@staix/agent-hub 0.12.21 → 0.12.22

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/help.ts

@@ -24,11 +24,11 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub doctor --orphans [--kill]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub kill", "stop this project's hub"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
-    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime"],
-    ["ahub upgrade --to <version> [--dry-run] [--yes]", "review and upgrade running projects"],
-    ["ahub recovery status|resume|abort <operation-id>", "inspect, resume or cancel a preflight; status names the next actions"],
-    ["ahub recovery dispose <operation-id> --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
-    ["ahub recovery dispose <operation-id> --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
+    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
+    ["ahub upgrade [--to <version>] [--dry-run] [--yes]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
+    ["ahub recovery [status|resume|abort] [<operation-id>]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
+    ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
+    ["ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
     ["ahub daemon [--unattended]", "internal: the detached hub process that ahub up or the dashboard manager starts"],
     ["ahub recovery-run <operation-id>", "internal: the detached runner of an upgrade, restart or recovery resume"],
   ]],
@@ -38,6 +38,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub kimi [--print-command] [--model <alias>]", "start Kimi headless under ACP"],
     ["ahub pi [--print-command] [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]", "start Pi"],
     ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
+    ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
     ["ahub models setup|status|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
   ]],
   ["Messages and approvals", [

package/src/cli/identity.ts

@@ -26,7 +26,7 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
-  if (command === "permission") return "console";
+  if (command === "permission" || command === "stop") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -47,7 +47,7 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "stop", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
     const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;

package/src/cli/launch.ts

@@ -1,10 +1,11 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
-import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomUUID, createHash } from "node:crypto";
 import { resolve, join, basename, dirname, isAbsolute } from "node:path";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
-import { peerChildEnv } from "../hub/child-process.ts";
+import { peerChildEnv, processTable } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
@@ -65,14 +66,188 @@ export function cleanupClaudeSettings(stateDir: string, previous: unknown): void
 /** Crash fallback only: an absent/unreadable owner identity never certifies that its native launch ended. */
 export function cleanupStaleClaudeSettings(stateDir: string, previous: unknown, identity = processSignature): void {
   if (!previous || typeof previous !== "object" || Array.isArray(previous)) return;
-  const record = previous as Record<string, unknown>;
+  const original = previous as Record<string, unknown>;
+  const record = readClaudeNative(stateDir, original as ClaudeLaunchRecord) ?? original;
   if (typeof record.launcherSignature !== "string" || !record.launcherSignature) return;
   if (processLiveness(record.launcherPid, record.launcherSignature, identity) !== "gone") return;
-  // ponytail: spawnSync launch records have no independent native identity, so crash-left settings are retained.
-  // Upgrade path: record the native child's PID and processSignature before admitting crash fallback cleanup.
   if (typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || record.nativePid === record.launcherPid || typeof record.nativeSignature !== "string" || !record.nativeSignature) return;
-  if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
+  if (record.nativeIdentity === "direct-child") {
+    // A direct child may exec in place. A changed signature while its PID still runs cannot certify native exit.
+    // The shared table excludes exited zombies; an unavailable table certifies nothing.
+    const table = processTable();
+    if (!table || table.some(row => row.pid === record.nativePid)) return;
+  } else if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
   cleanupClaudeSettings(stateDir, record.settingsFile);
+  removeClaudeNative(stateDir, original as ClaudeLaunchRecord);
+}
+
+export interface ClaudeLaunchRecord extends Record<string, unknown> {
+  instanceId: string; launchId: string; settingsFile?: string; launcherPid: number; launcherSignature?: string;
+}
+
+export interface ClaudeLaunchPublication { recorded: boolean; warning?: string; }
+
+/** Native attestation alone is serialized; managed hook metadata never waits on this lock. */
+async function withClaudeLaunchRecord(stateDir: string, action: () => void): Promise<ClaudeLaunchPublication> {
+  const lock = join(stateDir, "claude-launch.lock"), temp = `${lock}.${randomUUID()}.tmp`;
+  const skipped = (reason = `${lock} is busy or unverified`): ClaudeLaunchPublication => ({ recorded: false, warning: `Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}; inspect ${lock} and verify its owner has ended before removing it.` });
+  const signature = processSignature(process.pid);
+  if (!signature) return skipped("launcher identity could not be verified");
+  let locked = false, tempCreated = false, own: { dev: number; ino: number } | undefined;
+  try {
+    const fd = openSync(temp, "wx", 0o600); tempCreated = true;
+    try { writeFileSync(fd, JSON.stringify({ pid: process.pid, signature })); } finally { closeSync(fd); }
+    const stat = lstatSync(temp); own = { dev: stat.dev, ino: stat.ino };
+    const deadline = performance.now() + 250;
+    for (;;) {
+      try { linkSync(temp, lock); break; }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") return skipped();
+        let before;
+        try { before = lstatSync(lock); } catch { if (performance.now() < deadline) continue; return skipped(); }
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600 || !process.getuid || before.uid !== process.getuid()) return skipped();
+        let owner: { pid?: unknown; signature?: unknown };
+        try { owner = JSON.parse(readFileSync(lock, "utf8")); } catch { return skipped(); }
+        if (!owner || typeof owner.signature !== "string" || !owner.signature) return skipped();
+        const alive = processLiveness(owner.pid, owner.signature);
+        if (alive === "unknown") return skipped();
+        if (alive === "live") {
+          if (performance.now() >= deadline) return skipped();
+          await new Promise(resolve => setTimeout(resolve, 25)); continue;
+        }
+        const current = lstatSync(lock);
+        if (current.dev !== before.dev || current.ino !== before.ino) return skipped();
+        unlinkSync(lock);
+      }
+    }
+    locked = true;
+    unlinkSync(temp);
+    try { action(); } catch { return skipped("native attestation publication failed"); }
+    return { recorded: true };
+  } catch { return skipped("native attestation lock could not be read or published"); }
+  finally {
+    if (locked && own) {
+      try { const current = lstatSync(lock); if (current.dev === own.dev && current.ino === own.ino) unlinkSync(lock); }
+      catch { /* only our verified lock may be removed */ }
+    }
+    if (tempCreated) { try { unlinkSync(temp); } catch { /* our populated temp may already be linked and consumed */ } }
+  }
+}
+
+function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
+  const file = join(stateDir, "claude-launch.json"), temp = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
+  finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
+}
+
+export function recordClaudeLaunch(stateDir: string, record: ClaudeLaunchRecord): ClaudeLaunchPublication {
+  writeClaudeLaunchRecord(stateDir, record);
+  return { recorded: true };
+}
+
+function sameClaudeLaunch(left: ClaudeLaunchRecord, right: ClaudeLaunchRecord): boolean {
+  return left.instanceId === right.instanceId && left.launchId === right.launchId && left.settingsFile === right.settingsFile
+    && left.launcherPid === right.launcherPid && left.launcherSignature === right.launcherSignature;
+}
+function nativeAttestationPath(stateDir: string, launch: ClaudeLaunchRecord): string {
+  const hash = createHash("sha256").update(JSON.stringify([launch.instanceId, launch.launchId, launch.settingsFile, launch.launcherPid, launch.launcherSignature])).digest("hex");
+  return join(stateDir, `claude-native-${hash}.json`);
+}
+function privateClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): { file: string; stat: ReturnType<typeof lstatSync>; record: ClaudeLaunchRecord } | undefined {
+  const file = nativeAttestationPath(stateDir, launch);
+  try {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+    const record = JSON.parse(readFileSync(file, "utf8")) as ClaudeLaunchRecord;
+    if (!record || !sameClaudeLaunch(record, launch) || typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || typeof record.nativeSignature !== "string" || !record.nativeSignature || record.nativeIdentity !== "direct-child") return;
+    return { file, stat, record };
+  } catch { return; }
+}
+export function readClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): ClaudeLaunchRecord | undefined {
+  return privateClaudeNative(stateDir, launch)?.record;
+}
+function removeClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): void {
+  const saved = privateClaudeNative(stateDir, launch); if (!saved?.stat) return;
+  try { const now = lstatSync(saved.file); if (now.dev === saved.stat.dev && now.ino === saved.stat.ino) unlinkSync(saved.file); }
+  catch { /* absent or replaced native proof remains untouched */ }
+}
+
+/** Never attach an old child's identity to a replacement launch, even when its spawn callback arrives later. */
+export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchRecord, pid: number, signature: string, report?: (warning: string) => void): Promise<boolean> {
+  let recorded = false;
+  const publication = await withClaudeLaunchRecord(stateDir, () => {
+    let current: ClaudeLaunchRecord;
+    try {
+      const file = join(stateDir, "claude-launch.json"), stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+      current = JSON.parse(readFileSync(file, "utf8"));
+    } catch { return; }
+    if (!sameClaudeLaunch(current, launch)) return;
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid === launch.launcherPid || !signature) return;
+    const file = nativeAttestationPath(stateDir, launch), temp = `${file}.${randomUUID()}.tmp`;
+    try {
+      lstatSync(file);
+      const saved = privateClaudeNative(stateDir, launch);
+      recorded = !!saved && saved.record.nativePid === pid && saved.record.nativeSignature === signature;
+      return; // a launch's first native proof is immutable; an unknown file is never overwritten
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return; }
+    try {
+      writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
+      renameSync(temp, file);
+    } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+  });
+  if (publication.warning) report?.(publication.warning);
+  return publication.recorded && recorded;
+}
+
+/** Scripts and interpreters can leave a different native owner behind: their crash cleanup remains disabled. */
+function directNativeExecutable(command: string, cwd: string, env: NodeJS.ProcessEnv): boolean {
+  const interpreter = /^(?:node|bun|deno|env|busybox|python(?:[0-9.]+)?|ruby|perl|bash|sh|zsh|fish|dash|ksh|csh|tcsh|ash)(?:\.exe)?$/;
+  if (interpreter.test(basename(command))) return false;
+  const paths = command.includes("/") ? [resolve(cwd, command)] : (env.PATH ?? "").split(":").filter(Boolean).map(path => resolve(cwd, path, command));
+  for (const path of paths) {
+    let fd: number | undefined;
+    try {
+      const target = realPath(path);
+      accessSync(target, constants.X_OK);
+      if (interpreter.test(basename(target))) return false;
+      fd = openSync(target, "r");
+      const bytes = Buffer.alloc(4); if (readSync(fd, bytes, 0, 4, 0) !== 4) return false;
+      return ["7f454c46", "feedface", "cefaedfe", "feedfacf", "cffaedfe", "cafebabe", "bebafeca", "cafebabf", "bfbafeca"].includes(bytes.toString("hex"));
+    } catch { /* resolve the next PATH entry */ }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
+  return false;
+}
+
+/** Same native stdio/environment and exit result as spawnSync, with a live child identity before it exits. */
+export async function runClaudeLaunch(launch: Launch, options: { cwd: string; env: NodeJS.ProcessEnv; stateDir: string; record?: ClaudeLaunchRecord }): Promise<{ status: number | null; signal: NodeJS.Signals | null; error?: Error }> {
+  const direct = directNativeExecutable(launch.cmd, options.cwd, options.env);
+  return new Promise(resolveResult => {
+    let attestation: Promise<unknown> | undefined;
+    let childSignature: string | undefined;
+    const child = spawn(launch.cmd, launch.args, { cwd: options.cwd, env: options.env, stdio: "inherit" });
+    child.once("spawn", () => {
+      if (!options.record || !child.pid) return;
+      const unavailable = (reason: string) => console.error(`Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}.`);
+      if (!direct) { unavailable("native executable is a script or an unverified interpreter"); return; }
+      if (!options.record.launcherSignature) { unavailable("launcher identity could not be verified"); return; }
+      const signature = processSignature(child.pid);
+      if (!signature) { unavailable("native process identity could not be verified"); return; }
+      childSignature = signature;
+      attestation = recordClaudeNative(options.stateDir, options.record, child.pid, signature, warning => console.error(warning)).catch(() => undefined);
+    });
+    child.once("error", error => resolveResult({ status: null, signal: null, error }));
+    child.once("exit", async (status, signal) => {
+      await attestation;
+      if (options.record) {
+        const saved = readClaudeNative(options.stateDir, options.record);
+        if (saved && typeof child.pid === "number" && saved.nativePid === child.pid && saved.nativeSignature === childSignature) removeClaudeNative(options.stateDir, options.record);
+      } // this child's observed exit, after its last bounded write
+      resolveResult({ status, signal });
+    });
+  });
 }
 
 export interface StatusLineTee {