@awebai/oats 0.68.1 → 0.69.1

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 (67) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +108 -10
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.69.0.md +658 -0
  15. package/docs/release-notes/v0.69.1.md +25 -0
  16. package/docs/servers.md +44 -5
  17. package/docs/souls-and-instances.md +11 -7
  18. package/docs/tui.md +77 -12
  19. package/docs/upgrading.md +12 -7
  20. package/docs/workspaces.md +1 -1
  21. package/lib/core.mjs +345 -89
  22. package/lib/file-pieces.mjs +49 -0
  23. package/lib/instance-events.mjs +25 -4
  24. package/lib/launch-prompt-fixtures/README.md +62 -0
  25. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  26. package/lib/launch-prompt-fixtures.mjs +49 -0
  27. package/lib/launch-prompt-resume.mjs +55 -0
  28. package/lib/login-environment.mjs +27 -9
  29. package/lib/schedule.mjs +3 -3
  30. package/lib/servers.mjs +117 -23
  31. package/lib/session-end.mjs +82 -0
  32. package/lib/session-input.mjs +43 -9
  33. package/lib/session-resume-contract.mjs +32 -0
  34. package/lib/session-resume.mjs +310 -0
  35. package/lib/session-seen.mjs +163 -0
  36. package/lib/session-viewer.mjs +147 -44
  37. package/lib/soul-composition.mjs +2 -1
  38. package/lib/start-env.mjs +110 -0
  39. package/lib/tmux-server-scope.mjs +139 -14
  40. package/lib/workspace.mjs +38 -4
  41. package/package-catalog.json +10 -4
  42. package/package.json +1 -1
  43. package/packages/client/cli-adapter.mjs +9 -0
  44. package/packages/client/cli-locator.mjs +3 -2
  45. package/packages/client/deployment-data.mjs +7 -0
  46. package/packages/client/deployment-panel.mjs +3 -0
  47. package/packages/client/file-output-exec.mjs +98 -0
  48. package/packages/client/launch-prompt-outcome.mjs +25 -13
  49. package/packages/client/own-codes.mjs +2 -0
  50. package/packages/client/session-attach.mjs +35 -5
  51. package/packages/client/session-resume-cli.mjs +64 -0
  52. package/packages/client/session-resume-trigger.mjs +167 -0
  53. package/packages/client/session-resume.mjs +332 -0
  54. package/packages/client/tmux-status.mjs +30 -7
  55. package/packages/client/waiting-on-you.mjs +11 -4
  56. package/packages/client/workspace-step.mjs +17 -5
  57. package/packages/record/lib/last-conversation.mjs +123 -0
  58. package/packages/record/lib/session-roots.mjs +10 -1
  59. package/packages/tui/lib/client.mjs +1 -1
  60. package/packages/tui/lib/main.mjs +5 -3
  61. package/packages/tui/lib/model.mjs +45 -12
  62. package/packages/tui/lib/store.mjs +8 -7
  63. package/packages/tui/lib/term/text.mjs +12 -9
  64. package/packages/tui/lib/views/frame.mjs +72 -7
  65. package/packages/tui/lib/views/help.mjs +8 -3
  66. package/packages/tui/lib/views/instances.mjs +3 -2
  67. 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 | |
@@ -143,6 +153,7 @@ see the [official catalog](official-catalog.md) for current pins.
143
153
  | `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
154
  | `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
155
  | `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 | |
156
+ | `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
157
 
147
158
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
148
159
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -2453,6 +2464,10 @@ it to a temporary copy (`soulFetched: true`).
2453
2464
  otherwise. Show it, and `yolo`, whenever it is `true`. An explicit
2454
2465
  `--launch-config none` asks for the bare harness and bypasses the default;
2455
2466
  to run the host's default, omit `--launch-config`.
2467
+ - `launchConfigSource` (0.69) is the directory of the file that declares
2468
+ `launchConfig`: the deployment, or `~/.oats/config` for
2469
+ [this machine's launch configurations](configuration.md#this-machines-launch-configurations);
2470
+ `null` when there is no `launchConfig`. A spawn records the same value.
2456
2471
  - `modelSource` is `"explicit"`, `"soul default"`, `"launch-config <name>"`,
2457
2472
  `"native default"` or `"native default (explicit)"` (`--model
2458
2473
  @native-default`). Omitting `--model` and asking for the native default are
@@ -3231,8 +3246,12 @@ its absence.
3231
3246
  "shell"`, even though the window remains; a dead pane or absent window is
3232
3247
  `false`. A wrapper shell with a live non-shell descendant stays `true`;
3233
3248
  `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
3249
+ `runtimeError` when that server or its panes cannot be read (including a
3250
+ window where OATS cannot tell which pane is the agent's
3251
+ ([which pane is the agent's](execution-targets.md#which-pane-is-the-agents)),
3252
+ a session with two windows of the instance's name, or a failed
3253
+ shell-descendant process scan; a window whose agent's pane is found reads by
3254
+ that pane alone), and also when its socket
3236
3255
  file is missing while a process works in the home or the process scan
3237
3256
  cannot run, `runtimeError` then naming the processes or the scan's error
3238
3257
  ([#624](execution-targets.md#missing-socket); with no process in the home
@@ -3283,6 +3302,31 @@ its absence.
3283
3302
  An older kernel's `running` is the window's presence, and it checks a row
3284
3303
  with a claim against its session (as `oats session inspect` observes it),
3285
3304
  reading `null` unless a harness runs there.
3305
+ - <a id="row-session-end"></a>**`sessionEnd`** (feature `session-resume`, OATS
3306
+ 0.69): how the last session of a launched home that does not run ended:
3307
+ `lost` (the host went down, its tmux server died, or the harness was killed
3308
+ by a signal: the sweep brings it back when it can vouch for the loss,
3309
+ [Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
3310
+ `oats instance stop`, Desktop's Stop) or `exited` (the harness ended by
3311
+ itself: `/exit`, its own error). Present only on a row that reads
3312
+ `running: false` and records `launched: true`, a row at its fallback shell
3313
+ (`runtimeState: "shell"`) included; absent while it runs or reads unknown
3314
+ (`running: null`), for a home never launched, on rows with `retirePending`,
3315
+ `rollbackIncomplete` or `spawnInProgress`, and from older kernels. Read
3316
+ from the home's current start (`startId`; its time is the last
3317
+ `restarts[].startedAt`, else `createdAt`) and two kernel-private files of
3318
+ the home, not a contract ([execution-targets.md](execution-targets.md#how-a-sessions-end-is-read)).
3319
+ A home spawned before 0.69 and never restarted since reads `lost` when its
3320
+ harness ended on its own; its next start covers it.
3321
+ - **A local status read records what it sees** (feature `session-resume`,
3322
+ OATS 0.69): per home, its current start, when it was last seen running and
3323
+ first seen not running, with the boot of each, in a kernel-private file of
3324
+ this machine, one per deployment, under `~/.oats/session-resume/seen/`
3325
+ (`$OATS_HOME_DIR` when set), beside the sweep's per-boot note; it is not a
3326
+ contract, and only the sweep reads it. It never changes the answer: not the
3327
+ output, not the exit status, and nothing is printed, whether or not it can
3328
+ be read or written. A status routed with `--server` records nothing on this
3329
+ machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
3286
3330
  - **`color`** (feature `instance-color`): the instance's colour, one of
3287
3331
  `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3288
3332
  from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
@@ -3357,6 +3401,10 @@ its absence.
3357
3401
  relays a host's features from the status answer it already pulls. It is
3358
3402
  emitted at output time, never part of a reused observation. A kernel
3359
3403
  before 0.49.0 omits it.
3404
+ - **`sessionViewer`** (feature `session-attach-prefix-scroll`): this host's
3405
+ `{prefixScroll}`, as `version --json` answers it, read afresh at each
3406
+ run and never part of a reused observation, so a roster relays it from
3407
+ the status answer it already pulls.
3360
3408
  - `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
3361
3409
  `warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
3362
3410
 
@@ -3436,7 +3484,7 @@ route target:
3436
3484
  ```json
3437
3485
  {"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
3438
3486
  "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",
3487
+ "probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"],"sessionViewer":{"prefixScroll":true}},"agentsRoot":"/srv/team/agents",
3440
3488
  "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
3489
  "teams":{"default":"acme:team"},"teamsFrom":"observed"},
3442
3490
  "souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
@@ -3454,9 +3502,10 @@ route target:
3454
3502
  "retireFailures":[]}
3455
3503
  ```
3456
3504
 
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.
3505
+ - **`probe`**: `{ok: true, features, sessionViewer}` when the host's
3506
+ `status --json` was pulled, else `{ok: false, error: {code, message}}`
3507
+ (ssh failed or timed out, `E_SSH`; or the host answered `ok: false`),
3508
+ with no `features` and no `sessionViewer` key.
3460
3509
  Every group is probed at once, each within its own deadline, so a group's
3461
3510
  `probe` depends only on its own host: one that does not answer in time is
3462
3511
  `E_SSH` with `ssh to <host> timed out: no answer within <n> s`, and every
@@ -3475,6 +3524,13 @@ route target:
3475
3524
  its version. Read it as `Array.isArray(probe?.features)`: not an array
3476
3525
  means unknown; `[]` is a valid answer (a host with no features), not
3477
3526
  unknown.
3527
+ - **`probe.sessionViewer`** (feature `session-attach-prefix-scroll`): the
3528
+ host's `{prefixScroll}`, relayed from the `sessionViewer` of its
3529
+ [`status --json`](#the-roster-oats-status---json), never probed. It is
3530
+ relayed as a copy of `{prefixScroll}` only when that is a boolean;
3531
+ anything else, or a host whose kernel predates the field, is `null`.
3532
+ Read it only for a host whose `probe.features` lists
3533
+ `session-attach-prefix-scroll`.
3478
3534
  - **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
3479
3535
  own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
3480
3536
  relayed verbatim, or `null` when the host reports none (a deployment
@@ -3696,7 +3752,9 @@ An envelope, `ok: true` whenever no step failed, human steps included
3696
3752
  - `registration` is the registration as written or found (`sshHost`,
3697
3753
  `workspace`: the absolute path the host resolved for `--dir`, never `~`;
3698
3754
  `workspaceKey`; and `oatsPath`, `path`,
3699
- `label` when set), `null` until the `register` step has run.
3755
+ `label` when set, given or, without `--path`, read from the host user's
3756
+ [login shell](servers.md#the-hosts-login-shell-path)), `null` until the
3757
+ `register` step has run.
3700
3758
  - `human` lists the remedies of the `needs-human` steps, in order. A
3701
3759
  `readiness` step that needs a human has one line per problem
3702
3760
  (`<souls>: <subject>: <reason>[ → <remedy>]`, plus `readiness not checked
@@ -4012,7 +4070,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
4012
4070
  message}` per producer with a live claim in the current incarnation
4013
4071
  (cleared ones included). A producer's latest row with `data.waitingOnYou`
4014
4072
  decides. `waitingOnYou` is `{since, producer, reason, message}` of the
4015
- newest positive claim, or `null` (unknown, not "not waiting"). See
4073
+ newest positive claim that has a message, so a claim with no text never
4074
+ hides one with text; when its `reason` is `null`, the newest text-less
4075
+ claim's reason fills it. With no message anywhere it is the newest
4076
+ positive claim, or `null` (unknown, not "not waiting"). See
4016
4077
  [Waiting on you](#waiting-on-you) for the producers and the rules.
4017
4078
  - Errors: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
4018
4079
  `E_BAD_ARGS`, `E_EVENTS_FAILED`.
@@ -4063,8 +4124,14 @@ oats instance attention [--message <text>] [--clear] --json
4063
4124
  only ever the message, never a flag (`--message=--clear` sets the message
4064
4125
  "--clear"). The spaced form `--message --deploy` reads `--deploy` as a
4065
4126
  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.
4127
+ positive claim. The reader applies the same rule again, with one
4128
+ difference: a stored message over 200 code points (a row from another
4129
+ producer or an older writer, or a remote kernel's claim) is cut to 200, the
4130
+ last one `…`. So `waitingOnYou.message` and each `waitingClaims[].message`
4131
+ are never longer than 200 code points, whoever wrote them. The cut counts
4132
+ code points: a surrogate pair is never split, but a combining mark may be
4133
+ left out. A message that is still invalid after that (a refused character,
4134
+ a hand-edited log) reads as `null`, and the claim still counts.
4068
4135
  A stored `reason` outside `permission`, `question`, `attention` reads as
4069
4136
  `null` too, and a row whose `producer` is neither `kernel` nor a valid
4070
4137
  producer id, or whose `at` is not a date, is no claim at all.
@@ -4475,7 +4542,12 @@ leaves nothing of its own in the home: the private file each of the two
4475
4542
  writes goes through (`.oats-stop.json.tmp-<pid>`,
4476
4543
  `.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
4477
4544
  rename fails. Before 0.53.0 each apply on a full disk left both there,
4478
- empty.
4545
+ empty. With no record of the stop, the instance then reads
4546
+ [`sessionEnd: "lost"`](#row-session-end), and a resume sweep would start it
4547
+ again: stop it once more when the disk has space (a stop of an instance that
4548
+ reads `lost` records the stop, signalling nothing). The exit marker of the
4549
+ harness's window (0.69) is not the stop's: the window's shell writes it when
4550
+ the harness ends, and on a full disk its write fails too.
4479
4551
 
4480
4552
  In 0.52.0 a stop whose claim could not be written for one of those five
4481
4553
  codes was refused like the others, before anything was signalled
@@ -5861,7 +5933,9 @@ harness receipt. See [execution targets](execution-targets.md).
5861
5933
 
5862
5934
  ```text
5863
5935
  oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
5936
+ oats session start --resume --home <abs> --json
5864
5937
  oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
5938
+ oats session resume [--deployment <dir>] [--plan] --json
5865
5939
  ```
5866
5940
 
5867
5941
  Features `session-start`, `session-restart`, and `launch-config` for the
@@ -5941,6 +6015,152 @@ warning naming the same-key cleanup retry.
5941
6015
  [`details.cause`](#kernel-codes) when it has a code of its own or is a
5942
6016
  defect, and without it when it is a refusal without a code).
5943
6017
 
6018
+ #### Resume a lost session (`--resume`)
6019
+
6020
+ `oats session start --resume --home <abs> --json` (feature `session-resume`,
6021
+ OATS 0.69) is the ordinary start of a home whose session was lost
6022
+ ([`sessionEnd: "lost"`](#row-session-end)), in the harness's own last
6023
+ conversation: the same locks, checks, recorded recipe and launch hooks under
6024
+ the captured settings, with the conversation's selector and the resume
6025
+ notice in place of the task prompt
6026
+ ([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). Its
6027
+ answer is the ordinary start answer plus one object:
6028
+
6029
+ ```json
6030
+ "resume": {
6031
+ "resumed": true,
6032
+ "reason": "no-conversation",
6033
+ "harness": "claude",
6034
+ "sessionId": "<the harness's session id>",
6035
+ "waiting": "resume-confirmation"
6036
+ }
6037
+ ```
6038
+
6039
+ - `resumed: true` with `sessionId` when it continues that conversation;
6040
+ `resumed: false` with `reason` when it started fresh on `TASK.md` instead:
6041
+ `no-conversation` (no transcript of this incarnation whose cwd is the
6042
+ home), `no-receipts` (no native-record receipt of this incarnation names
6043
+ where the harness writes), `resume-unproven` (Codex, until a resume of it
6044
+ is proven end to end on a signed-in host).
6045
+ - `waiting: "resume-confirmation"`: the start **succeeded** (exit 0, the
6046
+ session runs and is kept) and Claude is waiting for its human to choose how
6047
+ to resume a long conversation (its resume-cost dialog). No key was sent.
6048
+ Absent otherwise, an unrecognised screen after the bound included.
6049
+ - Refused before anything is read, `E_BAD_ARGS`: `--resume` with
6050
+ `--launch-config`, `--harness`, `--model`, `--yolo`, `--no-yolo` or
6051
+ `--reselect-launch`; `--resume` on `session restart`; `--server`.
6052
+ - 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.
6055
+ - Refused `E_LAUNCH_ENV_CHANGED` when a `{fromEnv}` value differs from the
6056
+ one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
6057
+ the message names the variables, sorted, never a value; nothing was
6058
+ started. A home with no record of its last start's values (last started
6059
+ by an earlier kernel, or a record that does not read) is resumed, and
6060
+ `warnings` carries once `<instance>'s launch environment could not be
6061
+ verified this once (it was last started before OATS recorded it); its
6062
+ next start records it` ([The launch environment a resume runs
6063
+ under](execution-targets.md#the-launch-environment-a-resume-runs-under)).
6064
+ - Every refusal of an ordinary start answers as it does there
6065
+ (`E_SESSION_RUNNING`, `E_SESSION_START_BUSY`, `E_SESSION_UNKNOWN`,
6066
+ `E_LAUNCH_LEGACY` for a home with no recipe, `E_LAUNCH_ENV_MISSING`, …); a
6067
+ development-channel prompt that stops it is `E_SPAWN_INCOMPLETE` with
6068
+ `details.launchPrompts`, unchanged. A start by hand is neither bounded
6069
+ nor counted by the sweep's 3 resumes per home per boot.
6070
+ - What is persisted is the ordinary launch: `instance.json` `command`, the
6071
+ pending receipt and the recipe never carry the selector or the notice, so a
6072
+ later ordinary start opens a fresh conversation.
6073
+
6074
+ ### The machine sweep (`oats session resume`)
6075
+
6076
+ `oats session resume [--deployment <dir>] [--plan] --json` (feature
6077
+ `session-resume`, OATS 0.69) starts with `--resume` every home of this
6078
+ machine's deployments whose session was lost. A client runs it once when it
6079
+ opens. It reads this computer's list of deployments without writing it
6080
+ ([This computer's deployments](#this-computers-deployments-oats-deployments)),
6081
+ and never sweeps one `oats deployments remove` took out;
6082
+ `--deployment <dir>` sweeps that one directory instead, listed or not. Each
6083
+ home starts as a child process of the kernel, in its own deployment's scope,
6084
+ at most 4 at once.
6085
+
6086
+ The answer is the standard envelope, exit 0 whenever the sweep ran,
6087
+ whatever the rows say:
6088
+
6089
+ ```json
6090
+ {"schemaVersion":1,"ok":true,"result":{
6091
+ "schemaVersion": 1,
6092
+ "plan": false,
6093
+ "deployments": [
6094
+ { "deployment": "/abs/dep", "state": "ok", "swept": true },
6095
+ { "deployment": "/abs/gone", "state": "missing", "swept": false, "reason": "not-ok" }
6096
+ ],
6097
+ "rows": [
6098
+ { "deployment": "/abs/dep", "instance": "x", "home": "/abs/dep/agents/s/instances/x", "outcome": "resumed", "sessionId": "…" },
6099
+ { "deployment": "/abs/dep", "instance": "y", "home": "…", "outcome": "fresh", "reason": "no-conversation" },
6100
+ { "deployment": "/abs/dep", "instance": "z", "home": "…", "outcome": "already-running" }
6101
+ ]}}
6102
+ ```
6103
+
6104
+ - **`deployments[]`**: one entry per deployment considered, sorted by path.
6105
+ `state` is the list's state of it (`ok`, `missing`, `not-a-deployment`,
6106
+ `unreadable`). `swept: false` has a `reason`: `not-ok` (its state is not
6107
+ `ok`) or `unreadable` (its status could not be read; `code` and `message`
6108
+ then). Nothing opts a deployment out: stopping an instance with OATS is
6109
+ the only way to keep it down.
6110
+ - **`rows[]`**: one row per home that is lost (whatever its outcome),
6111
+ running (`already-running`) or unknown (`skipped`, `unknown`); stopped,
6112
+ exited and never-launched homes are not listed. Fields: `deployment`,
6113
+ `instance`, `home`, `outcome`, and only when they apply `reason`, `code`,
6114
+ `message`, `launchPrompts`, `sessionId` (resumed) and `warnings` (the
6115
+ start's warnings verbatim, an array of strings, present only when not
6116
+ empty: a client lists `channel-cache-unchecked` from here), without the
6117
+ host-wide ones the sweep's own `warnings` carries.
6118
+
6119
+ | `outcome` | `reason` |
6120
+ |---|---|
6121
+ | `resumed` | none |
6122
+ | `fresh` | `no-conversation`, `no-receipts`, `resume-unproven` |
6123
+ | `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) |
6125
+ | `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
+ | `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
+
6128
+ The kernel defines every `sessionEnd`, `resume` and row name in one
6129
+ module, `lib/session-resume-contract.mjs`; a change to one is a contract
6130
+ change ([#1567](https://github.com/awebai/oats/issues/1567)).
6131
+
6132
+ - **`warnings`**, beside `rows`, present only when there is one: an array
6133
+ of distinct strings, each a warning the sweep's starts said of the host
6134
+ rather than of their home, once whatever the number of starts that said
6135
+ it, verbatim. Today that is only the agent-scope warning (the harness
6136
+ runs in the OATS tmux server's cgroup, not a scope of its own, and why).
6137
+ 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`.
6142
+ - `--plan`: the same shape with `"plan": true`; nothing is started, no lock
6143
+ taken, no note written, no loss answered (its own status read records what
6144
+ it sees, as any local status read does). A lost home's outcome is the prediction: `resumed`
6145
+ (with `sessionId`) or `fresh` with its reason (and the launch-environment
6146
+ warning a start would give), `refused` for a noted refusal, a home sweeps
6147
+ started 3 times in this boot, a home with no recipe, or a launch reference
6148
+ the start would refuse (`E_LAUNCH_ENV_MISSING`, `E_LAUNCH_ENV_CHANGED`,
6149
+ from the sweep's environment). Clients should not call `--plan` on open.
6150
+ - **One sweep per machine.** A second sweep while one runs answers
6151
+ `E_RESUME_BUSY` through the standard failure envelope
6152
+ (`{"schemaVersion":1,"ok":false,"error":{"code":"E_RESUME_BUSY","message":"…"}}`,
6153
+ exit 1); nothing was started, and a client shows no notice. The lock and
6154
+ the per-boot note (refusals, and each home's count of sweep starts that
6155
+ launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
6156
+ not a contract. Without a boot id (neither Linux nor macOS) nothing is
6157
+ noted or counted.
6158
+ - Errors: `E_RESUME_BUSY`; `E_BAD_ARGS` (`--deployment` that is not a
6159
+ deployment directory, `--server`, an unknown flag or an argument); without
6160
+ `--deployment`, the list's own errors (`E_DEPLOYMENTS_INVALID`,
6161
+ `E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
6162
+ sweep's failure.
6163
+
5944
6164
  ### Upload
5945
6165
 
5946
6166
  ```text
@@ -5957,6 +6177,129 @@ stored file); a remote upload adds `server`, `instance` and `stderr?`. Errors:
5957
6177
  sha256 mismatch; the remote file is left), `E_SESSION_UNKNOWN`,
5958
6178
  `E_REMOTE_INCOMPATIBLE`.
5959
6179
 
6180
+ ### How the clients run the sweep
6181
+
6182
+ The kernel's machine sweep, `oats session resume --json`
6183
+ ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), is
6184
+ run by a client when it opens and again when its rosters show a lost session
6185
+ ([When Desktop opens](desktop-instance-start.md#when-desktop-opens)). The
6186
+ clients share one trigger, one runner and one reader, so the Desktop and the
6187
+ TUI decide, run and read it the same way.
6188
+
6189
+ **The trigger**, `createResumeTrigger({ cli, run, read, now, onReading })`
6190
+ (`packages/client/session-resume-trigger.mjs`), holds the rule:
6191
+
6192
+ - `launch()` arms it and runs the launch sweep, with no floor. A client calls
6193
+ it once, after anything the sweep reads is in place (the Desktop: after the
6194
+ startup deployments-list step). `observed()` does nothing before it.
6195
+ - `observed(rows, { localDeploymentIds })` is given each roster's instance
6196
+ rows as the client reads them, with the ids of that read's local
6197
+ deployments (the Desktop: `instances` of each accepted `/api/panel` reply,
6198
+ and `localDeploymentIds(reply)`, its `deployments[]` entries with
6199
+ `local: true`). It starts a sweep only when none is in flight, at least
6200
+ `RESUME_MIN_INTERVAL_MS` (30 s) has passed since the last sweep that ran
6201
+ started, and `lostLocalHomes(rows, localDeploymentIds)` names a home that
6202
+ is not settled. Locality is the roster's, by deployment id: a row is local
6203
+ only when its `deployment.id` (the panel's tag) is one of the local ids. A
6204
+ remote deployment's row, a row with no tag, and every row when no ids are
6205
+ given are not local; a client never acts on another host's loss.
6206
+ `lostLocalHomes` keeps a local row's absolute `home` when its `sessionEnd`
6207
+ says the session was lost and it is not running; it is the one place that
6208
+ 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),
6210
+ every instance it was started for waits until it changes: it runs, or it is
6211
+ no longer lost. A busy, failed or unsupported sweep, or a plan, settles
6212
+ nothing. A home a read releases while the sweep runs is settled by neither
6213
+ the snapshot nor the answer: that read is newer. A home
6214
+ is also settled when a sweep could not resume it, found it was not lost, or
6215
+ skipped it because the kernel had not seen it running recently. A sweep
6216
+ that resumed it, started it fresh, left it waiting for you or found it
6217
+ running unsettles it, and so does a later roster row that is running or not
6218
+ lost. So a home that cannot be resumed costs at most one sweep after the
6219
+ launch's. Which rows mean which is read in `session-resume.mjs` alone
6220
+ (`sweepSettlement`, `sweepCompleted`).
6221
+ - `cli()` gives the accepted probe or null, or a promise of either, and is
6222
+ asked at each would-be start: the sweep runs only when `resumeSupported`
6223
+ 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
6233
+ rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
6234
+ and cancels nothing: a sweep in flight runs to its end.
6235
+
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.
6241
+
6242
+ **The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
6243
+
6244
+ - It runs only when the probe is accepted, its `bin` is absolute and its
6245
+ `features` list `session-resume` (`resumeSupported`). Otherwise it runs
6246
+ nothing and answers `E_CLI_UNAVAILABLE` or `E_RESUME_FEATURE`. Nothing falls
6247
+ back.
6248
+ - The argv is exactly `session resume --json`, with no `--deployment`, no
6249
+ `--plan` and no `--server`. The working directory is `/`, so the kernel
6250
+ resolves no deployment from the client's own. The environment is the
6251
+ client's, without what Desktop's packaging adds (`cliEnvironment`) and without
6252
+ the instance variables (`withoutInstanceVariables`,
6253
+ `packages/client/kernel-environment.mjs`): a client started inside an
6254
+ instance's pane must not scope the sweep to that instance. `OATS_HOME_DIR`
6255
+ passes through.
6256
+ - It sets no deadline. The sweep runs in a process session of its own, and its
6257
+ stdout and stderr are files, not pipes: `execFileToFiles`
6258
+ (`packages/client/file-output-exec.mjs`) unlinks them right after the spawn
6259
+ and reads them back from its own descriptors. Neither the client's exit nor
6260
+ a signal to it reaches the sweep, and nothing is left on disk. A caller that
6261
+ passes its own exec must keep those three properties: detached, file-backed,
6262
+ and never signalling the child.
6263
+ - It answers the kernel's envelope: the result at exit 0, and an `ok:false`
6264
+ envelope whatever the exit (`E_RESUME_BUSY` exits 1). Otherwise it answers
6265
+ a code of its own, with no message: `E_CLI_OUTPUT_LIMIT` (more than 4 MiB),
6266
+ `E_CLI_PROTOCOL` (no envelope), `E_CLI_FAILED` (a nonzero exit without an
6267
+ `ok:false` envelope, or an exec that throws). No stderr and no exception text
6268
+ reaches the answer.
6269
+
6270
+ **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.
6302
+
5960
6303
  ### Launch configurations
5961
6304
 
5962
6305
  ```text
@@ -43,9 +43,12 @@ entry, or falls back to the recorded launch when it is no longer offered.
43
43
 
44
44
  Enter a model or leave the field blank to use the selected launch's default.
45
45
  An old harness's model is not carried to a different harness. Available local model
46
- suggestions are advisory; a model ID can also be typed. Start uses the saved
47
- briefing and state in a new harness conversation; it does not resume an old
48
- harness conversation ID. Once the kernel accepts the start or restart, the
46
+ suggestions are advisory; a model ID can also be typed. Start opens a fresh
47
+ harness conversation on the saved briefing and state. The one exception is a
48
+ resume after a shutdown, a reboot or a crash, which continues the instance's
49
+ own last conversation ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown));
50
+ it replaces the earlier rule that no start resumes a conversation (OATS 0.69).
51
+ A Start or Restart from this dialog is never a resume. Once the kernel accepts the start or restart, the
49
52
  dialog closes and Desktop opens the instance's terminal as soon as its row is
50
53
  running with a terminal session, so whatever the harness shows first (a
51
54
  confirmation such as Claude Code's development-channels prompt, an error, the
@@ -238,3 +241,85 @@ child remains running; a fallback shell or dead pane is stopped. Errors that
238
241
  prevent a reliable observation remain unknown. A row that records a Herdr
239
242
  target (Herdr was removed in 0.31.0) is never observed: it shows the kernel's
240
243
  `E_HERDR_REMOVED` text, and Open and Start are disabled.
244
+
245
+ ## When Desktop opens
246
+
247
+ After a shutdown, a reboot or a crash, the instances that were running have
248
+ lost their sessions. OATS Desktop asks the kernel to resume them: it runs
249
+ `oats session resume --json`
250
+ ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), and
251
+ the kernel does the rest. The kernel looks
252
+ at every deployment on this computer's list (local deployments only, never a
253
+ server's) and resumes each lost session as it decides. What the kernel does to
254
+ a session, when it starts one fresh from its briefing instead, and when it
255
+ stops trying for one that keeps losing its session, is the kernel's rule,
256
+ written beside the command. A session lost long ago is not resumed
257
+ automatically, and Desktop says nothing about it; `oats session start
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.
261
+
262
+ **When it runs.** Once when Desktop opens, after Desktop has imported its
263
+ saved workspaces into this computer's deployments list, because the sweep
264
+ reads that list. After that, whenever Desktop reads a roster that shows an
265
+ instance of a local deployment, as the roster names its deployments, whose
266
+ session was lost and that is not running, and only then:
267
+
268
+ - at most one sweep at a time, and at least 30 seconds after the last one
269
+ started (the one at launch counts);
270
+ - after a sweep that a status read started, every instance it was started
271
+ for waits until it changes (it runs, or it is no longer lost); so does an
272
+ instance any sweep could not resume, found was not lost, or left because it
273
+ was lost long ago. Such an instance does not set off another sweep until a
274
+ later roster shows it running or no longer lost, or a sweep resumes it;
275
+ - never for another machine's instances.
276
+
277
+ There is no timer and no queue: a read that comes too soon starts nothing,
278
+ and the next read asks again. A new window, a workspace switch, a restarted
279
+ backend or Desktop coming to the front start nothing on their own. The rule
280
+ is shared with the TUI (`packages/client/session-resume-trigger.mjs`), and
281
+ the kernel's machine lock and its record of this boot make running it from
282
+ several clients safe. It runs only when the installed OATS CLI advertises the
283
+ `session-resume` feature. Without it, nothing runs and nothing is said.
284
+
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.
318
+
319
+ **Quitting does not stop a sweep.** The sweep runs in a process session of its
320
+ 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.
323
+
324
+ How the clients run the command and read its answer is in
325
+ [desktop-cli-api.md](desktop-cli-api.md#how-the-clients-run-the-sweep).