@awebai/oats 0.69.18 → 0.69.20

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 (52) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +27 -14
  3. package/docs/container.md +416 -43
  4. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  5. package/docs/design/2026-09-28-automations-trust.md +1 -1
  6. package/docs/desktop-cli-api.md +52 -31
  7. package/docs/desktop.md +29 -6
  8. package/docs/execution-targets.md +32 -17
  9. package/docs/implementation.md +4 -3
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +6 -4
  15. package/docs/release-notes/v0.69.19.md +172 -0
  16. package/docs/release-notes/v0.69.20.md +325 -0
  17. package/docs/servers.md +6 -4
  18. package/docs/souls-and-instances.md +37 -13
  19. package/docs/tui.md +8 -8
  20. package/docs/upgrading.md +17 -5
  21. package/docs/workspaces.md +13 -7
  22. package/injects/work-directory.md +27 -2
  23. package/injects/work-workspace.md +32 -6
  24. package/lib/core.mjs +33 -197
  25. package/lib/hook-outcome.mjs +6 -0
  26. package/lib/host-run.mjs +24 -19
  27. package/lib/instance-lifecycle.mjs +3 -1
  28. package/lib/instance-listing.mjs +3 -2
  29. package/lib/launch-prompt-fixtures/README.md +6 -0
  30. package/lib/retire-admission.mjs +215 -0
  31. package/lib/servers.mjs +3 -0
  32. package/lib/session-resume-contract.mjs +1 -1
  33. package/lib/session-resume.mjs +130 -47
  34. package/lib/session-seen.mjs +3 -3
  35. package/package-catalog.json +3 -3
  36. package/package.json +3 -1
  37. package/packages/client/attributed-human.mjs +13 -0
  38. package/packages/client/deployment-data.mjs +4 -0
  39. package/packages/client/deployment-panel.mjs +2 -0
  40. package/packages/client/instance-lifecycle.mjs +6 -4
  41. package/packages/client/instance-presentation.mjs +2 -2
  42. package/packages/client/instance-tree.mjs +18 -7
  43. package/packages/client/lifecycle-confirmation.mjs +4 -2
  44. package/packages/client/lifecycle-contract.mjs +11 -6
  45. package/packages/client/remote-roster.mjs +4 -0
  46. package/packages/record/README.md +15 -2
  47. package/packages/record/docs/capture-service.md +14 -0
  48. package/packages/record/lib/canonical.mjs +2 -70
  49. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  50. package/packages/record/lib/capture-aw.mjs +11 -5
  51. package/packages/record/lib/capture-health.mjs +16 -5
  52. package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/host-run.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  /** `oats host run` (oats-project/oats#1789): the kernel's periodic work in one foreground process,
2
2
  * for a host where no timer can run it (a container, a machine without launchd or a systemd user
3
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
4
+ * without it nothing there runs the resume sweep or the schedule tick each minute, and
5
5
  * nothing stops the agents in order when the host stops.
6
6
  *
7
7
  * - Refused before any effect: inside an instance session (OATS_INSTANCE_HOME set), E_USAGE; while
@@ -13,12 +13,12 @@
13
13
  * holder by pid, process start and boot id. A lock whose holder is gone, or that was taken in
14
14
  * another kernel boot, is taken over at once; a holder that runs, and a
15
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
16
+ * - A run, in order: the lock; the resume sweep (`oats session resume`); then, at second 0 of
17
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).
18
+ * none it ticks nothing and says so), and the resume sweep again, which starts a home lost
19
+ * while this runs and records what runs for a later sweep. Each is an `oats` child, so this
20
+ * process's loop stays free for the signal. A minute whose tick still runs is skipped; a minute
21
+ * missed is never replayed (the host timer's own rule).
22
22
  * - SIGTERM or SIGINT stops it (hostRun): ticking first, then every running home, so that the
23
23
  * next start resumes them; then it answers and exits 0.
24
24
  * - `plan` says what a run would refuse, the scopes it would tick (the host schedule registry) and
@@ -99,7 +99,7 @@ function sweepSaid(rows) {
99
99
  }
100
100
 
101
101
  /** `oats host run`: refuses (above), then runs until SIGTERM or SIGINT →
102
- * `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the resume
102
+ * `{ schemaVersion, plan: false, signal, warnings, sweep, ticks, stopped }`: `sweep` the first resume
103
103
  * sweep's answer, or `{ error: { code, message } }`; `ticks` the minutes counted (`run`,
104
104
  * `skipped` while the tick before still ran, `failed`, `noScope` with no scope registered);
105
105
  * `stopped` one row per home that ran when it stopped, in the listing's order (stopHome).
@@ -159,15 +159,23 @@ export async function hostRun({
159
159
  say(`started (pid ${process.pid}); it holds ${hostRunLockPath()}`);
160
160
  for (const warning of warnings) say(`warning: ${warning}`);
161
161
 
162
- // The sweep, once: a home lost while this runs is a crash, and the sweep's bound is per boot.
163
- const swept = await execute(["session", "resume", "--json"]);
162
+ // The sweep, at the start and then each minute: a home lost while this runs is started again
163
+ // within the sweep's own bounds (lib/session-resume.mjs: its starts per hour, its retries).
164
+ // Each sweep is said when its outcomes differ from those of the sweep before.
165
+ let saidOfSweep;
166
+ const resume = async () => {
167
+ const swept = await execute(["session", "resume", "--json"]);
168
+ const said = swept?.ok === true ? `resume sweep: ${sweepSaid(swept.result?.rows ?? [])}` : `resume sweep failed ${failed(swept)}`;
169
+ if (said !== saidOfSweep) say(saidOfSweep = said);
170
+ return swept;
171
+ };
172
+ const swept = await resume();
164
173
  const sweep = swept?.ok === true ? swept.result : { error: { code: swept?.error?.code ?? "E_HOST_RUN_FAILED", message: swept?.error?.message ?? "no answer" } };
165
- say(swept?.ok === true ? `resume sweep: ${sweepSaid(sweep.rows ?? [])}` : `resume sweep failed ${failed(swept)}`);
166
174
 
167
175
  // The minutes. Each is armed from the clock as it reads then, for second 0 of the next one: a
168
176
  // minute missed while this process did not run is never armed again.
169
177
  const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
170
- let ticking = null, listing = null, ticked;
178
+ let ticking = null, sweeping = null, ticked;
171
179
  const list = (options) => execute(["session", "resume", "--plan", "--json"], options);
172
180
  const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
173
181
  const minute = () => {
@@ -189,13 +197,10 @@ export async function hostRun({
189
197
  if (answer?.ok !== true) { ticks.failed += 1; say(`tick failed ${failed(answer)}`); }
190
198
  });
191
199
  }
192
- // The listing each minute writes what the sweep of the next start needs: that each running
193
- // home was seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
194
- // deployment, which its plan does and nothing else).
195
- listing ??= list().then((answer) => {
196
- listing = null;
197
- if (answer?.ok !== true) say(`listing failed ${failed(answer)}`);
198
- });
200
+ // The sweep each minute also writes what a later sweep needs: that each running home was
201
+ // seen running (lib/session-seen.mjs recordSeen, by the sweep's own read of every
202
+ // deployment). One that still runs at the next minute is not run beside itself.
203
+ sweeping ??= resume().then(() => { sweeping = null; });
199
204
  arm();
200
205
  };
201
206
  if (!signal) arm();
@@ -205,7 +210,7 @@ export async function hostRun({
205
210
  // when it arrived during the initial sweep. No launch may race agent stops.
206
211
  say(`${signal}: ticking ended`);
207
212
  await draining;
208
- await Promise.all([ticking, listing]);
213
+ await Promise.all([ticking, sweeping]);
209
214
  const last = await list({ timeoutMs: 3000 });
210
215
  if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
211
216
  const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => row.outcome === OUTCOME.ALREADY_RUNNING && typeof row.home === "string").map((row) => row.home) : [];
@@ -7,6 +7,7 @@
7
7
  * plan instead of acting on a world the human did not see. Idempotency keys
8
8
  * make a retried apply return the first receipt rather than act twice.
9
9
  * Unknown is reported as unknown — never as "clean" or "no children". */
10
+ import { retireCleanupAdmission } from "./retire-admission.mjs";
10
11
  import { createHash } from "node:crypto";
11
12
  import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
12
13
  import { join } from "node:path";
@@ -478,8 +479,9 @@ const PLAN_NOT_COPIED_CAP = 16;
478
479
  * itself applies them: plain retire re-homes the worktree; --discard-worktree
479
480
  * is the dialog's opt-in. No retire deletes a branch: `deleteBranch` is
480
481
  * always false. */
481
- export function planRetire(ctx, root, name, { home } = {}) {
482
+ export function planRetire(ctx, root, name, { home, force = false } = {}) {
482
483
  const me = resolveTarget(ctx, root, name, { home });
484
+ retireCleanupAdmission(me.home, name, { force }, instanceWork);
483
485
  const kids = descendantsOf(me.root, name);
484
486
  // Read once, after the lineage: every fact of the plan that the record gives is of this read.
485
487
  const recorded = targetRecord(me.home);
@@ -53,7 +53,8 @@ export function legacyLocalAgents(root) {
53
53
 
54
54
  /** The captured homes (the 0.24–0.25 captured/portable path, removed in 0.26) under the
55
55
  * agents root `root`: one `legacy-captured-home` problem naming them, or null. They have
56
- * no 0.26 runtime (start, inspect and in-home commands refuse them); retire still works.
56
+ * no 0.26 runtime (start, inspect and in-home commands refuse them); captured homes
57
+ * without positive cleanup proof need manual cleanup and forced retirement.
57
58
  * `records`: the records listInstances read in this same read (its `records`), each home's
58
59
  * instance.json parsed once per read; a home it holds no record for is read here. */
59
60
  export function legacyCapturedHomes(root, { records } = {}) {
@@ -70,7 +71,7 @@ export function legacyCapturedHomes(root, { records } = {}) {
70
71
  homes.sort((a, b) => a.instance.localeCompare(b.instance));
71
72
  const one = homes.length === 1;
72
73
  return { code: "legacy-captured-home", instances: homes.map((h) => h.instance), homes: homes.map((h) => h.home),
73
- message: `${homes.length} captured home${one ? "" : "s"} (0.24–0.25; the captured/portable path was removed in 0.26) ${one ? "has" : "have"} no 0.26 runtime: start, inspect and in-home commands refuse ${one ? "it" : "them"}; retire ${one ? "it" : "them"} (\`oats retire\` still works) and re-spawn from the deployment (${homes.map((h) => h.instance).join(", ")})` };
74
+ message: `${homes.length} captured home${one ? "" : "s"} (0.24–0.25; the captured/portable path was removed in 0.26) ${one ? "has" : "have"} no 0.26 runtime: start, inspect and in-home commands refuse ${one ? "it" : "them"}; inspect and clean up external state; a captured home without proof that no spawn hook ran needs \`oats retire <instance> --force\`; then re-spawn from the deployment (${homes.map((h) => h.instance).join(", ")})` };
74
75
  }
75
76
  // The tmux session a new tmux instance opens its window in, when oats-local.yaml session.tmuxSession
76
77
  // names none (0.31). PI_AGENTS_TMUX_SESSION is the pre-0.31 variable, still honoured. The Desktop keeps
@@ -7,6 +7,12 @@ Enter only while the normalized screen EQUALS one `confirmation` entry's `text`.
7
7
  It also holds the notice Claude shows when it ignores the development-channel
8
8
  flag (`flag-ignored` entries), which ends a start with no key.
9
9
 
10
+ The engagement tests take the channel arguments from the pinned `oats.aweb`
11
+ mirror's `CLAUDE_CHANNEL_ARGUMENTS`. They check that the kernel engages for the
12
+ provider's development argument and stays disengaged for its approved argument,
13
+ so a provider argument change cannot silently bypass confirmation. The kernel
14
+ does not import the provider at runtime.
15
+
10
16
  ## Normalization, and only this
11
17
 
12
18
  1. Split the captured screen into rows.
@@ -0,0 +1,215 @@
1
+ // Internal lifecycle admission shared by Remove plans and retire apply.
2
+ // The record and cleanup readers live here; core re-exports only its existing API.
3
+ import { existsSync, readFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+ import { directoryRollbackPath, isCapturedHome, readHomeRecord, unreadableRecordSaid } from "./instance-listing.mjs";
6
+ import { isPlainObject } from "./session-inspect.mjs";
7
+ import { processLiveness } from "./worktree-hooks.mjs";
8
+ import { lifecycleBusy, oatsError } from "./errors.mjs";
9
+
10
+ /** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
11
+ * must satisfy, so the retry cannot skip Git cleanup on an unrecognised value. */
12
+ export const WORK_MODES = ["worktree", "checkout", "attached", "workspace", "directory"];
13
+ /** The quarantine cleanup-descriptor contract version. Bump when the shape the
14
+ * retry consumes changes, so an older/newer marker fails closed instead of
15
+ * driving a retry that cannot do what it claims.
16
+ *
17
+ * The rule applies from the first RELEASE of this shape onward. Markers are only
18
+ * ever written when a `required` spawn hook fails, and required hooks do not
19
+ * exist in any released kernel — so no deployment can hold a marker of an earlier
20
+ * v1 shape, and there is nothing to migrate from. A migration path for a file
21
+ * that has never existed would be dead code claiming to protect real data. */
22
+ export const QUARANTINE_CLEANUP_VERSION = 1;
23
+ /** The rollback-owned Git steps a quarantine can still owe. */
24
+ export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
25
+
26
+
27
+ /** The refusal of a lifecycle verb (retire, stop, session start) for a home whose record is there
28
+ * and cannot be read: E_UNIDENTIFIED_INSTANCE_HOME, with the file, the reason, `nothing` (what the
29
+ * verb had done by then: nothing; a spawn that names the home says "nothing was spawned") and the
30
+ * one remedy that exists. Every caller raises it before any effect: a client reads this code from
31
+ * a stop or a retire as "refused, nothing happened". `--force` does not apply to it: it removes a
32
+ * home that has NO record, never, blind, one whose record cannot be read. */
33
+ function unreadableRecordRefusal(record, nothing = "nothing was done") {
34
+ return oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${unreadableRecordSaid(record)}; ${nothing}. Restoring the file from a copy makes the home usable again; removing such a home through OATS is not possible yet.`);
35
+ }
36
+ /** The one check a lifecycle verb makes when it has resolved its home, before it takes a claim or
37
+ * reads anything of the home: a record that cannot be read refuses the verb (unreadableRecordRefusal).
38
+ * → the record as read (readHomeRecord), a record or an absent one. */
39
+ export function identifiedHomeRecord(home, nothing) {
40
+ const record = readHomeRecord(home);
41
+ if (record.state === "unreadable") throw unreadableRecordRefusal(record, nothing);
42
+ return record;
43
+ }
44
+ export function nonEmptyString(v) { return typeof v === "string" && !!v.trim(); }
45
+ export function usableCleanupDescriptor(marker) {
46
+ const c = marker?.cleanup;
47
+ if (!isPlainObject(c)) return false;
48
+ if (c.version !== QUARANTINE_CLEANUP_VERSION) return false;
49
+ if (!nonEmptyString(c.repo)) return false;
50
+ if (!WORK_MODES.includes(c.work)) return false;
51
+ if (c.work === "worktree" && !nonEmptyString(c.branch)) return false;
52
+ if (c.branch !== undefined && !nonEmptyString(c.branch)) return false;
53
+ if (c.capabilityMeta !== undefined && !isPlainObject(c.capabilityMeta)) return false;
54
+ const directoryDebt = c.outstanding?.directory === true && c.work === "directory";
55
+ if (c.outstanding?.directory !== undefined && !directoryDebt) return false;
56
+ // A worktree directory whose git admin entry is gone (awebai/oats#444) is debt too: the retry proves it
57
+ // cleared when the directory is no longer there or has its admin entry back.
58
+ const orphanDebt = c.outstanding?.orphanedWork === true && c.work === "worktree";
59
+ if (c.outstanding?.orphanedWork !== undefined && !orphanDebt) return false;
60
+ if (!Array.isArray(c.capabilityRuntime) || (!c.capabilityRuntime.length && !directoryDebt && !orphanDebt)) return false;
61
+ if (!c.capabilityRuntime.every((cap) => isPlainObject(cap) && nonEmptyString(cap.id))) return false;
62
+ if (!isPlainObject(c.outstanding) || !Array.isArray(c.outstanding.hooks) || !Array.isArray(c.outstanding.git)) return false;
63
+ if (!c.outstanding.hooks.every(nonEmptyString)) return false;
64
+ if (!c.outstanding.git.every((g) => QUARANTINE_GIT_DEBT.includes(g))) return false;
65
+ // Git debt only exists where the rollback owns Git steps, so claiming it in any
66
+ // other work mode describes a quarantine that could not have happened.
67
+ if (c.outstanding.git.length && c.work !== "worktree") return false;
68
+ // The decisive invariant: a quarantine with NOTHING outstanding is a proof
69
+ // obligation of zero. Directory preservation is also real debt: the retry's
70
+ // independent-authority inspection and verified snapshots must succeed even
71
+ // when no capability has a retire hook. It is never a Git/shared-work escape.
72
+ if (!c.outstanding.hooks.length && !c.outstanding.git.length && !directoryDebt && !orphanDebt) return false;
73
+ // The retry must be ABLE to rerun what it must prove: an outstanding hook whose
74
+ // capability is not in the set could never run, so the quarantine would never
75
+ // clear — and the home would be unremovable without --force.
76
+ const known = new Set(c.capabilityRuntime.map((cap) => cap.id));
77
+ if (!c.outstanding.hooks.every((id) => known.has(id))) return false;
78
+ return true;
79
+ }
80
+
81
+ /** The capabilities whose spawn hooks ran in a captured home (its identities, memberships):
82
+ * retire cannot run their captured retire hooks, so it names them. */
83
+ export function capturedHomeCapabilities(meta) {
84
+ const order = Array.isArray(meta?.captured?.hookOrder) ? meta.captured.hookOrder.filter((id) => typeof id === "string") : [];
85
+ const withMeta = meta?.capabilityMeta && typeof meta.capabilityMeta === "object" ? Object.keys(meta.capabilityMeta) : [];
86
+ const intents = isPlainObject(meta?.captured?.hookIntents) ? Object.keys(meta.captured.hookIntents) : [];
87
+ const failures = Array.isArray(meta?.captured?.hookFailures) ? meta.captured.hookFailures.map(failure => failure?.capability).filter(nonEmptyString) : [];
88
+ return [...new Set([...order, ...withMeta, ...intents, ...failures])].sort();
89
+ }
90
+ /** Read and admit the recorded cleanup before any lifecycle effect. Shared by
91
+ * Remove plans and every retire apply, including deferred self retirement.
92
+ * No current deployment configuration can prove an old home created no state.
93
+ * `readWork` is core's actual instanceWork reader, passed by both callers to
94
+ * keep the leaf independent of core while preserving its Git repo resolution. */
95
+ export function retireCleanupAdmission(home, name, { force = false } = {}, readWork) {
96
+ if (typeof readWork !== "function") throw new TypeError("retireCleanupAdmission requires the instanceWork reader");
97
+ const metaPath = join(home, "instance.json");
98
+ const directoryFallbackPath = directoryRollbackPath(home);
99
+ const quarantinePath = existsSync(directoryFallbackPath) ? directoryFallbackPath : join(home, ".oats-rollback-incomplete.json");
100
+ let quarantine;
101
+ let markerUnusable = false;
102
+ let rawMarker;
103
+ // A marker means the home is quarantined, WHETHER OR NOT instance.json exists:
104
+ // the post-launch rollback retains a home that already has one, and gating on
105
+ // its absence meant that quarantine was silently ignored — retire took the
106
+ // ordinary path, where hook failures do not retain, and deleted the credential
107
+ // while the external state survived (reviewer-final0130bc8).
108
+ if (existsSync(quarantinePath)) {
109
+ // A marker without a USABLE cleanup descriptor is NOT a quarantine we can
110
+ // retry — it is an unidentified home. Treating an unusable one as retryable
111
+ // made --force unable to ever clear it: the retry could not run, so the home
112
+ // was retained again, forever (reviewer-adff009). "Parses as JSON" is not
113
+ // the bar; "can actually drive the retry" is, so the shape is checked
114
+ // against what the retry below consumes (reviewer-45ff039r2).
115
+ try {
116
+ const parsed = JSON.parse(readFileSync(quarantinePath, "utf8"));
117
+ rawMarker = parsed;
118
+ if (isPlainObject(parsed) && usableCleanupDescriptor(parsed)) quarantine = parsed;
119
+ else markerUnusable = true;
120
+ } catch { markerUnusable = true; }
121
+ }
122
+ // #796: a marker a spawn wrote before its spawn or worktree hooks (`inProgress`). While that spawn's
123
+ // process is verifiably alive it is a spawn in progress, never a quarantine to retry, --force
124
+ // included. Once it is gone, the hook group it left is ended when its leader is alive at the
125
+ // recorded start time; a group whose leader is gone is never signalled, only reported (its id may
126
+ // be another group's by now). The retry below completes the rollback from the marker like any other.
127
+ // Whether that process still runs may also be unreadable (no procfs and `ps` failing): that is never
128
+ // taken for gone. Retire refuses it, naming the recorded pid and start for a check by hand, and the
129
+ // existing forced path (`--force`) is the way out; a forced retry then keeps the spawn's branch.
130
+ // The same holds for a hook group with members whose leader's start cannot be read.
131
+ const spawnGroupWarnings = [];
132
+ let inProgressUnverified = false;
133
+ if (isPlainObject(rawMarker?.inProgress)) {
134
+ const p = rawMarker.inProgress;
135
+ const live = processLiveness(p);
136
+ if (live.state === "alive") throw lifecycleBusy("running", `${name} is still being spawned (pid ${p.pid}, running its hooks since ${p.startedAt ?? "?"}); nothing was retired`, "wait for the spawn to end, or stop that process, then retire");
137
+ if (live.state === "unknown") {
138
+ if (!force) throw lifecycleBusy("unknown", `${name}: whether its spawn (pid ${p.pid}, recorded start ${p.processStart ?? "none"}, running its hooks since ${p.startedAt ?? "?"}) still runs cannot be read (${live.reason}); nothing was retired`,
139
+ `check that pid by hand, and if it is not that spawn, run \`oats retire ${name} --force\``, { pid: p.pid, processStart: p.processStart ?? null, unknown: live.reason, remedy: `oats retire ${name} --force` });
140
+ inProgressUnverified = true;
141
+ spawnGroupWarnings.push(`retired with --force although whether its spawn (pid ${p.pid}) still runs could not be read (${live.reason}); its branch is kept`);
142
+ }
143
+ }
144
+ // The retire's own read of the record, with the same reader as the resolution: one that became
145
+ // unreadable since then refuses as there. It comes before retireSteps' first signal,
146
+ // so E_UNIDENTIFIED_INSTANCE_HOME for an unreadable record is only ever answered
147
+ // while nothing was done: `reached` is untouched ("before-effects").
148
+ const liveMeta = identifiedHomeRecord(home).meta;
149
+ // A quarantined home may carry an instance.json that is NOT the spawn record:
150
+ // module materialization writes a pre-hook stub ({ modules, providers,
151
+ // resolutionRevision }) before the spawn hooks run, and a required-hook
152
+ // failure retains the home with that stub in place. Trusting it over the
153
+ // cleanup descriptor left meta.repo undefined, so the retry never re-ran the
154
+ // owed retire hook and reported "cleanup descriptor lost its context repo"
155
+ // on every attempt — only --force could clear the home (found by an operator
156
+ // rehearsal on 0.25.3). The descriptor is written FOR this retry; a live
157
+ // record only wins when it is a complete spawn record (repo + work present).
158
+ const liveIsSpawnRecord = !!liveMeta && nonEmptyString(liveMeta.repo) && WORK_MODES.includes(liveMeta.work);
159
+ const meta = liveIsSpawnRecord || !quarantine ? (liveMeta || quarantine?.cleanup || {}) : { ...liveMeta, ...quarantine.cleanup };
160
+ // Compensation metadata is the SPAWN's, from whichever record survived — never
161
+ // a failed retry's report, which says nothing about what still needs undoing.
162
+ if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;
163
+ if (quarantine && typeof quarantine.cleanup.launched === "boolean") {
164
+ meta.launched = quarantine.cleanup.launched;
165
+ meta.tmux = quarantine.cleanup.tmux;
166
+ meta.sessionTarget = quarantine.cleanup.sessionTarget;
167
+ }
168
+ // A home with NEITHER instance.json NOR a usable cleanup descriptor cannot be
169
+ // retired safely: hooks would be skipped and the directory removed, which is
170
+ // the credential deletion the quarantine exists to prevent — and the spawn
171
+ // path tolerates a failed marker write, so this state is reachable. Fail
172
+ // closed; `force` is the deliberate manual-cleanup escape.
173
+ // A marker that cannot drive a retry is not "ignore me" — it is evidence that
174
+ // cleanup was interrupted and OATS cannot tell what remains. Fail closed even
175
+ // when instance.json is present; `--force` is the deliberate manual escape.
176
+ if (markerUnusable && !force) {
177
+ throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${home} carries a rollback marker that cannot drive a retry (unreadable, or missing the cleanup descriptor fields the retry consumes), so OATS cannot tell what external state still depends on this home. Inspect it, then re-run with \`--force\` to remove it anyway.`);
178
+ }
179
+ if (!existsSync(metaPath) && !quarantine && !force) {
180
+ throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${home} has no instance.json and no cleanup descriptor, so OATS cannot tell whether external state (identities, worktrees) still depends on it. Retiring it would delete whatever it holds without running any cleanup. Inspect it, then re-run with \`--force\` to remove it anyway.`);
181
+ }
182
+ // #962: a missing recorded repo does not mean the own worktree has none.
183
+ // Resolve it with exactly the reader the retire uses; keep the raw record
184
+ // untouched so the plan still shows (and binds) its missing-repo fact.
185
+ const workIs = readWork(home, meta);
186
+ const repoFromGit = workIs.is === "own-tree" && !meta.repo ? workIs.tree?.repo : undefined;
187
+ const hookRepo = meta.repo || repoFromGit;
188
+ // Only positive evidence from this record can authorize skipping cleanup.
189
+ const bindings = meta.capabilityRuntime;
190
+ const knownBindings = Array.isArray(bindings) && bindings.every(cap =>
191
+ isPlainObject(cap) && nonEmptyString(cap.id) &&
192
+ (cap.hooks === undefined || isPlainObject(cap.hooks) &&
193
+ (!Object.hasOwn(cap.hooks, "retire") || nonEmptyString(cap.hooks.retire))));
194
+ const noRetireHooks = knownBindings && !bindings.some(cap => cap.hooks?.retire);
195
+ const captured = isCapturedHome(meta);
196
+ const noCapturedSpawn = Array.isArray(meta.captured?.hookOrder) && meta.captured.hookOrder.length === 0 &&
197
+ (meta.capabilityMeta === undefined || isPlainObject(meta.capabilityMeta) && Object.keys(meta.capabilityMeta).length === 0) &&
198
+ (meta.captured.hookIntents === undefined || isPlainObject(meta.captured.hookIntents) && Object.keys(meta.captured.hookIntents).length === 0) &&
199
+ (meta.captured.hookFailures === undefined || Array.isArray(meta.captured.hookFailures) && meta.captured.hookFailures.length === 0) &&
200
+ (meta.captured.lifecycle === undefined || typeof meta.captured.lifecycle === "string" && !meta.captured.lifecycle.endsWith("-cleanup-required"));
201
+ const cause = captured && !noCapturedSpawn
202
+ ? "is a captured home from before 0.26 whose retire hooks cannot run, and its record does not prove that no capability's spawn hook ran"
203
+ : !captured && !knownBindings
204
+ ? "does not record capabilityRuntime, or its recorded capability hooks cannot be identified (homes spawned before capabilityRuntime need manual cleanup)"
205
+ : !captured && !nonEmptyString(hookRepo) && !noRetireHooks
206
+ ? "names no repository in which its recorded retire hooks can run"
207
+ : null;
208
+ if (!force && cause) {
209
+ const named = [...new Set([...capturedHomeCapabilities(meta),
210
+ ...(Array.isArray(bindings) ? bindings.map(cap => cap?.id).filter(nonEmptyString) : [])])];
211
+ const capabilities = named.length ? `Capabilities that may have left state: ${named.join(", ")}. ` : "";
212
+ throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${metaPath} ${cause}. ${capabilities}External identities or memberships may still depend on this home. Nothing was stopped, run or removed, including children. Inspect the home and clean up that state with the provider's tooling, then remove it with \`oats retire ${name} --force\`; --force removes the home without revoking state whose retire hooks cannot run.`);
213
+ }
214
+ return { meta, liveMeta, workIs, repoFromGit, hookRepo, directoryFallbackPath, quarantinePath, quarantine, hooksKnown: knownBindings, spawnGroupWarnings, inProgressUnverified };
215
+ }
package/lib/servers.mjs CHANGED
@@ -1791,6 +1791,9 @@ export function redactArgv(argv) {
1791
1791
  * relay the host's envelope verbatim) and inherited otherwise; stderr is always inherited.
1792
1792
  * → { status, stdout } (stdout only under json). */
1793
1793
  export function routeCapability(serverId, argv, { server, spawnSync: spawn = spawnSync, stdinIsTTY = process.stdin.isTTY, json = false } = {}) {
1794
+ if (argv.some(arg => arg === "--invite" || arg.startsWith("--invite="))) {
1795
+ throw serverError("E_BAD_ARGS", "routed capability commands cannot carry --invite in argv: use --invite-stdin and pipe the invite on stdin so it is not exposed in the ssh process arguments");
1796
+ }
1794
1797
  const target = targetOf(server);
1795
1798
  const [bin, ...rest] = sshArgv(target, argv, { cwd: target.workspace, control: controlUsable(target, { serverId }) });
1796
1799
  const r = spawn(bin, rest, { stdio: [stdinIsTTY ? "ignore" : "inherit", json ? "pipe" : "inherit", "inherit"], maxBuffer: 64 * 1024 * 1024 });
@@ -25,7 +25,7 @@ export const OUTCOME = Object.freeze({ RESUMED: "resumed", FRESH: "fresh", ALREA
25
25
  export const ROW_REASON = Object.freeze({
26
26
  UNKNOWN: "unknown", START_BUSY: "start-busy", NOT_LOST: "not-lost", NOT_SEEN_RECENTLY: "not-seen-recently",
27
27
  RESUME_CONFIRMATION: RESUME_WAITING.RESUME_CONFIRMATION, LAUNCH_PROMPT: "launch-prompt",
28
- START_REFUSED: "start-refused", REFUSED_THIS_BOOT: "refused-this-boot", KEEPS_GETTING_LOST: "keeps-getting-lost",
28
+ START_REFUSED: "start-refused", START_REFUSED_RETRYING: "start-refused-retrying", KEEPS_GETTING_LOST: "keeps-getting-lost",
29
29
  LIFECYCLE_BUSY: "lifecycle-busy",
30
30
  });
31
31