create-agdf 0.20.1 → 0.30.0

package/runtime/core/lib/control-state/run-store-inspection.js

@@ -1,6 +1,7 @@
 import { lstatSync, readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { doctorRequiredFiles } from "../control-evaluation/required-files.js";
+import { readControlLayout, CURRENT_LAYOUT } from './control-layout.js';
 
 export function canonicalScaffoldRequired(root, path) {
   const error = new Error(
@@ -24,11 +25,12 @@ export function regularFileSnapshot(path) {
   return Object.freeze({ path, dev: stats.dev, ino: stats.ino, content: readFileSync(path) });
 }
 
-export function assertCanonicalRunStore(root) {
+export function assertCanonicalRunStore(root, { historicalRead = false } = {}) {
   const directoryPaths = [
     root,
     join(root, ".agdf"),
     join(root, ".agdf", "control"),
+    join(root, ".agdf", "control", "planned"),
     join(root, ".agdf", "control", "runs"),
   ];
   const directories = [];
@@ -40,10 +42,20 @@ export function assertCanonicalRunStore(root) {
       throw canonicalScaffoldRequired(root, path);
     }
   }
+  // Original creation lookup reads its sealed staged receipt before resolving
+  // today's configuration. This read-only path requires containment, not a
+  // current layout decision.
+  if (!historicalRead) {
+    try { readControlLayout(root); }
+    catch (error) {
+      if (error.message === 'AGDF_CONTROL_PATH_INVALID') throw canonicalScaffoldRequired(root, join(root, '.agdf/control/config.json'));
+      throw error;
+    }
+  }
   const requiredPaths = [...new Set([
     join(".agdf", "control", "config.json"),
     join(".agdf", "control", "README.md"),
-    ...doctorRequiredFiles.filter((path) => !path.endsWith("AGDF_RUN.md")),
+    ...doctorRequiredFiles,
   ])];
   const files = [];
   for (const relativePath of requiredPaths) {

package/runtime/core/lib/control-state/run-verified-change.js

@@ -0,0 +1,81 @@
+import { runDocumentPath, runControlPath } from './run-identity.js';
+import { canonicalJson, digest } from './approval-command-contract.js';
+import { canonicalRunText } from './run-seal.js';
+import { prepareOwnedOutput } from './run-owned-outputs.js';
+import { replaceFirstScalar } from './run-state-edits.js';
+import { prepareRunContentState } from '../control-evaluation/run-state.js';
+import { evaluateVerifiedChange, extractField, parseVerifiedChangePathList, readVerifiedChangeRecord } from '../control-evaluation/verified-change.js';
+import { filled, isPlaceholderValue } from '../control-evaluation/shared.js';
+import { closeoutConfirmation, closeoutContextDigest } from '../control-evaluation/closeout-readiness.js';
+import { currentOwnedMutationClaimPaths } from './control-layout.js';
+
+// These exact transient paths belong to the locks/journal of the active recording
+// owner. Caller paths, foreign locks and arbitrary suffixes are never ignored.
+export function ownedRecordingGitObservation(observation, runId) {
+  const transient = new Set([`.agdf/control/runs/${runId}/RUN_STATE.md.lock`,
+    runControlPath(runId, 'RUN_STEP_PENDING.json')]);
+  return { gitValue: observation?.gitValue, gitPathList(root, args) {
+    const ownClaims = new Set(currentOwnedMutationClaimPaths(root));
+    return observation?.gitPathList?.(root, args)?.filter(p => !transient.has(p) && !ownClaims.has(p)) ?? null;
+  } };
+}
+const invariantFields = ['related_ur', 'escalation_target', 'canonical_owner', 'allowed_source_paths', 'allowed_derived_paths',
+  'prohibited_impacts', 'propagation_command', 'validation_commands', 'baseline_commit', 'baseline_tracked_paths', 'baseline_untracked_paths'];
+const scalar = (text, key, value) => {
+  if ([...text.matchAll(new RegExp(`^- ${key}:.*$`, 'gmu'))].length !== 1) throw Error('verified_change_field_ambiguous');
+  return replaceFirstScalar(text, key, value);
+};
+
+// Domain preparation inside the existing Run transaction owner. Core
+// still evaluates the same compact eligibility rules as the CLI.
+export function prepareVerifiedChangeRecording(root, run, control, before, input, source, gitObservation) {
+  const phase = input.step === 'closeout' ? 'closeout' : input.phase;
+  const route = control.mode_slice_decision.decision;
+  if (control.approvals.get('UR')?.status !== 'approved' || control.meta.lifecycle !== 'active') throw Error('verified_change_not_ready');
+  if (phase === 'eligibility') {
+    if (!['Brownfield Review', 'Mode/Slice Decision', 'Verified Change Execution'].includes(before.current_gate)
+      || control.artefacts.get('Verified Change')?.path) throw Error('verified_change_not_ready');
+  } else if (route !== 'verified_change' || !['Verified Change Execution', 'OR'].includes(before.current_gate)) throw Error('verified_change_not_ready');
+  const observation = ownedRecordingGitObservation(gitObservation, input.runId);
+  const actual = () => ({ head: observation.gitValue?.(root, ['rev-parse', 'HEAD']) ?? null,
+    tracked: observation.gitPathList(root, ['diff', 'HEAD', '--name-only']), untracked: observation.gitPathList(root, ['ls-files', '--others', '--exclude-standard']) });
+  const seen = actual();
+  if (!seen.head || seen.tracked === null || seen.untracked === null) throw Error('verified_change_git_unavailable');
+  const path = `${runDocumentPath(input.runId, '')}/VERIFIED_CHANGE.md`;
+  let content = source.content;
+  if (phase === 'eligibility') {
+    content = scalar(content, 'baseline_commit', seen.head);
+    content = scalar(content, 'baseline_tracked_paths', seen.tracked.join(', ') || 'none');
+    content = scalar(content, 'baseline_untracked_paths', seen.untracked.join(', ') || 'none');
+    if (extractField(content, 'status') !== 'eligible') throw Error('verified_change_status_invalid');
+  } else {
+    const prior = readVerifiedChangeRecord(root, control);
+    if (prior.status !== 'present' || invariantFields.some(key => extractField(prior.content, key) !== extractField(content, key))) throw Error('verified_change_scope_changed');
+    if (phase === 'execution') {
+      if (!['executed', 'escalated'].includes(extractField(content, 'status'))) throw Error('verified_change_status_invalid');
+      const baseline = new Set([...parseVerifiedChangePathList(extractField(prior.content, 'baseline_tracked_paths')),
+        ...parseVerifiedChangePathList(extractField(prior.content, 'baseline_untracked_paths'))]);
+      const changed = [...new Set([...seen.tracked, ...seen.untracked])].filter(p => !baseline.has(p)).sort();
+      content = scalar(content, 'execution_changed_paths', changed.join(', ') || 'none');
+    }
+  }
+  let text = run.content;
+  const hash = digest(canonicalRunText(content)), proposedArtefacts = new Map([[path, { content, digest: hash }]]);
+  const candidate = prepareRunContentState(root, text, run.path, { proposedArtefacts });
+  candidate.artefacts = new Map(candidate.artefacts);
+  candidate.artefacts.set('Verified Change', { path, status: extractField(content, 'status') });
+  const evaluated = evaluateVerifiedChange(root, candidate, { ...observation, proposedArtefacts });
+  if (evaluated.findings.length && evaluated.status !== 'escalated' || phase === 'closeout' && evaluated.status !== 'executed') throw Error('verified_change_validation_failed:' + evaluated.findings.map(f => f.code).join(','));
+  if (phase === 'closeout') {
+    if (before.current_gate !== 'OR' || ['revise', 'block'].includes(control.context_graph?.gate_effect)) throw Error('verified_change_closeout_not_ready');
+    if (!['delivered', 'intentionally_not_delivered', 'residual_risk', 'next_step'].every(key => filled(extractField(content, key)) && !isPlaceholderValue(extractField(content, key)))) throw Error('verified_change_mini_closeout_incomplete');
+    if (input.confirmation !== closeoutConfirmation(input.runId, input.revisionId, input.operationId, hash)) throw Error('confirmation_required');
+    text = replaceFirstScalar(text, 'lifecycle', 'completed');
+  }
+  const record = phase === 'closeout' ? { mode: 'verified_change', verified_change: { path, digest: hash }, lifecycle: 'completed',
+    context_evidence_digest: closeoutContextDigest(content), confirmation_digest: digest(input.confirmation) } : null;
+  // Ignore only the transaction's own new control output when comparing paths.
+  const stable = value => canonicalJson({ ...value, tracked: value.tracked?.filter(p => p !== path), untracked: value.untracked?.filter(p => p !== path) });
+  return { text, content, path, digest: hash, record, outputs: [prepareOwnedOutput(root, input.runId, path, content)],
+    validate() { if (stable(actual()) !== stable(seen)) throw Error('verified_change_git_changed'); } };
+}

package/runtime/core/lib/control-state/run-work-summary-shape.d.ts

@@ -0,0 +1 @@
+export function validWorkSummary(value: unknown, runId: string): boolean;

package/{generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/backlog-summary-shape.js → runtime/core/lib/control-state/run-work-summary-shape.js}

@@ -1,24 +1,14 @@
-import { SUMMARY_KINDS } from '../control-evaluation/backlog-vocabulary.js';
+import { SUMMARY_KINDS } from '../control-evaluation/work-vocabulary.js';
+import { RUN_ID_PATTERN, runDocumentPath, runEvidencePath } from './run-identity.js';
 const exactObject = (v, keys) => !!v && typeof v === 'object' && !Array.isArray(v)
   && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
-export const BACKLOG_SUMMARY_FIELDS = ['schema_version', 'target_id', 'run_id', 'section', 'row_digest', 'revision_id', 'observed_at',
-  'kind', 'phase', 'qa_outcome', 'lifecycle', 'recorded_approvals', 'decisive_obligation', 'open_obligation_count',
-  'display_action', 'sources', 'limitations', 'authorizes'];
-const id = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/u.test(value);
+const id = value => typeof value === 'string' && RUN_ID_PATTERN.test(value);
 const hash = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/u.test(value);
 const text = value => typeof value === 'string' && !value.includes('\0');
 const list = value => Array.isArray(value) && value.every(text);
-const sourcePath = value => typeof value === 'string' && value.startsWith('.agdf/control/artefacts/')
+const sourcePath = (value, runId) => typeof value === 'string'
+  && [runDocumentPath(runId, ''), runEvidencePath(runId, '')].some(prefix => value.startsWith(`${prefix}/`))
   && !/[\\:%?#\0]/u.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
-const sections = ['Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers'];
-
-export function validBacklogSummary(row) {
-  return exactObject(row, BACKLOG_SUMMARY_FIELDS) && row.schema_version === 1 && hash(row.target_id) && id(row.run_id)
-    && sections.includes(row.section) && hash(row.row_digest)
-    && typeof row.revision_id === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(row.revision_id)
-    && text(row.observed_at) && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/u.test(row.observed_at) && Number.isFinite(Date.parse(row.observed_at))
-    && validWorkSummary(row, row.run_id);
-}
 
 export function validWorkSummary(row, runId) {
   if (!row || !id(runId)) return false;
@@ -30,11 +20,9 @@ export function validWorkSummary(row, runId) {
     && (row.decisive_obligation === null || exactObject(row.decisive_obligation, ['id', 'routing_target', 'action', 'source_path'])
       && text(row.decisive_obligation.id) && row.decisive_obligation.id.length <= 128
       && ['UR', 'PRD', 'SD', 'TP', 'CD+Tests', 'evidence_obligation'].includes(row.decisive_obligation.routing_target)
-      && text(row.decisive_obligation.action) && sourcePath(row.decisive_obligation.source_path)
-      && row.decisive_obligation.source_path.startsWith(`.agdf/control/artefacts/${runId}/`))
+      && text(row.decisive_obligation.action) && sourcePath(row.decisive_obligation.source_path, runId))
     && Number.isSafeInteger(row.open_obligation_count) && row.open_obligation_count >= 0 && row.open_obligation_count <= 64
     && text(row.display_action) && Array.isArray(row.sources) && row.sources.length <= 64
-    && row.sources.every(s => exactObject(s, ['path', 'digest', 'state']) && sourcePath(s.path)
-      && s.path.startsWith(`.agdf/control/artefacts/${runId}/`) && hash(s.digest) && s.state === 'available')
+    && row.sources.every(s => exactObject(s, ['path', 'digest', 'state']) && sourcePath(s.path, runId) && hash(s.digest) && s.state === 'available')
     && list(row.limitations) && row.authorizes === false;
 }

package/runtime/core/lib/delivery-continuation/service.js

@@ -1,67 +1,6 @@
-import process from "node:process";
-import { evaluateGateCheck } from "../control-evaluation/gate-check.js";
-import { correctRunRelationship } from "../control-state/run-relationship-correction.js";
-import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
-import { localePack } from "../interaction-presentation.js";
-import { createSkillDispatchFailure, createSkillDispatchService } from "../skill-dispatch/service.js";
+import { createSkillDispatchService } from '../skill-dispatch/service.js';
 
-// Application owner for authorized continuation. Routing itself remains read-only.
-// Neither the initial route nor a correction refusal is emitted until this call returns.
-export function createDeliveryContinuationService(dependencies = {}) {
-  const route = createSkillDispatchService(dependencies);
-  const evaluateGate = dependencies.evaluateGateCheck ?? evaluateGateCheck;
-  const correct = dependencies.correctRunRelationship ?? correctRunRelationship;
-  const now = dependencies.now ?? (() => process.hrtime.bigint());
-  const elapsed = start => Math.round(Math.max(0, Number(now() - start) / 1_000_000) * 1000) / 1000;
-
-  return function executeDeliveryContinuation(rawInput) {
-    const started = now();
-    const initial = route(rawInput);
-    // A successful route supplies the validated intent, target and exact control binding.
-    // Invalid, unresolved, stale-assignment, status and judgement routes cannot mutate.
-    if (rawInput.continueDelivery !== true || initial.outcome !== "control_result"
-        || initial.skill?.dispatch_mode !== "deterministic_control"
-        || initial.target?.resolution_state !== "resolved"
-        || initial.control?.run_id !== rawInput.runId || !initial.control?.revision_id
-        || initial.control.blocking_reason !== "AGDF_DELIVERY_RELATIONSHIP_MISSING") return initial;
-
-    const correctionStarted = now();
-    let correction;
-    const fail = details => createSkillDispatchFailure({
-      skill: initial.skill, runtime: initial.runtime,
-      timing: { ...initial.timing, control_ms: initial.timing.control_ms + elapsed(correctionStarted), total_ms: elapsed(started) },
-      code: DISPATCH_RECOVERY.control_evaluation_failed, details,
-      interactionLocales: rawInput.interactionLocales, presentationLanguage: rawInput.presentationLanguage,
-      renderRecovery: dependencies.renderSkillDispatchRecovery,
-    });
-    try {
-      correction = correct(initial.target.governance_target, {
-        runId: initial.control.run_id, revisionId: initial.control.revision_id,
-      }, { evaluateGateCheck: evaluateGate });
-      if (correction.reason === "correction_commit_unconfirmed") {
-        return fail(`AGDF_CORRECTION_COMMIT_UNCONFIRMED: ${correction.run_id}; committed revision ${correction.revision_id}.`);
-      }
-      if (correction.outcome !== "corrected") {
-        initial.timing.control_ms += elapsed(correctionStarted);
-        initial.timing.total_ms = elapsed(started);
-        return initial;
-      }
-      const correctionMs = elapsed(correctionStarted);
-      // Reuse the resolved target; evaluate the committed run afresh and route exactly once.
-      const freshRoute = createSkillDispatchService({ ...dependencies,
-        resolveTaskTarget: () => initial.target,
-        evaluateGateCheck: (root, selection) => {
-          const report = evaluateGate(root, selection);
-          return { ...report, relationship_correction: { ...correction,
-            message: localePack(rawInput.interactionLocales ?? dependencies.pluginDefinition?.interactionLocales,
-              report.status_card?.presentation_language ?? rawInput.presentationLanguage).operationalValues.relationshipCorrected } };
-        },
-      });
-      const result = freshRoute(rawInput);
-      for (const field of ["input_ms", "target_ms", "control_ms", "render_ms"]) result.timing[field] += initial.timing[field];
-      result.timing.control_ms += correctionMs;
-      result.timing.total_ms = elapsed(started);
-      return result;
-    } catch { return fail(); }
-  };
-}
+// Continuation consumes the same derived current facts as a read-only route.
+// Relationships come from canonical bindings; there is no editable projection
+// for this application layer to repair or synchronize.
+export const createDeliveryContinuationService = dependencies => createSkillDispatchService(dependencies);

package/runtime/core/lib/delivery-path-search/persistence.js

@@ -1,4 +1,9 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { createHash } from 'node:crypto';
+import { runEvidencePath } from '../control-state/run-identity.js';
+import { readSelectedRun } from '../control-state/run-state-reader.js';
+import { runSealState } from '../control-state/run-seal.js';
+import { hasSymlinkComponent } from '../control-state/contained-file.js';
+import { mkdirSync, writeFileSync, readFileSync, lstatSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { validateSearchResult } from "./contracts.js";
 
@@ -17,14 +22,27 @@ export function persistSearchResult(targetDir, result) {
   if (validated.provenance.valid_evaluations < 1) {
     throw new Error("search result requires at least one valid evaluation before persistence");
   }
-  const root = join(targetDir, ".agdf", "control", "artefacts", validated.scope_key);
-  const jsonPath = join(root, "DELIVERY_PATH_SEARCH.json");
-  const markdownPath = join(root, "DELIVERY_PATH_SEARCH.md");
-  mkdirSync(dirname(jsonPath), { recursive: true });
+  const run = readSelectedRun(targetDir, validated.scope_key);
+  if (!run.valid || runSealState(targetDir, run.content).status !== 'valid') throw Error('AGDF_SEARCH_CURRENT_RUN_REQUIRED');
+  const relative = runEvidencePath(run.run_id, '');
+  if (hasSymlinkComponent(targetDir, relative)) throw Error('AGDF_RUN_PATH_INVALID');
+  const root = join(targetDir, relative);
   const safe = safeResult(validated);
-  writeFileSync(jsonPath, `${JSON.stringify(safe, null, 2)}\n`, "utf8");
+  const jsonText = `${JSON.stringify(safe, null, 2)}\n`;
+  const identity = createHash('sha256').update(jsonText).digest('hex');
+  const jsonPath = join(root, `DELIVERY_PATH_SEARCH-${identity}.json`);
+  const markdownPath = join(root, `DELIVERY_PATH_SEARCH-${identity}.md`);
+  mkdirSync(dirname(jsonPath), { recursive: true });
+  if (hasSymlinkComponent(targetDir, relative)) throw Error('AGDF_RUN_PATH_INVALID');
+  const publish = (path, text) => {
+    try { writeFileSync(path, text, { encoding: 'utf8', flag: 'wx' }); }
+    catch (error) {
+      if (error.code !== 'EEXIST' || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink() || readFileSync(path, 'utf8') !== text) throw error;
+    }
+  };
+  publish(jsonPath, jsonText);
   const recommendation = safe.recommendation?.action ?? "No safe recommendation";
-  writeFileSync(markdownPath, [
+  publish(markdownPath, [
     "# Delivery Path Search Decision",
     "",
     `- status: ${safe.status}`,
@@ -46,6 +64,6 @@ export function persistSearchResult(targetDir, result) {
     "",
     "This summary contains model judgements, not measured facts. Canonical AGDF gate-check remains authoritative.",
     "",
-  ].join("\n"), "utf8");
+  ].join("\n"));
   return { jsonPath, markdownPath };
 }

package/runtime/core/lib/delivery-path-search/state-adapter.js

@@ -31,7 +31,7 @@ export function searchInputFromControl(targetDir, options = {}, dependencies = {
   const evaluatedRevision = gate.status_presentation?.revision_id ?? "";
   const runId = metaField(content, "run_id");
   const runRevision = metaField(content, "revision_id");
-  const runGate = metaField(content, "current_gate");
+  const runGate = run.current_gate ?? "";
   let inputFailureCode = "";
   if (!content || run.resolution_error) inputFailureCode = "canonical_control_unavailable";
   else if (!evaluatedRunId || !evaluatedRevision) inputFailureCode = "canonical_snapshot_identity_missing";

package/runtime/core/lib/index.js

@@ -1,14 +1,22 @@
 import { resources } from "./resources/context.js";
-import { readRuntimeContract, readSkillRuntimeContracts } from "./resources/contracts.js";
+import { readRuntimeContract, readSkillRuntimeContracts, runtimeContractModules } from "./resources/contracts.js";
 import { createDeliveryContinuationService } from "./delivery-continuation/service.js";
 import { createControlInspectService } from "./control-inspect/service.js";
 import { createRunCommandService } from "./control-state/run-command-service.js";
+import { createRunMaterialStore } from './control-state/run-material.js';
+import { evaluateGateCheck } from './control-evaluation/gate-check.js';
+import { evaluateDoctor } from './control-evaluation/doctor.js';
 export { createResourceContext, resources } from "./resources/context.js";
 export function createCoreServices({ resources: context = resources, observers = {}, runtimeBinding } = {}) {
-  const contracts = { readRuntimeContract: module => readRuntimeContract(module, { context }), readSkillRuntimeContracts: skill => readSkillRuntimeContracts(skill, { context }) };
-  return Object.freeze({ ...contracts, resources: context, runtimeBinding,
-    dispatch: createDeliveryContinuationService({ ...observers, ...contracts, pluginDefinition: context.pluginDefinition }),
-    inspect: createControlInspectService({ ...observers, ...contracts }),
-    command: createRunCommandService({ packageVersion: context.pluginDefinition.version, enabledGroups: observers.commandGroups, runtimeControl: observers.runtimeControl }),
+  const contracts = { runtimeContractModules: () => runtimeContractModules(context.pluginDefinition), readRuntimeContract: module => readRuntimeContract(module, { context }), readSkillRuntimeContracts: skill => readSkillRuntimeContracts(skill, { context }) };
+  const material = createRunMaterialStore();
+  const reads = observers.gitObservation ? { ...observers,
+    evaluateGateCheck: observers.evaluateGateCheck ?? ((root, selection) => evaluateGateCheck(root, selection, observers.gitObservation)),
+    evaluateDoctor: observers.evaluateDoctor ?? ((root, selection) => evaluateDoctor(root, selection, observers.gitObservation)),
+  } : observers;
+  return Object.freeze({ ...contracts, resources: context, runtimeBinding, material,
+    dispatch: createDeliveryContinuationService({ ...reads, ...contracts, pluginDefinition: context.pluginDefinition }),
+    inspect: createControlInspectService({ ...reads, ...contracts }),
+    command: createRunCommandService({ inputDefaults: context.defaults, packageVersion: context.pluginDefinition.version, enabledGroups: observers.commandGroups, runtimeControl: observers.runtimeControl, materialGrants: observers.materialGrants, gitObservation: observers.gitObservation, initializationProducer: observers.runtimeEvidence?.runtime_digest }),
   });
 }

package/runtime/core/lib/interaction-catalog.js

@@ -9,8 +9,8 @@ function freeze(value) {
 }
 export const INSTALL_SETUP_STATES = freeze({
   cancelled: { result: "cancelled", actions: ["cancelled"] },
-  control_migration_required: { result: "partial", actions: ["migrate_control"] },
-  control_repair_required: { result: "partial", actions: ["repair_control"] },
+  control_unsupported: { result: "partial", actions: ["inspect_control"] },
+  control_repair_required: { result: "partial", actions: ["inspect_control"] },
   plugin_ready_mcp_absent: { result: "success", actions: ["restart_host"] },
   plugin_ready_mcp_in_plugin: { result: "success", actions: ["restart_host"] },
   mcp_ready_hook_review_required: { result: "partial", actions: ["review_codex_hook"] },
@@ -58,7 +58,7 @@ export const INSTALL_ACTIONS = freeze([...new Set(Object.values(INSTALL_SETUP_ST
 export const DISPATCH_RECOVERY_CODES = freeze([
   "target_evaluation_failed", "target_presentation_failed", "control_evaluation_failed",
   "control_presentation_failed", "runtime_contracts_unavailable", "runtime_evidence_invalid",
-  "internal_failure", "output_too_large", "intake_run_collision", "intake_scaffold_required",
+  "internal_failure", "output_too_large", "intake_run_collision", "intake_scaffold_required", "intake_run_id_invalid",
   "run_assignment_inventory_invalid", "prd_authoring_inputs_invalid", "sd_authoring_inputs_invalid", "tp_authoring_inputs_invalid",
   "AGDF_ARTEFACT_TEMPLATE_UNSUPPORTED", "AGDF_ARTEFACT_TEMPLATE_ROOT_UNAVAILABLE",
   "AGDF_ARTEFACT_TEMPLATE_UNAVAILABLE", "AGDF_ARTEFACT_TEMPLATE_UNSAFE",

package/runtime/core/lib/interaction-presentation.js

@@ -1,4 +1,5 @@
 import { RUN_ID_PATTERN } from "./control-state/run-identity.js";
+import { normalizedRunTitle, runInventoryHistoryLine } from "./control-state/run-inventory.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";
 
@@ -233,13 +234,7 @@ function section(content, heading) {
   return content.match(new RegExp(`(?:^|\\n)## ${escaped}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`))?.[1]?.trim() ?? "";
 }
 
-export function normalizedRunTitle(runId) {
-  const words = String(runId ?? "")
-    .replace(/[._-]+/g, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-  return words ? words.replace(/\b\p{L}/gu, (letter) => letter.toUpperCase()) : "AGDF run";
-}
+export { normalizedRunTitle };
 
 export function resolveHumanRunTitle({ currentArtefactHeading, urHeading, runContent, runId }) {
   const objective = section(String(runContent ?? ""), "Objective").split(/\r?\n/).map(stripMarkdown).find(Boolean) ?? "";
@@ -266,7 +261,7 @@ export function buildRunCandidates(runs) {
   return [...(runs ?? [])]
     .filter((run) => run?.valid && run?.meta?.lifecycle === "active" && typeof run.run_id === "string")
     .map((run) => {
-      const currentGate = stripMarkdown(run.control_state?.current_gate || run.meta?.current_gate || "unknown") || "unknown";
+      const currentGate = stripMarkdown(run.control_state?.current_gate || "unknown") || "unknown";
       const title = resolveHumanRunTitle({
         currentArtefactHeading: run.current_artefact_heading,
         urHeading: run.ur_heading,
@@ -278,7 +273,7 @@ export function buildRunCandidates(runs) {
         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",
+        decision: String(run.control_state?.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(),
@@ -301,7 +296,8 @@ export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] }
   const requested = normalizeReconciliationText(scopeKey || requestText);
   if (!requested) return Object.freeze({ outcome: "match_uncertain", matches: [], reason: "scope_input_missing" });
   const matches = [...(runs ?? [])]
-    .filter((run) => run?.valid && ["active", "completed"].includes(run?.meta?.lifecycle) && typeof run.run_id === "string")
+    // A superseded or abandoned Run is history like a completed one: it can match, never as active work.
+    .filter((run) => run?.valid && ["active", "completed", "superseded", "abandoned"].includes(run?.meta?.lifecycle) && typeof run.run_id === "string")
     .filter((run) => {
       const keys = [run.scope_key, run.display_title, run.current_artefact_heading, run.ur_heading]
         .map(normalizeReconciliationText)
@@ -312,7 +308,7 @@ export function reconcileRunScope({ requestText = "", scopeKey = "", runs = [] }
       run_id: run.run_id,
       lifecycle: run.meta.lifecycle,
       display_title: displaySafeTitle(run.display_title || run.ur_heading || run.run_id, normalizedRunTitle(run.run_id)),
-      current_gate: run.control_state?.current_gate || run.meta?.current_gate || "unknown",
+      current_gate: run.control_state?.current_gate || "unknown",
     }))
     .sort((left, right) => left.run_id.localeCompare(right.run_id));
   if (matches.length !== 1) return Object.freeze({ outcome: matches.length ? "match_uncertain" : "no_match", matches, reason: matches.length > 1 ? "multiple_exact_matches" : "no_exact_match" });
@@ -409,7 +405,7 @@ function markdownCell(value) {
     .replaceAll("&", "&")
     .replaceAll("<", "&lt;")
     .replaceAll(">", "&gt;")
-    .replace(/\r?\n/g, "<br>");
+    .replace(/\r\n?|\n/g, " · ");
 }
 
 function localizedOperationalValue(value, pack, fallbackPack, fallbackLocale) {
@@ -1264,6 +1260,27 @@ export function renderActiveRunInventory(report, registry, language) {
   return { markdown: lines.join("\n"), authorizes: false };
 }
 
+// The shared run inventory: active and invalid runs by attention, history as counts. Classes rest
+// on stored state; each line carries its basis so no reader mistakes them for a live evaluation.
+export function renderRunInventory(inventory, registry, language) {
+  const copy = localePack(registry, language).activeRunInventory;
+  if (!copy) throw new Error("active_run_inventory_copy_missing");
+  const safe = (value) => String(value ?? "").replace(/[\r\n`|]/gu, " ").replace(/\*\*/gu, "");
+  // Authored titles are untrusted text: escape every Markdown metacharacter.
+  const text = (value) => safe(value).replace(/[\\[\]()<>*_#!~]/gu, (char) => `\\${char}`);
+  const open =inventory.runs.filter((run) => !run.valid || run.lifecycle === "active");
+  const lines = [inventory.state === "absent" ? copy.absentDescription
+    : inventory.state === "complete" && open.length === 0 ? copy.noneDescription
+      : copy.countDescription.replace("{count}", String(inventory.counts.lifecycle.active))];
+  if (inventory.state === "incomplete") lines.push("", copy.incompleteDescription);
+  if (open.length) lines.push("", ...open.map((run) => `- **${text(run.title)}** · \`${safe(run.run_id)}\` · ${safe(run.current_gate ?? "?")} · ${safe(run.attention.label)} · ${safe(run.basis)}`));
+  if (inventory.state !== "absent") lines.push("", runInventoryHistoryLine(inventory.counts.lifecycle, language));
+  const findings = [...(inventory.findings ?? []).map((finding) => `- \`${safe(finding.code)}\``),
+    ...inventory.runs.flatMap((run) => run.findings.map((finding) => `- \`${safe(finding.code)}\` · \`${safe(run.run_id)}\` · ${safe(finding.next_step)}`))];
+  if (findings.length) lines.push("", copy.findingsDescription, "", ...findings);
+  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;
@@ -1281,6 +1298,7 @@ export function renderSourceRevision(result, registry, language, input = {}) {
     `${copy.retained}: ${safe(result.impact.retained.join(", ") || copy.none)}`,
     `${copy.superseded}: ${safe(result.impact.superseded.join(", "))}`);
   if (outcome === "preview" && result.sources && result.impact) {
+    if (result.confirmation_selector) lines.push(`--confirmation: ${safe(result.confirmation_selector)}`);
     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(", "))}`,

package/runtime/core/lib/mcp-input-hints.js

@@ -0,0 +1,46 @@
+import { isAbsolute } from 'node:path';
+import { CONTROL_INSPECT_FUNCTION_DEFINITION, inspectInputValidationHint } from './control-inspect/contract.js';
+import { RUN_COMMAND_DESCRIPTORS, RUN_COMMAND_GROUPS, PLANNING_COMMAND_KINDS, TARGET_SCOPED_COMMAND_KINDS, schemaDiagnostics } from './control-state/run-command-schema.js';
+import { RUN_ID_PATTERN } from './control-state/run-identity.js';
+
+// Presentation only: never repairs an argument or decides permission. The SDK
+// and the canonical Core owners still validate the original request unchanged.
+export function mcpInputValidationHint(name, input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return '';
+  const messages = [];
+  if (name === 'agdf_inspect') {
+    if (input.operation === 'status') messages.push('Run status uses agdf_inspect operation gate-check. status is invalid; never dispatch a skill for a read.');
+    const hint = inspectInputValidationHint(input);
+    if (hint) messages.push(hint);
+    if (['status', 'gate-check', 'presentation-document', 'presentation-preview'].includes(input.operation)) {
+      // A new *read* suggestion, not a repaired/replayed original request. Copy
+      // only explicit locators; never infer a target, select a Run, refresh a
+      // write revision, fabricate a presentation ID or invoke a tool here.
+      const keys = ['working_directory', 'primary_target', 'target_source', 'run_id'];
+      const fields = CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema.properties;
+      if (keys.every(key => Object.hasOwn(input, key) && !schemaDiagnostics(input[key], fields[key]).length)
+        && isAbsolute(input.working_directory) && isAbsolute(input.primary_target)
+        && (input.presentation_language === undefined || !schemaDiagnostics(input.presentation_language, fields.presentation_language).length)) {
+        const args = { operation: 'gate-check', ...Object.fromEntries(keys.map(key => [key, input[key]])),
+          ...(input.presentation_language === undefined ? {} : { presentation_language: input.presentation_language }) };
+        const correction = ` Next read-only call (preserve the requested document selection): ${JSON.stringify({ tool: 'agdf_inspect', arguments: args })}`;
+        if (messages.join(' ').length + correction.length <= 768) return messages.join(' ') + correction;
+      }
+    }
+  } else if (name === 'agdf_dispatch' || Object.hasOwn(RUN_COMMAND_GROUPS, name)) {
+    for (const key of name === 'agdf_dispatch' ? ['skill_id'] : ['command', 'operation_id', 'target_id', 'primary_target', 'target_source'])
+      if (!Object.hasOwn(input, key)) messages.push(`Supply ${key}.`);
+    const kind = input.command?.kind, descriptor = RUN_COMMAND_DESCRIPTORS[kind];
+    if (descriptor?.group === name) {
+      if (!['project.initialize', 'run.create', ...PLANNING_COMMAND_KINDS, ...TARGET_SCOPED_COMMAND_KINDS].includes(kind))
+        for (const key of ['run_id', 'expected_revision_id']) if (!Object.hasOwn(input, key)) messages.push(`Supply ${key} for ${kind}.`);
+      if (PLANNING_COMMAND_KINDS.includes(kind) && !input.planning) messages.push(`Supply planning for ${kind}; no Run/revision.`);
+      messages.push(`Read agdf_inspect operation-contract module ${name}/${kind} for this payload. Preserve the original operation UUID and requested revision.`);
+    }
+  } else return '';
+  if (Object.hasOwn(input, 'run_id') && !RUN_ID_PATTERN.test(input.run_id))
+    messages.push('run_id must match ^[a-z0-9][a-z0-9._-]{0,127}$. Select the canonical Run ID from the request or confirmed inventory; do not guess another Run.');
+  if (Object.hasOwn(input, 'primary_target') !== Object.hasOwn(input, 'target_source'))
+    messages.push('Supply primary_target and target_source together from the confirmed task target; working_directory alone is not target authority.');
+  return messages.join(' ').slice(0, 768);
+}

package/runtime/core/lib/mcp-input-resolution.js

@@ -0,0 +1,98 @@
+import { isAbsolute, relative } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { resolveTaskTarget } from './task-target-resolution.js';
+import { COOPERATIVE_ASSURANCE, resolveControlCommandTarget } from './control-state/approval-command-contract.js';
+import { schemaDiagnostics, RUN_COMMAND_VERSION } from './control-state/run-command-schema.js';
+import { resolveConfiguration } from './resources/configuration.js';
+import { createInputResolution, restoreResolvedInput, validInputResolution } from './control-state/input-resolution.js';
+import { canonicalizeLanguageTag } from './interaction-presentation.js';
+import { validExecutionFacts } from './mcp-tool-errors.js';
+
+function reject(code, field) {
+  return Object.assign(Error(code), { code, facts: { code, dispatch: 'not_dispatched', ...(field ? { field } : {}) } });
+}
+// Called only by the serving adapter. Context and original-operation observations
+// are injected privately; neither can be supplied in public tool arguments.
+export function resolveMcpInput(definition, original, { defaults, executionContext, runtimeRoots = [], lookupOriginal = () => null } = {}) {
+  const diagnostics = schemaDiagnostics(original, definition.inputSchema);
+  if (diagnostics.length) {
+    const code = definition.name === 'agdf_inspect' ? 'inspect_input_invalid' : definition.name === 'agdf_dispatch' ? 'dispatch_input_invalid' : 'command_schema_invalid';
+    const field = diagnostics[0].path.match(/^\$\.([a-z_]+)$/u)?.[1];
+    throw reject(code, field && validExecutionFacts({ code, dispatch: 'not_dispatched', field }) ? field : undefined);
+  }
+  let effective = structuredClone(original);
+  if (effective.working_directory === undefined) {
+    if (executionContext?.source !== 'task_execution' || typeof executionContext.invocation_id !== 'string' || !executionContext.invocation_id
+      || !isAbsolute(executionContext.working_directory ?? '')) throw reject('working_directory_required', 'working_directory');
+    let directory;
+    try {
+      directory = realpathSync(executionContext.working_directory);
+      if (!statSync(directory).isDirectory() || runtimeRoots.some(root => {
+        const path = relative(realpathSync(root), directory); return path === '' || !path.startsWith('..') && !isAbsolute(path);
+      })) throw Error();
+    } catch { throw reject('working_directory_required', 'working_directory'); }
+    effective.working_directory = directory;
+  }
+  if (!isAbsolute(effective.working_directory)) throw reject('working_directory_required', 'working_directory');
+  let root = null;
+  if (effective.target_source !== undefined || effective.primary_target !== undefined) {
+    const target = resolveTaskTarget({ workingDirectory: effective.working_directory, targetSource: effective.target_source, primaryTarget: effective.primary_target });
+    if (target.resolution_state !== 'resolved') {
+      if (effective.command) throw reject('target_unresolved');
+      // Read/dispatch retain the Core's existing unresolved-target result plane.
+      // An unconfirmed target cannot supply project settings.
+    } else root = target.governance_target;
+    if (effective.command && effective.target_id !== undefined && resolveControlCommandTarget(root).target_id !== effective.target_id) throw reject('target_binding_mismatch');
+  }
+  let readLocator;
+  if (root && effective.operation === 'operation-status') {
+    const id = effective.module?.split('/').at(-1);
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(id ?? '')) readLocator = {
+      ...effective, operation_id: id, target_id: resolveControlCommandTarget(root).target_id,
+      command: { kind: ['project.initialize', 'planned_ur.create', 'planned_ur.replace', 'run.create_from_planned'].includes(effective.module?.split('/')[0])
+        ? effective.module.split('/')[0] : effective.run_id ? 'status.inspect' : 'run.create' },
+    };
+  } else if (root && ['presentation-document', 'presentation-preview'].includes(effective.operation)) readLocator = {
+    ...effective, operation_id: effective.presentation_id, command: { kind: 'presentation.prepare' },
+  };
+  const previous = root && (effective.operation_id || readLocator) ? lookupOriginal(root, readLocator ?? effective) : null;
+  if (readLocator && previous?.resolution) {
+    const c = previous.resolution.configuration;
+    if (c.root !== root) throw reject('target_binding_mismatch');
+    effective.presentation_language ??= previous.resolution.fields.presentation_language ?? c.values.chat_language;
+    const configuration = original.presentation_language === undefined ? c : { ...c,
+      values: { ...c.values, chat_language: canonicalizeLanguageTag(original.presentation_language) }, sources: { ...c.sources, chat_language: { kind: 'explicit' } } };
+    return { arguments: effective, resolution: createInputResolution(original, effective, configuration), original: true };
+  }
+  if (readLocator && previous?.known) throw reject('original_operation_unconfirmed');
+  if (!readLocator && previous?.resolution) {
+    if (['operation.recover', 'source_revision.recover'].includes(effective.command?.kind)) {
+      const c = previous.resolution;
+      for (const key of ['presentation_language', 'working_directory', 'schema_version', 'assurance']) effective[key] ??= c.fields[key];
+      effective.presentation_language ??= c.configuration.values.chat_language;
+      effective.schema_version ??= RUN_COMMAND_VERSION;
+      effective.assurance ??= COOPERATIVE_ASSURANCE.lane;
+      const resolution = createInputResolution(original, effective, c.configuration);
+      if (!validInputResolution(resolution)) throw reject('command_schema_invalid');
+      return { arguments: effective, resolution, original: true };
+    }
+    try { effective = restoreResolvedInput(original, previous.resolution); }
+    catch { throw reject('operation_payload_conflict'); }
+    return { arguments: effective, resolution: previous.resolution, original: true };
+  }
+  if (!readLocator && previous?.known) throw reject('original_operation_unconfirmed');
+  const explicit = { ...(original.presentation_language === undefined ? {} : { chat_language: original.presentation_language }),
+    ...(original.command?.kind === 'presentation.deliver' && original.command.payload.route !== undefined ? { presentation_route: original.command.payload.route } : {}),
+    ...(original.operation === 'gate-check' && original.variant !== undefined ? { gate_check_variant: original.variant } : {}) };
+  const configuration = resolveConfiguration(root, defaults, explicit);
+  effective.presentation_language ??= configuration.values.chat_language;
+  if (effective.command) {
+    effective.schema_version ??= RUN_COMMAND_VERSION;
+    effective.assurance ??= COOPERATIVE_ASSURANCE.lane;
+    if (effective.command.kind === 'presentation.deliver') effective.command.payload.route ??= configuration.values.presentation_route;
+  }
+  if (effective.operation === 'gate-check' && configuration.values.gate_check_variant !== null) effective.variant ??= configuration.values.gate_check_variant;
+  const resolution = createInputResolution(original, effective, configuration);
+  if (!validInputResolution(resolution)) throw reject('command_schema_invalid');
+  return { arguments: effective, resolution, original: false };
+}