spawnfile 0.1.34 → 0.1.35

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

@@ -1,10 +1,11 @@
 import { createHash, randomBytes } from "node:crypto";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { DAIMON_GATEWAY_KEY_ENV, DAIMON_GATEWAY_URL_ENV, getDaimonEngineDescriptor, isDaimonGatewayRealmMountId } from "../../../runtime/daimon/index.js";
+import { DAIMON_GATEWAY_KEY_ENV, DAIMON_GATEWAY_URL_ENV, daimonProfileRealmVolume, getDaimonEngineDescriptor, isDaimonGatewayRealmMountId } from "../../../runtime/daimon/index.js";
 import { daimonHelperControlCall } from "../../../runtime/daimon/control.js";
 import { RUNTIME_INSTALL_ROOT } from "../../../runtime/container.js";
 import { parseUsageLedger } from "../../../runtime/usageLedger.js";
+import { parseUsageRequestLedger } from "../../../runtime/usageRequestLedger.js";
 import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../../../runtime/daimon/contractManifest.js";
 import { SpawnfileError } from "../../../shared/index.js";
 import { buildCompiledProject } from "../../buildProject.js";
@@ -14,6 +15,7 @@ import { slugify } from "../../helpers.js";
 import { createDockerRunInvocation, runDockerContainer } from "../../runProject.js";
 import { executeDockerRunWithSupportCleanup } from "../../runProjectLifecycle.js";
 import { createTrialDocker, waitFor } from "./docker.js";
+import { HOME_LOGIN_FILES, saveHomeLogin, seedHomeLogin } from "./homeLogin.js";
 import { writeTrialProject } from "./project.js";
 /**
  * Lineage namespace for training trials: every trial derives its own durable
@@ -25,27 +27,61 @@ const CONTROL_TOKEN_ENV = "SPAWNFILE_DAIMON_CONTROL_TOKEN";
 const WAKE_VERSION = "noopolis.daimon.wake.v2";
 const TERMINAL = new Set(["completed", "failed", "stopped"]);
 const MAX_TRANSCRIPT_BYTES = 1024 * 1024;
+/**
+ * Readable and collision-free: trial ids may share long prefixes. The cut can
+ * land just after a hyphen, so it is trimmed: the slug names a kebab-case
+ * deployment, which refuses a doubled hyphen.
+ */
+export const trialSlug = (trialId) => `${slugify(trialId).slice(0, 32).replace(/-+$/u, "") || "trial"}-${createHash("sha256").update(trialId).digest("hex").slice(0, 8)}`;
 /** Compiles and builds the trial's one-agent organization under its own lineage, as production does. */
 export const prepareTrial = async (options) => {
     const docker = options.docker ?? createTrialDocker();
-    // Readable and collision-free: trial ids may share long prefixes.
-    const slug = `${slugify(options.trialId).slice(0, 32) || "trial"}-${createHash("sha256").update(options.trialId).digest("hex").slice(0, 8)}`;
-    const project = await writeTrialProject(options.agentManifestPath, options.instructions, path.join(options.directory, "project"));
-    const compiled = await compileProject(project, {
-        deploymentLineage: resolveDeploymentLineage(slug, TRAINING_TRIAL_LINEAGE_NAMESPACE),
-        outputDirectory: path.join(options.directory, "out")
-    });
+    const slug = trialSlug(options.trialId);
     const image = `spawnfile-training-trial:${slug}`;
-    await buildCompiledProject(project, compiled, { imageTag: image });
+    const compiled = await (async () => {
+        const project = await writeTrialProject(options.agentManifestPath, options.instructions, path.join(options.directory, "project"));
+        const compiled = await compileProject(project, {
+            deploymentLineage: resolveDeploymentLineage(slug, TRAINING_TRIAL_LINEAGE_NAMESPACE),
+            outputDirectory: path.join(options.directory, "out")
+        });
+        await buildCompiledProject(project, compiled, { imageTag: image });
+        return compiled;
+    })().catch(async (error) => {
+        await rm(options.directory, { recursive: true, force: true });
+        throw error;
+    });
     const instance = compiled.report.container?.runtime_instances.find((entry) => entry.runtime === "daimon");
     const agents = Object.entries(instance?.engine_by_node_id ?? {});
     if (!instance || agents.length !== 1)
         throw new SpawnfileError("validation_error", "A production-booted trial compiles exactly one Daimon agent");
-    const [agentId] = agents[0];
+    const [agentId, engine] = agents[0];
     const home = instance.agent_paths?.[agentId]?.home_path;
     // The engine writes its own session records under its home inside the agent's runtime home.
-    const engineHome = getDaimonEngineDescriptor(agents[0][1])?.homeDirectory;
+    const engineHome = getDaimonEngineDescriptor(engine)?.homeDirectory;
     const sessionsPath = home && engineHome !== undefined ? path.posix.join(home, engineHome, "sessions") : null;
+    const lineageVolumes = (realms) => (compiled.report.container?.persistent_mounts ?? [])
+        .filter((mount) => !isDaimonGatewayRealmMountId(mount.id) && daimonProfileRealmVolume(mount.id, realms) === undefined)
+        .map((mount) => mount.volume_name);
+    /**
+     * The profile's home login (`spawnfile auth login`) for this organization's
+     * fresh runtime home: seeded into it before the container starts, written
+     * back after it stops. Only the engine's login files cross; the home itself
+     * is the trial's own and is removed with it.
+     */
+    const homeLoginFor = (realms) => {
+        const files = HOME_LOGIN_FILES[engine];
+        const loginVolume = realms?.realms?.[engine]?.homeVolume;
+        if (!files || !loginVolume)
+            return undefined;
+        const mount = (compiled.report.container?.persistent_mounts ?? []).find((entry) => entry.mount_path === home);
+        if (!mount)
+            throw new SpawnfileError("validation_error", `The ${engine} runtime home of ${agentId} is not a persistent mount; its login cannot be seeded`);
+        return { files, homeMountPath: mount.mount_path, homeVolume: mount.volume_name, loginVolume };
+    };
+    const removeVolumes = async (volumes) => {
+        for (const volume of volumes)
+            await docker(["volume", "rm", "-f", volume]).catch(() => undefined);
+    };
     const dispose = async () => {
         await docker(["image", "rm", "-f", image]).catch(() => undefined);
         await rm(options.directory, { recursive: true, force: true });
@@ -54,33 +90,67 @@ export const prepareTrial = async (options) => {
         agentId, dispose, image,
         engines: agents.map(([, engine]) => engine),
         runtimeRoot: `${RUNTIME_INSTALL_ROOT}/daimon`,
+        login: async (realms, loginOptions = {}) => {
+            const homeLogin = homeLoginFor(realms);
+            const invocation = await createDockerRunInvocation(compiled, image, {
+                authProfile: realms, command: ["auth", engine, "login", "--config", instance.config_path],
+                containerName: `spawnfile-login-${slug}`, interactive: true
+            });
+            if (loginOptions.dryRun) {
+                await rm(invocation.supportDirectory, { recursive: true, force: true });
+                return [invocation.command, ...invocation.args];
+            }
+            try {
+                await executeDockerRunWithSupportCleanup(invocation, runDockerContainer);
+                if (homeLogin)
+                    await saveHomeLogin(docker, image, homeLogin);
+            }
+            finally {
+                await removeVolumes(lineageVolumes(realms));
+            }
+            return [invocation.command, ...invocation.args];
+        },
         boot: async (gateway, bootOptions = {}) => {
             const token = randomBytes(32).toString("base64url");
             const container = `spawnfile-trial-${slug}`;
             await mkdir(options.directory, { recursive: true });
             const envFilePath = path.join(options.directory, "boot.env");
-            // The boot inputs: control token, gateway URL and key. No login, no realm.
-            await writeFile(envFilePath, `${CONTROL_TOKEN_ENV}=${token}\n${DAIMON_GATEWAY_URL_ENV}=${gateway.url}\n${DAIMON_GATEWAY_KEY_ENV}=${gateway.key}\n`, { mode: 0o600 });
+            // The boot inputs: control token, plus the gateway URL and key. No gatewayed login, no
+            // gatewayed realm; only a volume-held login of the selected profile is mounted.
+            const gatewayEnv = gateway ? `${DAIMON_GATEWAY_URL_ENV}=${gateway.url}\n${DAIMON_GATEWAY_KEY_ENV}=${gateway.key}\n` : "";
+            await writeFile(envFilePath, `${CONTROL_TOKEN_ENV}=${token}\n${gatewayEnv}`, { mode: 0o600 });
             const invocation = await createDockerRunInvocation(compiled, image, {
-                containerName: container, deploymentName: slug, detach: true, envFilePath, network: gateway.network
+                authProfile: bootOptions.realms ?? null, containerName: container, deploymentName: slug, detach: true, envFilePath,
+                ...(gateway ? { network: gateway.network } : {})
             });
-            const volumes = (compiled.report.container?.persistent_mounts ?? [])
-                .filter((mount) => !isDaimonGatewayRealmMountId(mount.id)).map((mount) => mount.volume_name);
+            const volumes = lineageVolumes(bootOptions.realms);
+            const homeLogin = homeLoginFor(bootOptions.realms);
             const teardown = async () => {
-                await docker(["rm", "-f", container]).catch(() => undefined);
-                for (const volume of volumes)
-                    await docker(["volume", "rm", "-f", volume]).catch(() => undefined);
-                await rm(invocation.supportDirectory, { recursive: true, force: true });
-                await rm(envFilePath, { force: true });
+                try {
+                    // Stopped, not killed, so the engine finishes any login rewrite before it is saved.
+                    if (homeLogin)
+                        await docker(["stop", "--time", "10", container]).catch(() => undefined);
+                    await docker(["rm", "-f", container]).catch(() => undefined);
+                    if (homeLogin)
+                        await saveHomeLogin(docker, image, homeLogin);
+                }
+                finally {
+                    await removeVolumes(volumes);
+                    await rm(invocation.supportDirectory, { recursive: true, force: true });
+                    await rm(envFilePath, { force: true });
+                }
             };
             try {
+                if (homeLogin)
+                    await seedHomeLogin(docker, image, homeLogin);
                 await executeDockerRunWithSupportCleanup(invocation, runDockerContainer);
                 await rm(envFilePath, { force: true });
                 const target = { containerRef: container, dockerArgs: [], dockerCommand: "docker", imageRef: image, token };
                 const call = options.control ?? daimonHelperControlCall;
                 await waitFor(async () => {
-                    if (await docker(["inspect", "--format", "{{.State.Running}}", container]) !== "true") {
-                        const logs = await docker(["logs", "--tail", "30", container]).catch(() => "");
+                    // A restart means the organization already exited once (`--restart unless-stopped` hides it).
+                    if (await docker(["inspect", "--format", "{{.State.Running}} {{.RestartCount}}", container]) !== "true 0") {
+                        const logs = await docker(["logs", "--tail", "30", container], { combined: true }).catch(() => "");
                         throw new SpawnfileError("runtime_error", `trial organization exited before readiness: ${logs.replace(/\s+/gu, " ").slice(-600)}`);
                     }
                     return call(target, "GET", "/v2/availability").then((response) => response.status === 200, () => false);
@@ -88,12 +158,19 @@ export const prepareTrial = async (options) => {
                 return createBootedTrial({ agentId, call, container, docker, sessionsPath, target, teardown });
             }
             catch (error) {
-                await teardown();
+                // The boot failure is the error to report, not a teardown that follows it.
+                await teardown().catch(() => undefined);
                 throw error;
             }
         }
     };
 };
+/** Daimon's per-request stream sits beside the usage ledger. */
+const REQUEST_LEDGER = path.posix.join(path.posix.dirname(DAIMON_GROK_TURN_USAGE_LEDGER.filePath), "requests.jsonl");
+const readRequestToolCalls = async (docker, container, agentId, deliveryId) => {
+    const text = await docker(["exec", container, "cat", REQUEST_LEDGER]).catch(() => "");
+    return parseUsageRequestLedger(text).filter((row) => row.agent === agentId && row.wake === deliveryId).map((row) => row.tool_calls ?? null);
+};
 const readLedger = async (docker, container) => {
     const text = await docker(["exec", container, "cat", DAIMON_GROK_TURN_USAGE_LEDGER.filePath]).catch(() => "");
     return parseUsageLedger(text);
@@ -132,6 +209,7 @@ const createBootedTrial = (input) => {
                 acceptanceId: id, code: receipt.code ?? null, executionId: receipt.execution_id ?? null, usage,
                 state: TERMINAL.has(receipt.state ?? "") ? receipt.state : "timeout",
                 text: receipt.text ?? "",
+                requestToolCalls: await readRequestToolCalls(input.docker, input.container, input.agentId, options.deliveryId),
                 transcript: input.sessionsPath === null ? null : await readTranscript(input.docker, input.container, input.sessionsPath)
             };
         }

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

@@ -1,7 +1,9 @@
 /** Bounded Docker CLI call for trial lifecycle; stdout trimmed, stderr bounded into the error. */
+/** `combined` returns stderr after stdout (container logs write both). */
 export type TrialDocker = (args: readonly string[], options?: {
     timeoutMs?: number;
     stdin?: string;
+    combined?: boolean;
 }) => Promise<string>;
 export declare const createTrialDocker: (dockerCommand?: string) => TrialDocker;
 /** Poll `probe` until it resolves true, or fail after `timeoutMs`. */

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

@@ -3,7 +3,7 @@ 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(String(stdout).trim()));
+        : resolve(`${stdout}${options.combined ? stderr : ""}`.trim()));
     if (options.stdin !== undefined)
         child.stdin?.end(options.stdin);
     else

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

@@ -28,6 +28,11 @@ export interface TrainingGateway extends TrainingGatewayAccess {
     /** 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;
 /**

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

@@ -3,7 +3,7 @@ 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, daimonSourcePathForEngine } from "../../../runtime/daimon/runAuth.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";
@@ -15,6 +15,21 @@ 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`;
 /**
@@ -44,7 +59,7 @@ export const startTrainingGateway = async (options) => {
     const mounts = [];
     const realmVolumes = [];
     for (const descriptor of descriptors) {
-        const source = daimonSourcePathForEngine(descriptor.id, process.env, options.authProfile);
+        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);
@@ -73,7 +88,7 @@ export const startTrainingGateway = async (options) => {
         await waitFor(async () => {
             const state = await docker(["inspect", "--format", "{{.State.Running}}", container]);
             if (state !== "true") {
-                const logs = await docker(["logs", "--tail", "20", container]).catch(() => "");
+                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);

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

@@ -1,4 +1,8 @@
 export { TRAINING_TRIAL_LINEAGE_NAMESPACE, prepareTrial, type BootedTrial, type PreparedTrial, type TrialOptions, type TrialWake } from "./boot.js";
-export { startTrainingGateway, trainingGatewayRealmVolume, type TrainingGateway, type TrainingGatewayAccess, type TrainingGatewayOptions } from "./gateway.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

@@ -1,4 +1,8 @@
 export { TRAINING_TRIAL_LINEAGE_NAMESPACE, prepareTrial } from "./boot.js";
-export { startTrainingGateway, trainingGatewayRealmVolume } from "./gateway.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

@@ -1,6 +1,8 @@
 import type { ResolvedAuthProfile } from "../../../auth/index.js";
-import { type TrialWake } from "./boot.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;
@@ -8,25 +10,38 @@ export interface BootedTrialLauncherOptions {
     /** 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;
-    }): Promise<{
-        wake(text: string, options: {
-            deliveryId: string;
-            timeoutMs: number;
-            signal?: AbortSignal;
-        }): Promise<TrialWake>;
-        teardown(): Promise<void>;
-    }>;
-    /** Stops the run's gateway and removes its image and networks; the realm volume stays. */
+        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 trials: each boot compiles and starts the subject's
- * one-agent organization, and every trial shares the run's single auth
- * gateway, started from the first trial's image on first use.
+ * 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 {};