@awebai/oats 0.48.0 → 0.50.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 (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. 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","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,9 @@ 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
+ | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
121
+ | `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
122
 
117
123
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
118
124
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -215,6 +221,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
215
221
  | teams | soul teams <soul> … --max-age <seconds> --json
216
222
  oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
217
223
  oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
224
+ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
218
225
  ```
219
226
 
220
227
  - **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
@@ -274,8 +281,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
274
281
  `E_BAD_ARGS` first), with
275
282
  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
276
283
  verbs reuse observations (status, workspace status, souls, capabilities,
277
- capabilities show, inspect --soul|--home, spawn --preview, and the read
278
- forms of teams and soul teams)" and,
284
+ capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
285
+ and the read forms of teams and soul teams)" and,
279
286
  with `--server`, "--max-age cannot be combined with --server: observation
280
287
  reuse is local to this machine".
281
288
  A capability command's argv (`oats <namespace> …`) is its provider's: the
@@ -370,6 +377,7 @@ An instance subject, abridged:
370
377
  | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
371
378
  | `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
379
  | `problems` | below |
380
+ | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
373
381
 
374
382
  **Soul row** (`soulsApi: 2`). For a home it is read from the recorded
375
383
  `soulDir` (`path` and `kind` are `null`); for a soul it is the member's current
@@ -492,6 +500,9 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
492
500
  ready}` (`ready` also needs no subject blocker). `subjectBlockers[]` is
493
501
  `{check, subject, status}` for each failing required item not about a
494
502
  capability. `notes` is prose.
503
+ - `warnings` (0.49.0) is always present: the
504
+ [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)
505
+ of the subject's capabilities. They are not items and change no status.
495
506
 
496
507
  **`installed`**, one item per module with `evidence: {from}`. `--home`
497
508
  (producer `instance modules`): passes when the home's copy holds `oats.json`
@@ -755,7 +766,10 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
755
766
  "no-catalog", catalog, path, message}`), `E_AUTOMATION_SCHEMA` and
756
767
  `E_AUTOMATION_DUPLICATE` (with `kind`). A problem never aborts the sync.
757
768
  - `warnings[]`: `soul-private-ignored {code, soul, repoKey, path, message}`
758
- for a soul.yaml still carrying `private`.
769
+ for a soul.yaml still carrying `private`; then (0.49.0)
770
+ `hook-event-unsupported {code, capability, path, message}` per hook event a
771
+ listed member capability declares and this kernel does not run
772
+ ([capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)).
759
773
  - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
760
774
  `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
761
775
  `E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
@@ -983,6 +997,20 @@ nothing reads a working clone.
983
997
  is a list of `{name, path, description, files, filesTruncated}`, each file
984
998
  `{path, bytes}`, or `null`. `problems` is a list of `{code, message,
985
999
  path}`.
1000
+ - `warnings` (0.49.0) is always present, on the show and the `--file`
1001
+ answer: the capability's
1002
+ [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
1003
+ Their `path` is the repository-relative form, unlike the paths above. The
1004
+ text form prints them (to stderr with `--file`).
1005
+ - `triggerSources` (feature `trigger-sources`), after
1006
+ `warnings`, only when the manifest declares the key: the declaration
1007
+ exactly as written, whatever its shape (untrusted text: render it as
1008
+ text). `triggerSourceProblems: [{source, pointer, message}]` follows only
1009
+ when the declaration has problems: the ones a trigger naming a source
1010
+ would get as `E_TRIGGER_SOURCE`, `source` `null` for a top-level problem,
1011
+ `pointer` a JSON pointer into the manifest. A malformed declaration never
1012
+ refuses the command and adds nothing to `problems`
1013
+ ([capabilities.md](capabilities.md#trigger-sources-triggersources)).
986
1014
  - With `--max-age` (`0` included) both the show and the `--file` answer gain
987
1015
  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
988
1016
  block `{observedAt, reused, localRevision}`.
@@ -1077,11 +1105,49 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
1077
1105
  (`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
1078
1106
 
1079
1107
  **Without `--json`** the show prints a short listing for an operator: the
1080
- inject's path and size, each skill with its files and sizes, and the
1108
+ inject's path and size, each skill with its files and sizes, the trigger
1109
+ sources (name, command, events, description) and their problems, and the
1081
1110
  problems. `--file` prints the text; a binary file prints a one-line note
1082
1111
  instead, and a truncated file prints its text followed by a one-line note.
1083
1112
 
1084
1113
  <a id="desktop-facts-feature-desktop-facts-oats-0290"></a>
1114
+ ### Capability warnings (`hook-event-unsupported`, OATS 0.49.0)
1115
+
1116
+ A capability may declare a hook event this kernel does not run (a newer
1117
+ kernel's). It composes, the event never runs, and each answer that shows the
1118
+ capability carries one warning per such event
1119
+ ([capabilities.md](capabilities.md#manifest)):
1120
+
1121
+ ```json
1122
+ {"code":"hook-event-unsupported","capability":"acme.tool",
1123
+ "path":"github.com/acme/agents:capabilities/acme-tool/oats.json#/hooks/on-merge",
1124
+ "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)"}
1125
+ ```
1126
+
1127
+ | Answer | Where | Covers |
1128
+ |---|---|---|
1129
+ | `oats sync`, `oats workspace status` | `warnings[]`, beside `soul-private-ignored` | every listed member capability |
1130
+ | `oats capabilities show` (and `--file`) | `warnings[]`, always present | the capability shown |
1131
+ | `oats inspect`, `oats readiness` | `warnings[]`, always present | `--soul`: the soul's resolved modules; `--home`: the home's module copies |
1132
+ | `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 |
1133
+ | `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 |
1134
+
1135
+ `path` is never an absolute host path. It is `<repoKey>:<dir>/oats.json#<pointer>`
1136
+ for a member capability, `package:<id>:<dir>/oats.json#<pointer>` for a
1137
+ package capability (`<dir>` relative to the repository), and, for `--home`,
1138
+ `.oats/modules/<name>/oats.json#<pointer>`, relative to the home: the copy
1139
+ actually read. Without `--soul`, doctor reads only this machine's cache; what
1140
+ it cannot answer is one `information[]` line `hook-events-unchecked: <member
1141
+ capabilities | package <id>'s capabilities> were not checked …`, never an
1142
+ empty list read as "no warning". Older kernels answer no such `warnings` key
1143
+ (inspect, readiness, show, doctor) and refuse the capability instead.
1144
+
1145
+ `oats doctor --json` also lists what retires left behind in `information[]`:
1146
+ one `retained-recovery:` and one `retained-worktree:` line per item, after a
1147
+ line that gives each kind's total, and at most 50 items per kind
1148
+ ([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
1149
+ Each element is one line of text with no newline. The answer has no new key.
1150
+
1085
1151
  ### Desktop facts
1086
1152
 
1087
1153
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -1718,6 +1784,7 @@ it to a temporary copy (`soulFetched: true`).
1718
1784
  "preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
1719
1785
  "harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
1720
1786
  "branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
1787
+ "worktreeHooks":[{"capability":"nw-tools","required":true}],
1721
1788
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
1722
1789
  "executable":"/usr/local/bin/pi",
1723
1790
  "capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
@@ -1737,7 +1804,17 @@ it to a temporary copy (`soulFetched: true`).
1737
1804
  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
1738
1805
  cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
1739
1806
  preview and apply alike.
1807
+ - `worktreeHooks` (feature `worktree-event`, OATS 0.49.0): for a `worktree`
1808
+ spawn, the capabilities whose `worktree` hook the spawn would fire, in the
1809
+ order they run, as `[{capability, required}]` (`[]` when none declares
1810
+ one); `null` in every other mode. `worktree` stays the path string. The
1811
+ text preview prints `worktree hooks: a, b (required)` or `worktree hooks:
1812
+ none` ([the worktree event](capabilities.md#the-worktree-event)).
1740
1813
  - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
1814
+ - `warnings`, present only when there is one, is an array of strings: the
1815
+ launch-prompt notice, and (0.49.0) the message of each
1816
+ [capability warning](#capability-warnings-hook-event-unsupported-oats-0490)
1817
+ of the resolved modules. The apply's `warnings` carries the same messages.
1741
1818
 
1742
1819
  **Launch.**
1743
1820
  - `harness`, `model`, `modelSource`, `launchConfig`, `backend`, `yolo`
@@ -1884,7 +1961,12 @@ with `--expect-decision` records the key and decision in `instance.json`.
1884
1961
  read `tmux` for the target.
1885
1962
  - When they apply: `yolo`, `decision` and
1886
1963
  `replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
1887
- `wakeScheduleError` (a requested wake).
1964
+ `wakeScheduleError` (a requested wake), `worktreeHooks` (feature
1965
+ `worktree-event`: only when the spawn ran `worktree` hooks, the receipt
1966
+ `[{capability, ok, required, log, exitCode, signal?, timedOut?,
1967
+ contract?}]`, `log` being the hook's log file).
1968
+ - A spawn that runs `worktree` hooks can take up to 30 minutes per hook
1969
+ ([the worktree event](capabilities.md#the-worktree-event)).
1888
1970
 
1889
1971
  <a id="instance-names"></a>
1890
1972
  ### Instance names
@@ -1930,6 +2012,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
1930
2012
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
1931
2013
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
1932
2014
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
2015
+ | `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 |
2016
+ | `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` |
2017
+ | `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
2018
  | `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
1934
2019
 
1935
2020
  Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
@@ -1938,6 +2023,116 @@ cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
1938
2023
  Confirmed completed compensation does not set this marker. This is an additive
1939
2024
  producer migration; existing text-based compatibility checks remain.
1940
2025
 
2026
+ <a id="oats-worktree"></a>
2027
+ ### `oats worktree`
2028
+
2029
+ Feature `worktree-event` (OATS 0.49.0). An instance's extra trees,
2030
+ `<home>/.work-<purpose>`, made and removed from its home
2031
+ ([extra trees](souls-and-instances.md#extra-trees)). There is no `--home`,
2032
+ `--dir` or `--server`: the home is `$OATS_INSTANCE_HOME` (or `$OATS_HOME`),
2033
+ else the home enclosing the working directory.
2034
+
2035
+ ```text
2036
+ oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]
2037
+ oats worktree remove --purpose <p> [--json]
2038
+ ```
2039
+
2040
+ `add` creates the tree with Git, fires the `worktree` hooks
2041
+ ([the worktree event](capabilities.md#the-worktree-event)), writes
2042
+ `<home>/.oats/trees/<p>.json` and appends a `worktree-added` event. It can run
2043
+ for minutes; the hooks' output goes to stderr, and stdout holds only the
2044
+ envelope. A reader that closes either pipe early only stops reading: the add
2045
+ runs to its end (and its record to `ready`), the hooks' logs are whole, and
2046
+ what could not be printed is dropped. Its result:
2047
+
2048
+ ```json
2049
+ {"purpose":"docs","path":"/w/agents/dev/instances/dev-1/.work-docs","clone":"/w/docs","remote":"https://github.com/nw/docs.git",
2050
+ "member":"github.com/nw/docs","branch":"agents/dev-1-docs","base":"main","baseOid":"9f2c41d0…","state":"ready",
2051
+ "hooks":[{"capability":"nw-setup","ok":true,"required":true,"log":"/w/agents/dev/instances/dev-1/.oats/logs/worktree-docs-nw-setup.log","exitCode":0}],
2052
+ "record":"/w/agents/dev/instances/dev-1/.oats/trees/docs.json","resumed":false,"warnings":[]}
2053
+ ```
2054
+
2055
+ - `remote` never carries credentials; `member` is a member key or `null`.
2056
+ - `resumed: true`: a `ready` record with the same clone, branch and base was
2057
+ found; nothing ran, and the result is the recorded receipt.
2058
+ - `treeMissing: true` appears when a non-required hook removed or moved the
2059
+ tree.
2060
+ - `--preview` fetches and writes nothing: `{preview: true, purpose, path,
2061
+ clone, remote, member, branch, base, record, resume, hooks}`, `resume`
2062
+ being `null` or `"recover"` (an interrupted add is rolled back first), and
2063
+ `hooks` the hooks that would run, `[{capability, required}]`. When the tree
2064
+ is already made, it is the recorded receipt with `preview: true`,
2065
+ `resume: "noop"` and `hooksToRun: []`.
2066
+
2067
+ `remove` answers `{purpose, path, removed: true, rolledBack, branch,
2068
+ branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
2069
+ `rolledBack` is `false` and `branchKept` is `true`. When it completed an
2070
+ interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
2071
+ whether the branch still exists. The rollback deletes the branch only when
2072
+ that add created it, no worktree has it checked out, and it still points at
2073
+ the commit the add created it at. A branch kept for one of those reasons is
2074
+ named in `branchKeptReason`, and is not debt.
2075
+
2076
+ The rollback signals a hook process group that the interrupted add left only
2077
+ when the group's leader is alive with its recorded start time. A group whose
2078
+ leader has exited is never signalled, because its id may already belong to
2079
+ an unrelated group. Instead `warnings` names it, so that leftover processes
2080
+ can be ended by hand.
2081
+
2082
+ Every `add` or `remove` that reads a record it may act on holds the
2083
+ purpose's claim, `<home>/.oats/trees/<purpose>.lock`. The claim is a file
2084
+ that names its holder by pid and start time. A second command waits up to
2085
+ 3 s for a live holder, then answers `E_LIFECYCLE_BUSY` (`details.lock`,
2086
+ `details.pid`). A claim whose holder has died, for example one killed in the
2087
+ middle of a recovery, is taken over by the next command. So a killed `add`
2088
+ or `remove` can always be run again.
2089
+
2090
+ A killed parent does not take its running git with it. So every git step
2091
+ that changes a tree, a ref or the worktree list runs in its own process
2092
+ group, and is recorded (pid and start time) before it starts: in the claim,
2093
+ or for an `add`'s own steps, in the tree record. A takeover or recovery
2094
+ first ends a recorded git step that still runs, signalling it only while its
2095
+ leader runs with the recorded start time (SIGTERM, which git answers by
2096
+ removing its lock files, then SIGKILL). Only then does it act, so a dead
2097
+ command's git never finishes late on a tree or branch made after it. A git
2098
+ step that times out is cleared from the record only once its whole process
2099
+ group is gone. A git step that cannot be ended keeps the claim, or the
2100
+ record, and the command answers `E_LIFECYCLE_BUSY`.
2101
+
2102
+ A recorded hook group or git step that still has members while its leader's
2103
+ start cannot be read (where `ps` fails) is never signalled and never passed
2104
+ over: the leader may still be that hook or git step. The command answers
2105
+ `E_LIFECYCLE_BUSY`, keeping the claim or the record and touching nothing
2106
+ else. Its message names the group, its recorded start, why the start cannot
2107
+ be read and the way out: check the group by hand; if it is that step, end it
2108
+ (`kill -TERM -- -<pgid>`) and retry; if it is not, remove the claim or the
2109
+ record it names (a record with what that add left) and retry. A claim's refusal
2110
+ carries `details.gitPid` and `details.gitStart`.
2111
+
2112
+ A failed `add` reports the same facts about its rollback in `details`:
2113
+ `rolledBack`, `branchKept`, `branchKeptReason` and `warnings`.
2114
+
2115
+ | Code | When |
2116
+ |---|---|
2117
+ | `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`) |
2118
+ | `E_INSTANCE_RETIRING` | `add` in a quarantined home, or one being retired |
2119
+ | `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
2120
+ | `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
2121
+ | `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>` |
2122
+ | `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 |
2123
+ | `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 |
2124
+ | `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`) |
2125
+ | `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
2126
+ | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
2127
+ | `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`) |
2128
+ | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2129
+ | `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 |
2130
+ | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2131
+
2132
+ A rollback that cannot finish keeps the record and says so in the message
2133
+ (`details.rolledBack: false`, `details.owed`); the next `add` or `remove` of
2134
+ that purpose finishes it.
2135
+
1941
2136
  ## `instance.json` and the roster
1942
2137
 
1943
2138
  <a id="instancejson"></a>
@@ -1976,6 +2171,15 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
1976
2171
  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
1977
2172
  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
1978
2173
  `<home>/.agents/skills/<cap>/<skill>/`).
2174
+ - `branch`: for a worktree instance, the branch its worktree was created on.
2175
+ For an attached or checkout instance, the branch the tree's HEAD named at
2176
+ the spawn, or `null` when HEAD was detached or named a ref OATS carries no
2177
+ branch name for (one whose name is not valid UTF-8); never the word
2178
+ `"HEAD"`. The key is absent when the tree's HEAD could not be read, and for
2179
+ directory and workspace instances. A home spawned before 0.49.0 may record
2180
+ `"HEAD"` for a detached tree; [`oats instance git`](#instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247)
2181
+ reads it as no recorded branch. The roster row and the spawn result carry
2182
+ the same value (the spawn result has `null` where the key is absent).
1979
2183
  - `base` (a worktree instance): `{ref, oid}`, the commit its branch started
1980
2184
  at, as the spawn result states it (see Placement under the spawn preview).
1981
2185
  - `providers.<cap>`: the merged payload (`{}` when none).
@@ -2001,8 +2205,10 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
2001
2205
  oats status [--dir <d>] [--max-age <s>] --json
2002
2206
  ```
2003
2207
 
2004
- Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
2208
+ Not an envelope: `{root, agents, observation?, features, workspace?, problems?, warnings?}`
2005
2209
  (`observation` only with [`--max-age`](#observation-reuse-feature-observe-max-age-oats-0311)).
2210
+ It carries no `schemaVersion`: a remote caller recognizes the bare roster by
2211
+ its absence.
2006
2212
 
2007
2213
  ```json
2008
2214
  {"root":"/w/agents",
@@ -2013,6 +2219,7 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2013
2219
  "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
2220
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
2015
2221
  "soul":{"repoKey":"github.com/nw/agents","commit":"66566512…","current":"66566512…","status":"current"}}]}],
2222
+ "features":["retire-home","session-start","…","server-probe-features"],
2016
2223
  "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
2224
  "teams":{"eng":"eng:nw.aweb.ai","mine":"mine:ana.aweb.ai","ops":null},"teamsFrom":"observed"}}
2018
2225
  ```
@@ -2031,12 +2238,26 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2031
2238
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2032
2239
  the row's recorded tmux socket and session, never the caller's `$TMUX`;
2033
2240
  `null` with `runtimeState: "unreachable"` and the tmux error as
2034
- `runtimeError` when that server cannot be read; `null` for a home a
2241
+ `runtimeError` when that server cannot be read, and also when its socket
2242
+ file is missing while a process works in the home or the process scan
2243
+ cannot run, `runtimeError` then naming the processes or the scan's error
2244
+ ([#624](execution-targets.md#missing-socket); with no process in the home
2245
+ a missing socket file reads `false`, as after a reboot); `null` for a home a
2035
2246
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2036
2247
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2037
2248
  in the row),
2038
2249
  `identity` when a provider recorded one, `rollbackIncomplete` and
2039
2250
  `retirePending` when present, and the Desktop facts below.
2251
+ - **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
2252
+ while a spawn that is running its `worktree` hooks is verifiably alive (its
2253
+ pid runs with the recorded start time). Such a home holds the quarantine marker
2254
+ with an `inProgress` field ([capabilities.md](capabilities.md#manifest)),
2255
+ and its row carries `spawnInProgress: true` and **no**
2256
+ `rollbackIncomplete`: a live spawn, not a failed one. Once that process is
2257
+ gone, or when its start time cannot be read (where `ps` fails), the row
2258
+ carries `rollbackIncomplete` as for any quarantine, its `inProgress` naming
2259
+ the pid; retire still refuses an unreadable one with `E_LIFECYCLE_BUSY`
2260
+ until `--force`. Absent otherwise, and from older kernels.
2040
2261
  - **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
2041
2262
  message}` when the row is `running: true` and a producer holds a live claim
2042
2263
  that the instance needs input from a human, else `null` (unknown, not "not
@@ -2060,6 +2281,12 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
2060
2281
  message}` (modules then stay the recorded map), plus the deployment's
2061
2282
  [workspace identity](#workspace-identity-feature-workspace-identity-oats-0360)
2062
2283
  either way. Absent without `oats-local.yaml`.
2284
+ - **`features`** (feature `server-probe-features`, OATS 0.49.0): the
2285
+ running kernel's own feature list, the same array as `version --json`
2286
+ `features`, so a [remote roster](#the-remote-roster-oats-server-roster---json)
2287
+ relays a host's features from the status answer it already pulls. It is
2288
+ emitted at output time, never part of a reused observation. A kernel
2289
+ before 0.49.0 omits it.
2063
2290
  - `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
2064
2291
  `warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
2065
2292
 
@@ -2139,7 +2366,7 @@ route target:
2139
2366
  ```json
2140
2367
  {"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
2141
2368
  "target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
2142
- "probe":{"ok":true},"agentsRoot":"/srv/team/agents",
2369
+ "probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
2143
2370
  "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
2371
  "teams":{"default":"acme:team"},"teamsFrom":"observed"},
2145
2372
  "souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
@@ -2157,6 +2384,22 @@ route target:
2157
2384
  "retireFailures":[]}
2158
2385
  ```
2159
2386
 
2387
+ - **`probe`**: `{ok: true, features}` when the host's `status --json` was
2388
+ pulled, else `{ok: false, error: {code, message}}` (ssh failed, the host
2389
+ answered `ok: false`, or `E_ROSTER_BUDGET`: the roster's budget ran out
2390
+ before this target), with no `features` key.
2391
+ - **`probe.features`** (feature `server-probe-features`, OATS 0.49.0): the
2392
+ host's kernel features, relayed from the top-level `features` of its
2393
+ [`status --json`](#the-roster-oats-status---json), never probed: the roster
2394
+ runs no `version --json` and stores nothing. The answer is untrusted, so it
2395
+ is relayed only when it is an array of at most 256 entries, each a string
2396
+ of at most 64 characters matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`; then it is
2397
+ the host's list as answered (order and any duplicate kept). Anything else,
2398
+ even one bad entry among good ones, is `null`: never a filtered list. A
2399
+ host before 0.49.0 omits the key, so its group reads `null` too, whatever
2400
+ its version. Read it as `Array.isArray(probe?.features)`: not an array
2401
+ means unknown; `[]` is a valid answer (a host with no features), not
2402
+ unknown.
2160
2403
  - **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
2161
2404
  own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
2162
2405
  relayed verbatim, or `null` when the host reports none (a deployment
@@ -2372,6 +2615,11 @@ tree: `E_NO_WORKTREE`.
2372
2615
 
2373
2616
  - `observation.revision` is the HEAD oid (or `unborn`); `branch` is `null`
2374
2617
  when detached.
2618
+ - `recorded` is what the spawn recorded in `instance.json`: `branch` (`null`
2619
+ when none was recorded) and `repo`. `drift` is `true` only when a branch
2620
+ was recorded and the tree is not on it. A home spawned before 0.49.0 may
2621
+ record the word `"HEAD"` for a detached attached or checkout tree; no
2622
+ branch has that name, so it reads as `branch: null` with `drift: false`.
2375
2623
  - `upstream` without one is all `null` (unknown, not zero). `base` compares
2376
2624
  with the default branch's merge-base; `source` is `origin/HEAD` or
2377
2625
  `well-known`; none found is all `null` plus a note.
@@ -2396,8 +2644,11 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
2396
2644
  - `against` is the observed revision (the working tree against that commit,
2397
2645
  index included) or `"empty"` for an untracked file. A binary file has an
2398
2646
  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`).
2647
+ - The read runs without external diff, textconv, fsmonitor, hooks, lazy
2648
+ fetch, the caller's Git environment or global config, and writes nothing
2649
+ (`readOnly`). An object a partial clone lacks is not fetched: the read
2650
+ fails with `E_GIT_FAILED` (with Git 2.44 or later; an older Git ignores
2651
+ `GIT_NO_LAZY_FETCH`).
2401
2652
  - If HEAD or the index moved, the id is not in the current observation, or
2402
2653
  anything moved during the read: `E_STALE_OBSERVATION` with
2403
2654
  `details.observation`. Re-observe; never render a diff of another tree.
@@ -2437,7 +2688,11 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2437
2688
  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
2438
2689
  `launch` hook's warning at session start/restart, `data: {message}`),
2439
2690
  `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
2440
- [Waiting on you](#waiting-on-you)). `producer` is `kernel`, a capability id,
2691
+ [Waiting on you](#waiting-on-you)), `worktree-added` (0.49.0, feature
2692
+ `worktree-event`: `oats worktree add` made an extra tree, `data: {purpose,
2693
+ path, branch, base, baseOid, remote, member, hooks}`, `remote` without
2694
+ credentials, `member` a key or `null`, `hooks` the `worktree` hooks'
2695
+ receipt). `producer` is `kernel`, a capability id,
2441
2696
  or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
2442
2697
  `launched` is written by spawn and, since 0.40, once per session start or
2443
2698
  restart, as soon as the session exists (`data: {harness, backend,
@@ -2447,6 +2702,9 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2447
2702
  is dated at the receipt's launch time. The boundary is complete per log: a
2448
2703
  log that missed it gets a copy of the same row (same time and data), never
2449
2704
  a second one.
2705
+ - `spawned` carries `worktreeHooks` (the receipt `[{capability, ok,
2706
+ required, log, exitCode, …}]`) in its `data` only when the spawn ran
2707
+ `worktree` hooks (0.49.0).
2450
2708
  - `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
2451
2709
  reason?}`) is written to the workspace log only,
2452
2710
  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
@@ -2467,8 +2725,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2467
2725
  - **Incarnation.** Each row carries the writing home's `createdAt` (or
2468
2726
  `null` for old rows); the top-level `incarnation` is the current home's (or
2469
2727
  `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
2728
+ - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`),
2729
+ or a retired one (below). A home has one address in storage, its real path (since 0.40.2): rows are
2472
2730
  written and matched under it, whatever spelling a writer or reader used (a
2473
2731
  deployment reached through a symlink, a symlinked agents root). The answer
2474
2732
  keeps the spelling it was asked in: the top-level `home` and every
@@ -2497,6 +2755,27 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
2497
2755
  `oats status --dir <symlink>` could not see, are read now. They cannot
2498
2756
  surface a stale claim: such a session wrote its clears and its session
2499
2757
  boundaries under the real path too, so that history is complete.
2758
+ - **A retired instance** (#642) answers from its workspace log, which
2759
+ outlives the home. This applies only when no live home resolves: a live
2760
+ home of `<instance>` under the scope is always answered as above. Without
2761
+ `--home`, the kernel lists `<deployment>/.agents/events/*--<instance>.jsonl`
2762
+ (the deployment is the directory holding the scope's agents root) and takes
2763
+ the agent from the file name. One log answers for
2764
+ `<agents root>/<agent>/instances/<instance>`. Several (one name retired
2765
+ under two agents) refuse with `E_AMBIGUOUS_INSTANCE`, the message naming
2766
+ the count and asking for `--home`, and `details.candidates[]` listing each
2767
+ as `{root, agent, home}`. No log is `E_SESSION_UNKNOWN`, as before. A
2768
+ `--home` naming a removed home answers only when it is
2769
+ `<agents root>/<agent>/instances/<instance>` (compared by real path, so a
2770
+ symlinked spelling of the root is the same address) and
2771
+ `<deployment>/.agents/events/<agent>--<instance>.jsonl` exists; the agent
2772
+ is taken from the path. The logs are read from the scope's spelling of the
2773
+ home, and the answer's `home` (and each row's) is the `--home` as given.
2774
+ Any other removed `--home` is `E_HOME_MISMATCH`.
2775
+ The answer has the same shape as a live home's: the `home` source is
2776
+ `absent`, and `incarnation` is `null` (no `instance.json` remains), so
2777
+ `waitingOnYou` is `null` and `waitingClaims` is empty. The rows keep the
2778
+ incarnation they were written with.
2500
2779
  - **Window.** `count` is the rows after `--since`; `returned` the window
2501
2780
  (`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
2502
2781
  source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
@@ -2660,7 +2939,10 @@ the instance back.
2660
2939
  idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
2661
2940
  "transcript", "launch"], replayed: false}`. A result is `{instance, home,
2662
2941
  ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
2663
- code, message, stillRunning: [pid]}`.
2942
+ code, message, stillRunning: [pid]}`. `code` is `E_SESSION_UNAVAILABLE` when
2943
+ whether the instance runs cannot be established, among them a recorded
2944
+ tmux socket file that is missing while a process works in the home
2945
+ ([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
2664
2946
  - `ok: false`: at least one target still runs (text mode exits 1).
2665
2947
  - A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
2666
2948
  with `replayed: true`.
@@ -2698,8 +2980,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2698
2980
  true, note}` when the session is observably gone: instance.json records no
2699
2981
  launch, or the recorded tmux server is not running, or the recorded window
2700
2982
  is gone and no pane on that server works in the home, and in every case no
2701
- live process on the host has its working directory in the home (`lsof`; a
2702
- scan that cannot run counts as not absent). Retire then proceeds
2983
+ live process on the host has its working directory in the home
2984
+ ([the process scan](souls-and-instances.md#the-process-scan): `/proc` on
2985
+ Linux, `lsof` elsewhere; a scan that cannot run counts as not absent). Retire then proceeds
2703
2986
  without quiescing (hooks run, work is preserved). Otherwise it stays
2704
2987
  `unestablished`, with a `note` saying why, and retire refuses with
2705
2988
  `E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
@@ -2718,7 +3001,13 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2718
3001
  (`retirement.disposable.home`): `not copied: <roots> (<capability>)`, the
2719
3002
  roots as written in the manifest, in the order the baseline stores them
2720
3003
  (sorted by capability, then root), one group per capability, groups
2721
- separated by `; `. At most 16 roots are listed, then `, and N more`.
3004
+ separated by `; `. At most 16 roots are listed, and only as many as fit in
3005
+ about 1024 characters; the rest are `, and N more`. When not even one
3006
+ fits, the tail is `not copied: N declared roots, too long to list here`.
3007
+ The recovery path is never cut: when it is too long for the note, the
3008
+ note reads `recovery: the home is copied to the recovery directory beside
3009
+ the home … (its path is too long for this note: the retire receipt names
3010
+ it as workRecovery.path, and the retire summary prints it)`.
2722
3011
  The second is the line above in worktree mode, `recovery: work/ is copied
2723
3012
  there when it is not empty` in directory mode, and absent in checkout,
2724
3013
  attached and workspace modes. They are strings in `notes`: no other key
@@ -2741,16 +3030,44 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2741
3030
  - `reason`: `null` for `"remove"`, why the tree is not clean for
2742
3031
  `"retain"`, why it is refused for `"refuse"`.
2743
3032
 
2744
- `notes` also carries one string per tree that says the same. The trees are
3033
+ `notes` also carries one string per tree that says the same. When one is
3034
+ too long for a note, its longest parts (branch, repository, target,
3035
+ reason) are replaced, longest first, by a pointer to `facts.extraWorktrees`;
3036
+ the tree's path stays whole, or, when the path alone is too long, the note
3037
+ says `an extra worktree whose path is too long for this note …;
3038
+ facts.extraWorktrees in the plan JSON lists it`. The trees are
2745
3039
  part of `planRevision`: a tree created, removed, dirtied or cleaned between
2746
3040
  the plan and the apply, or a change of its disposition or target (another
2747
3041
  directory taking the `<leaf>-N` it would move to, for example), refuses a
2748
3042
  guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
2749
3043
  not know the key can ignore it; the `notes` strings say the same.
3044
+ - Every string in `notes` is at most 4096 characters, and a plan has at most
3045
+ 64 of them, the limits the Desktop reads (0.49.0, #658). The extra trees
3046
+ are the only notes whose number is not fixed: when they would pass 64, the
3047
+ last tree note kept says `and N more extra worktrees (facts.extraWorktrees
3048
+ in the plan JSON lists every one)`. A note never cuts a name or a path:
3049
+ the drift note gives way, longest name first, to a pointer to
3050
+ `facts.work.branch` or `facts.recordedBranch`; a session note whose reason
3051
+ is too long (a process's command line, a tmux error) points to
3052
+ `facts.session.note`.
3053
+ - A worktree-mode plan whose recorded children include attached instances
3054
+ that use this home's `work/` (`instance.json` `work: "attached"`, `work` a
3055
+ link to `<home>/work`, directly or through another link) has one note naming them (0.49.0, #718): `attached
3056
+ child instance(s) <names> use this home's work/ as their work: a retire
3057
+ that keeps the worktree repoints their work link to it; with
3058
+ --discard-worktree the worktree is removed and their work link will
3059
+ dangle`. It holds for either choice; no other key changes. A relink that
3060
+ fails is a string in the receipt's `warnings`.
3061
+ - `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
3062
+ (a detached checkout or attached spawn before 0.49.0, #641): it is not a
3063
+ branch name, so `facts.work.drift` is `false` for it as well.
2750
3064
 
2751
3065
  Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
2752
3066
  (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
2753
- `-2` suffix if taken; `detached-<oid12>` when detached), state intact. An
3067
+ `-2` suffix if taken; `detached-<oid12>` when detached), state intact. The
3068
+ `<branch>` leaf is the branch flattened to one path component, and a long one
3069
+ is cut and hashed to fit NAME_MAX
3070
+ ([souls-and-instances.md](souls-and-instances.md#extra-trees-at-retire)). An
2754
3071
  extra tree that is not clean is moved the same way; a clean one is removed.
2755
3072
 
2756
3073
  ```text
@@ -2783,10 +3100,20 @@ A first retire prints the **raw receipt**, not an envelope:
2783
3100
  entry is gone is never touched: it is an incomplete item (`git worktree
2784
3101
  <path>: its admin entry is missing; …`), and `--force` refuses it with
2785
3102
  `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
3103
+ - `--discard-worktree` removes the worktree, and verifies that it is gone (nothing
3104
+ at `work/`, not in `git worktree list`); a removal that did not happen, or
3105
+ cannot be verified, refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
3106
+ home, `--force` included. One exception: with no entry at all at `work/`
3107
+ (a dangling link is an entry) and a repository that cannot be read,
3108
+ `retention.worktree` is `"absent"`, never `"removed"`, and a quarantine
3109
+ retry keeps `could not verify removal` as an incomplete item, which only
3110
+ `--force` clears ([souls-and-instances.md](souls-and-instances.md)). No retire deletes a branch, a
3111
+ retried or `--force`d quarantine included, with the one exception below.
3112
+ `branchDeleted` means exactly "retire's own `--delete-branch`", which is
3113
+ refused, so it is always `false`; it does not say whether a branch was
3114
+ deleted. `spawnCompensation` (below) is the one place a branch deletion by
3115
+ retire is reported. `retention.branchDeleted` and
3116
+ `retention.branchDeletionSkipped` are not written. `--delete-branch` is refused with `E_BAD_ARGS` (`oats
2790
3117
  retire no longer deletes branches: …`) before any effect: before a plan
2791
3118
  revision is compared and before a recorded child is stopped. A failed
2792
3119
  spawn's quarantine that still owes the branch the spawn created stays
@@ -2798,6 +3125,23 @@ A first retire prints the **raw receipt**, not an envelope:
2798
3125
  Git cannot show it gone (`git branch <b>: could not verify whether it still
2799
3126
  exists (…)`). Such a home cannot be completed from Desktop: the operator
2800
3127
  deletes the branch with Git and retries, or uses `--force` from the CLI.
3128
+ - **The one exception** (feature `worktree-event`, OATS 0.49.0): a spawn
3129
+ killed while its `worktree` hooks ran (SIGKILL, or its rollback cut short)
3130
+ leaves a marker with `inProgress.branch` and `inProgress.baseOid`. Once
3131
+ that process is verified dead, retire ends the leftover hook process group,
3132
+ runs the retire hooks, removes the worktree and verifies the removal, and
3133
+ only then deletes the branch with an atomic compare-and-delete (`git
3134
+ update-ref -d refs/heads/<b> <baseOid>`), finishing the spawn's own
3135
+ compensation: a branch still at its creation commit holds no work. When
3136
+ the tip moved, the branch is checked out in any worktree, or the ref cannot
3137
+ be read, it is not deleted, and the retry stays incomplete with the
3138
+ "branch left" item above (the home is kept). `branchDeleted` stays
3139
+ `false` (retire's own `--delete-branch`); the step is reported in the
3140
+ additive `spawnCompensation`, the one place such a deletion is reported:
3141
+ `{branch, branchDeleted: true}`, or `{branch, branchDeleted: false, reason}`
3142
+ (`reason`: the tip moved, it is checked out in a worktree, it could not be
3143
+ read, or Git refused), present only when the step was reached. Desktop's
3144
+ retire-receipt reader accepts it as an unknown field.
2801
3145
  - Before the worktree is removed, HEAD is read again: a HEAD that moved since
2802
3146
  the retire's last inspection stops it with `E_WORK_PRESERVATION_FAILED`
2803
3147
  (`the worktree's HEAD changed after it was inspected, so the worktree was
@@ -2925,9 +3269,15 @@ Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
2925
3269
  `E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
2926
3270
  `--discard-worktree` when it is `work/` that could not be re-homed: it does
2927
3271
  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),
3272
+ message names the entry or the state that could not be read, or the directory
3273
+ Git reads as the top level of a `work/` whose `core.worktree` names another
3274
+ one),
2929
3275
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
2930
- `E_NO_ROOT`, `E_LIFECYCLE_FAILED`. A recovery whose Git status disagrees with
3276
+ `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
3277
+ `worktree-event`: the home is a spawn still running its `worktree` hooks, a
3278
+ row with `spawnInProgress: true`, `--force` included; or one whose start time
3279
+ cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
3280
+ group whose leader's start cannot be read, until `--force`). A recovery whose Git status disagrees with
2931
3281
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
2932
3282
  source, recovery}], total}}` (the first 10 paths). Usage errors are text on
2933
3283
  stderr, not envelopes.
@@ -3017,6 +3367,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3017
3367
  `E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
3018
3368
  that target and the way out: stop it, then `oats session restart`, which
3019
3369
  goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
3370
+ - A recorded tmux socket file that is missing while a process works in the
3371
+ home, or the process scan cannot run, is not a stopped server:
3372
+ `E_SESSION_UNKNOWN`, nothing started and no server created at that path
3373
+ ([#624](execution-targets.md#missing-socket)).
3020
3374
  - A lost response does not mean the launch failed: check status before a
3021
3375
  retry. A remote home's saved route names its execution host.
3022
3376
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
@@ -3224,11 +3578,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3224
3578
  ### `oats trigger`
3225
3579
 
3226
3580
  ```text
3227
- oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3581
+ oats trigger list | show <id> | status [<id>] | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3228
3582
  ```
3229
3583
 
3230
3584
  Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3231
- "trigger"`).
3585
+ "trigger"`). A trigger's source is the built-in `github.pull_request` or, with
3586
+ feature `trigger-sources`, `<capability>:<source>`, a source a
3587
+ capability declares ([schedules.md](schedules.md#capability-sources)).
3232
3588
 
3233
3589
  - `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
3234
3590
  `show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
@@ -3240,42 +3596,173 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3240
3596
  - `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
3241
3597
  `local/<id>` or a bare local id.
3242
3598
  - `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
3243
- ready_for_review | labeled | synchronize], labels, base?, poll}`.
3599
+ ready_for_review | labeled | synchronize], labels, base?, poll}`, or for a
3600
+ capability source `{source: "<capability>:<source>", params: {<name>:
3601
+ <string>}, events: [<the source's event names>], poll}`.
3244
3602
  - `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
3245
3603
  yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
3246
- `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`. `teams` are
3604
+ `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`, `{subject}` and
3605
+ `{key}`; a capability source's over `{trigger}`, `{source}`, `{subject}`,
3606
+ `{event}`, `{key}`, `{url}` and `{fields.<name>}`. `teams` are
3247
3607
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3248
3608
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3249
3609
  - `template?`: `{package, version, commit, template}`.
3250
- - `lastRun`: `{at, instance, home, event, number, key}`; `nextDue`: the
3251
- next poll here, `null` before the first.
3610
+ - `lastRun`: `{at, instance, home, event, number, subject, key}`
3611
+ (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3612
+ for a run recorded before 0.49.0, its number; a capability source's
3613
+ run has `number: null`); `nextDue`: the next poll here, `null` before
3614
+ the first.
3615
+ - `invalid?`: `{code, message, field?}` when the stored definition no
3616
+ longer validates, as before. A capability source's trigger whose last
3617
+ meaning check failed at a poll carries `invalid: {code, message, field?,
3618
+ at}` instead (`code` `E_TRIGGER_SOURCE` or `E_TRIGGER_INVALID`; `at` when
3619
+ the check ran), until a good poll. `invalid` always means the trigger
3620
+ itself is invalid; an event the source answered badly is an *invalid
3621
+ event* (`invalidEvents`).
3252
3622
  - `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
3253
3623
  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.
3624
+ liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
3625
+ {at, ok: true, prs, matching} | {at, ok: false, error} | null, nextPollAt,
3626
+ nextDue, pending: [{key, event, number, subject, url, observedAt}], fired:
3627
+ [{key, at, instance, home, event, number, subject}] (newest 50), firedTotal,
3628
+ lastError: {at, code, message, key?} | null}]}`. It writes nothing.
3629
+ `subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
3630
+ PR's number, as a string. A record written before 0.49.0 has none, and
3631
+ its number is reported.
3632
+ - **A capability source's `status` row** (feature `trigger-sources`) has
3633
+ `repo: null`, `number: null` in `pending[]`, `fired[]` and `live[]`, and
3634
+ adds `source: {capability, name}`, `invalidEvents: [{text, rule}]` (the
3635
+ last good poll's, at most 20; `rule` is `shape`, `unknown-key`, `key`,
3636
+ `subject`, `event`, `url`, `fields` or `duplicate-key`, `text` the first
3637
+ 200 characters of the event's JSON), `skipped: [{subject, why}]` (the last
3638
+ good poll's, at most 100) and, when its last meaning check failed,
3639
+ `invalid: {code, message, field?, at}`. Its `lastPoll` is `{at, ok: true,
3640
+ events, invalidEvents, skipped, filtered}` (counts) or `{at, ok: false,
3641
+ cause, error, source?}`, and `lastError` may carry the same `source`.
3642
+ `cause` is `exit`, `result`, `too-many-events`, `timeout`, `refused` or
3643
+ `resolution`; `source: {code, message?}` is the source's own refusal.
3644
+ `why`, `source.code` and `source.message` are the source's untrusted text,
3645
+ capped (200, 128, 500 characters) with control, separator, bidi,
3646
+ invisible and tag characters replaced by U+FFFD: render them as text,
3647
+ marked as the source's.
3648
+ - **Presence and staleness.** `source`, `invalidEvents` and `skipped` are
3649
+ always present on a capability source's status row. The two lists are
3650
+ `[]` until the trigger's first good poll and hold the last good poll's
3651
+ lists after that. A failed poll (`lastPoll.ok: false`) and a failed
3652
+ meaning check (`invalid`, which leaves `lastPoll` as it was) leave them
3653
+ unchanged, so they can be older than `lastPoll.at`, `lastError.at` and
3654
+ `invalid.at`. The lists are the current source's: changing a trigger's
3655
+ `on.source` empties them and `pending`, and clears `invalid`, `lastPoll`
3656
+ and `lastError` (`fired` stays), in what `status` and `list` answer at
3657
+ once and in the state at the next tick.
3658
+ - **Arrays versus counts.** In `trigger test`'s `source` (`ok: true`) and
3659
+ in `trigger poll`'s answer, `events`, `invalidEvents` and `skipped` are
3660
+ arrays and `filtered` is a count. In `lastPoll` (`ok: true`) and in the
3661
+ tick's `polled` row, all four are counts.
3259
3662
  - `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
3260
3663
  runsHere, reason, detail?, enabledHere}, gh: {ok, account,
3261
3664
  credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
3262
3665
  fullName, permissions: {push, maintain, admin}, canMerge} | {key, readable:
3263
3666
  false, error}, soul: {resolves, name, agent, messaging} | {resolves: false,
3264
3667
  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`.
3668
+ [{key, repo, number, subject, event, url, instance, nameCut, held?}],
3669
+ pollError?, problems, warnings, spawned: false}`. `ok` counts `problems`
3670
+ only; a credential the host timer cannot reach is a warning. `instance`
3671
+ and `nameCut` (0.49.0) are the name the spawn would be asked to derive
3672
+ (`<stem>-<purpose as passed>`, before spawn's `-<n>`) and whether its
3673
+ purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
3674
+ `null` when the soul does not resolve or its name is too long for a
3675
+ triggered spawn (that error is then in `problems`).
3676
+ - **`test <id> --run-source` of a capability source's trigger** runs the
3677
+ source (it executes the capability's source command, whatever the host's
3678
+ trust and `runsOn` say, and so only with the flag: see **`--run-source`**
3679
+ below) and answers `{triggerApi, id, ok, placement, gh, repo: null,
3680
+ soul, teams, source, wouldFire, problems, warnings, spawned: false}`, no
3681
+ `pollError`. `gh` is `null` unless the trigger has an `owner` (then as
3682
+ above, for the owner's host). `source` is `{capability, name, ok: true,
3683
+ events, invalidEvents, skipped, filtered}`, `{capability, name, ok: false,
3684
+ filtered: 0, invalid: {code, message, field?, at}, events: [],
3685
+ invalidEvents: [], skipped: []}` when its meaning fails, or `{capability,
3686
+ name, ok: false, filtered: 0, cause, error: {code, message}, source?,
3687
+ events: [], invalidEvents: [], skipped: []}` when the poll fails.
3688
+ Without `--run-source`, `test` answers a trigger whose meaning or
3689
+ resolution fails as above (exit 0, `source.ok: false`: no capability code
3690
+ runs to say so), and a trigger whose meaning holds with
3691
+ `E_TRIGGER_SOURCE_RUN`. `wouldFire` rows are `{key, subject,
3692
+ event, url?, instance, nameCut, held?}`. When the tick would not run the
3693
+ trigger here, `problems` holds `run manually with --run-source; the tick
3694
+ will not run it here: <reason>` (with the placement's detail). `warnings` always holds
3695
+ "this source's credential may not be visible to the host timer: it runs
3696
+ with only PATH and OATS_HOME_DIR set, so keep the source's login in its
3697
+ own store, not in an exported variable".
3698
+ - **`poll <id> --run-source`** (feature `trigger-sources`) runs a capability
3699
+ source's trigger's source once, its meaning checked first, and answers
3700
+ `{triggerApi, id, source: {capability, name}, events: [{key, subject,
3701
+ event, url?, fields}], invalidEvents: [{text, rule}], skipped: [{subject,
3702
+ why}], filtered}`, plus `observation` with `--max-age`. `events` are the
3703
+ valid events the trigger selects, `key` as the source wrote it (stored
3704
+ prefixed `<trigger>:`); `filtered` counts the valid events whose `event`
3705
+ the trigger does not select. It records nothing and spawns nothing, but it
3706
+ executes the capability's source command. A failed poll is `E_TRIGGER_POLL`
3707
+ with `details: {cause, source?}`; a meaning failure is `E_TRIGGER_SOURCE`
3708
+ `{capability, source, pointer?}` or `E_TRIGGER_INVALID {field}`; without
3709
+ the flag it is `E_TRIGGER_SOURCE_RUN`; a `github.pull_request` trigger is
3710
+ `E_BAD_ARGS`, with or without the flag. Without `--max-age` it observes
3711
+ the members live.
3712
+ - **`--run-source`** (feature `trigger-sources`): by hand, `test` and `poll`
3713
+ run a capability source's command only with this switch (it takes no
3714
+ value). It is caller intent, never trust consent: with it they run the
3715
+ source whatever the host's `automations.trust` and the trigger's `runsOn`
3716
+ say, and trust, `runsOn` and `owner` gate the tick exactly as before (the
3717
+ tick passes the flag to its own child). Without it, on a capability
3718
+ source's trigger: `E_TRIGGER_SOURCE_RUN`, `ok: false`, a non-zero exit,
3719
+ `details: {capability, source, flag: "--run-source"}`, and a message
3720
+ naming the command to run again (`oats trigger test|poll <id>
3721
+ --run-source`), and the trigger's `runsOn` when that is another host: it
3722
+ holds only the id, the capability and source names and `runsOn`, never
3723
+ text of the source's. Nothing of the capability has executed and nothing
3724
+ has been written in the deployment, the soul's copy under `agents/` and
3725
+ the capability's directory in the module store included. The
3726
+ order is fixed: a valid definition (`E_TRIGGER_INVALID`), then its meaning
3727
+ and the soul's resolution (`E_TRIGGER_SOURCE`, `E_TRIGGER_INVALID
3728
+ {field}`, `E_TRIGGER_POLL` `cause: "resolution"`), then this gate, then
3729
+ the run. On a `github.pull_request` trigger the flag is accepted and
3730
+ inert: `test` answers byte for byte the same.
3731
+ - **What a `triggerApi: 1` reader sees.** `triggerApi` stays 1. `on.source`
3732
+ is an open string: tell rows apart by it, and gate on `trigger-sources`.
3733
+ The keys above (`source`, `invalidEvents`, `skipped`, a meaning failure's
3734
+ `invalid`, `test`'s `source`) appear only on capability-source rows and
3735
+ are absent, not `null`, on a `github.pull_request` row, whose outputs are
3736
+ exactly as before. On a capability source's rows the PR-only fields are
3737
+ `null` (`repo`, `number`) or absent (`on.repo`, `on.labels`, `on.base`,
3738
+ `wouldFire[].repo`), and `lastPoll` carries the counts above instead of
3739
+ `prs` and `matching`.
3740
+ - A triggered instance records `instance.json.trigger`: `{id, key, source,
3741
+ repo, number, subject, url, event, headSha, observedAt, eventFile}`
3742
+ (`subject` since 0.49.0; `null` when the event had none). Its event file is
3743
+ `OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
3744
+ event, headSha, labels, observedAt, key}`. For a capability source the
3745
+ record has `repo: null`, `number: null`, `headSha: null` and adds `fields`,
3746
+ and the event file is `{trigger, source, subject, event, key, url?,
3747
+ fields, observedAt}`.
3270
3748
  - `update <id> --description=<text>` (feature `automation-descriptions`)
3271
3749
  changes only a local trigger's description; `--description=` (empty)
3272
3750
  removes it. It sets `updatedAt` and leaves fired and pending events
3273
3751
  untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
3274
3752
  refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
3275
3753
  --description is supported for now"). An older kernel has no `update`.
3754
+ - `add` of a capability source's trigger checks its meaning against the
3755
+ soul's resolution before anything is written (`E_TRIGGER_SOURCE`,
3756
+ `E_TRIGGER_INVALID {field}`, or the soul's own resolution error).
3276
3757
  - Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
3277
- `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_POLL`,
3278
- `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3758
+ `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_SOURCE {capability,
3759
+ source, pointer?}` (a capability source that is undeclared or malformed,
3760
+ whose capability the soul does not compose, or whose command is not a file
3761
+ inside the capability; `pointer` is a JSON pointer into the manifest),
3762
+ `E_TRIGGER_POLL` (`details.cause` and `details.source` for a capability
3763
+ source), `E_TRIGGER_SOURCE_RUN {capability, source, flag}` (`test` or
3764
+ `poll` of a capability source's trigger without `--run-source`: nothing
3765
+ ran, nothing was written), `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3279
3766
  `E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
3280
3767
 
3281
3768
  <a id="automations-shared-rows"></a>
@@ -3343,8 +3830,16 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3343
3830
  - The tick's `considered[]` holds schedule rows and trigger rows `{workspace,
3344
3831
  trigger, action, …}` with actions `not-due`, `poll-failed`, `polled`
3345
3832
  (`prs`, `matching`), `held`, `fired` (`key`, `instance`, `home`),
3346
- `spawn-failed` (`key`, `code`, `error`), `would-fire`, `invalid` and
3347
- `not-here`. A workspace schedule's state key is `<member>~<id>`. A failed
3833
+ `spawn-failed` (`key`, `code`, `error`), `would-fire` (`key`, `event`,
3834
+ `number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
3835
+ soul as a tick does, and reports a preview failure or a name that cannot
3836
+ fit as `spawn-failed`), `invalid` and
3837
+ `not-here`. A capability source's trigger adds `poll-deferred`
3838
+ (`deadline`: its poll could not end by 50 s after the tick started; it
3839
+ goes first next tick), its `polled` carries `events`, `invalidEvents`,
3840
+ `skipped` and `filtered`, `poll-failed` a `cause`, `invalid` a failed
3841
+ meaning check, and its `would-fire` has no `number`, and no `url` when the
3842
+ event has none. A workspace schedule's state key is `<member>~<id>`. A failed
3348
3843
  snapshot refresh is `{workspace, action: "error", error}`.
3349
3844
 
3350
3845
  <a id="the-harness-rename-feature-harness-oats-0270"></a>