@staix/agent-hub 0.12.23 → 0.12.25

package/src/adapters/jcode.ts

@@ -0,0 +1,110 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { existsSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type { Readable } from "node:stream";
+import type { PeerState } from "../hub/envelope.ts";
+import { AcpPeer, type AcpOptions } from "./acp.ts";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+
+export interface JcodeOptions extends Omit<AcpOptions, "cmd" | "qwen025" | "expectedAgent" | "mcpServers" | "permissionMode"> {
+  command: string[];
+  home: string;
+  providerProfile?: string;
+}
+export function jcodeCommand(command: string[], kind: "serve" | "acp", socket: string, cwd: string, model?: string, profile?: string): string[] {
+  if (!command.length || command.some(word => typeof word !== "string" || !word)) throw new Error("jcode_cmd must name an executable argv");
+  return [...command, kind, "--socket", socket, "--cwd", cwd, "--no-update", "--no-selfdev", ...(model ? ["--model", model] : []), ...(profile ? ["--provider-profile", profile] : []),
+    ...(kind === "serve" ? ["--temporary-server", "--owner-pid", String(process.pid), "--server-name", "agent-hub-jcode"] : ["--mcp-tools", "eager"])];
+}
+/** The wrapper contract preserves every configured prefix argument before the native probe. */
+export function verifiedJcodeCommand(command: string[], cwd: string): boolean {
+  const [bin, ...prefix] = command;
+  if (!bin) return false;
+  try {
+    const result = spawnSync(bin, [...prefix, "--quiet", "version", "--json"], { cwd, env: peerChildEnv("jcode"), encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024 });
+    if (result.status !== 0) return false;
+    const version = JSON.parse(result.stdout);
+    return version.semver === "0.94.0";
+  } catch { return false; }
+}
+
+/** Both processes are ours. The user's global daemon and its sockets are never stopped. */
+export class JcodePeer extends AcpPeer {
+  private readonly root: string;
+  private readonly socket: string;
+  private server: ChildProcess | undefined;
+  private ending = false;
+  private preserveRoot = false;
+  private stopPromise: Promise<void> | undefined;
+
+  constructor(private readonly jcode: JcodeOptions) {
+    if (!isAbsolute(jcode.home)) throw new Error("jcode_home must be an absolute native data path");
+    jcodeCommand(jcode.command, "acp", "preview", jcode.cwd);
+    const root = mkdtempSync(join(tmpdir(), "ahub-jcode-")), socket = join(root, "s");
+    const cmd = jcodeCommand(jcode.command, "acp", socket, jcode.cwd, jcode.launchModel, jcode.providerProfile);
+    super("jcode", { ...jcode, cmd, env: { ...jcode.env, JCODE_HOME: jcode.home, JCODE_SOCKET: socket, JCODE_DISABLE_CLAUDE_MCP: "1" }, mcpServers: [], requireLoadSessionEcho: true, expectedAgent: { name: "jcode", version: "0.94.0" } });
+    this.root = root; this.socket = socket;
+  }
+
+  override async start(): Promise<void> {
+    // The native loader otherwise imports Codex MCP into the user's store on first use.
+    if (!existsSync(join(this.jcode.home, "mcp.json"))) throw new Error("initialize Jcode's global MCP store with its native client before enabling this peer; the hub never initializes or copies it");
+    if (existsSync(this.socket)) { this.preserveRoot = true; throw new Error("Jcode private socket is occupied; no daemon was adopted or removed"); }
+    this.ending = false;
+    const [bin, ...args] = jcodeCommand(this.jcode.command, "serve", this.socket, this.jcode.cwd, this.jcode.launchModel, this.jcode.providerProfile);
+    const server = spawn(bin!, args, { cwd: this.jcode.cwd, detached: true, env: { ...peerChildEnv("jcode"), JCODE_HOME: this.jcode.home, JCODE_SOCKET: this.socket, JCODE_READY_FD: "3", JCODE_DISABLE_CLAUDE_MCP: "1" }, stdio: ["ignore", "ignore", "ignore", "pipe"] });
+    this.server = server; trackGroup(server);
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const ready = server.stdio[3] as Readable;
+        const timer = setTimeout(() => reject(new Error("Jcode owned daemon did not become ready within 30 s")), 30_000);
+        const fail = () => { clearTimeout(timer); reject(new Error("Jcode owned daemon exited before readiness; details withheld")); };
+        server.once("error", fail); server.once("exit", fail);
+        ready.once("data", () => { clearTimeout(timer); server.off("exit", fail); if (lstatSync(this.socket, { throwIfNoEntry: false })?.isSocket()) resolve(); else reject(new Error("Jcode readiness has no private socket")); });
+      });
+      server.once("exit", () => { if (!this.ending && this.server === server) void this.stop("Jcode owned daemon disconnected").catch(() => {}); });
+      await super.start();
+    } catch (error) { await this.stop().catch(() => {}); throw error; }
+  }
+
+  protected override setState(next: PeerState): void {
+    if (next === "offline" && this.server) {
+      // A removed socket is not process-exit proof. Retain a non-ready state until both owned groups settle.
+      if (!this.ending) { super.setState("busy"); void this.stop("Jcode ACP transport ended").catch(() => {}); }
+      return;
+    }
+    super.setState(next);
+  }
+  override async stop(reason?: string): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    const pending = this.end(reason); this.stopPromise = pending;
+    try { await pending; } finally { if (this.stopPromise === pending) this.stopPromise = undefined; }
+  }
+  private async end(reason?: string): Promise<void> {
+    this.ending = true;
+    if (this.server && this.state !== "offline") super.setState("busy");
+    let failure: unknown;
+    try { await super.stop(reason); } catch (error) { failure = error; }
+    try {
+      if (this.server) {
+        const server = this.server;
+        const closed = server.exitCode !== null || server.signalCode !== null ? Promise.resolve() : new Promise<void>((resolve) => server.once("close", () => resolve()));
+        await stopOwnedProcess(server, { group: true });
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await Promise.race([closed, new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("Jcode child exit is not confirmed; runtime retained")), 3000); })]);
+        } finally { clearTimeout(timer); }
+        if (this.server === server) this.server = undefined;
+      }
+    } catch (error) { failure ??= error; }
+    if (!failure && !this.server) {
+      if (!this.preserveRoot) rmSync(this.root, { recursive: true, force: true });
+      super.setState("offline");
+    }
+    if (failure) throw failure;
+  }
+  override recoveryMetadata(): Record<string, unknown> {
+    return { ...super.recoveryMetadata(), launch: { kind: "jcode", peer: "jcode", mode: "headless", ...(this.jcode.launchModel ? { model: this.jcode.launchModel } : {}), ...(this.jcode.providerProfile ? { providerProfile: this.jcode.providerProfile } : {}) } };
+  }
+}

package/src/adapters/local-worker.ts

@@ -5,7 +5,7 @@ import type { StaySwitchPolicy } from "../models/route/stage.ts";
 import type { ToolObservation } from "../models/route/signals.ts";
 import { randomUUID } from "node:crypto";
 import { renderDigest, replyAudience, replyParent, STANDING_INSTRUCTION, USER, type Envelope, type EnvelopeOpts, type PeerId } from "../hub/envelope.ts";
-import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS } from "../hub/hub-tools.ts";
+import { CONDUCTOR_TOOL_NAMES, CONDUCTOR_TOOLS, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { runTool, toolResultFailed, TOOL_SCHEMAS, touchedPaths, ApprovalWaitStop, type ToolApproval, type ApprovalProvenance, type ToolContext } from "../local/tools.ts";
@@ -16,6 +16,8 @@ import type { Sidecar } from "../switchyard/sidecar.ts";
 import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 
 export interface LocalOptions {
+  profile?: import("../hub/profiles.ts").ProfileSelection;
+  sdlcStages?: readonly string[];
   cwd: string;
   omni: OmniRoute;
   /** Absent = always the fixed model on OmniRoute. */
@@ -34,7 +36,7 @@ export interface LocalOptions {
   turnId?: () => string | undefined;
   onApprovalStop?: (reason: string) => void;
   onTool?: (observation: ToolObservation, task?: string) => void;
-  tools: { deny: string[]; permit: ToolContext["permit"]; bashNetwork?: SandboxNetwork; readAllow?: string[] };
+  tools: { deny: string[]; permit: ToolContext["permit"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
   capture?: Capture;
   /** Runs a hub task tool (hub_task_*, hub_review, hub_remember) as this peer. Absent = the tools are not offered. */
   taskTool?: (name: string, args: Record<string, unknown>, turn: { pii: boolean }) => Promise<string>;
@@ -106,7 +108,7 @@ export class LocalPeer extends BasePeer {
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...TASK_TOOLS, ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+        const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
         this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
@@ -119,7 +121,7 @@ export class LocalPeer extends BasePeer {
       onAdvisor: event => this.opts.onAdvisor?.(event),
       onRouteOutcome: event => this.opts.onRouteOutcome?.(event),
     });
-    this.sandboxProfile = profile(opts.cwd, opts.tools.bashNetwork ?? false, opts.tools.readAllow, opts.tools.deny);
+    this.sandboxProfile = profile(opts.cwd, opts.tools.bashNetwork ?? false, opts.tools.readAllow, opts.tools.deny, opts.tools.readOnly);
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -291,7 +293,8 @@ export class LocalPeer extends BasePeer {
     return {
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
-      permit: async (title, tool, _signal, canonicalTarget) => {
+      readOnly: this.opts.tools.readOnly,
+      permit: async (title, tool, _signal, canonicalTarget, _observe, originalPath) => {
         if (turnSignal.aborted) return "aborted";
         const generation = this.turn;
         let observed = false;
@@ -311,7 +314,7 @@ export class LocalPeer extends BasePeer {
           const finish = (decision: ToolApproval) => { turnSignal.removeEventListener("abort", onAbort); resolve(decision); };
           const onAbort = () => finish("aborted");
           turnSignal.addEventListener("abort", onAbort, { once: true });
-          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe, originalPath).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
         });
         if (generation !== this.turn || (turnSignal.aborted && picked !== "expired")) return "aborted";
         // Legacy permit callbacks can represent a person's denial without provenance. A true
@@ -375,7 +378,7 @@ export class LocalPeer extends BasePeer {
     const route = policy?.route ?? this.opts.route;
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
-    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...TASK_TOOLS, ...CONDUCTOR_TOOLS].map(asFunction) : [])];
+    const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages), ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);

package/src/adapters/pi.ts

@@ -28,6 +28,10 @@ export interface PiExit {
 export interface PiToolContext { userBash: boolean; isCurrent: () => boolean; onApproval: (provenance: ApprovalProvenance) => void; }
 export interface PiToolResult { text: string; exitCode: number | null; }
 class PiToolSettlementFailure extends Error {}
+class PiPromptNotStarted extends Error {
+  constructor(readonly promptId: string) { super("Pi native session changed before prompt insertion; reverify its retained terminal before retrying"); }
+}
+class PiPromptUncertain extends Error {}
 export interface PiOptions {
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
@@ -99,6 +103,15 @@ export class PiPeer extends BasePeer {
   private ownerClaimed = false;
   private ownerToken = "";
   private stopping = true;
+  private rosterDetached = false;
+  private rosterEpoch = 0;
+  private rosterLifecycleRevision = 0;
+  private fencedPrompt = false;
+  private hubPromptId: string | undefined;
+  private hubPromptGeneration: number | undefined;
+  private pendingPromptId: string | undefined;
+  /** A personal native turn observed on reattach has no hub reply audience. */
+  private rosterUnownedRun = false;
   private exitReported = false;
   private started = false;
   private lastToolName?: string;
@@ -118,7 +131,7 @@ export class PiPeer extends BasePeer {
     if (this.canReuseVerifiedEmptyResume()) return { sessionId: this.verifiedEmptyResume!.sessionId };
     return { sessionId: this.opts.sessionId, sessionFile: this.opts.sessionFile };
   }
-  get acceptingTools(): boolean { return !this.stopping; }
+  get acceptingTools(): boolean { return !this.stopping && !this.rosterDetached && !this.rosterUnownedRun; }
   /** Idle verified owners can be stopped; uncertain live owners and pending launches stay fenced. */
   get recoveryReady(): boolean {
     if (this.state === "busy" || this.starting || this.activeTools) return false;
@@ -171,13 +184,13 @@ export class PiPeer extends BasePeer {
 
   /** Envelopes belonging to the currently executing Pi turn, for relay-side model-call admission. */
   /** One id per admitted provider request; parallel tools share its assistant step. */
-  get observationTurn(): string | undefined { return this.agentRunning && this.modelStep ? `${this.observationScope}.${this.budgetGeneration}.${this.modelStep}` : undefined; }
+  get observationTurn(): string | undefined { return this.acceptingTools && this.agentRunning && this.modelStep ? `${this.observationScope}.${this.budgetGeneration}.${this.modelStep}` : undefined; }
 
-  get budgetEnvelopes(): Envelope[] { return this.agentRunning && this.state === "busy" ? this.activeEnvs.slice() : []; }
+  get budgetEnvelopes(): Envelope[] { return this.acceptingTools && this.agentRunning && this.state === "busy" ? this.activeEnvs.slice() : []; }
 
   /** Mark an authoritative relay admission stop against the current Pi turn, never a later turn. */
   recordBudgetStop(decision: ExecutionBudgetDecision): { generation: number; reason: string } | undefined {
-    if (!this.agentRunning || this.state !== "busy") return undefined;
+    if (!this.acceptingTools || !this.agentRunning || this.state !== "busy") return undefined;
     const generation = this.budgetGeneration;
     const reason = `execution budget ${decision.reason ?? "exhausted"}: ${decision.scope} ${decision.unit} used ${decision.used}${decision.limit === null ? "" : ` of ${decision.limit}`}; ${decision.remaining === null ? "remaining unknown" : `${decision.remaining} remaining`}`;
     this.budgetStops.set(generation, reason);
@@ -192,7 +205,7 @@ export class PiPeer extends BasePeer {
     try { await this.starting; } finally { this.starting = undefined; }
   }
   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.acceptingTools || this.state === "offline") return Response.json({ text: this.rosterDetached ? "error: Pi is off roster" : this.rosterUnownedRun ? "error: Pi native turn is pending" : "error: Pi owner is stopped" }, { status: 409 });
     if (!this.verifiedOwner() || typeof body.sessionId !== "string" || !body.sessionId || body.sessionId !== this.sessionId || !Number.isSafeInteger(body.generation) || body.generation !== this.budgetGeneration) {
       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}`);
@@ -238,9 +251,9 @@ export class PiPeer extends BasePeer {
     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),
+        isCurrent: () => generation === this.budgetGeneration && this.acceptingTools && 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.acceptingTools || !this.agentRunning || generation !== this.budgetGeneration || turnSignal !== this.executionAbort?.signal || this.approvalStopReason) return;
           if (this.approvalAnswerEpoch !== provenance.answerEpoch) {
             this.approvalExpiries = 0; this.approvalAnswerEpoch = provenance.answerEpoch;
           }
@@ -269,7 +282,7 @@ export class PiPeer extends BasePeer {
           if (this.agentRunning && generation === this.budgetGeneration && this.approvalStopReason === reason && !this.stopping) void this.endApprovalTurn(generation, reason);
         }, 10);
       }
-      if (this.state === "busy") {
+      if (this.state === "busy" && this.acceptingTools) {
         if (!this.activeTools && !this.agentRunning && !this.activeEnvs.length) this.setState("idle");
         else this.touch();
       }
@@ -277,11 +290,12 @@ export class PiPeer extends BasePeer {
   }
 
   private async handleBudgetRequest(body: any): Promise<Response> {
+    if (this.rosterDetached || this.rosterUnownedRun) return Response.json({ error: this.rosterDetached ? "Pi is off roster" : "Pi native turn is pending" }, { status: 409 });
     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 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;
+    const current = () => Number.isSafeInteger(generation) && generation === this.budgetGeneration && controller === this.executionAbort && session === this.sessionId && ownerPid === this.ownerPid && ownerSignature === this.ownerSignature && this.acceptingTools && this.verifiedOwner();
+    const idleOwner = this.opts.mode === "tui" && this.acceptingTools && 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;
@@ -311,8 +325,10 @@ export class PiPeer extends BasePeer {
 
   private async startImpl(): Promise<void> {
     this.stopping = false;
+    this.rosterDetached = false; this.rosterUnownedRun = false;
     this.requestedStopReason = undefined;
     this.approvalTurnAbort = false;
+    this.fencedPrompt = false; this.hubPromptId = undefined; this.hubPromptGeneration = undefined; this.pendingPromptId = undefined;
     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 });
@@ -341,7 +357,13 @@ export class PiPeer extends BasePeer {
       if (url.pathname === "/ack") {
         const pending = this.tuiCommands.get(String(body.id));
         if (!pending) return Response.json({ ok: false }, { status: 404 });
-        this.tuiCommands.delete(String(body.id)); body.ok ? pending.resolve(body.result) : pending.reject(new Error(String(body.error ?? "Pi TUI command failed")));
+        this.tuiCommands.delete(String(body.id));
+        const refusal = body.refusal;
+        const boundRefusal = this.fencedPrompt && this.verifiedOwner() && pending.command.type === "prompt" && pending.command.sessionId === this.sessionId
+          && refusal?.promptId === pending.command.id && refusal.sessionId === this.sessionId
+          && Number.isSafeInteger(refusal.generation) && refusal.generation >= Number(pending.command.generation);
+        body.ok ? pending.resolve(body.result) : pending.reject(boundRefusal && refusal.kind === "prompt_not_started" ? new PiPromptNotStarted(String(body.id))
+          : boundRefusal && refusal.kind === "prompt_uncertain" ? new PiPromptUncertain("Pi native prompt insertion is uncertain; inspect its retained terminal before retrying") : new Error(String(body.error ?? "Pi TUI command failed")));
         return Response.json({ ok: true });
       }
       if (url.pathname === "/tool") return this.handleToolRequest(body);
@@ -403,8 +425,50 @@ export class PiPeer extends BasePeer {
   }
   get mode(): "headless" | "tui" { return this.opts.mode; }
 
+  /** Withdraw hub admission without shutting down a person's Pi TUI or its bridge. */
+  async detachForRoster(): Promise<void> {
+    if (this.opts.mode !== "tui") throw new Error("Pi roster detach requires a personal TUI");
+    this.rosterDetached = true; this.rosterEpoch++;
+    this.setState("offline");
+    clearTimeout(this.executionBudgetTimer); this.executionBudgetTimer = undefined;
+    const ids = [...this.activeDeliveryIds]; this.activeDeliveryIds.clear();
+    this.activeEnvs = []; this.currentReply = undefined;
+    this.settledText = ""; this.settledError = ""; this.settledCancelled = false;
+    for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Pi removed from roster before settlement; inspect the native session before retrying" });
+    const settling = this.abortTools();
+    // Revoke hub commands not yet consumed, and fence an ACK already in flight by rosterEpoch.
+    for (const [id, pending] of this.tuiCommands) {
+      if (!["prompt", "steer", "set_model"].includes(String(pending.command.type))) continue;
+      this.tuiCommands.delete(id); this.tuiQueue = this.tuiQueue.filter((command) => command.id !== id);
+      pending.reject(new Error("Pi is off roster"));
+    }
+    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 roster detach")), this.opts.stopGraceMs ?? 5_000); })]); }
+      finally { clearTimeout(timer); }
+    }
+  }
+
+  /** A return reuses only the same verified native owner and a fresh, truthful snapshot. */
+  async resumeFromRoster(): Promise<void> {
+    if (!this.rosterDetached) return;
+    if (this.opts.mode !== "tui" || this.stopping || !this.rosterDetached || !this.server || !this.verifiedOwner()) throw new Error("Pi roster return has no verified live TUI owner");
+    if (!this.fencedPrompt) throw new Error("Pi roster return needs a fenced-prompt extension; restart the retained terminal with the current hub extension");
+    if (this.pendingPromptId) throw new Error("Pi prompt admission is still pending; wait before reverifying the retained terminal");
+    const epoch = this.rosterEpoch, lifecycle = this.rosterLifecycleRevision, session = this.sessionId, file = this.sessionFile;
+    const snapshot = await this.sendTui({ type: "get_session_state" });
+    if (epoch !== this.rosterEpoch || this.stopping || !this.verifiedOwner() || this.activeTools || snapshot?.sessionId !== session || snapshot?.sessionFile !== file || typeof snapshot?.idle !== "boolean") throw new Error("Pi roster return could not verify the current native session");
+    if (lifecycle !== this.rosterLifecycleRevision) throw new Error("Pi native activity changed during roster return; retry with a fresh session snapshot");
+    this.rosterDetached = false;
+    this.hubPromptId = undefined; this.hubPromptGeneration = undefined;
+    this.rosterUnownedRun = !snapshot.idle; this.agentRunning = !snapshot.idle;
+    this.setState(snapshot.idle ? "idle" : "busy");
+    if (!snapshot.idle) this.clearWatchdog();
+  }
+
   async stop(reason?: string): Promise<void> {
     if (reason !== undefined) this.requestedStopReason = reason;
+    this.rosterEpoch++;
     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();
@@ -482,22 +546,53 @@ export class PiPeer extends BasePeer {
   }
 
   async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (this.state !== "idle" || this.stopping) {
-      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not ready` });
-      throw new Error(`${this.id} is not ready`);
+    if (this.state !== "idle" || !this.acceptingTools) {
+      const reason = `${this.id} is not ready${this.rosterDetached ? ": off roster" : this.rosterUnownedRun ? ": native turn pending" : ""}`;
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason });
+      throw new Error(reason);
     }
     this.setState("busy"); this.activeEnvs = envs; this.currentReply = replyParent(envs); this.settledText = "";
+    const rosterEpoch = this.rosterEpoch;
     let attempted = false;
+    let promptId: string | undefined;
     try {
       const requested = await this.opts.selectModel?.(envs);
+      if (rosterEpoch !== this.rosterEpoch || !this.acceptingTools) throw new Error("Pi is off roster or stopped");
       if (requested) await this.setRequestedModel(requested);
+      if (rosterEpoch !== this.rosterEpoch || !this.acceptingTools) throw new Error("Pi is off roster or stopped");
       this.noteActivity();
       attempted = true;
       if (deliveryId) this.activeDeliveryIds.add(deliveryId);
-      if (this.opts.mode === "tui") await this.sendTui({ type: "prompt", message: renderDigest(envs, true) });
+      if (this.opts.mode === "tui") { const pending = this.sendTui({ type: "prompt", message: renderDigest(envs, true) }); promptId = this.pendingPromptId; await pending; }
       else await this.sendRpc({ type: "prompt", message: renderDigest(envs, true) });
+      if (promptId !== undefined && promptId !== this.pendingPromptId) return;
+      if (this.fencedPrompt && this.rosterDetached) {
+        if (deliveryId && this.activeDeliveryIds.delete(deliveryId)) this.delivery({ id: deliveryId, state: "needs_review", reason: "Pi native activity changed before prompt acceptance was confirmed" });
+        this.setState("offline");
+        return;
+      }
       if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
+      if (promptId !== undefined && promptId !== this.pendingPromptId) return;
+      if (error instanceof PiPromptUncertain) { this.pendingPromptId = undefined; await this.detachForRoster(); return; }
+      if (error instanceof PiPromptNotStarted && error.promptId === this.pendingPromptId) {
+        this.pendingPromptId = undefined;
+        if (deliveryId) this.activeDeliveryIds.delete(deliveryId);
+        if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: error.message });
+        else this.onFailed?.(envs);
+        await this.detachForRoster();
+        return;
+      }
+      if (this.fencedPrompt && this.pendingPromptId && this.rosterDetached) {
+        this.pendingPromptId = undefined;
+        if (deliveryId && this.activeDeliveryIds.delete(deliveryId)) this.delivery({ id: deliveryId, state: "needs_review", reason: "Pi prompt acknowledgement is uncertain after personal native activity" });
+        this.setState("offline");
+        return;
+      }
+      if (rosterEpoch !== this.rosterEpoch) {
+        if (!attempted && deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "Pi withdrawn before native dispatch" });
+        return;
+      }
       if (!attempted) {
         this.activeEnvs = []; this.setState("idle");
         if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: error instanceof Error ? error.message : String(error) });
@@ -511,14 +606,18 @@ export class PiPeer extends BasePeer {
         this.delivery({ id: deliveryId, state: "failed_safe", reason });
       }
       await this.terminateFailedTurn(error instanceof Error ? error : new Error(reason));
+    } finally {
+      if (promptId !== undefined && this.pendingPromptId === promptId) this.pendingPromptId = undefined;
     }
   }
 
   async steer(envs: Envelope[], deliveryId?: string): Promise<void> {
-    if (this.state !== "busy" || this.stopping || envs.some((e) => e.kind !== "chat" || e.private || e.priority !== "important")) {
-      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "Pi workflow/private messages must queue" });
-      throw new Error("Pi workflow/private messages must queue");
+    if (this.state !== "busy" || !this.acceptingTools || (this.fencedPrompt && this.pendingPromptId && this.hubPromptGeneration === undefined) || envs.some((e) => e.kind !== "chat" || e.private || e.priority !== "important")) {
+      const reason = `Pi workflow/private messages must queue${this.rosterDetached ? ": off roster" : this.rosterUnownedRun ? ": native turn pending" : ""}`;
+      if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason });
+      throw new Error(reason);
     }
+    const rosterEpoch = this.rosterEpoch;
     const reply = replyParent([...this.activeEnvs, ...envs]);
     this.activeEnvs.push(...envs); this.currentReply = reply;
     try {
@@ -527,12 +626,14 @@ export class PiPeer extends BasePeer {
       else await this.sendRpc({ type: "steer", message: renderDigest(envs, true) });
       if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
+      if (rosterEpoch !== this.rosterEpoch) return;
       await this.terminateFailedTurn(error instanceof Error ? error : new Error(String(error)));
     }
   }
 
   getRequestedModel(): string { return this.requestedModel; }
   async setRequestedModel(model: string): Promise<void> {
+    if (!this.acceptingTools) throw new Error("Pi is off roster or stopped");
     const slash = model.indexOf("/");
     const provider = "agent-hub-local";
     const modelId = model;
@@ -541,10 +642,54 @@ export class PiPeer extends BasePeer {
   }
 
   private handleBridgeEvent(event: any): void {
+    if (this.fencedPrompt && this.opts.mode === "tui" && !this.rosterUnownedRun && ["agent_start", "agent_end", "agent_settled"].includes(event.type)
+      && typeof event.promptId === "string" && event.promptId !== this.hubPromptId) return;
+    if (this.fencedPrompt && this.opts.mode === "tui" && (this.activeEnvs.length > 0 || this.pendingPromptId || this.hubPromptId) && !this.rosterDetached && !this.rosterUnownedRun && !this.stopping && ["agent_start", "agent_end", "agent_settled"].includes(event.type)) {
+      const bound = this.verifiedOwner() && (event.sessionId === undefined || event.sessionId === this.sessionId);
+      if (!bound || !Number.isSafeInteger(event.generation) || event.generation < this.budgetGeneration) return;
+      const owned = this.hubPromptId !== undefined && event.promptId === this.hubPromptId;
+      if (event.type === "agent_start" && event.generation > this.budgetGeneration) {
+        if (owned) this.hubPromptGeneration = event.generation;
+        else {
+          if (this.pendingPromptId || this.activeEnvs.length) {
+            // Await the prompt's exact ACK before deciding whether its effect was absent or uncertain.
+            this.rosterDetached = true; this.rosterEpoch++; this.clearWatchdog();
+            this.activeEnvs = []; this.currentReply = undefined; this.settledText = ""; this.settledError = "";
+            this.abortTools();
+            if (!this.pendingPromptId) {
+              for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: "Pi personal native activity replaced the accepted hub turn" });
+              this.activeDeliveryIds.clear(); this.setState("offline");
+            }
+          } else { this.rosterUnownedRun = true; this.setState("busy"); this.clearWatchdog(); }
+        }
+      } else if (!this.rosterUnownedRun && (!owned || event.generation !== this.hubPromptGeneration)) return;
+    }
+    if (this.rosterDetached || this.rosterUnownedRun) {
+      // The shipped extension's legacy agent_start omits sessionId. Its authenticated bridge
+      // and still-verified owner bind that event to this session; an explicit mismatch never does.
+      const bound = !this.stopping && this.verifiedOwner() && (event.sessionId === undefined || event.sessionId === this.sessionId);
+      if (bound && event.type === "agent_start" && Number.isSafeInteger(event.generation) && event.generation > this.budgetGeneration) {
+        this.rosterLifecycleRevision++;
+        this.budgetGeneration = event.generation;
+        this.noteActivity(); // personal native activity also revokes an earlier ID-only empty-resume proof
+      }
+      // Snapshot ACKs and lifecycle events use separate requests, so their arrival order is not native state order.
+      if (bound && event.type === "agent_settled" && (event.generation === undefined || event.generation === this.budgetGeneration)) this.rosterLifecycleRevision++;
+      if (!bound && event.type !== "session_shutdown") return;
+    }
+    if (this.rosterDetached && event.type !== "session_shutdown") return;
+    if (this.rosterUnownedRun && event.type !== "session_shutdown") {
+      if (event.type === "agent_settled" && (event.generation === undefined || event.generation === this.budgetGeneration)) {
+        this.rosterUnownedRun = false; this.agentRunning = false;
+        if (!this.stopping && this.verifiedOwner() && !this.activeTools) this.setState("idle");
+      }
+      return;
+    }
     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.fencedPrompt ||= event.fencedPrompt === 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; }
@@ -625,6 +770,7 @@ export class PiPeer extends BasePeer {
       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 = [];
+      this.hubPromptId = undefined; this.hubPromptGeneration = undefined;
       this.executionAbort?.abort(); this.executionAbort = undefined;
       this.approvalExpiries = 0; this.approvalAnswerEpoch = undefined; this.approvalStopReason = ""; this.approvalAbortSent = false;
       this.abortedToolIds.clear(); this.abortIdsOverflow = false;
@@ -643,7 +789,9 @@ export class PiPeer extends BasePeer {
   }
   private sendTui(command: Record<string, unknown>): Promise<any> {
     const id = `ahub-${++this.seq}`;
-    const wire = { id, ...command };
+    const fenced = this.fencedPrompt && command.type === "prompt";
+    if (fenced) { this.pendingPromptId = id; this.hubPromptId = id; this.hubPromptGeneration = undefined; }
+    const wire = { id, ...command, ...(fenced ? { sessionId: this.sessionId, generation: this.budgetGeneration } : {}) };
     return new Promise((resolvePromise, reject) => {
       const timer = setTimeout(() => {
         this.tuiCommands.delete(id);
@@ -655,7 +803,7 @@ export class PiPeer extends BasePeer {
       if (waiter) { clearTimeout(waiter.timer); waiter.resolve(wire); } else this.tuiQueue.push(wire);
     });
   }
-  private handleRpc(message: RpcMessage): void { if (["message_update", "tool_execution_update"].includes(message.type ?? "") && this.state === "busy") this.touch();  if (message.type === "agent_settled") return; // The authenticated extension is the single lifecycle source.
+  private handleRpc(message: RpcMessage): void { if (this.acceptingTools && ["message_update", "tool_execution_update"].includes(message.type ?? "") && this.state === "busy") this.touch();  if (message.type === "agent_settled") return; // The authenticated extension is the single lifecycle source.
     if (message.id !== undefined) { const pending = this.pending.get(String(message.id)); if (pending) { this.pending.delete(String(message.id)); message.success === false ? pending.reject(new Error(message.error ?? "Pi RPC command failed")) : pending.resolve(message); } } }
   private sendRpc(command: Record<string, unknown>): Promise<RpcMessage> { if (!this.proc?.stdin.writable) return Promise.reject(new Error("Pi process is not running")); const id = `ahub-${++this.seq}`; return new Promise((resolvePromise, reject) => { const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Pi RPC ${String(command.type)} timed out`)); }, 30_000); this.pending.set(id, { resolve: (m) => { clearTimeout(timer); resolvePromise(m); }, reject: (e) => { clearTimeout(timer); reject(e); } }); this.proc!.stdin.write(`${JSON.stringify({ id, ...command })}\n`); }); }
   private async waitRpc(command: string, timeout: number): Promise<RpcMessage> {
@@ -688,7 +836,7 @@ export class PiPeer extends BasePeer {
     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.requestedStopReason) {
+    if (envs.length && !this.requestedStopReason && !this.rosterDetached) {
       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"));
     }
@@ -712,7 +860,7 @@ export class PiPeer extends BasePeer {
   }
   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;
+    if (!this.agentRunning || generation !== this.budgetGeneration || this.approvalStopReason !== reason || !this.acceptingTools || this.state === "offline") return;
     this.executionAbort?.abort();
     if (this.approvalTurnAbort) {
       try { await this.sendTui({ type: "abort_budget", generation, cause: "approval", reason }); return; }
@@ -742,7 +890,7 @@ export class PiPeer extends BasePeer {
     }
   }
   protected override onWatchdog(): void {
-    if (this.stopping) return;
+    if (this.stopping || this.rosterDetached || this.rosterUnownedRun) return;
     if (this.activeTools) { this.touch(); return; }
     void this.terminateFailedTurn(new Error("Pi run became inactive before agent_settled"));
   }

package/src/cli/attention.ts

@@ -0,0 +1,60 @@
+import { needs, type Needs, type NeedsInput, type NeedItem } from "../ui/needs.ts";
+import { petFrame, type CharacterId, type PetPose } from "../pet/frame.ts";
+export interface AttentionState {
+  approvals: readonly { id: string; peer?: string; expiresAt: number }[];
+  permissionDefaults: readonly { peer: string }[];
+  peers: Record<string, { state?: string; attached?: boolean; needsReview?: number; heldBy?: string }>;
+  budget: Record<string, { paused?: { since?: number; resetsAt?: number } }>;
+  attentionMessages?: readonly { id?: string; peer?: string; important: boolean; since?: number }[];
+  storageBlocked?: boolean;
+  recoveryNeed?: { id?: string; running: boolean; since?: number };
+  queue?: readonly { id: string; peer?: string; state: string }[];
+  attentionFacts?: { kind: "review" | "offline"; id: number; peer?: string }[];
+}
+/** Allowlisted adapter between console-owned facts and the shared body-free model. */
+export function consoleNeeds(state: AttentionState, now: number): Needs {
+  const input: NeedsInput = { approvals: state.approvals.map(row => ({ id: row.id, peer: row.peer, expiresAt: row.expiresAt })), defaults: state.permissionDefaults.map(row => ({ peer: row.peer })), peers: Object.fromEntries(Object.entries(state.peers).map(([peer,row]) => [peer,{ state: row.state, attached: row.attached, needsReview: row.needsReview, heldBy: row.heldBy }])), budget: Object.fromEntries(Object.entries(state.budget).map(([peer,row]) => [peer,{ ...(row.paused ? { paused: { since: row.paused.since, resetsAt: row.paused.resetsAt } } : {}) }])), messages: (state.attentionMessages ?? []).map(row => ({ id: row.id, peer: row.peer, important: row.important, since: row.since })), storageBlocked: state.storageBlocked, recovery: state.recoveryNeed };
+  const result = needs({ ...input, facts: state.attentionFacts }, now);
+  // Panel snapshots know each held row; enrich only ids, without changing the status-derived count.
+  const used = new Set<string | number>();
+  for (const item of result.items) if (item.kind === "delivery") {
+    const eligible = (row: { id: string; peer?: string; state: string }) => row.state === "needs_review" && row.peer === item.peer && !used.has(row.id) && /^[A-Za-z0-9_.:-]{1,128}$/.test(row.id);
+    const row = state.queue?.find(row => row.id === item.id && eligible(row)) ?? state.queue?.find(eligible);
+    if (row) { item.id = row.id; used.add(row.id); }
+    else if (item.id !== undefined) used.add(item.id);
+  }
+  return result;
+}
+export function attentionLine(value: Needs, now = 0, blink = false, next = true): string {
+  const label = value.state === "waiting" ? `! ${value.act} need you` : value.state === "blocked" ? `! blocked (${value.act})` : value.state === "review" ? `? ${value.act} for review` : value.state === "working" ? "* working" : value.state === "idle" ? "idle" : "z asleep";
+  const eyes = blink && value.items.some(item => item.kind === "approval") && Math.floor(now / 1000) % 2 ? "(- -)" : "(O O)";
+  return `${eyes} ${label}${value.watch ? ` +${value.watch}` : ""}${next && value.items.length ? "  n next" : ""}`;
+}
+
+/** Preserve the shipped line layout; only its trusted built-in face is selectable. */
+export function characterAttentionLine(value: Needs, character: CharacterId = "stai", now = 0, blink = false, next = true, glyphs: "ascii" | "blocks" = "ascii"): string {
+  const pose: PetPose = blink && value.items.some(item => item.kind === "approval") && Math.floor(now / 1000) % 2 ? "waitingBlink" : value.state;
+  return petFrame(character, pose, "line", glyphs)[0]! + attentionLine(value, now, blink, next).slice(5);
+}
+
+/** Accept only body-free board facts from the authenticated status reply. */
+export function attentionFacts(raw: unknown): NonNullable<AttentionState["attentionFacts"]> {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap<NonNullable<AttentionState["attentionFacts"]>[number]>(row => {
+    if (!row || typeof row !== "object" || !Number.isSafeInteger(row.id) || row.id < 1) return [];
+    if (row.kind === "review" && row.level === "act") return [{ kind: "review" as const, id: row.id }];
+    if (row.kind === "offline" && row.level === "watch" && typeof row.peer === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(row.peer)) return [{ kind: "offline" as const, id: row.id, peer: row.peer }];
+    return [];
+  });
+}
+
+export function attentionCommand(item: NeedItem): string {
+  if (item.kind === "delivery") return `ahub queue list${item.id ? `; ahub queue show ${item.id}` : ""}`;
+  if (item.kind === "review") return `ahub task show ${item.id}; ahub review ${item.id} approved|changes_requested`;
+  if (item.kind === "offline") return `ahub status; ahub task show ${item.id}; ahub task assign ${item.id} <peer>`;
+  if (item.kind === "storage") return "ahub doctor";
+  if (item.kind === "recovery") return `ahub recovery status${item.id ? ` ${item.id}` : ""}`;
+  if (item.kind === "budget") return "ahub budget";
+  if (item.kind === "default") return "ahub permission";
+  return item.peer ? `ahub say @${item.peer} <message>` : "ahub console";
+}