@awebai/oats 0.69.1 → 0.69.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +273 -66
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +4 -4
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/release-notes/v0.69.3.md +43 -0
  17. package/docs/servers.md +7 -2
  18. package/docs/soul.schema.json +1 -0
  19. package/docs/souls-and-instances.md +35 -2
  20. package/docs/tui.md +112 -15
  21. package/docs/upgrading.md +9 -5
  22. package/docs/workspaces.md +2 -2
  23. package/injects/instance-boundary.md +19 -33
  24. package/injects/work-attached.md +8 -13
  25. package/injects/work-checkout.md +16 -30
  26. package/injects/work-directory.md +9 -15
  27. package/injects/work-workspace.md +8 -19
  28. package/injects/work-worktree.md +18 -33
  29. package/lib/capability-contract.mjs +2 -2
  30. package/lib/core.mjs +162 -49
  31. package/lib/instance-background.mjs +54 -0
  32. package/lib/instance-inspect.mjs +3 -0
  33. package/lib/instance-lifecycle.mjs +35 -0
  34. package/lib/instance-resolution.mjs +3 -2
  35. package/lib/instance-same-work.mjs +67 -0
  36. package/lib/instance-upgrade.mjs +18 -0
  37. package/lib/materialize.mjs +23 -2
  38. package/lib/resolve.mjs +32 -5
  39. package/lib/servers.mjs +19 -4
  40. package/lib/session-resume-contract.mjs +1 -0
  41. package/lib/session-resume.mjs +36 -9
  42. package/lib/soul-composition.mjs +13 -10
  43. package/lib/workspace.mjs +3 -2
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +30 -8
  47. package/packages/client/deployment-data.mjs +9 -0
  48. package/packages/client/deployment-panel.mjs +4 -0
  49. package/packages/client/instance-tree.mjs +64 -14
  50. package/packages/client/launch-prompt-outcome.mjs +1 -1
  51. package/packages/client/panel-views.mjs +11 -3
  52. package/packages/client/remote-roster.mjs +5 -1
  53. package/packages/client/roster-sections.mjs +50 -6
  54. package/packages/client/same-work.mjs +49 -0
  55. package/packages/client/session-resume-trigger.mjs +15 -37
  56. package/packages/client/session-resume.mjs +22 -259
  57. package/packages/client/soul-rows.mjs +2 -0
  58. package/packages/client/spawn-apply-contract.mjs +2 -1
  59. package/packages/client/spawn-decision.mjs +4 -1
  60. package/packages/client/spawn-preview-contract.mjs +12 -1
  61. package/packages/client/spawn-preview.mjs +2 -0
  62. package/packages/tui/README.md +2 -2
  63. package/packages/tui/lib/client.mjs +6 -2
  64. package/packages/tui/lib/main.mjs +44 -11
  65. package/packages/tui/lib/model.mjs +101 -43
  66. package/packages/tui/lib/panel.mjs +23 -13
  67. package/packages/tui/lib/store.mjs +76 -20
  68. package/packages/tui/lib/views/frame.mjs +2 -0
  69. package/packages/tui/lib/views/help.mjs +2 -0
  70. package/packages/tui/lib/views/instances.mjs +38 -1
  71. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -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 — the kernel blocks, then each capability's inject,
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`, and (feature
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`. `revision` (24 hex) hashes the
2675
- decision.
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
- This table covers those three commands; the upgrade pairs follow separately.
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
- Upgrade requires a stopped session. Start and restart do not take or read the
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"` or `"upgrade"`. A claim written
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 or oats instance upgrade holds it, then retry`.
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 or oats instance upgrade holds it, then retry` (0.52.0, #874; before,
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 start lock before
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`: it stopped or started between the read and the start) |
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: `not-seen-recently`,
6139
- `refused-this-boot`, `keeps-getting-lost`, then its start. A sweep that is
6140
- not a plan answers each lost home once: a later sweep answers that loss
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`
@@ -6206,7 +6438,7 @@ TUI decide, run and read it the same way.
6206
6438
  `lostLocalHomes` keeps a local row's absolute `home` when its `sessionEnd`
6207
6439
  says the session was lost and it is not running; it is the one place that
6208
6440
  reads `sessionEnd`'s meaning. There is no timer and no queue.
6209
- - After a sweep that a status read started completes (quiet or a notice),
6441
+ - After a sweep that a status read started completes (it reads `answered`),
6210
6442
  every instance it was started for waits until it changes: it runs, or it is
6211
6443
  no longer lost. A busy, failed or unsupported sweep, or a plan, settles
6212
6444
  nothing. A home a read releases while the sweep runs is settled by neither
@@ -6221,23 +6453,16 @@ TUI decide, run and read it the same way.
6221
6453
  - `cli()` gives the accepted probe or null, or a promise of either, and is
6222
6454
  asked at each would-be start: the sweep runs only when `resumeSupported`
6223
6455
  holds. When it does not, nothing runs and the floor does not move.
6224
- - Before reading an answer, it drops each `refused` row whose
6225
- `(home, reason, code)` an earlier sweep of this trigger already reported,
6226
- so a standing refusal is reported once. A home released (above) forgets its
6227
- reported refusals: refused again after it recovered, it is news. Every other
6228
- row is kept. The same goes for the result's own `warnings` (about the host):
6229
- one a notice of this trigger showed is left out of later answers by its
6230
- exact string, for the whole run; one only a quiet sweep carried stays news.
6231
- - `onReading(reading)` is called for every finished sweep, whatever the
6232
- reading. `launch()` and `observed()` never throw or reject; a `run` that
6456
+ - `read` is given the run's envelope itself, and `onReading(reading)` is
6457
+ called for every finished sweep, whatever the reading. `launch()` and `observed()` never throw or reject; a `run` that
6233
6458
  rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
6234
6459
  and cancels nothing: a sweep in flight runs to its end.
6235
6460
 
6236
- The Desktop's main process queues each `notice` reading's summary (at most
6237
- 10, the oldest dropped first) and tells every live window
6238
- (`session-resume:ready`). A window takes the whole queue
6239
- (`session-resume:take`, behind the trusted-frame guard) and posts each summary
6240
- as its own notice.
6461
+ The Desktop shows nothing of a reading (the product owner, 2026-10-27): its
6462
+ main process writes a `failed` reading's code to its log in one line and drops
6463
+ every other reading. The TUI says nothing of a reading either: an `answered`
6464
+ reading asks it for a live read, and every other reading for nothing
6465
+ ([Resuming lost sessions](tui.md#resuming-lost-sessions)).
6241
6466
 
6242
6467
  **The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
6243
6468
 
@@ -6268,37 +6493,19 @@ as its own notice.
6268
6493
  reaches the answer.
6269
6494
 
6270
6495
  **The reader**, `readResumeSweep` (`packages/client/session-resume.mjs`),
6271
- gives one of five readings: `unsupported` (nothing ran), `busy`
6272
- (`E_RESUME_BUSY`), `failed` with a code, `quiet`, or `notice` with a summary.
6273
- A plan answer (`plan: true`) is quiet.
6274
-
6275
- - The summary is facts: per row its instance, its deployment and its outcome's
6276
- reason, never a word of the kernel's text. `already-running` and `skipped`
6277
- rows are counted nowhere. A notice exists only when a row is `resumed`,
6278
- `fresh`, `blocked` or `refused`. Unchecked deployments are lines inside such
6279
- a notice, never a notice on their own; a deployment the kernel reports as
6280
- `opted-out` (an older kernel) reads as unchecked, with no reason.
6281
- - It is tolerant. A row without a string `instance` and `deployment`, with an
6282
- unknown `outcome`, or whose name the display filter withholds or empties, is
6283
- dropped. An unknown `reason` under a known outcome is read as no reason and
6284
- worded generically. A refusal's `code` is kept only when it matches
6285
- `^E_[A-Z0-9_]{1,64}$`.
6286
- - The result's own `warnings`, about the host and not one home, are the
6287
- summary's `host` (`{warnings, omitted}`, always present), kept and cut as a
6288
- row's are (below). They never make a notice alone; a notice shows them after
6289
- the unchecked deployments, under "OATS says about this computer:".
6290
- - A row's `warnings` are kept whole and in order, each as one display line
6291
- (`displayLine`), and cut by position only, at the bounds of
6292
- `launchFlagIgnored` (16 lines, 4096 UTF-16 units; `boundedWarnings`,
6293
- `packages/client/launch-prompt-outcome.mjs`). No warning is picked, matched
6294
- or dropped by its words.
6295
- - A refused row's `message` is the kernel's prose. It is shown only after
6296
- "OATS says:", attributed, through the display filter, and never matched.
6297
- - The summary keeps at most 100 rows, in the answer's order, and counts the
6298
- rest. The headline counts the real totals. `resumeSummaryFact` is the
6299
- summary's decoder at a boundary (the Desktop's main process hands it to a
6300
- window over IPC), and `resumeNotice` writes the headline and the Details in
6301
- the clients' own words.
6496
+ gives one of four readings: `unsupported` (`E_CLI_UNAVAILABLE` or
6497
+ `E_RESUME_FEATURE`: nothing ran), `busy` (`E_RESUME_BUSY`), `failed` with a
6498
+ code, or `answered`. A reading carries nothing of the answer's rows or words.
6499
+
6500
+ - `answered` is every `ok: true` answer whose result is the sweep's document,
6501
+ a plan (`plan: true`) included. A plan started nothing, so it completes
6502
+ nothing: its snapshot and its rows settle no home (`sweepCompleted`,
6503
+ `sweepSettlement`).
6504
+ - `failed` carries the refusal's code when it matches `^E_[A-Z0-9_]{1,64}$`,
6505
+ else `E_CLI_PROTOCOL`. An `ok: true` answer that is not the document (no
6506
+ `schemaVersion` 1, `plan` not a boolean, `deployments` or `rows` not an
6507
+ array, or either longer than 100 000 entries) is a protocol failure,
6508
+ `E_CLI_PROTOCOL`, and is never read in part.
6302
6509
 
6303
6510
  ### Launch configurations
6304
6511
 
@@ -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, waits for the answer and shows a summary. There is no switch to turn
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
- **The notice.** When a sweep resumed an instance, started one fresh, left one
286
- waiting for you or could not resume one, one window shows a notice that stays
287
- until you dismiss it. Switching that window's workspace does not take it away.
288
- The headline counts them ("OATS resumed 3 instances whose sessions were lost.
289
- 1 of them is waiting for you: open its terminal."). Its Details list each
290
- instance, in this order: those waiting for you (at a launch prompt, or to
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. Its answer is then
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).