@yolo-labs/yolobridge 0.1.0 → 0.2.0

package/dist/cli.js

@@ -24,6 +24,9 @@ import { runDetach } from './detach-cmd.js';
 import { getStatus, formatStatus } from './status-cmd.js';
 import { startLocalAgent, stopLocalAgent, DEFAULT_AGENT_BIN } from './local-agent.js';
 import { runListWorkspaces, formatWorkspacesTable } from './workspaces-cmd.js';
+import { startMcpProxy, mcpUrl, SECRET_ENV_VAR } from './mcp-proxy.js';
+import { writeLocalMcpConfig, removeLocalMcpConfig } from './local-mcp-config.js';
+import { writeLocalMcpTrust, removeLocalMcpTrust } from './local-mcp-trust.js';
 const DEFAULT_API_URL = 'https://api.yolo.studio';
 const DEFAULT_AUTH_URL = 'https://auth.yololabs.ai';
 function apiUrl() {
@@ -87,12 +90,16 @@ function printHelp() {
         '                         interactively from `yolo-bridge workspaces`.',
         '    [--label <name>]     Operator-facing host label (reported to the workspace).',
         '    [--agent <binary>]   Local coding-agent binary to spawn (default: $YOLOBRIDGE_AGENT_BIN or "claude").',
+        '    [--agent-id <id>]    Registry identity for local MCP access, if different from --agent',
+        '                         (e.g. a raw executable path, or an agent whose binary name differs',
+        '                         from its registry id like qwen-code/qwen). Defaults to --agent.',
         '  detach                 Detach the current workspace attachment.',
         '  status                 Print local login/attach state.',
         '  --help                 Print this help.',
         '',
         `API base:   ${apiUrl()} (override: YOLOBRIDGE_API_URL)`,
         `Auth base:  ${authUrl()} (override: YOLOBRIDGE_AUTH_URL)`,
+        `MCP base:   ${mcpUrl()} (override: YOLOBRIDGE_MCP_URL)`,
         `Agent bin:  ${DEFAULT_AGENT_BIN} (override: --agent or YOLOBRIDGE_AGENT_BIN)`,
         '',
     ].join('\n'));
@@ -106,28 +113,44 @@ async function cmdLogin() {
 }
 /**
  * Parses `attach`'s argv into its recognized `--label <name>` / `--agent
- * <binary>` flag pairs plus a leftover positional workspaceId — consuming
- * each flag's value together with the flag itself *before* deciding what's
- * left over for the positional, so e.g. `attach --label laptop` doesn't
- * mistake "laptop" for a workspace id (it should still fall through to the
- * interactive picker). An unrecognized `--something` is a hard error rather
- * than being silently swallowed as some other flag's value.
+ * <binary>` / `--agent-id <registryId>` flag pairs plus a leftover
+ * positional workspaceId — consuming each flag's value together with the
+ * flag itself *before* deciding what's left over for the positional, so
+ * e.g. `attach --label laptop` doesn't mistake "laptop" for a workspace id
+ * (it should still fall through to the interactive picker). An unrecognized
+ * `--something` is a hard error rather than being silently swallowed as
+ * some other flag's value.
+ *
+ * `--agent-id` exists because `--agent` names the literal spawn command
+ * (whatever `startLocalAgent` execs), which is NOT always the same string
+ * as the mint route's registry `agentId` (Codex review, 2026-08-24, round
+ * 4/5): a raw executable path (`--agent /opt/bin/claude`) 400s as
+ * unregistered, and some registered agents' own binary differs from their
+ * registry id (`qwen-code`'s binary is `qwen`, `kiro`'s is `kiro-cli`).
+ * yolobridge has no local copy of `agents.json` to resolve this itself (it
+ * runs on the operator's own machine, not in a pod) — asserting it
+ * explicitly is the honest fix, not guessing. Defaults to `agentBin` when
+ * omitted, which is correct for every agent whose registry id equals its
+ * binary name (the common case: `claude`, `codex`, ...).
  */
 export function parseAttachArgs(args) {
     let workspaceId;
     let hostLabel;
     let agentBin;
+    let agentId;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === '--label' || a === '--agent') {
+        if (a === '--label' || a === '--agent' || a === '--agent-id') {
             const value = args[i + 1];
             if (value === undefined || value.startsWith('--')) {
                 return { error: `${a} requires a value` };
             }
             if (a === '--label')
                 hostLabel = value;
-            else
+            else if (a === '--agent')
                 agentBin = value;
+            else
+                agentId = value;
             i++;
             continue;
         }
@@ -138,18 +161,32 @@ export function parseAttachArgs(args) {
             workspaceId = a;
         }
     }
-    return { workspaceId, hostLabel, agentBin };
+    return { workspaceId, hostLabel, agentBin, agentId };
 }
 async function cmdAttach(args) {
+    // Printed unconditionally, first thing, regardless of how the rest of
+    // this command goes — a self-diagnosing fix for a real, repeated support
+    // cost (2026-08-24): every one of that day's "Invalid delegated token" /
+    // wrong-workspace confusions traced back to ONE of these three URLs being
+    // stale in the caller's shell (e.g. YOLOBRIDGE_MCP_URL added to a .bashrc
+    // AFTER the terminal in use had already sourced it), with nothing in the
+    // command's own output making that visible until well after the fact.
+    process.stdout.write(`yolo-bridge: API base ${apiUrl()} · Auth base ${authUrl()} · MCP base ${mcpUrl()}\n`);
     const parsed = parseAttachArgs(args);
     if ('error' in parsed) {
         process.stderr.write(`yolo-bridge attach: ${parsed.error}\n`);
-        process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>]\n');
+        process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>] [--agent-id <registryId>]\n');
         return 64;
     }
     let workspaceId = parsed.workspaceId;
     const hostLabel = parsed.hostLabel;
     const agentBin = parsed.agentBin;
+    // The mint route's registry identity, NOT necessarily the same string as
+    // the spawn command above (see parseAttachArgs's doc comment). Falls back
+    // to agentBin (then DEFAULT_AGENT_BIN) for the common case where they
+    // match, which is every built-in agent this daemon has been used with so
+    // far (claude, codex).
+    const resolvedAgentId = parsed.agentId ?? agentBin ?? DEFAULT_AGENT_BIN;
     if (workspaceId) {
         const resolved = await resolveWorkspaceIdOrName(workspaceId, { commonApiBaseUrl: apiUrl() });
         if (!resolved.ok) {
@@ -178,7 +215,7 @@ async function cmdAttach(args) {
                     process.stderr.write(`yolo-bridge attach: ${pick.message}\n`);
                     break;
             }
-            process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>]\n');
+            process.stderr.write('Usage: yolo-bridge attach [workspaceId] [--label <name>] [--agent <binary>] [--agent-id <registryId>]\n');
             return 64;
         }
         workspaceId = pick.workspaceId;
@@ -193,39 +230,243 @@ async function cmdAttach(args) {
     };
     process.on('SIGINT', onSignal);
     process.on('SIGTERM', onSignal);
-    // Spawns the local coding agent under a real PTY right away — this
-    // command is what launches the user's local session (see
-    // docs/YOLOBRIDGE_PLAN.md's "⚠ Not yet functional" section). The PTY's
-    // output streams live to this process's own stdout and this process's
-    // stdin is piped into the PTY, so the terminal running `attach` is a
-    // live view onto the exact session remote prompts land in.
-    startLocalAgent({
-        agentBin,
-        onExit: ({ exitCode, signal }) => {
-            localAgentExited = true;
-            stopRequested = true;
-            process.stdout.write(`\nyolo-bridge: local agent exited (code=${exitCode}${signal ? `, signal=${signal}` : ''}), detaching...\n`);
-            // Fire-and-forget: don't wait on the SSE loop to unwind on its own
-            // (it only re-checks shouldStop() at loop boundaries) to report the
-            // status change — tell the server immediately so the tile flips to
-            // `stopped` right away instead of riding out the heartbeat
-            // staleness window (~90s, Decision Q2). The daemon loop below still
-            // exits promptly too, via `shouldStop`.
-            runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
-        },
-    });
-    const result = await runAttachFromDisk({
-        workspaceId,
-        commonApiBaseUrl: apiUrl(),
-        hostLabel,
-        shouldStop: () => stopRequested,
-    });
-    process.removeListener('SIGINT', onSignal);
-    process.removeListener('SIGTERM', onSignal);
-    // Whatever ended the attach loop — local Ctrl+C, a server-initiated
-    // `detached` frame, or the agent process exiting on its own — also ends
-    // the PTY session `attach` spawned. Safe no-op if it already exited.
-    stopLocalAgent();
+    const spawnCwd = process.cwd();
+    let mcpProxyHandle;
+    let mcpConfigCleanup;
+    let mcpTrustRemoval;
+    let result;
+    try {
+        result = await runAttachFromDisk({
+            workspaceId,
+            commonApiBaseUrl: apiUrl(),
+            hostLabel,
+            shouldStop: () => stopRequested,
+            // Fires once the real tileId exists (docs/YOLOBRIDGE_PLAN.md's "Local
+            // MCP access" section) — starts the local MCP proxy and writes
+            // `.mcp.json` BEFORE spawning the local agent, since Claude Code reads
+            // that file at process launch. A proxy-start failure is logged and
+            // skipped, not fatal — MCP access is an enhancement on a tile that
+            // already works without it (send_to_tile/read_tile_output are
+            // unaffected either way).
+            onAttached: async ({ getAccessToken, clearScreen }) => {
+                // Isolated from `startLocalAgent` below on purpose (Codex review,
+                // 2026-08-24): `startMcpProxy` itself never throws, but
+                // `writeLocalMcpConfig`/`writeLocalMcpTrust` do plain synchronous
+                // `fs` writes (e.g. a read-only `spawnCwd` throws EACCES) — without
+                // this try/catch, that exception propagates out of the WHOLE
+                // `onAttached` callback (`runAttachDaemon`'s own best-effort wrapper
+                // only logs it), and `startLocalAgent` — later in this same
+                // callback — never runs. That leaves a daemon holding a live
+                // attachment + SSE stream with no local PTY to ever receive a
+                // prompt. MCP access is an enhancement on a tile that already works
+                // without it; the local agent spawning is not optional.
+                try {
+                    mcpProxyHandle = await startMcpProxy({
+                        apiUrl: apiUrl(),
+                        getAccessToken,
+                        workspaceId,
+                        agentId: resolvedAgentId,
+                        log: (line) => process.stdout.write(`${line}\n`),
+                    });
+                    // `.mcp.json` + `.claude/settings.json` are Claude Code-specific
+                    // conventions — Codex reads `~/.codex/config.toml`'s
+                    // `[mcp_servers.*]` instead (`containers/services/container-api/
+                    // mcp-config-writer.js:5-7`). Writing Claude's files for a
+                    // non-Claude `--agent` would silently configure nothing that
+                    // binary ever reads (Codex review, 2026-08-24) — the proxy still
+                    // starts (harmless, agent-agnostic), but only Claude gets it
+                    // wired in until a Codex-format writer exists.
+                    //
+                    // Keyed on `resolvedAgentId`, NOT `agentBin`/`resolvedAgentBin`
+                    // (Codex review, round 5): `--agent-id` exists precisely to assert
+                    // "this really is claude" even when spawned via a nonstandard path
+                    // or name (`--agent /opt/bin/claude --agent-id claude`) — keying
+                    // this decision on the raw spawn string instead would mint
+                    // successfully but still skip writing the config a real Claude
+                    // Code process would actually read.
+                    if (mcpProxyHandle && resolvedAgentId !== 'claude') {
+                        // A non-claude agent never reads `.mcp.json`/`${SECRET_ENV_VAR}`
+                        // at all, so exporting the secret here is harmless (nothing
+                        // ever consumes it) — kept for that case only; see below for
+                        // why the claude case is NOT unconditional.
+                        process.env[SECRET_ENV_VAR] = mcpProxyHandle.secret;
+                        process.stdout.write(`yolo-bridge: local MCP auto-config is only implemented for claude (resolved agent id "${resolvedAgentId}") — the proxy is running at ${mcpProxyHandle.url} but nothing points the local agent at it.\n`);
+                    }
+                    else if (mcpProxyHandle) {
+                        const configResult = writeLocalMcpConfig(spawnCwd, mcpProxyHandle.url);
+                        if (!configResult.ok) {
+                            // Deliberately does NOT export `${SECRET_ENV_VAR}` here (Codex
+                            // review, 2026-08-24, round 29): the most common refusal
+                            // reason is a SIBLING attach in the same directory that
+                            // already owns the shared `.mcp.json` entry — `.mcp.json`
+                            // still points at THAT sibling's proxy URL, unrelated to
+                            // this process's own secret. Exporting our own secret anyway
+                            // used to make this session's Claude authenticate against
+                            // the sibling's proxy with the WRONG secret — a consistent,
+                            // confusing 401 on every MCP tool call, not the "left
+                            // unconfigured" degrade this log line describes. Leaving the
+                            // var unset doesn't fully fix that (Claude still sees the
+                            // sibling's entry either way — `.mcp.json` is shared, not
+                            // per-process), but it stops actively contributing a
+                            // guaranteed-wrong credential to an entry this process
+                            // doesn't own.
+                            process.stdout.write(`yolo-bridge: could not configure local MCP access (${spawnCwd}/.mcp.json is unparseable, already has its own "yolo-studio" entry — possibly from a live sibling attach in this same directory — or would not be safe from a future commit) — leaving it as-is rather than overwrite/dirty it.\n`);
+                        }
+                        else {
+                            // Exported on THIS process's env, before `startLocalAgent`
+                            // spawns the local agent below (which inherits it) — the
+                            // actual secret never touches `.mcp.json` itself (Codex
+                            // review, 2026-08-24, round 12: that file is a
+                            // `${SECRET_ENV_VAR}` template Claude Code expands against its
+                            // own inherited env at load time). Set ONLY after confirming
+                            // THIS process actually owns the `.mcp.json` entry it points
+                            // at — see the refusal branch above for why setting it
+                            // unconditionally was wrong.
+                            process.env[SECRET_ENV_VAR] = mcpProxyHandle.secret;
+                            mcpConfigCleanup = { expectedProxyUrl: mcpProxyHandle.url, createdFile: configResult.createdFile };
+                            // Pre-trusts ONLY the yolo-studio server (server-discovery trust +
+                            // its own tool-call approvals) so Claude Code doesn't sit on an
+                            // interactive "New MCP server found" / per-tool-call prompt with
+                            // nobody watching. Best-effort: a failure here still leaves the
+                            // MCP server configured and usable, just with the normal
+                            // approval prompts, so it's logged rather than fatal.
+                            const trustResult = writeLocalMcpTrust(spawnCwd);
+                            if (!trustResult.ok) {
+                                process.stdout.write(`yolo-bridge: could not pre-trust the local MCP server (${spawnCwd}/.claude/settings.local.json is unparseable, or would not be safe from a future commit) — MCP tool calls will need manual approval.\n`);
+                            }
+                            else {
+                                // Only remove on cleanup what THIS attach actually inserted —
+                                // an entry the operator already had (added_*Entry: false)
+                                // was their own standing trust grant, not ours to revoke.
+                                mcpTrustRemoval = {
+                                    removeServerEntry: trustResult.addedServerEntry,
+                                    removePermissionEntry: trustResult.addedPermissionEntry,
+                                    createdFile: trustResult.createdFile,
+                                    attachId: trustResult.attachId,
+                                };
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stdout.write(`yolo-bridge: local MCP setup failed (${err instanceof Error ? err.message : String(err)}) — continuing without it.\n`);
+                }
+                // A stop signal (Ctrl+C) can arrive while this callback was still
+                // awaiting the MCP-setup block above — `runAttachDaemon` only checks
+                // `shouldStop()` again after `onAttached` RETURNS, so without this
+                // check a cancellation mid-setup would still spawn a brand-new PTY
+                // process just to kill it moments later (Codex review, 2026-08-24).
+                if (stopRequested)
+                    return;
+                // Clears the terminal right before the agent's own UI takes over —
+                // NOT on the SSE 'connected' frame (reverted design, see
+                // attach-cmd.ts's `onAttached` doc comment for why: this is the one
+                // moment guaranteed to be before any agent output, regardless of how
+                // fast the agent boots or how slow the SSE connect is).
+                clearScreen();
+                // Spawns the local coding agent under a real PTY — this is what
+                // launches the user's local session (see docs/YOLOBRIDGE_PLAN.md's
+                // "⚠ Not yet functional" section). The PTY's output streams live to
+                // this process's own stdout and this process's stdin is piped into
+                // the PTY, so the terminal running `attach` is a live view onto the
+                // exact session remote prompts land in.
+                //
+                // Deliberately OUTSIDE the MCP-setup try/catch above and in its own
+                // (Codex review, 2026-08-24): an unspawnable agent (missing/
+                // non-executable binary — node-pty's `spawn()` throws synchronously,
+                // ENOENT) must not be swallowed by `runAttachDaemon`'s own
+                // best-effort `onAttached` wrapper, which only logs and continues —
+                // that would leave a live, apparently-connected tile with no PTY,
+                // waiting forever with nothing able to receive a prompt. Mirrors the
+                // real `onExit` handler below: stop + detach immediately rather than
+                // let the daemon loop ride out the full heartbeat-staleness window.
+                try {
+                    startLocalAgent({
+                        agentBin,
+                        cwd: spawnCwd,
+                        onExit: ({ exitCode, signal }) => {
+                            localAgentExited = true;
+                            stopRequested = true;
+                            process.stdout.write(`\nyolo-bridge: local agent exited (code=${exitCode}${signal ? `, signal=${signal}` : ''}), detaching...\n`);
+                            // Fire-and-forget: don't wait on the SSE loop to unwind on its own
+                            // (it only re-checks shouldStop() at loop boundaries) to report the
+                            // status change — tell the server immediately so the tile flips to
+                            // `stopped` right away instead of riding out the heartbeat
+                            // staleness window (~90s, Decision Q2). The daemon loop below still
+                            // exits promptly too, via `shouldStop`.
+                            runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+                        },
+                    });
+                }
+                catch (err) {
+                    localAgentExited = true;
+                    stopRequested = true;
+                    process.stdout.write(`\nyolo-bridge: failed to start the local agent (${err instanceof Error ? err.message : String(err)}), detaching...\n`);
+                    runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+                }
+            },
+        });
+    }
+    finally {
+        // Codex review, 2026-08-24, round 17: this whole block used to run
+        // unconditionally AFTER the `await` above, which only happens if
+        // `runAttachFromDisk` actually RESOLVES. If it instead throws (e.g. a
+        // reconnect-time fetch inside the daemon loop rejects in a way its own
+        // internal handling doesn't catch), the exception skips straight past
+        // ALL of this — signal listeners stay attached, the local PTY and the
+        // MCP proxy's HTTP server both stay alive, and neither local nor
+        // server-side state ever gets cleaned up. `main()`'s own top-level
+        // `.catch()` only sets `process.exitCode`, which does NOT force an
+        // exit — with the PTY/HTTP server still referenced, the process's
+        // event loop has no reason to ever end on its own, leaving the CLI
+        // hung indefinitely with a stale attachment and a live local proxy. A
+        // `finally` runs this cleanup on EITHER outcome, resolve or reject.
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        // Whatever ended the attach loop — local Ctrl+C, a server-initiated
+        // `detached` frame, or the agent process exiting on its own — also ends
+        // the PTY session `attach` spawned. Safe no-op if it already exited.
+        stopLocalAgent();
+        // Same "nothing left running detached" discipline for the local MCP
+        // proxy: stop the server (drops the delegated token from memory) and
+        // remove the .mcp.json entry we added, if we added one. Each step is
+        // wrapped individually (Codex review, 2026-08-24, round 12): the removal
+        // helpers' own `writeFileSync`/`unlinkSync` calls are unguarded, and an
+        // exception from any one of them — a permission change or a full disk
+        // mid-session — would otherwise propagate out of this whole cleanup
+        // sequence and skip the SERVER-side detach below entirely, leaving the
+        // tile live on the server even though the local process is exiting. Local
+        // cleanup is best-effort; the server detach is not.
+        if (mcpProxyHandle) {
+            try {
+                await mcpProxyHandle.stop();
+            }
+            catch (err) {
+                process.stdout.write(`yolo-bridge: local MCP proxy shutdown failed (${err instanceof Error ? err.message : String(err)}).\n`);
+            }
+        }
+        if (mcpTrustRemoval) {
+            try {
+                removeLocalMcpTrust(spawnCwd, mcpTrustRemoval);
+            }
+            catch (err) {
+                process.stdout.write(`yolo-bridge: local MCP trust cleanup failed (${err instanceof Error ? err.message : String(err)}).\n`);
+            }
+        }
+        // removeLocalMcpConfig only deletes the entry if its CURRENT value still
+        // matches the exact URL captured in mcpConfigCleanup, and only unlinks
+        // the whole file if THIS attachment is the one that created it
+        // (createdFile) -- an undefined mcpConfigCleanup (nothing was ever
+        // successfully written) correctly skips the call.
+        if (mcpConfigCleanup) {
+            try {
+                removeLocalMcpConfig(spawnCwd, mcpConfigCleanup.expectedProxyUrl, mcpConfigCleanup.createdFile);
+            }
+            catch (err) {
+                process.stdout.write(`yolo-bridge: local MCP config cleanup failed (${err instanceof Error ? err.message : String(err)}).\n`);
+            }
+        }
+    }
     if (!result.ok) {
         if (result.reason === 'not-logged-in') {
             process.stderr.write('yolo-bridge attach: not logged in — run `yolo-bridge login` first.\n');

package/dist/device-auth.js

@@ -13,15 +13,16 @@
  *       'authorization_pending' | 'access_denied' | 'expired_token'
  *       | 'Invalid device code' | 'Invalid device code state'
  *
- * NOTE (discrepancy from docs/YOLOBRIDGE_PLAN.md): the plan's Architecture
- * section says login "opens the browser to the verification URL with the
- * code pre-filled". The actual `initiateDeviceFlow` controller returns a
- * bare `verification_uri` (`${FRONTEND_URL}/device`, no query string) —
- * there is no code-prefill parameter in the real response. The CLI below
- * prints the user_code alongside the URL and expects the user to type it
- * in manually, same as GitHub's device flow UX. If prefill lands later on
- * the webapp `/device` page, this client doesn't need to change — it just
- * won't benefit from it.
+ * NOTE (was a discrepancy from docs/YOLOBRIDGE_PLAN.md, now resolved): the
+ * `initiateDeviceFlow` controller returns a bare `verification_uri`
+ * (`${FRONTEND_URL}/device`, no query string) — there is no code-prefill
+ * parameter in the raw response, and no auth-service change was needed to
+ * fix this. `webapp/app/device/page.tsx` already reads a `code` query
+ * param and pre-fills its input from it (an existing convention this CLI
+ * simply wasn't using yet). `login-cmd.ts` builds the pre-filled URL
+ * client-side (`verificationUri` + `?code=<userCode>`) before opening the
+ * browser — this module still hands back the bare `verificationUri`
+ * unchanged; the prefill is entirely the caller's concern.
  */
 export class DeviceAuthError extends Error {
 }

package/dist/git-safety.js

@@ -0,0 +1,151 @@
+/**
+ * Shared by `local-mcp-trust.ts` and `local-mcp-config.ts`: both write
+ * per-attach, machine-local state into a project file that MANY real
+ * projects intentionally track in Git (`.claude/settings.local.json` and
+ * `.mcp.json` respectively — this repo's own root tracks BOTH, confirmed
+ * with `git ls-files`/`git cat-file`, not assumed). A spawned coding agent
+ * running with YOLO-mode autonomy can `git add -A && commit` at any point
+ * while attached, publishing that ephemeral state to every collaborator;
+ * `chmod`/cleanup-on-detach only ever touch the WORKING TREE, never a
+ * commit already made. Extracted once both writers needed the identical
+ * check (Codex review, 2026-08-24, rounds 15 and 16).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, isAbsolute, relative, sep } from 'node:path';
+import { atomicWriteFileSync, resolveWriteTarget } from './atomic-write.js';
+/**
+ * True only when `git check-ignore` DEFINITIVELY confirms `path` is NOT
+ * ignored inside a real git repo at `cwd` (exit code 1) — i.e. a `git add
+ * -A` could actually pick it up. Empirically verified exit codes (not
+ * assumed): 0 = ignored (safe), 1 = not ignored (risky), 128 = `cwd` isn't
+ * a git repo at all (safe — nothing can ever commit it; also the exact
+ * code git reports for a path OUTSIDE the repository entirely, e.g. a
+ * symlink resolving somewhere `git add -A` from `cwd` could never reach
+ * anyway — verified with a real `git check-ignore` against `/etc/passwd`,
+ * not assumed). Any OTHER outcome (git missing, a weird error) is also
+ * treated as safe: this function's only job is to catch a CONFIRMED risk,
+ * not to require positive proof of safety, matching both callers' existing
+ * philosophy that this state is a best-effort enhancement, not something
+ * worth hard-failing an attach over.
+ *
+ * Also checks the REAL, symlink-resolved target, not just `path` itself
+ * (Codex review, 2026-08-24, round 21): `atomicWriteFileSync` follows a
+ * symlink at `path` and writes through it (round 16), so an ignored
+ * SYMLINK pointing at a TRACKED file elsewhere in the same repo would pass
+ * the check on `path` alone while every subsequent write actually lands in
+ * the tracked target — exactly what this guard exists to prevent, defeated
+ * by a resolution neither caller was checking. Verified empirically (not
+ * assumed): an ignored symlink to a tracked in-repo file reports
+ * `check-ignore` status 0 for the link itself but status 1 for its
+ * resolved target. Uses the SAME resolution `atomicWriteFileSync` itself
+ * performs, so this check can never diverge from what actually gets
+ * written to.
+ */
+export function riskyToCommit(cwd, path) {
+    if (isConfirmedNotIgnored(cwd, path))
+        return true;
+    const realTarget = resolveWriteTarget(path);
+    // `null` (Codex review, 2026-08-24, round 31) means `atomicWriteFileSync`
+    // would THROW rather than write anything through this symlink at all —
+    // nothing will be created, so there's nothing for a future commit to
+    // pick up either.
+    if (realTarget === null)
+        return false;
+    return realTarget !== path && isConfirmedNotIgnored(cwd, realTarget);
+}
+function isConfirmedNotIgnored(cwd, path) {
+    const result = spawnSync('git', ['check-ignore', '-q', path], { cwd });
+    return result.status === 1;
+}
+/**
+ * Idempotently adds a LOCAL-ONLY exclude pattern — `.git/info/exclude`, the
+ * git-native mechanism for machine-specific excludes that are never shared
+ * via `.gitignore` — covering an ephemeral sibling this module's callers
+ * create next to a destination path (Codex review, 2026-08-24, round 25;
+ * generalized to an explicit `pattern` in round 28 — see below).
+ *
+ * `riskyToCommit` validates the DESTINATION path, but a sibling this code
+ * itself creates (`atomicWriteFileSync`'s `<name>.tmp-<pid>-<hex>`, or
+ * `acquireConfigLock`'s `<lock>`/`<lock>.claim-*`/`<lock>.reclaim-*`) has a
+ * DIFFERENT literal name — an operator's typical EXACT-match `.gitignore`
+ * entry for `.mcp.json` (the common, expected shape — verified empirically,
+ * round 15) does NOT also cover a suffixed sibling. A crash in the narrow
+ * window between creating one of these and either renaming/unlinking it or
+ * cleaning it up on the next call would leave an untracked-but-not-ignored
+ * copy of live local state sitting in the working tree, ready for a
+ * spawned YOLO-mode agent's next `git add -A && commit` to publish — and
+ * even OUTSIDE a crash, a concurrently-running agent can `git add -A` at
+ * any moment while one of these briefly exists mid-operation.
+ *
+ * Refusing the write outright whenever a sibling name isn't covered was
+ * considered and rejected: an exact-match `.gitignore` pattern NEVER covers
+ * a suffixed sibling, so that would break local MCP configuration for
+ * every correctly-configured repo, not just a misconfigured one. Making the
+ * name actually covered — once, per repo, via the same mechanism
+ * `.gitignore` itself uses under the hood — closes the gap without that
+ * regression.
+ *
+ * `patternBasename` is the LITERAL exclude-file basename to add (a plain
+ * name, or a `*`-glob — round 28 generalized this from always appending
+ * `.tmp-*` onto a passed-in basename, since `acquireConfigLock`'s own
+ * siblings don't fit that one fixed shape). `destDir` is the absolute
+ * directory `patternBasename` lives in.
+ *
+ * Anchored to `destDir`, relative to the repo's working-tree root (Codex
+ * review, 2026-08-25, round 32) — a bare basename pattern with no `/` in it
+ * (what this function wrote through round 31) matches that basename in
+ * EVERY directory of the repo, not just the one the caller actually writes
+ * to: running `attach` in one monorepo package permanently hid a
+ * same-shaped file in every OTHER package too (e.g. an operator's own
+ * `.mcp.json.tmp-backup` sitting in an unrelated package now matches the
+ * trailing `*` and vanishes from `git status`). A leading `/` makes a
+ * `.git/info/exclude` pattern match only at the given path from the
+ * worktree root, the same anchoring a `/`-prefixed line in a root
+ * `.gitignore` gets.
+ *
+ * Best-effort and silent on any failure (no `.git` dir, a worktree/
+ * submodule shape `git rev-parse` can't resolve cleanly, a read-only
+ * `.git`, `destDir` outside the working tree entirely): degrades to "only
+ * the destination's own git-ignore status is checked," exactly the
+ * pre-round-25 behavior — never blocks the write itself over this.
+ *
+ * Writes via `atomicWriteFileSync` (Codex review, 2026-08-25, round 32),
+ * not a direct `writeFileSync` — this file routinely already holds an
+ * operator's OWN local excludes, so a truncate-then-write that gets cut off
+ * by ENOSPC/SIGKILL mid-write used to leave it partial or empty, silently
+ * un-hiding whatever the operator had excluded before. Write-to-temp then
+ * rename means the original content survives any failure up to the rename
+ * itself.
+ */
+export function ensureTempSiblingExcluded(cwd, destDir, patternBasename) {
+    try {
+        const topLevelResult = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf-8' });
+        if (topLevelResult.status !== 0)
+            return;
+        const topLevel = topLevelResult.stdout.trim();
+        if (!topLevel)
+            return;
+        const relDir = relative(topLevel, destDir);
+        if (relDir.startsWith('..') || isAbsolute(relDir))
+            return; // `destDir` isn't inside this working tree at all.
+        const relDirPosix = relDir.split(sep).join('/');
+        const pattern = relDirPosix ? `/${relDirPosix}/${patternBasename}` : `/${patternBasename}`;
+        const gitDirResult = spawnSync('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf-8' });
+        if (gitDirResult.status !== 0)
+            return;
+        const gitDir = gitDirResult.stdout.trim();
+        if (!gitDir)
+            return;
+        const excludePath = join(isAbsolute(gitDir) ? gitDir : join(cwd, gitDir), 'info', 'exclude');
+        const existing = existsSync(excludePath) ? readFileSync(excludePath, 'utf-8') : '';
+        if (existing.split('\n').some((line) => line.trim() === pattern))
+            return; // Already present.
+        mkdirSync(dirname(excludePath), { recursive: true });
+        const withTrailingNewline = existing.length > 0 && !existing.endsWith('\n') ? `${existing}\n` : existing;
+        atomicWriteFileSync(excludePath, `${withTrailingNewline}${pattern}\n`);
+    }
+    catch {
+        // Best-effort — see doc comment above.
+    }
+}