@awebai/oats 0.39.4 → 0.40.2

package/lib/instance-events.mjs

@@ -18,42 +18,158 @@
  *    recreated same-address instance's earlier rows are visible as earlier;
  *  - `waitingOnYou` is a producer STATE per (producer, current incarnation):
  *    that producer's latest row carrying the field decides, an explicit `false`
- *    clears, and it is computed over the full admitted read, before windowing. */
-import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+ *    clears, and it is computed over the full admitted read, before windowing;
+ *  - a claim is LIVE only after the incarnation's latest kernel session
+ *    boundary (`launched` | `restarted` | `stopped`): a claim written before
+ *    the boundary belongs to a session that has ended (WAITING_BOUNDARY_KINDS).
+ *
+ * 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.
+ *
+ * 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";
 const MAX_BYTES = 4 * 1024 * 1024;
 
-export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "recomposed"];
+export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "recomposed", "waiting"];
 
-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`);
+/** Kernel rows that end or begin a session: a waiting claim older than the
+ *  incarnation's latest one is not live. */
+export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
+/** The closed set of reasons a positive claim carries. */
+export const WAITING_REASONS = ["permission", "question", "attention"];
+/** A producer id: what `--producer` accepts (`kernel` is reserved). */
+export const WAITING_PRODUCER_RE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
+export const WAITING_MESSAGE_MAX = 200;
+/** Characters a claim's message may not contain (the maintainer's set): control
+ *  characters (Cc: C0, DEL, C1), the Unicode line and paragraph separators, the bidi
+ *  embeddings, overrides and isolates (U+202A-202E, U+2066-2069), the invisible hiders
+ *  U+200B, U+2060 and U+FEFF, and the tag characters (U+E0000-E007F). Everything else is
+ *  allowed, ZWJ and ZWNJ (U+200C/D, emoji sequences, Persian and Indic text) and the marks
+ *  LRM, RLM and ALM (U+200E/F, U+061C) included. The Desktop uses the identical set. */
+const WAITING_MESSAGE_REFUSED = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
+/** A claim's message: a non-empty string of 1 to 200 code points with none of
+ *  WAITING_MESSAGE_REFUSED. The writer refuses anything else; the reader turns a stored
+ *  message that fails it (a hand-edited log) into null. */
+export function validWaitingMessage(m) {
+  return typeof m === "string" && m.length > 0 && [...m].length <= WAITING_MESSAGE_MAX && !WAITING_MESSAGE_REFUSED.test(m);
 }
+// A reason read back from a log is shown as given only when it is one of the
+// 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));
 
-/** 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; }
+/** 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 };
+}
+
+/** 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 } = {}) {
+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}` };
-  const row = { eventsApi: EVENTS_API, 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 } : {}) };
+  // `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 && !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 });
@@ -96,47 +212,170 @@ function readLog(path, label) {
   return { rows, unreadable, source: { path: label, status: tail ? "tail" : "ok", bytes: st.size } };
 }
 
-/** 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 } = {}) {
+/** The ADDRESS's rows from the given log reads: foreign rows dropped and
+ *  counted, oldest first. The logs are merged as a multiset union: a row in
+ *  both logs (the same fact, written to each) is kept once, but rows that
+ *  genuinely repeat within one log (a set, a clear and the same set again in
+ *  one millisecond) are all kept, as many times as the log holding the most
+ *  copies has them. */
+function admit(home, reads) {
   const instance = basename(home);
-  const incarnation = incarnationOf(home);
-  const a = readLog(join(home, HOME_LOG), "home"), b = readLog(workspaceLogPath(home), "workspace");
-  const seen = new Set(); const rows = []; let foreign = 0;
-  for (const r of [...a.rows, ...b.rows]) {
-    if (r.instance !== instance || r.home !== home) { foreign++; continue; } // another address's row in this log: history of THIS address only
-    const k = `${r.producer ?? "kernel"}|${r.at}|${r.kind}|${r.incarnation ?? ""}|${JSON.stringify(r.data ?? null)}`; // same facts from two producers are two rows
-    if (seen.has(k)) continue; seen.add(k); rows.push({ ...r, incarnation: r.incarnation ?? null });
+  const admitted = new Map(); const rows = []; let foreign = 0;
+  for (const read of reads) {
+    const inThisLog = new Map();
+    for (const r of read.rows) {
+      if (r.instance !== instance || r.home !== home) { foreign++; continue; } // another address's row in this log: history of THIS address only
+      const k = `${r.producer ?? "kernel"}|${r.at}|${r.kind}|${r.incarnation ?? ""}|${JSON.stringify(r.data ?? null)}`; // same facts from two producers are two rows
+      const n = (inThisLog.get(k) ?? 0) + 1; inThisLog.set(k, n);
+      if (n <= (admitted.get(k) ?? 0)) continue; // this copy is already in from another log
+      admitted.set(k, n); rows.push({ ...r, incarnation: r.incarnation ?? null });
+    }
   }
   rows.sort((x, y) => x.at.localeCompare(y.at));
-  // Waiting: a producer STATE for the CURRENT incarnation, decided by that
-  // producer's latest row that carries the field, over the FULL admitted read.
-  // An UNKNOWN current incarnation (unreadable instance.json) admits NO claim:
-  // unknown stays unknown, it never resurrects an earlier incarnation's positive.
+  return { rows, foreign };
+}
+
+/** Waiting: a producer STATE for the CURRENT incarnation, decided by that
+ *  producer's latest row that carries the field, over the FULL admitted read.
+ *  An UNKNOWN current incarnation (unreadable instance.json) admits NO claim:
+ *  unknown stays unknown, it never resurrects an earlier incarnation's
+ *  positive. A row older than the incarnation's latest kernel session
+ *  boundary belongs to an ended session and is not a claim at all, nor is a
+ *  row whose producer is neither `kernel` nor a valid producer id. */
+function claimsOf(rows, incarnation) {
   const claims = new Map();
-  for (const r of (incarnation === null ? [] : rows)) {
-    if (r.incarnation !== incarnation) continue;
+  if (incarnation === null) return claims;
+  const current = rows.filter((r) => r.incarnation === incarnation);
+  // Positional: rows are time-sorted with a stable sort, so rows of the same
+  // millisecond keep their append order, and a claim appended before the
+  // boundary in that millisecond is still before it.
+  const boundary = current.findLastIndex((r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind));
+  for (const r of current.slice(boundary + 1)) {
     if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
     const p = r.producer ?? "kernel";
-    claims.set(p, r.data.waitingOnYou ? { producer: p, waiting: true, since: r.at, reason: typeof r.data.reason === "string" ? r.data.reason : null } : { producer: p, waiting: false, since: r.at, reason: null });
+    // 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: claim.since, reason: claim.reason, message: claim.message }
+      : { producer: p, waiting: false, since: claim.since, reason: null, message: null });
   }
+  return claims;
+}
+const positiveOf = (claims) => [...claims.values()].filter((c) => c.waiting).sort((x, y) => x.since.localeCompare(y.since)).at(-1) ?? null;
+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. 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 = waitingClaims.filter((c) => c.waiting).sort((x, y) => x.since.localeCompare(y.since)).at(-1) ?? null;
+  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] },
     events: window, lastEvent: last ? { kind: last.kind, at: last.at, producer: last.producer ?? "kernel", incarnation: last.incarnation } : null,
-    waitingOnYou: positive ? { since: positive.since, producer: positive.producer, reason: positive.reason } : null,
+    waitingOnYou: waitingShape(positive),
     waitingClaims,
     notes: [
       "events are producer-attributed facts written by the kernel action that made them true; nothing is inferred from transcripts or task files",
       "this is the ADDRESS's history: rows tagged with an earlier incarnation belong to a previous instance at this address",
       "waitingOnYou is null unless a producer reported it for the current incarnation — null means unknown, not 'not waiting'; an explicit false clears that producer's claim; an unknown current incarnation (null) admits no claim at all",
+      "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
+ *  null: what `oats status` rows and `oats session inspect` carry. The same
+ *  bounded read and the same claim rule as readEvents, over the home log only
+ *  (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 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 });
+
+/** Set or clear one producer's waiting claim on an instance home; appends a
+ *  `waiting` row only when the producer's LIVE claim changes (a positive set
+ *  whose reason or message differs is a change; a clear of a claim that is
+ *  not positive is not). Each log is judged on its own, so a row that reached
+ *  only one log earlier is repaired by the next call rather than hidden by the
+ *  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). 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");
+  if (waiting) {
+    if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
+    if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
+  } else {
+    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 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) => 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 = 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);
+}
+
+/** The kernel session boundary of one start receipt: a `launched` row tagged
+ *  `startId`, dated at the receipt's `startedAt`, written once to each log. A
+ *  start records it as soon as its session exists; recovering an interrupted
+ *  start (its receipt adopted later) completes it: a log that already has the
+ *  row is left alone, a log missing it gets a copy of the same row (same time,
+ *  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(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 = 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 === a.homeLog && !existsSync(home)) return { path, ok: false, reason: "home absent" };
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, line);
+      return { path, ok: true };
+    } catch (e) { return { path, ok: false, reason: e.message }; }
+  });
+  return { ok: results.every((r) => r.ok), repaired: true, row: existing, results };
 }

package/lib/schedule-command-child.mjs

@@ -0,0 +1,88 @@
+/** Private entry point for schedule-command.mjs; no CLI or provider contract.
+ * stdin carries launch arguments, stdout carries the observed command result.
+ * Command output has separate pipes so it cannot forge that result. */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+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, 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;
+    if (process.platform === "win32") return !exited;
+    try { process.kill(-child.pid, 0); return true; }
+    catch { groupEmpty = true; return false; }
+  };
+  const send = (sig) => {
+    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
+    // supervisor alive until the grace ends or its group is observed empty.
+    if (stopping && !hardEnd && groupAlive()) return;
+    settled = true;
+    clearTimeout(deadline); clearTimeout(escalation); clearInterval(probe);
+    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;
+    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();
+      finish();
+    }, 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; }
+  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;
+    // 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));

package/lib/schedule-command.mjs

@@ -0,0 +1,26 @@
+/** Synchronous scheduler child execution with an asynchronous timeout supervisor.
+ * The tick and its lock callbacks stay synchronous; only the supervisor owns
+ * the child, observes its exit and runs the TERM/KILL timers. Its stdout is a
+ * private result channel, never the command's stdout. */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { TERM_GRACE_MS } from "./process-group.mjs";
+
+const SUPERVISOR = fileURLToPath(new URL("./schedule-command-child.mjs", import.meta.url));
+export function runScheduleCommand(file, args, { cwd, env, timeout = 300_000, graceMs = TERM_GRACE_MS, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  for (const [name, value] of Object.entries({ timeout, graceMs, maxBuffer })) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 2 ** 31 - 1) throw new TypeError(`${name} must be a positive 32-bit integer`);
+  }
+  const r = spawnSync(process.execPath, [SUPERVISOR], {
+    cwd, env, encoding: "utf8", input: JSON.stringify({ file, args, timeout, graceMs, maxBuffer }),
+    // Each output stream is byte-bounded. JSON can expand a byte to six bytes.
+    maxBuffer: maxBuffer * 12 + 65536,
+  });
+  if (!r.error && r.status === 0) {
+    try { return JSON.parse(r.stdout); } catch { /* no trusted supervisor receipt */ }
+  }
+  // A failed supervisor is not evidence that its command exited. The scheduler
+  // conservatively retains the attempt and slot when there is no receipt.
+  return { status: null, signal: null, stdout: "", stderr: String(r.stderr || ""),
+    error: { code: r.error?.code || "E_SCHEDULE_RUNNER", message: r.error?.message || "schedule child supervisor returned no result" } };
+}