@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.
- package/README.md +1 -1
- package/bin/oats.mjs +27 -12
- package/docs/capabilities.md +1 -1
- package/docs/desktop-cli-api.md +30 -2
- package/docs/execution-targets.md +89 -4
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +13 -0
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/release-notes/v0.63.0.md +135 -0
- package/docs/souls-and-instances.md +6 -1
- package/docs/upgrading.md +135 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +73 -23
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/lib/tree-copy.mjs +188 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +200 -139
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +116 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1527 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +62 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +65 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +110 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +137 -17
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +116 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +136 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +241 -0
- package/packages/record/lib/capture-worker.mjs +74 -0
- package/packages/record/lib/derived-state.mjs +58 -17
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +121 -66
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +46 -14
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/skills/oats-getting-started/SKILL.md +1 -1
- 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 {
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
224
|
+
return finish(2);
|
|
172
225
|
}
|
|
173
226
|
console.error(`capture: ${err.message}\n\n${USAGE}`);
|
|
174
|
-
|
|
227
|
+
return finish(2);
|
|
175
228
|
}
|
|
176
229
|
|
|
177
230
|
if (args.help) {
|
|
178
231
|
console.log(USAGE);
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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)
|
|
348
|
+
if (lock.reclaimed) reportReclaimedLock({ path: lock.path, ...lock.reclaimed });
|
|
269
349
|
} catch (err) {
|
|
270
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
317
|
-
//
|
|
318
|
-
//
|
|
319
|
-
const
|
|
320
|
-
return
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
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
|
-
|
|
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)
|
|
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
|
|
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:
|
|
546
|
-
|
|
547
|
-
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
680
|
+
return finish(1);
|
|
637
681
|
}
|
|
638
682
|
|
|
639
683
|
if (args.watch) {
|
|
640
|
-
const
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
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
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
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);
|
|
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
|
-
//
|
|
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
|