create-agdf 0.14.5 → 0.20.0

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

@@ -0,0 +1,299 @@
+import { isAbsolute } from "node:path";
+import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from "../control-state/run-identity.js";
+import { ARTIFACT_READINESS_GATES } from "./artifact-readiness.js";
+import { RUN_COMMAND_GROUPS } from '../control-state/run-command-contract.js';
+import { APPROVAL_GATES } from '../control-state/run-identity.js';
+import {
+  PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE,
+  canonicalizeLanguageTag,
+  resolvePresentationLocale,
+} from "../interaction-presentation.js";
+import { normalizeTaskTargetSource, TASK_TARGET_SOURCES } from "../task-target-resolution.js";
+import { SKILL_DISPATCH_MAX_OUTPUT_BYTES, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
+import { ALL_ACTIVE_OPERATIONS, VARIANT_OPERATION, MODULE_OPERATION, CONTROL_INSPECT_OPERATIONS, GATE_CHECK_VARIANTS, ReadSelectionError, validateReadSelection } from "./selection.js";
+
+export const CONTROL_INSPECT_SCHEMA_VERSION = "1";
+export const CONTROL_INSPECT_CONTRACT_VERSION = 1;
+// Every byte of this definition is loaded into every session on every host (SDD-005).
+export const CONTROL_INSPECT_MAX_DEFINITION_BYTES = 5000;
+export const OPERATION_CONTRACT_MODULES = Object.freeze(Object.entries(RUN_COMMAND_GROUPS)
+  .flatMap(([group, kinds]) => kinds.map(kind => `${group}/${kind}`)));
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+// One field model supplies discovery, applicability guards and on-demand help.
+export const PRESENTATION_OPERATIONS = Object.freeze(['presentation-document', 'presentation-preview']);
+export const BOUND_INSPECT_OPERATIONS = Object.freeze(['artifact-readiness', 'operation-contract', 'operation-status', 'native-qualification', ...PRESENTATION_OPERATIONS, 'runtime-generations']);
+export const PRESENTATION_CATALOG_MODULE = 'agdf_prepare/presentation.prepare';
+const uuidSchema = { type: 'string', pattern: REVISION_ID_PATTERN.source };
+const cursorSchema = { type: 'string', maxLength: 80, pattern: '^[0-9a-f]{64}:(?:0|[1-9][0-9]{0,6})$' };
+const fieldModel = {
+  operation: { help: 'Read-only operation; requirements below. Reads never prepare or approve a gate.', schema: { enum: [...CONTROL_INSPECT_OPERATIONS] }, description: 'Read action.' },
+  presentation_language: { help: 'Required BCP47 tag; valid unsupported languages use the complete English pack.', schema: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE }, description: 'Reply BCP47 tag.' },
+  working_directory: { help: 'Absolute execution context; it does not select a target.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Absolute context; not target authority.' },
+  target_source: { help: 'explicit_target: directly specified target; continued_target: confirmed continuation; current_repository: unambiguous current repository. Use actual provenance.', schema: { enum: [...TASK_TARGET_SOURCES] }, description: 'Paired target provenance.' },
+  primary_target: { help: 'Confirmed absolute project root, paired with target_source. working_directory never selects the target.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Confirmed absolute root.' },
+  run_id: { help: 'Use the named or unambiguously confirmed run; never select by recency.', schema: { type: 'string', pattern: RUN_ID_PATTERN.source }, description: 'Confirmed run.' },
+  gate: { help: 'Use the requested document gate; it is an optional catalog filter, not a selection heuristic. artifact-readiness accepts UR, PRD, SD or TP drafts only.', schema: { enum: [...APPROVAL_GATES] }, description: 'Draft/read gate; catalog filter.', operations: ['artifact-readiness', 'operation-contract', ...PRESENTATION_OPERATIONS] },
+  expected_revision_id: { help: 'For bound current-state inspections use the current gate-check revision. For document/preview reads preserve the selected prepared record original revision from catalog read_arguments or the original conversation binding.', schema: { $ref: '#/$defs/i' }, description: 'gate-check revision; original for reads.', operations: BOUND_INSPECT_OPERATIONS },
+  presentation_id: { help: 'Use the exact prepared ID from a validated catalog candidate or the existing conversation binding. Never guess a UUID, choose by timestamp, or prepare another presentation to pass a read.', schema: { $ref: '#/$defs/i' }, description: 'ID from catalog/conversation.', operations: PRESENTATION_OPERATIONS },
+  target_id: { help: 'Copy binding.target_id from operation-contract or the selected catalog read_arguments; this digest identifies a target and grants no authority.', schema: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, description: 'Target hash: operation-contract.', operations: PRESENTATION_OPERATIONS },
+  cursor: { help: 'Omit on the first page, then copy next_cursor unchanged. Catalog cursors are accepted only on operation-contract module=agdf_prepare/presentation.prepare. Never exchange document, preview or catalog cursors.', schema: cursorSchema, description: 'Next cursor; omit initially.', operations: [...PRESENTATION_OPERATIONS, 'operation-contract'] },
+  variant: { help: 'gate-check only: status-card or approval-envelope. Neither variant records an approval.', schema: { enum: [...GATE_CHECK_VARIANTS] }, description: 'gate-check view.', operations: [VARIANT_OPERATION] },
+  module: { help: 'contract uses an advertised runtime module; operation-contract uses group/kind; operation-status uses the original operation_id from the saved command receipt, never a newly generated UUID.', schema: { type: 'string', minLength: 1, maxLength: 64 }, description: 'Contract, group/kind or receipt UUID.', operations: [MODULE_OPERATION, 'operation-contract', 'operation-status'] },
+  all_active: { help: 'Only doctor and delivery-map accept true. False retains the selected-run read behavior.', schema: { type: 'boolean' }, description: 'All runs: doctor/delivery-map.' },
+};
+const moduleOperations = [MODULE_OPERATION, 'operation-contract', 'operation-status'];
+const inputSchema = {
+  type: 'object', additionalProperties: false,
+  required: ['operation', 'presentation_language', 'working_directory'],
+  $defs: { i: uuidSchema, b: { not: { enum: CONTROL_INSPECT_OPERATIONS.filter(op => !BOUND_INSPECT_OPERATIONS.includes(op)) } }, d: { enum: PRESENTATION_OPERATIONS }, m: { enum: moduleOperations } },
+  properties: Object.fromEntries(Object.entries(fieldModel).map(([name, field]) => [name, { ...field.schema, description: field.description }])),
+  dependentRequired: { target_source: ['primary_target'], primary_target: ['target_source'] },
+  dependentSchemas: Object.fromEntries(Object.entries(fieldModel).filter(([, f]) => f.operations).map(([name, field]) => [name,
+    name === 'cursor' ? { anyOf: [ { properties: { operation: { $ref: '#/$defs/d' } } },
+      { properties: { operation: { const: 'operation-contract' }, module: { const: PRESENTATION_CATALOG_MODULE } } } ] }
+      : { properties: { operation: field.operations === BOUND_INSPECT_OPERATIONS ? { $ref: '#/$defs/b' }
+        : field.operations === PRESENTATION_OPERATIONS ? { $ref: '#/$defs/d' } : name === 'module' ? { $ref: '#/$defs/m' } : { enum: field.operations } } },
+  ])),
+  allOf: [
+    { anyOf: [{ properties: { all_active: { const: false } } }, { properties: { operation: { enum: [...ALL_ACTIVE_OPERATIONS] } } }] },
+    { if: { properties: { operation: { $ref: '#/$defs/m' } } }, then: { required: ['module'] } },
+    { if: { properties: { operation: { $ref: '#/$defs/b' } } }, then: { required: ['run_id', 'expected_revision_id', 'target_source'] } },
+    { if: { properties: { operation: { const: 'artifact-readiness' } } }, then: { required: ['gate'], properties: { gate: { enum: [...ARTIFACT_READINESS_GATES] } } } },
+    { if: { properties: { operation: { $ref: '#/$defs/d' } } }, then: { required: ['gate', 'presentation_id', 'target_id'] } },
+  ],
+};
+
+const inspectContract = {
+  name: "agdf_inspect",
+  description: "Read-only: gate-check -> operation-contract module=agdf_prepare/presentation.prepare -> catalog read_arguments -> presentation-document/next_cursor.",
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema,
+  outputSchema: {
+    type: 'object', required: ['outcome', 'terminal', 'authorizes', 'operation', 'report', 'presentation', 'host_action', 'target', 'recovery'],
+    properties: {
+      schema_version: { const: '1' }, contract_version: { const: 1 }, authorizes: { const: false },
+      operation: { type: ['string', 'null'] }, runtime: { type: 'object' }, target: { type: ['object', 'null'] },
+      report: { type: ['object', 'null'] }, recovery: { type: ['object', 'null'], required: ['action'], properties: { action: { type: 'string', minLength: 1 } } },
+      presentation: { type: ['object', 'null'], required: ['markdown'], properties: { markdown: { type: 'string' } } },
+      timing: { type: 'object' }, diagnostics: { type: 'array', items: { type: 'object' } },
+      host_action: { type: 'object', required: ['mode', 'source', 'allow_surrounding_text', 'may_request_run_or_evidence'],
+        properties: { text: { type: 'string', minLength: 1 }, may_request_run_or_evidence: { const: false } } },
+    },
+    oneOf: [
+      { properties: { outcome: { const: 'inspect_result' }, terminal: { const: false }, operation: { enum: [...CONTROL_INSPECT_OPERATIONS] },
+        report: { type: 'object' }, recovery: { type: 'null' }, target: { type: 'object', required: ['resolution_state'], properties: { resolution_state: { const: 'resolved' } } },
+        host_action: { properties: { mode: { const: 'consume_report_and_continue' }, source: { enum: ['report', 'presentation.markdown'] }, allow_surrounding_text: { const: true } } } },
+        if: { properties: { host_action: { properties: { source: { const: 'presentation.markdown' } } } } },
+        then: { properties: { presentation: { type: 'object', properties: { markdown: { minLength: 1 } } }, host_action: { required: ['text'] } } },
+        else: { properties: { presentation: { anyOf: [{ type: 'null' }, { properties: { markdown: { const: '' } } }] }, host_action: { not: { required: ['text'] } } } },
+      },
+      { properties: { outcome: { const: 'target_unresolved' }, terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' },
+        target: { type: 'object', required: ['resolution_state'], properties: { resolution_state: { const: 'unresolved' } } },
+        presentation: { type: 'object', properties: { markdown: { minLength: 1 } } },
+        host_action: { required: ['text'], properties: { mode: { const: 'transmit_presentation_verbatim_and_stop' }, source: { const: 'presentation.markdown' }, allow_surrounding_text: { const: false } } } } },
+      { properties: { outcome: { enum: ['invalid_input', 'evaluator_error'] }, terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' }, presentation: { type: 'null' },
+        host_action: { required: ['text'], properties: { mode: { const: 'transmit_recovery_verbatim_and_stop' }, source: { const: 'recovery.action' }, allow_surrounding_text: { const: false } } } } },
+    ],
+  },
+};
+
+// Detailed result semantics remain owned here. The discovered tool advertises the
+// bounded envelope; repeating every forwarding branch in each model session is
+// unnecessary. Both declarations derive from this same contract, without a
+// second evaluator or a larger discovery budget.
+export const CONTROL_INSPECT_OUTPUT_SCHEMA = deepFreeze(inspectContract.outputSchema);
+export const CONTROL_INSPECT_FUNCTION_DEFINITION = deepFreeze({
+  ...inspectContract,
+  outputSchema: { type: 'object', required: inspectContract.outputSchema.required,
+    properties: { ...Object.fromEntries(Object.entries(inspectContract.outputSchema.properties).filter(([key]) => key !== 'report').map(([key, value]) => [key, key === 'recovery' ? { required: value.required, properties: value.properties } : value])),
+      outcome: { enum: ['inspect_result', 'target_unresolved', 'invalid_input', 'evaluator_error'] },
+    },
+    if: { properties: { outcome: { const: 'inspect_result' } } },
+    then: { properties: { terminal: { const: false }, report: { type: 'object' }, recovery: { type: 'null' } } },
+    else: { properties: { terminal: { const: true }, report: { type: 'null' }, recovery: { type: 'object' } } },
+  },
+});
+
+export function inspectContractHelp() {
+  const base = { presentation_language: 'de', working_directory: '/workspace/project', target_source: 'explicit_target', primary_target: '/workspace/project', run_id: 'demo-run-01' };
+  const revision = '00000000-0000-4000-8000-000000000001';
+  return deepFreeze({ schema_version: '1', authorizes: false,
+    parameters: Object.fromEntries(Object.entries(fieldModel).map(([key, field]) => [key, { description: field.help ?? field.description, operations: field.operations ?? [...CONTROL_INSPECT_OPERATIONS] }])),
+    operations: Object.fromEntries(CONTROL_INSPECT_OPERATIONS.map(operation => [operation, {
+      required: [...inputSchema.required, ...(BOUND_INSPECT_OPERATIONS.includes(operation) ? ['run_id', 'expected_revision_id', 'target_source', 'primary_target'] : []),
+        ...(['contract', 'operation-contract', 'operation-status'].includes(operation) ? ['module'] : []),
+        ...(operation === 'artifact-readiness' ? ['gate'] : PRESENTATION_OPERATIONS.includes(operation) ? ['gate', 'presentation_id', 'target_id'] : [])],
+    }])),
+    examples_are_illustrative: true,
+    examples: [ { ...base, operation: 'gate-check' },
+      { ...base, operation: 'operation-contract', module: PRESENTATION_CATALOG_MODULE, expected_revision_id: revision, gate: 'UR' },
+      { ...base, operation: 'presentation-document', expected_revision_id: revision, gate: 'UR', presentation_id: '00000000-0000-4000-8000-000000000002', target_id: `sha256:${'0'.repeat(64)}` } ],
+    provenance: 'Keep exact conversation bindings. Otherwise use catalog read_arguments only after unique complete discovery or explicit selection. Document revision is original, not current. Prepared is not human-viewed or approved. Other modules reject catalog cursors.',
+    catalog_limits: { page_candidates: 16, record_files: 256, record_bytes: 1048576, directory_entries: 1024 },
+  });
+}
+
+export function controlInspectDefinitionBytes(definition = CONTROL_INSPECT_FUNCTION_DEFINITION) {
+  return Buffer.byteLength(JSON.stringify(definition), "utf8");
+}
+
+function requireText(value, field, maximum = 240) {
+  if (typeof value !== "string" || !value.trim()) throw new SkillDispatchInputError(field, `${field} is required`);
+  if (value.length > maximum || /[\r\n\0]/u.test(value)) throw new SkillDispatchInputError(field, `${field} is invalid`);
+  return value;
+}
+
+export function parseControlInspectFunctionArguments(argumentsValue, trustedContext) {
+  if (!argumentsValue || typeof argumentsValue !== "object" || Array.isArray(argumentsValue)) {
+    throw new SkillDispatchInputError("arguments", "arguments must be an object");
+  }
+  const schema = CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema;
+  const allowed = new Set(Object.keys(schema.properties));
+  const unknown = Object.keys(argumentsValue).find((key) => !allowed.has(key));
+  if (unknown) throw new SkillDispatchInputError(unknown, "unsupported argument");
+  const missing = schema.required.find((key) => !Object.hasOwn(argumentsValue, key));
+  if (missing) throw new SkillDispatchInputError(missing, "required argument is missing");
+  if (!trustedContext || typeof trustedContext !== "object") {
+    throw new SkillDispatchInputError("trusted_context", "trusted context is required");
+  }
+  if (Boolean(argumentsValue.target_source) !== Boolean(argumentsValue.primary_target)) {
+    throw new SkillDispatchInputError("primary_target", "target_source and primary_target must be supplied together");
+  }
+  return deepFreeze({
+    operation: argumentsValue.operation,
+    presentationLanguage: argumentsValue.presentation_language,
+    workingDirectory: argumentsValue.working_directory,
+    targetSource: argumentsValue.target_source,
+    primaryTarget: argumentsValue.primary_target,
+    runId: argumentsValue.run_id,
+    ...(argumentsValue.gate !== undefined ? { gate: argumentsValue.gate } : {}),
+    ...(argumentsValue.expected_revision_id !== undefined ? { expectedRevisionId: argumentsValue.expected_revision_id } : {}),
+    ...(argumentsValue.presentation_id !== undefined ? { presentationId: argumentsValue.presentation_id } : {}),
+    ...(argumentsValue.target_id !== undefined ? { targetId: argumentsValue.target_id } : {}),
+    ...(argumentsValue.cursor !== undefined ? { cursor: argumentsValue.cursor } : {}),
+    ...(argumentsValue.variant !== undefined ? { variant: argumentsValue.variant } : {}),
+    ...(argumentsValue.module !== undefined ? { contractModule: argumentsValue.module } : {}),
+    ...(argumentsValue.all_active !== undefined ? { allActive: argumentsValue.all_active } : {}),
+    surface: trustedContext.surface,
+    expectedVersion: trustedContext.expectedVersion,
+    interactionLocales: trustedContext.interactionLocales,
+  });
+}
+
+// Normalizes a raw inspect input with the dispatcher's language and target rules and the shared
+// read-selection rules. Throws SkillDispatchInputError or ReadSelectionError; both carry `field`.
+export function normalizeControlInspectInput(input) {
+  const operation = requireText(input.operation, "operation", 64);
+  if (!CONTROL_INSPECT_OPERATIONS.includes(operation)) throw new SkillDispatchInputError("operation", `Unsupported inspect operation: ${operation}`);
+  let requestedPresentationLanguage;
+  try {
+    requestedPresentationLanguage = requireText(input.presentationLanguage, "presentation_language", 64);
+  } catch {
+    throw new SkillDispatchInputError("presentation_language", "presentation_language is required");
+  }
+  const canonical = canonicalizeLanguageTag(requestedPresentationLanguage);
+  if (!canonical) throw new SkillDispatchInputError("presentation_language", "presentation_language is invalid");
+  const presentationLanguage = resolvePresentationLocale(input.interactionLocales, canonical);
+  const workingDirectory = requireText(input.workingDirectory, "working_directory", 4096);
+  if (!isAbsolute(workingDirectory)) throw new SkillDispatchInputError("working_directory", "working_directory must be absolute");
+  const rawTargetSource = input.targetSource || null;
+  const primaryTarget = input.primaryTarget || null;
+  if (Boolean(rawTargetSource) !== Boolean(primaryTarget)) throw new SkillDispatchInputError("primary_target", "target_source and primary_target must be supplied together");
+  if (primaryTarget && (!isAbsolute(primaryTarget) || primaryTarget.length > 4096)) throw new SkillDispatchInputError("primary_target", "primary_target must be an absolute bounded path");
+  const targetSource = rawTargetSource ? normalizeTaskTargetSource(rawTargetSource, { allowEmpty: false }) : null;
+  const runId = input.runId || null;
+  if (runId && !RUN_ID_PATTERN.test(runId)) throw new SkillDispatchInputError("run_id", "run_id is invalid");
+  if (operation === "artifact-readiness") {
+    if (!runId) throw new SkillDispatchInputError("run_id", "artifact-readiness requires an explicit run_id");
+    if (!primaryTarget) throw new SkillDispatchInputError("primary_target", "artifact-readiness requires an explicit target binding");
+    if (!ARTIFACT_READINESS_GATES.includes(input.gate)) throw new SkillDispatchInputError("gate", "Unsupported draft gate");
+    if (!REVISION_ID_PATTERN.test(input.expectedRevisionId ?? "")) throw new SkillDispatchInputError("expected_revision_id", "A valid expected revision is required");
+  } else if (BOUND_INSPECT_OPERATIONS.includes(operation)) {
+    if (!runId || !primaryTarget || !REVISION_ID_PATTERN.test(input.expectedRevisionId ?? '')) throw new SkillDispatchInputError('binding', 'An exact target, Run and expected revision binding is required');
+    if (operation === 'operation-contract' && !OPERATION_CONTRACT_MODULES.includes(input.contractModule)) {
+      throw new SkillDispatchInputError('module', 'Unsupported command group/operation module', { allowedValues: OPERATION_CONTRACT_MODULES });
+    }
+    if (operation === 'operation-status' && !REVISION_ID_PATTERN.test(input.contractModule ?? '')) throw new SkillDispatchInputError('operation_id', 'An original operation UUID is required');
+    if (input.gate !== undefined && (!['operation-contract', 'presentation-document', 'presentation-preview'].includes(operation) || !APPROVAL_GATES.includes(input.gate))) throw new SkillDispatchInputError('gate', 'Unsupported operation gate');
+  } else if (input.gate !== undefined || input.expectedRevisionId !== undefined) {
+    throw new SkillDispatchInputError("gate", "Draft binding fields are supported only by artifact-readiness");
+  }
+  if (['presentation-document', 'presentation-preview'].includes(operation)) {
+    if (!APPROVAL_GATES.includes(input.gate) || !REVISION_ID_PATTERN.test(input.presentationId ?? '')
+      || !/^sha256:[0-9a-f]{64}$/u.test(input.targetId ?? '')
+      || input.cursor !== undefined && !/^[0-9a-f]{64}:(?:0|[1-9][0-9]{0,6})$/u.test(input.cursor)) throw new SkillDispatchInputError('presentation', 'An exact presentation binding and bounded cursor are required');
+  } else if (input.presentationId !== undefined || input.targetId !== undefined || input.cursor !== undefined && !(operation === 'operation-contract' && input.contractModule === PRESENTATION_CATALOG_MODULE && new RegExp(cursorSchema.pattern, 'u').test(input.cursor) && typeof input.cursor === 'string' && input.cursor.length <= cursorSchema.maxLength)) {
+    throw new SkillDispatchInputError('presentation', 'Document selectors require presentation-document');
+  }
+  if (input.allActive !== undefined && typeof input.allActive !== "boolean") throw new SkillDispatchInputError("all_active", "all_active is invalid");
+  if (input.contractModule !== undefined) requireText(input.contractModule, "module", 64);
+  if (input.variant !== undefined) requireText(input.variant, "variant", 32);
+  validateReadSelection({
+    operation,
+    allActive: input.allActive === true,
+    contractModule: input.contractModule,
+    variant: input.variant,
+  });
+  const selectorKeys = { gate: 'gate', expected_revision_id: 'expectedRevisionId', presentation_id: 'presentationId', target_id: 'targetId', cursor: 'cursor', variant: 'variant', module: 'contractModule' };
+  for (const [field, key] of Object.entries(selectorKeys)) {
+    if (input[key] !== undefined && !fieldModel[field].operations.includes(operation)) throw new SkillDispatchInputError(field, `Unsupported selector for ${operation}`);
+  }
+  return Object.freeze({
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    operation,
+    surface: input.surface ?? null,
+    presentation_language: presentationLanguage,
+    working_directory: workingDirectory,
+    target_source: targetSource,
+    primary_target: primaryTarget,
+    run_id: runId,
+    gate: input.gate,
+    expected_revision_id: input.expectedRevisionId,
+    presentation_id: input.presentationId, target_id: input.targetId, cursor: input.cursor,
+    group: operation === 'operation-contract' ? input.contractModule.split('/')[0] : undefined,
+    kind: operation === 'operation-contract' ? input.contractModule.split('/')[1] : undefined, operation_id: operation === 'operation-status' ? input.contractModule : undefined,
+    variant: input.variant,
+    contract_module: input.contractModule,
+    all_active: input.allActive === true,
+    expected_version: requireText(input.expectedVersion, "expected_version", 64),
+  });
+}
+
+export { ReadSelectionError };
+
+export const CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY = "The inspect result exceeds the 1 MiB MCP output limit. Narrow the selection (one run_id instead of all_active) or use the CLI with --json.";
+
+// Same 1 MiB ceiling as the dispatcher, but the fallback keeps the inspect result shape so the host
+// receives a schema-valid recovery instead of a schema error.
+export function serializeControlInspectResult(result) {
+  const output = JSON.stringify(result, null, 2);
+  if (Buffer.byteLength(output, "utf8") <= SKILL_DISPATCH_MAX_OUTPUT_BYTES) return output;
+  return JSON.stringify({
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
+    outcome: "evaluator_error",
+    terminal: true,
+    authorizes: false,
+    operation: result?.operation ?? null,
+    runtime: result?.runtime ?? {},
+    target: result?.target ?? null,
+    report: null,
+    presentation: null,
+    recovery: { action: CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY },
+    host_action: {
+      mode: "transmit_recovery_verbatim_and_stop",
+      source: "recovery.action",
+      text: CONTROL_INSPECT_OUTPUT_TOO_LARGE_RECOVERY,
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    },
+    timing: result?.timing ?? emptySkillDispatchTiming(),
+    diagnostics: [{ code: "inspect_output_too_large" }],
+  }, null, 2);
+}

package/runtime/core/lib/control-inspect/decision-session.js

@@ -0,0 +1,243 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { createCockpitSessionService } from './cockpit-session.js';
+import { COCKPIT_LIMITS, parseCockpitArguments } from './cockpit-contract.js';
+import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
+import { validateRunPresentationRecord, readPresentationDocument, readPresentationPreview } from '../control-state/run-presentation.js';
+import { validateCurrentPreviewRecord } from '../control-state/preview-snapshot.js';
+import { prepareRunContentState } from '../control-evaluation/run-state.js';
+import { readRun } from '../control-state/run-state-edits.js';
+import { decisionMaterial } from '../control-state/presentation-decision.js';
+import { createDecisionActionService } from '../control-state/decision-action-service.js';
+import { validateDecisionAction, enabledDecisionActions } from '../control-state/decision-action-contract.js';
+import { RUN_COMMAND_GROUPS } from '../control-state/run-command-contract.js';
+import { interactionLocales } from '../resources/context.js';
+import { presentationVersionComparison, decisionBriefFromSummary } from '../control-state/run-presentation-render.js';
+import { qaDeviationPresentation } from '../control-state/qa-deviation-acceptance.js';
+import { runSealState } from '../control-state/run-seal.js';
+import { READ_LIMITS } from '../control-read/snapshot.js';
+
+// Bounded ephemeral views on the existing reader. A general cockpit ID is never a
+// decision-session ID, and no view is persistent gate authority.
+export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_GROUPS), now = Date.now,
+  appOnlyMediationQualified = false, readServiceFactory = root => createCockpitSessionService(root),
+  qualification = () => appOnlyMediationQualified === true,
+  actionService = createDecisionActionService({ enabledGroups: groups, appOnlyMediationQualified: true }),
+} = {}) {
+  const sessions = new Map(), readers = new Map(), epoch = randomUUID();
+  let closed = false, generation = 0;
+  const failure = reason => ({ schema_version: '1', outcome: 'rejected', reason, authorizes: false });
+  function retire(row) {
+    if (row.retirement) return row.retirement;
+    row.retired = true; ++row.generation; clearTimeout(row.timer); readers.delete(row.readId);
+    row.retirement = Promise.resolve().then(() => row.reader.close()).then(() => { sessions.delete(row.id); });
+    void row.retirement.catch(() => {}); // Failed worker retirement keeps its counted slot.
+    return row.retirement;
+  }
+  function active(id) {
+    const row = sessions.get(id);
+    if (closed || !row || row.retired) return null;
+    if (now() >= row.expires || now() - row.touched >= COCKPIT_LIMITS.idle) { void retire(row); return null; }
+    return row;
+  }
+  function touch(row) {
+    row.touched = now(); clearTimeout(row.timer);
+    row.timer = setTimeout(() => { void retire(row); }, Math.max(0, Math.min(row.expires, row.touched + COCKPIT_LIMITS.idle) - now()));
+    row.timer.unref?.();
+  }
+  return Object.freeze({
+    inspectOwnership() {
+      for (const row of sessions.values()) active(row.id);
+      return { views: sessions.size, active: [...sessions.values()].filter(row => !row.retired).length,
+        inflight: [...sessions.values()].filter(row => row.pending || row.readPending).length };
+    },
+    async open(input, result, host = {}) {
+      const prepared = result.family_result;
+      if (closed || !['accepted', 'already_applied'].includes(result.outcome) || typeof prepared?.text !== 'string') return { ...result, app_capability: 'unavailable' };
+      for (const row of sessions.values()) active(row.id);
+      if (sessions.size >= COCKPIT_LIMITS.sessions) return { ...result, app_capability: 'unavailable', app_reason: 'resource_limit' };
+      const root = resolveControlCommandTarget(input.primary_target).root;
+      const presentation = validateRunPresentationRecord(root, { runId: input.run_id, gate: input.command.payload.gate,
+        revisionId: input.expected_revision_id, presentationId: prepared.presentation_id });
+      const run = readRun(root, input.run_id);
+      if (presentation.reason || run.rejection || run.meta.revision_id !== input.expected_revision_id
+        || presentation.digest !== prepared.record_digest
+        || 'sha256:' + createHash('sha256').update(prepared.text).digest('hex') !== presentation.record.presentation_digest) return { ...result, app_capability: 'unavailable', app_reason: 'presentation_binding_changed' };
+      const state = prepareRunContentState(root, run.content, run.path);
+      const material = decisionMaterial(root, state, input.command.payload.gate);
+      if (!material.available) return { ...result, app_capability: 'unavailable', app_reason: material.reason };
+      if ([3, 4, 5].includes(presentation.record.schema_version) && (typeof prepared.summary !== 'string'
+        || 'sha256:' + createHash('sha256').update(prepared.summary).digest('hex') !== presentation.record.summary_digest)) {
+        return { ...result, app_capability: 'unavailable', app_reason: 'presentation_binding_changed' };
+      }
+      const binding = Object.freeze({ target_id: input.target_id, run_id: input.run_id, gate: input.command.payload.gate,
+        expected_revision_id: input.expected_revision_id, presentation_id: prepared.presentation_id, presentation_digest: presentation.digest,
+        material_version: material.material_version, material_sources: material.sources, presentation_language: prepared.presentation_language });
+      let qualified = false; try { qualified = qualification(host) === true; } catch {}
+      const row = { id: randomUUID(), reader: readServiceFactory(root), root, binding, qualified, created: now(), touched: now(),
+        expires: now() + COCKPIT_LIMITS.lifetime, generation: ++generation, retired: false, retirement: null, readId: null, timer: null, pending: null };
+      // UAT presents a bound evidence summary, not an invented UAT artefact or
+      // today's QA document. Its large view reads exactly the prepared text.
+      row.presentationDocument = binding.gate === 'UAT' ? Object.freeze({ resource_id: randomUUID(),
+        run_id: binding.run_id, type: 'UAT', status: 'registered', path: null,
+        registered_reference: `presentation:${binding.presentation_id}` }) : null;
+      row.hasSnapshot = [3, 4, 5].includes(presentation.record.schema_version);
+      row.previewRecord = presentation.record.schema_version === 5 ? presentation.record : null;
+      row.previewResourceId = row.previewRecord ? randomUUID() : null;
+      row.presentationText = row.presentationDocument ? prepared.text : null;
+      row.presentedContentSeal = presentation.record.content_digest;
+      row.documentDigest = row.hasSnapshot ? presentation.record.document_digest
+        : row.presentationDocument ? presentation.record.presentation_digest : presentation.record.artefact_digest;
+      if (row.hasSnapshot) {
+        let cursor, text = '';
+        do {
+          const page = readPresentationDocument(root, { runId: binding.run_id, gate: binding.gate,
+            revisionId: binding.expected_revision_id, presentationId: binding.presentation_id, targetId: binding.target_id, cursor });
+          if (!page.available) return { ...result, app_capability: 'unavailable', app_reason: page.reason };
+          text += page.content; cursor = page.next_cursor ?? undefined;
+        } while (cursor);
+        row.presentationText = text;
+      }
+      // Publish capacity ownership before the first await, including unsuccessful cleanup.
+      sessions.set(row.id, row); touch(row);
+      try {
+        const rendered = await row.reader.render({ run_id: binding.run_id });
+        if (active(row.id) !== row || !rendered._meta?.agdf_cockpit?.session_id) throw Error('session_expired');
+        row.readId = rendered._meta.agdf_cockpit.session_id; readers.set(row.readId, row);
+        const snapshot = await row.reader.read({ operation: 'snapshot', session_id: row.readId, run_id: binding.run_id });
+        if (active(row.id) !== row || snapshot.state !== 'available' || snapshot.data?.run?.revision_id !== binding.expected_revision_id) throw Error('source_snapshot_changed');
+        const resource = row.presentationDocument ?? snapshot.data.run.resources.find(item => item.type === binding.gate && item.status === 'registered');
+        // App metadata identifies one immutable presentation. The shared reader
+        // issues replacement snapshot/resource selectors when it projects a read.
+        // Keep that rotating cursor private to this exact decision view.
+        row.presentedRead = Object.freeze({ snapshot_id: snapshot.snapshot_id, resource_id: resource?.resource_id ?? null });
+        row.currentRead = row.presentedRead;
+        const qaAcceptance = prepared.qa_acceptance ? qaDeviationPresentation(state.qa_acceptance, binding.presentation_language) : null;
+        const labels = interactionLocales.locales[binding.presentation_language]?.decisionCard ?? interactionLocales.locales.en.decisionCard;
+        return { ...result, app_capability: row.qualified ? 'available' : 'not_qualified',
+          _meta: { agdf_decision: { schema_version: '1', session_id: row.id, read_session_id: row.readId,
+            owner_epoch: epoch, generation: row.generation, expires_at: row.expires, binding, target: snapshot.target,
+            title: snapshot.data.run.title, labels: qaAcceptance ? { ...labels, approve: qaAcceptance.approve_label, confirmed: qaAcceptance.confirmed_label } : labels,
+            approval_effect_label: interactionLocales.locales[binding.presentation_language]?.statusCard.allowedAfter ?? interactionLocales.locales.en.statusCard.allowedAfter,
+            summary: row.hasSnapshot ? prepared.summary : prepared.text,
+            decision_brief: qaAcceptance?.summary || (row.hasSnapshot ? decisionBriefFromSummary(prepared.summary, binding.presentation_language) : null),
+            gate_title: interactionLocales.locales[binding.presentation_language]?.gateTitles[binding.gate]
+              ?? interactionLocales.locales.en.gateTitles[binding.gate],
+            decision_heading: qaAcceptance ? labels.deviationAcceptanceIntro : interactionLocales.locales[binding.presentation_language]?.gateActionTitles[binding.gate]
+              ?? interactionLocales.locales.en.gateActionTitles[binding.gate],
+            approval_effect: qaAcceptance?.effect || (interactionLocales.locales[binding.presentation_language]?.primary.afterApproval[binding.gate]
+              ?? interactionLocales.locales.en.primary.afterApproval[binding.gate]),
+            snapshot_id: snapshot.snapshot_id, resource_id: resource?.resource_id ?? null,
+            document_digest: row.documentDigest,
+            ...(row.previewRecord ? { preview: { resource_id: row.previewResourceId,
+              version: row.previewRecord.preview_review.descriptor.version,
+              task: row.previewRecord.preview_review.descriptor.review_task,
+              scenarios: row.previewRecord.preview_review.descriptor.scenarios,
+              criterion_ids: row.previewRecord.preview_review.descriptor.criterion_ids,
+              open_questions: row.previewRecord.preview_review.descriptor.open_questions,
+              content_digest: row.previewRecord.preview_review.rendered_digest } } : {}),
+            enabled_actions: row.qualified ? enabledDecisionActions(groups).filter(action => action === 'approve') : [],
+            capability: row.qualified ? 'available' : 'not_qualified',
+            comparison: presentationVersionComparison(root, state, binding.gate, row.documentDigest) } } };
+      } catch (error) {
+        await retire(row).catch(() => {});
+        return { ...result, app_capability: 'unavailable', app_reason: error.message };
+      }
+    },
+    async action(input, host = {}) {
+      const errors = validateDecisionAction(input);
+      if (errors.length) return { ...failure('decision_schema_invalid'), diagnostics: errors };
+      const row = active(input.session_id);
+      if (!row) return failure('session_expired');
+      if (!row.qualified) return failure('app_only_mediation_not_qualified');
+      try { if (qualification(host) !== true) return failure('app_only_mediation_not_qualified'); }
+      catch { return failure('app_only_mediation_not_qualified'); }
+      if (input.presentation_id !== row.binding.presentation_id || input.expected_revision_id !== row.binding.expected_revision_id) return failure('decision_binding_invalid');
+      if (row.pending) return { ...failure('decision_pending'), outcome: row.pending === input.operation_id ? 'effect_unknown' : 'rejected', operation_id: row.pending };
+      touch(row); const captured = row.generation; row.pending = input.operation_id;
+      let result;
+      try { result = await actionService(row.root, row.binding, input); }
+      catch { result = { ...failure('decision_result_unknown'), outcome: 'effect_unknown', operation_id: input.operation_id }; }
+      finally { row.pending = null; }
+      if (active(row.id) !== row || row.generation !== captured) return { ...result, view_state: 'closed' };
+      touch(row); return { ...result, view_state: 'active' };
+    },
+    async read(input, signal) {
+      try { input = parseCockpitArguments(input); } catch { return failure('resource_denied'); }
+      const row = readers.get(input.session_id);
+      if (!row || active(row.id) !== row) return failure('session_expired');
+      if (input.operation === 'close') { await retire(row); return { schema_version: '1', state: 'available', data: { closed: true }, authorizes: false }; }
+      if (!['snapshot', 'document', 'preview', 'freshness', 'changes'].includes(input.operation) || input.run_id && input.run_id !== row.binding.run_id) return failure('resource_denied');
+      if (input.operation === 'preview') {
+        if (signal?.aborted) return failure('cancelled');
+        if (!row.previewRecord || input.resource_id !== row.previewResourceId
+          || ![row.presentedRead.snapshot_id, row.currentRead.snapshot_id].includes(input.snapshot_id)) return failure('resource_denied');
+        if (row.readPending) return failure('busy');
+        touch(row); const captured = row.generation; row.readPending = true;
+        try {
+          const run = readRun(row.root, row.binding.run_id);
+          if (run.rejection || run.meta.revision_id !== row.binding.expected_revision_id || runSealState(row.root, run.content).status !== 'valid') return failure('decision_binding_changed');
+          validateCurrentPreviewRecord(row.root, row.previewRecord);
+          let content = '', cursor;
+          do {
+            const chunk = readPresentationPreview(row.root, { runId: row.binding.run_id, gate: row.binding.gate,
+              revisionId: row.binding.expected_revision_id, presentationId: row.binding.presentation_id, targetId: row.binding.target_id, cursor });
+            if (signal?.aborted) return failure('cancelled');
+            if (!chunk.available) return failure(chunk.reason);
+            if (chunk.applicability !== 'current') return failure('decision_binding_changed');
+            content += chunk.content; cursor = chunk.next_cursor ?? undefined;
+          } while (cursor);
+          if (active(row.id) !== row || row.generation !== captured) return failure('session_expired');
+          const result = { schema_version: '1', state: 'available', data: { preview: { resource_id: row.previewResourceId,
+            content, content_digest: row.previewRecord.preview_review.rendered_digest, version: row.previewRecord.preview_review.descriptor.version } }, authorizes: false };
+          if (Buffer.byteLength(JSON.stringify(result), 'utf8') > READ_LIMITS.response) return failure('resource_limit');
+          return result;
+        } catch (error) { return failure(error.message.startsWith('preview_') ? error.message : 'preview_unavailable'); }
+        finally { row.readPending = false; }
+      }
+      const presented = input.snapshot_id === row.presentedRead.snapshot_id
+        && (input.operation !== 'document' || input.resource_id === row.presentedRead.resource_id);
+      const current = input.snapshot_id === row.currentRead.snapshot_id
+        && (input.operation !== 'document' || input.resource_id === row.currentRead.resource_id);
+      if (input.operation !== 'snapshot' && (!presented && !current
+        || input.operation === 'document' && !row.currentRead.resource_id)) return failure('resource_denied');
+      if (row.readPending) return failure('busy');
+      touch(row); const captured = row.generation;
+      row.readPending = true;
+      let result;
+      try {
+        result = await row.reader.read(input.operation === 'document' && (row.presentationDocument || row.hasSnapshot)
+          ? { operation: 'snapshot', session_id: row.readId, run_id: row.binding.run_id }
+          : input.operation === 'snapshot' ? { ...input, run_id: row.binding.run_id }
+          : { ...input, snapshot_id: row.currentRead.snapshot_id,
+            ...(input.operation === 'document' ? { resource_id: row.currentRead.resource_id } : {}) }, signal);
+      } finally { row.readPending = false; }
+      if (active(row.id) !== row || row.generation !== captured) return failure('session_expired');
+      if (result.data?.run && result.data.run.revision_id !== row.binding.expected_revision_id) return failure('decision_binding_changed');
+      if (input.operation === 'document' && (row.presentationDocument || row.hasSnapshot) && result.state === 'available') {
+        const run = readRun(row.root, row.binding.run_id);
+        if (run.rejection || run.meta.revision_id !== row.binding.expected_revision_id) return failure('decision_binding_changed');
+        const seal = runSealState(row.root, run.content);
+        if (seal.status !== 'valid' || seal.actual.content_seal !== row.presentedContentSeal) return failure('decision_binding_changed');
+        const material = decisionMaterial(row.root, prepareRunContentState(row.root, run.content, run.path), row.binding.gate);
+        if (!material.available || material.material_version !== row.binding.material_version) return failure('presented_document_unavailable');
+        const resource = row.presentationDocument ?? result.data.run.resources.find(item => item.type === row.binding.gate && item.status === 'registered');
+        if (!resource) return failure('presented_document_unavailable');
+        result = { ...result, data: { ...result.data, document: { resource,
+          content: row.presentationText, content_digest: row.documentDigest.slice(7) } } };
+        if (Buffer.byteLength(JSON.stringify(result), 'utf8') > READ_LIMITS.response) return failure('resource_limit');
+      }
+      const document = result.data?.document;
+      if (input.operation === 'document' && result.state === 'available'
+        && (document?.resource?.type !== row.binding.gate || 'sha256:' + document?.content_digest !== row.documentDigest)) {
+        // The digest comes from the immutable prepared record, never the mutable reader.
+        return failure('presented_document_unavailable');
+      }
+      if (result.state === 'available' && result.data?.run && result.snapshot_id) {
+        const resource = row.presentationDocument ?? result.data.run.resources.find(item => item.type === row.binding.gate && item.status === 'registered');
+        row.currentRead = { snapshot_id: result.snapshot_id, resource_id: resource?.resource_id ?? null };
+      }
+      return result;
+    },
+    async close() { closed = true; await Promise.allSettled([...sessions.values()].map(retire)); },
+  });
+}

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

@@ -0,0 +1,35 @@
+// Shared read-only selection policy for CLI and MCP; evaluation never writes control state.
+
+export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations"]);
+export const ALL_ACTIVE_OPERATIONS = Object.freeze(["doctor", "delivery-map"]);
+export const VARIANT_OPERATION = "gate-check";
+export const MODULE_OPERATION = "contract";
+export const GATE_CHECK_VARIANTS = Object.freeze(["status-card", "approval-envelope"]);
+
+export class ReadSelectionError extends Error {
+  constructor(field, message) {
+    super(message);
+    this.name = "ReadSelectionError";
+    this.field = field;
+  }
+}
+
+// `operation` is the CLI command name or the MCP operation. Rules apply to every command so that a
+// write command carrying a read-only flag is rejected exactly as before the extraction.
+export function validateReadSelection({ operation, allActive = false, contractModule, variant } = {}) {
+  if (allActive && !ALL_ACTIVE_OPERATIONS.includes(operation)) {
+    throw new ReadSelectionError("all_active", "--all-active is supported only by doctor and delivery-map");
+  }
+  if (contractModule !== undefined && ![MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation)) {
+    throw new ReadSelectionError("module", "--module is supported only by contract");
+  }
+  if ([MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation) && !contractModule) {
+    throw new ReadSelectionError("module", "contract requires --module");
+  }
+  if (variant !== undefined && operation !== VARIANT_OPERATION) {
+    throw new ReadSelectionError("variant", "--status-card and --approval-envelope are supported only by gate-check");
+  }
+  if (variant !== undefined && !GATE_CHECK_VARIANTS.includes(variant)) {
+    throw new ReadSelectionError("variant", `gate-check variant must be one of ${GATE_CHECK_VARIANTS.join(", ")}`);
+  }
+}