@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/pi-intercom/broker/last.js

@@ -1,24 +1,42 @@
 import { randomUUID } from "node:crypto";
 import { isRecord } from "../../shared/unknown.js";
-import { normalizeSessionInfo, } from "../types.js";
+import { isDeliveryGuard, isPublicationReplyHint, isLastMessageQuery, isReceiptQuery, LAST_MESSAGE_PAGE_LIMIT, normalizeSessionInfo, } from "../types.js";
+import { finiteNumber, nonNegativeInteger, optionalLabel, safeLabel } from "../validation.js";
 import { validateIntercomMessageSize, writeMessage } from "./framing.js";
 import { messageSender } from "./snapshots.js";
 import { findSessions } from "./targets.js";
-export const LAST_MESSAGE_PAGE_LIMIT = 16384;
-function nonNegativeInteger(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isNativeReadQuery(value) {
+    return isReceiptQuery(value) || isLastMessageQuery(value);
 }
-function optionalEntryId(value) {
-    return value === undefined || (typeof value === "string" && value.length > 0);
+function isNativeReceipt(value) {
+    if (!isReceiptQuery(value) || !isRecord(value) || !isRecord(value.sender)) {
+        return false;
+    }
+    return (value.version === 1 &&
+        safeLabel(value.sender.peerId) &&
+        [value.sender.rootSessionId, value.sender.incarnation].every(optionalLabel) &&
+        typeof value.textSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(value.textSha256) &&
+        receiptPublication(value) &&
+        receiptFacts(value));
 }
-export function isLastMessageQuery(value) {
-    return (isRecord(value) &&
-        optionalEntryId(value.entryId) &&
-        (value.offset === undefined || nonNegativeInteger(value.offset)) &&
-        (value.limit === undefined ||
-            (nonNegativeInteger(value.limit) &&
-                value.limit > 0 &&
-                value.limit <= LAST_MESSAGE_PAGE_LIMIT)));
+function receiptPublication(value) {
+    return (typeof value.delivery === "string" &&
+        ["queue", "steer", "passive"].includes(value.delivery) &&
+        (value.guard === undefined || isDeliveryGuard(value.guard)) &&
+        (value.replyHint === undefined || isPublicationReplyHint(value.replyHint)));
+}
+function receiptFacts(value) {
+    return (safeLabel(value.checkpointEntryId) &&
+        finiteNumber(value.receivedAt) &&
+        [value.queued, value.nativeHandoff, value.discarded].every((field) => typeof field === "boolean") &&
+        (value.placementEntryId === null || safeLabel(value.placementEntryId)));
+}
+export function isReceiptResult(value) {
+    return isRecord(value) && (typeof value.error === "string" || isNativeReceipt(value.receipt));
+}
+export function isNativeReadResult(value) {
+    return isReceiptResult(value) || isLastMessageResult(value);
 }
 function pageIdentity(value) {
     return (normalizeSessionInfo(value.session) !== null &&
@@ -45,16 +63,35 @@ export function isLastMessageResult(value) {
     return (isRecord(value) &&
         (typeof value.error === "string" || (pageIdentity(value) && pageOffsets(value))));
 }
-function unavailable(targets, name, pending) {
+/** An exited parked child answers nothing itself; only its main holds the captured history. */
+function exitedRefusal(target, query, via) {
+    if (target.parked?.closed !== true) {
+        return undefined;
+    }
+    // No loaded journal owner answers receipts, with or without its main.
+    if ("messageId" in query) {
+        return "publication_unavailable";
+    }
+    return via === undefined ? "Parked session history is unavailable." : undefined;
+}
+function unavailable(targets, name, pending, { query, via }) {
     if (targets.length === 0) {
         return "Session not found";
     }
     if (targets.length > 1) {
         return `Multiple sessions named "${name}" are connected. Use the session ID instead.`;
     }
+    const exited = exitedRefusal(targets[0], query, via);
+    if (exited !== undefined) {
+        return exited;
+    }
     if (!targets[0].lastMessages) {
         return "Recipient does not support last-message reads; reload its extension.";
     }
+    if ("messageId" in query &&
+        (!targets[0].receiptReads || targets[0].info.rootSessionId !== query.rootSessionId)) {
+        return "publication_unavailable";
+    }
     if (pending >= 128) {
         return "Too many pending last-message reads; retry after they settle.";
     }
@@ -64,10 +101,28 @@ function matchesPage(result, pending, fromId) {
     if ("error" in result) {
         return true;
     }
+    if ("messageId" in pending.query) {
+        return ("receipt" in result &&
+            result.receipt.messageId === pending.query.messageId &&
+            result.receipt.rootSessionId === pending.query.rootSessionId);
+    }
+    if ("receipt" in result) {
+        return false;
+    }
+    return matchesLastPage(result, pending.query, fromId);
+}
+function matchesLastPage(result, query, fromId) {
     return (result.session.id === fromId &&
-        result.offset === (pending.query.offset ?? 0) &&
-        (pending.query.entryId === undefined || result.entryId === pending.query.entryId) &&
-        result.text.length <= (pending.query.limit ?? LAST_MESSAGE_PAGE_LIMIT));
+        result.offset === (query.offset ?? 0) &&
+        (query.entryId === undefined || result.entryId === query.entryId) &&
+        result.text.length <= (query.limit ?? LAST_MESSAGE_PAGE_LIMIT));
+}
+function lastRequest(message) {
+    const { requestId, to, query } = message;
+    if (typeof requestId !== "string" || typeof to !== "string" || !isNativeReadQuery(query)) {
+        throw new Error("Invalid last message request");
+    }
+    return { requestId, to, query };
 }
 /** Correlation belongs to the broker, not the requester or the recipient's model queue. */
 export class LastMessageRelay {
@@ -76,40 +131,31 @@ export class LastMessageRelay {
     constructor(sessions) {
         this.sessions = sessions;
     }
-    request(fromId, message) {
-        if (typeof message.requestId !== "string" ||
-            typeof message.to !== "string" ||
-            !isLastMessageQuery(message.query)) {
-            throw new Error("Invalid last message request");
-        }
+    /** `reader` names another peer that answers for an exited target from its captured history. */
+    request(fromId, input, reader) {
+        const message = lastRequest(input);
         const targets = findSessions(this.sessions, message.to, fromId);
         const target = targets[0];
         const from = this.sessions.get(fromId);
         if (!from) {
             return;
         }
-        const error = unavailable(targets, message.to, this.pending.size);
-        if (error !== undefined) {
-            writeMessage(from.socket, {
-                type: "last_response",
-                requestId: message.requestId,
-                result: { error },
-            });
-            return;
-        }
         const token = randomUUID();
+        const via = targets.length === 1 ? reader(target.info.id) : undefined;
         const frame = {
             type: "last_request",
             requestId: token,
             from: messageSender(from.info),
             query: message.query,
+            parked: via && messageSender(target.info),
         };
-        const invalid = validateIntercomMessageSize(frame);
-        if (invalid) {
+        const error = unavailable(targets, message.to, this.pending.size, { query: message.query, via }) ??
+            validateIntercomMessageSize(frame)?.message;
+        if (error !== undefined) {
             writeMessage(from.socket, {
                 type: "last_response",
                 requestId: message.requestId,
-                result: { error: invalid.message },
+                result: { error },
             });
             return;
         }
@@ -118,12 +164,13 @@ export class LastMessageRelay {
         this.pending.set(token, {
             fromId,
             toId: target.info.id,
+            via: via?.info.id,
             requestId: message.requestId,
             query: message.query,
             timer,
         });
         try {
-            writeMessage(target.socket, frame);
+            writeMessage((via ?? target).socket, frame);
         }
         catch {
             this.finish(token, { error: "Recipient disconnected before last-message read" });
@@ -134,17 +181,17 @@ export class LastMessageRelay {
             throw new Error("Invalid last message response");
         }
         const pending = this.pending.get(message.requestId);
-        if (!pending || pending.toId !== fromId) {
+        if (!pending || (pending.via ?? pending.toId) !== fromId) {
             return;
         }
         const result = message.result;
-        this.finish(message.requestId, isLastMessageResult(result) && matchesPage(result, pending, fromId)
+        this.finish(message.requestId, isNativeReadResult(result) && matchesPage(result, pending, pending.toId)
             ? result
             : { error: "Recipient returned an invalid last-message page" });
     }
     disconnected(sessionId) {
         for (const [token, pending] of this.pending) {
-            if (pending.fromId === sessionId || pending.toId === sessionId) {
+            if ([pending.fromId, pending.toId, pending.via].includes(sessionId)) {
                 this.finish(token, { error: "Peer disconnected during last-message read" });
             }
         }

package/dist/pi-intercom/broker/parked.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "crypto";
+import { nativePeerId } from "../session-targets.js";
+import { writeMessage } from "./framing.js";
+export function reachable(target) {
+    const socket = target?.socket;
+    return socket !== undefined && !socket.destroyed && socket.writable && !socket.writableEnded;
+}
+function requested(id) {
+    return typeof id === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(id) ? id : undefined;
+}
+/** A fenced child keeps its identity and queued input; it never departs while parked. */
+export class ParkedSessions {
+    sessions;
+    deliver;
+    constructor(sessions, deliver) {
+        this.sessions = sessions;
+        this.deliver = deliver;
+    }
+    park(socket, id, on) {
+        const session = this.sessions.get(id);
+        if (on && session?.parking === true) {
+            session.parked ??= { retained: [], closed: false };
+            // Frames already written to this socket precede the acknowledgement.
+            writeMessage(socket, { type: "parked" });
+        }
+        else if (!on && session?.parked?.closed === false) {
+            const { retained } = session.parked;
+            session.parked = undefined;
+            this.flush(id, retained);
+        }
+    }
+    /**
+     * Delivers retained input in order. A transport that fails mid-flush keeps the rest for its
+     * next generation; delivery refusals on a live transport follow resident delivery.
+     */
+    flush(id, retained) {
+        for (const [index, { from, message }] of retained.entries()) {
+            const session = this.sessions.get(id);
+            if (this.deliver(id, from, message) !== null && session?.socket.writable === false) {
+                session.parked = { retained: retained.slice(index), closed: false };
+                return;
+            }
+        }
+    }
+    /** A free requested identity, or a parked one resumed by the same child lineage. */
+    claim(requestedId, next) {
+        const id = requested(requestedId);
+        const previous = id === undefined ? undefined : this.sessions.get(id);
+        const resumes = previous?.parked !== undefined &&
+            previous.info.rootSessionId === next.rootSessionId &&
+            previous.info.parentSessionId === next.parentSessionId;
+        if (id === undefined || (previous && !resumes)) {
+            return { id: randomUUID() };
+        }
+        previous?.socket.destroy();
+        return { id, resumed: previous };
+    }
+    /** Flushes a restored child's input and re-sends wakes owed to a (re)registered main. */
+    registered(id, previous) {
+        this.flush(id, previous?.parked?.retained ?? []);
+        for (const child of this.sessions.values()) {
+            if (nativePeerId(child.info.rootSessionId ?? "") === id) {
+                this.wake(child);
+            }
+        }
+    }
+    /** A transport handoff, not a departure: no session_left and queued input stays. */
+    closed(session) {
+        const { parked } = session;
+        if (parked) {
+            parked.closed = true;
+            this.wake(session);
+        }
+        return parked !== undefined;
+    }
+    /**
+     * Exited parked children keep identities while some live session remains. Input already
+     * admitted for one keeps the broker until a returning main wakes it.
+     */
+    get exited() {
+        return [...this.sessions.values()].every(({ parked }) => parked?.closed === true && parked.retained.length === 0);
+    }
+    retain(target, from, message) {
+        target?.parked?.retained.push({ from, message });
+        if (target) {
+            this.wake(target);
+        }
+        return target?.parked !== undefined;
+    }
+    /** Reads of an exited parked child go to its main, which answers from captured history. */
+    reader(id) {
+        const child = this.sessions.get(id);
+        return child?.parked?.closed === true ? this.main(child) : undefined;
+    }
+    // Passive breadcrumbs and topic updates wait for a genuine wake; they never spawn the child.
+    wake(child) {
+        const main = this.main(child);
+        const wakes = child.parked?.retained.some(({ message }) => message.passive !== true && message.delivery !== "passive" && message.topic === undefined);
+        if (main && child.parked?.closed === true && wakes === true) {
+            writeMessage(main.socket, { type: "wake", sessionId: child.info.id });
+        }
+    }
+    main(child) {
+        const main = this.sessions.get(nativePeerId(child.info.rootSessionId ?? ""));
+        return main?.parking === true && main.parked === undefined ? main : undefined;
+    }
+}

package/dist/pi-intercom/broker/paths.d.ts

@@ -0,0 +1,13 @@
+/** Old agent-directory namespaces are inspected for migration, never used for routing. */
+export declare function getPreviousBrokerSocketPaths(): readonly string[];
+export declare function isOwnedBrokerSocket(socketPath: string): boolean;
+/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
+export declare function getBrokerRuntimeDir(): string;
+/** Read-only child observation endpoints share the runtime policy, not the broker namespace.
+ * The endpoint name is a short token digest because the private runtime directory also counts
+ * toward the Unix-socket path limit; a full token made nested test/deployment roots overflow. */
+export declare function agentObservationSocketPath(token: string): string;
+export declare function getBrokerSocketPath(): string;
+/** Create or verify an owned, non-symlink, private socket directory. */
+export declare function preparePrivateSocketPath(socketPath: string): string;
+export declare function prepareBrokerSocketPath(): string;

package/dist/pi-intercom/broker/paths.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { getPiAgentDir } from "../agent-dir.js";
 const MAX_UNIX_SOCKET_PATH_BYTES = 100;
 function agentDigest(agentDir, uid) {
@@ -32,33 +32,56 @@ export function isOwnedBrokerSocket(socketPath) {
         return false;
     }
 }
-/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
-export function getBrokerRuntimeDir() {
+function defaultRuntimeRoot() {
+    if (process.platform !== "android") {
+        return "/tmp";
+    }
+    return process.env.PREFIX === undefined ? tmpdir() : join(process.env.PREFIX, "tmp");
+}
+function runtimeDirectory(socketName, sibling = "") {
     const configured = process.env.PI_INTERCOM_RUNTIME_DIR;
     const uid = process.getuid?.();
     if (uid === undefined) {
         throw new Error("Intercom requires Unix user IDs and Unix domain sockets.");
     }
-    const directory = configured ?? join("/tmp", `pi-intercom-${uid}`);
+    const base = configured ?? join(defaultRuntimeRoot(), `pi-intercom-${uid}`);
+    const directory = isAbsolute(base) && sibling !== "" ? `${resolve(base)}${sibling}` : base;
     if (!isAbsolute(directory) ||
         directory.includes("\0") ||
-        Buffer.byteLength(join(directory, "broker.sock")) > MAX_UNIX_SOCKET_PATH_BYTES) {
+        Buffer.byteLength(join(directory, socketName)) > MAX_UNIX_SOCKET_PATH_BYTES) {
         throw new Error("PI_INTERCOM_RUNTIME_DIR must be an absolute short Unix socket directory.");
     }
     return directory;
 }
+/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
+export function getBrokerRuntimeDir() {
+    return runtimeDirectory("broker.sock");
+}
+/** Read-only child observation endpoints share the runtime policy, not the broker namespace.
+ * The endpoint name is a short token digest because the private runtime directory also counts
+ * toward the Unix-socket path limit; a full token made nested test/deployment roots overflow. */
+export function agentObservationSocketPath(token) {
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(token)) {
+        throw new Error("Invalid actor token.");
+    }
+    const name = `obs-${createHash("sha256").update(token).digest("hex").slice(0, 16)}.sock`;
+    return join(runtimeDirectory(name, "-agents"), name);
+}
 export function getBrokerSocketPath() {
     return join(getBrokerRuntimeDir(), "broker.sock");
 }
-export function prepareBrokerSocketPath() {
-    const socketPath = getBrokerSocketPath();
-    const brokerDir = dirname(socketPath);
-    fs.mkdirSync(brokerDir, { recursive: true, mode: 0o700 });
-    const stat = fs.lstatSync(brokerDir);
+/** Create or verify an owned, non-symlink, private socket directory. */
+export function preparePrivateSocketPath(socketPath) {
+    const directory = dirname(socketPath);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
     const uid = process.getuid?.();
     if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) {
-        throw new Error(`Unsafe intercom socket directory: ${brokerDir}`);
+        throw new Error(`Unsafe intercom socket directory: ${directory}`);
     }
-    fs.chmodSync(brokerDir, 0o700);
+    fs.chmodSync(directory, 0o700);
     return socketPath;
 }
+export function prepareBrokerSocketPath() {
+    return preparePrivateSocketPath(getBrokerSocketPath());
+}

package/dist/pi-intercom/broker/pid.js

@@ -73,6 +73,10 @@ export function brokerPidRecord() {
     return `${process.pid}\n${identity !== undefined ? `${identity}\n` : ""}`;
 }
 export function isBrokerPidReused(pid, record) {
+    return isLinuxProcessReplaced(pid, record.slice(record.indexOf("\n") + 1));
+}
+/** True only when a live Linux PID provably names a different process than the identity. */
+export function isLinuxProcessReplaced(pid, identity) {
     const current = readLinuxProcess(pid);
     if (!current) {
         return false;
@@ -80,7 +84,7 @@ export function isBrokerPidReused(pid, record) {
     if (current.tgid !== pid) {
         return true;
     }
-    const saved = IDENTITY.exec(record.slice(record.indexOf("\n") + 1).trim());
+    const saved = IDENTITY.exec(identity.trim());
     const actual = IDENTITY.exec(current.identity ?? "");
     if (!saved || !actual) {
         return false;

package/dist/pi-intercom/broker/server-connection.js

@@ -1,4 +1,23 @@
+import { randomUUID } from "node:crypto";
 import { createMessageReader } from "./framing.js";
+import { assertMainParent } from "./targets.js";
+import { isSessionRegistration } from "../types.js";
+export function registeredSessionInfo(msg, sessions) {
+    if (!isSessionRegistration(msg.session)) {
+        throw new Error("Invalid register message");
+    }
+    assertMainParent(msg.session, sessions);
+    const requestedId = typeof msg.requestedId === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(msg.requestedId)
+        ? msg.requestedId
+        : undefined;
+    const id = requestedId !== undefined && !sessions.has(requestedId) ? requestedId : randomUUID();
+    return {
+        ...msg.session,
+        id,
+        guardedDelivery: msg.guardedDelivery === 1 ? msg.session.guardedDelivery : undefined,
+        lastSeen: msg.session.lastSeen ?? Date.now(),
+    };
+}
 /** A server connection owns its registration identity until the socket closes. */
 export function acceptBrokerConnection(socket, handleMessage, disconnected) {
     let sessionId = null;
@@ -9,7 +28,7 @@ export function acceptBrokerConnection(socket, handleMessage, disconnected) {
     }));
     socket.on("close", () => {
         if (sessionId !== null) {
-            disconnected(sessionId);
+            disconnected(sessionId, socket);
         }
     });
     socket.on("error", (error) => {

package/dist/pi-intercom/broker/snapshot-reader.d.ts

@@ -0,0 +1,9 @@
+import { type SessionSnapshot } from "../types.ts";
+/** Multipart frames build a private cache; only a complete validated snapshot escapes. */
+export declare class SnapshotReader {
+    private readonly sessions;
+    private readonly receipts;
+    private addSession;
+    append(sessions: readonly unknown[], receipts: unknown): void;
+    finish(): SessionSnapshot;
+}

package/dist/pi-intercom/broker/snapshots.d.ts

@@ -0,0 +1,29 @@
+import { type SessionInfo, type TopicUpdate, type Message, type BrokerMessage, type TopicSubscription, type SendResult } from "../types.ts";
+/** Direct messages and old clients receive identity, not potentially large topic state. */
+export declare function messageSender(info: SessionInfo): SessionInfo;
+export declare function snapshotFrames(requestId: string, infos: readonly SessionInfo[], stream: boolean): BrokerMessage[];
+interface PreparedTopicChange {
+    readonly topic?: TopicUpdate;
+    readonly subscription?: TopicSubscription;
+    readonly unsubscribe?: string;
+    readonly publication?: TopicUpdate;
+    readonly restore: boolean;
+    readonly changed: boolean;
+    readonly bytes: number;
+}
+/** Keep committed records indexed; restores validate only new bytes and cached envelope maxima. */
+export declare class TopicSnapshot {
+    private readonly topics;
+    private readonly subscriptions;
+    constructor(info: SessionInfo);
+    subscription(topic: string): TopicSubscription | undefined;
+    prepare(change: unknown, supported: boolean): PreparedTopicChange;
+    private preparePublication;
+    snapshot(info: SessionInfo, prepared?: PreparedTopicChange): SessionInfo;
+    validateRestore(info: SessionInfo, prepared: PreparedTopicChange, requestId: string): void;
+    commit(prepared: PreparedTopicChange): void;
+}
+export declare function deliveryAcknowledgement(receipt: SendResult): BrokerMessage;
+export declare function shouldReplaceDelivery(message: Message, info: SessionInfo): boolean;
+export declare function publicationMessage(publication: TopicUpdate, awaitRelease: boolean): Message;
+export {};

package/dist/pi-intercom/broker/targets.d.ts

@@ -0,0 +1,9 @@
+import type { SessionInfo } from "../types.ts";
+export declare function canSeeSession(from: SessionInfo, target: SessionInfo): boolean;
+export declare function assertMainParent(session: Omit<SessionInfo, "id">, sessions: ReadonlyMap<string, {
+    readonly info: SessionInfo;
+}>): void;
+/** Preserve exact-ID precedence and case-insensitive duplicate-name ambiguity. */
+export declare function findSessions<T extends {
+    readonly info: SessionInfo;
+}>(sessions: ReadonlyMap<string, T>, nameOrId: string, fromId: string): T[];

package/dist/pi-intercom/connection.js

@@ -2,10 +2,13 @@ import { IntercomClient } from "./broker/client.js";
 import { spawnBrokerIfNeeded } from "./broker/spawn.js";
 import { readLastMessage } from "./last-message.js";
 import { asError } from "./validation.js";
+import { RecoveryError } from "./tool-results.js";
 import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.js";
 /** Owns socket registration, coalesced connects and the reconnect/startup timers. */
 export class IntercomConnection {
     client = null;
+    /** The transport whose broker retains this actor's input while it parks. */
+    parked = null;
     reconnectTimer = null;
     startupTimer = null;
     connecting = null;
@@ -22,6 +25,22 @@ export class IntercomConnection {
     get active() {
         return this.client;
     }
+    async park() {
+        const client = this.client;
+        this.parked = client !== null && (await client.park().catch(() => false)) ? client : null;
+        return this.parked !== null && this.parked === this.client;
+    }
+    get parking() {
+        return this.parked !== null;
+    }
+    get reconnected() {
+        return this.client !== null && this.client !== this.parked;
+    }
+    unpark() {
+        const client = this.parked === this.client ? this.client : null;
+        this.parked = null;
+        return client?.park(false).catch(() => false) ?? Promise.resolve(false);
+    }
     start(ctx, generation) {
         this.attempt = 0;
         this.clearTimers();
@@ -93,9 +112,51 @@ export class IntercomConnection {
             this.client.updatePresence({
                 status: this.lifecycle.status(),
                 ...this.lifecycle.health(this.hooks.pendingAsks()),
+                applicationGuard: this.lifecycle.snapshot().applicationGuard ?? null,
             });
         }
     }
+    answerLast(next, request) {
+        const ctx = this.lifecycle.live();
+        const id = next.sessionId;
+        if (this.client !== next || !ctx || id === null) {
+            next.respondLast(request.requestId, { error: "Intercom runtime no longer active" });
+            return;
+        }
+        const { parked, query } = request;
+        if ("messageId" in query) {
+            // The broker refuses receipt reads of an exited parked child before relaying them.
+            next.respondLast(request.requestId, parked ? { error: "publication_unavailable" } : this.hooks.receipt(query));
+            return;
+        }
+        if (parked) {
+            this.hooks
+                .parkedHistory(parked)
+                .then((history) => history
+                ? readLastMessage(history, parked, query)
+                : { error: "Parked session history is unavailable." })
+                .catch((error) => ({ error: asError(error).message }))
+                .then((result) => {
+                next.respondLast(request.requestId, result);
+            })
+                .catch(() => {
+                /* The requester's broker timeout reports a lost transport. */
+            });
+            return;
+        }
+        try {
+            next.respondLast(request.requestId, readLastMessage(ctx.sessionManager, {
+                id,
+                ...this.lifecycle.identity(ctx.sessionManager.getSessionId()),
+                cwd: ctx.cwd,
+                model: ctx.model?.id ?? "unknown",
+                status: this.lifecycle.status(),
+            }, query));
+        }
+        catch (error) {
+            next.respondLast(request.requestId, { error: asError(error).message });
+        }
+    }
     createClient() {
         const next = new IntercomClient({
             sendTimeoutMs: this.config.sendTimeoutMs,
@@ -103,24 +164,7 @@ export class IntercomConnection {
         });
         this.client = next;
         next.on("last_request", (request) => {
-            const ctx = this.lifecycle.live();
-            const id = next.sessionId;
-            if (this.client !== next || !ctx || id === null) {
-                next.respondLast(request.requestId, { error: "Intercom runtime no longer active" });
-                return;
-            }
-            try {
-                next.respondLast(request.requestId, readLastMessage(ctx.sessionManager, {
-                    id,
-                    ...this.lifecycle.identity(ctx.sessionManager.getSessionId()),
-                    cwd: ctx.cwd,
-                    model: ctx.model?.id ?? "unknown",
-                    status: this.lifecycle.status(),
-                }, request.query));
-            }
-            catch (error) {
-                next.respondLast(request.requestId, { error: asError(error).message });
-            }
+            this.answerLast(next, request);
         });
         next.on("message", (from, message) => {
             const ctx = this.lifecycle.live();
@@ -131,6 +175,11 @@ export class IntercomConnection {
                 console.error("Intercom inbound delivery failed:", error);
             });
         });
+        next.on("wake", (peer) => {
+            if (this.client === next) {
+                this.hooks.wake(peer);
+            }
+        });
         next.on("session_left", (id) => {
             if (this.client !== next) {
                 return;
@@ -143,6 +192,7 @@ export class IntercomConnection {
             }
             this.hooks.disconnected(error);
             this.client = null;
+            this.lifecycle.transport(null);
             this.clearReconnect();
             this.scheduleReconnect();
         });
@@ -161,6 +211,7 @@ export class IntercomConnection {
                 throw new Error("Intercom runtime no longer active");
             }
             this.client = next;
+            this.lifecycle.transport(next.sessionId, next.supportsGuardedDelivery);
             this.syncIdentity(ctx.sessionManager.getSessionId());
             this.attempt = 0;
             return next;
@@ -239,10 +290,10 @@ export async function resolveConnectedTarget(active, name) {
         return resolution.target.id;
     }
     if (resolution.status === "ambiguous") {
-        throw new Error(`Target "${name}" matches multiple sessions. Use one of these targets: ${formatTargetOptions(resolution.matches, sessions)}.`);
+        throw new RecoveryError("ambiguous_target", `Target "${name}" matches multiple sessions. Use one of these targets: ${formatTargetOptions(resolution.matches, sessions)}.`);
     }
     if (resolution.status === "prefix_too_short") {
-        throw new Error(`Target "${name}" is too short. Use the displayed target from intercom list, such as ${formatTargetOptions(resolution.matches, sessions)}.`);
+        throw new RecoveryError("ambiguous_target", `Target "${name}" is too short. Use the displayed target from intercom list, such as ${formatTargetOptions(resolution.matches, sessions)}.`);
     }
     return null;
 }