@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/runtime/containerEngineDetector.js

@@ -0,0 +1,222 @@
+// Issue #1388 (Epic #1491, ADR-0070, D1) — opt-in ACTIVE container engine probe. Distinct from the
+// #1385 metadata-only detector (capabilityDetector.ts), which stays passive on the hot path; this
+// module is invoked ONLY on explicit request (GET /api/containers/capability) and actively runs
+// `docker version` / `docker info` (and the podman equivalents) THROUGH the single governed
+// runCommand spawn boundary (deny-by-default CONTAINER_TASK_RULES, no shell, name-allowlisted env +
+// ephemeral HOME, byte-capped + redacted output, timeout SIGTERM→SIGKILL). The host CLI process uses
+// network:"inherit" because it must reach the local daemon socket.
+//
+// NEVER THROWS: every outcome — including a probe timeout (probe-timed-out) or an unparseable
+// response (probe-failed) — is a structured ContainerEngineStatus. The KEIKO_CONTAINERS_DISABLED
+// kill-switch short-circuits every engine to policy-blocked WITHOUT spawning.
+import { CommandDeniedError, CommandTimeoutError, DEFAULT_SANDBOX_POLICY, runCommand, } from "@oscharko-dev/keiko-tools";
+import { nodeSpawnFn } from "@oscharko-dev/keiko-tools/internal/exec";
+import { CONTAINER_ENGINE_IDS, CONTAINER_RUNTIME_SCHEMA_VERSION, CONTAINER_TASK_RULES, } from "@oscharko-dev/keiko-contracts";
+export const DEFAULT_CONTAINER_PROBE_DEADLINE_MS = 4_000; // generous: real daemon round-trip
+export const SUPPORTED_DOCKER_MAJOR = 20; // engine-version floor; below → "unsupported"
+const PER_CALL_TIMEOUT_MS = 2_000; // per `version`/`info` call; the overall deadline bounds both
+export const KEIKO_CONTAINERS_DISABLED_ENV = "KEIKO_CONTAINERS_DISABLED";
+// runCommand needs a workspace for cwd containment; the probe never mounts anything, so a minimal
+// host-level descriptor is sufficient. The container surface is host-level (capability is not
+// project-scoped), so the detector accepts an optional workspace and synthesizes a stub otherwise.
+function hostWorkspace(workspace) {
+    if (workspace !== undefined) {
+        return workspace;
+    }
+    return {
+        root: process.cwd(),
+        name: undefined,
+        version: undefined,
+        testFramework: "unknown",
+        sourceDirs: [],
+        testDirs: [],
+        languages: [],
+        ignoreLines: [],
+    };
+}
+// Static remediation catalog (D1): a fixed string per state, NEVER raw engine/OS error text.
+const REMEDIATION_HINTS = {
+    available: undefined,
+    missing: "Install the container engine or make it available on PATH.",
+    "not-running": "Start Docker Desktop or the container daemon.",
+    "permission-denied": "Grant your user access to the container socket (e.g. the docker group).",
+    unsupported: "Upgrade the container engine to a supported version.",
+    "policy-blocked": "Container execution is disabled by policy on this host.",
+};
+function disabledByKillSwitch(processEnv) {
+    const raw = processEnv[KEIKO_CONTAINERS_DISABLED_ENV];
+    return typeof raw === "string" && raw.length > 0;
+}
+// Parses the leading integer of a `version --format {{.Server.Version}}` line. A value like
+// "24.0.7" → 24. Returns undefined when no leading integer is present (unparseable → probe-failed).
+function parseMajorVersion(raw) {
+    const match = /^\s*v?(\d+)\b/.exec(raw);
+    if (match === null) {
+        return undefined;
+    }
+    const major = Number.parseInt(match[1] ?? "", 10);
+    return Number.isInteger(major) ? major : undefined;
+}
+function isNotFoundDenial(error) {
+    // runCommand throws CommandDeniedError with "not found on PATH" for a missing binary; any other
+    // denial is a policy decision (allowlist/cwd), surfaced as policy-blocked.
+    return error.message.includes("not found on PATH");
+}
+const DAEMON_DOWN_SIGNATURES = [
+    "cannot connect to the docker daemon",
+    "is the docker daemon running",
+    "connect: connection refused",
+    "error during connect",
+    "cannot connect to podman",
+    "no such file or directory", // socket path absent
+];
+const PERMISSION_SIGNATURES = ["permission denied", "eacces", "got permission denied"];
+function matchesSignature(haystack, signatures) {
+    const lower = haystack.toLowerCase();
+    return signatures.some((needle) => lower.includes(needle));
+}
+// Maps a settled (resolved) `version` CommandResult to an engine resolution. exitCode 0 with a
+// parseable in-range version continues to the daemon-liveness `info` step; everything else is a
+// structured unavailable state per the D1 table.
+function resolveFromVersionResult(result) {
+    const combined = `${result.stdout}\n${result.stderr}`;
+    if (result.exitCode !== 0) {
+        if (matchesSignature(combined, PERMISSION_SIGNATURES)) {
+            return { state: "permission-denied", unavailableReason: "executable-not-runnable" };
+        }
+        return { state: "not-running", unavailableReason: "daemon-not-running" };
+    }
+    const major = parseMajorVersion(result.stdout);
+    if (major === undefined) {
+        return { state: "unsupported", unavailableReason: "probe-failed" };
+    }
+    if (major < SUPPORTED_DOCKER_MAJOR) {
+        return {
+            state: "unsupported",
+            version: result.stdout.trim(),
+            unavailableReason: "unsupported-version",
+        };
+    }
+    return { state: "available", version: result.stdout.trim() };
+}
+// Maps a thrown error from the `version` call. CommandTimeoutError → probe-timed-out (state stays
+// "missing" so an unreachable engine never reads as available); a not-found denial → missing; any
+// other denial → policy-blocked.
+function resolveFromVersionError(error) {
+    if (error instanceof CommandTimeoutError) {
+        return { state: "missing", unavailableReason: "probe-timed-out" };
+    }
+    if (error instanceof CommandDeniedError) {
+        return isNotFoundDenial(error)
+            ? { state: "missing", unavailableReason: "executable-not-found" }
+            : { state: "policy-blocked", unavailableReason: "policy-blocked" };
+    }
+    return { state: "unsupported", unavailableReason: "probe-failed" };
+}
+function buildProbeDeps(deps) {
+    const policy = deps.policy ?? DEFAULT_SANDBOX_POLICY;
+    return {
+        workspace: hostWorkspace(deps.workspace),
+        // network:"inherit" — the host CLI process must reach the local daemon socket (D4). The CONTAINER
+        // is isolated by --network none at run time; detection runs only `version`/`info`.
+        policy: { ...policy, network: "inherit" },
+        commandRules: CONTAINER_TASK_RULES,
+        spawn: nodeSpawnFn,
+        processEnv: deps.processEnv,
+        now: deps.now,
+    };
+}
+// Confirms daemon liveness via `info`. A clean exit keeps "available"; a non-zero exit or a daemon-
+// down signature downgrades to not-running; an error is mapped like the version error.
+async function confirmDaemon(engine, runDeps, run, signal, base) {
+    try {
+        const result = await run({
+            command: engine,
+            args: ["info", "--format", "{{.ServerErrors}}"],
+            cwd: undefined,
+            timeoutMs: PER_CALL_TIMEOUT_MS,
+            signal,
+        }, runDeps);
+        const combined = `${result.stdout}\n${result.stderr}`;
+        if (result.exitCode !== 0 || matchesSignature(combined, DAEMON_DOWN_SIGNATURES)) {
+            return { state: "not-running", unavailableReason: "daemon-not-running" };
+        }
+        return base;
+    }
+    catch (error) {
+        if (error instanceof CommandTimeoutError) {
+            return { state: "not-running", unavailableReason: "probe-timed-out" };
+        }
+        return { state: "not-running", unavailableReason: "daemon-not-running" };
+    }
+}
+async function probeEngine(engine, deps, runDeps) {
+    const controller = new AbortController();
+    let versionResolution;
+    try {
+        const result = await deps.runCommand({
+            command: engine,
+            args: ["version", "--format", "{{.Server.Version}}"],
+            cwd: undefined,
+            timeoutMs: PER_CALL_TIMEOUT_MS,
+            signal: controller.signal,
+        }, runDeps);
+        versionResolution = resolveFromVersionResult(result);
+    }
+    catch (error) {
+        return resolveFromVersionError(error);
+    }
+    if (versionResolution.state !== "available") {
+        return versionResolution;
+    }
+    return confirmDaemon(engine, runDeps, deps.runCommand, controller.signal, versionResolution);
+}
+function statusFromResolution(engine, resolution) {
+    const hint = REMEDIATION_HINTS[resolution.state];
+    return {
+        engine,
+        state: resolution.state,
+        ...(resolution.version === undefined ? {} : { version: resolution.version }),
+        ...(resolution.unavailableReason === undefined
+            ? {}
+            : { unavailableReason: resolution.unavailableReason }),
+        ...(hint === undefined ? {} : { remediationHint: hint }),
+    };
+}
+function killSwitchStatus(engine) {
+    return {
+        engine,
+        state: "policy-blocked",
+        unavailableReason: "policy-blocked",
+        remediationHint: REMEDIATION_HINTS["policy-blocked"],
+    };
+}
+// Active container-engine probe (D1). NEVER throws; returns a structured ContainerCapabilityResponse.
+export async function detectContainerEngines(deps) {
+    const generatedAtMs = deps.now();
+    const deadlineMs = deps.deadlineMs ?? DEFAULT_CONTAINER_PROBE_DEADLINE_MS;
+    const engines = deps.engines ?? CONTAINER_ENGINE_IDS;
+    // Kill-switch: short-circuit EVERY engine to policy-blocked with NO spawn (assert in tests).
+    if (disabledByKillSwitch(deps.processEnv)) {
+        return {
+            schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+            generatedAtMs,
+            deadlineMs,
+            engines: engines.map((engine) => killSwitchStatus(engine)),
+            anyAvailable: false,
+        };
+    }
+    const runDeps = buildProbeDeps(deps);
+    const statuses = [];
+    for (const engine of engines) {
+        const resolution = await probeEngine(engine, deps, runDeps);
+        statuses.push(statusFromResolution(engine, resolution));
+    }
+    return {
+        schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+        generatedAtMs,
+        deadlineMs,
+        engines: statuses,
+        anyAvailable: statuses.some((status) => status.state === "available"),
+    };
+}

package/dist/runtime/containerRoutes.d.ts

@@ -0,0 +1,8 @@
+import type { UiHandlerDeps } from "../deps.js";
+import { type HandlerOutcome, type RouteContext, type RouteResult } from "../routes.js";
+export declare function handleContainerCapability(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleContainerCatalog(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleCreateContainerRun(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleDeleteContainerRun(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleContainerEvents(ctx: RouteContext, deps: UiHandlerDeps): HandlerOutcome;
+//# sourceMappingURL=containerRoutes.d.ts.map

package/dist/runtime/containerRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerRoutes.d.ts","sourceRoot":"","sources":["../../src/runtime/containerRoutes.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAiGtB,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAID,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAiBtB;AAKD,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAQ5F;AAID,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,CAQ5F"}

package/dist/runtime/containerRoutes.js

@@ -0,0 +1,207 @@
+// Issue #1388 (Epic #1491, ADR-0070, D5) — five /api/containers/* BFF route handlers for the governed
+// container pilot. CSRF is enforced by the server's state-changing-request gate (POST/DELETE flow
+// through it); GET routes are read-only and exempt. SSE framing mirrors /api/commands/*/events.
+// Layer-2 redaction is applied to the run RESULT and to EVERY SSE frame. The capability route
+// additionally requires a registered project root when `root` is supplied.
+//
+//   GET    /api/containers/capability?root=…   active engine probe → ContainerCapabilityResponse
+//   GET    /api/containers/catalog?projectId=…  catalog (503 when no engine)
+//   POST   /api/containers/runs                 run a catalog task → structured result (redacted)
+//   DELETE /api/containers/runs/:runId          cancel an in-flight run
+//   GET    /api/containers/events               SSE stream of run lifecycle events (redacted)
+import { parseContainerRunRequest } from "@oscharko-dev/keiko-contracts";
+import { ContainerRunnerError } from "./containerRunner-errors.js";
+import { SSE_HEADERS, readyMessage } from "../sse.js";
+import { errorBody, STREAMING, } from "../routes.js";
+const MAX_CONTAINER_BODY_BYTES = 16_000;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("container runner request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+function noRunnerDeps() {
+    return {
+        status: 503,
+        body: errorBody("CONTAINER_ENGINE_UNAVAILABLE", "Container runner is not configured for this BFF."),
+    };
+}
+function requireRunner(deps) {
+    return deps.containerRunner ?? noRunnerDeps();
+}
+function isRouteResult(value) {
+    return typeof value.status === "number";
+}
+function toRouteResult(error) {
+    return { status: error.status, body: errorBody(error.code, error.message) };
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_CONTAINER_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", reject);
+    });
+}
+async function readJsonObject(req) {
+    const raw = await readBody(req);
+    if (raw.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ContainerRunnerError("BAD_REQUEST", "Request body is not valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ContainerRunnerError("BAD_REQUEST", "Request body must be a JSON object.");
+    }
+    return parsed;
+}
+async function runHandler(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return {
+                status: 413,
+                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+            };
+        }
+        if (error instanceof ContainerRunnerError)
+            return toRouteResult(error);
+        throw error;
+    }
+}
+function redactValue(deps, value) {
+    return deps.redactor(value);
+}
+// GET /api/containers/capability — active daemon probe. When `root` is supplied it MUST be a
+// registered project (403 WORKSPACE_NOT_REGISTERED otherwise); `root` absent is allowed because the
+// capability is host-level (no workspace mount context needed for detection). The response is redacted.
+export async function handleContainerCapability(ctx, deps) {
+    const guard = requireRunner(deps);
+    if (isRouteResult(guard))
+        return guard;
+    const rawRoot = ctx.url.searchParams.get("root");
+    const root = rawRoot === null ? undefined : rawRoot.trim();
+    if (root !== undefined && root.length > 0) {
+        if (!deps.store.listProjects().some((project) => project.path === root)) {
+            return {
+                status: 403,
+                body: errorBody("WORKSPACE_NOT_REGISTERED", "The workspace directory is not a registered project."),
+            };
+        }
+    }
+    return runHandler(async () => {
+        const capability = await guard.capability(root ?? "");
+        return { status: 200, body: redactValue(deps, capability) };
+    });
+}
+// GET /api/containers/catalog — the allowlisted catalog for a project. 503 when no engine is
+// available so the surface degrades gracefully rather than throwing.
+export async function handleContainerCatalog(ctx, deps) {
+    const guard = requireRunner(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const projectId = ctx.url.searchParams.get("projectId");
+        if (projectId === null || projectId.length === 0) {
+            throw new ContainerRunnerError("BAD_REQUEST", "Query parameter 'projectId' is required.");
+        }
+        const catalog = await guard.listCatalog(projectId);
+        if (!catalog.engineAvailable) {
+            throw new ContainerRunnerError("CONTAINER_ENGINE_UNAVAILABLE", "No container engine is available.");
+        }
+        return { status: 200, body: redactValue(deps, catalog) };
+    });
+}
+// POST /api/containers/runs — run a catalog task. The result carries the structured outcome; Layer-2
+// redaction is applied to stdout/stderr before the body reaches the browser. An engine-unavailable
+// governance failure throws CONTAINER_ENGINE_UNAVAILABLE (503) before any run id is minted.
+export async function handleCreateContainerRun(ctx, deps) {
+    const guard = requireRunner(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const body = await readJsonObject(ctx.req);
+        const parsed = parseContainerRunRequest(body);
+        if (!parsed.ok) {
+            throw new ContainerRunnerError("BAD_REQUEST", parsed.errors.join("; "));
+        }
+        const input = {
+            projectId: parsed.value.projectId,
+            taskId: parsed.value.taskId,
+            ...(parsed.value.timeoutMs === undefined ? {} : { timeoutMs: parsed.value.timeoutMs }),
+            ...(parsed.value.requestId === undefined ? {} : { requestId: parsed.value.requestId }),
+        };
+        const raw = await guard.execute(input);
+        const redactStr = (value) => {
+            const redacted = deps.redactor(value);
+            return typeof redacted === "string" ? redacted : value;
+        };
+        const result = { ...raw, stdout: redactStr(raw.stdout), stderr: redactStr(raw.stderr) };
+        return { status: 200, body: result };
+    });
+}
+export function handleDeleteContainerRun(ctx, deps) {
+    const guard = requireRunner(deps);
+    if (isRouteResult(guard))
+        return guard;
+    const runId = ctx.params.runId ?? "";
+    if (!guard.abort(runId)) {
+        return { status: 404, body: errorBody("RUN_NOT_FOUND", "Container run not found.") };
+    }
+    return { status: 200, body: { ok: true } };
+}
+// SSE — one runner event becomes one message with `event: container:<kind>` and a redacted JSON
+// payload. A synthetic `ready` is emitted first so the client can transition from connecting to live.
+export function handleContainerEvents(ctx, deps) {
+    const guard = requireRunner(deps);
+    if (isRouteResult(guard))
+        return guard;
+    openContainerSseStream(ctx.res, guard, deps.redactor);
+    ctx.req.on("close", () => {
+        ctx.res.end();
+    });
+    return STREAMING;
+}
+function openContainerSseStream(res, manager, redactor) {
+    res.writeHead(200, SSE_HEADERS);
+    let seq = 0;
+    const unsubscribe = manager.subscribe((event) => {
+        seq += 1;
+        writeContainerEvent(res, event, seq, redactor);
+    });
+    res.write(readyMessage());
+    res.on("close", () => {
+        unsubscribe();
+    });
+}
+function writeContainerEvent(res, event, seq, redactor) {
+    const redacted = redactor(event);
+    const data = JSON.stringify(redacted);
+    const frame = `id: ${String(seq)}\nevent: container:${event.kind}\ndata: ${data}\n\n`;
+    if (!res.write(frame)) {
+        res.destroy();
+    }
+}

package/dist/runtime/containerRunner-errors.d.ts

@@ -0,0 +1,18 @@
+export declare const CONTAINER_RUNNER_ERROR_CODES: {
+    readonly PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND";
+    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
+    readonly IMAGE_NOT_ALLOWED: "IMAGE_NOT_ALLOWED";
+    readonly RUN_LIMIT_EXCEEDED: "RUN_LIMIT_EXCEEDED";
+    readonly RUN_NOT_FOUND: "RUN_NOT_FOUND";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly CONTAINER_ENGINE_UNAVAILABLE: "CONTAINER_ENGINE_UNAVAILABLE";
+    readonly INTERNAL: "INTERNAL";
+};
+export type ContainerRunnerErrorCode = (typeof CONTAINER_RUNNER_ERROR_CODES)[keyof typeof CONTAINER_RUNNER_ERROR_CODES];
+export declare class ContainerRunnerError extends Error {
+    readonly code: ContainerRunnerErrorCode;
+    readonly status: number;
+    constructor(code: ContainerRunnerErrorCode, message: string);
+}
+//# sourceMappingURL=containerRunner-errors.d.ts.map

package/dist/runtime/containerRunner-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerRunner-errors.d.ts","sourceRoot":"","sources":["../../src/runtime/containerRunner-errors.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,4BAA4B;;;;;;;;;;CAU/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,OAAO,4BAA4B,CAAC,CAAC;AAcnF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAgB,IAAI,EAAE,wBAAwB,CAAC;IAC/C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM;CAMnE"}

package/dist/runtime/containerRunner-errors.js

@@ -0,0 +1,42 @@
+// Issue #1388 (Epic #1491, ADR-0070) — typed failure modes for the governed container runner.
+// Callers switch on `code`; messages are static strings that never leak filesystem paths, raw
+// engine/OS error text, or the constructed argv into the HTTP response or SSE payload. Mirrors the
+// #1387 command-runner error model.
+//
+// Only PRE-spawn GOVERNANCE failures surface as a thrown ContainerRunnerError (the route maps each
+// to a 4xx/5xx envelope) — most importantly CONTAINER_ENGINE_UNAVAILABLE, thrown BEFORE any run id
+// is minted so there is no run/event/evidence for a run that never started. Every actual EXECUTION
+// outcome (non-zero exit, timeout, cancellation, image-missing, denied spawn) is reported as a
+// ContainerRunResult with a `failureReason`, never as a thrown error.
+export const CONTAINER_RUNNER_ERROR_CODES = {
+    PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+    TASK_NOT_FOUND: "TASK_NOT_FOUND",
+    IMAGE_NOT_ALLOWED: "IMAGE_NOT_ALLOWED",
+    RUN_LIMIT_EXCEEDED: "RUN_LIMIT_EXCEEDED",
+    RUN_NOT_FOUND: "RUN_NOT_FOUND",
+    BAD_REQUEST: "BAD_REQUEST",
+    PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+    CONTAINER_ENGINE_UNAVAILABLE: "CONTAINER_ENGINE_UNAVAILABLE",
+    INTERNAL: "INTERNAL",
+};
+const STATUS_MAP = {
+    PROJECT_NOT_FOUND: 404,
+    TASK_NOT_FOUND: 404,
+    IMAGE_NOT_ALLOWED: 403,
+    RUN_LIMIT_EXCEEDED: 429,
+    RUN_NOT_FOUND: 404,
+    BAD_REQUEST: 400,
+    PAYLOAD_TOO_LARGE: 413,
+    CONTAINER_ENGINE_UNAVAILABLE: 503,
+    INTERNAL: 500,
+};
+export class ContainerRunnerError extends Error {
+    code;
+    status;
+    constructor(code, message) {
+        super(message);
+        this.name = "ContainerRunnerError";
+        this.code = code;
+        this.status = STATUS_MAP[code];
+    }
+}

package/dist/runtime/containerRunner-evidence.d.ts

@@ -0,0 +1,24 @@
+import type { EvidenceManifest, EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import type { ContainerEngineId, ContainerFailureReason, ContainerTaskKind } from "@oscharko-dev/keiko-contracts";
+export declare const CONTAINER_RUN_EVIDENCE_KIND: "container-run";
+export type ContainerRunEvidenceEntry = EvidenceManifest;
+export interface ContainerRunEvidenceInput {
+    readonly runId: string;
+    readonly projectId: string;
+    readonly taskId: string;
+    readonly kind: ContainerTaskKind;
+    readonly engine: ContainerEngineId;
+    readonly imageId: string;
+    readonly argCount: number;
+    readonly exitCode: number | null;
+    readonly durationMs: number;
+    readonly timedOut: boolean;
+    readonly truncated: boolean;
+    readonly failureReason: ContainerFailureReason;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    readonly startedAt: number;
+}
+export declare function buildContainerRunEvidenceEntry(input: ContainerRunEvidenceInput): ContainerRunEvidenceEntry;
+export declare function appendContainerRunEvidence(store: EvidenceStore, entry: ContainerRunEvidenceEntry, redact: (input: string) => string): string;
+//# sourceMappingURL=containerRunner-evidence.d.ts.map

package/dist/runtime/containerRunner-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerRunner-evidence.d.ts","sourceRoot":"","sources":["../../src/runtime/containerRunner-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAIpF,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,2BAA2B,EAAG,eAAwB,CAAC;AAEpE,MAAM,MAAM,yBAAyB,GAAG,gBAAgB,CAAC;AAEzD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAkBD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,yBAAyB,GAC/B,yBAAyB,CAwC3B;AAMD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,yBAAyB,EAChC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,MAAM,CAGR"}

package/dist/runtime/containerRunner-evidence.js

@@ -0,0 +1,74 @@
+// Issue #1388 (Epic #1491, ADR-0070, D6) — content-free container-run evidence. Each finished run
+// writes a standard EvidenceManifest via the existing EvidenceStore.put port so the shared evidence
+// list/detail APIs can parse it. It carries COUNTS and ENUMS ONLY — never the constructed docker/
+// podman argv, never the raw image ref free-text (only the closed-catalog image id), never the
+// workspace path, never any container output (ADR-0048 content-free invariant). Mirrors
+// command-runner-evidence.ts.
+import { deepRedactStrings } from "@oscharko-dev/keiko-evidence";
+import { EVIDENCE_SCHEMA_VERSION } from "@oscharko-dev/keiko-evidence";
+import { HARNESS_VERSION } from "@oscharko-dev/keiko-harness";
+export const CONTAINER_RUN_EVIDENCE_KIND = "container-run";
+function containerRunOutcome(input) {
+    switch (input.failureReason) {
+        case "none":
+            return "completed";
+        case "timed-out":
+            return "limit-exceeded";
+        case "cancelled":
+            return "cancelled";
+        default:
+            return "failed";
+    }
+}
+// PURE. Builds the on-disk manifest from a finished run. Identifiers/counts only; the docker argv,
+// the raw image ref, the workspace path, and all output are excluded. The caller supplies
+// runId/startedAt (no clock, no randomness here) so evidence stays deterministic.
+export function buildContainerRunEvidenceEntry(input) {
+    const runId = input.runId;
+    return {
+        evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
+        run: {
+            runId,
+            fingerprint: runId,
+            harnessVersion: HARNESS_VERSION,
+            taskType: CONTAINER_RUN_EVIDENCE_KIND,
+            outcome: containerRunOutcome(input),
+            startedAt: input.startedAt,
+            finishedAt: input.startedAt + input.durationMs,
+            durationMs: input.durationMs,
+        },
+        model: { modelId: "container-runner", costClass: "unknown" },
+        usageTotals: { promptTokens: 0, completionTokens: 0, requestCount: 0, totalLatencyMs: 0 },
+        context: {
+            workspaceRoot: input.projectId,
+            totalCandidates: 0,
+            usedBytes: 0,
+            budgetBytes: 0,
+            droppedForBudget: 0,
+            entries: [],
+        },
+        stateTransitions: [],
+        toolCalls: [],
+        commandExecutions: [
+            {
+                seq: 1,
+                ts: input.startedAt,
+                // The container ENGINE is the executable; the catalog image id rides in argCount/identity,
+                // never as a free-text leaf. argCount is the docker argv length, never the argv tokens.
+                executable: input.engine,
+                argCount: input.argCount,
+                exitCode: input.exitCode,
+                timedOut: input.timedOut,
+                durationMs: input.durationMs,
+            },
+        ],
+    };
+}
+// Defense in depth: applies the live redactor to every string leaf before serializing. All known
+// leaves (engine, projectId, runId, taskId) are structurally safe today; a future schema addition
+// inherits the redaction automatically. Mirrors appendCommandRunEvidence. Best-effort at the call
+// site: a write hiccup must never corrupt a real run result.
+export function appendContainerRunEvidence(store, entry, redact) {
+    const safe = deepRedactStrings(entry, redact);
+    return store.put(safe.run.runId, JSON.stringify(safe, null, 2));
+}

package/dist/runtime/containerRunner.d.ts

@@ -0,0 +1,37 @@
+import { type RunCommandDeps, type SandboxPolicy } from "@oscharko-dev/keiko-tools";
+import { type ContainerCapabilityResponse, type ContainerExecutionPolicy, type ContainerResourceLimits, type ContainerRunResult, type ContainerRunnerEvent, type ContainerTask, type ContainerTaskCatalog } from "@oscharko-dev/keiko-contracts";
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import type { UiStore } from "../store/index.js";
+export declare const DEFAULT_CONTAINER_RESOURCE_LIMITS: ContainerResourceLimits;
+export declare const DEFAULT_CONTAINER_EXECUTION_POLICY: ContainerExecutionPolicy;
+export declare const DEFAULT_CONTAINER_TASKS: readonly ContainerTask[];
+export declare function buildContainerRunArgv(task: ContainerTask, policy: ContainerExecutionPolicy, workspaceRoot: string): readonly string[];
+export interface ContainerRunInput {
+    readonly projectId: string;
+    readonly taskId: string;
+    readonly timeoutMs?: number | undefined;
+    readonly requestId?: string | undefined;
+}
+export type ContainerRunnerEventEmitter = (event: ContainerRunnerEvent) => void;
+export interface ContainerRunnerManager {
+    readonly capability: (projectId: string) => Promise<ContainerCapabilityResponse>;
+    readonly listCatalog: (projectId: string) => Promise<ContainerTaskCatalog>;
+    readonly execute: (input: ContainerRunInput) => Promise<ContainerRunResult>;
+    readonly abort: (runId: string) => boolean;
+    readonly subscribe: (listener: ContainerRunnerEventEmitter) => () => void;
+    readonly inFlightCount: () => number;
+}
+export interface ContainerRunnerManagerOptions {
+    readonly store: UiStore;
+    readonly evidenceStore?: EvidenceStore | undefined;
+    readonly policy?: SandboxPolicy | undefined;
+    readonly executionPolicy?: ContainerExecutionPolicy | undefined;
+    readonly catalog?: readonly ContainerTask[] | undefined;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly redactor?: ((input: string) => string) | undefined;
+    readonly runDeps?: Partial<RunCommandDeps> | undefined;
+    readonly detect?: ((projectId: string) => Promise<ContainerCapabilityResponse>) | undefined;
+    readonly now?: (() => number) | undefined;
+}
+export declare function createContainerRunnerManager(opts: ContainerRunnerManagerOptions): ContainerRunnerManager;
+//# sourceMappingURL=containerRunner.d.ts.map

package/dist/runtime/containerRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerRunner.d.ts","sourceRoot":"","sources":["../../src/runtime/containerRunner.ts"],"names":[],"mappings":"AAaA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAE7B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAEzB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAOlE,OAAO,KAAK,EAAW,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,eAAO,MAAM,iCAAiC,EAAE,uBAI/C,CAAC;AAQF,eAAO,MAAM,kCAAkC,EAAE,wBAQhD,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,SAAS,aAAa,EAc1D,CAAC;AAOH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,wBAAwB,EAChC,aAAa,EAAE,MAAM,GACpB,SAAS,MAAM,EAAE,CA6BnB;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAEhF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACjF,QAAQ,CAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC3E,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC5E,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,2BAA2B,KAAK,MAAM,IAAI,CAAC;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAEvD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5F,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAuaD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,6BAA6B,GAClC,sBAAsB,CAExB"}