@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -66,9 +66,12 @@ see the [official catalog](official-catalog.md) for current pins.
66
66
  with against that kernel's own version, so never finds it above. A
67
67
  `desktopApi` other than 1 is refused (`newerApi` on the candidate when it is
68
68
  a higher one).
69
- - `harnesses` is what `--harness` accepts; `sessionBackends` what `--backend`
70
- accepts: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend herdr`
71
- is refused with `E_HERDR_REMOVED`). A host without the `harness` feature
69
+ - `harnesses` is what `--harness` accepts; `sessionBackends` the kernel's own
70
+ session backends: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend
71
+ herdr` is refused with `E_HERDR_REMOVED`). With the feature
72
+ `session-providers`, `--backend` also takes a session provider's name: a
73
+ backend a capability supplies, never listed here
74
+ ([Session providers](#session-providers-feature-session-providers)). A host without the `harness` feature
72
75
  lists `runtimes` instead.
73
76
  - `remote` is the routed surface: the commands `--server <id>` sends to a
74
77
  registered server, plus `roster`. The Desktop checks the execution host's
@@ -189,6 +192,7 @@ see the [official catalog](official-catalog.md) for current pins.
189
192
  | `schedule-host-register-only` | `oats schedule host install --register-only`: the scope is recorded in the host schedule registry and no timer is installed ([`oats schedule`](#oats-schedule)). Routed with `--server`, the option is sent only to a host that lists this and `schedule`; otherwise it is refused here with `E_REMOTE_INCOMPATIBLE` before anything is sent, since a host without it ignores the option and installs a timer | |
190
193
  | `instance-board` | the agent's board: `oats instance board set\|unset\|ask\|ask --clear`, run by the agent in its own home; `board` on `oats status --json` instance rows and `oats server roster --json` rows; `oats inspect --home <h> --board` for each fact's history and each question's context; the `oats.board` needs-input claim, reason `attention` ([The agent's board](#the-agents-board-oats-instance-board)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses `oats instance board` (`E_BAD_ARGS`) and its rows have no `board` | `boardApi: 1` |
191
194
  | `spawn-task-stdin` | `oats spawn <soul> --task-file -` reads the task from standard input. A spawn routed with `--server` sends its `--task` or `--task-file` text that way, to the preview and to the apply, to a host that lists this, and not as an argument; a host that does not list it gets the text as an argument, and the answer's `warnings` gains one line that says it was readable in both machines' process lists ([servers.md](servers.md#a-routed-spawns-task)) |
195
+ | `session-providers` | session backends a capability supplies ([Session providers](#session-providers-feature-session-providers)): `--backend <provider>` on `oats spawn` (a schedule's `backend`, a trigger's `spawn.backend`); a provider home's `backend`, `session` and `open` on its status row (the endpoint only on its local inspect, spawn and start answers; nothing of it relayed); `backend: "tmux"` on a tmux home's status row; `sessionProviders` in `oats inspect` and `oats capabilities show`; a provider's readiness in `oats readiness`; `backends` on a capability's `requires` row; the codes `E_BACKEND_UNKNOWN`, `E_BACKEND_AMBIGUOUS`, `E_BACKEND_HARNESS`, `E_BACKEND_LAUNCH_ARG`, `E_BACKEND_NOT_READY`, `E_SESSION_NO_TERMINAL`, `E_SESSION_PROMPT_OPEN`, `E_SESSION_INPUT_QUEUED`; `backend` on the sweep's rows of provider homes; `oats session resume --plan --without-provider-inspect`, which is `oats host run`'s own switch for its shutdown listing, not a client's. A routed `--backend <provider>` is sent only to a host that lists it. |
192
196
 
193
197
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
194
198
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -347,7 +351,7 @@ for `--no-recursive`) is never ignored.
347
351
  | `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
348
352
  | `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
349
353
  | `oats session restart` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server`, `--stop-grace` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json` | `--native-record`, `--resume` | none |
350
- | `oats session resume` | none | `--deployment` | `--plan`, `--json` | `--native-record`, `--server` | none |
354
+ | `oats session resume` | none | `--deployment` | `--plan`, `--without-provider-inspect`, `--json` | `--native-record`, `--server` | none |
351
355
  | `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
352
356
  | `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
353
357
  | `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
@@ -437,6 +441,7 @@ kernel command.
437
441
 
438
442
  | Code | When |
439
443
  |---|---|
444
+ | `E_NODE_UNSUPPORTED` | Node.js is older than 22: before every command, exit 1 with `details: {found: "<process.versions.node>", minimum: "22"}` and message `oats needs Node.js 22 or later; this is Node.js <found>`. With `--json` anywhere in argv, stdout is one failure envelope; otherwise the message is on stderr. This includes the `version --json` probe, whose success shape is not the envelope: on unsupported Node it answers this failure envelope with exit 1. Node 18 and 20 get this refusal; a Node too old to parse the entry can fail with a SyntaxError first |
440
445
  | `E_UNKNOWN_COMMAND` | No kernel command or capability namespace matches; an unknown capability subcommand; a [removed verb](#removed-verbs-and-flags) (`details: {removed, replacement}`) |
441
446
  | `E_CAPABILITY_INACTIVE` | In a home: the namespace's module is not one of the home's recorded capabilities |
442
447
  | `E_CAPABILITY_BLOCKED` | In a home: the manifest claiming the namespace is not a workspace module copy of that home. There is no package trust gate |
@@ -1851,6 +1856,14 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
1851
1856
  empty list read as "no warning". Older kernels answer no such `warnings` key
1852
1857
  (inspect, readiness, show, doctor) and refuse the capability instead.
1853
1858
 
1859
+ `oats doctor --json` reports the Git version and whether it supports partial
1860
+ caches in an existing `information[]` line starting `git-version:` (text:
1861
+ `INFO: git-version: …`). Git before 2.45 uses the whole-tree fallback; this
1862
+ is information, never a warning or a refusal. A failed version probe reports
1863
+ unknown support. A newer Git supports partial caches, but a remote can
1864
+ require whole-tree fetches and an existing whole-tree cache keeps its mode
1865
+ ([Git version failures](workspaces.md#membership-and-trust)).
1866
+
1854
1867
  `oats doctor --json` also lists what retires left behind in `information[]`:
1855
1868
  one `retained-recovery:` and one `retained-worktree:` line per item, after a
1856
1869
  line that gives each kind's total, and at most 50 items per kind
@@ -3222,7 +3235,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
3222
3235
 
3223
3236
  - Always present: `instance, agent, home, work, branch, base ({ref, oid}
3224
3237
  the new branch started at; `null` without one), launched, warnings
3225
- (array), tmux ({session, window, socket?} | null), backend ("tmux"), repo, harness,
3238
+ (array), tmux ({session, window, socket?} | null), backend ("tmux", or a
3239
+ session provider's name with `session: {provider, endpoint}` after it and
3240
+ `tmux: null`, `attach: null`: [Session providers](#session-providers-feature-session-providers)), repo, harness,
3226
3241
  model, parent,
3227
3242
  sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
3228
3243
  launch` (the redacted recipe).
@@ -3885,6 +3900,62 @@ its absence.
3885
3900
  output, not the exit status, and nothing is printed, whether or not it can
3886
3901
  be read or written. A status routed with `--server` records nothing on this
3887
3902
  machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
3903
+ - <a id="row-backend-clients"></a>**How the clients read `backend`** (the
3904
+ Desktop and the TUI, `packages/client`). A row whose `backend` is text that
3905
+ is not empty and not `tmux` runs on a session provider, in no terminal (an
3906
+ empty `backend` names none: the kernel never sends one, and the row reads
3907
+ as one with no `backend`):
3908
+ - Its `running`, `runtimeState` and `runtimeError` are shown as the kernel
3909
+ reports them. No client asks tmux about it: with an older kernel, whose
3910
+ rows a client's own terminal check refines, such a row is never passed
3911
+ to that check.
3912
+ - Its acts are the ones of its state: Restart, Stop and Retire while it
3913
+ runs; Start, Stop and Retire stopped; Stop and Retire when the kernel
3914
+ answers `running: null`.
3915
+ - Open is never offered. The clients say where the agent runs ("Runs in a
3916
+ bb thread; open it in bb.") and, when the row carries `open`
3917
+ (`{label, url}`), show it as a link: the Desktop opens it in the system
3918
+ browser from the row's menu, the TUI prints the url. Only an `http` or
3919
+ `https` url with no credentials in it is shown, and only on a row of
3920
+ this machine: another machine's url is that machine's own loopback. No
3921
+ client attaches, splits or restores a terminal for the row.
3922
+ - Its `waitingOnYou` claim is shown unless the row is stopped
3923
+ (`running: false`): while it runs and when the kernel answers
3924
+ `running: null`, since an agent that waits on a person is idle in its
3925
+ provider. A tmux row's claim still needs `running: true` and no
3926
+ `runtimeState` but `running`. A row whose last read failed, or whose
3927
+ server was not reached, shows none, as for any row.
3928
+ - It counts as running (the Desktop's Home, the counts) on `running: true`
3929
+ alone: its `runtimeState` is the provider's word (`unknown` while it
3930
+ runs), never `running`.
3931
+ - A start's or a restart's answer for it carries the provider's name as
3932
+ `backend`, `session: {provider, endpoint?}` and no terminal `target`
3933
+ (the endpoint on a start on this machine, never on a routed one); the
3934
+ clients open no terminal after it.
3935
+ - Its stop and its retire run from the deployment's directory, never from
3936
+ its home. The retire of such a home is refused while any process works in
3937
+ it, the client's own included: start the Desktop or the TUI outside an
3938
+ agent's home.
3939
+ - The Desktop shows the backend and `session.threadId`, when it is text,
3940
+ as `bb · thread thr_…`. Only a status row of this machine carries the
3941
+ thread id: a row relayed from another host (`oats server roster`,
3942
+ `--server`) never does, so a client shows the backend alone there and
3943
+ depends on the id for nothing. The id addresses nothing.
3944
+
3945
+ A row with no `backend` (an older kernel's, or an older routed host's)
3946
+ reads as tmux, as one with `tmux` does: both are read as before. A row recorded
3947
+ on Herdr keeps its own reason (`E_HERDR_REMOVED`) before any of this. On a
3948
+ row of this machine `herdr` is not read as a backend: such a row is known
3949
+ by its `sessionTarget` or its `unsupported` state, and one that only names
3950
+ `herdr` reads as before. A
3951
+ `backend` that is no provider's name (1 to 40 lowercase letters, digits
3952
+ and dashes, the first a letter or a digit; not `tmux` or
3953
+ `session-provider`) still makes the row a provider's, never asked of tmux:
3954
+ the clients then say "Runs outside tmux; it has no terminal to open." and
3955
+ show the value only as display text. `--backend` on a
3956
+ client's spawn is held to the names the kernel lists: `sessionBackends` of
3957
+ `oats version --json` and the session providers `oats inspect --json`
3958
+ reports.
3888
3959
  - **`color`** (feature `instance-color`): the instance's colour, one of
3889
3960
  `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3890
3961
  from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
@@ -5279,7 +5350,12 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
5279
5350
  `E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
5280
5351
  a home the kernel cannot look into, where whether it has a `work/` cannot
5281
5352
  be told; OATS 0.52.0).
5282
- - `midTask`: `true`, `false` or `"unknown"`.
5353
+ - `midTask`: `true`, `false` or `"unknown"`. A home on a
5354
+ [session provider](execution-targets.md#session-providers) whose session
5355
+ is there reads what its provider reports of it (the `running` of
5356
+ `oats session inspect`, see [Session providers](#session-providers-feature-session-providers)): `true` when it runs a turn,
5357
+ and `"unknown"` when the provider reports no activity (`running: null`),
5358
+ unless its work has changes, which is `true`.
5283
5359
  - `retiring` and `stopPending`, booleans on every target, say who holds the
5284
5360
  target's home when the plan is read (OATS 0.52.0, feature
5285
5361
  `lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
@@ -7348,6 +7424,177 @@ relayed).
7348
7424
 
7349
7425
  ## Sessions and launch configurations
7350
7426
 
7427
+ ### Session providers (feature `session-providers`)
7428
+
7429
+ A capability can supply a session backend beside the kernel's tmux
7430
+ ([execution-targets.md](execution-targets.md#session-providers); the
7431
+ capability's side is
7432
+ [capabilities.md](capabilities.md#session-providers-sessionproviders)). A
7433
+ home on one is a **provider home**. Everything below is added by the
7434
+ feature; a tmux home's answers are as they were, except its status row's
7435
+ `backend`.
7436
+
7437
+ **Reading the offer.** `oats inspect --soul <soul> --json` and `oats inspect
7438
+ --home <abs> --json` carry `sessionProviders: [{name, capability}]`, the
7439
+ backends `--backend` takes there beside `tmux`, sorted by name (`[]` when the
7440
+ soul has none; a malformed declaration is none). `oats capabilities show
7441
+ <name> --json` carries `sessionProviders` (the manifest's key, exactly as
7442
+ declared) and, only when there is one, `sessionProviderProblems: [{provider,
7443
+ pointer, message}]`.
7444
+
7445
+ **Spawn.** `oats spawn <soul> --backend <name>` (after `--preview`, as for
7446
+ tmux). A preview carries `backend: "<name>"`, `backendStatus: {name,
7447
+ installed: true, started: false}` and `executable: null`. A launched spawn's
7448
+ answer carries `backend: "<name>"`, `session: {provider, endpoint}`, `tmux:
7449
+ null`, `attach: null`, and its `launch.executable` is `null`. While the
7450
+ provider launches, the spawn holds the new home's lifecycle claim: a stop's
7451
+ apply, a start and a retire of it are refused as busy (`E_LIFECYCLE_BUSY`,
7452
+ `E_SESSION_START_BUSY`) until the launch is recorded or undone. Refusals,
7453
+ before anything is created (a preview answers them too):
7454
+
7455
+ | Code | `details` |
7456
+ |---|---|
7457
+ | `E_BACKEND_UNKNOWN` | `{backend, available}`: the names `--backend` takes for this instance, `tmux` first |
7458
+ | `E_BACKEND_AMBIGUOUS` | `{backend, capabilities}`; also from a start or a restart |
7459
+ | `E_BACKEND_HARNESS` | `{backend, capability, harness, harnesses}` |
7460
+ | `E_BACKEND_LAUNCH_ARG` | `{backend, launchConfig, field: "executable"}` |
7461
+ | `E_BACKEND_NOT_READY`, any other `E_BACKEND_*` | the provider's readiness, or its own refusal of the launch: `{backend, capability}`; the spawn is rolled back |
7462
+
7463
+ A launch that fails otherwise is `E_SESSION_START_FAILED`.
7464
+
7465
+ **A status row** (`oats status --json`) of a provider home:
7466
+
7467
+ ```json
7468
+ { "instance": "dev-a", "home": "/abs/home", "launched": true,
7469
+ "backend": "bb",
7470
+ "session": { "provider": "oats.bb", "threadId": "thr_1" },
7471
+ "tmux": null,
7472
+ "open": { "label": "Open in bb", "url": "https://…" },
7473
+ "running": true, "runtimeState": "unknown", "waitingOnYou": null }
7474
+ ```
7475
+
7476
+ - `backend` is the provider's name. A tmux home's row carries `backend:
7477
+ "tmux"`. **A row with no `backend` key reads as tmux**: it comes from a
7478
+ kernel or a routed host without the feature (or is a home whose record
7479
+ cannot be read), never from a provider home.
7480
+ - `session.provider` is the capability. **`session.threadId` is on a local
7481
+ row only**: the thread id of the provider's endpoint, when the endpoint
7482
+ names one, on the host where the home lives, so a tool there can match a
7483
+ session to its instance. It is replaced at a start and a restart, and a
7484
+ home OATS stopped keeps its last. **A relayed row never has it** (`oats
7485
+ server roster`, `oats status --server`): a relayed row's `session` is
7486
+ `{provider}`. A client must not depend on `threadId` beyond the local
7487
+ host.
7488
+ - **The endpoint is never on a row.** `session.endpoint` (the provider's own
7489
+ locator) is on `oats session inspect --home`, a launched spawn's answer
7490
+ and a start's answer, on the host where the home lives; the same answers
7491
+ through `--server` carry `session: {provider}`. Neither the endpoint nor
7492
+ `open` holds a token or a secret.
7493
+ - `tmux` is `null`; `open` is `{label, url}` or `null`: a link a viewer may
7494
+ open instead of a terminal. It is relayed.
7495
+ - `running` is `true`, `false`, or `null` where the provider cannot tell a
7496
+ live idle session from a settled one. `runtimeState` is always set:
7497
+ `unknown` (there), `shell`, `stopped` (OATS stopped it, it was never
7498
+ launched, or it is gone) or `unreachable`, with `runtimeError`, when the
7499
+ provider failed, was slow or answered outside its contract. An unreachable
7500
+ row is never read as stopped.
7501
+ - `sessionEnd` is `stopped` for a home an operator stopped, and `lost` for
7502
+ one stopped with the host or whose session is gone while OATS did not
7503
+ stop it: the sweep resumes a lost one. Absent otherwise.
7504
+ - `waitingOnYou` is the producers' claim, read while the session is there
7505
+ and not in error (`runtimeState: "unknown"`, `running` true or null).
7506
+
7507
+ **Inspect.** `oats session inspect --home <abs> --json` answers `{home,
7508
+ backend, present, state, running, waitingOnYou, wakeHold, session: {provider,
7509
+ endpoint}, open}`: no `paneId`, no `size`. `state` is `unknown`, `shell`,
7510
+ `stopped` or, before the first launch, `not-launched`. For a home OATS
7511
+ stopped it answers `present: false, state: "stopped", running: false, open:
7512
+ null` without asking the provider. A provider that cannot be asked is
7513
+ `E_SESSION_UNAVAILABLE`.
7514
+
7515
+ **Input.** `oats session input --home <abs>` answers `{home, backend,
7516
+ submitted: true, verified}` (no `session`: the endpoint is inspect's, a
7517
+ spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
7518
+ stopped (nothing was sent, the provider was not called), and for a lost
7519
+ session at its resume cap or with a process of its last run still in the
7520
+ home; `E_SESSION_PROMPT_OPEN` and `E_SESSION_INPUT_QUEUED` from the provider
7521
+ (nothing was sent); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
7522
+ restart that lands while an input is being sent wins, whatever the provider
7523
+ answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
7524
+ is accepted only on `ok: true` with `submitted: true`.
7525
+
7526
+ **Start and restart.** The result has every key a tmux start answers, with
7527
+ `backend: "<name>"`, `session: {provider, endpoint}` and `target: null`:
7528
+ `{instance, agent, home, harness, backend, model, launchConfig, yolo, target,
7529
+ session, startedAt, restartCount, reused: "new", warnings}`, and `stop:
7530
+ {stopped: true, waitedMs}` on a restart. A start of a home whose session is
7531
+ there and that OATS did not stop is `E_SESSION_RUNNING` (it reads `running:
7532
+ true`) or `E_SESSION_UNKNOWN`. `--resume` answers the same keys with `reused:
7533
+ "session"`, `startedAt: null` and `resume: {resumed: true, harness}`: the
7534
+ resume notice went through the provider's input and nothing was launched.
7535
+ Its refusals: `E_RESUME_NOT_LOST` (not a lost session), `E_SESSION_NOT_RUNNING`
7536
+ (the resume cap; `details.resumeCap: {limit, windowMs, nextAttemptAt}`),
7537
+ `E_SESSION_UNKNOWN` (a process of the last run still works in the home, or
7538
+ the session cannot be read), `E_SESSION_PROMPT_OPEN` (a claim or a prompt is
7539
+ open) and `E_SESSION_INPUT_QUEUED`.
7540
+
7541
+ **A launch with no recorded outcome** (the lifecycle's
7542
+ [design record](design/2026-11-20-provider-home-lifecycle.md)). From the
7543
+ moment a spawn or a start sends the provider's launch until its endpoint is
7544
+ recorded, and for good when that command died first, the home's receipt
7545
+ carries `launchSent` and the home is unknown, whether it was launched before
7546
+ or not: `oats session inspect` answers `E_SESSION_UNAVAILABLE`, its status
7547
+ row reads `running: null`, `runtimeState: "unreachable"` with the reason, a
7548
+ `--resume` is `E_SESSION_UNKNOWN`, and `oats session input` is refused with
7549
+ nothing sent (`E_SESSION_NOT_RUNNING` for a home never launched or recorded
7550
+ as stopped, else `E_SESSION_INPUT_FAILED`). A stop, a start, a restart and a
7551
+ retire settle it first, by asking the provider to stop whatever session that
7552
+ launch started: a stop then answers `stopped: true` (never `alreadyIdle`),
7553
+ or `E_SESSION_STOP_FAILED` when the provider does not confirm; a home
7554
+ launched before is left stopped. The row of a never-launched home reads
7555
+ `launched: true` meanwhile.
7556
+
7557
+ **Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
7558
+ state: "stopped"}`; `E_SESSION_STOP_FAILED` when the provider does not confirm
7559
+ (the home stays recorded as stopped; a second stop asks the provider again). A retire goes on
7560
+ only when no process works in the home after the provider's stop, confirmed
7561
+ or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
7562
+ provider could not confirm the stop, the retire's answer carries a warning.
7563
+
7564
+ **Attach.** `E_SESSION_NO_TERMINAL`, `details: {backend, open}`; its message
7565
+ carries the `open` link when there is one. A client shows that link instead
7566
+ of a terminal.
7567
+
7568
+ **The authority check.** `E_RUNTIME_AUTHORITY_MISMATCH`'s `details.fields`
7569
+ for a provider home are `backend`, `session.provider` and `session.endpoint`
7570
+ (after `launched`).
7571
+
7572
+ **Readiness.** `oats readiness` carries a provider's own readiness, where it
7573
+ declares one, as a `providers` item: `subject: "<capability> session backend
7574
+ <name>"`, `producer: "session provider check"`, `result: {status, problems,
7575
+ warnings}` relayed as given, or `result: null` with `problems` when the
7576
+ provider could not be asked. Required for a home on that backend; not
7577
+ required for a soul.
7578
+
7579
+ **The sweep.** A row of `oats session resume` for a provider home carries
7580
+ `backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
7581
+ `already-running` (a session is there), `refused` with `keeps-getting-lost`
7582
+ (the home's resume cap; `code: "E_SESSION_NOT_RUNNING"`, with
7583
+ `nextAttemptAt`; a `--plan` reads the same count and answers the same) or `start-refused`
7584
+ (the notice was not sent: a prompt or a claim is open, or it was queued),
7585
+ `skipped` with `unknown` (not readable, or a process of the last run still
7586
+ works in the home). A home an operator stopped has no row. `--plan
7587
+ --without-provider-inspect` asks no session provider: every provider home
7588
+ OATS has not stopped is then `skipped`, `unknown`, with its `backend`
7589
+ (`E_BAD_ARGS` without `--plan`). The switch is `oats host run`'s own: it
7590
+ lists with it at shutdown, so that a provider going down with the host cannot
7591
+ hold the listing up. A client has no use for it.
7592
+
7593
+ **Launch preview.** `oats launch-config preview --home <abs> --json` of a
7594
+ provider home answers `command: null`, `argv: null` and `executable.path:
7595
+ null` (its launch is handed to the provider as data), `environment` by name,
7596
+ and a `backend` item in `preflight`.
7597
+
7351
7598
  ### Input
7352
7599
 
7353
7600
  ```text
@@ -7356,7 +7603,8 @@ oats session input --home <abs> [--text-file <path>] --json
7356
7603
 
7357
7604
  Input bytes come from stdin or the named file. The existing version-1 success
7358
7605
  answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
7359
- present: true, state, paneId, submitted: true, verified}}`. Session input runs
7606
+ present: true, state, paneId, submitted: true, verified}}` (a provider home's
7607
+ is under [Session providers](#session-providers-feature-session-providers)). Session input runs
7360
7608
  on the execution host, including when the wake broker invokes it there;
7361
7609
  `--server` is not supported for input. The adapter sends one literal
7362
7610
  bracketed paste and one Enter after the existing input/authority/target checks.
@@ -7395,7 +7643,7 @@ harness receipt. See [execution targets](execution-targets.md).
7395
7643
  oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
7396
7644
  oats session start --resume --home <abs> --json
7397
7645
  oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
7398
- oats session resume [--deployment <dir>] [--plan] --json
7646
+ oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json
7399
7647
  ```
7400
7648
 
7401
7649
  Features `session-start`, `session-restart`, and `launch-config` for the
@@ -7563,7 +7811,7 @@ answer is the ordinary start answer plus one object:
7563
7811
 
7564
7812
  ### The machine sweep (`oats session resume`)
7565
7813
 
7566
- `oats session resume [--deployment <dir>] [--plan] --json` (feature
7814
+ `oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json` (feature
7567
7815
  `session-resume`, OATS 0.69) starts with `--resume` every home of this
7568
7816
  machine's deployments whose session was lost. A client runs it once when it
7569
7817
  opens. It reads this computer's list of deployments without writing it