agentera 3.0.0-dev.7 → 3.0.0-dev.74

package/dist/cli/dispatch/lifecycle.js

@@ -1,4 +1,3 @@
-import fsForHooks from "node:fs";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,29 +7,34 @@ import { cmdUpgrade } from "../commands/upgrade.js";
 import { cmdVerify } from "../commands/verify.js";
 import { cmdGate } from "../commands/compact.js";
 import { cmdReport } from "../commands/report.js";
-import { runSessionStart } from "../../hooks/sessionStart.js";
-import { runSessionStop } from "../../hooks/sessionStop.js";
-import { runCursorSessionStart } from "../../hooks/cursorSessionStart.js";
-import { runCursorPreToolUse } from "../../hooks/cursorPreToolUse.js";
-import { HookCliAdapter } from "../../hooks/validateArtifact/index.js";
+import { runGlossaryAdviceCommand } from "../commands/glossaryAdvice.js";
+import { runPersonalGlossaryPublishCommand } from "../commands/personalGlossaryPublish.js";
+import { runPersonalGlossaryCandidateReadsCommand } from "../commands/personalGlossaryCandidateReads.js";
+import { runPersonalGlossaryDecisionCommand } from "../commands/personalGlossaryDecision.js";
+import { runPersonalGlossaryReviewRecordsCommand } from "../commands/personalGlossaryReviewRecords.js";
+import { runProfileGroundingCommand } from "../commands/profileGrounding.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 import { usageMain } from "../../analytics/usageStats.js";
 import { validatePathValue } from "../argvalidate.js";
 import { printAppHomeHelp, printDoctorHelp, printUpgradeHelp, wantsHelp } from "../help.js";
 import { makeArgvValueReader } from "./argvParser.js";
 import { parseCompactArgs } from "./check.js";
-import { asEnvelopeFormat, classifyParseError, emitDeprecationAlias } from "./shared.js";
+import { asEnvelopeFormat, classifyParseError, detectTopLevelFormat, emitDeprecationAlias } from "./shared.js";
 import { emitInvalidInput } from "../errors.js";
-function rejectUnsupportedUpgradeFlag(io, format, message) {
+import { migrationProject } from "../migrationRequired.js";
+import { fullEntityUpgradeCommand } from "../../upgrade/upgradeCommands.js";
+import { nativeResourceCleanupIds, resolveNativeResourceCleanupId } from "../../runtime/nativeResourceCleanup.js";
+function rejectUnsupportedUpgradeFlag(io, format, message, recovery) {
     return emitInvalidInput(io, {
         format: asEnvelopeFormat(format),
-        body: { class: "unsupported_target", message },
+        body: { class: "unsupported_target", message, recovery },
     });
 }
 export function runGate(argv, io, prog) {
     const parsed = parseCompactArgs(argv);
     if ("error" in parsed) {
         return emitInvalidInput(io, {
-            format: "text",
+            format: detectTopLevelFormat(argv),
             body: classifyParseError(parsed.error),
         });
     }
@@ -109,6 +113,7 @@ export function runDoctor(argv, io, prog) {
         project: null,
         expectedVersion: null,
         expectCommand: [],
+        retiredResource: null,
         smoke: false,
         allowLiveModel: false,
         format: "text",
@@ -131,6 +136,8 @@ export function runDoctor(argv, io, prog) {
             args.expectedVersion = v;
         else if ((v = value("--expect-command")) !== null)
             args.expectCommand.push(v);
+        else if ((v = value("--retired-resource")) !== null)
+            args.retiredResource = v;
         else if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json") {
                 return emitInvalidInput(io, {
@@ -171,50 +178,6 @@ export function runDoctor(argv, io, prog) {
         });
     }
 }
-export function readStdin() {
-    try {
-        return fsForHooks.readFileSync(0, "utf8");
-    }
-    catch {
-        return "";
-    }
-}
-export function runHook(name, argv, io) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
-    const raw = io.stdin ? io.stdin() : readStdin();
-    // Each hook owns its own stdout newline convention; do not wrap stdout here.
-    switch (name) {
-        case "session-start":
-            return runSessionStart(raw);
-        case "session-stop":
-            return runSessionStop(raw);
-        case "cursor-session-start":
-            return runCursorSessionStart(raw);
-        case "cursor-pre-tool-use":
-            return runCursorPreToolUse(raw);
-        case "validate-artifact": {
-            const [rc, violations] = new HookCliAdapter().run(raw, null);
-            for (const v of violations)
-                err(`${v}\n`);
-            return rc;
-        }
-        default:
-            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",
-                    ],
-                },
-            });
-    }
-}
 export function runUsage(argv, io, prog) {
     const realOut = io.out ?? ((t) => process.stdout.write(t));
     const realErr = io.err ?? ((t) => process.stderr.write(t));
@@ -296,6 +259,9 @@ export function runUpgrade(argv, io, prog) {
         dryRun: false,
         only: [],
         force: false,
+        verify: false,
+        runtime: null,
+        legacyCleanup: null,
         format: "text",
     };
     let jsonFlag = false;
@@ -317,10 +283,33 @@ export function runUpgrade(argv, io, prog) {
         else if ((v = value("--channel")) !== null)
             args.channel = v;
         else if ((v = value("--target-major")) !== null) {
-            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", "--target-major was removed; use --channel with dry-run preview then --yes");
+            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", "--target-major was removed; use --channel with dry-run preview then --yes", fullEntityUpgradeCommand(migrationProject(argv)));
         }
         else if ((v = value("--runtime")) !== null) {
-            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", "--runtime is not yet supported by the TypeScript upgrade command; use --only runtime for migration phases");
+            return emitInvalidInput(io, {
+                format: detectTopLevelFormat(argv),
+                body: {
+                    class: "invalid_choice",
+                    message: `argument --runtime ${v} is retired; Agentera now uses the shared skill at ` +
+                        "~/.agents/skills/agentera plus the CLI. Remove --runtime and rerun the app/project upgrade. " +
+                        "For explicit Agentera-owned native resource cleanup, use --legacy-cleanup RESOURCE_ID.",
+                },
+            });
+        }
+        else if ((v = value("--legacy-cleanup")) !== null) {
+            const validValues = nativeResourceCleanupIds();
+            const selectedResource = resolveNativeResourceCleanupId(v);
+            if (!selectedResource) {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --legacy-cleanup: invalid choice: '${v}' (choose from ${validValues.map((id) => `'${id}'`).join(", ")})`,
+                        valid_values: validValues,
+                    },
+                });
+            }
+            args.legacyCleanup = selectedResource.id;
         }
         else if ((v = value("--only")) !== null) {
             if (v !== "artifacts" && v !== "runtime" && v !== "cleanup") {
@@ -344,8 +333,13 @@ export function runUpgrade(argv, io, prog) {
             args.dryRun = true;
         else if (a === "--force")
             args.force = true;
+        else if (a === "--verify")
+            args.verify = true;
         else if (a === "--update-packages") {
-            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", "--update-packages is not yet supported by the TypeScript upgrade command; external package refresh is deferred for the 3.x channel model");
+            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", "--update-packages is retired; Agentera does not manage host package installation or updates");
+        }
+        else if (["--restore", "--rollback", "--downgrade"].includes(a)) {
+            return rejectUnsupportedUpgradeFlag(io, args.format ?? "text", `${a} was removed; v2-to-v3 upgrade is one-way and apply must run as one full upgrade --yes`, fullEntityUpgradeCommand(migrationProject(argv)));
         }
         else if (a === "--json")
             jsonFlag = true;
@@ -429,7 +423,7 @@ export function runVerify(argv, io, prog) {
             args.dryRun = true;
         else if (a.startsWith("--")) {
             return emitInvalidInput(io, {
-                format: asEnvelopeFormat(args.format),
+                format: detectTopLevelFormat(argv),
                 body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
             });
         }
@@ -451,13 +445,99 @@ export function runVerify(argv, io, prog) {
     }
 }
 export function runReport(argv, io, prog) {
+    if (argv[0] === "personal-glossary-decision") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "personal-glossary-decision has no stats alias",
+                    valid_values: ["report personal-glossary-decision"],
+                    recovery: `Run ${preCutoverCommand("report personal-glossary-decision --input - --format json")}; no bytes were changed.`,
+                },
+            });
+        }
+        return runPersonalGlossaryDecisionCommand(argv.slice(1), io);
+    }
+    if (argv[0] === "personal-glossary-candidates") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "personal-glossary-candidates has no stats alias",
+                    valid_values: ["report personal-glossary-candidates"],
+                    recovery: `Run ${preCutoverCommand("report personal-glossary-candidates list --limit 20 --format json")}; no projection bytes were changed.`,
+                },
+            });
+        }
+        return runPersonalGlossaryCandidateReadsCommand(argv.slice(1), io);
+    }
+    if (argv[0] === "personal-glossary-reviews") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "personal-glossary-reviews has no stats alias",
+                    valid_values: ["report personal-glossary-reviews"],
+                    recovery: `Run ${preCutoverCommand("report personal-glossary-reviews list --limit 20 --format json")}; no review metadata was changed.`,
+                },
+            });
+        }
+        return runPersonalGlossaryReviewRecordsCommand(argv.slice(1), io);
+    }
+    if (argv[0] === "glossary-advice") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "glossary-advice has no stats alias",
+                    valid_values: ["report glossary-advice"],
+                    recovery: `Run ${preCutoverCommand("report glossary-advice --input - --format json")}; no state was changed.`,
+                },
+            });
+        }
+        return runGlossaryAdviceCommand(argv.slice(1), io);
+    }
+    if (argv[0] === "profile-grounding") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "profile-grounding has no stats alias",
+                    valid_values: ["report profile-grounding"],
+                    recovery: `Run ${preCutoverCommand("report profile-grounding --format json")}; no profile bytes were changed.`,
+                },
+            });
+        }
+        return runProfileGroundingCommand(argv.slice(1), io);
+    }
+    if (argv[0] === "personal-glossary-publish") {
+        if (prog !== "agentera report") {
+            return emitInvalidInput(io, {
+                format: "json",
+                body: {
+                    class: "unsupported_target",
+                    message: "personal-glossary-publish has no stats alias",
+                    valid_values: ["report personal-glossary-publish"],
+                    recovery: `Run ${preCutoverCommand("report personal-glossary-publish --input - --format json")}; no profile bytes were changed.`,
+                },
+            });
+        }
+        return runPersonalGlossaryPublishCommand(argv.slice(1), io);
+    }
     const args = {
         action: null,
         format: "text",
         project: null,
+        sources: "active",
         dryRun: false,
         consent: null,
         projectRoot: [],
+        importSources: [],
     };
     const positionals = [];
     let i = 0;
@@ -471,6 +551,15 @@ export function runReport(argv, io, prog) {
             args.format = v;
         else if ((v = value("--project")) !== null)
             args.project = v;
+        else if ((v = value("--sources")) !== null) {
+            if (v !== "active" && v !== "all") {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: { class: "invalid_choice", message: `argument --sources: invalid choice: '${v}' (choose from 'active', 'all')`, valid_values: ["active", "all"] },
+                });
+            }
+            args.sources = v;
+        }
         else if ((v = value("--consent")) !== null) {
             if (v !== "local-history") {
                 return emitInvalidInput(io, {
@@ -492,6 +581,20 @@ export function runReport(argv, io, prog) {
             args.codexSessionsDir = v;
         else if ((v = value("--claude-projects-dir")) !== null)
             args.claudeProjectsDir = v;
+        else if ((v = value("--import-source")) !== null) {
+            if (v !== "claude") {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: {
+                        class: "invalid_choice",
+                        message: `argument --import-source: invalid choice: '${v}' (choose from 'claude')`,
+                        valid_values: ["claude"],
+                    },
+                });
+            }
+            if (!args.importSources.includes(v))
+                args.importSources.push(v);
+        }
         else if ((v = value("--opencode-conversations-dir")) !== null)
             args.opencodeConversationsDir = v;
         else if ((v = value("--copilot-conversations-dir")) !== null)
@@ -502,8 +605,6 @@ export function runReport(argv, io, prog) {
             args.cursorChatsDir = v;
         else if (a === "--no-codex")
             args.noCodex = true;
-        else if (a === "--no-claude")
-            args.noClaude = true;
         else if (a === "--no-opencode")
             args.noOpencode = true;
         else if (a === "--no-copilot")
@@ -518,7 +619,7 @@ export function runReport(argv, io, prog) {
             args.dryRun = true;
         else if (a.startsWith("--")) {
             return emitInvalidInput(io, {
-                format: asEnvelopeFormat(args.format),
+                format: detectTopLevelFormat(argv),
                 body: { class: "unrecognized_argument", message: `unrecognized arguments: ${a}` },
             });
         }
@@ -594,4 +695,3 @@ export function runVersion(argv, io) {
     }
     return 0;
 }
-//# sourceMappingURL=lifecycle.js.map

package/dist/cli/dispatch/prime.js

@@ -3,6 +3,17 @@ import { cmdCapability } from "../commands/capability.js";
 import { makeArgvValueReader } from "./argvParser.js";
 import { asEnvelopeFormat } from "./shared.js";
 import { emitInvalidInput } from "../errors.js";
+import { StateRetrievalFailure } from "../../state/directRetrieval.js";
+import { emitStructured } from "../structured.js";
+function emitStateFailure(error, format, io) {
+    const output = io.out ?? ((text) => process.stdout.write(text));
+    const diagnostic = io.err ?? ((text) => process.stderr.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, output);
+    else
+        diagnostic(`Error: ${error.body.error.message}\nRecovery: ${error.body.error.recovery}\n`);
+    return error.exitCode;
+}
 export function runCapability(command, argv, io, prog) {
     let format = "text";
     let i = 0;
@@ -45,6 +56,8 @@ export function runCapability(command, argv, io, prog) {
         return cmdCapability(command, { format }, io);
     }
     catch (exc) {
+        if (exc instanceof StateRetrievalFailure)
+            return emitStateFailure(exc, format, io);
         return emitInvalidInput(io, {
             format: asEnvelopeFormat(format),
             body: { class: "unsupported_target", message: exc.message },
@@ -52,7 +65,7 @@ export function runCapability(command, argv, io, prog) {
     }
 }
 export function runPrime(command, argv, io, prog) {
-    const args = { command, guidance: false, context: null, dashboard: false, orientation: false, format: "text" };
+    const args = { command, guidance: false, context: null, dashboard: false, orientation: false, format: "text", input: null };
     let i = 0;
     const value = makeArgvValueReader(argv, () => i, (n) => {
         i = n;
@@ -68,6 +81,27 @@ export function runPrime(command, argv, io, prog) {
             args.orientation = true;
         else if ((v = value("--context")) !== null)
             args.context = v;
+        else if (a === "--input" && (!argv[i + 1] || argv[i + 1].startsWith("--"))) {
+            return emitInvalidInput(io, {
+                format: asEnvelopeFormat(args.format),
+                body: { class: "missing_argument", message: "--input requires a file path or -", syntax: "--input <file|->" },
+            });
+        }
+        else if ((v = value("--input")) !== null) {
+            if (v.length === 0) {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: { class: "missing_argument", message: "--input requires a file path or -", syntax: "--input <file|->" },
+                });
+            }
+            if (args.input !== null) {
+                return emitInvalidInput(io, {
+                    format: asEnvelopeFormat(args.format),
+                    body: { class: "mutually_exclusive", message: "--input may only be supplied once" },
+                });
+            }
+            args.input = v;
+        }
         else if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json" && v !== "yaml") {
                 return emitInvalidInput(io, {
@@ -95,10 +129,11 @@ export function runPrime(command, argv, io, prog) {
         return cmdPrime(args, io);
     }
     catch (exc) {
+        if (exc instanceof StateRetrievalFailure)
+            return emitStateFailure(exc, args.format, io);
         return emitInvalidInput(io, {
             format: asEnvelopeFormat(args.format),
             body: { class: "unsupported_target", message: exc.message },
         });
     }
 }
-//# sourceMappingURL=prime.js.map

package/dist/cli/dispatch/projections.js

@@ -0,0 +1,17 @@
+/**
+ * Independent production projections of the accepted top-level command set.
+ * They intentionally do not import the dispatcher inventory: activation must
+ * detect drift in diagnostics, packaged schema, or public instructions.
+ */
+export const DIAGNOSTIC_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const SCHEMA_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const HELP_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);

package/dist/cli/dispatch/shared.js

@@ -37,7 +37,7 @@ export function classifyParseError(raw) {
 }
 /** Coerce the loose `string` format field on parsed args to the literal union. */
 export function asEnvelopeFormat(format) {
-    return format === "json" ? "json" : "text";
+    return format === "json" || format === "yaml" ? format : "text";
 }
 /**
  * Scan a top-level argv slice for `--format json` (or `--format=json`) so
@@ -61,4 +61,3 @@ export function detectTopLevelFormat(args) {
     }
     return "text";
 }
-//# sourceMappingURL=shared.js.map

package/dist/cli/dispatch/state.js

@@ -1,75 +1,72 @@
-import { cmdState } from "../commands/state/index.js";
-import { COMMAND_FILTERS } from "../stateQuery.js";
 import { cmdQuery } from "../commands/query.js";
 import { makeArgvValueReader } from "./argvParser.js";
-import { asEnvelopeFormat, classifyParseError } from "./shared.js";
+import { asEnvelopeFormat, classifyParseError, detectTopLevelFormat } from "./shared.js";
 import { emitInvalidInput } from "../errors.js";
-export function parseStateArgs(command, argv) {
-    const args = {
-        command,
-        topic: null,
-        status: null,
-        dimension: null,
-        severity: null,
-        limit: 5,
-        format: "text",
-        fields: null,
+import { runStateWrite } from "../commands/state/write.js";
+import { runStateGet } from "../commands/state/get.js";
+import { runStateList } from "../commands/state/list.js";
+import { runPlanTasks } from "../commands/state/planTasks.js";
+import { runPlans } from "../commands/state/plans.js";
+import { runExperimentRecords } from "../commands/state/experimentRecords.js";
+import { runtimeEntityFamilyForStateCommand } from "../../state/entityListRuntimeRegistry.js";
+import { entityListFamily, entityListValidValues } from "../../state/entityRetrievalHelp.js";
+import { emitStructured } from "../structured.js";
+import { verbsForArtifact } from "../../state/write/operations.js";
+function canonicalReadCorrection(familyKey, argv, io) {
+    const family = entityListFamily(familyKey);
+    const recoveryCommand = family.bareRecovery ?? family.example;
+    const format = argv.some((token, index) => token === "--format=yaml" || (token === "--format" && argv[index + 1] === "yaml"))
+        ? "yaml"
+        : detectTopLevelFormat(argv);
+    const body = {
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message: `bare state ${family.commandTokens.join(" ")} is not a canonical record-family read`,
+            syntax: `${family.syntax} | ${family.get}`,
+            valid_values: ["list", "get", ...entityListValidValues(family)],
+            example: recoveryCommand,
+            recovery: `Run \`${recoveryCommand}\`; no state was changed.`,
+            artifact: family.key,
+        },
     };
-    const allowed = new Set([...(COMMAND_FILTERS[command] ?? []), "format", "fields"]);
-    let i = 0;
-    const value = makeArgvValueReader(argv, () => i, (n) => {
-        i = n;
-    });
-    for (; i < argv.length; i++) {
-        const a = argv[i];
-        const named = (flag, key) => allowed.has(key) && (a === flag || a.startsWith(flag + "="));
-        let v;
-        if (named("--topic", "topic"))
-            args.topic = value("--topic");
-        else if (named("--status", "status"))
-            args.status = value("--status");
-        else if (named("--dimension", "dimension"))
-            args.dimension = value("--dimension");
-        else if (named("--severity", "severity"))
-            args.severity = value("--severity");
-        else if (named("--limit", "limit")) {
-            v = value("--limit");
-            const n = Number(v);
-            if (!Number.isInteger(n))
-                return { error: `argument --limit: invalid int value: '${v}'` };
-            args.limit = n;
-        }
-        else if (a === "--format" || a.startsWith("--format=")) {
-            v = value("--format");
-            if (v !== "text" && v !== "json" && v !== "yaml") {
-                return { error: `argument --format: invalid choice: '${v}' (choose from 'text', 'json', 'yaml')` };
-            }
-            args.format = v;
-        }
-        else if (a === "--fields" || a.startsWith("--fields="))
-            args.fields = value("--fields");
-        else
-            return { error: `unrecognized arguments: ${a}` };
-    }
-    return args;
+    if (format === "json" || format === "yaml")
+        emitStructured(body, format, io.out ?? ((text) => process.stdout.write(text)));
+    else
+        (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${body.error.message}\nSyntax: ${body.error.syntax}\nExample: ${body.error.example}\nRecovery: ${body.error.recovery}\n`);
+    return 2;
 }
 export function runState(command, argv, io, prog) {
-    const parsed = parseStateArgs(command, argv);
-    if ("error" in parsed) {
-        return emitInvalidInput(io, {
-            format: "text",
-            body: classifyParseError(parsed.error),
-        });
-    }
-    try {
-        return cmdState(parsed, io);
+    const runtime = runtimeEntityFamilyForStateCommand(command, argv);
+    if (runtime) {
+        const offset = runtime.commandTokens.length - 1;
+        const familyArgv = argv.slice(offset);
+        const verb = familyArgv[0];
+        if (verb === "list" || verb === "get") {
+            if (runtime.parser === "generic")
+                return verb === "list" ? runStateList(command, familyArgv.slice(1), io) : runStateGet(command, familyArgv.slice(1), io);
+            if (runtime.parser === "plans")
+                return runPlans(familyArgv, io);
+            if (runtime.parser === "plan_tasks")
+                return runPlanTasks(familyArgv, io);
+            return runExperimentRecords(familyArgv, io);
+        }
+        const family = entityListFamily(runtime.key);
+        const writeVerb = verb !== undefined && verbsForArtifact(command).some((candidate) => candidate === verb);
+        if (writeVerb && runtime.commandTokens.length === 1)
+            return runStateWrite(command, argv, io);
+        if (family.bareRead === "alias")
+            return runStateList(command, familyArgv, io);
+        return canonicalReadCorrection(family.key, familyArgv, io);
     }
-    catch (exc) {
-        return emitInvalidInput(io, {
-            format: asEnvelopeFormat(parsed.format),
-            body: { class: "unsupported_target", message: exc.message },
-        });
+    if (argv[0] && verbsForArtifact(command).some((candidate) => candidate === argv[0])) {
+        return runStateWrite(command, argv, io);
     }
+    return emitInvalidInput(io, {
+        format: detectTopLevelFormat(argv),
+        body: { class: "unsupported_target", message: `unsupported state artifact or operation '${command} ${argv[0] ?? ""}'`.trim() },
+    });
 }
 export function parseQueryArgs(argv) {
     const args = {
@@ -127,7 +124,7 @@ export function runQuery(argv, io, prog) {
     const parsed = parseQueryArgs(argv);
     if ("error" in parsed) {
         return emitInvalidInput(io, {
-            format: "text",
+            format: detectTopLevelFormat(argv),
             body: classifyParseError(parsed.error),
         });
     }
@@ -141,4 +138,3 @@ export function runQuery(argv, io, prog) {
         });
     }
 }
-//# sourceMappingURL=state.js.map

package/dist/cli/dispatch.js

@@ -1,2 +1 @@
 export { main } from "./dispatch/index.js";
-//# sourceMappingURL=dispatch.js.map

package/dist/cli/errors.js

@@ -1,15 +1,6 @@
-/**
- * Canonical invalid-input error envelope for all CLI surfaces.
- *
- * Two output modes:
- *   - json: writes the canonical envelope to stdout, returns rc 2.
- *   - text: writes the four-question guidance template to stderr, returns rc 2.
- *
- * Exit code 2 is reserved for invalid input (per existing CLI convention).
- * Engine failures (rc 1) and pass (rc 0) are handled by the command functions
- * themselves; this helper is for parse-time and run-time input rejection only.
- */
+import YAML from "yaml";
 export const INVALID_INPUT_EXIT_CODE = 2;
+const DEFAULT_RECOVERY = "Correct the input and retry; no state was changed.";
 const TEXT_GUIDANCE_LINES = [
     "What happened: {message}",
     "What the preview did: nothing; only the input was rejected.",
@@ -19,13 +10,20 @@ const TEXT_GUIDANCE_LINES = [
 export function emitInvalidInput(io, opts) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const err = io.err ?? ((t) => process.stderr.write(t));
-    if (opts.format === "json") {
+    if (opts.format === "json" || opts.format === "yaml") {
         const envelope = {
+            schemaVersion: "agentera.invalidInputEnvelope.v2",
             status: "fail",
-            error: opts.body,
+            error: {
+                ...opts.body,
+                recovery: opts.body.recovery ?? DEFAULT_RECOVERY,
+            },
         };
-        out(JSON.stringify(envelope) + "\n");
-        return INVALID_INPUT_EXIT_CODE;
+        if (opts.format === "json")
+            out(JSON.stringify(envelope) + "\n");
+        else
+            out(YAML.stringify(envelope));
+        return opts.exitCode ?? INVALID_INPUT_EXIT_CODE;
     }
     const lines = [];
     for (const tmpl of TEXT_GUIDANCE_LINES) {
@@ -47,7 +45,8 @@ export function emitInvalidInput(io, opts) {
         lines.push("Example:");
         lines.push(`  ${opts.body.example}`);
     }
+    lines.push("");
+    lines.push(`Recovery: ${opts.body.recovery ?? DEFAULT_RECOVERY}`);
     err(lines.join("\n") + "\n");
-    return INVALID_INPUT_EXIT_CODE;
+    return opts.exitCode ?? INVALID_INPUT_EXIT_CODE;
 }
-//# sourceMappingURL=errors.js.map