@awebai/oats 0.62.0 → 0.63.0

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 (34) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +30 -2
  3. package/docs/execution-targets.md +40 -1
  4. package/docs/official-catalog.md +1 -1
  5. package/docs/packages.md +5 -5
  6. package/docs/release-lane.md +13 -0
  7. package/docs/release-notes/v0.63.0.md +135 -0
  8. package/docs/souls-and-instances.md +6 -1
  9. package/docs/upgrading.md +5 -3
  10. package/docs/workspaces.md +1 -1
  11. package/lib/core.mjs +71 -21
  12. package/lib/tree-copy.mjs +188 -7
  13. package/package-catalog.json +1 -1
  14. package/package.json +1 -1
  15. package/packages/client/cli-locator.mjs +2 -2
  16. package/packages/record/bin/capture.mjs +59 -17
  17. package/packages/record/bin/setup.mjs +2 -1
  18. package/packages/record/docs/capture-service.md +89 -5
  19. package/packages/record/lib/capture-command-operation.mjs +2 -2
  20. package/packages/record/lib/capture-command-output.mjs +3 -2
  21. package/packages/record/lib/capture-command.mjs +20 -3
  22. package/packages/record/lib/capture-hook-runner.mjs +1 -1
  23. package/packages/record/lib/capture-index-reset.mjs +1 -0
  24. package/packages/record/lib/capture-lock.mjs +67 -33
  25. package/packages/record/lib/capture-pass.mjs +22 -8
  26. package/packages/record/lib/capture-run.mjs +1 -1
  27. package/packages/record/lib/capture-service-runner.mjs +1 -1
  28. package/packages/record/lib/capture-supervisor.mjs +24 -5
  29. package/packages/record/lib/capture-work-session.mjs +7 -4
  30. package/packages/record/lib/capture-worker.mjs +20 -4
  31. package/packages/record/lib/derived-state.mjs +30 -2
  32. package/packages/record/lib/index-db.mjs +118 -49
  33. package/packages/record/lib/store.mjs +13 -6
  34. package/skills/oats-getting-started/SKILL.md +1 -1
package/bin/oats.mjs CHANGED
@@ -105,7 +105,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
105
105
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
106
106
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
107
107
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
108
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size"];
108
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running"];
109
109
  /** Commands `--server <id>` runs on a registered server. */
110
110
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
111
111
  const flag = (name) => {
@@ -46,7 +46,7 @@ see the [official catalog](official-catalog.md) for current pins.
46
46
  "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
47
  "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
48
  "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
49
- "status-retire-state","session-inspect-size"],
49
+ "status-retire-state","session-inspect-size","session-inspect-running"],
50
50
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
51
51
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
52
52
  "capabilityShowApi":1}
@@ -124,6 +124,7 @@ see the [official catalog](official-catalog.md) for current pins.
124
124
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
125
125
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
126
126
  | `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
127
+ | `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
127
128
  | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
128
129
  | `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
129
130
  | `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
@@ -5139,7 +5140,34 @@ answered before any effect and carries [`details.holder`](#busy-holder)). The
5139
5140
  codes a retire answers only before any effect are
5140
5141
  [one list](#before-effect-codes). A recovery whose Git status disagrees with
5141
5142
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
5142
- source, recovery}], total}}` (the first 10 paths). Usage errors are text on
5143
+ source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
5144
+ bytes disagree with the source's (`worktree recovery verification disagreed
5145
+ with the source`) carries `details: {home, recoveryDisagreement: {basis:
5146
+ "current", entries: [{path, kind}], complete, stoppedBy?}}`, and the message
5147
+ names its first 5 entries. The refusal itself is the exact digest comparison
5148
+ and is unchanged; this report is read only after it refused, from the source
5149
+ and the copy as they are then (`basis: "current"`), so a source that changed
5150
+ since its bytes were recorded can show other differences, or none. `kind` is
5151
+ one of `missing` (in the source, not the copy), `extra`, `type`, `mode`,
5152
+ `link-target` and `file-content`, nothing is listed below a `missing`,
5153
+ `extra` or `type` entry, and one path can carry several kinds. `path` is
5154
+ relative to the worktree, with the same Git paths left out as the
5155
+ comparison: each printable ASCII byte as itself, a backslash as `\\`, every
5156
+ other byte as `\xHH`. No content, link target or absolute path is reported,
5157
+ and an entry that is a link is compared as a link, never followed. Every
5158
+ read is by path, so what is read is checked against what was listed: a file
5159
+ must be the regular file it was listed as (opened without following a link
5160
+ or waiting on a FIFO), and a directory the one it was listed as, before and
5161
+ after its listing and when the search leaves it; otherwise the search stops
5162
+ as `unreadable` and nothing found below that directory is reported. A
5163
+ replacement that is undone before the replaced directory is checked again is
5164
+ not detected: what was read through it can then be compared and named. Every
5165
+ path named is relative to the worktree. The search is bounded: at most 20 entries,
5166
+ 200,000 directory entries read (counted as each listing is read, so no
5167
+ listing goes past the budget), 64 MiB of file bytes read (files are compared
5168
+ in chunks, sizes first) and 5 seconds, checked between filesystem calls; when it stops early, `complete` is `false` and
5169
+ `stoppedBy` names why (`discrepancies`, `entries`, `bytes`, `time`, or
5170
+ `unreadable` when a tree could not be read). Usage errors are text on
5143
5171
  stderr, not envelopes.
5144
5172
 
5145
5173
  <a id="retire-reached"></a>
@@ -40,7 +40,9 @@ is the default); `tmux` must be installed on the execution host. A launched
40
40
  home keeps the session it recorded: `session start` and `restart` never
41
41
  re-read the defaults. The session target is recorded twice: in
42
42
  `instance.json` and in an independent lifecycle receipt. Every session command
43
- checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise).
43
+ checks that the two agree (`E_RUNTIME_AUTHORITY_MISMATCH` otherwise, with
44
+ `details.fields` naming what differs; see [Inspect, input and
45
+ attach](#inspect-input-and-attach)).
44
46
 
45
47
  ### tmux
46
48
 
@@ -1064,6 +1066,43 @@ oats session attach --home /abs/home --detach-key 'C-\'
1064
1066
  live claim that the instance needs input from a human, `{since, producer,
1065
1067
  reason, message}`, or `null`; it is non-null only for a running harness
1066
1068
  (docs/desktop-cli-api.md, "Waiting on you").
1069
+ With feature `session-inspect-running`, every successful result also
1070
+ carries `running`, a boolean read from the same pane observation by the
1071
+ same rule `oats status --json` uses for a row's `running`: `true` for a live
1072
+ non-shell process in the agent pane (`state: unknown`), a harness behind a
1073
+ wrapper shell included; `false` for a fallback shell (`state: shell`, where
1074
+ `present` stays `true`), an absent or dead pane or a missing home
1075
+ (`stopped`) and a home that never launched (`not-launched`). It costs no
1076
+ second observation: at most one process-table read, and only for a pane
1077
+ whose own command is a shell. `running` is activity at the authorized
1078
+ endpoint. It does not say the agent is generating, idle, healthy or ready
1079
+ for input, nor that it consumed a wake, and it does not prove which
1080
+ executable runs if a process inside the pane was replaced. When the
1081
+ backend or the process table cannot be read, or the pane answer is
1082
+ malformed or split, inspect is an error as before, never `running: false`.
1083
+ That includes a tmux server that is gone (`no server running on` its
1084
+ socket, as after a reboot): status reads that row as `running: false`, and
1085
+ inspect answers `E_SESSION_UNAVAILABLE`. Wherever inspect answers, its
1086
+ `running` is the one status reports.
1087
+ A consumer that sees no `running` (an older kernel or an older remote host)
1088
+ may read `state: unknown` on a successful result as running; a failed
1089
+ inspect is unknown, never stopped.
1090
+ `session inspect --server <id> --home <home> --json` relays the execution
1091
+ host's `running`, or its absence, as the host answered.
1092
+ A home whose `instance.json` disagrees with its session receipt is refused
1093
+ with `E_RUNTIME_AUTHORITY_MISMATCH` before any pane or process is read; the
1094
+ same refusal from any other session command, or in the answer of
1095
+ `oats retire`, carries the same details (the record a deferred
1096
+ `retire --self` leaves keeps only the code and message). Its `details.fields` names the differing fields, in this order, from this
1097
+ vocabulary only: `launched`, `tmux.session`, `tmux.window`, `tmux.socket`
1098
+ (the socket compared resolved, so a relative spelling of the same socket
1099
+ agrees). It carries no paths, values or receipt content. `launched` is
1100
+ listed unless a blocked or incomplete launch prompt explains
1101
+ `launched: false`; such a retained prompt is still allowed while its
1102
+ endpoint agrees, and only the endpoint fields that differ are named
1103
+ otherwise. A missing or invalid receipt stays `E_RUNTIME_ENDPOINT_UNKNOWN`
1104
+ and malformed metadata keeps its own refusal; neither carries
1105
+ `details.fields`.
1067
1106
  - **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
1068
1107
  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
1069
1108
  is never run by a shell. Existing endpoint authority, fallback-shell,
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.13.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.2.1` or `oats-framework/v1.13.1`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.2`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.13.1
77
+ oats.framework: v1.13.2
78
78
  oats.okf: v5.2.1
79
79
  oats.aweb: v1.29.0
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.1", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.2", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.1`
362
- resolves to tag `oats-framework/v1.13.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.2`
362
+ resolves to tag `oats-framework/v1.13.2`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -496,3 +496,16 @@ When the diff is not empty:
496
496
  not read it: it tags its own copy of `oats-package/`.) A green CI proves
497
497
  that the tag exists, not which commit it names: the pin's reviewer
498
498
  confirms on the remote that it names the first PR's merge commit.
499
+
500
+ ## Raising the Node version
501
+
502
+ A pull request that raises the Node version the workflows run
503
+ (`node-version` in `.github/workflows/`) also carries a macOS
504
+ [named run](named-test-runs.md) of `test/recovery-link-mode.test.mjs` at its
505
+ exact head. Every case in that file runs, with none skipped, and the run's
506
+ test warnings are read. The copier keeps each symbolic link's own mode with
507
+ `fs.lchmodSync`, which only macOS has and which Node lists as deprecated. If
508
+ a Node version drops it, the copy of a link whose mode differs from the new
509
+ link's must still be refused. Never take the link's mode out of the digest,
510
+ and never follow the link or change its target's mode, to make the upgrade
511
+ pass.
@@ -0,0 +1,135 @@
1
+ # OATS 0.63.0
2
+
3
+ Unreleased
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.62 Desktop refuses a 0.63.0 CLI. The
9
+ 0.63.0 Desktop accepts OATS CLIs `>=0.26.0 <0.64.0`.
10
+
11
+ - **The official catalog moves oats.framework 1.13.1 → 1.13.2** (oats.core
12
+ 2.6.4, see Provider updates). The other packages are unchanged. A
13
+ deployment takes it by moving its `oats.framework` pin and running
14
+ `oats sync`. Only new spawns use it.
15
+
16
+ ## Added
17
+
18
+ - `oats session inspect --json` reports `running` on every successful result,
19
+ advertised as `session-inspect-running`. Wherever inspect answers, it is the
20
+ liveness `oats status --json` reports for the row, by the same rule over the
21
+ same pane observation: `true` for a live harness, behind a wrapper shell included, and `false` for
22
+ a fallback shell, an absent or dead pane, a missing home or a home that never
23
+ launched. `state` and its enum are unchanged, and a failed observation is
24
+ still an error, never `false`; that includes a tmux server that is gone,
25
+ which status reads as `running: false` and inspect answers with
26
+ `E_SESSION_UNAVAILABLE`. `running` is activity at the session
27
+ endpoint, not health, readiness, busy or idle, or proof of which executable
28
+ runs. `--server` relays the execution host's answer; an older host's answer
29
+ has no `running`. See
30
+ [inspect, input and attach](../execution-targets.md#inspect-input-and-attach) (#1346).
31
+ - `E_RUNTIME_AUTHORITY_MISMATCH` (instance metadata that disagrees with the
32
+ independent session receipt, from a session command or `oats retire`) carries
33
+ `details.fields`: which of `launched`, `tmux.session`, `tmux.window` and
34
+ `tmux.socket` differ, never their values. A missing or invalid receipt is
35
+ still `E_RUNTIME_ENDPOINT_UNKNOWN`, without fields, and every refusal still
36
+ happens before any pane or process is read (#1346).
37
+
38
+ ## Changed
39
+
40
+ - A retire that refuses because the worktree recovery copy disagrees with the
41
+ source (`E_WORK_PRESERVATION_FAILED`, `worktree recovery verification
42
+ disagreed with the source`) now says where. `details.recoveryDisagreement`
43
+ lists up to 20 escaped relative paths, each with a fixed kind (`missing`,
44
+ `extra`, `type`, `mode`, `link-target`, `file-content`), and the message
45
+ names the first 5. The refusal is still decided by the exact digest
46
+ comparison, and nothing else changes: no hook runs, nothing is deleted and
47
+ the staged copy is removed as before. The report is read afterwards, from
48
+ the source and the copy as they are then, so it is a diagnosis, not a
49
+ verdict. Its search is bounded (entries, bytes read and 5 seconds) and says
50
+ when it stopped early. No content, link target or absolute path is
51
+ reported. See [the retire errors](../desktop-cli-api.md#retire) (#1360).
52
+
53
+ - **OATS Desktop accepts an `oats` CLI 0.63.x.** Its band is now
54
+ `>=0.26.0 <0.64.0`. 0.63 adds no new gate on the band: the Desktop does
55
+ not read `running` on `session inspect --json` or the mismatch's
56
+ `details.fields`, and it already reads a `launched` event's
57
+ `launchConfig: null` as no configuration (#1367).
58
+
59
+ ## Fixed
60
+
61
+ - A `session start|restart` that selects the bare harness from a home
62
+ recorded with a named configuration (for example `--launch-config none
63
+ --harness codex` on a home started with a claude configuration) now records
64
+ `launchConfig: null` everywhere. The launch itself, `instance.json` and the
65
+ command's answer already said so. But the session's `launched` event and the
66
+ restart receipt (`.oats-restart.json` `next.launchConfig`) named the earlier
67
+ configuration. So did the `launched` event an adoption records for a start
68
+ whose metadata write failed. Each now takes the name from the recipe the
69
+ start launched, its pending receipt's for an adoption. Only a receipt
70
+ without a recipe still falls back to the recorded one. Selection is
71
+ unchanged: `--launch-config none` is the bare harness, as
72
+ [launch configurations](../configuration.md#launch-configurations) say.
73
+ This is the kernel half of #1345. The provider's delivery for the selected
74
+ harness is tracked separately.
75
+
76
+ - SIGTERM or SIGINT now stops a capture pass cooperatively, where the worker was
77
+ killed at once before. The supervised pass starts no further worker, asks the
78
+ current worker to stop at its next unit boundary through the lock owner
79
+ record, and kills and reaps the worker if it has not stopped after a 5-second
80
+ grace, capped by the pass's deadline. The worker writes its own
81
+ `failed`/`interrupted` receipt and keeps its committed counts and the previous
82
+ `lastSuccess`. A killed worker leaves its `running` receipt, which the next
83
+ pass records as interrupted. The worker also catches a signal sent to the
84
+ caller's whole process group (Ctrl-C, `timeout`, a service manager), so it
85
+ is not killed mid-unit. An interrupted run's failure message now reads
86
+ "Capture execution was interrupted.", for a stop and for a later recovery
87
+ alike. The lock is released and the command exits 1.
88
+ `capture --home`, `--file` and `--reset-cursors` still run in the calling
89
+ process. They now stop at their safe points (before and after taking the
90
+ lock, before each format's batch, before the index update, and after the
91
+ work before answering), answer their
92
+ existing `failed` receipt with `capture interrupted by SIGTERM` and a
93
+ confirmed `appended`, release the lock and exit 1. Discovery, a format's
94
+ batch and the index update cannot be preempted, so a signal waits for the
95
+ segment it arrived in. See
96
+ [stopping capture](../../packages/record/docs/capture-service.md#stopping-capture-and-the-lock-owner-record) (#1347).
97
+ - The capture lock's `owner.json` now says who took it: `command`, `caller`
98
+ (`entry` and `trigger`) and `ppid`. These are fixed labels and process facts,
99
+ never argv or environment. They are diagnostic only. Records from earlier
100
+ releases are read and reclaimed exactly as before (#1347).
101
+
102
+ - The index update after `capture --home` or `--file` now skips streams it can
103
+ prove current. A stream is skipped when its validation checkpoint names the
104
+ journal's current version and its search cursor agrees with that checkpoint.
105
+ A skipped stream takes no stream lock, no validation and no `capture.db`
106
+ connection of its own. The pass opens `capture.db` once instead of twice per
107
+ stream, so an unchanged record no longer costs two lock cycles and two
108
+ database opens for every stream. Work now follows the streams that changed
109
+ and their new bytes. Backlog from `--no-index` passes, streams changed by
110
+ other writers, and missing or inconsistent evidence are still validated
111
+ under the stream lock, and a stale union still resets and is rebuilt. See
112
+ [the index update](../../packages/record/docs/capture-service.md) (#1348).
113
+
114
+ - A retire's recovery copy now keeps each symbolic link's own mode. The copy
115
+ recreated a link with its exact target but the platform's default mode,
116
+ while the verification digest holds the link's mode, so on macOS a worktree
117
+ whose ignored dependency tree has links of another mode (for example
118
+ `node_modules/.bin` links at 0700) was refused with "worktree recovery
119
+ verification disagreed with the source". The link is now given its source's
120
+ mode with lchmod, on the link itself, never on its target. Where the
121
+ platform cannot set a link's mode and the new link's differs, the copy is
122
+ refused rather than verified against another digest, and no target
123
+ changes. Spawn's copies of skills and the other recovery copies use the
124
+ same copier. See
125
+ [what a recovery copy carries](../souls-and-instances.md#retire) (#1360).
126
+
127
+ ## Provider updates
128
+
129
+ - **oats.framework 1.13.2, oats.core 2.6.4: `/oats-operate` reads inspect's
130
+ `running`** ([#1346](https://github.com/awebai/oats/issues/1346)). From OATS
131
+ 0.63.0 (feature `session-inspect-running`), the skill says what `running` on
132
+ `oats session inspect --json` means: activity at the session endpoint, not
133
+ health or readiness. A failed inspect is an error, never `running: false`.
134
+ Without the field, `state: unknown` on a successful result reads as running.
135
+ Text only: the capability's floor (`compatibility.oats`) is unchanged.
@@ -570,7 +570,12 @@ parses it, so it copies the files Git reads:
570
570
  and `info/exclude`) and the settings that change what `git status` reports
571
571
  (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
572
572
  `core.symlinks`, `core.autocrlf`, `core.eol`);
573
- - the bytes and the permission bits of its files, Git metadata left out.
573
+ - the bytes and the permission bits of its files, Git metadata left out, and
574
+ each symbolic link as itself: its raw target and its own permission bits.
575
+ A link is recreated with its target and then given its source's mode with
576
+ lchmod, on the link, never on what it points at; a platform that cannot
577
+ set a link's mode (no lchmod) refuses the copy where the new link's mode
578
+ differs, rather than keep a copy that differs from its source.
574
579
 
575
580
  The rule is that the work is unchanged only if everything its copy would
576
581
  carry is equal byte for byte, and anything that cannot be compared exactly
package/docs/upgrading.md CHANGED
@@ -89,9 +89,11 @@ For those released versions, follow their own Upgrade sections and the steps
89
89
  above. In particular, install the target Desktop before the CLI: the 0.61.0
90
90
  Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
91
91
 
92
- Service A ships in [0.62.0](release-notes/v0.62.0.md). Read its Upgrade
93
- section and keep this order: install the 0.62.0 Desktop first (it accepts CLIs
94
- `>=0.26.0 <0.63.0`), then the 0.62.0 CLI and matching pi bridge. Only **after
92
+ Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
+ release. Read 0.62.0's Upgrade section and keep this order: install the
94
+ Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
+ `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`), then that
96
+ release's CLI and matching pi bridge. Only **after
95
97
  installing that CLI**, run its setup conversion once per user on each host,
96
98
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
97
99
  watcher is replaced by the periodic service; foreign or disabled definitions
@@ -54,7 +54,7 @@ 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.13.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.2 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
package/lib/core.mjs CHANGED
@@ -83,7 +83,7 @@ export { exactTreeDigest, fingerprintTree, generatedWorkDigest, KERNEL_HOME_RECE
83
83
 
84
84
  import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
85
85
  import { readPortableBytes } from "./bounded-read.mjs";
86
- import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes } from "./tree-copy.mjs";
86
+ import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes, treeDisagreement } from "./tree-copy.mjs";
87
87
  import { readAheadConsumed, readingAhead } from "./read-ahead.mjs";
88
88
  import { assertSameWorktreeHead, gitRead, gitRefPresence, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
89
89
  import { systemTool } from "./system-tools.mjs";
@@ -6129,6 +6129,26 @@ export function statusDisagreement(sourceStatus, recoveredStatus, cap = STATUS_D
6129
6129
  const paths = [...new Set([...a.keys(), ...b.keys()])].filter((p) => a.get(p) !== b.get(p)).sort();
6130
6130
  return { rows: paths.slice(0, cap).map((path) => ({ path, source: a.get(path) ?? null, recovery: b.get(path) ?? null })), total: paths.length };
6131
6131
  }
6132
+ const RECOVERY_DISAGREEMENT_SHOWN = 5;
6133
+ /** The refusal of a copy whose exact digest is not its source's (`what`), with where the two differ
6134
+ * now (treeDisagreement, read with the same `excludePaths`) as `recoveryDisagreement`, and the first
6135
+ * of those in the message. The digest comparison has refused already; this reading only says where
6136
+ * to look, and its `basis: "current"` says that it is the source as it is now, not the bytes the
6137
+ * comparison recorded. Exported for its test. */
6138
+ export function recoveryDisagreed(what, source, copy, excludePaths) {
6139
+ const diff = treeDisagreement(source, copy, { excludePaths });
6140
+ const shown = diff.entries.slice(0, RECOVERY_DISAGREEMENT_SHOWN).map((d) => `${d.path} (${d.kind})`).join("; ");
6141
+ const more = diff.entries.length > RECOVERY_DISAGREEMENT_SHOWN ? `; and ${diff.entries.length - RECOVERY_DISAGREEMENT_SHOWN} more` : "";
6142
+ const unfinished = diff.complete ? "" : `${shown ? "; " : ""}the search stopped (${diff.stoppedBy})`;
6143
+ const found = shown || unfinished ? `${shown}${more}${unfinished}` : "no difference between the current source and the copy";
6144
+ return Object.assign(new Error(`${what}; where they differ now (diagnostic only): ${found}`), { recoveryDisagreement: { basis: "current", ...diff } });
6145
+ }
6146
+ /** The details of E_WORK_PRESERVATION_FAILED for `e`: the disagreements it carries, beside `home`.
6147
+ * Exported for its test. */
6148
+ export function preservationDetails(home, e) {
6149
+ if (!e.statusDisagreement && !e.recoveryDisagreement) return undefined;
6150
+ return { home, ...(e.statusDisagreement ? { statusDisagreement: e.statusDisagreement } : {}), ...(e.recoveryDisagreement ? { recoveryDisagreement: e.recoveryDisagreement } : {}) };
6151
+ }
6132
6152
  /** Refuse a recovery whose Git status is not the source's, naming the differing rows (capped). */
6133
6153
  function assertStatusAgrees(source, recovered, what, repo) {
6134
6154
  const sourceStatus = worktreeStatus(source), recoveredStatus = worktreeStatus(recovered);
@@ -6615,16 +6635,40 @@ function runtimeAuthorityOf(baseline) {
6615
6635
  return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
6616
6636
  }
6617
6637
 
6618
- /** instance.json's tmux endpoint is the one the independent receipt authorises. */
6619
- function tmuxEndpointAgrees(meta, authority) {
6620
- return meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
6638
+ /** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
6639
+ * authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
6640
+ function tmuxEndpointDifferences(meta, authority) {
6641
+ return [
6642
+ ...(meta.tmux?.session === authority.tmux?.session ? [] : ["tmux.session"]),
6643
+ ...(meta.tmux?.window === authority.tmux?.window ? [] : ["tmux.window"]),
6644
+ ...(resolve(meta.tmux?.socket || ".") === authority.tmux?.socket ? [] : ["tmux.socket"]),
6645
+ ];
6621
6646
  }
6647
+ /** instance.json's tmux endpoint is the one the independent receipt authorises. */
6648
+ function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
6622
6649
 
6650
+ /** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
6651
+ * launched receipt. */
6652
+ function promptRetained(meta, authority) {
6653
+ return authority.launched === true && meta.launched === false && ["blocked", "incomplete"].includes(meta.launchPrompts?.status);
6654
+ }
6623
6655
  /** A blocked prompt is a retained runtime, not evidence that no process exists.
6624
6656
  * The independent launched receipt and exact endpoint agreement remain mandatory. */
6625
6657
  function launchStateAgrees(meta, authority) {
6626
- return meta.launched === authority.launched || (authority.launched === true && meta.launched === false &&
6627
- ["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
6658
+ return meta.launched === authority.launched || (promptRetained(meta, authority) && tmuxEndpointAgrees(meta, authority));
6659
+ }
6660
+
6661
+ /** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
6662
+ * what differs, from a fixed vocabulary in a fixed order: `launched` (unless a blocked or incomplete
6663
+ * launch prompt explains metadata's `launched: false`), then, for a launched receipt, each differing
6664
+ * tmux endpoint field. Labels only: never a path, a value or the receipt. Callers throw it only once
6665
+ * their own comparison has refused, so these labels diagnose a refusal and never decide one. */
6666
+ function authorityMismatch(message, meta, authority) {
6667
+ const fields = [
6668
+ ...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
6669
+ ...(authority.launched ? tmuxEndpointDifferences(meta, authority) : []),
6670
+ ];
6671
+ return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
6628
6672
  }
6629
6673
 
6630
6674
  /** The refusal for a home whose session receipt is at neither key its path gives (findRetirementBaseline):
@@ -6658,20 +6702,23 @@ function instanceSessionTarget(home) {
6658
6702
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
6659
6703
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
6660
6704
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
6661
- if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
6705
+ if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
6662
6706
  return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined };
6663
6707
  }
6664
6708
 
6665
- export function inspectInstanceSession(home) {
6666
- if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", waitingOnYou: null };
6709
+ /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes. */
6710
+ export function inspectInstanceSession(home, { io } = {}) {
6711
+ if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null };
6667
6712
  const s = instanceSessionTarget(home);
6668
- if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", waitingOnYou: null };
6713
+ if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null };
6669
6714
  let observed;
6670
- try { observed = inspectSessionTarget(s.target, undefined, { includeSize: true }); }
6715
+ try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
6671
6716
  // The tmux failure stays the cause: sessionServerGone judges it.
6672
6717
  catch (e) { throw Object.assign(oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`), { cause: e }); }
6673
- // Feature waiting-on-you: beside `state`, whose enum is unchanged.
6674
- return { home: s.home, ...observed, waitingOnYou: harnessRunning(observed) ? liveWaiting(s.home) : null };
6718
+ // Features session-inspect-running and waiting-on-you: beside `state`, whose enum is unchanged.
6719
+ // `running` is status's own liveness predicate over this observation, never a second reading.
6720
+ const running = harnessRunning(observed);
6721
+ return { home: s.home, ...observed, running, waitingOnYou: running ? liveWaiting(s.home) : null };
6675
6722
  }
6676
6723
  /** Whether an observed session runs a harness: present, and neither a
6677
6724
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
@@ -7497,8 +7544,10 @@ export function startInstanceSession(home, o = {}) {
7497
7544
  // Reconcile even an exited target: the independent baseline may
7498
7545
  // already name it while metadata still names the old allocation.
7499
7546
  // The adopted start's session boundary, at its launch time, completed
7500
- // in whichever log the interrupted start did not record it.
7501
- recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: pending.launch?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: "recovered" });
7547
+ // in whichever log the interrupted start did not record it. The receipt's
7548
+ // recipe names its configuration (null: the bare harness); only a receipt
7549
+ // without a recipe falls back to the recorded one.
7550
+ recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: (pending.launch ? pending.launch.launchConfig : meta.launch?.launchConfig) ?? null, phase: "recovered" });
7502
7551
  const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
7503
7552
  // The adopted target is on another server than the home recorded (the start that allocated it
7504
7553
  // could not record it): this adoption records it, and says so once, here.
@@ -7693,7 +7742,7 @@ export function startInstanceSession(home, o = {}) {
7693
7742
  // end and wait, bounded. A harness still there afterwards is reported
7694
7743
  // as running; nothing is escalated and nothing is launched.
7695
7744
  stopReceipt = stopHarness(target, { graceMs: o.stopGraceMs ?? 20000, io: o.io, kill: o.io?.kill, sleep: o.io?.sleep });
7696
- writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
7745
+ writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe.launchConfig ?? null, model: model ?? null } }, 0o600);
7697
7746
  appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
7698
7747
  if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
7699
7748
  try { state = inspectSessionTarget(target, o.io); }
@@ -7794,7 +7843,8 @@ export function startInstanceSession(home, o = {}) {
7794
7843
  // The session exists: its boundary (lib/instance-events.mjs) is recorded
7795
7844
  // now, before the metadata, so a start whose metadata write fails still
7796
7845
  // voids the claims of the session it replaced; its adoption only completes a log it missed.
7797
- recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
7846
+ // The planned recipe names the configuration (null: the bare harness), never the recorded recipe's.
7847
+ recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
7798
7848
  // Keep launch evidence until the command exits or the target disappears.
7799
7849
  // A transient child (for example the native-start recorder) is not proof that startup
7800
7850
  // has finished. A later start reconciles the receipt without a watcher.
@@ -9118,7 +9168,7 @@ function copyRecoveryWork(observation, meta, parent, { rereadSource = true } = {
9118
9168
  let sourceBytes, gitPaths;
9119
9169
  if (observation.worktree) { sourceBytes = observedWorkBytes(observation); gitPaths = observation.workGitPaths ?? worktreeGitPaths(observation.work); }
9120
9170
  else { gitPaths = worktreeGitPaths(observation.work); sourceBytes = worktreeBytes(observation.work, gitPaths); }
9121
- if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw new Error("worktree recovery verification disagreed with the source");
9171
+ if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw recoveryDisagreed("worktree recovery verification disagreed with the source", observation.work, recoveredRepo, gitPaths);
9122
9172
  assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
9123
9173
  }
9124
9174
  // The proof of the copy: its HEAD is the commit the worktree has checked
@@ -9237,7 +9287,7 @@ function writeRetirementRecovery(observation, meta, instance, phase) {
9237
9287
  } catch (e) {
9238
9288
  const left = removeStaging(staging);
9239
9289
  if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
9240
- const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
9290
+ const details = preservationDetails(observation.home, e);
9241
9291
  throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
9242
9292
  }
9243
9293
  }
@@ -9323,7 +9373,7 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
9323
9373
  } catch (e) {
9324
9374
  const left = staging ? removeStaging(staging) : null;
9325
9375
  if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
9326
- const details = e.statusDisagreement ? { home: after.home, statusDisagreement: e.statusDisagreement } : undefined;
9376
+ const details = preservationDetails(after.home, e);
9327
9377
  throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
9328
9378
  }
9329
9379
  }
@@ -10328,7 +10378,7 @@ function retireSteps(root, name, o, found, at) {
10328
10378
  if (runtimeAuthority) {
10329
10379
  const metaAgrees = launchStateAgrees(meta, runtimeAuthority) && (!runtimeAuthority.launched || tmuxEndpointAgrees(meta, runtimeAuthority));
10330
10380
  if (!metaAgrees) {
10331
- throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
10381
+ throw authorityMismatch(`cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`, meta, runtimeAuthority);
10332
10382
  }
10333
10383
  }
10334
10384
  // The plan's promise about recorded children (`o.children`, computed the way