@sagentlab/navarch-runtime 0.1.0

package/dist/adapters/codex.cjs

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAdapter = void 0;
+exports.runCodexAdapter = runCodexAdapter;
+const node_child_process_1 = require("node:child_process");
+const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
+/**
+ * Headless OpenAI Codex CLI adapter — the Codex sibling of claude.cts's
+ * `runClaudeCodeAdapter`, implementing the same AgentAdapter interface
+ * (adapters/types.cts) so session.cts can pick either one at runtime via
+ * FLOTILLA_AGENT (config.cts's `agentType`). Structurally this mirrors
+ * claude.cts exactly: same host-vs-docker-exec split, same
+ * timeout/AbortSignal handling, same "attach best-effort usage onto the raw
+ * result" shape — only the CLI invocation and output parsing differ.
+ *
+ * ASSUMED — EVERYTHING BELOW ABOUT THE REAL `codex` BINARY MUST BE CONFIRMED
+ * AGAINST A REAL INSTALL. There is no `codex` binary available in this
+ * offline build environment, so (mirroring how claude.cts documents its own
+ * `claude -p --output-format json` assumption) this adapter is a best-effort
+ * implementation against the Codex CLI's publicly documented shape, not a
+ * verified one:
+ *
+ *   codex exec "<prompt>" --json [--mcp-config <path>] [...extraArgs]
+ *
+ * - `exec <prompt>` — ASSUMED to be Codex CLI's non-interactive/headless
+ *   subcommand (the `codex exec` "automation mode" analog of `claude -p`):
+ *   runs the prompt to completion without the interactive TUI and exits,
+ *   printing its result to stdout.
+ * - `--json` — ASSUMED to switch Codex CLI's output to newline-delimited
+ *   JSON ("JSONL") event objects rather than a single JSON result object
+ *   like Claude Code's `--output-format json`. See exit-conditions.cts's
+ *   parseCodexJsonEvents doc comment for the exact assumed event shape and
+ *   what happens when this guess is wrong (graceful degradation, never a
+ *   thrown error).
+ * - `--mcp-config <path>` — ASSUMED by analogy with the Claude adapter; there
+ *   is no confirmed Codex CLI flag of this name. Codex CLI is documented
+ *   elsewhere to configure MCP servers via a `~/.codex/config.toml`
+ *   `mcp_servers` table rather than a per-invocation flag, so this flag may
+ *   need to become "write a config.toml fragment into the sandbox before
+ *   exec" instead once a real binary is available to test against.
+ * - Sandboxing/approvals: a real `codex exec` may prompt for
+ *   approval/sandbox-escalation on some actions by default; because this
+ *   runtime already isolates the session in its own Docker container (or,
+ *   in `FLOTILLA_SANDBOX_MODE=host`, trusts the host), the intent is to pass
+ *   whatever flag disables Codex's own approval gate for a fully
+ *   non-interactive run (something like `--full-auto` or
+ *   `--dangerously-bypass-approvals-and-sandbox` in published Codex CLI
+ *   documentation) — deliberately NOT hardcoded here since getting an
+ *   unverified flag wrong could silently change sandboxing behavior; left to
+ *   be supplied via FLOTILLA_CODEX_EXTRA_ARGS until confirmed.
+ * - `FLOTILLA_CODEX_EXTRA_ARGS` (`extraArgs`) wins over the default `--json`
+ *   exactly like the Claude adapter's `--output-format` opt-out, so an
+ *   operator can fall back to plain-text output (or add the real
+ *   approval-bypass flag) without an adapter code change.
+ */
+async function runCodexAdapter(options) {
+    const args = ["exec", options.prompt];
+    if (options.mcpConfigPath) {
+        // ASSUMED flag/support — see module doc comment above.
+        args.push("--mcp-config", options.mcpConfigPath);
+    }
+    if (!options.extraArgs.includes("--json")) {
+        args.push("--json");
+    }
+    args.push(...options.extraArgs);
+    const raw = options.dockerExec ? await runViaDocker(options, args) : await runOnHost(options, args);
+    return attachUsage(raw);
+}
+/** Parses stdout for `codex exec --json` usage/final-message events and folds them onto the raw result (best-effort; leaves tokensIn/tokensOut/costUsd/reportText unset when nothing parses — see exit-conditions.cts#parseCodexJsonEvents). */
+function attachUsage(result) {
+    const events = (0, exit_conditions_cjs_1.parseCodexJsonEvents)(result.stdout);
+    if (events.length === 0)
+        return result;
+    const usage = (0, exit_conditions_cjs_1.extractUsageFromCodexEvents)(events);
+    const reportText = (0, exit_conditions_cjs_1.extractFinalMessageFromCodexEvents)(events) ?? undefined;
+    return {
+        ...result,
+        tokensIn: usage.tokensIn,
+        tokensOut: usage.tokensOut,
+        costUsd: usage.costUsd,
+        ...(reportText !== undefined ? { reportText } : {}),
+    };
+}
+async function runOnHost(options, args) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killedByLeaseLoss = false;
+        const child = (0, node_child_process_1.spawn)(options.bin, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, options.timeoutMs);
+        const onAbort = () => {
+            killedByLeaseLoss = true;
+            child.kill("SIGKILL");
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (d) => {
+            stdout += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            stderr += d.toString();
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            stderr += `\n${String(err)}`;
+            resolve({ exitCode: null, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve({ exitCode: code, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+    });
+}
+async function runViaDocker(options, args) {
+    const { containerName, runner } = options.dockerExec;
+    const quoted = [options.bin, ...args].map(shellQuote).join(" ");
+    const command = `[ -f /tmp/session.env ] && . /tmp/session.env; cd repo 2>/dev/null; ${quoted}`;
+    let killedByLeaseLoss = false;
+    const onAbort = () => {
+        killedByLeaseLoss = true;
+        // Best-effort: kill the exec'd process inside the container — see
+        // claude.cts's identical runViaDocker for the same caveat about
+        // nodeCommandRunner not exposing process-group tracking.
+        runner.run("docker", ["kill", containerName]).catch(() => undefined);
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const result = await runner.run("docker", ["exec", containerName, "sh", "-c", command], {
+            timeoutMs: options.timeoutMs,
+        });
+        return {
+            exitCode: result.code,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    catch (err) {
+        return {
+            exitCode: null,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: "",
+            stderr: String(err),
+        };
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via FLOTILLA_AGENT=codex. */
+exports.codexAdapter = {
+    agentType: "codex",
+    run: runCodexAdapter,
+};

package/dist/adapters/index.cjs

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+exports.selectAdapter = selectAdapter;
+const claude_cjs_1 = require("./claude.cjs");
+Object.defineProperty(exports, "claudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.claudeCodeAdapter; } });
+Object.defineProperty(exports, "runClaudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.runClaudeCodeAdapter; } });
+const codex_cjs_1 = require("./codex.cjs");
+Object.defineProperty(exports, "codexAdapter", { enumerable: true, get: function () { return codex_cjs_1.codexAdapter; } });
+Object.defineProperty(exports, "runCodexAdapter", { enumerable: true, get: function () { return codex_cjs_1.runCodexAdapter; } });
+/**
+ * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
+ * session with, keyed off config.cts's `agentType` (FLOTILLA_AGENT). This is
+ * the one place agent-type branching happens outside config loading itself —
+ * session.cts calls the returned adapter's `run()` uniformly regardless of
+ * which one it got.
+ */
+function selectAdapter(agentType) {
+    switch (agentType) {
+        case "codex":
+            return codex_cjs_1.codexAdapter;
+        case "claude-code":
+            return claude_cjs_1.claudeCodeAdapter;
+        default: {
+            // Exhaustiveness guard: config.cts only ever produces the two values
+            // above, but fall back to Claude Code rather than throwing if this
+            // widens in the future without every caller being updated.
+            const _exhaustive = agentType;
+            return claude_cjs_1.claudeCodeAdapter;
+        }
+    }
+}

package/dist/adapters/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api.cjs

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavarchApiClient = exports.NavarchApiError = void 0;
+class NavarchApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "NavarchApiError";
+    }
+}
+exports.NavarchApiError = NavarchApiError;
+/**
+ * Typed client for the Navarch control-plane API surface WP-07 depends on:
+ * dispatch/claim, per-lease heartbeat, complete, and broker/issue
+ * (schema-design.md §7, quoted verbatim in the method docs below), plus the
+ * machine-registration / machine-heartbeat / transcript-upload-url routes
+ * this package assumes (see types.cts doc comments — flagged "ASSUMED").
+ *
+ * Every request path lives in exactly one method here so wiring up the real
+ * deployment, once WP-01/WP-04/WP-05 land, is a base URL + token (and at most
+ * a one-line path fix for the assumed routes) — not a rewrite.
+ */
+class NavarchApiClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.token = opts.token;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    /** The control-plane base URL this client talks to (used to build the per-session platform MCP config -- see mcp-config.cts). */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /** The machine's own bearer token, if this client was constructed with one (absent only for self-registration). Needed to authenticate the session's platform MCP config -- see mcp-config.cts. */
+    getToken() {
+        return this.token;
+    }
+    async request(method, pathname, body, opts) {
+        const auth = opts?.auth ?? true;
+        const headers = { "content-type": "application/json" };
+        if (auth) {
+            if (!this.token) {
+                throw new Error(`Cannot call ${pathname} without a machine token.`);
+            }
+            headers.authorization = `Bearer ${this.token}`;
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}${pathname}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (response.status === 204)
+            return null;
+        const text = await response.text();
+        const parsed = text ? safeJsonParse(text) : null;
+        if (!response.ok) {
+            throw new NavarchApiError(`Navarch API ${method} ${pathname} failed with ${response.status}`, response.status, parsed ?? text);
+        }
+        if (opts?.allowEmpty && parsed === null)
+            return null;
+        return parsed;
+    }
+    /** ASSUMED endpoint — see types.cts RegisterMachineRequest doc comment. */
+    async registerMachine(req) {
+        const result = await this.request("POST", "/api/machines/register", req, { auth: false });
+        if (!result)
+            throw new Error("registerMachine: empty response from control plane.");
+        return result;
+    }
+    /**
+     * `POST /api/machines/connect` — "Connect an agent to a project"
+     * (docs/flotilla/schema-design.md §7 "Agent connect"). CONFIRMED endpoint,
+     * the project-scoped sibling of {@link registerMachine}: redeems a
+     * single-use, project-scoped enrollment token a project owner minted
+     * (POST /api/projects/:id/enrollment-tokens) instead of the global
+     * FLOTILLA_ENROLLMENT_SECRET. Unauthenticated like registerMachine — the
+     * enrollment token in the body is the auth.
+     */
+    async connectMachine(req) {
+        const result = await this.request("POST", "/api/machines/connect", req, { auth: false });
+        if (!result)
+            throw new Error("connectMachine: empty response from control plane.");
+        return result;
+    }
+    /** ASSUMED endpoint — see types.cts MachineHeartbeatRequest doc comment. */
+    async machineHeartbeat(machineId, req) {
+        const result = await this.request("POST", `/api/machines/${encodeURIComponent(machineId)}/heartbeat`, req);
+        if (!result)
+            throw new Error("machineHeartbeat: empty response from control plane.");
+        return result;
+    }
+    /** schema-design.md §7 — `POST /api/dispatch/claim {machine_capacity, capabilities} → task + context bundle`. */
+    async claim(req) {
+        const result = await this.request("POST", "/api/dispatch/claim", req, { allowEmpty: true });
+        if (!result || result.task == null)
+            return null;
+        return result;
+    }
+    /** schema-design.md §7 — `POST /api/dispatch/:leaseId/heartbeat`. */
+    async heartbeatLease(leaseId) {
+        const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/heartbeat`, {});
+        if (!result)
+            throw new Error("heartbeatLease: empty response from control plane.");
+        return result;
+    }
+    /** schema-design.md §7 — `POST /api/dispatch/:leaseId/complete {status, report, evidence_urls, cost}`. */
+    async completeLease(leaseId, req) {
+        await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/complete`, req, {
+            allowEmpty: true,
+        });
+    }
+    /** schema-design.md §7 — `POST /api/broker/issue {lease_id, secret names} → values (scoped, logged)`. */
+    async issueSecrets(req) {
+        const result = await this.request("POST", "/api/broker/issue", req);
+        if (!result)
+            throw new Error("issueSecrets: empty response from control plane.");
+        return result;
+    }
+    /** ASSUMED endpoint — see types.cts TranscriptUploadUrlResult doc comment. */
+    async getTranscriptUploadUrl(leaseId) {
+        const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/transcript-upload-url`, {});
+        if (!result)
+            throw new Error("getTranscriptUploadUrl: empty response from control plane.");
+        return result;
+    }
+}
+exports.NavarchApiClient = NavarchApiClient;
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/capacity.cjs

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapacityTracker = void 0;
+exports.computeAvailableCapacity = computeAvailableCapacity;
+/** Pure capacity math (implementation-plan.md WP-07: "capacity control (max_sessions)"). */
+function computeAvailableCapacity(maxSessions, activeSessions) {
+    return Math.max(0, maxSessions - activeSessions);
+}
+/**
+ * Tracks which session (lease) ids currently occupy a slot on this machine so
+ * the heartbeat loop reports accurate available_capacity and the claim loop
+ * never over-claims beyond FLOTILLA_MAX_SESSIONS.
+ */
+class CapacityTracker {
+    maxSessions;
+    active = new Set();
+    constructor(maxSessions) {
+        this.maxSessions = maxSessions;
+    }
+    get activeCount() {
+        return this.active.size;
+    }
+    available() {
+        return computeAvailableCapacity(this.maxSessions, this.active.size);
+    }
+    hasCapacity() {
+        return this.available() > 0;
+    }
+    acquire(sessionId) {
+        if (this.active.has(sessionId))
+            return;
+        if (!this.hasCapacity()) {
+            throw new Error(`No capacity available: ${this.active.size}/${this.maxSessions} sessions active.`);
+        }
+        this.active.add(sessionId);
+    }
+    release(sessionId) {
+        this.active.delete(sessionId);
+    }
+}
+exports.CapacityTracker = CapacityTracker;

package/dist/claim-loop.cjs

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaimLoop = void 0;
+const node_crypto_1 = require("node:crypto");
+const logger_cjs_1 = require("./logger.cjs");
+const log = (0, logger_cjs_1.createLogger)("claim");
+/**
+ * Polls dispatch/claim on an interval, gated by available capacity
+ * (implementation-plan.md WP-07 "Claim loop: poll dispatch, receive context
+ * bundle"). Each successful claim acquires a capacity slot immediately and
+ * releases it when the session (run asynchronously, not awaited here so
+ * multiple sessions can run concurrently) finishes.
+ */
+class ClaimLoop {
+    api;
+    config;
+    capacity;
+    runSession;
+    timer = null;
+    stopped = false;
+    constructor(api, config, capacity, runSession) {
+        this.api = api;
+        this.config = config;
+        this.capacity = capacity;
+        this.runSession = runSession;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.tick(), this.config.pollIntervalMs);
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    async tick() {
+        if (this.stopped || !this.capacity.hasCapacity())
+            return;
+        try {
+            // Pre-allocate the session id BEFORE claiming (author-exclusion timing):
+            // the dispatcher records it on the lease and excludes it from review
+            // tasks of PRs this session authors.
+            const sessionId = (0, node_crypto_1.randomUUID)();
+            const claimed = await this.api.claim({
+                available_capacity: this.capacity.available(),
+                capabilities: this.config.capabilities,
+                session_id: sessionId,
+            });
+            if (!claimed)
+                return;
+            this.capacity.acquire(claimed.lease_id);
+            log.info(`claimed task ${claimed.task.id} (${claimed.task.task_type}) as lease ${claimed.lease_id}, session ${sessionId}`);
+            this.runSession(claimed, sessionId)
+                .catch((err) => log.error(`session ${sessionId} failed: ${String(err)}`))
+                .finally(() => this.capacity.release(claimed.lease_id));
+        }
+        catch (err) {
+            log.warn(`claim failed: ${String(err)}`);
+        }
+    }
+}
+exports.ClaimLoop = ClaimLoop;

package/dist/cli.cjs

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const config_cjs_1 = require("./config.cjs");
+const machine_store_cjs_1 = require("./machine-store.cjs");
+const api_cjs_1 = require("./api.cjs");
+const capacity_cjs_1 = require("./capacity.cjs");
+const heartbeat_loop_cjs_1 = require("./heartbeat-loop.cjs");
+const claim_loop_cjs_1 = require("./claim-loop.cjs");
+const session_cjs_1 = require("./session.cjs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const logger_cjs_1 = require("./logger.cjs");
+const log = (0, logger_cjs_1.createLogger)("cli");
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg?.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = rest[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = "true";
+            }
+        }
+    }
+    return { command: command ?? "help", flags };
+}
+/**
+ * `navarch-runtime register` — the one command that prints the machine
+ * token, exactly once, per implementation-plan.md WP-07. See types.cts
+ * RegisterMachineRequest for the (assumed, to-confirm) endpoint contract.
+ */
+async function registerCommand(flags) {
+    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const apiBase = flags["api-base"] ?? config.apiBase;
+    const enrollmentToken = flags.token ?? process.env.FLOTILLA_ENROLLMENT_TOKEN;
+    const name = flags.name ?? process.env.FLOTILLA_MACHINE_NAME;
+    if (!enrollmentToken) {
+        throw new Error("Missing --token (or FLOTILLA_ENROLLMENT_TOKEN) — get one from the admin console.");
+    }
+    if (!name) {
+        throw new Error("Missing --name (or FLOTILLA_MACHINE_NAME) for this machine.");
+    }
+    const maxSessions = Number(flags["max-sessions"] ?? config.maxSessions);
+    const capabilities = (flags.capabilities ?? config.capabilities.join(","))
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const ownerZone = flags["owner-zone"] ?? config.ownerZone;
+    const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
+    const result = await client.registerMachine({
+        enrollment_token: enrollmentToken,
+        name,
+        owner_zone: ownerZone,
+        capabilities,
+        max_sessions: Number.isFinite(maxSessions) && maxSessions > 0 ? maxSessions : config.maxSessions,
+    });
+    await (0, machine_store_cjs_1.saveMachineIdentity)(config.configDir, {
+        machine_id: result.machine_id,
+        token: result.token,
+        name,
+        api_base: apiBase,
+    });
+    // Printed exactly once. Never logged or echoed again after this point.
+    console.log("Machine registered.");
+    console.log(`  machine_id: ${result.machine_id}`);
+    console.log(`  token:      ${result.token}`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`navarch-runtime start\` to begin serving tasks.`);
+}
+/**
+ * `navarch-runtime connect` — "Connect an agent to a project"
+ * (docs/flotilla/schema-design.md §7 "Agent connect"; self-hosted-runner
+ * style). The project-scoped sibling of `register`: redeems a short-lived,
+ * single-use enrollment token a project owner minted from the platform UI
+ * (ConnectAgentPanel → POST /api/projects/:id/enrollment-tokens) instead of
+ * the global FLOTILLA_ENROLLMENT_SECRET `register` needs. Prints the
+ * machine token exactly once, same discipline as `register`.
+ */
+async function connectCommand(flags) {
+    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const apiBase = flags["api-base"] ?? config.apiBase;
+    const enrollmentToken = flags.token ?? process.env.FLOTILLA_ENROLLMENT_TOKEN;
+    const name = flags.name ?? process.env.FLOTILLA_MACHINE_NAME;
+    const projectId = flags.project ?? process.env.FLOTILLA_PROJECT_ID;
+    if (!enrollmentToken) {
+        throw new Error("Missing --token (or FLOTILLA_ENROLLMENT_TOKEN) — get one from a project owner's \"Connect an agent\" panel.");
+    }
+    if (!name) {
+        throw new Error("Missing --name (or FLOTILLA_MACHINE_NAME) for this machine.");
+    }
+    const maxSessions = Number(flags["max-sessions"] ?? config.maxSessions);
+    const capabilities = (flags.capabilities ?? config.capabilities.join(","))
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
+    const result = await client.connectMachine({
+        enrollment_token: enrollmentToken,
+        name,
+        capabilities,
+        max_sessions: Number.isFinite(maxSessions) && maxSessions > 0 ? maxSessions : config.maxSessions,
+        project_id: projectId,
+    });
+    await (0, machine_store_cjs_1.saveMachineIdentity)(config.configDir, {
+        machine_id: result.machine_id,
+        token: result.token,
+        name,
+        api_base: apiBase,
+    });
+    // Printed exactly once. Never logged or echoed again after this point.
+    console.log("Machine connected.");
+    console.log(`  machine_id: ${result.machine_id}`);
+    console.log(`  token:      ${result.token}`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`navarch-runtime start\` to begin serving tasks.`);
+}
+async function startCommand() {
+    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
+    const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
+    const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
+    const heartbeat = new heartbeat_loop_cjs_1.MachineHeartbeatLoop(api, identity.machine_id, config, capacity);
+    const claimLoop = new claim_loop_cjs_1.ClaimLoop(api, config, capacity, (claimed, sessionId) => (0, session_cjs_1.runSession)({ api, config }, claimed, sessionId));
+    heartbeat.start();
+    claimLoop.start();
+    log.info(`navarch-runtime started: machine=${identity.name} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
+    const shutdown = () => {
+        log.info("shutting down...");
+        heartbeat.stop();
+        claimLoop.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+async function doctorCommand() {
+    const config = (0, config_cjs_1.loadRuntimeConfig)();
+    const dockerOk = await (0, sandbox_cjs_1.isDockerAvailable)();
+    console.log(`api_base:        ${config.apiBase}`);
+    console.log(`config_dir:      ${config.configDir}`);
+    console.log(`workspace_root:  ${config.workspaceRoot}`);
+    console.log(`max_sessions:    ${config.maxSessions}`);
+    console.log(`capabilities:    ${config.capabilities.join(", ")}`);
+    console.log(`sandbox_mode:    ${config.sandboxMode}`);
+    console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
+    try {
+        const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
+        console.log(`machine:         ${identity.name} (${identity.machine_id})`);
+    }
+    catch {
+        console.log("machine:         not registered — run `navarch-runtime register`");
+    }
+}
+function helpText() {
+    return `navarch-runtime — Navarch machine-side session manager
+
+Usage:
+  navarch-runtime register --token <enrollment-token> --name <machine-name> \\
+      [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+  navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
+      [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start
+  navarch-runtime doctor
+
+Configuration is via FLOTILLA_* environment variables; see runtime/README.md.
+`;
+}
+async function main(argv = process.argv.slice(2)) {
+    const { command, flags } = parseArgs(argv);
+    try {
+        switch (command) {
+            case "register":
+                await registerCommand(flags);
+                break;
+            case "connect":
+                await connectCommand(flags);
+                break;
+            case "start":
+                await startCommand();
+                break;
+            case "doctor":
+                await doctorCommand();
+                break;
+            case "help":
+            case "--help":
+            case "-h":
+                console.log(helpText());
+                break;
+            default:
+                console.error(`Unknown command: ${command}\n`);
+                console.log(helpText());
+                process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+}