@staix/agent-hub 0.12.21 → 0.12.23

package/src/adapters/pi.ts

@@ -8,7 +8,7 @@ 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";
 
@@ -25,10 +25,13 @@ export interface PiExit {
   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. */
@@ -40,6 +43,7 @@ export interface PiOptions {
   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;
 }
@@ -77,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 = "";
@@ -180,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 });
@@ -195,6 +215,18 @@ 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++;
@@ -203,11 +235,40 @@ export class PiPeer extends BasePeer {
     // `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();
@@ -218,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;
@@ -248,7 +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 });
@@ -311,17 +377,48 @@ export class PiPeer extends BasePeer {
       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> {
+  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;
-    for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: "Pi session stopped before settlement" });
-    this.activeDeliveryIds.clear();
     this.stopping = true;
     this.clearOwnerMonitor();
     if (this.opts.mode === "tui") {
@@ -361,6 +458,7 @@ export class PiPeer extends BasePeer {
     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;
   }
 
   /**
@@ -443,8 +541,10 @@ 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; }
@@ -457,11 +557,24 @@ export class PiPeer extends BasePeer {
       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 === "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
@@ -495,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);
@@ -505,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");
     }
   }
 
@@ -560,14 +678,19 @@ export class PiPeer extends BasePeer {
   }
 
   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");
@@ -588,6 +711,17 @@ export class PiPeer extends BasePeer {
     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;
@@ -595,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");

package/src/cli/bench.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { childEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { ControlClient } from "../hub/control-client.ts";
 import { readEvents } from "../hub/events.ts";
+import { hubGitArgv, hubGitEnv } from "../hub/git.ts";
 import { taskRecords } from "../hub/research.ts";
 import { appendBench, BENCH_SCHEMA, parseSuite, suiteHash, type Attempt, type AttemptError, type AttemptMetrics, type Fingerprint, type Outcome, type SuiteTask } from "../hub/bench.ts";
 import { hubHome, realPath } from "../hub/project.ts";
@@ -30,7 +31,7 @@ const fail = (message: string): never => { throw new Error(message); };
 
 /** Commands git runs without a shell; the arguments are ours, never suite text. */
 async function git(cwd: string, args: string[]): Promise<{ code: number; out: string }> {
-  const p = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+  const p = Bun.spawn(hubGitArgv(args), { cwd, stdout: "pipe", stderr: "ignore", env: hubGitEnv() });
   const [code, out] = await Promise.all([p.exited, new Response(p.stdout).text()]);
   return { code, out: out.trim() };
 }

package/src/cli/console-state.ts

@@ -1,4 +1,4 @@
-import { PERMISSION_MODES } from "../hub/permission-mode.ts";
+import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
@@ -35,12 +35,7 @@ export function initialConsoleState(panels = false): ConsoleState {
   return { mode: panels ? "panels" : "stream", panel: 1, selection: 0,
     input: "", editing: false, history: [], historyIndex: 0, approvals: [], events: [], peers: {}, budget: {}, tasks: [], tasksKnown: false, queue: [], permissionDefaults: [], permissionDefaultsHandled: [], detailOffset: 0, help: false, notice: "" };
 }
-/** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string): string {
-  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
-  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
-  return `${peer}: runs its own tools; NO hub sandbox`;
-}
+export { permissionBoundary };
 function permissionModeRefusal(peer: string, mode: unknown): string | undefined {
   if (mode === "unmanaged") return `${peer} permission mode is unmanaged; use its native controls`;
   if (mode === "unverified") return `${peer} permission mode is unverified; start with ahub ${peer} and run a tool first`;
@@ -174,7 +169,7 @@ export function resolveColor(flag: string | undefined, env: { isTTY: boolean; TE
   if (flag === "always") return true;
   if (flag === "never") return false;
   if (flag === undefined || flag === "auto") return env.isTTY && env.TERM !== "dumb" && !env.NO_COLOR;
-  return new Error("usage: ahub console [--panels] [--color=auto|always|never]");
+  return new Error("usage: ahub <command> [--color=auto|always|never]");
 }
 export function stateTone(state: string): Tone | undefined {
   if (state === "idle" || state === "approved") return "success";
@@ -189,7 +184,7 @@ const flat = (value: unknown) => terminalText(value).replace(/[\n\t]/g, " ");
  * Clip sanitized plain text to the width and keep the tones of the surviving prefix. Widths are measured as paint()
  * prints them: paint() sanitizes each span again, and a cut that ends a span in `[agent-hub` earns it a `> `.
  */
-function fitLine(line: Span[], columns: number): Span[] {
+export function fitLine(line: Span[], columns: number): Span[] {
   const clean = line.map(s => ({ ...s, text: flat(s.text) }));
   if (Bun.stringWidth(clean.map(s => s.text).join("")) <= columns) return clean;
   const marker = ".".repeat(Math.max(0, Math.min(3, columns)));
@@ -216,7 +211,9 @@ export function fit(value: unknown, columns: number): string {
 export function wrap(value: unknown, columns: number, hang = 4): string[] {
   const lines: string[] = [];
   const half = Math.floor(columns / 2);
-  const width = (text: string) => Bun.stringWidth(sanitize(text));
+  // A bare chunk ending in "--- from" becomes a header marker when table padding follows it.
+  const quoteChunk = (text: string) => sanitize(text + " ").slice(0, -1);
+  const width = (text: string) => Bun.stringWidth(quoteChunk(text));
   for (const part of terminalText(value).replace(/\t/g, " ").split("\n")) {
     const indent = /^\s*/.exec(part)![0];
     const lead = Math.min(Bun.stringWidth(indent), half);
@@ -224,7 +221,7 @@ export function wrap(value: unknown, columns: number, hang = 4): string[] {
     const first = lines.length;
     let start = " ".repeat(lead);
     let line = start;
-    const push = () => { lines.push(sanitize(line.trimEnd())); line = start = pad; };
+    const push = () => { lines.push(quoteChunk(line.trimEnd())); line = start = pad; };
     for (const token of part.slice(indent.length).match(/\s+|\S+/g) ?? []) {
       if (width(line + token) <= columns) { line += token; continue; }
       if (line !== start) push();
@@ -234,7 +231,7 @@ export function wrap(value: unknown, columns: number, hang = 4): string[] {
         line += char;
       }
     }
-    if (line !== start || lines.length === first) lines.push(sanitize(line.trimEnd()));
+    if (line !== start || lines.length === first) lines.push(quoteChunk(line.trimEnd()));
   }
   return lines;
 }
@@ -308,7 +305,7 @@ export function permissionText(a: Pick<Approval, "id" | "peer" | "title" | "opti
 const KEYS: [string, string[]][] = [
   ["Everywhere", ["Tab stream/panels", ": command", "? keys", "Esc back", "q quit"]],
   ["Command", ["Enter run", "Esc cancel", "Up/Down history", "Ctrl-U clear"]],
-  ["Panels", ["1-5 panel", "j/k or arrows move", "Enter view", "j/k scroll a view"]],
+  ["Panels", ["1-5 panel", "Left/Right panel", "j/k or Up/Down move", "Enter view", "j/k scroll a view"]],
   ["Approvals", ["a allow (then y)", "d deny", "v view", "[ ] select"]],
   ["Peers", ["p pause", "r resume", "m permission mode"]],
   ["Tasks", ["a assign (then y)", "r review"]],
@@ -444,7 +441,11 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   if (key === "q") { effects.push({ type: "exit" }); return done(); }
   if (key === "\t") { s.mode = s.mode === "panels" ? "stream" : "panels"; s.detail = undefined; s.requestDetail = undefined; return done(); }
   if (key === ":") { s.editing = true; return done(); }
-  if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) { s.panel = Number(key); s.selection = 0; s.detail = undefined; s.requestDetail = undefined; return done(); }
+  const switchPanel = (panel: number) => { s.panel = panel; s.selection = 0; s.detail = undefined; s.requestDetail = undefined; return done(); };
+  if (s.mode === "panels" && /^[1-5]$/.test(key) && !s.optionChoice) return switchPanel(Number(key));
+  // Right and Left are the digit of the next or previous tab, wrapping at both ends (#309); the same guards as the
+  // digits apply (the confirm, mode-choice, key-table and editing branches above returned already).
+  if (s.mode === "panels" && (key === "\x1b[C" || key === "\x1b[D") && !s.optionChoice) return switchPanel((s.panel + (key === "\x1b[C" ? 0 : 3)) % 5 + 1);
   if (key === "?") {
     if (s.mode === "stream") effects.push({ type: "keys" });
     else s.help = !s.help;
@@ -522,7 +523,7 @@ export function renderConsole(s: ConsoleState, columns: number, rows = 24, now =
   return renderConsoleLines(s, columns, rows, now).map(line => paint(line, false));
 }
 const NOTICE_MS = 10_000;
-const TABLES: Record<number, string[]> = {
+export const TABLES: Record<number, string[]> = {
   1: ["PEER", "STATE", "LINK", "Q", "!", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
   2: ["ID", "PEER", "LEFT", "TITLE"],
   3: ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "TITLE", "STAGE"],
@@ -531,7 +532,7 @@ const TABLES: Record<number, string[]> = {
 const showPermissionModes = (s: ConsoleState) => Object.values(s.peers).some(peer => peer.permissionMode && peer.permissionMode !== "ask");
 const count = (n: unknown) => typeof n === "number" && n ? String(n) : "-";
 /** One span per column of a panel row; zero counters and unknown values read `-`. */
-function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
+export function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages?: Map<number, ProgressStage>): Span[] {
   const id = (text: unknown, tone: Tone | undefined) => span(text, tone && (selected ? "strong" : tone));
   if (s.panel === 1) {
     const b = s.budget[row.id];
@@ -558,19 +559,22 @@ function cells(s: ConsoleState, row: any, selected: boolean, now: number, stages
   }
   if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
   const [header, ...body] = String(row.text).split("\n");
-  return [span(header, row.tone), ...(body.length ? [span("\n" + body.join("\n"))] : [])];
+  // The header goes through the stream's own tokenizer with the event's tone and kind, on the same tab-flattened
+  // text the stream tokenizes, so an event reads the same in both places (#309); body lines stay plain, as in the
+  // stream. Colour off concatenates to the same bytes.
+  return [...streamTokens((header ?? "").replace(/\t/g, " "), row.tone, row.kind), ...(body.length ? [span("\n" + body.join("\n"))] : [])];
 }
 /**
  * A header row, then the rows, each column starting at the same place on every row: two spaces apart, as wide as its
  * widest cell or header (Bun.stringWidth, at most a third of the width, wider cells cut with the marker); the last column
- * takes the rest.
+ * takes the rest. One-shot callers may supply widths for already-wrapped cells; console defaults stay unchanged.
  */
-function table(head: string[], rows: Span[][], columns: number): Span[][] {
+export function table(head: string[], rows: Span[][], columns: number, explicitWidths?: readonly number[]): Span[][] {
   const cap = Math.max(24, Math.floor(columns / 3));
   const width = (cell: Span | undefined) => Bun.stringWidth(flat(cell?.text));
-  const widths = head.map((h, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, width(row[i])), Bun.stringWidth(h))));
+  const widths = explicitWidths ? [...explicitWidths] : head.map((h, i) => Math.min(cap, rows.reduce((max, row) => Math.max(max, width(row[i])), Bun.stringWidth(h))));
   const flexible = head.includes("STAGE") ? head.indexOf("TITLE") : head.length - 1;
-  if (head.includes("STAGE")) {
+  if (!explicitWidths && head.includes("STAGE")) {
     // Keep the original columns adjacent; stage meters occupy a fixed right-edge column.
     const room = () => columns - 2 - widths.reduce((sum, value, index) => sum + (index === flexible ? 0 : value), 0) - 2 * (head.length - 1);
     for (const key of ["CLASS", "OWNER", "REVIEWER", "AGE", "STATE"]) {
@@ -579,7 +583,9 @@ function table(head: string[], rows: Span[][], columns: number): Span[][] {
     }
     widths[flexible] = Math.max(0, room());
   }
-  return [head.map(h => span(h, "info")), ...rows].map(row => row.map((cell, i) => {
+  const headerCells = explicitWidths ? head.map((h, i) => wrap(h, Math.max(1, widths[i]!), 0)) : undefined;
+  const headers = headerCells ? Array.from({ length: Math.max(...headerCells.map(cell => cell.length)) }, (_, n) => head.map((_, i) => span(headerCells[i]![n] ?? "", "info"))) : [head.map(h => span(h, "info"))];
+  return [...headers, ...rows].map(row => row.map((cell, i) => {
     if (i === head.length - 1 && flexible === i) return cell;
     const text = fit(cell.text, widths[i]!);
     return { ...cell, text: text + " ".repeat(Math.max(0, widths[i]! - Bun.stringWidth(text)) + (i === head.length - 1 ? 0 : 2)) };

package/src/cli/console.ts

@@ -23,7 +23,7 @@ export interface ConsoleOptions {
   terminal?: ConsoleTerminal;
   color?: boolean;
   /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
-  runCommand?: (args: string[], output: (text: string) => void, done: () => void) => (() => void);
+  runCommand?: (args: string[], output: (text: string) => void, done: () => void, columns?: number) => (() => void);
   pollMs?: number;
 }
 export const RESTORE_CONSOLE = "\x1b[?1049l\x1b[r\x1b[0m\x1b[?25h";
@@ -76,13 +76,18 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
   const notice = (text: string) => notify(state, text, Date.now());
   const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
-  const streamLines = (event: ConsoleEvent) => terminalText(event.text).split("\n").flatMap((text, index) => index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]));
+  const streamLines = (event: ConsoleEvent) => terminalText(event.text).replace(/\t/g, " ").split("\n").flatMap((text, index) => {
+    // Tabs are flattened before measuring, as wrap() does; commands already wrap cells at their own offsets.
+    if (event.kind === "command" && Bun.stringWidth(text) <= columns) return [[{ text }]];
+    return index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]);
+  });
   const writeStream = (event: ConsoleEvent) => {
     terminal.write(`\x1b[${rows - 4};1H`); // the scroll region ends above the rule and the three footer lines
     for (const line of streamLines(event)) { terminal.write(paint(line, color)); terminal.write("\r\n"); }
   };
   /** `record: false` is for the console's own prints (the key table, a request viewed again): not events, so not in Events. */
   const stream = (event: ConsoleEvent, record = true) => {
+    if (event.kind === "command") event = { ...event, text: terminalText(event.text).replace(/\t/g, " ") };
     if (record) state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
     if (plain) {
       const [header, ...body] = terminalText(event.text).split("\n");
@@ -145,9 +150,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     } catch (error) { if (active) { notice(String((error as Error).message)); draw(); } }
     finally { polling = false; }
   };
-  const run = options.runCommand ?? ((args, output, finished) => {
+  const run = options.runCommand ?? ((args, output, finished, commandColumns) => {
     const child = Bun.spawn([process.execPath, fileURLToPath(new URL("./main.ts", import.meta.url)), "--project", options.cwd, ...args], {
       cwd: options.cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe",
+      env: { ...process.env, COLUMNS: String(commandColumns), NO_COLOR: "1" },
     });
     const read = async (source: ReadableStream<Uint8Array>) => {
       const decoder = new TextDecoder(); const reader = source.getReader();
@@ -188,8 +194,8 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     stream({ text: `> ${action.args.join(" ")}`, kind: "command" });
     try {
       // Output lines sit at column 4, as message bodies do: what a command prints can carry peer text, and columns 0 and 2 are the hub's.
-      const output = (text: string) => { if (active) { stream({ text: text.replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
-      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); });
+      const output = (text: string) => { if (active) { stream({ text: terminalText(text).replace(/\t/g, " ").replace(/\n$/, "").replace(/^/gm, "    "), kind: "command" }); draw(); } };
+      cancelChild = run(action.args, output, () => { childRunning = false; cancelChild = undefined; if (active) void refresh(); }, Math.max(1, columns - 4));
     } catch (error) { childRunning = false; notice(String((error as Error).message)); draw(); }
   };
   const handle = (key: string) => {
@@ -229,12 +235,16 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       terminal.raw(true);
       removers.push(terminal.onData(text => {
         // A pasted chunk can only edit text, never approve, confirm or run commands. Bracketed-paste delimiters are stripped.
-        // Under the modal key table it does nothing at all.
+        // Under the modal key table it does nothing at all. A read holding nothing but arrow sequences is that many
+        // key presses (key repeat, a slow link), not a paste (#309): each arrow reaches the reducer on its own.
         if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
-          if (state.help && state.mode === "panels") return;
-          if (state.confirm?.type === "permission_default") { draw(); return; }
-          state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
-          state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
+          if (/^(?:\x1b\[[ABCD])+$/.test(text)) { for (const key of text.match(/\x1b\[[ABCD]/g)!) handle(key); }
+          else {
+            if (state.help && state.mode === "panels") return;
+            if (state.confirm?.type === "permission_default") { draw(); return; }
+            state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
+            state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();
+          }
         } else handle(text);
       }));
       removers.push(terminal.onResize(() => {