@fitchmultz/pi-subagents 0.52.4 → 0.52.5

package/dist/shared/parking.js

@@ -7,6 +7,12 @@ export const PARKED_HISTORY = "pi-subagents:parked-history";
 export function isParkRequest(value) {
     return isRecord(value) && typeof value.park === "boolean" && typeof value.reply === "function";
 }
+export function isWakeRequest(value) {
+    return (isRecord(value) &&
+        typeof value.peer === "string" &&
+        typeof value.reply === "function" &&
+        (value.signal === undefined || value.signal instanceof AbortSignal));
+}
 export function isHistoryRequest(value) {
     return isRecord(value) && typeof value.peer === "string" && typeof value.reply === "function";
 }

package/docs/development.md

@@ -1,5 +1,7 @@
 # Development
 
+Node.js 24.21 or newer is required.
+
 The supported Intercom client's package export uses emitted declarations for consumers.
 The repository's native `development` type condition points at its TypeScript source so
 cold lint and type checks do not require a prior build. Packed-consumer checks compile

package/docs/intercom.md

@@ -4,6 +4,13 @@
 child-only supervisor tool, peer overlay, topic registry, or separate extension
 to install. Ordinary and delegated sessions use the same messaging tool.
 
+Background failures appear as native notifications when a UI is active and on
+stderr in print or JSON mode, including during headless shutdown. In UI sessions,
+failures during shutdown or after the UI context is unavailable are recorded in
+`intercom/background-errors.log` under `PI_CODING_AGENT_DIR` (normally `~/.pi/agent`).
+If that directory is not writable, the fallback cannot record them. Repeated
+identical failures are reported once until the affected operation recovers.
+
 ## Discovery and groups
 
 ```js
@@ -139,6 +146,13 @@ active or sole pending ask when unambiguous; otherwise specify `replyTo` and the
 intended sender. Inspect `pending` for the exact correlation rather than guessing
 from text.
 
+Messages accepted for a parked child remain queued until it returns. If its
+owner reports a failed wake, a waiting ask returns the failure and says that the
+accepted question may still arrive later. Check the child before resending to
+avoid a duplicate question. A later active message requests another wake. Inspect
+the child's run for its last recorded wake failure. With older brokers or
+clients that cannot report wake outcomes, a waiting ask keeps its usual timeout.
+
 This ordinary request/reply mechanism does not recreate the retired durable
 supervisor approval/revival workflow. An expired wait is not an answered question
 or a completed delegated run.

package/docs/performance.md

@@ -144,7 +144,7 @@ switch request through an immediate successful `get_state` response changed from
 it now pays for cold receipt indexing. This is a change to when recovery work
 runs, not an installed macOS or general delegation-latency claim.
 
-The [issue 248 evidence](evidence/issue-248/README.md) includes both waits,
+The [issue 248 evidence](evidence/issue-248/report.md) includes both waits,
 switch-to-first-tool measurements, ranges, profiler results, exact runtime and
 build identities, reproducible commands, and retained synthetic RPC transcripts.
 
@@ -167,7 +167,7 @@ after `session_start`, chiefly the intercom broker and owner attachment. In two
 official-host 40 s floor/`0b6da9b` pairs, the later windows of about 10 s each
 stayed within 1.1 ms of the paired floor. There is no fork long run, and this
 is not an indefinite-idle bound. The
-[issue 238 evidence](evidence/issue-238-idle/README.md) has the samples, host
+[issue 238 evidence](evidence/issue-238-idle/report.md) has the samples, host
 hashes, native causal chain and limits.
 
 ### Idle parking shell records

package/docs/reference.md

@@ -106,7 +106,12 @@ not wake it and report `publication_unavailable`. A
 normal message, ask or continuation restores the exact saved state into a new
 process, which then receives retained messages in order. If the final save
 fails, the child records `park-failed.json` and nothing restarts implicitly;
-retained messages stay queued and continuing reports the failure. Official Pi
+retained messages stay queued and continuing reports the failure. A failed wake
+is recorded as the run's `lastWakeFailure` in `agent_runs list` and `inspect`.
+This is a historical failure, not a claim about the child's current state. A
+later active message requests another wake. The saved working directory must be
+available; no other directory is substituted. A pre-existing ambiguous actor
+claim still requires inspection and is not removed automatically. Official Pi
 keeps idle children resident. Parent exit or session replacement stops its actors and verified owned
 native shells, allowing native abort a short grace period before escalation.
 Actors also watch for parent death, including a hard kill. Ordinary extension
@@ -227,10 +232,13 @@ New-runtime backlogs are sorted by completion time, then launch time and ID—no
 directory order. A later scan cannot reorder messages already admitted to Pi.
 
 Admission is still not publication or model consumption. Native physical receipts
-suppress redelivery across reload/resume, and dropped queues can recover. Receipt
-polling reuses unchanged verified journal metadata; changed files validate the
-committed prefix before parsing appended records. Replacement, truncation, changed
-prefixes, malformed records, and missing final newlines do not fabricate receipts.
+suppress redelivery across reload/resume, and dropped queues can recover. A
+`--no-session` parent has no session file, so Pi's in-memory transcript holds its
+receipts for the life of that process; such a receipt never removes a retained
+legacy result file. Receipt polling reuses unchanged verified
+journal metadata; changed files validate the committed prefix before parsing
+appended records. Replacement, truncation, changed prefixes, malformed records,
+and missing final newlines do not fabricate receipts.
 Completion delivery appends context; it does not replace prior prompts, tools,
 model settings, or the active conversation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.4",
+  "version": "0.52.5",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/src/agent/completion-watches.ts

@@ -0,0 +1,73 @@
+import * as path from "node:path";
+import type { BackgroundReporter } from "../shared/background-reporting.ts";
+import { errorMessage } from "../shared/unknown.ts";
+import { DirectoryWatch, type WatchState } from "./wake.ts";
+
+/** Owns change hints for completion inputs and reports failures without losing polling. */
+export class CompletionWatches {
+  private readonly watches = new Map<string, DirectoryWatch>();
+  private awaited: ReadonlySet<string> = new Set();
+  private readonly reporter: BackgroundReporter;
+  private readonly wake: () => void;
+  constructor(reporter: BackgroundReporter, wake: () => void) {
+    this.reporter = reporter;
+    this.wake = wake;
+  }
+
+  update(
+    base: string,
+    legacy: readonly string[],
+    awaited: ReadonlySet<string>,
+  ): "poll" | "rescan" | "hints" {
+    this.awaited = awaited;
+    const directories = [
+      ...new Set([base, ...legacy, ...[...awaited].map((file) => path.dirname(file))]),
+    ];
+    for (const [directory, watch] of this.watches) {
+      if (!directories.includes(directory)) {
+        watch.close();
+        this.watches.delete(directory);
+        this.reporter.recover(`watch:${directory}`);
+      }
+    }
+    const states = directories.map((directory): [string, WatchState] => [
+      directory,
+      this.ensure(directory, directory === base || legacy.includes(directory)),
+    ]);
+    if (states.some(([directory, state]) => state === "unwatched" && !legacy.includes(directory))) {
+      return "poll";
+    }
+    return states.some(([, state]) => state === "armed") ? "rescan" : "hints";
+  }
+
+  private ensure(directory: string, every: boolean): WatchState {
+    let watch = this.watches.get(directory);
+    if (watch === undefined) {
+      watch = new DirectoryWatch(
+        directory,
+        (file) => every || file === null || this.awaited.has(path.join(directory, file)),
+        this.wake,
+      );
+      this.watches.set(directory, watch);
+    }
+    const owner = `watch:${directory}`;
+    try {
+      const state = watch.ensure();
+      this.reporter.recover(owner);
+      return state;
+    } catch (error) {
+      watch.close();
+      this.reporter.report(owner, `Agent directory watch ${directory}: ${errorMessage(error)}`);
+      return "unwatched";
+    }
+  }
+
+  close(): void {
+    for (const [directory, watch] of this.watches) {
+      watch.close();
+      this.reporter.recover(`watch:${directory}`);
+    }
+    this.watches.clear();
+    this.awaited = new Set();
+  }
+}

package/src/agent/contracts.ts

@@ -113,6 +113,17 @@ export const parkedSchema = Type.Object({
   leafId: Type.Union([Type.String(), Type.Null()]),
 });
 export type Parked = Static<typeof parkedSchema>;
+export const wakeFailureSchema = Type.Object({
+  at: Type.Number(),
+  reason: Type.String(),
+  beforeOpen: Type.Optional(
+    Type.Object({
+      actorToken: Type.String(),
+      parkedToken: Type.String(),
+    }),
+  ),
+});
+export const readySchema = Type.Object({ token: Type.String() });
 export const exitSchema = Type.Object({
   pid: Type.Integer(),
   code: Type.Union([Type.Integer(), Type.Null()]),

package/src/agent/host.ts

@@ -9,6 +9,12 @@ import { readIntercomLineage } from "../pi-intercom/identity.ts";
 
 export { errorMessage as errorText } from "../shared/unknown.ts";
 
+/** A launcher may still own children while handing off or replacing a worker. */
+export function retainsChildren(event: object): boolean {
+  const disposition: unknown = Reflect.get(event, "disposition");
+  return disposition === "handoff" || disposition === "provisional";
+}
+
 /** Fork-only exact native working state; official Pi lacks it, so its children stay resident. */
 interface LocalWorkingState {
   readonly header: { readonly id: string };

package/src/agent/index.ts

@@ -15,9 +15,9 @@ import {
   parkFailure,
   requestStop,
   signalProcess,
-  stopChildren,
 } from "./process.ts";
-import { isChild, errorText, rememberSDK } from "./host.ts";
+import { stopChildren } from "./shutdown.ts";
+import { isChild, errorText, rememberSDK, retainsChildren } from "./host.ts";
 import { serveParked } from "./parking.ts";
 import {
   resultSchema,
@@ -45,23 +45,20 @@ import {
 import { notifications, deliver, settle } from "./notifications.ts";
 import { prepareLaunch } from "./launch.ts";
 import { renderReceipt, renderInventory, renderInspection } from "./view.ts";
-import { legacyDirectory, legacyNotifications } from "./legacy.ts";
-import { DirectoryWatch, pathStamp, type WatchState } from "./wake.ts";
+import { legacyDirectory, reconcileLegacy } from "./legacy.ts";
+import { pathStamp } from "./wake.ts";
+import { CompletionWatches } from "./completion-watches.ts";
 import { savedContinuation } from "./saved.ts";
 import { executionCwd } from "./cwd.ts";
 import { getPiAgentDir } from "../pi-intercom/agent-dir.ts";
 import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.ts";
+import { BackgroundReporter } from "../shared/background-reporting.ts";
 
 /** Native fork lifetime owner (`ctx.managedHost`); read structurally so official Pi stays supported. */
 interface ManagedHost {
   readonly owner: { readonly pid: number };
   readonly ready: Promise<boolean>;
 }
-/** `handoff` and `provisional` mean another worker under the same launcher may still own these children. */
-function retainsChildren(event: object): boolean {
-  const disposition: unknown = Reflect.get(event, "disposition");
-  return disposition === "handoff" || disposition === "provisional";
-}
 function managedHost(context: ExtensionContext): ManagedHost | undefined {
   const host: unknown = Reflect.get(context, "managedHost");
   if (typeof host !== "object" || host === null) {
@@ -86,6 +83,7 @@ function legacyInput(): string[] {
 }
 class AgentRuntime {
   private ctx?: ExtensionContext;
+  private readonly reporter = new BackgroundReporter(() => this.ctx);
   // A managed launcher owns children across worker replacement; otherwise this process does.
   private host?: ManagedHost;
   private accepted = false;
@@ -96,7 +94,7 @@ class AgentRuntime {
   private timer?: NodeJS.Timeout;
   private woken?: NodeJS.Immediate;
   // Change hints for the owner directory, legacy results and every awaited canonical file.
-  private readonly watches = new Map<string, DirectoryWatch>();
+  private readonly watches: CompletionWatches;
   private awaited: ReadonlySet<string> = new Set();
   // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
   private observed = new Map<string, string>();
@@ -109,6 +107,7 @@ class AgentRuntime {
   private readonly pi: ExtensionAPI;
   constructor(pi: ExtensionAPI) {
     this.pi = pi;
+    this.watches = new CompletionWatches(this.reporter, this.wake);
   }
   private checkMain(): void {
     if (isChild()) {
@@ -143,19 +142,19 @@ class AgentRuntime {
     try {
       const { notices, awaited } = notifications(this.ctx, this.base, this.owner);
       this.awaited = awaited;
-      try {
-        notices.unshift(...legacyNotifications(this.ctx));
-      } catch (error) {
-        console.error(`Legacy completion reconciliation: ${errorText(error)}`);
-      }
+      notices.unshift(...reconcileLegacy(this.ctx, this.reporter));
       deliver(this.pi, this.ctx, notices);
+      this.reporter.recover("completion-scan");
     } catch (error) {
       reconciled = false;
-      console.error(`Agent completion reconciliation: ${errorText(error)}`);
+      this.reporter.report(
+        "completion-scan",
+        `Agent completion reconciliation: ${errorText(error)}`,
+      );
     }
     // Newly awaited files were absent when read, or are rechecked once by the probe.
     this.observed = new Map(inputs().map((file) => [file, before.get(file) ?? ""]));
-    const next = this.watch();
+    const next = this.watches.update(this.base, legacyInput(), this.awaited);
     if (!reconciled || next === "poll") {
       this.timer = setTimeout(this.scan, 200).unref();
     } else if (next === "rescan") {
@@ -163,49 +162,17 @@ class AgentRuntime {
       this.wake();
     }
   };
-  /** Watches every directory that can publish an awaited input; legacy results may never exist. */
-  private watch(): "poll" | "rescan" | "hints" {
-    const legacy = legacyInput();
-    const directories = [
-      ...new Set([this.base, ...legacy, ...[...this.awaited].map((file) => path.dirname(file))]),
-    ];
-    for (const [directory, watch] of this.watches) {
-      if (!directories.includes(directory)) {
-        watch.close();
-        this.watches.delete(directory);
-      }
-    }
-    const states = directories.map((directory): [string, WatchState] => {
-      let watch = this.watches.get(directory);
-      if (watch === undefined) {
-        const every = directory === this.base || legacy.includes(directory);
-        watch = new DirectoryWatch(
-          directory,
-          (file) => every || file === null || this.awaited.has(path.join(directory, file)),
-          this.wake,
-        );
-        this.watches.set(directory, watch);
-      }
-      return [directory, watch.ensure()];
-    });
-    if (states.some(([directory, state]) => state === "unwatched" && !legacy.includes(directory))) {
-      return "poll";
-    }
-    return states.some(([, state]) => state === "armed") ? "rescan" : "hints";
-  }
   private unwatch(): void {
     clearTimeout(this.timer);
     clearInterval(this.probe);
     this.observed.clear();
     clearImmediate(this.woken);
     this.woken = undefined;
-    for (const watch of this.watches.values()) {
-      watch.close();
-    }
-    this.watches.clear();
+    this.watches.close();
     this.awaited = new Set();
   }
   private start(context: ExtensionContext): Promise<void> | undefined {
+    this.reporter.start();
     this.host = managedHost(context);
     if (this.host === undefined || this.accepted || this.child) {
       this.reset = this.reset.then(() => this.attach(context));
@@ -224,7 +191,7 @@ class AgentRuntime {
         }
       })
       .catch((error: unknown) => {
-        console.error(`Agent runtime attachment: ${errorText(error)}`);
+        this.reporter.report(undefined, `Agent runtime attachment: ${errorText(error)}`);
       });
     return undefined;
   }
@@ -254,6 +221,7 @@ class AgentRuntime {
     this.probe = setInterval(this.recover, 1000).unref();
   }
   private async dispose(retain: boolean): Promise<void> {
+    this.reporter.shutdown();
     this.closing = true;
     this.unwatch();
     this.shutdown.abort();
@@ -267,7 +235,9 @@ class AgentRuntime {
           generation: attachment.generation,
           attached: false,
         });
-        await stopChildren(this.base, this.owner);
+        await stopChildren(this.base, this.owner, (message) =>
+          this.reporter.report(undefined, message),
+        );
       }
     }
     this.ctx = undefined;
@@ -296,7 +266,7 @@ class AgentRuntime {
           signalProcess(target, "SIGKILL");
         });
       } catch (error) {
-        console.error(`Agent stop escalation: ${errorText(error)}`);
+        this.reporter.report(undefined, `Agent stop escalation ${launch.id}: ${errorText(error)}`);
       }
     }, 3000);
     escalation.unref();

package/src/agent/legacy.ts

@@ -1,5 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { errorText } from "./host.ts";
+import type { BackgroundReporter } from "../shared/background-reporting.ts";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { journalStamp } from "../shared/native-journal.ts";
 import { receiptId } from "./receipts.ts";
@@ -7,7 +9,6 @@ import { resolveTempRootDir } from "../shared/types.ts";
 import { isRecord } from "../shared/unknown.ts";
 import { release, isHeld, type Completion } from "./notifications.ts";
 import { missing } from "./storage.ts";
-import { errorText } from "./host.ts";
 
 interface LegacyInput {
   file: string;
@@ -123,18 +124,24 @@ function receipt(body: unknown, input: LegacyInput): boolean {
   }
   return body.type === "message" && legacyWait(body.message, input);
 }
-function published(ctx: ExtensionContext, input: LegacyInput): boolean {
-  return (
-    receiptId(ctx.sessionManager.getSessionFile(), input.owner, (body) => receipt(body, input)) !==
-    undefined
-  );
+/** Where Pi recorded this input's receipt: its session file, or memory under `--no-session`. */
+function published(ctx: ExtensionContext, input: LegacyInput): "file" | "memory" | undefined {
+  const file = ctx.sessionManager.getSessionFile();
+  const matches = (body: unknown) => receipt(body, input);
+  if (file === undefined) {
+    return ctx.sessionManager.getEntries().some(matches) ? "memory" : undefined;
+  }
+  return receiptId(file, input.owner, matches) === undefined ? undefined : "file";
 }
 function notification(ctx: ExtensionContext, input: LegacyInput): Completion | undefined {
   const identity = `legacy:${input.id}:${input.key}`;
-  if (published(ctx, input)) {
+  const where = published(ctx, input);
+  if (where !== undefined) {
     release(input.owner, identity);
-    // Retire only the unchanged recovery input whose actual native receipt exists.
+    // Retire only an unchanged recovery input whose receipt is LF-published in the session file.
+    // An in-memory receipt stops redelivery but never removes the saved input.
     if (
+      where === "file" &&
       journalStamp(fs.lstatSync(input.file, { bigint: true })) === input.stamp &&
       fs.readFileSync(input.file, "utf8") === input.raw
     ) {
@@ -161,12 +168,15 @@ function legacyNotice(
   ctx: ExtensionContext,
   file: string,
   scan: LegacyScan,
+  report: (file: string, error?: unknown) => void,
 ): Completion | undefined {
   try {
     const input = legacyInput(file, scan);
-    return input ? notification(ctx, input) : undefined;
+    const result = input ? notification(ctx, input) : undefined;
+    report(file);
+    return result;
   } catch (error) {
-    console.error(`Skipped legacy completion ${file}: ${errorText(error)}`);
+    report(file, error);
     return;
   }
 }
@@ -188,7 +198,18 @@ function startScan(ctx: ExtensionContext, directory: string): LegacyScan {
 export function legacyDirectory(): string {
   return path.join(resolveTempRootDir(), "async-subagent-results");
 }
-export function legacyNotifications(ctx: ExtensionContext): Completion[] {
+export function legacyNotifications(
+  ctx: ExtensionContext,
+  reporter: BackgroundReporter,
+): Completion[] {
+  const report = (file: string, error?: unknown) => {
+    const owner = `legacy:${file}`;
+    if (error === undefined) {
+      reporter.recover(owner);
+    } else {
+      reporter.report(owner, `Skipped legacy completion ${file}: ${errorText(error)}`);
+    }
+  };
   const notices: Completion[] = [];
   const directory = legacyDirectory();
   const root = path.dirname(directory);
@@ -212,10 +233,21 @@ export function legacyNotifications(ctx: ExtensionContext): Completion[] {
     if (!name.endsWith(".json")) {
       continue;
     }
-    const notice = legacyNotice(ctx, path.join(directory, name), scan);
+    const notice = legacyNotice(ctx, path.join(directory, name), scan, report);
     if (notice) {
       notices.push(notice);
     }
   }
   return notices;
 }
+
+export function reconcileLegacy(ctx: ExtensionContext, reporter: BackgroundReporter): Completion[] {
+  try {
+    const notices = legacyNotifications(ctx, reporter);
+    reporter.recover("legacy-scan");
+    return notices;
+  } catch (error) {
+    reporter.report("legacy-scan", `Legacy completion reconciliation: ${errorText(error)}`);
+    return [];
+  }
+}

package/src/agent/notifications.ts

@@ -54,7 +54,7 @@ export function settle(owner: string, pending: boolean): boolean {
   return released;
 }
 export function published(ctx: ExtensionContext, launch: Launch): string | undefined {
-  return completionReceipts(ctx.sessionManager.getSessionFile(), launch.owner).get(launch.id);
+  return completionReceipts(ctx.sessionManager, launch.owner).get(launch.id);
 }
 export interface Completion {
   readonly owner: string;
@@ -239,8 +239,7 @@ export function notifications(ctx: ExtensionContext, base: string, owner: string
   const notices: Completion[] = [];
   const awaited = new Set<string>();
   const runs = completed(base, owner, awaited);
-  const receipts =
-    runs.length === 0 ? undefined : completionReceipts(ctx.sessionManager.getSessionFile(), owner);
+  const receipts = runs.length === 0 ? undefined : completionReceipts(ctx.sessionManager, owner);
   for (const run of runs) {
     const key = `${owner}/${run.id}`;
     if (receipts?.get(run.id) !== undefined) {