spawnfile 0.1.14 → 0.1.17

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

@@ -0,0 +1,102 @@
+import path from "node:path";
+import { SpawnfileError } from "../../../shared/index.js";
+import { DAIMON_GROK_BROKER_MODELS, DAIMON_GROK_BROKER_REASONING_EFFORTS, DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { DAIMON_GROK_WORKER_HOME_DIRECTORY, daimonGrokWorkerSandboxProfileSha256, renderDaimonGrokWorkerSandboxProfile, resolveDaimonGrokWorkerConfig } from "../../../runtime/daimon/grokWorkerContract.js";
+import { DAIMON_GROK_BASE_PROFILE_GRANTS, assertCanonicalRegisteredPath } from "../../containerDaimonGrokWorkerRender.js";
+import { TRAINING_ADDED_DENY_PATHS, TRAINING_BOOTSTRAP_MOUNT, TRAINING_DEFERRED_DENY_PATHS, TRAINING_REALM_MOUNT, TRAINING_SLOT_INDEX, TRAINING_SLOT_RUNTIME_HOME, TRAINING_SLOT_STATE_ROOT, TRAINING_SLOT_USAGE_LEDGER, TRAINING_SLOT_WORKSPACE, TRAINING_WORKER_HOME, TRAINING_WORKER_UID } from "./paths.js";
+const fail = (message) => {
+    throw new SpawnfileError("compile_error", message);
+};
+const within = (candidate, root) => candidate === root || candidate.startsWith(`${root}/`);
+/**
+ * The one training slot's deny list: Daimon's own protected set for a
+ * single-agent organization (Grok bootstrap, realm, and the slot state root that
+ * holds the wake-acceptance store) plus everything this container provisions that the subject must not read —
+ * the evaluator roots, the caller's protected `/run/paideia` paths, the broker
+ * control and registration roots, the grant home root, the inference ledger,
+ * the per-slot ledger, turn store and supervisor socket directory.
+ *
+ * The same two refusals the production render enforces apply here: an entry
+ * that equals or contains a Grok 1.0.34 base-profile grant makes Grok refuse
+ * the profile outright, and masks cannot nest, so an entry covered by another
+ * entry is a provisioning bug rather than something to silently drop.
+ */
+export const resolveTrainingGrokDenyPaths = (added = TRAINING_ADDED_DENY_PATHS) => {
+    // The wake-acceptance store is masked through `TRAINING_SLOT_STATE_ROOT`, never directly: Grok 1.0.34
+    // materializes every deny target inside bubblewrap AS THE WORKER UID, and the store's parent is
+    // `2000:2000 0700`, so the store itself is unplaceable and would make Grok refuse the whole profile
+    // (`.runtime/grok-deny-placement/EVIDENCE.md`). The state root covers it and nothing else lives there.
+    const daimonOwn = [TRAINING_BOOTSTRAP_MOUNT, TRAINING_REALM_MOUNT, TRAINING_SLOT_STATE_ROOT];
+    const grokHome = path.posix.join(TRAINING_WORKER_HOME, DAIMON_GROK_WORKER_HOME_DIRECTORY);
+    const grants = [
+        ...DAIMON_GROK_BASE_PROFILE_GRANTS, TRAINING_SLOT_WORKSPACE, grokHome,
+        path.posix.join(grokHome, "sessions"), path.posix.join(TRAINING_WORKER_HOME, "tmp")
+    ];
+    const candidates = [...new Set([...daimonOwn, ...added])].sort();
+    for (const entry of candidates) {
+        assertCanonicalRegisteredPath("deny path", entry);
+        const grant = grants.find((candidate) => within(candidate, entry));
+        if (grant)
+            fail(`Training Grok deny path ${entry} equals or contains the base profile grant ${grant}; Grok refuses such a profile`);
+        if (within(TRAINING_SLOT_WORKSPACE, entry) || within(TRAINING_WORKER_HOME, entry) || within(TRAINING_SLOT_RUNTIME_HOME, entry)) {
+            fail(`Training Grok deny path ${entry} would hide the subject's own workspace, home, or runtime home`);
+        }
+        const ancestor = candidates.find((other) => other !== entry && within(entry, other));
+        if (ancestor)
+            fail(`Training Grok deny path ${ancestor} would cover ${entry}; masks cannot nest`);
+    }
+    return candidates;
+};
+/**
+ * The single brokered Grok registration a training container runs, at the
+ * fixed container paths in `paths.ts`. Unlike production it points
+ * `usageLedgerPath` at the per-slot ledger, because each trial's spend must be
+ * separable and a recycle wipes it; the container-wide ledger and wake fuse do
+ * not exist here.
+ */
+export const resolveTrainingGrokRegistration = (input) => {
+    if (!input.agentId.trim())
+        fail("Training Grok slot requires an agent id");
+    if (!DAIMON_GROK_BROKER_MODELS.includes(input.model)
+        || !DAIMON_GROK_BROKER_REASONING_EFFORTS.includes(input.reasoningEffort)) {
+        fail(`Training Grok slot has no declared broker model and reasoning effort: ${input.agentId}`);
+    }
+    const home = assertCanonicalRegisteredPath("home", TRAINING_WORKER_HOME);
+    const grokHome = path.posix.join(home, DAIMON_GROK_WORKER_HOME_DIRECTORY);
+    const config = resolveDaimonGrokWorkerConfig(input.model, input.reasoningEffort);
+    const denyPaths = resolveTrainingGrokDenyPaths(input.denyPaths);
+    const profile = renderDaimonGrokWorkerSandboxProfile(denyPaths);
+    const eventsPath = path.posix.join(grokHome, DAIMON_GROK_ENGINE_BROKER.worker.home.sandboxEvents.relativePath);
+    const profilePath = path.posix.join(grokHome, "sandbox.toml");
+    for (const [label, value] of [["GROK_HOME", grokHome], ["profile", profilePath], ["events", eventsPath],
+        ["workspace", TRAINING_SLOT_WORKSPACE], ["runtime home", TRAINING_SLOT_RUNTIME_HOME],
+        ["usage ledger", TRAINING_SLOT_USAGE_LEDGER]])
+        assertCanonicalRegisteredPath(label, value);
+    return {
+        agentId: input.agentId,
+        config: config.bytes,
+        ...(input.limits === undefined ? {} : { limits: { ...input.limits } }),
+        configSha256: config.sha256,
+        deferredDenyPaths: denyPaths.filter((entry) => TRAINING_DEFERRED_DENY_PATHS.includes(entry)),
+        denyPaths,
+        eventsPath,
+        grokHome,
+        home,
+        model: input.model,
+        profile,
+        profilePath,
+        profileSha256: daimonGrokWorkerSandboxProfileSha256(denyPaths),
+        privateTmp: path.posix.join(home, DAIMON_GROK_ENGINE_BROKER.worker.home.privateTmp.relativeToWorkerHome),
+        reasoningEffort: input.reasoningEffort,
+        runtimeHome: TRAINING_SLOT_RUNTIME_HOME,
+        // Empty on purpose: training has no persistent mounts at all. Everything a trial writes under the slot
+        // runtime home is per-slot tmpfs the recycle wipes, and the only thing provisioned inside it is the
+        // setgid `tool-output/` spill directory, so the traversable `0710` home exposes nothing else.
+        runtimeHomeMounts: [],
+        slot: TRAINING_SLOT_INDEX,
+        spillDirectory: path.posix.join(TRAINING_SLOT_RUNTIME_HOME, DAIMON_GROK_ENGINE_BROKER.worker.home.spillDirectory.relativeToRuntimeHome),
+        uid: TRAINING_WORKER_UID,
+        usageLedgerPath: TRAINING_SLOT_USAGE_LEDGER,
+        workspace: TRAINING_SLOT_WORKSPACE
+    };
+};

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

@@ -0,0 +1,25 @@
+import type { DaimonGrokRegistration } from "../../containerDaimonGrokWorkerRender.js";
+import type { TrainingBrokerDeclaration } from "./declaration.js";
+import { type BrokerChild } from "./processes.js";
+import type { TrainingSlotRuntime } from "./supervisor.js";
+export interface TrainingSlotRuntimeOptions {
+    declaration: TrainingBrokerDeclaration;
+    registration: DaimonGrokRegistration;
+    projectionSha256: string;
+    /** Test seam: the shell the provisioning script runs in and the `/proc` it reads identities from. */
+    shell?: string;
+    procRoot?: string;
+    logPath?: string;
+}
+/**
+ * The real slot runtime: what `recycle` actually does to this container.
+ *
+ * Every mutation goes through the same rendered provisioning the root
+ * entrypoint ran at startup, so a recycled slot is byte-identically
+ * provisioned — including the credential journal recovery, which is how a
+ * recycle that lands on a `refreshing` or `stale` realm either recovers or
+ * fails closed with a named error instead of leaving a silently stale realm.
+ */
+export declare const createTrainingSlotRuntime: (options: TrainingSlotRuntimeOptions) => TrainingSlotRuntime & {
+    children(): readonly BrokerChild[];
+};

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

@@ -0,0 +1,173 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync } from "node:fs";
+import { chmod, chown, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as pause } from "node:timers/promises";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../../../shared/index.js";
+import { DAIMON_GROK_ENGINE_BROKER } from "../../../runtime/daimon/contractManifest.js";
+import { MOUNT_AWARE_CLEAR_HELPER } from "../../containerDaimonBrokerRender.js";
+import { renderTrainingBrokerProvisioning, renderTrainingIdentities } from "./provisioning.js";
+import { startBrokerProcesses, stopBrokerProcesses } from "./processes.js";
+import { buildTrainingSlotReceipt, readGrokExecutableSha256, resolveTrainingCanaries } from "./receipt.js";
+import { DAIMON_ORGANIZATION_UID, TRAINING_HOST_BIND_DENY_PATHS, TRAINING_SEALED_DENY_PATHS, TRAINING_WIPE_TARGETS, TRAINING_SLOT_GENERATION_FILE, TRAINING_SLOT_PREFLIGHT_RECEIPT, TRAINING_SLOT_TURN_STORE, TRAINING_SLOT_USAGE_DIRECTORY, TRAINING_SLOT_WORKSPACE, TRAINING_SUPERVISOR_LOG } from "./paths.js";
+const run = promisify(execFile);
+const quote = (value) => `'${value.replace(/'/gu, `'"'"'`)}'`;
+const CREDENTIAL_JOURNAL = `${DAIMON_GROK_ENGINE_BROKER.credentialHomePath}/.daimon-broker/credential-journal.json`;
+/** State the broker's credential authority may be left in; only `promoted` (or no journal at all) is settled. */
+const settledJournal = async () => {
+    const raw = await readFile(CREDENTIAL_JOURNAL, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (raw === undefined)
+        return "settled";
+    const journal = JSON.parse(raw);
+    if (journal.version !== "noopolis.daimon.broker-credential-journal.v1")
+        throw new SpawnfileError("runtime_error", "The broker credential journal is not a recognised version");
+    return journal.state === "promoted" ? "settled" : journal.state === "refreshing" ? "refreshing" : "stale";
+};
+/** A turn is active while its registry record says so; a terminal record is finished work and never blocks a recycle. */
+const activeTurns = async () => {
+    const names = await readdir(TRAINING_SLOT_TURN_STORE).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    let active = 0;
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const raw = await readFile(path.join(TRAINING_SLOT_TURN_STORE, name), "utf8").catch(() => "");
+        try {
+            if (JSON.parse(raw).state === "active")
+                active += 1;
+        }
+        catch { /* a half-written record is not an active turn */ }
+    }
+    return active;
+};
+/**
+ * The real slot runtime: what `recycle` actually does to this container.
+ *
+ * Every mutation goes through the same rendered provisioning the root
+ * entrypoint ran at startup, so a recycled slot is byte-identically
+ * provisioned — including the credential journal recovery, which is how a
+ * recycle that lands on a `refreshing` or `stale` realm either recovers or
+ * fails closed with a named error instead of leaving a silently stale realm.
+ */
+export const createTrainingSlotRuntime = (options) => {
+    const shell = options.shell ?? "/bin/bash";
+    const logPath = options.logPath ?? TRAINING_SUPERVISOR_LOG;
+    const script = [...renderTrainingIdentities(), ...renderTrainingBrokerProvisioning(options.registration)].join("\n");
+    let children = [];
+    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 */ }
+    };
+    /**
+     * One worker-uid reachability attempt. The command below *succeeds* when the
+     * worker can still reach the target, so a non-zero exit is the denial.
+     *
+     * `enter` is the stronger question a sealed root needs answered: a directory
+     * can be unreadable (`test -r` fails) and still searchable, and a subject
+     * that knows `test.paideia.yaml` by name needs only search permission.
+     */
+    const probe = async (target, depth) => {
+        const quoted = JSON.stringify(target);
+        const reachable = depth === "enter"
+            ? `test -r ${quoted} || test -x ${quoted} || ls -1 ${quoted} >/dev/null 2>&1`
+            : `test -r ${quoted}`;
+        try {
+            await run("setpriv", ["--clear-groups", `--reuid=${options.registration.uid}`, `--regid=${options.registration.uid}`,
+                "--inh-caps=-all", "--ambient-caps=-all", "--bounding-set=-all", "--", "/bin/sh", "-c", reachable], { timeout: 10_000 });
+            return false;
+        }
+        catch {
+            return true;
+        }
+    };
+    return {
+        log,
+        children: () => children,
+        drain: async (signal) => {
+            for (;;) {
+                signal.throwIfAborted();
+                const state = await settledJournal();
+                if (state === "stale") {
+                    // The audited provisioning below owns stale-realm recovery; it promotes the bootstrap or refuses outright.
+                    log("credential journal is stale; the recycle will replay the root credential recovery");
+                    return;
+                }
+                if (state === "settled" && await activeTurns() === 0)
+                    return;
+                await pause(100);
+            }
+        },
+        stop: async () => { await stopBrokerProcesses(children, log); children = []; },
+        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 targets = TRAINING_WIPE_TARGETS;
+            const contents = [TRAINING_SLOT_WORKSPACE, TRAINING_SLOT_USAGE_DIRECTORY];
+            const script = [
+                ...MOUNT_AWARE_CLEAR_HELPER,
+                // The parent has to be reclaimed too: unlinking is a write to the *directory*, and the slot hands
+                // several of these parents to uid 2000 or the broker. Provisioning restores every mode right after.
+                '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; }',
+                ...targets.map((target) => `reclaim ${quote(target)}; spawnfile_remove_tree ${quote(target)}`),
+                // The workspace and the per-slot ledger directory keep their own root: the registered paths must
+                // stay canonical across a recycle, so only what a trial put inside them goes.
+                ...contents.map((target) => `reclaim ${quote(target)}; spawnfile_clear_tree ${quote(target)}`)
+            ].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)}`);
+        },
+        start: async () => { children = await startBrokerProcesses({ log, procRoot: options.procRoot }); },
+        canaries: async () => 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(TRAINING_SLOT_GENERATION_FILE, "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(TRAINING_SLOT_GENERATION_FILE, `${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 = `${TRAINING_SLOT_PREFLIGHT_RECEIPT}.${randomUUID()}.tmp`;
+            await mkdir(path.dirname(TRAINING_SLOT_PREFLIGHT_RECEIPT), { 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, TRAINING_SLOT_PREFLIGHT_RECEIPT);
+            return TRAINING_SLOT_PREFLIGHT_RECEIPT;
+        }
+    };
+};

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