@awebai/oats 0.61.0 → 0.62.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.
Files changed (85) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +26 -11
  3. package/docs/capabilities.md +1 -1
  4. package/docs/execution-targets.md +49 -3
  5. package/docs/implementation.md +2 -1
  6. package/docs/named-test-runs.md +382 -0
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-notes/v0.62.0.md +223 -0
  10. package/docs/upgrading.md +133 -11
  11. package/docs/workspaces.md +1 -1
  12. package/lib/core.mjs +2 -2
  13. package/lib/doctor-capture.mjs +35 -0
  14. package/lib/session-viewer.mjs +86 -7
  15. package/package-catalog.json +1 -1
  16. package/package.json +1 -1
  17. package/packages/client/cli-locator.mjs +2 -2
  18. package/packages/record/README.md +87 -13
  19. package/packages/record/bin/capture-hook.mjs +8 -0
  20. package/packages/record/bin/capture.mjs +143 -124
  21. package/packages/record/bin/recall.mjs +8 -3
  22. package/packages/record/bin/setup.mjs +115 -225
  23. package/packages/record/bin/turn-record.mjs +2 -2
  24. package/packages/record/docs/capture-service.md +1443 -28
  25. package/packages/record/docs/capture-status.schema.json +429 -12
  26. package/packages/record/lib/capture-admission.mjs +82 -0
  27. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  28. package/packages/record/lib/capture-aw.mjs +31 -12
  29. package/packages/record/lib/capture-budget.mjs +31 -0
  30. package/packages/record/lib/capture-cc.mjs +39 -6
  31. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  32. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  33. package/packages/record/lib/capture-command-operation.mjs +37 -0
  34. package/packages/record/lib/capture-command-output.mjs +61 -0
  35. package/packages/record/lib/capture-command-worker.mjs +6 -0
  36. package/packages/record/lib/capture-command.mjs +48 -0
  37. package/packages/record/lib/capture-completion.mjs +152 -0
  38. package/packages/record/lib/capture-context.mjs +50 -0
  39. package/packages/record/lib/capture-default-roots.mjs +30 -0
  40. package/packages/record/lib/capture-discovery.mjs +114 -0
  41. package/packages/record/lib/capture-failures.mjs +45 -0
  42. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  43. package/packages/record/lib/capture-health-installation.mjs +117 -0
  44. package/packages/record/lib/capture-health.mjs +116 -0
  45. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  46. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  47. package/packages/record/lib/capture-hook.mjs +26 -0
  48. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  49. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  50. package/packages/record/lib/capture-index-reset.mjs +109 -0
  51. package/packages/record/lib/capture-index-work.mjs +77 -0
  52. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  53. package/packages/record/lib/capture-issues.mjs +15 -2
  54. package/packages/record/lib/capture-lock.mjs +102 -16
  55. package/packages/record/lib/capture-native-unit.mjs +322 -0
  56. package/packages/record/lib/capture-pass.mjs +102 -0
  57. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  58. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  59. package/packages/record/lib/capture-retry.mjs +102 -0
  60. package/packages/record/lib/capture-run.mjs +125 -0
  61. package/packages/record/lib/capture-scratch.mjs +12 -3
  62. package/packages/record/lib/capture-service-definition.mjs +104 -0
  63. package/packages/record/lib/capture-service-install.mjs +362 -0
  64. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  65. package/packages/record/lib/capture-service-runner.mjs +18 -0
  66. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  67. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  68. package/packages/record/lib/capture-source-queue.mjs +199 -0
  69. package/packages/record/lib/capture-source-work.mjs +85 -0
  70. package/packages/record/lib/capture-state.mjs +16 -71
  71. package/packages/record/lib/capture-status.mjs +171 -0
  72. package/packages/record/lib/capture-supervisor.mjs +117 -0
  73. package/packages/record/lib/capture-watch.mjs +32 -0
  74. package/packages/record/lib/capture-work-session.mjs +238 -0
  75. package/packages/record/lib/capture-worker.mjs +58 -0
  76. package/packages/record/lib/derived-state.mjs +28 -15
  77. package/packages/record/lib/file-lines.mjs +22 -6
  78. package/packages/record/lib/formats.mjs +4 -3
  79. package/packages/record/lib/index-capture.mjs +97 -0
  80. package/packages/record/lib/index-db.mjs +3 -17
  81. package/packages/record/lib/index-reset.mjs +19 -0
  82. package/packages/record/lib/store.mjs +36 -11
  83. package/packages/record/lib/transcript-prefix.mjs +125 -0
  84. package/skills/oats-getting-started/SKILL.md +1 -1
  85. package/docs/macos-test-runs.md +0 -246
@@ -1,8 +1,20 @@
1
1
  # Capture algorithms and recovery
2
2
 
3
3
  The record package owns source cursors, journal validation, indexing and capture
4
- status. This version changes those algorithms; it does not install a bounded
5
- runner or change service scheduling, hooks, root registration or doctor.
4
+ status. Ordinary/source-selected capture and explicit retry use the fixed
5
+ supervised worker. Explicit hooks launch a detached supervisor. Setup migrates
6
+ supported service definitions through the preflight/apply gate described below;
7
+ the package also owns offline installation/receipt/issue diagnosis. Root
8
+ registration and real-manager qualification remain separate. Deployment doctor
9
+ delegates to the package diagnosis through the bounded command boundary below.
10
+
11
+ The integration described below is service A, which ships in the next release
12
+ after 0.61.0; source and fake manager fixtures do not establish real manager
13
+ qualification. OATS 0.56.0 through 0.61.0 shipped without the bounded periodic
14
+ service. See
15
+ [capture service release order](../../../docs/upgrading.md#capture-service-release-order)
16
+ for the distinction between upgrading those releases and a future setup
17
+ conversion after installing a release that ships service A.
6
18
 
7
19
  ## Input contract
8
20
 
@@ -39,6 +51,15 @@ Detected changes have two outcomes:
39
51
  from the physical last transcript turn, so appending a revised earlier line
40
52
  would make those writers duplicate the remaining history.
41
53
 
54
+ Protected command prefix-conflict diagnostics name the refused input, conflicting stream
55
+ and native line/source byte position. They say "establishing source path
56
+ unavailable": the journal records native session and line, not that path.
57
+ Current discovery and derived cursors cannot supply missing provenance, and a
58
+ prefix mismatch does not itself prove that a second source exists. Native stream
59
+ identity and traversal precedence remain unchanged.
60
+ Ordinary supervised passes report confirmed appended counts and the worker
61
+ outcome; `capture --health` supplies active set-aside locations and remedies.
62
+
42
63
  ## Operator recovery
43
64
 
44
65
  `turn-record capture --reset-cursors [--source aw|cc|pi|codex]` uses the selected
@@ -60,10 +81,50 @@ For a conflicting native prefix, either:
60
81
  input from active set-aside entries. Removing the ignore rule later does not
61
82
  authorize the conflict.
62
83
 
63
- Retry takes the same nonblocking capture lock, marks all current entries eligible
64
- for revalidation, then performs one ordinary reconciliation while retaining the
65
- lock. An interruption after marking leaves the warning active. It is not yet a
66
- policy-bounded pass. Resetting cursors does not replace retry or clear a refusal.
84
+ **Oversized records.** The 8 MiB raw-record limit applies to capture beyond
85
+ the captured prefix. The supervised worker never allocates, captures or
86
+ modifies a new raw source record larger than 8 MiB. It appends and checkpoints
87
+ the complete records before that record through the normal unit commit, then
88
+ sets the input aside (`record-too-large`) at the oversized record's start
89
+ offset. Records after it stay pending until the operator edits the source or
90
+ adds the whole input to `<root>/ignore`, which, as above, also stops later
91
+ turns from that session. `--retry-set-aside` revalidates the input, appending
92
+ no captured record twice, but the oversized record still blocks it.
93
+
94
+ Records already captured (by a release without this limit) are not refused.
95
+ Staged recovery (after cache loss, a reset, a retry or a rewritten source)
96
+ copies the source in chunks without joining lines, and proves the captured
97
+ prefix by a SHA-256 digest of each staged line streamed over those chunks,
98
+ compared with the journal's line; a captured line of any size is compared
99
+ without being held whole, and a changed byte refuses the prefix as usual. The
100
+ journal side of that proof, like exact-version journal validation, still reads
101
+ each journal record whole: the largest captured journal record bounds recovery
102
+ memory, which the large-frame qualification measures in this recovery shape.
103
+ An AW comm log has no prefix proof: when its cursor stops qualifying (a new
104
+ journal epoch, a reset, a retry, or an older release's cursor), the rescan keeps
105
+ the cursor's byte offset as a captured frontier, provided the cursor names the
106
+ same file and its boundary witness still matches. Records before that frontier
107
+ are read without the limit, journal-id dedupe keeps them from being appended
108
+ twice, and the limit applies at and beyond it. While a rescan is below its
109
+ frontier, the cursor it writes carries the frontier and that offset's own
110
+ witness, so a second invalidation between the rescan's units keeps the larger
111
+ of the two proofs. A replaced or rewritten log has no frontier. That is the
112
+ price of never refusing a captured record: an already-captured AW record too
113
+ large for the worker's 256 MiB heap fails the worker on every rescan
114
+ (`capture-pass-failed`), and that stream does not advance.
115
+ One native case still captures nothing before an oversized record: an
116
+ oversized line before the session's first timestamped line, which the
117
+ unstamped lines before it need.
118
+ `--health` gives each listed `record-too-large` entry this remedy (edit the
119
+ source, then retry; or ignore the whole input, discarding it whole), never the
120
+ prefix-restoration remedy above.
121
+
122
+ Retry takes the same nonblocking capture lock, prepares current entries for
123
+ revalidation in durable bounded pages, then performs supervised reconciliation
124
+ while retaining the lock across replacement workers. An interruption after
125
+ marking leaves the warning active. The run-bound preparation cursor prevents
126
+ repeating committed retry generations. Resetting cursors does not replace retry
127
+ or clear a refusal. Public synchronous retry/reset APIs keep their contracts.
67
128
 
68
129
  `capture --status` keeps its existing store summary. `capture --health [--json]`
69
130
  reads current active set-aside rows from `index/capture.db`, without capturing,
@@ -74,15 +135,200 @@ or acquire an implicit root capture lock. Health gets historical run fields from
74
135
  the snapshot and never advances them from current issues. A database with no
75
136
  snapshot still exposes its active issues.
76
137
 
138
+ A supervised pass that finds the snapshot unreadable, malformed or future-dated
139
+ treats it as absent: under the root lock and before any worker, it moves the
140
+ file aside, never overwriting it, to `capture-status.json.invalid-<UTC stamp>`
141
+ (the root directory synced after the rename). A foreground, setup, watch or
142
+ service pass names that path on stderr; a hook pass, whose output is detached,
143
+ leaves only the moved-aside file. A system error reading the snapshot
144
+ (permission, I/O) fails the pass and leaves the file in place.
145
+ The pass then publishes a new snapshot with no history: no success is carried
146
+ over or invented. One moved-aside copy is kept; a newer one replaces it. An
147
+ older moved-aside copy that is a directory is not removed: each later
148
+ move-aside reports it, and an operator removes it. A move that fails leaves the
149
+ file in place and fails the pass.
150
+
151
+ ### Offline installation and run diagnosis
152
+
153
+ The package owns `captureHealth` and `turn-record capture --health [--json]`.
154
+ Its existing `schemaVersion: 1` health envelope remains separate from the
155
+ [status file schema](capture-status.schema.json): `rows` contains `{code,message}`,
156
+ `lastRun`/`lastSuccess`/`lastFailure` retain historical receipt values, and
157
+ `backlog` is the current issue projection. A warning diagnosis exits zero;
158
+ an installation/issue reader failure exits nonzero, without an empty successful
159
+ projection. No store is constructed on the health CLI branch.
160
+
161
+ Capture CLI terminal branches return from a single command dispatch and retain
162
+ their exit code while Node drains stdout and stderr naturally. Health cannot
163
+ fall through into capture, including on reader failure. The same boundary
164
+ applies to usage/help, recovery, hook launch reporting, explicit-file receipts,
165
+ install hints, status and ordinary errors; exact-home receipts already finish
166
+ naturally. It adds no stream closure or timed delay. Privacy failures print once
167
+ and stop dispatch before admission; a later watch privacy failure closes future
168
+ watch scheduling. Lock cleanup and admitted-child ownership remain with their
169
+ existing owners; hook launch still unrefs its detached child, and foreground
170
+ watch retains its signal lifecycle. Output delivery is distinct from diagnosis
171
+ and durably confirmed processing counts.
172
+
173
+ Installation evidence means service definitions, hooks or setup's pending marker, any of:
174
+
175
+ - On macOS, `~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` parses as
176
+ a supported owned periodic or legacy definition. On Linux, the candidates
177
+ are `~/.config/systemd/user/turn-record-capture.service` and
178
+ `turn-record-capture.timer`. Health shares setup's strict template/argv
179
+ ownership reader; a basename, marker or mention alone is insufficient.
180
+ - A `settings.json` in a top-level `~/.claude*` directory or directory symlink
181
+ has a recognized command in a Stop or SessionEnd hook group. Health shares
182
+ setup's unchanged tokenizer: script in the second word ending in
183
+ `/capture-hook.mjs` (this release's hook entry) or `/capture.mjs` (earlier
184
+ releases' forms), whole `--owner` and `--quiet` words, supported plain/single
185
+ quoted words, and no shell expansion, operator or second command.
186
+ - Setup's pending-activation marker, `capture-service-pending.json`, is in the
187
+ selected root. Only setup writes it, so a setup that failed after writing it
188
+ is diagnosed (the marker's row) even with no definition or hook.
189
+
190
+ A record root alone is not an installation: one `oats recall` or one manual
191
+ capture creates it (with `index/`), and such a host has never set capture up.
192
+ The selected root (`--root`, then `TURN_RECORD_ROOT`, then `~/.turn-record`)
193
+ still has to be a directory when it exists. Readable foreign service files alone do not establish installation. No evidence
194
+ means `ok`, no warnings and no root creation. That includes a host that runs
195
+ capture by other means, or was set up with `--no-hooks --no-service`: health
196
+ reads `ok` and withholds its history and backlog, even when a status file or
197
+ set-aside inputs exist. Unreadable candidates, dangling
198
+ links, malformed hook settings, observed changes or exceeded reader limits are
199
+ unknown and fail diagnosis, even if another candidate establishes installation.
200
+ Only named files and the top level of the caller home are inspected; source
201
+ roots, journal content, network and managers are never visited. Definition bytes
202
+ show installation evidence, **not** registered/enabled scheduling. Even an `ok`
203
+ receipt diagnosis does not certify a manager schedule or a permanent service PID.
204
+
205
+ Installation reads accept regular files up to 1 MiB each, with 16 MiB total,
206
+ 64 hook candidates, 4,096 home entries and 256 path components. These are private
207
+ fail-closed reader guards, not capture policy or truncation-based absence proof.
208
+ The reader uses a 15-second cooperative monotonic deadline between operations;
209
+ the isolated issue reader retains its hard 10-second child deadline. Synchronous
210
+ filesystem calls still depend on the host filesystem returning. Deployment
211
+ doctor supplies the separate finite command timeout described below; it does
212
+ not turn the synchronous library's cooperative deadline into a hard one.
213
+
214
+ Installed but absent status produces `capture-status-missing` with a setup
215
+ remedy; malformed, unsupported, unreadable or future-dated status produces
216
+ `capture-status-invalid` until the next supervised pass moves it aside and
217
+ writes a new status, as the setup remedy's pass does. Valid older nullable
218
+ receipts remain valid absence of run evidence. `capture-success-stale` means no recorded success or one **older
219
+ than** 3,600 seconds, not exactly that age. It names the last success and committed
220
+ progress, with an asleep/off-host caveat. Recent progress is not full success.
221
+ A failure newer than success and current unresolved stream failures produce
222
+ `capture-pass-failed` independently of current set-asides. An unfinished run
223
+ beyond its recorded deadline also warns, without inventing its termination cause.
224
+ Before that deadline, death evidence requires an unchanged local lock registration
225
+ whose worker PID matches the receipt and whose acquisition predates the run,
226
+ with both supervisor and worker positively dead. Missing/off-host/hostless,
227
+ changed or uncertain registration and live/reused PIDs supply no death proof.
228
+ The receipt is reread before accepting that observation; health never repairs,
229
+ reclaims, signals termination, writes counters or invents a finished receipt.
230
+ Owned legacy watcher definitions additionally produce `capture-setup-required`,
231
+ as does an owned capture hook whose entry is not this release's
232
+ `bin/capture-hook.mjs` (the `capture.mjs` forms earlier releases' setup wrote),
233
+ hooks-only installations included; the row names the settings files.
234
+ Until setup converts it, the hook line from before this release,
235
+ `<node> <package>/bin/capture.mjs --owner <owner> --quiet` run asynchronously
236
+ with a 120-second timeout, still works against this release: it is one
237
+ ordinary quiet foreground pass under the root lock, attributed `manual`, up to
238
+ its 300-second deadline. A harness that stops it at 120 seconds with SIGTERM or
239
+ SIGINT makes the supervisor kill its worker, end the pass as interrupted and
240
+ release the lock; with SIGKILL the supervisor dies holding the lock, which the
241
+ next pass reclaims as a dead owner. Either way the next pass records the
242
+ interruption and continues from the durable checkpoints.
243
+ Setup's pending-activation marker (`<root>/capture-service-pending.json`, see
244
+ [setup service migration](#setup-service-migration)) produces
245
+ `capture-service-pending` from file evidence only: beside setup's own marked
246
+ definitions it says the periodic schedule's activation was not verified (hooks
247
+ may be installed, the schedule is not confirmed), and with no such definition
248
+ it names the marker as stale. Both say "not verified", never "not running": a
249
+ crash after a verified activation can leave the marker until the next setup
250
+ clears it. The remedy is a setup rerun; health never removes the marker. It is
251
+ a warning and hides no other row.
252
+ Standalone remedies name `turn-record`; the private doctor entry, and
253
+ `capture --health` when the kernel runs it (`oats capture --health`) or a node
254
+ was handed in (`OATS_NODE_BIN`, as for setup), select `oats` when constructing
255
+ authored remedy literals, before interpolating paths/errors or receipt data. It never replaces substrings in completed messages. All diagnosis
256
+ is local observed evidence, not full service qualification.
257
+
258
+ ### Kernel doctor delegation
259
+
260
+ Deployment `oats doctor` (text or JSON) starts exactly one fixed package health
261
+ entry with `process.execPath`. `--soul` stays composition-only and starts none.
262
+ The kernel maps validated package `{code,message}` rows into its existing
263
+ `warnings` list; it does not read status, open the database, probe managers or
264
+ reimplement installation/freshness/issue rules. The package validates its
265
+ existing `schemaVersion: 1` envelope and reuses receipt/backlog validation.
266
+ Nullable historical values remain absence of evidence. No doctor schema field
267
+ or public capture option is added.
268
+
269
+ The child keeps the caller cwd and HOME selection; `TURN_RECORD_ROOT` selects
270
+ the root, otherwise `~/.turn-record` applies. A relative root is relative to the
271
+ calling process cwd, not doctor's deployment positional argument. Only the
272
+ reader's home/temp/cache/root environment and an explicit experimental SQLite
273
+ Node flag are forwarded; no inherited Node options, worker/executable override
274
+ or shell dispatch. The private entry constructs no store and exits naturally,
275
+ so queued JSON output can drain.
276
+
277
+ Transport uses a 20-second command timeout, SIGKILL on timeout/overflow and a
278
+ 1 MiB output cap. These are private fail-closed guards, not a response-time
279
+ measurement or public tuning policy. The synchronous child transport waits for
280
+ its direct child to terminate. The package's isolated SQLite reader retains its
281
+ own 10-second timeout; if the outer reader is killed while that child is active,
282
+ its existing finite lifetime still applies. OS scheduling/filesystem response
283
+ and process termination remain host dependencies; no real-manager or storage
284
+ qualification follows from these source guards.
285
+
286
+ Timeout, launch/transport/reader failure, excessive output or invalid JSON/envelope
287
+ produces `capture-health-unavailable`, never an empty successful diagnosis or
288
+ rows reconstructed from partial output. Doctor retains its warning exit/output
289
+ contract; standalone package reader failures remain nonzero. Valid package
290
+ warnings are forwarded as diagnosis, not command failure. Text output applies
291
+ the kernel's terminal escaping; JSON retains literal values. Even no warnings
292
+ does not establish enabled/registered scheduling or a permanent service PID.
293
+
77
294
  Both command snapshots and health use the same transactional count/sample
78
- projection: at most 100 deterministic entries, total count and `truncated`.
79
- Text output has the same bound and explains both remedies. Absent state on a
295
+ projection. Source set-asides have `setAsideCount`, at most 100 deterministic
296
+ `setAside` entries and `truncated`. Operational failures independently have
297
+ `failedCount`, at most 100 `failed` entries and `failedTruncated`; neither category
298
+ borrows the other's sample allowance. Text output has the same bounds (at most
299
+ 200 combined entries) and explains both source remedies. Absent state on a
80
300
  never-installed root is not a warning or a reason to create files. A missing
81
301
  current database cannot erase a known nonempty command snapshot. Malformed or
82
302
  unreadable status is reported as `capture-status-invalid`; an unavailable current
83
303
  issue reader fails the command rather than returning successful stale/empty
84
304
  health JSON.
85
305
 
306
+ An operational failure entry contains `stream`, `offset`, `reason`, `attempts`
307
+ and `nextRetryAt`. The offset is the journal byte offset where the durably
308
+ admitted failed **single-stream unit starts**, never an exact inner-frame claim.
309
+ Text says "unit starting at byte X" and "failing frame unknown". An interrupted
310
+ multi-stream group supplies run failure evidence, not guessed rows for every
311
+ member. Private journal generation and admission evidence stay out of this
312
+ projection. Active entries produce `capture-pass-failed`, including during
313
+ backoff; they do not become source set-asides or advance a processing cursor.
314
+
315
+ The fixed retry schedule is 2, 4, 8, then 16 capture intervals (30, 60, 120, then
316
+ 240 minutes, capped there). Only an actual failed attempt increments `attempts`
317
+ and sets a new date. Skipping a deferred unit does neither. Time passing, source
318
+ growth, cursor reset and `--retry-set-aside` do not resolve these failures or
319
+ override their schedule. Resolution requires committed progress past the failed
320
+ unit or validated reconciliation that it no longer needs work. A cooperative
321
+ stop that makes durable progress is ordinary partial work, not automatically a
322
+ failure. Old snapshots without these fields contain no recorded operational
323
+ failure evidence; their absence does not establish a successful pass.
324
+
325
+ An interrupted multi-stream group defers its members without assigning each a
326
+ failure. On the next due attempt, its members enter the normal queue singly,
327
+ after healthy work. A member's own failed admission then supplies its failure
328
+ row; successful members advance. There is no in-pass group retry or diagnostic
329
+ execution mode. Unknown attribution remains a run failure, with deferred work
330
+ keeping the backlog pending even when no member has an attributable failure row.
331
+
86
332
  Reading an existing database requires Node's read-only SQLite support: 22.12+
87
333
  on the 22.x line (22.13+ avoids needing `--experimental-sqlite`), 23.2+ on 23.x,
88
334
  or a newer major. Normal capture retains its declared runtime floor. Missing
@@ -101,19 +347,65 @@ from releasing POSIX locks belonging to another SQLite connection in the caller.
101
347
  Command snapshots reuse their owned connection for the shared projection.
102
348
 
103
349
  The shared schema is [capture-status.schema.json](capture-status.schema.json).
104
- In this algorithm-only phase `policy`, `lastRun`, `lastSuccess`, `lastFailure`
105
- and `lastProgressAt` are null: evidence has not been supplied. They never mean
106
- that a bounded pass, service installation or successful sweep occurred. Health
107
- `status: "ok"` with empty rows means no reported set-aside fault, not service
108
- liveness. Service supervision will extend this same mechanism with actual policy
109
- and run evidence. Status replacement is atomic with private file permissions;
110
- persistence failure is an operation failure, not a fabricated success.
350
+ Existing algorithm-phase snapshots retain null `policy`, `lastRun`,
351
+ `lastSuccess`, `lastFailure` and `lastProgressAt`: evidence has not been supplied.
352
+ They never mean a completed pass or prove service activation. The same version-1
353
+ schema accepts the fixed service policy and evidenced worker run/history fields;
354
+ no second status file is used. Run identities name their trigger, worker PID and
355
+ start; a running receipt has no finish/reason. Complete, partial and failed
356
+ receipts have a finish, and failure has an explicit reason. Success/failure
357
+ summaries retain run identity, finish, per-run counts and sampled peak RSS;
358
+ failure additionally has a safe message and optional path/offset. Future-dated,
359
+ malformed or unsupported evidence is invalid, not a freshness conclusion.
360
+
361
+ Failed/interrupted-run counters report only durably confirmed unit-accounting
362
+ results, not an exhaustive count of physical journal writes during that run.
363
+ A zero `turnsAppended` does not prove that no append reached disk: journal fsync
364
+ can precede a lost derived checkpoint/accounting commit. The failure message
365
+ states this qualification. Confirmed healthy-unit counts within the same failed
366
+ pass remain visible, without erasing the earlier interruption. Recovery dedupes
367
+ against journal truth; it neither attributes later journal growth retroactively
368
+ to the failed run nor counts recovered existing turns as newly appended.
369
+ Explicit `--file`/`--home` receipt semantics are unchanged.
370
+
371
+ `capture-status.mjs` validates this shared format and atomically replaces a
372
+ private same-directory temporary file after its fsync. Publication failure is
373
+ reported; the prior snapshot is not replaced by an invented success. Exact
374
+ receipt commands refresh backlog while preserving all prior service history,
375
+ without claiming their own unbounded operation was a bounded pass. Snapshot
376
+ format support alone does not produce run evidence: the admitted command worker
377
+ must supply committed facts.
378
+
379
+ The private `CaptureRun` helper publishes a running identity before initializing
380
+ its derived counter row. Counter changes join the processing transaction after
381
+ journal fsync or index commit; rolled-back work cannot publish progress. A
382
+ continuing worker combines those committed counters with the published sampled
383
+ RSS peak. Sampling alone never advances `lastProgressAt`. An unfinished run
384
+ whose counter cache is lost retains interruption evidence rather than becoming
385
+ a successful empty pass. A finished file receipt takes precedence over a stale
386
+ running counter row, and finalization needs one atomic file publication, not a
387
+ second derived-state commit. Supervisor failure evidence is bound explicitly to
388
+ the current run ID, including a child lost before any running receipt exists.
389
+ It is distinct from failure of an older abandoned run: only failure in the
390
+ current pass prevents that pass from succeeding after healthy work. Partial
391
+ work preserves previous success and failure history. These are private
392
+ accounting mechanics, not evidence that command integration has run a pass.
393
+
394
+ Source-stage fixtures use the private retained recovery cleanup unit described
395
+ below. A due retry may need it even for a tiny source after an interrupted
396
+ append. Cleanup failure is a failure in the current pass and preserves
397
+ confirmed work; it cannot be ignored to make a later receipt successful.
398
+ The private worker dispatcher also routes these units; fixture coverage is
399
+ separate from ordinary-command and installed-service qualification.
111
400
 
112
401
  ## Resource model
113
402
 
114
403
  Source and journal reads use 64 KiB chunks. Batches commit at 2,000 records or
115
- 8 MiB of accumulated raw bytes; a single larger record is still supported and
116
- can exceed that batch target. SQLite connections use a 2 MiB page-cache target
404
+ 8 MiB of accumulated raw bytes. Admission flushes the prior batch before adding
405
+ a record that would exceed that byte target. Its checkpoint excludes the next
406
+ record's bytes and timestamp, even when the parser has already scanned that
407
+ line. A single larger record remains supported by public library calls and can
408
+ exceed the batch target. SQLite connections use a 2 MiB page-cache target
117
409
  and disk-backed temporary tables. Metadata query pages hold at most 128 rows;
118
410
  keyset queries support the declared Node 22.5 SQLite API without rescanning
119
411
  prior pages. Content-processing memory therefore depends on fixed buffers,
@@ -123,7 +415,14 @@ are algorithm settings, **not** a memory/deadline policy or record-size limit.
123
415
 
124
416
  Native root and path discovery retain in-memory metadata inventories, sorted by
125
417
  the existing per-directory `localeCompare` order with stable ties and depth-first
126
- traversal. Aweb account logs retain their code-unit sorted basename order. Their memory grows with file/profile counts, separately from streamed
418
+ traversal. Aweb account discovery retains code-unit sorted basenames. Public synchronous
419
+ `captureAwLogs` keeps sorted whole-file traversal. Cross-account append order
420
+ in `owner~aw` under the service is unspecified; per-account order is preserved.
421
+ Bounded command work may rotate between account files, serially under the same
422
+ stream lock. IDs, projection, dedupe and journal-generation checks are unchanged.
423
+ [`recall --thread --json`](../README.md) exposes the resulting durable sequence,
424
+ including mixed-account ID windows; it does not regroup or sort journal history.
425
+ Discovery metadata memory grows with file/profile counts, separately from streamed
127
426
  content processing; metadata enumeration and sorting still run on unchanged
128
427
  passes. Public list APIs retain their full sorted-array output. Per-input
129
428
  cursors in `index/capture.db` replace whole-map JSON loads and rewrites. The
@@ -154,9 +453,29 @@ bounded transactions. Ordinary passes seek new journal bytes without parsing
154
453
  consumed prefixes. Inconsistent identities or cursors invalidate derived state;
155
454
  recovery can cost a historical scan. No journal format or turn ID changes.
156
455
 
157
- Scratch directories are private per synchronous caller (0700 directories, 0600
158
- owner/payload files), with a same-host PID and nonce marker. No supported path
159
- transfers their ownership or open descriptors to a subprocess. A command holding
456
+ Search-index reset remains one atomic transaction. Ordinary tables use SQLite's
457
+ truncate clear; the content-storing FTS table is dropped and recreated using the
458
+ owning schema instead of deleting text rows individually. Readers retain the
459
+ existing old-union/empty-union semantics, including already-open connections.
460
+ An interrupted transaction rolls back the entire reset. Successful timing alone
461
+ does not establish remaining deadline budget; the operator-only
462
+ [reset benchmark](../../../scripts/benchmark-record-reset.md) measures the full
463
+ commit separately from sampled reader blocking on a disposable SQLite backup.
464
+
465
+ The [operator's real-index qualification](https://github.com/awebai/oats/issues/1108#issuecomment-6165193608)
466
+ used benchmark commit `16c62e39aaa43c2bb510cc446c7528359a9a4bd2` on two fresh
467
+ online backups with identical counts: 4.82 GB, 2,286,985 turns and 1,313 streams.
468
+ On macOS ARM/APFS internal SSD, Node 26.11.1/SQLite 3.54.0 with DELETE/FULL,
469
+ the original reset took 45,291 ms and atomic drop/recreate took 824 ms, including
470
+ COMMIT. Longest sampled reader-busy spans were 44,453 ms and 463 ms; 10 ms
471
+ sampling with gaps up to 56 ms does not measure exact reader-exclusion time.
472
+ Sampled rollback-journal peaks (2.39 GB and 4.9 MB) are lower bounds. These
473
+ results qualify the isolated atomic reset on that storage, not the subsequent
474
+ 2.3-million-turn reconstruction, full-pass deadline or Linux service performance.
475
+
476
+ Ordinary scratch directories are private per synchronous caller (0700 directories,
477
+ 0600 owner/payload files), with a same-host PID and nonce marker. Those per-call
478
+ allocations never transfer ownership or open descriptors to a subprocess. A command holding
160
479
  the capture lock removes recognized allocations only after positively proving
161
480
  the local allocator dead and rechecking directory and marker identity. Public
162
481
  synchronous callers still do not acquire an implicit capture lock; their live
@@ -167,16 +486,432 @@ For such leftovers, stop all capture/library users, establish that no caller is
167
486
  using the specific allocation, and remove only that confirmed orphan; do not
168
487
  blanket-delete the scratch area while callers may be active. No age-only cleanup.
169
488
 
489
+ Command recovery uses separately recognized `recovery-*` allocations. Ordinary
490
+ dead-owner scavenging preserves them: allocator death alone cannot erase a job
491
+ that must resume. The registered root-lock worker requires a durable job
492
+ reference, stable allocation nonce and exact directory/payload identities before
493
+ opening one. Adoption requires positive death proof of the previous local owner
494
+ and rechecks the job, marker and registered worker before publication. A
495
+ self-identified owner publication names the prior committed marker stamp, so a
496
+ crash after publication but before its DB checkpoint can be recovered without
497
+ accepting a copied/replaced owner file. No descriptor transfers between workers.
498
+ Lost references, unknown owners and unpublished allocations cannot become proof
499
+ or cleanup authority by pathname. They retain the conservative orphan procedure
500
+ above. A committed deletion mark precedes allocation-specific removal; reference
501
+ finalization can be batched after removal, and interruption is repeatable.
502
+
503
+ `capture-cleanup-work.mjs` supplies that lifecycle as a private work unit.
504
+ `captureCleanupPage` reads at most 128 allocation references by key, including
505
+ active jobs, and returns only deleting jobs. It never scans indefinitely to
506
+ find a match. The caller saves its returned key and resumes another page;
507
+ reaching the end of a page sequence is enumeration evidence, not a completed
508
+ capture pass. Selection does not depend on a source remaining ready, so a
509
+ finished or refused source's deleting reference is still discoverable after
510
+ a worker dies. Active allocations are not selected for deletion.
511
+
512
+ `cleanupCaptureRecovery` binds a selected job to its allocation nonce and
513
+ stream, commits verified adoption, removes the allocation outside a database
514
+ transaction, then divides one bounded hash-row allowance between recovery
515
+ chunks and transcript prefix rows under the stream lock. Both tables must be
516
+ finished before it removes the allocation and staging references. A partial
517
+ unit, cooperative stop after removal, or failed final metadata commit retains
518
+ the deleting reference; the next registered worker revalidates it and resumes.
519
+ The source's committed cursor and journal bytes are not rewritten or recounted.
520
+ The caller still owns fair selection, operational failure handling, budgeting
521
+ and final receipt publication; this unit adds no separate retry policy. Its
522
+ optional commit callback joins admission retirement and confirmed progress to
523
+ the final stream-locked metadata transaction. Callback failure rolls back those
524
+ facts and metadata deletion together, even if the directory is already absent.
525
+
526
+ `CaptureCleanupQueue` supplies private worker scheduling for deleting claims.
527
+ Healthy and retry enumeration have independent durable keyset cursors; each
528
+ turn inspects at most one page of 128 references past its cursor and processes
529
+ at most one allocation under the shared hash-row allowance. When that page ends
530
+ the list without a job, the turn inspects one more page from the start, so an
531
+ unfinished allocation the cursor has passed continues in the same pass; with
532
+ no job there either, the cursor wraps for later work. A cleanup unit that
533
+ commits no metadata progress is not selected again in its pass; the next pass
534
+ tries it again. A scan endpoint describes enumeration only: partial jobs or
535
+ newly added earlier keys can still need work on the next rotation.
536
+
537
+ Before filesystem work, the queue commits an allocation-bound admission and
538
+ the next cursor. The cleanup unit must still acquire the stream lock, prove
539
+ ownership and commit adoption; queued identities never grant pathname authority.
540
+ Its final metadata transaction retires admission and records actual metadata
541
+ progress without inventing source/index counts. Cooperative deadline/RSS stop
542
+ retires only admission, preserving the deleting claim for continuation. Other
543
+ throws or worker death retain admission until the registered replacement
544
+ reconciles it after predecessor death.
545
+
546
+ Reconciliation records a pass-bound failure and allocation-specific backoff
547
+ using the fixed 30/60/120/240-minute schedule. It does not diagnose a journal
548
+ frame, create a public failed-stream row, or change source/index retry evidence.
549
+ Skipped work does not increment attempts or move the retry date. A failed
550
+ allocation cannot retry in the same pass; a due partial unit retains its retry
551
+ until complete and admits at most once in a pass. Successful deletion clears
552
+ only that allocation's retry. Historical run failure remains history; current
553
+ pass failure survives independent healthy processing. Final completion still
554
+ requires the owning runner's all-stage audit, not an empty cleanup page.
555
+
556
+ `capture-recovery-snapshot.mjs` copies the fixed source end in 64 KiB chunks under
557
+ the stream group. Payload fsync precedes committed copy offsets and chunk hashes.
558
+ An uncommitted suffix is truncated only inside the adopted allocation, followed
559
+ by bounded verification of all committed chunk hashes before continuing. Lost
560
+ chunk metadata or mismatched bytes revoke the staged proof. Copying checks the
561
+ raw-record limit incrementally, before allocating a whole oversized record.
562
+ After copying, consumers read only that staged descriptor and verify its version;
563
+ the mutable source remains an observation/custody check, not a replacement data
564
+ source. Append growth uses the shared append-only assumption and bounded source
565
+ boundary witness; replacement, shrink, same-size edits or witness mismatch revoke
566
+ the job. The scheduler's durable reset/retry generation also invalidates a staged
567
+ snapshot; it stays fixed across partial workers so retry cannot restart forever.
568
+ This source qualification is separate from exact journal-generation
569
+ validation. A journal change between workers retires the old fixed-end snapshot
570
+ before comparing a possibly longer captured prefix, including after public or
571
+ outgoing-release writes. Later source growth alone is work for a later snapshot.
572
+ The native command unit may carry a completed proof into its own next journal
573
+ generation only after its fsynced append under the same stream lock, committing
574
+ the source cursor and staged job's new journal version together. An interrupted
575
+ commit instead leaves the old generation and forces revalidation.
576
+
577
+ Small command recovery snapshots have a private optimization when their **total
578
+ fixed end** is at most 8 MiB. Each worker streams a new private copy and full
579
+ SHA-256 in 64 KiB chunks before trusting saved comparison progress. Complete
580
+ digest plus size identifies the proven bytes; source identity/observation,
581
+ reset/retry generation and exact journal generation must also qualify. The
582
+ comparison consumes that worker's verified snapshot, never a later source-path
583
+ reopen. Same-content replacement takes the normal validation path. Matching
584
+ snapshots preserve comparison progress; a changed digest or other qualification
585
+ restarts proof before append. Ordinary unchanged/growth capture does not use
586
+ this recovery optimization.
587
+
588
+ These small copies are disposable per-call allocations, with no payload or
589
+ ownership-handoff fsync. Their loss never loses a proven source checkpoint:
590
+ the next worker must copy/hash again. Repeated source/stage bytes are recovery
591
+ work and are counted separately from probes and ordinary incremental work.
592
+ If restaging exhausts the unit before required work can advance, the processing
593
+ commit selects retained resumable copying for subsequent admissions. A killed
594
+ unit cannot publish an in-memory fallback decision; its durable failed-admission
595
+ retry selects the retained path. The fixed source end is preserved by committed
596
+ observation metadata, which alone never authorizes prefix proof. SQLite commits,
597
+ journal syncs, root-lock publication and retained fallback syncs remain separate
598
+ costs; avoiding disposable-copy fsync is not a claim that first-upgrade storage
599
+ cost or the complete service has been qualified.
600
+
601
+ Staging consumes source-sized private space plus bounded-per-chunk hash metadata.
602
+ Revalidating staged bytes after interruption is recovery work, reported separately
603
+ from mutable-source reads and boundary probes. Completed or invalidated jobs
604
+ reclaim hashes in bounded units; a hash-cache entry never authorizes deletion of
605
+ a filesystem path. These are private worker primitives; their tests do not by
606
+ themselves qualify the complete command scheduler, run receipts or service limits.
607
+
608
+ The private `NativeCaptureDiscovery` walker checkpoints only its active
609
+ per-directory stack, directory identities and exact last basenames. A resumed
610
+ walker loads that stack directly rather than revisiting completed sibling
611
+ subtrees. Within a worker it retains only the sorted arrays for active
612
+ ancestors; completion, close and errors release those arrays. Selection and
613
+ stable `localeCompare` ordering match the public cc/pi/codex inventories,
614
+ including Claude's restricted subagent layout and existing link distinctions.
615
+ A replaced active directory invalidates its position. An absent fresh default
616
+ can be empty; disappearance of an already selected directory is an error.
617
+
618
+ Each discovery unit accounts for visited metadata entries, including irrelevant
619
+ ones, and returns a bounded file page plus the next checkpoint. The scheduling
620
+ caller must commit that page and checkpoint together. Directory reads/sorts
621
+ can recur on restart and their arrays still grow with directory size; this is
622
+ not a constant-memory metadata claim or new-byte-only work. Newly inserted
623
+ names before the saved position belong to a later sweep. A missing anchor
624
+ conservatively replays its collation equivalence class, requiring idempotent
625
+ inventory insertion. This walker does not itself select roots, schedule
626
+ capture/index work or certify that a complete command sweep occurred.
627
+
628
+ ## Internal transaction groups
629
+
630
+ The package-private `capture-context.mjs` helper can group synchronous work over
631
+ at most 128 streams. It acquires every stream lock in canonical order before
632
+ starting a shared `capture.db` transaction. Helpers reuse that connection and
633
+ use savepoints for nested failure isolation; journal appends still fsync before
634
+ the group commits derived offsets/IDs. No additional stream may be acquired
635
+ inside the transaction. This preserves public writers' stream-before-database
636
+ lock order. Group acquisition accepts an internal stop check and unwinds partial
637
+ acquisitions on failure. Callers must select bounded work before entering a group;
638
+ the helper alone does not turn a full reconciliation into a bounded pass.
639
+
640
+ Command groups can supply a bounded admission manifest. After acquiring all
641
+ member locks, the helper rechecks each exact journal generation and commits the
642
+ manifest plus the next fairness position in a separate transaction, before any
643
+ processing. That position is queue progress, not a processing cursor. The same
644
+ intent transaction also retains each stage's last position independently;
645
+ intervening index work cannot reset source rotation. This adds one state-row
646
+ write per admission, not another transaction or a per-record sync. Completed
647
+ checkpoints and removal of the active manifest then share the processing commit.
648
+ A crash or thrown error leaves the manifest and fairness position intact, while
649
+ only journal bytes already fsynced survive a rolled-back processing transaction.
650
+ The scheduler must reconcile an unfinished manifest before admitting another;
651
+ the helper refuses to overwrite it or guess per-member failure rows. A normal
652
+ changed group therefore adds one intent commit, regardless of its record count.
653
+ No-op groups without admission add no intent transaction. These counts describe
654
+ explicit SQLite transactions, not filesystem sync calls or storage latency.
655
+
656
+ `capture-retry.mjs` reconciles an interrupted manifest after the previous worker
657
+ has exited. One transaction stores retry membership, run failure evidence and
658
+ any attributable single-stream failure, then removes the manifest. A failed
659
+ commit leaves the manifest available for retry; completed reconciliation is
660
+ idempotent. Neither reconciliation nor admission advances processing cursors.
661
+ Deferred membership is separate from public failure rows. Admission itself
662
+ requires a due, single-stream retry and rejects a second attempt in the same
663
+ run. A separate durable retry position rotates incomplete members across runs;
664
+ bounded keyset enumeration avoids retaining all deferred members in memory.
665
+ The scheduler supplies a finite, fair healthy sweep before deferred selection.
666
+ Enumeration still costs metadata work and is not a new-content-only operation.
667
+
668
+ Resolution joins the processing checkpoint transaction. An unchanged journal
669
+ must be processed through the failed snapshot's end, or the stage must validate
670
+ that the unit no longer needs work. A checkpoint inside that snapshot, a changed
671
+ generation, expiration of the retry date or a process restart cannot by itself
672
+ clear the warning. The stage remains responsible for proving reconciliation;
673
+ these private queue helpers do not implement the full source/index scheduler.
674
+
675
+ Journal recovery exposes an internal work-unit interface: obsolete-ID deletion
676
+ has a persisted phase, and validation commits its byte/count cursor after each
677
+ bounded batch. A changed exact journal version invalidates that progress. A
678
+ partial checkpoint never authorizes append. Source framing accepts an internal
679
+ record limit and checks it before joining an oversized line; public callers keep
680
+ their unlimited framing default. These primitives require a scheduling caller to
681
+ provide budgets and continuation; they do not bound public library operations.
682
+
683
+ `advanceTranscriptPrefix` is the internal resumable comparison for a verified
684
+ immutable source snapshot. Its durable phases clear obsolete hashes, consume
685
+ the journal from a byte checkpoint, then compare source lines from a byte/line
686
+ checkpoint. Hashes and phase progress share the surrounding stream group's
687
+ transaction. A snapshot identity or exact journal generation change revokes
688
+ the proof; losing the hash table or its epoch cannot qualify old checkpoints.
689
+ Only the ready phase authorizes the caller to append. A late disagreement
690
+ reports the conflicting source line/offset without appending any suffix.
691
+ Cleanup revokes the proof before deleting bounded batches of hashes. Journal
692
+ processing retains the historical-single-record qualification; the raw source
693
+ record policy is not a serialized-journal size limit. This comparison helper
694
+ does not own snapshot staging, transfer its ownership or read the mutable source.
695
+
696
+ `capture-native-unit.mjs` combines these private primitives for one native input.
697
+ It performs bounded journal validation before any append, resumes verified
698
+ snapshot/prefix work when a source cursor is unqualified, and admits one bounded
699
+ batch from the verified bytes. Ordinary known growth uses the source cursor and
700
+ bounded witness without staging historical content. The fixed end survives
701
+ partial units; later growth is a later sweep. A separately checkpointed search
702
+ frontier finds the first timestamp across units, then carries it backward while
703
+ capturing the unstamped prefix. An unchanged unstamped or torn tail stays pending
704
+ without repeatedly scanning it. A record over the raw-record limit commits the
705
+ unit's complete records before it, then sets the input aside at its start
706
+ offset ([operator recovery](#operator-recovery)). Explicit retry generations
707
+ persist separately from active issue rows, so clearing a resolved issue cannot
708
+ restart its proof.
709
+ Ignore is applied before source/custody access; retry still compares the complete
710
+ captured prefix. The scheduler must account for pending/failed work and perform
711
+ allocation cleanup after its deletion mark commits. These are unit interfaces,
712
+ not a resource promise for public synchronous capture or exact receipts.
713
+
714
+ `capture-aw-unit.mjs` similarly processes one fixed-end log unit. Every scanned
715
+ raw line consumes its work allowance, including blank lines, malformed complete
716
+ lines and projection refusals. Cursor publication follows the pending batch's
717
+ durable append. A valid final object without its newline retains its starting
718
+ offset and keeps the command pending; an unchanged snapshot does not repeatedly
719
+ project that fragment. Replacement or explicit source reset reprojects through
720
+ persistent journal-ID deduplication. Raw oversized input uses the same set-aside
721
+ store, prefix capture and retry/ignore rules as native inputs
722
+ ([operator recovery](#operator-recovery)); a projection refusal itself is
723
+ consumed evidence and does not create a second issue mechanism.
724
+
725
+ Public synchronous library calls do not implicitly enter this context or acquire
726
+ a root capture lock. Healthy derived-state opens do not run a schema write
727
+ transaction, and identical state values do not produce redundant row updates.
728
+
729
+ The private supervisor transport admits one child at a time under the root lock. The child
730
+ announces its nonce and stays idle until the supervisor durably publishes its
731
+ identity in that lock and sends permission to start. A live, reused or unknown
732
+ worker PID prevents reclamation after supervisor death. Release occurs only
733
+ after the owned child exits; signals target the spawned child handle, never a
734
+ PID inferred from an abandoned lock or a process group. Continuation retains the
735
+ same root lock: it replaces only the exact previously registered worker identity
736
+ after positive death proof. Reused or uncertain PIDs prevent replacement.
737
+ Workers check their parent and lock identity between work units. The supervisor never writes status
738
+ on behalf of a crashed worker. A shared monotonic deadline includes process
739
+ startup and lock publication, with a separate cooperative drain boundary.
740
+ Launch arguments fix the heap policy and exclude inherited Node flags and
741
+ preloads. This transport requires a reconciliation entry that supplies bounded
742
+ units and persists run facts; it does not itself implement a complete pass.
743
+
744
+ `capture-pass.mjs` supplies serial child continuation under that same absolute
745
+ deadline. Startup, publication, checkpoint finalization and reaping consume the
746
+ pass budget; child replacement cannot renew it. Normal work has internal drain,
747
+ finalization and forced-stop boundaries, and is admitted only with its full
748
+ allowance. A reserved start and time allowance let a final worker reconcile an
749
+ interrupted predecessor and persist run facts. All starts, including spawn
750
+ failures and finalization, count against the fixed internal ceiling. The parent
751
+ can report its observed process failure, but only a worker can reconcile durable
752
+ admission and attribute it. There is no in-pass diagnostic retry mode. The
753
+ reconciliation entry must select independent ready work before deferred failed
754
+ work; transport tests alone do not establish that scheduling or recovery rule.
755
+
756
+ Bounded index groups reuse the already acquired stream group and capture-state
757
+ connection. Validation precedes the index write transaction; completed index
758
+ rows and byte/count cursors commit together once per group. A cooperative stop
759
+ commits completed work, while an exception rolls back that index group. Each
760
+ selected stream receives a share of the record/byte budget, so a large journal
761
+ does not consume every selected stream's allowance. The scheduler must visit
762
+ both live streams and indexed streams whose journals disappeared, and restart
763
+ its index sweep after an atomic union reset. The group helper never declares
764
+ the entire root complete. It defaults to returning `resetRequired` without
765
+ mutating index rows when reset is needed. The scheduler must reserve a fresh
766
+ full worker allowance for that atomic operation; the detection unit and the
767
+ finalization reserve cannot implicitly start it. Explicit reset permission is
768
+ an internal seam, not a public policy override. A no-op group performs no index write transaction;
769
+ its capture-state transaction remains separate from the index commit. A failure
770
+ between the two commits is recovered through journal version/epoch validation,
771
+ not by assuming a cross-database atomic transaction.
772
+
773
+ `capture-index-work.mjs` joins a selected index group to durable admission,
774
+ per-stage scheduling position and run accounting. Its caller supplies a finite,
775
+ fairly ordered union of live and indexed streams; this bridge neither builds
776
+ that inventory nor certifies sweep completion. Failure attribution starts at
777
+ the saved validation boundary when recovery is unfinished, otherwise at the
778
+ qualified index cursor. Changed journal generations start validation at zero.
779
+ Only the locked group validates and consumes those cursors.
780
+
781
+ Index rows commit before their confirmed `turnsIndexed` count joins the
782
+ capture-state commit. If that later transaction fails, the durable admission
783
+ remains for reconciliation while the index rows can survive. Resuming an
784
+ already indexed unit does not reconstruct its lost run count. Validation or
785
+ indexed-byte advancement can update progress; a no-op visit does not. Due
786
+ index retries are single-stream admissions; only completion of the current
787
+ validated journal resolves them. Partial validation/indexing and reset requests
788
+ retain failure evidence, and other-stage retries return to the scheduler.
789
+ Reset detection always defers: the owning scheduler must reserve a fresh full
790
+ worker allowance for reset and restart the union sweep afterward. Source,
791
+ discovery, cleanup and final receipt routing remain separate responsibilities.
792
+
793
+ The private `CaptureIndexInventory` builds the union of indexed stream names
794
+ and live journal stream names in `capture.db`. Indexed names are enumerated
795
+ first, including names whose journal disappeared; they remain in the inventory
796
+ so locked index validation can detect changes to cross-stream tombstone
797
+ authority. Each discovery call inspects at most 128 index rows or directory
798
+ entries, including irrelevant names. Inserting that page and advancing its
799
+ checkpoint share one transaction. Names shared by both sources occur once.
800
+ The inventory never reads journal content, changes index rows or grants reset
801
+ permission.
802
+
803
+ A scheduler-owned sweep identity resumes discovery across connection/worker
804
+ restarts. Live discovery retains a sorted directory-name array only within the
805
+ worker and resumes by a binary name key when reopened, even if that anchor was
806
+ removed. The selected streams directory's identity must remain unchanged.
807
+ Directory listing/sorting is still metadata work proportional to directory
808
+ size, and can recur after restart; it is not a bounded-memory metadata claim.
809
+ New names before the saved position belong to a later sweep. A fresh absent
810
+ directory can be empty; disappearance/replacement after selection is an error.
811
+
812
+ Ordered reads use bounded database pages and rotate after the durable index
813
+ admission position, visiting the discovered union once per iterator. Inventory
814
+ rows are not removed on an apparent index completion: membership is not cursor
815
+ or generation proof. The `complete` flag only means enumeration finished, never
816
+ that indexing or a pass succeeded. The scheduler still owns index outcomes,
817
+ new streams created by interleaved capture, reset admission and a fresh union
818
+ sweep after reset. Replacing a sweep retires its exact scope; indexed cleanup
819
+ deletes at most 128 obsolete rows per unit and refuses the active scope. Losing
820
+ this private table restarts enumeration without clearing retries, journal
821
+ checkpoints or the index. These primitives alone are not the full command runner.
822
+
823
+ `CaptureIndexOutcomes` records processing phases separately from membership in
824
+ that private inventory. The index-work bridge publishes outcomes inside the
825
+ admitted stream group's capture-state transaction, after the index commit and
826
+ run accounting. A failure in outcome publication rolls back its marks and run
827
+ counters together, leaving the admission for reconciliation even when index
828
+ rows survived. A later no-op can qualify those existing rows without guessing
829
+ the lost earlier run count.
830
+
831
+ A stored complete phase is only cached evidence. Before skipping that stream,
832
+ the outcome reader compares the current journal file version, completed
833
+ validation epoch/byte/count checkpoint and index count/byte/epoch cursors with
834
+ the recorded evidence. Growth, replacement, validation loss, outgoing count
835
+ writes or an index reset revoke mismatching evidence. This is metadata
836
+ requalification, not a historical content scan or new integrity mechanism;
837
+ locked validation/index work still owns processing authority. Outstanding
838
+ retries keep the stream pending. Ordinary inventory enumeration retains all
839
+ names, while outcome-aware selection skips only still-qualified completions.
840
+
841
+ The scheduler requalifies each stream once per worker pass. A stream found
842
+ qualified, or recorded complete by an index group, is not compared again by
843
+ later steps of that pass, and a walk that finds every stream qualified leaves
844
+ the index stage with no candidates. Each write the pass makes to a stream
845
+ revokes that: a capture unit other than an unchanged one, or an index outcome
846
+ other than complete. So does a new inventory member. A new worker, and so
847
+ every pass, requalifies every stream once; due retries, the completion audit
848
+ and other outcome reads always compare the evidence.
849
+
850
+ The source-work bridge can join an active index inventory to its processing
851
+ commit. It inserts every processed stream, including replay with no new append,
852
+ so streams created after directory discovery are not omitted. Duplicate
853
+ membership does not alter a prior outcome; subsequent outcome reads requalify
854
+ that evidence against the changed journal. A failed source transaction rolls
855
+ back membership with its source checkpoint and counters, while the durable
856
+ admission remains available to reconcile surviving journal bytes.
857
+
858
+ Reset-required outcomes remain durable and block further outcome-aware index
859
+ work in that sweep. Neither detection nor the outcome scheduler executes reset.
860
+ The owning scheduler must admit the separate atomic operation and replace the
861
+ inventory sweep afterward. Outcome audit pages inspect at most 128 names and
862
+ report how many still need work; their end-of-page `complete` flag is only audit
863
+ enumeration completion. The caller must also account for unfinished discovery,
864
+ new captures, retries, reset and other stages, and recheck after writes before
865
+ finalizing a pass. These outcome/source connections supply evidence to the
866
+ separate mixed-stage audit and owning command entry described below.
867
+
868
+ The private `CaptureIndexReset` bridge persists a union-reset request only
869
+ after an inventory outcome requires reset. The detecting worker publishes the
870
+ request and yields; a transient `resetRequired` continuation asks the pass
871
+ transport for a fresh normal worker allowance. Finalization never receives
872
+ that allowance. The reset bridge refuses the detecting worker, a normal worker
873
+ without reset admission, or an unreconciled stream admission. The owning entry
874
+ must dispatch reset before ordinary processing in that fresh worker. A restart
875
+ that lost the transient continuation can request another fresh worker from the
876
+ durable request; it cannot silently reset during ordinary processing.
877
+
878
+ Union-reset admission is separate from stream admissions. The reset transaction
879
+ uses the same atomic table mutations as public reset and commits a private token
880
+ in the existing index metadata table. It does not change schema version, owner,
881
+ journals, stream retry/failure rows or reader visibility. Only after that index
882
+ commit does a capture-state transaction publish a new, empty, pending inventory
883
+ scope, retire the old scope for bounded cleanup, record progress and remove the
884
+ request. These two commits are not a cross-database atomic transaction.
885
+
886
+ If sweep publication fails after the reset commits, a replacement worker uses
887
+ the index token to finish the bounded metadata publication without resetting
888
+ again. Index writes performed after the completed reset survive that recovery;
889
+ their counts are not reconstructed into the run receipt. If the reset itself
890
+ rolls back, the old index and request remain. The next registered worker, after
891
+ the predecessor has ended, reconciles the private admission into a pass-bound
892
+ failure and the fixed 30/60/120/240-minute retry delay. An attempted reset cannot
893
+ repeat in the same pass. A union failure does not identify a failing stream or
894
+ frame, so it creates no guessed stream-failure row and erases no stream retry.
895
+ The run writer must carry that returned failure into its actual pass receipt.
896
+ Completed-token recovery may finish metadata in a finalization worker; that
897
+ does not grant permission to execute another index reset there.
898
+
899
+ Reset completion starts index discovery/processing again; it is never indexing
900
+ completion or pass success. These reset and transport helpers still require
901
+ the owning mixed-stage entry to route reconciliation, healthy independent work,
902
+ deferred resets and final receipts. Transaction/reopen fixtures model this
903
+ handoff separately from actual worker-death and hosted manager qualification.
904
+
170
905
  ## First-upgrade cost
171
906
 
172
907
  The first capture after upgrade must reconcile existing journals and rebuild the
173
- search index. Per-input capture checkpoints and per-stream index transactions
174
- still incur substantial synchronous commit costs on storage where sync is costly.
175
- Connection/transaction amortization is unresolved by these algorithm changes;
176
- bounded memory and incremental content work do not imply a cheap first pass.
177
- The bounded service must separately qualify first-upgrade and unchanged passes
178
- beside actual v0.53.0 on a Linux runner, including filesystem/runtime details,
179
- connection/transaction/sync counts, resumable prefix proof and deadline progress.
908
+ search index. Capture and index groups amortize connections and transactions
909
+ over their member streams ([internal transaction groups](#internal-transaction-groups)):
910
+ a changed index group of several streams commits once per database, and an
911
+ unchanged one begins no index transaction. The bounded service must separately
912
+ qualify first-upgrade and unchanged passes beside actual v0.53.0 on a Linux
913
+ runner, including filesystem/runtime details, connection/transaction/sync
914
+ counts, resumable prefix proof and deadline progress.
180
915
 
181
916
  ## Downgrade and re-upgrade
182
917
 
@@ -191,3 +926,683 @@ versions and mismatched index counts on re-upgrade, requiring derived rebuilds.
191
926
  Deleting the derived caches has the same recovery cost. No journal-byte migration
192
927
  or rollback is required. Native-prefix set-aside is essential to that guarantee;
193
928
  it does not rewrite history or append a sentinel or duplicate terminal turn.
929
+
930
+
931
+ ## Private source inventory
932
+
933
+ `capture-source-queue.mjs` stores command discovery pages in the derived
934
+ `capture_sources` table. At most 128 input descriptors and the walk checkpoint
935
+ join one transaction. Replayed discovery preserves original ordinal positions
936
+ and completed outcomes. A new selection or a finished visit sweep creates a
937
+ new private scope; superseded scope rows are deleted by indexed 128-row units,
938
+ without scanning or resetting another owner's current inventory. Losing the
939
+ inventory table invalidates its discovery checkpoints and re-enumerates; it
940
+ never changes journals, source cursors, IDs or prefix-proof authority.
941
+
942
+ Ready-input reads use bounded database pages. Admission advances the persisted
943
+ source position before processing; source outcome changes commit alongside the
944
+ owning capture helper's source checkpoint. Rollback therefore retains the old
945
+ processing state while allowing another independent ready input its turn.
946
+ Native paths sharing a stream retain discovery precedence until the earlier
947
+ input reaches its fixed end, pending state or refusal. AW files may rotate
948
+ between bounded units in their shared stream; the existing retry selector still
949
+ applies stream-scoped backoff and admits no concurrent writer. The queue does
950
+ not clear failure rows or treat a finished inventory containing pending,
951
+ set-aside or failed inputs as a successful pass. Directory metadata work and
952
+ queue metadata work remain separate from source/journal content work.
953
+
954
+ `capture-source-discovery.mjs` connects an explicit ordered list of ordinary
955
+ `{ source, path }` roots to that queue. A persisted plan identity rejects a
956
+ changed root list within an unfinished sweep. Discovery rotates among cc, pi,
957
+ codex and AW, retaining caller root order within each format. Native traversal
958
+ uses the existing format layouts and stable `localeCompare` order; AW uses
959
+ code-unit sorted basenames. Each unit visits at most 128 metadata entries,
960
+ including irrelevant names, and inserts its selected files with the updated
961
+ walk position in one capture-state transaction. Its `added` count describes
962
+ the selected page, including any idempotent replay, not newly captured files
963
+ or processing progress. A failed commit discards volatile walkers so the next
964
+ unit reloads the durable checkpoint.
965
+
966
+ Directory-name arrays remain proportional to the selected directories and may
967
+ be rebuilt after worker replacement. Native walkers cache only active directory
968
+ stacks; AW caches one directory per current root. These are metadata costs, not
969
+ a bounded metadata-memory guarantee. Selected directory identities are checked
970
+ on reopening and before each page, including cached native ancestors. A fresh
971
+ missing optional root can enumerate as empty; a selected root cannot disappear
972
+ or be replaced silently. AW resumes by basename even when its anchor vanishes;
973
+ native traversal retains its conservative replay rule. Earlier arrivals can
974
+ belong to a later sweep. Closing or failing the bridge releases its caches.
975
+
976
+ The owning caller still supplies the queue's selection identity and either
977
+ explicit roots or a stable default-root plan. `capture-default-roots.mjs`
978
+ constructs the latter without filesystem work: explicit caller home/cwd,
979
+ selected formats, and only the native location environment keys. It does not
980
+ forward unrelated environment, credentials or Node runtime options. The
981
+ existing format selectors retain their configured-root refusal, relative-path,
982
+ Pi tilde/override precedence and Claude profile order. AW retains its home-based
983
+ log directory rather than inheriting XDG selection. The public synchronous
984
+ selectors and capture library are unchanged.
985
+
986
+ Default-root resolution is a separate owned discovery unit before file pages.
987
+ Its durable attempt binds the same sweep/plan/run/worker and unresolved format
988
+ group before the selector performs stat/readdir/sort. The private attempt's
989
+ `roots` phase identifies selection, and its path is the caller home context,
990
+ not an attributed journal or a claimed selected source path. Success commits
991
+ the format's ordered root list and directory identities with attempt retirement;
992
+ replacement reuses that list rather than rerunning selection. A new profile
993
+ appearing afterward belongs to a later sweep. Changed caller configuration
994
+ within an unfinished plan is refused. Excluded formats require no selector
995
+ I/O. A default-root plan cannot resolve without owning-run/worker context;
996
+ direct explicit-root readers retain their existing defaults.
997
+
998
+ Caught resolution errors and killed attempts use the existing format rotation,
999
+ pending failure/backoff and replacement reconciliation. An unresolved format
1000
+ keeps its original selection inputs, not an invented partial root list. A due
1001
+ resolution retry reruns that selector; successfully publishing the selection
1002
+ resolves that operation's private retry, not the later file enumeration or
1003
+ processing. The failed pass's failure evidence is retained. Publication rollback
1004
+ keeps the unresolved attempt recoverable. Shared storage errors still propagate.
1005
+ Once roots are published, their directory witnesses are carried into the first
1006
+ reader and checked on later pages: deletion or replacement cannot become an
1007
+ empty default merely because enumeration had not started. A fresh absent AW
1008
+ default remains optional. No selection result itself grants completion.
1009
+
1010
+ Default-root selection may materialize and sort the home directory and retain
1011
+ a list of matching profiles; this is proportional metadata cost, not a bounded
1012
+ memory claim or transcript parsing. Each selected format adds one admission and
1013
+ one publication transaction before its file pages; retries/reconciliation and
1014
+ directory identity stats add work as well. All belong in hosted allowance and
1015
+ storage/synchronization qualification. The ordinary CLI uses this plan, including
1016
+ append-only `--no-index`. Protected exact-home/file operations retain their
1017
+ separate synchronous path. Foreground watch may also enumerate roots in the
1018
+ parent for advisory notification hints; those hints cannot change this plan.
1019
+
1020
+ Descriptors do not authorize access to protected captured history: existing
1021
+ path guards apply, and this ordinary-root bridge accepts no custody-proof
1022
+ fields. Protected exact-home/file frontdoors retain their own proof contracts.
1023
+ Discovery completion means only enumeration ended; queued source processing,
1024
+ newly created streams, retries, cleanup and final index validation remain
1025
+ separate obligations.
1026
+
1027
+ When the owning session supplies its run and registered worker identity, each
1028
+ selected discovery unit first commits an attempt bound to that worker, run,
1029
+ sweep, plan, format/root and original checkpoint. This intent is not enumeration
1030
+ or processing progress. Reader work runs outside that transaction. Successful
1031
+ page/checkpoint publication retires the exact attempt in the same transaction;
1032
+ publication rollback preserves both the original checkpoint and the attempt.
1033
+ Before scheduling or opening run accounting, the registered replacement
1034
+ reconciles an ended predecessor's attempt into private pending root failure and
1035
+ backoff. The original run owns that failure; an observed current-pass process
1036
+ failure cannot be assigned to an older admission. Same-worker reconciliation
1037
+ and changed scope/plan/checkpoint are refused. This relies on the owning
1038
+ bootstrap ending the predecessor before registering its replacement.
1039
+
1040
+ A caught reader refusal likewise commits private root-failure evidence and
1041
+ format rotation while retiring its attempt before propagating the error.
1042
+ The refused root keeps its exact checkpoint and stays incomplete. Its format
1043
+ cannot advance to later roots, but a replacement worker can discover other
1044
+ formats and process independent queued capture, index and cleanup work. The
1045
+ failure remains bound to the failed pass; later healthy work cannot clear it
1046
+ or invent a failed journal stream. Direct readers without owning-run context
1047
+ continue to throw without publishing failure state.
1048
+
1049
+ Failed roots use the fixed 30/60/120/240-minute schedule and exclude the pass
1050
+ that attempted them. Due discovery follows independent healthy work and
1051
+ eligible stream/cleanup retries. One partial retry page per pass preserves its
1052
+ attempt/date and marks that pass attempted; only completing the refused root
1053
+ retires its pending failure. Restoring a selected directory permits recovery;
1054
+ a different directory never inherits its checkpoint. A deferred root keeps
1055
+ enumeration pending without blocking unrelated due work. These guarantees
1056
+ require functioning shared capture state: failure-evidence publication and
1057
+ page/checkpoint storage errors propagate, and cannot promise independent
1058
+ progress. An unfinished attempt can be reconciled only once the shared state
1059
+ is usable again. Owned discovery adds one admission transaction per selected
1060
+ page; page publication and retirement share the existing page transaction
1061
+ (with its nested queue savepoint). Final storage accounting must include these
1062
+ commits, retry/reconciliation transactions and actual synchronization cost;
1063
+ no lower fsync-cost claim follows from connection reuse.
1064
+
1065
+ `capture-source-work.mjs` joins one selected source group to those queue
1066
+ checkpoints and `CaptureRun` accounting. Locks precede the admission commit and
1067
+ processing transaction. Each input/category contributes to its run's counters
1068
+ once even when recovery spans workers; the visit flags live in derived database
1069
+ rows, not a process-wide file map. No-op visits do not count as processing
1070
+ progress. One AW account per shared-stream admission preserves serialized
1071
+ appends while the queue position allows other accounts their turn. A due retry
1072
+ is a single-stream admission, and an incomplete proof cannot clear its failure.
1073
+ Other-stage retry work returns to the scheduler rather than being mistaken for
1074
+ capture work. Allocation cleanup remains a separate committed-lifecycle step.
1075
+
1076
+ These private primitives do not themselves hold a root lock or implement the
1077
+ complete command runner. Their caller must own that lock, enforce the common
1078
+ budget, reconcile unfinished admissions, and publish the actual run outcome.
1079
+
1080
+ ## Private worker dispatch
1081
+
1082
+ `CaptureWorkSession` joins source/index processing, reset handoff and run
1083
+ accounting inside an already registered supervisor worker. Its bootstrap caller
1084
+ must own the root lock and have ended the predecessor before construction. The
1085
+ index-enabled session shares one capture-state connection and one search-index connection,
1086
+ reconciles durable stream, cleanup and union-reset admissions, then opens current run
1087
+ accounting. A recorded failure is bound to its run identity: an observed failure
1088
+ in the new pass cannot diagnose an older abandoned admission. Prior history
1089
+ remains distinct from failure in the current pass, including a child that died
1090
+ before publishing any receipt. Persisted reconciliation facts survive a second
1091
+ interruption before run publication.
1092
+
1093
+ With an explicit root plan, each dispatch step advances at most one bounded
1094
+ source-discovery page, one index-discovery page, one source or index group and
1095
+ one healthy cleanup turn after a selected group. Without a root plan, the
1096
+ caller supplies source pages as before. The last durable admission's stage
1097
+ determines which processing stage goes first next, including after a rolled-back
1098
+ group; no extra per-record or per-unit routing transaction is added. Source groups register new
1099
+ streams in the current index inventory as part of their processing commit.
1100
+ Cleanup uses its own allocation admission and cursor transactions; it does not
1101
+ replace the durable source/index stage position or claim lower sync cost.
1102
+
1103
+ Healthy selection in both processing stages suppresses retries. Only after both
1104
+ healthy stages and eligible discovery are exhausted does the session route a
1105
+ due retry through its own stage as a single-stream admission. Retry filtering retains
1106
+ unavailable capture inputs and other-stage work without changing their attempt
1107
+ or retry date, so they do not hide eligible source/index retries. Selection
1108
+ checks cooperative stop between bounded metadata pages/rows. Stage helpers keep
1109
+ their earlier default retry behavior when used without this dispatcher.
1110
+
1111
+ When no healthy group is selected, the session advances healthy cleanup pages
1112
+ before due work. Due cleanup follows healthy source/index work, eligible source
1113
+ and index discovery, and source/index retries. Cleanup can progress without a
1114
+ ready source. A cleanup exception leaves the already-committed group counts
1115
+ intact; replacement reconciliation applies backoff while independent healthy
1116
+ work remains eligible. A completed page or idle selection does not prove that
1117
+ every deleting reference has finished, especially across cursor wraparound.
1118
+
1119
+ A native input with its exact `stream:path` recovery claim in deleting phase
1120
+ depends on that allocation's cleanup. Selection rechecks the durable claim and
1121
+ excludes that input from both healthy capture and due capture retry until the
1122
+ claim retires, even if its directory is already absent. The source stays ready;
1123
+ neither its completion nor retry resolution is invented. Independent source and
1124
+ index work can drain before due allocation cleanup, after which the next
1125
+ selection can resume the native input. This avoids repeated cleanup-only source
1126
+ admissions starving the allocation's own backoff queue. Unrelated paths/streams
1127
+ and existing stream retry evidence retain their normal scheduling rules.
1128
+
1129
+ A fresh reset worker dispatches the union operation before ordinary work. A
1130
+ committed reset reopens the published pending inventory; an interrupted one is
1131
+ reconciled before processing. Detection requests a new worker rather than
1132
+ resetting in place. Deferred reset leaves independent source work eligible while
1133
+ index processing is blocked. Finalization can recover a committed reset's
1134
+ bounded metadata publication, but performs no discovery, source/index group,
1135
+ cleanup deletion or new reset.
1136
+
1137
+ Yielding publishes pending run facts. `finish()` is a conservative stop receipt,
1138
+ including for a finalization-only worker; it does not infer success from idle
1139
+ selection. The owning normal worker calls `complete()` for the separate final
1140
+ decision. `capture-completion.mjs` verifies source enumeration and outcomes,
1141
+ discovery/root failures, stream/cleanup/reset/discovery admissions, retries,
1142
+ retained allocations/stages, issue rows and obsolete inventory cleanup. Only
1143
+ complete or ignored source outcomes can contribute to success. Every current
1144
+ index outcome is checked against its journal generation, validation and index
1145
+ cursor evidence again. A fresh index-name/live-name union check adds missing
1146
+ members as ready work, including journals arriving before an earlier discovery
1147
+ cursor; they require processing before a later audit can succeed. Neither idle,
1148
+ reset publication nor a completed enumeration is a completion certificate.
1149
+
1150
+ The audit uses SQL pages of at most 128 rows and cooperative checks between
1151
+ metadata entries. Sorted live directory names retain the existing metadata-array
1152
+ cost qualification. Capture-state then index write reservations prevent supported
1153
+ database writers from changing the checked state during the audit. It acquires
1154
+ no stream locks and reads no journal content while holding those reservations.
1155
+ Journal evidence retains its per-stream metadata qualification; this is not a
1156
+ root-wide instantaneous filesystem snapshot or a new historical integrity proof
1157
+ against arbitrary raw file edits. Directory identity replacement is refused;
1158
+ observed directory changes or newly discovered members leave pending work.
1159
+
1160
+ Audit progress is worker-local: an interruption or deadline cannot turn a saved
1161
+ partial scan into later completion authority. A replacement verifies afresh.
1162
+ Source/content/index recovery and discovery retain their resumable checkpoints.
1163
+ The final metadata audit must fit one admitted normal worker; its lock duration,
1164
+ directory metadata memory and 1,300/thousands-stream completion time remain
1165
+ explicit hosted Linux/storage qualification gates. No measured bound or final
1166
+ service qualification follows from this private implementation. Each audit adds
1167
+ one capture-state transaction and an index reservation released without index
1168
+ mutation. Missing memberships or a retirement intent can add capture-state
1169
+ writes; include their real synchronization cost in storage accounting.
1170
+
1171
+ Terminal source visits can request retirement even when a torn, set-aside or
1172
+ failed input makes the receipt partial. The intent is bound to the source scope
1173
+ and run. It takes effect only on a later normal construction that sees that run's
1174
+ published final receipt; death before publication preserves the same source
1175
+ scope and confirmed counters. The next source sweep also renews index discovery.
1176
+ Old source/index inventories retire in bounded pages after healthy work, without
1177
+ manufacturing capture/index progress or counts. Pending inputs are thus revisited
1178
+ on a later sweep without being treated as successful in the earlier one.
1179
+
1180
+ An empty healthy audit may publish complete. Current-pass failure still overrides
1181
+ healthy work and complete audit evidence; an older failure remains history and
1182
+ does not poison a later success. Confirmed counts come only from their existing
1183
+ processing commits, never audit scans or reconstruction. Ordinary CLI dispatch
1184
+ uses this session. Protected exact-home/file operations retain their existing
1185
+ path; explicit hooks use a detached caller of the same session. Installed
1186
+ periodic service migration uses the setup gate below.
1187
+
1188
+ ### Append-only worker mode
1189
+
1190
+ The private session's `indexEnabled: false` option implements the supervised
1191
+ ordinary-command path for `--no-index`. The default remains enabled.
1192
+ A disabled session never constructs or opens `RecordIndex`, including during
1193
+ replacement or finalization. It does not create `turns.db`, register new stream
1194
+ membership, instantiate/rebuild index inventory, dispatch/reconcile union reset,
1195
+ retire index inventory or modify its source binding. Existing index/reset
1196
+ requests, retries and outcome evidence remain for a later enabled pass. Common
1197
+ stream-admission reconciliation still records an abandoned index group in
1198
+ capture state; its deferred index retry is not processed or erased by capture.
1199
+
1200
+ Source/default-root discovery, source capture, retained-allocation cleanup and
1201
+ their eligible retries keep their admission, dependency, backoff and fairness
1202
+ rules. Index/reset work cannot block independent healthy capture. Housekeeping
1203
+ collects only obsolete source scopes, leaving index garbage and inventory intact.
1204
+ Source-sweep renewal does not invalidate that retained index evidence; an
1205
+ enabled session subsequently reconciles its source binding and discovers all
1206
+ live/indexed names before claiming completion.
1207
+
1208
+ Append-only `complete()` performs a fresh source-only retirement audit, never
1209
+ the all-stage/index audit. It checks terminal visits and source discovery,
1210
+ refuses retirement while source/stream, cleanup or discovery admission remains,
1211
+ and publishes an intent bound to the source scope and run with no index scope.
1212
+ An unfinished or failed discovery group prevents this intent. As with full
1213
+ audits, terminal unsuccessful input visits may be renewed only after a final
1214
+ receipt, and interruption before that receipt retains the same scope/counters.
1215
+ This audit adds one capture-state transaction, paged source-row inspection and
1216
+ an optional retirement write, with no index reservation. A stopped scan provides
1217
+ no reusable proof. Its normal-worker allowance, reservation duration and actual
1218
+ synchronization costs remain hosted storage-qualification obligations.
1219
+
1220
+ Even an empty or fully visited append-only sweep remains pending/partial, or
1221
+ failed for a current-pass failure: it supplies no fresh index/all-stage proof.
1222
+ Prior success/failure history and confirmed counts remain distinct from that
1223
+ decision. The ordinary CLI uses this mode without changing public synchronous
1224
+ APIs or protected exact-home/file receipts. Explicit hooks can select this mode;
1225
+ installed service integration and hosted qualification remain separate obligations.
1226
+
1227
+ ### Fixed private command entry and issue preparation
1228
+
1229
+ `runCaptureCommand(root, options)` fixes the package worker entry and existing
1230
+ supervisor policy. Its private options require an owner, caller-bound default
1231
+ root plan, index-enabled boolean, explicit trigger and explicit retry boolean.
1232
+ Unknown options cannot supply a different worker path, executable, Node flags
1233
+ or timing/resource policy. Relative record roots resolve against the supplied
1234
+ caller cwd; source selectors still run only after worker admission. Triggers
1235
+ are manual, watch, hook, setup or service, never inferred from quiet output.
1236
+ The fixed worker requires the existing IPC/registered-lock bootstrap; direct
1237
+ invocation does not authorize capture.
1238
+
1239
+ The operation constructs the owning session, dispatches its bounded units,
1240
+ yields for fresh reset/continuation allowance and requests the actual final
1241
+ audit on idle. Only the worker publishes run facts. A finalized matching
1242
+ receipt supplies the private IPC appended/pending projection while the
1243
+ supervisor still holds the root lock; the caller neither reconstructs missing
1244
+ counts nor reads another pass's later status as its own. Operational failures
1245
+ leave admissions and unfinished receipts for replacement, while cooperative
1246
+ stops retain the existing pending continuation behavior. Transport failure may
1247
+ return without that receipt projection and must not become a zero-count success.
1248
+
1249
+ Before source enumeration/processing, the command session prepares issue rows
1250
+ in keyset pages of at most 128. Each page commits issue changes, any existing
1251
+ queued set-aside rows made ready, and its resume key together. The checkpoint
1252
+ binds owner, source sweep, run, selected formats and retry request. Replacement
1253
+ resumes committed pages; rollback keeps both the cursor and issue generations
1254
+ unchanged. Preparation supplies no capture/index counts or progress.
1255
+
1256
+ Ordinary preparation retains the synchronous native reconciliation rule:
1257
+ selected-owner, selected-format ignored issues can be removed without opening
1258
+ their source, even if the default directory disappeared. Other owners/formats
1259
+ remain untouched by that exclusion. Explicit all-input retry requires the full
1260
+ format selection and marks the root's unresolved issues as the existing public
1261
+ retry operation does, including other owners' retry intent without capturing
1262
+ under another owner. The run identity is the stable private retry generation;
1263
+ once prepared, a refusal in the same run is not marked for retry again.
1264
+ Existing source/index/cleanup failure backoff is separate and never cleared.
1265
+ Public synchronous `retrySetAside` and `resetSourceCursors` are unchanged.
1266
+
1267
+ Preparation finishes before content dispatch so newly refused inputs cannot
1268
+ re-enter its initial scan. Stop/finalization cannot start a page. Both completion
1269
+ audits refuse success/retirement while preparation is unfinished. This adds one
1270
+ capture-state transaction per page, including its checkpoint and per-issue
1271
+ generation updates; ignore loading/matching and total metadata scan/lock/sync
1272
+ costs remain hosted qualification obligations. Pages resume across workers,
1273
+ but preparation is not source enumeration or all-stage completion.
1274
+
1275
+ ### Ordinary CLI and foreground watch
1276
+
1277
+ Ordinary capture, `--sessions-only`, `--aw-only`, `--no-index` and
1278
+ `--retry-set-aside` await the fixed private entry. The CLI copies home, cwd and
1279
+ the selected native location environment into its plan. Quiet controls output,
1280
+ never trigger identity: ordinary and explicit retry use `manual`; the first
1281
+ foreground watch pass and later ticks use `watch`. Legacy quiet hook argv
1282
+ remains manual; the setup first pass explicitly uses `setup`. Quiet
1283
+ never invents hook attribution or a timeout cause. `--reset-cursors` remains reset-only;
1284
+ exact-home/file proofs and public synchronous libraries keep their paths.
1285
+
1286
+ Ordinary `--json` remains a usage error. Retry JSON retains exactly
1287
+ `{appended, pending}` from the matching worker projection. No caller reads a
1288
+ later status snapshot to fill a missing projection. Operational failure exits
1289
+ nonzero; a missing projection explicitly says the appended count is unknown.
1290
+ An `io` failure line (`capture worker failed (io): <message>`) carries the first
1291
+ failing worker's one-line diagnostic, bounded to 512 characters with control
1292
+ characters removed and parser errors reduced to their class; it reaches stderr
1293
+ only, never the published status, whose failure message stays fixed.
1294
+ A dead lock owner whose recorded start is missing, malformed or in the future
1295
+ is still reclaimed and reported on stderr, but published as `reclaimedLock: null`.
1296
+ Partial work exits zero without claiming completion. Ordinary lock overlap
1297
+ exits zero and preserves the existing receipt; recovery overlap instead reports
1298
+ that recovery was not performed and exits one. Lock reclamation, uncertain
1299
+ holders, initialization and release failures retain operator diagnostics.
1300
+ Nonquiet progress reports confirmed new turns and outcome; `index: updated`
1301
+ is emitted only for an enabled, fully completed pass, never a partial one.
1302
+
1303
+ Foreground watch retains its two-second debounce and fifteen-minute fallback.
1304
+ Its parent may enumerate selected default directories to install best-effort
1305
+ filesystem notification hints. This metadata work is proportional to profile
1306
+ inventory and is not a worker memory/allowance claim. Neither a hint nor its
1307
+ absence selects capture inputs or grants custody; only the admitted saved plan
1308
+ does that. Enumeration/installation errors leave periodic reconciliation active.
1309
+ Notifications coalesce while a pass runs; at most one pass is active, with one
1310
+ pending rerun. Stop cancels timers and future work, closes watchers, and leaves
1311
+ an active supervisor responsible for child termination/reaping and lock release.
1312
+ A failed later tick reports the error and retains a nonzero eventual exit status
1313
+ while periodic scheduling continues. It cannot strand the queue as busy.
1314
+
1315
+ The small-heap algorithm fixture invokes synchronous capture/index libraries
1316
+ directly: lowering the CLI parent's heap cannot lower its fixed-policy worker
1317
+ heap. Actual CLI fixtures separately cover worker routing, selected capture,
1318
+ append-only catch-up, recovery receipts, overlap and foreground scheduling.
1319
+ Package health and [kernel doctor delegation](#kernel-doctor-delegation) are
1320
+ implemented; health/doctor runtime qualification, fresh-audit/parent
1321
+ metadata/storage/synchronization and full hosted manager and rollback
1322
+ qualification are still required before service acceptance.
1323
+
1324
+ ### Detached hook launcher
1325
+
1326
+ `capture --hook` copies owner, home/cwd, selected native location environment,
1327
+ source selection and index mode into the fixed package supervisor's argument.
1328
+ It performs argument validation and OS spawn only: no capture lock, status
1329
+ read/write, network, default-directory resolution or source scan. Root selection
1330
+ still belongs to the admitted worker. Caller options cannot replace the Node
1331
+ executable, package entry, worker or resource policy. The supervisor starts in
1332
+ its own session/process group with all three standard streams ignored and a
1333
+ filtered environment; it does not retain harness pipes or Node preload options.
1334
+ The launcher unrefs it after the spawn event and exits. Killing the launcher
1335
+ after spawn does not terminate that detached child.
1336
+
1337
+ Exit zero means **capture launched**, not supervisor initialization, admission
1338
+ or capture completion. Nonquiet acknowledgement says so; quiet suppresses it.
1339
+ Spawn or argument failure prints one stderr line and exits one. Hook mode never
1340
+ uses exit two, including usage errors, because Claude interprets that status as
1341
+ Stop-blocking/model feedback. Ordinary usage errors outside hook mode retain
1342
+ their existing status. Proof, recovery, JSON, health, watch and reporting modes
1343
+ cannot be combined with `--hook`. Sessions-only/AW-only and append-only flags
1344
+ are copied explicitly, without resolving inputs in the launcher.
1345
+
1346
+ The detached supervisor owns the usual root lock, registered workers, failure
1347
+ handling, child reaping and lock release. Admitted worker receipts use trigger
1348
+ `hook`; overlapping launches do not create another pass or overwrite history.
1349
+ The launcher writes no receipt. Failure after OS spawn but before a worker can
1350
+ publish status may leave absent or older status, and ignored stderr cannot
1351
+ report that failure back to the completed harness call. Launch acknowledgement
1352
+ is therefore not a health check: use `capture --health` or deployment doctor.
1353
+ Hosted lifecycle qualification remains a separate gate. No numeric launch
1354
+ latency is established by this implementation.
1355
+
1356
+ Setup refreshes recognized owned Stop/SessionEnd entries to the hook entry,
1357
+ `<node> <package>/bin/capture-hook.mjs --owner <owner> --quiet --root <root>`
1358
+ (the same launch as `capture --quiet --hook`), with `async:false` and
1359
+ `timeout:10`, even when their command already matches. The hook runs its own
1360
+ entry because 0.61.0 and earlier releases do not have that file: after a
1361
+ rollback the persisted line fails to load with exit 1, which does not block
1362
+ Stop or SessionEnd, where an older `capture.mjs` would reject `--hook` with
1363
+ exit 2. Setup recognizes the `capture.mjs` forms earlier releases wrote and
1364
+ replaces them in place. The
1365
+ harness waits for the short launcher so its spawn result is ordered before
1366
+ harness shutdown; capture itself remains detached. The timeout applies to that
1367
+ launcher, not to the detached supervisor or its fixed worker allowance. The
1368
+ existing ownership recognition, duplicate groups, foreign commands and other
1369
+ fields are preserved; dry-run does not write settings. The same user
1370
+ `settings.json` (the person's `~/.claude`, or the Claude config a launch uses)
1371
+ has a second writer, oats.setup's `/oats-agent-permissions`, which merges only
1372
+ `permissions` and the `autoMode` block after keeping a `.before-oats` copy;
1373
+ setup touches only the capture `hooks` entries, so the two do not conflict. The install hint uses
1374
+ the same scheduling fields while retaining `--sessions-only --no-index`.
1375
+ This changes persisted settings from `async:true`/`timeout:120`; installing a
1376
+ CLI alone does not rewrite those settings. No release from 0.56.0 through 0.61.0
1377
+ shipped this hook migration. Periodic service conversion uses
1378
+ the separate setup gate below.
1379
+
1380
+ ### Setup first pass
1381
+
1382
+ After its requested installation steps, non-dry setup awaits the same fixed
1383
+ private supervisor as ordinary capture, with explicit `setup` trigger,
1384
+ all sources and indexing enabled. It copies caller home/cwd and native location
1385
+ environment; the admitted worker resolves source directories. The first pass
1386
+ uses the running `process.execPath`, not the stable Node pathname being written
1387
+ into future hooks or manager definitions. `--no-service` skips only manager
1388
+ files and manager inspection/actions; it does not skip this pass. `--dry-run` starts no worker and
1389
+ creates no capture store, lock or status.
1390
+
1391
+ Setup retains the foreground privacy-file preflight before lock acquisition.
1392
+ Shared foreground presentation uses only the matching worker projection for
1393
+ counts and pending state. Complete and partial return zero with their actual
1394
+ outcome; overlap returns zero with the holder/recovery and skip message without
1395
+ rewriting the holder's receipt. Operational failures and missing projections
1396
+ return nonzero; absent counts are unknown, never fabricated zero. Initialization,
1397
+ reclamation and release diagnostics retain their existing recovery guidance.
1398
+ The supervisor owns signal handling, child reaping and lock release; setup is
1399
+ not another status writer. Ordinary/retry text and JSON, protected exact-home/file
1400
+ receipts and public synchronous APIs retain their contracts.
1401
+
1402
+ First-pass routing follows the service migration gate when service installation
1403
+ is requested. It does not provide health/doctor acceptance or hosted
1404
+ Linux/manager/rollback qualification. The shared presentation
1405
+ adds no status transaction or counter reconstruction; existing source/audit
1406
+ allowance, reservation and actual storage/synchronization costs remain gates.
1407
+
1408
+ ### Finite service entry and periodic definitions
1409
+
1410
+ The private `capture-service-runner.mjs` entry takes one serialized request with
1411
+ explicit record root, owner and default-root plan. Relative record roots resolve
1412
+ against the copied caller cwd. Home, cwd and the four native location values
1413
+ come from that plan rather than the service process's ambient source selection.
1414
+ It requires all formats and fixes indexing enabled, retry preparation off and
1415
+ trigger `service`; the request cannot select an executable, worker or resource
1416
+ policy. After validation it reads the privacy policy before acquiring a lock,
1417
+ then uses the fixed supervisor and shared foreground presentation. Complete,
1418
+ partial, overlap, operational failure and absent receipt retain the setup/manual
1419
+ meanings above. There is no second status writer, repeated pass loop or manager
1420
+ operation in this entry.
1421
+
1422
+ `capture-service-definition.mjs` constructs definitions without filesystem or
1423
+ manager access. Both formats carry `oats-turn-record-service:1`. The recorded
1424
+ absolute Node runs the fixed package entry with the explicit request as one
1425
+ argument, with XML/systemd-specific escaping and refusal of values the selected
1426
+ manager cannot represent safely. No shell evaluates the request. XML preserves
1427
+ literal carriage returns through character references; systemd arguments escape
1428
+ both specifier and environment expansion syntax. Unsupported executable quote
1429
+ or backslash spellings are refused for systemd rather than silently rewritten.
1430
+
1431
+ The macOS definition names `ai.aweb.turn-record-capture`, uses `RunAtLoad` and
1432
+ `StartInterval` 900, and has no `KeepAlive` or watch argument. Linux pairs a finite
1433
+ `turn-record-capture.service` (`Type=exec`, `MemoryMax=2G`, `RuntimeMaxSec=300`, no
1434
+ restart loop) with `turn-record-capture.timer` (`OnBootSec=1min`,
1435
+ `OnUnitActiveSec=15min`). A timer/schedule is not a permanent worker PID.
1436
+
1437
+ Setup uses these definitions through the migration gate below. Constructing a
1438
+ definition alone proves neither installation nor enabled/registered scheduling.
1439
+ Source-only argument-decoding fixtures do not replace hosted manager tests;
1440
+ this entry introduces no additional capture-state transactions beyond the
1441
+ existing fixed command path.
1442
+
1443
+ ### Setup service migration
1444
+
1445
+ `setup --root <dir> --owner <name>` persists the resolved root and owner in
1446
+ hooks and the service request, alongside explicit caller home/cwd/native
1447
+ location selection. The recorded stable Node is used for future launches;
1448
+ the first pass still uses the running Node. These are user-manager definitions,
1449
+ not deployment automation timers. No external wrapper is removed.
1450
+
1451
+ The setup coordinator prepares hook edits in memory, then
1452
+ `capture-service-install.mjs` snapshots every named service target and inspects
1453
+ applicable manager state before any service/file/hook/capture mutation.
1454
+ Snapshots retain regular-file bytes and identity or the symlink's own identity
1455
+ and target, plus ancestor identities and explicit missing-ancestor records. Reads are limited to 1 MiB per target;
1456
+ unknown reads, nonregular targets and unsupported manager output refuse.
1457
+ `capture-service-ownership.mjs` parses only supported marked templates and
1458
+ the actual unmarked direct-Node `capture.mjs --watch --owner` templates with
1459
+ their known structure. Paths may name a moved or missing install; recognition
1460
+ does not execute them. A basename, shell mention, wrapper, unsupported marker,
1461
+ malformed file or extra directive is not ownership.
1462
+
1463
+ Foreign files or registered identities produce `E_CAPTURE_SERVICE_FOREIGN`;
1464
+ installed disabled/masked state produces `E_CAPTURE_SERVICE_DISABLED`, whose
1465
+ message states the manager state observed. It does not claim the operator
1466
+ disabled the unit: a timer that setup wrote but failed to enable reads as
1467
+ disabled too. Both refuse before mutation and print quoted recovery commands
1468
+ in the user-facing form preserving the selected owner/root: `oats setup …`
1469
+ when a node was handed in through the kernel environment (`OATS_NODE_BIN`,
1470
+ which `oats setup` sets and instance shells also carry), otherwise
1471
+ `turn-record setup …`; both commands work and record the same node: explicitly choose
1472
+ `--replace-service`, or `--no-service` to preserve the manager configuration.
1473
+ Other setup failures print the same form of retry command; none names the
1474
+ running Node or the package-internal setup script. New absent definitions
1475
+ are not disabled. A macOS `launchctl print-disabled` entry for the label is the
1476
+ exception: launchd keeps that override after the plist is gone and setup never
1477
+ writes one, so it is operator state and refuses even when the named plist is
1478
+ absent. Setup reads only the disabled-services block of that output, accepting
1479
+ both `true`/`false` and `disabled`/`enabled` values; any other entry refuses. Replacement intent never waives unknown state, read errors,
1480
+ unsupported drop-ins, backup failure or identity changes. On macOS, a
1481
+ registration of `ai.aweb.turn-record-capture` loaded from any plist other than
1482
+ the named one is foreign and is refused naming that path, even with
1483
+ `--replace-service`; setup never unlinks or boots out that file. `--no-service`
1484
+ bypasses service target reads and manager calls entirely. `--dry-run` reads
1485
+ target files but writes nothing and calls no manager; unloaded/disabled state
1486
+ is explicitly unexamined; a dry run also names a present pending-activation
1487
+ marker and whether a run would retry it or remove it as stale.
1488
+
1489
+ Apply rechecks file/ancestor identities and manager ownership/enablement.
1490
+ Replaced bytes or symlinks are saved nonoverwriting in a reported datable
1491
+ `<root>/service-backups/<date>-<unique-id>/` directory. Symlink backups
1492
+ preserve the link instead of reading or removing an external wrapper target.
1493
+ An ancestor absent at preflight must remain absent until this apply creates it.
1494
+ Creation proceeds one directory at a time without recursive adoption of an
1495
+ existing path; each created non-link directory's identity is retained in a
1496
+ per-apply map shared by subsequent service and hook writes. Newly introduced
1497
+ directories or links are not accepted as extra ancestry. Existing ancestor
1498
+ identities and observed symlink targets remain binding. The extra metadata
1499
+ checks and directory creation do not establish an atomic filesystem operation.
1500
+ Each write uses a temporary file and another identity check before rename;
1501
+ cleanup also refuses changed ancestry instead of unlinking through a redirected
1502
+ path. An interrupted/refused write can leave its original temporary file.
1503
+ An expected manager unmask can remove only the saved named `/dev/null` link;
1504
+ other observed replacements refuse. These checks detect observed races, not
1505
+ an OS-wide atomic transaction over files and managers.
1506
+
1507
+ On macOS, changed/legacy registered jobs are booted out before replacement;
1508
+ missing registration is bootstrapped. An unchanged enabled registered periodic
1509
+ job receives no restart. On Linux, conversion stops the timer before the
1510
+ service, disables the legacy service's boot activation, writes the finite
1511
+ service and timer, reloads and enables/starts the timer. Explicit replacement
1512
+ can unmask only the named units. An unchanged enabled active timer preserves
1513
+ an in-flight pass; an inactive finite service between ticks is normal.
1514
+ Setup verifies registration/enablement and expected definitions before saying
1515
+ “periodic capture scheduled (every 15 minutes)”. It does not promise a permanent
1516
+ PID or infer worker completion. Manager and setup first passes can overlap;
1517
+ the capture root lock admits one.
1518
+
1519
+ Manager commands have finite time/output limits; completed mutation commands
1520
+ and definition writes are reported before subsequent steps. Failure reports the action,
1521
+ reason and recovery without inventing scheduling or capture results. Apply
1522
+ can leave backups, stopped jobs or written definitions before a later failure;
1523
+ there is no global atomic rollback. Inspect the reported state and rerun.
1524
+
1525
+ **Pending activation.** Before its first replacement backup, manager change or
1526
+ definition write, setup writes a private (0600) pending-activation marker,
1527
+ `<root>/capture-service-pending.json`, the way it writes every setup target:
1528
+ against what preflight saw, refusing a marker or record root that was replaced,
1529
+ linked or created since (`setup target changed since preflight` / `setup target
1530
+ parent changed since preflight`; re-run setup). It removes the marker only once
1531
+ activation is verified (`service: activation verified; pending-activation marker removed`).
1532
+ A failure in between leaves it. On a rerun, a loaded, unmasked disabled unit
1533
+ beside setup's own marked definitions and a live marker is setup's own
1534
+ unverified activation (on Linux, the timer a failed `enable --now` left): it is
1535
+ retried with no flag. Without the marker, the same state is an operator's
1536
+ disable and is refused with `E_CAPTURE_SERVICE_DISABLED` and both remedies. A
1537
+ marker with no unit, or beside a unit without setup's mark, is stale: setup
1538
+ removes it and names it, and it authorizes nothing. A verified activation,
1539
+ including an explicit `--replace-service`, removes the marker. The package has
1540
+ no service uninstall command. On macOS an unfinished activation leaves the
1541
+ plist unregistered, which a plain rerun already bootstraps; a launchd disable
1542
+ entry is always an operator's. `capture --health` reports a present marker as
1543
+ `capture-service-pending` ([offline diagnosis](#offline-installation-and-run-diagnosis)).
1544
+
1545
+ **Service failure.** Preflight refusals (foreign, operator-disabled,
1546
+ indeterminate state) change nothing. When apply fails after preflight passed,
1547
+ setup still writes the hooks and runs the bounded first pass, then exits 1:
1548
+ capture is never skipped for a service failure, and the failure is never
1549
+ hidden in the exit status. Capture receipts retain their own failure and
1550
+ partial meanings. A rerun after the remedy changes nothing that is already
1551
+ right; it only completes the activation.
1552
+
1553
+ **Setup summary.** Once setup starts changing things (every run but
1554
+ `--dry-run` and preflight refusals), it ends with one setup summary on stdout:
1555
+ fixed labels, one item per line, in this order on every run. With a nonzero
1556
+ exit it is the setup failure summary.
1557
+
1558
+ ```
1559
+ setup summary:
1560
+ status: complete | incomplete (exit 1)
1561
+ hooks written: <settings path> (one line per file written, or "none")
1562
+ first capture pass: appended <n>, pending yes|no | skipped: another pass holds the record root | failed: <reason> | not run
1563
+ service: scheduled | failed: <reason> | skipped (--no-service) | no service template for <platform> | not changed
1564
+ service changed: <change> (after a service failure: one line per change it had already made)
1565
+ remedy: none | rerun <oats|turn-record> setup --owner <owner> --root <root> [flags] | inspect <oats|turn-record> capture --health --json, then rerun …
1566
+ ```
1567
+
1568
+ A caller reads a nonzero exit with this block as "these changes were made",
1569
+ never as "nothing happened". After a service failure, `service changed` lines
1570
+ name, in order, what the failed apply had already changed: the replacement
1571
+ backup directory, each manager action completed (units stopped, disabled or
1572
+ unmasked, a job booted out), each definition written, and the pending-activation
1573
+ marker written or a stale one removed. Setup has no `--json` mode.
1574
+
1575
+ Fake-manager and isolated CLI fixtures exercise this ordering and refusal
1576
+ contract. Real-manager cases live in `test/capture-service-real-darwin.test.mjs`
1577
+ (launchd) and `test/capture-service-real-linux.test.mjs` (systemd --user). They
1578
+ run only when `GITHUB_EVENT_NAME` is `workflow_dispatch`, `GITHUB_WORKFLOW`
1579
+ names their own workflow ("macOS tests" or "Linux tests") and the platform
1580
+ matches, and skip with that reason everywhere else, pull-request CI and any
1581
+ developer machine included; a skip is not evidence. They cover the real
1582
+ `print-disabled` output against setup's parser (first), first install,
1583
+ conversion from an owned legacy watcher with no surviving watcher, an
1584
+ unchanged rerun preserving an active pass, a changed definition taking effect,
1585
+ the #1099 failed-enable rerun, unloaded recovery, the next idle trigger, the
1586
+ effective `MemoryMax`/`RuntimeMaxSec`, and missing, failing or signalled
1587
+ managers. The idle-trigger case uses the definition's internal interval seam
1588
+ (default and production value 900 seconds; no CLI or setting reaches it).
1589
+ The qualification harness (`test/capture-qualify-*-linux.test.mjs`, helpers in
1590
+ `test/fixtures/qualify*.mjs`) runs under the same guard on the dispatched
1591
+ "Linux tests" runner only. It measures, and reports as JSON lines and tables,
1592
+ first upgrade and no-op at 1,300 and 3,000 synthetic streams (scaled against
1593
+ a population of about 1,300 streams and 8.4 GB of journals by a stated factor), an
1594
+ operator-shaped first upgrade at both counts with most bytes in sessions over
1595
+ 8 MiB on the retained path, caps-off
1596
+ memory scaling, the outgoing 0.61.0 and 0.53.0 releases side by side,
1597
+ 8/16/22.3 MB journal frames and near-limit records under the capped worker,
1598
+ Codex in-prefix recovery, old-new-old-new rollback with released 0.61.0, the
1599
+ rollback of the hooks and the periodic service to 0.61.0 (the hook entry exits
1600
+ 1, a service start fails, and 0.61.0's setup restores its watcher and hooks),
1601
+ and hook launcher latency. It runs the production operation under the real
1602
+ supervisor through the existing worker seam with the test counting patches;
1603
+ its assertions are structural, and its numbers are evidence only from an
1604
+ executed run.
1605
+ Quoting qualification remains a hosted obligation.
1606
+ Health/doctor runtime qualification, final schema delivery and full service
1607
+ acceptance remain separate; audit allowance/reservation/storage/synchronization
1608
+ gates are unchanged.