@staix/agent-hub 0.12.20 → 0.12.22

package/src/adapters/pi.ts

@@ -8,17 +8,30 @@ import { BasePeer } from "../hub/peers.ts";
 import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
-import { toolResultFailed } from "../local/tools.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";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
 export interface PiToolSchema { name: string; description?: string; parameters: Record<string, unknown>; }
 export interface PiRelay { url: string; token: string; models: PiModelDescriptor[]; }
+export interface PiExit {
+  cause: "process_exit" | "spawn_error" | "session_shutdown" | "owner_lost" | "owner_stopped";
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  expected: boolean;
+  started: boolean;
+  turnActive: boolean;
+  toolActive: boolean;
+  lastToolName?: string;
+}
+export interface PiToolContext { userBash: boolean; isCurrent: () => boolean; onApproval: (provenance: ApprovalProvenance) => void; }
+export interface PiToolResult { text: string; exitCode: number | null; }
+class PiToolSettlementFailure extends Error {}
 export interface PiOptions {
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
-  relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal) => Promise<string>; tools: PiToolSchema[];
+  relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal, context?: PiToolContext) => Promise<string | PiToolResult>; tools: PiToolSchema[];
   preamble?: string;
   selectModel?: (envs: Envelope[]) => Promise<string | undefined>; maxSteps?: number;
   /** Atomic task/run admission immediately before provider requests or tool execution. */
@@ -28,6 +41,9 @@ export interface PiOptions {
   /** `ceiling` is the validated, session/turn-bound tool-step ceiling signal (#179), present only when the trusted extension emitted one for this turn. */
   onTurnFailure?: (envs: Envelope[], reason: string, ceiling?: PiToolStepCeiling) => Promise<void>;
   watchdogMs?: number; log?: (line: string) => void;
+  /** Once per owner, after it is offline; a TUI owner may have unknown OS exit status. */
+  onExit?: (exit: PiExit) => void;
+  onApprovalStop?: (reason: string) => void;
   /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
   stopGraceMs?: number;
 }
@@ -65,8 +81,17 @@ export class PiPeer extends BasePeer {
   private persistedOnce = false;
   private activeEnvs: Envelope[] = [];
   private activeTools = 0;
+  private readonly pendingToolGenerations = new Map<string, { generation: number; abort: AbortController; settled: Promise<void> }>();
+  private readonly abortedToolIds = new Set<string>();
+  private abortIdsOverflow = false;
   private readonly activeDeliveryIds = new Set<string>();
   private agentRunning = false;
+  private approvalExpiries = 0;
+  private approvalAnswerEpoch: number | undefined;
+  private approvalTurnAbort = false;
+  private approvalAbortSent = false;
+  private approvalStopReason = "";
+  private requestedStopReason: string | undefined;
   private owner = randomUUID();
   private _tuiLaunch?: PiTuiLaunch;
   private requestedModel = "";
@@ -74,6 +99,10 @@ export class PiPeer extends BasePeer {
   private ownerClaimed = false;
   private ownerToken = "";
   private stopping = true;
+  private exitReported = false;
+  private started = false;
+  private lastToolName?: string;
+  private shutdownExit?: PiExit;
   private ownerPid?: number;
   private ownerSignature?: string;
   private ownerMonitor?: ReturnType<typeof setInterval>;
@@ -164,11 +193,18 @@ export class PiPeer extends BasePeer {
   }
   private async handleToolRequest(body: any): Promise<Response> {
     if (this.stopping || this.state === "offline") return Response.json({ text: "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) {
+      const text = "error: Pi tool lineage is missing, stale or unverified; restart Pi with the current hub extension before retrying";
+      this.opts.log?.(`[${this.id}] ${text}`);
+      return Response.json({ text, failed: true }, { status: 409 });
+    }
+    if (this.abortIdsOverflow || this.abortedToolIds.has(String(body.toolCallId))) return Response.json({ text: "error: tool call cancelled before execution", failed: true });
+    if (this.pendingToolGenerations.has(String(body.toolCallId ?? ""))) return Response.json({ text: "error: this Pi tool call is already in progress", failed: true }, { status: 409 });
     let executionSignal = this.executionAbort?.signal;
     let idleBashTimer: ReturnType<typeof setTimeout> | undefined;
     if (body.purpose === "idle_user_bash") {
       const reservation = typeof body.reservation === "string" ? this.idleBashReservations.get(body.reservation) : undefined;
-      if (!reservation || reservation.expiresAt < Date.now() || reservation.generation !== body.generation || !this.ownerClaimed || this.ownerPid === undefined || this.state !== "idle" || this.agentRunning || this.activeTools > 0 || this.activeEnvs.length > 0 || !Number.isSafeInteger(body.generation) || body.generation !== this.budgetGeneration) return Response.json({ text: "error: stale or non-idle Pi user shell request" }, { status: 409 });
+      if (this.opts.mode !== "tui" || !this.verifiedOwner() || !reservation || reservation.expiresAt < Date.now() || reservation.generation !== body.generation || !this.ownerClaimed || this.ownerPid === undefined || this.state !== "idle" || this.agentRunning || this.activeTools > 0 || this.activeEnvs.length > 0 || !Number.isSafeInteger(body.generation) || body.generation !== this.budgetGeneration) return Response.json({ text: "error: stale or non-idle Pi user shell request" }, { status: 409 });
       if (reservation.deadlineAt !== undefined && reservation.deadlineAt <= Date.now()) {
         this.idleBashReservations.delete(String(body.reservation));
         return Response.json({ text: "error: Pi user shell execution budget expired" }, { status: 409 });
@@ -179,17 +215,60 @@ export class PiPeer extends BasePeer {
       if (reservation.deadlineAt !== undefined) idleBashTimer = setTimeout(() => idleBashAbort.abort(), Math.max(0, reservation.deadlineAt - Date.now()));
     }
     this.noteActivity();
+    const generation = this.budgetGeneration;
+    const turnSignal = this.executionAbort?.signal;
+    const parentSignal = executionSignal;
+    const toolAbort = new AbortController();
+    const abortTool = () => toolAbort.abort();
+    parentSignal?.addEventListener("abort", abortTool, { once: true });
+    if (parentSignal?.aborted) abortTool();
+    executionSignal = toolAbort.signal;
+    const callId = String(body.toolCallId ?? "");
+    let settled!: () => void;
+    const settlement = new Promise<void>((resolve) => { settled = resolve; });
+    this.pendingToolGenerations.set(callId, { generation, abort: toolAbort, settled: settlement });
+    const name = String(body.name);
+    this.lastToolName = this.opts.tools.some((tool) => tool.name === name) && /^[a-zA-Z0-9_.-]{1,128}$/.test(name) ? name : "unknown";
     this.activeTools++;
     if (this.state === "idle") this.setState("busy");
     if (this.state === "busy") this.touch();
     // `failed` is the managed-tool failure verdict (toolResultFailed, the one contract): Pi 1.0.1
     // classifies a native tool result by isError === true alone, so the extension needs the flag,
     // not just the text (#181). An older extension simply ignores the extra field.
-    try { const text = await this.opts.executeTool(String(body.name), body.args, String(body.toolCallId ?? ""), this.sessionId, executionSignal); return Response.json({ text, failed: toolResultFailed(String(body.name), text) }); }
+    try {
+      const result = await this.opts.executeTool(name, body.args, callId, this.sessionId, executionSignal, {
+        userBash: body.purpose === "idle_user_bash",
+        isCurrent: () => generation === this.budgetGeneration && !this.stopping && this.state !== "offline" && !executionSignal?.aborted && !this.approvalStopReason && this.verifiedOwner() && (body.purpose === "idle_user_bash" ? this.opts.mode === "tui" : turnSignal === this.executionAbort?.signal),
+        onApproval: (provenance) => {
+          if (!this.agentRunning || generation !== this.budgetGeneration || turnSignal !== this.executionAbort?.signal || this.approvalStopReason) return;
+          if (this.approvalAnswerEpoch !== provenance.answerEpoch) {
+            this.approvalExpiries = 0; this.approvalAnswerEpoch = provenance.answerEpoch;
+          }
+          if (provenance.source === "person") this.approvalExpiries = 0;
+          if (provenance.source === "expired" && provenance.eligibleExpiry !== false && ++this.approvalExpiries >= 2) {
+            this.approvalStopReason = "Pi turn stopped after two unanswered approvals; no person answered. Do not retry the calls; inspect prior work before handoff or stopping.";
+            try { this.opts.onApprovalStop?.(this.approvalStopReason); } catch { /* stop remains authoritative */ }
+          }
+        },
+      });
+      const text = typeof result === "string" ? result : result.text;
+      return Response.json({ text, failed: typeof result !== "string" && result.exitCode !== null ? result.exitCode !== 0 : toolResultFailed(name, text), ...(typeof result === "string" ? {} : { exitCode: result.exitCode }) });
+    }
     catch (error) { return Response.json({ text: `error: ${(error as Error).message}`, failed: true }, { status: 200 }); }
     finally {
       clearTimeout(idleBashTimer);
       this.activeTools--;
+      parentSignal?.removeEventListener("abort", abortTool);
+      if (this.pendingToolGenerations.get(callId)?.abort === toolAbort) this.pendingToolGenerations.delete(callId);
+      settled();
+      if (this.approvalStopReason && !this.approvalAbortSent) {
+        this.approvalAbortSent = true;
+        const reason = this.approvalStopReason;
+        // Finish this request's expiry reply before withdrawing siblings and aborting the native turn.
+        setTimeout(() => {
+          if (this.agentRunning && generation === this.budgetGeneration && this.approvalStopReason === reason && !this.stopping) void this.endApprovalTurn(generation, reason);
+        }, 10);
+      }
       if (this.state === "busy") {
         if (!this.activeTools && !this.agentRunning && !this.activeEnvs.length) this.setState("idle");
         else this.touch();
@@ -200,12 +279,14 @@ export class PiPeer extends BasePeer {
   private async handleBudgetRequest(body: any): Promise<Response> {
     if (!["model_calls", "tool_calls"].includes(String(body.unit))) return Response.json({ error: "invalid Pi budget unit" }, { status: 400 });
     const idleUserBash = body.idleUserBash === true;
-    const current = Number.isSafeInteger(body.generation) && body.generation === this.budgetGeneration;
-    const idleOwner = this.ownerClaimed && this.ownerPid !== undefined && this.state === "idle" && !this.agentRunning && this.activeTools === 0 && this.activeEnvs.length === 0;
-    if (!current || (idleUserBash ? !idleOwner : !this.agentRunning || this.state !== "busy")) return Response.json({ error: "stale Pi budget request" }, { status: 409 });
+    const generation = body.generation, controller = this.executionAbort, session = this.sessionId, ownerPid = this.ownerPid, ownerSignature = this.ownerSignature;
+    const current = () => Number.isSafeInteger(generation) && generation === this.budgetGeneration && controller === this.executionAbort && session === this.sessionId && ownerPid === this.ownerPid && ownerSignature === this.ownerSignature && !this.stopping && this.verifiedOwner();
+    const idleOwner = this.opts.mode === "tui" && !this.stopping && this.verifiedOwner() && this.state === "idle" && !this.agentRunning && this.activeTools === 0 && this.activeEnvs.length === 0;
+    if (!current() || (idleUserBash ? !idleOwner : !this.agentRunning || this.state !== "busy")) return Response.json({ error: "stale Pi budget request" }, { status: 409 });
     // An interactive user shell has no task delivery. It may spend an eligible run budget only.
     const envs = idleUserBash ? [] : this.budgetEnvelopes;
     const decisions = this.opts.admitBudget ? await this.opts.admitBudget(envs, body.unit as ExecutionUnit) : [];
+    if (!current() || (idleUserBash ? this.state !== "idle" || this.agentRunning || this.activeTools > 0 || this.activeEnvs.length > 0 : !this.agentRunning || this.state !== "busy")) return Response.json({ error: "Pi owner or turn changed during admission" }, { status: 409 });
     const denied = decisions.find((decision) => !decision.allowed);
     const remaining = decisions.filter((decision) => decision.unit === "elapsed_ms" && decision.remaining !== null).reduce<number | undefined>((min, decision) => min === undefined ? decision.remaining! : Math.min(min, decision.remaining!), undefined);
     let reservation: string | undefined;
@@ -230,6 +311,10 @@ export class PiPeer extends BasePeer {
 
   private async startImpl(): Promise<void> {
     this.stopping = false;
+    this.requestedStopReason = undefined;
+    this.approvalTurnAbort = false;
+    this.exitReported = false; this.started = false; this.lastToolName = undefined; this.shutdownExit = undefined;
+    this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = ""; this.approvalAbortSent = false;
     mkdirSync(this.opts.stateDir, { recursive: true });
     const sessions = join(this.opts.stateDir, "pi-sessions");
     mkdirSync(sessions, { recursive: true, mode: 0o700 });
@@ -275,22 +360,65 @@ export class PiPeer extends BasePeer {
     trackGroup(this.proc);
     this.proc.stdout.on("data", (chunk) => this.onOutput(String(chunk)));
     this.proc.stderr.on("data", (chunk) => this.opts.log?.(`[${this.id}] ${String(chunk).trimEnd()}`));
-    this.proc.on("error", (error) => this.fail(error));
-    this.proc.on("exit", (code) => { if (code !== 0) this.fail(new Error(`pi exited with code ${code}`)); else this.setState("offline"); });
+    const proc = this.proc;
+    proc.on("error", (error) => {
+      const exit = this.exitMetadata("spawn_error");
+      this.fail(error);
+      this.reportExit(exit);
+    });
+    proc.on("exit", (code, signal) => {
+      const exit = { ...(this.shutdownExit ?? this.exitMetadata("process_exit")), code, signal };
+      this.fail(new Error(`pi exited with ${signal ? `signal ${signal}` : `code ${code}`}`));
+      this.reportExit(exit);
+    });
     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)) {
       throw new Error("Pi get_state session identity does not match the requested recovery session");
     }
     this.sessionId = state.data.sessionId; this.sessionFile = state.data.sessionFile;
+    // The hub spawned this headless owner and get_state proved its session. Pin the same
+    // identity a native extension claim uses, including fakes that do not load the extension.
+    if (!this.ownerClaimed) {
+      const pid = this.proc?.pid, signature = pid ? processSignature(pid) : undefined;
+      if (!pid || !signature) throw new Error("Pi headless owner process identity is not verified");
+      this.ownerPid = pid; this.ownerSignature = signature;
+      this.ownerToken = String(this._tuiLaunch?.env.AGENTHUB_PI_OWNER_TOKEN ?? ""); this.ownerClaimed = true;
+    }
     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.started = true;
     this.setState("idle");
   }
 
-  async stop(): Promise<void> {
-    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: "Pi session stopped before settlement" });
+  private verifiedOwner(): boolean {
+    return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature;
+  }
+  private abortTools(): Promise<void>[] {
+    this.executionAbort?.abort();
+    this.idleBashReservations.clear();
+    const pending = [...this.pendingToolGenerations.values()];
+    for (const call of pending) call.abort.abort();
+    return pending.map((call) => call.settled);
+  }
+  get mode(): "headless" | "tui" { return this.opts.mode; }
+
+  async stop(reason?: string): Promise<void> {
+    if (reason !== undefined) this.requestedStopReason = reason;
+    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" });
     this.activeDeliveryIds.clear();
+    const settling = this.abortTools();
+    let unsettled: unknown;
+    if (settling.length) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await Promise.race([Promise.all(settling), new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new PiToolSettlementFailure("Pi managed tools did not settle after cancellation")), this.opts.stopGraceMs ?? 5_000); })]);
+      } catch (error) { unsettled = error; } // a tool past its grace must not block the teardown (#253): stop reports it at the end
+      finally { clearTimeout(timer); }
+    }
+    const tuiExit = this.opts.mode === "tui" && this.ownerClaimed && this.ownerPid && this.ownerSignature
+      ? { ...this.exitMetadata("owner_stopped"), expected: true } : undefined;
     this.stopping = true;
     this.clearOwnerMonitor();
     if (this.opts.mode === "tui") {
@@ -329,6 +457,8 @@ export class PiPeer extends BasePeer {
     this.pending.clear();
     this.server?.stop(true); this.server = undefined; this.setState("offline");
     if (failed) throw failed;
+    if (tuiExit) this.reportExit(tuiExit); // the verified owner is gone; never invent an exit for an unclaimed launch
+    if (unsettled) throw unsettled;
   }
 
   /**
@@ -411,19 +541,40 @@ export class PiPeer extends BasePeer {
   }
 
   private handleBridgeEvent(event: any): void {
+    if (this.stopping && ["agent_start", "agent_end", "agent_settled"].includes(event.type)) return;
     if (event.type === "session_start") {
       if (!this.ownerClaimed) { this.ownerClaimed = true; this.ownerToken = String(event.ownerToken ?? ""); }
+      this.approvalTurnAbort = event.approvalTurnAbort === true;
       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.startOwnerMonitor(); if (this.opts.mode === "tui") this.setState("idle");
+      this.startOwnerMonitor(); if (this.opts.mode === "tui") { this.started = true; this.setState("idle"); }
+    }
+    if (event.type === "session_shutdown") {
+      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;
+      this.fail(new Error("Pi session shut down before settlement"));
+      if (this.opts.mode === "tui") this.reportExit(exit);
+    }
+    if (event.type === "tool_abort" && this.agentRunning && this.ownerClaimed && this.ownerPid && this.ownerSignature
+      && processSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration
+      && typeof event.toolCallId === "string" && event.toolCallId.length > 0 && event.toolCallId.length <= 512) {
+      const pending = this.pendingToolGenerations.get(event.toolCallId);
+      if (pending && pending.generation === event.generation) pending.abort.abort();
+      else { // a native abort may arrive before its HTTP tool request; fence that call in this generation
+        // ponytail: 64 early aborts per turn; fence further calls rather than forget a cancellation.
+        // A native per-call acknowledgement would replace this bounded early-arrival cache.
+        if (this.abortedToolIds.size >= 64 && !this.abortedToolIds.has(event.toolCallId)) this.abortIdsOverflow = true;
+        else this.abortedToolIds.add(event.toolCallId);
+      }
     }
-    if (event.type === "session_shutdown") { this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor(); this.resolveTuiExit?.(); this.resolveTuiExit = undefined; this.fail(new Error("Pi session shut down before settlement")); }
     if (event.type === "agent_start") {
       const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration + 1;
       if (generation <= this.budgetGeneration) return;
       this.modelStep = 0;
-      this.usageSeen.clear(); this.idleBashReservations.clear(); this.ceilingStops.clear(); this.executionAbort = new AbortController(); this.budgetGeneration = generation; this.noteActivity(); this.agentRunning = true; this.setState("busy");
+      this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = ""; this.approvalAbortSent = false; this.abortedToolIds.clear(); this.abortIdsOverflow = false;
+      this.usageSeen.clear(); this.ceilingStops.clear(); this.abortTools(); this.executionAbort = new AbortController(); this.budgetGeneration = generation; this.noteActivity(); this.agentRunning = true; this.setState("busy");
     }
     // #179: the extension's tool-step ceiling signal. Only a schema-valid event bound to THIS session,
     // THIS turn generation and a running turn is stored; the first signal of a turn stands. Anything
@@ -457,7 +608,8 @@ export class PiPeer extends BasePeer {
       this.agentRunning = false;
       if (typeof event.text === "string" && event.text.trim()) this.settledText = event.text;
       const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration;
-      const text = this.settledText.trim(); const error = this.budgetStops.get(generation) ?? this.settledError; const cancelled = !error && this.settledCancelled;
+      const approvalStopReason = this.approvalStopReason;
+      const text = this.settledText.trim(); const error = approvalStopReason || this.budgetStops.get(generation) || this.settledError; const cancelled = !error && this.settledCancelled;
       const ceiling = this.ceilingStops.get(generation);
       this.budgetStops.delete(generation);
       this.ceilingStops.delete(generation);
@@ -467,12 +619,16 @@ export class PiPeer extends BasePeer {
       const reply = { inReplyTo: this.currentReply, to: replyAudience(this.activeEnvs) };
       if (cancelled) this.onMessage?.("Pi turn cancelled; inspect any partial effects before continuing.", reply);
       else if (error?.startsWith("execution budget")) this.onMessage?.(`Pi stopped at the execution budget: ${error}. Inspect partial work before continuing.`, reply);
+      else if (approvalStopReason) this.onMessage?.(approvalStopReason, reply);
       else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error, ceiling);
       else if (text) this.onMessage?.(text, reply);
-      for (const id of this.activeDeliveryIds) this.delivery({ id, state: error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
+      for (const id of this.activeDeliveryIds) this.delivery({ id, state: approvalStopReason ? "completed" : error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
       this.activeDeliveryIds.clear();
-      this.currentReply = undefined; this.activeEnvs = []; if (this.state === "busy" && !this.activeTools) this.setState("idle");
-      this.executionAbort = undefined;
+      this.currentReply = undefined; this.activeEnvs = [];
+      this.executionAbort?.abort(); this.executionAbort = undefined;
+      this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = ""; this.approvalAbortSent = false;
+      this.abortedToolIds.clear(); this.abortIdsOverflow = false;
+      if (this.state === "busy" && !this.activeTools) this.setState("idle");
     }
   }
 
@@ -507,15 +663,34 @@ export class PiPeer extends BasePeer {
     try { return await Promise.race([this.sendRpc({ type: command }), new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error(`Pi ${command} timed out`)), timeout); })]); }
     finally { clearTimeout(timer); }
   }
+  private exitMetadata(cause: PiExit["cause"]): PiExit {
+    return { cause, code: null, signal: null, expected: this.stopping, started: this.started,
+      turnActive: this.agentRunning || this.activeEnvs.length > 0, toolActive: this.activeTools > 0,
+      ...(this.lastToolName ? { lastToolName: this.lastToolName } : {}) };
+  }
+
+  private reportExit(exit: PiExit): void {
+    if (this.exitReported) return;
+    this.exitReported = true;
+    const line = `[${this.id}] Pi exit: cause=${exit.cause} code=${exit.code ?? "unknown"} signal=${exit.signal ?? "unknown"} expected=${exit.expected} started=${exit.started} turnActive=${exit.turnActive} toolActive=${exit.toolActive} lastTool=${exit.lastToolName ?? "none"}`;
+    try { this.opts.log?.(line); } catch { /* reporting must not prevent owner settlement */ }
+    try { this.opts.onExit?.(exit); } catch { /* the owner is already offline */ }
+  }
+
   private fail(error: Error): void {
+    const approvalStopReason = this.approvalStopReason;
+    this.abortTools();
+    this.agentRunning = false;
+    this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = ""; this.approvalAbortSent = false;
+    this.abortedToolIds.clear(); this.abortIdsOverflow = false;
     for (const pending of this.pending.values()) pending.reject(error);
     this.pending.clear();
     const envs = this.activeEnvs; this.activeEnvs = [];
     for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: error.message });
     this.activeDeliveryIds.clear();
-    if (envs.length) {
-      this.onMessage?.("Pi turn failed; inspect its session and any partial effects before continuing.", { inReplyTo: this.currentReply });
-      void this.opts.onTurnFailure?.(envs, error.message).catch(() => this.opts.log?.("Pi failure handoff could not be completed"));
+    if (envs.length && !this.requestedStopReason) {
+      this.onMessage?.(approvalStopReason ? `${approvalStopReason} Pi is offline because its extension could not abort the turn; restart with ahub pi and settle the held delivery after inspecting prior work.` : "Pi turn failed; inspect its session and any partial effects before continuing.", { inReplyTo: this.currentReply });
+      if (!approvalStopReason && !(error instanceof ApprovalWaitStop)) void this.opts.onTurnFailure?.(envs, error.message).catch(() => this.opts.log?.("Pi failure handoff could not be completed"));
     }
     this.currentReply = undefined;
     this.setState("offline");
@@ -525,15 +700,28 @@ export class PiPeer extends BasePeer {
     if (this.opts.mode !== "tui" || !this.ownerPid || !this.ownerSignature) return;
     this.ownerMonitor = setInterval(() => {
       if (!this.ownerPid || ownerStillAlive(this.ownerPid, this.ownerSignature)) return;
+      const exit = this.exitMetadata("owner_lost");
       this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor();
       this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
       for (const pending of this.tuiCommands.values()) pending.reject(new Error("Pi owner exited"));
       this.tuiCommands.clear(); this.tuiQueue = [];
       this.fail(new Error("Pi owner process exited without session_shutdown"));
+      this.reportExit(exit);
     }, 500);
     this.ownerMonitor.unref?.();
   }
   private clearOwnerMonitor(): void { if (this.ownerMonitor) clearInterval(this.ownerMonitor); this.ownerMonitor = undefined; }
+  private async endApprovalTurn(generation: number, reason: string): Promise<void> {
+    if (!this.agentRunning || generation !== this.budgetGeneration || this.approvalStopReason !== reason || this.stopping || this.state === "offline") return;
+    this.executionAbort?.abort();
+    if (this.approvalTurnAbort) {
+      try { await this.sendTui({ type: "abort_budget", generation, cause: "approval", reason }); return; }
+      catch { if (generation !== this.budgetGeneration || !this.agentRunning) return; }
+    }
+    this.opts.log?.(`[${this.id}] approval turn abort unsupported; Pi goes offline. Restart with ahub pi and settle the held delivery after inspecting prior work.`);
+    await this.terminateFailedTurn(new ApprovalWaitStop(reason));
+  }
+
   private async terminateFailedTurn(error: Error): Promise<void> {
     const envs = this.activeEnvs.slice(), reply = this.currentReply;
     this.stopping = true;
@@ -541,7 +729,12 @@ export class PiPeer extends BasePeer {
       await this.stop();
       // The process exit handler may already have reported this failure.
       if (this.activeEnvs.length) this.fail(error);
-    } catch {
+    } catch (stopError) {
+      if (stopError instanceof PiToolSettlementFailure && this.state === "offline") {
+        this.opts.log?.(`Pi teardown completed with a managed-tool settlement failure: ${(stopError as Error).message}`);
+        if (this.activeEnvs.length) this.fail(error);
+        return;
+      }
       this.activeEnvs = envs; this.currentReply = reply;
       this.stopping = true;
       this.setState("busy");