create-agdf 0.14.5 → 0.20.1

package/{lib → runtime/core/lib}/interaction-presentation.js

@@ -1,4 +1,6 @@
 import { RUN_ID_PATTERN } from "./control-state/run-identity.js";
+import { DISPATCH_RECOVERY_CODES, DECISION_CARD_COPY_BUDGETS } from "./interaction-catalog.js";
+import { TASK_TARGET_SOURCES, TASK_TARGET_UNRESOLVED_REASONS } from "./task-target-resolution.js";
 
 const REQUIRED_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const ARTEFACT_ORDER = ["UR", "PRD", "SD", "TP"];
@@ -50,40 +52,81 @@ function visibleStrings(value, prefix = "") {
   for (const [key, child] of Object.entries(value ?? {})) {
     const path = prefix ? `${prefix}.${key}` : key;
     if (plainObject(child)) entries.push(...visibleStrings(child, path));
-    else if (typeof child === "string") entries.push([path, child]);
+    else entries.push([path, child]);
   }
   return entries;
 }
 
+export const PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE = "^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$";
+const PRESENTATION_LANGUAGE_TAG_PATTERN = new RegExp(PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE, "u");
+
 export function canonicalizeLanguageTag(value) {
-  const raw = String(value ?? "").trim().replaceAll("_", "-").replace(/\.(.+)$/, "");
-  if (!raw || !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(raw)) return "";
+  if (typeof value !== "string" || !PRESENTATION_LANGUAGE_TAG_PATTERN.test(value)) return "";
   try {
-    return Intl.getCanonicalLocales(raw)[0]?.toLowerCase() ?? "";
+    return Intl.getCanonicalLocales(value)[0]?.toLowerCase() ?? "";
   } catch {
     return "";
   }
 }
 
+// Only a fully immutable data graph can retain a successful pure validation.
+// This holds no Run, target, approval or filesystem observation; weak keys do not retain catalogs.
+const validatedImmutableLocales = new WeakSet();
+function immutableLocaleData(value, seen = new WeakSet()) {
+  if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return true;
+  if (typeof value !== 'object' || !Object.isFrozen(value)) return false;
+  const array = Array.isArray(value), prototype = Object.getPrototypeOf(value);
+  if (prototype !== (array ? Array.prototype : Object.prototype) && prototype !== null) return false;
+  if (seen.has(value)) return true;
+  seen.add(value);
+  return Reflect.ownKeys(value).every(key => {
+    if (typeof key !== 'string') return false;
+    const field = Object.getOwnPropertyDescriptor(value, key);
+    return field && Object.hasOwn(field, 'value') && (field.enumerable || array && key === 'length')
+      && immutableLocaleData(field.value, seen);
+  });
+}
+
 export function validateLocaleRegistry(registry) {
+  if (validatedImmutableLocales.has(registry)) return { valid: true, errors: [] };
+  const result = validateReadLocaleRegistry(registry);
+  // A frozen outer object alone is insufficient; nested mutable data and accessors stay live.
+  if (result.valid && immutableLocaleData(registry)) validatedImmutableLocales.add(registry);
+  return result;
+}
+
+function validateReadLocaleRegistry(registry) {
   const errors = [];
   if (!plainObject(registry) || registry.schemaVersion !== 1) errors.push("schema_version");
-  const fallback = canonicalizeLanguageTag(registry?.fallbackLocale);
   const locales = registry?.locales;
-  if (!fallback || !plainObject(locales) || !plainObject(locales[fallback])) errors.push("fallback_locale");
-  const baseline = plainObject(locales?.[fallback]) ? flattenKeys(locales[fallback]) : [];
+  if (registry?.fallbackLocale !== "en" || !plainObject(locales) || !plainObject(locales.en)) errors.push("fallback_locale");
+  const baseline = plainObject(locales?.en) ? flattenKeys(locales.en) : [];
   const budgets = registry?.lengthBudgets ?? {};
+  const canonicalLocales = new Set();
   for (const [locale, pack] of Object.entries(locales ?? {})) {
-    if (!canonicalizeLanguageTag(locale) || !plainObject(pack)) {
+    const canonicalLocale = canonicalizeLanguageTag(locale);
+    if (canonicalLocale && canonicalLocales.has(canonicalLocale)) errors.push(`duplicate_locale:${locale}`);
+    if (canonicalLocale) canonicalLocales.add(canonicalLocale);
+    if (!canonicalLocale || canonicalLocale !== locale || !plainObject(pack)) {
       errors.push(`invalid_locale:${locale}`);
       continue;
     }
     const keys = flattenKeys(pack);
+    for (const key of ["statusCard.maintenance", "operationalValues.relationshipCorrected", "operationalValues.blockedRelationshipConflict"]) {
+      if (!keys.includes(key)) errors.push(`missing_relationship_copy:${locale}:${key}`);
+    }
     if (JSON.stringify(keys) !== JSON.stringify(baseline)) errors.push(`incomplete_locale:${locale}`);
     for (const [key, value] of visibleStrings(pack)) {
+      if (typeof value !== "string") {
+        errors.push(`invalid_copy:${locale}:${key}`);
+        continue;
+      }
       if (!value.trim()) errors.push(`empty_copy:${locale}:${key}`);
-      const budget = key.startsWith("gateTitles.") || key.startsWith("gateActionTitles.") ? budgets.title
-        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("gateRequiredDecisions.") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key.startsWith("primary.narration.") || key.startsWith("gateRationale.") || key.startsWith("interaction.why.") || ["interaction.decisionInstruction", "interaction.decisionPrompt", "interaction.exactTextRequest", "interaction.decisionFollows", "interaction.presentationFailure", "interaction.nonReadyDecision", "primary.quality"].includes(key)
+      const cardBudget = key.startsWith("decisionCard.") ? DECISION_CARD_COPY_BUDGETS[key.slice("decisionCard.".length)] : null;
+      const budget = cardBudget ? budgets[cardBudget]
+        : key.startsWith("sourceRevision.") || key.startsWith("mcpErrors.") ? budgets.description
+        : key.startsWith("gateTitles.") || key.startsWith("gateActionTitles.") ? budgets.title
+        : key.includes("Description") || key.includes("fallbackReasons") || key.startsWith("runResolution.") || key.startsWith("controlSetup.") || key.startsWith("operationalValues.") || key.startsWith("gateRequiredDecisions.") || key.startsWith("taskTargetResolution.nextActions.") || key.startsWith("skillDispatch.recoveries.") || key.startsWith("skillDispatch.sourceInput.") || key.startsWith("primary.actions.") || key.startsWith("primary.afterApproval.") || key.startsWith("primary.narration.") || key.startsWith("gateRationale.") || key.startsWith("interaction.why.") || key.startsWith("mcpLifecycle.actions.") || key.startsWith("mcpLifecycle.permissionEffects.") || key.startsWith("mcpLifecycle.diagnostics.") || key.startsWith("installSetup.actions.") || key.startsWith("installSetup.blockReasons.") || key.startsWith("installSetup.runtimeConsent.") || ["installSetup.invalidChoice", "installSetup.emptyChoice", "installSetup.blockedChoice", "interaction.decisionInstruction", "interaction.decisionPrompt", "interaction.exactTextRequest", "interaction.decisionFollows", "interaction.presentationFailure", "interaction.nonReadyDecision", "primary.quality"].includes(key)
           ? budgets.description
           : budgets.label;
       if (Number.isInteger(budget) && value.length > budget) errors.push(`length_budget:${locale}:${key}`);
@@ -101,18 +144,75 @@ export function validateLocaleRegistry(registry) {
 export function resolvePresentationLocale(registry, requestedLocale) {
   const validation = validateLocaleRegistry(registry);
   if (!validation.valid) throw new Error(`Invalid AGDF interaction locale registry: ${validation.errors.join(",")}`);
-  const fallback = canonicalizeLanguageTag(registry.fallbackLocale);
+  const requested = canonicalizeLanguageTag(requestedLocale);
+  if (!requested) throw new Error("Invalid AGDF presentation language tag");
+  return matchPresentationLocale(registry, requested, { validated: true }) || "en";
+}
+
+export function matchPresentationLocale(registry, requestedLocale, { validated = false } = {}) {
+  if (!validated) {
+    const validation = validateLocaleRegistry(registry);
+    if (!validation.valid) throw new Error(`Invalid AGDF interaction locale registry: ${validation.errors.join(",")}`);
+  }
   const requested = canonicalizeLanguageTag(requestedLocale);
   if (requested && registry.locales[requested]) return requested;
   const language = requested.split("-")[0];
   if (language && registry.locales[language]) return language;
-  return fallback;
+  return "";
 }
 
 export function localePack(registry, requestedLocale) {
   return registry.locales[resolvePresentationLocale(registry, requestedLocale)];
 }
 
+export function renderSkillDispatchInputRecovery({ field, allowedValues = [] } = {}, {
+  registry,
+  requestedLocale,
+} = {}) {
+  if (typeof field !== "string" || !/^[a-z_]{1,64}$/u.test(field)) return null;
+  const allowedValuePattern = field === "skill_id" ? /^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?$/u
+    : field === "module" ? /^[a-z][a-z0-9_-]*(?:\/[a-z][a-z0-9._-]*)?$/u : /^[a-z_]{1,64}$/u;
+  if (!Array.isArray(allowedValues) || allowedValues.some((value) => typeof value !== "string" || value.length > 64 || !allowedValuePattern.test(value))) return null;
+  let pack;
+  try {
+    pack = localePack(registry, requestedLocale)?.skillDispatch;
+  } catch {
+    return null;
+  }
+  const template = allowedValues.length ? pack?.allowedValuesDescription : pack?.invalidInputDescription;
+  if (typeof template !== "string" || !template.includes("{field}")) return null;
+  if (allowedValues.length && !template.includes("{allowed_values}")) return null;
+  return template
+    .replaceAll("{field}", field)
+    .replaceAll("{allowed_values}", allowedValues.join(", "));
+}
+
+const SKILL_DISPATCH_RECOVERY_CODES = new Set(DISPATCH_RECOVERY_CODES);
+
+export function renderSkillDispatchRecovery({ code } = {}, {
+  registry,
+  requestedLocale,
+} = {}) {
+  if (!SKILL_DISPATCH_RECOVERY_CODES.has(code)) return null;
+  let pack;
+  try {
+    pack = localePack(registry, requestedLocale)?.skillDispatch?.recoveries;
+  } catch {
+    return null;
+  }
+  const action = pack?.[code];
+  return typeof action === "string" && action.trim() ? action : null;
+}
+
+// Paths and observed source words are diagnostic data, never instructions or authority.
+export function renderDefinitionSourceRecovery(issue, { registry, requestedLocale } = {}) {
+  let pack;
+  try { pack = localePack(registry, requestedLocale)?.skillDispatch?.sourceInput; } catch { return null; }
+  if (!pack?.conditions?.[issue?.code]) return null;
+  const safe = value => String(value ?? '').slice(0, 1024).replace(/[\r\n\u2028\u2029]/gu, ' ').replace(/[`\\<>|]/gu, '');
+  return `${pack.conditions[issue.code]}\n\n${pack.source}: \`${safe(issue.path)}\`\n${pack.expected}: \`${safe(issue.expected)}\`\n${pack.observed}: \`${safe(issue.observed)}\`\n${pack.next}: ${issue.repairable ? pack.prepare : pack.stop}`;
+}
+
 export function gateTitle(registry, requestedLocale, gate) {
   return localePack(registry, requestedLocale).gateTitles[gate] || String(gate || "");
 }
@@ -151,23 +251,37 @@ function displaySafeTitle(value, fallback) {
   return (title || fallback).slice(0, 100);
 }
 
+function displaySafeObjective(value, fallback) {
+  const objective = String(value ?? "")
+    .split(/\r?\n/u)
+    .map(stripMarkdown)
+    .filter(Boolean)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return (objective || fallback).slice(0, 500);
+}
+
 export function buildRunCandidates(runs) {
   return [...(runs ?? [])]
     .filter((run) => run?.valid && run?.meta?.lifecycle === "active" && typeof run.run_id === "string")
     .map((run) => {
-      const currentGate = run.control_state?.current_gate || run.meta?.current_gate || "unknown";
+      const currentGate = stripMarkdown(run.control_state?.current_gate || run.meta?.current_gate || "unknown") || "unknown";
       const title = resolveHumanRunTitle({
         currentArtefactHeading: run.current_artefact_heading,
         urHeading: run.ur_heading,
-        runContent: "",
+        runContent: run.content,
         runId: run.run_id,
       });
       return {
         run_id: run.run_id,
         display_title: displaySafeTitle(title, normalizedRunTitle(run.run_id)),
+        objective: displaySafeObjective(section(String(run.content ?? ""), "Objective"), normalizedRunTitle(run.run_id)),
         current_gate: currentGate,
+        decision: String(run.meta?.decision || "unknown").replaceAll("`", "").trim() || "unknown",
         next_allowed_action: String(run.control_state?.next_allowed_action ?? "").trim(),
         revision_id: String(run.meta?.revision_id ?? "").trim(),
+        last_updated_at: String(run.meta?.updated_at || run.last_updated_at || "").trim(),
       };
     })
     .sort((left, right) => left.display_title.localeCompare(right.display_title) || left.run_id.localeCompare(right.run_id));
@@ -298,9 +412,66 @@ function markdownCell(value) {
     .replace(/\r?\n/g, "<br>");
 }
 
-function operationalList(value, none) {
-  if (!Array.isArray(value) || value.length === 0) return none;
-  return value.map((item) => String(item ?? "").trim()).filter(Boolean).join("\n") || none;
+function localizedOperationalValue(value, pack, fallbackPack, fallbackLocale) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized || normalized === "none") return pack.primary.none;
+  if (fallbackLocale) return normalized;
+  for (const [key, source] of Object.entries(fallbackPack.operationalValues ?? {})) {
+    if (source === normalized) return String(pack.operationalValues?.[key] ?? "").trim() || null;
+  }
+  for (const [key, source] of Object.entries(fallbackPack.primary.actions ?? {})) {
+    if (source === normalized) return String(pack.primary.actions?.[key] ?? "").trim() || null;
+  }
+  for (const [key, source] of Object.entries(fallbackPack.primary.afterApproval ?? {})) {
+    if (source === normalized) return String(pack.primary.afterApproval?.[key] ?? "").trim() || null;
+  }
+  if (fallbackPack.primary.quality === normalized) return String(pack.primary.quality ?? "").trim() || null;
+  return null;
+}
+
+// Free text from a run state is shown only when the presentation locale can render it; callers use
+// this to substitute the deterministic value instead of failing the whole card.
+export function isOperationalValueRenderable(value, { registry, requestedLocale } = {}) {
+  try {
+    const locale = resolvePresentationLocale(registry, requestedLocale);
+    const fallbackLocale = resolvePresentationLocale(registry, registry.fallbackLocale);
+    return Boolean(localizedOperationalValue(value, localePack(registry, locale), localePack(registry, fallbackLocale), locale === fallbackLocale));
+  } catch {
+    return false;
+  }
+}
+
+function localizedOperationalList(value, pack, fallbackPack, fallbackLocale) {
+  if (!Array.isArray(value) || value.length === 0) return pack.primary.none;
+  const localized = value.map((item) => localizedOperationalValue(item, pack, fallbackPack, fallbackLocale));
+  if (localized.some((item) => !item)) return null;
+  return localized.join("\n");
+}
+
+function localizedBlockingCondition(value, pack, fallbackPack, fallbackLocale) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized || normalized === "none") return pack.primary.none;
+  if (/^[A-Za-z0-9_]+$/.test(normalized)) {
+    const reasonKeys = {
+      AGDF_UR_REQUIREMENTS_INCOMPLETE: "blockedUrRequirements",
+      AGDF_PRD_DECISIONS_OPEN: "blockedPrdDecisionsOpen",
+      AGDF_SD_DECISIONS_OPEN: "blockedSdDecisionsOpen",
+      AGDF_SD_TRACEABILITY_INCOMPLETE: "blockedSdTraceability",
+      AGDF_TP_TRACEABILITY_INCOMPLETE: "blockedTpTraceability",
+      AGDF_DECISION_CONTENT_INCOMPLETE: 'blockedDecisionContent',
+      AGDF_CONTROL_FILE_MISSING: "blockedControlMissing",
+      AGDF_ACTIVE_RUN_MISSING: "blockedRunMissing",
+      AGDF_DELIVERY_RELATIONSHIP_MISSING: "blockedRelationshipMissing",
+      AGDF_DELIVERY_RELATIONSHIP_EVIDENCE_MISSING: "blockedRelationshipEvidenceMissing",
+      AGDF_DELIVERY_RELATIONSHIP_CONFLICT: "blockedRelationshipConflict",
+      AGDF_MISSING_EVIDENCE_DECLARED: "blockedEvidenceDeclared",
+      AGDF_RISK_DECLARED: "blockedRiskDeclared",
+    };
+    const explanation = String(pack.operationalValues?.[reasonKeys[normalized]] ?? "").trim();
+    const fallback = String(pack.operationalValues?.blockedUnknown ?? "").trim();
+    return `${explanation || fallback || normalized} (${normalized})`;
+  }
+  return localizedOperationalValue(normalized, pack, fallbackPack, fallbackLocale);
 }
 
 function operationalBreadcrumb(value, labels) {
@@ -332,6 +503,22 @@ export function validateOperationalStatusCardPreconditions(statusCard, {
       locale = "";
     }
     if (!locale) errors.push("locale_unresolved");
+    if (locale) {
+      const labels = localePack(registry, locale).statusCard;
+      for (const key of ["waitingOn", "userTurn", "userInputNeeded", "agentWorking", "agentNext", "noReply"])
+        if (!String(labels?.[key] ?? "").trim()) errors.push(`status_card_${key}_missing`);
+      const fallbackLocale = resolvePresentationLocale(registry, registry.fallbackLocale);
+      if (locale !== fallbackLocale) {
+        const pack = localePack(registry, locale);
+        const fallbackPack = localePack(registry, fallbackLocale);
+        if (!localizedOperationalList(statusCard.allowed_now, pack, fallbackPack, false)) errors.push("allowed_now_unlocalized");
+        if (!localizedOperationalList(statusCard.forbidden_now, pack, fallbackPack, false)) errors.push("forbidden_now_unlocalized");
+        if (!localizedBlockingCondition(statusCard.blocking_condition, pack, fallbackPack, false)) errors.push("blocking_condition_unlocalized");
+        if (statusCard.allowed_after_approval !== "none" && !localizedOperationalValue(statusCard.allowed_after_approval, pack, fallbackPack, false)) errors.push("allowed_after_approval_unlocalized");
+        if (!localizedOperationalValue(statusCard.next_step, pack, fallbackPack, false)) errors.push("next_step_unlocalized");
+        if (!localizedOperationalValue(statusCard.quality_outlook, pack, fallbackPack, false)) errors.push("quality_outlook_unlocalized");
+      }
+    }
   }
   return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
 }
@@ -340,6 +527,8 @@ export function renderOperationalStatusCard(statusCard, {
   registry,
   humanPresentation,
   revisionId = "",
+  executionDisposition = "inspect",
+  qaFollowUp = null,
 } = {}) {
   if (!validateOperationalStatusCardPreconditions(statusCard, { registry, humanPresentation: humanPresentation ?? null }).valid) return null;
   const runId = String(statusCard.run_id ?? "").trim();
@@ -348,25 +537,78 @@ export function renderOperationalStatusCard(statusCard, {
   const locale = resolvePresentationLocale(registry, statusCard.presentation_language);
 
   const pack = localePack(registry, locale);
+  const fallbackLocale = resolvePresentationLocale(registry, registry.fallbackLocale);
+  const fallbackPack = localePack(registry, fallbackLocale);
+  const usesFallbackLocale = locale === fallbackLocale;
   const labels = pack.statusCard;
   const primary = pack.primary;
   const none = primary.none;
   const gateLabel = String(humanPresentation.gateTitle ?? "").trim() || gateTitle(registry, locale, currentGate);
   const runTitle = displaySafeTitle(humanPresentation.runTitle, normalizedRunTitle(runId));
   const breadcrumb = operationalBreadcrumb(statusCard.breadcrumb, labels);
+  const approvalReady = statusCard.interaction_kind === "gate_approval"
+    && statusCard.status === "open"
+    && statusCard.missing_approval === `Approval: ${currentGate}`;
+  const allowedNow = localizedOperationalList(statusCard.allowed_now, pack, fallbackPack, usesFallbackLocale);
+  const forbiddenNow = localizedOperationalList(statusCard.forbidden_now, pack, fallbackPack, usesFallbackLocale);
+  const blockingCondition = localizedBlockingCondition(statusCard.blocking_condition, pack, fallbackPack, usesFallbackLocale);
+  const allowedAfter = statusCard.allowed_after_approval === "none"
+    ? none
+    : localizedOperationalValue(statusCard.allowed_after_approval, pack, fallbackPack, usesFallbackLocale);
+  const nextStep = localizedOperationalValue(statusCard.next_step, pack, fallbackPack, usesFallbackLocale);
+  const qualityOutlook = localizedOperationalValue(statusCard.quality_outlook, pack, fallbackPack, usesFallbackLocale);
+  if (!allowedNow || !forbiddenNow || !blockingCondition || !allowedAfter || !nextStep || !qualityOutlook) return null;
+  const hasBlocker = statusCard.status === "blocked" && statusCard.blocking_condition !== "none";
+  const userMustAct = approvalReady || statusCard.user_action_required === "yes";
+  const agentMustAct = !userMustAct && statusCard.internal_next_step !== "none";
+  const actorRow = approvalReady
+    ? [labels.waitingOn, statusCard.missing_approval]
+    : userMustAct
+      ? [labels.userTurn, statusCard.next_user_gate !== "none" ? statusCard.next_user_gate : nextStep]
+      : agentMustAct
+        ? [executionDisposition === "continue" && statusCard.status === "open" ? labels.agentWorking : labels.agentNext, nextStep]
+        : [labels.noReply, nextStep];
+  const prdReadinessItems = Array.isArray(statusCard.prd_readiness_items) ? statusCard.prd_readiness_items : [];
+  const sdReadinessItems = Array.isArray(statusCard.sd_readiness_items) ? statusCard.sd_readiness_items : [];
+  const traceabilityGaps = Array.isArray(statusCard.traceability_gaps) ? statusCard.traceability_gaps : [];
+  const blockingDetails = hasBlocker && Array.isArray(statusCard.blocking_details)
+    ? statusCard.blocking_details.map((item) => {
+        const code = String(item?.code ?? "").trim();
+        const message = String(item?.message ?? "").trim();
+        const rawNextAction = String(item?.next_step ?? "").trim();
+        const nextActionValue = rawNextAction && rawNextAction !== "none"
+          ? localizedOperationalValue(rawNextAction, pack, fallbackPack, usesFallbackLocale)
+          : null;
+        return [
+          [labels.blockerDetails, `${code ? `${code}: ` : ""}${message}${message ? ` (${labels.sourceWording})` : ""}`],
+          [labels.recovery, nextActionValue || pack.operationalValues.unknownRunAction],
+        ];
+      }).flat()
+    : [];
   const rows = [
     [labels.run, `${runTitle} · \`${runId}\``],
     ...(breadcrumb ? [[labels.breadcrumb, breadcrumb]] : []),
     [labels.status, primary.status[statusCard.status] ?? statusCard.status],
     [labels.gate, `${gateLabel} (\`${currentGate}\`)`],
-    [labels.allowed, operationalList(statusCard.allowed_now, none)],
-    [labels.forbidden, operationalList(statusCard.forbidden_now, none)],
-    [labels.blocked, statusCard.blocking_condition === "none" ? none : statusCard.blocking_condition],
-    [labels.missing, statusCard.missing_approval === "none" ? none : statusCard.missing_approval],
-    [labels.nextGate, statusCard.next_gate_after_approval === "none" ? none : statusCard.next_gate_after_approval],
-    [labels.allowedAfter, statusCard.allowed_after_approval === "none" ? none : statusCard.allowed_after_approval],
-    [labels.step, statusCard.next_step || none],
-    [labels.quality, statusCard.quality_outlook || none],
+    ...(approvalReady
+      ? [[labels.userDecision, `${statusCard.missing_approval} · ${pack.interaction.reviseLabel} · ${pack.interaction.declineLabel}`],
+        [labels.agentAllowed, allowedNow]]
+      : [[labels.allowed, allowedNow]]),
+    [labels.forbidden, forbiddenNow],
+    ...(hasBlocker ? [[labels.blocked, blockingCondition]] : []),
+    ...blockingDetails,
+    ...(qaFollowUp?.reason ? [[labels.qaFollowUp, `${qaFollowUp.reason} (${labels.sourceWording})`]] : []),
+    ...(prdReadinessItems.length ? [[labels.prdReadinessItems, prdReadinessItems.join("\n")]] : []),
+    ...(sdReadinessItems.length ? [[labels.sdReadinessItems, sdReadinessItems.join("\n")]] : []),
+    ...(traceabilityGaps.length ? [[labels.traceabilityGaps, traceabilityGaps.join("\n")]] : []),
+    actorRow,
+    ...((statusCard.evidence ?? []).some(row => row.evidence === "Relationship correction")
+      ? [[labels.maintenance, pack.operationalValues.relationshipCorrected]] : []),
+    ...(!approvalReady ? [[labels.missing, statusCard.missing_approval === "none" ? none : statusCard.missing_approval]] : []),
+    ...(!approvalReady && statusCard.next_gate_after_approval !== "none" ? [[labels.nextGate, statusCard.next_gate_after_approval]] : []),
+    ...(!approvalReady && statusCard.allowed_after_approval !== "none" ? [[labels.allowedAfter, allowedAfter]] : []),
+    ...(statusCard.quality_outlook !== fallbackPack.operationalValues.noAdditionalQualityFollowUp
+      ? [[labels.quality, qualityOutlook]] : []),
   ];
   const markdown = [
     `## ${labels.title}`,
@@ -388,6 +630,109 @@ export function renderOperationalStatusCard(statusCard, {
   });
 }
 
+export function renderRunResolutionCard({ candidates = [], noActiveRun = false, presentationLanguage } = {}, {
+  registry,
+} = {}) {
+  let locale;
+  try {
+    locale = resolvePresentationLocale(registry, presentationLanguage);
+  } catch {
+    return null;
+  }
+  const labels = localePack(registry, locale)?.runResolution;
+  if (!plainObject(labels)) return null;
+  if (noActiveRun) {
+    return Object.freeze({
+      schema_version: "1",
+      semantic_block: "run_resolution",
+      presentation_language: locale,
+      markdown: `## ${labels.noneTitle}\n\n${labels.nonePrompt}`,
+      authorizes: false,
+    });
+  }
+  if (!Array.isArray(candidates) || candidates.length < 2) return null;
+  const orderedCandidates = [...candidates].sort((left, right) => {
+    const leftTime = Date.parse(left.last_updated_at) || 0;
+    const rightTime = Date.parse(right.last_updated_at) || 0;
+    return rightTime - leftTime || left.run_id.localeCompare(right.run_id);
+  });
+  const [recommended, ...alternatives] = orderedCandidates;
+  const renderCandidate = (candidate) => [
+    `- **${markdownCell(candidate.display_title || candidate.run_id)}** · \`${markdownCell(candidate.run_id)}\``,
+    `  - ${labels.gate}: ${markdownCell(candidate.current_gate || "unknown")}`,
+    ...(candidate.last_updated_at ? [`  - ${labels.updated}: ${markdownCell(candidate.last_updated_at)}`] : []),
+    ...(candidate.objective ? [`  - ${labels.objective}: ${markdownCell(candidate.objective)}`] : []),
+  ].join("\n");
+  const markdown = [
+    `## ${labels.title}`,
+    "",
+    `**${labels.latest}:**`,
+    renderCandidate(recommended),
+    ...(alternatives.length ? ["", `**${labels.otherRuns}:**`, ...alternatives.map(renderCandidate)] : []),
+    "",
+    labels.choosePrompt,
+  ].join("\n");
+  return Object.freeze({
+    schema_version: "1",
+    semantic_block: "run_resolution",
+    presentation_language: locale,
+    recommended_run_id: recommended.run_id,
+    markdown,
+    authorizes: false,
+  });
+}
+
+export function renderControlSetupOrientation({ target } = {}, {
+  registry,
+  requestedLocale,
+} = {}) {
+  const normalizedTarget = String(target ?? "").trim();
+  if (!normalizedTarget || /[\r\n\0]/u.test(normalizedTarget)) return null;
+  let locale;
+  try {
+    locale = resolvePresentationLocale(registry, requestedLocale);
+  } catch {
+    return null;
+  }
+  const labels = localePack(registry, locale)?.controlSetup;
+  if (!plainObject(labels)) return null;
+  const required = [
+    "title", "field", "value", "status", "target", "durableScope", "plannedEffect",
+    "excludedAuthority", "nextAction", "replyOptions", "replyOptionsValue", "required", "scopeValue", "effectValue",
+    "excludedValue", "actionValue",
+  ];
+  if (required.some((key) => !String(labels[key] ?? "").trim())) return null;
+  const rows = [
+    [labels.status, labels.required],
+    [labels.target, normalizedTarget],
+    [labels.durableScope, labels.scopeValue],
+    [labels.plannedEffect, labels.effectValue],
+    [labels.excludedAuthority, labels.excludedValue],
+    [labels.nextAction, labels.actionValue],
+    [labels.replyOptions, labels.replyOptionsValue],
+  ];
+  const markdown = [
+    `## ${labels.title}`,
+    "",
+    `| ${labels.field} | ${labels.value} |`,
+    "|---|---|",
+    ...rows.map(([label, value]) => `| ${markdownCell(label)} | ${markdownCell(value)} |`),
+  ].join("\n");
+  return Object.freeze({
+    schema_version: "1",
+    semantic_block: "control_setup",
+    status: "control_setup_required",
+    target: normalizedTarget,
+    durable_scope: ".agdf/control",
+    planned_effect: "create_canonical_control_scaffold",
+    excluded_authority: Object.freeze(["automatic_run_creation", "automatic_ur_persistence", "gate_approval"]),
+    next_action: "authorize_or_cancel",
+    presentation_language: locale,
+    markdown,
+    authorizes: false,
+  });
+}
+
 export function renderTaskTargetOrientation(resolution, {
   registry,
   requestedLocale,
@@ -407,12 +752,7 @@ export function renderTaskTargetOrientation(resolution, {
     : null;
 
   const resolvedReasons = new Set(["explicit_target", "continued_target"]);
-  const unresolvedReasons = new Set([
-    "multiple_plausible_targets",
-    "target_content_mismatch",
-    "target_unavailable",
-    "no_reliable_target",
-  ]);
+  const unresolvedReasons = new Set(TASK_TARGET_UNRESOLVED_REASONS);
 
   if (!["resolved", "unresolved"].includes(resolutionState)) return null;
   if (!workingDirectory || evidenceSources === null) return null;
@@ -422,6 +762,16 @@ export function renderTaskTargetOrientation(resolution, {
     return null;
   }
 
+  const inputError = resolution.input_error;
+  const allowedValues = reasonCode === "target_source_invalid"
+    && plainObject(inputError)
+    && inputError.field === "target_source"
+    && Array.isArray(inputError.allowed_values)
+    && JSON.stringify(inputError.allowed_values) === JSON.stringify(TASK_TARGET_SOURCES)
+    ? TASK_TARGET_SOURCES
+    : null;
+  if (reasonCode === "target_source_invalid" && !allowedValues) return null;
+
   let locale;
   try {
     locale = resolvePresentationLocale(registry, requestedLocale);
@@ -432,9 +782,12 @@ export function renderTaskTargetOrientation(resolution, {
 
   const pack = localePack(registry, locale);
   const labels = pack?.taskTargetResolution;
-  if (!plainObject(labels) || !plainObject(labels.reasonCodes)) return null;
+  if (!plainObject(labels) || !plainObject(labels.reasonCodes) || !plainObject(labels.nextActions)) return null;
+  if (!String(labels.nextActions.examples ?? "").trim() || !String(labels.examplesLabel ?? "").trim()) return null;
   const reason = labels.reasonCodes[reasonCode];
   if (!reason) return null;
+  const localizedNextAction = resolutionState === "unresolved" ? labels.nextActions[reasonCode] : "";
+  if (resolutionState === "unresolved" && !localizedNextAction) return null;
 
   const rows = resolutionState === "resolved"
     ? [
@@ -451,7 +804,9 @@ export function renderTaskTargetOrientation(resolution, {
         [labels.reason, reason],
         [labels.evidenceSources, evidenceSources.join("; ") || labels.none],
         [labels.workingDirectory, workingDirectory],
-        [labels.nextAction, nextAction],
+        ...(allowedValues ? [[labels.allowedValues, allowedValues.join(", ")]] : []),
+        [labels.nextAction, localizedNextAction],
+        [labels.examplesLabel, labels.nextActions.examples],
       ];
 
   const markdown = [
@@ -890,3 +1245,52 @@ export const interactionPresentationConstants = Object.freeze({
   approvalSequence: APPROVAL_SEQUENCE,
   qualityDimensions: QUALITY_DIMENSIONS,
 });
+
+// Presentation only: lifecycle selection and completeness belong to Doctor's canonical inventory.
+export function renderActiveRunInventory(report, registry, language) {
+  const copy = localePack(registry, language).activeRunInventory;
+  if (!copy) throw new Error("active_run_inventory_copy_missing");
+  const { state, active_count: count } = report.inventory;
+  const lines = [state === "absent" ? copy.absentDescription
+    : state === "complete" && count === 0 ? copy.noneDescription
+      : copy.countDescription.replace("{count}", String(count))];
+  if (state === "incomplete") lines.push("", copy.incompleteDescription);
+  if (report.runs.length) lines.push("", ...report.runs.map((run) => `- \`${run.run_id}\``));
+  if (report.findings.length) {
+    const safe = (value) => String(value).replace(/[\r\n`|]/gu, " ");
+    lines.push("", copy.findingsDescription, "",
+      ...report.findings.map((finding) => `- \`${safe(finding.code)}\`${finding.run_id ? ` · \`${safe(finding.run_id)}\`` : ""}`));
+  }
+  return { markdown: lines.join("\n"), authorizes: false };
+}
+
+// Lifecycle observations never act as a gate approval or an implementation grant.
+export function renderSourceRevision(result, registry, language, input = {}) {
+  const copy = localePack(registry, language).sourceRevision;
+  if (!copy) throw Error("source_revision_copy_missing");
+  const outcomes = ["preview", "reopened", "historical", "replayed", "recovered", "recovery_required", "rejected", "not_found"];
+  const outcome = outcomes.includes(result?.outcome) ? result.outcome : "rejected";
+  const safe = value => String(value ?? copy.none).replace(/[\r\n`|]/gu, " ");
+  const row = result?.history?.receipt;
+  const identity = { target: result?.target_id ?? row?.target_id ?? input.target,
+    run: result?.run_id ?? input.runId, operation: result?.operation_id ?? input.operationId,
+    revision: result?.current_revision_id ?? result?.revision_id ?? result?.expected_revision_id ?? input.revisionId };
+  const lines = [`${copy.title}: ${copy[outcome]}`, "", ...Object.entries(identity).map(([key, value]) => `${copy[key]}: ${safe(value)}`)];
+  if (result?.resulting_revision_id || row) lines.push(`${copy.original}: ${safe(result?.resulting_revision_id ?? row.resulting_revision_id)}`);
+  if (result?.impact) lines.push(`${copy.source}: ${safe(result.impact.source_gate)}`,
+    `${copy.retained}: ${safe(result.impact.retained.join(", ") || copy.none)}`,
+    `${copy.superseded}: ${safe(result.impact.superseded.join(", "))}`);
+  if (outcome === "preview" && result.sources && result.impact) {
+    lines.push(`${copy.intent}: ${safe(result.intended_change)}`, `${copy.binding}: ${safe(result.preview_digest)}`,
+      "", copy.sources, ...result.sources.map(source => `- ${safe(source.type)}: ${safe(source.path)} · ${safe(source.digest)}`),
+      "", `${copy.artefacts}: ${safe(result.impact.superseded.join(", "))}`,
+      `${copy.evidence}: ${safe(result.impact.invalidated_steps.join(", "))}`,
+      `${copy.work}: ${copy.retainedWork}`, "", copy.analyses,
+      ...result.impact.analyses.map(analysis => `- ${safe(analysis.type)}: ${copy[analysis.disposition]} · ${safe(analysis.reason)} · ${safe(analysis.path)} · ${safe(analysis.digest)}`));
+  }
+  if (result?.reason) lines.push(`${copy.reason}: ${safe(result.reason)}`);
+  const next = outcome === "preview" ? copy.reviewNext : outcome === "recovery_required" ? copy.recoverNext
+    : ["rejected", "not_found"].includes(outcome) ? copy.refuseNext : copy.readNext;
+  lines.push("", copy.authority, "", `${copy.next}: ${next}`);
+  return { markdown: lines.join("\n"), authorizes: false };
+}

package/runtime/core/lib/mcp-resource-contract.js

@@ -0,0 +1,4 @@
+// Pure resource identities shared by serving and build owners. Importing an
+// address must never load a control-state reader, writer or generated catalog.
+export const COCKPIT_UI_URI = 'ui://agdf/cockpit/v1.html';
+export const DECISION_UI_URI = 'ui://agdf/decision/v1.html';