@nylorun/cli 0.1.1-beta → 0.2.0-beta

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @nylorun/cli
 
+## 0.2.0-beta
+
+### Minor Changes
+
+- b8d822a: Remove `nylorun start`. The compiled agent process is now `nylorun serve [entry]`, with the
+  same `dist/agents/index.js` default, and generated projects must change `scripts.start` to
+  `nylorun serve`. The local Runtime becomes a persistent process of its own under
+  `nylorun runtime start|stop|status|logs`, with `nylorun up` and `nylorun down` as aliases.
+  `dev` and `serve` attach to that Runtime, start one when nothing is listening, and leave it
+  running, so a watch restart re-registers agents and reconnects executors instead of
+  destroying in-flight sessions; `--no-autostart` fails instead and is what continuous
+  integration should use. Scope is per project by default in `.nylorun/`, created on first use,
+  with `--global` and `NYLORUN_HOME` for a shared Runtime in the home directory. Commands
+  report a resolved scope in every message, accept `--port` and `--db` alongside the existing
+  environment variables, expose `nylorun runtime status --output json`, and use documented exit
+  codes for usage errors, port conflicts, version skew, refused autostart and failed starts.
+- b8d822a: Add `sandbox()`: one `.use(sandbox())` gives an agent Runtime-executed `bash`, `read`, `write`, `edit`, `grep` and `glob` tools on an isolated machine with a persistent `/workspace`. The Runtime selects a microsandbox microVM where available, otherwise an in-process virtual shell, enforces deny-by-default egress presets, owns sandbox lifecycle, and reports its choice through `GET /v1/host/sandbox`, the `nylorun dev` banner and `nylorun doctor sandbox`.
+
+### Patch Changes
+
+- Pin agents to the tested release.
+- Pin runtime to the tested release.
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/agents@0.4.0-beta
+  - @nylorun/runtime@0.8.0-beta
+
+## 0.1.2-beta
+
+### Patch Changes
+
+- 3a88f51: Ship Agent-Plugins (`plugin()` / `loadPlugin`), Skills (`load_skill` / skill resources), Runtime MCP pool + vault credentials, and manifest v3 capability fields. Validate completed tool `output` against the tool output schema so ordinary tools with `outputSchema` no longer false-fail as `tool.invalid-output`.
+- Pin agents to the tested release.
+- Pin runtime to the tested release.
+- Updated dependencies [3a88f51]
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/agents@0.3.0-beta
+  - @nylorun/runtime@0.7.0-beta
+
 ## 0.1.1-beta
 
 ### Patch Changes

package/README.md

@@ -3,21 +3,56 @@
 The local `nylorun` executable. Requires Node 24+.
 
 ```sh
-nylorun configure
-nylorun dev
+nylorun up                  # start the local Runtime (alias for "nylorun runtime start")
+nylorun dev                 # watch agents/index.ts, open Studio
 nylorun dev --no-studio
-nylorun start
-nylorun studio --runtime-url http://127.0.0.1:8787
+nylorun serve [entry]       # run the compiled build, default dist/agents/index.js
+nylorun configure
+nylorun studio
+nylorun runtime status
+nylorun down                # stop the Runtime, keeping SQLite and credentials
 ```
 
-The CLI launches `@nylorun/runtime/server` in a child process, registers the
-project's exported agents with the SDK, connects scoped customer executors and
-optionally opens a project-installed `@nylorun/studio`. Runtime and executor
-credentials remain separate. Configuration lives in the existing project files;
-the SQLite database defaults to `.nylorun/runtime.sqlite`.
+## The Runtime is a separate, persistent process
+
+`nylorun up` starts `@nylorun/runtime/server` in the background and returns the
+terminal. `dev` and `serve` attach to it, registering the project's exported
+agents and connecting scoped executors through `PUT /v1/executors`. They start
+the Runtime themselves when nothing is listening, and they leave it running on
+exit, so a watch restart re-registers agents without losing sessions. Pass
+`--no-autostart` to fail instead, which is what CI should do. `--foreground`
+keeps `runtime start` attached for logs.
+
+## Scope
+
+A project is the default scope: the Runtime's SQLite, credentials, log and pid
+live in `.nylorun/` beside the nearest `package.json`, created on first use and
+added to an existing `.gitignore`. `--global` (and running outside a project)
+uses `~/.nylorun` instead, relocatable with `NYLORUN_HOME`. Both default to
+`127.0.0.1:8787`; `--port` beats `NYLORUN_PORT`, then `PORT`, then the port
+recorded for a running Runtime. `--db` or `NYLORUN_SQLITE_PATH` moves the
+database. `nylorun runtime status --output json` prints the resolved scope for
+scripts, and `nylorun logs [-f]` tails the Runtime's own output.
+
+Runtime and executor credentials remain separate. On first `configure`, `dev` or
+`serve`, an interactive terminal saves the model provider credential into the
+Runtime vault; `configure` replaces it while the Runtime is already running.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success, including `down` when nothing was running |
+| 1 | Generic failure |
+| 2 | Usage error |
+| 3 | `runtime status` or `logs`: not running |
+| 4 | Port held by another process or another scope |
+| 5 | The running Runtime does not match this CLI |
+| 6 | `--no-autostart` and nothing is listening |
+| 7 | The Runtime did not become healthy |
+| 130 / 143 | SIGINT / SIGTERM |
 
 `dev` loads `agents/index.ts` using project-installed `tsx` and watches changes.
-`start [entry]` defaults to `dist/agents/index.js` without Studio or watching.
 Studio and `tsx` are optional development dependencies; the CLI is a production
 dependency when the application's `start` script uses it.
 

package/dist/cli.js

@@ -3,14 +3,83 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { ConfigurationCancelled, configureProvider, } from "./model/configure.js";
-import { loadProjectEnvironment } from "./environment.js";
-import { develop } from "./dev.js";
-const usage = `nylorun <configure|dev|start|studio>
-  dev [--no-studio] [--no-open]
-  start [entry]
-  configure
-  studio --runtime-url <http(s)-url> [--port <n>] [--no-open]`;
-async function startStudio(agentServerUrl, open, port) {
+import { putHostModel } from "./model/host-model.js";
+import { develop, developmentPreflight } from "./dev.js";
+import { CliError } from "./errors.js";
+import { loadScopeEnvironment, resolveScope, } from "./scope.js";
+import { cliRuntimeVersion, ensureRuntime, hostStatus, startHost, stopHost, tailLog, warnIncompatible, } from "./runtime-host.js";
+import { localCredentials } from "./project-runner.js";
+const usage = `nylorun <runtime|up|down|logs|dev|serve|configure|studio|doctor>
+
+  runtime start [--foreground] [--restart] [--port <n>] [--db <path>] [--global]
+  runtime stop [--global] [--timeout <seconds>]
+  runtime status [--output json] [--global]
+  runtime logs [-f] [-n <lines>] [--global]
+  up                       alias for "runtime start"
+  down                     alias for "runtime stop"
+  logs                     alias for "runtime logs"
+
+  dev [--no-studio] [--no-open] [--no-autostart] [--port <n>]
+  serve [entry] [--no-autostart] [--port <n>]
+  configure [--global]
+  studio [--runtime-url <http(s)-url>] [--port <n>] [--no-open]
+  doctor sandbox [--json]  show which sandbox backend this machine offers`;
+/**
+ * Flags are parsed before the scope is resolved so --port can win over a PORT in .env, which
+ * is only loaded once the project root is known.
+ */
+function parseFlags(args, allowed = {}) {
+    const booleans = new Set();
+    const values = new Map();
+    const rest = [];
+    const scope = {};
+    const booleanNames = new Set(["--global", ...(allowed.booleans ?? [])]);
+    const valueNames = new Set(["--port", "--db", ...(allowed.values ?? [])]);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith("-")) {
+            rest.push(arg);
+            continue;
+        }
+        if (booleanNames.has(arg)) {
+            if (booleans.has(arg))
+                throw usageError(`${arg} may only be supplied once.`);
+            booleans.add(arg);
+            continue;
+        }
+        if (valueNames.has(arg)) {
+            if (values.has(arg))
+                throw usageError(`${arg} may only be supplied once.`);
+            const value = args[++index];
+            if (!value || value.startsWith("-"))
+                throw usageError(`${arg} requires a value.`);
+            values.set(arg, value);
+            continue;
+        }
+        throw usageError(usage);
+    }
+    if (booleans.has("--global"))
+        scope.global = true;
+    if (values.has("--port"))
+        scope.port = parsePort(values.get("--port"));
+    if (values.has("--db"))
+        scope.db = values.get("--db");
+    return { scope, rest, booleans, values };
+}
+const usageError = (message) => new CliError(message, 2);
+function parsePort(value) {
+    if (value === undefined)
+        return undefined;
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw usageError("--port must be an integer between 1 and 65535.");
+    return port;
+}
+async function serverKeyFor(scope) {
+    return (process.env.NYLORUN_SERVER_KEY ??
+        (await localCredentials(scope.credentialsPath)).serverKey);
+}
+async function startStudio(agentServerUrl, serverKey, open, port) {
     let entry;
     try {
         entry = createRequire(join(process.cwd(), "package.json")).resolve("@nylorun/studio");
@@ -21,74 +90,203 @@ async function startStudio(agentServerUrl, open, port) {
     const studio = await import(pathToFileURL(entry).href);
     return studio.startStudio({
         runtimeUrl: agentServerUrl,
-        serverKey: process.env.NYLORUN_SERVER_KEY ??
-            (await (await import("./project-runner.js")).localCredentials())
-                .serverKey,
+        serverKey,
         open,
         ...(port === undefined ? {} : { port }),
     });
 }
-function parsePort(value) {
-    if (value === undefined)
-        return undefined;
-    const port = Number(value);
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new Error("--port must be an integer between 1 and 65535.");
-    return port;
+function printStatus(status) {
+    const { scope, runtime } = status;
+    const lines = [
+        ["Scope", `${scope.kind} (${scope.kind === "project" ? scope.root : scope.dataDir})`],
+        ["State", status.state],
+        ["URL", scope.url],
+        ["PID", runtime?.pid ? String(runtime.pid) : status.pid ? String(status.pid) : undefined],
+        ["Runtime", status.version],
+        ["CLI expects", cliRuntimeVersion()],
+        ["Database", scope.sqlitePath],
+        ["Log", scope.logPath],
+        ["Started", runtime?.startedAt],
+    ];
+    const width = Math.max(...lines.map(([label]) => label.length));
+    for (const [label, value] of lines)
+        if (value !== undefined)
+            console.log(`${label.padEnd(width)}  ${value}`);
+}
+async function runtimeCommand(args) {
+    const [verb, ...rest] = args;
+    if (verb === "start") {
+        const flags = parseFlags(rest, { booleans: ["--foreground", "--restart"] });
+        if (flags.rest.length)
+            throw usageError(usage);
+        const scope = resolveScope(flags.scope);
+        loadScopeEnvironment(scope);
+        const before = await hostStatus(scope);
+        if (before.state === "running" && !flags.booleans.has("--restart")) {
+            console.log(`Runtime already running for ${scope.label} at ${scope.url} (pid ${before.runtime?.pid ?? before.pid}).`);
+            warnIncompatible(scope, before);
+            return;
+        }
+        const status = await startHost(scope, {
+            foreground: flags.booleans.has("--foreground"),
+            restart: flags.booleans.has("--restart"),
+        });
+        printStatus(status);
+        console.log(`\n→ npx nylorun dev`);
+        return;
+    }
+    if (verb === "stop") {
+        const flags = parseFlags(rest, { values: ["--timeout"] });
+        if (flags.rest.length)
+            throw usageError(usage);
+        const scope = resolveScope(flags.scope);
+        const seconds = flags.values.has("--timeout")
+            ? Number(flags.values.get("--timeout"))
+            : undefined;
+        if (seconds !== undefined && (!Number.isFinite(seconds) || seconds <= 0))
+            throw usageError("--timeout must be a positive number of seconds.");
+        const result = await stopHost(scope, {
+            ...(seconds === undefined ? {} : { timeoutMs: seconds * 1000 }),
+        });
+        console.log(result === "stopped"
+            ? `Stopped the Runtime for ${scope.label}. SQLite and credentials are kept in ${scope.dataDir}.`
+            : `No Runtime is running for ${scope.label}.`);
+        return;
+    }
+    if (verb === "status") {
+        const flags = parseFlags(rest, { values: ["--output"] });
+        if (flags.rest.length)
+            throw usageError(usage);
+        const output = flags.values.get("--output") ?? "text";
+        if (output !== "text" && output !== "json")
+            throw usageError("--output must be text or json.");
+        const scope = resolveScope(flags.scope);
+        const status = await hostStatus(scope);
+        if (output === "json")
+            console.log(JSON.stringify({
+                scope: scope.kind,
+                root: scope.kind === "project" ? scope.root : scope.dataDir,
+                url: scope.url,
+                state: status.state,
+                pid: status.runtime?.pid ?? status.pid ?? null,
+                runtimeVersion: status.version ?? null,
+                cliVersion: cliRuntimeVersion() ?? null,
+                scopeId: status.scopeId ?? null,
+                sqlitePath: scope.sqlitePath,
+                logPath: scope.logPath,
+                startedAt: status.runtime?.startedAt ?? null,
+            }, null, 2));
+        else
+            printStatus(status);
+        if (status.state !== "running")
+            process.exitCode = status.state === "port-conflict" ? 4 : 3;
+        return;
+    }
+    if (verb === "logs") {
+        const flags = parseFlags(rest, { booleans: ["-f"], values: ["-n"] });
+        if (flags.rest.length)
+            throw usageError(usage);
+        const lines = flags.values.has("-n") ? Number(flags.values.get("-n")) : 200;
+        if (!Number.isInteger(lines) || lines < 1)
+            throw usageError("-n must be a positive integer.");
+        await tailLog(resolveScope(flags.scope), {
+            follow: flags.booleans.has("-f"),
+            lines,
+        });
+        return;
+    }
+    throw usageError(usage);
 }
 async function main() {
-    const [command, ...args] = process.argv.slice(2);
-    if (!command || command === "--help" || command === "-h")
+    const [rawCommand, ...rawArgs] = process.argv.slice(2);
+    if (!rawCommand || rawCommand === "--help" || rawCommand === "-h")
         return void console.log(usage);
-    if (["configure", "dev", "start"].includes(command))
-        loadProjectEnvironment();
-    if (command === "start") {
-        if (args.length > 1 || args[0]?.startsWith("--"))
-            throw new Error(usage);
-        await (await import("./launcher.js")).start(args[0]);
+    const aliases = {
+        up: "start",
+        down: "stop",
+        logs: "logs",
+    };
+    const command = rawCommand in aliases ? "runtime" : rawCommand;
+    const args = rawCommand in aliases ? [aliases[rawCommand], ...rawArgs] : rawArgs;
+    if (command === "runtime")
+        return await runtimeCommand(args);
+    if (command === "doctor") {
+        const [topic, ...options] = args;
+        if (topic !== "sandbox" || options.some((option) => option !== "--json"))
+            throw usageError("Usage: nylorun doctor sandbox [--json]");
+        const { doctorSandbox } = await import("./doctor.js");
+        await doctorSandbox({ json: options.includes("--json") });
         return;
     }
     if (command === "dev") {
-        process.exitCode = await develop(args);
+        const flags = parseFlags(args, {
+            booleans: ["--no-studio", "--no-open", "--no-autostart"],
+        });
+        if (flags.rest.length)
+            throw usageError(usage);
+        const scope = resolveScope(flags.scope);
+        loadScopeEnvironment(scope);
+        // The port is re-resolved after .env so a project file can set PORT, while --port wins.
+        const resolved = resolveScope(flags.scope);
+        process.env.PORT = String(resolved.port);
+        developmentPreflight([...flags.booleans]);
+        // The supervisor checks the host before spawning tsx so port conflicts, version skew and
+        // --no-autostart surface with their own exit codes instead of a generic watcher failure.
+        await ensureRuntime(resolved, {
+            autostart: !flags.booleans.has("--no-autostart"),
+        });
+        process.exitCode = await develop([...flags.booleans]);
+        return;
+    }
+    if (command === "serve") {
+        const flags = parseFlags(args, { booleans: ["--no-autostart"] });
+        if (flags.rest.length > 1)
+            throw usageError(usage);
+        const scope = resolveScope(flags.scope);
+        loadScopeEnvironment(scope);
+        const resolved = resolveScope(flags.scope);
+        // serve runs the project in this process, so runProject's own errors carry their exit
+        // codes out; it validates the agent registry before it touches the host.
+        await (await import("./launcher.js")).serve(flags.rest[0], {
+            autostart: !flags.booleans.has("--no-autostart"),
+            scope: resolved,
+        });
         return;
     }
     if (command === "configure") {
-        if (args.length)
-            throw new Error(usage);
+        const flags = parseFlags(args);
+        if (flags.rest.length)
+            throw usageError(usage);
+        const scope = resolveScope(flags.scope);
+        loadScopeEnvironment(scope);
         const controller = new AbortController();
         const cancel = (signal) => controller.abort(new ConfigurationCancelled(signal));
         process.once("SIGINT", () => cancel("SIGINT"));
         process.once("SIGTERM", () => cancel("SIGTERM"));
-        await configureProvider({ signal: controller.signal });
+        const serverKey = await serverKeyFor(scope);
+        const health = await fetch(`${scope.url}/health`).catch(() => undefined);
+        if (!health?.ok)
+            throw new CliError(`No Runtime is listening at ${scope.url} for ${scope.label}. Start one with "nylorun up".`, 6);
+        const prompted = await configureProvider({ signal: controller.signal });
+        await putHostModel(scope.url, serverKey, prompted);
         return;
     }
     if (command !== "studio")
-        throw new Error(usage);
-    let agentUrl;
-    let port;
-    let open = true;
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (arg === "--runtime-url") {
-            if (agentUrl !== undefined)
-                throw new Error("--runtime-url may only be supplied once.");
-            agentUrl = args[++index];
-            if (!agentUrl || agentUrl.startsWith("--"))
-                throw new Error("--runtime-url requires a value.");
-        }
-        else if (arg === "--port") {
-            if (port !== undefined)
-                throw new Error("--port may only be supplied once.");
-            port = parsePort(args[++index]);
-        }
-        else if (arg === "--no-open" && open)
-            open = false;
-        else
-            throw new Error(usage);
-    }
-    if (!agentUrl)
-        throw new Error("--runtime-url is required.");
-    const dashboard = await startStudio(agentUrl, open, port);
+        throw usageError(usage);
+    const flags = parseFlags(args, {
+        booleans: ["--no-open"],
+        values: ["--runtime-url", "--studio-port"],
+    });
+    if (flags.rest.length)
+        throw usageError(usage);
+    const scope = resolveScope(flags.scope);
+    const runtimeUrl = flags.values.get("--runtime-url") ?? scope.url;
+    const studioPort = flags.values.has("--studio-port")
+        ? parsePort(flags.values.get("--studio-port"))
+        : flags.scope.port !== undefined && flags.values.has("--runtime-url")
+            ? flags.scope.port
+            : undefined;
+    const dashboard = await startStudio(runtimeUrl, await serverKeyFor(scope), !flags.booleans.has("--no-open"), studioPort);
     console.log(`Studio on ${dashboard.address}`);
     await new Promise((resolve, reject) => {
         const close = () => void dashboard.close().then(resolve, reject);
@@ -96,8 +294,19 @@ async function main() {
         process.once("SIGTERM", close);
     });
 }
-void main().catch((error) => {
+/**
+ * Probing a port that answers but is not a Runtime can leave a pooled connection holding the
+ * event loop open, so a finished command exits explicitly once its output has drained.
+ */
+async function finish(code) {
+    process.exitCode = code;
+    for (const stream of [process.stdout, process.stderr])
+        await new Promise((resolve) => stream.write("", () => resolve()));
+    process.exit(code);
+}
+void main().then(() => finish(process.exitCode === undefined ? 0 : Number(process.exitCode)), (error) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode =
-        error instanceof ConfigurationCancelled ? error.exitCode : 1;
+    return finish(error instanceof ConfigurationCancelled || error instanceof CliError
+        ? error.exitCode
+        : 1);
 });

package/dist/dev-entry.js

@@ -2,4 +2,5 @@ import { runProject } from "./project-runner.js";
 await runProject("agents/index.ts", {
     studio: !process.argv.includes("--no-studio"),
     open: !process.argv.includes("--no-open"),
+    autostart: !process.argv.includes("--no-autostart"),
 });

package/dist/dev.d.ts

@@ -1 +1,6 @@
+/**
+ * Everything that can be checked without contacting the host, so a project that cannot run
+ * never causes a Runtime to be started on its behalf.
+ */
+export declare function developmentPreflight(args: readonly string[]): string;
 export declare function develop(args: readonly string[]): Promise<number>;

package/dist/dev.js

@@ -2,13 +2,14 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-export async function develop(args) {
+/**
+ * Everything that can be checked without contacting the host, so a project that cannot run
+ * never causes a Runtime to be started on its behalf.
+ */
+export function developmentPreflight(args) {
     if (new Set(args).size !== args.length ||
-        args.some((arg) => !["--no-studio", "--no-open"].includes(arg)))
-        throw new Error("Usage: nylorun dev [--no-studio] [--no-open]");
-    const port = Number(process.env.PORT ?? 8787);
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new Error("PORT must be between 1 and 65535");
+        args.some((arg) => !["--no-studio", "--no-open", "--no-autostart"].includes(arg)))
+        throw new Error("Usage: nylorun dev [--no-studio] [--no-open] [--no-autostart]");
     const require = createRequire(join(process.cwd(), "package.json"));
     let tsx;
     try {
@@ -24,6 +25,10 @@ export async function develop(args) {
         catch {
             throw new Error("Install @nylorun/studio or use --no-studio");
         }
+    return tsx;
+}
+export async function develop(args) {
+    const tsx = developmentPreflight(args);
     const child = spawn(process.execPath, [
         tsx,
         "watch",

package/dist/doctor.d.ts

@@ -0,0 +1,7 @@
+import type { AgentManifest } from "@nylorun/agents";
+/** `nylorun doctor sandbox`: what this machine offers and what a Runtime here would pick. */
+export declare function doctorSandbox(options: {
+    json: boolean;
+}): Promise<void>;
+/** One line for the dev banner, or undefined when no connected agent declares a sandbox. */
+export declare function sandboxBanner(runtimeUrl: string, serverKey: string, manifests: readonly AgentManifest[]): Promise<string | undefined>;

package/dist/doctor.js

@@ -0,0 +1,61 @@
+import { release } from "node:os";
+import { probeSandboxBackends, } from "@nylorun/runtime/node";
+const LABEL = {
+    microsandbox: "microsandbox VM",
+    virtual: "virtual shell",
+};
+/** `nylorun doctor sandbox`: what this machine offers and what a Runtime here would pick. */
+export async function doctorSandbox(options) {
+    const report = await probeSandboxBackends();
+    if (options.json) {
+        console.log(JSON.stringify({ platform: platform(), ...report }, null, 2));
+        return;
+    }
+    const rows = [["platform", platform()]];
+    for (const probe of report.probes)
+        rows.push([
+            probe.name,
+            `${probe.available ? "✓" : "✗"} ${probe.reason ?? ""}${probe.version ? ` · ${probe.version}` : ""}`,
+        ]);
+    rows.push(["preference", report.preference === "auto" ? "auto (set NYLORUN_SANDBOX to force one)" : report.preference]);
+    rows.push(["selected", report.backend ? `${report.backend} (${report.isolation} isolation)` : `none: ${report.reason}`]);
+    const width = Math.max(...rows.map(([key]) => key.length)) + 2;
+    for (const [key, value] of rows)
+        console.log(`  ${key.padEnd(width)}${value}`);
+    if (report.backend === "virtual")
+        console.log("\n  The virtual shell emulates bash in the Runtime process; it is not a VM boundary.\n" +
+            "  For hardware isolation use macOS on Apple Silicon or Linux with KVM.");
+}
+/** One line for the dev banner, or undefined when no connected agent declares a sandbox. */
+export async function sandboxBanner(runtimeUrl, serverKey, manifests) {
+    const capability = manifests
+        .flatMap((manifest) => manifest.capabilities)
+        .find((item) => item.sandbox);
+    if (!capability)
+        return undefined;
+    let report;
+    try {
+        const response = await fetch(`${runtimeUrl}/v1/host/sandbox`, {
+            headers: { authorization: `Bearer ${serverKey}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (response.ok)
+            report = await response.json();
+    }
+    catch { }
+    if (!report)
+        return undefined;
+    const doctor = "run `npx nylorun doctor sandbox` for options";
+    if (!report.backend)
+        return `sandbox: unavailable (${report.reason}) · ${doctor}`;
+    const image = capability.sandbox?.image ?? report.defaultImage;
+    const network = capability.sandbox?.network?.preset ?? "dev";
+    const fellBack = report.preference === "auto" && report.backend !== report.probes[0]?.name;
+    return fellBack
+        ? `sandbox: ${LABEL[report.backend] ?? report.backend} (${report.reason}) · ${doctor}`
+        : `sandbox: ${LABEL[report.backend] ?? report.backend}${report.backend === "microsandbox" && image ? ` · image ${image}` : ""} · network: ${network}`;
+}
+function platform() {
+    const os = process.platform === "darwin" ? "macOS" : process.platform === "win32" ? "Windows" : process.platform;
+    return `${os} (kernel ${release()}) · ${process.arch}`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/** Exit codes are part of the CLI contract; see cli/README.md. */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** Exit codes are part of the CLI contract; see cli/README.md. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}

package/dist/launcher.d.ts

@@ -1 +1,5 @@
-export declare function start(entry?: string): Promise<void>;
+import type { Scope } from "./scope.js";
+export declare function serve(entry?: string, options?: {
+    autostart?: boolean;
+    scope?: Scope;
+}): Promise<void>;

package/dist/launcher.js

@@ -1,4 +1,4 @@
 import { runProject } from "./project-runner.js";
-export async function start(entry = "dist/agents/index.js") {
-    await runProject(entry);
+export async function serve(entry = "dist/agents/index.js", options = {}) {
+    await runProject(entry, options);
 }