spawnfile 0.1.13 → 0.1.17

package/dist/compiler/training/broker/supervisor.js

@@ -0,0 +1,173 @@
+import { chmodSync, chownSync, lstatSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import path from "node:path";
+import { SpawnfileError } from "../../../shared/index.js";
+import { DAIMON_ORGANIZATION_UID } from "./paths.js";
+export const TRAINING_SUPERVISOR_PROTOCOL = "spawnfile.training-slot-supervisor.v1";
+export const TRAINING_SUPERVISOR_MAX_REQUEST_BYTES = 4_096;
+const NONCE = /^[a-f0-9]{64}$/u;
+/**
+ * Bringing a slot up, receipt included — the only way this container starts one.
+ *
+ * `provision → start` alone was the whole start-up path, and `canaries` and
+ * `publishReceipt` were reachable only from `recycle`. The first trial of every
+ * run therefore executed with no worker-uid denial evidence at all, and a
+ * refusal that should have cost nothing surfaced only after that trial's spend.
+ * Trial 1 is exactly the trial whose sealed datasets have never been probed, so
+ * it is the one that most needs the evidence.
+ *
+ * The receipt this publishes carries generation 1..N and a nonce of the
+ * container's own, so an evaluator that reads `preflight.json` before its first
+ * wake sees the same `noopolis.daimon.grok-slot-preflight.v2` shape a recycle
+ * publishes, from the same canaries.
+ */
+export const startTrainingSlot = async (runtime, nonce) => {
+    await runtime.provision();
+    await runtime.start();
+    const canaries = await runtime.canaries();
+    const generation = await runtime.nextGeneration();
+    const receipt = await runtime.publishReceipt({ generation, nonce, canaries });
+    runtime.log(`slot start generation=${generation} canaries=${canaries.length} receipt=${receipt}`);
+    return { generation, receipt, canaries: canaries.length };
+};
+/**
+ * The single-verb root slot supervisor.
+ *
+ * One verb, one argument, no path or command ever supplied by the caller: the
+ * whole point of D4 is that recycling replays the container's own audited
+ * provisioning rather than exposing a root file-system API to the evaluator.
+ * Recycles are serialized — a second caller waits rather than interleaving a
+ * wipe with a provision.
+ */
+export const createTrainingSlotSupervisor = (options) => {
+    const organizationUid = options.organizationUid ?? DAIMON_ORGANIZATION_UID;
+    const drainTimeoutMs = options.drainTimeoutMs ?? 120_000;
+    const now = options.now ?? Date.now;
+    let queue = Promise.resolve();
+    const recycle = async (nonce, peerUid) => {
+        if (peerUid !== organizationUid)
+            throw new SpawnfileError("validation_error", `Grok slot recycle refused for uid ${peerUid}`);
+        if (!NONCE.test(nonce))
+            throw new SpawnfileError("validation_error", "Grok slot recycle requires a 32-byte hex nonce");
+        const started = now();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), drainTimeoutMs);
+        try {
+            await options.runtime.drain(controller.signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        await options.runtime.stop();
+        await options.runtime.wipe();
+        await options.runtime.provision();
+        await options.runtime.start();
+        const canaries = await options.runtime.canaries();
+        const generation = await options.runtime.nextGeneration();
+        const receipt = await options.runtime.publishReceipt({ generation, nonce, canaries });
+        const durationMs = now() - started;
+        options.runtime.log(`recycle generation=${generation} canaries=${canaries.length} durationMs=${durationMs}`);
+        return { ok: true, verb: "recycle", generation, nonce, receipt, durationMs };
+    };
+    return {
+        /** Serialized: a recycle already in flight completes before the next one starts. */
+        recycle: (nonce, peerUid) => {
+            const next = queue.then(() => recycle(nonce, peerUid));
+            queue = next.catch(() => undefined);
+            return next;
+        }
+    };
+};
+const failure = (message) => `${JSON.stringify({ v: TRAINING_SUPERVISOR_PROTOCOL, ok: false, error: message })}\n`;
+/**
+ * Re-establishes, and re-checks on every connection, the only uid gate this
+ * socket has.
+ *
+ * The scope asked for `SO_PEERCRED`. Node exposes no ancillary-data or
+ * peer-credential API on a unix socket and no native addon ships in this
+ * image, so the gate is the socket node itself, which the kernel enforces on
+ * `connect()` exactly as it does on `open()`: the node is
+ * `root:<organization gid> 0660` inside a root-owned `0711` directory on
+ * tmpfs, where modes *are* enforced. Only uid 2000 (and root) can connect;
+ * uid 2200 gets `EACCES` before a byte is written. A `0600` root-owned socket
+ * — the literal reading of the scope — would deny the one caller it exists
+ * for, so this is the same restriction stated in the only mechanism available.
+ * The directory holds no write permission for anyone but root, so the node
+ * cannot be replaced by a laxer one.
+ */
+export const assertTrainingSupervisorSocketIdentity = (socketPath, organizationGid) => {
+    const directory = lstatSync(path.posix.dirname(socketPath));
+    if (!directory.isDirectory() || directory.uid !== 0 || directory.gid !== 0 || (directory.mode & 0o777) !== 0o711) {
+        throw new SpawnfileError("runtime_error", "The slot supervisor socket directory must be root-owned 0711");
+    }
+    const node = lstatSync(socketPath);
+    if (!node.isSocket() || node.uid !== 0 || node.gid !== organizationGid || (node.mode & 0o777) !== 0o660) {
+        throw new SpawnfileError("runtime_error", "The slot supervisor socket must be root-owned, organization-group 0660");
+    }
+};
+/**
+ * Line-delimited JSON over a unix socket. Every request is bounded,
+ * single-line, and must name the protocol, the one verb and nothing else.
+ */
+export const serveTrainingSlotSupervisor = (supervisor, socketPath, log, organizationUid = DAIMON_ORGANIZATION_UID) => {
+    const server = createServer((socket) => {
+        let peerUid;
+        try {
+            assertTrainingSupervisorSocketIdentity(socketPath, organizationUid);
+            peerUid = organizationUid;
+        }
+        catch (error) {
+            log(`refusing a connection on an unverified supervisor socket: ${error instanceof Error ? error.message : "unknown"}`);
+        }
+        let buffer = "", settled = false;
+        socket.setTimeout(600_000, () => socket.destroy());
+        const answer = (line) => { settled = true; socket.end(line); };
+        socket.on("data", (chunk) => {
+            if (settled)
+                return;
+            buffer += chunk.toString("utf8");
+            if (Buffer.byteLength(buffer) > TRAINING_SUPERVISOR_MAX_REQUEST_BYTES) {
+                answer(failure("request too large"));
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = buffer.slice(0, newline);
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                answer(failure("request is not JSON"));
+                return;
+            }
+            if (request.v !== TRAINING_SUPERVISOR_PROTOCOL || request.verb !== "recycle" || typeof request.nonce !== "string"
+                || Object.keys(request).length !== 3) {
+                answer(failure("unsupported request"));
+                return;
+            }
+            if (peerUid === undefined) {
+                answer(failure("peer identity is unavailable"));
+                return;
+            }
+            supervisor.recycle(request.nonce, peerUid)
+                .then((result) => answer(`${JSON.stringify({ v: TRAINING_SUPERVISOR_PROTOCOL, ...result })}\n`))
+                .catch((error) => {
+                const message = error instanceof Error ? error.message : "recycle failed";
+                log(`recycle failed: ${message}`);
+                answer(failure(message));
+            });
+        });
+        socket.on("error", () => socket.destroy());
+    });
+    rmSync(socketPath, { force: true });
+    server.listen(socketPath, () => {
+        chownSync(socketPath, 0, 0);
+        chmodSync(socketPath, 0o660);
+        chownSync(socketPath, 0, organizationUid);
+        assertTrainingSupervisorSocketIdentity(socketPath, organizationUid);
+        log(`slot supervisor listening on ${socketPath}`);
+    });
+    return server;
+};

package/dist/compiler/training/container/contract.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export declare const trainingImageSchema: z.ZodString;
+export declare const trainingContainerConfigSchema: z.ZodObject<{
+    version: z.ZodEnum<{
+        "spawnfile.training-container.v1": "spawnfile.training-container.v1";
+        "spawnfile.training-container.v3": "spawnfile.training-container.v3";
+    }>;
+    dockerContext: z.ZodString;
+    inputs: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        destination: z.ZodString;
+    }, z.core.$strict>>;
+    output: z.ZodObject<{
+        source: z.ZodString;
+        destination: z.ZodLiteral<"/run/training/output">;
+    }, z.core.$strict>;
+    auth: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        provider: z.ZodEnum<{
+            codex: "codex";
+            claude: "claude";
+        }>;
+    }, z.core.$strict>>;
+    broker: z.ZodOptional<z.ZodObject<{
+        engine: z.ZodLiteral<"grok">;
+        realmVolume: z.ZodString;
+        bootstrap: z.ZodString;
+        declaration: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TrainingContainerConfig = z.infer<typeof trainingContainerConfigSchema>;

package/dist/compiler/training/container/contract.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { z } from "zod";
+const hostPath = z.string().min(1).refine((value) => path.isAbsolute(value) && !/[,\r\n\0]/u.test(value), "Expected an absolute bind path");
+const inputPath = z.string().regex(/^\/run\/training\/inputs\/[A-Za-z0-9._/-]+$/u).refine((value) => path.posix.normalize(value) === value && !value.endsWith("/"));
+export const trainingImageSchema = z.string().regex(/^(?:sha256:[a-f0-9]{64}|[A-Za-z0-9][A-Za-z0-9._:/-]*@sha256:[a-f0-9]{64})$/u);
+const brokerLaunchSchema = z.object({
+    engine: z.literal("grok"),
+    /** The named Docker volume holding the training Grok realm: `auth.json` and the broker credential journal, nothing else. */
+    realmVolume: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u),
+    /** Host leaf of the dedicated training Grok login. Never the desktop `~/.grok/auth.json`. */
+    bootstrap: hostPath,
+    /** `spawnfile.training-broker.v1`, written beside the launch config and bound read-only into the container. */
+    declaration: hostPath
+}).strict();
+export const trainingContainerConfigSchema = z.object({
+    version: z.enum(["spawnfile.training-container.v1", "spawnfile.training-container.v3"]),
+    dockerContext: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u),
+    inputs: z.array(z.object({ source: hostPath, destination: inputPath }).strict()).min(1).max(64),
+    output: z.object({ source: hostPath, destination: z.literal("/run/training/output") }).strict(),
+    auth: z.array(z.object({ source: hostPath, provider: z.enum(["codex", "claude"]) }).strict()).max(2),
+    /** Present only on `spawnfile.training-container.v3`: the brokered Grok slot this container runs as root. */
+    broker: brokerLaunchSchema.optional()
+}).strict().superRefine((value, context) => {
+    const destinations = value.inputs.map((entry) => entry.destination);
+    if (destinations.some((entry, index) => destinations.some((other, otherIndex) => otherIndex !== index && (entry === other || entry.startsWith(`${other}/`))))) {
+        context.addIssue({ code: "custom", message: "Input destinations must not overlap" });
+    }
+    if (new Set(value.auth.map((entry) => entry.provider)).size !== value.auth.length)
+        context.addIssue({ code: "custom", message: "Duplicate auth provider" });
+    if ((value.version === "spawnfile.training-container.v3") !== (value.broker !== undefined)) {
+        context.addIssue({ code: "custom", message: "Only spawnfile.training-container.v3 declares a broker slot, and it always does" });
+    }
+});

package/dist/compiler/training/container/index.d.ts

@@ -0,0 +1,4 @@
+export { trainingContainerConfigSchema, trainingImageSchema } from "./contract.js";
+export type { TrainingContainerConfig } from "./contract.js";
+export { launchTrainingContainer } from "./launch.js";
+export type { LaunchTrainingContainerOptions } from "./launch.js";

package/dist/compiler/training/container/index.js

@@ -0,0 +1,2 @@
+export { trainingContainerConfigSchema, trainingImageSchema } from "./contract.js";
+export { launchTrainingContainer } from "./launch.js";

package/dist/compiler/training/container/launch.d.ts

@@ -0,0 +1,18 @@
+import type { TrainingContext } from "../contract.js";
+import { type TrainingDockerProcess } from "./process.js";
+export interface LaunchTrainingContainerOptions {
+    image: string;
+    configPath: string;
+    context: TrainingContext;
+    args: readonly string[];
+    timeoutMs: number;
+    signal?: AbortSignal;
+    streams: {
+        stdout(line: string): void;
+        stderr(line: string): void;
+    };
+    process?: TrainingDockerProcess;
+    preparationPath?: string;
+    repairPath?: string;
+}
+export declare const launchTrainingContainer: (options: LaunchTrainingContainerOptions) => Promise<number>;

package/dist/compiler/training/container/launch.js

@@ -0,0 +1,173 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { DAIMON_CODEX_NATIVE_SANDBOX_DOCKER_SECURITY_OPTS } from "../../../shared/index.js";
+import { assertNotDesktopGrokAuth } from "../broker/entrypoint.js";
+import { TRAINING_BROKER_ENTRYPOINT, trainingBrokerMounts, trainingBrokerSecurityArgs, trainingBrokerTmpfsTargets } from "./security.js";
+import { parseDetachedContainerInspect } from "../../runProjectDocker.js";
+import { trainingImageSchema } from "./contract.js";
+import { prepareTrainingContainer } from "./prepare.js";
+import { runTrainingDocker } from "./process.js";
+import { repairEnvelopeSchema } from "../repair/contract.js";
+import { hashJson } from "../preparation/files.js";
+import { parseTrainingMappedPreparation } from "../preparation/contract.js";
+const inspectFormat = "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}";
+export const launchTrainingContainer = async (options) => {
+    if (options.signal?.aborted)
+        return 130;
+    const image = trainingImageSchema.parse(options.image);
+    const uid = process.getuid?.(), gid = process.getgid?.();
+    if (uid === undefined || gid === undefined || uid === 0)
+        throw Error("Training requires an explicit non-root local user");
+    const configBytes = await readFile(options.configPath, "utf8");
+    if (Buffer.byteLength(configBytes) > 1024 * 1024)
+        throw Error("Training launch config exceeds 1 MiB");
+    const prepared = await prepareTrainingContainer(JSON.parse(configBytes), options.context, options.args);
+    // D2: the training Grok login is a dedicated one. Refuse the developer's desktop leaf before Docker ever sees it.
+    if (prepared.config.broker)
+        assertNotDesktopGrokAuth(prepared.config.broker.bootstrap);
+    if (options.preparationPath) {
+        if (await realpath(options.preparationPath) !== options.preparationPath)
+            throw Error("Preparation receipt path must be canonical");
+        parseTrainingMappedPreparation(JSON.parse(await readFile(options.preparationPath, "utf8")));
+    }
+    if (options.repairPath) {
+        if (await realpath(options.repairPath) !== options.repairPath)
+            throw Error("Repair receipt path must be canonical");
+        const raw = JSON.parse(await readFile(options.repairPath, "utf8"));
+        const envelope = repairEnvelopeSchema.parse(raw);
+        if (hashJson(raw.receipt) !== envelope.digest || envelope.receipt.current.imageId !== image ||
+            !prepared.config.inputs.some(input => input.destination === envelope.receipt.parent.root))
+            throw Error("Repair receipt launch identity mismatch");
+    }
+    const execute = options.process ?? runTrainingDocker;
+    const controller = new AbortController(), deadline = Date.now() + options.timeoutMs;
+    let interrupted = false, timedOut = false;
+    const interrupt = () => { interrupted = true; controller.abort(); };
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, options.timeoutMs);
+    options.signal?.addEventListener("abort", interrupt, { once: true });
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", interrupt);
+    if (options.signal?.aborted)
+        interrupt();
+    const prefix = ["--context", prepared.config.dockerContext];
+    const call = async (args, cleanup = false, stream = false) => {
+        if (!cleanup && controller.signal.aborted)
+            throw Error("Container operation cancelled");
+        return execute([...prefix, ...args], {
+            timeoutMs: cleanup ? 10_000 : Math.max(1, deadline - Date.now()),
+            ...(cleanup ? {} : { signal: controller.signal }), ...(stream ? options.streams : {})
+        });
+    };
+    const name = `spawnfile-training-${randomUUID()}`;
+    const labels = { "com.spawnfile.training.owner": name };
+    let privateRoot, containerId, creationAttempted = false;
+    let expectedImage, lastLine = "", closureVerified = false;
+    try {
+        const endpoint = await execute(["context", "inspect", prepared.config.dockerContext, "--format", "{{json .Endpoints.docker.Host}}"], { timeoutMs: 10_000, signal: controller.signal });
+        if (endpoint.code !== 0 || !/^unix:\/\//u.test(JSON.parse(endpoint.stdout)))
+            throw Error("Training requires an explicitly selected local Unix Docker context");
+        const inspected = await call(["image", "inspect", image, "--format", "{{.Id}}"]);
+        expectedImage = inspected.stdout.trim();
+        if (inspected.code !== 0 || !/^sha256:[a-f0-9]{64}$/u.test(expectedImage) || (image.startsWith("sha256:") && image !== expectedImage))
+            throw Error("Training image must be locally available with an immutable identity");
+        privateRoot = await realpath(await mkdtemp(path.join(path.dirname(prepared.config.output.source), ".spawnfile-training-container-")));
+        await chmod(privateRoot, 0o700);
+        const contextFile = path.join(privateRoot, "context.json");
+        await writeFile(contextFile, JSON.stringify(prepared.context), { mode: 0o444, flag: "wx" });
+        const mounts = [...prepared.config.inputs.map((entry) => `type=bind,src=${entry.source},dst=${entry.destination},readonly`),
+            `type=bind,src=${prepared.config.output.source},dst=/run/training/output`,
+            `type=bind,src=${contextFile},dst=/run/paideia/context.json,readonly`,
+            ...options.preparationPath ? [`type=bind,src=${options.preparationPath},dst=/run/paideia/preparation.json,readonly`] : [],
+            ...options.repairPath ? [`type=bind,src=${options.repairPath},dst=/run/paideia/repair.json,readonly`] : [],
+            ...prepared.config.auth.map((entry) => `type=bind,src=${entry.source},dst=/run/paideia-auth/${entry.provider},readonly`)];
+        const broker = prepared.config.broker;
+        // A brokered Grok slot runs the launcher, the broker and the model's own worker uid inside this container, so it
+        // starts as root with the production Daimon capability set instead of the host user with no capabilities at all.
+        const privilege = broker
+            ? [...await trainingBrokerSecurityArgs(privateRoot), "--pids-limit", "2048",
+                ...trainingBrokerTmpfsTargets().flatMap((entry) => ["--tmpfs", `${entry.path}:rw,nosuid,nodev,size=${entry.size},mode=${entry.mode}`])]
+            : ["--user", `${uid}:${gid}`, "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
+                ...DAIMON_CODEX_NATIVE_SANDBOX_DOCKER_SECURITY_OPTS, "--pids-limit", "512",
+                "--tmpfs", `/tmp:rw,nosuid,nodev,size=1g,uid=${uid},gid=${gid},mode=1777`, "--tmpfs", `/work:rw,nosuid,nodev,size=4g,uid=${uid},gid=${gid},mode=700`,
+                "--tmpfs", `/home/training:rw,nosuid,nodev,size=1g,uid=${uid},gid=${gid},mode=700`];
+        const args = ["create", "--name", name, "--label", `com.spawnfile.training.owner=${name}`,
+            "--init", "--read-only", ...privilege,
+            "--env", "HOME=/home/training", "--workdir", "/work", "--entrypoint", broker ? TRAINING_BROKER_ENTRYPOINT : "/opt/training/bin/train",
+            ...[...mounts, ...(broker ? trainingBrokerMounts(broker) : [])].flatMap((mount) => ["--mount", mount]),
+            ...(prepared.viewerPort === undefined ? [] : ["--publish", `127.0.0.1:${prepared.viewerPort}:${prepared.viewerPort}`]), expectedImage,
+            "train", "--spawnfile-context", "/run/paideia/context.json", ...prepared.args];
+        creationAttempted = true;
+        const created = await call(args);
+        containerId = created.stdout.trim();
+        if (created.code !== 0 || !/^[a-f0-9]{64}$/u.test(containerId)) {
+            let diagnostic = created.stderr;
+            for (const auth of prepared.config.auth)
+                diagnostic = diagnostic.replaceAll(auth.source, "[auth source]");
+            diagnostic = diagnostic.replace(/\p{Cc}/gu, " ").trim().slice(0, 2048);
+            throw Error(`Docker did not return a valid training container identity${diagnostic ? `: ${diagnostic}` : ""}`);
+        }
+        const identity = await call(["inspect", "--format", inspectFormat, containerId]);
+        if (identity.code !== 0 || parseDetachedContainerInspect(identity.stdout, containerId, labels, name).imageId !== expectedImage)
+            throw Error("Training container identity mismatch");
+        if (controller.signal.aborted)
+            throw Error("Container operation cancelled");
+        const result = await execute([...prefix, "start", "--attach", containerId], {
+            timeoutMs: Math.max(1, deadline - Date.now()), signal: controller.signal,
+            stdout: (line) => { if (line.trim())
+                lastLine = line; options.streams.stdout(line); }, stderr: options.streams.stderr
+        });
+        const terminal = await call(["inspect", "--format", "{{json .State}}", containerId]);
+        const state = JSON.parse(terminal.stdout);
+        if (terminal.code !== 0 || state.Running !== false || !Number.isInteger(state.ExitCode) || result.code !== state.ExitCode)
+            throw Error("Training container final state is unverified");
+        if (state.ExitCode !== 0 && state.ExitCode !== 1)
+            return state.ExitCode;
+        const receipt = JSON.parse(lastLine);
+        if (receipt.status !== "completed" || typeof receipt.index !== "string" || !receipt.index.startsWith("/run/training/output/") || path.posix.normalize(receipt.index) !== receipt.index)
+            throw Error("Training exited without a valid final receipt");
+        const artifact = path.join(prepared.config.output.source, receipt.index.slice("/run/training/output/".length));
+        if (await realpath(artifact) !== artifact || !(await stat(artifact)).isFile())
+            throw Error("Training completion artifact is missing or escapes output");
+        return state.ExitCode;
+    }
+    catch (error) {
+        if (interrupted)
+            return 130;
+        if (timedOut)
+            throw Error("Container training exceeded command deadline");
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", interrupt);
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", interrupt);
+        try {
+            if (creationAttempted) {
+                // A timed-out create may still have created our uniquely labelled container.
+                const found = await call(["inspect", "--format", inspectFormat, name], true);
+                if (found.code === 0) {
+                    const id = JSON.parse(found.stdout.split("\n")[0]);
+                    if (typeof id !== "string" || parseDetachedContainerInspect(found.stdout, id, labels, name).imageId !== expectedImage || (containerId && /^[a-f0-9]{64}$/u.test(containerId) && id !== containerId))
+                        throw Error("Refusing cleanup of unverified training container");
+                    const removed = await call(["rm", "--force", id], true);
+                    const remaining = await call(["container", "ls", "--all", "--no-trunc", "--filter", `id=${id}`, "--format", "{{.ID}}"], true);
+                    if (removed.code !== 0 || remaining.code !== 0 || remaining.stdout.trim())
+                        throw Error("Training container cleanup is unverified");
+                    closureVerified = true;
+                }
+                else {
+                    const remaining = await call(["container", "ls", "--all", "--filter", `name=^/${name}$`, "--format", "{{.ID}}"], true);
+                    if (remaining.code !== 0 || remaining.stdout.trim())
+                        throw Error("Training container closure is unknown");
+                    closureVerified = true;
+                }
+            }
+        }
+        finally {
+            if (privateRoot && (!creationAttempted || closureVerified))
+                await rm(privateRoot, { recursive: true, force: true });
+        }
+    }
+};

package/dist/compiler/training/container/prepare.d.ts

@@ -0,0 +1,8 @@
+import { type TrainingContext } from "../contract.js";
+import { type TrainingContainerConfig } from "./contract.js";
+export declare const prepareTrainingContainer: (raw: unknown, context: TrainingContext, args: readonly string[]) => Promise<{
+    config: TrainingContainerConfig;
+    context: TrainingContext;
+    args: string[];
+    viewerPort?: number;
+}>;

package/dist/compiler/training/container/prepare.js

@@ -0,0 +1,80 @@
+import { lstat, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { trainingContextSchema } from "../contract.js";
+import { trainingContainerConfigSchema } from "./contract.js";
+const inside = (root, value) => value === root || value.startsWith(`${root}/`);
+export const prepareTrainingContainer = async (raw, context, args) => {
+    const config = trainingContainerConfigSchema.parse(raw);
+    const entries = [...config.inputs, config.output];
+    const home = path.resolve(os.homedir());
+    const globalConfigRoots = [".codex", ".claude", ".grok", ".ssh", ".config"].map((name) => path.join(home, name));
+    for (const entry of [...entries, ...config.auth]) {
+        const canonical = await realpath(entry.source);
+        if (canonical !== entry.source)
+            throw Error("Training bind sources must be canonical, without symlink aliases");
+        const stat = await lstat(canonical);
+        if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory()))
+            throw Error("Training binds require regular files or directories");
+        if (config.auth.includes(entry) && !stat.isFile())
+            throw Error("Auth must be a single regular leaf file");
+        if (entries.includes(entry)) {
+            if (["/", "/etc", "/var", "/run", "/tmp", "/opt", "/usr", "/Users", "/home", home].includes(canonical) || globalConfigRoots.some((root) => inside(root, canonical)))
+                throw Error("Host homes, configuration and system roots cannot be training inputs");
+            if (config.auth.some((auth) => inside(canonical, auth.source)))
+                throw Error("Auth must not be exposed through input or output mounts");
+        }
+    }
+    if (config.inputs.some((entry, index) => config.inputs.some((other, otherIndex) => index !== otherIndex && inside(entry.source, other.source))))
+        throw Error("Training input source roots must not overlap");
+    if (!(await lstat(config.output.source)).isDirectory())
+        throw Error("Training output must be an existing directory");
+    if (config.inputs.some((entry) => inside(entry.source, config.output.source) || inside(config.output.source, entry.source)))
+        throw Error("Training output and inputs must not overlap");
+    const map = (value) => {
+        const absolute = path.resolve(value);
+        const entry = entries.find((item) => inside(item.source, absolute));
+        if (!entry)
+            throw Error(`Training path is not covered by a declared mount: ${value}`);
+        return path.posix.join(entry.destination, path.relative(entry.source, absolute).split(path.sep).join("/"));
+    };
+    const source = (entry) => ({ ...entry, sourcePath: map(entry.sourcePath) });
+    const mapped = trainingContextSchema.parse({ ...context,
+        project: { ...context.project, root: map(context.project.root), manifest: map(context.project.manifest) },
+        agent: { ...context.agent, source: map(context.agent.source) },
+        sources: context.sources.map(source), documents: context.documents.map(source), skills: context.skills.map(source)
+    });
+    const mappedArgs = [...args];
+    let viewerPort;
+    for (let index = 0; index < mappedArgs.length; index++) {
+        const flag = mappedArgs[index];
+        if (["--train", "--test", "--out", "--cost-config"].includes(flag)) {
+            const value = mappedArgs[++index];
+            if (!value)
+                throw Error(`Missing ${flag} path`);
+            mappedArgs[index] = map(value);
+            if (flag === "--out" && !inside("/run/training/output", mappedArgs[index]))
+                throw Error("Training --out must use the writable output mount");
+        }
+        else if (flag === "--resource") {
+            const value = mappedArgs[++index] ?? "", equals = value.indexOf("=");
+            if (equals < 1)
+                throw Error("Expected resource=id path mapping");
+            mappedArgs[index] = `${value.slice(0, equals)}=${map(value.slice(equals + 1))}`;
+        }
+        else if (flag === "--bridge-command") {
+            const value = mappedArgs[++index] ?? "";
+            if (!/^\/opt\/training\/[A-Za-z0-9._/-]+$/u.test(value) || path.posix.normalize(value) !== value)
+                throw Error("Bridge must be an installed executable under /opt/training");
+        }
+        else if (flag === "--view") {
+            const value = mappedArgs[++index] ?? "";
+            const port = Number(value);
+            if (viewerPort !== undefined || !/^\d+$/u.test(value) || !Number.isSafeInteger(port) || port < 1 || port > 65535)
+                throw Error("Container --view requires one explicit port from 1 to 65535");
+            viewerPort = port;
+            mappedArgs[index] = String(port);
+        }
+    }
+    return { config, context: mapped, args: mappedArgs, ...(viewerPort === undefined ? {} : { viewerPort }) };
+};

package/dist/compiler/training/container/process.d.ts

@@ -0,0 +1,14 @@
+export interface TrainingDockerProcess {
+    (args: readonly string[], options: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+        stdout?: (line: string) => void;
+        stderr?: (line: string) => void;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** Docker client only; no model executable runs on the host. */
+export declare const runTrainingDocker: TrainingDockerProcess;

package/dist/compiler/training/container/process.js

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+/** Docker client only; no model executable runs on the host. */
+export const runTrainingDocker = (args, options) => new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+        reject(Error("Training Docker operation cancelled"));
+        return;
+    }
+    const child = spawn("docker", [...args], { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "", stderr = "", failure;
+    let forceClose;
+    let settled = false;
+    const pending = { stdout: "", stderr: "" };
+    const stop = (message) => {
+        failure ??= Error(message);
+        child.kill("SIGKILL");
+        forceClose ??= setTimeout(() => {
+            // Releasing a stuck client lets the owner independently stop/verify the container.
+            child.stdout.destroy();
+            child.stderr.destroy();
+            finish(null);
+        }, 1000);
+    };
+    const abort = () => stop("Training Docker operation cancelled");
+    const timer = setTimeout(() => stop("Training Docker operation exceeded deadline"), options.timeoutMs);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    const consume = (channel, chunk) => {
+        pending[channel] += chunk;
+        if (Buffer.byteLength(pending[channel]) > 1024 * 1024) {
+            stop("Docker output exceeded bounded line size");
+            return;
+        }
+        const lines = pending[channel].split("\n");
+        pending[channel] = lines.pop();
+        for (const line of lines) {
+            options[channel]?.(line);
+            if (channel === "stdout")
+                stdout = options.stdout ? line : stdout + line + "\n";
+            else
+                stderr = options.stderr ? line : stderr + line + "\n";
+            if (stdout.length + stderr.length > 2 * 1024 * 1024)
+                stop("Docker output exceeded bounded capture size");
+        }
+    };
+    child.stdout.setEncoding("utf8").on("data", (chunk) => consume("stdout", chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => consume("stderr", chunk));
+    child.once("error", (error) => { failure = error; });
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(forceClose);
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abort);
+        for (const channel of ["stdout", "stderr"])
+            if (pending[channel]) {
+                options[channel]?.(pending[channel]);
+                if (channel === "stdout")
+                    stdout = options.stdout ? pending[channel] : stdout + pending[channel];
+                else
+                    stderr = options.stderr ? pending[channel] : stderr + pending[channel];
+            }
+        if (failure)
+            reject(failure);
+        else
+            resolve({ code: code ?? 1, stdout, stderr });
+    };
+    child.once("close", finish);
+});