feat(lab): CL-08 bounded automation with trusted live-route dispatch

src/cli/lab.ts

@@ -1,9 +1,10 @@
 /**
- * `ocx lab` — read-only Compatibility Lab inspection (CL-04).
+ * `ocx lab` — Compatibility Lab inspection and explicit CL-08 automation controls.
  *
- * Local SQLite projection reads; no daemon, network, probes, or rebuilds.
+ * Read commands use the local SQLite projection. Automation mutations and manual runs are
+ * explicit operator actions; read commands never start probes or scheduler ticks.
  */
-import { getConfigDir } from "../config";
+import { getConfigDir, readConfigDiagnostics } from "../config";
 import {
   ARTIFACT_CLASSES,
   EVIDENCE_LAYERS,
@@ -43,6 +44,23 @@ import {
   takeIntegerOption,
   takeOption,
 } from "./runtime-api";
+import {
+  buildLabAutomationStatus,
+  enqueueManualLabRun,
+  reconcileLabAutomationQueue,
+  setLabAutomationDispatchDeps,
+  startLabAutomationScheduler,
+  stopLabAutomationScheduler,
+} from "../lab/automation/orchestrator";
+import { loadLabAutomationState } from "../lab/automation/persistence";
+import {
+  loadLabAutomationConfig,
+  saveLabAutomationPolicyConfig,
+} from "../lab/automation/config-persistence";
+import { planManualLabRun } from "../lab/automation/planner";
+import { listLabAutomationRuns } from "../lab/automation/runs-query";
+import { LabAutomationError, type LabAutomationLayer } from "../lab/automation/types";
+import { createProductionLabRouteExecutor } from "../lib/lab-live-route-production";
 
 const USAGE = `Usage:
   ocx lab status [--json]
@@ -54,7 +72,12 @@ const USAGE = `Usage:
   ocx lab event <eventId> [--json]
   ocx lab artifacts [--status <s>] [--artifact-class <c>] [--limit <n>] [--cursor <c>] [--json]
   ocx lab artifact <digest> [--json]
-  ocx lab catalog [--layer <layer>] [--suite <id>] [--json]`;
+  ocx lab catalog [--layer <layer>] [--suite <id>] [--json]
+  ocx lab automation status [--json]
+  ocx lab automation enable [--protocol] [--live] [--json]
+  ocx lab automation disable [--json]
+  ocx lab automation runs [--limit <n>] [--cursor <c>] [--json]
+  ocx lab run --layer <layer> --scenario <id> [--provider <name>] [--model <id>] [--json]`;
 
 const ARTIFACT_STATUSES = ["present", "corrupt", "purged_unavailable"] as const;
 type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];
@@ -74,6 +97,7 @@ function labErrorMessage(err: unknown): string {
   if (err instanceof LabProjectionUnavailableError) return "lab projection is not available";
   if (err instanceof LabProjectionIncompatibleError) return "lab projection schema or spec version is incompatible";
   if (err instanceof InvalidCursorError) return "invalid cursor";
+  if (err instanceof LabAutomationError && err.code === "invalid_cursor") return "invalid cursor";
   return "lab read failed";
 }
 
@@ -163,6 +187,28 @@ function catalogLines(scenarios: ReturnType<typeof queryLabCatalogEntries>): str
   return lines.length > 0 ? lines : ["No catalog scenarios"];
 }
 
+function automationStatusLines(status: ReturnType<typeof buildLabAutomationStatus>): string[] {
+  return [
+    `Automation enabled: ${status.policy.enabled}`,
+    `Scheduler intent: ${status.policy.enabled ? "enabled" : "disabled"}`,
+    `Layers: protocol=${status.policy.layers.protocolConformance} live=${status.policy.layers.liveRouteCompatibility} task=${status.policy.layers.taskEffectiveness}`,
+    `Queued: ${status.counters.queued} | Running: ${status.counters.running}`,
+    `Run budget remaining: ${status.counters.remainingRunBudget} | Live request budget: ${status.counters.remainingLiveRequestBudget}`,
+  ];
+}
+
+function automationCliStatus(status: ReturnType<typeof buildLabAutomationStatus>) {
+  const { schedulerRunning: _processLocalSchedulerState, ...stable } = status;
+  return { ...stable, schedulerIntentEnabled: status.policy.enabled };
+}
+
+function runListLines(page: ReturnType<typeof listLabAutomationRuns>): string[] {
+  const lines = page.items.map((row) =>
+    `${row.runId} ${row.state} ${row.evidenceLayer} ${row.scenarioId} trigger=${row.trigger}`,
+  );
+  return lines.length > 0 ? lines : ["No automation runs"];
+}
+
 export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): Promise<number> {
   return runCliAction(async () => {
     const configDir = deps.configDir ?? getConfigDir();
@@ -199,14 +245,7 @@ export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): P
           const limit = takeIntegerOption(rest, "--limit", { min: 1 });
           const cursor = takeOption(rest, "--cursor");
           rejectArgs(rest, USAGE);
-          const page = queryLabVerdicts({
-            subjectId,
-            layer,
-            suiteId,
-            verdict,
-            from,
-            to,
-          }, cursor, limit, configDir);
+          const page = queryLabVerdicts({ subjectId, layer, suiteId, verdict, from, to }, cursor, limit, configDir);
           printData(page, wantsJson, verdictLines(page));
           return;
         }
@@ -231,52 +270,23 @@ export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): P
         }
         case "observations": {
           const subjectId = takeOption(rest, "--subject");
-          const layer = takeEnumOption<EvidenceLayer>(
-            rest,
-            "--layer",
-            EVIDENCE_LAYERS,
-            "--layer must be a supported evidence layer",
-          );
+          const layer = takeEnumOption<EvidenceLayer>(rest, "--layer", EVIDENCE_LAYERS, "--layer must be a supported evidence layer");
           const suiteId = takeOption(rest, "--suite");
           const scenarioId = takeOption(rest, "--scenario");
-          const outcome = takeEnumOption<ObservationOutcome>(
-            rest,
-            "--outcome",
-            OUTCOMES,
-            "--outcome must be a supported observation outcome",
-          );
-          const executionMode = takeEnumOption<ExecutionMode>(
-            rest,
-            "--execution-mode",
-            EXECUTION_MODES,
-            "--execution-mode must be a supported execution mode",
-          );
+          const outcome = takeEnumOption<ObservationOutcome>(rest, "--outcome", OUTCOMES, "--outcome must be a supported observation outcome");
+          const executionMode = takeEnumOption<ExecutionMode>(rest, "--execution-mode", EXECUTION_MODES, "--execution-mode must be a supported execution mode");
           const from = takeIntegerOption(rest, "--from", { min: 0 });
           const to = takeIntegerOption(rest, "--to", { min: 0 });
           assertRange(from, to);
           const limit = takeIntegerOption(rest, "--limit", { min: 1 });
           const cursor = takeOption(rest, "--cursor");
           rejectArgs(rest, USAGE);
-          const page = queryLabObservations({
-            subjectId,
-            layer,
-            suiteId,
-            scenarioId,
-            outcome,
-            executionMode,
-            from,
-            to,
-          }, cursor, limit, configDir);
+          const page = queryLabObservations({ subjectId, layer, suiteId, scenarioId, outcome, executionMode, from, to }, cursor, limit, configDir);
           printData(page, wantsJson, observationLines(page));
           return;
         }
         case "events": {
-          const eventKind = takeEnumOption<LabEventKind>(
-            rest,
-            "--event-kind",
-            EVENT_KINDS,
-            "--event-kind must be a supported lab event kind",
-          );
+          const eventKind = takeEnumOption<LabEventKind>(rest, "--event-kind", EVENT_KINDS, "--event-kind must be a supported lab event kind");
           const subjectId = takeOption(rest, "--subject");
           const from = takeIntegerOption(rest, "--from", { min: 0 });
           const to = takeIntegerOption(rest, "--to", { min: 0 });
@@ -309,18 +319,8 @@ export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): P
           return;
         }
         case "artifacts": {
-          const status = takeEnumOption<ArtifactStatus>(
-            rest,
-            "--status",
-            ARTIFACT_STATUSES,
-            "--status must be present, corrupt, or purged_unavailable",
-          );
-          const artifactClass = takeEnumOption<ArtifactClass>(
-            rest,
-            "--artifact-class",
-            ARTIFACT_CLASSES,
-            "--artifact-class must be a supported artifact class",
-          );
+          const status = takeEnumOption<ArtifactStatus>(rest, "--status", ARTIFACT_STATUSES, "--status must be present, corrupt, or purged_unavailable");
+          const artifactClass = takeEnumOption<ArtifactClass>(rest, "--artifact-class", ARTIFACT_CLASSES, "--artifact-class must be a supported artifact class");
           const limit = takeIntegerOption(rest, "--limit", { min: 1 });
           const cursor = takeOption(rest, "--cursor");
           rejectArgs(rest, USAGE);
@@ -339,18 +339,101 @@ export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): P
           return;
         }
         case "catalog": {
-          const layer = takeEnumOption<EvidenceLayer>(
-            rest,
-            "--layer",
-            EVIDENCE_LAYERS,
-            "--layer must be a supported evidence layer",
-          );
+          const layer = takeEnumOption<EvidenceLayer>(rest, "--layer", EVIDENCE_LAYERS, "--layer must be a supported evidence layer");
           const suiteId = takeOption(rest, "--suite");
           rejectArgs(rest, USAGE);
           const scenarios = queryLabCatalogEntries({ layer, suiteId });
           printData({ scenarios }, wantsJson, catalogLines(scenarios));
           return;
         }
+        case "automation": {
+          const [automationSub = "status", ...automationRest] = rest;
+          switch (automationSub) {
+            case "status": {
+              rejectArgs(automationRest, USAGE);
+              const status = buildLabAutomationStatus(configDir);
+              printData(automationCliStatus(status), wantsJson, automationStatusLines(status));
+              return;
+            }
+            case "enable": {
+              const enableProtocol = takeFlag(automationRest, "--protocol");
+              const enableLive = takeFlag(automationRest, "--live");
+              rejectArgs(automationRest, USAGE);
+              const selectionExplicit = enableProtocol || enableLive;
+              const current = loadLabAutomationConfig(configDir).policy;
+              const policy = {
+                ...current,
+                enabled: true,
+                layers: {
+                  protocolConformance: selectionExplicit ? enableProtocol : current.layers.protocolConformance,
+                  liveRouteCompatibility: selectionExplicit ? enableLive : current.layers.liveRouteCompatibility,
+                  taskEffectiveness: false,
+                },
+                taskEffectivenessBackgroundEnabled: false,
+              };
+              saveLabAutomationPolicyConfig(policy, configDir);
+              reconcileLabAutomationQueue(configDir);
+              startLabAutomationScheduler(configDir);
+              const status = buildLabAutomationStatus(configDir);
+              printData(automationCliStatus(status), wantsJson, automationStatusLines(status));
+              return;
+            }
+            case "disable": {
+              rejectArgs(automationRest, USAGE);
+              const policy = { ...loadLabAutomationConfig(configDir).policy, enabled: false };
+              saveLabAutomationPolicyConfig(policy, configDir);
+              reconcileLabAutomationQueue(configDir);
+              stopLabAutomationScheduler(configDir);
+              const status = buildLabAutomationStatus(configDir);
+              printData(automationCliStatus(status), wantsJson, automationStatusLines(status));
+              return;
+            }
+            case "runs": {
+              const limit = takeIntegerOption(automationRest, "--limit", { min: 1 });
+              const cursor = takeOption(automationRest, "--cursor");
+              rejectArgs(automationRest, USAGE);
+              const page = listLabAutomationRuns(loadLabAutomationState(configDir), limit ?? 50, cursor);
+              printData(page, wantsJson, runListLines(page));
+              return;
+            }
+            default:
+              throw new CliUsageError(`unknown automation subcommand: ${automationSub}`, USAGE);
+          }
+        }
+        case "run": {
+          const layer = takeEnumOption<LabAutomationLayer>(
+            rest,
+            "--layer",
+            ["protocol_conformance", "live_route_compatibility", "task_effectiveness"] as const,
+            "--layer must be protocol_conformance, live_route_compatibility, or task_effectiveness",
+          );
+          const scenarioId = takeOption(rest, "--scenario");
+          const providerName = takeOption(rest, "--provider");
+          const modelId = takeOption(rest, "--model");
+          rejectArgs(rest, USAGE);
+          if (!layer || !scenarioId) throw new CliUsageError("--layer and --scenario are required", USAGE);
+          const configSnapshot = readConfigDiagnostics().config;
+          if (layer === "live_route_compatibility") {
+            const loadConfig = () => configSnapshot;
+            setLabAutomationDispatchDeps({
+              configDir,
+              loadConfig,
+              routeExecutor: createProductionLabRouteExecutor({ configDir, loadConfig }),
+            });
+          }
+          const planned = planManualLabRun({
+            evidenceLayer: layer,
+            scenarioId,
+            providerName,
+            modelId,
+            config: configSnapshot,
+            configDir,
+          });
+          const record = await enqueueManualLabRun(planned, configDir);
+          if (!record) throw new CliUsageError("manual run enqueue failed", USAGE);
+          printData({ run: record }, wantsJson, [`Manual run ${record.runId} -> ${record.state}`]);
+          return;
+        }
         default:
           throw new CliUsageError(`unknown lab subcommand: ${sub}`, USAGE);
       }
@@ -364,4 +447,4 @@ export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): P
   });
 }
 
-export const LAB_USAGE = USAGE;
+export const LAB_USAGE = USAGE;

src/lab/automation/budgets.ts

@@ -0,0 +1,78 @@
+import { LAB_AUTOMATION_HARD_MAX } from "./constants";
+import type { LabAutomationPolicyV1, LabAutomationStateV1 } from "./types";
+
+export function rollBudgetWindow(state: LabAutomationStateV1, now: number): LabAutomationStateV1 {
+  if (now - state.budgetWindowStartedAt < LAB_AUTOMATION_HARD_MAX.budgetWindowMs) return state;
+  return {
+    ...state,
+    budgetWindowStartedAt: now,
+    runsThisHour: 0,
+    liveRequestsThisHour: 0,
+  };
+}
+
+function rollingStartedRuns(state: LabAutomationStateV1, now: number): number {
+  const cutoff = now - LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+  return state.runs.filter((run) => typeof run.startedAt === "number" && run.startedAt > cutoff && run.startedAt <= now).length;
+}
+
+function rollingStartedLiveRuns(state: LabAutomationStateV1, now: number): number {
+  const cutoff = now - LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+  return state.runs.filter((run) =>
+    run.evidenceLayer === "live_route_compatibility"
+    && typeof run.startedAt === "number"
+    && run.startedAt > cutoff
+    && run.startedAt <= now
+  ).length;
+}
+
+function legacyCounterActive(state: LabAutomationStateV1, now: number): boolean {
+  return now - state.budgetWindowStartedAt < LAB_AUTOMATION_HARD_MAX.budgetWindowMs;
+}
+
+export function runBudgetRemaining(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): number {
+  const rolling = rollingStartedRuns(state, now);
+  const legacy = legacyCounterActive(state, now) ? state.runsThisHour : 0;
+  return Math.max(0, policy.maxRunsPerHour - Math.max(rolling, legacy));
+}
+
+export function liveRequestBudgetRemaining(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): number {
+  const rolling = rollingStartedLiveRuns(state, now);
+  const legacy = legacyCounterActive(state, now) ? state.liveRequestsThisHour : 0;
+  return Math.max(0, policy.maxLiveRequestsPerHour - Math.max(rolling, legacy));
+}
+
+export function isRunBudgetExhausted(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): boolean {
+  return runBudgetRemaining(policy, state, now) <= 0;
+}
+
+export function isLiveRequestBudgetExhausted(
+  policy: LabAutomationPolicyV1,
+  state: LabAutomationStateV1,
+  now = Date.now(),
+): boolean {
+  return liveRequestBudgetRemaining(policy, state, now) <= 0;
+}
+
+/** Legacy persisted counters remain for schema compatibility; startedAt records are rolling authority. */
+export function recordRunBudgetUse(state: LabAutomationStateV1, liveRequest: boolean): LabAutomationStateV1 {
+  return {
+    ...state,
+    runsThisHour: Math.min(LAB_AUTOMATION_HARD_MAX.maxRunsPerHour, state.runsThisHour + 1),
+    liveRequestsThisHour: liveRequest
+      ? Math.min(LAB_AUTOMATION_HARD_MAX.maxLiveRequestsPerHour, state.liveRequestsThisHour + 1)
+      : state.liveRequestsThisHour,
+  };
+}