@awebai/oats 0.24.6 → 0.24.8

package/lib/instance-git.mjs

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

package/lib/instance-lifecycle.mjs

@@ -0,0 +1,181 @@
+/** K3 — lifecycle plans for the Desktop's Stop and Remove confirmations.
+ *
+ * A plan is a read-only statement of what an action WOULD touch, with the
+ * facts a human needs to decide (session state, children, dirty work) and a
+ * `planRevision` hashed from the facts that make the action safe. Apply
+ * takes that revision back: if reality moved, apply refuses with the fresh
+ * plan instead of acting on a world the human did not see. Idempotency keys
+ * make a retried apply return the first receipt rather than act twice.
+ * Unknown is reported as unknown — never as "clean" or "no children". */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, retirePendingMarkerPath, stopInstanceSession, teamAgentRoots, resolveOatsConfig } from "./core.mjs";
+import { observeInstanceGit } from "./instance-git.mjs";
+import { appendEvent } from "./instance-events.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const LIFECYCLE_API = 1;
+const KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const stopPendingPath = (home) => join(home, ".oats-stop-pending.json");
+const stopReceiptPath = (home, key) => join(home, `.oats-stop-receipt.${key}.json`);
+
+function readJson(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } }
+function planRevision(facts) { return createHash("sha256").update(JSON.stringify(facts)).digest("hex").slice(0, 24); }
+
+/** Resolve `<name>` under the scope's agents roots to exactly one home. */
+export function resolveInstance(ctx, root, name, { home } = {}) {
+  let r; try { r = resolveOatsConfig(ctx); } catch { r = {}; }
+  const roots = [...new Set([root, ...(r.team ? teamAgentRoots(r.team.scope) : [])])];
+  const candidates = [];
+  for (const rt of roots) for (const hit of findInstanceHomes(rt, name)) candidates.push({ root: rt, agent: hit.agent?.name ?? null, home: hit.home });
+  if (home !== undefined) {
+    const found = candidates.find((c) => c.home === home);
+    if (!found) throw oatsError("E_HOME_MISMATCH", `--home ${home} is not a home of instance ${JSON.stringify(name)} under ${roots.join(", ")}`);
+    return found;
+  }
+  if (!candidates.length) throw oatsError("E_SESSION_UNKNOWN", `no instance ${JSON.stringify(name)} under ${roots.join(", ")}`);
+  if (candidates.length > 1) throw Object.assign(oatsError("E_AMBIGUOUS_INSTANCE", `instance ${JSON.stringify(name)} has ${candidates.length} homes; pass --home <abs>`), { candidates });
+  return candidates[0];
+}
+
+/** Every instance under the roots whose recorded parent chain reaches `name`,
+ *  deepest first (children are acted on before their parent). Recorded
+ *  parentage is the only relation the kernel knows; it is reported as such. */
+export function descendantsOf(root, name) {
+  const rows = [];
+  for (const a of listAgents(root)) for (const i of listInstances(root).filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
+    const home = join(a._dir, "instances", inst.instance);
+    const meta = readJson(join(home, "instance.json"));
+    if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
+  }
+  // Recorded parentage is a BARE name, and names are unique only per agent
+  // directory. An edge whose parent name resolves to several homes under this
+  // root is ambiguous: it is reported, never acted on (nothing is inferred).
+  const homesByName = new Map();
+  for (const r of rows) { if (!homesByName.has(r.instance)) homesByName.set(r.instance, []); homesByName.get(r.instance).push(r); }
+  const byParent = new Map();
+  const ambiguous = [];
+  for (const r of rows) {
+    if (r.parent && (homesByName.get(r.parent) || []).length > 1) { ambiguous.push({ ...r, reason: `parent name ${JSON.stringify(r.parent)} resolves to ${homesByName.get(r.parent).length} homes; edge not followed` }); continue; }
+    if (!byParent.has(r.parent)) byParent.set(r.parent, []); byParent.get(r.parent).push(r);
+  }
+  const out = [];
+  const walk = (parent, depth) => { for (const c of byParent.get(parent) || []) { if (c.instance === parent) continue; walk(c.instance, depth + 1); out.push({ ...c, depth }); } };
+  walk(name, 1);
+  out.ambiguous = ambiguous.filter((r) => r.parent === name); // edges pointing at THIS name that could not be followed
+  return out; // deepest first
+}
+
+/** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
+ *  idle; "unknown" means a NON-shell process is running whose identity tmux
+ *  cannot name (the ordinary case for a launched harness). "Could not be
+ *  established" is a different thing and is `present: null` with a reason. */
+function sessionFacts(home) {
+  try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
+  catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: e.code || "E_SESSION_UNAVAILABLE" }; }
+}
+const running = (s) => s.established && s.present === true && !["shell", "stopped", "not-launched"].includes(s.state);
+function workFacts(home) {
+  if (!existsSync(join(home, "work"))) return { observed: false, reason: "no-worktree" };
+  try {
+    const g = observeInstanceGit(home);
+    return { observed: true, revision: g.observation.revision, branch: g.observation.branch, detached: g.observation.detached, drift: g.recorded.drift,
+      changed: g.summary.changed + g.summary.renamed + g.summary.copied + g.summary.unmerged, untracked: g.summary.untracked,
+      upstream: g.upstream, base: { ref: g.base.ref, ahead: g.base.ahead, behind: g.base.behind }, remote: g.remote ? { host: g.remote.host, path: g.remote.path } : null };
+  } catch (e) { return { observed: false, reason: e.code || "E_GIT_FAILED" }; }
+}
+function targetFacts(row) {
+  const meta = readJson(join(row.home, "instance.json")) || {};
+  return { instance: row.instance, agent: row.agent, home: row.home, depth: row.depth ?? 0, workMode: meta.work ?? null, launched: meta.launched === true,
+    session: sessionFacts(row.home), work: workFacts(row.home),
+    retiring: existsSync(retirePendingMarkerPath(row.home)), stopPending: existsSync(stopPendingPath(row.home)) };
+}
+
+/** Facts for Stop: the instance, its recorded descendants (deepest first),
+ *  each with session state and dirty-work counts. `midTask` is REPORTED
+ *  activity: dirty work or a running session; unknown says unknown. */
+export function planStop(ctx, root, name, { home, recursive = true } = {}) {
+  const me = resolveInstance(ctx, root, name, { home });
+  const kids = recursive ? descendantsOf(me.root, name) : [];
+  const targets = [...kids.map(targetFacts), targetFacts({ ...me, instance: name, depth: 0 })];
+  // Reported activity: a running session or dirty work is mid-task; when the
+  // session could not be established and work is not observed, say unknown.
+  for (const t of targets) t.midTask = running(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || !t.work.observed) ? "unknown" : false;
+  const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
+  const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
+  const plan = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: me.home, recursive, at: new Date().toISOString(),
+    targets, skipped: recursive ? [] : descendantsOf(me.root, name).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: "recursive=false" })),
+    ambiguous: ambiguousEdges,
+    planRevision: planRevision(safety),
+    notes: [...(ambiguousEdges.length ? [`${ambiguousEdges.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
+      ...(targets.some((t) => t.retiring) ? ["a target is being retired; apply will refuse it"] : []), ...(targets.some((t) => !t.session.established) ? ["a session state could not be established; it is reported unestablished, not idle"] : [])] };
+  return plan;
+}
+
+/** Apply a Stop plan: revalidate the revision, take the stop-pending marker
+ *  per target (refusing retiring targets), stop deepest-first, record a
+ *  receipt keyed by idempotency key. A retried apply with the same key
+ *  returns the recorded receipt without acting again. */
+export function applyStop(ctx, root, name, { home, recursive = true, planRevision: expected, idempotencyKey, graceMs } = {}) {
+  if (typeof expected !== "string" || !expected) throw oatsError("E_BAD_ARGS", "apply needs --plan-revision from a prior `--plan`");
+  if (typeof idempotencyKey !== "string" || !KEY.test(idempotencyKey)) throw oatsError("E_BAD_ARGS", "apply needs --idempotency-key (1-128 chars of [A-Za-z0-9._:-])");
+  const plan = planStop(ctx, root, name, { home, recursive });
+  const prior = readJson(stopReceiptPath(plan.home, idempotencyKey));
+  if (prior && prior.idempotencyKey === idempotencyKey) return { ...prior, replayed: true };
+  if (plan.planRevision !== expected) throw Object.assign(oatsError("E_PLAN_STALE", `the stop plan changed since it was shown (${expected} → ${plan.planRevision}); review the fresh plan`), { plan });
+  const retiring = plan.targets.filter((t) => t.retiring);
+  if (retiring.length) throw Object.assign(oatsError("E_INSTANCE_RETIRING", `${retiring.map((t) => t.instance).join(", ")} ${retiring.length === 1 ? "is" : "are"} being retired; nothing was stopped`), { plan });
+  const pending = plan.targets.filter((t) => t.stopPending);
+  if (pending.length) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `${pending.map((t) => t.instance).join(", ")} already ${pending.length === 1 ? "has" : "have"} a stop in progress`), { plan });
+  const results = [];
+  const marker = { action: "stop", idempotencyKey, planRevision: expected, at: new Date().toISOString() };
+  for (const t of plan.targets) { try { writeFileSyncAtomic(stopPendingPath(t.home), marker); } catch { /* best effort marker; the lock is advisory across our own apply paths */ } }
+  try {
+    for (const t of plan.targets) {
+      try {
+        const r = stopInstanceSession(t.home, { graceMs });
+        results.push({ instance: t.instance, home: t.home, ok: true, stopped: r.stopped, alreadyIdle: r.alreadyIdle, state: r.state });
+      } catch (e) {
+        results.push({ instance: t.instance, home: t.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null });
+      }
+    }
+  } finally { for (const t of plan.targets) rmSync(stopPendingPath(t.home), { force: true }); }
+  const receipt = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: plan.home, idempotencyKey, planRevision: expected, at: new Date().toISOString(),
+    ok: results.every((r) => r.ok), results, retained: ["home", "work", "transcript", "launch"], replayed: false };
+  // One receipt file per key: a retry of ANY earlier key replays its own
+  // receipt for as long as the home exists (the replay horizon).
+  try { writeFileSyncAtomic(stopReceiptPath(plan.home, idempotencyKey), receipt); } catch { /* receipt is evidence, not authority */ }
+  return receipt;
+}
+
+function writeFileSyncAtomic(path, value) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
+}
+
+/** Facts for Remove (retire): what retirement would touch, with the design's
+ *  defaults (retain worktree and branch; never touch a PR). `oats retire`
+ *  itself applies them: plain retire re-homes the worktree; --discard-worktree
+ *  / --delete-branch are the dialog's opt-ins. */
+export function planRetire(ctx, root, name, { home } = {}) {
+  const me = resolveInstance(ctx, root, name, { home });
+  const kids = descendantsOf(me.root, name);
+  const target = targetFacts({ ...me, instance: name, depth: 0 });
+  const meta = readJson(join(me.home, "instance.json")) || {};
+  const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch ?? null,
+    children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
+    ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
+    pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
+  const defaults = { retainWorktree: meta.work === "worktree", deleteBranch: false, stopChildren: true, retainChildren: true };
+  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home)];
+  appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
+  return { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
+    notes: [
+      ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch}, not the recorded ${facts.recordedBranch}; branch actions use the worktree's branch`] : []),
+      ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
+      ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
+      ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
+      "pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
+    ] };
+}

package/lib/portable-soul.mjs

@@ -9,7 +9,7 @@ export { FUNDAMENTAL_SLOTS } from "./portable-policy.mjs";
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const ALIAS = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const ROOT_FIELDS = ["schemaVersion", "name", "description", "requires", "defaults", "knowledge", "teams", "resources", "work", "runtime", "model", "yolo", "launch-config", "backend"];
+const ROOT_FIELDS = ["schemaVersion", "name", "description", "requires", "defaults", "knowledge", "teams", "resources", "work", "runtime", "model", "yolo", "launch-config", "backend", "children"];
 
 export function parsePortableSoul(input, { origin = null, localBase, allowLocalPaths = false, limits } = {}) {
   const parsed = parseConfigData(input, { origin, limits });
@@ -34,5 +34,9 @@ export function parsePortableSoul(input, { origin = null, localBase, allowLocalP
   if (Object.hasOwn(value, "launch-config")) stringAt(value["launch-config"], "/launch-config", { pattern: LAUNCH_CONFIG_NAME });
   if (Object.hasOwn(value, "backend") && !["tmux", "herdr"].includes(value.backend)) invalidShape("/backend", "unsupported session backend");
   if (Object.hasOwn(value, "yolo") && typeof value.yolo !== "boolean") invalidShape("/yolo", "expected boolean");
+  if (Object.hasOwn(value, "children")) {
+    const children = objectAt(value.children, ["spawn"], [], "/children");
+    if (Object.hasOwn(children, "spawn") && typeof children.spawn !== "boolean") invalidShape("/children/spawn", "expected boolean");
+  }
   return { declaration: value, sources, origins: parsed.origins, integrity: parsed.integrity };
 }

package/lib/readiness.mjs

@@ -0,0 +1,141 @@
+/** K5 — readiness quartet, signature status and enforced policy, as DATA.
+ *
+ * `installed | trusted | configured | enrolled`, each `pass | fail | unknown |
+ * not-applicable` with items a human can act on: subject, whether it is
+ * required, the reason, the producer of the fact, evidence, remedy. Every fact
+ * is derived from what inspect already reports (capability inventory, health,
+ * executable approval, activation, runtime-package requirements, soul
+ * declarations) — never a second opinion. Unknown is unknown; "Ready" is the
+ * consumer's word and only when every required check passes. */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseYamlNested } from "./core.mjs";
+
+export const READINESS_API = 1;
+
+function roll(items, { required = (i) => i.required !== false } = {}) {
+  const req = items.filter(required);
+  if (!items.length) return "not-applicable";
+  if (req.some((i) => i.status === "fail")) return "fail";
+  if (req.some((i) => i.status === "unknown")) return "unknown";
+  if (req.every((i) => i.status === "pass" || i.status === "not-applicable")) return req.length ? "pass" : "not-applicable";
+  return "unknown";
+}
+const item = (subject, status, { required = true, reason = null, producer = "kernel", evidence = null, remedy = null, ...rest } = {}) =>
+  ({ subject, status, required, reason, producer, evidence, remedy, ...rest });
+
+/** Verified Git signature of a source commit, named signer or nothing.
+ *  Requires network (fetch) — only when the caller asks (`verify: true`);
+ *  otherwise `unknown` with the reason. Never a URL, owner or hash as signer. */
+export function signatureOf({ url, commit }, { verify = false, timeoutMs = 30000 } = {}) {
+  if (!url || !commit || commit === "local") return { status: "not-applicable", signer: null, reason: commit === "local" ? "path-installed capability has no source commit" : "no source recorded" };
+  if (!verify) return { status: "unknown", signer: null, reason: "signature verification needs a network fetch; pass --verify-signatures" };
+  const dir = mkdtempSync(join(tmpdir(), "oats-sig-"));
+  const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", LC_ALL: "C" };
+  const git = (args) => execFileSync("git", ["-C", dir, "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs, env, shell: false });
+  try {
+    git(["init", "-q"]);
+    try { git(["fetch", "-q", "--depth", "1", url, commit]); }
+    catch (e) { return { status: "unknown", signer: null, reason: `fetch failed: ${String(e.stderr ?? e.message ?? "").trim().slice(0, 200) || "unknown"}` }; }
+    // %G? : G good, B bad, U good-untrusted, X expired, Y expired key, R revoked, E cannot check, N none
+    const out = git(["log", "-1", "--format=%G?%x00%GS%x00%GK%x00%GF", commit]).trim();
+    const [code, signerName, keyId, fingerprint] = out.split("\0");
+    if (code === "N") return { status: "unsigned", signer: null, reason: "commit carries no signature" };
+    if (code === "G") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: null };
+    if (code === "U") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: "good signature from a key not marked trusted in the local keyring", trust: "untrusted-key" };
+    if (code === "E") return { status: "unknown", signer: null, reason: "signature present but cannot be checked (missing public key)" };
+    return { status: "invalid", signer: null, reason: { B: "bad signature", X: "good signature that has expired", Y: "good signature made by an expired key", R: "good signature made by a revoked key" }[code] || `git reported ${code || "nothing"}` };
+  } catch (e) { return { status: "unknown", signer: null, reason: String(e.stderr ?? e.message ?? "").trim().slice(0, 200) || "verification failed" }; }
+  finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+function sourceOfCapability(cap, catalog) {
+  // cap.source is e.g. "catalog:oats.framework" or "git:https://…@ref#path"; the
+  // installed record's package commit is what we would verify.
+  const src = String(cap.source || "");
+  if (src.startsWith("git:")) { const m = /^git:([^@#]+)(?:@([^#]+))?/.exec(src); return { url: m?.[1] ?? null, commit: cap.commit ?? m?.[2] ?? null }; }
+  if (src.startsWith("catalog:") && catalog) { const entry = catalog.packages?.[src.slice(8)]; return { url: entry?.url ?? null, commit: cap.commit ?? null }; }
+  return { url: null, commit: cap.commit ?? null };
+}
+
+/** The quartet for a scope or one soul, from an inspect result. */
+export function readinessOf(inspect, { soul = null, verifySignatures = false, catalog = null, deploymentDir = null, memberDocument = null } = {}) {
+  const caps = inspect.capabilities || [];
+  const soulEntry = soul ? (inspect.souls || []).find((s) => s.name === soul) : null;
+  const required = new Set(soulEntry?.declarations?.requires?.capabilities ? Object.keys(soulEntry.declarations.requires.capabilities) : caps.filter((c) => c.activation?.enabled).map((c) => c.id));
+  const relevant = soul ? caps.filter((c) => required.has(c.id) || c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`))) : caps;
+
+  // installed — the artifact's bytes are present and locked with matching integrity
+  const installed = relevant.map((c) => {
+    const ok = c.health?.installed === true && (c.health.integrity == null || c.health.installedIntegrity == null || c.health.integrity === c.health.installedIntegrity);
+    return item(c.id, ok ? "pass" : c.health?.installed === false ? "fail" : "unknown", { required: required.has(c.id), producer: "oats list",
+      reason: ok ? null : c.health?.installed === false ? "not acquired" : c.health?.code || "integrity drift", evidence: { version: c.version ?? null, integrity: c.health?.integrity ?? null, origin: c.origin ?? null },
+      remedy: ok ? null : `oats install ${c.package || c.id}` });
+  });
+  for (const id of required) if (!caps.some((c) => c.id === id)) installed.push(item(id, "fail", { producer: "soul declaration", reason: "declared by the soul but not in the inventory", remedy: `oats install <package providing ${id}>` }));
+
+  // trusted — executable approval of the exact artifact; signature separately
+  const trusted = relevant.map((c) => {
+    const executable = !!(c.operations?.length || c.health?.code === "untrusted-surface" || c.health?.trusted !== undefined);
+    const approved = c.health?.trusted === true;
+    const sig = signatureOf(sourceOfCapability(c, catalog), { verify: verifySignatures });
+    return item(c.id, !executable ? "not-applicable" : approved ? "pass" : c.health?.trusted === false ? "fail" : "unknown", { required: required.has(c.id), producer: "artifact approval",
+      reason: !executable ? "no executable surface" : approved ? null : "executable surface not approved", evidence: { integrity: c.health?.integrity ?? null }, remedy: approved || !executable ? null : `oats trust ${c.id}`,
+      signature: sig });
+  });
+
+  // configured — activation for the subject + runtime package requirements + layer readiness problems
+  const configured = [];
+  for (const c of relevant) {
+    const active = soul ? (c.activation?.enabled === true || c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`))) : c.activation?.enabled === true;
+    if (required.has(c.id)) configured.push(item(`${c.id} activation`, active ? "pass" : "fail", { producer: "oats-config.yaml", reason: active ? null : `not active for ${soul ? `soul ${soul}` : "this scope"}`, evidence: { target: c.activation?.target ?? null, level: c.activation?.level ?? null }, remedy: active ? null : `oats use ${c.id}${soul ? ` --soul ${soul}` : ""}` }));
+    for (const miss of c.missingRequires || []) configured.push(item(`${c.id} requires ${miss.command}`, "fail", { producer: "capability manifest", reason: miss.why || "required command not on PATH", remedy: miss.install || null }));
+  }
+  for (const p of inspect.problems || []) if (/runtime package|DISABLED|extension/i.test(p.message || "")) configured.push(item(p.capability || p.code, "fail", { producer: "runtime settings", reason: p.message, remedy: null }));
+  if (soulEntry && soulEntry.readiness?.status === "undeclared") configured.push(item(`${soul} declarations`, "not-applicable", { required: false, producer: "soul.yaml", reason: "no requirements declared" }));
+
+  // enrolled — workspace member admission (decision §3): not-applicable for
+  // standalone; pass/fail when this repository declares a workspace.
+  const enrolled = [];
+  const member = memberDocument ?? readMemberDocument(deploymentDir);
+  if (!member) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "standalone deployment: no workspace declared in oats.yaml" }));
+  else if (!member.workspace?.source) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "oats.yaml declares exports but no workspace backlink" }));
+  else enrolled.push(item(`member of ${member.workspace.source}`, member.admitted === true ? "pass" : member.admitted === false ? "fail" : "unknown", { producer: "workspace discovery",
+    reason: member.admitted === true ? null : member.admitted === false ? "this repository is not admitted in the workspace's members" : "admission not verified (needs the workspace observation)",
+    evidence: { workspace: member.workspace.source, revision: member.workspace.revision ?? null }, remedy: member.admitted === true ? null : "ask the workspace maintainer to admit this repository (oats-workspace.yaml members) — enrolment is admission, not login" }));
+
+  const checks = { installed: { status: roll(installed), items: installed }, trusted: { status: roll(trusted), items: trusted }, configured: { status: roll(configured), items: configured }, enrolled: { status: roll(enrolled), items: enrolled } };
+  const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
+  return { readinessApi: READINESS_API, subject: soul ? { kind: "soul", name: soul } : { kind: "scope", context: inspect.scope?.context ?? null }, at: new Date().toISOString(),
+    checks, summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
+      pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length },
+    notes: [
+      ...(verifySignatures ? [] : ["signatures are unknown until --verify-signatures (network fetch)"]),
+      "ready means every REQUIRED check passes; it is never inferred from an empty set",
+      "enrolment is workspace member admission, not native login or team registration",
+    ] };
+}
+
+function readMemberDocument(deploymentDir) {
+  if (!deploymentDir) return null;
+  const file = join(deploymentDir, "oats.yaml");
+  if (!existsSync(file)) return null;
+  try { const doc = parseYamlNested(readFileSync(file, "utf8")); return { workspace: doc.workspace && typeof doc.workspace === "object" ? doc.workspace : null, admitted: null, exports: doc.exports ?? null }; }
+  catch { return { workspace: null, admitted: null, unreadable: true }; }
+}
+
+/** Enforced policy for an instance (from its recorded metadata) or a soul
+ *  (its declaration + default), with origins. Advisory/unknown stays unknown. */
+export function policyOf({ instanceMeta = null, soul = null } = {}) {
+  const child = instanceMeta?.policy?.childSpawns
+    ? { allowed: instanceMeta.policy.childSpawns.allowed === true, enforced: true, origin: instanceMeta.policy.childSpawns.origin ?? { kind: "recorded" } }
+    : instanceMeta ? { allowed: true, enforced: true, origin: { kind: "default", detail: "no recorded policy: children allowed (pre-0.24.8 instance)" } }
+    : soul?.declarations?.children && typeof soul.declarations.children.spawn === "boolean"
+      ? { allowed: soul.declarations.children.spawn, enforced: false, origin: { kind: "soul", detail: "children.spawn in soul.yaml; enforced once an instance records it" } }
+      : { allowed: true, enforced: false, origin: { kind: "default", detail: "no declaration: children allowed" } };
+  const worktree = instanceMeta ? { allowed: instanceMeta.work === "worktree" || instanceMeta.work === "checkout", mode: instanceMeta.work ?? null, enforced: true, origin: { kind: "work-mode", detail: `work: ${instanceMeta.work}` } }
+    : soul ? { allowed: ["worktree", "checkout"].includes(soul.work), mode: soul.work ?? null, enforced: false, origin: { kind: "soul", detail: `work: ${soul.work}` } } : { allowed: null, mode: null, enforced: false, origin: { kind: "unknown" } };
+  return { readinessApi: READINESS_API, policy: { childSpawns: child, worktrees: worktree }, notes: ["a lifecycle-authority claim enforced by the spawn route, not an OS sandbox"] };
+}

package/lib/schedule.mjs

@@ -145,7 +145,25 @@ export function readDefinitions(ws) {
 }
 export function writeDefinitions(ws, doc) { writeJson(definitionsPath(ws), doc); }
 export function readState(ws) { const st = readJson(statePath(ws), { jobs: {} }); if (!st.jobs || typeof st.jobs !== "object") st.jobs = {}; return st; }
-export function writeState(ws, st) { writeJson(statePath(ws), st); }
+/** K8 — bounded run history. Every time a job's lastRun reaches a settled
+ *  outcome (not "active"/"starting"), it is appended once to `recentRuns`
+ *  (newest first, max 50), keyed by scheduledFor+startedAt so re-saves of the
+ *  same run never duplicate it. Recording happens on save: producers keep
+ *  writing lastRun exactly as they do; nothing is inferred. */
+export const RECENT_RUNS_MAX = 50;
+function recordRecentRuns(st) {
+  for (const js of Object.values(st.jobs || {})) {
+    const lr = js.lastRun;
+    if (!lr || typeof lr !== "object" || ["active", "starting"].includes(lr.outcome)) continue;
+    const key = `${lr.scheduledFor ?? ""}|${lr.startedAt ?? ""}|${lr.outcome ?? ""}`;
+    js.recentRuns ||= [];
+    if (js.recentRuns[0]?.key === key) { js.recentRuns[0] = { key, ...lr }; continue; } // same run, later fields
+    if (js.recentRuns.some((r) => r.key === key)) continue;
+    js.recentRuns.unshift({ key, ...lr });
+    if (js.recentRuns.length > RECENT_RUNS_MAX) js.recentRuns.length = RECENT_RUNS_MAX;
+  }
+}
+export function writeState(ws, st) { recordRecentRuns(st); writeJson(statePath(ws), st); }
 
 // ------------------------------------------------------- host registry
 
@@ -712,7 +730,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
       if (run.startedRuntime) js.lastLaunchedAt = now.toISOString();
       if (!existsSync(def.home)) releaseJobLock(ws, id);
       if (run.pending) js.pendingWake = { scheduledFor: minute.toISOString() }; else delete js.pendingWake;
-      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), home: def.home, ...run, outcome: run.action };
+      js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), home: def.home, ...run, outcome: run.action, ...(run.instance ? { instance: run.instance } : {}) };
       record(id, run.action, { ...(run.reason ? { reason: run.reason } : {}), pending: !!run.pending });
       continue;
     }
@@ -877,7 +895,8 @@ export function describe(ws, id, io, { defs, st, now = new Date() } = {}) {
   let nextRun = null; try { nextRun = def.enabled ? nextRunAfter(def, now) : null; } catch { nextRun = null; }
   const lock = jobLockInfo(ws, id);
   const intent = js.attempt || (lock ? (js.lastRun?.execution ? { schemaVersion: SCHEDULE_ATTEMPT_VERSION, execution: js.lastRun.execution } : {}) : undefined);
-  return { ...def, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun || null, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
+  const recentRuns = (js.recentRuns || []).map(({ key, ...r }) => ({ ...r, ...(r.instance && r.home ? { transcript: { instance: r.instance, home: r.home, kind: "session" } } : {}) }));
+  return { ...def, scheduleApi: 2, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun || null, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
 }
 export function listSchedules(ws, io, { now = new Date() } = {}) {
   const defs = readDefinitions(ws), st = readState(ws);