feat(debugserver): attach lldb to a running process by pid (ios debug --pid)

[danielpaulus]

Problem

ios debug can only launch an app from a local .app path. Issue #387 asks for Xcode-style "attach to running process": connect lldb to a process that is already running on the device, addressed by its pid (ios debug --pid <pid>).

Design

The existing debug flow already does everything needed except the lldb command sequence: it connects to com.apple.debugserver via lockdown, proxies it on a random local port, and drives /usr/bin/lldb with a generated command script plus a python helper. Attach mode reuses that connection/proxy path unchanged and only swaps the tail of the lldb script:

• launch: target create "<app>" … connect … run
• attach: no target create (there is no local binary) … connect … process attach --pid <pid>

The python connect_command creates an empty target when none is selected (attach mode), so ConnectRemote has a target to work with; lldb's Target::Attach then reuses the already-connected remote process, which is the standard flow for attaching through a gdb-remote stub. App install lookup, bundle-id resolution and Info.plist parsing are skipped entirely for attach.

Implementation

• ios/debugserver/debugserver.go
  • renderLLDBScripts(cfg) — pure function rendering both the lldb command script and the python helper from a lldbScriptConfig (launch fields or pid, plus proxy port); startLLDB now just renders, writes the files, and executes lldb.
  • AttachByPid(device, pid) — new public entry point; validates pid > 0, logs with module/udid/pid attrs via golog.
  • runSession(device, cfg) — the connection/proxy/lldb plumbing factored out of Start; Start (launch) and AttachByPid both call it.
• ios/debugserver/format.go — LLDB_FMT gains template conditionals for the target create line and run vs process attach --pid; PY_FMT connect_command creates an empty target if none exists (no-op in launch mode).
• main.go / cmd_device_debug.go — usage is now ios debug [options] [--stop-at-entry] (<app_path> | --pid=<processID>); docopt's alternation enforces exactly one of the two. --stop-at-entry with --pid is rejected with a clear error (attaching always stops the process).

Options considered

1. --pid=<processID> only (chosen). Pid is unambiguous, maps 1:1 to lldb's process attach --pid, matches what the issue asks for, and users can resolve names to pids with ios ps. It also mirrors the existing --pid option on kill/pcap/ostrace.
2. Additionally --attach-name=<name> (deferred). lldb supports process attach --name (vAttachName/vAttachWait on the stub), which would also enable "wait for launch" semantics. Deferred because name matching on the remote stub is less predictable (partial/duplicate names), it doubles the surface to e2e-verify, and it composes cleanly on top of this PR later without touching the design.
3. New ios attach subcommand. Rejected: attach is a mode of the same debugserver session, not a different feature; keeping it under ios debug matches Xcode's "Debug > Attach to Process" mental model and avoids duplicated docs/plumbing.

Test plan

• New unit tests in ios/debugserver/debugserver_test.go for the pure renderLLDBScripts:
  • launch mode: target create, device_app, connect_url port, final run, no process attach, no stop-at-entry flag in the python helper
  • launch with --stop-at-entry: python helper contains SetLaunchFlags(lldb.eLaunchFlagStopAtEntry)
  • attach mode: final command process attach --pid 1337, no target create, no run, python helper creates the empty target
• go build ./... and go test ./... pass; gofmt -l clean on changed files.
• CLI parsing smoke-tested locally: ios debug --pid=1337 parses and proceeds to device resolution; ios debug alone and ios debug --pid=1 app.app are rejected by docopt.
• Note: attaching needs a real device with a running process; e2e verification of attach on the device farm is a follow-up (ios debug currently has no e2e coverage either).

Fixes #387

🤖 Generated with Claude Code

https://claude.ai/code/session_01J8eMENxJ1nec9CeHp4tjWk

[danielpaulus]

/test-devices

[github-actions]

🧪 Running real-device tests on PR #801 — run.

[github-actions]

❌ Real-device tests failed — see run.

[danielpaulus]

Adversarial review — attach-by-pid

Reviewed the lldb attach semantics, docopt changes, and refactor fidelity. One real defect found and fixed; the rest of the PR is sound.

Fixed (pushed to this branch, f889cfb)

• Per-command help was stale. ios help debug / ios debug --help render from internal/clihelp/help.yaml, which is separate from the top-level docopt usage in main.go. The PR updated main.go to (<app_path> | --pid=<processID>) but left the clihelp debug entry as <app_path> only, so the new attach-by-pid mode was undocumented in command help (and no consistency test guards this, so CI wouldn't catch it). Synced the usage line and summary.

Verified correct (no change needed)

• lldb remote-attach flow. platform select remote-ios → (no target create) → connect → the new python guard if not GetSelectedTarget().IsValid(): CreateTarget('') → ConnectRemote → process attach --pid <n>. This is the standard debugserver attach sequence; the empty target is the right way to give ConnectRemote something to bind to. platform select remote-ios is kept and is sufficient.
• docopt. The alternation is required, so ios debug with no args prints usage (no panic). --pid=<processID> matches the existing kill/pcap/ostrace convention. In launch mode --pid is absent and Args.Int("--pid") returns (0, err) — the error is intentionally ignored and pid==0 falls through to the launch path; no panic.
• --stop-at-entry + --pid is rejected with a clear message (attach always stops the process).
• Refactor fidelity. The launch-mode lldb command script renders byte-identical to the pre-refactor format string ({{if .AppPath}}…{{end}} and {{if .Pid}}…{{else}}run{{end}} collapse to the original text). The python helper gains an inert empty-target guard that never executes in launch mode (the target is already valid) — behavior-preserving.
• Tests in debugserver_test.go cover launch, stop-at-entry, and attach rendering with good negative assertions.

Status

go build ./..., go test ./... green; gofmt -l clean. Not merging.