@awebai/oats 0.24.12 → 0.25.0

package/lib/core.mjs

@@ -45,6 +45,14 @@ import { killGroup } from "./process-group.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 import { oatsError } from "./errors.mjs";
+async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
+// Capability rows for a PREPARED spawn (workspace model): the one function that
+// turns a Resolution's modules into the row shape hooks/environment/requirements/
+// retirement consume. Called twice per spawn — PLANNED before the home exists
+// (manifest, settings, origin, trust; no skills/inject since the copies are not
+// there yet) and REBUILT after materialize against what actually landed. Static
+// import: instance-resolution.mjs does not depend on core.mjs (no cycle).
+import { toCapabilityRows } from "./instance-resolution.mjs";
 const CAPTURED_NATIVE_START = Symbol("captured-native-start");
 import { renderInstructionText } from "./instruction-composition.mjs";
 import { loadCapturedAction } from "./captured-dispatch.mjs";
@@ -585,9 +593,10 @@ export function canonicalAgentsRoot(root) { return canonicalDeploymentPath(root)
 export function ensureRoot(cwd) {
   const root = findRoot(cwd);
   if (!root) {
-    throw new Error(
-      `no agents/, local-agents/, or deployment oats-config.yaml found walking up from ${resolve(cwd ?? process.cwd())} — create one (mkdir agents, or \`oats create <name> --local\`) or set PI_AGENTS_ROOT`,
-    );
+    const from = resolve(cwd ?? process.cwd());
+    throw oatsError("E_NO_DEPLOYMENT",
+      `no deployment found walking up from ${from}: no agents/ or local-agents/ directory — create one (mkdir agents, or \`oats create <name> --local\`), run from the deployment (where oats-local.yaml lives), or set PI_AGENTS_ROOT`,
+      { from, looked: ["agents/", "local-agents/"] });
   }
   // Deployment root ≠ invocation CWD: homes always land in the primary checkout.
   return canonicalAgentsRoot(root);
@@ -1104,7 +1113,12 @@ const PROCESS_BOOTSTRAP_PREFIXES = [
 function validateCapabilityManifest(m, mf) {
   const id = m.capability;
   if (!id) throw new Error(`capability manifest needs "capability": ${mf}`);
-  if (!/[.@/]/.test(id)) throw new Error(`capability ID must be namespaced: "${id}" (${mf})`);
+  // Workspace model (contract §2): a capability name is `^[a-z0-9][a-z0-9._-]*$`
+  // — a member capability is `nw-deploy`, a package one `oats.okf`. The classic
+  // "must be namespaced" rule kept marketplace ids unambiguous; the workspace
+  // has one flat name space per organisation instead (duplicate → E_CAPABILITY_AMBIGUOUS
+  // at resolution), so the grammar is the only requirement.
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) throw new Error(`capability ID must match ^[a-z0-9][a-z0-9._-]*$: "${id}" (${mf})`);
   if (m.retirement !== undefined) {
     if (!isPlainObject(m.retirement) || !isPlainObject(m.retirement.disposable)) throw new Error(`capability ${id} manifest retirement must contain a disposable map`);
     const unknown = Object.keys(m.retirement).filter((key) => key !== "disposable");
@@ -1620,6 +1634,31 @@ export function capabilityManifests(startDir) {
     // Dot-prefixed entries are transaction staging, never installed content.
     for (const e of readdirSync(dir, { withFileTypes: true })) if (e.isDirectory() && !e.name.startsWith(".")) add(loadManifestAt(join(dir, e.name), origin));
   };
+  // Workspace model: an INSTANCE HOME carries its own materialized modules
+  // (<home>/.oats/modules/<cap>/, recorded in instance.json.modules). They are
+  // the whole capability set of that instance — nothing from any config chain
+  // applies to it — so answer from them and stop. Trust: membership (member
+  // modules) or the per-version approval sync recorded (package modules); both
+  // were checked before materialization, and the copy is the instance's own.
+  // The deployment's module STORE (<deployment>/.oats/modules/<cap>@<commit>/ —
+  // where a package capability agent's tree was fetched by the workspace
+  // resolver): a store entry answers with its own manifest, trusted like an
+  // instance module (the lock approved the package before the fetch).
+  if (startDir && basename(dirname(startDir)) === "modules" && basename(dirname(dirname(startDir))) === ".oats"
+      && existsSync(join(dirname(dirname(dirname(startDir))), "oats-local.yaml")) && existsSync(join(startDir, "oats.json"))) {
+    const m = loadManifestAt(startDir, `module:${startDir}`);
+    if (m) add(m);
+    return out;
+  }
+  const modulesOf = instanceModulesRoot(startDir);
+  if (modulesOf) {
+    for (const [name, rec] of Object.entries(modulesOf.modules)) {
+      if (!isMaterializedCapabilityId(name) || name === "__proto__") continue;
+      const m = loadManifestAt(join(modulesOf.root, name), `module:${modulesOf.home}`);
+      if (m) { m._module = rec; add(m); }
+    }
+    return out;
+  }
   if (startDir) {
     for (const cfg of [...configChain(startDir)].reverse()) {
       const store = join(cfg._level, CAPABILITIES_DIRNAME);
@@ -1676,6 +1715,29 @@ export function capabilityManifests(startDir) {
 export function capabilityManifest(name, startDir) {
   return capabilityManifests(startDir)[name];
 }
+/** When `dir` is (or is inside) an instance home materialized under the workspace
+ *  model, → { home, root: <home>/.oats/modules, modules: instance.json.modules }; else null.
+ *  Walks up from `dir` to the nearest instance.json carrying a `modules` object. */
+export function instanceModulesRoot(dir) {
+  if (!dir) return null;
+  let cur = resolve(dir);
+  for (let i = 0; i < 6; i++) {
+    const metaFile = join(cur, "instance.json");
+    if (existsSync(metaFile)) {
+      let meta;
+      try { meta = JSON.parse(readFileSync(metaFile, "utf8")); } catch { return null; }
+      if (meta && typeof meta === "object" && meta.modules && typeof meta.modules === "object" && !Array.isArray(meta.modules)) {
+        const root = join(cur, ".oats", "modules");
+        return existsSync(root) ? { home: cur, root, modules: meta.modules } : null;
+      }
+      return null;
+    }
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return null;
+}
 
 /** Remove source-control metadata from the ROOT of a managed artifact.
  *
@@ -1923,6 +1985,14 @@ export function capabilityTrust(a, b) {
 function manifestTrust(manifest, startDir, requireExecutableApproval = true) {
   if (!manifest) return { trusted: false, reason: "manifest missing" };
   const origin = String(manifest._origin);
+  // Workspace model: a materialized module is trusted by construction — a
+  // member capability by membership (decision 2), a package capability by the
+  // per-version approval recorded in the lock before sync let it materialize
+  // (E_PACKAGE_UNAPPROVED otherwise). The copy is the instance's own.
+  if (origin.startsWith("module:")) {
+    const from = manifest._module?.from;
+    return { trusted: true, module: true, reason: from?.kind === "package" ? `package ${from.package} v${from.version} approved at sync` : `workspace member ${from?.repoKey ?? "?"}`, package: from?.kind === "package" ? from.package : undefined };
+  }
   if (origin.startsWith("owned:") || (!requireExecutableApproval && origin.startsWith("path:"))) return { trusted: true, configOwned: true };
   const executable = requireExecutableApproval && hasExecutableSurface(manifest);
   if (manifest._package) {
@@ -2449,7 +2519,14 @@ export function parseLockBytesStrict(bytes, { file = "<oats-lock.json>", limits
 
 export function parseLockFileStrict(file) {
   if (!existsSync(file)) return null;
-  return parseLockBytesStrict(readFileSync(file), { file });
+  const bytes = readFileSync(file);
+  // A workspace-model lock (lockfileVersion 3, lib/packages.mjs) annotates no
+  // installed tier — there is none. The classic chain treats it as "no v1 lock
+  // here"; the v3 readers (sync, spawn, doctor) own it. Sniffing the version is
+  // deliberately tolerant: a broken file still reaches the strict legacy codec
+  // so its typed error is preserved for doctor.
+  try { const v = JSON.parse(bytes.toString("utf8"))?.lockfileVersion; if (v === 3) return null; } catch { /* strict codec reports it */ }
+  return parseLockBytesStrict(bytes, { file });
 }
 
 /** Every lock-owning scope visible from a directory, outermost → innermost.
@@ -4146,14 +4223,69 @@ export function isOatsWorkspace(startDir) {
   return false;
 }
 
+/** Capability rows for a prepared spawn BEFORE its home exists: the same shape
+ * `toCapabilityRows` builds (manifest, settings, origin, provenance, trust, hooks,
+ * environment) with every home-relative path resolved against a placeholder that
+ * cannot exist, so `skills` is [] and `inject` is undefined until materialize has
+ * copied the module. `planned: true` marks the row so preflight knows those two
+ * fields are deferred (the copies are digest-verified by materialize itself). */
+const PLANNED_HOME_PLACEHOLDER = join(sep, "oats-planned-home-does-not-exist", "placeholder");
+function plannedCapabilityRows(resolution) {
+  return toCapabilityRows(resolution, PLANNED_HOME_PLACEHOLDER).map((row) => ({ ...row, level: undefined, dir: undefined, skills: [], inject: undefined, planned: true,
+    // Declared command text only (manifest-relative; never executed from a planned row).
+    hooks: Object.fromEntries(Object.entries(row.hooks || {}).filter(([event]) => APPROVED_HOOKS.has(event)).map(([event, h]) => [event, typeof h === "string" ? h : h?.command])) }));
+}
+/** Turn a materialized row's hook declarations (`{ command, cwd, required }` per
+ * event, as `toCapabilityRows` records them) into the SHELL STRINGS the kernel's
+ * hook runner and the retire path (via instance.json#capabilityRuntime) execute:
+ * `node <abs script> <args>`, exactly as `manifestHookCommands` renders a classic
+ * capability. The script must exist inside the module's copy under
+ * <home>/.oats/modules/<cap>/ — a path escaping it is a manifest defect. Only
+ * the events the kernel approves (soul-scaffold, spawn, retire, launch) are kept. */
+function materializedHookCommands(row, home) {
+  const out = {};
+  const moduleDir = row.dir || join(home, ".oats", "modules", row.id);
+  for (const [event, spec] of Object.entries(row.hooks || {})) {
+    if (!APPROVED_HOOKS.has(event)) continue;
+    const command = typeof spec === "string" ? spec : spec?.command;
+    if (typeof command !== "string" || !command.trim()) continue;
+    if (/^node\s+'/.test(command)) { out[event] = command; continue; } // already rendered
+    const [script, ...args] = command.trim().split(/\s+/);
+    const abs = join(moduleDir, script);
+    if (!existsSync(abs)) throw oatsError("E_CAPABILITY_RESOURCE_MISSING", `capability ${row.id} declares hook ${event} as ${JSON.stringify(command)}, but ${abs} is not in its materialized copy`);
+    const root = realpathSync(moduleDir); const target = realpathSync(abs); const fromRoot = relative(root, target);
+    if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) throw new Error(`capability ${row.id} hook ${event} path escapes its module copy: ${script}`);
+    out[event] = ["node", shq(abs), ...args].join(" ");
+  }
+  return out;
+}
+
 /** Compose, but never mutate, an instance instruction view from canonical soul instructions.
  * `kind` tunes composition: "local" adds the packaged local-soul briefing;
  * "capability" suppresses the knowledge layer's injection (ephemeral service
  * agents — reviewers, harvesters — carry no episodic memory by design). */
-export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode, kind) {
+export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode, kind, prepared = undefined) {
   const agentsMd = join(soulDir, "AGENTS.md");
   if (!existsSync(agentsMd)) throw new Error(`canonical soul instructions missing: ${agentsMd}`);
+  // Two chains meet here. With `prepared` (workspace model: discover → resolve over
+  // remotes; materialized into the home by the caller) the capability set is the
+  // resolution's modules and the classic config chain supplies ONLY machine-level
+  // knobs (yolo, launch configs, kernel/work-mode injects). WITHOUT `prepared`
+  // (a bare agents root, schedules, tests) the classic chain still activates
+  // capabilities from oats-config.yaml exactly as before — that path is scheduled
+  // to fold into the one prepared pipeline, not silently disabled.
   const resolved = resolveOatsConfig(contextDir, soulName);
+  if (prepared) {
+    // PLANNED rows: manifest/settings/origin/trust are known now; skills and
+    // inject paths point into the home, which does not exist yet, so they resolve
+    // to nothing here and are rebuilt by spawnBody once materialize has landed.
+    // `prepared.capabilityRows` (the CLI passes []) is honoured only when non-empty.
+    resolved.capabilities = Array.isArray(prepared.capabilityRows) && prepared.capabilityRows.length
+      ? prepared.capabilityRows
+      : plannedCapabilityRows(prepared.resolution);
+    resolved.workspace = { key: prepared.discovery?.key ?? null, commit: prepared.discovery?.commit ?? null, standalone: prepared.discovery?.standalone === true, revision: prepared.resolution.revision, team: prepared.resolution.soul?.team ?? null, slots: prepared.resolution.slots };
+    resolved.layers = Object.fromEntries(Object.entries(prepared.resolution.slots || {}).map(([slot, mod]) => [slot, mod ? { capability: mod } : null]));
+  }
   const wanted = [];
   const declaredOperations = declaredOperationalCapabilities(soulDir);
   const oatsCoreDeclared = declaredOperations.includes("oats.core");
@@ -4223,7 +4355,7 @@ function hasSkillDoc(dir) {
  * Installed-but-inactive capabilities are absent from `resolved.capabilities`
  * and so contribute nothing here, by construction.
  */
-export function planInstanceResources({ resolved, soulDir, agent, contextDir, composition }) {
+export function planInstanceResources({ resolved, soulDir, agent, contextDir, composition, prepared }) {
   const expected = [];
   const missing = [];
   /** `declares` marks a tree the manifest PROMISED: it must resolve AND yield at
@@ -4238,7 +4370,10 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     }
   };
 
-  for (const { path } of legacyOperationalSkills(soulDir)) {
+  // Workspace model: operational knowledge is a capability (oats.core, from a
+  // package) resolved like any other; the kernel bundles no skills for a prepared
+  // spawn. The classic path keeps the bundled trio for souls that declare nothing.
+  if (!prepared) for (const { path } of legacyOperationalSkills(soulDir)) {
     add({ type: "skill-tree", source: "kernel", declared: basename(path), path: existsSync(path) ? path : undefined });
   }
   const soulSkills = soulDir && join(soulDir, "skills");
@@ -4246,6 +4381,21 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
   if (soulSkills && existsSync(soulSkills)) add({ type: "skill-tree", source: "soul", declared: soulSkills, path: soulSkills }, { declares: false });
 
   for (const cap of resolved.capabilities || []) {
+    if (cap.planned === true) {
+      // Workspace model, before the home exists: the module's declared skills and
+      // inject are promised by its manifest and will be copied WHOLE (and digest-
+      // verified) by materialize. They are recorded as expected here — with their
+      // future home-relative paths — and asserted against the landed copies in
+      // spawnBody's EXPECTED == MATERIALIZED check, not against the filesystem now.
+      for (const s of cap.skillsDeclared || []) {
+        const declared = typeof s === "string" ? s : s?.declared;
+        if (typeof declared !== "string" || !declared) continue;
+        expected.push({ type: "skill-tree", source: cap.id, declared, path: undefined, entries: [], deferred: "materialize", origin: cap.origin, module: cap.id });
+      }
+      const intentionallyDroppedPlanned = agent?.kind === "capability" && cap.layer === "knowledge";
+      if (cap.injectDeclared && !intentionallyDroppedPlanned) expected.push({ type: "injection", source: cap.id, declared: cap.injectDeclared, path: undefined, deferred: "materialize", origin: cap.origin, module: cap.id });
+      continue;
+    }
     for (const s of cap.skillsDeclared || []) {
       add({ type: "skill-tree", source: cap.id, declared: s.declared, path: s.path, origin: cap.origin, level: cap.level });
     }
@@ -4268,7 +4418,9 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
   // A capability-defined agent always carries its own capability's skills,
   // regardless of config targeting, so they are expected for it too.
   if (agent?.kind === "capability" && agent.capability && !(resolved.capabilities || []).some((c) => c.id === agent.capability)) {
-    for (const s of capabilityDeclaredSkills(agent.capability, contextDir)) {
+    // A module-resolved capability agent (workspace model) reads its provider from
+    // the parent home's materialized copy, never from a config chain.
+    for (const s of capabilityDeclaredSkills(agent.capability, agent._manifestSource ?? contextDir)) {
       add({ type: "skill-tree", source: agent.capability, declared: s.declared, path: s.path });
     }
   }
@@ -4287,9 +4439,12 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
   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 });
+    // Workspace model: capabilities are not installed or activated per soul; the
+    // deployment names its workspace (or standalone repo) in oats-local.yaml and
+    // `oats sync` locks/approves the packages the souls draw from.
+    const remedy = "add oats-local.yaml (workspace: <ref> or standalone: <ref>) beside agents/ and run oats sync";
+    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  Remedy: ${remedy}${contextDir ? ` (here: ${join(contextDir, "oats-local.yaml")}, then \`oats sync --dir ${contextDir}\`)` : ""} — ${inactiveOps.join(", ")} then resolve${inactiveOps.length === 1 ? "s" : ""} from the workspace's packages (from: package).\n  Or remove the declaration from ${join(soulDir, "soul.yaml")} to run without it.`),
+      { soul: soulName, capabilities: inactiveOps, context: contextDir, remedy, details: { soul: soulName, capabilities: inactiveOps, context: contextDir, remedy } });
   }
 
   // A capability that declares a REQUIRED hook it cannot execute must not spawn.
@@ -4546,19 +4701,6 @@ export function runtimePackageIdentity(runtime, spec) {
   return mgr?.identity ? mgr.identity(spec) : packageSpecIdentity(spec);
 }
 
-/** Is a runtime package actually USABLE — present, with a verified install
- * location? Deliberately ONE predicate rather than a presence check plus a
- * satisfaction check: the two would drift, and every caller means "is it really
- * there". A configured row with no install location, a location that does not
- * exist, or a settings-only answer we could not verify all count as NOT
- * installed, so requirement aggregation still offers to install it and
- * post-install verification cannot report success while it is still missing
- * (reviewer-14c38e8). `runtimePackageStatus` carries the detail for diagnostics. */
-export function runtimePackageInstalled(runtime, spec, env = process.env, opts = {}) {
-  const st = runtimePackageStatus(runtime, spec, env, opts);
-  return !!st.installed && !st.unverified && !st.missingFiles && !st.disabled;
-}
-
 /** Gate: a runtime package spec must be a plain source token — no shell syntax,
  * whitespace, path traversal, or option-looking leading dash. Fail closed. */
 export function safeRuntimePackageSpec(spec, runtime = "pi") {
@@ -5029,6 +5171,76 @@ export function findCapabilityAgent(contextDir, root, name) {
   if (matchedFailures.length) throw matchedFailures[0];
   return undefined;
 }
+/**
+ * Workspace model: a capability-defined agent (a package's `agents:` soul, e.g.
+ * OKF's memory-harvest worker) resolves from a MATERIALIZED module — the copy the
+ * requesting instance already carries under <home>/.oats/modules/<cap>/. Looks in
+ * `anchorHome` first (the --parent / --relative-to instance), then every instance
+ * home under `root`; the first module declaring an agent of that name wins.
+ * → the same shape findCapabilityAgent returns, plus `_manifestSource` (the home
+ * whose modules supplied it) so skill/inject lookups read that copy.
+ */
+export function findModuleCapabilityAgent(root, name, { anchorHome = null } = {}) {
+  if (typeof name !== "string" || !name) return undefined;
+  const homes = [];
+  if (anchorHome) homes.push(anchorHome);
+  if (root && existsSync(root)) {
+    for (const a of readdirSync(root, { withFileTypes: true })) {
+      if (!a.isDirectory() || a.name.startsWith(".")) continue;
+      const inst = join(root, a.name, "instances");
+      if (!existsSync(inst)) continue;
+      for (const i of readdirSync(inst, { withFileTypes: true })) if (i.isDirectory() && !i.name.startsWith(".")) homes.push(join(inst, i.name));
+    }
+  }
+  const seen = new Set();
+  const failures = [];
+  for (const home of homes) {
+    const real = (() => { try { return realpathSync(home); } catch { return null; } })();
+    if (!real || seen.has(real)) continue;
+    seen.add(real);
+    const modules = instanceModulesRoot(real);
+    if (!modules) continue;
+    for (const [id, manifest] of Object.entries(capabilityManifests(real))) {
+      for (const rel of manifest?.agents || []) {
+        let meta;
+        try { meta = capabilityAgentMetadata(manifest, rel); } catch { continue; }
+        if (!meta || meta.name !== name) continue;
+        try {
+          assertCapabilityTreeContained(manifest, meta.soulDir, "agent");
+          return {
+            ...meta.soul, name,
+            kind: "capability", capability: id,
+            _dir: join(localAgentsDirOf(root), name),
+            _soulDir: meta.soulDir,
+            _manifestSource: real,
+            _module: manifest._module,
+          };
+        } catch (e) { failures.push(e); }
+      }
+    }
+  }
+  if (failures.length) throw failures[0];
+  return undefined;
+}
+/**
+ * A capability-defined agent from ONE capability directory (a package tree the
+ * workspace resolver fetched into the deployment's module store). The manifest is
+ * read from `dir`, trusted by construction (the lock approved the package), and
+ * the agent record points its skill/inject lookups at that store entry.
+ */
+export function capabilityAgentFromDir(dir, name, root, { module = null } = {}) {
+  const manifest = loadManifestAt(dir, `module:${dir}`);
+  if (!manifest) return undefined;
+  manifest._module = module;
+  for (const rel of manifest.agents || []) {
+    let meta;
+    try { meta = capabilityAgentMetadata(manifest, rel); } catch { continue; }
+    if (!meta || meta.name !== name) continue;
+    assertCapabilityTreeContained(manifest, meta.soulDir, "agent");
+    return { ...meta.soul, name, kind: "capability", capability: manifest.capability, _dir: join(localAgentsDirOf(root), name), _soulDir: meta.soulDir, _manifestSource: dir, _manifest: manifest, _module: module };
+  }
+  return undefined;
+}
 /** All capability-defined agents declared in a context (for status/errors).
  * Invalid providers degrade independently; diagnostics is a non-enumerable
  * array property so existing roster consumers keep the public array shape. */
@@ -5661,11 +5873,11 @@ export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env
  *  capability args; for claude/codex the `--` separator keeps them from
  *  swallowing the task, for pi they follow the task like capability args.
  *
- *  pi runs the STRICT CURRICULUM: the OATS-composed skill set and AGENTS.md
- *  only (--no-skills + --skill, --no-context-files, --no-prompt-templates,
- *  --append-system-prompt); extensions stay ambient by founder ruling (no
- *  --no-extensions, no -e), and the task positional goes ahead of contributed
- *  options because pi has no `--`. claude gets `--` before the prompt so a
+ *  pi starts NORMALLY (decision 13 of the workspace model): its own skill and
+ *  context discovery is left intact — the instance's copied capability skills
+ *  under <home>/.agents/skills are found from cwd=home like any repo's — and OATS
+ *  contributes only the composed AGENTS.md (--append-system-prompt). The task
+ *  positional goes ahead of contributed options because pi has no `--`. claude gets `--` before the prompt so a
  *  greedy contributed flag cannot eat it. codex keeps its native policy;
  *  yolo also trusts this generated home for the launch (projects=...). */
 export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
@@ -5682,7 +5894,11 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
     const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
     cmdline = `${shq(executable)} --cd ${shq(home)}${yolo ? ` --yolo -c ${shq(codexTrust)}` : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
   } else {
-    cmdline = `${shq(executable)} --no-skills --skill ${shq(join(home, ".agents", "skills"))} --no-context-files --no-prompt-templates --append-system-prompt ${shq(join(home, "AGENTS.md"))} --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${tail}`;
+    // Decision 13: pi starts NORMALLY — its own skill discovery (~/.pi/agent/skills,
+    // .agents/skills up the tree, so the instance's copied capability skills are
+    // found from cwd=home) and context files stay ambient. OATS contributes only
+    // the composed instructions.
+    cmdline = `${shq(executable)} --append-system-prompt ${shq(join(home, "AGENTS.md"))} --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${tail}`;
   }
   const hookEnv = recipe.hooks?.env || {};
   const envTokens = Object.keys(hookEnv).sort().map((name) => `${name}=${shq(redact ? "<redacted>" : hookEnv[name])}`);
@@ -5874,7 +6090,34 @@ export function redactLaunchRecipe(recipe) {
   const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
   return { ...recipe, env, ...(hooks ? { hooks } : {}) };
 }
+/** Spawn. With `o.prepared` (workspace model: a resolution prepared by
+ *  instance-resolution.mjs) this is ASYNC — capabilities are fetched and copied
+ *  into the home. Without it (classic soul-directory spawn: schedules, tests,
+ *  bare agents roots) it stays synchronous and returns the result directly. */
 export function spawnInstance(root, agent, o = {}) {
+  if (o.prepared) throw new Error("spawnInstance: a prepared (workspace) spawn is async — call spawnInstanceAsync");
+  // Generator trick: the body is written once (below) as a generator that yields
+  // exactly at its one asynchronous point. The classic path never reaches that
+  // yield, so driving the generator to completion here is fully synchronous and
+  // throws synchronously.
+  const it = spawnBody(root, agent, o);
+  const step = it.next();
+  if (!step.done) throw new Error("spawnInstance: classic spawn reached an asynchronous step (materialize) without `prepared`");
+  return step.value;
+}
+export async function spawnInstanceAsync(root, agent, o = {}) {
+  const it = spawnBody(root, agent, o);
+  let step = it.next();
+  while (!step.done) {
+    // The single yield hands back a promise-producing thunk; await it and feed the
+    // result (or throw the failure) back into the body.
+    try { const value = await step.value(); step = it.next(value); }
+    catch (e) { step = it.throw(e); }
+  }
+  return step.value;
+}
+function* spawnBody(root, agent, o = {}) {
+  const deliver = (r) => r;
   const work = o.work || agent.work || "checkout";
   if (!WORK_MODES.includes(work)) throw new Error(`unknown work mode "${work}" (${WORK_MODES.join("|")})`);
   if (work === "directory" && (o.workDir !== undefined || o.branch !== undefined)) {
@@ -6250,10 +6493,10 @@ export function spawnInstance(root, agent, o = {}) {
   // roll back — no home, no worktree, no identity, no tmux window.
   // Capability-defined agents carry _soulDir (read-only soul inside the package).
   const soulDir = agent._soulDir || soulOf(agent._dir);
-  const composition = composeInstanceAgentsMd(soulDir, repoAbs, agent.name, work, agent.kind);
+  const composition = composeInstanceAgentsMd(soulDir, repoAbs, agent.name, work, agent.kind, o.prepared);
   const resolvedCfg = composition.resolved;
   const yolo = resolveYolo(o.yolo ?? launchSelection.configuredYolo ?? agent.yolo ?? resolvedCfg.yolo);
-  const expectedResources = planInstanceResources({ resolved: resolvedCfg, soulDir, agent, contextDir: repoAbs, composition });
+  const expectedResources = planInstanceResources({ resolved: resolvedCfg, soulDir, agent, contextDir: repoAbs, composition, prepared: o.prepared });
   // Runtime extensions selected by ACTIVE capabilities for THIS instance's
   // runtime. Strict launch disables ambient extension discovery, so each one has
   // to be named by path — and a required runtime package that is not installed
@@ -6306,12 +6549,22 @@ export function spawnInstance(root, agent, o = {}) {
     const d = { instance, home, branch: plannedBranch, base: plannedBase,
       effective: { repo: repoAbs, work, runtime, model: model || null, launchConfig: launchConfig?.name ?? null, yolo: yolo ?? null, backend, // backend regardless of --no-launch: the decision is what WOULD launch
         childSpawns: ownChildPolicy.allowed, relation: relation ? { kind: relation, anchor: { instance: relativeTo ?? null, agentsRoot: anchorHome ? dirname(dirname(dirname(anchorHome))) : null } } : null } };
+    // Workspace model: the decision binds WHAT WILL BE MATERIALIZED — the
+    // resolution revision (member commits, package commits, payloads). A member
+    // that moved between preview and apply changes it → E_DECISION_STALE.
+    if (o.prepared) d.resolution = o.prepared.resolution.revision;
     d.revision = createHash("sha256").update(canonicalJson(d)).digest("hex").slice(0, 24);
     return d;
   };
   if (o.preview === true) {
     const decision = buildDecision();
-    return {
+    // Workspace model (M3): the preview reports what APPLY will produce — every
+    // module as a capability (name + origin) and every module skill by its
+    // directory basename with a `module:<cap>` source — not the classic chain's view.
+    const preparedCapabilities = o.prepared ? o.prepared.resolution.modules.map((m) => ({ name: m.name, origin: m.from.kind === "package" ? `package:${m.from.package}@${m.from.version}` : `member:${m.from.repoKey}@${m.from.commit}` })) : null;
+    const preparedSkills = o.prepared ? o.prepared.resolution.modules.flatMap((m) => (m.manifest?.skills || []).filter((s) => typeof s === "string" && s).map((s) => ({ name: basename(s.replace(/\/+$/, "")), source: `module:${m.name}` }))) : [];
+    return deliver({
+      ...(o.prepared ? { modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, resolution: o.prepared.resolution.revision, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true } : {}),
       spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
@@ -6319,9 +6572,9 @@ export function spawnInstance(root, agent, o = {}) {
       runtime, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
-      policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: resolvedCfg.capabilities.map((c) => c.id),
-      skills: expectedResources.filter((r) => r.type === "skill-tree").flatMap((r) => r.entries || []), task: task || null,
-    };
+      policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities ?? resolvedCfg.capabilities.map((c) => c.id),
+      skills: [...expectedResources.filter((r) => r.type === "skill-tree" && !r.deferred).flatMap((r) => r.entries || []), ...preparedSkills], task: task || null,
+    });
   }
   if (o.expectDecision !== undefined) {
     // A confirmed preview binds THIS apply: same name, home, branch and base
@@ -6331,6 +6584,12 @@ export function spawnInstance(root, agent, o = {}) {
     const fresh = buildDecision();
     if (fresh.revision !== o.expectDecision) throw Object.assign(oatsError("E_DECISION_STALE", `the previewed decision changed (${o.expectDecision} → ${fresh.revision}): ${fresh.instance}${plannedBase ? ` from ${plannedBase.ref}@${plannedBase.oid.slice(0, 12)}` : ""}; preview again`), { decision: fresh });
   }
+  // Backend PRESENCE is a prerequisite, checked before anything is placed (M1):
+  // an absent tmux/herdr binary must fail with nothing created, never after a
+  // populated home exists. Backend STARTUP (ensureHerdr) still waits for the
+  // bound decision and the exclusive placement below — a stale or losing apply
+  // must not start a daemon.
+  if (launch && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}; nothing was created`);
   // Exclusive placement reservation: the parent may be created, the home
   // itself never with `recursive` — EEXIST means another spawn (a concurrent
   // apply of the same decision, or anything else) got here first, and this one
@@ -6341,14 +6600,12 @@ export function spawnInstance(root, agent, o = {}) {
     if (e?.code === "EEXIST") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home} (a concurrent spawn won the placement); nothing was created by this call`), { instance, home });
     throw e;
   }
-  // Backend startup only now — the decision is bound and the placement is ours.
-  if (launch && !which(backend)) { try { rmdirSync(home); } catch { /* keep whatever is there */ } throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`); }
-  herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able
   // to write in the agent directory can swap `instances/` for a link elsewhere,
   // and mkdirSync follows it (reviewer-a6aa1c5). Re-assert on the directory that
-  // now exists, before a single file is written into it or any hook runs.
+  // now exists, before a single file is written into it (materialize included)
+  // or any hook runs.
   // This narrows the window to the mkdir itself rather than closing it outright:
   // Node has no openat/O_NOFOLLOW-relative API, so a truly hostile filesystem
   // needs OS-level protection on the deployment, not a pathname check.
@@ -6359,24 +6616,91 @@ export function spawnInstance(root, agent, o = {}) {
     try { rmdirSync(createdReal); } catch { /* not empty or not removable: leave it and say so */ }
     throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} was created at ${createdReal}, not at ${expectedHome} — the path changed after it was validated (a swapped instances/ link), so nothing has been written into it and the spawn is aborted`);
   }
+  // One rollback from here to the first lifecycle hook: the home is ours
+  // (placement won) and nothing outside it exists yet, so removing the home
+  // WHOLE is the entire compensation. `rmSync` recursive: a prepared home is
+  // populated by materialize (modules, skills, AGENTS.md, instance.json) — a
+  // non-recursive rmdir would leave it behind and the retry would find its
+  // name taken (M1). Nothing of a classic home exists at this point either.
+  const rollbackEmptyOrPreparedHome = (e) => {
+    try { rmSync(home, { recursive: true, force: true }); }
+    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; }
+    return e;
+  };
+  // Workspace model: copy every resolved capability WHOLE into the new home
+  // (.oats/modules/<cap>/ + .agents/skills/<cap>/) and record modules/providers
+  // in instance.json. Then REBUILD the capability rows against the copies that
+  // landed (H1): until now `resolvedCfg.capabilities` were PLANNED rows (no
+  // skills, no inject, no dir) — hooks, environment, requirements, retirement
+  // and instance.json all read the rebuilt rows from here on.
+  let materializeOutcome = null;
+  if (o.prepared) {
+    // The kernel's composed text (soul AGENTS.md + kernel/work-mode injects) is
+    // the body materialize composes the capability injects onto.
+    try {
+      materializeOutcome = yield () => (o.materialize ?? materializePreparedDefault)({ ...o.prepared, soulAgentsMd: composition.text, soulDir }, home);
+      const rows = (typeof o.prepared.toCapabilityRows === "function" ? o.prepared.toCapabilityRows : toCapabilityRows)(o.prepared.resolution, home);
+      if (!Array.isArray(rows)) throw new Error("toCapabilityRows returned no rows");
+      for (const row of rows) row.hooks = materializedHookCommands(row, home);
+      resolvedCfg.capabilities = rows;
+      // S1: the capability blocks materialize appended are part of the composed
+      // instructions. Read the markers back from the AGENTS.md that was WRITTEN
+      // (the authority on what the instance sees) and merge them into the
+      // composition so meta.instructions / composition.expected and the
+      // completeness check below describe the whole file, not only the kernel's
+      // half.
+      const written = readFileSync(join(home, "AGENTS.md"), "utf8");
+      const known = new Set(composition.blocks.map((b) => `${b.source}\u0000${b.file}`));
+      const outcomeBlocks = Array.isArray(materializeOutcome?.blocks) ? materializeOutcome.blocks : [];
+      for (const m of written.matchAll(/^<!-- oats:(capability:[^\s]+) src=(.+?) -->$/gm)) {
+        const source = m[1], file = m[2];
+        if (known.has(`${source}\u0000${file}`)) continue;
+        const fromOutcome = outcomeBlocks.find((b) => b.source === source && b.file === file);
+        const content = fromOutcome?.content ?? (existsSync(file) ? readFileSync(file, "utf8").trim() : "");
+        composition.blocks.push({ source, file, content, materialized: true });
+        // S1: the appended block is part of what the composition PROMISES the instance.
+        expectedResources.push({ type: "instruction-block", source, declared: file, path: file, materialized: true });
+        known.add(`${source}\u0000${file}`);
+      }
+      // The expected resources deferred to materialize (module skills/injects)
+      // are now resolvable: fill their paths so the record and the completeness
+      // check compare promised against landed.
+      for (const r of expectedResources) {
+        if (r.deferred !== "materialize") continue;
+        const row = rows.find((c) => c.id === r.module);
+        if (r.type === "injection") { r.path = row?.inject; continue; }
+        if (r.type === "skill-tree") {
+          const skillsRoot = join(home, ".agents", "skills", r.module);
+          r.path = existsSync(skillsRoot) ? skillsRoot : undefined;
+          r.entries = (row?.skills || []).map((p) => basename(p));
+        }
+      }
+    } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
+  }
+  // Backend startup only now — the decision is bound and the placement is ours.
+  try { herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined; }
+  catch (e) { throw rollbackEmptyOrPreparedHome(e); }
 
   initializeNativeHistory(home);
 
   // Body: the soul is linked for reference, while instructions are a generated instance-local view.
   symlinkSync(soulDir, join(home, "soul"));
-  writeFileSync(join(home, "AGENTS.md"), composition.text);
-  symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
-
-  // Runtime-neutral exact skill materialization. No harness receives ambient workspace/package skills.
-  const sources = legacyOperationalSkills(soulDir);
+  if (!o.prepared) { writeFileSync(join(home, "AGENTS.md"), composition.text); symlinkSync("AGENTS.md", join(home, "CLAUDE.md")); }
+  else if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
+
+  // Skills: capability skills were copied WHOLE into <home>/.agents/skills/<capability>/
+  // by materializePrepared (workspace model, decision 7/13); here only the soul's
+  // own skills join them. The harness is launched with its normal discovery — the
+  // machine's and the repo's skills are the harness's business, not excluded.
+  const sources = o.prepared ? [] : legacyOperationalSkills(soulDir);
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
-  for (const cap of resolvedCfg.capabilities) for (const path of cap.skills || []) sources.push({ id: cap.id, path });
+  if (!o.prepared) for (const cap of resolvedCfg.capabilities) for (const path of cap.skills || []) sources.push({ id: cap.id, path });
   // A capability-defined agent always carries its OWN capability's skills and
   // injection, regardless of config targeting (the reviewer needs its review
   // skills even though oats.review targets the developers type).
   if (agent.kind === "capability" && agent.capability && !resolvedCfg.capabilities.some((c) => c.id === agent.capability)) {
-    for (const path of capabilitySkillDirs(agent.capability, repoAbs)) sources.push({ id: agent.capability, path });
+    for (const path of capabilitySkillDirs(agent.capability, agent._manifestSource ?? repoAbs)) sources.push({ id: agent.capability, path });
   }
   // Skill names come from parsed config and from skill directories: on a plain
   // object, `"constructor" in overrides` is already true and `overrides[name]`
@@ -6403,7 +6727,7 @@ export function spawnInstance(root, agent, o = {}) {
     // Copy each selected tree so the exact instance-local set is real and immutable.
     copyTreeSafe(realpathSync(selected.src), join(home, ".agents", "skills", name));
   }
-  symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+  if (!existsSync(join(home, ".claude", "skills"))) symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
 
   // EXPECTED == MATERIALIZED. Preflight proved every declared resource resolves;
   // this proves the copies actually landed, so "the composition is complete" is
@@ -6420,12 +6744,30 @@ export function spawnInstance(root, agent, o = {}) {
   // entered the set (reviewer-400c1e6). Matching is by NAME because an explicit
   // skill-override may legitimately satisfy a promised name from another source.
   for (const r of expectedResources) {
+    if (r.deferred === "materialize") continue; // module skills: verified against the landed copies just below
     for (const name of r.entries || []) {
       if (!chosen.has(name)) incomplete.push(`skill "${name}", promised by ${r.source} (${r.declared}), is missing from the composed set`);
     }
   }
+  // Prepared spawn: every module's declared skill must have been copied under
+  // .agents/skills/<module>/<skill>/ by materialize — verify the copies landed
+  // as readable skills (the module directory alone proves nothing).
+  if (o.prepared) {
+    for (const m of o.prepared.resolution.modules) for (const s of m.manifest.skills || []) {
+      const sk = join(home, ".agents", "skills", m.name);
+      if (!existsSync(sk)) { incomplete.push(`module "${m.name}" declares skills but .agents/skills/${m.name} is absent`); break; }
+    }
+    for (const r of expectedResources) {
+      if (r.deferred !== "materialize" || r.type !== "skill-tree") continue;
+      if (!r.path) { incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but .agents/skills/${r.module} is absent`); continue; }
+      if (!r.entries.length) incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but no skill was copied under .agents/skills/${r.module}`);
+      for (const name of r.entries) if (!hasSkillDoc(join(r.path, name))) incomplete.push(`skill "${name}" (module ${r.module}) did not materialize as a readable SKILL.md`);
+    }
+  }
   for (const r of expectedResources) {
-    if (r.type === "injection" && !composition.blocks.some((b) => b.file === r.path)) incomplete.push(`injection from ${r.source} (${r.declared}) resolved but is not present in the composed AGENTS.md`);
+    if (r.type !== "injection") continue;
+    if (r.deferred === "materialize" && !r.path) { incomplete.push(`injection from ${r.source} (${r.declared}) was not materialized into the module copy`); continue; }
+    if (!composition.blocks.some((b) => b.file === r.path)) incomplete.push(`injection from ${r.source} (${r.declared}) resolved but is not present in the composed AGENTS.md`);
   }
   const aliasTarget = realPathOrNearest(join(home, ".claude", "skills"));
   if (aliasTarget !== realPathOrNearest(join(home, ".agents", "skills"))) {
@@ -6536,6 +6878,10 @@ export function spawnInstance(root, agent, o = {}) {
     extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
   });
   warnings.push(...hookRes.warnings);
+  // Which capability hooks RAN (in order) and how each ended — recorded on the
+  // `spawned` event below: the instance's event log is the auditable fact that
+  // a capability configured itself, independent of whatever the hook printed.
+  const hookReceipt = (res) => { const failedBy = new Map((res.failures || []).map((f) => [f.capability, f])); return (res.order || []).map((id) => ({ capability: id, ok: !failedBy.has(id), ...(failedBy.has(id) ? { required: failedBy.get(id).required === true, contract: failedBy.get(id).contract ?? null } : {}), meta: Object.hasOwn(res.meta || {}, id) })); };
   const requiredFailures = (hookRes.failures || []).filter((f) => f.required);
   let windowMayExist = false;
   let spawnTmux;
@@ -6785,7 +7131,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       // keeping both makes an instance's surface reviewable after the fact without
       // re-resolving config that may since have changed.
       composition: {
-        expected: expectedResources.map((r) => ({ type: r.type, source: r.source, declared: r.declared, resolved: r.path, origin: r.origin, level: r.level })),
+        expected: expectedResources.map((r) => ({ type: r.type, source: r.source, declared: r.declared, resolved: r.path, origin: r.origin, level: r.level, ...(r.deferred ? { deferred: r.deferred } : {}) })),
         materialized: {
           skills: materialized.map((m) => ({ name: m.name, source: m.source, from: m.from })),
           instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
@@ -6826,6 +7172,12 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       ...(backend === "herdr" ? { backend } : { tmux: { session, window: instance } }),
       launch: recipe, command: cmdline, createdAt: new Date().toISOString(),
     };
+    // Workspace model: materialize recorded modules/providers (and the module
+    // digests) in instance.json before this metadata is assembled — carry them.
+    if (o.prepared) {
+      try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null } };
+    }
     const spawnWarnings = warnings;
 
     spawnTmux = meta.tmux;
@@ -6895,14 +7247,14 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       }
     }
 
-    appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, runtime, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch } });
+    appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, runtime, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes) } });
     if (launch) appendEvent(home, { kind: "launched", data: { runtime, backend, launchConfig: launchConfig?.name ?? null } });
     if (o.idempotencyKey !== undefined) {
       // Only now is the spawn a finished receipt a same-key retry may replay.
       meta.spawnCompleted = true;
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
     }
-    return { ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+    return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
   } catch (error) {
     const note = compensateSpawn();
     error.message += note;
@@ -7504,6 +7856,11 @@ export function recomposeInstanceInstructions(home, { dryRun = false } = {}) {
   if (existsSync(retirePendingMarkerPath(realHome))) throw oatsError("E_INSTANCE_RETIRING", `${basename(realHome)} is being retired; nothing recomposed`);
   const meta = JSON.parse(readFileSync(metaFile, "utf8"));
   if (meta.executionBinding || meta.captured) throw oatsError("E_UNSUPPORTED_MODE", "captured incarnations are recomposed by preparing a new resolution, not in place");
+  // Workspace model (M2): a home whose capabilities were MATERIALIZED as modules
+  // composed its AGENTS.md from the module copies (capability injects under
+  // .oats/modules/). The classic composer knows nothing of them and would
+  // silently strip every capability block. Refuse rather than degrade.
+  if (meta.modules && typeof meta.modules === "object" && !Array.isArray(meta.modules)) throw oatsError("E_UNSUPPORTED_MODE", "recompose from materialized modules is not supported yet; re-spawn");
   const soulLink = join(realHome, "soul");
   let soulDir; try { soulDir = realpathSync(soulLink); } catch { throw oatsError("E_SOUL_UNKNOWN", `${realHome} has no readable soul link`); }
   const agentDir = dirname(dirname(realHome));
@@ -7771,7 +8128,10 @@ export function recipeFromLegacyCommand(meta, home) {
   const extras = [];
   const expect = (...seq) => { for (const w of seq) { if (value(i) !== w) throw oatsError("E_LAUNCH_LEGACY", `the recorded ${runtime} command is not the kernel's generated shape (expected ${JSON.stringify(w)} at argument ${i + 1}); it cannot be converted`); i++; } };
   if (runtime === "pi") {
-    expect("--no-skills", "--skill", join(home, ".agents", "skills"), "--no-context-files", "--no-prompt-templates", "--append-system-prompt", join(home, "AGENTS.md"), "--approve", "--name", meta.instance);
+    // Two generated shapes exist on disk: homes launched before the workspace
+    // model carry the strict-curriculum prefix; new homes start pi normally.
+    if (value(i) === "--no-skills") expect("--no-skills", "--skill", join(home, ".agents", "skills"), "--no-context-files", "--no-prompt-templates");
+    expect("--append-system-prompt", join(home, "AGENTS.md"), "--approve", "--name", meta.instance);
     if (value(i) === "--model") { model = value(i + 1) ?? null; i += 2; }
     expect("@TASK.md"); sawPrompt = true;
   } else {
@@ -9096,7 +9456,11 @@ export function retireInstance(root, name, o = {}) {
     else if (retention.worktree === "removed") appendEvent(found.home, { kind: "worktree-removed", data: { branch: retention.branch } }, { workspaceOnly: true });
     if (retention.branchDeleted) appendEvent(found.home, { kind: "branch-deleted", data: { branch: retention.branchDeleted } }, { workspaceOnly: true });
   }
-  appendEvent(found.home, { kind: "retired", data: { agent: found.agent.name, keepDir: !!o.keepDir, self, quarantine: !!quarantine, workRecovery: workRecovery?.path ?? null } }, { workspaceOnly: true });
+  // `hooks`: which retire hooks ran (in order) and how each ended — the same
+  // receipt `spawned` carries, so the workspace log shows both halves of a
+  // capability's lifecycle after the home is gone.
+  const retireHookReceipt = (() => { const res = hookResults || {}; const failedBy = new Map((res.failures || []).map((f) => [f.capability, f])); return (res.order || []).map((id) => ({ capability: id, ok: !failedBy.has(id), meta: Object.hasOwn(res.meta || {}, id) })); })();
+  appendEvent(found.home, { kind: "retired", data: { agent: found.agent.name, keepDir: !!o.keepDir, self, quarantine: !!quarantine, workRecovery: workRecovery?.path ?? null, hooks: retireHookReceipt } }, { workspaceOnly: true });
   // Retrying a quarantine only clears it if compensation ACTUALLY completed.
   // Otherwise the home — and the credentials in it — must survive again, or the
   // retry becomes the deletion the quarantine was preventing.