@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
@@ -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
package/lib/tree-copy.mjs CHANGED
@@ -1,9 +1,11 @@
1
1
  /** Tree mechanics only: the kernel's catchable recursive copy (spawn, retire and
2
- * work recovery). No acquisition, selection, trust, lock or lifecycle policy. */
3
- import {
4
- chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync,
2
+ * work recovery), and a bounded comparison of a copy with its source. No
3
+ * acquisition, selection, trust, lock or lifecycle policy. */
4
+ import fs, {
5
+ chmodSync, closeSync, constants, copyFileSync, fstatSync, lstatSync, mkdirSync, opendirSync, openSync, readSync, readdirSync, readlinkSync, symlinkSync,
5
6
  } from "node:fs";
6
7
  import { sep } from "node:path";
8
+ import { performance } from "node:perf_hooks";
7
9
  import { oatsError } from "./errors.mjs";
8
10
 
9
11
  const SEPARATOR = Buffer.from(sep);
@@ -36,22 +38,201 @@ export const entriesAsBytes = (dir) => readdirSync(pathBytes(dir), { encoding: "
36
38
  * - symlinks are recreated VERBATIM — never followed, never rewritten — because
37
39
  * the bytes about to be hashed must be the bytes the author wrote. The target
38
40
  * is read and written as bytes: read as text, a target that is not valid
39
- * UTF-8 would be recreated as another one;
41
+ * UTF-8 would be recreated as another one. A link keeps its own mode, which
42
+ * the exact digest holds: where the new link's mode is not the source's
43
+ * (macOS gives a link the umask's mode; Linux every link 0777), it is set
44
+ * with lchmod, on the link and never on its target. A platform with no
45
+ * lchmod cannot, and the copy is refused (linkModeUnsupported) rather than
46
+ * left with another mode;
40
47
  * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
41
48
  * distributable content, and copying them has no defined meaning here;
42
49
  * - directory modes are applied AFTER their children, so a read-only source
43
50
  * directory cannot block writing its own contents. */
44
- export function copyTreeSafe(src, dest) {
51
+ export function copyTreeSafe(src, dest, { lchmod = fs.lchmodSync } = {}) {
45
52
  const st = lstatSync(src);
46
- if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); return; }
53
+ if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); copyLinkMode(dest, st.mode & 0o7777, lchmod); return; }
47
54
  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
48
55
  if (!st.isDirectory()) {
49
56
  throw oatsError("invalid-source", `${src.toString()} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
50
57
  }
51
58
  mkdirSync(dest, { recursive: true });
52
- for (const e of entriesAsBytes(src)) copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name));
59
+ for (const e of entriesAsBytes(src)) copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name), { lchmod });
53
60
  chmodSync(dest, st.mode & 0o7777);
54
61
  }
62
+ /** Give the link `dest`, just made, the permission bits `mode` of its source: nothing to do when it
63
+ * has them already, else lchmod (`lchmod`: fs.lchmodSync, which only a platform that can set a
64
+ * link's mode has), read back. A mode that cannot be set is refused, never dropped. */
65
+ function copyLinkMode(dest, mode, lchmod) {
66
+ if ((lstatSync(dest).mode & 0o7777) === mode) return;
67
+ if (typeof lchmod !== "function") throw linkModeUnsupported(dest, mode, "this platform cannot set a link's mode (no lchmod)");
68
+ lchmod(dest, mode);
69
+ const now = lstatSync(dest).mode & 0o7777;
70
+ if (now !== mode) throw linkModeUnsupported(dest, mode, `lchmod left it ${now.toString(8).padStart(4, "0")}`);
71
+ }
72
+ const linkModeUnsupported = (dest, mode, why) =>
73
+ new Error(`cannot copy the link ${pathBytes(dest).toString()} with its mode ${mode.toString(8).padStart(4, "0")}: ${why}; the copy would differ from its source`);
74
+
75
+ /** How far treeDisagreement goes before it stops: differences listed, directory
76
+ * entries read (on both sides, together), file bytes read (on both sides,
77
+ * together) and milliseconds. */
78
+ export const TREE_DISAGREEMENT_LIMITS = Object.freeze({ discrepancies: 20, entries: 200_000, bytes: 64 * 1024 * 1024, ms: 5000 });
79
+ const COMPARE_CHUNK = 64 * 1024;
80
+ // A file is opened as the regular file lstat saw: a name that became a link is not followed
81
+ // (O_NOFOLLOW), and one that became a FIFO does not block the open (O_NONBLOCK).
82
+ const COMPARE_OPEN = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
55
83
 
84
+ /** A relative path, as bytes, in text that reads back one way only: each
85
+ * printable ASCII byte as itself (space included), `\` as `\\`, and every
86
+ * other byte (a control character, a byte of a UTF-8 sequence or of no valid
87
+ * one) as `\xHH`. */
88
+ export function escapedPath(bytes) {
89
+ let out = "";
90
+ for (const b of pathBytes(bytes)) out += b === 0x5c ? "\\\\" : b >= 0x20 && b <= 0x7e ? String.fromCharCode(b) : `\\x${b.toString(16).padStart(2, "0")}`;
91
+ return out;
92
+ }
56
93
 
94
+ /** Where a copy differs from its source, for a diagnosis only: never a verdict.
95
+ * It is read when an exact comparison of the two has already refused, and
96
+ * what it reads is the two trees as they are NOW, so a source that changed
97
+ * since its bytes were recorded can show differences that are not the ones
98
+ * the recorded comparison saw, or none.
99
+ *
100
+ * Both trees are walked together, names as bytes in the order of those bytes,
101
+ * with lstat: an entry that is a link is compared as a link, never followed.
102
+ * `excludePaths` (relative paths, as bytes)
103
+ * are passed over on both sides, exactly. The roots' own modes are not
104
+ * compared. Each difference is `{ path, kind }`: `path` relative to the roots,
105
+ * escaped (escapedPath), and `kind` one of `missing` (in the source, not the
106
+ * copy), `extra` (in the copy, not the source), `type`, `mode` (permission
107
+ * bits), `link-target` and `file-content`. Below a `missing`, `extra` or
108
+ * `type` entry nothing is listed. One entry can have several kinds, in that
109
+ * order. Nothing else is said: no content, no link target, no absolute path.
110
+ *
111
+ * The trees may change while they are read, and every read is by path (Node has
112
+ * no call relative to an open directory). So what is read is checked against
113
+ * what lstat saw: a file is opened without following a link or waiting on a
114
+ * FIFO and must be the regular file lstat saw (device, inode, size); a
115
+ * directory must be the directory lstat saw (device, inode) before its
116
+ * listing, after it, and when the search leaves it, also by a stop below it.
117
+ * A directory that fails its check stops the search as `unreadable`, and
118
+ * nothing noted below it is reported. A replacement that is undone before the
119
+ * replaced directory is checked again is not detected: what was read through
120
+ * it can then be compared and named. Every path named is relative to the
121
+ * roots.
122
+ *
123
+ * The work is bounded (`limits`, TREE_DISAGREEMENT_LIMITS): a directory's
124
+ * entries count as they are read, so no listing is read beyond the budget
125
+ * before the search stops; only what was read is sorted. Files are compared
126
+ * in chunks, sizes first, and never read whole. The time budget is checked
127
+ * between filesystem calls; it does not interrupt one. → `{ entries, complete }`,
128
+ * with `stoppedBy` when it stopped early: `discrepancies` (more than it
129
+ * lists), `entries`, `bytes`, `time`, or `unreadable` when a tree could not
130
+ * be read (it may have changed while it was read). It never throws. An
131
+ * answer with `complete: true` and no entries found nothing that differs now. */
132
+ export function treeDisagreement(source, copy, { excludePaths = [], limits = TREE_DISAGREEMENT_LIMITS, clock = () => performance.now(), io = { lstat: lstatSync, opendir: opendirSync } } = {}) {
133
+ const excluded = new Set(excludePaths.map((path) => pathBytes(path).toString("hex")));
134
+ const entries = [];
135
+ const started = clock();
136
+ let looked = 0, read = 0;
137
+ const STOP = Symbol("stop");
138
+ const stop = (reason) => { throw { [STOP]: reason }; };
139
+ const inTime = () => { if (clock() - started > limits.ms) stop("time"); };
140
+ const note = (rel, kind) => {
141
+ if (entries.length === limits.discrepancies) stop("discrepancies");
142
+ entries.push({ path: escapedPath(rel), kind });
143
+ };
144
+ const kindOf = (st) => (st.isSymbolicLink() ? "link" : st.isFile() ? "file" : st.isDirectory() ? "dir" : "other");
145
+ /** `path` opened as the regular file `st` (its lstat) describes, else the search stops: the tree
146
+ * changed while it was read. */
147
+ const openAsSeen = (path, st) => {
148
+ const fd = openSync(path, COMPARE_OPEN);
149
+ const now = fstatSync(fd);
150
+ if (!now.isFile() || now.ino !== st.ino || now.dev !== st.dev || now.size !== st.size) { closeSync(fd); stop("unreadable"); }
151
+ return fd;
152
+ };
153
+ const sameBytes = (a, sa, b, sb) => {
154
+ const size = sa.size;
155
+ const fa = openAsSeen(a, sa);
156
+ try {
157
+ const fb = openAsSeen(b, sb);
158
+ try {
159
+ const ba = Buffer.allocUnsafe(COMPARE_CHUNK), bb = Buffer.allocUnsafe(COMPARE_CHUNK);
160
+ for (let at = 0; at < size;) {
161
+ const want = Math.min(COMPARE_CHUNK, size - at);
162
+ if (read + 2 * want > limits.bytes) stop("bytes");
163
+ inTime();
164
+ const na = readSync(fa, ba, 0, want, at), nb = readSync(fb, bb, 0, want, at);
165
+ read += na + nb;
166
+ if (na !== nb || na === 0 || !ba.subarray(0, na).equals(bb.subarray(0, nb))) return false;
167
+ at += na;
168
+ }
169
+ return true;
170
+ } finally { closeSync(fb); }
171
+ } finally { closeSync(fa); }
172
+ };
173
+ /** Whether `path` is still the directory `st` (its lstat) describes. */
174
+ const sameDirectory = (path, st) => {
175
+ let now;
176
+ try { now = io.lstat(path); } catch { return false; }
177
+ return now.isDirectory() && now.dev === st.dev && now.ino === st.ino;
178
+ };
179
+ /** The names of the directory `dir` (lstat `st`), as bytes in their order, each counted as it is
180
+ * read: the listing stops with the search once the budget is spent. */
181
+ const listing = (dir, st) => {
182
+ const names = [];
183
+ const d = io.opendir(dir, { encoding: "buffer" });
184
+ try {
185
+ for (let e = d.readSync(); e !== null; e = d.readSync()) {
186
+ if (++looked > limits.entries) stop("entries");
187
+ inTime();
188
+ names.push(e.name);
189
+ }
190
+ } finally { d.closeSync(); }
191
+ if (!sameDirectory(dir, st)) stop("unreadable");
192
+ return names.sort(Buffer.compare);
193
+ };
194
+ /** One directory of each tree, compared. Leaving it, by its end or by a stop below it, it is
195
+ * checked again: if either is no longer the directory lstat saw, everything noted below it was
196
+ * read through a replacement and is dropped, and the search stops as `unreadable`. */
197
+ const walk = (a, sa0, b, sb0, rel) => {
198
+ const mark = entries.length;
199
+ const unchanged = () => sameDirectory(a, sa0) && sameDirectory(b, sb0);
200
+ try { compareDirectories(a, sa0, b, sb0, rel); } catch (e) {
201
+ if (!unchanged()) { entries.length = mark; stop("unreadable"); }
202
+ throw e;
203
+ }
204
+ if (!unchanged()) { entries.length = mark; stop("unreadable"); }
205
+ };
206
+ const compareDirectories = (a, sa0, b, sb0, rel) => {
207
+ const na = listing(a, sa0), nb = listing(b, sb0);
208
+ for (let i = 0, j = 0; i < na.length || j < nb.length;) {
209
+ const order = i === na.length ? 1 : j === nb.length ? -1 : Buffer.compare(na[i], nb[j]);
210
+ const inA = order <= 0, inB = order >= 0;
211
+ const name = inA ? na[i] : nb[j];
212
+ if (inA) i++;
213
+ if (inB) j++;
214
+ const childRel = rel.length ? Buffer.concat([rel, SEPARATOR, name]) : name;
215
+ if (excluded.has(childRel.toString("hex"))) continue;
216
+ inTime();
217
+ if (!inB) { note(childRel, "missing"); continue; }
218
+ if (!inA) { note(childRel, "extra"); continue; }
219
+ const pa = joinBytes(a, name), pb = joinBytes(b, name);
220
+ const sa = io.lstat(pa), sb = io.lstat(pb);
221
+ const kind = kindOf(sa);
222
+ if (kind !== kindOf(sb)) { note(childRel, "type"); continue; }
223
+ if ((sa.mode & 0o7777) !== (sb.mode & 0o7777)) note(childRel, "mode");
224
+ if (kind === "link" && !readlinkSync(pa, "buffer").equals(readlinkSync(pb, "buffer"))) note(childRel, "link-target");
225
+ else if (kind === "file" && (sa.size !== sb.size || !sameBytes(pa, sa, pb, sb))) note(childRel, "file-content");
226
+ else if (kind === "dir") walk(pa, sa, pb, sb, childRel);
227
+ }
228
+ };
229
+ try {
230
+ const ra = io.lstat(pathBytes(source)), rb = io.lstat(pathBytes(copy));
231
+ if (!ra.isDirectory() || !rb.isDirectory()) stop("unreadable");
232
+ walk(pathBytes(source), ra, pathBytes(copy), rb, Buffer.alloc(0));
233
+ return { entries, complete: true };
234
+ } catch (e) {
235
+ return { entries, complete: false, stoppedBy: e && typeof e === "object" && STOP in e ? e[STOP] : "unreadable" };
236
+ }
237
+ }
57
238
 
@@ -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.2",
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.63.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",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.62.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.64.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 62, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 64, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */
@@ -60,11 +60,11 @@ commands are `oats capture|recall|setup`.
60
60
 
61
61
  ```bash
62
62
  turn-record setup # install Stop/SessionEnd hooks into every
63
- # ~/.claude*/settings.json, install the background
64
- # watcher (launchd on macOS, systemd user unit on
63
+ # ~/.claude*/settings.json, install periodic capture
64
+ # (launchd on macOS, systemd user service + timer on
65
65
  # Linux), then run the first capture pass.
66
66
  # Idempotent; --dry-run previews; --owner overrides
67
- # the machine name.
67
+ # the machine name. --root selects the persisted store.
68
68
 
69
69
  turn-record capture # one reconciliation pass, then index update
70
70
  turn-record capture --watch # pass now, on filesystem change, every 15 min
@@ -77,13 +77,21 @@ turn-record recall --show t1:<hex> # print one turn
77
77
  turn-record recall --reindex # full rebuild of the derived index
78
78
  ```
79
79
 
80
+ `recall --thread <thread> --json` lists a thread in capture sequence.
81
+ For a thread spanning aweb accounts, cross-account sequence under the service
82
+ is unspecified, and an ID window may contain turns from more than one account.
83
+ `--after <id>` excludes its boundary; `--until <id>` includes its boundary.
84
+ `--ids-only` uses the same window and reports IDs and output byte sizes. Later
85
+ appends do not reorder an existing window; existing tombstone visibility rules
86
+ still apply. Text thread listings without a query remain timestamp-sorted.
87
+
80
88
  Store root: `--root`, else `$TURN_RECORD_ROOT`, else `~/.turn-record`.
81
89
 
82
90
  `recall --show` refuses a turn hidden by its author's tombstone, including a
83
91
  session event whose tombstone lives in another stream. It emits no turn payload
84
92
  and exits with status 1, as it does for a missing turn.
85
93
 
86
- **The `node` that `setup` writes down.** The hooks and the watcher's unit name
94
+ **The `node` that `setup` writes down.** The hooks and the service's unit name
87
95
  a `node` by its path, and only `setup` run again rewrites them. Which path
88
96
  depends on how it is run:
89
97
 
@@ -100,16 +108,66 @@ runs under the `node` that runs `setup`.
100
108
 
101
109
  Each path is written for what reads it: a shell word in the hook's command,
102
110
  systemd's quoting in `ExecStart`, XML text in the launchd plist. A path of
103
- plain characters is written bare. A run finds the hooks of an earlier run by
104
- their shape, quoted or not, and replaces their command; a command it cannot
111
+ plain characters stays bare in hook commands. A run finds the hooks of an earlier run by
112
+ their shape, quoted or not, and refreshes command, async and timeout fields; a command it cannot
105
113
  read as its own is left alone and a new hook is added beside it.
106
114
  Stream owner: `--owner`, else `$TURN_RECORD_OWNER`, else the short hostname.
107
115
 
116
+ Ordinary/source-selected capture, explicit retry and foreground watch ticks use
117
+ the fixed supervised worker. Partial passes exit zero with pending work;
118
+ operational failures exit nonzero. `--no-index` never opens or mutates the
119
+ derived search index and supplies no fresh all-stage success. Quiet does not
120
+ imply a hook trigger. Explicit `--hook` launches a detached supervisor and reports
121
+ only “capture launched”, not initialization or completion. Owned Stop/SessionEnd
122
+ settings run the hook entry `bin/capture-hook.mjs` (the same launch as
123
+ `--quiet --hook`, under a file a rolled-back release cannot load, so it can
124
+ never return Claude's blocking exit two), `async:false` and `timeout:10`: the harness waits
125
+ for the launcher, while capture runs detached without its output pipes. Setup
126
+ refreshes these fields even when the owned command already matches, preserving
127
+ foreign hooks and unrelated fields. Hook errors, including usage, exit one,
128
+ never Claude's Stop-blocking exit two. Existing ordinary quiet argv remain
129
+ manual. Setup's first pass awaits the fixed supervisor with explicit `setup`
130
+ attribution and all sources/indexing enabled; `--no-service` still runs it,
131
+ while `--dry-run` starts no pass. Partial and overlap exit zero without claiming
132
+ completion; operational failures remain nonzero. Setup preflights named service
133
+ files, manager state and hook edits before mutation, then converts supported
134
+ legacy watchers to periodic capture, from the next release after 0.61.0;
135
+ 0.56.0–0.61.0 shipped without it.
136
+ See [command routing and receipts](docs/capture-service.md#ordinary-cli-and-foreground-watch).
137
+ See [detached hook launch limits](docs/capture-service.md#detached-hook-launcher).
138
+ The [service migration gate](docs/capture-service.md#setup-service-migration)
139
+ refuses foreign, disabled or masked definitions unless the operator explicitly
140
+ chooses `--replace-service`; `--no-service` bypasses service inspection and
141
+ actions while still installing requested hooks and running the first pass.
142
+ Refusals print that choice as the user-facing command with the selected
143
+ owner/root: `oats setup …` when the kernel environment handed in a node
144
+ (`OATS_NODE_BIN`, also set in instance shells), otherwise `turn-record setup …`.
145
+ Unknown/read errors always refuse, as does a macOS registration of the capture
146
+ label from another plist path, even with `--replace-service`. A refusal
147
+ changes nothing. A service failure after preflight still writes the hooks and
148
+ runs the first pass, then exits 1 with the
149
+ [setup summary](docs/capture-service.md#setup-service-migration) of what changed;
150
+ setup's private pending-activation marker (`<root>/capture-service-pending.json`)
151
+ lets a plain rerun finish its own activation, and `capture --health` reports it
152
+ as `capture-service-pending`.
153
+ Replacement saves nonoverwriting backups under the selected root and rechecks
154
+ file identity. `--dry-run` writes nothing and invokes no manager, so it reports
155
+ manager state as unexamined.
156
+ Healthy unchanged schedules preserve an active pass; successful setup reports
157
+ verified periodic scheduling, not a permanent PID. Real-manager lifecycle
158
+ and full service qualification remain separate gates.
159
+
108
160
  Transcript capture reads 64 KiB chunks and frames complete native records,
109
- including UTF-8 characters split across chunks. It appends batches of at most
110
- 8 MiB of source bytes plus the last record and checkpoints after each batch.
111
- One very large native record can still require memory proportional to that
112
- record; capture does not impose a new record-size policy.
161
+ including UTF-8 characters split across chunks. It flushes before adding a
162
+ record that would exceed an 8 MiB source batch and checkpoints after each batch.
163
+ Public synchronous capture can still process a larger individual record, with
164
+ memory proportional to that record; its resource contract is unchanged. The
165
+ supervised worker separately applies the fixed service policy beyond what is
166
+ already captured: it captures the complete records before a new record over
167
+ 8 MiB, then sets the input aside at that record's start. Records captured
168
+ earlier, of any size, are proved on recovery by streamed digests, not refused. Later records stay pending until the source is edited or the
169
+ whole input is ignored; `--retry-set-aside` cannot pass the oversized record
170
+ ([operator recovery](docs/capture-service.md#operator-recovery)).
113
171
  Final, attributed and protected Pi capture stage the descriptor's snapshot on
114
172
  private scratch under `<root>/.capture-tmp` before the first append, preserving
115
173
  attribution and custody checks without retaining the source in process memory.
@@ -163,8 +221,10 @@ Name-only patterns apply across every capture source: a short or generic
163
221
  pattern meant for one aw account can also catch a session file's basename
164
222
  or id in any format. Prefer path patterns for anything short or generic.
165
223
 
166
- Ignored files are counted in each pass (`N ignored` in capture output;
167
- `capture --status` shows the active pattern count), never skipped silently.
224
+ Ignored inputs are accounted for in worker run counts; exact synchronous
225
+ receipts retain their ignored counts. `capture --status` shows the active
226
+ pattern count. Ordinary text output summarizes confirmed appended turns and
227
+ outcome; `capture --health` exposes active refusals and remedies.
168
228
  The file is per record root and is local policy, not record truth — the
169
229
  sync guidance below replicates only `streams/` and `objects/`, so each
170
230
  machine decides what its own capture refuses to read; sync the `ignore`
@@ -173,6 +233,18 @@ ignore file that exists but cannot be read fails the pass loudly (a privacy
173
233
  control must not fail open), and ignoring is **forward-looking only** —
174
234
  turns already captured stay in the record; hide those with a tombstone.
175
235
 
236
+ `turn-record capture --health [--json]` reads offline installation,
237
+ receipt freshness/failure and current issue evidence without capture, repair,
238
+ root creation or manager calls. Warnings exit zero; unavailable readers fail.
239
+ A recent receipt or definition file does not certify enabled scheduling.
240
+ See [health diagnosis](docs/capture-service.md#offline-installation-and-run-diagnosis)
241
+ for exact installation candidates, nullable history, reader bounds and the
242
+ asleep/off-host caveat. Deployment `oats doctor` delegates once to package health
243
+ with a finite command timeout/output bound and maps its rows into warnings.
244
+ Command, reader or invalid-response failures yield `capture-health-unavailable`;
245
+ `--soul` remains composition-only. Kernel remedies say `oats`; standalone package
246
+ remedies say `turn-record`, without rewriting user paths or receipt data.
247
+
176
248
  ## Multi-machine
177
249
 
178
250
  Replicate `streams/` and `objects/` with any dumb file sync (syncthing,
@@ -301,7 +373,9 @@ output inventories without suppressing error counts.
301
373
 
302
374
  Verified snapshots and prefix comparisons use private record-root scratch, which
303
375
  can expand with source size; journal and derived-index disk space also grow with
304
- captured content. Staging is cleaned on success and failure. No new heap, record
376
+ captured content. Public per-call staging is cleaned on success and failure;
377
+ internal command recovery can retain explicitly owned jobs across workers, as
378
+ described in the [resource model](docs/capture-service.md#resource-model). No new heap, record
305
379
  size, elapsed-time or service policy limit is imposed by these algorithms.
306
380
 
307
381
  ## Known costs, accepted for v1
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ // The capture hook's entry: `capture --hook` under a file name of its own.
3
+ // Claude treats a hook's exit 2 as blocking. A release that predates this file
4
+ // cannot load it, so after a rollback the persisted hook line fails with exit 1
5
+ // ("Cannot find module"), which never blocks Stop or SessionEnd, instead of an
6
+ // older capture.mjs rejecting a flag it does not know with exit 2.
7
+ process.argv.splice(2, 0, "--hook");
8
+ await import("./capture.mjs");