@staix/agent-hub 0.12.2 → 0.12.3

package/src/adapters/local-worker.ts

@@ -6,7 +6,9 @@ import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { runTool, TOOL_SCHEMAS, touchedPaths, type ToolContext } from "../local/tools.ts";
 import type { Capture } from "../memory/capture.ts";
 import type { ChatMessage, ChatResult, OmniRoute } from "../omniroute/client.ts";
+import { safeModelLabel } from "../omniroute/usage.ts";
 import type { Sidecar } from "../switchyard/sidecar.ts";
+import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 
 export interface LocalOptions {
   cwd: string;
@@ -21,6 +23,10 @@ export interface LocalOptions {
   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>;
+  /** Successful provider responses only; usage may be absent when the gateway omits it. Never includes prompt data. */
+  onUsage?: (record: { id: string; at: string; usage?: ChatResult["usage"]; requestedModel: string; servedModel?: string; provider?: string }) => void;
+  /** Atomic task/run admission immediately before every model request or tool execution. */
+  admitBudget?: (envs: Envelope[], unit: "model_calls" | "tool_calls") => Promise<ExecutionBudgetDecision[]>;
   /** Per-turn policy from the task the delivery carries: the class's route, and whether it is a PII task. */
   turnPolicy?: (envs: Envelope[]) => { route?: string; fixedModel?: string; pii: boolean; task?: string } | undefined;
   /** Role contract, appended to the system prompt. */
@@ -35,6 +41,7 @@ const HISTORY_CHARS = 100_000;
 const TURN_CHARS = 120_000;
 /** Tools whose effects outlive a failed turn: once one ran, the turn is never redelivered. */
 const SIDE_EFFECTS = new Set(["write", "edit", "bash", "git", "hub_send"]);
+class ExecutionBudgetStop extends Error { readonly budgetStop = true; }
 const chars = (msgs: ChatMessage[]) => msgs.reduce((n, m) => n + (m.content?.length ?? 0) + JSON.stringify(m.tool_calls ?? "").length, 0);
 
 const asFunction = (t: { name: string; description: string; inputSchema: unknown }) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.inputSchema } });
@@ -57,6 +64,8 @@ export class LocalPeer extends BasePeer {
   private readonly sessionId = `agent-hub-local-${randomUUID()}`;
   private turn = 0; // generation guard, as in acp.ts: a turn aborted by the watchdog must not touch the next one
   private abort: AbortController | undefined;
+  private budgetTimer?: ReturnType<typeof setTimeout>;
+  private budgetStopReason = "";
   private activeDeliveryId: string | undefined;
   private readonly sandboxProfile: string; // built once: profile() spawns git and must stay off the per-call path
   /** What served the last call, for `ahub status`. */
@@ -83,6 +92,7 @@ export class LocalPeer extends BasePeer {
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "turn stopped before settlement" });
     this.activeDeliveryId = undefined;
     this.turn++;
+    clearTimeout(this.budgetTimer); this.budgetTimer = undefined;
     this.abort?.abort();
     await this.opts.capture?.end();
     this.setState("offline");
@@ -95,7 +105,10 @@ export class LocalPeer extends BasePeer {
       throw new Error(`${this.id} is ${this.state}`);
     }
     const turn = ++this.turn;
+    this.budgetStopReason = "";
+    clearTimeout(this.budgetTimer); this.budgetTimer = undefined;
     this.activeDeliveryId = deliveryId;
+    this.abort = new AbortController();
     this.setState("busy");
     if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
     // The turn works on its own message list and joins the history only as a whole, so a failed or aborted turn can
@@ -115,7 +128,12 @@ export class LocalPeer extends BasePeer {
       })
       .catch((e: Error) => {
         if (turn !== this.turn) return; // aborted by the watchdog or stop(): nothing to report, nothing was committed
+        if (this.budgetStopReason && !(e instanceof ExecutionBudgetStop)) e = new ExecutionBudgetStop(this.budgetStopReason);
         this.opts.log?.(`[${this.id}] turn failed: ${e.message}`);
+        if (e instanceof ExecutionBudgetStop) {
+          this.reportBudgetStop(e, msgs, progress, reply, !!policy?.pii, deliveryId);
+          return;
+        }
         if (!progress.sideEffects) {
           if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: e.message });
           else this.onFailed?.(envs); // legacy delivery: safe to redeliver
@@ -130,6 +148,7 @@ export class LocalPeer extends BasePeer {
         if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
       })
       .finally(() => {
+        if (turn === this.turn) { clearTimeout(this.budgetTimer); this.budgetTimer = undefined; }
         if (turn === this.turn && this.state === "busy") this.setState("idle");
         if (turn === this.turn && this.activeDeliveryId === deliveryId) this.activeDeliveryId = undefined;
       });
@@ -139,6 +158,7 @@ export class LocalPeer extends BasePeer {
     if (this.activeDeliveryId) this.delivery({ id: this.activeDeliveryId, state: "needs_review", reason: "turn watchdog timeout" });
     this.activeDeliveryId = undefined;
     this.turn++;
+    clearTimeout(this.budgetTimer); this.budgetTimer = undefined;
     this.abort?.abort();
     super.onWatchdog();
   }
@@ -152,6 +172,7 @@ export class LocalPeer extends BasePeer {
     reply: EnvelopeOpts,
   ): Promise<string> {
     const { maxSteps = 30 } = this.opts;
+    const turnSignal = this.abort!.signal;
     // claude-mem's observer is a cloud model: nothing of a PII turn is captured.
     const capture = policy?.pii ? undefined : this.opts.capture;
     // Positive confirmation, and for the path this turn will really take: a sidecar generated against the off-campus URL
@@ -160,22 +181,11 @@ export class LocalPeer extends BasePeer {
     if (policy?.pii && (viaOffCampus || !(await this.opts.omni.onCampus()))) {
       return "Refused: this is a PII task and the only reachable gateway is off campus (Cloudflare Access). Connect the VPN and assign it again.";
     }
-    const ctx: ToolContext = {
-      cwd: this.opts.cwd,
-      deny: this.opts.tools.deny,
-      permit: this.opts.tools.permit,
-      sandboxProfile: this.sandboxProfile,
-      sandboxEnv: proxyEnv(this.opts.tools.bashNetwork ?? false),
-      send: (text, to) => {
-        const refused = this.onMessage?.(text, policy?.pii ? reply : { inReplyTo: replyParent(envs), to: to?.length ? to : replyAudience(envs) });
-        if (typeof refused === "string") return `not sent: ${refused}`;
-        return policy?.pii ? "sent to the console user only (PII task)" : "sent";
-      },
-    };
+    const ctx = this.toolContext(envs, turnSignal, !!policy?.pii, reply);
     let usedTools = false;
     for (let step = 0; step < maxSteps; step++) {
       this.elide(msgs);
-      const res = await this.call(msgs, policy);
+      const res = await this.call(msgs, policy, envs);
       if (turn !== this.turn) return "";
       this.touch();
       msgs.push(res.message);
@@ -188,6 +198,10 @@ export class LocalPeer extends BasePeer {
         // A tool has its own timeout (bash up to 600 s) and an approval can take 120 s: neither is the model going silent.
         const alive = setInterval(() => this.state === "busy" && turn === this.turn && this.touch(), 30_000);
         const name = call.function.name;
+        try {
+          await this.requireBudget(envs, "tool_calls");
+          if (turnSignal.aborted) throw new ExecutionBudgetStop(this.budgetStopReason || "turn cancelled before tool execution");
+        } catch (error) { clearInterval(alive); throw error; }
         const running = TASK_TOOL_NAMES.has(name) && this.opts.taskTool ? this.opts.taskTool(name, safeParse(call.function.arguments), { pii: !!policy?.pii }).catch((e: Error) => `error: ${e.message}`) : runTool(name, call.function.arguments, ctx);
         const output = await running.finally(() => clearInterval(alive));
         if (turn !== this.turn) return "";
@@ -202,32 +216,111 @@ export class LocalPeer extends BasePeer {
     return `(stopped after ${maxSteps} steps) ${progress.last}`.trim();
   }
 
+  private toolContext(envs: Envelope[], turnSignal: AbortSignal, pii: boolean, reply: EnvelopeOpts): ToolContext {
+    return {
+      cwd: this.opts.cwd,
+      deny: this.opts.tools.deny,
+      permit: async (title) => {
+        if (turnSignal.aborted) return false;
+        return new Promise<boolean>((resolve, reject) => {
+          const finish = (allowed: boolean) => { turnSignal.removeEventListener("abort", onAbort); resolve(allowed); };
+          const onAbort = () => finish(false);
+          turnSignal.addEventListener("abort", onAbort, { once: true });
+          this.opts.tools.permit(title).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+        });
+      },
+      sandboxProfile: this.sandboxProfile,
+      sandboxEnv: proxyEnv(this.opts.tools.bashNetwork ?? false),
+      signal: turnSignal,
+      send: (text, to) => {
+        const refused = this.onMessage?.(text, pii ? reply : { inReplyTo: replyParent(envs), to: to?.length ? to : replyAudience(envs) });
+        if (typeof refused === "string") return `not sent: ${refused}`;
+        return pii ? "sent to the console user only (PII task)" : "sent";
+      },
+    };
+  }
+
+  private reportBudgetStop(e: Error, msgs: ChatMessage[], progress: { sideEffects: number; last: string }, reply: EnvelopeOpts, pii: boolean, deliveryId?: string): void {
+    this.completeMissingToolResults(msgs, `not run: ${e.message}`);
+    const detail = progress.sideEffects
+      ? `(execution budget stopped after ${progress.sideEffects} tool call(s) with side effects; partial work may exist and needs review) ${progress.last}`.trim()
+      : `(execution budget stopped before any tool side effects; no work was repeated) ${progress.last}`.trim();
+    msgs.push({ role: "assistant", content: detail });
+    if (!pii) this.commit(msgs);
+    this.onMessage?.(detail, reply);
+    if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "needs_review", reason: e.message });
+  }
+
+  private async requireBudget(envs: Envelope[], unit: "model_calls" | "tool_calls"): Promise<void> {
+    if (!this.opts.admitBudget) return;
+    const decisions = await this.opts.admitBudget(envs, unit);
+    const denied = decisions.find((decision) => !decision.allowed);
+    if (denied) throw new ExecutionBudgetStop(`execution budget ${denied.reason ?? "exhausted"}: ${denied.scope} ${denied.unit} used ${denied.used}${denied.limit === null ? "" : ` of ${denied.limit}`}`);
+    const remaining = decisions.filter((decision) => decision.unit === "elapsed_ms" && decision.remaining !== null).reduce<number | undefined>((min, decision) => min === undefined ? decision.remaining! : Math.min(min, decision.remaining!), undefined);
+    if (remaining !== undefined) {
+      clearTimeout(this.budgetTimer);
+      this.budgetTimer = setTimeout(() => {
+        this.budgetStopReason = "execution budget exhausted: elapsed_ms wall cap reached";
+        this.abort?.abort();
+      }, Math.max(0, remaining));
+    }
+  }
+
+  /** Preserve valid model history when admission stops in the middle of a parallel tool-call batch. */
+  private completeMissingToolResults(msgs: ChatMessage[], result: string): void {
+    const called = new Set<string>();
+    for (const msg of msgs) if (msg.role === "tool" && msg.tool_call_id) called.add(msg.tool_call_id);
+    const missing: string[] = [];
+    for (const msg of msgs) if (msg.role === "assistant") for (const call of msg.tool_calls ?? []) if (call.id && !called.has(call.id)) {
+      called.add(call.id); missing.push(call.id);
+    }
+    for (const tool_call_id of missing) msgs.push({ role: "tool", tool_call_id, content: result });
+  }
+
   /** L2 when the sidecar is up, otherwise (or when a call through it fails) the fixed model on L3. */
-  private async call(turnMsgs: ChatMessage[], policy?: { route?: string; fixedModel?: string }): Promise<ChatResult> {
+  private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string } | undefined, envs: Envelope[]): Promise<ChatResult> {
     const { omni, sidecar } = this.opts;
     // A task turn asks for its class's route; a route needs the sidecar, which exists only when the worker was started with one.
     const route = sidecar ? (policy?.route ?? this.opts.route) : undefined;
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
     const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? TASK_TOOLS.map(asFunction) : [])];
-    this.abort = new AbortController();
-    const signal = this.abort.signal;
+    const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
     const via = route ? await sidecar?.endpoint() : undefined;
     if (via) {
+      await this.requireBudget(envs, "model_calls");
       try {
         const res = await omni.chat({ model: route!, messages, tools }, { via, sessionId: this.sessionId, signal });
         this.lastServedBy = `switchyard ${route} -> ${res.selectedModel ?? "?"}`;
+        this.recordUsage(res, route!);
         return res;
       } catch (e) {
         if (signal.aborted) throw e;
         sidecar!.disable((e as Error).message);
       }
     }
+    await this.requireBudget(envs, "model_calls");
     const res = await omni.chat({ model: fixedModel, messages, tools }, { signal });
     this.lastServedBy = `omniroute ${fixedModel} (provider ${res.provider ?? "?"})`;
+    this.recordUsage(res, fixedModel);
     return res;
   }
 
+  private recordUsage(res: ChatResult, requestedModel: string): void {
+    try {
+      this.opts.onUsage?.({
+        id: randomUUID(),
+        at: new Date().toISOString(),
+        ...(res.usage ? { usage: res.usage } : {}),
+        requestedModel: safeModelLabel(requestedModel) ?? "unknown",
+        ...(safeModelLabel(res.servedModel ?? res.selectedModel) ? { servedModel: safeModelLabel(res.servedModel ?? res.selectedModel)! } : {}),
+        ...(safeModelLabel(res.provider) ? { provider: safeModelLabel(res.provider)! } : {}),
+      });
+    } catch {
+      // Usage persistence is optional and must never affect a provider call or turn.
+    }
+  }
+
   /** A finished turn joins the history; whole old turns (user message up to the next one) fall off the front, so tool calls keep their results. */
   private commit(msgs: ChatMessage[]): void {
     this.history.push(...msgs);

package/src/adapters/pi.ts

@@ -6,6 +6,7 @@ import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId }
 import { BasePeer } from "../hub/peers.ts";
 import { stopOwnedProcess } from "../hub/child-process.ts";
 import { realPath } from "../hub/project.ts";
+import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
 export interface PiToolSchema { name: string; description?: string; parameters: Record<string, unknown>; }
@@ -13,9 +14,11 @@ export interface PiRelay { url: string; token: string; models: PiModelDescriptor
 export interface PiOptions {
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
-  relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string) => Promise<string>; tools: PiToolSchema[];
+  relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal) => Promise<string>; tools: PiToolSchema[];
   preamble?: string;
   selectModel?: (envs: Envelope[]) => Promise<string | undefined>; maxSteps?: number;
+  /** Atomic task/run admission immediately before provider requests or tool execution. */
+  admitBudget?: (envs: Envelope[], unit: ExecutionUnit) => Promise<ExecutionBudgetDecision[]>;
   /** Reported message usage as increments, before agent_settled releases the turn. */
   onTokens?: (added: number) => void;
   onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void>;
@@ -51,6 +54,11 @@ export class PiPeer extends BasePeer {
   private currentReply?: Envelope;
   private sessionId = "";
   private sessionFile = "";
+  private executionBudgetTimer?: ReturnType<typeof setTimeout>;
+  private executionAbort?: AbortController;
+  private readonly budgetStops = new Map<number, string>();
+  private readonly idleBashReservations = new Map<string, { generation: number; expiresAt: number; deadlineAt?: number }>();
+  private budgetGeneration = 0;
   private emptyResumeVerified = false;
   private verifiedEmptyResume?: VerifiedEmptyResume;
   private activityObserved = false;
@@ -132,11 +140,87 @@ export class PiPeer extends BasePeer {
     this.verifiedEmptyResume = undefined;
   }
 
+  /** Envelopes belonging to the currently executing Pi turn, for relay-side model-call admission. */
+  get budgetEnvelopes(): Envelope[] { return 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;
+    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);
+    this.executionAbort?.abort();
+    for (const old of this.budgetStops.keys()) if (old < generation - 8) this.budgetStops.delete(old);
+    return { generation, reason };
+  }
+
   async start(): Promise<void> {
     if (this.starting) return this.starting;
     this.starting = this.startImpl();
     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 });
+    let executionSignal = this.executionAbort?.signal;
+    let idleBashTimer: ReturnType<typeof setTimeout> | undefined;
+    if (body.purpose === "idle_user_bash") {
+      const reservation = typeof body.reservation === "string" ? this.idleBashReservations.get(body.reservation) : undefined;
+      if (!reservation || reservation.expiresAt < Date.now() || reservation.generation !== body.generation || !this.ownerClaimed || this.ownerPid === undefined || this.state !== "idle" || this.agentRunning || this.activeTools > 0 || this.activeEnvs.length > 0 || !Number.isSafeInteger(body.generation) || body.generation !== this.budgetGeneration) return Response.json({ text: "error: stale or non-idle Pi user shell request" }, { status: 409 });
+      if (reservation.deadlineAt !== undefined && reservation.deadlineAt <= Date.now()) {
+        this.idleBashReservations.delete(String(body.reservation));
+        return Response.json({ text: "error: Pi user shell execution budget expired" }, { status: 409 });
+      }
+      this.idleBashReservations.delete(String(body.reservation));
+      const idleBashAbort = new AbortController();
+      executionSignal = idleBashAbort.signal;
+      if (reservation.deadlineAt !== undefined) idleBashTimer = setTimeout(() => idleBashAbort.abort(), Math.max(0, reservation.deadlineAt - Date.now()));
+    }
+    this.noteActivity();
+    this.activeTools++;
+    if (this.state === "idle") this.setState("busy");
+    if (this.state === "busy") this.touch();
+    try { return Response.json({ text: await this.opts.executeTool(String(body.name), body.args, String(body.toolCallId ?? ""), this.sessionId, executionSignal) }); }
+    catch (error) { return Response.json({ text: `error: ${(error as Error).message}` }, { status: 200 }); }
+    finally {
+      clearTimeout(idleBashTimer);
+      this.activeTools--;
+      if (this.state === "busy") {
+        if (!this.activeTools && !this.agentRunning && !this.activeEnvs.length) this.setState("idle");
+        else this.touch();
+      }
+    }
+  }
+
+  private async handleBudgetRequest(body: any): Promise<Response> {
+    if (!["model_calls", "tool_calls"].includes(String(body.unit))) return Response.json({ error: "invalid Pi budget unit" }, { status: 400 });
+    const idleUserBash = body.idleUserBash === true;
+    const current = Number.isSafeInteger(body.generation) && body.generation === this.budgetGeneration;
+    const idleOwner = this.ownerClaimed && this.ownerPid !== undefined && this.state === "idle" && !this.agentRunning && this.activeTools === 0 && this.activeEnvs.length === 0;
+    if (!current || (idleUserBash ? !idleOwner : !this.agentRunning || this.state !== "busy")) return Response.json({ error: "stale Pi budget request" }, { status: 409 });
+    // An interactive user shell has no task delivery. It may spend an eligible run budget only.
+    const envs = idleUserBash ? [] : this.budgetEnvelopes;
+    const decisions = this.opts.admitBudget ? await this.opts.admitBudget(envs, body.unit as ExecutionUnit) : [];
+    const denied = decisions.find((decision) => !decision.allowed);
+    const remaining = decisions.filter((decision) => decision.unit === "elapsed_ms" && decision.remaining !== null).reduce<number | undefined>((min, decision) => min === undefined ? decision.remaining! : Math.min(min, decision.remaining!), undefined);
+    let reservation: string | undefined;
+    if (idleUserBash && !denied) {
+      for (const [key, value] of this.idleBashReservations) if (value.expiresAt < Date.now()) this.idleBashReservations.delete(key);
+      reservation = randomUUID();
+      this.idleBashReservations.set(reservation, { generation: body.generation, expiresAt: Date.now() + 30_000, ...(remaining === undefined ? {} : { deadlineAt: Date.now() + remaining }) });
+    }
+    clearTimeout(this.executionBudgetTimer);
+        if (!denied && remaining !== undefined && this.state === "busy") {
+          const generation = this.budgetGeneration;
+          const controller = this.executionAbort;
+          this.executionBudgetTimer = setTimeout(() => {
+            if (!this.agentRunning || generation !== this.budgetGeneration || controller !== this.executionAbort) return;
+            controller?.abort();
+            void this.sendTui({ type: "abort_budget", generation }).catch((error) => this.opts.log?.(`[${this.id}] elapsed budget stop could not reach Pi: ${(error as Error).message}`));
+          }, Math.max(0, remaining));
+        }
+    return Response.json({ decisions, ...(reservation ? { reservation } : {}) });
+  }
+
   private async startImpl(): Promise<void> {
     this.stopping = false;
     mkdirSync(this.opts.stateDir, { recursive: true });
@@ -168,22 +252,8 @@ export class PiPeer extends BasePeer {
         this.tuiCommands.delete(String(body.id)); body.ok ? pending.resolve(body.result) : pending.reject(new Error(String(body.error ?? "Pi TUI command failed")));
         return Response.json({ ok: true });
       }
-      if (url.pathname === "/tool") {
-        if (this.stopping || this.state === "offline") return Response.json({ text: "error: Pi owner is stopped" }, { status: 409 });
-        this.noteActivity();
-        this.activeTools++;
-        if (this.state === "idle") this.setState("busy");
-        if (this.state === "busy") this.touch();
-        try { return Response.json({ text: await this.opts.executeTool(String(body.name), body.args, String(body.toolCallId ?? ""), this.sessionId) }); }
-        catch (error) { return Response.json({ text: `error: ${(error as Error).message}` }, { status: 200 }); }
-        finally {
-          this.activeTools--;
-          if (this.state === "busy") {
-            if (!this.activeTools && !this.agentRunning && !this.activeEnvs.length) this.setState("idle");
-            else this.touch();
-          }
-        }
-      }
+      if (url.pathname === "/tool") return this.handleToolRequest(body);
+      if (url.pathname === "/budget") return this.handleBudgetRequest(body);
       return new Response("not found", { status: 404 });
     } });
     this.server = bridge;
@@ -340,7 +410,11 @@ export class PiPeer extends BasePeer {
       this.startOwnerMonitor(); if (this.opts.mode === "tui") this.setState("idle");
     }
     if (event.type === "session_shutdown") { this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor(); this.resolveTuiExit?.(); this.resolveTuiExit = undefined; this.fail(new Error("Pi session shut down before settlement")); }
-    if (event.type === "agent_start") { this.usageSeen.clear(); this.noteActivity(); this.agentRunning = true; this.setState("busy"); }
+    if (event.type === "agent_start") {
+      const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration + 1;
+      if (generation <= this.budgetGeneration) return;
+      this.usageSeen.clear(); this.idleBashReservations.clear(); this.executionAbort = new AbortController(); this.budgetGeneration = generation; this.noteActivity(); this.agentRunning = true; this.setState("busy");
+    }
     if (event.type === "activity" && this.state === "busy") this.touch();
     if (event.type === "tokens" && this.state === "busy" && typeof event.id === "string" && event.id.length <= 100 && Number.isSafeInteger(event.tokens) && event.tokens >= 0 && !this.usageSeen.has(event.id)) {
       this.usageSeen.add(event.id);
@@ -348,24 +422,35 @@ export class PiPeer extends BasePeer {
       if (event.tokens > 0) this.opts.onTokens?.(event.tokens);
     }
     if (event.type === "agent_end") {
+      if (Number.isSafeInteger(event.generation) && event.generation !== this.budgetGeneration) return;
+      clearTimeout(this.executionBudgetTimer); this.executionBudgetTimer = undefined;
+      const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration;
+      const budgetStop = this.budgetStops.get(generation);
+      if (budgetStop) this.executionAbort?.abort();
       this.settledText = typeof event.text === "string" ? event.text : "";
-      this.settledCancelled = event.cancelled === true;
-      this.settledError = event.failed ? String(event.error ?? "Pi agent run failed") : "";
+      this.settledCancelled = !budgetStop && event.cancelled === true;
+      this.settledError = budgetStop ?? (event.failed ? String(event.error ?? "Pi agent run failed") : "");
     }
     if (event.type === "agent_settled") {
+      if (Number.isSafeInteger(event.generation) && event.generation !== this.budgetGeneration) return;
+      clearTimeout(this.executionBudgetTimer); this.executionBudgetTimer = undefined;
       this.agentRunning = false;
       if (typeof event.text === "string" && event.text.trim()) this.settledText = event.text;
-      const text = this.settledText.trim(); const error = this.settledError; const cancelled = this.settledCancelled;
+      const generation = Number.isSafeInteger(event.generation) ? event.generation : this.budgetGeneration;
+      const text = this.settledText.trim(); const error = this.budgetStops.get(generation) ?? this.settledError; const cancelled = !error && this.settledCancelled;
+      this.budgetStops.delete(generation);
       this.settledText = ""; this.settledError = ""; this.settledCancelled = false;
       // Answer the peers this turn was for, not every peer on the bus (issue #29). activeEnvs still holds the
       // whole delivery here, steered additions included.
       const reply = { inReplyTo: this.currentReply, to: replyAudience(this.activeEnvs) };
       if (cancelled) this.onMessage?.("Pi turn cancelled; inspect any partial effects before continuing.", reply);
+      else if (error?.startsWith("execution budget")) this.onMessage?.(`Pi stopped at the execution budget: ${error}. Inspect partial work before continuing.`, reply);
       else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error);
       else if (text) this.onMessage?.(text, reply);
       for (const id of this.activeDeliveryIds) this.delivery({ id, state: error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
       this.activeDeliveryIds.clear();
       this.currentReply = undefined; this.activeEnvs = []; if (this.state === "busy" && !this.activeTools) this.setState("idle");
+      this.executionAbort = undefined;
     }
   }
 

package/src/cli/launch.ts

@@ -1,6 +1,23 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+/** A scoped candidate MCP server can be selected without promoting the installed plugin. */
+function claudeChannel(userArgs: string[]): string {
+  const bundle = resolve(import.meta.dir, "../../plugins/agent-hub/server.js");
+  for (let i = 0; i < userArgs.length; i++) {
+    const arg = userArgs[i]!;
+    const path = arg === "--mcp-config" ? userArgs[i + 1] : arg.startsWith("--mcp-config=") ? arg.slice("--mcp-config=".length) : undefined;
+    if (!path) continue;
+    try {
+      const server = JSON.parse(readFileSync(resolve(path), "utf8")).mcpServers?.["agent-hub"];
+      if (server?.command === "bun" && Array.isArray(server.args) && server.args.some((value: unknown) => typeof value === "string" && resolve(value) === bundle)) return "server:agent-hub";
+    } catch { /* The native CLI reports invalid user-supplied MCP configuration. */ }
+  }
+  return CLAUDE_CHANNEL;
+}
+
 const OWNED: Record<"claude" | "codex", string[]> = {
   claude: ["--dangerously-load-development-channels", "--dangerously-skip-permissions"],
   codex: ["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"],
@@ -53,7 +70,7 @@ export function buildLaunch(
     const notes = [unattended ? UNATTENDED_WARNING : "", ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : ""].filter(Boolean);
     return {
       cmd: "claude",
-      args: ["--dangerously-load-development-channels", CLAUDE_CHANNEL, ...(unattended ? ["--dangerously-skip-permissions"] : []), ...tee, ...passthrough],
+      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...tee, ...passthrough],
       ...(notes.length ? { warning: notes.join("\n") } : {}),
     };
   }

package/src/cli/main.ts

@@ -67,6 +67,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub say [@peer ...] <text>   send as the console user (no @peer = broadcast); delivered at once,
                                start the text with [STATUS] to let it batch or [FYI] for the record only
   ahub pause|resume <peer>      hold a peer's deliveries in its queue / release them
+  ahub budget execution configure <config.json> | status [id] | disable <id>
   ahub budget                   quota windows per peer, and who is paused until when
   ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]   feed a reading by hand (also: test the relay)
   ahub budget resume <peer>     override a budget pause; readings are ignored for that peer until the window resets
@@ -643,6 +644,18 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   budget: async () => {
     const hub = await connect();
+    if (args[0] === "execution") {
+      const op = args[1] ?? "status";
+      let request: Record<string, unknown> = { t: "execution_budget", op, ...(args[2] ? { id: args[2] } : {}) };
+      if (op === "configure") {
+        if (!args[2]) { hub.close(); fail("usage: ahub budget execution configure <config.json>"); }
+        try { request = { t: "execution_budget", op, config: JSON.parse(readFileSync(args[2]!, "utf8")) }; }
+        catch { hub.close(); fail("cannot read execution budget JSON configuration"); }
+      }
+      const result = await hub.request(request); hub.close();
+      if (!result.ok) fail(result.error);
+      return console.log(JSON.stringify(result.budgets ?? result.budget ?? { disabled: result.disabled }, null, 2));
+    }
     let set: Record<string, unknown> | undefined;
     if (args[0] === "resume") {
       if (!args[1]) fail("usage: ahub budget resume <peer>");

package/src/cli/status-lines.ts

@@ -1,6 +1,6 @@
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; attached?: boolean; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -15,6 +15,7 @@ export function peerLine(id: string, p: PeerRow): string {
     // Which queued messages the peer will not wait out the batch window for (issue #41).
     (p.queuedImportant ? ` (${p.queuedImportant} important)` : "") +
     (p.needsReview ? `  needs review ${p.needsReview}` : "") +
+    (p.liveAccepted?.length ? `  awaiting settlement ${p.liveAccepted.join(", ")} (adapter completion; Claude: reply or hub_delivery_done; task state is independent)` : "") +
     (p.heldBy ? `  ${p.holdNote ?? `held by needs_review ${p.heldBy}; ahub queue resolve ${p.heldBy} --action completed|retry|discard --reason <text>`}` : "") +
     (p.oldestQueuedAt !== undefined ? `  oldest ${Math.max(0, Math.floor((Date.now() - p.oldestQueuedAt) / 1000))}s` : "") +
     (p.attached === false ? "  disconnected" : "") +

package/src/cli/upgrade-runtime.ts

@@ -114,7 +114,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
-    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10 or protocol-11 source is required");
+    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10, protocol-11 or protocol-12 source is required");
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
     const sessions: { codex?: string; claude?: string; pi?: SessionRef } = {};
     for (const peer of source.peers) {

package/src/hub/bus.ts

@@ -340,12 +340,14 @@ export class Bus {
     void this.drain(record.peer);
   }
 
-  queueSummary(peer: string): { needsReview: number; heldBy?: string; oldestQueuedAt?: number } {
+  queueSummary(peer: string): { needsReview: number; heldBy?: string; liveAccepted?: string[]; oldestQueuedAt?: number } {
     const rows = this.storageError ? [] : this.queueList(peer);
     const queued = this.queues.get(peer) ?? [];
     const review = rows.filter((r) => r.state === "needs_review");
     const needsReview = review.length;
-    const hold = review[0] ? { heldBy: review[0].id } : {};
+    const blocked = rows.find((r) => r.state === "needs_review" || (["dispatching", "accepted"].includes(r.state) && !this.activeDeliveries.has(r.id)));
+    const liveAccepted = rows.filter((r) => r.state === "accepted" && this.activeDeliveries.get(r.id) === peer).map((r) => r.id);
+    const hold = { ...(blocked ? { heldBy: blocked.id } : {}), ...(liveAccepted.length ? { liveAccepted } : {}) };
     const oldest = queued.reduce<number | undefined>((a, r) => a === undefined ? r.ts : Math.min(a, r.ts), undefined);
     return oldest === undefined ? { needsReview, ...hold } : { needsReview, ...hold, oldestQueuedAt: oldest };
   }
@@ -379,7 +381,8 @@ export class Bus {
 
   private refreshRecoveryHold(peer: PeerId): void {
     if (!this.journal) return;
-    const blocked = this.journal.list(peer).some((r) => r.state === "needs_review" || r.state === "dispatching" || r.state === "accepted");
+    // Live accepted notifications are awaiting explicit correlation, not crash recovery.
+    const blocked = this.journal.list(peer).some((r) => r.state === "needs_review" || (["dispatching", "accepted"].includes(r.state) && this.activeDeliveries.get(r.id) !== peer));
     if (blocked) this.recoveryHeldPeers.add(peer); else this.recoveryHeldPeers.delete(peer);
   }
 
@@ -399,6 +402,17 @@ export class Bus {
     }
   }
 
+  /** Explicit completion never resolves recovered, unrelated or already uncertain work. */
+  completeDelivery(peer: PeerId, deliveryId: string): boolean {
+    const row = this.journal?.get(deliveryId);
+    // The bridge separately fences socket/generation/handed IDs. Retrying a completed
+    // acknowledgement (or acknowledging after a correlated reply) changes nothing.
+    if (row?.peer === peer && row.state === "completed") return true;
+    if (this.activeDeliveries.get(deliveryId) !== peer || row?.state !== "accepted") return false;
+    this.deliveryReceipt(peer, { id: deliveryId, state: "completed", reason: "explicit correlated completion" });
+    return true;
+  }
+
   queueIds(id: PeerId): string[] {
     return (this.queues.get(id) ?? []).map((e) => e.id);
   }

package/src/hub/control-client.ts

@@ -6,10 +6,10 @@ export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
-/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics. The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 11;
+/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets. The plugin is installed apart from the daemon, so they can drift. */
+export const PROTOCOL = 12;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
-export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, PROTOCOL] as const;
+export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, PROTOCOL] as const;
 
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */