codeam-cli 2.53.3 → 2.54.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `codeam-cli` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.53.4] — 2026-07-06
+
+### Fixed
+
+- **jetbrains:** Eliminate all 8 internal-API usages flagged by Plugin Verifier
+- **shared:** Phase 1 anti-drift — sync wire contracts, USER_EVENTS constants, zod RemoteCommand guard, JB respondWith + drift tests
+
+### Tests
+
+- **cli:** Backend contract fixtures for beads_action + migrate off deprecated BeadsActionPayload alias
+
+## [2.53.3] — 2026-07-06
+
+### Fixed
+
+- Phase 0 hygiene — 8 verified bugs across cli/shared/vsc/jetbrains
+
 ## [2.53.2] — 2026-07-06
 
 ### Fixed

package/dist/index.js

@@ -276,8 +276,16 @@ var AGENT_REGISTRY = {
     displayName: "Claude Code",
     binaryName: "claude",
     enabled: true,
-    supportedAuthKinds: ["oauth_token", "api_key"],
-    preferredAuthKind: "oauth_token"
+    // Mirrors the backend registry (codeagent-mobile
+    // apps/api-v2/src/codespaces/agent.ts — authoritative for auth
+    // capabilities). `setup_token` is the bare `sk-ant-oat01-…` from
+    // `claude setup-token` → delivered via CLAUDE_CODE_OAUTH_TOKEN.
+    supportedAuthKinds: ["setup_token", "oauth_token", "api_key"],
+    preferredAuthKind: "setup_token",
+    headroomWrappable: true,
+    headroomKind: "claude",
+    // npm adapter `@agentclientprotocol/claude-agent-acp`.
+    acp: true
   },
   codex: {
     id: "codex",
@@ -285,7 +293,15 @@ var AGENT_REGISTRY = {
     binaryName: "codex",
     enabled: true,
     supportedAuthKinds: ["oauth_token", "api_key"],
-    preferredAuthKind: "oauth_token"
+    preferredAuthKind: "oauth_token",
+    headroomWrappable: true,
+    headroomKind: "codex",
+    // npm adapter `@agentclientprotocol/codex-acp`.
+    acp: true,
+    // OAuth device-code flow; the user_code on the OpenAI page IS a real
+    // human-typed code — surfaces render it (with a copy affordance).
+    deviceFlow: true,
+    showsUserCode: true
   },
   copilot: {
     id: "copilot",
@@ -293,23 +309,47 @@ var AGENT_REGISTRY = {
     binaryName: "gh",
     enabled: false,
     supportedAuthKinds: ["oauth_token"],
-    preferredAuthKind: "oauth_token"
+    preferredAuthKind: "oauth_token",
+    // `headroom init --global copilot` exists even though the agent is
+    // still disabled here (no runtime builder yet).
+    headroomWrappable: true,
+    headroomKind: "copilot",
+    acp: false
   },
   coderabbit: {
     id: "coderabbit",
     displayName: "CodeRabbit",
     binaryName: "coderabbit",
     enabled: true,
-    supportedAuthKinds: ["oauth_token", "api_key"],
-    preferredAuthKind: "oauth_token"
+    // Backend registry is authoritative: CodeRabbit links via a real
+    // API key only (no OAuth flow exists in api-v2).
+    supportedAuthKinds: ["api_key"],
+    preferredAuthKind: "api_key",
+    headroomWrappable: false,
+    // Legacy PTY runtime — no ACP adapter registered.
+    acp: false
   },
   cursor: {
     id: "cursor",
     displayName: "Cursor Agent",
     binaryName: "cursor-agent",
     enabled: true,
-    supportedAuthKinds: ["oauth_token", "api_key"],
-    preferredAuthKind: "oauth_token"
+    // Backend registry is authoritative: since the Cursor OAuth
+    // device-flow shipped, new links are oauth_token only (the login
+    // blob written to ~/.config/cursor/auth.json). Legacy vaulted
+    // api_key rows may still exist server-side, but the link surface
+    // no longer offers api_key.
+    supportedAuthKinds: ["oauth_token"],
+    preferredAuthKind: "oauth_token",
+    // `headroom wrap cursor` is "manual/print-only" (IDE settings; the
+    // headless cursor-agent CLI has no base-URL override) — runs native.
+    headroomWrappable: false,
+    // Native ACP server: `cursor-agent acp`.
+    acp: true,
+    // Reverse-engineered device/poll flow; `userCode` is the secret PKCE
+    // verifier echoed back on poll — NEVER human-facing.
+    deviceFlow: true,
+    showsUserCode: false
   },
   aider: {
     id: "aider",
@@ -320,7 +360,10 @@ var AGENT_REGISTRY = {
     // / etc. env vars or `~/.aider.conf.yml`. The link flow surfaces
     // this via the existing --api-key escape hatch in commands/link.ts.
     supportedAuthKinds: ["api_key"],
-    preferredAuthKind: "api_key"
+    preferredAuthKind: "api_key",
+    headroomWrappable: false,
+    // Legacy PTY runtime — no ACP adapter registered.
+    acp: false
   },
   gemini: {
     id: "gemini",
@@ -332,7 +375,11 @@ var AGENT_REGISTRY = {
     // accepted by the backend's GeminiProvisioningStrategy and propagated
     // into codespace deploys.
     supportedAuthKinds: ["oauth_token", "api_key"],
-    preferredAuthKind: "oauth_token"
+    preferredAuthKind: "oauth_token",
+    // Not listed by `headroom wrap --help` — runs native.
+    headroomWrappable: false,
+    // Native ACP server: `gemini --skip-trust --acp`.
+    acp: true
   }
 };
 function getEnabledAgents() {
@@ -344,7 +391,57 @@ function getAgent(id) {
   return meta;
 }
 function isKnownAgentId(id) {
-  return id === "claude" || id === "codex" || id === "copilot" || id === "coderabbit" || id === "cursor" || id === "aider" || id === "gemini";
+  return id in AGENT_REGISTRY;
+}
+
+// ../../packages/shared/src/agents/identity.ts
+var HOUSE_AGENT_ID = "house-codeagent-cloud";
+var PUBLIC_TO_INTERNAL = {
+  claude_code: "claude",
+  // CLI-side extra: self-hosted deploy payloads may carry the internal id.
+  claude: "claude",
+  codex: "codex",
+  // CLI-side extra: copilot has no public LinkedAgentId (backend doesn't
+  // expose it) but the self-hosted path accepts it.
+  copilot: "copilot",
+  cursor: "cursor",
+  aider: "aider",
+  coderabbit: "coderabbit",
+  gemini: "gemini",
+  // The house agent runs Claude Code under the hood (pointed at the
+  // MiniMax proxy). Its internal runtime is therefore `claude`.
+  [HOUSE_AGENT_ID]: "claude"
+};
+var TERMINAL_AGENT_PREFIX = "__terminal__:";
+var AGENT_ID_ALIASES = {
+  claude_code: "claude",
+  "claude-code": "claude",
+  "anthropic.claude-code": "claude",
+  "anthropics.claude": "claude",
+  "anthropic.claude-ce": "claude",
+  "anthropic.claude": "claude",
+  "com.anthropic.claudecode": "claude",
+  "com.anthropic.claude": "claude",
+  "openai.chatgpt": "codex",
+  "coderabbitai.coderabbit-vscode": "coderabbit"
+};
+function normalizeAgentId(raw) {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (!value) return null;
+  if (isKnownAgentId(value)) return value;
+  const unprefixed = value.startsWith(TERMINAL_AGENT_PREFIX) ? value.slice(TERMINAL_AGENT_PREFIX.length) : value;
+  if (isKnownAgentId(unprefixed)) return unprefixed;
+  return AGENT_ID_ALIASES[unprefixed] ?? null;
+}
+function headroomKindFor(agentId) {
+  const normalized = (agentId ?? "").toLowerCase().replace(/[_-]/g, "");
+  if (!normalized) return null;
+  for (const meta of Object.values(AGENT_REGISTRY)) {
+    if (meta.headroomKind !== void 0 && normalized.startsWith(meta.id)) {
+      return meta.headroomKind;
+    }
+  }
+  return null;
 }
 
 // ../../packages/shared/src/api-url.ts
@@ -359,6 +456,112 @@ function resolveApiBaseUrl() {
   return DEFAULT_API_BASE_URL;
 }
 
+// ../../packages/shared/src/headroom/manifest.ts
+var HEADROOM_PIP_COMPANIONS = [
+  "fastapi",
+  "uvicorn",
+  "httpx[http2]",
+  "websockets",
+  "zstandard"
+];
+var HEADROOM_EXTRAS_BY_SURFACE = {
+  codespace: ["proxy", "code"],
+  selfHosted: ["proxy", "code"],
+  onDemand: ["proxy", "code", "image"]
+};
+function headroomPipPackage(extras) {
+  return `headroom-ai[${extras.join(",")}]`;
+}
+var HEADROOM_MODELS = [
+  {
+    repo: "chopratejas/kompress-v2-base",
+    allowPatterns: ["*.json", "onnx/*.onnx", "kompress-int8-wo.onnx"]
+  },
+  {
+    repo: "answerdotai/ModernBERT-base",
+    allowPatterns: ["*.json", "tokenizer*", "*.txt", "vocab*", "merges*"]
+  }
+];
+function headroomSnapshotDownloadLine(model, opts = {}) {
+  const sep7 = opts.spaceAfterComma ? ", " : ",";
+  const patterns = model.allowPatterns.map((p2) => `"${p2}"`).join(sep7);
+  return `snapshot_download("${model.repo}", allow_patterns=[${patterns}])`;
+}
+function headroomModelPredownloadScript(opts = {}) {
+  return [
+    "from huggingface_hub import snapshot_download",
+    ...HEADROOM_MODELS.map((m) => headroomSnapshotDownloadLine(m, opts))
+  ].join("\n");
+}
+
+// ../../packages/shared/src/types/events.ts
+var USER_EVENTS = {
+  PAIRED_SESSION_STATUS: "paired_session_status",
+  PAIRED_SESSION_ADDED: "paired_session_added",
+  PAIRED_SESSION_REMOVED: "paired_session_removed",
+  PAIRED_SESSION_BRANCH_CHANGED: "paired_session_branch_changed",
+  SHARED_WITH_ME_ADDED: "shared_with_me_added",
+  SHARED_WITH_ME_REVOKED: "shared_with_me_revoked",
+  USAGE_CHANGED: "usage_changed",
+  TASK_DONE: "task_done",
+  HUNK_PENDING_REVIEW_ADDED: "hunk_pending_review_added",
+  HUNK_REVIEW_RESOLVED: "hunk_review_resolved",
+  FILE_CHANGED: "file_changed",
+  FILES_BATCH_CHANGED: "files_batch_changed",
+  AGENT_STREAMING_CHUNK: "agent_streaming_chunk",
+  AGENT_AWAITING_ANSWER: "agent_awaiting_answer",
+  AWAITING_INPUT_ADDED: "awaiting_input_added",
+  AGENT_ANSWER_RESOLVED: "agent_answer_resolved",
+  TEMPLATE_ADDED: "template_added",
+  TEMPLATE_REMOVED: "template_removed",
+  TEMPLATE_UPDATED: "template_updated",
+  AGENT_TASK_DISPATCHED: "agent_task_dispatched",
+  AGENT_TASK_COMPLETED: "agent_task_completed",
+  LINKED_AGENT_ADDED: "linked_agent_added",
+  QUOTA_REACHED: "quota_reached",
+  LINKED_AGENT_LINK_FAILED: "linked_agent_link_failed",
+  CODESPACE_AGENT_INSTALLED: "codespace_agent_installed",
+  AGENT_CREDENTIALS_REFRESHED: "agent_credentials_refreshed",
+  CREDENTIAL_INVALID: "credential_invalid",
+  CODESPACE_WAKING: "codespace_waking",
+  CODESPACE_BILLING_BLOCKED: "codespace_billing_blocked",
+  COST_SAVING_UPDATED: "cost_saving_updated",
+  COMMAND_COMPLETED: "command_completed",
+  AI_SUMMARY_PENDING: "ai_summary_pending",
+  AI_SUMMARY_READY: "ai_summary_ready",
+  AI_INSIGHT_PENDING: "ai_insight_pending",
+  AI_INSIGHT_READY: "ai_insight_ready",
+  PUSH_TOKEN_INVALIDATED: "push_token_invalidated",
+  PREVIEW_DETECTION_PENDING: "preview_detection_pending",
+  PREVIEW_DETECTION_READY: "preview_detection_ready",
+  PREVIEW_STARTING: "preview_starting",
+  PREVIEW_READY: "preview_ready",
+  PREVIEW_STOPPED: "preview_stopped",
+  PREVIEW_ERROR: "preview_error",
+  PREVIEW_PROGRESS: "preview_progress",
+  BEADS_STATE_CHANGED: "beads_state_changed",
+  BEADS_PROVISIONING: "beads_provisioning",
+  BEADS_TEAM_MEMORY_CHANGED: "beads_team_memory_changed",
+  AUDIT_EVENT_ADDED: "audit_event_added",
+  SELF_HOSTED_HOST_ADDED: "self_hosted_host_added",
+  SELF_HOSTED_HOST_STATUS: "self_hosted_host_status",
+  SELF_HOSTED_HOST_REMOVED: "self_hosted_host_removed",
+  SELF_HOSTED_HOST_TELEMETRY: "self_hosted_host_telemetry",
+  SELF_HOSTED_HOST_METRICS: "self_hosted_host_metrics",
+  SELF_HOSTED_HOST_SESSIONS: "self_hosted_host_sessions",
+  SELF_HOSTED_DEPLOY_PROGRESS: "self_hosted_deploy_progress",
+  REFERRAL_REWARD_EARNED: "referral_reward_earned",
+  HEADROOM_PROGRESS: "headroom_progress",
+  HEADROOM_STATUS: "headroom_status",
+  BEADS_STATUS: "beads_status",
+  LINKED_AGENT_HEADROOM_BUDGET_UPDATED: "linked_agent_headroom_budget_updated",
+  CLI_UPDATE_AVAILABLE: "cli_update_available",
+  AGENT_INSTALL_PROGRESS: "agent_install_progress",
+  AGENT_INSTALL_FAILED: "agent_install_failed",
+  CLI_UPDATE_PROGRESS: "cli_update_progress",
+  CLI_UPDATE_FAILED: "cli_update_failed"
+};
+
 // ../../packages/shared/src/preview-prompts.ts
 var PREVIEW_DETECT_PROMPT = `
 Analyze the project in the current working directory and return how to start
@@ -5418,7 +5621,7 @@ function readAnonId() {
 }
 function superProperties() {
   return {
-    cliVersion: true ? "2.53.3" : "0.0.0-dev",
+    cliVersion: true ? "2.54.0" : "0.0.0-dev",
     nodeVersion: process.version,
     platform: process.platform,
     arch: process.arch,
@@ -5599,7 +5802,7 @@ var os4 = __toESM(require("os"));
 // package.json
 var package_default = {
   name: "codeam-cli",
-  version: "2.53.3",
+  version: "2.54.0",
   description: "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device \u2014 async. The terminal companion for CodeAgent Mobile.",
   type: "commonjs",
   main: "dist/index.js",
@@ -5687,7 +5890,7 @@ var package_default = {
     "@beads/bd": "1.0.5"
   },
   devDependencies: {
-    "@codeagent/shared": "*",
+    "@codeam/shared": "*",
     "@types/node": "^22.0.0",
     "@types/qrcode-terminal": "^0.12.0",
     "@types/which": "^3.0.4",
@@ -5952,6 +6155,8 @@ async function postBeadsProvisioning(input) {
   try {
     await _transport.postJsonAuthed(
       `${API_BASE}/api/beads/provisioning`,
+      // The CLI is the producer of this hop — the body is the shared wire
+      // shape (`@codeam/shared` `BeadsProvisioningPayload`), validated here.
       {
         sessionId: input.sessionId,
         pluginId: input.pluginId,
@@ -6633,7 +6838,7 @@ var CommandRelayService = class {
       // fresh + clear the "CLI update available" banner after a self-update
       // (a codespace that reinstalls @latest reconnects via heartbeat, not
       // pair/reconnect). Older backends ignore the extra field.
-      ..."2.53.3" ? { ideVersion: "2.53.3" } : {}
+      ..."2.54.0" ? { ideVersion: "2.54.0" } : {}
     }).then(() => log.trace("relay", `heartbeat ok online=${online}`)).catch((err) => log.trace("relay", `heartbeat failed online=${online}`, err));
   }
   /**
@@ -8115,7 +8320,7 @@ var startCommandSchema = import_zod.z.object({
   }).optional(),
   // `preview_start` carries the agent-detected `PreviewDetection`
   // shape from the mobile / web confirmation sheet. Mirrors
-  // `@codeagent/shared`'s `PreviewDetection` byte-for-byte. Kept
+  // `@codeam/shared`'s `PreviewDetection` byte-for-byte. Kept
   // loose (`unknown` for env / setup_commands) so a CLI version
   // running against a newer backend that adds optional fields still
   // accepts the payload; the handler validates the shape it needs
@@ -15133,7 +15338,7 @@ async function autoUpgradeBeforeCriticalCommand() {
   if (process.env.NODE_ENV === "test") return;
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
-  const current = true ? "2.53.3" : null;
+  const current = true ? "2.54.0" : null;
   if (!current) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -15150,7 +15355,7 @@ function checkForUpdates() {
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
   if (!process.stdout.isTTY) return;
-  const current = true ? "2.53.3" : null;
+  const current = true ? "2.54.0" : null;
   if (!current) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -15313,7 +15518,10 @@ var CONTROL_AGENT_META = {
   binaryName: "codeam",
   enabled: true,
   supportedAuthKinds: ["oauth_token"],
-  preferredAuthKind: "oauth_token"
+  preferredAuthKind: "oauth_token",
+  // Synthetic control channel — capability flags are moot (no agent runs).
+  headroomWrappable: false,
+  acp: false
 };
 var PEP668_MARKER = "externally-managed-environment";
 var PM_INSTALL_TIMEOUT_MS = 18e4;
@@ -15484,15 +15692,10 @@ async function ensurePip(runner) {
   return true;
 }
 function agentIdToHeadroomKind(agentId) {
-  const normalized = (agentId ?? "").toLowerCase().replace(/[_-]/g, "");
-  if (normalized.startsWith("claude")) return "claude";
-  if (normalized.startsWith("codex")) return "codex";
-  if (normalized.startsWith("copilot")) return "copilot";
-  return "claude";
+  return headroomKindFor(agentId) ?? "claude";
 }
 function isHeadroomSupportedAgent(agentId) {
-  const n = (agentId ?? "").toLowerCase().replace(/[_-]/g, "");
-  return n.startsWith("claude") || n.startsWith("codex") || n.startsWith("copilot");
+  return headroomKindFor(agentId) !== null;
 }
 function headroomConfigPath() {
   return path38.join(os31.homedir(), ".codeam", "headroom-config.json");
@@ -15745,10 +15948,10 @@ async function ensureModernPython(runner) {
   return py;
 }
 async function setupHeadroomForSelfHosted(agent, runner = defaultHeadroomRunner, opts = {}) {
-  const extras = opts.extras ?? ["proxy", "code"];
+  const extras = opts.extras ?? [...HEADROOM_EXTRAS_BY_SURFACE.selfHosted];
   const onProgress = opts.onProgress ?? (() => {
   });
-  const SERVER_DEPS = ["fastapi", "uvicorn", "httpx[http2]", "websockets", "zstandard"];
+  const SERVER_DEPS = HEADROOM_PIP_COMPANIONS;
   const pipAvailable = await ensurePip(runner);
   if (!pipAvailable) {
     return false;
@@ -15773,7 +15976,7 @@ async function setupHeadroomForSelfHosted(agent, runner = defaultHeadroomRunner,
     return false;
   };
   onProgress("pip");
-  const headroomPkg = `headroom-ai[${extras.join(",")}]`;
+  const headroomPkg = headroomPipPackage(extras);
   const installOk = await pipInstall([headroomPkg, ...SERVER_DEPS], [], ENGINE_INSTALL_TIMEOUT_MS);
   if (!installOk) {
     log.warn("host-agent", `headroom engine install failed (${headroomPkg}) \u2014 skipping Headroom`);
@@ -15781,11 +15984,7 @@ async function setupHeadroomForSelfHosted(agent, runner = defaultHeadroomRunner,
   }
   log.info("host-agent", `headroom + ONNX engines installed (${headroomPkg})`);
   onProgress("model");
-  const predownloadPy = [
-    "from huggingface_hub import snapshot_download",
-    'snapshot_download("chopratejas/kompress-v2-base", allow_patterns=["*.json","onnx/*.onnx","kompress-int8-wo.onnx"])',
-    'snapshot_download("answerdotai/ModernBERT-base", allow_patterns=["*.json","tokenizer*","*.txt","vocab*","merges*"])'
-  ].join("\n");
+  const predownloadPy = headroomModelPredownloadScript();
   const dl = await runner.run(py, ["-c", predownloadPy], {
     timeoutMs: ENGINE_INSTALL_TIMEOUT_MS
   });
@@ -15861,7 +16060,7 @@ var defaultSpawner = (env, cwd, args2 = []) => (0, import_node_child_process16.s
   detached: false
 });
 function currentCliVersion() {
-  return true ? "2.53.3" : null;
+  return true ? "2.54.0" : null;
 }
 function runCmd(cmd, args2, timeoutMs) {
   return new Promise((resolve7) => {
@@ -16573,11 +16772,13 @@ async function configureHeadroom(action, ctx, deps) {
   if (action === "enable") {
     if (!isHeadroomSupportedAgent(ctx.agent)) return { supported: false };
     const ok = await deps.setup(ctx.agent, void 0, {
-      extras: ["proxy", "code", "image"],
-      onProgress: (step) => deps.emit({ type: "headroom_progress", step })
+      // On-demand surface ships the extra `image` compression support — see
+      // the shared Headroom manifest (`HEADROOM_EXTRAS_BY_SURFACE`).
+      extras: [...HEADROOM_EXTRAS_BY_SURFACE.onDemand],
+      onProgress: (step) => deps.emit({ type: USER_EVENTS.HEADROOM_PROGRESS, step })
     });
     if (!ok) {
-      deps.emit({ type: "headroom_status", state: "error" });
+      deps.emit({ type: USER_EVENTS.HEADROOM_STATUS, state: "error" });
       return { enabled: false };
     }
     deps.persist({ enabled: true, agent: kind, ingestUrl: ctx.savingsIngestUrl });
@@ -16588,14 +16789,14 @@ async function configureHeadroom(action, ctx, deps) {
         pluginAuthToken: ctx.pluginAuthToken
       });
     }
-    deps.emit({ type: "headroom_status", state: "enabled" });
+    deps.emit({ type: USER_EVENTS.HEADROOM_STATUS, state: "enabled" });
     return { enabled: true };
   }
   deps.restoreAgentHeadroomConfig(kind);
   deps.stopProxy();
   deps.persist({ enabled: false });
   deps.stopReporter();
-  deps.emit({ type: "headroom_status", state: "disabled" });
+  deps.emit({ type: USER_EVENTS.HEADROOM_STATUS, state: "disabled" });
   return { enabled: false };
 }
 
@@ -17575,9 +17776,12 @@ function coerceIssue(row, projectKey) {
     owner: typeof r.owner === "string" && r.owner.length > 0 ? r.owner : null,
     created_at: typeof r.created_at === "string" ? r.created_at : "",
     updated_at: typeof r.updated_at === "string" ? r.updated_at : "",
-    dependency_count: typeof r.dependency_count === "number" ? r.dependency_count : void 0,
-    dependent_count: typeof r.dependent_count === "number" ? r.dependent_count : void 0,
-    comment_count: typeof r.comment_count === "number" ? r.comment_count : void 0,
+    // The backend ingest DTO validates the counts as REQUIRED ints — an
+    // omitted count would 400 the whole snapshot. Default to 0 when a bd
+    // version omits one instead of dropping the field.
+    dependency_count: typeof r.dependency_count === "number" ? r.dependency_count : 0,
+    dependent_count: typeof r.dependent_count === "number" ? r.dependent_count : 0,
+    comment_count: typeof r.comment_count === "number" ? r.comment_count : 0,
     projectKey
   };
 }
@@ -18414,9 +18618,10 @@ var BeadsWatcher = class {
       projectLabel,
       fullSnapshot: true,
       issues,
-      // The backend DTO requires `dependencies` (not `deps`). We don't track
-      // edges in the P0 snapshot yet, so always send an empty array rather than
-      // omitting the field (an omitted/conditional field 400s the ingest).
+      // We don't track edges in the P0 snapshot yet, so send an empty array.
+      // (The backend DTO marks `dependencies` optional and tolerates absence,
+      // but the wire contract in @codeam/shared says "always sent" — keep
+      // the payload deterministic.)
       dependencies: [],
       memories: [],
       // Always send a summary — a null `bd status` yields a zeroed block rather
@@ -19022,7 +19227,7 @@ var headroomConfigureH = async (ctx, cmd, parsed) => {
   }
   const savingsIngestUrl = parsed.savingsIngestUrl;
   let rawAgentId = ctx.agentId || (typeof parsed.agentId === "string" ? parsed.agentId : "");
-  if (rawAgentId === "claude_code") rawAgentId = "claude";
+  rawAgentId = normalizeAgentId(rawAgentId) ?? rawAgentId;
   let configuredAgent = rawAgentId;
   if (!configuredAgent) {
     try {
@@ -19136,9 +19341,9 @@ var headroomConfigureH = async (ctx, cmd, parsed) => {
 var headroomBudgetH = async (ctx, cmd) => {
   const payload = cmd.payload;
   let rawAgentId = ctx.agentId || (typeof payload.agentId === "string" ? payload.agentId : "");
-  if (rawAgentId === "claude_code") rawAgentId = "claude";
+  rawAgentId = normalizeAgentId(rawAgentId) ?? rawAgentId;
   let payloadAgentId = typeof payload.agentId === "string" ? payload.agentId : "";
-  if (payloadAgentId === "claude_code") payloadAgentId = "claude";
+  payloadAgentId = normalizeAgentId(payloadAgentId) ?? payloadAgentId;
   if (!rawAgentId || !isHeadroomSupportedAgent(rawAgentId)) {
     await ctx.relay.sendResult(cmd.id, "completed", { applied: false });
     return;
@@ -19198,7 +19403,7 @@ var beadsConfigureH = async (ctx, cmd, parsed) => {
     return;
   }
   let rawAgentId = ctx.agentId || (typeof parsed.agentId === "string" ? parsed.agentId : "");
-  if (rawAgentId === "claude_code") rawAgentId = "claude";
+  rawAgentId = normalizeAgentId(rawAgentId) ?? rawAgentId;
   const agentIds = rawAgentId && isKnownAgentId(rawAgentId) ? [rawAgentId] : [];
   const deps = {
     provision: async () => {
@@ -19238,7 +19443,7 @@ var beadsConfigureH = async (ctx, cmd, parsed) => {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken: token,
-          type: "beads_status",
+          type: USER_EVENTS.BEADS_STATUS,
           payload: Object.fromEntries(
             Object.entries(event).filter(([k2]) => k2 !== "type")
           )
@@ -19293,12 +19498,14 @@ function buildNpmInstallInvocation(opts) {
 async function runNpmInstallLatest() {
   let lastError = "";
   const invocation = buildNpmInstallInvocation();
+  const useShell = process.platform === "win32";
+  const command2 = useShell && invocation.command.includes(" ") ? `"${invocation.command}"` : invocation.command;
   for (let attempt = 1; attempt <= CLI_UPDATE_MAX_ATTEMPTS; attempt++) {
     const result = await new Promise((resolve7) => {
       (0, import_child_process22.execFile)(
-        invocation.command,
+        command2,
         invocation.args,
-        { timeout: CLI_UPDATE_INSTALL_TIMEOUT_MS },
+        { timeout: CLI_UPDATE_INSTALL_TIMEOUT_MS, shell: useShell },
         (err, _stdout, stderr) => {
           if (!err) {
             resolve7({ ok: true });
@@ -19465,9 +19672,9 @@ var requestLinkCredentialsH = (ctx, _cmd, parsed) => {
     log.trace("auto-link", "skipped \u2014 no pluginAuthToken on this paired session");
     return;
   }
-  const internalId = publicId === "claude_code" ? "claude" : publicId;
-  if (!isKnownAgentId(internalId) || !AGENT_REGISTRY[internalId].enabled) {
-    log.trace("auto-link", `unknown / disabled agent: ${internalId}`);
+  const internalId = normalizeAgentId(publicId);
+  if (!internalId || !AGENT_REGISTRY[internalId].enabled) {
+    log.trace("auto-link", `unknown / disabled agent: ${publicId}`);
     return;
   }
   const pluginAuthToken = ctx.pluginAuthToken;
@@ -19629,7 +19836,7 @@ var requestPreviewDetectH = (ctx) => {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken: ctx.pluginAuthToken,
-      type: "preview_error",
+      type: USER_EVENTS.PREVIEW_ERROR,
       payload: {
         stage: "detection",
         message: `Preview detection isn't available on ${ctx.runtime.id} sessions yet \u2014 link a Claude or Codex agent.`
@@ -19646,7 +19853,7 @@ var requestPreviewDetectH = (ctx) => {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_detection_ready",
+        type: USER_EVENTS.PREVIEW_DETECTION_READY,
         payload: { detection: fromFile }
       });
       return;
@@ -19655,7 +19862,7 @@ var requestPreviewDetectH = (ctx) => {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_detection_pending"
+      type: USER_EVENTS.PREVIEW_DETECTION_PENDING
     });
     log.info("preview", "detect: invoking generateOneShot");
     const startedAt = Date.now();
@@ -19671,7 +19878,7 @@ var requestPreviewDetectH = (ctx) => {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_error",
+        type: USER_EVENTS.PREVIEW_ERROR,
         payload: {
           stage: "detection",
           message: "Agent returned invalid JSON. Try again, or add a .codeam/preview.json override."
@@ -19685,7 +19892,7 @@ var requestPreviewDetectH = (ctx) => {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_error",
+        type: USER_EVENTS.PREVIEW_ERROR,
         payload: {
           stage: "unsupported",
           message: detection.notes ?? "No dev server applies to this project."
@@ -19701,7 +19908,7 @@ var requestPreviewDetectH = (ctx) => {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_detection_ready",
+      type: USER_EVENTS.PREVIEW_DETECTION_READY,
       payload: { detection }
     });
   })();
@@ -19818,7 +20025,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_progress",
+      type: USER_EVENTS.PREVIEW_PROGRESS,
       payload: { step, message, timestamp: Date.now() }
     });
   };
@@ -19834,7 +20041,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_ready",
+        type: USER_EVENTS.PREVIEW_READY,
         payload: { url: existing.url, framework: existing.framework, port: detection.port }
       });
       return;
@@ -19843,7 +20050,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_starting",
+      type: USER_EVENTS.PREVIEW_STARTING,
       payload: { framework: detection.framework, port: detection.port }
     });
     emitProgress("ENV_DETECTED", `${detection.framework}`);
@@ -19870,7 +20077,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
             sessionId: ctx.sessionId,
             pluginId: ctx.pluginId,
             pluginAuthToken,
-            type: "preview_error",
+            type: USER_EVENTS.PREVIEW_ERROR,
             payload: {
               stage: "spawn",
               message: `This project uses yarn but yarn isn't installed, and installing it automatically failed (npm install -g yarn, exit ${ensured.code}). Install yarn in this environment and try the preview again.`
@@ -19895,7 +20102,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "ready_timeout",
             message: `Dependency install (${missingDeps.cmd} ${missingDeps.args.join(" ")}) didn't finish within ${Math.round(INSTALL_TIMEOUT_MS / 1e3)}s and was stopped. Run it manually in this project, then try the preview again.`
@@ -19908,7 +20115,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "spawn",
             message: `Dependency install failed (${missingDeps.cmd} ${missingDeps.args.join(" ")}, exit ${result.code}). Run it manually in this project and try again.`
@@ -19945,7 +20152,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "ready_timeout",
             message: `Setup step (${setup.cmd} ${setup.args.join(" ")}) didn't finish within ${Math.round(timeoutMs / 1e3)}s and was stopped.`
@@ -19958,7 +20165,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "spawn",
             message: `Setup failed (${setup.cmd} ${setup.args.join(" ")}, exit ${result.code}).`
@@ -19979,7 +20186,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_ready",
+          type: USER_EVENTS.PREVIEW_READY,
           payload: { url: raceExisting.url, framework: raceExisting.framework, port: detection.port }
         });
         return;
@@ -19999,7 +20206,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
             sessionId: ctx.sessionId,
             pluginId: ctx.pluginId,
             pluginAuthToken,
-            type: "preview_error",
+            type: USER_EVENTS.PREVIEW_ERROR,
             payload: {
               stage: "spawn",
               message: `Port ${detection.port} is still in use after stopping the previous preview. Wait a moment and try again.`
@@ -20012,7 +20219,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "spawn",
             message: `Port ${detection.port} is already in use by another process, so the dev server can't start there. Stop whatever is listening on port ${detection.port} and try the preview again.`
@@ -20060,7 +20267,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_error",
+        type: USER_EVENTS.PREVIEW_ERROR,
         payload: {
           stage: "spawn",
           message: `The dev server exited (code ${outcome.code}) before it was ready. It may need a database or other services.`,
@@ -20075,7 +20282,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
         sessionId: ctx.sessionId,
         pluginId: ctx.pluginId,
         pluginAuthToken,
-        type: "preview_error",
+        type: USER_EVENTS.PREVIEW_ERROR,
         payload: {
           stage: "ready_timeout",
           message: "The dev server didn't become ready in time. It may be stuck waiting on a database or other service.",
@@ -20104,7 +20311,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: { stage: "tunnel", message: "Expo did not report a tunnel URL." }
         });
         return;
@@ -20120,7 +20327,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: { stage: "tunnel", message: e.message }
         });
         return;
@@ -20214,7 +20421,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
           sessionId: ctx.sessionId,
           pluginId: ctx.pluginId,
           pluginAuthToken,
-          type: "preview_error",
+          type: USER_EVENTS.PREVIEW_ERROR,
           payload: {
             stage: "tunnel",
             message: `Tunnel did not become reachable after ${MAX_TUNNEL_ATTEMPTS} attempts (${lastTunnelErr}). Cloudflare Quick Tunnels occasionally fail to register \u2014 please retry.`
@@ -20238,7 +20445,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_ready",
+      type: USER_EVENTS.PREVIEW_READY,
       payload: { url, framework: detection.framework, port: detection.port }
     });
   })().catch((err) => {
@@ -20248,7 +20455,7 @@ function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_error",
+      type: USER_EVENTS.PREVIEW_ERROR,
       payload: { stage: "spawn", message: `Preview failed to start: ${message}` }
     });
   });
@@ -20266,7 +20473,7 @@ var previewStopH = (ctx) => {
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
-      type: "preview_stopped",
+      type: USER_EVENTS.PREVIEW_STOPPED,
       payload: { reason: "user" }
     });
   })();
@@ -21255,7 +21462,7 @@ function resolveClaudeNativeBinary(deps = {}) {
   const sdkDir = deps.sdkDir !== void 0 ? deps.sdkDir : defaultSdkDir();
   if (!sdkDir) return null;
   const scopeDir = import_path8.default.dirname(sdkDir);
-  const binName = process.platform === "win32" ? "claude.exe" : "claude";
+  const binName = platformKey.startsWith("win32-") ? "claude.exe" : "claude";
   const candidate = import_path8.default.join(scopeDir, `claude-agent-sdk-${platformKey}`, binName);
   return existsSync21(candidate) ? candidate : null;
 }
@@ -31719,7 +31926,7 @@ function checkChokidar() {
 }
 async function doctor(args2 = []) {
   const json = args2.includes("--json");
-  const cliVersion = true ? "2.53.3" : "0.0.0-dev";
+  const cliVersion = true ? "2.54.0" : "0.0.0-dev";
   const apiBase2 = resolveApiBaseUrl();
   const diagnosticId = (0, import_node_crypto8.randomUUID)();
   log.info("doctor", `run id=${diagnosticId} cli=${cliVersion}`);
@@ -31918,7 +32125,7 @@ async function completion(args2) {
 // src/commands/version.ts
 var import_picocolors15 = __toESM(require("picocolors"));
 function version2() {
-  const v = true ? "2.53.3" : "unknown";
+  const v = true ? "2.54.0" : "unknown";
   console.log(`${import_picocolors15.default.bold("codeam-cli")} ${import_picocolors15.default.cyan(v)}`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeam-cli",
-  "version": "2.53.3",
+  "version": "2.54.0",
   "description": "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device — async. The terminal companion for CodeAgent Mobile.",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -88,7 +88,7 @@
     "@beads/bd": "1.0.5"
   },
   "devDependencies": {
-    "@codeagent/shared": "*",
+    "@codeam/shared": "*",
     "@types/node": "^22.0.0",
     "@types/qrcode-terminal": "^0.12.0",
     "@types/which": "^3.0.4",