@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
@@ -0,0 +1,223 @@
1
+ # OATS 0.62.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - The bounded periodic capture service ships in this release; 0.56.0 through
8
+ 0.61.0 do not include it. Upgrade in this order: install this release's
9
+ compatible Desktop first, then this CLI and the matching pi bridge, then run
10
+ this CLI's setup conversion once per user on each host, from that user's
11
+ shell, then its health and doctor checks. Do not use these flags or diagnostics as
12
+ pre-upgrade checks on 0.61.0 or older binaries, which do not have them. See
13
+ [capture service release order](../upgrading.md#capture-service-release-order).
14
+ - Run `oats setup` (standalone: `turn-record setup`) once per user on each
15
+ host, from that user's shell, with the deployment's owner and root: setup
16
+ writes that user's `~/.claude*/settings.json` and user manager. Installing the CLI
17
+ alone converts nothing: persisted hooks and manager definitions change only
18
+ when setup runs. Owned capture watchers convert to the periodic service there.
19
+ A foreign, disabled or masked definition is refused before any change, with
20
+ two printed commands that keep the owner and root: `--replace-service` to
21
+ replace only the named capture service, or `--no-service` to keep the
22
+ operator's service and skip service files and manager calls. Repair unknown
23
+ or unreadable state before retrying; replacement never waives it.
24
+ `--dry-run` writes nothing and calls no manager. Keep the backups setup
25
+ reports under `<root>/service-backups/`.
26
+ - Setup rewrites the owned `Stop`/`SessionEnd` capture hooks in every
27
+ `~/.claude*/settings.json` from `async: true`, `timeout: 120` to the hook
28
+ entry `bin/capture-hook.mjs` with `async: false`, `timeout: 10`, even where
29
+ the command already matches. 0.61.0 cannot load that entry, so after a
30
+ rollback the hook exits 1 instead of blocking Claude's Stop; the upgrade
31
+ guide gives the rollback steps. Until setup runs, the persisted hooks keep
32
+ the old fields.
33
+ - Setup rewrites each `~/.claude*/settings.json` it changes with mode `0600`.
34
+ - The capture status file keeps `schemaVersion: 1` while it gains fields, a
35
+ contract decision: 0.61.0 reads a status written by this release as invalid
36
+ (see the rollback note in the upgrade guide).
37
+ - A service refusal changes nothing. A service failure after preflight no
38
+ longer skips capture: setup still writes the hooks and runs the first pass,
39
+ then exits 1 and ends with a fixed-format
40
+ setup summary naming the hooks written, the first pass's result, the
41
+ service failure, what that failed apply had already changed (the backup
42
+ directory, units stopped or disabled, definitions written, the pending
43
+ marker), and the remedy. Setup has no `--json`; see #1330.
44
+ - A plain rerun finishes setup's own failed activation: setup records it in a
45
+ private `<root>/capture-service-pending.json` marker, removed once activation
46
+ is verified, so a timer its failed enable left disabled is retried without a
47
+ flag (#1099). A disabled unit without that marker is still the operator's
48
+ choice and needs `--replace-service` or `--no-service`. Until the rerun,
49
+ `capture --health` and `oats doctor` warn `capture-service-pending`: the
50
+ periodic schedule is not verified. Apply has no atomic rollback: a manager
51
+ failure can leave backups, stopped jobs or written definitions in place.
52
+ - After conversion, check `oats capture --health` (or
53
+ `turn-record capture --health`) against the intended root, and the capture
54
+ warnings of `oats doctor`, keeping the same `HOME` and `TURN_RECORD_ROOT`.
55
+ The health rows are `capture-status-missing`, `capture-status-invalid`,
56
+ `capture-success-stale`, `capture-pass-failed`, `capture-input-set-aside`,
57
+ `capture-setup-required` (an owned capture watcher or hook that setup has
58
+ not converted) and `capture-service-pending` (setup's activation is not
59
+ verified); `oats doctor` reports a failed health command as
60
+ `capture-health-unavailable`. Definition files, an `ok` diagnosis or no
61
+ warnings do not prove the schedule is registered and enabled. A missing recent success can reflect sleep or an
62
+ off-host machine; progress or cleared issues alone are not success. Update
63
+ the CLI before relying on complete piped health output.
64
+
65
+ ## Added
66
+
67
+ - **Named test files can be run by hand on a Linux runner whose user manager
68
+ works** ([#1108](https://github.com/awebai/oats/issues/1108)). The workflow
69
+ `Linux tests` (`linux-tests.yml`) is the Linux counterpart of `macOS tests`.
70
+ It runs named test files of a named ref, each alone, on `ubuntu-24.04`:
71
+ at most 10 files, 20 minutes a file, 240 minutes a job. Before the
72
+ header, it enables lingering for the runner user and waits at most 60
73
+ seconds for `systemctl --user` to answer. The header says whether
74
+ the manager answered, and a manager that did not answer fails the run
75
+ before anything is installed. Its terms are the macOS workflow's:
76
+ dispatch only, a read-only token, no secret, artifact or cache, and no
77
+ input in a shell line. Both workflows run one script. The workflow's name
78
+ is a contract that guarded tests key on, together with `workflow_dispatch`
79
+ and `linux`. The macOS workflow's name, inputs and printed evidence are
80
+ unchanged ([named test runs](../named-test-runs.md)).
81
+
82
+ ## Changed
83
+
84
+ - **Capture runs as bounded supervised passes.** Ordinary capture,
85
+ `--sessions-only`, `--aw-only`, `--no-index` and `--retry-set-aside` run one
86
+ pass through a fixed supervisor and worker under the root lock. A partial
87
+ pass exits 0 with work pending; an operational failure exits nonzero; a
88
+ missing worker receipt is reported as unknown, never as zero counts. Ordinary
89
+ lock overlap exits 0 and keeps the holder's receipt; a recovery that overlaps
90
+ is not performed and exits 1. `index: updated` is printed only for a complete
91
+ pass with indexing enabled. `--no-index` appends without opening the search
92
+ index and never reports a fresh all-stage success. Ordinary `--json` stays a
93
+ usage error and retry JSON keeps `{appended, pending}`. `--reset-cursors`,
94
+ the exact `--home`/`--file` proofs and the public synchronous APIs keep their
95
+ contracts.
96
+ - A pass resumes across worker replacement: source discovery, the index
97
+ inventory, index reset (separately admitted, atomic), retained recovery
98
+ cleanup and run accounting all commit in bounded pages. Interrupted work keeps
99
+ its retry evidence and backs off 30, 60, 120, then 240 minutes while healthy
100
+ work continues. Success is recorded only after an all-stage audit of sources,
101
+ index, admissions, retries and cleanup.
102
+ - A raw source record over 8 MiB is never allocated whole or captured. The
103
+ complete records before it are captured, and the input is set aside at that
104
+ record's start offset. Records after it stay pending until the operator edits
105
+ the source or adds the whole input to `<root>/ignore`; `--retry-set-aside`
106
+ retries the input, but the oversized record still blocks it, in every case.
107
+ The limit applies only beyond what is already captured: native recovery
108
+ (after cache loss, a reset, a retry or a rewritten source) proves captured
109
+ records of any size by streamed per-line digests, so sessions that already
110
+ hold records over 8 MiB keep capturing their later growth. Known limitation:
111
+ an oversized line before a session's first timestamped line captures
112
+ nothing before it. `--health` names the edit-or-ignore remedy for these
113
+ entries.
114
+ - Foreground `--watch` keeps its two-second debounce and 15-minute fallback,
115
+ runs one pass at a time and coalesces notifications into one pending rerun.
116
+ - **Hooks launch capture detached.** `capture --hook` starts the supervisor in
117
+ its own session without the harness's pipes. Exit 0 means **capture
118
+ launched**, not initialization or completion; launch and usage errors exit 1,
119
+ never Claude's Stop-blocking 2. The harness waits only for the launcher;
120
+ no launch latency is measured. Foreign hooks, groups and unrelated fields are
121
+ kept, and `--install-hint` prints the same fields, keeping
122
+ `--sessions-only --no-index`.
123
+ - **Setup installs a periodic service.** On macOS,
124
+ `ai.aweb.turn-record-capture` runs at load and every 900 seconds
125
+ (`StartInterval`), with no `KeepAlive`. On Linux, a finite
126
+ `turn-record-capture.service` (`MemoryMax=2G`, `RuntimeMaxSec=300`, no
127
+ restart) is started by `turn-record-capture.timer` one minute after boot and
128
+ every 15 minutes. Each start runs one pass with all sources and indexing.
129
+ Setup reports "periodic capture scheduled (every 15 minutes)" only after
130
+ verifying registration and enablement, never a permanent PID. An unchanged,
131
+ enabled schedule is left running, preserving a pass in flight.
132
+ - Setup takes `--root`, `--replace-service`, `--no-service` and `--dry-run`, and
133
+ preflights every named service file, the manager state and the hook edits
134
+ before changing anything. `E_CAPTURE_SERVICE_FOREIGN` refuses definitions or
135
+ registrations it does not own; on macOS that includes a registration of the
136
+ capture label from another plist path, refused naming that path even with
137
+ `--replace-service`. `E_CAPTURE_SERVICE_DISABLED` states the manager state it
138
+ observed, without claiming the operator disabled it. Refusals and failures
139
+ print the user-facing command with the selected `--owner` and `--root`:
140
+ `oats setup …` when the kernel environment handed in a node (`OATS_NODE_BIN`,
141
+ also set in instance shells), otherwise `turn-record setup …`; both record
142
+ the same node.
143
+ - Setup's first pass runs through the same supervisor with `setup` attribution,
144
+ all sources and indexing, under the running Node; the hooks and service record
145
+ a stable Node. `--no-service` still runs it and `--dry-run` starts none.
146
+ Partial and overlapping passes exit 0 without claiming completion.
147
+ - **`capture --health [--json]`** distinguishes no installation (no capture
148
+ service definition, capture hook or setup pending marker: a record root
149
+ alone, as one recall or manual capture leaves it, is not one), unknown
150
+ evidence, missing or invalid status, stale or absent success, newer failures,
151
+ unfinished runs and owned capture watchers that need setup. It reads no source
152
+ content or manager state and changes nothing. A capture pass that finds the
153
+ status file unreadable moves it aside to `capture-status.json.invalid-<UTC
154
+ stamp>` and writes a new status; a foreground, setup, watch or service pass
155
+ names the moved-aside file on stderr, a hook pass leaves only the file. Reader failures exit nonzero;
156
+ warnings exit 0. Reads are bounded, with a cooperative deadline.
157
+ - **`oats doctor`** runs package capture health once, with a finite timeout and
158
+ output bound, and turns its rows into warnings. A failed, timed-out or invalid
159
+ health run is `capture-health-unavailable`. Remedies say `oats` under the
160
+ kernel and `turn-record` standalone. Doctor's exit and output contracts are
161
+ unchanged.
162
+ - `recall --thread <thread> --json` lists a thread in capture sequence. For a
163
+ thread spanning aweb accounts the cross-account sequence is unspecified, and
164
+ an ID window may contain turns from more than one account. Text thread
165
+ listings without a query stay timestamp-sorted.
166
+ - Real macOS and Linux manager lifecycle, storage and synchronization costs, and
167
+ full hosted service qualification are verified separately from the isolated
168
+ fixtures.
169
+ - **OATS Desktop accepts an `oats` CLI 0.62.x.** Its band is now
170
+ `>=0.26.0 <0.63.0`. 0.62 adds no new gate on the band: the Desktop does
171
+ not read the capture service, and `oats session attach` keeps the
172
+ arguments and exit codes the Desktop's viewer relies on.
173
+
174
+ ## Fixed
175
+
176
+ - Capture CLI reporting finishes naturally, so piped stdout and stderr drain
177
+ before exit: health samples, truncation banners, JSON receipts and error
178
+ messages are no longer cut off. Exit codes are unchanged, and health cannot
179
+ fall through to a capture.
180
+ - **A viewer from `oats session attach` no longer outlives an attach that
181
+ died without detaching** ([#1332](https://github.com/awebai/oats/issues/1332)).
182
+ A cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh used
183
+ to leave the `oatsview-*` session, and a keyed viewer's key table, on the
184
+ agents' tmux server. Now the viewer's client sets a `client-detached` hook
185
+ on its own session once it has attached, so the server removes the session
186
+ when the client's connection drops without a word from it (`oats` and its
187
+ client SIGKILLed together), and with it a keyed viewer's key table; a
188
+ client that ends any other way leaves the viewer to `oats`, or, if `oats`
189
+ has died, to the next attach's sweep. A
190
+ viewer session that ends another way has its table unbound by one global
191
+ hook entry, `session-closed[900]`, the only one OATS owns on the agents'
192
+ server: keep your own `session-closed` hooks at other indexes (tmux 3.2 and
193
+ later; before 3.2 the sweep removes the table). The viewer never uses tmux's
194
+ `destroy-unattached`, which crashes a tmux 3.4 server when another client
195
+ detaches the viewer ([#1336](https://github.com/awebai/oats/issues/1336)).
196
+ A global `client-detached` hook of yours does not run for a viewer's
197
+ client whose connection dropped: the viewer's own hook takes its place. Every attach also
198
+ sweeps what earlier attaches left before it opens its viewer.
199
+ It removes a viewer session that has no client and whose attach is gone,
200
+ and every viewer key table whose session is gone. When the sweep removed
201
+ something, the attach says so in one line on stderr. Exit statuses are
202
+ unchanged, a leave by the detach key's 20 included
203
+ ([execution targets](../execution-targets.md#inspect-input-and-attach)).
204
+
205
+ ## Provider updates
206
+
207
+ - **oats.framework 1.13.1, oats.setup 2.8.1: record capture setup is a
208
+ person-run step** ([#1108](https://github.com/awebai/oats/issues/1108)).
209
+ From OATS 0.62.0, `/oats-setup-model` and the setup briefing name the record
210
+ capture conversion `oats setup` as the third install the person runs from
211
+ their own shell, beside the host wake broker and the host timer, and say how
212
+ to read `turn-record capture --health` and `oats doctor`'s capture warnings.
213
+ Every new line names the release it starts in. Instruction text only; the
214
+ floors are unchanged. A deployment gets it by pinning
215
+ `oats.framework: v1.13.1` and running `oats sync`.
216
+
217
+ ## Documentation
218
+
219
+ - **`docs/macos-test-runs.md` is now
220
+ [`docs/named-test-runs.md`](../named-test-runs.md)** and covers both
221
+ runners. It adds each workflow's name as a guard contract and says what a
222
+ Linux run is not evidence of: a hosted VM's user manager with lingering is
223
+ not a person's login session.
package/docs/upgrading.md CHANGED
@@ -74,6 +74,100 @@ 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). Read its Upgrade
93
+ section and keep this order: install the 0.62.0 Desktop first (it accepts CLIs
94
+ `>=0.26.0 <0.63.0`), then the 0.62.0 CLI and matching pi bridge. Only **after
95
+ installing that CLI**, run its setup conversion once per user on each host,
96
+ from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
97
+ watcher is replaced by the periodic service; foreign or disabled definitions
98
+ require an explicit operator choice. The conversion accepts `setup --root <dir>`
99
+ and `--replace-service`; refusal prints a quoted command preserving owner/root.
100
+ Choose `--no-service` to skip service files and manager operations entirely.
101
+ `--dry-run` writes nothing and calls no manager, so disabled/registered state
102
+ remains unexamined. Replaced definitions are backed up nonoverwriting under
103
+ the selected record root; retain the reported backup and inspect any partial
104
+ apply error before retrying. Replacement never waives unknown state or changed
105
+ identities. A CLI install alone is not conversion.
106
+ Use that release's capture health and doctor checks after conversion. Do not
107
+ run the service diagnostics or conversion flags as prerequisites on 0.61.0 or
108
+ older binaries, which do not have them, or assume that an older health command
109
+ proves periodic activation. The [capture reference](../packages/record/docs/capture-service.md)
110
+ distinguishes the implemented foundation from an installed service.
111
+
112
+ The first capture after that upgrade rebuilds the record root's derived
113
+ capture state and index from the existing journals: it validates each journal,
114
+ proves each session's captured prefix against a fresh staged copy of its
115
+ source, and indexes every record. This cost is paid once, and it grows linearly with the
116
+ number of streams and their bytes. On the hosted Linux runner (4 CPUs) it took
117
+ about 20 seconds per 1,000 streams of typical small sessions, and about 4
118
+ minutes per GB of journals overall: a record of about 1,300 streams and 8 GB of
119
+ journals needs roughly half an hour of capture work in about seven bounded
120
+ passes, which under the service's 15-minute interval is one to two hours of
121
+ elapsed time. A later pass over unchanged sessions does no content work and
122
+ costs about 2 ms per stream on the same runner (about 3 s at 1,300 streams),
123
+ growing linearly with the number of streams. Each pass stops at its deadline. A first upgrade that is interrupted or reaches its deadline resumes
124
+ from its durable checkpoints on the next pass (journal validation, index
125
+ cursors, the prefix proof and the staged copies of sources over 8 MiB) rather
126
+ than starting over; a smaller session's staged copy is made again. Reducing the
127
+ repeated source reads of small sessions is tracked in
128
+ [#1337](https://github.com/awebai/oats/issues/1337).
129
+
130
+ **Going back to 0.61.0.** Until the steps below are done, two things fail at
131
+ every trigger:
132
+
133
+ - each `Stop` and `SessionEnd` hook this release's setup wrote exits 1,
134
+ because its command names `bin/capture-hook.mjs`, a file 0.61.0 does not
135
+ have; Claude does not block on it;
136
+ - the periodic service's start fails every 15 minutes: on Linux
137
+ `turn-record-capture.timer` starts a unit whose runner 0.61.0 does not have,
138
+ and on macOS the `ai.aweb.turn-record-capture` job fails the same way.
139
+
140
+ To go back:
141
+
142
+ 1. Install 0.61.0: `npm install -g @awebai/oats@0.61.0`.
143
+ 2. From the same user's shell, run 0.61.0's setup with the same owner:
144
+ `oats setup --owner <owner>`. It installs its capture watcher (on Linux as
145
+ `turn-record-capture.service`, on macOS under the same
146
+ `ai.aweb.turn-record-capture` label) and adds its own `Stop` and
147
+ `SessionEnd` hooks. 0.61.0's setup takes no `--root` (it refuses one):
148
+ everything it starts records into `$TURN_RECORD_ROOT` as that process sees
149
+ it, else `~/.turn-record`. Its first pass runs with setup's environment, so
150
+ `TURN_RECORD_ROOT=<root> oats setup --owner <owner>` points that pass at
151
+ another root; its hooks see Claude's environment; its watcher's service
152
+ sets none, so the watcher gets only the user manager's environment and
153
+ records into `~/.turn-record` unless the user manager itself sets
154
+ `TURN_RECORD_ROOT`. With any other root, the watcher and the record you
155
+ were using part ways.
156
+ 3. In each `~/.claude*/settings.json`, delete the hook entries under `Stop` and
157
+ `SessionEnd` whose command names `capture-hook.mjs`: 0.61.0's setup does not
158
+ recognize them and leaves them in place.
159
+ 4. On Linux, remove the timer:
160
+ `systemctl --user disable --now turn-record-capture.timer`, then delete
161
+ `~/.config/systemd/user/turn-record-capture.timer` and run
162
+ `systemctl --user daemon-reload`.
163
+
164
+ After going back to 0.61.0, its `oats capture --health` reports the capture
165
+ status file this release wrote as invalid, and a capture by 0.61.0 clears the
166
+ run history in that file. A later capture with this release writes a fresh
167
+ status. 0.61.0 ignores the captured frontier this release keeps in an AW log's
168
+ cursor during a rescan and drops it when it rewrites that cursor; it reads that
169
+ log without a record limit, so nothing is lost.
170
+
77
171
  ## Which pi folders
78
172
 
79
173
  pi keeps its packages in one folder: `~/.pi/agent`, or the folder
@@ -197,6 +291,20 @@ at the version are left alone.
197
291
 
198
292
  ## What `oats doctor` reports
199
293
 
294
+ From the next release after 0.61.0 (service A), deployment doctor also delegates once to
295
+ the record package's offline health reader. Text and JSON carry its diagnosis
296
+ as existing warning rows. `capture-health-unavailable` means the bounded command
297
+ or reader failed, timed out, exceeded its output limit or returned an invalid
298
+ envelope; inspect `oats capture --health --json` with the same root environment.
299
+ Doctor retains its warning exit semantics. `TURN_RECORD_ROOT` selects the root,
300
+ otherwise the caller's `~/.turn-record` applies; `--soul` remains composition-only.
301
+ The kernel adds no status/DB/freshness parser or manager probe. Remedies use
302
+ `oats`, preserving literal user paths and existing owner guidance. Neither no
303
+ warnings nor definition bytes prove enabled scheduling. See the
304
+ [owning boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation)
305
+ for reader/transport limits and remaining qualification. This does not change
306
+ the released 0.56–0.61 upgrade prerequisites above.
307
+
200
308
  `oats doctor` prints one warning per folder whose bridge is not the kernel's
201
309
  version, naming the folder and why it is looked at:
202
310
 
@@ -233,9 +341,9 @@ under npm's global prefix (`npm prefix -g`).
233
341
  removes the kernel with it. Four things name that kernel by its path: each
234
342
  instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
235
343
  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.
344
+ (the turn record's capture hooks and its periodic capture service, which
345
+ name the capture scripts inside the kernel). OATS cannot make a path
346
+ inside a Node version outlast that version.
239
347
 
240
348
  Both layouts can exist on one host: check the prefix in the shell that
241
349
  installs the CLI.
@@ -248,7 +356,7 @@ record the `node` that runs them, by one rule
248
356
  - **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
249
357
  the `node` running the kernel. `brew upgrade node` repoints it, so the
250
358
  recorded path outlasts the upgrade: the hooks, the timer and the capture
251
- watcher need nothing done.
359
+ service need nothing done.
252
360
  - **Otherwise**, a `node` on `PATH` that is the same file as the one running
253
361
  the kernel. With mise that is the version's own install, which does not
254
362
  outlast the version (other version managers were not measured).
@@ -258,18 +366,32 @@ record the `node` that runs them, by one rule
258
366
 
259
367
  **What `oats setup` records is in your own files, not in an instance home:**
260
368
  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.
369
+ of the user who ran it, and the periodic capture service's definitions. On
370
+ macOS that is `~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist`, a
371
+ launchd job with `StartInterval` 900; on Linux, a finite
372
+ `~/.config/systemd/user/turn-record-capture.service` started by
373
+ `turn-record-capture.timer` every 15 minutes. Each start runs one bounded
374
+ capture pass and exits. No spawn, start or restart writes them: only
375
+ `oats setup` run again does. It replaces its own hooks and definitions, and
376
+ converts a capture watcher an earlier setup installed; it does not add a
377
+ second one. A definition it does not recognize as its own, or one found
378
+ disabled or masked, is refused with a printed choice: `--replace-service` to
379
+ replace it, or `--no-service` to keep it and skip service files and manager
380
+ calls. One exception on macOS: the capture label registered from another plist
381
+ is refused even with `--replace-service`; remove that registration yourself,
382
+ or keep it with `--no-service`. A service manager failure does not skip
383
+ capture: setup still writes the hooks and runs the first pass, exits 1 and
384
+ prints a setup summary of what changed; rerun the printed command, which
385
+ finishes setup's own activation without a flag. Until then `oats doctor` warns
386
+ `capture-service-pending`. `--dry-run` prints what setup would do and changes
387
+ nothing ([Capture service release order](#capture-service-release-order)).
266
388
 
267
389
  Once the recorded `node` no longer exists (an old version removed under a
268
390
  version manager, for example), the hooks fail without a message, so the
269
391
  instance stops reporting that it waits on you, and
270
392
  `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.
393
+ fail at every stop of every Claude Code session of that user, and every
394
+ 15-minute start of the capture service fails.
273
395
 
274
396
  **A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
275
397
  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.1 # 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
@@ -6978,11 +6978,11 @@ function stopRecordedChildren(children, signalled) {
6978
6978
  });
6979
6979
  }
6980
6980
 
6981
- export async function attachInstanceSession(home, { detachKey } = {}) {
6981
+ export async function attachInstanceSession(home, { detachKey, onSwept } = {}) {
6982
6982
  if (detachKey !== undefined) requireDetachKey(detachKey);
6983
6983
  const s = instanceSessionTarget(home);
6984
6984
  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
6985
- return attachSessionTarget(s.target, { detachKey });
6985
+ return attachSessionTarget(s.target, { detachKey, onSwept });
6986
6986
  }
6987
6987
 
6988
6988
  export function inputInstanceSession(home, text) {
@@ -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
+ }
@@ -32,9 +32,59 @@ const MOUSE_BINDINGS = [
32
32
  ["MouseDrag1Pane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -M"],
33
33
  ];
34
34
  /** What a detach key runs, as ONE bind-key argument (a bare `;` argument would end bind-key and
35
- * run the rest at once): mark the viewer session, then detach the client that pressed the key.
36
- * A constant: no caller text is ever part of a tmux command string. */
37
- const DETACH_BINDING = "set-option @oats-detached 1 ; detach-client";
35
+ * run the rest at once): mark the viewer session, keep it past its last client (its
36
+ * client-detached hook, below, would remove it, and the mark with it, before the attach reads the
37
+ * mark), then detach the client that pressed the key. The attach's cleanup removes the session; the next attach's sweep does,
38
+ * if the attach died first. A constant: no caller text is ever part of a tmux command string. */
39
+ const DETACH_BINDING = "set-option @oats-detached 1 ; set-hook -u client-detached ; detach-client";
40
+ /** A viewer session's name, which its key table shares: `oatsview-<pid of the attach>-<8 hex>`.
41
+ * One pattern for the sweep and the hook below; the 8 hex digits are spelled out because a
42
+ * format inside tmux's `#{...}` cannot hold `}`. */
43
+ const VIEWER_NAME_PATTERN = `^oatsview-([0-9]+)-${"[0-9a-f]".repeat(8)}$`;
44
+ const VIEWER_NAME = new RegExp(VIEWER_NAME_PATTERN);
45
+ /** The index of the one global hook entry the kernel owns on the agents' server,
46
+ * `session-closed[900]` (docs/execution-targets.md, "Inspect, input and attach"). */
47
+ export const VIEWER_CLOSED_HOOK_INDEX = 900;
48
+ /** What that entry runs when a session closes: when the session's name is a viewer's, unbind the
49
+ * key table of that name. A key table belongs to the server and outlives its session. The
50
+ * viewer's own client-detached hook (the attach, below) unbinds it when it ends the session; a
51
+ * session can also end with no client detaching from it (its window ended, a kill-session), and
52
+ * only a global session-closed hook runs then: a session's own hooks are gone with it. The name is matched before it reaches a command. `run-shell -C`
53
+ * expands the name; tmux before 3.2 has no -C, the entry does nothing there, and the next attach's
54
+ * sweep removes the table. A constant: setting it again leaves the server as it was. */
55
+ const VIEWER_CLOSED_HOOK = `if-shell -F '#{m/r:${VIEWER_NAME_PATTERN},#{hook_session_name}}' "run-shell -C 'unbind-key -a -q -T #{hook_session_name}'"`;
56
+ /** Whether a process exists: kill(pid, 0), and EPERM (another user's) exists too. */
57
+ function processAlive(pid) {
58
+ try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
59
+ }
60
+
61
+ /** Remove what attaches that died without detaching left on the server, and answer how many of
62
+ * each went. A viewer session goes when no client is attached and the attach named in it is gone;
63
+ * an attach that is alive may not have attached its client yet, or may be between a leave by its
64
+ * key and its own cleanup. A key table goes when no session has its name. Keys are listed before
65
+ * sessions: a viewer makes its session before its table, so a table listed belongs to a session
66
+ * that the later list shows, unless that session has ended. Nothing whose name is not a viewer's
67
+ * is touched, the shared locked table included. A failed call removes nothing and counts nothing:
68
+ * the attach goes on, and the next one sweeps again. */
69
+ function sweepViewers(run) {
70
+ const swept = { sessions: 0, tables: 0 };
71
+ let tables, sessions;
72
+ try {
73
+ tables = new Set(run(["list-keys"]).split("\n").map((line) => /^bind-key\s+(?:-r\s+)?-T\s+(\S+)\s/.exec(line)?.[1]).filter((t) => VIEWER_NAME.test(t ?? "")));
74
+ sessions = run(["list-sessions", "-F", "#{session_name}\t#{session_attached}"]).split("\n").map((line) => line.split("\t"));
75
+ } catch { return swept; }
76
+ const kept = new Set();
77
+ for (const [name, attached] of sessions) {
78
+ const viewer = VIEWER_NAME.exec(name);
79
+ if (!viewer || attached !== "0" || processAlive(Number(viewer[1]))) { kept.add(name); continue; }
80
+ try { run(["kill-session", "-t", `=${name}`]); swept.sessions++; } catch { kept.add(name); }
81
+ }
82
+ for (const table of tables) {
83
+ if (kept.has(table)) continue;
84
+ try { run(["unbind-key", "-a", "-q", "-T", table]); swept.tables++; } catch { /* the next attach sweeps again */ }
85
+ }
86
+ return swept;
87
+ }
38
88
 
39
89
  /** Whether a `tmux -V` answer names a release with the client's `-T <features>` flag (tmux 3.2):
40
90
  * `tmux X.Y` with an optional letter suffix only. A development build (`tmux next-3.6`,
@@ -61,6 +111,7 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
61
111
  const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {
62
112
  encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"], detached: true,
63
113
  }).trim();
114
+ const swept = sweepViewers(run);
64
115
  const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
65
116
  // A keyed viewer reads a table of its own, named as its session: a binding in the locked table
66
117
  // would be every viewer's, and the next viewer's unbind would remove it.
@@ -91,7 +142,11 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
91
142
  run(["unbind-key", "-a", "-q", "-T", table]);
92
143
  for (const binding of MOUSE_BINDINGS) run(["bind-key", "-T", table, ...binding]);
93
144
  // The key is its own argv element, after the grammar admitted it.
94
- if (detachKey !== undefined) run(["bind-key", "-T", table, detachKey, DETACH_BINDING]);
145
+ if (detachKey !== undefined) {
146
+ run(["bind-key", "-T", table, detachKey, DETACH_BINDING]);
147
+ // The table goes when the session does, however the session ended; no other index is touched.
148
+ run(["set-hook", "-g", `session-closed[${VIEWER_CLOSED_HOOK_INDEX}]`, VIEWER_CLOSED_HOOK]);
149
+ }
95
150
  run(["set-option", "-t", viewer, "mouse", "on"]);
96
151
  const env = { ...process.env }; delete env.TMUX;
97
152
  /** Whether the detach key's binding ran: it marks the viewer session before it detaches. A
@@ -113,7 +168,28 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
113
168
  clientFeatures.set(exec, sync);
114
169
  }
115
170
  const features = clientFeatures.get(exec) ? ["-T", "sync"] : [];
116
- return { binary: "tmux", args: ["-u", "-S", target.socket, ...features, "attach-session", "-t", `=${viewer}`], env, cleanup, detached };
171
+ // The client sets the viewer session's client-detached hook itself, after its attach succeeded
172
+ // (a command chained after attach-session runs only then; a viewer whose client never attached
173
+ // is the cleanup's, or the next attach's sweep's): when a client goes and none is left, the hook
174
+ // kills the viewer session. tmux finds this session's hook only when the client's connection
175
+ // drops with no word from the client: a SIGKILL of the attach and its client (oomd, a stop
176
+ // timeout), a crashed client. A client that leaves any other way (a hang-up or SIGTERM, which
177
+ // the client answers with MSG_EXITING; a `detach-client`; the detach key) has its session
178
+ // cleared before it has left, and the hook is then looked up on another session: the attach's
179
+ // own cleanup removes such a viewer, or, when the attach has died, the next attach's sweep.
180
+ // Never `destroy-unattached on` instead: on tmux 3.4 a `detach-client` from another client only
181
+ // flags the detached client CLIENT_EXIT; until that client answers (MSG_EXITING) it keeps its
182
+ // session, but recalculate_sizes no longer counts it as attached, so the next client lost
183
+ // (any command client) runs server_check_unattached, which destroys the session under it, and
184
+ // the server's next loop dereferences the session's NULL curw: SIGSEGV, every agent's session
185
+ // gone (#1336). client-detached fires only once the client has left the server's client list.
186
+ // A keyed viewer's hook unbinds its table too: tmux runs no hook for what a hook's own commands
187
+ // cause, so the session-closed entry does not run for a session this kill-session ends. The
188
+ // unbind comes first: a command list stops at a command that fails, as this kill-session does
189
+ // when the session has already ended.
190
+ const removal = table === LOCKED_TABLE ? `kill-session -t =${viewer}` : `unbind-key -a -q -T ${table} ; kill-session -t =${viewer}`;
191
+ const attach = ["attach-session", "-t", `=${viewer}`, ";", "set-hook", "-t", `=${viewer}:`, "client-detached", `if-shell -F '#{==:#{session_attached},0}' '${removal}'`];
192
+ return { binary: "tmux", args: ["-u", "-S", target.socket, ...features, ...attach], env, cleanup, detached, session: viewer, swept };
117
193
  } catch (e) { cleanup(); throw e; }
118
194
  }
119
195
 
@@ -131,8 +207,9 @@ function holdQuit() {
131
207
  }
132
208
 
133
209
  /** Attach this terminal to a viewer of the target and answer the client's status, or
134
- * SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. */
135
- export async function attachSessionTarget(target, { detachKey } = {}) {
210
+ * SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. `onSwept` is given what
211
+ * the preparation swept, `{ sessions, tables }`, before the client starts. */
212
+ export async function attachSessionTarget(target, { detachKey, onSwept } = {}) {
136
213
  if (detachKey !== undefined) { requireDetachKey(detachKey); holdQuit(); }
137
214
  // HUP, TERM and INT are held from before the viewer session exists until its cleanup has
138
215
  // finished: one that arrives in between, early or late, finds a listener and not the default
@@ -153,6 +230,8 @@ export async function attachSessionTarget(target, { detachKey } = {}) {
153
230
  // key pressed again, and the attach ends as a detach.
154
231
  if (detachKey !== undefined) onQuit = () => { if (viewer.detached()) return; quit = true; stop(); };
155
232
  try {
233
+ // Inside the try: a report that throws (a closed stderr) still has the viewer removed.
234
+ onSwept?.(viewer.swept);
156
235
  // A signal received during the synchronous preparation is dispatched only in a poll phase of
157
236
  // the event loop. Two setImmediate hops run at least one, wherever this attach was called
158
237
  // from, so such a signal stops the attach here, before a client takes the terminal: one loop
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.13.0",
46
+ "ref": "oats-framework/v1.13.1",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.61.0",
3
+ "version": "0.62.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",