@awebai/oats 0.22.0 → 0.22.1

package/lib/core.mjs

@@ -4395,7 +4395,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
           // OATS_INSTANCE_HOME is the runtime-neutral contract name for the
           // instance home (absolute). OATS_HOME predates it and stays as a
           // compatibility alias: shipped capability hooks read it
-          // (capabilities/oats-aweb, capabilities/oats-okf) and are versioned
+          // (the official oats.aweb and oats.okf packages) and are versioned
           // independently of this kernel. Neither is OATS_HOME_DIR, which is
           // the package STORE root — do not conflate them.
           OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
@@ -4665,7 +4665,7 @@ export function appendLogEntry(file, entry, title = "Log") {
   writeFileSync(file, lines.join("\n").replace(/\n{3,}/g, "\n\n"));
 }
 
-// (soul knowledge scaffolding belongs to capabilities/oats-okf — soul-scaffold hook)
+// (soul knowledge scaffolding belongs to the oats.okf package — soul-scaffold hook)
 
 // ---------- soul scaffolding ----------
 function fileSnapshot(dir) {
@@ -5333,6 +5333,13 @@ export function spawnInstance(root, agent, o = {}) {
   // reconciliation, so this spawn-time check is the authoritative one.
   const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs);
 
+  // Prerequisites must fail before creating a home, worktree, or identity.
+  const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
+  const bin = which(runtime === "claude" ? claudeBin : "pi");
+  if (!bin) throw new Error(`${runtime === "claude" ? claudeBin : runtime} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}`);
+  if (launch && !which("tmux")) throw new Error("tmux not installed (brew install tmux)");
+  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
+
   mkdirSync(home, { recursive: true });
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able
@@ -5508,41 +5515,54 @@ export function spawnInstance(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
-  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), resolved: resolvedCfg,
     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);
-  // A REQUIRED spawn hook that failed means an active capability is not actually
-  // configured — aweb without a minted identity is an agent that believes it can
-  // be woken by mail and cannot. Fail the spawn and roll back, rather than hand
-  // over a half-configured instance. Nothing is launched yet, so compensation is
-  // retire hooks + worktree/branch + home; the same three-state verification as
-  // the anchor-write path, because a cleanup we cannot confirm must never be
-  // reported as done.
   const requiredFailures = (hookRes.failures || []).filter((f) => f.required);
-  if (requiredFailures.length) {
-    const incomplete = [];
+  let windowMayExist = false;
+  let spawnTmux;
+  const ancillaryCleanup = [];
+  // One compensation owner, from the first hook result through launch and
+  // the final lineage write. Preserve the original failure and retain any
+  // credentials/metadata whose cleanup could not be confirmed.
+  const compensateSpawn = () => {
+    const failed = requiredFailures.length
+      ? requiredFailures.map((f) => ({ capability: f.capability, event: f.event, ...(f.contract ? { contract: f.contract } : {}) }))
+      : [{ capability: "oats.kernel", event: "spawn" }];
+    const incomplete = [...ancillaryCleanup];
     const probe = (argv) => {
       try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
-      // With encoding:"utf8" a silent command yields stderr === "" — FALSY — so
-          // `e2.stderr || e2.message` fell through to "Command failed: …" and made
-          // every clean probe look like a failed one. `git rev-parse --verify
-          // --quiet` on an absent ref is exactly that case, so a successful branch
-          // deletion could never be confirmed and rollback always reported
-          // INCOMPLETE. Distinguish "no output" from "no stderr captured".
-          catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
+      // An absent ref exits 1 with empty stderr; preserve that distinction.
+      catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
     };
-    // Which capabilities still owe cleanup, as IDS the retry can verify against —
-    // the prose in `incomplete` tells a human what happened, but a retry needs
-    // something it can check. Without this, a retry that resolves no capabilities
-    // at all (a descriptor naming none, or config drift since the spawn) runs zero
-    // hooks, finds zero failures, and clears the quarantine having done nothing
-    // (reviewer-dd03a98).
+    // Retain cleanup owners so a retry must actually discharge their debt.
     const outstandingHooks = new Set();
     const outstandingGit = new Set();
+    // A failed new-window command may still have created its window. Verify
+    // quiescence before removing credentials or work that runtime may be using.
+    if (windowMayExist) {
+      shTry(`tmux kill-window -t ${shq(`=${session}:=${instance}`)}`);
+      const winProbe = probe(["tmux", "list-windows", "-t", session, "-F", "#{window_name}"]);
+      const unresolved = !winProbe.ok || winProbe.out.split("\n").includes(instance);
+      if (unresolved) {
+        incomplete.push(!winProbe.ok
+          ? `tmux window ${session}:${instance}: could not verify removal (${winProbe.err || "list-windows failed"})`
+          : `tmux window ${session}:${instance} still running`);
+        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
+        if (work === "worktree") {
+          outstandingGit.add("worktree");
+          if (branch) outstandingGit.add("branch");
+        }
+        return quarantineInstanceHome({
+          home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
+          repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
+          launched: true, tmux: spawnTmux, recordRetirementBaseline: true,
+        });
+      }
+    }
     let compensationMeta = {};
     try {
       const comp = runLifecycleHooks("retire", {
@@ -5597,25 +5617,13 @@ export function spawnInstance(root, agent, o = {}) {
       incomplete.push(`${cap.id}: its spawn hook reported state it created, but the capability declares no retire hook, so OATS cannot undo it`);
       outstandingHooks.add(cap.id);
     }
-    const detail = requiredFailures.map((f) => `  ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
     let note;
-    if (incomplete.length) {
-      // QUARANTINE, do not delete. Compensation could not finish, and the home
-      // holds the very credentials and metadata a retry needs — for aweb,
-      // <instance-home>/.aw is the only signing key that can self-delete the
-      // remote identity. Removing it converts a transient cleanup failure into
-      // permanent remote residue (aggregate review at 798b156). The worktree and
-      // branch are already gone where that was independently safe; nothing is
-      // launched.
-      // A quarantine cannot promise to prove zero work. If a diagnostic exists
-      // but neither category identified its owner, conservatively require every
-      // retire hook to succeed on retry.
-      if (!outstandingHooks.size && !outstandingGit.size) {
-        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-      }
+    if (outstandingHooks.size || outstandingGit.size) {
+      // Preserve credentials and the original hook receipt until cleanup
+      // succeeds. The runtime is stopped; Git cleanup was independently safe.
       note = quarantineInstanceHome({
         home, instance, agent, incomplete,
-        failed: requiredFailures.map((f) => ({ capability: f.capability, event: f.event, ...(f.contract ? { contract: f.contract } : {}) })),
+        failed,
         outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg,
         hookMeta: hookRes.meta || {}, compensationMeta, launched: false,
         recordRetirementBaseline: true,
@@ -5625,18 +5633,24 @@ export function spawnInstance(root, agent, o = {}) {
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
-    throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration${note}`);
-  }
-  const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
-  const workDesc = work === "worktree"
-    ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
-    : work === "attached"
-    ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
-    : work === "workspace"
-    ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
-    : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
-  writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
+    return note;
+  };
+
+  try {
+    if (requiredFailures.length) {
+      const detail = requiredFailures.map((f) => `  ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
+      const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
+      throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`);
+    }
+    const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
+    const workDesc = work === "worktree"
+      ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
+      : work === "attached"
+      ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
+      : work === "workspace"
+      ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
+      : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
+    writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
 
 You are instance "${instance}" of agent "${agent.name}".
 - Home: ${home}${resolvedCfg.team ? `\n- Team: ${resolvedCfg.team.name}${resolvedCfg.team.id ? ` (${resolvedCfg.team.id})` : ""} — see teammates with \`oats status --team\`` : ""}
@@ -5644,315 +5658,198 @@ You are instance "${instance}" of agent "${agent.name}".
 - Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}
 ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`);
 
-  // Launch command. Spawn IS session start: this command is persisted in
-  // instance.json and executed in the instance's tmux window. Capabilities may
-  // contribute runtime-specific arguments via their spawn hook's `launch` map
-  // (e.g. aweb's Claude Code channel plugin flags).
-  const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
-  const bin = which(runtime === "claude" ? claudeBin : "pi");
-  if (!bin) throw new Error(`${runtime === "claude" ? claudeBin : runtime} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}`);
-  const hookArgs = hookRes.launch?.[runtime] ? ` ${hookRes.launch[runtime]}` : "";
-  let cmdline;
-  if (runtime === "claude") {
-    // .claude/skills already links the OATS-composed instance skill set.
-    // "--" terminates option parsing BEFORE the prompt: capability launch
-    // hooks can contribute greedy/variadic flags (e.g. aweb's
-    // --dangerously-load-development-channels), and without the separator
-    // the TASK.md text is swallowed as that flag's next value — claude
-    // errors out ("entries must be tagged: <task text>") and the window
-    // drops to the fallback shell, which reads as a silently stuck spawn.
-    cmdline = `${shq(bin)}${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
-  } else {
-    // STRICT CURRICULUM (pi): the OATS-composed set — no user, ancestor, project
-    // or package skill catalogs, and no auto-discovered AGENTS.md/CLAUDE.md.
-    // NOT "nothing else can contribute": extensions stay ambient by founder
-    // ruling (see below), and an extension's resources_discover hook can add
-    // skill paths that survive --no-skills. The OATS-managed root is exact; the
-    // extension surface is the operator's, and stating otherwise here would
-    // contradict the paragraph twelve lines down (reviewer-aggregate2).
-    //
-    //   --no-skills          ends discovery; --skill stays additive.
-    //   --no-context-files   stops ancestor AGENTS.md/CLAUDE.md auto-injection.
-    //                        It also stops the instance's OWN composed AGENTS.md
-    //                        loading, so that is delivered explicitly via
-    //                        --append-system-prompt. The work tree's AGENTS.md
-    //                        stays READABLE by the read tool: readable, not
-    //                        auto-injected, is the contract.
-    //   --no-prompt-templates  same posture for ambient prompt templates.
-    //
-    // Built-in tools and pi's native interaction model are untouched — OATS
-    // curates the curriculum, it does not cripple the runtime.
-    //
-    // EXTENSIONS STAY AMBIENT, by founder ruling: operators run cross-agent pi
-    // extensions (web search, output formatting) that every instance should
-    // keep. So no --no-extensions, and no -e flags either — pi discovers the
-    // installed extensions itself, and passing them explicitly as well would
-    // load the same extension twice.
-    //
-    // The trade-off is deliberate and narrow: an extension's
-    // `resources_discover` hook can contribute skill paths that survive
-    // --no-skills. Today only the OATS bridge does that, and inside an instance
-    // it contributes that instance's OWN .agents/skills, so the composed set is
-    // unchanged. A third-party extension that contributes skills WOULD add them,
-    // which is the accepted residue of keeping shared extensions working.
-    // Capability-required runtime packages are still verified and recorded
-    // (verifyRuntimePackages), so "aweb on pi requires the aweb pi package"
-    // still holds — it is loaded by pi's own discovery rather than by flag.
-    // pi has no `--` end-of-options marker (it rejects `--` in every position),
-    // so the task positional goes AHEAD of capability-contributed options:
-    // nothing preceding it is waiting for a value, so a trailing variadic
-    // contributed flag cannot consume the task.
-    cmdline = `${shq(bin)} --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")}${hookArgs}`;
-  }
-  // OATS_INSTANCE_HOME is the runtime-neutral contract name (absolute path to
-  // the instance home) exported to EVERY runtime. PI_AGENT_HOME/PI_AGENT_INSTANCE
-  // are pi-branded predecessors kept as compatibility aliases: the separately
-  // published @awebai/oats-pi extension and bin/oats.mjs still read them, and
-  // an older installed extension must keep working against a newer kernel.
-  const hookEnv = Object.keys(hookRes.env).sort().map((name) => `${name}=${shq(hookRes.env[name])}`).join(" ");
-  cmdline = `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${hookEnv ? ` ${hookEnv}` : ""} ${cmdline}`;
-
-  const meta = {
-    agent: agent.name, kind: agent.kind || "persistent", instance, home,
-    repo: repoAbs, work, branch, runtime, model: model || undefined,
-    team: resolvedCfg.team || undefined,
-    parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
-    siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
-    relation: relation || undefined,
-    relativeTo: relation ? relativeTo : undefined,
-    spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
-    capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
-    layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
-    capabilities: resolvedCfg.capabilities.map((cap) => ({
-      id: cap.id, layer: cap.layer, command: cap.command, origin: cap.origin, level: cap.level,
-      settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
-      hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
-      ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
-    })),
-    skills: [...chosen].sort(([a], [b]) => a.localeCompare(b)).map(([name, v]) => ({ name, source: v.source })),
-    instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
-    // The auditable record of the curriculum: what the resolved composition
-    // PROMISED, and what actually landed. Both are asserted equal before launch;
-    // 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 })),
-      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 })),
-        // `filtered` records that the operator's settings entry narrows this
-        // package's resources. A non-empty filter is a deliberate choice whose
-        // glob semantics belong to the runtime, so it is auditable here rather
-        // than second-guessed at spawn.
-        runtimePackages: runtimePackages.map((x) => ({ capability: x.capability, runtime: x.runtime, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "runtime-discovery" })),
-        // What this instance ACTUALLY sees beyond the OATS-composed set. Recorded
-        // so the deviation from strict composition is auditable instead of
-        // implied — the honest contract, not an aspiration.
-        runtimePosture: runtime === "claude"
-          ? {
-            oatsComposed: "skills via .claude/skills -> ../.agents/skills; instructions via CLAUDE.md -> AGENTS.md",
-            ambient: ["user skills", "project and ancestor skills to the repository root", "user and project plugins", "user and project settings", "user and ancestor CLAUDE.md"],
-            why: "founder ruling: Claude Code's own global and per-repo configuration stays enabled — it is powerful, and the operator decides. An all-OATS setup is the way to opt out.",
-          }
-          : {
-            oatsComposed: "skills via --skill <instance-home>/.agents/skills; instructions via --append-system-prompt",
-            curtailed: ["user skills", "project and ancestor skills", "package skills", "ambient AGENTS.md/CLAUDE.md discovery", "ambient prompt templates"],
-            ambient: ["globally configured pi extensions, and any resources they contribute"],
-            why: "founder ruling: shared cross-agent pi extensions (web search, output formatting) stay available to every instance.",
-          },
-        canonicalSkillTree: join(home, ".agents", "skills"),
-        skillAlias: { path: join(home, ".claude", "skills"), target: join("..", ".agents", "skills") },
+    // Launch command. Spawn IS session start: this command is persisted in
+    // instance.json and executed in the instance's tmux window. Capabilities may
+    // contribute runtime-specific arguments via their spawn hook's `launch` map
+    // (e.g. aweb's Claude Code channel plugin flags).
+    const hookArgs = hookRes.launch?.[runtime] ? ` ${hookRes.launch[runtime]}` : "";
+    let cmdline;
+    if (runtime === "claude") {
+      // .claude/skills already links the OATS-composed instance skill set.
+      // "--" terminates option parsing BEFORE the prompt: capability launch
+      // hooks can contribute greedy/variadic flags (e.g. aweb's
+      // --dangerously-load-development-channels), and without the separator
+      // the TASK.md text is swallowed as that flag's next value — claude
+      // errors out ("entries must be tagged: <task text>") and the window
+      // drops to the fallback shell, which reads as a silently stuck spawn.
+      cmdline = `${shq(bin)}${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
+    } else {
+      // STRICT CURRICULUM (pi): the OATS-composed set — no user, ancestor, project
+      // or package skill catalogs, and no auto-discovered AGENTS.md/CLAUDE.md.
+      // NOT "nothing else can contribute": extensions stay ambient by founder
+      // ruling (see below), and an extension's resources_discover hook can add
+      // skill paths that survive --no-skills. The OATS-managed root is exact; the
+      // extension surface is the operator's, and stating otherwise here would
+      // contradict the paragraph twelve lines down (reviewer-aggregate2).
+      //
+      //   --no-skills          ends discovery; --skill stays additive.
+      //   --no-context-files   stops ancestor AGENTS.md/CLAUDE.md auto-injection.
+      //                        It also stops the instance's OWN composed AGENTS.md
+      //                        loading, so that is delivered explicitly via
+      //                        --append-system-prompt. The work tree's AGENTS.md
+      //                        stays READABLE by the read tool: readable, not
+      //                        auto-injected, is the contract.
+      //   --no-prompt-templates  same posture for ambient prompt templates.
+      //
+      // Built-in tools and pi's native interaction model are untouched — OATS
+      // curates the curriculum, it does not cripple the runtime.
+      //
+      // EXTENSIONS STAY AMBIENT, by founder ruling: operators run cross-agent pi
+      // extensions (web search, output formatting) that every instance should
+      // keep. So no --no-extensions, and no -e flags either — pi discovers the
+      // installed extensions itself, and passing them explicitly as well would
+      // load the same extension twice.
+      //
+      // The trade-off is deliberate and narrow: an extension's
+      // `resources_discover` hook can contribute skill paths that survive
+      // --no-skills. Today only the OATS bridge does that, and inside an instance
+      // it contributes that instance's OWN .agents/skills, so the composed set is
+      // unchanged. A third-party extension that contributes skills WOULD add them,
+      // which is the accepted residue of keeping shared extensions working.
+      // Capability-required runtime packages are still verified and recorded
+      // (verifyRuntimePackages), so "aweb on pi requires the aweb pi package"
+      // still holds — it is loaded by pi's own discovery rather than by flag.
+      // pi has no `--` end-of-options marker (it rejects `--` in every position),
+      // so the task positional goes AHEAD of capability-contributed options:
+      // nothing preceding it is waiting for a value, so a trailing variadic
+      // contributed flag cannot consume the task.
+      cmdline = `${shq(bin)} --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")}${hookArgs}`;
+    }
+    // OATS_INSTANCE_HOME is the runtime-neutral contract name (absolute path to
+    // the instance home) exported to EVERY runtime. PI_AGENT_HOME/PI_AGENT_INSTANCE
+    // are pi-branded predecessors kept as compatibility aliases: the separately
+    // published @awebai/oats-pi extension and bin/oats.mjs still read them, and
+    // an older installed extension must keep working against a newer kernel.
+    const hookEnv = Object.keys(hookRes.env).sort().map((name) => `${name}=${shq(hookRes.env[name])}`).join(" ");
+    cmdline = `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${hookEnv ? ` ${hookEnv}` : ""} ${cmdline}`;
+
+    const meta = {
+      agent: agent.name, kind: agent.kind || "persistent", instance, home,
+      repo: repoAbs, work, branch, runtime, model: model || undefined,
+      team: resolvedCfg.team || undefined,
+      parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
+      siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
+      relation: relation || undefined,
+      relativeTo: relation ? relativeTo : undefined,
+      spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
+      capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
+      layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
+      capabilities: resolvedCfg.capabilities.map((cap) => ({
+        id: cap.id, layer: cap.layer, command: cap.command, origin: cap.origin, level: cap.level,
+        settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
+        hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
+        ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
+      })),
+      skills: [...chosen].sort(([a], [b]) => a.localeCompare(b)).map(([name, v]) => ({ name, source: v.source })),
+      instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
+      // The auditable record of the curriculum: what the resolved composition
+      // PROMISED, and what actually landed. Both are asserted equal before launch;
+      // 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 })),
+        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 })),
+          // `filtered` records that the operator's settings entry narrows this
+          // package's resources. A non-empty filter is a deliberate choice whose
+          // glob semantics belong to the runtime, so it is auditable here rather
+          // than second-guessed at spawn.
+          runtimePackages: runtimePackages.map((x) => ({ capability: x.capability, runtime: x.runtime, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "runtime-discovery" })),
+          // What this instance ACTUALLY sees beyond the OATS-composed set. Recorded
+          // so the deviation from strict composition is auditable instead of
+          // implied — the honest contract, not an aspiration.
+          runtimePosture: runtime === "claude"
+            ? {
+              oatsComposed: "skills via .claude/skills -> ../.agents/skills; instructions via CLAUDE.md -> AGENTS.md",
+              ambient: ["user skills", "project and ancestor skills to the repository root", "user and project plugins", "user and project settings", "user and ancestor CLAUDE.md"],
+              why: "founder ruling: Claude Code's own global and per-repo configuration stays enabled — it is powerful, and the operator decides. An all-OATS setup is the way to opt out.",
+            }
+            : {
+              oatsComposed: "skills via --skill <instance-home>/.agents/skills; instructions via --append-system-prompt",
+              curtailed: ["user skills", "project and ancestor skills", "package skills", "ambient AGENTS.md/CLAUDE.md discovery", "ambient prompt templates"],
+              ambient: ["globally configured pi extensions, and any resources they contribute"],
+              why: "founder ruling: shared cross-agent pi extensions (web search, output formatting) stay available to every instance.",
+            },
+          canonicalSkillTree: join(home, ".agents", "skills"),
+          skillAlias: { path: join(home, ".claude", "skills"), target: join("..", ".agents", "skills") },
+        },
       },
-    },
-    capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
-      id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
-      hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
-      missingRequires: cap.missingRequires, trust: cap.trust,
-      executable: cap.executable,
-    })),
-    tmux: { session, window: instance },
-    command: cmdline, createdAt: new Date().toISOString(),
-  };
-  const spawnWarnings = warnings;
-
-  let launched = false;
-  if (launch) {
-    if (!which("tmux")) throw new Error("tmux not installed (brew install tmux)");
-    if (!tmuxAlive(session)) {
-      const hq = existsSync(root) ? root : workspaceOf(root); // all-local scopes may have no agents/ dir
-      sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
-      shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
-      shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
-    }
-    if (tmuxWindows(session).includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
-    meta.tmux.socket = tmuxSocket(session);
-    meta.launched = true;
-    // Commit the final child metadata and its independent byte authority before
-    // the managed runtime can write. No child-home transition follows launch.
-    writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-    writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
-    // Wrap the command so the window drops into an interactive shell when the
-    // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
-    const windowCmd = `${cmdline}; exec "\${SHELL:-/bin/zsh}"`;
-    sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)} ${shq(windowCmd)}`);
-    launched = true;
-  } else {
-    meta.launched = false;
-    writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-    writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
-  }
-
-  // parent relation: re-point the ANCHOR's recorded lineage so its parent is
-  // the new instance (e.g. a maintainer reviewing the spawner sits above it).
-  // Committed LAST — after every other fallible step incl. launch — so a
-  // failed spawn (missing tmux, window collision, new-window error) never
-  // leaves the anchor's graph pointing at a zombie. --no-launch reaches here
-  // too: the scaffold itself succeeded, which is that path's definition of
-  // success. The write ITSELF is fallible (anchor retired concurrently,
-  // unwritable file): on failure the spawn is COMPENSATED — kill the launched
-  // window and remove the scaffold — so the operation stays all-or-nothing:
-  // either agent live + lineage recorded, or neither.
-  if (relation === "parent" && anchorMeta && anchorMetaPath) {
-    // Atomic anchor update: writeFileSync truncates-then-writes, so a mid-write
-    // failure (ENOSPC, I/O) could leave the anchor's instance.json empty.
-    // Write a same-directory temp file and rename it over the anchor — rename
-    // is atomic on POSIX, so the anchor is always either old or new, never
-    // truncated.
-    const tmpPath = `${anchorMetaPath}.tmp-${instance}`;
-    try {
-      anchorMeta.parentInstance = instance;
-      delete anchorMeta.siblingInstance; // the new parent carries the old sibling link
-      writeFileSync(tmpPath, JSON.stringify(anchorMeta, null, 2) + "\n");
-      renameSync(tmpPath, anchorMetaPath);
-    } catch (e) {
-      // Compensation steps are each independent and best-effort: no step may
-      // abort the remaining rollback or mask the original anchor-write error
-      // (rmSync force:true only suppresses ENOENT — EPERM/IO still throw).
-      // Failures are COLLECTED and reported: the thrown message must never
-      // claim a cleanup that did not happen.
-      const incomplete = [];
-      // Verification probes are argv-based (no shell interpolation — branch
-      // names may contain valid-but-hostile metacharacters like $(…)) and
-      // THREE-STATE: confirmed-absent | still-present | could-not-verify.
-      // Both of the latter are reported — a failed probe must never pass as
-      // a confirmed cleanup (fail closed).
-      const probe = (argv) => {
-        try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
-        // With encoding:"utf8" a silent command yields stderr === "" — FALSY — so
-          // `e2.stderr || e2.message` fell through to "Command failed: …" and made
-          // every clean probe look like a failed one. `git rev-parse --verify
-          // --quiet` on an absent ref is exactly that case, so a successful branch
-          // deletion could never be confirmed and rollback always reported
-          // INCOMPLETE. Distinguish "no output" from "no stderr captured".
-          catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
-      };
-      let windowUnresolved = false;
-      try { rmSync(tmpPath, { force: true }); } catch (e2) { incomplete.push(`temp file ${tmpPath}: ${e2.message}`); }
-      if (launched) {
-        // shTry returns "" on success and undefined on failure — neither is a
-        // reliable signal for kill-window, so verify the EFFECT unconditionally.
-        shTry(`tmux kill-window -t ${shq(`=${session}:=${instance}`)}`);
-        const winProbe = probe(["tmux", "list-windows", "-t", session, "-F", "#{window_name}"]);
-        if (!winProbe.ok) { incomplete.push(`tmux window ${session}:${instance}: could not verify removal (${winProbe.err || "list-windows failed"})`); windowUnresolved = true; }
-        else if (winProbe.out.split("\n").includes(instance)) { incomplete.push(`tmux window ${session}:${instance} still running`); windowUnresolved = true; }
+      capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
+        id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
+        hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
+        missingRequires: cap.missingRequires, trust: cap.trust,
+        executable: cap.executable,
+      })),
+      tmux: { session, window: instance },
+      command: cmdline, createdAt: new Date().toISOString(),
+    };
+    const spawnWarnings = warnings;
+
+    spawnTmux = meta.tmux;
+    if (launch) {
+      if (!tmuxAlive(session)) {
+        const hq = existsSync(root) ? root : workspaceOf(root); // all-local scopes may have no agents/ dir
+        sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
+        shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
+        shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
       }
-      // Outstanding debt as IDS, so a retry can verify it — same contract the
-      // required-hook rollback records.
-      const outstandingHooks = new Set();
-      const outstandingGit = new Set();
-      let compMeta = hookRes.meta || {};
+      if (tmuxWindows(session).includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
+      meta.tmux.socket = tmuxSocket(session);
+      meta.launched = true;
+      // Commit the final child metadata and its independent byte authority before
+      // the managed runtime can write. No child-home transition follows launch.
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
+      // Wrap the command so the window drops into an interactive shell when the
+      // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
+      const windowCmd = `${cmdline}; exec "\${SHELL:-/bin/zsh}"`;
+      windowMayExist = true;
+      sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)} ${shq(windowCmd)}`);
+    } else {
+      meta.launched = false;
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
+    }
+
+    // parent relation: re-point the ANCHOR's recorded lineage so its parent is
+    // the new instance (e.g. a maintainer reviewing the spawner sits above it).
+    // Committed LAST — after every other fallible step incl. launch — so a
+    // failed spawn (missing tmux, window collision, new-window error) never
+    // leaves the anchor's graph pointing at a zombie. --no-launch reaches here
+    // too: the scaffold itself succeeded, which is that path's definition of
+    // success. The write ITSELF is fallible (anchor retired concurrently,
+    // unwritable file): on failure the spawn is COMPENSATED — kill the launched
+    // window and remove the scaffold — so the operation stays all-or-nothing:
+    // either agent live + lineage recorded, or neither.
+    if (relation === "parent" && anchorMeta && anchorMetaPath) {
+      // Atomic anchor update: writeFileSync truncates-then-writes, so a mid-write
+      // failure (ENOSPC, I/O) could leave the anchor's instance.json empty.
+      // Write a same-directory temp file and rename it over the anchor — rename
+      // is atomic on POSIX, so the anchor is always either old or new, never
+      // truncated.
+      const tmpPath = `${anchorMetaPath}.tmp-${instance}`;
       try {
-        const comp = runLifecycleHooks("retire", {
-          home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
-          workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
-          priorMeta: hookRes.meta || {},
-        });
-        // runLifecycleHooks catches hook errors internally — detect them via
-        // the structured failures field, not this outer catch.
-        for (const f of comp.failures || []) { incomplete.push(`retire hook ${f.capability}: ${f.message}`); outstandingHooks.add(f.capability); }
-        // Exit 0 while reporting "not retired" is also unfinished cleanup.
-        for (const [capId, m] of Object.entries(comp.meta || {})) {
-          if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
-            incomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
-            outstandingHooks.add(capId);
-          }
-        }
-        compMeta = { ...compMeta, ...(comp.meta || {}) };
-      } catch (e2) {
-        incomplete.push(`retire hooks: ${e2.message}`);
-        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-      }
-      if (work === "worktree") {
-        const wt = join(home, "work");
-        // Git canonicalizes symlinked parent components when registering a
-        // worktree. Use the path captured immediately after successful add —
-        // retire-hook compensation may already have removed/inaccessible'd wt.
-        const wtCanonical = worktreeCanonical;
-        if (!wtCanonical) incomplete.push(`git worktree ${wt}: could not verify removal (canonical path unavailable)`);
-        probe(["git", "-C", repoAbs, "worktree", "remove", "--force", wt]);
-        probe(["git", "-C", repoAbs, "worktree", "prune"]);
-        // Verify effects, not exit codes: parse exact NUL-delimited `worktree`
-        // records (never substring-match a lexical path against Git's canonical
-        // registered path). The tree must be deregistered or later rmSync(home)
-        // strands stale Git metadata.
-        const wtProbe = probe(["git", "-C", repoAbs, "worktree", "list", "--porcelain", "-z"]);
-        if (!wtProbe.ok) { incomplete.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`); outstandingGit.add("worktree"); }
-        else {
-          const registered = wtProbe.out.split("\0").filter((field) => field.startsWith("worktree ")).map((field) => field.slice("worktree ".length));
-          if (wtCanonical && registered.includes(wtCanonical)) { incomplete.push(`git worktree ${wtCanonical}: still registered`); outstandingGit.add("worktree"); }
-        }
-        if (branch) {
-          probe(["git", "-C", repoAbs, "branch", "-D", branch]);
-          // rev-parse --verify: exit 0 = ref exists; exit 1 with empty stderr
-          // under --quiet = confirmed absent; anything else = could not verify.
-          const brProbe = probe(["git", "-C", repoAbs, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
-          if (brProbe.ok) { incomplete.push(`git branch ${branch}: still exists`); outstandingGit.add("branch"); }
-          else if (brProbe.status !== 1 || brProbe.err) { incomplete.push(`git branch ${branch}: could not verify deletion (${brProbe.err || `rev-parse exit ${brProbe.status}`})`); outstandingGit.add("branch"); }
-        }
-      }
-      // QUARANTINE, do not delete. This path deleted the home unconditionally —
-      // including while its own retire hook was reporting failure — which is
-      // exactly the credential destruction the required-hook path was fixed to
-      // avoid (reviewer-terminal54a87fd). A quarantine with nothing outstanding
-      // would be a proof obligation of zero, so the record is filled
-      // conservatively when both categories somehow came up empty.
-      // Quarantine only for state that COMPENSATION owns and did not finish: a
-      // retire hook that failed, Git the rollback could not undo, or a window
-      // still running. Litter beside the anchor (a leftover temp file) is
-      // reported but is not the child's external state, and retaining a home
-      // for it would turn an ordinary failure into a --force cleanup.
-      const unresolved = outstandingHooks.size > 0 || outstandingGit.size > 0 || windowUnresolved;
-      let rollbackNote;
-      if (unresolved) {
-        if (!outstandingHooks.size && !outstandingGit.size) {
-          for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-        }
-        rollbackNote = quarantineInstanceHome({
-          home, instance, agent, incomplete,
-          failed: [{ capability: "oats.kernel", event: "spawn" }],
-          outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg,
-          // The SPAWN metadata — the aweb alias a retry needs to delete the
-          // remote identity. Passing the compensation result overwrote it with
-          // `{retired:false}`, discarding the very handle cleanup requires.
-          hookMeta: hookRes.meta || {}, compensationMeta: compMeta,
-          launched: windowUnresolved, tmux: meta.tmux,
-          recordRetirementBaseline: true,
-        }).replace(/^ — /, "");
-      } else {
-        try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
-        if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
-        rollbackNote = incomplete.length
-          ? `rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}`
-          : "spawn rolled back (window killed, hooks compensated, scaffold removed)";
+        anchorMeta.parentInstance = instance;
+        delete anchorMeta.siblingInstance; // the new parent carries the old sibling link
+        writeFileSync(tmpPath, JSON.stringify(anchorMeta, null, 2) + "\n");
+        renameSync(tmpPath, anchorMetaPath);
+      } catch (e) {
+        try { rmSync(tmpPath, { force: true }); }
+        catch (cleanupError) { ancillaryCleanup.push(`temp file ${tmpPath}: ${cleanupError.message}`); }
+        throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message})`);
       }
-      throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message}) — ${rollbackNote}`);
     }
-  }
 
-  return { ...meta, attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+    return { ...meta, attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+  } catch (error) {
+    const note = compensateSpawn();
+    error.message += note;
+    throw error;
+  }
 }
 
 export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
@@ -6068,13 +5965,8 @@ export const QUARANTINE_CLEANUP_VERSION = 1;
 /** The rollback-owned Git steps a quarantine can still owe. */
 export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
 
-/** Retain a half-built instance home and mark it, so `oats retire <instance>` can
- * finish the cleanup that failed. THE one implementation: a spawn has two
- * rollback paths — a failed required hook, and a failure after the instance was
- * already launched (re-pointing a parent anchor) — and the second one deleted the
- * home while its own retire hook was reporting failure, destroying the credential
- * needed to undo the external state that survived (reviewer-terminal54a87fd).
- * Two copies of this logic is how that divergence happened; there is now one. */
+/** Retain the home and its cleanup receipt when spawn compensation or retirement
+ * cannot finish. Keeping the original credentials makes cleanup retryable. */
 function quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason }) {
   try {
     writeFileSync(join(home, ".oats-rollback-incomplete.json"), JSON.stringify({