agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/cli/commands/appHome.js

@@ -0,0 +1,22 @@
+import os from "node:os";
+import { formatResolvedAppHome } from "../../state/installRoot.js";
+import { expanduser } from "../../core/paths.js";
+export function cmdAppHome(args, io = {}) {
+    const out = io.out ?? ((t) => process.stdout.write(t));
+    const resolvedHome = args.home ? expanduser(args.home) : os.homedir();
+    let env = process.env;
+    if (args.home) {
+        env = { ...process.env, HOME: resolvedHome };
+        delete env.XDG_DATA_HOME;
+        delete env.APPDATA;
+        delete env.AGENTERA_HOME;
+        delete env.AGENTERA_DEFAULT_INSTALL_ROOT;
+    }
+    const output = formatResolvedAppHome(args.installRoot, {
+        env,
+        home: resolvedHome,
+        format: args.format,
+    });
+    out(output + "\n");
+    return 0;
+}

package/dist/cli/commands/capability.js

@@ -1,19 +1,13 @@
-import fs from "node:fs";
-import path from "node:path";
-import { resolveSourceRoot } from "../../core/sourceRoot.js";
 import { emitStructured } from "../structured.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 export const CAPABILITY_ROUTING_NAMES = [
-    "visionera", "resonera", "inspirera", "planera", "realisera",
-    "optimera", "inspektera", "dokumentera", "profilera", "visualisera", "orkestrera",
+    "vision", "discuss", "research", "plan", "build",
+    "optimize", "audit", "document", "profile", "design", "orchestrate",
 ];
-const PRIME_CAPABILITY_CONTEXT_COMMAND = "agentera prime --context {capability} --format json";
+const PRIME_CAPABILITY_CONTEXT_COMMAND = preCutoverCommand("prime --context {capability} --format json");
 export function cmdCapability(capability, args, io) {
     const out = io.out ?? ((t) => process.stdout.write(t));
-    const sourceRoot = resolveSourceRoot();
-    const instructions = path.join(sourceRoot, "skills", "agentera", "capabilities", capability, "instructions.md");
-    const instructionsPath = fs.existsSync(instructions)
-        ? path.relative(sourceRoot, instructions)
-        : `skills/agentera/capabilities/${capability}/instructions.md`;
+    const instructionsPath = `packages/cli/src/capabilities/${capability}/instructions.ts`;
     const startupContext = PRIME_CAPABILITY_CONTEXT_COMMAND.replace("{capability}", capability);
     const payload = {
         command: capability,
@@ -41,4 +35,3 @@ export function cmdCapability(capability, args, io) {
     }
     return 0;
 }
-//# sourceMappingURL=capability.js.map

package/dist/cli/commands/compact.js

@@ -1,6 +1,7 @@
 import { resolvePath } from "../../core/paths.js";
-import { runCompaction } from "../../hooks/compaction.js";
+import { runCompaction } from "../../hooks/compaction/index.js";
 import { emitStructured } from "../structured.js";
+import { boundStructuredProjection } from "../../state/projectionPolicy.js";
 function pyStr(value) {
     if (value === null || value === undefined)
         return "None";
@@ -21,34 +22,49 @@ function compactionOperationPayload(op) {
         archive_count: status.archive_count,
         total_count: status.total_count,
         over_limit_count: status.over_limit_count,
+        ...(status.pending_summarization_count !== undefined
+            ? { pending_summarization_count: status.pending_summarization_count }
+            : {}),
+        ...(status.projection_state ? { projection_state: status.projection_state } : {}),
         protected_overflow_count: status.protected_overflow_count ?? 0,
         mode: op.mode,
         action: op.action,
         changed: op.changed,
         message: op.message,
         reason: status.reason,
+        ...(status.projection_recovery ? { recovery: status.projection_recovery } : {}),
     };
     if (op.result !== null) {
+        const recovery = op.result.recovery;
         payload.result = {
             active_before: op.result.full_before,
             archive_before: op.result.oneline_before,
             active_after: op.result.full_after,
             archive_after: op.result.oneline_after,
             dropped: op.result.dropped,
+            omitted_count: op.result.omitted_count ?? 0,
+            ...(op.result.omission_reason ? { omission_reason: op.result.omission_reason } : {}),
             changed: op.result.changed,
+            ...(recovery ? { recovery } : {}),
         };
     }
     return payload;
 }
 function compactionGuidance(mode, operations) {
     const over = operations.filter((op) => op.action === "over_limit" || op.action === "pending_fix");
+    const projections = operations.filter((op) => op.action === "projection" || op.action === "pending_projection");
+    const formatting = operations.filter((op) => op.action === "formatting" || op.action === "pending_formatting");
     const protectedOps = operations.filter((op) => op.action === "protected_overflow");
     const errors = operations.filter((op) => op.action === "error");
-    const checkCommand = "npx -y agentera compact --mode check --format json";
-    const fixCommand = "npx -y agentera compact --mode fix --format json";
+    const refused = operations.filter((op) => op.action === "refused");
+    const checkCommand = "npx -y agentera check compact --mode check --format json";
+    const fixCommand = "npx -y agentera check compact --mode fix --format json";
     if (errors.length > 0) {
         return `Inspect the reported errors, repair invalid artifacts, then rerun \`${checkCommand}\`.`;
     }
+    if (refused.length > 0) {
+        return "Projection changes were safely refused until each full entry has a verified numbered archive; inspect recovery metadata and retry after recovery.";
+    }
     if (protectedOps.length > 0) {
         const artifacts = protectedOps.map((op) => op.status.artifact).join(", ");
         return (`Protected-overflow review pressure blocks compaction for: ${artifacts}. ` +
@@ -61,23 +77,36 @@ function compactionGuidance(mode, operations) {
     if (mode === "fix" && over.length > 0) {
         return "Some artifacts remain over limit; inspect skipped or unsupported artifacts before manual remediation.";
     }
-    return "No repair needed. Compactable artifacts are within uniform_10_40_50 limits.";
+    if (formatting.length > 0) {
+        const artifacts = formatting.map((op) => op.status.artifact).join(", ");
+        return mode === "check"
+            ? `Summary formatting is pending for: ${artifacts}. Safe fix: \`${fixCommand}\`.`
+            : `Summary formatting remains pending for: ${artifacts}; inspect the artifact diagnostics.`;
+    }
+    if (projections.length > 0) {
+        return "Projection defaults are bounded; numbered archive records remain complete and authoritative.";
+    }
+    return "No repair needed. Compactable artifacts are within the configured projection defaults.";
 }
 function compactionSummary(mode, operations) {
     const counts = {};
     for (const op of operations)
         counts[op.action] = (counts[op.action] ?? 0) + 1;
     const overLimit = operations.filter((op) => op.action === "over_limit" || op.action === "pending_fix").length;
+    const projections = operations.filter((op) => op.action === "projection" || op.action === "pending_projection").length;
+    const formatting = operations.filter((op) => op.action === "formatting" || op.action === "pending_formatting").length;
     const protectedOverflow = operations.filter((op) => op.action === "protected_overflow").length;
     const errors = operations.filter((op) => op.action === "error").length;
     const changed = operations.filter((op) => op.changed).length;
-    const status = errors || protectedOverflow || (mode === "check" && overLimit) ? "fail" : "pass";
+    const status = errors || (mode === "check" && (overLimit || formatting)) ? "fail" : "pass";
     return {
         status,
         mode,
         artifact_count: operations.length,
         over_limit_count: overLimit,
+        formatting_count: formatting,
         protected_overflow_count: protectedOverflow,
+        projection_count: projections,
         error_count: errors,
         changed_count: changed,
         action_counts: counts,
@@ -87,9 +116,8 @@ function compactionSummary(mode, operations) {
 function compactionExitCode(mode, operations) {
     if (operations.some((op) => op.action === "error"))
         return 2;
-    if (operations.some((op) => op.action === "protected_overflow"))
-        return 1;
-    if (mode === "check" && operations.some((op) => op.action === "over_limit"))
+    if (mode === "check" &&
+        operations.some((op) => op.action === "over_limit" || op.action === "formatting"))
         return 1;
     return 0;
 }
@@ -107,13 +135,14 @@ function emitCompactionPayload(payload, mode, format, out) {
     const summary = payload.summary;
     const project = payload.project;
     if (format === "json") {
-        emitStructured(payload, "json", out);
+        emitStructured(boundStructuredProjection(payload, "compact", "json"), "json", out);
         return;
     }
     out(`status=${summary.status} | mode=${mode} | project=${project}\n`);
     out("counts=" +
         `artifacts:${summary.artifact_count} ` +
         `over_limit:${summary.over_limit_count} ` +
+        `formatting:${summary.formatting_count} ` +
         `protected_overflow:${summary.protected_overflow_count} ` +
         `errors:${summary.error_count} ` +
         `changed:${summary.changed_count}\n`);
@@ -122,6 +151,7 @@ function emitCompactionPayload(payload, mode, format, out) {
             `classification=${item.classification} | path=${item.path} | ` +
             `active=${pyStr(item.active_count)} | archive=${pyStr(item.archive_count)} | ` +
             `total=${pyStr(item.total_count)} | over=${pyStr(item.over_limit_count)} | ` +
+            `pending_summarization=${pyStr(item.pending_summarization_count)} | ` +
             `protected_overflow=${item.protected_overflow_count} | ` +
             `message=${item.message}\n`);
     }
@@ -132,7 +162,7 @@ export function cmdCompact(args, io = {}) {
     const mode = args.mode ?? "check";
     const project = resolvePath(args.project ?? process.cwd());
     const operations = runCompaction(project, mode);
-    const payload = compactionPayload("compact", project, mode, operations);
+    const payload = compactionPayload("check compact", project, mode, operations);
     emitCompactionPayload(payload, mode, args.format ?? "text", out);
     return compactionExitCode(mode, operations);
 }
@@ -140,9 +170,7 @@ export function cmdGate(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const project = resolvePath(args.project ?? process.cwd());
     const operations = runCompaction(project, "check");
-    const payload = compactionPayload("gate", project, "check", operations);
-    payload.gate = "compaction";
+    const payload = compactionPayload("check compact", project, "check", operations);
     emitCompactionPayload(payload, "check", args.format ?? "text", out);
     return compactionExitCode("check", operations);
 }
-//# sourceMappingURL=compact.js.map

package/dist/cli/commands/doctor.js

@@ -1,8 +1,15 @@
 import os from "node:os";
 import { expanduser, resolvePath } from "../../core/paths.js";
+import { pyJsonIndentSorted } from "../../core/pyjson.js";
 import { resolveDoctorInstallRoot, resolveSourceRootStrict, } from "../../upgrade/appModel.js";
 import { runNpmSmokeChecks } from "../../setup/smokeChecks.js";
-import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, buildDoctorStatus, EXPECTED_STATE_COMMANDS, publicDoctorStatus, } from "../../upgrade/doctor.js";
+import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, appLifecycleActionNoun, buildDoctorStatus, EXPECTED_STATE_COMMANDS, doctorParityJsonEnvelope, } from "../../upgrade/doctor.js";
+import { classifyInstall } from "../../upgrade/compatibility.js";
+import { prependNextMajorDoctorSection, resolveNextMajorDoctorLines, } from "../../upgrade/nextMajorDoctor.js";
+import { diagnoseCanonicalSkill } from "../../setup/sharedSkill.js";
+import { diagnoseRetiredResources } from "../../upgrade/retiredResourceDiagnostics.js";
+import { commandText } from "../../upgrade/upgradeCommands.js";
+import { inspectTodoReconciliationState } from "../../state/todoReconciliationInspection.js";
 const PLAIN_STATUS = {
     pending: "ready to fix",
     applied: "fixed",
@@ -16,40 +23,40 @@ const PLAIN_STATUS = {
     [APP_MIGRATION_NEEDED]: "needs migration",
     [APP_MANUAL_REVIEW_NEEDED]: "needs manual review",
 };
-/** Commands the TS dispatcher exposes (used by the in-process CLI probe). */
-const DISPATCHER_COMMANDS = new Set([
-    "prime", "hej", "schema", "describe", "state", "query", "check", "lint", "backfill",
-    "compact", "gate", "validate", "decisions", "health", "todo", "plan", "progress",
-    "docs", "objective", "experiments",
-]);
 function plainStatus(value) {
     return PLAIN_STATUS[value] ?? value.replace(/_/g, " ").replace(/-/g, " ");
 }
-function doctorActionNoun(status) {
-    if (status.status === APP_OUTDATED)
-        return "update";
-    if (status.status === APP_MIGRATION_NEEDED)
-        return "migration";
-    return "repair";
+function previewCommand(resource, context) {
+    return commandText([
+        "npx",
+        "-y",
+        "agentera@next",
+        "doctor",
+        "--home",
+        context.home,
+        "--project",
+        context.project,
+        "--install-root",
+        context.installRoot,
+        "--retired-resource",
+        resource.id,
+        "--format",
+        "json",
+    ]);
 }
-/** In-process probe: confirm the TS CLI exposes the expected state commands. */
-function inProcessProbe(args) {
-    const missing = args.expectedCommands.filter((name) => !DISPATCHER_COMMANDS.has(name));
-    const command = ["npx", "-y", "agentera", "--help"];
+function doctorRetiredResources(diagnosis, context) {
     return {
-        ok: missing.length === 0,
-        command,
-        returnCode: 0,
-        stdoutTail: [],
-        stderrTail: [],
-        missingCommands: missing,
-        message: missing.length === 0
-            ? "CLI exposes expected state commands"
-            : "CLI is missing expected state commands",
+        ...diagnosis,
+        resources: diagnosis.resources.map((resource) => ({
+            id: resource.id,
+            status: resource.status,
+            evidence: resource.evidence,
+            preview_command: previewCommand(resource, context),
+        })),
     };
 }
-export function renderDoctorStatus(status) {
-    const actionNoun = doctorActionNoun(status);
+export function renderDoctorStatus(status, retiredResources) {
+    const actionNoun = appLifecycleActionNoun(String(status.status));
     const lines = [
         "Agentera doctor",
         `status: ${plainStatus(status.status)}`,
@@ -66,6 +73,31 @@ export function renderDoctorStatus(status) {
             if (signal.missingCommands && signal.missingCommands.length > 0) {
                 lines.push(`    Missing command: ${signal.missingCommands.join(", ")}`);
             }
+            if (signal.kind === "todo_reconciliation") {
+                if (signal.reconciliationState)
+                    lines.push(`    Reconciliation state: ${signal.reconciliationState}`);
+                if (signal.reconciliationCounts) {
+                    const counts = ["matched", "converted", "retained", "duplicate", "stale", "conflicting"]
+                        .filter((name) => name in signal.reconciliationCounts)
+                        .map((name) => `${name}=${signal.reconciliationCounts[name]}`)
+                        .join(" | ");
+                    lines.push(`    Counts: ${counts} | omitted=${String(signal.reconciliationOmittedCount ?? 0)}`);
+                }
+                if (signal.previewCommand)
+                    lines.push(`    Preview: ${signal.previewCommand}`);
+                if (signal.applyCommand)
+                    lines.push(`    Apply: ${signal.applyCommand}`);
+            }
+        }
+    }
+    const resources = Array.isArray(retiredResources?.resources) ? retiredResources.resources : [];
+    const todoReconciliation = status.signals?.some((signal) => signal.kind === "todo_reconciliation") ?? false;
+    if (resources.length > 0) {
+        lines.push("");
+        lines.push("Retired native resources:");
+        for (const resource of resources) {
+            lines.push(`  - action required: ${String(resource.id)}`);
+            lines.push(`    Preview: ${String(resource.preview_command)}`);
         }
     }
     if (status.status === APP_UP_TO_DATE) {
@@ -77,7 +109,20 @@ export function renderDoctorStatus(status) {
         lines.push("Next:");
         lines.push(`  1. Preview the ${actionNoun}: ${status.dryRunCommand}`);
         lines.push(`  2. If the preview looks right, apply the ${actionNoun}: ${status.applyCommand}`);
-        lines.push(`  3. Then retry Agentera: ${status.retryCommand}`);
+        if (status.retryCommand) {
+            lines.push(`  3. Then retry Agentera: ${status.retryCommand}`);
+        }
+        else {
+            lines.push("  3. Then retry Agentera once a retry command is available.");
+        }
+    }
+    else if (todoReconciliation) {
+        lines.push("");
+        lines.push("Next: run the reported TODO reconciliation preview, review its bounded effect, then use its exact apply_command.");
+    }
+    else if (resources.length > 0) {
+        lines.push("");
+        lines.push("Next: review each read-only retirement preview before any explicit cleanup.");
     }
     else {
         lines.push("");
@@ -97,67 +142,6 @@ function renderDoctorSmoke(smoke) {
     }
     return lines.join("\n");
 }
-export function pyJsonIndentSorted(value) {
-    return jsonIndent(value, 0);
-}
-function jsonAscii(str) {
-    let out = '"';
-    for (const ch of str) {
-        const cp = ch.codePointAt(0);
-        if (ch === '"')
-            out += '\\"';
-        else if (ch === "\\")
-            out += "\\\\";
-        else if (cp === 0x08)
-            out += "\\b";
-        else if (cp === 0x09)
-            out += "\\t";
-        else if (cp === 0x0a)
-            out += "\\n";
-        else if (cp === 0x0c)
-            out += "\\f";
-        else if (cp === 0x0d)
-            out += "\\r";
-        else if (cp < 0x20)
-            out += "\\u" + cp.toString(16).padStart(4, "0");
-        else if (cp < 0x80)
-            out += ch;
-        else if (cp > 0xffff) {
-            const v = cp - 0x10000;
-            out += "\\u" + (0xd800 + (v >> 10)).toString(16).padStart(4, "0");
-            out += "\\u" + (0xdc00 + (v & 0x3ff)).toString(16).padStart(4, "0");
-        }
-        else
-            out += "\\u" + cp.toString(16).padStart(4, "0");
-    }
-    return out + '"';
-}
-function jsonIndent(value, level) {
-    const pad = "  ".repeat(level);
-    const padIn = "  ".repeat(level + 1);
-    if (value === null || value === undefined)
-        return "null";
-    if (value === true)
-        return "true";
-    if (value === false)
-        return "false";
-    if (typeof value === "number")
-        return String(value);
-    if (typeof value === "string")
-        return jsonAscii(value);
-    if (Array.isArray(value)) {
-        if (value.length === 0)
-            return "[]";
-        return "[\n" + value.map((v) => padIn + jsonIndent(v, level + 1)).join(",\n") + "\n" + pad + "]";
-    }
-    if (typeof value === "object") {
-        const keys = Object.keys(value).sort();
-        if (keys.length === 0)
-            return "{}";
-        return "{\n" + keys.map((k) => padIn + jsonAscii(k) + ": " + jsonIndent(value[k], level + 1)).join(",\n") + "\n" + pad + "}";
-    }
-    return "null";
-}
 export function cmdDoctor(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const err = io.err ?? ((t) => process.stderr.write(t));
@@ -170,18 +154,52 @@ export function cmdDoctor(args, io = {}) {
         return 2;
     }
     const home = resolvePath(expanduser(args.home ?? os.homedir()));
+    const project = resolvePath(expanduser(args.project ?? process.cwd()));
     const [installRoot, rootSource] = resolveDoctorInstallRoot(args.installRoot ?? null, { home, sourceRoot });
     const expectedCommands = args.expectCommand && args.expectCommand.length > 0 ? args.expectCommand : [...EXPECTED_STATE_COMMANDS];
     const status = buildDoctorStatus(installRoot, {
         rootSource,
         sourceRoot,
         home,
-        project: resolvePath(expanduser(args.project ?? process.cwd())),
+        project,
         expectedVersion: args.expectedVersion ?? null,
         expectedCommands,
-        probeCli: true,
-        probeRunner: inProcessProbe,
     });
+    const todoReconciliation = inspectTodoReconciliationState(project, sourceRoot);
+    if (todoReconciliation?.status === "action_required") {
+        status.signals.push({
+            status: APP_MANUAL_REVIEW_NEEDED,
+            kind: "todo_reconciliation",
+            message: `action-required: TODO reconciliation is ${todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "in an invalid lifecycle state"}`,
+            reconciliationState: todoReconciliation.state,
+            reconciliationCounts: todoReconciliation.counts,
+            reconciliationOmittedCount: todoReconciliation.omitted_count,
+            previewCommand: todoReconciliation.preview_command,
+            applyCommand: todoReconciliation.apply_command,
+            recoveryCommand: todoReconciliation.recovery_command,
+        });
+        if (status.status === APP_UP_TO_DATE)
+            status.status = APP_MANUAL_REVIEW_NEEDED;
+    }
+    const retiredDiagnosis = diagnoseRetiredResources({
+        home,
+        project,
+        installRoot,
+        resourceId: args.retiredResource ?? null,
+    });
+    const retiredResources = doctorRetiredResources(retiredDiagnosis, { home, project, installRoot });
+    if (retiredDiagnosis.status === "action_required") {
+        status.signals.push({
+            status: APP_MANUAL_REVIEW_NEEDED,
+            kind: "retired_native_resources",
+            message: "retired native resource candidates need ownership review before cleanup",
+            resourceIds: retiredDiagnosis.resources.map((resource) => resource.id),
+            omittedResourceCount: retiredDiagnosis.omittedResourceCount,
+        });
+        if (status.status === APP_UP_TO_DATE)
+            status.status = APP_MANUAL_REVIEW_NEEDED;
+    }
+    const sharedSkill = diagnoseCanonicalSkill(home);
     let smokeReport = null;
     if (args.smoke) {
         smokeReport = runNpmSmokeChecks(sourceRoot, process.env, {
@@ -189,19 +207,31 @@ export function cmdDoctor(args, io = {}) {
         });
     }
     if ((args.format ?? "text") === "json") {
-        const payload = publicDoctorStatus(status);
+        const payload = doctorParityJsonEnvelope(status);
+        payload.shared_skill = sharedSkill;
+        payload.retired_resources = retiredResources;
         if (smokeReport)
             payload.smoke = smokeReport;
         out(pyJsonIndentSorted(payload) + "\n");
     }
     else {
-        out(renderDoctorStatus(status) + (smokeReport ? renderDoctorSmoke(smokeReport) : "") + "\n");
+        const install = classifyInstall({ appHome: installRoot, sourceRoot });
+        const nextMajorLines = resolveNextMajorDoctorLines({
+            sourceRoot,
+            home,
+            channel: status.updateChannel ?? null,
+            install,
+            env: process.env,
+        });
+        const body = prependNextMajorDoctorSection(renderDoctorStatus(status, retiredResources), nextMajorLines) +
+            `\nShared skill\n  ${String(sharedSkill.status)}: ${String(sharedSkill.message)}\n  path: ${String(sharedSkill.path)}\n` +
+            (smokeReport ? renderDoctorSmoke(smokeReport) : "");
+        out(body + "\n");
     }
     if (args.smoke) {
         const failCount = Number(smokeReport?.summary?.fail ?? 0);
         if (failCount > 0)
             return 1;
     }
-    return status.status === APP_UP_TO_DATE ? 0 : 1;
+    return status.status === APP_UP_TO_DATE && sharedSkill.status === "pass" ? 0 : 1;
 }
-//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/durability.js

@@ -0,0 +1,81 @@
+import { resolvePath } from "../../core/paths.js";
+import { resolveSourceRoot } from "../../core/sourceRoot.js";
+import { emitStructured } from "../structured.js";
+import { stateDurabilityContract } from "../../state/archiveDiscovery.js";
+import { StateRetrievalFailure } from "../../state/directRetrieval.js";
+import { inspectDurability, renderDurabilityText, } from "../../state/durability.js";
+import { entityArtifactValues } from "../../state/entityStorage.js";
+export function requestedDurabilityFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === "--format") {
+            const value = argv[index + 1];
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+        if (argv[index].startsWith("--format=")) {
+            const value = argv[index].slice("--format=".length);
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+    }
+    return "text";
+}
+export function validateDurabilityArgs(args, sourceRoot) {
+    const contract = stateDurabilityContract(sourceRoot);
+    const validArtifacts = entityArtifactValues(sourceRoot);
+    if (args.number !== undefined)
+        throw entityDurabilityFailure("entity mode rejects --number; use --artifact ARTIFACT --id ID", args.artifact, args.id ?? undefined, validArtifacts);
+    if (!args.artifact || !args.id)
+        throw entityDurabilityFailure("entity-mode durability requires --artifact ARTIFACT --id ID", args.artifact, args.id ?? undefined, validArtifacts);
+    if (!/^[a-z]{10}$/.test(args.id))
+        throw entityDurabilityFailure(`entity ID '${args.id}' must be ten lowercase letters`, args.artifact, args.id, validArtifacts);
+    if (args.artifact && !validArtifacts.includes(args.artifact)) {
+        throw entityDurabilityFailure(`unsupported durability artifact '${args.artifact}'`, args.artifact, args.id ?? undefined, validArtifacts);
+    }
+    if (args.limit !== undefined && (args.limit < 1 || args.limit > contract.maximumLimit)) {
+        throw entityDurabilityFailure(`argument --limit must be between 1 and ${contract.maximumLimit}`, args.artifact, args.id ?? undefined, validArtifacts);
+    }
+}
+export function entityDurabilityFailure(message, artifact, id, validValues) {
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: "agentera check durability --artifact ARTIFACT --id ID --format json",
+            example: "agentera check durability --artifact progress --id qjtrmnpvka --format json",
+            recovery: "Use one bare entity ID returned by the artifact list; no state was changed.",
+            ...(artifact ? { artifact } : {}),
+            ...(id ? { id } : {}),
+            ...(validValues ? { valid_values: validValues } : {}),
+        },
+    }, 2);
+}
+export function emitDurabilityFailure(failure, format, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(failure.body, format, out);
+    else {
+        const details = failure.body.error;
+        out([
+            `Error: ${details.message}`,
+            `Class: ${details.class}`,
+            `Syntax: ${details.syntax}`,
+            `Example: ${details.example}`,
+            `Recovery: ${details.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return failure.exitCode;
+}
+export function cmdDurability(args, io = {}) {
+    const output = io.out ?? ((text) => process.stdout.write(text));
+    const response = inspectDurability(resolvePath(args.project ?? process.cwd()), args, { sourceRoot: resolveSourceRoot() });
+    if (args.format === "json" || args.format === "yaml") {
+        emitStructured(response, args.format, output);
+    }
+    else {
+        renderDurabilityText(response, output);
+    }
+    return 0;
+}