@awebai/oats 0.26.0 → 0.27.1

package/docs/capabilities.md

@@ -47,7 +47,7 @@ A self-contained package has an `oats.json`:
   "requires": [
     { "command": "team-chat", "why": "send and receive messages" },
     {
-      "runtime": "pi",
+      "harness": "pi",
       "package": "npm:team-chat-pi",
       "why": "real-time push events in pi sessions"
     }
@@ -134,15 +134,15 @@ A self-contained package has an `oats.json`:
   the operator to clean up by hand.
 - `requires` declares what must exist before the capability works. Two kinds:
   - a **host command** (`command`), satisfied by a binary on `PATH`;
-  - a **runtime package** (`runtime` + `package`, optionally `marketplace`),
-    satisfied by that runtime's own package manager — `npm:@scope/name` for pi,
+  - a **harness package** (`harness` + `package`, optionally `marketplace`),
+    satisfied by that harness's own package manager — `npm:@scope/name` for pi,
     `plugin@marketplace` for Claude Code. It is raised only for deployments that use the named
-    runtime — a Claude-only deployment is never asked to install a pi package —
-    and is verified in the runtime's package list, never on `PATH`. A version
+    harness — a Claude-only deployment is never asked to install a pi package —
+    and is verified in the harness's package list, never on `PATH`. A version
     selector is allowed and ignored for identity, so `@latest` and a pinned
     version are one requirement.
-  A runtime package is **verified at spawn, never installed there**: installing
-  would mutate the operator's runtime configuration without asking, in the
+  A harness package is **verified at spawn, never installed there**: installing
+  would mutate the operator's harness configuration without asking, in the
   middle of a spawn. A missing, uninstalled or disabled package fails the spawn
   with the consent command that fixes it.
 - OATS never installs a host requirement silently. A missing host command is
@@ -250,7 +250,7 @@ team: [engineering, reviewers]
   discovery warning (`unmapped-team-label`, one per label naming its souls); a
   label not in `teams:` at all is the `E_TEAM_UNKNOWN` problem.
 
-## Exact runtime composition
+## Exact harness composition
 
 Every spawned instance receives:
 
@@ -334,7 +334,7 @@ existing manifests load, and change nothing.
 Hooks receive `OATS_EVENT`, `OATS_CAPABILITY`, `OATS_LAYER`, `OATS_INSTANCE`,
 `OATS_HOME`, `OATS_AGENT`, `OATS_SOUL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
 `OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, and `OATS_META`. A final JSON line may
-return `meta`, `brief`, `warning`, or runtime-specific `launch` arguments. A
+return `meta`, `brief`, `warning`, or harness-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
 
@@ -378,7 +378,7 @@ boundary — adding a new launch variable requires a visible manifest change
 `OATS_*`, `PI_AGENT_*`, kernel launch variables, and known shell/bootstrap/loader
 names are also rejected as defense in depth. The denylist includes current Node,
 JVM, .NET, Python, Perl, Ruby, Lua, PHP, ELF, and dyld surfaces, but is explicitly
-not the authority boundary: runtime bootstrap names are open-ended, so the
+not the authority boundary: harness bootstrap names are open-ended, so the
 manifest declaration and trust review enforce what an artifact may contribute.
 Two capabilities claiming the same name is an error even when their values
 match.
@@ -394,7 +394,7 @@ without a retire hook uses the standard retryable quarantine instead. Ordinary
 advisory hook execution failure itself contributes no environment.
 
 The environment prefix applies to the initial Pi or Claude process. `--no-launch`
-validates command preparation but has no runtime consumer. The fallback shell
+validates command preparation but launches no harness. The fallback shell
 after that process exits does not inherit command-scoped assignments, and OATS
 has no restart command or replay policy yet. The generated command is persisted
 as before; hooks must contribute locators, selectors, or broker endpoints—not

package/docs/capability-manifest.schema.json

@@ -117,17 +117,28 @@
             "additionalProperties": false
           },
           {
-            "title": "runtime package requirement",
-            "description": "A package that must be installed into a specific runtime's own package manager. Raised only for deployments using that runtime, satisfied by the runtime's package list rather than by PATH, and installed only with explicit consent.",
+            "title": "harness package requirement",
+            "description": "A package that must be installed into a specific harness's own package manager. Raised only for deployments using that harness, satisfied by the harness's package list rather than by PATH, and installed only with explicit consent. The harness is named by `harness` (0.27.0) or by `runtime`, its pre-0.27 name that released manifests use: exactly one of the two.",
             "type": "object",
             "required": [
-              "runtime",
               "package",
               "why"
             ],
+            "oneOf": [
+              { "required": ["harness"], "not": { "required": ["runtime"] } },
+              { "required": ["runtime"], "not": { "required": ["harness"] } }
+            ],
             "properties": {
+              "harness": {
+                "type": "string",
+                "enum": [
+                  "pi",
+                  "claude"
+                ]
+              },
               "runtime": {
                 "type": "string",
+                "description": "The pre-0.27 name of `harness`, accepted for released manifests.",
                 "enum": [
                   "pi",
                   "claude"
@@ -135,7 +146,7 @@
               },
               "package": {
                 "type": "string",
-                "description": "Source spec in that runtime's own naming: \"npm:@scope/name\" for pi, \"plugin@marketplace\" for Claude."
+                "description": "Source spec in that harness's own naming: \"npm:@scope/name\" for pi, \"plugin@marketplace\" for Claude."
               },
               "why": {
                 "type": "string"
@@ -155,7 +166,7 @@
               },
               "minVersion": {
                 "type": "string",
-                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the runtime's listing names; an older or absent manifest fails the requirement with the install remedy.",
+                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the harness's listing names; an older or absent manifest fails the requirement with the install remedy.",
                 "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+"
               },
               "ifInstalled": {

package/docs/configuration.md

@@ -37,7 +37,7 @@ souls:                                       # optional — souls this machine d
 
 launch-configs:                              # optional — named ways this host starts a harness
   personal:
-    runtime: claude
+    harness: claude
     executable: "./bin/claude-wrapper.sh"    # relative → against this deployment directory
     args: ["--verbose"]
     env:
@@ -55,7 +55,7 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `clones` | `<canonical repo key>: <absolute path>` — where a member's clone lives when it is not at `<deployment>/<member name>/`. Only a soul's **work target** (`work: worktree \| checkout`) needs a clone. Lookup order: `spawn --repo`, then this map (keys normalised through `parseRepoRef`, so any ref spelling of the same repo matches), then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`, since `agents/` is the instance root); none → `E_CLONE_MISSING`; a directory whose `origin` is another repo → `E_CLONE_MISMATCH`. |
 | `settings.<cap>.<key>` | Host-owned provider values the capability's manifest asks for — absolute paths, state roots, delivery modes. The workspace file **refuses** absolute paths; this is where they go. Merged into the capability's provider payload after the soul's own payload and before any `--provider` flag (see [three homes](workspaces.md#provider-payloads-have-three-homes)). |
 | `souls.disabled` | Soul names not run on this machine; reported by `oats sync` ("disabled here"). |
-| `launch-configs.<name>` | A named way to start a harness on this host (0.26.0; lead decision 2 — a spawn-time host choice, never a soul field): `runtime` (`pi` \| `claude` \| `codex`, required), `executable` (a bare name looked up on `PATH`, or a path — relative to this deployment directory), `args` (literal, no shell), `env` (a literal string, non-secret by contract and always redacted, or `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo`. Selected with `--launch-config <name>` on `oats spawn` and `oats session start \| restart`; explicit flags override its fields. Written by `oats launch-config set <name> --file <json>` / `remove <name>`, which rewrite only this block. Earlier kernels read `launch-configs:` from a scope's `oats-config.yaml`; 0.26.0 refuses it there with a message naming this move. |
+| `launch-configs.<name>` | A named way to start a harness on this host (0.26.0; lead decision 2 — a spawn-time host choice, never a soul field): `harness` (`pi` \| `claude` \| `codex`, required; named `runtime` before 0.27.0, which is still read with a `deprecated-runtime-name` warning), `executable` (a bare name looked up on `PATH`, or a path — relative to this deployment directory), `args` (literal, no shell), `env` (a literal string, non-secret by contract and always redacted, or `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo`. Selected with `--launch-config <name>` on `oats spawn` and `oats session start \| restart`; explicit flags override its fields. Written by `oats launch-config set <name> --file <json>` / `remove <name>`, which rewrite only this block. Earlier kernels read `launch-configs:` from a scope's `oats-config.yaml`; 0.26.0 refuses it there with a message naming this move. |
 
 ## Where it sits and how it is found
 

package/docs/conventions.md

@@ -48,8 +48,8 @@ Pi with ambient skill and context discovery disabled and the one instance path
 explicit; that exclusion is gone.)* Claude runs provider-native: it reads the
 instance's `.claude/skills` and `CLAUDE.md` symlinks, and the operator's own
 user and project configuration — skills, plugins, settings — stays in effect.
-Neither runtime gets a redirected config home.
-`composition.materialized.runtimePosture` in `instance.json` records what each
+Neither harness gets a redirected config home.
+`composition.materialized.harnessPosture` in `instance.json` records what each
 instance actually exposes. `oats-getting-started` is the sole pre-workspace
 ambient bootstrap.
 

package/docs/desktop-cli-api.md

@@ -28,7 +28,7 @@ refusals below remain authoritative.
 
 Optional features are negotiated from the probe's `features` array. Starting
 an existing home requires `session-start`; named launch configurations and
-runtime/permission overrides require `launch-config`; restarting a running
+harness/permission overrides require `launch-config`; restarting a running
 home also requires `session-restart`. Desktop checks the corresponding
 `remote` entries before offering these operations for a server. The router
 then probes the execution host before sending a mutation. An absent feature
@@ -48,6 +48,63 @@ no progress prose (progress goes to stderr):
 - success (exit 0): `{"schemaVersion":1,"ok":true,"result":{...}}`
 - failure (nonzero exit): `{"schemaVersion":1,"ok":false,"error":{"code":"...","message":"..."}}`
 
+Either may also carry `"warnings":[…]` (0.27.0+), present only when there is
+something to say. The one warning so far is `deprecated-runtime-name` (see
+[the harness rename](#the-harness-rename-feature-harness-oats-0270)). `oats status
+--json`, whose document is not an envelope, carries the same `warnings` beside
+its `problems`. In text mode the warning is one `oats: warning: …` line on stderr.
+
+## The harness rename (feature `harness`, OATS 0.27.0)
+
+What starts an instance (pi, claude or codex) is its **harness**. 0.27.0 renames
+the kernel's `runtime` to `harness` everywhere it means that:
+
+- Outputs speak only the new names.
+- Every input written before 0.27.0 still works. The rule is read either,
+  write new: the old spelling is read as the new one, and the next write
+  records the new one.
+- A command that read an old spelling answers **one** warning:
+  `{"code":"deprecated-runtime-name","key":"runtime","replacement":"harness","sources":[…],"message":"…"}`.
+  `sources` names each place it read the old spelling (a flag, a file and its
+  key, a home).
+- A pair that disagrees is refused rather than guessed, for example
+  `--harness pi --runtime claude`, or both keys with different values.
+- A later release drops the old spellings.
+
+Gate on the feature `harness`. A kernel without it speaks the old names: the
+routed commands (`--server`) already translate for such a host, sending
+`--runtime` and `runtime` keys to it and reading its `runtimes` list.
+
+| Surface | Before 0.27.0 | 0.27.0 | Old spelling still accepted? |
+|---|---|---|---|
+| `oats version --json` | `runtimes: [pi, claude, codex]` | `harnesses: [...]`, feature `harness` | **Dropped**: no `runtimes` alias; gate on the feature |
+| Flag on `spawn` (and `--preview`), `session start`/`restart`, `launch-config preview`, and their `--server` forms | `--runtime <h>` | `--harness <h>` | Yes, with the warning (the okf 2.1.5 harvest worker passes `--runtime` to spawn). Both flags disagreeing → `E_BAD_ARGS` |
+| `oats status --json`: `agents[]` rows (soul default) and `agents[].instances[]` rows | `runtime` | `harness` | Output only |
+| `oats status --json`: instance rows' `composition.materialized` | `runtimePackages`, `runtimePosture` | `harnessPackages`, `harnessPosture` | Output only |
+| `oats inspect --json` `souls[]` rows, remote roster rows | `runtime` | `harness` | Output only; a pre-0.27 host's `runtime` rows are read as `harness` |
+| `oats inspect --home --json` `instance` | `runtime` | `harness` | Output only |
+| The launch plan's package check (`launch-config preview` `problems[]`) | `runtime-packages` | `harness-packages` | Output only |
+| Soul `soul.yaml` (member souls and capability-defined agents) | `runtime:` | `harness:` | Yes, **without** a warning: released capabilities (oats.aweb 1.13.1) ship `runtime:`, and the operator cannot fix a provider's file. Both, disagreeing → `E_BAD_MANIFEST` |
+| `oats-local.yaml` `launch-configs.<name>` | `runtime:` | `harness:` | Yes, with the warning. Both, disagreeing → `E_WORKSPACE_SCHEMA`. `launch-config set` writes `harness` (a `runtime` in its `--file` definition too) |
+| `launch-config list/preview --json` rows and `selection` | `runtime` | `harness` | Output only |
+| Home `instance.json` | `runtime`; launch recipe `launch` version 1 `{runtime}` | `harness`; recipe version **2** `{harness}` | Yes, with the warning naming the home: a 0.26.0 home inspects, starts, restarts and retires; its next start or restart records the new names |
+| `oats spawn … --preview` decision | `effective.runtime` | `effective.harness` | Output only. The revision digests the key names, so a decision previewed by a 0.26 kernel is `E_DECISION_STALE` at apply (with the fresh decision) |
+| `spawn`/`session` results, `spawned` event `data` | `runtime` | `harness` | Output only |
+| Schedule definitions (`schedule add/update --spec-json`, stored jobs, `schedule list`) | `runtime` | `harness` | Yes, with the warning. A stored job is read in the new name and saved in it next time. Both, disagreeing → `E_SCHEDULE_INVALID` (a stored job: invalid on its own) |
+| Schedule run records (`lastRun`, `recentRuns`) | `startedRuntime` | `startedHarness` | Output; a 0.26.0 record's `startedRuntime` is still read |
+| Error codes | `E_UNSUPPORTED_RUNTIME`, `E_RUNTIME_PACKAGE`, `E_RUNTIME_RESOURCE_MISSING` | `E_UNSUPPORTED_HARNESS`, `E_HARNESS_PACKAGE`, `E_HARNESS_RESOURCE_MISSING` | Output only |
+| Hook environment (spawn and launch hooks) | `OATS_RUNTIME`, `OATS_PREVIOUS_RUNTIME` | `OATS_HARNESS`, `OATS_PREVIOUS_HARNESS` | Both are set, with the same values, for released hooks |
+| Capability manifest `requires[]` harness package | `runtime` | `harness` | Yes, **without** a warning (a provider's file); a row naming both is refused |
+| Package verification `loadedBy` | `runtime-discovery` | `harness-discovery` | Output only |
+
+Unchanged, because they do not name the harness: the session endpoint
+vocabulary (`runtimeAuthority`, `runtimeState`/`runtimeError` in liveness,
+`E_RUNTIME_ENDPOINT_UNKNOWN`, `E_RUNTIME_AUTHORITY_MISMATCH`,
+`E_RUNTIME_QUIESCE_FAILED`); `capabilityRuntime`; the retirement baseline's
+`runtime`; oats.okf's `harvest-runtime` setting; and the kernel's
+"runtime-neutral" design. Hook stdin carries no `launch.runtime` (no 0.26 hook
+emitter wrote it).
+
 ## Inspect, readiness and operation run on the workspace model (`operationsApi: 2`, `soulsApi: 2`, `readinessApi: 2`, OATS 0.26.0)
 
 On a workspace deployment (an `oats-local.yaml` in reach of `--dir`), and for
@@ -121,7 +178,7 @@ payload the spawn recorded for a home, or the resolution computes for a soul.
  "subject":{"kind":"instance","instance":"release-manager-x","home":"/w/agents/release-manager/instances/release-manager-x","soul":"release-manager"},
  "workspace":{"key":"github.com/northwind/agents","name":null,"deployment":"/w","commit":"461b9c24…","standalone":false},
  "souls":[{"soulsApi":2,"name":"release-manager","repoKey":"github.com/northwind/agents","commit":"461b9c24…","team":"engineering",
-   "kind":null,"path":null,"description":"Cuts, verifies and announces platform releases.","work":"worktree","runtime":null,"model":null,
+   "kind":null,"path":null,"description":"Cuts, verifies and announces platform releases.","work":"worktree","harness":null,"model":null,
    "declarations":{"requires":null,"defaults":null,"knowledge":{"owns":"release-manager","reads":["platform-engineer"]},"teams":null,"resources":null,"children":null,
                    "capabilities":{"nw-release-tooling":{"from":"here"},"nw-deploy":{"from":"package"}}},
    "declarationProblems":[],
@@ -138,7 +195,7 @@ payload the spawn recorded for a home, or the resolution computes for a soul.
     "operations":[{"name":"inspect","kind":"view","command":"inspect","context":"home","description":"…","args":[],"argv":["okf","inspect"],"available":true,"reason":null}]}],
  "knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"inspect","kind":"view","available":true,"reason":null}]},
  "instance":{"home":"/w/agents/release-manager/instances/release-manager-x","instance":"release-manager-x","agent":"release-manager",
-   "runtime":"pi","model":null,"yolo":null,"launched":false,"createdAt":"<iso>","resolution":"7217670b…",
+   "harness":"pi","model":null,"yolo":null,"launched":false,"createdAt":"<iso>","resolution":"7217670b…",
    "soulDir":"/w/agents/release-manager/souls/461b9c24929c",
    "instructions":{"file":"/w/agents/release-manager/instances/release-manager-x/AGENTS.md","text":"…","truncated":false,
                    "sources":[{"source":"kernel:instance-boundary","file":"…"},{"source":"capability:oats.okf","file":"…/.oats/modules/oats.okf/injects/okf.md"}]}},
@@ -471,7 +528,7 @@ home's removal, so a retired instance's `retired` event is still readable).
 
 ```json
 {"eventsApi":1,"instance":"dev-1","home":"/abs/home","count":7,"returned":7,"truncated":false,
- "events":[{"eventsApi":1,"at":"<iso>","instance":"dev-1","home":"/abs/home","producer":"kernel","kind":"spawned","data":{"agent":"dev","work":"worktree","branch":"agents/dev-1","runtime":"claude","model":null,"parentInstance":null,"relation":null,"launched":true}},
+ "events":[{"eventsApi":1,"at":"<iso>","instance":"dev-1","home":"/abs/home","producer":"kernel","kind":"spawned","data":{"agent":"dev","work":"worktree","branch":"agents/dev-1","harness":"claude","model":null,"parentInstance":null,"relation":null,"launched":true}},
            {"…":"launched | restarted | stopped | stop-refused | retire-planned | worktree-retained | worktree-removed | branch-deleted | retired | child-spawn-refused"}],
  "lastEvent":{"kind":"stopped","at":"<iso>","producer":"kernel"},
  "waitingOnYou":null,
@@ -628,12 +685,12 @@ unchecked, echoed a stored `definition.id` without checking it, and named a
 The Spawn modal's fields are backed by the kernel's own decision, taken **before
 any side effect**: `oats spawn <agent> [same flags as a real spawn] --preview --json`
 runs every preflight a spawn runs (placement, composition, resources,
-executable, runtime packages, child-spawn policy) and returns what the spawn
+executable, harness packages, child-spawn policy) and returns what the spawn
 *would* do — then returns without creating a home, branch or worktree.
 
 ```json
 {"spawnPreviewApi":1,"preview":true,"agent":"dev","kind":"persistent","instance":"dev-fix-login","home":"/abs/agents/dev/instances/dev-fix-login",
- "repo":"/abs/repo","work":"worktree","runtime":"claude","model":"opus","modelSource":"explicit","launchConfig":null,"yolo":false,"backend":"tmux",
+ "repo":"/abs/repo","work":"worktree","harness":"claude","model":"opus","modelSource":"explicit","launchConfig":null,"yolo":false,"backend":"tmux",
  "branch":"agents/dev-fix-login","base":{"ref":"HEAD","oid":"<oid>"},"worktree":"/abs/agents/dev/instances/dev-fix-login/work",
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"…"}}},
  "executable":"/abs/bin/claude","capabilities":["oats.core"],"skills":["oats-operate","oats-souls"],"task":"…"}
@@ -650,7 +707,7 @@ executable, runtime packages, child-spawn policy) and returns what the spawn
   the worktree **from that exact oid**.
 - **Model**: `model`/`modelSource` are the resolved selection. Omitting
   `--model` **inherits** the launch configuration's or soul's preference;
-  `--model @native-default` is the explicit "use the runtime's own default"
+  `--model @native-default` is the explicit "use the harness's own default"
   (`modelSource: "native default (explicit)"`). These are different requests
   and the UI must not relabel one as the other.
 - **Policy**: `policy.childSpawns` is what this instance will record (soul
@@ -722,11 +779,11 @@ the pre-fix marker and is never accepted for dispatch.
 - **Bounded preflight**: every native probe a preview runs (`pi --list-models`,
   `pi list`, `claude plugin list`) shares ONE budget (20 s default), runs in its
   own process group and is group-killed on timeout; `preflight {status:
-  complete|timeout, budgetMs, elapsedMs}` says which. A hanging runtime cannot
+  complete|timeout, budgetMs, elapsedMs}` says which. A hanging harness CLI cannot
   hang a preview.
 - **Confirmed apply contract** (0.24.10+, feature `spawn-apply-2`,
   `spawnApplyApi: 1`) — what a GUI may promise at "Confirm spawn":
-  - `decision` gains **`effective {repo, work, runtime, model, launchConfig,
+  - `decision` gains **`effective {repo, work, harness, model, launchConfig,
     yolo, backend, childSpawns, relation{kind, anchor{instance, agentsRoot}}}`**
     and `revision` hashes placement + effective. An inherited default that would
     change what launches (the soul's model edited between preview and apply,
@@ -1342,7 +1399,7 @@ are described in [the operations contract](design/operations-contract.md).
 
 ```text
 oats session start --home /absolute/home [--server id] \
-  [--launch-config name] [--runtime pi|claude|codex] \
+  [--launch-config name] [--harness pi|claude|codex] \
   [--model id] [--yolo|--no-yolo] --json
 oats session restart --home /absolute/home [the same options] --json
 ```
@@ -1366,7 +1423,7 @@ oats launch-config list [--dir /scope | --home /home | --soul name --agents-root
 oats launch-config set name --file /private/definition.json [--keep-env] --dir /scope --json
 oats launch-config remove name --dir /scope --json
 oats launch-config preview (--home /home | --soul name --agents-root /scope/agents --dir /scope) \
-  [--launch-config name] [--runtime runtime] [--model id] [--yolo|--no-yolo] --json
+  [--launch-config name] [--harness harness] [--model id] [--yolo|--no-yolo] --json
 ```
 
 All accept `--server id`. Scope edits follow the registration; inspection and
@@ -1375,7 +1432,7 @@ is serialized to SSH stdin and read on the host with `--file -`; the local
 filename is never passed to the server as though it existed there.
 
 The list result supplies `context`, `selected` and `configurations`. Each
-configuration has a name, runtime, executable, literal argument array,
+configuration has a name, harness, executable, literal argument array,
 environment, model, permission choice and declaring `source`. Environment
 literals appear as `{ "redacted": true }`; references appear as
 `{ "fromEnv": "VARIABLE_NAME" }`. Optional executable/model/yolo fields can be
@@ -1410,7 +1467,7 @@ See [launch configuration syntax](configuration.md) and
 | `warnings` | string[]        | non-fatal warnings (always an array)       |
 | `tmux`     | {session,window} \| null | tmux target                       |
 
-Additional informative fields: `repo`, `runtime`, `model`, `parent`,
+Additional informative fields: `repo`, `harness`, `model`, `parent`,
 `sibling` (explicit sibling cluster link when a root-level sibling relation
 was declared, else null), `relation` (`child`/`sibling`/`parent` when a
 relation was declared at spawn, else null), `spawnOrigin`, `attach`.

package/docs/desktop-instance-start.md

@@ -9,7 +9,7 @@ The Desktop roster is the place to return to it:
 - The hierarchy's action popover offers **Start…** for a stopped instance.
 - An unknown status is shown as unknown, not as permission to launch another process.
 
-The Start/Restart dialog names the existing instance, runtime and host. Choose
+The Start/Restart dialog names the existing instance, harness and host. Choose
 a named launch configuration or keep the recorded launch. Without a selected
 configuration, the harness can also be changed directly. A named configuration
 fixes its harness; model and permission choices can override its defaults.
@@ -53,7 +53,7 @@ Use the server's workspace to manage configurations defined on that server.
 Desktop sends `POST /api/start/<instance>?ws=…&home=…` (and `server=…` for a
 remote instance). The backend resolves that exact roster identity and calls
 `oats session start --home <absolute-home> [--server <id>] [--model <model>] --json`.
-Launch choices add `--launch-config`, `--runtime` or `--yolo`/`--no-yolo`.
+Launch choices add `--launch-config`, `--harness` or `--yolo`/`--no-yolo`.
 Restart uses `POST /api/restart/<instance>?ws=…&home=…` and the single kernel
 command `oats session restart` with the same selectors and choices.
 Configuration inspection and editing use `POST /api/launch-configs?ws=…`,

package/docs/first-team.md

@@ -103,7 +103,7 @@ oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run t
 oats status
 ```
 
-`--runtime pi|claude|codex` picks the harness; complete any native folder
+`--harness pi|claude|codex` picks the harness; complete any native folder
 trust or authentication prompt in the printed session. The instance home is
 `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
 `.oats/modules/<cap>/` and `.agents/skills/<cap>/` are the copied capabilities;

package/docs/implementation.md

@@ -162,7 +162,7 @@ instance homed inside a repository with its own `.claude/skills` sees those
 too. Project *settings* — hooks, plugins, permissions, custom agents — resolve
 from the instance home rather than from ancestors.
 
-Codex is available with `--runtime codex`. It starts in the instance home,
+Codex is available with `--harness codex`. It starts in the instance home,
 reads `AGENTS.md` and `.agents/skills` natively, and receives `TASK.md` as its
 initial prompt. User configuration, approval policy, ancestor instructions and
 ambient skill sources remain native. Worktrees are already below the instance
@@ -175,8 +175,8 @@ The Desktop model field accepts a native id without using Pi's model catalog.
 This launch support does not supply an aweb channel for Codex: agents can use
 `aw` from their home, with automatic wake delivery tracked separately.
 
-All runtimes record what they actually expose in `instance.json` under
-`composition.materialized.runtimePosture`: the OATS-composed set, what is
+All harnesses record what they actually expose in `instance.json` under
+`composition.materialized.harnessPosture`: the OATS-composed set, what is
 curtailed, and what remains ambient. The deviation from strict composition is
 auditable rather than implied.
 

package/docs/oats-local.schema.json

@@ -42,10 +42,11 @@
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["runtime"],
+        "anyOf": [{ "required": ["harness"] }, { "required": ["runtime"] }],
         "properties": {
-          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness family this configuration starts; it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
-          "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the runtime's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved against the deployment directory (where this oats-local.yaml lives) when relative. Checked to exist and be executable before any start; never executed just to probe it." },
+          "harness": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness this configuration starts (named `runtime` before 0.27.0); it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
+          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "deprecated": true, "description": "The pre-0.27 name of `harness`, still read (a deprecation warning); both, disagreeing, are refused. `oats launch-config set` writes `harness`." },
+          "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the harness's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved against the deployment directory (where this oats-local.yaml lives) when relative. Checked to exist and be executable before any start; never executed just to probe it." },
           "args": { "type": "array", "items": { "type": "string" }, "description": "Extra arguments, each passed literally (no shell interpretation): native configuration files or profiles go here as ordinary arguments." },
           "env": {
             "type": "object",
@@ -58,7 +59,7 @@
             },
             "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
           },
-          "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's runtime; overrides the soul default when this configuration is selected." },
+          "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
           "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." }
         }
       }

package/docs/packages.md

@@ -74,7 +74,7 @@ members:
 packages:
   oats.framework: v1.1.3
   oats.okf: v2.1.5
-  oats.aweb: v1.13.1
+  oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }
@@ -286,5 +286,5 @@ says so.
 replacement (`details.removed` / `details.replacement` in `--json`). There is
 no installed-capability directory, no config template adoption, no host
 requirement installer. A manifest's `requires` still describes what must exist
-on the host (runtime packages are verified at spawn; host commands are the
+on the host (harness packages are verified at spawn; host commands are the
 operator's to install).

package/docs/release-notes/v0.27.0.md

@@ -0,0 +1,100 @@
+# OATS 0.27.0
+
+What starts an instance (pi, claude or codex) is now called its **harness**
+everywhere the kernel used to say `runtime`: in flags, configuration, records,
+JSON and error codes. Nothing already written stops working. The rule is read
+either, write new: every spelling from before 0.27.0 is still read, and the
+next write records the new one. A command that reads an old spelling answers
+one `deprecated-runtime-name` warning, and a later release drops the old
+spellings. See [Upgrading from 0.26](#upgrading-from-026).
+
+## Changed
+
+- **runtime → harness.** [The Desktop CLI API](../desktop-cli-api.md#the-harness-rename-feature-harness-oats-0270)
+  has the complete table. In short:
+  - Flags: `--harness` replaces `--runtime` on `spawn` (and `--preview`),
+    `session start|restart` and `launch-config preview`, including their
+    `--server` forms. `--runtime` is still accepted, with the warning. The
+    two given with different values are refused (`E_BAD_ARGS`).
+  - `oats-local.yaml`: a launch configuration names `harness:`. `runtime:` is
+    still read, with the warning. Both, disagreeing, is a schema error
+    (`E_WORKSPACE_SCHEMA`). `oats launch-config set` writes `harness`.
+  - Schedules: a spawn job names `harness`. A job stored with `runtime` is
+    read as `harness`, with the warning, and saved in the new name next time.
+    Both, disagreeing, makes that job invalid (`E_SCHEDULE_INVALID`).
+    `lastRun`/`recentRuns` record `startedHarness` (was `startedRuntime`).
+  - Homes: `instance.json` records `harness`, and the launch recipe is version
+    **2** (`harness`; version 1 said `runtime`). A home spawned by 0.26.0 is
+    read in the new names, with the warning naming the home. It inspects,
+    starts, restarts and retires as before, and its next start or restart
+    records the new names.
+  - `soul.yaml` names `harness:`. `runtime:` is still read, **without** a
+    warning, because released capabilities ship it (oats.aweb 1.13.1's agents)
+    and an operator cannot fix a provider's file. Both, disagreeing:
+    `E_BAD_MANIFEST`. The same holds for a capability manifest's
+    `requires[]` harness package (`harness`, or `runtime`, never both).
+  - Hooks get `OATS_HARNESS` and `OATS_PREVIOUS_HARNESS` beside
+    `OATS_RUNTIME` and `OATS_PREVIOUS_RUNTIME`, with the same values.
+  - JSON outputs speak only the new names:
+    - `oats version --json` lists `harnesses` (no `runtimes`) and the feature
+      `harness`;
+    - `harness` replaces `runtime` in the status, inspect, spawn, preview,
+      session, launch-config, schedule and event documents;
+    - `harnessPackages` and `harnessPosture` replace `runtimePackages` and
+      `runtimePosture` in `composition.materialized`;
+    - the launch plan's package check (`launch-config preview` `problems[]`)
+      is `harness-packages`, and package verification's `loadedBy` is
+      `harness-discovery`.
+  - Error codes: `E_UNSUPPORTED_HARNESS`, `E_HARNESS_PACKAGE` and
+    `E_HARNESS_RESOURCE_MISSING` replace `E_UNSUPPORTED_RUNTIME`,
+    `E_RUNTIME_PACKAGE` and `E_RUNTIME_RESOURCE_MISSING`.
+  - JSON envelopes may carry `warnings: [...]`, only when there is something
+    to say. `oats status --json` carries it beside `problems`. In text mode,
+    a warning is one `oats: warning: …` line on stderr.
+  - Routed commands (`--server`) speak each host's own vocabulary. A host
+    without the `harness` feature (0.26.x and older) is sent `--runtime` and
+    `runtime` keys, and its `runtimes` list and `runtime` roster rows are read
+    as harnesses.
+  - A spawn decision previewed by a 0.26 kernel is `E_DECISION_STALE` at a
+    0.27 apply (the revision covers the key names), with the fresh decision
+    attached.
+  - Unchanged, because they do not name the harness: the session endpoint's
+    `runtimeAuthority`, `runtimeState` and `runtimeError`, the
+    `E_RUNTIME_ENDPOINT_*`, `E_RUNTIME_AUTHORITY_MISMATCH` and
+    `E_RUNTIME_QUIESCE_FAILED` codes, `capabilityRuntime`, the retirement
+    baseline, and oats.okf's `harvest-runtime` setting.
+
+## Desktop
+
+- **The Desktop speaks the harness names** on a kernel that declares feature
+  `harness` (`--harness`, `harness`/`harnesses`), and the old names on released
+  0.25.8–0.26.x kernels. It reads either spelling everywhere, shows only the
+  harness the kernel reports (no `pi` default for an instance that doesn't say),
+  and accepts kernels `>=0.25.8 <0.28.0`.
+- **Core capabilities name their origin** (soul, workspace or team) on the soul
+  page and the instance sidebar, on a kernel with feature `layers-from`.
+- The unused "the workspace's team settings" origin label is gone (0.26.0's
+  teams amendment K stopped emitting it).
+
+## Fixed
+
+- **0.26.0's notes said per-workspace personal teams need undeployed aweb
+  server support.** The aweb service (0.8.13 and later) and CLI (1.36.8 and
+  later) already carry personal enrollment; what remains is oats.aweb 1.15
+  adopting it. The bundled oats.aweb is still 1.13.1 (the personal team only);
+  the team verbs come with oats.aweb 1.14.1 in a 0.27.x patch.
+
+## Upgrading from 0.26
+
+Nothing to do. Old spellings keep working with a `deprecated-runtime-name`
+warning, and a later release drops them. To stop the warning:
+
+- write `harness:` for `runtime:` in `oats-local.yaml` launch configurations
+  (or re-save them with `oats launch-config set`);
+- pass `--harness` for `--runtime` in scripts;
+- re-save any schedule the warning names (`oats schedule update`). A stored
+  job is also rewritten on its next save.
+
+A 0.26.0 home stops warning after its next start or restart. A Desktop that
+gates on the `harness` feature reads the new names; an older Desktop reads
+`runtimes` and `runtime` and needs its update.

package/docs/release-notes/v0.27.1.md

@@ -0,0 +1,29 @@
+# OATS 0.27.1
+
+## Changed
+
+- **oats.aweb 1.14.2 is bundled and pinned** (was 1.13.1): **joining teams
+  beyond the personal one now works.** An instance joins the eligible teams it
+  is given at spawn (`--provider oats.aweb join=<labels>`) or later with
+  `oats aweb join <labels>` / the Desktop's Teams controls, and leaves with
+  `oats aweb leave <labels>`. Each joined team gets its own identity under the
+  instance home. Joined teams **poll** (their mail is read between tasks); live
+  receive for joined teams is planned for oats.aweb 1.15. Joining needs
+  **aw 1.36.12 or later** (older aw answers `E_TEAM_AW_FLOOR`; the primary
+  identity still mints). A leave removes the local identity only after aweb
+  confirms the membership is released, so a failed leave can be retried.
+  Retire leaves every joined team before releasing the primary identity.
+- The framework workspace (`oats-workspace.yaml`) pins oats.aweb v1.14.2.
+- Skip oats.aweb 1.14.0 and 1.14.1 (tagged, never pinned by an OATS release): their binding check answered a `teams` key that OATS rejects, so `oats readiness` showed messaging unknown; 1.14.2 fixes it, and 1.14.0's joins were refused by aw.
+
+## Known limitations
+
+- The bundled oats.okf is still 2.1.5: its harvest worker spawns with `--runtime`, so each harvest answers one `deprecated-runtime-name` warning on 0.27.x. It's harmless; oats.okf 2.1.6 passes `--harness`.
+
+- A per-workspace personal team still needs oats.aweb 1.15 (the aweb service
+  and CLI already carry personal enrollment); until then "personal" is the
+  person's active aweb team.
+
+## Upgrading from 0.27.0
+
+- To join teams: upgrade aw to 1.36.12 or later (and restart the host's wake daemon), then `oats sync` so the deployment's lock takes oats.aweb 1.14.2. Existing instances keep their primary identity; they join teams with `oats aweb join <labels>`.

package/docs/schedules.md

@@ -39,7 +39,7 @@ see [Captured definitions](#captured-definitions-removed-in-026).
 ## Kinds
 
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
-  repo?, backend?, purpose?, task, runtime?, model?, yolo?, wake?}` — every
+  repo?, backend?, purpose?, task, harness?, model?, yolo?, wake?}` — every
   due minute launches one disposable instance of `agent` with the same
   options `oats spawn` takes. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
@@ -136,7 +136,7 @@ running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
 ## What a run reports
 
 `launched` (spawn or command returned), `active` (the instance is running;
-a home whose retirement is pending still counts, its runtime may be alive),
+a home whose retirement is pending still counts, its harness may be alive),
 `ended` (its home is gone), `stopped` (home present, nothing running: needs
 attention, never removed for you), `launch-failed`, `unknown`, and for wake
 jobs `delivered`, `started` or `skipped`. The kernel never claims a task
@@ -159,13 +159,13 @@ unknown; check the roster and the host by hand, then
 slot (or `remove --force` forgets the job).
 
 A wake job that starts a stopped home holds a launch slot while that
-runtime is starting, active, retiring or unobservable, and releases it when
-the runtime is proven stopped (the session start receipt's exit marker for
+harness is starting, active, retiring or unobservable, and releases it when
+the harness is proven stopped (the session start receipt's exit marker for
 that launch, or a home that no longer has a session) or the home is gone.
 A persistent home that outlives its process does not keep a slot. Delivering
 a message to a home that is already running takes no slot. The host tick
 observes every registered scope first, then admits due jobs in one
-host-wide order, least recently launched first (only an actual runtime
+host-wide order, least recently launched first (only an actual harness
 launch counts; a skipped or pending job keeps its place at the front), so
 one frequent job in one scope cannot keep the only slot forever. An invalid
 or malformed definition is reported on that job and the rest of the tick
@@ -177,7 +177,7 @@ execution identity, kind and target cannot
 change; cron, tz and enabled can. A cold wake persists its slot before
 the session start runs and keeps it on any start exception, whatever its code
 (the kernel can refuse while recording, after the session exists); the next
-observation releases it once the runtime is proven stopped or absent, one tick
+observation releases it once the harness is proven stopped or absent, one tick
 at worst.
 `remove` refuses while the job's instance is still tracked (`--force`
 forgets the job without stopping anything). Retiring an instance removes the