@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.
- package/bin/oats.mjs +2 -2
- package/docs/capabilities.md +27 -14
- package/docs/container.md +416 -43
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +52 -31
- package/docs/desktop.md +29 -6
- package/docs/execution-targets.md +32 -17
- package/docs/implementation.md +4 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +6 -4
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/release-notes/v0.69.20.md +325 -0
- package/docs/servers.md +6 -4
- package/docs/souls-and-instances.md +37 -13
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +13 -7
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/core.mjs +33 -197
- package/lib/hook-outcome.mjs +6 -0
- package/lib/host-run.mjs +24 -19
- package/lib/instance-lifecycle.mjs +3 -1
- package/lib/instance-listing.mjs +3 -2
- package/lib/launch-prompt-fixtures/README.md +6 -0
- package/lib/retire-admission.mjs +215 -0
- package/lib/servers.mjs +3 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +130 -47
- package/lib/session-seen.mjs +3 -3
- package/package-catalog.json +3 -3
- package/package.json +3 -1
- package/packages/client/attributed-human.mjs +13 -0
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/instance-lifecycle.mjs +6 -4
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/lifecycle-confirmation.mjs +4 -2
- package/packages/client/lifecycle-contract.mjs +11 -6
- package/packages/client/remote-roster.mjs +4 -0
- package/packages/record/README.md +15 -2
- package/packages/record/docs/capture-service.md +14 -0
- package/packages/record/lib/canonical.mjs +2 -70
- package/packages/record/lib/capture-aw-unit.mjs +14 -3
- package/packages/record/lib/capture-aw.mjs +11 -5
- package/packages/record/lib/capture-health.mjs +16 -5
- 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
|
|
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
|
|
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
|
|
19
|
-
* records what runs for
|
|
20
|
-
* loop stays free for the signal. A minute whose tick still runs is skipped; a minute
|
|
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,
|
|
163
|
-
|
|
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,
|
|
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
|
|
193
|
-
//
|
|
194
|
-
// deployment
|
|
195
|
-
|
|
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,
|
|
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);
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -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);
|
|
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"};
|
|
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",
|
|
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
|
|