@awebai/oats 0.69.23 → 0.70.0

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 (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -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 +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  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/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -441,6 +441,10 @@ A self-contained package has an `oats.json`:
441
441
  - `triggerSources` (optional) declares the capability's
442
442
  [trigger sources](#trigger-sources-triggersources). It is checked only
443
443
  where a source is used, never when the capability loads.
444
+ - `sessionProviders` (optional) declares the session backends the
445
+ capability supplies beside the kernel's tmux
446
+ ([session providers](#session-providers-sessionproviders)). It is checked
447
+ only where a provider is used, never when the capability loads.
444
448
  - Target names never appear in a package manifest.
445
449
 
446
450
  `capability` is the only manifest identity field; it may also carry
@@ -655,11 +659,24 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
655
659
  `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
656
660
  `OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
657
661
  preview (only a preview-aware hook does, below); on a real run
658
- `OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
662
+ `OATS_LAUNCH_PREVIEW` is not set. A spawn hook and a launch hook also get
663
+ `OATS_BACKEND` (feature `session-providers`): the session
664
+ backend the instance launches on, `tmux` or the name of a
665
+ [session provider](#session-providers-sessionproviders). A spawn that launches
666
+ nothing (`--no-launch`) sets it too: it is what a later start launches on. A
667
+ kernel without the feature sets none, which means tmux. A launch hook also
668
+ gets `OATS_PREVIOUS_BACKEND`: the backend the home was last launched on, as the
669
+ kernel recorded it outside the home (its session receipt), `tmux` or a session
670
+ provider's name. It is absent at a home's first launch, and it is never read
671
+ from the home's own record, which the home's agent can write. A capability
672
+ that keeps files of its own in a home for one backend (a session provider's
673
+ settings file) removes them only when this variable names that backend, and
674
+ removes nothing when it is absent. A worktree hook also gets the tree
659
675
  variables of [The worktree event](#the-worktree-event).
660
676
 
661
677
  A spawn or launch hook also gets `OATS_HARNESS_EXECUTABLE`, for every harness
662
- and the same way in a preview: the absolute real path of the executable the
678
+ on tmux and the same way in a preview (a session provider runs the harness
679
+ itself, so the variable is absent there): the absolute real path of the executable the
663
680
  pane will run, found the way the pane finds it. It is reserved, so a launch
664
681
  configuration's `env` or a trigger cannot set it, and an inherited value is
665
682
  dropped. It doesn't reach the harness's pane, even from an existing server's
@@ -1026,7 +1043,10 @@ into the capture hooks and the capture service's unit. In the third case
1026
1043
 
1027
1044
  `OATS_EVENT=upgrade` lets a staged destination package module adopt the state
1028
1045
  of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
1029
- the staged new copy, with the usual lifecycle environment plus:
1046
+ the staged new copy (in a home on a session provider: from the kernel's own
1047
+ copy of the new module, see
1048
+ [What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)),
1049
+ with the usual lifecycle environment plus:
1030
1050
 
1031
1051
  - `OATS_UPGRADE_PHASE`: `plan` or `apply`;
1032
1052
  - `OATS_META`: the old recorded `capabilityMeta[capability]`;
@@ -1035,7 +1055,10 @@ the staged new copy, with the usual lifecycle environment plus:
1035
1055
  - `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
1036
1056
  - `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
1037
1057
  directory. Register host artifacts against this path, never the staging path,
1038
- which is removed after the move.
1058
+ which is removed after the move. In a home on a session provider, in the
1059
+ `apply` phase, it is the kernel's copy of the module, which is where the
1060
+ module's code runs from then on (in `plan`, where nothing is registered,
1061
+ it is the home's path).
1039
1062
 
1040
1063
  In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
1041
1064
  `{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
@@ -1257,7 +1280,8 @@ claim and holds no scheduled wake. The board is in
1257
1280
  **The Claude Code emitter.** For a Claude instance, oats.core's spawn and
1258
1281
  launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
1259
1282
  into the home's project settings, `<home>/.claude/settings.json`. Each one
1260
- runs `bin/claude-waiting.sh` from the home's module copy, which calls
1283
+ runs `bin/claude-waiting.sh` from the home's module copy (in a home on a
1284
+ session provider: from the kernel's copy of it), which calls
1261
1285
  `oats instance waiting set|clear --producer oats.core`:
1262
1286
 
1263
1287
  | Claude Code event | Matcher | Action |
@@ -1424,8 +1448,9 @@ waiting clear --producer oats.core --home <home>` from anywhere.
1424
1448
  - **Its own entries only.** oats.core marks its entries by the absolute
1425
1449
  path of its `claude-waiting.sh`. Each run removes only the entries that
1426
1450
  name that path (and any matcher group or event array the removal
1427
- empties), then appends its current ones. Every other key and entry stays
1428
- as it was, in order. The file is written atomically, mode 0600, and only
1451
+ empties), then appends its current ones. Apart from adding `tui` when
1452
+ absent (below), every other key and entry stays as it was, in order.
1453
+ The file is written atomically, mode 0600, and only
1429
1454
  when its content changes. A temp file an interrupted write left behind
1430
1455
  (`.claude/.settings.json.oats-core-<pid>-<ms>.tmp`) is removed by the next
1431
1456
  spawn or start once its writer is gone, so it needs no retirement
@@ -1527,8 +1552,9 @@ home whose oats.core moves to it is upgraded rather than respawned. The
1527
1552
  hook that runs is the destination's, so this covers homes spawned on any
1528
1553
  earlier oats.core, with or without the emitter. oats.core records no
1529
1554
  capability metadata, and its settings entries name the module copy's path,
1530
- `.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
1531
- hook rewrites them. So `plan` adopts a home whose recorded
1555
+ `.oats/modules/oats.core`, which an upgrade keeps (in a home on a session
1556
+ provider they name the kernel's copy, whose path an upgrade changes); the
1557
+ next start's launch hook rewrites them. So `plan` adopts a home whose recorded
1532
1558
  `capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
1533
1559
  `false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
1534
1560
  refuses any other value as state it cannot vouch for, with the remedy
@@ -1546,10 +1572,25 @@ that file replaces earlier ones wholesale, even one with no hooks. The
1546
1572
  project `.claude/settings.json` composes with the user's settings (under any
1547
1573
  `CLAUDE_CONFIG_DIR`) and with a `--settings`. So any capability that needs
1548
1574
  Claude settings uses the same managed `<home>/.claude/settings.json` with
1549
- its own marker, never `--settings`. oats.core leaves
1575
+ marked entries for its hooks, never `--settings`. oats.core leaves
1550
1576
  `.claude/settings.local.json` to Claude Code, which writes its "don't ask
1551
1577
  again" permission rules there.
1552
1578
 
1579
+ **Renderer selection.** In the same merge, at spawn and every launch,
1580
+ oats.core adds `"tui": "default"` when the project's settings have no `tui`
1581
+ key. Any existing value, including a non-string, is kept: a scalar has no
1582
+ marker to distinguish the person's choice from oats.core's. Any `tui` in
1583
+ Claude's merged settings skips its fullscreen-renderer offer, which can
1584
+ otherwise stop an unattended agent before it receives a wake. `"default"`
1585
+ selects the classic renderer used by the launch-prompt captures and keeps
1586
+ tmux scrollback. The cost: agent panes use Claude's classic renderer even
1587
+ where Claude defaults to fullscreen, and the project setting overrides a
1588
+ user-level `"tui": "fullscreen"`. An existing project `tui` still wins.
1589
+ A pass that changes nothing does not rewrite the file. The existing file
1590
+ refusals, preview behaviour and non-Claude behaviour above apply to `tui`
1591
+ too. If oats.core ever stops adding it, existing homes keep the key until
1592
+ respawn.
1593
+
1553
1594
  **Limits.**
1554
1595
 
1555
1596
  - If the user's Claude configuration sets `disableAllHooks` or
@@ -1681,7 +1722,8 @@ spawn's fail-closed hooks.
1681
1722
  ```
1682
1723
 
1683
1724
  **Invocation.** The kernel runs the command's script with `node`, from the
1684
- module directory. That is the home's module copy for `--home`, or the
1725
+ module directory. That is the home's module copy for `--home` (the kernel's
1726
+ copy of it, for a home on a session provider), or the
1685
1727
  deployment's verified module store for `--soul`. The script must resolve inside
1686
1728
  the module and be a regular file. The command's words after the script are
1687
1729
  passed as arguments; no shell is involved.
@@ -1944,3 +1986,647 @@ whole poll, resolution included, gets 35 s, and polls run only while they can
1944
1986
  end within 50 s of the tick's start. Answer from a cache or a quick query: a
1945
1987
  source slower than that should cache.
1946
1988
 
1989
+ ## Session providers (`sessionProviders`)
1990
+
1991
+ A kernel that lists the feature `session-providers` in `oats version --json`
1992
+ has this contract. tmux is the kernel's own session backend. A capability can supply another one, a
1993
+ **session provider**: the instance's agent then runs wherever the provider
1994
+ runs it (a thread of another product, a remote runner), and the kernel reaches
1995
+ it through four of the capability's own commands. The kernel keeps what a
1996
+ backend must not own: the receipts and the authority check, the lifecycle
1997
+ claims, the refusals and the JSON answers. What an operator sees is in
1998
+ [execution-targets.md](execution-targets.md#session-providers).
1999
+
2000
+ ```json
2001
+ "commands": { "session-launch": "bin/session.mjs launch", "session-inspect": "bin/session.mjs inspect",
2002
+ "session-input": "bin/session.mjs input", "session-stop": "bin/session.mjs stop",
2003
+ "session-inspect-many": "bin/session.mjs inspect-many" },
2004
+ "sessionProviders": {
2005
+ "bb": {
2006
+ "description": "Runs the agent as a bb thread",
2007
+ "wire": "1.3",
2008
+ "harnesses": ["claude"],
2009
+ "commands": { "launch": "session-launch", "inspect": "session-inspect", "input": "session-input",
2010
+ "stop": "session-stop", "inspectMany": "session-inspect-many" }
2011
+ }
2012
+ }
2013
+ ```
2014
+
2015
+ - The **name** is 1 to 40 lowercase letters, digits and dashes, starting with
2016
+ a letter or digit. `tmux`, `session-provider` and `herdr` are reserved. It
2017
+ is what `--backend` takes, and what a hook reads in `OATS_BACKEND`. At most
2018
+ 16 providers.
2019
+ - **`commands`** names `launch`, `inspect`, `input` and `stop`, and optionally
2020
+ `inspectMany` and `check`. Each value is a key of the manifest's
2021
+ `commands`.
2022
+ - **`harnesses`** lists the harnesses the provider runs (1 to 16 names). A
2023
+ spawn or a start on another one is refused `E_BACKEND_HARNESS`.
2024
+ - **`description`** is optional: one line of at most 200 characters.
2025
+ - **`wire`** is the version of this wire the provider speaks: `"1.3"`. The
2026
+ kernel calls only a provider that declares its own version. One that
2027
+ declares another, or none (a provider written before the key: wire 1.2),
2028
+ is refused `E_BACKEND_WIRE`, naming both versions, before anything is
2029
+ created, recorded, stopped or started: a spawn, a start, a stop (an
2030
+ operator's and the host's) and an input alike. Its homes' sessions read
2031
+ unavailable, and are never recorded as stopped by a provider that was not
2032
+ asked. A retire of such a home cannot ask it either: it goes on when no
2033
+ process works in the home, with a warning that names the provider's own
2034
+ tooling. Every request carries the kernel's version (`"wire"`), so refuse
2035
+ a request that carries none or another, with the same code.
2036
+ - No other key.
2037
+
2038
+ **Containment.** A malformed `sessionProviders` never refuses the capability:
2039
+ it is validated where a provider is used. A problem inside one provider
2040
+ disables that provider only, and `--backend <name>` then answers
2041
+ `E_BACKEND_UNKNOWN` with the problem. `oats capabilities show <name> --json`
2042
+ adds `sessionProviders` (as declared) and, when there is one,
2043
+ `sessionProviderProblems: [{provider, pointer, message}]`.
2044
+ [`docs/capability-manifest.schema.json`](capability-manifest.schema.json)
2045
+ carries the same shape; that a verb names one of the manifest's commands is
2046
+ checked by the kernel only.
2047
+
2048
+ **One name, one meaning.** A provider is selected among the capabilities of
2049
+ the instance being spawned. Two of them declaring the same name is
2050
+ `E_BACKEND_AMBIGUOUS`: compose only one.
2051
+
2052
+ ### The call
2053
+
2054
+ Every call runs the **kernel's copy** of the home's capability, kept outside
2055
+ the home, never the home's own copy
2056
+ ([What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)):
2057
+ `node <instances>/.oats-retirement/modules/…/<capability>/<script> <args>`. **Its working
2058
+ directory is not the home** (it is the filesystem root): read the home from
2059
+ the request (`input.home`) or `OATS_INSTANCE_HOME`, and leave
2060
+ nothing of the call's own running in the home (the session's processes work
2061
+ there; a helper of your command must not). OATS looks for
2062
+ processes working in a home before it resumes a lost session and before it
2063
+ retires the home, and a provider's call must never be one of them.
2064
+
2065
+ - **Environment:** what a lifecycle hook of the capability gets in that home
2066
+ ([Commands and hooks](#commands-and-hooks)): `OATS_INSTANCE`,
2067
+ `OATS_INSTANCE_HOME`, `OATS_SETTINGS` (the settings captured at spawn),
2068
+ `OATS_META`, `OATS_CLI_BIN` and the rest, with `OATS_EVENT=session` and
2069
+ `OATS_BACKEND=<name>`.
2070
+ - **stdin:** one JSON request,
2071
+ `{ "schemaVersion": 1, "wire": "1.3", "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
2072
+ - **stdout:** exactly one JSON document of at most 1 MiB, the same five header
2073
+ keys echoed, then `"ok": true, "result": { … }` or
2074
+ `"ok": false, "error": { "code": "E_…", "message": "…" }`. No other key.
2075
+ A refusal's code is `E_` followed by capitals, digits and underscores.
2076
+ - **Exit status 0**, for a result and for a refusal.
2077
+ - **Timeouts:** launch 120 s, stop 20 s plus the grace it is given, every
2078
+ other verb 20 s. The command is killed at its timeout.
2079
+ - **Process group:** OATS runs each command in a process group of its own,
2080
+ and ends the whole group (SIGKILL) at the timeout, and when the `oats`
2081
+ command that ran a `launch`, an `input` or a `stop` was itself killed
2082
+ while it waited (the next stop, start, input or retire of the home does
2083
+ it, before it calls you again). A stop also waits for an `input` that is
2084
+ being sent, up to its timeout, before it asks you to `stop`. **Run your helpers inside that group and never detach
2085
+ them** (no `setsid`, no daemon): a helper that escapes it can start a
2086
+ session OATS has no record of.
2087
+ - stderr is never read.
2088
+
2089
+ A call that does not end that way (another exit status, a signal, the
2090
+ timeout, no or malformed JSON, a wrong envelope, a result that breaks its
2091
+ verb's rules) is a **failed call**. A failed call is never read as an answer:
2092
+ an inspect that failed is never "stopped".
2093
+
2094
+ | Verb | A failed call, or a refusal the kernel does not relay |
2095
+ |---|---|
2096
+ | `inspect`, `inspectMany` | `E_SESSION_UNAVAILABLE`; the status row reads `running: null`, `runtimeState: "unreachable"` |
2097
+ | `check` | the readiness item reads `unknown`; a launch is refused `E_BACKEND_NOT_READY` |
2098
+ | `input` | `E_SESSION_INPUT_FAILED` |
2099
+ | `stop` | `E_SESSION_STOP_FAILED` |
2100
+ | `launch` | `E_SESSION_START_FAILED` |
2101
+
2102
+ The kernel relays these refusals under the provider's own code: from
2103
+ `launch`, any `E_BACKEND_*`; from `input`, `E_SESSION_PROMPT_OPEN` and
2104
+ `E_SESSION_INPUT_QUEUED`. The message of any refusal is carried into the
2105
+ kernel's, made safe to print and cut to 500 characters.
2106
+
2107
+ ### launch
2108
+
2109
+ In:
2110
+
2111
+ ```json
2112
+ { "home": "/abs/home", "instance": "dev-a", "harness": "claude", "model": "id-or-null", "yolo": true,
2113
+ "env": [ { "name": "OATS_INSTANCE", "value": "dev-a", "source": "kernel" },
2114
+ { "name": "AWEB_IDENTITY_HOME", "value": "/abs/…", "source": "capability", "capability": "oats.aweb" },
2115
+ { "name": "REGION", "value": "eu", "source": "launch-config" },
2116
+ { "name": "API_KEY", "value": "…", "source": "launch-config-reference", "secret": true } ],
2117
+ "unset": ["NAME"],
2118
+ "pathPrepend": ["/abs/home/.oats/bin"],
2119
+ "args": ["--flag", "value"],
2120
+ "promptFile": "/abs/home/TASK.md",
2121
+ "previous": null,
2122
+ "sandbox": { "domains": [], "write": [ { "path": "/abs/deployment/.agents/events", "reason": "oats events" } ], "missing": [] },
2123
+ "trees": ["/abs/home/work", "/abs/home/.work-docs"],
2124
+ "protected": ["/abs/deployment/agents/dev/instances/.oats-retirement"] }
2125
+ ```
2126
+
2127
+ - `env` is every variable the launch sets, in the order a tmux launch sets
2128
+ them. `source` says where each comes from: `kernel` (the instance's
2129
+ identity, a trigger's event file), `capability` (a hook's `env`, with the
2130
+ `capability` that owns it), `launch-config` (a launch configuration's
2131
+ literal value) or `launch-config-reference` (a launch configuration's
2132
+ `fromEnv` or `fromFile`: a secret source, marked `secret: true`, its value
2133
+ read on this host).
2134
+ - `unset` lists the names the launch removes: declared by a capability and
2135
+ left out of this launch.
2136
+ - `pathPrepend` is the home's kernel shim directory. Put it first on the
2137
+ agent's `PATH`, so its plain `oats` is the kernel that launched it.
2138
+ - `args` is the launch configuration's arguments, then the capabilities'
2139
+ launch arguments for the harness, as the words a shell would hand it
2140
+ (arguments the kernel cannot read as words are refused,
2141
+ `E_BACKEND_LAUNCH_ARG`, naming the capability). The kernel's own choices are never in
2142
+ it: they are `model` (null: the harness's default), `yolo` (`true`,
2143
+ `false`, or `null` when nobody chose) and the prompt.
2144
+ - `promptFile` is the home's `TASK.md`: the briefing a fresh conversation
2145
+ starts on.
2146
+ - `previous` is the endpoint of the session a start or a restart replaces;
2147
+ `null` for the home's first launch. The kernel has asked you to stop it
2148
+ just before, always (a restart's stop, once more for a home OATS had
2149
+ stopped, and for a session you answered as gone too: an input that reached
2150
+ it since may have had you restart it).
2151
+ - `sandbox` is what you may widen your harness's sandbox by, and nothing
2152
+ else: [Sandbox allowances](#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox).
2153
+ - `trees` is the home's trees, as absolute paths: `<home>/work`, always and
2154
+ first, then every extra tree of the home (`oats worktree add`). An extra
2155
+ tree is what Git itself says is one, a registered linked worktree of a
2156
+ repository outside the home, read with the kernel's own hardened Git;
2157
+ nothing in the home's `instance.json` names a tree. A provider that runs
2158
+ its harness in a sandbox keeps each tree's `.git` pointer, and the
2159
+ `config` and `hooks` of its Git directory and of its common directory,
2160
+ unwritable from the session, and refuses a launch it would sandbox without
2161
+ `trees`. One limit to know: the list of a repository's worktrees is in its
2162
+ common Git directory, so a session that can write there can take a tree
2163
+ off the list, and that tree is then no longer sent. `<home>/work` always
2164
+ is.
2165
+ - `protected` is the kernel's own state for this home, as absolute paths of
2166
+ directories: **paths a sandboxed agent must never write, and that a
2167
+ provider must not block reading or executing.** Today it is one entry,
2168
+ `<instances>/.oats-retirement/`, which holds the kernel's copies of the
2169
+ home's modules (what it runs, and what the home's hooks hand the harness
2170
+ to run), the receipts, the lifecycle claims and the records of provider
2171
+ commands in flight
2172
+ ([What the kernel trusts in a provider home](#what-the-kernel-trusts-in-a-provider-home)).
2173
+ The kernel makes each directory before it asks you anything, so one that
2174
+ is missing is a fault, not a first launch. It is never derived from the
2175
+ home. A provider that runs its harness in a sandbox denies writes to each
2176
+ entry, leaves it readable and executable at the same path, and refuses a
2177
+ launch it would sandbox when `protected` is absent or an entry is not an
2178
+ absolute path of a directory. (`trees` and `protected` were added to wire
2179
+ 1.3 without a new version only because no release carries a provider yet.)
2180
+
2181
+ **A provider that cannot carry an env entry, an argument or `unset`
2182
+ refuses, naming it** (`E_BACKEND_LAUNCH_ENV`, `E_BACKEND_LAUNCH_ARG`). It
2183
+ never drops one silently, and it never stores a `secret` value where others
2184
+ can read it.
2185
+
2186
+ Out: `{ "endpoint": { … } }`. The endpoint is a JSON object whose canonical
2187
+ JSON is at most 4 KiB (4096 bytes). **It names one session: answer an
2188
+ endpoint you never answered before for that home** (a new thread id, not a
2189
+ locator a later session takes over). The kernel stops a session by its
2190
+ endpoint, also after a newer one was launched. The kernel records it as given, in the
2191
+ home's `instance.json` and its receipt, and hands it back on every call. It
2192
+ holds **locators only, never a credential**.
2193
+
2194
+ The kernel refuses, before anything is created, a launch configuration that
2195
+ declares `executable` for a provider backend (`E_BACKEND_LAUNCH_ARG`): the
2196
+ provider runs the harness itself.
2197
+
2198
+ ### inspect and inspectMany
2199
+
2200
+ `inspect` in: `{ "home", "endpoint" }`. Out:
2201
+ `{ "present": true|false, "state": "unknown"|"shell"|"stopped", "running": true|false|null, "open"?: { "label", "url" } }`,
2202
+ exactly those keys.
2203
+
2204
+ | The session | present | state | running |
2205
+ |---|---|---|---|
2206
+ | a turn or a start is in progress | true | `unknown` | true |
2207
+ | there, and the provider cannot tell a live idle session from a settled one | true | `unknown` | null |
2208
+ | gone: missing, deleted, or in error with nothing running | false | `stopped` | false |
2209
+ | the harness ended and something else holds the session, as a terminal left at its shell | true | `shell` | false |
2210
+
2211
+ A session that is not there (`present: false`) is `stopped` and runs nothing:
2212
+ any other answer with `present: false` is outside the table, and is read as
2213
+ no answer (unavailable), like a word outside the contract.
2214
+
2215
+ Map only what the product shows; never infer. **A session that is gone on a
2216
+ home OATS did not stop is a lost session**: OATS resumes it through `input`,
2217
+ under its cap ([below](#what-the-kernel-does-around-the-verbs)). So answer a
2218
+ session whose run ended in error as gone, not as `shell`, when your product
2219
+ restarts it on the next input. `open` is what a client may
2220
+ show instead of a terminal: a one-line `label` of at most 100 characters and
2221
+ an `http` or `https` `url` of at most 2000, without credentials.
2222
+
2223
+ `inspectMany` (optional) in:
2224
+ `{ "homes": [ { "home", "instance", "endpoint" } ] }`, at most 200. Out:
2225
+ `{ "results": [ … ] }`, one per home in the same order, each an inspect
2226
+ result or `{ "error": { "code", "message" } }`. `oats status` calls it once
2227
+ per group of homes that share the capability's module copy (the same
2228
+ source, as each home's receipt records it),
2229
+ the provider and the settings; the call's environment is the group's first
2230
+ home's. Each entry is judged as one `inspect` answer would be. A batch that
2231
+ fails or is not one result per home, and an entry that is neither a result
2232
+ nor a refusal, fall back to that home's own `inspect`, never to "stopped".
2233
+ Without `inspectMany`, status calls `inspect` per home.
2234
+
2235
+ **The kernel never calls inspect for a home OATS stopped** (below).
2236
+
2237
+ ### input
2238
+
2239
+ In: `{ "home", "endpoint", "text" }`. Out: `{ "submitted": true, "verified": true|false }`
2240
+ **only when the text was dispatched** to the session. `submitted` is never
2241
+ `false` in a result: an input that was not dispatched is a refusal.
2242
+
2243
+ - A session with a prompt open (a permission prompt, a question) is not
2244
+ answered by an input: refuse `E_SESSION_PROMPT_OPEN` and send nothing.
2245
+ Otherwise any mail could approve a permission.
2246
+ - An input the product queued instead of dispatching is not a submission:
2247
+ withdraw it and refuse `E_SESSION_INPUT_QUEUED`.
2248
+
2249
+ Both reach the caller as they are, with `ok: false`. The messaging broker
2250
+ leaves such a mail unread; a scheduled wake records it not delivered.
2251
+
2252
+ ### stop
2253
+
2254
+ In: `{ "home", "endpoint", "graceSeconds", "launchSent"? }`. Out: `{ "stopped": true }`.
2255
+ `endpoint` is `null` when the kernel has no endpoint for a session you may
2256
+ have started: a launch whose answer was lost, and a launch it sent whose
2257
+ spawn or start ended before recording your answer (it was killed while you
2258
+ launched). Then stop whatever live session is rooted at the home, and answer
2259
+ `stopped: true` also when there is none. The input then also carries
2260
+ `"launchSent": "<instant>"`, the time the kernel recorded for that launch,
2261
+ when it has one: what the launch started was created at or after it, so you
2262
+ can leave alone what was in the home's place before (a person's own session
2263
+ there). **The kernel relies on this stop**: it is the only way a session
2264
+ started by a killed spawn is ever stopped.
2265
+
2266
+ ### check (optional)
2267
+
2268
+ The provider's readiness. In: `{ "home": "/abs/home" | null, "soul": "<name>" | null, "settings": { … } }`:
2269
+ a home, or, before any home exists, a soul; and, before a launch,
2270
+ `"launch": { "harness", "yolo", "args", "sandbox", "trees", "protected" }`, the launch that is
2271
+ planned: the harness, yolo, the allowances, the trees and the protected paths as its launch input will
2272
+ carry them, and in `args` the launch configuration's own arguments. **The
2273
+ arguments a capability's hooks contribute are not in it**: the check runs
2274
+ before any hook, and those reach the launch input only. Out:
2275
+ `{ "status": "ready" | "needs-configuration" | "authorization-required" | "unavailable", "problems": [ { "code", "message" } ], "warnings": [ { "code", "message" } ] }`
2276
+ (`warnings` optional; no problem on `ready`). Say where a credential comes
2277
+ from, never print it.
2278
+
2279
+ - `oats readiness` relays the answer as a `providers` item, the shape a
2280
+ binding check's answer has: for a home, its own backend's, required; for a
2281
+ soul, each provider its capabilities offer, not required (the soul can
2282
+ launch on tmux).
2283
+ - **The kernel asks it before every launch, and before any hook runs** (a
2284
+ spawn's before its spawn hooks, a start's and a restart's before their
2285
+ launch hooks and before a restart's stop). A status other than `ready`
2286
+ refuses the launch: with the first problem's code when that is an
2287
+ `E_BACKEND_*` code, else `E_BACKEND_NOT_READY`, the message carrying your
2288
+ problems. A refused spawn runs no hook and leaves no home; a refused
2289
+ start or restart runs no hook and stops nothing. A check that fails or
2290
+ answers outside these words is not ready.
2291
+
2292
+ ### What the kernel trusts in a provider home
2293
+
2294
+ A provider may run its harness in a sandbox that still lets the agent write
2295
+ its own home. The kernel that runs the home's hooks and your commands runs
2296
+ outside any sandbox, as the operator, while that agent runs. So, for a home
2297
+ on a session provider, **the kernel runs nothing that is in the home, and
2298
+ takes no capability setting from it**:
2299
+
2300
+ - **The kernel keeps its own copy of the home's modules, outside the home,**
2301
+ at `<instances>/.oats-retirement/modules/<hash of the home>/<store>/<capability>/`,
2302
+ beside the home's receipt. The spawn makes it from the copies it
2303
+ materialised, once, before it asks you anything and before any hook of
2304
+ the spawn runs. Every lifecycle hook
2305
+ and worktree hook, every one of your commands, every capability's
2306
+ readiness check and every command or operation dispatched in the home is
2307
+ run from that copy, and the home's manifests are read there. The copies
2308
+ under `<home>/.oats/modules/` stay where they are, for the agent and its
2309
+ harness (its skills, what the harness runs inside its sandbox). The kernel
2310
+ never runs them, and reads nothing it acts on from them, so nothing the agent does to them,
2311
+ at rest or while the kernel is running a command, changes what the kernel
2312
+ runs. (A copy in the home that is checked and then run can be exchanged
2313
+ between the two by the session that writes the home. That is why the
2314
+ kernel keeps a copy instead of checking the home's.)
2315
+ - **The receipt records the home's composition.** The home's receipt
2316
+ (`<instances>/.oats-retirement/baselines/`) carries `composition`: which
2317
+ store holds the kernel's copies, which modules the home has and where each
2318
+ came from, and the capability rows the spawn resolved from the deployment
2319
+ (each capability's settings, their origins, its level, and its hook
2320
+ commands, which name the kernel's copy).
2321
+ - **A capability's settings and hook commands are the receipt's.**
2322
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, which hooks a capability has and
2323
+ the command of each come from the receipt's rows, never from
2324
+ `instance.json` (`capabilityRuntime`, `capabilities`, `providers`, the
2325
+ settings recorded with each launch contribution) nor from a rollback
2326
+ marker. A capability the home's record adds is no capability of the
2327
+ home, at a launch, at a retire and at an upgrade alike.
2328
+ - **Retirement removes the kernel's copy** with the home, and so does the
2329
+ rollback of a spawn that fails. A home that is kept (a retire that could
2330
+ not finish, a quarantined spawn) keeps its copy, so that its cleanup can
2331
+ run. A spawn takes away whatever an earlier home left at its path, the
2332
+ receipt and the copies, before anything reads them.
2333
+ - **An upgrade** (`oats instance upgrade`) makes the kernel's copies for the
2334
+ upgraded home in a new store beside the old one, before any upgrade hook
2335
+ runs: each moved module from the upgrade's staged copy, once that is found
2336
+ to be the one the upgrade verified against the lock, and every other
2337
+ module from the kernel's own current copy. Each upgrade hook runs from the
2338
+ kernel's copy. The receipt is then written once, naming the new store and
2339
+ the new rows together, and keeping the pair it replaced as `previous`.
2340
+ **An upgrade that fails or is interrupted before that write leaves the old
2341
+ copy and the old capability rows, together**; after it, the new ones.
2342
+ There is no moment at which the rows name one version and the kernel runs
2343
+ another. A store is removed only once a move is complete, after the
2344
+ receipt's write: the one before the previous. A move that fails after
2345
+ that write and is rolled back puts the earlier receipt back whole, from
2346
+ the kernel's own memory of it and never from a copy kept in the home,
2347
+ with the stores it names still there.
2348
+ - **An undo** (`oats instance upgrade --undo`) writes the receipt once,
2349
+ naming the previous store and the previous rows again; the newer store is
2350
+ removed after that write. The hook an undo runs is the kernel's previous
2351
+ copy's. The home's own copies are restored from what the home kept, as
2352
+ for every home: they are the agent's. One previous move is kept, so one
2353
+ undo is possible.
2354
+ - **An upgrade that was interrupted is not resumed** for such a home: its
2355
+ journal is in the home, where the agent can write. The kernel's side is
2356
+ whole either way (the old pair, or the new one once the receipt was
2357
+ written); the home's own copies may be half moved, which
2358
+ `moduleCopy.homeCopy` on its status row then says. Such a home is not
2359
+ started again: the remedy is to retire it and spawn it again. The upgrade
2360
+ takes its module set and each module's source from the receipt: a module
2361
+ only the home's record names refuses it.
2362
+ - **When the kernel has no copy.** A home whose receipt has no
2363
+ `composition` (a kernel from before this spawned it), or whose kernel
2364
+ copy of a module is gone, runs nothing of that module. The call is
2365
+ refused with a sentence that names the module; a read (`oats session
2366
+ inspect`, a status row, the sweep's plan, readiness) shows the home
2367
+ **unavailable** (`E_SESSION_UNAVAILABLE`; `running: null`,
2368
+ `runtimeState: "unreachable"`), never stopped; a hook of that module that
2369
+ an event has, and that cannot run, counts as a failed required hook, so a
2370
+ retire names it and removes the home only with `--force`. The home's own
2371
+ copy is never run in its place. The remedy is to retire the instance and
2372
+ spawn it again: with `--force` for a home whose receipt has no
2373
+ `composition` (none of its retire hooks can be identified), and for one
2374
+ that lacks the kernel's copy of a capability that has a retire hook; a
2375
+ plain retire where that capability has none.
2376
+ - **What `oats status` and drift report.** The drift rows (`modules`) read
2377
+ the home's own record of which modules it holds, from where and at which
2378
+ version, as for every home. A provider home's status row also carries
2379
+ `moduleCopy`: that the kernel runs its own copy (`runs: "kernel-copy"`),
2380
+ and whether the home's record of its modules is the kernel's
2381
+ (`homeCopy: "same" | "differs"`, with the modules that differ). That
2382
+ compares records, not files: `oats readiness --home` compares the files
2383
+ (`kernelCopies.differing`). Both are added, optional keys
2384
+ ([desktop-cli-api.md](desktop-cli-api.md)). After an upgrade both are the
2385
+ new version. After an upgrade that was interrupted between moving the
2386
+ home's copies and writing the receipt, drift can say `current` while the
2387
+ kernel still runs the earlier copy: `moduleCopy.homeCopy` then says
2388
+ `differs`, naming the modules.
2389
+
2390
+ Your own part, if you sandbox: **keep `<instances>/.oats-retirement/`
2391
+ unwritable from the session**, by the harness's shell and by its file tools
2392
+ alike, and **keep it readable, and its `modules/` executable**, from the
2393
+ session, at the same path: a hook records paths of its own files there for
2394
+ the harness to run (as `oats.core`'s launch hook hands Claude Code the
2395
+ script its hooks run), and the harness runs them inside the sandbox. The
2396
+ launch input names the directory in `protected` ([launch](#launch)). The
2397
+ directory holds the kernel's copies of the modules, the receipts (the
2398
+ composition above, the session's endpoint), the lifecycle claims and the
2399
+ kernel's records of provider commands in flight. A session that can write
2400
+ there can make the kernel run anything. The kernel cannot check this for
2401
+ you: it does not run your sandbox.
2402
+
2403
+ What this does not cover: other fields of `instance.json` still reach hooks
2404
+ and your commands (the recorded teams, the harness, the soul directory,
2405
+ `OATS_META`, and the recorded launch: its harness, its arguments and
2406
+ environment, and the launch arguments and environment names each
2407
+ capability's hooks contributed). Nothing here makes a provider's sandboxed
2408
+ mode a security boundary between an agent and the operator's account.
2409
+
2410
+ **For a capability's author.** In a provider home your hooks and commands
2411
+ run from the kernel's copy of your capability, not from
2412
+ `<home>/.oats/modules/<your capability>/`. Find the home by
2413
+ `OATS_INSTANCE_HOME`, never by your own location, and never write beside
2414
+ your own code: what your code writes belongs in the home. A file of your
2415
+ own that you find by your own location is the kernel's copy of it. When a
2416
+ hook hands such a path to the harness (as `oats.core`'s launch hook hands
2417
+ Claude Code the script its hooks run), the harness runs what the kernel
2418
+ keeps, which the agent cannot rewrite where the provider keeps that
2419
+ directory unwritable. The path changes at an upgrade (the copies move to a
2420
+ new store), so write it again at every launch, as a launch hook does.
2421
+
2422
+ A tmux home is unchanged, and why: its agent already runs unsandboxed as
2423
+ the operator, and can do directly whatever a module it rewrote could. Its
2424
+ receipt gains no key, the kernel keeps no copy of its modules, and they are
2425
+ run from the home as before.
2426
+
2427
+ Every Git the kernel runs over a provider home's trees, or over their
2428
+ repository, runs with the repository's hooks and its file monitor off
2429
+ (`-c core.fsmonitor=false -c core.hooksPath=/dev/null`): the reads and a
2430
+ retire, as for every home, and also the spawn's `git worktree add`, its
2431
+ rollback, and `oats worktree add` and `remove`.
2432
+
2433
+ ### Sandbox allowances (`sandboxDomains`, the launch input's `sandbox`)
2434
+
2435
+ A provider may run its harness in a sandbox. What an instance needs from
2436
+ outside that sandbox is decided by the kernel, from the deployment's
2437
+ configuration, and handed to the provider with every launch:
2438
+
2439
+ ```json
2440
+ "sandbox": { "domains": [ { "host": "app.example.org", "capability": "oats.aweb", "setting": "services" } ],
2441
+ "write": [ { "path": "/abs/deployment/.agents/events", "reason": "oats events" } ],
2442
+ "missing": [ { "capability": "oats.aweb", "setting": "services", "team": "ops:acme.example", "defaultTeam": false } ] }
2443
+ ```
2444
+
2445
+ - **`domains`** are exact hosts (`host` or `host:port`, lower case; never a
2446
+ wildcard, a scheme or a path), each with the capability and the setting
2447
+ that asked for it. **Only the capability that fills the instance's
2448
+ messaging, knowledge or tasks slot can ask**, and only through its
2449
+ manifest:
2450
+
2451
+ ```json
2452
+ "layer": "messaging",
2453
+ "sandboxDomains": [ { "setting": "services" }, { "setting": "registryHost", "optional": true } ]
2454
+ ```
2455
+
2456
+ Each line names one of the capability's own settings. Its value is a URL
2457
+ (its host is taken), a bare host, or a map from team id to one of those,
2458
+ of which only the entries of the instance's own teams are read (the teams
2459
+ a spawn preview shows for the soul). A value that is set and gives no plain
2460
+ host refuses the launch, `E_BACKEND_SANDBOX_HOST`, naming the capability
2461
+ and the setting. So does the line on a capability that fills none of the
2462
+ three slots: it is never dropped. `"optional": true` says the session
2463
+ works without that host.
2464
+
2465
+ A line may instead name a file: `{ "settingFile": "<setting>", "urls":
2466
+ "<JSON pointer>" }`. The setting's value is the path of a JSON file of the
2467
+ deployment, and each string at the pointer (one segment may be `*`: every
2468
+ key, every element) that is a URL or a git remote (`git@host:path`) gives
2469
+ its host. The file is the deployment's own: inside the deployment, never
2470
+ inside an instance home or a path the allowances make writable, reached
2471
+ through no symbolic link anywhere along its path (otherwise
2472
+ `E_BACKEND_SANDBOX_HOST`); a regular file with one name (a file that has a
2473
+ second hard link when it is read is not read; keep the file where a
2474
+ session cannot link or write it) of at most 64 KiB, strict JSON, at most
2475
+ 16 hosts. An absolute path may spell the deployment's own directory
2476
+ through a link; from the first place it enters the deployment, no link is
2477
+ allowed. A file that is missing or is none of that gives no host,
2478
+ is named in the answer and in readiness (`unread`), and the launch goes on.
2479
+ **A host of a general forge opens that whole forge to the agent**, not
2480
+ only the repository named: say so where you document your line.
2481
+ - **`write`** are exact absolute paths, the kernel's own, never a
2482
+ capability's: the deployment's events directory, where `oats instance
2483
+ attention` appends. The kernel creates each before your launch: an
2484
+ allowance on a path that does not exist does not let a sandboxed agent
2485
+ create it. Each is a real directory at exactly that path: one reached
2486
+ through a symbolic link refuses the launch (`E_BACKEND_SANDBOX_HOST`).
2487
+ - **`missing`** is always there, `[]` when nothing is missing: what a line
2488
+ names and the deployment's configuration does not hold. `team` is the id
2489
+ of a team of the instance with no entry in a map, or `null` for a setting
2490
+ with no value at all. `defaultTeam` is `true` on the row of the soul's
2491
+ default team and on a row with `team: null`, `false` on another team's.
2492
+ A row of an optional line carries `"optional": true`. The kernel adds no
2493
+ host for these and refuses nothing.
2494
+
2495
+ **Nothing else adds a host or a path:** not hook output, not an environment
2496
+ variable, not a launch argument, not a task. A setting given to one spawn
2497
+ (`oats spawn … --provider <capability> <setting>=…`) is such an argument: a
2498
+ spawn that gives a setting a `sandboxDomains` line names is refused
2499
+ (`E_BACKEND_SANDBOX_HOST`), so that no host comes from it and the next start
2500
+ does not quietly resolve another. The values come from the
2501
+ deployment's configuration as a spawn preview resolves it (the workspace,
2502
+ the deployment's own settings, the soul's payload), **never from a file in
2503
+ the instance home**, which a sandboxed agent can write.
2504
+
2505
+ **What the provider does with it** is its own rule, because only it knows
2506
+ whether it sandboxes this launch: widen the sandbox by exactly `domains` and
2507
+ `write`; **refuse a launch you would sandbox** when `missing` holds a row
2508
+ that is not optional and whose `defaultTeam` is `true` (the other rows are
2509
+ for your readiness: say what the agent cannot reach), or when `sandbox` is
2510
+ `{ "unavailable": "<why>" }`
2511
+ (below), with an `E_BACKEND_*` code; write nothing for a launch you do not
2512
+ sandbox. Answer those refusals in `check` too, which is handed the planned
2513
+ launch (`"launch": { "harness", "yolo", "args", "sandbox" }`, absent on a
2514
+ readiness read): the kernel asks it before any hook runs and before a
2515
+ restart stops anything.
2516
+
2517
+ **A start or a restart of an existing home** resolves the deployment's
2518
+ configuration again, for the home's soul, **without reaching any remote**:
2519
+ the workspace and each repository are read **as this host last read them**
2520
+ (the commits any `oats` command that reads the workspace last saw here, from
2521
+ this host's cache), and the deployment's own `oats-local.yaml` and lock as
2522
+ they are now. So a launch never waits on the network or fails with it; a
2523
+ setting a person or a setup command writes to `oats-local.yaml` reaches the
2524
+ home at its next launch; and a change committed to the workspace reaches it
2525
+ once a command on this host has read the workspace (`oats status`, a spawn
2526
+ preview). A soul disabled for spawning on
2527
+ this machine (`souls.disabled`) still has its homes' allowances. **Which
2528
+ deployment and which soul that is comes from where the home is, never from
2529
+ what is in it**: the deployment is the
2530
+ directory four levels above the home (`<deployment>/agents/<agent>/instances/<instance>`,
2531
+ as its real path) and must hold its own `oats-local.yaml`; the soul is the
2532
+ one the workspace offers whose agent directory is `<agent>`. The home's
2533
+ `instance.json` decides neither. Hosts are taken only for capabilities that
2534
+ are also the home's modules, as the home records them: that record can only
2535
+ leave a host of the deployment's list out, never add one. A slot's provider
2536
+ of the deployment that is not one of them adds none and is named (`skipped`,
2537
+ and a warning of the start). When
2538
+ the deployment's configuration cannot be resolved (a member repository that
2539
+ this host's cache does not hold, a soul the workspace no longer offers, two
2540
+ souls of the workspace that share the home's agent directory (the same bare
2541
+ name: rename one, or take one out of the workspace), a home whose real
2542
+ path is not under a deployment because its agents root is reached through a
2543
+ link), the launch input
2544
+ carries `"sandbox": { "unavailable": "<the cause>" }` in place of the three
2545
+ lists, and the kernel refuses nothing: a provider that would sandbox the
2546
+ session does.
2547
+
2548
+ `oats spawn --preview`, a start's and a restart's answer and `oats readiness
2549
+ --home` list each host with who asked for it and each path with its reason.
2550
+ A host taken from a map is listed with its team: a team the instance **may
2551
+ join** (one the deployment allows its soul), which is not to say it has
2552
+ joined it. The launch input carries no team.
2553
+ A tmux launch has no `sandbox`, and reads no `sandboxDomains`.
2554
+
2555
+ **A kernel from before session providers ignores `sandboxDomains`**: it
2556
+ neither refuses the manifest nor acts on the line. The line costs an older
2557
+ deployment nothing and gives it nothing.
2558
+
2559
+ ### Requirements by backend (`requires[].backends`)
2560
+
2561
+ A harness-package requirement (`requires: [{ harness, package, … }]`) is for
2562
+ the harness install on this host. A row may say which backends it is for:
2563
+ `"backends": ["tmux"]`, `["session-provider"]` (any session provider) or
2564
+ both. Without the key it applies to every backend, a provider's launch
2565
+ included, where it is probed on this host. It is a key of its own, never
2566
+ inside `when`, whose keys are the capability's settings. A kernel without
2567
+ `session-providers` knows no such key and applies the row to every launch:
2568
+ a package that uses `backends` raises its OATS floor to a kernel that lists
2569
+ the feature.
2570
+
2571
+ ### What the kernel does around the verbs
2572
+
2573
+ - **Stop stays stopped.** At every OATS stop (`oats instance stop`, a
2574
+ restart's stop, a retire, `oats host run`'s shutdown) the kernel records
2575
+ `stoppedAt` in the home's receipt **before** it calls `stop`, and a start
2576
+ clears it. While it is set, inspect answers stopped (`present: false`,
2577
+ `running: false`) without calling the provider, and every input (a
2578
+ person's `oats session input`, a scheduled wake, a client, the messaging
2579
+ broker) is refused `E_SESSION_NOT_RUNNING` before any call. A provider
2580
+ whose product restarts a session on its next input can rely on this.
2581
+ - **Hooks first.** The capabilities' spawn hooks (at a spawn) and launch
2582
+ hooks (at a start or a restart) run before `launch`, as before a tmux
2583
+ window, with `OATS_BACKEND`.
2584
+ - **Retire** records `stoppedAt`, calls `stop`, then runs the retire hooks
2585
+ and removes the home. The retire hook is not handed the endpoint: a
2586
+ provider that archives its session finds it by the home.
2587
+ - **A launch that fails** leaves the home as it was (stopped, or never
2588
+ launched; a spawn is rolled back). When its answer was lost, the kernel
2589
+ calls `stop` with `endpoint: null` first.
2590
+ - **A launch that was sent and never recorded.** The kernel writes in the
2591
+ home's receipt that a launch is being sent, right before it calls you, and
2592
+ takes that away when it has recorded your endpoint. A spawn or a start
2593
+ that is killed while you launch leaves it there: the home then reads as
2594
+ unknown, and the next stop, start or retire first calls `stop` with
2595
+ `endpoint: null`.
2596
+ - **Which stop it was** is on the home's stop receipt, never a field of
2597
+ yours: `oats host run`'s shutdown is a loss that the sweep resumes, an
2598
+ operator's stop is the intent that keeps the home down.
2599
+ - **A lost session is resumed through `input`.** A home whose session you
2600
+ answer as gone, and that OATS did not stop, is resumed by the sweep with
2601
+ one notice, and any other input to it is a resume too. The kernel counts
2602
+ each against the home's cap before it calls `input` (at most 3 in an hour,
2603
+ within one boot), refuses at the cap with `E_SESSION_NOT_RUNNING` without
2604
+ calling you, and first waits (a resume) or refuses (an input) while a
2605
+ process still works in the home. So an `inspect` precedes every `input` to
2606
+ a home OATS did not stop (the resume of a home stopped with the host sends
2607
+ its notice without one).
2608
+ An input you refuse (`ok: false`: nothing was sent) is not counted. One
2609
+ whose call fails or answers outside the rules stays counted: you may have
2610
+ restarted the session on it.
2611
+ - **`stop` is idempotent.** The kernel calls it again wherever it needs the
2612
+ session gone: an operator's stop of a home that is already stopped (how a
2613
+ stop you did not confirm is finished), a start of a stopped home before
2614
+ its launch, and after an input that crossed a stop (an input holds no
2615
+ claim: when a stop or a restart lands while one is being sent, the kernel
2616
+ asks you to stop that session again and does not deliver the input,
2617
+ whatever you answered to it, a refusal included). After a restart it asks
2618
+ that only when the new session has another endpoint: where you hand a
2619
+ restart the same locator again, that locator is the new session's, and the
2620
+ kernel tells the two apart by its own record of the start. An input that
2621
+ is in flight when a start begins its launch is such a crossing too.
2622
+ Answer `stopped: true` for a session that is already stopped.
2623
+ - **A spawn holds the home while you launch.** From before the home can be
2624
+ acted on until your launch's endpoint is recorded (or the spawn is undone),
2625
+ the spawn holds the home's lifecycle claim: a stop, a start or a retire
2626
+ that arrives meanwhile is refused as busy, never answered as if there were
2627
+ nothing to stop.
2628
+ - **Nothing of your endpoint leaves the host.** A status row carries the
2629
+ capability and, on its own host only, the endpoint's `threadId` when it
2630
+ is a string; the endpoint is on local inspect, spawn and start answers.
2631
+ `open` is relayed: make its `url` one a viewer may open, never your API's
2632
+ address off its host, and put no token in either.