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

package/dist/cli/commands/compact.js

@@ -1,6 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML, { isMap, isScalar, isSeq } from "yaml";
 import { resolvePath } from "../../core/paths.js";
 import { runCompaction } from "../../hooks/compaction/index.js";
 import { emitStructured } from "../structured.js";
+import { boundStructuredProjection } from "../../state/projectionPolicy.js";
+const TODO_REFERENCE_DIAGNOSTIC_LIMIT = 20;
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isDirectory(directory) {
+    try {
+        const stat = fs.lstatSync(directory);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function yamlFilesBelow(directory) {
+    if (!isDirectory(directory))
+        return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+        .sort((left, right) => compareText(left.name, right.name))
+        .flatMap((entry) => {
+        const candidate = path.join(directory, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink())
+            return yamlFilesBelow(candidate);
+        return entry.isFile() && path.extname(entry.name) === ".yaml" ? [candidate] : [];
+    });
+}
+function activeStateYamlFiles(project) {
+    const stateRoot = path.join(project, ".agentera");
+    if (!isDirectory(stateRoot))
+        return [];
+    const topLevel = fs.readdirSync(stateRoot, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && path.extname(entry.name) === ".yaml")
+        .map((entry) => path.join(stateRoot, entry.name));
+    return [...topLevel, ...yamlFilesBelow(path.join(stateRoot, "entities"))]
+        .sort(compareText);
+}
+function stringScalarValues(node) {
+    if (isScalar(node))
+        return typeof node.value === "string" ? [node.value] : [];
+    if (isMap(node))
+        return node.items.flatMap((pair) => stringScalarValues(pair.value));
+    if (isSeq(node))
+        return node.items.flatMap(stringScalarValues);
+    return [];
+}
+function volatileTodoReferenceDiagnostics(project) {
+    const matches = [];
+    for (const file of activeStateYamlFiles(project)) {
+        const relativePath = path.relative(project, file).split(path.sep).join("/");
+        const contents = fs.readFileSync(file, "utf8");
+        let order = 0;
+        for (const document of YAML.parseAllDocuments(contents)) {
+            for (const value of stringScalarValues(document.contents)) {
+                for (const match of value.matchAll(/TODO line \d+|TODO\.md:\d+/g)) {
+                    matches.push({ path: relativePath, reference: match[0], order: order++ });
+                }
+            }
+        }
+    }
+    matches.sort((left, right) => compareText(left.path, right.path) || left.order - right.order);
+    return {
+        diagnostics: matches.slice(0, TODO_REFERENCE_DIAGNOSTIC_LIMIT).map(({ path, reference }) => ({ path, reference })),
+        omitted_count: Math.max(0, matches.length - TODO_REFERENCE_DIAGNOSTIC_LIMIT),
+    };
+}
+function volatileTodoReferenceGate(project, mode) {
+    const { diagnostics, omitted_count } = volatileTodoReferenceDiagnostics(project);
+    if (!diagnostics.length)
+        return null;
+    const count = diagnostics.length + omitted_count;
+    return {
+        status: {
+            artifact: "state_todo_references",
+            path: path.join(project, ".agentera"),
+            classification: "hygiene",
+            active_count: count,
+            archive_count: 0,
+            total_count: count,
+            over_limit_count: 0,
+            protected_overflow_count: 0,
+            exists: true,
+            reason: `${count} active state TODO reference${count === 1 ? "" : "s"} use volatile line syntax`,
+        },
+        mode,
+        action: "volatile_todo_reference",
+        changed: false,
+        result: null,
+        message: "replace TODO line references with stable TODO anchors",
+        diagnostics,
+        omitted_count,
+    };
+}
+function gatedCompactionOperations(project, mode) {
+    const hygiene = volatileTodoReferenceGate(project, mode);
+    if (mode === "fix" && hygiene)
+        return [hygiene];
+    const operations = runCompaction(project, mode);
+    return hygiene ? [...operations, hygiene] : operations;
+}
 function pyStr(value) {
     if (value === null || value === undefined)
         return "None";
@@ -21,34 +123,59 @@ 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 } : {}),
+        ...(op.diagnostics
+            ? {
+                diagnostics: op.diagnostics.map(({ path, reference }) => ({ path, reference })),
+                omitted_count: op.omitted_count ?? 0,
+            }
+            : {}),
     };
     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 volatileTodoReferences = operations.filter((op) => op.action === "volatile_todo_reference");
+    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 (volatileTodoReferences.length > 0) {
+        return `Replace volatile TODO line references in active state with stable anchors, 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 +188,37 @@ 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 volatileTodoReferences = operations.filter((op) => op.action === "volatile_todo_reference").length;
     const changed = operations.filter((op) => op.changed).length;
-    const status = errors || protectedOverflow || (mode === "check" && overLimit) ? "fail" : "pass";
+    const status = errors || volatileTodoReferences || (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 +228,10 @@ 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"))
+    if (operations.some((op) => op.action === "volatile_todo_reference"))
         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 +249,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,8 +265,17 @@ 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`);
+        if (Array.isArray(item.diagnostics)) {
+            for (const diagnostic of item.diagnostics) {
+                if (!diagnostic || typeof diagnostic !== "object" || Array.isArray(diagnostic))
+                    continue;
+                out(`  diagnostic=${String(diagnostic.path)}: ${String(diagnostic.reference)}\n`);
+            }
+            out(`  omitted_count=${pyStr(item.omitted_count)}\n`);
+        }
     }
     out(`guidance=${summary.guidance}\n`);
 }
@@ -131,18 +283,16 @@ export function cmdCompact(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     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 operations = gatedCompactionOperations(project, mode);
+    const payload = compactionPayload("check compact", project, mode, operations);
     emitCompactionPayload(payload, mode, args.format ?? "text", out);
     return compactionExitCode(mode, operations);
 }
 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 operations = gatedCompactionOperations(project, "check");
+    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

@@ -5,8 +5,11 @@ import { resolveDoctorInstallRoot, resolveSourceRootStrict, } from "../../upgrad
 import { runNpmSmokeChecks } from "../../setup/smokeChecks.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 { prependCoexistenceDoctorSection, resolveCoexistenceDoctorLines, } from "../../upgrade/coexistenceProbe.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",
@@ -23,7 +26,36 @@ const PLAIN_STATUS = {
 function plainStatus(value) {
     return PLAIN_STATUS[value] ?? value.replace(/_/g, " ").replace(/-/g, " ");
 }
-export function renderDoctorStatus(status) {
+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",
+    ]);
+}
+function doctorRetiredResources(diagnosis, context) {
+    return {
+        ...diagnosis,
+        resources: diagnosis.resources.map((resource) => ({
+            id: resource.id,
+            status: resource.status,
+            evidence: resource.evidence,
+            preview_command: previewCommand(resource, context),
+        })),
+    };
+}
+export function renderDoctorStatus(status, retiredResources) {
     const actionNoun = appLifecycleActionNoun(String(status.status));
     const lines = [
         "Agentera doctor",
@@ -41,6 +73,34 @@ 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}`);
+                if (signal.reconciliationState === "unsafe_inactive" && signal.recoveryCommand)
+                    lines.push(`    Recovery: ${signal.recoveryCommand}`);
+            }
+        }
+    }
+    const resources = Array.isArray(retiredResources?.resources) ? retiredResources.resources : [];
+    const todoReconciliation = status.signals?.some((signal) => signal.kind === "todo_reconciliation") ?? false;
+    const unsafeInactiveTodo = status.signals?.some((signal) => signal.kind === "todo_reconciliation" && signal.reconciliationState === "unsafe_inactive") ?? 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) {
@@ -59,6 +119,18 @@ export function renderDoctorStatus(status) {
             lines.push("  3. Then retry Agentera once a retry command is available.");
         }
     }
+    else if (unsafeInactiveTodo) {
+        lines.push("");
+        lines.push("Next: supply the complete owner mapping, preview the reported correction, then use its exact apply_command.");
+    }
+    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("");
         lines.push("Next: choose a safer Agentera directory, or use `--force` only after checking the directory is safe to replace.");
@@ -89,16 +161,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,
     });
+    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_inactive" ? "unsafe 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, {
@@ -107,17 +215,14 @@ export function cmdDoctor(args, io = {}) {
     }
     if ((args.format ?? "text") === "json") {
         const payload = doctorParityJsonEnvelope(status);
+        payload.shared_skill = sharedSkill;
+        payload.retired_resources = retiredResources;
         if (smokeReport)
             payload.smoke = smokeReport;
         out(pyJsonIndentSorted(payload) + "\n");
     }
     else {
         const install = classifyInstall({ appHome: installRoot, sourceRoot });
-        const coexistenceLines = resolveCoexistenceDoctorLines({
-            home,
-            sourceRoot,
-            env: { ...process.env, HOME: home },
-        });
         const nextMajorLines = resolveNextMajorDoctorLines({
             sourceRoot,
             home,
@@ -125,7 +230,9 @@ export function cmdDoctor(args, io = {}) {
             install,
             env: process.env,
         });
-        const body = prependCoexistenceDoctorSection(prependNextMajorDoctorSection(renderDoctorStatus(status), nextMajorLines), coexistenceLines) + (smokeReport ? renderDoctorSmoke(smokeReport) : "");
+        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) {
@@ -133,6 +240,5 @@ export function cmdDoctor(args, io = {}) {
         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;
+}