@awebai/oats 0.69.12 → 0.69.15

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 (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -42,13 +42,22 @@
42
42
  * that checks "the rows' home is the home I asked for" keeps holding. */
43
43
  import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
44
44
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
45
- import { REFUSED_TEXT } from "./refused-text.mjs";
45
+ import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
46
46
 
47
47
  export const EVENTS_API = 2;
48
48
  const HOME_LOG = ".oats-events.jsonl";
49
49
  const MAX_BYTES = 4 * 1024 * 1024;
50
50
 
51
- export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "retire-refused", "worktree-retained", "worktree-removed", "worktree-added", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "modules-upgraded", "upgrade-refused", "waiting", "wake-held"];
51
+ /** The kind of the row a retire hook's warning is recorded as (#1749): the one name the writer
52
+ * (retireInstance) and its tests use. */
53
+ export const RETIRE_HOOK_WARNING_KIND = "retire-warning";
54
+ /** The kinds whose `data.message` is a hook's or the kernel's warning text, and the longest one a
55
+ * row stores, in UTF-16 code units: the Desktop events reader's default detail bound
56
+ * (`eventsDetail`), which refuses the WHOLE read past it, as for RETIRE_REFUSED_REASON_MAX. */
57
+ const WARNING_KINDS = ["launch-warning", RETIRE_HOOK_WARNING_KIND];
58
+ export const WARNING_MESSAGE_MAX = 2048;
59
+
60
+ export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "retire-refused", RETIRE_HOOK_WARNING_KIND, "worktree-retained", "worktree-removed", "worktree-added", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "modules-upgraded", "upgrade-refused", "waiting", "wake-held"];
52
61
 
53
62
  /** The longest `reason` a `retire-refused` row carries, in UTF-16 code units. The bound is not the
54
63
  * kernel's: the Desktop's events reader refuses a whole read that holds a longer detail
@@ -60,9 +69,13 @@ export const RETIRE_REFUSED_REASON_MAX = 2048;
60
69
  * units. A longer one is cut and ends with `…`, the mark counted in the bound, and never through a
61
70
  * surrogate pair. */
62
71
  export function retireRefusedReason(sentence) {
63
- const line = String(sentence).replace(/\s+/g, " ").trim();
64
- if (line.length <= RETIRE_REFUSED_REASON_MAX) return line;
65
- const cut = line.slice(0, RETIRE_REFUSED_REASON_MAX - 1);
72
+ return cutToUnits(String(sentence).replace(/\s+/g, " ").trim(), RETIRE_REFUSED_REASON_MAX);
73
+ }
74
+ /** `text` at most `max` UTF-16 code units: a longer one is cut and ends with `…`, the mark counted
75
+ * in the bound, and never through a surrogate pair. */
76
+ function cutToUnits(text, max) {
77
+ if (text.length <= max) return text;
78
+ const cut = text.slice(0, max - 1);
66
79
  const last = cut.charCodeAt(cut.length - 1);
67
80
  // A high surrogate at the end was the first half of a pair the cut went through.
68
81
  return `${last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut}…`;
@@ -193,7 +206,16 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
193
206
  // `at`: the time the fact became true, when it is recorded later (a start
194
207
  // boundary reconciled from its receipt); readers order rows by it.
195
208
  if (at !== undefined && !validTime(at)) return { ok: false, reason: `invalid event time ${at}` };
196
- const row = { eventsApi: EVENTS_API, at: at ?? new Date().toISOString(), instance: a.instance, home: a.home, incarnation: incarnation === undefined ? a.incarnation : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
209
+ // A warning's message is text from outside (a hook's own words, or a kernel line quoting them):
210
+ // stored made safe and bounded here, where no writer can skip it, and never interpreted. A value
211
+ // that is not a string is stored as its JSON. The answer that carried the warning keeps it as given.
212
+ let data = event.data;
213
+ if (WARNING_KINDS.includes(event.kind) && data && typeof data === "object" && Object.hasOwn(data, "message")) {
214
+ const m = data.message;
215
+ // safeText with no bound only replaces; the cut counts the units the Desktop reader counts.
216
+ data = { ...data, message: cutToUnits(safeText(typeof m === "string" ? m : JSON.stringify(m), Infinity), WARNING_MESSAGE_MAX) };
217
+ }
218
+ const row = { eventsApi: EVENTS_API, at: at ?? new Date().toISOString(), instance: a.instance, home: a.home, incarnation: incarnation === undefined ? a.incarnation : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(data !== undefined ? { data } : {}) };
197
219
  const line = JSON.stringify(row) + "\n";
198
220
  const results = [];
199
221
  // Retirement fingerprints the home against its baseline and preserves any
@@ -25,21 +25,162 @@ export const INSTANCE_GIT_API = 1;
25
25
  * (GIT_NO_LAZY_FETCH=1): an object a promisor repository lacks is a failed
26
26
  * read, never fetched through the remote, helper, ssh command or credential
27
27
  * helper the repository's configuration names, and never written into it.
28
- * Git before 2.44 ignores the variable. */
28
+ * Git before 2.44 ignores the variable.
29
+ *
30
+ * Filter drivers (`filter.<name>.clean`, `.process`, `.smudge`): Git runs a
31
+ * clean or process filter when a status or a diff compares a work-tree file
32
+ * that carries the `filter` attribute, and it has no switch that turns
33
+ * filters off. Their names are the repository's to choose, so a command
34
+ * is preceded by one read of the configuration Git would use
35
+ * (`git config --list`, which runs nothing and follows `include.path` and
36
+ * `includeIf`), and every driver that read names is overridden to no command
37
+ * and not required (filterOverrides). An observation (observeInstanceGit)
38
+ * makes that read once, before its status, for its status and its line
39
+ * counts. A file with such an attribute is then
40
+ * compared as its bytes are in the work tree, unfiltered. A driver whose
41
+ * name `-c` cannot carry (it holds `=`, or is not UTF-8) is not overridden:
42
+ * the command is not run and the read fails. What this does not cover:
43
+ * - a driver added to the configuration between that read and the command
44
+ * (two processes; Git reads its configuration itself). For an observation
45
+ * that is until its last command that reads a work-tree file, the line
46
+ * counts' diff, which runs after the status and the reads of HEAD, the
47
+ * index and the refs;
48
+ * - a submodule's own configuration. A status or a diff of the work tree
49
+ * runs Git inside each populated submodule to learn whether it is dirty,
50
+ * and that Git reads the submodule's configuration: the overrides reach it
51
+ * (as fsmonitor's, the hooks' and the external diff's do), but they name
52
+ * this repository's drivers, not the submodule's.
53
+ *
54
+ * Commands that read no file of the work tree are not preceded by that
55
+ * read: the reads of HEAD and of refs (readHead, gitRefPresence,
56
+ * worktreeCommitUnreached: `symbolic-ref`, `rev-parse`, `for-each-ref`), and
57
+ * this module's own READS_NO_WORK_TREE_FILE commands. A command another
58
+ * module passes (gitRead, gitRepoRead, gitRepoRun) always is. */
59
+ /** The setting that keeps Git from running the `core.fsmonitor` command a repository's
60
+ * configuration names, which it asks whenever it reads the index of a work tree. */
61
+ export const NO_FILE_MONITOR = ["-c", "core.fsmonitor=false"];
29
62
  const READ_ONLY_GIT = ["--no-optional-locks",
30
- "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
63
+ ...NO_FILE_MONITOR, "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
31
64
  "-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
65
+ /** The subcommands this module runs (git) that read refs, objects, the index or the configuration,
66
+ * and no file of the work tree: no filter can run in them. */
67
+ const READS_NO_WORK_TREE_FILE = new Set(["rev-parse", "symbolic-ref", "merge-base", "rev-list", "ls-files", "config", "remote"]);
32
68
  function gitEnv() {
33
69
  const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", LANG: "C", LC_ALL: "C", GIT_OPTIONAL_LOCKS: "0", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" };
34
70
  // The user's global config may name helpers too; observations do not need it.
35
71
  env.GIT_CONFIG_GLOBAL = "/dev/null";
36
72
  return env;
37
73
  }
38
- function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
74
+ /** The `filter.<name>.<variable>` keys of a `git config --list -z` listing → [{ name, variable }].
75
+ * A record is "<key>\n<value>", or "<key>" alone. A driver's name is any text, dots and the empty
76
+ * one included (`filter..clean`); a variable holds no dot, and Git prints it in lower case. */
77
+ export function filterDriverKeys(listing) {
78
+ const keys = [];
79
+ for (const record of listing.split("\0")) {
80
+ const nl = record.indexOf("\n");
81
+ const m = /^filter\.(.*)\.([^.]+)$/s.exec(nl < 0 ? record : record.slice(0, nl));
82
+ if (m) keys.push({ name: m[1], variable: m[2] });
83
+ }
84
+ return keys;
85
+ }
86
+ /** The filter drivers the configuration of the repository at `where` (`-C <tree>` or `--git-dir <dir>`)
87
+ * defines, and the `-c` arguments that keep Git from running any of them
88
+ * → { ok: true, count, args } | { ok: false, refused, err }.
89
+ * `refused: true`: a driver is defined whose name `-c` cannot carry, so nothing can be run safely.
90
+ * `refused: false`: the configuration could not be read (`err` is Git's own words); the command it
91
+ * was read for would fail the same way.
92
+ * The listing is read as bytes (latin1 keeps each one): a name is passed on only when it is UTF-8,
93
+ * since that is how an argument reaches Git.
94
+ * The configuration listed is the repository's own (its local and per-worktree files and what they
95
+ * include), read with gitEnv: a driver that only the operator's own configuration (global, system)
96
+ * defines is not listed, and so not overridden where a caller's Git reads that configuration.
97
+ * `operatorEnv`, for a caller whose Git reads the operator's own configuration (a retire, a
98
+ * worktree removal), is the environment that Git runs with. A driver the repository defines under
99
+ * a name that configuration defines too is then overridden with the operator's own values, not
100
+ * with none: the operator's command runs, as it does for that name everywhere else the operator's
101
+ * Git runs (a retire's recovery copy has no configuration of its own), and the repository's never
102
+ * does. Where the repository defines `process` for that name and the operator's configuration
103
+ * does not, neither runs: the override that silences the repository's `process` silences the
104
+ * operator's clean and smudge commands with it, and the file is read or written unfiltered.
105
+ * The operator's configuration is the human's; the repository's is the agent's to write. A
106
+ * configuration of the operator's that cannot be read defines nothing.
107
+ * The one reader of a repository's filter drivers: this module's commands, a retire's
108
+ * (lib/core.mjs retireGitArgv), and a checkout's and a worktree removal's (workTreeOverrides)
109
+ * take their overrides here. */
110
+ export function filterOverrides(where, { operatorEnv } = {}) {
111
+ const r = spawnSync("git", [...where, ...READ_ONLY_GIT, "config", "--list", "-z"], { encoding: "latin1", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
112
+ if (r.error || r.status !== 0) return { ok: false, refused: false, err: String(r.error?.message ?? r.stderr ?? "").trim() || `git config exited with ${r.status}` };
113
+ const names = new Map();
114
+ for (const key of filterDriverKeys(r.stdout)) names.set(key.name, (names.get(key.name) ?? new Set()).add(key.variable));
115
+ const operator = names.size > 0 && operatorEnv ? operatorDrivers(operatorEnv) : new Map();
116
+ const args = [];
117
+ for (const [raw, variables] of names) {
118
+ const bytes = Buffer.from(raw, "latin1");
119
+ const name = bytes.toString("utf8");
120
+ if (name.includes("=") || !Buffer.from(name, "utf8").equals(bytes)) {
121
+ return { ok: false, refused: true, err: "the repository's configuration defines a filter driver whose name cannot be overridden on Git's command line (it holds \"=\" or is not UTF-8), so Git was not run: it would run that filter" };
122
+ }
123
+ const own = operator.get(raw) ?? {};
124
+ for (const command of ["clean", "smudge", "process"]) {
125
+ // Git runs a driver's clean and smudge commands only while its `process` is not set, and one
126
+ // set to nothing counts as set: the operator's commands for a name whose `process` neither
127
+ // configuration defines run only when `process` is left out.
128
+ if (command === "process" && operator.has(raw) && own.process === undefined && !variables.has("process")) continue;
129
+ args.push("-c", `filter.${name}.${command}=${own[command] ?? ""}`);
130
+ }
131
+ args.push("-c", `filter.${name}.required=${own.required ?? "false"}`);
132
+ }
133
+ return { ok: true, count: names.size, args };
134
+ }
135
+ /** The `-c` arguments of a Git command that reads or writes the files of a work tree of the
136
+ * repository at `where`, and that runs with `operatorEnv` and so reads the operator's own
137
+ * configuration: a checkout (a spawn's `git worktree add` in lib/core.mjs; the `git worktree add`
138
+ * and `git switch` of `oats worktree add` in lib/worktree.mjs) and the reads of
139
+ * `oats worktree remove` (lib/worktree.mjs) → filterOverrides's result, its `args` preceded by
140
+ * NO_FILE_MONITOR. Whoever works in a clone can write its configuration, and such a command would
141
+ * run two kinds of command it names: a filter driver for a file it reads or writes, and the
142
+ * `core.fsmonitor` command. Git's hooks (`post-checkout`) are not turned off here. */
143
+ export function workTreeOverrides(where, operatorEnv) {
144
+ const filters = filterOverrides(where, { operatorEnv });
145
+ return filters.ok ? { ...filters, args: [...NO_FILE_MONITOR, ...filters.args] } : filters;
146
+ }
147
+ /** The filter drivers the operator's own configuration defines, as the Git that runs with `env`
148
+ * reads it: the system configuration, then the global one (`~/.gitconfig`,
149
+ * `$XDG_CONFIG_HOME/git/config`, or `$GIT_CONFIG_GLOBAL`), whose value wins as it does for Git
150
+ * → Map of a driver's name, as the bytes of the listing, to { clean?, smudge?, process?,
151
+ * required? }, each the last value given. A scope that cannot be read (no such file) defines
152
+ * nothing, and the system one is not read when `env` tells Git not to (GIT_CONFIG_NOSYSTEM, a
153
+ * Git boolean: `git config --system` itself reads the file regardless). Each is read by its
154
+ * scope: no repository's configuration is part of it. */
155
+ function operatorDrivers(env) {
156
+ const drivers = new Map();
157
+ const noSystem = !["", "0", "false", "no", "off"].includes(String(env.GIT_CONFIG_NOSYSTEM ?? "").trim().toLowerCase());
158
+ for (const scope of noSystem ? ["--global"] : ["--system", "--global"]) {
159
+ const r = spawnSync("git", [...READ_ONLY_GIT, "config", scope, "--list", "-z"], { encoding: "latin1", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env });
160
+ if (r.error || r.status !== 0) continue;
161
+ for (const record of r.stdout.split("\0")) {
162
+ const nl = record.indexOf("\n");
163
+ const [key] = filterDriverKeys(nl < 0 ? record : record.slice(0, nl));
164
+ if (!key) continue;
165
+ if (!drivers.has(key.name)) drivers.set(key.name, {});
166
+ drivers.get(key.name)[key.variable] = Buffer.from(nl < 0 ? "true" : record.slice(nl + 1), "latin1").toString("utf8");
167
+ }
168
+ }
169
+ return drivers;
170
+ }
171
+ /** `overrides`: a filterOverrides result the caller already has for `cwd` (an observation reads it
172
+ * once for its commands); without it the command is preceded by its own read. */
173
+ function git(cwd, argv, { allowFail = false, input, diffExit = false, overrides } = {}) {
39
174
  const [sub, ...rest] = argv;
40
175
  const extra = sub === "diff" ? ["--no-ext-diff", "--no-textconv", "--no-color"] : [];
176
+ const filters = READS_NO_WORK_TREE_FILE.has(sub) ? { ok: true, args: [] } : overrides ?? filterOverrides(["-C", cwd]);
177
+ if (!filters.ok) {
178
+ // A refusal is not Git failing: it is never read as "no answer".
179
+ if (allowFail && !filters.refused) return null;
180
+ throw oatsError("E_GIT_FAILED", `git ${sub} failed in ${cwd}: ${filters.err}`);
181
+ }
41
182
  try {
42
- return execFileSync("git", [...READ_ONLY_GIT, "-C", cwd, sub, ...extra, ...rest], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, input, shell: false, timeout: 30_000, env: gitEnv() });
183
+ return execFileSync("git", [...READ_ONLY_GIT, ...filters.args, "-C", cwd, sub, ...extra, ...rest], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, input, shell: false, timeout: 30_000, env: gitEnv() });
43
184
  } catch (e) {
44
185
  // `git diff --no-index` exits 1 when the inputs differ: that is the answer, not a failure.
45
186
  if (diffExit && e.status === 1 && typeof e.stdout === "string") return e.stdout;
@@ -63,11 +204,15 @@ export function gitRepoRead(gitDir, argv, { input, encoding } = {}) { return git
63
204
  /** A Git command that changes the repository whose Git directory is `gitDir`
64
205
  * (a worktree move, remove or prune), under the same discipline as the
65
206
  * reads: the repository's own configuration names no helper that runs
66
- * (fsmonitor, hooks, external diff; they reach the commands Git starts for
67
- * it through GIT_CONFIG_PARAMETERS), and nothing of the caller's Git
68
- * environment is passed. → stdout; throws the error execFileSync throws. */
207
+ * (fsmonitor, hooks, external diff, filter drivers; they reach the commands
208
+ * Git starts for it through GIT_CONFIG_PARAMETERS), and nothing of the
209
+ * caller's Git environment is passed. → stdout; throws the error
210
+ * execFileSync throws, or an Error when a filter driver cannot be overridden
211
+ * (filterOverrides), in which case Git was not run. */
69
212
  export function gitRepoRun(gitDir, argv) {
70
- 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() });
213
+ const filters = filterOverrides(["--git-dir", gitDir]);
214
+ if (!filters.ok) throw new Error(`git ${argv[0]} was not run in ${gitDir}: ${filters.err}`);
215
+ return execFileSync("git", ["--git-dir", gitDir, ...READ_ONLY_GIT, ...filters.args, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 120_000, env: gitEnv() });
71
216
  }
72
217
  /** What the result of a `git rev-parse -q --verify <ref>` (spawnSync's) says
73
218
  * of the ref → "there" (status 0), "absent" (status 1 and nothing printed),
@@ -90,7 +235,9 @@ export function gitRefPresence(cwd, name) {
90
235
  return gitRefPresenceOf(spawnSync("git", ["-C", cwd, ...READ_ONLY_GIT, "rev-parse", "-q", "--verify", name], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() }));
91
236
  }
92
237
  function gitProbe(where, argv, input, encoding = "utf8") {
93
- 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() });
238
+ const filters = filterOverrides(where);
239
+ if (!filters.ok) return { ok: false, out: "", err: filters.err };
240
+ const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...filters.args, ...argv], { encoding, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
94
241
  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}` };
95
242
  }
96
243
 
@@ -280,10 +427,10 @@ function remoteOf(work, branch) {
280
427
  * and `oats instance diff`. An unborn tree counts against the empty tree (`hash-object` without -w writes nothing).
281
428
  * → Map path → { additions, deletions, binary }, keyed by the NEW path for a rename; null when git failed.
282
429
  * -z records: "A\tD\tpath\0", or "A\tD\t\0old\0new\0" for a rename; "-\t-" is a binary file. */
283
- function lineCounts(work, headOid) {
284
- const against = headOid ?? trim(git(work, ["hash-object", "-t", "tree", "/dev/null"], { allowFail: true }));
430
+ function lineCounts(work, headOid, overrides) {
431
+ const against = headOid ?? trim(git(work, ["hash-object", "-t", "tree", "/dev/null"], { allowFail: true, overrides }));
285
432
  if (!against) return null;
286
- const raw = git(work, ["diff", against, "--numstat", "-z", "-M", "--"], { allowFail: true });
433
+ const raw = git(work, ["diff", against, "--numstat", "-z", "-M", "--"], { allowFail: true, overrides });
287
434
  if (raw === null) return null;
288
435
  const counts = new Map(), recs = raw.split("\0");
289
436
  for (let i = 0; i < recs.length;) {
@@ -343,7 +490,10 @@ export function assertSameWorktreeHead(inspected, now) {
343
490
  export function observeInstanceGit(home) {
344
491
  const { meta, work, mode } = instanceWorkTree(home);
345
492
  const headOid = trim(git(work, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowFail: true }));
346
- const raw = git(work, ["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=all", "--ignore-submodules=none"]);
493
+ // The repository's filter drivers, read once for the observation's commands that read a
494
+ // work-tree file (the status here, the line counts below).
495
+ const filters = filterOverrides(["-C", work]);
496
+ const raw = git(work, ["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=all", "--ignore-submodules=none"], { overrides: filters });
347
497
  const { branch, entries } = parsePorcelainV2(raw);
348
498
  // The name comes from headName, not from the status header, which prints
349
499
  // "(detached)" and other words where a name would be and is read as text.
@@ -365,7 +515,7 @@ export function observeInstanceGit(home) {
365
515
  const counts = mergeBase ? countRange(work, `${base.ref}...HEAD`) : null;
366
516
  baseComparison = { ref: base.ref, source: base.source, mergeBase, ahead: counts ? counts.right : null, behind: counts ? counts.left : null };
367
517
  }
368
- const counts = lineCounts(work, headOid);
518
+ const counts = lineCounts(work, headOid, filters);
369
519
  const files = entries.filter((e) => e.kind !== "ignored").map((e) => ({ id: fileId(revision, indexOid, e), ...e, ...countsOf(counts, e) }));
370
520
  const summary = { changed: 0, renamed: 0, copied: 0, unmerged: 0, untracked: 0 };
371
521
  for (const f of files) summary[f.kind]++;
@@ -383,6 +533,7 @@ export function observeInstanceGit(home) {
383
533
  ...(upstream.ref === null ? ["no upstream configured: upstream ahead/behind are unknown, not zero"] : []),
384
534
  ...(baseComparison.ref === null ? ["no default branch found (origin/HEAD, origin/main, origin/master, main, master): base comparison unknown"] : []),
385
535
  ...(counts === null ? ["line counts unavailable (git diff --numstat failed): additions/deletions are unknown, not zero"] : []),
536
+ ...(filters.ok && filters.count > 0 ? ["the repository's configuration defines a filter driver, and filters are not run: a file one applies to is compared as its bytes are in the work tree, so it can read as changed, and its diff is against the stored form"] : []),
386
537
  ],
387
538
  };
388
539
  }
@@ -780,9 +780,14 @@ function packageSoulItem(t, d) {
780
780
  const shipped = (d.packageSouls || []).filter((s) => s.package === p.id);
781
781
  const live = shipped.find((s) => s.name === p.soul);
782
782
  if (!live) {
783
+ // A home whose package is no longer locked: readiness cannot tell a deliberate drop (only a respawn moves
784
+ // the home) from an accidental unpin or a pending sync (declaring it again fixes it in place), so the
785
+ // remedy names both, the respawn first. A soul (no home) can still be pinned.
786
+ const absent = t.home ? `if the workspace dropped ${p.id} on purpose, spawn a new instance from a soul this workspace offers (oats souls lists them), then retire this one; otherwise declare ${p.id} in the workspace's packages:, then oats sync`
787
+ : `declare ${p.id} in the workspace's packages:, then oats sync`;
783
788
  return item(subject, "fail", { producer: "workspace lock", evidence,
784
789
  reason: shipped.length ? `the version of ${p.id} locked in this workspace does not ship the soul ${p.soul}` : `${p.id} is not locked in this workspace's packages:`,
785
- remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : `declare ${p.id} in the workspace's packages:, then oats sync` });
790
+ remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : absent });
786
791
  }
787
792
  const integrity = (reason, remedy) => item(subject, "fail", { producer: "workspace lock", code: "E_PACKAGE_INTEGRITY", reason, evidence, remedy });
788
793
  const lockRemedy = "oats sync (a lock that was edited: remove the entry and sync again)";
@@ -11,6 +11,7 @@ import { createHash } from "node:crypto";
11
11
  import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
12
12
  import { join } from "node:path";
13
13
  import { attachedWorkLink, claimHomeFor, extraWorktreePlan, homeClaimHolder, identifiedHomeRecord, refuseBesideRetire, inspectInstanceSession, instanceWork, listAgents, listInstances, observeSessionWithoutReceipt, readHomeRecord, READ_CLAIM_WHEN_UNWRITABLE, releaseHomeClaim, requireStopGrace, retireClaimPath, retirePendingMarkerPath, retirementRecoveryFacts, shq, stillRunningOf, stopInstanceSession, STOP_UNDER_CLAIM } from "./core.mjs";
14
+ import { retireCarried } from "./instance-listing.mjs";
14
15
  import { groupedByOwner } from "./retire-output.mjs";
15
16
  import { observeInstanceGit } from "./instance-git.mjs";
16
17
  import { appendEvent } from "./instance-events.mjs";
@@ -192,14 +193,14 @@ function workFacts(home) {
192
193
  * (targetRecord) or a child's (otherRecord). `retiring` and `stopPending` are read from the
193
194
  * home's lifecycle claim (core homeClaimHolder), by the holder's verb: a holder that is not gone
194
195
  * (alive, or of a liveness that cannot be read) counts, and `retiring` is also true while a
195
- * self-retire is scheduled (its pending marker). A claim in `own` is the caller's and is not
196
- * reported. */
196
+ * self-retire is scheduled (its pending marker, unless the completion it names is gone:
197
+ * retireCarried). A claim in `own` is the caller's and is not reported. */
197
198
  function targetFacts(row, meta = {}, own) {
198
199
  const held = homeClaimHolder(row.home);
199
200
  const holds = (action) => !!held && held.action === action && held.state !== "gone" && !own?.has(held.holder.nonce);
200
201
  return { instance: row.instance, agent: row.agent, home: row.home, depth: row.depth ?? 0, workMode: meta.work ?? null, launched: meta.launched === true,
201
202
  session: sessionFacts(row.home), work: workFacts(row.home),
202
- retiring: existsSync(retirePendingMarkerPath(row.home)) || holds("retire"), stopPending: holds("stop") };
203
+ retiring: retireCarried(row.home) || holds("retire"), stopPending: holds("stop") };
203
204
  }
204
205
 
205
206
  /** Facts for Stop: the instance, its recorded descendants (deepest first),
@@ -18,7 +18,7 @@ import { readInstanceBackground } from "./instance-background.mjs";
18
18
  import { sameWorkOf } from "./instance-same-work.mjs";
19
19
  import { readSpawnedBy } from "./spawned-by.mjs";
20
20
  import { sessionEndOf } from "./session-end.mjs";
21
- import { recordSeen } from "./session-seen.mjs";
21
+ import { identityHolderState, recordSeen } from "./session-seen.mjs";
22
22
  import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
23
23
  import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot } from "./session-inspect.mjs";
24
24
 
@@ -180,7 +180,7 @@ export function redactLaunchCommand(command) {
180
180
  /** The recipe as answers carry it: every environment value withheld, and without `kernelBin`
181
181
  * (the home's record keeps it; human `oats status` reads it from there). */
182
182
  export function redactLaunchRecipe(recipe) {
183
- const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { fromEnv: recipe.env[n].fromEnv }]));
183
+ const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { ...recipe.env[n] }]));
184
184
  const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
185
185
  const { kernelBin: _recorded, ...answered } = recipe;
186
186
  return { ...answered, env, ...(hooks ? { hooks } : {}) };
@@ -312,27 +312,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
312
312
  const record = readHomeRecord(home);
313
313
  if (record.state === "record") records?.set(home, record.meta);
314
314
  const meta = record.state === "record" ? upgradeHomeMeta(record.meta, home) : { instance: e.name, home };
315
- // A home retained by an incomplete rollback is NOT a live instance: it
316
- // is preserved state awaiting cleanup, and must read that way.
317
- const fallback = directoryRollbackPath(home);
318
- const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
319
- let rollbackIncomplete, spawnInProgress;
320
- if (existsSync(quarantine)) {
321
- try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
322
- catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
323
- // #796: a spawn still running its worktree hooks keeps a marker that names it
324
- // (`inProgress`). While that process is verifiably alive the home is a spawn in
325
- // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
326
- // start cannot be read is not shown in progress either: on a host that never reads it, the
327
- // row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
328
- // the pid), and retire, which never takes it for gone, refuses it with the way out.
329
- if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
330
- }
331
- // A self-retire that has been requested but not completed: the home is
332
- // owed a retirement, not live work. Read-only here — completion is the
333
- // detached child's or an operator's `oats retire`, never status.
334
- const { retirePending, marker } = readRetirePending(home);
335
- const retire = retireStateOf(home, marker);
315
+ const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
336
316
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
337
317
  // A home whose record cannot be read is listed, never observed: where its session is, is in the record.
338
318
  const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
@@ -387,22 +367,6 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
387
367
 
388
368
  });
389
369
  };
390
- // Failed deferred self-retirements leave their outcome beside the home; a
391
- // successful one is evidence only and is not a problem to surface.
392
- const readRetireFailuresOf = (agentDir) => {
393
- const instancesDir = join(agentDir, "instances");
394
- if (!existsSync(instancesDir)) return [];
395
- const out = [];
396
- for (const e of readdirSync(instancesDir, { withFileTypes: true })) {
397
- const m = e.isFile() && /^\.oats-retired-(.+)\.json$/.exec(e.name);
398
- if (!m) continue;
399
- try {
400
- const r = JSON.parse(readFileSync(join(instancesDir, e.name), "utf8"));
401
- if (r.ok === false) out.push({ instance: m[1], completedAt: r.completedAt, error: r.error?.message, incomplete: r.result?.rollbackIncomplete, retry: r.retry, resultPath: join(instancesDir, e.name) });
402
- } catch { out.push({ instance: m[1], error: "unreadable result file", resultPath: join(instancesDir, e.name) }); }
403
- }
404
- return out;
405
- };
406
370
  const withFailures = (entry, agentDir) => {
407
371
  const retireFailures = readRetireFailuresOf(agentDir);
408
372
  return retireFailures.length ? { ...entry, retireFailures } : entry;
@@ -430,6 +394,84 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
430
394
  return out;
431
395
  }
432
396
 
397
+ /** What is beside and in `home` about a retire of it, as its status row reads it (listInstances,
398
+ * openRetirements): `rollbackIncomplete` (the quarantine marker), `spawnInProgress`,
399
+ * `retirePending` (the pending marker) and `retire` (retireStateOf). Each is undefined when it
400
+ * does not apply. Only read: no claim is taken, no file removed, no process signalled. */
401
+ function readRetireFacts(home) {
402
+ // A home retained by an incomplete rollback is NOT a live instance: it
403
+ // is preserved state awaiting cleanup, and must read that way.
404
+ const fallback = directoryRollbackPath(home);
405
+ const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
406
+ let rollbackIncomplete, spawnInProgress;
407
+ if (existsSync(quarantine)) {
408
+ try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
409
+ catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
410
+ // #796: a spawn still running its spawn or worktree hooks keeps a marker that names it
411
+ // (`inProgress`). While that process is verifiably alive the home is a spawn in
412
+ // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
413
+ // start cannot be read is not shown in progress either: on a host that never reads it, the
414
+ // row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
415
+ // the pid), and retire, which never takes it for gone, refuses it with the way out.
416
+ if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
417
+ }
418
+ // A self-retire that has been requested but not completed: the home is
419
+ // owed a retirement, not live work. Read-only here — completion is the
420
+ // detached child's or an operator's `oats retire`, never status.
421
+ const { retirePending, marker } = readRetirePending(home);
422
+ const retire = retireStateOf(home, marker);
423
+ return { rollbackIncomplete, spawnInProgress, retirePending, retire };
424
+ }
425
+
426
+ /** The failed deferred self-retirements of the soul at `agentDir`: the outcome each left beside its
427
+ * home, whether the home is still there or not (a status listing's `retireFailures`). A successful
428
+ * one is evidence only and is not a problem to surface. */
429
+ function readRetireFailuresOf(agentDir) {
430
+ const instancesDir = join(agentDir, "instances");
431
+ if (!existsSync(instancesDir)) return [];
432
+ const out = [];
433
+ for (const e of readdirSync(instancesDir, { withFileTypes: true })) {
434
+ const m = e.isFile() && /^\.oats-retired-(.+)\.json$/.exec(e.name);
435
+ if (!m) continue;
436
+ try {
437
+ const r = JSON.parse(readFileSync(join(instancesDir, e.name), "utf8"));
438
+ if (r.ok === false) out.push({ instance: m[1], completedAt: r.completedAt, error: r.error?.message, incomplete: r.result?.rollbackIncomplete, retry: r.retry, resultPath: join(instancesDir, e.name) });
439
+ } catch { out.push({ instance: m[1], error: "unreadable result file", resultPath: join(instancesDir, e.name) }); }
440
+ }
441
+ return out;
442
+ }
443
+
444
+ /** The homes under `root` and what is beside each about a retire of it, read as `oats status` reads
445
+ * it and from the same souls' directories (listInstances), without its sessions, tmux or process
446
+ * scans and without recording what it saw: for `oats doctor` (lib/retire-incomplete.mjs). Only
447
+ * read. → [{ agent, dir, homes: [{ instance, home, record, rollbackIncomplete?, spawnInProgress?,
448
+ * retirePending?, retire? }], retireFailures }]: `record` is "record", "absent" or "unreadable"
449
+ * (readHomeRecord), with `recordSaid` for an unreadable one. */
450
+ export function openRetirements(root) {
451
+ const homesOf = (agentDir) => {
452
+ const instancesDir = join(agentDir, "instances");
453
+ return (existsSync(instancesDir) ? readdirSync(instancesDir, { withFileTypes: true }) : [])
454
+ .filter((e) => e.isDirectory() && !e.name.startsWith("."))
455
+ .map((e) => {
456
+ const home = join(instancesDir, e.name);
457
+ const record = readHomeRecord(home);
458
+ return { instance: e.name, home, record: record.state, ...(record.state === "unreadable" ? { recordSaid: unreadableRecordSaid(record) } : {}), kind: record.state === "record" ? record.meta.kind : undefined, ...readRetireFacts(home) };
459
+ });
460
+ };
461
+ const out = listAgents(root).map((a) => ({ agent: a.name, dir: a._dir, homes: homesOf(a._dir), retireFailures: readRetireFailuresOf(a._dir) }));
462
+ // The capability-defined agents listInstances lists, by its rule.
463
+ const seen = new Set(out.map((a) => a.agent));
464
+ for (const { name, dir } of capabilityAgentDirs(root)) {
465
+ if (seen.has(name)) continue;
466
+ const homes = homesOf(dir), retireFailures = readRetireFailuresOf(dir);
467
+ if (!homes.some((h) => h.kind === "capability") && !retireFailures.length) continue;
468
+ out.push({ agent: name, dir, homes, retireFailures });
469
+ seen.add(name);
470
+ }
471
+ for (const a of out) for (const h of a.homes) delete h.kind;
472
+ return out;
473
+ }
474
+
433
475
  // A substituted/missing home cannot hold its own receipt. This sibling fallback
434
476
  // is independent of both home bytes and the recovery storage that may have failed.
435
477
  function directoryRollbackPath(home) {
@@ -666,6 +708,35 @@ function readRetirePending(home) {
666
708
  catch { return { retirePending: { reason: "retire pending" }, marker: { read: undefined } }; }
667
709
  }
668
710
 
711
+ /** Whether the completion a pending marker names (`pending`, the marker as it parsed) can still
712
+ * act: the state identityHolderState (packages/record/lib/process-identity.mjs) gives the holder
713
+ * the marker records (its pid, its start, the boot it runs in), the one judgement of a recorded
714
+ * holder: gone when the marker was written in another boot, whatever its pid reads as, else as its
715
+ * process reads. → { state: "gone" | "alive" | "unknown", reason? }; `reason` says why the state
716
+ * could not be told.
717
+ * A pending marker is always judged as naming its identity: its start and its boot are passed
718
+ * whether or not the marker has them. One that has neither therefore reads `unknown` while its pid
719
+ * exists, which a retire refuses with the step that ends it by hand, and never `alive` by its pid
720
+ * alone: a retire that reads as running refuses every other retire, and a pid that exists may be
721
+ * another process's. */
722
+ export const completionLiveness = (pending) => {
723
+ const holder = { pid: pending.completionPid, processStart: pending.completionStart, bootId: pending.completionBoot };
724
+ const state = identityHolderState(holder);
725
+ return state === "unknown" ? { state, reason: processLiveness(holder).reason ?? "the marker names no process that can be judged" } : { state };
726
+ };
727
+
728
+ /** Whether a self-retire holds `home` against a stop: its pending marker is there, and the
729
+ * completion it names is not gone (completionLiveness: it lives, or whether it does cannot be
730
+ * read). A marker that names no completion, or does not parse, holds the home too: whether its
731
+ * retire runs cannot be told. One whose completion is gone holds nothing: the home is owed the
732
+ * retire, nothing carries it out, and a session that still runs there is stopped as any other. */
733
+ export function retireCarried(home) {
734
+ const marker = retirePendingMarkerPath(home);
735
+ if (!existsSync(marker)) return false;
736
+ const pending = readJsonOrUndefined(marker);
737
+ return !(isPlainObject(pending) && Number.isSafeInteger(pending.completionPid) && completionLiveness(pending).state === "gone");
738
+ }
739
+
669
740
  /** A status row's `retire` (feature status-retire-state, lib/retire-state.mjs): whether a retire of
670
741
  * `home` runs, could not be told, failed or was interrupted, read from what is beside the home
671
742
  * (`marker`: `{ read }` when its retire marker is there, `read` what its file parsed as, undefined
@@ -675,9 +746,9 @@ function readRetirePending(home) {
675
746
  * - The marker of a self-retire comes first, whatever the claim says (its completion holds the
676
747
  * claim for its own retire), and gives `self: true`. A completion's result that says `ok:
677
748
  * false` is `failed`, with its time, code and message. Otherwise, a result that says anything
678
- * else included, the marker's completion decides: `running` while it lives (pid and recorded
679
- * start), `interrupted` once it is gone, and `unknown` when that cannot be read or the marker
680
- * names no completion. A marker that does not parse is `unknown`.
749
+ * else included, the marker's completion decides (completionLiveness): `running` while it lives
750
+ * (pid and recorded start), `interrupted` once it is gone (another boot's included), and
751
+ * `unknown` when that cannot be read or the marker names no completion. A marker that does not parse is `unknown`.
681
752
  * - Without a marker, the home's claim held for a retire is `running` while its holder lives and
682
753
  * `unknown` when that cannot be read, with `self: false`. A holder that is gone, a stop's claim
683
754
  * or no claim gives no value.
@@ -707,7 +778,7 @@ function retireStateOf(home, marker) {
707
778
  }
708
779
  const pid = pending.completionPid;
709
780
  const state = !Number.isSafeInteger(pid) || pid <= 0 ? "unknown"
710
- : { alive: "running", gone: "interrupted" }[processLiveness({ pid, processStart: pending.completionStart }).state] ?? "unknown";
781
+ : { alive: "running", gone: "interrupted" }[completionLiveness(pending).state] ?? "unknown";
711
782
  return readRetireState({ state, self: true, since: instantOr(pending.requestedAt) ?? markerTime() });
712
783
  }
713
784
  // Most rows have no claim: asked without the throw of a read that finds none, which is most of