@awebai/oats 0.68.1 → 0.69.2

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 (99) hide show
  1. package/bin/oats.mjs +180 -36
  2. package/docs/capabilities.md +73 -10
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/configuration.md +68 -2
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  6. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  7. package/docs/desktop-cli-api.md +600 -25
  8. package/docs/desktop-instance-start.md +59 -3
  9. package/docs/desktop.md +175 -10
  10. package/docs/execution-targets.md +536 -62
  11. package/docs/harness-trust.md +3 -1
  12. package/docs/implementation.md +33 -15
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge.md +25 -16
  15. package/docs/oats-local.schema.json +2 -2
  16. package/docs/official-catalog.md +6 -5
  17. package/docs/packages.md +14 -14
  18. package/docs/release-notes/v0.69.0.md +658 -0
  19. package/docs/release-notes/v0.69.1.md +25 -0
  20. package/docs/release-notes/v0.69.2.md +259 -0
  21. package/docs/servers.md +51 -7
  22. package/docs/soul.schema.json +1 -0
  23. package/docs/souls-and-instances.md +46 -9
  24. package/docs/tui.md +177 -21
  25. package/docs/upgrading.md +16 -7
  26. package/docs/workspaces.md +2 -2
  27. package/injects/instance-boundary.md +19 -33
  28. package/injects/work-attached.md +8 -13
  29. package/injects/work-checkout.md +16 -30
  30. package/injects/work-directory.md +9 -15
  31. package/injects/work-workspace.md +8 -19
  32. package/injects/work-worktree.md +18 -33
  33. package/lib/capability-contract.mjs +2 -2
  34. package/lib/core.mjs +496 -127
  35. package/lib/file-pieces.mjs +49 -0
  36. package/lib/instance-background.mjs +54 -0
  37. package/lib/instance-events.mjs +25 -4
  38. package/lib/instance-inspect.mjs +3 -0
  39. package/lib/instance-lifecycle.mjs +35 -0
  40. package/lib/instance-resolution.mjs +3 -2
  41. package/lib/instance-same-work.mjs +67 -0
  42. package/lib/instance-upgrade.mjs +18 -0
  43. package/lib/launch-prompt-fixtures/README.md +62 -0
  44. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  45. package/lib/launch-prompt-fixtures.mjs +49 -0
  46. package/lib/launch-prompt-resume.mjs +55 -0
  47. package/lib/login-environment.mjs +27 -9
  48. package/lib/materialize.mjs +23 -2
  49. package/lib/resolve.mjs +32 -5
  50. package/lib/schedule.mjs +3 -3
  51. package/lib/servers.mjs +136 -27
  52. package/lib/session-end.mjs +82 -0
  53. package/lib/session-input.mjs +43 -9
  54. package/lib/session-resume-contract.mjs +33 -0
  55. package/lib/session-resume.mjs +337 -0
  56. package/lib/session-seen.mjs +163 -0
  57. package/lib/session-viewer.mjs +147 -44
  58. package/lib/soul-composition.mjs +15 -11
  59. package/lib/start-env.mjs +110 -0
  60. package/lib/tmux-server-scope.mjs +139 -14
  61. package/lib/workspace.mjs +41 -6
  62. package/package-catalog.json +11 -5
  63. package/package.json +1 -1
  64. package/packages/client/cli-adapter.mjs +39 -8
  65. package/packages/client/cli-locator.mjs +3 -2
  66. package/packages/client/deployment-data.mjs +16 -0
  67. package/packages/client/deployment-panel.mjs +7 -0
  68. package/packages/client/file-output-exec.mjs +98 -0
  69. package/packages/client/instance-tree.mjs +64 -14
  70. package/packages/client/launch-prompt-outcome.mjs +25 -13
  71. package/packages/client/own-codes.mjs +2 -0
  72. package/packages/client/panel-views.mjs +11 -3
  73. package/packages/client/remote-roster.mjs +5 -1
  74. package/packages/client/roster-sections.mjs +50 -6
  75. package/packages/client/same-work.mjs +49 -0
  76. package/packages/client/session-attach.mjs +35 -5
  77. package/packages/client/session-resume-cli.mjs +64 -0
  78. package/packages/client/session-resume-trigger.mjs +167 -0
  79. package/packages/client/session-resume.mjs +332 -0
  80. package/packages/client/soul-rows.mjs +2 -0
  81. package/packages/client/spawn-apply-contract.mjs +2 -1
  82. package/packages/client/spawn-decision.mjs +4 -1
  83. package/packages/client/spawn-preview-contract.mjs +12 -1
  84. package/packages/client/spawn-preview.mjs +2 -0
  85. package/packages/client/tmux-status.mjs +30 -7
  86. package/packages/client/waiting-on-you.mjs +11 -4
  87. package/packages/client/workspace-step.mjs +17 -5
  88. package/packages/record/lib/last-conversation.mjs +123 -0
  89. package/packages/record/lib/session-roots.mjs +10 -1
  90. package/packages/tui/README.md +2 -2
  91. package/packages/tui/lib/client.mjs +7 -3
  92. package/packages/tui/lib/main.mjs +49 -14
  93. package/packages/tui/lib/model.mjs +146 -55
  94. package/packages/tui/lib/store.mjs +84 -27
  95. package/packages/tui/lib/term/text.mjs +12 -9
  96. package/packages/tui/lib/views/frame.mjs +74 -7
  97. package/packages/tui/lib/views/help.mjs +10 -3
  98. package/packages/tui/lib/views/instances.mjs +41 -3
  99. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -274,8 +274,9 @@ A self-contained package has an `oats.json`:
274
274
  `.a*`);
275
275
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
276
276
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
277
- `.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
278
- entries the kernel itself writes in an instance home;
277
+ `.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
278
+ `.oats-background` or `.oats-same-work`: the top-level entries the kernel
279
+ itself writes in an instance home;
279
280
  - a prefix that starts with `.oats-`.
280
281
 
281
282
  An exact name such as `.oats-aweb` is allowed: it is a provider's
@@ -473,8 +474,23 @@ Every spawned instance gets a **full copy** of each capability its soul
473
474
  resolved to, under `<home>/.oats/modules/<capability>/` (manifest, `bin/`,
474
475
  injects, skills), and those skills flat under `<home>/.agents/skills/<skill>/`
475
476
  beside the soul's own, one level deep where harnesses discover them. Its generated `AGENTS.md` is the
476
- soul's `AGENTS.md`, the kernel and work-mode blocks, then each module's inject
477
- in name order. Two composed skills with one name fail the spawn
477
+ soul's `AGENTS.md`, then each module's inject, then the kernel's instance-boundary
478
+ and work-mode blocks, last. The injects take the order the soul and the workspace
479
+ give them: first the capabilities the soul lists, in its `capabilities:` order (a
480
+ soul entry that re-lists a workspace default sits at the soul's place), then the
481
+ workspace defaults the soul does not list, in the order the workspace's
482
+ `defaults:` lists them (slot defaults and `defaults.capabilities` entries as they
483
+ appear in the file). A standalone soul has no workspace defaults; the kernel's
484
+ own `oats.core` default, which it gets unless it names `oats.core`, comes after
485
+ the capabilities it lists, as any default does. A capability name made only of
486
+ digits (`"123"`) is the one exception to the listing order: it comes first in its
487
+ list, ahead of the names written before it, because the parsed list puts
488
+ integer-like keys first. A capability
489
+ with no inject adds nothing, and one the soul turns `off` or a slot `none` drops
490
+ is not composed. Only the instructions take this order: modules, skills and hooks
491
+ stay in name order, and reordering a soul's list is not a composition change (no
492
+ drift). `oats instance upgrade` keeps the order a home recorded and puts the
493
+ kernel's blocks last. Two composed skills with one name fail the spawn
478
494
  (`E_SKILL_DUPLICATE`). The harness then starts normally, with its own skill
479
495
  discovery; the details are in [souls-and-instances.md](souls-and-instances.md).
480
496
  Change a capability's inject or skills in its repository, then spawn a new
@@ -1044,7 +1060,8 @@ latest-state capability.
1044
1060
 
1045
1061
  ### oats.core: needs input
1046
1062
 
1047
- oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
1063
+ oats.core (since 2.4.0, which needs kernel 0.40.0; 2.8.0 needs 0.49.0, as
1064
+ "Across `oats instance upgrade`" below says) tells the deployment
1048
1065
  when an instance is waiting on a human, in two independent ways. Each shows
1049
1066
  on `oats status` and in `oats instance events`. The verbs' contract
1050
1067
  (`oats instance waiting`, `oats instance attention`, the `waiting` event) is
@@ -1057,7 +1074,10 @@ question, a decision, an approval, a credential, any input it waits on), it runs
1057
1074
  `oats instance attention --message "<one line>"` from its home and ends its
1058
1075
  turn. Once it has the answer, it runs `oats instance attention --clear`. The
1059
1076
  claim belongs to producer `agent`. Only `--clear` or the next session start,
1060
- restart or stop clears it. The message is one line of at most 200
1077
+ restart or stop clears it. An instance whose human talks to its parent rather
1078
+ than to it sends the question to its parent instead; the parent sets its own
1079
+ claim naming the child and relays the answer. A claim is never set for
1080
+ another home. The message is one line of at most 200
1061
1081
  characters; control characters, the Unicode line and paragraph separators,
1062
1082
  bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
1063
1083
  characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
@@ -1091,10 +1111,31 @@ home. Before 2.4.1 it set and cleared the claim of the home its environment
1091
1111
  named, and its `Stop` and `SessionEnd` clears could erase that instance's
1092
1112
  real claim.
1093
1113
 
1114
+ **A set carries what the session waits on** (oats.core 2.8.0,
1115
+ [#1502](https://github.com/awebai/oats/issues/1502)). The script reads the
1116
+ hook's JSON input, at most 64 KiB and for at most 1 s, and its
1117
+ `bin/claude-waiting-message.mjs` makes the claim's `--message` from it. On
1118
+ Claude Code 2.1.300:
1119
+ - an `AskUserQuestion` gives its first question's own words
1120
+ (`tool_input.questions[0].question`), with `(+N more)` when it asks
1121
+ several;
1122
+ - a `Notification` gives its `message`: "Claude needs your permission to use
1123
+ Bash" for a permission prompt, "Claude Code needs your input" for an
1124
+ elicitation dialog.
1125
+
1126
+ The text is made one line, the kernel's refused characters are replaced with
1127
+ U+FFFD, and it is cut to 200 code points with `…`, so the kernel accepts it.
1128
+ An input with no text, or a reader that fails or takes over 1 s, sets the
1129
+ claim without one. A new text for the same reason is a change, so the claim
1130
+ is set again. A set records its intent before it reads the text, and only
1131
+ the latest event's text is ever applied. So a clear or a question that comes
1132
+ while an earlier set is still reading stands, and the earlier text never
1133
+ lands over it.
1134
+
1094
1135
  Claude Code shows an AskUserQuestion through its permission dialog, so that
1095
1136
  dialog's own `permission_prompt` follows the question's set: the script keeps
1096
- the current reason in its marker, and a permission prompt never relabels an
1097
- open question. A granted tool that fails fires `PostToolUseFailure`, not
1137
+ the current reason in its marker (and the text beside it), and a permission
1138
+ prompt never relabels an open question or replaces its text. A granted tool that fails fires `PostToolUseFailure`, not
1098
1139
  `PostToolUse`, so that clears too.
1099
1140
 
1100
1141
  **Subagents' tool calls do not clear.** Background and parallel subagents
@@ -1143,7 +1184,8 @@ clears it.
1143
1184
  in the home (`.oats/modules/oats.core`), which a start does not refresh. A
1144
1185
  home spawned with an oats.core that does not read the variable therefore
1145
1186
  writes its hook's own node path at every start: a restart repairs its
1146
- hooks after each Node upgrade, and a respawn gives it the lasting path. A
1187
+ hooks after each Node upgrade, and a respawn, or an upgrade of its
1188
+ oats.core (below), gives it the lasting path. A
1147
1189
  launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
1148
1190
  and pi homes get nothing.
1149
1191
  - **It never hurts the session.** Claude Code reads a hook's stdout and exit
@@ -1216,6 +1258,25 @@ clears it.
1216
1258
  exactly `.claude/settings.json`. oats.core writes it at spawn before the
1217
1259
  retirement baseline is taken, and again at every start.
1218
1260
 
1261
+ **Across `oats instance upgrade`.** oats.core 2.8.0 declares an `upgrade`
1262
+ hook ([the upgrade event](#the-upgrade-event)), not required, so a stopped
1263
+ home whose oats.core moves to it is upgraded rather than respawned. The
1264
+ hook that runs is the destination's, so this covers homes spawned on any
1265
+ earlier oats.core, with or without the emitter. oats.core records no
1266
+ capability metadata, and its settings entries name the module copy's path,
1267
+ `.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
1268
+ hook rewrites them. So `plan` adopts a home whose recorded
1269
+ `capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
1270
+ `false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
1271
+ refuses any other value as state it cannot vouch for, with the remedy
1272
+ `respawn the instance: oats retire <instance>, then oats spawn`. `apply`
1273
+ returns `{"meta":{}}`, which the kernel records as
1274
+ `capabilityMeta["oats.core"]`, and exits 1 with a JSON `warning` on any other
1275
+ metadata. Neither phase reads the home or calls the host. oats.core 2.8.0
1276
+ requires OATS 0.49.0: an earlier kernel drops a capability that declares a
1277
+ hook event it does not know, so it would lose oats.core whole. Only OATS
1278
+ 0.68.0 and later run the hook.
1279
+
1219
1280
  **Why the project settings file, not `--settings`.** On Claude Code
1220
1281
  2.1.288, Claude honours only the last `--settings` flag on a command line:
1221
1282
  that file replaces earlier ones wholesale, even one with no hooks. The
@@ -1281,7 +1342,9 @@ again" permission rules there.
1281
1342
  so its `Stop` and `SessionEnd` clears can erase the home's own live
1282
1343
  `oats.core` claim ([#557](https://github.com/awebai/oats/issues/557)).
1283
1344
  - A Claude instance spawned before the upgrade gets the emitter only when
1284
- it is respawned. Its launch hook comes from its recorded module copy.
1345
+ it is respawned, or when `oats instance upgrade` moves its oats.core to
1346
+ 2.8.0 or later and it starts again. Its launch hook comes from its
1347
+ recorded module copy.
1285
1348
 
1286
1349
  ## Operations a capability declares
1287
1350
 
@@ -366,7 +366,7 @@
366
366
  "description": "Home entries the kernel owns cannot be declared.",
367
367
  "anyOf": [
368
368
  {"pattern": "^\\.(?:oats|agents|claude)$"},
369
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
369
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
370
370
  {"pattern": "^\\.oats-.*\\*$"}
371
371
  ]
372
372
  }
@@ -251,6 +251,15 @@ v<semver>` after the logo, which may be caught mid-animation), the error and the
251
251
 
252
252
  A restart where the notice shows records `flag-ignored`.
253
253
 
254
+ **Known limit: a split window.** The confirmation still requires the agent's
255
+ window to have one pane. A start or restart in place on a window that has
256
+ another pane (oats.setup's no-echo prompt, for example) relaunches Claude in
257
+ the agent's pane
258
+ ([which pane is the agent's](execution-targets.md#which-pane-is-the-agents))
259
+ but answers nothing: the home records `launchPrompts.status: "blocked"`, and
260
+ Claude waits at its development-channel prompt for a person, as after any
261
+ blocked start. Close the other pane before the restart.
262
+
254
263
  **The two settings that stop it.** OATS confirms the prompt only because the
255
264
  deployment launches Claude with the development-channel flag. To keep the prompt
256
265
  for a person, stop launching that way: `settings.oats.aweb.delivery: session`
@@ -279,8 +288,8 @@ instance's terminal and press Enter yourself.
279
288
  ## Launch configurations
280
289
 
281
290
  An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
282
- (a bare name looked up on `PATH`, or a path relative to this deployment
283
- directory), `args` (literal, no shell), `env` (a literal string, or
291
+ (a bare name looked up on `PATH`, or a path relative to the directory of the
292
+ file that declares it), `args` (literal, no shell), `env` (a literal string, or
284
293
  `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
285
294
  `default` (0.32; see [the harness default](#the-harness-default)). A launch
286
295
  configuration is a host choice: a soul never names one.
@@ -315,6 +324,63 @@ configuration is a host choice: a soul never names one.
315
324
  `oats spawn` and reading `aw` mail and chat, and what stays gated.
316
325
  `yolo` is separate and is meant for isolated machines.
317
326
 
327
+ ### This machine's launch configurations
328
+
329
+ `~/.oats/config/launch-configs.yaml` (`$OATS_HOME_DIR/config/` when
330
+ `OATS_HOME_DIR` is set) declares launch configurations for every deployment
331
+ on this machine. The person writes it, or an installer running as the
332
+ person; nothing in OATS writes it.
333
+
334
+ ```yaml
335
+ launch-configs:
336
+ claude-auto:
337
+ harness: claude
338
+ args: ["--permission-mode", "auto"]
339
+ default: true
340
+ ```
341
+
342
+ - **One key.** The file holds `launch-configs:` and nothing else. Its entries
343
+ have exactly the schema of the deployment's block and the same checks.
344
+ - **Missing or broken.** A missing file declares nothing. A file that is there
345
+ but cannot be read, is not valid YAML, is empty, lacks `launch-configs:`,
346
+ has any other top-level key, or holds an invalid entry is refused
347
+ (`E_LAUNCH_CONFIG_INVALID`, naming the file). The refusal reaches every
348
+ listing, preview, spawn and start that reads launch configurations. It is
349
+ never skipped. `oats doctor` reports the file and does not fail on it.
350
+ - **Precedence, by name.** Each deployment reads the machine's entries under
351
+ its own. A deployment entry with the same name replaces the machine's
352
+ whole: no field of the machine's entry is kept. Its `shadows` names the
353
+ machine file. With no deployment in reach, the machine's entries alone
354
+ apply.
355
+ - **Precedence, for the default.** The [harness default](#the-harness-default)
356
+ is per harness. A deployment's `default: true` for a harness wins over the
357
+ machine's: the machine's entry for that harness stays listed, but not as
358
+ default. The machine's default applies when the deployment declares none
359
+ for that harness. Two defaults for one harness within one file are refused,
360
+ as in the deployment.
361
+ - **`source`** is the directory an entry was declared in: the deployment
362
+ directory, or `~/.oats/config`. A relative `executable` resolves against
363
+ it.
364
+ - **Where it shows.**
365
+ - `oats launch-config list` (and `--json`) gives each entry's `source` and
366
+ `shadows`.
367
+ - `oats spawn --preview` names the machine file when it supplied the
368
+ configuration; the JSON carries `launchConfigSource`.
369
+ - `oats doctor --json` reports the file under `machineLaunchConfigs`:
370
+ `file`, `present`, `ok`, `configurations` (the names) and, when broken,
371
+ `error`.
372
+ - **Writes.** `oats launch-config set|remove` writes only the deployment's
373
+ `oats-local.yaml`. Setting a name the machine also declares adds a
374
+ deployment entry that shadows it, and removing that entry uncovers the
375
+ machine's again. Desktop's launch-configuration editor writes the same
376
+ way: saving a row whose source is the machine file writes a deployment
377
+ entry of that name, which then shadows the machine's.
378
+ - **Homes.** A spawn records the configuration as it was, the machine's like
379
+ the deployment's (`launchConfigSource` is the directory it came from). A
380
+ start or restart runs the recorded recipe; a later edit of either file
381
+ reaches a home only through `--launch-config <name>`, `--reselect-launch`
382
+ or a respawn.
383
+
318
384
  ### The harness default
319
385
 
320
386
  `default: true` makes a configuration this host's baseline for its harness
@@ -258,13 +258,15 @@ delivers; what a provider consumes is its own contract. Teams reach providers as
258
258
  from: { kind: "member", repoKey, commit }
259
259
  | { kind: "package", package, version, commit, integrity, repoKey } }],
260
260
  slots, skills, injects, payloads, payloadOrigins,
261
- teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision }
261
+ teams, defaultTeam, slotsFrom, capabilitiesFrom, instructionOrder, turnedOff, declRevision, payloadRevision, revision }
262
262
  ```
263
263
 
264
264
  `module.dir` is the listed capability directory (for a package, the `oats-package.json#capabilities[]`
265
265
  entry). `declRevision` covers `{ resolutionApi, soul, modules, slots, skills, injects }`,
266
266
  `payloadRevision` the payloads, `revision` both (24 hex of SHA-256 over canonical JSON). A spawn decision
267
- binds `revision`. Provenance fields enter neither revision.
267
+ binds `revision`. Provenance fields enter neither revision. `instructionOrder` is one: the module names
268
+ in the order their injects take in the composed `AGENTS.md` (the soul's `capabilities:` order, then the
269
+ workspace defaults it does not list, in `defaults:` file order).
268
270
 
269
271
  ---
270
272
 
@@ -316,8 +318,8 @@ shims that throw `E_REMOVED { name, contract }`, pointing at this record.
316
318
  2. The copy's digest must equal the fetch's and any `module.digest` (`E_MATERIALIZE_INTEGRITY`).
317
319
  3. Copy skills whole to `<home>/.agents/skills/<skill>/`, flat (0.30.2; the grouped
318
320
  `<name>/<skill>/` layout this section first specified hid every skill from the harnesses).
319
- 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + kernel blocks + module
320
- injects; operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
321
+ 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + module injects in
322
+ `instructionOrder` + kernel blocks (`options.blocks`); operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
321
323
  and `.claude/skills → ../.agents/skills`.
322
324
  5. Record `modules: { <name>: { from, commit, digest, materializedAt } }`, `providers` (the payloads) and
323
325
  `resolutionRevision` in `instance.json`.
@@ -78,7 +78,7 @@ Apply runs under the claim, with the plan revision re-checked. A stale plan refu
78
78
 
79
79
  1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
80
80
  - `.agents/skills`;
81
- - `AGENTS.md`: the soul body at the **recorded soul commit**, the kernel blocks, then each module's inject. If the soul body at that commit can't be read, refuse;
81
+ - `AGENTS.md`: the soul body at the **recorded soul commit**, each module's inject in the order the home's `instructions` recorded (a module with no recorded block after them, by name), then the kernel blocks. If the soul body at that commit can't be read, refuse;
82
82
  - in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
83
83
  Read the soul body through discovery's path rule at that recorded commit:
84
84
  a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its