@sagentlab/navarch-runtime 0.1.0

package/dist/config.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRuntimeConfig = loadRuntimeConfig;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+function envInt(env, name, fallback) {
+    const raw = env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function envList(env, name, fallback) {
+    const raw = env[name];
+    if (!raw)
+        return fallback;
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Loads runtime config from FLOTILLA_* env vars, with sane defaults for a
+ * fresh machine. Accepts an explicit env map (defaulting to process.env) so
+ * it is trivially unit-testable without mutating global state.
+ */
+function loadRuntimeConfig(env = process.env) {
+    const configDir = env.FLOTILLA_CONFIG_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".flotilla");
+    const leaseHeartbeatIntervalMs = envInt(env, "FLOTILLA_LEASE_HEARTBEAT_INTERVAL_MS", 5 * 60 * 1000);
+    return {
+        apiBase: env.FLOTILLA_API_BASE ?? "http://localhost:3000",
+        workspaceRoot: env.FLOTILLA_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
+        configDir,
+        maxSessions: envInt(env, "FLOTILLA_MAX_SESSIONS", 3),
+        capabilities: envList(env, "FLOTILLA_CAPABILITIES", ["docker-sandbox", "shell"]),
+        ownerZone: env.FLOTILLA_OWNER_ZONE ?? "sagentlab",
+        pollIntervalMs: envInt(env, "FLOTILLA_POLL_INTERVAL_MS", 5000),
+        machineHeartbeatIntervalMs: envInt(env, "FLOTILLA_HEARTBEAT_INTERVAL_MS", 60_000),
+        // leases.expires_at = claimed_at + 15 min (schema-design.md §4) — default renewal
+        // interval must stay comfortably under that TTL.
+        leaseHeartbeatIntervalMs,
+        sessionTimeoutMs: envInt(env, "FLOTILLA_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
+        agentType: env.FLOTILLA_AGENT === "codex" ? "codex" : "claude-code",
+        claudeBin: env.FLOTILLA_CLAUDE_BIN ?? "claude",
+        claudeExtraArgs: envList(env, "FLOTILLA_CLAUDE_EXTRA_ARGS", []),
+        codexBin: env.FLOTILLA_CODEX_BIN ?? "codex",
+        codexExtraArgs: envList(env, "FLOTILLA_CODEX_EXTRA_ARGS", []),
+        mcpConfigPath: env.FLOTILLA_MCP_CONFIG_PATH ?? null,
+        sandboxMode: env.FLOTILLA_SANDBOX_MODE === "host" ? "host" : "docker",
+        dockerImage: env.FLOTILLA_DOCKER_IMAGE ?? "node:20-slim",
+    };
+}

package/dist/exit-conditions.cjs

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPrUrl = extractPrUrl;
+exports.parseClaudeJsonResult = parseClaudeJsonResult;
+exports.extractUsageFromClaudeJson = extractUsageFromClaudeJson;
+exports.parseCodexJsonEvents = parseCodexJsonEvents;
+exports.extractUsageFromCodexEvents = extractUsageFromCodexEvents;
+exports.extractFinalMessageFromCodexEvents = extractFinalMessageFromCodexEvents;
+exports.mapExitCondition = mapExitCondition;
+const PR_URL_PATTERN = /https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/;
+function extractPrUrl(text) {
+    const match = text.match(PR_URL_PATTERN);
+    return match ? match[0] : null;
+}
+/**
+ * Best-effort parse of `claude -p --output-format json` stdout into the
+ * assumed result shape above. Tries the whole trimmed stdout first (the
+ * expected case); if that fails, tries each non-empty line that looks like a
+ * JSON object, in case a warning/log line preceded the result (last such
+ * line wins, since the final result is expected last). Returns null rather
+ * than throwing when nothing parses as an object carrying at least one of
+ * the fields this module actually reads.
+ */
+function parseClaudeJsonResult(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    const isUsableResult = (value) => typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        ("result" in value || "usage" in value || "cost_usd" in value || "total_cost_usd" in value);
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isUsableResult(parsed))
+            return parsed;
+    }
+    catch {
+        // fall through to line-by-line best effort below
+    }
+    const lines = trimmed.split("\n").filter((line) => line.trim().startsWith("{"));
+    for (const line of lines.reverse()) {
+        try {
+            const parsed = JSON.parse(line);
+            if (isUsableResult(parsed))
+                return parsed;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Extracts token/cost usage from a parsed `claude -p --output-format json`
+ * result. Input tokens are the sum of `input_tokens` plus both cache
+ * variants (schema-design.md §4 `sessions.tokens_in` is a single bigint with
+ * no cache breakdown, so the components are folded together here rather
+ * than dropped). Cost prefers `total_cost_usd` (the field name used in
+ * multi-turn/agentic CLI output) and falls back to `cost_usd`.
+ */
+function extractUsageFromClaudeJson(parsed) {
+    const usage = parsed.usage ?? {};
+    const tokensIn = (usage.input_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0);
+    const tokensOut = usage.output_tokens ?? 0;
+    const costUsd = parsed.total_cost_usd ?? parsed.cost_usd ?? 0;
+    return { tokensIn, tokensOut, costUsd };
+}
+/**
+ * Best-effort line-by-line parse of `codex exec --json` stdout into the
+ * assumed JSONL event shape above. Silently skips any line that isn't a JSON
+ * object carrying a `msg` field (blank lines, stray log lines, a shape that
+ * doesn't match the guess) rather than throwing; returns an empty array (not
+ * null) when nothing parses, since a run can legitimately emit zero events.
+ */
+function parseCodexJsonEvents(stdout) {
+    const events = [];
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("{"));
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && "msg" in parsed) {
+                events.push(parsed);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return events;
+}
+/**
+ * Extracts token/cost usage from parsed `codex exec --json` events. Assumes
+ * each `token_count` event reports the run's cumulative totals so far (like
+ * Claude Code's running usage updates), so the *last* such event wins rather
+ * than summing across events; if that assumption is wrong (incremental
+ * per-turn deltas instead), this under- or over-counts until reconciled here.
+ */
+function extractUsageFromCodexEvents(events) {
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let costUsd = 0;
+    for (const event of events) {
+        if (event.msg?.type === "token_count") {
+            tokensIn = (event.msg.input_tokens ?? 0) + (event.msg.cached_input_tokens ?? 0);
+            tokensOut = event.msg.output_tokens ?? 0;
+        }
+        if (typeof event.msg?.total_cost_usd === "number") {
+            costUsd = event.msg.total_cost_usd;
+        }
+    }
+    return { tokensIn, tokensOut, costUsd };
+}
+/** The last `agent_message` event's text — assumed to be the run's final agent-visible output, mirroring Claude JSON result's `result` field. Returns null when no such event parsed (see parseCodexJsonEvents doc comment). */
+function extractFinalMessageFromCodexEvents(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const msg = events[i]?.msg;
+        if (msg?.type === "agent_message" && typeof msg.message === "string")
+            return msg.message;
+    }
+    return null;
+}
+function summarize(text, maxLen = 500) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return "";
+    const collapsed = trimmed.replace(/\s+/g, " ");
+    return collapsed.length > maxLen ? `${collapsed.slice(0, maxLen - 1)}…` : collapsed;
+}
+/**
+ * Maps a finished (or forcibly ended) Claude Code adapter run onto the
+ * dispatcher's complete() contract (implementation-plan.md WP-07: "collect
+ * final report + PR URL; map exit conditions to complete/fail"). Priority
+ * order, highest first: lease loss > timeout > process crash > non-zero
+ * exit > clean exit.
+ */
+function mapExitCondition(result) {
+    const prUrl = extractPrUrl(result.stdout) ?? extractPrUrl(result.stderr);
+    const evidenceUrls = prUrl ? [prUrl] : [];
+    if (result.killedByLeaseLoss) {
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "killed",
+            reportSummary: "Session killed: lease was lost or expired mid-run (heartbeat renewal failed).",
+            evidenceUrls,
+        };
+    }
+    if (result.timedOut) {
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "killed",
+            reportSummary: "Session killed: exceeded the configured max session duration.",
+            evidenceUrls,
+        };
+    }
+    if (result.exitCode === null) {
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "crashed",
+            reportSummary: summarize(result.stderr) || "Adapter process crashed before exiting.",
+            evidenceUrls,
+        };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "failed",
+            reportSummary: summarize(result.stderr || result.stdout) || `Adapter exited with code ${result.exitCode}.`,
+            evidenceUrls,
+        };
+    }
+    // Prefer an adapter-supplied reportText (e.g. codex.cts's extracted final
+    // `agent_message`) over parsing stdout ourselves; otherwise prefer the
+    // parsed `result` text (readable prose) over the raw `--output-format
+    // json` blob so report_summary doesn't end up being a dumped JSON object;
+    // falls back to raw stdout when neither is available (see
+    // parseClaudeJsonResult's doc comment).
+    const parsedJson = parseClaudeJsonResult(result.stdout);
+    const reportText = result.reportText ?? parsedJson?.result ?? result.stdout;
+    const reportSummary = summarize(reportText) || "Adapter completed with no report text.";
+    return {
+        leaseOutcome: "completed",
+        exitStatus: "completed",
+        reportSummary,
+        evidenceUrls,
+    };
+}

package/dist/heartbeat-loop.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineHeartbeatLoop = void 0;
+const logger_cjs_1 = require("./logger.cjs");
+const log = (0, logger_cjs_1.createLogger)("heartbeat");
+/**
+ * Machine-level heartbeat loop (implementation-plan.md WP-07), separate from
+ * the per-lease heartbeat in session.cts: reports this machine's online
+ * status, capabilities, and current available capacity regardless of whether
+ * any task is claimed right now.
+ */
+class MachineHeartbeatLoop {
+    api;
+    machineId;
+    config;
+    capacity;
+    timer = null;
+    constructor(api, machineId, config, capacity) {
+        this.api = api;
+        this.machineId = machineId;
+        this.config = config;
+        this.capacity = capacity;
+    }
+    start() {
+        if (this.timer)
+            return;
+        void this.tick();
+        this.timer = setInterval(() => void this.tick(), this.config.machineHeartbeatIntervalMs);
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    async tick() {
+        try {
+            await this.api.machineHeartbeat(this.machineId, {
+                available_capacity: this.capacity.available(),
+                capabilities: this.config.capabilities,
+            });
+        }
+        catch (err) {
+            log.warn(`machine heartbeat failed: ${String(err)}`);
+        }
+    }
+}
+exports.MachineHeartbeatLoop = MachineHeartbeatLoop;

package/dist/logger.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+/** Minimal structured console logger; swap for something richer without touching call sites. */
+function createLogger(scope) {
+    const emit = (level, msg) => {
+        const line = `[${new Date().toISOString()}] [${level.toUpperCase()}] [${scope}] ${msg}`;
+        if (level === "error")
+            console.error(line);
+        else if (level === "warn")
+            console.warn(line);
+        else
+            console.log(line);
+    };
+    return {
+        info: (msg) => emit("info", msg),
+        warn: (msg) => emit("warn", msg),
+        error: (msg) => emit("error", msg),
+    };
+}

package/dist/machine-store.cjs

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveMachineIdentity = saveMachineIdentity;
+exports.loadMachineIdentity = loadMachineIdentity;
+exports.resolveMachineIdentity = resolveMachineIdentity;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+function storePath(configDir) {
+    return node_path_1.default.join(configDir, "machine.json");
+}
+/** Persists the machine's long-lived auth token to `<configDir>/machine.json`, mode 0600. */
+async function saveMachineIdentity(configDir, identity) {
+    await node_fs_1.promises.mkdir(configDir, { recursive: true, mode: 0o700 });
+    const file = storePath(configDir);
+    await node_fs_1.promises.writeFile(file, `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+    await node_fs_1.promises.chmod(file, 0o600);
+}
+async function loadMachineIdentity(configDir) {
+    try {
+        const raw = await node_fs_1.promises.readFile(storePath(configDir), "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Resolves machine identity for the running daemon: env vars win (twelve-factor
+ * deployments — systemd EnvironmentFile, container secrets), falling back to
+ * the on-disk file written by `navarch-runtime register`.
+ *
+ * Note: this is the *machine's own* long-lived credential (analogous to an SSH
+ * host key), not a task secret from the broker — the "never write secrets to
+ * disk outside the sandbox" rule (implementation-plan.md WP-07) is scoped to
+ * per-task broker-issued secrets, handled entirely in session.cts/sandbox.cts.
+ */
+async function resolveMachineIdentity(configDir, apiBaseFallback) {
+    const envToken = process.env.FLOTILLA_MACHINE_TOKEN;
+    const envId = process.env.FLOTILLA_MACHINE_ID;
+    if (envToken && envId) {
+        return {
+            machine_id: envId,
+            token: envToken,
+            name: process.env.FLOTILLA_MACHINE_NAME ?? envId,
+            api_base: process.env.FLOTILLA_API_BASE ?? apiBaseFallback,
+        };
+    }
+    const stored = await loadMachineIdentity(configDir);
+    if (stored)
+        return stored;
+    throw new Error("No machine identity found. Run `navarch-runtime register` first, or set " +
+        "FLOTILLA_MACHINE_TOKEN + FLOTILLA_MACHINE_ID for a twelve-factor deployment.");
+}

package/dist/mcp-config.cjs

@@ -0,0 +1,41 @@
+"use strict";
+// Builds the per-session `--mcp-config` JSON pointed at the platform MCP
+// server (app/api/mcp/route.ts), per implementation-plan.md WP-07: "Claude
+// Code adapter: headless `claude -p` ... with `--mcp-config` pointing at the
+// platform MCP server".
+//
+// Previously `mcpConfigPath` was just a static, operator-supplied path
+// (config.cts's `FLOTILLA_MCP_CONFIG_PATH`) with nothing that ever wrote a
+// real config file -- there was no way for a session to actually reach the
+// platform MCP server with the auth it needs. This module is the fix: one
+// config, generated fresh per session, carrying the machine's bearer token
+// and this session's lease id (the same two-layer auth app/api/mcp/route.ts
+// requires -- see lib/flotilla/mcp/context.ts).
+//
+// Pure and side-effect free (no filesystem access) so it's trivially unit
+// testable; session.cts is the only caller that writes the result to disk.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOTILLA_LEASE_HEADER = void 0;
+exports.buildNavarchMcpConfig = buildNavarchMcpConfig;
+/** The header app/api/mcp/route.ts's lib/flotilla/mcp/context.ts reads to identify which lease is calling. */
+exports.FLOTILLA_LEASE_HEADER = "X-Navarch-Lease-Id";
+/**
+ * Builds the `.mcp.json`-shaped config object Claude Code's `--mcp-config`
+ * flag expects: a remote "http" (streamable HTTP) server entry with the
+ * bearer token and lease id as request headers.
+ */
+function buildNavarchMcpConfig(opts) {
+    const serverName = opts.serverName ?? "flotilla";
+    return {
+        mcpServers: {
+            [serverName]: {
+                type: "http",
+                url: `${opts.apiBase.replace(/\/+$/, "")}/api/mcp`,
+                headers: {
+                    Authorization: `Bearer ${opts.machineToken}`,
+                    [exports.FLOTILLA_LEASE_HEADER]: opts.leaseId,
+                },
+            },
+        },
+    };
+}

package/dist/prompt.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPrompt = renderPrompt;
+/**
+ * Renders the four-layer context bundle (project-plan.md §3.8: steering docs,
+ * task itself, task-type playbook, depends_on reports) into the single prompt
+ * string handed to `claude -p`. Also written verbatim to prompt.md in the
+ * session workspace (session.cts) for audit/debugging, per implementation-plan.md
+ * WP-07 "write prompt file".
+ */
+function renderPrompt(task, bundle) {
+    const sections = [];
+    sections.push(`# Task: ${task.summary}`);
+    sections.push(`Type: ${task.task_type} | Repo: ${task.repo} | Environment: ${task.environment_scope}`);
+    if (task.github_issue_url) {
+        sections.push(`GitHub issue: ${task.github_issue_url}`);
+    }
+    if (bundle.steering_docs.length > 0) {
+        sections.push("## Steering documents");
+        for (const doc of bundle.steering_docs) {
+            sections.push(`### ${doc.path}\n\n${doc.content}`);
+        }
+    }
+    if (bundle.depends_on_reports.length > 0) {
+        sections.push("## Prior task reports (depends_on)");
+        for (const report of bundle.depends_on_reports) {
+            sections.push(`- ${report.task_id}: ${report.report_summary ?? report.summary}`);
+        }
+    }
+    sections.push("## Playbook");
+    sections.push(bundle.playbook);
+    return sections.join("\n\n");
+}

package/dist/redact.cjs

@@ -0,0 +1,61 @@
+"use strict";
+// Log/transcript redaction (project-plan.md §3.7: "session logs are
+// redaction-filtered against known secret values before storage"; §3.9 exit
+// step 5; implementation-plan.md WP-04 "registry of issued values per
+// session; scrub from report_summary, transcripts, and event payloads before
+// persistence" — WP-07 owns the runtime-side half of that contract).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretRegistry = void 0;
+exports.redactText = redactText;
+const SECRET_PATTERNS = [
+    /gh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub PAT / OAuth / user-to-server / refresh tokens
+    /github_pat_[A-Za-z0-9_]{20,}/g, // GitHub fine-grained PAT
+    /sk-[A-Za-z0-9-]{20,}/g, // generic vendor secret-key style token
+    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+];
+const REDACTED = "[REDACTED]";
+/**
+ * Registry of secret values actually issued to a session, populated as soon
+ * as the broker returns them. Kept separate from redactText() so callers can
+ * accumulate values from multiple broker calls before a single redaction
+ * pass over the transcript.
+ */
+class SecretRegistry {
+    values = new Set();
+    register(value) {
+        if (value && value.length >= 4)
+            this.values.add(value);
+    }
+    registerAll(values) {
+        const list = Array.isArray(values) ? values : Object.values(values);
+        for (const v of list)
+            this.register(v);
+    }
+    list() {
+        return [...this.values];
+    }
+}
+exports.SecretRegistry = SecretRegistry;
+/**
+ * Scrubs known-issued secret values (exact match) and common secret-shaped
+ * patterns (defense in depth for values the registry didn't see, e.g. one an
+ * agent typed into a comment) from text before it is persisted anywhere:
+ * report_summary, transcripts, event payloads.
+ */
+function redactText(text, knownSecrets = []) {
+    let result = text;
+    for (const value of knownSecrets) {
+        if (!value)
+            continue;
+        result = splitJoin(result, value, REDACTED);
+    }
+    for (const pattern of SECRET_PATTERNS) {
+        result = result.replace(pattern, REDACTED);
+    }
+    return result;
+}
+function splitJoin(haystack, needle, replacement) {
+    if (!needle)
+        return haystack;
+    return haystack.split(needle).join(replacement);
+}

package/dist/sandbox.cjs

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerSandbox = exports.nodeCommandRunner = exports.SandboxUnavailableError = void 0;
+exports.isDockerAvailable = isDockerAvailable;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+class SandboxUnavailableError extends Error {
+}
+exports.SandboxUnavailableError = SandboxUnavailableError;
+/** Real process-spawning CommandRunner. Tests inject a fake one instead — see sandbox.test.cts. */
+exports.nodeCommandRunner = {
+    run(cmd, args, opts = {}) {
+        return new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(cmd, args, { cwd: opts.cwd });
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            const timer = opts.timeoutMs
+                ? setTimeout(() => {
+                    child.kill("SIGKILL");
+                }, opts.timeoutMs)
+                : null;
+            child.stdout?.on("data", (d) => {
+                stdout += d.toString();
+            });
+            child.stderr?.on("data", (d) => {
+                stderr += d.toString();
+            });
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                reject(err);
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                resolve({ code: code ?? -1, stdout, stderr });
+            });
+            if (opts.input !== undefined) {
+                child.stdin?.write(opts.input);
+            }
+            child.stdin?.end();
+        });
+    },
+};
+/**
+ * Whether Docker is usable on this machine. Degrades gracefully — callers use
+ * this to fall back to a clear "sandbox unavailable" failure instead of
+ * crashing when Docker isn't installed (needs-live-verification path per
+ * implementation-plan.md WP-07 test requirements).
+ */
+async function isDockerAvailable(runner = exports.nodeCommandRunner) {
+    try {
+        const result = await runner.run("docker", ["info"], { timeoutMs: 10_000 });
+        return result.code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function containerName(sessionId) {
+    return `flotilla-${sessionId}`;
+}
+/**
+ * One Docker container per session (implementation-plan.md WP-07 "Sandbox:
+ * Docker container per session (rootless; repo clone + env vars; wiped on
+ * exit)"): rootless-leaning flags (--cap-drop=ALL, --security-opt=no-new-
+ * privileges) and tmpfs /tmp + /run so injected secrets never touch a
+ * persistent disk, mirroring scripts/dcc-agent.mjs's sandbox.create pattern.
+ *
+ * Secret hygiene: injectEnv() writes KEY=value lines to a tmpfs-backed file
+ * *inside* the container over stdin (never a `docker run -e` flag, which
+ * would be visible via `docker inspect`, and never a host-side file).
+ * cloneRepo() then references the env var by name in a git credential
+ * helper, so the literal secret value never appears in any argv the host's
+ * `ps` can see and is never written to the container's persistent layer
+ * (tmpfs only) — it disappears with the container on wipe().
+ */
+class DockerSandbox {
+    name;
+    runner;
+    workDir;
+    image;
+    constructor(opts) {
+        this.name = containerName(opts.sessionId);
+        this.runner = opts.runner ?? exports.nodeCommandRunner;
+        this.workDir = node_path_1.default.join(opts.workspaceRoot, opts.sessionId);
+        this.image = opts.image;
+    }
+    async create() {
+        await node_fs_1.promises.mkdir(this.workDir, { recursive: true });
+        const result = await this.runner.run("docker", [
+            "run",
+            "-d",
+            "--name",
+            this.name,
+            "--cap-drop=ALL",
+            "--security-opt=no-new-privileges",
+            "--tmpfs",
+            "/tmp",
+            "--tmpfs",
+            "/run",
+            "-v",
+            `${this.workDir}:/workspace`,
+            "-w",
+            "/workspace",
+            this.image,
+            "tail",
+            "-f",
+            "/dev/null",
+        ]);
+        if (result.code !== 0) {
+            throw new SandboxUnavailableError(`docker run failed: ${result.stderr || result.stdout}`);
+        }
+    }
+    /**
+     * Writes KEY=value env lines into a tmpfs-backed file inside the container
+     * via stdin. Callers source it (`exec()` does this automatically) before
+     * running anything that needs the values.
+     */
+    async injectEnv(env) {
+        const lines = Object.entries(env)
+            .map(([k, v]) => `export ${k}=${shellQuote(v)}`)
+            .join("\n");
+        const result = await this.runner.run("docker", ["exec", "-i", this.name, "sh", "-c", "cat > /tmp/session.env"], { input: lines });
+        if (result.code !== 0) {
+            throw new SandboxUnavailableError(`failed to inject env: ${result.stderr || result.stdout}`);
+        }
+    }
+    /** Runs a shell command inside the container, sourcing any injected env first. */
+    async exec(command, opts = {}) {
+        return this.runner.run("docker", ["exec", this.name, "sh", "-c", `[ -f /tmp/session.env ] && . /tmp/session.env; ${command}`], { timeoutMs: opts.timeoutMs });
+    }
+    /**
+     * Clones `owner/repo` into /workspace/repo. When `hasCredential` is true,
+     * assumes GITHUB_TOKEN was already injected via injectEnv() and wires a
+     * git credential helper that references `$GITHUB_TOKEN` — the literal
+     * token value is never part of the argv string itself.
+     */
+    async cloneRepo(repo, hasCredential) {
+        const url = `https://github.com/${repo}.git`;
+        const command = hasCredential
+            ? `git -c credential.helper='!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f' clone --depth 1 ${shellQuote(url)} repo`
+            : `git clone --depth 1 ${shellQuote(url)} repo`;
+        return this.exec(command);
+    }
+    /** Force-removes the container and the host-side workspace mount. Best-effort: never throws. */
+    async wipe() {
+        await this.runner.run("docker", ["rm", "-f", this.name]).catch(() => undefined);
+        await node_fs_1.promises.rm(this.workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+exports.DockerSandbox = DockerSandbox;
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}