@loucompanion/forge-bridge 0.1.3-dev.f2b8822ce953 → 0.1.3-dev.fbe15023cdfe

package/dist/cli/cli.service.js

@@ -6,11 +6,18 @@ 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 { 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 +27,12 @@ export class ForgeBridgeCliService {
     sessions;
     bridgeFactory;
     pairRunner;
-    constructor(sessions = new BridgeSessionService(), bridgeFactory = (config) => new ForgeBridgeService(config), pairRunner = claimBridgeRunner) {
+    cleanupFactory;
+    constructor(sessions = new BridgeSessionService(), bridgeFactory = (config) => new ForgeBridgeService(config), pairRunner = claimBridgeRunner, cleanupFactory = stateRoot => new ManagedWorktreeCleanupService(stateRoot)) {
         this.sessions = sessions;
         this.bridgeFactory = bridgeFactory;
         this.pairRunner = pairRunner;
+        this.cleanupFactory = cleanupFactory;
     }
     async run(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
         if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
@@ -88,6 +97,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 +127,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 +206,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 +297,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 +325,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 +358,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;
@@ -470,7 +770,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 +799,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 +845,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 +869,27 @@ function connectStartupText(config) {
         `  repo folder: ${config.defaultRepoRoot || "not configured"}`,
         `  providers: ${formatList(config.cliProviders)}`,
         `  cleanup worktrees: ${config.cleanupWorktrees ? "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 +926,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 +935,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`);
             }
         }
@@ -822,6 +1154,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,8 @@ export interface BridgeLocalConfig {
     readonly deviceName?: string;
     readonly defaultRepoRoot?: string;
     readonly cleanupWorktrees?: boolean;
+    readonly dockerEnabled?: boolean;
+    readonly allowOpenPublicSandbox?: boolean;
     readonly cliProviders?: readonly string[];
     readonly providerStatuses?: Readonly<Record<string, BridgeProviderStatus>>;
     readonly projectLabels?: readonly string[];
@@ -17,6 +19,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 +36,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>>;

package/dist/cli/local-config.js

@@ -45,6 +45,12 @@ export function applyLocalConfigDefaults(config, local) {
         deviceName: process.env.FORGE_DEVICE_NAME ?? local.deviceName ?? config.deviceName,
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? local.defaultRepoRoot ?? config.defaultRepoRoot,
         cleanupWorktrees: local.cleanupWorktrees ?? config.cleanupWorktrees,
+        dockerEnabled: process.env.FORGE_DOCKER_SANDBOX === undefined
+            ? local.dockerEnabled ?? config.dockerEnabled
+            : config.dockerEnabled,
+        allowOpenPublicSandbox: process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX === undefined
+            ? local.allowOpenPublicSandbox ?? config.allowOpenPublicSandbox
+            : config.allowOpenPublicSandbox,
         cliProviders,
         providerStatuses: normalizeProviderStatuses(local.providerStatuses) ?? providerStatusesFor(cliProviders),
         projectLabels: local.projectLabels ?? config.projectLabels,
@@ -54,7 +60,9 @@ export function applyLocalConfigDefaults(config, local) {
         supportsManagedWorktrees: local.supportsManagedWorktrees ?? config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: local.supportsManagedForgeArtifacts ?? config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: local.supportsRunnerAuthoredPhaseArtifacts ?? config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce
+        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce,
+        supportsDraftAttachments: local.supportsDraftAttachments ?? config.supportsDraftAttachments,
+        supportsDraftImageAttachments: local.supportsDraftImageAttachments ?? config.supportsDraftImageAttachments
     };
 }
 export async function addRepoMapping(label, repoPath) {
@@ -86,6 +94,19 @@ export async function removeRepoMapping(label) {
     await writeLocalConfig(next);
     return { config: next, removed: after.length !== before.length };
 }
+export async function setServerUrl(serverUrl) {
+    const normalized = normalizeServerUrl(serverUrl);
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, serverUrl: normalized });
+    await writeLocalConfig(next);
+    return next;
+}
+export async function setSandboxPolicy(dockerEnabled, allowOpenPublicSandbox) {
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, dockerEnabled, allowOpenPublicSandbox });
+    await writeLocalConfig(next);
+    return next;
+}
 export function providerStatusesFor(providers) {
     return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
 }
@@ -104,6 +125,8 @@ function normalizeLocalConfig(config) {
         deviceName: cleanString(config.deviceName),
         defaultRepoRoot: cleanString(config.defaultRepoRoot),
         cleanupWorktrees: config.cleanupWorktrees,
+        dockerEnabled: config.dockerEnabled,
+        allowOpenPublicSandbox: config.allowOpenPublicSandbox,
         cliProviders: cleanList(config.cliProviders),
         providerStatuses: normalizeProviderStatuses(config.providerStatuses),
         projectLabels: cleanList(config.projectLabels),
@@ -113,7 +136,9 @@ function normalizeLocalConfig(config) {
         supportsManagedWorktrees: config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: config.supportsDraftRunOnce
+        supportsDraftRunOnce: config.supportsDraftRunOnce,
+        supportsDraftAttachments: config.supportsDraftAttachments,
+        supportsDraftImageAttachments: config.supportsDraftImageAttachments
     };
 }
 function emptyConfig() {
@@ -196,10 +221,11 @@ function normalizeQaAppLaunchTarget(value) {
         command: cleanString(value.command),
         working_directory: cleanString(value.working_directory),
         ready_url: cleanString(value.ready_url),
+        managed_runtime_port: cleanString(value.managed_runtime_port),
         routes,
         notes: cleanString(value.notes)
     };
-    return normalized.url || normalized.command || normalized.ready_url || routes?.length
+    return normalized.url || normalized.command || normalized.ready_url || normalized.managed_runtime_port
         ? normalized
         : undefined;
 }
@@ -207,6 +233,24 @@ function cleanString(value) {
     const clean = value?.trim();
     return clean ? clean : undefined;
 }
+function normalizeServerUrl(value) {
+    const clean = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(clean);
+    }
+    catch {
+        throw new Error(`Invalid Forge server URL: ${value}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Forge server URL must use http or https.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Forge server URL cannot include credentials, a query string, or a fragment.");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/+$/u, "") || "/";
+    return parsed.toString().replace(/\/$/u, "");
+}
 function cleanList(values) {
     const clean = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
     return clean.length > 0 ? clean : undefined;

package/dist/runtime/attempt-node-runtime-launcher.d.ts

@@ -0,0 +1,17 @@
+import type { AttemptProcessChildHandle, AttemptProcessSupervisor } from "./attempt-process-supervisor.js";
+import type { HostPortLeaseOwner } from "./host-port-broker.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import type { HostListenerOwnership, NodeRuntimeCommandLauncher, NodeRuntimeLaunchRequest, NodeRuntimeReadinessDiagnostics } from "./node-host-runtime-adapter.js";
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export declare class AttemptNodeRuntimeLauncher implements NodeRuntimeCommandLauncher<AttemptProcessChildHandle> {
+    private readonly supervisor;
+    private readonly owner;
+    private readonly logDirectory;
+    private readonly listenerInspector;
+    private readonly diagnosticsByChild;
+    constructor(supervisor: AttemptProcessSupervisor, owner: HostPortLeaseOwner, logDirectory: string, listenerInspector?: HostListenerInspector);
+    launch(request: NodeRuntimeLaunchRequest, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    inspectListener(child: AttemptProcessChildHandle, request: NodeRuntimeLaunchRequest): Promise<HostListenerOwnership>;
+    stop(child: AttemptProcessChildHandle): Promise<void>;
+    readinessDiagnostics(child: AttemptProcessChildHandle): Promise<NodeRuntimeReadinessDiagnostics>;
+}