lastlight 0.3.0 → 0.5.1

package/dist/overlay-assets.d.ts

@@ -0,0 +1,20 @@
+export type OverlayAssetType = "workflow" | "cron" | "prompt" | "skill" | "agent-context";
+export interface OverlayAsset {
+    type: OverlayAssetType;
+    /** Logical name — workflow/cron/skill name, or the filename for prompts/context. */
+    name: string;
+    /** True when a same-named built-in exists under `coreRoot` (overlay shadows it);
+     *  false when the overlay adds something the built-ins don't have. */
+    shadowsDefault: boolean;
+}
+export interface EnumerateOpts {
+    /** Built-in asset tree (the lastlight checkout root). */
+    coreRoot?: string;
+    /** Overlay asset tree (the instance/ overlay root). */
+    overlayRoot?: string;
+}
+/**
+ * List every asset the overlay provides, tagging each as shadowing a built-in or
+ * a fresh addition. Returns `[]` when no overlay is configured or present.
+ */
+export declare function enumerateOverlayAssets(opts: EnumerateOpts): OverlayAsset[];

package/dist/overlay-assets.js

@@ -0,0 +1,114 @@
+/**
+ * Enumerate the assets a deployment overlay overrides or adds.
+ *
+ * The instance overlay (`$LASTLIGHT_OVERLAY_DIR`, prod `instance/`) can replace
+ * or add workflows, prompts, skills, and agent-context files by logical name —
+ * the layer-aware resolution lives in `src/workflows/loader.ts`. This module is
+ * the read-only inverse: given the built-in (`coreRoot`) and overlay
+ * (`overlayRoot`) trees, list every asset the overlay provides and whether it
+ * **shadows** a same-named built-in or is a fresh **addition**.
+ *
+ * It's a pure filesystem walk (no loader caches), so the host-local CLI
+ * (`lastlight server status`, `lastlight fork`) and the in-harness admin API
+ * (`GET /admin/api/overrides`) can share one source of truth.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function listFiles(dir, predicate) {
+    if (!isDir(dir))
+        return [];
+    return readdirSync(dir).filter(predicate).sort();
+}
+function listDirs(dir) {
+    if (!isDir(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => isDir(join(dir, n)))
+        .sort();
+}
+const isYaml = (n) => n.endsWith(".yaml") || n.endsWith(".yml");
+const isMarkdown = (n) => n.endsWith(".md");
+/** Read a workflow YAML's `name`/`kind` without throwing on malformed files. */
+function readWorkflowMeta(filePath) {
+    try {
+        const raw = parseYaml(readFileSync(filePath, "utf-8"));
+        if (!raw || typeof raw.name !== "string")
+            return null;
+        return { name: raw.name, kind: typeof raw.kind === "string" ? raw.kind : "" };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Index built-in assets by logical name so overlay entries can be tagged as
+ * shadowing vs adding. Workflows/crons are keyed by their YAML `name`; prompts,
+ * skills, and agent-context by filename / directory name.
+ */
+function indexBuiltins(coreRoot) {
+    const workflows = new Set();
+    const crons = new Set();
+    const workflowDir = join(coreRoot, "workflows");
+    for (const file of listFiles(workflowDir, isYaml)) {
+        const meta = readWorkflowMeta(join(workflowDir, file));
+        if (!meta)
+            continue;
+        (meta.kind === "cron" ? crons : workflows).add(meta.name);
+    }
+    return {
+        workflows,
+        crons,
+        prompts: new Set(listFiles(join(coreRoot, "workflows", "prompts"), isMarkdown)),
+        skills: new Set(listDirs(join(coreRoot, "skills"))),
+        agentContext: new Set(listFiles(join(coreRoot, "agent-context"), isMarkdown)),
+    };
+}
+/**
+ * List every asset the overlay provides, tagging each as shadowing a built-in or
+ * a fresh addition. Returns `[]` when no overlay is configured or present.
+ */
+export function enumerateOverlayAssets(opts) {
+    const { coreRoot, overlayRoot } = opts;
+    if (!overlayRoot || !isDir(overlayRoot))
+        return [];
+    const builtins = coreRoot && isDir(coreRoot)
+        ? indexBuiltins(coreRoot)
+        : { workflows: new Set(), crons: new Set(), prompts: new Set(), skills: new Set(), agentContext: new Set() };
+    const assets = [];
+    // Workflows + crons — keyed by YAML `name`, split by `kind`.
+    const overlayWorkflowDir = join(overlayRoot, "workflows");
+    for (const file of listFiles(overlayWorkflowDir, isYaml)) {
+        const meta = readWorkflowMeta(join(overlayWorkflowDir, file));
+        if (!meta)
+            continue;
+        const isCron = meta.kind === "cron";
+        assets.push({
+            type: isCron ? "cron" : "workflow",
+            name: meta.name,
+            shadowsDefault: (isCron ? builtins.crons : builtins.workflows).has(meta.name),
+        });
+    }
+    // Prompts — keyed by filename under workflows/prompts/.
+    for (const file of listFiles(join(overlayRoot, "workflows", "prompts"), isMarkdown)) {
+        assets.push({ type: "prompt", name: file, shadowsDefault: builtins.prompts.has(file) });
+    }
+    // Skills — keyed by directory name under skills/.
+    for (const dir of listDirs(join(overlayRoot, "skills"))) {
+        assets.push({ type: "skill", name: dir, shadowsDefault: builtins.skills.has(dir) });
+    }
+    // Agent-context — keyed by filename under agent-context/.
+    for (const file of listFiles(join(overlayRoot, "agent-context"), isMarkdown)) {
+        assets.push({ type: "agent-context", name: file, shadowsDefault: builtins.agentContext.has(file) });
+    }
+    return assets;
+}
+//# sourceMappingURL=overlay-assets.js.map

package/dist/overlay-assets.js.map

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

package/dist/overlay-assets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/overlay-assets.test.js

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { enumerateOverlayAssets } from "./overlay-assets.js";
+function makeTree() {
+    const root = mkdtempSync(join(tmpdir(), "overlay-assets-"));
+    const core = join(root, "core");
+    const overlay = join(root, "instance");
+    // Built-in assets.
+    mkdirSync(join(core, "workflows", "prompts"), { recursive: true });
+    mkdirSync(join(core, "skills", "building"), { recursive: true });
+    mkdirSync(join(core, "agent-context"), { recursive: true });
+    writeFileSync(join(core, "workflows", "build.yaml"), "kind: build\nname: build\n");
+    writeFileSync(join(core, "workflows", "cron-health.yaml"), "kind: cron\nname: cron-health\nworkflow: repo-health\n");
+    writeFileSync(join(core, "workflows", "prompts", "architect.md"), "# architect");
+    writeFileSync(join(core, "skills", "building", "SKILL.md"), "# building");
+    writeFileSync(join(core, "agent-context", "soul.md"), "# soul");
+    return { core, overlay };
+}
+describe("enumerateOverlayAssets", () => {
+    let core;
+    let overlay;
+    beforeEach(() => {
+        ({ core, overlay } = makeTree());
+    });
+    it("returns [] when no overlay is given or it doesn't exist", () => {
+        expect(enumerateOverlayAssets({ coreRoot: core })).toEqual([]);
+        expect(enumerateOverlayAssets({ coreRoot: core, overlayRoot: join(overlay, "nope") })).toEqual([]);
+    });
+    it("tags overlay assets as shadowing a built-in vs added", () => {
+        mkdirSync(join(overlay, "workflows", "prompts"), { recursive: true });
+        mkdirSync(join(overlay, "skills", "building"), { recursive: true });
+        mkdirSync(join(overlay, "skills", "custom"), { recursive: true });
+        mkdirSync(join(overlay, "agent-context"), { recursive: true });
+        // Shadows the built-in build workflow.
+        writeFileSync(join(overlay, "workflows", "build.yaml"), "kind: build\nname: build\n");
+        // A brand-new workflow.
+        writeFileSync(join(overlay, "workflows", "ship.yaml"), "kind: build\nname: ship\n");
+        // Shadows a built-in cron.
+        writeFileSync(join(overlay, "workflows", "cron-health.yaml"), "kind: cron\nname: cron-health\nworkflow: repo-health\n");
+        // Prompt: one shadowing, none added.
+        writeFileSync(join(overlay, "workflows", "prompts", "architect.md"), "# overridden");
+        // Skills: building shadows, custom is added.
+        writeFileSync(join(overlay, "skills", "building", "SKILL.md"), "# overridden");
+        writeFileSync(join(overlay, "skills", "custom", "SKILL.md"), "# custom");
+        // Agent-context: soul shadows, extra is added.
+        writeFileSync(join(overlay, "agent-context", "soul.md"), "# overridden");
+        writeFileSync(join(overlay, "agent-context", "extra.md"), "# extra");
+        const assets = enumerateOverlayAssets({ coreRoot: core, overlayRoot: overlay });
+        const byKey = new Map(assets.map((a) => [`${a.type}:${a.name}`, a.shadowsDefault]));
+        expect(byKey.get("workflow:build")).toBe(true);
+        expect(byKey.get("workflow:ship")).toBe(false);
+        expect(byKey.get("cron:cron-health")).toBe(true);
+        expect(byKey.get("prompt:architect.md")).toBe(true);
+        expect(byKey.get("skill:building")).toBe(true);
+        expect(byKey.get("skill:custom")).toBe(false);
+        expect(byKey.get("agent-context:soul.md")).toBe(true);
+        expect(byKey.get("agent-context:extra.md")).toBe(false);
+    });
+    it("keys workflows by YAML name, not filename, and splits cron vs workflow", () => {
+        mkdirSync(join(overlay, "workflows"), { recursive: true });
+        // Filename differs from the logical name.
+        writeFileSync(join(overlay, "workflows", "my-build.yaml"), "kind: build\nname: build\n");
+        const assets = enumerateOverlayAssets({ coreRoot: core, overlayRoot: overlay });
+        expect(assets).toContainEqual({ type: "workflow", name: "build", shadowsDefault: true });
+    });
+    it("treats everything as 'added' when there are no built-ins to compare", () => {
+        mkdirSync(join(overlay, "skills", "custom"), { recursive: true });
+        writeFileSync(join(overlay, "skills", "custom", "SKILL.md"), "# custom");
+        const assets = enumerateOverlayAssets({ overlayRoot: overlay });
+        expect(assets).toEqual([{ type: "skill", name: "custom", shadowsDefault: false }]);
+    });
+});
+//# sourceMappingURL=overlay-assets.test.js.map

package/dist/overlay-assets.test.js.map

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

package/dist/sandbox/command-exec.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/command-exec.integration.test.js

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "child_process";
+import { mkdtempSync, mkdirSync, rmSync, readdirSync, existsSync } from "fs";
+import { join } from "path";
+import { runWorkflow } from "./../workflows/runner.js";
+/**
+ * Integration tests that ACTUALLY start a docker sandbox and execute
+ * deterministic `type: bash` / `type: script` phases end-to-end through the
+ * real workflow runner — no AI, no mocks. This is the one path the unit suite
+ * can't cover (it stubs `executeCommand`).
+ *
+ * Opt-in + self-gating: runs only when `RUN_SANDBOX_IT=1` AND the lean sandbox
+ * image is built, so the default `npx vitest run` (and CI without docker) skip
+ * it instantly. To run:
+ *
+ *   docker compose --profile build-only build sandbox   # if not already built
+ *   RUN_SANDBOX_IT=1 npx vitest run src/sandbox/command-exec.integration.test.ts
+ *
+ * Each command phase spins up + tears down its own container, so these are
+ * slow (tens of seconds) — hence the long per-test timeout.
+ */
+function sandboxImageBuilt() {
+    try {
+        const out = execFileSync("docker", ["images", "-q", "lastlight-sandbox:latest"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+const RUN = process.env.RUN_SANDBOX_IT === "1" && sandboxImageBuilt();
+const TIMEOUT = 180_000;
+let stateDir;
+const savedEnv = {};
+function setEnv(k, v) {
+    savedEnv[k] = process.env[k];
+    process.env[k] = v;
+}
+function baseCtx(taskId) {
+    return {
+        owner: "acme",
+        repo: "widget",
+        issueNumber: 1,
+        issueTitle: "integration",
+        issueBody: "",
+        issueLabels: [],
+        commentBody: "",
+        sender: "tester",
+        branch: "main",
+        taskId,
+        issueDir: ".lastlight/issue-1",
+        bootstrapLabel: "lastlight:bootstrap",
+    };
+}
+function dockerConfig() {
+    return {
+        sandbox: "docker",
+        stateDir,
+        sessionsDir: join(stateDir, "agent-sessions"),
+    };
+}
+describe.skipIf(!RUN)("sandbox command execution (integration)", () => {
+    beforeAll(() => {
+        // Base the workspace under the repo's gitignored `data/` dir (i.e. inside
+        // the project, under the user's home). Docker Desktop on macOS shares
+        // /Users by default but NOT /var/folders (os.tmpdir()) or /tmp — so the
+        // workspace bind mount is only visible to the daemon under a shared path.
+        // This mirrors scripts/dev-local.sh (STATE_DIR=$PROJECT_ROOT/data). On Linux
+        // any path works.
+        const base = join(process.cwd(), "data", "sandbox-it");
+        mkdirSync(base, { recursive: true });
+        stateDir = mkdtempSync(join(base, "run-"));
+        // Run on the default bridge (the compose sandbox-egress network + coredns
+        // sidecars don't exist outside docker-compose) and point DNS at a real
+        // resolver so the container has working name resolution + NAT.
+        setEnv("LASTLIGHT_SANDBOX_NETWORK", "default");
+        setEnv("LASTLIGHT_DNS_STRICT", "8.8.8.8");
+        setEnv("LASTLIGHT_DNS_OPEN", "8.8.8.8");
+        // Host-path data volume → bind-mount mode (mirrors scripts/dev-local.sh),
+        // so the harness and the daemon see the same workspace FS.
+        setEnv("SANDBOX_DATA_VOLUME", join(stateDir, "sandbox-data"));
+    });
+    afterAll(() => {
+        for (const [k, v] of Object.entries(savedEnv)) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+        if (stateDir)
+            rmSync(stateDir, { recursive: true, force: true });
+    });
+    it("runs a no-AI bash workflow and threads output to a downstream phase", async () => {
+        const wf = {
+            kind: "agent",
+            name: "it-bash",
+            phases: [
+                { name: "phase_0", type: "context" },
+                { name: "emit", type: "bash", command: "echo hello-from-sandbox", output_var: "greeting" },
+                // Consumes the upstream output two ways: template substitution + the
+                // forwarded LL_OUT_<PHASE> env var.
+                { name: "consume", type: "bash", command: "echo template={{phaseOutputs.emit}} env=$LL_OUT_EMIT" },
+            ],
+        };
+        const result = await runWorkflow(wf, baseCtx("it-bash-1"), dockerConfig(), {});
+        expect(result.success).toBe(true);
+        const emit = result.phases.find((p) => p.phase === "emit");
+        expect(emit?.success).toBe(true);
+        expect(emit?.output).toContain("hello-from-sandbox");
+        const consume = result.phases.find((p) => p.phase === "consume");
+        expect(consume?.success).toBe(true);
+        expect(consume?.output).toContain("template=hello-from-sandbox");
+        expect(consume?.output).toContain("env=hello-from-sandbox");
+        // The command run is mirrored to a session jsonl (visible in the dashboard
+        // + CLI), exactly like an agent turn.
+        const projects = join(stateDir, "agent-sessions", "projects");
+        expect(existsSync(projects)).toBe(true);
+        const jsonls = readdirSync(projects, { recursive: true }).filter((f) => String(f).endsWith(".jsonl"));
+        expect(jsonls.length).toBeGreaterThan(0);
+    }, TIMEOUT);
+    it("fails the workflow when a bash phase exits non-zero", async () => {
+        const wf = {
+            kind: "agent",
+            name: "it-bash-fail",
+            phases: [
+                { name: "phase_0", type: "context" },
+                { name: "boom", type: "bash", command: "echo nope >&2; exit 3" },
+            ],
+        };
+        const result = await runWorkflow(wf, baseCtx("it-bash-fail-1"), dockerConfig(), {});
+        expect(result.success).toBe(false);
+        const boom = result.phases.find((p) => p.phase === "boom");
+        expect(boom?.success).toBe(false);
+    }, TIMEOUT);
+    it("runs an inline JS script via node", async () => {
+        const wf = {
+            kind: "agent",
+            name: "it-js",
+            phases: [
+                { name: "phase_0", type: "context" },
+                {
+                    name: "calc",
+                    type: "script",
+                    runtime: "js",
+                    script: "console.log('js-answer:', 6 * 7);",
+                    output_var: "out",
+                },
+            ],
+        };
+        const result = await runWorkflow(wf, baseCtx("it-js-1"), dockerConfig(), {});
+        expect(result.success).toBe(true);
+        const calc = result.phases.find((p) => p.phase === "calc");
+        expect(calc?.success).toBe(true);
+        expect(calc?.output).toContain("js-answer: 42");
+    }, TIMEOUT);
+    it("runs an inline Python script via uv run (stdlib only, offline)", async () => {
+        const wf = {
+            kind: "agent",
+            name: "it-py",
+            phases: [
+                { name: "phase_0", type: "context" },
+                {
+                    name: "calc",
+                    type: "script",
+                    runtime: "python",
+                    timeout_seconds: 120,
+                    script: "import sys\nprint('py-answer:', 6 * 7)\nprint('py-version-ok:', sys.version_info[0] == 3)",
+                    output_var: "out",
+                },
+            ],
+        };
+        const result = await runWorkflow(wf, baseCtx("it-py-1"), dockerConfig(), {});
+        expect(result.success).toBe(true);
+        const calc = result.phases.find((p) => p.phase === "calc");
+        expect(calc?.success).toBe(true);
+        expect(calc?.output).toContain("py-answer: 42");
+        expect(calc?.output).toContain("py-version-ok: True");
+    }, TIMEOUT);
+});
+//# sourceMappingURL=command-exec.integration.test.js.map

package/dist/sandbox/command-exec.integration.test.js.map

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

package/dist/sandbox/docker.d.ts

@@ -139,6 +139,38 @@ export declare class DockerSandbox {
         /** Called for each newline-terminated stdout line as it arrives. */
         onLine?: (line: string) => void;
     }): Promise<void>;
+    /**
+     * Run a deterministic shell command inside an already-provisioned sandbox
+     * container and return its exit code + captured output. This is the
+     * non-agent sibling of {@link runAgent}: same `docker exec --user agent -w
+     * <workdir> … sh -c <cmd>` machinery, but it captures a bounded stdout tail
+     * (runAgent discards stdout) and RESOLVES with the exit code instead of
+     * rejecting on non-zero — the caller decides success/failure.
+     *
+     * Powers `type: bash` / `type: script` workflow phases (and the in-sandbox
+     * `generic_loop.until_bash` check). `command` is passed as a single argv slot
+     * to `sh -c`, so it is NOT re-parsed by the host shell — it is the script we
+     * intend to run. Env is forwarded via `docker exec -e KEY=VALUE` (argv, not
+     * shell-interpolated); keys are charset-asserted defensively.
+     */
+    runCommand(taskId: string, command: string, opts?: {
+        /**
+         * Working directory inside the container. Defaults to WORKSPACE_DIR.
+         * Asserted against the workspace-root allowlist (same guard as runAgent).
+         */
+        cwd?: string;
+        /** Env forwarded into the command via `docker exec -e`. */
+        sandboxEnv?: Record<string, string>;
+        /** Per-command timeout in seconds (default: the sandbox config timeout). */
+        timeoutSeconds?: number;
+        /** Called for each newline-terminated stdout line as it arrives. */
+        onLine?: (line: string) => void;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        timedOut: boolean;
+    }>;
     /**
      * Remove a sandbox container.
      */

package/dist/sandbox/docker.js

@@ -67,10 +67,16 @@ export class DockerSandbox {
         dockerArgs.push("-v", `${pkgCacheVolume}:${PKG_CACHE_DIR}`);
         // Point each package manager at its shared subdir. npm reads npm_config_cache;
         // pnpm reads npm-style env config (npm_config_store_dir → store-dir); yarn
-        // (classic + berry) reads YARN_CACHE_FOLDER. The agent already picks the PM
-        // from the repo's lockfile (see skills/pr-review/SKILL.md), so all three are
-        // wired regardless of which one a given repo uses.
-        dockerArgs.push("-e", `npm_config_cache=${PKG_CACHE_DIR}/npm`, "-e", `npm_config_store_dir=${PKG_CACHE_DIR}/pnpm`, "-e", `YARN_CACHE_FOLDER=${PKG_CACHE_DIR}/yarn`);
+        // (classic + berry) reads YARN_CACHE_FOLDER; uv (python `type: script`
+        // phases) reads UV_CACHE_DIR. The agent already picks the PM from the repo's
+        // lockfile (see skills/pr-review/SKILL.md), so all are wired regardless of
+        // which one a given repo uses.
+        dockerArgs.push("-e", `npm_config_cache=${PKG_CACHE_DIR}/npm`, "-e", `npm_config_store_dir=${PKG_CACHE_DIR}/pnpm`, "-e", `YARN_CACHE_FOLDER=${PKG_CACHE_DIR}/yarn`, "-e", `UV_CACHE_DIR=${PKG_CACHE_DIR}/uv`, 
+        // uv resolves PEP 723 deps from PyPI (pypi.org / pythonhosted.org are in
+        // the strict egress allowlist). Pin it to the baked-in system python3 so
+        // it never tries to fetch a managed interpreter from astral.sh / GitHub
+        // (not guaranteed reachable under strict egress).
+        "-e", "UV_PYTHON_DOWNLOADS=never");
         // Resolve git mounts for worktrees (if .git is a file pointing elsewhere).
         // In volume-subpath mode these are still emitted as bind mounts; the
         // gitMounts path is only hit for git worktrees that live alongside the
@@ -322,6 +328,105 @@ export class DockerSandbox {
             });
         });
     }
+    /**
+     * Run a deterministic shell command inside an already-provisioned sandbox
+     * container and return its exit code + captured output. This is the
+     * non-agent sibling of {@link runAgent}: same `docker exec --user agent -w
+     * <workdir> … sh -c <cmd>` machinery, but it captures a bounded stdout tail
+     * (runAgent discards stdout) and RESOLVES with the exit code instead of
+     * rejecting on non-zero — the caller decides success/failure.
+     *
+     * Powers `type: bash` / `type: script` workflow phases (and the in-sandbox
+     * `generic_loop.until_bash` check). `command` is passed as a single argv slot
+     * to `sh -c`, so it is NOT re-parsed by the host shell — it is the script we
+     * intend to run. Env is forwarded via `docker exec -e KEY=VALUE` (argv, not
+     * shell-interpolated); keys are charset-asserted defensively.
+     */
+    async runCommand(taskId, command, opts) {
+        const info = this.activeContainers.get(taskId);
+        if (!info)
+            throw new Error(`No sandbox for task ${taskId}`);
+        const timeout = opts?.timeoutSeconds || this.config.timeoutSeconds || 1800;
+        const workdir = opts?.cwd ?? WORKSPACE_DIR;
+        if (!workdir.startsWith(WORKSPACE_DIR) || !/^[A-Za-z0-9/_.-]+$/.test(workdir)) {
+            throw new Error(`Refusing to run command in cwd "${workdir}" — must live under ${WORKSPACE_DIR}`);
+        }
+        const envFlags = [];
+        for (const [k, v] of Object.entries(opts?.sandboxEnv ?? {})) {
+            if (!/^[A-Z_][A-Z0-9_]*$/.test(k)) {
+                throw new Error(`Refusing sandbox-env key "${k}" — must be UPPER_SNAKE`);
+            }
+            // Values travel as argv (no shell re-parse), so any value is safe — but a
+            // newline would let a value smuggle a second `-e` token in some shells;
+            // reject defensively to match runAgent's posture.
+            if (/[\n\r]/.test(v)) {
+                throw new Error(`Refusing sandbox-env value for "${k}" — contains newline`);
+            }
+            envFlags.push("-e", `${k}=${v}`);
+        }
+        const args = ["exec", "--user", "agent", "-w", workdir, ...envFlags, info.containerName, "sh", "-c", command];
+        // Bounded tails so a runaway command (e.g. a build dumping MB of logs)
+        // can't OOM the harness — keep enough stdout for the downstream
+        // `{{phaseOutputs.*}}` reference to be useful.
+        const STDOUT_TAIL_BYTES = 256 * 1024;
+        const STDERR_TAIL_BYTES = 32 * 1024;
+        return await new Promise((resolvePromise, reject) => {
+            const child = spawn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+            let stdoutTail = "";
+            let stderrTail = "";
+            let buf = "";
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, timeout * 1000);
+            child.stdout.setEncoding("utf-8");
+            child.stdout.on("data", (chunk) => {
+                stdoutTail += chunk;
+                if (stdoutTail.length > STDOUT_TAIL_BYTES)
+                    stdoutTail = stdoutTail.slice(-STDOUT_TAIL_BYTES);
+                if (!opts?.onLine)
+                    return;
+                buf += chunk;
+                let nl;
+                while ((nl = buf.indexOf("\n")) >= 0) {
+                    const line = buf.slice(0, nl);
+                    buf = buf.slice(nl + 1);
+                    if (line.length > 0) {
+                        try {
+                            opts.onLine(line);
+                        }
+                        catch { /* swallow listener errors */ }
+                    }
+                }
+            });
+            child.stderr.setEncoding("utf-8");
+            child.stderr.on("data", (chunk) => {
+                stderrTail += chunk;
+                if (stderrTail.length > STDERR_TAIL_BYTES)
+                    stderrTail = stderrTail.slice(-STDERR_TAIL_BYTES);
+            });
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                reject(new Error(`Sandbox command spawn failed: ${err.message}`));
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (buf.length > 0 && opts?.onLine) {
+                    try {
+                        opts.onLine(buf);
+                    }
+                    catch { /* ignore */ }
+                }
+                resolvePromise({
+                    exitCode: timedOut ? 124 : (code ?? 1),
+                    stdout: stdoutTail,
+                    stderr: stderrTail,
+                    timedOut,
+                });
+            });
+        });
+    }
     /**
      * Remove a sandbox container.
      */