@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.
- package/bin/oats.mjs +226 -14
- package/docs/capabilities.md +256 -8
- package/docs/capability-manifest.schema.json +18 -5
- package/docs/configuration.md +6 -0
- package/docs/desktop-cli-api.md +368 -31
- package/docs/desktop.md +72 -5
- package/docs/execution-targets.md +17 -2
- package/docs/implementation.md +62 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +8 -8
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/schedules.md +62 -39
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +381 -53
- package/docs/workspaces.md +2 -2
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +5 -2
- package/lib/core.mjs +1109 -321
- package/lib/instance-events.mjs +6 -3
- package/lib/instance-git.mjs +11 -5
- package/lib/instance-inspect.mjs +14 -3
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +1 -0
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/triggers.mjs +201 -65
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
package/docs/desktop-cli-api.md
CHANGED
|
@@ -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,
|
|
2400
|
-
caller's Git environment or global config, and writes nothing
|
|
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))
|
|
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,
|
|
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.
|
|
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
|
|
2787
|
-
|
|
2788
|
-
|
|
2789
|
-
|
|
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
|
|
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}
|
|
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:
|
|
3255
|
-
true, prs, matching} | {at, ok: false, error} | null, nextPollAt,
|
|
3256
|
-
pending: [{key, event, number, url, observedAt}], fired:
|
|
3257
|
-
instance, home, event, number}] (newest 50), firedTotal,
|
|
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?}],
|
|
3266
|
-
spawned: false}`. `ok` counts `problems`
|
|
3267
|
-
cannot reach is a warning.
|
|
3268
|
-
|
|
3269
|
-
|
|
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`, `
|
|
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
|
|