spawnfile 0.1.14 → 0.1.18

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

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { trainingSlotPaths } from "./paths.js";
+/** Root uses the broker's slot reset seam; the broker owns active-turn, worker-reap and clock checks. */
+export const resetTrainingBrokerSlot = (slot, signal, socketPath = DAIMON_GROK_ENGINE_BROKER.controlSocketPath) => {
+    trainingSlotPaths(slot);
+    signal.throwIfAborted();
+    const requestId = randomUUID();
+    const version = DAIMON_GROK_ENGINE_BROKER.controlProtocolVersion;
+    const payload = Buffer.from(JSON.stringify({ version, kind: "reset_slot", requestId, slot }));
+    const frame = Buffer.alloc(4 + payload.length);
+    frame.writeUInt32BE(payload.length);
+    payload.copy(frame, 4);
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        let buffer = Buffer.alloc(0), settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", abort);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const abort = () => finish(new Error("Training broker reset aborted; slot must be quarantined"));
+        signal.addEventListener("abort", abort, { once: true });
+        socket.once("error", error => finish(error));
+        socket.once("close", () => finish(new Error("Training broker reset refused: slot active, unavailable, or reset failed")));
+        socket.once("connect", () => socket.write(frame));
+        socket.on("data", chunk => {
+            buffer = Buffer.concat([buffer, chunk]);
+            if (buffer.length < 4)
+                return;
+            const size = buffer.readUInt32BE(0);
+            if (size < 2 || size > 4096 || buffer.length > size + 4) {
+                finish(new Error("Invalid broker reset response frame"));
+                return;
+            }
+            if (buffer.length < size + 4)
+                return;
+            try {
+                const response = JSON.parse(buffer.subarray(4).toString("utf8"));
+                if (!response || response.version !== version || response.kind !== "slot_reset" || response.requestId !== requestId
+                    || response.slot !== slot || Object.keys(response).length !== 4)
+                    throw Error("Invalid broker reset acknowledgement");
+                finish();
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error("Invalid broker reset response"));
+            }
+        });
+    });
+};
+/** The native control relay authenticates SO_PEERCRED uid 2000 and rejects root. */
+export const resetTrainingBrokerSlotAsOrganization = async (slot, signal, execute = promisify(execFile)) => {
+    trainingSlotPaths(slot);
+    signal.throwIfAborted();
+    const uid = DAIMON_GROK_ENGINE_BROKER.identities.organizationUid;
+    const program = `import { resetTrainingBrokerSlot } from ${JSON.stringify(import.meta.url)}; await resetTrainingBrokerSlot(Number(process.argv[1]), AbortSignal.timeout(10000)); process.stdout.write("slot-reset-complete\\n");`;
+    const result = await execute("setpriv", ["--clear-groups", `--reuid=${uid}`, `--regid=${uid}`,
+        "--inh-caps=-all", "--ambient-caps=-all", "--bounding-set=-all", "--", process.execPath,
+        "--input-type=module", "--eval", program, String(slot)], { signal, timeout: 15_000 });
+    if (result.stdout !== "slot-reset-complete\n")
+        throw Error("Broker reset child returned no verified acknowledgement");
+};

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

@@ -0,0 +1,22 @@
+import type { DaimonGrokRegistration } from "../../containerDaimonGrokWorkerRender.js";
+import type { TrainingBrokerDeclaration } from "./declaration.js";
+import type { TrainingSlotRuntime } from "./supervisor.js";
+export interface TrainingSlotRuntimeOptions {
+    declaration: TrainingBrokerDeclaration;
+    registration: DaimonGrokRegistration;
+    projectionSha256: string;
+    reset: (slot: number, signal: AbortSignal) => Promise<void>;
+    /** Test seam: the shell the provisioning script runs in and the `/proc` it reads identities from. */
+    shell?: string;
+    procRoot?: string;
+    logPath?: string;
+}
+export declare const createTrainingSlotRuntime: (options: TrainingSlotRuntimeOptions) => TrainingSlotRuntime;
+/** Never remove or change the ownership/mode of a worker home or tmp: siblings attest those inodes. */
+export declare const renderTrainingSlotWipe: (slot: number) => string[];
+/** A failed privilege drop is not evidence of denial; require a positive worker verdict. */
+export declare const probeTrainingWorker: (uid: number, target: string, depth: "read" | "enter", execute?: (command: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+}>) => Promise<boolean>;

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

@@ -0,0 +1,127 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync } from "node:fs";
+import { chmod, chown, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../../../shared/index.js";
+import { MOUNT_AWARE_CLEAR_HELPER } from "../../containerDaimonBrokerRender.js";
+import { probeTrainingSiblingClock } from "./clockProbe.js";
+import { renderTrainingTaskClockAssertions } from "./taskClock.js";
+import { renderTrainingSlotProvisioning } from "./provisioning.js";
+import { buildTrainingSlotReceipt, readGrokExecutableSha256, resolveTrainingCanaries } from "./receipt.js";
+import { DAIMON_ORGANIZATION_UID, TRAINING_HOST_BIND_DENY_PATHS, TRAINING_SEALED_DENY_PATHS, trainingSlotPaths, trainingWipeTargets, trainingClearTargets, TRAINING_SUPERVISOR_LOG } from "./paths.js";
+const run = promisify(execFile);
+const quote = (value) => `'${value.replace(/'/gu, `'"'"'`)}'`;
+export const createTrainingSlotRuntime = (options) => {
+    const shell = options.shell ?? "/bin/bash";
+    const logPath = options.logPath ?? TRAINING_SUPERVISOR_LOG;
+    const p = trainingSlotPaths(options.registration.slot);
+    const script = renderTrainingSlotProvisioning(options.registration).join("\n");
+    const log = (line) => {
+        const entry = `${new Date().toISOString()} ${line}\n`;
+        process.stderr.write(`[slot-supervisor] ${entry}`);
+        try {
+            appendFileSync(logPath, entry, { mode: 0o640 });
+        }
+        catch { /* the log is diagnostics, never the gate */ }
+    };
+    const siblingClocks = Array.from({ length: options.declaration.slots }, (_, slot) => trainingSlotPaths(slot))
+        .filter(peer => peer.slot !== p.slot).map(peer => peer.clockDirectory);
+    const probe = (target, depth) => siblingClocks.includes(target)
+        ? probeTrainingSiblingClock(p.slot, target)
+        : probeTrainingWorker(options.registration.uid, target, depth);
+    return {
+        log,
+        reset: signal => options.reset(p.slot, signal),
+        wipe: async () => {
+            // Root holds `CAP_CHOWN` and `CAP_DAC_READ_SEARCH` but not `CAP_DAC_OVERRIDE`, so it cannot delete
+            // inside a directory it handed to the worker or the broker. Reclaim each tree first, then remove it.
+            const script = renderTrainingSlotWipe(p.slot).join("\n");
+            await run(shell, ["--noprofile", "--norc", "-ceu", script], { maxBuffer: 1024 * 1024 }).catch((error) => {
+                const detail = error;
+                throw new SpawnfileError("runtime_error", `Training slot wipe failed: ${(detail.stderr ?? "").slice(-1024).trim() || "no diagnostic"}`);
+            });
+        },
+        provision: async () => {
+            const result = await run(shell, ["--noprofile", "--norc", "-ceu", script], { maxBuffer: 8 * 1024 * 1024 }).catch((error) => {
+                const detail = error;
+                throw new SpawnfileError("runtime_error", `Training slot provisioning failed: ${(detail.stderr ?? detail.stdout ?? "").slice(-2048).trim()}`);
+            });
+            if (result.stdout.trim())
+                log(`provisioning: ${result.stdout.trim().slice(-2048)}`);
+        },
+        canaries: async () => {
+            await run(shell, ["--noprofile", "--norc", "-ceu", renderTrainingTaskClockAssertions(options.registration).join("\n")]);
+            return resolveTrainingCanaries({
+                denyPaths: options.registration.denyPaths, probe, log, hostBindPaths: TRAINING_HOST_BIND_DENY_PATHS,
+                sealedPaths: TRAINING_SEALED_DENY_PATHS,
+                mountinfo: await readFile(`${options.procRoot ?? "/proc"}/self/mountinfo`, "utf8"),
+                unenforcedBindPolicy: options.declaration.unenforcedBindPolicy
+            });
+        },
+        nextGeneration: async () => {
+            const previous = await readFile(p.generationFile, "utf8").catch(() => "");
+            const parsed = Number.parseInt(JSON.parse(previous || "{}").generation ?? "0", 10);
+            // Seeded from the wall clock so a container restart cannot hand out a generation an evaluator already accepted.
+            const generation = Math.max(Number.isSafeInteger(parsed) && parsed > 0 ? parsed + 1 : 1, Math.floor(Date.now() / 1000));
+            await writeFile(p.generationFile, `${JSON.stringify({ generation })}\n`, { mode: 0o600 });
+            return generation;
+        },
+        publishReceipt: async ({ generation, nonce, canaries }) => {
+            const receipt = buildTrainingSlotReceipt({
+                slot: options.registration.slot, workerUid: options.registration.uid, generation, nonce,
+                projectionSha256: options.projectionSha256, sandboxProfileSha256: options.registration.profileSha256,
+                seccompProfileSha256: options.declaration.seccompProfileSha256,
+                grokExecutableSha256: readGrokExecutableSha256(), canaries, createdAt: new Date()
+            });
+            const temporary = `${p.preflightReceipt}.${randomUUID()}.tmp`;
+            await mkdir(path.dirname(p.preflightReceipt), { recursive: true });
+            await writeFile(temporary, `${JSON.stringify(receipt)}\n`, { mode: 0o600, flag: "wx" });
+            await chown(temporary, 0, DAIMON_ORGANIZATION_UID);
+            await chmod(temporary, 0o640);
+            await rename(temporary, p.preflightReceipt);
+            return p.preflightReceipt;
+        }
+    };
+};
+/** Never remove or change the ownership/mode of a worker home or tmp: siblings attest those inodes. */
+export const renderTrainingSlotWipe = (slot) => {
+    const p = trainingSlotPaths(slot);
+    const worker = `setpriv --clear-groups --reuid=${p.workerUid} --regid=${p.workerUid} --inh-caps=-all --ambient-caps=-all --bounding-set=-all --`;
+    return [
+        ...MOUNT_AWARE_CLEAR_HELPER,
+        // Attested roots must still be canonical before any recursive mutation.
+        ...[p.workerHome, p.privateTmp, ...trainingWipeTargets(slot), ...trainingClearTargets(slot)].map(target => `if [ -e ${quote(target)} ] || [ -L ${quote(target)} ]; then if [ -L ${quote(target)} ] || [ "$(realpath ${quote(target)})" != ${quote(target)} ]; then echo "noncanonical slot wipe target" >&2; exit 1; fi; fi`),
+        'reclaim() { parent=$(dirname "$1"); chown 0:0 "$parent"; chmod u+rwx "$parent"; if [ -e "$1" ]; then chown -R 0:0 "$1"; chmod -R u+rwX "$1"; fi; }',
+        ...trainingWipeTargets(slot).map(target => `reclaim ${quote(target)}; spawnfile_remove_tree ${quote(target)}`),
+        ...trainingClearTargets(slot).map(target => `reclaim ${quote(target)}; spawnfile_clear_tree ${quote(target)}`),
+        // Reclaim descendants only, then unlink as the worker, who owns the stable parent. No sibling inode changes.
+        `for worker_entry in ${quote(p.workerHome)}/* ${quote(p.workerHome)}/.[!.]* ${quote(p.workerHome)}/..?*; do`,
+        '  if [ ! -e "$worker_entry" ] && [ ! -L "$worker_entry" ]; then continue; fi',
+        `  if [ "$worker_entry" = ${quote(p.privateTmp)} ]; then continue; fi`,
+        '  if spawnfile_holds_mount "$worker_entry"; then echo "worker home contains a mount" >&2; exit 1; fi',
+        `  chown -hR ${p.workerUid}:${p.workerUid} "$worker_entry"`,
+        `  ${worker} /bin/sh -ceu 'if [ ! -L "$1" ]; then chmod -R u+rwX "$1"; fi; rm -rf "$1"' sh "$worker_entry"`,
+        'done',
+        `for worker_entry in ${quote(p.privateTmp)}/* ${quote(p.privateTmp)}/.[!.]* ${quote(p.privateTmp)}/..?*; do`,
+        '  if [ ! -e "$worker_entry" ] && [ ! -L "$worker_entry" ]; then continue; fi',
+        '  if spawnfile_holds_mount "$worker_entry"; then echo "worker tmp contains a mount" >&2; exit 1; fi',
+        `  chown -hR ${p.workerUid}:${p.workerUid} "$worker_entry"`,
+        `  ${worker} /bin/sh -ceu 'if [ ! -L "$1" ]; then chmod -R u+rwX "$1"; fi; rm -rf "$1"' sh "$worker_entry"`,
+        'done'
+    ];
+};
+/** A failed privilege drop is not evidence of denial; require a positive worker verdict. */
+export const probeTrainingWorker = async (uid, target, depth, execute = run) => {
+    const q = quote(target);
+    const reachable = depth === "enter" ? `test -r ${q} || test -x ${q} || ls -1 ${q} >/dev/null 2>&1` : `test -r ${q}`;
+    const result = await execute("setpriv", ["--clear-groups", `--reuid=${uid}`, `--regid=${uid}`,
+        "--inh-caps=-all", "--ambient-caps=-all", "--bounding-set=-all", "--", "/bin/sh", "-c",
+        `if ${reachable}; then echo reachable; else echo denied; fi`], { timeout: 10_000 });
+    if (result.stdout.trim() === "denied")
+        return true;
+    if (result.stdout.trim() === "reachable")
+        return false;
+    throw new SpawnfileError("runtime_error", "Training worker canary returned no verified verdict");
+};

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

@@ -0,0 +1,31 @@
+/**
+ * The syscalls a worker-uid namespace escape needs before it can even be
+ * attempted: a new user namespace, a new mount namespace, and the mount and
+ * unmount calls inside them.
+ *
+ * `clone`/`clone3` are deliberately absent. The pinned profile allows them only
+ * under an argument filter, so a static "is it allowed" question has no honest
+ * yes/no answer for them, and `unshare` already gates the route.
+ */
+export declare const TRAINING_NAMESPACE_ROUTE_SYSCALLS: readonly ["unshare", "mount", "umount2", "setns"];
+/**
+ * Whether the pinned seccomp profile lets the worker uid attempt a namespace
+ * escape at all — an **unconditional** `SCMP_ACT_ALLOW`, with no
+ * `includes.caps` (the container drops `CAP_SYS_ADMIN`) and no argument filter.
+ *
+ * This exists to keep one specific lie out of the slot receipt. When a probe
+ * route cannot run, the honest record is *which layer refused it*: a syscall
+ * the profile filters is a stronger denial than DAC and must be named as
+ * `seccomp`, while the same syscall refused by a profile that allows it came
+ * from the kernel or an LSM and must be named `kernel`. Merging the two into
+ * "denied" would let a filtered-syscall run read as though DAC had held.
+ */
+export declare const pinnedProfileAllowsNamespaceRoutes: (bytes?: string) => boolean;
+/**
+ * What to blame when the worker uid cannot open the namespace a route needs.
+ *
+ * Derived, never guessed: seccomp and a DAC/LSM refusal both surface as
+ * `EPERM`, so errno cannot tell them apart. The pinned profile can — Spawnfile
+ * ships its bytes and the declaration binds their digest.
+ */
+export declare const trainingNamespaceDenialMechanism: (bytes?: string) => "seccomp" | "kernel";

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

@@ -0,0 +1,36 @@
+import { DAIMON_GROK_SECCOMP_PROFILE_BYTES } from "../../../shared/daimonGrokSeccompProfile.js";
+/**
+ * The syscalls a worker-uid namespace escape needs before it can even be
+ * attempted: a new user namespace, a new mount namespace, and the mount and
+ * unmount calls inside them.
+ *
+ * `clone`/`clone3` are deliberately absent. The pinned profile allows them only
+ * under an argument filter, so a static "is it allowed" question has no honest
+ * yes/no answer for them, and `unshare` already gates the route.
+ */
+export const TRAINING_NAMESPACE_ROUTE_SYSCALLS = ["unshare", "mount", "umount2", "setns"];
+/**
+ * Whether the pinned seccomp profile lets the worker uid attempt a namespace
+ * escape at all — an **unconditional** `SCMP_ACT_ALLOW`, with no
+ * `includes.caps` (the container drops `CAP_SYS_ADMIN`) and no argument filter.
+ *
+ * This exists to keep one specific lie out of the slot receipt. When a probe
+ * route cannot run, the honest record is *which layer refused it*: a syscall
+ * the profile filters is a stronger denial than DAC and must be named as
+ * `seccomp`, while the same syscall refused by a profile that allows it came
+ * from the kernel or an LSM and must be named `kernel`. Merging the two into
+ * "denied" would let a filtered-syscall run read as though DAC had held.
+ */
+export const pinnedProfileAllowsNamespaceRoutes = (bytes = DAIMON_GROK_SECCOMP_PROFILE_BYTES) => {
+    const profile = JSON.parse(bytes);
+    return TRAINING_NAMESPACE_ROUTE_SYSCALLS.every((syscall) => (profile.syscalls ?? []).some((rule) => (rule.names ?? []).includes(syscall) && rule.action === "SCMP_ACT_ALLOW"
+        && (rule.includes?.caps ?? []).length === 0 && (rule.args ?? []).length === 0));
+};
+/**
+ * What to blame when the worker uid cannot open the namespace a route needs.
+ *
+ * Derived, never guessed: seccomp and a DAC/LSM refusal both surface as
+ * `EPERM`, so errno cannot tell them apart. The pinned profile can — Spawnfile
+ * ships its bytes and the declaration binds their digest.
+ */
+export const trainingNamespaceDenialMechanism = (bytes) => pinnedProfileAllowsNamespaceRoutes(bytes) ? "kernel" : "seccomp";

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

@@ -0,0 +1,108 @@
+export declare const TRAINING_SUPERVISOR_PROTOCOL: "spawnfile.training-slot-supervisor.v2";
+export declare const TRAINING_SUPERVISOR_MAX_REQUEST_BYTES = 4096;
+/**
+ * Everything the recycle verb does to the running slot. It is an interface so
+ * the state machine below can be tested without Docker, a broker, or root:
+ * the order of these calls *is* the contract, and getting it wrong (wiping
+ * before draining, writing a receipt before the canaries) is exactly the class
+ * of bug a live check finds far too late.
+ */
+export interface TrainingSlotRuntime {
+    /** Broker refuses active turns and live workers, then resets only this slot clock/turn store. */
+    reset(signal: AbortSignal): Promise<void>;
+    /** Clears this slot while preserving the worker-home/tmp identities attested by sibling turns. */
+    wipe(): Promise<void>;
+    /** Reuses the audited worker provisioning; shared broker files are untouched. */
+    provision(): Promise<void>;
+    /** Worker-uid denial canaries over every deny path; throws when one is still reachable. */
+    canaries(): Promise<{
+        path: string;
+        method: "sandboxed-read";
+        result: "denied";
+    }[]>;
+    /** Writes the slot preflight receipt v2 atomically, readable by the organization uid. */
+    publishReceipt(input: {
+        generation: number;
+        nonce: string;
+        canaries: readonly {
+            path: string;
+            method: "sandboxed-read";
+            result: "denied";
+        }[];
+    }): Promise<string>;
+    /** Monotonic per-slot generation; strictly greater than every generation this slot has ever published. */
+    nextGeneration(): Promise<number>;
+    log(line: string): void;
+}
+/**
+ * Bringing a slot up, receipt included — the only way this container starts one.
+ *
+ * `provision → start` alone was the whole start-up path, and `canaries` and
+ * `publishReceipt` were reachable only from `recycle`. The first trial of every
+ * run therefore executed with no worker-uid denial evidence at all, and a
+ * refusal that should have cost nothing surfaced only after that trial's spend.
+ * Trial 1 is exactly the trial whose sealed datasets have never been probed, so
+ * it is the one that most needs the evidence.
+ *
+ * The receipt this publishes carries generation 1..N and a nonce of the
+ * container's own, so an evaluator that reads `preflight.json` before its first
+ * wake sees the same `noopolis.daimon.grok-slot-preflight.v2` shape a recycle
+ * publishes, from the same canaries.
+ */
+export declare const startTrainingSlot: (runtime: TrainingSlotRuntime, nonce: string) => Promise<{
+    generation: number;
+    receipt: string;
+    canaries: number;
+}>;
+export interface TrainingSlotSupervisorOptions {
+    runtimes: readonly TrainingSlotRuntime[];
+    /** Only this uid may recycle. Paideia, DSPy and the judges all run as it; every worker uid is refused. */
+    organizationUid?: number;
+    drainTimeoutMs?: number;
+    now?: () => number;
+}
+export interface TrainingRecycleResult {
+    ok: true;
+    verb: "recycle";
+    slot: number;
+    generation: number;
+    nonce: string;
+    receipt: string;
+    durationMs: number;
+}
+/**
+ * The single-verb root slot supervisor.
+ *
+ * One verb, slot and nonce, no path or command ever supplied by the caller: the
+ * whole point of D4 is that recycling replays the container's own audited
+ * provisioning rather than exposing a root file-system API to the evaluator.
+ * Recycles of the same slot are serialized — a second caller waits rather than interleaving a
+ * wipe with a provision.
+ */
+export declare const createTrainingSlotSupervisor: (options: TrainingSlotSupervisorOptions) => {
+    /** Serialized: a recycle already in flight completes before the next one starts. */
+    recycle: (slot: number, nonce: string, peerUid: number) => Promise<TrainingRecycleResult>;
+};
+export type TrainingSlotSupervisor = ReturnType<typeof createTrainingSlotSupervisor>;
+/**
+ * Re-establishes, and re-checks on every connection, the only uid gate this
+ * socket has.
+ *
+ * The scope asked for `SO_PEERCRED`. Node exposes no ancillary-data or
+ * peer-credential API on a unix socket and no native addon ships in this
+ * image, so the gate is the socket node itself, which the kernel enforces on
+ * `connect()` exactly as it does on `open()`: the node is
+ * `root:<organization gid> 0660` inside a root-owned `0711` directory on
+ * tmpfs, where modes *are* enforced. Only uid 2000 (and root) can connect;
+ * uid 2200 gets `EACCES` before a byte is written. A `0600` root-owned socket
+ * — the literal reading of the scope — would deny the one caller it exists
+ * for, so this is the same restriction stated in the only mechanism available.
+ * The directory holds no write permission for anyone but root, so the node
+ * cannot be replaced by a laxer one.
+ */
+export declare const assertTrainingSupervisorSocketIdentity: (socketPath: string, organizationGid: number) => void;
+/**
+ * Line-delimited JSON over a unix socket. Every request is bounded,
+ * single-line, and must name the protocol, the one verb and nothing else.
+ */
+export declare const serveTrainingSlotSupervisor: (supervisor: TrainingSlotSupervisor, socketPath: string, log: (line: string) => void, organizationUid?: number) => import("net").Server;

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

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

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

@@ -0,0 +1,5 @@
+import type { DaimonGrokRegistration } from "../../containerDaimonGrokWorkerRender.js";
+/** Reclaim only the clock subtree before the shared program clears the control root at startup. */
+export declare const renderTrainingTaskClockReset: () => string[];
+/** Before a receipt, bind the actual installed bytes and worker access to the clocked projection. */
+export declare const renderTrainingTaskClockAssertions: (registration: DaimonGrokRegistration) => string[];

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

@@ -0,0 +1,41 @@
+import { DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { SpawnfileError } from "../../../shared/index.js";
+import { resolveDaimonGrokClockedWorkerConfig } from "../../../runtime/daimon/grokWorkerContract.js";
+const clock = DAIMON_GROK_ENGINE_BROKER.worker.taskClock;
+const quote = (value) => `'${value.replace(/'/gu, `'"'"'`)}'`;
+/** Reclaim only the clock subtree before the shared program clears the control root at startup. */
+export const renderTrainingTaskClockReset = () => [
+    `test ! -L ${quote(clock.rootDirectoryPath)}`,
+    `if [ -d ${quote(clock.rootDirectoryPath)} ]; then chown -R 0:0 ${quote(clock.rootDirectoryPath)}; chmod -R u+rwX ${quote(clock.rootDirectoryPath)}; fi`
+];
+/** Before a receipt, bind the actual installed bytes and worker access to the clocked projection. */
+export const renderTrainingTaskClockAssertions = (registration) => {
+    const pin = resolveDaimonGrokClockedWorkerConfig(registration.model, registration.reasoningEffort, registration.slot).sha256;
+    const directoryPath = clock.slotDirectoryPattern.replace("{slot}", String(registration.slot));
+    const timestampFilePath = clock.slotFilePattern.replace("{slot}", String(registration.slot));
+    if (registration.configVariant !== "clocked" || registration.configSha256 !== pin) {
+        throw new SpawnfileError("runtime_error", "Training slot requires the pinned clocked worker config");
+    }
+    const worker = [
+        `test -r ${quote(timestampFilePath)}`, `test ! -w ${quote(timestampFilePath)}`,
+        `test -x ${quote(directoryPath)}`, `test ! -w ${quote(directoryPath)}`,
+        `test -r ${quote(clock.preloadPath)}`
+    ].join(" && ");
+    return [
+        `test ! -L ${quote(directoryPath)} && test -d ${quote(directoryPath)}`,
+        `test ! -L ${quote(timestampFilePath)} && test -f ${quote(timestampFilePath)}`,
+        `test "$(stat -c '%u:%g %a' ${quote(directoryPath)})" = "${clock.ownerUid}:${clock.ownerUid} ${clock.directoryMode.toString(8)}"`,
+        `test "$(stat -c '%u:%g %a %h' ${quote(timestampFilePath)})" = "${clock.ownerUid}:${clock.ownerUid} ${clock.fileMode.toString(8)} 1"`,
+        `test "$(sha256sum ${quote(`${registration.grokHome}/config.toml`)} | cut -d ' ' -f1)" = ${quote(pin)}`,
+        // The read-only image bakes both the fixed symlink and the distro target. Refuse writable or
+        // non-root-owned ancestors/targets; a missing library must never masquerade as a working clock.
+        "node <<'SPAWNFILE_TASK_CLOCK_LIBRARY'",
+        "const fs = require('node:fs'), path = require('node:path');",
+        `const preload = ${JSON.stringify(clock.preloadPath)};`,
+        "const link = fs.lstatSync(preload); if (!link.isSymbolicLink() || link.uid !== 0 || link.gid !== 0) throw new Error('unsafe task clock preload link');",
+        "const library = fs.realpathSync(preload); if (!/^\\/usr\\/lib\\/(x86_64|aarch64)-linux-gnu\\/faketime\\/libfaketime\\.so\\.1$/.test(library) || !fs.statSync(library).isFile()) throw new Error('unexpected task clock library');",
+        "for (const root of [path.dirname(preload), library]) { for (let at = root;; at = path.dirname(at)) { const info = fs.lstatSync(at); if (info.isSymbolicLink() || info.uid !== 0 || info.gid !== 0 || (info.mode & 0o022)) throw new Error(`unsafe task clock library path: ${at}`); if (at === '/') break; } }",
+        "SPAWNFILE_TASK_CLOCK_LIBRARY",
+        `setpriv --clear-groups --reuid ${registration.uid} --regid ${registration.uid} --inh-caps=-all --ambient-caps=-all --bounding-set=-all -- /bin/sh -ceu ${quote(worker)}`
+    ];
+};

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

@@ -0,0 +1,21 @@
+export interface CompiledAgentPaths {
+    workspace: string;
+    runtimeConfig: string;
+    home: string | null;
+    skillRoots: string[];
+    moltnet: {
+        networkId: string;
+        memberId: string;
+        nodeConfig: string;
+        serverConfig: string | null;
+    }[];
+}
+export interface CompiledAgent extends CompiledAgentPaths {
+    agentId: string;
+    runtime: string;
+    instanceId: string;
+    /** The same paths in the container's namespace; top-level paths address compileOut/container/rootfs. */
+    containerPaths: CompiledAgentPaths;
+}
+/** Read compiler facts only. Does not load runtime state, credentials, or authored manifests. */
+export declare const resolveCompiledAgent: (compileOut: string, agentName: string) => Promise<CompiledAgent>;