@awebai/oats 0.69.18 → 0.69.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +27 -14
  3. package/docs/container.md +416 -43
  4. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  5. package/docs/design/2026-09-28-automations-trust.md +1 -1
  6. package/docs/desktop-cli-api.md +52 -31
  7. package/docs/desktop.md +29 -6
  8. package/docs/execution-targets.md +32 -17
  9. package/docs/implementation.md +4 -3
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +6 -4
  15. package/docs/release-notes/v0.69.19.md +172 -0
  16. package/docs/release-notes/v0.69.20.md +325 -0
  17. package/docs/servers.md +6 -4
  18. package/docs/souls-and-instances.md +37 -13
  19. package/docs/tui.md +8 -8
  20. package/docs/upgrading.md +17 -5
  21. package/docs/workspaces.md +13 -7
  22. package/injects/work-directory.md +27 -2
  23. package/injects/work-workspace.md +32 -6
  24. package/lib/core.mjs +33 -197
  25. package/lib/hook-outcome.mjs +6 -0
  26. package/lib/host-run.mjs +24 -19
  27. package/lib/instance-lifecycle.mjs +3 -1
  28. package/lib/instance-listing.mjs +3 -2
  29. package/lib/launch-prompt-fixtures/README.md +6 -0
  30. package/lib/retire-admission.mjs +215 -0
  31. package/lib/servers.mjs +3 -0
  32. package/lib/session-resume-contract.mjs +1 -1
  33. package/lib/session-resume.mjs +130 -47
  34. package/lib/session-seen.mjs +3 -3
  35. package/package-catalog.json +3 -3
  36. package/package.json +3 -1
  37. package/packages/client/attributed-human.mjs +13 -0
  38. package/packages/client/deployment-data.mjs +4 -0
  39. package/packages/client/deployment-panel.mjs +2 -0
  40. package/packages/client/instance-lifecycle.mjs +6 -4
  41. package/packages/client/instance-presentation.mjs +2 -2
  42. package/packages/client/instance-tree.mjs +18 -7
  43. package/packages/client/lifecycle-confirmation.mjs +4 -2
  44. package/packages/client/lifecycle-contract.mjs +11 -6
  45. package/packages/client/remote-roster.mjs +4 -0
  46. package/packages/record/README.md +15 -2
  47. package/packages/record/docs/capture-service.md +14 -0
  48. package/packages/record/lib/canonical.mjs +2 -70
  49. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  50. package/packages/record/lib/capture-aw.mjs +11 -5
  51. package/packages/record/lib/capture-health.mjs +16 -5
  52. package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/tui.md CHANGED
@@ -176,12 +176,12 @@ while a terminal is open); under 80 columns it has the whole width.
176
176
  kernel reported that were withheld (a home outside its soul's directory,
177
177
  or one reported twice), `2 withheld`, when there are any.
178
178
  - **The list** is the roster the Desktop draws: the same groups in the same
179
- order, from the same code. It is in name order, by each group's top
180
- instance, so starting or stopping an instance moves nothing. An instance
179
+ order, from the same code. It is in spawn order, newest first, by each
180
+ group's top instance, so starting or stopping an instance moves nothing. An instance
181
181
  that others were spawned from has them indented under it, and keeps its
182
182
  place when it gains or loses one. Under one parent, the instances that do
183
183
  its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
184
- come first, then the others, each part in name order, as the Desktop lists
184
+ come first, then the others, each part newest first, as the Desktop lists
185
185
  them. An empty row stands between each run
186
186
  of instances related to no other and the group before or after it. The
187
187
  indent alone says which instance is under which: no mark is drawn for
@@ -974,7 +974,7 @@ selected.
974
974
  ```
975
975
  acme-platform │ dev
976
976
  acme-billing ● │ soul dev
977
- lfx │ state running
977
+ lab │ state running
978
978
  garnet │ harness claude, claude-opus-5-5 (so…
979
979
  +2 │ work worktree, agents/dev
980
980
  │ team eng
@@ -983,7 +983,7 @@ selected.
983
983
 
984
984
  The sidebar's first rows list the workspaces this run can show, one row a
985
985
  workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
986
- order: `lfx` is one row however many machines hold it, and a machine the
986
+ order: `lab` is one row however many machines hold it, and a machine the
987
987
  rules shared with the Desktop matched to no workspace is a row by its own
988
988
  name, in the same flat list. A row is one line: the name. With one
989
989
  workspace the list is its row.
@@ -1028,7 +1028,7 @@ workspace the list is its row.
1028
1028
  that list fills the sidebar, which then has no such row, does the line
1029
1029
  take a row, the list giving up its last. With the list's focus (`w`) the
1030
1030
  focus stays there, the cursor where it was. A workspace with a deployment of this
1031
- machine not opened yet (lfx, with `~/Work/lfx` on this computer's list)
1031
+ machine not opened yet (lab, with `~/Work/lab` on this computer's list)
1032
1032
  opens it first, as the switcher's `Enter` does. What the workspace left
1033
1033
  had open is kept for it, as for a switch from the
1034
1034
  switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
@@ -1068,9 +1068,9 @@ switcher covers the whole screen.
1068
1068
  workspaces │ > * acme-platform
1069
1069
  │ This machine
1070
1070
  Instances 1 │ garnet
1071
- Souls 2 │ lfx
1071
+ Souls 2 │ lab
1072
1072
  Capabilities 3 │ This machine · not opened
1073
- ────────────────────────────────────────────────│ athenea (lfx)
1073
+ ────────────────────────────────────────────────│ builder (lab)
1074
1074
  Ctrl+X commands │ Not matched to a workspace
1075
1075
  Ctrl+K palette │ basalt ssh needs a prompt
1076
1076
  Enter open │ On this machine, not opened
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.18** ([release notes](release-notes/v0.69.18.md)).
10
- The 0.69.18 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.69.20** ([release notes](release-notes/v0.69.20.md)).
10
+ The 0.69.20 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.18,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.20,** 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.18, in either order
24
- npm install -g @awebai/oats@0.69.18 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.20, in either order
24
+ npm install -g @awebai/oats@0.69.20 # 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.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
221
+ oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
222
+ recorded cleanup hooks cannot run is refused; clean up its external state,
223
+ then run `oats retire --force`. Team-container deployments
224
+ recreate their agent containers, and those with a local registry service set
225
+ `team.registryRoute: local`. Respawn instances to take the new texts.
226
+ - **[0.69.19](release-notes/v0.69.19.md#upgrade):** the catalog pins
227
+ oats.aweb 1.42.1 and oats.framework 1.25.2. A retained seat that relied on
228
+ `OATS_AWEB_URL` records its server with `aw workspace connect` and unsets the
229
+ variable; a non-boolean `identity.e2ee` or `identity.takeOver` is set to
230
+ `true` or `false`. Respawn instances to take the shorter aweb text and the
231
+ workspace and directory modes' extra trees.
220
232
  - **[0.69.18](release-notes/v0.69.18.md#upgrade):** from this Desktop on,
221
233
  the Desktop and the CLI go in either order (a Desktop of 0.69.17 or older
222
234
  still goes first); the catalog pins oats.aweb 1.41.0, oats.okf 6.0.3 and
@@ -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.25.0 # bare version → resolves through the official catalog
58
- oats.okf: v6.0.3
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-v3.1.3, adapted to OATS: `oats.engineering-expert`,
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 four of the build skills and the
433
- developer's quality floor adapt. `oats.build` holds the build skills, and every soul that
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; the
436
- landing rules point at the lane map, which stays the one home of OATS's lanes.
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
@@ -4,9 +4,34 @@ Your `./work` is an **instance-owned execution directory**, not a Git worktree,
4
4
  checkout or link. The `repo` recorded for you supplies configuration only; it
5
5
  grants no permission to edit the `repo` directory.
6
6
 
7
- - Work inside `./work`. **Never initialize a fake repository**; a containing
8
- repository Git discovers is not yours.
7
+ - Work inside `./work`, apart from your extra trees. **Never initialize a
8
+ fake repository**; a containing repository Git discovers is not yours.
9
+ - **Repository work that needs a branch goes in an extra tree of your own**
10
+ (below): a change your role and task call for, or a repository at the
11
+ remote's current state. What work you take on stays your role's and your
12
+ task's call.
9
13
  - Use external inputs and destinations only as your task and capabilities
10
14
  explicitly authorize.
11
15
  - Deliver results through your task's own protocol before you finish: the
12
16
  recovery copy kept at retirement is not publication.
17
+
18
+ ### Extra trees
19
+
20
+ For a branch of a member repository, from your home (`--preview` first;
21
+ `<repo>`: the member key or clone path, always, since your own `./work` is
22
+ not a Git tree; `<base>`: the remote branch to start from, or the one you
23
+ rework):
24
+
25
+ oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
26
+
27
+ It moves none of the clone's refs. A tree is yours alone: build, test and
28
+ commit there.
29
+
30
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
31
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
32
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
33
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
34
+ - Before you finish, merge each tree into your PR branch, or push it and name
35
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
36
+ Retirement may keep a tree with uncommitted work; don't rely on it.
37
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
@@ -1,11 +1,37 @@
1
1
  ## Work mode: workspace
2
2
 
3
- Your `./work` is the **whole workspace**, not one repository. You route,
4
- analyse and coordinate; you do not change code.
3
+ Your `./work` is the **whole workspace**, not one repository: every member
4
+ clone, read through it. What work you take on is your role's and your task's
5
+ call; this block says where it happens.
5
6
 
6
- - **Read freely across member repositories; never edit or commit inside them,
7
- and NEVER change their Git state** (no branch switches, resets, pulls,
8
- stashes or worktrees). Route a repository change to that repository's agents
9
- or to your human.
7
+ - **Read freely across member repositories through `./work`; never edit or
8
+ commit there, and NEVER change a member clone's Git state** (no branch
9
+ switches, resets, pulls, stashes, or `git worktree` run by hand). Others
10
+ use those clones.
11
+ - **Work that needs a branch goes in an extra tree of your own** (below): a
12
+ change your role and task call for, or a member at the remote's current
13
+ state. Otherwise route a repository change to that repository's agents or
14
+ to your human.
10
15
  - A capability that delivers updates into a repository follows its own
11
16
  instructions; that is not an exception you take yourself.
17
+
18
+ ### Extra trees
19
+
20
+ For a branch of a member repository, from your home (`--preview` first;
21
+ `<repo>`: the member key or clone path, always, since your own `./work` is
22
+ not a Git tree; `<base>`: the remote branch to start from, or the one you
23
+ rework):
24
+
25
+ oats worktree add --purpose <purpose> --branch <branch> --base <base> --repo <repo>
26
+
27
+ It moves none of the clone's refs. A tree is yours alone: build, test and
28
+ commit there.
29
+
30
+ - Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
31
+ (if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
32
+ - `add` may take minutes: use a long timeout; if killed, rerun it.
33
+ - Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
34
+ - Before you finish, merge each tree into your PR branch, or push it and name
35
+ it in your hand-back; then `oats worktree remove --purpose <purpose>`.
36
+ Retirement may keep a tree with uncommitted work; don't rely on it.
37
+ Details: `oats worktree --help`, and `/oats-operate` if you have it.
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";
@@ -106,7 +109,7 @@ import { PKG_ROOT } from "./version.mjs";
106
109
  import { canonicalDeploymentPath } from "./deployment-path.mjs";
107
110
  import { INSTANCE_NAME_RE, RESERVED, capabilityAgentDirs, enclosingInstanceHome, findInstanceHomes, listAgents, logicalCwd, readSoul, soulOf, stripInternalAnnotations, withConfigFile, yamlKey } from "./soul-listing.mjs";
108
111
  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, unreadableRecordSaid, upgradeHomeMeta, upgradeLaunchRecipe } from "./instance-listing.mjs";
112
+ 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
113
  import { LAYERS, PACKAGE_ID_RE } from "./package-catalog.mjs";
111
114
  import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
112
115
  import { workspaceOf } from "./agents-root.mjs";
@@ -122,9 +125,6 @@ export { OATS_VERSION, PKG_ROOT } from "./version.mjs";
122
125
  export { oatsError } from "./errors.mjs";
123
126
  export { copyTreeSafe } from "./tree-copy.mjs";
124
127
 
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
128
  /** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
129
129
  * agent directory, whether or not it exists. */
130
130
  export function instancesDirs(root) {
@@ -2645,23 +2645,6 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
2645
2645
  return found.filter((x) => (seen.has(x.identity) ? false : seen.add(x.identity))).sort((a, b) => a.identity.localeCompare(b.identity));
2646
2646
  }
2647
2647
 
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
2648
  const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
2666
2649
  /** The fixed prompt a codex launch starts with: it names the task file, never its text (argv is
2667
2650
  * readable by every local user). Codex reads the file with a tool. */
@@ -4687,7 +4670,7 @@ function* spawnBody(root, agent, o = {}) {
4687
4670
  // must not be announced as clean while the local key that could delete it
4688
4671
  // is about to be removed.
4689
4672
  for (const [capId, m] of Object.entries(comp.meta || {})) {
4690
- if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
4673
+ if (!hookCleanupComplete(m)) {
4691
4674
  incomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
4692
4675
  outstandingHooks.add(capId);
4693
4676
  }
@@ -4824,14 +4807,14 @@ function* spawnBody(root, agent, o = {}) {
4824
4807
  : work === "directory"
4825
4808
  ? `an instance-owned execution directory — not a Git worktree or a link to ${repoAbs}; that path supplies configuration only`
4826
4809
  : work === "workspace"
4827
- ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
4810
+ ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you never edit member clones there (see your work-mode briefing)`
4828
4811
  : `a symlink to the ${repoAbs} checkout — you share it; ${branch ? `work on the currently checked-out branch (${branch})` : `work on what is checked out (${noBranch})`} and do not switch branches without being asked`;
4829
4812
  writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
4830
4813
 
4831
4814
  You are instance "${instance}" of agent "${agent.name}".
4832
4815
  - Home: ${home}
4833
4816
  - Work tree: ./work — ${workDesc}
4834
- - Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
4817
+ - ${work === "workspace" ? "Read across the workspace in ./work; do repository work only in your extra trees." : work === "directory" ? "Work in ./work; do repository work only in your extra trees." : "Do all repository work inside ./work."} Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
4835
4818
  ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`, { mode: 0o600 }); // human text: the owner's only
4836
4819
  // Feature instance-background: the home's record, beside its other files, so the spawn's rollback
4837
4820
  // (which removes the home) leaves nothing of it.
@@ -5154,20 +5137,6 @@ export function findInstanceHome(root, name) {
5154
5137
  }
5155
5138
 
5156
5139
 
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
5140
  function assertDirectoryHome(home, canonicalHome = realPathOrNearest(home)) {
5172
5141
  let st;
5173
5142
  try { st = lstatSync(home); } catch { /* fail closed below */ }
@@ -5379,43 +5348,6 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
5379
5348
  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
5349
  }
5381
5350
 
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
5351
  /** The version of the stored digests a spawn baseline is written with (fingerprintTrees,
5420
5352
  * generatedWorkDigest); a baseline without `digestVersion` holds the legacy ones, 1. */
5421
5353
  const BASELINE_DIGEST_VERSION = 2;
@@ -6914,14 +6846,7 @@ export function isWorkspaceHome(meta) {
6914
6846
  }
6915
6847
  /** The refusal for a captured home: E_UNSUPPORTED_MODE (lead decisions on (e), D1). */
6916
6848
  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 — retire it (\`oats retire\` still works on it) and re-spawn from the deployment; ${what}`), { details: { home, captured: true } });
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();
6849
+ 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
6850
  }
6926
6851
  /** The refusal for a home an earlier (0.25) kernel spawned: E_UNSUPPORTED_MODE. */
6927
6852
  export function preWorkspaceHome(home, what) {
@@ -9243,7 +9168,7 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
9243
9168
  instance: name, agent: found.agent.name, root: resolve(root),
9244
9169
  requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
9245
9170
  // 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 } : {}),
9171
+ options: { home: found.home, ...(o.force ? { force: true } : {}), ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
9247
9172
  // The recorded children as they were when the retirement was scheduled: the completion stops them first.
9248
9173
  ...(Array.isArray(o.children) ? { children: o.children.map((c) => ({ instance: c.instance, home: c.home })) } : {}) }, resultPath,
9249
9174
  };
@@ -9451,9 +9376,9 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
9451
9376
  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
9377
  return false;
9453
9378
  };
9454
- const retry = `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}`;
9379
+ const retry = `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}${intent.options?.force ? " --force" : ""}`;
9455
9380
  const retireOnce = (underClaim) => retireInstance(intent.root, intent.instance, {
9456
- home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
9381
+ home: intent.options?.home, keepDir: !!intent.options?.keepDir, force: !!intent.options?.force, tmuxSession: intent.options?.tmuxSession,
9457
9382
  ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
9458
9383
  ...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
9459
9384
  ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
@@ -10019,62 +9944,13 @@ function retireSteps(root, name, o, found, at) {
10019
9944
  // retirement is deferred to a detached external completion (below); with
10020
9945
  // --keep-dir the old in-process path runs and kills the window LAST.
10021
9946
  const self = o.self === true;
10022
- const metaPath = join(found.home, "instance.json");
10023
9947
  // A QUARANTINED home (spawn failed after a required hook and compensation did
10024
9948
  // not finish) has no instance.json — it never got that far. Its marker carries
10025
9949
  // the cleanup descriptor in the same shape, so retire can rerun compensation
10026
9950
  // instead of silently skipping every hook and deleting the credentials.
10027
- const directoryFallbackPath = directoryRollbackPath(found.home);
10028
- const quarantinePath = existsSync(directoryFallbackPath) ? directoryFallbackPath : join(found.home, ".oats-rollback-incomplete.json");
10029
- let quarantine;
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;
9951
+ const admission = retireCleanupAdmission(found.home, name, o, instanceWork);
9952
+ const { meta, liveMeta, workIs, repoFromGit, hookRepo, directoryFallbackPath, quarantinePath, quarantine, hooksKnown, spawnGroupWarnings } = admission;
9953
+ let inProgressUnverified = admission.inProgressUnverified;
10078
9954
  // What this retire did to the hook group an interrupted spawn left, when it signalled it. Ending
10079
9955
  // that group is the first signal a retire can send: from that call on the retire is no longer
10080
9956
  // "before-effects", and no answer says that nothing was stopped.
@@ -10102,53 +9978,9 @@ function retireSteps(root, name, o, found, at) {
10102
9978
  spawnGroupWarnings.push(`retired with --force although the worktree ${note}; its branch is kept`);
10103
9979
  }
10104
9980
  }
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
9981
 
10149
9982
  const workPath = join(found.home, "work");
10150
- // What work/ is, by the one function the plan reads too (instanceWork, #962). Read once, here.
10151
- const workIs = instanceWork(found.home, meta);
9983
+ // Admission read work/ with the same instanceWork reader as the plan (#962).
10152
9984
  const directoryMode = workIs.is === "directory-mode";
10153
9985
  // A real directory that is not the instance's own tree is bytes of the home: inspected, copied to
10154
9986
  // recovery and checked as a directory instance's work is, and removed with the home. It never
@@ -10164,8 +9996,7 @@ function retireSteps(root, name, o, found, at) {
10164
9996
  // is the one Git names for the tree. A directory of the home is no worktree, whatever it holds,
10165
9997
  // and neither is a link, under a record that says `worktree` too: every step that asks whether
10166
9998
  // this home is a worktree's (the recovery's writers, the rollback retry) asks this record.
10167
- const repoFromGit = workIs.is === "own-tree" && !meta.repo ? workIs.tree?.repo : undefined;
10168
- const workMeta = workIs.is === "own-tree" ? { ...meta, work: "worktree", repo: meta.repo || repoFromGit }
9999
+ const workMeta = workIs.is === "own-tree" ? { ...meta, work: "worktree", repo: hookRepo }
10169
10000
  : homeDirectory || link ? { ...meta, work: undefined } : meta;
10170
10001
  // A live harness cannot establish a stable final work inspection of itself,
10171
10002
  // so self-retire never inspects, runs hooks, or removes anything here. It
@@ -10356,11 +10187,11 @@ function retireSteps(root, name, o, found, at) {
10356
10187
  // e.g. aweb signing keys) is removed. The knowledge integration harvests notes/ here;
10357
10188
  // the kernel itself is memory-agnostic.
10358
10189
  let hookResults;
10359
- if (meta.repo) {
10190
+ if (hookRepo && !isCapturedHome(meta)) {
10360
10191
  // The hooks this home recorded at spawn. A home an earlier kernel spawned
10361
- // without them still retires (lead decision c3 Q2): no hook runs, and the
10362
- // result says so.
10363
- const resolved = { ...resolvedFromHome(found.home, meta), capabilities: Array.isArray(meta.capabilityRuntime) ? meta.capabilityRuntime : [] };
10192
+ // without them needs explicit --force (retireCleanupAdmission); a captured
10193
+ // home cannot run its hooks. Neither path infers cleanup from missing data.
10194
+ const resolved = { ...resolvedFromHome(found.home, meta), capabilities: hooksKnown ? meta.capabilityRuntime : [] };
10364
10195
  // The soul this home was spawned from, as recorded (a workspace home records its
10365
10196
  // per-commit directory; agents/<name>/soul may since point elsewhere) — the same
10366
10197
  // value spawn's hook saw.
@@ -10384,7 +10215,7 @@ function retireSteps(root, name, o, found, at) {
10384
10215
  home: found.home, instance: name, agentName: found.agent.name,
10385
10216
  soulDir: instanceSoulDir(found.home, meta) || found.agent._soulDir || join(found.agent._dir, "soul"),
10386
10217
  ...(nonEmptyString(meta.soulId) ? { soulId: meta.soulId } : {}),
10387
- contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
10218
+ contextDir: hookRepo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
10388
10219
  finished, onFinished: (capability, answered) => { ended.push({ capability, ...(isPlainObject(answered) ? { meta: answered } : {}) }); recordEnded(); },
10389
10220
  });
10390
10221
  // The hooks ran: their warnings are events now, whatever the retire does
@@ -10414,7 +10245,7 @@ function retireSteps(root, name, o, found, at) {
10414
10245
  // A hook may exit 0 and still report it did not finish. Only an explicit
10415
10246
  // "nothing to undo" counts as complete — same rule the rollback path uses.
10416
10247
  for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
10417
- if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
10248
+ if (!hookCleanupComplete(m)) {
10418
10249
  ordinaryIncomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
10419
10250
  }
10420
10251
  }
@@ -10429,7 +10260,7 @@ function retireSteps(root, name, o, found, at) {
10429
10260
  if (quarantine) {
10430
10261
  for (const f of hookResults?.failures || []) retryFailures.push(`retire hook ${f.capability}: ${f.message}`);
10431
10262
  for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
10432
- if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
10263
+ if (!hookCleanupComplete(m)) {
10433
10264
  retryFailures.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""}`);
10434
10265
  }
10435
10266
  }
@@ -10762,7 +10593,7 @@ function retireSteps(root, name, o, found, at) {
10762
10593
  const outstandingHooks = new Set();
10763
10594
  for (const f of hookResults?.failures || []) outstandingHooks.add(f.capability);
10764
10595
  for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
10765
- if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") outstandingHooks.add(capId);
10596
+ if (!hookCleanupComplete(m)) outstandingHooks.add(capId);
10766
10597
  }
10767
10598
  // What the writer adds to the items is debt of its own: a descriptor kept outside the home, or
10768
10599
  // one that could not be stored, owes a restoration no rerun of the hooks makes.
@@ -10928,12 +10759,17 @@ function retireSteps(root, name, o, found, at) {
10928
10759
  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
10760
  if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
10930
10761
  if (isCapturedHome(meta) && !quarantine) {
10931
- // A captured home retires through the workspace path; its captured retire hooks do not
10932
- // run (lead decisions on (e), D1), so each capability whose spawn hook ran is named.
10762
+ // A captured home cannot run its pre-0.26 hooks. A forced removal names
10763
+ // each capability whose spawn hook ran, with the state it did not revoke.
10933
10764
  const caps = capturedHomeCapabilities(meta);
10934
10765
  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 (!Array.isArray(meta?.capabilityRuntime) && !quarantine) 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");
10766
+ 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");
10767
+ } else if (!hooksKnown && !quarantine) {
10768
+ 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");
10769
+ 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");
10770
+ } else if (!nonEmptyString(hookRepo) && hooksKnown && o.force && !quarantine) {
10771
+ 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`);
10772
+ }
10937
10773
  return w.length ? w : undefined;
10938
10774
  })() };
10939
10775
  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
+ }