@awebai/oats 0.69.14 → 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 (49) hide show
  1. package/bin/oats.mjs +79 -18
  2. package/docs/capabilities.md +54 -12
  3. package/docs/container.md +57 -12
  4. package/docs/desktop-cli-api.md +215 -19
  5. package/docs/execution-targets.md +15 -3
  6. package/docs/first-team.md +4 -3
  7. package/docs/implementation.md +18 -8
  8. package/docs/release-notes/v0.69.15.md +444 -0
  9. package/docs/schedules.md +133 -2
  10. package/docs/servers.md +60 -2
  11. package/docs/souls-and-instances.md +87 -7
  12. package/docs/upgrading.md +17 -5
  13. package/lib/claim.mjs +2 -3
  14. package/lib/command-flags.mjs +4 -2
  15. package/lib/core.mjs +215 -72
  16. package/lib/dir-lock.mjs +17 -0
  17. package/lib/errors.mjs +2 -1
  18. package/lib/host-run.mjs +218 -0
  19. package/lib/host-stop-child.mjs +21 -0
  20. package/lib/instance-git.mjs +32 -6
  21. package/lib/instance-lifecycle.mjs +4 -3
  22. package/lib/instance-listing.mjs +35 -6
  23. package/lib/kernel-features.mjs +4 -1
  24. package/lib/read-call.mjs +1 -1
  25. package/lib/remote.mjs +17 -14
  26. package/lib/schedule.mjs +237 -20
  27. package/lib/servers.mjs +83 -5
  28. package/lib/session-end.mjs +28 -8
  29. package/lib/session-resume.mjs +10 -18
  30. package/lib/session-seen.mjs +4 -64
  31. package/lib/status-words.mjs +11 -4
  32. package/lib/system-tools.mjs +1 -36
  33. package/lib/worktree-hooks.mjs +6 -175
  34. package/lib/worktree.mjs +19 -10
  35. package/package.json +4 -1
  36. package/packages/record/README.md +56 -21
  37. package/packages/record/docs/capture-service.md +8 -5
  38. package/packages/record/docs/turn-record-sot.md +9 -0
  39. package/packages/record/lib/capture-health.mjs +6 -4
  40. package/packages/record/lib/capture-lock.mjs +31 -27
  41. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  42. package/packages/record/lib/capture-scratch.mjs +2 -1
  43. package/packages/record/lib/derived-state.mjs +4 -2
  44. package/packages/record/lib/index-db.mjs +4 -2
  45. package/packages/record/lib/lock-holder.mjs +21 -0
  46. package/packages/record/lib/private-files.mjs +18 -0
  47. package/packages/record/lib/process-identity.mjs +310 -0
  48. package/packages/record/lib/store.mjs +31 -25
  49. package/skills/oats-getting-started/SKILL.md +1 -1
package/lib/errors.mjs CHANGED
@@ -60,7 +60,8 @@ const SPAWN_REFUSAL_DETAILS = Object.freeze({
60
60
  E_CHILD_SPAWNS_DISABLED: (e) => ({ parent: e.parent, policy: e.policy }),
61
61
  E_BRANCH_EXISTS: () => undefined,
62
62
  E_BASE_UNKNOWN: () => undefined,
63
- // Interrupted while its worktree hooks ran (#796): rolled back, the message says how far.
63
+ // Interrupted while its capabilities were copied into the home, or while its worktree hooks ran
64
+ // (#796): rolled back, the message says how far.
64
65
  E_INTERRUPTED: (e) => e.details,
65
66
  // The hooks' receipt (paths only), and `unconfirmed` when the rollback could not confirm its effects.
66
67
  E_REQUIRED_HOOK_FAILED: hookReceipt,
@@ -0,0 +1,218 @@
1
+ /** `oats host run` (oats-project/oats#1789): the kernel's periodic work in one foreground process,
2
+ * for a host where no timer can run it (a container, a machine without launchd or a systemd user
3
+ * manager). Every `oats` command is short-lived and agents sit under a daemonised tmux server, so
4
+ * without it nothing there runs the resume sweep at start or the schedule tick each minute, and
5
+ * nothing stops the agents in order when the host stops.
6
+ *
7
+ * - Refused before any effect: inside an instance session (OATS_INSTANCE_HOME set), E_USAGE; while
8
+ * the host timer is active (lib/schedule-host.mjs hostUnitStatus), E_HOST_RUN_TIMER_ACTIVE: two
9
+ * tickers would run. Unit files that are installed and not active are a warning. Nothing asks
10
+ * whether this is a container: the command is as right on a machine without a user manager.
11
+ * - One host run per machine: the lock `host-run/lock` under OATS_HOME_DIR (default ~/.oats), taken
12
+ * as the resume sweep takes its own (lib/dir-lock.mjs acquireDirLock): a claim that names its
13
+ * holder by pid, process start and boot id. A lock whose holder is gone, or that was taken in
14
+ * another boot (in a container, another run), is taken over at once; a holder that runs, and a
15
+ * lock that cannot be judged, are E_HOST_RUN_BUSY, `details` `{ lock, found }`.
16
+ * - A run, in order: the lock; the resume sweep once (`oats session resume`); then, at second 0 of
17
+ * each minute, `oats schedule tick --host` when the host schedule registry lists a scope (with
18
+ * none it ticks nothing and says so), and a listing of every deployment's instances, which
19
+ * records what runs for the next start's sweep. Each is an `oats` child, so this process's
20
+ * loop stays free for the signal. A minute whose tick still runs is skipped; a minute missed is
21
+ * never replayed (the host timer's own rule).
22
+ * - SIGTERM or SIGINT stops it (hostRun): ticking first, then every running home, so that the
23
+ * next start resumes them; then it answers and exits 0.
24
+ * - `plan` says what a run would refuse, the scopes it would tick (the host schedule registry) and
25
+ * what its sweep would do (lib/session-resume.mjs, its own plan), and changes nothing.
26
+ * The answers' shapes and the two codes are a contract (docs/desktop-cli-api.md). */
27
+ import { homedir } from "node:os";
28
+ import { join } from "node:path";
29
+ import { fileURLToPath } from "node:url";
30
+ import { acquireDirLock, dirLockHeld, stuckLockRemedy } from "./dir-lock.mjs";
31
+ import { oatsError } from "./errors.mjs";
32
+ import { hostUnitStatus } from "./schedule-host.mjs";
33
+ import { readRegistry } from "./schedule.mjs";
34
+ import { kernelAnswer, resumeSessions } from "./session-resume.mjs";
35
+ import { OUTCOME } from "./session-resume-contract.mjs";
36
+ import { bootId, takenInAnotherBoot } from "./session-seen.mjs";
37
+
38
+ export const HOST_RUN_SCHEMA = 1;
39
+ /** What a run and a plan say when the host schedule registry lists no scope. */
40
+ export const NO_SCOPE_SAID = "no scope is registered, so nothing is ticked: register a deployment with oats schedule host install --register-only --dir <deployment>";
41
+
42
+ /** The signals that stop a run: what a container runtime sends, and Ctrl-C. */
43
+ const STOP_SIGNALS = ["SIGTERM", "SIGINT"];
44
+ const oatsHomeDir = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
45
+ export const hostRunLockPath = () => join(oatsHomeDir(), "host-run", "lock");
46
+
47
+ /** E_HOST_RUN_BUSY for the lock `path`, found as lib/dir-lock.mjs says it (`why`, `found`): a host
48
+ * run that runs, or a lock that needs a person, with what to do about it. */
49
+ function hostRunBusy(path, why, found) {
50
+ const said = found === "running" ? `another oats host run on this machine holds ${path} (${why})` : `the host run lock ${path} cannot be taken (${why}); ${stuckLockRemedy(path, found, "oats host run")}`;
51
+ return Object.assign(oatsError("E_HOST_RUN_BUSY", `${said}; nothing was started`), { details: { lock: path, found } });
52
+ }
53
+ /** Take the machine's host run lock → its release function. Its record also names the boot it was
54
+ * taken in (lib/session-seen.mjs bootId, takenInAnotherBoot), as the resume sweep's does. */
55
+ export function acquireHostRunLock({ boot = bootId() } = {}) {
56
+ const path = hostRunLockPath();
57
+ return acquireDirLock(path, { bootId: boot }, { busy: (why, { found }) => hostRunBusy(path, why, found), holderGone: takenInAnotherBoot(boot) });
58
+ }
59
+
60
+ /** What refuses a run before it takes its lock, in the order a run meets them: `inInstance`, the
61
+ * refusal inside an instance session, or null; `timer(unit)`, the refusal for what the host timer
62
+ * answered (hostUnitStatus), or null. A run asks the timer only once it is not refused as an instance. */
63
+ function refusalsBeforeLock({ env, hostStatus }) {
64
+ const home = env.OATS_INSTANCE_HOME;
65
+ const inInstance = home ? oatsError("E_USAGE", `oats host run runs as the host, never inside an instance session: OATS_INSTANCE_HOME is set (${home}); nothing was started`) : null;
66
+ return { inInstance, timer: (unit) => (unit.active ? Object.assign(oatsError("E_HOST_RUN_TIMER_ACTIVE", `the host timer is active (${unit.unit}) and already runs oats schedule tick --host every minute; remove it (oats schedule host uninstall) before oats host run; nothing was started`), { details: { unit: unit.unit } }) : null) };
67
+ }
68
+ /** The warning for unit files that are installed while the timer is not active, or none. */
69
+ const inactiveUnitWarnings = (unit) => (unit.installed && !unit.active
70
+ ? [`the host timer's unit files are installed but not active (${unit.unit}): oats host run ticks in its place; remove them (oats schedule host uninstall) so that the timer cannot start beside it`] : []);
71
+
72
+ /** `oats host run --plan` → `{ schemaVersion, plan: true, refusals, warnings, scopes, sweep }`:
73
+ * `refusals` every refusal a run would meet now (`{ code, message, details? }`, in a run's order),
74
+ * the lock's included, `scopes` the registered scopes it would tick, `sweep` the resume sweep's
75
+ * own plan. Read only. */
76
+ export async function hostRunPlan({ env = process.env, boot = bootId(), hostStatus = hostUnitStatus } = {}) {
77
+ const refuse = refusalsBeforeLock({ env, hostStatus }), unit = hostStatus();
78
+ // The lock as a run would find it, read where the run takes it and not taken (dirLockHeld).
79
+ const path = hostRunLockPath(), held = dirLockHeld(path, { holderGone: takenInAnotherBoot(boot) });
80
+ const refusals = [refuse.inInstance, refuse.timer(unit), held && hostRunBusy(path, held.why, held.found)].filter(Boolean).map((e) => ({ code: e.code, message: e.message, ...(e.details ? { details: e.details } : {}) }));
81
+ return { schemaVersion: HOST_RUN_SCHEMA, plan: true, refusals, warnings: inactiveUnitWarnings(unit), scopes: readRegistry().workspaces, sweep: await resumeSessions({ plan: true, env }) };
82
+ }
83
+
84
+ const MINUTE = 60_000;
85
+ /** How long a stopped home's harness is given when `--stop-grace` says nothing: the stop's own default. */
86
+ const STOP_GRACE_MS = 20_000;
87
+ const STOP_CHILD = fileURLToPath(new URL("./host-stop-child.mjs", import.meta.url));
88
+ /** A timer that fires this long before its minute, or less, is early: nothing runs then. */
89
+ const EARLY_MS = 1000;
90
+ const plural = (n, what) => `${n} ${what}${n === 1 ? "" : "s"}`;
91
+ /** A child's failure as the run says it. */
92
+ const failed = (answer) => `(${answer?.error?.code ?? "E_HOST_RUN_FAILED"}): ${answer?.error?.message ?? "no answer"}`;
93
+ /** The sweep's rows by outcome, in the order they first appear: `2 resumed, 1 skipped`. */
94
+ function sweepSaid(rows) {
95
+ const counts = new Map();
96
+ for (const row of rows) counts.set(row.outcome, (counts.get(row.outcome) ?? 0) + 1);
97
+ return counts.size ? [...counts].map(([outcome, n]) => `${n} ${outcome}`).join(", ") : "nothing to resume";
98
+ }
99
+
100
+ /** `oats host run`: refuses (above), then runs until SIGTERM or SIGINT →
101
+ * `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the resume
102
+ * sweep's answer, or `{ error: { code, message } }`; `ticks` the minutes counted (`run`,
103
+ * `skipped` while the tick before still ran, `failed`, `noScope` with no scope registered);
104
+ * `stopped` one row per home that ran when it stopped, in the listing's order (stopHome).
105
+ *
106
+ * On the signal, in this order: no minute is armed any more; a tick or a sweep that runs is
107
+ * waited for (a tick's wake job starts a stopped home, so ticking ends before any home is
108
+ * stopped); one listing; then every running home is stopped, side by side, each by a child of its
109
+ * own (lib/host-stop-child.mjs: the stop `oats session restart` and a retire use, its record
110
+ * written first and asking for a resume, the harness given `stopGraceMs` and never escalated).
111
+ * The next start's sweep resumes those homes.
112
+ *
113
+ * `stopHome(home, graceMs)` → Promise of `{ ok: true, home, stopped, alreadyIdle, state }` or
114
+ * `{ ok: false, home, code, message, stillRunning }`, which never rejects.
115
+ * `kernel` is `{ execPath, bin }`, how an `oats` child is run. The other options are the process
116
+ * boundary, for the tests: `run(argv)` → Promise of a child's JSON answer, which never rejects;
117
+ * `now()` and `timer(fn, ms)` → its cancel; `onSignal(handler)` → the function that stops
118
+ * listening; `scopes()` the registered scopes; `say(line)` one line of progress. */
119
+ export async function hostRun({
120
+ kernel, env = process.env, boot = bootId(), hostStatus = hostUnitStatus,
121
+ scopes = () => readRegistry().workspaces,
122
+ run = (argv) => kernelAnswer({ ...kernel, env }, argv, { code: "E_HOST_RUN_FAILED", what: `oats ${argv.join(" ")}` }),
123
+ stopGraceMs = STOP_GRACE_MS,
124
+ stopHome = async (home, graceMs) => {
125
+ const answer = await kernelAnswer({ execPath: kernel.execPath, bin: STOP_CHILD, env }, [home, String(graceMs)], { code: "E_SESSION_STOP_FAILED", what: "the stop" });
126
+ return answer.error ? { ok: false, home, code: answer.error.code, message: answer.error.message, stillRunning: null } : answer;
127
+ },
128
+ now = Date.now,
129
+ timer = (fn, ms) => { const armed = setTimeout(fn, ms); return () => clearTimeout(armed); },
130
+ onSignal = (handler) => {
131
+ for (const signal of STOP_SIGNALS) process.on(signal, handler);
132
+ return () => { for (const signal of STOP_SIGNALS) process.off(signal, handler); };
133
+ },
134
+ say = (line) => { process.stderr.write(`oats host run: ${line}\n`); },
135
+ } = {}) {
136
+ const refuse = refusalsBeforeLock({ env, hostStatus });
137
+ if (refuse.inInstance) throw refuse.inInstance;
138
+ const unit = hostStatus(), active = refuse.timer(unit);
139
+ if (active) throw active;
140
+ const release = acquireHostRunLock({ boot });
141
+ let signal = null, disarm = null, stopListening = () => {};
142
+ try {
143
+ const warnings = inactiveUnitWarnings(unit);
144
+ const stopRequested = new Promise((requested) => {
145
+ // The first signal ends the ticking at once: no minute is armed after it. A later one changes nothing.
146
+ stopListening = onSignal((received) => {
147
+ if (signal) return;
148
+ signal = received;
149
+ disarm?.();
150
+ requested();
151
+ });
152
+ });
153
+ say(`started (pid ${process.pid}); it holds ${hostRunLockPath()}`);
154
+ for (const warning of warnings) say(`warning: ${warning}`);
155
+
156
+ // The sweep, once: a home lost while this runs is a crash, and the sweep's bound is per boot.
157
+ const swept = await run(["session", "resume", "--json"]);
158
+ const sweep = swept?.ok === true ? swept.result : { error: { code: swept?.error?.code ?? "E_HOST_RUN_FAILED", message: swept?.error?.message ?? "no answer" } };
159
+ say(swept?.ok === true ? `resume sweep: ${sweepSaid(sweep.rows ?? [])}` : `resume sweep failed ${failed(swept)}`);
160
+
161
+ // The minutes. Each is armed from the clock as it reads then, for second 0 of the next one: a
162
+ // minute missed while this process did not run is never armed again.
163
+ const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
164
+ let ticking = null, listing = null, ticked;
165
+ const list = () => run(["session", "resume", "--plan", "--json"]);
166
+ const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
167
+ const minute = () => {
168
+ if (signal) return;
169
+ // Early: a tick started now would evaluate the minute before (it reads its own start).
170
+ if (now() % MINUTE >= MINUTE - EARLY_MS) return arm();
171
+ let registered;
172
+ try { registered = scopes(); } catch (e) { registered = null; ticks.failed += 1; say(`tick failed (${e?.code ?? "E_HOST_RUN_FAILED"}): ${e?.message ?? e}`); }
173
+ if (registered && registered.join("\n") !== ticked) {
174
+ ticked = registered.join("\n");
175
+ say(registered.length ? `ticking ${plural(registered.length, "scope")} each minute: ${registered.join(", ")}` : NO_SCOPE_SAID);
176
+ }
177
+ if (registered && !registered.length) ticks.noScope += 1;
178
+ else if (registered && ticking) { ticks.skipped += 1; say("tick skipped: the tick of the minute before still runs"); }
179
+ else if (registered) {
180
+ ticks.run += 1;
181
+ ticking = run(["schedule", "tick", "--host", "--json"]).then((answer) => {
182
+ ticking = null;
183
+ if (answer?.ok !== true) { ticks.failed += 1; say(`tick failed ${failed(answer)}`); }
184
+ });
185
+ }
186
+ // The listing each minute writes what the sweep of the next start needs: that each running
187
+ // home was seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
188
+ // deployment, which its plan does and nothing else).
189
+ listing ??= list().then((answer) => {
190
+ listing = null;
191
+ if (answer?.ok !== true) say(`listing failed ${failed(answer)}`);
192
+ });
193
+ arm();
194
+ };
195
+ if (!signal) arm();
196
+ await stopRequested;
197
+
198
+ // Ticking has ended. A tick that runs is waited for: its wake job may start a home.
199
+ say(`${signal}: ticking ended`);
200
+ await Promise.all([ticking, listing]);
201
+ const last = await list();
202
+ if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
203
+ const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => row.outcome === OUTCOME.ALREADY_RUNNING && typeof row.home === "string").map((row) => row.home) : [];
204
+ if (homes.length) say(`stopping ${plural(homes.length, "running instance")}, each given ${stopGraceMs / 1000} s`);
205
+ // Side by side: each stop waits for its own harness, and the host's patience is one span for all.
206
+ const stopped = await Promise.all(homes.map(async (home) => {
207
+ const row = await stopHome(home, stopGraceMs);
208
+ say(row.ok ? (row.stopped ? `stopped ${home}` : `${home} was already idle`) : `could not stop ${home} (${row.code}): ${row.message}`);
209
+ return row;
210
+ }));
211
+ say("ended");
212
+ return { schemaVersion: HOST_RUN_SCHEMA, plan: false, signal, warnings, sweep, ticks, stopped };
213
+ } finally {
214
+ disarm?.();
215
+ stopListening();
216
+ release();
217
+ }
218
+ }
@@ -0,0 +1,21 @@
1
+ /** Private entry point of lib/host-run.mjs; no CLI or provider contract. One process per running
2
+ * home when the host stops: `node host-stop-child.mjs <home> <grace ms>` stops that home's session
3
+ * with the host (lib/core.mjs stopInstanceSession, `withHost`: its record asks for a resume and is
4
+ * written before the harness is signalled) and prints one JSON line:
5
+ * { ok: true, home, stopped, alreadyIdle, state }
6
+ * { ok: false, home, code, message, stillRunning }
7
+ * A stop waits synchronously for its harness, so each home has a process of its own and the homes
8
+ * stop side by side. It exits 0 whatever the stop answered: the answer is the line. */
9
+ import { stillRunningOf, stopInstanceSession } from "./core.mjs";
10
+ import { kernelCode, reportDefect } from "./errors.mjs";
11
+
12
+ const [home, grace] = process.argv.slice(2);
13
+ let answer;
14
+ try {
15
+ const { stopped, alreadyIdle, state } = stopInstanceSession(home, { graceMs: Number(grace), withHost: true });
16
+ answer = { ok: true, home, stopped, alreadyIdle, state };
17
+ } catch (e) {
18
+ reportDefect(e); // the error becomes a row here: its stack would otherwise be lost
19
+ answer = { ok: false, home, code: kernelCode(e, "E_SESSION_STOP_FAILED"), message: String(e?.message ?? e), stillRunning: stillRunningOf(e) };
20
+ }
21
+ process.stdout.write(`${JSON.stringify(answer)}\n`);
@@ -56,8 +56,11 @@ export const INSTANCE_GIT_API = 1;
56
56
  * worktreeCommitUnreached: `symbolic-ref`, `rev-parse`, `for-each-ref`), and
57
57
  * this module's own READS_NO_WORK_TREE_FILE commands. A command another
58
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"];
59
62
  const READ_ONLY_GIT = ["--no-optional-locks",
60
- "-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",
61
64
  "-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
62
65
  /** The subcommands this module runs (git) that read refs, objects, the index or the configuration,
63
66
  * and no file of the work tree: no filter can run in them. */
@@ -96,28 +99,51 @@ export function filterDriverKeys(listing) {
96
99
  * a name that configuration defines too is then overridden with the operator's own values, not
97
100
  * with none: the operator's command runs, as it does for that name everywhere else the operator's
98
101
  * Git runs (a retire's recovery copy has no configuration of its own), and the repository's never
99
- * does. The operator's configuration is the human's; the repository's is the agent's to write. A
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
100
106
  * configuration of the operator's that cannot be read defines nothing.
101
107
  * The one reader of a repository's filter drivers: this module's commands, a retire's
102
- * (lib/core.mjs retireGitArgv) and a worktree removal's (lib/worktree.mjs) take their overrides here. */
108
+ * (lib/core.mjs retireGitArgv), and a checkout's and a worktree removal's (workTreeOverrides)
109
+ * take their overrides here. */
103
110
  export function filterOverrides(where, { operatorEnv } = {}) {
104
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() });
105
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}` };
106
- const names = new Set(filterDriverKeys(r.stdout).map((key) => key.name));
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));
107
115
  const operator = names.size > 0 && operatorEnv ? operatorDrivers(operatorEnv) : new Map();
108
116
  const args = [];
109
- for (const raw of names) {
117
+ for (const [raw, variables] of names) {
110
118
  const bytes = Buffer.from(raw, "latin1");
111
119
  const name = bytes.toString("utf8");
112
120
  if (name.includes("=") || !Buffer.from(name, "utf8").equals(bytes)) {
113
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" };
114
122
  }
115
123
  const own = operator.get(raw) ?? {};
116
- for (const command of ["clean", "smudge", "process"]) args.push("-c", `filter.${name}.${command}=${own[command] ?? ""}`);
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
+ }
117
131
  args.push("-c", `filter.${name}.required=${own.required ?? "false"}`);
118
132
  }
119
133
  return { ok: true, count: names.size, args };
120
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
+ }
121
147
  /** The filter drivers the operator's own configuration defines, as the Git that runs with `env`
122
148
  * reads it: the system configuration, then the global one (`~/.gitconfig`,
123
149
  * `$XDG_CONFIG_HOME/git/config`, or `$GIT_CONFIG_GLOBAL`), whose value wins as it does for Git
@@ -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
 
@@ -407,7 +407,7 @@ function readRetireFacts(home) {
407
407
  if (existsSync(quarantine)) {
408
408
  try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
409
409
  catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
410
- // #796: a spawn still running its worktree hooks keeps a marker that names it
410
+ // #796: a spawn still running its spawn or worktree hooks keeps a marker that names it
411
411
  // (`inProgress`). While that process is verifiably alive the home is a spawn in
412
412
  // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
413
413
  // start cannot be read is not shown in progress either: on a host that never reads it, the
@@ -708,6 +708,35 @@ function readRetirePending(home) {
708
708
  catch { return { retirePending: { reason: "retire pending" }, marker: { read: undefined } }; }
709
709
  }
710
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
+
711
740
  /** A status row's `retire` (feature status-retire-state, lib/retire-state.mjs): whether a retire of
712
741
  * `home` runs, could not be told, failed or was interrupted, read from what is beside the home
713
742
  * (`marker`: `{ read }` when its retire marker is there, `read` what its file parsed as, undefined
@@ -717,9 +746,9 @@ function readRetirePending(home) {
717
746
  * - The marker of a self-retire comes first, whatever the claim says (its completion holds the
718
747
  * claim for its own retire), and gives `self: true`. A completion's result that says `ok:
719
748
  * false` is `failed`, with its time, code and message. Otherwise, a result that says anything
720
- * else included, the marker's completion decides: `running` while it lives (pid and recorded
721
- * start), `interrupted` once it is gone, and `unknown` when that cannot be read or the marker
722
- * 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`.
723
752
  * - Without a marker, the home's claim held for a retire is `running` while its holder lives and
724
753
  * `unknown` when that cannot be read, with `self: false`. A holder that is gone, a stop's claim
725
754
  * or no claim gives no value.
@@ -749,7 +778,7 @@ function retireStateOf(home, marker) {
749
778
  }
750
779
  const pid = pending.completionPid;
751
780
  const state = !Number.isSafeInteger(pid) || pid <= 0 ? "unknown"
752
- : { alive: "running", gone: "interrupted" }[processLiveness({ pid, processStart: pending.completionStart }).state] ?? "unknown";
781
+ : { alive: "running", gone: "interrupted" }[completionLiveness(pending).state] ?? "unknown";
753
782
  return readRetireState({ state, self: true, since: instantOr(pending.requestedAt) ?? markerTime() });
754
783
  }
755
784
  // Most rows have no claim: asked without the throw of a read that finds none, which is most of
@@ -5,6 +5,9 @@
5
5
  * (test/cli-json-contract.test.mjs). Kernel-private, not exported from `./core`. Dependency-free. */
6
6
  import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
7
7
 
8
- export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only"]);
8
+ /** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
9
+ * its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
10
+ export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
11
+ export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
9
12
  /** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
10
13
  export const READER_API = 1;
package/lib/read-call.mjs CHANGED
@@ -45,7 +45,7 @@ export const READ_STATE = [
45
45
  { module: "lib/dir-lock.mjs", binding: "sections", how: "safe", why: "how many locked sections run now: a section is synchronous, so it is 0 between calls" },
46
46
  { module: "lib/dir-lock.mjs", binding: "listening", how: "safe", why: "whether the lock's signal listeners are on: they hold a signal back around a section and decide no answer" },
47
47
  { module: "lib/dir-lock.mjs", binding: "idle", how: "safe", why: "the pending removal of those listeners, run once the event loop turns" },
48
- { module: "lib/session-seen.mjs", binding: "processBoot", how: "safe", why: "the boot id: a process never outlives its boot" },
48
+ { module: "packages/record/lib/process-identity.mjs", binding: "processBoot", how: "safe", why: "the boot id: a process never outlives its boot" },
49
49
  { module: "lib/session-viewer.mjs", binding: "probed", how: "safe", why: "only an attach's preparation reads it; readSessionViewer asks tmux -V at every call" },
50
50
  { module: "lib/session-viewer.mjs", binding: "onQuit", how: "safe", why: "only an attach (attachSessionTarget) sets it" },
51
51
  { module: "lib/session-viewer.mjs", binding: "quitHeld", how: "safe", why: "only an attach (attachSessionTarget) sets it" },
package/lib/remote.mjs CHANGED
@@ -183,11 +183,10 @@ import {
183
183
  import { homedir } from "node:os";
184
184
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
185
185
  import { fileURLToPath } from "node:url";
186
- import { holderLiveness } from "./claim.mjs";
187
186
  import { oatsError } from "./errors.mjs";
188
187
  import { REFUSED_TEXT } from "./refused-text.mjs";
189
188
  import { killGroup, signalGroup, terminateGroup, watchGroup } from "./process-group.mjs";
190
- import { takenInAnotherBoot, thisBoot } from "./session-seen.mjs";
189
+ import { identityHolderState, thisBoot, validPid } from "./session-seen.mjs";
191
190
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
192
191
  import { processStartToken } from "./worktree-hooks.mjs";
193
192
 
@@ -655,8 +654,6 @@ const UNREADABLE_LOCK_STALE_MS = 30_000;
655
654
  * longest fetch any oats allows, so an older kernel's live fetch (it takes no write lock) is never broken. */
656
655
  const GIT_LOCK_STALE_MS = GIT_FETCH_TIMEOUT_MS + 60_000;
657
656
 
658
- function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } }
659
-
660
657
  /** The write lock of the cache repo `dir`: `<cacheRoot>/.locks/<repo>.lock`, outside git's own namespace. */
661
658
  const cacheWriteLockOf = (dir) => join(dirname(dir), ".locks", `${basename(dir)}.lock`);
662
659
 
@@ -682,7 +679,10 @@ function readCacheWriteLock(path) {
682
679
  * boot and start, as a claim's is (lib/claim.mjs). A live holder is waited for, never stolen from, whatever
683
680
  * its age; a gone holder's lock (isStaleLock: one taken in another boot, or whose pid is gone or runs with
684
681
  * another start; or an unreadable one past UNREADABLE_LOCK_STALE_MS) is removed after checking it is still the
685
- * same file. A record that names no boot or start is its holder's by pid alone. Every pass that does not
682
+ * same file. A record that names no boot or start is its holder's by pid alone. An owner whose liveness
683
+ * cannot be judged (identityHolderState "unknown": a pid or a start that cannot be read, a pid that is no
684
+ * process ID) is waited for like a live one, never reclaimed; the refusal for a pid that is no process ID
685
+ * says so, with no holderPid. Every pass that does not
686
686
  * acquire falls through one deadline check and one sleep. At the deadline: E_REMOTE_UNREADABLE { reason: "cache", stage, cacheDir, lock, holderPid }; at once
687
687
  * when a reclaimer died holding the reclaim guard (reclaimCacheWriteLock), with details.guard.
688
688
  * `fn({ waited })`: whether another process held the lock first (what it wrote is worth checking again).
@@ -702,9 +702,10 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
702
702
  const budgetEnded = () => {
703
703
  let now = held;
704
704
  try { now = readCacheWriteLock(lock); } catch { /* as last seen */ }
705
- const holder = now?.owner ? `oats process ${now.owner.pid}` : "another process";
705
+ const pid = now?.owner && validPid(now.owner.pid) ? now.owner.pid : null;
706
+ const holder = pid ? `oats process ${pid}` : "another process";
706
707
  return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (timeout, ${stage}): the read budget ended ${now ? `while ${holder} held its write lock ${lock}` : `before it took its write lock ${lock}`}`,
707
- { url: ref.url, key: ref.key, reason: "timeout", stage, cacheDir: dir, lock, ...(now?.owner ? { holderPid: now.owner.pid } : {}) });
708
+ { url: ref.url, key: ref.key, reason: "timeout", stage, cacheDir: dir, lock, ...(pid ? { holderPid: pid } : {}) });
708
709
  };
709
710
  for (let attempt = 0; ; attempt++) {
710
711
  if (signal?.aborted) throw unreadable(ref, abortError(signal), { cacheDir: dir, stage });
@@ -724,6 +725,8 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
724
725
  }
725
726
  }
726
727
  if (Date.now() >= deadline) {
728
+ // A record whose pid is no process ID names no process to check: the refusal says what it names.
729
+ if (held?.owner && !validPid(held.owner.pid)) throw refuse(`its write lock ${lock} names ${held.owner.pid}, which is no process ID, as its holder; it is safe to remove once no oats process is running`);
727
730
  throw refuse(held?.owner ? `process ${held.owner.pid} has been writing it since ${held.owner.startedAt} (lock ${lock}); try again once it finishes; check whether pid ${held.owner.pid} is an oats process: once no oats process holds it, the lock ${lock} is safe to remove`
728
731
  : `its write lock ${lock} is held; it is safe to remove once no oats process is running`, held?.owner ? { holderPid: held.owner.pid } : {});
729
732
  }
@@ -742,13 +745,13 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
742
745
  /** Whether a lock record (readCacheWriteLock) is provably abandoned: its owner is gone (ownerGone), or it has
743
746
  * no readable owner and is older than UNREADABLE_LOCK_STALE_MS. A live owner is never stale, whatever its age. */
744
747
  const isStaleLock = (held) => (held.owner ? ownerGone(held.owner) : Date.now() - held.mtimeMs > UNREADABLE_LOCK_STALE_MS);
745
- /** Whether the owner a lock record names is gone. One that names its boot or start (`bootId`, `processStart`)
746
- * is judged as a claim's holder is (lib/claim.mjs holderLiveness): gone when taken in another boot, or when
747
- * its pid is gone, runs with another start or is a zombie; one whose start cannot be read is never gone. One
748
- * that names neither is gone when its pid is. */
749
- const ownerGone = (owner) => ("bootId" in owner || "processStart" in owner
750
- ? holderLiveness(owner, { holderGone: takenInAnotherBoot(thisBoot()) }).state === "gone"
751
- : !pidAlive(owner.pid));
748
+ /** Whether the owner a lock record names is gone, as identityHolderState says it
749
+ * (packages/record/lib/process-identity.mjs, where the rule is composed). One that names its boot or start
750
+ * (`bootId`, `processStart`) is gone when taken in another boot, or when its pid is gone, runs with another
751
+ * start or is a zombie. One that names neither is gone when its pid is. An owner whose liveness cannot be
752
+ * judged (a start or a pid that cannot be read, a pid that is no process ID) is never gone: its lock is
753
+ * waited for and refused, as a live holder's is. */
754
+ const ownerGone = (owner) => identityHolderState(owner) === "gone";
752
755
  /** The same record still at `path`: the same owner token, or (no readable owner) the same file. */
753
756
  const sameLock = (now, held) => (held.owner ? now?.owner?.token === held.owner.token : now && !now.owner && now.ino === held.ino && now.mtimeMs === held.mtimeMs);
754
757