@awebai/oats 0.47.0 → 0.49.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 (44) hide show
  1. package/bin/oats.mjs +293 -41
  2. package/docs/capabilities.md +264 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +7 -1
  5. package/docs/desktop-cli-api.md +439 -40
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +19 -1
  8. package/docs/implementation.md +81 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +6 -5
  12. package/docs/packages.md +14 -14
  13. package/docs/release-notes/v0.48.0.md +106 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/schedules.md +62 -39
  16. package/docs/servers.md +7 -0
  17. package/docs/souls-and-instances.md +395 -52
  18. package/docs/workspaces.md +18 -3
  19. package/injects/work-checkout.md +17 -11
  20. package/injects/work-worktree.md +19 -13
  21. package/lib/capability-contract.mjs +100 -11
  22. package/lib/capability-show.mjs +5 -2
  23. package/lib/core.mjs +1147 -319
  24. package/lib/instance-events.mjs +6 -3
  25. package/lib/instance-git.mjs +11 -5
  26. package/lib/instance-inspect.mjs +14 -3
  27. package/lib/instance-lifecycle.mjs +106 -16
  28. package/lib/instance-resolution.mjs +15 -3
  29. package/lib/launch-prompt-policy.mjs +17 -3
  30. package/lib/packages.mjs +1 -0
  31. package/lib/real-path.mjs +27 -0
  32. package/lib/resolve.mjs +4 -4
  33. package/lib/retire-output.mjs +6 -1
  34. package/lib/schedule.mjs +1 -0
  35. package/lib/servers.mjs +32 -6
  36. package/lib/teams-verbs.mjs +40 -9
  37. package/lib/tree-copy.mjs +18 -7
  38. package/lib/triggers.mjs +201 -65
  39. package/lib/workspace.mjs +20 -5
  40. package/lib/worktree-hooks.mjs +392 -0
  41. package/lib/worktree.mjs +655 -0
  42. package/package-catalog.json +12 -5
  43. package/package.json +1 -1
  44. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -22,7 +22,9 @@ kernel emits it.
22
22
  Conventions: paths are absolute; a `commit` is a full 40-hex id; `integrity`
23
23
  and `digest` are `sha256-<hex>`; times are ISO-8601 UTC; repository keys are
24
24
  canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
25
- `/w` as the deployment and shorten ids and digests with `…`.
25
+ `/w` as the deployment and shorten ids and digests with `…`. Package versions
26
+ in example payloads are illustrative snapshots, not deployment pin advice;
27
+ see the [official catalog](official-catalog.md) for current pins.
26
28
 
27
29
  ## The probe
28
30
 
@@ -40,7 +42,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
40
42
  "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
41
43
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
42
44
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
43
- "automation-descriptions","souls-capabilities","soul-composed-instructions"],
45
+ "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
+ "server-probe-features","worktree-event"],
44
47
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
45
48
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
46
49
  "capabilityShowApi":1}
@@ -112,6 +115,9 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
112
115
  | `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
113
116
  | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
114
117
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
118
+ | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
119
+ | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
120
+ | `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)) | |
115
121
 
116
122
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
117
123
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -367,8 +373,9 @@ An instance subject, abridged:
367
373
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
368
374
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
369
375
  | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
370
- | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null` |
376
+ | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
371
377
  | `problems` | below |
378
+ | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
372
379
 
373
380
  **Soul row** (`soulsApi: 2`). For a home it is read from the recorded
374
381
  `soulDir` (`path` and `kind` are `null`); for a soul it is the member's current
@@ -491,6 +498,9 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
491
498
  ready}` (`ready` also needs no subject blocker). `subjectBlockers[]` is
492
499
  `{check, subject, status}` for each failing required item not about a
493
500
  capability. `notes` is prose.
501
+ - `warnings` (0.49.0) is always present: the
502
+ [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)
503
+ of the subject's capabilities. They are not items and change no status.
494
504
 
495
505
  **`installed`**, one item per module with `evidence: {from}`. `--home`
496
506
  (producer `instance modules`): passes when the home's copy holds `oats.json`
@@ -754,7 +764,10 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
754
764
  "no-catalog", catalog, path, message}`), `E_AUTOMATION_SCHEMA` and
755
765
  `E_AUTOMATION_DUPLICATE` (with `kind`). A problem never aborts the sync.
756
766
  - `warnings[]`: `soul-private-ignored {code, soul, repoKey, path, message}`
757
- for a soul.yaml still carrying `private`.
767
+ for a soul.yaml still carrying `private`; then (0.49.0)
768
+ `hook-event-unsupported {code, capability, path, message}` per hook event a
769
+ listed member capability declares and this kernel does not run
770
+ ([capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)).
758
771
  - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
759
772
  `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
760
773
  `E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
@@ -982,6 +995,11 @@ nothing reads a working clone.
982
995
  is a list of `{name, path, description, files, filesTruncated}`, each file
983
996
  `{path, bytes}`, or `null`. `problems` is a list of `{code, message,
984
997
  path}`.
998
+ - `warnings` (0.49.0) is always present, on the show and the `--file`
999
+ answer: the capability's
1000
+ [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
1001
+ Their `path` is the repository-relative form, unlike the paths above. The
1002
+ text form prints them (to stderr with `--file`).
985
1003
  - With `--max-age` (`0` included) both the show and the `--file` answer gain
986
1004
  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
987
1005
  block `{observedAt, reused, localRevision}`.
@@ -1081,6 +1099,37 @@ problems. `--file` prints the text; a binary file prints a one-line note
1081
1099
  instead, and a truncated file prints its text followed by a one-line note.
1082
1100
 
1083
1101
  <a id="desktop-facts-feature-desktop-facts-oats-0290"></a>
1102
+ ### Capability warnings (`hook-event-unsupported`, OATS 0.49.0)
1103
+
1104
+ A capability may declare a hook event this kernel does not run (a newer
1105
+ kernel's). It composes, the event never runs, and each answer that shows the
1106
+ capability carries one warning per such event
1107
+ ([capabilities.md](capabilities.md#manifest)):
1108
+
1109
+ ```json
1110
+ {"code":"hook-event-unsupported","capability":"acme.tool",
1111
+ "path":"github.com/acme/agents:capabilities/acme-tool/oats.json#/hooks/on-merge",
1112
+ "message":"capability acme.tool declares hook \"on-merge\", which this kernel does not run; it is ignored (this kernel runs soul-scaffold, spawn, retire, launch, worktree)"}
1113
+ ```
1114
+
1115
+ | Answer | Where | Covers |
1116
+ |---|---|---|
1117
+ | `oats sync`, `oats workspace status` | `warnings[]`, beside `soul-private-ignored` | every listed member capability |
1118
+ | `oats capabilities show` (and `--file`) | `warnings[]`, always present | the capability shown |
1119
+ | `oats inspect`, `oats readiness` | `warnings[]`, always present | `--soul`: the soul's resolved modules; `--home`: the home's module copies |
1120
+ | `oats doctor --json` | `warnings[]` | `--soul`: the soul's resolved modules; without it, every member capability and every locked package's, from this machine's cache |
1121
+ | `oats spawn --preview`, `oats spawn` | `warnings[]`, strings | the message of each, for the soul's resolved modules, each at most 1000 characters and at most 32 lines (past that, one line naming how many more); a same-key replay answers them from the home's module copies |
1122
+
1123
+ `path` is never an absolute host path. It is `<repoKey>:<dir>/oats.json#<pointer>`
1124
+ for a member capability, `package:<id>:<dir>/oats.json#<pointer>` for a
1125
+ package capability (`<dir>` relative to the repository), and, for `--home`,
1126
+ `.oats/modules/<name>/oats.json#<pointer>`, relative to the home: the copy
1127
+ actually read. Without `--soul`, doctor reads only this machine's cache; what
1128
+ it cannot answer is one `information[]` line `hook-events-unchecked: <member
1129
+ capabilities | package <id>'s capabilities> were not checked …`, never an
1130
+ empty list read as "no warning". Older kernels answer no such `warnings` key
1131
+ (inspect, readiness, show, doctor) and refuse the capability instead.
1132
+
1084
1133
  ### Desktop facts
1085
1134
 
1086
1135
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -1250,9 +1299,9 @@ unknown.
1250
1299
 
1251
1300
  ```text
1252
1301
  oats teams [--dir <d>] [--max-age <s>] --json
1253
- oats teams add <label> --team <id> [--description <d>] --json
1302
+ oats teams add <label> --team <id> [--description <d>] [--no-default] --json
1254
1303
  oats teams remove <label> --json
1255
- oats teams default <label> --json
1304
+ oats teams default <label> [--if-absent | --expect <label>] --json
1256
1305
  ```
1257
1306
 
1258
1307
  ```json
@@ -1284,13 +1333,41 @@ oats teams default <label> --json
1284
1333
  still runs there: taking local teams away is the last step of committing
1285
1334
  them in the workspace.
1286
1335
  - **`add`**: the first team added also becomes the local `defaultTeam`. A
1287
- label already declared is `E_TEAM_EXISTS {label, from}`; a bad label or no
1288
- `--team` is `E_BAD_ARGS`.
1336
+ label already declared is `E_TEAM_EXISTS {label, from, observed: {label,
1337
+ team, from}}` (`observed` is the declared mapping; `from` is `"local"` or
1338
+ `"shared"`); a bad label or no `--team` is `E_BAD_ARGS`.
1339
+ - **`add --no-default`** (feature `teams-conditional-default`) writes the
1340
+ mapping and never touches `defaultTeam`. A mapping already declared with
1341
+ the same label and the same team id (local or shared) is reuse: the answer
1342
+ is `changed: false, reused: true`, so a setup can retry it. The description
1343
+ is neither compared nor changed. The same label with another id is
1344
+ `E_TEAM_EXISTS` as above. `reused` appears only on that answer. Where local
1345
+ teams are not allowed, `add --no-default` is refused with local-teams-closed
1346
+ like every `add`, before reuse is considered.
1289
1347
  - **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
1290
1348
  {label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
1291
1349
  at}` (a label in both files can be removed locally); unknown is
1292
1350
  `E_TEAM_UNKNOWN {label}`.
1293
1351
  - **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
1352
+ - **`default --if-absent`** sets it only where the deployment has no effective
1353
+ default (this document's `defaultTeam` is `null`); **`default --expect
1354
+ <label0>`** only where the effective default's label is `<label0>`, local
1355
+ or inherited from the workspace (feature `teams-conditional-default`). The
1356
+ two together are `E_BAD_ARGS`. A failed condition is `E_TEAM_DEFAULT_MISMATCH
1357
+ {expected: {absent: true} | {label}, observed}`, `observed` being the
1358
+ `defaultTeam` exactly as this document reports it (or `null`); nothing was
1359
+ written. A soul's `souls:` default is not the deployment's and is not
1360
+ looked at. The refusals above run first, in order: `E_BAD_ARGS`,
1361
+ local-teams-closed, `E_TEAM_UNKNOWN`, then the condition. When the
1362
+ condition holds and `<label>` already is the local default, `changed` is
1363
+ `false`.
1364
+ - **Flags**: each form refuses a flag it does not take with `E_USAGE {flag}`,
1365
+ naming the flag and the usage, before anything is read. `add` takes
1366
+ `--team`, `--description`, `--no-default`; `remove` none; `default`
1367
+ `--if-absent`, `--expect`; every form `--dir` and `--json`, and the read
1368
+ form `--max-age` (on a write form, `--max-age` is the kernel's own
1369
+ `E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
1370
+ answer, as for every command.
1294
1371
  - A write that would introduce an unknown reference is refused with that
1295
1372
  code; an invalid result is `E_WORKSPACE_SCHEMA`.
1296
1373
  - **Writes** edit `oats-local.yaml` in place and touch only the entries that
@@ -1298,7 +1375,22 @@ oats teams default <label> --json
1298
1375
  entries, are kept. Each verb re-reads the file and judges its refusals on it
1299
1376
  as it is now, and writes only if the file did not change meanwhile (else it
1300
1377
  redoes the edit on the new content). A file that keeps changing is
1301
- `E_LOCAL_CHANGED {path}`; nothing was written.
1378
+ `E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
1379
+ and `--expect` is judged the same way, on the file as it is now and again on
1380
+ every redo.
1381
+ - **Concurrency.** Every `add`, `remove` and `default` holds
1382
+ `<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
1383
+ Among concurrent `oats teams` writers on one deployment, a conditional write
1384
+ therefore never overwrites a default another of them set: when two race, the
1385
+ later one sees the earlier result and refuses with
1386
+ `E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
1387
+ {path, lock}`, naming the directory to remove when no oats process is
1388
+ editing; nothing was written. The limits: a person or tool editing
1389
+ `oats-local.yaml` directly does not take the lock (the content compare still
1390
+ catches most such edits, but not one landing between the compare and the
1391
+ rename), and changes to the committed `oats-workspace.yaml` (a pull, a
1392
+ merge) are not serialized with it: the condition reads the workspace file
1393
+ when it is judged, and that is the only promise.
1302
1394
 
1303
1395
  <a id="oats-soul-teams"></a>
1304
1396
  ### `oats soul teams`
@@ -1674,6 +1766,7 @@ it to a temporary copy (`soulFetched: true`).
1674
1766
  "preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
1675
1767
  "harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
1676
1768
  "branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
1769
+ "worktreeHooks":[{"capability":"nw-tools","required":true}],
1677
1770
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
1678
1771
  "executable":"/usr/local/bin/pi",
1679
1772
  "capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
@@ -1693,7 +1786,17 @@ it to a temporary copy (`soulFetched: true`).
1693
1786
  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
1694
1787
  cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
1695
1788
  preview and apply alike.
1789
+ - `worktreeHooks` (feature `worktree-event`, OATS 0.49.0): for a `worktree`
1790
+ spawn, the capabilities whose `worktree` hook the spawn would fire, in the
1791
+ order they run, as `[{capability, required}]` (`[]` when none declares
1792
+ one); `null` in every other mode. `worktree` stays the path string. The
1793
+ text preview prints `worktree hooks: a, b (required)` or `worktree hooks:
1794
+ none` ([the worktree event](capabilities.md#the-worktree-event)).
1696
1795
  - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
1796
+ - `warnings`, present only when there is one, is an array of strings: the
1797
+ launch-prompt notice, and (0.49.0) the message of each
1798
+ [capability warning](#capability-warnings-hook-event-unsupported-oats-0490)
1799
+ of the resolved modules. The apply's `warnings` carries the same messages.
1697
1800
 
1698
1801
  **Launch.**
1699
1802
  - `harness`, `model`, `modelSource`, `launchConfig`, `backend`, `yolo`
@@ -1840,7 +1943,12 @@ with `--expect-decision` records the key and decision in `instance.json`.
1840
1943
  read `tmux` for the target.
1841
1944
  - When they apply: `yolo`, `decision` and
1842
1945
  `replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
1843
- `wakeScheduleError` (a requested wake).
1946
+ `wakeScheduleError` (a requested wake), `worktreeHooks` (feature
1947
+ `worktree-event`: only when the spawn ran `worktree` hooks, the receipt
1948
+ `[{capability, ok, required, log, exitCode, signal?, timedOut?,
1949
+ contract?}]`, `log` being the hook's log file).
1950
+ - A spawn that runs `worktree` hooks can take up to 30 minutes per hook
1951
+ ([the worktree event](capabilities.md#the-worktree-event)).
1844
1952
 
1845
1953
  <a id="instance-names"></a>
1846
1954
  ### Instance names
@@ -1886,6 +1994,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
1886
1994
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
1887
1995
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
1888
1996
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
1997
+ | `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
1998
+ | `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
1999
+ | `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
1889
2000
  | `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
1890
2001
 
1891
2002
  Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
@@ -1894,6 +2005,116 @@ cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
1894
2005
  Confirmed completed compensation does not set this marker. This is an additive
1895
2006
  producer migration; existing text-based compatibility checks remain.
1896
2007
 
2008
+ <a id="oats-worktree"></a>
2009
+ ### `oats worktree`
2010
+
2011
+ Feature `worktree-event` (OATS 0.49.0). An instance's extra trees,
2012
+ `<home>/.work-<purpose>`, made and removed from its home
2013
+ ([extra trees](souls-and-instances.md#extra-trees)). There is no `--home`,
2014
+ `--dir` or `--server`: the home is `$OATS_INSTANCE_HOME` (or `$OATS_HOME`),
2015
+ else the home enclosing the working directory.
2016
+
2017
+ ```text
2018
+ oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]
2019
+ oats worktree remove --purpose <p> [--json]
2020
+ ```
2021
+
2022
+ `add` creates the tree with Git, fires the `worktree` hooks
2023
+ ([the worktree event](capabilities.md#the-worktree-event)), writes
2024
+ `<home>/.oats/trees/<p>.json` and appends a `worktree-added` event. It can run
2025
+ for minutes; the hooks' output goes to stderr, and stdout holds only the
2026
+ envelope. A reader that closes either pipe early only stops reading: the add
2027
+ runs to its end (and its record to `ready`), the hooks' logs are whole, and
2028
+ what could not be printed is dropped. Its result:
2029
+
2030
+ ```json
2031
+ {"purpose":"docs","path":"/w/agents/dev/instances/dev-1/.work-docs","clone":"/w/docs","remote":"https://github.com/nw/docs.git",
2032
+ "member":"github.com/nw/docs","branch":"agents/dev-1-docs","base":"main","baseOid":"9f2c41d0…","state":"ready",
2033
+ "hooks":[{"capability":"nw-setup","ok":true,"required":true,"log":"/w/agents/dev/instances/dev-1/.oats/logs/worktree-docs-nw-setup.log","exitCode":0}],
2034
+ "record":"/w/agents/dev/instances/dev-1/.oats/trees/docs.json","resumed":false,"warnings":[]}
2035
+ ```
2036
+
2037
+ - `remote` never carries credentials; `member` is a member key or `null`.
2038
+ - `resumed: true`: a `ready` record with the same clone, branch and base was
2039
+ found; nothing ran, and the result is the recorded receipt.
2040
+ - `treeMissing: true` appears when a non-required hook removed or moved the
2041
+ tree.
2042
+ - `--preview` fetches and writes nothing: `{preview: true, purpose, path,
2043
+ clone, remote, member, branch, base, record, resume, hooks}`, `resume`
2044
+ being `null` or `"recover"` (an interrupted add is rolled back first), and
2045
+ `hooks` the hooks that would run, `[{capability, required}]`. When the tree
2046
+ is already made, it is the recorded receipt with `preview: true`,
2047
+ `resume: "noop"` and `hooksToRun: []`.
2048
+
2049
+ `remove` answers `{purpose, path, removed: true, rolledBack, branch,
2050
+ branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
2051
+ `rolledBack` is `false` and `branchKept` is `true`. When it completed an
2052
+ interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
2053
+ whether the branch still exists. The rollback deletes the branch only when
2054
+ that add created it, no worktree has it checked out, and it still points at
2055
+ the commit the add created it at. A branch kept for one of those reasons is
2056
+ named in `branchKeptReason`, and is not debt.
2057
+
2058
+ The rollback signals a hook process group that the interrupted add left only
2059
+ when the group's leader is alive with its recorded start time. A group whose
2060
+ leader has exited is never signalled, because its id may already belong to
2061
+ an unrelated group. Instead `warnings` names it, so that leftover processes
2062
+ can be ended by hand.
2063
+
2064
+ Every `add` or `remove` that reads a record it may act on holds the
2065
+ purpose's claim, `<home>/.oats/trees/<purpose>.lock`. The claim is a file
2066
+ that names its holder by pid and start time. A second command waits up to
2067
+ 3 s for a live holder, then answers `E_LIFECYCLE_BUSY` (`details.lock`,
2068
+ `details.pid`). A claim whose holder has died, for example one killed in the
2069
+ middle of a recovery, is taken over by the next command. So a killed `add`
2070
+ or `remove` can always be run again.
2071
+
2072
+ A killed parent does not take its running git with it. So every git step
2073
+ that changes a tree, a ref or the worktree list runs in its own process
2074
+ group, and is recorded (pid and start time) before it starts: in the claim,
2075
+ or for an `add`'s own steps, in the tree record. A takeover or recovery
2076
+ first ends a recorded git step that still runs, signalling it only while its
2077
+ leader runs with the recorded start time (SIGTERM, which git answers by
2078
+ removing its lock files, then SIGKILL). Only then does it act, so a dead
2079
+ command's git never finishes late on a tree or branch made after it. A git
2080
+ step that times out is cleared from the record only once its whole process
2081
+ group is gone. A git step that cannot be ended keeps the claim, or the
2082
+ record, and the command answers `E_LIFECYCLE_BUSY`.
2083
+
2084
+ A recorded hook group or git step that still has members while its leader's
2085
+ start cannot be read (where `ps` fails) is never signalled and never passed
2086
+ over: the leader may still be that hook or git step. The command answers
2087
+ `E_LIFECYCLE_BUSY`, keeping the claim or the record and touching nothing
2088
+ else. Its message names the group, its recorded start, why the start cannot
2089
+ be read and the way out: check the group by hand; if it is that step, end it
2090
+ (`kill -TERM -- -<pgid>`) and retry; if it is not, remove the claim or the
2091
+ record it names (a record with what that add left) and retry. A claim's refusal
2092
+ carries `details.gitPid` and `details.gitStart`.
2093
+
2094
+ A failed `add` reports the same facts about its rollback in `details`:
2095
+ `rolledBack`, `branchKept`, `branchKeptReason` and `warnings`.
2096
+
2097
+ | Code | When |
2098
+ |---|---|
2099
+ | `E_BAD_ARGS` | not run from an instance home; `--dir`, `--home` or `--server`; a missing value; a value starting with `-`; an invalid purpose, branch or base; `remove` of a purpose with no record (a tree made with raw Git is removed with `git worktree remove`) |
2100
+ | `E_INSTANCE_RETIRING` | `add` in a quarantined home, or one being retired |
2101
+ | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
2102
+ | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
2103
+ | `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
2104
+ | `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; the tree is removed |
2105
+ | `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
2106
+ | `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); or an interrupted add's rollback could not be completed (`details.owed`) |
2107
+ | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
2108
+ | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
2109
+ | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
2110
+ | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2111
+ | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
2112
+ | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2113
+
2114
+ A rollback that cannot finish keeps the record and says so in the message
2115
+ (`details.rolledBack: false`, `details.owed`); the next `add` or `remove` of
2116
+ that purpose finishes it.
2117
+
1897
2118
  ## `instance.json` and the roster
1898
2119
 
1899
2120
  <a id="instancejson"></a>
@@ -1932,6 +2153,15 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
1932
2153
  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
1933
2154
  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
1934
2155
  `<home>/.agents/skills/<cap>/<skill>/`).
2156
+ - `branch`: for a worktree instance, the branch its worktree was created on.
2157
+ For an attached or checkout instance, the branch the tree's HEAD named at
2158
+ the spawn, or `null` when HEAD was detached or named a ref OATS carries no
2159
+ branch name for (one whose name is not valid UTF-8); never the word
2160
+ `"HEAD"`. The key is absent when the tree's HEAD could not be read, and for
2161
+ directory and workspace instances. A home spawned before 0.49.0 may record
2162
+ `"HEAD"` for a detached tree; [`oats instance git`](#instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247)
2163
+ reads it as no recorded branch. The roster row and the spawn result carry
2164
+ the same value (the spawn result has `null` where the key is absent).
1935
2165
  - `base` (a worktree instance): `{ref, oid}`, the commit its branch started
1936
2166
  at, as the spawn result states it (see Placement under the spawn preview).
1937
2167
  - `providers.<cap>`: the merged payload (`{}` when none).
@@ -1957,8 +2187,10 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
1957
2187
  oats status [--dir <d>] [--max-age <s>] --json
1958
2188
  ```
1959
2189
 
1960
- Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
2190
+ Not an envelope: `{root, agents, observation?, features, workspace?, problems?, warnings?}`
1961
2191
  (`observation` only with [`--max-age`](#observation-reuse-feature-observe-max-age-oats-0311)).
2192
+ It carries no `schemaVersion`: a remote caller recognizes the bare roster by
2193
+ its absence.
1962
2194
 
1963
2195
  ```json
1964
2196
  {"root":"/w/agents",
@@ -1969,6 +2201,7 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
1969
2201
  "modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
1970
2202
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
1971
2203
  "soul":{"repoKey":"github.com/nw/agents","commit":"66566512…","current":"66566512…","status":"current"}}]}],
2204
+ "features":["retire-home","session-start","…","server-probe-features"],
1972
2205
  "workspace":{"reachable":true,"key":"github.com/nw/agents","ref":"git:github.com/nw/agents","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"eng","team":"eng:nw.aweb.ai"},
1973
2206
  "teams":{"eng":"eng:nw.aweb.ai","mine":"mine:ana.aweb.ai","ops":null},"teamsFrom":"observed"}}
1974
2207
  ```
@@ -1993,6 +2226,16 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
1993
2226
  in the row),
1994
2227
  `identity` when a provider recorded one, `rollbackIncomplete` and
1995
2228
  `retirePending` when present, and the Desktop facts below.
2229
+ - **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
2230
+ while a spawn that is running its `worktree` hooks is verifiably alive (its
2231
+ pid runs with the recorded start time). Such a home holds the quarantine marker
2232
+ with an `inProgress` field ([capabilities.md](capabilities.md#manifest)),
2233
+ and its row carries `spawnInProgress: true` and **no**
2234
+ `rollbackIncomplete`: a live spawn, not a failed one. Once that process is
2235
+ gone, or when its start time cannot be read (where `ps` fails), the row
2236
+ carries `rollbackIncomplete` as for any quarantine, its `inProgress` naming
2237
+ the pid; retire still refuses an unreadable one with `E_LIFECYCLE_BUSY`
2238
+ until `--force`. Absent otherwise, and from older kernels.
1996
2239
  - **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
1997
2240
  message}` when the row is `running: true` and a producer holds a live claim
1998
2241
  that the instance needs input from a human, else `null` (unknown, not "not
@@ -2016,6 +2259,12 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2016
2259
  message}` (modules then stay the recorded map), plus the deployment's
2017
2260
  [workspace identity](#workspace-identity-feature-workspace-identity-oats-0360)
2018
2261
  either way. Absent without `oats-local.yaml`.
2262
+ - **`features`** (feature `server-probe-features`, OATS 0.49.0): the
2263
+ running kernel's own feature list, the same array as `version --json`
2264
+ `features`, so a [remote roster](#the-remote-roster-oats-server-roster---json)
2265
+ relays a host's features from the status answer it already pulls. It is
2266
+ emitted at output time, never part of a reused observation. A kernel
2267
+ before 0.49.0 omits it.
2019
2268
  - `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
2020
2269
  `warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
2021
2270
 
@@ -2095,7 +2344,7 @@ route target:
2095
2344
  ```json
2096
2345
  {"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
2097
2346
  "target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
2098
- "probe":{"ok":true},"agentsRoot":"/srv/team/agents",
2347
+ "probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
2099
2348
  "workspace":{"reachable":true,"key":"github.com/acme/team","ref":"git:github.com/acme/team","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"default","team":"acme:team"},
2100
2349
  "teams":{"default":"acme:team"},"teamsFrom":"observed"},
2101
2350
  "souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
@@ -2113,6 +2362,22 @@ route target:
2113
2362
  "retireFailures":[]}
2114
2363
  ```
2115
2364
 
2365
+ - **`probe`**: `{ok: true, features}` when the host's `status --json` was
2366
+ pulled, else `{ok: false, error: {code, message}}` (ssh failed, the host
2367
+ answered `ok: false`, or `E_ROSTER_BUDGET`: the roster's budget ran out
2368
+ before this target), with no `features` key.
2369
+ - **`probe.features`** (feature `server-probe-features`, OATS 0.49.0): the
2370
+ host's kernel features, relayed from the top-level `features` of its
2371
+ [`status --json`](#the-roster-oats-status---json), never probed: the roster
2372
+ runs no `version --json` and stores nothing. The answer is untrusted, so it
2373
+ is relayed only when it is an array of at most 256 entries, each a string
2374
+ of at most 64 characters matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`; then it is
2375
+ the host's list as answered (order and any duplicate kept). Anything else,
2376
+ even one bad entry among good ones, is `null`: never a filtered list. A
2377
+ host before 0.49.0 omits the key, so its group reads `null` too, whatever
2378
+ its version. Read it as `Array.isArray(probe?.features)`: not an array
2379
+ means unknown; `[]` is a valid answer (a host with no features), not
2380
+ unknown.
2116
2381
  - **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
2117
2382
  own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
2118
2383
  relayed verbatim, or `null` when the host reports none (a deployment
@@ -2328,6 +2593,11 @@ tree: `E_NO_WORKTREE`.
2328
2593
 
2329
2594
  - `observation.revision` is the HEAD oid (or `unborn`); `branch` is `null`
2330
2595
  when detached.
2596
+ - `recorded` is what the spawn recorded in `instance.json`: `branch` (`null`
2597
+ when none was recorded) and `repo`. `drift` is `true` only when a branch
2598
+ was recorded and the tree is not on it. A home spawned before 0.49.0 may
2599
+ record the word `"HEAD"` for a detached attached or checkout tree; no
2600
+ branch has that name, so it reads as `branch: null` with `drift: false`.
2331
2601
  - `upstream` without one is all `null` (unknown, not zero). `base` compares
2332
2602
  with the default branch's merge-base; `source` is `origin/HEAD` or
2333
2603
  `well-known`; none found is all `null` plus a note.
@@ -2352,8 +2622,11 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
2352
2622
  - `against` is the observed revision (the working tree against that commit,
2353
2623
  index included) or `"empty"` for an untracked file. A binary file has an
2354
2624
  empty patch; over 256 KiB, `truncated: true`.
2355
- - The read runs without external diff, textconv, fsmonitor, hooks, the
2356
- caller's Git environment or global config, and writes nothing (`readOnly`).
2625
+ - The read runs without external diff, textconv, fsmonitor, hooks, lazy
2626
+ fetch, the caller's Git environment or global config, and writes nothing
2627
+ (`readOnly`). An object a partial clone lacks is not fetched: the read
2628
+ fails with `E_GIT_FAILED` (with Git 2.44 or later; an older Git ignores
2629
+ `GIT_NO_LAZY_FETCH`).
2357
2630
  - If HEAD or the index moved, the id is not in the current observation, or
2358
2631
  anything moved during the read: `E_STALE_OBSERVATION` with
2359
2632
  `details.observation`. Re-observe; never render a diff of another tree.
@@ -2393,7 +2666,11 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2393
2666
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
2394
2667
  `launch` hook's warning at session start/restart, `data: {message}`),
2395
2668
  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
2396
- [Waiting on you](#waiting-on-you)). `producer` is `kernel`, a capability id,
2669
+ [Waiting on you](#waiting-on-you)), `worktree-added` (0.49.0, feature
2670
+ `worktree-event`: `oats worktree add` made an extra tree, `data: {purpose,
2671
+ path, branch, base, baseOid, remote, member, hooks}`, `remote` without
2672
+ credentials, `member` a key or `null`, `hooks` the `worktree` hooks'
2673
+ receipt). `producer` is `kernel`, a capability id,
2397
2674
  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
2398
2675
  `launched` is written by spawn and, since 0.40, once per session start or
2399
2676
  restart, as soon as the session exists (`data: {harness, backend,
@@ -2403,6 +2680,9 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2403
2680
  is dated at the receipt's launch time. The boundary is complete per log: a
2404
2681
  log that missed it gets a copy of the same row (same time and data), never
2405
2682
  a second one.
2683
+ - `spawned` carries `worktreeHooks` (the receipt `[{capability, ok,
2684
+ required, log, exitCode, …}]`) in its `data` only when the spawn ran
2685
+ `worktree` hooks (0.49.0).
2406
2686
  - `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
2407
2687
  reason?}`) is written to the workspace log only,
2408
2688
  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
@@ -2423,8 +2703,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2423
2703
  - **Incarnation.** Each row carries the writing home's `createdAt` (or
2424
2704
  `null` for old rows); the top-level `incarnation` is the current home's (or
2425
2705
  `null`). Earlier incarnations are returned as this address's history.
2426
- - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`).
2427
- A home has one address in storage, its real path (since 0.40.2): rows are
2706
+ - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`),
2707
+ or a retired one (below). A home has one address in storage, its real path (since 0.40.2): rows are
2428
2708
  written and matched under it, whatever spelling a writer or reader used (a
2429
2709
  deployment reached through a symlink, a symlinked agents root). The answer
2430
2710
  keeps the spelling it was asked in: the top-level `home` and every
@@ -2453,6 +2733,27 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2453
2733
  `oats status --dir <symlink>` could not see, are read now. They cannot
2454
2734
  surface a stale claim: such a session wrote its clears and its session
2455
2735
  boundaries under the real path too, so that history is complete.
2736
+ - **A retired instance** (#642) answers from its workspace log, which
2737
+ outlives the home. This applies only when no live home resolves: a live
2738
+ home of `<instance>` under the scope is always answered as above. Without
2739
+ `--home`, the kernel lists `<deployment>/.agents/events/*--<instance>.jsonl`
2740
+ (the deployment is the directory holding the scope's agents root) and takes
2741
+ the agent from the file name. One log answers for
2742
+ `<agents root>/<agent>/instances/<instance>`. Several (one name retired
2743
+ under two agents) refuse with `E_AMBIGUOUS_INSTANCE`, the message naming
2744
+ the count and asking for `--home`, and `details.candidates[]` listing each
2745
+ as `{root, agent, home}`. No log is `E_SESSION_UNKNOWN`, as before. A
2746
+ `--home` naming a removed home answers only when it is
2747
+ `<agents root>/<agent>/instances/<instance>` (compared by real path, so a
2748
+ symlinked spelling of the root is the same address) and
2749
+ `<deployment>/.agents/events/<agent>--<instance>.jsonl` exists; the agent
2750
+ is taken from the path. The logs are read from the scope's spelling of the
2751
+ home, and the answer's `home` (and each row's) is the `--home` as given.
2752
+ Any other removed `--home` is `E_HOME_MISMATCH`.
2753
+ The answer has the same shape as a live home's: the `home` source is
2754
+ `absent`, and `incarnation` is `null` (no `instance.json` remains), so
2755
+ `waitingOnYou` is `null` and `waitingClaims` is empty. The rows keep the
2756
+ incarnation they were written with.
2456
2757
  - **Window.** `count` is the rows after `--since`; `returned` the window
2457
2758
  (`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
2458
2759
  source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
@@ -2674,7 +2975,13 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2674
2975
  (`retirement.disposable.home`): `not copied: <roots> (<capability>)`, the
2675
2976
  roots as written in the manifest, in the order the baseline stores them
2676
2977
  (sorted by capability, then root), one group per capability, groups
2677
- separated by `; `. At most 16 roots are listed, then `, and N more`.
2978
+ separated by `; `. At most 16 roots are listed, and only as many as fit in
2979
+ about 1024 characters; the rest are `, and N more`. When not even one
2980
+ fits, the tail is `not copied: N declared roots, too long to list here`.
2981
+ The recovery path is never cut: when it is too long for the note, the
2982
+ note reads `recovery: the home is copied to the recovery directory beside
2983
+ the home … (its path is too long for this note: the retire receipt names
2984
+ it as workRecovery.path, and the retire summary prints it)`.
2678
2985
  The second is the line above in worktree mode, `recovery: work/ is copied
2679
2986
  there when it is not empty` in directory mode, and absent in checkout,
2680
2987
  attached and workspace modes. They are strings in `notes`: no other key
@@ -2697,12 +3004,37 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2697
3004
  - `reason`: `null` for `"remove"`, why the tree is not clean for
2698
3005
  `"retain"`, why it is refused for `"refuse"`.
2699
3006
 
2700
- `notes` also carries one string per tree that says the same. The trees are
3007
+ `notes` also carries one string per tree that says the same. When one is
3008
+ too long for a note, its longest parts (branch, repository, target,
3009
+ reason) are replaced, longest first, by a pointer to `facts.extraWorktrees`;
3010
+ the tree's path stays whole, or, when the path alone is too long, the note
3011
+ says `an extra worktree whose path is too long for this note …;
3012
+ facts.extraWorktrees in the plan JSON lists it`. The trees are
2701
3013
  part of `planRevision`: a tree created, removed, dirtied or cleaned between
2702
3014
  the plan and the apply, or a change of its disposition or target (another
2703
3015
  directory taking the `<leaf>-N` it would move to, for example), refuses a
2704
3016
  guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
2705
3017
  not know the key can ignore it; the `notes` strings say the same.
3018
+ - Every string in `notes` is at most 4096 characters, and a plan has at most
3019
+ 64 of them, the limits the Desktop reads (0.49.0, #658). The extra trees
3020
+ are the only notes whose number is not fixed: when they would pass 64, the
3021
+ last tree note kept says `and N more extra worktrees (facts.extraWorktrees
3022
+ in the plan JSON lists every one)`. A note never cuts a name or a path:
3023
+ the drift note gives way, longest name first, to a pointer to
3024
+ `facts.work.branch` or `facts.recordedBranch`; a session note whose reason
3025
+ is too long (a process's command line, a tmux error) points to
3026
+ `facts.session.note`.
3027
+ - A worktree-mode plan whose recorded children include attached instances
3028
+ that use this home's `work/` (`instance.json` `work: "attached"`, `work` a
3029
+ link to `<home>/work`, directly or through another link) has one note naming them (0.49.0, #718): `attached
3030
+ child instance(s) <names> use this home's work/ as their work: a retire
3031
+ that keeps the worktree repoints their work link to it; with
3032
+ --discard-worktree the worktree is removed and their work link will
3033
+ dangle`. It holds for either choice; no other key changes. A relink that
3034
+ fails is a string in the receipt's `warnings`.
3035
+ - `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
3036
+ (a detached checkout or attached spawn before 0.49.0, #641): it is not a
3037
+ branch name, so `facts.work.drift` is `false` for it as well.
2706
3038
 
2707
3039
  Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
2708
3040
  (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
@@ -2739,10 +3071,20 @@ A first retire prints the **raw receipt**, not an envelope:
2739
3071
  entry is gone is never touched: it is an incomplete item (`git worktree
2740
3072
  <path>: its admin entry is missing; …`), and `--force` refuses it with
2741
3073
  `E_WORK_PRESERVATION_FAILED`.
2742
- - `--discard-worktree` removes the worktree. No retire deletes a branch, a
2743
- retried or `--force`d quarantine included: `branchDeleted` is always
2744
- `false`, and `retention.branchDeleted` and `retention.branchDeletionSkipped`
2745
- are not written. `--delete-branch` is refused with `E_BAD_ARGS` (`oats
3074
+ - `--discard-worktree` removes the worktree, and verifies that it is gone (nothing
3075
+ at `work/`, not in `git worktree list`); a removal that did not happen, or
3076
+ cannot be verified, refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
3077
+ home, `--force` included. One exception: with no entry at all at `work/`
3078
+ (a dangling link is an entry) and a repository that cannot be read,
3079
+ `retention.worktree` is `"absent"`, never `"removed"`, and a quarantine
3080
+ retry keeps `could not verify removal` as an incomplete item, which only
3081
+ `--force` clears ([souls-and-instances.md](souls-and-instances.md)). No retire deletes a branch, a
3082
+ retried or `--force`d quarantine included, with the one exception below.
3083
+ `branchDeleted` means exactly "retire's own `--delete-branch`", which is
3084
+ refused, so it is always `false`; it does not say whether a branch was
3085
+ deleted. `spawnCompensation` (below) is the one place a branch deletion by
3086
+ retire is reported. `retention.branchDeleted` and
3087
+ `retention.branchDeletionSkipped` are not written. `--delete-branch` is refused with `E_BAD_ARGS` (`oats
2746
3088
  retire no longer deletes branches: …`) before any effect: before a plan
2747
3089
  revision is compared and before a recorded child is stopped. A failed
2748
3090
  spawn's quarantine that still owes the branch the spawn created stays
@@ -2754,6 +3096,23 @@ A first retire prints the **raw receipt**, not an envelope:
2754
3096
  Git cannot show it gone (`git branch <b>: could not verify whether it still
2755
3097
  exists (…)`). Such a home cannot be completed from Desktop: the operator
2756
3098
  deletes the branch with Git and retries, or uses `--force` from the CLI.
3099
+ - **The one exception** (feature `worktree-event`, OATS 0.49.0): a spawn
3100
+ killed while its `worktree` hooks ran (SIGKILL, or its rollback cut short)
3101
+ leaves a marker with `inProgress.branch` and `inProgress.baseOid`. Once
3102
+ that process is verified dead, retire ends the leftover hook process group,
3103
+ runs the retire hooks, removes the worktree and verifies the removal, and
3104
+ only then deletes the branch with an atomic compare-and-delete (`git
3105
+ update-ref -d refs/heads/<b> <baseOid>`), finishing the spawn's own
3106
+ compensation: a branch still at its creation commit holds no work. When
3107
+ the tip moved, the branch is checked out in any worktree, or the ref cannot
3108
+ be read, it is not deleted, and the retry stays incomplete with the
3109
+ "branch left" item above (the home is kept). `branchDeleted` stays
3110
+ `false` (retire's own `--delete-branch`); the step is reported in the
3111
+ additive `spawnCompensation`, the one place such a deletion is reported:
3112
+ `{branch, branchDeleted: true}`, or `{branch, branchDeleted: false, reason}`
3113
+ (`reason`: the tip moved, it is checked out in a worktree, it could not be
3114
+ read, or Git refused), present only when the step was reached. Desktop's
3115
+ retire-receipt reader accepts it as an unknown field.
2757
3116
  - Before the worktree is removed, HEAD is read again: a HEAD that moved since
2758
3117
  the retire's last inspection stops it with `E_WORK_PRESERVATION_FAILED`
2759
3118
  (`the worktree's HEAD changed after it was inspected, so the worktree was
@@ -2848,14 +3207,32 @@ A first retire prints the **raw receipt**, not an envelope:
2848
3207
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
2849
3208
  `{…, alreadyScheduled: true, requestedAt}`.
2850
3209
 
3210
+ **Recorded children**, on every apply (plain, guarded and `--self`), as the
3211
+ plan says: each child the plan lists is stopped first (bounded SIGTERM,
3212
+ never escalated) and kept, once the retire has resolved the home and before
3213
+ the instance's own session is stopped. `childrenStopped[]` lists them,
3214
+ deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
3215
+ `{instance, home, ok: false, code, message, stillRunning}`. A plain or
3216
+ `--self` receipt carries it only when there are children; a guarded receipt
3217
+ always does (`[]` when there are none). One child still running after the
3218
+ grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
3219
+ `E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
3220
+ `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
3221
+ `code`). **`--force` does not bypass it**: `--force` covers incomplete
3222
+ cleanup, not a running child. A `--self` retirement stops the children
3223
+ recorded when it was scheduled that are still instances (a child retired in
3224
+ between is skipped), in its detached completion before it stops the caller;
3225
+ a refusal there leaves the caller's window and home in place and
3226
+ writes `{ok: false, error: {code: "E_CHILDREN_RUNNING"}, childrenStopped,
3227
+ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
3228
+
2851
3229
  **Guarded apply** (what the Desktop sends): `--plan-revision` and
2852
3230
  `--idempotency-key` together.
2853
3231
  - A used key replays its receipt as an **envelope** with `replayed: true`
2854
3232
  (receipts live beside the instances directory and outlive the home).
2855
3233
  - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
2856
- - Children are stopped first (never escalated) and kept; `childrenStopped[]`
2857
- lists them. One still running refuses everything: `E_CHILDREN_RUNNING
2858
- {childrenStopped, plan}`.
3234
+ - The children stopped are those of the revalidated plan, and a refusal
3235
+ carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
2859
3236
  - A first guarded retire prints the raw receipt with `planRevision`,
2860
3237
  `idempotencyKey` and `replayed: false`.
2861
3238
 
@@ -2863,9 +3240,15 @@ Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
2863
3240
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
2864
3241
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
2865
3242
  not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
2866
- message names the entry or the state that could not be read),
3243
+ message names the entry or the state that could not be read, or the directory
3244
+ Git reads as the top level of a `work/` whose `core.worktree` names another
3245
+ one),
2867
3246
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
2868
- `E_NO_ROOT`, `E_LIFECYCLE_FAILED`. A recovery whose Git status disagrees with
3247
+ `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
3248
+ `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3249
+ row with `spawnInProgress: true`, `--force` included; or one whose start time
3250
+ cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
3251
+ group whose leader's start cannot be read, until `--force`). A recovery whose Git status disagrees with
2869
3252
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
2870
3253
  source, recovery}], total}}` (the first 10 paths). Usage errors are text on
2871
3254
  stderr, not envelopes.
@@ -3185,26 +3568,39 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3185
3568
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3186
3569
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3187
3570
  - `template?`: `{package, version, commit, template}`.
3188
- - `lastRun`: `{at, instance, home, event, number, key}`; `nextDue`: the
3571
+ - `lastRun`: `{at, instance, home, event, number, subject, key}`
3572
+ (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3573
+ for a run recorded before 0.49.0, its number); `nextDue`: the
3189
3574
  next poll here, `null` before the first.
3190
3575
  - `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
3191
3576
  runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
3192
- liveCount, live: [{instance, home, repo, number, event}], lastPoll: {at, ok:
3193
- true, prs, matching} | {at, ok: false, error} | null, nextPollAt, nextDue,
3194
- pending: [{key, event, number, url, observedAt}], fired: [{key, at,
3195
- instance, home, event, number}] (newest 50), firedTotal, lastError: {at,
3196
- code, message, key?} | null}]}`. It writes nothing.
3577
+ liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
3578
+ {at, ok: true, prs, matching} | {at, ok: false, error} | null, nextPollAt,
3579
+ nextDue, pending: [{key, event, number, subject, url, observedAt}], fired:
3580
+ [{key, at, instance, home, event, number, subject}] (newest 50), firedTotal,
3581
+ lastError: {at, code, message, key?} | null}]}`. It writes nothing.
3582
+ `subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
3583
+ PR's number, as a string. A record written before 0.49.0 has none, and
3584
+ its number is reported.
3197
3585
  - `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
3198
3586
  runsHere, reason, detail?, enabledHere}, gh: {ok, account,
3199
3587
  credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
3200
3588
  fullName, permissions: {push, maintain, admin}, canMerge} | {key, readable:
3201
3589
  false, error}, soul: {resolves, name, agent, messaging} | {resolves: false,
3202
3590
  name, error}, teams: {requested, undeclared | null, messaging}, wouldFire:
3203
- [{key, repo, number, event, url, held?}], pollError?, problems, warnings,
3204
- spawned: false}`. `ok` counts `problems` only; a credential the host timer
3205
- cannot reach is a warning.
3206
- - A triggered instance records `instance.json.trigger`; its event file is
3207
- `OATS_TRIGGER_EVENT_FILE`.
3591
+ [{key, repo, number, subject, event, url, instance, nameCut, held?}],
3592
+ pollError?, problems, warnings, spawned: false}`. `ok` counts `problems`
3593
+ only; a credential the host timer cannot reach is a warning. `instance`
3594
+ and `nameCut` (0.49.0) are the name the spawn would be asked to derive
3595
+ (`<stem>-<purpose as passed>`, before spawn's `-<n>`) and whether its
3596
+ purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
3597
+ `null` when the soul does not resolve or its name is too long for a
3598
+ triggered spawn (that error is then in `problems`).
3599
+ - A triggered instance records `instance.json.trigger`: `{id, key, source,
3600
+ repo, number, subject, url, event, headSha, observedAt, eventFile}`
3601
+ (`subject` since 0.49.0; `null` when the event had none). Its event file is
3602
+ `OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
3603
+ event, headSha, labels, observedAt, key}`.
3208
3604
  - `update <id> --description=<text>` (feature `automation-descriptions`)
3209
3605
  changes only a local trigger's description; `--description=` (empty)
3210
3606
  removes it. It sets `updatedAt` and leaves fired and pending events
@@ -3281,7 +3677,10 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3281
3677
  - The tick's `considered[]` holds schedule rows and trigger rows `{workspace,
3282
3678
  trigger, action, …}` with actions `not-due`, `poll-failed`, `polled`
3283
3679
  (`prs`, `matching`), `held`, `fired` (`key`, `instance`, `home`),
3284
- `spawn-failed` (`key`, `code`, `error`), `would-fire`, `invalid` and
3680
+ `spawn-failed` (`key`, `code`, `error`), `would-fire` (`key`, `event`,
3681
+ `number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
3682
+ soul as a tick does, and reports a preview failure or a name that cannot
3683
+ fit as `spawn-failed`), `invalid` and
3285
3684
  `not-here`. A workspace schedule's state key is `<member>~<id>`. A failed
3286
3685
  snapshot refresh is `{workspace, action: "error", error}`.
3287
3686