@staix/agent-hub 0.12.23 → 0.12.24

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

@@ -99,6 +99,10 @@ export class PiPeer extends BasePeer {
   private ownerClaimed = false;
   private ownerToken = "";
   private stopping = true;
+  private rosterDetached = false;
+  private rosterEpoch = 0;
+  /** 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 +122,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 +175,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 +196,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 +242,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 +273,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 +281,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,6 +316,7 @@ 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.exitReported = false; this.started = false; this.lastToolName = undefined; this.shutdownExit = undefined;
@@ -403,8 +409,46 @@ 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");
+    const epoch = this.rosterEpoch, 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");
+    this.rosterDetached = false;
+    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,15 +526,19 @@ 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;
     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);
@@ -498,6 +546,10 @@ export class PiPeer extends BasePeer {
       else await this.sendRpc({ type: "prompt", message: renderDigest(envs, true) });
       if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
+      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) });
@@ -515,10 +567,12 @@ export class PiPeer extends BasePeer {
   }
 
   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 || 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 +581,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,6 +597,24 @@ export class PiPeer extends BasePeer {
   }
 
   private handleBridgeEvent(event: any): void {
+    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.budgetGeneration = event.generation;
+        this.noteActivity(); // personal native activity also revokes an earlier ID-only empty-resume proof
+      }
+      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 ?? ""); }
@@ -655,7 +729,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 +762,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 +786,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 +816,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";
+}

package/src/cli/bench.ts

@@ -7,9 +7,11 @@ import { ControlClient } from "../hub/control-client.ts";
 import { readEvents } from "../hub/events.ts";
 import { hubGitArgv, hubGitEnv } from "../hub/git.ts";
 import { taskRecords } from "../hub/research.ts";
-import { appendBench, BENCH_SCHEMA, parseSuite, suiteHash, type Attempt, type AttemptError, type AttemptMetrics, type Fingerprint, type Outcome, type SuiteTask } from "../hub/bench.ts";
+import { appendBench, BENCH_SCHEMA, memoryMode, type MemoryMode, parseSuite, suiteHash, type Attempt, type AttemptError, type AttemptMetrics, type Fingerprint, type Outcome, type SuiteTask } from "../hub/bench.ts";
 import { hubHome, realPath } from "../hub/project.ts";
 import { processSignature } from "../pi/process-signature.ts";
+import { loadConfig } from "../hub/daemon.ts";
+import { addonState, detectTooling, type Addon, type AddonName } from "../hub/tooling.ts";
 import { VERSION } from "../version.ts";
 
 /** What the runner needs from the world, so tests can drive it without a terminal. */
@@ -24,8 +26,12 @@ export interface BenchIo {
   now(): number;
   sleep(ms: number): Promise<void>;
   log(line: string): void;
+  /** #248: the add-ons a peer works with; `detectTooling` on this machine unless a test supplies its own. */
+  tooling?(peer: string): Addon[] | Promise<Addon[]>;
+  /** #258: the memory settings the project's hub runs with; the project config unless a test supplies them. */
+  memoryConfig?(): { enabled: boolean; native?: boolean };
 }
-export interface BenchOptions { cwd: string; stateDir: string; suitePath: string; arm: string; repeat: number; only?: string[]; home?: string; pollMs?: number; verifyTimeoutMs?: number; setupTimeoutMs?: number; settleMs?: number; stopped?: () => boolean }
+export interface BenchOptions { cwd: string; stateDir: string; suitePath: string; arm: string; repeat: number; addons?: Partial<Record<AddonName, "on" | "off">>; memory?: MemoryMode; only?: string[]; home?: string; pollMs?: number; verifyTimeoutMs?: number; setupTimeoutMs?: number; settleMs?: number; stopped?: () => boolean }
 
 const fail = (message: string): never => { throw new Error(message); };
 
@@ -192,12 +198,25 @@ export async function runBench(opts: BenchOptions, io: BenchIo): Promise<string>
       // ponytail: the hub's status reports a requested model for Pi only and permission modes once #242 lands; the rest
       // are recorded as absent. Reading each peer's launch settings would fill them in.
       // The status lists every peer the hub has known; an arm is the ones attached now.
-      peers: Object.entries(status.peers ?? {}).filter(([, p]) => p.state !== "offline")
-        .map(([id, p]) => ({ id, ...(p.requestedModel ? { model: p.requestedModel } : {}), ...(p.permissionMode ? { permissionMode: p.permissionMode } : {}) })).sort((a, b) => a.id.localeCompare(b.id)),
+      peers: (await Promise.all(Object.entries(status.peers ?? {}).filter(([, p]) => p.state !== "offline")
+        .map(async ([id, p]) => ({ id, ...(p.requestedModel ? { model: p.requestedModel } : {}), ...(p.permissionMode ? { permissionMode: p.permissionMode } : {}),
+          addons: await (io.tooling ?? ((peer: string) => detectTooling(peer, { cwd: opts.cwd })))(id) })))).sort((a, b) => a.id.localeCompare(b.id)),
       routingHash: existsSync(routing) ? createHash("sha256").update(readFileSync(routing)).digest("hex") : null,
       hubVersion: status.version,
     };
+    // #248: a declared add-on condition must hold for the attached peers before anything is recorded or reset.
+    const addons = Object.entries(opts.addons ?? {}) as [AddonName, "on" | "off"][];
+    for (const [name, want] of addons) {
+      const found = addonState(name, fingerprint.peers.map((p) => p.addons));
+      if (found !== want) throw new Error(`the arm declares ${name} ${want}, but the attached peers have it ${found}; change their setup or the declaration (nothing was run)`);
+    }
+    // #258 AC11: the memory the project's hub runs with (its config, read at hub start) must be the arm's.
+    // ponytail: read from the project config, not the running hub; a config edited since the hub started reads wrong.
+    const runsWith = opts.memory ? memoryMode((io.memoryConfig ?? (() => loadConfig(opts.cwd).memory))()) : undefined;
+    if (opts.memory && runsWith !== opts.memory) throw new Error(`the arm declares memory ${opts.memory}, but this project's hub runs with ${runsWith}; change memory.enabled / memory.native and restart the hub, or the declaration (nothing was run)`);
+    const condition = { ...(addons.length ? { addons: Object.fromEntries(addons.sort(([a], [b]) => a.localeCompare(b))) } : {}), ...(opts.memory ? { memory: opts.memory } : {}) };
     appendBench({ schema: BENCH_SCHEMA, kind: "run", run, suite: suite.name, suiteHash: suiteHash(suiteText), arm: opts.arm, fingerprint, version: VERSION,
+      ...(Object.keys(condition).length ? { condition } : {}),
       startedAt: new Date(io.now()).toISOString(), tasks: tasks.length, repeats: opts.repeat, order: tasks.map((t) => t.id), runner: { pid: process.pid, signature: processSignature(process.pid) ?? null } }, home);
     io.log(`bench run ${run}: ${suite.name} [${opts.arm}], ${tasks.length} task${tasks.length === 1 ? "" : "s"} x ${opts.repeat}`);
     let stopped: "timeout" | "interrupted" | "error" | undefined;
@@ -237,7 +256,7 @@ async function runAttempt(task: SuiteTask, commit: string, repeat: number, run:
   // The attempt ends when its outcome is known: the wait for its measures is not part of its time.
   const done = (outcome: Outcome, extra: { error?: AttemptError; verifyExit?: number | null; hubTask?: number | null; metrics?: AttemptMetrics | null; ended?: number; open?: boolean } = {}) => {
     const ended = extra.ended ?? io.now();
-    const attempt: Attempt = { schema: BENCH_SCHEMA, kind: "attempt", run, task: task.id, repeat, outcome, ...(extra.error ? { error: extra.error } : {}), verifyExit: extra.verifyExit ?? null,
+    const attempt: Attempt = { schema: BENCH_SCHEMA, kind: "attempt", run, arm: opts.arm, task: task.id, repeat, outcome, ...(extra.error ? { error: extra.error } : {}), verifyExit: extra.verifyExit ?? null,
       hubTask: extra.hubTask ?? null, startedAt: new Date(started).toISOString(), endedAt: new Date(ended).toISOString(), ms: ended - started, metrics: extra.metrics ?? null };
     return { attempt, open: extra.open ?? false };
   };

package/src/cli/board-read.ts

@@ -0,0 +1,12 @@
+/** Older same-protocol daemons may ignore newly added filter arguments. */
+export function supportsBoardReleaseFilter(status: unknown): boolean {
+  if (!status || typeof status !== "object") return false;
+  const capability = (status as Record<string,unknown>).boardReadCapabilities;
+  return !!capability && typeof capability === "object" && (capability as Record<string,unknown>).releaseFilter === true;
+}
+
+export function supportsBoardColumnMetadata(status: unknown): boolean {
+  if (!status || typeof status !== "object") return false;
+  const capability = (status as Record<string,unknown>).boardReadCapabilities;
+  return !!capability && typeof capability === "object" && (capability as Record<string,unknown>).columnMetadata === true;
+}