agentera 3.0.0-dev.3 → 3.0.0-dev.5

package/dist/cli/dispatch.js

@@ -1,6 +1,5 @@
 import { cmdPrime } from "./commands/prime.js";
 import { cmdLint } from "./commands/lint.js";
-import { cmdBackfill } from "./commands/backfill.js";
 import { cmdState, isPortedStateCommand } from "./commands/state.js";
 import { COMMAND_FILTERS } from "./stateQuery.js";
 import { cmdQuery } from "./commands/query.js";
@@ -18,11 +17,73 @@ import { HookCliAdapter } from "../hooks/validateArtifact.js";
 import fsForHooks from "node:fs";
 import { usageMain } from "../analytics/usageStats.js";
 import { validatePathValue } from "./argvalidate.js";
+import { emitInvalidInput, } from "./errors.js";
 import { cmdCapability, CAPABILITY_ROUTING_NAMES } from "./commands/capability.js";
+import { printCommandHelp, printDoctorHelp, printTopLevelHelp, printUpgradeHelp, splitHelpArgs, wantsHelp, } from "./help.js";
 import { cmdValidate, cmdValidateCapability, cmdValidateCapabilityContract, cmdValidateArtifact, cmdValidateDescriptors, isDelegatedValidateFamily, } from "./commands/validate.js";
 function emitDeprecationAlias(legacy, canonical, err) {
     err(`Deprecation: agentera ${legacy} is deprecated; use agentera ${canonical}\n`);
 }
+/**
+ * Map a legacy parse-error string (the kind returned by `parse*Args`) to the
+ * canonical invalid-input envelope body. Lets the parse functions keep their
+ * simple `{ error: string }` shape while every surface's error path still
+ * funnels through `emitInvalidInput` for the frozen envelope contract.
+ */
+function classifyParseError(raw) {
+    const required = /^the following arguments are required: (.+)$/.exec(raw);
+    if (required) {
+        return { class: "missing_argument", message: raw };
+    }
+    const unrecognized = /^unrecognized arguments: (.+)$/.exec(raw);
+    if (unrecognized) {
+        return { class: "unrecognized_argument", message: raw };
+    }
+    const choice = /^argument (--[\w-]+): invalid choice: '([^']+)' \(choose from (.+)\)$/.exec(raw);
+    if (choice) {
+        const validValues = [...choice[3].matchAll(/'([^']+)'/g)].map((m) => m[1]);
+        return {
+            class: "invalid_choice",
+            message: raw,
+            valid_values: validValues,
+        };
+    }
+    const intBad = /^argument (--[\w-]+): invalid int value: '([^']+)'$/.exec(raw);
+    if (intBad) {
+        return { class: "invalid_int", message: raw };
+    }
+    const mutex = /^argument (--[\w-]+): not allowed with argument (--[\w-]+)$/.exec(raw);
+    if (mutex) {
+        return { class: "mutually_exclusive", message: raw };
+    }
+    return { class: "unrecognized_argument", message: raw };
+}
+/** Coerce the loose `string` format field on parsed args to the literal union. */
+function asEnvelopeFormat(format) {
+    return format === "json" ? "json" : "text";
+}
+/**
+ * Scan a top-level argv slice for `--format json` (or `--format=json`) so
+ * main() can decide whether to route its error envelope to stdout or stderr.
+ * Unknown format values fall through to "text" — the user will discover the
+ * mis-spelling when the underlying command runs.
+ */
+function detectTopLevelFormat(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--format") {
+            const v = args[++i];
+            if (v === "json" || v === "text" || v === "yaml")
+                return v === "json" ? "json" : "text";
+        }
+        else if (a.startsWith("--format=")) {
+            const v = a.slice("--format=".length);
+            if (v === "json" || v === "text" || v === "yaml")
+                return v === "json" ? "json" : "text";
+        }
+    }
+    return "text";
+}
 /** Minimal flag parser for the `lint` command surface. */
 function parseLintArgs(argv) {
     const args = { artifact: "", file: null, text: null, strict: false, format: "text" };
@@ -68,73 +129,21 @@ function parseLintArgs(argv) {
     return args;
 }
 function runLint(argv, io, prog = "agentera lint") {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const parsed = parseLintArgs(argv);
     if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: "text",
+            body: classifyParseError(parsed.error),
+        });
     }
     try {
         return cmdLint(parsed, io);
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
-    }
-}
-function parseBackfillArgs(argv) {
-    const args = { project: null, mode: "check", commit: null, cycle: null, format: "text" };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        const value = (name) => {
-            if (a === name)
-                return argv[++i];
-            if (a.startsWith(name + "="))
-                return a.slice(name.length + 1);
-            return null;
-        };
-        let v;
-        if ((v = value("--project")) !== null)
-            args.project = v;
-        else if ((v = value("--mode")) !== null) {
-            if (v !== "check" && v !== "fix") {
-                return { error: `argument --mode: invalid choice: '${v}' (choose from 'check', 'fix')` };
-            }
-            args.mode = v;
-        }
-        else if ((v = value("--commit")) !== null)
-            args.commit = v;
-        else if ((v = value("--cycle")) !== null) {
-            const n = Number(v);
-            if (!Number.isInteger(n))
-                return { error: `argument --cycle: invalid int value: '${v}'` };
-            args.cycle = n;
-        }
-        else if ((v = value("--format")) !== null) {
-            if (v !== "text" && v !== "json") {
-                return { error: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')` };
-            }
-            args.format = v;
-        }
-        else {
-            return { error: `unrecognized arguments: ${a}` };
-        }
-    }
-    return args;
-}
-function runBackfill(argv, io, prog = "agentera backfill") {
-    const err = io.err ?? ((t) => process.stderr.write(t));
-    const parsed = parseBackfillArgs(argv);
-    if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
-    }
-    try {
-        return cmdBackfill(parsed, io);
-    }
-    catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
 }
 function parseStateArgs(command, argv) {
@@ -190,13 +199,22 @@ function parseStateArgs(command, argv) {
     return args;
 }
 function runState(command, argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const parsed = parseStateArgs(command, argv);
     if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: "text",
+            body: classifyParseError(parsed.error),
+        });
+    }
+    try {
+        return cmdState(parsed, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
-    return cmdState(parsed, io);
 }
 function parseQueryArgs(argv) {
     const args = {
@@ -254,22 +272,27 @@ function parseQueryArgs(argv) {
     return args;
 }
 function runQuery(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const parsed = parseQueryArgs(argv);
     if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: "text",
+            body: classifyParseError(parsed.error),
+        });
     }
     try {
         return cmdQuery(parsed, io);
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
 }
 function compactModeOf(argv) {
     for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--apply")
+            return "fix";
         if (argv[i] === "--mode")
             return argv[i + 1] ?? "check";
         if (argv[i].startsWith("--mode="))
@@ -289,7 +312,10 @@ function parseCompactArgs(argv) {
             return null;
         };
         let v;
-        if ((v = value("--project")) !== null)
+        if (a === "--apply") {
+            args.mode = "fix";
+        }
+        else if ((v = value("--project")) !== null)
             args.project = v;
         else if ((v = value("--mode")) !== null) {
             if (v !== "check" && v !== "fix") {
@@ -309,22 +335,24 @@ function parseCompactArgs(argv) {
     return args;
 }
 function runCompact(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const parsed = parseCompactArgs(argv);
     if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: "text",
+            body: classifyParseError(parsed.error),
+        });
     }
     try {
         return cmdCompact(parsed, io);
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
 }
 function runValidate(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     let family = null;
     let capabilityTarget = null;
     let artifactFlag = null;
@@ -336,16 +364,28 @@ function runValidate(argv, io, prog) {
         if (a === "--format") {
             const v = argv[++i];
             if (v !== "text" && v !== "json") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format,
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                        valid_values: ["text", "json"],
+                    },
+                });
             }
             format = v;
         }
         else if (a.startsWith("--format=")) {
             const v = a.slice("--format=".length);
             if (v !== "text" && v !== "json") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format,
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                        valid_values: ["text", "json"],
+                    },
+                });
             }
             format = v;
         }
@@ -359,8 +399,13 @@ function runValidate(argv, io, prog) {
             cwdFlag = a === "--cwd" ? argv[++i] : a.slice("--cwd=".length);
         }
         else if (a.startsWith("--")) {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format,
+                body: {
+                    class: "unrecognized_argument",
+                    message: `unrecognized arguments: ${a}`,
+                },
+            });
         }
         else if (family === null) {
             family = a;
@@ -369,19 +414,45 @@ function runValidate(argv, io, prog) {
             capabilityTarget = a;
         }
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format,
+                body: {
+                    class: "unrecognized_argument",
+                    message: `unrecognized arguments: ${a}`,
+                },
+            });
         }
     }
     if (family === null) {
-        err(`${prog}: error: the following arguments are required: validate_family\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format,
+            body: {
+                class: "missing_argument",
+                message: "the following arguments are required: validate_family",
+                valid_values: [
+                    "cross-capability",
+                    "lifecycle-adapters",
+                    "app-home-contract",
+                    "capability",
+                    "capability-contract",
+                    "descriptors",
+                    "artifact",
+                ],
+                example: "agentera check validate cross-capability",
+            },
+        });
     }
     try {
         if (family === "capability") {
             if (capabilityTarget === null) {
-                err(`${prog} capability: error: the following arguments are required: target\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format,
+                    body: {
+                        class: "missing_argument",
+                        message: "the following arguments are required: target",
+                        example: "agentera check validate capability planera",
+                    },
+                });
             }
             return cmdValidateCapability(capabilityTarget, { format }, io);
         }
@@ -393,24 +464,48 @@ function runValidate(argv, io, prog) {
         }
         if (family === "artifact") {
             if (artifactFlag === null) {
-                err(`${prog} artifact: error: the following arguments are required: --artifact\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format,
+                    body: {
+                        class: "missing_argument",
+                        message: "the following arguments are required: --artifact",
+                        example: "agentera check validate artifact --artifact PLAN.md",
+                    },
+                });
             }
             return cmdValidateArtifact({ artifact: artifactFlag, file: fileFlag, cwd: cwdFlag, format }, io);
         }
         if (isDelegatedValidateFamily(family)) {
             return cmdValidate(family, { format }, io);
         }
-        err(`agentera: validate family not yet ported: ${family}\n`);
-        return 1;
+        return emitInvalidInput(io, {
+            format,
+            body: {
+                class: "unsupported_target",
+                message: `validate family not yet ported: ${family}`,
+                valid_values: [
+                    "cross-capability",
+                    "lifecycle-adapters",
+                    "app-home-contract",
+                    "capability",
+                    "capability-contract",
+                    "descriptors",
+                    "artifact",
+                ],
+            },
+        });
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format,
+            body: {
+                class: "unsupported_target",
+                message: exc.message,
+            },
+        });
     }
 }
 function runSchema(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     let format = "json";
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -420,12 +515,20 @@ function runSchema(argv, io, prog) {
         else if (a.startsWith("--format="))
             v = a.slice("--format=".length);
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
         if (v !== "json" && v !== "yaml") {
-            err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'json', 'yaml')\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: {
+                    class: "invalid_choice",
+                    message: `argument --format: invalid choice: '${v}' (choose from 'json', 'yaml')`,
+                    valid_values: ["json", "yaml"],
+                },
+            });
         }
         format = v;
     }
@@ -433,12 +536,13 @@ function runSchema(argv, io, prog) {
         return cmdSchema({ format }, io);
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
 }
 function runCapability(command, argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     let format = "text";
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -454,19 +558,34 @@ function runCapability(command, argv, io, prog) {
             continue;
         }
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
         if (v !== "text" && v !== "json" && v !== "yaml") {
-            err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: {
+                    class: "invalid_choice",
+                    message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')`,
+                    valid_values: ["text", "json", "yaml"],
+                },
+            });
         }
         format = v;
     }
-    return cmdCapability(command, { format }, io);
+    try {
+        return cmdCapability(command, { format }, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 function runPrime(command, argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const args = { command, guidance: false, context: null, dashboard: false, orientation: false, format: "text" };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -484,8 +603,14 @@ function runPrime(command, argv, io, prog) {
         else if (a === "--format" || a.startsWith("--format=")) {
             v = a === "--format" ? argv[++i] : a.slice("--format=".length);
             if (v !== "text" && v !== "json" && v !== "yaml") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')`,
+                        valid_values: ["text", "json", "yaml"],
+                    },
+                });
             }
             args.format = v;
         }
@@ -496,30 +621,57 @@ function runPrime(command, argv, io, prog) {
             args.fields = a.slice("--fields=".length);
         }
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
     }
-    return cmdPrime(args, io);
+    try {
+        return cmdPrime(args, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 function runGate(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const parsed = parseCompactArgs(argv);
     if ("error" in parsed) {
-        err(`${prog}: error: ${parsed.error}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: "text",
+            body: classifyParseError(parsed.error),
+        });
     }
     try {
         return cmdGate(parsed, io);
     }
     catch (exc) {
-        err(`Error: ${exc.message}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(parsed.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
     }
 }
 function runDoctor(argv, io, prog) {
     const err = io.err ?? ((t) => process.stderr.write(t));
-    const args = { installRoot: null, home: null, project: null, expectedVersion: null, expectCommand: [], format: "text" };
+    const out = io.out ?? ((t) => process.stdout.write(t));
+    if (wantsHelp(argv)) {
+        out(printDoctorHelp() + "\n");
+        return 0;
+    }
+    const args = {
+        installRoot: null,
+        home: null,
+        project: null,
+        expectedVersion: null,
+        expectCommand: [],
+        smoke: false,
+        allowLiveModel: false,
+        format: "text",
+    };
     let jsonFlag = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -543,23 +695,43 @@ function runDoctor(argv, io, prog) {
             args.expectCommand.push(v);
         else if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                        valid_values: ["text", "json"],
+                    },
+                });
             }
             args.format = v;
         }
         else if (a === "--json")
             jsonFlag = true;
+        else if (a === "--smoke")
+            args.smoke = true;
+        else if (a === "--allow-live-model")
+            args.allowLiveModel = true;
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
     }
     if (jsonFlag) {
         emitDeprecationAlias("doctor --json", "doctor --format json", err);
         args.format = "json";
     }
-    return cmdDoctor(args, io);
+    try {
+        return cmdDoctor(args, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 function readStdin() {
     try {
@@ -589,8 +761,20 @@ function runHook(name, argv, io) {
             return rc;
         }
         default:
-            err(`agentera hook: unknown hook '${name}'\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: "text",
+                body: {
+                    class: "unsupported_target",
+                    message: `unknown hook '${name}'`,
+                    valid_values: [
+                        "session-start",
+                        "session-stop",
+                        "cursor-session-start",
+                        "cursor-pre-tool-use",
+                        "validate-artifact",
+                    ],
+                },
+            });
     }
 }
 function runUsage(argv, io, prog) {
@@ -616,8 +800,10 @@ function runUsage(argv, io, prog) {
         else if ((v = value("--project")) !== null)
             project = v;
         else {
-            realErr(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
     }
     if (corpus !== null) {
@@ -625,16 +811,26 @@ function runUsage(argv, io, prog) {
             validatePathValue(corpus, "path");
         }
         catch (e) {
-            realErr(`${prog}: error: argument --corpus: ${e.message}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(format),
+                body: {
+                    class: "invalid_format",
+                    message: `argument --corpus: ${e.message}`,
+                },
+            });
         }
     }
     if (format !== "text" && format !== "json") {
-        const syntax = "agentera usage [--format text|json] [--corpus PATH] [--project VALUE]";
-        const example = "agentera usage --format json --project agentera";
-        realErr(`Error: unsupported usage format '${format}'; valid formats: text, json. ` +
-            `Syntax: ${syntax}. Example: ${example}\n`);
-        return 2;
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(format),
+            body: {
+                class: "invalid_choice",
+                message: `unsupported usage format '${format}'; valid formats: text, json.`,
+                valid_values: ["text", "json"],
+                syntax: "agentera usage [--format text|json] [--corpus PATH] [--project VALUE]",
+                example: "agentera usage --format json --project agentera",
+            },
+        });
     }
     const engineArgv = [];
     if (corpus !== null)
@@ -650,6 +846,11 @@ function runUsage(argv, io, prog) {
 }
 function runUpgrade(argv, io, prog) {
     const err = io.err ?? ((t) => process.stderr.write(t));
+    const out = io.out ?? ((t) => process.stdout.write(t));
+    if (wantsHelp(argv)) {
+        out(printUpgradeHelp() + "\n");
+        return 0;
+    }
     const args = {
         installRoot: null,
         home: null,
@@ -685,15 +886,26 @@ function runUpgrade(argv, io, prog) {
             args.channel = v;
         else if ((v = value("--target-major")) !== null) {
             void v;
-            err(`${prog}: error: --target-major was removed; use --channel with dry-run preview then --yes\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: {
+                    class: "unsupported_target",
+                    message: "--target-major was removed; use --channel with dry-run preview then --yes",
+                },
+            });
         }
         else if ((v = value("--runtime")) !== null)
             void v; // accepted; orchestrator uses fixture runtimes
         else if ((v = value("--only")) !== null) {
             if (v !== "artifacts" && v !== "runtime" && v !== "cleanup") {
-                err(`${prog}: error: argument --only: invalid choice: '${v}' (choose from 'artifacts', 'runtime', 'cleanup')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --only: invalid choice: '${v}' (choose from 'artifacts', 'runtime', 'cleanup')`,
+                        valid_values: ["artifacts", "runtime", "cleanup"],
+                    },
+                });
             }
             args.only.push(v);
         }
@@ -711,22 +923,37 @@ function runUpgrade(argv, io, prog) {
             jsonFlag = true;
         else if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                        valid_values: ["text", "json"],
+                    },
+                });
             }
             args.format = v;
         }
         else {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
     }
     if (jsonFlag)
         args.format = "json";
-    return cmdUpgrade(args, io);
+    try {
+        return cmdUpgrade(args, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 function runVerify(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const args = {
         family: null,
         target: null,
@@ -752,8 +979,14 @@ function runVerify(argv, io, prog) {
         let v;
         if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json") {
-                err(`${prog}: error: argument --format: invalid choice: '${v}' (choose from 'text', 'json')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                        valid_values: ["text", "json"],
+                    },
+                });
             }
             args.format = v;
         }
@@ -770,8 +1003,10 @@ function runVerify(argv, io, prog) {
         else if (a === "--dry-run")
             args.dryRun = true;
         else if (a.startsWith("--")) {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
         else {
             positionals.push(a);
@@ -780,10 +1015,17 @@ function runVerify(argv, io, prog) {
     args.family = positionals[0] ?? null;
     args.target = positionals[1] ?? null;
     args.fixtures = positionals.slice(2);
-    return cmdVerify(args, io);
+    try {
+        return cmdVerify(args, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 function runReport(argv, io, prog) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
     const args = {
         action: null,
         format: "text",
@@ -809,8 +1051,14 @@ function runReport(argv, io, prog) {
             args.project = v;
         else if ((v = value("--consent")) !== null) {
             if (v !== "local-history") {
-                err(`${prog}: error: argument --consent: invalid choice: '${v}' (choose from 'local-history')\n`);
-                return 2;
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --consent: invalid choice: '${v}' (choose from 'local-history')`,
+                        valid_values: ["local-history"],
+                    },
+                });
             }
             args.consent = v;
         }
@@ -843,21 +1091,50 @@ function runReport(argv, io, prog) {
         else if (a === "--dry-run")
             args.dryRun = true;
         else if (a.startsWith("--")) {
-            err(`${prog}: error: unrecognized arguments: ${a}\n`);
-            return 2;
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
+            });
         }
         else {
             positionals.push(a);
         }
     }
     args.action = positionals[0] ?? null;
-    return cmdReport(args, io);
+    try {
+        return cmdReport(args, io);
+    }
+    catch (exc) {
+        return emitInvalidInput(io, {
+            format: asEnvelopeFormat(args.format),
+            body: { class: "unsupported_target", message: exc.message },
+        });
+    }
 }
 export function main(argv, io = {}) {
     const err = io.err ?? ((t) => process.stderr.write(t));
+    const out = io.out ?? ((t) => process.stdout.write(t));
     const args = argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        out(printTopLevelHelp() + "\n");
+        return 0;
+    }
     const command = args[0];
-    const rest = args.slice(1);
+    const { args: rest, help } = splitHelpArgs(args.slice(1));
+    if (help) {
+        const text = printCommandHelp(command, rest);
+        if (text) {
+            out(text + "\n");
+            return 0;
+        }
+        return emitInvalidInput(io, {
+            format: "text",
+            body: {
+                class: "unsupported_target",
+                message: `unknown or not-yet-ported command: ${command}`,
+            },
+        });
+    }
     switch (command) {
         case "prime":
             return runPrime("prime", rest, io, "agentera prime");
@@ -878,8 +1155,20 @@ export function main(argv, io = {}) {
         case "hook": {
             const name = rest[0];
             if (!name) {
-                err("agentera hook: error: the following arguments are required: hook_name\n");
-                return 2;
+                return emitInvalidInput(io, {
+                    format: "text",
+                    body: {
+                        class: "missing_argument",
+                        message: "the following arguments are required: hook_name",
+                        valid_values: [
+                            "session-start",
+                            "session-stop",
+                            "cursor-session-start",
+                            "cursor-pre-tool-use",
+                            "validate-artifact",
+                        ],
+                    },
+                });
             }
             return runHook(name, rest.slice(1), io);
         }
@@ -897,8 +1186,14 @@ export function main(argv, io = {}) {
         case "check": {
             const sub = rest[0];
             if (!sub) {
-                err("agentera check: error: the following arguments are required: check_command\n");
-                return 2;
+                return emitInvalidInput(io, {
+                    format: "text",
+                    body: {
+                        class: "missing_argument",
+                        message: "the following arguments are required: check_command",
+                        valid_values: ["validate", "verify", "lint", "compact"],
+                    },
+                });
             }
             if (sub === "validate")
                 return runValidate(rest.slice(1), io, "agentera check validate");
@@ -906,8 +1201,6 @@ export function main(argv, io = {}) {
                 return runVerify(rest.slice(1), io, "agentera check verify");
             if (sub === "lint")
                 return runLint(rest.slice(1), io, "agentera check lint");
-            if (sub === "backfill")
-                return runBackfill(rest.slice(1), io, "agentera check backfill");
             if (sub === "compact") {
                 const subArgs = rest.slice(1);
                 const mode = compactModeOf(subArgs);
@@ -915,21 +1208,59 @@ export function main(argv, io = {}) {
                     return runCompact(subArgs, io, "agentera check compact");
                 return runGate(subArgs, io, "agentera check compact");
             }
-            err(`agentera: unknown or not-yet-ported check subcommand: ${sub}\n`);
-            return 1;
+            return emitInvalidInput(io, {
+                format: "text",
+                body: {
+                    class: "unsupported_target",
+                    message: `unknown or not-yet-ported check subcommand: ${sub}`,
+                    valid_values: ["validate", "verify", "lint", "compact"],
+                },
+            });
         }
         case "state": {
             const sub = rest[0];
             if (!sub) {
-                err("agentera state: error: the following arguments are required: state_command\n");
-                return 2;
+                return emitInvalidInput(io, {
+                    format: "text",
+                    body: {
+                        class: "missing_argument",
+                        message: "the following arguments are required: state_command",
+                        valid_values: [
+                            "progress",
+                            "plan",
+                            "health",
+                            "docs",
+                            "objective",
+                            "experiments",
+                            "todo",
+                            "decisions",
+                            "query",
+                        ],
+                    },
+                });
             }
             if (sub === "query")
                 return runQuery(rest.slice(1), io, "agentera state query");
             if (isPortedStateCommand(sub))
                 return runState(sub, rest.slice(1), io, `agentera state ${sub}`);
-            err(`agentera: unknown or not-yet-ported state subcommand: ${sub}\n`);
-            return 1;
+            return emitInvalidInput(io, {
+                format: "text",
+                body: {
+                    class: "unsupported_target",
+                    message: `unknown or not-yet-ported state subcommand: ${sub}`,
+                    valid_values: [
+                        "progress",
+                        "plan",
+                        "health",
+                        "docs",
+                        "objective",
+                        "experiments",
+                        "todo",
+                        "decisions",
+                        "query",
+                    ],
+                },
+            });
         }
         case "query":
             emitDeprecationAlias("query", "state query", err);
@@ -951,8 +1282,13 @@ export function main(argv, io = {}) {
                 emitDeprecationAlias(command, `state ${command}`, err);
                 return runState(command, rest, io, `agentera ${command}`);
             }
-            err(`agentera: unknown or not-yet-ported command: ${command ?? "(none)"}\n`);
-            return 1;
+            return emitInvalidInput(io, {
+                format: "text",
+                body: {
+                    class: "unsupported_target",
+                    message: `unknown or not-yet-ported command: ${command ?? "(none)"}`,
+                },
+            });
     }
 }
 //# sourceMappingURL=dispatch.js.map