@awebai/oats 0.69.19 → 0.69.21
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 +28 -5
- package/docs/capabilities.md +27 -14
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +218 -18
- package/docs/desktop-cli-api.md +105 -11
- package/docs/desktop.md +122 -65
- package/docs/implementation.md +3 -2
- 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-notes/v0.69.20.md +325 -0
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/servers.md +9 -3
- package/docs/souls-and-instances.md +15 -2
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +13 -7
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +36 -198
- package/lib/hook-outcome.mjs +6 -0
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +19 -1
- package/lib/instance-listing.mjs +11 -6
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/launch-prompt-fixtures/README.md +6 -0
- package/lib/retire-admission.mjs +215 -0
- package/lib/servers.mjs +11 -3
- package/package-catalog.json +3 -3
- package/package.json +1 -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/lifecycle-confirmation.mjs +4 -2
- package/packages/client/lifecycle-contract.mjs +11 -6
- package/packages/client/remote-roster.mjs +4 -0
- package/packages/client/roster-row-facts.mjs +50 -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 +211 -28
package/lib/instance-listing.mjs
CHANGED
|
@@ -15,6 +15,7 @@ import { isInstant as isInstantString, readRetireState } from "./retire-state.mj
|
|
|
15
15
|
import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
|
|
16
16
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
17
17
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
18
|
+
import { readInstancePin } from "./instance-pin.mjs";
|
|
18
19
|
import { sameWorkOf } from "./instance-same-work.mjs";
|
|
19
20
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
20
21
|
import { sessionEndOf } from "./session-end.mjs";
|
|
@@ -53,7 +54,8 @@ export function legacyLocalAgents(root) {
|
|
|
53
54
|
|
|
54
55
|
/** The captured homes (the 0.24–0.25 captured/portable path, removed in 0.26) under the
|
|
55
56
|
* 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);
|
|
57
|
+
* no 0.26 runtime (start, inspect and in-home commands refuse them); captured homes
|
|
58
|
+
* without positive cleanup proof need manual cleanup and forced retirement.
|
|
57
59
|
* `records`: the records listInstances read in this same read (its `records`), each home's
|
|
58
60
|
* instance.json parsed once per read; a home it holds no record for is read here. */
|
|
59
61
|
export function legacyCapturedHomes(root, { records } = {}) {
|
|
@@ -70,7 +72,7 @@ export function legacyCapturedHomes(root, { records } = {}) {
|
|
|
70
72
|
homes.sort((a, b) => a.instance.localeCompare(b.instance));
|
|
71
73
|
const one = homes.length === 1;
|
|
72
74
|
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"};
|
|
75
|
+
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
76
|
}
|
|
75
77
|
// The tmux session a new tmux instance opens its window in, when oats-local.yaml session.tmuxSession
|
|
76
78
|
// names none (0.31). PI_AGENTS_TMUX_SESSION is the pre-0.31 variable, still honoured. The Desktop keeps
|
|
@@ -348,9 +350,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
348
350
|
try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
|
|
349
351
|
catch { waitingOnYou = null; }
|
|
350
352
|
}
|
|
351
|
-
// `retire` is only ever the value read above, and `background` and `sameWork` the home's own
|
|
352
|
-
// (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
353
|
-
|
|
353
|
+
// `retire` is only ever the value read above, and `background`, `pinned` and `sameWork` the home's own
|
|
354
|
+
// records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
355
|
+
// for it.
|
|
356
|
+
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
|
|
354
357
|
// `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
|
|
355
358
|
// a malformed one is null, and a home spawned before the feature has no key.
|
|
356
359
|
if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
|
|
@@ -360,10 +363,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
360
363
|
const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? sessionEndOf(home, meta) : null;
|
|
361
364
|
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
362
365
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
366
|
+
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
367
|
+
// otherwise, never false.
|
|
363
368
|
// Feature instance-same-work: `sameWork: true` only while the home's flag is bound to the parent
|
|
364
369
|
// its readable record names (lib/instance-same-work.mjs sameWorkOf); absent otherwise, never false.
|
|
365
370
|
const sameWork = record.state === "record" && sameWorkOf(home, meta.parentInstance);
|
|
366
|
-
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
371
|
+
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
367
372
|
|
|
368
373
|
});
|
|
369
374
|
};
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/** Whether an instance is pinned (feature instance-pin): presentation like the colour
|
|
2
|
+
* (lib/instance-color.mjs) and background (lib/instance-background.mjs), never identity or policy. A client
|
|
3
|
+
* of the machine lists a pinned instance at the top of its list; nothing else about the instance changes.
|
|
4
|
+
* The pin is the home's, so it is shared: everyone who views that machine sees it. It is a home file of
|
|
5
|
+
* its own, `<home>/.oats-pinned.json`, so that a start or restart, which rewrites instance.json, can never
|
|
6
|
+
* lose it, and retire removes it with the home.
|
|
7
|
+
*
|
|
8
|
+
* The record is `{ pinnedApi: 1, at }` (present means pinned), written atomically (writeThroughPrivateFile)
|
|
9
|
+
* at mode 0600; absent means not pinned, and `off` removes the file. A reader takes a regular file only,
|
|
10
|
+
* without following a link, up to RECORD_MAX bytes: anything that is not a valid record reads as not
|
|
11
|
+
* pinned (false), never an error. Dependency-free: the status rows, inspect and the command all read and
|
|
12
|
+
* write it through here. */
|
|
13
|
+
import { lstatSync, rmSync } from "node:fs";
|
|
14
|
+
import { join } from "node:path";
|
|
15
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
16
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
17
|
+
|
|
18
|
+
/** The record's own version, and the command answer's. */
|
|
19
|
+
export const PIN_API = 1;
|
|
20
|
+
export const INSTANCE_PIN_API = 1;
|
|
21
|
+
/** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
|
|
22
|
+
* fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
|
|
23
|
+
export const PIN_FILE = ".oats-pinned.json";
|
|
24
|
+
/** A record larger than this is not one. */
|
|
25
|
+
export const RECORD_MAX = 4096;
|
|
26
|
+
|
|
27
|
+
/** Whether `home` records itself pinned: false for no file, not a regular file (a link is never followed),
|
|
28
|
+
* over RECORD_MAX bytes, unreadable, not a JSON object or another pinnedApi. Never throws. */
|
|
29
|
+
export function readInstancePin(home) {
|
|
30
|
+
try {
|
|
31
|
+
const { bytes, size } = readFileHead(join(home, PIN_FILE), RECORD_MAX + 1);
|
|
32
|
+
if (size > RECORD_MAX) return false;
|
|
33
|
+
const record = JSON.parse(bytes.toString("utf8"));
|
|
34
|
+
return !!record && typeof record === "object" && !Array.isArray(record) && record.pinnedApi === PIN_API;
|
|
35
|
+
} catch { return false; }
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Pin `home` (`on` true), or remove its pin (`on` false). → `{ pinned, changed }`. A home already pinned is
|
|
39
|
+
* no change: nothing is written. `off` removes whatever stands at the name (a link or an invalid record
|
|
40
|
+
* included) and is a change only when the home read as pinned. The caller holds the right to change the
|
|
41
|
+
* home. */
|
|
42
|
+
export function writeInstancePin(home, on, { now = () => new Date() } = {}) {
|
|
43
|
+
const path = join(home, PIN_FILE);
|
|
44
|
+
const before = readInstancePin(home);
|
|
45
|
+
// What stands at the name, never followed: null for nothing. The name is kernel-owned, so a directory
|
|
46
|
+
// there is no one's work: `off` removes it, and `on` removes it before the record is renamed into place
|
|
47
|
+
// (a rename cannot replace a directory).
|
|
48
|
+
let standing = null;
|
|
49
|
+
try { standing = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
|
|
50
|
+
if (!on) {
|
|
51
|
+
if (standing) rmSync(path, { force: true, recursive: standing.isDirectory() });
|
|
52
|
+
return { pinned: false, changed: before };
|
|
53
|
+
}
|
|
54
|
+
if (before) return { pinned: true, changed: false };
|
|
55
|
+
if (standing?.isDirectory()) rmSync(path, { force: true, recursive: true });
|
|
56
|
+
const bytes = JSON.stringify({ pinnedApi: PIN_API, at: now().toISOString() }) + "\n";
|
|
57
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
|
|
58
|
+
return { pinned: true, changed: true };
|
|
59
|
+
}
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -8,6 +8,6 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
|
8
8
|
/** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
|
|
9
9
|
* its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
|
|
10
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]);
|
|
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-pin", "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]);
|
|
12
12
|
/** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
|
|
13
13
|
export const READER_API = 1;
|
|
@@ -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
|
@@ -936,6 +936,8 @@ const HOST_SURFACES = {
|
|
|
936
936
|
"instance color": { feature: "instance-color" },
|
|
937
937
|
// Feature instance-background: the same (its answer's instanceBackgroundApi is not a probe key).
|
|
938
938
|
"instance background": { feature: "instance-background" },
|
|
939
|
+
// Feature instance-pin: the feature alone, as instance background.
|
|
940
|
+
"instance pin": { feature: "instance-pin" },
|
|
939
941
|
// Feature instance-same-work: the feature alone, as instance color.
|
|
940
942
|
"instance same-work": { feature: "instance-same-work" },
|
|
941
943
|
};
|
|
@@ -946,7 +948,7 @@ function requireSurface(remote, target, surface) {
|
|
|
946
948
|
}
|
|
947
949
|
}
|
|
948
950
|
|
|
949
|
-
/** `readiness`, `instance events|git|diff|stop|color|background|same-work` and `retire --plan` on the
|
|
951
|
+
/** `readiness`, `instance events|git|diff|stop|color|background|pin|same-work` and `retire --plan` on the
|
|
950
952
|
* host: the instance is addressed as every routed session command addresses
|
|
951
953
|
* it (its name through a saved route or the host's roster, or an exact
|
|
952
954
|
* --home), the scope is an explicit --dir on the host or the registered
|
|
@@ -955,7 +957,7 @@ function requireSurface(remote, target, surface) {
|
|
|
955
957
|
function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
956
958
|
const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
|
|
957
959
|
const surface = HOST_SURFACES[key];
|
|
958
|
-
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background and same-work only (not ${key})`);
|
|
960
|
+
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and same-work only (not ${key})`);
|
|
959
961
|
const args = [...oatsArgs];
|
|
960
962
|
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
961
963
|
const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
|
|
@@ -1016,6 +1018,9 @@ const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: re
|
|
|
1016
1018
|
/** `background` (feature instance-background) only as `true`, relayed ONLY when the host's row says exactly
|
|
1017
1019
|
* that: absent is the only reading of "not background", so any other value is dropped, never false. */
|
|
1018
1020
|
const rowBackground = (i) => (i.background === true ? { background: true } : {});
|
|
1021
|
+
/** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
|
|
1022
|
+
* absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
|
|
1023
|
+
const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
|
|
1019
1024
|
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
1020
1025
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
1021
1026
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
@@ -1134,7 +1139,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1134
1139
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
|
|
1135
1140
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1136
1141
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1137
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i), ...rowSessionEnd(i),
|
|
1142
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowSameWork(i), ...rowSessionEnd(i),
|
|
1138
1143
|
// Every row the host reports is addressed by its home, saved
|
|
1139
1144
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1140
1145
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
|
@@ -1791,6 +1796,9 @@ export function redactArgv(argv) {
|
|
|
1791
1796
|
* relay the host's envelope verbatim) and inherited otherwise; stderr is always inherited.
|
|
1792
1797
|
* → { status, stdout } (stdout only under json). */
|
|
1793
1798
|
export function routeCapability(serverId, argv, { server, spawnSync: spawn = spawnSync, stdinIsTTY = process.stdin.isTTY, json = false } = {}) {
|
|
1799
|
+
if (argv.some(arg => arg === "--invite" || arg.startsWith("--invite="))) {
|
|
1800
|
+
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");
|
|
1801
|
+
}
|
|
1794
1802
|
const target = targetOf(server);
|
|
1795
1803
|
const [bin, ...rest] = sshArgv(target, argv, { cwd: target.workspace, control: controlUsable(target, { serverId }) });
|
|
1796
1804
|
const r = spawn(bin, rest, { stdio: [stdinIsTTY ? "ignore" : "inherit", json ? "pipe" : "inherit", "inherit"], maxBuffer: 64 * 1024 * 1024 });
|
package/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v6.0
|
|
6
|
+
"ref": "v6.2.0",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.43.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"oats.framework": {
|
|
50
50
|
"url": "https://github.com/awebai/oats.git",
|
|
51
|
-
"ref": "oats-framework/v1.
|
|
51
|
+
"ref": "oats-framework/v1.26.0",
|
|
52
52
|
"path": "oats-package"
|
|
53
53
|
}
|
|
54
54
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.69.
|
|
3
|
+
"version": "0.69.21",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** The owning human (feature spawn-attribution): a status row's `attributedHuman`, the label of the human
|
|
2
|
+
* the instance's messaging identity is attributed to, or null (docs/desktop-cli-api.md, "Attributed human").
|
|
3
|
+
* Read as the kernel gives it, under the contract's own rule for the label (a waiting claim's message rule,
|
|
4
|
+
* waiting-on-you.mjs `waitingMessage`), on a local row and again on a remote row its host relayed. Anything
|
|
5
|
+
* else (not a string, blank, a refused character, over 200 code points, or text withheld as unsafe) is null:
|
|
6
|
+
* no human, never a fault, so a malformed value can't fail the row. Pure, never throws. */
|
|
7
|
+
import { waitingMessage } from './waiting-on-you.mjs';
|
|
8
|
+
import { EVENTS_WITHHELD } from './instance-events-contract.mjs';
|
|
9
|
+
|
|
10
|
+
export function attributedHumanData(v) {
|
|
11
|
+
const label = waitingMessage(v);
|
|
12
|
+
return label === EVENTS_WITHHELD || !label?.trim() ? null : label;
|
|
13
|
+
}
|
|
@@ -8,6 +8,7 @@ import { teamRow, teamRowsOf, defaultTeamOf, TEAM_ID } from './team-rows.mjs';
|
|
|
8
8
|
import { launchOf, REPORT_FROM } from './launch-contract.mjs';
|
|
9
9
|
import { readIdentity } from './workspace-views.mjs';
|
|
10
10
|
import { waitingOnYouData } from './waiting-on-you.mjs';
|
|
11
|
+
import { attributedHumanData } from './attributed-human.mjs';
|
|
11
12
|
import { retireData } from './retire-state.mjs';
|
|
12
13
|
import { instanceColor } from './instance-presentation.mjs';
|
|
13
14
|
const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
|
|
@@ -244,6 +245,9 @@ export function deploymentStatusData(document, deployment) {
|
|
|
244
245
|
// Needs input (PR K): validated, never check()ed — an invalid claim is null (unknown), never an E_* that
|
|
245
246
|
// fails the roster. Absent stays absent.
|
|
246
247
|
if (own(instance, 'waitingOnYou')) row.waitingOnYou = waitingOnYouData(instance.waitingOnYou);
|
|
248
|
+
// Feature spawn-attribution: the owning human's label, or null. Validated, never check()ed: a malformed
|
|
249
|
+
// value is null (no human), never an E_* that fails the roster. Absent stays absent.
|
|
250
|
+
if (own(instance, 'attributedHuman')) row.attributedHuman = attributedHumanData(instance.attributedHuman);
|
|
247
251
|
return [row];
|
|
248
252
|
});
|
|
249
253
|
return out;
|
|
@@ -133,6 +133,8 @@ export function panelInstance(i) {
|
|
|
133
133
|
// Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
|
|
134
134
|
// The client's liveness is merged before projection, so running/runtimeState beside it are the probe's.
|
|
135
135
|
...(i.waitingOnYou !== undefined ? { waitingOnYou: i.waitingOnYou } : {}),
|
|
136
|
+
// The owning human (feature spawn-attribution): the label deployment-data.mjs validated, or null; absent stays absent.
|
|
137
|
+
...(i.attributedHuman !== undefined ? { attributedHuman: i.attributedHuman } : {}),
|
|
136
138
|
// Feature instance-color: the row's colour as instanceColor reads it, present only when it is one.
|
|
137
139
|
...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
|
|
138
140
|
// Feature instance-background (#1579): exactly true, else absent (instance-tree.mjs backgroundPlacement).
|
|
@@ -53,9 +53,9 @@ const kernelAnswered = envelope => envelope?.origin === 'kernel' && envelope.sch
|
|
|
53
53
|
* A kernel's E_LIFECYCLE_BUSY whose kernel (`features`: the answering kernel's) says who holds the claim
|
|
54
54
|
* reads by that (`holder`, busyHolder), local or remote, and names the target of `plan` the refusal is
|
|
55
55
|
* about when that is not the instance acted on (`about`). */
|
|
56
|
-
function failureReason(envelope, remote, terms, { code = envelope?.error?.code, features = null, plan = null } = {}) {
|
|
56
|
+
function failureReason(envelope, remote, terms, { code = envelope?.error?.code, features = null, plan = null, operation } = {}) {
|
|
57
57
|
const kernel = kernelAnswered(envelope), undescribed = kernel ? undescribedAnswer(code, terms) : null;
|
|
58
|
-
const reason = undescribed || lifecycleReason(code, terms), details = envelope?.error?.details;
|
|
58
|
+
const reason = undescribed || lifecycleReason(code, terms, { operation }), details = envelope?.error?.details;
|
|
59
59
|
const holder = kernel ? busyHolder(code, details, features) : null, about = holder ? busyAbout(plan, details?.home) : null;
|
|
60
60
|
const busy = holder ? { holder, ...(about ? { about } : {}) } : {};
|
|
61
61
|
const message = holder ? busyHeadline(holder) : reason.message;
|
|
@@ -140,7 +140,8 @@ export function createLifecycleBoundary({ invoke = cliLifecycle, now = () => per
|
|
|
140
140
|
if (!same(selected, current)) return denied('E_PLAN_CHANGED', selected.target);
|
|
141
141
|
if (envelope?.schemaVersion !== 1 || envelope.ok !== true) {
|
|
142
142
|
const code = envelope?.error?.code || 'E_CLI_PROTOCOL';
|
|
143
|
-
return denied(code, selected.target, { reason: failureReason(envelope, selected.remote, terms, { code, features: selected.features
|
|
143
|
+
return denied(code, selected.target, { reason: failureReason(envelope, selected.remote, terms, { code, features: selected.features,
|
|
144
|
+
operation: request.operation }) });
|
|
144
145
|
}
|
|
145
146
|
// The plan is read by the features of the kernel that made it: for a relayed plan its host's, never this computer's.
|
|
146
147
|
const data = lifecyclePlan(envelope.result, selected.target, request.operation, choices, { features: selected.features });
|
|
@@ -180,7 +181,8 @@ export function createLifecycleBoundary({ invoke = cliLifecycle, now = () => per
|
|
|
180
181
|
// children have already stopped. The user must explicitly read a new plan.
|
|
181
182
|
return failure(code, 'refused', { plan: fresh, childrenStopped });
|
|
182
183
|
}
|
|
183
|
-
if (beforeEffect.has(code)) return failure(code, 'refused', { reason: failureReason(envelope, entry.remote, terms,
|
|
184
|
+
if (beforeEffect.has(code)) return failure(code, 'refused', { reason: failureReason(envelope, entry.remote, terms,
|
|
185
|
+
{ features, plan: entry.plan, operation: entry.plan.action }) });
|
|
184
186
|
return failure('E_OUTCOME_UNKNOWN', 'unknown', { cause: failureReason(envelope, entry.remote, terms, { features }) });
|
|
185
187
|
}
|
|
186
188
|
/** The apply of this client that is running, as a reply names it. */
|
|
@@ -213,8 +213,10 @@ function refusal(reason, plan, { operation, leftover }, terms) {
|
|
|
213
213
|
return { status: { headline: LEFTOVER_HELD, more: [], next: 'retire-with-force', code: reason.code }, blocks: [{ type: 'quote', text: shown.detail }] };
|
|
214
214
|
// A reason with no code reads as the table's fallback, and says that fallback's code; a code only the client
|
|
215
215
|
// raises (one the table does not know) keeps its own, so the client can word it.
|
|
216
|
-
const table = lifecycleReason(reason?.code, terms
|
|
217
|
-
const
|
|
216
|
+
const table = lifecycleReason(reason?.code, terms, { operation });
|
|
217
|
+
const own = typeof reason?.code === 'string' && reason.code ? reason.code : table.code;
|
|
218
|
+
// This code's headline must hold for every cause, even when a relayed sentence still offers force.
|
|
219
|
+
const status = remote ? { headline: remote.code === 'E_UNIDENTIFIED_INSTANCE_HOME' ? table.message : remote.message, code: remote.code } : undescribed ? { headline: undescribed.message, code: reason.code }
|
|
218
220
|
: { headline: table.message, code: own };
|
|
219
221
|
return { status: { more: [], next: null, ...status }, blocks: shown ? [{ type: 'details', reason: shown, bare: !!undescribed }] : [] };
|
|
220
222
|
}
|
|
@@ -22,9 +22,13 @@ const messages = {
|
|
|
22
22
|
E_USAGE: 'Invalid lifecycle request.', E_WORKSPACE_UNKNOWN: 'Choose an advertised workspace.',
|
|
23
23
|
E_SESSION_UNKNOWN: 'This instance is no longer in the current roster.', E_AMBIGUOUS_INSTANCE: 'Select an exact instance home.',
|
|
24
24
|
E_HOME_MISMATCH: 'The instance home no longer matches this selection.',
|
|
25
|
-
// The kernel's, for a home
|
|
26
|
-
//
|
|
27
|
-
|
|
25
|
+
// The kernel's, for a home whose record or cleanup cannot be used. Answered only before any effect.
|
|
26
|
+
// The envelope has no structured cause discriminator. Details gives the remedy; never parse its words
|
|
27
|
+
// or promise force, which cannot bypass a record that is there and cannot be read.
|
|
28
|
+
E_UNIDENTIFIED_INSTANCE_HOME: (_terms, context) => {
|
|
29
|
+
if (context?.operation !== 'retire') return "OATS couldn't find or read what it needs in this instance's home folder, so nothing was done.";
|
|
30
|
+
return "OATS can't tell what this home's capabilities created, or can't run their cleanup, so nothing was removed. Details says what may be left and how to finish.";
|
|
31
|
+
},
|
|
28
32
|
'cli-unavailable': 'Choose a compatible installed OATS CLI.',
|
|
29
33
|
E_LIFECYCLE_UNAVAILABLE: terms => `This OATS can't stop or retire instances from ${terms.name}. Update OATS.`,
|
|
30
34
|
'unsupported-remote-operation': "This computer's OATS can't route this to the server. Update OATS here.",
|
|
@@ -53,11 +57,12 @@ export const LIFECYCLE_CODES = Object.freeze(Object.keys(messages));
|
|
|
53
57
|
/** The code as the table knows it: itself, or `E_CLI_FAILED` for one it has no sentence for. Needs no terms. */
|
|
54
58
|
export const lifecycleCode = code => (Object.hasOwn(messages, code) ? code : 'E_CLI_FAILED');
|
|
55
59
|
/** The code and its sentence, in the client's terms (client-terms.mjs): a sentence that names the client is
|
|
56
|
-
* built from them.
|
|
57
|
-
|
|
60
|
+
* built from them. `context` supplies the explicit operation for a Remove's cleanup refusal;
|
|
61
|
+
* without it the unidentified-home sentence stays neutral, as it is for Stop. */
|
|
62
|
+
export function lifecycleReason(code, terms, context = {}) {
|
|
58
63
|
requireTerms(terms, 'lifecycleReason');
|
|
59
64
|
const known = lifecycleCode(code), message = messages[known];
|
|
60
|
-
return { code: known, message: typeof message === 'function' ? message(terms) : message };
|
|
65
|
+
return { code: known, message: typeof message === 'function' ? message(terms, context) : message };
|
|
61
66
|
}
|
|
62
67
|
/** A kernel's error answer whose code has no sentence here. It says "OATS answered", so it is chosen only
|
|
63
68
|
* for a code read out of the kernel's own error envelope: by where the code came from, which only the caller
|
|
@@ -2,6 +2,7 @@ import { harnessOf } from "./harness-names.mjs";
|
|
|
2
2
|
import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
|
|
3
3
|
import { madeByKernel } from "./kernel-made.mjs";
|
|
4
4
|
import { waitingOnYouData } from "./waiting-on-you.mjs";
|
|
5
|
+
import { attributedHumanData } from "./attributed-human.mjs";
|
|
5
6
|
import { retireData } from "./retire-state.mjs";
|
|
6
7
|
import { readIdentity } from "./workspace-views.mjs";
|
|
7
8
|
import { sameRepo } from "./repo-moves.mjs";
|
|
@@ -61,6 +62,9 @@ export function remotePanel(group, at) {
|
|
|
61
62
|
tmux: i.tmux || null, git: i.git || null, task: i.task || "", next: i.next || "",
|
|
62
63
|
// Needs input: only a remote kernel with the feature reports it — validated, never synthesized when absent.
|
|
63
64
|
...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
|
|
65
|
+
// The owning human (feature spawn-attribution): the host's label validated again here (attributed-human.mjs),
|
|
66
|
+
// a malformed one null; a host that does not report it leaves it absent.
|
|
67
|
+
...(Object.hasOwn(i, "attributedHuman") ? { attributedHuman: attributedHumanData(i.attributedHuman) } : {}),
|
|
64
68
|
// #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
|
|
65
69
|
...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
|
|
66
70
|
// #1577: the host's same-work flag, true only (anything else reads unflagged). `sameWorkKnown` is this
|