@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
@@ -12,37 +12,69 @@
12
12
  // accounts) whose sources are never captured — see lib/ignore.mjs.
13
13
  // Reconciliation is the capture; hooks and watch only decide when to run it.
14
14
 
15
- import { closeSync, constants, fstatSync, openSync, readFileSync, watch } from "node:fs";
15
+ import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync, watch } from "node:fs";
16
16
  import { homedir, hostname } from "node:os";
17
- import { basename, join, resolve } from "node:path";
17
+ import { basename, isAbsolute, join, resolve } from "node:path";
18
18
  import process from "node:process";
19
19
 
20
20
  import { RecordStore } from "../lib/store.mjs";
21
- import { captureAllSessions, captureSessions } from "../lib/capture-cc.mjs";
21
+ import { captureSessions } from "../lib/capture-cc.mjs";
22
22
  import { sessionsForHome } from "../lib/sessions-for-home.mjs";
23
23
  import { SESSION_FORMATS } from "../lib/formats.mjs";
24
24
  import { cwdOfLine } from "../lib/sessions-for-home.mjs";
25
25
  import { stageSnapshot } from "../lib/session-snapshot.mjs";
26
26
  import { cleanupCaptureScratch } from "../lib/capture-scratch.mjs";
27
27
  import { bufferLines } from "../lib/file-lines.mjs";
28
- import { captureAwLogs, defaultCommLogDir } from "../lib/capture-aw.mjs";
29
28
  import { withReceiptSummaries } from "../lib/receipt-summary.mjs";
30
29
  import { RecordIndex } from "../lib/index-db.mjs";
31
30
  import { IgnoreError, ignoreFilePath, loadIgnore } from "../lib/ignore.mjs";
32
- import { CAPTURE_SOURCES, captureHealth, resetSourceCursors, retrySetAside, writeCaptureStatus } from "../lib/capture-state.mjs";
31
+ import { CAPTURE_SOURCES, captureHealth, resetSourceCursors, writeCaptureStatus } from "../lib/capture-state.mjs";
33
32
  import { acquireCaptureLock } from "../lib/capture-lock.mjs";
33
+ import { captureHealthForDoctor } from "../lib/capture-health.mjs";
34
+ import { captureDefaultRootPlan, resolveCaptureDefaultRoots } from "../lib/capture-default-roots.mjs";
35
+ import { captureCommandPass, reportLockInitializationFailure, reportReclaimedLock, releaseDetail } from "../lib/capture-command-output.mjs";
36
+ import { captureCommandEntry } from "../lib/capture-command.mjs";
37
+ import { captureSignalPoll } from "../lib/capture-supervisor.mjs";
38
+ import { captureWatchQueue } from "../lib/capture-watch.mjs";
39
+ import { launchCaptureHook } from "../lib/capture-hook.mjs";
34
40
 
35
41
  // Fail closed but actionably: an unreadable ignore file must stop capture,
36
42
  // as one clear line naming the file — never an uncaught stack trace.
37
- function loadIgnoreOrExit(recordRoot) {
43
+ class PrintedCaptureFailure extends Error {}
44
+ function loadIgnoreForCommand(recordRoot) {
38
45
  try {
39
46
  return loadIgnore(recordRoot);
40
47
  } catch (err) {
41
48
  console.error(err instanceof IgnoreError ? err.message : String(err));
42
- process.exit(1);
49
+ throw new PrintedCaptureFailure();
43
50
  }
44
51
  }
45
52
 
53
+ // The exact commands (--home, --file, --reset-cursors) run in this process.
54
+ // TERM/INT while one runs is observed only at its safe points: before the
55
+ // lock, after taking it, before each format's batch of exact files and before
56
+ // the index update. Discovery, one format's batch, the index update and the
57
+ // receipt summaries are synchronous and cannot be preempted, so a signal
58
+ // waits for the segment it arrived in; no response time is promised. An
59
+ // interruption at a safe point unwinds through the lock's release.
60
+ class CaptureInterrupted extends Error {}
61
+ let signalled = null;
62
+ const onSignal = signal => { signalled ??= signal; };
63
+ /** Run `fn` with TERM/INT observed, from before its lock until it returns. */
64
+ async function observingSignals(fn) {
65
+ process.on("SIGTERM", onSignal); process.on("SIGINT", onSignal);
66
+ try { return await fn(); }
67
+ finally { process.off("SIGTERM", onSignal); process.off("SIGINT", onSignal); }
68
+ }
69
+ /** A safe point: a signal pending from synchronous work dispatches during
70
+ * the poll this yields to, and an observed one ends the command here.
71
+ * `after` says what had already been done, so the answer never implies it
72
+ * was not. */
73
+ async function safePoint(after) {
74
+ await captureSignalPoll();
75
+ if (signalled) throw new CaptureInterrupted(`capture interrupted by ${signalled}${after ? ` after ${after}` : ""}`);
76
+ }
77
+
46
78
  // Every flag this program understands. An unknown flag is rejected rather
47
79
  // than ignored, because the fall-through from argument parsing is pass() —
48
80
  // a WRITE. `capture --help` was once a full reconciliation pass under a
@@ -51,6 +83,7 @@ function loadIgnoreOrExit(recordRoot) {
51
83
  // it does not understand before anything can be written.
52
84
  const VALUE_FLAGS = new Set(["root", "owner", "home", "file", "format", "source"]);
53
85
  const BOOL_FLAGS = new Set([
86
+ "hook",
54
87
  "reset-cursors",
55
88
  "retry-set-aside",
56
89
  "health",
@@ -71,10 +104,12 @@ const USAGE = `capture — land sessions and aw client logs in the turn record.
71
104
  capture one reconciliation pass (sessions + aw logs)
72
105
  capture --sessions-only only session transcripts (Claude Code, pi, codex)
73
106
  capture --aw-only only aw client comm logs
107
+ capture --hook launch detached capture; exit 0 acknowledges
108
+ launch only, never capture completion
74
109
  capture --watch pass now, then re-pass on filesystem change
75
110
  (debounced) and every 15 minutes regardless
76
111
  capture --status show store/stream summary, capture nothing
77
- capture --health [--json] read capture set-aside diagnosis, capture nothing
112
+ capture --health [--json] read offline installation, run and issue diagnosis
78
113
  capture --reset-cursors [--source aw|cc|pi|codex]
79
114
  reset selected source cursors and exit; the next
80
115
  pass reprocesses them with journal deduplication
@@ -132,6 +167,10 @@ Every invocation with no explicit subcommand WRITES. Reconciliation is the
132
167
  capture; hooks and watch only decide when to run it.`;
133
168
 
134
169
  class UsageError extends Error {}
170
+ const hookRequested = process.argv.slice(2).some(arg => arg === "--hook" || arg.startsWith("--hook="));
171
+ function hookLaunchError(error) {
172
+ console.error(`capture hook launch failed: ${String(error.message).replace(/[\r\n]+/g, " ")}`);
173
+ }
135
174
 
136
175
  function parseArgs(argv) {
137
176
  const args = {};
@@ -144,7 +183,7 @@ function parseArgs(argv) {
144
183
  const name = a.slice(2);
145
184
  if (VALUE_FLAGS.has(name)) {
146
185
  const value = argv[++i];
147
- if (value === undefined) throw new UsageError(`${a} needs a value`);
186
+ if (value === undefined || hookRequested && value.startsWith("--")) throw new UsageError(`${a} needs a value`);
148
187
  if (name === "file" && args.file !== undefined) throw new UsageError("one --file per call");
149
188
  args[name] = value;
150
189
  } else if (BOOL_FLAGS.has(name)) {
@@ -156,6 +195,12 @@ function parseArgs(argv) {
156
195
  return args;
157
196
  }
158
197
 
198
+ // Terminal branches return instead of forcing termination while stdout/stderr
199
+ // may still contain queued pipe writes. Returning also prevents reporting from
200
+ // falling through to capture. Lock/child owners finish before returning; watch
201
+ // retains its signal lifecycle. No stream is closed or given an arbitrary delay.
202
+ const finish = code => { process.exitCode = code; };
203
+ async function main() {
159
204
  let args;
160
205
  try {
161
206
  args = parseArgs(process.argv.slice(2));
@@ -163,60 +208,93 @@ try {
163
208
  if (recovery.length > 1) throw new UsageError("choose one recovery or health operation");
164
209
  if (args.source !== undefined && (!args["reset-cursors"] || !CAPTURE_SOURCES.includes(args.source))) throw new UsageError("--source requires --reset-cursors and aw|cc|pi|codex");
165
210
  if (recovery.length && ["home", "file", "format", "watch", "status", "install-hint", "current-roots", "sessions-only", "aw-only"].some(key => args[key])) throw new UsageError("recovery/health cannot be combined with another capture mode");
211
+ if (args.hook && ["home", "file", "format", "watch", "status", "install-hint", "help", "current-roots", "json", ...recovery].some(key => args[key] !== undefined))
212
+ throw new UsageError("--hook cannot be combined with proof, recovery, JSON or another capture mode");
166
213
  } catch (err) {
167
214
  if (!(err instanceof UsageError)) throw err;
215
+ // Claude treats hook exit2 as blocking/model feedback. Explicit hook usage
216
+ // failures report launch failure on stderr/exit1, never that special status.
217
+ if (hookRequested) {
218
+ hookLaunchError(err);
219
+ return finish(1);
220
+ }
168
221
  // --file --json answers JSON even for a usage error: it is for programs.
169
222
  if (process.argv.includes("--json")) {
170
223
  console.log(JSON.stringify({ status: "failed", complete: false, code: "E_USAGE", error: err.message }, null, 2));
171
- process.exit(2);
224
+ return finish(2);
172
225
  }
173
226
  console.error(`capture: ${err.message}\n\n${USAGE}`);
174
- process.exit(2);
227
+ return finish(2);
175
228
  }
176
229
 
177
230
  if (args.help) {
178
231
  console.log(USAGE);
179
- process.exit(0);
232
+ return finish(0);
180
233
  }
181
234
 
182
235
  const root = args.root ?? process.env.TURN_RECORD_ROOT ?? join(homedir(), ".turn-record");
183
236
  const ownerExplicit = args.owner !== undefined || process.env.TURN_RECORD_OWNER !== undefined;
184
237
  const owner = args.owner ?? process.env.TURN_RECORD_OWNER ?? hostname().split(".")[0];
185
238
  const quiet = Boolean(args.quiet || args.json && (args["reset-cursors"] || args["retry-set-aside"]));
186
- const store = new RecordStore(root, { owner });
239
+ const store = args.hook || args.health ? null : new RecordStore(root, { owner });
187
240
 
188
241
  if (args.health) {
189
242
  try {
190
- const health = captureHealth(root);
243
+ // Remedies name the command the person has: `oats` when the kernel runs
244
+ // this script (it imports it, so argv[1] is the kernel's entry, an npm bin
245
+ // symlink named oats included) or handed a node, as setup's remedies do;
246
+ // `turn-record` when run alone.
247
+ const entry = (() => {
248
+ try { return realpathSync(process.argv[1] ?? ""); }
249
+ catch (error) { if (error.code === "ENOENT") return process.argv[1] ?? ""; throw error; }
250
+ })();
251
+ const viaKernel = basename(entry) === "oats.mjs" || isAbsolute(process.env.OATS_NODE_BIN ?? "");
252
+ const health = viaKernel ? captureHealthForDoctor(root) : captureHealth(root);
191
253
  if (args.json) console.log(JSON.stringify(health, null, 2));
192
254
  else {
193
255
  console.log(`capture: ${health.status}`);
194
256
  for (const row of health.rows) console.log(`${row.code}: ${row.message}`);
195
257
  for (const entry of health.backlog.setAside) console.log(`${entry.source}: ${entry.path}:${entry.line ?? "?"} offset ${entry.offset}: ${entry.reason}`);
196
258
  if (health.backlog.truncated) console.log("showing first 100 set-aside inputs");
259
+ for (const entry of health.backlog.failed) console.log(`${entry.stream}: unit starting at byte ${entry.offset} (failing frame unknown): ${entry.reason}; attempts ${entry.attempts}; next retry ${entry.nextRetryAt}`);
260
+ if (health.backlog.failedTruncated) console.log("showing first 100 failed stream units");
197
261
  }
198
262
  } catch (err) {
199
263
  if (args.json) console.log(JSON.stringify({ status: "failed", error: err.message }));
200
264
  else console.error(`capture: ${err.message}`);
201
265
  process.exitCode = 1;
202
266
  }
203
- process.exit(process.exitCode ?? 0);
267
+ return;
204
268
  }
205
269
  if (args["reset-cursors"] || args["retry-set-aside"]) {
206
270
  try {
207
271
  const result = args["reset-cursors"]
208
- ? withCaptureLock(() => { resetSourceCursors(root, owner, args.source); return { reset: true, sources: args.source ? [args.source] : CAPTURE_SOURCES }; })
209
- : pass({ retry: true });
272
+ ? await observingSignals(() => withCaptureLock(() => { resetSourceCursors(root, owner, args.source); return { reset: true, sources: args.source ? [args.source] : CAPTURE_SOURCES }; }, "reset-cursors", "the cursor reset was committed"))
273
+ : await pass({ retry: true });
210
274
  if (result.skipped) throw new Error("capture lock held; recovery was not performed");
211
275
  if (process.exitCode) throw new Error("recovery failed to release its capture lock");
212
276
  if (args.json) console.log(JSON.stringify(result));
213
277
  else if (args["reset-cursors"]) log(`capture: reset source cursors (${result.sources.join(", ")})`);
214
278
  } catch (err) {
279
+ if (err instanceof PrintedCaptureFailure) throw err;
215
280
  if (args.json) console.log(JSON.stringify({ status: "failed", complete: false, error: err.message }));
216
281
  else console.error(`capture: ${err.message}`);
217
282
  process.exitCode = 1;
218
283
  }
219
- process.exit(process.exitCode ?? 0);
284
+ return;
285
+ }
286
+
287
+ if (args.hook) {
288
+ try {
289
+ await launchCaptureHook(root, { owner, plan: commandPlan(), indexEnabled: !args["no-index"], trigger: "hook", retrySetAside: false });
290
+ log("capture launched; launch is not completion (see capture --health)");
291
+ } catch (error) {
292
+ hookLaunchError(error);
293
+ process.exitCode = 1;
294
+ }
295
+ // No capture work or discovery in the harness process. The detached owner
296
+ // takes the lock and retains the existing worker lifetime/reaping contract.
297
+ return;
220
298
  }
221
299
 
222
300
  // The owner decides the stream namespace, and turn ids hash it into the
@@ -258,25 +336,18 @@ function log(...parts) {
258
336
  * in the finally, and a release that did not happen is said so on stderr
259
337
  * with the operator recovery and a nonzero exit status. Likewise an owner
260
338
  * record that could not be written: the lock never silently outlives the
261
- * pass that created it. */
262
- function withCaptureLock(fn) {
339
+ * pass that created it. `command` labels the owner record; `done` names
340
+ * what `fn` committed, for an interruption observed after it returned. */
341
+ async function withCaptureLock(fn, command, done) {
263
342
  let lock;
343
+ await safePoint();
264
344
  try {
265
- lock = acquireCaptureLock(root);
345
+ lock = acquireCaptureLock(root, { command, caller: { entry: captureCommandEntry(), trigger: "manual" } });
266
346
  // Said by the pass that removed it, never quiet, whether or not it then took the lock: a pass that
267
347
  // died holding the lock is worth knowing about.
268
- if (lock.reclaimed) console.error(`capture: reclaimed ${lock.path} from pid ${lock.reclaimed.pid}, which died (started ${lock.reclaimed.startedAt || "?"})`);
348
+ if (lock.reclaimed) reportReclaimedLock({ path: lock.path, ...lock.reclaimed });
269
349
  } catch (err) {
270
- if (err.lockCleanup) {
271
- const c = err.lockCleanup;
272
- const outcome = c.removed ? "the initializing lock was removed"
273
- : c.reason === "gone" ? "the initializing lock was already gone (removed by another party)"
274
- : c.reason === "replaced" ? (c.owner
275
- ? `the lock now belongs to pid ${c.owner.pid} (started ${c.owner.startedAt || "?"}) and was left alone`
276
- : "the lock directory changed or its identity could not be verified, no owner record was readable, and it was left alone")
277
- : `the initializing lock could NOT be removed${c.error ? ` (${c.error})` : ""}; ${c.recovery}`;
278
- console.error(`capture: could not write the owner record of ${c.path}: ${err.message}; ${outcome}`);
279
- }
350
+ reportLockInitializationFailure(err);
280
351
  throw err;
281
352
  }
282
353
  if (lock.held) {
@@ -289,7 +360,9 @@ function withCaptureLock(fn) {
289
360
  }
290
361
  try {
291
362
  let result, failure;
292
- try { cleanupCaptureScratch(root, lock); result = fn(); return result; }
363
+ // The callback's last segment is synchronous too: poll once more before
364
+ // its result can become a success answer.
365
+ try { cleanupCaptureScratch(root, lock); await safePoint(); result = await fn(); await safePoint(done); return result; }
293
366
  catch (err) { failure = err; throw err; }
294
367
  finally {
295
368
  try { writeCaptureStatus(root, { pending: Boolean(failure || result?.pending || result?.held || result?.incomplete || result?.failed) }); }
@@ -303,79 +376,35 @@ function withCaptureLock(fn) {
303
376
  if (!r.released) {
304
377
  // Say what was observed: gone, unreadable (unknown), another owner, or
305
378
  // our own lock that would not go away; never a guess about liveness.
306
- const detail = r.reason === "gone" ? "it was already removed by another party (an operator recovery?); nothing to release"
307
- : r.reason === "not-owner" ? `it now belongs to pid ${r.owner.pid} (started ${r.owner.startedAt || "?"}); left alone`
308
- : r.reason === "unknown-owner" ? `its owner record is missing or unreadable, so it may be an operator removal in progress or a newer pass initializing; left alone; ${r.recovery}`
309
- : `${r.error ? `${r.error}; ` : ""}${r.recovery}`;
310
- console.error(`capture: did not release ${lock.path} (${r.reason}): ${detail}`);
379
+ console.error(`capture: did not release ${lock.path} (${r.reason}): ${releaseDetail(r)}`);
311
380
  process.exitCode = 1;
312
381
  }
313
382
  }
314
383
  }
315
384
 
316
- function pass({ retry = false } = {}) {
317
- // The privacy loader fails closed by exiting; it runs before the lock is
318
- // taken so that exit never leaves the lock behind.
319
- const ignore = loadIgnoreOrExit(root);
320
- return withCaptureLock(() => {
321
- if (retry) retrySetAside(root);
322
- const out = { appended: 0, pending: false };
323
- if (!args["aw-only"]) {
324
- for (const r of captureAllSessions(store, { owner, ignore, collectIssues: false })) {
325
- out.appended += r.appended;
326
- out.pending ||= !r.complete;
327
- const extras = [r.ignored ? `${r.ignored} ignored` : "", r.held ? `${r.held} held` : "", r.incomplete ? `${r.incomplete} incomplete` : ""]
328
- .filter(Boolean)
329
- .join(", ");
330
- log(
331
- `sessions: ${r.sessions} scanned, ${r.appended} new turns in ${r.streams} sessions${extras ? ` (${extras})` : ""} -> ${r.stream}`,
332
- );
333
- }
334
- }
335
- if (!args["sessions-only"]) {
336
- let awEntries = 0;
337
- let awAppended = 0;
338
- let awFailed = 0;
339
- let awFiles = 0;
340
- let awIgnored = 0;
341
- for (const r of captureAwLogs(store, { owner, ignore, collect: false })) {
342
- if (r.ignored) {
343
- awIgnored++;
344
- continue;
345
- }
346
- awFiles++;
347
- awEntries += r.entries;
348
- awAppended += r.appended;
349
- awFailed += r.failed;
350
- out.pending ||= r.failed > 0;
351
- out.appended += r.appended;
352
- if (r.failed) console.error(`aw-log ${r.account}: ${r.failed} entries failed to project`);
353
- }
354
- const ignored = awIgnored ? `, ${awIgnored} ignored` : "";
355
- log(`aw-logs: ${awFiles} files, ${awEntries} entries, ${awAppended} new, ${awFailed} failed${ignored}`);
356
- }
357
- // Index whenever this pass may index, not only when THIS pass appended:
358
- // an append-only pass (--no-index, the hook form) leaves turns behind
359
- // that the next indexing pass must pick up. index.update() walks
360
- // per-stream cursors, so a pass with nothing new is cheap.
361
- if (!args["no-index"]) {
362
- const index = new RecordIndex(store);
363
- try {
364
- index.update();
365
- log("index: updated");
366
- } finally {
367
- index.close();
368
- }
369
- }
370
- return out;
371
- });
385
+ function commandPlan() {
386
+ // Copy caller selection before spawning; only the admitted worker resolves
387
+ // the capture roots. Both selection flags retain their existing empty union.
388
+ const sources = CAPTURE_SOURCES.filter(source => source === "aw" ? !args["sessions-only"] : !args["aw-only"]);
389
+ return captureDefaultRootPlan({ home: homedir(), cwd: process.cwd(), env: process.env, sources });
390
+ }
391
+
392
+ async function pass({ retry = false, trigger = "manual" } = {}) {
393
+ // Privacy refusal unwinds to the command boundary before the lock is
394
+ // taken, leaving no admitted child or lock. The worker independently
395
+ // reloads privacy rules; this preflight supplies the existing actionable error.
396
+ loadIgnoreForCommand(root);
397
+ // Recovery JSON keeps its existing small shape. Never read a later status
398
+ // file after releasing the lock to reconstruct this pass's counters.
399
+ return captureCommandPass(root, { owner, plan: commandPlan(), indexEnabled: !args["no-index"], trigger, retrySetAside: retry }, { log, entry: captureCommandEntry() });
372
400
  }
373
401
 
374
402
  /** A final capture of exact files, one batch per format, under the lock: counts into `outcome`, issues into
375
403
  * `issues`, then the index unless --no-index. → withCaptureLock's answer (`outcome`, or a skip). */
376
- function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, issues) {
377
- return withCaptureLock(() => {
404
+ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, issues, command) {
405
+ return withCaptureLock(async () => {
378
406
  for (const [format, files] of batches) {
407
+ await safePoint();
379
408
  const r = captureSessions(recordStore, { owner: recordOwner, files, format, ignore, final: true });
380
409
  outcome.appended += r.appended;
381
410
  outcome.held += r.held;
@@ -384,6 +413,7 @@ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, is
384
413
  issues.push(...r.issues);
385
414
  }
386
415
  if (!args["no-index"]) { // an earlier append-only pass may have left unindexed turns
416
+ await safePoint();
387
417
  const index = new RecordIndex(recordStore);
388
418
  try {
389
419
  index.update();
@@ -392,7 +422,7 @@ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, is
392
422
  }
393
423
  }
394
424
  return outcome;
395
- });
425
+ }, command, "every batch completed");
396
426
  }
397
427
 
398
428
  /** The outcome vocabulary: complete only with no failure, skip, hold or incomplete tail (and, for --home, no
@@ -440,7 +470,7 @@ function fileKind(stat) {
440
470
  }
441
471
 
442
472
  /** → the exit status. */
443
- function fileCapture() {
473
+ async function fileCapture() {
444
474
  const json = Boolean(args.json);
445
475
  const fail = (code, error, extra = {}) => {
446
476
  if (json) console.log(JSON.stringify({ ...extra, status: "failed", complete: false, code, error }, null, 2));
@@ -505,15 +535,19 @@ function fileCapture() {
505
535
  const outcome = { appended: 0, skipped: false, held: 0, incomplete: 0, failed: 0, ignored: 0 };
506
536
  const issues = [];
507
537
  try {
508
- Object.assign(outcome, captureUnderLock(fileStore, fileOwner, [[args.format, [{ path, pinned }]]], ignore, outcome, issues));
538
+ Object.assign(outcome, await captureUnderLock(fileStore, fileOwner, [[args.format, [{ path, pinned }]]], ignore, outcome, issues, "file"));
509
539
  } catch (err) {
510
540
  // A failed pass may have appended part of the file: never claim a count for it.
511
- return fail("E_CAPTURE_FAILED", err.message || String(err), { ...where, sha256, appended: null });
541
+ // An interruption stops only between whole batches, so its count is confirmed.
542
+ return fail("E_CAPTURE_FAILED", err.message || String(err), { ...where, sha256, appended: err instanceof CaptureInterrupted ? outcome.appended : null });
512
543
  }
513
544
  if (process.exitCode) return fail("E_CAPTURE_FAILED", "capture lock release failed; see stderr for recovery", { ...where, sha256 });
514
545
 
515
546
  const stream = `${fileOwner}~${fmt.source}.${sessionId}`;
516
547
  const turns = withReceiptSummaries(fileStore, summary => summary(stream));
548
+ // The summaries are synchronous: a signal during them is still answered.
549
+ try { await safePoint("every batch completed"); }
550
+ catch (err) { return fail("E_CAPTURE_FAILED", err.message, { ...where, sha256, appended: outcome.appended }); }
517
551
  const status = statusOf(outcome);
518
552
  const { lock: _lock, ...counts } = outcome;
519
553
  const receipt = {
@@ -527,36 +561,40 @@ function fileCapture() {
527
561
  } finally { pinned.close(); }
528
562
  }
529
563
 
530
- if (args.file !== undefined || args.format !== undefined || args.json) process.exit(fileCapture());
564
+ if (args.file !== undefined || args.format !== undefined || args.json) return finish(await observingSignals(fileCapture));
531
565
 
532
566
  if (args["install-hint"]) {
533
- const self = new URL(import.meta.url).pathname;
567
+ const self = new URL("./capture-hook.mjs", import.meta.url).pathname;
534
568
  console.log(`Add to Claude Code settings.json to capture on session stop/end:
535
569
 
536
570
  {
537
571
  "hooks": {
538
- "Stop": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet"}]}],
539
- "SessionEnd": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet"}]}]
572
+ "Stop": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet", "async": false, "timeout": 10}]}],
573
+ "SessionEnd": [{"hooks": [{"type": "command", "command": "node ${self} --sessions-only --no-index --quiet", "async": false, "timeout": 10}]}]
540
574
  }
541
575
  }
542
576
 
543
- Hook passes append turns only (--no-index); the search index is updated by
577
+ Hook acknowledgement means capture launched, not capture completed. The
578
+ harness waits only for the launcher (async:false, timeout:10); its detached
579
+ supervisor inherits no harness output pipes. Hook failures exit 1, never 2.
580
+ These hook passes append turns only (--no-index); the search index is updated by
544
581
  capture --watch (every 15 minutes and on change) or by a plain capture pass.
545
- One pass runs per record root at a time: a hook pass that finds another
546
- running exits at once, and a dropped hook is recovered by any later pass.`);
547
- process.exit(0);
582
+ One pass runs per record root at a time: the detached supervisor skips an
583
+ overlap; launch acknowledgement does not report that later decision. A dropped
584
+ hook is recovered by any later pass.`);
585
+ return finish(0);
548
586
  }
549
587
 
550
588
  if (args.status) {
551
589
  console.log(`root: ${root}\nowner: ${owner}`);
552
- const ignore = loadIgnoreOrExit(root);
590
+ const ignore = loadIgnoreForCommand(root);
553
591
  if (ignore.size > 0) {
554
592
  console.log(`ignore: ${ignore.size} pattern${ignore.size === 1 ? "" : "s"} (${ignoreFilePath(root)})`);
555
593
  }
556
594
  for (const streamId of store.listStreams()) {
557
595
  console.log(` ${streamId}: ${store.readStream(streamId).length} turns`);
558
596
  }
559
- process.exit(0);
597
+ return finish(0);
560
598
  }
561
599
 
562
600
  // One instance home: capture its own sessions and report them with exact
@@ -564,7 +602,7 @@ if (args.status) {
564
602
  // as the OKF harvester can name what it read without timestamps, which tie
565
603
  // and which late capture appends behind. Output is JSON, always: this mode
566
604
  // exists for programs.
567
- if (args.home) {
605
+ if (args.home) await observingSignals(async () => {
568
606
  warnOnStrangerOwner();
569
607
  const unattributed = [];
570
608
  let found = [];
@@ -587,7 +625,7 @@ if (args.home) {
587
625
  if (!formats.has(s.source)) formats.set(s.source, []);
588
626
  formats.get(s.source).push(s);
589
627
  }
590
- Object.assign(outcome, captureUnderLock(store, owner, formats, ignore, outcome, issues));
628
+ Object.assign(outcome, await captureUnderLock(store, owner, formats, ignore, outcome, issues, "home"));
591
629
  withReceiptSummaries(store, summary => {
592
630
  for (const s of found) {
593
631
  const stream = `${owner}~${s.source}.${s.sessionId}`;
@@ -607,13 +645,18 @@ if (args.home) {
607
645
  });
608
646
  }
609
647
  });
648
+ // Summaries are synchronous: a signal that arrived during them is still a
649
+ // signal this command received before answering.
650
+ await safePoint("every batch completed");
610
651
  } catch (err) {
611
652
  error = err.message || String(err);
612
653
  console.error(`capture pass failed: ${error}`);
613
654
  outcome.failed++;
614
655
  // captureSessions can throw after appending part of a directory. Do not
615
656
  // claim zero (or a complete count) for a partially performed failed pass.
616
- outcome.appended = null;
657
+ // An interruption stops only between whole format batches: its count of
658
+ // completed batches is confirmed.
659
+ if (!(err instanceof CaptureInterrupted)) outcome.appended = null;
617
660
  process.exitCode = 1;
618
661
  }
619
662
  if (process.exitCode && !outcome.failed) {
@@ -625,43 +668,61 @@ if (args.home) {
625
668
  ...(error ? { error } : {}), ...(issues.length ? { issues } : {}), ...(unattributed.length ? { unattributed } : {}),
626
669
  }, null, 2));
627
670
  // Let stdout drain naturally, including large session-boundary receipts.
628
- } else {
671
+ }); else {
629
672
 
630
673
  warnOnStrangerOwner();
631
674
  try {
632
- pass();
675
+ await pass({ trigger: args.watch ? "watch" : "manual" });
633
676
  } catch (err) {
677
+ if (err instanceof PrintedCaptureFailure) throw err;
634
678
  // The lock's finally has run by now; one line, then the status.
635
679
  console.error(`capture pass failed: ${err.message}`);
636
- process.exit(1);
680
+ return finish(1);
637
681
  }
638
682
 
639
683
  if (args.watch) {
640
- const roots = [
641
- ...Object.values(SESSION_FORMATS).flatMap((f) => f.defaultRoots()),
642
- defaultCommLogDir(),
643
- ];
644
- let timer = null;
645
- const schedule = () => {
646
- if (timer) clearTimeout(timer);
647
- timer = setTimeout(() => {
648
- timer = null;
649
- try {
650
- pass();
651
- } catch (err) {
652
- console.error(`capture pass failed: ${err.message}`);
653
- }
654
- }, 2000);
655
- };
656
- for (const dir of roots) {
684
+ const queue = captureWatchQueue(() => pass({ trigger: "watch" }), {
685
+ onError: err => {
686
+ process.exitCode = 1;
687
+ // A privacy refusal used to terminate immediately. It still stops the
688
+ // watch, before child admission, but lets its already printed error drain.
689
+ if (err instanceof PrintedCaptureFailure) { stop(); return; }
690
+ console.error(`capture pass failed: ${err.message}`);
691
+ },
692
+ });
693
+ const watchers = [], plan = commandPlan();
694
+ // These are notification hints only. Their enumeration has parent metadata
695
+ // cost, supplies no capture authority, and may fail independently of a pass.
696
+ for (const source of plan.sources) {
657
697
  try {
658
- watch(dir, { recursive: true }, schedule);
659
- log(`watching ${dir}`);
660
- } catch (err) {
661
- console.error(`cannot watch ${dir}: ${err.message}`);
662
- }
698
+ for (const dir of resolveCaptureDefaultRoots(plan, source)) {
699
+ try {
700
+ const watcher = watch(dir, { recursive: true }, () => queue.schedule());
701
+ watcher.on("error", err => { console.error(`cannot watch ${dir}: ${err.message}`); watcher.close(); });
702
+ watchers.push(watcher);
703
+ log(`watching ${dir}`);
704
+ } catch (err) { console.error(`cannot watch ${dir}: ${err.message}`); }
705
+ }
706
+ } catch (err) { console.error(`cannot select ${source} watch hints: ${err.message}`); }
663
707
  }
664
- setInterval(schedule, 15 * 60 * 1000); // reconcile even if events were missed
708
+ const interval = setInterval(() => queue.schedule(), 15 * 60 * 1000);
709
+ const stop = () => {
710
+ queue.close(); clearInterval(interval);
711
+ for (const watcher of watchers) watcher.close();
712
+ process.off("SIGINT", stop); process.off("SIGTERM", stop);
713
+ // If a pass is active its supervisor also observes this signal and owns
714
+ // child termination/reaping and lock release. No new pass may start.
715
+ };
716
+ process.on("SIGINT", stop); process.on("SIGTERM", stop);
717
+ }
718
+
719
+ }
665
720
  }
666
721
 
722
+ try { await main(); }
723
+ catch (error) {
724
+ if (!(error instanceof PrintedCaptureFailure)) throw error;
725
+ // Privacy already printed its one actionable error. No duplicate diagnostic
726
+ // and no later mode may run, but both output pipes can finish normally.
727
+ process.exitCode = 1;
667
728
  }
@@ -3,14 +3,19 @@
3
3
  //
4
4
  // recall <query...> FTS5 query over mail, chat, sessions
5
5
  // recall --kind mail <query...> filter by kind (mail|chat|session|note)
6
- // recall --thread <thread> [query] filter/list by thread
7
- // recall --thread <thread> --json the thread's turns in journal order,
6
+ // recall --thread <thread> [query] filter/list by thread; text listings
7
+ // without a query are timestamp-sorted
8
+ // recall --thread <thread> --json the thread's turns in capture sequence,
8
9
  // [--after <id>] [--until <id>] with extracted text; exact id bounds
9
10
  // [--limit n] [--ids-only] (after is exclusive, until inclusive);
10
11
  // --ids-only lists id, ts and the bytes
11
12
  // each turn occupies in the --json output
12
13
  // (text extracted but not emitted), so a
13
- // consumer can size a window it will read
14
+ // consumer can size a window it will read.
15
+ // For a thread spanning aw accounts the
16
+ // cross-account sequence is unspecified
17
+ // and an id window may hold turns from
18
+ // more than one account
14
19
  // recall --from <name> <query...> filter by speaker
15
20
  // recall --limit N max results (default 20)
16
21
  // recall --show <turn-id> print one turn as JSON