@awebai/oats 0.23.1 → 0.24.0

package/docs/provider-check-input.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oats.dev/schemas/provider-check-input-v1.json",
+  "title": "Provider check input v1",
+  "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/ProviderCheckInput"
+}

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

@@ -0,0 +1,49 @@
+# OATS v0.23.2 — Desktop Workspace redesign
+
+This release refreshes OATS Desktop around souls, instances and reported
+capabilities, while keeping lifecycle operations behind the installed OATS CLI.
+It builds on the released 0.23.1 kernel and knowledge contracts; it does not
+implement the proposed Portable Souls architecture.
+
+## Workspace and visual polish
+
+- A cleaner sidebar, aligned toolbar and soul cards, with a side inspector for
+  explicit Launch, Files and Schedule actions.
+- Workspace sections for **Souls**, **Capabilities** and **Sources**. Capability
+  health, installation, trust and activation are reported facts; Sources shows
+  provenance, not a new remote discovery or repository-admission feature.
+- **White** is the default theme, alongside explicit **Solarized** and **Dark**
+  choices. Existing valid theme preferences are retained.
+- Orange accents distinct from errors, quieter split controls, roomier instance
+  selection, darker navigation and colored marks for reported runtimes.
+- Stable muted soul marks. Optional local `soul.yaml` display metadata accepts
+  `color: sand`, `sage`, `slate`, `mauve`, `clay` or `olive`. Unknown values use a
+  deterministic identity-based fallback. Current remote CLI rosters do not report
+  this metadata; colors are decorative, never identity or status authority.
+
+## Working with instances and files
+
+- Workspace switches retain session-local tabs, selected panels and split sizes.
+- Closing a tab preserves its empty panel. Selecting that panel and reopening an
+  instance uses the selected destination; reusing an open terminal does not create
+  another attachment. Close split remains an explicit layout action.
+- **File: open read-only…** / **Mod+O** opens a native file chooser for sanitized
+  Markdown, highlighted code or plain text, alongside ordinary workspace tabs.
+  Files are read-only with a 2 MiB limit; no absolute-path guessing, sibling-file
+  access, editing or save workflow is introduced.
+- Soul Spawn no longer presents launch-configuration controls; the CLI's inherited
+  defaults remain authoritative. Quick Open inspects; Launch is always explicit.
+- Improved picker/shortcut focus handoffs and stale-selection protection across
+  workspace changes, roster refreshes and delayed operations.
+
+## Compatibility and boundaries
+
+Desktop supports the reviewed OATS 0.22.x and 0.23.x CLI contracts. Without a
+compatible installation it remains observation-only, with persistent recovery
+controls across Workspace sections. The root npm package still contains no
+Electron dependencies; Desktop remains a private, separately packaged app.
+
+New Knowledge/Tasks views, portable-soul membership/discovery and an agent-facing
+file-open CLI command are not part of this release. Workspace layout memory is
+session-local, not restart persistence. macOS assets retain the existing ad-hoc
+signing model; this release does not introduce Developer ID notarization.

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

@@ -0,0 +1,104 @@
+# OATS v0.24.0 — retained execution first cut
+
+This kernel/Pi/Desktop **0.24.0** cut covers the qualified retained-execution slice
+below. Source review, native acceptance, packaged-artifact validation, publication
+and deployment remain distinct facts; this note is not proof of any user's rollout.
+
+## Published official OKF pairing
+
+This cut pins **oats.okf 2.1.0**, requiring **OATS >=0.24.0**, at the existing
+`oats-package` source path. Published tag `v2.1.0` resolves to reviewed commit
+`f20f8e57a22bdffb48b34dee9bcbc03a9e0704db`. The existing finalizer verified the actual
+origin tag object, committed payload bytes/modes/alias and wrapper files; the mirror
+inventory now records that publication. Do not use an installed0.23.x kernel with
+this newer provider floor. Kernel versions are stamped by the existing tag lane;
+no compatibility check is bypassed.
+
+Before kernel publication, real retained primary and operation-created SOURCE workers
+completed on both tmux and Herdr, with qualified process/SDK outcomes, protected
+captured turns and independent directory-knowledge delivery. A separate real probe
+passed exact replay and distinct restart for all four homes, observing the supplied
+instruction heading and selected skill read without a controlled unrelated ancestor
+canary. The release-stamped kernel/adapter tarballs with this provider also passed
+actual installation and smoke outside the checkout. These results do not extend the
+explicit feature limits below or substitute for installed published-artifact checks.
+
+## Source-complete preparation and retained execution
+
+- Public `prepare --request` accepts one bounded nonsecret JSON input through the
+  shared strict reader and preparation validator. Source, deployment, work target
+  and workspace/standalone context remain distinct; no inherited current config
+  fills missing source authority. Exact executable approvals remain explicit.
+- Fresh onboarding detects existing managed state without deleting it. Inspected
+  deployment/work-directory replacement or later provisioning requires reinspection;
+  ordinary project edits remain allowed. This is a point-in-time check, not a lock
+  against concurrent writers or a general migration engine.
+- Captured instructions/resources, source identity and provider bindings remain
+  usable from retained bytes after the source is removed. Portable home/work
+  boundaries preserve canonical aliases and immutable source custody.
+- Captured primary/helper public start and restart use retained selections and
+  indexed incarnation/intent custody. A helper is launched through its exact
+  **SOURCE helper edge**, not by treating a dedicated helper ID as a persistent
+  source. Same-ID uncertainty is held rather than redispatched; failure receipts,
+  pending allocation, native history and cleanup obligations are preserved.
+- Provider execution keeps generic invocation, same-owner binding and explicitly
+  opted-in source-receipt inputs separate. Missing/invalid current transport does
+  not silently become legacy authority. Source-owned completion is not transferred
+  to a helper or invented instance.
+
+## Backends and first-cut Pi profile
+
+The shared native path supports the existing tmux and Herdr adapters. Herdr adapter
+selection understands exact protocols20 and22; it does not negotiate an unknown
+protocol, relabel a retained target or fall back to tmux. Public caller/schema support
+and the actual explicit server endpoint must match the selected protocol. API2
+availability/readiness-not-checked is not server, model or provider health.
+
+The first-cut Pi host target is explicit print-mode retained execution, not unrestricted
+interactive/plugin parity. Its packaged entrypoint, parser/native services, selected
+curriculum eligibility and external session-directory identity witness must be complete
+before that selected profile is usable. An absent/incomplete witness or required
+runtime/bridge/plugin contribution remains a refusal, never a dummy success or a
+silently dropped requirement.
+
+The user's already-authenticated harness retains its normal native profile,
+auth/helpers/OAuth/model configuration. This cut does not introduce an auth-file
+selector, credential inspection/copy, provider/key allowlist, empty production store
+or substitute profile. Strict selected curriculum and controlled native history are
+separate from that authentication boundary.
+
+## Desktop CLI compatibility
+
+Desktop's released-CLI band extends to `>=0.22.0 <0.25.0`, including0.24.x. Desktop
+CLI API remains **v1**; prereleases, wrong probe/API versions and failed probes still
+refuse. Optional execution/remote capabilities are advertised separately—version
+acceptance grants none of them. Observation-only degradation remains available when
+no compatible CLI is verified.
+
+This version-band update is not complete captured UI, Herdr0.9 terminal attachment,
+plugin, scheduling, retirement/recovery or all-platform Desktop parity. The existing
+release lane aligns kernel, Pi and Desktop manifests/locks together, retains package
+and installed-artifact checks, and keeps Desktop artifact gates before tag-workflow
+publication. Ad-hoc signing is not Developer ID notarization.
+
+## Explicit limits and safe adoption
+
+- No automatic reconstruction/in-place migration, old-state deletion, role-library
+  adoption or new operator-root/bootstrap-helper grammar is introduced.
+- Selected unsupported managed/plugin/bridge or interactive profiles stay held.
+  Default-OKF worker/capture/learning claims require the actual selected launcher,
+  real turn, captured result and accepted fresh-reader evidence—not seeded transcripts
+  or a successful scaffold. Git knowledge delivery remains PR-only.
+- Public captured retirement, wake and recovery remain separately bounded work;
+  do not strip selectors, use a legacy/private fallback, or delete an uncertain home
+  to simulate completion. Preserve old sessions, identities, work and receipts.
+- No private-aweb human/admin/privacy qualification follows from backend/model
+  success. External authority evidence cannot be fabricated by the framework.
+- Provider versions, catalog refs and compatibility floors must identify real
+  reviewed/published artifacts. This note does not finalize or repin them.
+
+Use a new explicit deployment/source request and the actual installed public contract.
+Do not assume parked source candidates or optional helper packages are published.
+Final release evidence must distinguish package installation, native dispatch, actual
+model/task completion, provider-worker behavior and learning; a narrow first-cut pass
+must not be presented as full parity.

package/docs/schedules.md

@@ -18,8 +18,16 @@ and no queue.
 
 ## Files
 
-- `<workspace>/oats-schedules.json` — the definitions (`{version: 1, jobs:
-  {<id>: ...}}`). Commit it if you want the schedule shared with the team.
+- `<workspace>/oats-schedules.json` — the definitions (`{version: 1|2, jobs:
+  {<id>: ...}}`). Version 1 is the legacy format. Adding the first explicit
+  version-2 execution upgrades the whole document to version 2 so an older
+  scheduler refuses it instead of ignoring capture policy. Existing legacy
+  entries may remain visibly unmigrated; new entries in a v2 file must declare
+  their policy. Commit the file if you want the schedule shared with the team.
+  Automatic wake creation uses this same document-version gate. Remote captured
+  mutations require advertised numeric schedule API 2 before forwarding; the old
+  feature-only gate is insufficient. Unclassifiable remote spec files also require
+  API 2. Legacy inline specs/read operations remain compatible with older hosts.
 - `<workspace>/.agents/schedules/state.json` — last attempted minute and
   last run per job (gitignored), plus one lock directory per running job.
 - `~/.oats/schedules/registry.json` — the host registry: which scopes the
@@ -29,6 +37,10 @@ and no queue.
   with the directory to remove, and the holder removes its own lock on exit
   and on SIGINT/SIGTERM. Definition edits take a short per-scope lock.
 
+The existing Desktop adapter can inspect/manage supported API-2 schedules, but its
+legacy editor refuses captured policy fields rather than dropping them. Full captured
+editing UI remains later Desktop work; use the explicit CLI for those definitions.
+
 ## Kinds
 
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
@@ -48,6 +60,8 @@ and no queue.
   from durable context; the job follows that worker until its home is gone.
   Command return is not task completion. Avoid binding durable work to a
   disposable source-home cwd; see [OKF v2 source jobs](#okf-v2-source-jobs).
+  New exact-record command definitions use the fields described in
+  [Captured execution and recurrence](#captured-execution-and-recurrence).
 - **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
   due minute inspects the instance at `home` through its session receipts.
   Running: `message` is delivered once with `session input`. Not running
@@ -77,6 +91,88 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
+## Captured execution and recurrence
+
+A new captured command definition is explicitly versioned and chooses its
+recurrence policy. Its containing schedule document is version 2:
+
+```json
+{
+  "id": "retained-job",
+  "definitionVersion": 2,
+  "recurrencePolicy": "capture",
+  "kind": "command",
+  "cwd": "/absolute/workspace",
+  "argv": [
+    "oats", "example-action", "run",
+    "--deployment", "/absolute/deployment",
+    "--resolution", "sha256-...",
+    "--", "--provider-argument", "--json"
+  ],
+  "responsibleHuman": null,
+  "cron": "0 * * * *",
+  "tz": "UTC"
+}
+```
+
+The admitted-attempt wire is published as
+[`execution-capsule.schema.json`](execution-capsule.schema.json). Runtime
+validation checks selector/target agreement. A canonical `oats.json.v1` digest
+of all fields except `executionId` is the separate content witness;
+`executionId` itself is opaque admission identity.
+
+`capture` requires the explicit deployment/resolution selector pair and
+`--json` in the **saved argv**. The scheduler never appends an unrecorded
+protocol argument to a captured target. Adding or updating the definition
+derives an immutable `execution` template containing that exact target,
+resolution, input references and explicitly supplied responsible-human value.
+It contains no execution ID; `executionStatus.contentIntegrity` exposes its
+canonical content witness. At each due tick the
+scheduler verifies the retained action first, then mints a fresh opaque
+`executionId`, writes the resulting capsule into the attempt before reserving a
+slot, and only then invokes the CLI. Thus two attempts with identical content
+have the same capsule digest but remain different intents. Definition edits
+affect later admissions only; an unknown attempt, `run`, or reconciliation never
+replaces its capsule with the edited definition or today's config/lock. Captured
+attempts carry their own `schemaVersion:1`; their launch-slot lock names the same
+`executionId`. A mismatching lock or malformed/unknown attempt version stays
+unresolved and cannot dispatch. Scheduler launch also scrubs ambient
+`OATS_DEPLOYMENT` and `OATS_RESOLUTION`; only the saved argv is authority.
+
+`prepare-on-tick` is a distinct explicit policy for a genuinely new command
+tick. Its `preparation` object maps directly to the generic
+`prepareCapturedComposition({deployment,source,workspace?,member?,operator?,mode?})`
+input; scheduler code does not parse source/workspace policy itself. Production
+uses the core adapter and tests may inject the same contract. Direct-source and
+workspace-alias requests are supported; `mode` is a work-mode string, not a nested
+launch object. A complete result must preserve the requested deployment and
+returned resolution, and contain `executionBinding` and an explicit
+`responsibleHuman` (`null` means messaging was actually disabled). The scheduler
+then inserts the exact selector pair before `--`, verifies the captured action,
+mints and persists the attempt, and dispatches. Missing adapters and incomplete
+results return typed `migration-required`/`needs-configuration` with no attempt.
+A dry run never invokes preparation or mints intent. There is no current-context
+fallback. Captured spawn and
+operation definitions remain unavailable until their public captured consumer
+adapters exist. A captured wake definition is accepted only when its target
+`instance.json` has an exact `executionBinding`; the binding is copied into the
+execution template and checked again at admission without consulting source or
+configuration. Actual captured wake delivery/start remains blocked with
+`migration-required` until the parent-owned lifecycle consumer lands. Legacy
+wakes continue through the old lifecycle boundary in this release.
+
+Definitions without `definitionVersion`/`recurrencePolicy` are legacy v1
+definitions. They retain the old release behavior during migration and are not
+reported as captured execution. `list`/`show` report their `executionStatus` as
+`{kind:"legacy",capture:"unknown",migrationRequired:true}`. A captured definition
+reports only `capture:"recorded"` until action admission verifies the retained
+record and current exact approval; it does not claim launch readiness. While an
+attempt is unresolved or its confirmed launched work still holds a slot,
+`executionStatus.intent` separately reports captured, legacy-unknown or invalid
+authority, so editing a future definition cannot hide an older admitted capsule.
+Partial, malformed or unsupported versioned
+definitions/attempts are invalid or blocked, never reinterpreted as legacy.
+
 ## Commands
 
 ```sh
@@ -100,20 +196,29 @@ running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
 
 ## What a run reports
 
-`launched` (spawn or command returned), `active` (the instance is running;
+`launched` (spawn or command returned), `blocked` (versioned execution
+admission refused before a launch slot or child process), `active` (the instance is running;
 a home whose retirement is pending still counts, its runtime 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
 succeeded.
 
+`blocked` includes an unavailable exact record/approval or incomplete new-work
+preparation, including not-yet-qualified provider bindings. The result preserves the typed
+`errorCode`; no attempt capsule or launch lock is created.
+
 `unknown` means the launch's side effects are unconfirmed: a command timed
 out or answered no envelope, an envelope named an instance the roster
 cannot place, or an attempt was never recorded. The job keeps its slot and
 is skipped until `oats schedule reconcile <id>`. Reconcile adopts only an
-attributable receipt: a spawn job's instance is named deterministically for
-its minute, a command job's only by the instance its answer named. Nothing
-is inferred from file times. A command whose answer named nothing stays
+attributable receipt: a legacy spawn job's instance is named deterministically
+for its minute. A captured command requires the SAME admitted execution ID and
+content witness, plus its explicitly recorded home and matching instance metadata;
+current-config roster lookup or a previous attempt's name cannot establish it.
+Nothing is inferred from file times. Observation validates custody before releasing
+slots, and unresolved attempts remain held even in the crash gap before a lock
+exists. Ordinary removal refuses those attempts; force-forget remains explicit. A command whose answer named nothing stays
 unknown; check the roster and the host by hand, then
 `oats schedule reconcile <id> --clear` records launch-failed and frees the
 slot (or `remove --force` forgets the job).
@@ -132,13 +237,14 @@ or malformed definition is reported on that job and the rest of the tick
 continues.
 
 `disable` never stops anything. `update` never touches a running instance,
-and while a job holds a slot or has an unresolved attempt what its run is
-tracked or reconciled by (kind, agent, agentsRoot, repo, purpose, home, cwd,
-argv) cannot change; cron, tz, task, message, runtime, model 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 at worst.
+and while a job holds a slot or has an unresolved attempt its complete
+execution identity (including a versioned capsule), kind and target cannot
+change; cron, tz and enabled can. Legacy definitions retain their narrower
+compatibility behavior until migrated. 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
+at worst.
 `remove` refuses while the job's instance is still tracked (`--force`
 forgets the job without stopping anything). Retiring an instance removes the
 wake jobs bound to its home; a wake whose home is gone otherwise stays
@@ -150,7 +256,13 @@ listed with its skipped reason.
 saves a wake job `wake-<instance>` bound to the new home after the spawn
 succeeded. If the spawn succeeds but the save fails, the spawn result still
 carries the full instance receipt, plus `wakeScheduleError` and a warning;
-the instance is neither hidden nor spawned again.
+the instance is neither hidden nor spawned again. When the spawning consumer
+supplies both the returned `executionBinding` and `responsibleHuman`,
+`saveWakeForHome` creates a version-2 captured wake from the matching binding in
+the new home. Supplying only one, or a result binding that differs from the
+home, refuses. The current parent-owned spawn caller still needs to pass these
+fields when its captured lifecycle path lands; omission retains explicit legacy
+behavior rather than inventing a binding.
 
 ## OKF v2 source jobs
 

package/docs/soul.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://oats.dev/schemas/soul-v1.json",
+  "title": "Portable soul declaration v1",
+  "description": "Authored shape only. The shared source codec, provider codec and preparation transaction enforce source semantics, containment, requirements and readiness.",
+  "type": "object",
+  "required": ["schemaVersion", "name"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "name": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "description": { "type": "string" },
+    "requires": { "$ref": "#/$defs/requirements" },
+    "defaults": { "$ref": "#/$defs/defaults" },
+    "knowledge": {
+      "type": "object",
+      "required": ["contract", "version", "payload"],
+      "additionalProperties": false,
+      "properties": {
+        "contract": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
+        "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+        "payload": {}
+      }
+    },
+    "teams": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }
+    },
+    "resources": {
+      "type": "array", "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^(?:\\.|(?![A-Za-z]:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/\\\\\u0000]+(?:/[^/\\\\\u0000]+)*)$" }
+    },
+    "work": { "enum": ["worktree", "checkout", "attached", "workspace", "directory"] },
+    "runtime": { "enum": ["pi", "claude", "codex"] },
+    "model": { "type": "string", "minLength": 1 },
+    "launch-config": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+    "backend": { "enum": ["tmux", "herdr"] },
+    "yolo": { "type": "boolean" }
+  },
+  "$defs": {
+    "source": { "type": "string", "pattern": "^(git|repo|path):.+$" },
+    "capability": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "selection": {
+      "type": "object", "required": ["source"], "additionalProperties": false,
+      "properties": { "source": { "$ref": "#/$defs/source" }, "settings": { "type": "object" } }
+    },
+    "provider": {
+      "type": "object", "required": ["capability", "source"], "additionalProperties": false,
+      "properties": {
+        "capability": { "$ref": "#/$defs/capability" },
+        "source": { "$ref": "#/$defs/source" },
+        "settings": { "type": "object" }
+      }
+    },
+    "requiredProvider": { "anyOf": [{ "const": "any" }, { "$ref": "#/$defs/provider" }] },
+    "defaultProvider": { "anyOf": [{ "const": "none" }, { "$ref": "#/$defs/provider" }] },
+    "requirements": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "capabilities": {
+          "type": "object", "additionalProperties": false,
+          "patternProperties": { "^[a-z0-9][a-z0-9._-]*$": { "$ref": "#/$defs/selection" } }
+        },
+        "knowledge": { "$ref": "#/$defs/requiredProvider" },
+        "messaging": { "$ref": "#/$defs/requiredProvider" },
+        "tasks": { "$ref": "#/$defs/requiredProvider" }
+      }
+    },
+    "defaults": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "capabilities": {
+          "type": "object", "additionalProperties": false,
+          "patternProperties": { "^[a-z0-9][a-z0-9._-]*$": { "anyOf": [{ "$ref": "#/$defs/selection" }, { "const": false }] } }
+        },
+        "knowledge": { "$ref": "#/$defs/defaultProvider" },
+        "messaging": { "$ref": "#/$defs/defaultProvider" },
+        "tasks": { "$ref": "#/$defs/defaultProvider" }
+      }
+    }
+  }
+}

package/injects/oats-portable.md

@@ -0,0 +1,17 @@
+## You run on a captured OATS composition
+
+You are an instance of a retained soul/helper composition selected by
+`instance.json.executionBinding`. Managed instructions, skills, capabilities,
+settings, provider bindings, and executable resources come from that exact
+`deployment` + `resolution`; do not replace them with a current checkout,
+configuration cascade, package lock, similarly named capability, or source path.
+
+Load **oats-portable** before invoking or reasoning about captured OATS commands.
+Load **oats-portable-setup** for fresh by-reference preparation and explicit
+source/workspace/deployment/work/team choices. Load **oats-portable-artifacts**
+for exact retained inspection and approval. Do not load the legacy **oats**,
+**oats-config**, or **oats-packages** procedures to fill a captured input.
+
+Captured start/restart/wake/retire, managed launch/runtime and non-directory work
+are not yet public. If a command is unsupported or retained authority is missing,
+stop and report it; never remove selectors or fall back to ambient configuration.

package/injects/portable-instance-boundary.md

@@ -0,0 +1,39 @@
+## Captured instance: home, source and work
+
+**Your instance home** is the specific OATS instance directory supplied as
+`OATS_INSTANCE_HOME`, not your user home, source repository or work target.
+`instance.json.executionBinding` names the explicit captured **deployment and
+resolution**. Home-bound actions must also match this owned home's incarnation
+and recorded custody. Do not invent, copy or rewrite those identifiers to make
+another home or composition appear authorized.
+
+- **Home holds composed instructions and instance state.** `AGENTS.md` is the
+  canonical composed instruction file; `CLAUDE.md -> AGENTS.md` is its relative
+  compatibility alias, not a second instruction source. Preserve the generated
+  instructions, aliases and metadata; do not hand-edit them to change authority.
+  Task material and provider-managed state belong where their owning contract
+  specifies. The selected capabilities define any knowledge or memory protocol.
+- **`./soul` is a read-only retained source link, not your edit surface.** Reading
+  it must not depend on the publisher's current checkout. Never write through it
+  or modify retained artifacts. If a task authorizes source changes, use its
+  explicitly authorized tracked work surface and review path instead.
+- **`./work` is the task's work surface.** The work-mode instructions determine
+  whether it is an owned directory or another permitted repository view. Make
+  task edits only on that authorized surface, not in deployment stores or a
+  convenient source checkout. Reading an external input is not permission to
+  modify it or its owner.
+
+For supported captured commands, keep the explicit `--deployment` and
+`--resolution` pair from the recorded binding; supply the exact owned home when
+an action requires one. Running from home preserves the invocation's working
+location, but **cwd and a recorded `repo` path never select configuration or
+execution authority**. Source location, deployment, work target and team
+membership are separate facts. Do not fill missing inputs from a config cascade,
+a current lock, an alias match or another instance's environment.
+
+Load **oats-portable** for the running kernel's supported captured operations.
+A no-launch scaffold or `launchPending` receipt is not a running agent. Where
+captured launch, start/restart/wake/retire or recovery is unsupported, stop and
+report the limitation; do not strip selectors or use a legacy command as a
+workaround. Preserve work, knowledge, native history, identities and outstanding
+cleanup receipts. Missing authority is a hold, never permission to erase state.

package/injects/portable-work-directory.md

@@ -0,0 +1,29 @@
+## Portable work mode: owned directory
+
+Your `./work` is an **instance-owned execution directory**, not a Git worktree,
+a checkout, or a link to the source, deployment or another instance. No Git
+repository or branch is created by this mode. Do not initialize a fake repository
+to satisfy a workflow; a containing Git repository does not grant authority over
+its contents.
+
+- Do task work inside `./work`. External inputs and delivery destinations require
+  explicit task/capability authorization. Neither a source link nor a recorded
+  `repo` or work-target path grants permission to edit that external directory.
+- Execution uses the explicit captured deployment/resolution and, for home-bound
+  actions, the matching owned home/incarnation binding. Cwd does not resolve
+  configuration or select a provider; do not rebind from a current checkout,
+  config cascade, package lock or another instance.
+- Preserve home/work separation and canonical instruction aliases:
+  `AGENTS.md` in home, `CLAUDE.md -> AGENTS.md`, and the generated skill aliases.
+  The home's `./soul` link and retained software are read-only, not edit surfaces.
+- Deliver results using the task and selected capability's supported protocol.
+  This mode imposes no knowledge layout, harvester, storage backend or publication
+  policy. A recovery copy, if independently verified, is not publication or
+  accepted delivery.
+
+Keep nonempty work and its custody evidence intact. This mode does not promise
+implemented captured launch, start/restart/wake/retire or automatic recovery.
+Before any supported, explicitly authorized teardown, require verified
+preservation of outstanding work and receipts; if that capability is unavailable,
+hold and report rather than deleting or moving the home/work yourself. A
+`launchPending` result means runtime launch remains pending.