@fitchmultz/pi-subagents 0.52.4 → 0.52.5

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.52.5] - 2026-10-31
+
+### Fixed
+
+- Stop repeating finished-run completion messages in `--no-session` parents. Pi keeps an unsaved session's transcript only in memory, and the completion check looked only for a session file, so each settled turn delivered the same completion again and started another turn. The check now reads Pi's in-memory transcript when there is no session file. Saved sessions still use the session file. This also covers a result from a pre-0.50 background run that finishes after `/reload`; its saved result file is kept, because only a receipt in a session file can remove it.
+- Report parked-child wake failures to waiting asks and run inspection without printing them into the parent TUI. Accepted questions remain queued and may still arrive; a later active message requests another wake.
+- A failed restore can retry when its exact exited actor proves it never entered native open for the same parked generation. Ambiguous or possibly live claims remain protected.
+- Release launch claims when a child process did not start, so later attempts can recover without a false ambiguity. Preserve claims when a process may have started.
+- Show background errors as native notifications instead of writing over an active terminal. Report repeated failures once until the affected operation recovers; UI shutdown diagnostics are recorded separately when possible.
+- Keep the `@fitchmultz/pi-subagents/intercom-client` type declarations independent of Pi so standalone Node consumers can type-check without installing the Pi SDK.
+
 ## [0.52.4] - 2026-10-29
 
 ### Fixed

package/README.md

@@ -128,7 +128,8 @@ It never runs during startup/install, deletes data, or reclaims disk space.
 - [Diagnosis, baseline, and measurable rebuild gates](docs/single-agent-rebuild.md)
 
 Supports official Pi and the maintained `fitchmultz/pi` fork; the two hosts are
-qualified separately, including native Android/Termux. Node.js 24.21 or newer is
-required. Source installs on Android also need an Android-native `tsgo` on PATH;
-the prebuilt npm package does not need a compiler. See
-[development prerequisites](docs/development.md#native-androidtermux). MIT licensed.
+qualified separately, including native Android/Termux. Node.js is required; see
+[development prerequisites](docs/development.md). Source installs on Android also
+need an Android-native `tsgo` on PATH; the prebuilt npm package does not need a
+compiler. See [native Android/Termux](docs/development.md#native-androidtermux).
+MIT licensed.

package/dist/agent/completion-watches.js

@@ -0,0 +1,61 @@
+import * as path from "node:path";
+import { errorMessage } from "../shared/unknown.js";
+import { DirectoryWatch } from "./wake.js";
+/** Owns change hints for completion inputs and reports failures without losing polling. */
+export class CompletionWatches {
+    watches = new Map();
+    awaited = new Set();
+    reporter;
+    wake;
+    constructor(reporter, wake) {
+        this.reporter = reporter;
+        this.wake = wake;
+    }
+    update(base, legacy, awaited) {
+        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) => [
+            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";
+    }
+    ensure(directory, every) {
+        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() {
+        for (const [directory, watch] of this.watches) {
+            watch.close();
+            this.reporter.recover(`watch:${directory}`);
+        }
+        this.watches.clear();
+        this.awaited = new Set();
+    }
+}

package/dist/agent/contracts.js

@@ -98,6 +98,15 @@ export const parkedSchema = Type.Object({
     sessionId: Type.String(),
     leafId: Type.Union([Type.String(), Type.Null()]),
 });
+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/dist/agent/host.js

@@ -12,6 +12,11 @@ import { findPackageJSON } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readIntercomLineage } from "../pi-intercom/identity.js";
 export { errorMessage as errorText } from "../shared/unknown.js";
+/** A launcher may still own children while handing off or replacing a worker. */
+export function retainsChildren(event) {
+    const disposition = Reflect.get(event, "disposition");
+    return disposition === "handoff" || disposition === "provisional";
+}
 function isPackage(root) {
     const file = path.join(root, "package.json");
     if (!fs.existsSync(file)) {

package/dist/agent/index.js

@@ -2,8 +2,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import * as loadedSDK from "@earendil-works/pi-coding-agent";
-import { actor, alive, ensureActor, ownIdentity, parkFailure, requestStop, signalProcess, stopChildren, } from "./process.js";
-import { isChild, errorText, rememberSDK } from "./host.js";
+import { actor, alive, ensureActor, ownIdentity, parkFailure, requestStop, signalProcess, } from "./process.js";
+import { stopChildren } from "./shutdown.js";
+import { isChild, errorText, rememberSDK, retainsChildren } from "./host.js";
 import { serveParked } from "./parking.js";
 import { resultSchema, attachmentSchema, admissionSchema, commandSchema, } from "./contracts.js";
 import { delegateSchema, runsSchema } from "./tool-schemas.js";
@@ -11,17 +12,14 @@ import { enqueue, latest, launchAt, list, read, runDirectory, ownerDirectory, co
 import { notifications, deliver, settle } from "./notifications.js";
 import { prepareLaunch } from "./launch.js";
 import { renderReceipt, renderInventory, renderInspection } from "./view.js";
-import { legacyDirectory, legacyNotifications } from "./legacy.js";
-import { DirectoryWatch, pathStamp } from "./wake.js";
+import { legacyDirectory, reconcileLegacy } from "./legacy.js";
+import { pathStamp } from "./wake.js";
+import { CompletionWatches } from "./completion-watches.js";
 import { savedContinuation } from "./saved.js";
 import { executionCwd } from "./cwd.js";
 import { getPiAgentDir } from "../pi-intercom/agent-dir.js";
 import { registerCompactMessages, renderCompactResult } from "../shared/compact-cards.js";
-/** `handoff` and `provisional` mean another worker under the same launcher may still own these children. */
-function retainsChildren(event) {
-    const disposition = Reflect.get(event, "disposition");
-    return disposition === "handoff" || disposition === "provisional";
-}
+import { BackgroundReporter } from "../shared/background-reporting.js";
 function managedHost(context) {
     const host = Reflect.get(context, "managedHost");
     if (typeof host !== "object" || host === null) {
@@ -45,6 +43,7 @@ function legacyInput() {
 }
 class AgentRuntime {
     ctx;
+    reporter = new BackgroundReporter(() => this.ctx);
     // A managed launcher owns children across worker replacement; otherwise this process does.
     host;
     accepted = false;
@@ -55,7 +54,7 @@ class AgentRuntime {
     timer;
     woken;
     // Change hints for the owner directory, legacy results and every awaited canonical file.
-    watches = new Map();
+    watches;
     awaited = new Set();
     // Input stamps the last reconciliation saw; a one-second probe recovers dropped hints.
     observed = new Map();
@@ -68,6 +67,7 @@ class AgentRuntime {
     pi;
     constructor(pi) {
         this.pi = pi;
+        this.watches = new CompletionWatches(this.reporter, this.wake);
     }
     checkMain() {
         if (isChild()) {
@@ -102,21 +102,17 @@ 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();
         }
@@ -125,45 +121,17 @@ class AgentRuntime {
             this.wake();
         }
     };
-    /** Watches every directory that can publish an awaited input; legacy results may never exist. */
-    watch() {
-        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) => {
-            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";
-    }
     unwatch() {
         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();
     }
     start(context) {
+        this.reporter.start();
         this.host = managedHost(context);
         if (this.host === undefined || this.accepted || this.child) {
             this.reset = this.reset.then(() => this.attach(context));
@@ -182,7 +150,7 @@ class AgentRuntime {
             }
         })
             .catch((error) => {
-            console.error(`Agent runtime attachment: ${errorText(error)}`);
+            this.reporter.report(undefined, `Agent runtime attachment: ${errorText(error)}`);
         });
         return undefined;
     }
@@ -212,6 +180,7 @@ class AgentRuntime {
         this.probe = setInterval(this.recover, 1000).unref();
     }
     async dispose(retain) {
+        this.reporter.shutdown();
         this.closing = true;
         this.unwatch();
         this.shutdown.abort();
@@ -225,7 +194,7 @@ 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;
@@ -253,7 +222,7 @@ class AgentRuntime {
                 });
             }
             catch (error) {
-                console.error(`Agent stop escalation: ${errorText(error)}`);
+                this.reporter.report(undefined, `Agent stop escalation ${launch.id}: ${errorText(error)}`);
             }
         }, 3000);
         escalation.unref();

package/dist/agent/legacy.js

@@ -1,12 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { errorText } from "./host.js";
 import { journalStamp } from "../shared/native-journal.js";
 import { receiptId } from "./receipts.js";
 import { resolveTempRootDir } from "../shared/types.js";
 import { isRecord } from "../shared/unknown.js";
 import { release, isHeld } from "./notifications.js";
 import { missing } from "./storage.js";
-import { errorText } from "./host.js";
 // Retain only foreign classifications, never their saved output, for each live native manager.
 const ignoredInputs = new WeakMap();
 function fileStamp(file) {
@@ -91,16 +91,24 @@ function receipt(body, input) {
     }
     return body.type === "message" && legacyWait(body.message, input);
 }
+/** Where Pi recorded this input's receipt: its session file, or memory under `--no-session`. */
 function published(ctx, input) {
-    return (receiptId(ctx.sessionManager.getSessionFile(), input.owner, (body) => receipt(body, input)) !==
-        undefined);
+    const file = ctx.sessionManager.getSessionFile();
+    const matches = (body) => 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, input) {
     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.
-        if (journalStamp(fs.lstatSync(input.file, { bigint: true })) === input.stamp &&
+        // 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) {
             fs.unlinkSync(input.file);
         }
@@ -121,13 +129,15 @@ function notification(ctx, input) {
         },
     };
 }
-function legacyNotice(ctx, file, scan) {
+function legacyNotice(ctx, file, scan, report) {
     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;
     }
 }
@@ -149,7 +159,16 @@ function startScan(ctx, directory) {
 export function legacyDirectory() {
     return path.join(resolveTempRootDir(), "async-subagent-results");
 }
-export function legacyNotifications(ctx) {
+export function legacyNotifications(ctx, reporter) {
+    const report = (file, error) => {
+        const owner = `legacy:${file}`;
+        if (error === undefined) {
+            reporter.recover(owner);
+        }
+        else {
+            reporter.report(owner, `Skipped legacy completion ${file}: ${errorText(error)}`);
+        }
+    };
     const notices = [];
     const directory = legacyDirectory();
     const root = path.dirname(directory);
@@ -174,10 +193,21 @@ export function legacyNotifications(ctx) {
         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, reporter) {
+    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/dist/agent/notifications.js

@@ -51,7 +51,7 @@ export function settle(owner, pending) {
     return released;
 }
 export function published(ctx, launch) {
-    return completionReceipts(ctx.sessionManager.getSessionFile(), launch.owner).get(launch.id);
+    return completionReceipts(ctx.sessionManager, launch.owner).get(launch.id);
 }
 export function deliver(pi, ctx, notices) {
     const idle = ctx.isIdle();
@@ -194,7 +194,7 @@ export function notifications(ctx, base, owner) {
     const notices = [];
     const awaited = new Set();
     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) {

package/dist/agent/parking.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { parkedSchema } from "./contracts.js";
+import { exitSchema, parkedSchema, readySchema, wakeFailureSchema, } from "./contracts.js";
 import { errorText, loadSDK } from "./host.js";
 import { conversation, latest, launchAt, list, read, runDirectory, write } from "./storage.js";
-import { alive, shell, shells, wakeActor } from "./process.js";
-import { isHistoryRequest, PARK, PARKED_HISTORY, WAKE, } from "../shared/parking.js";
+import { actor as claimedActor, alive, shell, shells, wakeActor } from "./process.js";
+import { DirectoryWatch, Wake } from "./wake.js";
+import { isHistoryRequest, isWakeRequest, PARK, PARKED_HISTORY, WAKE, } from "../shared/parking.js";
 import { nativePeerId } from "../pi-intercom/session-targets.js";
 function parkable(session) {
     return typeof Reflect.get(session, "acquireWorkingSession") === "function";
@@ -85,6 +86,8 @@ export function parkedState(dir, launch, restore) {
 /** One actor generation's idle parking and exact restore; commands stay with the runner. */
 export class Parking {
     saved;
+    /** Set before entering either native open, whose effects may outlive an exception. */
+    opened = false;
     restored;
     since = 0;
     leaf;
@@ -110,6 +113,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);
         }
@@ -248,22 +252,126 @@ async function history(runs, peer) {
     const state = runs && launch && parkedState(conversation(runs.base, launch), launch, restore)?.saved;
     return state && { getBranch: () => branchOf(state) };
 }
+function unavailableCwd(cwd) {
+    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, identity, legacy) {
+    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, launch, signal, legacy) {
+    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, launch, error) {
+    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.
  */
 export function serveParked(pi, runs, signal) {
-    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();
+    const attempt = async (peer, registered) => {
+        let current;
+        let launch;
+        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) => {
-            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)) {