@staix/agent-hub 0.12.20 → 0.12.21

package/src/adapters/acp.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
+import { KIMI_MODE_IDS, type PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -56,6 +57,9 @@ export interface AcpOptions {
   cmd: string[];
   /** Coordinator-visible selected model only; contains no prompts or command arguments. */
   launchModel?: string;
+  permissionMode?: PermissionMode;
+  /** Bound for native mode acknowledgement; defaults to the handshake deadline. */
+  permissionModeTimeoutMs?: number;
   /** Load this earlier session (ACP `session/load`) instead of starting a new one: crash recovery, issue #37. */
   resumeSessionId?: string;
   cwd: string;
@@ -94,6 +98,8 @@ export function canonicalMcpToolName(announcedTitle: string | undefined, serverN
   return m && serverNames?.some((name) => name === m[2]) ? `mcp__${m[2]}__${m[1]}` : undefined;
 }
 
+class RpcTimeoutError extends Error {}
+
 type Pending = { resolve: (v: any) => void; reject: (e: Error) => void };
 
 /** Streamed argument text as a payload: a complete JSON object, or nothing (a partial stream is not what will run). */
@@ -108,6 +114,10 @@ function jsonObject(text: string | undefined): object | undefined {
 
 /** ACP client (JSON-RPC 2.0, newline-delimited, over the child's stdio). One session, one prompt in flight. */
 export class AcpPeer extends BasePeer {
+  private permissionMode: PermissionMode;
+  private modeUnknown = false;
+  private kimiAgent = false;
+  private availableModes = new Set<string>();
   private proc: ChildProcessWithoutNullStreams | undefined;
   private sessionId = "";
   private nextId = 1;
@@ -126,6 +136,7 @@ export class AcpPeer extends BasePeer {
     private readonly opts: AcpOptions,
   ) {
     super(id, opts.watchdogMs);
+    this.permissionMode = opts.permissionMode ?? "ask";
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -149,26 +160,68 @@ export class AcpPeer extends BasePeer {
         protocolVersion: 1,
         clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
       });
+      // The configured peer id and command are labels, not an agent-specific mode contract.
+      // Installed Kimi Code CLI's ACP initialize advertises this exact name.
+      this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
       // The agent replays the session as updates while it loads; they arrive before the peer is idle, so none of
       // them is taken for an answer.
       if (!init?.agentCapabilities?.loadSession) throw new Error(`${this.id} cannot load an earlier session (the agent offers no loadSession)`);
-      await this.request("session/load", { sessionId: resume, cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
-      return { sessionId: resume };
+      const loaded = await this.request("session/load", { sessionId: resume, cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
+      return { ...loaded, sessionId: resume };
     };
     const timeout = new Promise<never>((_, reject) => {
       setTimeout(() => reject(new Error(`${this.id} did not complete the ACP handshake within ${HANDSHAKE_MS / 1000} s`)), HANDSHAKE_MS).unref();
     });
     try {
-      this.sessionId = (await Promise.race([handshake(), timeout])).sessionId;
+      const session = await Promise.race([handshake(), timeout]);
+      this.sessionId = session.sessionId;
+      const modes: unknown = session.modes?.availableModes;
+      this.availableModes = new Set(Array.isArray(modes) ? modes.flatMap((mode) => typeof mode?.id === "string" ? [mode.id] : []) : []);
+      // A recovered session can retain a previous runtime opt-in. An advertised non-default mode
+      // must be reset for the configured ask default before any prompt; a fresh ask session stays untouched.
+      const resetResumed = this.opts.resumeSessionId && typeof session.modes?.currentModeId === "string" && session.modes.currentModeId !== KIMI_MODE_IDS.ask;
+      // Other ACP vendors retain their native policy, including reported non-default modes on resume.
+      if (this.kimiAgent && (this.permissionMode !== "ask" || resetResumed)) await this.setPermissionMode(this.permissionMode);
     } catch (e) {
-      await stopOwnedProcess(proc, { group: true }).catch((stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
+      this.setState("offline");
+      if (this.proc === proc) {
+        await stopOwnedProcess(proc, { group: true }).then(() => { if (this.proc === proc) this.proc = undefined; }, (stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
+      }
       throw e;
     }
     this.setState("idle");
   }
 
+  getPermissionMode(): PermissionMode { return this.permissionMode; }
+  get permissionModeState(): PermissionMode | "unknown" | "unmanaged" {
+    return !this.kimiAgent ? "unmanaged" : this.modeUnknown ? "unknown" : this.permissionMode;
+  }
+
+  async setPermissionMode(mode: PermissionMode): Promise<void> {
+    if (!this.kimiAgent) throw new Error(`${this.id} permission mode ${mode} unmanaged: this ACP agent has no verified mode mapping; use Kimi Code CLI or add an agent-specific mapping`);
+    if (this.modeUnknown) throw new Error(`${this.id} permission mode unknown after an unanswered change; restart the peer before changing modes`);
+    const id = KIMI_MODE_IDS[mode];
+    if (!this.sessionId || !this.proc || !this.availableModes.has(id)) throw new Error(`${this.id} permission mode ${mode} unavailable: session does not offer ${id}`);
+    try {
+      await this.request("session/set_mode", { sessionId: this.sessionId, modeId: id }, this.opts.permissionModeTimeoutMs ?? HANDSHAKE_MS);
+    } catch (error) {
+      if (error instanceof RpcTimeoutError) {
+        // No reply means the native mode may have changed. Invalidate the turn before stopping
+        // our verified process group; neither a late prompt result nor a late mode ack restores idle.
+        this.modeUnknown = true;
+        this.turn++;
+        this.setState("offline");
+        await this.stop().catch((stop: Error) => this.opts.log?.(`[${this.id}] ${stop.message}`));
+        throw new Error(`${this.id} permission mode ${mode} unknown: ${error.message}; peer is offline, restart it before sending work`);
+      }
+      throw new Error(`${this.id} permission mode ${mode} refused: ${(error as Error).message}`);
+    }
+    if (this.modeUnknown) throw new Error(`${this.id} permission mode unknown; restart the peer`);
+    this.permissionMode = mode;
+  }
+
   async stop(): Promise<void> {
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "ACP session stopped before settlement" });
     this.activeDeliveryId = undefined;
@@ -350,10 +403,18 @@ export class AcpPeer extends BasePeer {
     });
   }
 
-  private request(method: string, params: unknown): Promise<any> {
+  private request(method: string, params: unknown, timeoutMs?: number): Promise<any> {
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      this.pending.set(id, { resolve, reject });
+      const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
+        this.pending.delete(id);
+        reject(new RpcTimeoutError(`${method} did not answer within ${timeoutMs / 1000} s`));
+      }, timeoutMs);
+      timer?.unref();
+      this.pending.set(id, {
+        resolve: (value) => { clearTimeout(timer); resolve(value); },
+        reject: (error) => { clearTimeout(timer); reject(error); },
+      });
       this.send({ jsonrpc: "2.0", id, method, params });
     });
   }

package/src/adapters/codex-appserver.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
@@ -8,6 +9,7 @@ import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process
 export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
+  permissionMode?: PermissionMode;
   /** Port for the spawned `codex app-server`. Ignored when `upstreamUrl` is set. */
   appPort: number;
   /** Attach to an already running app-server instead of spawning one (tests). */
@@ -60,6 +62,10 @@ const TRACKED = new Set(["thread/start", "thread/resume"]);
  * TUI's, and their responses are swallowed.
  */
 export class CodexPeer extends BasePeer {
+  private permissionMode: PermissionMode;
+  private nativeApprovalPolicy: unknown;
+  private approvalOverridden = false;
+  private readonly restoringApprovals = new Set<string | number>();
   private proc: ChildProcess | undefined;
   private server: Server<Link> | undefined;
   private link: Link | undefined; // the connection that owns the current thread
@@ -96,6 +102,7 @@ export class CodexPeer extends BasePeer {
     private readonly opts: CodexOptions,
   ) {
     super(id, opts.watchdogMs);
+    this.permissionMode = opts.permissionMode ?? "ask";
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -184,6 +191,7 @@ export class CodexPeer extends BasePeer {
       this.pending.set(id, {
         deliveryId, kind: "deliver",
         resolve: (result) => {
+          if (this.restoringApprovals.delete(id) && this.permissionMode === "ask") this.approvalOverridden = false;
           this.primed = true;
           this.injected = replyParent(envs);
           this.answering = [...envs];
@@ -196,13 +204,14 @@ export class CodexPeer extends BasePeer {
           resolve();
         },
         reject: (e) => {
+          this.restoringApprovals.delete(id);
           if (!this.activeTurns.size) this.setState("idle");
           if (deliveryId) this.delivery({ id: deliveryId, state: this.knownRejection(e) ? "failed_safe" : "needs_review", reason: e.message });
           reject(e);
         },
       });
       link.up.send(
-        JSON.stringify({ method: "turn/start", id, params: { threadId: this.threadId, input: [{ type: "text", text }] } }),
+        JSON.stringify({ method: "turn/start", id, params: this.applyPermissionPolicy({ threadId: this.threadId, input: [{ type: "text", text }] }, id) }),
       );
     });
   }
@@ -350,6 +359,7 @@ export class CodexPeer extends BasePeer {
     if (this.link !== link) return;
     clearInterval(this.usageTimer);
     this.link = undefined;
+    this.restoringApprovals.clear();
     this.threadId = "";
     this.contextEpoch++;
     this.activeTurns.clear();
@@ -372,8 +382,55 @@ export class CodexPeer extends BasePeer {
     this.lastAnswer = "";
   }
 
+  get proxyAttached(): boolean { return !!this.link && this.link.up.readyState === WebSocket.OPEN; }
+
+  getPermissionMode(): PermissionMode { return this.permissionMode; }
+
+  /** Reconcile the daemon's current choice after startup, before the returned proxy URL has a TUI. */
+  setStartupPermissionMode(mode: PermissionMode): void {
+    if (this.link || this.state !== "offline" || this.approvalOverridden) throw new Error("codex startup mode reconciliation requires a fresh unattached proxy");
+    this.permissionMode = mode;
+  }
+
+  /**
+   * The hub's choice was cleared while no TUI is attached: this proxy sends no override from now on. Returns false
+   * when an override it already sent cannot be undone on that thread (its native policy was never reported): a thread
+   * started or resumed through the proxy afterwards reports its own policy, and that one is left alone.
+   */
+  clearPermissionMode(): boolean {
+    const restorable = !this.approvalOverridden || this.nativeApprovalPolicy !== undefined;
+    this.permissionMode = "ask";
+    return restorable;
+  }
+
+  async setPermissionMode(mode: PermissionMode): Promise<void> {
+    if (!this.link || this.link.up.readyState !== WebSocket.OPEN) throw new Error("codex permission mode unavailable: attach the TUI through ahub codex first");
+    if (mode === "ask" && this.approvalOverridden && this.nativeApprovalPolicy === undefined) throw new Error("codex cannot restore ask: native approval policy unavailable; restart the Codex session");
+    this.permissionMode = mode;
+  }
+
+  private applyPermissionPolicy(params: Record<string, unknown>, id: string | number): Record<string, unknown> {
+    if (this.permissionMode !== "ask") {
+      this.approvalOverridden = true;
+      return { ...params, approvalPolicy: this.permissionMode === "never-ask" ? "never" : "on-request" };
+    }
+    if (this.permissionMode === "ask" && this.approvalOverridden) {
+      this.restoringApprovals.add(id);
+      return { ...params, approvalPolicy: this.nativeApprovalPolicy };
+    }
+    return params;
+  }
+
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
+    if (msg?.method === "turn/start" && msg.params && link === this.link) {
+      if (msg.params.approvalPolicy != null) this.nativeApprovalPolicy = msg.params.approvalPolicy;
+      if (this.permissionMode !== "ask" || this.approvalOverridden) {
+        // Native turn overrides persist: ask restores the captured native policy once on successful admission.
+        msg.params = this.applyPermissionPolicy(msg.params, msg.id);
+        raw = JSON.stringify(msg);
+      }
+    }
     if (msg?.id !== undefined && TRACKED.has(msg.method)) link.tracked.set(msg.id, msg.method);
     if (link.up.readyState === WebSocket.OPEN) link.up.send(raw);
     else link.backlog.push(raw);
@@ -391,9 +448,17 @@ export class CodexPeer extends BasePeer {
       else p?.resolve(msg.result);
       return; // ours: the TUI never asked for it
     }
+    if (msg.id !== undefined && !msg.method && this.restoringApprovals.delete(msg.id) && !msg.error && this.permissionMode === "ask") this.approvalOverridden = false;
     if (typeof msg.result?.userAgent === "string") this.version = /^[^/\s]+\/(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(msg.result.userAgent)?.[1] ?? this.version;
     const tracked = msg.id !== undefined && !msg.method ? link.tracked.get(msg.id) : undefined;
-    if (tracked && link.tracked.delete(msg.id)) this.adopt(link, msg.result?.thread?.id, tracked === "thread/start");
+    if (tracked && link.tracked.delete(msg.id)) {
+      if (typeof msg.result?.thread?.id === "string") {
+        this.nativeApprovalPolicy = msg.result?.approvalPolicy;
+        this.approvalOverridden = false;
+        this.restoringApprovals.clear();
+        this.adopt(link, msg.result.thread.id, tracked === "thread/start");
+      }
+    }
     else if (msg.method) this.onNotification(link, msg.method, msg.params ?? {});
     link.tui.send(raw);
   }

package/src/adapters/local-worker.ts

@@ -264,7 +264,8 @@ export class LocalPeer extends BasePeer {
           const result: ChatMessage = { role: "tool", tool_call_id: call.id, content: output, is_error: toolResultFailed(name, output) };
           msgs.push(result); results.push(result);
           this.observeTool(call, output, policy, `${this.sessionId}.${turn}.${step}`);
-          capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
+          // Hub tool arguments/results are not capture evidence; Tasks owns its screened memory writes.
+          if (name !== "hub_send" && !TASK_TOOL_NAMES.has(name) && !CONDUCTOR_TOOL_NAMES.has(name)) capture?.observe({ tool: call.function.name, args: call.function.arguments, output, id: call.id, paths: touchedPaths(call.function.name, safeParse(call.function.arguments)) });
         }
       } finally { if (results.length) this.routes.observeResults(res.routeDecision, res.message, results); }
     }
@@ -276,13 +277,13 @@ export class LocalPeer extends BasePeer {
     return {
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
-      permit: async (title) => {
+      permit: async (title, tool, _signal, path) => {
         if (turnSignal.aborted) return false;
         return new Promise<boolean>((resolve, reject) => {
           const finish = (allowed: boolean) => { turnSignal.removeEventListener("abort", onAbort); resolve(allowed); };
           const onAbort = () => finish(false);
           turnSignal.addEventListener("abort", onAbort, { once: true });
-          this.opts.tools.permit(title).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+          this.opts.tools.permit(title, tool, turnSignal, path).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
         });
       },
       sandboxProfile: this.sandboxProfile,

package/src/adapters/pi.ts

@@ -15,6 +15,16 @@ import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-bu
 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 PiOptions {
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
@@ -28,6 +38,8 @@ 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;
   /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
   stopGraceMs?: number;
 }
@@ -74,6 +86,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>;
@@ -179,6 +195,8 @@ export class PiPeer extends BasePeer {
       if (reservation.deadlineAt !== undefined) idleBashTimer = setTimeout(() => idleBashAbort.abort(), Math.max(0, reservation.deadlineAt - Date.now()));
     }
     this.noteActivity();
+    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();
@@ -230,6 +248,7 @@ export class PiPeer extends BasePeer {
 
   private async startImpl(): Promise<void> {
     this.stopping = false;
+    this.exitReported = false; this.started = false; this.lastToolName = undefined; this.shutdownExit = undefined;
     mkdirSync(this.opts.stateDir, { recursive: true });
     const sessions = join(this.opts.stateDir, "pi-sessions");
     mkdirSync(sessions, { recursive: true, mode: 0o700 });
@@ -275,8 +294,17 @@ 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)) {
@@ -285,10 +313,13 @@ export class PiPeer extends BasePeer {
     this.sessionId = state.data.sessionId; this.sessionFile = state.data.sessionFile;
     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> {
+    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;
@@ -329,6 +360,7 @@ 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
   }
 
   /**
@@ -416,9 +448,15 @@ export class PiPeer extends BasePeer {
       this.sessionId = String(event.sessionId ?? ""); this.sessionFile = String(event.sessionFile ?? "");
       this.ownerPid = Number.isInteger(event.pid) ? event.pid : undefined; this.ownerSignature = typeof event.signature === "string" ? event.signature : undefined;
       if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) { this.opts.log?.(`[${this.id}] Pi session identity mismatch`); return; }
-      this.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 === "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;
@@ -507,6 +545,20 @@ 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 {
     for (const pending of this.pending.values()) pending.reject(error);
     this.pending.clear();
@@ -525,11 +577,13 @@ 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?.();
   }