@awebai/oats 0.68.1 → 0.69.2
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 +180 -36
- package/docs/capabilities.md +73 -10
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/configuration.md +68 -2
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +600 -25
- package/docs/desktop-instance-start.md +59 -3
- package/docs/desktop.md +175 -10
- package/docs/execution-targets.md +536 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +33 -15
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +25 -16
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +51 -7
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +46 -9
- package/docs/tui.md +177 -21
- package/docs/upgrading.md +16 -7
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +496 -127
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +136 -27
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +33 -0
- package/lib/session-resume.mjs +337 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +15 -11
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +41 -6
- package/package-catalog.json +11 -5
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +39 -8
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +16 -0
- package/packages/client/deployment-panel.mjs +7 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/README.md +2 -2
- package/packages/tui/lib/client.mjs +7 -3
- package/packages/tui/lib/main.mjs +49 -14
- package/packages/tui/lib/model.mjs +146 -55
- package/packages/tui/lib/store.mjs +84 -27
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/frame.mjs +74 -7
- package/packages/tui/lib/views/help.mjs +10 -3
- package/packages/tui/lib/views/instances.mjs +41 -3
- package/skills/oats-getting-started/SKILL.md +117 -4
package/docs/desktop-cli-api.md
CHANGED
|
@@ -49,7 +49,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
49
49
|
"status-retire-state","session-inspect-size","session-inspect-running","deployments-list"],
|
|
50
50
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
51
51
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
52
|
-
"capabilityShowApi":1}
|
|
52
|
+
"capabilityShowApi":1,"sessionViewer":{"prefixScroll":true}}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
- The Desktop accepts `desktopApi === 1` and a released `version` inside
|
|
@@ -65,6 +65,14 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
65
65
|
probe before a routed mutation. From 0.31: `readiness`, `instance-events`,
|
|
66
66
|
`instance-git` and `lifecycle-plans` name the
|
|
67
67
|
[routed reads and plans](#routed-reads-and-plans).
|
|
68
|
+
- `sessionViewer` (feature `session-attach-prefix-scroll`) is a fact of
|
|
69
|
+
this host, not of the binary: `prefixScroll` is `true` when a viewer
|
|
70
|
+
without a detach key binds `C-b [` here, that is when the `tmux` on
|
|
71
|
+
`PATH` is 3.3 or later (`tmuxForwardsBoundKey`, lib/session-viewer.mjs),
|
|
72
|
+
and `false` with an older tmux or none. The kernel asks `tmux -V` afresh
|
|
73
|
+
at every run and keeps no answer, so read it again after a tmux upgrade.
|
|
74
|
+
The feature is in every kernel's list that has the field, whatever this
|
|
75
|
+
host's tmux: gate on the feature, then read the field.
|
|
68
76
|
- In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
|
|
69
77
|
|
|
70
78
|
### Features
|
|
@@ -129,6 +137,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
129
137
|
| `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
130
138
|
| `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
131
139
|
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
140
|
+
| `session-attach-no-status-line` | `oats session attach … --no-status-line`, local and `--server`: a viewer without a detach key, without its status line (`Shift+PgUp or C-b [ to scroll back`), for a caller that shows the scroll keys itself ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe: a kernel without it ignores the flag and shows the line. A routed attach sends it to any host, with no probe of its own | |
|
|
141
|
+
| `session-attach-prefix-scroll` | `sessionViewer: {prefixScroll}` on `oats version --json` and `oats status --json`, and `probe.sessionViewer` on each `oats server roster --json` group: whether that host's viewer without a detach key binds `C-b [` (tmux 3.3 and later), read afresh per host at each run. A kernel with the feature has the viewer's `Shift+PgUp` binding; one without it may not, so don't name the viewer's scroll keys for its tabs ([execution-targets.md](execution-targets.md#inspect-input-and-attach)) | |
|
|
132
142
|
| `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
|
|
133
143
|
| `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
|
|
134
144
|
| `lifecycle-claim-stop` | `oats instance stop --apply` holds the claim of every target (the file one retire of a home at a time is ordered by), so a stop is refused beside a retire in flight (`E_INSTANCE_RETIRING`) or another stop (`E_LIFECYCLE_BUSY`), a retire beside a stop (`E_LIFECYCLE_BUSY`), and `oats worktree add` beside a retire (`E_INSTANCE_RETIRING`), each before any effect ([Commands that meet on one home](#lifecycle-pairs)); a stop that was killed refuses nothing afterwards, and `<home>/.oats-stop-pending.json` is no longer written or read: a client's own handling of a stale stop marker is not needed for a kernel that lists this; `error.details.action` (the holder's verb) on those refusals, and `error.details.holder` on every `E_LIFECYCLE_BUSY` ([`details.holder`](#busy-holder)); the codes a stop and a retire answer only before any effect, as one list ([the list](#before-effect-codes)), with two retire answers that came after an effect given codes outside it (`E_WORK_PRESERVATION_FAILED`, `E_RUNTIME_QUIESCE_FAILED`), OATS 0.52.0. Gate on the probe; routed with `--server`, on the host's list | |
|
|
@@ -139,10 +149,13 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
139
149
|
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
140
150
|
| `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
|
|
141
151
|
| `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
|
|
152
|
+
| `instance-same-work` | `oats instance same-work <instance> on\|off` and `oats spawn … --same-work`, local and `--server` ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work)); `sameWork: true` on `oats status --json` instance rows and on `oats server roster --json` rows while the instance's flag is bound to its current `parentInstance`, the key absent otherwise ([`sameWork`](#row-same-work)). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows never carry `sameWork`, and it refuses the flag and the verb (`E_BAD_ARGS`) | |
|
|
142
153
|
| `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
|
|
143
154
|
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
144
155
|
| `instance-suggest-name` | `oats instance suggest-name --soul <soul> (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn of `<soul>` would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
|
|
145
156
|
| `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
|
|
157
|
+
| `instance-background` | background instances (awebai/oats#1579): `soul.yaml` `background:`; `oats spawn … --background\|--no-background`, whose preview and result carry `background` and `backgroundFrom`; `oats instance background <instance> on\|off`, local and `--server`; `background: true` on `oats status --json` instance rows, `oats server roster --json` rows, `oats inspect --home` `instance` and `oats souls --json` soul rows, absent otherwise ([Background instances](#background-instances-oats-instance-background)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the flags and the verb, and its rows have no `background`. A routed spawn with either flag needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) | `instanceBackgroundApi: 1` (payload only) |
|
|
158
|
+
| `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
|
|
146
159
|
|
|
147
160
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
148
161
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -503,7 +516,7 @@ capabilities}`, each the soul.yaml section as written or `null`.
|
|
|
503
516
|
with `--instructions`, which takes a soul subject (`--home` is `E_BAD_ARGS`);
|
|
504
517
|
without the flag the key is absent and nothing extra is composed. It is the
|
|
505
518
|
AGENTS.md a spawn of this soul here with no flags would write, produced by
|
|
506
|
-
spawn's own composition —
|
|
519
|
+
spawn's own composition — each capability's inject, then the kernel blocks,
|
|
507
520
|
materialized into a scratch home outside the deployment and removed. It is
|
|
508
521
|
`{file: null, text, truncated, resolution, body, sources}`. `text` and
|
|
509
522
|
`truncated` follow the 200,000-character cap of `instructions`; `resolution` is
|
|
@@ -1249,8 +1262,10 @@ are absent until `sync`.
|
|
|
1249
1262
|
**Soul rows:** `name, origin, kind (member | external | package), repoKey,
|
|
1250
1263
|
commit, teams, defaultTeam, private (always false), path, work, description`,
|
|
1251
1264
|
plus the Desktop facts `harness, model, harnessFrom, file, spawnable,
|
|
1252
|
-
problem`, (feature `souls-capabilities`) `capabilities`,
|
|
1253
|
-
`launch-preference`) `key` and `launch
|
|
1265
|
+
problem`, (feature `souls-capabilities`) `capabilities`, (feature
|
|
1266
|
+
`launch-preference`) `key` and `launch`, and (feature `instance-background`)
|
|
1267
|
+
`background: true` on a soul whose `soul.yaml` says `background: true`,
|
|
1268
|
+
absent otherwise: the launch dialog's default for Run in background.
|
|
1254
1269
|
- `key` is the soul key that `souls.launch` uses, and that
|
|
1255
1270
|
`oats soul teams <key>` takes: `qualifiedName` for a package
|
|
1256
1271
|
soul, the bare `name` for a member or external soul. Two member souls that
|
|
@@ -2453,6 +2468,10 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2453
2468
|
otherwise. Show it, and `yolo`, whenever it is `true`. An explicit
|
|
2454
2469
|
`--launch-config none` asks for the bare harness and bypasses the default;
|
|
2455
2470
|
to run the host's default, omit `--launch-config`.
|
|
2471
|
+
- `launchConfigSource` (0.69) is the directory of the file that declares
|
|
2472
|
+
`launchConfig`: the deployment, or `~/.oats/config` for
|
|
2473
|
+
[this machine's launch configurations](configuration.md#this-machines-launch-configurations);
|
|
2474
|
+
`null` when there is no `launchConfig`. A spawn records the same value.
|
|
2456
2475
|
- `modelSource` is `"explicit"`, `"soul default"`, `"launch-config <name>"`,
|
|
2457
2476
|
`"native default"` or `"native default (explicit)"` (`--model
|
|
2458
2477
|
@native-default`). Omitting `--model` and asking for the native default are
|
|
@@ -2461,6 +2480,20 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2461
2480
|
native probes share one 20 s budget.
|
|
2462
2481
|
- `policy.childSpawns` is what the instance will record.
|
|
2463
2482
|
|
|
2483
|
+
**Background** (feature `instance-background`).
|
|
2484
|
+
- `background` (`true` or `false`) says whether the instance will be listed
|
|
2485
|
+
under the clients' Background section
|
|
2486
|
+
([Background instances](#background-instances-oats-instance-background)).
|
|
2487
|
+
It is `--background` or `--no-background`, else the soul's
|
|
2488
|
+
`background:`, else `false`.
|
|
2489
|
+
- `backgroundFrom` is `"flag"` or `"soul"`, the layer that declared the
|
|
2490
|
+
value; a soul's explicit `background: false` is `"soul"`. It is absent
|
|
2491
|
+
when neither declares it.
|
|
2492
|
+
- Both flags together are `E_BAD_ARGS` (`choose --background or
|
|
2493
|
+
--no-background, not both`). The text preview prints `list: background
|
|
2494
|
+
(from the soul)` or `(from the --background flag)` for a background
|
|
2495
|
+
instance.
|
|
2496
|
+
|
|
2464
2497
|
**Composition.**
|
|
2465
2498
|
- `modules[]` (feature `instance-modules`): `{name, from, layer, private,
|
|
2466
2499
|
declares, changedSince, composedFrom}`; `from` is what `instance.json` will
|
|
@@ -2656,8 +2689,11 @@ preview's call and rules above, through the soul's harness.
|
|
|
2656
2689
|
revision}`. `effective` (feature `spawn-apply-2`) is `{repo, work, harness,
|
|
2657
2690
|
model, launchConfig, yolo, backend, childSpawns, relation, providers}`;
|
|
2658
2691
|
`relation` is `null` or `{kind, anchor: {instance, agentsRoot}}`; `providers`
|
|
2659
|
-
(feature `served-identity`) equals `settings`. `
|
|
2660
|
-
|
|
2692
|
+
(feature `served-identity`) equals `settings`. `effective.background: true`
|
|
2693
|
+
(feature `instance-background`) is there only when the instance will be
|
|
2694
|
+
background, so a decision without it keeps the revision it had: an apply
|
|
2695
|
+
whose resolved value differs from the preview's is `E_DECISION_STALE`.
|
|
2696
|
+
`revision` (24 hex) hashes the decision.
|
|
2661
2697
|
|
|
2662
2698
|
Apply with `oats spawn <soul> … --expect-decision <revision> --json`. Any drift
|
|
2663
2699
|
refuses `E_DECISION_STALE` with the fresh `details.decision`; nothing is
|
|
@@ -2747,6 +2783,10 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
2747
2783
|
--home <home>` for `--no-launch`. A value is single-quoted only when it
|
|
2748
2784
|
holds a character outside `A-Za-z0-9_./:-`. It is not a field to parse:
|
|
2749
2785
|
read `tmux` for the target.
|
|
2786
|
+
- `background` and `backgroundFrom` (feature `instance-background`) are the
|
|
2787
|
+
preview's. A background spawn writes the home's record with the home's
|
|
2788
|
+
other files, so a spawn that rolls back leaves none. A keyed replay answers
|
|
2789
|
+
`background` as the home's record reads now, without `backgroundFrom`.
|
|
2750
2790
|
- When they apply: `yolo`, `decision` and
|
|
2751
2791
|
`replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
|
|
2752
2792
|
`wakeScheduleError` (a requested wake), `worktreeHooks` (feature
|
|
@@ -2907,7 +2947,7 @@ kernel stage raised as well.
|
|
|
2907
2947
|
|
|
2908
2948
|
| Code | Details | When |
|
|
2909
2949
|
|---|---|---|
|
|
2910
|
-
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
|
|
2950
|
+
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul; `--same-work` for an instance that would record no parent ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work)) |
|
|
2911
2951
|
| `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
|
|
2912
2952
|
| `E_SOUL_UNKNOWN` | `{name, members, packages}` | no such soul, or not at `--agents-root` |
|
|
2913
2953
|
| `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
|
|
@@ -3231,8 +3271,12 @@ its absence.
|
|
|
3231
3271
|
"shell"`, even though the window remains; a dead pane or absent window is
|
|
3232
3272
|
`false`. A wrapper shell with a live non-shell descendant stays `true`;
|
|
3233
3273
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
3234
|
-
`runtimeError` when that server or its panes cannot be read (including a
|
|
3235
|
-
|
|
3274
|
+
`runtimeError` when that server or its panes cannot be read (including a
|
|
3275
|
+
window where OATS cannot tell which pane is the agent's
|
|
3276
|
+
([which pane is the agent's](execution-targets.md#which-pane-is-the-agents)),
|
|
3277
|
+
a session with two windows of the instance's name, or a failed
|
|
3278
|
+
shell-descendant process scan; a window whose agent's pane is found reads by
|
|
3279
|
+
that pane alone), and also when its socket
|
|
3236
3280
|
file is missing while a process works in the home or the process scan
|
|
3237
3281
|
cannot run, `runtimeError` then naming the processes or the scan's error
|
|
3238
3282
|
([#624](execution-targets.md#missing-socket); with no process in the home
|
|
@@ -3283,12 +3327,50 @@ its absence.
|
|
|
3283
3327
|
An older kernel's `running` is the window's presence, and it checks a row
|
|
3284
3328
|
with a claim against its session (as `oats session inspect` observes it),
|
|
3285
3329
|
reading `null` unless a harness runs there.
|
|
3330
|
+
- <a id="row-session-end"></a>**`sessionEnd`** (feature `session-resume`, OATS
|
|
3331
|
+
0.69): how the last session of a launched home that does not run ended:
|
|
3332
|
+
`lost` (the host went down, its tmux server died, or the harness was killed
|
|
3333
|
+
by a signal: the sweep brings it back when it can vouch for the loss,
|
|
3334
|
+
[Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
|
|
3335
|
+
`oats instance stop`, Desktop's Stop) or `exited` (the harness ended by
|
|
3336
|
+
itself: `/exit`, its own error). Present only on a row that reads
|
|
3337
|
+
`running: false` and records `launched: true`, a row at its fallback shell
|
|
3338
|
+
(`runtimeState: "shell"`) included; absent while it runs or reads unknown
|
|
3339
|
+
(`running: null`), for a home never launched, on rows with `retirePending`,
|
|
3340
|
+
`rollbackIncomplete` or `spawnInProgress`, and from older kernels. Read
|
|
3341
|
+
from the home's current start (`startId`; its time is the last
|
|
3342
|
+
`restarts[].startedAt`, else `createdAt`) and two kernel-private files of
|
|
3343
|
+
the home, not a contract ([execution-targets.md](execution-targets.md#how-a-sessions-end-is-read)).
|
|
3344
|
+
A home spawned before 0.69 and never restarted since reads `lost` when its
|
|
3345
|
+
harness ended on its own; its next start covers it.
|
|
3346
|
+
- **A local status read records what it sees** (feature `session-resume`,
|
|
3347
|
+
OATS 0.69): per home, its current start, when it was last seen running and
|
|
3348
|
+
first seen not running, with the boot of each, in a kernel-private file of
|
|
3349
|
+
this machine, one per deployment, under `~/.oats/session-resume/seen/`
|
|
3350
|
+
(`$OATS_HOME_DIR` when set), beside the sweep's per-boot note; it is not a
|
|
3351
|
+
contract, and only the sweep reads it. It never changes the answer: not the
|
|
3352
|
+
output, not the exit status, and nothing is printed, whether or not it can
|
|
3353
|
+
be read or written. A status routed with `--server` records nothing on this
|
|
3354
|
+
machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
|
|
3286
3355
|
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3287
3356
|
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3288
3357
|
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
3289
3358
|
a `color` in `instance.json` never stands in for it. Every row has it,
|
|
3290
3359
|
an unreadable record's row included (`null`). Presentation only: it is not
|
|
3291
3360
|
identity and never addresses anything.
|
|
3361
|
+
- **`background`** (feature `instance-background`): `true` while the home
|
|
3362
|
+
holds a valid background record ([Background instances](#background-instances-oats-instance-background)),
|
|
3363
|
+
absent otherwise; never `false`. A `background` in `instance.json` never
|
|
3364
|
+
stands in for it. The text rows mark it: `• <instance> [background]`.
|
|
3365
|
+
- <a id="row-same-work"></a>**`sameWork`** (feature `instance-same-work`):
|
|
3366
|
+
`true` when the home's same-work flag
|
|
3367
|
+
([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work))
|
|
3368
|
+
is bound to the parent the row's `parentInstance` names. Otherwise the key
|
|
3369
|
+
is absent, never `false` or `null`: no flag, a flag bound to an earlier
|
|
3370
|
+
parent, no `parentInstance`, and a row whose `instance.json` cannot be read.
|
|
3371
|
+
A `sameWork` in `instance.json` never stands in for it. Clients draw the
|
|
3372
|
+
parent→child line for a row that carries it; a client that does not know
|
|
3373
|
+
the key ignores it, and an older kernel never sends it.
|
|
3292
3374
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3293
3375
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3294
3376
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -3357,6 +3439,10 @@ its absence.
|
|
|
3357
3439
|
relays a host's features from the status answer it already pulls. It is
|
|
3358
3440
|
emitted at output time, never part of a reused observation. A kernel
|
|
3359
3441
|
before 0.49.0 omits it.
|
|
3442
|
+
- **`sessionViewer`** (feature `session-attach-prefix-scroll`): this host's
|
|
3443
|
+
`{prefixScroll}`, as `version --json` answers it, read afresh at each
|
|
3444
|
+
run and never part of a reused observation, so a roster relays it from
|
|
3445
|
+
the status answer it already pulls.
|
|
3360
3446
|
- `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
|
|
3361
3447
|
`warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
|
|
3362
3448
|
|
|
@@ -3436,7 +3522,7 @@ route target:
|
|
|
3436
3522
|
```json
|
|
3437
3523
|
{"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
|
|
3438
3524
|
"target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
|
|
3439
|
-
"probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
|
|
3525
|
+
"probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"],"sessionViewer":{"prefixScroll":true}},"agentsRoot":"/srv/team/agents",
|
|
3440
3526
|
"workspace":{"reachable":true,"key":"github.com/acme/team","ref":"git:github.com/acme/team","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"default","team":"acme:team"},
|
|
3441
3527
|
"teams":{"default":"acme:team"},"teamsFrom":"observed"},
|
|
3442
3528
|
"souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
|
|
@@ -3454,9 +3540,10 @@ route target:
|
|
|
3454
3540
|
"retireFailures":[]}
|
|
3455
3541
|
```
|
|
3456
3542
|
|
|
3457
|
-
- **`probe`**: `{ok: true, features}` when the host's
|
|
3458
|
-
pulled, else `{ok: false, error: {code, message}}`
|
|
3459
|
-
out, `E_SSH`; or the host answered `ok: false`),
|
|
3543
|
+
- **`probe`**: `{ok: true, features, sessionViewer}` when the host's
|
|
3544
|
+
`status --json` was pulled, else `{ok: false, error: {code, message}}`
|
|
3545
|
+
(ssh failed or timed out, `E_SSH`; or the host answered `ok: false`),
|
|
3546
|
+
with no `features` and no `sessionViewer` key.
|
|
3460
3547
|
Every group is probed at once, each within its own deadline, so a group's
|
|
3461
3548
|
`probe` depends only on its own host: one that does not answer in time is
|
|
3462
3549
|
`E_SSH` with `ssh to <host> timed out: no answer within <n> s`, and every
|
|
@@ -3475,6 +3562,13 @@ route target:
|
|
|
3475
3562
|
its version. Read it as `Array.isArray(probe?.features)`: not an array
|
|
3476
3563
|
means unknown; `[]` is a valid answer (a host with no features), not
|
|
3477
3564
|
unknown.
|
|
3565
|
+
- **`probe.sessionViewer`** (feature `session-attach-prefix-scroll`): the
|
|
3566
|
+
host's `{prefixScroll}`, relayed from the `sessionViewer` of its
|
|
3567
|
+
[`status --json`](#the-roster-oats-status---json), never probed. It is
|
|
3568
|
+
relayed as a copy of `{prefixScroll}` only when that is a boolean;
|
|
3569
|
+
anything else, or a host whose kernel predates the field, is `null`.
|
|
3570
|
+
Read it only for a host whose `probe.features` lists
|
|
3571
|
+
`session-attach-prefix-scroll`.
|
|
3478
3572
|
- **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
|
|
3479
3573
|
own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
|
|
3480
3574
|
relayed verbatim, or `null` when the host reports none (a deployment
|
|
@@ -3518,6 +3612,15 @@ route target:
|
|
|
3518
3612
|
cut to the same bound. `oats status --server
|
|
3519
3613
|
<id> --json` relays the host's answer verbatim, `retire` included, as it
|
|
3520
3614
|
does every other field.
|
|
3615
|
+
- **`background`** (feature `instance-background`) is on a row only when the
|
|
3616
|
+
host's row has exactly `background: true`; any other value, a host whose
|
|
3617
|
+
kernel predates the feature and a saved route the host did not list carry
|
|
3618
|
+
none.
|
|
3619
|
+
- **`sameWork`** (feature `instance-same-work`) is on a row only when the
|
|
3620
|
+
host's row has `sameWork: true`, and is then `true`. Any other value, a host
|
|
3621
|
+
whose kernel predates the feature, and a saved route the host did not list
|
|
3622
|
+
carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
|
|
3623
|
+
--json` relays the host's answer verbatim, `sameWork` included.
|
|
3521
3624
|
- **`addressable`** (0.31): `true` for every row the host reports. Routed
|
|
3522
3625
|
session and lifecycle commands reach it by `--home`, or by name when the
|
|
3523
3626
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
@@ -3696,7 +3799,9 @@ An envelope, `ok: true` whenever no step failed, human steps included
|
|
|
3696
3799
|
- `registration` is the registration as written or found (`sshHost`,
|
|
3697
3800
|
`workspace`: the absolute path the host resolved for `--dir`, never `~`;
|
|
3698
3801
|
`workspaceKey`; and `oatsPath`, `path`,
|
|
3699
|
-
`label` when set
|
|
3802
|
+
`label` when set, given or, without `--path`, read from the host user's
|
|
3803
|
+
[login shell](servers.md#the-hosts-login-shell-path)), `null` until the
|
|
3804
|
+
`register` step has run.
|
|
3700
3805
|
- `human` lists the remedies of the `needs-human` steps, in order. A
|
|
3701
3806
|
`readiness` step that needs a human has one line per problem
|
|
3702
3807
|
(`<souls>: <subject>: <reason>[ → <remedy>]`, plus `readiness not checked
|
|
@@ -3745,6 +3850,8 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
3745
3850
|
| `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3746
3851
|
| `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3747
3852
|
| `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
|
|
3853
|
+
| `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
|
|
3854
|
+
| `oats instance same-work <name> on\|off --server <id>` | none | `instance-same-work` |
|
|
3748
3855
|
|
|
3749
3856
|
- The flags are the local command's. The instance is addressed like every
|
|
3750
3857
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -4012,7 +4119,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
4012
4119
|
message}` per producer with a live claim in the current incarnation
|
|
4013
4120
|
(cleared ones included). A producer's latest row with `data.waitingOnYou`
|
|
4014
4121
|
decides. `waitingOnYou` is `{since, producer, reason, message}` of the
|
|
4015
|
-
newest positive claim
|
|
4122
|
+
newest positive claim that has a message, so a claim with no text never
|
|
4123
|
+
hides one with text; when its `reason` is `null`, the newest text-less
|
|
4124
|
+
claim's reason fills it. With no message anywhere it is the newest
|
|
4125
|
+
positive claim, or `null` (unknown, not "not waiting"). See
|
|
4016
4126
|
[Waiting on you](#waiting-on-you) for the producers and the rules.
|
|
4017
4127
|
- Errors: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
|
|
4018
4128
|
`E_BAD_ARGS`, `E_EVENTS_FAILED`.
|
|
@@ -4063,8 +4173,14 @@ oats instance attention [--message <text>] [--clear] --json
|
|
|
4063
4173
|
only ever the message, never a flag (`--message=--clear` sets the message
|
|
4064
4174
|
"--clear"). The spaced form `--message --deploy` reads `--deploy` as a
|
|
4065
4175
|
flag and is `E_BAD_ARGS`. It is stored as given, only on a
|
|
4066
|
-
positive claim. The reader applies the same rule again
|
|
4067
|
-
|
|
4176
|
+
positive claim. The reader applies the same rule again, with one
|
|
4177
|
+
difference: a stored message over 200 code points (a row from another
|
|
4178
|
+
producer or an older writer, or a remote kernel's claim) is cut to 200, the
|
|
4179
|
+
last one `…`. So `waitingOnYou.message` and each `waitingClaims[].message`
|
|
4180
|
+
are never longer than 200 code points, whoever wrote them. The cut counts
|
|
4181
|
+
code points: a surrogate pair is never split, but a combining mark may be
|
|
4182
|
+
left out. A message that is still invalid after that (a refused character,
|
|
4183
|
+
a hand-edited log) reads as `null`, and the claim still counts.
|
|
4068
4184
|
A stored `reason` outside `permission`, `question`, `attention` reads as
|
|
4069
4185
|
`null` too, and a row whose `producer` is neither `kernel` nor a valid
|
|
4070
4186
|
producer id, or whose `at` is not a date, is no claim at all.
|
|
@@ -4475,7 +4591,12 @@ leaves nothing of its own in the home: the private file each of the two
|
|
|
4475
4591
|
writes goes through (`.oats-stop.json.tmp-<pid>`,
|
|
4476
4592
|
`.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
|
|
4477
4593
|
rename fails. Before 0.53.0 each apply on a full disk left both there,
|
|
4478
|
-
empty.
|
|
4594
|
+
empty. With no record of the stop, the instance then reads
|
|
4595
|
+
[`sessionEnd: "lost"`](#row-session-end), and a resume sweep would start it
|
|
4596
|
+
again: stop it once more when the disk has space (a stop of an instance that
|
|
4597
|
+
reads `lost` records the stop, signalling nothing). The exit marker of the
|
|
4598
|
+
harness's window (0.69) is not the stop's: the window's shell writes it when
|
|
4599
|
+
the harness ends, and on a full disk its write fails too.
|
|
4479
4600
|
|
|
4480
4601
|
In 0.52.0 a stop whose claim could not be written for one of those five
|
|
4481
4602
|
codes was refused like the others, before anything was signalled
|
|
@@ -4567,8 +4688,10 @@ in flight.
|
|
|
4567
4688
|
### Commands that meet on one home
|
|
4568
4689
|
|
|
4569
4690
|
Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
|
|
4570
|
-
hold the home's claim for their whole run, and `oats worktree add` reads it
|
|
4571
|
-
|
|
4691
|
+
hold the home's claim for their whole run, and `oats worktree add` reads it;
|
|
4692
|
+
from OATS 0.69.2 a `session start --resume` holds it too (its rows below).
|
|
4693
|
+
This table covers the commands that arrive on a home; the upgrade pairs and
|
|
4694
|
+
the resume pairs follow separately.
|
|
4572
4695
|
Each cell is the answer of the command that **arrives**. It is given at once
|
|
4573
4696
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
4574
4697
|
nothing, and the command already on the home is not disturbed.
|
|
@@ -4578,8 +4701,10 @@ nothing, and the command already on the home is not disturbed.
|
|
|
4578
4701
|
| a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
4579
4702
|
| a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
4580
4703
|
| a stop apply is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
4704
|
+
| a resume is running | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
4581
4705
|
| a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4582
4706
|
| a stop whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
4707
|
+
| a resume whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | not refused |
|
|
4583
4708
|
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4584
4709
|
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
4585
4710
|
|
|
@@ -4590,13 +4715,30 @@ The `instance-upgrade` pairs use the same home's lifecycle claim:
|
|
|
4590
4715
|
|---|---|---|
|
|
4591
4716
|
| a retire is running | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4592
4717
|
| a self-retire is scheduled | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4593
|
-
| a stop or upgrade apply is running | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4718
|
+
| a stop or upgrade apply, or a `session start --resume`, is running | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4594
4719
|
| a holder's verb is unknown, its liveness cannot be read, or the claim is unreadable | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4595
4720
|
| the holder of the claim is gone | `oats instance upgrade` apply | not refused after claim takeover checks |
|
|
4596
4721
|
| an upgrade apply is running | `oats retire` or `oats instance stop --apply` | `E_LIFECYCLE_BUSY` |
|
|
4597
4722
|
| an upgrade apply is running | `oats worktree add` | not refused |
|
|
4598
4723
|
|
|
4599
|
-
|
|
4724
|
+
<a id="resume-lifecycle-pairs"></a>
|
|
4725
|
+
`oats session start --resume` (OATS 0.69.2, #1559) holds the same claim for
|
|
4726
|
+
the whole start. What it answers when it arrives:
|
|
4727
|
+
|
|
4728
|
+
| On the home | Answer of `oats session start --resume` |
|
|
4729
|
+
|---|---|
|
|
4730
|
+
| a retire is running | `E_INSTANCE_RETIRING` |
|
|
4731
|
+
| a self-retire is scheduled, or a retire is owed (the row's [`retire`](#row-retire)) | `E_INSTANCE_RETIRING` |
|
|
4732
|
+
| a stop, an upgrade or another resume is running | `E_LIFECYCLE_BUSY` |
|
|
4733
|
+
| a holder's liveness cannot be read, or the claim is unreadable | `E_LIFECYCLE_BUSY` |
|
|
4734
|
+
| the holder of the claim is gone | not refused after claim takeover checks |
|
|
4735
|
+
|
|
4736
|
+
The sweep reports each of these `skipped`, `lifecycle-busy`
|
|
4737
|
+
([the sweep's rows](#the-machine-sweep-oats-session-resume)). An upgrade
|
|
4738
|
+
apply refuses a home that is not stopped, so it stops nothing: beside a
|
|
4739
|
+
resume that is still starting, it meets the claim.
|
|
4740
|
+
|
|
4741
|
+
Upgrade requires a stopped session. An ordinary start and restart do not take or read the
|
|
4600
4742
|
lifecycle claim: upgrade instead holds their existing `.oats-start.lock`
|
|
4601
4743
|
mutex until its final invocation receipt is persisted. A start blocked by an
|
|
4602
4744
|
upgrade mutex names the same-key retry. A partial receipt refuses starts through the remaining
|
|
@@ -4677,7 +4819,8 @@ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
|
|
|
4677
4819
|
stop this may be a child of the instance asked for.**
|
|
4678
4820
|
- `lock`: the file that names the holder. `pid` and `since`: the holder's
|
|
4679
4821
|
pid and when it took the claim.
|
|
4680
|
-
- **`action`: the holder's verb**, `"retire"`, `"stop"
|
|
4822
|
+
- **`action`: the holder's verb**, `"retire"`, `"stop"`, `"upgrade"` or
|
|
4823
|
+
`"resume"` (a `session start --resume`, OATS 0.69.2). A claim written
|
|
4681
4824
|
by a kernel before this feature has no verb and reads as `"retire"`. A
|
|
4682
4825
|
reader treats a value it does not know as busy.
|
|
4683
4826
|
- <a id="claim-file-text"></a>**Text of a claim file is never part of an
|
|
@@ -5516,7 +5659,7 @@ line and says that nothing was done:
|
|
|
5516
5659
|
second for a retire, which does not wait).
|
|
5517
5660
|
`details` is `{instance, home, lock, holder: "unknown"}`; the message is
|
|
5518
5661
|
`<lock> is not a readable claim; nothing was done — inspect it and remove
|
|
5519
|
-
it if no oats retire, oats instance stop
|
|
5662
|
+
it if no oats retire, oats instance stop, oats instance upgrade or oats session start --resume holds it, then retry`.
|
|
5520
5663
|
- A claim whose holder is gone and that this kernel cannot take over is
|
|
5521
5664
|
never removed either: its `nonce` is not the 32 hexadecimal digits a claim
|
|
5522
5665
|
carries (a file written or damaged by hand); or it is the claim of a
|
|
@@ -5528,7 +5671,7 @@ line and says that nothing was done:
|
|
|
5528
5671
|
The message is `the
|
|
5529
5672
|
process that held <lock> (pid <pid>) is gone, and this file is not a claim
|
|
5530
5673
|
this kernel can take over (<why>); nothing was done — inspect <lock> and
|
|
5531
|
-
remove it if no oats retire, oats instance stop
|
|
5674
|
+
remove it if no oats retire, oats instance stop, oats instance upgrade or oats session start --resume holds it, then retry` (0.52.0, #874; before,
|
|
5532
5675
|
the first was answered as a live holder, to wait for, and the second as
|
|
5533
5676
|
`E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
|
|
5534
5677
|
does not exist). Removing that one file lets the next retire take the
|
|
@@ -5819,6 +5962,150 @@ palette name is relayed, anything else is `null`), and on `oats inspect
|
|
|
5819
5962
|
row's palette name, else none. Colour never says a state alone: a client's
|
|
5820
5963
|
mark keeps the state by its shape.
|
|
5821
5964
|
|
|
5965
|
+
## Background instances (`oats instance background`)
|
|
5966
|
+
|
|
5967
|
+
Feature `instance-background` (awebai/oats#1579).
|
|
5968
|
+
|
|
5969
|
+
```text
|
|
5970
|
+
oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json]
|
|
5971
|
+
```
|
|
5972
|
+
|
|
5973
|
+
A background instance is listed by the clients under a Background section of
|
|
5974
|
+
its own. That is all it changes: it spawns, starts, attaches, takes input,
|
|
5975
|
+
messages, shows in `oats status` and retires like any other. Like the colour,
|
|
5976
|
+
it is presentation, never identity or policy, and anyone may change it at any
|
|
5977
|
+
time, a stopped instance's included.
|
|
5978
|
+
|
|
5979
|
+
- **At spawn** the value is `--background` or `--no-background`, else the
|
|
5980
|
+
soul's `background:` ([soul.yaml](souls-and-instances.md#soulyaml-v2)),
|
|
5981
|
+
else `false` ([the preview](#the-preview)). Nothing is inherited from a
|
|
5982
|
+
parent, and there is no workspace or host default. A later edit of the soul
|
|
5983
|
+
does not move an existing instance: this command does.
|
|
5984
|
+
- **The record** is `<home>/.oats-background.json`, `{"backgroundApi": 1,
|
|
5985
|
+
"at": "<ISO time>"}`, mode 0600, written atomically. Present means
|
|
5986
|
+
background; `off` removes it. It lasts as long as the home, through start,
|
|
5987
|
+
restart, stop, resume and `oats instance upgrade`. It is a kernel-owned
|
|
5988
|
+
home file: a capability cannot declare it as its own, and it is no change
|
|
5989
|
+
to the home at retire.
|
|
5990
|
+
- **A reader** takes a regular file only, without following a link, of at
|
|
5991
|
+
most 4 KiB, holding a JSON object with `backgroundApi: 1`. Anything else
|
|
5992
|
+
reads as not background, never as an error, and `off` removes it.
|
|
5993
|
+
- **The instance** is addressed and refused exactly as `oats instance color`
|
|
5994
|
+
addresses and refuses it ([An instance's colour](#an-instances-colour-oats-instance-color)),
|
|
5995
|
+
with "the background was not changed" where the colour's refusals say the
|
|
5996
|
+
colour.
|
|
5997
|
+
|
|
5998
|
+
The answer:
|
|
5999
|
+
|
|
6000
|
+
```json
|
|
6001
|
+
{"instanceBackgroundApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","background":true,"changed":true}
|
|
6002
|
+
```
|
|
6003
|
+
|
|
6004
|
+
`on` for a background instance and `off` for one that is not answer
|
|
6005
|
+
`changed: false` and write nothing (`off` still removes an invalid file).
|
|
6006
|
+
The text answer is `<instance>: background` or `<instance>: not
|
|
6007
|
+
background`, with ` (unchanged)` when nothing changed.
|
|
6008
|
+
|
|
6009
|
+
| Code | When |
|
|
6010
|
+
|---|---|
|
|
6011
|
+
| `E_BAD_ARGS` | Not exactly one of `on` or `off`: `give on or off; usage: …` |
|
|
6012
|
+
| *(as `oats instance color`)* | Instance resolution, `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY` |
|
|
6013
|
+
|
|
6014
|
+
Routed with `--server <id>`, the command runs on the host
|
|
6015
|
+
([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
|
|
6016
|
+
not advertise `instance-background` is refused with `E_REMOTE_INCOMPATIBLE`,
|
|
6017
|
+
and nothing is sent. The same holds for a routed `oats spawn` with
|
|
6018
|
+
`--background` or `--no-background`; without either flag the route is
|
|
6019
|
+
unchanged.
|
|
6020
|
+
|
|
6021
|
+
Where it is read: `background: true` on [status rows](#the-roster-oats-status---json),
|
|
6022
|
+
on [remote roster rows](#the-remote-roster-oats-server-roster---json), on
|
|
6023
|
+
`oats inspect --home` as `instance.background`, and on the soul rows of
|
|
6024
|
+
[`oats souls`](#oats-capabilities-and-oats-souls) for a soul that declares
|
|
6025
|
+
it. Each is absent when not background.
|
|
6026
|
+
|
|
6027
|
+
## Same work as the parent (`oats instance same-work`)
|
|
6028
|
+
|
|
6029
|
+
Feature `instance-same-work` (awebai/oats#1577).
|
|
6030
|
+
|
|
6031
|
+
```text
|
|
6032
|
+
oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
|
|
6033
|
+
oats spawn <soul> … --same-work
|
|
6034
|
+
```
|
|
6035
|
+
|
|
6036
|
+
The flag records that an instance does the same work as its parent. Clients
|
|
6037
|
+
draw the parent→child line for an instance that carries it. Nothing else in
|
|
6038
|
+
the kernel reads it: it is not identity, it grants nothing and it never
|
|
6039
|
+
addresses anything.
|
|
6040
|
+
|
|
6041
|
+
- **The record** is `<home>/.oats-same-work.json`, `{"sameWorkApi": 1,
|
|
6042
|
+
"parent": "<instance>", "at": "<ISO time>"}`, mode 0600, written
|
|
6043
|
+
atomically. Present means on; `off` removes it. It is a kernel-owned home
|
|
6044
|
+
file: a capability cannot declare it as its own, a retire does not count it
|
|
6045
|
+
as work (on its own it never makes a recovery copy), and `oats instance
|
|
6046
|
+
upgrade` does not see it as a change to the home.
|
|
6047
|
+
- **A reader** takes a regular file only, without following a link, of at
|
|
6048
|
+
most 4 KiB, holding JSON with `sameWorkApi: 1` and a non-empty string
|
|
6049
|
+
`parent`. Anything else reads as off, never as an error.
|
|
6050
|
+
- **Bound to the parent.** The flag is on only while the record's `parent` is
|
|
6051
|
+
the home's current recorded `parentInstance`. A reparent leaves the record
|
|
6052
|
+
naming the old parent, so the flag reads off: a retire's lineage relink
|
|
6053
|
+
(the instances pointing at the retiree re-pointed to its parent) and a
|
|
6054
|
+
`--relation parent` spawn re-pointing its anchor. `on` binds it to the
|
|
6055
|
+
current parent again.
|
|
6056
|
+
- **Lifetime.** It survives `oats session restart`, a stop and a start, a
|
|
6057
|
+
resume (`oats session start --resume`) and `oats instance upgrade`. Only
|
|
6058
|
+
`off` and retirement clear it.
|
|
6059
|
+
|
|
6060
|
+
**The verb.** The instance is addressed as `oats instance color` addresses
|
|
6061
|
+
it, and refused with the same answers.
|
|
6062
|
+
|
|
6063
|
+
- `on` binds the flag to the instance's recorded `parentInstance`; an
|
|
6064
|
+
instance with none is refused. `on` again while the flag is bound to that
|
|
6065
|
+
parent writes nothing; `on` after a reparent rebinds it to the current
|
|
6066
|
+
parent.
|
|
6067
|
+
- `off` removes whatever stands at the record's name (a file, a link, a
|
|
6068
|
+
directory). It succeeds whether or not the flag was on and whether or not a
|
|
6069
|
+
parent is recorded; `off` again is the same answer.
|
|
6070
|
+
|
|
6071
|
+
The answer, the envelope's `result`, has exactly these two keys:
|
|
6072
|
+
|
|
6073
|
+
```json
|
|
6074
|
+
{"instance":"dev-a","sameWork":true}
|
|
6075
|
+
```
|
|
6076
|
+
|
|
6077
|
+
`sameWork` is the binding rule read after the write: `true` after `on`,
|
|
6078
|
+
`false` after `off`. The text answer is `dev-a: same work on` (or `off`).
|
|
6079
|
+
|
|
6080
|
+
| Code | When |
|
|
6081
|
+
|---|---|
|
|
6082
|
+
| `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with no recorded parent: `<instance> has no parent instance: same work is declared against a recorded parent; the flag was not changed` |
|
|
6083
|
+
| *(as `oats instance color`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
|
|
6084
|
+
| `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes), or the home is quarantined. Nothing was written |
|
|
6085
|
+
| `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
|
|
6086
|
+
|
|
6087
|
+
**At spawn.** `oats spawn … --same-work` sets the flag on the new instance,
|
|
6088
|
+
bound to the parent its home records, whichever relation gave it: `--parent
|
|
6089
|
+
<instance>` or `--relation child`; `--relation sibling` of an anchor that has
|
|
6090
|
+
a parent (the new instance shares it); `--relation parent` of an anchor that
|
|
6091
|
+
had a parent (the new instance inherits it); `--work attached` (the owner of
|
|
6092
|
+
the tree). The record is written inside the spawn, before the launch, so the
|
|
6093
|
+
instance's first status row carries `sameWork: true`; a spawn rolled back
|
|
6094
|
+
removes it with the home. When the new instance would record no parent (no
|
|
6095
|
+
relation, `--relation unrelated`, a sibling of a root anchor, `--relation
|
|
6096
|
+
parent` of a root anchor), the spawn is refused with `E_BAD_ARGS` before
|
|
6097
|
+
anything is created, `--preview` included.
|
|
6098
|
+
|
|
6099
|
+
Routed with `--server <id>`, the verb runs on the host
|
|
6100
|
+
([Routed reads and plans](#routed-reads-and-plans)) and `spawn --server …
|
|
6101
|
+
--same-work` sends the flag there. A host whose probe does not advertise
|
|
6102
|
+
`instance-same-work` is refused with `E_REMOTE_INCOMPATIBLE` for either, and
|
|
6103
|
+
nothing is sent.
|
|
6104
|
+
|
|
6105
|
+
Where it is read: `sameWork` on [status rows](#row-same-work) and on
|
|
6106
|
+
[remote roster rows](#the-remote-roster-oats-server-roster---json) (only
|
|
6107
|
+
`true` is relayed).
|
|
6108
|
+
|
|
5822
6109
|
## Sessions and launch configurations
|
|
5823
6110
|
|
|
5824
6111
|
### Input
|
|
@@ -5861,7 +6148,9 @@ harness receipt. See [execution targets](execution-targets.md).
|
|
|
5861
6148
|
|
|
5862
6149
|
```text
|
|
5863
6150
|
oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
|
|
6151
|
+
oats session start --resume --home <abs> --json
|
|
5864
6152
|
oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
|
|
6153
|
+
oats session resume [--deployment <dir>] [--plan] --json
|
|
5865
6154
|
```
|
|
5866
6155
|
|
|
5867
6156
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
@@ -5941,6 +6230,169 @@ warning naming the same-key cleanup retry.
|
|
|
5941
6230
|
[`details.cause`](#kernel-codes) when it has a code of its own or is a
|
|
5942
6231
|
defect, and without it when it is a refusal without a code).
|
|
5943
6232
|
|
|
6233
|
+
#### Resume a lost session (`--resume`)
|
|
6234
|
+
|
|
6235
|
+
`oats session start --resume --home <abs> --json` (feature `session-resume`,
|
|
6236
|
+
OATS 0.69) is the ordinary start of a home whose session was lost
|
|
6237
|
+
([`sessionEnd: "lost"`](#row-session-end)), in the harness's own last
|
|
6238
|
+
conversation: the same locks, checks, recorded recipe and launch hooks under
|
|
6239
|
+
the captured settings, with the conversation's selector and the resume
|
|
6240
|
+
notice in place of the task prompt
|
|
6241
|
+
([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). Its
|
|
6242
|
+
answer is the ordinary start answer plus one object:
|
|
6243
|
+
|
|
6244
|
+
```json
|
|
6245
|
+
"resume": {
|
|
6246
|
+
"resumed": true,
|
|
6247
|
+
"reason": "no-conversation",
|
|
6248
|
+
"harness": "claude",
|
|
6249
|
+
"sessionId": "<the harness's session id>",
|
|
6250
|
+
"waiting": "resume-confirmation"
|
|
6251
|
+
}
|
|
6252
|
+
```
|
|
6253
|
+
|
|
6254
|
+
- `resumed: true` with `sessionId` when it continues that conversation;
|
|
6255
|
+
`resumed: false` with `reason` when it started fresh on `TASK.md` instead:
|
|
6256
|
+
`no-conversation` (no transcript of this incarnation whose cwd is the
|
|
6257
|
+
home), `no-receipts` (no native-record receipt of this incarnation names
|
|
6258
|
+
where the harness writes), `resume-unproven` (Codex, until a resume of it
|
|
6259
|
+
is proven end to end on a signed-in host).
|
|
6260
|
+
- `waiting: "resume-confirmation"`: the start **succeeded** (exit 0, the
|
|
6261
|
+
session runs and is kept) and Claude is waiting for its human to choose how
|
|
6262
|
+
to resume a long conversation (its resume-cost dialog). No key was sent.
|
|
6263
|
+
Absent otherwise, an unrecognised screen after the bound included.
|
|
6264
|
+
- Refused before anything is read, `E_BAD_ARGS`: `--resume` with
|
|
6265
|
+
`--launch-config`, `--harness`, `--model`, `--yolo`, `--no-yolo` or
|
|
6266
|
+
`--reselect-launch`; `--resume` on `session restart`; `--server`.
|
|
6267
|
+
- It holds the home's lifecycle claim for the whole start (OATS 0.69.2), the
|
|
6268
|
+
claim a retire, a stop apply and an upgrade apply hold, so it never runs
|
|
6269
|
+
beside one of them: beside a retire it is refused `E_INSTANCE_RETIRING`,
|
|
6270
|
+
beside a stop, an upgrade or another resume `E_LIFECYCLE_BUSY`, before
|
|
6271
|
+
anything is read or started, and one of them that arrives while it holds
|
|
6272
|
+
the claim is refused `E_LIFECYCLE_BUSY` with `details.action: "resume"`
|
|
6273
|
+
([Commands that meet on one home](#lifecycle-pairs)). A home that is not
|
|
6274
|
+
there takes no claim. An ordinary start or restart takes none.
|
|
6275
|
+
- Refused `E_INSTANCE_RETIRING` when the home is owed a retire: its status
|
|
6276
|
+
row's [`retire`](#row-retire) has a value (a retire runs, cannot be told,
|
|
6277
|
+
failed or was interrupted) or a self-retire is scheduled, read under the
|
|
6278
|
+
claim; nothing was started.
|
|
6279
|
+
- Refused `E_RESUME_NOT_LOST` when the home did not lose its session
|
|
6280
|
+
(`stopped`, `exited`, never launched), read under the claim and the start
|
|
6281
|
+
lock before any launch hook runs; nothing was started.
|
|
6282
|
+
- Refused `E_LAUNCH_ENV_CHANGED` when a `{fromEnv}` value differs from the
|
|
6283
|
+
one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
|
|
6284
|
+
the message names the variables, sorted, never a value; nothing was
|
|
6285
|
+
started. A home with no record of its last start's values (last started
|
|
6286
|
+
by an earlier kernel, or a record that does not read) is resumed, and
|
|
6287
|
+
`warnings` carries once `<instance>'s launch environment could not be
|
|
6288
|
+
verified this once (it was last started before OATS recorded it); its
|
|
6289
|
+
next start records it` ([The launch environment a resume runs
|
|
6290
|
+
under](execution-targets.md#the-launch-environment-a-resume-runs-under)).
|
|
6291
|
+
- Every refusal of an ordinary start answers as it does there
|
|
6292
|
+
(`E_SESSION_RUNNING`, `E_SESSION_START_BUSY`, `E_SESSION_UNKNOWN`,
|
|
6293
|
+
`E_LAUNCH_LEGACY` for a home with no recipe, `E_LAUNCH_ENV_MISSING`, …); a
|
|
6294
|
+
development-channel prompt that stops it is `E_SPAWN_INCOMPLETE` with
|
|
6295
|
+
`details.launchPrompts`, unchanged. A start by hand is neither bounded
|
|
6296
|
+
nor counted by the sweep's 3 resumes per home per boot.
|
|
6297
|
+
- What is persisted is the ordinary launch: `instance.json` `command`, the
|
|
6298
|
+
pending receipt and the recipe never carry the selector or the notice, so a
|
|
6299
|
+
later ordinary start opens a fresh conversation.
|
|
6300
|
+
|
|
6301
|
+
### The machine sweep (`oats session resume`)
|
|
6302
|
+
|
|
6303
|
+
`oats session resume [--deployment <dir>] [--plan] --json` (feature
|
|
6304
|
+
`session-resume`, OATS 0.69) starts with `--resume` every home of this
|
|
6305
|
+
machine's deployments whose session was lost. A client runs it once when it
|
|
6306
|
+
opens. It reads this computer's list of deployments without writing it
|
|
6307
|
+
([This computer's deployments](#this-computers-deployments-oats-deployments)),
|
|
6308
|
+
and never sweeps one `oats deployments remove` took out;
|
|
6309
|
+
`--deployment <dir>` sweeps that one directory instead, listed or not. Each
|
|
6310
|
+
home starts as a child process of the kernel, in its own deployment's scope,
|
|
6311
|
+
at most 4 at once.
|
|
6312
|
+
|
|
6313
|
+
The answer is the standard envelope, exit 0 whenever the sweep ran,
|
|
6314
|
+
whatever the rows say:
|
|
6315
|
+
|
|
6316
|
+
```json
|
|
6317
|
+
{"schemaVersion":1,"ok":true,"result":{
|
|
6318
|
+
"schemaVersion": 1,
|
|
6319
|
+
"plan": false,
|
|
6320
|
+
"deployments": [
|
|
6321
|
+
{ "deployment": "/abs/dep", "state": "ok", "swept": true },
|
|
6322
|
+
{ "deployment": "/abs/gone", "state": "missing", "swept": false, "reason": "not-ok" }
|
|
6323
|
+
],
|
|
6324
|
+
"rows": [
|
|
6325
|
+
{ "deployment": "/abs/dep", "instance": "x", "home": "/abs/dep/agents/s/instances/x", "outcome": "resumed", "sessionId": "…" },
|
|
6326
|
+
{ "deployment": "/abs/dep", "instance": "y", "home": "…", "outcome": "fresh", "reason": "no-conversation" },
|
|
6327
|
+
{ "deployment": "/abs/dep", "instance": "z", "home": "…", "outcome": "already-running" }
|
|
6328
|
+
]}}
|
|
6329
|
+
```
|
|
6330
|
+
|
|
6331
|
+
- **`deployments[]`**: one entry per deployment considered, sorted by path.
|
|
6332
|
+
`state` is the list's state of it (`ok`, `missing`, `not-a-deployment`,
|
|
6333
|
+
`unreadable`). `swept: false` has a `reason`: `not-ok` (its state is not
|
|
6334
|
+
`ok`) or `unreadable` (its status could not be read; `code` and `message`
|
|
6335
|
+
then). Nothing opts a deployment out: stopping an instance with OATS is
|
|
6336
|
+
the only way to keep it down.
|
|
6337
|
+
- **`rows[]`**: one row per home that is lost (whatever its outcome),
|
|
6338
|
+
running (`already-running`) or unknown (`skipped`, `unknown`); stopped,
|
|
6339
|
+
exited and never-launched homes are not listed. Fields: `deployment`,
|
|
6340
|
+
`instance`, `home`, `outcome`, and only when they apply `reason`, `code`,
|
|
6341
|
+
`message`, `launchPrompts`, `sessionId` (resumed) and `warnings` (the
|
|
6342
|
+
start's warnings verbatim, an array of strings, present only when not
|
|
6343
|
+
empty: a client lists `channel-cache-unchecked` from here), without the
|
|
6344
|
+
host-wide ones the sweep's own `warnings` carries.
|
|
6345
|
+
|
|
6346
|
+
| `outcome` | `reason` |
|
|
6347
|
+
|---|---|
|
|
6348
|
+
| `resumed` | none |
|
|
6349
|
+
| `fresh` | `no-conversation`, `no-receipts`, `resume-unproven` |
|
|
6350
|
+
| `already-running` | none |
|
|
6351
|
+
| `skipped` | `not-seen-recently` (the sweep cannot vouch for this loss: OATS never saw the home running for its current start, an earlier sweep already answered the loss, the loss was first seen 24 hours ago or more, or, within one boot, it was first seen 24 hours or more after the last running look; with a `message` that says which, nothing started: [Which losses come back](execution-targets.md#which-losses-come-back)), `unknown` (running reads `null`, or the start could not establish it: `code` `E_SESSION_UNKNOWN`), `start-busy` (`E_SESSION_START_BUSY`: a concurrent start), `not-lost` (`E_RESUME_NOT_LOST` or `E_SESSION_RUNNING`, or any refusal of a home that is gone: it stopped, started or was removed between the read and the start), `lifecycle-busy` (OATS 0.69.2: OATS is stopping, upgrading or retiring the home, or its retire is owed; read from its row, with a `message`, or answered by its start, with the start's `code`, `E_INSTANCE_RETIRING` or `E_LIFECYCLE_BUSY`, and `message`; nothing started) |
|
|
6352
|
+
| `blocked` | `resume-confirmation` (Claude's resume-cost dialog: the session runs and waits for its human), `launch-prompt` (`code` `E_SPAWN_INCOMPLETE`, with `launchPrompts`: the session is kept) |
|
|
6353
|
+
| `refused` | `start-refused` (`code` and `message`: the start's own refusal), `refused-this-boot` (an earlier sweep in this boot was refused for this home and start, and its answer to the loss was lost: reported again with that `code` and `message`, nothing started; a refused loss is never retried automatically, after a reboot either), `keeps-getting-lost` (sweeps started this home 3 times in this boot and it was lost again each time: nothing started, no `code`, a `message` that says so; no sweep starts this loss again, after a reboot either: a person starts it by hand) |
|
|
6354
|
+
|
|
6355
|
+
The kernel defines every `sessionEnd`, `resume` and row name in one
|
|
6356
|
+
module, `lib/session-resume-contract.mjs`; a change to one is a contract
|
|
6357
|
+
change ([#1567](https://github.com/awebai/oats/issues/1567)).
|
|
6358
|
+
|
|
6359
|
+
- **`warnings`**, beside `rows`, present only when there is one: an array
|
|
6360
|
+
of distinct strings, each a warning the sweep's starts said of the host
|
|
6361
|
+
rather than of their home, once whatever the number of starts that said
|
|
6362
|
+
it, verbatim. Today that is only the agent-scope warning (the harness
|
|
6363
|
+
runs in the OATS tmux server's cgroup, not a scope of its own, and why).
|
|
6364
|
+
Each start still records it in its own home's events. `--plan` has none.
|
|
6365
|
+
- A lost home is answered with the first that applies: `lifecycle-busy`,
|
|
6366
|
+
`not-seen-recently`, `refused-this-boot`, `keeps-getting-lost`, then its
|
|
6367
|
+
start. A sweep that is not a plan answers each lost home once: a later
|
|
6368
|
+
sweep answers that loss `not-seen-recently`. A `lifecycle-busy` row does
|
|
6369
|
+
not answer it: whatever OATS was doing to the home decides what it is
|
|
6370
|
+
next, and a later sweep reads it again.
|
|
6371
|
+
- A home whose self-retire is scheduled or owed reads no `sessionEnd`; a
|
|
6372
|
+
launched one that does not run is listed `skipped`, `lifecycle-busy`, as
|
|
6373
|
+
a lost one is.
|
|
6374
|
+
- `--plan`: the same shape with `"plan": true`; nothing is started, no lock
|
|
6375
|
+
taken, no note written, no loss answered (its own status read records what
|
|
6376
|
+
it sees, as any local status read does). A lost home's outcome is the prediction: `resumed`
|
|
6377
|
+
(with `sessionId`) or `fresh` with its reason (and the launch-environment
|
|
6378
|
+
warning a start would give), `refused` for a noted refusal, a home sweeps
|
|
6379
|
+
started 3 times in this boot, a home with no recipe, or a launch reference
|
|
6380
|
+
the start would refuse (`E_LAUNCH_ENV_MISSING`, `E_LAUNCH_ENV_CHANGED`,
|
|
6381
|
+
from the sweep's environment). Clients should not call `--plan` on open.
|
|
6382
|
+
- **One sweep per machine.** A second sweep while one runs answers
|
|
6383
|
+
`E_RESUME_BUSY` through the standard failure envelope
|
|
6384
|
+
(`{"schemaVersion":1,"ok":false,"error":{"code":"E_RESUME_BUSY","message":"…"}}`,
|
|
6385
|
+
exit 1); nothing was started, and a client shows no notice. The lock and
|
|
6386
|
+
the per-boot note (refusals, and each home's count of sweep starts that
|
|
6387
|
+
launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
|
|
6388
|
+
not a contract. Without a boot id (neither Linux nor macOS) nothing is
|
|
6389
|
+
noted or counted.
|
|
6390
|
+
- Errors: `E_RESUME_BUSY`; `E_BAD_ARGS` (`--deployment` that is not a
|
|
6391
|
+
deployment directory, `--server`, an unknown flag or an argument); without
|
|
6392
|
+
`--deployment`, the list's own errors (`E_DEPLOYMENTS_INVALID`,
|
|
6393
|
+
`E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
|
|
6394
|
+
sweep's failure.
|
|
6395
|
+
|
|
5944
6396
|
### Upload
|
|
5945
6397
|
|
|
5946
6398
|
```text
|
|
@@ -5957,6 +6409,129 @@ stored file); a remote upload adds `server`, `instance` and `stderr?`. Errors:
|
|
|
5957
6409
|
sha256 mismatch; the remote file is left), `E_SESSION_UNKNOWN`,
|
|
5958
6410
|
`E_REMOTE_INCOMPATIBLE`.
|
|
5959
6411
|
|
|
6412
|
+
### How the clients run the sweep
|
|
6413
|
+
|
|
6414
|
+
The kernel's machine sweep, `oats session resume --json`
|
|
6415
|
+
([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), is
|
|
6416
|
+
run by a client when it opens and again when its rosters show a lost session
|
|
6417
|
+
([When Desktop opens](desktop-instance-start.md#when-desktop-opens)). The
|
|
6418
|
+
clients share one trigger, one runner and one reader, so the Desktop and the
|
|
6419
|
+
TUI decide, run and read it the same way.
|
|
6420
|
+
|
|
6421
|
+
**The trigger**, `createResumeTrigger({ cli, run, read, now, onReading })`
|
|
6422
|
+
(`packages/client/session-resume-trigger.mjs`), holds the rule:
|
|
6423
|
+
|
|
6424
|
+
- `launch()` arms it and runs the launch sweep, with no floor. A client calls
|
|
6425
|
+
it once, after anything the sweep reads is in place (the Desktop: after the
|
|
6426
|
+
startup deployments-list step). `observed()` does nothing before it.
|
|
6427
|
+
- `observed(rows, { localDeploymentIds })` is given each roster's instance
|
|
6428
|
+
rows as the client reads them, with the ids of that read's local
|
|
6429
|
+
deployments (the Desktop: `instances` of each accepted `/api/panel` reply,
|
|
6430
|
+
and `localDeploymentIds(reply)`, its `deployments[]` entries with
|
|
6431
|
+
`local: true`). It starts a sweep only when none is in flight, at least
|
|
6432
|
+
`RESUME_MIN_INTERVAL_MS` (30 s) has passed since the last sweep that ran
|
|
6433
|
+
started, and `lostLocalHomes(rows, localDeploymentIds)` names a home that
|
|
6434
|
+
is not settled. Locality is the roster's, by deployment id: a row is local
|
|
6435
|
+
only when its `deployment.id` (the panel's tag) is one of the local ids. A
|
|
6436
|
+
remote deployment's row, a row with no tag, and every row when no ids are
|
|
6437
|
+
given are not local; a client never acts on another host's loss.
|
|
6438
|
+
`lostLocalHomes` keeps a local row's absolute `home` when its `sessionEnd`
|
|
6439
|
+
says the session was lost and it is not running; it is the one place that
|
|
6440
|
+
reads `sessionEnd`'s meaning. There is no timer and no queue.
|
|
6441
|
+
- After a sweep that a status read started completes (quiet or a notice),
|
|
6442
|
+
every instance it was started for waits until it changes: it runs, or it is
|
|
6443
|
+
no longer lost. A busy, failed or unsupported sweep, or a plan, settles
|
|
6444
|
+
nothing. A home a read releases while the sweep runs is settled by neither
|
|
6445
|
+
the snapshot nor the answer: that read is newer. A home
|
|
6446
|
+
is also settled when a sweep could not resume it, found it was not lost, or
|
|
6447
|
+
skipped it because the kernel had not seen it running recently. A sweep
|
|
6448
|
+
that resumed it, started it fresh, left it waiting for you or found it
|
|
6449
|
+
running unsettles it, and so does a later roster row that is running or not
|
|
6450
|
+
lost. So a home that cannot be resumed costs at most one sweep after the
|
|
6451
|
+
launch's. Which rows mean which is read in `session-resume.mjs` alone
|
|
6452
|
+
(`sweepSettlement`, `sweepCompleted`).
|
|
6453
|
+
- `cli()` gives the accepted probe or null, or a promise of either, and is
|
|
6454
|
+
asked at each would-be start: the sweep runs only when `resumeSupported`
|
|
6455
|
+
holds. When it does not, nothing runs and the floor does not move.
|
|
6456
|
+
- Before reading an answer, it drops each `refused` row whose
|
|
6457
|
+
`(home, reason, code)` an earlier sweep of this trigger already reported,
|
|
6458
|
+
so a standing refusal is reported once. A home released (above) forgets its
|
|
6459
|
+
reported refusals: refused again after it recovered, it is news. Every other
|
|
6460
|
+
row is kept. The same goes for the result's own `warnings` (about the host):
|
|
6461
|
+
one a notice of this trigger showed is left out of later answers by its
|
|
6462
|
+
exact string, for the whole run; one only a quiet sweep carried stays news.
|
|
6463
|
+
- `onReading(reading)` is called for every finished sweep, whatever the
|
|
6464
|
+
reading. `launch()` and `observed()` never throw or reject; a `run` that
|
|
6465
|
+
rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
|
|
6466
|
+
and cancels nothing: a sweep in flight runs to its end.
|
|
6467
|
+
|
|
6468
|
+
The Desktop shows nothing of a reading (the product owner, 2026-10-27): its
|
|
6469
|
+
main process writes a `failed` reading's code to its log in one line and drops
|
|
6470
|
+
every other reading, a `notice` included. The TUI says nothing of a reading
|
|
6471
|
+
either: a `notice` or a `quiet` reading asks it for a live read, and every
|
|
6472
|
+
other reading for nothing
|
|
6473
|
+
([Resuming lost sessions](tui.md#resuming-lost-sessions)).
|
|
6474
|
+
|
|
6475
|
+
**The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
|
|
6476
|
+
|
|
6477
|
+
- It runs only when the probe is accepted, its `bin` is absolute and its
|
|
6478
|
+
`features` list `session-resume` (`resumeSupported`). Otherwise it runs
|
|
6479
|
+
nothing and answers `E_CLI_UNAVAILABLE` or `E_RESUME_FEATURE`. Nothing falls
|
|
6480
|
+
back.
|
|
6481
|
+
- The argv is exactly `session resume --json`, with no `--deployment`, no
|
|
6482
|
+
`--plan` and no `--server`. The working directory is `/`, so the kernel
|
|
6483
|
+
resolves no deployment from the client's own. The environment is the
|
|
6484
|
+
client's, without what Desktop's packaging adds (`cliEnvironment`) and without
|
|
6485
|
+
the instance variables (`withoutInstanceVariables`,
|
|
6486
|
+
`packages/client/kernel-environment.mjs`): a client started inside an
|
|
6487
|
+
instance's pane must not scope the sweep to that instance. `OATS_HOME_DIR`
|
|
6488
|
+
passes through.
|
|
6489
|
+
- It sets no deadline. The sweep runs in a process session of its own, and its
|
|
6490
|
+
stdout and stderr are files, not pipes: `execFileToFiles`
|
|
6491
|
+
(`packages/client/file-output-exec.mjs`) unlinks them right after the spawn
|
|
6492
|
+
and reads them back from its own descriptors. Neither the client's exit nor
|
|
6493
|
+
a signal to it reaches the sweep, and nothing is left on disk. A caller that
|
|
6494
|
+
passes its own exec must keep those three properties: detached, file-backed,
|
|
6495
|
+
and never signalling the child.
|
|
6496
|
+
- It answers the kernel's envelope: the result at exit 0, and an `ok:false`
|
|
6497
|
+
envelope whatever the exit (`E_RESUME_BUSY` exits 1). Otherwise it answers
|
|
6498
|
+
a code of its own, with no message: `E_CLI_OUTPUT_LIMIT` (more than 4 MiB),
|
|
6499
|
+
`E_CLI_PROTOCOL` (no envelope), `E_CLI_FAILED` (a nonzero exit without an
|
|
6500
|
+
`ok:false` envelope, or an exec that throws). No stderr and no exception text
|
|
6501
|
+
reaches the answer.
|
|
6502
|
+
|
|
6503
|
+
**The reader**, `readResumeSweep` (`packages/client/session-resume.mjs`),
|
|
6504
|
+
gives one of five readings: `unsupported` (nothing ran), `busy`
|
|
6505
|
+
(`E_RESUME_BUSY`), `failed` with a code, `quiet`, or `notice` with a summary.
|
|
6506
|
+
A plan answer (`plan: true`) is quiet.
|
|
6507
|
+
|
|
6508
|
+
- The summary is facts: per row its instance, its deployment and its outcome's
|
|
6509
|
+
reason, never a word of the kernel's text. `already-running` and `skipped`
|
|
6510
|
+
rows are counted nowhere. A notice exists only when a row is `resumed`,
|
|
6511
|
+
`fresh`, `blocked` or `refused`. Unchecked deployments are lines inside such
|
|
6512
|
+
a notice, never a notice on their own; a deployment the kernel reports as
|
|
6513
|
+
`opted-out` (an older kernel) reads as unchecked, with no reason.
|
|
6514
|
+
- It is tolerant. A row without a string `instance` and `deployment`, with an
|
|
6515
|
+
unknown `outcome`, or whose name the display filter withholds or empties, is
|
|
6516
|
+
dropped. An unknown `reason` under a known outcome is read as no reason and
|
|
6517
|
+
worded generically. A refusal's `code` is kept only when it matches
|
|
6518
|
+
`^E_[A-Z0-9_]{1,64}$`.
|
|
6519
|
+
- The result's own `warnings`, about the host and not one home, are the
|
|
6520
|
+
summary's `host` (`{warnings, omitted}`, always present), kept and cut as a
|
|
6521
|
+
row's are (below). They never make a notice alone; a notice shows them after
|
|
6522
|
+
the unchecked deployments, under "OATS says about this computer:".
|
|
6523
|
+
- A row's `warnings` are kept whole and in order, each as one display line
|
|
6524
|
+
(`displayLine`), and cut by position only, at the bounds of
|
|
6525
|
+
`launchFlagIgnored` (16 lines, 4096 UTF-16 units; `boundedWarnings`,
|
|
6526
|
+
`packages/client/launch-prompt-outcome.mjs`). No warning is picked, matched
|
|
6527
|
+
or dropped by its words.
|
|
6528
|
+
- A refused row's `message` is the kernel's prose. It is shown only after
|
|
6529
|
+
"OATS says:", attributed, through the display filter, and never matched.
|
|
6530
|
+
- The summary keeps at most 100 rows, in the answer's order, and counts the
|
|
6531
|
+
rest. The headline counts the real totals. `resumeSummaryFact` is the
|
|
6532
|
+
summary's decoder at a boundary, and `resumeNotice` writes the headline and
|
|
6533
|
+
the Details in the clients' own words (the TUI's line).
|
|
6534
|
+
|
|
5960
6535
|
### Launch configurations
|
|
5961
6536
|
|
|
5962
6537
|
```text
|