@awebai/oats 0.48.0 → 0.50.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 (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -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
+ }
@@ -30,11 +30,15 @@ export function receiptRecoveries(receipt) {
30
30
  return receipt?.workRecovery ? [receipt.workRecovery] : [];
31
31
  }
32
32
 
33
+ /** Where the summary sends an operator to inspect, restore or dispose of a recovery (#703). */
34
+ const RECOVERY_POINTER = " to inspect, restore or dispose of a recovery: see docs/souls-and-instances.md#after-a-retire-inspect-restore-dispose";
35
+
33
36
  /** The lines `oats retire` prints for what a receipt preserved; `host` (the
34
37
  * remote path) names where. Per recovery: the classes, the path with its
35
38
  * size, then, when they apply, what was copied from the home, the copied
36
39
  * outputs, the home entries left out by a capability's declaration (names and
37
- * owners only) and which parts were copied again under after-hooks/. */
40
+ * owners only) and which parts were copied again under after-hooks/; and,
41
+ * after them all, where the docs say what to do with a recovery. */
38
42
  export function workRecoveryLines(receipt, { host } = {}) {
39
43
  const lines = [];
40
44
  for (const recovery of receiptRecoveries(receipt)) {
@@ -47,6 +51,7 @@ export function workRecoveryLines(receipt, { host } = {}) {
47
51
  const again = [recovery.afterHooks?.home === true && "home", recovery.afterHooks?.work === true && "work"].filter(Boolean);
48
52
  if (again.length) lines.push(` after the retire hooks: ${again.join(" and ")} copied again under after-hooks/`);
49
53
  }
54
+ if (lines.length) lines.push(RECOVERY_POINTER);
50
55
  return lines;
51
56
  }
52
57
 
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";
@@ -552,6 +552,7 @@ export function childEnv() {
552
552
  "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
553
553
  "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
554
554
  "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
555
+ "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
555
556
  ]) delete env[key];
556
557
  return env;
557
558
  }
@@ -917,6 +918,9 @@ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, ca
917
918
  export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
918
919
  const reg = readRegistry();
919
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: [] };
920
924
  const body = () => {
921
925
  const considered = [];
922
926
  // Observe every registered scope first, then admit in one host-wide
@@ -944,9 +948,12 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
944
948
  }
945
949
  // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
946
950
  for (const ws of wsList) {
947
- 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 })); }
948
952
  catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
949
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}` }); }
950
957
  if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
951
958
  return { tickedAt: now.toISOString(), minute: minuteKey(minuteStart(now)), considered, scheduler: schedulerStatus(undefined, io) };
952
959
  };
package/lib/servers.mjs CHANGED
@@ -798,6 +798,27 @@ const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k,
798
798
  * value passes the kernel's own read rule again; anything it refuses is null. */
799
799
  const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: readWaitingClaim(i.waitingOnYou) } : {});
800
800
 
801
+ /** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
802
+ export const HOST_FEATURES_MAX = 256;
803
+ export const HOST_FEATURE_NAME_MAX = 64;
804
+ const FEATURE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
805
+ /** The host's kernel features from its `status --json` result (feature server-probe-features), or
806
+ * null when unknown. The answer is untrusted: it is relayed as given (order, duplicates and all)
807
+ * only when it is an array of at most HOST_FEATURES_MAX names, each a string of lowercase
808
+ * hyphen-separated words of at most HOST_FEATURE_NAME_MAX characters. Anything else, a host
809
+ * before 0.49.0 that omits the key, or a single bad entry, is null: never filtered, coerced,
810
+ * sorted or deduped. `[]` is a valid answer, distinct from null. */
811
+ export function hostFeatures(result) {
812
+ if (!result || typeof result !== "object" || !Object.hasOwn(result, "features")) return null;
813
+ const list = result.features;
814
+ if (!Array.isArray(list) || list.length > HOST_FEATURES_MAX) return null;
815
+ for (let i = 0; i < list.length; i++) {
816
+ const name = list[i];
817
+ if (typeof name !== "string" || name.length > HOST_FEATURE_NAME_MAX || !FEATURE_NAME_RE.test(name)) return null;
818
+ }
819
+ return [...list];
820
+ }
821
+
801
822
  export function rosterGroups({ server, io = {} } = {}) {
802
823
  const started = Date.now();
803
824
  if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
@@ -837,20 +858,25 @@ export function rosterGroups({ server, io = {} } = {}) {
837
858
  const bySnapshot = new Map(g._snapshots.map((s) => [s.instance, s]));
838
859
  const routeOf = (i) => { const s = bySnapshot.get(i.instance); return s && s.home && i.home && resolve(s.home) === resolve(i.home) ? s : undefined; };
839
860
  if (status?.ok) {
840
- g.probe = { ok: true };
841
- g.agentsRoot = status.result.root;
861
+ // A success envelope whose result is null or missing reads as an empty answer, never a crash
862
+ // that would sink every other group.
863
+ const result = status.result ?? {};
864
+ // The host's own kernel features (feature server-probe-features), relayed from the same status
865
+ // answer, never probed: null when the host does not report a valid list.
866
+ g.probe = { ok: true, features: hostFeatures(result) };
867
+ g.agentsRoot = result.root;
842
868
  // The host's own workspace identity (feature workspace-identity), relayed as it answered it: never
843
869
  // derived here, null when the host reports none.
844
- g.workspace = status.result.workspace ?? null;
845
- for (const a of status.result.agents || []) {
846
- g.souls.push({ name: a.name, harness: a.harness ?? a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: status.result.root });
870
+ g.workspace = result.workspace ?? null;
871
+ for (const a of result.agents || []) {
872
+ g.souls.push({ name: a.name, harness: a.harness ?? a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: result.root });
847
873
  // A failed deferred self-retirement needs an operator: it rides with
848
874
  // the group, named by agent and instance, as `oats status` prints it.
849
875
  for (const f of a.retireFailures || []) g.retireFailures.push({ agent: a.name, ...f });
850
876
  for (const i of a.instances || []) {
851
877
  const snap = routeOf(i);
852
878
  g.instances.push({
853
- server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: status.result.root,
879
+ server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
854
880
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
855
881
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
856
882
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
package/lib/tree-copy.mjs CHANGED
@@ -3,9 +3,19 @@
3
3
  import {
4
4
  chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync,
5
5
  } from "node:fs";
6
- import { join } from "node:path";
6
+ import { sep } from "node:path";
7
7
  import { oatsError } from "./errors.mjs";
8
8
 
9
+ const SEPARATOR = Buffer.from(sep);
10
+ /** A path as bytes: a Buffer as it is, a string as its UTF-8. */
11
+ export const pathBytes = (path) => (Buffer.isBuffer(path) ? path : Buffer.from(path));
12
+ /** `dir` and `name` joined with the separator byte, as bytes: what a name read
13
+ * as bytes needs to be opened by its own name. */
14
+ export const joinBytes = (dir, name) => Buffer.concat([pathBytes(dir), SEPARATOR, pathBytes(name)]);
15
+ /** The entries of a directory, their names as bytes, in the order of those
16
+ * bytes (Buffer.compare): `readdirSync`'s Dirents, `withFileTypes`. */
17
+ export const entriesAsBytes = (dir) => readdirSync(pathBytes(dir), { encoding: "buffer", withFileTypes: true }).sort((a, b) => Buffer.compare(a.name, b.name));
18
+
9
19
  /** Recursively copy a tree the way `cpSync(..., { recursive: true })` would —
10
20
  * except catchably.
11
21
  *
@@ -18,8 +28,11 @@ import { oatsError } from "./errors.mjs";
18
28
  * where an EACCES is an ordinary throwable error.
19
29
  *
20
30
  * Semantics chosen to be safe rather than maximally faithful:
21
- * - deterministic traversal (sorted entries), so two copies of one tree hash
22
- * identically;
31
+ * - names are read, joined and written as bytes, never as decoded text, so a
32
+ * name that is not valid UTF-8 is copied as it is. `src` and `dest` may be
33
+ * strings or Buffers;
34
+ * - deterministic traversal (entries in the order of their bytes), so two
35
+ * copies of one tree hash identically;
23
36
  * - symlinks are recreated VERBATIM — never followed, never rewritten — because
24
37
  * the bytes about to be hashed must be the bytes the author wrote. The target
25
38
  * is read and written as bytes: read as text, a target that is not valid
@@ -33,12 +46,10 @@ export function copyTreeSafe(src, dest) {
33
46
  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); return; }
34
47
  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
35
48
  if (!st.isDirectory()) {
36
- throw oatsError("invalid-source", `${src} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
49
+ throw oatsError("invalid-source", `${src.toString()} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
37
50
  }
38
51
  mkdirSync(dest, { recursive: true });
39
- for (const e of readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
40
- copyTreeSafe(join(src, e.name), join(dest, e.name));
41
- }
52
+ for (const e of entriesAsBytes(src)) copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name));
42
53
  chmodSync(dest, st.mode & 0o7777);
43
54
  }
44
55