@minhspark/codex-mcp-bridge 1.20.1 → 1.21.0

package/docs/desktop-handoff-design.md

@@ -0,0 +1,180 @@
+# Desktop handoff recovery and project onboarding
+
+This follow-up is based on upstream `00730b6` (1.19.6). PR #84 is already
+merged and is not being resubmitted. Its historical validation record remains
+dated; the maintainer's managed-permission implementation takes precedence.
+
+## Problems addressed
+
+| Trigger | Result before this change | Recovery/behavior in this branch |
+| --- | --- | --- |
+| A long Desktop conversation exceeds a whole-file read limit or rotates into continuation files | Sender verification or final-response collection becomes unavailable | Bounded per-record streaming, exact-ID segment discovery and active-turn/native identity checks |
+| A native Desktop send is accepted but its first wait expires | The caller cannot continue the same reply observation after reconnecting | An owner/account-bound `deliveryId` and `wait_codex_reply`; no second send |
+| A confirmed creation uses up the first-call budget, or a follow-up acknowledgement arrives late | The reply exists but no continuation ID reaches Claude | Preserve the original creation or pre-send binding, distinguish unconfirmed delivery, and continue observing without another send |
+| Claude finishes a background command after an interim answer | The interim answer may be mistaken for the final report | Correlate the originating tool, background task and native completion notification |
+| A new conversation command interrupts the reply chain | An old pending observation blocks later handoffs indefinitely | Return `interrupted`, `pending=false`, with task outcome explicitly unknown; inspect existing work before a follow-up |
+| Read(image) adds a native `turnCompanion` record | A user-role image-size annotation breaks reply ancestry even though Claude already replied | Follow only companions with matching session, prompt and Read/image-result ancestry; preserve real user boundaries |
+| Native `create_thread` creates a dedicated dispatcher | `agent_created_thread` is rejected as though it were a transient subagent | Require independent, account-bound Desktop ownership and exact active-turn proof, then re-read that task's own permissions |
+| New projects need multiple copied connection settings | Generic Desktop processes cannot attest their actual Code caller, and grants drift between entries | Explicit user-level Code registration, a shared live project policy and diagnostic onboarding tools |
+
+## Integration with current upstream
+
+The existing upstream permission classifier, managed-policy diagnostics and
+opt-in Full access repair implementation are retained. This contribution does
+not enable Full access repair or change a user's installed permission mode.
+
+Two modules serve different purposes:
+
+- Upstream `project-scope.mjs` is unchanged: it binds the verified Claude sender
+  and Codex destination to the same canonical directory or registered Git
+  repository, and detects replacement before a native mutation.
+- New `project-policy.mjs` stores explicit project/parent grants and denials.
+  It is optional; when configured, both that policy and the upstream binding
+  must pass. A grant for two unrelated repositories does not permit a
+  cross-project Claude-to-Codex handoff.
+
+The authorization module was renamed during integration because both branches
+had independently introduced `project-scope.mjs`. Both sets of tests are kept.
+Native creation, sends and renames retain the upstream before-write project
+checks and additionally recheck a captured live policy grant. Diagnostic
+readiness also reports a sender/destination mismatch even when both paths are
+authorized. MCP tool approval is still evaluated separately by the host.
+
+## Deliberate boundaries
+
+Identity comes from host metadata, local records and native account-bound
+inspection, not from claims in a message. `agent_created_thread` support is
+limited to the measured Desktop origin; unknown sources and transient
+subagents remain unsupported. The permission class is always the sending
+task's current class, never a parent's class.
+
+An interrupted wait is not a cancellation or a successful task result. Timeout,
+unreadable records and unknown transcript formats do not silently discard
+pending ownership. Image companions are recognized through bounded ancestry,
+not by matching an image-size sentence. Forged companions, unrelated tools,
+different sessions/prompts, failed image results and real human interruptions
+have negative regression cases.
+
+Project setup is explicit and backed up. The messaging-automation installer is
+preview-only unless the user opts in, permits only the exact send/wait tools,
+and refuses conflicting ask/deny rules. The optional card-settings adapter
+does not require the card extension for communication or merge card and
+communication permissions. The separate card extension binary is not shipped
+by this PR.
+
+## Validation and limits
+
+Run the full isolated regression suite with:
+
+```sh
+node --test --test-concurrency=2
+```
+
+The merge retains upstream mismatch, moved-target, replaced-directory and
+managed-policy negative tests. Additional integration cases combine live
+revocation with same-project enforcement and confirm that authorized unrelated
+repositories fail readiness while registered worktrees pass.
+
+Earlier installed Windows builds completed two-way Desktop handoffs and
+accepted-timeout continuation without a resend. The latest image-companion fix
+passed 62 peer tests and recovered the exact historical reply in an offline
+replay of the affected transcript, including pending-release and reload checks.
+Raw transcripts, identifiers, hashes and machine paths are not published.
+
+That offline replay is not a claim that the old live worker recovered. A worker
+already stuck on an unrecognized pending record can defer hot reload until it
+is reconnected. Preserve the original receipt and inspect the existing task
+first; an unknown ID after reconnecting never proves non-delivery. The merged
+1.19.6 branch has not yet replaced the installed runtime or completed a new
+live Desktop round trip. No second-machine or cross-platform live acceptance
+is claimed; upstream CI should validate the supported platforms.
+
+### Merged-branch Windows check (2026-10-02)
+
+Node 24.13.0, `node --test --test-concurrency=2`: **1,000 tests,
+986 passed, 2 failed, 12 skipped**, approximately 903 seconds. The Windows
+pipe ACL checks ran successfully with `RemoteSigned` scoped only to the test
+process; machine/account policy and assertions were unchanged. All messaging,
+sender, project-binding and revocation checks passed.
+
+Both failures were existing installer cases reaching their unchanged 60-second
+deadline: explicit Full access setup and cross-machine defaults. A focused
+repeat of the installer, messaging-automation and repository-hygiene suites
+gave **28 passed, the same 2 timeouts**, after the final documentation/package
+and language-guidance edits. This is not a clean full-suite pass.
+
+A control run on untouched upstream `00730b6`, with freshly installed locked
+dependencies and only those two test names selected, reproduced **both**
+60-second timeouts (~125 seconds total). Thus the failures reproduce without
+this contribution on this machine; their underlying cause remains undiagnosed.
+No test deadline was increased and no failing case was skipped.
+
+`npm pack --dry-run --json --ignore-scripts` includes the English guides and
+excludes local acceptance artifacts. `git diff --check` passes. The standalone
+Desktop health check discovers tools and the existing native relay, then
+returns `SENDER_UNVERIFIED` as expected for a terminal process with no Claude
+Code ancestry. It does not substitute a sender or start an external app-server.
+
+### Path-alias CI fixes (2026-10-03)
+
+The first CI run exposed path aliases on macOS (`/var` versus `/private/var`)
+and Windows (short versus long temporary-directory names). The card-settings
+adapter compared page paths literally against canonical policy paths, so
+removing a displayed project or parent could leave its grant in place. It now
+canonicalizes page paths, including missing projects via their nearest existing
+ancestor, before reconciliation. Exclusions and concurrent-change checks remain
+in force. Onboarding also canonicalizes the configured home before rejecting
+whole-home trust requests.
+
+Continuation/sender tests now expect the canonical paths returned by rollout
+discovery. They still check exact file and turn identity; no production sender
+check was relaxed. New directory-alias regressions exercise project revocation,
+parent removal, deleted-project exclusions and home-root rejection on Windows
+junctions and POSIX symlinks. The focused Windows run passed 102 checks with one
+existing platform skip. Fresh installation and bidirectional live acceptance
+remain separate from these isolated tests.
+
+The full Windows run at `989ed6c` completed with **989 passed, 2 failed and
+12 skipped** (1,003 tests). Both failures remain the same installer cases
+reaching the unchanged 60-second deadline described above. The standalone
+health check listed tools but could not reach the default native relay and
+reported an unverified sender from the terminal; it did not send a message,
+change permissions or launch an external app-server.
+
+Upstream subsequently advanced to `e0f40b5` (1.20.1), making the PR conflicted
+and preventing a fresh pull-request CI run. The merge preserves upstream's
+composer submission, dormant-task recovery, Sites connector and dependency
+updates. Creation and recovery callbacks still await this branch's asynchronous
+sender verification before any UI action. A regression checks rejection both
+before opening and between opening and automatic trust/submission. No installed
+runtime or client configuration was replaced for this merge.
+
+
+### Native creation acknowledgement continuation
+
+Local Desktop creation probes the companion's `get_creation_receipt` capability
+before mutation. An older companion refuses the probe before a task is created;
+reload both installed workers after upgrading. Hosted callers retain their
+existing creation contract and receive no local observation binding.
+
+The caller persists an owner/account-bound delivery ID before dispatch. The
+companion reserves a separate unpredictable native receipt ID with the exact
+creation arguments, their canonical hash, accounts and executor. It keeps the
+result after the caller socket times out. `wait_codex_reply` queries that receipt
+without another creation and verifies current accounts, project scope, the native
+task directory and the exact initial creation response before releasing text.
+The companion authenticates every persisted receipt field with HMAC-SHA256.
+Its 32-byte signing key lives in the separate `bridge-native-creation-authority`
+directory beside the receipt store, with owner-only permissions or a protected
+Windows ACL. Altered, unsigned legacy receipts and missing, replaced or unsafe
+keys fail closed before any ownership is restored. The key is never returned
+to callers. Existing live account, executor and project checks still apply.
+
+Duplicate native receipt IDs never dispatch again. A prompt edited on retry
+cannot replace the original observation binding.
+
+This is recovery of a late acknowledgement, not reconstruction by title or by
+scanning unrelated conversations. If the native operation itself never confirms,
+or the companion crashes before persisting its result, the outcome remains
+unknown and automatic re-creation remains blocked. Receipts made by earlier
+versions without this binding cannot be retroactively recovered by guessing.

package/docs/new-machine-setup.md

@@ -0,0 +1,112 @@
+# New-machine setup and initial permissions
+
+This is a Windows local Desktop source-install guide, not evidence of testing
+on a second machine. Use a pinned source revision containing these scripts;
+published npm versions may not yet include this branch. The optional card
+extension is distributed separately. Keep the source in a stable directory.
+
+Install/sign in to Codex Desktop and Claude Desktop; install Node 22+ and Git,
+and make the Codex CLI available. Record the source revision and optional MCPB
+version/hash. Do not copy login caches, old session identities, unfinished
+receipts or directory-identity grants from another machine.
+
+## Three messaging entries
+
+| Client | Entry | Purpose |
+| --- | --- | --- |
+| Codex | `claude-bridge` | Send to Claude and observe replies |
+| Codex | `codex-native-relay` | Deliver Claude requests through the Desktop host |
+| Claude Code, user scope | `codex-bridge` | Send to Codex and continue reply observation |
+
+Begin with one dedicated test directory and explicitly grant it:
+
+```powershell
+node scripts/bridge-projects.mjs allow-project 'C:\Projects\BridgeTest'
+```
+
+Merge a user-level Claude Code entry, replacing placeholder paths with actual
+absolute paths and preserving unrelated settings:
+
+```json
+{
+  "mcpServers": {
+    "codex-bridge": {
+      "command": "C:/Tools/nodejs/node.exe",
+      "args": ["C:/Tools/GptClaudeBridge/src/mcp-supervisor.mjs", "index.mjs"],
+      "env": {
+        "CODEX_BIN": "C:/Tools/Codex/codex.exe",
+        "CODEX_BRIDGE_DESKTOP_TASKS": "1",
+        "CODEX_BRIDGE_AUTOSTART": "0",
+        "CODEX_BRIDGE_PROJECT_POLICY": "C:/Users/<user>/.config/GptClaudeBridge/projects.json",
+        "CODEX_BRIDGE_ALLOWED_ROOTS": "C:/Projects/BridgeTest",
+        "CODEX_BRIDGE_THREAD_POLICY": "roots",
+        "CODEX_BRIDGE_APPROVAL_POLICY": "on-request",
+        "CODEX_BRIDGE_SANDBOX": "workspace-write"
+      }
+    }
+  }
+}
+```
+
+Then run `node scripts/install-claude-code.mjs --check`. That helper migrates or
+checks an existing supervised entry; it does not create a first entry from
+nothing. See [project onboarding](project-onboarding.md) for migration.
+
+Configure the same policy for Codex using the repository installers:
+
+```powershell
+$env:CODEX_BRIDGE_PROJECT_POLICY = Join-Path $env:USERPROFILE '.config\GptClaudeBridge\projects.json'
+$env:CODEX_BRIDGE_DESKTOP_TASKS = '1'
+node scripts/install-native-relay.mjs
+node scripts/install-codex-mcp.mjs
+```
+
+If discovery fails, set `CODEX_EXE` to the real CLI executable. Relay setup may
+create an initial relay task. Do not add a permission-bypass mode. If CC Switch
+manages the entries, save the same configuration there. Reload affected clients
+and inspect the tools inside the actual Code/dispatch conversations.
+
+## Permissions are separate
+
+- Prepare workspace trust for the explicitly selected project using
+  `prepare_bridge_project`; verify with `inspect_bridge_project`.
+- Grant specific communication projects or parents, not all local projects by
+  default. A card extension's grants are separate. Denials take precedence.
+- If the user opts into automatic messaging, preview and apply
+  `configure-message-automation.mjs` as described in the onboarding guide. It
+  permits only the exact send/wait tools and preserves other host checks.
+
+If card management is wanted, select its precise tools independently in the
+actual Code permission configuration. Do not assume ordinary-chat connector
+settings apply to Code, or that a query/authorization allow rule includes card
+startup, cleanup or permanent deletion. `ready=true` is not host approval.
+
+For a compatible optional card extension, install its MCPB and run
+`node scripts/bridge-projects.mjs register-card-settings`. Verify separate card
+and communication lists in its original settings page. Do not edit Claude's
+private settings file to force a UI refresh. A local launcher using
+`--disable-backgrounding-occluded-windows --disable-renderer-backgrounding`
+helped background card redraw on the measured machine, but must be retested on
+each client build. Remote Control is not required.
+
+## One small end-to-end acceptance
+
+Create one Claude collaboration parent from the intended Code project sidebar
+and verify its real cwd first; see [daily handoffs](daily-handoffs.md).
+
+1. Check both identities, target projects and normal tool permissions.
+2. Send Codex-to-Claude and automatically receive the exact complete answer.
+3. Send Claude-to-Codex; also test one accepted timeout followed by automatic
+   continuation with the same receipt and no second send.
+4. In the authorized test directory, create, read back and delete one clearly
+   named test file. Respect normal file-operation approval.
+5. If using cards, verify local and worktree startup, parent/child identity,
+   directory, branch, Remote Control off and no duplicate on repeated startup.
+6. Revoke and restore test-only card authorization, checking UI and effective
+   state while communication grants remain unchanged. Run another normal task.
+
+Record incomplete steps instead of calling tool discovery a full pass. Before
+upgrading, back up configuration and receipts without publishing personal data.
+Archive historical files with an inventory; verify dependencies and unique
+worktree changes before deletion. Conversation archival does not prove that
+its checkout or branch was removed.

package/docs/project-onboarding.md

@@ -0,0 +1,122 @@
+# Project onboarding and shared authorization
+
+Both bridge directions can read the same optional policy file via
+`CODEX_BRIDGE_PROJECT_POLICY`. `bridge-projects` defaults to
+`~/.config/GptClaudeBridge/projects.json`. A shared home-directory path avoids
+different AppData views in packaged Windows applications. The policy stores
+canonical directory identities; do not copy it to a new machine as proof of
+authorization there.
+
+```sh
+node scripts/bridge-projects.mjs allow-project /absolute/projects/example
+node scripts/bridge-projects.mjs allow-parent /absolute/projects
+node scripts/bridge-projects.mjs revoke /absolute/projects/example
+node scripts/bridge-projects.mjs list
+node scripts/bridge-projects.mjs check /absolute/projects/example
+```
+
+A registered worktree inherits a grant for its repository, including when its
+directory is outside the granted parent. Denials beat parent grants and require
+explicit reauthorization. Revocation affects subsequent operations, not work
+already dispatched. Invalid/missing configured policies fail closed.
+
+Project grants bind both the project directory and its verified common Git
+directory. Revocation preserves repository and registered worktree path
+denials even when the original directory or Git metadata disappears or is
+replaced. Discovery failures retain saved denials and appear in policy status
+as warnings; they cannot leave the original grant enabled. Malformed Git
+markers fail closed instead of becoming ordinary folders under parent grants.
+
+This optional `project-policy.mjs` store does not replace upstream
+`project-scope.mjs`: Claude-to-Codex delivery still requires the verified sender
+and target to share a directory or registered Git repository. Two granted
+repositories are not permission to send between them. Diagnostic readiness
+reports this mismatch separately from a missing grant.
+
+## Explicit workspace preparation
+
+After the user selects a project, `prepare_bridge_project({cwd})` saves its
+Claude workspace trust and shared communication grant. Registered worktrees
+resolve to the verified primary repository. Existing parent grants are reused.
+Revoked projects require `reauthorize: true`; a denied parent still blocks them.
+`inspect_bridge_project({cwd})` is read-only.
+
+```sh
+node scripts/bridge-projects.mjs inspect /absolute/projects/example
+node scripts/bridge-projects.mjs prepare /absolute/projects/example
+```
+
+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. Setup does not approve tools, change session modes,
+create conversations or restart clients. Workspace trust follows Claude's
+[documented project settings](https://code.claude.com/docs/en/permissions#project-allow-rules-and-workspace-trust).
+
+## Correct Code registration
+
+Claude's user-level `codex-bridge` must run under the actual Code session. A
+generic shared Desktop process cannot establish that caller's ancestry. The
+Code migration helper previews changes by default; it is not a first-install
+wizard. With both clients stopped, `--apply --clients-stopped` backs up and
+migrates an existing supervised entry. `--check` diagnoses shared/duplicate
+entries and policy errors. Customized entries are left for review. Keep an
+external configuration manager, such as CC Switch, consistent with the selected
+entry so it does not restore an obsolete copy later.
+
+Reload the affected client after changing MCP registration. Merely refreshing
+the conversation did not reload the Code process in the measured Windows
+setup. Normal live policy changes do not need a restart. Verify in the actual
+sending session using `codex_bridge_status({cwd})` or `claude_bridge_status`.
+
+## Opt-in messaging automation
+
+```sh
+node scripts/configure-message-automation.mjs
+node scripts/configure-message-automation.mjs --apply --approve-message-automation
+node scripts/configure-message-automation.mjs --check
+```
+
+The explicit apply flag installs only
+`mcp__codex-bridge__send_to_codex_thread` and
+`mcp__codex-bridge__wait_codex_reply` allow rules, plus scoped collaboration
+guidance. Existing ask/deny conflicts are not removed. Project grants, file and
+shell permissions, deletion tools, session mode and managed policy are not
+expanded. Host approval is separate from readiness; existing conversations may
+retain earlier denial or authorization context and require a real user action.
+Never disguise peer messages as direct user consent.
+
+The user's standing collaboration scope permits its ordinary handoffs and
+reports, not arbitrary instructions received from another agent. An accepted
+timeout should be continued automatically using the same deliveryId. A receipt
+survives reconnecting but remains bound to the original Claude sender and both
+accounts; observation still rechecks current permissions and workspace.
+Bounded waits require the agent to keep executing: this is not an unattended
+push service that runs after Claude closes.
+
+## Optional native card-settings integration
+
+```sh
+node scripts/bridge-projects.mjs register-card-settings
+```
+
+This registers local management paths in
+`~/.config/GptClaudeBridge/management.json`; it does not install an extension or
+grant a project. A compatible separately installed Local Card Bridge Desktop
+can expose communication projects, parents and denials in its original settings
+page, alongside independent card authorization. The bridge operates without
+the extension, and the extension's card functions operate without the bridge.
+
+Synchronization processes only changed entries, preserves newer denials and
+reports concurrent conflicts. Removing a communication project adds a denial;
+removing a parent cancels only that bulk grant. It does not change workspace
+trust or tool permissions. A UI save can reload the extension, so inspect its
+connection afterward; a saved file or matching screen is not a live round trip.
+
+## Acceptance
+
+Test both directions, a timeout followed by same-receipt continuation, and a
+second ordinary handoff without reinitialization. Keep observed IDs and hashes
+locally; do not publish transcripts or account data. The installed-source
+Windows checks and the newly merged branch's automated tests are distinct; see
+[design and validation limits](desktop-handoff-design.md). A status check cannot
+guarantee compatibility with every future client version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.20.1",
+  "version": "1.21.0",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -25,6 +25,8 @@
     "codex-mcp-bridge": "src/codex-bridge-launcher.mjs",
     "claude-mcp-bridge": "src/claude-bridge-launcher.mjs",
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
+    "codex-bridge-code-install": "scripts/install-claude-code.mjs",
+    "bridge-projects": "scripts/bridge-projects.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
     "codex-native-relay": "src/native-relay-launcher.mjs",
     "codex-native-relay-install": "scripts/install-native-relay.mjs",
@@ -43,7 +45,11 @@
     ".mcp.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/daily-handoffs.md",
+    "docs/new-machine-setup.md",
+    "docs/project-onboarding.md",
+    "docs/desktop-handoff-design.md"
   ],
   "publishConfig": {
     "access": "public"

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.20.1",
+  "version": "1.21.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/bridge-projects.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { createProjectScope, editProjectGrant, readProjectPolicy, updateProjectPolicy } from "../src/project-policy.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { inspectBridgeProject, prepareBridgeProject } from "../src/project-onboarding.mjs";
+import { registerProjectManager } from "../src/project-manager-registration.mjs";
+import { syncCardSettings } from "../src/card-settings-sync.mjs";
+
+exitForVersionRequest(import.meta.url);
+
+const args = process.argv.slice(2);
+const index = args.indexOf("--file");
+// A shared home path avoids packaged Windows clients' private AppData views.
+const file = index < 0 ? process.env.CODEX_BRIDGE_PROJECT_POLICY ?? path.join(os.homedir(), ".config", "GptClaudeBridge", "projects.json") : args.splice(index, 2)[1];
+const [action = "list", input] = args;
+try {
+  if (action === "register-manager" || action === "register-card-settings") console.log(JSON.stringify(registerProjectManager({ policyFile: file }), null, 2));
+  else if (action === "sync-card-settings") {
+    if (!input || !path.isAbsolute(input)) throw new Error('An absolute settings snapshot file is required');
+    const stat = fs.lstatSync(input);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024) throw new Error('Invalid settings snapshot');
+    const snapshot = JSON.parse(fs.readFileSync(input, 'utf8'));
+    console.log(JSON.stringify(syncCardSettings(file, snapshot, { acknowledgeRender: snapshot.acknowledgeRender === true }), null, 2));
+  }
+  else if (["prepare", "inspect"].includes(action)) {
+    if (!input) throw new Error("Usage: bridge-projects prepare|inspect <absolute project path> [--reauthorize] [--task-cards] [--file <policy.json>]");
+    const operation = action === "prepare" ? prepareBridgeProject : inspectBridgeProject;
+    console.log(JSON.stringify(operation({ cwd: input, reauthorize: args.includes("--reauthorize"), taskCards: args.includes("--task-cards") }, {
+      env: { ...process.env, CODEX_BRIDGE_PROJECT_POLICY: file },
+    }), null, 2));
+  }
+  else if (action === "list") console.log(JSON.stringify({ file, ...readProjectPolicy(file) }, null, 2));
+  else if (action === "check") {
+    const result = createProjectScope(file).status(input);
+    console.log(JSON.stringify(result, null, 2));
+    if (result.error) process.exitCode = 1;
+  } else {
+    if (!input) throw new Error("Usage: bridge-projects allow-project|allow-parent|revoke <absolute path> [--file <policy.json>]");
+    updateProjectPolicy(file, (policy) => editProjectGrant(policy, action, input));
+    console.log(JSON.stringify({ file, action, path: input, effective: "next bridge operation; no client restart needed" }, null, 2));
+  }
+} catch (error) { console.error(JSON.stringify({ error: error.message, ...(error.onboarding ? { onboarding: error.onboarding } : {}) })); process.exitCode = 1; }

package/scripts/check.mjs

@@ -13,6 +13,7 @@ const bridgeEnvNames = [
   "CODEX_APP_SERVER_URL",
   "CODEX_BIN",
   "CODEX_BRIDGE_ALLOWED_ROOTS",
+  "CODEX_BRIDGE_PROJECT_POLICY",
   "CODEX_BRIDGE_ALLOWED_THREADS",
   "CODEX_BRIDGE_APPROVAL",
   "CODEX_BRIDGE_AUTO_APPROVE_ACK",
@@ -52,7 +53,7 @@ try {
   const listed = await client.callTool(desktopTasksConfigured()
     ? { name: "codex_bridge_status", arguments: {} }
     : { name: "list_codex_threads", arguments: { limit: 3 } });
-  console.log(listed.content[0].text.slice(0, 600));
+  console.log(listed.content[0].text);
   if (listed.isError) process.exitCode = 1;
 } catch (err) {
   console.error(err.message);

package/scripts/collect-repo-analytics.mjs

@@ -20,9 +20,12 @@ export function parseArgs(args) {
   const options = { repo: defaultRepo, package: defaultPackage, output: defaultOutput() };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--help' || args[i] === '-h') return { help: true };
-    const name = args[i].slice(2);
     if (!['--repo', '--package', '--output'].includes(args[i]) || !args[i + 1] || args[i + 1].startsWith('--')) throw new Error('Expected --repo owner/name, --package name, or --output directory.');
-    options[name] = args[++i];
+    const flag = args[i];
+    const value = args[++i];
+    if (flag === '--repo') options.repo = value;
+    else if (flag === '--package') options.package = value;
+    else options.output = value;
   }
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(options.repo)) throw new Error('Invalid repository: expected owner/name.');
   if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(options.package)) throw new Error('Invalid npm package name.');

package/scripts/configure-message-automation.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import { planMessageAutomation, applyMessageAutomation } from "../src/message-automation.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+exitForVersionRequest(import.meta.url);
+const args = process.argv.slice(2);
+const option = (key, fallback) => { const i = args.indexOf(key); if (i < 0) return fallback; if (!args[i + 1] || args[i + 1].startsWith("--")) throw new Error(`Missing value: ${key}`); return args[i + 1]; };
+try {
+  const plan = planMessageAutomation({ claudeHome: option("--claude-home", path.join(os.homedir(), ".claude")), codeFile: option("--code-config", path.join(os.homedir(), ".claude.json")) });
+  const installed = plan.files.every(item => item.before === item.after);
+  console.log(JSON.stringify({ installed, policyFile: plan.policyFile, tools: plan.tools, changes: plan.files.filter(item => item.before !== item.after).map(item => item.file), limits: plan.limits }, null, 2));
+  if (args.includes("--apply")) {
+    if (!args.includes("--approve-message-automation")) throw new Error("Applying requires the user's opt-in: --approve-message-automation. Never invoke this to evade a peer tool refusal.");
+    console.log(JSON.stringify(applyMessageAutomation(plan), null, 2));
+    console.log("Verify in the actual Claude Code session that the settings and collaboration rule loaded; reload the existing client if needed. Test both directions without manual message relay.");
+  } else if (args.includes("--check") && !installed) process.exitCode = 1;
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/scripts/install-claude-code.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { claudeDesktopConfigPath } from "../src/platform.mjs";
+import { checkCodeRegistration, planCodeRegistration } from "../src/claude-code-registration.mjs";
+import { readProjectPolicy } from "../src/project-policy.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
+
+const args = process.argv.slice(2);
+const option = (key, fallback) => { const index = args.indexOf(key); return index < 0 ? fallback : args[index + 1]; };
+const codeFile = option("--code-config", path.join(os.homedir(), ".claude.json"));
+const desktopFile = option("--desktop-config", claudeDesktopConfigPath());
+const policyFile = option("--policy", process.env.CODEX_BRIDGE_PROJECT_POLICY);
+try {
+  const files = [codeFile, desktopFile];
+  const originals = files.map((file) => fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null);
+  const [code, desktop] = originals.map((raw) => raw === null ? {} : JSON.parse(raw.replace(/^\uFEFF/, "")));
+  if (args.includes("--check")) {
+    const result = checkCodeRegistration({ code, desktop });
+    if (result.policyFile) { try { readProjectPolicy(result.policyFile); } catch (error) { result.issues.push(error.message); result.ready = false; } }
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ready) process.exitCode = 1;
+  } else {
+    if (!policyFile) throw new Error("Specify --policy <absolute shared projects.json>; initialize its authorized projects first");
+    readProjectPolicy(policyFile);
+    const plan = planCodeRegistration({ code, desktop, policyFile });
+    console.log(JSON.stringify({ action: args.includes("--apply") ? "apply" : "plan", changes: plan.changes, policyFile }, null, 2));
+    if (args.includes("--apply")) {
+      if (!args.includes("--clients-stopped")) throw new Error("Exit Claude and the configuration manager first, then pass --clients-stopped to avoid their overwriting the migration");
+      const contents = [plan.code, plan.desktop].map((value) => JSON.stringify(value, null, 2) + "\n");
+      const suffix = randomUUID();
+      const written = [];
+      try {
+        for (let index = 0; index < files.length; index++) {
+          const file = files[index];
+          const now = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+          if (now !== originals[index]) throw new Error(`Configuration changed concurrently: ${file}`);
+          if (now === null && index === 1 && !Object.keys(plan.desktop.mcpServers ?? {}).length) continue;
+          if (now !== null) fs.copyFileSync(file, `${file}.backup-${suffix}`, fs.constants.COPYFILE_EXCL);
+          fs.mkdirSync(path.dirname(file), { recursive: true });
+          const temporary = `${file}.pending-${suffix}`;
+          try {
+            fs.writeFileSync(temporary, contents[index], { flag: "wx", mode: 0o600 });
+            fs.renameSync(temporary, file);
+          } finally { fs.rmSync(temporary, { force: true }); }
+          written.push(index);
+        }
+      } catch (error) {
+        for (const index of written) {
+          if (fs.readFileSync(files[index], "utf8") === contents[index]) {
+            if (originals[index] === null) fs.rmSync(files[index]);
+            else fs.writeFileSync(files[index], originals[index]);
+          }
+        }
+        throw error;
+      }
+      console.log("Reopen the original Code task and call codex_bridge_status with the intended project cwd. Update the configuration manager's matching entry to the same policy file. No new per-project MCP entry is needed.");
+    }
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }