@awebai/oats 0.29.4 → 0.30.1

package/docs/design/2026-09-17-capability-helper-input-contract.md

@@ -1,95 +0,0 @@
-# Capability-owned helper injection and lifecycle input contract
-
-**Decision status: exact syntax/witness plan approved; shared producer implementation candidate, paired provider qualification pending.** Shared codecs, retained composition/publication checks and selected hook input delivery are implemented together and require independent review and exact provider pairing before runtime qualification. This is not production acceptance, does not waive custody/launch gates, and does not authorize changes to a stable provider/index review pin. Native launch/custody work remains the priority.
-
-Context: current captured preparation omits helper knowledge injections by slot and activation automatically supplies a source receipt to a knowledge spawn hook. These are capability policies in kernel clothing. Replace only those assumptions with explicit retained declarations, reusing [captured invocation](2026-09-16-provider-binding-wire.md), existing choices/resources/composition and the existing hook table. No knowledge store, harvester, new resolver or action registry belongs in this change.
-
-## 1. Exact `helperInjection` syntax
-
-One optional capability-manifest field; when present it is exactly one of:
-
-```json
-{"helperInjection":{"version":1,"mode":"inherit"}}
-```
-
-```json
-{"helperInjection":{"version":1,"mode":"omit"}}
-```
-
-```json
-{"helperInjection":{"version":1,"mode":"file","path":"injects/helper.md"}}
-```
-
-`version` is the integer 1. The declaration is closed: `version`/`mode` are required; only `file` requires/allows `path`. Unknown fields, versions, modes and null/false alternatives refuse. There are no helper-name patterns, conditions, settings overrides or software/provider/team selections in this declaration.
-
-| Mode | Contribution to a helper composition selecting this capability |
-| --- | --- |
-| `inherit` | Its own retained `inject` contribution, under existing composition choices. Missing own injection refuses rather than inventing one. |
-| `omit` | No injection from this capability; record the explicit declaration-backed omission. |
-| `file` | Its own contained, normalized capability-relative regular file. It may be helper-only even if the capability has no primary `inject`. |
-
-The field controls only `capability:<its-id>`, never kernel/work-mode/another capability's block. It is not permission to register a source, own a store, harvest, publish, delete state or edit retained resources. Existing separately authorized instruction disable/override choices cannot be silently displaced; an unsupported combination refuses instead of introducing another precedence algorithm.
-
-For **new helper preparation**, a selected capability with an injection contribution but missing policy is unresolved (`needs-configuration`), regardless of its layer. A capability with neither a primary injection nor a helper declaration contributes nothing and needs no invented policy. Primary compositions are unchanged. Preflight all advertised helpers before publishing any helper or parent record; keep the current helper-authored software/provider-policy refusal.
-
-### Captured witness
-
-Use the existing choice resolver with a capability-local hard equality fact:
-
-- Choice key: `/helpers/injections/<JSON-pointer-escaped-capability-id>`.
-- Value: the existing `instruction:capability:<id>` resource key, or null for omission.
-- Origin: existing `kind:"source-export"`, witnessing this capability's exported instruction contribution; artifact document `{kind:"artifact",owner:<exact capability artifact>,path:"oats.json",integrity:<raw manifest bytes integrity>}`, pointer `/helperInjection`.
-- Inclusion: existing block `{source:"capability:<id>",resource:<key>,choice:<choice-key>}`. The resource remains owned by the same exact capability artifact and must match its retained declared file.
-- Omission: `{source:"capability:<id>",reason:"helper-policy",choice:<choice-key>}` with null value and the exact retained `omit` witness.
-
-No new authority kind or resolver is needed. The verifier must check both directions: every capability-sourced block/omission in a newly published helper agrees with its owner's exact retained helper-policy fact, and every applicable retained declaration is represented. This includes entries with no choice or an unrelated operator choice: neither can supply a contribution from a capability with no applicable declaration. Publication checks run through the real `commitCapturedResolution` boundary before creating the store/staging, not only through the compiler. A same-valued fabricated origin is not sufficient. Such witnesses cannot justify choices for software or other capabilities.
-
-### Old evidence versus new publication
-
-`helper-knowledge` remains readable/verifiable as literal old captured evidence; never rewrite its record or infer a new policy from it. The new compiler never emits it. New publication must not mint a legacy slot-derived omission to evade declaration checks; reuse of an already-present identical old record remains distinct from creating one. `verifyResolutionInputs` checks declared policy witnesses on retained inputs. `commitCapturedResolution` first permits verified identical already-present evidence reuse, then enforces the new-publication policy BEFORE creating a store/staging file for a new record. Direct callers bypassing the compiler cannot mint a legacy omission or missing-policy helper. Literal historical read/reuse and distinct new-mint refusals have explicit storage-level counterexamples. No historical reconstruction or general migration is added.
-
-## 2. Exact per-hook source-receipt opt-in
-
-Extend the existing **object form of a hook**, not a parallel hook/action table:
-
-```json
-{
-  "hooks": {
-    "spawn": {
-      "command": "<unchanged existing spawn command>",
-      "required": true,
-      "inputs": {
-        "sourceReceipt": {"version": 1}
-      }
-    }
-  }
-}
-```
-
-The command is a placeholder for the capability's unchanged actual declaration. Existing command-string hooks still work and request no source receipt. `inputs` is an optional closed object, presently allowing only `sourceReceipt`; that value is exactly `{version:1}`. Absence/empty `inputs` means no opt-in; null/false/unsupported versions and arbitrary contract names refuse. Existing approved hook names and `required` restrictions are unchanged. An opt-in does not implement an otherwise unsupported lifecycle path.
-
-The emitted payload is the existing **SourceReceipt1**, unchanged: schemaVersion/kind/home/work/context/agent/instance/sourceIdentity/role/executionBinding/responsibleHuman/binding. Its legacy `context` field remains the normalized execution deployment; the generic invocation separately carries the full captured workspace/standalone context. Do not silently redefine either field.
-
-Before readiness or hook effects, an opted-in input requires:
-
-1. An exact verified selected manifest/hook and approved executable, with version-1 opt-in read from retained bytes.
-2. The current owned instance/incarnation/work custody and matching admitted action; source/subject/instance/human/context/execution-binding equality remains mandatory.
-3. The opting capability's **actual selected ProviderBinding1** in its declared layer, with matching owner and versioned payload. An additive capability with no such binding cannot request this input; never borrow another provider's binding or infer one from a slot name alone.
-4. The retained canonical role resource for that subject in the verified composition, including source/definition ownership and canonical alias checks. Helpers retain their helper identity semantics, not an invented persistent identity.
-
-The captured hook runner derives separately for each opted-in hook owner, using the existing source-receipt validator/private snapshot wrapper beside its generic invocation and binding snapshots. All selected-input prerequisites are checked during static all-hook preflight, then the owned instance facts and selected receipt are compared again under the admitted projection before provider readiness/execution. Activation no longer supplies an automatic knowledge-slot receipt. Do not derive one knowledge receipt and distribute it to other providers. Generic invocation remains available without source-receipt opt-in.
-
-If a core caller supplies an explicit receipt, require exact equality with the derived input and a matching opted-in owner; reject unsolicited or contradictory receipts before provider code. Ambient/caller-nominated snapshot files are not authority. Unselected inputs must not leak through `extraEnv`, and selected snapshots must retain same-owner/no-fallback handling. Uncertainty, cleanup failures and observed receipts continue through the existing independent custody/reporting path.
-
-No opt-in means **no automatic SourceReceipt1**, including for a knowledge provider. Absence is not consent, but absence alone is also not generic proof of provider dependency or non-readiness. Do not infer that dependency from a capability name or layer. A deliberately registered old source may replay from its retained descriptor plus binding when its existing qualified contract allows it; NEW source registration must not acquire authority through that fallback. Old captures remain immutable. Producer/provider candidates must identify and test this compatibility/readiness distinction against exact qualified artifact/version pins, rather than claiming a universal automatic non-ready diagnosis.
-
-## 3. Default OKF and qualification sequence
-
-This producer candidate changes the captured preparation/dispatch paths; it does not qualify legacy config-chain lifecycle execution for these selected inputs. The compatible candidates must declare the actual OATS compatibility floor containing these codecs, coordinated at release; an older kernel or legacy route silently ignoring new fields is not compatible. Default OKF's separate compatible candidate must explicitly declare `helperInjection:{version:1,mode:"omit"}` and add `inputs.sourceReceipt:{version:1}` only to spawn/retire hooks that actually consume SourceReceipt1: preserve spawn command/required:true, retain the retire command/required semantics when converting it to an object, and do NOT opt in soul-scaffold. Keep actual commands and required-hook semantics intact. Registration/helper skip/recursive-harvest prevention remain provider-owned and must still pass; omitted instruction text is not recursion prevention. Runtime Git knowledge delivery remains PR-only.
-
-Sequence after priority custody/native-launch work:
-
-1. Exact syntax/witness review is complete and implementation is authorized, including the provider's binding edges; do not change the stable source-main/index review pin or wait for another milestone permission.
-2. Shared producer implementation now includes manifest codec/schema, retained declaration verification, helper choices/composer, storage publication guard and per-hook input opt-in together. Preserve legacy evidence without new slot-based omissions; independent source review is still required.
-3. Pair a separately committed default OKF consumer with the exact producer. Test own-only inherit/omit/file, missing policy, cross-owner/path escape, forged/absent declaration witnesses, missing input prerequisites, multi-provider same-owner delivery and snapshot fallback attempts.
-4. Re-run provider registration/helper-skip/recursion and PR-delivery safeguards on the paired pins. Fixture compatibility is not native enrollment/privacy or real helper launch. Coordinator owns final acceptance/main/production under standing when-ready authorization.

package/docs/design/2026-09-17-captured-backend-parity.md

@@ -1,53 +0,0 @@
-# Captured native backend parity: tmux and Herdr
-
-Implementation candidate over the existing native session transaction. Herdr is a required backend, not optional post-release work. This increment supports captured primary/helper public start/restart with both adapters; applicable wake/retire/recovery/provider-worker paths and real model/host qualification remain separate required gates before overall rollout completion.
-
-## Exact public endpoint and receipt shapes
-
-The existing native request remains `{schemaVersion:1,backend?,task?,stopGraceMs?}`. Backend is a closed tagged union:
-
-```json
-{"backend":"tmux","binary":"/absolute/tmux","socket":"/absolute/tmux.sock","session":"selected-session"}
-```
-
-```json
-{"backend":"herdr","binary":"/absolute/herdr","socket":"/absolute/herdr.sock","protocol":20}
-```
-
-No Herdr `session`/`window`, caller-created workspace/pane/terminal ID, config lookup or inferred socket. First start requires explicit endpoint/task; later calls may reuse their guarded owned values. A supplied malformed/null endpoint is not omission. Model/runtime/yolo/managed resources still come from the captured recipe, credentials only through the existing nonsecret references.
-
-Existing `allocateHerdr` issues `workspace create --cwd HOME --label INSTANCE --no-focus` and returns the actual `root_pane` IDs. Receipts retain:
-
-```json
-{"backend":"herdr","binary":"/absolute/herdr","socket":"/absolute/herdr.sock","protocol":20,"workspaceId":"w1","paneId":"w1:p1","terminalId":"term_native"}
-```
-
-These are observations allocated after admission, never IDs fabricated from a name/home/hash. The protocol adapter targets Herdr 0.8.x, with documented reference baseline 0.8.2; enforced runtime prerequisite is snapshot protocol **20** plus the existing commands/result fields. This source increment does not claim an installed version or live socket was checked. An explicit existing operator-managed socket and executable are required; unavailable or incompatible snapshots refuse. Captured start does NOT call `ensureHerdr`, start a daemon, install a backend or fall back to tmux.
-
-## Existing transaction, stronger target custody
-
-Both branches use `startCapturedInstanceSession` and the existing private-plan route into `startInstanceSession`, including independent home/work/native-history/baseline witnesses, admitted task/endpoint commitment, locks, pending start, bounded stop, native location recording and result publication. Source completion still uses SOURCE binding; helper execution uses its exact dedicated binding and owned incarnation.
-
-NS1 metadata/index lifecycle agreement and explicit cleanup-debt retry rules apply unchanged. NS2 returns same-ID present non-shell pending adoption without another stop/dispatch; absent/exited/shell uncertainty remains held. NS3 checks the backend-tagged metadata and independent endpoint before provider/backend effects. Herdr targets additionally need indexed observation custody; residual tmux metadata, unrecorded/changed workspace/pane/terminal IDs, wrong endpoint or missing launched-target metadata refuse.
-
-First Herdr allocation extends the EXISTING pending record with `phase:"allocating"` and explicit endpoint before `workspace create`. If the response is lost or fails, the same intent remains unconfirmed and retry refuses automatic reallocation or label-based lookup. No new journal service or silent repair is introduced.
-
-When allocation returns, its exact valid target and native-history reference are persisted in the EXISTING running index intent BEFORE pane launch. The full pending record is then written. Returned target facts reach failure custody even if later publication/root checks fail. An unknown allocation with no IDs cannot be replaced by invented authority. Complete pending target IDs must agree with indexed evidence; the pending request must be the latest session intent. Baseline, indexed known targets and metadata are checked together, including during interrupted acknowledgment.
-
-The existing Herdr adapter's captured strict observation compares workspace + pane + terminal and rejects ambiguous/missing workspace matches. A replacement terminal is not the old target. Transport carries the exact admitted `HERDR_SOCKET_PATH`, scrubbing inherited `HERDR_SESSION`/socket values. Native guards do not accidentally discard the adapter's endpoint environment. Normal legacy adapter behavior is unchanged outside the explicit captured strict path.
-
-## Availability is not readiness
-
-`oats.captured-session` API **version2** advertises supported adapters without claiming host readiness:
-
-```json
-{"schemaVersion":1,"api":{"contract":"oats.captured-session","version":2,"available":true,"backends":["tmux","herdr"]},"readiness":{"status":"not-checked"}}
-```
-
-Request envelope1 is still native action input, not configuration or authorization to choose a different model/provider. Version1 pins remain historical; consumers must require a understood version/backend contract and validate actual results/refusals, not guess from backend names. Static discovery never probes or provisions. Dispatch acceptance is not model health, task completion, provider/private messaging readiness or release acceptance.
-
-## Evidence and limits
-
-Focused public tests run the real CLI with fake backend EXECUTABLES and actual inert native children for both primary/helper records. Herdr fixture verifies the explicit transport socket and indexed target/intent BEFORE the child effect; tests first start, distinct restart, same-ID uncertain restart adoption, allocation-response uncertainty with no duplicate allocation, poisoned metadata/terminal refusal, workspace mismatch before launch, wrong protocol with no allocation and retained target/history facts. A synthetic present-agent snapshot after an inert child exits drives the uncertain-adoption branch; it is not a live-model observation.
-
-Tmux public regressions and native NS1/NS2/NS3 guards remain covered. This is a small implementation parity check, not a full platform matrix or real daemon/Pi/provider qualification. No production socket/account/backend was changed. Coherent integration and later real Herdr/native-Pi gates belong to the coordinator, with independent reviewers owning source verdicts.

package/docs/design/2026-09-17-captured-native-start.md

@@ -1,58 +0,0 @@
-# Captured native start through the existing session transaction
-
-**Implementation candidate; not release, privacy or live-model acceptance.** This is an actual native dispatch path, not replay of a no-launch scaffold. Tests execute inert native fixture binaries through the existing backend command path. The subsequent [public start/helper CLI bridge](2026-09-17-public-captured-start.md) exposes this transaction with required [tmux/Herdr parity](2026-09-17-captured-backend-parity.md); provider-worker and Pi qualification remain separate.
-
-## Explicit executable inputs
-
-The [launch request](2026-09-16-captured-launch-inputs.md) now accepts either:
-
-- `executable:{capability,command}` for an OATS-managed retained entrypoint; or
-- `executable:"/absolute/normalized/host/tool"` for an explicit external host executable.
-
-An external host tool is not forced into a new runtime capability and its binary bytes are not represented as an OATS artifact pin. Dispatch checks availability/executability at the recorded path, not current PATH/config aliases. An executable resolving into this deployment's managed `.agents` namespace must use retained-resource authority, not this escape. Managed entrypoints must match the selected retained manifest command and its exact resource.
-
-Runtime, model, environment references and yolo remain explicit captured inputs. There is no current launch-config/model resolver. Native runtime configuration is not claimed totally hermetic; credential reference values stay outside records.
-
-## Fresh native evidence
-
-Public `scaffoldCapturedInstance` initializes the existing native-history and independent retirement/session baseline **only for a freshly created owned home**, before hooks. Existing sidecars at a reused address cause refusal, not deletion or history backfill. Home existence retains its normal refusal.
-
-Metadata and the existing guarded instance index retain a versioned `nativeScaffold` directory-witness set (native-history root/home directory and retirement root/baseline directory). Native start checks those witnesses and the unchanged complete fresh-history header. Older/unwitnessed captured homes do not gain these facts by starting.
-
-The existing `packages/record` APIs are reused without modifying that package. Native location recording still happens inside the backend shell under the actual execution environment, before native exec. Location rules, historical preservation and unsupported explicit-session handling remain that contract's responsibility.
-
-## Core API and authority
-
-```js
-startCapturedInstanceSession(home, {
-  deployment, resolution, // optional equality assertions; owned binding is authoritative
-  backend: {backend:"tmux", binary:"/absolute/tmux", socket:"/absolute/socket", session:"name"},
-  task: "explicit initial task",
-  restart: false,
-  retryExecutionId // explicit retry/replay only
-})
-```
-
-Embedding/test options include explicit `env`, existing backend `io`, and bounded-stop configuration. These are not a new provider protocol. Initial task/backend placement must be supplied; later calls can use their owned metadata/TASK.md. Herdr additionally accepts `{backend:"herdr",binary:ABS,socket:ABS,protocol:20}` and allocates actual workspace/pane/terminal IDs after admission via the existing adapter; no automatic daemon start or tmux fallback. Backend relocation refuses rather than adopting another endpoint. Contradictory residual `tmux`/window/socket/session, `sessionTarget`, or backend metadata refuses before provider/backend calls. The exact admitted target is carried into the private native transaction and checked against any independent endpoint; first allocation never selects a legacy metadata fallback. Placement is rechecked with the root guards.
-
-The old public home-only `startInstanceSession`/`restartInstanceSession` routes captured homes into this path **before** legacy `planLaunch` or current configuration resolution. Runtime/model/config/yolo replacements are refused; a new captured selection is required. Omitted legacy option properties do not create overrides.
-
-Before provider readiness, validate the exact record, approvals, subject/human/home/work, native sidecars, instruction/skill bytes and aliases, executable, supported arguments, environment references, backend and task. Selected bindings then receive their existing read-only `inspect` check with the owned generic invocation. This is availability checking, not invented enrollment or a provider-native action. Recheck custody/curriculum/task before every backend call.
-
-## Admission and native transaction reuse
-
-A kernel-owned index intent uses `{kind:"session",name:"start"|"restart"}` with `capability:null`. It extends the existing bounded index, not the provider invocation action table or a new journal service. Provider wire remains unchanged. Its input commitment binds the explicit backend and task bytes; resolution/incarnation remain independently verified authority.
-
-Require matching metadata/index lifecycle before provider checks/admission. New requests start only from matching `spawned-launch-pending` or `start-dispatched`; cleanup-required needs the exact latest saved retry, and a completed intent with remaining publication debt stays held for explicit reconciliation (no automatic cleanup path is invented). Native admission checks the expected metadata/index state again under the existing write guard, before minting or incrementing an attempt. Acquire `start-running` only from that validated state, then mark the admitted attempt running before task/metadata/backend effects. The existing `startInstanceSession` transaction consumes a private captured plan instead of invoking the legacy planner. It reuses locking, endpoint observation, preflight-before-stop, tmux allocation/respawn, native-history recording, pending receipt, independent endpoint baseline and metadata publication.
-
-Pending/start IDs use the admitted logical executionId. Native-history segment IDs remain their existing evidence IDs and are linked in the pending/result receipts as `nativeRecordId`; they are not replacement logical request identities. The native process receives exact OATS deployment/resolution/incarnation/execution/attempt markers, not its caller's identity.
-
-Successful backend dispatch records `start-dispatched` and returns `dispatchAccepted:true`; that means the existing native transaction accepted the dispatch, **not** that a model is healthy, a task finished, or a provider is private/enrolled. Completed explicit replay performs no backend dispatch. Distinct new requests get distinct execution IDs under the same incarnation.
-
-On uncertainty, preserve pending target/native-history references and an unconfirmed indexed intent using original authority and the owned lifecycle state; never write a replacement home. A retry cannot turn an absent/exited uncertain pending target into another launch under the same logical request. If the same-ID pending target is present and non-shell, return its reconciled receipt for BOTH start and restart retries, without stopping or dispatching a second process. Only a distinct new restart ID may continue through the ordinary restart path. Such evidence remains held for explicit reconciliation. No force cleanup or fabricated success is provided.
-
-## Initial limits and evidence
-
-Unsupported work modes, backends other than the existing tmux/Herdr adapters, arbitrary extra native arguments, required managed runtime packages without a qualified captured loader, and unresolved launch/spawn runtime contributions explicitly refuse. This does not replace their missing implementation with `--no-launch`. The static helper resolver now advertises the public versioned native API separately from unchecked readiness; the provider `E_CAPTURED_HELPER` gate still requires its own qualified public-path consumption. Neither static availability nor the CLI bridge qualifies each provider-worker path.
-
-The focused test prepares separate primary/helper recipes, deletes source/current config authority, executes actual inert fixture processes through a fake tmux transport, verifies admission inside those processes, checks captured model/identity markers and native history linkage, exercises new-request/replay/restart and preflight-before-backend refusal, holds a metadata-write uncertainty without duplicate execution, and refuses missing native scaffold evidence or replaced native custody directories. No real model, GUI, backend daemon, provider enrollment, timer, release or deployment operation runs in that fixture. Narrow native-review regressions additionally preserve divergent/newer lifecycle bytes, hold completed publication debt, check admission state before mint/retry, adopt a same-ID uncertain restart under a synthetic present-target observation without another stop/dispatch, and reject residual endpoint B before proving actual A allocation argv. Inert Node executables explicitly use `.cjs`, including public CLI fixtures, so an ancestor `type:module` does not change their semantics.

package/docs/design/2026-09-17-portable-boundary-hookup.md

@@ -1,19 +0,0 @@
-# Captured boundary resource hookup
-
-This integrates the [IC1 resource-only correction](2026-09-17-portable-boundary-resources.md) into actual captured preparation. It is not a change to legacy injections, provider memory behavior or native launch readiness.
-
-`completePreparedResources` now inventories and selects:
-
-| Stable block label | Retained file |
-| --- | --- |
-| `kernel:oats-portable` | `injects/oats-portable.md` |
-| `kernel:instance-boundary` | `injects/portable-instance-boundary.md` |
-| `work-mode:directory` | `injects/portable-work-directory.md` |
-
-Labels and order are unchanged. The captured resource bundle no longer includes the old instance-boundary or work-directory files. Other modes retain their own resource mapping rather than receiving directory behavior; unsupported materialization still refuses before creating a home. No old captured record or retained artifact is rewritten.
-
-The existing `ResourceRef`/`InstructionComposition` schema supports these exact file references without a wire change. Full persistent and helper records are validated against the shared structural schema, then their composed text and resource ownership/path/bytes are checked through the actual captured loader.
-
-The focused source-deleted composition regression verifies the combined portable kernel + boundary + directory doctrine: explicit execution binding and owned incarnation, canonical aliases, read-only retained source, authorized work surface, and no cwd/repo configuration authority or unsupported lifecycle/recovery promise. It asserts exact retained bytes and paths for both subject kinds, unchanged block order, absence of the specific old operative clauses, and refusal—not current-package fallback—after a retained boundary file is removed from the isolated fixture.
-
-The new resources' own retention tests remain resource-only evidence. The complete preparation/composition regression supplies the additional IC1 integration evidence. Existing legacy scaffold-only layout/retire coverage remains separate. Neither proves real provider privacy, managed runtime/helper start, or production acceptance.

package/docs/design/2026-09-17-portable-boundary-resources.md

@@ -1,52 +0,0 @@
-# Captured-only instance and directory boundaries
-
-## IC1 resource correction and ownership
-
-New resources:
-
-- `injects/portable-instance-boundary.md`
-- `injects/portable-work-directory.md`
-
-These are captured-only variants, not replacements for the legacy files. The
-resource owner creates/tests the new text; the lifecycle owner selects it in
-captured preparation and verifies the complete retained curriculum. This change
-alone does **not** wire the new resources into active compositions.
-
-Both variants preserve instance-home/work separation, canonical
-`AGENTS.md`/relative `CLAUDE.md` alias, generated instruction/metadata custody,
-read-only retained soul links, authorized edit surfaces and preservation of
-nonempty work/receipts. Authority is explicit captured deployment/resolution and
-matching owned-home incarnation—not cwd, a `repo` path, a config cascade or an
-alias. External reads do not authorize edits.
-
-The directory variant describes an owned execution directory, not a source or
-work-target checkout. It creates no policy requiring a knowledge layout,
-harvester, publication mechanism or storage backend. Capabilities define any
-knowledge/memory functionality. No-launch/launch-pending state is not a running
-runtime, and unsupported captured launch/start/restart/wake/retire/recovery has no
-legacy fallback or promised automatic recovery.
-
-## Lifecycle integration request
-
-In the **captured** resource inventory/selection only, retain the new boundary and
-directory variant instead of the old `instance-boundary.md` and
-`work-directory.md` text. Preserve existing labels/order as appropriate; update
-both capture inventory and its resource references together. Do not change old
-injections or legacy composition. Other work modes remain individually supported
-or refused by their owning implementation, not silently given directory behavior.
-
-Lifecycle's complete persistent/helper retained-text tests must demonstrate that
-the active portable skills plus kernel/boundary/work-mode blocks do not reintroduce
-cwd/`repo` configuration authority or unsupported lifecycle/recovery promises.
-Keep missing-resource, exact retention and helper policy guards intact.
-
-## Bounded local evidence
-
-`test/portable-onboarding-resources.test.mjs` checks the two new resources' required
-custody clauses and specific old contradictory instructions. It then retains
-fixture copies using the existing artifact store, removes only the fixture source,
-and renders those exact retained bytes through the existing composition formatter.
-It does not pretend this fixture is the full captured-preparation selector.
-
-No old injection, core/prepared-resources implementation, sibling test, provider,
-live deployment, main branch or runtime launch is changed by the resource commit.

package/docs/design/2026-09-17-public-captured-start.md

@@ -1,108 +0,0 @@
-# Public captured start and retained helper dispatch
-
-This is the public CLI bridge to [captured native session custody](2026-09-17-captured-native-start.md). It adds no backend, configuration resolver, provider action registry or harvester. CLI support and inert process evidence are not provider-worker, live-model, Pi-loader, privacy or rollout acceptance.
-
-## Callable interface
-
-```text
-oats session start|restart --deployment DEPLOYMENT --resolution RESOLUTION_ID \
-  --home NORMALIZED_ABSOLUTE_HOME [--helper EXACT_SOURCE_HELPER_KEY] \
-  [--request NORMALIZED_ABSOLUTE_JSON] [--retry-intent SAVED_EXECUTION_ID] [--json]
-```
-
-The existing global `capturedSelector` still owns selector parsing (including explicit pairs replacing poisoned inheritance as a unit). Only start/restart adopt this route. Current-context flags, runtime/model/yolo/config overrides and unknown/duplicate native flags refuse; no fallback to legacy session routing.
-
-Request files reuse the unchanged bounded strict object-file reader already used for preparation. Native request validation is separate: a closed object with required `schemaVersion:1`, and optional `backend`, `task`, `stopGraceMs`. Unknown fields are rejected before any projection; env/io/credentials/provider settings/selectors are not accepted. Symlinks/nonregular files, invalid UTF-8/JSON, malformed paths and bounds retain that shared reader's typed refusals. Its historical diagnostics may still say "preparation request"; it does not prepare or resolve anything on this route.
-
-```json
-{
-  "schemaVersion": 1,
-  "backend": {
-    "backend": "tmux",
-    "binary": "/absolute/host/tmux",
-    "socket": "/absolute/selected/socket",
-    "session": "captured"
-  },
-  "task": "Explicit initial task",
-  "stopGraceMs": 20000
-}
-```
-
-The backend is a closed tagged union: the tmux form above, or
-`{"backend":"herdr","binary":"/absolute/herdr","socket":"/absolute/herdr.sock","protocol":20}`.
-Herdr returns actual `workspaceId`/`paneId`/`terminalId` in target receipts; request
-fields never invent them or substitute tmux session/window names. See
-[backend parity and allocation custody](2026-09-17-captured-backend-parity.md).
-
-First start needs task/backend. Later calls can use owned TASK.md and native endpoint. A supplied null backend is invalid, not omission. Core validates all backend fields, availability, task text/bounds, stop grace 1–300000ms and exact captured native prerequisites before backend access. Endpoint relocation, contradictory residual native placement metadata and unsupported work/root/package/argument/contribution/backend paths refuse. First placement uses the exact admitted endpoint, not a legacy metadata fallback. Nothing is inferred from a current model/config alias.
-
-## Read-only API availability, separate from readiness
-
-Public `inspect` returns `result.nativeSession`; helper inspection also returns
-the same value as `helperSelection.launch`:
-
-```json
-{"schemaVersion":1,"api":{"contract":"oats.captured-session","version":2,"available":true,"backends":["tmux","herdr"]},"readiness":{"status":"not-checked"}}
-```
-
-This closed `CapturedNativeSessionAvailability` shape identifies the implemented
-callable request/result contract, not the selected record's or execution host's
-readiness. Core exposes the same static value through
-`capturedNativeSessionAvailability()`. Inspection has no target home/task/backend
-and performs no provider readiness/backend call, provisioning or admission. The
-descriptor stays `not-checked` before and after native dispatch; it never stores
-readiness as permanent authority. Missing launch recipes, approvals, supported
-roots/args/backends/contributions or clear custody still refuse during start.
-
-Consumers must recognize the contract/version, treat old/absent/unknown or
-contradictory descriptors as unqualified rather than fabricate a replacement,
-and still validate the actual action result/error and source/helper authority.
-API availability alone does not remove a provider's `E_CAPTURED_HELPER` gate or
-satisfy provider/runtime/Pi/privacy/release acceptance. The previous unreleased
-blanket helper launch-unsupported signal is not emitted alongside this descriptor.
-
-## Persistent and helper stages
-
-For a persistent home, use its own binding. For a helper:
-
-1. `inspect --helper EXACT_KEY` on the SOURCE selection returns the dedicated helper selection/name.
-2. Existing `spawn HELPER_NAME --deployment HELPER_DEPLOYMENT --resolution HELPER_ID --home NEW_HOME --no-launch --json` creates the fresh owned scaffold and runs retained hooks. It is not native dispatch.
-3. Invoke the new `session start` with SOURCE selectors, the same `--helper EXACT_KEY`, that owned home and the native request. The kernel revalidates the retained edge and context/human equality, then passes the HELPER binding to `startCapturedInstanceSession`. A source home or another helper home does not match and refuses.
-
-Passing a dedicated HELPER resolution directly to public `session start|restart`
-without the SOURCE edge refuses with `helper-not-selected`, before reading the
-native request or calling providers/backends. This applies to both tmux and Herdr;
-it emits no fabricated primary-shaped result or source/helper custody. The
-helper-ID scaffold stage above remains supported.
-
-An occupied home is not silently recreated. Hook failures/custody gaps remain held; this API does not add automatic hook replay or a compound scaffold/start transaction. Keep source completion calls on the source's saved binding, not the helper's inherited runtime selection. Static helper lookup uses the versioned availability/not-checked descriptor above; consumers require that qualified callable contract and real action result, never the lookup as proof of running status.
-
-## Provider-chosen home addressability and retirement gap
-
-A provider chooses a normalized absolute new home with a physical existing
-parent, then retains the returned home, incarnation, helper binding and hook/run
-receipts. Supported captured start/restart addresses that explicit home; it does
-not require an `agents/<soul>/instances` convention. Keep source completion on the
-source binding rather than deriving identity from this path.
-
-Captured public retirement is **not yet implemented** by this start/restart API.
-Legacy `retire --home` still enters agents-root/current-config machinery and is
-not a qualified workaround. Do not strip selectors, import private core helpers,
-guess an instance-root convention, force-delete or re-scaffold an uncertain home.
-Preserve the home/custody and hold complete ephemeral-worker lifecycle
-qualification until a public home-addressed captured retirement route is delivered
-and independently verified for both backends. API availability/version2 does not
-claim that missing lifecycle operation. A source candidate's commit/API version
-is also not its final published package compatibility floor.
-
-## Result and failure custody
-
-Success uses the existing one-object CLI envelope `{schemaVersion:1,ok:true,result}`. Result includes the canonical selected `executionBinding`, existing native target/history/intent fields and, for `--helper`, exact `sourceExecutionBinding` and `helper:{key,name,subject}`. Initial dispatch has `dispatchAccepted:true`. Completed explicit replay returns `replayed:true` with the saved receipt and intent; it does not dispatch again or certify a currently live process.
-
-Failure uses one nonzero envelope. Native uncertainty remains in `error.details.nativeCustody`, including admitted intent, pending path and observed native/history evidence; `details.unconfirmed:true` is not flattened into an ordinary static error. Source/helper bindings remain distinguishable in failure details. Preserve that evidence. Lifecycle mismatch/held publication debt is returned separately as `error.details.custody` with indexed/metadata status and any saved intent/receipt, without claiming a new native effect. New requests cannot bypass cleanup-required even when its intent is completed; that completed publication debt stays held for explicit reconciliation. Retry with `--retry-intent` names the saved logical ID; it cannot silently rerun an exited/absent uncertain dispatch under the same ID. A present non-shell same-ID pending restart is adopted and returned without another stop/dispatch, just like start. An unknown Herdr workspace allocation retains its existing pending phase/endpoint/intent and refuses duplicate allocation or label-based identity inference. A new distinct restart request gets a new execution ID within the same incarnation. There is no metadata wipe, ID derived from a home/name, or borrowed provider credential/context.
-
-## Evidence
-
-The public test prepares separate primary/helper launch records, removes source and poisons current config/lock, then uses CLI subprocesses for lookup, scaffold/hooks, native start, completed replay and restart. An actual fake-backend executable runs inert native executables; those processes verify indexed running admission before writing. This is not a private backend `io` seam or a real backend daemon/model.
-
-Refusals include unknown request/override fields, null/unsupported backend, wrong task, symlink request, conflicting flags, missing helper and wrong home, all before native backend access. Both backend fixtures additionally refuse direct helper-ID start/restart without the source edge, preserve metadata/index bytes and produce no backend/native effect, even when the supplied request file is absent (subject refusal precedes request reading). A backend fixture executes the native process and then fails its response; public JSON retains unknown custody. Retry preserves the execution ID/attempt chain and never runs the process twice. Occupied helper homes and their metadata are retained. Source completion/publication policy, Pi managed loaders, live credentials/models, and provider runtime integration are not tested or accepted by this fixture.

package/docs/design/2026-09-17-public-prepare-request.md

@@ -1,90 +0,0 @@
-# Public preparation request-file transport
-
-## Implemented helper; CLI routing remains lifecycle-owned
-
-`lib/portable-onboarding-request.mjs` implements:
-
-```js
-readPortablePreparationRequest({ file, inputFlags = {}, explicitSelector = null })
-```
-
-It returns the **request object itself**, decoded through existing bounded strict
-JSON and frozen without adding defaults or filtering fields. The public
-`prepareCapturedComposition` remains the only preparation schema validator and
-resolver. The helper does not call it and performs no installation, approval,
-activation, command dispatch or provider operation.
-
-- `file` is an explicit normalized absolute path. The shared descriptor reader
-  requires a regular file, uses no-follow opening and checks byte/identity changes;
-  its existing 8 MiB limit applies before content allocation.
-- `inputFlags` is the map of **other** prepare value flags already parsed by the
-  CLI's existing per-command parser. Any own key is a conflict, even when its
-  value is empty, false or null. Request/json controls do not belong in this map.
-- `explicitSelector` is the existing `capturedSelector(argv, {})` result or null.
-  Any non-null selector refuses. The helper neither parses global argv nor reads
-  inherited resolution/instance environment as preparation authority.
-
-Transport conflicts are rejected before opening the file. Invalid UTF-8,
-duplicate decoded JSON keys, oversized/deep data and non-object roots refuse.
-Read/decode diagnostics do not echo request payloads. Unknown preparation fields
-survive transport so the existing closed public validator can reject them. A
-private `directory` field must never be stripped to force acceptance.
-
-Requests must contain only nonsecret declarations/settings and the selected
-capability's supported credential references, never credential values. JSON shape
-validation alone cannot classify arbitrary provider payloads as nonsecret; that
-classification remains capability-owned. This helper adds no credential keyword
-filter, provider schema or destination default.
-
-## Minimal shared-entrypoint integration request
-
-Proposed command (not available in pinned c5/257 CLIs):
-
-```text
-oats prepare --request <absolute-regular-json-file> [--json]
-```
-
-The file contains exactly `buildFreshPreparationRequest(...).preparation`, **not**
-the outer onboarding result, private scratch, work-target wrapper or old execution
-binding. Lifecycle owner should:
-
-1. Keep existing explicit `--source` and `--workspace` forms unchanged. Add
-   `request` to the existing prepare value-flag parser; retain duplicate/missing/
-   unknown flag handling. Make request mode exclusive with every other source,
-   deployment and override flag before file reads. Do not merge CLI values into
-   request content.
-2. Pass that parser's other-value map and the shared explicit-only selector result
-   into the helper, then pass the full returned object to existing public prepare
-   and its existing result/error renderer. No copied preparation validator or
-   second config schema.
-3. At the existing global routing boundary, refuse explicit captured selectors
-   with prepare, before/after the command and in equals spelling. Use the shared
-   selector parser, not a new onboarding argv scanner. Preserve typed refusal of
-   partial/malformed selectors.
-4. Ignore inherited `OATS_DEPLOYMENT`, `OATS_RESOLUTION` and old instance context
-   for this explicit new-work request. Missing request values are not filled from
-   them. Other captured commands retain their normal inheritance semantics.
-
-The transport is not an installation permit or a serialized ready-inspection
-token. Fresh setup must recheck managed-state boundaries before its first mutating
-prepare. An explicit approval/reprepare continuation is ordinary preparation of a
-now-existing deployment, not a fresh preflight bypass or permission to delete it.
-
-## Evidence and remaining gates
-
-Parser tests perform no installation or activation. They verify literal
-string/null/boolean/list preservation, unknown-field forwarding, conflicting
-transport/selector refusal before reads, inherited-authority isolation, and
-bounded malformed/symlink/oversize refusals.
-
-The pinned real public preparation consumer now reads its entire request through
-this helper in workspace, keyed standalone and explicit-null contexts, then passes
-it unchanged to core at `c5c6a3c9171e424a36a1bdbf3932b9319a3c6c72`. It also proves
-that a private field survives transport and is rejected by real core before
-acquisition. The separate actual public no-launch producer case remains pinned to
-`257c4b96b67001fa2bcf38436e57106c44aa797b`.
-
-This is helper/public-API and no-launch evidence, **not** a claim that the proposed
-CLI router is installed, runtime launch is qualified, or private providers are
-certified. See the [operator walkthrough](2026-09-16-fresh-operator-walkthrough.md).
-No migration CLI, new installer engine, provider backend or global parser is added.