@awebai/oats 0.24.7 → 0.24.9

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/process-group.mjs

@@ -0,0 +1,12 @@
+/** Kill a detached child's whole process group (e.g. git + its remote helper /
+ *  ssh, or a runtime probe + what it forked). ONLY for a child that was actually
+ *  spawned: a failed spawn (ENOENT) reports `pid: 0`, and `process.kill(-0)` /
+ *  `process.kill(0)` address the CALLER's own process group — the operator's
+ *  shell, tmux session or Desktop backend. Returns whether anything was signalled. */
+export function killGroup(child, signal = "SIGKILL") {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(-pid, signal); } catch { /* already gone */ }
+  try { process.kill(pid, signal); } catch { /* already gone */ }
+  return true;
+}

package/lib/readiness.mjs

@@ -0,0 +1,225 @@
+/** 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 { spawnSync } from "node:child_process";
+import { killGroup } from "./process-group.mjs";
+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 const SIGNATURE_FAILURES = Object.freeze(["transport-not-allowed", "fetch-failed", "fetch-timeout", "budget-exhausted", "verifier-failed", "verifier-timeout", "cannot-check", "no-source"]);
+const ALLOWED_TRANSPORTS = /^(https:\/\/|ssh:\/\/|git@[^/:]+:)/;
+/** 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.
+ *  Bounded custody: one total budget per call (`budgetMs`, default 60s) shared
+ *  by fetch and verify; each Git child runs in its own process group and is
+ *  killed with the group on timeout; the scratch repository is removed on every
+ *  exit including signals; Git reads NO global/system config and cannot prompt;
+ *  only https/ssh transports are fetched. Failures carry a closed `failure`
+ *  code — never stderr. */
+/** One verification budget for a whole readiness read: every signatureOf call
+ *  in that read draws from it, so a target with N capabilities is bounded by the
+ *  TOTAL (default 120 s), not N × per-call. */
+export function verificationBudget(totalMs = 120000) {
+  const started = Date.now();
+  return { totalMs, remaining: () => totalMs - (Date.now() - started) };
+}
+const scratchDirs = new Set();
+let signalCleanupInstalled = false;
+function installSignalCleanup() {
+  if (signalCleanupInstalled) return; signalCleanupInstalled = true;
+  const sweep = () => { for (const d of scratchDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } } scratchDirs.clear(); };
+  process.once("exit", sweep);
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(sig, () => { sweep(); process.exit(128 + (sig === "SIGINT" ? 2 : sig === "SIGTERM" ? 15 : 1)); });
+}
+export function signatureOf({ url, commit }, { verify = false, budgetMs = 60000, budget = null } = {}) {
+  if (!url || !commit || commit === "local") return { status: "not-applicable", signer: null, reason: commit === "local" ? "path-installed capability has no source commit" : "no source recorded", failure: null };
+  if (!verify) return { status: "unknown", signer: null, reason: "signature verification needs a network fetch; pass --verify-signatures", failure: null };
+  if (!ALLOWED_TRANSPORTS.test(url)) return { status: "unknown", signer: null, reason: "source transport is not https or ssh; not fetched", failure: { code: "transport-not-allowed" } };
+  const shared = budget ?? verificationBudget(budgetMs);
+  if (shared.remaining() <= 0) return { status: "unknown", signer: null, reason: "the verification budget was exhausted", failure: { code: "budget-exhausted" } };
+  installSignalCleanup();
+  const dir = mkdtempSync(join(tmpdir(), "oats-sig-")); scratchDirs.add(dir);
+  const cleanup = () => { scratchDirs.delete(dir); try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
+  const env = { PATH: process.env.PATH ?? "", HOME: dir, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_ASKPASS: "/bin/false", SSH_ASKPASS: "/bin/false", GIT_SSH_COMMAND: "ssh -o BatchMode=yes", LC_ALL: "C" };
+  const git = (args, stage) => {
+    const left = shared.remaining();
+    if (left <= 0) throw Object.assign(new Error("budget"), { failure: "budget-exhausted" });
+    const child = spawnSync("git", ["-C", dir, "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always", ...args],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: left, killSignal: "SIGKILL", detached: true, env, shell: false });
+    if (child.error?.code === "ETIMEDOUT" || child.signal === "SIGKILL") { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-timeout` }); }
+    if (child.error || child.status !== 0) { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-failed` }); }
+    return child.stdout;
+  };
+  try {
+    git(["init", "-q"], "verifier");
+    git(["fetch", "-q", "--depth", "1", url, commit], "fetch");
+    // %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], "verifier").trim();
+    const [code, signerName, keyId, fingerprint] = out.split("\0");
+    if (code === "N") return { status: "unsigned", signer: null, reason: "commit carries no signature", failure: null };
+    if (code === "G") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: null, failure: 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", failure: null };
+    if (code === "E") return { status: "unknown", signer: null, reason: "signature present but cannot be checked (missing public key)", failure: { code: "cannot-check" } };
+    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] || "verifier reported an unrecognised state", failure: null };
+  } catch (e) {
+    const code = SIGNATURE_FAILURES.includes(e.failure) ? e.failure : "verifier-failed";
+    const reasons = { "fetch-failed": "the source could not be fetched", "fetch-timeout": "the fetch exceeded the verification budget", "budget-exhausted": "the verification budget was exhausted", "verifier-failed": "the local verifier failed", "verifier-timeout": "the local verifier exceeded the verification budget" };
+    return { status: "unknown", signer: null, reason: reasons[code], failure: { code } };
+  } finally { cleanup(); }
+}
+
+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, selector = null, verificationBudgetMs = 120000 } = {}) {
+  const caps = inspect.capabilities || [];
+  const budget = verifySignatures ? verificationBudget(verificationBudgetMs) : null;
+  const soulEntry = soul ? (inspect.souls || []).find((s) => s.name === soul) : null;
+  const declaredRequires = soulEntry?.declarations?.requires?.capabilities ? Object.keys(soulEntry.declarations.requires.capabilities) : null;
+  const required = new Set(declaredRequires ?? caps.filter((c) => c.activation?.enabled).map((c) => c.id));
+  const declaredForSoul = (c) => !!c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`));
+  const relevant = soul ? caps.filter((c) => required.has(c.id) || declaredForSoul(c)) : caps;
+  // Typed linkage for consumers (frame-level per-capability rows): WHICH
+  // capability, at which config level/scope, and WHY it is in this quartet.
+  const capabilityOf = (c) => ({ id: c.id, level: c.activation?.level ?? null, scope: c.activation?.target ?? null });
+  const originOf = (c) => declaredRequires?.includes(c.id) ? { kind: "requires", target: `soul:${soul}` }
+    : soul && declaredForSoul(c) ? { kind: "declares", target: `soul:${soul}` }
+    : c.activation?.enabled ? { kind: "default", target: c.activation?.target ?? "global" } : { kind: "inventory", target: null };
+  const typed = (c) => ({ capability: capabilityOf(c), origin: originOf(c) });
+
+  // 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}`, ...typed(c) });
+  });
+  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}>`,
+    capability: { id, level: null, scope: null }, origin: { kind: "requires", target: `soul:${soul}` } }));
+
+  // trusted — executable approval of the exact artifact; signature separately
+  const trusted = relevant.map((c) => {
+    // The inspect row states whether the manifest has anything trust approves
+    // (commands/hooks/launch env). No surface → trust is not-applicable, however
+    // the lock records it. Older rows without the flag fall back to the old heuristic.
+    const executable = typeof c.health?.executableSurface === "boolean" ? c.health.executableSurface
+      : !!(c.operations?.length || c.health?.code === "untrusted-surface");
+    const approved = c.health?.trusted === true;
+    const sig = signatureOf(sourceOfCapability(c, catalog), { verify: verifySignatures, budget });
+    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, ...typed(c) });
+  });
+
+  // configured — EFFECTIVE activation for the subject (a declaration at the
+  // soul is not activation: `enabled` is the resolved verdict for this subject,
+  // and a declared-but-disabled binding is a fail that says so) + runtime
+  // package requirements + layer readiness problems
+  const configured = [];
+  for (const c of relevant) {
+    const active = c.activation?.enabled === true;
+    const declaredOnly = !active && soul && declaredForSoul(c);
+    if (required.has(c.id)) configured.push(item(`${c.id} activation`, active ? "pass" : "fail", { producer: "oats-config.yaml",
+      reason: active ? null : declaredOnly ? `declared for soul ${soul} but disabled${c.activation?.reason ? ` (${c.activation.reason})` : ""}` : `not active for ${soul ? `soul ${soul}` : "this scope"}`,
+      evidence: { target: c.activation?.target ?? null, level: c.activation?.level ?? null, source: c.activation?.source ?? null }, remedy: active ? null : `oats use ${c.id}${soul ? ` --soul ${soul}` : ""}`, ...typed(c) }));
+    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, ...typed(c) }));
+  }
+  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.unreadable) enrolled.push(item("workspace membership", "unknown", { producer: "oats.yaml", reason: "workspace member document is unreadable; membership cannot be stated", evidence: { file: member.file ?? null }, remedy: "repair oats.yaml (valid YAML) and re-run" }));
+  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" : "reciprocal admission not observed: this CLI reads the backlink but does not yet fetch the workspace's members (declared, not verified)",
+    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));
+  // Per-capability grouping of the same items (no second observation): each
+  // capability's four verdicts, ready only if all its REQUIRED items pass.
+  const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
+    const of = (name) => checks[name].items.filter((i) => i.capability?.id === id);
+    const statuses = Object.keys(checks).flatMap((name) => of(name).filter((i) => i.required).map((i) => i.status));
+    const any = Object.keys(checks).flatMap((name) => of(name)).find(Boolean);
+    return { capability: any?.capability ?? { id, level: null, scope: null }, origin: any?.origin ?? null, required: statuses.length > 0,
+      checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
+      ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
+  });
+  // Items that belong to no capability (workspace membership, soul declarations)
+  // are SUBJECT-level: a capability's own verdict never overrides them, and a
+  // row must not read "ready" while the subject is blocked by one of them.
+  const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
+  for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
+  return { readinessApi: READINESS_API, subject: { ...(soul ? { kind: "soul", name: soul } : { kind: "scope", context: inspect.scope?.context ?? null }), ...(selector ? { selector } : {}) }, 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, byCapability, subjectBlockers },
+    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"));
+    // The lenient parser never throws: a `workspace:` that is present but not a
+    // mapping is a document we cannot read a membership from — unreadable, not absent.
+    if (doc.workspace !== undefined && (doc.workspace === null || typeof doc.workspace !== "object")) return { workspace: null, admitted: null, unreadable: true, file };
+    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, file }; }
+}
+
+/** 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);

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.2",
+      "ref": "v2.1.3",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

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