create-agdf 0.30.0 → 0.31.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/service.js

@@ -1,5 +1,6 @@
 import { baseResult, bindHostAction } from "./result.js";
 import { inspectArtefactRecordingMode } from '../control-state/run-artefact-recording.js';
+import { preparedCommandCall } from '../control-state/prepared-control-calls.js';
 import { inspectProjectState } from './project-state.js';
 import process from "node:process";
 import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
@@ -10,8 +11,9 @@ import { readRuntimeContract, runtimeContractModules } from "../resources/contra
 import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory, renderRunInventory } 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, OPERATION_CONTRACT_MODULES, PRESENTATION_CATALOG_MODULE } from "./contract.js";
+import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, inspectModuleRecoveryCall, OPERATION_CONTRACT_MODULES, PRESENTATION_CATALOG_MODULE } from "./contract.js";
 import { RUN_COMMAND_DESCRIPTORS, operationContract } from '../control-state/run-command-contract.js';
+import { PROPOSAL_COMMAND_KINDS, PROPOSAL_MATERIAL_SLOT } from '../control-state/run-command-schema.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';
@@ -132,6 +134,19 @@ export function createControlInspectService(dependencies = {}) {
       result.diagnostics = [{ code: "inspect_input_invalid", field,
         ...(inputError?.allowedValues?.length ? { allowed_values: [...inputError.allowedValues] } : {}),
       }];
+      if (field === 'module') {
+        const supplied = { operation: rawInput.operation,
+          ...Object.fromEntries([['module', 'contractModule'], ['working_directory', 'workingDirectory'],
+            ['primary_target', 'primaryTarget'], ['target_source', 'targetSource'], ['presentation_language', 'presentationLanguage'],
+            ['run_id', 'runId'], ['expected_revision_id', 'expectedRevisionId'], ['gate', 'gate'], ['target_id', 'targetId']]
+            .filter(([, key]) => rawInput[key] !== undefined).map(([field, key]) => [field, rawInput[key]])) };
+        // Preserve unsupported selectors too, so they prevent a misleading
+        // executable suggestion rather than disappearing from the new lookup.
+        for (const [field, key] of [['presentation_id', 'presentationId'], ['cursor', 'cursor'], ['planning', 'planning'], ['all_active', 'allActive']])
+          if (rawInput[key] !== undefined) supplied[field] = rawInput[key];
+        const next = inspectModuleRecoveryCall(supplied);
+        if (next) result.recovery.next_calls = [next];
+      }
       return bindHostAction(result);
     }
     timing.input_ms = round(milliseconds(started, now()));
@@ -208,7 +223,7 @@ export function createControlInspectService(dependencies = {}) {
             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 });
+            const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentation_language });
             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,
@@ -221,15 +236,27 @@ export function createControlInspectService(dependencies = {}) {
                 next_calls: [{ tool: input.group, kind: input.kind, instruction: contract.planning_capture?.instructions
                   ?? 'Use the confirmed planning scope and original UUID; no Run/revision. Planning never approves a gate. Start a Run only from a deliberately selected complete source.' }] }, presentation: null };
             }
-            if (['agdf_run', 'agdf_project'].includes(input.group) && !input.run_id) return { report: { ...operationContract(input.group, input.kind),
+            if (['agdf_run', 'agdf_project'].includes(input.group) && !input.run_id) {
+              const prepared = preparedCommandCall(input.group, input.kind, { ...input, presentation_language: input.presentation_language,
+                target_id: resolveControlCommandTarget(target.governance_target).target_id });
+              return { report: { ...operationContract(input.group, input.kind),
               binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
-              next_calls: [{ tool: input.group, kind: input.kind, instruction: input.group === 'agdf_project' ? 'Explicit fixed setup only. Use the confirmed existing Git root and one original UUID. No Run/revision, force, repair, install or approval.' : 'Use a new original operation UUID and confirmed title; there is no prior Run/revision.' }] }, presentation: null };
+              prepared_call: prepared, next_calls: prepared?.state === 'ready' ? [prepared.call] : [],
+              next_action: input.group === 'agdf_project' ? 'Explicit fixed setup only. No Run, repair, installation or approval.'
+                : 'Fill the prepared title from the authorized original request, preserving its UUID and target. No prior Run/revision.' }, presentation: null };
+            }
             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 ?? state.current_gate }),
+              prepared_call: preparedCommandCall(input.group, input.kind, { ...input, presentation_language: input.presentation_language, target_id: targetId },
+                { gate: input.gate ?? state.current_gate, recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) }),
               ...(input.kind === 'artefact.record' ? { recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) } : {}),
+              // Revision proposals are staged in their own slot. Offer that staging form with the
+              // revision commands and beside a material.stage form, whose prepared_call uses the gate's slot.
+              ...(PROPOSAL_COMMAND_KINDS.includes(input.kind) || input.kind === 'material.stage' ? { material_call: preparedCommandCall('agdf_record', 'material.stage',
+                { ...input, presentation_language: input.presentation_language, target_id: targetId }, { gate: PROPOSAL_MATERIAL_SLOT }) } : {}),
               ...(input.contract_module === PRESENTATION_CATALOG_MODULE ? {
                 inspect_contract: inspectContractHelp(),
                 presentation_catalog: readPresentationCatalog(target.governance_target, { runId: input.run_id,
@@ -243,7 +270,7 @@ export function createControlInspectService(dependencies = {}) {
                 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 });
+              current: (() => { const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentation_language });
                 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))

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/authoring-text-handoff.js

@@ -0,0 +1,3 @@
+// Shared guidance for passing authored bytes; never an additional file reader,
+// an authoring result or authority to record an artefact.
+export const AUTHORING_TEXT_HANDOFF = 'Pass Markdown as UTF-8 string data, never executable code. Prefer structured tool input. If the host uses JavaScript, author with its file-editing tool and pass a UTF-8 file read as content; never embed the document in backtick literals.';

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/input-resolution.js

@@ -2,7 +2,7 @@ import { CURRENT_LAYOUT } from './run-identity.js';
 // Shared representation, not a file owner or replay ledger. Existing operation
 // families alone validate, persist and recover their versioned records.
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { isAbsolute } from 'node:path';
+import { isAbsolute, posix, win32 } from 'node:path';
 import { canonicalJson, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
 import { runCommandRequestDigest } from './run-command-schema.js';
 import { canonicalizeLanguageTag } from '../interaction-presentation.js';
@@ -28,7 +28,9 @@ export function createInputResolution(original, effective, configuration) {
     operation_id: original.operation_id ?? null, kind: original.command?.kind ?? null,
     fields: Object.fromEntries(paths.filter(path => get(original, path) === undefined && get(effective, path) !== undefined).map(path => [path, get(effective, path)])), configuration };
 }
-export function validInputResolution(value) {
+export function validInputResolution(value, { persisted = false } = {}) {
+  // Stored paths describe the writer's host. Live requests still use the serving host's paths.
+  const absolutePath = persisted ? path => posix.isAbsolute(path) || win32.isAbsolute(path) : isAbsolute;
   if (!exactObject(value, ['schema_version', 'logical_digest', 'effective_digest', 'operation_id', 'kind', 'fields', 'configuration']) || value.schema_version !== 1
     || !(value.operation_id === null || typeof value.operation_id === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value.operation_id))
     || !(value.kind === null || typeof value.kind === 'string' && /^[a-z_]+\.[a-z_]+$/u.test(value.kind) && value.kind.length <= 64)
@@ -36,14 +38,14 @@ export function validInputResolution(value) {
     || Buffer.byteLength(canonicalJson(value)) > 8192 || Object.keys(value.fields).some(key => !paths.includes(key))) return false;
   const f = value.fields, c = value.configuration;
   if (Object.hasOwn(f, 'presentation_language') && !tag(f.presentation_language)
-    || Object.hasOwn(f, 'working_directory') && (typeof f.working_directory !== 'string' || !isAbsolute(f.working_directory) || f.working_directory.length > 4096)
+    || Object.hasOwn(f, 'working_directory') && (typeof f.working_directory !== 'string' || !absolutePath(f.working_directory) || f.working_directory.length > 4096)
     || Object.hasOwn(f, 'schema_version') && f.schema_version !== '1'
     || Object.hasOwn(f, 'assurance') && f.assurance !== 'cooperative_local'
     || Object.hasOwn(f, 'variant') && !['status-card', 'approval-envelope'].includes(f.variant)
     || Object.hasOwn(f, 'command.payload.route') && !['markdown', 'automatic', 'fallback'].includes(f['command.payload.route'])) return false;
   if (!exactObject(c, ['root', 'control', 'config_digest', 'values', 'sources', 'defaults_digest', 'control_layout'])
     || (c.control === 'active' ? c.control_layout !== CURRENT_LAYOUT : c.control_layout !== null)
-    || !(c.root === null || typeof c.root === 'string' && isAbsolute(c.root) && c.root.length <= 4096) || !['inactive', 'active'].includes(c.control)
+    || !(c.root === null || typeof c.root === 'string' && absolutePath(c.root) && c.root.length <= 4096) || !['inactive', 'active'].includes(c.control)
     || !(c.config_digest === null || hash(c.config_digest)) || !hash(c.defaults_digest)
     || !exactObject(c.values, preferenceKeys) || !exactObject(c.sources, preferenceKeys)
     || !tag(c.values.chat_language) || !tag(c.values.artifact_language)
@@ -82,7 +84,7 @@ export function resolutionRecord(record) {
   const { input_resolution: extension, ...body } = record;
   if (!plain(extension)) return null;
   const { record_version, ...resolution } = extension;
-  if (!['string', 'number'].includes(typeof record_version) || !validInputResolution(resolution)) return null;
+  if (!['string', 'number'].includes(typeof record_version) || !validInputResolution(resolution, { persisted: true })) return null;
   // Pending journals retain the owning family's digest (approval/revision have
   // their own domain digest). The committed receipt binds the full command and
   // journal recovery cross-checks both retained resolutions below that owner.

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/material-limits.js

@@ -0,0 +1,4 @@
+// Private transfer limits; direct text is bounded independently from a multipart piece.
+// The existing 64 KiB canonical command budget additionally bounds every JSON request.
+export const MATERIAL_LIMITS = Object.freeze({ inline: 49152, part: 16384, file: 131072, set: 524288, sets: 4, total: 2097152,
+  lifetime: 600000, idle: 120000 });

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/prepared-control-calls.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { canonicalJson, digest } from './approval-command-contract.js';
+import { RUN_COMMAND_DESCRIPTORS, validateRunCommand } from './run-command-schema.js';
+import { closeoutConfirmation } from '../control-evaluation/closeout-readiness.js';
+import { REPORT_DECISION_FORMAT } from '../control-evaluation/report-decision.js';
+import { MATERIAL_LIMITS } from './material-limits.js';
+
+// Call construction only. The existing command/dispatch owners still validate
+// intent, current bindings, review, presentation and every actual mutation.
+export function continueDeliveryCall(input, runId = input.run_id) {
+  return { tool: 'agdf_dispatch', arguments: { presentation_language: input.presentation_language,
+    working_directory: input.working_directory, primary_target: input.primary_target, target_source: input.target_source,
+    skill_id: 'gate-check', run_id: runId, continue_delivery: true } };
+}
+
+// Observation of the original UUID, never a new write or refreshed revision.
+export function originalOperationCall(input) {
+  const kind = input.command?.kind;
+  if (!input.run_id && !input.planning && !['project.initialize', 'run.create'].includes(kind)) return undefined;
+  if (['material.stage', 'planned_material.stage', 'presentation.deliver'].includes(kind)) return undefined;
+  return { tool: 'agdf_inspect', arguments: {
+    presentation_language: input.presentation_language, working_directory: input.working_directory,
+    primary_target: input.primary_target, target_source: input.target_source,
+    operation: 'operation-status', module: input.planning || kind === 'project.initialize' ? `${kind}/${input.operation_id}` : input.operation_id,
+    ...(input.planning ? { planning: input.planning } : input.run_id ? { run_id: input.run_id, expected_revision_id: input.expected_revision_id } : {}),
+  } };
+}
+
+function compatible(schema, value) {
+  if (schema.oneOf || schema.anyOf) return (schema.oneOf ?? schema.anyOf).some(row => compatible(row, value));
+  if (schema.allOf) return schema.allOf.every(row => compatible(row, value));
+  if (schema.additionalProperties === false && value && typeof value === 'object'
+      && Object.keys(value).some(key => !Object.hasOwn(schema.properties ?? {}, key))) return false;
+  return Object.entries(schema.properties ?? {}).every(([key, rule]) => value?.[key] === undefined
+    || (!Object.hasOwn(rule, 'const') || value[key] === rule.const) && (!rule.enum || rule.enum.includes(value[key])));
+}
+
+function missing(schema, value, path) {
+  if (schema.oneOf || schema.anyOf) {
+    const variants = (schema.oneOf ?? schema.anyOf).filter(row => compatible(row, value));
+    return variants.length === 1 ? missing(variants[0], value, path) : [path];
+  }
+  if (schema.allOf) return [...new Set(schema.allOf.flatMap(row => missing(row, value, path)))];
+  if (schema.type === 'array' && Array.isArray(value)) return value.flatMap((row, i) => missing(schema.items, row, `${path}/${i}`));
+  if (schema.type !== 'object') return [];
+  return Object.entries(schema.properties ?? {}).flatMap(([key, rule]) => value?.[key] === undefined
+    ? (schema.required ?? []).includes(key) ? [`${path}/${key}`] : [] : missing(rule, value[key], `${path}/${key}`));
+}
+
+// Authoring gates whose staged source uses another material slot. A Quick Task
+// closes with its mandatory Code Review, so that report is the material it stages.
+const MATERIAL_SLOT_BY_GATE = Object.freeze({ 'Mode/Slice Decision': 'Brownfield Review',
+  'Verified Change Execution': 'Verified Change', 'Quick Task Execution': 'CR' });
+const INTERNAL_STEPS = Object.freeze(['UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']);
+// Reports whose recorded result Core reads with readReportDecision.
+const DECISION_REPORT_SLOTS = new Set(['Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR']);
+
+// Selects the one step.record variant an authoring gate records, so the form's
+// required inputs name concrete fields instead of the ambiguous whole payload.
+function recordingStep(gate) {
+  if (gate === 'UR') return { step: 'ur' };
+  if (['Brownfield Review', 'Mode/Slice Decision'].includes(gate)) return { step: 'route' };
+  if (gate === 'Quick Task Execution') return { step: 'review' };
+  if (INTERNAL_STEPS.includes(gate)) return { step: 'internal', internal_step: gate };
+  return {};
+}
+
+// A restaged OR may have a different material handle but the same command identity.
+function stagedCloseoutOperationId(binding, reportDigest) {
+  const hash = digest(`agdf-staged-closeout/1\0${canonicalJson([binding, reportDigest])}`).slice(7, 39);
+  const variant = (8 | (Number.parseInt(hash[16], 16) & 3)).toString(16);
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-8${hash.slice(13, 16)}-${variant}${hash.slice(17, 20)}-${hash.slice(20)}`;
+}
+
+// `revision` continues an accepted source revision preview: apply keeps the
+// preview's operation UUID, which the proposal binds, and its preview digest.
+export function preparedCommandCall(group, kind, input, { gate, material, recording, presentationId, revision } = {}) {
+  if (!RUN_COMMAND_DESCRIPTORS[kind] || RUN_COMMAND_DESCRIPTORS[kind].group !== group) return undefined;
+  let payload = {}, slot;
+  if (kind === 'material.stage') {
+    slot = MATERIAL_SLOT_BY_GATE[gate] ?? gate ?? 'EVIDENCE';
+    const roles = RUN_COMMAND_DESCRIPTORS[kind].payload_schema.oneOf.find(row => row.properties.action.const === 'put').properties.files.items.properties.slot.enum;
+    if (!roles.includes(slot)) return undefined;
+    payload = { action: 'put', files: [{ slot }] };
+  }
+  if (kind === 'artefact.record') payload = { ...(gate ? { gate } : {}), ...(material ? { material } : {}),
+    ...(recording?.available ? { update_draft: recording.update_draft } : {}) };
+  if (['presentation.prepare', 'presentation.deliver', 'approval.record'].includes(kind)) payload = {
+    ...(gate ? { gate } : {}), ...(presentationId ? { presentation_id: presentationId } : {}),
+    ...(kind === 'presentation.deliver' ? { route: 'automatic' } : {}) };
+  if (kind === 'ur_draft.replace' && material) payload = { source: material };
+  if (kind === 'step.record') payload = { ...(material ? { source: material } : {}), ...recordingStep(gate) };
+  // The proposal reference stays an input: staged material rarely outlives the
+  // person's confirmation, and restaging identical bytes keeps the same digest.
+  if (kind === 'source_revision.apply' && revision) payload = { source_gate: revision.source_gate, preview_digest: revision.preview_digest };
+  const unbound = ['run.create', 'project.initialize'].includes(kind);
+  const binding = { schema_version: '1', presentation_language: input.presentation_language,
+    working_directory: input.working_directory, primary_target: input.primary_target, target_source: input.target_source,
+    target_id: input.target_id, ...(!unbound ? { run_id: input.run_id, expected_revision_id: input.expected_revision_id } : {}),
+    assurance: 'cooperative_local' };
+  const stagedCloseout = kind === 'closeout.record' && material;
+  const operation_id = stagedCloseout ? stagedCloseoutOperationId(binding, material.digest) : revision?.operation_id ?? randomUUID();
+  if (stagedCloseout) payload = { or: material,
+    confirmation: closeoutConfirmation(binding.run_id, binding.expected_revision_id, operation_id, material.digest) };
+  const argumentsValue = { ...binding, operation_id, command: { kind, payload } };
+  const required = missing(RUN_COMMAND_DESCRIPTORS[kind].payload_schema, payload, '/command/payload');
+  const valid = validateRunCommand(group, argumentsValue).length === 0;
+  return { state: valid ? 'ready' : 'requires_author_input', call: { tool: group, arguments: argumentsValue },
+    required_inputs: valid ? [] : required.length ? required : ['/command/payload'], authorizes: false,
+    ...(kind === 'material.stage' ? { content_contract: {
+      encoding: 'UTF-8', max_utf8_bytes_per_file: RUN_COMMAND_DESCRIPTORS[kind].payload_schema.oneOf[0].properties.files.items.properties.content.maxLength,
+      instruction: 'put accepts text up to this UTF-8 limit within the 64 KiB whole JSON request bound; no client hashes or byte counts are needed. If either bound would be exceeded, retain the complete text and use the supplied larger_source_call for multipart; never truncate or shorten approved source to fit.',
+      larger_source_call: { tool: 'agdf_inspect', arguments: { operation: 'operation-contract', module: `${group}/${kind}`,
+        presentation_language: input.presentation_language, working_directory: input.working_directory,
+        primary_target: input.primary_target, target_source: input.target_source,
+        run_id: input.run_id, expected_revision_id: input.expected_revision_id } },
+      // Staged material is private to the serving MCP process and short-lived,
+      // so a recording that waits for a person must not stage first.
+      retention: { idle_ms: MATERIAL_LIMITS.idle, lifetime_ms: MATERIAL_LIMITS.lifetime, scope: 'serving MCP server process',
+        instruction: 'Stage only when every input of the following recording (for example reviewer and review confirmation) is already available. Staged material does not survive a reconnect or a pause beyond idle_ms. After expiry stage the identical bytes again: a form that takes the material reference as an input (closeout, source revision apply) is reused with the new reference, which keeps its UUID and any confirmation valid; otherwise use the recording form returned by the new staging.' },
+      ...(DECISION_REPORT_SLOTS.has(slot) ? { report_decision: REPORT_DECISION_FORMAT } : {}),
+    } } : {}),
+    ...(kind === 'approval.record' && gate ? { contract_call: { tool: 'agdf_inspect', arguments: {
+      operation: 'operation-contract', module: 'agdf_approve/approval.record',
+      presentation_language: input.presentation_language, working_directory: input.working_directory,
+      primary_target: input.primary_target, target_source: input.target_source,
+      run_id: input.run_id, expected_revision_id: input.expected_revision_id, gate,
+    } }, response_contract: {
+      approval_value: `Approval: ${gate}`, exact: true,
+      instruction: 'Only a NEW deliberate reply for this presentation. Put the exact reply alone in response; simulation/reviewer explanation belongs outside response. Never prefix or suffix the approval formula. This value is a format, not a decision or permission. The complete approval form already binds the revision and presentation; fill response without another contract read. If explanatory schema help is needed, copy contract_call exactly; never omit or guess expected_revision_id.' } } : {}),
+    ...(kind === 'source_revision.apply' && revision ? { confirmation_contract: { confirmation_value: revision.confirmation_selector, exact: true,
+      instruction: 'confirmation is only the person\'s NEW deliberate reply with exactly this text. proposal is the reference of the previewed proposal; if its staged material expired, stage the identical bytes again and use the new reference. This form keeps the previewed UUID and digest.' } } : {}),
+    ...(stagedCloseout && valid ? { operation_status_call: originalOperationCall(argumentsValue) } : {}),
+    instruction: stagedCloseout
+      ? 'Invoke the supplied closeout separately. If its effect is uncertain, inspect the original operation first. If material expired and restaging is appropriate, stage the identical OR with the original binding and use the returned form for the same operation and digest.'
+      : 'Fill required_inputs from actual authored content, review or a NEW deliberate reply. Preserve the supplied binding and UUID. Retry an uncertain dispatch with the identical call; each new logical command already has its own supplied UUID; do not regenerate it or put IDs in inputs. This form is not permission or an approval.' };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/presentation-delivery.js

@@ -4,6 +4,7 @@ import { readRun } from './run-state-edits.js';
 import { runSealState } from './run-seal.js';
 import { currentInputResolution } from './input-resolution.js';
 import { assertInputConfigurationCurrent } from '../resources/configuration.js';
+import { preparedCommandCall } from './prepared-control-calls.js';
 
 export const presentationDeliveryKey = input => [input.target_id, input.run_id, input.expected_revision_id,
   input.command?.payload?.presentation_id ?? input.presentation_id ?? input.operation_id].join(':');
@@ -45,7 +46,9 @@ export function createPresentationDelivery({ now = Date.now } = {}) {
       if (row.pending || pendingRuns.has(runKey)) return { ...base, ...failure('busy') };
       const selected = row.selected;
       if (selected?.operation_id === input.operation_id && selected.digest !== base.request_digest) return { ...base, ...failure('operation_payload_conflict') };
-      const emit = (mode, text, historical = false) => ({ ...base, historical_effect: historical, presentation_delivery: {
+      const emit = (mode, text, historical = false) => ({ ...base, historical_effect: historical, next_calls: [],
+        ...(!historical ? { approval_call: preparedCommandCall('agdf_approve', 'approval.record', input,
+          { gate: payload.gate, presentationId: payload.presentation_id }) } : {}), presentation_delivery: {
         delivery_id: selected?.operation_id ?? input.operation_id, mode, text, historical_delivery: historical,
         presentation_id: payload.presentation_id, revision_id: input.expected_revision_id, document_digest: row.result.family_result.document_digest,
         cleanup_state: row.cleanup ?? 'not_required',

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-command-contract.js

@@ -1,3 +1,5 @@
+import { MATERIAL_LIMITS } from './material-limits.js';
+import { AUTHORING_TEXT_HANDOFF } from './authoring-text-handoff.js';
 import { projectMcpInputSchema } from '../mcp-input-schema.js';
 // Compatibility facade: existing exports retain the same schema/validator objects.
 export { RUN_COMMAND_VERSION, RUN_COMMAND_LIMITS, TARGET_SCOPED_COMMAND_KINDS, PLANNING_COMMAND_KINDS, PLANNING_SCOPE_SCHEMA, strictObject, MATERIAL_REFERENCE_SCHEMA, RUN_COMMAND_DESCRIPTORS, RUN_COMMAND_GROUPS, commandGroupSchema, compactCommandSchema, RUN_COMMAND_RESULT_SCHEMA, commandResultSchema, validateRunCommandResult, commandGroupDefinition, schemaDiagnostics, validateRunCommand, runCommandRequestDigest } from './run-command-schema.js';
@@ -7,6 +9,7 @@ import { PRD_DECISION_FORMAT } from '../control-evaluation/prd-readiness.js';
 import { SD_DECISION_FORMAT } from '../control-evaluation/sd-readiness.js';
 import { ACCEPTANCE_CRITERIA_FORMAT, TP_AUTHORING_FORMAT } from '../control-evaluation/traceability-readiness.js';
 import { UX_DECISION_FORMAT } from '../control-evaluation/definition-sources.js';
+import { REPORT_DECISION_FORMAT } from '../control-evaluation/report-decision.js';
 import { REVIEWED_BINDING_FORMAT, REVISION_PROPOSAL_FORMAT } from './recording-formats.js';
 import { relationshipForGate } from '../control-evaluation/delivery-relationships.js';
 import { PREVIEW_REVIEW_FORMAT } from './preview-review.js';
@@ -23,17 +26,20 @@ export function operationContract(group, kind, { gate } = {}) {
       plan_id: 'plan-<planned_ur.create operation_id>', expected_digest: null,
       instructions: 'For a new planned UR, reserve the future planned_ur.create UUID first. Use plan- followed by that exact UUID as planning.plan_id. Begin, append and seal planned_material.stage with the same plan_id and null expected_digest; each material call has its own operation_id. Create with the reserved UUID. Creation source material is the plain canonical UR: omit Planning schema, Planning id and Planning priority lines; the writer adds them from the request. Replacement instead stages the full selected UR with its existing planning metadata. Never use a title/slug as the creation plan_id.',
     } } : {}),
-    ...(['material.stage', 'planned_material.stage'].includes(kind) ? { material_transport: { part_bytes: 16384, file_bytes: 131072, set_bytes: 524288, max_sets: 4,
+    ...(['material.stage', 'planned_material.stage'].includes(kind) ? { material_transport: { inline_file_bytes: MATERIAL_LIMITS.inline, part_bytes: MATERIAL_LIMITS.part, file_bytes: MATERIAL_LIMITS.file, set_bytes: MATERIAL_LIMITS.set, max_sets: MATERIAL_LIMITS.sets,
+      preferred: 'action put with files [{slot,content}] seals exact plain UTF-8 text in one bounded private call; at most 49152 UTF-8 bytes per file within the existing 65536-byte JSON request bound. No byte counts, base64 or transfer choreography are needed. Use recording_calls after sealing. ' + AUTHORING_TEXT_HANDOFF,
       total_bytes: 2097152, lifetime_ms: 600000, idle_ms: 120000, effect: 'private transfer only; no canonical files or gate decision',
       encoding: 'append data is canonical standard base64 (no whitespace) of raw UTF-8 bytes; bytes and offsets count decoded bytes, not characters',
-      replay: 'begin preserves its original UUID; append uses exact offsets/base64 bytes. Seal returns Core identity/digest. Read transfer status after uncertainty; generation loss requires restaging semantic bytes. Preserve the future canonical write UUID.',
+      replay: 'Every logical put/begin/append/seal/status call has its own operation UUID; reuse one UUID only for the identical request after uncertainty. transfer_id, not operation_id, links multipart actions. Seal/put return Core identity/digest. Generation loss requires restaging semantic bytes; preserve the future canonical write UUID.',
       lifecycle: 'A receipt-confirmed canonical commit retires its consumed set; otherwise discard it explicitly or let it expire.' } } : {}),
     internal_result_formats: kind === 'step.record' ? { 'UX Intent Definition': UX_DECISION_FORMAT,
-      reviews: { declaration: '- decision: pass | revise | block | not_applicable', result_scope: 'actual current owner report; no generated judgement or approval' } } : undefined,
+      reviews: { section: REPORT_DECISION_FORMAT.section, declaration: '- decision: pass | revise | block | not_applicable',
+        instruction: REPORT_DECISION_FORMAT.instruction, result_scope: 'actual current owner report; no generated judgement or approval' } } : undefined,
     reviewed_binding_format: kind === 'artefact.record' ? { ...REVIEWED_BINDING_FORMAT, current_relationship: relationshipForGate(gate) ?? null,
       destination_status: gate === 'QA' ? 'pass | revise | block matching the actual QA report' : 'draft' } : undefined,
     proposal_format: kind.startsWith('source_revision.') ? REVISION_PROPOSAL_FORMAT : undefined,
     ...(kind === 'closeout.record' ? { confirmation_format: closeoutConfirmation('{run_id}', '{expected_revision_id}', '{operation_id}', '{or.digest}'),
+      confirmation_binding: 'The confirmation names the operation UUID of the prepared closeout form. Keep using that same form: if the staged OR expired, stage the identical bytes and put the new reference into or; digest and confirmation stay valid. A newly read form has a new UUID and needs a new confirmation.',
       closeout_modes: { quick_task: 'OR-lite: Result, Evidence, Risk, Next Step', verified_change: 'Verified Change Mini-Closeout; retain the same canonical record',
         structured_slice: 'Existing OR-full closeout and its applicable obligations', structured_delivery: 'Existing OR-full closeout and its applicable obligations' } } : {}),
     ...(kind === 'verified_change.record' ? { canonical_receipt_kind: 'step.record', execution: 'Actual edits/tests/Git actions remain external; this writer records their bounded observed result.' } : {}),
@@ -42,7 +48,7 @@ export function operationContract(group, kind, { gate } = {}) {
       priority: ['high', 'normal', 'low'], default_priority: 'normal only on explicit create', source_identity: 'SHA-256 of the whole canonical UR text',
       fields: kind === 'planned_ur.create' ? 'Stage the canonical UR without any Planning schema/id/priority lines. The create writer inserts all three from the request.' : 'Use the selected canonical UR including exactly one initial scalar of each planning metadata field. Planning id remains unchanged on replacement.' },
       authoring_format: UR_AUTHORING_FORMAT } : {}),
-    authorizes: false, ...(!kind.startsWith('planned_ur.') && kind !== 'run.create_from_planned' ? { authoring_format: kind === 'closeout.record' ? { quick_task: QUICK_CLOSEOUT_AUTHORING_FORMAT } : kind === 'artefact.record' || kind === 'presentation.prepare' || kind === 'step.record'
+    authorizes: false, ...(!kind.startsWith('planned_ur.') && kind !== 'run.create_from_planned' ? { authoring_format: kind === 'closeout.record' ? { quick_task: QUICK_CLOSEOUT_AUTHORING_FORMAT } : kind === 'artefact.record' || kind === 'presentation.prepare' || kind === 'step.record' || kind === 'ur_draft.replace'
       ? ({ UR: UR_AUTHORING_FORMAT, PRD: { decisions: PRD_DECISION_FORMAT, criteria: ACCEPTANCE_CRITERIA_FORMAT, preview_review: PREVIEW_REVIEW_FORMAT }, SD: SD_DECISION_FORMAT, TP: TP_AUTHORING_FORMAT }[gate] ?? null) : undefined,
     } : {}),
     presentation_format: kind === 'presentation.prepare' || kind === 'artefact.record' ? {

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-command-schema.js

@@ -1,3 +1,4 @@
+import { MATERIAL_LIMITS } from './material-limits.js';
 import { projectMcpInputSchema } from '../mcp-input-schema.js';
 import { DIGEST_PATTERN, COOPERATIVE_ASSURANCE, canonicalJson, digest } from './approval-command-contract.js';
 import { RUN_ID_PATTERN, REVISION_ID_PATTERN, APPROVAL_GATES } from './run-identity.js';
@@ -23,6 +24,8 @@ const materialSource = { oneOf: [source, MATERIAL_REFERENCE_SCHEMA] };
 const materialSlot = enumeration(['UR', 'PRD', 'SD', 'TP', 'QA', 'OR', 'Verified Change', 'Brownfield Review', 'UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR', 'EVIDENCE']);
 const integer = maximum => ({ type: 'integer', minimum: 0, maximum });
 const materialStage = { oneOf: [
+  strictObject({ action: { const: 'put' }, files: { type: 'array', minItems: 1, maxItems: 4,
+    items: strictObject({ slot: materialSlot, content: { type: 'string', maxLength: MATERIAL_LIMITS.inline, description: 'Plain UTF-8 text, at most 49152 encoded bytes per file; the whole JSON request stays <=65536 bytes. Core computes sizes and digests and seals all files in this one call.' } }) } }),
   strictObject({ action: { const: 'begin' }, files: { type: 'array', minItems: 1, maxItems: 4, items: strictObject({ slot: materialSlot, bytes: integer(131072) }) } }),
   strictObject({ action: { const: 'append' }, transfer_id: identity, file: integer(3), offset: integer(131072),
     data: { type: 'string', maxLength: 21848, contentEncoding: 'base64', description: 'Standard base64 of at most 16384 raw UTF-8 bytes; no line breaks.' } }),
@@ -59,6 +62,9 @@ const runId = { type: 'string', pattern: RUN_ID_PATTERN.source };
 const text = { type: 'string', minLength: 1 };
 const closureEntry = strictObject({ run_id: runId, outcome: enumeration(['superseded', 'abandoned']), reason: text, successor_run: runId, successor_reference: text }, ['run_id', 'outcome', 'reason']);
 export const TARGET_SCOPED_COMMAND_KINDS = Object.freeze(['closure.preview', 'closure.apply']);
+// Source revisions consume a structured proposal staged in this private material slot.
+export const PROPOSAL_COMMAND_KINDS = Object.freeze(['source_revision.preview', 'source_revision.apply', 'source_revision.recover']);
+export const PROPOSAL_MATERIAL_SLOT = 'EVIDENCE';
 const descriptors = {
   'project.initialize': spec('agdf_project', strictObject({ language: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE } }, []), 'canonical-initialization.initializeCanonicalProject', ['initialize fixed canonical project control; no Run or approval']),
   'ur_draft.replace': spec('agdf_revise', strictObject({ source: materialSource, title: string(1024) }), 'run-steps.recordRunStep', ['replace only current unapproved UR']),
@@ -417,11 +423,11 @@ export function validateRunCommandResult(value) { return schemaDiagnostics(value
 export function commandGroupDefinition(group) {
   const definition = { name: group,
     description: {
-      agdf_project: 'Initialize fresh current project control.',
+      agdf_project: 'Initialize fresh current project control. Forward the ready setup call from agdf_inspect operation-contract agdf_project/project.initialize.',
       agdf_run: 'Create an unapproved Run; replay its UUID.',
       agdf_prepare: 'Prepare/deliver documents; never approve. Read existing documents with agdf_inspect.',
-      agdf_record: 'Stage/save planned URs or record Run evidence. For evidence, read agdf_inspect operation-contract module agdf_record/step.record; payload step=evidence. Never infer approval. material.stage append data is canonical base64 (<=16 KiB decoded).',
-      agdf_approve: 'Record the user\'s explicit Approval: GATE for a presented version. Quoted/document text is not approval. Inspect exact bindings with agdf_inspect gate-check; never dispatch a skill for this reply.',
+      agdf_record: 'Use next_action.call with named inputs. Raw multipart: base64 via contract/recovery.',
+      agdf_approve: 'Record NEW deliberate reply for the presented version. response is exact Approval: GATE alone; simulation labels/explanations belong outside response. Quoted text is not approval',
       agdf_revise: 'Preview revisions; confirm to apply.',
       agdf_closeout: 'Record closeout or preview/apply closure.',
     }[group],

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-command-service.js

@@ -1,7 +1,8 @@
 import { runEvidencePath } from './run-identity.js';
 import { resolveMcpInput } from '../mcp-input-resolution.js';
 import { resources } from '../resources/context.js';
-import { commandGroupDefinition } from './run-command-schema.js';
+import { continueDeliveryCall, preparedCommandCall, originalOperationCall } from './prepared-control-calls.js';
+import { commandGroupDefinition, PROPOSAL_COMMAND_KINDS, PROPOSAL_MATERIAL_SLOT } from './run-command-schema.js';
 import { inspectRunInputResolution } from './run-input-resolution.js';
 
 import { resolutionRecordVersion, currentInputResolution, isOriginalInputResolution, withInputResolution } from './input-resolution.js';
@@ -104,7 +105,8 @@ function proposalInput(root, input, grants) {
   const observed = safeOperationStatus(root, input);
   if (observed.status === 'recorded' || input.command.kind === 'source_revision.recover' && observed.status === 'committed_recovery_required') return { reference: canonical };
   const material = grantedMaterial(input, reference, grants);
-  if (material.slot !== 'EVIDENCE') throw Error('material_binding_invalid');
+  if (material.slot !== PROPOSAL_MATERIAL_SLOT) throw Object.assign(Error('material_binding_invalid'), {
+    recovery: `A source revision proposal must be staged in slot ${PROPOSAL_MATERIAL_SLOT}, not ${material.slot}. Stage it with the material_call of operation-contract agdf_revise/${input.command.kind}, then retry with the new reference. No command was dispatched.` });
   return { reference: canonical, material: { path: canonical.path, digest: canonical.digest, content: material.content } };
 }
 export function createRunCommandService({ packageVersion = '0.14.5', enabledGroups = Object.keys(RUN_COMMAND_GROUPS), checkpoint = () => {}, runtimeControl, materialGrants = [], gitObservation, initializationProducer, inputDefaults = resources.defaults } = {}) {
@@ -150,6 +152,7 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
           // The envelope already carries this exact receipt; the family copy only doubled the response.
           family_result: family.receipt && receipt && canonicalJson(family.receipt) === canonicalJson(receipt)
             ? (({ receipt: _receipt, ...rest }) => rest)(family) : family, ...extra };
+        response.operation_status_call = originalOperationCall(input);
         if (['accepted', 'already_applied'].includes(outcome)) {
           const common = { presentation_language: input.presentation_language, working_directory: input.working_directory,
             primary_target: input.primary_target, target_source: input.target_source, target_id: input.target_id };
@@ -164,8 +167,20 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
                 module: 'agdf_prepare/presentation.prepare', run_id, expected_revision_id: response.current.revision_id, gate: 'UR' })];
           }
           if (input.command.kind === 'presentation.prepare' && family.presentation_id && family.revision_id)
-            response.next_calls = [inspect({ operation: 'presentation-document', run_id: input.run_id,
-              expected_revision_id: family.revision_id, gate: family.gate, presentation_id: family.presentation_id })];
+            response.next_calls = response.current.lifecycle === 'active' && response.current.revision_id === family.revision_id
+              ? [preparedCommandCall('agdf_prepare', 'presentation.deliver', { ...input, expected_revision_id: family.revision_id },
+                { gate: family.gate, presentationId: family.presentation_id }).call]
+              : [inspect({ operation: 'presentation-document', run_id: input.run_id,
+                expected_revision_id: family.revision_id, gate: family.gate, presentation_id: family.presentation_id })];
+          // An accepted preview continues with its apply form: same UUID and preview digest,
+          // with the proposal reference and the person's confirmation left as inputs.
+          if (input.command.kind === 'source_revision.preview' && family.preview_digest && family.confirmation_selector)
+            response.recording_calls = [preparedCommandCall('agdf_revise', 'source_revision.apply', input, { revision: {
+              operation_id: input.operation_id, source_gate: input.command.payload.source_gate,
+              preview_digest: family.preview_digest, confirmation_selector: family.confirmation_selector } })];
+          if (!response.historical_effect && response.current.available && response.current.lifecycle === 'active'
+              && ['run.create', 'run.create_from_planned', 'step.record', 'artefact.record', 'ur_draft.replace', 'approval.record'].includes(input.command.kind))
+            response.next_calls = [continueDeliveryCall({ ...input, primary_target: root }, response.current.run_id ?? family.run_id ?? selectedInput.run_id)];
         }
         if (Buffer.byteLength(JSON.stringify(response)) > (input.command.kind === 'project.initialize' ? 16384 : RUN_COMMAND_LIMITS.result_bytes)) return { schema_version: '1', outcome: dispatched ? 'effect_unknown' : 'rejected',
           reason: 'command_result_budget_exceeded', operation_id: input.operation_id, binding: response.binding, authorizes: false,
@@ -217,9 +232,13 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
           const state = inspectCanonicalProject(root, { operationId: input.operation_id });
           if (state.receipt?.operation.operation_id === input.operation_id && state.receipt.operation.request_digest !== requestDigest)
             return result('rejected', 'operation_payload_conflict', {}, { dispatch: 'not_dispatched' });
-          if (state.operation_status === 'recorded' && state.status !== 'pending') return result('already_applied', null, {
-            receipt: state.receipt, historical_effect: true, status: 'unchanged', created_run: false,
-            created_gate_approval: false, next_calls: inspectProjectState(root, input, gitObservation).next_calls });
+          if (state.operation_status === 'recorded' && state.status !== 'pending') {
+            const continuation = inspectProjectState(root, input, gitObservation);
+            return result('already_applied', null, {
+              receipt: state.receipt, historical_effect: true, status: 'unchanged', created_run: false,
+              created_gate_approval: false, next_calls: continuation.next_calls,
+              ...(continuation.recovery_only ? { recovery_only: continuation.recovery_only } : {}) });
+          }
           if (state.status === 'blocked') return result('rejected', state.reason, {}, { dispatch: 'not_dispatched' });
           canonicalInitPlan(payload.language); // Resource/plan failures are known before dispatch.
           if (state.operation?.operation_id === input.operation_id && state.operation.request_digest !== requestDigest)
@@ -235,8 +254,10 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
               afterPublish: () => checkpoint('project_after_publish'), afterReceipt: () => checkpoint('project_after_receipt'),
               beforeMarkerCleanup: () => checkpoint('project_before_marker_cleanup') });
           checkpoint('before_result');
+          const continuation = inspectProjectState(root, input, gitObservation);
           return result(family.historical_effect ? 'already_applied' : 'accepted', null,
-            { ...family, next_calls: inspectProjectState(root, input, gitObservation).next_calls });
+            { ...family, next_calls: continuation.next_calls,
+              ...(continuation.recovery_only ? { recovery_only: continuation.recovery_only } : {}) });
         }
         if (kind === 'run.create') {
           // Preflight only; the writer repeats validation before publication.
@@ -267,6 +288,9 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
             } })).then(family => result(family.outcome, family.reason, family, { runtime_control: true }),
               error => result('effect_unknown', error.message, {}, { runtime_control: true }));
         }
+        // Binding the staged proposal is input validation: a missing or misplaced
+        // proposal is rejected before dispatch, never reported as an unknown effect.
+        const proposal = PROPOSAL_COMMAND_KINDS.includes(kind) ? proposalInput(root, input, materialGrants) : null;
         checkpoint('before_dispatch'); dispatched = true;
         if (kind === 'presentation.prepare') {
           family = withOwnedFileLock(runPath(root, input.run_id), () => {
@@ -290,12 +314,10 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
             resolveMaterial: reference => grantedMaterial(input, reference, materialGrants), gitObservation });
         } else if (kind === 'operation.recover') family = boundedRecover(root, input);
         else if (kind === 'source_revision.preview' || kind === 'source_revision.apply') {
-          const proposal = proposalInput(root, input, materialGrants);
           const revised = { ...bound, sourceGate: payload.source_gate, evidence: proposal.reference.path, previewDigest: payload.preview_digest,
             proposalBinding: proposal.reference, proposalMaterial: proposal.material, confirmation: payload.confirmation, commandContext: context, packageVersion };
           family = kind.endsWith('.apply') ? applySourceRevision(root, revised, { afterWrite: checkpoint }) : previewSourceRevision(root, revised);
         } else if (kind === 'source_revision.recover') {
-          const proposal = proposalInput(root, input, materialGrants);
           family = recoverSourceRevision(root, { ...bound, proposalBinding: proposal.reference, proposalMaterial: proposal.material, evidence: proposal.reference.path, sourceGate: payload.source_gate,
             recoveryRevisionId: payload.recovery_revision_id, pendingDigest: payload.pending_digest });
         } else if (kind === 'prd_revision.reopen') {
@@ -331,7 +353,9 @@ export function createRunCommandService({ packageVersion = '0.14.5', enabledGrou
             operation: 'project-state', primary_target: root, target_source: input.target_source,
             working_directory: input.working_directory, presentation_language: input.presentation_language } }] });
         if (error.message === 'AGDF_OPERATION_PAYLOAD_CONFLICT') return result('rejected', 'operation_payload_conflict');
-        return result(dispatched ? 'effect_unknown' : 'rejected', error.message, {}, { dispatch: dispatched ? 'unknown' : 'not_dispatched' });
+        // A pre-dispatch input error may name its own correction.
+        return result(dispatched ? 'effect_unknown' : 'rejected', error.message, {}, { dispatch: dispatched ? 'unknown' : 'not_dispatched',
+          ...(!dispatched && error.recovery ? { recovery: error.recovery } : {}) });
       }
     });
   };

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-identity.js

@@ -17,6 +17,8 @@ export const creationRunId = operationId => `run-${operationId}`;
 export const CURRENT_LAYOUT = 'run-folders-v1';
 export const CURRENT_RUN_VERSION = 4;
 export const RUN_MODES = Object.freeze(['undecided', 'quick_task', 'verified_change', 'structured_slice', 'structured_delivery', 'block']);
+// The artefact slot each recorded run step writes (internal steps name their own slot).
+export const RUN_STEP_SLOTS = Object.freeze({ ur: 'UR', route: 'Brownfield Review', review: 'CR', evidence: 'EVIDENCE', closeout: 'OR' });
 export function runRelativePath(runId, area = '', name = '') {
   if (!RUN_ID_PATTERN.test(String(runId ?? ''))) throw Error('AGDF_RUN_ID_INVALID');
   if (!['', 'documents', 'evidence', 'control', 'history'].includes(area)) throw Error('AGDF_RUN_PATH_INVALID');

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-inventory-reader.js

@@ -7,8 +7,10 @@ import { discoverRuns } from "./run-state-reader.js";
 import { buildRunInventory } from "./run-inventory.js";
 
 // Feeds the pure inventory from the run discovery of the current read view: each run's parsed text
-// and, when the full parser rejected it, its findings. No run state is read a second time.
-export function readRunInventory(root, { language = "en" } = {}) {
+// and, when the full parser rejected it, its findings. No run state is read a second time. `observe: false`
+// skips the per-run gate observation, which reads registered documents, for a caller that evaluates the
+// runs itself (the companion run view, which reads each run in its own captured snapshot).
+export function readRunInventory(root, { language = "en", observe = true } = {}) {
   if (!existsSync(join(root, '.agdf/control'))) return buildRunInventory(null, { language });
   readControlLayout(root);
   if (!existsSync(join(root, '.agdf/control/runs'))) return buildRunInventory([], { language,
@@ -18,7 +20,7 @@ export function readRunInventory(root, { language = "en" } = {}) {
   const store = discovered.filter((run) => run.run_id === "<repository>");
   const sources = discovered.filter(run => run.run_id !== '<repository>').map(run => {
     const source = { run_id: run.run_id, ...(typeof run.content === 'string' ? { text: run.content } : {}), findings: run.valid ? [] : run.findings };
-    if (run.valid) {
+    if (run.valid && observe) {
       try {
         const state = prepareRunContentState(root, run.content, run.path), decision = transitionDecisionForRunState(state);
         source.observation = { current_gate: decision.current_gate, decision: decision.status, missing: decision.missing_approval,