xcodebug 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,541 @@
1
- # Temporary Holding Version
1
+ # xcodebug
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Drive a **physical iOS device** from the agent session: build/install/launch with
4
+ Xcode, then read the app's console output (stdout/stderr + os_log) inside the
5
+ session.
6
+
7
+ No jailbreak, no LLDB attach, no paid account. It uses the tooling Xcode itself
8
+ ships with:
9
+
10
+ | What Xcode's console shows | How xcodebug gets it |
11
+ |---|---|
12
+ | `print` / `NSLog` / `os_log` | `xcrun devicectl device process launch --console` |
13
+ | os_log in the console | `OS_ACTIVITY_DT_MODE=YES` on that launch |
14
+ | an app you don't want to restart | `idevicesyslog -p <ProcessName>` (optional) |
15
+ | build + install | `xcodebuild` + `xcrun devicectl device install app` |
16
+
17
+ `devicectl --console` needs the app to be launched *by* it, so `launch` restarts
18
+ the app. `syslog` attaches to an already-running process instead.
19
+
20
+ ## Install
21
+
22
+ The extension is a directory with `index.ts` plus a `pi` manifest; either install
23
+ it as a package or drop the directory in place.
24
+
25
+ ```bash
26
+ # from npm (writes to ~/.pi/agent/settings.json)
27
+ pi install npm:xcodebug
28
+ pi install npm:xcodebug -l # project scope: .pi/settings.json
29
+
30
+ # pin a version, or install from a checkout
31
+ pi install npm:xcodebug@1.0.0
32
+ pi install /path/to/xcodebug
33
+ ```
34
+
35
+ **Upgrading from `xcodebug-extension`:** the package was renamed, so both names
36
+ register the same `xcodebug` tool and the loader refuses to start the second one
37
+ (`Tool "xcodebug" conflicts with ...`). Remove the old package first:
38
+
39
+ ```bash
40
+ pi remove npm:xcodebug-extension
41
+ pi install npm:xcodebug
42
+ ```
43
+
44
+ Or copy the directory into the global extensions dir, which the engine discovers
45
+ on startup:
46
+
47
+ ```text
48
+ <agentDir>/extensions/xcodebug/index.ts
49
+ ```
50
+
51
+ `<agentDir>` is whatever the host resolves (`~/.omo/agent` under OmO,
52
+ `~/.omp/agent` under omp, `~/.senpi/agent` under senpi, `~/.pi/agent` under
53
+ upstream pi): xcodebug is a generic pi extension and names no brand.
54
+
55
+ **Restart the session** afterwards. Neither pi nor omp reloads an already-loaded
56
+ extension: pi has no reload command at all, and omp's `/reload-plugins` only
57
+ clears plugin discovery, not the imported module graph. Editing `index.ts` while
58
+ a session is running therefore has no effect on that session.
59
+
60
+ ## Claude Code and Codex (MCP)
61
+
62
+ Neither client has an in-process extension API - tools reach them as MCP servers.
63
+ `mcp/server.ts` is that adapter: it loads `index.ts` with a stub host and serves
64
+ the tool it registers, so it exposes the same actions and arguments as the pi
65
+ extension rather than a parallel implementation.
66
+
67
+ ### Set up (once per machine)
68
+
69
+ ```bash
70
+ npm i -g xcodebug # >= 1.1.0, the first release that ships mcp/
71
+ codex mcp add xcodebug -- node "$(npm root -g)/xcodebug/mcp/server.ts"
72
+ claude mcp add xcodebug -- node "$(npm root -g)/xcodebug/mcp/server.ts"
73
+ ```
74
+
75
+ Working from a checkout instead? Point both at `mcp/server.ts` in the repo:
76
+
77
+ ```bash
78
+ codex mcp add xcodebug -- node /path/to/xcodebug/mcp/server.ts
79
+ claude mcp add xcodebug -- node /path/to/xcodebug/mcp/server.ts
80
+ ```
81
+
82
+ `node` >= 22.18 is enough: the imports carry explicit `.ts` extensions and the
83
+ package declares `"type": "module"`, so there is no build step and no Bun.
84
+
85
+ Check that the client picked it up:
86
+
87
+ ```bash
88
+ codex mcp list # xcodebug node …
89
+ claude mcp list # xcodebug: … ✔ Connected
90
+ ```
91
+
92
+ ### Use
93
+
94
+ Start the client **in the project directory**. The server inherits its cwd, and
95
+ that directory is the project root every action resolves against.
96
+
97
+ ```bash
98
+ cd ~/myapp # holds the .xcworkspace or .xcodeproj
99
+ codex # or: claude
100
+ ```
101
+
102
+ Then ask for the outcome; the model calls the tool:
103
+
104
+ ```text
105
+ Build and launch on my device, then show me the console.
106
+ ```
107
+
108
+ The actions that matter in this mode:
109
+
110
+ ```text
111
+ action=launch device=<udid> build + install + launch; the capture starts
112
+ action=logs since=0 incremental read - the cursor is per capture
113
+ action=logs grep=Weather narrow to one subsystem
114
+ action=wait match="..." block until a line appears
115
+ action=status captures, line counts, log paths
116
+ action=stop close every running capture
117
+ ```
118
+
119
+ ### What differs from pi
120
+
121
+ | | pi / omp / omo | Claude Code / Codex |
122
+ |---|---|---|
123
+ | how the tool is exposed | registered in-process | MCP server process |
124
+ | status line, widget | yes | none |
125
+ | `push` | mirrors new lines into the session | refused |
126
+ | capture state | in the session | in the server process |
127
+ | lifetime | the session | the client process |
128
+
129
+ - **`push` is refused on purpose.** MCP has no channel that injects content into a
130
+ running turn, and neither client renders `notifications/message` - measured on
131
+ both, where the model reported that nothing arrived on its own between two tool
132
+ calls. Read with `action=logs` or `action=wait`; both are pull-based, and the
133
+ cursor means you only pay for new lines.
134
+ - **Captures end with the client.** The server is a child of Codex/Claude, so
135
+ quitting the client stops the bridges. Relaunch next session.
136
+
137
+ Logs land in `~/.xcodebug/logs/xcodebug/`, or under `XCODEBUG_AGENT_DIR` when set.
138
+ Every response also reports the exact path, so the model can read the file once a
139
+ run is over.
140
+
141
+ ## Requirements
142
+
143
+ | Need | Why |
144
+ |---|---|
145
+ | macOS + Xcode (command-line tools) | `xcodebuild`, `xcrun devicectl` |
146
+ | `idevicesyslog` from libimobiledevice | optional; only `syslog` and the dual-channel safety net |
147
+ | git | change detection; without a repo every run rebuilds |
148
+ | CocoaPods | optional; only projects with a `Podfile` |
149
+ | Node >= 22.18 | only for the MCP clients (Claude Code, Codex); pi runs the extension itself |
150
+
151
+ `xcodebug action=doctor` reports which of these are present.
152
+
153
+ ## Imports
154
+
155
+ The only engine import is a type import, erased at compile time:
156
+
157
+ ```typescript
158
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
159
+ ```
160
+
161
+ That is the official specifier; loaders also alias `@code-yeongyu/senpi` and the
162
+ `@mariozechner/*` names to the same module. `typebox` is the other dependency,
163
+ for tool parameter schemas. Everything else is `node:` built-ins.
164
+
165
+ The extension is written against the **published** types, and that is enforced:
166
+ it typechecks against `@earendil-works/pi-coding-agent@1.4.0`, whose
167
+ `ExtensionContext` carries only `cwd` and `sessionManager` and whose
168
+ `ExtensionAPI` has no `cwd`. Hosts that add more - `ctx.agentDir`, `pi.cwd`,
169
+ `argumentHint` on a command - are supported without depending on them:
170
+
171
+ ```typescript
172
+ if ("agentDir" in ctx) { /* host supplies it */ }
173
+ ```
174
+
175
+ So the same file runs unchanged on every distribution, and a host that omits
176
+ those fields loses nothing: the project root falls back to `ctx.cwd`, and the
177
+ agent directory to the session directory's parent (every brand stores sessions at
178
+ `<agentDir>/sessions/<encoded-cwd>`), then to a `*_CODING_AGENT_DIR` environment
179
+ override. If none of those exist the extension fails naming what was missing
180
+ rather than writing logs to a guessed path.
181
+
182
+ ## Configure (optional)
183
+
184
+ `.xcodebug.json` in the project root:
185
+
186
+ ```json
187
+ {
188
+ "workspace": "MyApp.xcworkspace",
189
+ "scheme": "MyApp",
190
+ "configuration": "Debug",
191
+ "bundleId": "com.example.myapp",
192
+ "device": "My-iPhone",
193
+ "args": [],
194
+ "environment": {}
195
+ }
196
+ ```
197
+
198
+ `device` may be a name, UDID, ECID or CoreDevice uuid. With one physical device
199
+ connected it can be omitted.
200
+
201
+ ## Change detection and pod install
202
+
203
+ Every `build` and `launch` first inspects the working tree with
204
+ `git status --porcelain -uall`:
205
+
206
+ 1. **Any build-relevant change** (sources, resources, Podfile, podspec, project
207
+ files) forces a rebuild + relaunch.
208
+ 2. **A new file inside a pod** forces `pod install --no-repo-update` first,
209
+ because the generated Pods project enumerates pod sources and will not
210
+ compile a file it has never seen. Pod membership comes from the repo's own
211
+ podspec `source_files` globs, so `Packages/FeatureX/Classes/**` maps to
212
+ `FeatureX`, etc.
213
+ 3. **`Podfile.lock` out of step with `Pods/Manifest.lock`** also forces
214
+ `pod install`. That mismatch fails every target's "[CP] Check Pods
215
+ Manifest.lock" phase with an error the user cannot act on from a build log.
216
+
217
+ `pod install` only ever runs in the directory that holds the container's own
218
+ `Podfile` (the workspace's parent). If there is none, the step is skipped and
219
+ the reason is reported - it never searches elsewhere, because that could
220
+ reinstall a different project's pods.
221
+ 4. **No change** since the last successful build in this session reuses that
222
+ build instead of rebuilding for minutes. Pass `force=true` to override.
223
+
224
+ Inspect the decision without building:
225
+
226
+ ```text
227
+ xcodebug action=changes
228
+ ```
229
+
230
+ ```text
231
+ 2 build-relevant change(s)
232
+ M Packages/FeatureX/Classes/Weather/AddCityController.swift
233
+ fingerprint: 963e92a4
234
+ rebuild needed: yes
235
+ pod install needed: no
236
+ ```
237
+
238
+ `pod install` runs once per change set (tracked by fingerprint), not on every
239
+ run. Set `installPods=false` to skip it deliberately.
240
+
241
+ ## One-shot: `/xcodebug <what to verify>`
242
+
243
+ ```text
244
+ /xcodebug 验证天气添加城市
245
+ ```
246
+
247
+ Detects the workspace from the current directory (walking up, so a nested cwd
248
+ works), rebuilds when the tree changed, installs, launches, and streams the
249
+ console into this session. The phrase is a goal for the model, not a log filter.
250
+
251
+ - **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
252
+ CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
253
+ - **The scheme** defaults to the container's own name (`MyApp.xcworkspace`
254
+ -> `MyApp`). That guess is checked once with `xcodebuild -list`; when it
255
+ does not exist, the scheme files are read for the one declaring
256
+ `BuildableName = "*.app"` (a workspace usually keeps its schemes in the
257
+ sibling `.xcodeproj`).
258
+ - **The outcome reaches the session**, including a failed build or install - not
259
+ just a UI toast.
260
+
261
+ A leading action word is still honoured: `/xcodebug logs`, `/xcodebug stop`.
262
+
263
+ `/xcodebug restart` is the mid-run answer to "I just changed the code": it
264
+ rebuilds, reinstalls, relaunches and reattaches by replaying the last launch in
265
+ this session, so the phrase, device and scheme do not have to be retyped. It
266
+ forces the rebuild even though nothing about the invocation changed - the edited
267
+ code is the whole point - and it retires the previous capture for that app
268
+ through the same path as `launch`. The app identity parameters it remembers -
269
+ goal, bundleId, processName, device, scheme/workspace/project, configuration,
270
+ derivedDataPath, args, environment, push, match, dualChannel - are each
271
+ overridden by an explicit one (`/xcodebug restart device=My-iPhone`), so an
272
+ override is never silently ignored. `installPods` and `timeoutSeconds` are
273
+ per-invocation and always pass through. It remembers one launch - the most
274
+ recent - so after launching a second app, `restart` targets that second app.
275
+ The shell line a launch carried with `command=` is remembered too, and `restart`
276
+ runs it again after the relaunch - that is what closes the edit → restart → test
277
+ loop. Pass a new `command="..."` to override it, or `command=""` to clear it so
278
+ the next restart only rebuilds and relaunches.
279
+
280
+ ## `command=`: run a shell line alongside a capture
281
+
282
+ `command=` is a general primitive, not a test-runner hook: **any** shell line,
283
+ run to completion after the app is up, with the capture recording the whole time.
284
+ When it exits, the capture is stopped and you get the exit code plus the
285
+ app-side log for exactly that window. xcodebug knows nothing about the command's
286
+ contents - it never parses it, never assumes a framework.
287
+
288
+ That makes it the way to *provoke* something on the device and watch what the app
289
+ does in response:
290
+
291
+ | You want to see... | `command=` runs |
292
+ |---|---|
293
+ | an automated case tapping through a flow | `cd /repo && npm run test:weather` |
294
+ | a backend event reaching the app | `curl -X POST .../push -d @event.json` |
295
+ | a file/dataset the app then consumes | `./scripts/import-fixtures.sh` |
296
+ | a CLI driving the phone (deep link, locale, permission) | `xcrun simctl ...` / `idevice* ...` |
297
+ | a codegen or asset step whose output the app reloads | `npm run codegen` |
298
+ | a benchmark, then the log of that run | `./bench.sh --iterations 100` |
299
+
300
+ The app must already be running for this to mean anything, so `command=` is a
301
+ **second phase appended to the main action** - `/xcodebug command="..."` on its
302
+ own still launches first. Use `action=await` when the app is already up.
303
+
304
+ ### Worked case: the automation stands in for the user
305
+
306
+ The most common use is replacing a human's taps. A capture alone only records
307
+ what the app does while **a person** drives the phone: slow to reproduce and
308
+ never quite identical twice.
309
+
310
+ ```text
311
+ /xcodebug 分析天气添加城市 command="cd /repo && npm run test:weather"
312
+ ```
313
+
314
+ | Without `command=` | With `command=` |
315
+ |---|---|
316
+ | a person opens the weather page and adds a city | the case taps the same path |
317
+ | the log records whatever they happened to do | the log records exactly that path, every run |
318
+ | the agent waits for a human, then reads | the agent reads as soon as the case exits |
319
+ | "it worked when I tried it" | exit code + app-side log for the same run |
320
+
321
+ So the shape of a verification run is: **goal** (what to prove) + **command**
322
+ (how to provoke it) + **capture** (what the app did). The exit code says whether
323
+ the UI reached the expected state; the log says what the app did to get there -
324
+ which is the part a test assertion cannot see.
325
+
326
+ ### The mechanics
327
+
328
+ That single line does the whole linkage run:
329
+
330
+ 1. build + install + launch the app, start the console capture;
331
+ 2. run the shell line to completion (blocking);
332
+ 3. stop the capture it was watching;
333
+ 4. report the exit code, the app-side cursor, and the log path - with the
334
+ phrase `分析天气添加城市` attached as the goal the analysis must answer.
335
+
336
+ `command=` is a **second phase appended to the main action**, never an action of
337
+ its own. That ordering is the point: a command is only meaningful when the app is
338
+ already built, launched and being captured, so `/xcodebug command="..."` on its
339
+ own still launches first.
340
+
341
+ The two-step form remains available when the app is already up:
342
+
343
+ ```text
344
+ /xcodebug launch scheme=MyApp
345
+ /xcodebug await command="cd /repo && npm run test:weather"
346
+ ```
347
+
348
+ ```text
349
+ # equivalent spellings
350
+ xcodebug action=launch command="cd /repo && npm run test:weather"
351
+ xcodebug action=await command="cd /repo && npm run test:weather"
352
+ /xcodebug await command="cd /repo && npm run test:weather" timeoutSeconds=900
353
+ ```
354
+
355
+ A bare `/xcodebug` (or `/xcodebug 分析xxx`) has **no deadline**: it launches,
356
+ streams, and waits for you. Nothing stops it except `stop`, a new launch of the
357
+ same app, or the app exiting.
358
+
359
+ `command` is an opaque **shell line** handed to `/bin/sh -lc`; xcodebug knows
360
+ nothing about any test framework. Two consequences worth knowing:
361
+
362
+ - **Quote the whole line.** `command="cd /repo && npm run test"`. Unquoted, the
363
+ slash command splits on whitespace before it reads the value and only `cd`
364
+ reaches the shell, so the run "succeeds" having run nothing - xcodebug now
365
+ refuses that shape outright rather than guess.
366
+ - **Write `cd /repo && npm run test`, never `cd /repo npm run test`.** `cd`
367
+ treats the trailing words as extra arguments and returns 0 without running
368
+ anything, so the run looks like a pass. This one is inside a correctly quoted
369
+ line, so xcodebug cannot detect it for you.
370
+ - **Let the repo pick its own config.** A repo with several test configs will
371
+ fail with "No tests found" (exit 1) when run against the wrong one, which reads
372
+ exactly like a failing test. An npm script
373
+ (`"test:weather": "myrunner test --config myrunner-weather.config.ts"`)
374
+ pins the right config once, where the repo already declares it.
375
+
376
+ What it reports: exit code, elapsed time, how many new lines the capture gained,
377
+ the log path, and the `action=logs` call (with the right `since`) that returns
378
+ the app side of that run. A non-zero exit is surfaced as an error, not as a
379
+ successful "run finished".
380
+
381
+ ### What the model does with it
382
+
383
+ The command's exit code answers "did the UI reach the expected state". The log
384
+ answers "what did the app actually do", which no assertion can see. The cursor in
385
+ the report is what makes the second half cheap:
386
+
387
+ ```text
388
+ awaited cd /repo && npm test · exit 0 · 125s
389
+ stopped console-mvq1bclw · 5568 new line(s) · <agentDir>/logs/xcodebug/console-...log
390
+ next: xcodebug action=logs captureId=console-mvq1bclw since=12428
391
+ ```
392
+
393
+ That `since=` starts exactly where the case began, so the next call returns only
394
+ this run's app-side lines, not the 12k from launch:
395
+
396
+ ```text
397
+ xcodebug action=logs captureId=console-mvq1bclw since=12428 grep=Weather
398
+ ```
399
+
400
+ ```text
401
+ 14572 MySDK: Net | WeatherService pushCities(payload) count=4
402
+ 14588 MySDK: Net | WeatherService pushCurrent(city="...") ok
403
+ ```
404
+
405
+ Which is how "the case tapped add-city" becomes "the app pushed four cities".
406
+ Two patterns that keep it small:
407
+
408
+ - `grep=` narrows to the subsystem under test (a class name, a log prefix).
409
+ - `wait match="..."` blocks until an expected line appears, for the case where
410
+ the assertion passes but the app's own path is what you need to see.
411
+
412
+ If the case fails, the same cursor still returns the app side, so the failure can
413
+ be read from both ends: the assertion says where the UI stopped, the log says why.
414
+
415
+ Boundaries that keep it out of every other workflow:
416
+
417
+ - `await` only stops **the capture it targets** (`captureId` > the active
418
+ capture). A second app under debug keeps streaming.
419
+ - It never terminates the app (`stop keepApp=true` semantics), so the screen
420
+ stays where the run left it.
421
+ - It writes no capture state, so a later `launch`/`stop`/`logs` is unaffected.
422
+ - No timer or silence heuristic is involved: the process exiting is the only
423
+ automatic finish. `timeoutSeconds` (default 1800) bounds the child process
424
+ only; on timeout the child is killed and the capture is still stopped, and
425
+ the result is reported as an error.
426
+ - With no capture running, `await` still runs the command and reports the exit
427
+ code instead of failing.
428
+
429
+ **Prerequisite when the command drives the UI:** the runner must not relaunch the
430
+ app. Many UI-test fixtures terminate and relaunch the app before every test
431
+ unless `autoAppLaunch: false` is set, which kills the very launch xcodebug is
432
+ capturing. Set it in the config the run uses. A command that does not touch the
433
+ app (a curl, a fixture import, a codegen step) has no such constraint.
434
+
435
+ ### Run semantics
436
+
437
+ Verification is a loop: run, read the log, conclude, stop, edit the code, run
438
+ again. Each `launch` or `syslog` retires the previous cycle's capture for that same
439
+ app **before** the new bridge starts, so the two never push the same app's lines
440
+ into one conversation; other apps keep streaming, so several apps can be
441
+ debugged in one session.
442
+
443
+ - **Stop once the log has answered the question.** Keeping a capture alive after
444
+ the conclusion only floods the session.
445
+ - **Do not stop while the user has not acted yet.** Silence there means nothing
446
+ has been tried, not that the run is over: say what to do on the phone and keep
447
+ listening.
448
+ - A capture ends on its own when the app process exits. A run whose app the user
449
+ deliberately closed is not reconnected.
450
+ - A dropped console bridge otherwise reconnects indefinitely. An inconclusive
451
+ probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
452
+ - `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
453
+ it and the exit hook reattaches. Reattachment has exactly one owner, so the
454
+ watchdog and the exit hook can never both assume the other is handling it.
455
+ - After 60s with no new lines the run says so once and keeps capturing.
456
+ - A footer line and a widget above the editor show the live state, e.g.
457
+ `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus the
458
+ last few log lines and how many channels are streaming.
459
+ - Pushed log batches are **hidden from the transcript** (`display: false`) but
460
+ still delivered to the model, which is the only consumer that needs every
461
+ line. The screen keeps one status line instead of a wall of log frames.
462
+ - `/xcodebug stop` (or `action=stop`) closes **every running capture** - the
463
+ console bridge and its syslog companion, plus any other app still streaming.
464
+ Pass `captureId=` to close one. `keepApp=false` also terminates the app.
465
+
466
+ ## Usage
467
+
468
+ ```text
469
+ xcodebug action=devices
470
+ xcodebug action=doctor
471
+ xcodebug action=changes
472
+ xcodebug action=changes force=true
473
+
474
+ # build + install + launch, then stream the console
475
+ xcodebug action=launch scheme=MyApp
476
+
477
+ # build only
478
+ xcodebug action=build scheme=MyApp
479
+
480
+ # install an already-built .app without rebuilding
481
+ xcodebug action=install appPath=/path/to/App.app
482
+
483
+ # already-running app, no restart
484
+ xcodebug action=syslog processName=MyApp
485
+
486
+ # incremental reads (cursor-based)
487
+ xcodebug action=logs limit=200
488
+ xcodebug action=logs grep=MySDK
489
+ xcodebug action=wait match="DataPacket" timeoutSeconds=30
490
+
491
+ xcodebug action=status
492
+ xcodebug action=stop keepApp=true
493
+ xcodebug action=terminate
494
+
495
+ # force a rebuild even when the tree is unchanged
496
+ xcodebug action=launch force=true
497
+ # skip the automatic pod install deliberately
498
+ xcodebug action=launch installPods=false
499
+
500
+ # edited the code mid-run: rebuild + relaunch the same app, same device, same goal
501
+ xcodebug action=restart
502
+
503
+ # run any shell line to completion, then stop the capture and hand back the log
504
+ xcodebug action=await command="cd /repo && npm run test:weather"
505
+ /xcodebug await command="cd /repo && npm run test:weather"
506
+ ```
507
+
508
+ ### Pushing logs into the conversation
509
+
510
+ `push` controls whether new lines are mirrored into the session:
511
+
512
+ - `context` (default) — new lines are queued for the next turn (does not start one).
513
+ - `off` — pull with `logs`/`wait` only.
514
+ - `wake` — new lines start a turn.
515
+
516
+ A device console is a firehose; the push carries at most 80 lines per tick and
517
+ reports how many older lines it dropped. Combine it with `match` to keep it
518
+ useful, e.g. `xcodebug action=launch match=MySDK push=wake`.
519
+
520
+ ### Files
521
+
522
+ Every capture also writes a full log to
523
+ `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`, so
524
+ nothing is lost when the in-memory ring buffer (20k lines) rolls over.
525
+
526
+ The app's bundle id is part of the name because several apps are debugged in
527
+ one session; the timestamp carries milliseconds so a relaunch of the same app
528
+ cannot reuse the previous run's file (files are opened in append mode, so a
529
+ collision would interleave two runs with no way to tell them apart).
530
+
531
+ A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
532
+ from a previous binary cannot be mistaken for the run that is starting.
533
+
534
+ ### Device archiving is off
535
+
536
+ Pulling the device unified log on a timer is disabled. Measured on an 18-minute
537
+ run it cost ~208 MB per snapshot (each covers the whole previous hour) with no
538
+ reader, and it cannot serve its stated purpose: `log show --archive ... | grep
539
+ MySDK` returns nothing, because `NSLog`/`print` never enters the unified log.
540
+ Only framework records (RunningBoard, CFNetwork, WebKit) come back, so a dropped
541
+ console bridge is recovered by reconnecting, not by replaying an archive.