cueline 0.1.6 → 0.1.7

package/dist/src/cli/health-commands.js

@@ -0,0 +1,191 @@
+import { routingConfigPath } from "../api.js";
+import { CueLineError } from "../core/errors.js";
+import { executableAvailability } from "../router/availability.js";
+import { loadRoutingConfig } from "../router/config-loader.js";
+import { resolveRoute } from "../router/resolver.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { CUELINE_VERSION } from "../version.js";
+function routingErrorCode(error) {
+    return error instanceof CueLineError ? error.code : "ROUTE_UNAVAILABLE";
+}
+async function collectRoutingReport(environment) {
+    const configPath = routingConfigPath(environment);
+    let config;
+    try {
+        config = await loadRoutingConfig(configPath);
+    }
+    catch {
+        return {
+            version: CUELINE_VERSION,
+            config: {
+                path: configPath,
+                valid: false,
+                errorCode: "ROUTING_CONFIG_INVALID",
+            },
+            availableLanes: 0,
+            lanes: [],
+            findings: [
+                {
+                    code: "ROUTING_CONFIG_INVALID",
+                    message: "Routing configuration could not be loaded.",
+                },
+            ],
+        };
+    }
+    const availability = executableAvailability(environment);
+    const lanes = [];
+    for (const [lane, laneConfig] of Object.entries(config.lanes)) {
+        if (!laneConfig.enabled) {
+            lanes.push({
+                name: lane,
+                enabled: false,
+                status: "disabled",
+                selectedRunnerId: null,
+            });
+            continue;
+        }
+        try {
+            const route = resolveRoute(lane, config, availability);
+            lanes.push({
+                name: lane,
+                enabled: true,
+                status: "available",
+                selectedRunnerId: route.candidate.id,
+            });
+        }
+        catch (error) {
+            lanes.push({
+                name: lane,
+                enabled: true,
+                status: "unavailable",
+                selectedRunnerId: null,
+                errorCode: routingErrorCode(error),
+            });
+        }
+    }
+    return {
+        version: CUELINE_VERSION,
+        config: { path: configPath, valid: true },
+        availableLanes: lanes.filter((lane) => lane.status === "available").length,
+        lanes,
+        findings: [],
+    };
+}
+async function routingCommand(json, environment, io) {
+    const report = await collectRoutingReport(environment);
+    if (json) {
+        io.stdout(JSON.stringify(report, null, 2));
+    }
+    else if (!report.config.valid) {
+        io.stdout(`config\t${report.config.path}\tinvalid\t${report.config.errorCode}`);
+    }
+    else {
+        for (const lane of report.lanes) {
+            io.stdout(`${lane.name}\t${lane.selectedRunnerId ?? "-"}\t${lane.status}${lane.errorCode === undefined ? "" : ` (${lane.errorCode})`}`);
+        }
+    }
+    return report.availableLanes > 0 ? 0 : 1;
+}
+async function collectDoctorReport(environment) {
+    const configPath = routingConfigPath(environment);
+    const home = defaultCueLineHome(environment);
+    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    const nodeOk = major >= 22;
+    const availability = executableAvailability(environment);
+    const findings = [];
+    let callerLanes = 0;
+    let processAvailableLanes = 0;
+    let config;
+    try {
+        config = await loadRoutingConfig(configPath);
+    }
+    catch {
+        findings.push({
+            code: "ROUTING_CONFIG_INVALID",
+            surface: "config",
+            message: "Routing configuration could not be loaded.",
+        });
+    }
+    if (config !== undefined) {
+        for (const [lane, laneConfig] of Object.entries(config.lanes)) {
+            if (!laneConfig.enabled)
+                continue;
+            callerLanes += 1;
+            try {
+                resolveRoute(lane, config, availability);
+                processAvailableLanes += 1;
+            }
+            catch {
+                // `cueline routing` reports per-lane details.
+            }
+        }
+    }
+    if (!nodeOk) {
+        findings.push({
+            code: "NODE_VERSION_UNSUPPORTED",
+            surface: "node",
+            message: "Node.js 22 or newer is required.",
+        });
+    }
+    if (config !== undefined && callerLanes === 0) {
+        findings.push({
+            code: "CALLER_LANES_UNAVAILABLE",
+            surface: "caller",
+            message: "No enabled caller lane is configured.",
+        });
+    }
+    const callerReady = nodeOk && config !== undefined && callerLanes > 0;
+    return {
+        version: CUELINE_VERSION,
+        status: callerReady ? "ok" : "degraded",
+        node: {
+            version: process.versions.node,
+            ok: nodeOk,
+            requirement: ">=22",
+        },
+        config: config === undefined
+            ? { path: configPath, valid: false, errorCode: "ROUTING_CONFIG_INVALID" }
+            : { path: configPath, valid: true },
+        home,
+        caller: {
+            ready: callerReady,
+            enabledLanes: callerLanes,
+        },
+        process: {
+            availableLanes: processAvailableLanes,
+        },
+        findings,
+    };
+}
+async function doctorCommand(json, environment, io) {
+    const report = await collectDoctorReport(environment);
+    if (json) {
+        io.stdout(JSON.stringify(report, null, 2));
+    }
+    else {
+        io.stdout(`CueLine ${report.version}`);
+        io.stdout(`status\t${report.status}`);
+        io.stdout(`node\t${report.node.version}\t${report.node.ok ? "ok" : `requires ${report.node.requirement}`}`);
+        io.stdout(`config\t${report.config.path}\t${report.config.valid ? "valid" : "invalid"}`);
+        io.stdout(`home\t${report.home}`);
+        io.stdout(`caller_ready\t${report.caller.ready ? "yes" : "no"}`);
+        io.stdout(`caller_lanes\t${report.caller.enabledLanes}`);
+        io.stdout(`process_available_lanes\t${report.process.availableLanes}`);
+        for (const item of report.findings) {
+            io.stdout(`finding\t${item.code}\t${item.surface}\t${item.message}`);
+        }
+    }
+    return report.status === "ok" ? 0 : 1;
+}
+export async function handleHealthCommand(args, environment, io) {
+    if (args[0] === "routing" &&
+        (args.length === 1 || (args.length === 2 && args[1] === "--json"))) {
+        return routingCommand(args[1] === "--json", environment, io);
+    }
+    if (args[0] === "doctor" &&
+        (args.length === 1 || (args.length === 2 && args[1] === "--json"))) {
+        return doctorCommand(args[1] === "--json", environment, io);
+    }
+    return undefined;
+}
+//# sourceMappingURL=health-commands.js.map

package/dist/src/cli/health-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-commands.js","sourceRoot":"","sources":["../../../src/cli/health-commands.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/io.d.ts

@@ -0,0 +1,4 @@
+export interface CliIo {
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}

package/dist/src/cli/io.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=io.js.map

package/dist/src/cli/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":""}

package/dist/src/cli/main.d.ts

@@ -1,7 +1,3 @@
 #!/usr/bin/env node
-interface CliIo {
-    stdout: (line: string) => void;
-    stderr: (line: string) => void;
-}
+import type { CliIo } from "./io.js";
 export declare function main(args?: readonly string[], environment?: NodeJS.ProcessEnv, io?: CliIo): Promise<number>;
-export {};

package/dist/src/cli/main.js

@@ -3,22 +3,24 @@ import { readdir, readFile } from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { cancelCueLineJob, cancelCueLineRun, confirmManualControllerSubmission, loadCueLineRunStatus, reconcileCueLineRuntime, routingConfigPath, takeoverCueLineRuntime, } from "../api.js";
+import { cancelCueLineJob, cancelCueLineRun, confirmManualControllerSubmission, loadCueLineRunStatus, lintControllerCommandText, reconcileCueLineRuntime, routingConfigPath, takeoverCueLineRuntime, } from "../api.js";
 import { CueLineError } from "../core/errors.js";
-import { executableAvailability } from "../router/availability.js";
+import { JobStatusStore } from "../jobs/status.js";
 import { loadRoutingConfig } from "../router/config-loader.js";
-import { resolveRoute } from "../router/resolver.js";
 import { defaultCueLineHome } from "../state/paths.js";
 import { readRuntimeLease } from "../state/runtime-lease.js";
 import { readAuthoritativeRunEvents } from "../state/store.js";
 import { CUELINE_VERSION } from "../version.js";
+import { handleHealthCommand } from "./health-commands.js";
+import { handleObservationCommand } from "./observation-commands.js";
+import { safeCueLineRunStatus } from "./run-status-view.js";
 import { installSkill, uninstallSkill } from "./skill-links.js";
 const processIo = {
     stdout: (line) => process.stdout.write(`${line}\n`),
     stderr: (line) => process.stderr.write(`${line}\n`),
 };
 function usage() {
-    return "usage: cueline <install|uninstall|doctor|routing|jobs|run status|run reconcile|run takeover|run reconcile-runtime|run cancel|run stop|job cancel|api path|config path|help|version>";
+    return "usage: cueline <install|uninstall|doctor|routing|jobs|runs|protocol lint|run status|run doctor|run watch|run handoff|run timeline|run verify|run reconcile|run takeover|run reconcile-runtime|run cancel|run stop|job cancel|api path|config path|help|version>";
 }
 function help() {
     return [
@@ -32,7 +34,14 @@ function help() {
         "  doctor         report Node, caller readiness, state home, and process lanes",
         "  routing        list every lane and the candidate that would be selected",
         "  jobs           list persisted local jobs with run, key, lane, mode, and PID",
-        "  run status     summarize one persisted run for safe cross-session handoff",
+        "  protocol lint  validate a Pro control envelope offline and explain corrections",
+        "  runs           list safe summaries of every persisted run",
+        "  run status     metadata-only summary for safe cross-session handoff",
+        "  run doctor     explain why a run is waiting or blocked and name the safe next action",
+        "  run watch      wait briefly for a newer durable event without owning the run",
+        "  run handoff    emit a restart packet with exact paths and safe next action",
+        "  run timeline   show a sanitized, cursor-paginated audit timeline",
+        "  run verify     verify durable run evidence without returning its content",
         "  run reconcile  confirm one manually sent controller turn; never resends it",
         "  run takeover   explicitly retire one exact stale runtime owner",
         "  run reconcile-runtime  settle dead ownerless workers from persisted evidence",
@@ -47,10 +56,17 @@ function help() {
         "command syntax:",
         "  cueline install",
         "  cueline uninstall",
-        "  cueline doctor",
-        "  cueline routing",
+        "  cueline doctor [--json]",
+        "  cueline routing [--json]",
         "  cueline jobs [--json]",
+        "  cueline protocol lint <file> --run-id <id> --round <n> --request-id <id> [--json]",
+        "  cueline runs [--json]",
         "  cueline run status <run-id> [--json]",
+        "  cueline run doctor <run-id> [--json]",
+        "  cueline run watch <run-id> --after <sequence> [--timeout-ms <0..30000>] [--json]",
+        "  cueline run handoff <run-id> [--include-content] [--max-content-chars <16..10000>] [--json]",
+        "  cueline run timeline <run-id> [--after <sequence>] [--limit <1..1000>] [--json]",
+        "  cueline run verify <run-id> [--json]",
         "  cueline run reconcile <run-id> --request-id <request-id> --manual-send-confirmed [--conversation-url <url>] [--json]",
         "  cueline run takeover <run-id> [--json]",
         "  cueline run reconcile-runtime <run-id> [--json]",
@@ -76,7 +92,7 @@ function help() {
         "  2  the arguments were not understood",
         "",
         "state effects:",
-        "  Read-only: doctor, routing, jobs, run status, api path, config path, help, version.",
+        "  Read-only: doctor, routing, jobs, runs, protocol lint, run status, run doctor, run watch, run handoff, run timeline, run verify, api path, config path, help, version.",
         "  Local setup: install and uninstall change only the package-owned skill link.",
         "  Durable state writes: run reconcile, takeover, reconcile-runtime, cancel/stop,",
         "  and job cancel append evidence or change local run/job state.",
@@ -90,25 +106,26 @@ function errorMessage(error) {
         return `${error.code}: ${error.message}`;
     return error instanceof Error ? error.message : String(error);
 }
-async function routingCommand(environment, io) {
-    const config = await loadRoutingConfig(routingConfigPath(environment));
-    const availability = executableAvailability(environment);
-    let available = 0;
-    for (const [lane, laneConfig] of Object.entries(config.lanes)) {
-        if (!laneConfig.enabled) {
-            io.stdout(`${lane}\t-\tdisabled`);
-            continue;
-        }
-        try {
-            const route = resolveRoute(lane, config, availability);
-            available += 1;
-            io.stdout(`${lane}\t${route.candidate.id}\tavailable`);
-        }
-        catch (error) {
-            io.stdout(`${lane}\t-\tunavailable (${errorMessage(error)})`);
-        }
-    }
-    return available > 0 ? 0 : 1;
+function jobStatusMetadata(status) {
+    return {
+        jobId: status.jobId,
+        ...(status.runId === undefined ? {} : { runId: status.runId }),
+        ...(status.jobKey === undefined ? {} : { jobKey: status.jobKey }),
+        ...(status.lane === undefined ? {} : { lane: status.lane }),
+        ...(status.mode === undefined ? {} : { mode: status.mode }),
+        ...(status.runnerId === undefined ? {} : { runnerId: status.runnerId }),
+        ...(status.model === undefined ? {} : { model: status.model }),
+        ...(status.provider === undefined ? {} : { provider: status.provider }),
+        ...(status.pid === undefined ? {} : { pid: status.pid }),
+        ...(status.phase === undefined ? {} : { phase: status.phase }),
+        ...(status.lastProgressAt === undefined
+            ? {}
+            : { lastProgressAt: status.lastProgressAt }),
+        execution: status.execution,
+        status: status.status,
+        startedAt: status.startedAt,
+        ...(status.finishedAt === undefined ? {} : { finishedAt: status.finishedAt }),
+    };
 }
 async function readRunJobMetadata(home) {
     const metadata = new Map();
@@ -151,7 +168,6 @@ async function readRunJobMetadata(home) {
                     jobKey: record.jobKey,
                     lane: spec.lane,
                     mode: spec.mode,
-                    task: spec.task,
                     execution: "foreground",
                     status: "pending",
                     startedAt: event.timestamp,
@@ -203,13 +219,23 @@ async function readJobs(home) {
         else
             throw error;
     }
+    const statusStore = new JobStatusStore(home);
     const statuses = [];
-    for (const name of names.filter((candidate) => candidate.endsWith(".json")).sort()) {
+    const jobIds = new Set();
+    for (const name of names) {
+        if (name.endsWith(".json"))
+            jobIds.add(name.slice(0, -".json".length));
+        if (name.endsWith(".terminal"))
+            jobIds.add(name.slice(0, -".terminal".length));
+    }
+    for (const jobId of [...jobIds].sort()) {
         try {
-            statuses.push(JSON.parse(await readFile(path.join(directory, name), "utf8")));
+            const status = await statusStore.read(jobId);
+            if (status !== undefined)
+                statuses.push(status);
         }
         catch (error) {
-            throw new CueLineError("JOB_STATUS_INVALID", `unable to parse job status: ${name}`, {
+            throw new CueLineError("JOB_STATUS_INVALID", `unable to parse job status: ${jobId}`, {
                 cause: error,
             });
         }
@@ -225,16 +251,22 @@ async function readJobs(home) {
     for (const persisted of statuses) {
         const authoritative = runMetadata.get(persisted.jobId);
         const conflict = authoritative !== undefined && authoritative.status !== persisted.status;
+        const persistedMetadata = jobStatusMetadata(persisted);
+        const { finishedAt: _persistedFinishedAt, ...activePersistedMetadata } = persistedMetadata;
         const status = conflict
             ? {
-                ...Object.fromEntries(Object.entries(persisted).filter(([key]) => key !== "result" && key !== "error" && key !== "finishedAt")),
+                ...activePersistedMetadata,
                 ...authoritative,
                 execution: persisted.execution,
                 startedAt: persisted.startedAt,
             }
             : {
+                ...(authoritative?.status === "pending" || authoritative?.status === "running"
+                    ? activePersistedMetadata
+                    : persistedMetadata),
                 ...authoritative,
-                ...persisted,
+                execution: persisted.execution,
+                startedAt: persisted.startedAt,
                 status: authoritative?.status ?? persisted.status,
             };
         let observedStatus = conflict ? "conflict" : status.status;
@@ -252,7 +284,7 @@ async function readJobs(home) {
             }
         }
         listed.push({
-            ...status,
+            ...jobStatusMetadata(status),
             ...(conflict ? { persistedStatus: persisted.status } : {}),
             observedStatus,
         });
@@ -270,14 +302,50 @@ async function jobsCommand(json, environment, io) {
         return 0;
     }
     for (const job of jobs) {
-        io.stdout(`${job.jobId}\t${job.runId ?? "-"}\t${job.jobKey ?? "-"}\t${job.lane ?? "-"}\t${job.mode ?? "-"}\t${job.pid ?? "-"}\t${job.execution}\t${job.observedStatus}\t${job.startedAt}\trunner=${job.runnerId ?? "-"}\tmodel=${job.model ?? "-"}\tprovider=${job.provider ?? "-"}\tphase=${job.phase ?? "-"}\tprogress=${job.lastProgressAt ?? "-"}\ttask=${JSON.stringify(job.task ?? "")}`);
+        io.stdout(`${job.jobId}\t${job.runId ?? "-"}\t${job.jobKey ?? "-"}\t${job.lane ?? "-"}\t${job.mode ?? "-"}\t${job.pid ?? "-"}\t${job.execution}\t${job.observedStatus}\t${job.startedAt}\trunner=${job.runnerId ?? "-"}\tmodel=${job.model ?? "-"}\tprovider=${job.provider ?? "-"}\tphase=${job.phase ?? "-"}\tprogress=${job.lastProgressAt ?? "-"}`);
     }
     return 0;
 }
+async function protocolLintCommand(file, expected, json, environment, io) {
+    const config = await loadRoutingConfig(routingConfigPath(environment));
+    const runnerLanes = Object.create(null);
+    for (const [lane, laneConfig] of Object.entries(config.lanes)) {
+        if (!laneConfig.enabled)
+            continue;
+        for (const candidate of laneConfig.candidates) {
+            if (candidate.enabled === false || runnerLanes[candidate.id] !== undefined)
+                continue;
+            runnerLanes[candidate.id] = lane;
+        }
+    }
+    const text = await readFile(file, "utf8");
+    const report = lintControllerCommandText(text, {
+        expected,
+        routing: {
+            lanes: Object.entries(config.lanes)
+                .filter(([, lane]) => lane.enabled)
+                .map(([lane]) => lane),
+            runnerLanes,
+        },
+    });
+    if (json) {
+        io.stdout(JSON.stringify({ version: CUELINE_VERSION, ...report }, null, 2));
+    }
+    else {
+        io.stdout(`valid\t${report.valid ? "yes" : "no"}`);
+        io.stdout(`format\t${report.format}`);
+        for (const issue of report.issues) {
+            io.stdout(`issue\t${issue.severity}\t${issue.code}\t${issue.path ?? "-"}\t${issue.message}\tsuggestion=${issue.suggestion ?? "-"}`);
+        }
+        if (report.command !== undefined)
+            io.stdout(`action\t${report.command.action}`);
+    }
+    return report.valid ? 0 : 1;
+}
 async function runStatusCommand(runId, json, environment, io) {
     const status = await loadCueLineRunStatus(runId, { environment });
     if (json) {
-        io.stdout(JSON.stringify({ version: CUELINE_VERSION, ...status }, null, 2));
+        io.stdout(JSON.stringify({ version: CUELINE_VERSION, ...safeCueLineRunStatus(status) }, null, 2));
         return 0;
     }
     const controller = status.controller.responseAccepted
@@ -297,47 +365,18 @@ async function runStatusCommand(runId, json, environment, io) {
         : `\theartbeat=${status.runtime.heartbeatAt}\tage_ms=${status.runtime.ageMs ?? "-"}`}`);
     io.stdout(`sequence\t${status.lastEventSequence}`);
     io.stdout(`controller\t${controller}\tpending=${status.controller.pendingTurns}\taccepted_commands=${status.controller.acceptedCommands}\tlast_action=${status.controller.lastAcceptedAction ?? "-"}\tlast_jobs=${status.controller.lastAcceptedJobKeys.length}`);
+    if (status.controller.archive.enabled) {
+        io.stdout(`controller_archive\tenabled=yes\tstatus=${status.controller.archive.status}\tcode=${status.controller.archive.code ?? "-"}\tproof=${status.controller.archive.proof ?? "-"}`);
+    }
     io.stdout(`jobs\ttotal=${status.jobs.total}\tpending=${counts.pending}\trunning=${counts.running}\tsucceeded=${counts.succeeded}\tfailed=${counts.failed}\ttimed_out=${counts.timed_out}\torphaned=${counts.orphaned}\tcancelled=${counts.cancelled}\tambiguous=${counts.ambiguous}`);
     for (const job of status.jobs.items) {
-        io.stdout(`job\t${job.jobId}\t${job.jobKey}\t${job.status}\t${job.mode}\t${job.lane}\trequired=${job.required}\tpersisted=${job.persistedStatus}\trunner=${job.execution?.runnerId ?? "-"}\tpid=${job.execution?.pid ?? "-"}\tmodel=${job.execution?.model ?? "-"}\tprovider=${job.execution?.provider ?? "-"}\tphase=${job.execution?.phase ?? "-"}\tprogress=${job.execution?.lastProgressAt ?? "-"}\ttask=${JSON.stringify(job.task)}`);
+        io.stdout(`job\t${job.jobId}\t${job.jobKey}\t${job.status}\t${job.mode}\t${job.lane}\trequired=${job.required}\tpersisted=${job.persistedStatus}\trunner=${job.execution?.runnerId ?? "-"}\tpid=${job.execution?.pid ?? "-"}\tmodel=${job.execution?.model ?? "-"}\tprovider=${job.execution?.provider ?? "-"}\tphase=${job.execution?.phase ?? "-"}\tprogress=${job.execution?.lastProgressAt ?? "-"}`);
     }
     io.stdout(`cancellation\trun=${status.cancellation.runRequested ? "requested" : "none"}\tjobs=${status.cancellation.jobRequests.length}`);
     io.stdout(`continue\t${status.continueAllowed ? "allowed" : "forbidden"}`);
     io.stdout(`next\t${status.safeNextAction}`);
     return 0;
 }
-async function doctorCommand(environment, io) {
-    const configPath = routingConfigPath(environment);
-    const home = defaultCueLineHome(environment);
-    const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-    const nodeOk = major >= 22;
-    const config = await loadRoutingConfig(configPath);
-    const availability = executableAvailability(environment);
-    let callerLanes = 0;
-    let processAvailableLanes = 0;
-    for (const [lane, laneConfig] of Object.entries(config.lanes)) {
-        if (!laneConfig.enabled)
-            continue;
-        callerLanes += 1;
-        try {
-            resolveRoute(lane, config, availability);
-            processAvailableLanes += 1;
-        }
-        catch {
-            // Doctor reports the aggregate below; `cueline routing` shows lane details.
-        }
-    }
-    const callerReady = nodeOk && callerLanes > 0;
-    io.stdout(`CueLine ${CUELINE_VERSION}`);
-    io.stdout(`status\t${callerReady ? "ok" : "degraded"}`);
-    io.stdout(`node\t${process.versions.node}\t${nodeOk ? "ok" : "requires >=22"}`);
-    io.stdout(`config\t${configPath}\tvalid`);
-    io.stdout(`home\t${home}`);
-    io.stdout(`caller_ready\t${callerReady ? "yes" : "no"}`);
-    io.stdout(`caller_lanes\t${callerLanes}`);
-    io.stdout(`process_available_lanes\t${processAvailableLanes}`);
-    return callerReady ? 0 : 1;
-}
 export async function main(args = process.argv.slice(2), environment = process.env, io = processIo) {
     try {
         if (args.length === 0) {
@@ -373,13 +412,59 @@ export async function main(args = process.argv.slice(2), environment = process.e
             io.stdout(await uninstallSkill(environment));
             return 0;
         }
-        if (args[0] === "routing" && args.length === 1) {
-            return routingCommand(environment, io);
-        }
+        const healthResult = await handleHealthCommand(args, environment, io);
+        if (healthResult !== undefined)
+            return healthResult;
         if (args[0] === "jobs" &&
             (args.length === 1 || (args.length === 2 && args[1] === "--json"))) {
-            return jobsCommand(args[1] === "--json", environment, io);
+            return await jobsCommand(args[1] === "--json", environment, io);
         }
+        if (args[0] === "protocol" &&
+            args[1] === "lint" &&
+            typeof args[2] === "string") {
+            let runId;
+            let round;
+            let requestId;
+            let json = false;
+            let valid = true;
+            for (let index = 3; index < args.length; index += 1) {
+                const argument = args[index];
+                if (argument === "--run-id" && runId === undefined && typeof args[index + 1] === "string") {
+                    runId = args[index + 1];
+                    index += 1;
+                }
+                else if (argument === "--round" &&
+                    round === undefined &&
+                    typeof args[index + 1] === "string") {
+                    round = Number(args[index + 1]);
+                    index += 1;
+                }
+                else if (argument === "--request-id" &&
+                    requestId === undefined &&
+                    typeof args[index + 1] === "string") {
+                    requestId = args[index + 1];
+                    index += 1;
+                }
+                else if (argument === "--json" && !json) {
+                    json = true;
+                }
+                else {
+                    valid = false;
+                }
+            }
+            if (!valid ||
+                !runId ||
+                !requestId ||
+                round === undefined ||
+                !Number.isSafeInteger(round) ||
+                round < 1) {
+                throw new CueLineError("CLI_ARGUMENTS_INVALID", "usage: cueline protocol lint <file> --run-id <id> --round <n> --request-id <id> [--json]");
+            }
+            return await protocolLintCommand(args[2], { runId, round, requestId }, json, environment, io);
+        }
+        const observationResult = await handleObservationCommand(args, environment, io);
+        if (observationResult !== undefined)
+            return observationResult;
         if (args[0] === "run" &&
             args[1] === "takeover" &&
             typeof args[2] === "string" &&
@@ -453,7 +538,7 @@ export async function main(args = process.argv.slice(2), environment = process.e
             args[1] === "status" &&
             typeof args[2] === "string" &&
             (args.length === 3 || (args.length === 4 && args[3] === "--json"))) {
-            return runStatusCommand(args[2], args[3] === "--json", environment, io);
+            return await runStatusCommand(args[2], args[3] === "--json", environment, io);
         }
         if (args[0] === "run" &&
             (args[1] === "cancel" || args[1] === "stop") &&
@@ -484,9 +569,6 @@ export async function main(args = process.argv.slice(2), environment = process.e
                 io.stdout(`${result.runId}\t${result.jobId}\t${result.outcome}`);
             return 0;
         }
-        if (args[0] === "doctor" && args.length === 1) {
-            return doctorCommand(environment, io);
-        }
         io.stderr(`cueline: unrecognized command: ${args.join(" ")}`);
         io.stderr(usage());
         io.stderr("try `cueline help`");