spawnfile 0.1.33 → 0.1.35

package/dist/compiler/training/trial/docker.js

@@ -0,0 +1,22 @@
+import { execFile } from "node:child_process";
+import { SpawnfileError } from "../../../shared/index.js";
+export const createTrialDocker = (dockerCommand = "docker") => (args, options = {}) => new Promise((resolve, reject) => {
+    const child = execFile(dockerCommand, [...args], { maxBuffer: 16 * 1024 * 1024, timeout: options.timeoutMs ?? 120_000 }, (error, stdout, stderr) => error
+        ? reject(new SpawnfileError("runtime_error", `docker ${args[0]} ${args[1] ?? ""} failed: ${String(stderr).replace(/\s+/gu, " ").slice(-400)}`))
+        : resolve(`${stdout}${options.combined ? stderr : ""}`.trim()));
+    if (options.stdin !== undefined)
+        child.stdin?.end(options.stdin);
+    else
+        child.stdin?.end();
+});
+/** Poll `probe` until it resolves true, or fail after `timeoutMs`. */
+export const waitFor = async (probe, timeoutMs, label, pollMs = 500) => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (await probe())
+            return;
+        if (Date.now() >= deadline)
+            throw new SpawnfileError("runtime_error", `${label} timed out after ${timeoutMs}ms`);
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+};

package/dist/compiler/training/trial/gateway.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedAuthProfile } from "../../../auth/index.js";
+import { type TrialDocker } from "./docker.js";
+export interface TrainingGatewayOptions {
+    /** Any compiled image of the subject: it carries the pinned Daimon runtime the gateway binary comes from. */
+    image: string;
+    runtimeRoot: string;
+    engines: readonly string[];
+    authProfile: ResolvedAuthProfile;
+    /** Training run identity; names the run's networks and labels every resource. */
+    runId: string;
+    docker?: TrialDocker;
+    /** Overrides the rendered sidecar script (tests and diagnostics only). */
+    script?: (script: string) => string;
+    readyTimeoutMs?: number;
+}
+/** What a trial needs to boot against the sidecar: one agent contract, never a login. */
+export interface TrainingGatewayAccess {
+    url: string;
+    key: string;
+    /** Internal (no egress) network the trials join; only the gateway reaches the internet. */
+    network: string;
+}
+export interface TrainingGateway extends TrainingGatewayAccess {
+    container: string;
+    realmVolumes: readonly string[];
+    /** Stops and removes the sidecar and both networks. The realm volumes stay: they are the login. */
+    stop(): Promise<void>;
+    /** Replaces a dead or stuck sidecar in place: same key, networks and realm, so booted trials keep working. */
+    restart(script?: (script: string) => string): Promise<void>;
+}
+/**
+ * The gatewayed engines whose login the auth profile holds: the run's gateway
+ * serves all of them, so subject and judges may run on any of these engines.
+ */
+export declare const trainingGatewayLogins: (profile: ResolvedAuthProfile) => string[];
+/** One durable realm volume per auth profile and engine: the gateway is its sole holder (exclusive flock). */
+export declare const trainingGatewayRealmVolume: (profile: string, engine: string) => string;
+/**
+ * Places Daimon's auth gateway as a sidecar for one training run: a container
+ * from the subject's own compiled image (the pinned Daimon runtime is a
+ * scratch copy source and runs nothing by itself), with the production Docker
+ * security posture, owning the engine realm volume, on a dedicated egress
+ * network plus the run's internal network that the trials join. Nothing is
+ * published to the host. The bootstrap leaf of the selected auth profile is
+ * staged through the same gate as `spawnfile up`.
+ */
+export declare const startTrainingGateway: (options: TrainingGatewayOptions) => Promise<TrainingGateway>;

package/dist/compiler/training/trial/gateway.js

@@ -0,0 +1,113 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DAIMON_GATEWAY_PORT, daimonGatewayBootstrapMountPath, daimonGatewayedEngines, daimonGatewayRealmPath } from "../../../runtime/daimon/gateway.js";
+import { assertSafeDaimonSourceFile } from "../../../runtime/daimon/runAuth.js";
+import { DAIMON_DOCKER_RUNTIME_SECURITY_ARGS, SpawnfileError } from "../../../shared/index.js";
+import { createDockerTargetExecutors } from "../../../target/dockerCommandExecutor.js";
+import { removeExactDockerResource } from "../../../target/dockerResources.js";
+import { createDockerResourceSpec, executeDockerResource } from "../../../target/dockerResourcesProvider.js";
+import { parseOpaqueTargetHandle } from "../../../target/contracts.js";
+import { DAIMON_GATEWAY_SIDECAR_ALIAS, DAIMON_GATEWAY_SIDECAR_KEY_ENV, DAIMON_GATEWAY_SIDECAR_URL, renderDaimonGatewaySidecarScript } from "../../containerDaimonGatewayRender.js";
+import { slugify } from "../../helpers.js";
+import { createTrialDocker, waitFor } from "./docker.js";
+const hex = (value) => createHash("sha256").update(value).digest("hex");
+const opaque = (value) => parseOpaqueTargetHandle(`opaque_${hex(value)}`);
+const LABEL = "spawnfile.training-gateway";
+/**
+ * The gatewayed engines whose login the auth profile holds: the run's gateway
+ * serves all of them, so subject and judges may run on any of these engines.
+ */
+export const trainingGatewayLogins = (profile) => daimonGatewayedEngines(Object.keys(profile.imports)).map(({ id }) => id);
+/**
+ * The bootstrap leaf comes only from the profile's own import: a training
+ * gateway never falls back to the operator's personal engine home.
+ */
+const trainingGatewaySource = (profile, engine, fileName) => {
+    const imported = profile.imports[engine];
+    if (!imported)
+        throw new SpawnfileError("validation_error", `Auth profile ${profile.name} has no imported ${engine} login`);
+    return path.join(imported.path, fileName);
+};
+/** One durable realm volume per auth profile and engine: the gateway is its sole holder (exclusive flock). */
+export const trainingGatewayRealmVolume = (profile, engine) => `spawnfile-training-${slugify(profile) || "profile"}-${engine}-realm`;
+/**
+ * Places Daimon's auth gateway as a sidecar for one training run: a container
+ * from the subject's own compiled image (the pinned Daimon runtime is a
+ * scratch copy source and runs nothing by itself), with the production Docker
+ * security posture, owning the engine realm volume, on a dedicated egress
+ * network plus the run's internal network that the trials join. Nothing is
+ * published to the host. The bootstrap leaf of the selected auth profile is
+ * staged through the same gate as `spawnfile up`.
+ */
+export const startTrainingGateway = async (options) => {
+    const docker = options.docker ?? createTrialDocker();
+    const descriptors = daimonGatewayedEngines(options.engines);
+    if (descriptors.length === 0)
+        throw new SpawnfileError("validation_error", "Training gateway needs a gatewayed engine");
+    const context = await docker(["context", "show"]);
+    const executor = createDockerTargetExecutors().resource;
+    const internal = createDockerResourceSpec({
+        kind: "data_network", operationHandle: opaque(`${options.runId}\0network`), requestDigest: `sha256:${hex(options.runId)}`,
+        runId: options.runId, selectedTargetHandle: opaque(context)
+    });
+    const suffix = hex(options.runId).slice(0, 16);
+    const egress = `spawnfile-training-egress-${suffix}`;
+    const container = `spawnfile-training-gateway-${suffix}`;
+    const key = randomBytes(32).toString("hex");
+    const mounts = [];
+    const realmVolumes = [];
+    for (const descriptor of descriptors) {
+        const source = trainingGatewaySource(options.authProfile, descriptor.id, descriptor.auth.fileName);
+        await assertSafeDaimonSourceFile(source, descriptor.id, descriptor.auth.maxCredentialBytes, descriptor.id);
+        const volume = trainingGatewayRealmVolume(options.authProfile.name, descriptor.id);
+        realmVolumes.push(volume);
+        mounts.push("--mount", `type=volume,source=${volume},target=${daimonGatewayRealmPath(descriptor)}`, "-v", `${source}:${daimonGatewayBootstrapMountPath(descriptor.auth.realm)}:ro`);
+    }
+    const stop = async () => {
+        await docker(["rm", "-f", container]).catch(() => undefined);
+        await docker(["network", "rm", egress]).catch(() => undefined);
+        await removeExactDockerResource(internal, { context, executor, timeoutMs: 30_000 }).catch(() => undefined);
+    };
+    const launch = async (wrap = options.script) => {
+        const support = await mkdtemp(path.join(os.tmpdir(), "spawnfile-training-gateway-"));
+        try {
+            const envFile = path.join(support, "gateway.env");
+            await writeFile(envFile, `${DAIMON_GATEWAY_SIDECAR_KEY_ENV}=${key}\n`, { mode: 0o600 });
+            const script = renderDaimonGatewaySidecarScript(options.engines, options.runtimeRoot);
+            await docker(["create", "--name", container, "--restart", "no", "--network", egress, "--label", `${LABEL}=${suffix}`,
+                ...DAIMON_DOCKER_RUNTIME_SECURITY_ARGS, ...mounts, "--env-file", envFile,
+                "--entrypoint", "bash", options.image, "-ceu", wrap ? wrap(script) : script]);
+        }
+        finally {
+            await rm(support, { recursive: true, force: true });
+        }
+        await docker(["network", "connect", "--alias", DAIMON_GATEWAY_SIDECAR_ALIAS, internal.name, container]);
+        await docker(["start", container]);
+        await waitFor(async () => {
+            const state = await docker(["inspect", "--format", "{{.State.Running}}", container]);
+            if (state !== "true") {
+                const logs = await docker(["logs", "--tail", "20", container], { combined: true }).catch(() => "");
+                throw new SpawnfileError("runtime_error", `training auth gateway exited before readiness: ${logs.replace(/\s+/gu, " ").slice(-400)}`);
+            }
+            return docker(["exec", container, "bash", "-c", `(exec 3<>/dev/tcp/127.0.0.1/${DAIMON_GATEWAY_PORT})`]).then(() => true, () => false);
+        }, options.readyTimeoutMs ?? 60_000, "training auth gateway readiness");
+    };
+    try {
+        await executeDockerResource({ args: ["--context", context, ...internal.args], executor, timeoutMs: 30_000 });
+        await docker(["network", "create", "--label", `${LABEL}=${suffix}`, egress]);
+        await launch();
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+    return {
+        container, key, network: internal.name, realmVolumes, stop, url: DAIMON_GATEWAY_SIDECAR_URL,
+        restart: async (wrap) => {
+            await docker(["rm", "-f", container]);
+            await launch(wrap);
+        }
+    };
+};

package/dist/compiler/training/trial/homeLogin.d.ts

@@ -0,0 +1,31 @@
+import type { TrialDocker } from "./docker.js";
+/**
+ * The login files an engine with a volume-held login keeps in its runtime home,
+ * relative to that home. AGY's OAuth token (which AGY rewrites when it
+ * refreshes), its installation id and its onboarded project: nothing else, so
+ * no conversation, history or knowledge ever passes between trials.
+ */
+export declare const HOME_LOGIN_FILES: Readonly<Record<string, readonly string[]>>;
+/** One organization's runtime home and the profile volume its login files persist in. */
+export interface HomeLogin {
+    /** The organization's own runtime home volume and where it is mounted. */
+    homeVolume: string;
+    homeMountPath: string;
+    /** The profile's volume holding only the login files. */
+    loginVolume: string;
+    files: readonly string[];
+}
+/**
+ * Copies each listed file that exists from the profile's login root into the
+ * runtime home (`seed`) or back (`save`), as the organization uid: regular
+ * single-link files only, no link anywhere on either path, written beside the
+ * target and renamed over it, identical files left alone. Started as root only
+ * to hand the destination root to the uid and to enter the home, whose image
+ * ancestors the uid cannot traverse until the organization's entrypoint opens
+ * them; the bytes are never printed.
+ */
+export declare const HOME_LOGIN_PROGRAM: string;
+/** Seeds the profile's login files into the organization's fresh runtime home, before it boots. */
+export declare const seedHomeLogin: (docker: TrialDocker, image: string, login: HomeLogin) => Promise<string>;
+/** Writes the login files the engine wrote or rewrote (a refreshed token) back to the profile, after the container stops. */
+export declare const saveHomeLogin: (docker: TrialDocker, image: string, login: HomeLogin) => Promise<string>;

package/dist/compiler/training/trial/homeLogin.js

@@ -0,0 +1,69 @@
+import { DAIMON_ORGANIZATION_UID } from "../../../runtime/daimon/runtimeIdentity.js";
+/**
+ * The login files an engine with a volume-held login keeps in its runtime home,
+ * relative to that home. AGY's OAuth token (which AGY rewrites when it
+ * refreshes), its installation id and its onboarded project: nothing else, so
+ * no conversation, history or knowledge ever passes between trials.
+ */
+export const HOME_LOGIN_FILES = {
+    agy: [
+        ".gemini/antigravity-cli/antigravity-oauth-token",
+        ".gemini/antigravity-cli/installation_id",
+        ".gemini/antigravity-cli/cache/default_project_id.txt",
+        ".gemini/antigravity-cli/cache/onboarding.json"
+    ]
+};
+const LOGIN_ROOT = "/spawnfile-home-login";
+/**
+ * Copies each listed file that exists from the profile's login root into the
+ * runtime home (`seed`) or back (`save`), as the organization uid: regular
+ * single-link files only, no link anywhere on either path, written beside the
+ * target and renamed over it, identical files left alone. Started as root only
+ * to hand the destination root to the uid and to enter the home, whose image
+ * ancestors the uid cannot traverse until the organization's entrypoint opens
+ * them; the bytes are never printed.
+ */
+export const HOME_LOGIN_PROGRAM = [
+    "const fs = require('node:fs'), path = require('node:path'), { constants } = fs;",
+    "const [uidText, direction, home, login, ...files] = process.argv.slice(1); const uid = Number(uidText);",
+    "const fail = (message) => { console.error(message); process.exit(3); };",
+    "if (direction !== 'seed' && direction !== 'save') fail('invalid direction');",
+    "process.chdir(home); const [from, to] = direction === 'seed' ? [login, '.'] : ['.', login];",
+    "if (process.getuid() === 0) {",
+    "  const root = fs.lstatSync(to); if (!root.isDirectory()) fail('login destination is not a directory');",
+    "  if (root.uid !== uid || (root.mode & 0o777) !== 0o700) { fs.chmodSync(to, 0o700); fs.chownSync(to, uid, uid); }",
+    "  process.setgroups([]); process.setgid(uid); process.setuid(uid);",
+    "}",
+    "const walk = (root, segments, create) => { let current = root; for (const segment of segments) { current = path.join(current, segment);",
+    "  let entry; try { entry = fs.lstatSync(current); } catch (error) { if (error.code !== 'ENOENT') throw error; if (!create) return null; fs.mkdirSync(current, { mode: 0o700 }); entry = fs.lstatSync(current); }",
+    "  if (!entry.isDirectory()) fail('login directory is not a directory'); } return current; };",
+    "for (const file of files) {",
+    "  const segments = file.split('/'); if (path.isAbsolute(file) || segments.some((segment) => segment === '' || segment === '.' || segment === '..')) fail('invalid login file path');",
+    "  if (walk(from, segments.slice(0, -1), false) === null) continue;",
+    "  let fd; try { fd = fs.openSync(path.join(from, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); } catch (error) { if (error.code === 'ENOENT') continue; fail('login file is unreadable or a link'); }",
+    "  const entry = fs.fstatSync(fd); if (!entry.isFile() || entry.nlink !== 1) fail('login file is not a regular file');",
+    "  const bytes = fs.readFileSync(fd); fs.closeSync(fd); const mode = entry.mode & 0o777;",
+    "  const directory = walk(to, segments.slice(0, -1), true), target = path.join(directory, segments.at(-1));",
+    "  let current = null; try { const existing = fs.lstatSync(target); if (!existing.isFile()) fail('login target is not a regular file'); current = fs.readFileSync(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }",
+    "  if (current !== null && current.equals(bytes) && (fs.lstatSync(target).mode & 0o777) === mode) { bytes.fill(0); current.fill(0); continue; }",
+    "  current?.fill(0); const temporary = `${target}.spawnfile-${process.pid}`;",
+    "  const out = fs.openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);",
+    "  let offset = 0; while (offset < bytes.length) offset += fs.writeSync(out, bytes, offset, bytes.length - offset, offset);",
+    "  bytes.fill(0); fs.fchmodSync(out, mode); fs.fsyncSync(out); fs.closeSync(out); fs.renameSync(temporary, target);",
+    "  const parent = fs.openSync(directory, constants.O_RDONLY); fs.fsyncSync(parent); fs.closeSync(parent);",
+    "}"
+].join("\n");
+const copy = (docker, image, login, direction) => docker([
+    "run", "--rm", "--network", "none", "--user", "0:0", "--cap-drop", "ALL",
+    // DAC_READ_SEARCH: root enters a home the organization already made its own (0700) to save from it.
+    "--cap-add", "CHOWN", "--cap-add", "DAC_READ_SEARCH", "--cap-add", "FOWNER", "--cap-add", "SETUID", "--cap-add", "SETGID",
+    "--security-opt", "no-new-privileges", "--entrypoint", "node",
+    "--mount", `type=volume,source=${login.loginVolume},target=${LOGIN_ROOT}`,
+    // Mounted where the organization mounts it, so a fresh home gets the image's own preimage first.
+    "--mount", `type=volume,source=${login.homeVolume},target=${login.homeMountPath}`,
+    image, "-e", HOME_LOGIN_PROGRAM, String(DAIMON_ORGANIZATION_UID), direction, login.homeMountPath, LOGIN_ROOT, ...login.files
+]);
+/** Seeds the profile's login files into the organization's fresh runtime home, before it boots. */
+export const seedHomeLogin = (docker, image, login) => copy(docker, image, login, "seed");
+/** Writes the login files the engine wrote or rewrote (a refreshed token) back to the profile, after the container stops. */
+export const saveHomeLogin = (docker, image, login) => copy(docker, image, login, "save");

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

@@ -0,0 +1,8 @@
+export { TRAINING_TRIAL_LINEAGE_NAMESPACE, prepareTrial, type BootedTrial, type PreparedTrial, type TrialOptions, type TrialWake } from "./boot.js";
+export { startTrainingGateway, trainingGatewayLogins, trainingGatewayRealmVolume, type TrainingGateway, type TrainingGatewayAccess, type TrainingGatewayOptions } from "./gateway.js";
+export { HOME_LOGIN_FILES, saveHomeLogin, seedHomeLogin, type HomeLogin } from "./homeLogin.js";
+export { JUDGE_INSTRUCTIONS, writeJudgeAgent, type JudgeSpec } from "./judge.js";
+export { createBootedTrialRun, type BootedTrialLauncherOptions, type BootedTrialRun } from "./launcher.js";
+export { TRIAL_INSTRUCTIONS_FILE, writeTrialProject } from "./project.js";
+export { ensureSubscriptionRealmVolumes, loginSubscriptionRealm, subscriptionRealmBinding, type SubscriptionRealmLoginOptions, type SubscriptionRealmLoginResult } from "./login.js";
+export { createRealmTurns, type RealmTurnOptions, type RealmTurns, type ReleaseRealmTurn } from "./realmTurns.js";

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

@@ -0,0 +1,8 @@
+export { TRAINING_TRIAL_LINEAGE_NAMESPACE, prepareTrial } from "./boot.js";
+export { startTrainingGateway, trainingGatewayLogins, trainingGatewayRealmVolume } from "./gateway.js";
+export { HOME_LOGIN_FILES, saveHomeLogin, seedHomeLogin } from "./homeLogin.js";
+export { JUDGE_INSTRUCTIONS, writeJudgeAgent } from "./judge.js";
+export { createBootedTrialRun } from "./launcher.js";
+export { TRIAL_INSTRUCTIONS_FILE, writeTrialProject } from "./project.js";
+export { ensureSubscriptionRealmVolumes, loginSubscriptionRealm, subscriptionRealmBinding } from "./login.js";
+export { createRealmTurns } from "./realmTurns.js";

package/dist/compiler/training/trial/judge.d.ts

@@ -0,0 +1,15 @@
+/** One judge identity of a run: the engine, and the model and effort its compiled organization pins. */
+export interface JudgeSpec {
+    engine: string;
+    model: string;
+    effort?: string;
+}
+/** The judge's system document: one self-contained judgment per wake, answered in the reply alone. */
+export declare const JUDGE_INSTRUCTIONS: string;
+/**
+ * Writes the judge's tool-free one-agent Daimon declaration: no skills, no
+ * MCP, no memory, no surfaces, no schedule. The model is pinned only where
+ * the engine's descriptor makes model selection configurable; otherwise the
+ * engine's own default model judges and the requested model is an assumption.
+ */
+export declare const writeJudgeAgent: (spec: JudgeSpec, directory: string) => Promise<string>;

package/dist/compiler/training/trial/judge.js

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getDaimonEngineDescriptor } from "../../../runtime/daimon/index.js";
+import { SpawnfileError } from "../../../shared/index.js";
+/** The judge's system document: one self-contained judgment per wake, answered in the reply alone. */
+export const JUDGE_INSTRUCTIONS = [
+    "You are a judge in a training run. Every message is one self-contained judging task.",
+    "Answer it directly in your reply. Never use a tool, command, file, memory, skill or the network:",
+    "a reply produced with any tool activity is discarded.",
+    "When the task gives a JSON Schema, reply with exactly one JSON value that matches it and nothing else."
+].join("\n");
+/**
+ * Writes the judge's tool-free one-agent Daimon declaration: no skills, no
+ * MCP, no memory, no surfaces, no schedule. The model is pinned only where
+ * the engine's descriptor makes model selection configurable; otherwise the
+ * engine's own default model judges and the requested model is an assumption.
+ */
+export const writeJudgeAgent = async (spec, directory) => {
+    const descriptor = getDaimonEngineDescriptor(spec.engine);
+    if (!descriptor)
+        throw new SpawnfileError("validation_error", `Judge engine ${spec.engine} is not a Daimon engine`);
+    const { provider, method } = descriptor.auth;
+    const pinned = descriptor.modelSelection.configurable && provider !== null && method !== null;
+    if (pinned && spec.effort !== undefined && !descriptor.modelSelection.reasoningEfforts.includes(spec.effort)) {
+        throw new SpawnfileError("validation_error", `Judge engine ${spec.engine} does not accept reasoning effort ${spec.effort}`);
+    }
+    const manifest = {
+        spawnfile_version: "0.1",
+        kind: "agent",
+        name: `judge-${spec.engine}`,
+        description: `Tool-free ${spec.engine} training judge`,
+        runtime: { name: "daimon", options: { engine: spec.engine } },
+        ...(pinned ? { execution: { model: { primary: {
+                        provider, name: spec.model, auth: { method }, ...(spec.effort === undefined ? {} : { reasoning_effort: spec.effort })
+                    } } } } : {})
+    };
+    await mkdir(directory, { recursive: true });
+    const manifestPath = path.join(directory, "Spawnfile");
+    // JSON is YAML; the trial project re-renders it with the judge instructions as its system document.
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return manifestPath;
+};

package/dist/compiler/training/trial/launcher.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedAuthProfile } from "../../../auth/index.js";
+import { prepareTrial, type BootedTrial, type TrialWake } from "./boot.js";
+import { type TrialDocker } from "./docker.js";
+import { type JudgeSpec } from "./judge.js";
+import { type RealmTurns } from "./realmTurns.js";
+export interface BootedTrialLauncherOptions {
+    /** The subject agent's own Spawnfile. */
+    agentManifestPath: string;
+    authProfile: ResolvedAuthProfile;
+    /** Trial projects, compile outputs and boot env files live here, one fresh directory per trial. */
+    scratchRoot: string;
+    docker?: TrialDocker;
+    turns?: RealmTurns;
+    /** Compiles and builds one organization (tests only). */
+    prepare?: typeof prepareTrial;
+    /** Bound on a judge's wait for a volume-held login another container holds (default 30 minutes). */
+    judgeRealmWaitMs?: number;
+}
+type Wake = (text: string, options: {
+    deliveryId: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<TrialWake>;
+type Booted = Pick<BootedTrial, "container" | "scanCredentials" | "teardown"> & {
+    wake: Wake;
+};
+export interface BootedTrialRun {
+    boot(input: {
+        trialId: string;
+        instructions: string;
+        signal?: AbortSignal;
+    }): Promise<Booted>;
+    /** The run's warm judge for this engine, model and effort: booted once, woken once per judgment. */
+    judge(spec: JudgeSpec): Promise<Omit<Booted, "teardown">>;
+    /** Tears down every judge, stops the run's gateway and removes its image and networks; the realm volumes stay. */
+    close(): Promise<void>;
+}
+/**
+ * One training run's containers: each trial boot compiles and starts the
+ * subject's one-agent organization, each judge is a tool-free one-agent
+ * organization booted the same way, and all of them share the run's single
+ * auth gateway, started from the first image on first use. The gateway holds
+ * every gatewayed login of the run's auth profile, so trials and judges on
+ * any engine reach it with one key.
+ */
+export declare const createBootedTrialRun: (options: BootedTrialLauncherOptions) => BootedTrialRun;
+export {};

package/dist/compiler/training/trial/launcher.js

@@ -0,0 +1,193 @@
+import { mkdir, mkdtemp } from "node:fs/promises";
+import path from "node:path";
+import { daimonGatewayedEngines } from "../../../runtime/daimon/gateway.js";
+import { getDaimonEngineDescriptor } from "../../../runtime/daimon/index.js";
+import { ensureNoopolisRunId } from "../../../runtime/index.js";
+import { SpawnfileError } from "../../../shared/index.js";
+import { prepareTrial } from "./boot.js";
+import { createTrialDocker } from "./docker.js";
+import { startTrainingGateway, trainingGatewayLogins } from "./gateway.js";
+import { JUDGE_INSTRUCTIONS, writeJudgeAgent } from "./judge.js";
+import { HOME_LOGIN_FILES } from "./homeLogin.js";
+import { createRealmTurns } from "./realmTurns.js";
+/**
+ * One training run's containers: each trial boot compiles and starts the
+ * subject's one-agent organization, each judge is a tool-free one-agent
+ * organization booted the same way, and all of them share the run's single
+ * auth gateway, started from the first image on first use. The gateway holds
+ * every gatewayed login of the run's auth profile, so trials and judges on
+ * any engine reach it with one key.
+ */
+export const createBootedTrialRun = (options) => {
+    const docker = options.docker ?? createTrialDocker();
+    const turns = options.turns ?? createRealmTurns();
+    const prepare = options.prepare ?? prepareTrial;
+    const runId = ensureNoopolisRunId();
+    const logins = trainingGatewayLogins(options.authProfile);
+    let gateway;
+    const judges = new Map();
+    let closed = false;
+    /** The gateway this organization needs (null: no gatewayed engine), started on first use. */
+    const gatewayFor = async (prepared) => {
+        const gatewayed = daimonGatewayedEngines(prepared.engines);
+        if (gatewayed.length === 0)
+            return null;
+        const missing = gatewayed.filter((descriptor) => !logins.includes(descriptor.id));
+        if (missing.length > 0) {
+            throw new SpawnfileError("validation_error", `Auth profile ${options.authProfile.name} has no ${missing.map(({ id }) => id).join(", ")} login; run \`spawnfile auth import <engine> --profile ${options.authProfile.name}\``);
+        }
+        gateway ??= (async () => {
+            const image = `spawnfile-training-gateway:${runId.replace(/[^A-Za-z0-9_.-]/gu, "-").slice(0, 100)}`;
+            await docker(["tag", prepared.image, image]);
+            return { image, gateway: await startTrainingGateway({ authProfile: options.authProfile, docker, engines: logins,
+                    image, runId, runtimeRoot: prepared.runtimeRoot }) };
+        })();
+        return (await gateway).gateway;
+    };
+    /**
+     * The volume-held login (`spawnfile auth login`) this organization mounts,
+     * as a profile view that carries nothing else: no env, no imports.
+     */
+    const realmFor = (prepared) => {
+        const engine = prepared.engines.find((id) => getDaimonEngineDescriptor(id)?.auth.staging === "secret-service");
+        if (engine === undefined)
+            return undefined;
+        const binding = options.authProfile.realms?.[engine];
+        // A login recorded before its home login files were kept cannot enroll a fresh home.
+        if (!binding || (HOME_LOGIN_FILES[engine] !== undefined && binding.homeVolume === undefined)) {
+            throw new SpawnfileError("validation_error", `Auth profile ${options.authProfile.name} has no ${engine} login; run \`spawnfile auth login ${engine} --profile ${options.authProfile.name}\``);
+        }
+        return { volume: binding.realmVolume, profile: { ...options.authProfile, env: {}, imports: {}, realms: { [engine]: binding } } };
+    };
+    /** Boots one container, holding its login realm's turn (if any) until the container is gone. */
+    const bootContainer = async (prepared, turn = {}) => {
+        const access = await gatewayFor(prepared);
+        const realm = realmFor(prepared);
+        const release = realm ? await turns.take(realm.volume, turn) : undefined;
+        try {
+            const booted = await prepared.boot(access, realm ? { realms: realm.profile } : {});
+            return { ...booted, teardown: async () => { try {
+                    await booted.teardown();
+                }
+                finally {
+                    release?.();
+                } } };
+        }
+        catch (error) {
+            release?.();
+            throw error;
+        }
+    };
+    const start = async (prepared, signal) => {
+        try {
+            const booted = await bootContainer(prepared, signal ? { signal } : {});
+            return { ...booted, teardown: async () => { try {
+                    await booted.teardown();
+                }
+                finally {
+                    await prepared.dispose();
+                } } };
+        }
+        catch (error) {
+            await prepared.dispose();
+            throw error;
+        }
+    };
+    /**
+     * A judge on a volume-held login takes turns with the run's trials: it stays
+     * warm while nobody else waits for the realm, and hands the turn over (its
+     * container removed) after its current judgment once someone does. Its image
+     * is built once and kept.
+     */
+    const takeTurnsJudge = (prepared) => {
+        let booted;
+        let container = "";
+        let busy = 0;
+        let evict = false;
+        const down = async () => {
+            const current = booted;
+            booted = undefined;
+            evict = false;
+            await (await current?.catch(() => undefined))?.teardown();
+        };
+        const timeoutMs = options.judgeRealmWaitMs ?? 30 * 60_000;
+        return {
+            get container() { return container; },
+            scanCredentials: async () => (await booted?.catch(() => undefined))?.scanCredentials() ?? [],
+            wake: async (text, wakeOptions) => {
+                busy++;
+                try {
+                    if (!booted) {
+                        const pending = bootContainer(prepared, { timeoutMs, ...(wakeOptions.signal ? { signal: wakeOptions.signal } : {}),
+                            onContended: () => { evict = true; if (busy === 0)
+                                void down(); } });
+                        booted = pending;
+                        pending.then((judge) => { container = judge.container; }, () => { if (booted === pending)
+                            booted = undefined; });
+                    }
+                    return await (await booted).wake(text, wakeOptions);
+                }
+                finally {
+                    busy--;
+                    if (evict && busy === 0)
+                        await down();
+                }
+            },
+            teardown: async () => { try {
+                await down();
+            }
+            finally {
+                await prepared.dispose();
+            } }
+        };
+    };
+    const directory = async (prefix) => {
+        await mkdir(options.scratchRoot, { recursive: true });
+        return mkdtemp(path.join(options.scratchRoot, prefix));
+    };
+    return {
+        boot: async ({ trialId, instructions, signal }) => start(await prepare({
+            agentManifestPath: options.agentManifestPath, docker, instructions, trialId, directory: await directory("trial-")
+        }), signal),
+        judge: (spec) => {
+            if (closed)
+                return Promise.reject(new SpawnfileError("runtime_error", "the training run is closed"));
+            const key = JSON.stringify([spec.engine, spec.model, spec.effort ?? null]);
+            let judge = judges.get(key);
+            if (!judge) {
+                judge = (async () => {
+                    const root = await directory("judge-");
+                    const prepared = await prepare({
+                        agentManifestPath: await writeJudgeAgent(spec, path.join(root, "source")), docker, instructions: JUDGE_INSTRUCTIONS,
+                        trialId: `judge-${spec.engine}-${key}-${runId}`, directory: root
+                    });
+                    let turnTaking;
+                    try {
+                        turnTaking = realmFor(prepared) !== undefined;
+                    }
+                    catch (error) {
+                        await prepared.dispose();
+                        throw error;
+                    }
+                    return turnTaking ? takeTurnsJudge(prepared) : start(prepared);
+                })();
+                judges.set(key, judge);
+                // A failed boot is not cached: the next judgment retries it.
+                judge.catch(() => { if (judges.get(key) === judge)
+                    judges.delete(key); });
+            }
+            return judge;
+        },
+        close: async () => {
+            closed = true;
+            const booted = await Promise.all([...judges.values()].map((judge) => judge.catch(() => undefined)));
+            judges.clear();
+            await Promise.all(booted.map((judge) => judge?.teardown().catch(() => undefined)));
+            const started = await gateway?.catch(() => undefined);
+            if (!started)
+                return;
+            await started.gateway.stop();
+            await docker(["image", "rm", "-f", started.image]).catch(() => undefined);
+        }
+    };
+};

package/dist/compiler/training/trial/login.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedAuthProfile, type SubscriptionRealmBinding } from "../../../auth/index.js";
+import { prepareTrial } from "./boot.js";
+import { type TrialDocker } from "./docker.js";
+export interface SubscriptionRealmLoginOptions {
+    profileName: string;
+    engine: string;
+    /** Prepare volumes and image and return the login command without running it or recording the login. */
+    dryRun?: boolean;
+    docker?: TrialDocker;
+    /** Where the throwaway login organization is compiled (default: a fresh temp directory). */
+    scratchRoot?: string;
+    /** Builds the throwaway one-agent organization the login runs in (tests only). */
+    prepare?: typeof prepareTrial;
+}
+export interface SubscriptionRealmLoginResult {
+    binding: SubscriptionRealmBinding;
+    /** The exact `docker run` argv the login uses. */
+    command: readonly string[];
+    profile: ResolvedAuthProfile;
+}
+/** The profile's volume names for an engine's volume-held login. */
+export declare const subscriptionRealmBinding: (profileName: string, engine: string) => Required<SubscriptionRealmBinding>;
+export declare const ensureSubscriptionRealmVolumes: (docker: TrialDocker, image: string, engine: string, binding: SubscriptionRealmBinding) => Promise<void>;
+/**
+ * `spawnfile auth login <engine>`: gives an auth profile its own volume-held
+ * login for an engine that keeps its login in a Daimon secret-service realm
+ * (AGY). Creates the profile's realm, unlock and home login volumes, then runs
+ * Daimon's own interactive `auth <engine> login` in a throwaway,
+ * production-booted one-agent organization (a tool-free judge) attached to the
+ * operator's terminal, keeps the engine's login files from that throwaway home
+ * in the home login volume, and records the volume names on the profile once
+ * it succeeds.
+ * Spawnfile never reads the login or the unlock secret.
+ */
+export declare const loginSubscriptionRealm: (options: SubscriptionRealmLoginOptions) => Promise<SubscriptionRealmLoginResult>;