@staix/agent-hub 0.29.0 → 0.31.0

package/src/adapters/pi.ts

@@ -3,8 +3,9 @@ import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { spawn, type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
-import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
-import { BasePeer } from "../hub/peers.ts";
+import { renderDigest, remoteEnvelope, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
+import { BasePeer, type SessionTitleResult } from "../hub/peers.ts";
+import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { assessVersion, COMPAT, type CompatVerdict } from "./compat.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
@@ -12,6 +13,7 @@ import { PiSessionBookmarkMismatch, validatePiSession } from "../pi/session.ts";
 import { ApprovalWaitStop, toolResultFailed, type ApprovalProvenance } from "../local/tools.ts";
 import { piToolStepCeiling, type PiToolStepCeiling } from "../pi/ceiling.ts";
 import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
+import { QuestionWaitDetached } from "../hub/question-detach.ts";
 import type { StartForm } from "./registry-types.ts";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
@@ -41,6 +43,8 @@ export interface PiOptions {
   model?: string;
   relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal, context?: PiToolContext) => Promise<string | PiToolResult>; tools: PiToolSchema[];
   preamble?: string;
+  /** Host-owned conditional instruction, sampled once per delivered turn. */
+  titlePreface?: () => string | undefined;
   selectModel?: (envs: Envelope[]) => Promise<string | undefined>; maxSteps?: number;
   /** Atomic task/run admission immediately before provider requests or tool execution. */
   admitBudget?: (envs: Envelope[], unit: ExecutionUnit) => Promise<ExecutionBudgetDecision[]>;
@@ -113,6 +117,66 @@ export class PiPeer extends BasePeer {
   private currentReply?: Envelope;
   private sessionId = "";
   private sessionFile = "";
+  /** A read-only observation of Pi's native slot, never a second writable title store. */
+  private observedTitle: string | undefined;
+  private titleRevision = -1;
+  private titleEpoch = 0;
+  private nativeTitleEpoch: string | undefined;
+  get sessionTitle(): string | undefined { return this.acceptingTools && this.verifiedOwner() ? this.observedTitle : undefined; }
+  get titleSession(): string | undefined { return this.nativeSession; }
+  async setSessionTitle(title: string, onlyIfUnnamed: boolean, current?: () => boolean): Promise<SessionTitleResult> {
+    const invalid = (error: string, mayHaveApplied = false): SessionTitleResult => ({ ok: false, reason: "invalid", error, ...(mayHaveApplied ? { mayHaveApplied: true as const } : {}) });
+    if (typeof title !== "string" || !title.trim() || [...title].length > 80 || typeof onlyIfUnnamed !== "boolean") return invalid("Session title must contain 1-80 normalized characters and use a conditional-write flag; correct the title request and try again.");
+    if (this.stopping || this.state === "offline") return invalid("Pi session is offline or stopped; start or reconnect Pi and check ahub status before naming it.");
+    const session = this.sessionId, generation = this.budgetGeneration, owner = this.sessionGeneration, epoch = this.titleEpoch;
+    if (!owner || !this.verifiedOwner()) return invalid("Pi native session owner is unverified; reconnect the retained Pi session and check ahub status before naming it.");
+    if (!this.acceptingTools) return invalid("Pi session is detached or running a personal turn; reconnect its current hub session and check ahub status before naming it.");
+    const valid = () => {
+      try { return this.acceptingTools && this.verifiedOwner() && this.sessionGeneration === owner && this.sessionId === session && this.budgetGeneration === generation && this.titleEpoch === epoch && current?.() !== false; }
+      catch { return false; }
+    };
+    if (!valid()) return invalid("Pi session, turn or title admission changed before dispatch; check ahub status before retrying in the current public session.");
+    let dispatched = false;
+    try {
+      const result = await this.sendTui({ type: "set_session_title", title, onlyIfUnnamed, sessionId: session, generation, ...(this.nativeTitleEpoch ? { titleEpoch: this.nativeTitleEpoch } : {}) }, valid, () => { dispatched = true; });
+      if (!valid()) return invalid("Pi session, turn or title admission changed after dispatch; the title may have been applied; check ahub status before retrying.", true);
+      if (result?.ok === false && result.reason === "invalid") {
+        if (result.cause === "session") return invalid("Pi native session changed before the title write; check ahub status and reconnect the current session before retrying.");
+        if (result.cause === "generation") return invalid("Pi native turn changed before the title write; wait for the current turn and check ahub status before retrying.");
+        if (result.cause === "arguments") return invalid("Pi rejected invalid title command arguments; use a 1-80 character normalized title and retry in the current session.");
+        if (result.cause === "native_unavailable") return invalid("Pi native title API is unavailable; restart Pi with the supported hub extension and check ahub status before retrying.");
+        if (result.cause === "native_failed") return invalid("Pi native title API failed without confirming the write; the title may have been applied; check ahub status before retrying.", true);
+        if (result.cause === "native_readback") return invalid("Pi native title readback did not confirm the write; the title may have been applied; check ahub status before retrying.", true);
+      }
+      if (result?.sessionId !== session || typeof result.sessionName !== "string" || this.nativeTitleEpoch !== undefined && result.titleEpoch !== this.nativeTitleEpoch) return invalid("Pi title acknowledgement did not confirm the current native slot; the title may have been applied; check ahub status before retrying.", true);
+      this.observeTitle(result.sessionName, result.titleRevision, result.titleEpoch);
+      if (result.ok === false && result.reason === "already_named") return { ok: false, reason: "already_named", error: "This session already has a title; keep it or ask the person to rename it with ahub title." };
+      if (result.ok === true && result.sessionName === title) return { ok: true };
+      return invalid("Pi native title write or readback was not confirmed; the title may have been applied; check ahub status before retrying.", true);
+    } catch (error) {
+      const timeout = error instanceof Error && error.message.includes("acknowledgement timed out");
+      if (dispatched) return invalid(`Pi title ${timeout ? "acknowledgement timed out" : "bridge command failed after dispatch"}; the title may have been applied; check ahub status before retrying.`, true);
+      return invalid(`Pi title ${timeout ? "command expired" : "admission changed or bridge failed"} before dispatch; check ahub status before retrying in the current session.`);
+    }
+  }
+  private observeTitle(value: unknown, revision?: unknown, epoch?: unknown): void {
+    if (this.nativeTitleEpoch !== undefined && epoch !== this.nativeTitleEpoch) return;
+    if (typeof revision === "number" && Number.isSafeInteger(revision) && revision >= 0) {
+      if (revision < this.titleRevision) return;
+      this.titleRevision = revision;
+    }
+    if (value === undefined) value = ""; // A verified native session omits its name while unnamed.
+    if (typeof value !== "string") return;
+    if (value) this.noteActivity(); // Native session_info is history even before Pi creates its session file.
+    if (this.observedTitle !== value) { this.observedTitle = value; this.onDoing?.("title", value); }
+  }
+  private observeSnapshotTitle(snapshot: { sessionName?: unknown; titleRevision?: unknown; titleEpoch?: unknown }, before: number, beforeEpoch: number): boolean {
+    if (this.titleEpoch !== beforeEpoch || snapshot.titleEpoch !== undefined && snapshot.titleEpoch !== this.nativeTitleEpoch) return false;
+    if (snapshot.titleRevision === undefined && this.titleRevision !== before) return false;
+    if (typeof snapshot.titleRevision === "number" && snapshot.titleRevision < this.titleRevision) return false;
+    this.observeTitle(snapshot.sessionName, snapshot.titleRevision, snapshot.titleEpoch ?? this.nativeTitleEpoch);
+    return true;
+  }
   private executionBudgetTimer?: ReturnType<typeof setTimeout>;
   private executionAbort?: AbortController;
   private readonly budgetStops = new Map<number, string>();
@@ -164,7 +228,7 @@ export class PiPeer extends BasePeer {
   private terminalOwnerObservation?: TerminalOwnerObservation;
   private tuiExit?: Promise<void>;
   private resolveTuiExit?: () => void;
-  private tuiCommands = new Map<string, { command: Record<string, unknown>; resolve: (value: any) => void; reject: (error: Error) => void }>();
+  private tuiCommands = new Map<string, { command: Record<string, unknown>; current?: () => boolean; onDispatch?: () => void; resolve: (value: any) => void; reject: (error: Error) => void }>();
   private tuiQueue: Record<string, unknown>[] = [];
   private tuiWaiters: Array<{ resolve: (command: Record<string, unknown> | undefined) => void; timer: ReturnType<typeof setTimeout> }> = [];
 
@@ -219,14 +283,16 @@ export class PiPeer extends BasePeer {
     this.emptyResumeVerified = false;
     if (this.state !== "idle" || this.stopping || this.activeTools) throw new Error("Pi must settle before session capture");
     if (this.sessionFile && existsSync(this.sessionFile)) return this.recoveryMetadata();
+    const titleRevisionBefore = this.titleRevision, titleEpochBefore = this.titleEpoch;
     const snapshot = this.opts.mode === "headless"
       ? (await this.waitRpc("get_state", 15_000)).data
       : await this.sendTui({ type: "get_session_state" });
     if (this.state !== "idle" || this.activeTools || snapshot?.sessionId !== this.sessionId || snapshot?.sessionFile !== this.sessionFile) throw new Error("Pi source session changed during capture");
+    if (!this.observeSnapshotTitle(snapshot, titleRevisionBefore, titleEpochBefore)) throw new Error("Pi source session title changed during capture; retry with a fresh native session snapshot");
     const empty = this.opts.mode === "headless"
       ? snapshot.messageCount === 0 && snapshot.pendingMessageCount === 0 && snapshot.isStreaming === false && snapshot.isCompacting !== true && !snapshot.sessionName
       : snapshot.empty === true && snapshot.idle === true;
-    if (!empty || this.activityObserved || this.persistedOnce) throw new Error("Pi session history is not persisted; refusing to recreate it");
+    if (!empty || this.activityObserved || this.persistedOnce) throw new Error("Pi session history is not persisted; refusing to recreate it. Exchange one message or start a new session, then retry");
     this.emptyResumeVerified = true;
     const captured = this.recoveryMetadata();
     if (typeof captured.sessionId === "string" && !captured.sessionFile) this.verifiedEmptyResume = { sessionId: captured.sessionId };
@@ -265,6 +331,35 @@ export class PiPeer extends BasePeer {
     this.starting = this.startImpl();
     try { await this.starting; } finally { this.starting = undefined; }
   }
+  /** The keepalive period of a long tool reply; well under every timer between the hub and Pi's runtime (60 s Bun idle, 300 s undici). A test shortens it. */
+  toolKeepaliveMs = 15_000;
+  /**
+   * A tool reply that may take minutes (`hub_ask`): the status line and headers go out at once, a space is written every `toolKeepaliveMs`, and the JSON body
+   * follows when the call settles. Whitespace before a JSON value is valid JSON, so the extension's `response.json()` reads it unchanged. When the client goes away
+   * the stream is cancelled and the call is aborted through its own signal with `QuestionWaitDetached`, so the wait ends `pending` and the row stays open for the late envelope;
+   * nothing else about `handleToolRequest` changes.
+   */
+  private streamedToolResponse(body: any, clientGone: AbortSignal): Response {
+    const encoder = new TextEncoder();
+    let timer: ReturnType<typeof setInterval> | undefined, closed = false;
+    const stop = () => { closed = true; if (timer) clearInterval(timer); timer = undefined; };
+    return new Response(new ReadableStream({
+      start: controller => {
+        timer = setInterval(() => { if (!closed) try { controller.enqueue(encoder.encode(" ")); } catch { stop(); } }, this.toolKeepaliveMs);
+        timer.unref?.();
+        const abort = () => { stop(); this.pendingToolGenerations.get(String(body?.toolCallId ?? ""))?.abort.abort(new QuestionWaitDetached()); };
+        clientGone.addEventListener("abort", abort, { once: true });
+        void this.handleToolRequest(body).then(async response => {
+          const text = await response.text();
+          if (closed) return;
+          stop();
+          try { controller.enqueue(encoder.encode(text)); controller.close(); } catch { /* the client already left */ }
+        }, () => { if (closed) return; stop(); try { controller.enqueue(encoder.encode(JSON.stringify({ text: "error: Pi tool call failed", failed: true }))); controller.close(); } catch { /* the client already left */ } });
+      },
+      cancel: () => { stop(); this.pendingToolGenerations.get(String(body?.toolCallId ?? ""))?.abort.abort(new QuestionWaitDetached()); },
+    }), { headers: { "content-type": "application/json" } });
+  }
+
   private async handleToolRequest(body: any): Promise<Response> {
     if (!this.acceptingTools || this.state === "offline") return Response.json({ text: this.rosterDetached ? "error: Pi is off roster" : this.rosterUnownedRun ? "error: Pi native turn is pending" : "error: Pi owner is stopped" }, { status: 409 });
     if (!this.verifiedOwner() || typeof body.sessionId !== "string" || !body.sessionId || body.sessionId !== this.sessionId || !Number.isSafeInteger(body.generation) || body.generation !== this.budgetGeneration) {
@@ -388,6 +483,7 @@ export class PiPeer extends BasePeer {
     if (this.preflight) await this.preflight();
     this.terminalOwnerObservation = undefined;
     this.stopping = false;
+    this.observedTitle = undefined; this.titleRevision = -1; this.nativeTitleEpoch = undefined; this.onDoing?.("reset");
     this.rosterDetached = false; this.rosterUnownedRun = false;
     this.requestedStopReason = undefined;
     this.approvalTurnAbort = false;
@@ -429,7 +525,18 @@ export class PiPeer extends BasePeer {
           : boundRefusal && refusal.kind === "prompt_uncertain" ? new PiPromptUncertain("Pi native prompt insertion is uncertain; inspect its retained terminal before retrying") : new Error(String(body.error ?? "Pi TUI command failed")));
         return Response.json({ ok: true });
       }
-      if (url.pathname === "/tool") return this.handleToolRequest(body);
+      if (url.pathname === "/tool") {
+        // #1053: `hub_ask` holds this request open for the person's wait window. Two timers would cut it: Bun's 60 s bridge idle timeout (lifted for this one call with
+        // `timeout(request, 0)`) and the extension's own fetch, whose undici dispatcher Pi installs with headersTimeout and bodyTimeout of 300 s (Pi 1.4.0
+        // `configureHttpDispatcher`, measured: UND_ERR_HEADERS_TIMEOUT). So the reply is streamed: headers go out at once and a space every 15 s keeps both timers
+        // quiet, then the JSON follows (`response.json()` ignores leading whitespace). A client that gives up anyway cancels the stream, which aborts the call; the
+        // question row stays open and its answer takes the late-envelope path.
+        if (body?.name === "hub_ask") {
+          bridge.timeout(request, 0);
+          return this.streamedToolResponse(body, request.signal);
+        }
+        return this.handleToolRequest(body);
+      }
       if (url.pathname === "/budget") return this.handleBudgetRequest(body);
       return new Response("not found", { status: 404 });
     } });
@@ -456,6 +563,7 @@ export class PiPeer extends BasePeer {
       this.fail(new Error(`pi exited with ${signal ? `signal ${signal}` : `code ${code}`}`));
       this.reportExit(exit);
     });
+    const titleRevisionBefore = this.titleRevision, titleEpochBefore = this.titleEpoch;
     const state = await this.waitRpc("get_state", 15_000);
     if (state.success !== true || typeof state.data?.sessionId !== "string" || typeof state.data?.sessionFile !== "string" || !state.data.sessionId || !state.data.sessionFile) throw new Error("Pi get_state did not prove session identity");
     if ((this.opts.sessionId && state.data.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && state.data.sessionFile !== this.opts.sessionFile)) {
@@ -472,6 +580,7 @@ export class PiPeer extends BasePeer {
     }
     this.persistedOnce = existsSync(this.sessionFile);
     if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) throw new Error("Pi startup session identity mismatch");
+    this.observeSnapshotTitle(state.data, titleRevisionBefore, titleEpochBefore);
     this.started = true;
     this.setState("idle");
   }
@@ -542,9 +651,11 @@ export class PiPeer extends BasePeer {
     if (!this.fencedPrompt) throw new Error("Pi roster return needs a fenced-prompt extension; restart the retained terminal with the current hub extension");
     if (this.pendingPromptId) throw new Error("Pi prompt admission is still pending; wait before reverifying the retained terminal");
     const epoch = this.rosterEpoch, lifecycle = this.rosterLifecycleRevision, session = this.sessionId, file = this.sessionFile;
+    const titleRevisionBefore = this.titleRevision, titleEpochBefore = this.titleEpoch;
     const snapshot = await this.sendTui({ type: "get_session_state" });
     if (epoch !== this.rosterEpoch || this.stopping || !this.verifiedOwner() || this.activeTools || snapshot?.sessionId !== session || snapshot?.sessionFile !== file || typeof snapshot?.idle !== "boolean") throw new Error("Pi roster return could not verify the current native session");
     if (lifecycle !== this.rosterLifecycleRevision) throw new Error("Pi native activity changed during roster return; retry with a fresh session snapshot");
+    this.observeSnapshotTitle(snapshot, titleRevisionBefore, titleEpochBefore);
     this.rosterDetached = false;
     this.hubPromptId = undefined; this.hubPromptGeneration = undefined;
     this.rosterUnownedRun = !snapshot.idle; this.agentRunning = !snapshot.idle;
@@ -552,12 +663,12 @@ export class PiPeer extends BasePeer {
     if (!snapshot.idle) this.clearWatchdog();
   }
 
-  async stop(reason?: string): Promise<void> {
+  async stop(reason?: string, failureCause?: DeliveryFailureCause): Promise<void> {
     if (reason !== undefined) this.requestedStopReason = reason;
     this.rosterEpoch++;
     this.terminalOwnerObservation = undefined;
     this.stopping = true; // fence new calls before withdrawing both turn and idle-shell execution
-    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: reason ?? "Pi session stopped before settlement" });
+    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: reason ?? "Pi session stopped before settlement", ...(failureCause ? { failureCause } : {}) });
     this.activeDeliveryIds.clear();
     const settling = this.abortTools();
     let unsettled: unknown;
@@ -650,8 +761,9 @@ export class PiPeer extends BasePeer {
       this.noteActivity();
       attempted = true;
       if (deliveryId) this.activeDeliveryIds.add(deliveryId);
-      if (this.opts.mode === "tui") { const pending = this.sendTui({ type: "prompt", message: renderDigest(envs, true) }); promptId = this.pendingPromptId; await pending; }
-      else await this.sendRpc({ type: "prompt", message: renderDigest(envs, true) });
+      const message = [envs.some(env => env.private || remoteEnvelope(env)) ? undefined : this.opts.titlePreface?.(), renderDigest(envs, true)].filter(Boolean).join("\n");
+      if (this.opts.mode === "tui") { const pending = this.sendTui({ type: "prompt", message }); promptId = this.pendingPromptId; await pending; }
+      else await this.sendRpc({ type: "prompt", message });
       if (promptId !== undefined && promptId !== this.pendingPromptId) return;
       if (this.fencedPrompt && this.rosterDetached) {
         if (deliveryId && this.activeDeliveryIds.delete(deliveryId)) this.delivery({ id: deliveryId, state: "needs_review", reason: "Pi native activity changed before prompt acceptance was confirmed" });
@@ -780,10 +892,15 @@ export class PiPeer extends BasePeer {
       this.sessionId = String(event.sessionId ?? ""); this.sessionFile = String(event.sessionFile ?? "");
       this.ownerPid = Number.isInteger(event.pid) ? event.pid : undefined; this.ownerSignature = typeof event.signature === "string" ? event.signature : undefined;
       if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) { this.opts.log?.(`[${this.id}] Pi session identity mismatch`); return; }
+      this.titleRevision = -1; this.titleEpoch++;
+      this.nativeTitleEpoch = typeof event.titleEpoch === "string" && event.titleEpoch ? event.titleEpoch : undefined;
+      this.observeTitle(event.sessionName, event.titleRevision, event.titleEpoch);
       this.rememberTerminalOwner();
       this.startOwnerMonitor(); if (this.opts.mode === "tui") { this.started = true; this.setState("idle"); }
     }
+    if ((event.type === "session_title" || event.type === "agent_start" && Object.hasOwn(event, "sessionName")) && event.sessionId === this.sessionId && this.verifiedOwner()) this.observeTitle(event.sessionName, event.titleRevision, event.titleEpoch);
     if (event.type === "session_shutdown") {
+      this.observedTitle = undefined; this.titleRevision = -1; this.nativeTitleEpoch = undefined; this.onDoing?.("reset");
       const exit = this.exitMetadata("session_shutdown");
       this.shutdownExit ??= exit; // headless waits for the OS exit, retaining the pre-cleanup turn and stop facts
       this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor(); this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
@@ -872,10 +989,17 @@ export class PiPeer extends BasePeer {
     while ((index = this.buffer.indexOf("\n")) >= 0) { const line = this.buffer.slice(0, index).replace(/\r$/, ""); this.buffer = this.buffer.slice(index + 1); if (!line) continue; try { this.handleRpc(JSON.parse(line) as RpcMessage); } catch (error) { this.opts.log?.(`[${this.id}] invalid Pi RPC output: ${(error as Error).message}`); } }
   }
   private nextTuiCommand(timeout: number): Promise<Record<string, unknown> | undefined> {
-    const next = this.tuiQueue.shift(); if (next) return Promise.resolve(next);
+    let next = this.tuiQueue.shift();
+    while (next) {
+      const pending = this.tuiCommands.get(String(next.id));
+      if (pending && pending.current?.() !== false) { pending.onDispatch?.(); return Promise.resolve(next); }
+      if (pending) { this.tuiCommands.delete(String(next.id)); pending.reject(new Error("Pi session title admission changed before dispatch")); }
+      next = this.tuiQueue.shift();
+    }
     return new Promise((resolvePromise) => { const entry = { resolve: resolvePromise, timer: setTimeout(() => { const i = this.tuiWaiters.indexOf(entry); if (i >= 0) this.tuiWaiters.splice(i, 1); resolvePromise(undefined); }, timeout) }; this.tuiWaiters.push(entry); });
   }
-  private sendTui(command: Record<string, unknown>): Promise<any> {
+  private sendTui(command: Record<string, unknown>, current?: () => boolean, onDispatch?: () => void): Promise<any> {
+    if (current?.() === false) return Promise.reject(new Error("Pi session title admission changed before dispatch"));
     const id = `ahub-${++this.seq}`;
     const fenced = this.fencedPrompt && command.type === "prompt";
     if (fenced) { this.pendingPromptId = id; this.hubPromptId = id; this.hubPromptGeneration = undefined; }
@@ -886,9 +1010,9 @@ export class PiPeer extends BasePeer {
         this.tuiQueue = this.tuiQueue.filter((queued) => queued.id !== id);
         reject(new Error(`Pi TUI ${String(command.type)} acknowledgement timed out`));
       }, 30_000);
-      this.tuiCommands.set(id, { command: wire, resolve: (value) => { clearTimeout(timer); resolvePromise(value); }, reject: (error) => { clearTimeout(timer); reject(error); } });
+      this.tuiCommands.set(id, { command: wire, current, onDispatch, resolve: (value) => { clearTimeout(timer); resolvePromise(value); }, reject: (error) => { clearTimeout(timer); reject(error); } });
       const waiter = this.tuiWaiters.shift();
-      if (waiter) { clearTimeout(waiter.timer); waiter.resolve(wire); } else this.tuiQueue.push(wire);
+      if (waiter) { clearTimeout(waiter.timer); onDispatch?.(); waiter.resolve(wire); } else this.tuiQueue.push(wire);
     });
   }
   private handleRpc(message: RpcMessage): void { if (this.acceptingTools && ["message_update", "tool_execution_update"].includes(message.type ?? "") && this.state === "busy") this.touch();  if (message.type === "agent_settled") return; // The authenticated extension is the single lifecycle source.
@@ -965,11 +1089,11 @@ export class PiPeer extends BasePeer {
     await this.terminateFailedTurn(new ApprovalWaitStop(reason));
   }
 
-  private async terminateFailedTurn(error: Error): Promise<void> {
+  private async terminateFailedTurn(error: Error, failureCause?: DeliveryFailureCause): Promise<void> {
     const envs = this.activeEnvs.slice(), reply = this.currentReply;
     this.stopping = true;
     try {
-      await this.stop();
+      await this.stop(undefined, failureCause);
       // The process exit handler may already have reported this failure.
       if (this.activeEnvs.length) this.fail(error);
     } catch (stopError) {
@@ -987,7 +1111,7 @@ export class PiPeer extends BasePeer {
   protected override onWatchdog(): void {
     if (this.stopping || this.rosterDetached || this.rosterUnownedRun) return;
     if (this.activeTools) { this.touch(); return; }
-    void this.terminateFailedTurn(new Error("Pi run became inactive before agent_settled"));
+    void this.terminateFailedTurn(new Error("Pi run became inactive before agent_settled"), "timeout");
   }
 }
 

package/src/adapters/registry-types.ts

@@ -81,6 +81,10 @@ export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   daemon: Ports;
 }
 
+/** `native-stop`: Claude's transcript-verified Stop. `turn-completed`: Codex's `turn/completed` with no active turn. `agent-settled`: Pi's own settled event. `route-outcome`: the local worker's per-decision outcome. `prompt-response`: an ACP `session/prompt` response. `message-stop`: Qwen's TUI `message_stop`. */
+export type SettleSignal = "native-stop" | "turn-completed" | "agent-settled" | "route-outcome" | "prompt-response" | "message-stop";
+export const SETTLE_SIGNALS: readonly SettleSignal[] = Object.freeze(["native-stop", "turn-completed", "agent-settled", "route-outcome", "prompt-response", "message-stop"]);
+
 export interface StartRequest {
   instance: string;
   form?: StartForm;
@@ -204,6 +208,18 @@ export interface AdapterDefinition {
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin"; currentChild?: true };
+  /** Who owns the session title; only hub-owned slots receive hub_set_title. */
+  title?: "native" | "hub";
+  /** Fixed builtins only: the title slot survives native-session restoration. Absent means ephemeral. */
+  titlePersistence?: "native";
+  /** #1053: how long a `hub_ask` call waits for the person before it answers `pending` (milliseconds). MCP peers 45 s, hub-native peers 300 s; config `questions.wait_ms.<kind>` overrides it. Fixed builtins only. */
+  questionWaitMs?: number;
+  /**
+   * #1054: the code-verified signal that ends a peer's logical run, declared per definition. ABSENT means the adapter creates no completion: nothing is guessed (owner
+   * decision 2026-11-04). Fixed builtins only (`assertNativeCapabilityScope`): a project or external definition cannot claim one. A definition with a pull-only form (Kimi's TUI)
+   * declares it for its headless form only, because the daemon starts no run for a peer that attached pull-only.
+   */
+  settle?: { signal: SettleSignal };
   /** External module data-only opt-in. The verified loader derives the internal instances policy from it (#754). */
   headlessInstances?: { form: "headless"; roles: readonly ("implementer" | "verifier" | "reviewer")[] };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */

package/src/adapters/registry.ts

@@ -239,6 +239,10 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
   if (isFixedBuiltinDefinition(definition)) return;
   const declared = (block: object | undefined, key: string): boolean => block !== undefined && key in block;
   const restricted: [string, boolean][] = [
+    ["title", definition.title !== undefined],
+    ["titlePersistence", definition.titlePersistence !== undefined],
+    ["questionWaitMs", definition.questionWaitMs !== undefined],
+    ["settle", definition.settle !== undefined],
     ["start.acpCommand", declared(definition.start, "acpCommand")],
     ["attach.admission", declared(definition.attach, "admission")],
     ["budget.resetSoftTokensOnResume", declared(definition.budget, "resetSoftTokensOnResume")],

package/src/adapters/reviewer-print.ts

@@ -1,8 +1,9 @@
 import type { ChildProcess } from "node:child_process";
-import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
+import { OwnedPrintChild, PrintChildCleanupError, type OwnedInputContext, type OwnedInputObserver } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
 import { HUB, frame, sanitize } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
+import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import type { ReviewerMcpSession, ReviewerToolName } from "./reviewer-mcp.ts";
 
@@ -31,6 +32,7 @@ export class ReviewerUnavailableError extends Error {
 class ReviewerAdmissionError extends Error {
   constructor(readonly reason: "stale_binding" | "policy_changed") { super("review admission changed"); }
 }
+class ReviewerInputAdmissionError extends Error {}
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -136,6 +138,13 @@ export interface ReviewerPrintOptions {
   /** Synchronous host task/privacy/policy fence, checked again after awaited preparation. */
   admit?(env: Envelope): boolean;
   bindingCurrent?(task: number, binding: ReviewerReviewBinding): boolean;
+  /** Private-profile observer input provenance only; never a native resume or budget identity. */
+  beforeInput?: OwnedInputObserver;
+  inputReleased?: OwnedInputObserver;
+  /** Host privacy state for the currently attached reviewer input, read only for diagnostics. */
+  reviewObserverHeld?(): boolean;
+  /** Runs after this fresh child group, task MCP and launch cleanup are confirmed closed. */
+  inputFinished?: OwnedInputObserver;
 }
 
 type ReviewTarget = Omit<ReviewerFailure, "cause">;
@@ -166,9 +175,13 @@ export class ReviewerPrintPeer extends BasePeer {
   private batch: ReviewBatch | undefined;
   private preparation: { abort: AbortController; done: Promise<ReviewerLaunch> } | undefined;
   private receipt: ReviewerIsolationReceipt | undefined;
+  private observerSessionIdValue: string | undefined;
   get isolationReceipt(): ReviewerIsolationReceipt | undefined { return this.receipt; }
+  reviewObserverInputHeld(): boolean { return this.opts.reviewObserverHeld?.() ?? false; }
   /** The task whose review the running child was started for (R4: the hub records `fresh` for its verdict). */
   reviewing: number | undefined;
+  /** Privacy-only identity for a fresh review profile; never part of resume or budget authority. */
+  get observerSessionId(): string | undefined { return this.observerSessionIdValue; }
   private reviewSeq = 0;
   private runningBinding: { task: number; binding: ReviewerReviewBinding } | undefined;
   private activeTrace: { task: number; generation: number; value: ReviewerTraceState } | undefined;
@@ -234,16 +247,16 @@ export class ReviewerPrintPeer extends BasePeer {
     this.setState("offline");
   }
 
-  protected override onWatchdog(): void { this.abortReview("review watchdog timeout"); }
+  protected override onWatchdog(): void { this.abortReview("review watchdog timeout", "timeout"); }
 
-  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded" | "review policy changed"): void {
+  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded" | "review policy changed", failureCause?: DeliveryFailureCause): void {
     const generation = ++this.generation, batch = this.batch, preparation = this.preparation;
     this.reviewing = undefined;
     this.reviewMcpClose?.();
     this.receipt = undefined;
     this.clearWatchdog();
     preparation?.abort.abort();
-    this.settle("needs_review", reason);
+    this.settle("needs_review", reason, failureCause);
     // Revoke first, then confirm both preparation and the model's whole group are gone before fallback.
     void (async () => {
       if (preparation) await preparation.done.catch(() => {});
@@ -288,6 +301,11 @@ export class ReviewerPrintPeer extends BasePeer {
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
+        if (error instanceof ReviewerInputAdmissionError) {
+          failure = { state: started ? "needs_review" : "failed_safe", reason: "review input provenance unavailable" };
+          batch.next = envs.length;
+          break;
+        }
         if (error instanceof ReviewerAdmissionError) {
           this.opts.log?.(`[${this.id}] review of task #${task} skipped: ${error.reason === "stale_binding" ? "stale binding" : "review policy changed"}`);
           if (error.reason === "policy_changed") {
@@ -395,18 +413,30 @@ export class ReviewerPrintPeer extends BasePeer {
     let facts: string | undefined;
     try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
     const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
+    const sessionId = randomUUID();
+    const inputContext: OwnedInputContext = Object.freeze({ sessionId, inputId: randomUUID() });
+    this.observerSessionIdValue = sessionId;
+    try { this.opts.beforeInput?.(inputContext, [env]); }
+    catch { this.observerSessionIdValue = undefined; throw new ReviewerInputAdmissionError(); }
     let launch: ReviewerLaunch | undefined;
     const trace: ReviewerTraceState = { reviewCalled: false };
     this.activeTrace = { task, generation, value: trace };
     const mcp = this.opts.backend.taskMcp ? this.opts.taskMcp?.(task, () => generation === this.generation && this.reviewToken(task) !== undefined && this.opts.bindingCurrent?.(task,binding) !== false) : undefined;
-    let mcpClosed=false;
-    const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
+    let mcpClosed = false, mcpCloseConfirmed = false;
+    const closeMcp = () => {
+      if (mcpClosed) return;
+      mcpClosed = true;
+      try { mcp?.close(); mcpCloseConfirmed = true; }
+      catch { this.opts.log?.(`[${this.id}] reviewer task MCP cleanup incomplete`); }
+      if (this.reviewMcpClose === closeMcp) this.reviewMcpClose = undefined;
+    };
     this.reviewMcpClose=closeMcp;
     let ownedChild: OwnedPrintChild | undefined, releasing: Promise<void> | undefined;
+    let inputReleased = false, childClosed = false, launchCleanupConfirmed = false;
     let policyTimer: ReturnType<typeof setInterval> | undefined;
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
-    launch = await this.prepare(randomUUID(), input, task, mcp?.config);
+    launch = await this.prepare(sessionId, input, task, mcp?.config);
     if (generation !== this.generation) throw new ReviewerAdmissionError("stale_binding");
     this.assertAdmission(env, task, binding);
     if (launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation changed before child spawn", "binary");
@@ -415,6 +445,7 @@ export class ReviewerPrintPeer extends BasePeer {
     const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
       cwd: launch.cwd ?? this.opts.cwd, env: launch.env, envMode: launch.envMode, input,
       current: () => generation === this.generation, stop: launch.stop,
+      onInputReleased: () => { inputReleased = true; this.opts.inputReleased?.(inputContext, [env]); },
       onError: () => { if (this.child === child) this.child = undefined; },
       onSpawn: () => {
         this.runningBinding={task,binding};
@@ -441,21 +472,29 @@ export class ReviewerPrintPeer extends BasePeer {
     this.childCleanup = release;
     this.childCurrent = launch.watchCurrent ? launch.current : undefined;
     const code = await child.done;
+    childClosed = true;
     if (this.child === child) this.child = undefined;
     return { code, quota, trace };
     } finally {
       if (this.activeTrace?.value === trace) this.activeTrace = undefined;
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
-      try { if (!ownedChild || this.child !== ownedChild) { await release(); if (this.childCleanup === release) this.childCleanup = undefined; } }
-      catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
+      try {
+        if (!ownedChild || this.child !== ownedChild) {
+          await release(); if (this.childCleanup === release) this.childCleanup = undefined;
+          launchCleanupConfirmed = true;
+        }
+      } catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
+      const closedWithoutChild = !ownedChild || ownedChild.process.pid === undefined;
+      if (mcpCloseConfirmed && launchCleanupConfirmed && (closedWithoutChild || inputReleased && childClosed))
+        try { this.opts.inputFinished?.(inputContext, [env]); } catch { /* receipt cleanup never changes the review verdict */ }
     }
   }
 
-  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string): void {
+  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string, failureCause?: DeliveryFailureCause): void {
     const id = this.activeDeliveryId;
     this.activeDeliveryId = undefined;
-    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
+    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}), ...(failureCause ? { failureCause } : {}) });
   }
 
   /** Revokes the verdict authority at once, then stops the child; on failure the handle is kept and the error thrown. */

package/src/broker/server.ts

@@ -25,6 +25,7 @@ export interface BrokerOptions {
 interface Client {
   ws?: ServerWebSocket<Client>;
   room: string;
+  ephemeral: boolean;
   challenge: BrokerChallenge;
   phase: "challenge" | "authenticating" | "roster" | "ready" | "closed";
   busy: boolean;
@@ -35,6 +36,9 @@ interface Client {
   rosterDigest?: string;
   rosterDeadline?: number;
   inFlight?: string;
+  inFlightEphemeral?: boolean;
+  inFlightExpiresAt?: number;
+  inFlightEpoch?: string;
 }
 export interface BrokerRuntime {
   readonly port: number;
@@ -104,8 +108,12 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
   function close(client: Client, code: string): void {
     if (client.phase === "closed") return;
     client.phase = "closed";
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     queuedBytes -= client.inboxBytes; client.inboxBytes = 0; client.inbox.length = 0;
-    if (client.member && members.get(memberKey(client)) === client) members.delete(memberKey(client));
+    if (client.member && members.get(memberKey(client)) === client) {
+      members.delete(memberKey(client));
+      try { store.disconnect(client.room, client.member); } catch { emit("refused", client, "state_unavailable"); }
+    }
     if (client.ws) { try { client.ws.close(4403, code); } catch { /* already closed */ } }
     else clients.delete(client);
   }
@@ -117,9 +125,9 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     close(client, "backpressure"); return false;
   }
   const control = (client: Client, value: unknown) => send(client, canonicalBytes(value));
-  function refused(client: Client, code: string, terminal = true): void {
+  function refused(client: Client, code: string, terminal = true, digest?: string): void {
     emit("refused", client, code);
-    control(client, { v: 1, type: "error", code });
+    control(client, { v: 1, type: "error", code, ...(code === "queue_full" && digest ? { digest } : {}) });
     if (terminal) close(client, code);
   }
   function active(client: Client): VerifiedPublicRoster {
@@ -133,16 +141,29 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     const roster = active(client);
     client.phase = "roster"; client.rosterDigest = roster.digest;
     client.rosterDeadline = now() + BROKER_SOCKET_LIMITS.rosterAckMs;
-    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest });
+    // Legacy hubs have a closed ready grammar; advertise only after HTTP opt-in.
+    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}) });
   }
   function pump(client: Client): void {
     if (stopping || client.phase === "closed" || !client.member) return;
-    active(client);
+    const roster = active(client);
     const next = store.next(client.room, client.member);
-    if (client.inFlight && next?.digest === client.inFlight) return;
-    client.inFlight = undefined; // the previous packet may have expired or been purged.
+    if (client.inFlightEphemeral && client.inFlightEpoch !== roster.epoch) {
+      const previous = store.current(client.room)?.previous;
+      client.inFlightExpiresAt = previous && previous.roster.epoch === client.inFlightEpoch
+        ? Math.min(client.inFlightExpiresAt ?? 0, previous.expiresAt) : 0;
+    }
+    // Replacement retires an ephemeral queue row, not the packet already handed
+    // to this socket. Keep its slot until ACK or its original TTL/grace deadline.
+    if (client.inFlight && (client.inFlightEphemeral && now() < (client.inFlightExpiresAt ?? 0) || next?.digest === client.inFlight)) return;
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined; // durable expiry/purge still releases its slot.
     if (client.phase !== "ready" || !next) return;
-    if (send(client, next.wire)) client.inFlight = next.digest;
+    if (send(client, next.wire)) {
+      client.inFlight = next.digest;
+      const frame = decodeFrame(next.wire);
+      client.inFlightEphemeral = frame.ephemeral === true;
+      client.inFlightExpiresAt = next.expiresAt; client.inFlightEpoch = frame.epoch;
+    }
   }
   function safePump(client: Client): void {
     try { pump(client); } catch (error) { refused(client, errorCode(error)); }
@@ -195,9 +216,19 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const selected = state && (header.epoch === state.current.epoch ? state.current : state.previous?.roster);
       if (!selected) throw new BrokerServerError("wrong_epoch");
       const proof = await (ports.verifyFrame ?? verifyPublicFrame)({ wire: bytes, roster: selected });
-      active(client);
-      const result = store.enqueue(proof, client.member!); // latest membership/grace/caps checked transactionally.
-      control(client, { v: 1, type: "stored", digest: result.digest, seq: proof.seq, duplicate: result.duplicate });
+      const onlineRecipients = proof.recipients.filter(recipient => {
+        const target = members.get(`${client.room}|${recipient}`);
+        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral);
+      });
+      try {
+        active(client);
+        const result = store.enqueue(proof, client.member!, onlineRecipients); // latest membership/grace/caps checked transactionally.
+        control(client, { v: 1, type: "stored", digest: result.digest, seq: proof.seq, duplicate: result.duplicate });
+      } catch (error) {
+        if (errorCode(error) !== "queue_full") throw error;
+        refused(client, "queue_full", false, client.ephemeral ? proof.digest : undefined);
+        return;
+      }
       for (const recipient of proof.recipients) {
         const target = members.get(`${client.room}|${recipient}`);
         if (target) safePump(target);
@@ -215,7 +246,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (packet.digest !== client.inFlight) { refused(client, "unexpected_ack", false); return; }
     active(client);
     store.ack(client.room, client.member!, packet.digest);
-    client.inFlight = undefined;
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     control(client, { v: 1, type: "queue_ack", digest: packet.digest });
     safePump(client);
   }
@@ -259,7 +290,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
           const room = roomId(url.pathname.slice("/v1/rooms/".length));
           if (clients.size >= BROKER_SOCKET_LIMITS.connections) return new Response("busy", { status: 503 });
           const current = store.current(room)?.current;
-          const client: Client = { room, challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
+          const client: Client = { room, ephemeral: req.headers.get("x-agent-hub-ephemeral") === "1", challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
           clients.add(client);
           if (host.upgrade(req, { data: client })) return;
           clients.delete(client); return new Response("websocket required", { status: 400 });