spawnfile 0.1.11 → 0.1.13

package/README.md

@@ -37,12 +37,25 @@ 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 up . --context gpu-4090 --detach       # build and run on a Docker context
+spawnfile dev up . --auth-profile dev            # detached dev loop in .spawn-dev
+spawnfile dev apply . --agent researcher         # hot-add/reload one Pi agent
+spawnfile dev activity . --agent researcher      # inspect buffered Pi activity events
+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.
+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. Daimon, OpenClaw, and PicoClaw use published copyable artifact images by default, so normal prompt/config edits reuse their dependency layers. To test a local runtime artifact instead, set `SPAWNFILE_DAIMON_RUNTIME_IMAGE`, `SPAWNFILE_OPENCLAW_RUNTIME_IMAGE`, or `SPAWNFILE_PICOCLAW_RUNTIME_IMAGE` to a local image tag. For Pi-heavy orgs, build a reusable runtime base with `npm run runtime:pi-base -- noopolis/spawnfile-pi-runtime:0.79.9-node24`, then set `SPAWNFILE_PI_RUNTIME_BASE_IMAGE` during `spawnfile up`. For `build`/`up` on a docker `--context`, Moltnet release assets are staged for that context's architecture (`amd64` or `arm64`); for local-only manual compile targeting a fixed architecture, set `SPAWNFILE_MOLTNET_TARGET_ARCH=amd64|arm64`.
+
+`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. For a remote Docker context where the local record is missing, pass `--context <name>` with `--live` to recover the deployment from Spawnfile container labels.
+
+`spawnfile dev` is the source-backed interactive loop. It uses `.spawn-dev/` by default, starts a detached dev deployment with `spawnfile dev up`, and can hot-apply one Daimon runtime agent with `spawnfile dev apply --agent <id>` without restarting the rest of the org. Hot apply recompiles source, copies the selected agent workspace, Daimon config, matching Moltnet node configs, and managed Moltnet server configs into the running container, loads it through the Daimon control endpoint, and starts only that agent's Moltnet bridges when it is new. `spawnfile dev activity` reads the generated Daimon app's bounded activity buffer as JSON lines so operators can see queued wakes, turn starts/completions, runtime event types, output completions, and errors without mixing those diagnostics into Moltnet chat. Running managed Moltnet servers keep their current in-memory room membership until an operator-token `moltnet apply` or server restart reconciles the copied server config.
+
+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.
 
@@ -91,9 +104,12 @@ 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)   |
+| Pi        | active        |         | Embedded org app, Moltnet client config       |
 | 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 +129,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/auth/runtimeCredentials.js

@@ -14,6 +14,21 @@ const parseJson = (filePath, content) => {
         throw new SpawnfileError("validation_error", `Invalid imported auth file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 };
+const decodeJwtExpiry = (token) => {
+    const payload = token.split(".")[1];
+    if (!payload) {
+        return null;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        return typeof decoded.exp === "number" && Number.isFinite(decoded.exp)
+            ? decoded.exp * 1000
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
 export const loadImportedClaudeCodeCredential = async (sourceDirectory) => {
     const credentialsPath = path.join(sourceDirectory, ".credentials.json");
     if (!(await fileExists(credentialsPath))) {
@@ -66,11 +81,12 @@ export const loadImportedCodexCredential = async (sourceDirectory) => {
         refresh.length === 0) {
         return null;
     }
-    const fileStats = await stat(authPath);
+    const jwtExpiry = decodeJwtExpiry(access);
+    const expires = jwtExpiry ?? (await stat(authPath)).mtimeMs + 60 * 60 * 1000;
     return {
         access,
         ...(typeof accountId === "string" && accountId.length > 0 ? { accountId } : {}),
-        expires: fileStats.mtimeMs + 60 * 60 * 1000,
+        expires,
         refresh
     };
 };

package/dist/cli/devCommands.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export declare const registerDevCommands: (program: Command, handlers: CliHandlers, streams: CliStreams) => void;

package/dist/cli/devCommands.js

@@ -0,0 +1,115 @@
+import { InvalidArgumentError } from "commander";
+const parsePositiveIntegerOption = (value) => {
+    if (!/^[1-9]\d*$/u.test(value)) {
+        throw new InvalidArgumentError("must be a positive integer");
+    }
+    return Number(value);
+};
+export const registerDevCommands = (program, handlers, streams) => {
+    const dev = program.command("dev").description("Run an interactive Spawnfile development deployment");
+    dev
+        .command("up")
+        .description("Compile, build, and start a detached dev deployment under .spawn-dev")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .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("--env-file <file>", "Path to an env file for runtime secrets")
+        .option("--name <container>", "Docker container name")
+        .option("-o, --out <directory>", "Dev output directory")
+        .option("-t, --tag <image>", "Docker image tag")
+        .action(async (inputPath, options) => {
+        const result = await handlers.devUpProject(inputPath, {
+            authProfile: options.authProfile,
+            containerName: options.name,
+            deploymentName: options.deployment,
+            dockerCommand: options.dockerCommand,
+            dockerContext: options.context,
+            envFilePath: options.envFile,
+            imageTag: options.tag,
+            outputDirectory: options.out
+        });
+        streams.stdout(`dev deployment: ${result.containerName ?? "unknown"}`);
+        streams.stdout(`image: ${result.imageTag}`);
+        streams.stdout(`compiled to ${result.outputDirectory}`);
+        if (result.deploymentRecordPath) {
+            streams.stdout(`record: ${result.deploymentRecordPath}`);
+        }
+    });
+    dev
+        .command("apply")
+        .description("Hot-apply one agent into a running dev deployment")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--agent <id>", "Agent id, slug, or name to hot-apply")
+        .option("--deployment <name>", "Detached deployment record name")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Dev output directory")
+        .action(async (inputPath, options) => {
+        const result = await handlers.devApplyProject(inputPath, {
+            agent: options.agent,
+            deploymentName: options.deployment,
+            dockerCommand: options.dockerCommand,
+            outputDirectory: options.out
+        });
+        streams.stdout(`applied agent ${result.agentId}`);
+        streams.stdout(`container: ${result.containerName}`);
+        streams.stdout(`bridge: ${result.bridgeStarted ? "started" : "unchanged"}`);
+    });
+    dev
+        .command("restart")
+        .description("Reload one agent in a running dev deployment")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--agent <id>", "Agent id, slug, or name to reload")
+        .option("--deployment <name>", "Detached deployment record name")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Dev output directory")
+        .action(async (inputPath, options) => {
+        const result = await handlers.devRestartProject(inputPath, {
+            agent: options.agent,
+            deploymentName: options.deployment,
+            dockerCommand: options.dockerCommand,
+            outputDirectory: options.out
+        });
+        streams.stdout(`restarted agent ${result.agentId}`);
+        streams.stdout(`container: ${result.containerName}`);
+        streams.stdout(`bridge: ${result.bridgeStarted ? "started" : "unchanged"}`);
+    });
+    dev
+        .command("activity")
+        .description("Print the current Pi agent activity buffer from a running dev deployment")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--agent <id>", "Only show events for one agent id, slug, or name")
+        .option("--deployment <name>", "Detached deployment record name")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Dev output directory")
+        .option("--tail <count>", "Maximum buffered events to print", parsePositiveIntegerOption)
+        .action(async (inputPath, options) => {
+        const result = await handlers.devActivityProject(inputPath, {
+            agent: options.agent,
+            deploymentName: options.deployment,
+            dockerCommand: options.dockerCommand,
+            outputDirectory: options.out,
+            tail: options.tail
+        });
+        for (const event of result.events) {
+            streams.stdout(JSON.stringify(event));
+        }
+    });
+    dev
+        .command("stop")
+        .description("Stop the recorded dev deployment container")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--deployment <name>", "Detached deployment record name")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Dev output directory")
+        .action(async (inputPath, options) => {
+        const result = await handlers.devStopProject(inputPath, {
+            deploymentName: options.deployment,
+            dockerCommand: options.dockerCommand,
+            outputDirectory: options.out
+        });
+        streams.stdout(`stopped dev deployment ${result.deploymentName}`);
+        streams.stdout(`container: ${result.containerName}`);
+    });
+};

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,12 +31,15 @@ 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("--context <name>", "Docker context for the build target")
         .option("--docker-command <command>", "Docker command")
         .option("-o, --out <directory>", "Output directory")
         .option("-t, --tag <image>", "Docker image tag")
         .action(async (inputPath, options) => {
         const result = await handlers.buildProject(inputPath, {
+            dockerContext: options.context,
             dockerCommand: options.dockerCommand,
             imageTag: options.tag,
             outputDirectory: options.out
@@ -26,20 +50,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 +90,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,7 @@
 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 { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
+import { consumeImageUp } from "../distribution/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
 export interface CliStreams {
     stderr: (message: string) => void;
@@ -15,6 +17,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 +33,12 @@ export interface CliHandlers {
     requireAuthProfile: typeof requireAuthProfile;
     runProject: typeof runProject;
     upProject: typeof upProject;
+    consumeImageUp: typeof consumeImageUp;
+    devActivityProject: typeof devActivityProject;
+    devApplyProject: typeof devApplyProject;
+    devRestartProject: typeof devRestartProject;
+    devStopProject: typeof devStopProject;
+    devUpProject: typeof devUpProject;
     setProjectPrimaryModel: typeof setProjectPrimaryModel;
     setProjectRuntime: typeof setProjectRuntime;
     setProjectSurfaceAccess: typeof setProjectSurfaceAccess;

package/dist/cli/runCli.js

@@ -1,13 +1,17 @@
 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 { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
+import { consumeImageUp } from "../distribution/index.js";
+import { errorExitCode, isSpawnfileError } from "../shared/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
+import { registerDevCommands } from "./devCommands.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 +28,13 @@ 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,
+    devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject,
     setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth
 });
 const isCliStreams = (value) => {
@@ -62,6 +67,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 +97,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();
@@ -91,8 +107,10 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
         writeOut: (message) => writeCommanderOutput(streams.stdout, message)
     });
     registerLifecycleCommands(program, handlers, streams);
+    registerDevCommands(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 +126,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 +141,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 +154,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 +168,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 +195,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 +204,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 +213,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 +222,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 +239,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 +247,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);
     }
 };