spawnfile 0.1.14 → 0.1.17

package/dist/compiler/runProjectDockerDaimonGuards.js

@@ -0,0 +1,122 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const parseDockerContextHost = (stdout) => {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed === "string" ? parsed : null;
+    }
+    catch {
+        return trimmed;
+    }
+};
+const resolveDockerContextHost = async (invocation, context) => {
+    const { stdout } = await execFile(invocation.command, [
+        "context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"
+    ], { cwd: invocation.cwd, timeout: 10_000 });
+    return parseDockerContextHost(stdout);
+};
+const resolveActiveDockerContext = async (invocation) => {
+    const { stdout } = await execFile(invocation.command, ["context", "show"], {
+        cwd: invocation.cwd,
+        timeout: 10_000
+    });
+    const context = stdout.trim();
+    if (!context || /\s/u.test(context)) {
+        throw new SpawnfileError("validation_error", "Unable to attest the active Docker context for opaque Daimon credentials");
+    }
+    return context;
+};
+const resolveDockerDaemonEndpoint = async (invocation) => {
+    if (invocation.dockerContext)
+        return resolveDockerContextHost(invocation, invocation.dockerContext);
+    if (invocation.dockerHost)
+        return invocation.dockerHost;
+    const ambientContext = process.env.DOCKER_CONTEXT?.trim();
+    if (ambientContext)
+        return resolveDockerContextHost(invocation, ambientContext);
+    const ambientHost = process.env.DOCKER_HOST?.trim();
+    if (ambientHost)
+        return ambientHost;
+    return resolveDockerContextHost(invocation, await resolveActiveDockerContext(invocation));
+};
+const isLocalDockerEndpoint = (host) => {
+    if (host.startsWith("/"))
+        return true;
+    if (host.startsWith("unix://")) {
+        try {
+            const endpoint = new URL(host);
+            return endpoint.host === "" && endpoint.pathname.startsWith("/");
+        }
+        catch {
+            return false;
+        }
+    }
+    return host.startsWith("npipe:////./pipe/") || host.startsWith("npipe://./pipe/");
+};
+const explicitLocalEndpoint = (endpoint) => endpoint.startsWith("/") ? `unix://${endpoint}` : endpoint;
+const withPinnedDockerEndpoint = (invocation, endpoint) => {
+    const run = invocation.args.indexOf("run");
+    if (run < 0) {
+        throw new SpawnfileError("validation_error", "Unable to pin Docker daemon endpoint for opaque Daimon credentials");
+    }
+    return {
+        ...invocation,
+        args: ["--host", endpoint, ...invocation.args.slice(run)],
+        dockerContext: null,
+        dockerHost: endpoint
+    };
+};
+/**
+ * Resolves a possibly mutable Docker context once, validates that endpoint,
+ * then makes every remaining Docker operation use the immutable endpoint.
+ */
+export const pinOpaqueDaimonDockerEndpoint = async (invocation) => {
+    if (!invocation.opaqueDaimonCredentials)
+        return invocation;
+    let resolved;
+    try {
+        resolved = await resolveDockerDaemonEndpoint(invocation);
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        throw new SpawnfileError("validation_error", "Unable to attest the Docker daemon locality for opaque Daimon credentials");
+    }
+    if (!resolved || !isLocalDockerEndpoint(resolved)) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a local Docker daemon; remote and SSH daemons are unsupported");
+    }
+    return withPinnedDockerEndpoint(invocation, explicitLocalEndpoint(resolved));
+};
+export const assertOpaqueDaimonCredentialsUseLocalDaemon = async (invocation) => {
+    await pinOpaqueDaimonDockerEndpoint(invocation);
+};
+export const assertOpaqueDaimonCredentialsHaveNoUserNamespace = async (invocation) => {
+    if (!invocation.opaqueDaimonCredentials)
+        return;
+    if (invocation.dockerContext || !invocation.dockerHost) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a pinned Docker daemon endpoint before Docker info");
+    }
+    const args = [
+        "--host", invocation.dockerHost,
+        "info", "--format", "{{json .SecurityOptions}}"
+    ];
+    let securityOptions;
+    try {
+        const { stdout } = await execFile(invocation.command, args, {
+            cwd: invocation.cwd,
+            timeout: 10_000
+        });
+        securityOptions = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw new SpawnfileError("validation_error", "Unable to verify that the Docker daemon has no user namespace remapping for opaque Daimon credentials");
+    }
+    if (!Array.isArray(securityOptions) || securityOptions.some((value) => typeof value !== "string" || /userns|rootless/iu.test(value))) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a Docker daemon without user namespace remapping");
+    }
+};

package/dist/compiler/runProjectDockerReservation.d.ts

@@ -0,0 +1,3 @@
+import type { DockerRunInvocation, DockerRunResult } from "./runProjectDocker.js";
+/** Holds daemon-side atomic volume reservations through verified startup. */
+export declare const withExclusiveVolumeReservations: (invocation: DockerRunInvocation, operation: () => Promise<DockerRunResult | void>) => Promise<DockerRunResult | void>;

package/dist/compiler/runProjectDockerReservation.js

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const dockerId = /^[a-f0-9]{64}$/u;
+const versionLabel = "com.spawnfile.exclusive-volume-reservation";
+const ownerLabel = "com.spawnfile.exclusive-volume-owner";
+const volumeLabel = "com.spawnfile.exclusive-volume-digest";
+const endpointArgs = (invocation) => invocation.dockerContext
+    ? ["--context", invocation.dockerContext]
+    : invocation.dockerHost ? ["--host", invocation.dockerHost] : [];
+const execute = async (invocation, args) => {
+    const { stdout } = await execFile(invocation.command, [...endpointArgs(invocation), ...args], {
+        cwd: invocation.cwd,
+        timeout: 10_000
+    });
+    return stdout;
+};
+const reservationName = (digest) => `spawnfile-volume-reservation-${digest.slice("sha256:".length, "sha256:".length + 24)}`;
+const verifyReservation = async (invocation, reservation) => {
+    try {
+        const [idRaw, labelsRaw, ...extra] = (await execute(invocation, [
+            "container", "inspect", "--format", "{{json .Id}}\n{{json .Config.Labels}}", reservation.id
+        ])).trim().split("\n");
+        if (!idRaw || !labelsRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const labels = JSON.parse(labelsRaw);
+        if (id !== reservation.id || !labels || typeof labels !== "object" || Array.isArray(labels))
+            throw new Error("identity");
+        const values = labels;
+        if (values[versionLabel] !== "v1" || values[ownerLabel] !== reservation.owner
+            || values[volumeLabel] !== reservation.volumeDigest)
+            throw new Error("authority");
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation identity is unavailable");
+    }
+};
+const release = async (invocation, reservations) => {
+    let failed = false;
+    for (const reservation of [...reservations].reverse()) {
+        try {
+            await verifyReservation(invocation, reservation);
+            await execute(invocation, ["container", "rm", reservation.id]);
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed)
+        throw new SpawnfileError("runtime_error", "Unable to release exclusive persistent mount reservation");
+};
+const assertAvailable = async (invocation) => {
+    for (const volume of invocation.exclusiveReattachVolumes ?? []) {
+        let stdout;
+        try {
+            stdout = await execute(invocation, [
+                "ps", "--filter", `volume=${volume}`, "--format", "{{.Names}}"
+            ]);
+        }
+        catch {
+            throw new SpawnfileError("runtime_error", "Unable to verify exclusive persistent mount occupancy");
+        }
+        const occupants = stdout.split("\n").map((name) => name.trim()).filter(Boolean);
+        if (occupants.some((name) => name !== invocation.containerName)) {
+            throw new SpawnfileError("runtime_error", "Exclusive persistent mount is attached to another running deployment; stop it before reattaching this lineage");
+        }
+    }
+};
+const acquire = async (invocation) => {
+    const reservations = [];
+    const volumes = [...new Set(invocation.exclusiveReattachVolumes ?? [])].sort();
+    try {
+        for (const volume of volumes) {
+            const volumeDigest = `sha256:${createHash("sha256").update(volume).digest("hex")}`;
+            const owner = randomUUID();
+            let id;
+            try {
+                id = (await execute(invocation, [
+                    "container", "create", "--name", reservationName(volumeDigest),
+                    "--label", `${versionLabel}=v1`,
+                    "--label", `${ownerLabel}=${owner}`,
+                    "--label", `${volumeLabel}=${volumeDigest}`,
+                    invocation.imageTag
+                ])).trim();
+            }
+            catch {
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation is already held");
+            }
+            if (!dockerId.test(id))
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation returned invalid identity");
+            const reservation = { id, owner, volumeDigest };
+            reservations.push(reservation);
+            await verifyReservation(invocation, reservation);
+        }
+        await assertAvailable(invocation);
+        return reservations;
+    }
+    catch (error) {
+        if (reservations.length > 0)
+            await release(invocation, reservations);
+        throw error;
+    }
+};
+/** Holds daemon-side atomic volume reservations through verified startup. */
+export const withExclusiveVolumeReservations = async (invocation, operation) => {
+    if ((invocation.exclusiveReattachVolumes?.length ?? 0) === 0)
+        return operation();
+    const reservations = await acquire(invocation);
+    try {
+        return await operation();
+    }
+    finally {
+        await release(invocation, reservations);
+    }
+};

package/dist/compiler/runProjectLifecycle.js

@@ -12,9 +12,9 @@ export const executeDockerRunWithSupportCleanup = async (invocation, runner) =>
             ? {
                 ...invocation,
                 onDetachedStarted: async (result) => {
+                    await invocation.onDetachedStarted?.(result);
                     started = true;
                     await rm(invocation.envFilePath, { force: true });
-                    await invocation.onDetachedStarted?.(result);
                 }
             }
             : invocation;

package/dist/compiler/training/broker/declaration.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * `spawnfile.training-broker.v1`: the only thing the host tells the
+ * broker-capable training container about its slot. It is data, never code —
+ * the image's own Spawnfile distribution renders the provisioning from it with
+ * the same renderers production uses, so no host-written executable is ever
+ * mounted (`../container/AGENTS.md`).
+ *
+ * It carries no credentials: the training Grok login reaches the container only
+ * as the read-only bootstrap leaf bind, and the rotating credential lives on
+ * the named realm volume.
+ */
+export declare const trainingBrokerDeclarationSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.training-broker.v1">;
+    engine: z.ZodLiteral<"grok">;
+    agentId: z.ZodString;
+    model: z.ZodEnum<{
+        "grok-4.6": "grok-4.6";
+        "grok-4.5": "grok-4.5";
+        "grok-build": "grok-build";
+    }>;
+    reasoningEffort: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    architecture: z.ZodEnum<{
+        arm64: "arm64";
+        x64: "x64";
+    }>;
+    limits: z.ZodObject<{
+        maxRequests: z.ZodNumber;
+        maxTokens: z.ZodNumber;
+        timeoutMs: z.ZodNumber;
+    }, z.core.$strict>;
+    bootstrap: z.ZodString;
+    organizationUid: z.ZodLiteral<2000>;
+    seccompProfileSha256: z.ZodString;
+    unenforcedBindPolicy: z.ZodDefault<z.ZodEnum<{
+        refuse: "refuse";
+        "profile-only": "profile-only";
+    }>>;
+}, z.core.$strict>;
+export type TrainingBrokerDeclaration = z.infer<typeof trainingBrokerDeclarationSchema>;
+export declare const parseTrainingBrokerDeclaration: (value: unknown) => TrainingBrokerDeclaration;

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

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { z } from "zod";
+import { DAIMON_GROK_BROKER_MODELS, DAIMON_GROK_BROKER_REASONING_EFFORTS, DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+const canonical = z.string().min(2).max(4_096).refine((value) => path.posix.isAbsolute(value) && path.posix.normalize(value) === value && !value.endsWith("/") && !value.includes("\0"), "canonical absolute path");
+/**
+ * `spawnfile.training-broker.v1`: the only thing the host tells the
+ * broker-capable training container about its slot. It is data, never code —
+ * the image's own Spawnfile distribution renders the provisioning from it with
+ * the same renderers production uses, so no host-written executable is ever
+ * mounted (`../container/AGENTS.md`).
+ *
+ * It carries no credentials: the training Grok login reaches the container only
+ * as the read-only bootstrap leaf bind, and the rotating credential lives on
+ * the named realm volume.
+ */
+export const trainingBrokerDeclarationSchema = z.strictObject({
+    version: z.literal("spawnfile.training-broker.v1"),
+    engine: z.literal("grok"),
+    agentId: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u),
+    model: z.enum(DAIMON_GROK_BROKER_MODELS),
+    reasoningEffort: z.enum(DAIMON_GROK_BROKER_REASONING_EFFORTS),
+    architecture: z.enum(["arm64", "x64"]),
+    limits: z.strictObject({
+        maxRequests: z.number().int().min(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.maxRequests[0]).max(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.maxRequests[1]),
+        maxTokens: z.number().int().min(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.maxTokens[0]).max(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.maxTokens[1]),
+        timeoutMs: z.number().int().min(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.timeoutMs[0]).max(DAIMON_GROK_ENGINE_BROKER.turnLimits.bounds.timeoutMs[1])
+    }),
+    /** The read-only bootstrap credential leaf, already refused if it is the desktop `~/.grok/auth.json`. */
+    bootstrap: canonical,
+    /** The uid the trained evaluator (Paideia, DSPy, judges) runs as; the only uid the slot supervisor serves. */
+    organizationUid: z.literal(DAIMON_GROK_ENGINE_BROKER.identities.organizationUid),
+    seccompProfileSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    /**
+     * What the slot supervisor does with a deny path whose backing filesystem
+     * does not enforce unix ownership — virtiofs and grpcfuse under Docker
+     * Desktop and Colima, where `chown` is silently ignored and uid 2200 reads a
+     * root `0600` file (P0 §5). The backing filesystem decides, not the fact of
+     * being a host bind: the same bind over ext4 or overlay on a Linux daemon is
+     * probed for real, which is what makes `refuse` a default a run can meet.
+     *
+     * `refuse` (the default) fails the slot and writes no receipt: a worker-uid
+     * probe over such a path carries no information, so the supervisor will not
+     * certify it. `profile-only` is the operator's explicit acceptance that for
+     * those paths the boundary is the bubblewrap-enforced `deny` list alone —
+     * verified to block both shell `cat` and `read_file` on 1.0.34 (P0 §4), but
+     * *not* a boundary a worker-uid namespace cannot lift — and the supervisor
+     * records every path that used that weaker evidence in its log.
+     *
+     * It does not reach `TRAINING_SEALED_DENY_PATHS`. The sealed train and test
+     * datasets are held by DAC on their ancestor under both values, and a slot
+     * that cannot prove that denial is refused whatever this says.
+     */
+    unenforcedBindPolicy: z.enum(["refuse", "profile-only"]).default("refuse")
+}).strict();
+export const parseTrainingBrokerDeclaration = (value) => trainingBrokerDeclarationSchema.parse(value);

package/dist/compiler/training/broker/entrypoint.d.ts

@@ -0,0 +1,39 @@
+import { type DaimonProjectionModule } from "./projection.js";
+export declare const TRAINING_GROK_BROKER_CONTROL_SOCKET_ENV = "PAIDEIA_GROK_BROKER_CONTROL_SOCKET";
+export declare const TRAINING_GROK_GRANT_HOME_ROOT_ENV = "PAIDEIA_GROK_GRANT_HOME_ROOT";
+export declare const TRAINING_ENTRYPOINT_COMMAND = "/opt/training/bin/train";
+/**
+ * The desktop Grok login, in every spelling a caller might reach it by.
+ *
+ * D2 is explicit: training uses one dedicated Grok login and never the
+ * developer's own. An in-container refresh rotates the credential, so mounting
+ * the desktop leaf would invalidate the developer's desktop session as a side
+ * effect of a training run — and the refreshed token would live on tmpfs, so
+ * the desktop login would be gone rather than moved.
+ */
+export declare const desktopGrokAuthPaths: (home?: string) => string[];
+export declare const assertNotDesktopGrokAuth: (source: string, home?: string) => string;
+export interface TrainingEntrypointOptions {
+    argv: readonly string[];
+    declarationPath?: string;
+    loadDaimon?: () => Promise<DaimonProjectionModule>;
+    log?: (line: string) => void;
+}
+/**
+ * The broker-capable training container's root entrypoint.
+ *
+ * Order matters and is the whole privilege model: provision as root with the
+ * production capability set, start the launcher (root) and the broker and
+ * relay (2100) and prove each one's post-drop identity, publish the slot
+ * supervisor socket, and only then drop to uid 2000 with an empty capability
+ * bounding set to run `train`. Paideia, DSPy and the judges are that uid; the
+ * model's own tools are the worker uid the launcher alone can reach.
+ */
+export declare const runTrainingBrokerEntrypoint: (options: TrainingEntrypointOptions) => Promise<number>;
+/**
+ * `train` as uid 2000 with an empty bounding set, proven inside the child
+ * before it execs: `setpriv --bounding-set=-all` silently does nothing without
+ * `CAP_SETPCAP`, so the guard has to read `/proc/self/status` rather than
+ * trust the flag.
+ */
+export declare const trainingChildArgv: (argv: readonly string[], uid?: number) => string[];

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

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SpawnfileError } from "../../../shared/index.js";
+import { DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { parseTrainingBrokerDeclaration } from "./declaration.js";
+import { loadDaimonProjectionModule, resolveTrainingGrokProjection } from "./projection.js";
+import { resolveTrainingGrokRegistration } from "./registration.js";
+import { createTrainingSlotRuntime } from "./runtime.js";
+import { createTrainingSlotSupervisor, serveTrainingSlotSupervisor, startTrainingSlot } from "./supervisor.js";
+import { DAIMON_ORGANIZATION_UID, TRAINING_BOOTSTRAP_MOUNT, TRAINING_BROKER_DECLARATION_FILE, TRAINING_GRANT_HOME_ROOT, TRAINING_SUPERVISOR_SOCKET } from "./paths.js";
+export const TRAINING_GROK_BROKER_CONTROL_SOCKET_ENV = "PAIDEIA_GROK_BROKER_CONTROL_SOCKET";
+export const TRAINING_GROK_GRANT_HOME_ROOT_ENV = "PAIDEIA_GROK_GRANT_HOME_ROOT";
+export const TRAINING_ENTRYPOINT_COMMAND = "/opt/training/bin/train";
+/**
+ * The desktop Grok login, in every spelling a caller might reach it by.
+ *
+ * D2 is explicit: training uses one dedicated Grok login and never the
+ * developer's own. An in-container refresh rotates the credential, so mounting
+ * the desktop leaf would invalidate the developer's desktop session as a side
+ * effect of a training run — and the refreshed token would live on tmpfs, so
+ * the desktop login would be gone rather than moved.
+ */
+export const desktopGrokAuthPaths = (home = os.homedir()) => [path.resolve(home, ".grok/auth.json"), path.resolve(home, ".grok", "auth.json")];
+export const assertNotDesktopGrokAuth = (source, home = os.homedir()) => {
+    if (desktopGrokAuthPaths(home).includes(path.resolve(source))) {
+        throw new SpawnfileError("validation_error", "Training refuses the desktop ~/.grok/auth.json as its Grok bootstrap; import a dedicated login with `spawnfile auth import grok --profile paideia-training --from <dir>`");
+    }
+    return source;
+};
+/** The bootstrap leaf inside the container: the fixed read-only mount, a bounded regular file, never a symlink. */
+const assertBootstrap = async (declaration) => {
+    if (declaration.bootstrap !== TRAINING_BOOTSTRAP_MOUNT) {
+        throw new SpawnfileError("validation_error", `The training Grok bootstrap must be mounted at ${TRAINING_BOOTSTRAP_MOUNT}`);
+    }
+    const info = await lstat(declaration.bootstrap);
+    if (!info.isFile() || info.isSymbolicLink() || info.size < 2 || info.size > DAIMON_GROK_SUBSCRIPTION_MAX_BYTES) {
+        throw new SpawnfileError("validation_error", "The training Grok bootstrap must be a bounded regular credential leaf");
+    }
+};
+const DAIMON_GROK_SUBSCRIPTION_MAX_BYTES = 64 * 1024;
+/**
+ * The broker-capable training container's root entrypoint.
+ *
+ * Order matters and is the whole privilege model: provision as root with the
+ * production capability set, start the launcher (root) and the broker and
+ * relay (2100) and prove each one's post-drop identity, publish the slot
+ * supervisor socket, and only then drop to uid 2000 with an empty capability
+ * bounding set to run `train`. Paideia, DSPy and the judges are that uid; the
+ * model's own tools are the worker uid the launcher alone can reach.
+ */
+export const runTrainingBrokerEntrypoint = async (options) => {
+    const log = options.log ?? ((line) => process.stderr.write(`[training-entrypoint] ${line}\n`));
+    if (process.getuid?.() !== 0)
+        throw new SpawnfileError("runtime_error", "The broker-capable training container must start as root");
+    const declaration = parseTrainingBrokerDeclaration(JSON.parse(await readFile(options.declarationPath ?? TRAINING_BROKER_DECLARATION_FILE, "utf8")));
+    await assertBootstrap(declaration);
+    const registration = resolveTrainingGrokRegistration(declaration);
+    const daimon = await (options.loadDaimon ?? loadDaimonProjectionModule)();
+    // Daimon's projection is I/O-free, so the digest the receipt will bind is known before anything is provisioned.
+    const { projectionSha256 } = await resolveTrainingGrokProjection(declaration, registration, daimon);
+    const runtime = createTrainingSlotRuntime({ declaration, registration, projectionSha256 });
+    // Provision, start, canary and publish the slot preflight receipt before `train` exists at all: the
+    // first trial must not be the one trial that runs on no worker-uid denial evidence, and a refusal
+    // here costs nothing while the same refusal after the first wake costs that trial's spend.
+    const preflight = await startTrainingSlot(runtime, randomBytes(32).toString("hex"));
+    const supervisor = createTrainingSlotSupervisor({ runtime, organizationUid: declaration.organizationUid });
+    const server = serveTrainingSlotSupervisor(supervisor, TRAINING_SUPERVISOR_SOCKET, log, declaration.organizationUid);
+    log(`slot ${registration.slot} provisioned for ${registration.agentId} (${registration.model}/${registration.reasoningEffort}), projection ${projectionSha256}, `
+        + `generation ${preflight.generation} with ${preflight.canaries} denied canaries at ${preflight.receipt}`);
+    const status = await runTrainingChild(options.argv, declaration, log);
+    server.close();
+    await runtime.stop();
+    return status;
+};
+/**
+ * `train` as uid 2000 with an empty bounding set, proven inside the child
+ * before it execs: `setpriv --bounding-set=-all` silently does nothing without
+ * `CAP_SETPCAP`, so the guard has to read `/proc/self/status` rather than
+ * trust the flag.
+ */
+export const trainingChildArgv = (argv, uid = DAIMON_ORGANIZATION_UID) => [
+    "setpriv", "--clear-groups", `--reuid=${uid}`, `--regid=${uid}`, "--inh-caps=-all", "--ambient-caps=-all", "--bounding-set=-all",
+    "--", "/bin/bash", "-ceu",
+    'if [ "$EUID" -eq 0 ]; then echo "training must not run as root" >&2; exit 1; fi\n'
+        + 'test "$(sed -n "s/^CapBnd:[[:space:]]*//p" /proc/self/status)" = 0000000000000000\n'
+        + 'test "$(sed -n "s/^CapEff:[[:space:]]*//p" /proc/self/status)" = 0000000000000000\n'
+        + 'exec "$@"',
+    "bash", TRAINING_ENTRYPOINT_COMMAND, ...argv
+];
+const runTrainingChild = (argv, declaration, log) => new Promise((resolve) => {
+    const command = trainingChildArgv(argv, declaration.organizationUid);
+    const child = spawn(command[0], command.slice(1), {
+        stdio: ["ignore", "inherit", "inherit"],
+        env: {
+            ...process.env,
+            [TRAINING_GROK_BROKER_CONTROL_SOCKET_ENV]: DAIMON_GROK_ENGINE_BROKER.controlSocketPath,
+            [TRAINING_GROK_GRANT_HOME_ROOT_ENV]: TRAINING_GRANT_HOME_ROOT,
+            HOME: "/home/training"
+        }
+    });
+    const forward = (signal) => () => child.kill(signal);
+    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
+        process.on(signal, forward(signal));
+    child.once("exit", (code, signal) => {
+        log(`training exited code=${code ?? "null"} signal=${signal ?? "none"}`);
+        resolve(signal ? (signal === "SIGINT" ? 130 : 143) : code ?? 1);
+    });
+});

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

@@ -0,0 +1,10 @@
+export { parseTrainingBrokerDeclaration, trainingBrokerDeclarationSchema, type TrainingBrokerDeclaration } from "./declaration.js";
+export { assertNotDesktopGrokAuth, desktopGrokAuthPaths, runTrainingBrokerEntrypoint, trainingChildArgv, TRAINING_GROK_BROKER_CONTROL_SOCKET_ENV, TRAINING_GROK_GRANT_HOME_ROOT_ENV } from "./entrypoint.js";
+export { brokerProcessPlan, startBrokerProcesses, stopBrokerProcesses } from "./processes.js";
+export { loadDaimonProjectionModule, resolveTrainingGrokProjection, trainingOrganizationRuntimeConfig } from "./projection.js";
+export { renderTrainingBrokerProvisioning, renderTrainingIdentities, trainingSlotDirectories } from "./provisioning.js";
+export { buildTrainingSlotReceipt, readGrokExecutableSha256, resolveBackingFilesystem, resolveTrainingCanaries } from "./receipt.js";
+export { resolveTrainingGrokDenyPaths, resolveTrainingGrokRegistration } from "./registration.js";
+export { createTrainingSlotRuntime } from "./runtime.js";
+export { assertTrainingSupervisorSocketIdentity, createTrainingSlotSupervisor, serveTrainingSlotSupervisor, TRAINING_SUPERVISOR_PROTOCOL, type TrainingSlotRuntime } from "./supervisor.js";
+export * from "./paths.js";

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

@@ -0,0 +1,10 @@
+export { parseTrainingBrokerDeclaration, trainingBrokerDeclarationSchema } from "./declaration.js";
+export { assertNotDesktopGrokAuth, desktopGrokAuthPaths, runTrainingBrokerEntrypoint, trainingChildArgv, TRAINING_GROK_BROKER_CONTROL_SOCKET_ENV, TRAINING_GROK_GRANT_HOME_ROOT_ENV } from "./entrypoint.js";
+export { brokerProcessPlan, startBrokerProcesses, stopBrokerProcesses } from "./processes.js";
+export { loadDaimonProjectionModule, resolveTrainingGrokProjection, trainingOrganizationRuntimeConfig } from "./projection.js";
+export { renderTrainingBrokerProvisioning, renderTrainingIdentities, trainingSlotDirectories } from "./provisioning.js";
+export { buildTrainingSlotReceipt, readGrokExecutableSha256, resolveBackingFilesystem, resolveTrainingCanaries } from "./receipt.js";
+export { resolveTrainingGrokDenyPaths, resolveTrainingGrokRegistration } from "./registration.js";
+export { createTrainingSlotRuntime } from "./runtime.js";
+export { assertTrainingSupervisorSocketIdentity, createTrainingSlotSupervisor, serveTrainingSlotSupervisor, TRAINING_SUPERVISOR_PROTOCOL } from "./supervisor.js";
+export * from "./paths.js";

package/dist/compiler/training/broker/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runTrainingBrokerEntrypoint } from "./entrypoint.js";
+/**
+ * The broker-capable training image's root entrypoint process. The image ships
+ * it; the host supplies only the read-only `spawnfile.training-broker.v1`
+ * declaration and never a script, so no host executable enters the container.
+ */
+const main = async () => {
+    process.exitCode = await runTrainingBrokerEntrypoint({ argv: process.argv.slice(2) });
+};
+main().catch((error) => {
+    process.stderr.write(`[training-entrypoint] ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});