@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/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.21** ([release notes](release-notes/v0.69.21.md)).
|
|
10
|
+
The 0.69.21 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.69.
|
|
14
|
+
0.69.21,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
24
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.21, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.21 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,18 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.69.21](release-notes/v0.69.21.md#upgrade):** the catalog pins
|
|
221
|
+
oats.aweb 1.43.0. A deployment on a non-public aw registry runs
|
|
222
|
+
`oats aweb setup --registry <origin>`, reruns `oats aweb resident create`,
|
|
223
|
+
reinstalls the wake service and restarts its homes; exported aw selectors no
|
|
224
|
+
longer reach aw. Respawn grant seats whose resident or default team changed.
|
|
225
|
+
Respawn instances to take the new module.
|
|
226
|
+
- **[0.69.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
|
|
227
|
+
oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
|
|
228
|
+
recorded cleanup hooks cannot run is refused; clean up its external state,
|
|
229
|
+
then run `oats retire --force`. Team-container deployments
|
|
230
|
+
recreate their agent containers, and those with a local registry service set
|
|
231
|
+
`team.registryRoute: local`. Respawn instances to take the new texts.
|
|
220
232
|
- **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
|
|
221
233
|
oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
|
|
222
234
|
`OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
58
|
-
oats.okf: v6.0
|
|
57
|
+
oats.framework: v1.26.0 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v6.2.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
|
@@ -425,15 +425,21 @@ member soul that is the expert in that capability (`oats-okf-expert`,
|
|
|
425
425
|
**OATS's coordination is a member copy of the engineering template.** The
|
|
426
426
|
`oats` repository keeps its own copy of
|
|
427
427
|
[oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
|
|
428
|
-
at template-
|
|
428
|
+
at template-v4.0.2, adapted to OATS: `oats.engineering-expert`,
|
|
429
429
|
`oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
|
|
430
430
|
`oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
|
|
431
431
|
`capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
|
|
432
|
-
`capabilities/THIRD-PARTY-NOTICES.md` the sources
|
|
433
|
-
|
|
432
|
+
`capabilities/THIRD-PARTY-NOTICES.md` the sources that three rules of the build skill and
|
|
433
|
+
the quality floor adapt. `oats.build` holds the build skills, and every soul that
|
|
434
434
|
builds composes it: the developers, and the engineering experts that build their own
|
|
435
|
-
specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies
|
|
436
|
-
|
|
435
|
+
specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies. The
|
|
436
|
+
template drops the lane map, but OATS keeps it: the landing rules point at the lane map,
|
|
437
|
+
which stays the one home of OATS's lanes and their owners, and a lane's maintainer is
|
|
438
|
+
found by its entry there. Every lane asks for its maintainer's green light on every PR of
|
|
439
|
+
an effort, before its second reader and the release lane's sign-off where the lane asks.
|
|
440
|
+
Both maintainer reads look at the code and judge direction, roadmap and product fit: the
|
|
441
|
+
lane maintainer by the five checks of its green light plus its own read of the whole
|
|
442
|
+
diff, the release lane by the four gates, at the exact head being merged.
|
|
437
443
|
The reviewer is the template's `code-reviewer` soul, in `souls/`. The workspace
|
|
438
444
|
doesn't pin the `oats.engineering` package, frozen at v1.18.0
|
|
439
445
|
([official catalog](official-catalog.md#coordination-templates)), so each of
|
|
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
|
|
|
181
181
|
* declaration may not cover them: these exact names, and every exact name
|
|
182
182
|
* starting with one of these prefixes (the events log; the stop, restart and
|
|
183
183
|
* start receipts and locks; the rollback marker; AGENTS.md backups; the
|
|
184
|
-
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
|
|
184
|
+
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
|
|
185
185
|
* home entry MUST be added here and to the `not` patterns of
|
|
186
186
|
* `retirement.disposable.home` in docs/capability-manifest.schema.json. A
|
|
187
187
|
* prefix declaration can reach none of them except through `.oats-`, which is
|
|
188
188
|
* refused whole; `.oats-<provider>` as an exact name stays declarable. */
|
|
189
189
|
const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
|
|
190
|
-
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-same-work"];
|
|
190
|
+
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work"];
|
|
191
191
|
|
|
192
192
|
/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
|
|
193
193
|
* name or prefix), "kernel-owned", or undefined when it is sound. */
|
package/lib/command-flags.mjs
CHANGED
|
@@ -102,6 +102,7 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
102
102
|
{ command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
|
|
103
103
|
usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
104
104
|
onOff("background"),
|
|
105
|
+
onOff("pin"),
|
|
105
106
|
onOff("same-work"),
|
|
106
107
|
waiting("set"),
|
|
107
108
|
waiting("clear"),
|
package/lib/core.mjs
CHANGED
|
@@ -27,6 +27,9 @@
|
|
|
27
27
|
* work (worktree|checkout|attached|workspace|directory), harness (pi|claude|codex), model (pi model pattern, optional)
|
|
28
28
|
* (attached as soul default is for service agents — spawn must supply workDir)
|
|
29
29
|
*/
|
|
30
|
+
import { hookCleanupComplete } from "./hook-outcome.mjs";
|
|
31
|
+
import { WORK_MODES, QUARANTINE_CLEANUP_VERSION, QUARANTINE_GIT_DEBT, capturedHomeCapabilities, identifiedHomeRecord, nonEmptyString, retireCleanupAdmission } from "./retire-admission.mjs";
|
|
32
|
+
export { WORK_MODES, QUARANTINE_CLEANUP_VERSION, QUARANTINE_GIT_DEBT, capturedHomeCapabilities, identifiedHomeRecord } from "./retire-admission.mjs";
|
|
30
33
|
import { assertHostRunAdmission } from "./host-run-admission.mjs";
|
|
31
34
|
import { isLaunchEnvReference, referenceSource, referenceValue, fileReferenceRemedy, launchEnvHandoff, LAUNCH_ENV_HANDOFF } from "./launch-env.mjs";
|
|
32
35
|
import { canonicalHomePath, realPathOrNearest } from "./real-path.mjs";
|
|
@@ -95,6 +98,7 @@ import { systemTool } from "./system-tools.mjs";
|
|
|
95
98
|
import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
|
|
96
99
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
97
100
|
import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
|
|
101
|
+
import { PIN_FILE } from "./instance-pin.mjs";
|
|
98
102
|
import { SAME_WORK_FILE, writeSameWork } from "./instance-same-work.mjs";
|
|
99
103
|
import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
|
|
100
104
|
import { thisBoot } from "./session-seen.mjs";
|
|
@@ -106,7 +110,7 @@ import { PKG_ROOT } from "./version.mjs";
|
|
|
106
110
|
import { canonicalDeploymentPath } from "./deployment-path.mjs";
|
|
107
111
|
import { INSTANCE_NAME_RE, RESERVED, capabilityAgentDirs, enclosingInstanceHome, findInstanceHomes, listAgents, logicalCwd, readSoul, soulOf, stripInternalAnnotations, withConfigFile, yamlKey } from "./soul-listing.mjs";
|
|
108
112
|
import { RETIRE_BASELINE_VERSION, authorityMismatch, findRetirementBaseline, inspectInstanceSession, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, retirementBaselinePath, runtimeAuthorityOf, tmuxEndpointAgrees } from "./session-inspect.mjs";
|
|
109
|
-
import { CLAIM_VERBS, DEFAULT_TMUX_SESSION, LAUNCH_RECIPE_VERSION, claimAction, completionLiveness, defaultTmuxWindows, deferredRetireResultPath, directoryRollbackPath, hostProcesses, isCapturedHome, lookupOnPath, missingSocketUnestablished, namedProcesses, parseLaunchCommand, procReadable, processesWorkingIn, readHomeRecord, readRetirePending, redactLaunchCommand, redactLaunchRecipe, retireCarried, retireClaimPath, retirePendingMarkerPath, retireStateOf, subdirs, tmuxFailure, tmuxOn, tmuxServerAbsence,
|
|
113
|
+
import { CLAIM_VERBS, DEFAULT_TMUX_SESSION, LAUNCH_RECIPE_VERSION, claimAction, completionLiveness, defaultTmuxWindows, deferredRetireResultPath, directoryRollbackPath, hostProcesses, isCapturedHome, lookupOnPath, missingSocketUnestablished, namedProcesses, parseLaunchCommand, procReadable, processesWorkingIn, readHomeRecord, readRetirePending, redactLaunchCommand, redactLaunchRecipe, retireCarried, retireClaimPath, retirePendingMarkerPath, retireStateOf, subdirs, tmuxFailure, tmuxOn, tmuxServerAbsence, upgradeHomeMeta, upgradeLaunchRecipe } from "./instance-listing.mjs";
|
|
110
114
|
import { LAYERS, PACKAGE_ID_RE } from "./package-catalog.mjs";
|
|
111
115
|
import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
|
|
112
116
|
import { workspaceOf } from "./agents-root.mjs";
|
|
@@ -122,9 +126,6 @@ export { OATS_VERSION, PKG_ROOT } from "./version.mjs";
|
|
|
122
126
|
export { oatsError } from "./errors.mjs";
|
|
123
127
|
export { copyTreeSafe } from "./tree-copy.mjs";
|
|
124
128
|
|
|
125
|
-
/** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
|
|
126
|
-
* must satisfy, so the retry cannot skip Git cleanup on an unrecognised value. */
|
|
127
|
-
export const WORK_MODES = ["worktree", "checkout", "attached", "workspace", "directory"];
|
|
128
129
|
/** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
|
|
129
130
|
* agent directory, whether or not it exists. */
|
|
130
131
|
export function instancesDirs(root) {
|
|
@@ -2645,23 +2646,6 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
|
|
|
2645
2646
|
return found.filter((x) => (seen.has(x.identity) ? false : seen.add(x.identity))).sort((a, b) => a.identity.localeCompare(b.identity));
|
|
2646
2647
|
}
|
|
2647
2648
|
|
|
2648
|
-
/** The refusal of a lifecycle verb (retire, stop, session start) for a home whose record is there
|
|
2649
|
-
* and cannot be read: E_UNIDENTIFIED_INSTANCE_HOME, with the file, the reason, `nothing` (what the
|
|
2650
|
-
* verb had done by then: nothing; a spawn that names the home says "nothing was spawned") and the
|
|
2651
|
-
* one remedy that exists. Every caller raises it before any effect: a client reads this code from
|
|
2652
|
-
* a stop or a retire as "refused, nothing happened". `--force` does not apply to it: it removes a
|
|
2653
|
-
* home that has NO record, never, blind, one whose record cannot be read. */
|
|
2654
|
-
function unreadableRecordRefusal(record, nothing = "nothing was done") {
|
|
2655
|
-
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.`);
|
|
2656
|
-
}
|
|
2657
|
-
/** The one check a lifecycle verb makes when it has resolved its home, before it takes a claim or
|
|
2658
|
-
* reads anything of the home: a record that cannot be read refuses the verb (unreadableRecordRefusal).
|
|
2659
|
-
* → the record as read (readHomeRecord), a record or an absent one. */
|
|
2660
|
-
export function identifiedHomeRecord(home, nothing) {
|
|
2661
|
-
const record = readHomeRecord(home);
|
|
2662
|
-
if (record.state === "unreadable") throw unreadableRecordRefusal(record, nothing);
|
|
2663
|
-
return record;
|
|
2664
|
-
}
|
|
2665
2649
|
const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
|
|
2666
2650
|
/** The fixed prompt a codex launch starts with: it names the task file, never its text (argv is
|
|
2667
2651
|
* readable by every local user). Codex reads the file with a tool. */
|
|
@@ -4687,7 +4671,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4687
4671
|
// must not be announced as clean while the local key that could delete it
|
|
4688
4672
|
// is about to be removed.
|
|
4689
4673
|
for (const [capId, m] of Object.entries(comp.meta || {})) {
|
|
4690
|
-
if (m
|
|
4674
|
+
if (!hookCleanupComplete(m)) {
|
|
4691
4675
|
incomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
|
|
4692
4676
|
outstandingHooks.add(capId);
|
|
4693
4677
|
}
|
|
@@ -5154,20 +5138,6 @@ export function findInstanceHome(root, name) {
|
|
|
5154
5138
|
}
|
|
5155
5139
|
|
|
5156
5140
|
|
|
5157
|
-
/** The quarantine cleanup-descriptor contract version. Bump when the shape the
|
|
5158
|
-
* retry consumes changes, so an older/newer marker fails closed instead of
|
|
5159
|
-
* driving a retry that cannot do what it claims.
|
|
5160
|
-
*
|
|
5161
|
-
* The rule applies from the first RELEASE of this shape onward. Markers are only
|
|
5162
|
-
* ever written when a `required` spawn hook fails, and required hooks do not
|
|
5163
|
-
* exist in any released kernel — so no deployment can hold a marker of an earlier
|
|
5164
|
-
* v1 shape, and there is nothing to migrate from. A migration path for a file
|
|
5165
|
-
* that has never existed would be dead code claiming to protect real data. */
|
|
5166
|
-
export const QUARANTINE_CLEANUP_VERSION = 1;
|
|
5167
|
-
/** The rollback-owned Git steps a quarantine can still owe. */
|
|
5168
|
-
export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
|
|
5169
|
-
|
|
5170
|
-
|
|
5171
5141
|
function assertDirectoryHome(home, canonicalHome = realPathOrNearest(home)) {
|
|
5172
5142
|
let st;
|
|
5173
5143
|
try { st = lstatSync(home); } catch { /* fail closed below */ }
|
|
@@ -5379,43 +5349,6 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
|
|
|
5379
5349
|
return ` — rollback INCOMPLETE. The instance home is RETAINED at ${home} because it holds the state needed to finish cleanup; it is not a live instance. Retry with \`oats retire ${instance}\`, then remove it once cleanup succeeds. Outstanding: ${incomplete.join("; ")}`;
|
|
5380
5350
|
}
|
|
5381
5351
|
|
|
5382
|
-
function nonEmptyString(v) { return typeof v === "string" && !!v.trim(); }
|
|
5383
|
-
function usableCleanupDescriptor(marker) {
|
|
5384
|
-
const c = marker?.cleanup;
|
|
5385
|
-
if (!isPlainObject(c)) return false;
|
|
5386
|
-
if (c.version !== QUARANTINE_CLEANUP_VERSION) return false;
|
|
5387
|
-
if (!nonEmptyString(c.repo)) return false;
|
|
5388
|
-
if (!WORK_MODES.includes(c.work)) return false;
|
|
5389
|
-
if (c.work === "worktree" && !nonEmptyString(c.branch)) return false;
|
|
5390
|
-
if (c.branch !== undefined && !nonEmptyString(c.branch)) return false;
|
|
5391
|
-
if (c.capabilityMeta !== undefined && !isPlainObject(c.capabilityMeta)) return false;
|
|
5392
|
-
const directoryDebt = c.outstanding?.directory === true && c.work === "directory";
|
|
5393
|
-
if (c.outstanding?.directory !== undefined && !directoryDebt) return false;
|
|
5394
|
-
// A worktree directory whose git admin entry is gone (awebai/oats#444) is debt too: the retry proves it
|
|
5395
|
-
// cleared when the directory is no longer there or has its admin entry back.
|
|
5396
|
-
const orphanDebt = c.outstanding?.orphanedWork === true && c.work === "worktree";
|
|
5397
|
-
if (c.outstanding?.orphanedWork !== undefined && !orphanDebt) return false;
|
|
5398
|
-
if (!Array.isArray(c.capabilityRuntime) || (!c.capabilityRuntime.length && !directoryDebt && !orphanDebt)) return false;
|
|
5399
|
-
if (!c.capabilityRuntime.every((cap) => isPlainObject(cap) && nonEmptyString(cap.id))) return false;
|
|
5400
|
-
if (!isPlainObject(c.outstanding) || !Array.isArray(c.outstanding.hooks) || !Array.isArray(c.outstanding.git)) return false;
|
|
5401
|
-
if (!c.outstanding.hooks.every(nonEmptyString)) return false;
|
|
5402
|
-
if (!c.outstanding.git.every((g) => QUARANTINE_GIT_DEBT.includes(g))) return false;
|
|
5403
|
-
// Git debt only exists where the rollback owns Git steps, so claiming it in any
|
|
5404
|
-
// other work mode describes a quarantine that could not have happened.
|
|
5405
|
-
if (c.outstanding.git.length && c.work !== "worktree") return false;
|
|
5406
|
-
// The decisive invariant: a quarantine with NOTHING outstanding is a proof
|
|
5407
|
-
// obligation of zero. Directory preservation is also real debt: the retry's
|
|
5408
|
-
// independent-authority inspection and verified snapshots must succeed even
|
|
5409
|
-
// when no capability has a retire hook. It is never a Git/shared-work escape.
|
|
5410
|
-
if (!c.outstanding.hooks.length && !c.outstanding.git.length && !directoryDebt && !orphanDebt) return false;
|
|
5411
|
-
// The retry must be ABLE to rerun what it must prove: an outstanding hook whose
|
|
5412
|
-
// capability is not in the set could never run, so the quarantine would never
|
|
5413
|
-
// clear — and the home would be unremovable without --force.
|
|
5414
|
-
const known = new Set(c.capabilityRuntime.map((cap) => cap.id));
|
|
5415
|
-
if (!c.outstanding.hooks.every((id) => known.has(id))) return false;
|
|
5416
|
-
return true;
|
|
5417
|
-
}
|
|
5418
|
-
|
|
5419
5352
|
/** The version of the stored digests a spawn baseline is written with (fingerprintTrees,
|
|
5420
5353
|
* generatedWorkDigest); a baseline without `digestVersion` holds the legacy ones, 1. */
|
|
5421
5354
|
const BASELINE_DIGEST_VERSION = 2;
|
|
@@ -5542,13 +5475,14 @@ function retireGitProbe(repo, args, { encoding } = {}) {
|
|
|
5542
5475
|
* as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
|
|
5543
5476
|
* KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
|
|
5544
5477
|
// `.oats-color.json` (feature instance-color) and `.oats-background.json` (feature instance-background) are
|
|
5545
|
-
// presentation anyone may change at any time: never work.
|
|
5478
|
+
// presentation anyone may change at any time: never work. `.oats-pinned.json` (feature instance-pin) is
|
|
5479
|
+
// presentation of the same kind.
|
|
5546
5480
|
// `.oats-same-work.json` (feature instance-same-work) is kernel presentation of the same kind.
|
|
5547
5481
|
// `.oats-start-exited` (lib/session-end.mjs) is the window's record of how the harness ended: every
|
|
5548
5482
|
// launched home whose harness ever ended holds it.
|
|
5549
5483
|
// `.oats-start-env.json` and its key (lib/start-env.mjs) are written at every start that renders a
|
|
5550
5484
|
// recipe, after the spawn's baseline: every launched home holds them.
|
|
5551
|
-
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5485
|
+
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
|
|
5552
5486
|
// `instance.json.tmp-<pid>` is what a process killed between the two steps of writeJsonAtomic leaves
|
|
5553
5487
|
// of the record: not a hidden name, so a capability cannot declare it (disposableHomeRootProblem).
|
|
5554
5488
|
const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/, /^instance\.json\.tmp-\d+$/, START_ENV_TMP, LAUNCH_ENV_HANDOFF];
|
|
@@ -6914,14 +6848,7 @@ export function isWorkspaceHome(meta) {
|
|
|
6914
6848
|
}
|
|
6915
6849
|
/** The refusal for a captured home: E_UNSUPPORTED_MODE (lead decisions on (e), D1). */
|
|
6916
6850
|
export function capturedHomeRefusal(home, what) {
|
|
6917
|
-
return Object.assign(oatsError("E_UNSUPPORTED_MODE", `${home} is a captured home (0.24–0.25; the captured/portable path was removed in 0.26): it has no 0.26 runtime —
|
|
6918
|
-
}
|
|
6919
|
-
/** The capabilities whose spawn hooks ran in a captured home (its identities, memberships):
|
|
6920
|
-
* retire cannot run their captured retire hooks, so it names them. */
|
|
6921
|
-
export function capturedHomeCapabilities(meta) {
|
|
6922
|
-
const order = Array.isArray(meta?.captured?.hookOrder) ? meta.captured.hookOrder.filter((id) => typeof id === "string") : [];
|
|
6923
|
-
const withMeta = meta?.capabilityMeta && typeof meta.capabilityMeta === "object" ? Object.keys(meta.capabilityMeta) : [];
|
|
6924
|
-
return [...new Set([...order, ...withMeta])].sort();
|
|
6851
|
+
return Object.assign(oatsError("E_UNSUPPORTED_MODE", `${home} is a captured home (0.24–0.25; the captured/portable path was removed in 0.26): it has no 0.26 runtime — inspect and clean up external state; a captured home without proof that no spawn hook ran needs \`oats retire ${basename(home)} --force\`; then re-spawn from the deployment; ${what}`), { details: { home, captured: true } });
|
|
6925
6852
|
}
|
|
6926
6853
|
/** The refusal for a home an earlier (0.25) kernel spawned: E_UNSUPPORTED_MODE. */
|
|
6927
6854
|
export function preWorkspaceHome(home, what) {
|
|
@@ -9243,7 +9170,7 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
|
|
|
9243
9170
|
instance: name, agent: found.agent.name, root: resolve(root),
|
|
9244
9171
|
requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
|
|
9245
9172
|
// A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
|
|
9246
|
-
options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
|
|
9173
|
+
options: { home: found.home, ...(o.force ? { force: true } : {}), ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
|
|
9247
9174
|
// The recorded children as they were when the retirement was scheduled: the completion stops them first.
|
|
9248
9175
|
...(Array.isArray(o.children) ? { children: o.children.map((c) => ({ instance: c.instance, home: c.home })) } : {}) }, resultPath,
|
|
9249
9176
|
};
|
|
@@ -9451,9 +9378,9 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
9451
9378
|
if (!written.ok) console.error(`deferred retirement of ${intent.instance}: its retire-refused event could not be written: ${written.reason ?? (written.results ?? []).map((r) => `${r.path}: ${r.reason}`).join("; ")}`);
|
|
9452
9379
|
return false;
|
|
9453
9380
|
};
|
|
9454
|
-
const retry = `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}`;
|
|
9381
|
+
const retry = `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}${intent.options?.force ? " --force" : ""}`;
|
|
9455
9382
|
const retireOnce = (underClaim) => retireInstance(intent.root, intent.instance, {
|
|
9456
|
-
home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
|
|
9383
|
+
home: intent.options?.home, keepDir: !!intent.options?.keepDir, force: !!intent.options?.force, tmuxSession: intent.options?.tmuxSession,
|
|
9457
9384
|
...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
|
|
9458
9385
|
...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
|
|
9459
9386
|
...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
|
|
@@ -9632,7 +9559,7 @@ const claimCommand = (action) => action === "resume" ? "oats session start --res
|
|
|
9632
9559
|
/** What each verb that meets a held claim says it did not do: the words its refusals end with,
|
|
9633
9560
|
* before any effect. After a takeover ended a dead holder's step, every verb says the same
|
|
9634
9561
|
* (lib/errors.mjs nothingAfter). */
|
|
9635
|
-
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed" };
|
|
9562
|
+
const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
|
|
9636
9563
|
|
|
9637
9564
|
/** The refusals of `arriving` ("retire", "stop", "upgrade", "resume", "start", or "worktree add", which
|
|
9638
9565
|
* reads the claim and does not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
|
|
@@ -10019,62 +9946,13 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10019
9946
|
// retirement is deferred to a detached external completion (below); with
|
|
10020
9947
|
// --keep-dir the old in-process path runs and kills the window LAST.
|
|
10021
9948
|
const self = o.self === true;
|
|
10022
|
-
const metaPath = join(found.home, "instance.json");
|
|
10023
9949
|
// A QUARANTINED home (spawn failed after a required hook and compensation did
|
|
10024
9950
|
// not finish) has no instance.json — it never got that far. Its marker carries
|
|
10025
9951
|
// the cleanup descriptor in the same shape, so retire can rerun compensation
|
|
10026
9952
|
// instead of silently skipping every hook and deleting the credentials.
|
|
10027
|
-
const
|
|
10028
|
-
const
|
|
10029
|
-
let
|
|
10030
|
-
let markerUnusable = false;
|
|
10031
|
-
let rawMarker;
|
|
10032
|
-
// A marker means the home is quarantined, WHETHER OR NOT instance.json exists:
|
|
10033
|
-
// the post-launch rollback retains a home that already has one, and gating on
|
|
10034
|
-
// its absence meant that quarantine was silently ignored — retire took the
|
|
10035
|
-
// ordinary path, where hook failures do not retain, and deleted the credential
|
|
10036
|
-
// while the external state survived (reviewer-final0130bc8).
|
|
10037
|
-
if (existsSync(quarantinePath)) {
|
|
10038
|
-
// A marker without a USABLE cleanup descriptor is NOT a quarantine we can
|
|
10039
|
-
// retry — it is an unidentified home. Treating an unusable one as retryable
|
|
10040
|
-
// made --force unable to ever clear it: the retry could not run, so the home
|
|
10041
|
-
// was retained again, forever (reviewer-adff009). "Parses as JSON" is not
|
|
10042
|
-
// the bar; "can actually drive the retry" is, so the shape is checked
|
|
10043
|
-
// against what the retry below consumes (reviewer-45ff039r2).
|
|
10044
|
-
try {
|
|
10045
|
-
const parsed = JSON.parse(readFileSync(quarantinePath, "utf8"));
|
|
10046
|
-
rawMarker = parsed;
|
|
10047
|
-
if (isPlainObject(parsed) && usableCleanupDescriptor(parsed)) quarantine = parsed;
|
|
10048
|
-
else markerUnusable = true;
|
|
10049
|
-
} catch { markerUnusable = true; }
|
|
10050
|
-
}
|
|
10051
|
-
// #796: a marker a spawn wrote before its spawn or worktree hooks (`inProgress`). While that spawn's
|
|
10052
|
-
// process is verifiably alive it is a spawn in progress, never a quarantine to retry, --force
|
|
10053
|
-
// included. Once it is gone, the hook group it left is ended when its leader is alive at the
|
|
10054
|
-
// recorded start time; a group whose leader is gone is never signalled, only reported (its id may
|
|
10055
|
-
// be another group's by now). The retry below completes the rollback from the marker like any other.
|
|
10056
|
-
// Whether that process still runs may also be unreadable (no procfs and `ps` failing): that is never
|
|
10057
|
-
// taken for gone. Retire refuses it, naming the recorded pid and start for a check by hand, and the
|
|
10058
|
-
// existing forced path (`--force`) is the way out; a forced retry then keeps the spawn's branch.
|
|
10059
|
-
// The same holds for a hook group with members whose leader's start cannot be read.
|
|
10060
|
-
const spawnGroupWarnings = [];
|
|
10061
|
-
let inProgressUnverified = false;
|
|
10062
|
-
if (isPlainObject(rawMarker?.inProgress)) {
|
|
10063
|
-
const p = rawMarker.inProgress;
|
|
10064
|
-
const live = processLiveness(p);
|
|
10065
|
-
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");
|
|
10066
|
-
if (live.state === "unknown") {
|
|
10067
|
-
if (!o.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`,
|
|
10068
|
-
`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` });
|
|
10069
|
-
inProgressUnverified = true;
|
|
10070
|
-
spawnGroupWarnings.push(`retired with --force although whether its spawn (pid ${p.pid}) still runs could not be read (${live.reason}); its branch is kept`);
|
|
10071
|
-
}
|
|
10072
|
-
}
|
|
10073
|
-
// The retire's own read of the record, with the same reader as the resolution: one that became
|
|
10074
|
-
// unreadable since then refuses as there. It comes before the first signal a retire can send
|
|
10075
|
-
// (below), so that E_UNIDENTIFIED_INSTANCE_HOME for an unreadable record is only ever answered
|
|
10076
|
-
// while nothing was done: `reached` is untouched ("before-effects").
|
|
10077
|
-
const liveMeta = identifiedHomeRecord(found.home).meta;
|
|
9953
|
+
const admission = retireCleanupAdmission(found.home, name, o, instanceWork);
|
|
9954
|
+
const { meta, liveMeta, workIs, repoFromGit, hookRepo, directoryFallbackPath, quarantinePath, quarantine, hooksKnown, spawnGroupWarnings } = admission;
|
|
9955
|
+
let inProgressUnverified = admission.inProgressUnverified;
|
|
10078
9956
|
// What this retire did to the hook group an interrupted spawn left, when it signalled it. Ending
|
|
10079
9957
|
// that group is the first signal a retire can send: from that call on the retire is no longer
|
|
10080
9958
|
// "before-effects", and no answer says that nothing was stopped.
|
|
@@ -10102,53 +9980,9 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10102
9980
|
spawnGroupWarnings.push(`retired with --force although the worktree ${note}; its branch is kept`);
|
|
10103
9981
|
}
|
|
10104
9982
|
}
|
|
10105
|
-
// A quarantined home may carry an instance.json that is NOT the spawn record:
|
|
10106
|
-
// module materialization writes a pre-hook stub ({ modules, providers,
|
|
10107
|
-
// resolutionRevision }) before the spawn hooks run, and a required-hook
|
|
10108
|
-
// failure retains the home with that stub in place. Trusting it over the
|
|
10109
|
-
// cleanup descriptor left meta.repo undefined, so the retry never re-ran the
|
|
10110
|
-
// owed retire hook and reported "cleanup descriptor lost its context repo"
|
|
10111
|
-
// on every attempt — only --force could clear the home (found by an operator
|
|
10112
|
-
// rehearsal on 0.25.3). The descriptor is written FOR this retry; a live
|
|
10113
|
-
// record only wins when it is a complete spawn record (repo + work present).
|
|
10114
|
-
const liveIsSpawnRecord = !!liveMeta && nonEmptyString(liveMeta.repo) && WORK_MODES.includes(liveMeta.work);
|
|
10115
|
-
const meta = liveIsSpawnRecord || !quarantine ? (liveMeta || quarantine?.cleanup || {}) : { ...liveMeta, ...quarantine.cleanup };
|
|
10116
|
-
// Compensation metadata is the SPAWN's, from whichever record survived — never
|
|
10117
|
-
// a failed retry's report, which says nothing about what still needs undoing.
|
|
10118
|
-
if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;
|
|
10119
|
-
if (quarantine && typeof quarantine.cleanup.launched === "boolean") {
|
|
10120
|
-
meta.launched = quarantine.cleanup.launched;
|
|
10121
|
-
meta.tmux = quarantine.cleanup.tmux;
|
|
10122
|
-
meta.sessionTarget = quarantine.cleanup.sessionTarget;
|
|
10123
|
-
}
|
|
10124
|
-
// A home with NEITHER instance.json NOR a usable cleanup descriptor cannot be
|
|
10125
|
-
// retired safely: hooks would be skipped and the directory removed, which is
|
|
10126
|
-
// the credential deletion the quarantine exists to prevent — and the spawn
|
|
10127
|
-
// path tolerates a failed marker write, so this state is reachable. Fail
|
|
10128
|
-
// closed; `force` is the deliberate manual-cleanup escape.
|
|
10129
|
-
// A marker that cannot drive a retry is not "ignore me" — it is evidence that
|
|
10130
|
-
// cleanup was interrupted and OATS cannot tell what remains. Fail closed even
|
|
10131
|
-
// when instance.json is present; `--force` is the deliberate manual escape.
|
|
10132
|
-
if (markerUnusable && !o.force) {
|
|
10133
|
-
throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${found.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.`);
|
|
10134
|
-
}
|
|
10135
|
-
if (!existsSync(metaPath) && !quarantine && !o.force) {
|
|
10136
|
-
throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${found.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.`);
|
|
10137
|
-
}
|
|
10138
|
-
// The retire hooks run from the record: the repository they are run for (`repo`) and the
|
|
10139
|
-
// capabilities with their hooks (`capabilityRuntime`). A record with no repository runs none.
|
|
10140
|
-
// That is a retire with nothing left out only when the record says that no capability has a
|
|
10141
|
-
// retire hook. One that does not say (the stub lib/materialize.mjs writes, left by a spawn that
|
|
10142
|
-
// was killed before its record and wrote no marker before its hooks) may stand for an identity
|
|
10143
|
-
// registered outside the home: removing the home would leave it there with nothing that knows
|
|
10144
|
-
// of it. Fail closed, as for a home with no record; `--force` is the same deliberate escape.
|
|
10145
|
-
if (!o.force && !nonEmptyString(meta.repo) && !(Array.isArray(meta.capabilityRuntime) && !meta.capabilityRuntime.some((cap) => cap?.hooks?.retire))) {
|
|
10146
|
-
throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${metaPath} records neither a repository nor its capabilities' hooks (a spawn that was interrupted before it wrote its record leaves such a file), so OATS cannot tell which retire hooks to run, and what the spawn's hooks registered outside the home (an identity, a seat) may still be there. Retiring it would remove the home without running any of them. Nothing was stopped, run or removed. Inspect the home, clean up by hand what its capabilities registered, then remove it with \`oats retire ${name} --force\`.`);
|
|
10147
|
-
}
|
|
10148
9983
|
|
|
10149
9984
|
const workPath = join(found.home, "work");
|
|
10150
|
-
//
|
|
10151
|
-
const workIs = instanceWork(found.home, meta);
|
|
9985
|
+
// Admission read work/ with the same instanceWork reader as the plan (#962).
|
|
10152
9986
|
const directoryMode = workIs.is === "directory-mode";
|
|
10153
9987
|
// A real directory that is not the instance's own tree is bytes of the home: inspected, copied to
|
|
10154
9988
|
// recovery and checked as a directory instance's work is, and removed with the home. It never
|
|
@@ -10164,8 +9998,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10164
9998
|
// is the one Git names for the tree. A directory of the home is no worktree, whatever it holds,
|
|
10165
9999
|
// and neither is a link, under a record that says `worktree` too: every step that asks whether
|
|
10166
10000
|
// this home is a worktree's (the recovery's writers, the rollback retry) asks this record.
|
|
10167
|
-
const
|
|
10168
|
-
const workMeta = workIs.is === "own-tree" ? { ...meta, work: "worktree", repo: meta.repo || repoFromGit }
|
|
10001
|
+
const workMeta = workIs.is === "own-tree" ? { ...meta, work: "worktree", repo: hookRepo }
|
|
10169
10002
|
: homeDirectory || link ? { ...meta, work: undefined } : meta;
|
|
10170
10003
|
// A live harness cannot establish a stable final work inspection of itself,
|
|
10171
10004
|
// so self-retire never inspects, runs hooks, or removes anything here. It
|
|
@@ -10356,11 +10189,11 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10356
10189
|
// e.g. aweb signing keys) is removed. The knowledge integration harvests notes/ here;
|
|
10357
10190
|
// the kernel itself is memory-agnostic.
|
|
10358
10191
|
let hookResults;
|
|
10359
|
-
if (meta
|
|
10192
|
+
if (hookRepo && !isCapturedHome(meta)) {
|
|
10360
10193
|
// The hooks this home recorded at spawn. A home an earlier kernel spawned
|
|
10361
|
-
// without them
|
|
10362
|
-
//
|
|
10363
|
-
const resolved = { ...resolvedFromHome(found.home, meta), capabilities:
|
|
10194
|
+
// without them needs explicit --force (retireCleanupAdmission); a captured
|
|
10195
|
+
// home cannot run its hooks. Neither path infers cleanup from missing data.
|
|
10196
|
+
const resolved = { ...resolvedFromHome(found.home, meta), capabilities: hooksKnown ? meta.capabilityRuntime : [] };
|
|
10364
10197
|
// The soul this home was spawned from, as recorded (a workspace home records its
|
|
10365
10198
|
// per-commit directory; agents/<name>/soul may since point elsewhere) — the same
|
|
10366
10199
|
// value spawn's hook saw.
|
|
@@ -10384,7 +10217,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10384
10217
|
home: found.home, instance: name, agentName: found.agent.name,
|
|
10385
10218
|
soulDir: instanceSoulDir(found.home, meta) || found.agent._soulDir || join(found.agent._dir, "soul"),
|
|
10386
10219
|
...(nonEmptyString(meta.soulId) ? { soulId: meta.soulId } : {}),
|
|
10387
|
-
contextDir:
|
|
10220
|
+
contextDir: hookRepo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
|
|
10388
10221
|
finished, onFinished: (capability, answered) => { ended.push({ capability, ...(isPlainObject(answered) ? { meta: answered } : {}) }); recordEnded(); },
|
|
10389
10222
|
});
|
|
10390
10223
|
// The hooks ran: their warnings are events now, whatever the retire does
|
|
@@ -10414,7 +10247,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10414
10247
|
// A hook may exit 0 and still report it did not finish. Only an explicit
|
|
10415
10248
|
// "nothing to undo" counts as complete — same rule the rollback path uses.
|
|
10416
10249
|
for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
|
|
10417
|
-
if (m
|
|
10250
|
+
if (!hookCleanupComplete(m)) {
|
|
10418
10251
|
ordinaryIncomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
|
|
10419
10252
|
}
|
|
10420
10253
|
}
|
|
@@ -10429,7 +10262,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10429
10262
|
if (quarantine) {
|
|
10430
10263
|
for (const f of hookResults?.failures || []) retryFailures.push(`retire hook ${f.capability}: ${f.message}`);
|
|
10431
10264
|
for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
|
|
10432
|
-
if (m
|
|
10265
|
+
if (!hookCleanupComplete(m)) {
|
|
10433
10266
|
retryFailures.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""}`);
|
|
10434
10267
|
}
|
|
10435
10268
|
}
|
|
@@ -10762,7 +10595,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10762
10595
|
const outstandingHooks = new Set();
|
|
10763
10596
|
for (const f of hookResults?.failures || []) outstandingHooks.add(f.capability);
|
|
10764
10597
|
for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
|
|
10765
|
-
if (m
|
|
10598
|
+
if (!hookCleanupComplete(m)) outstandingHooks.add(capId);
|
|
10766
10599
|
}
|
|
10767
10600
|
// What the writer adds to the items is debt of its own: a descriptor kept outside the home, or
|
|
10768
10601
|
// one that could not be stored, owes a restoration no rerun of the hooks makes.
|
|
@@ -10928,12 +10761,17 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10928
10761
|
if (linkLed) w.push(`${workPath} was a link though the record says work mode worktree: nothing was retained or removed as a work tree, and ${linkLed.path === null ? "it led nowhere that could be read" : `what it led to (${linkLed.path}) was not touched`}`);
|
|
10929
10762
|
if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
|
|
10930
10763
|
if (isCapturedHome(meta) && !quarantine) {
|
|
10931
|
-
// A captured home
|
|
10932
|
-
//
|
|
10764
|
+
// A captured home cannot run its pre-0.26 hooks. A forced removal names
|
|
10765
|
+
// each capability whose spawn hook ran, with the state it did not revoke.
|
|
10933
10766
|
const caps = capturedHomeCapabilities(meta);
|
|
10934
10767
|
for (const cap of caps) w.push(`${cap}: its retire hook did NOT run (captured home; the captured/portable path was removed in 0.26) — identities/memberships it created are not revoked; remove them with the provider's own tooling`);
|
|
10935
|
-
if (!caps.length) w.push("captured home: no retire hook ran (the captured/portable path was removed in 0.26) — any identities/memberships its capabilities created are not revoked; remove them with the provider's own tooling");
|
|
10936
|
-
} else if (!
|
|
10768
|
+
if (!caps.length && o.force) w.push("captured home: no retire hook ran (the captured/portable path was removed in 0.26) — any identities/memberships its capabilities created are not revoked; remove them with the provider's own tooling");
|
|
10769
|
+
} else if (!hooksKnown && !quarantine) {
|
|
10770
|
+
if (meta.capabilityRuntime === undefined) w.push("this home records no capability hooks (an earlier kernel spawned it): no retire hook ran; any external state its capabilities created is the operator's to clean up");
|
|
10771
|
+
else w.push("this home's recorded capability hooks cannot be identified: no retire hook ran; any identities/memberships its capabilities created are not revoked; remove them with the provider's own tooling");
|
|
10772
|
+
} else if (!nonEmptyString(hookRepo) && hooksKnown && o.force && !quarantine) {
|
|
10773
|
+
for (const cap of meta.capabilityRuntime.filter(cap => cap.hooks?.retire)) w.push(`${cap.id}: its retire hook did NOT run (no context repository) — identities/memberships it created are not revoked; remove them with the provider's own tooling`);
|
|
10774
|
+
}
|
|
10937
10775
|
return w.length ? w : undefined;
|
|
10938
10776
|
})() };
|
|
10939
10777
|
result[RETIRE_SELECTED_HOME] = found.home;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// The lifecycle cleanup vocabulary belongs to the kernel (docs/capabilities.md).
|
|
2
|
+
// Missing metadata makes no claim of incomplete cleanup. An explicit refusal
|
|
3
|
+
// is complete only for the documented idempotent "nothing to delete" outcome.
|
|
4
|
+
export function hookCleanupComplete(meta) {
|
|
5
|
+
return !(meta && typeof meta === 'object' && meta.retired === false && meta.reason !== 'nothing-to-delete');
|
|
6
|
+
}
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -30,6 +30,7 @@ import { readLockIfPresent } from "./packages.mjs";
|
|
|
30
30
|
import { composeSoulInstructions } from "./soul-composition.mjs";
|
|
31
31
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
32
32
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
33
|
+
import { readInstancePin } from "./instance-pin.mjs";
|
|
33
34
|
/** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
|
|
34
35
|
const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
|
|
35
36
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
@@ -543,6 +544,8 @@ export function inspectDocument(t, { kernel }) {
|
|
|
543
544
|
color: readInstanceColor(t.home),
|
|
544
545
|
// Feature instance-background: `true` while the home holds a valid record, absent otherwise (as on a row).
|
|
545
546
|
...(readInstanceBackground(t.home) ? { background: true } : {}),
|
|
547
|
+
// Feature instance-pin: `true` while the home holds a valid pin, absent otherwise (as on a row).
|
|
548
|
+
...(readInstancePin(t.home) ? { pinned: true } : {}),
|
|
546
549
|
resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
|
|
547
550
|
...(m ? { identity: servedIdentityOf(m) } : {}),
|
|
548
551
|
problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.skillsProblems || []), ...(t.composedSkillsProblems || []), ...(t.discoveryError ? [t.discoveryError] : []),
|
|
@@ -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";
|
|
@@ -19,6 +20,7 @@ import { afterFirstEffect, isAnswerCode, kernelCode, lifecycleBusy, oatsError, r
|
|
|
19
20
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
20
21
|
import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
|
|
21
22
|
import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
|
|
23
|
+
import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
|
|
22
24
|
import { sameWorkOf, writeSameWork } from "./instance-same-work.mjs";
|
|
23
25
|
import { resolveInstance } from "./instance-address.mjs";
|
|
24
26
|
export { resolveInstance } from "./instance-address.mjs";
|
|
@@ -93,6 +95,21 @@ export function setInstanceBackground(ctx, root, name, { home, background }) {
|
|
|
93
95
|
return { instanceBackgroundApi: INSTANCE_BACKGROUND_API, instance: name, home: me.home, background, changed };
|
|
94
96
|
}
|
|
95
97
|
|
|
98
|
+
/** `oats instance pin <instance> on|off` (feature instance-pin): pin the home `name` resolves to at the top of
|
|
99
|
+
* its machine's list, or remove its pin, with the authority and the refusals of `instance background` above
|
|
100
|
+
* (setInstanceBackground), a stopped home included. The pin is the home's, so every viewer of the machine
|
|
101
|
+
* sees it. `pinned` is a boolean; the caller refused anything else.
|
|
102
|
+
* → `{ instancePinApi, instance, home, pinned, changed }`. */
|
|
103
|
+
export function setInstancePin(ctx, root, name, { home, pinned }) {
|
|
104
|
+
if (typeof pinned !== "boolean") throw oatsError("E_BAD_ARGS", "pinned must be on or off");
|
|
105
|
+
const me = resolveTarget(ctx, root, name, { home });
|
|
106
|
+
if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the pin was not changed`);
|
|
107
|
+
if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the pin was not changed`);
|
|
108
|
+
refuseBesideRetire("instance pin", me.home);
|
|
109
|
+
const { changed } = writeInstancePin(me.home, pinned);
|
|
110
|
+
return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
|
|
111
|
+
}
|
|
112
|
+
|
|
96
113
|
/** `oats instance same-work <instance> on|off` (feature instance-same-work, awebai/oats#1577): bind the flag
|
|
97
114
|
* of the home `name` resolves to to its recorded parent (`on`), or remove it (`off`). Addressed, and refused
|
|
98
115
|
* beside a retire or in a quarantined home, exactly as setInstanceColor is. `on` needs a recorded
|
|
@@ -478,8 +495,9 @@ const PLAN_NOT_COPIED_CAP = 16;
|
|
|
478
495
|
* itself applies them: plain retire re-homes the worktree; --discard-worktree
|
|
479
496
|
* is the dialog's opt-in. No retire deletes a branch: `deleteBranch` is
|
|
480
497
|
* always false. */
|
|
481
|
-
export function planRetire(ctx, root, name, { home } = {}) {
|
|
498
|
+
export function planRetire(ctx, root, name, { home, force = false } = {}) {
|
|
482
499
|
const me = resolveTarget(ctx, root, name, { home });
|
|
500
|
+
retireCleanupAdmission(me.home, name, { force }, instanceWork);
|
|
483
501
|
const kids = descendantsOf(me.root, name);
|
|
484
502
|
// Read once, after the lineage: every fact of the plan that the record gives is of this read.
|
|
485
503
|
const recorded = targetRecord(me.home);
|