@awebai/oats 0.48.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 (41) hide show
  1. package/bin/oats.mjs +226 -14
  2. package/docs/capabilities.md +256 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +6 -0
  5. package/docs/desktop-cli-api.md +368 -31
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +17 -2
  8. package/docs/implementation.md +62 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +2 -2
  12. package/docs/packages.md +8 -8
  13. package/docs/release-notes/v0.49.0.md +770 -0
  14. package/docs/schedules.md +62 -39
  15. package/docs/servers.md +7 -0
  16. package/docs/souls-and-instances.md +381 -53
  17. package/docs/workspaces.md +2 -2
  18. package/injects/work-checkout.md +17 -11
  19. package/injects/work-worktree.md +19 -13
  20. package/lib/capability-contract.mjs +100 -11
  21. package/lib/capability-show.mjs +5 -2
  22. package/lib/core.mjs +1109 -321
  23. package/lib/instance-events.mjs +6 -3
  24. package/lib/instance-git.mjs +11 -5
  25. package/lib/instance-inspect.mjs +14 -3
  26. package/lib/instance-lifecycle.mjs +106 -16
  27. package/lib/instance-resolution.mjs +15 -3
  28. package/lib/launch-prompt-policy.mjs +17 -3
  29. package/lib/packages.mjs +1 -0
  30. package/lib/real-path.mjs +27 -0
  31. package/lib/resolve.mjs +4 -4
  32. package/lib/retire-output.mjs +6 -1
  33. package/lib/schedule.mjs +1 -0
  34. package/lib/servers.mjs +32 -6
  35. package/lib/tree-copy.mjs +18 -7
  36. package/lib/triggers.mjs +201 -65
  37. package/lib/workspace.mjs +20 -5
  38. package/lib/worktree-hooks.mjs +392 -0
  39. package/lib/worktree.mjs +655 -0
  40. package/package-catalog.json +1 -1
  41. package/package.json +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","teams-conditional-default"],
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}
@@ -113,6 +116,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
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)) | |
115
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)) | |
116
121
 
117
122
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
118
123
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -370,6 +375,7 @@ An instance subject, abridged:
370
375
  | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
371
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 |
372
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 |
373
379
 
374
380
  **Soul row** (`soulsApi: 2`). For a home it is read from the recorded
375
381
  `soulDir` (`path` and `kind` are `null`); for a soul it is the member's current
@@ -492,6 +498,9 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
492
498
  ready}` (`ready` also needs no subject blocker). `subjectBlockers[]` is
493
499
  `{check, subject, status}` for each failing required item not about a
494
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.
495
504
 
496
505
  **`installed`**, one item per module with `evidence: {from}`. `--home`
497
506
  (producer `instance modules`): passes when the home's copy holds `oats.json`
@@ -755,7 +764,10 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
755
764
  "no-catalog", catalog, path, message}`), `E_AUTOMATION_SCHEMA` and
756
765
  `E_AUTOMATION_DUPLICATE` (with `kind`). A problem never aborts the sync.
757
766
  - `warnings[]`: `soul-private-ignored {code, soul, repoKey, path, message}`
758
- 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)).
759
771
  - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
760
772
  `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
761
773
  `E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
@@ -983,6 +995,11 @@ nothing reads a working clone.
983
995
  is a list of `{name, path, description, files, filesTruncated}`, each file
984
996
  `{path, bytes}`, or `null`. `problems` is a list of `{code, message,
985
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`).
986
1003
  - With `--max-age` (`0` included) both the show and the `--file` answer gain
987
1004
  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
988
1005
  block `{observedAt, reused, localRevision}`.
@@ -1082,6 +1099,37 @@ problems. `--file` prints the text; a binary file prints a one-line note
1082
1099
  instead, and a truncated file prints its text followed by a one-line note.
1083
1100
 
1084
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
+
1085
1133
  ### Desktop facts
1086
1134
 
1087
1135
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -1718,6 +1766,7 @@ it to a temporary copy (`soulFetched: true`).
1718
1766
  "preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
1719
1767
  "harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
1720
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}],
1721
1770
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
1722
1771
  "executable":"/usr/local/bin/pi",
1723
1772
  "capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
@@ -1737,7 +1786,17 @@ it to a temporary copy (`soulFetched: true`).
1737
1786
  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
1738
1787
  cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
1739
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)).
1740
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.
1741
1800
 
1742
1801
  **Launch.**
1743
1802
  - `harness`, `model`, `modelSource`, `launchConfig`, `backend`, `yolo`
@@ -1884,7 +1943,12 @@ with `--expect-decision` records the key and decision in `instance.json`.
1884
1943
  read `tmux` for the target.
1885
1944
  - When they apply: `yolo`, `decision` and
1886
1945
  `replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
1887
- `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)).
1888
1952
 
1889
1953
  <a id="instance-names"></a>
1890
1954
  ### Instance names
@@ -1930,6 +1994,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
1930
1994
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
1931
1995
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
1932
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 |
1933
2000
  | `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
1934
2001
 
1935
2002
  Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
@@ -1938,6 +2005,116 @@ cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
1938
2005
  Confirmed completed compensation does not set this marker. This is an additive
1939
2006
  producer migration; existing text-based compatibility checks remain.
1940
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
+
1941
2118
  ## `instance.json` and the roster
1942
2119
 
1943
2120
  <a id="instancejson"></a>
@@ -1976,6 +2153,15 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
1976
2153
  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
1977
2154
  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
1978
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).
1979
2165
  - `base` (a worktree instance): `{ref, oid}`, the commit its branch started
1980
2166
  at, as the spawn result states it (see Placement under the spawn preview).
1981
2167
  - `providers.<cap>`: the merged payload (`{}` when none).
@@ -2001,8 +2187,10 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
2001
2187
  oats status [--dir <d>] [--max-age <s>] --json
2002
2188
  ```
2003
2189
 
2004
- Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
2190
+ Not an envelope: `{root, agents, observation?, features, workspace?, problems?, warnings?}`
2005
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.
2006
2194
 
2007
2195
  ```json
2008
2196
  {"root":"/w/agents",
@@ -2013,6 +2201,7 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2013
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"},
2014
2202
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
2015
2203
  "soul":{"repoKey":"github.com/nw/agents","commit":"66566512…","current":"66566512…","status":"current"}}]}],
2204
+ "features":["retire-home","session-start","…","server-probe-features"],
2016
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"},
2017
2206
  "teams":{"eng":"eng:nw.aweb.ai","mine":"mine:ana.aweb.ai","ops":null},"teamsFrom":"observed"}}
2018
2207
  ```
@@ -2037,6 +2226,16 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2037
2226
  in the row),
2038
2227
  `identity` when a provider recorded one, `rollbackIncomplete` and
2039
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.
2040
2239
  - **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
2041
2240
  message}` when the row is `running: true` and a producer holds a live claim
2042
2241
  that the instance needs input from a human, else `null` (unknown, not "not
@@ -2060,6 +2259,12 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2060
2259
  message}` (modules then stay the recorded map), plus the deployment's
2061
2260
  [workspace identity](#workspace-identity-feature-workspace-identity-oats-0360)
2062
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.
2063
2268
  - `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
2064
2269
  `warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
2065
2270
 
@@ -2139,7 +2344,7 @@ route target:
2139
2344
  ```json
2140
2345
  {"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
2141
2346
  "target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
2142
- "probe":{"ok":true},"agentsRoot":"/srv/team/agents",
2347
+ "probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
2143
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"},
2144
2349
  "teams":{"default":"acme:team"},"teamsFrom":"observed"},
2145
2350
  "souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
@@ -2157,6 +2362,22 @@ route target:
2157
2362
  "retireFailures":[]}
2158
2363
  ```
2159
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.
2160
2381
  - **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
2161
2382
  own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
2162
2383
  relayed verbatim, or `null` when the host reports none (a deployment
@@ -2372,6 +2593,11 @@ tree: `E_NO_WORKTREE`.
2372
2593
 
2373
2594
  - `observation.revision` is the HEAD oid (or `unborn`); `branch` is `null`
2374
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`.
2375
2601
  - `upstream` without one is all `null` (unknown, not zero). `base` compares
2376
2602
  with the default branch's merge-base; `source` is `origin/HEAD` or
2377
2603
  `well-known`; none found is all `null` plus a note.
@@ -2396,8 +2622,11 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
2396
2622
  - `against` is the observed revision (the working tree against that commit,
2397
2623
  index included) or `"empty"` for an untracked file. A binary file has an
2398
2624
  empty patch; over 256 KiB, `truncated: true`.
2399
- - The read runs without external diff, textconv, fsmonitor, hooks, the
2400
- 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`).
2401
2630
  - If HEAD or the index moved, the id is not in the current observation, or
2402
2631
  anything moved during the read: `E_STALE_OBSERVATION` with
2403
2632
  `details.observation`. Re-observe; never render a diff of another tree.
@@ -2437,7 +2666,11 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2437
2666
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
2438
2667
  `launch` hook's warning at session start/restart, `data: {message}`),
2439
2668
  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
2440
- [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,
2441
2674
  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
2442
2675
  `launched` is written by spawn and, since 0.40, once per session start or
2443
2676
  restart, as soon as the session exists (`data: {harness, backend,
@@ -2447,6 +2680,9 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2447
2680
  is dated at the receipt's launch time. The boundary is complete per log: a
2448
2681
  log that missed it gets a copy of the same row (same time and data), never
2449
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).
2450
2686
  - `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
2451
2687
  reason?}`) is written to the workspace log only,
2452
2688
  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
@@ -2467,8 +2703,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2467
2703
  - **Incarnation.** Each row carries the writing home's `createdAt` (or
2468
2704
  `null` for old rows); the top-level `incarnation` is the current home's (or
2469
2705
  `null`). Earlier incarnations are returned as this address's history.
2470
- - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`).
2471
- 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
2472
2708
  written and matched under it, whatever spelling a writer or reader used (a
2473
2709
  deployment reached through a symlink, a symlinked agents root). The answer
2474
2710
  keeps the spelling it was asked in: the top-level `home` and every
@@ -2497,6 +2733,27 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2497
2733
  `oats status --dir <symlink>` could not see, are read now. They cannot
2498
2734
  surface a stale claim: such a session wrote its clears and its session
2499
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.
2500
2757
  - **Window.** `count` is the rows after `--since`; `returned` the window
2501
2758
  (`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
2502
2759
  source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
@@ -2718,7 +2975,13 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2718
2975
  (`retirement.disposable.home`): `not copied: <roots> (<capability>)`, the
2719
2976
  roots as written in the manifest, in the order the baseline stores them
2720
2977
  (sorted by capability, then root), one group per capability, groups
2721
- 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)`.
2722
2985
  The second is the line above in worktree mode, `recovery: work/ is copied
2723
2986
  there when it is not empty` in directory mode, and absent in checkout,
2724
2987
  attached and workspace modes. They are strings in `notes`: no other key
@@ -2741,12 +3004,37 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2741
3004
  - `reason`: `null` for `"remove"`, why the tree is not clean for
2742
3005
  `"retain"`, why it is refused for `"refuse"`.
2743
3006
 
2744
- `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
2745
3013
  part of `planRevision`: a tree created, removed, dirtied or cleaned between
2746
3014
  the plan and the apply, or a change of its disposition or target (another
2747
3015
  directory taking the `<leaf>-N` it would move to, for example), refuses a
2748
3016
  guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
2749
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.
2750
3038
 
2751
3039
  Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
2752
3040
  (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
@@ -2783,10 +3071,20 @@ A first retire prints the **raw receipt**, not an envelope:
2783
3071
  entry is gone is never touched: it is an incomplete item (`git worktree
2784
3072
  <path>: its admin entry is missing; …`), and `--force` refuses it with
2785
3073
  `E_WORK_PRESERVATION_FAILED`.
2786
- - `--discard-worktree` removes the worktree. No retire deletes a branch, a
2787
- retried or `--force`d quarantine included: `branchDeleted` is always
2788
- `false`, and `retention.branchDeleted` and `retention.branchDeletionSkipped`
2789
- 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
2790
3088
  retire no longer deletes branches: …`) before any effect: before a plan
2791
3089
  revision is compared and before a recorded child is stopped. A failed
2792
3090
  spawn's quarantine that still owes the branch the spawn created stays
@@ -2798,6 +3096,23 @@ A first retire prints the **raw receipt**, not an envelope:
2798
3096
  Git cannot show it gone (`git branch <b>: could not verify whether it still
2799
3097
  exists (…)`). Such a home cannot be completed from Desktop: the operator
2800
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.
2801
3116
  - Before the worktree is removed, HEAD is read again: a HEAD that moved since
2802
3117
  the retire's last inspection stops it with `E_WORK_PRESERVATION_FAILED`
2803
3118
  (`the worktree's HEAD changed after it was inspected, so the worktree was
@@ -2925,9 +3240,15 @@ Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
2925
3240
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
2926
3241
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
2927
3242
  not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
2928
- 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),
2929
3246
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
2930
- `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
2931
3252
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
2932
3253
  source, recovery}], total}}` (the first 10 paths). Usage errors are text on
2933
3254
  stderr, not envelopes.
@@ -3247,26 +3568,39 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3247
3568
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3248
3569
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3249
3570
  - `template?`: `{package, version, commit, template}`.
3250
- - `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
3251
3574
  next poll here, `null` before the first.
3252
3575
  - `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
3253
3576
  runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
3254
- liveCount, live: [{instance, home, repo, number, event}], lastPoll: {at, ok:
3255
- true, prs, matching} | {at, ok: false, error} | null, nextPollAt, nextDue,
3256
- pending: [{key, event, number, url, observedAt}], fired: [{key, at,
3257
- instance, home, event, number}] (newest 50), firedTotal, lastError: {at,
3258
- 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.
3259
3585
  - `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
3260
3586
  runsHere, reason, detail?, enabledHere}, gh: {ok, account,
3261
3587
  credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
3262
3588
  fullName, permissions: {push, maintain, admin}, canMerge} | {key, readable:
3263
3589
  false, error}, soul: {resolves, name, agent, messaging} | {resolves: false,
3264
3590
  name, error}, teams: {requested, undeclared | null, messaging}, wouldFire:
3265
- [{key, repo, number, event, url, held?}], pollError?, problems, warnings,
3266
- spawned: false}`. `ok` counts `problems` only; a credential the host timer
3267
- cannot reach is a warning.
3268
- - A triggered instance records `instance.json.trigger`; its event file is
3269
- `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}`.
3270
3604
  - `update <id> --description=<text>` (feature `automation-descriptions`)
3271
3605
  changes only a local trigger's description; `--description=` (empty)
3272
3606
  removes it. It sets `updatedAt` and leaves fired and pending events
@@ -3343,7 +3677,10 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3343
3677
  - The tick's `considered[]` holds schedule rows and trigger rows `{workspace,
3344
3678
  trigger, action, …}` with actions `not-due`, `poll-failed`, `polled`
3345
3679
  (`prs`, `matching`), `held`, `fired` (`key`, `instance`, `home`),
3346
- `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
3347
3684
  `not-here`. A workspace schedule's state key is `<member>~<id>`. A failed
3348
3685
  snapshot refresh is `{workspace, action: "error", error}`.
3349
3686