@awebai/oats 0.23.2 → 0.24.0

package/docs/design/2026-09-18-captured-pi-host.md

@@ -0,0 +1,205 @@
+# Captured Pi print host — kernel implementation boundary
+
+This increment implements an explicit SDK host, not a reinterpretation of a Pi
+CLI executable. It is not interactive/plugin/private-provider qualification.
+The host is packaged by the existing `bin/` and `lib/` file inclusion; no new
+package metadata or mandatory model capability is introduced.
+
+## Selection and native behavior
+
+Choose the physical installed `bin/oats-pi-sdk-host.mjs` path as an explicit
+captured Pi executable. Operator args are exactly:
+
+```
+--oats-pi-host 1 --mode print --thinking medium --sdk-root /physical/pi/package --sdk-version 0.85.1
+```
+
+Launch env is empty (no additional OATS contribution, NOT an empty inherited
+process environment); yolo is false; model is an exact `provider/id`. The kernel
+alone prefixes `--home H --session-dir S --model M --task-file H/TASK.md`.
+There is exactly one session-dir flag at prefix indices2/3. Unknown/duplicate
+args, arbitrary task/history/model flags and empty tasks refuse.
+
+The public SDK export is resolved from the exact selected package name/version
+and public export map without PATH/package acquisition or private imports.
+ModelRuntime.create() uses its normal native defaults. Native getAgentDir and
+SettingsManager.create preserve the user's ordinary profile/auth/helpers/OAuth,
+model config and persistence. There is no OATS credential selector/parser/store,
+no copied auth, and no null/empty/no-refresh production fixture configuration.
+
+The public ResourceLoader consumes only reverified retained instructions and
+exact skill files (`includeDefaults:false`). It has zero extensions and refuses
+resource additions. Public services, createAgentSessionFromServices,
+AgentSessionRuntime and runPrintMode remain the actual engine. The print host
+rejects session switch/import/fork/new operations before delegation. Native
+compaction/retry are not disabled. The captured exact model must exist; no
+first-available/default substitution occurs.
+
+## Admission, history and activation hold
+
+The execution-side host verifies the original index/incarnation/intent, native
+pending receipt/target, task input digest, capability approvals, selected launch,
+zero-plugin eligibility and projected curriculum. It revalidates for resource
+reload and startup; it does not admit another action or create an identity.
+
+S is `nativeHistoryPath(H)`'s sibling named `<history-basename>.pi`, never inside
+the native UUID-receipt directory and never the native auth/profile directory.
+Core hooks the EXISTING native transaction's record preparation point, preserving
+its record-ID/pending/target/replay/uncertainty logic. Legacy noncaptured renderers
+are unchanged. A captured Pi CLI recipe is held rather than silently converted
+or launched with unqualified ambient extension behavior.
+
+**Fail-closed dependency:** the record library must provide the complete v2 root
+witness AND discovery/read/each-append guard implementation. This kernel checks
+`CAPTURED_PI_RECORD_VERSION === 2` and these synchronous native-history APIs:
+
+- `inspectCapturedPiRoot(home, { incarnationId, sessionDir })`: read-only original
+  proof validation or truly absent fresh root; missing/ambiguous evidence holds.
+- `prepareCapturedPiStart(home, { incarnationId, intent, sessionDir, assertAuthority })`:
+  pending-v2 before exclusive creation; kernel-authority checks around effects;
+  durable witness outside S before dependent execution; original witness on reuse;
+  returns the existing native record ID, never a replacement action identity.
+- `assertCapturedPiStart(home, id, { incarnationId, intent, sessionDir })`: validate
+  the execution-side started-v2 receipt, original associations and root identity.
+
+The record owner's approved `history.json` v2 expected-ID claim is mutable
+record custody. For the exact strict Pi profile, Core's authority callback keeps
+index/incarnation/lifecycle/home/native-directory/baseline/target checks but does
+not duplicate that private codec or freeze its bytes to v1. The pinned read-only
+inspection, guarded preparation and started-v2 assertion own that validation.
+Re-entering inspection during a pending publication would incorrectly reject the
+record owner's own transition. Non-Pi retains literal v1 manifest equality.
+This narrow consumer correction was demonstrated by the combined package fixture;
+it is not acceptance of a path/self-marker or a weaker record implementation.
+
+The existing recordNativeStart execution must understand/check v2 before exec;
+all downstream guards must be present before the version advertises support.
+Until then, this increment refuses ZP1 BEFORE admission/backend effects. It does
+not fake a complete runnable path or bypass the separate record source exception.
+The API seam is subject to the parent-owned combined code review and coordinated
+record implementation; no record lib/bin edits occur in this increment.
+
+## Non-authorizing print-completion observation (version 1)
+
+The dispatch ID marker and native SDK return value answer different questions.
+Neither proves that the native process terminated successfully AND produced an
+attributable final turn. The small observation increment uses the existing
+native ID, original pending/index/started-v2 custody and witnessed S, not another
+resolver, admission, identity, transcript parser or observation service.
+
+Two exclusive 0600 JSON files live in S:
+
+- `.oats-pi-sdk-<nativeRecordId>.json`: `kind: oats.pi-sdk-outcome`;
+- `.oats-pi-process-<nativeRecordId>.json`: `kind: oats.pi-process-outcome`.
+
+Both have `schemaVersion: 1`, `authority` and `observed`. Authority contains the
+original home/sessionDir/incarnation/IntentRef/nativeRecordId/executionBinding,
+target/admitted input integrity and expected `{runtime: pi, provider, id,
+sdkVersion}` selection. It is attribution, NOT an additional authorization.
+The original attempt remains original even when same-ID reconciliation advances
+the index counter (PH1). Existing/partial/conflicting receipt files are not
+rewritten, adopted or cleaned up. File and directory sync plus custody checks
+surround publication. Before ANY content read, and again before every bounded
+read, the opened outcome descriptor must match the CURRENT physically named
+regular file under original-root proof. An earlier stat can itself come from a
+redirected ancestor; a restored root or a post-read exception is not FD authority.
+Size/version stability checks remain, with no bytes read to discover a mismatch.
+These files are neither root witnesses nor native JSONL;
+the record3API, native inventory, S formula, v1 readers and capture parsing are
+unchanged. Their presence never establishes root ownership.
+
+SDK `observed` is `{exitCode, observation}`. `exitCode` is the actual numeric
+return from native `runPrintMode`, never a default. The public runtime's
+synchronous `setBeforeSessionInvalidate` hook snapshots actual public session
+metadata after shutdown handlers and BEFORE native disposal. It copies only
+SDK VERSION, SessionManager header/id/file, session.model, and the final native
+branch assistant entry's id/provider/model/optional responseModel/stopReason/
+timestamp. That entry must agree with the last state message; an earlier
+assistant followed by another message is not a final assistant. No prompt,
+content/nonce, raw error, profile, credential or request-as-response is copied.
+Unavailable observation stays null; it does not prevent native disposal or
+manufacture a successful turn. The host publishes only after native print mode
+returns and original custody is reverified. Native print output is unchanged.
+
+Process `observed` is `{exitCode, source: launcher-wait-status}`. The COMMON
+captured Pi completion wrapper used by tmux AND Herdr saves the native execution
+chain's actual shell `$?`, then invokes the existing host executable's PRIVATE
+`--oats-pi-record-exit 1 --home H --native-record UUID --exit-status N` mode under
+the ORIGINAL kernel command environment. The native recorder execs the original
+host, so this is post-process wait status, not a sidecar's intent or the SDK
+return value. Nonzero/signaled shell status is retained literally; no signal
+number is guessed. The observer imports/creates no SDK/model/auth services and
+cannot change the enclosing shell's saved native status. This private mode is
+NOT accepted by the launch recipe grammar. Ordinary/Claude/Codex paths are
+unchanged, including explicit permission settings and native defaults.
+
+Only after guarded process-receipt publication does the observer atomically
+publish the EXISTING `.oats-start-exited` with its unchanged dispatch-ID-only
+contents. Legacy readers remain correlation-only. If custody or publication is
+uncertain, missing evidence is held; there is no success fallback, repair or
+new native attempt. A failed process can have a process-only observation; a
+successful-looking SDK receipt without process observation is incomplete.
+
+### Public read-only query
+
+```
+oats session inspect --deployment /deployment --resolution <retained-id> \
+  --home /original/home --native-record <native-UUID> --json
+```
+
+For a helper, use the SOURCE resolution plus `--helper <exact-source-map-key>`.
+There is no current-context lookup. Inspect accepts only home/helper/native-record
+and json after the captured selectors; request/retry/model overrides are refused.
+It admits/provisions nothing, calls no backend/model, and does not forge process
+environment to inspect evidence. Existing source/helper and physical custody
+checks plus pinned `assertCapturedPiStart` surround every receipt read and
+native session-path check. The narrow query requires the ORIGINAL current
+pending dispatch; an old ID after another dispatch replaces pending, a deleted
+incarnation, changed curriculum/input or uncertain root remains held. Files in
+S remain retained; this is not a new historical-incarnation recovery API.
+
+The normal JSON envelope's `result.outcome` has `schemaVersion: 1`,
+`contract: oats.pi-print-completion`, `nonAuthorizing: true`, `authority`,
+`status: succeeded|failed|incomplete`, `qualified`, `processExitCode`,
+`sdkExitCode`, `finalObserved`, nullable `sdk`, and evidence-presence flags.
+Envelope `ok: true` means the QUERY succeeded, not that execution did.
+
+`qualified: true` requires BOTH actual exit codes0, the observed selected SDK
+version/header-v3/home/session-id/file, observed session and final assistant model
+tuples equal to the retained selection, and final `stopReason: stop`. Missing
+facts, mismatches, truncation/tool-use/error/aborted or nonzero status never pass.
+This qualifies only **native-print completion**, NOT meaningful task completion,
+automatic SOURCE helper execution, learning/privacy/capture correctness,
+installation or release. A gate must still compare the expected original IDs,
+consume protected native capture, and establish its domain-specific result.
+Optional native `responseModel` is reported literally, not substituted for a
+missing value or treated as cryptographic provider-side model attestation.
+Receipts share the existing trusted execution-host/filesystem boundary; they do
+not introduce signatures or promise detection of coherent privileged tampering.
+
+Packaging needs the new `lib/captured-pi-outcome.mjs` alongside the existing
+host/custody/SDK modules and bin. Existing lib inclusion already ships it; no
+package/version metadata changes are needed.
+
+## Evidence and honest results
+
+Targeted unit tests use explicit SDK doubles to check parser/assembly argument
+flow, normal native service initialization, loader and before-delegation guards.
+They are NOT another SDK-consumer/model proof. Real retained preparation/scaffold
+checks establish missing-record-support refusal before native effects. Existing
+inert native regression checks cover unchanged custody/replay/placement behavior.
+The previously completed public SDK consumer proof remains separate and closed.
+
+`dispatchAccepted` proves native dispatch acceptance, not a model response.
+The existing `.oats-start-exited` ID marker still does not contain a success code.
+The new completion receipts/query are implemented as bounded kernel consumers;
+unit doubles and inert shells are not actual SDK/model/backend qualification.
+The coupled integration fixture REQUIRES actual complete record-v2 source (no
+skip/stub of record support), exercising kernel/record/CLI wiring on both backend
+paths with an explicitly FAKE SDK and inert transport. The bounded negative case
+uses an existing unwitnessed S and retains legacy CLI refusal, rather than an
+obsolete assumption that record support is absent. Neither fixture is actual
+native SDK/model/backend qualification.
+Real acceptance must observe SDK-created native session/assistant turns and
+actual capture/recall under the completed witness guards, on BOTH selected native
+backends. Do not fabricate process names, sessions, worker runs or learning.

package/docs/design/2026-09-18-first-cut-release-checklist.md

@@ -0,0 +1,131 @@
+# First-cut retained execution: installation and release checklist
+
+This is an execution checklist for the release owner, **not a completed-release or
+runtime-readiness claim**. The first-cut goal is an actual runnable packaged retained
+path. A narrowly working profile does not establish full Desktop/plugin/lifecycle or
+private-provider parity. Developers deliver code; the parent reviews combined code,
+integrates, runs real acceptance and is the sole publisher. No independent-reviewer
+wait is required by the current human workflow.
+
+## 1. Freeze what is actually being shipped
+
+- Record exact framework commit/tree, provider commit/manifest and runtime-consumer
+  revision; retained resolutions, source/helper bindings, protocol selection and
+  emitted witnesses must agree with that combination. Prior closed source gates are
+  evidence at their old pins, not qualification of the new SDK host or protocol22.
+- Include the explicit print-mode SDK host/parser/native-services assembly only when
+  its complete retained eligibility/curriculum, kernel-owned task/args/thinking/history
+  controls and approved external session-directory identity witness are implemented.
+  Path-only history attribution is not an original-root identity witness.
+- Launch the user's already-authenticated harness through its normal native profile,
+  auth/helpers/OAuth/model configuration. **No auth-file selector, CredentialStore,
+  key/provider allowlist, empty production store, profile substitution, credential
+  inspection/copy or new login questionnaire.** Strict selected curriculum/history is
+  a separate boundary, not a reason to replace native authentication.
+- Preserve selected hard runtime/bridge/plugin requirements. If the first supported
+  host is zero-plugin, a profile selecting an unqualified plugin/bridge remains held;
+  do not remove that requirement to advertise default-OKF success.
+- Record-runtime changes remain limited to the exact additional boundary explicitly
+  assigned by the parent after resolving its scope. Do not import held patches or
+  bypass the guard. No general record-package rewrite, bootstrap grammar, role-source
+  adoption or proposed retirement semantics is part of this checklist.
+
+## 2. Metadata and package surfaces (parent-controlled)
+
+Choose an actual unused release version **V** after the final code/pin selection;
+verify it against existing published artifacts. Do not invent a tag or claim that
+source/API2/protocol22 alone establishes a package compatibility floor.
+
+| Surface | Required check/update |
+|---|---|
+| `package.json`, `package-lock.json` | Kernel version/root lock agree; SDK host's real runtime dependencies/import resolution are declared and available after installation, not accidentally from a development/global checkout. Keep manifest exports usable. |
+| `packages/pi/package.json` | Version agrees with kernel; actual supported SDK/native package dependency contract and extension resource paths are truthful. |
+| `packages/desktop/package.json`, `packages/desktop/package-lock.json` | All three release manifests and lock root entries use V. This metadata alignment does not mean complete Desktop behavior is qualified. |
+| Provider distribution/capability manifests | Selected provider version and minimum OATS floor must include its actual supported wire/input/runtime requirements. Source-main with old metadata is not a released compatibility claim. |
+| `scripts/okf-source-inventory.json`, `capabilities/oats-okf/`, `package-catalog.json` | If shipping an updated default provider, use the authoritative provider source and existing mirror/finalization tooling, then verify exact retained closure/canonical aliases and real published refs. Never hand-edit the mirror or point a catalog at an invented tag. |
+| `docs/release-notes/<actual-tag>.md` | Exact tag-matching filename exists before build/tag. List implemented profile/actual gates and every remaining refusal; no real-worker/learning or model-health claim from inert output. |
+
+The existing `.github/workflows/release.yml` and `scripts/release-lane.mjs` derive V
+for **root, Pi and Desktop**, using `--allow-same-version`. The older release skill's
+blanket two-package/no-same-version description is not the current implementation.
+No developer package/version edits are authorized by this checklist alone.
+
+## 3. Artifact/install boundary
+
+Release owner uses the existing release tooling; this lane performs no pack/install/
+publish operation. Build from the exact reviewed commit, not moving HEAD.
+
+1. Run the applicable syntax/project/package gates on that assembled tree. Confirm
+   the new SDK host/bin, parser, native adapter and all runtime dependencies are in the
+   **actual** kernel tarball; Pi bridge resources must also be in its tarball. Verify
+   no deployment config/lock, agents/instances, credentials, private KB or scratch leaks.
+2. Keep canonical Git payload aliases intact for selected capabilities. npm's omission
+   of source symlinks does not make its copied provider subtree a self-contained Git
+   distribution; use the supported complete provider acquisition path.
+3. Pack kernel and Pi bridge once and record hashes. Install those exact tarballs in a
+   clean external location, outside the source checkout. Confirm installed CLI/core/
+   SDK-host dependency resolution with no repository-module or unselected resource
+   fallback. A checkout scaffold is not an installed-artifact test.
+4. Use existing public `prepare --request` with an explicit valid source export,
+   deployment and workspace-or-standalone context. Approval/reprepare is explicit;
+   no private scratch input/current-config hole filling. Do not assume the parked five
+   roles or public bootstrap package have been adopted/published.
+5. Inspect retained instructions/skills/launch inputs and preserve unsupported-profile
+   refusals. Create only a new owned home; do not overwrite old instances/state. A
+   source-complete helper is selected by its **SOURCE edge**, not a bare helper-ID
+   start. No-launch can still run admitted hooks and is not a real session gate.
+
+## 4. Parent-run real first-cut acceptance
+
+Use the already assigned single provider/native path rather than inventing a second
+matrix. Pin and retain its real results separately from old inert/seeded evidence.
+
+- Both tmux and Herdr are required, not a deferred optional backend. For Herdr select
+  the exact supported protocol and explicit operator-managed executable/socket; the
+  server snapshot must match it. IDs are observed receipts. No automatic daemon start,
+  tmux fallback, fabricated caller context or focused user session.
+- Run an actual retained primary and exact SOURCE-helper through the new host, using
+  normal authenticated native harness operation. Verify an actual turn/task result,
+  selected curriculum and original session-directory identity/history continuity.
+  Source deletion/current-config poison must not redirect the retained selection.
+- Record dispatch acceptance separately from model health, task completion, capture,
+  judged knowledge delivery, acceptance and fresh-reader learning. With default OKF,
+  use the provider's explicit private owned directory-store path and required selected
+  launcher/bridge; do not fake a worker/process/transcript or convert seed data into
+  learning evidence. If a required bridge is unqualified, report the exact hold.
+- Preserve source versus helper execution authority and original incarnation/intent/
+  pending/history receipts across replay/restart/failure. Same-ID ambiguity never
+  authorizes redispatch. Missing public retirement/recovery remains a documented hold,
+  not permission to call a legacy/private fallback or delete an uncertain home.
+- Credential/account/private-messaging authority is not granted by backend/model success.
+  External human/admin private-aweb evidence cannot be manufactured by this gate.
+
+## 5. Publication and honest first-cut status
+
+The existing tag workflow publishes only after build/test/smoke **and Desktop matrix**
+jobs are green; npm kernel then Pi, GitHub release/assets last. The existing runnerless
+lane can stage exact artifacts and publish its two staged npm tarballs; the parent owns
+whether/how to use that documented route. Do not edit away gates to meet a clock.
+
+Before publication retain exact source/tag ancestry, version probes, package checksums,
+provider provenance and completed gate receipts. Verify published versions, package
+integrities/source identity and installed behavior afterward. Do not move a tag after
+any publication; distinguish partial npm publication, GitHub assets and bump-PR results
+before retrying the appropriate existing phase. No force-push or credential repair here.
+
+If packaging or a required real gate is incomplete at the first-cut deadline, deliver
+its exact candidate artifacts plus named hold; label it **candidate**, not published or
+usable for the blocked profile. Do not reset the agreed clock or conflate npm readiness
+with all-platform Desktop delivery.
+
+### Explicit limitations to carry into release notes unless genuinely closed
+
+- Adapter20/22 unit support is not public caller/schema22 or real-server readiness.
+- SDK feasibility/inert dispatch is not an actual normal-auth model turn.
+- Zero-plugin success is not eligibility for a selected plugin/bridge/managed profile.
+- Directory/history custody is not completed public retirement, wake or recovery.
+- Source/provider gates are not actual worker/capture/learning/private-aweb proof.
+- A packaged CLI/Pi path is not complete Desktop/platform behavior or rollout parity.
+
+Every open item retains its existing refusal and owner. This checklist changes no
+runtime semantics, metadata, release automation, live state or production authority.

package/docs/design/2026-09-18-herdr-protocol-compatibility.md

@@ -0,0 +1,60 @@
+# Explicit Herdr protocol20/22 adapter compatibility
+
+The host-local adapter in `lib/herdr.mjs` supports exactly numeric protocols **20**
+(documented0.8 baseline) and **22** (documented0.9.0 native schema). This is explicit
+selection, not version negotiation or proof of an installed/running backend.
+
+## Shared adapter interface
+
+- `HERDR_PROTOCOL` remains20 for existing legacy/default behavior. In particular,
+  the unchanged legacy `ensureHerdr` path is not silently switched to22.
+- `HERDR_SUPPORTED_PROTOCOLS` is the frozen `[20,22]` set.
+- `isSupportedHerdrProtocol(value)` accepts only those numbers; no strings,
+  omitted/null value, protocol21, future number or range is accepted.
+- `herdrSnapshot(target, io)` requires a supported explicit target protocol before
+  issuing a command, then requires **snapshot.protocol === target.protocol** and a
+  pane inventory. A20 target cannot accept a22 snapshot, or vice versa. Missing or
+  malformed observations refuse; saved target metadata is not upgraded/downgraded.
+- `allocateHerdr` also validates the selected protocol before workspace creation,
+  preserving it alongside the actual returned workspace/pane/terminal identifiers.
+  As before, callers own preflight/admission and the pending/observed-target ledger;
+  allocation is not a new independent lifecycle transaction.
+- `validHerdrTarget` recognizes both explicit protocols with its existing target
+  checks. Delivered strict workspace/pane/terminal uniqueness, explicit socket
+  transport, replacement refusal, run/input/stop behavior and server-error handling
+  are retained. No daemon, focused target or alternate-backend fallback is added.
+
+The captured caller and generated request/target schema must use the same set and
+retain selected/admitted/observed target equality. That integration belongs to the
+lifecycle owner (`lib/captured-session-backend.mjs`, core and shared schema generator),
+not this adapter-only change. A current const20 caller still correctly refuses22 until
+that separate integration lands. API availability is not protocol/host/model readiness.
+
+## Documented native0.9 subset
+
+The bundled protocol22 schema retains `.result.snapshot`, panes/agents and their
+workspace/pane/terminal identifiers, `.result.root_pane` allocation identifiers,
+agent status values and process-info fields used by the existing adapter. The CLI
+spellings remain `api snapshot`, `workspace create --cwd ... --label ... --no-focus`,
+`pane run <id> <command>`, `pane process-info --pane <id>` and `pane close <id>`.
+
+These observations justify reusing the adapter, not treating arbitrary later protocol
+numbers as compatible. Client version, server version, endpoint-protocol generation,
+OATS API version and native request version remain distinct facts. Explicit existing
+operator-managed executable/socket and actual server protocol must be qualified by the
+real acceptance gate. No `HERDR_ENV` value is fabricated or focused user session used.
+
+## Evidence boundary
+
+`test/herdr-protocol.test.mjs` uses injected inert command responses, not a live
+server or process:20/22 preservation, unknown/missing refusal before commands, exact
+snapshot mismatches, actual-ID projection, explicit command/socket transport, strict
+ambiguous/foreign/replaced targets and stop/input behavior. Existing adapter tests
+remain applicable. The controlled scaffold probe composes resources and normally
+retires without invoking a backend.
+
+This slice does not qualify public native protocol22 integration, real model health,
+Pi managed-resource eligibility, worker completion, public retirement/recovery, private
+messaging, release floors or production. None of those guards is removed. Ordinary
+already-authenticated harness operation remains separate from this backend adapter;
+no auth-file selector, credential copy or production profile substitution is introduced.

package/docs/desktop-cli-api.md

@@ -18,8 +18,11 @@ prints exactly one JSON object on stdout:
 ```
 
 `version` is the installed package's exact semver (e.g. `0.20.0`).
-Desktop 0.23 accepts `desktopApi === 1` and semver `>=0.22.0 <0.24.0`
-(the earlier Desktop 0.22 band was `>=0.22.0 <0.23.0`).
+Desktop 0.24 accepts `desktopApi === 1` and semver `>=0.22.0 <0.25.0`
+(the earlier Desktop 0.23 band was `>=0.22.0 <0.24.0`). This admits the paired
+0.24 CLI without changing Desktop API v1. It does not establish complete captured
+UI, backend, plugin, retirement or recovery parity; capability checks and explicit
+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

package/docs/execution-capsule.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oats.dev/schemas/execution-capsule-v1.json",
+  "title": "Scheduled execution capsule v1",
+  "description": "Immutable local authority for one admitted scheduled execution. executionId identifies this intent; a canonical oats.json.v1 digest of the remaining fields separately identifies content. Structural validation does not verify freshness, the retained resolution, approval, host readiness or provider state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "executionId",
+    "resolution",
+    "deployment",
+    "action",
+    "target",
+    "inputRefs",
+    "responsibleHuman"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "executionId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "resolution": {
+      "$ref": "https://oats.dev/schemas/portable-v1.json#/$defs/ResolutionRef"
+    },
+    "deployment": {
+      "type": "string",
+      "minLength": 1
+    },
+    "action": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "name"],
+          "properties": {
+            "kind": { "const": "command" },
+            "name": { "type": "string", "pattern": "^[^:\\s]+:[^:\\s]+$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "name"],
+          "properties": {
+            "kind": { "const": "wake" },
+            "name": { "const": "session" }
+          }
+        }
+      ]
+    },
+    "target": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["cwd", "argv"],
+          "properties": {
+            "cwd": { "type": "string", "minLength": 1 },
+            "argv": {
+              "type": "array",
+              "minItems": 3,
+              "items": { "type": "string" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["home", "message"],
+          "properties": {
+            "home": { "type": "string", "minLength": 1 },
+            "message": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "inputRefs": {
+      "type": "object"
+    },
+    "responsibleHuman": {
+      "type": ["object", "null"]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "action": { "type": "object", "properties": { "kind": { "const": "command" } } } }
+      },
+      "then": {
+        "properties": { "target": { "type": "object", "required": ["cwd", "argv"], "properties": { "cwd": {}, "argv": {} } } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "action": { "type": "object", "properties": { "kind": { "const": "wake" } } } }
+      },
+      "then": {
+        "properties": { "target": { "type": "object", "required": ["home", "message"], "properties": { "home": {}, "message": {} } } }
+      }
+    }
+  ]
+}

package/docs/execution-targets.md

@@ -235,13 +235,26 @@ Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
 scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
 `--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
 the same per-launch choice. With no setting, native policy is retained.
-
-Codex receives `--yolo` plus a launch-local trust setting for the generated
-instance home; Claude receives `--dangerously-skip-permissions`. Pi's existing
-project trust behavior is unchanged. `--no-yolo` removes the OATS bypass flags;
-it leaves the operator's native harness settings in force. Instance metadata
-records an explicitly resolved setting. This choice applies when starting an
-agent, not retroactively to running sessions.
+Autonomous or unattended execution is not permission to synthesize `yolo: true`.
+Explicit user CLI/UI input or a user-selected configuration is the opt-in; explicit
+`false` remains false.
+
+Only for an explicitly resolved true setting does OATS add Codex `--yolo` plus
+launch-local project trust, or Claude `--dangerously-skip-permissions`. `--no-yolo` removes the
+OATS-added bypass flags while native settings stay in force. Instance metadata
+records the resolved choice; this policy does not rewrite frozen recipes, live
+configuration or already-running sessions.
+
+Claude Code and Codex use their ordinary native context, skills, settings, plugins,
+profile and authentication. OATS still builds the complete ordinary instance home:
+resolved skills, capabilities and resources, canonical AGENTS plus its CLAUDE alias,
+task, metadata and normal work placement. Resolution, approvals and lifecycle hooks
+are not skipped; normal native launch is not an empty/no-capability mode. Only outside
+native context/skill coexistence is relaxed: OATS does not impose an OATS-only ambient
+view or route these runtimes through the Pi SDK. Pi's selected strict SDK profile is unchanged. OATS
+composition integrity/provenance, source/helper authority, record attribution and
+guards, and admission/retry obligations remain separate and required; normal native
+context alone is not a Claude/Codex qualification failure.
 
 Desktop remote terminal requests contain only the server id and instance name.
 The selected installed CLI resolves the saved route and performs remote

package/docs/oats-lock-v3.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oats.dev/schemas/selection-lock-v3.json",
+  "title": "Source-request selection lock v3",
+  "description": "New private wire boundary; public consumer activation requires the explicit preparation/migration integration. See portable-v1.json for semantic verification requirements.",
+  "$ref": "https://oats.dev/schemas/portable-v1.json#/$defs/Lock3"
+}

package/docs/oats-member.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oats.dev/schemas/member-v1.json",
+  "title": "Portable repository export index v1",
+  "description": "oats.yaml advertises definitions; a backlink is not admission or permission. Public external export indexes may omit workspace.",
+  "type": "object",
+  "required": ["schemaVersion", "exports"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "workspace": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/repository" },
+    "exports": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "souls": {
+          "type": "array", "items": {
+            "type": "object", "required": ["path", "definition"], "additionalProperties": false,
+            "properties": {
+              "path": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
+              "definition": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "packages": {
+          "type": "array", "items": {
+            "type": "object", "required": ["path"], "additionalProperties": false,
+            "properties": {
+              "path": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "knowledge": { "type": "array", "items": { "$ref": "https://oats.dev/schemas/soul-v1.json#/properties/knowledge" } }
+      }
+    }
+  }
+}