@mxalbert/context-mode 2.0.0

package/hooks/normalize-hooks.mjs

@@ -0,0 +1,323 @@
+// normalize-hooks.mjs — fixes #378
+//
+// Static committed files (hooks/hooks.json, .claude-plugin/plugin.json) ship
+// with `${CLAUDE_PLUGIN_ROOT}` placeholder + bare `node` command. On Windows
+// + Claude Code this triggers cjs/loader:1479 errors because:
+//   1. bare `node` may not resolve via PATH (Git Bash, see #369)
+//   2. `${CLAUDE_PLUGIN_ROOT}` resolution can hit MSYS path mangling (#372)
+//   3. backslash paths get corrupted in shell quoting
+//
+// Our buildNodeCommand() fix handles dynamically-generated settings.json but
+// not the static committed files. Solution: start.mjs detects the placeholder
+// pattern on every MCP boot and rewrites with absolute paths using
+// process.execPath + forward slashes. Idempotent — only rewrites when needed.
+// Survives upgrades because it runs at every start.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}";
+
+// #604: matches a cache path segment `context-mode/context-mode/<version>`.
+// Capture group is the X.Y.Z version. Used to detect command paths frozen on a
+// previous-version dir that Claude Code's native plugin manager has since
+// cleaned up. `/g` so a single content blob with multiple stale references is
+// fully covered. Forward-slash only — callers convert beforehand.
+const CACHE_VERSION_RE =
+  /context-mode\/context-mode\/([0-9]+\.[0-9]+\.[0-9]+)(?=\/)/g;
+
+/** Convert any path string to forward slashes (MSYS-safe). */
+function fwd(p) {
+  return String(p).replace(/\\/g, "/");
+}
+
+/**
+ * Extract the X.Y.Z version segment from a pluginRoot under the context-mode
+ * cache layout. Returns null when running from npm-global, a dev checkout, or
+ * any layout that does not match the `<…>/context-mode/context-mode/<v>(/…)?`
+ * pattern — callers must treat null as "no stale-path check is possible".
+ */
+function pluginRootVersion(pluginRoot) {
+  if (!pluginRoot) return null;
+  const m =
+    /context-mode\/context-mode\/([0-9]+\.[0-9]+\.[0-9]+)(?:\/|$)/.exec(
+      fwd(pluginRoot),
+    );
+  return m ? m[1] : null;
+}
+
+/**
+ * Does `content` reference any context-mode cache version segment that differs
+ * from `currentVersion`? Detects the #604 ratchet: already-normalized hooks.json
+ * / plugin.json carrying a previous version's absolute paths forward into a
+ * newer version's cache directory after Claude Code's auto-update.
+ */
+function hasStaleCacheVersionSegment(content, currentVersion) {
+  if (!currentVersion || !content || typeof content !== "string") return false;
+  const safe = fwd(content);
+  CACHE_VERSION_RE.lastIndex = 0;
+  let m;
+  while ((m = CACHE_VERSION_RE.exec(safe)) !== null) {
+    if (m[1] !== currentVersion) return true;
+  }
+  return false;
+}
+
+/**
+ * Pure detection: does this content need to be (re-)normalized?
+ *
+ * Two triggers:
+ *   1. Fresh content still containing the `${CLAUDE_PLUGIN_ROOT}` placeholder
+ *      — the original #378 first-boot path on any host.
+ *   2. (#604) Already-resolved content whose absolute paths point at a
+ *      different version of the context-mode cache than the current
+ *      `pluginRoot`. Breaks the ratchet that previously froze stale paths
+ *      after Claude Code's native plugin manager copied a previous version's
+ *      hooks.json forward.
+ *
+ * `pluginRoot` is optional for backwards compatibility with single-arg
+ * callers; without it, only the placeholder check runs.
+ */
+export function needsHookNormalization(content, pluginRoot) {
+  if (!content || typeof content !== "string") return false;
+  if (content.includes(PLACEHOLDER)) return true;
+  return hasStaleCacheVersionSegment(content, pluginRootVersion(pluginRoot));
+}
+
+/**
+ * Rewrite hooks.json content. Replaces:
+ *   - `node "${CLAUDE_PLUGIN_ROOT}/x.mjs"` →
+ *     `"<execPath>" "<pluginRoot>/x.mjs"`  (forward slashes, double-quoted)
+ *
+ * Pure function — takes content + paths, returns new content.
+ * Idempotent — leaves already-normalized content unchanged.
+ */
+export function normalizeHooksJson(content, nodePath, pluginRoot) {
+  if (!needsHookNormalization(content, pluginRoot)) return content;
+
+  const safeNode = fwd(nodePath);
+  const safeRoot = fwd(pluginRoot);
+  const currentVersion = pluginRootVersion(pluginRoot);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return content;
+  }
+
+  const hooks = parsed?.hooks;
+  if (!hooks || typeof hooks !== "object") return content;
+
+  let mutated = false;
+  for (const eventName of Object.keys(hooks)) {
+    const matchers = hooks[eventName];
+    if (!Array.isArray(matchers)) continue;
+    for (const matcher of matchers) {
+      const inner = matcher?.hooks;
+      if (!Array.isArray(inner)) continue;
+      for (const h of inner) {
+        if (typeof h?.command !== "string") continue;
+
+        const hasPlaceholder = h.command.includes(PLACEHOLDER);
+        // #604: also rewrite when the command holds a stale absolute path under
+        // a previous-version cache dir (Claude Code's auto-update ratchet).
+        const hasStale = hasStaleCacheVersionSegment(h.command, currentVersion);
+        if (!hasPlaceholder && !hasStale) continue;
+
+        let next = h.command;
+        if (hasPlaceholder) {
+          // Replace placeholder with absolute root (forward-slash).
+          next = next.replaceAll(PLACEHOLDER, safeRoot);
+          // Replace bare `node ` prefix with quoted execPath. Match both
+          // `node ` and `node\t` at start, with optional surrounding whitespace.
+          next = next.replace(/^\s*node\s+/, `"${safeNode}" `);
+        }
+        if (hasStale) {
+          // Re-point every `context-mode/context-mode/<old-version>/…` segment
+          // to the current pluginRoot's version. Operates on the forward-slash
+          // form so MSYS-mangled paths heal as well.
+          next = fwd(next).replace(
+            CACHE_VERSION_RE,
+            `context-mode/context-mode/${currentVersion}`,
+          );
+        }
+        h.command = next;
+        mutated = true;
+      }
+    }
+  }
+
+  if (!mutated) return content;
+
+  // Preserve 2-space indent (matches committed format).
+  return JSON.stringify(parsed, null, 2);
+}
+
+/**
+ * Rewrite plugin.json mcpServers. Replaces:
+ *   - `command: "node"` → `command: "<execPath-fwd>"`
+ *   - `args: ["${CLAUDE_PLUGIN_ROOT}/start.mjs"]` →
+ *     `args: ["<pluginRoot-fwd>/start.mjs"]`
+ *
+ * Idempotent.
+ */
+export function normalizePluginJson(content, nodePath, pluginRoot) {
+  if (!needsHookNormalization(content, pluginRoot)) return content;
+
+  const safeNode = fwd(nodePath);
+  const safeRoot = fwd(pluginRoot);
+  const currentVersion = pluginRootVersion(pluginRoot);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return content;
+  }
+
+  const servers = parsed?.mcpServers;
+  if (!servers || typeof servers !== "object") return content;
+
+  let mutated = false;
+  for (const name of Object.keys(servers)) {
+    const srv = servers[name];
+    if (!srv || typeof srv !== "object") continue;
+
+    if (Array.isArray(srv.args)) {
+      const before = srv.args;
+      const after = before.map((a) => {
+        if (typeof a !== "string") return a;
+        let next = a;
+        if (next.includes(PLACEHOLDER)) {
+          next = next.replaceAll(PLACEHOLDER, safeRoot);
+        }
+        // #604: same auto-update ratchet hits plugin.json args (see #523).
+        if (hasStaleCacheVersionSegment(next, currentVersion)) {
+          next = fwd(next).replace(
+            CACHE_VERSION_RE,
+            `context-mode/context-mode/${currentVersion}`,
+          );
+        }
+        return next;
+      });
+      if (after.some((v, i) => v !== before[i])) {
+        srv.args = after;
+        mutated = true;
+      }
+    }
+
+    if (srv.command === "node" && mutated) {
+      // Only swap bare `node` when we also rewrote args — otherwise we'd
+      // touch user-customized server entries unrelated to placeholders.
+      srv.command = safeNode;
+    }
+  }
+
+  if (!mutated) return content;
+  return JSON.stringify(parsed, null, 2);
+}
+
+/**
+ * Apply normalization to hooks/hooks.json ONLY (not plugin.json).
+ *
+ * Why a narrow variant exists (#711 + #414 / #528):
+ *   - plugin.json is read by Claude Code's plugin manager and carried forward
+ *     into NEW versioned cache dirs on auto-update. Baking absolute paths into
+ *     it during /ctx-upgrade poisons the next version (#711).
+ *   - hooks/hooks.json lives in the per-version dir and is read by the SAME
+ *     Node process that needs to spawn a child. On Windows + Git Bash, Claude
+ *     Code fires SessionStart/PreToolUse BEFORE MCP boot — the unresolved
+ *     `${CLAUDE_PLUGIN_ROOT}` placeholder yields MODULE_NOT_FOUND for the
+ *     first hook fire after /ctx-upgrade (#414).
+ *
+ * So /ctx-upgrade calls THIS narrow function (hooks.json only) to close the
+ * Windows first-hook-fire window without re-introducing #711.
+ *
+ * Options:
+ *   - pluginRoot:     absolute path to plugin install dir
+ *   - nodePath:       process.execPath (the Node binary running this script)
+ *   - jsRuntimePath:  optional — resolved Bun ≥1.0 path (#738). When set, the
+ *                     rewrite uses this instead of nodePath so hook invocations
+ *                     gain Bun's ~40-60ms cold-start advantage. Falls back to
+ *                     nodePath when omitted (back-compat).
+ *   - platform:       process.platform. Triggers a write on:
+ *                       • "win32" / "linux" — the original #378 path
+ *                         (#369/#372 MSYS / nvm fixes), AND
+ *                       • any platform when jsRuntimePath !== nodePath
+ *                         (#738 — bun swap is a perf optimisation that should
+ *                         not be gated by the historical Windows-only check;
+ *                         issue was filed from macOS).
+ *
+ * Best-effort — never throws.
+ */
+export function normalizeHooksJsonOnly({ pluginRoot, nodePath, jsRuntimePath, platform }) {
+  const effectiveRuntime = jsRuntimePath || nodePath;
+  // #378 path: always normalize on Windows/Linux to heal placeholder + bare-node.
+  // #738 path: also fire on macOS when we have a real bun swap to perform — the
+  // legacy gate skipped darwin because system node was reliable there, but bun
+  // resolution is the new perf-win that the gate now needs to allow through.
+  const isPlatformGated = platform !== "win32" && platform !== "linux";
+  const hasBunSwap = jsRuntimePath && jsRuntimePath !== nodePath;
+  if (isPlatformGated && !hasBunSwap) return;
+  if (!pluginRoot || !effectiveRuntime) return;
+
+  try {
+    const hooksPath = resolve(pluginRoot, "hooks", "hooks.json");
+    if (existsSync(hooksPath)) {
+      const original = readFileSync(hooksPath, "utf-8");
+      if (needsHookNormalization(original, pluginRoot)) {
+        const next = normalizeHooksJson(original, effectiveRuntime, pluginRoot);
+        if (next !== original) {
+          writeFileSync(hooksPath, next, "utf-8");
+        }
+      }
+    }
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Apply normalization to hooks.json and plugin.json on startup.
+ *
+ * Options:
+ *   - pluginRoot:     absolute path to plugin install dir (e.g. __dirname of start.mjs)
+ *   - nodePath:       process.execPath
+ *   - jsRuntimePath:  optional Bun ≥1.0 path (#738) — used for hooks.json only,
+ *                     never for plugin.json (the MCP server itself must stay on
+ *                     Node — better-sqlite3 ABI, #543)
+ *   - platform:       process.platform ("win32" and "linux" trigger plugin.json
+ *                     rewrite for #378; hooks.json also rewrites on darwin when
+ *                     `jsRuntimePath` !== `nodePath` for #738)
+ *
+ * Best-effort — never throws.
+ */
+export function normalizeHooksOnStartup({ pluginRoot, nodePath, jsRuntimePath, platform }) {
+  // Delegate the hooks.json branch to the narrow helper so /ctx-upgrade and
+  // boot share one implementation. plugin.json normalization stays here —
+  // start.mjs and postinstall still need it; /ctx-upgrade must NOT (#711).
+  normalizeHooksJsonOnly({ pluginRoot, nodePath, jsRuntimePath, platform });
+
+  // plugin.json rewrite: ALWAYS uses nodePath (MCP server must stay on Node,
+  // #543). Bun resolution is irrelevant here — `jsRuntimePath` is consumed
+  // exclusively by the hooks.json branch above.
+  if (platform !== "win32" && platform !== "linux") return;
+  if (!pluginRoot || !nodePath) return;
+
+  // .claude-plugin/plugin.json
+  try {
+    const pluginPath = resolve(pluginRoot, ".claude-plugin", "plugin.json");
+    if (existsSync(pluginPath)) {
+      const original = readFileSync(pluginPath, "utf-8");
+      if (needsHookNormalization(original, pluginRoot)) {
+        const next = normalizePluginJson(original, nodePath, pluginRoot);
+        if (next !== original) {
+          writeFileSync(pluginPath, next, "utf-8");
+        }
+      }
+    }
+  } catch {
+    /* best effort */
+  }
+}

package/hooks/platform-bridge.mjs

@@ -0,0 +1,340 @@
+// hooks/platform-bridge.mjs — Fire-and-forget event forwarder.
+// Reads ~/.context-mode/platform.json {api_key, platform_url}.
+// POSTs every event to ${platform_url}/events.
+// Privacy: redacts secrets + normalizes $HOME before send.
+// Backward-compat (PRD §5.3 Upgrade Lag): v1 events_url → platform_url; token → api_key.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+
+const CACHE_TTL_MS = 60_000;
+const FETCH_TIMEOUT_MS = 2_000;
+const MAX_FIELD_LEN = 200;
+const MAX_DEPTH = 4;
+
+// Negative-cache sentinel — distinguishes "uninitialized" (null) from
+// "we checked recently and there's no config" (NO_CONFIG). Without this,
+// the unconfigured-user path would hit fs.readFileSync on every event.
+const NO_CONFIG = Symbol("no-config");
+
+let _cache = null;
+let _cacheLoadedAt = 0;
+let _warned = false; // dedupe stderr — log first failure only, reset on success
+let _fsLoads = 0;    // test-only counter: how many times readConfig hit the FS
+
+// === Cross-platform config path (bug-free across Win/Linux/Mac/WSL) ===
+export function configPath() {
+  if (process.platform === "win32") {
+    const appdata = process.env.APPDATA;
+    if (appdata) return path.join(appdata, "context-mode", "platform.json");
+    // Fallback if APPDATA unset (rare — Git Bash without env)
+    return path.join(os.homedir(), "AppData", "Roaming", "context-mode", "platform.json");
+  }
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, "context-mode", "platform.json");
+  }
+  return path.join(os.homedir(), ".context-mode", "platform.json");
+}
+
+function warn(msg) {
+  if (_warned) return;
+  _warned = true;
+  process.stderr.write(`[context-mode] ${msg}\n`);
+}
+
+// v1 events_url + token alias kept for Upgrade Lag (PRD §5.3).
+// Stray fields (version, hostname, device_id, endpoints.sessions, routes) silently ignored.
+function normalizeConfig(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const api_key = raw.api_key ?? raw.token;
+  let platform_url = raw.platform_url;
+  if (!platform_url && raw.endpoints?.events) platform_url = String(raw.endpoints.events).replace(/\/events$/, "");
+  if (!platform_url && raw.events_url) platform_url = String(raw.events_url).replace(/\/events$/, "");
+  if (typeof api_key !== "string" || !api_key.startsWith("ctxm_")) return null;
+  if (typeof platform_url !== "string" || !platform_url) return null;
+  return { api_key, platform_url: platform_url.replace(/\/$/, "") };
+}
+
+function readConfig() {
+  const now = Date.now();
+  // Cache hit — covers BOTH positive (config object) and negative (NO_CONFIG) results.
+  if (_cache !== null && now - _cacheLoadedAt < CACHE_TTL_MS) {
+    return _cache === NO_CONFIG ? null : _cache;
+  }
+  _cacheLoadedAt = now;
+  _fsLoads++;
+  const cfgPath = configPath();
+
+  let raw;
+  try {
+    raw = fs.readFileSync(cfgPath, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") warn(`cannot read ${cfgPath}: ${e.code || e.message}`);
+    _cache = NO_CONFIG;
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    warn(`${cfgPath} is not valid JSON: ${e.message}`);
+    _cache = NO_CONFIG;
+    return null;
+  }
+
+  const normalized = normalizeConfig(parsed);
+  if (!normalized) {
+    warn(`${cfgPath} schema invalid — expected {api_key (ctxm_*), platform_url}`);
+    _cache = NO_CONFIG;
+    return null;
+  }
+
+  _warned = false; // success — re-arm warning for future failures
+  _cache = normalized;
+  return _cache;
+}
+
+// === Gate — cheap boolean for callers that want to skip allocations entirely ===
+// `session-loaders.mjs` uses this BEFORE the per-event forwarding loop so the
+// loop never executes when ~/.context-mode/platform.json is missing. Honors
+// the same 60s TTL as readConfig() — first call hits the FS, subsequent calls
+// within the TTL return the cached decision (positive or negative).
+export function hasPlatformConfig() {
+  return readConfig() !== null;
+}
+
+// === URL construction (single endpoint per ADR-0006) ===
+export function buildUrl(cfg, _eventType) {
+  return `${cfg.platform_url}/events`;
+}
+
+// === Project identity resolution — worktree-invariant canonicalization ===
+// Filesystem path is the wrong identifier for "project": git worktrees fork
+// the path while keeping the same repo, monorepos collapse N packages into
+// one umbrella, and forks of the same repo look like different projects.
+// Resolve to a stable identity using:
+//   1. Closest package.json `name` if it lives DEEPER than the .git root
+//      (monorepo sub-package — preserve granularity)
+//   2. git config remote.origin.url, normalized
+//      (worktrees of one repo collapse to one identity)
+//   3. Closest package.json `name` at any depth
+//      (local-only Node project)
+//   4. basename(projectDir) (last resort)
+const _projectIdentityCache = new Map();
+
+function resolveProjectIdentity(projectDir) {
+  if (typeof projectDir !== "string" || !projectDir) return null;
+  if (_projectIdentityCache.has(projectDir)) return _projectIdentityCache.get(projectDir);
+  const id = computeProjectIdentity(projectDir);
+  _projectIdentityCache.set(projectDir, id);
+  return id;
+}
+
+function computeProjectIdentity(projectDir) {
+  let absoluteDir;
+  try {
+    absoluteDir = path.resolve(projectDir);
+  } catch {
+    return null;
+  }
+  const walked = walkUpFromDir(absoluteDir);
+  const pkg = walked.packageJson;
+  const gitTop = walked.gitToplevel;
+
+  // (1) Monorepo sub-package: package.json STRICTLY deeper than .git root.
+  if (pkg && gitTop && pkg.dir !== gitTop && pkg.dir.length > gitTop.length && pkg.name) {
+    return pkg.name;
+  }
+  // (2) Git remote URL.
+  const remote = gitTop ? readGitRemote(gitTop) : null;
+  if (remote) return normalizeRemoteUrl(remote);
+  // (3) Closest package.json (any depth).
+  if (pkg?.name) return pkg.name;
+  // (4) Basename.
+  return path.basename(absoluteDir);
+}
+
+function walkUpFromDir(start) {
+  let dir = start;
+  let pkg = null;
+  let gitTop = null;
+  // Safety: cap walk to 64 levels; real filesystems never hit this.
+  for (let i = 0; i < 64; i++) {
+    if (!pkg) {
+      const pkgPath = path.join(dir, "package.json");
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+          if (typeof parsed?.name === "string" && parsed.name.trim()) {
+            pkg = { dir, name: parsed.name.trim() };
+          }
+        } catch { /* malformed — skip silently */ }
+      }
+    }
+    if (!gitTop && fs.existsSync(path.join(dir, ".git"))) {
+      gitTop = dir;
+    }
+    if (pkg && gitTop) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { packageJson: pkg, gitToplevel: gitTop };
+}
+
+function readGitRemote(gitTop) {
+  try {
+    const url = execSync("git config --get remote.origin.url", {
+      cwd: gitTop,
+      encoding: "utf8",
+      timeout: 500,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+}
+
+// Canonical wire shape: host/path, lowercased host, no scheme, no .git suffix,
+// no embedded credentials. All clone-equivalents collapse to one identity.
+function normalizeRemoteUrl(url) {
+  let u = String(url).trim();
+  // SSH form (git@host:org/repo) → host/org/repo
+  const sshMatch = u.match(/^[a-z0-9_-]+@([^:]+):(.+)$/i);
+  if (sshMatch) {
+    u = `${sshMatch[1]}/${sshMatch[2]}`;
+  } else {
+    // scheme://[user[:pass]@]host/path  →  host/path
+    u = u.replace(/^[a-z]+:\/\/(?:[^@/]+@)?/i, "");
+  }
+  u = u.replace(/\.git\/?$/i, "").replace(/\/+$/, "");
+  // Lowercase host segment only (paths can be case-sensitive)
+  const slash = u.indexOf("/");
+  if (slash > 0) {
+    u = u.slice(0, slash).toLowerCase() + u.slice(slash);
+  } else {
+    u = u.toLowerCase();
+  }
+  return u;
+}
+
+// === Privacy: secret + PII redaction ===
+const SECRETS = [
+  /\b(?:ghp|gho|ghs|ghu|github_pat)_[A-Za-z0-9_]{20,}\b/g, // GitHub
+  /\bAKIA[0-9A-Z]{16}\b/g,                                 // AWS
+  /\bsk-(?:ant|proj)?-?[A-Za-z0-9_-]{32,}\b/g,             // OpenAI/Anthropic
+  /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, // JWT
+  /\bxox[bpoas]-[A-Za-z0-9-]{10,}\b/g,                     // Slack
+  /\bglpat-[A-Za-z0-9_-]{20,}\b/g,                         // GitLab
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,   // emails
+  /\b\d{3}-\d{2}-\d{4}\b/g,                                // SSN-like
+];
+const HOME = os.homedir();
+const USER_DIR_RE = /(\/Users\/|\/home\/|\\+Users\\+)[^/\\]+/g;
+
+function privacyTransform(s) {
+  if (typeof s !== "string") return s;
+  let out = s.split(HOME).join("<HOME>")
+    .replace(USER_DIR_RE, (m) => m.replace(/[^/\\]+$/, "<USER>"));
+  for (const re of SECRETS) out = out.replace(re, "[REDACTED]");
+  return out;
+}
+
+function walk(obj, depth) {
+  if (depth > MAX_DEPTH) return "[depth-limited]";
+  if (obj == null) return obj;
+  if (typeof obj === "string") {
+    const cleaned = privacyTransform(obj);
+    return cleaned.length > MAX_FIELD_LEN ? cleaned.slice(0, MAX_FIELD_LEN) + "…[truncated]" : cleaned;
+  }
+  if (Array.isArray(obj)) return obj.slice(0, 50).map((x) => walk(x, depth + 1));
+  if (typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = walk(v, depth + 1);
+    return out;
+  }
+  return obj;
+}
+
+export function sanitizeEvent(event) {
+  return event && typeof event === "object" ? walk(event, 0) : event;
+}
+
+// === Public API ===
+export async function maybeForward(event, platform, opts = {}) {
+  const cfg = readConfig();
+  if (!cfg) return;
+
+  // Project identity must be resolved from the RAW projectDir — the resolver
+  // reads `git config` against the actual filesystem path. After sanitize,
+  // $HOME-normalization would break the lookup. We overlay the resolved id
+  // back onto the event so the sanitize/walk path sees the canonical value
+  // (URL or package name, which need no further normalization).
+  const resolvedProject = resolveProjectIdentity(event?.projectDir);
+  const eventWithProject = resolvedProject !== null
+    ? { ...event, project: resolvedProject }
+    : event;
+  const ev = sanitizeEvent(eventWithProject);
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(buildUrl(cfg, ev.type), {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${cfg.api_key}`,
+        "Content-Type": "application/json",
+        "X-Source-Platform": platform,
+        "X-Schema-Version": "2",
+      },
+      // Canonical envelope (PRD §5.4 stability ABI):
+      //   - All event fields passthrough — server-side Zod picks per event.type
+      //   - `platform` envelope metadata (claude-code, cursor, ...)
+      //   - `ts` defaulted from event or wall clock
+      // Hand-mapping individual fields here is the anti-pattern: every new
+      // event field forced a bridge release. With this envelope, new fields
+      // ride the existing pipe and the platform schema is the only thing
+      // that ever needs to learn them.
+      body: JSON.stringify({
+        ...ev,
+        platform,
+        ts: ev.ts ?? opts.ts ?? Math.floor(Date.now() / 1000),
+      }),
+      signal: ctrl.signal,
+    });
+    if (res.status === 401) { _cache = null; _cacheLoadedAt = 0; }
+    else if (res.status === 429) {
+      process.stderr.write(`[context-mode-platform] rate limited (retry after ${res.headers.get("Retry-After")}s)\n`);
+    }
+    return { ok: res.ok, status: res.status };
+  } catch (e) {
+    return { ok: false, status: 0, error: e.message };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export const _internal = {
+  readConfig,
+  normalizeConfig,
+  buildUrl,
+  sanitizeEvent,
+  privacyTransform,
+  configPath,
+  resolveProjectIdentity,
+  normalizeRemoteUrl,
+  walkUpFromDir,
+  resetState: () => {
+    _cache = null;
+    _cacheLoadedAt = 0;
+    _warned = false;
+    _fsLoads = 0;
+    _projectIdentityCache.clear();
+  },
+  get fsLoads() { return _fsLoads; },
+  get projectIdentityCacheSize() { return _projectIdentityCache.size; },
+};