spawnfile 0.1.14 → 0.1.17

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);
+});

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

@@ -0,0 +1,36 @@
+export declare const TRAINING_BROKER_ENTRYPOINT = "/opt/training/bin/train-broker";
+/**
+ * Writable state of a broker-capable training container, all on tmpfs.
+ *
+ * The image root stays read-only and nothing here is a host bind, so a trial's
+ * worker home, workspace, turn store, wake-acceptance store and ledgers are
+ * on a filesystem that enforces unix ownership — which is what lets the slot
+ * supervisor's worker-uid canaries mean anything (P0 §5: a host bind under
+ * Docker Desktop or Colima silently ignores `chown`). The Grok realm is the
+ * one durable mount, and it is a named volume, not a bind.
+ */
+export declare const trainingBrokerTmpfsTargets: () => readonly {
+    path: string;
+    size: string;
+    mode: string;
+}[];
+/**
+ * `docker create` arguments for the broker-capable training container.
+ *
+ * It starts as root with the *production* Daimon capability set rather than
+ * the v1 path's `--cap-drop ALL` as the host user: the root entrypoint has to
+ * provision uid-owned directories (`CAP_CHOWN`), let the native launcher
+ * `setuid` to a worker (`CAP_SETUID`/`SETGID`), drop bounding sets
+ * (`CAP_SETPCAP`), supervise dropped children (`CAP_KILL`) and read the
+ * attested layout it does not own (`CAP_DAC_READ_SEARCH`). `CAP_FOWNER` is
+ * deliberately absent, which is why every provisioning chmod reclaims the
+ * inode first. Grok 1.0.34 runs every sandbox profile inside bubblewrap, so
+ * the container also needs the pinned default-plus-userns seccomp profile and
+ * AppArmor unconfined — the narrowest combination P0 found.
+ */
+export declare const trainingBrokerSecurityArgs: (seccompProfileDirectory: string) => Promise<string[]>;
+export declare const trainingBrokerMounts: (broker: {
+    realmVolume: string;
+    bootstrap: string;
+    declaration: string;
+}) => string[];

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

@@ -0,0 +1,58 @@
+import { DAIMON_DOCKER_RUNTIME_SECURITY_ARGS, materializeDaimonGrokSeccompProfile } from "../../../shared/index.js";
+import { DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../../../runtime/daimon/contractManifest.js";
+import { DAIMON_WAKE_FUSE_DIRECTORY } from "../../../runtime/daimon/config.js";
+import { TRAINING_BROKER_TMPDIR, TRAINING_GRANT_HOME_ROOT, TRAINING_INFERENCE_DIRECTORY, TRAINING_PAIDEIA_ROOT, TRAINING_SLOT_ROOT, TRAINING_SUPERVISOR_DIRECTORY, TRAINING_WORKER_ROOT } from "../broker/paths.js";
+export const TRAINING_BROKER_ENTRYPOINT = "/opt/training/bin/train-broker";
+/**
+ * Writable state of a broker-capable training container, all on tmpfs.
+ *
+ * The image root stays read-only and nothing here is a host bind, so a trial's
+ * worker home, workspace, turn store, wake-acceptance store and ledgers are
+ * on a filesystem that enforces unix ownership — which is what lets the slot
+ * supervisor's worker-uid canaries mean anything (P0 §5: a host bind under
+ * Docker Desktop or Colima silently ignores `chown`). The Grok realm is the
+ * one durable mount, and it is a named volume, not a bind.
+ */
+export const trainingBrokerTmpfsTargets = () => [
+    { path: "/tmp", size: "1g", mode: "1777" },
+    { path: "/var/tmp", size: "256m", mode: "1777" },
+    { path: "/work", size: "4g", mode: "0755" },
+    { path: "/home/training", size: "1g", mode: "0755" },
+    { path: TRAINING_PAIDEIA_ROOT, size: "64m", mode: "0755" },
+    { path: TRAINING_SLOT_ROOT, size: "4g", mode: "0755" },
+    { path: TRAINING_GRANT_HOME_ROOT, size: "64m", mode: "0755" },
+    { path: TRAINING_INFERENCE_DIRECTORY, size: "64m", mode: "0755" },
+    { path: TRAINING_SUPERVISOR_DIRECTORY, size: "16m", mode: "0755" },
+    { path: TRAINING_WORKER_ROOT, size: "1g", mode: "0755" },
+    { path: "/etc/daimon-engine-broker", size: "16m", mode: "0755" },
+    { path: "/run/daimon-engine-broker", size: "64m", mode: "0755" },
+    { path: TRAINING_BROKER_TMPDIR, size: "64m", mode: "0755" },
+    { path: DAIMON_GROK_TURN_USAGE_LEDGER.directoryPath, size: "64m", mode: "0755" },
+    { path: DAIMON_WAKE_FUSE_DIRECTORY, size: "16m", mode: "0755" }
+];
+/**
+ * `docker create` arguments for the broker-capable training container.
+ *
+ * It starts as root with the *production* Daimon capability set rather than
+ * the v1 path's `--cap-drop ALL` as the host user: the root entrypoint has to
+ * provision uid-owned directories (`CAP_CHOWN`), let the native launcher
+ * `setuid` to a worker (`CAP_SETUID`/`SETGID`), drop bounding sets
+ * (`CAP_SETPCAP`), supervise dropped children (`CAP_KILL`) and read the
+ * attested layout it does not own (`CAP_DAC_READ_SEARCH`). `CAP_FOWNER` is
+ * deliberately absent, which is why every provisioning chmod reclaims the
+ * inode first. Grok 1.0.34 runs every sandbox profile inside bubblewrap, so
+ * the container also needs the pinned default-plus-userns seccomp profile and
+ * AppArmor unconfined — the narrowest combination P0 found.
+ */
+export const trainingBrokerSecurityArgs = async (seccompProfileDirectory) => [
+    "--user", "0:0",
+    ...DAIMON_DOCKER_RUNTIME_SECURITY_ARGS,
+    `--security-opt=seccomp=${await materializeDaimonGrokSeccompProfile(seccompProfileDirectory)}`,
+    "--security-opt=apparmor=unconfined"
+];
+export const trainingBrokerMounts = (broker) => [
+    `type=volume,src=${broker.realmVolume},dst=${DAIMON_GROK_ENGINE_BROKER.credentialHomePath}`,
+    `type=bind,src=${broker.bootstrap},dst=/var/lib/spawnfile/daimon/grok-bootstrap-auth,readonly`,
+    `type=bind,src=${broker.declaration},dst=${TRAINING_PAIDEIA_ROOT}/training-broker.json,readonly`
+];

package/dist/compiler/training/context.d.ts

@@ -0,0 +1,7 @@
+import { type TrainingContext } from "./contract.js";
+export interface CreateTrainingContextOptions {
+    agent?: string;
+    packageVersion: string;
+}
+/** Resolves the complete project, preserving inherited selection and source provenance. */
+export declare const createTrainingContext: (inputPath: string, options: CreateTrainingContextOptions) => Promise<TrainingContext>;