@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/lab.ts

@@ -0,0 +1,607 @@
+/**
+ * `ocx lab` — Compatibility Lab inspection and explicit CL-08 automation controls.
+ *
+ * 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, readConfigDiagnostics } from "../config";
+import {
+  ARTIFACT_CLASSES,
+  EVIDENCE_LAYERS,
+  EVENT_KINDS,
+  EXECUTION_MODES,
+  OUTCOMES,
+  VERDICTS,
+  type ArtifactClass,
+  type CompatibilityVerdict,
+  type EvidenceLayer,
+  type ExecutionMode,
+  type LabEventKind,
+  type ObservationOutcome,
+} from "../lab/constants";
+import {
+  InvalidCursorError,
+  LabProjectionIncompatibleError,
+  LabProjectionUnavailableError,
+  queryLabArtifactByDigest,
+  queryLabArtifacts,
+  queryLabCatalogEntries,
+  queryLabEventById,
+  queryLabEvents,
+  queryLabObservations,
+  queryLabStatus,
+  queryLabSubjectById,
+  queryLabSubjects,
+  queryLabVerdicts,
+  queryPassiveProductionSignals,
+  type PassiveProductionQueryResultV1,
+} from "../lab/query";
+import { isLabRouteSubjectId } from "../usage/log";
+import {
+  CliUsageError,
+  RuntimeApiError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  takeFlag,
+  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";
+import {
+  exportLocalPublicEvidence,
+  importCommunityEvidenceFile,
+  listCommunityEvidenceContext,
+  previewLocalPublicEvidence,
+  verifyPublicEvidenceFile,
+  type PublicVerificationSummaryV1,
+} from "../lab/public";
+
+const USAGE = `Usage:
+  ocx lab status [--json]
+  ocx lab production-signals --subject <id> [--limit <n>] [--json]
+  ocx lab verdicts [--subject <id>] [--layer <layer>] [--suite <id>] [--verdict <v>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <c>] [--json]
+  ocx lab subjects [--kind <kind>] [--limit <n>] [--cursor <c>] [--json]
+  ocx lab subject <subjectId> [--json]
+  ocx lab observations [--subject <id>] [--layer <layer>] [--suite <id>] [--scenario <id>] [--outcome <o>] [--execution-mode <m>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <c>] [--json]
+  ocx lab events [--event-kind <k>] [--subject <id>] [--from <ms>] [--to <ms>] [--excluded <true|false>] [--limit <n>] [--cursor <c>] [--json]
+  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 public preview --event <eventId> [--event <eventId> ...] [--json]
+  ocx lab public export --event <eventId> [--event <eventId> ...] [--json]
+  ocx lab public verify --file <bundle.json> [--json]
+  ocx lab public import --file <bundle.json> [--json]
+  ocx lab public community [--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];
+
+export interface LabCliDeps {
+  configDir?: string;
+}
+
+class LabStateError extends RuntimeApiError {
+  constructor(message: string) {
+    super(message, 503, null);
+    this.name = "LabStateError";
+  }
+}
+
+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";
+}
+
+function takeEnumOption<T extends string>(
+  args: string[],
+  flag: string,
+  values: readonly T[],
+  message: string,
+): T | undefined {
+  const raw = takeOption(args, flag);
+  if (raw === undefined) return undefined;
+  if (!(values as readonly string[]).includes(raw)) {
+    throw new CliUsageError(message, USAGE);
+  }
+  return raw as T;
+}
+
+function assertRange(from: number | undefined, to: number | undefined): void {
+  if (from !== undefined && to !== undefined && from > to) {
+    throw new CliUsageError("--from must not be greater than --to", USAGE);
+  }
+}
+
+function appendPaginationHint(
+  lines: string[],
+  page: { hasMore: boolean; nextCursor?: string | null },
+): void {
+  if (page.hasMore) lines.push(`(more available; pass --cursor ${page.nextCursor ?? ""})`);
+}
+
+function statusSummary(status: ReturnType<typeof queryLabStatus>): string[] {
+  if (!status.projectionAvailable) {
+    if (status.projectionIncompatible) return ["Lab projection: incompatible"];
+    return ["Lab projection: unavailable"];
+  }
+  return [
+    "Lab projection: available",
+    `SQLite schema: ${status.sqliteSchemaVersion}`,
+    `Projection spec: ${status.projectionSpecVersion}`,
+    `Built at: ${status.builtAtMs}`,
+    `Events: ${status.eventCount} | Subjects: ${status.subjectCount} | Observations: ${status.observationCount}`,
+    `Claims: ${status.claimCount} | Verdicts: ${status.verdictCount} | Artifacts: ${status.artifactCount}`,
+    `Corruption rows: ${status.corruptionCount}`,
+  ];
+}
+
+function verdictLines(page: ReturnType<typeof queryLabVerdicts>): string[] {
+  const lines = page.items.map((v) =>
+    `${v.verdict} ${v.evidenceLayer} ${v.suiteId} subject=${v.subjectId} asOf=${v.asOf}`,
+  );
+  appendPaginationHint(lines, page);
+  return lines.length > 0 ? lines : ["No verdicts"];
+}
+
+function subjectListLines(page: ReturnType<typeof queryLabSubjects>): string[] {
+  const lines = page.items.map((s) => `${s.subjectId} (${s.subjectKind})`);
+  appendPaginationHint(lines, page);
+  return lines.length > 0 ? lines : ["No subjects"];
+}
+
+function observationLines(page: ReturnType<typeof queryLabObservations>): string[] {
+  const lines = page.items.map((o) =>
+    `${o.outcome} ${o.evidenceLayer} ${o.scenarioId} event=${o.eventId} completed=${o.completedAt}`,
+  );
+  appendPaginationHint(lines, page);
+  return lines.length > 0 ? lines : ["No observations"];
+}
+
+function eventListLines(page: ReturnType<typeof queryLabEvents>): string[] {
+  const lines = page.items.map((e) =>
+    `${e.eventKind} ${e.eventId} recorded=${e.recordedAt}${e.excluded ? " excluded" : ""}`,
+  );
+  appendPaginationHint(lines, page);
+  return lines.length > 0 ? lines : ["No events"];
+}
+
+function artifactLines(page: ReturnType<typeof queryLabArtifacts>): string[] {
+  const lines = page.items.map((a) => `${a.status} ${a.digest} class=${a.artifactClass ?? "unknown"}`);
+  appendPaginationHint(lines, page);
+  return lines.length > 0 ? lines : ["No artifacts"];
+}
+
+function catalogLines(scenarios: ReturnType<typeof queryLabCatalogEntries>): string[] {
+  const lines = scenarios.map((s) =>
+    `${s.evidenceLayer} ${s.suiteId} ${s.scenarioId} digest=${s.scenarioManifestDigest.slice(0, 12)}…`,
+  );
+  return lines.length > 0 ? lines : ["No catalog scenarios"];
+}
+
+function passiveProductionLines(result: PassiveProductionQueryResultV1): string[] {
+  const summary = result.summary;
+  return [
+    "Observed production traffic (not Lab verification)",
+    `Attempts: ${summary.recentProductionAttempts} | Successes: ${summary.recentSuccessfulAttempts} | Route errors: ${summary.recentRouteErrorSignals}`,
+    ...(summary.lastObservedProductionAttempt !== undefined
+      ? [`Last observed: ${summary.lastObservedProductionAttempt}`]
+      : []),
+  ];
+}
+
+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"];
+}
+
+function takeRepeatedOptions(args: string[], flag: string): string[] {
+  const values: string[] = [];
+  while (true) {
+    const index = args.indexOf(flag);
+    if (index < 0) break;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+      throw new CliUsageError(`${flag} requires a value`, USAGE);
+    }
+    values.push(value);
+    args.splice(index, 2);
+  }
+  return values;
+}
+
+function publicPreviewLines(result: ReturnType<typeof previewLocalPublicEvidence>): string[] {
+  return [
+    `Public evidence preview: ${result.bundle.records.length} exportable record(s)`,
+    `Excluded: ${result.excluded.length}`,
+    "Unsigned local preview; no publisher key or remote publish is created.",
+  ];
+}
+
+function publicExportLines(result: ReturnType<typeof exportLocalPublicEvidence>): string[] {
+  return [
+    "Public evidence exported locally",
+    `Bundle: ${result.bundle.bundleId}`,
+    `Publisher: ${result.bundle.publisher.keyId}`,
+    `Path: ${result.stored.path}`,
+    `Excluded: ${result.excluded.length}`,
+    "No remote publish occurred.",
+  ];
+}
+
+function publicVerificationLines(result: PublicVerificationSummaryV1): string[] {
+  if (result.status !== "cryptographically_valid") {
+    return [
+      `Public evidence verification: ${result.status}`,
+      "Not locally verified.",
+    ];
+  }
+  return [
+    "Public evidence verification: cryptographically valid",
+    `Bundle: ${result.bundleId}`,
+    `Publisher: ${result.publisherKeyId}`,
+    "Not locally verified. Signature validity proves integrity/continuity only.",
+  ];
+}
+
+function handlePublicLabCommand(
+  argv: string[],
+  wantsJson: boolean,
+  configDir: string,
+): void {
+  const [action, ...restInput] = argv;
+  const rest = [...restInput];
+  switch (action) {
+    case "preview": {
+      const eventIds = takeRepeatedOptions(rest, "--event");
+      rejectArgs(rest, USAGE);
+      const result = previewLocalPublicEvidence({ eventIds }, configDir);
+      printData(result, wantsJson, publicPreviewLines(result));
+      return;
+    }
+    case "export": {
+      const eventIds = takeRepeatedOptions(rest, "--event");
+      rejectArgs(rest, USAGE);
+      const result = exportLocalPublicEvidence({ eventIds }, configDir);
+      printData(result, wantsJson, publicExportLines(result));
+      return;
+    }
+    case "verify": {
+      const path = takeOption(rest, "--file");
+      if (!path) throw new CliUsageError("public verify requires --file", USAGE);
+      rejectArgs(rest, USAGE);
+      const result = verifyPublicEvidenceFile(path);
+      printData(result, wantsJson, publicVerificationLines(result));
+      if (result.status !== "cryptographically_valid") {
+        throw new RuntimeApiError(`public evidence verification failed: ${result.status}`, 422, result);
+      }
+      return;
+    }
+    case "import": {
+      const path = takeOption(rest, "--file");
+      if (!path) throw new CliUsageError("public import requires --file", USAGE);
+      rejectArgs(rest, USAGE);
+      const result = importCommunityEvidenceFile(path, configDir);
+      printData(result, wantsJson, [
+        `Community evidence imported: ${result.bundleId}`,
+        `Publisher: ${result.publisherKeyId}`,
+        "Trust: community_untrusted_v1; not locally verified.",
+      ]);
+      return;
+    }
+    case "community": {
+      rejectArgs(rest, USAGE);
+      const result = listCommunityEvidenceContext(configDir);
+      const lines = result.evidence.length > 0
+        ? result.evidence.map((row) =>
+          `${row.bundleId} publisher=${row.publisherKeyId} active=${row.activeRecordCount} revoked=${row.revokedRecordCount}`,
+        )
+        : ["No community evidence"];
+      printData(result, wantsJson, [
+        "Community evidence (untrusted, read-only context; not locally verified)",
+        ...lines,
+      ]);
+      return;
+    }
+    default:
+      throw new CliUsageError("unknown public subcommand", USAGE);
+  }
+}
+
+export async function handleLabCommand(argv: string[], deps: LabCliDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const configDir = deps.configDir ?? getConfigDir();
+    const argvCopy = [...argv];
+    const wantsJson = takeFlag(argvCopy, "--json");
+    const [sub = "status", ...rest] = argvCopy;
+
+    try {
+      switch (sub) {
+        case "public": {
+          handlePublicLabCommand(rest, wantsJson, configDir);
+          return;
+        }
+        case "status": {
+          rejectArgs(rest, USAGE);
+          const status = queryLabStatus(configDir);
+          printData(status, wantsJson, statusSummary(status));
+          return;
+        }
+        case "production-signals": {
+          const subjectId = takeOption(rest, "--subject");
+          const limit = takeIntegerOption(rest, "--limit", { min: 1 });
+          rejectArgs(rest, USAGE);
+          if (!subjectId) throw new CliUsageError("--subject is required", USAGE);
+          if (!isLabRouteSubjectId(subjectId)) {
+            throw new CliUsageError("--subject must be an exact Lab route subject id", USAGE);
+          }
+          const result = queryPassiveProductionSignals(subjectId, limit, configDir);
+          printData(result, wantsJson, passiveProductionLines(result));
+          return;
+        }
+        case "verdicts": {
+          const subjectId = takeOption(rest, "--subject");
+          const layer = takeEnumOption<EvidenceLayer>(
+            rest,
+            "--layer",
+            EVIDENCE_LAYERS,
+            "--layer must be a supported evidence layer",
+          );
+          const suiteId = takeOption(rest, "--suite");
+          const verdict = takeEnumOption<CompatibilityVerdict>(
+            rest,
+            "--verdict",
+            VERDICTS,
+            "--verdict must be a supported compatibility verdict",
+          );
+          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 = queryLabVerdicts({ subjectId, layer, suiteId, verdict, from, to }, cursor, limit, configDir);
+          printData(page, wantsJson, verdictLines(page));
+          return;
+        }
+        case "subjects": {
+          const kind = takeOption(rest, "--kind");
+          const limit = takeIntegerOption(rest, "--limit", { min: 1 });
+          const cursor = takeOption(rest, "--cursor");
+          rejectArgs(rest, USAGE);
+          const page = queryLabSubjects(kind, cursor, limit, configDir);
+          printData(page, wantsJson, subjectListLines(page));
+          return;
+        }
+        case "subject": {
+          const subjectId = rest[0];
+          if (!subjectId) throw new CliUsageError("subject id required", USAGE);
+          rest.splice(0, 1);
+          rejectArgs(rest, USAGE);
+          const subject = queryLabSubjectById(subjectId, configDir);
+          if (!subject) throw new CliUsageError("unknown subject", USAGE);
+          printData({ subject }, wantsJson, [`Subject ${subjectId}`]);
+          return;
+        }
+        case "observations": {
+          const subjectId = takeOption(rest, "--subject");
+          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 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);
+          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 subjectId = takeOption(rest, "--subject");
+          const from = takeIntegerOption(rest, "--from", { min: 0 });
+          const to = takeIntegerOption(rest, "--to", { min: 0 });
+          assertRange(from, to);
+          const excludedRaw = takeOption(rest, "--excluded");
+          if (excludedRaw !== undefined && excludedRaw !== "true" && excludedRaw !== "false") {
+            throw new CliUsageError("--excluded must be true or false", USAGE);
+          }
+          const limit = takeIntegerOption(rest, "--limit", { min: 1 });
+          const cursor = takeOption(rest, "--cursor");
+          rejectArgs(rest, USAGE);
+          const page = queryLabEvents({
+            eventKind,
+            subjectId,
+            from,
+            to,
+            excluded: excludedRaw === "true" ? true : excludedRaw === "false" ? false : undefined,
+          }, cursor, limit, configDir);
+          printData(page, wantsJson, eventListLines(page));
+          return;
+        }
+        case "event": {
+          const eventId = rest[0];
+          if (!eventId) throw new CliUsageError("event id required", USAGE);
+          rest.splice(0, 1);
+          rejectArgs(rest, USAGE);
+          const event = queryLabEventById(eventId, configDir);
+          if (!event) throw new CliUsageError("unknown event", USAGE);
+          printData({ event }, wantsJson, [`Event ${eventId}`]);
+          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 limit = takeIntegerOption(rest, "--limit", { min: 1 });
+          const cursor = takeOption(rest, "--cursor");
+          rejectArgs(rest, USAGE);
+          const page = queryLabArtifacts({ status, artifactClass }, cursor, limit, configDir);
+          printData(page, wantsJson, artifactLines(page));
+          return;
+        }
+        case "artifact": {
+          const digest = rest[0];
+          if (!digest) throw new CliUsageError("artifact digest required", USAGE);
+          rest.splice(0, 1);
+          rejectArgs(rest, USAGE);
+          const artifact = queryLabArtifactByDigest(digest, configDir);
+          if (!artifact) throw new CliUsageError("unknown artifact", USAGE);
+          printData({ artifact }, wantsJson, [`Artifact ${digest}`]);
+          return;
+        }
+        case "catalog": {
+          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);
+      }
+    } catch (err) {
+      if (err instanceof CliUsageError || err instanceof RuntimeApiError) throw err;
+      if (err instanceof LabProjectionUnavailableError || err instanceof LabProjectionIncompatibleError) {
+        throw new LabStateError(labErrorMessage(err));
+      }
+      throw new CliUsageError(labErrorMessage(err), USAGE);
+    }
+  });
+}
+
+export const LAB_USAGE = USAGE;

package/src/cli/launcher-context.ts

@@ -0,0 +1,77 @@
+/**
+ * Trusted facts captured by the plain-Node npm launcher before Bun auto-loads
+ * project dotenv files. The random proof travels in argv while the context
+ * travels in the environment, so a project `.env` cannot forge the pair during
+ * an ordinary `ocx ...` invocation.
+ */
+export const NODE_LAUNCH_CONTEXT_ENV = "OCX_NODE_LAUNCH_CONTEXT";
+export const NODE_LAUNCH_PROOF_PREFIX = "--ocx-internal-launch-proof=";
+
+export const ANTHROPIC_PARENT_ENV_SLOTS = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+] as const;
+
+export type AnthropicParentEnvSlot = typeof ANTHROPIC_PARENT_ENV_SLOTS[number];
+
+export type TrustedNodeLaunchContext = {
+  anthropicEnvSlots: readonly AnthropicParentEnvSlot[];
+};
+
+let trustedContext: TrustedNodeLaunchContext | null = null;
+
+function isLaunchProof(value: string): boolean {
+  return /^[A-Za-z0-9_-]{43}$/.test(value);
+}
+
+/** Consume the internal proof before normal CLI argument parsing. */
+export function initializeNodeLauncherContext(
+  argv: string[] = process.argv,
+  env: NodeJS.ProcessEnv = process.env,
+): TrustedNodeLaunchContext | null {
+  const proofArgs: string[] = [];
+  for (let index = argv.length - 1; index >= 2; index -= 1) {
+    const value = argv[index];
+    if (!value?.startsWith(NODE_LAUNCH_PROOF_PREFIX)) continue;
+    proofArgs.push(value.slice(NODE_LAUNCH_PROOF_PREFIX.length));
+    argv.splice(index, 1);
+  }
+
+  const raw = env[NODE_LAUNCH_CONTEXT_ENV];
+  delete env[NODE_LAUNCH_CONTEXT_ENV];
+  // Older launchers used this unauthenticated marker. Never let a project
+  // dotenv resurrect it as a trusted provenance channel.
+  delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
+  trustedContext = null;
+
+  if (proofArgs.length !== 1 || !raw || raw.length > 2048) return null;
+  const proof = proofArgs[0]!;
+  if (!isLaunchProof(proof)) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as {
+      version?: unknown;
+      proof?: unknown;
+      anthropicEnvSlots?: unknown;
+    };
+    if (parsed.version !== 1 || parsed.proof !== proof || !Array.isArray(parsed.anthropicEnvSlots)) {
+      return null;
+    }
+    const allowed = new Set<string>(ANTHROPIC_PARENT_ENV_SLOTS);
+    const slots = parsed.anthropicEnvSlots.filter(
+      (slot): slot is AnthropicParentEnvSlot => typeof slot === "string" && allowed.has(slot),
+    );
+    if (slots.length !== parsed.anthropicEnvSlots.length || new Set(slots).size !== slots.length) {
+      return null;
+    }
+    trustedContext = { anthropicEnvSlots: slots };
+    return trustedContext;
+  } catch {
+    return null;
+  }
+}
+
+export function trustedNodeLauncherContext(): TrustedNodeLaunchContext | null {
+  return trustedContext;
+}