@awebai/oats 0.69.24 → 0.70.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 (38) hide show
  1. package/bin/oats.mjs +62 -6
  2. package/docs/capabilities.md +374 -18
  3. package/docs/capability-manifest.schema.json +30 -0
  4. package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
  5. package/docs/design/2026-11-21-human-ids-contract.md +342 -0
  6. package/docs/design/README.md +2 -0
  7. package/docs/desktop-cli-api.md +111 -4
  8. package/docs/execution-targets.md +24 -1
  9. package/docs/implementation.md +26 -3
  10. package/docs/release-notes/v0.70.0.md +155 -0
  11. package/docs/release-notes/v0.70.1.md +70 -0
  12. package/docs/schedules.md +42 -3
  13. package/docs/souls-and-instances.md +12 -0
  14. package/docs/trust-model.md +8 -1
  15. package/docs/upgrading.md +16 -5
  16. package/lib/automation-scope.mjs +1 -1
  17. package/lib/capability-show.mjs +10 -1
  18. package/lib/core.mjs +408 -66
  19. package/lib/home-integrity.mjs +329 -0
  20. package/lib/hook-env.mjs +2 -1
  21. package/lib/instance-events.mjs +32 -5
  22. package/lib/instance-git.mjs +9 -0
  23. package/lib/instance-inspect.mjs +64 -10
  24. package/lib/instance-listing.mjs +5 -1
  25. package/lib/instance-resolution.mjs +85 -2
  26. package/lib/instance-upgrade.mjs +170 -14
  27. package/lib/remote.mjs +33 -1
  28. package/lib/retire-admission.mjs +7 -0
  29. package/lib/sandbox-allowances.mjs +329 -0
  30. package/lib/schedule.mjs +6 -4
  31. package/lib/servers.mjs +10 -1
  32. package/lib/session-inspect.mjs +20 -75
  33. package/lib/session-providers.mjs +68 -19
  34. package/lib/session-receipt.mjs +93 -0
  35. package/lib/upgrade-state.mjs +6 -1
  36. package/lib/worktree-hooks.mjs +18 -2
  37. package/lib/worktree.mjs +21 -7
  38. package/package.json +1 -1
@@ -664,7 +664,14 @@ preview (only a preview-aware hook does, below); on a real run
664
664
  backend the instance launches on, `tmux` or the name of a
665
665
  [session provider](#session-providers-sessionproviders). A spawn that launches
666
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 worktree hook also gets the tree
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
668
675
  variables of [The worktree event](#the-worktree-event).
669
676
 
670
677
  A spawn or launch hook also gets `OATS_HARNESS_EXECUTABLE`, for every harness
@@ -1036,7 +1043,10 @@ into the capture hooks and the capture service's unit. In the third case
1036
1043
 
1037
1044
  `OATS_EVENT=upgrade` lets a staged destination package module adopt the state
1038
1045
  of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
1039
- 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:
1040
1050
 
1041
1051
  - `OATS_UPGRADE_PHASE`: `plan` or `apply`;
1042
1052
  - `OATS_META`: the old recorded `capabilityMeta[capability]`;
@@ -1045,7 +1055,10 @@ the staged new copy, with the usual lifecycle environment plus:
1045
1055
  - `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
1046
1056
  - `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
1047
1057
  directory. Register host artifacts against this path, never the staging path,
1048
- 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).
1049
1062
 
1050
1063
  In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
1051
1064
  `{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
@@ -1267,7 +1280,8 @@ claim and holds no scheduled wake. The board is in
1267
1280
  **The Claude Code emitter.** For a Claude instance, oats.core's spawn and
1268
1281
  launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
1269
1282
  into the home's project settings, `<home>/.claude/settings.json`. Each one
1270
- 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
1271
1285
  `oats instance waiting set|clear --producer oats.core`:
1272
1286
 
1273
1287
  | Claude Code event | Matcher | Action |
@@ -1538,8 +1552,9 @@ home whose oats.core moves to it is upgraded rather than respawned. The
1538
1552
  hook that runs is the destination's, so this covers homes spawned on any
1539
1553
  earlier oats.core, with or without the emitter. oats.core records no
1540
1554
  capability metadata, and its settings entries name the module copy's path,
1541
- `.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
1542
- 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
1543
1558
  `capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
1544
1559
  `false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
1545
1560
  refuses any other value as state it cannot vouch for, with the remedy
@@ -1707,7 +1722,8 @@ spawn's fail-closed hooks.
1707
1722
  ```
1708
1723
 
1709
1724
  **Invocation.** The kernel runs the command's script with `node`, from the
1710
- 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
1711
1727
  deployment's verified module store for `--soul`. The script must resolve inside
1712
1728
  the module and be a regular file. The command's words after the script are
1713
1729
  passed as arguments; no shell is involved.
@@ -1988,6 +2004,7 @@ claims, the refusals and the JSON answers. What an operator sees is in
1988
2004
  "sessionProviders": {
1989
2005
  "bb": {
1990
2006
  "description": "Runs the agent as a bb thread",
2007
+ "wire": "1.3",
1991
2008
  "harnesses": ["claude"],
1992
2009
  "commands": { "launch": "session-launch", "inspect": "session-inspect", "input": "session-input",
1993
2010
  "stop": "session-stop", "inspectMany": "session-inspect-many" }
@@ -2005,6 +2022,17 @@ claims, the refusals and the JSON answers. What an operator sees is in
2005
2022
  - **`harnesses`** lists the harnesses the provider runs (1 to 16 names). A
2006
2023
  spawn or a start on another one is refused `E_BACKEND_HARNESS`.
2007
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.
2008
2036
  - No other key.
2009
2037
 
2010
2038
  **Containment.** A malformed `sessionProviders` never refuses the capability:
@@ -2023,8 +2051,10 @@ the instance being spawned. Two of them declaring the same name is
2023
2051
 
2024
2052
  ### The call
2025
2053
 
2026
- Every call runs the **home's own copy** of the capability:
2027
- `node <home>/.oats/modules/<capability>/<script> <args>`. **Its working
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
2028
2058
  directory is not the home** (it is the filesystem root): read the home from
2029
2059
  the request (`input.home`) or `OATS_INSTANCE_HOME`, and leave
2030
2060
  nothing of the call's own running in the home (the session's processes work
@@ -2038,7 +2068,7 @@ retires the home, and a provider's call must never be one of them.
2038
2068
  `OATS_META`, `OATS_CLI_BIN` and the rest, with `OATS_EVENT=session` and
2039
2069
  `OATS_BACKEND=<name>`.
2040
2070
  - **stdin:** one JSON request,
2041
- `{ "schemaVersion": 1, "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
2071
+ `{ "schemaVersion": 1, "wire": "1.3", "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
2042
2072
  - **stdout:** exactly one JSON document of at most 1 MiB, the same five header
2043
2073
  keys echoed, then `"ok": true, "result": { … }` or
2044
2074
  `"ok": false, "error": { "code": "E_…", "message": "…" }`. No other key.
@@ -2088,7 +2118,10 @@ In:
2088
2118
  "pathPrepend": ["/abs/home/.oats/bin"],
2089
2119
  "args": ["--flag", "value"],
2090
2120
  "promptFile": "/abs/home/TASK.md",
2091
- "previous": null }
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"] }
2092
2125
  ```
2093
2126
 
2094
2127
  - `env` is every variable the launch sets, in the order a tmux launch sets
@@ -2115,6 +2148,35 @@ In:
2115
2148
  just before, always (a restart's stop, once more for a home OATS had
2116
2149
  stopped, and for a session you answered as gone too: an input that reached
2117
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.)
2118
2180
 
2119
2181
  **A provider that cannot carry an env entry, an argument or `unset`
2120
2182
  refuses, naming it** (`E_BACKEND_LAUNCH_ENV`, `E_BACKEND_LAUNCH_ARG`). It
@@ -2162,7 +2224,8 @@ an `http` or `https` `url` of at most 2000, without credentials.
2162
2224
  `{ "homes": [ { "home", "instance", "endpoint" } ] }`, at most 200. Out:
2163
2225
  `{ "results": [ … ] }`, one per home in the same order, each an inspect
2164
2226
  result or `{ "error": { "code", "message" } }`. `oats status` calls it once
2165
- per group of homes that share the capability's module copy (same digest),
2227
+ per group of homes that share the capability's module copy (the same
2228
+ source, as each home's receipt records it),
2166
2229
  the provider and the settings; the call's environment is the group's first
2167
2230
  home's. Each entry is judged as one `inspect` answer would be. A batch that
2168
2231
  fails or is not one result per home, and an entry that is neither a result
@@ -2203,7 +2266,12 @@ started by a killed spawn is ever stopped.
2203
2266
  ### check (optional)
2204
2267
 
2205
2268
  The provider's readiness. In: `{ "home": "/abs/home" | null, "soul": "<name>" | null, "settings": { … } }`:
2206
- a home, or, before any home exists, a soul. Out:
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:
2207
2275
  `{ "status": "ready" | "needs-configuration" | "authorization-required" | "unavailable", "problems": [ { "code", "message" } ], "warnings": [ { "code", "message" } ] }`
2208
2276
  (`warnings` optional; no problem on `ready`). Say where a credential comes
2209
2277
  from, never print it.
@@ -2212,11 +2280,299 @@ from, never print it.
2212
2280
  binding check's answer has: for a home, its own backend's, required; for a
2213
2281
  soul, each provider its capabilities offer, not required (the soul can
2214
2282
  launch on tmux).
2215
- - **The kernel asks it right before every launch** (a spawn's, a start's, a
2216
- restart's before its stop). A status other than `ready` refuses the launch:
2217
- with the first problem's code when that is an `E_BACKEND_*` code, else
2218
- `E_BACKEND_NOT_READY`, the message carrying your problems. A check that
2219
- fails or answers outside these words is not ready.
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
+ - **A preview asks it too, with the same planned launch**, so that a launch
2292
+ you would refuse does not read clean in its preview. `check` must only
2293
+ read, and must answer for a home that is not there:
2294
+ - A spawn's preview (`oats spawn --preview`) hands you the home's
2295
+ **planned path, which does not exist yet**, `trees` with its one planned
2296
+ tree and `protected` by name, none of them made. Treat an absent home
2297
+ and absent files as absent, not as an error. Your environment is the
2298
+ spawn's too; `OATS_SOUL` and `OATS_LEVEL` may name directories that are
2299
+ not there yet. Your script then runs from
2300
+ your package's tree in the deployment's module store, as it does for
2301
+ `oats readiness --soul`, not from a home's copy. A refusal fails the
2302
+ preview with the code the spawn would be refused with, and nothing is
2303
+ created. You are given what is left of the preview's budget, and never
2304
+ more than the spawn gives its check. A provider that lives in a member module, which runs only from
2305
+ a spawned home, is not asked: the preview says so in its `warnings`.
2306
+ - A launch's preview (`oats launch-config preview --home`) hands you the
2307
+ home as a start would. A refusal is a failed `backend` item in its
2308
+ `preflight`.
2309
+
2310
+ ### What the kernel trusts in a provider home
2311
+
2312
+ A provider may run its harness in a sandbox that still lets the agent write
2313
+ its own home. The kernel that runs the home's hooks and your commands runs
2314
+ outside any sandbox, as the operator, while that agent runs. So, for a home
2315
+ on a session provider, **the kernel runs nothing that is in the home, and
2316
+ takes no capability setting from it**:
2317
+
2318
+ - **The kernel keeps its own copy of the home's modules, outside the home,**
2319
+ at `<instances>/.oats-retirement/modules/<hash of the home>/<store>/<capability>/`,
2320
+ beside the home's receipt. The spawn makes it from the copies it
2321
+ materialised, once, before it asks you anything and before any hook of
2322
+ the spawn runs. Every lifecycle hook
2323
+ and worktree hook, every one of your commands, every capability's
2324
+ readiness check and every command or operation dispatched in the home is
2325
+ run from that copy, and the home's manifests are read there. The copies
2326
+ under `<home>/.oats/modules/` stay where they are, for the agent and its
2327
+ harness (its skills, what the harness runs inside its sandbox). The kernel
2328
+ never runs them, and reads nothing it acts on from them, so nothing the agent does to them,
2329
+ at rest or while the kernel is running a command, changes what the kernel
2330
+ runs. (A copy in the home that is checked and then run can be exchanged
2331
+ between the two by the session that writes the home. That is why the
2332
+ kernel keeps a copy instead of checking the home's.)
2333
+ - **The receipt records the home's composition.** The home's receipt
2334
+ (`<instances>/.oats-retirement/baselines/`) carries `composition`: which
2335
+ store holds the kernel's copies, which modules the home has and where each
2336
+ came from, and the capability rows the spawn resolved from the deployment
2337
+ (each capability's settings, their origins, its level, and its hook
2338
+ commands, which name the kernel's copy).
2339
+ - **A capability's settings and hook commands are the receipt's.**
2340
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, which hooks a capability has and
2341
+ the command of each come from the receipt's rows, never from
2342
+ `instance.json` (`capabilityRuntime`, `capabilities`, `providers`, the
2343
+ settings recorded with each launch contribution) nor from a rollback
2344
+ marker. A capability the home's record adds is no capability of the
2345
+ home, at a launch, at a retire and at an upgrade alike.
2346
+ - **Retirement removes the kernel's copy** with the home, and so does the
2347
+ rollback of a spawn that fails. A home that is kept (a retire that could
2348
+ not finish, a quarantined spawn) keeps its copy, so that its cleanup can
2349
+ run. A spawn takes away whatever an earlier home left at its path, the
2350
+ receipt and the copies, before anything reads them.
2351
+ - **An upgrade** (`oats instance upgrade`) makes the kernel's copies for the
2352
+ upgraded home in a new store beside the old one, before any upgrade hook
2353
+ runs: each moved module from the upgrade's staged copy, once that is found
2354
+ to be the one the upgrade verified against the lock, and every other
2355
+ module from the kernel's own current copy. Each upgrade hook runs from the
2356
+ kernel's copy. The receipt is then written once, naming the new store and
2357
+ the new rows together, and keeping the pair it replaced as `previous`.
2358
+ **An upgrade that fails or is interrupted before that write leaves the old
2359
+ copy and the old capability rows, together**; after it, the new ones.
2360
+ There is no moment at which the rows name one version and the kernel runs
2361
+ another. A store is removed only once a move is complete, after the
2362
+ receipt's write: the one before the previous. A move that fails after
2363
+ that write and is rolled back puts the earlier receipt back whole, from
2364
+ the kernel's own memory of it and never from a copy kept in the home,
2365
+ with the stores it names still there.
2366
+ - **An undo** (`oats instance upgrade --undo`) writes the receipt once,
2367
+ naming the previous store and the previous rows again; the newer store is
2368
+ removed after that write. The hook an undo runs is the kernel's previous
2369
+ copy's. The home's own copies are restored from what the home kept, as
2370
+ for every home: they are the agent's. One previous move is kept, so one
2371
+ undo is possible.
2372
+ - **An upgrade that was interrupted is not resumed** for such a home: its
2373
+ journal is in the home, where the agent can write. The kernel's side is
2374
+ whole either way (the old pair, or the new one once the receipt was
2375
+ written); the home's own copies may be half moved, which
2376
+ `moduleCopy.homeCopy` on its status row then says. Such a home is not
2377
+ started again: the remedy is to retire it and spawn it again. The upgrade
2378
+ takes its module set and each module's source from the receipt: a module
2379
+ only the home's record names refuses it.
2380
+ - **When the kernel has no copy.** A home whose receipt has no
2381
+ `composition` (a kernel from before this spawned it), or whose kernel
2382
+ copy of a module is gone, runs nothing of that module. The call is
2383
+ refused with a sentence that names the module; a read (`oats session
2384
+ inspect`, a status row, the sweep's plan, readiness) shows the home
2385
+ **unavailable** (`E_SESSION_UNAVAILABLE`; `running: null`,
2386
+ `runtimeState: "unreachable"`), never stopped; a hook of that module that
2387
+ an event has, and that cannot run, counts as a failed required hook, so a
2388
+ retire names it and removes the home only with `--force`. The home's own
2389
+ copy is never run in its place. The remedy is to retire the instance and
2390
+ spawn it again: with `--force` for a home whose receipt has no
2391
+ `composition` (none of its retire hooks can be identified), and for one
2392
+ that lacks the kernel's copy of a capability that has a retire hook; a
2393
+ plain retire where that capability has none.
2394
+ - **What `oats status` and drift report.** The drift rows (`modules`) read
2395
+ the home's own record of which modules it holds, from where and at which
2396
+ version, as for every home. A provider home's status row also carries
2397
+ `moduleCopy`: that the kernel runs its own copy (`runs: "kernel-copy"`),
2398
+ and whether the home's record of its modules is the kernel's
2399
+ (`homeCopy: "same" | "differs"`, with the modules that differ). That
2400
+ compares records, not files: `oats readiness --home` compares the files
2401
+ (`kernelCopies.differing`). Both are added, optional keys
2402
+ ([desktop-cli-api.md](desktop-cli-api.md)). After an upgrade both are the
2403
+ new version. After an upgrade that was interrupted between moving the
2404
+ home's copies and writing the receipt, drift can say `current` while the
2405
+ kernel still runs the earlier copy: `moduleCopy.homeCopy` then says
2406
+ `differs`, naming the modules.
2407
+
2408
+ Your own part, if you sandbox: **keep `<instances>/.oats-retirement/`
2409
+ unwritable from the session**, by the harness's shell and by its file tools
2410
+ alike, and **keep it readable, and its `modules/` executable**, from the
2411
+ session, at the same path: a hook records paths of its own files there for
2412
+ the harness to run (as `oats.core`'s launch hook hands Claude Code the
2413
+ script its hooks run), and the harness runs them inside the sandbox. The
2414
+ launch input names the directory in `protected` ([launch](#launch)). The
2415
+ directory holds the kernel's copies of the modules, the receipts (the
2416
+ composition above, the session's endpoint), the lifecycle claims and the
2417
+ kernel's records of provider commands in flight. A session that can write
2418
+ there can make the kernel run anything. The kernel cannot check this for
2419
+ you: it does not run your sandbox.
2420
+
2421
+ What this does not cover: other fields of `instance.json` still reach hooks
2422
+ and your commands (the recorded teams, the harness, the soul directory,
2423
+ `OATS_META`, and the recorded launch: its harness, its arguments and
2424
+ environment, and the launch arguments and environment names each
2425
+ capability's hooks contributed). Nothing here makes a provider's sandboxed
2426
+ mode a security boundary between an agent and the operator's account.
2427
+
2428
+ **For a capability's author.** In a provider home your hooks and commands
2429
+ run from the kernel's copy of your capability, not from
2430
+ `<home>/.oats/modules/<your capability>/`. Find the home by
2431
+ `OATS_INSTANCE_HOME`, never by your own location, and never write beside
2432
+ your own code: what your code writes belongs in the home. A file of your
2433
+ own that you find by your own location is the kernel's copy of it. When a
2434
+ hook hands such a path to the harness (as `oats.core`'s launch hook hands
2435
+ Claude Code the script its hooks run), the harness runs what the kernel
2436
+ keeps, which the agent cannot rewrite where the provider keeps that
2437
+ directory unwritable. The path changes at an upgrade (the copies move to a
2438
+ new store), so write it again at every launch, as a launch hook does.
2439
+
2440
+ A tmux home is unchanged, and why: its agent already runs unsandboxed as
2441
+ the operator, and can do directly whatever a module it rewrote could. Its
2442
+ receipt gains no key, the kernel keeps no copy of its modules, and they are
2443
+ run from the home as before.
2444
+
2445
+ Every Git the kernel runs over a provider home's trees, or over their
2446
+ repository, runs with the repository's hooks and its file monitor off
2447
+ (`-c core.fsmonitor=false -c core.hooksPath=/dev/null`): the reads and a
2448
+ retire, as for every home, and also the spawn's `git worktree add`, its
2449
+ rollback, and `oats worktree add` and `remove`.
2450
+
2451
+ ### Sandbox allowances (`sandboxDomains`, the launch input's `sandbox`)
2452
+
2453
+ A provider may run its harness in a sandbox. What an instance needs from
2454
+ outside that sandbox is decided by the kernel, from the deployment's
2455
+ configuration, and handed to the provider with every launch:
2456
+
2457
+ ```json
2458
+ "sandbox": { "domains": [ { "host": "app.example.org", "capability": "oats.aweb", "setting": "services" } ],
2459
+ "write": [ { "path": "/abs/deployment/.agents/events", "reason": "oats events" } ],
2460
+ "missing": [ { "capability": "oats.aweb", "setting": "services", "team": "ops:acme.example", "defaultTeam": false } ] }
2461
+ ```
2462
+
2463
+ - **`domains`** are exact hosts (`host` or `host:port`, lower case; never a
2464
+ wildcard, a scheme or a path), each with the capability and the setting
2465
+ that asked for it. **Only the capability that fills the instance's
2466
+ messaging, knowledge or tasks slot can ask**, and only through its
2467
+ manifest:
2468
+
2469
+ ```json
2470
+ "layer": "messaging",
2471
+ "sandboxDomains": [ { "setting": "services" }, { "setting": "registryHost", "optional": true } ]
2472
+ ```
2473
+
2474
+ Each line names one of the capability's own settings. Its value is a URL
2475
+ (its host is taken), a bare host, or a map from team id to one of those,
2476
+ of which only the entries of the instance's own teams are read (the teams
2477
+ a spawn preview shows for the soul). A value that is set and gives no plain
2478
+ host refuses the launch, `E_BACKEND_SANDBOX_HOST`, naming the capability
2479
+ and the setting. So does the line on a capability that fills none of the
2480
+ three slots: it is never dropped. `"optional": true` says the session
2481
+ works without that host.
2482
+
2483
+ A line may instead name a file: `{ "settingFile": "<setting>", "urls":
2484
+ "<JSON pointer>" }`. The setting's value is the path of a JSON file of the
2485
+ deployment, and each string at the pointer (one segment may be `*`: every
2486
+ key, every element) that is a URL or a git remote (`git@host:path`) gives
2487
+ its host. The file is the deployment's own: inside the deployment, never
2488
+ inside an instance home or a path the allowances make writable, reached
2489
+ through no symbolic link anywhere along its path (otherwise
2490
+ `E_BACKEND_SANDBOX_HOST`); a regular file with one name (a file that has a
2491
+ second hard link when it is read is not read; keep the file where a
2492
+ session cannot link or write it) of at most 64 KiB, strict JSON, at most
2493
+ 16 hosts. An absolute path may spell the deployment's own directory
2494
+ through a link; from the first place it enters the deployment, no link is
2495
+ allowed. A file that is missing or is none of that gives no host,
2496
+ is named in the answer and in readiness (`unread`), and the launch goes on.
2497
+ **A host of a general forge opens that whole forge to the agent**, not
2498
+ only the repository named: say so where you document your line.
2499
+ - **`write`** are exact absolute paths, the kernel's own, never a
2500
+ capability's: the deployment's events directory, where `oats instance
2501
+ attention` appends. The kernel creates each before your launch: an
2502
+ allowance on a path that does not exist does not let a sandboxed agent
2503
+ create it. Each is a real directory at exactly that path: one reached
2504
+ through a symbolic link refuses the launch (`E_BACKEND_SANDBOX_HOST`).
2505
+ - **`missing`** is always there, `[]` when nothing is missing: what a line
2506
+ names and the deployment's configuration does not hold. `team` is the id
2507
+ of a team of the instance with no entry in a map, or `null` for a setting
2508
+ with no value at all. `defaultTeam` is `true` on the row of the soul's
2509
+ default team and on a row with `team: null`, `false` on another team's.
2510
+ A row of an optional line carries `"optional": true`. The kernel adds no
2511
+ host for these and refuses nothing.
2512
+
2513
+ **Nothing else adds a host or a path:** not hook output, not an environment
2514
+ variable, not a launch argument, not a task. A setting given to one spawn
2515
+ (`oats spawn … --provider <capability> <setting>=…`) is such an argument: a
2516
+ spawn that gives a setting a `sandboxDomains` line names is refused
2517
+ (`E_BACKEND_SANDBOX_HOST`), so that no host comes from it and the next start
2518
+ does not quietly resolve another. The values come from the
2519
+ deployment's configuration as a spawn preview resolves it (the workspace,
2520
+ the deployment's own settings, the soul's payload), **never from a file in
2521
+ the instance home**, which a sandboxed agent can write.
2522
+
2523
+ **What the provider does with it** is its own rule, because only it knows
2524
+ whether it sandboxes this launch: widen the sandbox by exactly `domains` and
2525
+ `write`; **refuse a launch you would sandbox** when `missing` holds a row
2526
+ that is not optional and whose `defaultTeam` is `true` (the other rows are
2527
+ for your readiness: say what the agent cannot reach), or when `sandbox` is
2528
+ `{ "unavailable": "<why>" }`
2529
+ (below), with an `E_BACKEND_*` code; write nothing for a launch you do not
2530
+ sandbox. Answer those refusals in `check` too, which is handed the planned
2531
+ launch (`"launch": { "harness", "yolo", "args", "sandbox" }`, absent on a
2532
+ readiness read): the kernel asks it before any hook runs and before a
2533
+ restart stops anything.
2534
+
2535
+ **A start or a restart of an existing home** resolves the deployment's
2536
+ configuration again, for the home's soul, **without reaching any remote**:
2537
+ the workspace and each repository are read **as this host last read them**
2538
+ (the commits any `oats` command that reads the workspace last saw here, from
2539
+ this host's cache), and the deployment's own `oats-local.yaml` and lock as
2540
+ they are now. So a launch never waits on the network or fails with it; a
2541
+ setting a person or a setup command writes to `oats-local.yaml` reaches the
2542
+ home at its next launch; and a change committed to the workspace reaches it
2543
+ once a command on this host has read the workspace (`oats status`, a spawn
2544
+ preview). A soul disabled for spawning on
2545
+ this machine (`souls.disabled`) still has its homes' allowances. **Which
2546
+ deployment and which soul that is comes from where the home is, never from
2547
+ what is in it**: the deployment is the
2548
+ directory four levels above the home (`<deployment>/agents/<agent>/instances/<instance>`,
2549
+ as its real path) and must hold its own `oats-local.yaml`; the soul is the
2550
+ one the workspace offers whose agent directory is `<agent>`. The home's
2551
+ `instance.json` decides neither. Hosts are taken only for capabilities that
2552
+ are also the home's modules, as the home records them: that record can only
2553
+ leave a host of the deployment's list out, never add one. A slot's provider
2554
+ of the deployment that is not one of them adds none and is named (`skipped`,
2555
+ and a warning of the start). When
2556
+ the deployment's configuration cannot be resolved (a member repository that
2557
+ this host's cache does not hold, a soul the workspace no longer offers, two
2558
+ souls of the workspace that share the home's agent directory (the same bare
2559
+ name: rename one, or take one out of the workspace), a home whose real
2560
+ path is not under a deployment because its agents root is reached through a
2561
+ link), the launch input
2562
+ carries `"sandbox": { "unavailable": "<the cause>" }` in place of the three
2563
+ lists, and the kernel refuses nothing: a provider that would sandbox the
2564
+ session does.
2565
+
2566
+ `oats spawn --preview`, a start's and a restart's answer and `oats readiness
2567
+ --home` list each host with who asked for it and each path with its reason.
2568
+ A host taken from a map is listed with its team: a team the instance **may
2569
+ join** (one the deployment allows its soul), which is not to say it has
2570
+ joined it. The launch input carries no team.
2571
+ A tmux launch has no `sandbox`, and reads no `sandboxDomains`.
2572
+
2573
+ **A kernel from before session providers ignores `sandboxDomains`**: it
2574
+ neither refuses the manifest nor acts on the line. The line costs an older
2575
+ deployment nothing and gives it nothing.
2220
2576
 
2221
2577
  ### Requirements by backend (`requires[].backends`)
2222
2578
 
@@ -266,6 +266,7 @@
266
266
  "additionalProperties": false,
267
267
  "properties": {
268
268
  "description": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
269
+ "wire": { "type": "string", "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}$", "description": "The version of the session-provider wire this provider speaks (docs/capabilities.md, The call). A kernel calls only a provider that declares its own version: one that declares another, or none (a provider from before the key, wire 1.2), is refused E_BACKEND_WIRE, naming both." },
269
270
  "harnesses": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$" }, "description": "The harnesses this backend runs. A spawn or a start on another is refused E_BACKEND_HARNESS before anything is created or stopped." },
270
271
  "commands": {
271
272
  "type": "object",
@@ -353,6 +354,34 @@
353
354
  "additionalProperties": {"$ref":"#/$defs/OptionalHook"},
354
355
  "description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
355
356
  },
357
+ "sandboxDomains": {
358
+ "description": "Sandbox allowances (docs/capabilities.md, Sandbox allowances): the hosts a session provider may add to its harness's sandbox for an instance whose messaging, knowledge or tasks slot this capability fills. Each entry names one of this capability's settings; the kernel reads the setting's value from the deployment's configuration (never from an instance home) and takes its host: a URL's host, a bare host, or, for a map from team id to one of those, the hosts of the instance's own teams. Only a capability that declares `layer` may carry the key, and only the capability that fills the slot contributes: on any other capability a session-provider launch is refused (E_BACKEND_SANDBOX_HOST), never the line dropped. A tmux launch does not read it. A kernel from before session providers ignores the key. One rule this schema does not express: a setting is named by ONE line (two lines for the same setting, of either form, refuse the launch).",
359
+ "type": "array",
360
+ "minItems": 1,
361
+ "maxItems": 16,
362
+ "items": {
363
+ "oneOf": [
364
+ {
365
+ "type": "object",
366
+ "required": ["setting"],
367
+ "properties": {
368
+ "setting": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is a URL, a bare host, or a map from team id to one of those." },
369
+ "optional": { "type": "boolean", "description": "true: the session works without this host. A value the deployment does not hold is then reported and is no reason for a session provider to refuse a launch." }
370
+ },
371
+ "additionalProperties": false
372
+ },
373
+ {
374
+ "type": "object",
375
+ "required": ["settingFile", "urls"],
376
+ "properties": {
377
+ "settingFile": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is the path of a JSON file of the deployment (never inside an instance home; a regular file reached through no symbolic link, at most 64 KiB, strict JSON)." },
378
+ "urls": { "type": "string", "pattern": "^(/([^/~]|~[01])+){1,16}$", "not": { "pattern": "/\\*(/.*)?/\\*(/|$)" }, "maxLength": 400, "description": "A JSON pointer into that file, of which at most one segment may be `*` (every key of an object, every element of an array): each string there that is a URL or a git remote gives its host, at most 16 hosts a file." }
379
+ },
380
+ "additionalProperties": false
381
+ }
382
+ ]
383
+ }
384
+ },
356
385
  "settings": {
357
386
  "type": "object",
358
387
  "description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",
@@ -436,5 +465,6 @@
436
465
  "additionalProperties": false
437
466
  }
438
467
  },
468
+ "dependentRequired": { "sandboxDomains": ["layer"] },
439
469
  "additionalProperties": false
440
470
  }
@@ -39,6 +39,7 @@ state, in what order it writes, and what happens when two things cross.
39
39
  | Record | Where | Who can write it | What it holds |
40
40
  |---|---|---|---|
41
41
  | **Receipt** | `<instances>/.oats-retirement/baselines/<hash of the home>.json`, `runtime` | the kernel; outside the home | the authority: `launched`, `backend`, `provider`, `endpoint`, `stoppedAt`, `launchSent` |
42
+ | **Composition** | the same receipt, `composition`; and the kernel's own copy of the home's modules, `<instances>/.oats-retirement/modules/<hash of the home>/<store>/` | the kernel (a spawn, and an upgrade's swap); outside the home | what the kernel runs of the home: its own copy of every module, and the home's capability rows (settings, hook commands that name that copy). No verb of this page writes it; every one runs the home's hooks and its provider's commands from it, never from the home ([What the kernel trusts in a provider home](../capabilities.md#what-the-kernel-trusts-in-a-provider-home)). A retire removes the copy with the home |
42
43
  | **Record** | `<home>/instance.json` | the kernel; inside the home, so the agent can | a copy for readers: `launched`, `backend`, `session {provider, endpoint}`, `startId` |
43
44
  | **Stop receipt** | `<home>/.oats-stop.json` | the kernel; inside the home | which stop the last one was, for the current `startId`: an operator's, or the host's (`resume: true, reason: "host-stop"`) |
44
45
  | **Claim** | `<instances>/.oats-retirement/claims/<name>.lock` | the kernel; outside the home | which lifecycle verb acts on the home now, and its process |
@@ -115,7 +116,7 @@ before its home can be acted on):
115
116
 
116
117
  | # | Step | Record written | State after |
117
118
  |---|---|---|---|
118
- | 1 | What can refuse: the plan, the launch hooks, the provider's `check` with the planned launch. (Three checks run right before step 4: the home's roots, the kernel's shim, the host run's admission. One that refuses there leaves the home as it then is: stopped by step 3, or as before the verb) | none | unchanged |
119
+ | 1 | What can refuse, in this order: a module of the home the kernel holds no copy of (it runs its own copy of each, and reads their manifests there); the provider's `check` with the planned launch (the harness, yolo, the sandbox allowances, the home's trees and the launch configuration's own arguments), **before any hook runs**; then the plan and the launch hooks. A spawn or a start its backend refuses runs no hook. (Three checks run right before step 4: the home's roots, the kernel's shim, the host run's admission. One that refuses there leaves the home as it then is: stopped by step 3, or as before the verb) | none | unchanged |
119
120
  | 2 | If unsettled: for a home launched before, the provider's `stop {endpoint: E}` (not confirmed: `E_SESSION_STOP_FAILED`); then settle | see Settling | planned or stopped |
120
121
  | 3 | If launched before: stop the session at `E`. A restart of *running* whose session is there records `stoppedAt` and the stop receipt first (the stop rule). A start or a restart of *stopped* asks the provider's `stop {endpoint: E}` again; not confirmed is `E_SESSION_STOP_FAILED`, nothing started. (*Running* whose session is gone: step 4) | receipt, stop receipt (a restart of a session that is there) | stopped, or running-and-gone |
121
122
  | 4 | **Mark**: receipt `launchSent: t` (and `launched: true` from planned), then the record's `launched: true` from planned. Then, for *running* whose session is gone, the provider's `stop {endpoint: E}`, and nothing is recorded of it (so a stop that is not confirmed leaves a lost home lost, not stopped as by an operator): not confirmed is `E_SESSION_STOP_FAILED`, the mark taken back (6b), nothing started. After the mark, because an input holds no claim: see the crossings | receipt, then record | sent or resent |
@@ -226,6 +227,7 @@ orders of "A launch" and of the stop rule:
226
227
  | during a launch the provider refused, between the record and the receipt of its unmarking | sent | settles (there is nothing to stop) |
227
228
  | during a spawn, after its launch's outcome and before its last write of the record | resent (the mark is kept to that write) | settles: `stop {E}`, then the launch's; the home is stopped |
228
229
  | during a spawn's rollback, between its record and its receipt | unsettled: the launch still marked, the record already planned (not compared) | settles |
230
+ | during a spawn, before its record (while the provider's `check` is asked, or its hooks run) | not a home of the table yet: a receipt, where there is one, says planned, and the record is the one its files were composed with. A read answers that it is being spawned (`E_SESSION_UNAVAILABLE`), never that its records disagree | as for any spawn that ended before its record: the kernel has no verb for it yet (not this change's) |
229
231
  | during a spawn, between the planned record and its last receipt | planned (the receipt was written before the record) | acts on it |
230
232
  | during a resume of a home stopped with the host, after its notice | stopped with the host; its session may run again | the sweep sends the notice again; a stop or a start asks `stop {E}` |
231
233
  | during that resume, after `stoppedAt` was cleared | running, with the host's stop receipt left | acts on a running home; a later loss of that start is a loss like any other, counted (a stop receipt says the host's stop only beside a receipt that says stopped), and a later stop removes that receipt before it records its own |