@awebai/oats 0.61.0 → 0.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +26 -11
  3. package/docs/capabilities.md +1 -1
  4. package/docs/execution-targets.md +49 -3
  5. package/docs/implementation.md +2 -1
  6. package/docs/named-test-runs.md +382 -0
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-notes/v0.62.0.md +223 -0
  10. package/docs/upgrading.md +133 -11
  11. package/docs/workspaces.md +1 -1
  12. package/lib/core.mjs +2 -2
  13. package/lib/doctor-capture.mjs +35 -0
  14. package/lib/session-viewer.mjs +86 -7
  15. package/package-catalog.json +1 -1
  16. package/package.json +1 -1
  17. package/packages/client/cli-locator.mjs +2 -2
  18. package/packages/record/README.md +87 -13
  19. package/packages/record/bin/capture-hook.mjs +8 -0
  20. package/packages/record/bin/capture.mjs +143 -124
  21. package/packages/record/bin/recall.mjs +8 -3
  22. package/packages/record/bin/setup.mjs +115 -225
  23. package/packages/record/bin/turn-record.mjs +2 -2
  24. package/packages/record/docs/capture-service.md +1443 -28
  25. package/packages/record/docs/capture-status.schema.json +429 -12
  26. package/packages/record/lib/capture-admission.mjs +82 -0
  27. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  28. package/packages/record/lib/capture-aw.mjs +31 -12
  29. package/packages/record/lib/capture-budget.mjs +31 -0
  30. package/packages/record/lib/capture-cc.mjs +39 -6
  31. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  32. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  33. package/packages/record/lib/capture-command-operation.mjs +37 -0
  34. package/packages/record/lib/capture-command-output.mjs +61 -0
  35. package/packages/record/lib/capture-command-worker.mjs +6 -0
  36. package/packages/record/lib/capture-command.mjs +48 -0
  37. package/packages/record/lib/capture-completion.mjs +152 -0
  38. package/packages/record/lib/capture-context.mjs +50 -0
  39. package/packages/record/lib/capture-default-roots.mjs +30 -0
  40. package/packages/record/lib/capture-discovery.mjs +114 -0
  41. package/packages/record/lib/capture-failures.mjs +45 -0
  42. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  43. package/packages/record/lib/capture-health-installation.mjs +117 -0
  44. package/packages/record/lib/capture-health.mjs +116 -0
  45. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  46. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  47. package/packages/record/lib/capture-hook.mjs +26 -0
  48. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  49. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  50. package/packages/record/lib/capture-index-reset.mjs +109 -0
  51. package/packages/record/lib/capture-index-work.mjs +77 -0
  52. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  53. package/packages/record/lib/capture-issues.mjs +15 -2
  54. package/packages/record/lib/capture-lock.mjs +102 -16
  55. package/packages/record/lib/capture-native-unit.mjs +322 -0
  56. package/packages/record/lib/capture-pass.mjs +102 -0
  57. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  58. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  59. package/packages/record/lib/capture-retry.mjs +102 -0
  60. package/packages/record/lib/capture-run.mjs +125 -0
  61. package/packages/record/lib/capture-scratch.mjs +12 -3
  62. package/packages/record/lib/capture-service-definition.mjs +104 -0
  63. package/packages/record/lib/capture-service-install.mjs +362 -0
  64. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  65. package/packages/record/lib/capture-service-runner.mjs +18 -0
  66. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  67. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  68. package/packages/record/lib/capture-source-queue.mjs +199 -0
  69. package/packages/record/lib/capture-source-work.mjs +85 -0
  70. package/packages/record/lib/capture-state.mjs +16 -71
  71. package/packages/record/lib/capture-status.mjs +171 -0
  72. package/packages/record/lib/capture-supervisor.mjs +117 -0
  73. package/packages/record/lib/capture-watch.mjs +32 -0
  74. package/packages/record/lib/capture-work-session.mjs +238 -0
  75. package/packages/record/lib/capture-worker.mjs +58 -0
  76. package/packages/record/lib/derived-state.mjs +28 -15
  77. package/packages/record/lib/file-lines.mjs +22 -6
  78. package/packages/record/lib/formats.mjs +4 -3
  79. package/packages/record/lib/index-capture.mjs +97 -0
  80. package/packages/record/lib/index-db.mjs +3 -17
  81. package/packages/record/lib/index-reset.mjs +19 -0
  82. package/packages/record/lib/store.mjs +36 -11
  83. package/packages/record/lib/transcript-prefix.mjs +125 -0
  84. package/skills/oats-getting-started/SKILL.md +1 -1
  85. package/docs/macos-test-runs.md +0 -246
@@ -0,0 +1,152 @@
1
+ // Private final metadata verification, never a reusable completion certificate.
2
+ // Capture-state reservation precedes index reservation, as in group processing.
3
+ // There are no stream-lock acquisitions or content reads while they are held.
4
+ import { readdirSync, statSync } from "node:fs";
5
+ import { fileVersion, statVersion, sameVersion } from "./derived-state.mjs";
6
+ import { validStreamId } from "./store.mjs";
7
+
8
+ const terminal = new Set(["complete", "pending", "set-aside", "ignored", "failed"]);
9
+ const blockedKinds = ["capture-retry", "capture-cleanup-retry", "capture-discovery-attempt",
10
+ "recovery-allocation", "recovery-stage", "source-queue-garbage", "index-inventory-garbage",
11
+ "set-aside", "capture-failed"];
12
+ function directoryVersion(path) {
13
+ try {
14
+ const stat = statSync(path, { bigint: true });
15
+ if (!stat.isDirectory()) throw new Error("capture completion streams root is not a directory");
16
+ return statVersion(stat);
17
+ } catch (error) { if (error.code === "ENOENT") return null; throw error; }
18
+ }
19
+
20
+ function sourceVisits(state, sweep, { limit, stopped, work, admitted }) {
21
+ let position = 0, terminalSources = sweep.discovered && !admitted, pending = false;
22
+ while (true) {
23
+ if (stopped()) return { terminal: false, pending: true };
24
+ const rows = state.db.prepare(`SELECT position,outcome FROM capture_sources
25
+ WHERE scope=? AND position>? ORDER BY position LIMIT ?`).all(sweep.id, position, limit);
26
+ if (work) work.sourceRows = (work.sourceRows ?? 0) + rows.length;
27
+ for (const row of rows) {
28
+ if (stopped()) return { terminal: false, pending: true };
29
+ if (row.outcome !== "ready" && !terminal.has(row.outcome)) throw new Error("invalid capture source outcome");
30
+ if (row.outcome === "ready") terminalSources = false;
31
+ if (row.outcome !== "complete" && row.outcome !== "ignored") pending = true;
32
+ position = row.position;
33
+ }
34
+ if (rows.length < limit) break;
35
+ }
36
+ return { terminal: terminalSources, pending };
37
+ }
38
+
39
+ // Append-only mode cannot qualify index evidence or full completion. It only
40
+ // permits terminal source visits to be rediscovered after a final receipt.
41
+ // Index requests/inventory/bindings survive this source-only retirement.
42
+ export function auditCaptureSourceRetirement(session, { limit = 128, work } = {}) {
43
+ const { state, queue, sourceDiscovery, start, run } = session;
44
+ if (session.indexEnabled !== false || session.index || session.inventory || state.depth || start.pass.finalize ||
45
+ !Number.isSafeInteger(limit) || limit < 1 || limit > 128)
46
+ throw new Error("source retirement requires a normal append-only worker");
47
+ const result = { complete: false, pending: true, needsWork: false, stopped: false, sourceTerminal: false };
48
+ if (session.issues && !session.issues.complete()) return { ...result, needsWork: true };
49
+ const stopped = () => { if (start.budget.sample() === null) return false; result.stopped = true; return true; };
50
+ if (stopped()) return result;
51
+ return state.transaction(() => {
52
+ const sweep = queue.current();
53
+ const admitted = state.get("capture-admission", "active") !== null || state.get("capture-cleanup", "active") !== null ||
54
+ state.db.prepare("SELECT 1 AS found FROM state WHERE kind='capture-discovery-attempt' LIMIT 1").get()?.found === 1;
55
+ const sources = sourceVisits(state, sweep, { limit, stopped, work, admitted });
56
+ if (stopped()) return result;
57
+ result.sourceTerminal = sources.terminal && !sourceDiscovery?.current().groups.some(group => !group.complete || group.failure);
58
+ if (result.sourceTerminal) state.set("capture-sweep-retirement", queue.owner,
59
+ { runId: run.id, sourceScope: sweep.id, indexScope: null });
60
+ return result;
61
+ });
62
+ }
63
+
64
+ export function auditCaptureCompletion(session, { limit = 128, work } = {}) {
65
+ const { state, index, queue, inventory, outcomes, sourceDiscovery, start, run } = session;
66
+ if (state.depth || start.pass.finalize || !Number.isSafeInteger(limit) || limit < 1 || limit > 128)
67
+ throw new Error("capture completion requires a normal worker outside processing");
68
+ const result = { complete: false, pending: false, needsWork: false, stopped: false, sourceTerminal: false };
69
+ if (session.issues && !session.issues.complete()) return { ...result, pending: true, needsWork: true };
70
+ const stopped = () => {
71
+ if (start.budget.sample() === null) return false;
72
+ result.stopped = true; result.pending = true; return true;
73
+ };
74
+ if (stopped()) return result;
75
+ return state.transaction(() => {
76
+ index.db.exec("BEGIN IMMEDIATE");
77
+ try {
78
+ // No cached audit position survives this call. Supported writers cannot
79
+ // change either database during verification. Raw filesystem edits have
80
+ // only the existing per-journal metadata qualification, not a root-wide
81
+ // historical integrity or instantaneous filesystem snapshot guarantee.
82
+ const sweep = queue.current(), union = inventory.current();
83
+ const admission = state.get("capture-admission", "active") !== null ||
84
+ state.get("capture-cleanup", "active") !== null ||
85
+ state.get("capture-index-reset", "current") !== null ||
86
+ state.db.prepare("SELECT 1 AS found FROM state WHERE kind='capture-discovery-attempt' LIMIT 1").get()?.found === 1;
87
+ result.pending = admission || !sweep.discovered || union.phase !== "complete";
88
+ if (sourceDiscovery?.current().groups.some(group => !group.complete || group.failure)) result.pending = true;
89
+ const hasKind = state.db.prepare("SELECT 1 AS found FROM state WHERE kind=? LIMIT 1");
90
+ for (const kind of blockedKinds) if (hasKind.get(kind)?.found === 1) result.pending = true;
91
+
92
+ const sources = sourceVisits(state, sweep, { limit, stopped, work, admitted: admission });
93
+ if (result.stopped) return result;
94
+ const sourcesDone = sources.terminal;
95
+ if (sources.pending) result.pending = true;
96
+ result.sourceTerminal = sourcesDone;
97
+
98
+ // Reconcile names that arrived after discovery (including before its
99
+ // saved cursor). Membership never promotes them to processed outcomes.
100
+ const member = state.db.prepare("SELECT 1 AS found FROM capture_index_inventory WHERE scope=? AND stream=?");
101
+ const include = names => {
102
+ const missing = names.filter(name => member.get(inventory.id, name)?.found !== 1);
103
+ if (missing.length) { inventory.include(missing); result.needsWork = true; result.pending = true; }
104
+ return missing.length !== 0;
105
+ };
106
+ let after = "";
107
+ while (true) {
108
+ if (stopped()) return result;
109
+ const rows = index.db.prepare("SELECT stream FROM index_state WHERE stream>? ORDER BY stream LIMIT ?").all(after, limit);
110
+ if (work) work.indexNames = (work.indexNames ?? 0) + rows.length;
111
+ if (rows.some(row => !validStreamId(row.stream))) throw new Error("invalid indexed stream during capture completion");
112
+ if (include(rows.map(row => row.stream))) return result;
113
+ after = rows.at(-1)?.stream ?? after;
114
+ if (rows.length < limit) break;
115
+ }
116
+ const path = index.store.streamsDir(), before = directoryVersion(path);
117
+ if (union.directory && (!before || union.directory.dev !== before.dev || union.directory.ino !== before.ino))
118
+ throw new Error("capture completion streams directory changed");
119
+ const names = before === null ? [] : readdirSync(path).sort();
120
+ if (work) work.directoryEntries = (work.directoryEntries ?? 0) + names.length;
121
+ for (let offset = 0; offset < names.length; offset += limit) {
122
+ const live = [];
123
+ for (const name of names.slice(offset, offset + limit)) {
124
+ if (stopped()) return result;
125
+ if (validStreamId(name) && fileVersion(index.store.journalPath(name))) live.push(name);
126
+ }
127
+ if (include(live)) return result;
128
+ }
129
+ if (!sameVersion(before, directoryVersion(path))) { result.pending = true; result.needsWork = true; return result; }
130
+ after = "";
131
+ while (true) {
132
+ if (stopped()) return result;
133
+ const page = outcomes.audit({ after, limit, stopped });
134
+ if (work) work.outcomeRows = (work.outcomeRows ?? 0) + page.checked;
135
+ if (page.stopped || stopped()) return result;
136
+ if (page.pending) result.pending = true;
137
+ if (page.complete) break;
138
+ after = page.after;
139
+ }
140
+ if (!sameVersion(before, directoryVersion(path))) { result.pending = true; result.needsWork = true; return result; }
141
+ if (stopped()) return result;
142
+ // Retirement is conditional on a subsequently published final receipt.
143
+ // Death before that receipt must resume this scope, not recount inputs
144
+ // in a new scope of the same unfinished run. Terminal pending inputs can
145
+ // be rediscovered on the next pass without ever qualifying as success.
146
+ if (sourcesDone && union.phase === "complete") state.set("capture-sweep-retirement", queue.owner,
147
+ { runId: run.id, sourceScope: sweep.id, indexScope: inventory.id });
148
+ result.complete = !result.pending;
149
+ return result;
150
+ } finally { index.db.exec("ROLLBACK"); }
151
+ });
152
+ }
@@ -0,0 +1,50 @@
1
+ // Package-private synchronous work context. Public library calls never enter
2
+ // this scope implicitly. A worker chooses bounded work before entering it.
3
+ import { DerivedState, fileVersion, sameVersion } from "./derived-state.mjs";
4
+ import { commitCaptureAdmission, finishCaptureAdmission } from "./capture-admission.mjs";
5
+
6
+ const contexts = new WeakMap();
7
+ export const captureContext = store => contexts.get(store);
8
+
9
+ // All stream locks precede the database write transaction, matching ordinary
10
+ // writers' stream -> database order. Acquiring another stream inside the
11
+ // transaction would deadlock against a public caller holding that stream.
12
+ export function withCaptureGroup(store, streams, fn, { state, check = () => {}, batchBytes = 8 * 1024 * 1024, admission, admissionNow } = {}) {
13
+ if (!Number.isSafeInteger(batchBytes) || batchBytes < 1 || batchBytes > 8 * 1024 * 1024) throw new Error("invalid capture work-group batch size");
14
+ if (contexts.has(store)) throw new Error("capture work groups cannot nest");
15
+ if (state?.depth) throw new Error("capture work group cannot acquire streams inside a transaction");
16
+ const held = new Set();
17
+ for (const stream of streams) {
18
+ store.journalPath(stream);
19
+ held.add(stream);
20
+ if (held.size > 128) throw new Error("capture work group exceeds 128 streams");
21
+ }
22
+ const ordered = [...held].sort();
23
+ const acquire = index => {
24
+ check();
25
+ if (index < ordered.length) return store.withStreamLock(ordered[index], () => acquire(index + 1), { check });
26
+ const owned = !state, derived = state ?? new DerivedState(store.root);
27
+ try {
28
+ if (admission) {
29
+ if (!Array.isArray(admission.members) || admission.members.length > 128) throw new Error("invalid capture admission selection");
30
+ for (const member of admission.members) {
31
+ check();
32
+ if (!held.has(member?.stream) || !sameVersion(member.generation, fileVersion(store.journalPath(member.stream)))) {
33
+ throw new Error("capture admission journal changed before locking");
34
+ }
35
+ }
36
+ }
37
+ const admitted = admission ? commitCaptureAdmission(derived, admission, held, { now: admissionNow }) : null;
38
+ return derived.transaction(() => {
39
+ contexts.set(store, { state: derived, held, batchBytes, admission: admitted });
40
+ try {
41
+ const result = fn();
42
+ if (result && typeof result.then === "function") throw new Error("capture work groups must be synchronous");
43
+ if (admitted) finishCaptureAdmission(derived, admitted.id);
44
+ return result;
45
+ } finally { contexts.delete(store); }
46
+ });
47
+ } finally { if (owned) derived.close(); }
48
+ };
49
+ return acquire(0);
50
+ }
@@ -0,0 +1,30 @@
1
+ // Private, serializable caller selection. Constructing this plan performs no
2
+ // filesystem work. Only an admitted discovery worker resolves default roots;
3
+ // the caller need not widen the child's inherited environment to convey them.
4
+ import { isAbsolute } from "node:path";
5
+ import { SESSION_FORMATS } from "./formats.mjs";
6
+ import { defaultCommLogDir } from "./capture-aw.mjs";
7
+
8
+ const formats = ["cc", "pi", "codex", "aw"];
9
+ const locations = ["CLAUDE_CONFIG_DIR", "PI_CODING_AGENT_DIR", "PI_CODING_AGENT_SESSION_DIR", "CODEX_HOME"];
10
+ const absolute = value => typeof value === "string" && isAbsolute(value) && !value.includes("\0");
11
+
12
+ export function captureDefaultRootPlan({ home, cwd, env = {}, sources = formats } = {}) {
13
+ if (!absolute(home) || !absolute(cwd) || !env || typeof env !== "object" || Array.isArray(env) ||
14
+ !Array.isArray(sources) || sources.some(source => !formats.includes(source)) || new Set(sources).size !== sources.length)
15
+ throw new Error("invalid capture default-root selection");
16
+ const selected = {};
17
+ for (const key of locations) if (env[key] !== undefined) {
18
+ if (typeof env[key] !== "string" || env[key].includes("\0")) throw new Error("invalid capture root environment");
19
+ selected[key] = env[key];
20
+ }
21
+ return { kind: "default-roots", home, cwd, env: selected, sources: formats.filter(source => sources.includes(source)) };
22
+ }
23
+
24
+ export function resolveCaptureDefaultRoots(plan, source) {
25
+ if (!plan.sources.includes(source)) throw new Error("capture default-root source is not selected");
26
+ // Keep the public selectors' configured/optional absence, tilde, relative
27
+ // path and profile ordering contracts. In particular AW does not use XDG.
28
+ return source === "aw" ? [defaultCommLogDir(plan.home)] :
29
+ SESSION_FORMATS[source].defaultRoots(plan.home, plan.env, { cwd: plan.cwd });
30
+ }
@@ -0,0 +1,114 @@
1
+ // Private resumable native-directory walk. The durable checkpoint is only the
2
+ // active directory stack and exact last basename, never a whole-file state map.
3
+ // Per-directory Dirent arrays retain the existing stable localeCompare order;
4
+ // readdir/sort metadata cost is separate from content bytes and can recur after
5
+ // restart. A live walker caches ONLY its active stack, releasing arrays on pop.
6
+ import { statSync } from "node:fs";
7
+ import { join } from "node:path";
8
+ import { sortedSessionEntries } from "./formats.mjs";
9
+ import { guardCapturedPath } from "./native-history.mjs";
10
+
11
+ const nameValid = value => typeof value === "string" && value && value !== "." && value !== ".." && !/[\/\\\0]/.test(value);
12
+ const identityOf = stat => ({ dev: String(stat.dev), ino: String(stat.ino) });
13
+ const sameIdentity = (a, b) => a?.dev === b?.dev && a?.ino === b?.ino;
14
+ const ccDirectory = (entry, path) => entry.isDirectory() ||
15
+ entry.isSymbolicLink() && !entry.name.endsWith(".jsonl") && statSync(path).isDirectory();
16
+
17
+ export class NativeCaptureDiscovery {
18
+ constructor(format, root, checkpoint = null) {
19
+ if (!["cc", "pi", "codex"].includes(format) || typeof root !== "string" || !root) throw new Error("invalid capture discovery root");
20
+ this.format = format; this.root = root; this.frames = [];
21
+ if (checkpoint === null) checkpoint = { format, root, complete: false, stack: [{ name: null, after: null }] };
22
+ if (checkpoint.format !== format || checkpoint.root !== root || typeof checkpoint.complete !== "boolean" ||
23
+ !Array.isArray(checkpoint.stack) || checkpoint.stack.length > (format === "pi" ? 2 : 4) ||
24
+ checkpoint.complete !== (checkpoint.stack.length === 0)) throw new Error("invalid capture discovery checkpoint");
25
+ let path = root;
26
+ for (const [depth, item] of checkpoint.stack.entries()) {
27
+ if (!item || (depth === 0 ? item.name !== null : !nameValid(item.name)) ||
28
+ depth > 0 && item.name !== checkpoint.stack[depth - 1].after ||
29
+ item.after !== null && !nameValid(item.after) ||
30
+ item.identity != null && (typeof item.identity.dev !== "string" || typeof item.identity.ino !== "string") ||
31
+ format === "cc" && depth === 3 && item.name !== "subagents") throw new Error("invalid capture discovery stack");
32
+ if (depth) path = join(path, item.name);
33
+ this.frames.push({ name: item.name, after: item.after, identity: item.identity ?? null, path, depth,
34
+ // A resumed selected directory cannot silently disappear as an absent
35
+ // default. Only a newly entered optional root has that meaning.
36
+ optional: depth === 0 && checkpoint.stack.length === 1 && item.after === null });
37
+ }
38
+ }
39
+
40
+ checkpoint() {
41
+ return { format: this.format, root: this.root, complete: this.frames.length === 0,
42
+ stack: this.frames.map(({ name, after, identity }) => ({ name, after, identity: identity ?? null })) };
43
+ }
44
+
45
+ advance({ limit = 128, stopped = () => false, work } = {}) {
46
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 2000) throw new Error("invalid capture discovery budget");
47
+ if (this.closed || this.failed) throw new Error("capture discovery is closed or failed");
48
+ const files = []; let visited = 0;
49
+ try {
50
+ // Cached arrays do not qualify a replaced selected ancestor. Recheck the
51
+ // bounded active stack on every page, including within the same worker.
52
+ for (const frame of this.frames) if (frame.identity) {
53
+ guardCapturedPath(frame.path);
54
+ if (!sameIdentity(frame.identity, identityOf(statSync(frame.path, { bigint: true }))))
55
+ throw new Error("capture discovery directory identity changed");
56
+ }
57
+ while (this.frames.length && visited < limit && !stopped()) {
58
+ const frame = this.frames.at(-1);
59
+ guardCapturedPath(frame.path);
60
+ if (!frame.entries) {
61
+ let before;
62
+ try { before = statSync(frame.path, { bigint: true }); }
63
+ catch (error) {
64
+ if (frame.optional && !frame.identity && error.code === "ENOENT") { this.frames.pop(); continue; }
65
+ throw error;
66
+ }
67
+ if (frame.identity && !sameIdentity(frame.identity, identityOf(before))) throw new Error("capture discovery directory identity changed");
68
+ frame.entries = sortedSessionEntries(frame.path);
69
+ const after = statSync(frame.path, { bigint: true });
70
+ if (!sameIdentity(identityOf(before), identityOf(after))) throw new Error("capture discovery directory changed during enumeration");
71
+ frame.identity = identityOf(after);
72
+ if (work) { work.directoriesRead = (work.directoriesRead ?? 0) + 1;
73
+ work.directoryEntriesRead = (work.directoryEntriesRead ?? 0) + frame.entries.length; }
74
+ const anchor = frame.after === null ? -1 : frame.entries.findIndex(entry => entry.name === frame.after);
75
+ // Exact-name anchoring preserves stable ties. If the last name vanished,
76
+ // replay its equivalence class conservatively; inventory insertion is
77
+ // idempotent. Newly inserted earlier names belong to the next sweep.
78
+ frame.position = frame.after === null ? 0 : anchor >= 0 ? anchor + 1 :
79
+ frame.entries.findIndex(entry => entry.name.localeCompare(frame.after) >= 0);
80
+ if (frame.position < 0) frame.position = frame.entries.length;
81
+ }
82
+ const entry = frame.entries[frame.position];
83
+ if (!entry) { this.frames.pop(); continue; }
84
+ frame.position++; frame.after = entry.name; visited++;
85
+ const path = join(frame.path, entry.name); guardCapturedPath(path);
86
+ let descend = false, file = false;
87
+ if (this.format === "cc") {
88
+ if (frame.depth < 2) {
89
+ descend = ccDirectory(entry, path);
90
+ file = !descend && entry.name.endsWith(".jsonl");
91
+ } else if (frame.depth === 2) {
92
+ if (entry.name === "subagents") {
93
+ if (!ccDirectory(entry, path)) throw new Error(`session subagents root is not a directory: ${path}`);
94
+ descend = true;
95
+ }
96
+ } else file = entry.name.endsWith(".jsonl");
97
+ } else {
98
+ if (entry.name.endsWith(".jsonl") && !entry.isDirectory()) file = true;
99
+ else if (entry.isDirectory() || entry.isSymbolicLink() && statSync(path).isDirectory())
100
+ descend = frame.depth < (this.format === "pi" ? 1 : 3);
101
+ }
102
+ if (file) files.push(path);
103
+ if (descend) this.frames.push({ name: entry.name, after: null, path, depth: frame.depth + 1, optional: false });
104
+ }
105
+ } catch (error) { this.failed = true; this.close(); throw error; }
106
+ if (work) work.entriesVisited = (work.entriesVisited ?? 0) + visited;
107
+ return { files, visited, complete: this.frames.length === 0, checkpoint: this.checkpoint() };
108
+ }
109
+
110
+ close() {
111
+ for (const frame of this.frames) { delete frame.entries; delete frame.position; }
112
+ this.closed = true;
113
+ }
114
+ }
@@ -0,0 +1,45 @@
1
+ // Shared operational-failure projection and fixed retry schedule. This module
2
+ // opens no database and creates no failure evidence: callers may persist a row
3
+ // only for an actually failed, durably admitted SINGLE-stream unit. Its offset
4
+ // is the unit start, never an assertion about the exact failing inner frame.
5
+ export const FAILURE_REASONS = ["heap", "rss", "deadline", "interrupted", "io"];
6
+ const INTERVAL_MS = 900_000;
7
+
8
+ export function retryAfterAttempt(attempts, now = Date.now()) {
9
+ if (!Number.isSafeInteger(attempts) || attempts < 1 || !Number.isSafeInteger(now) || now < 0) {
10
+ throw new Error("invalid capture retry time");
11
+ }
12
+ return new Date(now + INTERVAL_MS * 2 ** Math.min(attempts, 4)).toISOString();
13
+ }
14
+
15
+ export function validFailure(row) {
16
+ return row !== null && typeof row === "object" && typeof row.stream === "string" && row.stream.length > 0 &&
17
+ Number.isSafeInteger(row.offset) && row.offset >= 0 && FAILURE_REASONS.includes(row.reason) &&
18
+ Number.isSafeInteger(row.attempts) && row.attempts > 0 && typeof row.nextRetryAt === "string" &&
19
+ Number.isFinite(Date.parse(row.nextRetryAt)) && new Date(row.nextRetryAt).toISOString() === row.nextRetryAt;
20
+ }
21
+
22
+ // Skipping a deferred unit must not call this function: only an actual failed
23
+ // attempt increments the count or moves its retry date. Journal generation and
24
+ // durable admission identity remain private state alongside the public row.
25
+ export function failureAfterAttempt(previous, { stream, offset, reason }, now = Date.now()) {
26
+ if (previous !== null && previous !== undefined && (!validFailure(previous) || previous.stream !== stream)) {
27
+ throw new Error("invalid previous capture failure");
28
+ }
29
+ if (!Number.isSafeInteger(now) || now < 0) throw new Error("invalid capture failure time");
30
+ const attempts = (previous?.attempts ?? 0) + 1;
31
+ const next = { stream, offset, reason, attempts,
32
+ nextRetryAt: retryAfterAttempt(attempts, now) };
33
+ if (!validFailure(next)) throw new Error("invalid capture failure");
34
+ return next;
35
+ }
36
+
37
+ export function validFailureBacklog(backlog, { legacy = false } = {}) {
38
+ if (!backlog || typeof backlog !== "object") return false;
39
+ if (legacy && !["failedCount", "failed", "failedTruncated"].some(key => Object.hasOwn(backlog, key))) return true;
40
+ return Number.isSafeInteger(backlog.failedCount) && backlog.failedCount >= 0 && Array.isArray(backlog.failed) &&
41
+ backlog.failed.length === Math.min(backlog.failedCount, 100) && backlog.failed.every(validFailure) &&
42
+ backlog.failedTruncated === (backlog.failedCount > 100);
43
+ }
44
+
45
+ export const emptyFailureBacklog = () => ({ failedCount: 0, failed: [], failedTruncated: false });
@@ -0,0 +1,13 @@
1
+ // Fixed private package entry for the kernel's bounded offline diagnosis.
2
+ // No store construction, capture dispatch, manager or configurable executable.
3
+ import { homedir } from "node:os";
4
+ import { join } from "node:path";
5
+ import { captureHealthForDoctor } from "./capture-health.mjs";
6
+
7
+ try {
8
+ const root = process.env.TURN_RECORD_ROOT ?? join(homedir(), ".turn-record");
9
+ console.log(JSON.stringify(captureHealthForDoctor(root)));
10
+ } catch (error) {
11
+ console.log(JSON.stringify({ status: "failed", error: error.message }));
12
+ process.exitCode = 1;
13
+ }
@@ -0,0 +1,117 @@
1
+ // Offline installation evidence, not manager registration or schedule health.
2
+ // Refuse indeterminate evidence instead of calling it an absent installation.
3
+ import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, statSync } from "node:fs";
4
+ import { join, parse, resolve, sep } from "node:path";
5
+ import { captureServiceOwnership } from "./capture-service-ownership.mjs";
6
+ import { capturePendingActivationName, captureServiceLabel, captureServiceUnit, captureServiceTimer } from "./capture-service-definition.mjs";
7
+ import { isCaptureHook, isCurrentCaptureHook } from "./capture-hook-ownership.mjs";
8
+
9
+ const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode &&
10
+ a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
11
+
12
+ // Limits are private reader guards, not capture policy. They bound enumeration,
13
+ // allocations and parsing; exceeding one is an unavailable diagnosis, not a
14
+ // truncated proof of absence. The existing isolated DB reader has its own hard
15
+ // timeout. Filesystem syscalls still depend on the host filesystem responding.
16
+ export function captureInstallation(root, { home, platform, check = () => {} }) {
17
+ let remaining = 16 * 1024 * 1024;
18
+ function stat(path) {
19
+ const absolute = resolve(path), prefix = parse(absolute).root;
20
+ const parts = absolute.slice(prefix.length).split(sep).filter(Boolean);
21
+ if (parts.length > 256) throw new Error("installation path exceeds the reader component limit");
22
+ let current = prefix, result = statSync(prefix);
23
+ for (let i = 0; i < parts.length; i++) {
24
+ check(); current = join(current, parts[i]);
25
+ try { result = lstatSync(current); }
26
+ catch (error) { if (error.code === "ENOENT") return null; throw error; }
27
+ // A dangling/unreadable link is unknown, even when a descendant name
28
+ // would otherwise produce ENOENT. Following a readable link is read-only.
29
+ if (result.isSymbolicLink()) result = statSync(current);
30
+ if (i < parts.length - 1 && !result.isDirectory()) throw new Error(`installation parent is not a directory: ${current}`);
31
+ }
32
+ return result;
33
+ }
34
+ function read(path) {
35
+ const before = stat(path);
36
+ if (!before) return null;
37
+ if (!before.isFile() || before.size > 1024 * 1024) throw new Error(`installation evidence is not a regular file within 1 MiB: ${path}`);
38
+ if (remaining < before.size + 1) throw new Error("installation evidence exceeds the total reader byte limit");
39
+ let fd;
40
+ try {
41
+ fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
42
+ if (!same(before, fstatSync(fd))) throw new Error(`installation evidence changed: ${path}`);
43
+ const bytes = Buffer.alloc(before.size + 1); let size = 0;
44
+ while (size < bytes.length) {
45
+ check(); const n = readSync(fd, bytes, size, bytes.length - size, size);
46
+ if (!n) break; size += n;
47
+ }
48
+ remaining -= size;
49
+ const after = stat(path);
50
+ if (size !== before.size || !same(before, fstatSync(fd)) || !after || !same(before, after))
51
+ throw new Error(`installation evidence changed while reading: ${path}`);
52
+ return bytes.toString("utf8", 0, size);
53
+ } finally { if (fd !== undefined) closeSync(fd); }
54
+ }
55
+
56
+ // Settings files holding an owned capture hook in a form earlier releases
57
+ // wrote, which this release's setup converts.
58
+ let installed = false, legacy = false;
59
+ const earlierHooks = new Set();
60
+ // A record root alone is not an installation: one recall or one manual
61
+ // capture creates it. Installation is owned or legacy service definitions,
62
+ // capture hooks, or setup's pending marker, below.
63
+ const selected = stat(root);
64
+ if (selected && !selected.isDirectory()) throw new Error(`selected record root is not a directory: ${root}`);
65
+ const candidates = platform === "darwin" ? [[join(home, "Library/LaunchAgents", `${captureServiceLabel}.plist`), "plist"]]
66
+ : platform === "linux" ? [[join(home, ".config/systemd/user", captureServiceUnit), "service"],
67
+ [join(home, ".config/systemd/user", captureServiceTimer), "timer"]] : [];
68
+ let periodic = candidates.length > 0;
69
+ for (const [path, kind] of candidates) {
70
+ const text = read(path); if (text === null) { periodic = false; continue; }
71
+ const ownership = captureServiceOwnership(text, kind);
72
+ installed ||= ownership !== "foreign"; legacy ||= ownership === "legacy"; periodic &&= ownership === "periodic";
73
+ }
74
+ // File evidence only: setup's marker beside its own marked definitions is
75
+ // an unverified activation; with no such definition the marker is stale.
76
+ const markerPath = join(root, capturePendingActivationName);
77
+ const pending = selected && read(markerPath) !== null ? { path: markerPath, stale: !periodic } : null;
78
+ // Only setup writes the marker, so it is setup evidence even beside nothing
79
+ // else (a setup that failed after writing it).
80
+ installed ||= pending !== null;
81
+
82
+ const beforeHome = stat(home);
83
+ if (beforeHome) {
84
+ if (!beforeHome.isDirectory()) throw new Error("installation home is not a directory");
85
+ const directory = opendirSync(home); let entries = 0, settings = 0;
86
+ try {
87
+ for (let entry; (entry = directory.readSync()) !== null;) {
88
+ check(); if (++entries > 4096) throw new Error("installation home exceeds the reader entry limit");
89
+ if (!entry.name.startsWith(".claude") || !(entry.isDirectory() || entry.isSymbolicLink())) continue;
90
+ if (++settings > 64) throw new Error("installation hook candidates exceed the reader limit");
91
+ const path = join(home, entry.name, "settings.json"), text = read(path);
92
+ if (text === null) continue;
93
+ let value;
94
+ try { value = JSON.parse(text); } catch { throw new Error(`invalid hook settings JSON: ${path}`); }
95
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`invalid hook settings object: ${path}`);
96
+ if (value.hooks === undefined) continue;
97
+ if (!value.hooks || typeof value.hooks !== "object" || Array.isArray(value.hooks)) throw new Error(`invalid hooks object: ${path}`);
98
+ for (const event of ["Stop", "SessionEnd"]) {
99
+ const groups = value.hooks[event] ?? [];
100
+ if (!Array.isArray(groups)) throw new Error(`invalid ${event} hook groups: ${path}`);
101
+ for (const group of groups) {
102
+ if (!group || typeof group !== "object" || Array.isArray(group) || !Array.isArray(group.hooks ?? []))
103
+ throw new Error(`invalid ${event} hook group: ${path}`);
104
+ for (const hook of group.hooks ?? []) {
105
+ if (!isCaptureHook(hook)) continue;
106
+ installed = true;
107
+ if (!isCurrentCaptureHook(hook)) earlierHooks.add(path);
108
+ }
109
+ }
110
+ }
111
+ }
112
+ } finally { directory.closeSync(); }
113
+ const afterHome = stat(home);
114
+ if (!afterHome || !same(beforeHome, afterHome)) throw new Error("installation home changed during enumeration");
115
+ }
116
+ return { installed, legacy, pending, earlierHooks: [...earlierHooks].sort() };
117
+ }
@@ -0,0 +1,116 @@
1
+ // Package-owned offline diagnosis. No writable DB/store, lock acquisition,
2
+ // manager, repair or capture; warnings never publish new run evidence.
3
+ import { homedir, hostname, platform as hostPlatform } from "node:os";
4
+ import { join } from "node:path";
5
+ import { readCaptureStatus } from "./capture-status.mjs";
6
+ import { readCurrentIssueBacklog } from "./capture-issues.mjs";
7
+ import { emptyFailureBacklog } from "./capture-failures.mjs";
8
+ import { captureInstallation } from "./capture-health-installation.mjs";
9
+ import { holderLiveness, readCaptureLockOwner, shellQuote } from "./capture-lock.mjs";
10
+
11
+ const setAsideRemedy = (command, root) => `Restore the captured prefix and run ${command} capture --retry-set-aside; or add the source to ${root}/ignore (later turns from that session will not be captured). Retry revalidates; it never authorizes a changed prefix.`;
12
+ export const SET_ASIDE_REMEDY = setAsideRemedy("turn-record", "<root>");
13
+ // Retry re-reads an unchanged oversized record and sets it aside again: only an
14
+ // edited source or an ignore of the whole input moves past it.
15
+ const oversizedRemedy = (command, root) => `Edit the source so no record exceeds 8 MiB, leaving its captured prefix unchanged, then run ${command} capture --retry-set-aside; or add the whole input to ${root}/ignore, which discards the whole input, its records after the oversized one included, and later turns from that session.`;
16
+ // The one rule for remedy wording: the kernel's own entry points say `oats`,
17
+ // the standalone package says `turn-record`. Each entry point states which it is.
18
+ export const captureRemedyCommand = viaKernel => viaKernel ? "oats" : "turn-record";
19
+ const emptyBacklog = () => ({ pending: false, setAsideCount: 0, setAside: [], truncated: false, ...emptyFailureBacklog() });
20
+ const noHistory = () => ({ lastRun: null, lastSuccess: null, lastFailure: null, lastProgressAt: null, backlog: emptyBacklog() });
21
+ const time = value => typeof value === "string" ? Date.parse(value) : NaN;
22
+
23
+ function deadExecution(root, run, host, liveness, now) {
24
+ // A receipt has no host field. Never signal-probe its PID without matching
25
+ // local registration. Both owner and worker must be dead: a live supervisor
26
+ // can still replace a child and finish this same pass. Reused/unknown PIDs
27
+ // and changed/foreign/hostless lock records supply no death evidence.
28
+ const owner = readCaptureLockOwner(root), worker = owner?.worker;
29
+ if (owner?.host !== host || worker?.host !== host || worker.pid !== run.pid ||
30
+ !Number.isInteger(owner.pid) || owner.pid <= 0 || owner.pid === worker.pid ||
31
+ typeof owner.nonce !== "string" || !owner.nonce || typeof worker.nonce !== "string" || !worker.nonce ||
32
+ !(time(owner.startedAt) <= time(run.startedAt)) || !(time(worker.startedAt) >= time(owner.startedAt)) ||
33
+ !(time(worker.startedAt) <= now)) return false;
34
+ if (liveness(owner.pid) !== "dead" || liveness(worker.pid) !== "dead") return false;
35
+ return JSON.stringify(readCaptureLockOwner(root)) === JSON.stringify(owner) &&
36
+ JSON.stringify(readCaptureStatus(root, { now })?.lastRun) === JSON.stringify(run);
37
+ }
38
+
39
+ // Optional caller/clock/liveness context is for isolated readers and fixtures;
40
+ // no CLI option selects an alternate reader, executable or resource policy.
41
+ export function captureHealth(root, options = {}) { return diagnose(root, options, captureRemedyCommand(false)); }
42
+
43
+ // Private kernel presentation: choose only authored command literals, before
44
+ // interpolating paths/receipt data. Never replace words in completed messages.
45
+ export function captureHealthForDoctor(root, options = {}) { return diagnose(root, options, captureRemedyCommand(true)); }
46
+
47
+ function diagnose(root, { home = homedir(), platform = hostPlatform(), now = Date.now(),
48
+ host = hostname(), liveness = holderLiveness } = {}, command) {
49
+ const began = performance.now();
50
+ const check = () => { if (performance.now() - began > 15000) throw new Error("capture health reader deadline exceeded"); };
51
+ let installation;
52
+ try { installation = captureInstallation(root, { home, platform, check }); }
53
+ catch (error) { throw new Error(`Capture installation evidence is unknown: ${error.message}`, { cause: error }); }
54
+ const rows = [], path = join(root, "capture-status.json");
55
+ let status = noHistory();
56
+ const result = backlog => ({ schemaVersion: 1, status: rows.length ? "warning" : "ok", rows,
57
+ lastRun: status.lastRun, lastSuccess: status.lastSuccess, lastFailure: status.lastFailure, backlog });
58
+ if (!installation.installed) { check(); return result(emptyBacklog()); }
59
+
60
+ const setup = `Run ${command} setup --root ${shellQuote(root)} with your existing --owner to inspect and refresh installation.`;
61
+ try {
62
+ const saved = readCaptureStatus(root, { now });
63
+ if (saved) status = saved;
64
+ else rows.push({ code: "capture-status-missing", message: `Capture status is missing at ${path}. ${setup}` });
65
+ } catch (error) { rows.push({ code: "capture-status-invalid", message: `Cannot read capture status at ${path}: ${error.message}. ${setup}` }); }
66
+ check();
67
+ let backlog;
68
+ try {
69
+ backlog = readCurrentIssueBacklog(root);
70
+ if (!backlog && (status.backlog.setAsideCount || status.backlog.failedCount))
71
+ throw new Error("capture.db is missing but the last command reported active capture issues");
72
+ } catch (error) { throw new Error(`Cannot read current capture issues at ${join(root, "index", "capture.db")}: ${error.message}`, { cause: error }); }
73
+ check(); backlog ??= emptyBacklog();
74
+ if (backlog.setAsideCount) {
75
+ // Remedies follow each listed entry's reason. Reasons beyond the bounded
76
+ // sample are unknown here, so a truncated list says so rather than guess.
77
+ const oversized = backlog.setAside.filter(entry => entry.reason === "record-too-large").length;
78
+ const others = backlog.setAsideCount - oversized, general = setAsideRemedy(command, root);
79
+ const message = !oversized ? general + (backlog.truncated ? ` Unlisted entries: see each entry's reason; record-too-large entries need: ${oversizedRemedy(command, root)}` : "") :
80
+ `${oversized} listed as record-too-large: ${oversizedRemedy(command, root)}` + (!others ? "" : backlog.truncated ?
81
+ ` The other ${others}, including unlisted entries: see each entry's reason; record-too-large entries need the edit-or-ignore remedy above. Otherwise: ${general}` :
82
+ ` The other ${others}: ${general}`);
83
+ rows.push({ code: "capture-input-set-aside", message: `${backlog.setAsideCount} capture inputs set aside. ${message}` });
84
+ }
85
+
86
+ const failures = [];
87
+ if (backlog.failedCount) failures.push(`${backlog.failedCount} capture stream units failed. Deferred retries remain unresolved; offsets name unit starts, not exact failing frames.`);
88
+ const successAt = time(status.lastSuccess?.finishedAt);
89
+ const failure = status.lastFailure;
90
+ if (failure && (!status.lastSuccess || time(failure.finishedAt) > successAt))
91
+ failures.push(`Last recorded failure ${failure.finishedAt} (${failure.reason}) is newer than any recorded success.`);
92
+ const run = status.lastRun;
93
+ if (run?.outcome === "failed" && (!status.lastSuccess || time(run.finishedAt) > successAt) && run.id !== failure?.id)
94
+ failures.push(`Last run ${run.id} failed at ${run.finishedAt} (${run.reason}).`);
95
+ if (run?.outcome === "running") {
96
+ if (now - time(run.startedAt) > status.policy.deadlineSeconds * 1000)
97
+ failures.push(`Run ${run.id} has no final receipt after its ${status.policy.deadlineSeconds}s deadline. This does not identify why execution stopped or prove that it stopped.`);
98
+ else if (deadExecution(root, run, host, liveness, now))
99
+ failures.push(`Run ${run.id} is unfinished and its matching local registered supervisor and worker are no longer alive.`);
100
+ }
101
+ if (failures.length) rows.push({ code: "capture-pass-failed", message:
102
+ `${failures.join(" ")} Inspect ${command} capture --health --json and the retained receipt; counters are durably confirmed accounting, not all physical writes. A sleeping or off-host execution can leave old observations; no process is killed or lock reclaimed by health.` });
103
+ if (!status.lastSuccess || now - successAt > 3600 * 1000) rows.push({ code: "capture-success-stale", message:
104
+ `Last successful capture: ${status.lastSuccess?.finishedAt ?? "none recorded"}; last committed progress: ${status.lastProgressAt ?? "none recorded"}. No success within 3600s. This may reflect a sleeping machine or off-host execution; recent progress is not full success. ${setup}` });
105
+ if (installation.legacy) rows.push({ code: "capture-setup-required", message:
106
+ `An owned legacy continuous-watch definition remains. ${setup} Definition files do not prove manager registration or enabled scheduling; health invokes no manager.` });
107
+ if (installation.earlierHooks?.length) rows.push({ code: "capture-setup-required", message:
108
+ `Capture hooks in ${installation.earlierHooks.join(", ")} use a form an earlier release's setup wrote, not this release's hook entry. ${setup}` });
109
+ // Activation is "not verified", never "not running": a crash after a
110
+ // verified activation can leave the marker until the next setup clears it.
111
+ const retry = `Run ${command} setup --root ${shellQuote(root)} with your existing --owner`;
112
+ if (installation.pending) rows.push({ code: "capture-service-pending", message: installation.pending.stale
113
+ ? `The pending-activation marker ${installation.pending.path} is stale: no setup-marked capture service definition remains. ${retry}; it removes the stale marker and activates nothing on its account.`
114
+ : `Setup started activating the periodic capture service and did not verify it (marker ${installation.pending.path}): capture hooks may be installed, but the periodic schedule is not verified. ${retry} to retry the activation.` });
115
+ check(); return result(backlog);
116
+ }