create-agdf 0.14.5 → 0.20.0

package/runtime/core/lib/control-inspect/service.js

@@ -0,0 +1,319 @@
+import process from "node:process";
+import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
+import { buildStatusCard, evaluateGateCheck, postApprovalTransition, printApprovalEnvelope, printGateCheckReport } from "../control-evaluation/gate-check.js";
+import { evaluateDoctor } from "../control-evaluation/doctor.js";
+import { evaluateDeliveryMap } from "../control-evaluation/delivery-map.js";
+import { readRuntimeContract } from "../resources/contracts.js";
+import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory } from "../interaction-presentation.js";
+import { resolveTaskTarget, TaskTargetInputError } from "../task-target-resolution.js";
+import { SKILL_DISPATCH_PRESENTATION_LANGUAGE_RECOVERY, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
+import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, PRESENTATION_CATALOG_MODULE } from "./contract.js";
+import { operationContract } from '../control-state/run-command-contract.js';
+import { inspectRunOperation } from '../control-state/run-operation-status.js';
+import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
+import { readRunState } from '../control-evaluation/run-state.js';
+import { inspectArtifactReadiness } from "./artifact-readiness.js";
+import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
+import { parseRunState } from '../control-state/run-state-parser.js';
+import { artefactFileDigest, runSealState } from '../control-state/run-seal.js';
+import { readArtefactBindings } from '../control-state/artefact-bindings.js';
+import { readPresentationDocument, readPresentationPreview, readPresentationCatalog } from '../control-state/run-presentation.js';
+import { sourceRevisionBoundary } from '../control-state/run-revision-boundary.js';
+import { sourceRevisionQualityFacts } from '../control-state/run-source-revisions.js';
+import { readHistoryBytes } from '../control-state/run-revision-history.js';
+
+// The MCP read tool is a projection over the existing evaluators. It calls exactly the functions the
+// CLI handlers call and returns their --json report. Draft preflight additionally composes those
+// existing content validators through its read-only Core owner; it adds no CLI command. It never writes,
+// never selects a run on its own and never prepares an approval binding. Evaluators run with the
+// dispatcher's dependency set: no git child process, so verified_change git observation is absent.
+
+const defaultNow = () => process.hrtime.bigint();
+const milliseconds = (start, end) => Number(end - start) / 1_000_000;
+const round = (value) => Math.round(Math.max(0, value) * 1000) / 1000;
+
+class ControlInspectRuntimeError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "ControlInspectRuntimeError";
+    this.code = code;
+  }
+}
+
+function stage(code, callback) {
+  try {
+    return callback();
+  } catch {
+    throw new ControlInspectRuntimeError(code);
+  }
+}
+
+function runtimeEvidence(expectedVersion, evidence, env) {
+  if (evidence && typeof evidence === "object" && !Array.isArray(evidence)) {
+    return Object.freeze({
+      machine_validation: typeof evidence.machine_validation === "string" ? evidence.machine_validation : "unavailable",
+      expected_version: expectedVersion,
+      plugin_root: typeof evidence.plugin_root === "string" ? evidence.plugin_root : null,
+      runtime_digest: typeof evidence.runtime_digest === "string" ? evidence.runtime_digest : null,
+      provenance_status: typeof evidence.provenance_status === "string" ? evidence.provenance_status : null,
+    });
+  }
+  return Object.freeze({
+    machine_validation: env.AGDF_MACHINE_VALIDATION || "unavailable",
+    expected_version: expectedVersion,
+    plugin_root: env.AGDF_DISPATCH_PLUGIN_ROOT || null,
+    runtime_digest: env.AGDF_DISPATCH_RUNTIME_DIGEST || null,
+    provenance_status: env.AGDF_DISPATCH_PROVENANCE_STATUS || null,
+  });
+}
+
+function baseResult({ outcome, operation, runtime, timing }) {
+  return {
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
+    outcome,
+    terminal: outcome !== "inspect_result",
+    authorizes: false,
+    operation: operation ?? null,
+    runtime,
+    target: null,
+    report: null,
+    presentation: null,
+    recovery: null,
+    host_action: null,
+    timing,
+    diagnostics: [],
+  };
+}
+
+function bindHostAction(result) {
+  if (result.outcome === "inspect_result") {
+    result.host_action = Object.freeze({
+      mode: "consume_report_and_continue",
+      source: result.presentation?.markdown ? "presentation.markdown" : "report",
+      ...(result.presentation?.markdown ? { text: result.presentation.markdown } : {}),
+      allow_surrounding_text: true,
+      may_request_run_or_evidence: false,
+    });
+  } else if (result.presentation?.markdown) {
+    result.host_action = Object.freeze({
+      mode: "transmit_presentation_verbatim_and_stop",
+      source: "presentation.markdown",
+      text: result.presentation.markdown,
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    });
+  } else {
+    result.host_action = Object.freeze({
+      mode: "transmit_recovery_verbatim_and_stop",
+      source: "recovery.action",
+      text: result.recovery?.action ?? "",
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    });
+  }
+  return Object.freeze(result);
+}
+
+export function createInspectFailureResult(code, runtime, action) {
+  const result = baseResult({ outcome: "evaluator_error", runtime, timing: emptySkillDispatchTiming() });
+  result.recovery = { action };
+  result.diagnostics = [{ code }];
+  return bindHostAction(result);
+}
+
+function gateCheckPresentation(report, variant, reEvaluate) {
+  if (variant === "approval-envelope" || variant === "status-card") {
+    const lines = [];
+    const io = { log: (line = "") => lines.push(String(line)) };
+    if (variant === "approval-envelope") printApprovalEnvelope(report, { io, reEvaluate });
+    else printGateCheckReport(report, false, true, io);
+    return lines.length ? { markdown: lines.join("\n"), authorizes: false } : null;
+  }
+  if (report.status_presentation?.markdown) return report.status_presentation;
+  if (report.approval_presentation?.preview_markdown) return { markdown: report.approval_presentation.preview_markdown, authorizes: false };
+  return null;
+}
+
+export function createControlInspectService(dependencies = {}) {
+  const now = dependencies.now ?? defaultNow;
+  const env = dependencies.env ?? process.env;
+  const resolveTarget = dependencies.resolveTaskTarget ?? resolveTaskTarget;
+  const renderTarget = dependencies.renderTaskTargetOrientation ?? renderTaskTargetOrientation;
+  const renderInputRecovery = dependencies.renderSkillDispatchInputRecovery ?? renderSkillDispatchInputRecovery;
+  const renderRecovery = dependencies.renderSkillDispatchRecovery ?? renderSkillDispatchRecovery;
+  const doctor = dependencies.evaluateDoctor ?? evaluateDoctor;
+  const gateCheck = dependencies.evaluateGateCheck ?? evaluateGateCheck;
+  const deliveryMap = dependencies.evaluateDeliveryMap ?? evaluateDeliveryMap;
+  const readContract = dependencies.readRuntimeContract ?? readRuntimeContract;
+  const validateControlReadBoundary = dependencies.validateControlReadBoundary;
+  const deliveryMapDependencies = Object.freeze({ evaluateDoctor: doctor, buildStatusCard, postApprovalTransition });
+
+  return function executeControlInspect(rawInput) {
+    const started = now();
+    const timing = emptySkillDispatchTiming();
+    const runtime = runtimeEvidence(rawInput.expectedVersion, dependencies.runtimeEvidence, env);
+    let input;
+    try {
+      input = normalizeControlInspectInput(rawInput);
+    } catch (error) {
+      timing.input_ms = round(milliseconds(started, now()));
+      timing.total_ms = timing.input_ms;
+      const result = baseResult({ outcome: "invalid_input", operation: typeof rawInput.operation === "string" ? rawInput.operation : null, runtime, timing });
+      const inputError = error instanceof SkillDispatchInputError || error instanceof TaskTargetInputError || error instanceof ReadSelectionError ? error : null;
+      const field = inputError?.field ?? "arguments";
+      // Shared read-selection rules keep the CLI wording so both surfaces reject identically.
+      const action = error instanceof ReadSelectionError
+        ? error.message
+        : field === "presentation_language"
+          ? SKILL_DISPATCH_PRESENTATION_LANGUAGE_RECOVERY
+          : renderInputRecovery(
+            { field, allowedValues: inputError?.allowedValues ?? [] },
+            { registry: rawInput.interactionLocales, requestedLocale: rawInput.presentationLanguage },
+          ) ?? "Repair the installed locale registry and retry once.";
+      result.recovery = { action };
+      result.diagnostics = [{ code: "inspect_input_invalid", field,
+        ...(inputError?.allowedValues?.length ? { allowed_values: [...inputError.allowedValues] } : {}),
+      }];
+      return bindHostAction(result);
+    }
+    timing.input_ms = round(milliseconds(started, now()));
+    try {
+      const targetStarted = now();
+      const target = stage(DISPATCH_RECOVERY.target_evaluation_failed, () => resolveTarget({
+        targetSource: input.target_source, primaryTarget: input.primary_target, workingDirectory: input.working_directory,
+      }));
+      timing.target_ms = round(milliseconds(targetStarted, now()));
+      if (target.resolution_state !== "resolved") {
+        const renderStarted = now();
+        const orientation = stage(DISPATCH_RECOVERY.target_presentation_failed, () => {
+          const rendered = renderTarget(target, { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language });
+          if (!rendered) throw new Error("task_target_orientation_unavailable");
+          return rendered;
+        });
+        timing.render_ms = round(milliseconds(renderStarted, now()));
+        const result = baseResult({ outcome: "target_unresolved", operation: input.operation, runtime, timing });
+        result.target = target;
+        result.presentation = orientation;
+        result.recovery = { action: target.next_action };
+        timing.total_ms = round(milliseconds(started, now()));
+        return bindHostAction(result);
+      }
+      const controlStarted = now();
+      const { report, presentation, invalidModule } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
+        validateControlReadBoundary?.(target.governance_target);
+        const selection = {
+          ...(input.run_id ? { runId: input.run_id } : {}),
+          ...(input.all_active ? { allActive: true } : {}),
+        };
+        switch (input.operation) {
+          case 'presentation-document':
+          case 'presentation-preview':
+            return { report: (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
+              runId: input.run_id, gate: input.gate, revisionId: input.expected_revision_id,
+              presentationId: input.presentation_id, targetId: input.target_id, cursor: input.cursor,
+            }), presentation: null };
+          case 'runtime-generations':
+          case 'native-qualification': {
+            const state = readRunState(target.governance_target, { runId: input.run_id });
+            const valid = parseRunState(state.content, input.run_id).valid && state.meta?.revision_id === input.expected_revision_id
+              && runSealState(target.governance_target, state.content).status === 'valid';
+            if (!valid) return { report: { available: false, reason: 'operation_binding_stale_or_invalid', authorizes: false }, presentation: null };
+            if (input.operation === 'runtime-generations') return { report: dependencies.runtimeControl?.status()
+              ?? { available: false, reason: 'connection_control_unavailable', authorizes: false }, presentation: null };
+            const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentationLanguage });
+            return { report: { available: true, run_id: input.run_id, revision_id: state.meta.revision_id,
+              ui_rendering_support: 'unknown', action_qualification: { qualified: false, reason: 'host_context_unavailable', authorizes: false },
+              business_readiness: { current_gate: decision.current_gate, status: decision.status,
+                next_operation: decision.next_operation, blocking_reason: decision.blocking_reason }, authorizes: false }, presentation: null };
+          }
+          case 'operation-contract': {
+            const state = readRunState(target.governance_target, { runId: input.run_id });
+            const targetId = resolveControlCommandTarget(target.governance_target).target_id;
+            const valid = parseRunState(state.content, input.run_id).valid && state.meta?.revision_id === input.expected_revision_id
+              && runSealState(target.governance_target, state.content).status === 'valid';
+            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate }),
+              ...(input.contract_module === PRESENTATION_CATALOG_MODULE ? {
+                inspect_contract: inspectContractHelp(),
+                presentation_catalog: readPresentationCatalog(target.governance_target, { runId: input.run_id,
+                  revisionId: input.expected_revision_id, targetId, gate: input.gate, cursor: input.cursor,
+                  workingDirectory: input.working_directory, targetSource: input.target_source,
+                  primaryTarget: input.primary_target, language: input.presentation_language }),
+              } : {}),
+              ...(input.kind.startsWith('source_revision.') ? { revision_facts: {
+                policy_version: 2, eligible_sources: ['UR', 'PRD', 'SD', 'TP'].filter(gate => sourceRevisionBoundary(state, gate, 2)),
+                initiating_phase: policyForRunContent(target.governance_target, state.content, state.path).current_gate,
+                quality_records: sourceRevisionQualityFacts(state, path => { try { return readHistoryBytes(target.governance_target, path).toString('utf8'); } catch { return undefined; } }),
+              } } : {}),
+              binding: { target_id: targetId, run_id: input.run_id, expected_revision_id: input.expected_revision_id },
+              current: (() => { const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentationLanguage });
+                return { current_gate: decision.current_gate, lifecycle: state.meta.lifecycle, status: decision.status, missing_approval: decision.missing_approval,
+                  next_operation: decision.next_operation, completion: decision.completion,
+                  artefacts: [...state.artefacts].filter(([type]) => ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR', 'QA', 'OR'].includes(type))
+                    .map(([type, row]) => ({ type, path: row.path, status: row.status, digest: row.path ? artefactFileDigest(target.governance_target, row.path) : null,
+                      association: state.evidence_applicability.by_step.get(type)?.applicability ?? 'applicability_unknown' })),
+                  source_bindings: readArtefactBindings(state.content).active.map(row => ({ binding_id: row.binding_id, source: row.source, destination: row.destination, relationship: row.relationship })) }; })() }
+              : { available: false, authorizes: false, reason: 'operation_binding_stale_or_invalid' }, presentation: null };
+          }
+          case 'operation-status':
+            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id, operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id }, presentation: null };
+          case "artifact-readiness":
+            return { report: inspectArtifactReadiness(target.governance_target, {
+              runId: input.run_id, gate: input.gate, expectedRevisionId: input.expected_revision_id,
+              presentationLanguage: input.presentation_language,
+            }), presentation: null };
+          case "doctor": {
+            const evaluated = doctor(target.governance_target, selection);
+            return { report: evaluated, presentation: input.all_active
+              ? renderActiveRunInventory(evaluated, rawInput.interactionLocales, input.presentation_language) : null };
+          }
+          case "gate-check": {
+            const evaluate = () => gateCheck(target.governance_target, { ...selection, presentationLanguage: input.presentation_language });
+            const evaluated = evaluate();
+            return { report: evaluated, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
+          }
+          case "delivery-map": {
+            const evaluated = deliveryMap(target.governance_target, selection, deliveryMapDependencies);
+            return { report: evaluated, presentation: null };
+          }
+          case "contract": {
+            const read = readContract(input.contract_module, { pluginRoot: null });
+            if (!read.ok) return { report: null, presentation: null, invalidModule: read };
+            return { report: { module: read.module, content: read.content }, presentation: { markdown: read.content, authorizes: false } };
+          }
+          default:
+            throw new Error("unsupported_operation");
+        }
+      });
+      timing.control_ms = round(milliseconds(controlStarted, now()));
+      if (invalidModule) {
+        const result = baseResult({ outcome: "invalid_input", operation: input.operation, runtime, timing });
+        result.target = target;
+        // Same wording as the CLI `contract` handler's error output.
+        result.recovery = { action: `${invalidModule.reason}: ${input.contract_module}. Available modules: ${invalidModule.modules.join(", ")}` };
+        result.diagnostics = [{ code: "inspect_input_invalid", field: "module", allowed_values: [...invalidModule.modules] }];
+        timing.total_ms = round(milliseconds(started, now()));
+        return bindHostAction(result);
+      }
+      const result = baseResult({ outcome: "inspect_result", operation: input.operation, runtime, timing });
+      result.target = target;
+      result.report = report;
+      result.presentation = presentation;
+      timing.total_ms = round(milliseconds(started, now()));
+      return bindHostAction(result);
+    } catch (error) {
+      const code = error instanceof ControlInspectRuntimeError ? error.code : DISPATCH_RECOVERY.internal_failure;
+      let action;
+      try {
+        action = renderRecovery({ code }, { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language });
+      } catch {
+        action = null;
+      }
+      const result = baseResult({ outcome: "evaluator_error", operation: input.operation, runtime, timing });
+      result.recovery = { action: action ?? "Repair the installed locale registry and retry once." };
+      result.diagnostics = [{ code: `inspect_${code}` }];
+      timing.total_ms = round(milliseconds(started, now()));
+      return bindHostAction(result);
+    }
+  };
+}

package/runtime/core/lib/control-maintenance/compatibility.js

@@ -0,0 +1,149 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { discoverRuns } from "../control-state/run-state-reader.js";
+import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
+import { artefactFileDigest, listedArtefactPaths, pendingArtefactPaths, runSealState } from "../control-state/run-seal.js";
+import { inspectRunRecovery } from "../control-state/run-recovery.js";
+import { doctorRequiredFiles } from "../control-evaluation/required-files.js";
+import { inspectControlConfiguration } from "../control-state/control-configuration.js";
+import { hasSymlinkComponent } from "../control-state/contained-file.js";
+import { APPROVAL_GATES } from "../control-state/run-seal-compute.js";
+
+function entryExists(path) {
+  try { lstatSync(path); return true; } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function safeApprovalReset(approvals) {
+  return APPROVAL_GATES.every((gate) => approvals.some((approval) => approval.gate === gate))
+    && approvals.every((approval) => approval.status === "missing" && !approval.evidence);
+}
+
+function interruptedRecoveries(root, runId) {
+  const directory = join(root, ".agdf", "control", "runs", runId, "recovery-previews");
+  if (!entryExists(directory)) return [];
+  directoryIdentity(directory);
+  return readdirSync(directory).filter((name) => name.endsWith(".json")).map((name) => {
+    const journal = JSON.parse(regularFileSnapshot(join(directory, name)).content.toString("utf8"));
+    return journal.phase === "applying" ? { preview_id: journal.preview_id, confirmation: journal.confirmation,
+      prior_approvals: journal.prior_approvals, source_revision_id: journal.source_revision_id, next_gate: journal.next_gate,
+      journal: `.agdf/control/runs/${runId}/recovery-previews/${name}` } : null;
+  }).filter(Boolean);
+}
+
+export const CONTROL_MIGRATION_STATUSES = Object.freeze(["not_checked", "absent", "current", "migration_required", "repair_required"]);
+
+export function uncheckedControl() {
+  return { schema_version: 1, supported_control_state_version: 2, target: null,
+    status: "not_checked", runs: [], diagnostics: [], changes: [], authorizes: false };
+}
+
+// Repository compatibility is separate from delivery readiness and grants no gate authority.
+// Never search neighbouring repositories or infer a write target from a host configuration path.
+export function inspectControlMigration(root) {
+  if (!root) return uncheckedControl();
+  if (!isAbsolute(root)) throw new Error("AGDF_CONTROL_MIGRATION_TARGET_INVALID");
+  const result = { ...uncheckedControl(), target: root, status: "absent" };
+  const agdf = join(root, ".agdf");
+  try {
+    if (!entryExists(agdf)) return result;
+    for (const path of [root, agdf, join(agdf, "control")]) {
+      try { directoryIdentity(path); } catch {
+        throw Object.assign(new Error("AGDF_CONTROL_PATH_INVALID"), { path });
+      }
+    }
+    const required = [join(".agdf", "control", "config.json"), join(".agdf", "control", "README.md"),
+      ...doctorRequiredFiles.filter((path) => !path.endsWith("AGDF_RUN.md"))];
+    for (const path of required) {
+      try { regularFileSnapshot(join(root, path)); } catch {
+        throw Object.assign(new Error("AGDF_CONTROL_SCAFFOLD_INCOMPLETE"), { path });
+      }
+    }
+    const configuration = inspectControlConfiguration(root);
+    if (!configuration.active) throw new Error(configuration.diagnostic);
+    const legacyPath = join(agdf, "control", "AGDF_RUN.md");
+    if (entryExists(legacyPath)) {
+      const legacy = regularFileSnapshot(legacyPath).content.toString("utf8");
+      if (!legacy.startsWith("<!-- AGDF LEGACY PROJECTION")) {
+        result.diagnostics.push({ code: "AGDF_LEGACY_MIGRATION_REQUIRED", path: ".agdf/control/AGDF_RUN.md" });
+      }
+    }
+    const runsPath = join(agdf, "control", "runs");
+    if (!entryExists(runsPath) && result.diagnostics.length) {
+      result.status = "migration_required";
+      return result;
+    }
+    directoryIdentity(runsPath);
+    for (const run of discoverRuns(root)) {
+      const entry = { run_id: run.run_id, control_state_version: run.meta?.control_state_version ?? null,
+        lifecycle: run.meta?.lifecycle ?? null, status: "current", seal_status: null,
+        safe_to_migrate: false, approvals: [], pending_recoveries: [], diagnostics: [] };
+      if (!run.valid) {
+        entry.status = "repair_required";
+        entry.diagnostics = run.findings;
+      } else {
+        const seal = runSealState(root, run.content);
+        entry.seal_status = seal.status;
+        const pending = new Set(pendingArtefactPaths(run.content));
+        const unresolved = listedArtefactPaths(run.content).filter((path) => {
+          const status = artefactFileDigest(root, path);
+          return status === "unresolved" || (status === "missing" && (!pending.has(path) || hasSymlinkComponent(root, path)));
+        });
+        if (run.meta.lifecycle !== "active" && seal.status === "unsealed") {
+          // Historical records remain non-authorizing evidence; installation does not reopen them
+          // or manufacture a retrospective integrity/approval attestation.
+          entry.status = "historical";
+        } else if (unresolved.length) {
+          entry.status = "repair_required";
+          entry.diagnostics = unresolved.map((path) => ({ code: "AGDF_RECOVERY_ARTEFACT_MISSING", path }));
+        } else if (seal.status === "unsealed" && run.meta.lifecycle === "active") {
+          const inspection = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
+          entry.approvals = inspection.approvals;
+          entry.next_gate = inspection.next_gate_if_recovered;
+          entry.status = inspection.artefacts.every((file) => file.status === "valid" || file.planned) ? "migration_required" : "repair_required";
+          entry.safe_to_migrate = entry.status === "migration_required" && safeApprovalReset(inspection.approvals);
+          entry.diagnostics = inspection.artefacts.filter((file) => file.status !== "valid" && !file.planned)
+            .map((file) => ({ code: "AGDF_RECOVERY_ARTEFACT_PATH_INVALID", path: file.path }));
+        } else if (seal.status !== "valid") {
+          entry.status = "repair_required";
+          entry.diagnostics = [{ code: "AGDF_RUN_SEAL_INVALID", seal_status: seal.status }];
+        }
+        entry.pending_recoveries = interruptedRecoveries(root, run.run_id);
+        if (entry.pending_recoveries.length) {
+          entry.status = "repair_required";
+          entry.diagnostics.push({ code: "AGDF_RECOVERY_RESUME_REQUIRED" });
+        }
+      }
+      result.runs.push(entry);
+    }
+    result.status = result.runs.some((run) => run.status === "repair_required") ? "repair_required"
+      : result.diagnostics.length || result.runs.some((run) => run.status === "migration_required") ? "migration_required" : "current";
+  } catch (error) {
+    result.status = "repair_required";
+    result.diagnostics.push({ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) });
+  }
+  return result;
+}
+
+export function assertControlMigration(value) {
+  if (!value || value.schema_version !== 1 || value.supported_control_state_version !== 2
+      || !CONTROL_MIGRATION_STATUSES.includes(value.status) || value.authorizes !== false
+      || !(value.target === null || (typeof value.target === "string" && isAbsolute(value.target)))
+      || (value.status === "not_checked" && value.target !== null)
+      || (value.status !== "not_checked" && value.target === null)
+      || !Array.isArray(value.runs) || !Array.isArray(value.diagnostics) || !Array.isArray(value.changes)) {
+    throw new Error("AGDF_CONTROL_MIGRATION_REPORT_INVALID");
+  }
+  if (value.repair && (value.repair.authorizes !== false || value.repair.target !== value.target
+      || !["needs_input", "deferred", "partial", "applied"].includes(value.repair.status)
+      || !Array.isArray(value.repair.diagnostics) || !Array.isArray(value.repair.items)
+      || value.repair.items.some((item) => typeof item.run_id !== "string" || typeof item.available !== "boolean"
+        || !["manual", "self_reference", "run_snapshot", "missing_artefacts"].includes(item.kind)
+        || !Array.isArray(item.sources) || !Array.isArray(item.required)))) {
+    throw new Error("AGDF_CONTROL_REPAIR_REPORT_INVALID");
+  }
+  return value;
+}
+

package/runtime/core/lib/control-maintenance/contract.js

@@ -0,0 +1,41 @@
+import { isAbsolute } from "node:path";
+import { assertControlMigration } from "./compatibility.js";
+
+// Counts are presentation projections of the canonical inventory, never a stored policy.
+export function controlCounts(control) {
+  return {
+    migration: control.runs.filter((run) => run.status === "migration_required" || run.pending_recoveries?.length === 1).length,
+    repair: control.runs.filter((run) => run.status === "repair_required" && run.pending_recoveries?.length !== 1).length,
+    historical: control.runs.filter((run) => run.status === "historical").length,
+  };
+}
+
+export function assertMaintenanceResult(value, target = value?.target) {
+  if (!value || value.schema_version !== 1 || value.authorizes !== false
+      || typeof target !== "string" || !isAbsolute(target) || value.target !== target
+      || !["inspect", "guided"].includes(value.operation)
+      || !["complete", "unavailable", "not_checked"].includes(value.inspection_state)
+      || !["not_started", "deferred", "applied", "partial", "needs_input"].includes(value.maintenance_outcome)
+      || !Array.isArray(value.diagnostics)) throw new Error("AGDF_MAINTENANCE_RESULT_INVALID");
+  if (value.inspection_state === "complete") {
+    assertControlMigration(value.compatibility);
+    if (value.compatibility.target !== target
+        || JSON.stringify(value.counts) !== JSON.stringify(controlCounts(value.compatibility))) {
+      throw new Error("AGDF_MAINTENANCE_TARGET_MISMATCH");
+    }
+  } else if (value.compatibility !== null || value.counts !== null) throw new Error("AGDF_MAINTENANCE_RESULT_INVALID");
+  return value;
+}
+
+export function maintenanceResult(target, compatibility, { operation = "inspect", outcome = "not_started", diagnostic, diagnostics = [] } = {}) {
+  return assertMaintenanceResult({ schema_version: 1, target, operation, authorizes: false,
+    inspection_state: compatibility ? "complete" : "unavailable",
+    compatibility, counts: compatibility ? controlCounts(compatibility) : null,
+    maintenance_outcome: outcome, diagnostics: diagnostic ? [{ code: diagnostic }] : diagnostics });
+}
+
+export function maintenanceExitCode(report) {
+  if (report.inspection_state !== "complete") return 1;
+  if (report.maintenance_outcome === "deferred") return 0;
+  return ["current", "absent"].includes(report.compatibility.status) ? 0 : 2;
+}

package/runtime/core/lib/control-maintenance/interaction.js

@@ -0,0 +1,57 @@
+import { interactionLocales } from "../resources/context.js";
+import { localePack } from "../interaction-presentation.js";
+import { renderMaintenanceOffer, renderControlMigrationDecision, renderControlRepairOffer, renderControlRepairPlan } from "./presentation.js";
+
+export async function selectControlMaintenance(control, {
+  readChoice, write = () => {}, registry = interactionLocales, language = "en",
+} = {}) {
+  if (typeof readChoice !== "function") throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
+  const copy = localePack(registry, language).repositoryMaintenance;
+  write(renderMaintenanceOffer(control, { registry, language }));
+  while (true) {
+    let raw;
+    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
+    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
+    if (["1", "start"].includes(choice)) return "start";
+    if (["3", "d", "details"].includes(choice)) write(renderMaintenanceOffer(control, { registry, language, details: true }));
+    else write(copy.invalid);
+  }
+}
+
+export async function selectControlMigration(plan, {
+  readChoice, write = () => {}, registry = interactionLocales, language = "en",
+} = {}) {
+  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_MIGRATION_READER_REQUIRED");
+  const copy = localePack(registry, language).installSetup.controlMigration;
+  write(renderControlMigrationDecision(plan, { registry, language }));
+  while (true) {
+    let value;
+    try { value = await readChoice({ prompt: copy.batchPrompt, default: null }); } catch { return "skip"; }
+    const choice = typeof value === "string" ? value.trim().toLowerCase() : "";
+    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
+    if (["1", "migrate"].includes(choice)) return "migrate";
+    if (["3", "d", "details"].includes(choice)) write(renderControlMigrationDecision(plan, { registry, language, details: true }));
+    else write(copy.invalidChoice);
+  }
+}
+
+export async function selectControlRepair(value, {
+  readChoice, write = () => {}, registry = interactionLocales, language = "en", phase = "offer",
+} = {}) {
+  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_REPAIR_READER_REQUIRED");
+  if (!["offer", "plan"].includes(phase)) throw new Error("AGDF_CONTROL_REPAIR_PHASE_INVALID");
+  const copy = localePack(registry, language).installSetup.controlRepair;
+  const render = phase === "offer" ? renderControlRepairOffer : renderControlRepairPlan;
+  write(render(value, { registry, language }));
+  while (true) {
+    let raw;
+    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
+    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
+    if (choice === "1" && (phase === "offer" || value.items.some((item) => item.available))) return phase === "offer" ? "start" : "repair";
+    if (["3", "d", "details"].includes(choice)) write(render(value, { registry, language, details: true }));
+    else write(copy.invalidChoice);
+  }
+}
+

package/runtime/core/lib/control-maintenance/migration.js

@@ -0,0 +1,85 @@
+import { join } from "node:path";
+import { regularFileSnapshot } from "../control-state/run-store-inspection.js";
+import { applyRunRecovery, inspectRunRecovery, previewRunRecovery } from "../control-state/run-recovery.js";
+import { inspectControlMigration, safeApprovalReset } from "./compatibility.js";
+
+export async function migrateInstallationControl(root, { mode = "inspect", confirmMigration } = {}) {
+  if (!["inspect", "safe"].includes(mode)) throw new Error("AGDF_CONTROL_MIGRATION_MODE_INVALID");
+  const before = inspectControlMigration(root);
+  if (mode === "inspect" || !root) return before;
+  const changes = [];
+  const errors = [];
+  // A structural inventory failure never authorizes a partial migration of an incomplete inventory.
+  if (before.diagnostics.some((finding) => finding.code !== "AGDF_LEGACY_MIGRATION_REQUIRED")) return before;
+  const candidates = before.runs.filter((entry) => entry.status === "migration_required" || entry.pending_recoveries?.length);
+  // Bind the single decision to read-only snapshots. Declining must not even create journals.
+  // The canonical recovery writer still checks each selected revision under its own lock.
+  let selected;
+  if (typeof confirmMigration === "function" && candidates.length) {
+    selected = new Map();
+    for (const run of candidates) {
+      try {
+        if (run.pending_recoveries?.length > 1) throw new Error("AGDF_RECOVERY_JOURNAL_CONFLICT");
+        const pending = run.pending_recoveries?.[0];
+        const journalContent = pending ? regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") : null;
+        const journal = pending ? JSON.parse(journalContent) : null;
+        const inspection = pending ? null : inspectRunRecovery(root, run.run_id, { inspectHistory: false });
+        selected.set(run.run_id, {
+          run_id: run.run_id, pending, journalContent,
+          source_revision_id: journal?.source_revision_id ?? inspection.revision_id,
+          source_content_digest: journal?.source_content_digest ?? inspection.content_digest,
+          source_artefacts: journal?.source_artefacts ?? inspection.artefacts,
+          prior_approvals: journal?.prior_approvals ?? inspection.approvals,
+          next_gate: journal?.next_gate ?? inspection.next_gate_if_recovered,
+        });
+      } catch (error) { errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) }); }
+    }
+    if (selected.size) {
+      const plan = { target: root, control: before, runs: [...selected.values()], diagnostics: errors,
+        approval_reset_count: [...selected.values()].filter((run) => !safeApprovalReset(run.prior_approvals)).length,
+        authorizes: false };
+      if (await confirmMigration(structuredClone(plan)) !== "migrate") return before;
+    }
+  }
+  for (const run of candidates) {
+    if (selected && !selected.has(run.run_id)) continue;
+    if (run.pending_recoveries?.length > 1) { errors.push({ run_id: run.run_id, code: "AGDF_RECOVERY_JOURNAL_CONFLICT" }); continue; }
+    if (run.pending_recoveries?.length) run.safe_to_migrate = safeApprovalReset(run.pending_recoveries[0].prior_approvals ?? []);
+    if (!selected && !run.safe_to_migrate) continue;
+    try {
+      const snapshot = selected?.get(run.run_id);
+      const pending = run.pending_recoveries?.[0];
+      if (snapshot) {
+        if (pending) {
+          if (regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") !== snapshot.journalContent) {
+            throw new Error("AGDF_STALE_RUN_REVISION");
+          }
+        } else {
+          const current = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
+          if (current.revision_id !== snapshot.source_revision_id || current.content_digest !== snapshot.source_content_digest
+              || JSON.stringify(current.artefacts) !== JSON.stringify(snapshot.source_artefacts)) throw new Error("AGDF_STALE_RUN_REVISION");
+        }
+      }
+      const preview = pending ?? previewRunRecovery(root, run.run_id);
+      if (snapshot && !pending && (preview.source_content_digest !== snapshot.source_content_digest
+          || JSON.stringify(preview.source_artefacts) !== JSON.stringify(snapshot.source_artefacts))) throw new Error("AGDF_STALE_RUN_REVISION");
+      // A concurrent approval change must never turn a safe migration into approval invalidation.
+      const journal = JSON.parse(regularFileSnapshot(join(root, preview.journal)).content.toString("utf8"));
+      const safe = safeApprovalReset(journal.prior_approvals);
+      const confirmation = selected || safe ? preview.confirmation : null;
+      if (confirmation !== preview.confirmation) continue;
+      const applied = applyRunRecovery(root, { runId: run.run_id, previewId: preview.preview_id, confirmation });
+      if (applied.seal_status !== "valid" && applied.outcome !== "already_recovered") throw new Error("AGDF_CONTROL_MIGRATION_VERIFICATION_FAILED");
+      changes.push({ run_id: run.run_id, outcome: applied.outcome, revision_id: applied.revision_id,
+        backup: preview.journal, next_gate: preview.next_gate });
+    } catch (error) {
+      errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) });
+    }
+  }
+  const after = inspectControlMigration(root);
+  after.changes = changes;
+  after.diagnostics.push(...errors);
+  if (errors.length) after.status = "repair_required";
+  return after;
+}
+