@awebai/oats 0.69.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 +79 -15
- package/docs/capabilities.md +24 -5
- package/docs/capability-manifest.schema.json +1 -1
- 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 +260 -28
- package/docs/desktop-instance-start.md +8 -37
- package/docs/desktop.md +76 -9
- package/docs/execution-targets.md +27 -5
- package/docs/implementation.md +6 -5
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +7 -2
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +35 -2
- package/docs/tui.md +100 -9
- package/docs/upgrading.md +9 -5
- 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 +162 -49
- package/lib/instance-background.mjs +54 -0
- 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/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/servers.mjs +19 -4
- package/lib/session-resume-contract.mjs +1 -0
- package/lib/session-resume.mjs +36 -9
- package/lib/soul-composition.mjs +13 -10
- package/lib/workspace.mjs +3 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +30 -8
- package/packages/client/deployment-data.mjs +9 -0
- package/packages/client/deployment-panel.mjs +4 -0
- package/packages/client/instance-tree.mjs +64 -14
- 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-resume.mjs +1 -1
- 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/tui/README.md +2 -2
- package/packages/tui/lib/client.mjs +6 -2
- package/packages/tui/lib/main.mjs +44 -11
- package/packages/tui/lib/model.mjs +101 -43
- package/packages/tui/lib/store.mjs +76 -20
- package/packages/tui/lib/views/frame.mjs +2 -0
- package/packages/tui/lib/views/help.mjs +2 -0
- package/packages/tui/lib/views/instances.mjs +38 -1
- package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/desktop-cli-api.md
CHANGED
|
@@ -149,10 +149,12 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
149
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 | |
|
|
150
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`) | |
|
|
151
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`) | |
|
|
152
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` |
|
|
153
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 | |
|
|
154
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) | |
|
|
155
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) |
|
|
156
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` | |
|
|
157
159
|
|
|
158
160
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
@@ -514,7 +516,7 @@ capabilities}`, each the soul.yaml section as written or `null`.
|
|
|
514
516
|
with `--instructions`, which takes a soul subject (`--home` is `E_BAD_ARGS`);
|
|
515
517
|
without the flag the key is absent and nothing extra is composed. It is the
|
|
516
518
|
AGENTS.md a spawn of this soul here with no flags would write, produced by
|
|
517
|
-
spawn's own composition —
|
|
519
|
+
spawn's own composition — each capability's inject, then the kernel blocks,
|
|
518
520
|
materialized into a scratch home outside the deployment and removed. It is
|
|
519
521
|
`{file: null, text, truncated, resolution, body, sources}`. `text` and
|
|
520
522
|
`truncated` follow the 200,000-character cap of `instructions`; `resolution` is
|
|
@@ -1260,8 +1262,10 @@ are absent until `sync`.
|
|
|
1260
1262
|
**Soul rows:** `name, origin, kind (member | external | package), repoKey,
|
|
1261
1263
|
commit, teams, defaultTeam, private (always false), path, work, description`,
|
|
1262
1264
|
plus the Desktop facts `harness, model, harnessFrom, file, spawnable,
|
|
1263
|
-
problem`, (feature `souls-capabilities`) `capabilities`,
|
|
1264
|
-
`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.
|
|
1265
1269
|
- `key` is the soul key that `souls.launch` uses, and that
|
|
1266
1270
|
`oats soul teams <key>` takes: `qualifiedName` for a package
|
|
1267
1271
|
soul, the bare `name` for a member or external soul. Two member souls that
|
|
@@ -2476,6 +2480,20 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2476
2480
|
native probes share one 20 s budget.
|
|
2477
2481
|
- `policy.childSpawns` is what the instance will record.
|
|
2478
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
|
+
|
|
2479
2497
|
**Composition.**
|
|
2480
2498
|
- `modules[]` (feature `instance-modules`): `{name, from, layer, private,
|
|
2481
2499
|
declares, changedSince, composedFrom}`; `from` is what `instance.json` will
|
|
@@ -2671,8 +2689,11 @@ preview's call and rules above, through the soul's harness.
|
|
|
2671
2689
|
revision}`. `effective` (feature `spawn-apply-2`) is `{repo, work, harness,
|
|
2672
2690
|
model, launchConfig, yolo, backend, childSpawns, relation, providers}`;
|
|
2673
2691
|
`relation` is `null` or `{kind, anchor: {instance, agentsRoot}}`; `providers`
|
|
2674
|
-
(feature `served-identity`) equals `settings`. `
|
|
2675
|
-
|
|
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.
|
|
2676
2697
|
|
|
2677
2698
|
Apply with `oats spawn <soul> … --expect-decision <revision> --json`. Any drift
|
|
2678
2699
|
refuses `E_DECISION_STALE` with the fresh `details.decision`; nothing is
|
|
@@ -2762,6 +2783,10 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
2762
2783
|
--home <home>` for `--no-launch`. A value is single-quoted only when it
|
|
2763
2784
|
holds a character outside `A-Za-z0-9_./:-`. It is not a field to parse:
|
|
2764
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`.
|
|
2765
2790
|
- When they apply: `yolo`, `decision` and
|
|
2766
2791
|
`replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
|
|
2767
2792
|
`wakeScheduleError` (a requested wake), `worktreeHooks` (feature
|
|
@@ -2922,7 +2947,7 @@ kernel stage raised as well.
|
|
|
2922
2947
|
|
|
2923
2948
|
| Code | Details | When |
|
|
2924
2949
|
|---|---|---|
|
|
2925
|
-
| `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)) |
|
|
2926
2951
|
| `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
|
|
2927
2952
|
| `E_SOUL_UNKNOWN` | `{name, members, packages}` | no such soul, or not at `--agents-root` |
|
|
2928
2953
|
| `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
|
|
@@ -3333,6 +3358,19 @@ its absence.
|
|
|
3333
3358
|
a `color` in `instance.json` never stands in for it. Every row has it,
|
|
3334
3359
|
an unreadable record's row included (`null`). Presentation only: it is not
|
|
3335
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.
|
|
3336
3374
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3337
3375
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3338
3376
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -3574,6 +3612,15 @@ route target:
|
|
|
3574
3612
|
cut to the same bound. `oats status --server
|
|
3575
3613
|
<id> --json` relays the host's answer verbatim, `retire` included, as it
|
|
3576
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.
|
|
3577
3624
|
- **`addressable`** (0.31): `true` for every row the host reports. Routed
|
|
3578
3625
|
session and lifecycle commands reach it by `--home`, or by name when the
|
|
3579
3626
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
@@ -3803,6 +3850,8 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
3803
3850
|
| `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3804
3851
|
| `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3805
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` |
|
|
3806
3855
|
|
|
3807
3856
|
- The flags are the local command's. The instance is addressed like every
|
|
3808
3857
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -4639,8 +4688,10 @@ in flight.
|
|
|
4639
4688
|
### Commands that meet on one home
|
|
4640
4689
|
|
|
4641
4690
|
Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
|
|
4642
|
-
hold the home's claim for their whole run, and `oats worktree add` reads it
|
|
4643
|
-
|
|
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.
|
|
4644
4695
|
Each cell is the answer of the command that **arrives**. It is given at once
|
|
4645
4696
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
4646
4697
|
nothing, and the command already on the home is not disturbed.
|
|
@@ -4650,8 +4701,10 @@ nothing, and the command already on the home is not disturbed.
|
|
|
4650
4701
|
| a retire is running | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
4651
4702
|
| a self-retire is scheduled | `E_LIFECYCLE_BUSY` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` | `E_INSTANCE_RETIRING` |
|
|
4652
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 |
|
|
4653
4705
|
| a retire whose liveness cannot be read holds the claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4654
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 |
|
|
4655
4708
|
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4656
4709
|
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
4657
4710
|
|
|
@@ -4662,13 +4715,30 @@ The `instance-upgrade` pairs use the same home's lifecycle claim:
|
|
|
4662
4715
|
|---|---|---|
|
|
4663
4716
|
| a retire is running | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4664
4717
|
| a self-retire is scheduled | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4665
|
-
| 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` |
|
|
4666
4719
|
| a holder's verb is unknown, its liveness cannot be read, or the claim is unreadable | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4667
4720
|
| the holder of the claim is gone | `oats instance upgrade` apply | not refused after claim takeover checks |
|
|
4668
4721
|
| an upgrade apply is running | `oats retire` or `oats instance stop --apply` | `E_LIFECYCLE_BUSY` |
|
|
4669
4722
|
| an upgrade apply is running | `oats worktree add` | not refused |
|
|
4670
4723
|
|
|
4671
|
-
|
|
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
|
|
4672
4742
|
lifecycle claim: upgrade instead holds their existing `.oats-start.lock`
|
|
4673
4743
|
mutex until its final invocation receipt is persisted. A start blocked by an
|
|
4674
4744
|
upgrade mutex names the same-key retry. A partial receipt refuses starts through the remaining
|
|
@@ -4749,7 +4819,8 @@ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
|
|
|
4749
4819
|
stop this may be a child of the instance asked for.**
|
|
4750
4820
|
- `lock`: the file that names the holder. `pid` and `since`: the holder's
|
|
4751
4821
|
pid and when it took the claim.
|
|
4752
|
-
- **`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
|
|
4753
4824
|
by a kernel before this feature has no verb and reads as `"retire"`. A
|
|
4754
4825
|
reader treats a value it does not know as busy.
|
|
4755
4826
|
- <a id="claim-file-text"></a>**Text of a claim file is never part of an
|
|
@@ -5588,7 +5659,7 @@ line and says that nothing was done:
|
|
|
5588
5659
|
second for a retire, which does not wait).
|
|
5589
5660
|
`details` is `{instance, home, lock, holder: "unknown"}`; the message is
|
|
5590
5661
|
`<lock> is not a readable claim; nothing was done — inspect it and remove
|
|
5591
|
-
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`.
|
|
5592
5663
|
- A claim whose holder is gone and that this kernel cannot take over is
|
|
5593
5664
|
never removed either: its `nonce` is not the 32 hexadecimal digits a claim
|
|
5594
5665
|
carries (a file written or damaged by hand); or it is the claim of a
|
|
@@ -5600,7 +5671,7 @@ line and says that nothing was done:
|
|
|
5600
5671
|
The message is `the
|
|
5601
5672
|
process that held <lock> (pid <pid>) is gone, and this file is not a claim
|
|
5602
5673
|
this kernel can take over (<why>); nothing was done — inspect <lock> and
|
|
5603
|
-
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,
|
|
5604
5675
|
the first was answered as a live holder, to wait for, and the second as
|
|
5605
5676
|
`E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
|
|
5606
5677
|
does not exist). Removing that one file lets the next retire take the
|
|
@@ -5891,6 +5962,150 @@ palette name is relayed, anything else is `null`), and on `oats inspect
|
|
|
5891
5962
|
row's palette name, else none. Colour never says a state alone: a client's
|
|
5892
5963
|
mark keeps the state by its shape.
|
|
5893
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
|
+
|
|
5894
6109
|
## Sessions and launch configurations
|
|
5895
6110
|
|
|
5896
6111
|
### Input
|
|
@@ -6049,9 +6264,21 @@ answer is the ordinary start answer plus one object:
|
|
|
6049
6264
|
- Refused before anything is read, `E_BAD_ARGS`: `--resume` with
|
|
6050
6265
|
`--launch-config`, `--harness`, `--model`, `--yolo`, `--no-yolo` or
|
|
6051
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.
|
|
6052
6279
|
- Refused `E_RESUME_NOT_LOST` when the home did not lose its session
|
|
6053
|
-
(`stopped`, `exited`, never launched), read under the
|
|
6054
|
-
any launch hook runs; nothing was started.
|
|
6280
|
+
(`stopped`, `exited`, never launched), read under the claim and the start
|
|
6281
|
+
lock before any launch hook runs; nothing was started.
|
|
6055
6282
|
- Refused `E_LAUNCH_ENV_CHANGED` when a `{fromEnv}` value differs from the
|
|
6056
6283
|
one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
|
|
6057
6284
|
the message names the variables, sorted, never a value; nothing was
|
|
@@ -6121,7 +6348,7 @@ whatever the rows say:
|
|
|
6121
6348
|
| `resumed` | none |
|
|
6122
6349
|
| `fresh` | `no-conversation`, `no-receipts`, `resume-unproven` |
|
|
6123
6350
|
| `already-running` | none |
|
|
6124
|
-
| `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
|
|
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) |
|
|
6125
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) |
|
|
6126
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) |
|
|
6127
6354
|
|
|
@@ -6135,10 +6362,15 @@ whatever the rows say:
|
|
|
6135
6362
|
it, verbatim. Today that is only the agent-scope warning (the harness
|
|
6136
6363
|
runs in the OATS tmux server's cgroup, not a scope of its own, and why).
|
|
6137
6364
|
Each start still records it in its own home's events. `--plan` has none.
|
|
6138
|
-
- A lost home is answered with the first that applies: `
|
|
6139
|
-
`refused-this-boot`, `keeps-getting-lost`, then its
|
|
6140
|
-
not a plan answers each lost home once: a later
|
|
6141
|
-
`not-seen-recently`.
|
|
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.
|
|
6142
6374
|
- `--plan`: the same shape with `"plan": true`; nothing is started, no lock
|
|
6143
6375
|
taken, no note written, no loss answered (its own status read records what
|
|
6144
6376
|
it sees, as any local status read does). A lost home's outcome is the prediction: `resumed`
|
|
@@ -6233,11 +6465,12 @@ TUI decide, run and read it the same way.
|
|
|
6233
6465
|
rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
|
|
6234
6466
|
and cancels nothing: a sweep in flight runs to its end.
|
|
6235
6467
|
|
|
6236
|
-
The Desktop
|
|
6237
|
-
|
|
6238
|
-
|
|
6239
|
-
|
|
6240
|
-
|
|
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)).
|
|
6241
6474
|
|
|
6242
6475
|
**The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
|
|
6243
6476
|
|
|
@@ -6296,9 +6529,8 @@ A plan answer (`plan: true`) is quiet.
|
|
|
6296
6529
|
"OATS says:", attributed, through the display filter, and never matched.
|
|
6297
6530
|
- The summary keeps at most 100 rows, in the answer's order, and counts the
|
|
6298
6531
|
rest. The headline counts the real totals. `resumeSummaryFact` is the
|
|
6299
|
-
summary's decoder at a boundary
|
|
6300
|
-
|
|
6301
|
-
the clients' own words.
|
|
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).
|
|
6302
6534
|
|
|
6303
6535
|
### Launch configurations
|
|
6304
6536
|
|
|
@@ -256,8 +256,7 @@ stops trying for one that keeps losing its session, is the kernel's rule,
|
|
|
256
256
|
written beside the command. A session lost long ago is not resumed
|
|
257
257
|
automatically, and Desktop says nothing about it; `oats session start
|
|
258
258
|
--resume` still brings it back by hand. Desktop owns no session: it runs the
|
|
259
|
-
command
|
|
260
|
-
it off.
|
|
259
|
+
command and shows nothing of its answer. There is no switch to turn it off.
|
|
261
260
|
|
|
262
261
|
**When it runs.** Once when Desktop opens, after Desktop has imported its
|
|
263
262
|
saved workspaces into this computer's deployments list, because the sweep
|
|
@@ -282,44 +281,16 @@ the kernel's machine lock and its record of this boot make running it from
|
|
|
282
281
|
several clients safe. It runs only when the installed OATS CLI advertises the
|
|
283
282
|
`session-resume` feature. Without it, nothing runs and nothing is said.
|
|
284
283
|
|
|
285
|
-
**
|
|
286
|
-
waiting for you or could not resume
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
choose how to resume it: open its terminal), those that could not be resumed,
|
|
292
|
-
those that started fresh and why, then those resumed in their own
|
|
293
|
-
conversation. An instance that keeps losing its session is listed with those
|
|
294
|
-
that could not be resumed: the kernel stops resuming it, and it stays down
|
|
295
|
-
until you start it yourself. The deployments the sweep did not check are
|
|
296
|
-
listed after them. Text from OATS appears only after "OATS says:", as a quote.
|
|
297
|
-
The Details show at most 100 instances, then say how many more there are.
|
|
298
|
-
|
|
299
|
-
Each sweep with something to report gives a notice of its own. An instance
|
|
300
|
-
that could not be resumed is reported once: a later sweep that finds it the
|
|
301
|
-
same way leaves it out, and says nothing if that was all it found. Once it has
|
|
302
|
-
been resumed, or shown running or no longer lost, a later refusal is reported
|
|
303
|
-
again. More than three notices fold into one entry, "N notices about resumed
|
|
304
|
-
sessions". Desktop keeps the last 10 notices no window has shown yet, so a
|
|
305
|
-
window that opens after a sweep has finished still gets them, and only one
|
|
306
|
-
window ever shows each. Closing that window loses it.
|
|
307
|
-
|
|
308
|
-
OATS can also warn about this computer rather than one instance (how the
|
|
309
|
-
sessions it resumes are run on this machine, say). Such a warning is shown
|
|
310
|
-
once each time Desktop runs, in the next notice, after the deployments, under
|
|
311
|
-
"OATS says about this computer:". A warning alone never makes a notice.
|
|
312
|
-
|
|
313
|
-
There is no notice when nothing was lost, when the sessions were already
|
|
314
|
-
running, when another sweep holds the machine (another Desktop, the TUI, or
|
|
315
|
-
`oats session resume` run by hand), or when the only thing to report is a
|
|
316
|
-
deployment that was not checked. A sweep that fails writes one line with its
|
|
317
|
-
code to Desktop's log, and shows nothing.
|
|
284
|
+
**Nothing is shown.** Desktop says nothing about a sweep: no notice, whatever
|
|
285
|
+
it resumed, started fresh, left waiting for you or could not resume (the
|
|
286
|
+
product owner, 2026-10-27). A resumed instance shows running in the roster
|
|
287
|
+
once a read sees it running. A sweep that fails writes one line with its code
|
|
288
|
+
to Desktop's log. `oats tui` says nothing about a sweep either
|
|
289
|
+
([Resuming lost sessions](tui.md#resuming-lost-sessions)).
|
|
318
290
|
|
|
319
291
|
**Quitting does not stop a sweep.** The sweep runs in a process session of its
|
|
320
292
|
own, and writes its answer to files rather than to Desktop. Quitting Desktop,
|
|
321
|
-
or Desktop crashing, while it runs leaves it to finish.
|
|
322
|
-
not shown.
|
|
293
|
+
or Desktop crashing, while it runs leaves it to finish.
|
|
323
294
|
|
|
324
295
|
How the clients run the command and read its answer is in
|
|
325
296
|
[desktop-cli-api.md](desktop-cli-api.md#how-the-clients-run-the-sweep).
|