@loucompanion/forge-bridge 0.1.3-dev.9bc5014a2270 → 0.1.3-dev.a58d7cd1092f

package/dist/cli/cli.service.d.ts

@@ -1,12 +1,18 @@
+import { type DotNetToolchainSelection } from "../shared/process/dotnet-toolchain.js";
 import type { BridgeService } from "../bridge/bridge.base.js";
 import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
+import type { CleanupMode } from "../cleanup/cleanup.types.js";
+import type { CleanupService } from "../cleanup/cleanup.base.js";
 import type { SessionService } from "../session/session.base.js";
 import type { CliIo, CliService } from "./cli.base.js";
+type DotNetToolchainConfigurator = (repoRoots: readonly string[]) => Promise<DotNetToolchainSelection | null>;
 export declare class ForgeBridgeCliService implements CliService {
     private readonly sessions;
     private readonly bridgeFactory;
     private readonly pairRunner;
-    constructor(sessions?: SessionService, bridgeFactory?: (config: BridgeServiceConfig) => BridgeService, pairRunner?: PairRunnerClient);
+    private readonly cleanupFactory;
+    private readonly dotNetToolchainConfigurator;
+    constructor(sessions?: SessionService, bridgeFactory?: (config: BridgeServiceConfig) => BridgeService, pairRunner?: PairRunnerClient, cleanupFactory?: CleanupServiceFactory, dotNetToolchainConfigurator?: DotNetToolchainConfigurator);
     run(argv: readonly string[], io?: CliIo): Promise<number>;
 }
 export declare function parseArgs(argv: readonly string[]): {
@@ -34,6 +40,14 @@ export declare function parseArgs(argv: readonly string[]): {
     readonly ok: true;
     readonly command: "remove-repo";
     readonly label: string;
+} | {
+    readonly ok: true;
+    readonly command: "server-show";
+    readonly config: BridgeServiceConfig;
+} | {
+    readonly ok: true;
+    readonly command: "server-set";
+    readonly serverUrl: string;
 } | {
     readonly ok: true;
     readonly command: "status";
@@ -45,6 +59,35 @@ export declare function parseArgs(argv: readonly string[]): {
     readonly config: BridgeServiceConfig;
     readonly mode: CleanupMode;
     readonly force: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-init";
+    readonly repoPath: string;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-doctor";
+    readonly repoPath: string;
+    readonly requirePinnedBase: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-smoke";
+    readonly repoPath: string;
+    readonly reportPath?: string;
+    readonly requirePinnedBase: boolean;
+    readonly probeLoopbackPort: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-reap";
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-on";
+    readonly allowOpenPublic: boolean;
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-off";
+} | {
+    readonly ok: true;
+    readonly command: "sandbox-status";
 } | {
     readonly ok: false;
     readonly error: string;
@@ -66,5 +109,5 @@ interface PairRunnerClaim {
 type PairRunnerClient = (args: PairArgs) => Promise<PairRunnerClaim>;
 export declare function parseCodexModelCatalog(raw: string): string[];
 export declare function parseCursorModelList(raw: string): string[];
-type CleanupMode = "stale" | "merged" | "all";
+type CleanupServiceFactory = (stateRoot: string) => CleanupService;
 export {};

package/dist/cli/cli.service.js

@@ -6,11 +6,19 @@ import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 import { resolveCursorAgentDirectLaunch } from "../shared/cursor-agent/cursor-agent.launch.js";
 import { buildWindowsCmdLaunch } from "../shared/process/windows-launch.js";
-import { redactSecrets, redactText } from "../shared/redaction/redaction.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 { commandHelpText, helpText } from "./cli.help.js";
@@ -20,10 +28,14 @@ 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") {
@@ -58,11 +70,29 @@ export class ForgeBridgeCliService {
                 io.stderr.write(`forge-bridge connect requires ${missing[0]}.\n`);
                 return 2;
             }
+            let dotNetToolchain;
+            try {
+                dotNetToolchain = await this.dotNetToolchainConfigurator([
+                    ...config.repoMappings.map((mapping) => mapping.localPath?.trim()),
+                    config.defaultRepoRoot.trim(),
+                ].filter((repoRoot) => Boolean(repoRoot)));
+            }
+            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;
@@ -88,6 +118,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 });
@@ -117,12 +148,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);
@@ -142,12 +227,12 @@ 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) {
@@ -233,6 +318,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) {
@@ -252,6 +346,9 @@ 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,
@@ -282,6 +379,230 @@ 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();
+    }
+}
 function parseConnectArgs(argv) {
     let serverUrl = null;
     let runnerId = null;
@@ -414,7 +735,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] : []
     };
@@ -470,7 +791,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) {
@@ -499,6 +820,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 ?? []
     };
 }
@@ -543,6 +866,12 @@ 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}/`;
 }
@@ -561,11 +890,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";
 }
@@ -602,7 +948,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");
@@ -611,20 +957,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`);
             }
         }
@@ -773,8 +1127,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;
@@ -798,6 +1152,7 @@ async function withDetectedCliProviders(config) {
     };
 }
 async function withDetectedPairCliProviders(args) {
+    const configured = configuredProviderCandidates(args.cliProviders);
     const detectedConfig = await withDetectedCliProviders({
         ...defaultBridgeServiceConfig({
             serverUrl: args.serverUrl,
@@ -807,7 +1162,7 @@ async function withDetectedPairCliProviders(args) {
             cleanupWorktrees: args.cleanupWorktrees,
             defaultRepoRoot: args.repoRoot ?? defaultBridgeServiceConfig().defaultRepoRoot
         })
-    });
+    }, configured);
     return {
         ...args,
         cliProviders: detectedConfig.cliProviders
@@ -822,6 +1177,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 });
-}

package/dist/cli/local-config.d.ts

@@ -7,6 +7,9 @@ export interface BridgeLocalConfig {
     readonly deviceName?: string;
     readonly defaultRepoRoot?: string;
     readonly cleanupWorktrees?: boolean;
+    readonly dockerEnabled?: boolean;
+    readonly dockerDesktopRecoveryEnabled?: boolean;
+    readonly allowOpenPublicSandbox?: boolean;
     readonly cliProviders?: readonly string[];
     readonly providerStatuses?: Readonly<Record<string, BridgeProviderStatus>>;
     readonly projectLabels?: readonly string[];
@@ -17,6 +20,8 @@ export interface BridgeLocalConfig {
     readonly supportsManagedForgeArtifacts?: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean;
     readonly supportsDraftRunOnce?: boolean;
+    readonly supportsDraftAttachments?: boolean;
+    readonly supportsDraftImageAttachments?: boolean;
 }
 export interface LocalRepoMapping extends BridgeRepoMapping {
     readonly label: string;
@@ -32,4 +37,6 @@ export declare function removeRepoMapping(label: string): Promise<{
     readonly config: BridgeLocalConfig;
     readonly removed: boolean;
 }>;
+export declare function setServerUrl(serverUrl: string): Promise<BridgeLocalConfig>;
+export declare function setSandboxPolicy(dockerEnabled: boolean, allowOpenPublicSandbox: boolean): Promise<BridgeLocalConfig>;
 export declare function providerStatusesFor(providers: readonly string[]): Readonly<Record<string, BridgeProviderStatus>>;