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