@raysonmeng/agentbridge 0.1.11 → 0.1.12

package/plugins/agentbridge/server/daemon.js

@@ -17,8 +17,8 @@ function defineNumber(value, fallback) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 var BUILD_INFO = Object.freeze({
-  version: defineString("0.1.11", "0.0.0-source"),
-  commit: defineString("48eb0ed", "source"),
+  version: defineString("0.1.12", "0.0.0-source"),
+  commit: defineString("eec6018", "source"),
   bundle: defineBundle("plugin"),
   contractVersion: defineNumber(1, CONTRACT_VERSION)
 });
@@ -209,13 +209,14 @@ import { appendFileSync, existsSync as existsSync2, renameSync, statSync, unlink
 import { dirname } from "path";
 var DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
 var DEFAULT_KEEP = 3;
-function appendRotatingLog(path, content, options = {}) {
+var REAL_FS_OPS = { statSync, renameSync, unlinkSync, appendFileSync, existsSync: existsSync2 };
+function appendRotatingLog(path, content, options = {}, fsOps = REAL_FS_OPS) {
   const maxBytes = options.maxBytes ?? positiveIntFromEnv("AGENTBRIDGE_LOG_MAX_BYTES", DEFAULT_MAX_BYTES);
   const keep = options.keep ?? positiveIntFromEnv("AGENTBRIDGE_LOG_ROTATE_KEEP", DEFAULT_KEEP);
-  if (!existsSync2(dirname(path)))
+  if (!fsOps.existsSync(dirname(path)))
     return;
-  rotateIfNeeded(path, Buffer.byteLength(content), maxBytes, keep);
-  appendFileSync(path, content, "utf-8");
+  rotateIfNeeded(path, Buffer.byteLength(content), maxBytes, keep, fsOps);
+  fsOps.appendFileSync(path, content, "utf-8");
 }
 function positiveIntFromEnv(name, fallback) {
   const value = process.env[name];
@@ -224,26 +225,48 @@ function positiveIntFromEnv(name, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
 }
-function rotateIfNeeded(path, incomingBytes, maxBytes, keep) {
+function isEnoent(error) {
+  return !!error && error.code === "ENOENT";
+}
+function renameIfPresent(from, to, fsOps) {
+  try {
+    fsOps.renameSync(from, to);
+  } catch (error) {
+    if (!isEnoent(error))
+      throw error;
+  }
+}
+function unlinkIfPresent(path, fsOps) {
+  try {
+    fsOps.unlinkSync(path);
+  } catch (error) {
+    if (!isEnoent(error))
+      throw error;
+  }
+}
+function rotateIfNeeded(path, incomingBytes, maxBytes, keep, fsOps) {
   if (!Number.isFinite(maxBytes) || maxBytes <= 0 || keep <= 0)
     return;
-  if (!existsSync2(path))
-    return;
-  const size = statSync(path).size;
+  let size;
+  try {
+    size = fsOps.statSync(path).size;
+  } catch (error) {
+    if (isEnoent(error))
+      return;
+    throw error;
+  }
   if (size + incomingBytes <= maxBytes)
     return;
   for (let index = keep;index >= 1; index--) {
     const current = `${path}.${index}`;
     const next = `${path}.${index + 1}`;
-    if (!existsSync2(current))
-      continue;
     if (index === keep) {
-      unlinkSync(current);
+      unlinkIfPresent(current, fsOps);
     } else {
-      renameSync(current, next);
+      renameIfPresent(current, next, fsOps);
     }
   }
-  renameSync(path, `${path}.1`);
+  renameIfPresent(path, `${path}.1`, fsOps);
 }
 
 // src/process-log.ts
@@ -362,6 +385,28 @@ function isAppServerResponseMessage(value) {
   return (typeof value.id === "number" || typeof value.id === "string") && value.method === undefined && (("result" in value) || ("error" in value));
 }
 
+// src/env-utils.ts
+function parsePositiveIntEnv(name, fallback, log = () => {}, env = process.env) {
+  const raw = env[name];
+  if (raw == null || raw === "")
+    return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > Number.MAX_SAFE_INTEGER) {
+    log(`Invalid ${name}=${JSON.stringify(raw)} (must be a positive integer within ` + `Number.MAX_SAFE_INTEGER); falling back to ${fallback}`);
+    return fallback;
+  }
+  return parsed;
+}
+
+// src/interrupt-timing.ts
+var CLIENT_REPLY_TIMEOUT_MS = 15000;
+var INTERRUPT_CLIENT_MARGIN_MS = 2000;
+var DEFAULT_INTERRUPT_TIMEOUT_MS = 1e4;
+var MAX_INTERRUPT_TIMEOUT_MS = CLIENT_REPLY_TIMEOUT_MS - INTERRUPT_CLIENT_MARGIN_MS;
+function clampInterruptTimeoutMs(requested) {
+  return Math.min(requested, MAX_INTERRUPT_TIMEOUT_MS);
+}
+
 // src/codex-transport.ts
 import { createServer, connect } from "net";
 import { spawnSync } from "child_process";
@@ -602,6 +647,25 @@ function buildTurnAbortedNotice(reason, replyWasRequired) {
   return `\u26A0\uFE0F Codex's current turn ended without completing (${reason}). ` + "This usually means Codex hit an error (e.g. a rate limit / 429), the app-server connection dropped, or the turn was interrupted." + tail;
 }
 
+// src/ws-origin-guard.ts
+var ALLOWED_ORIGINS_ENV = "AGENTBRIDGE_WS_ALLOWED_ORIGINS";
+function parseAllowedWsOrigins(env = process.env) {
+  const raw = env[ALLOWED_ORIGINS_ENV];
+  if (raw == null || raw === "")
+    return new Set;
+  const origins = raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  return new Set(origins);
+}
+function isAllowedWsUpgrade(req, allowedOrigins = parseAllowedWsOrigins()) {
+  const origin = req.headers.get("origin");
+  if (origin == null || origin === "")
+    return true;
+  return allowedOrigins.has(origin);
+}
+function wsOriginRejectedResponse() {
+  return new Response("Forbidden: WebSocket Origin not allowed", { status: 403 });
+}
+
 // src/codex-adapter.ts
 class CodexAdapter extends EventEmitter {
   static RESPONSE_TRACKING_TTL_MS = 30000;
@@ -764,15 +828,15 @@ class CodexAdapter extends EventEmitter {
   injectMessage(text, overrides) {
     if (!this.threadId) {
       this.log("Cannot inject: no active thread");
-      return false;
+      return null;
     }
     if (!this.appServerWs || this.appServerWs.readyState !== WebSocket.OPEN) {
       this.log("Cannot inject: app-server WebSocket not connected");
-      return false;
+      return null;
     }
     if (this.turnInProgress) {
       this.log(`Rejected injection: Codex turn is in progress (thread ${this.threadId})`);
-      return false;
+      return null;
     }
     this.log(`Injecting message into Codex (${text.length} chars)`);
     const requestId = this.nextInjectionId--;
@@ -791,30 +855,30 @@ class CodexAdapter extends EventEmitter {
         id: requestId,
         params
       }));
-      return true;
+      return requestId;
     } catch (err) {
       this.untrackBridgeRequestId(requestId);
       this.log(`Injection send failed: ${err.message}`);
-      return false;
+      return null;
     }
   }
   steerMessage(text) {
     if (!this.threadId) {
       this.log("Cannot steer: no active thread");
-      return false;
+      return null;
     }
     if (!this.appServerWs || this.appServerWs.readyState !== WebSocket.OPEN) {
       this.log("Cannot steer: app-server WebSocket not connected");
-      return false;
+      return null;
     }
     if (!this.turnInProgress) {
       this.log("Cannot steer: no turn in progress (use injectMessage)");
-      return false;
+      return null;
     }
     const expectedTurnId = this.currentSteerableTurnId();
     if (!expectedTurnId) {
       this.log("Cannot steer: no addressable active turn id (turn/started carried no id)");
-      return false;
+      return null;
     }
     this.log(`Steering message into active Codex turn ${expectedTurnId} (${text.length} chars)`);
     const requestId = this.nextInjectionId--;
@@ -830,12 +894,96 @@ class CodexAdapter extends EventEmitter {
         id: requestId,
         params
       }));
-      return true;
+      return requestId;
     } catch (err) {
       this.untrackBridgeRequestId(requestId);
       this.log(`Steer send failed: ${err.message}`);
-      return false;
+      return null;
+    }
+  }
+  interruptActiveTurns() {
+    if (!this.threadId) {
+      this.log("Cannot interrupt: no active thread");
+      return { ok: false, code: "interrupt_unavailable", error: "no active thread" };
+    }
+    if (!this.appServerWs || this.appServerWs.readyState !== WebSocket.OPEN) {
+      this.log("Cannot interrupt: app-server WebSocket not connected");
+      return { ok: false, code: "interrupt_unavailable", error: "app-server WebSocket not connected" };
+    }
+    const addressable = [...this.activeTurnIds].filter((id) => !id.startsWith("unknown:"));
+    if (addressable.length === 0) {
+      this.log("Cannot interrupt: no addressable active turn id (turn/started carried no id)");
+      return {
+        ok: false,
+        code: "interrupt_unavailable",
+        error: "no addressable active turn id (turn/started carried no id)"
+      };
+    }
+    for (const turnId of addressable) {
+      const requestId = this.nextInjectionId--;
+      this.trackBridgeRequestId(requestId, "interrupt");
+      const params = { threadId: this.threadId, turnId };
+      try {
+        this.appServerWs.send(JSON.stringify({
+          method: "turn/interrupt",
+          id: requestId,
+          params
+        }));
+        this.log(`Sent turn/interrupt for active turn ${turnId} (request ${requestId})`);
+      } catch (err) {
+        this.untrackBridgeRequestId(requestId);
+        this.log(`turn/interrupt send failed for ${turnId}: ${err.message}`);
+        return {
+          ok: false,
+          code: "interrupt_unavailable",
+          error: `turn/interrupt send failed (${err.message}); earlier interrupts may still land`
+        };
+      }
     }
+    return { ok: true, turnIds: addressable };
+  }
+  interruptTimeoutMs() {
+    const requested = parsePositiveIntEnv("AGENTBRIDGE_INTERRUPT_TIMEOUT_MS", DEFAULT_INTERRUPT_TIMEOUT_MS, (m) => this.log(m));
+    const clamped = clampInterruptTimeoutMs(requested);
+    if (clamped !== requested) {
+      this.log(`AGENTBRIDGE_INTERRUPT_TIMEOUT_MS=${requested}ms exceeds the safe ceiling \u2014 ` + `clamped to ${clamped}ms (must resolve before the client reply timeout to avoid a double-turn)`);
+    }
+    return clamped;
+  }
+  waitForTurnsTerminal(turnIds, timeoutMs = this.interruptTimeoutMs(), signal) {
+    const satisfied = () => turnIds.every((id) => !this.activeTurnIds.has(id) && !this.currentlyStalledTurnIds.has(id));
+    if (satisfied())
+      return Promise.resolve({ ok: true });
+    if (signal?.aborted)
+      return Promise.resolve({ ok: false, code: "interrupt_aborted" });
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timer);
+        this.off("turnIdCompleted", check);
+        this.off("turnTrackingReset", check);
+        this.off("turnPhaseChanged", check);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(result);
+      };
+      const check = () => {
+        if (satisfied())
+          finish({ ok: true });
+      };
+      const onAbort = () => finish({ ok: false, code: "interrupt_aborted" });
+      const timer = setTimeout(() => {
+        this.log(`waitForTurnsTerminal timed out after ${timeoutMs}ms (still active: ` + `${turnIds.filter((id) => this.activeTurnIds.has(id)).join(", ") || "none"}, phase=${this.turnPhase})`);
+        finish({ ok: false, code: "interrupt_timeout" });
+      }, timeoutMs);
+      timer.unref?.();
+      this.on("turnIdCompleted", check);
+      this.on("turnTrackingReset", check);
+      this.on("turnPhaseChanged", check);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
   }
   async waitForHealthy(maxRetries = 20, delayMs = 500) {
     for (let i = 0;i < maxRetries; i++) {
@@ -1151,6 +1299,10 @@ class CodexAdapter extends EventEmitter {
           }
           return fetch(`http://127.0.0.1:${self.appPort}${url.pathname}`);
         }
+        if (isUpgrade && !isAllowedWsUpgrade(req)) {
+          self.log("Rejected WS upgrade on proxy port: Origin header present (possible CSWSH)");
+          return wsOriginRejectedResponse();
+        }
         if (server.upgrade(req, { data: { connId: 0 } }))
           return;
         self.log(`WARNING: non-upgrade HTTP request not handled: ${req.method} ${url.pathname}`);
@@ -1564,16 +1716,30 @@ class CodexAdapter extends EventEmitter {
       if (parsed.error) {
         this.log(`Bridge-originated ${bridgeKind} request failed (id ${responseId}): ${parsed.error.message ?? "unknown error"}`);
         if (bridgeKind === "steer") {
-          this.emit("steerFailed", parsed.error.message ?? "unknown error");
+          this.emit("steerFailed", { requestId: numericId, reason: parsed.error.message ?? "unknown error" });
+        } else if (bridgeKind === "interrupt") {
+          this.emit("interruptFailed", parsed.error.message ?? "unknown error");
         } else {
           this.lastTurnEndedAbnormally = true;
           this.emit("turnAborted", `injected turn/start rejected: ${parsed.error.message ?? "unknown error"}`);
+          this.emit("bridgeTurnRejected", {
+            requestId: numericId,
+            error: parsed.error.message ?? "unknown error"
+          });
           this.notifyPhaseIfChanged();
         }
       } else {
         this.log(`Bridge-originated ${bridgeKind} request completed (id ${responseId})`);
         if (bridgeKind === "steer") {
-          this.emit("steerAccepted");
+          this.emit("steerAccepted", { requestId: numericId });
+        } else if (bridgeKind === "turn-start") {
+          const result = parsed.result;
+          const turnId = result?.turn?.id;
+          if (typeof turnId === "string" && turnId.length > 0) {
+            this.emit("bridgeTurnStarted", { requestId: numericId, turnId });
+          } else {
+            this.log(`Bridge-originated turn/start response carried no turn id (id ${responseId}) \u2014 turn_started ACK skipped`);
+          }
         }
       }
       return null;
@@ -1775,6 +1941,9 @@ class CodexAdapter extends EventEmitter {
     }
     return newest;
   }
+  get steerableTurnId() {
+    return this.currentSteerableTurnId();
+  }
   get turnPhase() {
     if (this.activeTurnIds.size > 0) {
       const allStalled = [...this.activeTurnIds].every((id) => this.currentlyStalledTurnIds.has(id));
@@ -1806,11 +1975,12 @@ class CodexAdapter extends EventEmitter {
     this.notifyPhaseIfChanged();
   }
   markTurnCompleted(turnId) {
-    if (typeof turnId === "string" && turnId.length > 0) {
-      this.activeTurnIds.delete(turnId);
-      this.clearTurnWatchdog(turnId);
-      this.stalledTurnIds.delete(turnId);
-      this.currentlyStalledTurnIds.delete(turnId);
+    const completedId = typeof turnId === "string" && turnId.length > 0 ? turnId : null;
+    if (completedId !== null) {
+      this.activeTurnIds.delete(completedId);
+      this.clearTurnWatchdog(completedId);
+      this.stalledTurnIds.delete(completedId);
+      this.currentlyStalledTurnIds.delete(completedId);
     } else {
       this.activeTurnIds.clear();
       this.clearAllTurnWatchdogs();
@@ -1819,6 +1989,7 @@ class CodexAdapter extends EventEmitter {
     }
     this.lastTurnEndedAbnormally = false;
     this.turnInProgress = this.activeTurnIds.size > 0;
+    this.emit("turnIdCompleted", completedId);
     this.notifyPhaseIfChanged();
   }
   turnWatchdogMs() {
@@ -1888,6 +2059,7 @@ class CodexAdapter extends EventEmitter {
       this.log(`Turn state reset (${reason})`);
     }
     this.notifyPhaseIfChanged();
+    this.emit("turnTrackingReset", reason);
   }
   requestKey(id) {
     if (typeof id === "number" || typeof id === "string")
@@ -2229,19 +2401,6 @@ import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync3, readFileSync, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync, openSync, closeSync, constants } from "fs";
 import { fileURLToPath } from "url";
 
-// src/env-utils.ts
-function parsePositiveIntEnv(name, fallback, log = () => {}, env = process.env) {
-  const raw = env[name];
-  if (raw == null || raw === "")
-    return fallback;
-  const parsed = Number(raw);
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > Number.MAX_SAFE_INTEGER) {
-    log(`Invalid ${name}=${JSON.stringify(raw)} (must be a positive integer within ` + `Number.MAX_SAFE_INTEGER); falling back to ${fallback}`);
-    return fallback;
-  }
-  return parsed;
-}
-
 // src/process-lifecycle.ts
 import { execFileSync as execFileSync2 } from "child_process";
 function commandForPid(pid) {
@@ -2285,6 +2444,48 @@ var REUSE_READY_RETRIES = parsePositiveIntEnv("AGENTBRIDGE_REUSE_READY_RETRIES",
 var REUSE_READY_DELAY_MS = 250;
 var HEALTH_FETCH_TIMEOUT_MS = 500;
 var LOCK_IDENTITY_GRACE_MS = parsePositiveIntEnv("AGENTBRIDGE_LOCK_IDENTITY_GRACE_MS", 120000);
+function isReuseVerdict(verdict) {
+  return verdict === "reuse" || verdict === "reuse-despite-drift";
+}
+function classifyDaemon(expectedPairId, status, buildInfo) {
+  if (!status) {
+    return { verdict: "unreachable", reason: "daemon status is unavailable or unparseable" };
+  }
+  const reportedPairId = status.pairId;
+  if (!expectedPairId && reportedPairId != null) {
+    return {
+      verdict: "manual-conflict",
+      reason: `manual mode must not adopt registered pair ${reportedPairId}`
+    };
+  }
+  if (expectedPairId) {
+    if (reportedPairId == null) {
+      return {
+        verdict: "replace-foreign",
+        reason: `pair ${expectedPairId} found daemon without pair identity`
+      };
+    }
+    if (reportedPairId !== expectedPairId) {
+      return {
+        verdict: "replace-foreign",
+        reason: `pair ${expectedPairId} found daemon for pair ${reportedPairId}`
+      };
+    }
+  }
+  if (!sameRuntimeContract(status.build, buildInfo)) {
+    if (compatibleContractVersion(status.build, buildInfo) && status.tuiConnected === true) {
+      return {
+        verdict: "reuse-despite-drift",
+        reason: "runtime build drift has a compatible contract and a live Codex TUI is attached"
+      };
+    }
+    return {
+      verdict: "replace-drifted",
+      reason: `runtime build ${formatBuildInfo(status.build)} does not match launcher ${formatBuildInfo(buildInfo)}`
+    };
+  }
+  return { verdict: "reuse", reason: "daemon pair and runtime contract match" };
+}
 
 class DaemonLifecycle {
   stateDir;
@@ -2317,52 +2518,37 @@ class DaemonLifecycle {
       return null;
     }
   }
-  isForeignDaemon(status) {
-    const expected = this.expectedPairId;
-    if (!expected)
-      return false;
-    if (!status)
-      return false;
-    const reported = status.pairId;
-    if (reported == null)
-      return true;
-    return reported !== expected;
-  }
-  isRegisteredPairDaemonInManualMode(status) {
-    return !this.expectedPairId && status?.pairId != null;
-  }
-  isBuildDrifted(status) {
-    if (process.env.AGENTBRIDGE_ALLOW_BUILD_DRIFT === "1")
-      return false;
-    const runtime = status?.build;
-    if (!runtime)
-      return true;
-    return !sameRuntimeContract(runtime, BUILD_INFO);
+  classifyDaemon(status) {
+    const classification = classifyDaemon(this.expectedPairId, status, BUILD_INFO);
+    if (process.env.AGENTBRIDGE_ALLOW_BUILD_DRIFT === "1" && (classification.verdict === "replace-drifted" || classification.verdict === "unreachable")) {
+      return { verdict: "reuse", reason: "build drift replacement disabled by AGENTBRIDGE_ALLOW_BUILD_DRIFT" };
+    }
+    return classification;
   }
-  canReuseDespiteDrift(status) {
-    if (!compatibleContractVersion(status?.build, BUILD_INFO))
-      return false;
-    return status?.tuiConnected === true;
+  manualConflictError(status) {
+    return new Error(`Control port ${this.controlPort} is owned by registered pair ${status?.pairId}. ` + `This session has no pair identity (manual mode) and will not reuse or replace it \u2014 ` + `start with \`agentbridge claude\` from that pair's directory, or set AGENTBRIDGE_CONTROL_PORT to a free port.`);
   }
   async ensureRunning() {
     if (await this.isHealthy()) {
       const status = await this.fetchStatus();
-      if (this.isRegisteredPairDaemonInManualMode(status)) {
-        throw new Error(`Control port ${this.controlPort} is owned by registered pair ${status?.pairId}. ` + `This session has no pair identity (manual mode) and will not reuse or replace it \u2014 ` + `start with \`agentbridge claude\` from that pair's directory, or set AGENTBRIDGE_CONTROL_PORT to a free port.`);
-      }
-      if (this.isForeignDaemon(status)) {
-        this.log(`Control port ${this.controlPort} held by a daemon for pair ${status?.pairId ?? "<none>"}, ` + `but this pair is ${this.expectedPairId} \u2014 replacing foreign daemon`);
-        await this.replaceUnhealthyDaemon(status?.pid);
-        return;
-      }
-      if (this.isBuildDrifted(status)) {
-        if (this.canReuseDespiteDrift(status)) {
-          this.log(`Daemon on control port ${this.controlPort} is running build ${formatBuildInfo(status?.build)} ` + `(launcher ${formatBuildInfo(BUILD_INFO)}) but a live Codex TUI is attached \u2014 reusing instead of ` + `replacing; the new build is picked up at the next restart (abg kill, then relaunch)`);
-        } else {
+      const classification = this.classifyDaemon(status);
+      switch (classification.verdict) {
+        case "manual-conflict":
+          throw this.manualConflictError(status);
+        case "replace-foreign":
+          this.log(`Control port ${this.controlPort} held by a daemon for pair ${status?.pairId ?? "<none>"}, ` + `but this pair is ${this.expectedPairId} \u2014 replacing foreign daemon`);
+          await this.replaceUnhealthyDaemon(status?.pid);
+          return;
+        case "replace-drifted":
+        case "unreachable":
           this.log(`Daemon on control port ${this.controlPort} is running build ${formatBuildInfo(status?.build)} ` + `but launcher is ${formatBuildInfo(BUILD_INFO)} \u2014 replacing drifted daemon`);
           await this.replaceUnhealthyDaemon(status?.pid);
           return;
-        }
+        case "reuse-despite-drift":
+          this.log(`Daemon on control port ${this.controlPort} is running build ${formatBuildInfo(status?.build)} ` + `(launcher ${formatBuildInfo(BUILD_INFO)}) but a live Codex TUI is attached \u2014 reusing instead of ` + `replacing; the new build is picked up at the next restart (abg kill, then relaunch)`);
+          break;
+        case "reuse":
+          break;
       }
       try {
         await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
@@ -2392,14 +2578,17 @@ class DaemonLifecycle {
     }
     await this.withStartupLockStrict(async (locked) => {
       if (!locked) {
-        this.log("Another process holds the startup lock, waiting for readiness+identity...");
-        await this.waitForReadyAndOurs();
+        await this.waitForContendedStartupLock();
         return;
       }
       if (await this.isHealthy()) {
         const status = await this.fetchStatus();
-        if (this.isForeignDaemon(status) || this.isBuildDrifted(status) && !this.canReuseDespiteDrift(status)) {
-          this.log(`Daemon on control port ${this.controlPort} is not reusable under startup lock ` + `(pair=${status?.pairId ?? "<none>"}, build=${formatBuildInfo(status?.build)}) \u2014 replacing`);
+        const classification = this.classifyDaemon(status);
+        if (classification.verdict === "manual-conflict") {
+          throw this.manualConflictError(status);
+        }
+        if (!isReuseVerdict(classification.verdict)) {
+          this.log(`Daemon on control port ${this.controlPort} is not reusable under startup lock ` + `(pair=${status?.pairId ?? "<none>"}, build=${formatBuildInfo(status?.build)}, ` + `reason=${classification.reason}) \u2014 replacing`);
           await this.kill(3000, status?.pid);
         } else {
           try {
@@ -2451,7 +2640,11 @@ class DaemonLifecycle {
     for (let attempt = 0;attempt < maxRetries; attempt++) {
       if (await this.isReady()) {
         const status = await this.fetchStatus();
-        if (!this.isForeignDaemon(status) && (!this.isBuildDrifted(status) || this.canReuseDespiteDrift(status))) {
+        const classification = this.classifyDaemon(status);
+        if (classification.verdict === "manual-conflict") {
+          throw this.manualConflictError(status);
+        }
+        if (isReuseVerdict(classification.verdict)) {
           return;
         }
       }
@@ -2533,13 +2726,16 @@ class DaemonLifecycle {
   async replaceUnhealthyDaemon(statusPid) {
     await this.withStartupLockStrict(async (locked) => {
       if (!locked) {
-        this.log("Another process holds the startup lock, waiting for readiness+identity...");
-        await this.waitForReadyAndOurs();
+        await this.waitForContendedStartupLock();
         return;
       }
       if (await this.isHealthy()) {
         const status = await this.fetchStatus();
-        if (!this.isForeignDaemon(status) && (!this.isBuildDrifted(status) || this.canReuseDespiteDrift(status))) {
+        const classification = this.classifyDaemon(status);
+        if (classification.verdict === "manual-conflict") {
+          throw this.manualConflictError(status);
+        }
+        if (isReuseVerdict(classification.verdict)) {
           try {
             await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
             return;
@@ -2552,6 +2748,10 @@ class DaemonLifecycle {
       await this.waitForReady();
     });
   }
+  async waitForContendedStartupLock() {
+    this.log("Another process holds the startup lock, waiting for readiness+identity...");
+    await this.waitForReadyAndOurs();
+  }
   async withStartupLockStrict(fn) {
     const locked = this.acquireLockStrict();
     try {
@@ -2673,7 +2873,7 @@ import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSy
 import { join as join3 } from "path";
 var DEFAULT_BUDGET_CONFIG = {
   enabled: true,
-  pollSeconds: 60,
+  pollSeconds: 300,
   pauseAt: 90,
   resumeBelow: 30,
   syncDriftPct: 10,
@@ -2702,9 +2902,52 @@ var DEFAULT_CONFIG = {
 };
 var CONFIG_DIR = ".agentbridge";
 var CONFIG_FILE = "config.json";
+var NOOP_LOGGER = () => {};
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isCoercibleNumber(value) {
+  if (typeof value === "number")
+    return Number.isFinite(value);
+  if (typeof value === "string")
+    return Number.isFinite(Number(value));
+  return false;
+}
+function findShapeViolation(raw) {
+  if ("idleShutdownSeconds" in raw && !isCoercibleNumber(raw.idleShutdownSeconds)) {
+    return "idleShutdownSeconds is present but not a number";
+  }
+  if ("budget" in raw) {
+    const budget = raw.budget;
+    if (!isRecord(budget)) {
+      return "budget is present but not an object";
+    }
+    const numericKeys = ["pauseAt", "resumeBelow", "pollSeconds", "syncDriftPct"];
+    for (const key of numericKeys) {
+      if (key in budget && !isCoercibleNumber(budget[key])) {
+        return `budget.${key} is present but not a number`;
+      }
+    }
+    if ("parallel" in budget) {
+      const parallel = budget.parallel;
+      if (!isRecord(parallel)) {
+        return "budget.parallel is present but not an object";
+      }
+      for (const key of ["minRemainingPct", "timeWindowSec"]) {
+        if (key in parallel && !isCoercibleNumber(parallel[key])) {
+          return `budget.parallel.${key} is present but not a number`;
+        }
+      }
+    }
+  }
+  return null;
+}
+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;
+}
 function normalizeInteger(value, fallback) {
   if (typeof value === "number" && Number.isFinite(value))
     return value;
@@ -2740,35 +2983,35 @@ function normalizeCodexOverride(raw) {
     override.effort = raw.effort.trim();
   return Object.keys(override).length > 0 ? override : null;
 }
-function normalizeCodexTiers(raw) {
+function normalizeCodexTiers(raw, fallback = DEFAULT_BUDGET_CONFIG.codexTiers) {
   const tiers = isRecord(raw) ? raw : {};
   return {
     full: normalizeCodexOverride(tiers.full),
-    balanced: normalizeCodexOverride(tiers.balanced) ?? DEFAULT_BUDGET_CONFIG.codexTiers.balanced,
-    eco: normalizeCodexOverride(tiers.eco) ?? DEFAULT_BUDGET_CONFIG.codexTiers.eco
+    balanced: normalizeCodexOverride(tiers.balanced) ?? fallback.balanced,
+    eco: normalizeCodexOverride(tiers.eco) ?? fallback.eco
   };
 }
-function normalizeBudgetConfig(raw) {
+function normalizeBudgetConfig(raw, fallback = DEFAULT_BUDGET_CONFIG) {
   const budget = isRecord(raw) ? raw : {};
   const parallel = isRecord(budget.parallel) ? budget.parallel : {};
-  const codexTiers = normalizeCodexTiers(budget.codexTiers);
-  let pauseAt = normalizeBoundedInteger(budget.pauseAt, DEFAULT_BUDGET_CONFIG.pauseAt, 1, 100);
-  let resumeBelow = normalizeBoundedInteger(budget.resumeBelow, DEFAULT_BUDGET_CONFIG.resumeBelow, 0, 99);
+  const codexTiers = normalizeCodexTiers(budget.codexTiers, fallback.codexTiers);
+  let pauseAt = normalizeBoundedInteger(budget.pauseAt, fallback.pauseAt, 1, 100);
+  let resumeBelow = normalizeBoundedInteger(budget.resumeBelow, fallback.resumeBelow, 0, 99);
   if (pauseAt <= resumeBelow) {
     pauseAt = DEFAULT_BUDGET_CONFIG.pauseAt;
     resumeBelow = DEFAULT_BUDGET_CONFIG.resumeBelow;
   }
   return {
-    enabled: normalizeBoolean(budget.enabled, DEFAULT_BUDGET_CONFIG.enabled),
-    pollSeconds: normalizeBoundedInteger(budget.pollSeconds, DEFAULT_BUDGET_CONFIG.pollSeconds, 5, 3600),
+    enabled: normalizeBoolean(budget.enabled, fallback.enabled),
+    pollSeconds: normalizeBoundedInteger(budget.pollSeconds, fallback.pollSeconds, 5, 3600),
     pauseAt,
     resumeBelow,
-    syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, DEFAULT_BUDGET_CONFIG.syncDriftPct, 1, 100),
+    syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, fallback.syncDriftPct, 1, 100),
     parallel: {
-      minRemainingPct: normalizeBoundedInteger(parallel.minRemainingPct, DEFAULT_BUDGET_CONFIG.parallel.minRemainingPct, 1, 100),
-      timeWindowSec: normalizeBoundedInteger(parallel.timeWindowSec, DEFAULT_BUDGET_CONFIG.parallel.timeWindowSec, 60, 604800)
+      minRemainingPct: normalizeBoundedInteger(parallel.minRemainingPct, fallback.parallel.minRemainingPct, 1, 100),
+      timeWindowSec: normalizeBoundedInteger(parallel.timeWindowSec, fallback.parallel.timeWindowSec, 60, 604800)
     },
-    codexTierControl: normalizeBoolean(budget.codexTierControl, DEFAULT_BUDGET_CONFIG.codexTierControl) && codexTiers.full !== null,
+    codexTierControl: normalizeBoolean(budget.codexTierControl, fallback.codexTierControl) && codexTiers.full !== null,
     codexTiers
   };
 }
@@ -2786,7 +3029,7 @@ function applyBudgetEnvOverrides(budget, env = process.env) {
     codexTierControl: env.AGENTBRIDGE_BUDGET_CODEX_TIER_CONTROL ?? budget.codexTierControl,
     codexTiers: budget.codexTiers
   };
-  return normalizeBudgetConfig(overlay);
+  return normalizeBudgetConfig(overlay, budget);
 }
 function normalizeConfig(raw) {
   if (!isRecord(raw))
@@ -2821,15 +3064,59 @@ class ConfigService {
     return existsSync4(this.configPath);
   }
   load() {
+    let raw;
     try {
-      const raw = readFileSync2(this.configPath, "utf-8");
-      return normalizeConfig(JSON.parse(raw));
-    } catch {
-      return null;
+      raw = readFileSync2(this.configPath, "utf-8");
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        return { state: "absent" };
+      }
+      return { state: "corrupt", reason: `config.json is unreadable: ${err.message}` };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      return {
+        state: "corrupt",
+        reason: `config.json is not valid JSON: ${err.message}`
+      };
+    }
+    if (!isRecord(parsed)) {
+      return { state: "corrupt", reason: "config.json is not a JSON object" };
+    }
+    const violation = findShapeViolation(parsed);
+    if (violation) {
+      return { state: "corrupt", reason: `config.json is shape-invalid: ${violation}` };
     }
+    const config = normalizeConfig(parsed);
+    if (!config) {
+      return { state: "corrupt", reason: "config.json could not be normalized" };
+    }
+    return { state: "parsed", config };
+  }
+  loadOrDefault(log = NOOP_LOGGER) {
+    const result = this.load();
+    if (result.state === "parsed")
+      return result.config;
+    if (result.state === "corrupt") {
+      log(`config.json at ${this.configPath} is unusable (${result.reason}); ` + "falling back to defaults \u2014 your custom budget thresholds / idle-shutdown settings are NOT in effect. " + "Fix the file and restart to re-apply them.");
+    }
+    return structuredClone(DEFAULT_CONFIG);
   }
-  loadOrDefault() {
-    return this.load() ?? structuredClone(DEFAULT_CONFIG);
+  describeConfig() {
+    const result = this.load();
+    if (result.state === "absent") {
+      return { state: "absent", path: this.configPath, customValues: false };
+    }
+    if (result.state === "corrupt") {
+      return { state: "corrupt", path: this.configPath, reason: result.reason, customValues: false };
+    }
+    return {
+      state: "parsed",
+      path: this.configPath,
+      customValues: hasCustomDecisionValues(result.config)
+    };
   }
   save(config) {
     this.ensureConfigDir();
@@ -3082,6 +3369,23 @@ function computeBudgetState(claude, codex, cfg, now) {
 
 // src/budget/budget-coordinator.ts
 var RESET_FINGERPRINT_BUCKET_SEC = 600;
+var LOW_UTIL_PCT = 50;
+var NEAR_PAUSE_MARGIN_PCT = 10;
+var NEAR_WARN_UTIL_PCT = 75;
+var NEAR_THRESHOLD_POLL_MS = 60000;
+var PAUSED_POLL_MS = 15000;
+var RESET_WAKE_AFTER_SEC = 5;
+var RESET_RECENTLY_PASSED_WINDOW_SEC = 120;
+var REAL_BUDGET_POLL_SCHEDULER = {
+  setTimeout(callback, delayMs) {
+    return setTimeout(() => {
+      callback();
+    }, delayMs);
+  },
+  clearTimeout(timer) {
+    clearTimeout(timer);
+  }
+};
 var AGENT_LABEL2 = {
   claude: "Claude",
   codex: "Codex"
@@ -3104,6 +3408,55 @@ function matchingGateReset2(usage) {
     return 0;
   return Math.min(...candidates.map((window) => window.resetEpoch));
 }
+function maxPollDelayMs(config) {
+  return Math.max(0, config.pollSeconds * 1000);
+}
+function capDelay(delayMs, maxDelayMs) {
+  if (maxDelayMs <= 0)
+    return 0;
+  return Math.min(delayMs, maxDelayMs);
+}
+function usagePressure(usage) {
+  const readings = [usage?.claude, usage?.codex].filter((agentUsage) => agentUsage !== null && agentUsage !== undefined).flatMap((agentUsage) => [agentUsage.gateUtil, agentUsage.warnUtil]);
+  if (readings.length === 0)
+    return null;
+  return Math.max(...readings);
+}
+function usageResetEpochs(usage) {
+  return [usage?.claude, usage?.codex].filter((agentUsage) => agentUsage !== null && agentUsage !== undefined).flatMap((agentUsage) => [agentUsage.fiveHour?.resetEpoch ?? 0, agentUsage.weekly?.resetEpoch ?? 0]).filter((epoch) => epoch > 0);
+}
+function adaptiveBudgetPollDelayMs(input) {
+  const maxDelayMs = maxPollDelayMs(input.config);
+  if (input.paused)
+    return capDelay(PAUSED_POLL_MS, maxDelayMs);
+  const pressure = usagePressure(input.usage);
+  if (pressure === null || pressure < LOW_UTIL_PCT)
+    return maxDelayMs;
+  const nearPauseAt = Math.max(0, input.config.pauseAt - NEAR_PAUSE_MARGIN_PCT);
+  if (pressure >= nearPauseAt || pressure >= NEAR_WARN_UTIL_PCT) {
+    return capDelay(NEAR_THRESHOLD_POLL_MS, maxDelayMs);
+  }
+  return capDelay(maxDelayMs / 2, maxDelayMs);
+}
+function resetAlignedDelayMs(input, adaptiveDelayMs) {
+  const epochs = usageResetEpochs(input.usage);
+  if (epochs.length === 0)
+    return null;
+  const candidates = epochs.map((epoch) => {
+    if (epoch >= input.now)
+      return (epoch - input.now + RESET_WAKE_AFTER_SEC) * 1000;
+    if (input.now - epoch <= RESET_RECENTLY_PASSED_WINDOW_SEC)
+      return RESET_WAKE_AFTER_SEC * 1000;
+    return null;
+  }).filter((delayMs) => delayMs !== null && delayMs >= 0 && delayMs <= adaptiveDelayMs);
+  if (candidates.length === 0)
+    return null;
+  return Math.min(...candidates);
+}
+function nextBudgetPollDelayMs(input) {
+  const adaptiveDelayMs = adaptiveBudgetPollDelayMs(input);
+  return resetAlignedDelayMs(input, adaptiveDelayMs) ?? adaptiveDelayMs;
+}
 
 class BudgetCoordinator {
   source;
@@ -3111,6 +3464,7 @@ class BudgetCoordinator {
   emit;
   onPauseChange;
   now;
+  scheduler;
   log;
   timer = null;
   running = false;
@@ -3130,6 +3484,7 @@ class BudgetCoordinator {
     this.emit = options.emit;
     this.onPauseChange = options.onPauseChange;
     this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    this.scheduler = options.scheduler ?? REAL_BUDGET_POLL_SCHEDULER;
     this.log = options.log ?? (() => {});
   }
   async start() {
@@ -3143,7 +3498,7 @@ class BudgetCoordinator {
   stop() {
     this.running = false;
     if (this.timer) {
-      clearTimeout(this.timer);
+      this.scheduler.clearTimeout(this.timer);
       this.timer = null;
     }
   }
@@ -3177,11 +3532,17 @@ class BudgetCoordinator {
     if (!this.running)
       return;
     if (this.timer)
-      clearTimeout(this.timer);
-    const delayMs = Math.max(0, this.config.pollSeconds * 1000);
-    this.timer = setTimeout(() => {
+      this.scheduler.clearTimeout(this.timer);
+    const snapshotUsage = this.latestSnapshot ? { claude: this.latestSnapshot.claude, codex: this.latestSnapshot.codex } : null;
+    const delayMs = nextBudgetPollDelayMs({
+      config: this.config,
+      usage: snapshotUsage,
+      now: this.now(),
+      paused: this.isPaused()
+    });
+    this.timer = this.scheduler.setTimeout(() => {
       this.timer = null;
-      this.pollAndReschedule();
+      return this.pollAndReschedule();
     }, delayMs);
   }
   async pollAndReschedule() {
@@ -3553,38 +3914,44 @@ function identifyWindows(buckets) {
   const weeklyMatches = buckets.filter((bucket) => bucket.id.includes("seven_day") || bucket.id.includes("secondary_window"));
   let fiveHour = toWindow(pickHighestUtil(fiveHourMatches));
   let weekly = toWindow(pickHighestUtil(weeklyMatches));
+  let parsedVia = "id-match";
   const sorted = [...buckets].sort((a, b) => bucketSortKey(a) - bucketSortKey(b));
   if (!fiveHour && sorted.length > 0) {
     fiveHour = toWindow(sorted[0]);
+    parsedVia = "positional";
   }
   if (!weekly && sorted.length > 1) {
     const latestDistinct = [...sorted].reverse().find((bucket) => !sameBucketWindow(bucket, fiveHour));
     weekly = toWindow(latestDistinct);
+    if (latestDistinct)
+      parsedVia = "positional";
   }
-  return { fiveHour, weekly };
+  return { fiveHour, weekly, parsedVia };
 }
-function normalizeProbeResult(raw) {
-  const record = asRecord(raw);
-  if (!record)
-    return null;
+function normalizeTolerantProbeRecord(record) {
   const fetchedAt = numberOr(record.fetched_at ?? record.fetchedAt ?? record.now_epoch ?? record.nowEpoch, 0);
   const hasFiniteUtil = asFiniteNumber(record.util ?? record.hard_util ?? record.hardUtil) !== null || asFiniteNumber(record.warn_util ?? record.warnUtil) !== null;
   const gateUtil = clamp(numberOr(record.util ?? record.hard_util ?? record.hardUtil, 0), 0, 100);
   const warnUtil = clamp(numberOr(record.warn_util ?? record.warnUtil, gateUtil), 0, 100);
   const rawBuckets = Array.isArray(record.buckets) ? record.buckets : [];
   const buckets = rawBuckets.map((bucket) => normalizeBucket(bucket, fetchedAt)).filter((bucket) => bucket !== null);
+  let parsedVia = "id-match";
   if (buckets.length === 0 && hasFiniteUtil) {
     const topLevelBucket = normalizeTopLevelBucket(record, gateUtil, fetchedAt);
-    if (topLevelBucket)
+    if (topLevelBucket) {
       buckets.push(topLevelBucket);
+      parsedVia = "top-level";
+    }
   }
   const rateLimitedUntil = Math.max(0, numberOr(record.rate_limited_until ?? record.rateLimitedUntil, 0));
   const ok = record.ok === true;
   if (!ok && rateLimitedUntil <= 0 && buckets.length === 0)
     return null;
-  const { fiveHour, weekly } = identifyWindows(buckets);
+  const { fiveHour, weekly, parsedVia: bucketParsedVia } = identifyWindows(buckets);
   if (!fiveHour && !weekly && rateLimitedUntil === 0 && !hasFiniteUtil)
     return null;
+  if (parsedVia !== "top-level")
+    parsedVia = bucketParsedVia;
   return {
     ok,
     stale: record.stale === true,
@@ -3594,9 +3961,37 @@ function normalizeProbeResult(raw) {
     weekly,
     remaining: clamp(100 - gateUtil, 0, 100),
     rateLimitedUntil,
-    fetchedAt
+    fetchedAt,
+    parsedVia
   };
 }
+var PROBE_SCHEMA_PARSERS = {
+  "1": normalizeTolerantProbeRecord
+};
+function schemaVersionKey(record) {
+  const value = record.schema_version ?? record.schemaVersion;
+  if (typeof value === "number" && Number.isFinite(value))
+    return String(value);
+  if (typeof value === "string" && value.trim() !== "")
+    return value.trim();
+  return null;
+}
+function normalizeProbeResultWithDiagnostics(raw) {
+  const record = asRecord(raw);
+  if (!record)
+    return { usage: null, unknownSchemaVersion: null };
+  const schemaVersion = schemaVersionKey(record);
+  if (schemaVersion) {
+    const parser = PROBE_SCHEMA_PARSERS[schemaVersion];
+    if (parser)
+      return { usage: parser(record), unknownSchemaVersion: null };
+    return {
+      usage: normalizeTolerantProbeRecord(record),
+      unknownSchemaVersion: schemaVersion
+    };
+  }
+  return { usage: normalizeTolerantProbeRecord(record), unknownSchemaVersion: null };
+}
 function withTimeout(promise, timeoutMs) {
   let timer = null;
   const timeout = new Promise((_, reject) => {
@@ -3622,6 +4017,8 @@ class QuotaSource {
   log;
   now;
   degradedLogged = new Map;
+  positionalFallbackLogged = false;
+  unknownSchemaVersionsLogged = new Set;
   constructor(options = {}) {
     this.env = options.env ?? process.env;
     this.homeDir = options.homeDir ?? homedir2();
@@ -3683,7 +4080,9 @@ class QuotaSource {
           this.log(`budget probe output unparseable for ${agent}: ${candidate.command} \u2014 raw: ${text.slice(0, 200)}`);
           continue;
         }
-        const usage = normalizeProbeResult(parsed);
+        const normalized = normalizeProbeResultWithDiagnostics(parsed);
+        this.noteParserDiagnostics(agent, normalized);
+        const usage = normalized.usage;
         if (usage) {
           this.noteDegradation(agent, usage);
           return usage;
@@ -3695,6 +4094,16 @@ class QuotaSource {
     }
     return null;
   }
+  noteParserDiagnostics(agent, normalized) {
+    if (normalized.unknownSchemaVersion && !this.unknownSchemaVersionsLogged.has(normalized.unknownSchemaVersion)) {
+      this.unknownSchemaVersionsLogged.add(normalized.unknownSchemaVersion);
+      this.log(`unknown budget probe schema_version ${normalized.unknownSchemaVersion} for ${agent}; using tolerant legacy parser`);
+    }
+    if (normalized.usage?.parsedVia === "positional" && !this.positionalFallbackLogged) {
+      this.positionalFallbackLogged = true;
+      this.log(`budget probe positional bucket fallback for ${agent}: bucket ids did not identify quota windows; check probe schema_version/bucket ids`);
+    }
+  }
   noteDegradation(agent, usage) {
     const degraded = isDegradedUsage(usage, this.now());
     const wasDegraded = this.degradedLogged.get(agent) === true;
@@ -3711,6 +4120,127 @@ function createQuotaSource(options) {
   return new QuotaSource(options);
 }
 
+// src/idempotency-tracker.ts
+var DEFAULT_TOMBSTONE_TTL_MS = 20 * 60 * 1000;
+
+class IdempotencyTracker {
+  entries = new Map;
+  ttlMs;
+  now;
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_TOMBSTONE_TTL_MS;
+    this.now = options.now ?? Date.now;
+  }
+  get size() {
+    return this.entries.size;
+  }
+  check(threadId, key) {
+    const entry = this.getLive(threadId, key);
+    if (!entry)
+      return { duplicate: false };
+    if (entry.state.phase === "terminal") {
+      return { duplicate: true, code: "duplicate_terminal", state: entry.state };
+    }
+    return { duplicate: true, code: "duplicate_in_flight", state: entry.state };
+  }
+  peek(threadId, key) {
+    return this.getLive(threadId, key)?.state ?? null;
+  }
+  accept(threadId, key) {
+    if (this.getLive(threadId, key))
+      return;
+    this.entries.set(this.compositeKey(threadId, key), {
+      threadId,
+      state: { phase: "accepted" },
+      expiresAtMs: null,
+      timer: null
+    });
+  }
+  release(threadId, key) {
+    const composite = this.compositeKey(threadId, key);
+    const entry = this.entries.get(composite);
+    if (!entry || entry.state.phase === "terminal")
+      return;
+    this.entries.delete(composite);
+  }
+  markStarted(threadId, key, turnId) {
+    const entry = this.getLive(threadId, key);
+    if (!entry || entry.state.phase === "terminal")
+      return;
+    entry.state = { phase: "started", turnId };
+  }
+  markRejected(threadId, key) {
+    const entry = this.getLive(threadId, key);
+    if (!entry || entry.state.phase === "terminal")
+      return;
+    this.terminate(entry, "rejected");
+  }
+  completeTurn(turnId, threadId) {
+    for (const entry of this.entries.values()) {
+      if (entry.state.phase !== "started")
+        continue;
+      if (turnId !== null) {
+        if (entry.state.turnId !== turnId)
+          continue;
+      } else if (threadId !== undefined && entry.threadId !== threadId) {
+        continue;
+      }
+      this.terminate(entry, "completed");
+    }
+  }
+  terminateThread(threadId, outcome) {
+    for (const entry of this.entries.values()) {
+      if (entry.threadId !== threadId || entry.state.phase === "terminal")
+        continue;
+      this.terminate(entry, outcome);
+    }
+  }
+  terminateAll(outcome) {
+    for (const entry of this.entries.values()) {
+      if (entry.state.phase === "terminal")
+        continue;
+      this.terminate(entry, outcome);
+    }
+  }
+  dispose() {
+    for (const entry of this.entries.values()) {
+      if (entry.timer)
+        clearTimeout(entry.timer);
+    }
+    this.entries.clear();
+  }
+  compositeKey(threadId, key) {
+    return `${threadId}\x00${key}`;
+  }
+  getLive(threadId, key) {
+    const composite = this.compositeKey(threadId, key);
+    const entry = this.entries.get(composite);
+    if (!entry)
+      return null;
+    if (entry.expiresAtMs !== null && this.now() >= entry.expiresAtMs) {
+      if (entry.timer)
+        clearTimeout(entry.timer);
+      this.entries.delete(composite);
+      return null;
+    }
+    return entry;
+  }
+  terminate(entry, outcome) {
+    entry.state = { phase: "terminal", outcome };
+    entry.expiresAtMs = this.now() + this.ttlMs;
+    const timer = setTimeout(() => {
+      for (const [composite, candidate] of this.entries.entries()) {
+        if (candidate === entry) {
+          this.entries.delete(composite);
+          break;
+        }
+      }
+    }, this.ttlMs);
+    timer.unref?.();
+    entry.timer = timer;
+  }
+}
+
 // src/reply-required-tracker.ts
 class ReplyRequiredTracker {
   armed = false;
@@ -3918,9 +4448,9 @@ async function probeLiveness(target, options) {
 // src/daemon.ts
 var stateDir = new StateDirResolver;
 stateDir.ensure();
-var configService = new ConfigService;
-var config = configService.loadOrDefault();
 var processLogger = createProcessLogger({ component: "AgentBridgeDaemon", logFile: stateDir.logFile });
+var configService = new ConfigService;
+var config = configService.loadOrDefault(processLogger.log);
 var CODEX_APP_PORT = parseInt(process.env.CODEX_WS_PORT ?? String(config.codex.appPort), 10);
 var CODEX_PROXY_PORT = parseInt(process.env.CODEX_PROXY_PORT ?? String(config.codex.proxyPort), 10);
 var CONTROL_PORT = parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
@@ -3945,6 +4475,10 @@ var codexBootstrapped = false;
 var attentionWindowTimer = null;
 var inAttentionWindow = false;
 var replyTracker = new ReplyRequiredTracker;
+var idempotencyTracker = new IdempotencyTracker;
+var pendingTurnStarts = new Map;
+var pendingSteerDispatches = new Map;
+var BUSY_RETRY_ADVISORY_MS = 15000;
 var shuttingDown = false;
 var bootDeadlineTimer = null;
 var idleShutdownTimer = null;
@@ -4019,13 +4553,70 @@ codex.on("turnPhaseChanged", ({ phase, previous }) => {
   tryWriteStatusFile(`turnPhase:${phase}`);
   broadcastStatus();
 });
-codex.on("steerFailed", (reason) => {
+codex.on("steerFailed", ({ requestId, reason }) => {
   log(`Steer rejected by app-server: ${reason}`);
+  const dispatch = pendingSteerDispatches.get(requestId);
+  pendingSteerDispatches.delete(requestId);
+  if (dispatch?.idempotencyKey && dispatch.threadId) {
+    idempotencyTracker.release(dispatch.threadId, dispatch.idempotencyKey);
+    log(`Released idempotency key after steer failure (request ${requestId}) \u2014 same key is retryable again`);
+  }
   const advice = codex.turnInProgress ? "wait for it to finish (\u2705), then send normally" : "the turn has ended \u2014 resend as a normal reply";
   emitToClaude(systemMessage("system_steer_failed", `\u26A0\uFE0F Your steer message did NOT reach Codex (${reason}). The original turn continues unaffected \u2014 ${advice}.`));
 });
-codex.on("steerAccepted", () => {
+codex.on("steerAccepted", ({ requestId }) => {
   log("Steer accepted by app-server");
+  const dispatch = pendingSteerDispatches.get(requestId);
+  pendingSteerDispatches.delete(requestId);
+  if (dispatch?.requireReply) {
+    replyTracker.arm();
+    log("Reply required armed on steer-accept (steer-scoped expectation)");
+  }
+});
+codex.on("bridgeTurnStarted", ({ requestId, turnId }) => {
+  const pending = pendingTurnStarts.get(requestId);
+  if (!pending) {
+    log(`bridgeTurnStarted for unknown injection ${requestId} (turn ${turnId}) \u2014 correlation dropped`);
+    return;
+  }
+  pendingTurnStarts.delete(requestId);
+  log(`Bridge turn started: injection ${requestId} \u2192 turn ${turnId} (request ${pending.requestId})`);
+  if (pending.idempotencyKey) {
+    idempotencyTracker.markStarted(pending.threadId, pending.idempotencyKey, turnId);
+  }
+  if (attachedClaude) {
+    sendProtocolMessage(attachedClaude, {
+      type: "turn_started",
+      requestId: pending.requestId,
+      ...pending.idempotencyKey ? { idempotencyKey: pending.idempotencyKey } : {},
+      threadId: pending.threadId,
+      turnId
+    });
+  }
+});
+codex.on("bridgeTurnRejected", ({ requestId, error }) => {
+  const pending = pendingTurnStarts.get(requestId);
+  if (!pending)
+    return;
+  pendingTurnStarts.delete(requestId);
+  log(`Bridge turn rejected before start: injection ${requestId} (request ${pending.requestId}): ${error}`);
+  if (pending.idempotencyKey) {
+    idempotencyTracker.markRejected(pending.threadId, pending.idempotencyKey);
+  }
+});
+codex.on("turnIdCompleted", (turnId) => {
+  idempotencyTracker.completeTurn(turnId, codex.activeThreadId ?? undefined);
+});
+codex.on("turnTrackingReset", (reason) => {
+  idempotencyTracker.terminateAll("aborted");
+  if (pendingTurnStarts.size > 0) {
+    log(`Cleared ${pendingTurnStarts.size} pending turn-start correlation(s) on turn tracking reset (${reason})`);
+  }
+  if (pendingSteerDispatches.size > 0) {
+    log(`Cleared ${pendingSteerDispatches.size} pending steer dispatch(es) on turn tracking reset (${reason})`);
+  }
+  pendingTurnStarts.clear();
+  pendingSteerDispatches.clear();
 });
 codex.on("turnStarted", () => {
   log("Codex turn started");
@@ -4133,6 +4724,9 @@ codex.on("exit", (code) => {
   log(`Codex process exited (code ${code})`);
   codexBootstrapped = false;
   replyTracker.reset();
+  idempotencyTracker.terminateAll("aborted");
+  pendingTurnStarts.clear();
+  pendingSteerDispatches.clear();
   statusBuffer.flush("codex exited");
   tuiConnectionState.handleCodexExit();
   clearPendingClaudeDisconnect("Codex process exited");
@@ -4152,8 +4746,14 @@ function startControlServer() {
       if (url.pathname === "/readyz") {
         return Response.json(currentStatus(), { status: codexBootstrapped ? 200 : 503 });
       }
-      if (url.pathname === "/ws" && server.upgrade(req, { data: { clientId: 0, attached: false, lastPongAt: Date.now(), pongCount: 0, pendingBackpressure: [] } })) {
-        return;
+      if (url.pathname === "/ws") {
+        if (!isAllowedWsUpgrade(req)) {
+          log("Rejected WS upgrade on control port: Origin header present (possible CSWSH)");
+          return wsOriginRejectedResponse();
+        }
+        if (server.upgrade(req, { data: { clientId: 0, attached: false, lastPongAt: Date.now(), pongCount: 0, pendingBackpressure: [] } })) {
+          return;
+        }
       }
       return new Response("AgentBridge daemon");
     },
@@ -4228,98 +4828,217 @@ function handleControlMessage(ws, raw) {
       });
       return;
     case "claude_to_codex": {
-      if (message.message.source !== "claude") {
-        sendProtocolMessage(ws, {
-          type: "claude_to_codex_result",
-          requestId: message.requestId,
+      handleClaudeToCodex(ws, message).catch((err) => {
+        log(`handleClaudeToCodex threw for request ${message.requestId}: ${err?.message ?? err}`);
+        sendClaudeToCodexResult(ws, message.requestId, {
           success: false,
-          error: "Invalid message source"
-        });
-        return;
-      }
-      if (!tuiConnectionState.canReply()) {
-        sendProtocolMessage(ws, {
-          type: "claude_to_codex_result",
-          requestId: message.requestId,
-          success: false,
-          error: "Codex is not ready. Wait for TUI to connect and create a thread."
-        });
-        return;
-      }
-      if (budgetCoordinator?.isGateClosed()) {
-        const reason = budgetPauseGateError();
-        log(`Injection rejected by budget pause gate`);
-        sendProtocolMessage(ws, {
-          type: "claude_to_codex_result",
-          requestId: message.requestId,
-          success: false,
-          error: reason
+          code: "internal_error",
+          error: `Internal bridge error: ${err?.message ?? err}`
         });
+      });
+      return;
+    }
+  }
+}
+function sendClaudeToCodexResult(ws, requestId, opts) {
+  sendProtocolMessage(ws, {
+    type: "claude_to_codex_result",
+    requestId,
+    success: opts.success,
+    ...opts.error !== undefined ? { error: opts.error } : {},
+    ok: opts.success,
+    ...opts.code !== undefined ? { code: opts.code } : {},
+    phase: codex.turnPhase,
+    ...opts.retryAfterMs !== undefined ? { retryAfterMs: opts.retryAfterMs } : {}
+  });
+}
+function describeDuplicate(dup) {
+  if (dup.code === "duplicate_terminal") {
+    const outcome = dup.state.phase === "terminal" ? dup.state.outcome : "unknown";
+    return `Duplicate idempotency_key: the original message already reached a terminal state (${outcome}) ` + `and was NOT re-injected. Use a fresh key to send a genuinely new message.`;
+  }
+  const detail = dup.state.phase === "started" ? `already running as turn ${dup.state.turnId}` : "still in flight";
+  return `Duplicate idempotency_key: a message with this key is ${detail} \u2014 NOT re-injected. ` + `Wait for its outcome, or use a fresh key for a genuinely new message.`;
+}
+function waitForInterruptOutcome(turnIds) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const abort = new AbortController;
+    const finish = (result) => {
+      if (settled)
         return;
+      settled = true;
+      codex.off("interruptFailed", onFailed);
+      abort.abort();
+      resolve(result);
+    };
+    const onFailed = (reason) => finish({ ok: false, code: "interrupt_rejected", reason });
+    codex.on("interruptFailed", onFailed);
+    codex.waitForTurnsTerminal(turnIds, undefined, abort.signal).then((result) => {
+      if (result.ok) {
+        finish({ ok: true });
+      } else if (result.code === "interrupt_timeout") {
+        finish({ ok: false, code: "interrupt_timeout" });
       }
-      const requireReply = !!message.requireReply;
-      let contentToSend = message.message.content;
-      if (requireReply) {
-        contentToSend += REPLY_REQUIRED_INSTRUCTION;
-      }
-      log(`Forwarding Claude \u2192 Codex (${message.message.content.length} chars, requireReply=${requireReply})`);
-      const tierOverrides = BUDGET_CONFIG.codexTierControl ? budgetCoordinator?.getCodexTurnOverrides() ?? undefined : undefined;
-      if (codex.turnInProgress && message.onBusy === "steer") {
-        if (requireReply) {
-          sendProtocolMessage(ws, {
-            type: "claude_to_codex_result",
-            requestId: message.requestId,
-            success: false,
-            error: 'require_reply is not supported together with on_busy="steer" yet. Send the steer without require_reply, or wait for the turn to finish.'
-          });
-          return;
-        }
-        const steerContent = `[STEER from Claude]
+    });
+  });
+}
+async function handleClaudeToCodex(ws, message) {
+  if (message.message.source !== "claude") {
+    sendClaudeToCodexResult(ws, message.requestId, {
+      success: false,
+      code: "invalid_source",
+      error: "Invalid message source"
+    });
+    return;
+  }
+  const idempotencyKey = typeof message.idempotencyKey === "string" && message.idempotencyKey.length > 0 ? message.idempotencyKey : undefined;
+  if (idempotencyKey && codex.activeThreadId) {
+    const dup = idempotencyTracker.check(codex.activeThreadId, idempotencyKey);
+    if (dup.duplicate) {
+      log(`Rejected duplicate idempotency key (${dup.code})`);
+      sendClaudeToCodexResult(ws, message.requestId, {
+        success: false,
+        code: dup.code,
+        error: describeDuplicate(dup)
+      });
+      return;
+    }
+  }
+  if (!tuiConnectionState.canReply()) {
+    sendClaudeToCodexResult(ws, message.requestId, {
+      success: false,
+      code: "no_thread",
+      error: "Codex is not ready. Wait for TUI to connect and create a thread."
+    });
+    return;
+  }
+  if (budgetCoordinator?.isGateClosed()) {
+    const reason = budgetPauseGateError();
+    log(`Injection rejected by budget pause gate`);
+    const resumeAfterEpoch2 = budgetCoordinator?.getSnapshot()?.resumeAfterEpoch ?? null;
+    const retryAfterMs = resumeAfterEpoch2 !== null ? Math.max(0, resumeAfterEpoch2 * 1000 - Date.now()) : undefined;
+    sendClaudeToCodexResult(ws, message.requestId, {
+      success: false,
+      code: "budget_paused",
+      error: reason,
+      ...retryAfterMs !== undefined ? { retryAfterMs } : {}
+    });
+    return;
+  }
+  const requireReply = !!message.requireReply;
+  let contentToSend = message.message.content;
+  if (requireReply) {
+    contentToSend += REPLY_REQUIRED_INSTRUCTION;
+  }
+  log(`Forwarding Claude \u2192 Codex (${message.message.content.length} chars, requireReply=${requireReply})`);
+  const tierOverrides = BUDGET_CONFIG.codexTierControl ? budgetCoordinator?.getCodexTurnOverrides() ?? undefined : undefined;
+  if (codex.turnInProgress && message.onBusy === "steer") {
+    const steerContent = `[STEER from Claude]
 ` + `Mid-turn update for the current Codex turn. Integrate if relevant; do not restart work unless explicitly requested.
 
-` + message.message.content;
-        const steered = codex.steerMessage(steerContent);
-        log(`Steer ${steered ? "transport-accepted" : "failed"} (${message.message.content.length} chars)`);
-        if (steered) {
-          clearAttentionWindow();
+` + contentToSend;
+    const steerTurnId = codex.steerableTurnId;
+    const steerThreadId = codex.activeThreadId;
+    const steerRequestId = codex.steerMessage(steerContent);
+    const steered = steerRequestId !== null;
+    log(`Steer ${steered ? "transport-accepted" : "failed"} (${message.message.content.length} chars, requireReply=${requireReply})`);
+    if (steered) {
+      clearAttentionWindow();
+      pendingSteerDispatches.set(steerRequestId, {
+        requireReply,
+        ...idempotencyKey ? { idempotencyKey } : {},
+        ...steerThreadId ? { threadId: steerThreadId } : {}
+      });
+      if (idempotencyKey && steerThreadId) {
+        idempotencyTracker.accept(steerThreadId, idempotencyKey);
+        if (steerTurnId) {
+          idempotencyTracker.markStarted(steerThreadId, idempotencyKey, steerTurnId);
         }
-        const steerFailureAdvice = codex.turnInProgress ? "Steer failed: the running turn cannot be steered right now \u2014 wait for it to finish (\u2705), then send normally." : "Steer failed: the turn may have just ended or the connection dropped \u2014 retry as a normal reply.";
-        sendProtocolMessage(ws, {
-          type: "claude_to_codex_result",
-          requestId: message.requestId,
-          success: steered,
-          error: steered ? undefined : steerFailureAdvice
-        });
-        return;
-      }
-      const injected = codex.injectMessage(contentToSend, tierOverrides);
-      if (!injected) {
-        const reason = codex.turnInProgress ? 'Codex is busy executing a turn. Options: wait for it to finish, or retry with on_busy="steer" to feed this message into the running turn without interrupting it.' : "Injection failed: no active thread or WebSocket not connected.";
-        log(`Injection rejected: ${reason}`);
-        sendProtocolMessage(ws, {
-          type: "claude_to_codex_result",
-          requestId: message.requestId,
-          success: false,
-          error: reason
-        });
-        return;
-      }
-      if (tierOverrides) {
-        budgetCoordinator?.notifyOverridesDelivered();
       }
-      if (requireReply) {
-        replyTracker.arm();
-        log(`Reply required flag set for this message`);
+    }
+    const steerFailureAdvice = codex.turnInProgress ? "Steer failed: the running turn cannot be steered right now \u2014 wait for it to finish (\u2705), then send normally." : "Steer failed: the turn may have just ended or the connection dropped \u2014 retry as a normal reply.";
+    sendClaudeToCodexResult(ws, message.requestId, {
+      success: steered,
+      ...steered ? {} : { code: "steer_failed", error: steerFailureAdvice }
+    });
+    return;
+  }
+  if (codex.turnInProgress && message.onBusy === "interrupt") {
+    const interruptThreadId = codex.activeThreadId;
+    if (idempotencyKey && interruptThreadId) {
+      idempotencyTracker.accept(interruptThreadId, idempotencyKey);
+    }
+    const releaseInterruptKey = () => {
+      if (idempotencyKey && interruptThreadId) {
+        idempotencyTracker.release(interruptThreadId, idempotencyKey);
       }
-      clearAttentionWindow();
-      sendProtocolMessage(ws, {
-        type: "claude_to_codex_result",
-        requestId: message.requestId,
-        success: true
+    };
+    const interrupted = codex.interruptActiveTurns();
+    if (!interrupted.ok) {
+      releaseInterruptKey();
+      log(`Interrupt unavailable: ${interrupted.error}`);
+      sendClaudeToCodexResult(ws, message.requestId, {
+        success: false,
+        code: interrupted.code,
+        error: `Interrupt failed (${interrupted.error}). The original turn keeps running \u2014 ` + `your message was NOT injected. Wait for \u2705, or retry with on_busy="steer".`
       });
       return;
     }
+    log(`Interrupt dispatched for turn(s) ${interrupted.turnIds.join(", ")} \u2014 waiting for terminal boundary`);
+    const outcome = await waitForInterruptOutcome(interrupted.turnIds);
+    if (!outcome.ok) {
+      releaseInterruptKey();
+      const error = outcome.code === "interrupt_rejected" ? `Interrupt was rejected by the app-server (${outcome.reason ?? "unknown reason"}). ` + `The original turn keeps running \u2014 your message was NOT injected. ` + `Wait for \u2705, or retry with on_busy="steer".` : `Interrupt did not reach a terminal boundary in time. The turn MAY still be running \u2014 ` + `do not assume it stopped. Your message was NOT injected (this avoids a double-turn race); ` + `check for \u2705/\u26A0\uFE0F notices before retrying.`;
+      log(`Interrupt failed (${outcome.code})`);
+      sendClaudeToCodexResult(ws, message.requestId, {
+        success: false,
+        code: outcome.code,
+        error
+      });
+      return;
+    }
+    log("Interrupt reached terminal boundary \u2014 injecting the message as a new turn");
+    if (interruptThreadId && codex.activeThreadId !== interruptThreadId) {
+      releaseInterruptKey();
+    }
+  }
+  const injectThreadId = codex.activeThreadId;
+  const injectionId = codex.injectMessage(contentToSend, tierOverrides);
+  if (injectionId === null) {
+    if (idempotencyKey && injectThreadId) {
+      idempotencyTracker.release(injectThreadId, idempotencyKey);
+    }
+    const busy = codex.turnInProgress;
+    const reason = busy ? 'Codex is busy executing a turn. Options: wait for it to finish, retry with on_busy="steer" to feed this message into the running turn without interrupting it, or retry with on_busy="interrupt" to stop the current turn and start a new one with this message.' : "Injection failed: no active thread or WebSocket not connected.";
+    log(`Injection rejected: ${reason}`);
+    sendClaudeToCodexResult(ws, message.requestId, {
+      success: false,
+      code: busy ? "busy_reject" : "no_thread",
+      error: reason,
+      ...busy ? { retryAfterMs: BUSY_RETRY_ADVISORY_MS } : {}
+    });
+    return;
+  }
+  if (tierOverrides) {
+    budgetCoordinator?.notifyOverridesDelivered();
+  }
+  if (requireReply) {
+    replyTracker.arm();
+    log(`Reply required flag set for this message`);
+  }
+  clearAttentionWindow();
+  if (injectThreadId) {
+    if (idempotencyKey) {
+      idempotencyTracker.accept(injectThreadId, idempotencyKey);
+    }
+    pendingTurnStarts.set(injectionId, {
+      requestId: message.requestId,
+      ...idempotencyKey ? { idempotencyKey } : {},
+      threadId: injectThreadId
+    });
   }
+  sendClaudeToCodexResult(ws, message.requestId, { success: true });
 }
 async function attachClaude(ws, identity) {
   const occupant = attachedClaude;
@@ -4707,6 +5426,7 @@ function shutdown(reason, exitCode = 0) {
   log(`Shutting down daemon (${reason})...`);
   clearBootDeadline();
   stopBudgetCoordinator();
+  idempotencyTracker.dispose();
   tuiConnectionState.dispose(`daemon shutdown (${reason})`);
   clearPendingClaudeDisconnect(`daemon shutdown (${reason})`);
   controlServer?.stop();