@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/agent/process.ts

@@ -4,28 +4,133 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
-import { readChildProcessIdentity, trySignalChildTree } from "../shared/post-exit-stdio-guard.ts";
-import { processSchema, type Launch, type ProcessIdentity } from "./contracts.ts";
-import { conversation, read, write } from "./storage.ts";
+import {
+  isChildProcessReplaced,
+  observeChildProcessReplaced,
+  readChildProcessIdentity,
+  readProcessClock,
+  trySignalChildTree,
+} from "../shared/post-exit-stdio-guard.ts";
+import { agentObservationSocketPath } from "../pi-intercom/broker/paths.ts";
+import { hasErrorCode } from "../shared/unknown.ts";
+import {
+  attachmentSchema,
+  parkedSchema,
+  processSchema,
+  type Launch,
+  type ProcessIdentity,
+} from "./contracts.ts";
+import { conversation, enqueue, launchAt, list, read, write } from "./storage.ts";
+import { errorText } from "./host.ts";
 
-export function alive(identity: Pick<ProcessIdentity, "pid" | "identity">): boolean {
+/** Darwin's in-memory publication bound; Android records carry their own native clock. */
+interface Published {
+  readonly published?: number | undefined;
+}
+type OwnedProcess = ProcessIdentity & Published;
+type ClaimedProcess = Pick<ProcessIdentity, "pid" | "identity" | "clock"> & Published;
+/** Owner records follow their process's birth; stat after read only moves the bound later. */
+export function published<T extends object>(
+  file: string,
+  record: T | undefined,
+): (T & Published) | undefined {
+  return record && { ...record, published: fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs };
+}
+/** Settles liveness without a birth lookup; undefined means compare the recorded birth. */
+function probe(identity: ClaimedProcess): boolean | undefined {
   try {
     process.kill(identity.pid, 0);
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ESRCH") {
-      return false;
+    // EPERM still names a live PID, possibly another user's reuse; check its birth below.
+    if (!hasErrorCode(error, "EPERM")) {
+      return !hasErrorCode(error, "ESRCH");
     }
-    return true;
   }
-  const actual = readChildProcessIdentity(identity.pid);
-  return identity.identity === "unverified" || actual === undefined || actual === identity.identity;
+  return identity.identity === "unverified" ? true : undefined;
+}
+export function alive(identity: ClaimedProcess): boolean {
+  // Only a proven different birth disproves a live PID; ambiguous identities stay possibly owned.
+  return (
+    probe(identity) ??
+    (readChildProcessIdentity(identity.pid) === identity.identity || !replaced(identity))
+  );
+}
+/** Routine `alive` without waiting on `ps`; signals still use the synchronous proof. */
+export async function observeAlive(identities: readonly ClaimedProcess[]): Promise<boolean[]> {
+  const verdicts: boolean[] = [];
+  for (const claim of identities) {
+    // One `ps` at a time: each spawn briefly holds the event loop, so concurrent spawns add up.
+    const { pid, identity, clock } = claim;
+    verdicts.push(
+      probe(claim) ??
+        // oxlint-disable-next-line no-await-in-loop
+        !(await observeChildProcessReplaced(pid, identity, claim.published, clock)),
+    );
+  }
+  return verdicts;
 }
-export function ownIdentity(): { pid: number; identity: string } {
-  // An ordinary main need not be a group leader. Ambiguous live PIDs fail closed.
-  return { pid: process.pid, identity: readChildProcessIdentity(process.pid) ?? "unverified" };
+/**
+ * A child's routine parent check, one observation at a time. A dead parent detaches the child
+ * only while its check is current and the attachment generation is unchanged: a newer parent
+ * may adopt the child meanwhile.
+ */
+export class ParentCheck {
+  private current?: object;
+  /**
+   * Reads the attachment synchronously, so an unreadable one still fails the caller at once.
+   * Missing or released attachments detach immediately; a check in flight makes this a no-op.
+   */
+  check(file: string, detached: () => void): Promise<void> {
+    if (this.current !== undefined) {
+      return Promise.resolve();
+    }
+    const attachment = published(file, read(file, attachmentSchema));
+    if (attachment === undefined || !attachment.attached) {
+      detached();
+      return Promise.resolve();
+    }
+    const check = {};
+    this.current = check;
+    const settle = async () => {
+      try {
+        const [live] = await observeAlive([attachment]);
+        if (
+          this.current === check &&
+          !live &&
+          read(file, attachmentSchema)?.generation === attachment.generation
+        ) {
+          detached();
+        }
+      } finally {
+        if (this.current === check) {
+          this.current = undefined;
+        }
+      }
+    };
+    return settle();
+  }
+  /** A check settling later no longer acts. */
+  cancel(): void {
+    this.current = undefined;
+  }
 }
-export function actor(base: string, launch: Launch): ProcessIdentity | undefined {
-  return read(path.join(conversation(base, launch), "actor.lock", "process.json"), processSchema);
+function replaced(identity: ClaimedProcess): boolean {
+  return (
+    identity.identity !== "unverified" &&
+    isChildProcessReplaced(identity.pid, identity.identity, identity.published, identity.clock)
+  );
+}
+export function ownIdentity(pid = process.pid): Omit<ProcessIdentity, "token"> {
+  // An ordinary main or managed launcher need not be a group leader. Ambiguous live PIDs fail closed.
+  return {
+    pid,
+    identity: readChildProcessIdentity(pid) ?? "unverified",
+    clock: readProcessClock(),
+  };
+}
+export function actor(base: string, launch: Launch): OwnedProcess | undefined {
+  const file = path.join(conversation(base, launch), "actor.lock", "process.json");
+  return published(file, read(file, processSchema));
 }
 function childEnvironment(launch: Launch): NodeJS.ProcessEnv {
   const env = { ...process.env };
@@ -76,12 +181,21 @@ function spawnActor(base: string, launch: Launch, token: string): void {
     pid: child.pid,
     identity: readChildProcessIdentity(child.pid) ?? "unverified",
     token,
+    clock: readProcessClock(),
   });
 }
-async function awaitStopping(dir: string, existing: ProcessIdentity | undefined): Promise<void> {
-  if (existing && fs.existsSync(path.join(dir, `stopping-${existing.token}.json`))) {
-    const deadline = Date.now() + 5000;
-    while (alive(existing)) {
+async function awaitStopping(
+  dir: string,
+  existing: OwnedProcess | undefined,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (existing) {
+    const stopping = path.join(dir, `stopping-${existing.token}.json`);
+    // Parking ends in exit or a removed marker, after native shutdown persistence.
+    const parking = path.join(dir, "actor.lock", "parking.json");
+    const deadline = Date.now() + (fs.existsSync(stopping) ? 5000 : 30_000);
+    while ((fs.existsSync(stopping) || fs.existsSync(parking)) && alive(existing)) {
+      signal?.throwIfAborted();
       if (Date.now() > deadline) {
         throw new Error("Previous actor is still stopping; no replacement was launched.");
       }
@@ -91,19 +205,26 @@ async function awaitStopping(dir: string, existing: ProcessIdentity | undefined)
     }
   }
 }
-export async function ensureActor(base: string, launch: Launch): Promise<void> {
+export async function ensureActor(
+  base: string,
+  launch: Launch,
+  signal?: AbortSignal,
+): Promise<void> {
   const dir = conversation(base, launch);
   const lock = path.join(dir, "actor.lock");
-  await awaitStopping(dir, actor(base, launch));
+  await awaitStopping(dir, actor(base, launch), signal);
+  signal?.throwIfAborted();
   // Another parallel tool may replace the claim while this invocation yields.
   const existing = actor(base, launch);
   if (existing && alive(existing)) {
     return;
   }
+  parkFailure(base, launch, existing);
   if (existing) {
     if (shells(base, launch, existing.token).some(alive)) {
       throw new Error("Owned native shell work remains live; stop it before continuing.");
     }
+    removeObservationEndpoint(existing.token);
     fs.rmSync(lock, { recursive: true });
   }
   try {
@@ -120,32 +241,77 @@ export async function ensureActor(base: string, launch: Launch): Promise<void> {
   write(path.join(lock, "claim.json"), { ...ownIdentity(), token });
   spawnActor(base, launch, token);
 }
-function verifyLiveness(pid: number): boolean {
+/** A failed park keeps its input queued; exact state is lost, so nothing restarts it implicitly. */
+export function parkFailure(base: string, launch: Launch, exited?: OwnedProcess): void {
+  const dir = conversation(base, launch);
+  const parked = read(path.join(dir, "parked.json"), parkedSchema);
+  if (exited && parked && parked.token !== exited.token) {
+    // Only the exited claim that saved this state may hand it to the next generation.
+    throw new Error(
+      "Parked working state belongs to another actor generation; nothing was reopened.",
+    );
+  }
+  const file = path.join(dir, "park-failed.json");
+  if (fs.existsSync(file)) {
+    throw new Error(
+      `This idle child exited without saving its exact working state (${file}). Nothing was restarted or admitted; messages for it stay queued. Inspect it, then delegate new work.`,
+    );
+  }
+}
+/** A broker wake may only restore exact parked state, never reopen the journal alone. */
+export async function wakeActor(base: string, launch: Launch, signal?: AbortSignal): Promise<void> {
+  const dir = conversation(base, launch);
+  await awaitStopping(dir, actor(base, launch), signal);
+  parkFailure(base, launch);
+  if (!fs.existsSync(path.join(dir, "parked.json"))) {
+    throw new Error("No parked working state; the child was not woken.");
+  }
+  await ensureActor(base, launch, signal);
+}
+/** A crashed generation cannot unlink its endpoint; its exact token names the leftover. */
+function removeObservationEndpoint(token: string): void {
+  try {
+    const socketPath = agentObservationSocketPath(token);
+    if (fs.lstatSync(socketPath, { throwIfNoEntry: false })?.isSocket() === true) {
+      fs.rmSync(socketPath, { force: true });
+    }
+  } catch {
+    // Observation leftovers are inert to a new token and must never block native work.
+  }
+}
+function verifyLiveness(identity: OwnedProcess): boolean {
   try {
-    process.kill(pid, 0);
+    process.kill(identity.pid, 0);
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+    // Another user's live PID is released only by the same proof as a signalable one.
+    if (hasErrorCode(error, "ESRCH") || (hasErrorCode(error, "EPERM") && replaced(identity))) {
       return false;
     }
     throw new Error("Actor liveness is ambiguous; no stop was sent.", { cause: error });
   }
   return true;
 }
-export function verifyProcess(identity: ProcessIdentity): boolean {
-  if (!verifyLiveness(identity.pid)) {
+export function verifyProcess(identity: OwnedProcess): boolean {
+  if (!verifyLiveness(identity)) {
     return false;
   }
   const actual = readChildProcessIdentity(identity.pid);
-  if (identity.identity !== "unverified" && actual === undefined && !verifyLiveness(identity.pid)) {
-    // Native abort can reap a shell between the liveness probe and birth lookup.
-    return false;
+  if (identity.identity !== "unverified" && actual !== identity.identity) {
+    if (actual === undefined && !verifyLiveness(identity)) {
+      // Native abort can reap a shell between the liveness probe and birth lookup.
+      return false;
+    }
+    // A different-birth process at the PID proves the recorded process is gone.
+    if (replaced(identity)) {
+      return false;
+    }
   }
   if (identity.identity === "unverified" || actual !== identity.identity) {
     throw new Error("Cannot verify actor process identity; no signal sent.");
   }
   return true;
 }
-export function signalProcess(identity: ProcessIdentity, signal: NodeJS.Signals): boolean {
+export function signalProcess(identity: OwnedProcess, signal: NodeJS.Signals): boolean {
   if (!verifyProcess(identity)) {
     return false;
   }
@@ -154,18 +320,95 @@ export function signalProcess(identity: ProcessIdentity, signal: NodeJS.Signals)
     signal,
   );
 }
-export function shells(base: string, launch: Launch, token: string): ProcessIdentity[] {
+export function requestStop(
+  base: string,
+  launch: Launch,
+  onError?: (error: unknown) => void,
+): { targets: OwnedProcess[]; command: string | undefined } {
+  const attempt = (operation: () => boolean): boolean => {
+    try {
+      return operation();
+    } catch (error) {
+      if (onError === undefined) {
+        throw error;
+      }
+      onError(error);
+      return false;
+    }
+  };
+  const identity = actor(base, launch);
+  const targets = identity ? [identity, ...shells(base, launch, identity.token)] : [];
+  // Interactive Stop validates the whole set; shutdown reports and skips only ambiguous targets.
+  const live = targets.filter((target) => attempt(() => verifyProcess(target)));
+  const command =
+    identity && live.includes(identity)
+      ? enqueue(base, launch, "stop", { actorToken: identity.token })
+      : undefined;
+  if (identity && live.length > 0) {
+    write(path.join(conversation(base, launch), `stopping-${identity.token}.json`), {
+      at: Date.now(),
+    });
+  }
+  live.forEach((target) => {
+    attempt(() => signalProcess(target, "SIGTERM"));
+  });
+  return { targets: live, command };
+}
+export async function stopChildren(base: string, owner: string): Promise<void> {
+  const roots = new Set<string>();
+  const targets: OwnedProcess[] = [];
+  for (const id of list(base)) {
+    try {
+      const launch = launchAt(base, id, owner);
+      if (!roots.has(launch.rootId)) {
+        roots.add(launch.rootId);
+        targets.push(
+          ...requestStop(base, launch, (error) => {
+            console.error(`Child shutdown ${id}: ${errorText(error)}`);
+          }).targets,
+        );
+      }
+    } catch (error) {
+      console.error(`Child shutdown ${id}: ${errorText(error)}`);
+    }
+  }
+  await waitForExit(targets, 3000);
+  for (const target of targets) {
+    try {
+      signalProcess(target, "SIGKILL");
+    } catch (error) {
+      console.error(`Child shutdown ${target.pid}: ${errorText(error)}`);
+    }
+  }
+  await waitForExit(targets, 1000);
+  if (targets.some(alive)) {
+    console.error("Child shutdown could not confirm every owned process exit.");
+  }
+}
+async function waitForExit(targets: readonly OwnedProcess[], timeout: number): Promise<void> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline && targets.some(alive)) {
+    // Join actual process exit while native abort persists the interrupted turn.
+    // oxlint-disable-next-line no-await-in-loop
+    await delay(25);
+  }
+}
+export function shells(base: string, launch: Launch, token: string): OwnedProcess[] {
   const dir = path.join(conversation(base, launch), "shells", token);
   if (!fs.existsSync(dir)) {
     return [];
   }
-  return fs.readdirSync(dir).map((name) => {
-    const identity = read(path.join(dir, name), processSchema);
-    if (!identity || identity.token !== token) {
-      throw new Error("Foreign or missing native shell identity.");
-    }
-    return identity;
-  });
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => {
+      const file = path.join(dir, name);
+      const identity = published(file, read(file, processSchema));
+      if (!identity || identity.token !== token) {
+        throw new Error("Foreign or missing native shell identity.");
+      }
+      return identity;
+    });
 }
 function quote(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;

package/src/agent/receipts.ts

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import { scanJournal } from "../shared/journal-frames.ts";
-import { journalStamp } from "../shared/native-journal.ts";
+import { journalStamp, nativeAppend } from "../shared/native-journal.ts";
 import type { Projection } from "../shared/json-projection.ts";
-import type { UnknownRecord } from "../shared/unknown.ts";
+import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
 
 const detailFields = new Set([
   "owner",
@@ -35,7 +35,7 @@ const receiptProjection: Projection = (keys) => {
   if (keys.length === 0) {
     return true;
   }
-  if (["type", "id", "customType"].includes(String(keys[0]))) {
+  if (["type", "id", "customType", "version"].includes(String(keys[0]))) {
     return keys.length === 1 ? 4096 : false;
   }
   if (keys[0] !== "message") {
@@ -50,39 +50,129 @@ const receiptProjection: Projection = (keys) => {
   return detailsProjection(keys.slice(1));
 };
 
-/** Physical LF publication owns delivery, including when native memory is stale. */
-export function receiptId(
-  file: string | undefined,
-  owner: string,
-  matches: (entry: UnknownRecord) => boolean,
-): string | undefined {
-  if (file === undefined || !fs.existsSync(file)) {
-    return;
+interface ReceiptIndex {
+  stamp: string;
+  end: number;
+  stat: fs.BigIntStats;
+  entries: UnknownRecord[];
+  /** First completion receipt per owned run ID, built in the same LF pass. */
+  completions: Map<string, string | undefined>;
+}
+const indexes = new Map<string, ReceiptIndex>();
+type Prefix = Pick<ReceiptIndex, "end" | "entries" | "completions">;
+
+function toolCompletion(message: unknown): unknown {
+  return isRecord(message) &&
+    message.role === "toolResult" &&
+    (message.toolName === "delegate" || message.toolName === "agent_runs") &&
+    isRecord(message.details) &&
+    message.details.receivedResult === true
+    ? message.details
+    : undefined;
+}
+function completionDetails(entry: UnknownRecord): unknown {
+  if (entry.type === "custom_message" && entry.customType === "agent-completion") {
+    return entry.details;
+  }
+  return entry.type === "message" ? toolCompletion(entry.message) : undefined;
+}
+function addEntry(journal: Prefix, entry: UnknownRecord) {
+  const header = journal.entries.at(0);
+  const owner = header?.type === "session" ? header.id : undefined;
+  const details = typeof owner === "string" ? completionDetails(entry) : undefined;
+  if (
+    isRecord(details) &&
+    details.owner === owner &&
+    details.completed === true &&
+    typeof details.id === "string" &&
+    !journal.completions.has(details.id)
+  ) {
+    journal.completions.set(details.id, typeof entry.id === "string" ? entry.id : undefined);
+  }
+  journal.entries.push(entry);
+}
+function prefix(stat: fs.BigIntStats, cached: ReceiptIndex | undefined): Prefix {
+  return cached && nativeAppend(cached.stat, stat, cached.entries[0])
+    ? cached
+    : { end: 0, entries: [], completions: new Map() };
+}
+function index(file: string, observed: fs.BigIntStats): ReceiptIndex {
+  const cached = indexes.get(file);
+  if (cached?.stamp === journalStamp(observed)) {
+    return cached;
   }
   const fd = fs.openSync(file, "r");
-  let first = true;
-  let owned = false;
-  let found: string | undefined;
   try {
-    const stamp = journalStamp(fs.fstatSync(fd, { bigint: true }));
-    scanJournal(
+    const stat = fs.fstatSync(fd, { bigint: true });
+    const stamp = journalStamp(stat);
+    if (cached?.stamp === stamp) {
+      return cached;
+    }
+    const retained = prefix(stat, cached);
+    const appended: UnknownRecord[] = [];
+    const end = scanJournal(
       fd,
       receiptProjection,
       ({ value }) => {
-        if (first) {
-          first = false;
-          owned = value.type === "session" && value.id === owner;
-        } else if (owned && found === undefined && typeof value.id === "string" && matches(value)) {
-          found = value.id;
-        }
+        appended.push(value);
+      },
+      {
+        policy: "live",
+        requireNewline: true,
+        start: retained.end,
       },
-      { policy: "live", requireNewline: true },
     );
     if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp) {
       throw new Error("Native receipt journal changed while reading.");
     }
-    return found;
+    for (const entry of appended) {
+      addEntry(retained, entry);
+    }
+    const result = { ...retained, stamp, end, stat };
+    indexes.delete(file);
+    indexes.set(file, result);
+    if (indexes.size > 8) {
+      const oldest = indexes.keys().next().value;
+      if (oldest !== undefined) {
+        indexes.delete(oldest);
+      }
+    }
+    return result;
+  } catch (error) {
+    indexes.delete(file);
+    throw error;
   } finally {
     fs.closeSync(fd);
   }
 }
+
+/** Physical LF publication owns delivery, including when native memory is stale. */
+function owned(file: string | undefined, owner: string): ReceiptIndex | undefined {
+  const stat =
+    file === undefined ? undefined : fs.statSync(file, { bigint: true, throwIfNoEntry: false });
+  if (file === undefined || stat === undefined) {
+    return;
+  }
+  const journal = index(file, stat);
+  const header = journal.entries.at(0);
+  return header?.type === "session" && header.id === owner ? journal : undefined;
+}
+export function receiptId(
+  file: string | undefined,
+  owner: string,
+  matches: (entry: UnknownRecord) => boolean,
+): string | undefined {
+  const found = owned(file, owner)?.entries.find(
+    (entry) => entry.type !== "session" && matches(entry),
+  );
+  return typeof found?.id === "string" ? found.id : undefined;
+}
+/** Live read-only completion IDs by run; later appends extend this view.
+ * A matching entry without an ID is unpublished. Invalidations replace the view.
+ */
+export function completionReceipts(
+  file: string | undefined,
+  owner: string,
+): ReadonlyMap<string, string | undefined> {
+  return owned(file, owner)?.completions ?? new Map<string, string>();
+}