@awebai/oats 0.24.6 → 0.24.8

package/lib/core.mjs

@@ -40,6 +40,7 @@ import { PI_SDK_HOST, isPiSdkHost, validatePiHostRecipe, piHostArgv, resolvePiSd
 import { capturedPiSessionDirectory, requireCapturedPiRecordSupport, inspectCapturedPiRoot, prepareCapturedPiStart } from "./captured-pi-custody.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
+import { appendEvent } from "./instance-events.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 import { oatsError } from "./errors.mjs";
@@ -4248,6 +4249,22 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     for (const b of composition.blocks || []) expected.push({ type: "instruction-block", source: b.source, declared: b.file, path: b.file });
   }
 
+  // A soul that DECLARES an operational capability (requires.capabilities,
+  // e.g. oats.core written by `oats create`) has, by that declaration, given up
+  // the kernel's legacy skill injection. If the declared capability is not
+  // active for this soul in this context, the instance would start with no
+  // operational curriculum and no warning — a hollow agent. That is an unmet
+  // declared requirement: refuse, attributed, with the exact remedy. Removing
+  // the declaration from soul.yaml is the supported way to opt out.
+  const declaredOps = declaredOperationalCapabilities(soulDir);
+  const inactiveOps = declaredOps.filter((id) => !(resolved.capabilities || []).some((c) => c.id === id));
+  if (inactiveOps.length) {
+    const soulName = agent?.name ?? basename(dirname(soulDir));
+    const remedy = inactiveOps.map((id) => `oats use ${id} --soul ${soulName}${contextDir ? ` --dir ${contextDir}` : ""}`).join(" && ");
+    throw Object.assign(oatsError("E_REQUIREMENT_INACTIVE", `soul ${soulName} declares ${inactiveOps.join(", ")} in requires.capabilities, but ${inactiveOps.length === 1 ? "it is" : "they are"} not active for this soul in ${contextDir}; the declaration suppresses the kernel's legacy skills, so the instance would start with no operational curriculum.\n  Acquire if needed (\`oats install oats.framework\`), then activate: ${remedy}\n  Or remove the declaration from ${join(soulDir, "soul.yaml")} to run without it.`),
+      { soul: soulName, capabilities: inactiveOps, context: contextDir, remedy });
+  }
+
   // A capability that declares a REQUIRED hook it cannot execute must not spawn.
   // Advisory executable hooks stay disabled-with-warning; a required one is a
   // promise, and starting without it is the failure required:true exists to stop.
@@ -5196,7 +5213,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
     home: soulDir, instance: name, agentName: name, soulDir,
     contextDir: ctx, workspaceDir: workspaceOf(root), rootDir: root, resolved,
   });
-  return { agentDir, soulDir, ...(notes.length ? { notes } : {}) };
+  return { agentDir, soulDir, declaredCapabilities: Object.keys(requires?.capabilities ?? {}), ...(notes.length ? { notes } : {}) };
 }
 function defaultSoulAgentsMd(name, description) {
   return `# ${name}
@@ -5218,8 +5235,8 @@ export function createAgent(root, o) {
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
-  const { agentDir, notes } = writeSoul(root, { ...o, name, kind });
-  return { agent: name, kind, soul: soulOf(agentDir), ...(notes ? { notes } : {}) };
+  const { agentDir, notes, declaredCapabilities } = writeSoul(root, { ...o, name, kind });
+  return { agent: name, kind, soul: soulOf(agentDir), declaredCapabilities, ...(notes ? { notes } : {}) };
 }
 
 /** Upsert a local agent soul (from raw instructions or a Claude-style def file).
@@ -5549,6 +5566,8 @@ export function missingLaunchEnvRefs(configEnv, env = process.env) {
  *  configuration behind (its executable and args are not carried), and a
  *  model never crosses runtimes: explicit or configured model, else the
  *  frozen model on the same runtime, else the runtime's native default. */
+/** Sentinel a caller passes as `model` to mean "the runtime's own default, not the configured/soul preference". */
+export const NATIVE_DEFAULT_MODEL = "@native-default";
 export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, selection = {} }) {
   const bad = (code, msg) => { throw oatsError(code, msg); };
   let wanted = selection.launchConfig;
@@ -5572,8 +5591,13 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   const runtime = config?.runtime || selection.runtime || (frozen ? frozen.runtime : agent?.runtime || "pi");
   if (!LAUNCH_RUNTIMES.includes(runtime)) bad("E_UNSUPPORTED_RUNTIME", `unknown runtime "${runtime}" (pi|claude|codex)`);
   let model, modelSource;
-  const explicit = selection.model !== undefined && selection.model !== null && String(selection.model).trim() !== "";
-  if (explicit) {
+  // K6: an EXPLICIT "use the runtime's native default" is distinct from an
+  // omitted model (which inherits the configuration's or soul's preference).
+  const nativeDefault = selection.model === NATIVE_DEFAULT_MODEL || (selection.model && typeof selection.model === "object" && selection.model.kind === "native-default");
+  const explicit = !nativeDefault && selection.model !== undefined && selection.model !== null && String(selection.model).trim() !== "";
+  if (nativeDefault) {
+    model = ""; modelSource = "native default (explicit)";
+  } else if (explicit) {
     model = resolveModelPreference(String(selection.model), runtime); modelSource = "explicit";
     if (!model) bad("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(selection.model)} has no entry usable by runtime ${runtime}; give a ${runtime} model id`);
   } else if (config?.model) {
@@ -6063,6 +6087,32 @@ export function spawnInstance(root, agent, o = {}) {
     if (anchorMeta?.siblingInstance) siblingInstance = anchorMeta.siblingInstance;
   }
   if (!relation && attachedOwner && attachedOwner !== instance) parentInstance = attachedOwner;
+  // K5 §4 — child-spawn permission is ENFORCED here, by the spawn route. The
+  // parent's recorded policy (instance.json policy.childSpawns) says whether
+  // it may have children; off refuses, attributed to that policy and its
+  // origin. Absent policy = allowed (today's behaviour), reported as such.
+  // A lifecycle-authority claim, not an OS sandbox.
+  const childPolicyOf = (metaOf) => metaOf?.policy?.childSpawns && typeof metaOf.policy.childSpawns === "object"
+    ? metaOf.policy.childSpawns : { allowed: true, origin: { kind: "default", detail: "no recorded policy: children allowed" } };
+  if (parentInstance && parentInstance !== instance) {
+    const parentHome = parentInstance === relativeTo && anchorHome ? anchorHome
+      : (findInstanceHome(root, parentInstance) || findTeamInstance(root, parentInstance))?.home;
+    const parentMeta = parentHome && existsSync(join(parentHome, "instance.json")) ? JSON.parse(readFileSync(join(parentHome, "instance.json"), "utf8")) : anchorMeta;
+    const policy = childPolicyOf(parentMeta);
+    if (policy.allowed === false) {
+      if (parentHome) appendEvent(parentHome, { kind: "child-spawn-refused", data: { child: instance, agent: agent.name, policy } });
+      throw Object.assign(oatsError("E_CHILD_SPAWNS_DISABLED", `${parentInstance} does not allow child spawns (policy origin: ${policy.origin?.kind ?? "recorded"}${policy.origin?.detail ? ` — ${policy.origin.detail}` : ""}); nothing was spawned. Spawn without a parent relation, or respawn the parent with --allow-child-spawns.`),
+        { parent: parentInstance, policy });
+    }
+  }
+  // This instance's own policy: soul declaration (children.spawn), overridden
+  // per spawn; recorded so the route above and the readiness view can read it.
+  const declaredChildren = agent.children && typeof agent.children === "object" ? agent.children : (typeof agent.children === "string" ? (() => { try { return JSON.parse(agent.children); } catch { return undefined; } })() : undefined);
+  const ownChildPolicy = o.allowChildSpawns !== undefined
+    ? { allowed: o.allowChildSpawns === true, origin: { kind: "spawn-option", detail: o.allowChildSpawns ? "--allow-child-spawns" : "--no-child-spawns" } }
+    : declaredChildren && typeof declaredChildren.spawn === "boolean"
+      ? { allowed: declaredChildren.spawn, origin: { kind: "soul", detail: `children.spawn: ${declaredChildren.spawn} in soul.yaml` } }
+      : { allowed: true, origin: { kind: "default", detail: "no declaration: children allowed" } };
 
   // Inherited edges must round-trip too. Sibling and parent relations copy
   // names from the ANCHOR's instance.json (anchorMeta.parentInstance /
@@ -6175,6 +6225,33 @@ export function spawnInstance(root, agent, o = {}) {
   const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
 
   if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
+  // K6: everything a spawn decides is decided by here — and nothing has been
+  // touched. Branch/base for a worktree are named now (not after mkdir) so the
+  // preview and the apply agree on them; `o.baseRef` selects the start point.
+  let plannedBranch = null, plannedBase = null;
+  if (work === "worktree") {
+    plannedBranch = o.branch || `agents/${instance}`;
+    // Validity is Git's own rule (check-ref-format), not a stricter charset:
+    // every later git call takes the name as an argv element, never through a
+    // shell, so a valid-but-hostile name is safe and stays exercisable.
+    try { execFileSync("git", ["check-ref-format", "--branch", plannedBranch], { stdio: ["ignore", "pipe", "pipe"] }); }
+    catch { throw oatsError("E_BAD_ARGS", `branch ${JSON.stringify(plannedBranch)} is not a valid branch name`); }
+    if (shInTry(repoAbs, `git rev-parse --verify --quiet ${shq("refs/heads/" + plannedBranch)}`) !== undefined) throw oatsError("E_BRANCH_EXISTS", `branch ${plannedBranch} already exists in ${repoAbs}; choose another name or reuse it deliberately`);
+    const baseRef = o.baseRef || "HEAD";
+    const baseOid = shInTry(repoAbs, `git rev-parse --verify --quiet ${shq(baseRef + "^{commit}")}`);
+    if (baseOid === undefined) throw oatsError("E_BASE_UNKNOWN", `base ${JSON.stringify(baseRef)} does not resolve to a commit in ${repoAbs}`);
+    plannedBase = { ref: baseRef, oid: baseOid };
+  }
+  if (o.preview === true) {
+    return {
+      spawnPreviewApi: 1, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
+      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,
+    };
+  }
   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
@@ -6275,11 +6352,11 @@ export function spawnInstance(root, agent, o = {}) {
   let branch;
   let worktreeCanonical; // captured immediately after add, before setup/hooks can mutate/remove it
   if (work === "worktree") {
-    branch = o.branch || `agents/${instance}`;
+    branch = plannedBranch;
     const wt = join(home, "work");
     let added = false;
     try {
-      execFileSync("git", ["-C", repoAbs, "worktree", "add", wt, "-b", branch],
+      execFileSync("git", ["-C", repoAbs, "worktree", "add", wt, "-b", branch, plannedBase.oid],
         { stdio: ["ignore", "pipe", "pipe"] });
       added = true;
       // Git registers a canonical path. Retain it now: compensation hooks can
@@ -6594,6 +6671,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       relation: relation || undefined,
       relativeTo: relation ? relativeTo : undefined,
       spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
+      policy: { childSpawns: ownChildPolicy },
       capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
       layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
       capabilities: resolvedCfg.capabilities.map((cap) => ({
@@ -6720,6 +6798,8 @@ ${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 } });
+    if (launch) appendEvent(home, { kind: "launched", data: { runtime, backend, launchConfig: launchConfig?.name ?? null } });
     return { ...meta, 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();
@@ -7071,6 +7151,12 @@ function retirementBaselinePath(home) {
  *  loudly, and streaming is deliberately not attempted in this change. */
 const GIT_MAX_BUFFER = 512 * 1024 * 1024;
 
+/** Kernel-owned receipts the kernel itself appends to a home after the spawn
+ *  baseline (events log, stop/restart receipts). They are evidence about the
+ *  instance, not the instance's work, so a retirement fingerprint ignores them —
+ *  otherwise every stop or event write would read as "changed home bytes". */
+const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
+const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
 function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false } = {}) {
   const hash = createHash("sha256");
   const rootStat = lstatSync(root);
@@ -7083,7 +7169,7 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
   }
   const walk = (dir, rel = "") => {
     for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      if ((!rel && excludeRoot.has(e.name)) || (excludeGitMetadata && e.name === ".git")) continue;
+      if ((!rel && excludeRoot.has(e.name)) || (!rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
       const childRel = rel ? join(rel, e.name) : e.name;
       const path = join(dir, e.name);
       const st = lstatSync(path);
@@ -7259,6 +7345,73 @@ export function inspectInstanceSession(home) {
   catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
 }
 
+/** K3: quiesce one instance's session and RETAIN everything else — home,
+ *  worktree, transcript, launch configuration — so `restart` can bring it back.
+ *  Exactly restart's stop half under the same independent endpoint authority
+ *  (`instanceSessionTarget`), bounded and never escalated: a harness still
+ *  there after the grace is reported still running, nothing is killed harder.
+ *  A no-launch or already-idle instance is a no-op that says so. */
+function tmuxServerLost(e) { return /no server running on |(?:error connecting to|failed to connect to) .*(?:No such file or directory|Connection refused)/i.test(String(e.stderr ?? e.message ?? "")); }
+export function stopInstanceSession(home, o = {}) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
+  if (o.graceMs !== undefined && (!Number.isSafeInteger(o.graceMs) || o.graceMs < 1 || o.graceMs > 300000)) throw oatsError("E_BAD_ARGS", "stop grace must be 1-300000 ms");
+  const realHome = realPathOrNearest(home);
+  if (existsSync(retirePendingMarkerPath(realHome))) throw oatsError("E_INSTANCE_RETIRING", `${basename(realHome)} is being retired; nothing was stopped`);
+  const s = instanceSessionTarget(realHome);
+  if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
+  let before;
+  try { before = inspectSessionTarget(s.target, s.io); }
+  catch (e) { if (s.target.backend === "tmux" && tmuxServerLost(e)) before = { present: false, state: "stopped" }; else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${e.message}`); }
+  if (!before.present || before.state === "shell" || before.state === "stopped") return { home: s.home, backend: s.target.backend, stopped: false, alreadyIdle: true, state: before.state, receipt: null };
+  const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, io: s.io, kill: o.io?.kill, sleep: o.io?.sleep });
+  writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
+  appendEvent(realHome, { kind: receipt.exited ? "stopped" : "stop-refused", data: { signal: receipt.signal, waitedMs: receipt.waitedMs, stillRunning: receipt.stillRunning ?? [], state: receipt.state } });
+  if (!receipt.exited) throw Object.assign(oatsError("E_SESSION_STOP_FAILED", `${basename(realHome)} was asked to stop (${receipt.signal} to ${receipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")}) and is still running after ${receipt.waitedMs} ms; nothing was escalated`), { receipt });
+  return { home: s.home, backend: s.target.backend, stopped: true, alreadyIdle: false, state: receipt.state, receipt };
+}
+
+/** Recompose a running home's instructions from its CURRENT canonical soul and
+ *  context — an operator-authorized refresh, so a role change can reach a live
+ *  instance without a respawn. Composition only: the same composer spawn
+ *  used, the same soul the home links to, the home's recorded context/work
+ *  mode; the previous AGENTS.md is retained as evidence; the change is
+ *  recorded in instance.json (instructions sources) and as a typed event.
+ *  Nothing is launched, restarted or signalled — the running process picks the
+ *  new text up on its next read (harness-dependent; the receipt says so). */
+export function recomposeInstanceInstructions(home, { dryRun = false } = {}) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "recompose needs an absolute instance home");
+  const realHome = realPathOrNearest(home);
+  const metaFile = join(realHome, "instance.json");
+  if (!existsSync(metaFile)) throw oatsError("E_SESSION_UNKNOWN", `${realHome} is not an OATS instance home (no instance.json)`);
+  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");
+  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));
+  const agent = findAgent(dirname(agentDir), basename(agentDir)) || { name: meta.agent, kind: meta.kind, _dir: agentDir };
+  if (agent.kind === "capability") throw oatsError("E_UNSUPPORTED_MODE", "capability-defined souls are recomposed by updating their package");
+  const contextDir = meta.repo && existsSync(meta.repo) ? meta.repo : dirname(dirname(agentDir));
+  const composition = composeInstanceAgentsMd(soulDir, contextDir, meta.agent, meta.work || "checkout", meta.kind || "persistent");
+  const target = join(realHome, "AGENTS.md");
+  const before = existsSync(target) ? readFileSync(target, "utf8") : null;
+  const changed = before !== composition.text;
+  const result = { home: realHome, instance: meta.instance, agent: meta.agent, soulDir, contextDir, changed, dryRun,
+    blocks: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
+    previous: null, note: "the running harness re-reads its instructions on its own schedule (typically the next turn or restart); this refresh does not signal or restart anything" };
+  if (dryRun || !changed) return result;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const previous = join(realHome, `.oats-agents-md.${stamp}.previous`);
+  if (before !== null) writeFileSync(previous, before);
+  writeFileSync(target, composition.text);
+  meta.instructions = composition.blocks.map((b) => ({ source: b.source, file: b.file }));
+  meta.recomposedAt = new Date().toISOString();
+  writeFileSync(metaFile, JSON.stringify(meta, null, 2) + "\n");
+  appendEvent(realHome, { kind: "recomposed", data: { previous, blocks: result.blocks.length, soulDir } });
+  result.previous = previous;
+  return result;
+}
+
 export async function attachInstanceSession(home) {
   const s = instanceSessionTarget(home);
   if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
@@ -7445,8 +7598,12 @@ export function harnessProcesses(target, io) {
  *  running. Elapsed time is never taken as exit. */
 export function stopHarness(target, { graceMs = 20000, signal = "SIGTERM", io = {}, kill = process.kill, sleep } = {}) {
   const wait = sleep || ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms));
-  const before = inspectSessionTarget(target, io);
-  if (!before.present || before.state === "shell" || before.state === "stopped") return { requested: [], signal, sentAt: null, observedAt: new Date().toISOString(), exited: true, waitedMs: 0, state: before.state, note: "nothing was running" };
+  // "Already idle" must be a STABLE reading: the shell-vs-harness decision walks
+  // `ps`, which under load can miss a just-forked descendant for one sample.
+  // One momentary "shell" must never be taken as exit with nothing signalled.
+  const idle = (s) => !s.present || s.state === "shell" || s.state === "stopped";
+  let before = inspectSessionTarget(target, io);
+  if (idle(before)) { wait(250); const again = inspectSessionTarget(target, io); if (idle(again)) return { requested: [], signal, sentAt: null, observedAt: new Date().toISOString(), exited: true, waitedMs: 0, state: again.state, stillRunning: [] }; before = again; }
   const procs = harnessProcesses(target, io);
   if (!procs.length) throw oatsError("E_SESSION_UNKNOWN", `the session reads as ${before.state} but no harness process was found under its pane; nothing was signalled`);
   const requested = [];
@@ -7457,12 +7614,14 @@ export function stopHarness(target, { graceMs = 20000, signal = "SIGTERM", io =
   }
   const started = Date.now();
   const alive = (pid) => { try { kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
-  let st = before;
+  let st = before, idleStreak = 0;
   while (Date.now() - started <= graceMs) {
     wait(250);
     try { st = inspectSessionTarget(target, io); } catch { st = { present: true, state: "unknown" }; }
     const gone = requested.every((r) => !alive(r.pid));
-    if (gone && (!st.present || st.state === "shell" || st.state === "stopped")) return { requested, signal, sentAt, observedAt: new Date().toISOString(), exited: true, waitedMs: Date.now() - started, state: st.state };
+    idleStreak = gone && idle(st) ? idleStreak + 1 : 0;
+    // Exit needs two consecutive agreeing samples, not one.
+    if (idleStreak >= 2) return { requested, signal, sentAt, observedAt: new Date().toISOString(), exited: true, waitedMs: Date.now() - started, state: st.state };
   }
   return { requested, signal, sentAt, observedAt: null, exited: false, waitedMs: Date.now() - started, state: st.state, stillRunning: requested.filter((r) => alive(r.pid)).map((r) => r.pid) };
 }
@@ -7897,7 +8056,7 @@ export function startInstanceSession(home, o = {}) {
   const pendingPath = join(realHome, ".oats-start-pending.json");
   const exitedPath = join(realHome, ".oats-start-exited");
   const readMeta = () => { try { return JSON.parse(readFileSync(metaPath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${metaPath}: ${e.message}`); } };
-  const lostTmuxServer = (e) => /no server running on |(?:error connecting to|failed to connect to) .*(?:No such file or directory|Connection refused)/i.test(String(e.stderr ?? e.message ?? ""));
+  const lostTmuxServer = tmuxServerLost;
   const launchFailure = (backend, error) => {
     // execFileSync errors embed argv (including capability environment) in
     // message; backend stderr can echo it too. Neither belongs in the API.
@@ -8058,6 +8217,7 @@ export function startInstanceSession(home, o = {}) {
       // as running; nothing is escalated and nothing is launched.
       stopReceipt = stopHarness(target, { graceMs: o.stopGraceMs ?? 20000, io: o.io, kill: o.io?.kill, sleep: o.io?.sleep });
       writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { runtime: launchPlan?.runtime || runtime, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
+      appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
       if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
       try { state = inspectSessionTarget(target, o.io); } catch (e) { if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
       if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
@@ -8767,11 +8927,58 @@ export function retireInstance(root, name, o = {}) {
   } catch { /* no team scope resolvable — local root only */ }
   for (const r2 of roots) scanRoot(r2);
 
+  // K3b — retention is the default (lifecycle decision §1): the worktree,
+  // branch and any PR outlive the home. The worktree cannot stay under
+  // <home>/work once the home is removed, so it is RE-HOMED with
+  // `git worktree move` to the deployment-level worktrees root and the move is
+  // recorded in the receipt. `discardWorktree` restores removal; branch
+  // deletion uses the VERIFIED current ref of the worktree, never the
+  // spawn-time recorded name. A failed move keeps the home (fail closed).
+  let retention = null;
   if (isWorktree && meta.repo) {
-    shTry(`git -C ${shq(meta.repo)} worktree remove --force ${shq(workPath)}`);
-    shTry(`git -C ${shq(meta.repo)} worktree prune`);
-    if (o.deleteBranch && meta.branch) shTry(`git -C ${shq(meta.repo)} branch -D ${shq(meta.branch)}`);
+    const ref = existsSync(workPath) ? (() => { try { return worktreeRef(workPath); } catch { return { branch: null, oid: null }; } })() : { branch: meta.branch ?? null, oid: null };
+    const verifiedBranch = ref.branch;
+    // A branch cannot be deleted while a worktree has it checked out, so
+    // --delete-branch implies discarding the worktree (which is what every
+    // caller of it meant: clean up everything). Plain retire retains.
+    if (o.discardWorktree || o.deleteBranch || quarantine) {
+      shTry(`git -C ${shq(meta.repo)} worktree remove --force ${shq(workPath)}`);
+      shTry(`git -C ${shq(meta.repo)} worktree prune`);
+      retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
+    } else if (existsSync(workPath)) {
+      const repoName = basename(realPathOrNearest(meta.repo)).replace(/\.git$/, "") || "repo";
+      const leaf = (verifiedBranch ?? `detached-${(ref.oid || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
+      const retainedRoot = join(workspaceOf(root), ".agents", "worktrees", repoName);
+      mkdirSync(retainedRoot, { recursive: true });
+      let dest = join(retainedRoot, leaf);
+      for (let n = 2; existsSync(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
+      try {
+        execFileSync("git", ["-C", meta.repo, "worktree", "move", workPath, dest], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+      } catch (e) {
+        throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be re-homed to ${dest} (${String(e.stderr ?? e.message ?? "").trim()}); the home is kept so nothing is lost — resolve and retry, or pass --discard-worktree to remove the worktree instead`);
+      }
+      retention = { worktree: "retained", movedTo: dest, branch: verifiedBranch, detachedAt: verifiedBranch === null ? ref.oid : null, recordedBranch: meta.branch ?? null };
+    } else retention = { worktree: "absent", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
+    if (o.deleteBranch && verifiedBranch) {
+      // A plan-driven caller passes the branch it CONFIRMED. Hooks may mutate
+      // the tree during retirement, so the branch is re-verified here, at the
+      // moment of deletion; a mismatch deletes nothing and says so.
+      if (o.expectedBranch !== undefined && o.expectedBranch !== verifiedBranch) {
+        retention.branchDeletionSkipped = { expected: o.expectedBranch, actual: verifiedBranch, reason: "the worktree's branch changed between confirmation and deletion; nothing was deleted" };
+      } else {
+        shTry(`git -C ${shq(meta.repo)} branch -D ${shq(verifiedBranch)}`);
+        retention.branchDeleted = verifiedBranch;
+      }
+    } else if (o.deleteBranch && !verifiedBranch && o.expectedBranch !== undefined) {
+      retention.branchDeletionSkipped = { expected: o.expectedBranch, actual: null, reason: "the worktree was detached or absent at deletion time; nothing was deleted" };
+    }
+  }
+  if (retention) {
+    if (retention.worktree === "retained") appendEvent(found.home, { kind: "worktree-retained", data: { movedTo: retention.movedTo, branch: retention.branch, recordedBranch: retention.recordedBranch } }, { workspaceOnly: true });
+    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 });
   // 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.
@@ -8877,7 +9084,7 @@ export function retireInstance(root, name, o = {}) {
   }
 
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
+  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, retention, worktreeRemoved: isWorktree && retention?.worktree !== "retained", branchDeleted: !!(retention?.branchDeleted) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
   if (self) {
     // The caller is the instance: its process lives in the window we are about to
     // kill. Detach the kill so this function can return and the caller can report

package/lib/instance-events.mjs

@@ -0,0 +1,76 @@
+/** K7 — typed lifecycle events per instance, append-only, producer-attributed.
+ *
+ * Every event is a fact a kernel action just made true (spawned, launched,
+ * stopped, restarted, retired…), written by the code that did it, with the
+ * receipt it produced. Nothing here is inferred from transcripts, task files or
+ * prose; "waiting on you" is reported only when a producer says so — today no
+ * producer does, and the view says `null`, not a guess. Retirement's event
+ * outlives the home in the workspace-level log. */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export const EVENTS_API = 1;
+const HOME_LOG = ".oats-events.jsonl";
+const MAX_BYTES = 4 * 1024 * 1024;
+
+export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "recomposed"];
+
+function workspaceLogPath(home) {
+  // <workspace>/.agents/events/<agent>--<instance>.jsonl — deployment-private
+  // state beside installed capabilities and schedules; survives the home's removal.
+  const agentDir = dirname(dirname(home)); // <root>/<agent>/instances/<instance>
+  const workspace = dirname(dirname(agentDir)); // <workspace>/agents/<agent>
+  return join(workspace, ".agents", "events", `${basename(agentDir)}--${basename(home)}.jsonl`);
+}
+
+/** Append one typed event. Never throws into the caller's action: an event is
+ *  evidence, not authority — a failed write is reported in the return value. */
+export function appendEvent(home, event, { workspaceOnly = false } = {}) {
+  if (!EVENT_KINDS.includes(event.kind)) return { ok: false, reason: `unknown event kind ${event.kind}` };
+  const row = { eventsApi: EVENTS_API, at: new Date().toISOString(), instance: basename(home), home, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
+  const line = JSON.stringify(row) + "\n";
+  const results = [];
+  // Retirement fingerprints the home against its baseline and preserves any
+  // changed bytes as "unknown work": events written DURING retirement go only
+  // to the workspace log, never into the home being inspected.
+  for (const path of [...(workspaceOnly ? [] : [join(home, HOME_LOG)]), workspaceLogPath(home)]) {
+    try {
+      if (path.startsWith(home) && !existsSync(home)) { results.push({ path, ok: false, reason: "home absent" }); continue; }
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, line);
+      results.push({ path, ok: true });
+    } catch (e) { results.push({ path, ok: false, reason: e.message }); }
+  }
+  return { ok: results.some((r) => r.ok), row, results };
+}
+
+function readLog(path) {
+  if (!existsSync(path)) return { rows: [], truncated: false, bytes: 0 };
+  const size = statSync(path).size;
+  const text = readFileSync(path, "utf8");
+  const rows = [];
+  for (const line of text.split("\n")) { if (!line.trim()) continue; try { const r = JSON.parse(line); if (r && r.eventsApi === EVENTS_API && typeof r.kind === "string") rows.push(r); } catch { /* a torn line is skipped, counted */ rows.push({ eventsApi: EVENTS_API, kind: "unreadable", at: null, producer: "kernel", data: { reason: "torn or invalid line" } }); } }
+  return { rows, truncated: size > MAX_BYTES, bytes: size };
+}
+
+/** Events for one instance, newest last, from both logs (deduplicated by
+ *  at+kind), with a bounded window. `waitingOnYou` is a producer claim or null. */
+export function readEvents(home, { limit = 200, since = null } = {}) {
+  const a = readLog(join(home, HOME_LOG)), b = readLog(workspaceLogPath(home));
+  const seen = new Set(); const rows = [];
+  for (const r of [...a.rows, ...b.rows]) { const k = `${r.at}|${r.kind}|${JSON.stringify(r.data ?? null)}`; if (seen.has(k)) continue; seen.add(k); rows.push(r); }
+  rows.sort((x, y) => String(x.at ?? "").localeCompare(String(y.at ?? "")));
+  const filtered = since ? rows.filter((r) => r.at && r.at > since) : rows;
+  const window = filtered.slice(-limit);
+  const last = window.at(-1) ?? null;
+  const waiting = window.filter((r) => r.data && r.data.waitingOnYou === true).at(-1) ?? null;
+  return {
+    eventsApi: EVENTS_API, instance: basename(home), home, count: filtered.length, returned: window.length, truncated: filtered.length > window.length || a.truncated || b.truncated,
+    events: window, lastEvent: last ? { kind: last.kind, at: last.at, producer: last.producer } : null,
+    waitingOnYou: waiting ? { since: waiting.at, producer: waiting.producer, reason: waiting.data.reason ?? null } : null,
+    notes: [
+      "events are producer-attributed facts written by the kernel action that made them true; nothing is inferred from transcripts or task files",
+      "waitingOnYou is null unless a producer reported it — null means unknown, not 'not waiting'",
+    ],
+  };
+}