@fitchmultz/pi-subagents 0.52.4 → 0.52.6

package/src/agent/parking.ts

@@ -2,16 +2,26 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentSession, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { parkedSchema, type Launch, type Parked } from "./contracts.ts";
+import {
+  exitSchema,
+  parkedSchema,
+  readySchema,
+  wakeFailureSchema,
+  type Launch,
+  type Parked,
+} from "./contracts.ts";
 import { errorText, loadSDK, type WorkingState } from "./host.ts";
 import { conversation, latest, launchAt, list, read, runDirectory, write } from "./storage.ts";
-import { alive, shell, shells, wakeActor } from "./process.ts";
+import { actor as claimedActor, alive, shell, shells, wakeActor } from "./process.ts";
+import { DirectoryWatch, Wake } from "./wake.ts";
 import {
   isHistoryRequest,
+  isWakeRequest,
   PARK,
   PARKED_HISTORY,
   WAKE,
   type ParkRequest,
+  type WakeResult,
 } from "../shared/parking.ts";
 import { nativePeerId } from "../pi-intercom/session-targets.ts";
 import type { NativeHistory } from "../pi-intercom/last-message.ts";
@@ -147,6 +157,8 @@ export function parkedState(
 /** One actor generation's idle parking and exact restore; commands stay with the runner. */
 export class Parking {
   saved?: WorkingState;
+  /** Set before entering either native open, whose effects may outlive an exception. */
+  opened = false;
   private restored?: string;
   private since = 0;
   private leaf?: string | null;
@@ -172,6 +184,7 @@ export class Parking {
     const { sdk, launch } = this;
     const { openWorkingSession: restore } = sdk;
     const parked = parkedState(this.dir, launch, restore && sdk.readWorkingSession);
+    this.opened = true;
     if (!parked || !restore) {
       return sdk.SessionManager.open(launch.sessionFile, undefined, launch.cwd);
     }
@@ -328,6 +341,96 @@ async function history(runs: Runs | undefined, peer: string): Promise<NativeHist
   return state && { getBranch: () => branchOf(state) };
 }
 
+function unavailableCwd(cwd: string): string | undefined {
+  try {
+    if (!fs.statSync(cwd).isDirectory()) {
+      return `Saved working directory ${cwd} is unavailable: not a directory.`;
+    }
+    fs.accessSync(cwd, fs.constants.X_OK);
+  } catch (error) {
+    return `Saved working directory ${cwd} is unavailable: ${errorText(error)}.`;
+  }
+  return undefined;
+}
+
+function exitedWake(
+  dir: string,
+  identity: NonNullable<ReturnType<typeof claimedActor>>,
+  legacy: boolean,
+): string | undefined {
+  const exit = read(path.join(dir, `exit-${identity.token}.json`), exitSchema);
+  if (!exit && alive(identity)) {
+    return undefined;
+  }
+  const failure = read(path.join(dir, `wake-failure-${identity.token}.json`), wakeFailureSchema);
+  return (
+    failure?.reason ??
+    `Actor exited before ${legacy ? "readiness" : "intercom registration"} (code ${exit?.code ?? "unknown"}, signal ${exit?.signal ?? "unknown"}). See ${path.join(dir, "runner.log")}.`
+  );
+}
+
+/** A spawned actor is only requested until its own readiness or exit is observed. */
+async function awaitWake(
+  base: string,
+  launch: Launch,
+  signal: AbortSignal,
+  legacy: boolean,
+): Promise<void> {
+  const dir = conversation(base, launch);
+  const identity = claimedActor(base, launch);
+  if (!identity) {
+    throw new Error("The wake returned without an observable actor claim.");
+  }
+  const wake = new Wake();
+  const watch = new DirectoryWatch(dir, () => true, wake.raise);
+  try {
+    for (;;) {
+      signal.throwIfAborted();
+      wake.take();
+      watch.ensure();
+      if (
+        legacy &&
+        read(path.join(dir, "ready.json"), readySchema)?.token === identity.token &&
+        !fs.existsSync(path.join(dir, "parked.json"))
+      ) {
+        return;
+      }
+      const failure = exitedWake(dir, identity, legacy);
+      if (failure !== undefined) {
+        throw new Error(failure);
+      }
+      // DirectoryWatch reconciles dropped hints without imposing a deadline on native startup.
+      // oxlint-disable-next-line no-await-in-loop
+      await wake.sleep(200);
+    }
+  } finally {
+    watch.close();
+  }
+}
+
+function wakeFailed(
+  current: Runs | undefined,
+  launch: Launch | undefined,
+  error: unknown,
+): WakeResult {
+  let reason = errorText(error);
+  const unavailable = launch && unavailableCwd(launch.cwd);
+  if (unavailable !== undefined) {
+    reason += ` ${unavailable}`;
+  }
+  if (current && launch) {
+    try {
+      write(path.join(conversation(current.base, launch), "wake-failure.json"), {
+        at: Date.now(),
+        reason,
+      });
+    } catch (recordError) {
+      reason += ` Wake failure could not be recorded: ${errorText(recordError)}.`;
+    }
+  }
+  return { status: "failed", reason };
+}
+
 /**
  * Wakes this owner's parked children for broker input and reads their saved history.
  * `runs` is undefined while this session owns no children.
@@ -337,17 +440,50 @@ export function serveParked(
   runs: () => Runs | undefined,
   signal: AbortSignal,
 ): void {
-  pi.events.on(WAKE, (peer) => {
-    // On failure, retained input stays queued at the broker until the next main registration.
-    (async () => {
-      const current = runs();
-      const launch = ownedRun(current, peer);
-      if (current && launch) {
-        await wakeActor(current.base, launch, signal);
+  const pending = new Map<string, Promise<WakeResult>>();
+  const attempt = async (peer: string, registered?: AbortSignal): Promise<WakeResult> => {
+    let current: Runs | undefined;
+    let launch: Launch | undefined;
+    const cancelled = registered ? AbortSignal.any([signal, registered]) : signal;
+    try {
+      current = runs();
+      launch = ownedRun(current, peer);
+      if (!current || !launch) {
+        throw new Error("No active agent runtime owns this parked child.");
       }
-    })().catch((error: unknown) => {
-      console.error(`Agent wake: ${errorText(error)}`);
-    });
+      await wakeActor(current.base, launch, cancelled);
+      await awaitWake(current.base, launch, cancelled, registered === undefined);
+      return { status: "requested" };
+    } catch (error) {
+      if (registered?.aborted === true) {
+        return { status: "requested" };
+      }
+      return wakeFailed(current, launch, error);
+    }
+  };
+  pi.events.on(WAKE, (request) => {
+    const peer = isWakeRequest(request) ? request.peer : request;
+    if (typeof peer !== "string") {
+      return;
+    }
+    // Serialize wake requests; a successful in-flight wake already serves queued requests.
+    const previous = pending.get(peer);
+    const registered = isWakeRequest(request) ? request.signal : undefined;
+    const result = previous
+      ? previous.then((outcome) =>
+          outcome.status === "requested" ? outcome : attempt(peer, registered),
+        )
+      : attempt(peer, registered);
+    pending.set(peer, result);
+    const clear = () => {
+      if (pending.get(peer) === result) {
+        pending.delete(peer);
+      }
+    };
+    void result.then(clear, clear);
+    if (isWakeRequest(request)) {
+      request.reply(result);
+    }
   });
   pi.events.on(PARKED_HISTORY, (request) => {
     if (isHistoryRequest(request)) {

package/src/agent/process.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
@@ -17,10 +17,11 @@ import {
   attachmentSchema,
   parkedSchema,
   processSchema,
+  wakeFailureSchema,
   type Launch,
   type ProcessIdentity,
 } from "./contracts.ts";
-import { conversation, enqueue, launchAt, list, read, write } from "./storage.ts";
+import { conversation, enqueue, read, write } from "./storage.ts";
 import { errorText } from "./host.ts";
 
 /** Darwin's in-memory publication bound; Android records carry their own native clock. */
@@ -149,34 +150,74 @@ function childEnvironment(launch: Launch): NodeJS.ProcessEnv {
     PI_INTERCOM_PARENT_SESSION_ID: launch.owner,
   });
 }
-function spawnActor(base: string, launch: Launch, token: string): void {
+interface LaunchClaim {
+  readonly spawned: () => void;
+  readonly release: () => void;
+}
+function saveSpawnFailure(dir: string, error: Error): Error {
+  try {
+    write(path.join(dir, "spawn-error.json"), { error: error.message });
+    return error;
+  } catch (failure) {
+    return Object.assign(
+      new Error(`${error.message}; could not save the spawn diagnostic: ${errorText(failure)}`, {
+        cause: error,
+      }),
+      "code" in error ? { code: error.code } : {},
+    );
+  }
+}
+async function spawnActor(
+  base: string,
+  launch: Launch,
+  token: string,
+  claim: LaunchClaim,
+): Promise<void> {
   const dir = conversation(base, launch);
-  const log = fs.openSync(path.join(dir, "runner.log"), "a", 0o600);
-  const runner = fileURLToPath(
-    new URL(import.meta.url.endsWith(".ts") ? "./runner.ts" : "./runner.js", import.meta.url),
-  );
-  let child;
+  let child: ChildProcess;
+  let spawnError: Promise<Error> | undefined;
   try {
-    child = spawn(process.execPath, [runner, base, launch.rootId, token, launch.id], {
-      cwd: launch.cwd,
-      env: childEnvironment(launch),
-      detached: true,
-      stdio: ["ignore", log, log],
-    });
-  } finally {
-    fs.closeSync(log);
+    const log = fs.openSync(path.join(dir, "runner.log"), "a", 0o600);
+    try {
+      const runner = fileURLToPath(
+        new URL(import.meta.url.endsWith(".ts") ? "./runner.ts" : "./runner.js", import.meta.url),
+      );
+      child = spawn(process.execPath, [runner, base, launch.rootId, token, launch.id], {
+        cwd: launch.cwd,
+        env: childEnvironment(launch),
+        detached: true,
+        stdio: ["ignore", log, log],
+      });
+      if (child.pid === undefined) {
+        spawnError = new Promise((resolve) => {
+          child.once("error", (error) => resolve(saveSpawnFailure(dir, error)));
+        });
+        claim.release();
+      } else {
+        claim.spawned();
+        child.on("error", (error) => {
+          write(path.join(dir, "spawn-error.json"), { error: error.message });
+        });
+      }
+    } finally {
+      fs.closeSync(log);
+    }
+  } catch (error) {
+    claim.release();
+    throw error;
+  }
+  if (child.pid === undefined && spawnError) {
+    throw await spawnError;
+  }
+  if (child.pid === undefined) {
+    claim.spawned();
+    throw new Error("Actor spawn outcome is ambiguous.");
   }
-  child.on("error", (error) => {
-    write(path.join(dir, "spawn-error.json"), { error: error.message });
-  });
   child.on("exit", (code, signal) => {
     write(path.join(dir, `exit-${token}.json`), { pid: child.pid, code, signal, at: Date.now() });
     trySignalChildTree(child, "SIGKILL");
   });
   child.unref();
-  if (child.pid === undefined) {
-    throw new Error("Actor was not spawned; retained launch claim requires inspection.");
-  }
   write(path.join(dir, "actor.lock", "process.json"), {
     pid: child.pid,
     identity: readChildProcessIdentity(child.pid) ?? "unverified",
@@ -205,6 +246,50 @@ async function awaitStopping(
     }
   }
 }
+function releaseClaim(
+  lock: string,
+  identity: fs.Stats | undefined,
+  token: string | undefined,
+): void {
+  try {
+    const current = fs.lstatSync(lock, { throwIfNoEntry: false });
+    if (current && identity && current.dev === identity.dev && current.ino === identity.ino) {
+      const file = path.join(lock, "claim.json");
+      const claim = read(file, processSchema);
+      if (claim === undefined || claim.token === token) {
+        fs.rmSync(file, { force: true });
+        fs.rmdirSync(lock);
+      }
+    }
+  } catch {
+    // Keep the original failure; an unremovable claim remains safely ambiguous.
+  }
+}
+async function launchClaimedActor(base: string, launch: Launch, lock: string): Promise<void> {
+  let identity: fs.Stats | undefined;
+  let token: string | undefined;
+  let state: "claimed" | "spawned" | "released" = "claimed";
+  const claim: LaunchClaim = {
+    spawned: () => {
+      state = "spawned";
+    },
+    release: () => {
+      if (state === "claimed") {
+        state = "released";
+        releaseClaim(lock, identity, token);
+      }
+    },
+  };
+  try {
+    identity = fs.lstatSync(lock);
+    token = randomUUID();
+    write(path.join(lock, "claim.json"), { ...ownIdentity(), token });
+    await spawnActor(base, launch, token, claim);
+  } catch (error) {
+    claim.release();
+    throw error;
+  }
+}
 export async function ensureActor(
   base: string,
   launch: Launch,
@@ -237,16 +322,34 @@ export async function ensureActor(
     }
     throw error;
   }
-  const token = randomUUID();
-  write(path.join(lock, "claim.json"), { ...ownIdentity(), token });
-  spawnActor(base, launch, token);
+  await launchClaimedActor(base, launch, lock);
+}
+/** A failed restore can hand the old cut forward only before native open and after death. */
+function failedBeforeOpenToken(
+  dir: string,
+  exited: OwnedProcess,
+  current: OwnedProcess | undefined,
+): string | undefined {
+  const failure = read(path.join(dir, `wake-failure-${exited.token}.json`), wakeFailureSchema);
+  if (
+    current?.token === exited.token &&
+    !alive(current) &&
+    failure?.beforeOpen?.actorToken === exited.token
+  ) {
+    return failure.beforeOpen.parkedToken;
+  }
+  return undefined;
 }
 /** 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.
+  if (
+    exited &&
+    parked &&
+    parked.token !== exited.token &&
+    failedBeforeOpenToken(dir, exited, actor(base, launch)) !== parked.token
+  ) {
     throw new Error(
       "Parked working state belongs to another actor generation; nothing was reopened.",
     );
@@ -354,45 +457,6 @@ export function requestStop(
   });
   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 shell(file: string, token: string): OwnedProcess | undefined {
   const identity = published(file, read(file, processSchema));
   if (identity && identity.token !== token) {

package/src/agent/receipts.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { scanJournal } from "../shared/journal-frames.ts";
 import { journalStamp, nativeAppend } from "../shared/native-journal.ts";
 import type { Projection } from "../shared/json-projection.ts";
@@ -157,6 +158,24 @@ function owned(file: string | undefined, owner: string): ReceiptIndex | undefine
   const header = journal.entries.at(0);
   return header?.type === "session" && header.id === owner ? journal : undefined;
 }
+/** Without a session file (`--no-session`), Pi's append-only memory is the whole native transcript. */
+function remembered(
+  manager: ExtensionContext["sessionManager"],
+  owner: string,
+): Prefix | undefined {
+  const header = manager.getHeader();
+  if (header?.id !== owner) {
+    return;
+  }
+  const journal: Prefix = { end: 0, entries: [], completions: new Map() };
+  // Index the same record frames the physical journal scan accepts.
+  for (const entry of [header, ...manager.getEntries()]) {
+    if (isRecord(entry)) {
+      addEntry(journal, entry);
+    }
+  }
+  return journal;
+}
 export function receiptId(
   file: string | undefined,
   owner: string,
@@ -167,12 +186,14 @@ export function receiptId(
   );
   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.
+/** Completion IDs by run from the native transcript: the session file when Pi persists one,
+ * otherwise Pi's in-memory entries. A matching entry without an ID is unpublished.
  */
 export function completionReceipts(
-  file: string | undefined,
+  manager: ExtensionContext["sessionManager"],
   owner: string,
 ): ReadonlyMap<string, string | undefined> {
-  return owned(file, owner)?.completions ?? new Map<string, string>();
+  const file = manager.getSessionFile();
+  const journal = file === undefined ? remembered(manager, owner) : owned(file, owner);
+  return journal?.completions ?? new Map<string, string>();
 }

package/src/agent/runner.ts

@@ -2,7 +2,13 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import { commandSchema, type Command, type Launch, type Result } from "./contracts.ts";
+import {
+  commandSchema,
+  parkedSchema,
+  type Command,
+  type Launch,
+  type Result,
+} from "./contracts.ts";
 import { launchAt, missing, read, runDirectory, write } from "./storage.ts";
 import { ownIdentity, ParentCheck, shells, signalProcess } from "./process.ts";
 import { errorText, loadSDK } from "./host.ts";
@@ -374,7 +380,7 @@ class Actor {
     }
     return this.parking;
   }
-  private failure(error: unknown): void {
+  private failure(error: unknown, unopened?: string): void {
     const launch = this.current ?? this.initial;
     const result: Result = {
       id: launch.id,
@@ -384,6 +390,16 @@ class Actor {
       error: errorText(error),
     };
     const directory = runDirectory(this.base, launch.id);
+    if (fs.existsSync(path.join(this.dir, "parked.json"))) {
+      const parked = read(path.join(this.dir, "parked.json"), parkedSchema);
+      write(path.join(this.dir, `wake-failure-${this.token}.json`), {
+        at: Date.now(),
+        reason: errorText(error),
+        ...(unopened !== undefined && parked?.token === unopened
+          ? { beforeOpen: { actorToken: this.token, parkedToken: unopened } }
+          : {}),
+      });
+    }
     if (!fs.existsSync(path.join(directory, "result.json"))) {
       fs.writeFileSync(path.join(directory, "output.txt"), "", { mode: 0o600 });
       write(path.join(directory, "result.json"), result);
@@ -449,17 +465,21 @@ class Actor {
     parked.adopt();
   }
   async serve(): Promise<void> {
-    const sdk = await loadSDK(this.initial.sdk);
-    const parked = new Parking(this.base, this.initial, this.token, sdk);
     let runtime: Runtime | undefined;
+    let parked: Parking | undefined;
+    let parkedToken: string | undefined;
     try {
+      // Capture the old generation before SDK import or any native working-state operation.
+      parkedToken = read(path.join(this.dir, "parked.json"), parkedSchema)?.token;
+      const sdk = await loadSDK(this.initial.sdk);
+      parked = new Parking(this.base, this.initial, this.token, sdk);
       runtime = await this.start(sdk, parked);
       process.on("SIGTERM", this.stop);
       process.on("SIGINT", this.stop);
       await this.admitCommands(runtime, parked);
       await this.active;
     } catch (error) {
-      this.failure(error);
+      this.failure(error, parked?.opened === true ? undefined : parkedToken);
     } finally {
       await this.finish(runtime);
     }

package/src/agent/shutdown.ts

@@ -0,0 +1,50 @@
+import { setTimeout as delay } from "node:timers/promises";
+import type { ProcessIdentity } from "./contracts.ts";
+import { errorText } from "./host.ts";
+import { alive, requestStop, signalProcess } from "./process.ts";
+import { launchAt, list } from "./storage.ts";
+
+export async function stopChildren(
+  base: string,
+  owner: string,
+  report: (message: string) => void,
+): Promise<void> {
+  const roots = new Set<string>();
+  const targets: ProcessIdentity[] = [];
+  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) => {
+            report(`Child shutdown ${id}: ${errorText(error)}`);
+          }).targets,
+        );
+      }
+    } catch (error) {
+      report(`Child shutdown ${id}: ${errorText(error)}`);
+    }
+  }
+  await waitForExit(targets, 3000);
+  for (const target of targets) {
+    try {
+      signalProcess(target, "SIGKILL");
+    } catch (error) {
+      report(`Child shutdown ${target.pid}: ${errorText(error)}`);
+    }
+  }
+  await waitForExit(targets, 1000);
+  if (targets.some(alive)) {
+    report("Child shutdown could not confirm every owned process exit.");
+  }
+}
+
+async function waitForExit(targets: readonly ProcessIdentity[], 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);
+  }
+}

package/src/agent/view.ts

@@ -8,6 +8,7 @@ import {
   commandSchema,
   exitSchema,
   successorSchema,
+  wakeFailureSchema,
   type Launch,
   type Result,
 } from "./contracts.ts";
@@ -47,6 +48,7 @@ interface RunSummary {
   result?: Pick<Result, "status" | "endedAt" | "error">;
   nativeReceipt: string | null;
   process: ReturnType<typeof processView>;
+  lastWakeFailure?: { at: number; reason: string };
   sessionId: string;
   sessionFile: string;
   outputFile: string;
@@ -175,6 +177,10 @@ function metadata(
     result,
     nativeReceipt: options.ctx ? (published(options.ctx, launch) ?? null) : null,
     process,
+    lastWakeFailure: read(
+      path.join(conversation(base, launch), "wake-failure.json"),
+      wakeFailureSchema,
+    ),
     sessionId: launch.sessionId,
     sessionFile: launch.sessionFile,
     outputFile,
@@ -275,6 +281,9 @@ function resultText(details: RunView): string {
     `Agent run ${details.id}: ${details.status}; admission ${details.admission}; process ${details.process.live ? "live" : "not observed live"}.`,
     receiptText(details),
     exitText(details),
+    details.lastWakeFailure
+      ? `Last wake failure at ${new Date(details.lastWakeFailure.at).toISOString()}: ${details.lastWakeFailure.reason} Retained intercom messages may still arrive after a later wake.`
+      : "",
     `Guidance (latest 20):\n${guidance.length > 0 ? guidance : "  none"}`,
     "Guidance states: pending = not yet admitted; accepted = native queue admission, not journal publication or model consumption; stale = rejected, no new work was started (retry the entire prompt as a continuation).",
     details.result?.error ?? "",