@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.bfa11ebe98c6

package/dist/cli/cli.service.js

@@ -5,23 +5,37 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { resolveCursorAgentDirectLaunch } from "../shared/cursor-agent/cursor-agent.launch.js";
-import { redactSecrets, redactText } from "../shared/redaction/redaction.js";
+import { buildWindowsCmdLaunch } from "../shared/process/windows-launch.js";
+import { configureDotNetToolchain } from "../shared/process/dotnet-toolchain.js";
+import { supportsDraftImageAttachmentsFor } from "../shared/provider-capabilities.js";
+import { redactText } from "../shared/redaction/redaction.js";
 import { defaultBridgeServiceConfig, ForgeBridgeService } from "../bridge/bridge.service.js";
 import { forgeBridgeVersion } from "../version.js";
-import { addRepoMapping, applyLocalConfigDefaults, providerStatusesFor, readLocalConfigSync, removeRepoMapping, resolveLocalConfigPath, writeLocalConfig } from "./local-config.js";
+import { ManagedWorktreeCleanupService } from "../cleanup/cleanup.service.js";
+import { addRepoMapping, applyLocalConfigDefaults, providerStatusesFor, readLocalConfigSync, removeRepoMapping, resolveLocalConfigPath, setSandboxPolicy, setServerUrl, writeLocalConfig } from "./local-config.js";
 import { BridgeSessionService } from "../session/session.service.js";
+import { redactRunnerDispatchEvent, redactRunOnceResultPacket } from "../session/session-redaction.js";
+import { validateDockerfilePolicy, validateSandboxContract } from "../sandbox/contract.js";
+import { DockerPreflight } from "../sandbox/preflight.js";
+import { DockerSandboxRuntime } from "../sandbox/runtime.js";
+import { DockerSandboxSmoke } from "../sandbox/smoke.js";
 import { parseCompletionMcpArgs, runCompletionMcpServer } from "../session/phase-completion.js";
-import { failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
+import { failureFactsFromError, failureResult, parseRunOnceDispatchPacket } from "../session/session.types.js";
+import { commandHelpText, helpText } from "./cli.help.js";
 const apiKeySecretGrantEnv = "FORGE_API_KEY_SECRET_GRANT";
 const execFileAsync = promisify(execFile);
 export class ForgeBridgeCliService {
     sessions;
     bridgeFactory;
     pairRunner;
-    constructor(sessions = new BridgeSessionService(), bridgeFactory = (config) => new ForgeBridgeService(config), pairRunner = claimBridgeRunner) {
+    cleanupFactory;
+    dotNetToolchainConfigurator;
+    constructor(sessions = new BridgeSessionService(), bridgeFactory = (config) => new ForgeBridgeService(config), pairRunner = claimBridgeRunner, cleanupFactory = stateRoot => new ManagedWorktreeCleanupService(stateRoot), dotNetToolchainConfigurator = configureDotNetToolchain) {
         this.sessions = sessions;
         this.bridgeFactory = bridgeFactory;
         this.pairRunner = pairRunner;
+        this.cleanupFactory = cleanupFactory;
+        this.dotNetToolchainConfigurator = dotNetToolchainConfigurator;
     }
     async run(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
         if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
@@ -56,11 +70,26 @@ export class ForgeBridgeCliService {
                 io.stderr.write(`forge-bridge connect requires ${missing[0]}.\n`);
                 return 2;
             }
+            let dotNetToolchain;
+            try {
+                dotNetToolchain = await this.dotNetToolchainConfigurator(await dotNetPreflightRoots(config, args.implicitCloneDestination), { cloneFolders: [config.defaultRepoRoot.trim()].filter(Boolean) });
+            }
+            catch (error) {
+                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                return 1;
+            }
+            if (dotNetToolchain) {
+                io.stdout.write(`Using .NET SDK ${dotNetToolchain.sdkVersion}: ${dotNetToolchain.executablePath}\n`);
+            }
             const controller = new AbortController();
             const stop = () => controller.abort("signal received");
             process.once("SIGINT", stop);
             process.once("SIGTERM", stop);
             try {
+                if (config.cleanupWorktrees && config.repoMappings.some(mapping => mapping.localPath?.trim())) {
+                    io.stdout.write("Cleaning stale managed worktrees before accepting dispatches.\n");
+                    await cleanupRepos(config, "stale", true, this.cleanupFactory(config.sandboxStateRoot), io);
+                }
                 io.stdout.write(connectStartupText(config));
                 await this.bridgeFactory(config).run(controller.signal);
                 return 0;
@@ -86,6 +115,7 @@ export class ForgeBridgeCliService {
         if (args.command === "pair") {
             try {
                 const current = readLocalConfigSync();
+                io.stdout.write(`Pairing with server: ${args.serverUrl}\n`);
                 const code = await resolvePairingCode(args.code);
                 const repoRoot = await resolvePairRepoRoot(args.repoRoot, current.defaultRepoRoot);
                 await fs.mkdir(repoRoot, { recursive: true });
@@ -115,12 +145,66 @@ export class ForgeBridgeCliService {
                 return 2;
             }
         }
+        if (args.command === "server-show") {
+            const saved = readLocalConfigSync().serverUrl ?? "not configured";
+            io.stdout.write(`Saved server: ${saved}\n`);
+            if (process.env.FORGE_URL?.trim()) {
+                io.stdout.write(`Effective server: ${process.env.FORGE_URL.trim()} (FORGE_URL override)\n`);
+            }
+            else {
+                io.stdout.write(`Effective server: ${args.config.serverUrl || "not configured"}\n`);
+            }
+            return 0;
+        }
+        if (args.command === "server-set") {
+            try {
+                const config = await setServerUrl(args.serverUrl);
+                io.stdout.write(`Saved Forge server: ${config.serverUrl}\n`);
+                io.stdout.write("Existing runner credentials were retained. Re-run `forge-bridge pair --server <url>` if this is a different Forge deployment.\n");
+                if (process.env.FORGE_URL?.trim()) {
+                    io.stdout.write(`Warning: FORGE_URL is set to ${process.env.FORGE_URL.trim()} and overrides the saved server.\n`);
+                }
+                return 0;
+            }
+            catch (error) {
+                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                return 2;
+            }
+        }
         if (args.command === "status") {
             await writeStatus(args.config, args.checkUpdates, io);
             return 0;
         }
         if (args.command === "cleanup") {
-            return await cleanupRepos(args.config, args.mode, args.force, io);
+            return await cleanupRepos(args.config, args.mode, args.force, this.cleanupFactory(args.config.sandboxStateRoot), io);
+        }
+        if (args.command === "sandbox-init") {
+            return await initializeSandbox(args.repoPath, io);
+        }
+        if (args.command === "sandbox-doctor") {
+            return await diagnoseSandbox(args.repoPath, args.requirePinnedBase, io);
+        }
+        if (args.command === "sandbox-smoke") {
+            return await smokeSandbox(args.repoPath, args.reportPath, args.requirePinnedBase, args.probeLoopbackPort, io);
+        }
+        if (args.command === "sandbox-reap") {
+            return await reapSandboxes(io);
+        }
+        if (args.command === "sandbox-on") {
+            const saved = await setSandboxPolicy(true, args.allowOpenPublic);
+            io.stdout.write("Saved local Docker sandbox policy. Restart the bridge to apply it.\n");
+            writeSandboxPolicyStatus(saved, io);
+            return 0;
+        }
+        if (args.command === "sandbox-off") {
+            const saved = await setSandboxPolicy(false, false);
+            io.stdout.write("Disabled local Docker sandbox placement. Restart the bridge to apply it.\n");
+            writeSandboxPolicyStatus(saved, io);
+            return 0;
+        }
+        if (args.command === "sandbox-status") {
+            writeSandboxPolicyStatus(readLocalConfigSync(), io);
+            return 0;
         }
         if (args.command === "mcp") {
             const parsed = parseCompletionMcpArgs(args.argv);
@@ -140,17 +224,17 @@ export class ForgeBridgeCliService {
                 emit: async (event) => {
                     const line = {
                         type: "runner_event",
-                        event: redactSecrets(event, redactionSecrets)
+                        event: redactRunnerDispatchEvent(event, redactionSecrets)
                     };
                     io.stdout.write(`${JSON.stringify(line)}\n`);
                 }
             });
-            await writeJsonAtomic(args.resultPath, redactSecrets(result, redactionSecrets));
+            await writeJsonAtomic(args.resultPath, redactRunOnceResultPacket(result, redactionSecrets));
             return result.exitCode;
         }
         catch (error) {
             const summary = redactText(error instanceof Error ? error.message : String(error), redactionSecrets);
-            await writeJsonAtomic(args.resultPath, failureResult(summary)).catch(() => undefined);
+            await writeJsonAtomic(args.resultPath, redactRunOnceResultPacket(failureResult(summary, [], failureFactsFromError(error, { source: "bridge" })), redactionSecrets)).catch(() => undefined);
             io.stderr.write(`${summary}\n`);
             return 1;
         }
@@ -231,6 +315,15 @@ export function parseArgs(argv) {
         }
         return { ok: true, command: "remove-repo", label: argv[1] };
     }
+    if (argv[0] === "server") {
+        if (argv.length === 1 || (argv[1] === "show" && argv.length === 2)) {
+            return { ok: true, command: "server-show", config: configuredBridgeServiceConfig() };
+        }
+        if (argv[1] === "set" && argv[2] && argv.length === 3) {
+            return { ok: true, command: "server-set", serverUrl: argv[2] };
+        }
+        return { ok: false, error: "Usage: forge-bridge server <show|set <url>>" };
+    }
     if (argv[0] === "status") {
         let checkUpdates = false;
         for (let index = 1; index < argv.length; index += 1) {
@@ -250,10 +343,13 @@ export function parseArgs(argv) {
     if (argv[0] === "mcp") {
         return { ok: true, command: "mcp", argv };
     }
+    if (argv[0] === "sandbox") {
+        return parseSandboxArgs(argv);
+    }
     if (argv[0] !== "run-once") {
         return {
             ok: false,
-            error: usage()
+            error: helpText()
         };
     }
     let dispatchPath = null;
@@ -280,6 +376,252 @@ export function parseArgs(argv) {
         resultPath: path.resolve(resultPath)
     };
 }
+function parseSandboxArgs(argv) {
+    const action = argv[1];
+    if (action === "on") {
+        let allowOpenPublic = false;
+        for (let index = 2; index < argv.length; index += 1) {
+            if (argv[index] === "--allow-open-public") {
+                allowOpenPublic = true;
+            }
+            else {
+                return { ok: false, error: `Unknown sandbox argument: ${argv[index]}` };
+            }
+        }
+        return { ok: true, command: "sandbox-on", allowOpenPublic };
+    }
+    if (action === "off" && argv.length === 2)
+        return { ok: true, command: "sandbox-off" };
+    if (action === "status" && argv.length === 2)
+        return { ok: true, command: "sandbox-status" };
+    let repoPath = process.cwd();
+    let reportPath;
+    let requirePinnedBase = false;
+    let probeLoopbackPort = false;
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo") {
+            repoPath = argv[++index] ?? "";
+            if (!repoPath)
+                return { ok: false, error: "--repo requires a path." };
+        }
+        else if (arg === "--report" && action === "smoke") {
+            reportPath = argv[++index];
+            if (!reportPath)
+                return { ok: false, error: "--report requires a path." };
+        }
+        else if (arg === "--require-pinned-base" && (action === "doctor" || action === "smoke")) {
+            requirePinnedBase = true;
+        }
+        else if (arg === "--probe-loopback-port" && action === "smoke") {
+            probeLoopbackPort = true;
+        }
+        else {
+            return { ok: false, error: `Unknown sandbox argument: ${arg}` };
+        }
+    }
+    if (action === "init")
+        return { ok: true, command: "sandbox-init", repoPath: path.resolve(repoPath) };
+    if (action === "doctor")
+        return { ok: true, command: "sandbox-doctor", repoPath: path.resolve(repoPath), requirePinnedBase };
+    if (action === "smoke")
+        return {
+            ok: true,
+            command: "sandbox-smoke",
+            repoPath: path.resolve(repoPath),
+            reportPath: reportPath ? path.resolve(reportPath) : undefined,
+            requirePinnedBase,
+            probeLoopbackPort,
+        };
+    if (action === "reap" && argv.length === 2)
+        return { ok: true, command: "sandbox-reap" };
+    return { ok: false, error: "Usage: forge-bridge sandbox <on|off|status|init|doctor|smoke|reap> [--allow-open-public] [--repo <path>] [--report <path>] [--require-pinned-base] [--probe-loopback-port]" };
+}
+const sandboxContractTemplate = `schemaVersion: 1
+workingDirectory: /workspace
+commands:
+  install: npm ci
+  test: npm test
+caches:
+  - name: npm
+    mode: readonly
+services: []
+environment: []
+artifacts: []
+logs: []
+browser: false
+`;
+const sandboxDockerfileTemplate = `# Pin this base by digest before enabling sandbox_required.
+FROM node:22.17.0-bookworm-slim
+WORKDIR /workspace
+`;
+async function initializeSandbox(repoPath, io) {
+    const forgePath = path.join(repoPath, ".forge");
+    const files = [
+        ["forge.sandbox.yml", sandboxContractTemplate],
+        ["Dockerfile", sandboxDockerfileTemplate],
+        ["forge.env.example", "# List non-secret variable names in forge.sandbox.yml. Never commit secret values.\n"]
+    ];
+    await fs.mkdir(forgePath, { recursive: true });
+    let created = 0;
+    for (const [name, contents] of files) {
+        const target = path.join(forgePath, name);
+        try {
+            const handle = await fs.open(target, "wx", 0o600);
+            await handle.writeFile(contents);
+            await handle.close();
+            io.stdout.write(`Created ${path.relative(repoPath, target)}\n`);
+            created += 1;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            io.stdout.write(`Kept existing ${path.relative(repoPath, target)}\n`);
+        }
+    }
+    io.stdout.write(created > 0 ? "Sandbox scaffold is ready. Run `forge-bridge sandbox doctor`.\n" : "Sandbox scaffold already exists.\n");
+    return 0;
+}
+async function diagnoseSandbox(repoPath, requirePinnedBase, io) {
+    try {
+        const forgePath = path.join(repoPath, ".forge");
+        const contractSource = await fs.readFile(path.join(forgePath, "forge.sandbox.yml"), "utf8");
+        const dockerfile = await fs.readFile(path.join(forgePath, "Dockerfile"), "utf8");
+        const contract = validateSandboxContract(contractSource);
+        const warnings = validateDockerfilePolicy(dockerfile, requirePinnedBase);
+        io.stdout.write(`Contract: valid (${contract.digest})\n`);
+        for (const warning of warnings)
+            io.stdout.write(`Warning: ${warning}\n`);
+        const config = defaultBridgeServiceConfig();
+        const preflight = new DockerPreflight({
+            dockerExecutable: config.dockerExecutable,
+            dockerContext: config.dockerContext,
+            stateRoot: config.sandboxStateRoot,
+            maxConcurrentSandboxes: config.maxConcurrentSandboxes,
+            diskHighWatermarkPercent: config.diskHighWatermarkPercent,
+            diskLowWatermarkPercent: config.diskLowWatermarkPercent,
+            minimumWorkspaceBytes: config.minimumWorkspaceBytes,
+            hostMemoryReserveBytes: config.sandboxHostMemoryReserveBytes,
+            defaultWorkerMemoryLimitBytes: config.defaultSandboxWorkerMemoryLimitBytes,
+            defaultServiceMemoryLimitBytes: config.defaultSandboxServiceMemoryLimitBytes,
+            runtimeOverheadBytes: config.sandboxRuntimeOverheadBytes,
+            requireRootless: config.requireRootlessDocker
+        });
+        try {
+            const result = await preflight.refresh();
+            if (!result.healthy) {
+                io.stderr.write(`Docker: unavailable (${result.unavailableCode ?? "preflight_failed"}): ${result.unavailableReason ?? "unknown reason"}\n`);
+                return 1;
+            }
+            io.stdout.write(`Docker: healthy (${result.runtimeVersion}; capacity ${result.maxConcurrentSandboxes})\n`);
+            return 0;
+        }
+        finally {
+            await preflight.release();
+        }
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function smokeSandbox(repoPath, reportPath, requirePinnedBase, probeLoopbackPort, io) {
+    try {
+        const result = await new DockerSandboxSmoke(defaultBridgeServiceConfig()).run({
+            repoPath,
+            reportPath,
+            requirePinnedBase,
+            probeLoopbackPort,
+            onProgress: (stage) => io.stdout.write(`Smoke: ${stage}...\n`),
+        });
+        const { report } = result;
+        if (report.repository.contractDigest)
+            io.stdout.write(`Contract: valid (${report.repository.contractDigest})\n`);
+        for (const warning of report.repository.policyWarnings)
+            io.stdout.write(`Warning: ${warning}\n`);
+        if (report.docker.runtimeVersion) {
+            io.stdout.write(`Docker: healthy (${report.docker.runtimeVersion}; capacity ${report.docker.capacity})\n`);
+        }
+        io.stdout.write(`Attempt: ${report.dispatchAttemptId}\n`);
+        io.stdout.write(`Resource lease: ${report.resourceLeaseId}\n`);
+        if (report.publishedPortProbe) {
+            io.stdout.write(`Loopback port: ${report.publishedPortProbe.hostIp}:${report.publishedPortProbe.hostPort} -> ${report.publishedPortProbe.containerPort}/tcp\n`);
+        }
+        io.stdout.write(`Cleanup: ${report.cleanup.verified ? "verified (zero exact-label resources)" : "failed"}\n`);
+        io.stdout.write(`Report: ${result.reportPath}\n`);
+        if (report.status === "passed") {
+            io.stdout.write("Sandbox smoke: PASS\n");
+            return 0;
+        }
+        io.stderr.write(`Sandbox smoke: FAIL (${report.failure?.code ?? "sandbox_smoke_failed"} at ${report.failure?.stage ?? "unknown"}): ${report.failure?.message ?? "unknown failure"}\n`);
+        return 1;
+    }
+    catch (error) {
+        io.stderr.write(`Sandbox smoke could not write its report: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function reapSandboxes(io) {
+    const config = defaultBridgeServiceConfig();
+    if (!/^[0-9a-f-]{32,36}$/iu.test(config.runnerId)) {
+        io.stderr.write("FORGE_RUNNER_ID must identify the runner whose exact-labeled resources may be reaped.\n");
+        return 2;
+    }
+    const preflight = new DockerPreflight({
+        dockerExecutable: config.dockerExecutable,
+        dockerContext: config.dockerContext,
+        stateRoot: config.sandboxStateRoot,
+        maxConcurrentSandboxes: config.maxConcurrentSandboxes,
+        diskHighWatermarkPercent: config.diskHighWatermarkPercent,
+        diskLowWatermarkPercent: config.diskLowWatermarkPercent,
+        minimumWorkspaceBytes: config.minimumWorkspaceBytes,
+        hostMemoryReserveBytes: config.sandboxHostMemoryReserveBytes,
+        defaultWorkerMemoryLimitBytes: config.defaultSandboxWorkerMemoryLimitBytes,
+        defaultServiceMemoryLimitBytes: config.defaultSandboxServiceMemoryLimitBytes,
+        runtimeOverheadBytes: config.sandboxRuntimeOverheadBytes,
+        requireRootless: config.requireRootlessDocker
+    });
+    try {
+        const result = await preflight.refresh();
+        if (!result.healthy && result.unavailableCode !== "docker_disk_low") {
+            io.stderr.write(`Docker: unavailable (${result.unavailableCode ?? "preflight_failed"}): ${result.unavailableReason ?? "unknown reason"}\n`);
+            return 1;
+        }
+        const runtime = new DockerSandboxRuntime(config);
+        await runtime.reap({ diskLow: result.diskLow });
+        io.stdout.write(`Sandbox reaper completed for runner ${config.runnerId}.\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await preflight.release();
+    }
+}
+async function dotNetPreflightRoots(config, implicitCloneDestination) {
+    const roots = config.repoMappings.map((mapping) => mapping.localPath?.trim())
+        .filter((repoRoot) => Boolean(repoRoot));
+    const defaultRoot = config.defaultRepoRoot.trim();
+    if (!defaultRoot)
+        return roots;
+    if (implicitCloneDestination) {
+        try {
+            // The built-in clone destination need not exist on first connect. lstat
+            // deliberately retains dangling links for the strict SDK scanner to reject.
+            // Explicit mappings (including this same path) remain required inputs.
+            await fs.lstat(defaultRoot);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return roots;
+            throw error;
+        }
+    }
+    roots.push(defaultRoot);
+    return roots;
+}
 function parseConnectArgs(argv) {
     let serverUrl = null;
     let runnerId = null;
@@ -349,7 +691,10 @@ function parseConnectArgs(argv) {
     return {
         ok: true,
         command: "connect",
-        config: configuredBridgeServiceConfig(overrides, localConfig)
+        config: configuredBridgeServiceConfig(overrides, localConfig),
+        implicitCloneDestination: repoRoot === null
+            && process.env.FORGE_REPO_ROOT === undefined
+            && localConfig.defaultRepoRoot === undefined,
     };
 }
 function parsePairArgs(argv) {
@@ -412,7 +757,7 @@ function parsePairArgs(argv) {
         name: name?.trim() || defaultName,
         fingerprint: fingerprint?.trim() || `local-bridge:${os.hostname()}:${user}`,
         repoRoot: repoRoot?.trim() ? path.resolve(repoRoot) : undefined,
-        cleanupWorktrees: cleanupWorktrees ?? localConfig.cleanupWorktrees ?? false,
+        cleanupWorktrees: cleanupWorktrees ?? defaultConfig.cleanupWorktrees,
         cliProviders: cliProviders.length > 0 ? cliProviders : localConfig.cliProviders && localConfig.cliProviders.length > 0 ? [...localConfig.cliProviders] : ["codex"],
         projectLabels: projectLabels.length > 0 ? projectLabels : localConfig.projectLabels ? [...localConfig.projectLabels] : []
     };
@@ -468,7 +813,7 @@ async function claimBridgeRunner(args) {
         })
     });
     if (!response.ok) {
-        throw new Error(`Pairing failed (${response.status}): ${await response.text()}`);
+        throw new Error(formatPairingFailure(response.status, args.serverUrl, await response.text()));
     }
     const value = await response.json();
     if (!value.runnerId || !value.deviceToken) {
@@ -497,6 +842,8 @@ function pairedConfig(current, args, claim) {
         supportsManagedForgeArtifacts: current.supportsManagedForgeArtifacts ?? true,
         supportsRunnerAuthoredPhaseArtifacts: current.supportsRunnerAuthoredPhaseArtifacts ?? true,
         supportsDraftRunOnce: current.supportsDraftRunOnce ?? true,
+        supportsDraftAttachments: current.supportsDraftAttachments ?? true,
+        supportsDraftImageAttachments: supportsDraftImageAttachmentsFor(args.cliProviders),
         repoMappings: current.repoMappings ?? []
     };
 }
@@ -541,181 +888,15 @@ async function resolvePairRepoRoot(repoRoot, configuredRoot) {
 function normalizePairingCode(code) {
     return code?.replace(/[\s-]/g, "").trim() ?? "";
 }
+function formatPairingFailure(status, serverUrl, body) {
+    const hint = body.includes("runner.invalid_pairing_code")
+        ? " Make sure the code was generated by the same Forge server shown above."
+        : "";
+    return `Pairing failed (${status}) against ${serverUrl}: ${body}${hint}`;
+}
 function normalizeServerUrl(serverUrl) {
     return serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`;
 }
-function usage() {
-    return helpText();
-}
-function helpText() {
-    const version = defaultBridgeServiceConfig().version ?? forgeBridgeVersion;
-    return [
-        `🛠 Forge Bridge ${version} — Local provider runners for Forge.`,
-        "",
-        "Usage: forge-bridge [options] [command]",
-        "",
-        "Options:",
-        "  -h, --help       Display help for command",
-        "  -v, --version    Output the version number",
-        "",
-        "Commands:",
-        "  Hint: commands suffixed with * have detailed help. Run <command> --help for details.",
-        "  connect *        Start the runner bridge and wait for Forge dispatches",
-        "  pair *           Pair this machine with Forge and save runner credentials",
-        "  status *         Show config, runner identity, repos, provider CLIs, and updates",
-        "  add-repo *       Map a Forge repo label/name to a local checkout path",
-        "  remove-repo *    Remove a saved repo mapping",
-        "  cleanup *        Prune managed bridge worktrees",
-        "  version *        Print the installed bridge package version",
-        "  help *           Display help for command",
-        "  run-once *       Internal: run one dispatch packet from JSON",
-        "  mcp *            Internal: run the phase-completion MCP server",
-        "",
-        "Examples:",
-        "  npm install -g @loucompanion/forge-bridge@next",
-        "  forge-bridge pair 1234-5678 --server https://srv1493013.tail66073d.ts.net:8443 --repo-root \"%USERPROFILE%\\ForgeRepos\"",
-        "  forge-bridge connect",
-        "  forge-bridge status --check-updates",
-        "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
-        "  forge-bridge cleanup --stale",
-        "",
-        "Troubleshooting:",
-        "  If Forge says the bridge is old: npm install -g @loucompanion/forge-bridge@next",
-        "  If connect shows 502/500: leave it open; it reconnects with backoff while dev restarts.",
-        "  If a provider is missing: run forge-bridge status --check-updates and verify CLI login.",
-        "",
-        "Docs:",
-        "  https://github.com/coleman399/Forge/tree/develop/tools/forge-bridge#readme",
-        "",
-    ].join("\n");
-}
-function commandHelpText(command) {
-    switch (command) {
-        case "pair":
-            return [
-                "Forge Bridge — pair",
-                "Pair this machine with Forge and save runner credentials.",
-                "",
-                "Usage:",
-                "  forge-bridge pair [code] [options]",
-                "",
-                "Options:",
-                "  --server <url>              Forge server URL.",
-                "  --repo-root <path>          Folder where bridge-managed repos/worktrees live.",
-                "  --name <name>               Display name for this runner.",
-                "  --fingerprint <value>       Stable device fingerprint override.",
-                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
-                "  --cleanup-worktrees         Enable managed worktree cleanup.",
-                "  --no-cleanup-worktrees      Disable managed worktree cleanup.",
-                "",
-                "Example:",
-                "  forge-bridge pair 1234-5678 --server https://forge.example.com --repo-root \"%USERPROFILE%\\ForgeRepos\"",
-                "",
-            ].join("\n");
-        case "connect":
-            return [
-                "Forge Bridge — connect",
-                "Start the runner bridge and keep it connected for Forge dispatches.",
-                "",
-                "Usage:",
-                "  forge-bridge connect [options]",
-                "",
-                "Options:",
-                "  --server <url>              Forge server URL; saved config is used when omitted.",
-                "  --runner-id <id>            Runner id; saved config is used when omitted.",
-                "  --device-token <token>      Device token; saved config is used when omitted.",
-                "  --repo-root <path>          Override repo/worktree folder for this run.",
-                "  --cli-provider <list>       Comma-separated providers, e.g. codex,cursor.",
-                "  --heartbeat-interval-ms <n> Heartbeat interval in milliseconds.",
-                "  --cleanup-worktrees         Enable managed worktree cleanup for this run.",
-                "  --no-cleanup-worktrees      Disable managed worktree cleanup for this run.",
-                "",
-                "Example:",
-                "  forge-bridge connect",
-                "",
-            ].join("\n");
-        case "status":
-            return [
-                "Forge Bridge — status",
-                "Show saved configuration, paired runner identity, repo mappings, detected provider CLIs, and optional update info.",
-                "",
-                "Usage:",
-                "  forge-bridge status [--check-updates]",
-                "",
-                "Example:",
-                "  forge-bridge status --check-updates",
-                "",
-            ].join("\n");
-        case "add-repo":
-            return [
-                "Forge Bridge — add-repo",
-                "Map a Forge repo label/name to an existing local checkout.",
-                "",
-                "Usage:",
-                "  forge-bridge add-repo <label> <path>",
-                "",
-                "Example:",
-                "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
-                "",
-            ].join("\n");
-        case "remove-repo":
-            return [
-                "Forge Bridge — remove-repo",
-                "Remove a saved local repo mapping.",
-                "",
-                "Usage:",
-                "  forge-bridge remove-repo <label>",
-                "",
-            ].join("\n");
-        case "cleanup":
-            return [
-                "Forge Bridge — cleanup",
-                "Prune managed bridge worktrees under the configured repo folder.",
-                "",
-                "Usage:",
-                "  forge-bridge cleanup [--stale|--merged|--all] [--force]",
-                "",
-                "Examples:",
-                "  forge-bridge cleanup --stale",
-                "  forge-bridge cleanup --all --force",
-                "",
-            ].join("\n");
-        case "run-once":
-            return [
-                "Forge Bridge — run-once",
-                "Internal command used by Forge to run a single dispatch packet.",
-                "",
-                "Usage:",
-                "  forge-bridge run-once --dispatch <dispatch-json-path> --result <result-json-path>",
-                "",
-            ].join("\n");
-        case "mcp":
-            return [
-                "Forge Bridge — mcp",
-                "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
-                "",
-                "Usage:",
-                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
-                "",
-            ].join("\n");
-        case "version":
-            return [
-                "Forge Bridge — version",
-                "Print the installed bridge package version.",
-                "",
-                "Usage:",
-                "  forge-bridge version",
-                "",
-            ].join("\n");
-        default:
-            return [
-                `Unknown forge-bridge command: ${command}`,
-                "",
-                "Run `forge-bridge help` to see available commands.",
-                "",
-            ].join("\n");
-    }
-}
 function connectStartupText(config) {
     const runner = config.runnerId
         ? `${config.runnerId}${config.deviceName ? ` (${config.deviceName})` : ""}`
@@ -731,11 +912,28 @@ function connectStartupText(config) {
         `  repo folder: ${config.defaultRepoRoot || "not configured"}`,
         `  providers: ${formatList(config.cliProviders)}`,
         `  cleanup worktrees: ${config.cleanupWorktrees ? "enabled" : "disabled"}`,
+        `  Docker Desktop auto-recovery: ${config.dockerDesktopRecoveryEnabled ? "enabled" : "disabled"}`,
+        `  open public sandbox networking: ${config.allowOpenPublicSandbox ? "enabled" : "disabled"}`,
         "",
         "Press Ctrl+C to stop.",
         "",
     ].join("\n");
 }
+function writeSandboxPolicyStatus(local, io) {
+    const effective = configuredBridgeServiceConfig({}, local);
+    io.stdout.write(`Config: ${resolveLocalConfigPath()}\n`);
+    io.stdout.write(`Docker sandbox placement: ${effective.dockerEnabled ? "on" : "off"}\n`);
+    io.stdout.write(`Open public sandbox networking: ${effective.allowOpenPublicSandbox ? "allowed" : "denied"}\n`);
+    if (process.env.FORGE_DOCKER_SANDBOX !== undefined) {
+        io.stdout.write("Docker setting source: FORGE_DOCKER_SANDBOX override\n");
+    }
+    if (process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX !== undefined) {
+        io.stdout.write("Open public setting source: FORGE_ALLOW_OPEN_PUBLIC_SANDBOX override\n");
+    }
+    if (effective.allowOpenPublicSandbox) {
+        io.stdout.write("Warning: open_public permits unrestricted outbound network access from developer sandboxes.\n");
+    }
+}
 function formatList(values) {
     return values.length > 0 ? values.join(", ") : "none";
 }
@@ -746,7 +944,7 @@ async function writeJsonAtomic(outputPath, value) {
     await fs.rename(tempPath, outputPath);
 }
 async function writeStatus(config, checkUpdates, io) {
-    const detected = await detectCliProviders([...new Set([...config.cliProviders, "codex", "cursor"])]);
+    const detected = await detectCliProviders([...new Set([...config.cliProviders, "codex", "cursor", "claude"])]);
     const repos = config.repoMappings.filter((mapping) => mapping.localPath?.trim());
     io.stdout.write(`Forge bridge ${config.version}\n`);
     io.stdout.write(`Config: ${resolveLocalConfigPath()}\n`);
@@ -772,7 +970,7 @@ async function writeStatus(config, checkUpdates, io) {
         io.stdout.write("Update check: no update channel configured.\n");
     }
 }
-async function cleanupRepos(config, mode, force, io) {
+async function cleanupRepos(config, mode, force, cleanup, io) {
     const repos = config.repoMappings.filter((mapping) => mapping.localPath?.trim());
     if (repos.length === 0) {
         io.stdout.write("No repos configured.\n");
@@ -781,20 +979,28 @@ async function cleanupRepos(config, mode, force, io) {
     let failures = 0;
     for (const repo of repos) {
         const repoPath = path.resolve(repo.localPath);
-        const worktreeRoot = path.join(path.dirname(repoPath), ".forge-worktrees", path.basename(repoPath));
-        if (!force) {
-            const action = mode === "all" ? "remove" : "prune";
-            io.stdout.write(`[dry-run] Would ${action} ${worktreeRoot}\n`);
-            continue;
-        }
         try {
-            if (mode === "all") {
-                await fs.rm(worktreeRoot, { recursive: true, force: true });
-                await runGit(repoPath, ["worktree", "prune"]);
-                io.stdout.write(`Removed ${worktreeRoot}\n`);
+            const result = await cleanup.run({
+                repoRoot: repoPath,
+                allowedRepoRoot: config.defaultRepoRoot || undefined,
+                mode,
+                force,
+            });
+            if (!force) {
+                const action = mode === "all"
+                    ? "remove"
+                    : mode === "stale"
+                        ? `remove ${result.candidateWorktrees} stale managed ${result.candidateWorktrees === 1 ? "worktree" : "worktrees"} from`
+                        : "prune";
+                io.stdout.write(`[dry-run] Would ${action} ${result.worktreeRoot}\n`);
+            }
+            else if (mode === "all") {
+                io.stdout.write(`Removed ${result.worktreeRoot}\n`);
+            }
+            else if (mode === "stale") {
+                io.stdout.write(`Removed ${result.removedWorktrees} stale managed ${result.removedWorktrees === 1 ? "worktree" : "worktrees"} from ${result.worktreeRoot}\n`);
             }
             else {
-                await runGit(repoPath, ["worktree", "prune"]);
                 io.stdout.write(`Pruned stale worktree metadata for ${repoPath}\n`);
             }
         }
@@ -811,7 +1017,7 @@ async function detectCliProviders(providers) {
         let detected = null;
         for (const probe of cliProbeCommandsFor(provider)) {
             try {
-                detected = await execVersionCommand(probe);
+                detected = await execVersionCommand(probe, probe.timeoutMs);
                 break;
             }
             catch {
@@ -835,6 +1041,13 @@ function cliProbeCommandsFor(provider) {
             { command: "codex", args: ["--version"] }
         ];
     }
+    if (normalized === "claude") {
+        return [
+            // Claude Code's Node startup can exceed the default 2s probe on a cold Windows host.
+            { command: "claude", args: ["--version"], timeoutMs: 8000 },
+            { command: "claude", args: ["-v"], timeoutMs: 8000 }
+        ];
+    }
     if (normalized === "cursor") {
         return [
             { command: "cursor-agent", args: ["-v"] },
@@ -848,31 +1061,23 @@ function cliProbeCommandsFor(provider) {
         { command: provider, args: ["-V"] }
     ];
 }
-async function execVersionCommand(probe, timeout = 2000) {
+async function execVersionCommand(probe, timeout = 2000, maxBuffer) {
     const directLaunch = process.platform === "win32"
         ? await resolveCursorAgentDirectLaunch(probe.command, probe.args)
         : null;
     if (directLaunch) {
-        return await execFileAsync(directLaunch.command, [...directLaunch.args], { timeout });
+        return await execFileAsync(directLaunch.command, [...directLaunch.args], { timeout, maxBuffer });
     }
     try {
-        return await execFileAsync(probe.command, probe.args, { timeout });
+        return await execFileAsync(probe.command, probe.args, { timeout, maxBuffer });
     }
     catch (error) {
         if (process.platform !== "win32") {
             throw error;
         }
-        return await execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", windowsCommandLine(probe)], { timeout });
-    }
-}
-function windowsCommandLine(probe) {
-    return [probe.command, ...probe.args].map(quoteWindowsCommandLineArg).join(" ");
-}
-function quoteWindowsCommandLineArg(value) {
-    if (value.length > 0 && !/[\s"]/.test(value)) {
-        return value;
+        const launch = buildWindowsCmdLaunch(probe.command, probe.args);
+        return await execFileAsync(launch.command, [...launch.args], { timeout, maxBuffer });
     }
-    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
 }
 function versionLine(output) {
     const lines = output
@@ -886,19 +1091,26 @@ async function detectCliModels(provider) {
     const normalized = provider.toLowerCase();
     try {
         if (normalized === "codex") {
-            const result = await execFileAsync("codex", ["debug", "models"], { timeout: 5000, maxBuffer: 10 * 1024 * 1024 });
+            // Windows installs codex as a .cmd shim, which execFile cannot launch directly.
+            const result = await execVersionCommand({ command: "codex", args: ["debug", "models"] }, 10_000, 10 * 1024 * 1024);
             return parseCodexModelCatalog(result.stdout);
         }
         if (normalized === "cursor") {
             const result = await execVersionCommand({ command: "cursor-agent", args: ["models"] }, 10_000);
             return parseCursorModelList(`${result.stdout || result.stderr}`);
         }
+        if (normalized === "claude") {
+            // Claude Code has no model-listing command; it accepts these aliases and full model IDs.
+            const configured = splitCsv(process.env.FORGE_CLAUDE_MODELS ?? "");
+            return configured.length > 0 ? configured : [...claudeDefaultModels];
+        }
     }
     catch {
         return [];
     }
     return [];
 }
+export const claudeDefaultModels = ["sonnet", "opus", "haiku"];
 export function parseCodexModelCatalog(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -951,8 +1163,8 @@ function uniqueModels(models) {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-async function withDetectedCliProviders(config) {
-    const detected = await detectCliProviders(configuredProviderCandidates(config.cliProviders));
+async function withDetectedCliProviders(config, candidates = config.cliProviders) {
+    const detected = await detectCliProviders(uniqueProviders(candidates));
     const found = detected.filter((result) => result.found);
     if (found.length === 0) {
         return config;
@@ -976,6 +1188,7 @@ async function withDetectedCliProviders(config) {
     };
 }
 async function withDetectedPairCliProviders(args) {
+    const configured = configuredProviderCandidates(args.cliProviders);
     const detectedConfig = await withDetectedCliProviders({
         ...defaultBridgeServiceConfig({
             serverUrl: args.serverUrl,
@@ -985,14 +1198,14 @@ async function withDetectedPairCliProviders(args) {
             cleanupWorktrees: args.cleanupWorktrees,
             defaultRepoRoot: args.repoRoot ?? defaultBridgeServiceConfig().defaultRepoRoot
         })
-    });
+    }, configured);
     return {
         ...args,
         cliProviders: detectedConfig.cliProviders
     };
 }
 function configuredProviderCandidates(providers) {
-    return uniqueProviders([...providers, "codex", "cursor"]);
+    return uniqueProviders([...providers, "codex", "cursor", "claude"]);
 }
 function uniqueProviders(providers) {
     return providers
@@ -1000,6 +1213,3 @@ function uniqueProviders(providers) {
         .filter((provider) => provider.length > 0)
         .filter((provider, index, all) => all.findIndex((candidate) => candidate.toLowerCase() === provider.toLowerCase()) === index);
 }
-async function runGit(cwd, args) {
-    await execFileAsync("git", args, { cwd, timeout: 10_000 });
-}