spawnfile 0.1.10 → 0.1.12

package/README.md

@@ -37,13 +37,20 @@ spawnfile init                                   # scaffold an agent (defaults t
 spawnfile validate                               # check the graph
 spawnfile view .                                 # read-only graph view; writes no files
 spawnfile compile                                # lower to runtime-native output
+spawnfile status .                               # read declared/compiled status
 spawnfile auth sync --profile dev --env-file .env
 spawnfile build  --tag my-agent                  # compile + docker build
-spawnfile run    --tag my-agent --auth-profile dev
+spawnfile run    --tag my-agent --auth-profile dev --detach
+spawnfile status . --live                        # inspect the detached deployment
+spawnfile publish . --tag you/my-agent:1.0.0     # compile + build + verify + push
 ```
 
 Compiled output lands under `.spawn/` by default, including a `Dockerfile`, `entrypoint.sh`, `.env.example`, and a prebuilt `container/rootfs/` tree. `spawnfile build` uses the pinned runtime artifacts from `runtimes.yaml`; it does not rebuild runtimes from source.
 
+`spawnfile status` is read-only. By default it shows authored and compiled state without Docker, runtime, or Moltnet calls. With `--live`, it reads the selected detached deployment record, inspects the recorded Docker target, runs adapter-owned runtime probes, and checks Moltnet metadata without reading message bodies. Add `--logs` for a redacted Docker log tail, or `--watch` to refresh status continuously.
+
+Compiled images are self-describing: `spawnfile publish` pushes one to any OCI registry, and anyone can run it with no source — `spawnfile up you/my-agent:1.0.0 --deployment prod --detach --auth-profile me` — or inspect what it needs first with `spawnfile status you/my-agent:1.0.0`. See [`specs/DISTRIBUTION.md`](specs/DISTRIBUTION.md).
+
 Declare external credentials in `secrets:` and provide values through an ignored env file or the shell environment. `spawnfile auth sync --env-file .env` stores declared model auth and project secrets in a local auth profile; `spawnfile run --env-file .env` can inject the same values directly for a single run. This is the intended pattern for credentials like `GH_TOKEN`, MCP tokens, and provider API keys.
 
 ## Project structure
@@ -91,9 +98,11 @@ v0.1 targets autonomous agent runtimes that share a markdown workspace identity
 |-----------|---------------|---------|-----------------------------------------------|
 | OpenClaw  | active        | ✅      | Discord, Telegram, WhatsApp, Slack            |
 | PicoClaw  | active        |         | Discord, Telegram, Slack (WhatsApp blocked)   |
-| TinyClaw  | active        |         | Discord, Telegram, WhatsApp (pairing-gated)   |
 | NullClaw  | exploratory   |         | No active adapter yet                         |
 | ZeroClaw  | exploratory   |         | No active adapter yet                         |
+| OpenFang  | exploratory   |         | No active adapter yet                         |
+| Hermes Agent | exploratory |        | No active adapter yet                         |
+| OpenCode  | exploratory   |         | No active adapter yet                         |
 
 Each adapter maps the portable schema into its native forms. The compiler reports a machine-readable `spawnfile-report.json` with the resolved graph, chosen runtimes, and capability outcomes (`supported`, `degraded`, `unsupported`). See [`specs/RUNTIMES.md`](specs/RUNTIMES.md) for the live matrix and pinned versions, or [`runtimes.yaml`](runtimes.yaml) for the registry source of truth.
 
@@ -113,6 +122,8 @@ The source-of-truth specs live in this repo:
 - [`specs/CONTAINERS.md`](specs/CONTAINERS.md) — container compilation
 - [`specs/RUNTIMES.md`](specs/RUNTIMES.md) — runtime registry and version pinning
 - [`specs/SURFACES.md`](specs/SURFACES.md) — messaging surface model
+- [`specs/STATUS.md`](specs/STATUS.md) — static and live operational status
+- [`specs/DISTRIBUTION.md`](specs/DISTRIBUTION.md) — image distribution, publish, and sourceless run
 - [`fixtures/`](fixtures/) — canonical example projects
 
 ## From source

package/dist/cli/lifecycleCommands.js

@@ -1,6 +1,27 @@
+import { readRunEnvFile } from "../compiler/runProjectAuth.js";
+import { SpawnfileError } from "../shared/index.js";
+import { resolveCommandInput } from "./resolveCommandInput.js";
+const resolveAuthProfileForImage = async (handlers, authProfile) => {
+    if (!authProfile || !handlers.requireAuthProfile) {
+        return null;
+    }
+    return handlers.requireAuthProfile(authProfile);
+};
+const shortDigest = (digest) => digest ? digest.replace(/^sha256:/, "").slice(0, 12) : "unknown";
+/** Summarizes a redeploy as previous → new ref/digest, per specs/DISTRIBUTION.md. */
+const formatRedeploySummary = (previous, newRef, newDigest) => {
+    // Only claim "unchanged" when we actually resolved a matching digest; two null
+    // digests (local-only images) are unknown, not provably identical.
+    if (previous.ref === newRef && newDigest !== null && previous.digest === newDigest) {
+        return `redeployed image ${newRef} (digest unchanged ${shortDigest(newDigest)})`;
+    }
+    return (`redeployed image: ${previous.ref} (${shortDigest(previous.digest)}) ` +
+        `→ ${newRef} (${shortDigest(newDigest)})`);
+};
 export const registerLifecycleCommands = (program, handlers, streams) => {
     program
         .command("compile")
+        .description("Compile a project into runtime-native output under .spawn")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-o, --out <directory>", "Output directory")
         .action(async (inputPath, options) => {
@@ -10,6 +31,7 @@ export const registerLifecycleCommands = (program, handlers, streams) => {
     });
     program
         .command("build")
+        .description("Compile and build the organization Docker image")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--docker-command <command>", "Docker command")
         .option("-o, --out <directory>", "Output directory")
@@ -26,20 +48,36 @@ export const registerLifecycleCommands = (program, handlers, streams) => {
     });
     program
         .command("run")
+        .description("Compile, build, and run the organization container locally")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("-o, --out <directory>", "Output directory")
         .option("-t, --tag <image>", "Docker image tag")
         .option("--auth-profile <name>", "Local Spawnfile auth profile")
+        .option("--context <name>", "Docker context for the deployment target")
+        .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")
+        .option("--image", "Interpret the argument as an image reference")
         .option("-d, --detach", "Run the container in detached mode")
         .action(async (inputPath, options) => {
+        const runInput = resolveCommandInput(inputPath, { forceImage: options.image });
+        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).");
+        }
+        if (runInput.kind === "invalid") {
+            throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
+                "Pass a project directory, a Spawnfile path, or an image like 'name:tag' (use --image to force image mode).");
+        }
         const result = await handlers.runProject(inputPath, {
             authProfile: options.authProfile,
             containerName: options.name,
             detach: options.detach,
+            deploymentName: options.deployment,
             dockerCommand: options.dockerCommand,
+            dockerContext: options.context,
             envFilePath: options.envFile,
             imageTag: options.tag,
             outputDirectory: options.out
@@ -50,21 +88,83 @@ export const registerLifecycleCommands = (program, handlers, streams) => {
         }
     });
     program
-        .command("up")
+        .command("publish")
+        .description("Compile, build, verify, and push the organization image to a registry")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("-t, --tag <image>", "Registry image reference to push")
+        .option("-o, --out <directory>", "Output directory")
+        .option("--docker-command <command>", "Docker command")
+        .action(async (inputPath, options) => {
+        const publishInput = resolveCommandInput(inputPath);
+        if (publishInput.kind !== "project") {
+            throw new SpawnfileError("validation_error", "publish operates on a project path, not an image reference");
+        }
+        const result = await handlers.publishProject(inputPath, {
+            dockerCommand: options.dockerCommand,
+            imageTag: options.tag,
+            outputDirectory: options.out
+        });
+        streams.stdout(`published ${result.imageTag}`);
+        streams.stdout(`digest: ${result.digest ?? "unknown"}`);
+        streams.stdout(`next: spawnfile up ${result.imageTag} --detach --auth-profile <profile>`);
+    });
+    program
+        .command("up")
+        .description("Deploy an organization from a project or a published image reference")
+        .argument("[path]", "Project directory, Spawnfile path, or image reference", process.cwd())
         .option("-o, --out <directory>", "Output directory")
         .option("-t, --tag <image>", "Docker image tag")
         .option("--auth-profile <name>", "Local Spawnfile auth profile")
+        .option("--context <name>", "Docker context for the deployment target")
+        .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")
+        .option("--image", "Interpret the argument as an image reference")
+        .option("--pull", "Pull the image before deploying")
         .option("-d, --detach", "Run the container in detached mode")
         .action(async (inputPath, options) => {
+        const upInput = resolveCommandInput(inputPath, { forceImage: options.image });
+        if (upInput.kind === "invalid") {
+            throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
+                "Pass a project directory, a Spawnfile path, or an image like 'name:tag' (use --image to force image mode).");
+        }
+        if (upInput.kind === "image") {
+            const [authProfile, envFileEnv] = await Promise.all([
+                resolveAuthProfileForImage(handlers, options.authProfile),
+                readRunEnvFile(options.envFile)
+            ]);
+            const consumed = await handlers.consumeImageUp(upInput.ref, {
+                authProfile,
+                authProfileName: options.authProfile ?? null,
+                authValues: authProfile?.env ?? {},
+                deploymentName: options.deployment,
+                dockerCommand: options.dockerCommand,
+                dockerContext: options.context,
+                envFileEnv,
+                envFilePath: options.envFile ?? null,
+                pull: options.pull
+            });
+            if (consumed.previous) {
+                const newDigest = consumed.record.source.kind === "image" ? consumed.record.source.digest : null;
+                streams.stdout(formatRedeploySummary(consumed.previous, consumed.imageRef, newDigest));
+            }
+            else {
+                streams.stdout(`deployed image ${consumed.imageRef}`);
+            }
+            streams.stdout(`deployment: ${consumed.deploymentName}`);
+            streams.stdout(`running container ${consumed.containerName}`);
+            streams.stdout(`record: ${consumed.recordPath}`);
+            streams.stdout(`next: spawnfile status --deployment ${consumed.deploymentName} --live`);
+            return;
+        }
         const result = await handlers.upProject(inputPath, {
             authProfile: options.authProfile,
             containerName: options.name,
             detach: options.detach,
+            deploymentName: options.deployment,
             dockerCommand: options.dockerCommand,
+            dockerContext: options.context,
             envFilePath: options.envFile,
             imageTag: options.tag,
             outputDirectory: options.out

package/dist/cli/modelCommands.js

@@ -4,6 +4,7 @@ export const registerModelCommands = (program, handlers, streams) => {
         .description("Edit primary and fallback model declarations");
     modelCommand
         .command("set")
+        .description("Set an agent's primary model")
         .argument("<provider>", "Model provider")
         .argument("<name>", "Model name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
@@ -29,6 +30,7 @@ export const registerModelCommands = (program, handlers, streams) => {
     });
     modelCommand
         .command("add-fallback")
+        .description("Append a fallback model to an agent")
         .argument("<provider>", "Model provider")
         .argument("<name>", "Model name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
@@ -54,6 +56,7 @@ export const registerModelCommands = (program, handlers, streams) => {
     });
     modelCommand
         .command("clear-fallbacks")
+        .description("Remove all fallback models from an agent")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--recursive", "Update the target project and its descendants")
         .action(async (inputPath, options) => {

package/dist/cli/resolveCommandInput.d.ts

@@ -0,0 +1,19 @@
+export type CommandInput = {
+    kind: "project";
+    path: string;
+} | {
+    kind: "image";
+    ref: string;
+} | {
+    kind: "invalid";
+    value: string;
+};
+export interface ResolveCommandInputOptions {
+    forceImage?: boolean;
+}
+/**
+ * Resolves a positional argument that may be a project path or an image
+ * reference. An existing directory or file always wins unless --image forces
+ * image mode. Implicit image refs require a tag, digest, or registry component.
+ */
+export declare const resolveCommandInput: (value: string, options?: ResolveCommandInputOptions) => CommandInput;

package/dist/cli/resolveCommandInput.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parseImplicitImageReference } from "../distribution/index.js";
+/**
+ * Resolves a positional argument that may be a project path or an image
+ * reference. An existing directory or file always wins unless --image forces
+ * image mode. Implicit image refs require a tag, digest, or registry component.
+ */
+export const resolveCommandInput = (value, options = {}) => {
+    if (!options.forceImage) {
+        const resolved = path.resolve(value);
+        if (existsSync(resolved)) {
+            return { kind: "project", path: value };
+        }
+    }
+    if (options.forceImage) {
+        // --image accepts Docker's full reference grammar, including bare names.
+        return { kind: "image", ref: value };
+    }
+    const parsed = parseImplicitImageReference(value);
+    if (parsed) {
+        return { kind: "image", ref: value };
+    }
+    return { kind: "invalid", value };
+};

package/dist/cli/runCli.d.ts

@@ -1,5 +1,6 @@
 import { importClaudeCodeAuth, importCodexAuth, importEnvFile, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, clearProjectModelFallbacks, compileProject, initProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, clearProjectModelFallbacks, compileProject, initProject, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { consumeImageUp } from "../distribution/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
 export interface CliStreams {
     stderr: (message: string) => void;
@@ -15,6 +16,7 @@ export interface CliHandlers {
     buildOrganizationView: typeof buildOrganizationView;
     buildProject: typeof buildProject;
     compileProject: typeof compileProject;
+    publishProject: typeof publishProject;
     addAgentProject: typeof addAgentProject;
     addProjectModelFallback: typeof addProjectModelFallback;
     addProjectSurface: typeof addProjectSurface;
@@ -30,6 +32,7 @@ export interface CliHandlers {
     requireAuthProfile: typeof requireAuthProfile;
     runProject: typeof runProject;
     upProject: typeof upProject;
+    consumeImageUp: typeof consumeImageUp;
     setProjectPrimaryModel: typeof setProjectPrimaryModel;
     setProjectRuntime: typeof setProjectRuntime;
     setProjectSurfaceAccess: typeof setProjectSurfaceAccess;

package/dist/cli/runCli.js

@@ -1,13 +1,15 @@
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
 import { importClaudeCodeAuth, importCodexAuth, importEnvFile, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, clearProjectModelFallbacks, compileProject, initProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
-import { isSpawnfileError } from "../shared/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, clearProjectModelFallbacks, compileProject, initProject, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { consumeImageUp } from "../distribution/index.js";
+import { errorExitCode, isSpawnfileError } from "../shared/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
 import { registerLifecycleCommands } from "./lifecycleCommands.js";
 import { registerModelCommands } from "./modelCommands.js";
 import { registerRuntimeCommands } from "./runtimeCommands.js";
 import { registerSurfaceCommands } from "./surfaceCommands.js";
+import { registerStatusCommand } from "./statusCommand.js";
 import { registerViewCommand } from "./viewCommand.js";
 const packageJsonPath = new URL("../../package.json", import.meta.url);
 const readPackageVersion = () => {
@@ -24,12 +26,12 @@ const createDefaultRenderEnvironment = () => ({
     stdoutIsTty: process.stdout.isTTY === true
 });
 const createDefaultHandlers = () => ({
-    buildCompilePlan, buildOrganizationView, buildProject, compileProject,
+    buildCompilePlan, buildOrganizationView, buildProject, compileProject, publishProject,
     addAgentProject, addProjectModelFallback, addProjectSurface,
     addSubagentProject, addTeamProject, clearProjectModelFallbacks,
     importClaudeCodeAuth, importCodexAuth, importEnvFile,
     initProject, listRuntimeAdapters, removeProjectSurface, requireAuthProfile,
-    runProject, setProjectPrimaryModel, setProjectRuntime, upProject,
+    runProject, setProjectPrimaryModel, setProjectRuntime, upProject, consumeImageUp,
     setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth
 });
 const isCliStreams = (value) => {
@@ -62,6 +64,16 @@ const isCommanderError = (error) => {
         && candidate.code.startsWith("commander.")
         && typeof candidate.exitCode === "number";
 };
+const formatCliErrorMessage = (error) => {
+    if (isSpawnfileError(error)) {
+        // Surface the human message only; the internal code is not user-facing.
+        return error.message;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+};
 const formatPlanSummary = (plan) => [
     `root: ${plan.root}`,
     `nodes: ${plan.nodes.length}`,
@@ -82,6 +94,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     const cliOptions = normalizeRunCliOptions(optionsOrStreams, handlerOverrides);
     const streams = cliOptions.streams;
     const handlers = { ...createDefaultHandlers(), ...cliOptions.handlers };
+    let commandExitCode = 0;
     const program = new Command();
     program.name("spawnfile").description("Spawnfile v0.1 compiler").version(readPackageVersion());
     program.exitOverride();
@@ -93,6 +106,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerLifecycleCommands(program, handlers, streams);
     program
         .command("init")
+        .description("Scaffold a new Spawnfile project or team in a directory")
         .argument("[path]", "Directory to initialize", process.cwd())
         .option("--team", "Initialize a team project")
         .option("--runtime <name>", "Runtime for agent scaffolds")
@@ -108,6 +122,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     const addCommand = program.command("add").description("Add children to an existing Spawnfile project");
     addCommand
         .command("agent")
+        .description("Add an agent member to a team project")
         .argument("<id>", "Agent member id")
         .argument("[path]", "Team project directory or Spawnfile path", process.cwd())
         .option("--runtime <name>", "Runtime for the new agent member")
@@ -122,6 +137,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     addCommand
         .command("subagent")
+        .description("Add a subagent to an agent project")
         .argument("<id>", "Subagent id")
         .argument("[path]", "Agent project directory or Spawnfile path", process.cwd())
         .action(async (id, inputPath) => {
@@ -134,6 +150,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     addCommand
         .command("team")
+        .description("Add a nested team to a team project")
         .argument("<id>", "Nested team id")
         .argument("[path]", "Team project directory or Spawnfile path", process.cwd())
         .action(async (id, inputPath) => {
@@ -147,9 +164,13 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerModelCommands(program, handlers, streams);
     registerRuntimeCommands(program, handlers, streams);
     registerSurfaceCommands(program, handlers, streams);
+    registerStatusCommand(program, handlers, streams, (exitCode) => {
+        commandExitCode = exitCode;
+    });
     registerViewCommand(program, handlers, streams, cliOptions.renderEnvironment);
     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);
@@ -170,6 +191,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
         .description("Import auth material into a local auth profile");
     authImportCommand
         .command("env")
+        .description("Import secrets from an env file into a profile")
         .argument("<file>", "Path to an env file")
         .option("-p, --profile <name>", "Auth profile name", "default")
         .action(async (filePath, options) => {
@@ -178,6 +200,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     authImportCommand
         .command("claude-code")
+        .description("Import Claude Code subscription credentials into a profile")
         .option("-p, --profile <name>", "Auth profile name", "default")
         .option("--from <directory>", "Source Claude Code config directory")
         .action(async (options) => {
@@ -186,6 +209,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     authImportCommand
         .command("codex")
+        .description("Import Codex subscription credentials into a profile")
         .option("-p, --profile <name>", "Auth profile name", "default")
         .option("--from <directory>", "Source Codex config directory")
         .action(async (options) => {
@@ -194,6 +218,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     authCommand
         .command("sync")
+        .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")
@@ -210,6 +235,7 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     authCommand
         .command("show")
+        .description("Show the contents of a local auth profile")
         .option("-p, --profile <name>", "Auth profile name", "default")
         .action(async (options) => {
         const profile = await handlers.requireAuthProfile(options.profile);
@@ -217,18 +243,16 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     });
     try {
         await program.parseAsync(argv, { from: "user" });
-        return 0;
+        return commandExitCode;
     }
     catch (error) {
         if (isCommanderError(error)) {
-            return error.exitCode === 0 ? 0 : 1;
+            // Commander prints its own usage message; usage errors exit 2.
+            return error.exitCode === 0 ? 0 : 2;
         }
-        const message = isSpawnfileError(error)
-            ? `${error.code}: ${error.message}`
-            : error instanceof Error
-                ? error.message
-                : String(error);
-        streams.stderr(message);
-        return 1;
+        streams.stderr(`error: ${formatCliErrorMessage(error)}`);
+        // Usage/input errors exit 2; runtime failures exit 1, matching the
+        // documented status exit-code contract across all commands.
+        return errorExitCode(error);
     }
 };

package/dist/cli/runtimeCommands.js

@@ -4,6 +4,7 @@ export const registerRuntimeCommands = (program, handlers, streams) => {
         .description("Edit runtime declarations");
     runtimeCommand
         .command("set")
+        .description("Set an agent's runtime binding")
         .argument("<name>", "Runtime name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--recursive", "Update the target project and its descendants")

package/dist/cli/statusCommand.d.ts

@@ -0,0 +1,42 @@
+import { Command } from "commander";
+import { inspectDockerDeployment } from "../deployment/index.js";
+import { collectDeploymentLogObservations, collectMoltnetProbeObservations, collectRuntimeProbeObservations, type StatusCommandResult, type StatusExitCode } from "../status/index.js";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+type StatusCommandHandlers = Pick<CliHandlers, "buildOrganizationView"> & Partial<Pick<CliHandlers, "requireAuthProfile">>;
+type StatusCommandLiveHandlers = {
+    collectDeploymentLogObservations?: typeof collectDeploymentLogObservations;
+    collectMoltnetProbeObservations?: typeof collectMoltnetProbeObservations;
+    collectRuntimeProbeObservations?: typeof collectRuntimeProbeObservations;
+    inspectDockerDeployment?: typeof inspectDockerDeployment;
+};
+type StatusCommandHandlersWithLive = StatusCommandHandlers & StatusCommandLiveHandlers;
+export interface StatusCommandOptions {
+    agent?: string;
+    context?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    image?: boolean;
+    json?: boolean;
+    live?: boolean;
+    logs?: boolean;
+    network?: string;
+    out?: string;
+    pretty?: boolean;
+    pull?: boolean;
+    pullCheck?: boolean;
+    quiet?: boolean;
+    recover?: boolean;
+    runtime?: string;
+    team?: string;
+    timeout?: string;
+    watch?: boolean;
+}
+export interface StatusWatchOptions {
+    intervalMs?: number;
+    iterations?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const executeStatusWatch: (inputPath: string, options: StatusCommandOptions, handlers: StatusCommandHandlersWithLive, streams: CliStreams, setExitCode: (exitCode: StatusExitCode) => void, watchOptions?: StatusWatchOptions) => Promise<void>;
+export declare const executeStatusCommand: (inputPath: string, options: StatusCommandOptions, handlers: StatusCommandHandlersWithLive) => Promise<StatusCommandResult>;
+export declare const registerStatusCommand: (program: Command, handlers: CliHandlers, streams: CliStreams, setExitCode: (exitCode: StatusExitCode) => void) => void;
+export {};