spawnfile 0.1.14 → 0.1.18

package/dist/compiler/runProjectDocker.js

@@ -2,6 +2,8 @@ import { execFile as execFileCallback, spawn } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
 import { SpawnfileError } from "../shared/index.js";
+import { assertOpaqueDaimonCredentialsHaveNoUserNamespace, pinOpaqueDaimonDockerEndpoint } from "./runProjectDockerDaimonGuards.js";
+import { withExclusiveVolumeReservations } from "./runProjectDockerReservation.js";
 const execFile = promisify(execFileCallback);
 const parseDockerContextHost = (stdout) => {
     const trimmed = stdout.trim();
@@ -138,20 +140,22 @@ export const createDetachedContainerInspectArgs = (invocation, containerId) => {
         : invocation.dockerHost
             ? ["--host", invocation.dockerHost, "inspect"]
             : ["inspect"];
-    return [...base, "--format", "{{json .Id}}\n{{json .Image}}\n{{json .Config.Labels}}", containerId];
+    return [...base, "--format", "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}", containerId];
 };
-export const parseDetachedContainerInspect = (stdout, expectedContainerId, expectedLabels) => {
-    const [idRaw, imageRaw, labelsRaw, ...extra] = stdout.trim().split("\n");
-    if (!idRaw || !imageRaw || !labelsRaw || extra.length > 0)
+export const parseDetachedContainerInspect = (stdout, expectedContainerId, expectedLabels, expectedContainerName) => {
+    const [idRaw, nameRaw, imageRaw, labelsRaw, ...extra] = stdout.trim().split("\n");
+    if (!idRaw || !nameRaw || !imageRaw || !labelsRaw || extra.length > 0)
         throw new Error("unexpected inspect response");
     const actualId = JSON.parse(idRaw);
+    const actualName = JSON.parse(nameRaw);
     const imageId = JSON.parse(imageRaw);
     const labels = JSON.parse(labelsRaw);
     if (typeof actualId !== "string" || actualId !== expectedContainerId || !/^[a-f0-9]{64}$/u.test(actualId)
+        || typeof actualName !== "string" || actualName !== `/${expectedContainerName ?? ""}`
         || typeof imageId !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(imageId))
         throw new Error("malformed detached container metadata");
     if (!expectedLabels)
-        return { containerId: actualId, imageId };
+        return { containerId: actualId, containerName: actualName.slice(1), imageId };
     if (!labels || typeof labels !== "object" || Array.isArray(labels))
         throw new Error("missing detached deployment labels");
     const actual = Object.fromEntries(Object.keys(expectedLabels).sort().map((key) => {
@@ -160,15 +164,15 @@ export const parseDetachedContainerInspect = (stdout, expectedContainerId, expec
             throw new Error("detached deployment label drift");
         return [key, value];
     }));
-    return { containerId: actualId, imageId, deploymentLabels: actual };
+    return { containerId: actualId, containerName: actualName.slice(1), imageId, deploymentLabels: actual };
 };
-const inspectDetachedContainer = async (invocation, containerId) => {
+export const inspectDetachedContainer = async (invocation, containerId) => {
     try {
         const { stdout } = await execFile(invocation.command, createDetachedContainerInspectArgs(invocation, containerId), {
             cwd: invocation.cwd,
             timeout: 10_000
         });
-        return parseDetachedContainerInspect(stdout, containerId, invocation.deploymentLabels);
+        return parseDetachedContainerInspect(stdout, containerId, invocation.deploymentLabels, invocation.containerName);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -203,8 +207,11 @@ const runPreparedDockerContainer = (prepared) => new Promise((resolve, reject) =
                 settle(() => resolve(undefined));
                 return;
             }
-            Promise.resolve(prepared.invocation.onDetachedStarted?.({ containerId }))
-                .then(() => inspectDetachedContainer(prepared.invocation, containerId))
+            Promise.resolve(inspectDetachedContainer(prepared.invocation, containerId))
+                .then(async (result) => {
+                await prepared.invocation.onDetachedStarted?.(result);
+                return result;
+            })
                 .then(resolve)
                 .catch(reject);
             return;
@@ -214,12 +221,30 @@ const runPreparedDockerContainer = (prepared) => new Promise((resolve, reject) =
             : `Docker run for ${prepared.invocation.imageTag} failed with exit code ${code ?? "unknown"}`));
     });
 });
-export const runDockerContainer = (invocation) => {
-    if (!invocation.dockerContext || collectBindMountSources(invocation.args).length === 0) {
-        return runPreparedDockerContainer({
-            cleanup: async () => undefined,
-            invocation
-        });
-    }
-    return prepareRemoteBindMounts(invocation).then(runPreparedDockerContainer);
+const runDockerContainerPrepared = async (invocation) => {
+    const run = async () => {
+        if (!invocation.dockerContext || collectBindMountSources(invocation.args).length === 0) {
+            if (invocation.opaqueDaimonCredentials && !invocation.dockerEndpointPinned) {
+                await assertOpaqueDaimonCredentialsHaveNoUserNamespace(invocation);
+                return await runPreparedDockerContainer({
+                    cleanup: async () => undefined,
+                    invocation
+                });
+            }
+            return await runPreparedDockerContainer({
+                cleanup: async () => undefined,
+                invocation
+            });
+        }
+        return await runPreparedDockerContainer(await prepareRemoteBindMounts(invocation));
+    };
+    return withExclusiveVolumeReservations(invocation, run);
 };
+export const runDockerContainer = (invocation) => invocation.opaqueDaimonCredentials
+    ? pinOpaqueDaimonDockerEndpoint(invocation)
+        .then(async (pinned) => {
+        await assertOpaqueDaimonCredentialsHaveNoUserNamespace(pinned);
+        return pinned;
+    })
+        .then((pinned) => runDockerContainerPrepared({ ...pinned, dockerEndpointPinned: true }))
+    : runDockerContainerPrepared(invocation);

package/dist/compiler/runProjectDockerDaimonGuards.d.ts

@@ -0,0 +1,15 @@
+export interface DaimonDockerGuardInvocation {
+    args: string[];
+    command: string;
+    cwd: string;
+    dockerContext?: string | null;
+    dockerHost?: string | null;
+    opaqueDaimonCredentials?: boolean;
+}
+/**
+ * Resolves a possibly mutable Docker context once, validates that endpoint,
+ * then makes every remaining Docker operation use the immutable endpoint.
+ */
+export declare const pinOpaqueDaimonDockerEndpoint: <T extends DaimonDockerGuardInvocation>(invocation: T) => Promise<T>;
+export declare const assertOpaqueDaimonCredentialsUseLocalDaemon: (invocation: DaimonDockerGuardInvocation) => Promise<void>;
+export declare const assertOpaqueDaimonCredentialsHaveNoUserNamespace: (invocation: DaimonDockerGuardInvocation) => Promise<void>;

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/surfaces.d.ts

@@ -1,10 +1,9 @@
-import { DocsBlock, McpServer, Secret, SkillReference } from "../manifest/index.js";
+import { DocsBlock, Secret, SkillReference } from "../manifest/index.js";
 import { StringMap } from "../shared/index.js";
 import { ResolvedDocument, ResolvedPackage, ResolvedSkill } from "./types.js";
 export declare const mergeSkills: (sharedSkills?: SkillReference[], localSkills?: SkillReference[]) => SkillReference[];
 export declare const mergeResolvedSkills: (sharedSkills?: ResolvedSkill[], localSkills?: ResolvedSkill[]) => ResolvedSkill[];
 export declare const mergePackages: (sharedPackages?: ResolvedPackage[], localPackages?: ResolvedPackage[]) => ResolvedPackage[];
-export declare const mergeMcpServers: (sharedServers?: McpServer[], localServers?: McpServer[]) => McpServer[];
 export declare const mergeSecrets: (sharedSecrets?: Secret[], localSecrets?: Secret[]) => Secret[];
 export declare const mergeEnv: (sharedEnv?: StringMap, localEnv?: StringMap) => StringMap;
 export declare const loadResolvedDocuments: (manifestPath: string, docs: DocsBlock | undefined) => Promise<ResolvedDocument[]>;

package/dist/compiler/surfaces.js

@@ -13,7 +13,6 @@ const mergeByKey = (sharedValues, localValues, getKey) => {
 export const mergeSkills = (sharedSkills = [], localSkills = []) => mergeByKey(sharedSkills, localSkills, (skill) => skill.ref);
 export const mergeResolvedSkills = (sharedSkills = [], localSkills = []) => mergeByKey(sharedSkills, localSkills, (skill) => skill.ref);
 export const mergePackages = (sharedPackages = [], localPackages = []) => mergeByKey(sharedPackages, localPackages, (pkg) => `${pkg.manager}::${pkg.name}`);
-export const mergeMcpServers = (sharedServers = [], localServers = []) => mergeByKey(sharedServers, localServers, (server) => server.name);
 export const mergeSecrets = (sharedSecrets = [], localSecrets = []) => mergeByKey(sharedSecrets, localSecrets, (secret) => secret.name);
 export const mergeEnv = (sharedEnv = {}, localEnv = {}) => ({
     ...sharedEnv,

package/dist/compiler/syncProjectAuth.js

@@ -25,7 +25,8 @@ const resolveAuthRequirements = async (inputPath) => {
                 addProjectSecret(secret);
             }
             for (const server of node.value.shared.mcpServers) {
-                if (server.auth?.secret) {
+                // An opt-in server's secret is required only through the members that select it.
+                if (server.auth?.secret && server.opt_in !== true) {
                     addProjectSecret({ name: server.auth.secret, required: true });
                 }
             }

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

@@ -0,0 +1,6 @@
+/** Clock directories are public by contract; prove the sibling mask in the worker's mount namespace. */
+export declare const probeTrainingSiblingClock: (slot: number, target: string, execute?: (command: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+}>) => Promise<boolean>;

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

@@ -0,0 +1,27 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../../../shared/index.js";
+import { trainingSlotPaths } from "./paths.js";
+const run = promisify(execFile);
+const quote = (value) => `'${value.replace(/'/gu, `'"'"'`)}'`;
+/** Clock directories are public by contract; prove the sibling mask in the worker's mount namespace. */
+export const probeTrainingSiblingClock = async (slot, target, execute = run) => {
+    const p = trainingSlotPaths(slot);
+    const script = [
+        'set -eu',
+        `cat ${quote(p.clockFile)} >/dev/null`,
+        // Use the same mode-000 directory bind as Grok's deny mounts. Neither an unavailable
+        // namespace nor a hidden own clock is a successful denial.
+        `blocked=$(mktemp -d ${quote(`${p.privateTmp}/clock-probe.XXXXXX`)})`,
+        'trap \'chmod 700 "$blocked"; rmdir "$blocked"\' EXIT',
+        'chmod 000 "$blocked"',
+        `bwrap --die-with-parent --cap-drop ALL --ro-bind / / --dev /dev --ro-bind "$blocked" ${quote(target)} -- /bin/sh -ceu ${quote(`cat ${quote(p.clockFile)} >/dev/null; if ls -A ${quote(target)} >/dev/null 2>&1; then echo reachable; else echo denied; fi`)}`
+    ].join("\n");
+    const result = await execute("setpriv", ["--clear-groups", `--reuid=${p.workerUid}`, `--regid=${p.workerUid}`,
+        "--inh-caps=-all", "--ambient-caps=-all", "--bounding-set=-all", "--", "/bin/sh", "-ceu", script], { timeout: 10_000 });
+    if (result.stdout.trim() === "denied")
+        return true;
+    if (result.stdout.trim() === "reachable")
+        return false;
+    throw new SpawnfileError("runtime_error", "Training clock canary returned no verified verdict");
+};

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/**
+ * `spawnfile.training-broker.v2`: 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.v2">;
+    maxRunRequests: z.ZodDefault<z.ZodNumber>;
+    slots: z.ZodDefault<z.ZodNumber>;
+    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,57 @@
+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.v2`: 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.v2"),
+    maxRunRequests: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).default(1000),
+    slots: z.number().int().min(1).max(8).default(4),
+    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[];