@awebai/oats 0.49.0 → 0.51.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.
@@ -40,6 +40,7 @@
40
40
  * that checks "the rows' home is the home I asked for" keeps holding. */
41
41
  import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
42
42
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
43
+ import { REFUSED_TEXT } from "./refused-text.mjs";
43
44
 
44
45
  export const EVENTS_API = 2;
45
46
  const HOME_LOG = ".oats-events.jsonl";
@@ -55,13 +56,8 @@ export const WAITING_REASONS = ["permission", "question", "attention"];
55
56
  /** A producer id: what `--producer` accepts (`kernel` is reserved). */
56
57
  export const WAITING_PRODUCER_RE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
57
58
  export const WAITING_MESSAGE_MAX = 200;
58
- /** Characters a claim's message may not contain (the maintainer's set): control
59
- * characters (Cc: C0, DEL, C1), the Unicode line and paragraph separators, the bidi
60
- * embeddings, overrides and isolates (U+202A-202E, U+2066-2069), the invisible hiders
61
- * U+200B, U+2060 and U+FEFF, and the tag characters (U+E0000-E007F). Everything else is
62
- * allowed, ZWJ and ZWNJ (U+200C/D, emoji sequences, Persian and Indic text) and the marks
63
- * LRM, RLM and ALM (U+200E/F, U+061C) included. The Desktop uses the identical set. */
64
- const WAITING_MESSAGE_REFUSED = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
59
+ /** Characters a claim's message may not contain: the kernel's refused set (lib/refused-text.mjs). */
60
+ const WAITING_MESSAGE_REFUSED = REFUSED_TEXT;
65
61
  /** A claim's message: a non-empty string of 1 to 200 code points with none of
66
62
  * WAITING_MESSAGE_REFUSED. The writer refuses anything else; the reader turns a stored
67
63
  * message that fails it (a hand-edited log) into null. */
@@ -50,12 +50,15 @@ const trim = (s) => (s === null ? null : s.trim());
50
50
  /** One helper-free Git probe run like the module's other reads
51
51
  * (READ_ONLY_GIT, gitEnv, argv, no shell) → { ok, out, err }. `out` is text.
52
52
  * Never throws: the caller decides what a failure means. `cwd`: the tree
53
- * `-C` names; gitRepoRead names the repository by its Git directory instead. */
54
- export function gitRead(cwd, argv) { return gitProbe(["-C", cwd], argv); }
53
+ * `-C` names; gitRepoRead names the repository by its Git directory instead.
54
+ * `input`: text for the command's standard input (`--stdin`), else none.
55
+ * `encoding`: how `out` is decoded ("latin1" keeps every byte as one
56
+ * character, for an exact comparison of names), "utf8" by default. */
57
+ export function gitRead(cwd, argv, { input, encoding } = {}) { return gitProbe(["-C", cwd], argv, input, encoding); }
55
58
  /** gitRead against the repository whose (common) Git directory is `gitDir`,
56
59
  * named explicitly (`--git-dir`), so that a bare repository is read too
57
60
  * (READ_ONLY_GIT sets safe.bareRepository=explicit). */
58
- export function gitRepoRead(gitDir, argv) { return gitProbe(["--git-dir", gitDir], argv); }
61
+ export function gitRepoRead(gitDir, argv, { input, encoding } = {}) { return gitProbe(["--git-dir", gitDir], argv, input, encoding); }
59
62
  /** A Git command that changes the repository whose Git directory is `gitDir`
60
63
  * (a worktree move, remove or prune), under the same discipline as the
61
64
  * reads: the repository's own configuration names no helper that runs
@@ -65,8 +68,8 @@ export function gitRepoRead(gitDir, argv) { return gitProbe(["--git-dir", gitDir
65
68
  export function gitRepoRun(gitDir, argv) {
66
69
  return execFileSync("git", ["--git-dir", gitDir, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 120_000, env: gitEnv() });
67
70
  }
68
- function gitProbe(where, argv) {
69
- const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
71
+ function gitProbe(where, argv, input, encoding = "utf8") {
72
+ const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...argv], { encoding, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
70
73
  return !r.error && r.status === 0 ? { ok: true, out: r.stdout } : { ok: false, out: "", err: String(r.error?.message ?? r.stderr ?? "").trim() || `git ${argv[0]} exited with ${r.status}` };
71
74
  }
72
75
 
@@ -151,8 +151,11 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
151
151
 
152
152
  /** The soul target, resolved exactly as a spawn of `soul` would be. A resolution
153
153
  * refusal that is a readiness fact is kept as `resolutionError` (callers that
154
- * must answer — inspect, operation run — refuse with it). */
155
- export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
154
+ * must answer — inspect, operation run — refuse with it). `materialize: false`
155
+ * resolves only: it writes nothing under the deployment's agents root, and names the
156
+ * soul's per-commit copy only when an earlier resolution left one
157
+ * (materializeSoulTarget makes it, later, for a caller that then goes on). */
158
+ export async function soulTarget(contextDir, soul, { remoteOptions, materialize = true } = {}) {
156
159
  let prepared = null, resolutionError = null;
157
160
  try { prepared = await prepareInstance(contextDir, soul, { remoteOptions }); }
158
161
  catch (e) {
@@ -180,7 +183,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
180
183
  // commit answered a false negative. A failure is a readiness fact (soulCopyError), never a silent null.
181
184
  // A refused resolution has nothing to materialise: the cached copy, when there is one.
182
185
  let soulDir = null, soulCopyError = null;
183
- if (prepared) {
186
+ if (prepared && materialize) {
184
187
  try { soulDir = await ensureWorkspaceSoul(prepared, join(deployment, "agents")); }
185
188
  catch (e) { soulCopyError = { code: e?.code || "E_SOUL_COPY_FAILED", message: e?.message || String(e) }; }
186
189
  } else {
@@ -207,6 +210,16 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
207
210
  };
208
211
  }
209
212
 
213
+ /** Materialise the soul of a target resolved with `materialize: false`, as soulTarget itself does:
214
+ * the per-commit copy its checks and commands get as OATS_SOUL. A failure is the same readiness
215
+ * fact (`soul.copyError`). → the target, updated in place */
216
+ export async function materializeSoulTarget(t) {
217
+ if (!t.prepared) return t;
218
+ try { t.soul.soulDir = await ensureWorkspaceSoul(t.prepared, t.agentsRoot); delete t.soul.copyError; }
219
+ catch (e) { t.soul.copyError = { code: e?.code || "E_SOUL_COPY_FAILED", message: e?.message || String(e) }; }
220
+ return t;
221
+ }
222
+
210
223
  /** The tmux session a NEW tmux spawn here would open in ({tmuxSession}, 0.31); null when the
211
224
  * deployment's oats-local.yaml cannot be read. */
212
225
  function newSessionDefaults(deployment) {
@@ -411,6 +424,26 @@ function moduleExecutable(dir, script) {
411
424
  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
412
425
  try { return statSync(file).isFile() ? file : null; } catch { return null; }
413
426
  }
427
+ /** Run one of a capability's own commands the way a provider check runs (the binding wire's
428
+ * runner, shared with trigger sources, lib/triggers.mjs): `node <script> <args>` from the module
429
+ * directory, the script contained in it (moduleExecutable), one JSON `request` on stdin, the
430
+ * environment providerEnv's for the request's `settings`, SIGKILL at `timeoutMs`, at most
431
+ * BINDING_LIMITS of stdout, decoded as exactly one strict JSON document (whitespace around it
432
+ * allowed). → { doc } or { failure: "no-command" | "no-executable" (script) | "incomplete"
433
+ * (timedOut, signal, overflow) | "exit" (status) | "invalid" }. The caller judges the document. */
434
+ export function runModuleCommand(t, mod, dir, command, request, { timeoutMs = 30000 } = {}) {
435
+ const spec = command ? mod.manifest?.commands?.[command] : null;
436
+ if (typeof spec !== "string" || !spec.trim()) return { failure: "no-command" };
437
+ const [script, ...args] = spec.trim().split(/\s+/);
438
+ const file = dir ? moduleExecutable(dir, script) : null;
439
+ if (!file) return { failure: "no-executable", script };
440
+ // The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
441
+ // inherited.
442
+ const r = spawnSync(process.execPath, [file, ...args], { cwd: dir, env: providerEnv(t, mod.name, request.settings), input: JSON.stringify(request), encoding: "utf8", timeout: Math.max(1, timeoutMs), killSignal: "SIGKILL", maxBuffer: BINDING_LIMITS.maxBytes, stdio: ["pipe", "pipe", "pipe"] });
443
+ if (r.error || r.signal) return { failure: "incomplete", timedOut: r.error?.code === "ETIMEDOUT", signal: r.signal ?? null, overflow: r.error?.code === "ENOBUFS" };
444
+ if (r.status !== 0) return { failure: "exit", status: r.status };
445
+ try { return { doc: parseStrictJson(r.stdout || "", BINDING_LIMITS) }; } catch { return { failure: "invalid" }; }
446
+ }
414
447
  /** The four check statuses of the binding wire, and what each means for readiness. */
415
448
  const PROVIDER_STATUS_ITEM = Object.freeze({ ready: "pass", "needs-configuration": "fail", "authorization-required": "fail", unavailable: "unknown" });
416
449
  const ENVELOPE_KEYS = ["schemaVersion", "phase", "slot", "capability", "ok"];
@@ -425,27 +458,23 @@ const codeMessages = (p) => p.map((x) => ({ code: x.code, message: x.message }))
425
458
  * are the provider's own (not checked against binding.reasons, which are refusal
426
459
  * sentences); problems and the optional warnings must be {code, message} strings. */
427
460
  export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
428
- const m = mod.manifest, check = m?.binding?.check, spec = check ? m.commands?.[check] : null;
461
+ const m = mod.manifest, check = m?.binding?.check;
429
462
  const unavailable = (code, message) => ({ outcome: "unknown", problems: [{ code, message }] });
430
- if (typeof spec !== "string" || !spec.trim()) return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
431
- const [script, ...args] = spec.trim().split(/\s+/);
432
- const file = dir ? moduleExecutable(dir, script) : null;
433
- if (!file) return unavailable("resource-not-found", `${mod.name}: the check executable ${script} is unavailable`);
434
463
  const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
435
464
  // The released binding wire, key for key: providers decode it strictly (oats.aweb 1.13.1
436
465
  // refuses any other key). The teams reach the check through its environment
437
466
  // (OATS_DEFAULT_TEAM* / OATS_TEAMS / OATS_TEAMS_SOURCE, providerEnv), never on stdin.
438
467
  const request = { schemaVersion: 1, phase: "check", slot: m.layer ?? null, capability: mod.name, settings,
439
468
  input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
440
- // The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
441
- // inherited.
442
- const r = spawnSync(process.execPath, [file, ...args], { cwd: dir, env: providerEnv(t, mod.name, settings), input: JSON.stringify(request), encoding: "utf8", timeout: Math.max(1, timeoutMs), killSignal: "SIGKILL", maxBuffer: BINDING_LIMITS.maxBytes, stdio: ["pipe", "pipe", "pipe"] });
443
- if (r.error || r.signal) return unavailable("provider-unavailable", `${mod.name} check did not complete${r.error?.code === "ETIMEDOUT" || r.signal ? " in time" : ""}`);
444
- if (r.status !== 0) return unavailable("provider-unavailable", `${mod.name} check exited ${r.status}`);
469
+ const run = runModuleCommand(t, mod, dir, check, request, { timeoutMs });
470
+ if (run.failure === "no-command") return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
471
+ if (run.failure === "no-executable") return unavailable("resource-not-found", `${mod.name}: the check executable ${run.script} is unavailable`);
472
+ if (run.failure === "incomplete") return unavailable("provider-unavailable", `${mod.name} check did not complete${run.timedOut || run.signal ? " in time" : ""}`);
473
+ if (run.failure === "exit") return unavailable("provider-unavailable", `${mod.name} check exited ${run.status}`);
445
474
  const invalid = () => unavailable("provider-unavailable", `${mod.name} check answered invalid binding data`);
446
- let doc;
475
+ if (run.failure === "invalid") return invalid();
476
+ const doc = run.doc;
447
477
  try {
448
- doc = parseStrictJson(r.stdout || "", BINDING_LIMITS);
449
478
  if (!obj(doc)) return invalid();
450
479
  const allowed = [...ENVELOPE_KEYS, doc.ok === true ? "result" : "error"];
451
480
  if (Object.keys(doc).some((k) => !allowed.includes(k)) || allowed.some((k) => !Object.hasOwn(doc, k))) return invalid();
@@ -0,0 +1,17 @@
1
+ /** The characters the kernel never stores or prints in text it did not write itself (the
2
+ * maintainer's set): control characters (Cc: C0, DEL, C1), the Unicode line and paragraph
3
+ * separators, the bidi embeddings, overrides and isolates (U+202A-202E, U+2066-2069), the
4
+ * invisible hiders U+200B, U+2060 and U+FEFF, and the tag characters (U+E0000-E007F).
5
+ * Everything else is allowed, ZWJ and ZWNJ (U+200C/D, emoji sequences, Persian and Indic text)
6
+ * and the marks LRM, RLM and ALM (U+200E/F, U+061C) included. One set for the kernel: a waiting
7
+ * claim's message (lib/instance-events.mjs) refuses it, a trigger source's text
8
+ * (lib/triggers.mjs) has it replaced. The Desktop keeps its own identical copy. */
9
+ export const REFUSED_TEXT = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
10
+ const REFUSED_TEXT_ALL = new RegExp(REFUSED_TEXT.source, "gu");
11
+
12
+ /** Text from outside the kernel, made safe to store and print: every REFUSED_TEXT character
13
+ * replaced with U+FFFD, then cut to `max` code points, ending in `…` when cut. */
14
+ export function safeText(text, max) {
15
+ const points = [...String(text).replace(REFUSED_TEXT_ALL, "\uFFFD")];
16
+ return points.length > max ? `${points.slice(0, max - 1).join("")}…` : points.join("");
17
+ }
@@ -0,0 +1,387 @@
1
+ /** What retires left behind in a deployment, as `oats doctor` information
2
+ * lines (#703 part 2a): the recovery copies under each instances directory's
3
+ * `.oats-retirement/recovery/`, and the retained worktrees under
4
+ * `<deployment>/.agents/worktrees/<repo>/`. Each line gives the facts to
5
+ * decide with (docs/souls-and-instances.md, "After a retire: inspect,
6
+ * restore, dispose"): whether the HEAD commit is reachable from another ref
7
+ * of the source repository, and what is uncommitted. Never a conclusion
8
+ * ("unique", "redundant", "safe to delete"): a retained worktree and a
9
+ * recovery can hold the same uncommitted bytes.
10
+ *
11
+ * Read-only: nothing is written, moved or removed. Git runs only through
12
+ * gitRead/gitRepoRead (helper-free, no optional locks, no lazy fetch), so no
13
+ * index is refreshed. Links are never followed, neither to size a tree nor
14
+ * to read a JSON file. What can't be read is said on its line and never fails
15
+ * doctor. Each line is one line of text: values from disk or Git have their
16
+ * control characters escaped. */
17
+ import { closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, realpathSync } from "node:fs";
18
+ import { isAbsolute, join } from "node:path";
19
+ import { instancesDirs, RECOVERABLE_GIT_ADMIN, retainedWorktreesRoot, retirementRecoveryRoot } from "./core.mjs";
20
+ import { gitRead, gitRepoRead } from "./instance-git.mjs";
21
+ import { formatBytes } from "./retire-output.mjs";
22
+ import { joinBytes } from "./tree-copy.mjs";
23
+
24
+ /** Item lines per kind; past it, one `… and N more` line. */
25
+ export const RETAINED_LINES_MAX = 50;
26
+ /** Entries a size walk visits before it stops and reports a lower bound. */
27
+ export const SIZE_ENTRIES_MAX = 250_000;
28
+ /** recovery.json and the copied instance.json are read up to this size. */
29
+ const JSON_MAX_BYTES = 16 * 1024 * 1024;
30
+ const RECOVERY = "retained-recovery";
31
+ const WORKTREE = "retained-worktree";
32
+ const DOCS = "to inspect, restore or dispose of them, see docs/souls-and-instances.md#after-a-retire-inspect-restore-dispose";
33
+
34
+ const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
35
+ /** A value from disk, Git or a JSON file as text on one line: control
36
+ * characters (C0, DEL, C1) and the line and paragraph separators escaped,
37
+ * at most 512 characters. */
38
+ function shown(value) {
39
+ const s = String(value).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
40
+ return s.length > 512 ? `${s.slice(0, 512)}…` : s;
41
+ }
42
+ const why = (e) => shown(e?.code ?? e?.message ?? e);
43
+ const realOrNull = (path) => { try { return realpathSync(path); } catch { return null; } };
44
+ /** The entries of `dir` sorted, [] when it does not exist; throws when it can't be read. */
45
+ function namesIn(dir) {
46
+ try { return readdirSync(dir).sort(byCodeUnit); } catch (e) { if (e?.code === "ENOENT" || e?.code === "ENOTDIR") return []; throw e; }
47
+ }
48
+ /** What a path is, without following a link → "dir" | "link" | "other" | { error }. */
49
+ function kindOf(path) {
50
+ try {
51
+ const st = lstatSync(path);
52
+ return st.isSymbolicLink() ? "link" : st.isDirectory() ? "dir" : "other";
53
+ } catch (e) { return { error: e }; }
54
+ }
55
+ /** The facts a path that is not a directory gets instead of its kind's. */
56
+ function notADirectory(kind) {
57
+ return kind === "link" ? "a symbolic link, not followed" : kind === "other" ? "not a directory" : `could not be read (${why(kind.error)})`;
58
+ }
59
+
60
+ /** The bytes under `path` as a retire counts them (treeBytes in core.mjs: a
61
+ * link counts as itself, never followed; a directory as what it holds), names
62
+ * read as bytes, visiting at most SIZE_ENTRIES_MAX entries. → its fact. */
63
+ function sizeFact(path) {
64
+ let bytes = 0, entries = 0;
65
+ const pending = [Buffer.from(path)];
66
+ while (pending.length) {
67
+ const at = pending.pop();
68
+ if (++entries + pending.length > SIZE_ENTRIES_MAX) return `size: at least ${formatBytes(bytes)} (stopped after ${SIZE_ENTRIES_MAX} entries)`;
69
+ let st;
70
+ try { st = lstatSync(at); } catch (e) { return `size: unknown (${shown(at.toString())} could not be read: ${why(e)})`; }
71
+ if (!st.isDirectory()) { bytes += st.size; continue; }
72
+ try { for (const name of readdirSync(at, { encoding: "buffer" })) pending.push(joinBytes(at, name)); }
73
+ catch (e) { return `size: unknown (${shown(at.toString())} could not be read: ${why(e)})`; }
74
+ }
75
+ return `size: ${formatBytes(bytes)}`;
76
+ }
77
+
78
+ /** A JSON file read without following a link and without blocking on a FIFO,
79
+ * up to JSON_MAX_BYTES → { value } | { error } (what it is, as a phrase). */
80
+ function readJsonFile(path) {
81
+ let fd;
82
+ try { fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK); }
83
+ catch (e) { return { error: e?.code === "ENOENT" ? "missing" : e?.code === "ELOOP" ? "a symbolic link, not followed" : `unreadable (${why(e)})` }; }
84
+ try {
85
+ const st = fstatSync(fd);
86
+ if (!st.isFile()) return { error: "not a regular file" };
87
+ if (st.size > JSON_MAX_BYTES) return { error: `larger than ${formatBytes(JSON_MAX_BYTES)}` };
88
+ let text;
89
+ try { text = readFileSync(fd, "utf8"); } catch (e) { return { error: `unreadable (${why(e)})` }; }
90
+ try { return { value: JSON.parse(text) }; } catch { return { error: "not valid JSON" }; }
91
+ } finally { closeSync(fd); }
92
+ }
93
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
94
+
95
+ /** Ref names are read as bytes, one character each ("latin1"), so that two
96
+ * names compare equal only when their bytes do; `refText` is a name as text,
97
+ * for a line (bytes that are not UTF-8 shown as U+FFFD). */
98
+ const BYTES = { encoding: "latin1" };
99
+ const refText = (ref) => Buffer.from(ref, "latin1").toString("utf8");
100
+ /** The short name of a ref, as Git prints it for a branch, a remote-tracking
101
+ * ref or a tag; any other ref by its full name. */
102
+ function shortRef(ref) {
103
+ for (const prefix of ["refs/heads/", "refs/remotes/", "refs/tags/"]) if (ref.startsWith(prefix)) return ref.slice(prefix.length);
104
+ return ref;
105
+ }
106
+ /** The ref a line names among those that reach a commit: a remote-tracking
107
+ * ref first (a remote's HEAD after its branches), then a branch, a tag, any
108
+ * other ref; by name within each. */
109
+ function preferredRef(refs) {
110
+ const rank = (r) => r.startsWith("refs/remotes/") ? (r.endsWith("/HEAD") ? 1 : 0) : r.startsWith("refs/heads/") ? 2 : r.startsWith("refs/tags/") ? 3 : 4;
111
+ return [...refs].sort((a, b) => rank(a) - rank(b) || byCodeUnit(a, b))[0];
112
+ }
113
+
114
+ /** The reachability fact of `commit` in the repository whose Git directory is
115
+ * `commonDir`: whether a ref other than `ownRef` (the tree's own branch,
116
+ * null when detached) reaches it, and if none does, how many commits no
117
+ * other ref reaches. Per-worktree refs (refs/worktree/, refs/bisect/) are
118
+ * not other refs. → "commits: …". */
119
+ function commitsFact(commonDir, commit, ownRef) {
120
+ const short = commit.slice(0, 12);
121
+ const present = gitRepoRead(commonDir, ["cat-file", "--batch-check"], { input: `${commit}^{commit}\n` });
122
+ if (!present.ok) return `commits: unknown (whether the source repository has HEAD ${short} could not be read: ${shown(present.err)})`;
123
+ if (/ missing\s*$/.test(present.out)) return `commits: HEAD ${short} is not in the source repository`;
124
+ const other = (ref) => ref && ref !== ownRef && !ref.startsWith("refs/worktree/") && !ref.startsWith("refs/bisect/");
125
+ const reaching = gitRepoRead(commonDir, ["for-each-ref", "--contains", commit, "--format=%(refname)"], BYTES);
126
+ if (!reaching.ok) return `commits: unknown (which refs reach HEAD ${short} could not be read: ${shown(reaching.err)})`;
127
+ const reachedBy = reaching.out.split("\n").filter(other);
128
+ if (reachedBy.length) return `commits: all reachable from ${shown(refText(shortRef(preferredRef(reachedBy))))}`;
129
+ // No other ref reaches HEAD: count what none of them reaches. Each other
130
+ // ref's commit goes on stdin, so the argv stays bounded however many there are.
131
+ const refs = gitRepoRead(commonDir, ["for-each-ref", "--format=%(objectname)%00%(objecttype)%00%(*objectname)%00%(*objecttype)%00%(refname)"], BYTES);
132
+ if (!refs.ok) return `commits: unknown (the refs could not be read: ${shown(refs.err)})`;
133
+ const tips = [];
134
+ for (const row of refs.out.split("\n")) {
135
+ const [oid, type, peeled, peeledType, ref] = row.split("\0");
136
+ if (!other(ref)) continue;
137
+ if (type === "commit") tips.push(oid);
138
+ else if (type === "tag" && peeledType === "commit") tips.push(peeled);
139
+ }
140
+ const count = gitRepoRead(commonDir, ["rev-list", "--count", "--stdin"], { input: [commit, ...tips.map((t) => `^${t}`)].join("\n") + "\n" });
141
+ const n = Number(count.out.trim());
142
+ if (!count.ok || !Number.isInteger(n)) return `commits: unknown (the commits could not be counted: ${shown(count.err || count.out)})`;
143
+ return n === 0 ? "commits: all reachable from another ref" : `commits: ${n} not reachable from any other ref`;
144
+ }
145
+
146
+ /** A tree's HEAD, read through Git (gitRead/gitRepoRead's `read`) →
147
+ * { commit, ref } (`ref` null when detached) | { error }. `ref` is the ref's
148
+ * bytes (BYTES) as Git prints them, without the line feed that ends them:
149
+ * nothing else is trimmed, since a name may begin or end with a character
150
+ * that reads as white space (headName in instance-git.mjs). Only Git's quiet
151
+ * answer (exit 1, nothing on stderr) is "detached". */
152
+ function headOf(read) {
153
+ const commit = read(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
154
+ const oid = commit.ok ? commit.out.replace(/\n$/, "") : "";
155
+ if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(oid)) return { error: commit.err || "it names no commit" };
156
+ const ref = read(["symbolic-ref", "--quiet", "HEAD"], BYTES);
157
+ if (ref.ok) return { commit: oid, ref: ref.out.replace(/\n$/, "") };
158
+ return ref.err === "git symbolic-ref exited with 1" ? { commit: oid, ref: null } : { error: `what it has checked out could not be read: ${ref.err}` };
159
+ }
160
+ /** The content filters (`filter.<driver>.clean` or `.process`) the
161
+ * configuration of the repository at `path` names → { names } | { error }.
162
+ * A status that compares a file's bytes with the index runs the filter its
163
+ * attributes name, and doctor runs no helper: with one configured, it does
164
+ * not ask for a status. A driver's name is any text, the empty one included
165
+ * (`filter..clean`), and a key counts whatever its value: Git decides what
166
+ * an empty one means, not this guard. */
167
+ function contentFilters(path) {
168
+ const config = gitRead(path, ["config", "--list", "-z"]);
169
+ if (!config.ok) return { error: config.err };
170
+ const names = new Set();
171
+ for (const entry of config.out.split("\0")) {
172
+ const nl = entry.indexOf("\n");
173
+ const m = /^filter\.(.*)\.(clean|process)$/s.exec(nl < 0 ? entry : entry.slice(0, nl));
174
+ if (m) names.add(m[1]);
175
+ }
176
+ return { names: [...names].sort(byCodeUnit) };
177
+ }
178
+ /** Whether the index of the tree at `path` holds a submodule (a gitlink,
179
+ * mode 160000) → true | false | { error }. */
180
+ function holdsSubmodules(path) {
181
+ const index = gitRead(path, ["ls-files", "--stage", "-z"]);
182
+ if (!index.ok) return { error: index.err };
183
+ return index.out.split("\0").some((row) => row.startsWith("160000 "));
184
+ }
185
+ /** The uncommitted classes in a `git status --porcelain=v1 -z --ignored`
186
+ * answer, in a fixed order. */
187
+ function uncommittedClasses(z) {
188
+ const found = new Set();
189
+ const fields = z.split("\0");
190
+ for (let i = 0; i < fields.length; i++) {
191
+ const xy = fields[i].slice(0, 2);
192
+ if (fields[i].length < 4) continue;
193
+ if (xy[0] === "R" || xy[0] === "C") i++; // a rename or copy carries its source path next
194
+ if (xy === "??") found.add("untracked files");
195
+ else if (xy === "!!") found.add("ignored files");
196
+ else if (["DD", "AU", "UD", "UA", "DU", "AA", "UU"].includes(xy)) found.add("conflicts");
197
+ else {
198
+ if (xy[0] !== " ") found.add("staged changes");
199
+ if (xy[1] !== " ") found.add("unstaged changes");
200
+ }
201
+ }
202
+ return ["staged changes", "unstaged changes", "conflicts", "untracked files", "ignored files"].filter((c) => found.has(c));
203
+ }
204
+
205
+ /** Whether the tree at `path` (Git directory `gitDir`) is clean, as retire's
206
+ * rule has it (untracked and ignored files and an operation in progress
207
+ * count) → its facts. The status never runs a helper: not with a content
208
+ * filter configured (contentFilters), and never inside a submodule, which
209
+ * would be a Git of its own with its own configuration
210
+ * (`--ignore-submodules=dirty` compares only the commit a submodule is at). */
211
+ function cleanFacts(path, gitDir) {
212
+ const classes = [];
213
+ if (RECOVERABLE_GIT_ADMIN.some((name) => typeof kindOf(join(gitDir, name)) === "string")) classes.push("an operation in progress");
214
+ const uncommitted = classes.length ? `; uncommitted: ${classes.join(", ")}` : "";
215
+ const filters = contentFilters(path);
216
+ if (filters.error) return [`clean: unknown (its configuration could not be read: ${shown(filters.error)})${uncommitted}`];
217
+ if (filters.names.length) return [`clean: unknown (its repository configures a content filter that doctor does not run: ${filters.names.map((n) => (n === "" ? 'filter."" (the empty driver name)' : shown(`filter.${n}`))).join(", ")})${uncommitted}`];
218
+ const status = gitRead(path, ["status", "--porcelain=v1", "-z", "--ignored", "--untracked-files=normal", "--ignore-submodules=dirty"]);
219
+ if (!status.ok) return [`clean: unknown (its status could not be read: ${shown(status.err)})${uncommitted}`];
220
+ classes.unshift(...uncommittedClasses(status.out));
221
+ // What a submodule's own work tree holds is not read, so a tree with one is
222
+ // clean only as far as the rest goes: unknown, unless the rest is not clean.
223
+ const submodules = holdsSubmodules(path);
224
+ const unread = submodules === true ? "submodule work trees not read" : submodules.error ? `whether it holds submodules could not be read: ${shown(submodules.error)}` : null;
225
+ if (classes.length) return [`not clean; uncommitted: ${classes.join(", ")}`, ...(unread ? [unread] : [])];
226
+ return [unread ? `clean: unknown (${unread})` : "clean"];
227
+ }
228
+
229
+ /** One retained worktree, read: → { path, facts, commonDir?, ref? }.
230
+ * `commonDir` (its repository's Git directory, canonical) and `ref` (its
231
+ * branch) when it is a registered linked worktree. */
232
+ function retainedWorktree(path) {
233
+ const kind = kindOf(path);
234
+ if (kind !== "dir") return { path, facts: [notADirectory(kind)] };
235
+ const gitFile = kindOf(join(path, ".git"));
236
+ if (gitFile !== "other") return { path, facts: ["not a registered worktree (it has no .git file)"] };
237
+ const dirs = gitRead(path, ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "--show-toplevel"]);
238
+ if (!dirs.ok) return { path, facts: [`not a registered worktree (Git could not read it: ${shown(dirs.err)})`] };
239
+ const [gitDir, commonDir, toplevel] = dirs.out.split("\n");
240
+ const real = realOrNull(path);
241
+ if (!toplevel || realOrNull(toplevel) !== real) return { path, facts: [`not a registered worktree (its top level is ${shown(toplevel || "unknown")})`] };
242
+ const realCommon = commonDir && realOrNull(commonDir);
243
+ if (!gitDir || !realCommon || realOrNull(gitDir) === realCommon) return { path, facts: ["not a registered worktree (it is not a linked worktree)"] };
244
+ const list = gitRepoRead(realCommon, ["worktree", "list", "--porcelain", "-z"]);
245
+ const trees = list.ok ? list.out.split("\0").filter((f) => f.startsWith("worktree ")).map((f) => f.slice("worktree ".length)) : [];
246
+ if (!list.ok) return { path, facts: [`not a registered worktree (its repository's worktree list could not be read: ${shown(list.err)})`] };
247
+ if (!trees.some((t) => realOrNull(t) === real)) return { path, facts: ["not a registered worktree (its repository's worktree list does not name it)"] };
248
+ const facts = [`repository ${shown(trees[0])}`];
249
+ const head = headOf((argv, options) => gitRead(path, argv, options));
250
+ if (head.error) facts.push(`HEAD unknown (${shown(head.error)})`);
251
+ else facts.push(head.ref ? `branch ${shown(refText(shortRef(head.ref)))}` : `detached at ${head.commit.slice(0, 12)}`);
252
+ facts.push(...cleanFacts(path, gitDir));
253
+ if (!head.error) facts.push(commitsFact(realCommon, head.commit, head.ref));
254
+ return { path, facts, commonDir: realCommon, ref: head.ref ?? null };
255
+ }
256
+
257
+ /** The retained worktrees under `<deployment>/.agents/worktrees/<repo>/`,
258
+ * each read (retainedWorktree), sorted by path; an entry that is not a
259
+ * directory, at either level, is listed as such. → { trees, unreadable }:
260
+ * `unreadable`, the directories that could not be listed. */
261
+ export function retainedWorktrees(deployment) {
262
+ const root = retainedWorktreesRoot(deployment);
263
+ const trees = [], unreadable = [];
264
+ let repos;
265
+ try { repos = namesIn(root); } catch (e) { return { trees, unreadable: [{ path: root, error: e }] }; }
266
+ for (const repo of repos) {
267
+ const dir = join(root, repo);
268
+ const kind = kindOf(dir);
269
+ if (kind !== "dir") { trees.push({ path: dir, facts: [notADirectory(kind)] }); continue; }
270
+ let leaves;
271
+ try { leaves = namesIn(dir); } catch (e) { unreadable.push({ path: dir, error: e }); continue; }
272
+ for (const leaf of leaves) trees.push({ path: join(dir, leaf) });
273
+ }
274
+ // Read every tree: a recovery line names the one on its branch, wherever it is in the list.
275
+ return { trees: trees.map((t) => (t.facts ? t : retainedWorktree(t.path))), unreadable };
276
+ }
277
+
278
+ /** The repository a recovery's copied home records (`instance.json` `repo`):
279
+ * a hint, never authority. It is used only when it is the top level of a
280
+ * Git repository, canonical paths compared (or a bare repository's Git
281
+ * directory). → { commonDir } (canonical) | { error }. */
282
+ function recordedRepository(recorded) {
283
+ const notGit = { error: `recorded repository ${shown(recorded)} is not a Git repository` };
284
+ if (!isAbsolute(recorded)) return notGit;
285
+ const real = realOrNull(recorded);
286
+ if (!real) return { error: `recorded repository ${shown(recorded)} is not there` };
287
+ const work = gitRead(real, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]);
288
+ if (work.ok) {
289
+ const [toplevel, commonDir] = work.out.split("\n");
290
+ if (realOrNull(toplevel) === real && realOrNull(commonDir)) return { commonDir: realOrNull(commonDir) };
291
+ }
292
+ const bare = gitRepoRead(real, ["rev-parse", "--path-format=absolute", "--is-bare-repository", "--git-common-dir"]);
293
+ if (bare.ok) {
294
+ const [isBare, commonDir] = bare.out.split("\n");
295
+ if (isBare === "true" && realOrNull(commonDir) === real) return { commonDir: real };
296
+ }
297
+ return notGit;
298
+ }
299
+
300
+ /** The facts of a recovery's repository copy (`repo/`): its HEAD's
301
+ * reachability in the source repository, and the retained worktree of that
302
+ * repository on the same branch, when there is one. */
303
+ function recoveryCommitFacts(recovery, worktrees) {
304
+ const repo = join(recovery, "repo");
305
+ const kind = kindOf(repo);
306
+ if (kind.error?.code === "ENOENT") return ["commits: no repository copy"];
307
+ if (kind !== "dir") return [`commits: unknown (repo/: ${notADirectory(kind)})`];
308
+ const gitDir = join(repo, ".git");
309
+ if (kindOf(gitDir) !== "dir") return ["commits: unknown (repo/.git is not a directory)"];
310
+ // The clone's own Git directory, named explicitly: never one found by walking up from it.
311
+ const head = headOf((argv, options) => gitRepoRead(gitDir, argv, options));
312
+ if (head.error) return [`commits: unknown (the copy's HEAD could not be read: ${shown(head.error)})`];
313
+ const home = readJsonFile(join(recovery, "home", "instance.json"));
314
+ const recorded = isObject(home.value) ? home.value.repo : undefined;
315
+ if (typeof recorded !== "string" || !recorded) return [`commits: unknown (the copied home's instance.json ${home.error ? `is ${home.error}` : "records no repository"})`];
316
+ const source = recordedRepository(recorded);
317
+ if (source.error) return [`commits: unknown (${source.error})`];
318
+ const facts = [commitsFact(source.commonDir, head.commit, head.ref)];
319
+ if (head.ref) for (const tree of worktrees) if (tree.commonDir === source.commonDir && tree.ref === head.ref) facts.push(`retained worktree on the same branch: ${shown(tree.path)}`);
320
+ return facts;
321
+ }
322
+
323
+ /** One recovery copy's facts. A dot-named entry is the staging of a copy
324
+ * that a retire could not remove. */
325
+ function recoveryFacts(path, name, worktrees) {
326
+ const kind = kindOf(path);
327
+ if (kind !== "dir") return [notADirectory(kind)];
328
+ if (name.startsWith(".")) return ["unfinished copy (staging a retire could not remove)", sizeFact(path)];
329
+ const facts = [];
330
+ const manifest = readJsonFile(join(path, "recovery.json"));
331
+ const m = manifest.value;
332
+ if (!isObject(m)) {
333
+ facts.push(`recovery.json is ${manifest.error ?? "not a JSON object"}, so its phase and classes are not known`);
334
+ // `<instance>-<six random characters>`, as the retire names it (mkdtemp).
335
+ facts.push(`instance ${shown(name.replace(/-[^-]{6}$/, ""))} (by the directory's name)`);
336
+ } else {
337
+ facts.push(typeof m.instance === "string" ? `instance ${shown(m.instance)}` : "instance not recorded");
338
+ facts.push(typeof m.phase === "string" ? `phase ${shown(m.phase)}` : "phase not recorded");
339
+ const classes = Array.isArray(m.classes) && m.classes.every((c) => typeof c === "string") ? m.classes : null;
340
+ facts.push(classes ? `classes: ${classes.length ? classes.map(shown).join(", ") : "none"}` : "classes not recorded");
341
+ }
342
+ facts.push(sizeFact(path));
343
+ const afterHooks = kindOf(join(path, "after-hooks"));
344
+ facts.push(afterHooks === "dir" ? "after-hooks/ present" : afterHooks.error?.code === "ENOENT" ? "no after-hooks/" : `after-hooks: ${notADirectory(afterHooks)}`);
345
+ facts.push(...recoveryCommitFacts(path, worktrees));
346
+ return facts;
347
+ }
348
+
349
+ /** The count line, then at most RETAINED_LINES_MAX lines: the items, then
350
+ * the directories that could not be listed (whose contents are not counted);
351
+ * past them, `… and N more`. [] when there is nothing to say. */
352
+ function boundedLines(prefix, noun, items, unreadable, facts) {
353
+ if (!items.length && !unreadable.length) return [];
354
+ const notListed = unreadable.length ? `; ${unreadable.length} ${unreadable.length === 1 ? "directory" : "directories"} could not be listed, and what they hold is not counted` : "";
355
+ const lines = [`${prefix}: ${items.length} ${noun(items.length)} that retires left in this deployment${notListed}; nothing removes them; ${DOCS}`];
356
+ const entries = [...items, ...unreadable.map((u) => ({ ...u, unreadable: true }))];
357
+ for (const entry of entries.slice(0, RETAINED_LINES_MAX)) {
358
+ lines.push(entry.unreadable ? `${prefix}: ${shown(entry.path)} could not be listed (${why(entry.error)})` : `${prefix}: ${shown(entry.path)}: ${facts(entry).join("; ")}`);
359
+ }
360
+ if (entries.length > RETAINED_LINES_MAX) lines.push(`${prefix}: … and ${entries.length - RETAINED_LINES_MAX} more`);
361
+ return lines;
362
+ }
363
+
364
+ /** The `retained-recovery:` information lines: one per recovery copy under
365
+ * the recovery storage of each instances directory of the agents root
366
+ * `agentsRoot` (where retire writes them: retirementRecoveryRoot), with its
367
+ * instance, phase, classes, size, after-hooks/ and the reachability of its
368
+ * clone's HEAD. `kept`: retainedWorktrees(deployment). */
369
+ export function retainedRecoveryLines(agentsRoot, kept) {
370
+ const items = [], unreadable = [];
371
+ for (const instances of instancesDirs(agentsRoot)) {
372
+ const root = retirementRecoveryRoot(instances);
373
+ let names;
374
+ try { names = namesIn(root); } catch (e) { unreadable.push({ path: root, error: e }); continue; }
375
+ for (const name of names) items.push({ path: join(root, name), name });
376
+ }
377
+ items.sort((a, b) => byCodeUnit(a.path, b.path));
378
+ return boundedLines(RECOVERY, (n) => `recovery ${n === 1 ? "copy" : "copies"}`, items, unreadable, (item) => recoveryFacts(item.path, item.name, kept.trees));
379
+ }
380
+
381
+ /** The `retained-worktree:` information lines: one per entry under
382
+ * `<deployment>/.agents/worktrees/<repo>/`, with its repository, branch (or
383
+ * detached commit), whether it is clean, and its HEAD's reachability.
384
+ * `kept`: retainedWorktrees(deployment). */
385
+ export function retainedWorktreeLines(kept) {
386
+ return boundedLines(WORKTREE, (n) => `retained worktree${n === 1 ? "" : "s"}`, kept.trees, kept.unreadable, (tree) => tree.facts);
387
+ }
package/lib/schedule.mjs CHANGED
@@ -32,7 +32,7 @@ import { loadLocal } from "./workspace.mjs";
32
32
  import { noteRuntimeName } from "./deprecation.mjs";
33
33
  import { herdrSettingRemoved } from "./errors.mjs";
34
34
  import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
35
- import { tickTriggers } from "./triggers.mjs";
35
+ import { pollSourced, tickTriggers } from "./triggers.mjs";
36
36
  import { resolveMemberClone } from "./instance-resolution.mjs";
37
37
  import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
38
38
  import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
@@ -918,6 +918,9 @@ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, ca
918
918
  export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
919
919
  const reg = readRegistry();
920
920
  const wsList = reg.workspaces.filter((w) => existsSync(w));
921
+ // When this tick started: no trigger source's poll may end later than 50 s after it; `sourced`
922
+ // collects every scope's due capability-source triggers, polled host-wide below (lib/triggers.mjs).
923
+ const tick = { start: (io?.clock ?? Date.now)(), sourced: [] };
921
924
  const body = () => {
922
925
  const considered = [];
923
926
  // Observe every registered scope first, then admit in one host-wide
@@ -945,9 +948,12 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
945
948
  }
946
949
  // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
947
950
  for (const ws of wsList) {
948
- try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws), reg, wsList })); }
951
+ try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws), reg, wsList, tick })); }
949
952
  catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
950
953
  }
954
+ // Capability sources: every scope's in one most-overdue-first order, under the tick's one deadline.
955
+ try { considered.push(...pollSourced(tick.sourced, { now, io, dryRun, reg, wsList, tickStart: tick.start, reserved: tick.reserved ?? 0 })); }
956
+ catch (e) { considered.push({ action: "error", error: `trigger sources: ${e.message}` }); }
951
957
  if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
952
958
  return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
953
959
  };