spawnfile 0.1.17 → 0.1.19

package/dist/cli/releaseCommand.js

@@ -0,0 +1,91 @@
+import { createDefaultReleaseDependencies, releaseExitCode, resolveNotifierConfig, resolvePostDeployHook, runRelease } from "../release/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
+const UNITS = { h: 3_600_000, m: 60_000, ms: 1, s: 1_000 };
+/** `90s`, `30m`, `2h`, `500ms`. A bare number is refused: the unit is never guessed. */
+export const parseReleaseDuration = (value, flag) => {
+    const match = /^(\d+)(ms|s|m|h)$/u.exec(value.trim());
+    if (!match)
+        throw new SpawnfileError("validation_error", `${flag} must be a duration like 90s, 30m or 2h`);
+    const ms = Number(match[1]) * UNITS[match[2]];
+    if (!Number.isSafeInteger(ms) || ms <= 0)
+        throw new SpawnfileError("validation_error", `${flag} must be positive`);
+    return ms;
+};
+export const registerReleaseCommand = (program, streams, setExitCode, dependencies = createDefaultReleaseDependencies) => {
+    program
+        .command("release")
+        .description("Build and deploy only when the image inputs changed, draining running turns first")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--deployment <name>", "Detached deployment to release into")
+        .addOption(runtimeEnvFileOption("Runtime secrets; must set SPAWNFILE_DAIMON_CONTROL_TOKEN to drain"))
+        .addOption(envFileAliasOption())
+        .option("--auth-profile <name>", "Local Spawnfile auth profile")
+        .option("--context <name>", "Docker context for the build and deployment target")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Compile output directory")
+        .option("--image-repository <name>", "Repository for release image tags (default spawnfile-<project>)")
+        .option("--drain-timeout <duration>", "How long running turns may take to finish before the release is abandoned", "30m")
+        .option("--no-drain", "Deploy without draining (kills in-flight turns)")
+        .option("--force", "Release even when the running identity is unchanged")
+        .option("--dev-inputs", "Hash working-tree bundle inputs instead of requiring a clean commit")
+        .option("--notify-command <path>", "Executable run on failure; receives the notification JSON on stdin")
+        .option("--notify-webhook-env <name>", "Environment variable holding an https URL to POST the notification to")
+        .option("--notify-deferred-after <duration>", "Notify once when a release has been deferred this long", "24h")
+        .option("--post-deploy-command <path>", "Executable run (no shell) on the new container's host after it settled; non-zero fails the release")
+        .option("--post-deploy-arg <arg>", "Argument for --post-deploy-command (repeatable)", (value, previous = []) => [...previous, value])
+        .option("--post-deploy-timeout <duration>", "How long --post-deploy-command may run", "10m")
+        .action(async (inputPath, options) => {
+        let notifier;
+        try {
+            notifier = resolveNotifierConfig(options);
+        }
+        catch (error) {
+            throw new SpawnfileError("validation_error", error.message);
+        }
+        const envFile = resolveEnvFileOption(options);
+        let postDeploy;
+        try {
+            postDeploy = resolvePostDeployHook({ ...options, timeoutMs: parseReleaseDuration(options.postDeployTimeout, "--post-deploy-timeout") });
+        }
+        catch (error) {
+            throw new SpawnfileError("validation_error", error.message);
+        }
+        const drainTimeoutMs = parseReleaseDuration(options.drainTimeout, "--drain-timeout");
+        const notifyDeferredAfterMs = parseReleaseDuration(options.notifyDeferredAfter, "--notify-deferred-after");
+        const abort = new AbortController();
+        const onSignal = () => abort.abort();
+        process.once("SIGTERM", onSignal);
+        process.once("SIGINT", onSignal);
+        try {
+            const request = {
+                authProfileName: options.authProfile ?? null,
+                bundleIdentity: options.devInputs ? "dev" : "release",
+                deployment: options.deployment,
+                dockerCommand: options.dockerCommand ?? "docker",
+                ...(options.context ? { dockerContext: options.context } : {}),
+                drain: options.drain,
+                drainPollMs: 5_000,
+                drainTimeoutMs,
+                envFileEnv: {},
+                ...(envFile ? { envFilePath: envFile } : {}),
+                force: options.force === true,
+                ...(options.imageRepository ? { imageRepository: options.imageRepository } : {}),
+                inputPath,
+                log: streams.stdout,
+                notifier,
+                notifyDeferredAfterMs,
+                ...(options.out ? { outputDirectory: options.out } : {}),
+                postDeploy,
+                settle: { pollMs: 5_000, polls: 36, stablePolls: 3 },
+                signal: abort.signal
+            };
+            const outcome = await runRelease(request, dependencies());
+            setExitCode(releaseExitCode(outcome));
+        }
+        finally {
+            process.off("SIGTERM", onSignal);
+            process.off("SIGINT", onSignal);
+        }
+    });
+};

package/dist/cli/runCli.d.ts

@@ -1,5 +1,5 @@
 import { importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, initProject, listInitTemplates, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, createTrainingPlan, loadTrainingProject, resolveTrainingPlan, materializeTrainingMoment, lowerTrainingExecution, allocateTrainingOutputParent, initProject, listInitTemplates, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
 import { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
 import { consumeImageUp } from "../distribution/index.js";
 import { createDockerProbeGateway, downDeployment, exportRunArtifacts, inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords } from "../deployment/index.js";
@@ -16,6 +16,12 @@ export interface CliRenderEnvironment {
 }
 export interface CliHandlers {
     createTrainingContext: typeof createTrainingContext;
+    createTrainingPlan: typeof createTrainingPlan;
+    lowerTrainingExecution: typeof lowerTrainingExecution;
+    allocateTrainingOutputParent: typeof allocateTrainingOutputParent;
+    loadTrainingProject: typeof loadTrainingProject;
+    resolveTrainingPlan: typeof resolveTrainingPlan;
+    materializeTrainingMoment: typeof materializeTrainingMoment;
     delegatePaideiaTraining: typeof delegatePaideiaTraining;
     buildCompilePlan: typeof buildCompilePlan;
     buildOrganizationView: typeof buildOrganizationView;

package/dist/cli/runCli.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, initProject, listInitTemplates, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, createTrainingPlan, loadTrainingProject, resolveTrainingPlan, materializeTrainingMoment, lowerTrainingExecution, allocateTrainingOutputParent, initProject, listInitTemplates, preflightCompilePlan, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
 import { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
 import { consumeImageUp } from "../distribution/index.js";
 import { createDockerProbeGateway, downDeployment, exportRunArtifacts, inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords } from "../deployment/index.js";
@@ -18,8 +18,10 @@ import { registerRuntimeCommands } from "./runtimeCommands.js";
 import { registerSurfaceCommands } from "./surfaceCommands.js";
 import { registerStatusCommand } from "./statusCommand.js";
 import { registerUsageCommand } from "./usageCommand.js";
+import { registerRecordCommands } from "./recordCommands.js";
 import { registerProductionTargetCommands } from "./targetProductionCommands.js";
 import { registerViewCommand } from "./viewCommand.js";
+import { registerVolumeCommands } from "./volumeCommands.js";
 import { registerTrainCommand } from "./trainCommand.js";
 import { delegatePaideiaTraining } from "./paideiaDelegation.js";
 const packageJsonPath = new URL("../../package.json", import.meta.url);
@@ -37,7 +39,7 @@ const createDefaultRenderEnvironment = () => ({
     stdoutIsTty: process.stdout.isTTY === true
 });
 const createDefaultHandlers = () => ({
-    createTrainingContext, delegatePaideiaTraining,
+    createTrainingContext, createTrainingPlan, loadTrainingProject, resolveTrainingPlan, materializeTrainingMoment, lowerTrainingExecution, allocateTrainingOutputParent, delegatePaideiaTraining,
     buildCompilePlan, buildOrganizationView, buildProject, compileProject, publishProject,
     addAgentProject, addProjectModelFallback, addProjectSurface,
     addSubagentProject, addTeamProject, clearProjectModelFallbacks,
@@ -118,7 +120,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
         },
         writeOut: (message) => writeCommanderOutput(streams.stdout, message)
     });
-    registerLifecycleCommands(program, handlers, streams, cliOptions.stdin);
+    registerLifecycleCommands(program, handlers, streams, cliOptions.stdin, (code) => { commandExitCode = code; });
     registerDevCommands(program, handlers, streams);
     registerArtifactsCommands(program, handlers, streams);
     registerCapabilitiesCommand(program, streams, readPackageVersion());
@@ -198,9 +200,8 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerStatusCommand(program, handlers, streams, (exitCode) => {
         commandExitCode = exitCode;
     });
-    registerUsageCommand(program, streams, (exitCode) => {
-        commandExitCode = exitCode;
-    }, handlers);
+    registerUsageCommand(program, streams, (exitCode) => { commandExitCode = exitCode; }, handlers);
+    registerRecordCommands(program, streams, (exitCode) => { commandExitCode = exitCode; }, handlers);
     registerViewCommand(program, handlers, streams, cliOptions.renderEnvironment);
     registerTrainCommand(program, handlers, streams, readPackageVersion(), (code) => {
         commandExitCode = code;
@@ -208,12 +209,16 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerProductionTargetCommands(program, streams, cliOptions.stdin, (exitCode) => {
         commandExitCode = exitCode;
     });
+    registerVolumeCommands(program, streams, (exitCode) => {
+        commandExitCode = exitCode;
+    });
     program
         .command("validate")
         .description("Validate a Spawnfile and report the resolved compile plan")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .action(async (inputPath) => {
         const plan = await handlers.buildCompilePlan(inputPath);
+        preflightCompilePlan(plan);
         streams.stdout("validation succeeded");
         streams.stdout(formatPlanSummary(plan));
     });

package/dist/cli/runPublishCommands.js

@@ -1,5 +1,6 @@
 import { SpawnfileError } from "../shared/index.js";
 import { resolveCommandInput } from "./resolveCommandInput.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 export const registerRunPublishCommands = (program, handlers, streams) => {
     program
         .command("run")
@@ -12,7 +13,8 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
         .option("--deployment <name>", "Detached deployment record name")
         .option("--docker-command <command>", "Docker command")
         .option("--name <container>", "Docker container name")
-        .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("--world-bindings <file>", "Path to a versioned world-bindings artifact")
         .option("--image", "Interpret the argument as an image reference")
         .option("-d, --detach", "Run the container in detached mode")
@@ -21,7 +23,7 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
         if (runInput.kind === "image" || (runInput.kind === "invalid" && options.image)) {
             throw new SpawnfileError("validation_error", `Image-mode run is not supported. Deploy the image with: ` +
                 `spawnfile up ${inputPath} --auth-profile <profile> ` +
-                "(add --env-file for any extra secrets; image deployments always detach).");
+                "(add --runtime-env-file for any extra secrets; image deployments always detach).");
         }
         if (runInput.kind === "invalid") {
             throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
@@ -34,7 +36,7 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
             deploymentName: options.deployment,
             dockerCommand: options.dockerCommand,
             dockerContext: options.context,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             imageTag: options.tag,
             outputDirectory: options.out,
             ...(options.worldBindings !== undefined

package/dist/cli/trainCommand.js

@@ -1,16 +1,19 @@
 import { SpawnfileError } from "../shared/index.js";
-const forwarded = ["train", "test", "editable", "resource", "judge", "judge-citation-repairs", "validation-group", "optimizer-model",
-    "bridge-command", "out", "max-trials", "max-proposals", "seed", "timeout-ms", "view", "cost-config"];
+const forwarded = ["train", "validation", "test", "editable", "resource", "judge", "judge-citation-repairs", "validation-group", "optimizer-model",
+    "bridge-command", "out", "max-trials", "max-proposals", "seed", "timeout-ms", "experiment-timeout-ms", "trial-timeout-ms", "view", "cost-config", "concurrency"];
 const repeated = new Set(["editable", "resource", "judge", "judge-citation-repairs", "validation-group"]);
 const key = (name) => name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
 export const registerTrainCommand = (program, handlers, streams, packageVersion, setExitCode, signal) => {
     const command = program.command("train")
-        .description("Train one canonical agent through Paideia's isolated native integration")
+        .description("Plan, rewind, or train one canonical agent through its declared training inputs")
         .argument("[path]", "Canonical project directory or Spawnfile path", process.cwd())
-        .option("--agent <id>", "Exact canonical agent node id (inferred only for a single-agent project)")
+        .option("--agent <id>", "Canonical agent id or unambiguous short name (inferred for one agent)")
         .option("--paideia-command <executable>", "Installed Paideia executable; no shell or automatic install", "paideia")
         .option("--training-image <immutable-image>", "Pinned image containing the complete training environment")
         .option("--training-config <json>", "V2 image recipe and declared inputs, or advanced v1 local bindings")
+        .option("--plan", "Print the resolved training authoring plan without executing training")
+        .option("--materialize <example>", "Rewind an authored example into --out without running training")
+        .option("--history <directory>", "Local recorded history for --materialize")
         .option("--dry-run", "Validate and estimate without compiling, authenticating or starting models")
         .option("--repair-measurements <parent-out>", "Fork captured work into a fresh output for authorized measurement repair")
         .option("--repair-witness <manifest>", "Explicit verified image witness for a legacy parent")
@@ -19,26 +22,48 @@ export const registerTrainCommand = (program, handlers, streams, packageVersion,
         const flag = `--${name} <value>`;
         if (repeated.has(name))
             command.option(flag, `Paideia ${name}; repeatable`, (value, previous) => [...previous, value], []);
-        else if (name === "train")
-            command.requiredOption(flag, `Paideia ${name}`);
         else
-            command.option(flag, `Paideia ${name}`);
+            command.option(flag, name === "out" ? "Output directory for training or moment materialization" : `Paideia ${name}`);
     }
     command.action(async (inputPath, options) => {
-        if (options.dryRun !== true && typeof options.out !== "string") {
-            throw new SpawnfileError("validation_error", "Actual training requires --out; dry-run does not write an output directory");
+        if (typeof options.materialize === "string") {
+            if (options.plan === true) {
+                throw new SpawnfileError("validation_error", "--materialize and --plan are mutually exclusive");
+            }
+            if (typeof options.out !== "string") {
+                throw new SpawnfileError("validation_error", "--materialize requires --out");
+            }
+            const project = await handlers.loadTrainingProject(inputPath);
+            const plan = handlers.resolveTrainingPlan(project, options.agent, packageVersion);
+            const moment = await handlers.materializeTrainingMoment({ plan, project, example: options.materialize,
+                historyDir: options.history, out: options.out });
+            if (moment.status === "refused") {
+                streams.stderr(`error: Moment refused: ${moment.inputs.filter((input) => input.refusal !== null).length} input refusal(s), ${moment.leakCheck.findings} leak finding(s); see moment.json in --out`);
+                setExitCode(1);
+            }
+            else {
+                streams.stdout(JSON.stringify(moment, null, 2));
+                setExitCode(0);
+            }
+            return;
         }
-        if (options.dryRun !== true && typeof options.trainingConfig !== "string") {
-            throw new SpawnfileError("validation_error", "Actual training requires --training-config; v1 additionally requires --training-image; host execution is disabled");
+        if (options.history !== undefined) {
+            throw new SpawnfileError("validation_error", "--history requires --materialize");
         }
-        const timeout = options.timeoutMs === undefined ? 3_600_000 : Number(options.timeoutMs);
-        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3_600_000 ||
-            (options.timeoutMs !== undefined && !/^\d+$/u.test(String(options.timeoutMs)))) {
-            throw new SpawnfileError("validation_error", "--timeout-ms must be an integer from 1 to 3600000");
+        if (options.plan === true) {
+            const plan = await handlers.createTrainingPlan(inputPath, {
+                agent: options.agent, packageVersion
+            });
+            streams.stdout(JSON.stringify(plan, null, 2));
+            setExitCode(0);
+            return;
+        }
+        for (const name of ["timeout-ms", "experiment-timeout-ms", "trial-timeout-ms"]) {
+            const value = options[key(name)], maximum = name === "trial-timeout-ms" ? 86_400_000 : 604_800_000;
+            if (value !== undefined && (!/^\d+$/u.test(String(value)) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > maximum)) {
+                throw new SpawnfileError("validation_error", `--${name} must be an integer from 1 to ${maximum}`);
+            }
         }
-        const context = await handlers.createTrainingContext(inputPath, {
-            agent: options.agent, packageVersion
-        });
         const args = [];
         for (const name of forwarded) {
             const value = options[key(name)];
@@ -52,9 +77,37 @@ export const registerTrainCommand = (program, handlers, streams, packageVersion,
             args.push("--dry-run");
         if (options.resume === true)
             args.push("--resume");
-        setExitCode(await handlers.delegatePaideiaTraining({ context, args,
+        const project = await handlers.loadTrainingProject(inputPath);
+        const plan = handlers.resolveTrainingPlan(project, options.agent, packageVersion);
+        const timeout = Number(options.experimentTimeoutMs ?? options.timeoutMs ?? plan.deadlines?.experiment_ms ?? 43_200_000);
+        if (options.experimentTimeoutMs === undefined && options.timeoutMs === undefined)
+            args.push("--experiment-timeout-ms", String(timeout));
+        if (options.trialTimeoutMs === undefined && plan.deadlines?.trial_ms !== undefined)
+            args.push("--trial-timeout-ms", String(plan.deadlines.trial_ms));
+        const lowered = plan.targets.length > 0 ? await handlers.lowerTrainingExecution({ project, plan, args,
+            trainingConfig: options.trainingConfig, trainingImage: options.trainingImage }) : undefined;
+        if (lowered && options.dryRun === true) {
+            streams.stdout(JSON.stringify({ ...lowered.execution, container: { configPath: lowered.trainingConfig,
+                    declaration: lowered.declaration, ...(lowered.trainingImage ? { imageOverride: lowered.trainingImage } : {}) } }, null, 2));
+            setExitCode(0);
+            return;
+        }
+        if (!lowered && typeof options.train !== "string") {
+            throw new SpawnfileError("validation_error", `Agent ${plan.agent.id} has no executable training targets; supply --train`);
+        }
+        if (!lowered && options.dryRun !== true && typeof options.out !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --out when no training targets are declared");
+        }
+        if (!lowered && options.dryRun !== true && typeof options.trainingConfig !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --training-config when no training targets are declared; host execution is disabled");
+        }
+        const context = await handlers.createTrainingContext(inputPath, { agent: plan.agent.id, packageVersion });
+        if (lowered)
+            await handlers.allocateTrainingOutputParent(lowered.execution.output);
+        setExitCode(await handlers.delegatePaideiaTraining({ context, args: lowered?.execution.args ?? args, execution: lowered?.execution,
             repairMeasurements: options.repairMeasurements, repairWitness: options.repairWitness,
-            trainingImage: options.trainingImage, trainingConfig: options.trainingConfig,
+            trainingImage: lowered?.trainingImage ?? options.trainingImage,
+            trainingConfig: lowered?.trainingConfig ?? options.trainingConfig,
             command: options.paideiaCommand, dryRun: options.dryRun === true,
             timeoutMs: timeout + 5000, streams, signal }));
     });

package/dist/cli/upCommand.js

@@ -7,6 +7,7 @@ import { resolveCommandInput } from "./resolveCommandInput.js";
 import { runImageUpCommand } from "./upImageCommand.js";
 import { createUpLifecycleInvocation, createUpProjectOptions } from "./upLifecycleInvocation.js";
 import { reconcileUpLifecycle } from "./upLifecycleRecovery.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 const readSelectedTargetReceipt = async (file) => {
     if (typeof file !== "string" || file.length < 1 || Buffer.byteLength(file, "utf8") > 4096) {
         throw new SpawnfileError("validation_error", "Invalid selected target receipt");
@@ -38,7 +39,8 @@ export const registerUpCommand = (program, handlers, streams) => {
         .option("--deployment <name>", "Detached deployment record name")
         .option("--docker-command <command>", "Docker command")
         .option("--name <container>", "Docker container name")
-        .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("--world-bindings <file>", "Path to a versioned world-bindings artifact")
         .option("--selected-target-receipt-digest <digest>", "Selected target receipt digest for an organization handoff")
         .option("--selected-target-receipt <file>", "Selected target receipt for an organization handoff")
@@ -51,6 +53,8 @@ export const registerUpCommand = (program, handlers, streams) => {
         .option("--json", "Render a spawnfile.up-receipt.v1 machine-readable receipt")
         .option("--lifecycle-invocation <id>", "Durably bind this exact JSON lifecycle invocation")
         .action(async (inputPath, options) => {
+        options.envFile = resolveEnvFileOption(options);
+        delete options.runtimeEnvFile;
         requireMachineLifecycle(options.lifecycleInvocation, options.json);
         const upInput = resolveCommandInput(inputPath, { forceImage: options.image });
         if (upInput.kind === "invalid") {

package/dist/cli/volumeCommands.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+import type { CliStreams } from "./runCli.js";
+/**
+ * `spawnfile volume refresh|verify`: host-side operations on a fed volume, suitable for a timer.
+ * Exit 0 when the volume is clean (current, freshly landed, or another writer holds the lock); exit 1
+ * when anything needs a human (tampering found, repaired or not, or a refusal).
+ */
+export declare const registerVolumeCommands: (program: Command, streams: CliStreams, setExitCode: (code: number) => void) => void;

package/dist/cli/volumeCommands.js

@@ -0,0 +1,53 @@
+import { InvalidArgumentError } from "commander";
+import { feedResultClean, refreshVolumeFeed, resolveFeedTarget, verifyVolumeFeed } from "../volume/index.js";
+const positiveInteger = (value) => {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new InvalidArgumentError("must be a positive integer");
+    return parsed;
+};
+const targetOptions = (options) => ({
+    ...(options.fetch === false ? { fetch: false } : {}),
+    ...(options.healLimit ? { healLimit: options.healLimit } : {}),
+    ...(options.stateDir ? { stateDir: options.stateDir } : {}),
+    ...(options.volumePath ? { volumePath: options.volumePath } : {})
+});
+const report = (streams, result, json) => {
+    if (json) {
+        streams.stdout(JSON.stringify(result));
+        return;
+    }
+    streams.stdout(`${result.status}${result.revision ? ` ${result.revision}` : ""}`);
+    for (const finding of result.findings)
+        streams.stderr(`finding: ${finding}`);
+};
+const withShared = (command) => command
+    .argument("<id>", "Volume resource id that declares feed")
+    .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+    .option("--volume-path <dir>", "Host directory of the volume content (default: docker volume inspect)")
+    .option("--state-dir <dir>", "Host state directory, outside the volume and on its filesystem")
+    .option("--json", "Print the result as one JSON line");
+/**
+ * `spawnfile volume refresh|verify`: host-side operations on a fed volume, suitable for a timer.
+ * Exit 0 when the volume is clean (current, freshly landed, or another writer holds the lock); exit 1
+ * when anything needs a human (tampering found, repaired or not, or a refusal).
+ */
+export const registerVolumeCommands = (program, streams, setExitCode) => {
+    const volume = program.command("volume").description("Operate host-fed volumes");
+    withShared(volume.command("refresh").description("Land the feed's current content by atomic swap, or verify and heal what is landed"))
+        .option("--no-fetch", "Do not fetch a git feed before resolving its ref")
+        .option("--heal-limit <n>", "Re-lands of one revision before auto-repair is suspended", positiveInteger)
+        .action(async (id, inputPath, options) => {
+        const target = await resolveFeedTarget(inputPath, id, targetOptions(options));
+        const result = refreshVolumeFeed(target, { log: (line) => streams.stderr(line) });
+        report(streams, result, options.json);
+        setExitCode(feedResultClean(result) ? 0 : 1);
+    });
+    withShared(volume.command("verify").description("Check a fed volume against the host record without changing it"))
+        .action(async (id, inputPath, options) => {
+        const target = await resolveFeedTarget(inputPath, id, targetOptions(options));
+        const result = verifyVolumeFeed(target, { log: (line) => streams.stderr(line) });
+        report(streams, result, options.json);
+        setExitCode(feedResultClean(result) ? 0 : 1);
+    });
+};

package/dist/compiler/agentNodeMerge.js

@@ -2,11 +2,11 @@ import path from "node:path";
 import { SpawnfileError } from "../shared/index.js";
 import { stableStringify } from "./helpers.js";
 import { mergeWorkspaceResources } from "./workspaceResources.js";
-const assertSame = (field, existing, next, nodeName) => {
+const assertSame = (field, existing, next, nodeName, errorCode = "compile_error") => {
     if (stableStringify(existing) === stableStringify(next)) {
         return;
     }
-    throw new SpawnfileError("compile_error", `Agent ${nodeName} resolves with incompatible ${field} across team imports`);
+    throw new SpawnfileError(errorCode, `Agent ${nodeName} resolves with incompatible ${field} across team imports`);
 };
 const mergeEnvStrict = (existing, next, nodeName) => {
     const merged = { ...existing };
@@ -62,6 +62,7 @@ export const mergeCompatibleAgentNode = (existing, next) => {
     assertSame("source", existing.source, next.source, existing.name);
     assertSame("source path", existing.sourcePath, next.sourcePath, existing.name);
     assertSame("surfaces", existing.surfaces, next.surfaces, existing.name);
+    assertSame("training", existing.training, next.training, existing.name, "validation_error");
     existing.docs = mergeDocuments(existing.docs, next.docs, existing.sourcePath ?? existing.source);
     existing.env = mergeEnvStrict(existing.env, next.env, existing.name);
     existing.mcpServers = mergeByKeyStrict(existing.mcpServers, next.mcpServers, (server) => server.name, "MCP server", existing.name) ?? [];

package/dist/compiler/buildCompilePlan.js

@@ -1,11 +1,13 @@
 import { getCanonicalManifestPath, getManifestPath } from "../filesystem/index.js";
 import { loadManifest, isAgentManifest } from "../manifest/index.js";
 import { assignStableNodeIds } from "./helpers.js";
+import { resolvePlanMcpPlaceholders } from "./mcpPlaceholders.js";
 import { resolvePlanMoltnetAttachments } from "./moltnetResolution.js";
 import { resolvePlanMemoryAccess } from "./memoryResolution.js";
 import { resolveMoltnetRoomMemberships } from "./moltnetRoomMemberships.js";
 import { createRuntimeGroups } from "./buildCompilePlanRuntime.js";
 import { validateAllowedWakeSenders } from "./moltnetAllowedWakeSendersValidation.js";
+import { resolvePlanTrainingSources } from "./training/resolution.js";
 import { createCompilePlanTraversal } from "./buildCompilePlanTraversal.js";
 import { resolveMoltnetExternalParticipantIntents, resolveOrganizationIdentity, validateB31MoltnetAuth } from "./organizationIdentity.js";
 export const buildCompilePlan = async (inputPath) => {
@@ -49,6 +51,8 @@ export const buildCompilePlan = async (inputPath) => {
         source: node.source,
         value: node.value
     })));
+    resolvePlanMcpPlaceholders(nodes);
+    resolvePlanTrainingSources(nodes);
     const idBySource = new Map(nodes.map((node) => [node.value.source, node.id]));
     const compilePlanNodes = nodes;
     const compilePlanEdges = edges.map((edge) => ({

package/dist/compiler/buildCompilePlanAgent.js

@@ -9,13 +9,14 @@ import { assertRuntimeSupportsExecutionModelAuth } from "./modelAuth.js";
 import { loadResolvedSkills, mergeResolvedSkills } from "./surfaces.js";
 import { assertRuntimeSupportsAgentSurfaces } from "./surfaceSupport.js";
 import { mergeWorkspaceResources } from "./workspaceResources.js";
+import { mergeTrainingDeclarations, resolveTrainingDeclaration } from "./training/resolution.js";
 export const resolveAgentNode = async ({ context, manifest, manifestPath, source }) => {
     const runtime = await resolveRuntime(manifest, context);
     const execution = applyExecutionDefaults(context.isSubagent
         ? mergeExecution(context.inheritedExecution, manifest.execution)
         : manifest.execution);
     assertRuntimeSupportsExecutionModelAuth(runtime.name, execution, manifest.name);
-    const environment = resolveEffectiveEnvironment(context.inheritedShared?.surface?.environment, manifest.environment);
+    const environment = resolveEffectiveEnvironment(manifest.name, context.inheritedShared?.surface?.environment, manifest.environment);
     const inheritedSkills = context.inheritedShared
         ? await loadResolvedSkills(context.inheritedShared.manifestPath, context.inheritedShared.surface?.workspace?.skills)
         : [];
@@ -49,6 +50,7 @@ export const resolveAgentNode = async ({ context, manifest, manifestPath, source
         ...(source === manifestPath ? {} : { sourcePath: manifestPath }),
         surfaces: resolveAgentSurfaces(manifest.surfaces),
         subagents: [],
+        training: mergeTrainingDeclarations(resolveTrainingDeclaration(context.inheritedShared?.surface?.training, context.inheritedShared?.manifestPath ?? manifestPath, context.inheritedShared?.manifestPath ?? source), resolveTrainingDeclaration(manifest.training, manifestPath, source)),
         workspaceResources
     };
     assertRuntimeSupportsAgentSurfaces(runtime.name, candidate.surfaces, manifest.name);

package/dist/compiler/buildCompilePlanTraversal.js

@@ -11,6 +11,7 @@ import { mergeWorkspaceResources } from "./workspaceResources.js";
 import { DEFAULT_POLICY_MODE, DEFAULT_POLICY_ON_DEGRADE, mergeResolvedDocuments, } from "./buildCompilePlanTraversalHelpers.js";
 import { resolveAgentNode } from "./buildCompilePlanAgent.js";
 import { createInlineAgentSource } from "./projectManifestGraph.js";
+import { resolveTrainingDeclaration } from "./training/resolution.js";
 export const createCompilePlanTraversal = ({ getLoadedManifest, nodeCache, fingerprintCache, edges, memberships }) => {
     const visitStack = [];
     const recordAgentMembership = (teamSource, teamName, memberId, agent) => {
@@ -128,6 +129,7 @@ export const createCompilePlanTraversal = ({ getLoadedManifest, nodeCache, finge
                 skills: sharedSkills
             },
             source: canonicalPath,
+            training: resolveTrainingDeclaration(manifest.shared?.training, canonicalPath, canonicalPath)
         };
         const fingerprint = getTeamFingerprint(candidate);
         const existingFingerprint = fingerprintCache.get(canonicalPath);

package/dist/compiler/buildCompilePlanTraversalHelpers.d.ts

@@ -1,4 +1,4 @@
-import { type Environment, type McpServer, type Secret, type TeamWorkspace } from "../manifest/index.js";
+import { type Environment, type McpServer, type Secret, type SharedEnvironment, type TeamWorkspace } from "../manifest/index.js";
 import { ResolvedDocument, ResolvedPackage, ResolvedAgentNode, ResolvedTeamNode } from "./types.js";
 export declare const DEFAULT_POLICY_MODE = "warn";
 export declare const DEFAULT_POLICY_ON_DEGRADE = "warn";
@@ -9,7 +9,7 @@ export type InternalNode = {
 };
 type ResolvedPackageArray = ResolvedPackage[] | undefined;
 export declare const mergeResolvedDocuments: (primaryPath: string, primaryDocs: TeamWorkspace["docs"] | undefined, fallbackPath: string | undefined, fallbackDocs: TeamWorkspace["docs"] | undefined) => Promise<ResolvedDocument[]>;
-export declare const resolveEffectiveEnvironment: (sharedEnvironment: Environment | undefined, localEnvironment: Environment | undefined) => {
+export declare const resolveEffectiveEnvironment: (agentName: string, sharedEnvironment: SharedEnvironment | undefined, localEnvironment: Environment | undefined) => {
     env: Record<string, string>;
     mcpServers: McpServer[];
     packages: ResolvedPackageArray;

package/dist/compiler/buildCompilePlanTraversalHelpers.js

@@ -1,4 +1,5 @@
-import { loadResolvedDocuments, mergeEnv, mergeMcpServers, mergePackages, mergeSecrets } from "./surfaces.js";
+import { loadResolvedDocuments, mergeEnv, mergePackages, mergeSecrets } from "./surfaces.js";
+import { resolveInheritedMcpServers } from "./mcpServerInheritance.js";
 export const DEFAULT_POLICY_MODE = "warn";
 export const DEFAULT_POLICY_ON_DEGRADE = "warn";
 export const mergeResolvedDocuments = async (primaryPath, primaryDocs, fallbackPath, fallbackDocs) => {
@@ -14,9 +15,9 @@ export const mergeResolvedDocuments = async (primaryPath, primaryDocs, fallbackP
     }
     return [...merged.values()];
 };
-export const resolveEffectiveEnvironment = (sharedEnvironment, localEnvironment) => ({
+export const resolveEffectiveEnvironment = (agentName, sharedEnvironment, localEnvironment) => ({
     env: mergeEnv(sharedEnvironment?.env, localEnvironment?.env),
-    mcpServers: mergeMcpServers(sharedEnvironment?.mcp_servers, localEnvironment?.mcp_servers),
+    mcpServers: resolveInheritedMcpServers(agentName, sharedEnvironment?.mcp_servers, localEnvironment?.mcp_servers),
     packages: mergePackages(sharedEnvironment?.packages, localEnvironment?.packages),
     secrets: mergeSecrets(sharedEnvironment?.secrets, localEnvironment?.secrets)
 });

package/dist/compiler/buildProject.d.ts

@@ -29,6 +29,7 @@ export interface BuildProjectResult extends CompileProjectResult {
     imageTag: string;
 }
 export declare const createDefaultImageTag: (projectRoot: string) => string;
+export declare const resolveImageTagRoot: (inputPath: string) => string;
 export declare const createDockerBuildInvocation: (outputDirectory: string, imageTag: string, options?: string | {
     dockerCommand?: string;
     dockerContext?: string;
@@ -37,3 +38,12 @@ export declare const normalizeDockerArchitecture: (architecture: string) => Molt
 export declare const resolveDockerBuildArchitecture: (options: Pick<BuildProjectOptions, "dockerCommand" | "dockerContext">) => Promise<MoltnetTargetArchitecture | undefined>;
 export declare const runDockerBuild: DockerBuildRunner;
 export declare const buildProject: (inputPath: string, options?: BuildProjectOptions) => Promise<BuildProjectResult>;
+/**
+ * The image half of `buildProject`, for callers that compiled first and need
+ * the build-context identity before deciding whether to build at all (a
+ * release no-ops on an unchanged identity without touching Docker).
+ * `contextDigest` may be passed when the caller already computed it.
+ */
+export declare const buildCompiledProject: (inputPath: string, compileResult: CompileProjectResult, options?: Omit<BuildProjectOptions, keyof CompileProjectOptions> & {
+    contextDigest?: string;
+}) => Promise<BuildProjectResult>;

package/dist/compiler/buildProject.js

@@ -13,7 +13,7 @@ export const createDefaultImageTag = (projectRoot) => {
     const baseName = slugify(path.basename(projectRoot));
     return `spawnfile-${baseName || "project"}`;
 };
-const resolveImageTagRoot = (inputPath) => {
+export const resolveImageTagRoot = (inputPath) => {
     const resolvedPath = path.resolve(inputPath);
     return path.basename(resolvedPath).toLowerCase() === "spawnfile"
         ? path.dirname(resolvedPath)
@@ -78,6 +78,9 @@ export const runDockerBuild = async (invocation) => new Promise((resolve, reject
 export const buildProject = async (inputPath, options = {}) => {
     const targetArchitecture = options.containerArchitecture ?? await resolveDockerBuildArchitecture(options);
     const compileResult = await compileProject(inputPath, {
+        ...(options.bundleCacheDirectory !== undefined ? { bundleCacheDirectory: options.bundleCacheDirectory } : {}),
+        ...(options.bundleIdentity !== undefined ? { bundleIdentity: options.bundleIdentity } : {}),
+        ...(options.bundleDockerCommand ?? options.dockerCommand ? { bundleDockerCommand: options.bundleDockerCommand ?? options.dockerCommand } : {}),
         clean: options.clean,
         containerArchitecture: targetArchitecture,
         outputDirectory: options.outputDirectory,
@@ -86,6 +89,15 @@ export const buildProject = async (inputPath, options = {}) => {
             ? { worldBindingsPath: options.worldBindingsPath }
             : {})
     });
+    return buildCompiledProject(inputPath, compileResult, options);
+};
+/**
+ * The image half of `buildProject`, for callers that compiled first and need
+ * the build-context identity before deciding whether to build at all (a
+ * release no-ops on an unchanged identity without touching Docker).
+ * `contextDigest` may be passed when the caller already computed it.
+ */
+export const buildCompiledProject = async (inputPath, compileResult, options = {}) => {
     const imageTag = options.imageTag ?? createDefaultImageTag(resolveImageTagRoot(inputPath));
     const invocation = createDockerBuildInvocation(compileResult.outputDirectory, imageTag, {
         dockerCommand: options.dockerCommand,
@@ -96,7 +108,7 @@ export const buildProject = async (inputPath, options = {}) => {
     const contextDigestStartedAt = performance.now();
     const [contextFiles, contextDigest] = await Promise.all([
         listDockerBuildContextFiles(compileResult.outputDirectory),
-        createDockerBuildContextDigest(compileResult.outputDirectory)
+        options.contextDigest ?? createDockerBuildContextDigest(compileResult.outputDirectory)
     ]);
     const contextDigestMs = performance.now() - contextDigestStartedAt;
     let probeMs = 0;