@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.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/lib/instance-events.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
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
|
package/lib/instance-git.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
67
|
-
* it through GIT_CONFIG_PARAMETERS), and nothing of the
|
|
68
|
-
* environment is passed. → stdout; throws the error
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
}
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -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` :
|
|
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
|
|
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:
|
|
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),
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -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 } : {
|
|
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
|
-
|
|
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
|
|
679
|
-
* start), `interrupted` once it is gone
|
|
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" }[
|
|
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
|