@raysonmeng/agentbridge 0.1.6 → 0.1.7

package/dist/cli.js

@@ -17,9 +17,309 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
-// src/config-service.ts
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+// src/state-dir.ts
+import { mkdirSync, existsSync } from "fs";
 import { join } from "path";
+import { homedir, platform } from "os";
+
+class StateDirResolver {
+  stateDir;
+  static platformBaseDir() {
+    if (platform() === "darwin") {
+      return join(homedir(), "Library", "Application Support", "AgentBridge");
+    }
+    const xdgState = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+    return join(xdgState, "agentbridge");
+  }
+  constructor(envOverride) {
+    const override = envOverride ?? process.env.AGENTBRIDGE_STATE_DIR;
+    this.stateDir = override && override.length > 0 ? override : StateDirResolver.platformBaseDir();
+  }
+  ensure() {
+    if (!existsSync(this.stateDir)) {
+      mkdirSync(this.stateDir, { recursive: true });
+    }
+  }
+  get dir() {
+    return this.stateDir;
+  }
+  get pidFile() {
+    return join(this.stateDir, "daemon.pid");
+  }
+  get tuiPidFile() {
+    return join(this.stateDir, "codex-tui.pid");
+  }
+  get lockFile() {
+    return join(this.stateDir, "daemon.lock");
+  }
+  get statusFile() {
+    return join(this.stateDir, "status.json");
+  }
+  get portsFile() {
+    return join(this.stateDir, "ports.json");
+  }
+  get currentThreadFile() {
+    return join(this.stateDir, "current-thread.json");
+  }
+  get logFile() {
+    return join(this.stateDir, "agentbridge.log");
+  }
+  get codexWrapperLogFile() {
+    return join(this.stateDir, "codex-wrapper.log");
+  }
+  get killedFile() {
+    return join(this.stateDir, "killed");
+  }
+  get updateCheckFile() {
+    return join(this.stateDir, "update-check.json");
+  }
+}
+var init_state_dir = () => {};
+
+// src/version-utils.ts
+function isStableVersion(v) {
+  return STABLE_SEMVER_RE.test(v.trim());
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0;i < 3; i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb)
+      return -1;
+    if (va > vb)
+      return 1;
+  }
+  return 0;
+}
+function isStableUpgrade(current, latest) {
+  if (!isStableVersion(current) || !isStableVersion(latest))
+    return false;
+  return compareVersions(latest, current) === 1;
+}
+var STABLE_SEMVER_RE;
+var init_version_utils = __esm(() => {
+  STABLE_SEMVER_RE = /^\d+\.\d+\.\d+$/;
+});
+
+// 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;
+}
+
+// package.json
+var require_package = __commonJS((exports, module) => {
+  module.exports = {
+    name: "@raysonmeng/agentbridge",
+    version: "0.1.7",
+    description: "Bridge between Claude Code and Codex \u2014 bidirectional agent communication via MCP Channel + JSON-RPC",
+    type: "module",
+    packageManager: "bun@1.3.11",
+    engines: {
+      bun: ">=1.3.11"
+    },
+    bin: {
+      agentbridge: "dist/cli.js",
+      abg: "dist/cli.js"
+    },
+    files: [
+      "dist/",
+      "plugins/",
+      ".claude-plugin/",
+      "scripts/postinstall.cjs",
+      "scripts/install-safety.cjs",
+      "README.md",
+      "LICENSE"
+    ],
+    scripts: {
+      start: "bun run src/bridge.ts",
+      "build:cli": "node scripts/build-bundles.mjs cli daemon",
+      "build:plugin": "node scripts/build-bundles.mjs bridge-plugin daemon-plugin",
+      "smoke:built": "bun scripts/smoke-built-cli.mjs",
+      "smoke:pack": "bun scripts/smoke-pack.mjs",
+      "verify:plugin-sync": "node scripts/verify-plugin-sync.cjs",
+      postinstall: "node scripts/postinstall.cjs",
+      prepublishOnly: "bun run build:cli && bun run build:plugin && bun run verify:plugin-sync && bun scripts/check-plugin-versions.js",
+      "validate:plugin": "claude plugin validate plugins/agentbridge && claude plugin validate .claude-plugin/marketplace.json",
+      test: "bun test src",
+      "e2e:transport": "bun scripts/e2e-codex-transport.mjs",
+      "install:global": "node scripts/install-global.mjs local",
+      "install:global:local": "node scripts/install-global.mjs local",
+      "install:global:npm": "node scripts/install-global.mjs npm",
+      "release:bump": "node scripts/bump-version.mjs",
+      typecheck: "tsc --noEmit",
+      "validate:plugin-versions": "bun scripts/check-plugin-versions.js",
+      check: "tsc --noEmit && bun test src && bun run verify:plugin-sync && bun scripts/check-plugin-versions.js",
+      "ci:local": "bun run check && bun run smoke:built && bun run smoke:pack"
+    },
+    repository: {
+      type: "git",
+      url: "https://github.com/raysonmeng/agent-bridge.git"
+    },
+    homepage: "https://github.com/raysonmeng/agent-bridge#readme",
+    bugs: {
+      url: "https://github.com/raysonmeng/agent-bridge/issues"
+    },
+    keywords: [
+      "claude-code",
+      "codex",
+      "mcp",
+      "agent",
+      "bridge",
+      "multi-agent",
+      "channels"
+    ],
+    author: "AgentBridge Contributors",
+    license: "MIT",
+    devDependencies: {
+      "@modelcontextprotocol/sdk": "^1.27.1",
+      "@types/bun": "^1.3.11",
+      typescript: "^5.8.0"
+    }
+  };
+});
+
+// src/update-notifier.ts
+var exports_update_notifier = {};
+__export(exports_update_notifier, {
+  refreshUpdateCache: () => refreshUpdateCache,
+  parseLatestFromRegistry: () => parseLatestFromRegistry,
+  maybeNotifyUpdate: () => maybeNotifyUpdate,
+  isUpdateCheckSuppressed: () => isUpdateCheckSuppressed,
+  getCurrentVersion: () => getCurrentVersion,
+  buildUpdateNotice: () => buildUpdateNotice,
+  PACKAGE_NAME: () => PACKAGE_NAME
+});
+import { readFileSync, writeFileSync } from "fs";
+function getCurrentVersion() {
+  try {
+    return require_package().version;
+  } catch {
+    return "0.0.0";
+  }
+}
+function isUpdateCheckSuppressed(env, isTTY) {
+  if (env.NO_UPDATE_NOTIFIER)
+    return true;
+  if (env.AGENTBRIDGE_NO_UPDATE_NOTIFIER)
+    return true;
+  if (env.CI)
+    return true;
+  if (env.NODE_ENV === "test")
+    return true;
+  if (!isTTY)
+    return true;
+  return false;
+}
+function readCache(stateDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(stateDir.updateCheckFile, "utf-8"));
+    if (typeof parsed.lastCheckMs !== "number" || !Number.isFinite(parsed.lastCheckMs))
+      return null;
+    return {
+      lastCheckMs: parsed.lastCheckMs,
+      latest: typeof parsed.latest === "string" ? parsed.latest : null
+    };
+  } catch {
+    return null;
+  }
+}
+function writeCache(stateDir, cache) {
+  try {
+    stateDir.ensure();
+    writeFileSync(stateDir.updateCheckFile, JSON.stringify(cache, null, 2) + `
+`, "utf-8");
+  } catch {}
+}
+function parseLatestFromRegistry(body) {
+  if (typeof body !== "object" || body === null)
+    return null;
+  const distTags = body["dist-tags"];
+  if (typeof distTags !== "object" || distTags === null)
+    return null;
+  const latest = distTags.latest;
+  if (typeof latest !== "string" || !isStableVersion(latest))
+    return null;
+  return latest;
+}
+async function fetchLatest(fetchImpl) {
+  try {
+    const res = await fetchImpl(REGISTRY_URL, {
+      headers: { Accept: ABBREVIATED_ACCEPT },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok)
+      return null;
+    return parseLatestFromRegistry(await res.json());
+  } catch {
+    return null;
+  }
+}
+async function refreshUpdateCache(deps = {}) {
+  const stateDir = deps.stateDir ?? new StateDirResolver;
+  const now = deps.now ?? Date.now;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  try {
+    const latest = await fetchLatest(fetchImpl);
+    const prev = readCache(stateDir);
+    writeCache(stateDir, { lastCheckMs: now(), latest: latest ?? prev?.latest ?? null });
+  } catch {}
+}
+function buildUpdateNotice(current, latest, isTTY) {
+  const yellow = isTTY ? "\x1B[33m" : "";
+  const bold = isTTY ? "\x1B[1m" : "";
+  const reset = isTTY ? "\x1B[0m" : "";
+  return [
+    `${yellow}\u26A0 AgentBridge update available: ${bold}${current}${reset}${yellow} \u2192 ${bold}${latest}${reset}`,
+    `  CLI:    npm install -g ${PACKAGE_NAME}@latest`,
+    `  Plugin: /plugin marketplace update agentbridge   (then /reload-plugins)`,
+    `  (silence with NO_UPDATE_NOTIFIER=1)`
+  ].join(`
+`);
+}
+function checkIntervalMs(env) {
+  return parsePositiveIntEnv(CHECK_INTERVAL_ENV, DEFAULT_CHECK_INTERVAL_MS, undefined, env);
+}
+function maybeNotifyUpdate(deps = {}) {
+  try {
+    const env = deps.env ?? process.env;
+    const isTTY = deps.isTTY ?? Boolean(process.stderr.isTTY);
+    if (isUpdateCheckSuppressed(env, isTTY))
+      return;
+    const current = deps.current ?? getCurrentVersion();
+    const stateDir = deps.stateDir ?? new StateDirResolver;
+    const now = deps.now ?? Date.now;
+    const print = deps.print ?? ((m) => process.stderr.write(m + `
+`));
+    const cache = readCache(stateDir);
+    if (cache?.latest && isStableUpgrade(current, cache.latest)) {
+      print(buildUpdateNotice(current, cache.latest, isTTY));
+    }
+    if (deps.refresh && (!cache || now() - cache.lastCheckMs >= checkIntervalMs(env))) {
+      refreshUpdateCache({ stateDir, now, fetchImpl: deps.fetchImpl }).catch(() => {});
+    }
+  } catch {}
+}
+var PACKAGE_NAME = "@raysonmeng/agentbridge", REGISTRY_URL, ABBREVIATED_ACCEPT = "application/vnd.npm.install-v1+json", DEFAULT_CHECK_INTERVAL_MS, FETCH_TIMEOUT_MS = 2500, CHECK_INTERVAL_ENV = "AGENTBRIDGE_UPDATE_CHECK_INTERVAL_MS";
+var init_update_notifier = __esm(() => {
+  init_state_dir();
+  init_version_utils();
+  REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`;
+  DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+});
+
+// src/config-service.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -33,6 +333,63 @@ function normalizeInteger(value, fallback) {
   }
   return fallback;
 }
+function normalizeBoundedInteger(value, fallback, min, max) {
+  const parsed = normalizeInteger(value, fallback);
+  if (parsed < min || parsed > max)
+    return fallback;
+  return parsed;
+}
+function normalizeBoolean(value, fallback) {
+  if (typeof value === "boolean")
+    return value;
+  if (value === "true" || value === "1")
+    return true;
+  if (value === "false" || value === "0")
+    return false;
+  return fallback;
+}
+function normalizeCodexOverride(raw) {
+  if (!isRecord(raw))
+    return null;
+  const override = {};
+  if (typeof raw.model === "string" && raw.model.trim() !== "")
+    override.model = raw.model.trim();
+  if (typeof raw.effort === "string" && raw.effort.trim() !== "")
+    override.effort = raw.effort.trim();
+  return Object.keys(override).length > 0 ? override : null;
+}
+function normalizeCodexTiers(raw) {
+  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
+  };
+}
+function normalizeBudgetConfig(raw) {
+  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);
+  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),
+    pauseAt,
+    resumeBelow,
+    syncDriftPct: normalizeBoundedInteger(budget.syncDriftPct, DEFAULT_BUDGET_CONFIG.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)
+    },
+    codexTierControl: normalizeBoolean(budget.codexTierControl, DEFAULT_BUDGET_CONFIG.codexTierControl) && codexTiers.full !== null,
+    codexTiers
+  };
+}
 function normalizeConfig(raw) {
   if (!isRecord(raw))
     return null;
@@ -49,7 +406,8 @@ function normalizeConfig(raw) {
     turnCoordination: {
       attentionWindowSeconds: normalizeInteger(turnCoordination.attentionWindowSeconds, DEFAULT_CONFIG.turnCoordination.attentionWindowSeconds)
     },
-    idleShutdownSeconds: normalizeInteger(config.idleShutdownSeconds, DEFAULT_CONFIG.idleShutdownSeconds)
+    idleShutdownSeconds: normalizeInteger(config.idleShutdownSeconds, DEFAULT_CONFIG.idleShutdownSeconds),
+    budget: normalizeBudgetConfig(config.budget)
   };
 }
 
@@ -58,15 +416,15 @@ class ConfigService {
   configPath;
   constructor(projectRoot) {
     const root = projectRoot ?? process.cwd();
-    this.configDir = join(root, CONFIG_DIR);
-    this.configPath = join(this.configDir, CONFIG_FILE);
+    this.configDir = join2(root, CONFIG_DIR);
+    this.configPath = join2(this.configDir, CONFIG_FILE);
   }
   hasConfig() {
-    return existsSync(this.configPath);
+    return existsSync2(this.configPath);
   }
   load() {
     try {
-      const raw = readFileSync(this.configPath, "utf-8");
+      const raw = readFileSync2(this.configPath, "utf-8");
       return normalizeConfig(JSON.parse(raw));
     } catch {
       return null;
@@ -77,13 +435,13 @@ class ConfigService {
   }
   save(config) {
     this.ensureConfigDir();
-    writeFileSync(this.configPath, JSON.stringify(config, null, 2) + `
+    writeFileSync2(this.configPath, JSON.stringify(config, null, 2) + `
 `, "utf-8");
   }
   initDefaults() {
     this.ensureConfigDir();
     const created = [];
-    if (!existsSync(this.configPath)) {
+    if (!existsSync2(this.configPath)) {
       this.save(DEFAULT_CONFIG);
       created.push(this.configPath);
     }
@@ -93,13 +451,30 @@ class ConfigService {
     return this.configPath;
   }
   ensureConfigDir() {
-    if (!existsSync(this.configDir)) {
-      mkdirSync(this.configDir, { recursive: true });
+    if (!existsSync2(this.configDir)) {
+      mkdirSync2(this.configDir, { recursive: true });
     }
   }
 }
-var DEFAULT_CONFIG, CONFIG_DIR = ".agentbridge", CONFIG_FILE = "config.json";
+var DEFAULT_BUDGET_CONFIG, DEFAULT_CONFIG, CONFIG_DIR = ".agentbridge", CONFIG_FILE = "config.json";
 var init_config_service = __esm(() => {
+  DEFAULT_BUDGET_CONFIG = {
+    enabled: true,
+    pollSeconds: 60,
+    pauseAt: 90,
+    resumeBelow: 30,
+    syncDriftPct: 10,
+    parallel: {
+      minRemainingPct: 60,
+      timeWindowSec: 3600
+    },
+    codexTierControl: false,
+    codexTiers: {
+      full: null,
+      balanced: { effort: "medium" },
+      eco: { effort: "low" }
+    }
+  };
   DEFAULT_CONFIG = {
     version: "1.0",
     codex: {
@@ -109,18 +484,19 @@ var init_config_service = __esm(() => {
     turnCoordination: {
       attentionWindowSeconds: 15
     },
-    idleShutdownSeconds: 30
+    idleShutdownSeconds: 30,
+    budget: DEFAULT_BUDGET_CONFIG
   };
 });
 
 // src/cli/pkg-root.ts
-import { dirname, join as join2 } from "path";
-import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join3 } from "path";
+import { existsSync as existsSync3 } from "fs";
 import { execFileSync } from "child_process";
 function findPackageRoot() {
   let dir = import.meta.dir;
   while (true) {
-    if (existsSync2(join2(dir, "package.json"))) {
+    if (existsSync3(join3(dir, "package.json"))) {
       return dir;
     }
     const parent = dirname(dir);
@@ -177,7 +553,7 @@ Another AI agent (Codex, by OpenAI) is available in a parallel session on this m
 
 ### Communication mechanism
 - **Claude \u2192 Codex**: Use the AgentBridge MCP tools (\`reply\` / \`get_messages\`) \u2014 these are yours only.
-- **Codex \u2192 Claude**: Codex has no symmetric tool. The bridge transparently intercepts Codex's normal output and forwards it to you. Messages arrive as push notifications (or via \`get_messages\` in pull mode).
+- **Codex \u2192 Claude**: Codex has no symmetric tool. The bridge transparently intercepts Codex's normal output and forwards it to you as push notifications (if a push fails, drain the fallback queue with \`get_messages\`).
 - If Codex ever complains it can't find a "send-to-Claude" API, remind it that its side is transparent \u2014 it just writes a reply and you'll see it.
 
 ### When to collaborate vs. work solo
@@ -199,7 +575,16 @@ Another AI agent (Codex, by OpenAI) is available in a parallel session on this m
 1. When you receive a complex task, **proactively propose a division of labor** to Codex via the reply tool.
 2. State what you'll handle and what you'd like Codex to take on.
 3. Ask for Codex's agreement or counter-proposal before proceeding.
-4. After task completion, **cross-review** each other's work.`, AGENTS_MD_SECTION = `## AgentBridge \u2014 Multi-Agent Collaboration
+4. After task completion, **cross-review** each other's work.
+
+### Budget awareness (active when agent-quota-guard is installed)
+- Goal: **keep the task moving while fully using the subscription quota**. The bridge polls both agents' account-level 5h/weekly windows and may send \`system_budget_*\` notices: **balance** (route more work to the lighter side), **parallel** (quota surplus near the 5h reset \u2014 split more parallel subtasks), **pause/handoff/resume**.
+- \`get_budget\` shows BOTH sides' quota \u2014 re-check it **before every task-allocation decision**. NEVER rely on quota numbers remembered from earlier in the conversation: the weekly window can refresh EARLY (resetting both 5h and weekly), so a side you remember as nearly exhausted may be fully restored.
+- Side-aware pause semantics:
+  - **Codex exhausted** (\`system_budget_pause\`): the reply gate closes. Do not retry replies; continue solo on independent work, note the split point in a checkpoint.
+  - **You (Claude) exhausted** (\`system_budget_handoff\`): the gate stays OPEN \u2014 immediately send ONE handoff reply to Codex packaging the remaining task list, context, artifact locations and acceptance criteria, then stop working (your own quota-guard will hard-stop you at 92%). Codex relays the baton.
+  - **Both exhausted**: joint pause; checkpoint and wait for the resume notice.
+- Save quota with model tiers: route mechanical subagent work to **haiku**, routine work to **sonnet**, reserve **opus** for architecture decisions; when your side is the heavier consumer, delegate more to Codex.`, AGENTS_MD_SECTION = `## AgentBridge \u2014 Multi-Agent Collaboration
 
 You are working in a **multi-agent environment** powered by AgentBridge.
 Another AI agent (Claude, by Anthropic) is available in a parallel session on this machine.
@@ -231,7 +616,33 @@ AgentBridge is a **transparent proxy** on your side. You do **not** have a tool
 1. When you receive a complex task, **proactively propose a division of labor** in your response (Claude will receive it).
 2. State what you'll handle and what you'd like Claude to take on.
 3. Ask for Claude's agreement or counter-proposal before proceeding.
-4. After task completion, **cross-review** each other's work.`;
+4. After task completion, **cross-review** each other's work.
+
+### Message markers
+Put a marker at the **very start** of each \`agentMessage\` (it must be the first text \u2014 e.g. \`[IMPORTANT] Task done\`, not \`Task done [IMPORTANT]\`):
+- \`[IMPORTANT]\` \u2014 decisions, reviews, completions, blockers
+- \`[STATUS]\` \u2014 progress updates
+- \`[FYI]\` \u2014 background context
+
+Keep \`agentMessage\` for high-value communication only.
+
+### Git operations \u2014 FORBIDDEN for you
+You MUST NOT run git **write** commands: \`commit\`, \`push\`, \`pull\`, \`fetch\`, \`checkout -b\`, \`branch\`, \`merge\`, \`rebase\`, \`cherry-pick\`, \`tag\`, \`stash\`. They write the \`.git\` directory (blocked by your sandbox) and will hang your session. Read-only git (\`status\`, \`log\`, \`diff\`, \`show\`, \`rev-parse\`) is fine. Delegate **all** git writes to Claude: report what you changed and let Claude handle branching, committing, and pushing.
+
+### Role guidance
+- Your default role: **Implementer, Executor, Verifier**.
+- Analytical / review tasks: **Independent Analysis & Convergence**.
+- Implementation tasks: **Architect \u2192 Builder \u2192 Critic**.
+- Debugging tasks: **Hypothesis \u2192 Experiment \u2192 Interpretation**.
+- Do not blindly follow Claude \u2014 challenge with evidence when you disagree.
+- Use explicit collaboration phrases: "My independent view is:", "I agree on:", "I disagree on:", "Current consensus:".
+
+### Budget awareness (active when agent-quota-guard is installed)
+- Goal: **keep the task moving while fully using the subscription quota**. You can check BOTH sides' quota yourself via your quota-guard MCP tool \`check_budget\` with \`agent: "claude"\` or \`"codex"\` \u2014 re-check **before negotiating task splits**, and NEVER rely on remembered numbers: the weekly window can refresh early (resetting both 5h and weekly windows).
+- During a **budget pause** (your side exhausted) you simply stop receiving new turns \u2014 that IS the pause. Your own quota-guard hooks still apply; work resumes when Claude's next message arrives.
+- **Handoff (Claude's side exhausted)**: you may receive a baton message packaging the remaining work. Push as far as possible within that single turn; write leftovers to a checkpoint file; do NOT expect Claude to respond until its quota refreshes.
+- Claude may route more or less work to you based on quota drift \u2014 expected load balancing, not preference.
+- When the user enabled tier control, the bridge may adjust your model/reasoning-effort via turn parameters under budget pressure; if asked to economize, prefer lower effort and concise outputs.`;
 
 // src/cli/init.ts
 var exports_init = {};
@@ -241,8 +652,8 @@ __export(exports_init, {
   compareVersions: () => compareVersions
 });
 import { execSync, execFileSync as execFileSync2 } from "child_process";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
 async function runInit() {
   console.log(`AgentBridge Init
 `);
@@ -331,29 +742,16 @@ function checkCodex() {
     process.exit(1);
   }
 }
-function compareVersions(a, b) {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0;i < 3; i++) {
-    const va = pa[i] ?? 0;
-    const vb = pb[i] ?? 0;
-    if (va < vb)
-      return -1;
-    if (va > vb)
-      return 1;
-  }
-  return 0;
-}
 function writeCollaborationSections(projectRoot) {
   const results = [];
   const files = [
-    { name: "CLAUDE.md", path: join3(projectRoot, "CLAUDE.md"), section: CLAUDE_MD_SECTION },
-    { name: "AGENTS.md", path: join3(projectRoot, "AGENTS.md"), section: AGENTS_MD_SECTION }
+    { name: "CLAUDE.md", path: join4(projectRoot, "CLAUDE.md"), section: CLAUDE_MD_SECTION },
+    { name: "AGENTS.md", path: join4(projectRoot, "AGENTS.md"), section: AGENTS_MD_SECTION }
   ];
   for (const { name, path, section } of files) {
     let existing = "";
     try {
-      existing = readFileSync2(path, "utf-8");
+      existing = readFileSync3(path, "utf-8");
     } catch {}
     let updated;
     try {
@@ -367,7 +765,7 @@ function writeCollaborationSections(projectRoot) {
       results.push(`${name}: unchanged (section already up to date)`);
       continue;
     }
-    writeFileSync2(path, updated, "utf-8");
+    writeFileSync3(path, updated, "utf-8");
     if (existing === "") {
       results.push(`${name}: created with collaboration section`);
     } else if (existing.includes(`<!-- ${MARKER_ID}:start -->`)) {
@@ -383,6 +781,7 @@ var init_init = __esm(() => {
   init_config_service();
   init_cli();
   init_pkg_root();
+  init_version_utils();
 });
 
 // src/cli/dev.ts
@@ -392,43 +791,60 @@ __export(exports_dev, {
 });
 import { execFileSync as execFileSync3, spawnSync } from "child_process";
 import { resolve } from "path";
-import { existsSync as existsSync3, cpSync, rmSync } from "fs";
-import { homedir } from "os";
-async function runDev() {
+import { existsSync as existsSync4, cpSync, rmSync } from "fs";
+import { homedir as homedir2 } from "os";
+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");
-  console.log("Building CLI from source...");
-  const cliBuild = spawnSync("bun", ["run", "build:cli"], {
-    cwd: projectRoot,
-    stdio: "inherit"
-  });
-  if (cliBuild.status !== 0) {
-    console.error("  ERROR: CLI build failed. Fix build errors and try again.");
+  const buildScript = resolve(projectRoot, "scripts", "build-bundles.mjs");
+  if (!existsSync4(buildScript)) {
+    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("");
+    console.error("    cd <agent_bridge repo> && bun src/cli.ts dev");
+    console.error("");
+    console.error("  Tip: from the repo, `bun run install:global` updates the global CLI");
+    console.error("  AND syncs the Claude Code plugin in one step.");
     process.exit(1);
   }
-  console.log(`  \u2713 CLI built successfully
+  if (skipBuild) {
+    console.log(`Skipping builds (--skip-build: caller already built CLI + plugin)
 `);
-  console.log("Building plugin from source...");
-  const buildResult = spawnSync("bun", ["run", "build:plugin"], {
-    cwd: projectRoot,
-    stdio: "inherit"
-  });
-  if (buildResult.status !== 0) {
-    console.error("  ERROR: Plugin build failed. Fix build errors and try again.");
-    process.exit(1);
-  }
-  console.log(`  \u2713 Plugin built successfully
+  } else {
+    console.log("Building CLI from source...");
+    const cliBuild = spawnSync("bun", ["run", "build:cli"], {
+      cwd: projectRoot,
+      stdio: "inherit"
+    });
+    if (cliBuild.status !== 0) {
+      console.error("  ERROR: CLI build failed. Fix build errors and try again.");
+      process.exit(1);
+    }
+    console.log(`  \u2713 CLI built successfully
+`);
+    console.log("Building plugin from source...");
+    const buildResult = spawnSync("bun", ["run", "build:plugin"], {
+      cwd: projectRoot,
+      stdio: "inherit"
+    });
+    if (buildResult.status !== 0) {
+      console.error("  ERROR: Plugin build failed. Fix build errors and try again.");
+      process.exit(1);
+    }
+    console.log(`  \u2713 Plugin built successfully
 `);
-  if (!existsSync3(pluginManifest)) {
+  }
+  if (!existsSync4(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 (!existsSync3(marketplacePath)) {
+  if (!existsSync4(marketplacePath)) {
     console.error(`  ERROR: Marketplace manifest not found at ${marketplacePath}`);
     process.exit(1);
   }
@@ -457,8 +873,8 @@ Installing plugin...`);
   }
   console.log(`
 Syncing local plugin to cache...`);
-  const cacheDir = resolve(homedir(), ".claude", "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME);
-  if (existsSync3(cacheDir)) {
+  const cacheDir = resolve(homedir2(), ".claude", "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME);
+  if (existsSync4(cacheDir)) {
     const versionDirs = Bun.spawnSync(["ls", cacheDir]).stdout.toString().trim().split(`
 `).filter(Boolean);
     for (const ver of versionDirs) {
@@ -484,65 +900,414 @@ var init_dev = __esm(() => {
   init_pkg_root();
 });
 
-// src/daemon-lifecycle.ts
-import { spawn, execFileSync as execFileSync4 } from "child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync3, openSync, closeSync, constants } from "fs";
-import { fileURLToPath } from "url";
+// 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;
 
-class DaemonLifecycle {
-  stateDir;
-  controlPort;
-  log;
-  constructor(opts) {
-    this.stateDir = opts.stateDir;
-    this.controlPort = opts.controlPort;
-    this.log = opts.log;
-  }
-  get healthUrl() {
-    return `http://127.0.0.1:${this.controlPort}/healthz`;
-  }
-  get readyUrl() {
-    return `http://127.0.0.1:${this.controlPort}/readyz`;
-  }
-  get controlWsUrl() {
-    return `ws://127.0.0.1:${this.controlPort}/ws`;
-  }
-  async ensureRunning() {
-    if (await this.isHealthy()) {
-      await this.waitForReady();
-      return;
+// src/daemon-client.ts
+import { EventEmitter } from "events";
+var nextSocketId = 0, DaemonClient;
+var init_daemon_client = __esm(() => {
+  DaemonClient = class DaemonClient extends EventEmitter {
+    url;
+    options;
+    ws = null;
+    wsId = 0;
+    nextRequestId = 1;
+    pendingReplies = new Map;
+    constructor(url, options = {}) {
+      super();
+      this.url = url;
+      this.options = options;
     }
-    const existingPid = this.readPid();
-    if (existingPid) {
-      if (isProcessAlive(existingPid)) {
-        if (this.isDaemonProcess(existingPid)) {
-          try {
-            await this.waitForReady(12, 250);
-            return;
-          } catch {
-            throw new Error(`Found existing daemon process ${existingPid}, but control port ${this.controlPort} never became ready.`);
-          }
-        }
-        this.log(`Pid ${existingPid} is alive but not an AgentBridge daemon, removing stale pid file`);
+    async connect() {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.log(`connect() skipped \u2014 ws#${this.wsId} already OPEN`);
+        return;
       }
-      this.removeStalePidFile();
+      if (this.ws) {
+        const state = this.ws.readyState;
+        this.log(`connect() closing lingering ws#${this.wsId} (readyState=${state})`);
+        try {
+          this.ws.close();
+        } catch {}
+        this.ws = null;
+      }
+      const socketId = ++nextSocketId;
+      await new Promise((resolve2, reject) => {
+        const ws = new WebSocket(this.url);
+        let settled = false;
+        ws.onopen = () => {
+          settled = true;
+          this.ws = ws;
+          this.wsId = socketId;
+          this.attachSocketHandlers(ws, socketId);
+          this.log(`ws#${socketId} opened and attached`);
+          resolve2();
+        };
+        ws.onerror = () => {
+          if (settled)
+            return;
+          settled = true;
+          reject(new Error(`Failed to connect to AgentBridge daemon at ${this.url}`));
+        };
+        ws.onclose = () => {
+          if (settled)
+            return;
+          settled = true;
+          reject(new Error(`AgentBridge daemon closed the connection during startup (${this.url})`));
+        };
+      });
     }
-    const lockAcquired = this.acquireLock();
-    if (!lockAcquired) {
-      this.log("Another process is starting the daemon, waiting for readiness...");
-      await this.waitForReady();
-      return;
+    attachClaude() {
+      this.send({
+        type: "claude_connect",
+        ...this.options.identity ? { identity: this.options.identity } : {}
+      });
+    }
+    async attachClaudeAndWaitForStatus(timeoutMs = 1000) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return null;
+      }
+      return await new Promise((resolve2) => {
+        let settled = false;
+        let timer = null;
+        const cleanup = () => {
+          if (settled)
+            return;
+          settled = true;
+          if (timer) {
+            clearTimeout(timer);
+            timer = null;
+          }
+          this.off("status", onStatus);
+          this.off("rejected", onRejected);
+          this.off("disconnect", onDisconnect);
+        };
+        const finish = (value) => {
+          cleanup();
+          resolve2(value);
+        };
+        const onStatus = (status) => finish(status);
+        const onRejected = () => finish(null);
+        const onDisconnect = () => finish(null);
+        this.on("status", onStatus);
+        this.on("rejected", onRejected);
+        this.on("disconnect", onDisconnect);
+        timer = setTimeout(() => {
+          finish(null);
+        }, timeoutMs);
+        try {
+          this.attachClaude();
+        } catch {
+          finish(null);
+        }
+      });
+    }
+    async probeIncumbent(timeoutMs = 3000) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return { connected: false, alive: false };
+      }
+      return await new Promise((resolve2) => {
+        let settled = false;
+        let timer = null;
+        const finish = (value) => {
+          if (settled)
+            return;
+          settled = true;
+          if (timer)
+            clearTimeout(timer);
+          this.off("incumbentStatus", onStatus);
+          this.off("disconnect", onDisconnect);
+          this.off("rejected", onRejected);
+          resolve2(value);
+        };
+        const onStatus = (s) => finish(s);
+        const onDisconnect = () => finish({ connected: false, alive: false });
+        const onRejected = () => finish({ connected: false, alive: false });
+        this.on("incumbentStatus", onStatus);
+        this.on("disconnect", onDisconnect);
+        this.on("rejected", onRejected);
+        timer = setTimeout(() => finish({ connected: false, alive: false }), timeoutMs);
+        try {
+          this.send({ type: "probe_incumbent" });
+        } catch {
+          finish({ connected: false, alive: false });
+        }
+      });
+    }
+    async disconnect() {
+      if (!this.ws)
+        return;
+      try {
+        this.send({ type: "claude_disconnect" });
+      } catch {}
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+      this.rejectPendingReplies("Daemon connection closed");
+    }
+    async sendReply(message, requireReply) {
+      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) => {
+        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 });
+        this.send({
+          type: "claude_to_codex",
+          requestId,
+          message,
+          ...requireReply ? { requireReply: true } : {}
+        });
+      });
+    }
+    attachSocketHandlers(ws, socketId) {
+      ws.onmessage = (event) => {
+        const raw = typeof event.data === "string" ? event.data : event.data.toString();
+        let message;
+        try {
+          message = JSON.parse(raw);
+        } catch {
+          return;
+        }
+        switch (message.type) {
+          case "codex_to_claude":
+            this.emit("codexMessage", message.message);
+            return;
+          case "claude_to_codex_result": {
+            const pending = this.pendingReplies.get(message.requestId);
+            if (!pending)
+              return;
+            clearTimeout(pending.timer);
+            this.pendingReplies.delete(message.requestId);
+            pending.resolve({ success: message.success, error: message.error });
+            return;
+          }
+          case "status":
+            this.emit("status", message.status);
+            return;
+          case "incumbent_status":
+            this.emit("incumbentStatus", { connected: message.connected, alive: message.alive });
+            return;
+        }
+      };
+      ws.onclose = (event) => {
+        const isCurrent = this.ws === ws;
+        this.log(`ws#${socketId} onclose (code=${event.code}, reason=${event.reason || "none"}, isCurrent=${isCurrent}, currentWsId=${this.wsId})`);
+        if (isCurrent) {
+          this.ws = null;
+          this.rejectPendingReplies("AgentBridge daemon disconnected.");
+          if (event.code === CLOSE_CODE_REPLACED || event.code === CLOSE_CODE_EVICTED_STALE || event.code === CLOSE_CODE_PROBE_IN_PROGRESS || event.code === CLOSE_CODE_PAIR_MISMATCH) {
+            this.emit("rejected", event.code);
+          } else {
+            this.emit("disconnect");
+          }
+        }
+      };
+      ws.onerror = () => {};
+    }
+    rejectPendingReplies(error) {
+      for (const [requestId, pending] of this.pendingReplies.entries()) {
+        clearTimeout(pending.timer);
+        pending.resolve({ success: false, error });
+        this.pendingReplies.delete(requestId);
+      }
+    }
+    send(message) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        throw new Error("AgentBridge daemon socket is not open.");
+      }
+      this.ws.send(JSON.stringify(message));
+    }
+    log(msg) {
+      process.stderr.write(`[${new Date().toISOString()}] [DaemonClient] ${msg}
+`);
     }
+  };
+});
+
+// src/contract-version.ts
+var CONTRACT_VERSION = 1;
+
+// src/build-info.ts
+function defineString(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function defineBundle(value) {
+  if (value === "source" || value === "dist" || value === "plugin")
+    return value;
+  return import.meta.url.endsWith(".ts") ? "source" : "dist";
+}
+function defineNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function sameRuntimeContract(a, b) {
+  if (!a || !b)
+    return false;
+  return a.version === b.version && a.commit === b.commit && a.contractVersion === b.contractVersion;
+}
+function compatibleContractVersion(a, b) {
+  if (!a || !b)
+    return false;
+  return a.contractVersion === b.contractVersion;
+}
+function formatBuildInfo(build) {
+  if (!build)
+    return "<unknown>";
+  return `${build.version}/${build.commit}/${build.bundle}/contract-v${build.contractVersion}`;
+}
+var BUILD_INFO;
+var init_build_info = __esm(() => {
+  BUILD_INFO = Object.freeze({
+    version: defineString("0.1.7", "0.0.0-source"),
+    commit: defineString("1df8b91", "source"),
+    bundle: defineBundle("dist"),
+    contractVersion: defineNumber(1, CONTRACT_VERSION)
+  });
+});
+
+// src/daemon-lifecycle.ts
+import { spawn, execFileSync as execFileSync4 } from "child_process";
+import { existsSync as existsSync5, readFileSync as readFileSync4, statSync, unlinkSync, writeFileSync as writeFileSync4, openSync, closeSync, constants } from "fs";
+import { fileURLToPath } from "url";
+
+class DaemonLifecycle {
+  stateDir;
+  controlPort;
+  log;
+  constructor(opts) {
+    this.stateDir = opts.stateDir;
+    this.controlPort = opts.controlPort;
+    this.log = opts.log;
+  }
+  get healthUrl() {
+    return `http://127.0.0.1:${this.controlPort}/healthz`;
+  }
+  get readyUrl() {
+    return `http://127.0.0.1:${this.controlPort}/readyz`;
+  }
+  get controlWsUrl() {
+    return `ws://127.0.0.1:${this.controlPort}/ws`;
+  }
+  get expectedPairId() {
+    return process.env.AGENTBRIDGE_PAIR_ID || null;
+  }
+  async fetchStatus() {
     try {
+      const response = await fetchWithTimeout(this.healthUrl);
+      if (!response.ok)
+        return null;
+      return await response.json();
+    } catch {
+      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);
+  }
+  canReuseDespiteDrift(status) {
+    if (!compatibleContractVersion(status?.build, BUILD_INFO))
+      return false;
+    return status?.tuiConnected === true;
+  }
+  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 {
+          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;
+        }
+      }
+      try {
+        await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
+        return;
+      } catch {
+        this.log(`Daemon on control port ${this.controlPort} is healthy but not ready within reuse window \u2014 replacing`);
+        await this.replaceUnhealthyDaemon(status?.pid);
+        return;
+      }
+    }
+    const existingPid = this.readPid();
+    if (existingPid) {
+      if (isProcessAlive(existingPid)) {
+        if (this.isDaemonProcess(existingPid)) {
+          try {
+            await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
+            return;
+          } catch {
+            this.log(`Existing daemon process ${existingPid} never became ready \u2014 replacing`);
+            await this.replaceUnhealthyDaemon(existingPid);
+            return;
+          }
+        }
+        this.log(`Pid ${existingPid} is alive but not an AgentBridge daemon, removing stale pid file`);
+      }
+      this.removeStalePidFile();
+    }
+    await this.withStartupLockStrict(async (locked) => {
+      if (!locked) {
+        this.log("Another process holds the startup lock, waiting for readiness+identity...");
+        await this.waitForReadyAndOurs();
+        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`);
+          await this.kill(3000, status?.pid);
+        } else {
+          try {
+            await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
+            return;
+          } catch {
+            this.log(`Daemon on control port ${this.controlPort} is healthy but not ready under startup lock \u2014 replacing`);
+            await this.kill(3000, status?.pid);
+          }
+        }
+      }
       this.launch();
       await this.waitForReady();
-    } finally {
-      this.releaseLock();
-    }
+    });
   }
   async isHealthy() {
     try {
-      const response = await fetch(this.healthUrl);
+      const response = await fetchWithTimeout(this.healthUrl);
       return response.ok;
     } catch {
       return false;
@@ -558,7 +1323,7 @@ class DaemonLifecycle {
   }
   async isReady() {
     try {
-      const response = await fetch(this.readyUrl);
+      const response = await fetchWithTimeout(this.readyUrl);
       return response.ok;
     } catch {
       return false;
@@ -572,9 +1337,21 @@ class DaemonLifecycle {
     }
     throw new Error(`Timed out waiting for AgentBridge daemon readiness on ${this.readyUrl}`);
   }
+  async waitForReadyAndOurs(maxRetries = 40, delayMs = 250) {
+    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))) {
+          return;
+        }
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+    }
+    throw new Error(`Timed out waiting for AgentBridge daemon readiness+identity on ${this.readyUrl} (control port ${this.controlPort})`);
+  }
   readStatus() {
     try {
-      const raw = readFileSync3(this.stateDir.statusFile, "utf-8");
+      const raw = readFileSync4(this.stateDir.statusFile, "utf-8");
       return JSON.parse(raw);
     } catch {
       return null;
@@ -582,12 +1359,12 @@ class DaemonLifecycle {
   }
   writeStatus(status) {
     this.stateDir.ensure();
-    writeFileSync3(this.stateDir.statusFile, JSON.stringify(status, null, 2) + `
+    writeFileSync4(this.stateDir.statusFile, JSON.stringify(status, null, 2) + `
 `, "utf-8");
   }
   readPid() {
     try {
-      const raw = readFileSync3(this.stateDir.pidFile, "utf-8").trim();
+      const raw = readFileSync4(this.stateDir.pidFile, "utf-8").trim();
       if (!raw)
         return null;
       const pid = Number.parseInt(raw, 10);
@@ -598,7 +1375,7 @@ class DaemonLifecycle {
   }
   writePid(pid) {
     this.stateDir.ensure();
-    writeFileSync3(this.stateDir.pidFile, `${pid ?? process.pid}
+    writeFileSync4(this.stateDir.pidFile, `${pid ?? process.pid}
 `, "utf-8");
   }
   removePidFile() {
@@ -613,7 +1390,7 @@ class DaemonLifecycle {
   }
   markKilled() {
     this.stateDir.ensure();
-    writeFileSync3(this.stateDir.killedFile, `${Date.now()}
+    writeFileSync4(this.stateDir.killedFile, `${Date.now()}
 `, "utf-8");
   }
   clearKilled() {
@@ -622,7 +1399,7 @@ class DaemonLifecycle {
     } catch {}
   }
   wasKilled() {
-    return existsSync4(this.stateDir.killedFile);
+    return existsSync5(this.stateDir.killedFile);
   }
   launch() {
     this.stateDir.ensure();
@@ -643,36 +1420,90 @@ class DaemonLifecycle {
     this.log("Removing stale pid file");
     this.removePidFile();
   }
-  acquireLock(depth = 0) {
-    if (depth > 1) {
-      this.log("Lock acquisition failed after retry, proceeding without lock");
-      return true;
+  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();
+        return;
+      }
+      if (await this.isHealthy()) {
+        const status = await this.fetchStatus();
+        if (!this.isForeignDaemon(status) && (!this.isBuildDrifted(status) || this.canReuseDespiteDrift(status))) {
+          try {
+            await this.waitForReady(REUSE_READY_RETRIES, REUSE_READY_DELAY_MS);
+            return;
+          } catch {}
+        }
+      }
+      this.log(`Killing unhealthy daemon on control port ${this.controlPort} and relaunching`);
+      await this.kill(3000, statusPid);
+      this.launch();
+      await this.waitForReady();
+    });
+  }
+  async withStartupLockStrict(fn) {
+    const locked = this.acquireLockStrict();
+    try {
+      return await fn(locked);
+    } finally {
+      if (locked)
+        this.releaseLock();
     }
+  }
+  acquireLockStrict(reclaimed = false) {
     this.stateDir.ensure();
+    let fd = null;
     try {
-      const fd = openSync(this.stateDir.lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
-      writeFileSync3(fd, `${process.pid}
+      fd = openSync(this.stateDir.lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+      writeFileSync4(fd, `${process.pid}
 `);
       closeSync(fd);
       return true;
     } catch (err) {
+      if (fd !== null && err.code !== "EEXIST") {
+        try {
+          closeSync(fd);
+        } catch {}
+        this.releaseLock();
+      }
       if (err.code === "EEXIST") {
+        if (reclaimed)
+          return false;
         try {
-          const holderPid = Number.parseInt(readFileSync3(this.stateDir.lockFile, "utf-8").trim(), 10);
+          const holderPid = Number.parseInt(readFileSync4(this.stateDir.lockFile, "utf-8").trim(), 10);
           if (Number.isFinite(holderPid) && !isProcessAlive(holderPid)) {
-            this.log(`Stale lock file from dead process ${holderPid}, removing`);
+            this.log(`Stale startup lock from dead process ${holderPid}, reclaiming`);
+            this.releaseLock();
+            return this.acquireLockStrict(true);
+          }
+          if (Number.isFinite(holderPid) && this.lockAgeMs() > LOCK_IDENTITY_GRACE_MS && !this.isAgentBridgeProcess(holderPid)) {
+            this.log(`Startup lock is ${Math.round(this.lockAgeMs() / 1000)}s old and holder pid ${holderPid} ` + `is an unrelated process (pid recycled), reclaiming`);
             this.releaseLock();
-            return this.acquireLock(depth + 1);
+            return this.acquireLockStrict(true);
           }
         } catch {
-          this.log("Cannot read lock file, removing stale lock");
-          this.releaseLock();
-          return this.acquireLock(depth + 1);
+          return false;
         }
         return false;
       }
-      this.log(`Warning: could not acquire startup lock: ${err.message}`);
-      return true;
+      this.log(`Could not acquire strict startup lock: ${err.message}`);
+      return false;
+    }
+  }
+  lockAgeMs() {
+    try {
+      return Date.now() - statSync(this.stateDir.lockFile).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+  isAgentBridgeProcess(pid) {
+    try {
+      const cmd = execFileSync4("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf-8" }).trim();
+      return cmd.includes("agentbridge") || cmd.includes("agent_bridge");
+    } catch {
+      return false;
     }
   }
   releaseLock() {
@@ -680,8 +1511,8 @@ class DaemonLifecycle {
       unlinkSync(this.stateDir.lockFile);
     } catch {}
   }
-  async kill(gracefulTimeoutMs = 3000) {
-    const pid = this.readPid();
+  async kill(gracefulTimeoutMs = 3000, pidOverride) {
+    const pid = pidOverride ?? this.readPid();
     if (!pid) {
       this.log("No daemon pid file found");
       this.cleanup();
@@ -723,7 +1554,9 @@ class DaemonLifecycle {
   isDaemonProcess(pid) {
     try {
       const cmd = execFileSync4("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf-8" }).trim();
-      return cmd.includes("daemon") && (cmd.includes("agentbridge") || cmd.includes("agent_bridge"));
+      const hasDaemonEntry = /(?:^|[\s/\\])[\w.-]*-?daemon\.(?:ts|js)(?:\s|$)/.test(cmd);
+      const hasAgentbridge = cmd.includes("agentbridge") || cmd.includes("agent_bridge");
+      return hasDaemonEntry && hasAgentbridge;
     } catch {
       return false;
     }
@@ -731,7 +1564,15 @@ class DaemonLifecycle {
   cleanup() {
     this.removePidFile();
     this.removeStatusFile();
-    this.releaseLock();
+  }
+}
+async function fetchWithTimeout(url, timeoutMs = HEALTH_FETCH_TIMEOUT_MS) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
   }
 }
 function isProcessAlive(pid) {
@@ -742,87 +1583,910 @@ function isProcessAlive(pid) {
     return false;
   }
 }
-var DAEMON_ENTRY, DAEMON_PATH;
+var DEFAULT_DAEMON_ENTRY, DAEMON_ENTRY, DAEMON_PATH, REUSE_READY_RETRIES, REUSE_READY_DELAY_MS = 250, HEALTH_FETCH_TIMEOUT_MS = 500, LOCK_IDENTITY_GRACE_MS;
 var init_daemon_lifecycle = __esm(() => {
-  DAEMON_ENTRY = process.env.AGENTBRIDGE_DAEMON_ENTRY ?? "./daemon.ts";
+  init_build_info();
+  DEFAULT_DAEMON_ENTRY = import.meta.url.endsWith(".ts") ? "./daemon.ts" : "./daemon.js";
+  DAEMON_ENTRY = process.env.AGENTBRIDGE_DAEMON_ENTRY || DEFAULT_DAEMON_ENTRY;
   DAEMON_PATH = fileURLToPath(new URL(DAEMON_ENTRY, import.meta.url));
+  REUSE_READY_RETRIES = parsePositiveIntEnv("AGENTBRIDGE_REUSE_READY_RETRIES", 12);
+  LOCK_IDENTITY_GRACE_MS = parsePositiveIntEnv("AGENTBRIDGE_LOCK_IDENTITY_GRACE_MS", 120000);
 });
 
-// src/state-dir.ts
-import { mkdirSync as mkdirSync2, existsSync as existsSync5 } from "fs";
-import { join as join4 } from "path";
-import { homedir as homedir2, platform } from "os";
-
-class StateDirResolver {
-  stateDir;
-  constructor(envOverride) {
-    const override = envOverride ?? process.env.AGENTBRIDGE_STATE_DIR;
-    if (override) {
-      this.stateDir = override;
-    } else if (platform() === "darwin") {
-      this.stateDir = join4(homedir2(), "Library", "Application Support", "AgentBridge");
-    } else {
-      const xdgState = process.env.XDG_STATE_HOME ?? join4(homedir2(), ".local", "state");
-      this.stateDir = join4(xdgState, "agentbridge");
-    }
+// src/pair-registry.ts
+import { execFileSync as execFileSync5 } from "child_process";
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync6,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync as mkdirSync3,
+  openSync as openSync2,
+  readdirSync,
+  readFileSync as readFileSync5,
+  realpathSync,
+  renameSync,
+  rmSync as rmSync2,
+  statSync as statSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync5
+} from "fs";
+import { createServer } from "net";
+import { createHash, randomUUID } from "crypto";
+import { hostname, userInfo } from "os";
+import { basename, join as join5, resolve as resolve2, sep } from "path";
+function portsForSlot(slot) {
+  if (!Number.isInteger(slot) || slot < 0) {
+    throw new PairError("PAIR_ID_INVALID", `Invalid slot: ${slot}`);
   }
-  ensure() {
-    if (!existsSync5(this.stateDir)) {
-      mkdirSync2(this.stateDir, { recursive: true });
-    }
+  if (slot > MAX_PAIR_SLOT) {
+    throw new PairError("PAIR_ID_INVALID", `Slot ${slot} exceeds the maximum (${MAX_PAIR_SLOT}); ports would overflow 65535.`, { slot, maxSlot: MAX_PAIR_SLOT });
   }
-  get dir() {
-    return this.stateDir;
+  const base = PAIR_BASE_PORT + slot * PAIR_SLOT_STRIDE;
+  return { appPort: base, proxyPort: base + 1, controlPort: base + 2 };
+}
+function validatePairId(raw) {
+  const id = raw.trim();
+  const deviceBase = id.split(".")[0] ?? "";
+  if (id === "." || id === ".." || !PAIR_ID_REGEX.test(id) || id.endsWith(".") || WINDOWS_RESERVED_RE.test(deviceBase)) {
+    throw new PairError("PAIR_ID_INVALID", `Invalid --pair name: ${JSON.stringify(raw)}. Allowed: letters, digits, "." "_" "-", 1-64 chars ` + `(not "." / ".." / a trailing dot / a reserved name like CON, NUL, COM1).`, { raw });
   }
-  get pidFile() {
-    return join4(this.stateDir, "daemon.pid");
+  return id;
+}
+function derivePairId(cwd, name) {
+  let real;
+  try {
+    real = realpathSync(cwd);
+  } catch {
+    real = cwd;
   }
-  get tuiPidFile() {
-    return join4(this.stateDir, "codex-tui.pid");
+  const hash = createHash("sha256").update(real).update("\x00").update(name.toLowerCase()).digest("hex").slice(0, 8);
+  const slug = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "pair";
+  return `${slug}-${hash}`;
+}
+function pickLowestFreeSlot(entries) {
+  const used = new Set(entries.map((e) => e.slot));
+  let slot = 0;
+  while (used.has(slot))
+    slot++;
+  return slot;
+}
+function pairsDir(base) {
+  return join5(base, "pairs");
+}
+function registryPath(base) {
+  return join5(pairsDir(base), REGISTRY_FILE_NAME);
+}
+function readRegistry(base) {
+  const path = registryPath(base);
+  if (!existsSync6(path))
+    return { version: 1, pairs: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync5(path, "utf-8"));
+  } catch (err) {
+    throw new PairError("PAIR_REGISTRY_CORRUPT", `Registry JSON is not parseable at ${path}: ${err.message}`, {
+      path
+    });
   }
-  get lockFile() {
-    return join4(this.stateDir, "daemon.lock");
+  if (!parsed || typeof parsed !== "object" || parsed.version !== 1 || !Array.isArray(parsed.pairs)) {
+    throw new PairError("PAIR_REGISTRY_CORRUPT", `Registry shape is invalid at ${path}`, { path });
   }
-  get statusFile() {
-    return join4(this.stateDir, "status.json");
+  const entries = parsed.pairs;
+  const seenSlots = new Set;
+  const seenIds = new Set;
+  for (const e of entries) {
+    const idValid = e && typeof e.pairId === "string" && e.pairId !== "." && e.pairId !== ".." && PAIR_ID_REGEX.test(e.pairId);
+    if (!idValid || !Number.isInteger(e.slot) || e.slot < 0) {
+      throw new PairError("PAIR_REGISTRY_CORRUPT", `Registry has a malformed entry at ${path}`, { path, entry: e });
+    }
+    const lower = e.pairId.toLowerCase();
+    if (seenSlots.has(e.slot) || seenIds.has(lower)) {
+      throw new PairError("PAIR_REGISTRY_CORRUPT", `Registry has duplicate slot/pairId at ${path}`, {
+        path,
+        pairId: e.pairId,
+        slot: e.slot
+      });
+    }
+    seenSlots.add(e.slot);
+    seenIds.add(lower);
   }
-  get portsFile() {
-    return join4(this.stateDir, "ports.json");
+  return parsed;
+}
+function writeRegistry(base, reg) {
+  mkdirSync3(pairsDir(base), { recursive: true });
+  const target = registryPath(base);
+  const tmp = `${target}.tmp.${process.pid}`;
+  const data = JSON.stringify(reg, null, 2) + `
+`;
+  const fd = openSync2(tmp, "w");
+  try {
+    writeFileSync5(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync2(fd);
   }
-  get logFile() {
-    return join4(this.stateDir, "agentbridge.log");
+  renameSync(tmp, target);
+}
+function lockFilePath(base) {
+  return join5(pairsDir(base), LOCK_FILE_NAME);
+}
+function readLockOwner(lockFile) {
+  try {
+    const parsed = JSON.parse(readFileSync5(lockFile, "utf-8"));
+    if (typeof parsed.pid === "number" && typeof parsed.nonce === "string")
+      return parsed;
+    return null;
+  } catch {
+    return null;
   }
-  get codexWrapperLogFile() {
-    return join4(this.stateDir, "codex-wrapper.log");
+}
+function pidLooksAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
   }
-  get killedFile() {
-    return join4(this.stateDir, "killed");
+}
+function lockFileAgeMs(lockFile) {
+  try {
+    return Date.now() - statSync2(lockFile).mtimeMs;
+  } catch {
+    return Number.POSITIVE_INFINITY;
   }
 }
-var init_state_dir = () => {};
-
-// src/cli/claude.ts
-var exports_claude = {};
-__export(exports_claude, {
-  runClaude: () => runClaude,
-  checkOwnedFlagConflicts: () => checkOwnedFlagConflicts
-});
-import { spawn as spawn2 } from "child_process";
-async function runClaude(args) {
-  checkOwnedFlagConflicts(args, "agentbridge claude", OWNED_FLAGS);
-  const stateDir = new StateDirResolver;
-  const controlPort = parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
-  const lifecycle = new DaemonLifecycle({
-    stateDir,
-    controlPort,
-    log: (msg) => console.error(`[agentbridge] ${msg}`)
-  });
-  lifecycle.clearKilled();
-  const channelEntry = `plugin:${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+function safeHostname() {
+  try {
+    return hostname();
+  } catch {
+    return;
+  }
+}
+function safeUid() {
+  try {
+    return userInfo().uid;
+  } catch {
+    return;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function lockIsStale(lockFile) {
+  const owner = readLockOwner(lockFile);
+  if (owner)
+    return !pidLooksAlive(owner.pid);
+  return lockFileAgeMs(lockFile) > ORPHAN_GRACE_MS;
+}
+function attemptReclaim(lockFile) {
+  const reclaimLock = `${lockFile}.reclaim`;
+  const myNonce = randomUUID();
+  const ownerJson = JSON.stringify({
+    pid: process.pid,
+    createdAt: Date.now(),
+    nonce: myNonce,
+    hostname: safeHostname(),
+    uid: safeUid()
+  });
+  const tmp = `${reclaimLock}.acq.${process.pid}.${randomUUID()}`;
+  let held = false;
+  try {
+    writeFileSync5(tmp, ownerJson);
+    try {
+      linkSync(tmp, reclaimLock);
+      held = true;
+    } catch (err) {
+      if (err?.code === "EEXIST") {
+        if (lockIsStale(reclaimLock)) {
+          try {
+            unlinkSync2(reclaimLock);
+          } catch {}
+        }
+        return;
+      }
+      throw err;
+    }
+  } finally {
+    try {
+      unlinkSync2(tmp);
+    } catch {}
+  }
+  if (!held)
+    return;
+  try {
+    if (readLockOwner(reclaimLock)?.nonce !== myNonce)
+      return;
+    if (lockIsStale(lockFile)) {
+      try {
+        unlinkSync2(lockFile);
+      } catch {}
+    }
+  } finally {
+    if (readLockOwner(reclaimLock)?.nonce === myNonce) {
+      try {
+        unlinkSync2(reclaimLock);
+      } catch {}
+    }
+  }
+}
+async function withRegistryLock(base, fn) {
+  mkdirSync3(pairsDir(base), { recursive: true });
+  const lockFile = lockFilePath(base);
+  const deadline = Date.now() + LOCK_DEADLINE_MS;
+  const myNonce = randomUUID();
+  const ownerJson = JSON.stringify({
+    pid: process.pid,
+    createdAt: Date.now(),
+    nonce: myNonce,
+    hostname: safeHostname(),
+    uid: safeUid()
+  });
+  for (;; ) {
+    const tmp = `${lockFile}.acq.${process.pid}.${randomUUID()}`;
+    let acquired = false;
+    try {
+      writeFileSync5(tmp, ownerJson);
+      try {
+        linkSync(tmp, lockFile);
+        acquired = true;
+      } catch (err) {
+        if (err?.code !== "EEXIST")
+          throw err;
+      }
+    } finally {
+      try {
+        unlinkSync2(tmp);
+      } catch {}
+    }
+    if (acquired) {
+      try {
+        return await fn();
+      } finally {
+        const current = readLockOwner(lockFile);
+        if (!current || current.nonce === myNonce) {
+          try {
+            unlinkSync2(lockFile);
+          } catch {}
+        }
+      }
+    }
+    if (lockIsStale(lockFile)) {
+      attemptReclaim(lockFile);
+    }
+    if (Date.now() >= deadline) {
+      throw new PairError("PAIR_LOCK_TIMEOUT", `Timed out acquiring registry lock at ${lockFile}`, {
+        holderPid: readLockOwner(lockFile)?.pid
+      });
+    }
+    await sleep(25 + Math.floor(Math.random() * 50));
+  }
+}
+function isDaemonProcess(pid) {
+  try {
+    const cmd = execFileSync5("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf-8" }).trim();
+    return cmd.includes("daemon") && (cmd.includes("agentbridge") || cmd.includes("agent_bridge"));
+  } catch {
+    return false;
+  }
+}
+function detectLegacyRootDaemon(base) {
+  const rootPidFile = join5(base, "daemon.pid");
+  if (!existsSync6(rootPidFile))
+    return null;
+  let pid;
+  try {
+    const raw = readFileSync5(rootPidFile, "utf-8").trim();
+    pid = Number.parseInt(raw, 10);
+  } catch {
+    return null;
+  }
+  if (!Number.isFinite(pid) || !pidLooksAlive(pid) || !isDaemonProcess(pid))
+    return null;
+  return { pid, controlPort: LEGACY_ROOT_CONTROL_PORT };
+}
+function probePortFree(port) {
+  return new Promise((resolve3) => {
+    const server = createServer();
+    server.once("error", () => resolve3(false));
+    server.once("listening", () => {
+      server.close(() => resolve3(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+function pidOnPort(port) {
+  try {
+    const out = execFileSync5("lsof", ["-ti", `:${port}`, "-sTCP:LISTEN"], { encoding: "utf-8" }).trim();
+    const first = out.split(/\s+/)[0];
+    const pid = Number.parseInt(first ?? "", 10);
+    return Number.isFinite(pid) ? pid : undefined;
+  } catch {
+    return;
+  }
+}
+async function resolvePair(base, opts) {
+  const hasFlag = opts.pairFlag != null;
+  const name = hasFlag ? validatePairId(opts.pairFlag) : DEFAULT_PAIR_NAME;
+  const pairId = derivePairId(opts.cwd, name);
+  const source = hasFlag ? "flag" : "cwd";
+  const lower = pairId.toLowerCase();
+  const flagLower = name.toLowerCase();
+  const allocation = await withRegistryLock(base, () => {
+    const reg = readRegistry(base);
+    const scoped = reg.pairs.find((p) => p.pairId.toLowerCase() === lower);
+    if (scoped)
+      return { slot: scoped.slot, entry: scoped, isNew: false, matchedRaw: false };
+    if (hasFlag) {
+      const raw = reg.pairs.find((p) => p.pairId.toLowerCase() === flagLower);
+      if (raw) {
+        if (raw.cwd === opts.cwd) {
+          return { slot: raw.slot, entry: raw, isNew: false, matchedRaw: true };
+        }
+        return { crossCwd: raw };
+      }
+    }
+    const newSlot = pickLowestFreeSlot(reg.pairs);
+    if (newSlot === 0) {
+      const legacy = detectLegacyRootDaemon(base);
+      if (legacy) {
+        throw new PairError("PAIR_LEGACY_ROOT_DAEMON", `A pre-multi-pair AgentBridge daemon is running at the legacy location ` + `(pid ${legacy.pid}, control port ${legacy.controlPort}). Run "abg kill" to stop it, then retry \u2014 ` + `your new session would otherwise collide on port ${legacy.controlPort}.`, { pid: legacy.pid, controlPort: legacy.controlPort });
+      }
+    }
+    portsForSlot(newSlot);
+    const newEntry = {
+      pairId,
+      slot: newSlot,
+      cwd: opts.cwd,
+      name,
+      source,
+      createdAt: new Date().toISOString()
+    };
+    writeRegistry(base, { version: 1, pairs: [...reg.pairs, newEntry] });
+    return { slot: newSlot, entry: newEntry, isNew: true, matchedRaw: false };
+  });
+  if ("crossCwd" in allocation) {
+    const raw = allocation.crossCwd;
+    throw new PairError("PAIR_CROSS_CWD", `--pair ${opts.pairFlag ?? name} refers to pair "${raw.pairId}" registered for ${raw.cwd}, ` + `but you are in ${opts.cwd}. A pair is scoped to its directory \u2014 cd into that directory ` + `to use it, or pass a short name to create/use a pair here.`, { pairId: raw.pairId, registeredCwd: raw.cwd, cwd: opts.cwd });
+  }
+  const { slot, entry, isNew, matchedRaw } = allocation;
+  const ports = portsForSlot(slot);
+  if (isNew && opts.probePorts !== false) {
+    for (const port of [ports.appPort, ports.proxyPort, ports.controlPort]) {
+      if (!await probePortFree(port)) {
+        await removeAllocatedPairIfUnchanged(base, pairId, slot);
+        throw new PairError("PAIR_PORTS_BUSY", `Port ${port} (pair "${pairId}", slot ${slot}) is already in use by another process. ` + `Free it or remove the conflicting pair; AgentBridge will not silently move slots.`, { port, slot, pairId, pid: pidOnPort(port) });
+      }
+    }
+  }
+  let warning;
+  if (isNew && hasFlag && /-[0-9a-f]{8}$/i.test(name)) {
+    warning = `--pair ${opts.pairFlag ?? name} looks like a full pair id, but no registered pair matched; ` + `creating a NEW pair named "${name}". Pass a short name (e.g. "main") or run \`abg pairs\` ` + `to see existing pairs.`;
+  }
+  return {
+    pairId: entry.pairId,
+    slot,
+    ports,
+    stateDir: join5(pairsDir(base), entry.pairId),
+    name: entry.name ?? name,
+    entry,
+    warning
+  };
+}
+async function removeAllocatedPairIfUnchanged(base, pairId, slot) {
+  await withRegistryLock(base, () => {
+    if (existsSync6(pairDirPath(base, pairId)) || pairDirDaemonAlive(base, pairId))
+      return;
+    const reg = readRegistry(base);
+    const nextPairs = reg.pairs.filter((pair) => !(pair.pairId === pairId && pair.slot === slot));
+    if (nextPairs.length === reg.pairs.length)
+      return;
+    writeRegistry(base, { version: 1, pairs: nextPairs });
+  });
+}
+function pairDirPath(base, pairId) {
+  const id = validatePairId(pairId);
+  return join5(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);
+  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))
+    return false;
+  rmSync2(canonicalDir, { recursive: true, force: true });
+  return true;
+}
+function assertPairsRootNotSymlinked(root) {
+  let stat;
+  try {
+    stat = lstatSync(root);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new PairError("PAIR_ID_INVALID", `Refusing to operate through a symlinked pairs root: ${root}`, { root });
+  }
+}
+function listPairDirs(base) {
+  const root = pairsDir(base);
+  if (!existsSync6(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 pids = [];
+  try {
+    const pid = Number.parseInt(readFileSync5(join5(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"));
+    if (typeof status?.pid === "number")
+      pids.push(status.pid);
+  } catch {}
+  return pids.some((pid) => pidLooksAlive(pid));
+}
+async function removePairEntryAndDir(base, pairId) {
+  const lower = pairId.toLowerCase();
+  return withRegistryLock(base, () => {
+    const reg = readRegistry(base);
+    const found = reg.pairs.find((p) => p.pairId.toLowerCase() === lower) ?? null;
+    if (pairDirDaemonAlive(base, pairId)) {
+      return { entry: found, dirRemoved: false, keptLive: true };
+    }
+    const dirRemoved = removePairDir(base, pairId);
+    if (found) {
+      writeRegistry(base, { version: 1, pairs: reg.pairs.filter((p) => p.pairId.toLowerCase() !== lower) });
+    }
+    return { entry: found, dirRemoved, keptLive: false };
+  });
+}
+async function removeUnregisteredPairDir(base, pairId) {
+  const lower = pairId.toLowerCase();
+  return withRegistryLock(base, () => {
+    const reg = readRegistry(base);
+    if (reg.pairs.some((p) => p.pairId.toLowerCase() === lower)) {
+      return { removed: false, reason: "registered" };
+    }
+    if (pairDirDaemonAlive(base, pairId)) {
+      return { removed: false, reason: "live" };
+    }
+    return { removed: removePairDir(base, pairId) };
+  });
+}
+var PAIR_BASE_PORT = 4500, PAIR_SLOT_STRIDE = 10, PAIR_ID_REGEX, DEFAULT_PAIR_NAME = "main", LOCK_FILE_NAME = ".registry.lock", REGISTRY_FILE_NAME = "registry.json", LOCK_DEADLINE_MS = 1e4, ORPHAN_GRACE_MS = 3000, LEGACY_ROOT_CONTROL_PORT = 4502, WINDOWS_RESERVED_RE, PairError, MAX_PAIR_SLOT;
+var init_pair_registry = __esm(() => {
+  PAIR_ID_REGEX = /^[A-Za-z0-9._-]{1,64}$/;
+  WINDOWS_RESERVED_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+  PairError = class PairError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+      super(message);
+      this.name = "PairError";
+      this.code = code;
+      this.details = details;
+    }
+  };
+  MAX_PAIR_SLOT = Math.floor((65535 - 2 - PAIR_BASE_PORT) / PAIR_SLOT_STRIDE);
+});
+
+// src/env-guard.ts
+function normalizeEnvGuardMode(raw, fallback = "fix") {
+  if (raw === "off" || raw === "warn" || raw === "fix" || raw === "strict")
+    return raw;
+  return fallback;
+}
+function inspectAgentBridgeEnv(opts) {
+  const env = opts.env ?? process.env;
+  const actualPairId = nonEmpty(env.AGENTBRIDGE_PAIR_ID);
+  const pairName = nonEmpty(env.AGENTBRIDGE_PAIR_NAME) ?? "main";
+  const stateDir = nonEmpty(env.AGENTBRIDGE_STATE_DIR);
+  const baseDir = nonEmpty(env.AGENTBRIDGE_BASE_DIR);
+  const manualOptIn = env.AGENTBRIDGE_MANUAL === "1";
+  const manualRuntimeEnv = !!stateDir || !!nonEmpty(env.AGENTBRIDGE_CONTROL_PORT) || !!nonEmpty(env.CODEX_WS_PORT) || !!nonEmpty(env.CODEX_PROXY_PORT);
+  const expectedPairId = actualPairId ? derivePairId(opts.cwd, pairName) : null;
+  const reasons = [];
+  if (!actualPairId && manualRuntimeEnv && !manualOptIn) {
+    reasons.push("AgentBridge runtime env is set without AGENTBRIDGE_PAIR_ID or AGENTBRIDGE_MANUAL=1");
+  }
+  if (actualPairId && expectedPairId && actualPairId !== expectedPairId) {
+    reasons.push(`AGENTBRIDGE_PAIR_ID=${actualPairId} does not match cwd-derived ${expectedPairId}`);
+  }
+  if (actualPairId && stateDir && !stateDir.endsWith(`/pairs/${actualPairId}`)) {
+    reasons.push(`AGENTBRIDGE_STATE_DIR does not end with /pairs/${actualPairId}`);
+  }
+  if (actualPairId && baseDir && stateDir && !stateDir.startsWith(`${baseDir}/`)) {
+    reasons.push("AGENTBRIDGE_BASE_DIR and AGENTBRIDGE_STATE_DIR disagree");
+  }
+  return {
+    ok: reasons.length === 0,
+    expectedPairId,
+    actualPairId,
+    pairName,
+    reasons
+  };
+}
+function guardAgentBridgeEnv(opts) {
+  const env = opts.env ?? process.env;
+  const mode = normalizeEnvGuardMode(opts.mode, "fix");
+  const effectiveMode = mode === "strict" && opts.allowStrict === false ? "fix" : mode;
+  const inspection = inspectAgentBridgeEnv({ cwd: opts.cwd, env });
+  if (effectiveMode === "off" || inspection.ok) {
+    return { ...inspection, action: "none" };
+  }
+  const message = `stale AgentBridge environment detected for ${opts.cwd}: ${inspection.reasons.join("; ")}`;
+  if (effectiveMode === "strict") {
+    throw new Error(message);
+  }
+  opts.log?.(`[agentbridge] ${message}`);
+  if (effectiveMode === "warn") {
+    return { ...inspection, action: "warned" };
+  }
+  for (const key of GENERATED_ENV_KEYS) {
+    delete env[key];
+  }
+  opts.log?.("[agentbridge] cleared stale AgentBridge environment variables");
+  return { ...inspection, action: "fixed" };
+}
+function nonEmpty(value) {
+  return value && value.length > 0 ? value : null;
+}
+var GENERATED_ENV_KEYS;
+var init_env_guard = __esm(() => {
+  init_pair_registry();
+  GENERATED_ENV_KEYS = [
+    "AGENTBRIDGE_BASE_DIR",
+    "AGENTBRIDGE_PAIR_ID",
+    "AGENTBRIDGE_PAIR_NAME",
+    "AGENTBRIDGE_STATE_DIR",
+    "AGENTBRIDGE_CONTROL_PORT",
+    "AGENTBRIDGE_MODE",
+    "AGENTBRIDGE_FILTER_MODE",
+    "AGENTBRIDGE_MAX_BUFFERED_MESSAGES",
+    "AGENTBRIDGE_CODEX_TRANSPORT",
+    "CODEX_WS_PORT",
+    "CODEX_PROXY_PORT"
+  ];
+});
+
+// src/pair-resolver.ts
+import { realpathSync as realpathSync2 } from "fs";
+import { join as join6, resolve as resolve3 } from "path";
+function computeBaseDir() {
+  return process.env.AGENTBRIDGE_BASE_DIR || process.env.AGENTBRIDGE_STATE_DIR || StateDirResolver.platformBaseDir();
+}
+function parsePairFlag(args) {
+  const rest = [];
+  let pairFlag;
+  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("-")) {
+        pairFlag = next;
+        i++;
+      } else {
+        pairFlag = "";
+      }
+      continue;
+    }
+    if (a.startsWith("--pair=")) {
+      pairFlag = a.slice("--pair=".length);
+      continue;
+    }
+    rest.push(a);
+  }
+  return { pairFlag, rest };
+}
+function parseKillArgs(args) {
+  let all = false;
+  let pairFlag;
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "all") {
+      all = true;
+      continue;
+    }
+    if (a === "--all") {
+      all = true;
+      continue;
+    }
+    if (a === "--pair") {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        pairFlag = next;
+        i++;
+      } else {
+        pairFlag = "";
+      }
+      continue;
+    }
+    if (a.startsWith("--pair=")) {
+      pairFlag = a.slice("--pair=".length);
+    }
+  }
+  return { all, pairFlag };
+}
+async function applyPairEnv(opts) {
+  const explicitEnv = !!process.env.AGENTBRIDGE_STATE_DIR || !!process.env.AGENTBRIDGE_CONTROL_PORT || !!process.env.CODEX_WS_PORT || !!process.env.CODEX_PROXY_PORT;
+  if (opts.pairFlag === undefined && explicitEnv && process.env.AGENTBRIDGE_MANUAL === "1") {
+    const stateDir = new StateDirResolver;
+    const controlPort = Number.parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
+    const appPort = Number.parseInt(process.env.CODEX_WS_PORT ?? "4500", 10);
+    const proxyPort = Number.parseInt(process.env.CODEX_PROXY_PORT ?? "4501", 10);
+    return {
+      pairId: "(manual)",
+      slot: null,
+      ports: { appPort, proxyPort, controlPort },
+      stateDir,
+      name: "(manual)",
+      manual: true
+    };
+  }
+  const base = computeBaseDir();
+  const resolved = await resolvePair(base, { pairFlag: opts.pairFlag, cwd: process.cwd() });
+  process.env.AGENTBRIDGE_BASE_DIR = base;
+  process.env.AGENTBRIDGE_PAIR_ID = resolved.pairId;
+  process.env.AGENTBRIDGE_PAIR_NAME = resolved.name;
+  process.env.AGENTBRIDGE_STATE_DIR = resolved.stateDir;
+  process.env.AGENTBRIDGE_CONTROL_PORT = String(resolved.ports.controlPort);
+  process.env.CODEX_WS_PORT = String(resolved.ports.appPort);
+  process.env.CODEX_PROXY_PORT = String(resolved.ports.proxyPort);
+  return {
+    pairId: resolved.pairId,
+    slot: resolved.slot,
+    ports: resolved.ports,
+    stateDir: new StateDirResolver(resolved.stateDir),
+    name: resolved.name,
+    manual: false,
+    warning: resolved.warning
+  };
+}
+function resolvePairReadOnly(pairFlag) {
+  const explicitEnv = !!process.env.AGENTBRIDGE_STATE_DIR || !!process.env.AGENTBRIDGE_CONTROL_PORT || !!process.env.CODEX_WS_PORT || !!process.env.CODEX_PROXY_PORT;
+  if (pairFlag === undefined && explicitEnv && process.env.AGENTBRIDGE_MANUAL === "1") {
+    return {
+      registered: true,
+      pair: {
+        pairId: "(manual)",
+        slot: null,
+        ports: {
+          appPort: Number.parseInt(process.env.CODEX_WS_PORT ?? "4500", 10),
+          proxyPort: Number.parseInt(process.env.CODEX_PROXY_PORT ?? "4501", 10),
+          controlPort: Number.parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10)
+        },
+        stateDir: new StateDirResolver,
+        name: "(manual)",
+        manual: true
+      }
+    };
+  }
+  const base = computeBaseDir();
+  const cwd = process.cwd();
+  const name = pairFlag ?? "main";
+  let entry = null;
+  try {
+    entry = findPairForFlag(base, cwd, name);
+  } catch (err) {
+    if (err instanceof PairError && err.code === "PAIR_ID_INVALID")
+      throw err;
+  }
+  if (entry) {
+    return {
+      registered: true,
+      pair: {
+        pairId: entry.pairId,
+        slot: entry.slot,
+        ports: portsForEntry(entry),
+        stateDir: new StateDirResolver(join6(base, "pairs", entry.pairId)),
+        name: entry.name ?? name,
+        manual: false
+      }
+    };
+  }
+  const pairId = derivePairId(cwd, name);
+  return {
+    registered: false,
+    pair: {
+      pairId,
+      slot: null,
+      ports: { appPort: 0, proxyPort: 0, controlPort: 0 },
+      stateDir: new StateDirResolver(join6(base, "pairs", pairId)),
+      name,
+      manual: false
+    }
+  };
+}
+function listPairs(base) {
+  return readRegistry(base).pairs;
+}
+function listPairsForCwd(base, cwd) {
+  const canonicalCwd = canonicalizeCwd(cwd);
+  return listPairs(base).filter((pair) => canonicalizeCwd(pair.cwd) === canonicalCwd);
+}
+function findPair(base, pairId) {
+  const lower = pairId.toLowerCase();
+  return readRegistry(base).pairs.find((p) => p.pairId.toLowerCase() === lower) ?? null;
+}
+function findPairForFlag(base, cwd, flag) {
+  const name = validatePairId(flag);
+  const scopedId = derivePairId(cwd, name);
+  const scoped = findPair(base, scopedId);
+  if (scoped)
+    return scoped;
+  const raw = findPair(base, name);
+  return raw && raw.cwd === cwd ? raw : null;
+}
+function portsForEntry(entry) {
+  return portsForSlot(entry.slot);
+}
+function canonicalizeCwd(cwd) {
+  const absolute = resolve3(cwd);
+  try {
+    return realpathSync2.native(absolute);
+  } catch {
+    try {
+      return realpathSync2(absolute);
+    } catch {
+      return absolute;
+    }
+  }
+}
+var init_pair_resolver = __esm(() => {
+  init_state_dir();
+  init_pair_registry();
+});
+
+// src/trace-log.ts
+import { appendFileSync, mkdirSync as mkdirSync4 } from "fs";
+import { join as join7 } from "path";
+function pickRelevantEnv(env) {
+  const picked = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!RELEVANT_ENV_RE.test(key))
+      continue;
+    picked[key] = SECRET_KEY_RE.test(key) && value !== undefined ? "<redacted>" : value;
+  }
+  return picked;
+}
+function redactArgv(argv) {
+  const redacted = [];
+  let redactNext = false;
+  for (const arg of argv) {
+    if (redactNext) {
+      redacted.push("<redacted>");
+      redactNext = false;
+      continue;
+    }
+    if (SECRET_ARG_RE.test(arg)) {
+      if (arg.includes("=")) {
+        const [key] = arg.split("=", 1);
+        redacted.push(`${key}=<redacted>`);
+      } else {
+        redacted.push(arg);
+        redactNext = true;
+      }
+      continue;
+    }
+    redacted.push(arg);
+  }
+  return redacted;
+}
+function traceLogPath(cwd, timestamp) {
+  const day = timestamp.slice(0, 10);
+  return join7(cwd, ".agentbridge", "logs", `trace-${day}.jsonl`);
+}
+function appendTraceEvent(input) {
+  const timestamp = input.timestamp ?? new Date().toISOString();
+  const path = traceLogPath(input.cwd, timestamp);
+  const event = {
+    timestamp,
+    event: input.event,
+    cwd: input.cwd,
+    pid: input.pid ?? process.pid,
+    ...input.argv ? { argv: redactArgv(input.argv) } : {},
+    ...input.env ? { env: pickRelevantEnv(input.env) } : {},
+    ...input.data ? { data: redactData(input.data) } : {}
+  };
+  mkdirSync4(join7(input.cwd, ".agentbridge", "logs"), { recursive: true });
+  appendFileSync(path, JSON.stringify(event) + `
+`, "utf-8");
+  return path;
+}
+function isEnvSnapshot(key, value) {
+  return /env$/i.test(key) && !!value && typeof value === "object" && !Array.isArray(value);
+}
+function redactData(value, key = "") {
+  if (typeof value === "string") {
+    return SECRET_KEY_RE.test(key) ? "<redacted>" : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactData(item, key));
+  }
+  if (value && typeof value === "object") {
+    const redacted = {};
+    for (const [childKey, childValue] of Object.entries(value)) {
+      if (SECRET_KEY_RE.test(childKey)) {
+        redacted[childKey] = "<redacted>";
+      } else if (isEnvSnapshot(childKey, childValue)) {
+        redacted[childKey] = pickRelevantEnv(childValue);
+      } else {
+        redacted[childKey] = redactData(childValue, childKey);
+      }
+    }
+    return redacted;
+  }
+  return value;
+}
+var SECRET_KEY_RE, SECRET_ARG_RE, RELEVANT_ENV_RE;
+var init_trace_log = __esm(() => {
+  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_)/;
+});
+
+// src/cli/claude.ts
+var exports_claude = {};
+__export(exports_claude, {
+  runClaude: () => runClaude,
+  checkOwnedFlagConflicts: () => checkOwnedFlagConflicts
+});
+import { spawn as spawn2 } from "child_process";
+async function runClaude(args) {
+  const originalEnv = { ...process.env };
+  const envGuardResult = guardAgentBridgeEnv({
+    cwd: process.cwd(),
+    env: process.env,
+    mode: normalizeEnvGuardMode(process.env.AGENTBRIDGE_ENV_GUARD),
+    allowStrict: true,
+    log: (msg) => console.error(msg)
+  });
+  const { pairFlag, rest } = parsePairFlag(args);
+  checkOwnedFlagConflicts(rest, "agentbridge claude", OWNED_FLAGS);
+  let pair;
+  try {
+    pair = await applyPairEnv({ pairFlag });
+  } catch (err) {
+    console.error(`[agentbridge] ${err.message}`);
+    process.exit(1);
+  }
+  if (pair.warning)
+    console.error(`[agentbridge] \u26A0\uFE0F  ${pair.warning}`);
+  if (process.env.AGENTBRIDGE_TRACE === "1") {
+    traceCliStart("cli.claude.start", args, originalEnv, envGuardResult.action, pair);
+  }
+  const stateDir = pair.stateDir;
+  const controlPort = pair.ports.controlPort;
+  const lifecycle = new DaemonLifecycle({
+    stateDir,
+    controlPort,
+    log: (msg) => console.error(`[agentbridge] ${msg}`)
+  });
+  if (!pair.manual) {
+    console.error(`[agentbridge] pair "${pair.pairId}" (slot ${pair.slot}) \u2014 control :${controlPort}, ` + `codex :${pair.ports.appPort}/:${pair.ports.proxyPort}`);
+  }
+  await assertPairNotLive(lifecycle, pair);
+  lifecycle.clearKilled();
+  const channelEntry = `plugin:${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
   const fullArgs = [
     "--dangerously-load-development-channels",
     channelEntry,
-    ...args
+    ...rest
   ];
   const child = spawn2("claude", fullArgs, {
     stdio: "inherit",
@@ -841,6 +2505,62 @@ async function runClaude(args) {
     process.exit(1);
   });
 }
+function traceCliStart(event, args, originalEnv, envGuardAction, pair) {
+  try {
+    appendTraceEvent({
+      cwd: process.cwd(),
+      event,
+      pid: process.pid,
+      argv: ["agentbridge", "claude", ...args],
+      env: process.env,
+      data: {
+        originalEnv: pickRelevantEnv(originalEnv),
+        effectiveEnv: pickRelevantEnv(process.env),
+        envGuardAction,
+        pairId: pair.pairId,
+        pairName: pair.name,
+        manual: pair.manual,
+        slot: pair.slot,
+        stateDir: pair.stateDir.dir,
+        ports: pair.ports,
+        build: BUILD_INFO
+      }
+    });
+  } catch {}
+}
+async function assertPairNotLive(lifecycle, pair) {
+  let healthy = false;
+  try {
+    healthy = await lifecycle.isHealthy();
+  } catch {
+    return;
+  }
+  if (!healthy)
+    return;
+  const client = new DaemonClient(lifecycle.controlWsUrl);
+  let incumbent;
+  try {
+    await client.connect();
+    const daemonProbeMs = parsePositiveIntEnv("AGENTBRIDGE_LIVENESS_PROBE_TIMEOUT_MS", 3000);
+    incumbent = await client.probeIncumbent(daemonProbeMs + 2500);
+  } catch {
+    return;
+  } finally {
+    try {
+      await client.disconnect();
+    } catch {}
+  }
+  if (incumbent.connected && incumbent.alive) {
+    const name = pair.name;
+    console.error(`[agentbridge] Pair "${name}" in ${process.cwd()} already has an active Claude session.`);
+    console.error(`[agentbridge] Refusing to open a second one in the same pair.`);
+    console.error(`[agentbridge]`);
+    console.error(`[agentbridge]   \u2022 Use that existing session, or`);
+    console.error(`[agentbridge]   \u2022 Start a different pair:  abg --pair <other-name> claude`);
+    console.error(`[agentbridge]   \u2022 If that session is actually dead, take it over with:  abg --pair ${name} kill`);
+    process.exit(1);
+  }
+}
 function checkOwnedFlagConflicts(args, commandName, ownedFlags) {
   for (const flag of ownedFlags) {
     if (args.some((a) => a === flag || a.startsWith(`${flag}=`))) {
@@ -861,17 +2581,201 @@ function checkOwnedFlagConflicts(args, commandName, ownedFlags) {
 var OWNED_FLAGS;
 var init_claude = __esm(() => {
   init_cli();
+  init_daemon_client();
   init_daemon_lifecycle();
-  init_state_dir();
+  init_build_info();
+  init_env_guard();
+  init_pair_resolver();
+  init_trace_log();
   OWNED_FLAGS = ["--channels", "--dangerously-load-development-channels"];
 });
 
-// src/stderr-ring-buffer.ts
-class StderrRingBuffer {
-  maxBytes;
-  chunks = [];
+// src/agents-contract.ts
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import { join as join8 } from "path";
+function checkAgentsMdContract(cwd) {
+  const path = join8(cwd, "AGENTS.md");
+  const exists = existsSync7(path);
+  let content = "";
+  if (exists) {
+    try {
+      content = readFileSync6(path, "utf-8");
+    } catch {
+      return {
+        fresh: false,
+        exists,
+        message: "AGENTS.md could not be read; re-run `abg init` to refresh the AgentBridge contract."
+      };
+    }
+  }
+  const fresh = isFreshAgentsMdContract(content);
+  if (fresh) {
+    return { fresh: true, exists, message: "AGENTS.md AgentBridge contract is up to date" };
+  }
+  return {
+    fresh: false,
+    exists,
+    message: exists ? "AGENTS.md is missing the current AgentBridge contract; re-run `abg init` to refresh it." : "AGENTS.md not found; re-run `abg init` to write the AgentBridge contract."
+  };
+}
+function isFreshAgentsMdContract(content) {
+  if (!content.includes(`<!-- ${MARKER_ID}:start -->`))
+    return false;
+  return content.includes("transparent proxy") && content.includes("Do not") && content.includes("sendToClaude") && content.includes("Git operations") && content.includes("Implementer, Executor, Verifier");
+}
+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";
+function discoverNativeChildPid(launcherPid, run) {
+  try {
+    const out = run("pgrep", ["-P", String(launcherPid)]);
+    const first = out.split(/\r?\n/).map((line) => line.trim()).find((line) => /^\d+$/.test(line));
+    return first ? Number(first) : null;
+  } catch {
+    return null;
+  }
+}
+function readTurnInProgress(statusFilePath, read = (p) => readFileSync7(p, "utf-8"), isPidAlive = defaultIsPidAlive) {
+  try {
+    const status = JSON.parse(read(statusFilePath));
+    if (typeof status.turnInProgress !== "boolean")
+      return null;
+    if (typeof status.pid === "number" && !isPidAlive(status.pid))
+      return null;
+    return status.turnInProgress;
+  } catch {
+    return null;
+  }
+}
+function defaultIsPidAlive(pid) {
+  if (pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function refineCleanExitClassification(turnInProgress) {
+  if (turnInProgress === true)
+    return "exit_0_during_turn";
+  if (turnInProgress === false)
+    return "exit_0_idle";
+  return "exit_0_turn_unknown";
+}
+function findCodexSqliteLog(codexHome, fs = { readdir: readdirSync2, stat: statSync3 }) {
+  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));
+      try {
+        const mtime = fs.stat(path).mtimeMs;
+        if (!best || mtime > best.mtime)
+          best = { path, mtime };
+      } catch {}
+    }
+    return best?.path ?? null;
+  } catch {
+    return null;
+  }
+}
+function codexSqliteTailCommand(dbPath, nativePid, limit = 80) {
+  const rows = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 80;
+  const pid = Math.max(0, Math.floor(nativePid));
+  const sql = `select ts, level, target, substr(feedback_log_body,1,300) from logs ` + `where process_uuid like 'pid:${pid}:%' order by id desc limit ${rows};`;
+  return { cmd: "sqlite3", args: ["-readonly", dbPath, sql] };
+}
+function captureTuiLogTail(options) {
+  if (options.nativePid === null) {
+    return "(native child pid unknown \u2014 tui log tail unavailable)";
+  }
+  const db = findCodexSqliteLog(options.codexHome);
+  if (!db) {
+    return "(no codex sqlite log database found)";
+  }
+  try {
+    const { cmd, args } = codexSqliteTailCommand(db, options.nativePid);
+    const out = options.run(cmd, args).trim();
+    return out.length > 0 ? out : `(no log rows for pid ${options.nativePid} in ${db})`;
+  } catch (err) {
+    return `(tui log tail capture failed: ${err instanceof Error ? err.message : String(err)})`;
+  }
+}
+var init_wrapper_exit_observability = () => {};
+
+// src/pair-command.ts
+function pairScopedCommand(cmd) {
+  const pairId = process.env.AGENTBRIDGE_PAIR_ID;
+  if (!pairId)
+    return `agentbridge ${cmd}`;
+  let selector = process.env.AGENTBRIDGE_PAIR_NAME;
+  if (!selector) {
+    try {
+      selector = findPair(computeBaseDir(), pairId)?.name || pairId;
+    } catch {
+      selector = pairId;
+    }
+  }
+  return `agentbridge --pair ${selector} ${cmd}`;
+}
+var init_pair_command = __esm(() => {
+  init_pair_resolver();
+});
+
+// src/rotating-log.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync8, renameSync as renameSync2, statSync as statSync4, unlinkSync as unlinkSync3 } from "fs";
+import { dirname as dirname2 } from "path";
+function appendRotatingLog(path, content, options = {}) {
+  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)))
+    return;
+  rotateIfNeeded(path, Buffer.byteLength(content), maxBytes, keep);
+  appendFileSync2(path, content, "utf-8");
+}
+function positiveIntFromEnv(name, fallback) {
+  const value = process.env[name];
+  if (!value)
+    return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function rotateIfNeeded(path, incomingBytes, maxBytes, keep) {
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0 || keep <= 0)
+    return;
+  if (!existsSync8(path))
+    return;
+  const size = statSync4(path).size;
+  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);
+    } else {
+      renameSync2(current, next);
+    }
+  }
+  renameSync2(path, `${path}.1`);
+}
+var DEFAULT_MAX_BYTES, DEFAULT_KEEP = 3;
+var init_rotating_log = __esm(() => {
+  DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+});
+
+// src/stderr-ring-buffer.ts
+class StderrRingBuffer {
+  maxBytes;
+  chunks = [];
   bytes = 0;
-  constructor(maxBytes = DEFAULT_MAX_BYTES) {
+  constructor(maxBytes = DEFAULT_MAX_BYTES2) {
     this.maxBytes = maxBytes;
     if (maxBytes <= 0) {
       throw new Error("StderrRingBuffer maxBytes must be positive");
@@ -909,36 +2813,270 @@ class StderrRingBuffer {
     return this.bytes;
   }
 }
-var DEFAULT_MAX_BYTES;
+var DEFAULT_MAX_BYTES2;
 var init_stderr_ring_buffer = __esm(() => {
-  DEFAULT_MAX_BYTES = 64 * 1024;
+  DEFAULT_MAX_BYTES2 = 64 * 1024;
 });
 
+// src/thread-state.ts
+import {
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync5,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync8,
+  renameSync as renameSync3,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { homedir as homedir3 } from "os";
+import { basename as basename2, dirname as dirname3, join as join10 } 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");
+}
+function atomicWriteJson(path, value) {
+  mkdirSync5(dirname3(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync6(tmp, JSON.stringify(value, null, 2) + `
+`, "utf-8");
+  renameSync3(tmp, path);
+}
+function readRawCurrentThread(stateDir) {
+  try {
+    const parsed = JSON.parse(readFileSync8(stateDir.currentThreadFile, "utf-8"));
+    if (parsed?.version === 1 && typeof parsed.threadId === "string" && parsed.threadId.length > 0 && (parsed.status === "pending" || parsed.status === "current") && typeof parsed.cwd === "string") {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
+function findCodexRolloutFile(threadId, env = process.env, maxEntries = 20000) {
+  const sessionsDir = join10(codexHome(env), "sessions");
+  if (!threadId || !existsSync9(sessionsDir))
+    return null;
+  const exactName = `rollout-${threadId}.jsonl`;
+  const stack = [sessionsDir];
+  let visited = 0;
+  while (stack.length > 0 && visited < maxEntries) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync3(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      visited++;
+      const path = join10(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(path);
+        continue;
+      }
+      if (!entry.isFile())
+        continue;
+      const name = basename2(entry.name);
+      if (name === exactName || name.startsWith("rollout-") && name.endsWith(".jsonl") && name.includes(threadId)) {
+        return path;
+      }
+    }
+  }
+  return null;
+}
+function readUsableCurrentThread(identity, env = process.env) {
+  const state = readRawCurrentThread(identity.stateDir);
+  if (!state)
+    return null;
+  if (state.status !== "current")
+    return null;
+  if (state.pairId !== identity.pairId)
+    return null;
+  if (state.cwd !== identity.cwd)
+    return null;
+  if (state.rolloutPath && existsSync9(state.rolloutPath))
+    return state;
+  const rolloutPath = findCodexRolloutFile(state.threadId, env);
+  if (!rolloutPath)
+    return null;
+  const repaired = {
+    ...state,
+    rolloutPath,
+    rolloutVerifiedAt: nowIso(),
+    updatedAt: nowIso()
+  };
+  atomicWriteJson(identity.stateDir.currentThreadFile, repaired);
+  return repaired;
+}
+var init_thread_state = () => {};
+
+// src/process-lifecycle.ts
+import { execFileSync as execFileSync6 } from "child_process";
+import { basename as basename3 } from "path";
+function parsePsProcessList(output) {
+  const entries = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^\s*(\d+)\s+(.+?)\s*$/);
+    if (!match)
+      continue;
+    const pid = Number.parseInt(match[1], 10);
+    if (!Number.isFinite(pid))
+      continue;
+    entries.push({ pid, command: match[2] });
+  }
+  return entries;
+}
+function invokesCodexBinary(command) {
+  const tokens = command.trim().split(/\s+/);
+  const exe = tokens[0] ? basename3(tokens[0]) : "";
+  if (exe === "codex")
+    return true;
+  if ((exe === "node" || exe === "bun") && tokens[1]) {
+    return basename3(tokens[1]) === "codex";
+  }
+  return false;
+}
+function commandMatchesManagedCodexTui(command, proxyUrl) {
+  if (!invokesCodexBinary(command))
+    return false;
+  if (!command.includes("tui_app_server"))
+    return false;
+  const remoteUrl = extractRemoteUrl(command);
+  if (!remoteUrl)
+    return false;
+  if (!proxyUrl)
+    return true;
+  return remoteTargetsProxy(remoteUrl, proxyUrl);
+}
+function findManagedCodexTuiProcessesFromList(processes, proxyUrl) {
+  return processes.filter((entry) => commandMatchesManagedCodexTui(entry.command, proxyUrl));
+}
+function findManagedCodexTuiProcesses(proxyUrl) {
+  try {
+    const output = execFileSync6("ps", ["-axo", "pid=,command="], { encoding: "utf-8" });
+    return findManagedCodexTuiProcessesFromList(parsePsProcessList(output), proxyUrl).filter((entry) => entry.pid !== process.pid);
+  } catch {
+    return [];
+  }
+}
+function listManagedCodexTuiProcessesFromList(processes) {
+  return processes.filter((entry) => commandMatchesManagedCodexTui(entry.command)).map((entry) => ({ ...entry, remoteUrl: extractRemoteUrl(entry.command) }));
+}
+function listManagedCodexTuiProcesses() {
+  try {
+    const output = execFileSync6("ps", ["-axo", "pid=,command="], { encoding: "utf-8" });
+    return listManagedCodexTuiProcessesFromList(parsePsProcessList(output)).filter((entry) => entry.pid !== process.pid);
+  } catch {
+    return [];
+  }
+}
+function listBridgeFrontendProcessesFromList(processes) {
+  return processes.filter((entry) => /(?:^|[\s/\\])bridge-server\.js(?:\s|$)/.test(entry.command) && (entry.command.includes("agentbridge") || entry.command.includes("agent_bridge")));
+}
+function listBridgeFrontendProcesses() {
+  try {
+    const output = execFileSync6("ps", ["-axo", "pid=,command="], { encoding: "utf-8" });
+    return listBridgeFrontendProcessesFromList(parsePsProcessList(output)).filter((entry) => entry.pid !== process.pid);
+  } catch {
+    return [];
+  }
+}
+function isProcessAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function commandForPid(pid) {
+  try {
+    return execFileSync6("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+function terminateProcessSync(pid, options = {}) {
+  const gracefulTimeoutMs = options.gracefulTimeoutMs ?? 2000;
+  const target = options.processGroup && process.platform !== "win32" ? -pid : pid;
+  const label = options.processGroup && process.platform !== "win32" ? `process group ${pid}` : `pid ${pid}`;
+  try {
+    process.kill(target, "SIGTERM");
+    options.log?.(`Sent SIGTERM to ${label}`);
+  } catch {
+    return !isProcessAlive2(pid);
+  }
+  if (waitForExitSync(pid, gracefulTimeoutMs))
+    return true;
+  try {
+    process.kill(target, "SIGKILL");
+    options.log?.(`Sent SIGKILL to ${label}`);
+  } catch {}
+  return waitForExitSync(pid, 500);
+}
+function waitForExitSync(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive2(pid))
+      return true;
+    sleepSync(50);
+  }
+  return !isProcessAlive2(pid);
+}
+function sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  const view = new Int32Array(buffer);
+  Atomics.wait(view, 0, 0, ms);
+}
+function extractRemoteUrl(command) {
+  const equals = command.match(/(?:^|\s)--remote=([^\s]+)/);
+  if (equals)
+    return equals[1];
+  const separate = command.match(/(?:^|\s)--remote\s+([^\s]+)/);
+  return separate?.[1] ?? null;
+}
+function remoteTargetsProxy(remoteUrl, proxyUrl) {
+  try {
+    const remote = new URL(remoteUrl);
+    const proxy = new URL(proxyUrl);
+    return remote.protocol === proxy.protocol && remote.hostname === proxy.hostname && remote.port === proxy.port && normalizePath(remote.pathname) === normalizePath(proxy.pathname);
+  } catch {
+    return remoteUrl === proxyUrl;
+  }
+}
+function normalizePath(pathname) {
+  return pathname === "" ? "/" : pathname;
+}
+var init_process_lifecycle = () => {};
+
 // src/cli/codex.ts
 var exports_codex = {};
 __export(exports_codex, {
-  runCodex: () => runCodex
+  runCodex: () => runCodex,
+  resolveCodexResumeArgs: () => resolveCodexResumeArgs,
+  parseAgentBridgeCodexArgs: () => parseAgentBridgeCodexArgs,
+  buildCodexArgs: () => buildCodexArgs
 });
-import { spawn as spawn3, execSync as execSync2 } from "child_process";
+import { spawn as spawn3, execSync as execSync2, execFileSync as execFileSync7 } from "child_process";
 import {
-  openSync as openSync2,
+  openSync as openSync3,
   writeSync,
-  closeSync as closeSync2,
-  writeFileSync as writeFileSync4,
-  unlinkSync as unlinkSync2,
-  appendFileSync,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync3
+  closeSync as closeSync3,
+  writeFileSync as writeFileSync7,
+  readFileSync as readFileSync9,
+  unlinkSync as unlinkSync4,
+  existsSync as existsSync10,
+  mkdirSync as mkdirSync6
 } from "fs";
-import { dirname as dirname2 } from "path";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname4, join as join11 } from "path";
 function appendWrapperLog(path, entry) {
   try {
-    const dir = dirname2(path);
-    if (!existsSync6(dir)) {
-      mkdirSync3(dir, { recursive: true });
+    const dir = dirname4(path);
+    if (!existsSync10(dir)) {
+      mkdirSync6(dir, { recursive: true });
     }
-    appendFileSync(path, `[${new Date().toISOString()}] ${entry}
-`, "utf-8");
+    appendRotatingLog(path, `[${new Date().toISOString()}] ${entry}
+`);
   } catch {}
 }
 function buildChildEnv() {
@@ -948,17 +3086,106 @@ function buildChildEnv() {
     RUST_LOG: process.env.RUST_LOG ?? "info,codex_core=debug,codex_tui=debug,codex_app_server=debug"
   };
 }
+function parseAgentBridgeCodexArgs(args) {
+  const rest = [];
+  let forceNew = false;
+  let resumeCurrent = false;
+  for (const arg of args) {
+    if (arg === "--new") {
+      forceNew = true;
+      continue;
+    }
+    if (arg === "resume-current") {
+      resumeCurrent = true;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { rest, forceNew, resumeCurrent };
+}
+function resolveCodexResumeArgs(parsed, pair, env = process.env) {
+  if (parsed.forceNew && parsed.resumeCurrent) {
+    return {
+      rest: parsed.rest,
+      mode: "new",
+      error: "`--new` cannot be combined with `resume-current`."
+    };
+  }
+  if (parsed.forceNew) {
+    return { rest: parsed.rest, mode: "new" };
+  }
+  const identity = {
+    stateDir: pair.stateDir,
+    pairId: pair.manual ? null : pair.pairId,
+    pairName: pair.name,
+    cwd: process.cwd()
+  };
+  const current = readUsableCurrentThread(identity, env);
+  if (parsed.resumeCurrent) {
+    if (!current) {
+      return {
+        rest: parsed.rest,
+        mode: "resume-current",
+        error: "No verified current Codex thread for this pair. Start a new one with `abg codex --new`, or resume a specific thread with `abg codex resume <threadId>`."
+      };
+    }
+    return {
+      rest: ["resume", current.threadId, ...parsed.rest],
+      mode: "resume-current",
+      thread: current
+    };
+  }
+  if (parsed.rest.length === 0 && current) {
+    return {
+      rest: ["resume", current.threadId],
+      mode: "auto-resume",
+      thread: current
+    };
+  }
+  return { rest: parsed.rest, mode: "passthrough" };
+}
+function buildCodexArgs(userArgs, proxyUrl) {
+  const bridgeFlags = ["--enable", "tui_app_server", "--remote", proxyUrl];
+  const first = userArgs[0];
+  if (!first || first.startsWith("-")) {
+    return { fullArgs: [...bridgeFlags, ...userArgs], injectedBridgeFlags: true };
+  }
+  if (TUI_SUBCOMMANDS.has(first)) {
+    return {
+      fullArgs: [first, ...bridgeFlags, ...userArgs.slice(1)],
+      injectedBridgeFlags: true
+    };
+  }
+  if (NON_TUI_SUBCOMMANDS.has(first)) {
+    return { fullArgs: userArgs, injectedBridgeFlags: false };
+  }
+  return { fullArgs: [...bridgeFlags, ...userArgs], injectedBridgeFlags: true };
+}
 async function runCodex(args) {
-  checkOwnedFlagConflicts(args, "agentbridge codex", OWNED_FLAGS2);
-  for (let i = 0;i < args.length; i++) {
-    if (args[i] === "--enable" && args[i + 1] === "tui_app_server") {
+  const originalEnv = { ...process.env };
+  const envGuardResult = guardAgentBridgeEnv({
+    cwd: process.cwd(),
+    env: process.env,
+    mode: normalizeEnvGuardMode(process.env.AGENTBRIDGE_ENV_GUARD),
+    allowStrict: true,
+    log: (msg) => console.error(msg)
+  });
+  const { pairFlag, rest } = parsePairFlag(args);
+  const wrapperArgs = parseAgentBridgeCodexArgs(rest);
+  const agentsContract = checkAgentsMdContract(process.cwd());
+  if (!agentsContract.fresh) {
+    console.error(`[agentbridge] ${agentsContract.message}`);
+  }
+  checkOwnedFlagConflicts(wrapperArgs.rest, "agentbridge codex", OWNED_FLAGS2);
+  for (let i = 0;i < wrapperArgs.rest.length; i++) {
+    if (wrapperArgs.rest[i] === "--enable" && wrapperArgs.rest[i + 1] === "tui_app_server") {
       console.error(`Error: "--enable tui_app_server" is automatically set by agentbridge codex.`);
       console.error("");
       console.error("If you need full control over these flags, use the native command directly:");
       console.error("  codex [your flags here]");
       process.exit(1);
     }
-    if (args[i] === "--enable=tui_app_server") {
+    if (wrapperArgs.rest[i] === "--enable=tui_app_server") {
       console.error(`Error: "--enable=tui_app_server" is automatically set by agentbridge codex.`);
       console.error("");
       console.error("If you need full control over these flags, use the native command directly:");
@@ -966,15 +3193,30 @@ async function runCodex(args) {
       process.exit(1);
     }
   }
-  const stateDir = new StateDirResolver;
-  const configService = new ConfigService;
-  const config = configService.loadOrDefault();
-  const controlPort = parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
+  let pair;
+  try {
+    pair = await applyPairEnv({ pairFlag });
+  } catch (err) {
+    console.error(`[agentbridge] ${err.message}`);
+    process.exit(1);
+  }
+  if (pair.warning)
+    console.error(`[agentbridge] \u26A0\uFE0F  ${pair.warning}`);
+  if (process.env.AGENTBRIDGE_TRACE === "1") {
+    traceCliStart2("cli.codex.start", args, originalEnv, envGuardResult.action, pair);
+  }
+  const stateDir = pair.stateDir;
+  const controlPort = pair.ports.controlPort;
+  const pairProxyUrl = `ws://127.0.0.1:${pair.ports.proxyPort}`;
+  guardNoLiveManagedTui(stateDir, pairProxyUrl);
   const lifecycle = new DaemonLifecycle({
     stateDir,
     controlPort,
     log: (msg) => console.error(`[agentbridge] ${msg}`)
   });
+  if (!pair.manual) {
+    console.error(`[agentbridge] pair "${pair.pairId}" (slot ${pair.slot}) \u2014 control :${controlPort}, ` + `codex :${pair.ports.appPort}/:${pair.ports.proxyPort}`);
+  }
   console.error("[agentbridge] Ensuring daemon is running...");
   try {
     lifecycle.clearKilled();
@@ -982,7 +3224,7 @@ async function runCodex(args) {
     console.error("[agentbridge] Daemon is ready.");
   } catch (err) {
     console.error(`[agentbridge] Failed to start daemon: ${err.message}`);
-    console.error("[agentbridge] Try: agentbridge kill && agentbridge claude");
+    console.error(`[agentbridge] Try: ${pairScopedCommand("kill")} && ${pairScopedCommand("claude")}`);
     process.exit(1);
   }
   let proxyUrl;
@@ -990,8 +3232,9 @@ async function runCodex(args) {
   if (status?.proxyUrl) {
     proxyUrl = status.proxyUrl;
   } else {
-    proxyUrl = `ws://127.0.0.1:${config.codex.proxyPort}`;
-    console.error(`[agentbridge] No daemon status found, using config default: ${proxyUrl}`);
+    const fallbackProxyPort = process.env.CODEX_PROXY_PORT ?? String(new ConfigService().loadOrDefault().codex.proxyPort);
+    proxyUrl = `ws://127.0.0.1:${fallbackProxyPort}`;
+    console.error(`[agentbridge] No daemon status found, using fallback proxy port: ${proxyUrl}`);
   }
   try {
     await waitForProxyReady(proxyUrl);
@@ -1018,7 +3261,7 @@ async function runCodex(args) {
     }
     let ttyFd = null;
     try {
-      ttyFd = openSync2("/dev/tty", "w");
+      ttyFd = openSync3("/dev/tty", "w");
     } catch {
       if (process.stdout.isTTY) {
         ttyFd = 1;
@@ -1040,32 +3283,53 @@ async function runCodex(args) {
       }
       if (ttyFd !== 1) {
         try {
-          closeSync2(ttyFd);
+          closeSync3(ttyFd);
         } catch {}
       }
     }
   }
-  const fullArgs = [
-    "--enable",
-    "tui_app_server",
-    "--remote",
-    proxyUrl,
-    ...args
-  ];
+  const resumeArgs = resolveCodexResumeArgs(wrapperArgs, pair);
+  if (resumeArgs.error) {
+    console.error(`[agentbridge] ${resumeArgs.error}`);
+    process.exit(1);
+  }
+  if (resumeArgs.mode === "auto-resume" || resumeArgs.mode === "resume-current") {
+    console.error(`[agentbridge] Resuming current Codex thread ${resumeArgs.thread.threadId}`);
+  }
+  const { fullArgs } = buildCodexArgs(resumeArgs.rest, proxyUrl);
   const stderrTail = new StderrRingBuffer;
   const wrapperLogPath = stateDir.codexWrapperLogFile;
   const startedAt = Date.now();
   stateDir.ensure();
-  appendWrapperLog(wrapperLogPath, `spawn: codex ${fullArgs.map((a) => a.includes(" ") ? JSON.stringify(a) : a).join(" ")}`);
+  appendWrapperLog(wrapperLogPath, `spawn: codex ${redactArgv(fullArgs).map((a) => a.includes(" ") ? JSON.stringify(a) : a).join(" ")}`);
   const child = spawn3("codex", fullArgs, {
     stdio: ["inherit", "inherit", "pipe"],
     env: buildChildEnv()
   });
   if (typeof child.pid === "number") {
-    writeFileSync4(stateDir.tuiPidFile, `${child.pid}
+    writeFileSync7(stateDir.tuiPidFile, `${child.pid}
 `, "utf-8");
     appendWrapperLog(wrapperLogPath, `child pid=${child.pid}`);
   }
+  let nativeChildPid = null;
+  if (typeof child.pid === "number") {
+    const launcherPid = child.pid;
+    let attempts = 0;
+    const discover = () => {
+      attempts += 1;
+      nativeChildPid = discoverNativeChildPid(launcherPid, (cmd, args2) => execFileSync7(cmd, args2, { encoding: "utf-8", timeout: 2000 }));
+      if (nativeChildPid !== null) {
+        appendWrapperLog(wrapperLogPath, `native child pid=${nativeChildPid} (launcher pid=${launcherPid})`);
+        return;
+      }
+      if (attempts < 5 && !childExited) {
+        const retry = setTimeout(discover, 500);
+        retry.unref();
+      }
+    };
+    const first = setTimeout(discover, 300);
+    first.unref();
+  }
   if (child.stderr) {
     child.stderr.on("data", (chunk) => {
       try {
@@ -1075,29 +3339,69 @@ async function runCodex(args) {
     });
   }
   let cleanedTuiPid = false;
+  let childExited = false;
+  let wrapperShuttingDown = false;
+  let signalExitCode = null;
   function cleanupTuiPidFile() {
     if (cleanedTuiPid)
       return;
     cleanedTuiPid = true;
     try {
-      unlinkSync2(stateDir.tuiPidFile);
+      unlinkSync4(stateDir.tuiPidFile);
     } catch {}
   }
-  process.on("exit", () => {
-    restoreTerminal();
-    cleanupTuiPidFile();
-  });
-  process.on("SIGINT", () => {
+  function requestChildTermination(reason) {
+    if (childExited)
+      return;
+    const pid = child.pid;
+    if (typeof pid !== "number")
+      return;
+    appendWrapperLog(wrapperLogPath, `terminating child pid=${pid} reason=${reason}`);
+    try {
+      child.kill("SIGTERM");
+    } catch {}
+    const killTimer = setTimeout(() => {
+      if (childExited)
+        return;
+      appendWrapperLog(wrapperLogPath, `child pid=${pid} still alive after SIGTERM; sending SIGKILL`);
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    }, 1500);
+    killTimer.unref();
+  }
+  function shutdownWrapper(reason, exitCode) {
+    if (wrapperShuttingDown)
+      return;
+    wrapperShuttingDown = true;
+    signalExitCode = exitCode;
     restoreTerminal();
-    cleanupTuiPidFile();
-    process.exit(130);
-  });
-  process.on("SIGTERM", () => {
+    requestChildTermination(reason);
+    if (childExited) {
+      cleanupTuiPidFile();
+      process.exit(exitCode);
+      return;
+    }
+    const forceTimer = setTimeout(() => {
+      cleanupTuiPidFile();
+      process.exit(exitCode);
+    }, 3000);
+    forceTimer.unref();
+  }
+  process.on("exit", () => {
     restoreTerminal();
+    if (!childExited && typeof child.pid === "number") {
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    }
     cleanupTuiPidFile();
-    process.exit(143);
   });
+  process.on("SIGHUP", () => shutdownWrapper("SIGHUP", 129));
+  process.on("SIGINT", () => shutdownWrapper("SIGINT", 130));
+  process.on("SIGTERM", () => shutdownWrapper("SIGTERM", 143));
   child.on("exit", (code, signal) => {
+    childExited = true;
     cleanupTuiPidFile();
     const runtimeMs = Date.now() - startedAt;
     const tail = stderrTail.toString();
@@ -1113,16 +3417,25 @@ async function runCodex(args) {
       classification = `signal:${signal}`;
     else if (typeof code === "number" && code !== 0)
       classification = `nonzero_exit:${code}`;
-    else if (code === 0 && tail.trim().length === 0)
-      classification = "exit_0_empty_stderr";
+    else if (code === 0 && tail.trim().length === 0) {
+      classification = refineCleanExitClassification(readTurnInProgress(stateDir.statusFile));
+    }
+    const tuiLogTail = captureTuiLogTail({
+      codexHome: join11(homedir4(), ".codex"),
+      nativePid: nativeChildPid,
+      run: (cmd, args2) => execFileSync7(cmd, args2, { encoding: "utf-8", timeout: 2000 })
+    });
     appendWrapperLog(wrapperLogPath, [
-      `exit: code=${code ?? "null"} signal=${signal ?? "null"} runtime_ms=${runtimeMs} pid=${child.pid ?? "unknown"} classification=${classification}`,
+      `exit: code=${code ?? "null"} signal=${signal ?? "null"} runtime_ms=${runtimeMs} pid=${child.pid ?? "unknown"} native_pid=${nativeChildPid ?? "unknown"} classification=${classification}`,
       `--- last stderr (${stderrTail.byteLength} bytes) ---`,
       tailLines,
-      `--- end stderr ---`
+      `--- end stderr ---`,
+      `--- last tui log (native pid ${nativeChildPid ?? "unknown"}) ---`,
+      tuiLogTail,
+      `--- end tui log ---`
     ].join(`
 `));
-    process.exit(code ?? 0);
+    process.exit(signalExitCode ?? code ?? 0);
   });
   child.on("error", (err) => {
     cleanupTuiPidFile();
@@ -1136,197 +3449,1383 @@ async function runCodex(args) {
     process.exit(1);
   });
 }
-function proxyHealthUrl(proxyUrl) {
-  const url = new URL(proxyUrl);
-  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
-  url.pathname = "/healthz";
-  url.search = "";
-  url.hash = "";
-  return url.toString();
+function traceCliStart2(event, args, originalEnv, envGuardAction, pair) {
+  try {
+    appendTraceEvent({
+      cwd: process.cwd(),
+      event,
+      pid: process.pid,
+      argv: ["agentbridge", "codex", ...args],
+      env: process.env,
+      data: {
+        originalEnv: pickRelevantEnv(originalEnv),
+        effectiveEnv: pickRelevantEnv(process.env),
+        envGuardAction,
+        pairId: pair.pairId,
+        pairName: pair.name,
+        manual: pair.manual,
+        slot: pair.slot,
+        stateDir: pair.stateDir.dir,
+        ports: pair.ports,
+        build: BUILD_INFO
+      }
+    });
+  } catch {}
+}
+function guardNoLiveManagedTui(stateDir, proxyUrl) {
+  const pid = readTuiPid(stateDir);
+  if (pid) {
+    if (!isProcessAlive2(pid)) {
+      try {
+        unlinkSync4(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);
+      } catch {}
+    } else {
+      console.error(`[agentbridge] This pair already has a managed Codex TUI running (pid ${pid}).`);
+      console.error(`[agentbridge] Use that terminal, or stop it with: ${pairScopedCommand("kill")}`);
+      process.exit(1);
+    }
+  }
+  const orphan = findManagedCodexTuiProcesses(proxyUrl)[0];
+  if (!orphan)
+    return;
+  console.error(`[agentbridge] This pair already has a managed Codex TUI running (pid ${orphan.pid}).`);
+  console.error(`[agentbridge] Use that terminal, or stop it with: ${pairScopedCommand("kill")}`);
+  process.exit(1);
+}
+function readTuiPid(stateDir) {
+  try {
+    const raw = readFileSync9(stateDir.tuiPidFile, "utf-8").trim();
+    if (!raw)
+      return null;
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function isManagedCodexTuiProcess(pid, proxyUrl) {
+  const cmd = commandForPid(pid);
+  return cmd !== null && commandMatchesManagedCodexTui(cmd, proxyUrl);
+}
+function proxyHealthUrl(proxyUrl) {
+  const url = new URL(proxyUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = "/healthz";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+async function waitForProxyReady(proxyUrl, maxRetries = 20, delayMs = 100) {
+  const healthUrl = proxyHealthUrl(proxyUrl);
+  for (let attempt = 0;attempt < maxRetries; attempt++) {
+    try {
+      const response = await fetch(healthUrl);
+      if (response.ok) {
+        return;
+      }
+    } catch {}
+    await new Promise((resolve4) => setTimeout(resolve4, delayMs));
+  }
+  throw new Error(`Timed out waiting for Codex proxy readiness on ${healthUrl}`);
+}
+var OWNED_FLAGS2, TUI_SUBCOMMANDS, NON_TUI_SUBCOMMANDS;
+var init_codex = __esm(() => {
+  init_agents_contract();
+  init_wrapper_exit_observability();
+  init_config_service();
+  init_build_info();
+  init_daemon_lifecycle();
+  init_env_guard();
+  init_pair_command();
+  init_rotating_log();
+  init_pair_resolver();
+  init_stderr_ring_buffer();
+  init_thread_state();
+  init_trace_log();
+  init_process_lifecycle();
+  init_claude();
+  OWNED_FLAGS2 = ["--remote"];
+  TUI_SUBCOMMANDS = new Set(["resume", "fork"]);
+  NON_TUI_SUBCOMMANDS = new Set([
+    "exec",
+    "e",
+    "review",
+    "login",
+    "logout",
+    "mcp",
+    "mcp-server",
+    "plugin",
+    "remote-control",
+    "update",
+    "app-server",
+    "exec-server",
+    "app",
+    "completion",
+    "sandbox",
+    "debug",
+    "apply",
+    "a",
+    "cloud",
+    "features",
+    "help"
+  ]);
+});
+
+// src/cli/kill.ts
+var exports_kill = {};
+__export(exports_kill, {
+  stopPairEntry: () => stopPairEntry,
+  runKill: () => runKill,
+  formatKillReport: () => formatKillReport
+});
+import { readFileSync as readFileSync10, unlinkSync as unlinkSync5 } from "fs";
+import { join as join12 } from "path";
+async function runKill(args = []) {
+  const argError = validateKillArgs(args);
+  if (argError === "help") {
+    printKillUsage();
+    return;
+  }
+  if (argError) {
+    console.error(`Error: ${argError}`);
+    printKillUsage();
+    process.exit(1);
+  }
+  const parsed = parseKillArgs(args);
+  if (parsed.pairFlag !== undefined && parsed.all) {
+    console.error('Error: use either "--pair <name>" or "--all", not both.');
+    process.exit(1);
+  }
+  const base = computeBaseDir();
+  console.log(`AgentBridge Kill \u2014 stopping AgentBridge pair processes
+`);
+  const results = [];
+  let restartCommand = "agentbridge claude";
+  if (parsed.pairFlag !== undefined) {
+    let pair;
+    try {
+      pair = findPairForFlag(base, process.cwd(), parsed.pairFlag);
+    } catch (err) {
+      console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+    if (!pair) {
+      console.log(`No such pair: "${parsed.pairFlag}" in ${process.cwd()}`);
+      printKnownPairs(base);
+      return;
+    }
+    restartCommand = `agentbridge --pair ${pair.name ?? parsed.pairFlag} claude`;
+    results.push(await stopPairEntry(base, pair));
+  } else if (parsed.all) {
+    let registered = [];
+    try {
+      registered = listPairs(base);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.log(`\u26A0\uFE0F  pair registry \u4E0D\u53EF\u8BFB\uFF08${message}\uFF09\u2014\u2014\u964D\u7EA7\u4E3A\u72B6\u6001\u76EE\u5F55\u626B\u63CF\uFF0C\u4ECD\u4F1A\u505C\u6B62\u80FD\u627E\u5230\u7684\u5168\u90E8 pair\u3002`);
+    }
+    for (const pair of registered) {
+      results.push(await stopPairEntry(base, pair));
+    }
+    const registeredIds = new Set(registered.map((pair) => pair.pairId));
+    for (const dirName of listPairDirsSafe(base)) {
+      if (registeredIds.has(dirName))
+        continue;
+      const stateDir = new StateDirResolver(join12(base, "pairs", dirName));
+      results.push(await stopStateDir(`${dirName} (unregistered)`, stateDir, portsFromStateDir(stateDir)));
+    }
+    const legacy = detectLegacyRootDaemon(base);
+    if (legacy) {
+      results.push(await stopStateDir("(legacy-root)", new StateDirResolver(base), {
+        appPort: 4500,
+        proxyPort: 4501,
+        controlPort: legacy.controlPort
+      }));
+    }
+  } else {
+    let cwdPairs = [];
+    try {
+      cwdPairs = listPairsForCwd(base, process.cwd());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.log(`\u26A0\uFE0F  pair registry \u4E0D\u53EF\u8BFB\uFF08${message}\uFF09\u2014\u2014\u65E0\u6CD5\u6309\u76EE\u5F55\u5B9A\u4F4D pair\u3002` + "\u8FD0\u884C `abg kill --all` \u53EF\u964D\u7EA7\u4E3A\u5168\u76D8\u72B6\u6001\u76EE\u5F55\u626B\u63CF\uFF0C\u505C\u6B62\u6240\u6709\u80FD\u627E\u5230\u7684 pair\u3002");
+      process.exitCode = 2;
+    }
+    for (const pair of cwdPairs) {
+      results.push(await stopPairEntry(base, pair));
+    }
+    const legacy = detectLegacyRootDaemon(base);
+    if (legacy) {
+      results.push(await stopStateDir("(legacy-root)", new StateDirResolver(base), {
+        appPort: 4500,
+        proxyPort: 4501,
+        controlPort: legacy.controlPort
+      }));
+    }
+    if (results.length === 0) {
+      console.log(`No AgentBridge pairs registered for current directory: ${process.cwd()}`);
+      console.log("Use `abg kill all` or `abg kill --all` to stop pairs from every directory.");
+      return;
+    }
+  }
+  printSummary(results, restartCommand);
+}
+function validateKillArgs(args) {
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h")
+      return "help";
+    if (arg === "all")
+      continue;
+    if (arg === "--all")
+      continue;
+    if (arg === "--pair") {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("-")) {
+        return 'Missing value for "--pair".';
+      }
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--pair=")) {
+      if (arg.slice("--pair=".length).length === 0) {
+        return 'Missing value for "--pair".';
+      }
+      continue;
+    }
+    return `Unknown kill argument: ${arg}`;
+  }
+  return null;
+}
+function printKillUsage() {
+  console.log(`
+Usage: abg kill [--all]
+       abg kill all
+       abg [--pair <name|id>] kill
+
+Stops AgentBridge daemon/TUI processes.
+
+Options:
+  --pair <name|id>  Stop only one pair \u2014 a cwd-scoped name (e.g. "main") or the
+                    same pair id when run from that directory.
+  all, --all        Stop all registered pairs and any legacy-root daemon.
+  --help, -h        Show this help message.
+
+No arguments stop this directory's registered pairs and any legacy-root daemon.
+`.trim());
+}
+async function stopPairEntry(base, pair) {
+  const ports = portsForEntry(pair);
+  const stateDir = new StateDirResolver(join12(base, "pairs", pair.pairId));
+  return stopStateDir(pair.pairId, stateDir, ports);
+}
+function listPairDirsSafe(base) {
+  try {
+    return listPairDirs(base);
+  } catch {
+    return [];
+  }
+}
+function portsFromStateDir(stateDir) {
+  try {
+    const raw = JSON.parse(readFileSync10(stateDir.statusFile, "utf-8"));
+    return {
+      appPort: portFromUrl(raw?.appServerUrl) ?? 0,
+      proxyPort: portFromUrl(raw?.proxyUrl) ?? 0,
+      controlPort: typeof raw?.controlPort === "number" ? raw.controlPort : 0
+    };
+  } catch {
+    return { appPort: 0, proxyPort: 0, controlPort: 0 };
+  }
+}
+function portFromUrl(url) {
+  if (typeof url !== "string")
+    return null;
+  const match = url.match(/:(\d+)(?:[/?]|$)/);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+async function stopStateDir(label, stateDir, ports) {
+  const portsLabel = `${ports.appPort}/${ports.proxyPort}/${ports.controlPort}`;
+  const details = [];
+  const log = (msg) => details.push(msg);
+  try {
+    const lifecycle = new DaemonLifecycle({
+      stateDir,
+      controlPort: ports.controlPort,
+      log
+    });
+    lifecycle.markKilled();
+    const status = lifecycle.readStatus();
+    const proxyUrl = typeof status?.proxyUrl === "string" && status.proxyUrl.length > 0 ? status.proxyUrl : `ws://127.0.0.1:${ports.proxyPort}`;
+    const tuiKilled = await killManagedCodexTui(stateDir, proxyUrl, log);
+    const daemonKilled = await lifecycle.kill();
+    return { label, portsLabel, daemonKilled, tuiKilled, details };
+  } catch (error) {
+    log(`ERROR: ${error instanceof Error ? error.message : String(error)}`);
+    return { label, portsLabel, daemonKilled: false, tuiKilled: false, details, error };
+  }
+}
+function printKnownPairs(base) {
+  try {
+    const pairs = listPairs(base);
+    if (pairs.length === 0) {
+      console.log("No pairs registered.");
+      return;
+    }
+    console.log("Known pairs:");
+    for (const pair of pairs) {
+      const ports = portsForEntry(pair);
+      console.log(`  ${pair.pairId} (name=${pair.name ?? "main"}, cwd=${pair.cwd}, slot ${pair.slot}, ports ${ports.appPort}/${ports.proxyPort}/${ports.controlPort})`);
+    }
+  } catch (error) {
+    if (error instanceof PairError) {
+      console.log(`Could not read pair registry: ${error.message}`);
+      return;
+    }
+    throw error;
+  }
+}
+function describeStopped(result) {
+  const parts = [];
+  if (result.daemonKilled)
+    parts.push("daemon");
+  if (result.tuiKilled)
+    parts.push("Codex TUI");
+  return `${result.label}\uFF08${parts.join(" + ")}\uFF09`;
+}
+function formatKillReport(results, frontends, restartCommand) {
+  const lines = [];
+  if (results.length === 0) {
+    lines.push("No pairs registered.");
+    return lines;
+  }
+  const stopped = results.filter((r) => (r.daemonKilled || r.tuiKilled) && !r.error);
+  const failed = results.filter((r) => r.error);
+  const idle = results.filter((r) => !r.daemonKilled && !r.tuiKilled && !r.error);
+  for (const result of [...stopped, ...failed]) {
+    lines.push(`  [${result.label} ${result.portsLabel}]`);
+    for (const detail of result.details)
+      lines.push(`    ${detail}`);
+  }
+  if (stopped.length > 0 || failed.length > 0)
+    lines.push("");
+  lines.push(`\u603B\u7ED3\uFF08\u5171 ${results.length} \u4E2A\u76EE\u6807\uFF09:`);
+  if (stopped.length > 0) {
+    lines.push(`  \u2705 \u5DF2\u505C\u6B62 ${stopped.length} \u4E2A: ${stopped.map(describeStopped).join(", ")}`);
+  }
+  if (idle.length > 0) {
+    lines.push(`  \u26AA \u672C\u6765\u5C31\u6CA1\u5728\u8FD0\u884C ${idle.length} \u4E2A: ${idle.map((r) => r.label).join(", ")}`);
+  }
+  if (failed.length > 0) {
+    lines.push(`  \u274C \u5931\u8D25 ${failed.length} \u4E2A: ${failed.map((r) => r.label).join(", ")}\uFF08\u8BE6\u89C1\u4E0A\u65B9\u65E5\u5FD7\uFF09`);
+  }
+  lines.push("");
+  if (stopped.length > 0) {
+    lines.push("AgentBridge stopped.");
+    lines.push(`Please restart Claude Code (\`${restartCommand}\`), switch to a new conversation, or run \`/resume\` to fully disconnect.`);
+    lines.push("\u2139\uFE0F  \u5DF2\u5199\u5165 killed \u54E8\u5175\uFF1A\u88AB\u505C\u6B62\u7684 pair \u4E0D\u4F1A\u88AB\u81EA\u52A8\u590D\u6D3B\uFF1B" + `\u4E0B\u6B21 \`${restartCommand}\` / \`agentbridge codex\` \u4F1A\u6E05\u9664\u54E8\u5175\u5E76\u7528\u5F53\u524D\u5B89\u88C5\u7248\u672C\u542F\u52A8\u5168\u65B0 daemon\u3002`);
+  } else {
+    lines.push("No running AgentBridge daemon or managed Codex TUI found.");
+    lines.push("\u2139\uFE0F  \u76EE\u6807 pair \u90FD\u6CA1\u6709\u5728\u8FD0\u884C\u7684\u8FDB\u7A0B\u2014\u2014\u5982\u679C\u4F60\u4ECD\u770B\u5230 AgentBridge \u6D3B\u52A8\uFF0C\u89C1\u4E0B\u65B9\u524D\u7AEF\u63D0\u793A\u3002");
+  }
+  if (frontends.length > 0) {
+    lines.push(`\u26A0\uFE0F  \u68C0\u6D4B\u5230 ${frontends.length} \u4E2A\u4ECD\u5728\u8FD0\u884C\u7684 Claude Code \u6865\u63A5\u524D\u7AEF (pid ${frontends.map((f) => f.pid).join(", ")})\uFF1A`);
+    lines.push("    \u5B83\u4EEC\u73B0\u5728\u5904\u4E8E\u5F85\u673A\u72B6\u6001\u3001\u4E0D\u4F1A\u590D\u6D3B\u5DF2\u505C\u6B62\u7684 daemon\uFF1B\u4F46\u65E7\u7A97\u53E3\u91CC\u52A0\u8F7D\u7684\u63D2\u4EF6\u4EE3\u7801");
+    lines.push("    \u4E0D\u4F1A\u81EA\u52A8\u66F4\u65B0\u2014\u2014\u5347\u7EA7\u540E\u9700\u8981\u65B0\u7248\u672C\u65F6\uFF0C\u8BF7\u5173\u95ED\u5E76\u91CD\u5F00\u5BF9\u5E94\u7684 Claude Code \u7A97\u53E3\u3002");
+  }
+  lines.push("Registry entries were preserved. Use `abg pairs rm <name|id>` to stop and release a slot.");
+  return lines;
+}
+function printSummary(results, restartCommand) {
+  const frontends = listBridgeFrontendProcesses();
+  for (const line of formatKillReport(results, frontends, restartCommand)) {
+    console.log(line);
+  }
+  if (results.some((r) => r.error)) {
+    process.exitCode = 2;
+  }
+}
+async function killManagedCodexTui(stateDir, proxyUrl, log, gracefulTimeoutMs = 3000) {
+  const pid = readTuiPid2(stateDir);
+  let killed = false;
+  if (!pid) {
+    log("No Codex TUI pid file found");
+    removeTuiPidFile(stateDir);
+  } else if (!isProcessAlive2(pid)) {
+    log(`Codex TUI pid ${pid} is not alive, cleaning up stale pid file`);
+    removeTuiPidFile(stateDir);
+  } else if (!isManagedCodexTuiProcess2(pid, proxyUrl)) {
+    log(`Pid ${pid} is alive but is NOT a managed AgentBridge Codex TUI \u2014 refusing to kill. Cleaning up stale pid file.`);
+    removeTuiPidFile(stateDir);
+  } else {
+    log(`Stopping Codex TUI pid ${pid}`);
+    terminateProcessSync(pid, { gracefulTimeoutMs, log });
+    removeTuiPidFile(stateDir);
+    killed = true;
+  }
+  const orphanCandidates = findManagedCodexTuiProcesses(proxyUrl).filter((entry) => entry.pid !== pid);
+  for (const candidate of orphanCandidates) {
+    log(`Stopping orphan Codex TUI pid ${candidate.pid} attached to ${proxyUrl}`);
+    terminateProcessSync(candidate.pid, { gracefulTimeoutMs, log });
+    killed = true;
+  }
+  removeTuiPidFile(stateDir);
+  return killed;
+}
+function readTuiPid2(stateDir) {
+  try {
+    const raw = readFileSync10(stateDir.tuiPidFile, "utf-8").trim();
+    if (!raw)
+      return null;
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function removeTuiPidFile(stateDir) {
+  try {
+    unlinkSync5(stateDir.tuiPidFile);
+  } catch {}
+}
+function isManagedCodexTuiProcess2(pid, proxyUrl) {
+  const cmd = commandForPid(pid);
+  return cmd !== null && commandMatchesManagedCodexTui(cmd, proxyUrl);
+}
+var init_kill = __esm(() => {
+  init_daemon_lifecycle();
+  init_pair_registry();
+  init_pair_resolver();
+  init_process_lifecycle();
+  init_state_dir();
+});
+
+// src/cli/pairs.ts
+var exports_pairs = {};
+__export(exports_pairs, {
+  runPairs: () => runPairs
+});
+import { join as join13 } from "path";
+async function runPairs(args = []) {
+  const [command, ...rest] = args;
+  if (command === "rm") {
+    await runRemove(rest);
+    return;
+  }
+  if (command === "prune") {
+    await runPrune(rest);
+    return;
+  }
+  if (command && command !== "list" && command !== "--json" && command !== "--threads") {
+    console.error(`Unknown pairs command: ${command}`);
+    console.error("Usage: abg pairs [--json] [--threads] | abg pairs rm <name|id> | abg pairs prune [--dry-run]");
+    process.exit(1);
+  }
+  const json = command === "--json" || rest.includes("--json");
+  const includeThreads = rest.includes("--threads") || args.includes("--threads");
+  const rows = await collectRows();
+  if (json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  printTable(rows, { includeThreads });
+}
+async function runRemove(args) {
+  const flag = args[0];
+  if (!flag) {
+    console.error("Error: `abg pairs rm <name|id>` requires a pair name or id.");
+    process.exit(1);
+  }
+  const base = computeBaseDir();
+  let pair;
+  try {
+    pair = findPairForFlag(base, process.cwd(), flag);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  if (!pair) {
+    console.log(`No such pair: "${flag}" in ${process.cwd()}`);
+    printKnownPairs2(base);
+    return;
+  }
+  const stop = await stopPairEntry(base, pair);
+  if (stop.error) {
+    console.error(`Error: failed to stop pair ${pair.pairId}; leaving it registered. ` + `${stop.error instanceof Error ? stop.error.message : String(stop.error)}`);
+    process.exit(1);
+  }
+  let result;
+  try {
+    result = await removePairEntryAndDir(base, pair.pairId);
+  } catch (err) {
+    console.error(`Error: could not delete state dir for ${pair.pairId}; registry entry kept \u2014 retry or run \`abg pairs prune\`. ` + `${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  if (result.keptLive) {
+    console.log(`Pair ${pair.pairId} is live again (relaunched concurrently); not removed. Stop it first, then retry.`);
+    return;
+  }
+  const dirNote = result.dirRemoved ? " State directory deleted." : "";
+  if (result.entry) {
+    console.log(`Removed pair ${result.entry.pairId}; slot ${result.entry.slot} is now available.${dirNote}`);
+  } else {
+    console.log(`Pair ${pair.pairId} was already absent from the registry.${dirNote}`);
+  }
+}
+async function runPrune(args) {
+  const dryRun = args.includes("--dry-run");
+  for (const arg of args) {
+    if (arg !== "--dry-run") {
+      console.error(`Unknown prune argument: ${arg}`);
+      console.error("Usage: abg pairs prune [--dry-run]");
+      process.exit(1);
+    }
+  }
+  const base = computeBaseDir();
+  const registered = new Set(listPairs(base).map((pair) => pair.pairId.toLowerCase()));
+  const removed = [];
+  const kept = [];
+  for (const name of listPairDirs(base)) {
+    let id;
+    try {
+      id = validatePairId(name);
+    } catch {
+      kept.push({ name, reason: "not a managed pair-id directory" });
+      continue;
+    }
+    if (id !== name) {
+      kept.push({ name, reason: "directory name is not a canonical pair id" });
+      continue;
+    }
+    if (registered.has(id.toLowerCase())) {
+      kept.push({ name, reason: "registered \u2014 use `abg pairs rm`" });
+      continue;
+    }
+    if (pairDirDaemonAlive(base, id)) {
+      kept.push({ name, reason: "daemon still alive" });
+      continue;
+    }
+    if (dryRun) {
+      removed.push(name);
+      continue;
+    }
+    try {
+      const outcome = await removeUnregisteredPairDir(base, id);
+      if (outcome.removed) {
+        removed.push(name);
+      } else if (outcome.reason === "registered") {
+        kept.push({ name, reason: "registered during prune \u2014 use `abg pairs rm`" });
+      } else if (outcome.reason === "live") {
+        kept.push({ name, reason: "daemon became live during prune" });
+      } else {
+        kept.push({ name, reason: "already gone" });
+      }
+    } catch (err) {
+      kept.push({ name, reason: `error: ${err instanceof Error ? err.message : String(err)}` });
+    }
+  }
+  printPruneSummary(removed, kept, dryRun);
+}
+function printPruneSummary(removed, kept, dryRun) {
+  if (removed.length === 0 && kept.length === 0) {
+    console.log("No pair directories found.");
+    return;
+  }
+  if (removed.length > 0) {
+    console.log(dryRun ? "Would remove orphan pair directories:" : "Removed orphan pair directories:");
+    for (const name of removed)
+      console.log(`  ${name}`);
+  } else {
+    console.log(dryRun ? "No orphan pair directories to remove." : "No orphan pair directories removed.");
+  }
+  if (kept.length > 0) {
+    console.log("Kept:");
+    for (const { name, reason } of kept)
+      console.log(`  ${name} (${reason})`);
+  }
+  if (dryRun) {
+    console.log(`
+(dry run \u2014 nothing was deleted. Re-run without --dry-run to apply.)`);
+  }
+}
+async function collectRows() {
+  const base = computeBaseDir();
+  const rows = await Promise.all(listPairs(base).map((pair) => rowForPair(base, pair)));
+  const legacy = detectLegacyRootDaemon(base);
+  if (legacy) {
+    rows.push({
+      pairId: "(legacy-root)",
+      name: "-",
+      slot: null,
+      ports: { appPort: 4500, proxyPort: 4501, controlPort: legacy.controlPort },
+      source: "legacy",
+      cwd: base,
+      running: true,
+      pid: legacy.pid,
+      threadId: null,
+      threadStatus: null,
+      threadUpdatedAt: null
+    });
+  }
+  return rows;
+}
+async function rowForPair(base, pair) {
+  const ports = portsForEntry(pair);
+  const stateDir = new StateDirResolver(join13(base, "pairs", pair.pairId));
+  const lifecycle = new DaemonLifecycle({
+    stateDir,
+    controlPort: ports.controlPort,
+    log: () => {}
+  });
+  const [running, status] = await Promise.all([
+    lifecycle.isHealthy(),
+    Promise.resolve(lifecycle.readStatus())
+  ]);
+  const thread = readRawCurrentThread(stateDir);
+  return {
+    pairId: pair.pairId,
+    name: pair.name ?? "-",
+    slot: pair.slot,
+    ports,
+    source: pair.source,
+    cwd: pair.cwd,
+    running,
+    pid: typeof status?.pid === "number" ? status.pid : null,
+    threadId: thread?.threadId ?? null,
+    threadStatus: thread?.status ?? null,
+    threadUpdatedAt: thread?.updatedAt ?? null
+  };
+}
+function printTable(rows, options = {}) {
+  if (rows.length === 0) {
+    console.log("No pairs registered.");
+    return;
+  }
+  const data = rows.map((row) => ({
+    name: row.name,
+    pairId: row.pairId,
+    slot: row.slot === null ? "-" : String(row.slot),
+    ports: `${row.ports.appPort}/${row.ports.proxyPort}/${row.ports.controlPort}`,
+    source: row.source,
+    cwd: row.cwd,
+    status: row.running ? "running" : "stopped",
+    pid: row.pid === null ? "-" : String(row.pid),
+    thread: row.threadId === null ? "-" : row.threadId,
+    threadStatus: row.threadStatus === null ? "-" : row.threadStatus
+  }));
+  const headers = {
+    name: "name",
+    pairId: "pairId",
+    slot: "slot",
+    ports: "app/proxy/control",
+    source: "source",
+    status: "status",
+    pid: "pid",
+    thread: "threadId",
+    threadStatus: "thread",
+    cwd: "cwd"
+  };
+  const visibleKeys = options.includeThreads ? ["name", "pairId", "slot", "ports", "source", "status", "pid", "thread", "threadStatus", "cwd"] : ["name", "pairId", "slot", "ports", "source", "status", "pid", "cwd"];
+  const widths = Object.fromEntries(visibleKeys.map((key) => [
+    key,
+    Math.max(headers[key].length, ...data.map((row) => row[key].length))
+  ]));
+  const line = (row) => visibleKeys.map((key) => row[key].padEnd(widths[key])).join("  ");
+  console.log(line(headers));
+  console.log(visibleKeys.map((key) => "-".repeat(widths[key])).join("  "));
+  for (const row of data) {
+    console.log(line(row));
+  }
+}
+function printKnownPairs2(base) {
+  const pairs = listPairs(base);
+  if (pairs.length === 0) {
+    console.log("No pairs registered.");
+    return;
+  }
+  console.log("Known pairs:");
+  for (const pair of pairs) {
+    console.log(`  ${pair.pairId}`);
+  }
+}
+var init_pairs = __esm(() => {
+  init_daemon_lifecycle();
+  init_pair_registry();
+  init_pair_resolver();
+  init_state_dir();
+  init_thread_state();
+  init_kill();
+});
+
+// src/daemon-status.ts
+async function fetchDaemonStatus(port, path = "/healthz", timeoutMs = DAEMON_STATUS_FETCH_TIMEOUT_MS) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}${path}`, { signal: controller.signal });
+    if (!response.ok)
+      return null;
+    return await response.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var DAEMON_STATUS_FETCH_TIMEOUT_MS = 1000;
+
+// src/resume-pollution.ts
+import { Database } from "bun:sqlite";
+import {
+  copyFileSync,
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync7,
+  readFileSync as readFileSync11
+} from "fs";
+import { dirname as dirname5, join as join14 } from "path";
+function isKickoffText(text) {
+  if (!text)
+    return false;
+  return KICKOFF_FINGERPRINTS.some((fingerprint) => text.includes(fingerprint));
 }
-async function waitForProxyReady(proxyUrl, maxRetries = 20, delayMs = 100) {
-  const healthUrl = proxyHealthUrl(proxyUrl);
-  for (let attempt = 0;attempt < maxRetries; attempt++) {
+function extractFirstRealUserMessage(rolloutPath) {
+  if (!existsSync11(rolloutPath))
+    return null;
+  const raw = readFileSync11(rolloutPath, "utf-8");
+  for (const line of raw.split(`
+`)) {
+    if (!line.trim())
+      continue;
+    let entry;
     try {
-      const response = await fetch(healthUrl);
-      if (response.ok) {
-        return;
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const message = extractUserText(entry);
+    if (!message)
+      continue;
+    if (isSyntheticUserMessage(message))
+      continue;
+    return message.trim();
+  }
+  return null;
+}
+function scanResumePollution(options = {}) {
+  const codexHome2 = options.codexHome ?? codexHome();
+  const dbPath = options.dbPath ?? join14(codexHome2, "state_5.sqlite");
+  if (!existsSync11(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 });
+  try {
+    const rows = db.query(`
+      select id, cwd, rollout_path as rolloutPath, title,
+             first_user_message as firstUserMessage, preview
+      from threads
+      where archived = 0 and (
+        first_user_message like '%AgentBridge%' or
+        first_user_message like '%multi-agent collaboration%' or
+        title like '%AgentBridge%' or
+        title like '%multi-agent collaboration%' or
+        preview like '%AgentBridge%' or
+        preview like '%multi-agent collaboration%'
+      )
+      order by updated_at desc
+    `).all();
+    const candidates = [];
+    for (const row of rows) {
+      const pollutedFields = [
+        isKickoffText(row.title) ? "title" : null,
+        isKickoffText(row.firstUserMessage) ? "first_user_message" : null,
+        isKickoffText(row.preview) ? "preview" : null
+      ].filter(Boolean);
+      if (pollutedFields.length === 0)
+        continue;
+      const realMessage = extractFirstRealUserMessage(row.rolloutPath);
+      if (!realMessage) {
+        candidates.push({
+          id: row.id,
+          cwd: row.cwd,
+          rolloutPath: row.rolloutPath,
+          title: row.title,
+          firstUserMessage: row.firstUserMessage,
+          preview: row.preview,
+          action: "delete",
+          replacementTitle: row.title,
+          replacementFirstUserMessage: row.firstUserMessage,
+          replacementPreview: row.preview,
+          reason: `kickoff-only, polluted ${pollutedFields.join(", ")}`
+        });
+        continue;
       }
-    } catch {}
-    await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      candidates.push({
+        id: row.id,
+        cwd: row.cwd,
+        rolloutPath: row.rolloutPath,
+        title: row.title,
+        firstUserMessage: row.firstUserMessage,
+        preview: row.preview,
+        action: "rename",
+        replacementTitle: isKickoffText(row.title) ? sidebarTitle(realMessage) : row.title,
+        replacementFirstUserMessage: isKickoffText(row.firstUserMessage) ? realMessage : row.firstUserMessage,
+        replacementPreview: isKickoffText(row.preview) ? previewText(realMessage) : row.preview,
+        reason: `polluted ${pollutedFields.join(", ")}`
+      });
+    }
+    let renamed = 0;
+    let deleted = 0;
+    let backupDir;
+    if (options.apply && candidates.length > 0) {
+      backupDir = backupCodexStateFiles(dbPath, options.now);
+      const update = db.prepare(`
+        update threads
+        set title = ?,
+            first_user_message = ?,
+            preview = ?
+        where id = ?
+      `);
+      const remove = db.prepare(`delete from threads where id = ?`);
+      const tx = db.transaction((items) => {
+        for (const item of items) {
+          if (item.action === "delete") {
+            remove.run(item.id);
+            deleted++;
+          } else {
+            update.run(item.replacementTitle, item.replacementFirstUserMessage, item.replacementPreview, item.id);
+            renamed++;
+          }
+        }
+      });
+      tx(candidates);
+    }
+    const applied = renamed + deleted;
+    return { codexHome: codexHome2, dbPath, scanned: rows.length, candidates, applied, renamed, deleted, backupDir };
+  } finally {
+    db.close();
   }
-  throw new Error(`Timed out waiting for Codex proxy readiness on ${healthUrl}`);
 }
-var OWNED_FLAGS2;
-var init_codex = __esm(() => {
-  init_state_dir();
-  init_config_service();
-  init_daemon_lifecycle();
-  init_stderr_ring_buffer();
-  init_claude();
-  OWNED_FLAGS2 = ["--remote"];
+function backupCodexStateFiles(dbPath, now = new Date().toISOString()) {
+  const safeStamp = now.replace(/[:.]/g, "-");
+  const base = join14(dirname5(dbPath), "agentbridge-backups", `resume-pollution-${safeStamp}`);
+  mkdirSync7(base, { recursive: true });
+  for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (!existsSync11(path))
+      continue;
+    const target = join14(base, path.split("/").pop());
+    mkdirSync7(dirname5(target), { recursive: true });
+    copyFileSync(path, target);
+  }
+  return base;
+}
+function extractUserText(entry) {
+  if (entry?.type === "event_msg" && entry.payload?.type === "user_message") {
+    return typeof entry.payload.message === "string" ? entry.payload.message : null;
+  }
+  if (entry?.type === "response_item" && entry.payload?.type === "message" && entry.payload?.role === "user") {
+    const content = entry.payload.content;
+    if (!Array.isArray(content))
+      return null;
+    const parts = content.map((item) => typeof item?.text === "string" ? item.text : typeof item?.input_text?.text === "string" ? item.input_text.text : null).filter((part) => !!part);
+    return parts.length > 0 ? parts.join(`
+`) : null;
+  }
+  return null;
+}
+function isSyntheticUserMessage(message) {
+  return isKickoffText(message) || message.includes("AGENTS.md instructions for") || message.includes("<environment_context>");
+}
+function sidebarTitle(message) {
+  return compact(message).slice(0, 80);
+}
+function previewText(message) {
+  return compact(message).slice(0, 160);
+}
+function compact(message) {
+  return message.replace(/\s+/g, " ").trim();
+}
+var KICKOFF_FINGERPRINTS;
+var init_resume_pollution = __esm(() => {
+  init_thread_state();
+  KICKOFF_FINGERPRINTS = [
+    "Claude Code has connected via AgentBridge",
+    "You are now in a multi-agent collaboration session",
+    "When you receive a complex task, propose a division of labor to Claude"
+  ];
 });
 
-// src/cli/kill.ts
-var exports_kill = {};
-__export(exports_kill, {
-  runKill: () => runKill
+// src/cli/doctor.ts
+var exports_doctor = {};
+__export(exports_doctor, {
+  runDoctor: () => runDoctor,
+  formatDoctorReport: () => formatDoctorReport
 });
-import { execFileSync as execFileSync5 } from "child_process";
-import { readFileSync as readFileSync4, unlinkSync as unlinkSync3 } from "fs";
-async function runKill() {
-  console.log(`AgentBridge Kill \u2014 stopping daemon and managed Codex TUI
-`);
-  const stateDir = new StateDirResolver;
-  const controlPort = parseInt(process.env.AGENTBRIDGE_CONTROL_PORT ?? "4502", 10);
-  const lifecycle = new DaemonLifecycle({
-    stateDir,
-    controlPort,
-    log: (msg) => console.log(`  ${msg}`)
-  });
-  lifecycle.markKilled();
-  const tuiKilled = await killManagedCodexTui(stateDir, (msg) => console.log(`  ${msg}`));
-  const killed = await lifecycle.kill();
-  if (killed || tuiKilled) {
-    console.log(`
-AgentBridge stopped.`);
-    console.log("Please restart Claude Code (`agentbridge claude`), switch to a new conversation, or run `/resume` to fully disconnect.");
-  } else {
-    console.log(`
-No running AgentBridge daemon or managed Codex TUI found.`);
-    console.log("Stale state files cleaned up (if any).");
+import { existsSync as existsSync12, readFileSync as readFileSync12, readdirSync as readdirSync4, realpathSync as realpathSync3, statSync as statSync5 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join15 } from "path";
+async function runDoctor(args = []) {
+  if (args[0] === "resume-pollution") {
+    runResumePollution(args.slice(1));
+    return;
+  }
+  const json = args.includes("--json");
+  const agent = args.includes("--agent");
+  const { pairFlag, rest } = parsePairFlag(args.filter((arg) => arg !== "--json" && arg !== "--agent"));
+  const unknown = rest.filter((arg) => arg.startsWith("-"));
+  if (unknown.length > 0) {
+    console.error(`Unknown doctor option(s): ${unknown.join(", ")}`);
+    console.error("Usage: abg doctor [--pair <name|id>] [--json] [--agent]");
+    process.exit(1);
+  }
+  let resolution;
+  try {
+    resolution = resolvePairReadOnly(pairFlag);
+  } catch (err) {
+    console.error(`[agentbridge] ${err.message}`);
+    process.exit(1);
+  }
+  const report = await buildDoctorReport(resolution.pair, resolution.registered);
+  if (agent) {
+    report.checks.push({
+      name: "agent backend",
+      status: "warn",
+      detail: "--agent is reserved for read-only delegated analysis; static diagnostics were run locally in this build."
+    });
   }
+  if (report.checks.some((check) => check.status === "fail")) {
+    process.exitCode = 1;
+  }
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  printDoctorReport(report);
 }
-async function killManagedCodexTui(stateDir, log, gracefulTimeoutMs = 3000) {
-  const pid = readTuiPid(stateDir);
-  if (!pid) {
-    log("No Codex TUI pid file found");
-    removeTuiPidFile(stateDir);
-    return false;
+function runResumePollution(args) {
+  const json = args.includes("--json");
+  const apply = args.includes("--apply");
+  const codexHomeIndex = args.indexOf("--codex-home");
+  const codexHome2 = codexHomeIndex >= 0 ? args[codexHomeIndex + 1] : undefined;
+  if (codexHomeIndex >= 0 && !codexHome2) {
+    console.error("Usage: abg doctor resume-pollution [--json] [--apply] [--codex-home <path>]");
+    process.exit(1);
   }
-  if (!isProcessAlive(pid)) {
-    log(`Codex TUI pid ${pid} is not alive, cleaning up stale pid file`);
-    removeTuiPidFile(stateDir);
-    return false;
+  const report = scanResumePollution({ codexHome: codexHome2, apply });
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
   }
-  if (!isManagedCodexTuiProcess(pid)) {
-    log(`Pid ${pid} is alive but is NOT a managed AgentBridge Codex TUI \u2014 refusing to kill. Cleaning up stale pid file.`);
-    removeTuiPidFile(stateDir);
-    return false;
+  const renameCount = report.candidates.filter((c) => c.action === "rename").length;
+  const deleteCount = report.candidates.filter((c) => c.action === "delete").length;
+  console.log(`Resume pollution scan: ${report.candidates.length} candidate(s) ` + `(${renameCount} rename, ${deleteCount} delete) from ${report.dbPath}`);
+  if (report.backupDir)
+    console.log(`Backup: ${report.backupDir}`);
+  for (const candidate of report.candidates) {
+    if (candidate.action === "delete") {
+      const verb = apply ? "deleted" : "would delete";
+      console.log(`${verb} ${candidate.id}: ${candidate.reason}`);
+    } else {
+      const verb = apply ? "updated" : "would rename";
+      console.log(`${verb} ${candidate.id}: ${candidate.reason}`);
+      console.log(`  title: ${candidate.replacementTitle}`);
+    }
   }
-  log(`Sending SIGTERM to Codex TUI pid ${pid}`);
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch {
-    removeTuiPidFile(stateDir);
-    return false;
+  if (apply) {
+    console.log(`Applied: ${report.renamed} renamed, ${report.deleted} deleted.`);
+  } else if (report.candidates.length > 0) {
+    console.log("Dry-run only. Re-run with --apply to rename/delete Codex sessions after backing up state.");
   }
-  const deadline = Date.now() + gracefulTimeoutMs;
-  while (Date.now() < deadline) {
-    if (!isProcessAlive(pid)) {
-      log(`Codex TUI pid ${pid} stopped gracefully`);
-      removeTuiPidFile(stateDir);
-      return true;
+}
+async function buildDoctorReport(pair, registered) {
+  const cwd = process.cwd();
+  const env = inspectAgentBridgeEnv({ cwd, env: process.env });
+  const [health, ready] = registered ? await Promise.all([
+    fetchDaemonStatus(pair.ports.controlPort, "/healthz"),
+    fetchDaemonStatus(pair.ports.controlPort, "/readyz")
+  ]) : [null, null];
+  const launcherStamped = BUILD_INFO.commit !== "source";
+  const buildDrift = !launcherStamped ? null : health?.build ? !sameRuntimeContract(health.build, BUILD_INFO) : health ? true : null;
+  const rawThread = readRawCurrentThread(pair.stateDir);
+  const usableThread = readUsableCurrentThread({
+    stateDir: pair.stateDir,
+    pairId: pair.manual ? null : pair.pairId,
+    pairName: pair.name,
+    cwd
+  });
+  const checks = [];
+  checks.push({
+    name: "pair registration",
+    status: registered ? "ok" : "warn",
+    detail: registered ? pair.manual ? "manual mode (explicit env)" : `registered as ${pair.pairId}` : `not registered yet \u2014 would be ${pair.pairId} (created on first launch)`,
+    hint: registered ? undefined : "\u8BE5\u76EE\u5F55\u8FD8\u6CA1\u6709\u6CE8\u518C\u8FC7 pair\uFF1A\u8FD0\u884C `agentbridge claude` \u5373\u4F1A\u521B\u5EFA\u3002\u4EE5\u4E0B\u68C0\u67E5\u6309\u672A\u542F\u52A8\u72B6\u6001\u89E3\u8BFB\u3002"
+  });
+  checks.push({
+    name: "env",
+    status: env.ok ? "ok" : "fail",
+    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({
+    name: "daemon health",
+    status: health ? "ok" : "warn",
+    detail: health ? `healthz reachable pid=${health.pid}` : registered ? `no daemon reachable on :${pair.ports.controlPort}` : "n/a \u2014 pair not registered",
+    hint: health ? undefined : "daemon \u672A\u8FD0\u884C\u3002\u8FD0\u884C `agentbridge claude`\uFF08\u6216 `agentbridge codex`\uFF09\u4F1A\u81EA\u52A8\u542F\u52A8\u5B83\u3002"
+  });
+  checks.push({
+    name: "daemon readiness",
+    status: ready ? "ok" : health ? "warn" : "skip",
+    detail: ready ? `ready thread=${ready.threadId ?? "none"}` : health ? "readyz is not OK" : "n/a \u2014 daemon not running",
+    hint: !ready && health ? "daemon \u5728\u8FD0\u884C\u4F46 codex app-server \u5C1A\u672A\u5C31\u7EEA\uFF1B\u7A0D\u5019\u7247\u523B\u91CD\u8BD5\uFF0C\u6301\u7EED\u4E0D\u5C31\u7EEA\u8BF7\u67E5\u770B\u4E0B\u65B9 daemon log\u3002" : undefined
+  });
+  checks.push({
+    name: "build drift",
+    status: buildDrift === false ? "ok" : buildDrift === true ? "fail" : "skip",
+    detail: buildDrift === false ? `runtime matches launcher ${formatBuildInfo(BUILD_INFO)}` : buildDrift === true ? `runtime ${formatBuildInfo(health?.build)} differs from launcher ${formatBuildInfo(BUILD_INFO)}` : launcherStamped ? "n/a \u2014 daemon not running" : "n/a \u2014 launcher running from source (unstamped)",
+    hint: buildDrift === true ? "daemon \u8FD0\u884C\u7684\u662F\u65E7\u6784\u5EFA\uFF08\u901A\u5E38\u7531\u65E7\u7248 CLI \u6216\u672A\u91CD\u5F00\u7684 Claude Code \u7A97\u53E3\u542F\u52A8\uFF09\u3002" + "\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684 Codex \u4F1A\u8BDD\u65F6\uFF0C\u8FD0\u884C `abg kill` \u540E\u91CD\u65B0 `agentbridge claude` \u5373\u53EF\u5BF9\u9F50\uFF1B" + "\u6709\u6D3B\u8DC3\u4F1A\u8BDD\u5219\u7B49\u6536\u5C3E\u540E\u518D\u91CD\u542F\u2014\u2014\u7248\u672C\u5DEE\u5F02\u4E0D\u4F1A\u5F3A\u6740\u6D3B\u8DC3\u4F1A\u8BDD\uFF0C\u53EF\u4EE5\u7EE7\u7EED\u7528\u3002" : undefined
+  });
+  checks.push(artifactAlignmentCheck());
+  checks.push({
+    name: "current thread",
+    status: usableThread ? "ok" : rawThread ? "warn" : registered ? "warn" : "skip",
+    detail: usableThread ? `current=${usableThread.threadId}` : rawThread ? rawThread.status === "current" ? `stored ${rawThread.threadId} has no rollout file yet` : `stored ${rawThread.threadId} is still ${rawThread.status} (no first response yet)` : registered ? "no current-thread.json for this pair" : "n/a \u2014 pair not registered",
+    hint: usableThread ? undefined : rawThread ? "\u901A\u5E38\u65E0\u5BB3\uFF1A\u7EBF\u7A0B\u8FD8\u6CA1\u6709\u4EA7\u751F\u9996\u6761\u56DE\u5E94\u3001\u6216 rollout \u6587\u4EF6\u5C1A\u672A\u843D\u76D8\u3002" + "\u4EC5\u5F53 `abg codex`\uFF08resume\uFF09\u5931\u8D25\u65F6\u624D\u9700\u8981\u5904\u7406\uFF1A\u7528 `abg codex --new` \u5F00\u65B0\u7EBF\u7A0B\u3002" : registered ? "\u5C1A\u65E0\u7EBF\u7A0B\u8BB0\u5F55\uFF1A\u8FDE\u63A5 Codex \u540E\u5EFA\u7ACB\u9996\u4E2A\u7EBF\u7A0B\u65F6\u4F1A\u81EA\u52A8\u5199\u5165\uFF0C\u65E0\u9700\u5904\u7406\u3002" : undefined
+  });
+  const pairProxyUrl = `ws://127.0.0.1:${pair.ports.proxyPort}`;
+  const managedTuis = listManagedCodexTuiProcesses();
+  const attachedHere = [];
+  const attachedElsewhere = [];
+  for (const tui of managedTuis) {
+    if (commandMatchesManagedCodexTui(tui.command, pairProxyUrl)) {
+      attachedHere.push(tui);
+    } else {
+      attachedElsewhere.push(tui);
     }
-    await new Promise((resolve2) => setTimeout(resolve2, 200));
   }
-  log(`Codex TUI pid ${pid} did not stop gracefully, sending SIGKILL`);
+  checks.push({
+    name: "codex tui (this pair)",
+    status: attachedHere.length > 0 ? "ok" : "warn",
+    detail: attachedHere.length > 0 ? `${attachedHere.length} attached to ${pairProxyUrl} (pid ${attachedHere.map((t) => t.pid).join(", ")})` : `no managed Codex TUI attached to this pair's proxy ${pairProxyUrl}`,
+    hint: attachedHere.length > 0 ? undefined : "\u53E6\u5F00\u4E00\u4E2A\u7EC8\u7AEF\u3001\u5728\u540C\u4E00\u76EE\u5F55\u8FD0\u884C `agentbridge codex` \u8FDE\u63A5\u672C pair\u3002"
+  });
+  checks.push({
+    name: "codex tui (other pairs)",
+    status: attachedElsewhere.length > 0 ? "warn" : "ok",
+    detail: attachedElsewhere.length > 0 ? `${attachedElsewhere.length} managed Codex TUI(s) attached to a DIFFERENT pair/proxy \u2014 likely started from another cwd, will not bridge here: ` + attachedElsewhere.map((t) => `pid ${t.pid}\u2192${t.remoteUrl ?? "?"}`).join(", ") : "no managed Codex TUI attached to another pair",
+    hint: attachedElsewhere.length > 0 ? "\u8FD9\u4E9B TUI \u5C5E\u4E8E\u5176\u4ED6\u76EE\u5F55\u7684 pair\uFF0C\u4E0D\u5F71\u54CD\u672C pair\uFF1B\u5B83\u4EEC\u4E0D\u4F1A\u6865\u63A5\u5230\u8FD9\u91CC\u3002\u5982\u4E0D\u518D\u9700\u8981\uFF0C\u53BB\u5BF9\u5E94\u76EE\u5F55\u8FD0\u884C `abg kill`\u3002" : undefined
+  });
+  for (const [name, path] of [
+    ["daemon log", pair.stateDir.logFile],
+    ["codex wrapper log", pair.stateDir.codexWrapperLogFile]
+  ]) {
+    checks.push(logCheck(name, path));
+  }
+  return {
+    cwd,
+    pair: {
+      pairId: pair.pairId,
+      name: pair.name,
+      manual: pair.manual,
+      slot: pair.slot,
+      stateDir: pair.stateDir.dir,
+      ports: pair.ports
+    },
+    env,
+    daemon: { health, ready, buildDrift },
+    tui: {
+      attachedHere: attachedHere.map((t) => ({ pid: t.pid, remoteUrl: t.remoteUrl })),
+      attachedElsewhere: attachedElsewhere.map((t) => ({ pid: t.pid, remoteUrl: t.remoteUrl }))
+    },
+    checks
+  };
+}
+function artifactAlignmentCheck() {
+  const stamps = [];
+  if (BUILD_INFO.commit !== "source") {
+    stamps.push({ label: `launcher(${BUILD_INFO.bundle})`, commit: BUILD_INFO.commit });
+  }
+  const bin = Bun.which("agentbridge") ?? Bun.which("abg");
+  if (bin) {
+    try {
+      const commit = extractBundleCommit(realpathSync3(bin));
+      if (commit)
+        stamps.push({ label: "global-cli", commit });
+    } catch {}
+  }
+  const cacheRoot = join15(homedir5(), ".claude", "plugins", "cache", "agentbridge", "agentbridge");
   try {
-    process.kill(pid, "SIGKILL");
+    for (const version of readdirSync4(cacheRoot)) {
+      const commit = extractBundleCommit(join15(cacheRoot, version, "server", "daemon.js"));
+      if (commit)
+        stamps.push({ label: `plugin-cache@${version}`, commit });
+    }
   } catch {}
-  removeTuiPidFile(stateDir);
-  return true;
+  const repoBundle = join15(process.cwd(), "plugins", "agentbridge", "server", "daemon.js");
+  if (existsSync12(repoBundle)) {
+    const commit = extractBundleCommit(repoBundle);
+    if (commit)
+      stamps.push({ label: "repo-bundle", commit });
+  }
+  if (stamps.length < 2) {
+    return {
+      name: "artifact alignment",
+      status: "skip",
+      detail: "n/a \u2014 fewer than two stamped artifacts found"
+    };
+  }
+  const commits = new Set(stamps.map((s) => s.commit));
+  const rendered = stamps.map((s) => `${s.label}=${s.commit}`).join(", ");
+  if (commits.size === 1) {
+    return { name: "artifact alignment", status: "ok", detail: rendered };
+  }
+  return {
+    name: "artifact alignment",
+    status: "fail",
+    detail: `deployed artifacts are at DIFFERENT builds: ${rendered}`,
+    hint: "\u90E8\u7F72\u7269\u7248\u672C\u5206\u88C2\u4F1A\u5BFC\u81F4\u4E92\u76F8\u66FF\u6362 daemon\uFF08\u6740\u6389\u6D3B\u4F1A\u8BDD\uFF09\u3002\u5728\u4ED3\u5E93\u76EE\u5F55\u8FD0\u884C `bun run install:global` " + "\u4E00\u6B21\u6027\u5BF9\u9F50\u5168\u5C40 CLI \u4E0E\u63D2\u4EF6\u7F13\u5B58\uFF0C\u7136\u540E\u5173\u95ED\u5E76\u91CD\u5F00\u4ECD\u5728\u4F7F\u7528\u65E7\u63D2\u4EF6\u7684 Claude Code \u7A97\u53E3\u3002"
+  };
 }
-function readTuiPid(stateDir) {
+function extractBundleCommit(path) {
   try {
-    const raw = readFileSync4(stateDir.tuiPidFile, "utf-8").trim();
-    if (!raw)
-      return null;
-    const pid = Number.parseInt(raw, 10);
-    return Number.isFinite(pid) ? pid : null;
+    const match = readFileSync12(path, "utf-8").match(/commit:\s*defineString\("([^"]+)",\s*"source"\)/);
+    return match ? match[1] : null;
   } catch {
     return null;
   }
 }
-function removeTuiPidFile(stateDir) {
-  try {
-    unlinkSync3(stateDir.tuiPidFile);
-  } catch {}
+function logCheck(name, path) {
+  if (!existsSync12(path)) {
+    return {
+      name,
+      status: "warn",
+      detail: `missing: ${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 = statSync5(path);
+  if (stat.size > LARGE_LOG_WARN_BYTES) {
+    return {
+      name,
+      status: "warn",
+      detail: `${path} (${stat.size} bytes, oversized; stop the pair, rebuild/reinstall, then rotate or remove this log)`,
+      hint: "\u65E5\u5FD7\u8FC7\u5927\uFF1A`abg kill` \u505C\u6B62 pair \u540E\u5220\u9664\u8BE5\u6587\u4EF6\u518D\u91CD\u542F\u5373\u53EF\u3002"
+    };
+  }
+  return { name, status: "ok", detail: `${path} (${stat.size} bytes)` };
 }
-function isManagedCodexTuiProcess(pid) {
-  try {
-    const cmd = execFileSync5("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf-8" }).trim();
-    return cmd.includes("codex") && cmd.includes("--enable") && cmd.includes("tui_app_server") && cmd.includes("--remote");
-  } catch {
-    return false;
+function formatDoctorReport(report) {
+  const lines = [];
+  lines.push(`AgentBridge doctor: ${report.pair.pairId}`);
+  lines.push(`cwd: ${report.cwd}`);
+  lines.push(`state: ${report.pair.stateDir}`);
+  lines.push(`ports: ${report.pair.ports.appPort}/${report.pair.ports.proxyPort}/${report.pair.ports.controlPort}`);
+  for (const check of report.checks) {
+    lines.push(`${check.status.toUpperCase().padEnd(4)} ${check.name}: ${check.detail}`);
+    if ((check.status === "warn" || check.status === "fail") && check.hint) {
+      lines.push(`     \u21B3 ${check.hint}`);
+    }
+  }
+  const fails = report.checks.filter((c) => c.status === "fail");
+  const warns = report.checks.filter((c) => c.status === "warn");
+  lines.push("");
+  if (fails.length === 0 && warns.length === 0) {
+    lines.push("\u7ED3\u8BBA: \u5168\u90E8\u68C0\u67E5\u901A\u8FC7 \u2705");
+  } else if (fails.length > 0) {
+    lines.push(`\u7ED3\u8BBA: ${fails.length} FAIL / ${warns.length} WARN \u2014 \u4F18\u5148\u5904\u7406: ${fails[0].name}\uFF08\u89C1\u4E0A\u65B9 \u21B3 \u63D0\u793A\uFF09`);
+  } else {
+    lines.push(`\u7ED3\u8BBA: ${warns.length} WARN\uFF08\u65E0 FAIL\uFF09\u2014 \u591A\u6570 WARN \u662F\u5F85\u8FDE\u63A5/\u672A\u542F\u52A8\u7684\u6B63\u5E38\u4E2D\u95F4\u6001\uFF0C\u6309 \u21B3 \u63D0\u793A\u5224\u65AD\u5373\u53EF`);
   }
+  return lines;
 }
-var init_kill = __esm(() => {
-  init_state_dir();
-  init_daemon_lifecycle();
+function printDoctorReport(report) {
+  for (const line of formatDoctorReport(report)) {
+    console.log(line);
+  }
+}
+var LARGE_LOG_WARN_BYTES;
+var init_doctor = __esm(() => {
+  init_build_info();
+  init_env_guard();
+  init_pair_resolver();
+  init_thread_state();
+  init_resume_pollution();
+  init_process_lifecycle();
+  LARGE_LOG_WARN_BYTES = 100 * 1024 * 1024;
 });
 
-// package.json
-var require_package = __commonJS((exports, module) => {
-  module.exports = {
-    name: "@raysonmeng/agentbridge",
-    version: "0.1.6",
-    description: "Bridge between Claude Code and Codex \u2014 bidirectional agent communication via MCP Channel + JSON-RPC",
-    type: "module",
-    bin: {
-      agentbridge: "dist/cli.js",
-      abg: "dist/cli.js"
-    },
-    files: [
-      "dist/",
-      "plugins/",
-      ".claude-plugin/",
-      "scripts/postinstall.cjs",
-      "README.md",
-      "LICENSE"
-    ],
-    scripts: {
-      start: "bun run src/bridge.ts",
-      "build:cli": "mkdir -p dist && bun build src/cli.ts --outfile dist/cli.js --target bun && chmod +x dist/cli.js",
-      "build:plugin": "mkdir -p plugins/agentbridge/server && bun build src/bridge.ts --outfile plugins/agentbridge/server/bridge-server.js --target bun && bun build src/daemon.ts --outfile plugins/agentbridge/server/daemon.js --target bun",
-      "verify:plugin-sync": "node scripts/verify-plugin-sync.cjs",
-      postinstall: "node scripts/postinstall.cjs",
-      prepublishOnly: "bun run build:cli && bun run build:plugin",
-      "validate:plugin": "claude plugin validate plugins/agentbridge && claude plugin validate .claude-plugin/marketplace.json",
-      test: "bun test src",
-      typecheck: "tsc --noEmit",
-      "validate:plugin-versions": "bun scripts/check-plugin-versions.js",
-      check: "tsc --noEmit && bun test src && bun run verify:plugin-sync && bun scripts/check-plugin-versions.js"
-    },
-    repository: {
-      type: "git",
-      url: "https://github.com/raysonmeng/agent-bridge.git"
-    },
-    homepage: "https://github.com/raysonmeng/agent-bridge#readme",
-    bugs: {
-      url: "https://github.com/raysonmeng/agent-bridge/issues"
-    },
-    keywords: [
-      "claude-code",
-      "codex",
-      "mcp",
-      "agent",
-      "bridge",
-      "multi-agent",
-      "channels"
-    ],
-    author: "AgentBridge Contributors",
-    license: "MIT",
-    devDependencies: {
-      "@modelcontextprotocol/sdk": "^1.27.1",
-      "@types/bun": "^1.3.11",
-      typescript: "^5.8.0"
+// src/budget/render.ts
+function formatEpoch(epochSeconds) {
+  if (!epochSeconds || epochSeconds <= 0)
+    return "\u672A\u77E5";
+  return new Date(epochSeconds * 1000).toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+}
+function formatWindow(window, label) {
+  if (!window)
+    return `${label} \u672A\u77E5`;
+  return `${label} ${window.util}%\uFF08\u91CD\u7F6E ${formatEpoch(window.resetEpoch)}\uFF09`;
+}
+function formatAgent(name, usage, snapshotAt) {
+  if (!usage)
+    return `${name}\uFF1A\u672A\u77E5\uFF08\u63A2\u6D4B\u4E0D\u53EF\u7528\uFF09`;
+  const parts = [
+    formatWindow(usage.fiveHour, "5h"),
+    formatWindow(usage.weekly, "\u5468"),
+    `\u95E8\u63A7 ${usage.gateUtil}%`,
+    `\u9884\u8B66 ${usage.warnUtil}%`
+  ];
+  if (usage.rateLimitedUntil > 0) {
+    parts.push(`\u9650\u6D41\u81F3 ${formatEpoch(usage.rateLimitedUntil)}`);
+  }
+  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`);
+  } else if (usage.stale) {
+    parts.push("\uFF08\u7F13\u5B58\u6570\u636E\uFF09");
+  }
+  return `${name}\uFF1A${parts.join(" \xB7 ")}`;
+}
+function renderBudgetSnapshot(snapshot) {
+  const lines = [];
+  lines.push(`\u3010\u9884\u7B97\u5FEB\u7167 \xB7 \u8D26\u53F7\u7EA7\u3011\u9636\u6BB5\uFF1A${PHASE_LABELS[snapshot.phase]} \xB7 \u66F4\u65B0\u4E8E ${formatEpoch(snapshot.updatedAt)}`);
+  lines.push(formatAgent("Claude", snapshot.claude, snapshot.updatedAt));
+  lines.push(formatAgent("Codex", snapshot.codex, snapshot.updatedAt));
+  if (snapshot.claude && snapshot.codex) {
+    const abs = Math.abs(snapshot.driftPct);
+    if (abs > 0) {
+      const heavier = snapshot.driftPct > 0 ? "Claude" : "Codex";
+      const lighter = snapshot.driftPct > 0 ? "Codex" : "Claude";
+      lines.push(`\u6F02\u79FB\uFF1A${heavier} \u6BD4 ${lighter} \u9AD8 ${abs} \u4E2A\u767E\u5206\u70B9`);
+    } else {
+      lines.push("\u6F02\u79FB\uFF1A\u53CC\u65B9\u6301\u5E73");
+    }
+  }
+  if (snapshot.paused) {
+    const resume = snapshot.resumeAfterEpoch ? `\uFF1B\u9884\u8BA1\u6062\u590D ${formatEpoch(snapshot.resumeAfterEpoch)}\uFF08\u4EE5\u5B9E\u6D4B\u4E3A\u51C6\uFF1B\u63D0\u524D\u5237\u65B0\u4F1A\u66F4\u65E9\u89E3\u9664\uFF09` : "";
+    const reason = snapshot.pauseReason ?? "\u989D\u5EA6\u63A5\u8FD1\u8017\u5C3D";
+    if (snapshot.pauseSide === "claude" && !snapshot.gateClosed) {
+      lines.push(`\u63A5\u529B\u4E2D\uFF1AClaude \u4FA7\u989D\u5EA6\u8017\u5C3D\uFF0C\u5DF2\u4EA4\u63A5 Codex \u7EE7\u7EED\u63A8\u8FDB\uFF08\u95F8\u95E8\u5F00\u653E\uFF09 \u2014 ${reason}${resume}`);
+    } else if (snapshot.pauseSide === "codex") {
+      lines.push(`\u6682\u505C\uFF1ACodex \u4FA7\u989D\u5EA6\u8017\u5C3D\uFF08\u95F8\u95E8\u5173\u95ED\uFF0CClaude \u53EF solo \u63A8\u8FDB\u72EC\u7ACB\u90E8\u5206\uFF09 \u2014 ${reason}${resume}`);
+    } else {
+      lines.push(`\u6682\u505C\uFF1A\u53CC\u4FA7\u8054\u5408\u6682\u505C\uFF08\u95F8\u95E8\u5173\u95ED\uFF09 \u2014 ${reason}${resume}`);
     }
+  } else {
+    lines.push("\u6682\u505C\uFF1A\u5426");
+  }
+  if (snapshot.parallelRecommended) {
+    lines.push("\u5E76\u884C\u5EFA\u8BAE\uFF1A\u989D\u5EA6\u5BCC\u4F59\u4E14\u4E34\u8FD1\u7ED3\u7B97\uFF0C\u5EFA\u8BAE\u62C6\u5206\u66F4\u591A\u5E76\u884C\u5B50\u4EFB\u52A1");
+  }
+  if (snapshot.codexTier !== "full") {
+    lines.push(`Codex \u6863\u4F4D\uFF1A${snapshot.codexTier}`);
+  }
+  if (snapshot.claudeAdvice) {
+    lines.push(`Claude \u5EFA\u8BAE\uFF1A${snapshot.claudeAdvice}`);
+  }
+  lines.push("\u6CE8\uFF1A\u767E\u5206\u6BD4\u4E3A\u8BA2\u9605\u8D26\u53F7\u7EA7\u7528\u91CF\uFF08\u540C\u673A\u5176\u4ED6\u4F1A\u8BDD\u5171\u4EAB\u540C\u4E00\u989D\u5EA6\u6C60\uFF09\u3002");
+  return lines.join(`
+`);
+}
+var PHASE_LABELS, BUDGET_UNAVAILABLE_TEXT = "\u9884\u7B97\u611F\u77E5\u4E0D\u53EF\u7528\uFF1A\u672A\u68C0\u6D4B\u5230 agent-quota-guard \u63A2\u9488\uFF08~/.budget-guard/bin/budget-probe\uFF09\u6216 budget \u529F\u80FD\u5DF2\u7981\u7528\u3002\u534F\u4F5C\u4E0D\u53D7\u5F71\u54CD\u3002";
+var init_render = __esm(() => {
+  PHASE_LABELS = {
+    normal: "normal\uFF08\u6B63\u5E38\uFF09",
+    balance: "balance\uFF08\u9700\u5747\u8861\uFF09",
+    parallel: "parallel\uFF08\u5EFA\u8BAE\u5E76\u884C\u63D0\u901F\uFF09",
+    paused: "paused\uFF08\u9884\u7B97\u5E72\u9884\u4E2D\uFF09"
   };
 });
 
+// src/cli/budget.ts
+var exports_budget = {};
+__export(exports_budget, {
+  runBudget: () => runBudget
+});
+async function runBudget(args) {
+  const json = args.includes("--json");
+  const { pairFlag } = parsePairFlag(args.filter((arg) => arg !== "--json"));
+  let resolution;
+  try {
+    resolution = resolvePairReadOnly(pairFlag);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) {
+      console.log(JSON.stringify({ ok: false, error: message }));
+    } else {
+      console.error(`[agentbridge] ${message}`);
+    }
+    process.exit(1);
+    return;
+  }
+  const { pair } = resolution;
+  if (!resolution.registered) {
+    if (json) {
+      console.log(JSON.stringify({ ok: false, error: "pair_not_registered" }));
+    } else {
+      console.error("\u8BE5\u76EE\u5F55\u5C1A\u65E0 pair\uFF0C\u5148\u8FD0\u884C abg claude");
+    }
+    process.exit(1);
+    return;
+  }
+  const status = await fetchDaemonStatus(pair.ports.controlPort);
+  if (!status) {
+    if (json) {
+      console.log(JSON.stringify({ ok: false, pairId: pair.pairId, error: "daemon_unreachable" }));
+    } else {
+      console.error(`AgentBridge daemon \u672A\u8FD0\u884C\uFF08pair ${pair.pairId}\uFF0C\u63A7\u5236\u7AEF\u53E3 ${pair.ports.controlPort}\uFF09\u3002` + "\u5148\u8FD0\u884C `abg claude` \u542F\u52A8\u4F1A\u8BDD\u3002");
+    }
+    process.exit(1);
+  }
+  if (json) {
+    console.log(JSON.stringify({ ok: true, pairId: status.pairId ?? pair.pairId, budget: status.budget ?? null }, null, 2));
+    return;
+  }
+  console.log(`pair: ${status.pairId ?? pair.pairId}`);
+  console.log(status.budget ? renderBudgetSnapshot(status.budget) : BUDGET_UNAVAILABLE_TEXT);
+}
+var init_budget = __esm(() => {
+  init_pair_resolver();
+  init_render();
+});
+
 // src/cli.ts
-async function main() {
+function parseTopLevel(args) {
+  const pairTokens = [];
+  let i = 0;
+  for (;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--pair") {
+      pairTokens.push(a);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        pairTokens.push(next);
+        i++;
+      }
+      continue;
+    }
+    if (a.startsWith("--pair=")) {
+      pairTokens.push(a);
+      continue;
+    }
+    break;
+  }
+  const command = args[i];
+  const tail = args.slice(i + 1);
+  if (command !== undefined && PAIR_AWARE_COMMANDS.has(command)) {
+    return { command, restArgs: [...pairTokens, ...tail] };
+  }
+  return { command, restArgs: tail };
+}
+async function main(command, restArgs) {
+  if (command && NOTIFY_COMMANDS.has(command)) {
+    try {
+      const { maybeNotifyUpdate: maybeNotifyUpdate2 } = await Promise.resolve().then(() => (init_update_notifier(), exports_update_notifier));
+      maybeNotifyUpdate2({ refresh: REFRESH_COMMANDS.has(command) });
+    } catch {}
+  }
   switch (command) {
     case "init":
       const { runInit: runInit2 } = await Promise.resolve().then(() => (init_init(), exports_init));
@@ -1334,7 +4833,7 @@ async function main() {
       break;
     case "dev":
       const { runDev: runDev2 } = await Promise.resolve().then(() => (init_dev(), exports_dev));
-      await runDev2();
+      await runDev2(restArgs);
       break;
     case "claude":
       const { runClaude: runClaude2 } = await Promise.resolve().then(() => (init_claude(), exports_claude));
@@ -1346,7 +4845,19 @@ async function main() {
       break;
     case "kill":
       const { runKill: runKill2 } = await Promise.resolve().then(() => (init_kill(), exports_kill));
-      await runKill2();
+      await runKill2(restArgs);
+      break;
+    case "pairs":
+      const { runPairs: runPairs2 } = await Promise.resolve().then(() => (init_pairs(), exports_pairs));
+      await runPairs2(restArgs);
+      break;
+    case "doctor":
+      const { runDoctor: runDoctor2 } = await Promise.resolve().then(() => (init_doctor(), exports_doctor));
+      await runDoctor2(restArgs);
+      break;
+    case "budget":
+      const { runBudget: runBudget2 } = await Promise.resolve().then(() => (init_budget(), exports_budget));
+      await runBudget2(restArgs);
       break;
     case "--help":
     case "-h":
@@ -1368,27 +4879,54 @@ function printHelp() {
 AgentBridge \u2014 Multi-agent collaboration bridge
 
 Usage:
-  agentbridge <command> [args...]
-  abg <command> [args...]
+  agentbridge [--pair <name>] <command> [args...]
+  abg [--pair <name>] <command> [args...]
 
 Commands:
-  init              Install plugin, check dependencies, generate project config
-  dev               Register local marketplace + install plugin (for local dev)
-  claude [args...]  Start Claude Code with push channel enabled
-  codex [args...]   Start Codex TUI connected to AgentBridge daemon
-  kill              Force kill all AgentBridge processes
+  init               Install plugin, check dependencies, generate project config
+  dev                Register local marketplace + install plugin (for local dev)
+  claude [args...]   Start Claude Code with push channel enabled
+  codex [args...]    Start Codex TUI connected to AgentBridge daemon
+                     (bare command auto-resumes the last thread; --new starts fresh)
+  pairs [rm <name|id> | prune [--dry-run]]
+                     List pairs; remove one (rm), or delete orphan state dirs (prune)
+  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)
+  kill [all | --all | --pair <name|id>]
+                     Stop this directory's pairs (default), every pair (all/--all), or one (--pair)
 
 Options:
-  --help, -h        Show this help message
-  --version, -v     Show version
+  --pair <name>      Run claude/codex/kill in a named pair. The name is scoped to
+                     the current directory, so the same name in another directory
+                     is a separate pair. Goes BEFORE the command. Without it, the
+                     pair name defaults to "main" for the current directory.
+  --help, -h         Show this help message
+  --version, -v      Show version
+
+Multi-pair:
+  Each pair is an isolated daemon with its own port triple. The first pair uses
+  the classic ports 4500/4501/4502; each additional pair steps +10. If "main" in
+  this directory already has a live Claude session, "abg claude" errors instead of
+  contesting it \u2014 pick another --pair name (or kill the live one first).
 
 Examples:
   abg init                     # First-time setup
-  abg claude                   # Start Claude Code
-  abg claude --resume          # Start Claude Code and resume session
-  abg codex                    # Start Codex TUI
-  abg codex --model o3         # Start Codex with specific model
-  abg kill                     # Emergency: kill all processes
+  abg claude                   # Start the "main" pair for this directory
+  abg codex                    # Connect Codex to this directory's "main" pair
+  abg --pair work claude       # Start a named pair "work" (this directory)
+  abg --pair work codex        # Connect Codex to the "work" pair
+  abg --pair review claude     # A second, parallel pair
+  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 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)
+  abg pairs prune              # ...delete those orphan state directories
+  abg --pair work kill         # Stop only this directory's "work" pair
+  abg kill                     # Stop this directory's pairs (+ any legacy-root daemon)
+  abg kill all                 # Stop every pair in every directory (+ legacy-root)
 `.trim());
 }
 function printVersion() {
@@ -1399,19 +4937,23 @@ function printVersion() {
     console.log("agentbridge (version unknown)");
   }
 }
-var args, command, restArgs, MARKETPLACE_NAME = "agentbridge", PLUGIN_NAME = "agentbridge";
+var MARKETPLACE_NAME = "agentbridge", PLUGIN_NAME = "agentbridge", REFRESH_COMMANDS, NOTIFY_COMMANDS, PAIR_AWARE_COMMANDS;
 var init_cli = __esm(() => {
-  args = process.argv.slice(2);
-  command = args[0];
-  restArgs = args.slice(1);
-  main().catch((err) => {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  });
+  REFRESH_COMMANDS = new Set(["claude", "codex"]);
+  NOTIFY_COMMANDS = new Set(["claude", "codex", "init", "dev"]);
+  PAIR_AWARE_COMMANDS = new Set(["claude", "codex", "kill", "doctor", "budget"]);
+  if (import.meta.main) {
+    const { command, restArgs } = parseTopLevel(process.argv.slice(2));
+    main(command, restArgs).catch((err) => {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    });
+  }
 });
 init_cli();
 
 export {
+  parseTopLevel,
   PLUGIN_NAME,
   MARKETPLACE_NAME
 };