@awebai/oats 0.40.1 → 0.41.0

package/lib/dir-lock.mjs

@@ -10,9 +10,9 @@ function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) {
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
 /** A mkdir lock that is never reclaimed by another process: an existing
- *  lock whose owner is unreadable or dead is refused with the directory to
- *  remove, because the gap between mkdir and owner.json belongs to a live
- *  acquirer and a dead-owner reclaim races every other acquirer. The
+ *  lock whose owner is unreadable or dead is refused after bounded waiting,
+ *  with the directory to remove, because the gap between mkdir and owner.json
+ *  belongs to a live acquirer and a dead-owner reclaim races every other acquirer. The
  *  holder removes its own lock in finally and on SIGINT/SIGTERM. A lock still
  *  held after `retryMs` is refused with `busy(why)`, the caller's own error. */
 export function withDirLock(dir, what, fn, { retryMs = 0, busy } = {}) {
@@ -23,7 +23,10 @@ export function withDirLock(dir, what, fn, { retryMs = 0, busy } = {}) {
     catch (e) {
       if (e.code !== "EEXIST") throw e;
       let owner; try { owner = JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); } catch { owner = undefined; }
-      if (owner?.pid && pidAlive(owner.pid) && Date.now() < deadline) { pause(50); continue; }
+      // Missing/unreadable owners also occur between mkdir and publication,
+      // and while the holder removes its directory. Wait without touching it.
+      const remaining = deadline - Date.now();
+      if (remaining > 0) { pause(Math.min(50, remaining)); continue; }
       throw busy(!owner ? "its owner is not readable yet or the file is missing" : pidAlive(owner.pid) ? `pid ${owner.pid} holds it` : `its owner pid ${owner.pid} is gone`);
     }
   }

package/lib/instance-events.mjs

@@ -26,9 +26,20 @@
  * Producers write claims as `waiting` rows through `setWaiting` (the CLI's
  * `oats instance waiting` and `oats instance attention`): data
  * `{waitingOnYou, reason?, message?}`, appended only on a change. A claim is
- * evidence for display, never authority: nothing in the kernel acts on it. */
-import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+ * evidence for display, never authority: nothing in the kernel acts on it.
+ *
+ * ONE ADDRESS PER HOME (awebai/oats#583). A home has several spellings when its
+ * deployment is reached through a symlink or its agents root is one: status
+ * addresses it lexically, a session carries the real path. Rows are keyed by
+ * the home string, so every exported function here resolves the home it is
+ * given to its REAL path first (`addressOf`): rows record it, readers compare
+ * against it, and both logs are found from any spelling. `admit` stays strict.
+ * That is storage and matching. An ANSWER (readEvents, setWaiting) names the
+ * home the way the caller did: `admit` has proved every returned row is this
+ * one home's, so its `home` is the address that was asked about, and a consumer
+ * that checks "the rows' home is the home I asked for" keeps holding. */
+import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
 export const EVENTS_API = 2;
 const HOME_LOG = ".oats-events.jsonl";
@@ -61,36 +72,104 @@ export function validWaitingMessage(m) {
 // closed set; anything else reads as null, and the claim still counts.
 /** A stored reason outside the closed set (a hand-edited or foreign row) reads as null. */
 const readReason = (r) => (WAITING_REASONS.includes(r) ? r : null);
+/** An event time: a string that parses as a date. The writer refuses anything else. */
+const validTime = (at) => typeof at === "string" && Number.isFinite(Date.parse(at));
 
-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`);
+/** The READ rule for one claim `{since, producer, reason, message}`, the same for a
+ *  row of this machine's log and for a claim another kernel reports (a remote roster
+ *  row): `since` is a valid date and `producer` is `kernel` or a producer id, or there
+ *  is no claim (null); a reason outside the closed set and a message that fails
+ *  validWaitingMessage read as null, and the claim still counts. Anything that is not
+ *  such an object is null. */
+export function readWaitingClaim(claim) {
+  if (!claim || typeof claim !== "object" || Array.isArray(claim)) return null;
+  const { since, producer } = claim;
+  if (!validTime(since)) return null;
+  // A producer the writer would refuse (a hand-edited log) is never shown as one.
+  if (producer !== "kernel" && !(typeof producer === "string" && WAITING_PRODUCER_RE.test(producer))) return null;
+  return { since, producer, reason: readReason(claim.reason), message: validWaitingMessage(claim.message) ? claim.message : null };
 }
 
-/** The incarnation of the home at `home`: its instance.json `createdAt`, or null. */
-export function incarnationOf(home) {
-  try { const m = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); return typeof m?.createdAt === "string" ? m.createdAt : null; } catch { return null; }
+/** realpath of `p`, or, when `p` is gone, the realpath of its nearest existing
+ *  ancestor with the rest re-appended (retirement writes its rows after the home
+ *  is removed). */
+function realOrNearest(p) {
+  try { return realpathSync(p); } catch { /* absent: resolve what exists */ }
+  let d = resolve(p); const tail = [];
+  while (!existsSync(d) && dirname(d) !== d) { tail.unshift(basename(d)); d = dirname(d); }
+  try { return join(realpathSync(d), ...tail); } catch { return resolve(p); }
+}
+function metaOf(home) {
+  try { const m = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); return m && typeof m === "object" ? m : null; } catch { return null; }
+}
+const incarnationIn = (meta) => (typeof meta?.createdAt === "string" ? meta.createdAt : null);
+
+/** <deployment>/.agents/events/<agent>--<instance>.jsonl: deployment-private state
+ *  beside installed capabilities and schedules; survives the home's removal.
+ *
+ *  The DEPLOYMENT decides where it is, not the real home string: under a symlinked
+ *  agents root the real home's ancestors are outside the deployment. The rule:
+ *   1. the deployment the spawn recorded (instance.json `workspace.deployment`), used
+ *      ONLY when it verifies: the real path of its agents/<agent>/instances/<instance>
+ *      is this home, with agent and instance taken from the home's path, never from
+ *      instance.json;
+ *   2. otherwise the fourth ancestor of the home AS THE CALLER SPELLED IT, which is how
+ *      the kernel addresses a home with no record, or one already removed (retirement).
+ *  The result is resolved, so every spelling of the home gives one path.
+ *
+ *  Two limits. A home with no recorded deployment (or already removed) that is named
+ *  by its REAL path under a symlinked agents root still derives a directory outside
+ *  the deployment; no kernel caller does that. And instance.json is home content: a
+ *  record edited to name another directory that links back to this home moves the log
+ *  there. That is the class the home log is already in (a path the agent can write,
+ *  which the kernel appends to under the same uid), so nothing stricter is checked. */
+function workspaceLogPath(given, home, meta) {
+  const instance = basename(home), agent = basename(dirname(dirname(home))); // <root>/<agent>/instances/<instance>
+  const recorded = meta?.workspace?.deployment;
+  const verified = typeof recorded === "string" && isAbsolute(recorded) && realOrNearest(join(recorded, "agents", agent, "instances", instance)) === home;
+  const deployment = verified ? recorded : dirname(dirname(dirname(dirname(resolve(given)))));
+  return join(realOrNearest(deployment), ".agents", "events", `${agent}--${instance}.jsonl`);
 }
 
+/** The one address of the home a caller named, in any spelling: the real home, its
+ *  instance name and incarnation, its two logs, and `asked`, the caller's spelling. */
+function addressOf(given) {
+  const home = realOrNearest(given);
+  const meta = metaOf(home);
+  let workspaceLog;
+  return {
+    home, asked: given, instance: basename(home), incarnation: incarnationIn(meta), homeLog: join(home, HOME_LOG),
+    get workspaceLog() { return (workspaceLog ??= workspaceLogPath(given, home, meta)); },
+  };
+}
+
+/** THE OUTPUT EDGE, and the only one: canonical inside, the caller's spelling outside.
+ *  Whatever this module ANSWERS about an address (an events read, each row in it, a
+ *  waiting answer) passes through here, which names the home as the caller spelled
+ *  it. Rows on disk and every comparison keep the real path. A new answer that
+ *  carries a `home` must go through this too, never write `a.home` out itself. */
+const answered = (a, body) => ({ ...body, home: a.asked });
+
+/** The incarnation of the home at `home`: its instance.json `createdAt`, or null. */
+export function incarnationOf(home) { return incarnationIn(metaOf(home)); }
+
 /** 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, incarnation, at } = {}) {
+export function appendEvent(home, event, options) { return append(addressOf(home), event, options); }
+function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
   if (!EVENT_KINDS.includes(event.kind)) return { ok: false, reason: `unknown event kind ${event.kind}` };
   // `at`: the time the fact became true, when it is recorded later (a start
   // boundary reconciled from its receipt); readers order rows by it.
-  if (at !== undefined && (typeof at !== "string" || !Number.isFinite(Date.parse(at)))) return { ok: false, reason: `invalid event time ${at}` };
-  const row = { eventsApi: EVENTS_API, at: at ?? new Date().toISOString(), instance: basename(home), home, incarnation: incarnation === undefined ? incarnationOf(home) : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
+  if (at !== undefined && !validTime(at)) return { ok: false, reason: `invalid event time ${at}` };
+  const row = { eventsApi: EVENTS_API, at: at ?? new Date().toISOString(), instance: a.instance, home: a.home, incarnation: incarnation === undefined ? a.incarnation : incarnation, 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)]) {
+  for (const path of [...(workspaceOnly ? [] : [a.homeLog]), a.workspaceLog]) {
     try {
-      if (path.startsWith(home) && !existsSync(home)) { results.push({ path, ok: false, reason: "home absent" }); continue; }
+      if (path === a.homeLog && !existsSync(a.home)) { results.push({ path, ok: false, reason: "home absent" }); continue; }
       mkdirSync(dirname(path), { recursive: true });
       appendFileSync(path, line);
       results.push({ path, ok: true });
@@ -174,11 +253,12 @@ function claimsOf(rows, incarnation) {
   for (const r of current.slice(boundary + 1)) {
     if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
     const p = r.producer ?? "kernel";
-    // A producer the writer would refuse (a hand-edited log) is never shown as one.
-    if (p !== "kernel" && !(typeof p === "string" && WAITING_PRODUCER_RE.test(p))) continue;
+    // A row the read rule refuses (a hand-edited log: its producer, its time) says nothing.
+    const claim = readWaitingClaim({ since: r.at, producer: p, reason: r.data.reason, message: r.data.message });
+    if (!claim) continue;
     claims.set(p, r.data.waitingOnYou
-      ? { producer: p, waiting: true, since: r.at, reason: readReason(r.data.reason), message: validWaitingMessage(r.data.message) ? r.data.message : null }
-      : { producer: p, waiting: false, since: r.at, reason: null, message: null });
+      ? { producer: p, waiting: true, since: claim.since, reason: claim.reason, message: claim.message }
+      : { producer: p, waiting: false, since: claim.since, reason: null, message: null });
   }
   return claims;
 }
@@ -186,19 +266,20 @@ const positiveOf = (claims) => [...claims.values()].filter((c) => c.waiting).sor
 const waitingShape = (c) => (c ? { since: c.since, producer: c.producer, reason: c.reason, message: c.message } : null);
 
 /** Events for one instance ADDRESS, newest last, from both logs, with a bounded
- *  window; integrity is reported independently of the selected rows. */
-export function readEvents(home, { limit = 200, since = null } = {}) {
-  const instance = basename(home);
-  const incarnation = incarnationOf(home);
-  const a = readLog(join(home, HOME_LOG), "home"), b = readLog(workspaceLogPath(home), "workspace");
+ *  window; integrity is reported independently of the selected rows. The answer's
+ *  `home`, and each returned row's, is the home as the caller spelled it. */
+export function readEvents(given, { limit = 200, since = null } = {}) {
+  const address = addressOf(given);
+  const { home, instance, incarnation, homeLog, workspaceLog } = address;
+  const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
   const { rows, foreign } = admit(home, [a, b]);
   const claims = claimsOf(rows, incarnation);
   const waitingClaims = [...claims.values()];
   const positive = positiveOf(claims);
   const filtered = since ? rows.filter((r) => r.at > since) : rows;
-  const window = filtered.slice(-limit);
+  const window = filtered.slice(-limit).map((r) => answered(address, r));
   const last = window.at(-1) ?? null;
-  return {
+  return answered(address, {
     eventsApi: EVENTS_API, instance, home, incarnation, count: filtered.length, returned: window.length,
     truncated: filtered.length > window.length || a.source.status === "tail" || b.source.status === "tail",
     integrity: { unreadableRows: a.unreadable + b.unreadable, foreignRows: foreign, sources: [a.source, b.source] },
@@ -212,7 +293,7 @@ export function readEvents(home, { limit = 200, since = null } = {}) {
       "a claim older than the incarnation's latest kernel launched, restarted or stopped row belongs to an ended session and is not counted",
       "integrity counts torn and foreign rows and names each source's status; truncated is true when the window cut rows or a source was read as a tail",
     ],
-  };
+  });
 }
 
 /** The instance's live waiting state, `{since, producer, reason, message}` or
@@ -221,11 +302,11 @@ export function readEvents(home, { limit = 200, since = null } = {}) {
  *  (the workspace log only when the home log is absent): every row a producer
  *  or a session boundary writes goes to both. */
 export function liveWaiting(home) {
-  const incarnation = incarnationOf(home);
-  if (incarnation === null) return null;
-  let log = readLog(join(home, HOME_LOG), "home");
-  if (log.source.status === "absent") log = readLog(workspaceLogPath(home), "workspace");
-  return waitingShape(positiveOf(claimsOf(admit(home, [log]).rows, incarnation)));
+  const a = addressOf(home);
+  if (a.incarnation === null) return null;
+  let log = readLog(a.homeLog, "home");
+  if (log.source.status === "absent") log = readLog(a.workspaceLog, "workspace");
+  return waitingShape(positiveOf(claimsOf(admit(a.home, [log]).rows, a.incarnation)));
 }
 
 const waitingError = (code, message) => Object.assign(new Error(message), { code });
@@ -238,8 +319,9 @@ const waitingError = (code, message) => Object.assign(new Error(message), { code
  *  other log; success means both logs took the row. Validates its input
  *  (E_BAD_ARGS); a home without a readable instance.json is
  *  E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
- *  repairs it). Evidence, not authority: nothing else is touched. */
-export function setWaiting(home, { producer, waiting, reason, message } = {}) {
+ *  repairs it). The answer's `home` is the home as the caller spelled it; the row
+ *  records the real path. Evidence, not authority: nothing else is touched. */
+export function setWaiting(given, { producer, waiting, reason, message } = {}) {
   if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
   if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
   if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
@@ -250,15 +332,16 @@ export function setWaiting(home, { producer, waiting, reason, message } = {}) {
     if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
     if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
   }
-  const incarnation = incarnationOf(home);
-  if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${home} is not an instance home (no readable instance.json)`);
-  const live = [readLog(join(home, HOME_LOG), "home"), readLog(workspaceLogPath(home), "workspace")]
+  const a = addressOf(given);
+  const { home, incarnation } = a;
+  if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${given} is not an instance home (no readable instance.json)`);
+  const live = [readLog(a.homeLog, "home"), readLog(a.workspaceLog, "workspace")]
     .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
   const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
-  const answer = (changed, claim) => ({ eventsApi: EVENTS_API, instance: basename(home), home, producer, changed, waitingOnYou: waitingShape(claim) });
+  const answer = (changed, claim) => answered(a, { eventsApi: EVENTS_API, instance: a.instance, home, producer, changed, waitingOnYou: waitingShape(claim) });
   if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
   const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
-  const res = appendEvent(home, { producer, kind: "waiting", data }, { incarnation });
+  const res = append(a, { producer, kind: "waiting", data }, { incarnation });
   const failed = (res.results || []).filter((r) => !r.ok);
   if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
   return answer(true, waiting ? { producer, since: res.row.at, reason, message: message ?? null } : null);
@@ -272,22 +355,23 @@ export function setWaiting(home, { producer, waiting, reason, message } = {}) {
  *  same data), and only when neither has it is the row made, still at the
  *  launch time, so a claim the new session made since is kept. `ok` is true
  *  only when every log holds the row; evidence, never authority. */
-export function recordStartBoundary(home, { startId, startedAt, ...data }) {
-  const paths = [join(home, HOME_LOG), workspaceLogPath(home)];
-  const instance = basename(home);
+export function recordStartBoundary(given, { startId, startedAt, ...data }) {
+  const a = addressOf(given);
+  const { home, instance } = a;
+  const paths = [a.homeLog, a.workspaceLog];
   const isIt = (r) => r.instance === instance && r.home === home && (r.producer ?? "kernel") === "kernel" && r.kind === "launched" && r.data?.startId === startId;
   const found = paths.map((path) => readLog(path, "log").rows.find(isIt) ?? null);
   if (found.every(Boolean)) return { ok: true, existed: true };
   const existing = found.find(Boolean);
   if (!existing) {
-    const res = appendEvent(home, { kind: "launched", data: { ...data, startId } }, { at: startedAt });
+    const res = append(a, { kind: "launched", data: { ...data, startId } }, { at: startedAt });
     return { ...res, ok: res.ok && (res.results || []).every((r) => r.ok) };
   }
   // The row exactly as the other log holds it: same time, incarnation and data.
   const line = JSON.stringify(existing) + "\n";
   const results = paths.filter((_, i) => !found[i]).map((path) => {
     try {
-      if (path.startsWith(home) && !existsSync(home)) return { path, ok: false, reason: "home absent" };
+      if (path === a.homeLog && !existsSync(home)) return { path, ok: false, reason: "home absent" };
       mkdirSync(dirname(path), { recursive: true });
       appendFileSync(path, line);
       return { path, ok: true };

package/lib/instance-git.mjs

@@ -6,7 +6,7 @@
  * 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 { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -44,6 +44,78 @@ function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
 }
 const trim = (s) => (s === null ? null : s.trim());
 
+const BRANCH_REFS = Buffer.from("refs/heads/");
+/** The two reads of HEAD, as bytes. They run like the module's other reads:
+ *  read-only, helper-free, and with the module's own environment (gitEnv),
+ *  which keeps only the caller's PATH and HOME: GIT_DIR, GIT_WORK_TREE,
+ *  GIT_COMMON_DIR, GIT_INDEX_FILE and every other variable of the caller are
+ *  not passed, and no global or system configuration is read, so nothing but
+ *  the work tree named by `-C` decides what is read. `-C` comes first. */
+const readHead = (work, args) => spawnSync("git", ["-C", work, ...READ_ONLY_GIT, ...args], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+/** What a failed read of HEAD says, without a line of the output that was not an error. */
+const headReadFailure = (r, command) => String(r.error?.message ?? r.stderr ?? "").trim() || `git ${command} ${r.signal ? `was ended by ${r.signal}` : `exited with ${r.status}`}`;
+
+/** What a work tree's HEAD names → { branch, detached, ref }. The one reader
+ *  of that name: the retire plan and the retire both use it.
+ *
+ *  `ref` is the ref HEAD points at, as the bytes `git symbolic-ref --quiet HEAD`
+ *  prints, without the one line feed that ends them; null when HEAD is
+ *  detached. It is evidence for a comparison and is never serialized. Through a
+ *  chain of symbolic refs it is the last one: the branch the commits go to.
+ *
+ *  `branch` is the name OATS carries for it: the part after `refs/heads/`, when
+ *  that part is valid UTF-8 (it decodes and encodes back to the same bytes).
+ *  Nothing of it is trimmed or replaced: a name may begin or end with a
+ *  character that reads as white space. It is null when HEAD is detached, and
+ *  also for a ref OATS carries no name for: one whose name is not valid UTF-8,
+ *  or one outside `refs/heads/`. So `branch: null, detached: false` means "a
+ *  name OATS does not carry", and two such HEADs are never taken for the same
+ *  one by their missing names: compare `ref`.
+ *
+ *  A read that fails throws E_WORK_INSPECTION_FAILED. Only Git's own quiet
+ *  answer (exit 1, nothing printed) is "detached". */
+export function headName(work) {
+  const r = readHead(work, ["symbolic-ref", "--quiet", "HEAD"]);
+  if (!r.error && r.status === 0 && r.stdout.length > 1) {
+    const ref = Buffer.from(r.stdout[r.stdout.length - 1] === 0x0a ? r.stdout.subarray(0, -1) : r.stdout);
+    let branch = null;
+    if (ref.length > BRANCH_REFS.length && ref.subarray(0, BRANCH_REFS.length).equals(BRANCH_REFS)) {
+      const name = ref.subarray(BRANCH_REFS.length);
+      try {
+        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(name);
+        if (Buffer.from(text, "utf8").equals(name)) branch = text;
+      } catch { /* not valid UTF-8: a name OATS does not carry */ }
+    }
+    return { branch, detached: false, ref };
+  }
+  if (!r.error && r.status === 1 && !r.stdout.length && !r.stderr.length) return { branch: null, detached: true, ref: null };
+  throw oatsError("E_WORK_INSPECTION_FAILED", `could not read what the worktree at ${work} has checked out: ${headReadFailure(r, "symbolic-ref")}`);
+}
+
+/** A worktree's HEAD for a retire → { commit, branch, detached, ref }: what
+ *  headName gives, and the commit HEAD is at.
+ *
+ *  A HEAD that has no commit (a branch that is not born yet) is a failed read
+ *  here: the retire proves its copy against this commit, and removes a
+ *  worktree only after it has asked which refs reach it, so there is nothing
+ *  it could do without one. That differs from the plan on purpose: the plan
+ *  (observeInstanceGit) reads the commit for itself, and an unborn work tree is
+ *  a value on its wire (`revision: "unborn"`).
+ *
+ *  The name and the commit are two reads, and nothing binds them but what is
+ *  done with them: a copy is proven against `commit`, so a name read at
+ *  another moment than the commit gives a copy that fails its proof. Nothing
+ *  destructive rests on the name. */
+export function worktreeHead(work) {
+  const name = headName(work);
+  const r = readHead(work, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  const commit = !r.error && r.status === 0 ? r.stdout.toString("latin1").replace(/\n$/, "") : "";
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(commit)) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", `the HEAD of the worktree at ${work} has no commit that could be read${r.error || r.stderr?.length ? `: ${headReadFailure(r, "rev-parse")}` : ""}`);
+  }
+  return { commit, ...name };
+}
+
 /** 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. */
@@ -169,12 +241,49 @@ 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);
 }
 
+/** The HEAD of a worktree a retire is about to remove, and whether a ref of
+ *  its repository reaches that commit → { head, unreached }. A ref outlives
+ *  the worktree; HEAD, and refs only the worktree has, do not.
+ *
+ *  One read in the repository that carries no ref name, so a ref whose name is
+ *  not valid UTF-8, or very many refs, cannot make it refuse:
+ *  `git for-each-ref --contains <commit> --count=1 --format=%(objectname)`.
+ *  Exit 0 with a line printed: some ref reaches the commit. Exit 0 with
+ *  nothing printed: none does, and the commit is something to preserve. Any
+ *  other exit throws E_WORK_INSPECTION_FAILED. Standard error is not a failure
+ *  here: a damaged ref prints a warning there with exit 0, and reaches
+ *  nothing. A commit that only another worktree's HEAD reaches counts as not
+ *  reached, which can only add a copy. */
+export function worktreeCommitUnreached(repo, work) {
+  const head = worktreeHead(work);
+  const r = spawnSync("git", ["-C", repo, ...READ_ONLY_GIT, "for-each-ref", "--contains", head.commit, "--count=1", "--format=%(objectname)"], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+  if (r.error || r.status !== 0) throw oatsError("E_WORK_INSPECTION_FAILED", `could not read which refs of ${repo} reach the commit the worktree at ${work} has checked out: ${headReadFailure(r, "for-each-ref")}`);
+  return { head, unreached: r.stdout.length === 0 };
+}
+
+/** The check made immediately before a retire removes a worktree: HEAD as it
+ *  is now (`now`, worktreeHead) against HEAD as the final inspection read it
+ *  (`inspected`). Equal when the commits are equal and both are detached or
+ *  both point at a ref with the same bytes. The branch names are not compared:
+ *  for a ref OATS carries no name for they are null on both sides, and null
+ *  equal to null proves nothing. Anything else throws
+ *  E_WORK_PRESERVATION_FAILED, and the worktree is not removed. */
+export function assertSameWorktreeHead(inspected, now) {
+  const same = !!inspected && !!now && inspected.commit === now.commit
+    && (inspected.ref === null || now.ref === null ? inspected.ref === null && now.ref === null && inspected.detached === true && now.detached === true : Buffer.compare(inspected.ref, now.ref) === 0);
+  if (!same) throw oatsError("E_WORK_PRESERVATION_FAILED", "the worktree's HEAD changed after it was inspected, so the worktree was not removed. The home and the worktree are kept, and so is any recovery the retire wrote; retry the retire.");
+}
+
 /** 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 name comes from headName, not from the status header, which prints
+  // "(detached)" and other words where a name would be and is read as text.
+  // The header still gives the upstream and its counts.
+  const head = headName(work);
   // 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.
@@ -198,10 +307,10 @@ export function observeInstanceGit(home) {
   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 },
+    observation: { revision, indexRevision: indexOid, at, worktree: work, branch: head.branch, detached: head.detached && headOid !== null, unborn: headOid === null },
+    recorded: { branch: meta.branch ?? null, repo: meta.repo ?? null, drift: meta.branch !== undefined && meta.branch !== null && head.branch !== meta.branch },
     upstream, base: baseComparison,
-    remote: remoteOf(work, branch.head),
+    remote: remoteOf(work, head.branch),
     summary, files,
     notes: [
       ...(upstream.ref === null ? ["no upstream configured: upstream ahead/behind are unknown, not zero"] : []),

package/lib/instance-lifecycle.mjs

@@ -167,7 +167,8 @@ function writeFileSyncAtomic(path, value) {
 /** 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. */
+ *  is the dialog's opt-in. No retire deletes a branch: `deleteBranch` is
+ *  always false. */
 export function planRetire(ctx, root, name, { home } = {}) {
   const me = resolveInstance(ctx, root, name, { home });
   const kids = descendantsOf(me.root, name);
@@ -183,7 +184,7 @@ export function planRetire(ctx, root, name, { 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.drift ? [`the worktree is on ${facts.work.branch ?? (facts.work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for")}, not the recorded ${facts.recordedBranch}`] : []),
       ...(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`] : []),

package/lib/packages.mjs

@@ -2,7 +2,7 @@
  * OATS packages — versions, lock v3 (workspace model v2).
  *
  * Contract: docs/design/2026-09-23-workspace-module-contracts.md §4.
- * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-expert/decisions/workspace-model-v2.md.
+ * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-maintainer/decisions/workspace-model-v2.md.
  *
  * A package is a place to fetch from WITH a version attached. Nothing is
  * installed: `resolvePackages` turns each `workspace.packages` entry into an

package/lib/resolve.mjs

@@ -2,7 +2,7 @@
  * lib/resolve.mjs — from a soul to an immutable resolution (module contract §3).
  *
  * Contract: docs/design/2026-09-23-workspace-module-contracts.md §3.
- * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-expert/decisions/workspace-model-v2.md (6, 12, 14, 16, 19–21).
+ * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-maintainer/decisions/workspace-model-v2.md (6, 12, 14, 16, 19–21).
  *
  * `resolveSoul(discovery, soulEntry, options)` turns a discovered soul into the
  * exact set of modules an instance will be built from: which capability comes

package/lib/schedule-command-child.mjs

@@ -7,9 +7,10 @@ import { signalGroup } from "./process-group.mjs";
 
 const { file, args, timeout, graceMs, maxBuffer } = JSON.parse(readFileSync(0, "utf8"));
 const result = await new Promise((resolve) => {
-  let child, status = null, signal = null, error;
-  let exited = false, closed = false, stopping = false, hardEnd = false, settled = false;
+  let child, status = null, signal = null, error, interrupted = false;
+  let exited = false, closed = false, stopping = false, hardEnd = false, settled = false, termSent = false;
   let deadline, escalation, probe, groupEmpty = false;
+  const signalHandlers = new Map();
   const chunks = { stdout: [], stderr: [] }, sizes = { stdout: 0, stderr: 0 };
   const groupAlive = () => {
     if (groupEmpty || !child?.pid) return false;
@@ -21,6 +22,11 @@ const result = await new Promise((resolve) => {
     if (process.platform === "win32") { if (!exited) child.kill(sig); }
     else if (groupAlive()) signalGroup(child, sig);
   };
+  const requestTerm = () => {
+    if (termSent || !child?.pid) return;
+    termSent = true;
+    send("SIGTERM");
+  };
   const finish = () => {
     if (settled || (!closed && !hardEnd) || (!exited && child?.pid)) return;
     // A leader can close while a pipe-free descendant ignores TERM. Keep the
@@ -28,31 +34,55 @@ const result = await new Promise((resolve) => {
     if (stopping && !hardEnd && groupAlive()) return;
     settled = true;
     clearTimeout(deadline); clearTimeout(escalation); clearInterval(probe);
-    resolve({ status, signal, stdout: Buffer.concat(chunks.stdout).toString("utf8"), stderr: Buffer.concat(chunks.stderr).toString("utf8"), ...(error ? { error } : {}) });
+    for (const [sig, handler] of signalHandlers) process.off(sig, handler);
+    resolve({ status, signal, stdout: Buffer.concat(chunks.stdout).toString("utf8"), stderr: Buffer.concat(chunks.stderr).toString("utf8"), ...(error ? { error } : {}), ...(interrupted ? { interrupted: true } : {}) });
+  };
+  const watchGroup = () => {
+    probe ??= setInterval(() => { groupAlive(); finish(); }, Math.min(50, graceMs));
   };
   const stop = (cause) => {
     if (stopping || settled) return;
-    stopping = true; error = cause;
-    send("SIGTERM");
+    stopping = true; error ??= cause;
+    requestTerm();
     escalation = setTimeout(() => {
       send("SIGKILL"); hardEnd = true;
       // A detached descendant can escape the group yet retain inherited pipes.
       // Its pipes must not prevent returning after the direct child's exit.
-      child.stdout.destroy(); child.stderr.destroy();
+      child?.stdout?.destroy(); child?.stderr?.destroy();
       finish();
     }, graceMs);
-    probe = setInterval(() => { if (closed) finish(); }, Math.min(50, graceMs));
+    watchGroup();
   };
+  // Catchable supervisor shutdown owns the same cleanup as timeout/overflow.
+  // Keep handlers throughout cleanup: repeated signals cannot bypass it.
+  // SIGKILL/OOM cannot run this path; a missing receipt stays unconfirmed.
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => {
+      // Preserve interruption even if overflow/timeout already began cleanup;
+      // the first error alone cannot describe both independent observations.
+      interrupted = true;
+      stop({ code: "EINTR", message: `schedule command supervisor interrupted by ${sig}` });
+    };
+    signalHandlers.set(sig, handler);
+    process.on(sig, handler);
+  }
   try { child = spawn(file, args, { detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] }); }
-  catch (e) { error = { code: e.code, message: e.message }; closed = true; finish(); return; }
+  catch (e) { error ??= { code: e.code, message: e.message }; closed = true; finish(); return; }
   for (const stream of ["stdout", "stderr"]) child[stream].on("data", (chunk) => {
     const room = maxBuffer - sizes[stream];
     if (room > 0) { const kept = chunk.subarray(0, room); chunks[stream].push(kept); sizes[stream] += kept.length; }
     if (chunk.length > room) stop({ code: "ENOBUFS", message: `schedule command ${stream} exceeded ${maxBuffer} bytes` });
   });
   child.once("error", (e) => { error ??= { code: e.code, message: e.message }; });
-  child.once("exit", (code, sig) => { exited = true; status = code; signal = sig; finish(); });
+  child.once("exit", (code, sig) => {
+    exited = true; status = code; signal = sig;
+    // Do not wait for pipes or the deadline: an escaped session may hold pipes
+    // after this group empties. Once observed empty it is never signalled again.
+    if (groupAlive()) watchGroup();
+    finish();
+  });
   child.once("close", () => { closed = true; finish(); });
+  if (stopping) requestTerm(); // Shutdown may have begun while spawn returned.
   deadline = setTimeout(() => stop({ code: "ETIMEDOUT", message: `schedule command exceeded ${timeout} ms` }), timeout);
 });
 process.stdout.write(JSON.stringify(result));