@awebai/oats 0.61.0 → 0.63.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 (90) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +27 -12
  3. package/docs/capabilities.md +1 -1
  4. package/docs/desktop-cli-api.md +30 -2
  5. package/docs/execution-targets.md +89 -4
  6. package/docs/implementation.md +2 -1
  7. package/docs/named-test-runs.md +382 -0
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-lane.md +13 -0
  11. package/docs/release-notes/v0.62.0.md +223 -0
  12. package/docs/release-notes/v0.63.0.md +135 -0
  13. package/docs/souls-and-instances.md +6 -1
  14. package/docs/upgrading.md +135 -11
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +73 -23
  17. package/lib/doctor-capture.mjs +35 -0
  18. package/lib/session-viewer.mjs +86 -7
  19. package/lib/tree-copy.mjs +188 -7
  20. package/package-catalog.json +1 -1
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/record/README.md +87 -13
  24. package/packages/record/bin/capture-hook.mjs +8 -0
  25. package/packages/record/bin/capture.mjs +200 -139
  26. package/packages/record/bin/recall.mjs +8 -3
  27. package/packages/record/bin/setup.mjs +116 -225
  28. package/packages/record/bin/turn-record.mjs +2 -2
  29. package/packages/record/docs/capture-service.md +1527 -28
  30. package/packages/record/docs/capture-status.schema.json +429 -12
  31. package/packages/record/lib/capture-admission.mjs +82 -0
  32. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  33. package/packages/record/lib/capture-aw.mjs +31 -12
  34. package/packages/record/lib/capture-budget.mjs +31 -0
  35. package/packages/record/lib/capture-cc.mjs +39 -6
  36. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  37. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  38. package/packages/record/lib/capture-command-operation.mjs +37 -0
  39. package/packages/record/lib/capture-command-output.mjs +62 -0
  40. package/packages/record/lib/capture-command-worker.mjs +6 -0
  41. package/packages/record/lib/capture-command.mjs +65 -0
  42. package/packages/record/lib/capture-completion.mjs +152 -0
  43. package/packages/record/lib/capture-context.mjs +50 -0
  44. package/packages/record/lib/capture-default-roots.mjs +30 -0
  45. package/packages/record/lib/capture-discovery.mjs +114 -0
  46. package/packages/record/lib/capture-failures.mjs +45 -0
  47. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  48. package/packages/record/lib/capture-health-installation.mjs +117 -0
  49. package/packages/record/lib/capture-health.mjs +116 -0
  50. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  51. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  52. package/packages/record/lib/capture-hook.mjs +26 -0
  53. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  54. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  55. package/packages/record/lib/capture-index-reset.mjs +110 -0
  56. package/packages/record/lib/capture-index-work.mjs +77 -0
  57. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  58. package/packages/record/lib/capture-issues.mjs +15 -2
  59. package/packages/record/lib/capture-lock.mjs +137 -17
  60. package/packages/record/lib/capture-native-unit.mjs +322 -0
  61. package/packages/record/lib/capture-pass.mjs +116 -0
  62. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  63. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  64. package/packages/record/lib/capture-retry.mjs +102 -0
  65. package/packages/record/lib/capture-run.mjs +125 -0
  66. package/packages/record/lib/capture-scratch.mjs +12 -3
  67. package/packages/record/lib/capture-service-definition.mjs +104 -0
  68. package/packages/record/lib/capture-service-install.mjs +362 -0
  69. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  70. package/packages/record/lib/capture-service-runner.mjs +18 -0
  71. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  72. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  73. package/packages/record/lib/capture-source-queue.mjs +199 -0
  74. package/packages/record/lib/capture-source-work.mjs +85 -0
  75. package/packages/record/lib/capture-state.mjs +16 -71
  76. package/packages/record/lib/capture-status.mjs +171 -0
  77. package/packages/record/lib/capture-supervisor.mjs +136 -0
  78. package/packages/record/lib/capture-watch.mjs +32 -0
  79. package/packages/record/lib/capture-work-session.mjs +241 -0
  80. package/packages/record/lib/capture-worker.mjs +74 -0
  81. package/packages/record/lib/derived-state.mjs +58 -17
  82. package/packages/record/lib/file-lines.mjs +22 -6
  83. package/packages/record/lib/formats.mjs +4 -3
  84. package/packages/record/lib/index-capture.mjs +97 -0
  85. package/packages/record/lib/index-db.mjs +121 -66
  86. package/packages/record/lib/index-reset.mjs +19 -0
  87. package/packages/record/lib/store.mjs +46 -14
  88. package/packages/record/lib/transcript-prefix.mjs +125 -0
  89. package/skills/oats-getting-started/SKILL.md +1 -1
  90. package/docs/macos-test-runs.md +0 -246
@@ -0,0 +1,135 @@
1
+ # OATS 0.63.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.62 Desktop refuses a 0.63.0 CLI. The
9
+ 0.63.0 Desktop accepts OATS CLIs `>=0.26.0 <0.64.0`.
10
+
11
+ - **The official catalog moves oats.framework 1.13.1 → 1.13.2** (oats.core
12
+ 2.6.4, see Provider updates). The other packages are unchanged. A
13
+ deployment takes it by moving its `oats.framework` pin and running
14
+ `oats sync`. Only new spawns use it.
15
+
16
+ ## Added
17
+
18
+ - `oats session inspect --json` reports `running` on every successful result,
19
+ advertised as `session-inspect-running`. Wherever inspect answers, it is the
20
+ liveness `oats status --json` reports for the row, by the same rule over the
21
+ same pane observation: `true` for a live harness, behind a wrapper shell included, and `false` for
22
+ a fallback shell, an absent or dead pane, a missing home or a home that never
23
+ launched. `state` and its enum are unchanged, and a failed observation is
24
+ still an error, never `false`; that includes a tmux server that is gone,
25
+ which status reads as `running: false` and inspect answers with
26
+ `E_SESSION_UNAVAILABLE`. `running` is activity at the session
27
+ endpoint, not health, readiness, busy or idle, or proof of which executable
28
+ runs. `--server` relays the execution host's answer; an older host's answer
29
+ has no `running`. See
30
+ [inspect, input and attach](../execution-targets.md#inspect-input-and-attach) (#1346).
31
+ - `E_RUNTIME_AUTHORITY_MISMATCH` (instance metadata that disagrees with the
32
+ independent session receipt, from a session command or `oats retire`) carries
33
+ `details.fields`: which of `launched`, `tmux.session`, `tmux.window` and
34
+ `tmux.socket` differ, never their values. A missing or invalid receipt is
35
+ still `E_RUNTIME_ENDPOINT_UNKNOWN`, without fields, and every refusal still
36
+ happens before any pane or process is read (#1346).
37
+
38
+ ## Changed
39
+
40
+ - A retire that refuses because the worktree recovery copy disagrees with the
41
+ source (`E_WORK_PRESERVATION_FAILED`, `worktree recovery verification
42
+ disagreed with the source`) now says where. `details.recoveryDisagreement`
43
+ lists up to 20 escaped relative paths, each with a fixed kind (`missing`,
44
+ `extra`, `type`, `mode`, `link-target`, `file-content`), and the message
45
+ names the first 5. The refusal is still decided by the exact digest
46
+ comparison, and nothing else changes: no hook runs, nothing is deleted and
47
+ the staged copy is removed as before. The report is read afterwards, from
48
+ the source and the copy as they are then, so it is a diagnosis, not a
49
+ verdict. Its search is bounded (entries, bytes read and 5 seconds) and says
50
+ when it stopped early. No content, link target or absolute path is
51
+ reported. See [the retire errors](../desktop-cli-api.md#retire) (#1360).
52
+
53
+ - **OATS Desktop accepts an `oats` CLI 0.63.x.** Its band is now
54
+ `>=0.26.0 <0.64.0`. 0.63 adds no new gate on the band: the Desktop does
55
+ not read `running` on `session inspect --json` or the mismatch's
56
+ `details.fields`, and it already reads a `launched` event's
57
+ `launchConfig: null` as no configuration (#1367).
58
+
59
+ ## Fixed
60
+
61
+ - A `session start|restart` that selects the bare harness from a home
62
+ recorded with a named configuration (for example `--launch-config none
63
+ --harness codex` on a home started with a claude configuration) now records
64
+ `launchConfig: null` everywhere. The launch itself, `instance.json` and the
65
+ command's answer already said so. But the session's `launched` event and the
66
+ restart receipt (`.oats-restart.json` `next.launchConfig`) named the earlier
67
+ configuration. So did the `launched` event an adoption records for a start
68
+ whose metadata write failed. Each now takes the name from the recipe the
69
+ start launched, its pending receipt's for an adoption. Only a receipt
70
+ without a recipe still falls back to the recorded one. Selection is
71
+ unchanged: `--launch-config none` is the bare harness, as
72
+ [launch configurations](../configuration.md#launch-configurations) say.
73
+ This is the kernel half of #1345. The provider's delivery for the selected
74
+ harness is tracked separately.
75
+
76
+ - SIGTERM or SIGINT now stops a capture pass cooperatively, where the worker was
77
+ killed at once before. The supervised pass starts no further worker, asks the
78
+ current worker to stop at its next unit boundary through the lock owner
79
+ record, and kills and reaps the worker if it has not stopped after a 5-second
80
+ grace, capped by the pass's deadline. The worker writes its own
81
+ `failed`/`interrupted` receipt and keeps its committed counts and the previous
82
+ `lastSuccess`. A killed worker leaves its `running` receipt, which the next
83
+ pass records as interrupted. The worker also catches a signal sent to the
84
+ caller's whole process group (Ctrl-C, `timeout`, a service manager), so it
85
+ is not killed mid-unit. An interrupted run's failure message now reads
86
+ "Capture execution was interrupted.", for a stop and for a later recovery
87
+ alike. The lock is released and the command exits 1.
88
+ `capture --home`, `--file` and `--reset-cursors` still run in the calling
89
+ process. They now stop at their safe points (before and after taking the
90
+ lock, before each format's batch, before the index update, and after the
91
+ work before answering), answer their
92
+ existing `failed` receipt with `capture interrupted by SIGTERM` and a
93
+ confirmed `appended`, release the lock and exit 1. Discovery, a format's
94
+ batch and the index update cannot be preempted, so a signal waits for the
95
+ segment it arrived in. See
96
+ [stopping capture](../../packages/record/docs/capture-service.md#stopping-capture-and-the-lock-owner-record) (#1347).
97
+ - The capture lock's `owner.json` now says who took it: `command`, `caller`
98
+ (`entry` and `trigger`) and `ppid`. These are fixed labels and process facts,
99
+ never argv or environment. They are diagnostic only. Records from earlier
100
+ releases are read and reclaimed exactly as before (#1347).
101
+
102
+ - The index update after `capture --home` or `--file` now skips streams it can
103
+ prove current. A stream is skipped when its validation checkpoint names the
104
+ journal's current version and its search cursor agrees with that checkpoint.
105
+ A skipped stream takes no stream lock, no validation and no `capture.db`
106
+ connection of its own. The pass opens `capture.db` once instead of twice per
107
+ stream, so an unchanged record no longer costs two lock cycles and two
108
+ database opens for every stream. Work now follows the streams that changed
109
+ and their new bytes. Backlog from `--no-index` passes, streams changed by
110
+ other writers, and missing or inconsistent evidence are still validated
111
+ under the stream lock, and a stale union still resets and is rebuilt. See
112
+ [the index update](../../packages/record/docs/capture-service.md) (#1348).
113
+
114
+ - A retire's recovery copy now keeps each symbolic link's own mode. The copy
115
+ recreated a link with its exact target but the platform's default mode,
116
+ while the verification digest holds the link's mode, so on macOS a worktree
117
+ whose ignored dependency tree has links of another mode (for example
118
+ `node_modules/.bin` links at 0700) was refused with "worktree recovery
119
+ verification disagreed with the source". The link is now given its source's
120
+ mode with lchmod, on the link itself, never on its target. Where the
121
+ platform cannot set a link's mode and the new link's differs, the copy is
122
+ refused rather than verified against another digest, and no target
123
+ changes. Spawn's copies of skills and the other recovery copies use the
124
+ same copier. See
125
+ [what a recovery copy carries](../souls-and-instances.md#retire) (#1360).
126
+
127
+ ## Provider updates
128
+
129
+ - **oats.framework 1.13.2, oats.core 2.6.4: `/oats-operate` reads inspect's
130
+ `running`** ([#1346](https://github.com/awebai/oats/issues/1346)). From OATS
131
+ 0.63.0 (feature `session-inspect-running`), the skill says what `running` on
132
+ `oats session inspect --json` means: activity at the session endpoint, not
133
+ health or readiness. A failed inspect is an error, never `running: false`.
134
+ Without the field, `state: unknown` on a successful result reads as running.
135
+ Text only: the capability's floor (`compatibility.oats`) is unchanged.
@@ -570,7 +570,12 @@ parses it, so it copies the files Git reads:
570
570
  and `info/exclude`) and the settings that change what `git status` reports
571
571
  (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
572
572
  `core.symlinks`, `core.autocrlf`, `core.eol`);
573
- - the bytes and the permission bits of its files, Git metadata left out.
573
+ - the bytes and the permission bits of its files, Git metadata left out, and
574
+ each symbolic link as itself: its raw target and its own permission bits.
575
+ A link is recreated with its target and then given its source's mode with
576
+ lchmod, on the link, never on what it points at; a platform that cannot
577
+ set a link's mode (no lchmod) refuses the copy where the new link's mode
578
+ differs, rather than keep a copy that differs from its source.
574
579
 
575
580
  The rule is that the work is unchanged only if everything its copy would
576
581
  carry is equal byte for byte, and anything that cannot be compared exactly
package/docs/upgrading.md CHANGED
@@ -74,6 +74,102 @@ Versions are compared as semver, so a prerelease is below its release:
74
74
  no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
75
75
  installed over it.
76
76
 
77
+ ## Capture service release order
78
+
79
+ The bounded periodic capture service (service A) is **not shipped in
80
+ [0.56.0](release-notes/v0.56.0.md) through [0.61.0](release-notes/v0.61.0.md)**
81
+ ([0.57.0](release-notes/v0.57.0.md), [0.57.1](release-notes/v0.57.1.md),
82
+ [0.58.0](release-notes/v0.58.0.md), [0.59.0](release-notes/v0.59.0.md) and
83
+ [0.60.0](release-notes/v0.60.0.md) included). Those releases retain the
84
+ existing capture watcher, and upgrading to any of them does not install the
85
+ periodic service. The capture algorithms and recovery commands already
86
+ released do not prove that migration happened.
87
+
88
+ For those released versions, follow their own Upgrade sections and the steps
89
+ above. In particular, install the target Desktop before the CLI: the 0.61.0
90
+ Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
91
+
92
+ Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
+ release. Read 0.62.0's Upgrade section and keep this order: install the
94
+ Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
+ `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`), then that
96
+ release's CLI and matching pi bridge. Only **after
97
+ installing that CLI**, run its setup conversion once per user on each host,
98
+ from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
99
+ watcher is replaced by the periodic service; foreign or disabled definitions
100
+ require an explicit operator choice. The conversion accepts `setup --root <dir>`
101
+ and `--replace-service`; refusal prints a quoted command preserving owner/root.
102
+ Choose `--no-service` to skip service files and manager operations entirely.
103
+ `--dry-run` writes nothing and calls no manager, so disabled/registered state
104
+ remains unexamined. Replaced definitions are backed up nonoverwriting under
105
+ the selected record root; retain the reported backup and inspect any partial
106
+ apply error before retrying. Replacement never waives unknown state or changed
107
+ identities. A CLI install alone is not conversion.
108
+ Use that release's capture health and doctor checks after conversion. Do not
109
+ run the service diagnostics or conversion flags as prerequisites on 0.61.0 or
110
+ older binaries, which do not have them, or assume that an older health command
111
+ proves periodic activation. The [capture reference](../packages/record/docs/capture-service.md)
112
+ distinguishes the implemented foundation from an installed service.
113
+
114
+ The first capture after that upgrade rebuilds the record root's derived
115
+ capture state and index from the existing journals: it validates each journal,
116
+ proves each session's captured prefix against a fresh staged copy of its
117
+ source, and indexes every record. This cost is paid once, and it grows linearly with the
118
+ number of streams and their bytes. On the hosted Linux runner (4 CPUs) it took
119
+ about 20 seconds per 1,000 streams of typical small sessions, and about 4
120
+ minutes per GB of journals overall: a record of about 1,300 streams and 8 GB of
121
+ journals needs roughly half an hour of capture work in about seven bounded
122
+ passes, which under the service's 15-minute interval is one to two hours of
123
+ elapsed time. A later pass over unchanged sessions does no content work and
124
+ costs about 2 ms per stream on the same runner (about 3 s at 1,300 streams),
125
+ growing linearly with the number of streams. Each pass stops at its deadline. A first upgrade that is interrupted or reaches its deadline resumes
126
+ from its durable checkpoints on the next pass (journal validation, index
127
+ cursors, the prefix proof and the staged copies of sources over 8 MiB) rather
128
+ than starting over; a smaller session's staged copy is made again. Reducing the
129
+ repeated source reads of small sessions is tracked in
130
+ [#1337](https://github.com/awebai/oats/issues/1337).
131
+
132
+ **Going back to 0.61.0.** Until the steps below are done, two things fail at
133
+ every trigger:
134
+
135
+ - each `Stop` and `SessionEnd` hook this release's setup wrote exits 1,
136
+ because its command names `bin/capture-hook.mjs`, a file 0.61.0 does not
137
+ have; Claude does not block on it;
138
+ - the periodic service's start fails every 15 minutes: on Linux
139
+ `turn-record-capture.timer` starts a unit whose runner 0.61.0 does not have,
140
+ and on macOS the `ai.aweb.turn-record-capture` job fails the same way.
141
+
142
+ To go back:
143
+
144
+ 1. Install 0.61.0: `npm install -g @awebai/oats@0.61.0`.
145
+ 2. From the same user's shell, run 0.61.0's setup with the same owner:
146
+ `oats setup --owner <owner>`. It installs its capture watcher (on Linux as
147
+ `turn-record-capture.service`, on macOS under the same
148
+ `ai.aweb.turn-record-capture` label) and adds its own `Stop` and
149
+ `SessionEnd` hooks. 0.61.0's setup takes no `--root` (it refuses one):
150
+ everything it starts records into `$TURN_RECORD_ROOT` as that process sees
151
+ it, else `~/.turn-record`. Its first pass runs with setup's environment, so
152
+ `TURN_RECORD_ROOT=<root> oats setup --owner <owner>` points that pass at
153
+ another root; its hooks see Claude's environment; its watcher's service
154
+ sets none, so the watcher gets only the user manager's environment and
155
+ records into `~/.turn-record` unless the user manager itself sets
156
+ `TURN_RECORD_ROOT`. With any other root, the watcher and the record you
157
+ were using part ways.
158
+ 3. In each `~/.claude*/settings.json`, delete the hook entries under `Stop` and
159
+ `SessionEnd` whose command names `capture-hook.mjs`: 0.61.0's setup does not
160
+ recognize them and leaves them in place.
161
+ 4. On Linux, remove the timer:
162
+ `systemctl --user disable --now turn-record-capture.timer`, then delete
163
+ `~/.config/systemd/user/turn-record-capture.timer` and run
164
+ `systemctl --user daemon-reload`.
165
+
166
+ After going back to 0.61.0, its `oats capture --health` reports the capture
167
+ status file this release wrote as invalid, and a capture by 0.61.0 clears the
168
+ run history in that file. A later capture with this release writes a fresh
169
+ status. 0.61.0 ignores the captured frontier this release keeps in an AW log's
170
+ cursor during a rescan and drops it when it rewrites that cursor; it reads that
171
+ log without a record limit, so nothing is lost.
172
+
77
173
  ## Which pi folders
78
174
 
79
175
  pi keeps its packages in one folder: `~/.pi/agent`, or the folder
@@ -197,6 +293,20 @@ at the version are left alone.
197
293
 
198
294
  ## What `oats doctor` reports
199
295
 
296
+ From the next release after 0.61.0 (service A), deployment doctor also delegates once to
297
+ the record package's offline health reader. Text and JSON carry its diagnosis
298
+ as existing warning rows. `capture-health-unavailable` means the bounded command
299
+ or reader failed, timed out, exceeded its output limit or returned an invalid
300
+ envelope; inspect `oats capture --health --json` with the same root environment.
301
+ Doctor retains its warning exit semantics. `TURN_RECORD_ROOT` selects the root,
302
+ otherwise the caller's `~/.turn-record` applies; `--soul` remains composition-only.
303
+ The kernel adds no status/DB/freshness parser or manager probe. Remedies use
304
+ `oats`, preserving literal user paths and existing owner guidance. Neither no
305
+ warnings nor definition bytes prove enabled scheduling. See the
306
+ [owning boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation)
307
+ for reader/transport limits and remaining qualification. This does not change
308
+ the released 0.56–0.61 upgrade prerequisites above.
309
+
200
310
  `oats doctor` prints one warning per folder whose bridge is not the kernel's
201
311
  version, naming the folder and why it is looked at:
202
312
 
@@ -233,9 +343,9 @@ under npm's global prefix (`npm prefix -g`).
233
343
  removes the kernel with it. Four things name that kernel by its path: each
234
344
  instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
235
345
  of a Claude instance, the host timer's unit, and what `oats setup` installs
236
- (the turn record's capture hooks and its watcher, which name the capture
237
- script inside the kernel). OATS cannot make a path inside a Node version
238
- outlast that version.
346
+ (the turn record's capture hooks and its periodic capture service, which
347
+ name the capture scripts inside the kernel). OATS cannot make a path
348
+ inside a Node version outlast that version.
239
349
 
240
350
  Both layouts can exist on one host: check the prefix in the shell that
241
351
  installs the CLI.
@@ -248,7 +358,7 @@ record the `node` that runs them, by one rule
248
358
  - **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
249
359
  the `node` running the kernel. `brew upgrade node` repoints it, so the
250
360
  recorded path outlasts the upgrade: the hooks, the timer and the capture
251
- watcher need nothing done.
361
+ service need nothing done.
252
362
  - **Otherwise**, a `node` on `PATH` that is the same file as the one running
253
363
  the kernel. With mise that is the version's own install, which does not
254
364
  outlast the version (other version managers were not measured).
@@ -258,18 +368,32 @@ record the `node` that runs them, by one rule
258
368
 
259
369
  **What `oats setup` records is in your own files, not in an instance home:**
260
370
  the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
261
- of the user who ran it, and the capture watcher's unit
262
- (`~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` on macOS,
263
- `~/.config/systemd/user/turn-record-capture.service` on Linux). No spawn,
264
- start or restart writes them: only `oats setup` run again does, and it
265
- replaces its own hooks and unit, it does not add a second one.
371
+ of the user who ran it, and the periodic capture service's definitions. On
372
+ macOS that is `~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist`, a
373
+ launchd job with `StartInterval` 900; on Linux, a finite
374
+ `~/.config/systemd/user/turn-record-capture.service` started by
375
+ `turn-record-capture.timer` every 15 minutes. Each start runs one bounded
376
+ capture pass and exits. No spawn, start or restart writes them: only
377
+ `oats setup` run again does. It replaces its own hooks and definitions, and
378
+ converts a capture watcher an earlier setup installed; it does not add a
379
+ second one. A definition it does not recognize as its own, or one found
380
+ disabled or masked, is refused with a printed choice: `--replace-service` to
381
+ replace it, or `--no-service` to keep it and skip service files and manager
382
+ calls. One exception on macOS: the capture label registered from another plist
383
+ is refused even with `--replace-service`; remove that registration yourself,
384
+ or keep it with `--no-service`. A service manager failure does not skip
385
+ capture: setup still writes the hooks and runs the first pass, exits 1 and
386
+ prints a setup summary of what changed; rerun the printed command, which
387
+ finishes setup's own activation without a flag. Until then `oats doctor` warns
388
+ `capture-service-pending`. `--dry-run` prints what setup would do and changes
389
+ nothing ([Capture service release order](#capture-service-release-order)).
266
390
 
267
391
  Once the recorded `node` no longer exists (an old version removed under a
268
392
  version manager, for example), the hooks fail without a message, so the
269
393
  instance stops reporting that it waits on you, and
270
394
  `oats schedule host status` reports `node-missing`. The capture hooks then
271
- fail at every stop of every Claude Code session of that user, and launchd or
272
- systemd keeps restarting a watcher that cannot start.
395
+ fail at every stop of every Claude Code session of that user, and every
396
+ 15-minute start of the capture service fails.
273
397
 
274
398
  **A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
275
399
  not follow the rule. Its hooks record the path of the `node` its hook ran
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.13.0 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.2 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
package/lib/core.mjs CHANGED
@@ -83,7 +83,7 @@ export { exactTreeDigest, fingerprintTree, generatedWorkDigest, KERNEL_HOME_RECE
83
83
 
84
84
  import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
85
85
  import { readPortableBytes } from "./bounded-read.mjs";
86
- import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes } from "./tree-copy.mjs";
86
+ import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes, treeDisagreement } from "./tree-copy.mjs";
87
87
  import { readAheadConsumed, readingAhead } from "./read-ahead.mjs";
88
88
  import { assertSameWorktreeHead, gitRead, gitRefPresence, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
89
89
  import { systemTool } from "./system-tools.mjs";
@@ -6129,6 +6129,26 @@ export function statusDisagreement(sourceStatus, recoveredStatus, cap = STATUS_D
6129
6129
  const paths = [...new Set([...a.keys(), ...b.keys()])].filter((p) => a.get(p) !== b.get(p)).sort();
6130
6130
  return { rows: paths.slice(0, cap).map((path) => ({ path, source: a.get(path) ?? null, recovery: b.get(path) ?? null })), total: paths.length };
6131
6131
  }
6132
+ const RECOVERY_DISAGREEMENT_SHOWN = 5;
6133
+ /** The refusal of a copy whose exact digest is not its source's (`what`), with where the two differ
6134
+ * now (treeDisagreement, read with the same `excludePaths`) as `recoveryDisagreement`, and the first
6135
+ * of those in the message. The digest comparison has refused already; this reading only says where
6136
+ * to look, and its `basis: "current"` says that it is the source as it is now, not the bytes the
6137
+ * comparison recorded. Exported for its test. */
6138
+ export function recoveryDisagreed(what, source, copy, excludePaths) {
6139
+ const diff = treeDisagreement(source, copy, { excludePaths });
6140
+ const shown = diff.entries.slice(0, RECOVERY_DISAGREEMENT_SHOWN).map((d) => `${d.path} (${d.kind})`).join("; ");
6141
+ const more = diff.entries.length > RECOVERY_DISAGREEMENT_SHOWN ? `; and ${diff.entries.length - RECOVERY_DISAGREEMENT_SHOWN} more` : "";
6142
+ const unfinished = diff.complete ? "" : `${shown ? "; " : ""}the search stopped (${diff.stoppedBy})`;
6143
+ const found = shown || unfinished ? `${shown}${more}${unfinished}` : "no difference between the current source and the copy";
6144
+ return Object.assign(new Error(`${what}; where they differ now (diagnostic only): ${found}`), { recoveryDisagreement: { basis: "current", ...diff } });
6145
+ }
6146
+ /** The details of E_WORK_PRESERVATION_FAILED for `e`: the disagreements it carries, beside `home`.
6147
+ * Exported for its test. */
6148
+ export function preservationDetails(home, e) {
6149
+ if (!e.statusDisagreement && !e.recoveryDisagreement) return undefined;
6150
+ return { home, ...(e.statusDisagreement ? { statusDisagreement: e.statusDisagreement } : {}), ...(e.recoveryDisagreement ? { recoveryDisagreement: e.recoveryDisagreement } : {}) };
6151
+ }
6132
6152
  /** Refuse a recovery whose Git status is not the source's, naming the differing rows (capped). */
6133
6153
  function assertStatusAgrees(source, recovered, what, repo) {
6134
6154
  const sourceStatus = worktreeStatus(source), recoveredStatus = worktreeStatus(recovered);
@@ -6615,16 +6635,40 @@ function runtimeAuthorityOf(baseline) {
6615
6635
  return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
6616
6636
  }
6617
6637
 
6618
- /** instance.json's tmux endpoint is the one the independent receipt authorises. */
6619
- function tmuxEndpointAgrees(meta, authority) {
6620
- return meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
6638
+ /** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
6639
+ * authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
6640
+ function tmuxEndpointDifferences(meta, authority) {
6641
+ return [
6642
+ ...(meta.tmux?.session === authority.tmux?.session ? [] : ["tmux.session"]),
6643
+ ...(meta.tmux?.window === authority.tmux?.window ? [] : ["tmux.window"]),
6644
+ ...(resolve(meta.tmux?.socket || ".") === authority.tmux?.socket ? [] : ["tmux.socket"]),
6645
+ ];
6621
6646
  }
6647
+ /** instance.json's tmux endpoint is the one the independent receipt authorises. */
6648
+ function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
6622
6649
 
6650
+ /** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
6651
+ * launched receipt. */
6652
+ function promptRetained(meta, authority) {
6653
+ return authority.launched === true && meta.launched === false && ["blocked", "incomplete"].includes(meta.launchPrompts?.status);
6654
+ }
6623
6655
  /** A blocked prompt is a retained runtime, not evidence that no process exists.
6624
6656
  * The independent launched receipt and exact endpoint agreement remain mandatory. */
6625
6657
  function launchStateAgrees(meta, authority) {
6626
- return meta.launched === authority.launched || (authority.launched === true && meta.launched === false &&
6627
- ["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
6658
+ return meta.launched === authority.launched || (promptRetained(meta, authority) && tmuxEndpointAgrees(meta, authority));
6659
+ }
6660
+
6661
+ /** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
6662
+ * what differs, from a fixed vocabulary in a fixed order: `launched` (unless a blocked or incomplete
6663
+ * launch prompt explains metadata's `launched: false`), then, for a launched receipt, each differing
6664
+ * tmux endpoint field. Labels only: never a path, a value or the receipt. Callers throw it only once
6665
+ * their own comparison has refused, so these labels diagnose a refusal and never decide one. */
6666
+ function authorityMismatch(message, meta, authority) {
6667
+ const fields = [
6668
+ ...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
6669
+ ...(authority.launched ? tmuxEndpointDifferences(meta, authority) : []),
6670
+ ];
6671
+ return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
6628
6672
  }
6629
6673
 
6630
6674
  /** The refusal for a home whose session receipt is at neither key its path gives (findRetirementBaseline):
@@ -6658,20 +6702,23 @@ function instanceSessionTarget(home) {
6658
6702
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
6659
6703
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
6660
6704
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
6661
- if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
6705
+ if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
6662
6706
  return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined };
6663
6707
  }
6664
6708
 
6665
- export function inspectInstanceSession(home) {
6666
- if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", waitingOnYou: null };
6709
+ /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes. */
6710
+ export function inspectInstanceSession(home, { io } = {}) {
6711
+ if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null };
6667
6712
  const s = instanceSessionTarget(home);
6668
- if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", waitingOnYou: null };
6713
+ if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null };
6669
6714
  let observed;
6670
- try { observed = inspectSessionTarget(s.target, undefined, { includeSize: true }); }
6715
+ try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
6671
6716
  // The tmux failure stays the cause: sessionServerGone judges it.
6672
6717
  catch (e) { throw Object.assign(oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`), { cause: e }); }
6673
- // Feature waiting-on-you: beside `state`, whose enum is unchanged.
6674
- return { home: s.home, ...observed, waitingOnYou: harnessRunning(observed) ? liveWaiting(s.home) : null };
6718
+ // Features session-inspect-running and waiting-on-you: beside `state`, whose enum is unchanged.
6719
+ // `running` is status's own liveness predicate over this observation, never a second reading.
6720
+ const running = harnessRunning(observed);
6721
+ return { home: s.home, ...observed, running, waitingOnYou: running ? liveWaiting(s.home) : null };
6675
6722
  }
6676
6723
  /** Whether an observed session runs a harness: present, and neither a
6677
6724
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
@@ -6978,11 +7025,11 @@ function stopRecordedChildren(children, signalled) {
6978
7025
  });
6979
7026
  }
6980
7027
 
6981
- export async function attachInstanceSession(home, { detachKey } = {}) {
7028
+ export async function attachInstanceSession(home, { detachKey, onSwept } = {}) {
6982
7029
  if (detachKey !== undefined) requireDetachKey(detachKey);
6983
7030
  const s = instanceSessionTarget(home);
6984
7031
  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
6985
- return attachSessionTarget(s.target, { detachKey });
7032
+ return attachSessionTarget(s.target, { detachKey, onSwept });
6986
7033
  }
6987
7034
 
6988
7035
  export function inputInstanceSession(home, text) {
@@ -7497,8 +7544,10 @@ export function startInstanceSession(home, o = {}) {
7497
7544
  // Reconcile even an exited target: the independent baseline may
7498
7545
  // already name it while metadata still names the old allocation.
7499
7546
  // The adopted start's session boundary, at its launch time, completed
7500
- // in whichever log the interrupted start did not record it.
7501
- recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: pending.launch?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: "recovered" });
7547
+ // in whichever log the interrupted start did not record it. The receipt's
7548
+ // recipe names its configuration (null: the bare harness); only a receipt
7549
+ // without a recipe falls back to the recorded one.
7550
+ recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: (pending.launch ? pending.launch.launchConfig : meta.launch?.launchConfig) ?? null, phase: "recovered" });
7502
7551
  const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
7503
7552
  // The adopted target is on another server than the home recorded (the start that allocated it
7504
7553
  // could not record it): this adoption records it, and says so once, here.
@@ -7693,7 +7742,7 @@ export function startInstanceSession(home, o = {}) {
7693
7742
  // end and wait, bounded. A harness still there afterwards is reported
7694
7743
  // as running; nothing is escalated and nothing is launched.
7695
7744
  stopReceipt = stopHarness(target, { graceMs: o.stopGraceMs ?? 20000, io: o.io, kill: o.io?.kill, sleep: o.io?.sleep });
7696
- writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
7745
+ writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe.launchConfig ?? null, model: model ?? null } }, 0o600);
7697
7746
  appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
7698
7747
  if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
7699
7748
  try { state = inspectSessionTarget(target, o.io); }
@@ -7794,7 +7843,8 @@ export function startInstanceSession(home, o = {}) {
7794
7843
  // The session exists: its boundary (lib/instance-events.mjs) is recorded
7795
7844
  // now, before the metadata, so a start whose metadata write fails still
7796
7845
  // voids the claims of the session it replaced; its adoption only completes a log it missed.
7797
- recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
7846
+ // The planned recipe names the configuration (null: the bare harness), never the recorded recipe's.
7847
+ recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
7798
7848
  // Keep launch evidence until the command exits or the target disappears.
7799
7849
  // A transient child (for example the native-start recorder) is not proof that startup
7800
7850
  // has finished. A later start reconciles the receipt without a watcher.
@@ -9118,7 +9168,7 @@ function copyRecoveryWork(observation, meta, parent, { rereadSource = true } = {
9118
9168
  let sourceBytes, gitPaths;
9119
9169
  if (observation.worktree) { sourceBytes = observedWorkBytes(observation); gitPaths = observation.workGitPaths ?? worktreeGitPaths(observation.work); }
9120
9170
  else { gitPaths = worktreeGitPaths(observation.work); sourceBytes = worktreeBytes(observation.work, gitPaths); }
9121
- if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw new Error("worktree recovery verification disagreed with the source");
9171
+ if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw recoveryDisagreed("worktree recovery verification disagreed with the source", observation.work, recoveredRepo, gitPaths);
9122
9172
  assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
9123
9173
  }
9124
9174
  // The proof of the copy: its HEAD is the commit the worktree has checked
@@ -9237,7 +9287,7 @@ function writeRetirementRecovery(observation, meta, instance, phase) {
9237
9287
  } catch (e) {
9238
9288
  const left = removeStaging(staging);
9239
9289
  if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
9240
- const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
9290
+ const details = preservationDetails(observation.home, e);
9241
9291
  throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
9242
9292
  }
9243
9293
  }
@@ -9323,7 +9373,7 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
9323
9373
  } catch (e) {
9324
9374
  const left = staging ? removeStaging(staging) : null;
9325
9375
  if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
9326
- const details = e.statusDisagreement ? { home: after.home, statusDisagreement: e.statusDisagreement } : undefined;
9376
+ const details = preservationDetails(after.home, e);
9327
9377
  throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
9328
9378
  }
9329
9379
  }
@@ -10328,7 +10378,7 @@ function retireSteps(root, name, o, found, at) {
10328
10378
  if (runtimeAuthority) {
10329
10379
  const metaAgrees = launchStateAgrees(meta, runtimeAuthority) && (!runtimeAuthority.launched || tmuxEndpointAgrees(meta, runtimeAuthority));
10330
10380
  if (!metaAgrees) {
10331
- throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
10381
+ throw authorityMismatch(`cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`, meta, runtimeAuthority);
10332
10382
  }
10333
10383
  }
10334
10384
  // The plan's promise about recorded children (`o.children`, computed the way
@@ -0,0 +1,35 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { fileURLToPath } from "node:url";
3
+ import { validCaptureHealthEnvelope } from "../packages/record/lib/capture-status.mjs";
4
+
5
+ const entry = fileURLToPath(new URL("../packages/record/lib/capture-health-doctor.mjs", import.meta.url));
6
+ const timeout = 20000, maxBuffer = 1024 * 1024;
7
+ const unavailable = detail => [{ code: "capture-health-unavailable", message:
8
+ `Capture health is unavailable (${detail}). Run oats capture --health --json to inspect the package reader failure; no capture or repair was attempted.` }];
9
+
10
+ // One fixed package command. No status/DB reads or diagnosis rules live here.
11
+ // Injection is an internal transport fixture seam, never a CLI/env override.
12
+ export function doctorCaptureWarnings({ env = process.env, cwd = process.cwd(), run = spawnSync } = {}) {
13
+ const childEnv = Object.fromEntries(["HOME", "USERPROFILE", "TMPDIR", "XDG_CACHE_HOME", "TURN_RECORD_ROOT"]
14
+ .filter(key => env[key] !== undefined).map(key => [key, env[key]]));
15
+ let result;
16
+ try {
17
+ result = run(process.execPath, [
18
+ ...process.execArgv.filter(arg => arg === "--experimental-sqlite"), entry,
19
+ ], { cwd, env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
20
+ timeout, maxBuffer, killSignal: "SIGKILL", windowsHide: true });
21
+ } catch { return unavailable("command transport failed"); }
22
+ if (!result || result.error || result.signal || result.status !== 0) {
23
+ // Do not promote unvalidated stderr or failed stdout into diagnosis rows.
24
+ return unavailable(result?.error?.code === "ETIMEDOUT" ? "command timed out" :
25
+ result?.error?.code === "ENOBUFS" ? "command output exceeded its bound" : "command or reader failed");
26
+ }
27
+ if (typeof result.stdout !== "string" || typeof result.stderr !== "string" ||
28
+ Buffer.byteLength(result.stdout) + Buffer.byteLength(result.stderr) > maxBuffer)
29
+ return unavailable("command output exceeded its bound");
30
+ let health;
31
+ try { health = JSON.parse(result.stdout); }
32
+ catch { return unavailable("invalid package response"); }
33
+ if (!validCaptureHealthEnvelope(health)) return unavailable("invalid package health envelope");
34
+ return health.rows.map(({ code, message }) => ({ code, message }));
35
+ }