@awebai/oats 0.68.1 → 0.69.2

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