@awebai/oats 0.23.2 → 0.24.1

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.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/release-notes/v0.24.1.md

@@ -0,0 +1,17 @@
+# OATS v0.24.1 — workspace adoption, public inspection, captured custody on the home route
+
+Kernel/Pi/Desktop **0.24.1**. Publication is not deployment; every operator still installs, approves and qualifies locally.
+
+## What changed
+
+- **Framework repository joins the Git workspace model.** `oats-workspace.yaml` (workspace `oats-development`, seven intended members) and `oats.yaml` (exports: transitional `souls/oats-expert` edition, `oats-package`, `capabilities/oats-authoring`) are published at the repository root. Member indexes are on `main` in oats-okf, oats-aweb, oats-authoring and oats-jira. Membership is discovery, not activation; `imports` stay empty until sources are pinned at reviewed revisions.
+- **`oats inspect --request <absolute-json> [--json]`** — read-only inspection of a source/workspace/member through the existing onboarding facade. Metadata only: provider payloads and adoption values are omitted, no deployment state or approval is touched, captured selectors are refused.
+- **Captured custody on the home-only session route.** `oats session inspect|input --home H` now applies the existing captured incarnation/custody checks for captured homes and refuses before any transport when the home was replaced (integrity drift). Non-captured homes are unchanged. This is the route the aweb broker uses.
+- **OKF 2.1.1 pairing.** The mirror, `package-catalog.json` ref and the transitional soul's source pin `oats.okf@v2.1.1`: ordinary Claude/Codex helpers with a complete approved capability closure are accepted by the OKF consumer; strict Pi still requires an explicit model and the sole-OKF profile.
+- **Official marketplace policy** — `docs/official-marketplace.md`: the reviewed `package-catalog.json` list *is* the official marketplace; listing is by maintainer-reviewed PR; discoverable ≠ installed ≠ approved.
+- **Kernel setup skill removed.** `skills/oats-portable-setup` is deleted on the human's instruction; setup guidance moves to the planned `oats.setup` capability (see the [decision](https://github.com/awebai/oats/blob/main/agents/oats-expert/soul/knowledge/decisions/official-capabilities-oats-core-setup-and-marketplace.md)).
+- Docs: `docs/workspaces.md`, `docs/workspace-adoption.md`, condensed `docs/layers.md`, `docs/design/README.md` navigation, program board.
+
+## Not in this cut
+
+`oats.core` / `oats.setup` capabilities, explicit default `oats.core` on soul creation, `oats-setup-expert` onboarding, the five expert soul editions, the aweb portable adapter (aweb 1.10.3 still has no binding interface) and Desktop marketplace views are in progress — see the [program board](../design/2026-09-20-redesign-program-board.md).

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/docs/souls-and-instances.md

@@ -1,8 +1,19 @@
 # Souls and instances
 
-Souls and instances are the two layers the OATS kernel owns. A soul is the
-expert. An instance is a named incarnation of that expert, with its own ID,
-home, worktree, and lifecycle. It is not the same thing as one chat session.
+Souls and instances are the two layers the OATS kernel owns. A soul defines a
+reusable specialisation. An instance is a named working incarnation, with its own
+ID, home, work view and lifecycle—not necessarily one task or chat session.
+
+An instance may be ephemeral, such as a developer or reviewer doing bounded work,
+or long-running, carrying planning, investigation and domain understanding across
+many tasks. Lifetime does not itself change the soul's identity. See the
+[canonical knowledge and specialisation model](knowledge-theory.md) for how skills,
+shared knowledge, working context and state differ.
+
+This operational guide includes the configuration-based soul and lifecycle forms.
+Portable source definitions and captured lifecycle have their own versioned scope;
+see the [0.24 release notes](release-notes/v0.24.0.md) rather than assuming every
+legacy example below applies to a captured instance.
 
 ## Soul anatomy
 
@@ -45,10 +56,12 @@ runtime-specific guidance, while keeping `AGENTS.md` canonical.
 
 ## Instance anatomy
 
-An instance is transient, but it is not a single chat session. It is the
-identity of one instantiated soul while that work is alive. Several sessions,
-compactions, restarts, or model switches can happen inside the same instance
-before it is retired.
+An instance has a lifecycle, but need not be short-lived. It is the identity of
+one instantiated soul while its assignment is alive. Supported session continuations,
+compactions and restarts can preserve that continuity. Model or harness changes must
+follow the selected execution profile; they are not permission to reinterpret a
+captured recipe. Retirement should account for valuable context and unfinished work,
+not assume an experienced instance is cheap to replace.
 
 An instance has a home directory, a task, and a worktree when the work mode
 needs one. Its runtime setup is composed from the canonical soul plus