@minhspark/codex-mcp-bridge 1.20.1 → 1.21.0

package/scripts/install-claude-desktop.mjs

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
 
 import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
 import { desktopTasksConfigured } from "../src/native-relay.mjs";
@@ -40,7 +41,37 @@ if (!path.isAbsolute(codexBin) || !fs.existsSync(codexBin)) {
 
 fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
 
-const cfg = fs.existsSync(cfgPath) ? JSON.parse(fs.readFileSync(cfgPath, "utf8")) : {};
+function readConfig() {
+  let descriptor;
+  try {
+    const before = fs.lstatSync(cfgPath);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 4 * 1024 * 1024) throw new Error("Unsafe Desktop configuration file");
+    descriptor = fs.openSync(cfgPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const opened = fs.fstatSync(descriptor);
+    const fields = ["dev", "ino", "size", "mtimeMs", "ctimeMs"];
+    const matches = (left, right) => fields.every(field => left[field] === right[field]);
+    if (!opened.isFile() || opened.nlink !== 1 || !matches(before, opened)) throw new Error("Desktop configuration changed during access");
+    const data = Buffer.alloc(opened.size);
+    let offset = 0;
+    while (offset < data.length) {
+      const count = fs.readSync(descriptor, data, offset, data.length - offset, offset);
+      if (!count) throw new Error("Desktop configuration changed during access");
+      offset += count;
+    }
+    const after = fs.fstatSync(descriptor);
+    const current = fs.lstatSync(cfgPath);
+    if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || !matches(opened, after) || !matches(after, current)) throw new Error("Desktop configuration changed during access");
+    return { data, version: fields.map(field => current[field]) };
+  } catch (error) {
+    if (error.code === "ENOENT" && descriptor === undefined) return null;
+    throw error;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+const original = readConfig();
+const cfg = original ? JSON.parse(original.data.toString("utf8")) : {};
 cfg.mcpServers = cfg.mcpServers ?? {};
 
 /**
@@ -119,11 +150,23 @@ cfg.mcpServers["codex-bridge"] = {
 
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...cfg.mcpServers["codex-bridge"].env }) });
 
-if (fs.existsSync(cfgPath)) {
-  const backup = `${cfgPath}.bak-${new Date().toISOString().slice(0, 10)}-codexbridge`;
-  if (!fs.existsSync(backup)) fs.copyFileSync(cfgPath, backup);
+const backup = `${cfgPath}.bak-${new Date().toISOString().slice(0, 10)}-codexbridge`;
+if (original) {
+  try { fs.writeFileSync(backup, original.data, { flag: "wx", mode: 0o600 }); }
+  catch (error) { if (error.code !== "EEXIST") throw error; }
+}
+const temporary = `${cfgPath}.${randomUUID()}.tmp`;
+try {
+  fs.writeFileSync(temporary, `${JSON.stringify(cfg, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+  const current = readConfig();
+  if (original === null ? current !== null : current === null || !original.data.equals(current.data) || original.version.some((value, index) => value !== current.version[index])) {
+    throw new Error("Desktop configuration changed during installation; retry after the other writer finishes");
+  }
+  fs.renameSync(temporary, cfgPath);
+} finally {
+  try { fs.unlinkSync(temporary); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
 }
-fs.writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`updated ${cfgPath}`);

package/scripts/install-native-relay.mjs

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.20.1";
+const VERSION = "1.21.0";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
@@ -79,6 +79,11 @@ const existingServer = servers.some((server) => server.name === serverName)
  */
 const runtime = resolveCodexDesktopNodeBin();
 
+if (IS_MACOS || IS_WINDOWS) {
+  console.log(`Native Desktop setup: in ${path.join(homeDir(), ".codex", "config.toml")} (or CODEX_HOME/config.toml), add env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"] to the existing [mcp_servers.${serverName}] entry after registration.`);
+  console.log("Preserve existing settings and append the name to any existing env_vars list; do not save the temporary pipe path. Reconnect the relay or restart Codex Desktop after active work finishes, then check native_relay_status in the existing task.");
+}
+
 const registration = stdioMcpRegistration({ name: serverName, existing: existingServer, node: runtime.path, entry, entryArgs, envOverrides: {
   ...(process.env.CLAUDE_DESKTOP_USER_DATA !== undefined ? { CLAUDE_DESKTOP_USER_DATA: process.env.CLAUDE_DESKTOP_USER_DATA } : {}),
 } });

package/scripts/install-npm-footer.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 
 exitForVersionRequest(import.meta.url);
@@ -70,7 +71,18 @@ if (!remove) {
   fs.mkdirSync(footerDirectory, { recursive: true, mode: 0o700 });
   if (fs.existsSync(footerPath) && (!fs.lstatSync(footerPath).isFile() || fs.lstatSync(footerPath).isSymbolicLink())) throw new Error(`Unsafe footer destination: ${footerPath}`);
   if (!fs.existsSync(footerPath) || fs.readFileSync(footerPath, "utf8") !== source) {
-    fs.writeFileSync(footerPath, source, { mode: 0o600 });
+    const temporary = `${footerPath}.${randomUUID()}.tmp`;
+    let created = false;
+    try {
+      fs.writeFileSync(temporary, source, { mode: 0o600, flag: "wx" });
+      created = true;
+      fs.renameSync(temporary, footerPath);
+    } finally {
+      if (created) {
+        try { fs.unlinkSync(temporary); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+      }
+    }
   }
 }
 for (const { file, before, after } of edits) {

package/scripts/publish-repo-analytics.mjs

@@ -105,6 +105,29 @@ export function renderPublicDashboard(data) {
   return `<svg xmlns="http://www.w3.org/2000/svg" width="820" height="${y + 35}" viewBox="0 0 820 ${y + 35}" role="img" aria-label="Repository aggregate analytics"><rect width="100%" height="100%" fill="#0d1626"/><g font-family="Arial, sans-serif">${body.join('')}</g></svg>\n`;
 }
 
+export function renderGithubViewsBadge(data, { now = Date.now() } = {}) {
+  const snapshot = [...data.snapshots].sort((a, b) => String(b.collectedAt).localeCompare(String(a.collectedAt))).find(row => row.views);
+  const views = snapshot?.views;
+  const time = snapshot?.sourceCollectedAt?.views;
+  const start = views?.views?.[0]?.timestamp?.slice(0, 10);
+  const end = views?.views?.at(-1)?.timestamp?.slice(0, 10);
+  const validWindow = date(start) && date(end);
+  const days = validWindow ? (Date.parse(end) - Date.parse(start)) / 86400000 + 1 : null;
+  const label = `GitHub views / ${days > 0 ? `${days}d` : 'window'}`;
+  const value = views?.count;
+  const undated = !date(time);
+  const stale = !undated && now - Date.parse(time) > staleAfter;
+  const age = value == null ? '' : undated ? ' · undated' : stale ? ' · stale' : '';
+  const message = format(value) + age;
+  const color = value == null ? '#555' : stale || undated ? '#92400e' : '#0369a1';
+  const detail = `${validWindow ? `${start} to ${end} UTC` : 'Source window unavailable'}. Source: ${displayTime(time)}. Archived badge; freshness is relative to generation time.`;
+  const labelWidth = Math.ceil([...label].length * 7.2 + 16);
+  const messageWidth = Math.ceil([...message].length * 7.2 + 16);
+  const width = labelWidth + messageWidth;
+  const accessible = `${label}: ${message}`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="24" viewBox="0 0 ${width} 24" role="img" aria-label="${escapeXml(accessible)}"><title>${escapeXml(`${accessible}. ${detail}`)}</title><rect width="${width}" height="24" rx="4" fill="#555"/><path d="M${labelWidth} 0H${width - 4}Q${width} 0 ${width} 4V20Q${width} 24 ${width - 4} 24H${labelWidth}Z" fill="${color}"/><g fill="#fff" font-family="DejaVu Sans Mono,monospace" font-size="12" text-anchor="middle"><text x="${labelWidth / 2}" y="16">${escapeXml(label)}</text><text x="${labelWidth + messageWidth / 2}" y="16">${escapeXml(message)}</text></g></svg>\n`;
+}
+
 export function renderLiveDashboard(data) {
   const latest = source => [...data.snapshots].sort((a, b) => String(b.collectedAt).localeCompare(String(a.collectedAt))).find(row => row[source]);
   const npm = latest('npm');
@@ -195,7 +218,7 @@ export function publicFiles(history, usage) {
   const table = ['| Date (UTC) | Views | Unique visitors | Clones | Unique cloners | npm downloads | Active installations |', '|---|---:|---:|---:|---:|---:|---:|', ...days.map(day => `| ${day} | ${[data.daily.views[day]?.count, data.daily.views[day]?.uniques, data.daily.clones[day]?.count, data.daily.clones[day]?.uniques, data.daily.npm[day]?.downloads, usageDays[day]].map(format).join(' | ')} |`)].join('\n');
   const readme = `# Public repository analytics\n\n![Repository dashboard](dashboard.svg)\n\n[Aggregate JSON history](data.json) · [Repository](https://github.com/${data.repo})\n\nAll dates and source windows use UTC. Source timestamps on the dashboard show when each metric was last available. Downloads and clones include automation and do not measure people. Unique visitors/cloners apply only to the source window; never sum daily unique counts across dates. Active installations cover consenting installations only, with distinct counts for each whole period. Operating system and version breakdowns cover 30 days; an installation may appear in multiple version groups after upgrading.\n\nThis branch contains only aggregate statistics. No installation identifiers, prompts, account details, credentials, private error messages, or local paths are published. Missing metrics mean unavailable, not zero.\n\n## Daily history\n\nEvery archived source day is listed below, newest first. Active installations count consenting installations that reported that UTC day.\n\n${table}\n`;
   const pagesUrl = `https://${data.repo.split('/')[0]}.github.io/${data.repo.split('/')[1]}/`;
-  return { 'dashboard.svg': renderPublicDashboard(data), 'README.md': readme.replace('![Repository dashboard]', `[Live dashboard · refreshes every 30 seconds](${pagesUrl})\n\n![Repository dashboard]`), 'data.json': `${JSON.stringify(data, null, 2)}\n`, 'index.html': renderLiveDashboard(data) };
+  return { 'stats-github-views.svg': renderGithubViewsBadge(data), 'dashboard.svg': renderPublicDashboard(data), 'README.md': readme.replace('![Repository dashboard]', `[Live dashboard · refreshes every 30 seconds](${pagesUrl})\n\n![Repository dashboard]`), 'data.json': `${JSON.stringify(data, null, 2)}\n`, 'index.html': renderLiveDashboard(data) };
 }
 
 export function githubEnvironment(token, env = process.env) {

package/src/app-server-client.mjs

@@ -69,7 +69,9 @@ function listeningPids(port) {
 }
 
 function httpBase(wsUrl) {
-  return wsUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:").replace(/\/+$/, "");
+  const url = assertAllowedAppServerUrl(wsUrl);
+  url.protocol = url.protocol === "ws:" ? "http:" : "https:";
+  return url.href.replace(/\/+$/, "");
 }
 
 /**
@@ -133,6 +135,7 @@ export class CodexAppServerClient {
     try {
       const res = await fetch(`${httpBase(this.url)}/readyz`, {
         signal: AbortSignal.timeout(2000),
+        redirect: "error",
       });
       return res.ok;
     } catch {
@@ -283,7 +286,7 @@ export class CodexAppServerClient {
     }
 
     this.#assertConnectionEpoch(epoch);
-    const ws = new WebSocket(this.url);
+    const ws = new WebSocket(assertAllowedAppServerUrl(this.url).href);
     this.ws = ws;
     try {
       await new Promise((resolve, reject) => {

package/src/bridge-readiness.mjs

@@ -0,0 +1,23 @@
+export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, verifyTargetProject }) {
+  const issues = [];
+  if (sender?.status !== "verified") issues.push({ code: "SENDER_UNVERIFIED", detail: sender?.reason ?? "No current Code session identity", action: "Load the user-level Claude Code bridge entry in this existing task; a shared Desktop entry cannot identify the caller. Run the Code registration check, then reload the affected client." });
+  const projectPolicy = scope?.status?.(sender?.status === "verified" ? sender.cwd : undefined) ?? null;
+  if (projectPolicy?.error) issues.push({ code: "PROJECT_SCOPE_INVALID", detail: projectPolicy.error, action: "Check the shared project policy. Authorize the intended project once; never change the sending task to work around a refusal." });
+  let target = null;
+  if (targetCwd) {
+    try {
+      const binding = scope.capture?.(targetCwd);
+      target = { ...(binding ?? {}), cwd: binding?.path ?? scope.assert(targetCwd), authorized: true };
+    }
+    catch (error) { target = { cwd: targetCwd, authorized: false }; issues.push({ code: "TARGET_NOT_AUTHORIZED", detail: error.message, action: "Authorize this project or its parent directory once in the shared project policy." }); }
+  }
+  if (target?.authorized && sender?.status === "verified" && verifyTargetProject) {
+    try { verifyTargetProject(sender.cwd, target.cwd); target.sameProject = true; }
+    catch (error) {
+      target.sameProject = false;
+      issues.push({ code: error.code ?? "PROJECT_SCOPE_UNVERIFIED", detail: error.message, action: "Select a destination in the verified sender's project. A project grant does not authorize cross-project delivery." });
+    }
+  }
+  if (!nativeAvailable) issues.push({ code: "RELAY_UNAVAILABLE", action: "Open Codex Desktop and check native_relay_status in its existing task." });
+  return { ready: issues.length === 0, readyScope: "transport-identity-and-project", hostToolPermission: "evaluated-by-client-at-call-time", sender, projectPolicy, target, issues };
+}

package/src/card-settings-sync.mjs

@@ -0,0 +1,125 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectRevocationEntry, scopeEntry, updateProjectPolicy } from './project-policy.mjs';
+
+const empty = () => ({ projects: [], parents: [], excluded: [] });
+const key = p => process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p);
+const same = (a, b) => key(a) === key(b);
+const includes = (list, p) => list.some(v => same(v, p));
+function canonicalSettingsPath(value) {
+  // Policy entries use real directory paths. Native pages can use /var aliases
+  // or Windows short names; compare them in the same namespace. Keep missing
+  // paths removable by resolving their nearest existing ancestor, not dropping
+  // the record (in particular a revoked or deleted project).
+  let current = path.resolve(value);
+  const suffix = [];
+  for (;;) {
+    try { return path.join(fs.realpathSync.native(current), ...suffix); }
+    catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      const parent = path.dirname(current);
+      if (parent === current) return path.resolve(value);
+      suffix.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+function normalize(page) {
+  const output = empty();
+  for (const field of Object.keys(output)) {
+    if (!Array.isArray(page?.[field]) || page[field].length > 512) throw new Error('Invalid card settings list: ' + field);
+    for (const item of page[field]) {
+      if (typeof item !== 'string' || item.length > 32768) throw new Error('Invalid card settings path');
+      const value = item.trim();
+      if (!value) continue;
+      if (!path.isAbsolute(value)) throw new Error('Card settings paths must be absolute');
+      const canonical = canonicalSettingsPath(value);
+      if (!includes(output[field], canonical)) output[field].push(canonical);
+    }
+    output[field].sort((a, b) => key(a).localeCompare(key(b)));
+  }
+  return output;
+}
+const equal = (a, b) => Object.keys(empty()).every(k => a[k].length === b[k].length && a[k].every(p => includes(b[k], p)));
+const pageHash = page => createHash('sha256').update(JSON.stringify(Object.fromEntries(Object.entries(page).map(([k, v]) => [k, v.map(key).sort()])))).digest('hex');
+const fingerprint = policy => createHash('sha256').update(JSON.stringify({ grants: policy.grants, denies: policy.denies })).digest('hex');
+const projection = policy => normalize({ projects: policy.grants.filter(g => g.kind === 'project').map(g => g.path),
+  parents: policy.grants.filter(g => g.kind === 'parent').map(g => g.path), excluded: policy.denies.map(g => g.path) });
+const sameEntry = (a, b) => same(a.path, b.path) || (a.repository && b.repository && same(a.repository.path, b.repository.path) && a.repository.identity === b.repository.identity);
+
+// This optional UI adapter is not read by messaging permission checks. Keep the
+// acknowledgement in the same atomic file as grants so a crash cannot replay an
+// old settings save as a fresh permission change. No card grants or trust flags
+// are copied into the messaging policy.
+export function syncCardSettings(policyFile, input, options = {}) {
+  const page = normalize(input);
+  let result;
+  updateProjectPolicy(policyFile, policy => {
+    const saved = policy.uiAdapters?.localCardDesktop;
+    if (saved && saved.version !== 1) throw new Error('Unsupported card settings acknowledgement');
+    const previous = saved ? normalize(saved.page) : empty();
+    const current = fingerprint(policy);
+    const priorRenders = saved?.renderTargets ?? [];
+    if (!Array.isArray(priorRenders) || priorRenders.length > 16 || priorRenders.some(v => !/^[a-f0-9]{64}$/.test(v))) throw new Error('Invalid settings render acknowledgement');
+    const rendered = saved && (equal(page, normalize(saved.target)) || priorRenders.includes(pageHash(page)));
+    const changed = !equal(page, previous);
+    // Reinstalling the extension resets its page to blank while this acknowledgement
+    // survives, so a blank page cannot be told apart from "remove everything". Treat
+    // it like a first page: import the current lists and revoke nothing. A last
+    // project can still be revoked explicitly through the exclusion list.
+    const blank = Object.values(page).every(list => list.length === 0);
+    const reset = saved && changed && blank && !rendered && !options.acknowledgeRender;
+    const conflict = saved && changed && !rendered && !reset && (saved.renderOverflow || current !== saved.authorizationFingerprint);
+    const warnings = [];
+    if (conflict) warnings.push('通信授权刚被其他入口修改，本次页面更改未应用；先同步最新页面，再修改。');
+    if (reset) warnings.push('通信页面为空，未撤销任何授权，已按现有授权重新填充。确需撤销，请把项目移入通信禁止列表后保存。');
+    if (changed && !rendered && !conflict && !reset && !options.acknowledgeRender) {
+      // Removing a displayed exclusion is an explicit UI action. A new grant
+      // never implicitly removes an exclusion that the page has not shown.
+      const removedExclusions = previous.excluded.filter(p => !includes(page.excluded, p));
+      policy.denies = policy.denies.filter(d => !includes(removedExclusions, d.path));
+      for (const [field, kind] of [['projects', 'project'], ['parents', 'parent']]) {
+        const removed = previous[field].filter(p => !includes(page[field], p));
+        const oldGrants = policy.grants.filter(g => g.kind === kind && includes(removed, g.path));
+        policy.grants = policy.grants.filter(g => !(g.kind === kind && includes(removed, g.path)));
+        // Removing one project revokes it even under a granted parent. Removing
+        // a parent only removes that broad grant; exact project grants survive.
+        if (kind === 'project') for (const grant of oldGrants) {
+          if (!policy.denies.some(d => sameEntry(d, grant))) policy.denies.push(projectRevocationEntry(grant, options));
+        }
+        for (const p of page[field].filter(p => !includes(previous[field], p))) {
+          if (policy.grants.some(g => g.kind === kind && same(g.path, p))) continue;
+          const entry = scopeEntry(p, kind, options);
+          if (policy.denies.some(d => sameEntry(d, entry))) {
+            warnings.push(`项目仍被禁止，未恢复授权：${p}。请先从通信禁止列表移除，再添加授权。`);
+            continue;
+          }
+          policy.grants = policy.grants.filter(g => !(g.kind === kind && sameEntry(g, entry)));
+          policy.grants.push(entry);
+        }
+      }
+      for (const p of page.excluded.filter(p => !includes(previous.excluded, p))) {
+        if (policy.denies.some(d => same(d.path, p))) continue;
+        const old = policy.grants.find(g => same(g.path, p));
+        const entry = projectRevocationEntry(old ?? scopeEntry(p, 'project', options), options);
+        policy.grants = policy.grants.filter(g => !sameEntry(g, entry));
+        policy.denies.push(entry);
+      }
+    }
+    const target = projection(policy);
+    // A detached page helper can finish rendering an older policy after a newer
+    // revocation. Remember issued snapshots: that save is display acknowledgement,
+    // never a user's request to restore the old grant.
+    const aligned = equal(page, target);
+    const acknowledged = aligned && (options.acknowledgeRender || (changed && rendered));
+    const renderTargets = acknowledged ? [] : aligned ? [...priorRenders] : [...new Set([...priorRenders, pageHash(target)])];
+    policy.uiAdapters ??= {};
+    policy.uiAdapters.localCardDesktop = { version: 1, page, target, authorizationFingerprint: fingerprint(policy),
+      renderTargets: renderTargets.slice(-16), renderOverflow: !acknowledged && (saved?.renderOverflow === true || renderTargets.length > 16) };
+    result = { status: conflict ? 'conflict_preserved' : reset ? 'blank_page_imported' : 'synchronized', target,
+      needsPageUpdate: !equal(page, target), warnings, authorizationChanged: current !== fingerprint(policy),
+      detail: 'Only messaging lists were reconciled. Card grants and workspace trust are unchanged.' };
+  });
+  return result;
+}

package/src/claude-bridge.mjs

@@ -10,13 +10,13 @@ import { PLATFORM_LABEL, openClaudeCodeComposer } from "./platform.mjs";
 import { PeerEndpoint, assertClaudeSessionCwd, assertClaudeSessionProcess, findClaudeSession, listClaudeSessions, readTranscript, readInitialTranscriptMessage } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
-import { desktopTasksConfigured } from "./native-relay.mjs";
+import { desktopTasksConfigured, NativeDesktopRelay, desktopTaskSocketPath, accountRelaySocketPath } from "./native-relay.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
 import { readClaudeDesktopContext, readClaudeDesktopTasks } from "./claude-desktop-context.mjs";
 import { ClaudeSessionCreation } from "./claude-session-creation.mjs";
 import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
 import { assertRecipientClass, preflightFailure } from "./recipient-preflight.mjs";
-import { readCodexSenderContext } from "./codex-sender-context.mjs";
+import { resolveCodexSenderContext } from "./codex-sender-context.mjs";
 import { ReplyForwarder } from "./reply-forwarder.mjs";
 import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
 import { readClaudeAccountContext } from "./desktop-account-context.mjs";
@@ -25,10 +25,11 @@ import { recoverClaudeDesktopSession, resolveClaudeDesktopSession, sameClaudeDes
 import { submitClaudeCodeComposer, trustClaudeCodeComposer } from "./claude-composer-submit.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
+import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.20.1";
+const VERSION = "1.21.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -216,8 +217,20 @@ function assertDesktopTask(session, expectedTaskId) {
   }
 }
 
-function assertSender(meta) {
-  const sender = readCodexSenderContext(meta);
+const senderRelay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() });
+async function readSender(meta) {
+  return resolveCodexSenderContext(meta, { inspectDesktopTask: async (threadId) => {
+    const accounts = requireBridgeAccounts(readBridgeAccounts());
+    const { result } = await senderRelay.requestDesktop("read_thread", {
+      threadId, hostId: "local", turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 1,
+    }, { accountContext: accounts, beforeSend: () => assertAccountIdentity(accounts) });
+    assertAccountIdentity(accounts);
+    return { thread: result?.thread, latestTurnId: result?.turns?.[0]?.id ?? null };
+  } });
+}
+
+async function assertSender(meta) {
+  const sender = await readSender(meta);
   if (sender.status !== "verified") {
     throw preflightFailure("CODEX_SENDER_CONTEXT_UNVERIFIED", `${sender.reason} Check claude_bridge_status in the calling Codex Desktop task. Manual relay binding and a global permission override do not establish the sender's permissions.`);
   }
@@ -233,7 +246,7 @@ function assertCreationRoots(requestId, sender) {
 async function startClaudeCreation({ requestId, cwd, prompt, autoSubmit = process.platform === "win32", trustProject = process.env.CLAUDE_BRIDGE_AUTO_TRUST_PROJECTS === "1" }, meta) {
   runtime.assertCurrent();
   if (!desktopOnly) throw new Error("New Claude sessions require Desktop-only mode");
-  const sender = assertSender(meta);
+  const sender = await assertSender(meta);
   const accounts = readBridgeAccounts();
   const selectedAccounts = requireBridgeAccounts(accounts);
   if (rootPolicy.enabled && creations.requests.has(requestId)) assertCreationRoots(requestId, sender);
@@ -242,13 +255,17 @@ async function startClaudeCreation({ requestId, cwd, prompt, autoSubmit = proces
     recipient: rootPolicy.capture(cwd, "Claude creation working directory"),
   } : null;
   const receipt = await creations.start({ requestId, cwd, prompt, autoSubmit, trustProject, account: accounts.claude, senderThreadId: sender.threadId,
-    beforeOpen: () => {
+    beforeOpen: async () => {
       runtime.assertCurrent();
       assertAccountIdentity(selectedAccounts);
       recheckScopeBindings(scopeBindings);
       if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
-      const current = assertSender(meta);
+      const current = await assertSender(meta);
       if (JSON.stringify(current) !== JSON.stringify(sender)) throw new Error("The calling Codex turn changed before opening Claude Desktop");
+      runtime.assertCurrent();
+      assertAccountIdentity(selectedAccounts);
+      recheckScopeBindings(scopeBindings);
+      if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
     },
   });
   if (rootPolicy.enabled) creationRootBindings.set(requestId, scopeBindings);
@@ -256,7 +273,7 @@ async function startClaudeCreation({ requestId, cwd, prompt, autoSubmit = proces
 }
 
 async function inspectClaudeCreation(requestId, meta) {
-  const sender = assertSender(meta);
+  const sender = await assertSender(meta);
   assertCreationRoots(requestId, sender);
   const accounts = readBridgeAccounts();
   requireBridgeAccounts(accounts);
@@ -314,6 +331,13 @@ function registerTool(name, definition, handler) {
   });
 }
 
+registerProjectOnboardingTools(registerTool, { beforePrepare: async (extra) => {
+  runtime.assertCurrent();
+  if (!desktopOnly) throw new Error("Project onboarding requires a verified Desktop caller");
+  await assertSender(extra?._meta);
+  requireBridgeAccounts(readBridgeAccounts());
+} });
+
 registerTool(
   "start_claude_session",
   {
@@ -351,7 +375,7 @@ registerTool(
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   },
   async ({ requestId }, extra) => {
-    const sender = assertSender(extra?._meta);
+    const sender = await assertSender(extra?._meta);
     assertCreationRoots(requestId, sender);
     const accounts = readBridgeAccounts();
     requireBridgeAccounts(accounts);
@@ -443,7 +467,7 @@ registerTool(
       runtime.assertCurrent();
       if (target === "new") {
         if (expectedTaskId !== undefined) throw new Error("A new Claude conversation cannot target an existing task ID");
-        const sender = assertSender(extra?._meta);
+        const sender = await assertSender(extra?._meta);
         const creationId = requestId ?? createHash("sha256").update(JSON.stringify([sender.threadId, expectedCwd, message])).digest("hex");
         return await startClaudeCreation({ requestId: creationId, cwd: expectedCwd, prompt: message, autoSubmit, trustProject }, extra?._meta);
       }
@@ -458,8 +482,8 @@ registerTool(
         listTasks: () => readClaudeDesktopTasks({ account: accounts.claude }),
         listSessions: () => listClaudeSessions().filter((entry) => entry.pid !== process.pid),
         open: (taskId) => openClaudeCodeComposer(`claude://code/continue?session=${encodeURIComponent(taskId)}`),
-        beforeOpen: () => {
-          const currentSender = assertSender(extra?._meta);
+        beforeOpen: async () => {
+          const currentSender = await assertSender(extra?._meta);
           if (!recoverySender) {
             recoverySender = currentSender;
             recoveryBindings = rootPolicy.enabled ? { sender: rootPolicy.capture(recoverySender.cwd, "Codex sender working directory"), recipient: rootPolicy.capture(expectedCwd, "Claude recipient working directory") } : null;
@@ -481,7 +505,7 @@ registerTool(
         assertDesktopTask(session, selectedTaskId);
         assertClaudeSessionProcess(session);
       }
-      const sender = desktopOnly ? assertSender(extra?._meta) : null;
+      const sender = desktopOnly ? await assertSender(extra?._meta) : null;
       const scopeBindings = rootPolicy.enabled ? {
         sender: rootPolicy.capture(sender?.cwd, "Codex sender working directory"),
         recipient: rootPolicy.capture(session.cwd, "Claude recipient working directory"),
@@ -491,14 +515,14 @@ registerTool(
 
       const wait = waitSec ?? 180;
       const desktop = session.entrypoint === "claude-desktop";
-      const text = desktop ? `${message}\n\n[Bridge response routing: reply with ordinary text in this conversation. The bridge reads the response associated with this message from the local transcript; no cross-session reply tool is needed.]` : message;
+      const text = desktop ? `${message}\n\n[Bridge response routing: reply with ordinary text in this conversation. The bridge reads the response associated with this message from the local transcript; no cross-session reply tool is needed. For native child tasks, check completion with native session/event tools. Do not infer completion by regex-matching JSON field order or leave an unbounded custom watcher running.]` : message;
       const { msgId, reply, delivery } = await peer.sendAndWait(session.socket, text, {
         timeoutMs: wait * 1000,
         ...(selectedAccounts ? { accountContext: selectedAccounts } : {}),
         ...(sender ? { permissionMode: sender.mode, replyThreadId: sender.threadId, senderReview: sender.review, senderApprovalPolicy: sender.approvalPolicy } : {}),
         ...(desktop ? { recipient: { permissionMode: session.desktop.permissionMode ?? null, permissionClass: session.desktop.permissionClass ?? null, inboundPolicy: session.inbound?.value ?? null } } : {}),
         ...(scopeBindings ? { scopeBindings } : {}),
-        beforeSend: () => {
+        beforeSend: async () => {
           runtime.assertCurrent();
           if (desktopOnly) assertAccountIdentity(selectedAccounts);
           const current = findClaudeSession(session.sessionId ?? String(session.pid), { desktopOnly });
@@ -514,7 +538,7 @@ registerTool(
             assertClaudeSessionProcess(current);
             const refreshed = withDesktopContext(current, readClaudeAccountContext());
             assertDesktopTask(refreshed, selectedTaskId);
-            const active = assertSender(extra?._meta);
+            const active = await assertSender(extra?._meta);
             if (rootPolicy.enabled) {
               rootPolicy.recheck(scopeBindings.sender, "Codex sender working directory");
               rootPolicy.recheck(scopeBindings.recipient, "Claude recipient working directory");
@@ -531,6 +555,10 @@ registerTool(
       });
       const status = reply ? "reply_received" : delivery?.status ?? (wait === 0 ? "sent_unconfirmed" : "reply_timeout");
       const receipt = { status, msgId, target: session.name ?? String(session.pid), sessionId: session.sessionId, cwd: session.cwd, entrypoint: session.entrypoint, waitSec: wait,
+        ...(delivery?.status === "interrupted" ? { pending: false, outcome: "unknown", waitEnded: true,
+          taskCancelled: false, retrySafe: false, nextAction: "inspect_existing_task_then_follow_up",
+          reason: delivery.reason, interruption: { reasonCode: delivery.reasonCode, source: delivery.source,
+            observedAt: delivery.observedAt, entryIds: delivery.interruptedBy, backgroundTaskIds: delivery.backgroundTaskIds } } : {}),
         ...(selectedAccounts ? { accountContext: selectedAccounts, rediscovered: target === "auto" || ![session.name, String(session.pid), session.sessionId].includes(target) } : {}),
         ...(desktop ? { taskId: session.desktop.taskId, title: session.desktop.title, approvalUi: "unverified", recipientPermissionMode: session.desktop.permissionMode ?? null, recipientPermissionClass: session.desktop.permissionClass ?? null, recipientInboundPolicy: session.inbound?.value ?? null } : {}),
         ...(sender ? { senderMode: sender.mode, senderApprovalPolicy: sender.approvalPolicy, senderThreadId: sender.threadId, senderTurnId: sender.turnId, senderReview: sender.review } : {}),
@@ -543,6 +571,10 @@ registerTool(
       }
       const targetLabel = `${session.desktop?.title ?? session.name ?? session.pid} (pid ${session.pid}, session ${session.sessionId ?? "?"}, via ${session.entrypoint ?? "unknown"}, cwd ${session.cwd ?? "?"})`;
 
+      if (!reply && delivery?.status === "interrupted") {
+        return result(`Reply waiting ended for ${targetLabel} because a new conversation command interrupted the original request.\nMessage id: ${msgId}\nThe original task was not cancelled and its result remains unknown. Inspect that existing session/card, then send a scoped follow-up if needed. Do not resend the original action or create a replacement task. This is not a permission rejection.`, true);
+      }
+
       if (!reply && delivery && delivery.status !== "delivered") {
         const classes = desktop && sender ? `Recipient task mode: ${session.desktop.permissionMode ?? "unknown"}${session.desktop.permissionClass ? ` (${session.desktop.permissionClass} class)` : ""}; this sender attested ${sender.mode}.\n` : "";
         return result(`Claude inbox reported ${delivery.status} for ${targetLabel}.\n${delivery.reason}\n${classes}Message id: ${msgId}\nInspect read_claude_delivery with this message ID. Do not resend, change the sender permission class, or alter recipient permissions to bypass this receipt. The approval UI has not been verified; Claude Desktop declares no peer approval dialog, so do not tell the user an approval button exists without inspecting this exact Desktop task.`, true);
@@ -571,7 +603,7 @@ registerTool(
   "read_claude_delivery",
   {
     title: "Inspect a Claude message receipt without resending",
-    description: "Read the latest recipient control receipt or correlated reply for a message sent by this MCP process. Also accepts the 64-character requestId returned by target new to inspect creation without reopening. Unknown IDs do not prove non-delivery; retain the original receipt after a reconnect and inspect the existing Claude session before any resend.",
+    description: "Read the latest recipient control receipt or correlated reply for a message sent by this MCP process. An interrupted receipt ends only reply waiting: task outcome remains unknown and background work may still run. Inspect the existing task before any scoped follow-up; never resend the original action automatically. Ordinary timeouts remain pending. Also accepts the 64-character requestId returned by target new to inspect creation without reopening. Unknown IDs do not prove non-delivery; retain the original receipt after a reconnect and inspect the existing Claude session before any resend.",
     inputSchema: { msgId: z.string().describe("The original message ID returned by send_to_claude_session") },
     annotations: { readOnlyHint: true, openWorldHint: false },
   },
@@ -719,7 +751,8 @@ registerTool(
       const visibleInbox = peer.inbox.filter((record) => recordVisible(record, accounts));
       const visiblePending = [...peer.pendingMessages.keys()].filter((id) => readReceipt(id));
       const visibleForwarding = replyForwarder.status((record) => recordVisible(record, accounts));
-      const sender = desktopOnly ? readCodexSenderContext(extra?._meta) : null;
+      const sender = desktopOnly ? await readSender(extra?._meta) : null;
+      const projectPolicy = rootPolicy.status?.(sender?.status === "verified" ? sender.cwd : undefined);
       const lines = [
         `platform:      ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
         `bridge:        claude-bridge ${VERSION}`,
@@ -731,6 +764,7 @@ registerTool(
         ...(sender?.permissionProfile ? [`sender permission profile: ${sender.permissionProfile}`, `sender approval reviewer: ${sender.approvalsReviewer}`] : []),
         ...(sender?.review ? [`sender auto review: ${sender.review.autoReview}`, `sender Node REPL review: ${sender.review.nodeReplReview}`] : []),
         `session policy: ${desktopOnly ? "desktop-only" : "all Claude Code entrypoints"}`,
+        ...(projectPolicy ? [`project policy: ${projectPolicy.file}; ${projectPolicy.error ?? `${projectPolicy.grants} grants, ${projectPolicy.denies} revocations; live per operation`}`] : []),
         `Claude account: ${accounts.claude.status}${accounts.claude.fingerprint ? ` (${accounts.claude.fingerprint.slice(0, 12)})` : ` - ${accounts.claude.reason}`}`,
         `Codex account: ${accounts.codex.status}${accounts.codex.fingerprint ? ` (${accounts.codex.fingerprint.slice(0, 12)})` : ` - ${accounts.codex.reason}`}`,
         `live sessions: ${eligible.length}`,
@@ -745,7 +779,7 @@ registerTool(
       ];
       const state = runtime.status();
       lines.push(`runtime pid:   ${state.pid}`, `loaded source: ${state.revision}`, `disk source:   ${state.diskRevision ?? "unreadable"}`, `runtime state: ${state.current ? "current" : `STALE - ${state.reason}; reconnect this MCP server in the existing task`}`);
-      return { ...textResult(lines.join("\n"), !state.current), structuredContent: { runtime: state, accounts: { claude: publicAccountState(accounts.claude), codex: publicAccountState(accounts.codex) }, discovery, replyForwarding: visibleForwarding, ...(sender ? { sender } : {}) } };
+      return { ...textResult(lines.join("\n"), !state.current || Boolean(projectPolicy?.error)), structuredContent: { runtime: state, accounts: { claude: publicAccountState(accounts.claude), codex: publicAccountState(accounts.codex) }, discovery, replyForwarding: visibleForwarding, ...(projectPolicy ? { projectPolicy } : {}), ...(sender ? { sender } : {}) } };
     } catch (err) {
       return failure(err);
     }

package/src/claude-code-registration.mjs

@@ -0,0 +1,54 @@
+import path from "node:path";
+
+function worker(entry) {
+  return entry?.args?.length === 2 && path.basename(entry.args[0]) === "mcp-supervisor.mjs" && entry.args[1] === "index.mjs";
+}
+const stable = (value) => JSON.stringify(value, Object.keys(value ?? {}).sort());
+
+export function planCodeRegistration({ code, desktop, policyFile, name = "codex-bridge" }) {
+  if (!path.isAbsolute(policyFile)) throw new Error("Shared project policy path must be absolute");
+  const source = code.mcpServers?.[name];
+  if (!worker(source)) throw new Error(`Expected an existing supervised ${name} Code registration; no configuration was changed`);
+  if (source.env?.CODEX_BRIDGE_HARDENED === "1") throw new Error("Keep the hardened installation's pinned roots; automatic policy migration is not supported");
+  const updated = structuredClone(code);
+  const updatedDesktop = structuredClone(desktop);
+  const replacement = { ...source, env: { ...source.env, CODEX_BRIDGE_PROJECT_POLICY: policyFile } };
+  // The explicitly selected shared policy becomes the scope authority. Keep legacy
+  // roots intact for rollback, and preserve every other setting and restriction.
+  updated.mcpServers[name] = replacement;
+  const changes = [{ kind: "user-code-entry", name }];
+  const comparable = (entry) => {
+    const normalized = structuredClone(entry);
+    delete normalized.env?.CODEX_BRIDGE_ALLOWED_ROOTS;
+    delete normalized.env?.CODEX_BRIDGE_PROJECT_POLICY;
+    return JSON.stringify({ ...normalized, env: stable(normalized.env) });
+  };
+  for (const [project, config] of Object.entries(updated.projects ?? {})) {
+    for (const [alias, entry] of Object.entries(config.mcpServers ?? {})) {
+      if (!worker(entry) || path.resolve(entry.args[0]) !== path.resolve(source.args[0])) continue;
+      if (comparable(entry) !== comparable(source)) throw new Error(`Project ${project} has a customized ${alias} entry; review its settings instead of replacing it`);
+      delete config.mcpServers[alias];
+      changes.push({ kind: "remove-duplicate-project-entry", project, name: alias });
+    }
+  }
+  for (const [alias, entry] of Object.entries(updatedDesktop.mcpServers ?? {})) {
+    if (!worker(entry) || path.resolve(entry.args[0]) !== path.resolve(source.args[0])) continue;
+    if (comparable(entry) !== comparable(source)) throw new Error(`Shared Desktop entry ${alias} has customized settings; review it before migration`);
+    delete updatedDesktop.mcpServers[alias];
+    changes.push({ kind: "remove-shared-desktop-entry", name: alias });
+  }
+  return { code: updated, desktop: updatedDesktop, entry: replacement, changes };
+}
+
+export function checkCodeRegistration({ code, desktop, name = "codex-bridge" }) {
+  const entry = code.mcpServers?.[name];
+  const issues = [];
+  if (!worker(entry)) issues.push("User-level Claude Code bridge is missing or does not use the supervisor");
+  const shared = Object.keys(desktop.mcpServers ?? {}).filter((key) => worker(desktop.mcpServers[key]));
+  if (shared.length) issues.push(`Shared Desktop bridge entries can hide the Code caller identity: ${shared.join(", ")}`);
+  const overrides = Object.entries(code.projects ?? {}).flatMap(([project, config]) => Object.entries(config.mcpServers ?? {})
+    .filter(([, item]) => worker(item)).map(([alias]) => ({ project, alias })));
+  if (overrides.length) issues.push("Project-specific bridge entries override or duplicate the user-level registration");
+  if (!entry?.env?.CODEX_BRIDGE_PROJECT_POLICY) issues.push("No shared live project policy configured");
+  return { ready: issues.length === 0, issues, shared, overrides, policyFile: entry?.env?.CODEX_BRIDGE_PROJECT_POLICY ?? null };
+}