@awebai/oats 0.24.7 → 0.24.9

package/capabilities/oats-okf/lib/worker.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { isAbsolute, resolve } from 'node:path';
 import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, oats, command, fail, relPath } from './io.mjs';
-import { loadSource, loadStatus, saveStatus, updateStatus, capture, input, markerPath, homeSource } from './sources.mjs';
+import { loadSource, loadStatus, saveStatus, updateStatus, capture, input, markerPath, homeSource, settleRetiredSchedule } from './sources.mjs';
 import {capturedSource,qualifyCapturedWorker,assertCapturedRun,capturedScaffold,retainCapturedWorkerCustody,assertCapturedWorkerHome,capturedStart} from './captured-worker.mjs';
 import { metadata, splitRef } from './config.mjs';
 import { stageBase, validateBase, allowedChanges, verifyGitScope, gitPublish, directoryPublish, journalPath, baseLock, recoveryStage, reconcileDirectoryIntent, gitRecoveryState } from './stores.mjs';
@@ -63,7 +63,10 @@ export function runSource(source,{noLaunch=false,manual=false,capturedInvocation
     const previous=status.pendingRejudgment?readRun(source,status.pendingRejudgment):null;
     if(previous) checkRecoveryGuards(source,previous);
     const ids=previous?previous.inputs:status.captured.inputs.filter(id=>!status.processed.includes(id));
-    if(!ids.length) return status.finalCaptureUncertified?{status:'source-unavailable',processedCapturedInput:true,finalCaptureComplete:false}:{status:'empty',processed:true};
+    if(!ids.length) {
+      if(status.retired && !status.finalCaptureUncertified) {updateStatus(source,current=>{current.auto=false;});settleRetiredSchedule(source);}
+      return status.finalCaptureUncertified?{status:'source-unavailable',processedCapturedInput:true,finalCaptureComplete:false}:{status:'empty',processed:true};
+    }
     const selected=[];let bytes=0;
     for(const id of ids) {const n=Buffer.byteLength(JSON.stringify(input(source,id)));if(selected.length && bytes+n>192000) break;selected.push(id);bytes+=n;}
     if(!source.decl.owns.length) fail('E_OWNER','source has evidence but owns no destination; retained for explicit ownership routing');

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -62,7 +62,16 @@
       "setting state-dir must be a normalized absolute host path",
       "setting harvest-runtime is required (pi, claude or codex)",
       "setting harvest-runtime must be pi, claude or codex",
-      "setting harvest-model must be null or a non-empty string"
+      "setting harvest-model must be null or a non-empty string",
+      "check action is not an admitted knowledge operation",
+      "bound runtime bindings file is missing or invalid",
+      "more than 64 git knowledge bases declared",
+      "declared knowledge base could not be staged from its git source",
+      "declared knowledge base is not a validated knowledge tree",
+      "knowledge base owner or remote custody requirement not met",
+      "staged git source does not match the declared knowledge base",
+      "harvest runtime command is not installed on this host",
+      "harvest runtime could not be qualified against the accepted bases"
     ]
   },
   "inject": "injects/okf.md",
@@ -76,13 +85,17 @@
       "command": "bin/oats-okf.mjs spawn",
       "required": true,
       "inputs": {
-        "sourceReceipt": { "version": 1 }
+        "sourceReceipt": {
+          "version": 1
+        }
       }
     },
     "retire": {
       "command": "bin/oats-okf.mjs retire",
       "inputs": {
-        "sourceReceipt": { "version": 1 }
+        "sourceReceipt": {
+          "version": 1
+        }
       }
     }
   },
@@ -99,8 +112,18 @@
       "context": "home",
       "description": "Capture this source into durable custody and request an independent worker.",
       "args": [
-        {"name": "native-request", "flag": "--native-request", "required": false, "description": "Captured operations require an explicit absolute backend-only native request JSON; provider owns the worker task."},
-        {"name": "worker-mode", "flag": "--worker-mode", "required": false, "description": "Captured worker mode: prepare or launch (default launch); legacy behavior is unchanged when absent."}
+        {
+          "name": "native-request",
+          "flag": "--native-request",
+          "required": false,
+          "description": "Captured operations require an explicit absolute backend-only native request JSON; provider owns the worker task."
+        },
+        {
+          "name": "worker-mode",
+          "flag": "--worker-mode",
+          "required": false,
+          "description": "Captured worker mode: prepare or launch (default launch); legacy behavior is unchanged when absent."
+        }
       ]
     }
   }

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-21 19:25Z (earlier stamps reading 2026-09-22 were a lead clock error — the work happened 2026-09-21; corrected on Antares's observation) · S8: 1a/1b/3/4/6a/7a MERGED · K1+K4 MERGED · engineer → 2a · lead → P1 Decision, K3, K5; tag 0.24.7 once 2a lands
+**Last update:** 2026-09-22 17:30Z · main `1b8349e5` · Slice 5 ✅ (PR71) · security follow-up ✅ (PR73) · K5 pins ✅ (PR74/75) · **K6b ✅ (PR76: `spawnPreviewApi 2` / `spawn-preview-2` — side-effect-free preview, `--agents-root`, `--expect-decision`/`E_DECISION_STALE`, bounded preflight)** · **PR77 ✅ killGroup pid-0 guard (HIGH; engineer-found)** · OKF 2.1.3 ✅ · engineer → **6b READ wiring** (API 2 gate) → 6b apply companion (proposal) → 7b → 8 · open contracts: K11 admission, attach-knowledge (OKF node refs), auto-PR (P1 write approval), branch enumeration · **0.24.9** after 6b read (release-notes file FIRST)
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 
@@ -17,7 +17,7 @@ Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, n
 | S5 | Official marketplace = reviewed list in oats repo | ✅ D4 merged · ✅ `oats.framework` 1.1.1 listed (`oats.core`, `oats.setup`, `oats.knowledge-theory` aliases) | M | Desktop view → S8 |
 | S6 | Five expert souls created in the oats repo (`souls/<name>/`) | ✅ five + `oats-setup-expert` on main, all declaring `oats.core`, exported + imported | M, L, lead | legacy `agents/` cutover after S7 proof |
 | S7 | Centralised per-soul knowledge in `oats-knowledge` (migration + PR-only learning) | ✅ **MIGRATED — PR #2 merged → main `7148a36`, 58 concepts / 35k words from 399 legacy** (kernel 26, expert 18, desktop 13, assistant 1, market-research chartered empty); option A roster; theory + no-code-teaching rule; two workflow passes (24 agents) + lead review; validator 58/0/0; ownership 14/14 · ⏸ harvest OFF until new souls run from the base (human) | lead | next: legacy `agents/` decommission with the `~/OATS` cutover |
-| S8 | Desktop parity with the redesign (Redesign v3, aweb palette, discovery-first control panel) | 🔄 **STARTED 2026-09-22**: existing `oats-desktop-engineer-1` retrofitted with an aweb identity (spawn hook replayed, `capabilityMeta` persisted, session reloaded); redesign artefacts copied into its home; brief sent (f16eed3f): merge main (0.24.5) first, then PR slices — shell/palette/sidebar → right panel follows selection → Souls view → **Capabilities view incl. official catalog (human's required feature; server-side via kernel catalog API, never auto-acquire/auto-trust)** → Knowledge/Tasks adapters → remainder. Lead reviews/merges each slice. **Decisions 2026-09-22:** human's later palette/row instructions supersede the HTML where they conflict; grouping is agent-group (cross-repo clusters), not repo; kernel seam `oats catalog --json` merged (PR46 `524180b7`, ships 0.24.6); the Juan-host fresh-engineer plan is superseded — this instance owns S8. | oats-desktop-engineer-1, lead | per-slice PRs | ✅ **Slice 3 MERGED** (PR54; Souls + Sources on K4 soulsApi 1; 1503/1503) · ✅ **K1 MERGED** (PR53; `oats instance git|diff`, instanceGitApi 1; DTO in docs/desktop-cli-api.md) · ✅ **K4 MERGED** (PR52; `inspect --json` soulsApi 1: declarations/provenance/readiness/sources; onboard records provenance; DTO in docs/desktop-cli-api.md) · ✅ **Slice 7a MERGED** (PR51; frame 07 Active overview on /api/panel; anonymous groups; 1466/1466) · ✅ **Slice 6a MERGED** (PR50; Spawn modal frame 02 on existing seams; launchConfig restored; 1435/1435) · ✅ **Slice 4 MERGED** (PR49; Capabilities view: official catalog via `oats catalog` + classic inventory; 1386/1386; server boundary reviewed) · ✅ **Slice 1b MERGED** (PR48; contextual panel + focus mode; 1238/1238) · ✅ **Slice 1a MERGED `508c4b5f`** (PR45; 273/273 real jsdom; gates green) → v0.24.6. **Plan + seams recorded: [`docs/design/2026-09-22-desktop-parity-seams.md`](2026-09-22-desktop-parity-seams.md)** — slices 1a–8, seams K1–K8/P1, five policy decisions **DECIDED 2026-09-22 under delegation** — see `decisions/desktop-parity-lifecycle-and-policy-decisions.md`.
+| S8 | Desktop parity with the redesign (Redesign v3, aweb palette, discovery-first control panel) | 🔄 **STARTED 2026-09-22**: existing `oats-desktop-engineer-1` retrofitted with an aweb identity (spawn hook replayed, `capabilityMeta` persisted, session reloaded); redesign artefacts copied into its home; brief sent (f16eed3f): merge main (0.24.5) first, then PR slices — shell/palette/sidebar → right panel follows selection → Souls view → **Capabilities view incl. official catalog (human's required feature; server-side via kernel catalog API, never auto-acquire/auto-trust)** → Knowledge/Tasks adapters → remainder. Lead reviews/merges each slice. **Decisions 2026-09-22:** human's later palette/row instructions supersede the HTML where they conflict; grouping is agent-group (cross-repo clusters), not repo; kernel seam `oats catalog --json` merged (PR46 `524180b7`, ships 0.24.6); the Juan-host fresh-engineer plan is superseded — this instance owns S8. | oats-desktop-engineer-1, lead | per-slice PRs | ✅ **Slice 2b MERGED** (PR65; Connections + PR card; 1654/1654) · ✅ **K5+K6 MERGED** (PR63; readiness quartet/signatures/enforced child policy; spawn --preview/--base/@native-default) · ✅ **K7+K8 MERGED** (PR64; typed instance events; schedule recentRuns) · ✅ **K3 MERGED** (PR62; `instance stop --plan|--apply`, `retire --plan`, retention-by-default retire with re-home) · ✅ baseline flakes fixed (PR61) · ✅ **P1 decided + K1 `remote` MERGED** (PR60) · ✅ **Components (frame 10, existing data) MERGED** (PR59; 1606/1606) · ✅ **Slice 2a MERGED** (PR57; Git panel on K1; legacy gitState collector removed) · ✅ **v0.24.7 tagged/published** (tag → `c923d81b`) · ✅ **Slice 3 MERGED** (PR54; Souls + Sources on K4 soulsApi 1; 1503/1503) · ✅ **K1 MERGED** (PR53; `oats instance git|diff`, instanceGitApi 1; DTO in docs/desktop-cli-api.md) · ✅ **K4 MERGED** (PR52; `inspect --json` soulsApi 1: declarations/provenance/readiness/sources; onboard records provenance; DTO in docs/desktop-cli-api.md) · ✅ **Slice 7a MERGED** (PR51; frame 07 Active overview on /api/panel; anonymous groups; 1466/1466) · ✅ **Slice 6a MERGED** (PR50; Spawn modal frame 02 on existing seams; launchConfig restored; 1435/1435) · ✅ **Slice 4 MERGED** (PR49; Capabilities view: official catalog via `oats catalog` + classic inventory; 1386/1386; server boundary reviewed) · ✅ **Slice 1b MERGED** (PR48; contextual panel + focus mode; 1238/1238) · ✅ **Slice 1a MERGED `508c4b5f`** (PR45; 273/273 real jsdom; gates green) → v0.24.6. **Plan + seams recorded: [`docs/design/2026-09-22-desktop-parity-seams.md`](2026-09-22-desktop-parity-seams.md)** — slices 1a–8, seams K1–K8/P1, five policy decisions **DECIDED 2026-09-22 under delegation** — see `decisions/desktop-parity-lifecycle-and-policy-decisions.md`.
 
 ## S1 — Knowledge capability contract rework
 - ✅ Provider-neutral contract, binding wire v1, helper/input contract, retained execution: OATS 0.24.0 + OKF 2.1.0 (f20f8e57) published.

package/docs/design/2026-09-22-desktop-parity-seams.md

@@ -34,9 +34,9 @@ Envelope `{schemaVersion:1, ok, result|error}` unchanged. Requests address a ser
 - **K2 review-thread delivery**: explicit, confirmed send of selected threads to the exact home's session input with receipt (`delivered | refused | unknown`); delivered ≠ consumed. Typed producer events for commit / branch-renamed / PR-updated / review-request; **no prose parsing** to infer actions.
 - **K3 lifecycle plan/apply**: read-only plan (runtime activity, children, worktree dirt, branch + open PRs, retention per artefact, per-option allowed/default/reason, warnings, blockers) → apply with plan revision + idempotency key, revalidated under the lifecycle lock; per-target `completed | retained | partial | unknown`. Today there is **no standalone stop**, and retire removes owned worktrees; the design's default Remove retains worktree/branch/PR.
 - **K4 souls/sources enumeration** (✅ MERGED PR52 as additive `inspect --json` `soulsApi:1`, not a new command — see docs/desktop-cli-api.md): qualified list of imported editions + authored local souls with identity/source/revision/requirements/declarations/editability; readiness separate from launchability and adoption; no renderer YAML.
-- **K5 readiness quartet**: `installed | trusted | configured | enrolled`, each `pass | fail | unknown | not-applicable` with items (subject, requiredness, reason, producer, evidence, remedy); trust separates artifact approval from `signature {verified|unsigned|unknown|invalid, signer}`; policy view returns **enforced** child-spawn/worktree permissions with origins; native config items report labels/scope state, never secrets; unknown ≠ granted.
-- **K6 spawn preview/apply** (add, 2026-09-22 from 6a review: an explicit `model: {kind: "native-default"}` request field — today an omitted model inherits the configured/soul model and there is no force-native override; 6a renders that control disabled until K6): kernel returns suggestions, canonical worktree/home/branch/base OID, resolved knowledge refs, enforced child policy, auto-PR policy, readiness, typed field problems; apply revalidates and captures; no Desktop-derived paths or branches.
-- **K7 activity feed**: bounded typed events per instance with provenance; "waiting on you" only from a producer that reports it.
+- **K5 readiness quartet** (✅ MERGED PR63 — `oats readiness`): `installed | trusted | configured | enrolled`, each `pass | fail | unknown | not-applicable` with items (subject, requiredness, reason, producer, evidence, remedy); trust separates artifact approval from `signature {verified|unsigned|unknown|invalid, signer}`; policy view returns **enforced** child-spawn/worktree permissions with origins; native config items report labels/scope state, never secrets; unknown ≠ granted.
+- **K6 spawn preview/apply** (✅ MERGED PR63 — `oats spawn --preview`, `--base`, `--model @native-default`) (add, 2026-09-22 from 6a review: an explicit `model: {kind: "native-default"}` request field — today an omitted model inherits the configured/soul model and there is no force-native override; 6a renders that control disabled until K6): kernel returns suggestions, canonical worktree/home/branch/base OID, resolved knowledge refs, enforced child policy, auto-PR policy, readiness, typed field problems; apply revalidates and captures; no Desktop-derived paths or branches.
+- **K7 activity feed** (✅ MERGED PR64 — `oats instance events`): bounded typed events per instance with provenance; "waiting on you" only from a producer that reports it.
 - **K8 schedule run history** + captured-policy-preserving edit contract; transcript access via the owning CLI/provider.
 
 ## Decisions — DECIDED 2026-09-22 (lead, delegated by the human)
@@ -55,4 +55,4 @@ Also to confirm: prototype "Gemini" runtime is illustrative (not an OATS runtime
 
 ## Ownership
 
-Lead: K1, K4, K5 (readiness/policy shape), K6 preview/apply plumbing, K7/K8 projections, dispatch contract for additive-capability views — proposed as Decisions where they change contracts, implemented in small PRs otherwise. P1: a new capability (`oats.git`/GitHub backend) — spec'd as a Decision with the human; implementation lane TBD. Desktop engineer: all slices, Desktop IPC review items (detach, open-in-editor).
+Lead: K1, K4, K5 (readiness/policy shape), K6 preview/apply plumbing, K7/K8 projections, dispatch contract for additive-capability views — proposed as Decisions where they change contracts, implemented in small PRs otherwise. P1: **forge connections are ADE/workstation integrations, not capabilities** — **Decision ACCEPTED** (`agents/oats-expert/soul/knowledge/decisions/p1-forge-connection-is-an-ade-integration.md`). Desktop *Connections* surface (GitHub card: status / Connect = `gh auth login --web` in an owned pane / Disconnect), PR card read by the Desktop server via fixed-argv `gh pr view … --json` at the existing guarded boundary, typed states (available / no-pull-request / not-connected / cli-not-installed / unsupported-forge / no-remote / unavailable), remote workspaces refuse; OATS never holds a token. No kernel dispatch contract. Kernel: K1 gains `remote {name,url,host,path}` (lead). Slice **2b** = Connections + PR card (engineer; lead security gate before wiring). Auto-PR: ADE-owned, off, per spawn, after K6. Desktop engineer: all slices, Desktop IPC review items (detach, open-in-editor).

package/docs/desktop-cli-api.md

@@ -53,8 +53,9 @@ declares**, parsed by the kernel — a consumer never parses YAML and never
 infers a field that is not there:
 
 - `soulsApi: 1`
-- `declarations: { requires, defaults, knowledge, teams, resources }` — each
-  the declared object, or `null` when the section is absent.
+- `declarations: { requires, defaults, knowledge, teams, resources, children }` — each
+  the declared object, or `null` when the section is absent (`children`
+  since 0.24.8: `{spawn: boolean}`, see readiness policy).
 - `provenance: { kind, source, revision, path, workspaceRevision } | null` —
   where this soul copy came from, as recorded by the kernel when it created
   it (`oats onboard` records `packaged-definition` or
@@ -105,6 +106,7 @@ un-materialized tree → `E_NO_WORKTREE`.
  "recorded":{"branch":"feat/x","repo":"/abs/repo","drift":true},
  "upstream":{"ref":"origin/feat/y","ahead":1,"behind":0},
  "base":{"ref":"origin/main","source":"origin/HEAD","mergeBase":"<oid>","ahead":2,"behind":0},
+ "remote":{"name":"origin","url":"git@github.com:acme/one.git","host":"github.com","path":"acme/one","source":"branch-upstream|origin"},
  "summary":{"changed":1,"renamed":1,"copied":0,"unmerged":0,"untracked":1},
  "files":[{"id":"<24 hex>","kind":"renamed","xy":"R.","submodule":false,"score":"R100","path":"src/new.txt","origPath":"src/old.txt"}],
  "notes":[]}
@@ -119,6 +121,11 @@ un-materialized tree → `E_NO_WORKTREE`.
   unmerged | untracked. Ignored files are not listed.
 - `files[].id` is **opaque**, minted under (`revision`, `indexRevision`). It is
   the only way to ask for a diff.
+- `remote` (0.24.8+): the branch's configured remote (`source: branch-upstream`),
+  else `origin`, else `null` — never invented. `host`/`path` are **parsed** from
+  the URL (ssh/https forms; `.git` stripped) so an ADE can choose a forge backend
+  and a `owner/repo` **without running Git**; a local path has `host: null`. No
+  network, no forge knowledge in the kernel.
 
 `oats instance diff <instance> --file <id> --revision <rev> [--index-revision <idx>] --json`
 returns a bounded unified diff:
@@ -147,7 +154,389 @@ returns a bounded unified diff:
   render a diff against a tree that is not the one on screen. A path in
   `--file` is `E_BAD_ARGS`.
 
-No GitHub/PR data here: that is a capability seam (see the `oats.git` decision).
+No forge (PR/checks/reviews) data here: forge connections are an ADE/workstation integration (P1 decision), read by the Desktop server through the forge's own CLI; the kernel only reports the instance's `remote` so the ADE can pick a backend.
+
+## Instance events (`oats instance events`, `eventsApi: 1`, OATS 0.24.8+) — K7
+
+Typed lifecycle events per instance, **written by the kernel action that made
+them true**, with the receipt it produced. Nothing is inferred from
+transcripts, TASK/STATE files or prose. Append-only, two logs: `<home>/.oats-events.jsonl`
+and `<workspace>/.agents/events/<agent>--<instance>.jsonl` (survives the
+home's removal, so a retired instance's `retired` event is still readable).
+
+`oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] --json`
+
+```json
+{"eventsApi":1,"instance":"dev-1","home":"/abs/home","count":7,"returned":7,"truncated":false,
+ "events":[{"eventsApi":1,"at":"<iso>","instance":"dev-1","home":"/abs/home","producer":"kernel","kind":"spawned","data":{"agent":"dev","work":"worktree","branch":"agents/dev-1","runtime":"claude","model":null,"parentInstance":null,"relation":null,"launched":true}},
+           {"…":"launched | restarted | stopped | stop-refused | retire-planned | worktree-retained | worktree-removed | branch-deleted | retired | child-spawn-refused"}],
+ "lastEvent":{"kind":"stopped","at":"<iso>","producer":"kernel"},
+ "waitingOnYou":null,
+ "notes":["…"]}
+```
+
+- `kind` is a closed set (unknown kinds are refused at write). `producer` is
+  `kernel` for lifecycle facts; a capability may append its own events with
+  its id as producer (the write API is `appendEvent`, not the renderer).
+- **`waitingOnYou` is `null` unless a producer reported it** (`data.waitingOnYou:
+  true` with a `reason`). `null` means *unknown*, not "not waiting". Today no
+  kernel path claims it; the Active overview keeps rendering unknown until a
+  producer (a messaging or review capability) does.
+- Window is bounded (`--limit`, default 200; `truncated` says so). A torn line
+  appears as `kind: "unreadable"` rather than vanishing.
+
+## Schedule run history (`scheduleApi: 2`, OATS 0.24.8+) — K8
+
+`oats schedule show|list --json` entries gain **`recentRuns`**: the last 50
+settled runs (newest first) — every `lastRun` the scheduler recorded once its
+outcome settled (`ended | stopped | blocked | invalid | delivered | skipped |
+unknown …`, never `active`/`starting`), exactly as the producer wrote it,
+deduplicated per run. Where the run launched or targeted an instance, a
+`transcript: {instance, home, kind: "session"}` pointer says which home's
+session to open (the existing `oats session` surface); the kernel does not
+copy transcripts. `nextRun`/`lastRun`/`executionStatus` are unchanged. The
+Schedules view (frame 08) renders `recentRuns` as the recent-runs list and the
+transcript pointer as the handoff; captured-policy definitions are preserved
+as they are (definition fields are untouched by this addition).
+
+## Spawn preview (`oats spawn … --preview`, `spawnPreviewApi: 1`, OATS 0.24.8+)
+
+The Spawn modal's fields are backed by the kernel's own decision, taken **before
+any side effect**: `oats spawn <agent> [same flags as a real spawn] --preview --json`
+runs every preflight a spawn runs (placement, composition, resources,
+executable, runtime packages, child-spawn policy) and returns what the spawn
+*would* do — then returns without creating a home, branch or worktree.
+
+```json
+{"spawnPreviewApi":1,"preview":true,"agent":"dev","kind":"persistent","instance":"dev-fix-login","home":"/abs/agents/dev/instances/dev-fix-login",
+ "repo":"/abs/repo","work":"worktree","runtime":"claude","model":"opus","modelSource":"soul","launchConfig":null,"yolo":false,"backend":"tmux",
+ "branch":"agents/dev-fix-login","base":{"ref":"HEAD","oid":"<oid>"},"worktree":"/abs/agents/dev/instances/dev-fix-login/work",
+ "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"…"}}},
+ "executable":"/abs/bin/claude","capabilities":["oats.core"],"skills":["oats-operate","oats-souls"],"task":"…"}
+```
+
+- **Name / work area**: `instance` is the canonical name (`<agent>-<purpose>`,
+  de-duplicated with `-2`, `-3`…); `home` and `worktree` are the canonical
+  paths. The renderer never derives paths.
+- **Branch / base** (worktree mode): `branch` defaults to `agents/<instance>`
+  (`--branch <name>` overrides; validated); `base` is `--base <ref>` resolved
+  to its commit oid (default `HEAD`). `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN`
+  are refused in preview and in apply, before anything exists. Apply creates
+  the worktree **from that exact oid**.
+- **Model**: `model`/`modelSource` are the resolved selection. Omitting
+  `--model` **inherits** the launch configuration's or soul's preference;
+  `--model @native-default` is the explicit "use the runtime's own default"
+  (`modelSource: "native default (explicit)"`). These are different requests
+  and the UI must not relabel one as the other.
+- **Policy**: `policy.childSpawns` is what this instance will record (soul
+  declaration / spawn option / default), enforced later by the spawn route for
+  its children (see readiness).
+- **Apply** = the same command without `--preview`; the same inputs yield the
+  same decisions (instance, branch, base oid). If the world moved between
+  preview and apply (name taken, branch created, base gone) the apply refuses
+  with the same typed codes — the preview is a statement, not a reservation.
+- Not in preview (later K6 follow-ups): attach-knowledge refs from the
+  knowledge provider (05 excluded, attach stays), auto-PR intent (ADE-owned,
+  P1).
+
+### Preview API 2 (0.24.9+, feature `spawn-preview-2`) — the safe-mode fence
+
+**API 1 previews wrote before they returned** (a refused child spawn appended an
+event to the parent; a Herdr backend could be started; an unknown soul could be
+imported from an importable def). A consumer must therefore gate on
+**`spawnPreviewApi === 2` AND `features.includes("spawn-preview-2")`** — API 1 is
+the pre-fix marker and is never accepted for dispatch.
+
+- **No writes, success or refusal.** A preview appends no event, starts no
+  daemon (`backendStatus {name, installed, started:false}` reports what it
+  observed), and never creates/updates a soul (`E_SOUL_UNKNOWN` instead of an
+  import; `--instructions-file`/`--def-file` refused with `E_BAD_ARGS`). Test:
+  the deployment tree is byte-identical after a success, a refusal and an
+  unknown-soul preview.
+- **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
+  (as inspect/readiness take it) — no team-soul / capability-agent / importable-
+  def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
+  `subject {soul, agentsRoot|null, dir|null}` **as given, byte-exact**.
+- **Decision binding**: `decision {instance, home, branch, base{ref,oid},
+  revision}` (24-hex). Apply with `spawn … --expect-decision <revision>`: the
+  kernel recomputes name/home/branch/base under the same placement path and
+  refuses **`E_DECISION_STALE`** with `details.decision` (the fresh one) on ANY
+  drift — no auto-suffix, no silent re-base, nothing created. A GUI re-previews
+  and re-confirms; it never second-guesses names or paths. Without the flag the
+  CLI keeps its legacy auto-suffix for humans.
+- **Bounded preflight**: every native probe a preview runs (`pi --list-models`,
+  `pi list`, `claude plugin list`) shares ONE budget (20 s default), runs in its
+  own process group and is group-killed on timeout; `preflight {status:
+  complete|timeout, budgetMs, elapsedMs}` says which. A hanging runtime cannot
+  hang a preview.
+- Still absent (named follow-ups, not parity-done): attach-knowledge node refs
+  (provider contract), auto-PR (P1/ADE write approval), branch enumeration
+  (producer seam).
+
+## Readiness quartet, signatures, enforced policy (`oats readiness`, `readinessApi: 1`, OATS 0.24.8+)
+
+`oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json`
+is the first-run readiness view (frame 09) and the Capabilities readiness rows
+(frame 04). Every fact is derived from the **same** data `oats inspect` reports
+— never a second opinion — and rolled into four checks:
+
+```json
+{"readinessApi":1,"subject":{"kind":"soul","name":"dev"},"at":"<iso>",
+ "checks":{
+  "installed": {"status":"pass","items":[{"subject":"oats.core","status":"pass","required":true,"reason":null,"producer":"oats list","evidence":{"version":"1.1.3","integrity":"sha256-…","origin":"installed"},"remedy":null}]},
+  "trusted":   {"status":"fail","items":[{"subject":"oats.core","status":"fail","required":true,"reason":"executable surface not approved","producer":"artifact approval","evidence":{"integrity":"sha256-…"},"remedy":"oats trust oats.core",
+                                          "signature":{"status":"unknown","signer":null,"reason":"signature verification needs a network fetch; pass --verify-signatures"}}]},
+  "configured":{"status":"pass","items":[{"subject":"oats.core activation","status":"pass","required":true,"producer":"oats-config.yaml","evidence":{"target":"declared","level":"/abs"},"remedy":null}]},
+  "enrolled":  {"status":"not-applicable","items":[{"subject":"workspace membership","status":"not-applicable","required":false,"producer":"oats.yaml","reason":"standalone deployment: no workspace declared in oats.yaml"}]}},
+ "summary":{"ready":false,"required":3,"pass":2,"fail":1,"unknown":0},
+ "notes":["…"]}
+```
+
+- Each check is `pass | fail | unknown | not-applicable`; items carry
+  `subject, status, required, reason, producer, evidence, remedy`. **"Ready" is
+  `summary.ready`**: every *required* item passes (or is not-applicable) and
+  there is at least one required item — never inferred from an empty set.
+- **`installed`**: artifact present, locked, integrity matches. **`trusted`**:
+  executable approval of the exact artifact (`oats trust`). Separately,
+  `signature {status: verified | unsigned | unknown | invalid | not-applicable,
+  signer: {id, label} | null, reason}` — the source commit's **verified Git
+  signature**, named signer or nothing. It is `unknown` unless
+  `--verify-signatures` (a network fetch of that one commit; `git log %G?`);
+  a catalog URL, repository owner or byte hash is never a signer. Render
+  "Trusted · signed by <label>" only for `verified`.
+- **`configured`**: activation for the subject, runtime-package requirements
+  (`missingRequires`), runtime-settings problems. **`enrolled`**: workspace
+  **member admission** (decision §3) — `not-applicable` for a standalone
+  deployment (no `workspace:` in `oats.yaml`), `unknown` until admission is
+  verified against the workspace observation, `pass`/`fail` when it is. Never
+  login, never team registration; "Skip" leaves it not-applicable, never pass.
+- Subject: `--soul <name>` scopes required items to the soul's declared
+  requirements; without it, to the scope's active capabilities.
+
+`--policy` adds the **enforced** policy view with origins:
+
+```json
+"policy":{"childSpawns":{"allowed":false,"enforced":true,"origin":{"kind":"soul","detail":"children.spawn: false in soul.yaml"}},
+          "worktrees":{"allowed":true,"mode":"worktree","enforced":true,"origin":{"kind":"work-mode","detail":"work: worktree"}}}
+```
+
+`childSpawns` is **enforced by the spawn route**: `soul.yaml` may declare
+`children: {spawn: false}`; `oats spawn --allow-child-spawns | --no-child-spawns`
+overrides per spawn; the result is recorded in `instance.json`
+`policy.childSpawns {allowed, origin}`. A spawn with `--parent <p>` (or
+`--relation child --relative-to <p>`) under a parent whose recorded policy is
+off refuses **`E_CHILD_SPAWNS_DISABLED`** (`details.parent`, `details.policy`)
+before anything is created. Absent policy (pre-0.24.8 instances) = allowed,
+reported as `origin.kind: "default"`. With `--home <abs>` the policy is the
+instance's recorded (enforced) one; with only `--soul` it is the declaration
+(`enforced: false`). It is a lifecycle-authority claim, not an OS sandbox —
+the UI says so.
+
+### Slice-5 producer pins (0.24.9+; all additive — gate items on field presence)
+
+- **`configured` is EFFECTIVE activation.** `activation.enabled` is the resolved
+  verdict for the subject; a capability *declared* for the soul but disabled is
+  `fail` with reason `declared for soul <n> but disabled (…)`. Declaration is
+  never activation.
+- **Trust is not-applicable for data-only capabilities.** The inspect row now
+  carries `health.executableSurface` (manifest commands/hooks/launch env — what
+  `oats trust` approves). No surface → `trusted` item `not-applicable`, reason
+  `no executable surface`, whatever the lock records. This is why a fresh
+  `oats trust <package> --all-capabilities` "skipped" `oats.core` and readiness
+  still said fail before 0.24.9.
+- **Typed linkage on every item**: `capability {id, level, scope}` and
+  `origin {kind: requires|declares|default|inventory, target}`; plus
+  `summary.byCapability[] {capability, origin, required, checks{installed,
+  trusted, configured, enrolled}, ownReady, ready}` — the SAME items regrouped,
+  no second observation. `ownReady` is the capability's own four verdicts;
+  `ready` is `ownReady` AND no **subject-level blocker** — items that belong to
+  no capability (workspace membership, soul declarations) are listed in
+  `summary.subjectBlockers[] {check, subject, status}` and block every row.
+  A per-capability row never says ready while the subject is blocked, and a
+  row's verdict is never promoted to the subject's `summary.ready`. Render
+  per-capability rows from this; never parse subjects.
+- **Selector echo**: `subject.selector` = the arguments **as given, byte-exact,
+  no realpath** — `{kind:"scope", dir|null}` · `{kind:"soul", soul,
+  agentsRoot|null, dir|null}` · `{kind:"home", home, soul, agentsRoot|null}`.
+  Compare with what you sent, byte for byte; never filesystem-normalize a
+  response path. The canonical scope is `subject.context` (may differ from
+  `dir`, e.g. `/var` vs `/private/var` on macOS).
+- **Unreadable member document** (`oats.yaml` unreadable, or `workspace:`
+  present but not a mapping) → `enrolled` item `unknown` with
+  `evidence.file`, never `not-applicable`. A declared backlink stays `unknown`
+  with reason `reciprocal admission not observed …` until the CLI fetches the
+  workspace's members (K11).
+- **Captured homes refuse**: `readiness --home <captured>` →
+  `E_UNSUPPORTED_MODE` (`details.captured: true`) before any current-config
+  interpretation.
+- **`--agents-root <abs>`** is accepted with `--soul` (and with `--home`), as
+  inspect takes it — pin the exact root you admitted.
+- **Signature verification (feature `readiness-verify`)**: `--verify-signatures`
+  is bounded custody — **one total budget per readiness read** (120 s default)
+  shared by every capability's fetch and verify (an exhausted budget refuses the
+  remaining capabilities with `budget-exhausted`, no fetch), each Git child in
+  its own process group and the **whole group** SIGKILLed on timeout or failure,
+  scratch repositories removed on normal exit and on SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL
+  =/dev/null` + no system config + no prompts/askpass, **only https/ssh**
+  transports. `signature.failure` is `null` or `{code}` from the closed set
+  `transport-not-allowed | fetch-failed | fetch-timeout | budget-exhausted |
+  verifier-failed | verifier-timeout | cannot-check`; `signature.reason` is a
+  fixed sentence, **never stderr**. Gate the *Verify signatures…* action on the
+  feature name; keep it an explicit user action.
+
+## Lifecycle plans — Stop and Remove (`lifecycleApi: 1`, OATS 0.24.8+)
+
+The Desktop's Stop and Remove confirmations render **plans**: a read-only
+statement of what the action would touch, with the facts a human needs, and a
+`planRevision` hashed from the facts that make the action safe. Apply carries
+the revision back; if reality moved, apply **refuses with the fresh plan**
+(`E_PLAN_STALE`, `details.plan`) instead of acting on a world the human did
+not see. An `idempotencyKey` makes a retried apply return the first receipt.
+
+### `oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>] --json`
+
+```json
+{"lifecycleApi":1,"action":"stop","instance":"dev-1","home":"/abs/home","recursive":true,"at":"<iso>",
+ "targets":[{"instance":"dev-1-child","agent":"dev","home":"/abs/child","depth":1,"workMode":"worktree","launched":true,
+   "session":{"state":"unknown","present":true,"backend":"tmux","established":true},
+   "work":{"observed":true,"revision":"<oid>","branch":"feat/x","detached":false,"drift":false,"changed":2,"untracked":1,"upstream":{"ref":null,"ahead":null,"behind":null},"base":{"ref":"origin/main","ahead":1,"behind":0},"remote":{"host":"github.com","path":"acme/one"}},
+   "retiring":false,"stopPending":false,"midTask":true}],
+ "skipped":[],"planRevision":"<24 hex>","notes":[]}
+```
+
+- `targets` are the instance's **recorded descendants deepest-first, then the
+  instance** (recorded parentage — `parentInstance` — is the only relation the
+  kernel knows). `--no-recursive` lists them under `skipped` instead.
+- `session.state` is the backend's word: `shell`/`stopped`/`not-launched` are
+  idle; `unknown` means a non-shell process is running whose identity tmux
+  cannot name (the ordinary state of a launched harness). If the state **could
+  not be established**, `established:false`, `present:null`,
+  `state:"unestablished"`, with a `reason` — render that as unknown, never as
+  idle.
+- `work` is K1's observation (`observed:false` with a `reason` when there is no
+  work tree or it cannot be read — not "clean").
+- `midTask` is **reported** activity: `true` (running session or dirty work),
+  `false` (established idle and observed clean), or `"unknown"`.
+
+### `oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key> [--no-recursive] [--grace-ms <n>] --json`
+
+Quiesces each target (SIGTERM to the harness processes, bounded wait, **never
+escalated**), children first, under a per-home stop marker; retains home, work
+tree, transcript and launch configuration so `oats session restart` brings the
+instance back. Refuses `E_PLAN_STALE` (fresh plan attached),
+`E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`.
+
+```json
+{"lifecycleApi":1,"action":"stop","instance":"dev-1","home":"/abs/home","idempotencyKey":"k","planRevision":"<rev>","at":"<iso>",
+ "ok":false,"results":[{"instance":"dev-1-child","home":"/abs/child","ok":false,"code":"E_SESSION_STOP_FAILED","message":"…still running after 1500 ms; nothing was escalated","stillRunning":[4242]},
+                       {"instance":"dev-1","home":"/abs/home","ok":true,"stopped":true,"alreadyIdle":false,"state":"shell"}],
+ "retained":["home","work","transcript","launch"],"replayed":false}
+```
+
+`ok:false` means at least one target is still running; the receipt says which
+pid. Nothing was killed harder. A replay (`replayed:true`) is the recorded
+receipt for that key, not a second action.
+
+### `oats retire <instance> --plan [--home <abs>] [--dir <d>] --json`
+
+What Remove would touch, with the design's defaults. Read-only.
+
+```json
+{"lifecycleApi":1,"action":"retire","instance":"dev-1","home":"/abs/home","at":"<iso>",
+ "facts":{"session":{…},"work":{…K1 summary…},"workMode":"worktree","repo":"/abs/repo","recordedBranch":"agents/dev-1",
+          "children":[{"instance":"dev-1-child","agent":"dev","home":"/abs/child","session":{…}}],"pullRequest":"unknown"},
+ "defaults":{"retainWorktree":true,"deleteBranch":false,"stopChildren":true,"retainChildren":true},
+ "planRevision":"<24 hex>","notes":["the worktree is on feat/x, not the recorded agents/dev-1; branch actions use the worktree's branch", "…"]}
+```
+
+`pullRequest` is **always `"unknown"` from the kernel**: forge facts belong to
+the ADE's connection (P1). Branch actions use the **worktree's** branch
+(`facts.work.branch`), never `recordedBranch`.
+
+### `oats retire <instance> [--discard-worktree] [--delete-branch] --json` — retention is the default (K3b)
+
+Plain `retire` now **retains** a worktree-mode instance's work: the worktree
+cannot stay under the removed home, so it is **re-homed** with
+`git worktree move` to `<workspace>/.agents/worktrees/<repo>/<branch>` (a
+`-2`, `-3` suffix if taken; detached → `detached-<oid12>`), with staged,
+unstaged and untracked state intact, and the repository knows the new
+location. The receipt says so:
+
+```json
+{"retired":"dev-1","retention":{"worktree":"retained","movedTo":"/ws/.agents/worktrees/repo/feat-x","branch":"feat/x","detachedAt":null,"recordedBranch":"agents/dev-1"},
+ "worktreeRemoved":false,"branchDeleted":false, "workRecovery":{…}}
+```
+
+- `--discard-worktree` restores removal (`retention.worktree: "removed"`).
+- `--delete-branch` deletes the **worktree's verified branch**
+  (`retention.branchDeleted`), never the recorded spawn name, and implies
+  discarding the worktree (a checked-out branch cannot be deleted).
+- A failed move keeps the home and refuses `E_WORK_PRESERVATION_FAILED` —
+  nothing is lost; retry or pass `--discard-worktree`.
+- Non-worktree modes report `retention: null`. Quarantine/rollback paths keep
+  their removal semantics.
+- The Remove dialog's "also delete worktree / branch" checkboxes map to these
+  two flags; the kernel never touches a PR.
+- **Guarded apply** (what a GUI sends): `oats retire <i> --plan-revision <rev>
+  --idempotency-key <key> [--discard-worktree] [--delete-branch] --json`. The
+  revision is revalidated against a fresh plan first — facts moved →
+  `E_PLAN_STALE` with `details.plan` (re-render, re-confirm; nothing retired);
+  a repeated key **replays** the recorded receipt (`replayed: true`, JSON-v1
+  envelope) instead of retiring twice. A first retire prints its raw receipt
+  (pre-existing shape) with `planRevision`/`idempotencyKey`/`replayed:false`
+  added. Mint the key server-side per confirmation intent and keep it for that
+  intent's retries.
+  - **Children first, kernel-owned.** The plan's `facts.children` are stopped
+    by the kernel before retirement (bounded SIGTERM, never escalated) and
+    retained; the receipt lists `childrenStopped[]`. A child still running
+    after the grace **refuses the whole retirement** — `E_CHILDREN_RUNNING`
+    with `details.childrenStopped` (pids) and `details.plan`; nothing retired.
+  - **Branch deletion is bound to the confirmed branch.** The kernel re-verifies
+    the worktree's branch at the moment of deletion, after hooks (which may
+    mutate the tree); a mismatch deletes nothing and reports
+    `retention.branchDeletionSkipped {expected, actual, reason}`.
+  - **Ambiguous parentage is reported, never acted on.** Recorded parentage is
+    a bare name; if a child's parent name resolves to several homes under the
+    root, that child appears under `ambiguous[]` — `plan.ambiguous` on a stop
+    plan, `plan.facts.ambiguous` on a retire plan — with the reason, and is
+    excluded from `targets`/`children`.
+- **Stop replay horizon**: stop receipts are stored **per idempotency key**
+  (`<home>/.oats-stop-receipt.<key>.json`); any earlier key replays its own
+  receipt for as long as the home exists. Retire receipts live beside the
+  instances directory and replay after the home is gone.
+
+### Feature advertisement — gate every new command on the probe
+
+`oats version --json` `features` now lists: `catalog`, `instance-git`,
+`instance-git-remote`, `souls-declarations`, `lifecycle-plans`,
+`retire-retention`, `readiness`, `spawn-preview`, `instance-events`,
+`schedule-history`, and carries the API integers (`instanceGitApi`, `soulsApi`,
+`lifecycleApi`, `readinessApi`, `spawnPreviewApi`, `eventsApi`,
+`scheduleHistoryApi`). **Gate on these, never on a version string and never by
+optimistic invocation**: an older CLI ignores an unknown `--plan` on `retire`
+and *retires*. Absent feature → the view is unavailable.
+
+## Instruction refresh (`oats session recompose`, feature `session-recompose`, OATS 0.24.8+)
+
+A live instance's composed `AGENTS.md` is generated at spawn and outranks any
+mail or tracked file *in the running context*. When a soul changes (a role or
+budget amendment) and a respawn is not possible or wanted, an operator
+refreshes the home in place:
+
+- `oats session recompose --home <abs> [--dry-run] --json` → `{home, instance,
+  agent, soulDir, contextDir, changed, dryRun, blocks[{source,file}], previous,
+  note}`. Same composer spawn used, the home's own `soul` link and recorded
+  context/work mode. `changed:false` is a no-op (no receipt). On change the
+  prior text is retained as `previous` (`<home>/.oats-agents-md.<stamp>.previous`),
+  `instance.json` gains `instructions[]`/`recomposedAt`, and a `recomposed`
+  event is appended.
+- **Nothing is signalled or restarted** — the harness re-reads on its own
+  schedule; the receipt's `note` says so. Refuses a retiring home
+  (`E_INSTANCE_RETIRING`), captured incarnations and capability-defined souls
+  (`E_UNSUPPORTED_MODE`: those are refreshed by a new resolution / package).
+- Gate on `features.includes("session-recompose")`. It is an **operator
+  action** (the human or the instance's parent), never something a Desktop
+  poll or an agent runs on itself.
 
 ## Mutations exposed to Desktop v1
 

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

@@ -1,6 +1,6 @@
 # OATS v0.24.7 — instance Git observation, soul declarations, and no hollow agents
 
-Kernel/Pi/Desktop **0.24.7**. Two additive read-only contracts for the Desktop
+Kernel/Pi/Desktop **0.24.7**. Tag `v0.24.7` → commit `c923d81b` (this notes commit; the last code change is `912aaee0`, PR #57). The npm tarball's `gitHead` is `c923d81b`; the version-bump commit lands after the tag (PR #58). A from-the-tag verifier should expect `gitHead == c923d81b`. Two additive read-only contracts for the Desktop
 (`instanceGitApi: 1`, `soulsApi: 1`), one spawn refusal that closes a
 first-team-path defect, and four Desktop parity slices.
 
@@ -53,7 +53,7 @@ first-team-path defect, and four Desktop parity slices.
   which ran Git against every instance tree on every roster poll without helper
   controls and substituted healthy zeros on failure — is **removed**. Desktop
   Git reads are the K1 route only. GitHub/PR card is *unavailable* pending the
-  `oats.git` decision.
+  P1 decision: forge connections are an ADE/workstation integration, not a capability (working names `oats.git`/`oats.forge` retired).
 - **3** Souls + Sources on K4: declarations, recorded provenance (`null` renders
   *Unrecorded*, never *Local*), "Not declared" vs "Not reported" distinguished,
   sources-installed ≠ Ready.