@awebai/oats 0.24.6 → 0.24.7

package/bin/oats.mjs

@@ -30,7 +30,7 @@ import {
   approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, planInstanceResources, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
-  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, listCapabilityAgents, workspaceOf,
+  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
   spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
@@ -58,12 +58,13 @@ import { portableScope } from "../lib/portable-state.mjs";
 import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../lib/captured-operation-process.mjs";
 import { approveCapturedCapability } from "../lib/artifact-approvals.mjs";
 import { loadSetupExpertEdition, SETUP_EXPERT, SETUP_CAPABILITIES } from "../lib/setup-expert-source.mjs";
+import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
 import { parsePortableSource } from "../lib/source-spec.mjs";
 
 const args = process.argv.slice(2);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "operation", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "catalog", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "instance", "operation", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "catalog", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -815,11 +816,36 @@ function homeContexts(home, meta) {
   out.push(dirname(agentsRootOfHome(realOrResolved(home))));
   return out;
 }
+/** A soul's own declared requirements/defaults/provenance, read from its
+ *  soul.yaml through the kernel's parser (never guessed, never re-parsed by a
+ *  consumer). Absent sections are null: an unrecorded provenance is a fact
+ *  about the soul, not a prompt to infer one. */
+function soulDeclarations(soulDir) {
+  const file = join(soulDir, "soul.yaml");
+  const empty = { declarations: { requires: null, defaults: null, knowledge: null, teams: null, resources: null }, provenance: null, problems: [] };
+  if (!existsSync(file)) return empty;
+  let parsed;
+  try { parsed = withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))); }
+  catch (e) { return { ...empty, problems: [{ code: "soul-declarations-unreadable", message: e.message }] }; }
+  const section = (key) => (parsed[key] !== undefined && parsed[key] !== null && typeof parsed[key] === "object") ? parsed[key] : (parsed[key] === undefined ? null : parsed[key]);
+  const provenance = section("provenance");
+  return {
+    declarations: { requires: section("requires"), defaults: section("defaults"), knowledge: section("knowledge"), teams: section("teams"), resources: section("resources") },
+    provenance: provenance && typeof provenance === "object" ? {
+      kind: provenance.kind ?? null, source: provenance.source ?? null, revision: provenance.revision ?? null,
+      path: provenance.path ?? null, workspaceRevision: provenance.workspaceRevision ?? null,
+    } : null,
+    problems: [],
+  };
+}
 function soulEntry(soul, root, { capability } = {}) {
   const dir = soul._dir || soul.soulDir;
   const soulDir = capability ? soul.soulDir : join(dir, "soul");
   const packaged = !!capability;
+  const declared = soulDeclarations(soulDir);
   return {
+    soulsApi: 1, declarations: declared.declarations, provenance: declared.provenance,
+    declarationProblems: declared.problems,
     name: soul.name, kind: packaged ? "capability" : (soul.kind || "persistent"), capability: capability || null,
     type: soul.type ?? null, description: soul.description ?? null, repo: soul.repo ?? null, work: soul.work || "checkout",
     runtime: soul.runtime || "pi", model: soul.model ?? null, yolo: soul.yolo === true || soul.yolo === "true" ? true : soul.yolo === false || soul.yolo === "false" ? false : null, launchConfig: soul["launch-config"] ?? null, backend: soul.backend ?? null,
@@ -996,11 +1022,32 @@ function inspectCmd() {
       instructions: { ...readTextCapped(join(home, "AGENTS.md")), sources: meta.instructions || [] }, drift,
     };
   }
+  // K4: the deployment's portable source context and each soul's declared
+  // requirements joined against the capability inventory in this same payload.
+  // Readiness is about the soul's declared sources, kept apart from
+  // launchability (spawn) and adoption (prepare); unobservable = null.
+  const capabilityById = new Map(capabilities.map((c) => [c.id, c]));
+  for (const s of souls) {
+    const required = s.declarations?.requires?.capabilities;
+    const requirements = required && typeof required === "object" ? Object.entries(required).map(([id, spec]) => {
+      const cap = capabilityById.get(id) || null;
+      return { capability: id, source: spec && typeof spec === "object" ? spec.source ?? null : null,
+        installed: cap ? cap.health?.installed ?? null : false, approved: cap ? cap.health?.trusted ?? null : null,
+        active: cap ? !!cap.activation?.enabled : null, version: cap?.version ?? null };
+    }) : null;
+    s.readiness = { source: s.provenance ? "recorded" : "unrecorded", requirements,
+      status: requirements === null ? "undeclared" : requirements.every((q) => q.installed === true) ? "sources-installed" : requirements.some((q) => q.installed === false) ? "sources-missing" : "unknown" };
+  }
+  const sourceKey = (p) => JSON.stringify([p.source, p.revision, p.path]);
+  const sourceItems = [...new Map(souls.filter((s) => s.provenance?.source).map((s) => [sourceKey(s.provenance), { ...s.provenance, souls: [] }])).values()];
+  for (const s of souls) if (s.provenance?.source) sourceItems.find((i) => sourceKey(i) === sourceKey(s.provenance)).souls.push(s.name);
+  const sources = { soulsApi: 1, kind: sourceItems.length ? "recorded-provenance" : "none-recorded", items: sourceItems,
+    note: sourceItems.length ? null : "no soul in this scope records a portable source address" };
   const result = {
     operationsApi: 1, kernel: OATS_VERSION,
     scope: { context: ctx, requestedContext: requestedContext === ctx ? null : requestedContext, workspace: roots.length ? workspaceOf(roots[0]) : ctx, team: r.team || null, chain: chain.map((c) => ({ file: c._file, level: c._level, levelKind: levelOf(c._level) })), agentsRoots: roots },
     selected: { soul: selectedSoul?.name || null, agentsRoot: selectedSoul?.agentsRoot || null, home: home || null, source: meta ? "snapshot" : "config" },
-    souls, layers, capabilities, knowledge, snapshot, currentConfig,
+    souls, sources, layers, capabilities, knowledge, snapshot, currentConfig,
     problems: [...(lockError ? [lockError] : []), ...packagedDiagnostics.map((d) => ({ code: d.code, message: d.message, capability: d.capability })),
       ...(meta ? snapshotCaps.filter((c) => !mans[c.id]).map((c) => ({ code: "captured-capability-missing", message: `${c.id} was active when this home was composed but no manifest for it is acquired now`, capability: c.id })) : [])],
   };
@@ -3062,6 +3109,53 @@ function renderMergeRegion(r) {
 /** `oats catalog [--json]` — the effective official package catalog, read-only.
  *  Identity/discovery for consumers that cannot import the kernel (Desktop):
  *  never acquires, never trusts, never fetches. */
+/** `oats instance <git|diff> <instance>` — K1: read-only Git observation of one
+ *  instance's work tree. The instance is addressed qualified: an explicit
+ *  --home, or a name under the --dir scope (team roots included) that resolves
+ *  to exactly one home; several homes refuse with every candidate named. */
+function instanceCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  const sub = args[1], name = args[2];
+  const usage = "usage: oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json]";
+  if (!["git", "diff"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
+  dropAmbientRoot();
+  let home = flag("home");
+  if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+  if (home !== undefined && !isAbsolute(home)) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+  if (home === undefined) {
+    let root;
+    try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    let r; try { r = resolveOatsConfig(dirFlag()); } catch (e) { return bail(e.code || "E_CONFIG_BROKEN", e.message); }
+    const roots = [...new Set([root, ...(r.team ? teamAgentRoots(r.team.scope) : [])].map((p) => realOrResolved(p)))];
+    const candidates = [];
+    for (const rt of roots) for (const hit of findInstanceHomes(rt, name)) candidates.push({ root: rt, agent: hit.agent?.name ?? null, home: hit.home });
+    if (!candidates.length) return bail("E_SESSION_UNKNOWN", `no instance ${JSON.stringify(name)} under ${roots.join(", ")}`);
+    if (candidates.length > 1) return bail("E_AMBIGUOUS_INSTANCE", `instance ${JSON.stringify(name)} has ${candidates.length} homes; pass --home <abs>`, { candidates });
+    home = candidates[0].home;
+  } else if (basename(home) !== name) return bail("E_HOME_MISMATCH", `--home ${home} is not the home of instance ${JSON.stringify(name)}`);
+  try {
+    if (sub === "git") {
+      const observed = observeInstanceGit(home);
+      if (JSON_MODE) { jsonOk(observed); return; }
+      const o = observed.observation;
+      console.log(`${observed.instance} — ${shortPath(o.worktree)} @ ${o.branch ?? (o.detached ? `detached ${o.revision.slice(0, 12)}` : "unborn")}`);
+      console.log(`  upstream: ${observed.upstream.ref ? `${observed.upstream.ref} +${observed.upstream.ahead} -${observed.upstream.behind}` : "none (ahead/behind unknown)"}`);
+      console.log(`  base: ${observed.base.ref ? `${observed.base.ref} +${observed.base.ahead} -${observed.base.behind} (merge-base ${observed.base.mergeBase?.slice(0, 12)})` : "unknown"}`);
+      console.log(`  files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
+      for (const f of observed.files) console.log(`    ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}  [${f.id}]`);
+      for (const n of observed.notes) console.log(`  note: ${n}`);
+      return;
+    }
+    const fileId = flag("file"), revision = flag("revision"), indexRevision = flag("index-revision");
+    if (fileId === true || revision === true || indexRevision === true) return bail("E_BAD_ARGS", usage);
+    const d = diffInstanceFile(home, { fileId, revision, indexRevision });
+    if (JSON_MODE) { jsonOk(d); return; }
+    console.log(`${d.file.origPath ? `${d.file.origPath} -> ` : ""}${d.file.path} (${d.file.kind}, against ${d.against})${d.binary ? " [binary]" : ""}${d.truncated ? ` [truncated at ${d.limit} bytes]` : ""}`);
+    if (!d.binary) process.stdout.write(d.patch);
+  } catch (e) {
+    bail(e.code || "E_GIT_FAILED", e.message, e.observation ? { observation: e.observation } : undefined);
+  }
+}
 function catalogCmd() {
   const described = describeOfficialCatalog();
   if (JSON_MODE) { jsonOk(described); return; }
@@ -3960,7 +4054,7 @@ function statusTeam() {
 
 function spawnCmd() {
   // JSON mode: contract envelope, stable error codes, stderr-only progress.
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
   const yolo = yoloFlag();
   const backend = valueFlag("backend"), herdrSocket = valueFlag("herdr-socket");
@@ -4110,6 +4204,9 @@ function spawnCmd() {
     // model, runtime) is a fact about the selection, not a spawn-mechanism
     // failure: it keeps its own code so a GUI can act on it.
     if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_RUNTIME$/.test(e.code)) { bail(e.code, e.message); throw e; }
+    // An unmet declared requirement is a fact about the soul's configuration
+    // (with a remedy), not a spawn-mechanism failure: keep its code and details.
+    if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
     bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e); throw e;
   }
   // The instance exists from here on: a failed wake save is reported beside
@@ -4418,7 +4515,8 @@ function onboardCmd() {
     const source = parsePortableSource(`git:${catalogSource.url}@${pkg.commit}#${pkg.path}`);
     const requires = { capabilities: Object.fromEntries(SETUP_CAPABILITIES.map(id => [id, { source: `${source.source}#${source.path}` }])) };
     const soulFile = join(created.soul, "soul.yaml");
-    writeFileAtomic(soulFile, readFileSync(soulFile, "utf8") + `requires: ${JSON.stringify(requires)}\ndefaults: ${JSON.stringify(edition.declaration.defaults)}\n`);
+    writeFileAtomic(soulFile, readFileSync(soulFile, "utf8") + `requires: ${JSON.stringify(requires)}\ndefaults: ${JSON.stringify(edition.declaration.defaults)}\n`
+      + `provenance: ${JSON.stringify({ kind: edition.source.kind, source: edition.source.source, revision: edition.source.revision, path: edition.source.path, ...(edition.source.workspaceRevision ? { workspaceRevision: edition.source.workspaceRevision } : {}) })}\n`);
     const agent = findAgent(root, SETUP_EXPERT), composition = composeInstanceAgentsMd(created.soul, deployment, SETUP_EXPERT, "directory", "local");
     planInstanceResources({ resolved: composition.resolved, soulDir: created.soul, agent, contextDir: deployment, composition });
     const argv = [process.execPath, CLI_BIN, "spawn", SETUP_EXPERT, "--dir", deployment, "--no-yolo", "--task", "Help me configure this deployment and adopt my workspace with explicit approvals."];
@@ -4469,11 +4567,17 @@ function createCmd() {
     work: flag("work"), runtime: flag("runtime"), model: flag("model"), yolo,
     instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
   });
-  if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
-  for (const information of r.notes || []) console.error(`[${information.code}] ${information.message}`);
+  // A declared oats.core is a requirement spawn will enforce: say the next
+  // step here, not only at the refusal.
+  const declared = r.declaredCapabilities || [];
+  const inactive = declared.filter((id) => !(resolveOatsConfig(workspaceOf(root), name).capabilities || []).some((c) => c.id === id));
+  const next = inactive.length ? [{ code: "next-step", message: `${name} declares ${inactive.join(", ")}; before spawning, acquire if needed (oats install oats.framework) and activate: ${inactive.map((id) => `oats use ${id} --soul ${name}`).join(" && ")}` }] : [];
+  const notes = [...(r.notes || []), ...next];
+  if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(notes.length ? { notes } : {}), ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
+  for (const information of notes) console.error(`[${information.code}] ${information.message}`);
   if (bootstrapped) console.log(`Created deployment root ${shortPath(root)} (this scope had no agents/ yet)`);
   console.log(`Created ${r.kind === "local" ? "LOCAL agent (uncommitted — soul lives in local-agents/, gitignored)" : "agent"} "${r.agent}" — soul at ${shortPath(r.soul)}`);
-  console.log(`Edit ${shortPath(join(r.soul, "AGENTS.md"))} to define its role, then: oats spawn ${r.agent} --task "..."`);
+  console.log(`Edit ${shortPath(join(r.soul, "AGENTS.md"))} to define its role, then${inactive.length ? ` activate ${inactive.join(", ")} (above) and` : ":"} oats spawn ${r.agent} --task "..."`);
 }
 
 // ---------- capability command dispatch ----------
@@ -5174,6 +5278,7 @@ else if (cmd === "config") configCmd();
 else if (cmd === "trust") trust();
 else if (cmd === "list") listCmd();
 else if (cmd === "catalog") catalogCmd();
+else if (cmd === "instance") instanceCmd();
 else if (cmd === "remove") removeCmd();
 else if (cmd === "migrate") migrateCmd();
 else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
@@ -5368,6 +5473,13 @@ Usage:
                                             scopes, trust state
   oats catalog [--json]                      the effective official package catalog (read-only:
                                                identity/discovery, no acquisition or trust)
+  oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
+                                             read-only Git observation of the instance's work
+                                             tree: branch, status (renames kept), ahead/behind
+                                             vs upstream AND vs default-branch merge-base
+  oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json]
+                                             bounded diff of one observed file; refuses when
+                                             the tree moved since the observation
   oats update <package> [<package>@<ref>]    transactional package update: temp fetch,
       [--to <ref>] [--dir <d>]              closure validation, diff, lock replace,
                                             all capability approvals invalidated; a

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-22 07:00Z · main `508c4b5f`+ · **OATS v0.24.6 cutting** (PR45 slice 1a + `oats catalog`) · S8 slice 1b next
+**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
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 
@@ -12,12 +12,12 @@ Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, n
 |---|---|---|---|---|
 | S1 | Knowledge capability contract rework (kernel↔provider boundary, OKF 2.x) | ✅ OATS 0.24.1 / OKF 2.1.1 published | P | done for this phase |
 | S2 | Workspace/Portable Souls adoption of the OATS repos | ✅ **FIRST SECOND-OPERATOR PUBLICATION (735296c5, 2026-09-21)**: fresh machine, published definition alone, no `launch` → `status: prepared`, resolution `sha256-f11c433c…`, zero problems. ❌ then OKF `check` → `needs-configuration / provider-not-qualified`, **no message/key/origins**, identical for `harvest-runtime` pi and claude — OKF's check phase is code-only and folds ≥4 causes into one code (P, OKF 2.1.3). ⏳ Pi `launch` blocked by kernel ifInstalled defect (L, 0.24.5). Earlier: ✅ knowledge: bound to public `oats-knowledge` via OKF 2.1.2 from a fresh machine, four kernel versions · ✅ messaging normalizes; `wider` deadlock gone; named reasons in one run · ❌ **operator's amended verdict (9816b8ec): no resolution can publish — behind `responsibleHuman`, helper composition refuses because `oats.core` and `oats.aweb` ship `inject` without `helperInjection`** (OKF adopted the contract; its siblings did not). Both remaining blockers are packaging, not operator input. Fix: [decision](https://github.com/awebai/oats/blob/main/agents/oats-expert/soul/knowledge/decisions/helper-injection-policy-on-every-injecting-capability.md) — core `inherit`, aweb `omit`, framework release check, attributed early refusal · then unchanged re-run | lead, Antares | oats.framework 1.1.3 + aweb 1.11.2 + pins; re-run |
-| S3 | Messaging capability readiness on the new infrastructure (aweb) | ✅ aweb 1.11.0 released · ✅ **catalog + six editions pin v1.11.0 (0.24.2)** · ⬜ second-operator re-run | P, lead | Antares re-run |
+| S3 | Messaging capability readiness on the new infrastructure (aweb) | ✅ aweb 1.11.0 released · ✅ **catalog + six editions pin v1.11.0 (0.24.2)** · ✅ **second-operator `launch` re-run on 0.24.6 (Antares, 2026-09-21)**: resolution `sha256-0cbedec4…` published WITH launch selection {pi, model}; helper `oats.okf:memory-harvest` resolved alongside; hard runtime row (`delivery: channel`) refused attributed with capability/slot/runtime/package/install/origin — no bare `needs-configuration`. `check` half parked with OKF 2.1.3 by direction | P, lead | Antares re-run |
 | S4 | Official capabilities `oats.core` / `oats.setup` + explicit default + onboarding `oats-setup-expert` | ✅ D1, D2, **D3 merged (PR35)**: `oats onboard` verified live (acquire 1.1.1 → setup expert with both caps → scaffold composes the five capability skills, no legacy) · `oats.framework` 1.1.1 tagged | P, L | done; Desktop surfaces → S8 |
 | 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 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 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

@@ -14,7 +14,8 @@ Status: **proposal accepted for direction** by the lead on 2026-09-22; contracts
 | 3 | 03 Souls + Sources: imported editions + local souls, requirements, provenance, editability | **K4** |
 | 4 | 04 Capabilities: official catalog (`oats catalog --json`, 0.24.6+) + deployment inventory/readiness/used-by; Add capability = exact command | landed catalog + list/inspect + **K5** |
 | 5 | 09 First-run readiness quartet; View policy; Skip/Enrol | **K5** + enrollment decision |
-| 6 | 02 Spawn (two-column): soul chooser, provider/model, launch config (restored), work-area naming/worktree/base+branch, opening instruction, attach knowledge, child spawns, auto-PR, readiness, ⌘↵ | **K6** (+ knowledge-node JSON from the knowledge provider; 05 excluded but attach stays) |
+| 6a | 02 Spawn modal **design parity on existing seams** (human pulled forward 2026-09-22): two-column layout, soul chooser, provider/model dropdowns, launch config restored, opening instruction, readiness from known facts (`unknown` where not), ⌘↵ guards; not-yet-backed fields rendered disabled with "available after <seam>" | existing spawn/launch-config seams |
+| 6b | 02 Spawn fields live: soul chooser, provider/model, launch config (restored), work-area naming/worktree/base+branch, opening instruction, attach knowledge, child spawns, auto-PR, readiness, ⌘↵ | **K6** (+ knowledge-node JSON from the knowledge provider; 05 excluded but attach stays) |
 | 7a | 07 Active overview: counts, relations, activity/waiting-on-you, actions, pan/zoom | **K7** |
 | 7b | 08 Schedules: table/toggles/new/edit, next/last, recent runs, transcript handoff, captured-policy preservation | **K8** |
 | 8 | 10 Components: dropdowns, workspace join/manage, Open in split, Detach to window, Open worktree in editor, actions, toasts, collapsed rail | existing seams + Desktop IPC review for detach/editor |
@@ -23,15 +24,18 @@ Status: **proposal accepted for direction** by the lead on 2026-09-22; contracts
 
 Envelope `{schemaVersion:1, ok, result|error}` unchanged. Requests address a server-admitted exact target (`{home, server}` / exact source+revision+soul), never a renderer cwd. Results echo target + `contract`, `version`, `observedAt`, opaque `revision`, typed `problems[]`, explicit completeness/truncation. `null` = not known; empty = observed empty only when complete. Per-section availability `available | not-applicable | unavailable | denied | unsupported | error`. No stack traces, auth stderr, tokens or token-bearing URLs in renderer data. Remote paths are provenance, never local authority. Read-only calls never install, trust, enroll, spawn, fetch into the operator's worktree, switch branches or repair config.
 
+
+> **Ownership amendment (2026-09-22, human):** contract-dependent slices are not waits — the team implements the contracts. Kernel seams may be assigned to the Desktop engineer under lead review (the `lib/`/`bin/` lane rule is lifted per assigned seam). Current split (revised 17:10Z): **K1, P1 Decision, K3, K5 → lead** — the engineer's composed instructions forbid kernel edits and a mail cannot recompose them (role change = soul edit + recomposition; spawns blocked by the deployment's pi-profile pin). Engineer: slice 3 now (K4 merged), then 2a after K1. Kernel PRs: full root `npm test` + DTO in `docs/desktop-cli-api.md` in the same PR.
+
 ## Seams
 
 - **K1 `oats.instance-git` / `oats.instance-diff`** (kernel): typed per-instance Git state — worktree, head, upstream/merge-base comparison (missing upstream ≠ 0/0), NUL-delimited changes with rename paths and per-file counts; bounded unified diff by opaque file id + observation revision (stale selection refuses, never a different file). Replaces the Desktop-only `instance.git` aggregate whose fallback zeros can masquerade as clean.
 - **P1 `oats.instance-github`** (provider, not kernel): PR summary/checks/reviews through an additive Git/review **capability** with its own credential policy (native custody; Desktop never runs `gh`, reads tokens or opens credential forms). Needs a kernel dispatch contract for additive-capability structured views (today `operation run` accepts only knowledge/messaging/tasks). "No PR" ≠ unavailable ≠ unauthenticated ≠ rate-limited. Checks bind to exact head OID. Review markdown is untrusted text.
 - **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**: qualified list of imported editions + authored local souls with identity/source/revision/requirements/declarations/editability; readiness separate from launchability and adoption; no renderer YAML.
+- **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**: 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.
+- **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.
 - **K8 schedule run history** + captured-policy-preserving edit contract; transcript access via the owning CLI/provider.
 

package/docs/desktop-cli-api.md

@@ -46,6 +46,109 @@ 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 }` — each
+  the declared object, or `null` when the section is absent.
+- `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},
+ "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.
+
+`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 GitHub/PR data here: that is a capability seam (see the `oats.git` decision).
+
 ## 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**. 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
+  `oats.git` decision.
+- **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/lib/core.mjs

@@ -4248,6 +4248,22 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     for (const b of composition.blocks || []) expected.push({ type: "instruction-block", source: b.source, declared: b.file, path: b.file });
   }
 
+  // A soul that DECLARES an operational capability (requires.capabilities,
+  // e.g. oats.core written by `oats create`) has, by that declaration, given up
+  // the kernel's legacy skill injection. If the declared capability is not
+  // active for this soul in this context, the instance would start with no
+  // operational curriculum and no warning — a hollow agent. That is an unmet
+  // declared requirement: refuse, attributed, with the exact remedy. Removing
+  // the declaration from soul.yaml is the supported way to opt out.
+  const declaredOps = declaredOperationalCapabilities(soulDir);
+  const inactiveOps = declaredOps.filter((id) => !(resolved.capabilities || []).some((c) => c.id === id));
+  if (inactiveOps.length) {
+    const soulName = agent?.name ?? basename(dirname(soulDir));
+    const remedy = inactiveOps.map((id) => `oats use ${id} --soul ${soulName}${contextDir ? ` --dir ${contextDir}` : ""}`).join(" && ");
+    throw Object.assign(oatsError("E_REQUIREMENT_INACTIVE", `soul ${soulName} declares ${inactiveOps.join(", ")} in requires.capabilities, but ${inactiveOps.length === 1 ? "it is" : "they are"} not active for this soul in ${contextDir}; the declaration suppresses the kernel's legacy skills, so the instance would start with no operational curriculum.\n  Acquire if needed (\`oats install oats.framework\`), then activate: ${remedy}\n  Or remove the declaration from ${join(soulDir, "soul.yaml")} to run without it.`),
+      { soul: soulName, capabilities: inactiveOps, context: contextDir, remedy });
+  }
+
   // A capability that declares a REQUIRED hook it cannot execute must not spawn.
   // Advisory executable hooks stay disabled-with-warning; a required one is a
   // promise, and starting without it is the failure required:true exists to stop.
@@ -5196,7 +5212,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
     home: soulDir, instance: name, agentName: name, soulDir,
     contextDir: ctx, workspaceDir: workspaceOf(root), rootDir: root, resolved,
   });
-  return { agentDir, soulDir, ...(notes.length ? { notes } : {}) };
+  return { agentDir, soulDir, declaredCapabilities: Object.keys(requires?.capabilities ?? {}), ...(notes.length ? { notes } : {}) };
 }
 function defaultSoulAgentsMd(name, description) {
   return `# ${name}
@@ -5218,8 +5234,8 @@ export function createAgent(root, o) {
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
-  const { agentDir, notes } = writeSoul(root, { ...o, name, kind });
-  return { agent: name, kind, soul: soulOf(agentDir), ...(notes ? { notes } : {}) };
+  const { agentDir, notes, declaredCapabilities } = writeSoul(root, { ...o, name, kind });
+  return { agent: name, kind, soul: soulOf(agentDir), declaredCapabilities, ...(notes ? { notes } : {}) };
 }
 
 /** Upsert a local agent soul (from raw instructions or a Claude-style def file).

package/lib/instance-git.mjs

@@ -0,0 +1,204 @@
+/** K1 — read-only Git observation of one instance's work tree.
+ *
+ * Truth comes from the tree itself (never from recorded spawn metadata):
+ * branch/HEAD via the worktree, status via porcelain v2 NUL records, ahead/
+ * behind reported twice and separately (upstream; merge-base with the
+ * repository's default branch) with "no upstream" ≠ 0/0. Diffs are bounded and
+ * addressed by an opaque file id minted with an observation revision; a diff
+ * against a tree that has since moved is refused, never served. */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { oatsError } from "./errors.mjs";
+
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+const DIFF_MAX_BYTES = 256 * 1024;
+export const INSTANCE_GIT_API = 1;
+
+/** Every invocation is read-only and helper-free: the tree being observed may
+ *  carry a hostile repo config (an agent works there), so external diff /
+ *  textconv drivers, fsmonitor and hooks are disabled explicitly, the caller's
+ *  Git environment is not inherited, and optional locks are off so status/diff
+ *  never refresh (write) the index. */
+const READ_ONLY_GIT = ["--no-optional-locks",
+  "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
+  "-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
+function gitEnv() {
+  const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", LANG: "C", LC_ALL: "C", GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" };
+  // The user's global config may name helpers too; observations do not need it.
+  env.GIT_CONFIG_GLOBAL = "/dev/null";
+  return env;
+}
+function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
+  const [sub, ...rest] = argv;
+  const extra = sub === "diff" ? ["--no-ext-diff", "--no-textconv", "--no-color"] : [];
+  try {
+    return execFileSync("git", [...READ_ONLY_GIT, "-C", cwd, sub, ...extra, ...rest], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, input, shell: false, timeout: 30_000, env: gitEnv() });
+  } catch (e) {
+    // `git diff --no-index` exits 1 when the inputs differ: that is the answer, not a failure.
+    if (diffExit && e.status === 1 && typeof e.stdout === "string") return e.stdout;
+    if (allowFail) return null;
+    throw oatsError("E_GIT_FAILED", `git ${sub} failed in ${cwd}: ${String(e.stderr ?? e.message ?? "").trim() || "unknown error"}`);
+  }
+}
+const trim = (s) => (s === null ? null : s.trim());
+
+/** The instance's work tree, from its home. The home's instance.json names
+ *  the work mode; the tree is `<home>/work` (a directory or a symlink to the
+ *  shared checkout). Missing/retired → attributed refusal, never a crash. */
+export function instanceWorkTree(home) {
+  const metaFile = join(home, "instance.json");
+  if (!existsSync(metaFile)) throw oatsError("E_SESSION_UNKNOWN", `${home} is not an OATS instance home (no instance.json)`);
+  let meta;
+  try { meta = JSON.parse(readFileSync(metaFile, "utf8")); } catch (e) { throw oatsError("E_SESSION_UNKNOWN", `${metaFile}: ${e.message}`); }
+  const work = join(home, "work");
+  if (!existsSync(work)) throw oatsError("E_NO_WORKTREE", `${meta.instance ?? home} has no work tree at ${work} (retired, recovered, or never materialized)`);
+  const inside = trim(git(work, ["rev-parse", "--is-inside-work-tree"], { allowFail: true }));
+  if (inside !== "true") throw oatsError("E_NO_WORKTREE", `${work} is not inside a git work tree`);
+  return { meta, work, mode: meta.work ?? null };
+}
+
+/** Porcelain v2 `-z` records → entries. Renames carry both paths. */
+export function parsePorcelainV2(raw) {
+  const fields = raw.split("\0");
+  const entries = [];
+  let branch = { oid: null, head: null, upstream: null, ahead: null, behind: null };
+  for (let i = 0; i < fields.length; i++) {
+    const rec = fields[i];
+    if (!rec) continue;
+    if (rec.startsWith("# ")) {
+      const [, key, ...rest] = rec.split(" ");
+      const value = rest.join(" ");
+      if (key === "branch.oid") branch.oid = value === "(initial)" ? null : value;
+      else if (key === "branch.head") branch.head = value === "(detached)" ? null : value;
+      else if (key === "branch.upstream") branch.upstream = value;
+      else if (key === "branch.ab") { const m = /^\+(\d+) -(\d+)$/.exec(value); if (m) { branch.ahead = Number(m[1]); branch.behind = Number(m[2]); } }
+      continue;
+    }
+    const type = rec[0];
+    if (type === "1") {
+      const parts = rec.split(" ");
+      entries.push({ kind: "changed", xy: parts[1], submodule: parts[2] !== "N...", path: parts.slice(8).join(" "), origPath: null });
+    } else if (type === "2") {
+      const parts = rec.split(" ");
+      const path = parts.slice(9).join(" ");
+      const origPath = fields[++i] ?? null; // rename/copy: the original path is the next NUL field
+      entries.push({ kind: /^R/.test(parts[8]) ? "renamed" : "copied", xy: parts[1], submodule: parts[2] !== "N...", score: parts[8], path, origPath });
+    } else if (type === "u") {
+      const parts = rec.split(" ");
+      entries.push({ kind: "unmerged", xy: parts[1], submodule: parts[2] !== "N...", path: parts.slice(10).join(" "), origPath: null });
+    } else if (type === "?") entries.push({ kind: "untracked", xy: "??", submodule: false, path: rec.slice(2), origPath: null });
+    else if (type === "!") entries.push({ kind: "ignored", xy: "!!", submodule: false, path: rec.slice(2), origPath: null });
+  }
+  return { branch, entries };
+}
+
+function defaultBranch(work) {
+  const sym = trim(git(work, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], { allowFail: true }));
+  if (sym) return { ref: sym, source: "origin/HEAD" };
+  for (const candidate of ["origin/main", "origin/master", "main", "master"]) {
+    if (git(work, ["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], { allowFail: true }) !== null) return { ref: candidate, source: "well-known" };
+  }
+  return null;
+}
+
+function countRange(work, range) {
+  const out = trim(git(work, ["rev-list", "--left-right", "--count", range], { allowFail: true }));
+  if (out === null) return null;
+  const [left, right] = out.split(/\s+/).map(Number);
+  return { left, right };
+}
+
+function indexRevisionOf(work) {
+  const listing = git(work, ["ls-files", "--stage", "-z"], { allowFail: true });
+  return listing === null ? "no-index" : createHash("sha256").update(listing).digest("hex").slice(0, 40);
+}
+function blobOf(work, path) {
+  // Content fingerprint of the working-tree file without writing an object.
+  return trim(git(work, ["hash-object", "--no-filters", "--", path], { allowFail: true }));
+}
+function fileId(revision, indexOid, entry) {
+  return createHash("sha256").update(`${revision}\0${indexOid}\0${entry.kind}\0${entry.path}\0${entry.origPath ?? ""}`).digest("hex").slice(0, 24);
+}
+
+/** One consistent observation of the tree. Every field is what git said. */
+export function observeInstanceGit(home) {
+  const { meta, work, mode } = instanceWorkTree(home);
+  const headOid = trim(git(work, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowFail: true }));
+  const raw = git(work, ["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=all", "--ignore-submodules=none"]);
+  const { branch, entries } = parsePorcelainV2(raw);
+  // The index state participates in the revision so that a stage/unstage
+  // between observation and diff is a moved tree, not a stale-but-served diff.
+  // Hashed from the index listing: no `write-tree`, so observing creates no object.
+  const indexOid = indexRevisionOf(work);
+  const revision = headOid ?? "unborn";
+  const at = new Date().toISOString();
+  const upstream = branch.upstream
+    ? { ref: branch.upstream, ahead: branch.ahead, behind: branch.behind }
+    : { ref: null, ahead: null, behind: null };
+  const base = defaultBranch(work);
+  let baseComparison = { ref: null, source: null, mergeBase: null, ahead: null, behind: null };
+  if (base && headOid) {
+    const mergeBase = trim(git(work, ["merge-base", "HEAD", base.ref], { allowFail: true }));
+    const counts = mergeBase ? countRange(work, `${base.ref}...HEAD`) : null;
+    baseComparison = { ref: base.ref, source: base.source, mergeBase, ahead: counts ? counts.right : null, behind: counts ? counts.left : null };
+  }
+  const files = entries.filter((e) => e.kind !== "ignored").map((e) => ({ id: fileId(revision, indexOid, e), ...e }));
+  const summary = { changed: 0, renamed: 0, copied: 0, unmerged: 0, untracked: 0 };
+  for (const f of files) summary[f.kind]++;
+  return {
+    instanceGitApi: INSTANCE_GIT_API,
+    instance: meta.instance ?? null, agent: meta.agent ?? null, home, workMode: mode,
+    observation: { revision, indexRevision: indexOid, at, worktree: work, branch: branch.head, detached: branch.head === null && headOid !== null, unborn: headOid === null },
+    recorded: { branch: meta.branch ?? null, repo: meta.repo ?? null, drift: meta.branch !== undefined && meta.branch !== null && branch.head !== meta.branch },
+    upstream, base: baseComparison,
+    summary, files,
+    notes: [
+      ...(upstream.ref === null ? ["no upstream configured: upstream ahead/behind are unknown, not zero"] : []),
+      ...(baseComparison.ref === null ? ["no default branch found (origin/HEAD, origin/main, origin/master, main, master): base comparison unknown"] : []),
+    ],
+  };
+}
+
+/** A bounded unified diff for one observed file. The caller passes the id
+ *  and the observation revision it was minted under; a moved tree refuses. */
+export function diffInstanceFile(home, { fileId: id, revision, indexRevision } = {}) {
+  if (typeof id !== "string" || !/^[a-f0-9]{24}$/.test(id)) throw oatsError("E_BAD_ARGS", "--file needs the opaque file id from `oats instance git --json`");
+  if (typeof revision !== "string" || !revision) throw oatsError("E_BAD_ARGS", "--revision needs the observation revision the file id was minted under");
+  const current = observeInstanceGit(home);
+  if (current.observation.revision !== revision || (indexRevision !== undefined && current.observation.indexRevision !== indexRevision)) {
+    throw Object.assign(oatsError("E_STALE_OBSERVATION", "the work tree moved since this file id was observed; re-observe with `oats instance git --json`"), { observation: current.observation });
+  }
+  const file = current.files.find((f) => f.id === id);
+  if (!file) throw Object.assign(oatsError("E_STALE_OBSERVATION", "this file id is not part of the current observation; re-observe"), { observation: current.observation });
+  const work = current.observation.worktree;
+  const paths = file.origPath ? [file.origPath, file.path] : [file.path];
+  const before = { blob: blobOf(work, file.path) };
+  let patch, binary = false;
+  if (file.kind === "untracked") {
+    const numstat = trim(git(work, ["diff", "--no-index", "--numstat", "--", "/dev/null", file.path], { diffExit: true, allowFail: true }));
+    binary = /^-\t-\t/.test(numstat ?? "");
+    patch = binary ? "" : (git(work, ["diff", "--no-index", "--", "/dev/null", file.path], { diffExit: true, allowFail: true }) ?? "");
+  } else {
+    const numstat = trim(git(work, ["diff", current.observation.revision, "--numstat", "-M", "--", ...paths], { allowFail: true }));
+    binary = /^-\t-\t/.test(numstat ?? "");
+    patch = binary ? "" : git(work, ["diff", current.observation.revision, "-M", "--", ...paths]);
+  }
+  // Consistency across the read, not only before it: HEAD, index and the file's
+  // own content must be what the observation said when the patch was produced.
+  const after = { revision: trim(git(work, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowFail: true })) ?? "unborn", indexRevision: indexRevisionOf(work), blob: blobOf(work, file.path) };
+  if (after.revision !== current.observation.revision || after.indexRevision !== current.observation.indexRevision || after.blob !== before.blob) {
+    const moved = observeInstanceGit(home);
+    throw Object.assign(oatsError("E_STALE_OBSERVATION", "the work tree moved while the diff was being read; re-observe with `oats instance git --json`"), { observation: moved.observation });
+  }
+  const bytes = Buffer.byteLength(patch, "utf8");
+  const truncated = bytes > DIFF_MAX_BYTES;
+  const body = truncated ? Buffer.from(patch, "utf8").subarray(0, DIFF_MAX_BYTES).toString("utf8") : patch;
+  return {
+    instanceGitApi: INSTANCE_GIT_API, observation: current.observation,
+    file: { id: file.id, kind: file.kind, xy: file.xy, path: file.path, origPath: file.origPath },
+    against: file.kind === "untracked" ? "empty" : current.observation.revision, binary, bytes, truncated, limit: DIFF_MAX_BYTES, patch: body,
+    readOnly: { helpers: "disabled", optionalLocks: "off", objectsWritten: 0 },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.24.6",
+  "version": "0.24.7",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",