@yolo-labs/yolo-cli 0.23.0

package/dist/run-list.js

@@ -0,0 +1,148 @@
+/**
+ * `yolo run list` — list Plan Runs in the current workspace.
+ *
+ * Read companion to the run lifecycle slice. After starting/transitioning
+ * runs, an operator wants a "what runs are in this workspace?" view
+ * without remembering planRunIds. Maps to `work.list_runs` (added on
+ * the server side as part of this slice).
+ *
+ * Two output modes:
+ *   - default (`--summary`): one row per run with planRunId, planId,
+ *     run #, executionState, operator, startedAt.
+ *   - `--json`: pretty-printed raw `runs[]` for jq pipelines.
+ *
+ * Filter: `--state <pending|running|paused|succeeded|failed|cancelled|superseded>`
+ * passed as `?executionState=` query string for server-side filtering.
+ *
+ * Exit codes:
+ *   - 0  = success (zero runs is also success — empty list, not an error)
+ *   - 1  = http (e.g., 401 from a revoked token)
+ *   - 64 = usage (bad --state, missing env, --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+const ALLOWED_STATES = [
+    'pending',
+    'running',
+    'paused',
+    'succeeded',
+    'failed',
+    'cancelled',
+    'superseded',
+];
+// ─── Public entry ─────────────────────────────────────────────────────────
+export async function runRunList(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (options.stateFilter !== undefined && !ALLOWED_STATES.includes(options.stateFilter)) {
+        return fail('usage', `invalid --state '${options.stateFilter}': must be one of ${ALLOWED_STATES.join(', ')}`);
+    }
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_RUN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const path = options.stateFilter
+        ? `/workspaces/${mint.workspaceId}/runs?executionState=${options.stateFilter}`
+        : `/workspaces/${mint.workspaceId}/runs`;
+    const response = await authenticatedRequest(ctx, path, { method: 'GET' });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.list_runs failed: HTTP ${response.status} — ${text}`, {
+            status: response.status,
+        });
+    }
+    const json = (await response.json());
+    if (!Array.isArray(json.runs)) {
+        return fail('http', 'work.list_runs response missing `runs` array');
+    }
+    return {
+        ok: true,
+        output: format === 'json'
+            ? formatJson(json.runs)
+            : formatSummary(json.runs, mint.workspaceId, options.stateFilter),
+        runs: json.runs,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+/**
+ * Header + one row per run. Columns (auto-padded):
+ *   planRunId  planId  #N  state  operator  startedAt
+ * Empty list renders "(no runs)" instead of just a header.
+ */
+export function formatSummary(runs, workspaceId, stateFilter) {
+    const lines = [];
+    const filterTag = stateFilter ? ` (filter: ${stateFilter})` : '';
+    lines.push(`Plan Runs in workspace ${workspaceId}${filterTag}: ${runs.length}`);
+    if (runs.length === 0) {
+        lines.push('  (no runs)');
+        return lines.join('\n');
+    }
+    const idCol = Math.max(9, ...runs.map((r) => r.planRunId.length));
+    const planCol = Math.max(6, ...runs.map((r) => r.planId.length));
+    const stateCol = Math.max(5, ...runs.map((r) => r.executionState.length));
+    const operatorCol = Math.max(8, ...runs.map((r) => (r.operatorAgentId ?? '(unbound)').length));
+    const header = `  ${'planRunId'.padEnd(idCol)}  ${'planId'.padEnd(planCol)}  run#   ${'state'.padEnd(stateCol)}  ${'operator'.padEnd(operatorCol)}  startedAt`;
+    lines.push(header);
+    for (const r of runs) {
+        const id = r.planRunId.padEnd(idCol);
+        const plan = r.planId.padEnd(planCol);
+        const runNum = `#${r.runNumber}`.padEnd(5);
+        const state = r.executionState.padEnd(stateCol);
+        const operator = (r.operatorAgentId ?? '(unbound)').padEnd(operatorCol);
+        lines.push(`  ${id}  ${plan}  ${runNum}  ${state}  ${operator}  ${r.startedAt}`);
+    }
+    return lines.join('\n');
+}
+function formatJson(runs) {
+    return JSON.stringify(runs, null, 2);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64;
+        case 'http':
+            return 1;
+    }
+}

package/dist/run-start.js

@@ -0,0 +1,110 @@
+/**
+ * `yolo run start <planId>` — bootstrap a Plan Run via work.start_run.
+ *
+ * Mints a session-bound delegated token (work.start_run scope) and
+ * POSTs to `/internal/work/workspaces/<wsId>/runs` with the planId
+ * and (optional) inputs. The route handler (common-api/src/routes/
+ * work.ts) binds `operatorAgentId: ctx.agentId` — so a Run started
+ * via this verb has `operatorAgentId === 'substrate-cli'` and only
+ * the substrate CLI can pause/resume/cancel it via MCP.
+ *
+ * Inputs: passed as a JSON object literal via `--inputs '<json>'`.
+ * If absent, defaults to `{}` (the route accepts that and lets Plan
+ * input validation reject if any inputs were declared as required).
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (plan not found, plan not active, validation failure)
+ *   - 64 = usage (bad planId, malformed --inputs JSON, missing env
+ *          trio, --workspace mismatch)
+ */
+import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+export async function runRunStart(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (!PLAN_ID_REGEX.test(options.planId)) {
+        return fail('usage', `invalid planId '${options.planId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/`);
+    }
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_RUN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const body = { planId: options.planId };
+    if (options.inputs !== undefined)
+        body.inputs = options.inputs;
+    const response = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/runs`, { method: 'POST', jsonBody: body });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.start_run failed: HTTP ${response.status} — ${text}`, { status: response.status });
+    }
+    const json = (await response.json());
+    if (typeof json.planRunId !== 'string' || !json.planRunId) {
+        return fail('http', 'work.start_run response missing planRunId');
+    }
+    return {
+        ok: true,
+        output: format === 'json' ? formatJson(json) : formatSummary(json, options.planId),
+        response: json,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+export function formatSummary(response, planId) {
+    const operatorTag = response.operatorAgentId ? `operator=${response.operatorAgentId}` : 'operator=(unbound)';
+    return `OK: started run ${response.planRunId} for plan ${planId} (run #${response.runNumber}, executionState=${response.executionState}, ${operatorTag})`;
+}
+function formatJson(response) {
+    return JSON.stringify(response, null, 2);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64;
+        case 'http':
+            return 1;
+    }
+}

package/dist/run-transfer.js

@@ -0,0 +1,128 @@
+/**
+ * `yolo run transfer <runId> --to <agentId>` — change a Run's bound
+ * Operator. The handoff verb that closes the loop on the lifecycle
+ * slice's operator-binding implication.
+ *
+ * Natural use case: `yolo run start <planId>` makes substrate-cli
+ * the Operator; `yolo run transfer <runId> --to claude` hands the
+ * Run off to claude/codex for actual execution. The route's R4
+ * matrix permits self-transfer (current Operator → new agent),
+ * claim-user-driven (taking over a Run with operatorAgentId=null),
+ * and force-transfer of an unresponsive Operator.
+ *
+ * Target validation: the route enforces `isValidOperatorTarget` —
+ * target must be in OPERATOR_TIER_AGENT_IDS (claude, codex) or
+ * null (user-driven). Substrate-cli is NOT Operator-tier, so
+ * `--to substrate-cli` always fails at the route layer with 403
+ * NOT_AUTHORIZED + reason=invalid_transfer_target.
+ *
+ * Errors map to exit codes via the CLI wrapper:
+ *   - 0  = success
+ *   - 1  = http (404, 403 NOT_AUTHORIZED, 409 INVALID_STATE, 5xx)
+ *   - 64 = usage (bad runId, missing env trio, --workspace mismatch,
+ *          --to + --user-driven mutex violation, missing target)
+ */
+import { SUBSTRATE_CLI_RUN_SCOPES, WorkClientError, authenticatedRequest, mintSubstrateToken, } from './work-client.js';
+import { resolveSubstrateContext } from './auth-context.js';
+// ─── Public entry ─────────────────────────────────────────────────────────
+const PLAN_RUN_ID_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/;
+const AGENT_ID_MAX_LEN = 128;
+export async function runRunTransfer(options) {
+    const env = options.env ?? process.env;
+    const format = options.outputFormat ?? 'summary';
+    if (!PLAN_RUN_ID_REGEX.test(options.planRunId)) {
+        return fail('usage', `invalid planRunId '${options.planRunId}': must match /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,191}$/`);
+    }
+    // Target must be a non-empty string ≤128 chars or explicit null.
+    // Mirrors the route's pre-store check so we fail fast without a
+    // network round-trip.
+    if (options.newOperatorAgentId !== null &&
+        (typeof options.newOperatorAgentId !== 'string' ||
+            options.newOperatorAgentId.length === 0 ||
+            options.newOperatorAgentId.length > AGENT_ID_MAX_LEN)) {
+        return fail('usage', `newOperatorAgentId must be a non-empty string ≤${AGENT_ID_MAX_LEN} chars or null`);
+    }
+    const auth = resolveSubstrateContext(env);
+    if (!auth.ok)
+        return fail('auth', auth.message);
+    const { sessionId, commonApiUrl, userToken } = auth.context;
+    let mint;
+    try {
+        mint = await mintSubstrateToken({
+            commonApiUrl,
+            userToken,
+            sessionId,
+            scopes: SUBSTRATE_CLI_RUN_SCOPES,
+            fetchImpl: options.fetchImpl,
+        });
+    }
+    catch (err) {
+        if (err instanceof WorkClientError) {
+            return fail('auth', `failed to mint substrate token: ${err.message}`, { status: err.status, code: err.code });
+        }
+        return fail('auth', `failed to mint substrate token: ${describeError(err)}`);
+    }
+    if (options.workspaceFlag && options.workspaceFlag !== mint.workspaceId) {
+        return fail('workspace_mismatch', `--workspace ${options.workspaceFlag} does not match the workspace bound to this session (${mint.workspaceId}).`);
+    }
+    const ctx = {
+        commonApiUrl,
+        delegatedToken: mint.token,
+        fetchImpl: options.fetchImpl,
+    };
+    const response = await authenticatedRequest(ctx, `/workspaces/${mint.workspaceId}/runs/${options.planRunId}/operator/transfer`, { method: 'POST', jsonBody: { newOperatorAgentId: options.newOperatorAgentId } });
+    if (!response.ok) {
+        const text = await safeReadText(response);
+        return fail('http', `work.transfer_run_operator failed: HTTP ${response.status} — ${text}`, {
+            status: response.status,
+        });
+    }
+    const json = (await response.json());
+    if (typeof json.planRunId !== 'string') {
+        return fail('http', 'work.transfer_run_operator response missing planRunId');
+    }
+    return {
+        ok: true,
+        output: format === 'json' ? formatJson(json) : formatSummary(json),
+        response: json,
+        workspaceId: mint.workspaceId,
+    };
+}
+// ─── Output formatting ────────────────────────────────────────────────────
+export function formatSummary(response) {
+    const target = response.operatorAgentId === null
+        ? 'user-driven (primaryOperator=null)'
+        : response.operatorAgentId;
+    // operatorCount surfaces the size of the additive operators[];
+    // the legacy operatorHistoryLength was removed in item 16.
+    const count = response.operatorCount ?? 0;
+    return `OK: transferred run ${response.planRunId} primary to ${target} (operatorCount=${count})`;
+}
+function formatJson(response) {
+    return JSON.stringify(response, null, 2);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function fail(kind, message, detail) {
+    return { ok: false, kind, message, detail };
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+export function exitCodeForFailure(kind) {
+    switch (kind) {
+        case 'usage':
+        case 'auth':
+        case 'workspace_mismatch':
+            return 64;
+        case 'http':
+            return 1;
+    }
+}

package/dist/serve.js

@@ -0,0 +1,227 @@
+/**
+ * `yolo serve <dir>` — a minimal, dependency-free static file server.
+ *
+ * Purpose (BAKE_OFF / decision-preview Gap 2a): a `mode:workstream`
+ * candidate that produces a STATIC site (index.html + assets, no dev
+ * server) has nothing to preview. The substrate auto-spawns a preview tile
+ * whose command is `yolo serve <lane-worktree> --port $PORT` so the operator
+ * can SEE each bake-off variant before picking a winner — without the agent
+ * having to ship a server or an operator hand-rolling `python3 -m http.server`.
+ *
+ * Deliberately built on Node's stdlib only (http/fs/path) so it has zero
+ * install cost and starts instantly in any sandbox. Long-running: it binds
+ * the port and runs until the process is killed (the preview-manager owns
+ * the lifecycle), so the command never "completes".
+ *
+ * Usage:
+ *   yolo serve <dir> [--port N] [--host H] [--spa] [--no-cache]
+ *     <dir>        directory to serve (required)
+ *     --port N     port (default: $PORT, else 3000)
+ *     --host H     bind host (default: 0.0.0.0 — reachable by preview-manager)
+ *     --spa        serve index.html for unmatched routes (single-page apps)
+ *     --no-cache   send no-store (default; previews should always be fresh)
+ */
+import * as http from 'http';
+import * as fs from 'fs';
+import * as path from 'path';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.map': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.wasm': 'application/wasm',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+};
+/** Parse `yolo serve` args. Exported for tests. Returns the options or a
+ *  usage error string. */
+export function parseServeArgs(args) {
+    let dir;
+    let port;
+    let host = '0.0.0.0';
+    let spa = false;
+    let noCache = true;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--port' || a === '-p') {
+            const v = args[++i];
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 1 || n > 65535)
+                return { ok: false, error: `invalid --port '${v}'` };
+            port = n;
+        }
+        else if (a.startsWith('--port=')) {
+            const n = Number(a.slice('--port='.length));
+            if (!Number.isInteger(n) || n < 1 || n > 65535)
+                return { ok: false, error: `invalid --port` };
+            port = n;
+        }
+        else if (a === '--host') {
+            host = args[++i] ?? host;
+        }
+        else if (a.startsWith('--host=')) {
+            host = a.slice('--host='.length);
+        }
+        else if (a === '--spa') {
+            spa = true;
+        }
+        else if (a === '--cache') {
+            noCache = false;
+        }
+        else if (a === '--no-cache') {
+            noCache = true;
+        }
+        else if (a.startsWith('-')) {
+            return { ok: false, error: `unknown flag '${a}'` };
+        }
+        else if (dir === undefined) {
+            dir = a;
+        }
+        else {
+            return { ok: false, error: `unexpected argument '${a}'` };
+        }
+    }
+    if (!dir)
+        return { ok: false, error: 'serve requires a <dir> argument' };
+    // $PORT (preview-manager injects it) is the fallback before the 3000 default.
+    if (port === undefined) {
+        const envPort = Number(process.env.PORT);
+        port = Number.isInteger(envPort) && envPort >= 1 && envPort <= 65535 ? envPort : 3000;
+    }
+    return { ok: true, opts: { dir: path.resolve(dir), port, host, spa, noCache } };
+}
+/** Resolve a request URL path to an on-disk file path, GUARDING against
+ *  traversal outside `root`. Returns null when the resolved path escapes
+ *  root. Exported for tests. */
+export function resolveRequestPath(root, urlPath) {
+    // Strip query/hash, decode, normalize.
+    let p = urlPath.split('?')[0].split('#')[0];
+    try {
+        p = decodeURIComponent(p);
+    }
+    catch {
+        return null; // malformed percent-encoding
+    }
+    // A decoded NUL byte (e.g. `/%00`) passes decodeURIComponent but makes the
+    // downstream fs.* calls THROW SYNCHRONOUSLY (ERR_INVALID_ARG_VALUE),
+    // crashing the server instead of returning a 4xx. Reject it here.
+    if (p.includes('\0'))
+        return null;
+    // Join + normalize, then confirm the result is still within root.
+    const resolved = path.resolve(root, '.' + (p.startsWith('/') ? p : '/' + p));
+    if (resolved !== root && !resolved.startsWith(root + path.sep))
+        return null;
+    return resolved;
+}
+export function createServeHandler(opts) {
+    // The real (symlink-resolved) served root, computed once. Per-request
+    // realpath checks confirm targets stay within THIS. Falls back to the
+    // lexical dir if the root itself can't be realpath'd (shouldn't happen —
+    // runServeCmd verified it's a directory first).
+    let realRoot = opts.dir;
+    try {
+        realRoot = fs.realpathSync(opts.dir);
+    }
+    catch {
+        /* keep lexical opts.dir */
+    }
+    return (req, res) => {
+        const send = (status, body, contentType) => {
+            res.writeHead(status, {
+                'Content-Type': contentType,
+                ...(opts.noCache ? { 'Cache-Control': 'no-store, max-age=0' } : {}),
+            });
+            res.end(body);
+        };
+        const resolved = resolveRequestPath(opts.dir, req.url ?? '/');
+        if (resolved === null) {
+            send(400, 'Bad Request', 'text/plain; charset=utf-8');
+            return;
+        }
+        const serveFile = (filePath) => {
+            // Resolve symlinks and RE-CHECK containment: the lexical guard in
+            // resolveRequestPath can't catch a symlink INSIDE root that points
+            // outside it. realpath the target and confirm its real path is still
+            // within realRoot before reading — blocks symlink escapes while still
+            // allowing symlinks that stay inside the served tree.
+            fs.realpath(filePath, (rpErr, realPath) => {
+                if (rpErr) {
+                    // Missing / broken-symlink → SPA fallback to root index.html, else 404.
+                    if (opts.spa) {
+                        const indexPath = path.join(opts.dir, 'index.html');
+                        if (filePath !== indexPath) {
+                            serveFile(indexPath);
+                            return;
+                        }
+                    }
+                    send(404, 'Not Found', 'text/plain; charset=utf-8');
+                    return;
+                }
+                if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+                    send(403, 'Forbidden', 'text/plain; charset=utf-8'); // symlink escaped root
+                    return;
+                }
+                fs.readFile(realPath, (err, data) => {
+                    if (err) {
+                        send(404, 'Not Found', 'text/plain; charset=utf-8');
+                        return;
+                    }
+                    send(200, data, MIME[path.extname(realPath).toLowerCase()] ?? 'application/octet-stream');
+                });
+            });
+        };
+        fs.stat(resolved, (err, stat) => {
+            if (err) {
+                serveFile(resolved); // delegate to serveFile's 404 / SPA handling
+                return;
+            }
+            // Directory → its index.html.
+            if (stat.isDirectory()) {
+                serveFile(path.join(resolved, 'index.html'));
+                return;
+            }
+            serveFile(resolved);
+        });
+    };
+}
+/** Start the static server. Resolves only on a fatal listen error;
+ *  otherwise runs until the process is killed (long-running). */
+export async function runServeCmd(args) {
+    const parsed = parseServeArgs(args);
+    if (!parsed.ok) {
+        process.stderr.write(`yolo serve: ${parsed.error}\n`);
+        process.stderr.write('Usage: yolo serve <dir> [--port N] [--host H] [--spa] [--no-cache]\n');
+        return 64; // EX_USAGE
+    }
+    const { opts } = parsed;
+    if (!fs.existsSync(opts.dir) || !fs.statSync(opts.dir).isDirectory()) {
+        process.stderr.write(`yolo serve: not a directory: ${opts.dir}\n`);
+        return 66; // EX_NOINPUT
+    }
+    const server = http.createServer(createServeHandler(opts));
+    return new Promise((resolve) => {
+        server.on('error', (err) => {
+            process.stderr.write(`yolo serve: ${err.code === 'EADDRINUSE' ? `port ${opts.port} is already in use` : err.message}\n`);
+            resolve(70); // EX_SOFTWARE
+        });
+        server.listen(opts.port, opts.host, () => {
+            process.stdout.write(`yolo serve: serving ${opts.dir} on http://${opts.host}:${opts.port}\n`);
+            // Intentionally never resolve — the server runs until killed.
+        });
+    });
+}