lastlight 0.1.8 → 0.2.0

package/dist/sandbox/egress-firewall-config.test.js

@@ -0,0 +1,244 @@
+import { describe, it, expect } from "vitest";
+import { COREDNS_OPEN_IP, COREDNS_STRICT_IP, NGINX_OPEN_IP, NGINX_STRICT_IP, OTEL_COLLECTOR_IP, OTEL_COLLECTOR_OTLP_GRPC_PORT, OTEL_COLLECTOR_OTLP_HTTP_PORT, OTEL_COLLECTOR_SANDBOX_ENDPOINT, renderCorefileOpen, renderCorefileStrict, renderNginxOpenConf, renderNginxStrictConf, renderOtelCollectorConfig, SANDBOX_EGRESS_SUBNET, } from "./egress-firewall-config.js";
+import { DEFAULT_ALLOWLIST } from "./egress-allowlist.js";
+import { parse as parseYaml } from "yaml";
+describe("static IP constants", () => {
+    it("all four service IPs sit inside the sandbox-egress subnet", () => {
+        const prefix = SANDBOX_EGRESS_SUBNET.split("/")[0].split(".").slice(0, 3).join(".");
+        for (const ip of [COREDNS_STRICT_IP, COREDNS_OPEN_IP, NGINX_STRICT_IP, NGINX_OPEN_IP]) {
+            expect(ip.startsWith(prefix + ".")).toBe(true);
+        }
+    });
+    it("strict and open IPs are distinct in both pairs", () => {
+        expect(COREDNS_STRICT_IP).not.toBe(COREDNS_OPEN_IP);
+        expect(NGINX_STRICT_IP).not.toBe(NGINX_OPEN_IP);
+    });
+});
+describe("nginx strict config", () => {
+    const conf = renderNginxStrictConf();
+    it("listens on 443 with ssl_preread enabled", () => {
+        expect(conf).toMatch(/listen\s+443;/);
+        expect(conf).toMatch(/ssl_preread\s+on;/);
+    });
+    it("defaults unknown SNIs to a black-hole upstream (instant reset)", () => {
+        expect(conf).toMatch(/default\s+127\.0\.0\.1:1;/);
+    });
+    it("emits a leading-dot map entry per allowlist host (apex+subdomain match)", () => {
+        for (const host of DEFAULT_ALLOWLIST) {
+            // nginx's `.foo.com` syntax matches `foo.com` and any subdomain.
+            // Upstream is the live SNI value, not pinned at config time.
+            expect(conf).toContain(`.${host} $ssl_preread_server_name:443;`);
+        }
+    });
+    it("uses docker's embedded DNS as the upstream resolver", () => {
+        expect(conf).toMatch(/resolver\s+127\.0\.0\.11/);
+    });
+    it("declares `hostnames` in the map block so leading-dot wildcards work", () => {
+        // Without `hostnames;`, nginx's `map` does exact string match only —
+        // `.github.com` becomes a literal key that never matches anything.
+        // We hit this in prod: every allowlisted host fell through to the
+        // black-hole default. Pin the contract so it can't regress.
+        expect(conf).toMatch(/map\s+\$ssl_preread_server_name\s+\$upstream_target\s*\{\s*\n\s*hostnames;/);
+    });
+});
+describe("nginx open config", () => {
+    const conf = renderNginxOpenConf();
+    it("tunnels whatever SNI was sent — no allowlist map", () => {
+        expect(conf).toMatch(/proxy_pass\s+\$ssl_preread_server_name:443;/);
+        expect(conf).not.toMatch(/map\s+\$ssl_preread_server_name/);
+    });
+    it("still listens on 443 with ssl_preread enabled", () => {
+        expect(conf).toMatch(/listen\s+443;/);
+        expect(conf).toMatch(/ssl_preread\s+on;/);
+    });
+});
+describe("coredns strict Corefile", () => {
+    const conf = renderCorefileStrict();
+    it("uses a SINGLE template block with one match line per allowlist host", () => {
+        // CoreDNS only honours one `template` block per (class, type, zone) —
+        // multiple blocks silently shadow each other. Catching a regression
+        // matters because we hit this exact bug in prod.
+        const templateBlocks = conf.match(/template\s+IN\s+A\s*\{/g) || [];
+        expect(templateBlocks.length).toBe(1);
+        for (const host of DEFAULT_ALLOWLIST) {
+            const escaped = host.replaceAll(".", "\\.");
+            expect(conf).toContain(`(^|\\.)${escaped}\\.$`);
+        }
+    });
+    it("answers with the nginx-strict IP", () => {
+        expect(conf).toContain(`IN A ${NGINX_STRICT_IP}`);
+    });
+    it("catches every unmatched query with an NXDOMAIN template", () => {
+        expect(conf).toMatch(/template\s+IN\s+ANY\s*\{[\s\S]*rcode\s+NXDOMAIN[\s\S]*\}/);
+    });
+});
+describe("coredns open Corefile", () => {
+    const conf = renderCorefileOpen();
+    it("returns the nginx-open IP for arbitrary A queries", () => {
+        expect(conf).toContain(`IN A ${NGINX_OPEN_IP}`);
+    });
+    it("hard-denies cloud metadata literals even in unrestricted mode", () => {
+        // Each hard-deny host gets its own zone block so CoreDNS's
+        // longest-suffix routing intercepts the apex + subdomains before
+        // the catch-all `.` zone sees them.
+        expect(conf).toMatch(/metadata\.google\.internal:53\s*\{[\s\S]*?rcode\s+NXDOMAIN/);
+        expect(conf).toMatch(/169\.254\.169\.254:53\s*\{[\s\S]*?rcode\s+NXDOMAIN/);
+    });
+    it("returns NOERROR / empty for AAAA so IPv6 doesn't accidentally bypass us", () => {
+        expect(conf).toMatch(/template\s+IN\s+AAAA\s*\{[\s\S]*rcode\s+NOERROR[\s\S]*\}/);
+    });
+});
+describe("otel collector config", () => {
+    // Most tests run with forwarding active; the gating tests below cover inactive.
+    const renderActive = (env) => parseYaml(renderOtelCollectorConfig({ active: true, env }));
+    it("sandbox endpoint points at the collector's static IP + OTLP/HTTP port", () => {
+        expect(OTEL_COLLECTOR_SANDBOX_ENDPOINT).toBe(`http://${OTEL_COLLECTOR_IP}:${OTEL_COLLECTOR_OTLP_HTTP_PORT}`);
+    });
+    it("receives OTLP on both http and grpc, on all interfaces", () => {
+        const cfg = renderActive({});
+        expect(cfg.receivers.otlp.protocols.http.endpoint).toBe(`0.0.0.0:${OTEL_COLLECTOR_OTLP_HTTP_PORT}`);
+        expect(cfg.receivers.otlp.protocols.grpc.endpoint).toBe(`0.0.0.0:${OTEL_COLLECTOR_OTLP_GRPC_PORT}`);
+    });
+    it("re-exports to the generic endpoint (as a base URL) with parsed auth headers on every signal", () => {
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector.example.com:4318",
+            OTEL_EXPORTER_OTLP_HEADERS: "api-key=secret-123,x-tenant=acme",
+        });
+        for (const signal of ["traces", "metrics", "logs"]) {
+            const exp = cfg.exporters[`otlphttp/${signal}`];
+            // Generic endpoint → `endpoint` field (collector appends /v1/<signal>).
+            expect(exp.endpoint).toBe("https://collector.example.com:4318");
+            expect(exp[`${signal}_endpoint`]).toBeUndefined();
+            expect(exp.headers).toEqual({ "api-key": "secret-123", "x-tenant": "acme" });
+            expect(cfg.service.pipelines[signal].exporters).toEqual([`otlphttp/${signal}`]);
+        }
+    });
+    it("routes per-signal endpoints to their own pipeline (no fallback-chain misrouting)", () => {
+        // The bug the reviewer flagged: separate traces/metrics endpoints must not
+        // both export to whichever one won a `||` chain.
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://traces.example.com/v1/traces",
+            OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: "https://metrics.example.com/v1/metrics",
+        });
+        // Signal-specific endpoints are used verbatim via `<signal>_endpoint`.
+        expect(cfg.exporters["otlphttp/traces"].traces_endpoint).toBe("https://traces.example.com/v1/traces");
+        expect(cfg.exporters["otlphttp/metrics"].metrics_endpoint).toBe("https://metrics.example.com/v1/metrics");
+        expect(cfg.service.pipelines.traces.exporters).toEqual(["otlphttp/traces"]);
+        expect(cfg.service.pipelines.metrics.exporters).toEqual(["otlphttp/metrics"]);
+        // logs had no endpoint configured → debug, not silently misrouted.
+        expect(cfg.service.pipelines.logs.exporters).toEqual(["debug"]);
+        expect(cfg.exporters.debug).toBeDefined();
+    });
+    it("honours a logs-only endpoint instead of dropping it (the silent-drop case)", () => {
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: "https://logs.example.com/v1/logs",
+        });
+        expect(cfg.exporters["otlphttp/logs"].logs_endpoint).toBe("https://logs.example.com/v1/logs");
+        expect(cfg.service.pipelines.logs.exporters).toEqual(["otlphttp/logs"]);
+        expect(cfg.service.pipelines.traces.exporters).toEqual(["debug"]);
+        expect(cfg.service.pipelines.metrics.exporters).toEqual(["debug"]);
+    });
+    it("lets a signal-specific endpoint override the generic one for just that signal", () => {
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_ENDPOINT: "https://generic.example.com",
+            OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://traces.example.com/v1/traces",
+        });
+        // traces → verbatim specific URL; metrics/logs → generic base.
+        expect(cfg.exporters["otlphttp/traces"].traces_endpoint).toBe("https://traces.example.com/v1/traces");
+        expect(cfg.exporters["otlphttp/metrics"].endpoint).toBe("https://generic.example.com");
+        expect(cfg.exporters["otlphttp/logs"].endpoint).toBe("https://generic.example.com");
+    });
+    it("applies per-signal header overrides, falling back to generic headers", () => {
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_ENDPOINT: "https://generic.example.com",
+            OTEL_EXPORTER_OTLP_HEADERS: "authorization=generic",
+            OTEL_EXPORTER_OTLP_TRACES_HEADERS: "authorization=traces-only",
+        });
+        expect(cfg.exporters["otlphttp/traces"].headers.authorization).toBe("traces-only");
+        expect(cfg.exporters["otlphttp/metrics"].headers.authorization).toBe("generic");
+    });
+    it("supports a non-443 / custom-port HTTPS backend the strict SNI firewall could not reach", () => {
+        // This is the case the reviewer flagged for the old direct-forward path.
+        // It now works because the collector dials the backend on its trusted
+        // outbound leg, not through ssl_preread.
+        const cfg = renderActive({ OTEL_EXPORTER_OTLP_ENDPOINT: "https://otel.internal:4318" });
+        expect(cfg.exporters["otlphttp/traces"].endpoint).toBe("https://otel.internal:4318");
+    });
+    it("preserves '=' inside header values (bearer tokens survive intact)", () => {
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_ENDPOINT: "https://b.example.com",
+            OTEL_EXPORTER_OTLP_HEADERS: "authorization=Bearer abc=def==",
+        });
+        expect(cfg.exporters["otlphttp/traces"].headers.authorization).toBe("Bearer abc=def==");
+    });
+    it("falls back to a debug exporter (no data leaves) when active but no backend is configured", () => {
+        const cfg = renderActive({});
+        expect(cfg.exporters.debug).toBeDefined();
+        expect(cfg.exporters["otlphttp/traces"]).toBeUndefined();
+        for (const signal of ["traces", "metrics", "logs"]) {
+            expect(cfg.service.pipelines[signal].exporters).toEqual(["debug"]);
+        }
+    });
+    it("produces valid YAML even with quote/backslash-bearing header values", () => {
+        // Crucially, a single quote in a header value no longer fails anything:
+        // it lives in the host-side collector config, never a sandbox shell wrap.
+        const cfg = renderActive({
+            OTEL_EXPORTER_OTLP_ENDPOINT: "https://b.example.com",
+            OTEL_EXPORTER_OTLP_HEADERS: `x-quote=it's "quoted" \\ backslash`,
+        });
+        expect(cfg.exporters["otlphttp/traces"].headers["x-quote"]).toBe(`it's "quoted" \\ backslash`);
+    });
+    it("drops CR/LF-bearing header pairs (no header injection, no broken YAML) but keeps the rest", () => {
+        // A newline in a header value would be header injection on the
+        // collector→backend leg and would also break the YAML scalar.
+        const raw = renderOtelCollectorConfig({
+            active: true,
+            env: {
+                OTEL_EXPORTER_OTLP_ENDPOINT: "https://b.example.com",
+                OTEL_EXPORTER_OTLP_HEADERS: "x-good=ok,x-bad=line1\nline2",
+            },
+        });
+        expect(() => parseYaml(raw)).not.toThrow();
+        const cfg = parseYaml(raw);
+        expect(cfg.exporters["otlphttp/traces"].headers).toEqual({ "x-good": "ok" });
+    });
+    describe("forwarding gate (security floor)", () => {
+        it("when inactive, drops every signal to debug and emits no backend endpoint or credential", () => {
+            const raw = renderOtelCollectorConfig({
+                active: false,
+                env: {
+                    OTEL_EXPORTER_OTLP_ENDPOINT: "https://real-backend.example.com",
+                    OTEL_EXPORTER_OTLP_HEADERS: "authorization=super-secret-token",
+                    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://traces.example.com",
+                },
+            });
+            // No backend URL or secret leaks into the generated file at all.
+            expect(raw).not.toContain("real-backend.example.com");
+            expect(raw).not.toContain("super-secret-token");
+            expect(raw).not.toContain("traces.example.com");
+            expect(raw).not.toContain("otlphttp");
+            const cfg = parseYaml(raw);
+            expect(cfg.exporters.debug).toBeDefined();
+            for (const signal of ["traces", "metrics", "logs"]) {
+                expect(cfg.service.pipelines[signal].exporters).toEqual(["debug"]);
+            }
+            // Receiver still listens so sandboxes don't get connection errors.
+            expect(cfg.receivers.otlp.protocols.http.endpoint).toBe(`0.0.0.0:${OTEL_COLLECTOR_OTLP_HTTP_PORT}`);
+        });
+    });
+});
+describe("apex + subdomain match sanity", () => {
+    // Pin behaviour: a bare entry like "github.com" must match both
+    // the apex and any subdomain in both backends.
+    it("'github.com' generates an nginx leading-dot map entry", () => {
+        const conf = renderNginxStrictConf();
+        expect(conf).toMatch(/\s\.github\.com\s+\$ssl_preread_server_name:443;/);
+    });
+    it("'github.com' generates a CoreDNS pattern matching apex + subdomains", () => {
+        const conf = renderCorefileStrict();
+        // (^|\.)github\.com\.$ matches both "github.com." and "api.github.com."
+        // in FQDN-with-trailing-dot form.
+        expect(conf).toContain("(^|\\.)github\\.com\\.$");
+    });
+});
+//# sourceMappingURL=egress-firewall-config.test.js.map

package/dist/sandbox/egress-firewall-config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress-firewall-config.test.js","sourceRoot":"","sources":["../../src/sandbox/egress-firewall-config.test.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/images.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sandbox image names + the docker availability probes. Kept in this
+ * dependency-light module (only `child_process`, no `./docker.js`) so callers
+ * like the workflow runner can check image availability without importing the
+ * full `DockerSandbox` machinery — `docker.ts` runs `promisify(execFile)` at
+ * module load, which trips test suites that mock `child_process`.
+ */
+/** The lean default sandbox image (`sandbox.Dockerfile`). */
+export declare const SANDBOX_IMAGE = "lastlight-sandbox:latest";
+/**
+ * The enriched browser-QA image (Playwright + Chromium baked in). Built only
+ * when QA is enabled (`sandbox-qa.Dockerfile`); a phase opts into it with
+ * `sandbox_image: qa`. Fixed name, deliberately not overridable.
+ */
+export declare const SANDBOX_IMAGE_QA = "lastlight-sandbox-qa:latest";
+/** Check if Docker sandbox mode is available (docker up + lean image built). */
+export declare function isSandboxAvailable(): boolean;
+/**
+ * Whether the browser-QA sandbox image is present on this host. Used by the
+ * runner to gracefully skip a `sandbox_image: qa` phase when the image hasn't
+ * been built (the lean default deploy), rather than failing the run.
+ */
+export declare function qaImageAvailable(): boolean;

package/dist/sandbox/images.js

@@ -0,0 +1,55 @@
+import { execFileSync } from "child_process";
+/**
+ * Sandbox image names + the docker availability probes. Kept in this
+ * dependency-light module (only `child_process`, no `./docker.js`) so callers
+ * like the workflow runner can check image availability without importing the
+ * full `DockerSandbox` machinery — `docker.ts` runs `promisify(execFile)` at
+ * module load, which trips test suites that mock `child_process`.
+ */
+/** The lean default sandbox image (`sandbox.Dockerfile`). */
+export const SANDBOX_IMAGE = "lastlight-sandbox:latest";
+/**
+ * The enriched browser-QA image (Playwright + Chromium baked in). Built only
+ * when QA is enabled (`sandbox-qa.Dockerfile`); a phase opts into it with
+ * `sandbox_image: qa`. Fixed name, deliberately not overridable.
+ */
+export const SANDBOX_IMAGE_QA = "lastlight-sandbox-qa:latest";
+/** Check if Docker sandbox mode is available (docker up + lean image built). */
+export function isSandboxAvailable() {
+    return dockerAvailable() && sandboxImageExists(SANDBOX_IMAGE);
+}
+/** Cached check — only probe for the QA image once per process. */
+let _qaImageAvailable = null;
+/**
+ * Whether the browser-QA sandbox image is present on this host. Used by the
+ * runner to gracefully skip a `sandbox_image: qa` phase when the image hasn't
+ * been built (the lean default deploy), rather than failing the run.
+ */
+export function qaImageAvailable() {
+    if (_qaImageAvailable === null) {
+        _qaImageAvailable = dockerAvailable() && sandboxImageExists(SANDBOX_IMAGE_QA);
+    }
+    return _qaImageAvailable;
+}
+function dockerAvailable() {
+    try {
+        execFileSync("docker", ["info"], { stdio: "ignore", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sandboxImageExists(imageName) {
+    try {
+        const out = execFileSync("docker", ["images", "-q", imageName], {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=images.js.map

package/dist/sandbox/images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../src/sandbox/images.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;GAMG;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAE9D,gFAAgF;AAChF,MAAM,UAAU,kBAAkB;IAChC,OAAO,eAAe,EAAE,IAAI,kBAAkB,CAAC,aAAa,CAAC,CAAC;AAChE,CAAC;AAED,mEAAmE;AACnE,IAAI,iBAAiB,GAAmB,IAAI,CAAC;AAE7C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,iBAAiB,KAAK,IAAI,EAAE,CAAC;QAC/B,iBAAiB,GAAG,eAAe,EAAE,IAAI,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,SAAS,eAAe;IACtB,IAAI,CAAC;QACH,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE;YAC9D,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/sandbox/index.d.ts

@@ -1,15 +1,34 @@
 import { DockerSandbox } from "./docker.js";
 export { DockerSandbox } from "./docker.js";
+export { SANDBOX_IMAGE, SANDBOX_IMAGE_QA, isSandboxAvailable, qaImageAvailable, } from "./images.js";
 /**
  * Clean up orphaned sandbox containers from previous runs.
  * Called on startup to remove containers that survived a harness restart.
  */
 export declare function cleanupOrphanedSandboxes(): void;
+export declare function sandboxAvailable(): boolean;
 /**
- * Check if Docker sandbox mode is available.
+ * Set up the per-task worktree directory (mkdir + optional pre-clone) without
+ * touching Docker. Used by the non-docker sandbox modes (gondolin / none) where
+ * agentic-pi runs in-process or in a VM rather than a container, but still
+ * wants a per-task workspace cloned from the target branch.
  */
-export declare function isSandboxAvailable(): boolean;
-export declare function sandboxAvailable(): boolean;
+export declare function setupTaskWorktree(opts: {
+    taskId: string;
+    stateDir: string;
+    sandboxDir?: string;
+    prePopulate?: {
+        owner: string;
+        repo: string;
+        branch: string;
+        token: string;
+        /** Owning run id — stamped into a marker so a reused per-PR workspace
+         * refreshes across runs but is preserved between phases of one run. */
+        runId?: string;
+        /** Clone shallowly (`--depth 1 --single-branch`) for read-only workflows. */
+        shallow?: boolean;
+    };
+}): string;
 /**
  * Create a sandbox for a task. Returns the sandbox and a cleanup function.
  * If Docker is not available, returns null (caller should fall back to direct execution).
@@ -19,8 +38,68 @@ export declare function createTaskSandbox(opts: {
     stateDir: string;
     sandboxDir?: string;
     env?: Record<string, string>;
+    /**
+     * When set, the harness clones the repo into workDir at the named branch
+     * before starting the sandbox container. The agent then enters a
+     * workspace that's already checked out, avoiding a redundant
+     * `clone_repo` MCP call inside the session.
+     *
+     * Token must be alphanumeric (shape asserted upstream) and is embedded
+     * into the clone URL just for this one-shot operation — git's own
+     * credential.helper inside the sandbox covers subsequent push/pull.
+     */
+    prePopulate?: {
+        owner: string;
+        repo: string;
+        branch: string;
+        token: string;
+        /** Owning run id — stamped into a marker so a reused per-PR workspace
+         * refreshes across runs but is preserved between phases of one run. */
+        runId?: string;
+        /** Clone shallowly (`--depth 1 --single-branch`) for read-only workflows. */
+        shallow?: boolean;
+    };
+    /**
+     * IP of the coredns sidecar to use as the sandbox's DNS resolver.
+     * Selects the egress policy: `172.30.0.10` (coredns-strict) for the
+     * default allowlist, `172.30.0.11` (coredns-open) for phases that
+     * declared `unrestricted_egress: true`. Passed to `docker run` as
+     * `--dns <ip>`. See src/sandbox/egress-firewall-config.ts.
+     */
+    dnsIp?: string;
+    /**
+     * Override the container image. Defaults to the lean `SANDBOX_IMAGE`; a
+     * browser-QA phase passes `SANDBOX_IMAGE_QA`. The caller is responsible for
+     * ensuring the image exists (see `qaImageAvailable`).
+     */
+    imageName?: string;
 }): Promise<{
     sandbox: DockerSandbox;
     workDir: string;
     cleanup: () => Promise<void>;
 } | null>;
+type PrePopulate = {
+    owner: string;
+    repo: string;
+    branch: string;
+    token: string;
+    runId?: string;
+    shallow?: boolean;
+};
+/**
+ * Clone the repo into `<workDir>/<repo>` at the given branch.
+ *
+ * Three cases:
+ * - **Fresh dir** (no `.git`): clone. `--depth 1 --single-branch` for
+ *   read-only workflows (`pre.shallow`), `--depth 50` otherwise.
+ * - **Same run revisiting the workspace** (`.git` exists, run marker matches
+ *   `pre.runId`): preserve — this is a later phase of the same run reading
+ *   what an earlier phase wrote (architect's `plan.md`, the reviewer's
+ *   checkout). No git ops.
+ * - **A fresh run reusing an old per-PR workspace** (`.git` exists, marker
+ *   differs/absent): fetch + hard-reset to the remote branch + `git clean`
+ *   that **keeps `node_modules`** so the next `npm install` is incremental.
+ *   This is the re-review fast path from issue #107.
+ */
+export { prePopulateWorkspace as __prePopulateWorkspaceForTest };
+declare function prePopulateWorkspace(workDir: string, pre: PrePopulate): void;