@minhspark/codex-mcp-bridge 1.27.0 → 1.27.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.27.0",
+  "version": "1.27.2",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.27.2] - 2026-11-05
+
+### Fixed
+
+- The native relay and the Antigravity sidecar now recover when an owner is killed between publishing its socket and removing the private name used to create it. That left the socket with a second hard link, which the safety check refused to remove, so every later start failed and `codex_bridge_status` kept reporting `RELAY_UNREACHABLE` with `ECONNREFUSED`, even after restarting Codex Desktop. Once a socket has refused a connection, a replacement removes only hard links of that same socket named like a private socket and owned by the same user. A socket with any other hard link is still refused, and a live owner that is confirmed by the probe is left alone. The removal is now bound to the socket that was probed, so an owner that replaces it during the probe keeps its socket. The native relay then retries, and the Antigravity sidecar start fails without touching that owner.
+
+### Verification and limits
+
+- Reproduced on macOS: Codex Desktop killed a relay companion that exceeded its 30-second startup limit under heavy load, and the relay stayed down until the extra link was removed by hand. Regression tests kill a real process inside that window, and also cover a live owner and a foreign hard link.
+- Private socket names left unlinked by earlier crashes stay in `~/.codex`. They are harmless and are not removed, because a live companion may be using a name of that form.
+- A running supervised companion loads the new version once idle and then recovers on its own; a companion without a supervisor needs its host to reconnect. This reload was checked with a test harness, not on a machine stuck in this state with live Codex Desktop.
+- In the native relay, a liveness probe that fails or times out under heavy load still counts as a dead owner. That existing limit is unchanged and now also covers an owner still inside the brief link step. The Antigravity sidecar treats a timeout as a live owner.
+- `codex-native-relay-install --remove` still stops with `Unsafe relay socket file` on a socket in this state. Starting a companion recovers it, or the leftover private name can be removed by hand.
+- Upgrade with `npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts`.
+
+## [1.27.1] - 2026-11-05
+
+### Fixed
+
+- `inspect_bridge_project` no longer reports `needs_setup` or recommends installing a project policy when the bridge process already authorizes the directory by another supported mode. `communicationAuthorization` now reports the effective `mode` and result for the calling process (`project-policy`, `allowed-roots`, `all-directories`, `pinned-roots`, `no-root-restriction`), and a new `projectPolicy` field reports the policy file separately. Installing a policy appears as `projectPolicy.optionalMigration` for an authorized directory unless policy mode is actually in force. A configured policy stays authoritative and still fails closed. Under thread policy `owned`, `existingTasks` and the detail state that existing tasks stay unreachable until they are allowlisted or the policy changes. `bridge-projects inspect` now reports `not_evaluated`, because it reads only the policy file. Hardened deployments can now be inspected through MCP without being prepared or migrated, and inspection of a directory outside their pinned roots returns only the refusal.
+- Inspection now marks the same-project and new-task checks as `not_checked` and explains that a grant or allowed root does not replace them. A directory outside the allowed roots asks for an owner decision instead of a policy.
+- `codex_bridge_status({cwd})` reports `authorizationMode`, `existingTasks` and, for a verified sender in the same project, `readiness.target.savedProject` (`matched`, `absent`, `rejected`, `ambiguous`, `unresolved`, `not_checked`) for creating a new Codex Desktop task. It checks the same resolved directory a delegation uses, so a mapped path can now report its resolved target. Outside hardened deployments this does not change `ready`, because sending to an existing task does not need a saved project. In `pinned-roots` mode every native operation needs one, so an unusable result makes `ready` false with `NATIVE_SCOPE_UNVERIFIED`. A refusal for a directory outside the allowed roots no longer points at the project policy.
+- A failed saved-project match now separates an absent project from one rejected for its kind, host or missing ID, and counts saved projects that could not be compared, with code `DESKTOP_PROJECT_UNMATCHED`. The message does not name other saved projects.
+
+### Verification and limits
+
+- Reproduced on v1.27.0 with `CODEX_BRIDGE_THREAD_POLICY=roots` and no policy: inspection said `needs_setup` while `codex_bridge_status` said `authorized=true` for the same directory.
+- Delivery enforcement is unchanged: authorization, same-project, receipt and project-match decisions make the same choices as before. Only diagnostics, one error code and the message text change. Without a policy, the Codex-to-Claude bridge has no directory allowlist and now says so.
+- The cause of the reported `No saved local Codex Desktop project` refusal is still unknown. The new status and message should narrow it down on the next occurrence; this release does not change which projects match.
+- Upgrade with `npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts`, then reconnect the MCP clients so they load the new version.
+
 ## [1.27.0] - 2026-11-05
 
 ### Added

package/docs/project-onboarding.md

@@ -102,6 +102,60 @@ node scripts/bridge-projects.mjs inspect /absolute/projects/example
 node scripts/bridge-projects.mjs prepare /absolute/projects/example
 ```
 
+Through MCP, the inspection reports what the calling bridge process actually
+enforces. Read `communicationAuthorization` for the effective result and
+`projectPolicy` for the state of the shared policy file:
+
+| `communicationAuthorization.mode` | Decided by | Policy needed for native delivery |
+|---|---|---|
+| `project-policy` | `CODEX_BRIDGE_PROJECT_POLICY` grants and revocations | Yes |
+| `allowed-roots` | `CODEX_BRIDGE_ALLOWED_ROOTS` in the Claude-to-Codex bridge | No |
+| `all-directories` | `CODEX_BRIDGE_ALLOWED_ROOTS` allowing every directory | No |
+| `pinned-roots` | A hardened deployment's pinned roots | Not accepted |
+| `no-root-restriction` | No directory allowlist in the Codex-to-Claude bridge | No |
+| `not_evaluated` | `bridge-projects inspect`, which reads only the policy file | Unknown |
+
+`status: "configured"` needs workspace trust and an authorized directory. A
+missing policy file becomes a prerequisite only in `project-policy` mode, where
+`nextActions` lists it. In the `allowed-roots`, `all-directories` and
+`no-root-restriction` modes, `projectPolicy.optionalMigration` describes an
+optional move to the shared policy for an authorized directory, which needs the
+user's request. Independent background workers keep their own explicit grant;
+check `worker_status` for them.
+
+An authorized directory does not always make existing tasks reachable. In the
+Claude-to-Codex bridge, `existingTasks: "owned-or-allowlisted"` means thread
+policy `owned` is in force: new tasks can be created, but tasks this bridge did
+not create need `CODEX_BRIDGE_THREAD_POLICY=roots` or an allowlisted thread ID.
+
+A hardened deployment can be inspected through MCP but not prepared or migrated.
+For a directory outside its pinned roots, inspection returns only the refusal.
+
+`liveChecks` stays `not_checked` because a saved configuration cannot prove a
+live caller. Claude-to-Codex delivery still requires the verified sender and
+destination to share a project, and neither a grant nor an allowed root replaces
+that. `codex_bridge_status({cwd})` checks it, and also reports
+`readiness.target.savedProject` for creating a new task:
+
+| `savedProject.status` | Meaning |
+|---|---|
+| `matched` | One eligible saved project has this exact directory |
+| `absent` | No saved project has this exact path |
+| `rejected` | A saved project has this path but its kind, host or ID makes it ineligible |
+| `ambiguous` | More than one eligible saved project has this path |
+| `unresolved` | The requested directory could not be resolved |
+| `not_checked` | The native project list was unavailable |
+
+The result is shown only after a verified sender and the destination are
+confirmed to share a project; otherwise it stays `not_checked`. The status checks
+the same resolved directory a delegation would use.
+
+Outside hardened deployments this status does not change `ready`, because sending
+to an existing task does not need a saved-project match. In `pinned-roots` mode
+every native operation needs one, so an unusable result makes `ready` false with
+`NATIVE_SCOPE_UNVERIFIED`. A failed creation reports the same reason with code
+`DESKTOP_PROJECT_UNMATCHED`, without naming other saved projects.
+
 Changes are backed up and verified. Concurrent changes abort; failed rollback
 returns `partial_needs_review` and remaining files. `configured` does not mean
 live communication passed. Project preparation does not approve tools, change

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.27.0",
+  "version": "1.27.2",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.27.0",
+  "version": "1.27.2",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.27.0";
+const VERSION = "1.27.2";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/antigravity-ipc.mjs

@@ -4,7 +4,7 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
-import { relayFileIdentity, removeRelayFile } from "./native-relay-files.mjs";
+import { releasePrivateSocketLinks, relayFileIdentity, removeRelayFile, staleSocketIdentity } from "./native-relay-files.mjs";
 import { bridgeDiagnostic } from "./recipient-preflight.mjs";
 
 const LIMIT = 2 * 1024 * 1024;
@@ -131,9 +131,12 @@ export async function serveAntigravityDesktop(handler, { directory = antigravity
       try { fs.linkSync(privatePath, socketPath); }
       catch (error) {
         if (error.code !== "EEXIST") throw error;
-        const existing = relayFileIdentity(socketPath, "socket");
-        if (!await socketRefused(socketPath)) throw new Error("Another Antigravity sidecar owns the socket");
-        removeRelayFile(socketPath, { expected: existing });
+        const existing = staleSocketIdentity(socketPath);
+        if (existing !== null) {
+          if (!await socketRefused(socketPath)) throw new Error("Another Antigravity sidecar owns the socket");
+          releasePrivateSocketLinks(socketPath, existing);
+          removeRelayFile(socketPath, { expected: existing });
+        }
         fs.linkSync(privatePath, socketPath);
       }
       fs.unlinkSync(privatePath);

package/src/bridge-readiness.mjs

@@ -1,6 +1,16 @@
 import { RELAY_DOWN_GUIDANCE } from "./thread-delivery.mjs";
 
-export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, nativeDiagnostic, verifyTargetProject }) {
+const SAVED_PROJECT_NOT_CHECKED = { status: "not_checked", detail: "The native project list was not available, so the exact saved project required to create a new task was not checked." };
+const SAVED_PROJECT_UNVERIFIED = { status: "not_checked", detail: "The saved project is shown only after a verified sender and this destination are confirmed to share a project." };
+const UNUSABLE_SAVED_PROJECT = new Set(["absent", "rejected", "ambiguous"]);
+
+function outOfScopeGuidance(scope) {
+  return scope?.status
+    ? "Authorize this project or its parent directory once in the shared project policy."
+    : "This bridge authorizes by CODEX_BRIDGE_ALLOWED_ROOTS. Ask the user whether this directory belongs in scope; never widen scope to work around a refusal.";
+}
+
+export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, nativeDiagnostic, verifyTargetProject, authorizationMode, existingTasks, savedProject }) {
   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;
@@ -11,7 +21,7 @@ export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = tr
       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." }); }
+    catch (error) { target = { cwd: targetCwd, authorized: false }; issues.push({ code: "TARGET_NOT_AUTHORIZED", detail: error.message, action: outOfScopeGuidance(scope) }); }
   }
   if (target?.authorized && sender?.status === "verified" && verifyTargetProject) {
     try { verifyTargetProject(sender.cwd, target.cwd); target.sameProject = true; }
@@ -20,6 +30,10 @@ export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = tr
       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 (target?.authorized) target.savedProject = sender?.status === "verified" && target.sameProject === true ? savedProject ?? SAVED_PROJECT_NOT_CHECKED : SAVED_PROJECT_UNVERIFIED;
+  if (authorizationMode === "pinned-roots" && UNUSABLE_SAVED_PROJECT.has(target?.savedProject?.status)) {
+    issues.push({ code: "NATIVE_SCOPE_UNVERIFIED", detail: target.savedProject.detail, action: "This hardened deployment requires exactly one saved local project at the task's directory for every native operation. Ask the user to save or correct that project; never change the destination to work around a refusal." });
+  }
   if (!nativeAvailable) issues.push({ code: nativeDiagnostic?.code ?? "RELAY_UNAVAILABLE", detail: nativeDiagnostic?.reason, action: RELAY_DOWN_GUIDANCE, ...(nativeDiagnostic ? { diagnostic: nativeDiagnostic } : {}) });
-  return { ready: issues.length === 0, readyScope: "transport-identity-and-project", hostToolPermission: "evaluated-by-client-at-call-time", sender, projectPolicy, target, issues };
+  return { ready: issues.length === 0, readyScope: "transport-identity-and-project", hostToolPermission: "evaluated-by-client-at-call-time", sender, ...(authorizationMode ? { authorizationMode } : {}), ...(existingTasks ? { existingTasks } : {}), projectPolicy, target, issues };
 }

package/src/claude-bridge.mjs

@@ -23,7 +23,7 @@ import { readClaudeAccountContext } from "./desktop-account-context.mjs";
 import { assertAccountIdentity, bindUnsolicitedClaudeMessageAccount, publicAccountState, readBridgeAccounts, requireBridgeAccounts, sameAccountIdentity } from "./bridge-account-context.mjs";
 import { recoverClaudeDesktopSession, resolveClaudeDesktopSession, sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
 import { submitClaudeCodeComposer, trustClaudeCodeComposer } from "./claude-composer-submit.mjs";
-import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
+import { createHardenedRootPolicy, rootPolicyAccessScope } from "./hardened-root-policy.mjs";
 import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 import { discoverClaudeProject } from "./claude-project-discovery.mjs";
@@ -31,7 +31,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.27.0";
+const VERSION = "1.27.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -349,7 +349,7 @@ function registerTool(name, definition, handler) {
 
 registerBackgroundTools(registerTool);
 
-registerProjectOnboardingTools(registerTool, { options: { policyRegistration: "codex" }, beforePrepare: async (extra) => {
+registerProjectOnboardingTools(registerTool, { options: { policyRegistration: "codex", evaluateAuthorization: (cwd) => rootPolicyAccessScope(rootPolicy, cwd) ?? { mode: "no-root-restriction", authorized: true } }, beforePrepare: async (extra) => {
   runtime.assertCurrent();
   if (!desktopOnly) throw new Error("Project onboarding requires a verified Desktop caller");
   await assertSender(extra?._meta);

package/src/hardened-root-policy.mjs

@@ -98,3 +98,9 @@ export function createHardenedRootPolicy(env = process.env) {
 }
 
 export function hardenedBridgeEnabled(env = process.env) { return enabled(env); }
+
+export function rootPolicyAccessScope(policy, cwd) {
+  if (policy.mode === "project-policy") return { mode: "project-policy", authorized: policy.allows(cwd) };
+  if (policy.enabled) return { mode: "pinned-roots", authorized: policy.allows(cwd) };
+  return null;
+}

package/src/index.mjs

@@ -44,7 +44,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.27.0";
+const VERSION = "1.27.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -533,7 +533,7 @@ registerDesktopReadTools(registerTool, {
   assertThreadAccess, normalizeThreadCwd, textResult, replyResult, failure,
 });
 
-registerProjectOnboardingTools(registerTool, { options: { policyRegistration: "claude-code" }, beforePrepare: async () => {
+registerProjectOnboardingTools(registerTool, { options: { policyRegistration: "claude-code", evaluateAuthorization: (cwd) => security.effectiveAccessScope(cwd) }, beforePrepare: async () => {
   if (!desktopTasksEnabled || !desktopOperation.getStore()?.caller) throw new Error("Project onboarding requires a verified Desktop caller.");
   await assertDesktopOperation(desktopOperation.getStore(), { verifyProcess: true });
 } });
@@ -1040,9 +1040,12 @@ registerTool(
   async ({ cwd }) => {
     const summary = security.summary();
     if (desktopTasksEnabled) {
-      const native = await desktopTasks.status();
+      const targetCwd = cwd ? resolveWorkspacePath(cwd).path : undefined;
+      const authorization = security.effectiveAccessScope(targetCwd);
+      const native = await desktopTasks.status({ cwd: targetCwd });
       const sender = await readClaudeSenderContext({ account: readBridgeAccounts().claude });
-      const readiness = bridgeReadiness({ sender, scope: security.hardenedRoots.mode === "project-policy" ? security.hardenedRoots : { assert: (candidate) => { security.assertCwd(candidate); return candidate; } }, targetCwd: cwd, nativeAvailable: native.available, nativeDiagnostic: native.diagnostic, verifyTargetProject: captureProjectScope });
+      const readiness = bridgeReadiness({ sender, scope: security.hardenedRoots.mode === "project-policy" ? security.hardenedRoots : { assert: (candidate) => { security.assertCwd(candidate); return candidate; } }, targetCwd, nativeAvailable: native.available, nativeDiagnostic: native.diagnostic, verifyTargetProject: captureProjectScope, authorizationMode: authorization.mode, existingTasks: authorization.existingTasks, savedProject: native.targetProject });
+      const { targetProject: _targetProject, ...nativeStatus } = native;
       return { ...textResult([
         `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
         `bridge version: ${VERSION}`,
@@ -1058,9 +1061,11 @@ registerTool(
         `claude desktop config: ${claudeDesktopConfigPath()}`,
         `sender context: ${sender.status}${sender.taskId ? `; task ${sender.taskId}` : ""}`,
         ...(readiness.projectPolicy ? [`project policy: ${readiness.projectPolicy.file}; revision ${readiness.projectPolicy.revision ?? "unavailable"}; changes apply on the next operation`] : []),
+        `authorization:  ${readiness.authorizationMode}; existing tasks ${readiness.existingTasks}`,
         ...(readiness.target ? [`target: ${readiness.target.cwd}; authorized=${readiness.target.authorized}${readiness.target.authorizedBy ? `; via ${readiness.target.authorizedBy.kind} ${readiness.target.authorizedBy.path}` : ""}`] : []),
+        ...(readiness.target?.savedProject ? [`new task target: ${readiness.target.savedProject.status}; ${readiness.target.savedProject.detail}`] : []),
         ...readiness.issues.map((issue) => `${issue.code}: ${issue.detail ?? ""} ${issue.action}`),
-      ].join("\n"), !readiness.ready), structuredContent: { readiness, native, ...(native.diagnostic ? { diagnostic: native.diagnostic } : !readiness.ready ? { error: { code: readiness.issues[0]?.code, message: readiness.issues[0]?.detail } } : {}), projectScope: { enabled: true, policy: "verified-sender-same-project", match: "canonical-directory-or-git-repository", checkedBeforeMutation: true } } };
+      ].join("\n"), !readiness.ready), structuredContent: { readiness, native: nativeStatus, ...(native.diagnostic ? { diagnostic: native.diagnostic } : !readiness.ready ? { error: { code: readiness.issues[0]?.code, message: readiness.issues[0]?.detail } } : {}), projectScope: { enabled: true, policy: "verified-sender-same-project", match: "canonical-directory-or-git-repository", checkedBeforeMutation: true } } };
     }
     const up = await client.isServerUp();
     let liveThreads = null;

package/src/native-relay-companion.mjs

@@ -35,7 +35,7 @@ import { createRuntimeState } from "./runtime-state.mjs";
 import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
-import { removeRelayFile, relayFileIdentity, verifyRelaySocketMode } from "./native-relay-files.mjs";
+import { releasePrivateSocketLinks, removeRelayFile, relayFileIdentity, staleSocketIdentity, verifyRelaySocketMode } from "./native-relay-files.mjs";
 
 import { NativeCreationReceipts, creationIdValid } from "./native-creation-receipts.mjs";
 import { registerRemoteCodexTools } from "./remote-codex-tools.mjs";
@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.27.0";
+const VERSION = "1.27.2";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -565,9 +565,13 @@ export class RelaySocketServer {
         try { fs.linkSync(privatePath, this.socketPath); break; }
         catch (error) {
           if (error.code !== "EEXIST") throw error;
-          if (!replaceStale || attempt || await this.#socketIsLive()) throw new Error(`another native relay companion already owns ${this.socketPath}`);
+          if (!replaceStale || attempt) throw new Error(`another native relay companion already owns ${this.socketPath}`);
+          const stale = staleSocketIdentity(this.socketPath);
+          if (stale === null) continue;
+          if (await this.#socketIsLive()) throw new Error(`another native relay companion already owns ${this.socketPath}`);
           this.log(`removing the stale relay socket left at ${this.socketPath}`);
-          removeRelayFile(this.socketPath);
+          releasePrivateSocketLinks(this.socketPath, stale);
+          removeRelayFile(this.socketPath, { expected: stale });
         }
       }
       const identity = fs.lstatSync(this.socketPath, { bigint: true });

package/src/native-relay-files.mjs

@@ -17,6 +17,49 @@ export function relayFileIdentity(target, kind, expected) {
   return current;
 }
 
+const PRIVATE_SOCKET_LINK = /^\.[0-9a-f]{12}\.sock$/;
+
+const ownedSocket = (stat) => stat.isSocket() && (typeof process.getuid !== "function" || stat.uid === BigInt(process.getuid()));
+
+export function staleSocketIdentity(target) {
+  let root;
+  try { root = fs.realpathSync.native(path.dirname(target)); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  const file = path.resolve(root, path.basename(target));
+  if (!file.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`)) throw new Error("Relay file escaped its directory");
+  let current;
+  try { current = fs.lstatSync(file, { bigint: true }); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (!ownedSocket(current)) throw new Error(`Unsafe relay socket file: ${target}`);
+  return { dev: current.dev, ino: current.ino };
+}
+
+export function releasePrivateSocketLinks(target, expected) {
+  let root;
+  try { root = fs.realpathSync.native(path.dirname(target)); }
+  catch (error) { if (error.code === "ENOENT") return 0; throw error; }
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  const file = path.resolve(root, path.basename(target));
+  if (!file.startsWith(prefix)) throw new Error("Relay file escaped its directory");
+  let current;
+  try { current = fs.lstatSync(file, { bigint: true }); }
+  catch (error) { if (error.code === "ENOENT") return 0; throw error; }
+  if (current.nlink === 1n || !ownedSocket(current) || current.dev !== expected.dev || current.ino !== expected.ino) return 0;
+  let released = 0;
+  for (const name of fs.readdirSync(root)) {
+    if (!PRIVATE_SOCKET_LINK.test(name)) continue;
+    const link = path.resolve(root, name);
+    if (!link.startsWith(prefix)) continue;
+    let stat;
+    try { stat = fs.lstatSync(link, { bigint: true }); }
+    catch (error) { if (error.code === "ENOENT") continue; throw error; }
+    if (!ownedSocket(stat) || stat.dev !== current.dev || stat.ino !== current.ino) continue;
+    fs.unlinkSync(link);
+    released += 1;
+  }
+  return released;
+}
+
 export function removeRelayFile(target, { kind = "socket", directory = path.dirname(target), expected } = {}) {
   let root;
   try { root = fs.realpathSync.native(directory); }

package/src/project-onboarding-tools.mjs

@@ -12,7 +12,7 @@ export function registerProjectOnboardingTools(register, { beforePrepare, option
   const failed = error => ({ content: [{ type: "text", text: error.message }], isError: true, structuredContent: { onboarding: error.onboarding ?? { status: "failed", connection: { status: "not_tested", ready: null } } } });
   register("inspect_bridge_project", {
     title: "Check project onboarding",
-    description: "Read workspace trust and shared messaging authorization without changing files. Distinguishes configured files from untested live connections. Card extension authorization is a separate check. Does not send messages or create conversations.",
+    description: "Read workspace trust and this bridge process's effective messaging authorization without changing files. Reports the authorization mode separately from shared project-policy state; a missing policy is a prerequisite only when nextActions says so. Distinguishes configured files from untested live connections. Same-project and new-task checks are reported as not checked here. Card extension authorization is a separate check. Does not send messages or create conversations.",
     inputSchema: fields,
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
   }, async args => {

package/src/project-onboarding.mjs

@@ -9,8 +9,8 @@ const object = value => value && typeof value === "object" && !Array.isArray(val
 const samePath = (a, b) => path.relative(a, b) === "";
 const inside = (a, b) => { const r = path.relative(a, b); return r === "" || (!path.isAbsolute(r) && r !== ".." && !r.startsWith(`..${path.sep}`)); };
 
-export function onboardingPaths(env = process.env, { requirePolicy = true } = {}) {
-  if (env.CODEX_BRIDGE_HARDENED === "1") throw new Error("Project onboarding cannot change a hardened deployment's pinned roots.");
+export function onboardingPaths(env = process.env, { requirePolicy = true, allowHardened = false } = {}) {
+  if (env.CODEX_BRIDGE_HARDENED === "1" && !allowHardened) throw new Error("Project onboarding cannot change a hardened deployment's pinned roots.");
   const policyFile = env.CODEX_BRIDGE_PROJECT_POLICY && path.isAbsolute(env.CODEX_BRIDGE_PROJECT_POLICY) ? env.CODEX_BRIDGE_PROJECT_POLICY : null;
   if (!policyFile && requirePolicy) throw new Error("Configure the shared CODEX_BRIDGE_PROJECT_POLICY before onboarding projects.");
   const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
@@ -74,12 +74,12 @@ function loadPolicy(file, project, options, tolerant) {
 }
 
 function load(cwd, options, { inspect = false } = {}) {
-  const files = onboardingPaths(options.env, { requirePolicy: !inspect });
+  const files = onboardingPaths(options.env, { requirePolicy: !inspect, allowHardened: inspect && Boolean(options.evaluateAuthorization) });
   const project = target(cwd, { ...options, home: files.home });
   const configRaw = read(files.configFile);
   const config = parse(configRaw);
   const trust = trustEntry(config, project);
-  return { files, project, configRaw, config, trust, policyRegistration: options.policyRegistration, ...loadPolicy(files.policyFile, project, options, inspect) };
+  return { files, project, configRaw, config, trust, policyRegistration: options.policyRegistration, evaluateAuthorization: options.evaluateAuthorization, ...loadPolicy(files.policyFile, project, options, inspect) };
 }
 
 const POLICY_REGISTRATION = {
@@ -87,28 +87,96 @@ const POLICY_REGISTRATION = {
   codex: file => `register that file by running claude-mcp-bridge-install with CODEX_BRIDGE_PROJECT_POLICY="${file}" set, then restart Codex Desktop once so this MCP server loads it`,
 };
 
-function policyActions(state) {
-  if (!state.policyProblem) return [{ tool: "prepare_bridge_project", cwd: state.project.directory.path }];
+const AUTHORIZATION_MODE_DETAIL = {
+  "allowed-roots": "This bridge process authorizes native delivery by CODEX_BRIDGE_ALLOWED_ROOTS.",
+  "all-directories": "CODEX_BRIDGE_ALLOWED_ROOTS allows every directory in this bridge process.",
+  "pinned-roots": "This hardened deployment authorizes native delivery by its pinned CODEX_BRIDGE_ALLOWED_ROOTS.",
+  "no-root-restriction": "This bridge process applies no directory allowlist without a project policy; CODEX_BRIDGE_ALLOWED_ROOTS is not consulted here.",
+};
+
+const POLICY_FILE_ONLY = "This result reads only the policy file and does not show what a running bridge enforces. Use inspect_bridge_project in the calling session before treating it as a prerequisite.";
+const EXISTING_TASK_LIMIT = "Existing tasks this bridge did not create need CODEX_BRIDGE_THREAD_POLICY=roots or an allowlisted thread ID.";
+const OUTSIDE_SCOPE_ACTION = { setting: "CODEX_BRIDGE_ALLOWED_ROOTS", ownerDecision: true, then: "This directory is outside this bridge's authorized scope. Ask the user whether it belongs in scope; changing the bridge registration needs their decision and a reconnect. Never widen scope to work around a refusal." };
+const UNTESTED_CONNECTION = { status: "not_tested", ready: null, detail: "Saved configuration does not prove a live sender, target, tool permission or successful round trip." };
+const joinDetail = (...parts) => parts.filter(Boolean).join(" ");
+
+const LIVE_CHECKS = {
+  "claude-code": {
+    senderDestination: "Each native Codex Desktop delivery separately requires the verified Claude sender and the destination to share a directory or registered Git repository. A project grant or allowed root does not replace this. Check codex_bridge_status with this cwd in the calling session.",
+    creationTarget: "Creating a new Codex Desktop task separately requires exactly one saved local project at this exact directory. Check codex_bridge_status with this cwd.",
+    existingTasks: "Sending to an existing task does not need this match.",
+    pinnedExistingTasks: "In this hardened deployment, every native operation on an existing task needs the same match for that task's directory.",
+  },
+  codex: {
+    senderDestination: "Each Claude delivery separately verifies the Codex sender, the recipient session, its permission class and the accounts. A project grant does not replace these checks. Check claude_bridge_status in the calling task.",
+    creationTarget: "Creating a new Claude session is confirmed separately through read_claude_creation; this inspection does not open or check one.",
+  },
+};
+
+function communicationAuthorization(state) {
+  const file = state.files.policyFile;
+  const live = state.evaluateAuthorization?.(state.project.directory.path);
+  const threads = live?.existingTasks ? { threadPolicy: live.threadPolicy, existingTasks: live.existingTasks } : {};
+  const taskLimit = live?.existingTasks === "owned-or-allowlisted" ? EXISTING_TASK_LIMIT : "";
+  if (live && live.mode !== "project-policy") {
+    return { mode: live.mode, status: live.authorized ? "authorized" : "outside_allowed_roots", detail: joinDetail(AUTHORIZATION_MODE_DETAIL[live.mode], taskLimit), ...threads, file: null };
+  }
+  const decided = state.policyProblem ?? { status: state.authorized ? "authorized" : state.denials.length ? "revoked" : "missing" };
+  const detail = joinDetail(decided.detail, taskLimit, live ? "" : POLICY_FILE_ONLY);
+  return { mode: live?.mode ?? "not_evaluated", ...decided, ...(detail ? { detail } : {}), ...threads, file };
+}
+
+const usesPolicyForNativeDelivery = authorization => authorization.mode === "project-policy" || authorization.mode === "not_evaluated";
+
+function suggestedPolicySetup(state) {
   const suggestedFile = path.join(state.files.home, ".config", "GptClaudeBridge", "projects.json");
-  if (state.policyProblem.status === "policy_invalid") return [{ setting: "CODEX_BRIDGE_PROJECT_POLICY", file: state.files.policyFile, then: "Repair or restore this policy file from a backup; prepare_bridge_project does not overwrite an unreadable policy. Run inspect_bridge_project again afterwards." }];
   const registration = POLICY_REGISTRATION[state.policyRegistration ?? "claude-code"];
   if (!registration) throw new Error(`Unknown project policy registration: ${state.policyRegistration}`);
-  return [{ setting: "CODEX_BRIDGE_PROJECT_POLICY", suggestedFile, then: `Run bridge-projects prepare "${state.project.directory.path}" --file "${suggestedFile}", ${registration(suggestedFile)}. prepare_bridge_project is available once the setting is loaded.` }];
+  return { setting: "CODEX_BRIDGE_PROJECT_POLICY", suggestedFile, then: `Run bridge-projects prepare "${state.project.directory.path}" --file "${suggestedFile}", ${registration(suggestedFile)}. prepare_bridge_project is available once the setting is loaded.` };
+}
+
+function projectPolicyState(state, authorization) {
+  const status = state.policyProblem?.status === "policy_invalid" ? "invalid" : !state.files.policyFile ? "not_configured" : state.policyRaw === null ? "file_missing" : "configured";
+  const canMigrate = status === "not_configured" && authorization.status === "authorized" && !usesPolicyForNativeDelivery(authorization) && authorization.mode !== "pinned-roots";
+  return {
+    status,
+    file: state.files.policyFile,
+    requiredForNativeDelivery: authorization.mode === "not_evaluated" ? null : authorization.mode === "project-policy",
+    backgroundWorkers: "Independent background workers use their own explicit project grant; check worker_status for them.",
+    ...(canMigrate ? { optionalMigration: { ...suggestedPolicySetup(state), detail: "Optional configuration migration for a shared project policy. It is not needed to restore native communication and needs the user's request." } } : {}),
+  };
+}
+
+function policyActions(state) {
+  if (!state.policyProblem) return [{ tool: "prepare_bridge_project", cwd: state.project.directory.path }];
+  if (state.policyProblem.status === "policy_invalid") return [{ setting: "CODEX_BRIDGE_PROJECT_POLICY", file: state.files.policyFile, then: "Repair or restore this policy file from a backup; prepare_bridge_project does not overwrite an unreadable policy. Run inspect_bridge_project again afterwards." }];
+  return [suggestedPolicySetup(state)];
+}
+
+function setupActions(state, authorization) {
+  if (usesPolicyForNativeDelivery(authorization)) return policyActions(state);
+  return [
+    ...(authorization.status === "authorized" ? [] : [OUTSIDE_SCOPE_ACTION]),
+    ...(state.trust.trusted ? [] : [{ setting: "workspaceTrust", ownerDecision: true, then: "Claude has not recorded workspace trust for this project. Ask the user to open it in Claude Code and accept the trust prompt." }]),
+  ];
 }
 
 function report(state, taskCards, extra = {}) {
-  const configured = state.trust.trusted && state.authorized;
+  const authorization = communicationAuthorization(state);
+  const configured = state.trust.trusted && authorization.status === "authorized";
+  const liveChecks = LIVE_CHECKS[state.policyRegistration] ?? LIVE_CHECKS["claude-code"];
+  const existingTaskMatch = authorization.mode === "pinned-roots" ? liveChecks.pinnedExistingTasks : liveChecks.existingTasks;
   return {
     status: configured ? "configured" : "needs_setup",
     project: { cwd: state.project.directory.path, root: state.project.root.path, kind: state.project.repo ? "git" : "directory", repository: state.project.repo?.common.path ?? null },
     workspaceTrust: { status: state.trust.trusted ? "configured" : "missing", file: state.files.configFile, key: state.trust.key },
-    communicationAuthorization: state.policyProblem
-      ? { ...state.policyProblem, file: state.files.policyFile }
-      : { status: state.authorized ? "authorized" : state.denials.length ? "revoked" : "missing", file: state.files.policyFile },
-    connection: { status: "not_tested", ready: null, detail: "Saved configuration does not prove a live sender, target, tool permission or successful round trip." },
+    communicationAuthorization: authorization,
+    projectPolicy: projectPolicyState(state, authorization),
+    connection: UNTESTED_CONNECTION,
+    liveChecks: { senderDestination: { status: "not_checked", detail: liveChecks.senderDestination }, creationTarget: { status: "not_checked", detail: joinDetail(liveChecks.creationTarget, existingTaskMatch) } },
     taskCards: { status: taskCards ? "requires_extension_check" : "not_requested", detail: "The card extension owns its authorization and connection; this tool does not edit its settings or restart it." },
     nextActions: [
-      ...(!configured ? policyActions(state) : []),
+      ...(!configured ? setupActions(state, authorization) : []),
       ...(taskCards ? [{ component: "Local Card Bridge Desktop", tool: "list_projects", cwd: state.project.root.path, then: "If absent, use authorize_project for this exact project under the user's onboarding request; verify desktop_bridge_info after saving. Stop on any denial or disconnected extension." }] : []),
       { tools: ["claude_bridge_status", "codex_bridge_status"], then: "Check in the actual calling sessions, then perform one authorized round trip in each direction. Do not create a new conversation without user authorization." },
     ],
@@ -116,7 +184,18 @@ function report(state, taskCards, extra = {}) {
   };
 }
 
+function outsidePinnedRoots() {
+  return {
+    status: "needs_setup",
+    communicationAuthorization: { mode: "pinned-roots", status: "outside_allowed_roots", detail: AUTHORIZATION_MODE_DETAIL["pinned-roots"], file: null },
+    connection: UNTESTED_CONNECTION,
+    nextActions: [OUTSIDE_SCOPE_ACTION],
+  };
+}
+
 export function inspectBridgeProject({ cwd, taskCards = false }, options = {}) {
+  const requested = options.evaluateAuthorization?.(cwd);
+  if (requested?.mode === "pinned-roots" && !requested.authorized) return outsidePinnedRoots();
   return report(load(cwd, options, { inspect: true }), taskCards);
 }
 

package/src/security-policy.mjs

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import path from "node:path";
-import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
+import { createHardenedRootPolicy, rootPolicyAccessScope } from "./hardened-root-policy.mjs";
 
 const APPROVAL_POLICIES = new Set(["untrusted", "on-failure", "on-request", "never"]);
 const SANDBOXES = new Set(["read-only", "workspace-write", "danger-full-access"]);
@@ -211,6 +211,13 @@ export class BridgeSecurityPolicy {
     throw new Error(`Working directory is outside CODEX_BRIDGE_ALLOWED_ROOTS: ${cwd}`);
   }
 
+  effectiveAccessScope(cwd) {
+    const threads = { threadPolicy: this.threadPolicy, existingTasks: this.allowAllThreads || this.threadPolicy === "roots" ? "in-scope" : "owned-or-allowlisted" };
+    const pinned = rootPolicyAccessScope(this.hardenedRoots, cwd);
+    if (pinned) return { ...pinned, ...threads };
+    return { mode: this.allowAllRoots ? "all-directories" : "allowed-roots", authorized: this.isCwdAuthorized(cwd), ...threads };
+  }
+
   summary() {
     const projectPolicy = this.hardenedRoots.mode === "project-policy" ? this.hardenedRoots.status() : null;
     return {

package/src/thread-delivery.mjs

@@ -57,22 +57,62 @@ function sameAccountContext(expected, current) {
     typeof expected[provider] === "string" && expected[provider] === current[provider]));
 }
 
-export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
+const PROJECT_REJECTION_TEXT = { kind: "its project kind is not local", host: "its host is not local", metadata: "its project ID is missing" };
+
+const projectRejections = (project) => [
+  project.projectKind !== "local" && "kind",
+  project.hostId !== "local" && "host",
+  !project.projectId && "metadata",
+].filter(Boolean);
+
+export function classifyDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
   const requested = canonicalize(cwd);
-  const matches = projects.filter((project) => {
-    if (project.projectKind !== "local" || project.hostId !== "local" || !project.path || !project.projectId) return false;
-    try {
-      return paths.relative(requested, canonicalize(project.path)) === "";
-    } catch {
-      return false;
+  const eligible = [];
+  const rejected = new Set();
+  let uncomparable = 0;
+  for (const project of projects) {
+    const remote = (project?.projectKind && project.projectKind !== "local") || (project?.hostId && project.hostId !== "local");
+    let saved = null;
+    if (typeof project?.path === "string" && project.path) {
+      try { saved = canonicalize(project.path); }
+      catch { saved = remote ? project.path : null; }
+    }
+    if (saved === null) {
+      if (!remote) uncomparable += 1;
+      continue;
     }
-  });
-  if (matches.length !== 1) {
-    throw new Error(matches.length
-      ? `Multiple Codex Desktop projects match ${cwd}; keep one saved project for this directory before delegating.`
-      : `No saved local Codex Desktop project exactly matches ${cwd}. Choose an existing saved project's directory or continue an existing task in this workspace. The bridge will not create a project or substitute a different directory.`);
+    if (paths.relative(requested, saved) !== "") continue;
+    const reasons = projectRejections(project);
+    if (reasons.length) reasons.forEach((reason) => rejected.add(reason));
+    else eligible.push(project);
   }
-  return matches[0];
+  if (eligible.length === 1) return { status: "matched", project: eligible[0], reasons: [], uncomparable };
+  if (eligible.length) return { status: "ambiguous", reasons: [], uncomparable };
+  return { status: rejected.size ? "rejected" : "absent", reasons: [...rejected], uncomparable };
+}
+
+function describeProjectMatch({ status, reasons, uncomparable }) {
+  if (status === "matched") return "One saved local project matches this exact directory.";
+  if (status === "ambiguous") return "More than one saved local project matches this exact directory.";
+  const uncompared = uncomparable ? ` ${uncomparable} saved project${uncomparable === 1 ? " was" : "s were"} not compared because the saved path is missing or no longer resolves.` : "";
+  if (status === "rejected") return `A saved project has this exact path but is not eligible: ${reasons.map((reason) => PROJECT_REJECTION_TEXT[reason]).join(", ")}.${uncompared}`;
+  return `No saved project has this exact path.${uncompared}`;
+}
+
+export function savedProjectStatus(projects, cwd, options) {
+  let match;
+  try { match = classifyDesktopProject(projects, cwd, options); }
+  catch { return { status: "unresolved", reasons: [], uncomparable: 0, detail: "The requested directory could not be resolved, so its saved project was not checked." }; }
+  const { project, ...summary } = match;
+  return { ...summary, ...(project ? { projectId: project.projectId } : {}), detail: describeProjectMatch(match) };
+}
+
+export function matchDesktopProject(projects, cwd, options) {
+  const match = classifyDesktopProject(projects, cwd, options);
+  if (match.status === "matched") return match.project;
+  throw Object.assign(new Error(match.status === "ambiguous"
+    ? `Multiple Codex Desktop projects match ${cwd}; keep one saved project for this directory before delegating.`
+    : `No saved local Codex Desktop project exactly matches ${cwd}. ${describeProjectMatch(match)} Choose an existing saved project's directory or continue an existing task in this workspace. The bridge will not create a project or substitute a different directory.`), { code: "DESKTOP_PROJECT_UNMATCHED", projectMatch: { status: match.status, reasons: match.reasons, uncomparable: match.uncomparable } });
 }
 
 export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening after waiting for silent recovery. Its Desktop-owned supervisor restarts crashed relay workers without replaying requests. An unloaded native host cannot be cold-started by this bridge. Inspect codex_bridge_status and include its diagnostic in a report. Never open an app or an old, new, empty or failed chat to load a relay.";
@@ -194,7 +234,7 @@ export class DesktopTaskDelivery {
     }
   }
 
-  async status() {
+  async status({ cwd } = {}) {
     const accountContext = this.accountContext?.();
     const socketPath = this.relay.status?.({ accountContext })?.socketPath ?? this.relay.socketPath;
     if (this.accountContext && !accountContext) {
@@ -204,7 +244,7 @@ export class DesktopTaskDelivery {
     try {
       const response = await this.request("list_projects", {});
       if (!Array.isArray(response?.projects)) throw new Error("Desktop returned no project list");
-      return { available: true, socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
+      return { available: true, socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length, ...(cwd ? { targetProject: savedProjectStatus(response.projects, cwd) } : {}) };
     } catch (err) {
       const diagnostic = bridgeDiagnostic(err, { component: "codex-bridge", operation: "codex_bridge_status", readOnly: true });
       return { available: false, socketPath, code: diagnostic.code, reason: err.message, diagnostic };