agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/cli/commands/query.js

@@ -1,12 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveArtifactPath } from "../../registries/artifactRegistry.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+import { loadDocsPathOverrides, resolveArtifactPath, } from "../../registries/artifactRegistry.js";
 import { activeObjectiveName, artifactPath, discoverSchemasDir, loadSchemas, resolveArtifactPathLocal, } from "../appContext.js";
 import { validateAgentString } from "../argvalidate.js";
-import { loadDocsPathOverrides } from "../../registries/artifactRegistry.js";
 import { emitStructured } from "../structured.js";
-import { COMMAND_FILTERS, emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, recentCycles, sourceMetadata, structuredState, validateFilterValues, } from "../stateQuery.js";
+import { COMMAND_FILTERS, emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, sourceMetadata, structuredState, validateFilterValues, } from "../stateQuery.js";
 import { displayFields, queryTodo } from "./state/index.js";
+import { STATE_FAMILY_GET_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "../capabilityContext/types.js";
+import { entityPublicRetrieval } from "../../state/retrievalAuthority.js";
+import { listProgressEntities } from "../../state/progressEntities.js";
+import { readChangelog } from "../../state/changelog.js";
 const ENCODED_TRAVERSAL_RE = /%(?:2e|2f|5c)/i;
 const ALLOWED_RAW_ARTIFACT_USES = [
     "artifact writes",
@@ -17,7 +21,7 @@ const ALLOWED_RAW_ARTIFACT_USES = [
     "unavailable or incomplete CLI state after CLI fallbacks",
     "benchmark analysis",
 ];
-const BENCHMARK_CONTEXT_COMMAND = "agentera prime --context optimize --format json";
+const BENCHMARK_CONTEXT_COMMAND = preCutoverCommand("prime --context optimize --format json");
 const STATE_COMMAND_NAMES = new Set([
     "decisions",
     "docs",
@@ -43,7 +47,16 @@ function projectRelativeOrAbsolute(p) {
 }
 function artifactReadInterfaces(name, record) {
     const artifactId = record !== null ? record.artifactId : name;
-    const routineCommand = STATE_COMMAND_NAMES.has(artifactId) ? `agentera ${artifactId} --format json` : null;
+    const retrieval = (entityPublicRetrieval().commands ?? {});
+    const experimentList = retrieval.experiments.list
+        .replace(" [--limit N] [--cursor TOKEN]", " --limit 20");
+    const routineCommand = artifactId === "experiments"
+        ? experimentList
+        : STATE_FAMILY_LIST_COMMANDS[artifactId] ?? (STATE_COMMAND_NAMES.has(artifactId) ? `agentera state ${artifactId} --format json` : null);
+    const requiredSelectors = artifactId === "experiments" ? ["--objective OBJECTIVE_ID"] : [];
+    const detailCommand = artifactId === "experiments"
+        ? retrieval.experiments.get
+        : STATE_FAMILY_GET_COMMANDS[artifactId] ?? null;
     let advancedCommand;
     if (artifactId === "benchmark_context")
         advancedCommand = BENCHMARK_CONTEXT_COMMAND;
@@ -52,7 +65,11 @@ function artifactReadInterfaces(name, record) {
     else
         advancedCommand = `agentera query ${artifactId} --format json`;
     let policy;
-    if (routineCommand)
+    if (artifactId === "experiments")
+        policy = "Replace OBJECTIVE_ID with one stable objective identity, use the objective-scoped bounded list for discovery, and use exact get for detail; no selector-free normal read exists.";
+    else if (STATE_FAMILY_LIST_COMMANDS[artifactId])
+        policy = "Use bounded state list for discovery and exact state get for detail before any raw artifact access.";
+    else if (routineCommand)
         policy = "Use the routine state command for normal content reads before any raw artifact access.";
     else if (advancedCommand)
         policy = "Use the listed CLI discovery/query surface before any last-resort raw artifact access.";
@@ -60,6 +77,9 @@ function artifactReadInterfaces(name, record) {
         policy = "No normal content-read command is registered; raw access is limited to allowed boundary cases.";
     return {
         normal_read_command: routineCommand,
+        normal_read_required_selectors: requiredSelectors,
+        normal_detail_command: detailCommand,
+        normal_read_guidance: policy,
         advanced_query_command: advancedCommand,
         raw_access_boundary: {
             normal_policy: policy,
@@ -67,7 +87,7 @@ function artifactReadInterfaces(name, record) {
         },
     };
 }
-function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
+function artifactLocationRecord(name, info, schemasDir) {
     const record = info.record ?? null;
     const schema = info.schema && typeof info.schema === "object" ? info.schema : {};
     // cast: schema.meta is read from a parsed artifact schema (YAML IO boundary)
@@ -76,13 +96,14 @@ function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
     const artifactId = record !== null ? record.artifactId : name;
     const displayName = record !== null ? record.displayName : String(meta.name ?? name);
     const defaultPath = record !== null ? record.defaultPath : String(info.path ?? "");
-    let mappedPath = defaultPath;
-    let resolutionSource = record !== null ? "registry default" : "schema metadata";
+    const docsOverrides = record !== null ? loadDocsPathOverrides(process.cwd()) : {};
+    const mappedPath = record !== null && record.docsYamlCanOverridePath && record.displayName in docsOverrides
+        ? docsOverrides[record.displayName]
+        : defaultPath;
+    const resolutionSource = record !== null
+        ? mappedPath === defaultPath ? "registry default" : "docs mapping for registry identity"
+        : "schema metadata";
     const caveats = [];
-    if (record !== null && record.docsYamlCanOverridePath && record.displayName in docsOverrides) {
-        mappedPath = docsOverrides[record.displayName];
-        resolutionSource = ".agentera/docs.yaml mapping";
-    }
     const objectiveName = activeObjectiveName();
     let resolvedPath = null;
     if (record !== null && record.pathTemplate && mappedPath.includes("<name>") && !objectiveName) {
@@ -104,14 +125,15 @@ function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
         display_path: resolvedPath !== null ? projectRelativeOrAbsolute(resolvedPath) : mappedPath,
         resolution_source: resolutionSource,
         exists: resolvedPath !== null ? fs.existsSync(resolvedPath) : false,
-        docs_yaml_can_override_path: record !== null ? record.docsYamlCanOverridePath : false,
+        docs_yaml_can_override_path: record?.docsYamlCanOverridePath ?? false,
         project_boundary_check: resolvedPath !== null ? "enforced" : "not_resolved",
     };
     return {
-        artifact_id: artifactId,
+        artifact: artifactId,
         name: artifactId,
         display_name: displayName,
         artifact_type: record !== null ? record.artifactType : meta.artifact_type ?? "unknown",
+        implementation_status: record !== null ? record.implementationStatus : meta.implementation_status ?? "implemented",
         format: typeof meta === "object" ? meta.format ?? "unknown" : "unknown",
         producer: record !== null ? [...record.producers].sort() : meta.producer ?? "unknown",
         consumers: record !== null ? [...record.consumers].sort() : meta.consumers ?? "unknown",
@@ -130,9 +152,8 @@ function fileExists(p) {
     }
 }
 export function artifactLocationContract(schemasDir, schemas) {
-    const docsOverrides = loadDocsPathOverrides(process.cwd());
     const names = Object.keys(schemas).sort();
-    const records = names.map((name) => artifactLocationRecord(name, schemas[name], schemasDir, docsOverrides));
+    const records = names.map((name) => artifactLocationRecord(name, schemas[name], schemasDir));
     // cast: record.caveats is built from schema/registry path resolution (IO boundary)
     const caveats = records.flatMap((record) => record.caveats);
     return {
@@ -140,8 +161,7 @@ export function artifactLocationContract(schemasDir, schemas) {
         status: dirExists(schemasDir) ? "complete" : "missing_schemas",
         source: {
             schemas_dir: schemasDir,
-            docs_yaml_path: path.join(process.cwd(), ".agentera", "docs.yaml"),
-            docs_yaml_overrides_loaded: Object.keys(docsOverrides).length > 0,
+            path_overrides: "disabled_for_entity_authority",
         },
         source_contract: {
             raw_artifact_reads_required_for_discovery: false,
@@ -213,30 +233,35 @@ function queryGeneric(args, schemas, name, io) {
     }
     return 0;
 }
-function queryLastPhase(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
+function matchedSchemaName(schemas, query) {
+    if (query in schemas)
+        return query;
+    return Object.keys(schemas).find((name) => query === name.replace(/s$/, "") || query === `${name}s`) ?? null;
+}
+function rejectEntityAggregateQuery(args, name, query, io) {
     const format = args.format ?? "text";
-    const info = schemas.progress;
-    if (!info) {
-        e(missingSchemaError("progress") + "\n");
-        return 1;
+    const command = `agentera state ${name} --format ${format}`;
+    if (format !== "text") {
+        emitStructured({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: "unsupported_target", message: `routine artifact alias '${query}' is not available through state query`, syntax: command, example: command, recovery: `Use the canonical entity-aware command: ${command}` } }, format, out(io));
     }
-    const data = loadArtifact(artifactPath(info, "progress"));
-    const entries = extractEntries(data);
-    if (entries.length === 0) {
-        if (format !== "text")
-            emitStructured(null, format, o);
-        return 0;
+    else {
+        err(io)(`Unsupported routine query: ${query}. Use \`${command}\` instead.\n`);
     }
-    const last = recentCycles(entries, 1)[0];
-    const phase = last.phase ?? "";
-    if (format !== "text") {
-        emitStructured({ phase }, format, o);
-        return 0;
+    return 1;
+}
+function queryLastPhase(args, schemas, io) {
+    const o = out(io);
+    const format = args.format ?? "text";
+    const response = listProgressEntities(process.cwd(), 1, {}, undefined, { format: format });
+    const entry = Array.isArray(response.entries) ? response.entries[0] : undefined;
+    const record = entry?.record;
+    const phase = String(record?.phase ?? "");
+    if (format === "text") {
+        if (phase)
+            o(`${phase}\n`);
     }
-    if (phase)
-        o(phase + "\n");
+    else
+        emitStructured(entry ? { phase, id: entry.id, artifact: entry.artifact, provenance: entry.provenance, snapshot: response.snapshot, retrieval: { get: `agentera state progress get --id ${entry.id} --format json` } } : null, format, o);
     return 0;
 }
 function queryDesign(args, schemas, io) {
@@ -317,10 +342,6 @@ export function cmdQuery(args, io) {
     if (query.includes("/") || query.includes("\\") || query === "." || query === ".." || ENCODED_TRAVERSAL_RE.test(query)) {
         throw new Error(`unsupported artifact/query name ${pyRepr(query)}; path-like values are not artifact names`);
     }
-    if (STATE_COMMAND_NAMES.has(query)) {
-        e(`Unsupported routine query: ${query}. Use \`agentera ${query}\` instead.\n`);
-        return 1;
-    }
     const schemas = loadSchemas(discoverSchemasDir());
     const stateArgs = args;
     const handlers = {
@@ -329,16 +350,18 @@ export function cmdQuery(args, io) {
         "open-todos": (a, s, ioo) => queryTodo({ ...a, command: "todo" }, s, ioo, true),
     };
     if (query in handlers) {
-        if (format !== "text" && query in schemas)
-            return queryGeneric(args, schemas, query, io);
-        return handlers[query](args, schemas, io);
+        if (format === "text" || !(query in schemas))
+            return handlers[query](args, schemas, io);
     }
-    if (query in schemas)
-        return queryGeneric(args, schemas, query, io);
-    for (const name of Object.keys(schemas)) {
-        if (query === name || query === name.replace(/s$/, "") || query === name + "s") {
-            return queryGeneric(args, schemas, name, io);
+    const name = matchedSchemaName(schemas, query);
+    if (name !== null) {
+        if (STATE_COMMAND_NAMES.has(name)) {
+            return rejectEntityAggregateQuery(args, name, query, io);
+        }
+        if (name === "changelog" && format !== "text") {
+            return emitStateStructured(name, readChangelog(process.cwd()).projection, format, args.fields, o, e);
         }
+        return queryGeneric(args, schemas, name, io);
     }
     e(`Unknown query: ${query}\n`);
     return 1;
@@ -346,4 +369,3 @@ export function cmdQuery(args, io) {
 function pyRepr(value) {
     return value.includes("'") && !value.includes('"') ? `"${value}"` : `'${value}'`;
 }
-//# sourceMappingURL=query.js.map

package/dist/cli/commands/report.js

@@ -5,14 +5,22 @@ import { resolveProfileDirOverride, resolveXdgDataHome } from "../../core/envPat
 import { expanduser } from "../../core/paths.js";
 import { usageMain, corpusTooLargeReason } from "../../analytics/usageStats.js";
 import { extractCorpusMain } from "../../analytics/extractCorpus.js";
+import { tiersDirForCorpusPath, assessTiers, readBoundedMetadata, } from "../../analytics/extractCorpus/index.js";
 function buildExtractArgv(args, corpusPath) {
-    const argv = ["--output", corpusPath];
+    // Refresh publishes bounded evidence tiers to the directory co-located with
+    // the canonical corpus path (`<dir>/tiers`); the extract engine no longer
+    // accepts the monolithic `--output corpusPath` write target (tiers are the
+    // only canonical output). Passing `--tier-output` makes the displayed
+    // `corpus_path`/`tier_path` truthful: tiers land at `dirname(corpusPath)/tiers`.
+    const argv = ["--tier-output", tiersDirForCorpusPath(corpusPath)];
     for (const root of args.projectRoot ?? [])
         argv.push("--project-root", root);
     if (args.codexSessionsDir)
         argv.push("--codex-sessions-dir", args.codexSessionsDir);
     if (args.claudeProjectsDir)
         argv.push("--claude-projects-dir", args.claudeProjectsDir);
+    for (const source of args.importSources ?? [])
+        argv.push("--import-source", source);
     if (args.opencodeConversationsDir)
         argv.push("--opencode-conversations-dir", args.opencodeConversationsDir);
     if (args.copilotConversationsDir)
@@ -23,8 +31,6 @@ function buildExtractArgv(args, corpusPath) {
         argv.push("--cursor-chats-dir", args.cursorChatsDir);
     if (args.noCodex)
         argv.push("--no-codex");
-    if (args.noClaude)
-        argv.push("--no-claude");
     if (args.noOpencode)
         argv.push("--no-opencode");
     if (args.noCopilot)
@@ -38,7 +44,7 @@ function buildExtractArgv(args, corpusPath) {
     return argv;
 }
 function usageSyntax() {
-    return "agentera usage [--format text|json] [--corpus PATH] [--project VALUE]";
+    return "agentera usage [--format text|json] [--corpus PATH] [--project VALUE] [--sources active|all]";
 }
 function usageExample() {
     return "agentera usage --format json --project agentera";
@@ -73,30 +79,62 @@ export function statsCorpusPath(env = process.env, platform = process.platform)
 }
 /** Faithful port of `_stats_existing_corpus_status`. */
 export function statsExistingCorpusStatus(corpusPath) {
+    // Bounded tier path: when tiers are published, report readiness from the
+    // manifest + retained corpus metadata without reading full evidence. The
+    // documented `tier_state`/`tier_path` fields extend the legacy shape;
+    // existing `status`/`reason`/`extracted_at`/`total_records` are preserved.
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    if (assessment.analyzable) {
+        const meta = readBoundedMetadata(tiersDir);
+        const manifest = meta.manifest;
+        const extractedAt = meta.corpusMetadata?.extracted_at ?? null;
+        return {
+            status: "ready",
+            path: corpusPath,
+            tier_path: tiersDir,
+            tier_state: assessment.state,
+            reason: "bounded evidence tier published",
+            extracted_at: extractedAt ?? (manifest?.published_at ?? null),
+            total_records: manifest?.total_records ?? 0,
+        };
+    }
+    if (assessment.state === "oversized" || assessment.state === "corrupt") {
+        return {
+            status: "stale",
+            path: corpusPath,
+            tier_path: tiersDir,
+            tier_state: assessment.state,
+            reason: assessment.recovery ?? `${assessment.state} evidence tier`,
+            ...(assessment.artifact ? { artifact: assessment.artifact } : {}),
+        };
+    }
+    // Legacy or missing: preserve the corpus-envelope status behavior.
     if (!fs.existsSync(corpusPath)) {
         return { status: "missing", path: corpusPath, reason: "corpus file does not exist" };
     }
     const tooLarge = corpusTooLargeReason(corpusPath);
     if (tooLarge) {
-        return { status: "stale", path: corpusPath, reason: tooLarge };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: tooLarge };
     }
     let data;
     try {
         data = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
     }
     catch (exc) {
-        return { status: "stale", path: corpusPath, reason: `corpus is not readable JSON: ${exc.message}` };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: `corpus is not readable JSON: ${exc.message}` };
     }
     const records = data && typeof data === "object" && !Array.isArray(data) ? data.records ?? [] : [];
     const hasTurn = Array.isArray(records) &&
         records.some((r) => r && typeof r === "object" && r.source_kind === "conversation_turn");
     if (!hasTurn) {
-        return { status: "stale", path: corpusPath, reason: "corpus has no conversation_turn records" };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: "corpus has no conversation_turn records" };
     }
     const metadata = data.metadata && typeof data.metadata === "object" ? data.metadata : {};
     return {
         status: "ready",
         path: corpusPath,
+        tier_state: "legacy",
         reason: "existing corpus has conversation_turn records",
         extracted_at: metadata.extracted_at ?? null,
         total_records: records.length,
@@ -105,9 +143,9 @@ export function statsExistingCorpusStatus(corpusPath) {
 /**
  * Faithful port of scripts/agentera `cmd_stats` (canonical command is `report`;
  * `stats` is the deprecated alias and shares this logic). The plain read path
- * reuses the ported usage engine; corpus refresh (which would run the maintainer
- * extractor over local runtime history) is reported as unavailable in the
- * self-contained package.
+ * reuses the ported usage engine over bounded tiers (with a legacy
+ * corpus.json fallback when no tiers are published). `stats refresh` publishes
+ * bounded tiers from local runtime history under explicit consent.
  */
 export function cmdReport(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
@@ -143,27 +181,31 @@ export function cmdReport(args, io = {}) {
                 privacy: {
                     local_history_read: false,
                     local_history_write: false,
-                    corpus_write: false,
+                    tier_write: false,
                     required_consent: "local-history",
                     provided_consent: null,
                 },
                 corpus_path: corpusPath,
+                tier_path: tiersDirForCorpusPath(corpusPath),
                 engine: { command: engineCommand },
                 diagnostics: [
-                    "dry-run does not read runtime history or write corpus files",
-                    "generated corpus is internal state for stats at $AGENTERA_PROFILE_DIR/intermediate/corpus.json",
+                    "dry-run does not read runtime history or write tier files",
+                    "published tiers are internal state for stats at $AGENTERA_PROFILE_DIR/intermediate/tiers",
+                    ...(args.importSources?.includes("claude")
+                        ? ["Claude historical import can contain secrets, file contents, and command output; apply stays local and read-only"]
+                        : []),
                 ],
             };
             if (outputFormat === "json") {
                 out(JSON.stringify(payload, null, 2) + "\n");
             }
             else {
-                out(`agentera stats refresh: dry_run\ncorpus=${corpusPath}\nengine=${engineCommand.join(" ")}\n`);
-                out("privacy=local_history_read=false, corpus_write=false, required_consent=local-history\n");
+                out(`agentera stats refresh: dry_run\ncorpus=${corpusPath}\ntiers=${tiersDirForCorpusPath(corpusPath)}\nengine=${engineCommand.join(" ")}\n`);
+                out("privacy=local_history_read=false, tier_write=false, required_consent=local-history\n");
             }
             return 0;
         }
-        // consent === "local-history": run the corpus extractor over local history.
+        // consent === "local-history": extract local history into bounded tiers.
         let engineOut = "";
         let engineErr = "";
         const rc = extractCorpusMain(engineArgv, {
@@ -175,15 +217,26 @@ export function cmdReport(args, io = {}) {
             command: "stats refresh",
             status: refreshStatus,
             exit_signal: rc === 4 ? "EX2" : null,
-            privacy: { local_history_read: true, local_history_write: false, corpus_write: rc === 0, required_consent: "local-history", provided_consent: "local-history" },
+            privacy: {
+                local_history_read: true,
+                local_history_write: false,
+                tier_write: rc === 0,
+                required_consent: "local-history",
+                provided_consent: "local-history",
+                historical_imports: args.importSources ?? [],
+                historical_import_warning: args.importSources?.includes("claude")
+                    ? "Claude transcripts can contain secrets, file contents, and command output. Import is local and read-only."
+                    : null,
+            },
             corpus_path: corpusPath,
+            tier_path: tiersDirForCorpusPath(corpusPath),
             engine: { command: engineCommand, exit_code: rc, stdout: engineOut.split("\n").filter((l) => l), stderr: engineErr.split("\n").filter((l) => l) },
         };
         if (outputFormat === "json") {
             out(JSON.stringify(payload, null, 2) + "\n");
         }
         else {
-            out(`agentera stats refresh: ${payload.status}\ncorpus=${corpusPath}\n`);
+            out(`agentera stats refresh: ${payload.status}\ncorpus=${corpusPath}\ntiers=${tiersDirForCorpusPath(corpusPath)}\n`);
             if (engineOut)
                 out(engineOut);
             if (engineErr)
@@ -221,6 +274,8 @@ export function cmdReport(args, io = {}) {
     const engineArgs = ["--corpus", corpusPath];
     if (args.project)
         engineArgs.push("--project", args.project);
+    if (args.sources)
+        engineArgs.push("--sources", args.sources);
     if (outputFormat === "json")
         engineArgs.push("--json");
     return usageMain(engineArgs, {
@@ -228,4 +283,3 @@ export function cmdReport(args, io = {}) {
         err: (t) => err(t + "\n"),
     });
 }
-//# sourceMappingURL=report.js.map

package/dist/cli/commands/route.js

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { HybridRouteRegistryError, resolveRouteRequest } from "../../registries/hybridRoute.js";
+import { RouteReceiptValidationError, validateRouteReceiptSubmission } from "../../registries/hybridRouteReceipt.js";
+import { evaluateHybridRoute } from "../../eval/hybridRouteEvaluation.js";
+import { emitStructured } from "../structured.js";
+import { emitInvalidInput } from "../errors.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+/** A conformance report that fails is a failed CLI gate, not a successful invocation. */
+export const ROUTE_EVALUATION_FAILED_EXIT_CODE = 1;
+export function routeEvaluationExitCode(report) {
+    return report.status === "fail" ? ROUTE_EVALUATION_FAILED_EXIT_CODE : 0;
+}
+function decodeRouteInput(bytes) {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function loadRouteInput(source, readStdin) {
+    let bytes;
+    try {
+        if (source === "-") {
+            const stdin = readStdin();
+            bytes = typeof stdin === "string" ? Buffer.from(stdin, "utf8") : stdin;
+        }
+        else {
+            bytes = fs.readFileSync(source);
+        }
+    }
+    catch {
+        throw new Error("route request input is not readable");
+    }
+    return loadYamlMapping(decodeRouteInput(bytes));
+}
+function invalidRouteInput(io, body) {
+    return emitInvalidInput({ out: io.out, err: io.err }, { format: "json", body });
+}
+function parse(argv) {
+    let input;
+    let format = "json";
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const [name, inline] = argument.split("=", 2);
+        if (name === "--input" || name === "--format") {
+            const value = inline ?? argv[++index];
+            if (!value || value.startsWith("--"))
+                return { class: "missing_argument", message: `${name} requires a value`, syntax: `${name} VALUE` };
+            if (name === "--input") {
+                if (input)
+                    return { class: "mutually_exclusive", message: "--input may only be supplied once" };
+                input = value;
+            }
+            else if (value !== "json") {
+                return { class: "invalid_choice", message: `argument --format: invalid choice: '${value}' (choose from 'json')`, valid_values: ["json"] };
+            }
+            continue;
+        }
+        return { class: "unrecognized_argument", message: "unrecognized route argument; request text must be supplied through --input" };
+    }
+    if (!input)
+        return { class: "missing_argument", message: "--input is required so request text is not placed in argv", syntax: "--input PATH", example: preCutoverCommand("route request --input - --format json") };
+    return { input, format };
+}
+export function runRouteRequest(argv, io) {
+    const parsed = parse(argv);
+    if ("class" in parsed)
+        return invalidRouteInput(io, parsed);
+    let input;
+    try {
+        input = loadRouteInput(parsed.input, io.stdin ?? readStdin);
+    }
+    catch {
+        return invalidRouteInput(io, { class: "invalid_format", message: "route request input must be a readable YAML or JSON mapping", syntax: "--input PATH" });
+    }
+    if (Object.keys(input).some((key) => key !== "version" && key !== "request")) {
+        return invalidRouteInput(io, { class: "schema_violation", message: "route request input contains unsupported fields" });
+    }
+    if (input.version !== undefined && input.version !== "agentera.route_request.v1") {
+        return invalidRouteInput(io, { class: "schema_violation", message: "route request version must be agentera.route_request.v1" });
+    }
+    if (typeof input.request !== "string") {
+        return invalidRouteInput(io, { class: "invalid_request", message: "route request input requires a string request field" });
+    }
+    try {
+        emitStructured(resolveRouteRequest(input.request), parsed.format, io.out ?? ((text) => process.stdout.write(text)));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof HybridRouteRegistryError) {
+            return invalidRouteInput(io, { class: "conflict", message: "routing authority validation failed before routing" });
+        }
+        return invalidRouteInput(io, { class: "invalid_request", message: "route request could not be resolved" });
+    }
+}
+export function runRouteReceipt(argv, io) {
+    const parsed = parse(argv);
+    if ("class" in parsed)
+        return invalidRouteInput(io, parsed);
+    let input;
+    try {
+        input = loadRouteInput(parsed.input, io.stdin ?? readStdin);
+        emitStructured(validateRouteReceiptSubmission(input), parsed.format, io.out ?? ((text) => process.stdout.write(text)));
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof RouteReceiptValidationError
+            ? `invalid route receipt at ${error.field}: ${error.message}`
+            : "route receipt input must be a readable UTF-8 YAML or JSON mapping";
+        return emitInvalidInput({ out: io.out, err: io.err }, {
+            format: "json",
+            body: {
+                class: "invalid_receipt",
+                message,
+                recovery: "Submit the original request and a complete nullable host receipt through --input; no capability was started.",
+            },
+            exitCode: 64,
+        });
+    }
+}
+/** Run the contract-owned frozen synthetic corpus without invoking a semantic host. */
+export function runRouteEvaluation(argv, io) {
+    if (argv.length !== 2 || argv[0] !== "--format" || argv[1] !== "json") {
+        return invalidRouteInput(io, {
+            class: "unrecognized_argument",
+            message: "route evaluation accepts only --format json and never accepts request text or corpus overrides",
+            syntax: preCutoverCommand("route evaluate --format json"),
+        });
+    }
+    try {
+        const report = evaluateHybridRoute();
+        emitStructured(report, "json", io.out ?? ((text) => process.stdout.write(text)));
+        return routeEvaluationExitCode(report);
+    }
+    catch {
+        return invalidRouteInput(io, {
+            class: "conflict",
+            message: "routing evaluation authority validation failed before evaluation",
+            recovery: "Restore the contract-owned corpus and authorities, then retry; no request was sent or persisted.",
+        });
+    }
+}
+function readStdin() {
+    return process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
+}