spawnfile 0.1.17 → 0.1.19

package/README.md

@@ -98,7 +98,7 @@ Portability is capability-specific: the compiler reports each feature as **suppo
 | Plan isolated agent training | [Paideia training handoff](specs/TRAINING.md) |
 | Find a detailed contract | [Specification index](specs/INDEX.md) |
 
-Spawnfile is part of [Noopolis](https://github.com/noopolis). [Moltnet](https://moltnet.dev) supplies messaging; [Daimon](https://github.com/noopolis/daimon) runs individual agents; [Simfile](https://simfile.org) builds simulation worlds around organizations. You can use Spawnfile on its own.
+Spawnfile is part of [Noopolis](https://github.com/noopolis). [Moltnet](https://moltnet.dev) supplies messaging; [Daimon](https://github.com/noopolis/daimon-harness) runs individual agents; [Simfile](https://simfile.org) builds simulation worlds around organizations. You can use Spawnfile on its own.
 
 ## License
 

package/dist/auth/importers.js

@@ -1,8 +1,10 @@
 import path from "node:path";
 import os from "node:os";
-import { fileExists, readUtf8File, writePrivateUtf8File } from "../filesystem/index.js";
+import { ensurePrivateDirectory, fileExists, readUtf8File, writeDurableFile, writePrivateUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { registerImportedAuth, setAuthProfileEnv } from "./profileStore.js";
+import { ensureAuthProfile, registerImportedAuth, setAuthProfileEnv } from "./profileStore.js";
+import { resolveImportedAuthDirectory } from "./paths.js";
+import { acquireTrainingGrokWritebackLock } from "./trainingGrokWritebackLock.js";
 const ENV_LINE_PATTERN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/;
 const CLAUDE_CODE_KEYCHAIN_SERVICE = "Claude Code-credentials";
 const stripWrappedQuotes = (value) => {
@@ -92,9 +94,23 @@ export const importGrokAuth = async (profileName, sourceDirectory) => {
     if (!(await fileExists(authFilePath))) {
         throw new SpawnfileError("validation_error", `Grok auth file does not exist: ${authFilePath}`);
     }
-    const { directory, profile } = await registerImportedAuth(profileName, "grok");
-    await writePrivateUtf8File(path.join(directory, "auth.json"), await readUtf8File(authFilePath));
-    return profile;
+    await ensureAuthProfile(profileName);
+    const directory = resolveImportedAuthDirectory(profileName, "grok");
+    await ensurePrivateDirectory(path.dirname(directory));
+    await ensurePrivateDirectory(directory);
+    const destination = path.join(directory, "auth.json");
+    const release = await acquireTrainingGrokWritebackLock(destination).catch(() => {
+        throw new SpawnfileError("validation_error", "Grok credential lock unavailable; retry import after the active writer finishes");
+    });
+    try {
+        const content = await readUtf8File(authFilePath);
+        const { profile } = await registerImportedAuth(profileName, "grok");
+        await writeDurableFile(destination, content);
+        return profile;
+    }
+    finally {
+        release();
+    }
 };
 export const importClaudeCodeAuth = async (profileName, sourceDirectory, options = {}) => {
     const resolvedSource = resolveClaudeSourceDirectory(sourceDirectory);

package/dist/auth/index.d.ts

@@ -12,3 +12,4 @@ export * from "./targetSecretSourceLifecycle.js";
 export * from "./targetSecretSourceResolver.js";
 export { stageTrainingAuth } from "./trainingAuth.js";
 export type { TrainingAuthStageOptions, TrainingAuthProvider } from "./trainingAuth.js";
+export { writeBackTrainingGrokCredential } from "./trainingGrokWriteback.js";

package/dist/auth/index.js

@@ -11,3 +11,4 @@ export * from "./credentialWorldBindings.js";
 export * from "./targetSecretSourceLifecycle.js";
 export * from "./targetSecretSourceResolver.js";
 export { stageTrainingAuth } from "./trainingAuth.js";
+export { writeBackTrainingGrokCredential } from "./trainingGrokWriteback.js";

package/dist/auth/profileStore.js

@@ -99,7 +99,10 @@ export const registerImportedAuth = async (profileName, kind) => {
     const current = (await loadAuthProfile(profileName)) ?? (await ensureAuthProfile(profileName));
     const importDirectory = resolveImportedAuthDirectory(profileName, kind);
     await ensurePrivateDirectory(path.dirname(importDirectory));
-    await removeDirectory(importDirectory);
+    // Grok import and writeback share a persistent lock inside this directory.
+    // Removing it would let another writer lock a different inode concurrently.
+    if (kind !== "grok")
+        await removeDirectory(importDirectory);
     await ensurePrivateDirectory(importDirectory);
     const nextProfile = {
         env: { ...current.env },

package/dist/auth/trainingGrokWriteback.d.ts

@@ -0,0 +1,4 @@
+/** Reads only private, bounded, canonical leaves. Errors never include credential bytes. */
+export declare const readTrainingGrokLeaf: (file: string) => Promise<Buffer>;
+/** A settled journal proves rotation; native expiry orders credentials across independent realms. */
+export declare const writeBackTrainingGrokCredential: (profile: string, candidate: string, journalFile: string) => Promise<boolean>;

package/dist/auth/trainingGrokWriteback.js

@@ -0,0 +1,119 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { acquireTrainingGrokWritebackLock } from "./trainingGrokWritebackLock.js";
+const failure = () => Error("Training Grok credential writeback failed");
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Reads only private, bounded, canonical leaves. Errors never include credential bytes. */
+export const readTrainingGrokLeaf = async (file) => {
+    if (await realpath(file) !== path.resolve(file))
+        throw failure();
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.nlink !== 1n || (before.mode & 511n) !== 384n || before.size < 2n || before.size > 65536n)
+            throw failure();
+        const bytes = Buffer.alloc(Number(before.size) + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const result = await handle.read(bytes, length, bytes.length - length, null);
+            if (!result.bytesRead)
+                break;
+            length += result.bytesRead;
+        }
+        const after = await handle.stat({ bigint: true });
+        if (BigInt(length) !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs) {
+            bytes.fill(0);
+            throw failure();
+        }
+        return bytes.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+};
+const expiry = (bytes) => {
+    try {
+        const rows = Object.entries(JSON.parse(bytes.toString("utf8")))
+            .filter(([key]) => /^https:\/\/auth\.x\.ai::/u.test(key)).map(([, value]) => value);
+        const row = rows[0];
+        if (rows.length !== 1 || typeof row?.key !== "string" || !row.key.trim() || typeof row.refresh_token !== "string" || !row.refresh_token.trim() || typeof row.expires_at !== "string")
+            throw failure();
+        const value = Date.parse(row.expires_at);
+        if (!Number.isFinite(value))
+            throw failure();
+        return value;
+    }
+    catch {
+        throw failure();
+    }
+};
+/** A settled journal proves rotation; native expiry orders credentials across independent realms. */
+export const writeBackTrainingGrokCredential = async (profile, candidate, journalFile) => {
+    const release = await acquireTrainingGrokWritebackLock(profile, 30_000).catch(() => { throw failure(); });
+    const temporary = path.join(path.dirname(profile), `.grok-writeback-${randomUUID()}`);
+    let current, renewed, journalBytes;
+    try {
+        current = await readTrainingGrokLeaf(profile);
+        renewed = await readTrainingGrokLeaf(candidate);
+        if (digest(current) === digest(renewed))
+            return false;
+        journalBytes = await readTrainingGrokLeaf(journalFile);
+        const journal = JSON.parse(journalBytes.toString("utf8"));
+        if (journal.version !== "noopolis.daimon.broker-credential-journal.v1" || journal.state !== "promoted" ||
+            !Number.isSafeInteger(journal.generation) || journal.generation < 1 ||
+            typeof journal.sourceDigest !== "string" || !/^[a-f0-9]{64}$/u.test(journal.sourceDigest) || journal.promotedDigest !== digest(renewed))
+            throw failure();
+        const renewedExpiry = expiry(renewed), currentExpiry = expiry(current);
+        const ancestors = journal.ancestorDigests ?? [];
+        if (!Array.isArray(ancestors) || ancestors.length > 900 || ancestors.some((entry) => typeof entry !== "string" || !/^[a-f0-9]{64}$/u.test(entry)))
+            throw failure();
+        if (renewedExpiry < currentExpiry || (renewedExpiry === currentExpiry && journal.sourceDigest !== digest(current) && !ancestors.includes(digest(current))))
+            return false;
+        const identity = await lstat(profile, { bigint: true });
+        const output = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        try {
+            await output.writeFile(renewed);
+            await output.sync();
+        }
+        finally {
+            await output.close();
+        }
+        // Import and writeback hold the same lock through publication. This check
+        // also detects non-cooperating edits made before validation, not after it.
+        const check = await readTrainingGrokLeaf(profile);
+        try {
+            const now = await lstat(profile, { bigint: true });
+            if (digest(check) !== digest(current) || now.ino !== identity.ino || now.dev !== identity.dev || now.ctimeNs !== identity.ctimeNs)
+                throw failure();
+        }
+        finally {
+            check.fill(0);
+        }
+        await rename(temporary, profile);
+        const directory = await open(path.dirname(profile), constants.O_RDONLY);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        return true;
+    }
+    catch {
+        throw failure();
+    }
+    finally {
+        current?.fill(0);
+        renewed?.fill(0);
+        journalBytes?.fill(0);
+        try {
+            await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+                throw error; });
+        }
+        finally {
+            release();
+        }
+    }
+};

package/dist/auth/trainingGrokWritebackLock.d.ts

@@ -0,0 +1,5 @@
+/** A persistent, non-secret SQLite file owns the OS lock, never the directory.
+ * SQLite releases it on process death. Do not unlink the file/directory: another
+ * writer may already have the same inode open. Legacy empty lock dirs are safe.
+ */
+export declare const acquireTrainingGrokWritebackLock: (profile: string, timeoutMs?: number) => Promise<() => void>;

package/dist/auth/trainingGrokWritebackLock.js

@@ -0,0 +1,56 @@
+import { closeSync, constants, openSync } from "node:fs";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout } from "node:timers/promises";
+/** A persistent, non-secret SQLite file owns the OS lock, never the directory.
+ * SQLite releases it on process death. Do not unlink the file/directory: another
+ * writer may already have the same inode open. Legacy empty lock dirs are safe.
+ */
+export const acquireTrainingGrokWritebackLock = async (profile, timeoutMs = 0) => {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw Error("Invalid writeback lock timeout");
+    const root = `${profile}.training-writeback.lock`;
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const directory = await lstat(root);
+    if (await realpath(root) !== path.resolve(root) || !directory.isDirectory() ||
+        directory.uid !== process.getuid?.() || (directory.mode & 0o777) !== 0o700)
+        throw Error("Unsafe writeback lock");
+    const file = path.join(root, "lock.sqlite");
+    // Closing an independently opened fd can drop this process's POSIX locks.
+    // Only open when creating; SQLite owns every fd for an existing lock file.
+    // Creation and close must not yield to another acquisition in this process.
+    try {
+        closeSync(openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600));
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const entry = await lstat(file);
+    if (!entry.isFile() || entry.nlink !== 1 || entry.uid !== process.getuid?.() || (entry.mode & 0o777) !== 0o600)
+        throw Error("Unsafe writeback lock");
+    const { DatabaseSync } = await import("node:sqlite");
+    const database = new DatabaseSync(file);
+    const deadline = performance.now() + timeoutMs;
+    try {
+        // SQLite's synchronous busy timeout would block a same-process holder
+        // from finishing its async publication. Yield between acquisition attempts.
+        database.exec("PRAGMA busy_timeout = 0");
+        for (;;) {
+            try {
+                database.exec("BEGIN EXCLUSIVE");
+                return () => { database.close(); };
+            }
+            catch (error) {
+                const remaining = deadline - performance.now();
+                if (error.errcode !== 5 || remaining <= 0)
+                    throw error;
+                await setTimeout(Math.min(25, remaining));
+            }
+        }
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+};

package/dist/cli/authCommands.js

@@ -5,6 +5,7 @@ import { createCanonicalTargetSecretSourceJson } from "../auth/targetSecretSourc
 import { renderSimfileWorldBindings } from "../compiler/worldBindings.js";
 import { MAX_TARGET_SECRET_SOURCE_SECRET_BYTES, TARGET_SECRET_SOURCE_ERROR } from "../auth/targetSecretSourceRecordCommon.js";
 import { createTargetSecretSourceReceiptBytes, readBoundedTargetSecretStdin, readTargetSecretSourceGrantRequestFile, readTargetSecretSourceRequestFile } from "./targetSecretSourceInput.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const formatAuthProfileSummary = (profile) => {
     const envKeys = Object.keys(profile.env).sort();
     const importedKinds = Object.keys(profile.imports).sort();
@@ -112,14 +113,15 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
         .description("Provision auth material a project requires into a profile")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-p, --profile <name>", "Auth profile name", "default")
-        .option("--env-file <file>", "Path to an env file with model keys and runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file with model keys and runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--claude-from <directory>", "Source Claude Code config directory")
         .option("--codex-from <directory>", "Source Codex config directory")
         .action(async (inputPath, options) => {
         const profile = await handlers.syncProjectAuth(inputPath, {
             claudeCodeDirectory: options.claudeFrom,
             codexDirectory: options.codexFrom,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             profileName: options.profile
         });
         emitLines(streams, formatAuthProfileSummary(profile));
@@ -136,10 +138,12 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
         .command("provision")
         .description("Provision a declarative batch of target credentials")
         .argument("<request-file>", "Secret-free credential provisioning request JSON")
-        .option("--env-file <path>", "Create a 0600 environment file")
+        .addOption(runtimeEnvFileOption("Create a 0600 environment file", "path"))
+        .addOption(envFileAliasOption("path"))
         .option("--world-bindings <path>", "Create a resolved world-bindings artifact")
         .option("--resolved-grants <path>", "Resolved world grants used to derive world bindings")
         .action((requestFile, options) => targetSecretAction(async () => {
+        const envFilePath = resolveEnvFileOption(options);
         let materials;
         try {
             const request = await readCredentialProvisioningRequestFile(requestFile);
@@ -153,11 +157,11 @@ export const registerAuthCommands = (program, handlers, streams, stdin) => {
                 await handlers.importCodexAuth(request.model_engine_auth.profile, request.model_engine_auth.from);
                 modelEngineAuth = true;
             }
-            const envFile = options.envFile === undefined
+            const envFile = envFilePath === undefined
                 ? undefined
                 : await writeProvisionedEnvFile({
                     materials,
-                    path: options.envFile,
+                    path: envFilePath,
                     receipt: provisioned.receipt
                 });
             let worldBindingsDigest;

package/dist/cli/compileBuildCommands.js

@@ -16,8 +16,10 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-o, --out <directory>", "Output directory")
         .option("--world-bindings <file>", "Path to a versioned world-bindings artifact")
+        .option("--release", "Build workspace bundles only from clean committed inputs")
         .action(async (inputPath, options) => {
         const result = await handlers.compileProject(inputPath, {
+            ...(options.release ? { bundleIdentity: "release" } : {}),
             outputDirectory: options.out,
             worldBindingsPath: options.worldBindings
         });
@@ -33,8 +35,10 @@ export const registerCompileBuildCommands = (program, handlers, streams) => {
         .option("--docker-command <command>", "Docker command")
         .option("-o, --out <directory>", "Output directory")
         .option("-t, --tag <image>", "Docker image tag")
+        .option("--release", "Build workspace bundles only from clean committed inputs")
         .action(async (inputPath, options) => {
         const result = await handlers.buildProject(inputPath, {
+            ...(options.release ? { bundleIdentity: "release" } : {}),
             dockerContext: options.context,
             dockerCommand: options.dockerCommand,
             imageTag: options.tag,

package/dist/cli/devCommands.js

@@ -1,4 +1,5 @@
 import { InvalidArgumentError } from "commander";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const parsePositiveIntegerOption = (value) => {
     if (!/^[1-9]\d*$/u.test(value)) {
         throw new InvalidArgumentError("must be a positive integer");
@@ -16,7 +17,8 @@ export const registerDevCommands = (program, handlers, streams) => {
         .option("--context <name>", "Docker context for the deployment target")
         .option("--deployment <name>", "Detached deployment record name")
         .option("--docker-command <command>", "Docker command")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file for runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--name <container>", "Docker container name")
         .option("-o, --out <directory>", "Dev output directory")
         .option("-t, --tag <image>", "Docker image tag")
@@ -28,7 +30,7 @@ export const registerDevCommands = (program, handlers, streams) => {
             deploymentName: options.deployment,
             dockerCommand: options.dockerCommand,
             dockerContext: options.context,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             imageTag: options.tag,
             outputDirectory: options.out
         });

package/dist/cli/downCommand.d.ts

@@ -4,6 +4,7 @@ import type { CliHandlers, CliStreams } from "./runCli.js";
 export interface DownOptions {
     compiled?: string;
     deployment: string;
+    discardRecordedMemory?: boolean;
     dockerCommand?: string;
     exportTo?: string;
     force?: boolean;
@@ -20,6 +21,7 @@ export declare const createDownLifecyclePolicy: (options: DownOptions) => {
     reader_image: string | null;
     remove_volumes: boolean;
     timeout_ms: number | null;
+    discard_recorded_memory?: boolean | undefined;
 };
 export declare const createDownLifecycleInvocation: (id: string, compiledOutputDirectory: string, options: DownOptions, correlation: DeploymentLifecycleCorrelation) => LifecycleInvocation;
 export declare const registerDownCommand: (program: Command, handlers: CliHandlers, streams: CliStreams) => void;

package/dist/cli/downCommand.js

@@ -5,6 +5,7 @@ import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
 import { canonicalLifecycleJson } from "../deployment/lifecycleCompletionContracts.js";
 import { createLifecycleInvocation, requireMachineLifecycle, runMachineLifecycle, } from "./lifecycleMachine.js";
 export const createDownLifecyclePolicy = (options) => ({
+    ...(options.discardRecordedMemory ? { discard_recorded_memory: true } : {}),
     docker_command: options.dockerCommand ?? null,
     export_to: options.exportTo ? path.resolve(options.exportTo) : null,
     force: options.force ?? false,
@@ -52,6 +53,7 @@ export const registerDownCommand = (program, handlers, streams) => {
         .option("--docker-command <command>", "Docker command")
         .option("--export-to <directory>", "Export first, then tear down")
         .option("--force", "Discard un-exported artifacts")
+        .option("--discard-recorded-memory", "Allow --volumes to discard memory ledgers used by recording agents")
         .option("--reader-image <image>", "Image used to read named volumes during auto export")
         .option("--timeout <ms>", "Bound each Docker call in milliseconds")
         .option("--volumes", "Also remove this deployment's own named volumes (author-declared names are shared project state and are always skipped)")
@@ -67,6 +69,7 @@ export const registerDownCommand = (program, handlers, streams) => {
             const receipt = await handlers.downDeployment({
                 compiledOutputDirectory: compiled,
                 deploymentName: options.deployment,
+                discardRecordedMemory: options.discardRecordedMemory,
                 dockerCommand: options.dockerCommand,
                 exportTo: options.exportTo,
                 force: options.force,

package/dist/cli/envFileOption.d.ts

@@ -0,0 +1,18 @@
+import { Option } from "commander";
+/**
+ * Node reads `--env-file` from the WHOLE argv, script arguments included
+ * (verified on 22.23 and 24.21): `node dist/cli/index.js up --env-file x`
+ * dies with `node: x: not found` (exit 9) before Spawnfile runs when x is
+ * missing or unreadable, and a `NODE_OPTIONS=` line in x is applied to the
+ * Spawnfile process itself. `--runtime-env-file` is the spelling Node does not
+ * claim; `--env-file` stays as a hidden alias for existing callers.
+ */
+export declare const RUNTIME_ENV_FILE_FLAG = "--runtime-env-file";
+export interface EnvFileOptions {
+    envFile?: string;
+    runtimeEnvFile?: string;
+}
+export declare const runtimeEnvFileOption: (description: string, valueName?: string) => Option;
+export declare const envFileAliasOption: (valueName?: string) => Option;
+/** One env file: either spelling, never two different files. */
+export declare const resolveEnvFileOption: (options: EnvFileOptions) => string | undefined;

package/dist/cli/envFileOption.js

@@ -0,0 +1,20 @@
+import { Option } from "commander";
+import { SpawnfileError } from "../shared/index.js";
+/**
+ * Node reads `--env-file` from the WHOLE argv, script arguments included
+ * (verified on 22.23 and 24.21): `node dist/cli/index.js up --env-file x`
+ * dies with `node: x: not found` (exit 9) before Spawnfile runs when x is
+ * missing or unreadable, and a `NODE_OPTIONS=` line in x is applied to the
+ * Spawnfile process itself. `--runtime-env-file` is the spelling Node does not
+ * claim; `--env-file` stays as a hidden alias for existing callers.
+ */
+export const RUNTIME_ENV_FILE_FLAG = "--runtime-env-file";
+export const runtimeEnvFileOption = (description, valueName = "file") => new Option(`${RUNTIME_ENV_FILE_FLAG} <${valueName}>`, description);
+export const envFileAliasOption = (valueName = "file") => new Option(`--env-file <${valueName}>`, `Alias of ${RUNTIME_ENV_FILE_FLAG}`).hideHelp();
+/** One env file: either spelling, never two different files. */
+export const resolveEnvFileOption = (options) => {
+    if (options.runtimeEnvFile !== undefined && options.envFile !== undefined && options.runtimeEnvFile !== options.envFile) {
+        throw new SpawnfileError("validation_error", `${RUNTIME_ENV_FILE_FLAG} and --env-file name different files; pass one`);
+    }
+    return options.runtimeEnvFile ?? options.envFile;
+};

package/dist/cli/lifecycleCommands.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from "commander";
 import type { CliHandlers, CliStreams } from "./runCli.js";
-export declare const registerLifecycleCommands: (program: Command, handlers: CliHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>) => void;
+export declare const registerLifecycleCommands: (program: Command, handlers: CliHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>, setExitCode?: (code: number) => void) => void;

package/dist/cli/lifecycleCommands.js

@@ -1,12 +1,14 @@
 import { registerCompileBuildCommands } from "./compileBuildCommands.js";
 import { registerDownCommand } from "./downCommand.js";
 import { registerLifecyclePlanningCommands } from "./lifecyclePlanningCommands.js";
+import { registerReleaseCommand } from "./releaseCommand.js";
 import { registerRunPublishCommands } from "./runPublishCommands.js";
 import { registerUpCommand } from "./upCommand.js";
-export const registerLifecycleCommands = (program, handlers, streams, stdin) => {
+export const registerLifecycleCommands = (program, handlers, streams, stdin, setExitCode = () => undefined) => {
     registerLifecyclePlanningCommands(program, streams, stdin);
     registerCompileBuildCommands(program, handlers, streams);
     registerRunPublishCommands(program, handlers, streams);
     registerUpCommand(program, handlers, streams);
     registerDownCommand(program, handlers, streams);
+    registerReleaseCommand(program, streams, setExitCode);
 };

package/dist/cli/lifecyclePlan.d.ts

@@ -17,6 +17,7 @@ export declare const lifecyclePlanRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
     version: z.ZodLiteral<"spawnfile.lifecycle-plan-request.v1">;
 }, z.core.$strict>, z.ZodObject<{
     deployment: z.ZodString;
+    discard_recorded_memory: z.ZodOptional<z.ZodBoolean>;
     export_to: z.ZodNullable<z.ZodString>;
     force: z.ZodBoolean;
     operation: z.ZodLiteral<"down">;

package/dist/cli/lifecyclePlan.js

@@ -35,6 +35,7 @@ export const lifecyclePlanRequestSchema = z.discriminatedUnion("operation", [
         .object({
         ...common,
         deployment: z.string().min(1).max(128),
+        discard_recorded_memory: z.boolean().optional(),
         export_to: z.string().min(1).max(4096).nullable(),
         force: z.boolean(),
         operation: z.literal("down"),
@@ -225,6 +226,7 @@ export const createPlannedLifecycleInvocation = async (request) => {
     const options = {
         compiled: request.compiled ?? undefined,
         deployment: request.deployment,
+        discardRecordedMemory: request.discard_recorded_memory,
         dockerCommand: request.docker_command ?? undefined,
         exportTo: request.export_to ?? undefined,
         force: request.force,

package/dist/cli/paideiaDelegation.d.ts

@@ -1,7 +1,8 @@
-import { type TrainingContext } from "../compiler/training/index.js";
+import { type TrainingContext, type TrainingExecution } from "../compiler/training/index.js";
 import type { CliStreams } from "./runCli.js";
 export interface DelegatePaideiaTrainingOptions {
     context: TrainingContext;
+    execution?: TrainingExecution;
     command: string;
     args: readonly string[];
     dryRun: boolean;

package/dist/cli/paideiaDelegation.js

@@ -171,12 +171,13 @@ export const delegatePaideiaTraining = async (options) => {
         throw failure("--repair-witness requires --repair-measurements");
     if (options.trainingConfig) {
         const config = await readBoundedJson(options.trainingConfig);
-        // v2 and v3 are both declarative preparations; a v3 *launch* config (already lowered, with `inputs`) goes straight to Docker.
-        if (config.version === "spawnfile.training-container.v2" || (config.version === "spawnfile.training-container.v3" && config.image !== undefined)) {
-            if (options.trainingImage)
+        // Image declarations go through preparation; lowered launch configurations go straight to Docker.
+        if (config.version === "spawnfile.training-container.v2" || (["spawnfile.training-container.v3", "spawnfile.training-container.v4"].includes(String(config.version)) && config.image !== undefined)) {
+            if (options.trainingImage && !options.execution)
                 throw failure("V2 owns its image declaration; --training-image is only for v1");
             const prepared = await prepareTraining({ configPath: options.trainingConfig, context: options.context, args: options.args,
                 repairMeasurements: options.repairMeasurements, repairWitness: options.repairWitness,
+                execution: options.execution, outputOverride: options.execution?.output, imageOverride: options.execution ? options.trainingImage : undefined,
                 dryRun: options.dryRun, process: runTrainingDocker, timeoutMs: options.timeoutMs, signal: options.signal, streams: options.streams });
             if (!("dryRun" in prepared))
                 return launchTrainingContainer({ ...prepared,
@@ -191,7 +192,7 @@ export const delegatePaideiaTraining = async (options) => {
         if (!options.trainingImage || !options.trainingConfig)
             throw failure("Actual training requires --training-image and --training-config; host execution is disabled");
         return launchTrainingContainer({ image: options.trainingImage, configPath: options.trainingConfig,
-            context: options.context, args: options.args, timeoutMs: options.timeoutMs, streams: options.streams, signal: options.signal });
+            context: options.context, args: options.args, execution: options.execution, timeoutMs: options.timeoutMs, streams: options.streams, signal: options.signal });
     }
     if (process.platform === "win32")
         throw failure("Paideia delegation requires POSIX process-group supervision");

package/dist/cli/recordCommands.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+import { type RecordingDeploymentHandlers } from "../recording/index.js";
+import type { CliStreams } from "./runCli.js";
+import { type UsageCommandLiveHandlers } from "./usageCommandLive.js";
+export interface RecordSyncOptions {
+    deployment?: string;
+    out?: string;
+    dockerCommand?: string;
+    timeout?: string;
+}
+export type RecordCommandHandlers = UsageCommandLiveHandlers & RecordingDeploymentHandlers;
+export declare const executeRecordSyncCommand: (inputPath: string, options: RecordSyncOptions, handlers?: RecordCommandHandlers) => Promise<{
+    exitCode: 0 | 1 | 2;
+    output?: string;
+    error?: string;
+}>;
+export declare const registerRecordCommands: (program: Command, streams: CliStreams, setExitCode: (code: 0 | 1 | 2) => void, handlers?: RecordCommandHandlers) => void;

package/dist/cli/recordCommands.js

@@ -0,0 +1,43 @@
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { syncDeploymentMoments } from "../recording/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, errorExitCode } from "../shared/index.js";
+import { selectUsageDeployment } from "./usageCommandLive.js";
+import { resolveUsageDeploymentSource } from "./usageDeploymentSource.js";
+export const executeRecordSyncCommand = async (inputPath, options, handlers = {}) => {
+    try {
+        const timeoutMs = options.timeout === undefined ? undefined : Number(options.timeout);
+        if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+            return { exitCode: 2, error: "--timeout must be a positive number of milliseconds" };
+        }
+        const outputDirectory = resolveProjectOutputDirectory(inputPath, options.out, DEFAULT_OUTPUT_DIRECTORY);
+        const source = await resolveUsageDeploymentSource(inputPath, options, handlers, outputDirectory);
+        const records = await source.loader(source.outputDirectory);
+        const record = selectUsageDeployment(records, options.deployment);
+        if ("error" in record)
+            return { exitCode: 2, error: record.error.replace("spawnfile usage", "spawnfile record sync") };
+        const recordPath = records.find((entry) => entry.record === record).path;
+        const result = await syncDeploymentMoments({ record, recordPath, timeoutMs, dockerCommand: options.dockerCommand }, handlers);
+        return {
+            exitCode: result.failures.length ? 1 : 0,
+            output: `Records: ${result.written} written / ${result.skipped} skipped / ${result.nonExact} non-exact`,
+            ...((result.failures.length || result.warnings.length) ? { error: [...result.failures, ...new Set(result.warnings)].join("\n") } : {})
+        };
+    }
+    catch (error) {
+        return { exitCode: errorExitCode(error), error: error instanceof Error ? error.message : String(error) };
+    }
+};
+export const registerRecordCommands = (program, streams, setExitCode, handlers = {}) => {
+    program.command("record").description("Compose training moment records from deployed wake evidence")
+        .command("sync").argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--deployment <name>", "Deployment record name").option("--out <dir>", "Compile output directory")
+        .option("--docker-command <command>", "Docker command").option("--timeout <ms>", "Bound Docker reads in milliseconds")
+        .action(async (inputPath, options) => {
+        const result = await executeRecordSyncCommand(inputPath, options, handlers);
+        setExitCode(result.exitCode);
+        if (result.error)
+            streams.stderr(result.error);
+        if (result.output)
+            streams.stdout(result.output);
+    });
+};

package/dist/cli/releaseCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import { type ReleaseDependencies } from "../release/index.js";
+import type { CliStreams } from "./runCli.js";
+/** `90s`, `30m`, `2h`, `500ms`. A bare number is refused: the unit is never guessed. */
+export declare const parseReleaseDuration: (value: string, flag: string) => number;
+export declare const registerReleaseCommand: (program: Command, streams: CliStreams, setExitCode: (code: number) => void, dependencies?: () => ReleaseDependencies) => void;