@raysonmeng/agentbridge 0.1.21 → 0.1.23

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
     {
       "name": "agentbridge",
       "description": "Bridge Claude Code and Codex through a shared daemon, push channel delivery, and reply/get_messages tools.",
-      "version": "0.1.21",
+      "version": "0.1.23",
       "author": {
         "name": "AgentBridge Contributors",
         "email": "raysonmeng@qq.com"

package/README.md

@@ -217,10 +217,11 @@ agent_bridge/
 │   ├── pull_request_template.md
 │   └── workflows/ci.yml          # GitHub Actions CI
 ├── assets/                        # Static assets (images, etc.)
-├── docs/
-│   ├── phase3-spec.md            # Phase 3 design spec (CLI + Plugin)
-│   ├── v1-roadmap.md             # v1 feature roadmap
-│   └── v2-architecture.md        # v2 multi-agent architecture design
+├── docs/                          # Numbered docs; index in docs/README.md
+│   ├── 01-协作系统规格-v3.md       # Collaboration system spec v3 (main)
+│   ├── 02-v2架构设计.md            # v2 multi-agent architecture (foundation)
+│   ├── 03-08 …                     # multi-pair / budget / protocol / release
+│   └── archive/历史归档.md         # Archived design / post-mortems / test plans
 ├── plugins/agentbridge/           # Claude Code plugin bundle
 │   ├── .claude-plugin/plugin.json
 │   ├── commands/init.md
@@ -346,8 +347,8 @@ Codex runs in a sandboxed environment that **blocks all writes to the `.git` dir
 
 ## Roadmap
 
-- **v1.x (current)**: Improve the single-bridge experience without architectural refactoring -- less noise, better turn discipline, and clearer collaboration modes. See [docs/v1-roadmap.md](docs/v1-roadmap.md).
-- **v2 (planned)**: Introduce the multi-agent foundation -- room-scoped collaboration, stable identity, a formal control protocol, and stronger recovery semantics. See [docs/v2-architecture.md](docs/v2-architecture.md).
+- **v1.x (current)**: Improve the single-bridge experience without architectural refactoring -- less noise, better turn discipline, and clearer collaboration modes. See [docs/archive/历史归档.md](docs/archive/历史归档.md).
+- **v2 (planned)**: Introduce the multi-agent foundation -- room-scoped collaboration, stable identity, a formal control protocol, and stronger recovery semantics. See [docs/02-v2架构设计.md](docs/02-v2架构设计.md).
 - **v3+ (longer term)**: Explore smarter collaboration, richer policies, and more advanced orchestration across runtimes.
 
 ## How This Project Was Built

package/README.zh-CN.md

@@ -215,10 +215,11 @@ agent_bridge/
 │   ├── pull_request_template.md
 │   └── workflows/ci.yml          # GitHub Actions CI
 ├── assets/                        # 图片资源
-├── docs/
-│   ├── phase3-spec.md            # Phase 3 设计文档（CLI + Plugin）
-│   ├── v1-roadmap.md             # v1 功能路线图
-│   └── v2-architecture.md        # v2 多 Agent 架构设计
+├── docs/                          # 文档（带序号，索引见 docs/README.md）
+│   ├── 01-协作系统规格-v3.md       # 协作系统实现规格 v3（主规格）
+│   ├── 02-v2架构设计.md            # v2 多 Agent 架构（基座，中英双语）
+│   ├── 03-08 …                     # 单机多对 / 额度 / 协作协议 / 发布
+│   └── archive/历史归档.md         # 已归档的历史设计 / 复盘 / 测试计划
 ├── plugins/agentbridge/           # Claude Code 插件包
 │   ├── .claude-plugin/plugin.json
 │   ├── commands/init.md
@@ -340,8 +341,8 @@ Codex 运行在沙箱环境中，**禁止对 `.git` 目录进行任何写操作*
 
 ## Roadmap
 
-- **v1.x（当前）**：在不改变架构的前提下优化单桥体验 -- 降噪、控回合、定角色。详见 [docs/v1-roadmap.md](docs/v1-roadmap.md)。
-- **v2（规划中）**：引入多 Agent 基础设施 -- Room 作用域协作、稳定身份、正式控制协议、更强的恢复语义。详见 [docs/v2-architecture.md](docs/v2-architecture.md)。
+- **v1.x（当前）**：在不改变架构的前提下优化单桥体验 -- 降噪、控回合、定角色。详见 [docs/archive/历史归档.md](docs/archive/历史归档.md)。
+- **v2（规划中）**：引入多 Agent 基础设施 -- Room 作用域协作、稳定身份、正式控制协议、更强的恢复语义。详见 [docs/02-v2架构设计.md](docs/02-v2架构设计.md)。
 - **v3+（远期）**：更智能的协作、更丰富的策略、跨 runtime 的高级编排。
 
 ## 这个项目是怎么建成的

package/dist/cli.js

@@ -179,7 +179,7 @@ function parsePositiveIntEnv(name, fallback, log = () => {}, env = process.env)
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@raysonmeng/agentbridge",
-    version: "0.1.21",
+    version: "0.1.23",
     description: "Bridge between Claude Code and Codex \u2014 bidirectional agent communication via MCP Channel + JSON-RPC",
     type: "module",
     packageManager: "bun@1.3.11",
@@ -487,7 +487,7 @@ function findShapeViolation(raw) {
     if (!isRecord(budget)) {
       return "budget is present but not an object";
     }
-    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct"];
+    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct", "budgetFreshTtlSec", "idleAdviceActivityWindowSec"];
     for (const key of numericKeys) {
       if (key in budget && !isCoercibleNumber(budget[key])) {
         return `budget.${key} is present but not a number`;
@@ -541,7 +541,7 @@ function hasCustomDecisionValues(config) {
   const d = DEFAULT_CONFIG;
   const b = config.budget;
   const db = d.budget;
-  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
+  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.budgetFreshTtlSec !== db.budgetFreshTtlSec || b.idleAdviceActivityWindowSec !== db.idleAdviceActivityWindowSec || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
 }
 function normalizeInteger(value, fallback) {
   if (typeof value === "number" && Number.isFinite(value))
@@ -637,6 +637,8 @@ function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
   return {
     enabled: normalizeBoolean(budget.enabled, fallback.enabled),
     pollSeconds: normalizeBoundedInteger(budget.pollSeconds, fallback.pollSeconds, 5, 3600),
+    budgetFreshTtlSec: normalizeBoundedInteger(budget.budgetFreshTtlSec, fallback.budgetFreshTtlSec, 1, 300),
+    idleAdviceActivityWindowSec: normalizeBoundedInteger(budget.idleAdviceActivityWindowSec, fallback.idleAdviceActivityWindowSec, 0, 86400),
     pauseAt,
     resumeBelow,
     syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, fallback.syncDriftPct, 1, 100),
@@ -654,6 +656,8 @@ function applyBudgetEnvOverrides(budget, env = process.env) {
   const overlay = {
     enabled: env.AGENTBRIDGE_BUDGET_ENABLED ?? budget.enabled,
     pollSeconds: env.AGENTBRIDGE_BUDGET_POLL_SECONDS ?? budget.pollSeconds,
+    budgetFreshTtlSec: env.AGENTBRIDGE_BUDGET_FRESH_TTL_SEC ?? budget.budgetFreshTtlSec,
+    idleAdviceActivityWindowSec: env.AGENTBRIDGE_BUDGET_IDLE_ADVICE_ACTIVITY_WINDOW_SEC ?? budget.idleAdviceActivityWindowSec,
     pauseAt: env.AGENTBRIDGE_BUDGET_PAUSE_AT ?? budget.pauseAt,
     resumeBelow: env.AGENTBRIDGE_BUDGET_RESUME_BELOW ?? budget.resumeBelow,
     syncDriftPct: env.AGENTBRIDGE_BUDGET_SYNC_DRIFT_PCT ?? budget.syncDriftPct,
@@ -793,6 +797,8 @@ var init_config_service = __esm(() => {
   DEFAULT_BUDGET_CONFIG = {
     enabled: true,
     pollSeconds: 300,
+    budgetFreshTtlSec: 25,
+    idleAdviceActivityWindowSec: 600,
     pauseAt: 90,
     resumeBelow: 30,
     syncDriftPct: 10,
@@ -1501,9 +1507,26 @@ var init_daemon_client = __esm(() => {
         send: () => this.send({ type: "probe_incumbent" })
       });
     }
+    async requestBudgetRefresh(timeoutMs = 3000) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return null;
+      }
+      const requestId = `budget_${Date.now()}_${this.nextRequestId++}`;
+      return this.awaitTypedResponse({
+        key: "budget_refresh",
+        successEvent: "budgetRefresh",
+        match: (payload) => payload.requestId === requestId,
+        successValue: (payload) => payload.snapshot,
+        failValue: null,
+        timeoutMs,
+        send: () => this.send({ type: "request_budget_refresh", requestId })
+      });
+    }
     awaitTypedResponse(opts) {
-      const { key, successEvent, successValue, failValue, timeoutMs, send } = opts;
+      const { key, successEvent, successValue, failValue, timeoutMs, send, match } = opts;
       const onSuccess = (payload) => {
+        if (match && !match(payload))
+          return;
         this.pendingEventWaiters.settle(key, successValue(payload));
       };
       const onRejected = () => {
@@ -1604,6 +1627,9 @@ var init_daemon_client = __esm(() => {
           case "incumbent_status":
             this.emit("incumbentStatus", { connected: message.connected, alive: message.alive });
             return;
+          case "budget_refresh":
+            this.emit("budgetRefresh", { requestId: message.requestId, snapshot: message.snapshot });
+            return;
         }
       };
       ws.onclose = (event) => {
@@ -1682,11 +1708,11 @@ function formatBuildInfo(build) {
 var CODE_HASH_SENTINEL = "source", BUILD_INFO;
 var init_build_info = __esm(() => {
   BUILD_INFO = Object.freeze({
-    version: defineString("0.1.21", "0.0.0-source"),
-    commit: defineString("ddee9b2", "source"),
+    version: defineString("0.1.23", "0.0.0-source"),
+    commit: defineString("487e717", "source"),
     bundle: defineBundle("dist"),
     contractVersion: defineNumber(1, CONTRACT_VERSION),
-    codeHash: defineString("8354efa9fcad", "source")
+    codeHash: defineString("e5377c294644", "source")
   });
 });
 

package/dist/daemon.js

@@ -29,11 +29,11 @@ function defineNumber(value, fallback) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 var BUILD_INFO = Object.freeze({
-  version: defineString("0.1.21", "0.0.0-source"),
-  commit: defineString("ddee9b2", "source"),
+  version: defineString("0.1.23", "0.0.0-source"),
+  commit: defineString("487e717", "source"),
   bundle: defineBundle("dist"),
   contractVersion: defineNumber(1, CONTRACT_VERSION),
-  codeHash: defineString("8354efa9fcad", "source")
+  codeHash: defineString("e5377c294644", "source")
 });
 function daemonStatusBuildInfo() {
   return { ...BUILD_INFO };
@@ -3478,6 +3478,8 @@ import { join as join4 } from "path";
 var DEFAULT_BUDGET_CONFIG = {
   enabled: true,
   pollSeconds: 300,
+  budgetFreshTtlSec: 25,
+  idleAdviceActivityWindowSec: 600,
   pauseAt: 90,
   resumeBelow: 30,
   syncDriftPct: 10,
@@ -3539,7 +3541,7 @@ function findShapeViolation(raw) {
     if (!isRecord(budget)) {
       return "budget is present but not an object";
     }
-    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct"];
+    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct", "budgetFreshTtlSec", "idleAdviceActivityWindowSec"];
     for (const key of numericKeys) {
       if (key in budget && !isCoercibleNumber(budget[key])) {
         return `budget.${key} is present but not a number`;
@@ -3593,7 +3595,7 @@ function hasCustomDecisionValues(config) {
   const d = DEFAULT_CONFIG;
   const b = config.budget;
   const db = d.budget;
-  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
+  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.budgetFreshTtlSec !== db.budgetFreshTtlSec || b.idleAdviceActivityWindowSec !== db.idleAdviceActivityWindowSec || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
 }
 function normalizeInteger(value, fallback) {
   if (typeof value === "number" && Number.isFinite(value))
@@ -3689,6 +3691,8 @@ function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
   return {
     enabled: normalizeBoolean(budget.enabled, fallback.enabled),
     pollSeconds: normalizeBoundedInteger(budget.pollSeconds, fallback.pollSeconds, 5, 3600),
+    budgetFreshTtlSec: normalizeBoundedInteger(budget.budgetFreshTtlSec, fallback.budgetFreshTtlSec, 1, 300),
+    idleAdviceActivityWindowSec: normalizeBoundedInteger(budget.idleAdviceActivityWindowSec, fallback.idleAdviceActivityWindowSec, 0, 86400),
     pauseAt,
     resumeBelow,
     syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, fallback.syncDriftPct, 1, 100),
@@ -3706,6 +3710,8 @@ function applyBudgetEnvOverrides(budget, env = process.env) {
   const overlay = {
     enabled: env.AGENTBRIDGE_BUDGET_ENABLED ?? budget.enabled,
     pollSeconds: env.AGENTBRIDGE_BUDGET_POLL_SECONDS ?? budget.pollSeconds,
+    budgetFreshTtlSec: env.AGENTBRIDGE_BUDGET_FRESH_TTL_SEC ?? budget.budgetFreshTtlSec,
+    idleAdviceActivityWindowSec: env.AGENTBRIDGE_BUDGET_IDLE_ADVICE_ACTIVITY_WINDOW_SEC ?? budget.idleAdviceActivityWindowSec,
     pauseAt: env.AGENTBRIDGE_BUDGET_PAUSE_AT ?? budget.pauseAt,
     resumeBelow: env.AGENTBRIDGE_BUDGET_RESUME_BELOW ?? budget.resumeBelow,
     syncDriftPct: env.AGENTBRIDGE_BUDGET_SYNC_DRIFT_PCT ?? budget.syncDriftPct,
@@ -4846,6 +4852,7 @@ class BudgetCoordinator {
   resumeSignals;
   adviceCooldown;
   isCodexTurnActive;
+  hasRecentActivity;
   timer = null;
   running = false;
   fpState = INITIAL_FINGERPRINT_STATE;
@@ -4876,6 +4883,7 @@ class BudgetCoordinator {
       log: this.log
     });
     this.isCodexTurnActive = options.isCodexTurnActive ?? (() => false);
+    this.hasRecentActivity = options.hasRecentActivity ?? (() => true);
   }
   async start() {
     if (this.running || !this.config.enabled)
@@ -4908,6 +4916,24 @@ class BudgetCoordinator {
   getSnapshot() {
     return this.latestSnapshot;
   }
+  async refreshSnapshotReadonly() {
+    let usage;
+    try {
+      usage = await this.source.fetchBoth();
+    } catch (error) {
+      this.log(`budget readonly refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    if (!usage)
+      return null;
+    const now = this.now();
+    const runway = {
+      claude: agentRunway(usage.claude, now),
+      codex: agentRunway(usage.codex, now)
+    };
+    const state = computeBudgetState(usage.claude, usage.codex, this.config, now, runway);
+    return this.toSnapshot(state, runway);
+  }
   getResumeCandidate() {
     const { detail, ...rest } = this.resumeCandidate;
     return detail ? {
@@ -5025,6 +5051,12 @@ class BudgetCoordinator {
           this.fpState = { ...this.fpState, fingerprint: null };
           return;
         }
+        const activityWindowSec = this.config.idleAdviceActivityWindowSec;
+        if (activityWindowSec > 0 && !this.hasRecentActivity(activityWindowSec)) {
+          this.log(`budget advise suppressed: no agent activity in last ${activityWindowSec}s`);
+          this.fpState = { ...this.fpState, fingerprint: null };
+          return;
+        }
         if (effect.phase === "underutilized") {
           if (!this.adviceCooldown.tryAcquire("underutilization", state.now))
             return;
@@ -6795,7 +6827,8 @@ function ensureBudgetCoordinatorStarted() {
         });
       },
       resumeSignals: readResumeSignals,
-      isCodexTurnActive: () => codex.turnInProgress
+      isCodexTurnActive: () => codex.turnInProgress,
+      hasRecentActivity: (windowSec) => codex.turnInProgress || Date.now() - lastActivityEpochMs <= windowSec * 1000
     });
   }
   budgetCoordinator.start();
@@ -6924,6 +6957,7 @@ codex.on("steerFailed", ({ requestId, reason }) => {
 });
 codex.on("steerAccepted", ({ requestId }) => {
   log("Steer accepted by app-server");
+  recordAgentActivity();
   const dispatch = pendingSteerDispatches.get(requestId);
   pendingSteerDispatches.delete(requestId);
   if (dispatch?.requireReply) {
@@ -6993,13 +7027,19 @@ codex.on("turnTrackingReset", (reason) => {
   pendingSteerDispatches.clear();
   resumeInjectionQueue.onTurnTrackingReset();
 });
+var lastActivityEpochMs = 0;
+function recordAgentActivity() {
+  lastActivityEpochMs = Date.now();
+}
 codex.on("turnStarted", () => {
   log("Codex turn started");
+  recordAgentActivity();
   emitToClaude(systemMessage("system_turn_started", "\u23F3 Codex is working on the current task. Wait for completion before sending a reply."));
 });
 codex.on("agentMessage", (msg) => {
   if (msg.source !== "codex")
     return;
+  recordAgentActivity();
   const route = routeCodexMessage(msg.content, {
     mode: FILTER_MODE,
     replyArmed: replyTracker.isArmed,
@@ -7217,6 +7257,11 @@ function handleControlMessage(ws, raw) {
         log(`handleProbeIncumbent threw for #${ws.data.clientId}: ${err?.message ?? err}`);
       });
       return;
+    case "request_budget_refresh":
+      handleRequestBudgetRefresh(ws, message.requestId).catch((err) => {
+        log(`handleRequestBudgetRefresh threw for #${ws.data.clientId}: ${err?.message ?? err}`);
+      });
+      return;
     case "claude_to_codex": {
       handleClaudeToCodex(ws, message).catch((err) => {
         log(`handleClaudeToCodex threw for request ${message.requestId}: ${err?.message ?? err}`);
@@ -7575,6 +7620,11 @@ async function handleProbeIncumbent(ws) {
     alive: stillConnected && alive
   });
 }
+async function handleRequestBudgetRefresh(ws, requestId) {
+  const snapshot = budgetCoordinator ? await budgetCoordinator.refreshSnapshotReadonly() : null;
+  log(`request_budget_refresh from #${ws.data.clientId}: ${snapshot ? "fresh" : "unavailable"}`);
+  sendProtocolMessage(ws, { type: "budget_refresh", requestId, snapshot });
+}
 async function probeLiveness2(ws, timeoutMs) {
   return probeLiveness({
     get readyState() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raysonmeng/agentbridge",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Bridge between Claude Code and Codex — bidirectional agent communication via MCP Channel + JSON-RPC",
   "type": "module",
   "packageManager": "bun@1.3.11",

package/plugins/agentbridge/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentbridge",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Bridge Claude Code and Codex with a shared daemon, push channel delivery, and bidirectional reply tooling.",
   "author": {
     "name": "AgentBridge Contributors",

package/plugins/agentbridge/server/bridge-server.js

@@ -14161,6 +14161,7 @@ var DEFAULT_MAX_BUFFERED_MESSAGES = 100;
 var DEFAULT_MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
 var DEFAULT_DEDUPE_CAPACITY = 2048;
 var DEFAULT_DEDUPE_TTL_MS = 20 * 60 * 1000;
+var DEFAULT_BUDGET_FRESH_TTL_MS = 25 * 1000;
 var CLAUDE_INSTRUCTIONS = [
   "Codex is an AI coding agent (OpenAI) running in a separate session on the same machine.",
   "",
@@ -14224,6 +14225,10 @@ class ClaudeAdapter extends EventEmitter {
   monotonicNow;
   deliveredMessageIds = new Map;
   budgetSnapshot = null;
+  budgetFreshTtlMs;
+  wallNow;
+  requestFreshSnapshot = null;
+  pendingBudgetRefresh = null;
   constructor(logFile = new StateDirResolver().logFile, options = {}) {
     super();
     this.logFile = logFile;
@@ -14240,6 +14245,8 @@ class ClaudeAdapter extends EventEmitter {
     this.dedupeCapacity = positiveIntegerOr(options.dedupeCapacity, DEFAULT_DEDUPE_CAPACITY);
     this.dedupeTtlMs = positiveIntegerOr(options.dedupeTtlMs, DEFAULT_DEDUPE_TTL_MS);
     this.monotonicNow = options.now ?? (() => performance.now());
+    this.budgetFreshTtlMs = positiveIntegerOr(options.budgetFreshTtlMs, parsePositiveIntegerEnv("AGENTBRIDGE_BUDGET_FRESH_TTL_SEC", DEFAULT_BUDGET_FRESH_TTL_MS / 1000) * 1000);
+    this.wallNow = options.wallNow ?? (() => Date.now());
     this.server = new Server({ name: "agentbridge", version: "0.1.0" }, {
       capabilities: {
         experimental: { "claude/channel": {} },
@@ -14267,6 +14274,9 @@ class ClaudeAdapter extends EventEmitter {
   setBudgetSnapshot(snapshot) {
     this.budgetSnapshot = snapshot;
   }
+  setRequestFreshSnapshot(fetcher) {
+    this.requestFreshSnapshot = fetcher;
+  }
   async pushNotification(message) {
     this.log(`pushNotification (instance=${this.instanceId}, msgId=${message.id}, len=${message.content.length})`);
     if (!this.rememberDelivery(message))
@@ -14543,13 +14553,42 @@ chat_id: ${this.sessionId}`);
       content: [{ type: "text", text: `Resume acknowledged (resume_id=${resumeIdRaw}, status=${status}).` }]
     };
   }
-  handleGetBudget() {
-    this.log(`get_budget called (instance=${this.instanceId}, hasSnapshot=${this.budgetSnapshot !== null})`);
-    const text = this.budgetSnapshot ? renderBudgetSnapshot(this.budgetSnapshot) : BUDGET_UNAVAILABLE_TEXT;
+  async handleGetBudget() {
+    let snapshot = this.budgetSnapshot;
+    const fresh = snapshot !== null && this.isBudgetSnapshotFresh(snapshot);
+    this.log(`get_budget called (instance=${this.instanceId}, hasSnapshot=${snapshot !== null}, fresh=${fresh})`);
+    if (!fresh && this.requestFreshSnapshot) {
+      const refreshed = await this.refreshBudgetSnapshot();
+      snapshot = refreshed ?? this.budgetSnapshot;
+    }
+    const text = snapshot ? renderBudgetSnapshot(snapshot) : BUDGET_UNAVAILABLE_TEXT;
     return {
       content: [{ type: "text", text }]
     };
   }
+  isBudgetSnapshotFresh(snapshot) {
+    if (!snapshot.updatedAt || snapshot.updatedAt <= 0)
+      return false;
+    const ageMs = this.wallNow() - snapshot.updatedAt * 1000;
+    return ageMs < this.budgetFreshTtlMs;
+  }
+  refreshBudgetSnapshot() {
+    if (!this.requestFreshSnapshot)
+      return Promise.resolve(null);
+    if (!this.pendingBudgetRefresh) {
+      this.pendingBudgetRefresh = this.requestFreshSnapshot().then((snapshot) => {
+        if (snapshot)
+          this.budgetSnapshot = snapshot;
+        return snapshot;
+      }).catch((error2) => {
+        this.log(`get_budget refresh failed: ${error2 instanceof Error ? error2.message : String(error2)}`);
+        return null;
+      }).finally(() => {
+        this.pendingBudgetRefresh = null;
+      });
+    }
+    return this.pendingBudgetRefresh;
+  }
   async handleReply(args) {
     const text = args?.text;
     if (!text) {
@@ -14667,11 +14706,11 @@ function defineNumber(value, fallback) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 var BUILD_INFO = Object.freeze({
-  version: defineString("0.1.21", "0.0.0-source"),
-  commit: defineString("ddee9b2", "source"),
+  version: defineString("0.1.23", "0.0.0-source"),
+  commit: defineString("487e717", "source"),
   bundle: defineBundle("plugin"),
   contractVersion: defineNumber(1, CONTRACT_VERSION),
-  codeHash: defineString("8354efa9fcad", "source")
+  codeHash: defineString("e5377c294644", "source")
 });
 function sameRuntimeContract(a, b) {
   if (!a || !b)
@@ -14875,9 +14914,26 @@ class DaemonClient extends EventEmitter2 {
       send: () => this.send({ type: "probe_incumbent" })
     });
   }
+  async requestBudgetRefresh(timeoutMs = 3000) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return null;
+    }
+    const requestId = `budget_${Date.now()}_${this.nextRequestId++}`;
+    return this.awaitTypedResponse({
+      key: "budget_refresh",
+      successEvent: "budgetRefresh",
+      match: (payload) => payload.requestId === requestId,
+      successValue: (payload) => payload.snapshot,
+      failValue: null,
+      timeoutMs,
+      send: () => this.send({ type: "request_budget_refresh", requestId })
+    });
+  }
   awaitTypedResponse(opts) {
-    const { key, successEvent, successValue, failValue, timeoutMs, send } = opts;
+    const { key, successEvent, successValue, failValue, timeoutMs, send, match } = opts;
     const onSuccess = (payload) => {
+      if (match && !match(payload))
+        return;
       this.pendingEventWaiters.settle(key, successValue(payload));
     };
     const onRejected = () => {
@@ -14978,6 +15034,9 @@ class DaemonClient extends EventEmitter2 {
         case "incumbent_status":
           this.emit("incumbentStatus", { connected: message.connected, alive: message.alive });
           return;
+        case "budget_refresh":
+          this.emit("budgetRefresh", { requestId: message.requestId, snapshot: message.snapshot });
+          return;
       }
     };
     ws.onclose = (event) => {
@@ -15694,6 +15753,8 @@ import { join as join2 } from "path";
 var DEFAULT_BUDGET_CONFIG = {
   enabled: true,
   pollSeconds: 300,
+  budgetFreshTtlSec: 25,
+  idleAdviceActivityWindowSec: 600,
   pauseAt: 90,
   resumeBelow: 30,
   syncDriftPct: 10,
@@ -15755,7 +15816,7 @@ function findShapeViolation(raw) {
     if (!isRecord(budget)) {
       return "budget is present but not an object";
     }
-    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct"];
+    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct", "budgetFreshTtlSec", "idleAdviceActivityWindowSec"];
     for (const key of numericKeys) {
       if (key in budget && !isCoercibleNumber(budget[key])) {
         return `budget.${key} is present but not a number`;
@@ -15809,7 +15870,7 @@ function hasCustomDecisionValues(config2) {
   const d = DEFAULT_CONFIG;
   const b = config2.budget;
   const db = d.budget;
-  return config2.idleShutdownSeconds !== d.idleShutdownSeconds || config2.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config2.codex.appPort !== d.codex.appPort || config2.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
+  return config2.idleShutdownSeconds !== d.idleShutdownSeconds || config2.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config2.codex.appPort !== d.codex.appPort || config2.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.budgetFreshTtlSec !== db.budgetFreshTtlSec || b.idleAdviceActivityWindowSec !== db.idleAdviceActivityWindowSec || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
 }
 function normalizeInteger(value, fallback) {
   if (typeof value === "number" && Number.isFinite(value))
@@ -15905,6 +15966,8 @@ function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
   return {
     enabled: normalizeBoolean(budget.enabled, fallback.enabled),
     pollSeconds: normalizeBoundedInteger(budget.pollSeconds, fallback.pollSeconds, 5, 3600),
+    budgetFreshTtlSec: normalizeBoundedInteger(budget.budgetFreshTtlSec, fallback.budgetFreshTtlSec, 1, 300),
+    idleAdviceActivityWindowSec: normalizeBoundedInteger(budget.idleAdviceActivityWindowSec, fallback.idleAdviceActivityWindowSec, 0, 86400),
     pauseAt,
     resumeBelow,
     syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, fallback.syncDriftPct, 1, 100),
@@ -15918,6 +15981,37 @@ function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
     allocation: normalizeAllocationConfig(budget.allocation, fallback.allocation)
   };
 }
+function applyBudgetEnvOverrides(budget, env = process.env) {
+  const overlay = {
+    enabled: env.AGENTBRIDGE_BUDGET_ENABLED ?? budget.enabled,
+    pollSeconds: env.AGENTBRIDGE_BUDGET_POLL_SECONDS ?? budget.pollSeconds,
+    budgetFreshTtlSec: env.AGENTBRIDGE_BUDGET_FRESH_TTL_SEC ?? budget.budgetFreshTtlSec,
+    idleAdviceActivityWindowSec: env.AGENTBRIDGE_BUDGET_IDLE_ADVICE_ACTIVITY_WINDOW_SEC ?? budget.idleAdviceActivityWindowSec,
+    pauseAt: env.AGENTBRIDGE_BUDGET_PAUSE_AT ?? budget.pauseAt,
+    resumeBelow: env.AGENTBRIDGE_BUDGET_RESUME_BELOW ?? budget.resumeBelow,
+    syncDriftPct: env.AGENTBRIDGE_BUDGET_SYNC_DRIFT_PCT ?? budget.syncDriftPct,
+    parallel: {
+      minRemainingPct: env.AGENTBRIDGE_BUDGET_PARALLEL_MIN_REMAINING_PCT ?? budget.parallel.minRemainingPct,
+      timeWindowSec: env.AGENTBRIDGE_BUDGET_PARALLEL_TIME_WINDOW_SEC ?? budget.parallel.timeWindowSec
+    },
+    codexTierControl: env.AGENTBRIDGE_BUDGET_CODEX_TIER_CONTROL ?? budget.codexTierControl,
+    codexTiers: budget.codexTiers,
+    maximize: {
+      targetUtil: env.AGENTBRIDGE_BUDGET_TARGET_UTIL ?? budget.maximize.targetUtil,
+      reserveSlopePctPerHour: env.AGENTBRIDGE_BUDGET_RESERVE_SLOPE_PCT_PER_HOUR ?? budget.maximize.reserveSlopePctPerHour,
+      reserveMaxPct: env.AGENTBRIDGE_BUDGET_RESERVE_MAX_PCT ?? budget.maximize.reserveMaxPct,
+      finishingHorizonMinutes: env.AGENTBRIDGE_BUDGET_FINISHING_HORIZON_MINUTES ?? budget.maximize.finishingHorizonMinutes,
+      resumeHysteresisPct: env.AGENTBRIDGE_BUDGET_RESUME_HYSTERESIS_PCT ?? budget.maximize.resumeHysteresisPct,
+      admissionAt: env.AGENTBRIDGE_BUDGET_ADMISSION_AT ?? budget.maximize.admissionAt,
+      wrapUpQuota: env.AGENTBRIDGE_BUDGET_WRAP_UP_QUOTA ?? budget.maximize.wrapUpQuota
+    },
+    allocation: {
+      minRunwayRatio: env.AGENTBRIDGE_BUDGET_MIN_RUNWAY_RATIO ?? budget.allocation.minRunwayRatio,
+      minRunwayGapHours: env.AGENTBRIDGE_BUDGET_MIN_RUNWAY_GAP_HOURS ?? budget.allocation.minRunwayGapHours
+    }
+  };
+  return normalizeBudgetConfig(overlay, budget);
+}
 function normalizeConfig(raw) {
   if (!isRecord(raw))
     return null;
@@ -16397,8 +16491,12 @@ var config2 = configService.loadOrDefault(processLogger.log);
 var CONTROL_PORT = parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
 var daemonLifecycle = new DaemonLifecycle({ stateDir, controlPort: CONTROL_PORT, log });
 var CONTROL_WS_URL = daemonLifecycle.controlWsUrl;
-var claude = new ClaudeAdapter(stateDir.logFile);
+var effectiveBudget = applyBudgetEnvOverrides(config2.budget);
+var claude = new ClaudeAdapter(stateDir.logFile, {
+  budgetFreshTtlMs: effectiveBudget.budgetFreshTtlSec * 1000
+});
 var daemonClient = new DaemonClient(CONTROL_WS_URL, { identity: currentClientIdentity });
+claude.setRequestFreshSnapshot(() => daemonClient.requestBudgetRefresh());
 var shuttingDown = false;
 var daemonDisabled = false;
 var daemonDisabledReason = null;

package/plugins/agentbridge/server/daemon.js

@@ -29,11 +29,11 @@ function defineNumber(value, fallback) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 var BUILD_INFO = Object.freeze({
-  version: defineString("0.1.21", "0.0.0-source"),
-  commit: defineString("ddee9b2", "source"),
+  version: defineString("0.1.23", "0.0.0-source"),
+  commit: defineString("487e717", "source"),
   bundle: defineBundle("plugin"),
   contractVersion: defineNumber(1, CONTRACT_VERSION),
-  codeHash: defineString("8354efa9fcad", "source")
+  codeHash: defineString("e5377c294644", "source")
 });
 function daemonStatusBuildInfo() {
   return { ...BUILD_INFO };
@@ -3478,6 +3478,8 @@ import { join as join4 } from "path";
 var DEFAULT_BUDGET_CONFIG = {
   enabled: true,
   pollSeconds: 300,
+  budgetFreshTtlSec: 25,
+  idleAdviceActivityWindowSec: 600,
   pauseAt: 90,
   resumeBelow: 30,
   syncDriftPct: 10,
@@ -3539,7 +3541,7 @@ function findShapeViolation(raw) {
     if (!isRecord(budget)) {
       return "budget is present but not an object";
     }
-    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct"];
+    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct", "budgetFreshTtlSec", "idleAdviceActivityWindowSec"];
     for (const key of numericKeys) {
       if (key in budget && !isCoercibleNumber(budget[key])) {
         return `budget.${key} is present but not a number`;
@@ -3593,7 +3595,7 @@ function hasCustomDecisionValues(config) {
   const d = DEFAULT_CONFIG;
   const b = config.budget;
   const db = d.budget;
-  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
+  return config.idleShutdownSeconds !== d.idleShutdownSeconds || config.turnCoordination.attentionWindowSeconds !== d.turnCoordination.attentionWindowSeconds || config.codex.appPort !== d.codex.appPort || config.codex.proxyPort !== d.codex.proxyPort || b.enabled !== db.enabled || b.pollSeconds !== db.pollSeconds || b.budgetFreshTtlSec !== db.budgetFreshTtlSec || b.idleAdviceActivityWindowSec !== db.idleAdviceActivityWindowSec || b.pauseAt !== db.pauseAt || b.resumeBelow !== db.resumeBelow || b.syncDriftPct !== db.syncDriftPct || b.parallel.minRemainingPct !== db.parallel.minRemainingPct || b.parallel.timeWindowSec !== db.parallel.timeWindowSec || b.codexTierControl !== db.codexTierControl || b.maximize.targetUtil !== db.maximize.targetUtil || b.maximize.reserveSlopePctPerHour !== db.maximize.reserveSlopePctPerHour || b.maximize.reserveMaxPct !== db.maximize.reserveMaxPct || b.maximize.finishingHorizonMinutes !== db.maximize.finishingHorizonMinutes || b.maximize.resumeHysteresisPct !== db.maximize.resumeHysteresisPct || b.maximize.admissionAt !== db.maximize.admissionAt || b.maximize.wrapUpQuota !== db.maximize.wrapUpQuota || b.allocation.minRunwayRatio !== db.allocation.minRunwayRatio || b.allocation.minRunwayGapHours !== db.allocation.minRunwayGapHours;
 }
 function normalizeInteger(value, fallback) {
   if (typeof value === "number" && Number.isFinite(value))
@@ -3689,6 +3691,8 @@ function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
   return {
     enabled: normalizeBoolean(budget.enabled, fallback.enabled),
     pollSeconds: normalizeBoundedInteger(budget.pollSeconds, fallback.pollSeconds, 5, 3600),
+    budgetFreshTtlSec: normalizeBoundedInteger(budget.budgetFreshTtlSec, fallback.budgetFreshTtlSec, 1, 300),
+    idleAdviceActivityWindowSec: normalizeBoundedInteger(budget.idleAdviceActivityWindowSec, fallback.idleAdviceActivityWindowSec, 0, 86400),
     pauseAt,
     resumeBelow,
     syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, fallback.syncDriftPct, 1, 100),
@@ -3706,6 +3710,8 @@ function applyBudgetEnvOverrides(budget, env = process.env) {
   const overlay = {
     enabled: env.AGENTBRIDGE_BUDGET_ENABLED ?? budget.enabled,
     pollSeconds: env.AGENTBRIDGE_BUDGET_POLL_SECONDS ?? budget.pollSeconds,
+    budgetFreshTtlSec: env.AGENTBRIDGE_BUDGET_FRESH_TTL_SEC ?? budget.budgetFreshTtlSec,
+    idleAdviceActivityWindowSec: env.AGENTBRIDGE_BUDGET_IDLE_ADVICE_ACTIVITY_WINDOW_SEC ?? budget.idleAdviceActivityWindowSec,
     pauseAt: env.AGENTBRIDGE_BUDGET_PAUSE_AT ?? budget.pauseAt,
     resumeBelow: env.AGENTBRIDGE_BUDGET_RESUME_BELOW ?? budget.resumeBelow,
     syncDriftPct: env.AGENTBRIDGE_BUDGET_SYNC_DRIFT_PCT ?? budget.syncDriftPct,
@@ -4846,6 +4852,7 @@ class BudgetCoordinator {
   resumeSignals;
   adviceCooldown;
   isCodexTurnActive;
+  hasRecentActivity;
   timer = null;
   running = false;
   fpState = INITIAL_FINGERPRINT_STATE;
@@ -4876,6 +4883,7 @@ class BudgetCoordinator {
       log: this.log
     });
     this.isCodexTurnActive = options.isCodexTurnActive ?? (() => false);
+    this.hasRecentActivity = options.hasRecentActivity ?? (() => true);
   }
   async start() {
     if (this.running || !this.config.enabled)
@@ -4908,6 +4916,24 @@ class BudgetCoordinator {
   getSnapshot() {
     return this.latestSnapshot;
   }
+  async refreshSnapshotReadonly() {
+    let usage;
+    try {
+      usage = await this.source.fetchBoth();
+    } catch (error) {
+      this.log(`budget readonly refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    if (!usage)
+      return null;
+    const now = this.now();
+    const runway = {
+      claude: agentRunway(usage.claude, now),
+      codex: agentRunway(usage.codex, now)
+    };
+    const state = computeBudgetState(usage.claude, usage.codex, this.config, now, runway);
+    return this.toSnapshot(state, runway);
+  }
   getResumeCandidate() {
     const { detail, ...rest } = this.resumeCandidate;
     return detail ? {
@@ -5025,6 +5051,12 @@ class BudgetCoordinator {
           this.fpState = { ...this.fpState, fingerprint: null };
           return;
         }
+        const activityWindowSec = this.config.idleAdviceActivityWindowSec;
+        if (activityWindowSec > 0 && !this.hasRecentActivity(activityWindowSec)) {
+          this.log(`budget advise suppressed: no agent activity in last ${activityWindowSec}s`);
+          this.fpState = { ...this.fpState, fingerprint: null };
+          return;
+        }
         if (effect.phase === "underutilized") {
           if (!this.adviceCooldown.tryAcquire("underutilization", state.now))
             return;
@@ -6795,7 +6827,8 @@ function ensureBudgetCoordinatorStarted() {
         });
       },
       resumeSignals: readResumeSignals,
-      isCodexTurnActive: () => codex.turnInProgress
+      isCodexTurnActive: () => codex.turnInProgress,
+      hasRecentActivity: (windowSec) => codex.turnInProgress || Date.now() - lastActivityEpochMs <= windowSec * 1000
     });
   }
   budgetCoordinator.start();
@@ -6924,6 +6957,7 @@ codex.on("steerFailed", ({ requestId, reason }) => {
 });
 codex.on("steerAccepted", ({ requestId }) => {
   log("Steer accepted by app-server");
+  recordAgentActivity();
   const dispatch = pendingSteerDispatches.get(requestId);
   pendingSteerDispatches.delete(requestId);
   if (dispatch?.requireReply) {
@@ -6993,13 +7027,19 @@ codex.on("turnTrackingReset", (reason) => {
   pendingSteerDispatches.clear();
   resumeInjectionQueue.onTurnTrackingReset();
 });
+var lastActivityEpochMs = 0;
+function recordAgentActivity() {
+  lastActivityEpochMs = Date.now();
+}
 codex.on("turnStarted", () => {
   log("Codex turn started");
+  recordAgentActivity();
   emitToClaude(systemMessage("system_turn_started", "\u23F3 Codex is working on the current task. Wait for completion before sending a reply."));
 });
 codex.on("agentMessage", (msg) => {
   if (msg.source !== "codex")
     return;
+  recordAgentActivity();
   const route = routeCodexMessage(msg.content, {
     mode: FILTER_MODE,
     replyArmed: replyTracker.isArmed,
@@ -7217,6 +7257,11 @@ function handleControlMessage(ws, raw) {
         log(`handleProbeIncumbent threw for #${ws.data.clientId}: ${err?.message ?? err}`);
       });
       return;
+    case "request_budget_refresh":
+      handleRequestBudgetRefresh(ws, message.requestId).catch((err) => {
+        log(`handleRequestBudgetRefresh threw for #${ws.data.clientId}: ${err?.message ?? err}`);
+      });
+      return;
     case "claude_to_codex": {
       handleClaudeToCodex(ws, message).catch((err) => {
         log(`handleClaudeToCodex threw for request ${message.requestId}: ${err?.message ?? err}`);
@@ -7575,6 +7620,11 @@ async function handleProbeIncumbent(ws) {
     alive: stillConnected && alive
   });
 }
+async function handleRequestBudgetRefresh(ws, requestId) {
+  const snapshot = budgetCoordinator ? await budgetCoordinator.refreshSnapshotReadonly() : null;
+  log(`request_budget_refresh from #${ws.data.clientId}: ${snapshot ? "fresh" : "unavailable"}`);
+  sendProtocolMessage(ws, { type: "budget_refresh", requestId, snapshot });
+}
 async function probeLiveness2(ws, timeoutMs) {
   return probeLiveness({
     get readyState() {