@staix/agent-hub 0.12.2 → 0.12.3

package/src/hub/daemon.ts

@@ -6,7 +6,9 @@ import { spawn } from "node:child_process";
 import { childEnv } from "./child-process.ts";
 import { runCheck } from "./checks.ts";
 import { stripUntrusted } from "./config-trust.ts";
-import { eventLog, tokenDeltas } from "./events.ts";
+import { eventLog, readEvents, tokenDeltas } from "./events.ts";
+import { ExecutionBudget } from "./execution-budget.ts";
+import { readClaudeTranscriptUsage } from "./usage.ts";
 import type { ServerWebSocket } from "bun";
 import { AcpPeer, type PermissionRequest } from "../adapters/acp.ts";
 import { CodexPeer } from "../adapters/codex-appserver.ts";
@@ -218,6 +220,8 @@ type Sock = ServerWebSocket<Client>;
 
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 class WsPeer extends BasePeer {
+  private generation = crypto.randomUUID();
+  private delivered = new Set<string>();
   private sock: Sock | undefined;
   private claimed: Sock | undefined;
   /** Called at hello, before the async preface: the newest hello wins even if an older one's recall finishes last. */
@@ -231,8 +235,11 @@ class WsPeer extends BasePeer {
   }
   attach(sock: Sock): void {
     if (sock !== this.claimed) return void sock.close(4000, "replaced"); // a newer session said hello meanwhile
+    if (this.sock) this.setState("offline"); // unresolved work belongs to the previous connection
     this.sock?.close(4000, "replaced");
     this.sock = sock;
+    this.generation = crypto.randomUUID();
+    this.delivered.clear();
     this.setState("idle");
   }
   detach(sock: Sock): void {
@@ -242,9 +249,11 @@ class WsPeer extends BasePeer {
   }
   async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
     if (!this.sock) throw new Error(`${this.id} is offline`);
-    this.sock.send(JSON.stringify({ t: "deliver", envs, ...(deliveryId ? { deliveryId } : {}) }));
+    if (deliveryId) this.delivered.add(deliveryId);
+    this.sock.send(JSON.stringify({ t: "deliver", envs, generation: this.generation, ...(deliveryId ? { deliveryId } : {}) }));
   }
   owns(sock: Sock): boolean { return this.sock === sock; }
+  ownsDelivery(sock: Sock, generation: unknown, id: string): boolean { return this.owns(sock) && generation === this.generation && this.delivered.has(id); }
   async start(): Promise<void> {}
   async stop(): Promise<void> {
     this.sock?.close();
@@ -441,6 +450,8 @@ export async function startDaemon(opts: DaemonOptions) {
   };
   const board = new Board(join(opts.stateDir, "hub.db"));
   startupCleanup.push(() => board.close());
+  const executionBudget = new ExecutionBudget(join(opts.stateDir, "hub.db"));
+  startupCleanup.push(() => executionBudget.close());
   // Completion checks (issue #7): only from a config file git does not track, one at a time, killed on stop.
   const checkCommands = Object.fromEntries(Object.entries(config.checks).filter(([k, v]) => (CLASSES as readonly string[]).includes(k) && typeof v === "string" && v.trim())) as Record<string, string>;
   const strayChecks = Object.keys(config.checks).filter((k) => k !== "timeout_s" && !(k in checkCommands));
@@ -456,6 +467,7 @@ export async function startDaemon(opts: DaemonOptions) {
   const tasks = new Tasks({
     board,
     bus,
+    executionBudget,
     routing: () => currentRouting(opts.cwd, log), // routing.toml is edited while the hub runs: re-read on change, last good parse kept
     cwd: opts.cwd,
     project: chain.at(-1)!,
@@ -807,6 +819,20 @@ export async function startDaemon(opts: DaemonOptions) {
     const config = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
     return existsSync(join(config, "projects", opts.cwd.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`));
   };
+  // Optional native usage: only the instance-fenced explicit Claude session is read.
+  // IDs persist in telemetry, so a restart/resume never counts the same native message twice.
+  const claudeNativeUsageSeen = new Set(readEvents(join(opts.stateDir, "events.jsonl")).filter(e => e.type === "usage" && e.source === "claude_transcript").map(e => (e as { id: string }).id));
+  const collectClaudeUsage = () => {
+    const session = claudeSession();
+    if (!session.sessionId || !session.transcriptPath) return;
+    for (const record of readClaudeTranscriptUsage(session.sessionId, session.transcriptPath)) {
+      if (claudeNativeUsageSeen.has(record.id)) continue;
+      claudeNativeUsageSeen.add(record.id);
+      event({ type: "usage", peer: "claude", source: "claude_transcript", id: record.id, ...record.usage, ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.at ? { measuredAt: record.at } : {}) });
+    }
+  };
+  const claudeUsageTimer = setInterval(collectClaudeUsage, 2000);
+  claudeUsageTimer.unref(); intervals.push(claudeUsageTimer);
   const recoveryPeers = (): Record<string, RestartPeerSnapshot> => Object.fromEntries([...bus.peers].map(([id, peer]) => {
     const metadata = peer.recoveryMetadata?.() ?? {};
     const row: RestartPeerSnapshot = { id, state: peer.state, queueIds: bus.queueIds(id), ...(metadata.launch ? { launch: metadata.launch as Record<string, unknown> } : {}) };
@@ -855,7 +881,7 @@ export async function startDaemon(opts: DaemonOptions) {
     ...(dashboard ? { uiOrigin: dashboard.origin } : {}),
     codexProxyPort: opts.codexProxyPort,
     peers: Object.fromEntries(
-      bus.knownPeers().map((id) => { const p = bus.peers.get(id); const summary = bus.queueSummary(id); return [id, { state: bus.stateOf(id), queued: bus.queued(id), ...(p ? {} : { attached: false }), ...(summary.needsReview ? { needsReview: summary.needsReview } : {}), ...queueHoldStatus(id, summary.heldBy), ...(summary.oldestQueuedAt !== undefined ? { oldestQueuedAt: summary.oldestQueuedAt } : {}), ...(bus.queuedImportant(id) ? { queuedImportant: bus.queuedImportant(id) } : {}), ...pausedNote(id), ...(p instanceof LocalPeer && p.lastServedBy ? { servedBy: p.lastServedBy } : {}), ...(p instanceof WsPeer && p.claiming ? { claiming: true } : {}), ...(p instanceof PiPeer ? { requestedModel: p.getRequestedModel(), backends: modelRelay?.status().backends ?? [] } : {}) }]; }),
+      bus.knownPeers().map((id) => { const p = bus.peers.get(id); const summary = bus.queueSummary(id); return [id, { state: bus.stateOf(id), queued: bus.queued(id), ...(p ? {} : { attached: false }), ...(summary.needsReview ? { needsReview: summary.needsReview } : {}), ...(summary.liveAccepted ? { liveAccepted: summary.liveAccepted, settlementNote: "awaiting adapter completion (Claude: correlated reply or hub_delivery_done); task state is independent" } : {}), ...queueHoldStatus(id, summary.heldBy), ...(summary.oldestQueuedAt !== undefined ? { oldestQueuedAt: summary.oldestQueuedAt } : {}), ...(bus.queuedImportant(id) ? { queuedImportant: bus.queuedImportant(id) } : {}), ...pausedNote(id), ...(p instanceof LocalPeer && p.lastServedBy ? { servedBy: p.lastServedBy } : {}), ...(p instanceof WsPeer && p.claiming ? { claiming: true } : {}), ...(p instanceof PiPeer ? { requestedModel: p.getRequestedModel(), backends: modelRelay?.status().backends ?? [] } : {}) }]; }),
     ),
     ...(sidecar ? { switchyard: sidecar.status } : {}),
     ...(modelRelay ? { models: modelRelay.status() } : {}),
@@ -1297,7 +1323,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const mode = args.mode ?? "headless";
       const backend = args.backend ?? config.pi.backend;
       if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend)) return { ok: false, error: "invalid Pi mode/backend" };
-      modelRelay ??= await startModelRelay({ omni, dgxMaxInputTokens: currentRouting(opts.cwd, log).pi.dgx_max_context_tokens, allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast }, mlx: config.mlx, mlxAlias: "mlx/fast", fallbackDGXAlias: "dgx/fast" });
+      modelRelay ??= await startModelRelay({ omni, admitRequest: admitPiRequest, dgxMaxInputTokens: currentRouting(opts.cwd, log).pi.dgx_max_context_tokens, allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast }, mlx: config.mlx, mlxAlias: "mlx/fast", fallbackDGXAlias: "dgx/fast" });
       piReceipts ??= new PiToolReceipts(join(opts.stateDir, "hub.db"));
       let piReply: Envelope | undefined;
       const ctx: ToolContext = {
@@ -1316,14 +1342,24 @@ export async function startDaemon(opts: DaemonOptions) {
         cwd: opts.cwd, stateDir: opts.stateDir, cmd: config.pi.cmd, mode, backend,
         model: args.model,
         sessionId: args.sessionId, sessionFile: args.sessionFile,
+        admitBudget: async (envs, unit) => unit === "model_calls" ? [] : tasks.admitExecutionEnvelopes(envs, "pi", unit),
         relay: { url: modelRelay.url, token: modelRelay.token, models: modelRelay.models.map((id) => ({ id, contextWindow: id.startsWith("mlx/") ? Math.min(routing.pi.mlx_max_context_tokens, config.mlx.provider === "ollama" ? (config.mlx.contextWindow ?? 8192) : routing.pi.mlx_max_context_tokens) : routing.pi.dgx_max_context_tokens, maxTokens: id.startsWith("mlx/") ? (config.mlx.maxTokens ?? 2048) : 8192 })) },
         tools: [...TOOL_SCHEMAS.map((t) => t.function), ...TASK_TOOLS.map((t) => ({ name: t.name, description: t.description, parameters: t.inputSchema }))],
-        executeTool: async (name, raw, callId, sessionId) => {
+        executeTool: async (name, raw, callId, sessionId, signal) => {
+          if (signal?.aborted) return "error: turn cancelled before tool effects";
           if (stopping || (recoveryActive() && recoveryPhase !== "preparing")) return "error: recovery is holding tool effects";
           return piReceipts!.execute(sessionId ?? "", callId, name, raw, async () => {
             if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "error: invalid tool arguments";
             if (TASK_TOOLS.some((t) => t.name === name)) return taskOp("pi", name, raw as Record<string, unknown>, true);
-            return runTool(name, JSON.stringify(raw), ctx);
+            return runTool(name, JSON.stringify(raw), { ...ctx, signal, permit: async title => {
+              if (!signal) return ctx.permit(title);
+              if (signal.aborted) return false;
+              return new Promise<boolean>((resolve, reject) => {
+                const finish = (allowed: boolean) => { signal.removeEventListener("abort", aborted); resolve(allowed && !signal.aborted); };
+                const aborted = () => finish(false); signal.addEventListener("abort", aborted, { once: true });
+                Promise.resolve(ctx.permit(title)).then(finish, error => { signal.removeEventListener("abort", aborted); reject(error); });
+              });
+            } });
           });
         },
         selectModel: async (envs) => {
@@ -1401,6 +1437,8 @@ export async function startDaemon(opts: DaemonOptions) {
       const local = new LocalPeer("local", {
         cwd: opts.cwd,
         omni,
+        onUsage: record => event({ type: "usage", peer: "local", source: "omniroute", id: record.id, ...record.usage, requestedModel: record.requestedModel, ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.provider ? { provider: record.provider } : {}), measuredAt: record.at }),
+        admitBudget: async (envs, unit) => tasks.admitExecutionEnvelopes(envs, "local", unit),
         ...(sidecar && route ? { sidecar, route } : {}),
         fixedModel: args.model ?? routing.local.fixed_model,
         tools: { deny: config.local.deny, bashNetwork: sandboxNetwork, readAllow: config.local.read_allow, permit },
@@ -1425,6 +1463,16 @@ export async function startDaemon(opts: DaemonOptions) {
     return { ok: false, error: `unknown peer "${peer}"` };
   }
 
+  async function admitPiRequest(): Promise<{ allowed: boolean; reason?: string; remainingMs?: number }> {
+    const current = bus.peers.get("pi");
+    if (!(current instanceof PiPeer)) return { allowed: false, reason: "Pi owner is not active" };
+    const decisions = tasks.admitExecutionEnvelopes(current.budgetEnvelopes, "pi", "model_calls");
+    const denied = decisions.find(d => !d.allowed);
+    const stop = denied ? current.recordBudgetStop(denied) : undefined;
+    const deadline = decisions.filter(d => d.unit === "elapsed_ms" && d.remaining !== null).map(d => d.remaining!);
+    return { allowed: !denied, ...(denied ? { reason: stop?.reason ?? `execution budget ${denied.reason}: ${denied.scope}` } : {}), ...(deadline.length ? { remainingMs: Math.min(...deadline) } : {}) };
+  }
+
   async function validateLocalChoice(route: string | undefined, fixedModel: string): Promise<void> {
     const routing = currentRouting(opts.cwd, log);
     if (route && !routing.routes[route]) throw new Error(`routing.toml has no route "${route}"`);
@@ -1729,10 +1777,30 @@ export async function startDaemon(opts: DaemonOptions) {
       }
       case "delivery_receipt": {
         const peer = c.peer ? bus.peers.get(c.peer) : undefined;
-        if (c.role !== "peer" || !(peer instanceof WsPeer) || !peer.owns(sock) || typeof msg.deliveryId !== "string" || !["accepted", "needs_review"].includes(msg.state)) return void reply({ ok: false, error: "invalid delivery receipt" });
+        if (c.role !== "peer" || !(peer instanceof WsPeer) || typeof msg.deliveryId !== "string" || !peer.ownsDelivery(sock, msg.generation, msg.deliveryId) || !["accepted", "needs_review"].includes(msg.state)) return void reply({ ok: false, error: "invalid delivery receipt" });
         bus.deliveryReceipt(peer.id, { id: msg.deliveryId, state: msg.state, ...(msg.state === "needs_review" ? { reason: "Claude bridge could not confirm notification delivery" } : {}) });
         return void reply({ ok: true });
       }
+      case "delivery_complete": {
+        const peer = c.peer ? bus.peers.get(c.peer) : undefined;
+        if (c.role !== "peer" || !(peer instanceof WsPeer) || typeof msg.deliveryId !== "string" || !peer.ownsDelivery(sock, msg.generation, msg.deliveryId)) return void reply({ ok: false, error: "delivery does not belong to this connection generation" });
+        return void reply(bus.completeDelivery(peer.id, msg.deliveryId) ? { ok: true } : { ok: false, error: "delivery is not live and accepted; inspect ahub queue show before resolving" });
+      }
+      case "execution_budget": {
+        if (c.role !== "console") return void reply({ ok: false, error: "execution budgets are console-only" });
+        if (msg.op === "status") return void reply({ ok: true, budgets: tasks.executionBudgetStatus(msg.id) });
+        if (recoveryActive() || stopping) return void reply({ ok: false, error: "recovery or shutdown is holding budget mutations" });
+        try {
+          if (msg.op === "configure") {
+            const cfg = msg.config;
+            if (!cfg || !Array.isArray(cfg.peers) || cfg.peers.some((p: unknown) => p !== "local" && p !== "pi")) throw new Error("strict execution budgets support local and Pi only; native Codex/Claude calls are not instrumented");
+            if (cfg.kind === "task" && !board.get(cfg.taskId)) throw new Error("task not found");
+            return void reply({ ok: true, budget: tasks.configureExecutionBudget(cfg) });
+          }
+          if (msg.op === "disable" && typeof msg.id === "string") return void reply({ ok: true, disabled: tasks.disableExecutionBudget(msg.id) });
+          return void reply({ ok: false, error: "unknown execution budget operation" });
+        } catch (error) { return void reply({ ok: false, error: (error as Error).message }); }
+      }
       case "recovery":
         if (c.role !== "console") return void reply(recoveryError("recovery is a console command"));
         void recoveryOp(msg).then(reply, (error) => reply(recoveryError((error as Error)?.message ?? "recovery operation failed")));
@@ -1899,7 +1967,9 @@ export async function startDaemon(opts: DaemonOptions) {
       await modelRelay?.close();
       await egress?.close();
       await piReceipts?.close();
+      collectClaudeUsage();
       budget.close();
+      executionBudget.close();
       board.close();
       turnLog?.close();
       server.stop(true);

package/src/hub/events.ts

@@ -14,6 +14,7 @@ export type HubEvent =
   | { type: "turn_start"; peer: string; turn: string }
   | { type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number }
   | { type: "tokens"; peer: string; n: number }
+  | { type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
   | { type: "conflict"; peer: string; task?: number; other: number; owner: string; paths: string[]; concurrent: boolean; turns?: [string, string] }
@@ -75,7 +76,8 @@ export function readEvents(file: string, since = 0): StampedEvent[] {
     if (!line.trim()) return [];
     try {
       const e = JSON.parse(line) as StampedEvent;
-      return Date.parse(e.at) >= since ? [e] : [];
+      const measuredAt = e.type === "usage" && typeof e.measuredAt === "string" ? e.measuredAt : e.at;
+      return Date.parse(measuredAt) >= since ? [e] : [];
     } catch {
       return [];
     }

package/src/hub/execution-budget.ts

@@ -0,0 +1,138 @@
+import { Database } from "bun:sqlite";
+
+export type ExecutionUnit = "model_calls" | "tool_calls" | "elapsed_ms" | "tokens";
+export type ExecutionBudgetLimits = Partial<Record<ExecutionUnit, number>>;
+export interface ExecutionBudgetConfig {
+  id: string;
+  kind: "task" | "run";
+  taskId?: number;
+  peers: string[];
+  limits: ExecutionBudgetLimits;
+}
+export interface ExecutionBudgetStatus extends ExecutionBudgetConfig {
+  used: Partial<Record<ExecutionUnit, number>>;
+  units: Partial<Record<ExecutionUnit, { used: number; limit: number; remaining: number; reason?: "exhausted" | "unknown_usage" }>>;
+  createdAt: number;
+  updatedAt: number;
+}
+export interface ExecutionBudgetDecision {
+  allowed: boolean;
+  scope: string;
+  unit: ExecutionUnit;
+  used: number;
+  limit: number | null;
+  remaining: number | null;
+  reason?: "exhausted" | "unknown_usage" | "not_eligible";
+}
+
+const UNITS = new Set<ExecutionUnit>(["model_calls", "tool_calls", "elapsed_ms", "tokens"]);
+const validLimits = (raw: ExecutionBudgetLimits): ExecutionBudgetLimits => {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("execution budget limits must be an object");
+  const out: ExecutionBudgetLimits = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!UNITS.has(key as ExecutionUnit)) throw new Error(`unsupported execution budget unit: ${key}`);
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error(`execution budget ${key} limit must be a nonnegative integer`);
+    out[key as ExecutionUnit] = value;
+  }
+  return out;
+};
+
+/** Persistent, cross-turn execution meter. Each admission and increment is one SQLite transaction. */
+export class ExecutionBudget {
+  private readonly db: Database;
+  constructor(path: string) {
+    this.db = new Database(path, { create: true });
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run(`CREATE TABLE IF NOT EXISTS execution_budgets (
+      id TEXT PRIMARY KEY, kind TEXT NOT NULL, task_id INTEGER, peers TEXT NOT NULL,
+      limits TEXT NOT NULL, used TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)`);
+  }
+
+  configure(input: ExecutionBudgetConfig): ExecutionBudgetStatus {
+    if (!input.id || input.id.length > 200) throw new Error("execution budget id is invalid");
+    if (input.kind !== "task" && input.kind !== "run") throw new Error("execution budget kind must be task or run");
+    if (input.kind === "task" && (!Number.isSafeInteger(input.taskId) || input.taskId! < 1)) throw new Error("task budget requires a positive task id");
+    const peers = [...new Set(input.peers.filter((p) => typeof p === "string" && p.length > 0))].sort();
+    if (!peers.length) throw new Error("execution budget requires at least one peer");
+    const unsupported = peers.filter((peer) => peer !== "pi" && peer !== "local");
+    if (unsupported.length) throw new Error(`execution budgets require instrumented peers (pi, local); unsupported: ${unsupported.join(", ")}`);
+    const limits = validLimits(input.limits ?? {});
+    if (!Object.keys(limits).length) throw new Error("execution budget requires at least one supported limit");
+    const now = Date.now();
+    const existing = this.db.query("SELECT kind,task_id FROM execution_budgets WHERE id=?").get(input.id) as { kind: string; task_id: number | null } | undefined;
+    if (existing && (existing.kind !== input.kind || existing.task_id !== (input.taskId ?? null))) throw new Error("execution budget id is already bound to another scope");
+    this.db.query(`INSERT INTO execution_budgets (id,kind,task_id,peers,limits,used,created_at,updated_at)
+      VALUES (?,?,?,?,?,'{}',?,?) ON CONFLICT(id) DO UPDATE SET kind=excluded.kind,task_id=excluded.task_id,
+      peers=excluded.peers,limits=excluded.limits,updated_at=excluded.updated_at`).run(
+      input.id, input.kind, input.taskId ?? null, JSON.stringify(peers), JSON.stringify(limits), now, now,
+    );
+    return this.status(input.id) as ExecutionBudgetStatus;
+  }
+
+  disable(id: string): boolean { return this.db.query("DELETE FROM execution_budgets WHERE id=?").run(id).changes > 0; }
+
+  status(id?: string): ExecutionBudgetStatus | ExecutionBudgetStatus[] | undefined {
+    const rows = (id
+      ? this.db.query("SELECT * FROM execution_budgets WHERE id=?").all(id)
+      : this.db.query("SELECT * FROM execution_budgets ORDER BY created_at,id").all()) as BudgetRow[];
+    const values = rows.map(fromRow);
+    return id ? values[0] : values;
+  }
+
+  admitTask(taskId: number | undefined, peer: string, unit: ExecutionUnit, amount = 1): ExecutionBudgetDecision[] {
+    return this.admitTasks(taskId === undefined ? [] : [taskId], peer, unit, amount);
+  }
+
+  admitTasks(taskIds: number[], peer: string, unit: ExecutionUnit, amount = 1): ExecutionBudgetDecision[] {
+    if (!UNITS.has(unit) || !Number.isSafeInteger(amount) || amount <= 0) throw new Error("execution budget admission is invalid");
+    const transaction = this.db.transaction(() => {
+      // Read scopes only after BEGIN IMMEDIATE so a concurrent configure/admission cannot evade a scope or overdraw it.
+      const ids = [...new Set(taskIds.filter((id) => Number.isSafeInteger(id) && id > 0))];
+      const taskRows = ids.length
+        ? this.db.query(`SELECT * FROM execution_budgets WHERE kind='task' AND task_id IN (${ids.map(() => "?").join(",")}) AND EXISTS (SELECT 1 FROM json_each(peers) WHERE value=?)`).all(...ids, peer) as BudgetRow[]
+        : [];
+      const runRows = this.db.query("SELECT * FROM execution_budgets WHERE kind='run' AND EXISTS (SELECT 1 FROM json_each(peers) WHERE value=?)").all(peer) as BudgetRow[];
+      const rows = [...taskRows, ...runRows].sort((a, b) => a.created_at - b.created_at || a.id.localeCompare(b.id));
+      const pending: { cfg: ExecutionBudgetStatus; updates: Partial<Record<ExecutionUnit, number>>; decisions: ExecutionBudgetDecision[] }[] = rows.map((row) => {
+        const cfg = fromRow(row), updates: Partial<Record<ExecutionUnit, number>> = {}, decisions: ExecutionBudgetDecision[] = [];
+        const now = Date.now(), elapsedLimit = cfg.limits.elapsed_ms;
+        if (elapsedLimit !== undefined) {
+          const elapsed = Math.max(cfg.used.elapsed_ms ?? 0, now - cfg.createdAt);
+          const decision: ExecutionBudgetDecision = { allowed: elapsed < elapsedLimit, scope: cfg.id, unit: "elapsed_ms", used: elapsed, limit: elapsedLimit, remaining: Math.max(0, elapsedLimit - elapsed), ...(elapsed >= elapsedLimit ? { reason: "exhausted" } : {}) };
+          decisions.push(decision); updates.elapsed_ms = elapsed;
+        }
+        const limit = cfg.limits[unit], current = cfg.used[unit] ?? 0;
+        if (unit === "tokens" || (unit === "model_calls" && cfg.limits.tokens !== undefined)) {
+          decisions.push({ allowed: false, scope: cfg.id, unit: "tokens", used: cfg.used.tokens ?? 0, limit: cfg.limits.tokens ?? null, remaining: cfg.limits.tokens === undefined ? null : Math.max(0, cfg.limits.tokens - (cfg.used.tokens ?? 0)), reason: "unknown_usage" });
+        } else if (limit === undefined) decisions.push({ allowed: true, scope: cfg.id, unit, used: current, limit: null, remaining: null });
+        else if (current + amount > limit) decisions.push({ allowed: false, scope: cfg.id, unit, used: current, limit, remaining: Math.max(0, limit - current), reason: "exhausted" });
+        else {
+          updates[unit] = current + amount;
+          decisions.push({ allowed: true, scope: cfg.id, unit, used: current + amount, limit, remaining: Math.max(0, limit - current - amount) });
+        }
+        return { cfg, updates, decisions };
+      });
+      if (pending.some((item) => item.decisions.some((decision) => !decision.allowed))) return pending.flatMap((item) => item.decisions);
+      for (const item of pending) if (Object.keys(item.updates).length) {
+        item.cfg.used = { ...item.cfg.used, ...item.updates };
+        this.db.query("UPDATE execution_budgets SET used=?,updated_at=? WHERE id=?").run(JSON.stringify(item.cfg.used), Date.now(), item.cfg.id);
+      }
+      return pending.flatMap((item) => item.decisions);
+    });
+    return transaction.immediate();
+  }
+  close(): void { this.db.close(); }
+}
+
+interface BudgetRow { id: string; kind: "task"|"run"; task_id: number | null; peers: string; limits: string; used: string; created_at: number; updated_at: number }
+function fromRow(row: BudgetRow): ExecutionBudgetStatus {
+  const limits = JSON.parse(row.limits) as ExecutionBudgetLimits;
+  const used = JSON.parse(row.used) as Partial<Record<ExecutionUnit, number>>;
+  if (limits.elapsed_ms !== undefined) used.elapsed_ms = Math.max(used.elapsed_ms ?? 0, Date.now() - row.created_at);
+  const units: ExecutionBudgetStatus["units"] = {};
+  for (const [unit, limit] of Object.entries(limits) as [ExecutionUnit, number][]) {
+    const current = used[unit] ?? 0, remaining = Math.max(0, limit - current);
+    units[unit] = { used: current, limit, remaining, ...((unit === "tokens" && remaining > 0) ? { reason: "unknown_usage" as const } : (remaining === 0 ? { reason: "exhausted" as const } : {})) };
+  }
+  return { id: row.id, kind: row.kind, ...(row.task_id === null ? {} : { taskId: row.task_id }), peers: JSON.parse(row.peers), limits, used, units, createdAt: row.created_at, updatedAt: row.updated_at };
+}

package/src/hub/report.ts

@@ -4,6 +4,7 @@ export interface Report {
   from?: string;
   to?: string;
   peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
+  usage: { peers: Record<string, UsageCoverage>; totals: UsageTotals; unknownPeers: string[]; completeCoverage: boolean; estimatedUsd?: number; measuredSpendUsd?: number };
   messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
   overlaps: { warnings: number; pairs: number };
   /** Files one agent changed after another owner's open task had changed them (issue #32). */
@@ -12,12 +13,82 @@ export interface Report {
   quota: { readings: number; hard: number };
 }
 
+export interface UsageCoverage {
+  records: number;
+  withUsage: number;
+  withoutUsage: number;
+  inputTokens: number;
+  inputRecords: number;
+  outputTokens: number;
+  outputRecords: number;
+  cacheReadTokens: number;
+  cacheReadRecords: number;
+  cacheWriteTokens: number;
+  cacheWriteRecords: number;
+  totalTokens: number;
+  totalRecords: number;
+}
+
+export type UsageTotals = Omit<UsageCoverage, "records" | "withUsage" | "withoutUsage">;
+
+const emptyUsage = (): UsageCoverage => ({ records: 0, withUsage: 0, withoutUsage: 0, inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 });
+
+function recordUsage(coverage: UsageCoverage, e: Extract<StampedEvent, { type: "usage" }>): void {
+  coverage.records++;
+  const fields = [e.inputTokens, e.outputTokens, e.cacheReadTokens, e.cacheWriteTokens, e.totalTokens];
+  if (fields.some((n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0)) coverage.withUsage++;
+  else coverage.withoutUsage++;
+  const add = (field: keyof UsageTotals, n: number | undefined, countField: keyof UsageTotals) => {
+    if (typeof n === "number" && Number.isSafeInteger(n) && n >= 0) {
+      coverage[field] += n;
+      coverage[countField]++;
+    }
+  };
+  add("inputTokens", e.inputTokens, "inputRecords");
+  add("outputTokens", e.outputTokens, "outputRecords");
+  add("cacheReadTokens", e.cacheReadTokens, "cacheReadRecords");
+  add("cacheWriteTokens", e.cacheWriteTokens, "cacheWriteRecords");
+  add("totalTokens", e.totalTokens, "totalRecords");
+}
+
+function finalizeUsage(report: Report): void {
+  for (const id of Object.keys(report.peers)) {
+    if (!report.usage.peers[id]) {
+      report.usage.peers[id] = emptyUsage();
+      report.usage.unknownPeers.push(id);
+    }
+  }
+  for (const p of Object.values(report.usage.peers)) {
+    const out = report.usage.totals;
+    for (const field of ["inputTokens", "inputRecords", "outputTokens", "outputRecords", "cacheReadTokens", "cacheReadRecords", "cacheWriteTokens", "cacheWriteRecords", "totalTokens", "totalRecords"] as const) out[field] += p[field];
+    if (p.withoutUsage || p.inputRecords < p.withUsage || p.outputRecords < p.withUsage || p.cacheReadRecords < p.withUsage || p.cacheWriteRecords < p.withUsage || p.totalRecords < p.withUsage) report.usage.completeCoverage = false;
+  }
+  if (report.usage.unknownPeers.length) report.usage.completeCoverage = false;
+}
+
+function formatUsage(usage: Report["usage"]): string[] {
+  const lines: string[] = [];
+  for (const [id, u] of Object.entries(usage.peers).sort(([a], [b]) => a.localeCompare(b))) {
+    const coverage = `${u.withUsage}/${u.records} records with usage`;
+    const value = (name: string, count: number, records: number) => records ? `${name} ${count} (${records} known)` : `${name} unknown (0 known)`;
+    const known = [value("input", u.inputTokens, u.inputRecords), value("output", u.outputTokens, u.outputRecords), value("cache read", u.cacheReadTokens, u.cacheReadRecords), value("cache write", u.cacheWriteTokens, u.cacheWriteRecords), value("reported total", u.totalTokens, u.totalRecords)].join(", ");
+    const incomplete = u.withoutUsage || u.inputRecords < u.withUsage || u.outputRecords < u.withUsage || u.cacheReadRecords < u.withUsage || u.cacheWriteRecords < u.withUsage || u.totalRecords < u.withUsage;
+    lines.push(`usage ${id}: ${u.records ? coverage : "no usage records"}; ${known}; coverage ${incomplete ? "incomplete" : u.records ? "complete for recorded calls" : "unknown"}`);
+  }
+  const total = usage.totals.totalRecords ? `${usage.totals.totalTokens} reported tokens (${usage.totals.totalRecords} known records)` : "reported token total unknown (0 known records)";
+  const coverage = usage.completeCoverage ? "recorded-call coverage complete" : `incomplete or unknown peer coverage${usage.unknownPeers.length ? ` (${usage.unknownPeers.join(", ")})` : ""}`;
+  lines.push(`usage team totals: ${total}; ${coverage}; estimated price unknown; measured spend unknown`);
+  return lines;
+}
+
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
+  const usagePeer = (id: string) => (r.usage.peers[id] ??= emptyUsage());
   const pairs = new Set<string>();
   const taskMessages = new Map<string, number>();
+  const seenUsage = new Set<string>();
   for (const e of events) {
     r.from ??= e.at;
     r.to = e.at;
@@ -35,9 +106,19 @@ export function summarize(events: StampedEvent[]): Report {
         peer(e.peer).turns++;
         peer(e.peer).busyMinutes += e.ms / 60_000;
         break;
+      case "state":
+        peer(e.peer);
+        break;
       case "tokens":
         peer(e.peer).tokens += e.n;
         break;
+      case "usage": {
+        const key = `${e.peer}\0${e.source}\0${e.id}`;
+        if (seenUsage.has(key)) break;
+        seenUsage.add(key);
+        recordUsage(usagePeer(e.peer), e);
+        break;
+      }
       case "task":
         r.tasks[e.event] = (r.tasks[e.event] ?? 0) + 1;
         break;
@@ -55,6 +136,8 @@ export function summarize(events: StampedEvent[]): Report {
     }
   }
   r.overlaps.pairs = pairs.size;
+  finalizeUsage(r);
+  // Pricing is intentionally absent: a token count is neither an estimated price nor provider-reported spend.
   r.messages.perTask = taskMessages.size ? Number(([...taskMessages.values()].reduce((a, b) => a + b, 0) / taskMessages.size).toFixed(1)) : 0;
   for (const p of Object.values(r.peers)) p.busyMinutes = Number(p.busyMinutes.toFixed(1));
   return r;
@@ -63,6 +146,7 @@ export function summarize(events: StampedEvent[]): Report {
 export function formatReport(r: Report): string[] {
   const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
   for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) lines.push(`peer ${id}: ${p.turns} turn${p.turns === 1 ? "" : "s"}, ${p.busyMinutes} busy minutes, ${p.tokens ? `${p.tokens} tokens` : id === "pi" ? "tokens not reported" : "- tokens"}`);
+  if (Object.keys(r.usage.peers).length) lines.push(...formatUsage(r.usage));
   const dropped = Object.entries(r.messages.dropped).map(([k, n]) => `${n} ${k}`).join(", ");
   lines.push(`messages: ${r.messages.total} (dropped: ${dropped || "none"}; overflow ${r.messages.overflow}; undeliverable ${r.messages.undeliverable}); ${r.messages.perTask} per task that had any`);
   lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}; edit conflicts: ${r.conflicts}`);

package/src/hub/tasks.ts

@@ -4,6 +4,7 @@ import { CLASSES, OUTCOMES_KEPT_MS, PLAN_KEYS, type Board, type Task, type TaskC
 import type { Bus } from "./bus.ts";
 import { HUB, newEnvelope, NOTE_KINDS, noteLine, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
 import { assign, detectSignals, LOCAL, PI, type Assignment, type Routing } from "./routing.ts";
+import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecision, type ExecutionBudgetStatus, type ExecutionUnit } from "./execution-budget.ts";
 
 export interface TasksDeps {
   board: Board;
@@ -27,6 +28,8 @@ export interface TasksDeps {
   recordOverlap?: (task: number, owner: PeerId, others: { task: number; owner: PeerId; paths: string[]; symbols?: string[] }[]) => void;
   /** Quota per peer from fresh readings (issue #36): routing drains the windows that reset soonest first. */
   quota?: () => Record<PeerId, { headroom: number; resetsAt?: number }>;
+  /** Optional persisted task/run execution limits (issue #102). */
+  executionBudget?: ExecutionBudget;
   /** Reviewer choice from recorded review outcomes (issue #35); off unless the project config turns it on. */
   review?: { adaptive: boolean; min_reviews: number };
   /** Peers whose recent deliveries all failed, with the reason (issue #89); routing skips them. */
@@ -108,6 +111,25 @@ export class Tasks {
 
   isPii = (task: Pick<Task, "signals">) => task.signals.includes("pii") && this.d.routing().constraints.pii === "local_only";
 
+  configureExecutionBudget = (config: ExecutionBudgetConfig): ExecutionBudgetStatus | undefined => {
+    if (!this.d.executionBudget) return undefined;
+    if (config.kind === "task" && (!config.taskId || !this.d.board.get(config.taskId))) throw new Error(`task #${config.taskId ?? "?"} does not exist`);
+    return this.d.executionBudget.configure(config);
+  };
+  disableExecutionBudget = (id: string): boolean => this.d.executionBudget?.disable(id) ?? false;
+  executionBudgetStatus = (id?: string): ExecutionBudgetStatus | ExecutionBudgetStatus[] | undefined => this.d.executionBudget?.status(id);
+  /** Charge only budgets matching the task actually delivered to this peer, plus active run budgets. */
+  admitExecution = (taskId: number | undefined, peer: PeerId, unit: ExecutionUnit, amount = 1): ExecutionBudgetDecision[] => this.d.executionBudget?.admitTask(taskId, peer, unit, amount) ?? [];
+  /** A digest may include several tasks. Charge each matching task budget and each run budget once, atomically. */
+  admitExecutionEnvelopes = (envs: Envelope[], peer: PeerId, unit: ExecutionUnit, amount = 1): ExecutionBudgetDecision[] => {
+    const ids = [...new Set(envs.flatMap((e) => {
+      const value = e.refs?.task;
+      const id = typeof value === "string" ? Number(value) : NaN;
+      return Number.isSafeInteger(id) && id > 0 ? [id] : [];
+    }))];
+    return this.d.executionBudget?.admitTasks(ids, peer, unit, amount) ?? [];
+  };
+
   /** What peers other than the owner, the console stream and the log may see of a task. */
   publicTitle = (task: Task) => (this.isPii(task) ? `#${task.id} [pii]` : `#${task.id} ${task.title}`);
 

package/src/hub/usage.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { normalizeUsage, safeModelLabel, type NormalizedUsage } from "../omniroute/usage.ts";
+
+export interface UsageRecord {
+  id: string;
+  at?: string;
+  usage?: NormalizedUsage;
+  requestedModel?: string;
+  servedModel?: string;
+  provider?: string;
+}
+
+function opaqueId(sessionId: string, messageId: string): string {
+  return createHash("sha256").update(sessionId).update("\0").update(messageId).digest("hex");
+}
+
+// Documented successful Messages API values, including beta compaction, plus stop_sequence in native transcripts.
+const COMPLETED_STOP_REASONS = new Set(["end_turn", "tool_use", "max_tokens", "stop_sequence", "pause_turn", "refusal", "model_context_window_exceeded", "compaction"]);
+
+/**
+ * Read Claude's native JSONL usage without returning transcript text, paths or session identity.
+ * Repeated streaming records are collapsed by message.id, using only a completed assistant message.
+ * Malformed lines and unavailable files are ignored so telemetry cannot interrupt a Claude turn.
+ */
+export function readClaudeTranscriptUsage(sessionId: string, transcriptPath: string): UsageRecord[] {
+  try {
+    // Avoid repeatedly parsing an unbounded transcript on the daemon's polling path.
+    if (statSync(transcriptPath).size > 32 * 1024 * 1024) {
+      // Signal unavailable coverage with a stable opaque id; a repeated poll dedupes in the report.
+      return [{ id: opaqueId(sessionId, "transcript-too-large") }];
+    }
+    const latest = new Map<string, { usage?: NormalizedUsage; at?: string; servedModel?: string }>();
+    for (const line of readFileSync(transcriptPath, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line) as { type?: unknown; timestamp?: unknown; sessionId?: unknown; message?: unknown };
+        if (typeof row.sessionId === "string" && row.sessionId !== sessionId) continue;
+        if (row.type !== "assistant" || !row.message || typeof row.message !== "object") continue;
+        const message = row.message as { id?: unknown; stop_reason?: unknown; usage?: unknown; model?: unknown };
+        if (typeof message.id !== "string" || !message.id || typeof message.stop_reason !== "string" || !message.stop_reason) continue;
+        const supportedStopReason = COMPLETED_STOP_REASONS.has(message.stop_reason);
+        const usage = supportedStopReason ? normalizeUsage(message.usage) : undefined;
+        const at = typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? new Date(row.timestamp).toISOString() : undefined;
+        const servedModel = safeModelLabel(message.model);
+        latest.set(message.id, { ...(usage ? { usage } : {}), ...(at ? { at } : {}), ...(servedModel ? { servedModel } : {}) });
+      } catch {
+        // A streaming or crash-truncated line is not a record.
+      }
+    }
+    return [...latest].map(([messageId, value]) => ({ id: opaqueId(sessionId, messageId), ...value }));
+  } catch {
+    return [];
+  }
+}

package/src/local/sandbox.ts

@@ -118,8 +118,9 @@ export interface ExecResult {
 }
 
 /** Run argv under seatbelt with a scrubbed environment. Never runs unsandboxed: no sandbox, no exec. */
-export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string> }): Promise<ExecResult> {
+export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string>; signal?: AbortSignal }): Promise<ExecResult> {
   if (!sandboxAvailable()) return Promise.resolve({ code: null, output: "error: command execution needs macOS sandbox-exec and is disabled on this host" });
+  if (opts.signal?.aborted) return Promise.resolve({ code: null, output: "error: command cancelled before execution" });
   return new Promise((resolve) => {
     // A temp dir of its own (#63): the user's is shared with every other process, and what a command reads can reach
     // an answer shown to cloud peers. Allowed after the profile's denies, and gone when the command ends.
@@ -141,6 +142,8 @@ export function sandboxedExec(argv: string[], opts: { cwd: string; profile: stri
         child.kill("SIGKILL");
       }
     };
+    const abort = () => killGroup();
+    opts.signal?.addEventListener("abort", abort, { once: true });
     // Best effort, never in the way of the result: a command can mark its files immutable (`chflags uchg`), and then
     // the plain remove throws. What still fails is left to the OS temp cleanup.
     const dropOwn = () => {
@@ -154,11 +157,12 @@ export function sandboxedExec(argv: string[], opts: { cwd: string; profile: stri
       if (done) return;
       done = true;
       clearTimeout(timer);
+      opts.signal?.removeEventListener("abort", abort);
       dropOwn();
       const clipped = output.length >= OUTPUT_CAP ? `${output.slice(0, OUTPUT_CAP)}\n(output truncated)` : output;
       resolve({ code, output: signal ? `${clipped}\n(killed: ${signal}, timeout?)` : clipped });
     };
-    child.on("error", (e) => (done || ((done = true), dropOwn(), resolve({ code: null, output: `error: ${e.message}` }))));
+    child.on("error", (e) => (done || ((done = true), clearTimeout(timer), opts.signal?.removeEventListener("abort", abort), dropOwn(), resolve({ code: null, output: `error: ${e.message}` }))));
     child.on("close", finish);
     // `close` waits for every holder of the pipes; after `exit` give stragglers a moment, then stop waiting and reap them.
     child.on("exit", (code, signal) => setTimeout(() => (killGroup(), finish(code, signal)), 500).unref());