@raysonmeng/agentbridge 0.1.11 → 0.1.12

package/dist/cli.js

@@ -120,7 +120,7 @@ function parsePositiveIntEnv(name, fallback, log = () => {}, env = process.env)
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@raysonmeng/agentbridge",
-    version: "0.1.11",
+    version: "0.1.12",
     description: "Bridge between Claude Code and Codex \u2014 bidirectional agent communication via MCP Channel + JSON-RPC",
     type: "module",
     packageManager: "bun@1.3.11",
@@ -323,6 +323,48 @@ import { join as join2 } from "path";
 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;
@@ -358,35 +400,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
   };
 }
@@ -423,15 +465,59 @@ class ConfigService {
     return existsSync2(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() {
-    return this.load() ?? structuredClone(DEFAULT_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);
+  }
+  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();
@@ -456,11 +542,11 @@ class ConfigService {
     }
   }
 }
-var DEFAULT_BUDGET_CONFIG, DEFAULT_CONFIG, CONFIG_DIR = ".agentbridge", CONFIG_FILE = "config.json";
+var DEFAULT_BUDGET_CONFIG, DEFAULT_CONFIG, CONFIG_DIR = ".agentbridge", CONFIG_FILE = "config.json", NOOP_LOGGER = () => {};
 var init_config_service = __esm(() => {
   DEFAULT_BUDGET_CONFIG = {
     enabled: true,
-    pollSeconds: 60,
+    pollSeconds: 300,
     pauseAt: 90,
     resumeBelow: 30,
     syncDriftPct: 10,
@@ -513,6 +599,30 @@ function registerMarketplace(marketplaceRoot) {
 }
 var init_pkg_root = () => {};
 
+// src/cli/plugin-cache.ts
+import { existsSync as existsSync4 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join4, resolve } from "path";
+function pluginCacheRoot(home = homedir2()) {
+  return join4(home, ".claude", "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME);
+}
+function isInsideRepoCheckout(projectRoot) {
+  const buildScript = resolve(projectRoot, "scripts", "build-bundles.mjs");
+  return existsSync4(buildScript);
+}
+function shouldWarnMissingPluginCache(cacheExists) {
+  return !cacheExists;
+}
+var MARKETPLACE_STEPS;
+var init_plugin_cache = __esm(() => {
+  init_cli();
+  MARKETPLACE_STEPS = [
+    `/plugin marketplace add raysonmeng/agent-bridge`,
+    `/plugin install ${PLUGIN_NAME}@${MARKETPLACE_NAME}`,
+    `/reload-plugins`
+  ];
+});
+
 // src/marker-section.ts
 function upsertMarkedSection(content, sectionId, section) {
   const startMarker = MARKER_START(sectionId);
@@ -649,11 +759,12 @@ var exports_init = {};
 __export(exports_init, {
   writeCollaborationSections: () => writeCollaborationSections,
   runInit: () => runInit,
+  pluginInstallFallbackGuidance: () => pluginInstallFallbackGuidance,
   compareVersions: () => compareVersions
 });
 import { execSync, execFileSync as execFileSync2 } from "child_process";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 async function runInit() {
   console.log(`AgentBridge Init
 `);
@@ -681,25 +792,54 @@ async function runInit() {
   }
   console.log("");
   console.log("Installing AgentBridge plugin...");
+  let pluginInstalled = false;
   try {
-    registerMarketplace(findPackageRoot());
+    const packageRoot = findPackageRoot();
+    registerMarketplace(packageRoot);
     execFileSync2("claude", ["plugin", "install", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`], {
       stdio: "inherit"
     });
     console.log("  Plugin installed successfully.");
+    pluginInstalled = true;
   } catch {
     console.log("  Plugin install skipped (marketplace registration or install failed).");
-    console.log("  You can install it later with:");
-    console.log(`    abg dev   # registers marketplace and installs plugin`);
+    for (const line of pluginInstallFallbackGuidance(detectRepoCheckout())) {
+      console.log(line);
+    }
   }
   console.log("");
-  console.log(`Setup complete!
+  if (pluginInstalled) {
+    console.log(`Setup complete!
 `);
+  } else {
+    console.log(`Setup incomplete \u2014 plugin not installed.
+`);
+    process.exitCode = 1;
+  }
   console.log("Next steps:");
   console.log("  1. If Claude Code is already running, execute /reload-plugins in your session");
   console.log("  2. Start Claude Code:  agentbridge claude");
   console.log("  3. Start Codex TUI:    agentbridge codex");
 }
+function detectRepoCheckout() {
+  try {
+    return isInsideRepoCheckout(findPackageRoot());
+  } catch {
+    return false;
+  }
+}
+function pluginInstallFallbackGuidance(insideRepo) {
+  if (insideRepo) {
+    return [
+      "  You can install it later with:",
+      "    abg dev   # registers marketplace and installs plugin"
+    ];
+  }
+  return [
+    "  Install the plugin from Claude Code with these steps:",
+    ...MARKETPLACE_STEPS.map((step) => `    ${step}`)
+  ];
+}
 function checkBun() {
   try {
     const version = execSync("bun --version", { encoding: "utf-8" }).trim();
@@ -745,8 +885,8 @@ function checkCodex() {
 function writeCollaborationSections(projectRoot) {
   const results = [];
   const files = [
-    { name: "CLAUDE.md", path: join4(projectRoot, "CLAUDE.md"), section: CLAUDE_MD_SECTION },
-    { name: "AGENTS.md", path: join4(projectRoot, "AGENTS.md"), section: AGENTS_MD_SECTION }
+    { name: "CLAUDE.md", path: join5(projectRoot, "CLAUDE.md"), section: CLAUDE_MD_SECTION },
+    { name: "AGENTS.md", path: join5(projectRoot, "AGENTS.md"), section: AGENTS_MD_SECTION }
   ];
   for (const { name, path, section } of files) {
     let existing = "";
@@ -781,6 +921,7 @@ var init_init = __esm(() => {
   init_config_service();
   init_cli();
   init_pkg_root();
+  init_plugin_cache();
   init_version_utils();
 });
 
@@ -790,19 +931,17 @@ __export(exports_dev, {
   runDev: () => runDev
 });
 import { execFileSync as execFileSync3, spawnSync } from "child_process";
-import { resolve } from "path";
-import { existsSync as existsSync4, cpSync, rmSync } from "fs";
-import { homedir as homedir2 } from "os";
+import { resolve as resolve2 } from "path";
+import { existsSync as existsSync5, cpSync, rmSync } from "fs";
 async function runDev(args = []) {
   console.log(`AgentBridge Dev Setup
 `);
   const skipBuild = args.includes("--skip-build");
   const projectRoot = findPackageRoot();
-  const marketplacePath = resolve(projectRoot, ".claude-plugin", "marketplace.json");
-  const pluginDir = resolve(projectRoot, "plugins", "agentbridge");
-  const pluginManifest = resolve(pluginDir, ".claude-plugin", "plugin.json");
-  const buildScript = resolve(projectRoot, "scripts", "build-bundles.mjs");
-  if (!existsSync4(buildScript)) {
+  const marketplacePath = resolve2(projectRoot, ".claude-plugin", "marketplace.json");
+  const pluginDir = resolve2(projectRoot, "plugins", "agentbridge");
+  const pluginManifest = resolve2(pluginDir, ".claude-plugin", "plugin.json");
+  if (!isInsideRepoCheckout(projectRoot)) {
     console.error("  ERROR: 'agentbridge dev' must run inside an AgentBridge repository checkout \u2014");
     console.error("  the published package does not ship the build scripts.");
     console.error("");
@@ -839,12 +978,12 @@ async function runDev(args = []) {
     console.log(`  \u2713 Plugin built successfully
 `);
   }
-  if (!existsSync4(pluginManifest)) {
+  if (!existsSync5(pluginManifest)) {
     console.error(`  ERROR: Plugin manifest not found at ${pluginManifest}`);
     console.error("  Run 'bun run build:plugin' first, or check your working tree.");
     process.exit(1);
   }
-  if (!existsSync4(marketplacePath)) {
+  if (!existsSync5(marketplacePath)) {
     console.error(`  ERROR: Marketplace manifest not found at ${marketplacePath}`);
     process.exit(1);
   }
@@ -873,12 +1012,12 @@ Installing plugin...`);
   }
   console.log(`
 Syncing local plugin to cache...`);
-  const cacheDir = resolve(homedir2(), ".claude", "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME);
-  if (existsSync4(cacheDir)) {
+  const cacheDir = pluginCacheRoot();
+  if (existsSync5(cacheDir)) {
     const versionDirs = Bun.spawnSync(["ls", cacheDir]).stdout.toString().trim().split(`
 `).filter(Boolean);
     for (const ver of versionDirs) {
-      const targetDir = resolve(cacheDir, ver);
+      const targetDir = resolve2(cacheDir, ver);
       rmSync(targetDir, { recursive: true, force: true });
       cpSync(pluginDir, targetDir, { recursive: true });
       console.log(`  Synced to ${targetDir}`);
@@ -898,15 +1037,23 @@ Syncing local plugin to cache...`);
 var init_dev = __esm(() => {
   init_cli();
   init_pkg_root();
+  init_plugin_cache();
 });
 
 // src/control-protocol.ts
 var CLOSE_CODE_REPLACED = 4001, CLOSE_CODE_EVICTED_STALE = 4002, CLOSE_CODE_PROBE_IN_PROGRESS = 4003, CLOSE_CODE_PAIR_MISMATCH = 4004;
 
+// src/interrupt-timing.ts
+var CLIENT_REPLY_TIMEOUT_MS = 15000, INTERRUPT_CLIENT_MARGIN_MS = 2000, MAX_INTERRUPT_TIMEOUT_MS;
+var init_interrupt_timing = __esm(() => {
+  MAX_INTERRUPT_TIMEOUT_MS = CLIENT_REPLY_TIMEOUT_MS - INTERRUPT_CLIENT_MARGIN_MS;
+});
+
 // src/daemon-client.ts
 import { EventEmitter } from "events";
 var nextSocketId = 0, DaemonClient;
 var init_daemon_client = __esm(() => {
+  init_interrupt_timing();
   DaemonClient = class DaemonClient extends EventEmitter {
     url;
     options;
@@ -933,7 +1080,7 @@ var init_daemon_client = __esm(() => {
         this.ws = null;
       }
       const socketId = ++nextSocketId;
-      await new Promise((resolve2, reject) => {
+      await new Promise((resolve3, reject) => {
         const ws = new WebSocket(this.url);
         let settled = false;
         ws.onopen = () => {
@@ -942,7 +1089,7 @@ var init_daemon_client = __esm(() => {
           this.wsId = socketId;
           this.attachSocketHandlers(ws, socketId);
           this.log(`ws#${socketId} opened and attached`);
-          resolve2();
+          resolve3();
         };
         ws.onerror = () => {
           if (settled)
@@ -968,7 +1115,7 @@ var init_daemon_client = __esm(() => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
         return null;
       }
-      return await new Promise((resolve2) => {
+      return await new Promise((resolve3) => {
         let settled = false;
         let timer = null;
         const cleanup = () => {
@@ -985,7 +1132,7 @@ var init_daemon_client = __esm(() => {
         };
         const finish = (value) => {
           cleanup();
-          resolve2(value);
+          resolve3(value);
         };
         const onStatus = (status) => finish(status);
         const onRejected = () => finish(null);
@@ -1007,7 +1154,7 @@ var init_daemon_client = __esm(() => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
         return { connected: false, alive: false };
       }
-      return await new Promise((resolve2) => {
+      return await new Promise((resolve3) => {
         let settled = false;
         let timer = null;
         const finish = (value) => {
@@ -1019,7 +1166,7 @@ var init_daemon_client = __esm(() => {
           this.off("incumbentStatus", onStatus);
           this.off("disconnect", onDisconnect);
           this.off("rejected", onRejected);
-          resolve2(value);
+          resolve3(value);
         };
         const onStatus = (s) => finish(s);
         const onDisconnect = () => finish({ connected: false, alive: false });
@@ -1047,23 +1194,24 @@ var init_daemon_client = __esm(() => {
       this.ws = null;
       this.rejectPendingReplies("Daemon connection closed");
     }
-    async sendReply(message, requireReply, onBusy) {
+    async sendReply(message, requireReply, onBusy, idempotencyKey) {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
         return { success: false, error: "AgentBridge daemon is not connected." };
       }
       const requestId = `reply_${Date.now()}_${this.nextRequestId++}`;
-      return new Promise((resolve2) => {
+      return new Promise((resolve3) => {
         const timer = setTimeout(() => {
           this.pendingReplies.delete(requestId);
-          resolve2({ success: false, error: "Timed out waiting for AgentBridge daemon reply." });
-        }, 15000);
-        this.pendingReplies.set(requestId, { resolve: resolve2, timer });
+          resolve3({ success: false, error: "Timed out waiting for AgentBridge daemon reply." });
+        }, CLIENT_REPLY_TIMEOUT_MS);
+        this.pendingReplies.set(requestId, { resolve: resolve3, timer });
         this.send({
           type: "claude_to_codex",
           requestId,
           message,
           ...requireReply ? { requireReply: true } : {},
-          ...onBusy && onBusy !== "reject" ? { onBusy } : {}
+          ...onBusy && onBusy !== "reject" ? { onBusy } : {},
+          ...idempotencyKey ? { idempotencyKey } : {}
         });
       });
     }
@@ -1086,9 +1234,23 @@ var init_daemon_client = __esm(() => {
               return;
             clearTimeout(pending.timer);
             this.pendingReplies.delete(message.requestId);
-            pending.resolve({ success: message.success, error: message.error });
+            pending.resolve({
+              success: message.success,
+              error: message.error,
+              ...message.code !== undefined ? { code: message.code } : {},
+              ...message.phase !== undefined ? { phase: message.phase } : {},
+              ...message.retryAfterMs !== undefined ? { retryAfterMs: message.retryAfterMs } : {}
+            });
             return;
           }
+          case "turn_started":
+            this.emit("turnStarted", {
+              requestId: message.requestId,
+              ...message.idempotencyKey !== undefined ? { idempotencyKey: message.idempotencyKey } : {},
+              threadId: message.threadId,
+              turnId: message.turnId
+            });
+            return;
           case "status":
             this.emit("status", message.status);
             return;
@@ -1165,8 +1327,8 @@ function formatBuildInfo(build) {
 var BUILD_INFO;
 var init_build_info = __esm(() => {
   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("dist"),
     contractVersion: defineNumber(1, CONTRACT_VERSION)
   });
@@ -1332,8 +1494,50 @@ var init_process_lifecycle = __esm(() => {
 
 // src/daemon-lifecycle.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync5, readFileSync as readFileSync4, statSync, unlinkSync, writeFileSync as writeFileSync4, openSync, closeSync, constants } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, statSync, unlinkSync, writeFileSync as writeFileSync4, openSync, closeSync, constants } from "fs";
 import { fileURLToPath } from "url";
+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;
@@ -1366,52 +1570,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);
@@ -1441,14 +1630,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 {
@@ -1476,7 +1668,7 @@ class DaemonLifecycle {
     for (let attempt = 0;attempt < maxRetries; attempt++) {
       if (await this.isHealthy())
         return;
-      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      await new Promise((resolve3) => setTimeout(resolve3, delayMs));
     }
     throw new Error(`Timed out waiting for AgentBridge daemon health on ${this.healthUrl}`);
   }
@@ -1492,7 +1684,7 @@ class DaemonLifecycle {
     for (let attempt = 0;attempt < maxRetries; attempt++) {
       if (await this.isReady())
         return;
-      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      await new Promise((resolve3) => setTimeout(resolve3, delayMs));
     }
     throw new Error(`Timed out waiting for AgentBridge daemon readiness on ${this.readyUrl}`);
   }
@@ -1500,11 +1692,15 @@ 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;
         }
       }
-      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      await new Promise((resolve3) => setTimeout(resolve3, delayMs));
     }
     throw new Error(`Timed out waiting for AgentBridge daemon readiness+identity on ${this.readyUrl} (control port ${this.controlPort})`);
   }
@@ -1558,7 +1754,7 @@ class DaemonLifecycle {
     } catch {}
   }
   wasKilled() {
-    return existsSync5(this.stateDir.killedFile);
+    return existsSync6(this.stateDir.killedFile);
   }
   launch() {
     this.stateDir.ensure();
@@ -1582,13 +1778,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;
@@ -1601,6 +1800,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 {
@@ -1693,7 +1896,7 @@ class DaemonLifecycle {
         this.cleanup();
         return true;
       }
-      await new Promise((resolve2) => setTimeout(resolve2, 200));
+      await new Promise((resolve3) => setTimeout(resolve3, 200));
     }
     this.log(`Daemon pid ${pid} did not stop gracefully, sending SIGKILL`);
     try {
@@ -1731,7 +1934,7 @@ var init_daemon_lifecycle = __esm(() => {
 import { execFileSync as execFileSync5 } from "child_process";
 import {
   closeSync as closeSync2,
-  existsSync as existsSync6,
+  existsSync as existsSync7,
   fsyncSync,
   linkSync,
   lstatSync,
@@ -1749,7 +1952,7 @@ import {
 import { createServer } from "net";
 import { createHash, randomUUID } from "crypto";
 import { hostname, userInfo } from "os";
-import { basename as basename2, join as join5, resolve as resolve2, sep } from "path";
+import { basename as basename2, join as join6, resolve as resolve3, sep } from "path";
 function portsForSlot(slot) {
   if (!Number.isInteger(slot) || slot < 0) {
     throw new PairError("PAIR_ID_INVALID", `Invalid slot: ${slot}`);
@@ -1787,14 +1990,14 @@ function pickLowestFreeSlot(entries) {
   return slot;
 }
 function pairsDir(base) {
-  return join5(base, "pairs");
+  return join6(base, "pairs");
 }
 function registryPath(base) {
-  return join5(pairsDir(base), REGISTRY_FILE_NAME);
+  return join6(pairsDir(base), REGISTRY_FILE_NAME);
 }
 function readRegistry(base) {
   const path = registryPath(base);
-  if (!existsSync6(path))
+  if (!existsSync7(path))
     return { version: 1, pairs: [] };
   let parsed;
   try {
@@ -1844,7 +2047,7 @@ function writeRegistry(base, reg) {
   renameSync(tmp, target);
 }
 function lockFilePath(base) {
-  return join5(pairsDir(base), LOCK_FILE_NAME);
+  return join6(pairsDir(base), LOCK_FILE_NAME);
 }
 function readLockOwner(lockFile) {
   try {
@@ -1878,7 +2081,7 @@ function safeUid() {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function lockIsStale(lockFile) {
   const owner = readLockOwner(lockFile);
@@ -1990,8 +2193,8 @@ async function withRegistryLock(base, fn) {
   }
 }
 function detectLegacyRootDaemon(base) {
-  const rootPidFile = join5(base, "daemon.pid");
-  if (!existsSync6(rootPidFile))
+  const rootPidFile = join6(base, "daemon.pid");
+  if (!existsSync7(rootPidFile))
     return null;
   let pid;
   try {
@@ -2005,11 +2208,11 @@ function detectLegacyRootDaemon(base) {
   return { pid, controlPort: LEGACY_ROOT_CONTROL_PORT };
 }
 function probePortFree(port) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const server = createServer();
-    server.once("error", () => resolve3(false));
+    server.once("error", () => resolve4(false));
     server.once("listening", () => {
-      server.close(() => resolve3(true));
+      server.close(() => resolve4(true));
     });
     server.listen(port, "127.0.0.1");
   });
@@ -2086,7 +2289,7 @@ async function resolvePair(base, opts) {
     pairId: entry.pairId,
     slot,
     ports,
-    stateDir: join5(pairsDir(base), entry.pairId),
+    stateDir: join6(pairsDir(base), entry.pairId),
     name: entry.name ?? name,
     entry,
     warning
@@ -2094,7 +2297,7 @@ async function resolvePair(base, opts) {
 }
 async function removeAllocatedPairIfUnchanged(base, pairId, slot) {
   await withRegistryLock(base, () => {
-    if (existsSync6(pairDirPath(base, pairId)) || pairDirDaemonAlive(base, pairId))
+    if (existsSync7(pairDirPath(base, pairId)) || pairDirDaemonAlive(base, pairId))
       return;
     const reg = readRegistry(base);
     const nextPairs = reg.pairs.filter((pair) => !(pair.pairId === pairId && pair.slot === slot));
@@ -2105,19 +2308,19 @@ async function removeAllocatedPairIfUnchanged(base, pairId, slot) {
 }
 function pairDirPath(base, pairId) {
   const id = validatePairId(pairId);
-  return join5(pairsDir(base), id);
+  return join6(pairsDir(base), id);
 }
 function removePairDir(base, pairId) {
   const id = validatePairId(pairId);
   const root = pairsDir(base);
-  const dir = join5(root, id);
-  const canonicalRoot = resolve2(root);
-  const canonicalDir = resolve2(dir);
+  const dir = join6(root, id);
+  const canonicalRoot = resolve3(root);
+  const canonicalDir = resolve3(dir);
   if (canonicalDir === canonicalRoot || !canonicalDir.startsWith(canonicalRoot + sep)) {
     throw new PairError("PAIR_ID_INVALID", `Refusing to remove a pair dir outside ${canonicalRoot}: ${canonicalDir}`, { pairId });
   }
   assertPairsRootNotSymlinked(root);
-  if (!existsSync6(canonicalDir))
+  if (!existsSync7(canonicalDir))
     return false;
   rmSync2(canonicalDir, { recursive: true, force: true });
   return true;
@@ -2135,22 +2338,22 @@ function assertPairsRootNotSymlinked(root) {
 }
 function listPairDirs(base) {
   const root = pairsDir(base);
-  if (!existsSync6(root))
+  if (!existsSync7(root))
     return [];
   if (lstatSync(root).isSymbolicLink())
     return [];
   return readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
 function pairDirDaemonAlive(base, pairId) {
-  const dir = join5(pairsDir(base), pairId);
+  const dir = join6(pairsDir(base), pairId);
   const pids = [];
   try {
-    const pid = Number.parseInt(readFileSync5(join5(dir, "daemon.pid"), "utf-8").trim(), 10);
+    const pid = Number.parseInt(readFileSync5(join6(dir, "daemon.pid"), "utf-8").trim(), 10);
     if (Number.isFinite(pid))
       pids.push(pid);
   } catch {}
   try {
-    const status = JSON.parse(readFileSync5(join5(dir, "status.json"), "utf-8"));
+    const status = JSON.parse(readFileSync5(join6(dir, "status.json"), "utf-8"));
     if (typeof status?.pid === "number")
       pids.push(status.pid);
   } catch {}
@@ -2283,7 +2486,7 @@ var init_env_guard = __esm(() => {
 
 // src/pair-resolver.ts
 import { realpathSync as realpathSync2 } from "fs";
-import { join as join6, resolve as resolve3 } from "path";
+import { join as join7, resolve as resolve4 } from "path";
 function computeBaseDir() {
   return process.env.AGENTBRIDGE_BASE_DIR || process.env.AGENTBRIDGE_STATE_DIR || StateDirResolver.platformBaseDir();
 }
@@ -2410,7 +2613,7 @@ function resolvePairReadOnly(pairFlag) {
         pairId: entry.pairId,
         slot: entry.slot,
         ports: portsForEntry(entry),
-        stateDir: new StateDirResolver(join6(base, "pairs", entry.pairId)),
+        stateDir: new StateDirResolver(join7(base, "pairs", entry.pairId)),
         name: entry.name ?? name,
         manual: false
       }
@@ -2423,7 +2626,7 @@ function resolvePairReadOnly(pairFlag) {
       pairId,
       slot: null,
       ports: { appPort: 0, proxyPort: 0, controlPort: 0 },
-      stateDir: new StateDirResolver(join6(base, "pairs", pairId)),
+      stateDir: new StateDirResolver(join7(base, "pairs", pairId)),
       name,
       manual: false
     }
@@ -2453,7 +2656,7 @@ function portsForEntry(entry) {
   return portsForSlot(entry.slot);
 }
 function canonicalizeCwd(cwd) {
-  const absolute = resolve3(cwd);
+  const absolute = resolve4(cwd);
   try {
     return realpathSync2.native(absolute);
   } catch {
@@ -2470,8 +2673,8 @@ var init_pair_resolver = __esm(() => {
 });
 
 // src/trace-log.ts
-import { appendFileSync, mkdirSync as mkdirSync4 } from "fs";
-import { join as join7 } from "path";
+import { appendFileSync, existsSync as existsSync8, mkdirSync as mkdirSync4, readdirSync as readdirSync2, statSync as statSync3, unlinkSync as unlinkSync3 } from "fs";
+import { join as join8 } from "path";
 function pickRelevantEnv(env) {
   const picked = {};
   for (const [key, value] of Object.entries(env)) {
@@ -2506,7 +2709,7 @@ function redactArgv(argv) {
 }
 function traceLogPath(cwd, timestamp) {
   const day = timestamp.slice(0, 10);
-  return join7(cwd, ".agentbridge", "logs", `trace-${day}.jsonl`);
+  return join8(cwd, ".agentbridge", "logs", `trace-${day}.jsonl`);
 }
 function appendTraceEvent(input) {
   const timestamp = input.timestamp ?? new Date().toISOString();
@@ -2520,11 +2723,39 @@ function appendTraceEvent(input) {
     ...input.env ? { env: pickRelevantEnv(input.env) } : {},
     ...input.data ? { data: redactData(input.data) } : {}
   };
-  mkdirSync4(join7(input.cwd, ".agentbridge", "logs"), { recursive: true });
+  const logsDir = join8(input.cwd, ".agentbridge", "logs");
+  const isNewDayFile = !existsSync8(path);
+  mkdirSync4(logsDir, { recursive: true });
+  if (isNewDayFile) {
+    pruneOldTraceLogs(logsDir, path, Date.parse(timestamp));
+  }
   appendFileSync(path, JSON.stringify(event) + `
 `, "utf-8");
   return path;
 }
+function pruneOldTraceLogs(logsDir, keepPath, nowMs) {
+  if (!Number.isFinite(nowMs))
+    return;
+  const cutoff = nowMs - TRACE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+  let entries;
+  try {
+    entries = readdirSync2(logsDir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!TRACE_FILE_RE.test(name))
+      continue;
+    const filePath = join8(logsDir, name);
+    if (filePath === keepPath)
+      continue;
+    try {
+      if (statSync3(filePath).mtimeMs < cutoff) {
+        unlinkSync3(filePath);
+      }
+    } catch {}
+  }
+}
 function isEnvSnapshot(key, value) {
   return /env$/i.test(key) && !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -2550,8 +2781,9 @@ function redactData(value, key = "") {
   }
   return value;
 }
-var SECRET_KEY_RE, SECRET_ARG_RE, RELEVANT_ENV_RE;
+var TRACE_RETENTION_DAYS = 7, TRACE_FILE_RE, SECRET_KEY_RE, SECRET_ARG_RE, RELEVANT_ENV_RE;
 var init_trace_log = __esm(() => {
+  TRACE_FILE_RE = /^trace-\d{4}-\d{2}-\d{2}\.jsonl$/;
   SECRET_KEY_RE = /(token|secret|password|passwd|api[_-]?key|auth|cookie|session)/i;
   SECRET_ARG_RE = /^--?(?:token|secret|password|passwd|apikey|api-key|api_key|auth|cookie|session)(?:=.*)?$/i;
   RELEVANT_ENV_RE = /^(AGENTBRIDGE_|CODEX_)/;
@@ -2600,10 +2832,12 @@ var init_max_permissions = __esm(() => {
 // src/cli/claude.ts
 var exports_claude = {};
 __export(exports_claude, {
+  warnIfPluginCacheMissing: () => warnIfPluginCacheMissing,
   runClaude: () => runClaude,
   checkOwnedFlagConflicts: () => checkOwnedFlagConflicts
 });
 import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync9 } from "fs";
 async function runClaude(args) {
   const originalEnv = { ...process.env };
   const envGuardResult = guardAgentBridgeEnv({
@@ -2641,6 +2875,7 @@ async function runClaude(args) {
   }
   await assertPairNotLive(lifecycle, pair);
   lifecycle.clearKilled();
+  warnIfPluginCacheMissing();
   const channelEntry = `plugin:${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
   if (permissionPlan.inject) {
     console.error(`[agentbridge] running with ${CLAUDE_MAX_PERMISSION_FLAG} (default; opt out with --safe or AGENTBRIDGE_SAFE=1)`);
@@ -2668,6 +2903,18 @@ async function runClaude(args) {
     process.exit(1);
   });
 }
+function warnIfPluginCacheMissing(cacheRoot = pluginCacheRoot(), log = (msg) => console.error(msg)) {
+  let cacheExists;
+  try {
+    cacheExists = existsSync9(cacheRoot);
+  } catch {
+    return false;
+  }
+  if (!shouldWarnMissingPluginCache(cacheExists))
+    return false;
+  log("[agentbridge] \u26A0\uFE0F  Plugin not installed (no plugin cache found). Run `abg init`, " + `or in Claude Code: ${MARKETPLACE_STEPS.join(" \u2192 ")}. Launching anyway\u2026`);
+  return true;
+}
 function traceCliStart(event, args, originalEnv, envGuardAction, pair) {
   try {
     appendTraceEvent({
@@ -2744,6 +2991,7 @@ function checkOwnedFlagConflicts(args, commandName, ownedFlags) {
 var OWNED_FLAGS;
 var init_claude = __esm(() => {
   init_cli();
+  init_plugin_cache();
   init_daemon_client();
   init_daemon_lifecycle();
   init_build_info();
@@ -2755,11 +3003,11 @@ var init_claude = __esm(() => {
 });
 
 // src/agents-contract.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync6 } from "fs";
+import { join as join9 } from "path";
 function checkAgentsMdContract(cwd) {
-  const path = join8(cwd, "AGENTS.md");
-  const exists = existsSync7(path);
+  const path = join9(cwd, "AGENTS.md");
+  const exists = existsSync10(path);
   let content = "";
   if (exists) {
     try {
@@ -2790,8 +3038,8 @@ function isFreshAgentsMdContract(content) {
 var init_agents_contract = () => {};
 
 // src/wrapper-exit-observability.ts
-import { readFileSync as readFileSync7, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
-import { join as join9 } from "path";
+import { readFileSync as readFileSync7, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
+import { join as join10 } from "path";
 function discoverNativeChildPid(launcherPid, run) {
   try {
     const out = run("pgrep", ["-P", String(launcherPid)]);
@@ -2820,12 +3068,12 @@ function refineCleanExitClassification(turnInProgress) {
     return "exit_0_idle";
   return "exit_0_turn_unknown";
 }
-function findCodexSqliteLog(codexHome, fs = { readdir: readdirSync2, stat: statSync3 }) {
+function findCodexSqliteLog(codexHome, fs = { readdir: readdirSync3, stat: statSync4 }) {
   try {
     const entries = fs.readdir(codexHome).filter((name) => /^logs.*\.sqlite$/.test(String(name)));
     let best = null;
     for (const name of entries) {
-      const path = join9(codexHome, String(name));
+      const path = join10(codexHome, String(name));
       try {
         const mtime = fs.stat(path).mtimeMs;
         if (!best || mtime > best.mtime)
@@ -2885,15 +3133,15 @@ var init_pair_command = __esm(() => {
 });
 
 // src/rotating-log.ts
-import { appendFileSync as appendFileSync2, existsSync as existsSync8, renameSync as renameSync2, statSync as statSync4, unlinkSync as unlinkSync3 } from "fs";
+import { appendFileSync as appendFileSync2, existsSync as existsSync11, renameSync as renameSync2, statSync as statSync5, unlinkSync as unlinkSync4 } from "fs";
 import { dirname as dirname2 } from "path";
-function appendRotatingLog(path, content, options = {}) {
+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 (!existsSync8(dirname2(path)))
+  if (!fsOps.existsSync(dirname2(path)))
     return;
-  rotateIfNeeded(path, Buffer.byteLength(content), maxBytes, keep);
-  appendFileSync2(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];
@@ -2902,30 +3150,53 @@ 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 (!existsSync8(path))
-    return;
-  const size = statSync4(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 (!existsSync8(current))
-      continue;
     if (index === keep) {
-      unlinkSync3(current);
+      unlinkIfPresent(current, fsOps);
     } else {
-      renameSync2(current, next);
+      renameIfPresent(current, next, fsOps);
     }
   }
-  renameSync2(path, `${path}.1`);
+  renameIfPresent(path, `${path}.1`, fsOps);
 }
-var DEFAULT_MAX_BYTES, DEFAULT_KEEP = 3;
+var DEFAULT_MAX_BYTES, DEFAULT_KEEP = 3, REAL_FS_OPS;
 var init_rotating_log = __esm(() => {
   DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+  REAL_FS_OPS = { statSync: statSync5, renameSync: renameSync2, unlinkSync: unlinkSync4, appendFileSync: appendFileSync2, existsSync: existsSync11 };
 });
 
 // src/stderr-ring-buffer.ts
@@ -2978,20 +3249,20 @@ var init_stderr_ring_buffer = __esm(() => {
 
 // src/thread-state.ts
 import {
-  existsSync as existsSync9,
+  existsSync as existsSync12,
   mkdirSync as mkdirSync5,
-  readdirSync as readdirSync3,
+  readdirSync as readdirSync4,
   readFileSync as readFileSync8,
   renameSync as renameSync3,
   writeFileSync as writeFileSync6
 } from "fs";
 import { homedir as homedir3 } from "os";
-import { basename as basename3, dirname as dirname3, join as join10 } from "path";
+import { basename as basename3, dirname as dirname3, join as join11 } from "path";
 function nowIso() {
   return new Date().toISOString();
 }
 function codexHome(env = process.env) {
-  return env.CODEX_HOME && env.CODEX_HOME.length > 0 ? env.CODEX_HOME : join10(homedir3(), ".codex");
+  return env.CODEX_HOME && env.CODEX_HOME.length > 0 ? env.CODEX_HOME : join11(homedir3(), ".codex");
 }
 function atomicWriteJson(path, value) {
   mkdirSync5(dirname3(path), { recursive: true });
@@ -3010,8 +3281,8 @@ function readRawCurrentThread(stateDir) {
   return null;
 }
 function findCodexRolloutFile(threadId, env = process.env, maxEntries = 20000) {
-  const sessionsDir = join10(codexHome(env), "sessions");
-  if (!threadId || !existsSync9(sessionsDir))
+  const sessionsDir = join11(codexHome(env), "sessions");
+  if (!threadId || !existsSync12(sessionsDir))
     return null;
   const exactName = `rollout-${threadId}.jsonl`;
   const stack = [sessionsDir];
@@ -3020,13 +3291,13 @@ function findCodexRolloutFile(threadId, env = process.env, maxEntries = 20000) {
     const dir = stack.pop();
     let entries;
     try {
-      entries = readdirSync3(dir, { withFileTypes: true });
+      entries = readdirSync4(dir, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
       visited++;
-      const path = join10(dir, entry.name);
+      const path = join11(dir, entry.name);
       if (entry.isDirectory()) {
         stack.push(path);
         continue;
@@ -3051,7 +3322,7 @@ function readUsableCurrentThread(identity, env = process.env) {
     return null;
   if (state.cwd !== identity.cwd)
     return null;
-  if (state.rolloutPath && existsSync9(state.rolloutPath))
+  if (state.rolloutPath && existsSync12(state.rolloutPath))
     return state;
   const rolloutPath = findCodexRolloutFile(state.threadId, env);
   if (!rolloutPath)
@@ -3082,16 +3353,16 @@ import {
   closeSync as closeSync3,
   writeFileSync as writeFileSync7,
   readFileSync as readFileSync9,
-  unlinkSync as unlinkSync4,
-  existsSync as existsSync10,
+  unlinkSync as unlinkSync5,
+  existsSync as existsSync13,
   mkdirSync as mkdirSync6
 } from "fs";
 import { homedir as homedir4 } from "os";
-import { dirname as dirname4, join as join11 } from "path";
+import { dirname as dirname4, join as join12 } from "path";
 function appendWrapperLog(path, entry) {
   try {
     const dir = dirname4(path);
-    if (!existsSync10(dir)) {
+    if (!existsSync13(dir)) {
       mkdirSync6(dir, { recursive: true });
     }
     appendRotatingLog(path, `[${new Date().toISOString()}] ${entry}
@@ -3258,7 +3529,7 @@ async function runCodex(args) {
   if (status?.proxyUrl) {
     proxyUrl = status.proxyUrl;
   } else {
-    const fallbackProxyPort = process.env.CODEX_PROXY_PORT ?? String(new ConfigService().loadOrDefault().codex.proxyPort);
+    const fallbackProxyPort = process.env.CODEX_PROXY_PORT ?? String(new ConfigService().loadOrDefault((msg) => console.error(`[agentbridge] ${msg}`)).codex.proxyPort);
     proxyUrl = `ws://127.0.0.1:${fallbackProxyPort}`;
     console.error(`[agentbridge] No daemon status found, using fallback proxy port: ${proxyUrl}`);
   }
@@ -3378,7 +3649,7 @@ async function runCodex(args) {
       return;
     cleanedTuiPid = true;
     try {
-      unlinkSync4(stateDir.tuiPidFile);
+      unlinkSync5(stateDir.tuiPidFile);
     } catch {}
   }
   function requestChildTermination(reason) {
@@ -3452,7 +3723,7 @@ async function runCodex(args) {
       classification = refineCleanExitClassification(readTurnInProgress(stateDir.statusFile));
     }
     const tuiLogTail = captureTuiLogTail({
-      codexHome: join11(homedir4(), ".codex"),
+      codexHome: join12(homedir4(), ".codex"),
       nativePid: nativeChildPid,
       run: (cmd, args2) => execFileSync6(cmd, args2, { encoding: "utf-8", timeout: 2000 })
     });
@@ -3508,12 +3779,12 @@ function guardNoLiveManagedTui(stateDir, proxyUrl) {
   if (pid) {
     if (!isProcessAlive(pid)) {
       try {
-        unlinkSync4(stateDir.tuiPidFile);
+        unlinkSync5(stateDir.tuiPidFile);
       } catch {}
     } else if (!isManagedCodexTuiProcess(pid, proxyUrl)) {
       appendWrapperLog(stateDir.codexWrapperLogFile, `stale tui pid file pointed at unmanaged live pid=${pid}; removing`);
       try {
-        unlinkSync4(stateDir.tuiPidFile);
+        unlinkSync5(stateDir.tuiPidFile);
       } catch {}
     } else {
       console.error(`[agentbridge] This pair already has a managed Codex TUI running (pid ${pid}).`);
@@ -3560,7 +3831,7 @@ async function waitForProxyReady(proxyUrl, maxRetries = 20, delayMs = 100) {
         return;
       }
     } catch {}
-    await new Promise((resolve4) => setTimeout(resolve4, delayMs));
+    await new Promise((resolve5) => setTimeout(resolve5, delayMs));
   }
   throw new Error(`Timed out waiting for Codex proxy readiness on ${healthUrl}`);
 }
@@ -3609,17 +3880,17 @@ var init_codex = __esm(() => {
 });
 
 // src/claude-session.ts
-import { readdirSync as readdirSync4, statSync as statSync5 } from "fs";
+import { readdirSync as readdirSync5, statSync as statSync6 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function encodeClaudeProjectDir(cwd) {
   return cwd.replace(/[^a-zA-Z0-9]/g, "-");
 }
-function findLatestClaudeSession(cwd, claudeHome = process.env.CLAUDE_CONFIG_DIR || join12(homedir5(), ".claude")) {
-  const dir = join12(claudeHome, "projects", encodeClaudeProjectDir(cwd));
+function findLatestClaudeSession(cwd, claudeHome = process.env.CLAUDE_CONFIG_DIR || join13(homedir5(), ".claude")) {
+  const dir = join13(claudeHome, "projects", encodeClaudeProjectDir(cwd));
   let entries;
   try {
-    entries = readdirSync4(dir);
+    entries = readdirSync5(dir);
   } catch {
     return null;
   }
@@ -3630,10 +3901,10 @@ function findLatestClaudeSession(cwd, claudeHome = process.env.CLAUDE_CONFIG_DIR
     const sessionId = name.slice(0, -".jsonl".length);
     if (!SESSION_ID_PATTERN.test(sessionId))
       continue;
-    const file = join12(dir, name);
+    const file = join13(dir, name);
     let mtimeMs;
     try {
-      const st = statSync5(file);
+      const st = statSync6(file);
       if (!st.isFile())
         continue;
       mtimeMs = st.mtimeMs;
@@ -3739,8 +4010,8 @@ __export(exports_kill, {
   runKill: () => runKill,
   formatKillReport: () => formatKillReport
 });
-import { readFileSync as readFileSync10, unlinkSync as unlinkSync5 } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync10, unlinkSync as unlinkSync6 } from "fs";
+import { join as join14 } from "path";
 async function runKill(args = []) {
   const argError = validateKillArgs(args);
   if (argError === "help") {
@@ -3792,7 +4063,7 @@ async function runKill(args = []) {
     for (const dirName of listPairDirsSafe(base)) {
       if (registeredIds.has(dirName))
         continue;
-      const stateDir = new StateDirResolver(join13(base, "pairs", dirName));
+      const stateDir = new StateDirResolver(join14(base, "pairs", dirName));
       results.push(await stopStateDir(`${dirName} (unregistered)`, stateDir, portsFromStateDir(stateDir)));
     }
     const legacy = detectLegacyRootDaemon(base);
@@ -3877,7 +4148,7 @@ No arguments stop this directory's registered pairs and any legacy-root daemon.
 }
 async function stopPairEntry(base, pair) {
   const ports = portsForEntry(pair);
-  const stateDir = new StateDirResolver(join13(base, "pairs", pair.pairId));
+  const stateDir = new StateDirResolver(join14(base, "pairs", pair.pairId));
   return stopStateDir(pair.pairId, stateDir, ports);
 }
 function listPairDirsSafe(base) {
@@ -4046,7 +4317,7 @@ function readTuiPid2(stateDir) {
 }
 function removeTuiPidFile(stateDir) {
   try {
-    unlinkSync5(stateDir.tuiPidFile);
+    unlinkSync6(stateDir.tuiPidFile);
   } catch {}
 }
 function isManagedCodexTuiProcess2(pid, proxyUrl) {
@@ -4066,7 +4337,7 @@ var exports_pairs = {};
 __export(exports_pairs, {
   runPairs: () => runPairs
 });
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 async function runPairs(args = []) {
   const [command, ...rest] = args;
   if (command === "rm") {
@@ -4232,7 +4503,7 @@ async function collectRows() {
 }
 async function rowForPair(base, pair) {
   const ports = portsForEntry(pair);
-  const stateDir = new StateDirResolver(join14(base, "pairs", pair.pairId));
+  const stateDir = new StateDirResolver(join15(base, "pairs", pair.pairId));
   const lifecycle = new DaemonLifecycle({
     stateDir,
     controlPort: ports.controlPort,
@@ -4339,18 +4610,18 @@ var DAEMON_STATUS_FETCH_TIMEOUT_MS = 1000;
 import { Database } from "bun:sqlite";
 import {
   copyFileSync,
-  existsSync as existsSync11,
+  existsSync as existsSync14,
   mkdirSync as mkdirSync7,
   readFileSync as readFileSync11
 } from "fs";
-import { dirname as dirname5, join as join15 } from "path";
+import { dirname as dirname5, join as join16 } from "path";
 function isKickoffText(text) {
   if (!text)
     return false;
   return KICKOFF_FINGERPRINTS.some((fingerprint) => text.includes(fingerprint));
 }
 function extractFirstRealUserMessage(rolloutPath) {
-  if (!existsSync11(rolloutPath))
+  if (!existsSync14(rolloutPath))
     return null;
   const raw = readFileSync11(rolloutPath, "utf-8");
   for (const line of raw.split(`
@@ -4374,8 +4645,8 @@ function extractFirstRealUserMessage(rolloutPath) {
 }
 function scanResumePollution(options = {}) {
   const codexHome2 = options.codexHome ?? codexHome();
-  const dbPath = options.dbPath ?? join15(codexHome2, "state_5.sqlite");
-  if (!existsSync11(dbPath)) {
+  const dbPath = options.dbPath ?? join16(codexHome2, "state_5.sqlite");
+  if (!existsSync14(dbPath)) {
     return { codexHome: codexHome2, dbPath, scanned: 0, candidates: [], applied: 0, renamed: 0, deleted: 0 };
   }
   const db = options.apply ? new Database(dbPath) : new Database(dbPath, { readonly: true });
@@ -4468,12 +4739,12 @@ function scanResumePollution(options = {}) {
 }
 function backupCodexStateFiles(dbPath, now = new Date().toISOString()) {
   const safeStamp = now.replace(/[:.]/g, "-");
-  const base = join15(dirname5(dbPath), "agentbridge-backups", `resume-pollution-${safeStamp}`);
+  const base = join16(dirname5(dbPath), "agentbridge-backups", `resume-pollution-${safeStamp}`);
   mkdirSync7(base, { recursive: true });
   for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
-    if (!existsSync11(path))
+    if (!existsSync14(path))
       continue;
-    const target = join15(base, path.split("/").pop());
+    const target = join16(base, path.split("/").pop());
     mkdirSync7(dirname5(target), { recursive: true });
     copyFileSync(path, target);
   }
@@ -4521,9 +4792,8 @@ __export(exports_doctor, {
   runDoctor: () => runDoctor,
   formatDoctorReport: () => formatDoctorReport
 });
-import { existsSync as existsSync12, readFileSync as readFileSync12, readdirSync as readdirSync5, realpathSync as realpathSync3, statSync as statSync6 } from "fs";
-import { homedir as homedir6 } from "os";
-import { join as join16 } from "path";
+import { existsSync as existsSync15, readFileSync as readFileSync12, readdirSync as readdirSync6, realpathSync as realpathSync3, statSync as statSync7 } from "fs";
+import { join as join17 } from "path";
 async function runDoctor(args = []) {
   if (args[0] === "resume-pollution") {
     runResumePollution(args.slice(1));
@@ -4626,6 +4896,7 @@ async function buildDoctorReport(pair, registered) {
     detail: env.ok ? "AgentBridge env matches cwd" : env.reasons.join("; "),
     hint: env.ok ? undefined : "\u73AF\u5883\u53D8\u91CF\u4E0E\u5F53\u524D\u76EE\u5F55\u4E0D\u5339\u914D\uFF1A\u8BF7\u5728\u6B63\u786E\u7684\u9879\u76EE\u76EE\u5F55\u91CC\u91CD\u65B0\u8FD0\u884C `agentbridge claude`\uFF0C\u4E0D\u8981\u590D\u7528\u5176\u4ED6\u76EE\u5F55\u7684\u4F1A\u8BDD\u73AF\u5883\u3002"
   });
+  checks.push(configParseabilityCheck(cwd));
   checks.push({
     name: "daemon health",
     status: health ? "ok" : "warn",
@@ -4712,16 +4983,16 @@ function artifactAlignmentCheck() {
         stamps.push({ label: "global-cli", commit });
     } catch {}
   }
-  const cacheRoot = join16(homedir6(), ".claude", "plugins", "cache", "agentbridge", "agentbridge");
+  const cacheRoot = pluginCacheRoot();
   try {
-    for (const version of readdirSync5(cacheRoot)) {
-      const commit = extractBundleCommit(join16(cacheRoot, version, "server", "daemon.js"));
+    for (const version of readdirSync6(cacheRoot)) {
+      const commit = extractBundleCommit(join17(cacheRoot, version, "server", "daemon.js"));
       if (commit)
         stamps.push({ label: `plugin-cache@${version}`, commit });
     }
   } catch {}
-  const repoBundle = join16(process.cwd(), "plugins", "agentbridge", "server", "daemon.js");
-  if (existsSync12(repoBundle)) {
+  const repoBundle = join17(process.cwd(), "plugins", "agentbridge", "server", "daemon.js");
+  if (existsSync15(repoBundle)) {
     const commit = extractBundleCommit(repoBundle);
     if (commit)
       stamps.push({ label: "repo-bundle", commit });
@@ -4753,8 +5024,31 @@ function extractBundleCommit(path) {
     return null;
   }
 }
+function configParseabilityCheck(cwd) {
+  const desc = new ConfigService(cwd).describeConfig();
+  if (desc.state === "absent") {
+    return {
+      name: "config.json",
+      status: "ok",
+      detail: `no project config at ${desc.path} \u2014 built-in defaults in effect`
+    };
+  }
+  if (desc.state === "corrupt") {
+    return {
+      name: "config.json",
+      status: "warn",
+      detail: `unparseable at ${desc.path} (${desc.reason}) \u2014 custom thresholds NOT in effect, using defaults`,
+      hint: "config.json \u635F\u574F\u6216\u5B57\u6BB5\u7C7B\u578B\u9519\u8BEF\uFF1Abridge \u5DF2\u56DE\u9000\u5230\u9ED8\u8BA4\u9608\u503C\uFF0C\u4F60\u7684\u81EA\u5B9A\u4E49 budget/idle \u8BBE\u7F6E\u672A\u751F\u6548\u3002" + "\u4FEE\u6B63\u8BE5\u6587\u4EF6\u7684 JSON \u8BED\u6CD5/\u5B57\u6BB5\u7C7B\u578B\u540E\u91CD\u542F `agentbridge claude` \u5373\u53EF\u91CD\u65B0\u751F\u6548\u3002"
+    };
+  }
+  return {
+    name: "config.json",
+    status: "ok",
+    detail: desc.customValues ? `parsed at ${desc.path} \u2014 custom values in effect` : `parsed at ${desc.path} \u2014 all values match defaults`
+  };
+}
 function logCheck(name, path) {
-  if (!existsSync12(path)) {
+  if (!existsSync15(path)) {
     return {
       name,
       status: "warn",
@@ -4762,7 +5056,7 @@ function logCheck(name, path) {
       hint: "\u65E5\u5FD7\u4F1A\u5728\u76F8\u5E94\u8FDB\u7A0B\u9996\u6B21\u542F\u52A8\u65F6\u521B\u5EFA\uFF1B\u8FDB\u7A0B\u4ECE\u672A\u542F\u52A8\u8FC7\u65F6\u8FD9\u662F\u6B63\u5E38\u7684\u3002"
     };
   }
-  const stat = statSync6(path);
+  const stat = statSync7(path);
   if (stat.size > LARGE_LOG_WARN_BYTES) {
     return {
       name,
@@ -4804,7 +5098,9 @@ function printDoctorReport(report) {
 }
 var LARGE_LOG_WARN_BYTES;
 var init_doctor = __esm(() => {
+  init_plugin_cache();
   init_build_info();
+  init_config_service();
   init_env_guard();
   init_pair_resolver();
   init_thread_state();
@@ -4836,6 +5132,9 @@ function formatAgent(name, usage, snapshotAt) {
   if (usage.rateLimitedUntil > 0) {
     parts.push(`\u9650\u6D41\u81F3 ${formatEpoch(usage.rateLimitedUntil)}`);
   }
+  if (usage.parsedVia === "positional") {
+    parts.push("\u26A0\uFE0F \u7A97\u53E3\u8BC6\u522B\u4F7F\u7528\u4F4D\u7F6E\u515C\u5E95");
+  }
   const ageSec = usage.fetchedAt > 0 ? snapshotAt - usage.fetchedAt : 0;
   if (ageSec > 300) {
     parts.push(`\u26A0\uFE0F \u6570\u636E\u91C7\u96C6\u4E8E ${Math.round(ageSec / 60)} \u5206\u949F\u524D`);
@@ -4947,6 +5246,160 @@ var init_budget = __esm(() => {
   init_render();
 });
 
+// src/cli/logs.ts
+var exports_logs = {};
+__export(exports_logs, {
+  tailLines: () => tailLines,
+  runLogs: () => runLogs,
+  parseLogsArgs: () => parseLogsArgs,
+  followLog: () => followLog
+});
+import { existsSync as existsSync16, readFileSync as readFileSync13 } from "fs";
+import { spawn as spawn4 } from "child_process";
+function parseLogsArgs(args) {
+  let codex = false;
+  let follow = false;
+  let lines = DEFAULT_LINES;
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--codex") {
+      codex = true;
+      continue;
+    }
+    if (a === "-f" || a === "--follow") {
+      follow = true;
+      continue;
+    }
+    if (a === "-n" || a === "--lines") {
+      const next = args[i + 1];
+      if (next === undefined) {
+        throw new Error(`${a} requires a positive integer (e.g. ${a} 200)`);
+      }
+      lines = parsePositiveInt(next, a);
+      i++;
+      continue;
+    }
+    if (a.startsWith("-n")) {
+      lines = parsePositiveInt(a.slice(2), "-n");
+      continue;
+    }
+    if (a.startsWith("--lines=")) {
+      lines = parsePositiveInt(a.slice("--lines=".length), "--lines");
+      continue;
+    }
+    throw new Error(`Unknown logs flag: ${a}`);
+  }
+  return { codex, follow, lines };
+}
+function parsePositiveInt(raw, flag) {
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`${flag} must be a positive integer, got "${raw}"`);
+  }
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${flag} must be a positive integer, got "${raw}"`);
+  }
+  return n;
+}
+function tailLines(text, count) {
+  const body = text.endsWith(`
+`) ? text.slice(0, -1) : text;
+  if (body.length === 0)
+    return [];
+  const all = body.split(`
+`);
+  return all.length <= count ? all : all.slice(all.length - count);
+}
+async function runLogs(args) {
+  const { pairFlag } = parsePairFlag(args);
+  const rest = stripPairTokens(args);
+  let options;
+  try {
+    options = parseLogsArgs(rest);
+  } catch (err) {
+    console.error(`[agentbridge] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+    return;
+  }
+  let resolution;
+  try {
+    resolution = resolvePairReadOnly(pairFlag);
+  } catch (err) {
+    console.error(`[agentbridge] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+    return;
+  }
+  const { pair } = resolution;
+  const logPath = options.codex ? pair.stateDir.codexWrapperLogFile : pair.stateDir.logFile;
+  const logLabel = options.codex ? "codex wrapper log" : "daemon log";
+  if (!existsSync16(logPath)) {
+    const which = options.codex ? "codex wrapper log" : "daemon log";
+    console.error(`no ${which} for pair ${pair.name} yet \u2014 start it with \`abg claude\` (${logPath})`);
+    process.exit(1);
+    return;
+  }
+  if (options.follow) {
+    await followLog(logPath, options.lines);
+    return;
+  }
+  printTail(logPath, options.lines, logLabel, pair.name);
+}
+function printTail(logPath, count, label, pairName) {
+  let text;
+  try {
+    text = readFileSync13(logPath, "utf8");
+  } catch (err) {
+    console.error(`[agentbridge] failed to read ${label} for pair ${pairName}: ` + `${err instanceof Error ? err.message : String(err)} (${logPath})`);
+    process.exit(1);
+    return;
+  }
+  const lines = tailLines(text, count);
+  for (const line of lines)
+    console.log(line);
+}
+function followLog(logPath, count) {
+  return new Promise((resolvePromise) => {
+    const child = spawn4("tail", ["-f", "-n", String(count), logPath], {
+      stdio: "inherit"
+    });
+    child.on("error", (err) => {
+      console.error(`[agentbridge] failed to follow log: ${err.message}`);
+      process.exit(1);
+    });
+    child.on("exit", (code, signal) => {
+      if (signal === "SIGINT" || signal === "SIGTERM") {
+        resolvePromise();
+        return;
+      }
+      if (code != null && code !== 0) {
+        process.exit(code);
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+function stripPairTokens(args) {
+  const out = [];
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--pair") {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-"))
+        i++;
+      continue;
+    }
+    if (a.startsWith("--pair="))
+      continue;
+    out.push(a);
+  }
+  return out;
+}
+var DEFAULT_LINES = 100;
+var init_logs = __esm(() => {
+  init_pair_resolver();
+});
+
 // src/cli.ts
 function parseTopLevel(args) {
   const pairTokens = [];
@@ -5019,6 +5472,10 @@ async function main(command, restArgs) {
       const { runBudget: runBudget2 } = await Promise.resolve().then(() => (init_budget(), exports_budget));
       await runBudget2(restArgs);
       break;
+    case "logs":
+      const { runLogs: runLogs2 } = await Promise.resolve().then(() => (init_logs(), exports_logs));
+      await runLogs2(restArgs);
+      break;
     case "--help":
     case "-h":
     case undefined:
@@ -5057,6 +5514,9 @@ Commands:
   doctor [--json]    Diagnose env, daemon, build drift, logs, and current thread
   doctor resume-pollution [--apply]  Find/fix old AgentBridge kickoff metadata
   budget [--json]    Show both agents' subscription quota snapshot (5h/weekly, drift, pause state)
+  logs [--codex] [-f] [-n N]
+                     Tail this pair's daemon log (or the codex wrapper log with
+                     --codex). -n N: last N lines (default 100). -f: follow/stream.
   kill [all | --all | --pair <name|id>]
                      Stop this directory's pairs (default), every pair (all/--all), or one (--pair)
 
@@ -5095,6 +5555,10 @@ Examples:
   abg pairs                    # List all pairs and their ports/status
   abg pairs --threads          # Include current thread mapping
   abg doctor --json            # Emit a structured diagnostics report
+  abg logs                     # Tail the last 100 lines of this pair's daemon log
+  abg logs -f -n 200           # Follow the log, starting from the last 200 lines
+  abg logs --codex             # Tail the codex wrapper log instead
+  abg --pair work logs         # Tail the "work" pair's daemon log
   abg pairs rm work            # Stop this directory's "work" pair and free its slot
   abg pairs rm work-1a2b3c4d   # ...or by its full id (from that pair's directory)
   abg pairs prune --dry-run    # Preview orphan pair dirs (no registry entry, not live)
@@ -5116,7 +5580,7 @@ var MARKETPLACE_NAME = "agentbridge", PLUGIN_NAME = "agentbridge", REFRESH_COMMA
 var init_cli = __esm(() => {
   REFRESH_COMMANDS = new Set(["claude", "codex", "resume"]);
   NOTIFY_COMMANDS = new Set(["claude", "codex", "init", "dev", "resume"]);
-  PAIR_AWARE_COMMANDS = new Set(["claude", "codex", "kill", "doctor", "budget", "resume"]);
+  PAIR_AWARE_COMMANDS = new Set(["claude", "codex", "kill", "doctor", "budget", "resume", "logs"]);
   if (import.meta.main) {
     const { command, restArgs } = parseTopLevel(process.argv.slice(2));
     main(command, restArgs).catch((err) => {
@@ -5129,6 +5593,9 @@ init_cli();
 
 export {
   parseTopLevel,
+  REFRESH_COMMANDS,
   PLUGIN_NAME,
+  PAIR_AWARE_COMMANDS,
+  NOTIFY_COMMANDS,
   MARKETPLACE_NAME
 };