@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.eeefdb0d19c1

package/dist/sandbox/sandbox.types.d.ts

@@ -29,7 +29,10 @@ export interface SandboxPreflightResult {
     readonly generation: number;
     readonly runtimeVersion: string | null;
     readonly maxConcurrentSandboxes: number;
+    readonly totalMemoryBytes: number;
     readonly availableMemoryBytes: number;
+    readonly hostReserveBytes: number;
+    readonly admissionMemoryBytes: number;
     readonly availableCpuMillis: number;
     readonly availableWorkspaceBytes: number;
     readonly diskLow: boolean;

package/dist/sandbox/smoke.d.ts

@@ -0,0 +1,76 @@
+import type { BridgeServiceConfig } from "../bridge/bridge.types.js";
+import type { CommandRunner } from "./sandbox.types.js";
+export interface SandboxSmokeRequest {
+    readonly repoPath: string;
+    readonly reportPath?: string;
+    readonly requirePinnedBase?: boolean;
+    readonly probeLoopbackPort?: boolean;
+    readonly onProgress?: (message: string) => void;
+}
+export interface SandboxSmokeStage {
+    readonly name: string;
+    readonly status: "passed" | "failed";
+    readonly durationMs: number;
+}
+export interface SandboxSmokeReport {
+    readonly schemaVersion: 1;
+    readonly kind: "forge_sandbox_smoke";
+    readonly status: "passed" | "failed";
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly dispatchAttemptId: string;
+    readonly resourceLeaseId: string;
+    readonly repository: {
+        readonly name: string;
+        readonly contractDigest: string | null;
+        readonly dockerfileDigest: string | null;
+        readonly policyWarnings: readonly string[];
+    };
+    readonly docker: {
+        readonly runtimeVersion: string | null;
+        readonly contextConfigured: boolean;
+        readonly capacity: number;
+        readonly availableMemoryBytes: number;
+        readonly availableCpuMillis: number;
+        readonly availableWorkspaceBytes: number;
+    };
+    readonly publishedPortProbe: {
+        readonly containerPort: number;
+        readonly hostIp: "127.0.0.1";
+        readonly hostPort: number;
+    } | null;
+    readonly stages: readonly SandboxSmokeStage[];
+    readonly cleanup: {
+        readonly verified: boolean;
+        readonly removed: readonly string[];
+        readonly residual: {
+            readonly containers: number;
+            readonly networks: number;
+            readonly volumes: number;
+            readonly images: number;
+        };
+    };
+    readonly failure: {
+        readonly code: string;
+        readonly stage: string;
+        readonly message: string;
+    } | null;
+}
+export interface SandboxSmokeResult {
+    readonly report: SandboxSmokeReport;
+    readonly reportPath: string;
+}
+export declare class DockerSandboxSmoke {
+    private readonly config;
+    private readonly commands;
+    constructor(config: BridgeServiceConfig, commands?: CommandRunner);
+    run(request: SandboxSmokeRequest): Promise<SandboxSmokeResult>;
+    private createPreflight;
+    private stage;
+    private labelArgs;
+    private dockerArgs;
+    private requireDocker;
+    private cleanup;
+    private inventoryCount;
+}
+export declare function parseDockerAssignedLoopbackPort(output: string): SandboxSmokeReport["publishedPortProbe"];

package/dist/sandbox/smoke.js

@@ -0,0 +1,380 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "../shared/redaction/redaction.js";
+import { BoundedCommandRunner } from "./command-runner.js";
+import { validateDockerfilePolicy, validateSandboxContract } from "./contract.js";
+import { DockerPreflight } from "./preflight.js";
+const managedLabel = "dev.forge.managed";
+const smokeLabel = "dev.forge.smoke";
+const attemptLabel = "dev.forge.dispatch-attempt-id";
+const resourceLeaseLabel = "dev.forge.resource-lease-id";
+export class DockerSandboxSmoke {
+    config;
+    commands;
+    constructor(config, commands = new BoundedCommandRunner()) {
+        this.config = config;
+        this.commands = commands;
+    }
+    async run(request) {
+        const startedAt = new Date();
+        const dispatchAttemptId = randomUUID();
+        const resourceLeaseId = randomUUID();
+        const token = dispatchAttemptId.replaceAll("-", "").slice(0, 20);
+        const resources = {
+            image: `forge-sandbox-smoke:${token}`,
+            container: `forge-smoke-agent-${token}`,
+            network: `forge-smoke-network-${token}`,
+            volume: `forge-smoke-workspace-${token}`,
+            portFixtureContainer: `forge-smoke-port-${token}`,
+            portFixtureNetwork: `forge-smoke-port-network-${token}`,
+        };
+        const reportPath = path.resolve(request.reportPath ?? path.join(this.config.sandboxStateRoot, "smoke-reports", `${startedAt.toISOString().replaceAll(":", "-")}-${token}.json`));
+        const evidence = {
+            contractDigest: null,
+            dockerfileDigest: null,
+            policyWarnings: [],
+            preflight: null,
+            stages: [],
+            removed: [],
+            residual: { containers: -1, networks: -1, volumes: -1, images: -1 },
+            cleanupVerified: false,
+            publishedPortProbe: null,
+            failure: null,
+        };
+        const preflight = this.createPreflight();
+        try {
+            await this.stage("doctor", evidence, request, async () => {
+                const forgePath = path.join(path.resolve(request.repoPath), ".forge");
+                const contractSource = await fs.readFile(path.join(forgePath, "forge.sandbox.yml"), "utf8");
+                const dockerfile = await fs.readFile(path.join(forgePath, "Dockerfile"), "utf8");
+                evidence.contractDigest = validateSandboxContract(contractSource).digest;
+                evidence.dockerfileDigest = `sha256:${createHash("sha256").update(dockerfile).digest("hex")}`;
+                evidence.policyWarnings = [...validateDockerfilePolicy(dockerfile, request.requirePinnedBase ?? false)];
+                evidence.preflight = await preflight.refresh();
+                if (!evidence.preflight.healthy) {
+                    throw new SmokeFailure(evidence.preflight.unavailableCode ?? "sandbox_preflight_failed", "doctor", evidence.preflight.unavailableReason ?? "Docker preflight did not report a healthy runtime.");
+                }
+            });
+            await this.stage("build_image", evidence, request, async () => {
+                const dockerfilePath = path.join(path.resolve(request.repoPath), ".forge", "Dockerfile");
+                await this.requireDocker("sandbox_smoke_build_failed", "build_image", [
+                    "build",
+                    "--tag", resources.image,
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    "--file", dockerfilePath,
+                    path.resolve(request.repoPath),
+                ], { timeoutMs: 15 * 60_000, maxOutputBytes: 64 * 1024 });
+            });
+            await this.stage("create_resources", evidence, request, async () => {
+                await this.requireDocker("sandbox_smoke_network_failed", "create_resources", [
+                    "network", "create", "--internal",
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    resources.network,
+                ]);
+                await this.requireDocker("sandbox_smoke_volume_failed", "create_resources", [
+                    "volume", "create",
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    resources.volume,
+                ]);
+                await this.requireDocker("sandbox_smoke_container_failed", "create_resources", [
+                    "create",
+                    "--name", resources.container,
+                    ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                    "--network", resources.network,
+                    "--read-only",
+                    "--cap-drop", "ALL",
+                    "--security-opt", "no-new-privileges",
+                    "--pids-limit", "64",
+                    "--memory", String(256 * 1024 ** 2),
+                    "--memory-swap", String(256 * 1024 ** 2),
+                    "--cpus", "0.5",
+                    "--tmpfs", "/tmp:rw,nosuid,nodev,size=64m,uid=10001,gid=10001",
+                    "--user", "10001:10001",
+                    "--workdir", "/workspace",
+                    "--mount", `type=volume,src=${resources.volume},dst=/workspace,volume-nocopy`,
+                    "--env", `FORGE_SMOKE_ATTEMPT_ID=${dispatchAttemptId}`,
+                    "--env", `FORGE_RESOURCE_LEASE_ID=${resourceLeaseId}`,
+                    "--entrypoint", "/bin/sh",
+                    resources.image,
+                    "-lc",
+                    `set -eu; test "$PWD" = /workspace; test "$FORGE_SMOKE_ATTEMPT_ID" = "${dispatchAttemptId}"; test "$FORGE_RESOURCE_LEASE_ID" = "${resourceLeaseId}"; test ! -S /var/run/docker.sock; printf 'FORGE_SANDBOX_SMOKE_OK\\n'`,
+                ]);
+            });
+            await this.stage("verify_isolation", evidence, request, async () => {
+                const inspect = await this.requireDocker("sandbox_smoke_inspect_failed", "verify_isolation", [
+                    "inspect", "--format",
+                    "{{json .Mounts}}|{{.Config.User}}|{{.HostConfig.ReadonlyRootfs}}|{{.HostConfig.Privileged}}|{{json .HostConfig.CapDrop}}|{{json .HostConfig.PortBindings}}",
+                    resources.container,
+                ]);
+                const [mountsJson, user, readonlyRootfs, privileged, capDropJson, portBindingsJson] = inspect.stdout.trim().split("|");
+                const mounts = JSON.parse(mountsJson ?? "[]");
+                const capDrop = JSON.parse(capDropJson ?? "[]");
+                const workspaceMounted = mounts.some((mount) => mount.Destination === "/workspace" && mount.Name === resources.volume);
+                if (!workspaceMounted || user !== "10001:10001" || readonlyRootfs !== "true" || privileged !== "false"
+                    || !capDrop.includes("ALL") || !["null", "{}"].includes(portBindingsJson ?? "")) {
+                    throw new SmokeFailure("sandbox_smoke_isolation_failed", "verify_isolation", "The disposable container did not match the hardened smoke profile.");
+                }
+            });
+            await this.stage("execute", evidence, request, async () => {
+                const result = await this.requireDocker("sandbox_smoke_execution_failed", "execute", ["start", "--attach", resources.container]);
+                if (!result.stdout.includes("FORGE_SANDBOX_SMOKE_OK")) {
+                    throw new SmokeFailure("sandbox_smoke_marker_missing", "execute", "The disposable container exited without its success marker.");
+                }
+            });
+            if (request.probeLoopbackPort) {
+                await this.stage("discover_loopback_port", evidence, request, async () => {
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "network", "create",
+                        ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                        resources.portFixtureNetwork,
+                    ]);
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "create",
+                        "--name", resources.portFixtureContainer,
+                        ...this.labelArgs(dispatchAttemptId, resourceLeaseId),
+                        "--network", resources.portFixtureNetwork,
+                        "--publish", "127.0.0.1::8080/tcp",
+                        "--read-only",
+                        "--cap-drop", "ALL",
+                        "--security-opt", "no-new-privileges",
+                        "--pids-limit", "32",
+                        "--memory", String(128 * 1024 ** 2),
+                        "--memory-swap", String(128 * 1024 ** 2),
+                        "--cpus", "0.25",
+                        "--tmpfs", "/tmp:rw,nosuid,nodev,size=16m,uid=10001,gid=10001",
+                        "--user", "10001:10001",
+                        "--entrypoint", "/bin/sh",
+                        resources.image,
+                        "-lc", "exec sleep 300",
+                    ]);
+                    await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", [
+                        "start", resources.portFixtureContainer,
+                    ]);
+                    const inspect = await this.requireDocker("sandbox_smoke_port_discovery_failed", "discover_loopback_port", ["inspect", "--format", "{{json .NetworkSettings.Ports}}", resources.portFixtureContainer]);
+                    evidence.publishedPortProbe = parseDockerAssignedLoopbackPort(inspect.stdout);
+                    if (!evidence.publishedPortProbe) {
+                        throw new SmokeFailure("sandbox_smoke_port_discovery_failed", "discover_loopback_port", "Docker did not assign exactly one valid loopback host port to the fixture.");
+                    }
+                });
+            }
+        }
+        catch (error) {
+            evidence.failure = failureFrom(error);
+        }
+        finally {
+            await this.cleanup(resources, dispatchAttemptId, evidence, request);
+            await preflight.release();
+        }
+        if (!evidence.cleanupVerified && !evidence.failure) {
+            evidence.failure = {
+                code: "sandbox_smoke_cleanup_failed",
+                stage: "cleanup",
+                message: "Exact-label cleanup verification found residual or unreadable Docker resources.",
+            };
+        }
+        const completedAt = new Date();
+        const report = redactSecrets({
+            schemaVersion: 1,
+            kind: "forge_sandbox_smoke",
+            status: evidence.failure || !evidence.cleanupVerified ? "failed" : "passed",
+            startedAt: startedAt.toISOString(),
+            completedAt: completedAt.toISOString(),
+            dispatchAttemptId,
+            resourceLeaseId,
+            repository: {
+                name: path.basename(path.resolve(request.repoPath)),
+                contractDigest: evidence.contractDigest,
+                dockerfileDigest: evidence.dockerfileDigest,
+                policyWarnings: evidence.policyWarnings,
+            },
+            docker: {
+                runtimeVersion: evidence.preflight?.runtimeVersion ?? null,
+                contextConfigured: this.config.dockerContext.length > 0,
+                capacity: evidence.preflight?.maxConcurrentSandboxes ?? 0,
+                availableMemoryBytes: evidence.preflight?.availableMemoryBytes ?? 0,
+                availableCpuMillis: evidence.preflight?.availableCpuMillis ?? 0,
+                availableWorkspaceBytes: evidence.preflight?.availableWorkspaceBytes ?? 0,
+            },
+            publishedPortProbe: evidence.publishedPortProbe,
+            stages: evidence.stages,
+            cleanup: {
+                verified: evidence.cleanupVerified,
+                removed: evidence.removed,
+                residual: evidence.residual,
+            },
+            failure: evidence.failure,
+        });
+        await writeReport(reportPath, report);
+        return { report, reportPath };
+    }
+    createPreflight() {
+        return new DockerPreflight({
+            dockerExecutable: this.config.dockerExecutable,
+            dockerContext: this.config.dockerContext,
+            stateRoot: this.config.sandboxStateRoot,
+            maxConcurrentSandboxes: this.config.maxConcurrentSandboxes,
+            diskHighWatermarkPercent: this.config.diskHighWatermarkPercent,
+            diskLowWatermarkPercent: this.config.diskLowWatermarkPercent,
+            minimumWorkspaceBytes: this.config.minimumWorkspaceBytes,
+            hostMemoryReserveBytes: this.config.sandboxHostMemoryReserveBytes,
+            defaultWorkerMemoryLimitBytes: this.config.defaultSandboxWorkerMemoryLimitBytes,
+            defaultServiceMemoryLimitBytes: this.config.defaultSandboxServiceMemoryLimitBytes,
+            runtimeOverheadBytes: this.config.sandboxRuntimeOverheadBytes,
+            requireRootless: this.config.requireRootlessDocker,
+        }, this.commands);
+    }
+    async stage(name, evidence, request, action) {
+        request.onProgress?.(name);
+        const started = Date.now();
+        try {
+            await action();
+            evidence.stages.push({ name, status: "passed", durationMs: Date.now() - started });
+        }
+        catch (error) {
+            evidence.stages.push({ name, status: "failed", durationMs: Date.now() - started });
+            if (error instanceof SmokeFailure)
+                throw error;
+            if (name === "doctor" && error instanceof Error && error.message.includes("docker_context_owned")) {
+                throw new SmokeFailure("sandbox_smoke_context_owned", name, "The Docker context is owned by a connected Forge bridge. Stop the bridge and retry.");
+            }
+            throw new SmokeFailure(`sandbox_smoke_${name}_failed`, name, name === "doctor"
+                ? "The repository contract, Dockerfile, or Docker preflight check failed."
+                : `The ${name.replaceAll("_", " ")} stage failed.`);
+        }
+    }
+    labelArgs(dispatchAttemptId, resourceLeaseId) {
+        return [
+            "--label", `${managedLabel}=true`,
+            "--label", `${smokeLabel}=true`,
+            "--label", `${attemptLabel}=${dispatchAttemptId}`,
+            "--label", `${resourceLeaseLabel}=${resourceLeaseId}`,
+        ];
+    }
+    dockerArgs(args) {
+        return this.config.dockerContext ? ["--context", this.config.dockerContext, ...args] : [...args];
+    }
+    async requireDocker(code, stage, args, options = {}) {
+        let result;
+        try {
+            result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                timeoutMs: options.timeoutMs ?? 60_000,
+                maxOutputBytes: options.maxOutputBytes ?? 16 * 1024,
+            });
+        }
+        catch {
+            throw new SmokeFailure(code, stage, "Docker could not execute the requested smoke stage.");
+        }
+        if (result.exitCode !== 0) {
+            throw new SmokeFailure(code, stage, `Docker exited with code ${result.exitCode} during the smoke stage.`);
+        }
+        return result;
+    }
+    async cleanup(resources, dispatchAttemptId, evidence, request) {
+        const started = Date.now();
+        request.onProgress?.("cleanup");
+        const removals = [
+            ["portFixtureContainer", ["rm", "--force", resources.portFixtureContainer]],
+            ["container", ["rm", "--force", resources.container]],
+            ["portFixtureNetwork", ["network", "rm", resources.portFixtureNetwork]],
+            ["network", ["network", "rm", resources.network]],
+            ["volume", ["volume", "rm", "--force", resources.volume]],
+            ["image", ["image", "rm", "--force", resources.image]],
+        ];
+        for (const [kind, args] of removals) {
+            try {
+                const result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                    timeoutMs: 60_000,
+                    maxOutputBytes: 8 * 1024,
+                });
+                if (result.exitCode === 0)
+                    evidence.removed.push(kind);
+            }
+            catch {
+                // Exact-label inventory below is authoritative for cleanup verification.
+            }
+        }
+        evidence.residual = {
+            containers: await this.inventoryCount(["ps", "--all", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            networks: await this.inventoryCount(["network", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            volumes: await this.inventoryCount(["volume", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+            images: await this.inventoryCount(["image", "ls", "--quiet", "--filter", `label=${attemptLabel}=${dispatchAttemptId}`]),
+        };
+        evidence.cleanupVerified = Object.values(evidence.residual).every((count) => count === 0);
+        evidence.stages.push({
+            name: "cleanup",
+            status: evidence.cleanupVerified ? "passed" : "failed",
+            durationMs: Date.now() - started,
+        });
+    }
+    async inventoryCount(args) {
+        try {
+            const result = await this.commands.run(this.config.dockerExecutable, this.dockerArgs(args), {
+                timeoutMs: 30_000,
+                maxOutputBytes: 64 * 1024,
+            });
+            if (result.exitCode !== 0)
+                return -1;
+            return result.stdout.split(/\r?\n/u).filter((line) => line.trim().length > 0).length;
+        }
+        catch {
+            return -1;
+        }
+    }
+}
+export function parseDockerAssignedLoopbackPort(output) {
+    try {
+        const parsed = JSON.parse(output.trim());
+        const bindings = Array.isArray(parsed)
+            ? parsed
+            : typeof parsed === "object" && parsed !== null
+                ? parsed["8080/tcp"]
+                : null;
+        if (!Array.isArray(bindings) || bindings.length !== 1)
+            return null;
+        const binding = bindings[0];
+        if (binding.HostIp !== "127.0.0.1" || typeof binding.HostPort !== "string" || !/^\d{1,5}$/u.test(binding.HostPort)) {
+            return null;
+        }
+        const hostPort = Number(binding.HostPort);
+        return hostPort >= 1 && hostPort <= 65535
+            ? { containerPort: 8080, hostIp: "127.0.0.1", hostPort }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+class SmokeFailure extends Error {
+    code;
+    stage;
+    constructor(code, stage, message) {
+        super(message);
+        this.code = code;
+        this.stage = stage;
+    }
+}
+function failureFrom(error) {
+    if (error instanceof SmokeFailure) {
+        return { code: error.code, stage: error.stage, message: error.message };
+    }
+    if (error instanceof Error && "code" in error && typeof error.code === "string") {
+        return {
+            code: `sandbox_smoke_${String(error.code).toLowerCase()}`,
+            stage: "doctor",
+            message: "The repository sandbox contract or Dockerfile could not be read or validated.",
+        };
+    }
+    return {
+        code: "sandbox_smoke_failed",
+        stage: "unknown",
+        message: "The disposable sandbox smoke attempt failed.",
+    };
+}
+async function writeReport(reportPath, report) {
+    await fs.mkdir(path.dirname(reportPath), { recursive: true, mode: 0o700 });
+    const temporary = `${reportPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(report, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(temporary, reportPath);
+    await fs.chmod(reportPath, 0o600).catch(() => undefined);
+}

package/dist/sandbox/worker-supervisor.js

@@ -31,6 +31,6 @@ export function terminationMessage(code) {
     switch (code) {
         case "sandbox_lease_expired": return "The durable execution lease expired inside the sandbox.";
         case "sandbox_wall_timeout": return "The sandbox reached its hard wall-clock limit.";
-        case "sandbox_idle_timeout": return "The sandbox produced no control or process activity before its idle limit.";
+        case "sandbox_idle_timeout": return "The provider produced no process activity before the sandbox idle limit.";
     }
 }

package/dist/sandbox/worker.js

@@ -41,7 +41,7 @@ async function main() {
     let bundleSha256 = null;
     let bundleBytes = 0;
     const bundlePath = path.join(controlRoot, "output", "result.bundle");
-    if (!runOutcome.terminationCode && await exists(path.join(workspace, ".git"))) {
+    if (!runOutcome.terminationCode && runOutcome.exitCode === 0 && await exists(path.join(workspace, ".git"))) {
         resultCommitSha = (await capture("git", ["-C", workspace, "rev-parse", "HEAD"])).trim();
         const resultRef = `refs/forge/results/${attemptId.replace(/-/g, "")}`;
         await runRequired("git", ["-C", workspace, "update-ref", resultRef, resultCommitSha]);
@@ -123,10 +123,7 @@ async function run(command, args, watchdog) {
             readingUpdate = true;
             fs.readFile(watchdog.updatePath, "utf8")
                 .then(value => {
-                const applied = watchdog.deadline.apply(JSON.parse(value));
-                if (applied)
-                    watchdog.supervisor.touch();
-                return applied;
+                return watchdog.deadline.apply(JSON.parse(value));
             })
                 .catch(() => false)
                 .finally(() => { readingUpdate = false; });

package/dist/sandbox/workspace.service.d.ts

@@ -10,3 +10,4 @@ export declare class SandboxWorkspaceService implements WorktreeService {
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     release(_handle: WorktreeHandle): Promise<void>;
 }
+export declare function sandboxInputRefFromBundle(bundleHeads: string, inputCommitSha: string): string;

package/dist/sandbox/workspace.service.js

@@ -2,7 +2,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { GitClient } from "../shared/git/git.js";
 import { injectWorktreeArtifacts, filterArtifactsForLane } from "../worktree/artifact-injector.js";
-import { normalizeBranchName } from "../worktree/worktree.service.js";
+import { hydratePriorPhaseArtifacts } from "../worktree/prior-phase-artifact-hydrator.js";
+import { clearRunArtifactRoots, normalizeBranchName } from "../worktree/worktree.service.js";
 export class SandboxWorkspaceService {
     workspace;
     bundlePath;
@@ -23,7 +24,10 @@ export class SandboxWorkspaceService {
         const entries = await fs.readdir(this.workspace);
         if (entries.length > 0)
             throw new Error("Sandbox workspace must be empty before bundle import.");
-        await this.git.run(path.dirname(this.workspace), ["clone", "--no-checkout", "--no-local", this.bundlePath, this.workspace]);
+        const bundleHeads = await this.git.run(path.dirname(this.workspace), ["bundle", "list-heads", this.bundlePath]);
+        const inputRef = sandboxInputRefFromBundle(bundleHeads, this.inputCommitSha);
+        await this.git.run(path.dirname(this.workspace), ["init", this.workspace]);
+        await this.git.run(this.workspace, ["fetch", "--no-tags", "--no-write-fetch-head", this.bundlePath, `${inputRef}:refs/forge/input`]);
         const actualSha = (await this.git.run(this.workspace, ["rev-parse", "--verify", `${this.inputCommitSha}^{commit}`])).trim();
         if (actualSha.toLowerCase() !== this.inputCommitSha.toLowerCase())
             throw new Error("Imported bundle does not contain the exact recorded input commit.");
@@ -32,18 +36,37 @@ export class SandboxWorkspaceService {
         await this.git.run(this.workspace, ["config", "user.email", "forge-agent@forge.local"]);
         await this.git.run(this.workspace, ["config", "user.name", "Forge Agent"]);
         await this.git.run(this.workspace, ["config", "core.hooksPath", "/dev/null"]);
+        await clearRunArtifactRoots(this.workspace, request);
         const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
-        if (artifacts.length > 0)
-            await injectWorktreeArtifacts(this.workspace, artifacts);
+        if (artifacts.length > 0) {
+            const trackedForgePaths = new Set((await this.git.run(this.workspace, ["ls-files", "-z", "--", ".forge"]))
+                .split("\0")
+                .filter(Boolean)
+                .map(value => value.replaceAll("\\", "/")));
+            await injectWorktreeArtifacts(this.workspace, artifacts, trackedForgePaths);
+        }
+        const hydratedPriorPhaseArtifactCount = await hydratePriorPhaseArtifacts(this.workspace, request.priorPhaseArtifacts);
         return {
             repoPath: this.workspace,
             worktreePath: this.workspace,
             branchName,
             baseBranch: request.baseBranch,
-            cleanupWorktrees: false
+            cleanupWorktrees: false,
+            hydratedPriorPhaseArtifactCount
         };
     }
     async release(_handle) {
         // The host supervisor owns the workspace volume lifecycle.
     }
 }
+export function sandboxInputRefFromBundle(bundleHeads, inputCommitSha) {
+    const expectedSha = inputCommitSha.toLowerCase();
+    const matches = bundleHeads
+        .split(/\r?\n/u)
+        .map(line => /^([0-9a-f]{40}|[0-9a-f]{64}) (refs\/forge\/inputs\/[0-9a-f]{32})$/iu.exec(line.trim()))
+        .filter((match) => Boolean(match) && match[1].toLowerCase() === expectedSha);
+    if (matches.length !== 1) {
+        throw new Error("Sandbox input bundle does not expose the exact recorded input ref.");
+    }
+    return matches[0][2];
+}

package/dist/session/managed-attempt-tools.d.ts

@@ -0,0 +1,12 @@
+export declare const managedAttemptToolNames: readonly ["forge.run_managed_command", "run_managed_command", "forge.start_managed_command", "start_managed_command", "forge.get_managed_command", "get_managed_command", "forge.reset_generated_outputs", "reset_generated_outputs"];
+export declare function isManagedAttemptTool(name: string): boolean;
+export declare function managedAttemptToolDefinition(name: string): unknown;
+export interface ManagedAttemptToolResult {
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    readonly structuredContent: Readonly<Record<string, unknown>>;
+    readonly isError?: boolean;
+}
+export declare function callManagedAttemptTool(name: string, input: unknown, worktreePath: string): Promise<ManagedAttemptToolResult>;