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

package/dist/cli/migrationRequired.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { emitStructured } from "./structured.js";
+import { classifyProjectState, detectStateMode } from "../state/stateMode.js";
+import { commandText, fullEntityUpgradeCommand, fullEntityUpgradePreviewCommand } from "../upgrade/upgradeCommands.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
+function value(argv, flag) {
+    const equals = argv.find((arg) => typeof arg === "string" && arg.startsWith(`${flag}=`));
+    if (equals)
+        return equals.slice(flag.length + 1);
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+export function requestedMigrationFailureFormat(argv) {
+    const format = value(argv, "--format");
+    return format === "json" || format === "yaml" ? format : "text";
+}
+/** Marker-absent projects expose only the forward upgrade and static discovery. */
+export function requiresCompletedEntityCutover(argv) {
+    const [command, subcommand, verb] = argv;
+    if (["--version", "version", "app-home", "doctor", "schema", "route", "upgrade"].includes(command))
+        return false;
+    if (command === "report" &&
+        ["personal-glossary-publish", "profile-grounding", "personal-glossary-candidates", "personal-glossary-decision", "personal-glossary-reviews"].includes(subcommand))
+        return false;
+    if (command === "check" && subcommand === "verify" && verb === "eval" && argv[3] === "glossary")
+        return false;
+    if (command === "prime" && (argv.includes("--guidance") || !argv.includes("--context") || value(argv, "--context") === "status"))
+        return false;
+    if (command === "query")
+        return !argv.includes("--list-artifacts");
+    if (command === "state" && subcommand === "query" && argv.includes("--list-artifacts"))
+        return false;
+    if (command === "state" && verb === "explain")
+        return false;
+    return true;
+}
+export function migrationProject(argv, fallback = process.cwd()) {
+    const explicit = value(argv, "--project");
+    if (explicit)
+        return path.resolve(explicit);
+    let candidate = path.resolve(fallback);
+    while (true) {
+        if (fs.existsSync(path.join(candidate, ".agentera", "state-mode.yaml")))
+            return candidate;
+        const parent = path.dirname(candidate);
+        if (parent === candidate)
+            return path.resolve(fallback);
+        candidate = parent;
+    }
+}
+function permitsFreshPlanInitialization(argv) {
+    const [command, subcommand, verb] = argv;
+    return command === "state" && subcommand === "plan" && verb === "create"
+        || command === "prime" && value(argv, "--context") === "plan";
+}
+function freshPlanCreateCommand(project) {
+    return commandText([
+        "npx", "-y", "agentera@next", "state", "plan", "create", "--project", project,
+        "--input", "PLAN.yaml", "--format", "json",
+    ]);
+}
+/** Read-only cutover gate. It only inspects the durable marker and emits a failure. */
+export function enforceCompletedEntityCutover(projectRoot, format, io = {}, argv = []) {
+    const project = path.resolve(projectRoot);
+    let mode;
+    try {
+        mode = detectStateMode(project);
+    }
+    catch (error) {
+        const recovery = `Restore the exact durable migration marker, then run ${preCutoverCommand("check validate state --format json")}.`;
+        const envelope = {
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: { class: "invalid_state_marker", message: error.message, project, recovery },
+        };
+        if (format === "json" || format === "yaml")
+            emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+        else
+            (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+        return 1;
+    }
+    if (mode === "entities")
+        return null;
+    const classification = classifyProjectState(project);
+    if (classification.state === "fresh_uninitialized") {
+        if (permitsFreshPlanInitialization(argv))
+            return null;
+        const recovery = freshPlanCreateCommand(project);
+        const envelope = {
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "fresh_initialization_required",
+                message: "Fresh project state is initialized only by state plan create; no other state writer can create entity authority.",
+                project,
+                recovery,
+            },
+        };
+        if (format === "json" || format === "yaml")
+            emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+        else
+            (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+        return 1;
+    }
+    const legacy = classification.state === "legacy";
+    const recovery = legacy ? fullEntityUpgradeCommand(project) : fullEntityUpgradePreviewCommand(project);
+    const envelope = {
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "migration_required",
+            message: legacy
+                ? "This command requires the completed entity-state cutover; legacy aggregates remain migration input only."
+                : `This command cannot adopt marker-absent ${classification.state} Agentera state; inspect it with the read-only recovery command before any mutation.`,
+            project,
+            recovery,
+        },
+    };
+    if (format === "json" || format === "yaml")
+        emitStructured(envelope, format, io.out ?? ((text) => process.stdout.write(text)));
+    else
+        (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
+    return 1;
+}

package/dist/cli/orientation/attention.js

@@ -1,16 +1,24 @@
 import { projectIntegrationAttention } from "../../upgrade/projectIntegration.js";
-import { isV2ManagedInstallAtAppHome } from "../../upgrade/coexistenceProbe.js";
 import { corpusCoverageAttention } from "./corpusCoverage.js";
 import { firstPresent } from "../stateQuery.js";
 import { TODO_SEVERITY_ORDER } from "../todoSeverity.js";
 export function buildOrientationAttention(state) {
-    const { profile_status: profileStatus, profile, profile_dict: profileDict, v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, } = state;
+    const { v1_migration: v1Migration, project_integration: projectIntegration, health, plan, decision_attention: decisionAttention, glossary_caveat_attention: glossaryCaveatAttention, corpus_coverage: corpusCoverage, todo_items: todoItems, todo_reconciliation: todoReconciliation, } = state;
     const attention = [];
-    if (isV2ManagedInstallAtAppHome(state.app.appHome)) {
-        attention.push(`normal: v2/v3 coexistence at ${state.app.appHome}; pick one line: complete v3 migration, uninstall v3, or stay on v2`);
+    if (todoReconciliation?.status === "action_required") {
+        const label = todoReconciliation.state === "inactive" ? "inactive" : todoReconciliation.state === "unsafe_inactive" ? "unsafe inactive" : todoReconciliation.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+        attention.push(todoReconciliation.state === "unsafe_inactive"
+            ? `action-required: TODO reconciliation is ${label}; ${todoReconciliation.recovery_command}`
+            : `action-required: TODO reconciliation is ${label}; preview \`${todoReconciliation.preview_command ?? "n/a"}\`; apply \`${todoReconciliation.apply_command ?? "n/a"}\``);
+    }
+    const skillDivergenceSignals = (state.app.signals ?? []).filter((s) => s.kind === "skill_root_divergence");
+    for (const signal of skillDivergenceSignals) {
+        attention.push(`degraded: skill-root divergence — ${signal.message ?? "a recognized skill root is below expected"}; run \`npx -y agentera@next upgrade --dry-run --channel development\` to preview repair (D78)`);
     }
     const integrationAttention = projectIntegrationAttention(projectIntegration);
-    if (integrationAttention) {
+    const hasAppIntegration = (projectIntegration.phases?.app.counts.total ?? 0) > 0;
+    const includeIntegrationAttention = Boolean(integrationAttention && hasAppIntegration);
+    if (includeIntegrationAttention && integrationAttention) {
         attention.push(integrationAttention);
     }
     const coverageAttention = corpusCoverageAttention(corpusCoverage);
@@ -20,21 +28,12 @@ export function buildOrientationAttention(state) {
     if (v1Migration.detected && projectIntegration.recommendation !== "upgrade") {
         attention.push(`degraded: v1 artifacts detected; preview \`${v1Migration.dry_run_command}\`; files=${v1Migration.affected_files.join(", ")}`);
     }
-    if (profileStatus === "not found") {
-        attention.push(`degraded: PROFILE.md not found at ${profile}; suggest running profile to generate PROFILE.md`);
-    }
-    else if (profileDict.stale) {
-        const daysSince = profileDict.days_since_generated ?? "?";
-        const staleDays = profileDict.stale_threshold_days ?? "?";
-        attention.push(`normal: profile stale (${daysSince} days since last refresh; ` +
-            `threshold=${staleDays}); suggest running profile to refresh PROFILE.md`);
-    }
     if (health.stale) {
-        const auditNumber = health.number ?? "?";
+        const auditId = health.id ?? "unknown";
         const daysSince = health.days_since_audit ?? "?";
         const thresholdDays = health.stale_threshold_days ?? "?";
         const thresholdCycles = health.stale_threshold_cycles ?? "?";
-        let attentionText = `normal: audit stale (${daysSince} days since Audit ${auditNumber}; ` +
+        let attentionText = `normal: audit stale (${daysSince} days since health audit ${auditId}; ` +
             `threshold days=${thresholdDays}, cycles=${thresholdCycles}`;
         const cyclesSince = health.cycles_since_audit;
         if (cyclesSince !== null && cyclesSince !== undefined)
@@ -45,6 +44,8 @@ export function buildOrientationAttention(state) {
         const worst = health.worst;
         attention.push(worst ? `critical: health needs attention (${worst[0]}:${worst[1]})` : "critical: health is degrading");
     }
+    if (glossaryCaveatAttention)
+        attention.push(glossaryCaveatAttention);
     const pending = plan.first_pending;
     if (pending && typeof pending === "object" && !Array.isArray(pending)) {
         const title = firstPresent(pending, ["name", "title"], "pending task");
@@ -53,9 +54,8 @@ export function buildOrientationAttention(state) {
     if (decisionAttention !== null)
         attention.push(String(decisionAttention.attention));
     if (!(pending && typeof pending === "object" && !Array.isArray(pending)) && todoItems.length > 0) {
-        const firstTodo = [...todoItems].sort((a, b) => (TODO_SEVERITY_ORDER[a.severity] ?? 2) - (TODO_SEVERITY_ORDER[b.severity] ?? 2))[0];
-        attention.push(`${firstTodo.severity}: TODO: ${firstTodo.text}`);
+        const firstTodo = [...todoItems].sort((a, b) => (TODO_SEVERITY_ORDER[String(a.severity)] ?? 2) - (TODO_SEVERITY_ORDER[String(b.severity)] ?? 2))[0];
+        attention.push(`${String(firstTodo.severity)}: TODO: ${String(firstTodo.text)}`);
     }
     return attention;
 }
-//# sourceMappingURL=attention.js.map

package/dist/cli/orientation/corpusCoverage.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { corpusTooLargeReason } from "../../analytics/usageStats.js";
 import { statsCorpusPath } from "../commands/report.js";
+import { tiersDirForCorpusPath, assessTiers, readBoundedMetadata, } from "../../analytics/extractCorpus/index.js";
 function emptyCoverageSummary(path, status) {
     return {
         path,
@@ -25,6 +26,36 @@ function parseCoverageGap(value) {
 }
 export function corpusCoverageSummary(env = process.env, platform = process.platform) {
     const corpusPath = statsCorpusPath(env, platform);
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    // Bounded tier coverage: when tiers are published, the manifest's coverage
+    // envelope truthfully reports the audit's available/selected/skipped runtimes
+    // without reading full evidence. The signal tier (bounded) remains usable even
+    // when a full-evidence shard is oversized, per the authority contract.
+    if (assessment.state !== "legacy" && assessment.state !== "missing") {
+        const meta = readBoundedMetadata(tiersDir);
+        const envelope = meta.corpusMetadata?.coverage_envelope;
+        if (meta.signal && envelope) {
+            return {
+                path: corpusPath,
+                tier_path: tiersDir,
+                status: "loaded",
+                tier_state: assessment.state,
+                available_runtimes: [...envelope.available_runtimes],
+                selected_runtimes: [...envelope.selected_runtimes],
+                available_but_not_selected: envelope.available_but_not_selected.map((g) => ({
+                    runtime: g.runtime,
+                    reason: g.reason,
+                    ...(typeof g.store_path === "string" ? { store_path: g.store_path } : {}),
+                })),
+            };
+        }
+        if (assessment.state === "oversized")
+            return emptyCoverageSummary(corpusPath, "too_large");
+        if (assessment.state === "corrupt")
+            return emptyCoverageSummary(corpusPath, "unreadable");
+    }
+    // Legacy monolithic envelope: small state preserved for compatibility.
     if (!fs.existsSync(corpusPath))
         return emptyCoverageSummary(corpusPath, "missing");
     const tooLarge = corpusTooLargeReason(corpusPath);
@@ -56,6 +87,7 @@ export function corpusCoverageSummary(env = process.env, platform = process.plat
     return {
         path: corpusPath,
         status: "loaded",
+        tier_state: "legacy",
         available_runtimes: availableRuntimes,
         selected_runtimes: selectedRuntimes,
         available_but_not_selected: skipped,
@@ -68,4 +100,3 @@ export function corpusCoverageAttention(summary) {
     return (`flagged: corpus coverage loss (EX2): available runtimes skipped (${skipped}); ` +
         "suggest running profile stats refresh without --no-* flags");
 }
-//# sourceMappingURL=corpusCoverage.js.map