@awebai/oats 0.24.6 → 0.24.8

package/docs/desktop-cli-api.md

@@ -46,6 +46,412 @@ no progress prose (progress goes to stderr):
 - success (exit 0): `{"schemaVersion":1,"ok":true,"result":{...}}`
 - failure (nonzero exit): `{"schemaVersion":1,"ok":false,"error":{"code":"...","message":"..."}}`
 
+## Souls and sources (`oats inspect --json`, `soulsApi: 1`, OATS 0.24.7+)
+
+Every entry in `result.souls[]` carries what the soul's **own `soul.yaml`
+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, 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
+  `exported-edition-copy`). Souls created before 0.24.7 or authored by hand
+  read `null`; render that as *unrecorded*, not as local or as anything else.
+- `readiness` — the soul's **declared sources**, joined against
+  `result.capabilities[]` from the same payload. Distinct from launchability
+  (`oats spawn`) and adoption (`oats prepare`); never a green "Ready".
+  - `source: "recorded" | "unrecorded"`
+  - `requirements: [{ capability, source, installed, approved, active, version }] | null`
+    (`null` = nothing declared). `installed: false` = not in the inventory;
+    `approved`/`active`/`version` are `null` when there is no inventory row.
+  - `status: "undeclared" | "sources-installed" | "sources-missing" | "unknown"`
+- `declarationProblems: [{ code, message }]` — an unreadable file reports why;
+  the soul is still listed.
+
+`result.sources` is the scope's **portable source context**: the distinct
+provenance sources its souls record.
+
+```json
+{"soulsApi":1,"kind":"recorded-provenance","note":null,
+ "items":[{"kind":"exported-edition-copy","source":"git:https://…/oats.git","revision":"<sha>","path":"souls/oats-setup-expert","workspaceRevision":"<sha>","souls":["oats-setup-expert"]}]}
+```
+
+`kind: "none-recorded"` (empty `items`, explanatory `note`) means no soul in the
+scope records a portable **source address** — a soul may still carry a
+`provenance` of kind `packaged-definition` with `source: null`. Say "no portable
+source recorded"; do not infer "local" or "authored" from this state.
+Workspace imports adopted onto a deployment will appear here at their pinned
+revisions when that adoption is recorded on the deployment; nothing is
+enumerated from a source repository that the deployment does not record.
+
+## Instance Git state (`oats instance git|diff`, `instanceGitApi: 1`, OATS 0.24.7+)
+
+Read-only observation of one instance's **work tree**. Truth comes from the
+tree — the branch the tree is on, not the branch recorded at spawn (that is
+reported under `recorded` with a `drift` flag). Fixed-argv `git`, no shell.
+
+Address the instance qualified: `oats instance git <instance> --dir <scope>`
+resolves the name under the scope's agents roots (team roots included) and
+**refuses when several homes match** (`E_AMBIGUOUS_INSTANCE`, `details.candidates`);
+pass `--home <abs>` to pick one. Unknown → `E_SESSION_UNKNOWN`; retired or
+un-materialized tree → `E_NO_WORKTREE`.
+
+```json
+{"instanceGitApi":1,"instance":"dev-1","agent":"dev","home":"/abs/home","workMode":"worktree",
+ "observation":{"revision":"<HEAD oid|unborn>","indexRevision":"<index tree oid>","at":"<iso>","worktree":"/abs/work","branch":"feat/y","detached":false,"unborn":false},
+ "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":[]}
+```
+
+- `upstream` and `base` are **two separate comparisons**. No upstream →
+  `upstream: {ref:null, ahead:null, behind:null}` — unknown, **not 0/0**. `base`
+  is against the merge-base with the default branch (`origin/HEAD`, else a
+  well-known name; `source` says which); none found → all `null` plus a note.
+- Status is porcelain v2, NUL-delimited: renames/copies carry `origPath`;
+  paths with spaces/newlines are intact. `kind` ∈ changed | renamed | copied |
+  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:
+
+```json
+{"instanceGitApi":1,"observation":{…},"file":{"id":"…","kind":"changed","xy":".M","path":"README.md","origPath":null},
+ "against":"<captured revision oid>","binary":false,"bytes":2683,"truncated":false,"limit":262144,"patch":"diff --git …",
+ "readOnly":{"helpers":"disabled","optionalLocks":"off","objectsWritten":0}}
+```
+
+- `against` is the **captured revision oid** for tracked changes (working tree
+  vs that exact commit, index included — never the moving `HEAD`) and `empty`
+  for untracked files. Binary → `binary: true`, empty patch. Over 256 KiB →
+  `truncated: true` at the byte limit.
+- **Read-only, helper-free, consistent across the read** (`readOnly` echoes
+  it): the observed tree may carry a hostile repo config, so external diff,
+  textconv, fsmonitor and hooks are disabled and the caller's Git environment
+  and global config are not inherited; `--no-optional-locks` means no index
+  refresh and no object is written (`ls-files --stage` hash, not `write-tree`).
+  After producing the patch the CLI re-checks HEAD, index and the file's own
+  content against the observation and refuses `E_STALE_OBSERVATION` if any
+  moved mid-read — the result is never internally inconsistent.
+- If HEAD or the index moved since the id was minted, or the id is not in the
+  current observation, the CLI **refuses** with `E_STALE_OBSERVATION` and
+  attaches the current `observation` in `error.details` — re-observe, never
+  render a diff against a tree that is not the one on screen. A path in
+  `--file` is `E_BAD_ARGS`.
+
+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).
+
+## 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.
+
+## 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
 
 The commands below use the same envelope. Additional capability operations

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

@@ -0,0 +1,81 @@
+# OATS v0.24.7 — instance Git observation, soul declarations, and no hollow agents
+
+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.
+
+## Kernel
+
+- **`oats instance git <instance> [--home] [--dir] [--json]`** and
+  **`oats instance diff <instance> --file <id> --revision <rev> [--index-revision <idx>] [--json]`** (K1) —
+  read-only Git observation of one instance's work tree. Truth from the tree:
+  the branch the tree is on (the spawn-recorded branch is reported as
+  `recorded` with a `drift` flag). Porcelain v2 NUL status with renames keeping
+  both paths; **upstream and default-branch merge-base as two separate
+  comparisons** — no upstream is `null`, never 0/0. Opaque file ids minted
+  under (HEAD, index); a diff is taken against the *captured* revision oid and
+  refuses `E_STALE_OBSERVATION` (fresh observation attached) if HEAD, index or
+  the file's content moved, before **or during** the read. Bounded (256 KiB,
+  binary flagged). Qualified addressing: several homes with one name refuse
+  `E_AMBIGUOUS_INSTANCE` with candidates; retired/unmaterialized tree is
+  `E_NO_WORKTREE`.
+  **Hardened after a consumer-side adversarial probe**: the observed tree is
+  worked in by an agent, so its repo config is input — external diff, textconv,
+  fsmonitor and hooks are disabled, the caller's Git environment and global/
+  system config are not inherited, optional locks are off (no index refresh),
+  and the index revision is a hash of `ls-files --stage` (no `write-tree`, no
+  object written). The response states it: `readOnly: {helpers, optionalLocks, objectsWritten}`.
+- **`oats inspect --json` souls carry their declarations** (K4, `soulsApi: 1`):
+  `declarations` (requires/defaults/knowledge/teams/resources, parsed
+  kernel-side, `null` when absent), `provenance` (recorded by `oats onboard`
+  from now on; `null` = *unrecorded*, never inferred), `readiness` (declared
+  sources joined against the same payload's capability inventory — separate
+  from launchability and adoption; never a green "Ready"), and
+  `result.sources` — the scope's portable source context, with an honest
+  `none-recorded` state.
+- **No hollow agents.** `oats create` declares `oats.core` by default; composition
+  honours the declaration by suppressing the kernel's legacy skills — but nothing
+  on that path activates the replacement, so a `spawn` produced an agent with
+  **no operational curriculum and no warning** (second-operator finding on 0.24.6).
+  Now `spawn` refuses `E_REQUIREMENT_INACTIVE` before creating anything, with
+  the remedy (`oats install oats.framework` if needed, then
+  `oats use oats.core --soul <name>`) and the opt-out (remove the declaration).
+  `create` states the activation step up front (`next-step` note,
+  `declaredCapabilities` in `--json`). `create` stays declaration, not acquisition.
+
+## Desktop (parity slices 1b, 2a, 3, 4, 6a, 7a)
+
+- **1b** shared contextual right panel (Instance · Git & GitHub · Soul), collapsed
+  rail, per-workspace preferences, temporary focus mode.
+- **2a** Git & GitHub panel on K1: worktree/branch/drift, upstream and base named
+  separately, real file counts and rename paths, bounded read-only diff; stale
+  → re-observe, never rendered. The legacy background `gitState` collector —
+  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
+  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.
+- **4** Capabilities: official catalog via `oats catalog` (0.24.6+) plus the
+  deployment's classic inventory; aliases are mappings not exports, refs are refs,
+  override catalogs conspicuously labelled; "Add capability" copies the schema's
+  exact `oats install <package>` argv and never executes it.
+- **6a** Spawn modal to the redesign on existing seams: two-column layout,
+  grouped soul chooser, provider/model with reported-vs-assumed provenance,
+  launch configuration restored (an already-supported property the renderer had
+  regressed out of), fields that need K6 rendered disabled with their seam named.
+- **7a** Active overview (frame 07) on the roster: anonymous count-labelled
+  relation groups (the roster reports no group names), activity `unknown` until K7.
+
+Desktop CLI floor for the new views is **0.24.7** (`instanceGitApi`/`soulsApi`
+gates); an older CLI renders those views as *unavailable*, never as empty-healthy.
+
+## Also
+
+- Board and seams doc dates corrected (2026-09-21, not 09-22 — lead clock error
+  caught by the second operator). Pinned SHAs unaffected.
+- Second-operator `launch` re-run on 0.24.6 passed both halves (publish with an
+  executable launch selection; hard runtime row refuses attributed).
+- OKF 2.1.3 bug list (deferred with harvest): `check` per-cause reasons; retire
+  leaves the per-source `okf-<id>` schedule definition enabled.

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

@@ -0,0 +1,107 @@
+# OATS v0.24.8 — lifecycle plans, readiness, spawn preview, instance events, and guarded Stop/Remove in the Desktop
+
+Kernel/Pi/Desktop **0.24.8**. Tag `v0.24.8` → the commit carrying these notes
+(the last code change is `508fda04`, PR #69). The npm tarball's `gitHead` is
+the tagged commit; the version-bump commit lands after the tag. All new
+contracts are **advertised**: consumers gate on `oats version --json`
+`features[]` names and the API integers below — never on the version number,
+never by optimistic invocation.
+
+## Kernel — the remaining Desktop-parity seams (K3, K5, K6, K7, K8)
+
+- **Lifecycle plans** (K3, `lifecycleApi: 1`, feature `lifecycle-plans`):
+  `oats instance stop <i> --plan|--apply` and `oats retire <i> --plan`, then the
+  **guarded apply** `oats retire <i> --plan-revision <rev> --idempotency-key <key>
+  [--discard-worktree] [--delete-branch]`. A plan states producer facts (ordered
+  targets deepest-first, session/work facts, recorded children, `midTask:
+  "unknown"` never inferred) under a 24-hex `planRevision`; apply re-reads and
+  refuses `E_PLAN_STALE` (fresh plan attached) when facts moved. Keys replay
+  their own receipt instead of acting twice — stop receipts are stored **per
+  key**, retire receipts survive the home's removal.
+  - **Retention by default** (feature `retire-retention`): a plain retire
+    re-homes the worktree to `<workspace>/.agents/worktrees/<repo>/<branch>`
+    instead of deleting it; `--discard-worktree` removes; `--delete-branch`
+    deletes the branch the tree is **verified** to be on and implies discard.
+    Receipt `retention {worktree: retained|removed|absent, movedTo, branch,
+    recordedBranch, branchDeleted?, branchDeletionSkipped?}`; a failed move is
+    `E_WORK_PRESERVATION_FAILED` with the home kept.
+  - **Children first, kernel-owned.** A guarded retire stops the plan's recorded
+    children (bounded SIGTERM, never escalated) and retains them; a child still
+    running refuses the whole retirement — `E_CHILDREN_RUNNING`, nothing retired.
+  - **Branch deletion is bound to the confirmed branch**: re-verified at deletion,
+    after hooks (which may mutate the tree); a mismatch deletes nothing and
+    reports `branchDeletionSkipped {expected, actual, reason}`.
+  - **Ambiguous parentage is reported, never acted on**: parent edges are bare
+    names; one that resolves to several homes appears under `ambiguous[]`
+    (`plan.ambiguous` on stop, `plan.facts.ambiguous` on retire).
+  - A pre-plan CLI does not understand `--plan` and would retire on it; that is
+    exactly why the feature is advertised — consumers must gate.
+- **Readiness** (K5, `readinessApi: 1`): `oats readiness [--soul] [--home]
+  [--verify-signatures] [--policy] --json` — the quartet
+  installed · trusted · configured · enrolled, each `pass|fail|unknown|not-applicable`
+  with items `{subject, required, reason, producer, evidence, remedy}`;
+  `summary.ready` is never vacuous. Signatures are `unknown` unless
+  `--verify-signatures` (an explicit one-commit fetch; `verified|unsigned|invalid`
+  with the signer named). Enrolled = workspace-member admission.
+- **Enforced child policy** (K5): soul `children: {spawn: bool}`, spawn
+  `--allow-child-spawns|--no-child-spawns`, recorded as `instance.json`
+  `policy.childSpawns {allowed, origin}`; a spawn with `--parent` under an off
+  policy refuses `E_CHILD_SPAWNS_DISABLED`. `inspect --json` souls carry
+  `declarations.children`; capability rows carry `commit`.
+- **Spawn preview** (K6, `spawnPreviewApi: 1`): `oats spawn … --preview --json`
+  states the decision — instance name, home, worktree, branch, base `{ref, oid}`,
+  runtime/model/launch config, work mode, composition sources, policy — without
+  creating anything. `--base <ref>` picks the base; `@native-default` names the
+  runtime's own default explicitly.
+- **Instance events** (K7, `eventsApi: 1`, feature `instance-events`):
+  `oats instance events <i> [--limit] [--since] --json` — typed, producer-
+  attributed lifecycle events (spawned, launched, restarted, stopped,
+  stop-refused, retire-planned, retired, worktree-retained, branch-deleted,
+  child-spawn-refused, recomposed) from the home's log and the workspace's
+  retained copy; truncation and unreadable lines are visible, never smoothed.
+- **Schedule run history** (K8, `scheduleApi: 2`, feature `schedule-history`):
+  schedules report `recentRuns` — settled runs only, producer order, ≤ 50.
+- **Instruction refresh** (feature `session-recompose`): `oats session recompose
+  --home <abs> [--dry-run] --json` recomposes a **live** home's `AGENTS.md`
+  from its current soul with the same composer spawn used; previous text is
+  retained beside it, `instance.json` and a `recomposed` event record it,
+  nothing is restarted. An operator action for when a role changes and a
+  respawn is not possible or wanted.
+- Remote workspaces: `oats instance git|diff` reach a remote instance through
+  the negotiated route (K1 remote), refusing rather than guessing where no
+  route exists.
+
+## Desktop (parity slices 2b and 2c)
+
+- **2b — Connections.** Settings → Connections with an inline "Connect
+  GitHub" (device flow through `gh`, credential custody stays with `gh`; the
+  auth pane is a closed key set with redaction). The Git & GitHub panel gains an
+  observation-bound PR card: informational, correlated to the exact K1
+  revision/branch/remote, never authority. Forge connections are an **ADE
+  integration**, not a capability.
+- **2c — Stop and Remove.** The instance menu offers *Stop…* and *Remove
+  instance…*; both open a plan-backed confirmation showing the kernel's exact
+  targets, skipped/ambiguous children, session and work facts, the real branch
+  (recorded-branch drift noted separately) and retained-by-default choices.
+  One guarded local route; the plan is read from the CLI, each confirmation
+  gets an opaque reference, the idempotency key is minted on the first
+  confirmation and kept for that intent's retries, one apply at a time; lost
+  responses are shown as **unknown outcome**, never "no effect". Stale plans
+  require a new confirmation; a refused child stop names the child. The old
+  unguarded retire route now answers `E_PLAN_REQUIRED`.
+- Everything above is **unavailable** (not hidden, not guessed) when the
+  installed CLI does not advertise the corresponding feature.
+
+## Also
+
+- Lessons recorded: consumers gate on advertised features, never on
+  optimistic invocation; a declaration that suppresses a default must be
+  enforced; read-only Git observation is a security boundary.
+- Verification budget: one full gate per change is PR CI; locally only the
+  affected suites. Desktop-only changes run the Desktop suites plus the
+  focused suite.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.8`, then `oats doctor`. Desktops pinned to an
+older CLI keep working; new controls appear as the CLI's advertised features do.