@awebai/oats 0.40.1 → 0.40.2

package/docs/schedules.md

@@ -86,8 +86,19 @@ jobs) sets it so that its command jobs can be told apart.
   sends SIGTERM to the child's process group, allows two seconds for cleanup,
   then sends SIGKILL if the group remains. It observes the direct child's exit
   before returning; inherited output pipes cannot hold the tick indefinitely.
-  A timeout leaves effects unconfirmed even if the child printed an envelope.
-  Spawn previews use the same bounded runner.
+  SIGINT, SIGTERM or SIGHUP received by the supervisor enters that same cleanup
+  once; repeated signals do not bypass it. A timeout or interrupted supervisor
+  leaves effects unconfirmed even if the child printed an envelope. Spawn
+  previews use the same bounded runner.
+
+  Cleanup covers the owned process group. A descendant that creates its own
+  session can escape it; inherited pipes are bounded but that escaped process
+  is not terminated by this group cleanup. The supervisor checks the group when
+  the leader exits and never signals it after observing it empty. This reduces
+  the group-ID reuse window; it does not eliminate PID reuse races. SIGKILL,
+  OOM and other unrecoverable supervisor deaths cannot run JavaScript handlers:
+  cleanup is not guaranteed then. Without a private supervisor receipt, the
+  scheduler keeps the unknown attempt and its slot until reconciliation.
 - **wake** `{…, home, message}` — every due minute inspects the instance at
   `home`. Running: `message` is delivered once as terminal input (bracketed
   paste plus Enter), never an interrupt. Not running: the home is started with
@@ -273,9 +284,12 @@ add` / `oats schedule add` definitions need no trust.
 
 **Opting out on one host.** `oats trigger disable <member>/<id>` writes
 `triggers.disabled`, and `oats schedule disable <member>/<id>` writes
-`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. A
-workspace definition is never edited or removed from the CLI (`update` and
-`remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
+`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. The
+schedule part of a qualified ID accepts up to 100 characters in both
+`schedules.disabled` and named `automations.trust` entries. Trigger definitions
+and `triggers.disabled` keep their 40-character limit; the shared trust list
+does not widen trigger IDs. A workspace definition is never edited or removed
+from the CLI (`update` and `remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
 
 **Refresh.**
 
@@ -329,12 +343,27 @@ current choices. Invalid values fail with `E_BAD_ARGS` before registration or
 timer changes. `host status` reports the effective `maxConcurrent` and
 `triggersMaxConcurrent` (`null` when uncapped).
 
-The registry stores explicit choices only. On the first registry read after
-upgrade, a legacy stored `maxConcurrent: 1` without the new choice marker is
-migrated to the default under the registry lock; other explicit values survive.
-If you need a cap of one, run `oats schedule host install --max-concurrent 1`
-after upgrading. That explicit choice survives later reads and reinstalls.
-Set these values through the CLI; do not edit the registry by hand.
+The registry stores explicit choices only. Reading status or the registry takes
+no registry lock and creates or rewrites no files or directories. A reader
+interprets a pre-migration stored `maxConcurrent: 1` as the default of five in
+memory. Registration, unregistration and cap updates persist that migration
+once, under the registry lock, even if the workspace membership is unchanged.
+Other explicit values and the independent trigger cap survive.
+
+A pre-migration hand-set one is indistinguishable from the old implicit one;
+both follow that compatibility choice. When a write migrates one to the default,
+it prints a notice on stderr with `oats schedule host install --max-concurrent 1`
+to restore one if needed. Pure reads stay silent and JSON stdout is unchanged.
+A later explicit one survives writes by current kernels. Older binaries sharing
+the registry can write one back while preserving `capsVersion: 2`; there is no
+provenance to distinguish that from a new explicit one. Stop mixed-version
+writes and explicitly set the desired cap with the supported CLI.
+
+A present invalid `maxConcurrent` is `E_SCHEDULE_INVALID`, not a fallback to
+five. Correct it with `oats schedule host install --max-concurrent N` (or
+`--max-concurrent default`) from the deployment, or with `--dir <deployment>`.
+An absent value still means five. Set caps through the CLI; do not edit the
+registry by hand.
 
 `oats schedule list --json` answers:
 

package/docs/servers.md

@@ -298,7 +298,9 @@ the host's own facts from its `status --json`: `identity`,
 `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
 `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
 `relativeTo` and `spawnOrigin`. A fact the host does not supply is `null`
-(an older host, or a saved route the host no longer lists). A removed or edited registration keeps
+(an older host, or a saved route the host no longer lists). A row also
+carries `waitingOnYou` (needs input) when the host's kernel reports it, and
+only then: an older host's row has no such key. A removed or edited registration keeps
 its group from the saved routes. State is pulled on every call within
 `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
 not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.

package/docs/workspaces.md

@@ -54,7 +54,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.6.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.6.1                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 

package/lib/core.mjs

@@ -2668,6 +2668,12 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
   }
   return step.value;
 }
+/** The producer sets this only when dispatched effects or their compensation
+ * cannot be confirmed. A diagnostic's wording or home path is not evidence. */
+function unconfirmedSpawn(error) {
+  error.details = { ...error.details, unconfirmed: true };
+  return error;
+}
 function* spawnBody(root, agent, o = {}) {
   if (!o.prepared) throw localMissingForSpawn(agent);
   const deliver = (r) => r;
@@ -2756,7 +2762,7 @@ function* spawnBody(root, agent, o = {}) {
       // Completion custody: the home exists from the first metadata write, but
       // the launch/lineage/events that make it a finished spawn may not have
       // happened (crash in the interval). Say which, never replay a half-spawn.
-      if (prior.spawnCompleted !== true) throw Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false });
+      if (prior.spawnCompleted !== true) throw unconfirmedSpawn(Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false }));
       return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null } };
     }
   }
@@ -3218,7 +3224,7 @@ function* spawnBody(root, agent, o = {}) {
   // name taken (M1). Nothing of a classic home exists at this point either.
   const rollbackEmptyOrPreparedHome = (e) => {
     try { rmSync(home, { recursive: true, force: true }); }
-    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; }
+    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; unconfirmedSpawn(e); }
     return e;
   };
   // Workspace model: copy every resolved capability WHOLE into the new home
@@ -3386,9 +3392,10 @@ function* spawnBody(root, agent, o = {}) {
   if (incomplete.length) {
     // Nothing outside the home exists yet (no worktree, no hooks, no window), so
     // removing the scaffold is the whole rollback.
-    let removal = "";
-    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
-    throw oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    let removal = "", removalFailed = false;
+    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removalFailed = true; removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
+    const error = oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    throw removalFailed ? unconfirmedSpawn(error) : error;
   }
 
   // Work tree.
@@ -3433,7 +3440,8 @@ function* spawnBody(root, agent, o = {}) {
       }
       try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
       const note = incomplete.length ? ` — rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}` : "";
-      throw new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      const error = new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      throw incomplete.length ? unconfirmedSpawn(error) : error;
     }
   } else if (work === "directory") {
     // An owned execution directory, not a link to the source or a fake Git repo.
@@ -3529,11 +3537,11 @@ function* spawnBody(root, agent, o = {}) {
           outstandingGit.add("worktree");
           if (branch) outstandingGit.add("branch");
         }
-        return quarantineInstanceHome({
+        return { unconfirmed: true, note: quarantineInstanceHome({
           home, instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId, incomplete, failed, outstandingHooks, outstandingGit,
           repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
           launched: true, tmux: spawnTmux, directoryHome: homeReal, recordRetirementBaseline: true,
-        });
+        }) };
       }
     }
     // Once hooks ran, directory execution may already hold authored results.
@@ -3555,7 +3563,7 @@ function* spawnBody(root, agent, o = {}) {
         launched: false, directoryPreservation: true, directoryHome: homeReal,
         recordRetirementBaseline: true,
       });
-      return `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}`;
+      return { unconfirmed: true, note: `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}` };
     };
     const preserveDirectory = () => {
       if (work !== "directory") return;
@@ -3639,7 +3647,7 @@ function* spawnBody(root, agent, o = {}) {
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    return `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}`;
+    return { unconfirmed: incomplete.length > 0, note: `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}` };
   };
 
   try {
@@ -3858,8 +3866,15 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     }
     return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
   } catch (error) {
-    const note = compensateSpawn();
-    error.message += note;
+    try {
+      const compensation = compensateSpawn();
+      error.message += compensation.note;
+      if (compensation.unconfirmed) unconfirmedSpawn(error);
+    } catch (cleanupError) {
+      // An interrupted compensation pass cannot establish that effects ended.
+      error.message += ` — rollback INCOMPLETE: cleanup could not be completed: ${cleanupError.message}`;
+      unconfirmedSpawn(error);
+    }
     throw error;
   }
 }

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/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));