create-agdf 0.20.1 → 0.30.0

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

@@ -1,7 +1,7 @@
+import { projectMcpInputSchema } from '../mcp-input-schema.js';
 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 { RUN_COMMAND_GROUPS, PLANNING_COMMAND_KINDS, PLANNING_SCOPE_SCHEMA, schemaDiagnostics } from '../control-state/run-command-schema.js';
 import { APPROVAL_GATES } from '../control-state/run-identity.js';
 import {
   PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE,
@@ -10,12 +10,12 @@ import {
 } 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";
+import { ARTIFACT_READINESS_GATES, 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;
+// Shared discovery budget across hosts (SDD-005).
+export const CONTROL_INSPECT_MAX_DEFINITION_BYTES = 6144;
 export const OPERATION_CONTRACT_MODULES = Object.freeze(Object.entries(RUN_COMMAND_GROUPS)
   .flatMap(([group, kinds]) => kinds.map(kind => `${group}/${kind}`)));
 
@@ -25,55 +25,83 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
-// One field model supplies discovery, applicability guards and on-demand help.
+// Shared discovery, selector 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 BOUND_INSPECT_OPERATIONS = Object.freeze(['artifact-readiness', 'authoring-inputs', '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.' },
+  operation: { help: 'Read only; never prepare or approve.', schema: { enum: [...CONTROL_INSPECT_OPERATIONS] }, description: 'Read action.' },
+  presentation_language: { help: 'Optional MCP override of configured chat language; valid unsupported tags use complete English.', schema: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE }, description: 'Reply BCP47 tag.' },
+  working_directory: { help: 'Absolute context; never selects a target.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Context; not target authority.' },
+  target_source: { help: 'Actual provenance: explicit_target = specified; continued_target = confirmed; current_repository = unambiguous.', schema: { enum: [...TASK_TARGET_SOURCES] }, description: 'Requires primary_target.' },
+  primary_target: { help: 'Confirmed absolute root paired with target_source; cwd is not target authority.', schema: { type: 'string', minLength: 1, maxLength: 4096 }, description: 'Pair: target_source.' },
+  run_id: { help: 'Named or confirmed Run; never select by recency.', schema: { type: 'string', pattern: RUN_ID_PATTERN.source }, description: 'Confirmed run.' },
+  planning: { help: 'Selected pre-Run plan and canonical source digest; null digest is permitted for initial capture/inspection. Never combine with Run/revision.', schema: PLANNING_SCOPE_SCHEMA, description: 'Pre-Run source scope.', operations: ['authoring-inputs', 'planned-entry', 'operation-status'] },
+  gate: { help: 'Requested document gate or catalog filter, never a selection heuristic. artifact-readiness: UR/PRD/SD/TP only.', schema: { enum: [...APPROVAL_GATES] }, description: 'Document gate.', operations: ['artifact-readiness', 'operation-contract', ...PRESENTATION_OPERATIONS] },
+  expected_revision_id: { help: 'Bound inspections use current gate-check revision. Document/preview reads preserve the original selected catalog or conversation revision.', schema: { $ref: '#/$defs/i' }, description: 'gate-check revision; original for reads.', operations: BOUND_INSPECT_OPERATIONS },
+  presentation_id: { help: 'Exact prepared ID from validated catalog or conversation. Never guess, select by timestamp, or prepare a replacement to read.', schema: { $ref: '#/$defs/i' }, description: 'ID from catalog/conversation.', operations: PRESENTATION_OPERATIONS },
+  target_id: { help: 'Optional confirmed target hash on target-bound reads; when supplied it must match. Required for presentation reads; never grants authority.', schema: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, description: 'Optional verified target hash.' },
+  cursor: { help: 'Omit initially; copy next_cursor. doctor requires all_active; catalog requires its declared module. Never exchange cursor types.', schema: cursorSchema, description: 'Copy next_cursor.', operations: [...PRESENTATION_OPERATIONS, 'operation-contract', 'authoring-inputs', 'doctor'] },
+  variant: { help: 'gate-check view only; never records approval.', schema: { enum: [...GATE_CHECK_VARIANTS] }, description: 'gate-check view.', operations: [VARIANT_OPERATION] },
+  module: { help: 'contract: advertised module; operation-contract: group/kind; operation-status: original operation UUID from saved receipt, never a new UUID. Setup uses project.initialize/ORIGINAL_UUID without Run/revision; Run operations require Run/revision.', schema: { type: 'string', minLength: 1, maxLength: 64 }, description: 'Contract, group/kind or receipt UUID.', operations: [MODULE_OPERATION, 'operation-contract', 'operation-status'] },
+  all_active: { help: 'true: doctor/delivery-map only; false: selected Run.', schema: { type: 'boolean' }, description: 'doctor/delivery-map only.' },
 };
+const selectorKeys = { gate: 'gate', expected_revision_id: 'expectedRevisionId', presentation_id: 'presentationId', target_id: 'targetId', cursor: 'cursor', variant: 'variant', module: 'contractModule', planning: 'planning' };
 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 } },
+  $defs: { i: uuidSchema, b: { not: { enum: CONTROL_INSPECT_OPERATIONS.filter(op => !BOUND_INSPECT_OPERATIONS.includes(op)) } }, d: { enum: PRESENTATION_OPERATIONS }, m: { enum: ['operation-contract', 'operation-status'] } },
   properties: Object.fromEntries(Object.entries(fieldModel).map(([name, field]) => [name, { ...field.schema, description: field.description }])),
-  dependentRequired: { target_source: ['primary_target'], primary_target: ['target_source'] },
+  dependentRequired: { target_source: ['primary_target'], primary_target: ['target_source'], target_id: ['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' } } },
+    name === 'cursor' ? { anyOf: [ { properties: { operation: { enum: [...PRESENTATION_OPERATIONS, 'authoring-inputs'] } } },
+      { properties: { operation: { const: 'doctor' }, all_active: { const: true } }, required: ['all_active'] },
       { 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 } } },
+        : field.operations === PRESENTATION_OPERATIONS ? { $ref: '#/$defs/d' } : name === 'module' ? { enum: moduleOperations } : { enum: field.operations } } },
   ])),
   allOf: [
+    { if: { properties: { operation: { enum: ['project-state', 'planned-inventory', 'planned-entry'] } } }, then: { required: ['target_source', 'primary_target'], not: { anyOf: [{ required: ['run_id'] }, { required: ['expected_revision_id'] }] } } },
+    { if: { properties: { operation: { const: 'planned-entry' } } }, then: { required: ['planning'] } },
+    { if: { required: ['planning'] }, then: { required: ['target_source', 'primary_target'], not: { anyOf: [{ required: ['run_id'] }, { required: ['expected_revision_id'] }] } } },
+    { not: { properties: { all_active: { const: true } }, required: ['all_active', 'run_id'] } },
     { 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: { $ref: '#/$defs/b' } } }, then: { required: ['target_source'], anyOf: [
+      { required: ['run_id', 'expected_revision_id'] },
+      { not: { anyOf: [{ required: ['run_id'] }, { required: ['expected_revision_id'] }] }, oneOf: [
+        { properties: { operation: { const: 'operation-status' } } },
+        { properties: { operation: { const: 'operation-contract' }, module: { anyOf: [{ enum: ['agdf_run/run.create', 'agdf_project/project.initialize'] }, { pattern: '/(?:planned_|run\\.create_from_planned)' }] } }, required: ['module'] },
+        { properties: { operation: { const: 'authoring-inputs' } }, required: ['planning'] },
+      ] },
+    ] } },
     { 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'] } },
   ],
 };
 
+inputSchema.dependentSchemas.operation = { allOf: inputSchema.allOf };
+delete inputSchema.allOf;
+const conciseHelp = { target_source: 'Pair primary_target; explicit=named; continued=confirmed; current=unambiguous repo.', primary_target: 'Confirmed root; pair target_source.',
+  module: 'contract:index; operation-contract:group/kind; status:UUID.',
+  run_id: 'Not for inventory/project/planned.',
+  expected_revision_id: 'Bound reads only; not gate-check.',
+  planning: 'Planning reads only.',
+  target_id: 'Required for docs; gate-check.',
+  gate: 'Not for gate-check.' };
+for (const [key, field] of Object.entries(inputSchema.properties)) {
+  delete field.description;
+  if (conciseHelp[key]) field.description = conciseHelp[key];
+}
+
 const inspectContract = {
   name: "agdf_inspect",
-  description: "Read-only: gate-check -> operation-contract module=agdf_prepare/presentation.prepare -> catalog read_arguments -> presentation-document/next_cursor.",
+  description: 'Read-only. Ex:{"operation":"operation-contract","module":"agdf_run/run.create","working_directory":"/r","target_source":"explicit_target","primary_target":"/r"}. navigation.next_calls sequentially; read all pages; never dispatch. Setup status: project.initialize/UUID, no Run/revision. Run status: original UUID+run_id+expected_revision_id.',
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  inputSchema,
+  inputSchema: projectMcpInputSchema(inputSchema),
   outputSchema: {
     type: 'object', required: ['outcome', 'terminal', 'authorizes', 'operation', 'report', 'presentation', 'host_action', 'target', 'recovery'],
     properties: {
@@ -103,15 +131,12 @@ const inspectContract = {
   },
 };
 
-// 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.
+// Core retains full result validation; discovery advertises the bounded envelope.
 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])),
+    properties: { authorizes: { const: false },
       outcome: { enum: ['inspect_result', 'target_unresolved', 'invalid_input', 'evaluator_error'] },
     },
     if: { properties: { outcome: { const: 'inspect_result' } } },
@@ -122,23 +147,70 @@ export const CONTROL_INSPECT_FUNCTION_DEFINITION = deepFreeze({
 
 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 { run_id: _exampleRun, ...projectBase } = base;
   const revision = '00000000-0000-4000-8000-000000000001';
   return deepFreeze({ schema_version: '1', authorizes: false,
+    input_completion: 'MCP inherits matching configured language. Current native adapters require explicit working_directory; private trustworthy task context alone may supply it. Bindings remain explicit.',
     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'] : []),
+      required: [...CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema.required, ...(BOUND_INSPECT_OPERATIONS.includes(operation) ? ['run_id', 'expected_revision_id', 'target_source', 'primary_target'] : []),
+        ...(['operation-contract', 'operation-status'].includes(operation) ? ['module'] : []),
         ...(operation === 'artifact-readiness' ? ['gate'] : PRESENTATION_OPERATIONS.includes(operation) ? ['gate', 'presentation_id', 'target_id'] : [])],
+      omit: [...Object.entries(fieldModel).filter(([, field]) => field.operations && !field.operations.includes(operation)).map(([name]) => name),
+        ...(['inventory', 'planned-inventory', 'planned-entry', 'project-state'].includes(operation) ? ['run_id'] : [])],
+      ...(['operation-contract', 'operation-status'].includes(operation) ? { unbound: {
+        module: operation === 'operation-contract' ? 'agdf_run/run.create' : 'project.initialize/original-UUID or original run.create UUID',
+        required: [...CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema.required, 'target_source', 'primary_target', 'module'],
+        omit: ['run_id', 'expected_revision_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.',
+      { ...base, operation: 'presentation-document', expected_revision_id: revision, gate: 'UR', presentation_id: '00000000-0000-4000-8000-000000000002', target_id: `sha256:${'0'.repeat(64)}` },
+      { ...projectBase, operation: 'project-state' },
+      { ...projectBase, operation: 'operation-status', module: `project.initialize/${revision}` } ],
+    provenance: 'Preserve exact conversation bindings; otherwise require unique complete catalog discovery or explicit selection. Reads keep original revisions. Prepared proves neither viewing nor approval. Catalog cursors require the catalog module.',
     catalog_limits: { page_candidates: 16, record_files: 256, record_bytes: 1048576, directory_entries: 1024 },
   });
 }
 
+export function inspectInputValidationHint(input) {
+  if (!input || typeof input !== 'object' || !CONTROL_INSPECT_OPERATIONS.includes(input.operation)) return '';
+  const operation = input.operation, messages = [];
+  if (operation === 'operation-contract' && typeof input.module === 'string' && input.module.length <= 64
+    && !OPERATION_CONTRACT_MODULES.includes(input.module)) {
+    const kind = input.module.split('/').at(-1);
+    const matches = OPERATION_CONTRACT_MODULES.filter(module => module.split('/').at(-1) === kind);
+    messages.push(matches.length === 1 ? `Use module ${matches[0]}; this is the registered owner of ${kind}.`
+      : 'Read contract without module for the registered operation_modules; do not guess a group/kind.');
+  }
+  for (const [name, field] of Object.entries(fieldModel)) {
+    if (Object.hasOwn(input, name) && field.operations && !field.operations.includes(operation))
+      messages.push(`Remove ${name} for ${operation}.`);
+  }
+  if (input.run_id && ['inventory', 'project-state', 'planned-inventory', 'planned-entry'].includes(operation))
+    messages.push(`Remove run_id for ${operation}; it reads the target scope.`);
+  // Diagnose the selected operation, rather than making the model interpret
+  // errors from every alternative of the discovery schema's oneOf branches.
+  const unboundContract = operation === 'operation-contract' &&
+    (['agdf_run/run.create', 'agdf_project/project.initialize'].includes(input.module)
+      || OPERATION_CONTRACT_MODULES.includes(input.module) && /\/(?:planned_|run\.create_from_planned)/u.test(input.module));
+  const bound = BOUND_INSPECT_OPERATIONS.includes(operation) && !unboundContract
+    && !(operation === 'operation-status' && !input.run_id && !input.expected_revision_id)
+    && !(operation === 'authoring-inputs' && input.planning);
+  const required = [...(['operation-contract', 'operation-status'].includes(operation) ? ['module'] : []),
+    ...(bound ? ['run_id', 'expected_revision_id'] : []),
+    ...(BOUND_INSPECT_OPERATIONS.includes(operation) || ['project-state', 'planned-inventory', 'planned-entry'].includes(operation)
+      ? ['primary_target', 'target_source'] : []),
+    ...(PRESENTATION_OPERATIONS.includes(operation) ? ['gate', 'presentation_id', 'target_id'] : [])];
+  for (const key of required) if (!Object.hasOwn(input, key)) messages.push(`Supply ${key} for ${operation}.`);
+  if (PRESENTATION_OPERATIONS.includes(operation)) messages.push('Copy the exact agdf_inspect arguments from presentation.prepare next_calls or the presentation catalog.');
+  if (bound && (!input.run_id || !input.expected_revision_id))
+    messages.push('Read gate-check with the confirmed target and run_id to inspect the current binding; never silently replace a requested revision.');
+  return messages.join(' ').slice(0, 768);
+}
+
 export function controlInspectDefinitionBytes(definition = CONTROL_INSPECT_FUNCTION_DEFINITION) {
   return Buffer.byteLength(JSON.stringify(definition), "utf8");
 }
@@ -172,13 +244,7 @@ export function parseControlInspectFunctionArguments(argumentsValue, trustedCont
     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 } : {}),
+    ...Object.fromEntries(Object.entries(selectorKeys).filter(([field]) => argumentsValue[field] !== undefined).map(([field, key]) => [key, argumentsValue[field]])),
     ...(argumentsValue.all_active !== undefined ? { allActive: argumentsValue.all_active } : {}),
     surface: trustedContext.surface,
     expectedVersion: trustedContext.expectedVersion,
@@ -186,8 +252,7 @@ export function parseControlInspectFunctionArguments(argumentsValue, trustedCont
   });
 }
 
-// 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`.
+// Shared language, target and read-selection rules; errors carry the invalid 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}`);
@@ -207,19 +272,37 @@ export function normalizeControlInspectInput(input) {
   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;
+  if (input.targetId !== undefined && (!primaryTarget || !/^sha256:[0-9a-f]{64}$/u.test(input.targetId)))
+    throw new SkillDispatchInputError('target_id', 'A valid target hash requires a confirmed target');
   const runId = input.runId || null;
+  const planning = input.planning;
+  if (planning !== undefined && (schemaDiagnostics(planning, PLANNING_SCOPE_SCHEMA).length || runId || input.expectedRevisionId !== undefined || input.gate !== undefined
+    || !primaryTarget || !fieldModel.planning.operations.includes(operation))) throw new SkillDispatchInputError('planning', 'Planning requires one exact pre-Run source scope and confirmed target; no Run/revision/gate');
+  if (operation === 'operation-status' && Boolean(planning) !== /^(?:planned_ur\.|run\.create_from_planned\/)/u.test(input.contractModule ?? ''))
+    throw new SkillDispatchInputError('planning', 'Pre-Run planning status needs its original operation kind/UUID and planning scope');
   if (runId && !RUN_ID_PATTERN.test(runId)) throw new SkillDispatchInputError("run_id", "run_id is invalid");
-  if (operation === "artifact-readiness") {
+  if (runId && input.allActive === true) throw new SkillDispatchInputError('all_active', 'All-active and selected Run scopes cannot be combined');
+  if (operation === 'planned-inventory' || operation === 'planned-entry' || operation === 'authoring-inputs' && planning) {
+    if (!primaryTarget || runId || input.expectedRevisionId !== undefined || input.gate !== undefined || operation !== 'planned-inventory' && !planning)
+      throw new SkillDispatchInputError('planning', 'A confirmed target and planning scope are required; inventory needs only the target');
+  } else if (operation === 'project-state') {
+    if (!primaryTarget || runId || input.expectedRevisionId !== undefined || input.gate !== undefined) throw new SkillDispatchInputError('binding', 'Project state requires only the confirmed target, no Run/revision');
+  } else 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');
+    const creation = !runId && input.expectedRevisionId === undefined && (operation === 'operation-status'
+      || operation === 'operation-contract' && (['agdf_run/run.create', 'agdf_project/project.initialize'].includes(input.contractModule) || input.contractModule?.startsWith('agdf_project/planned_layout.')
+        || PLANNING_COMMAND_KINDS.includes(input.contractModule?.split('/')[1])));
+    if (!primaryTarget || !creation && (!runId || !REVISION_ID_PATTERN.test(input.expectedRevisionId ?? ''))) throw new SkillDispatchInputError('binding', 'An exact target, Run and expected revision binding is required; creation lookup uses target/original UUID');
     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 (operation === 'operation-status' && !(REVISION_ID_PATTERN.test(input.contractModule ?? '')
+      || !runId && /^(?:project\.initialize|planned_layout\.apply|planned_ur\.(?:create|replace)|run\.create_from_planned)\/[0-9a-f-]{36}$/u.test(input.contractModule ?? '')
+        && REVISION_ID_PATTERN.test(input.contractModule.split('/')[1]))) 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");
@@ -228,7 +311,7 @@ export function normalizeControlInspectInput(input) {
     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)) {
+  } else if (input.presentationId !== undefined || input.cursor !== undefined && !((operation === 'authoring-inputs' || operation === 'doctor' && input.allActive === true || 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");
@@ -237,12 +320,12 @@ export function normalizeControlInspectInput(input) {
   validateReadSelection({
     operation,
     allActive: input.allActive === true,
-    contractModule: input.contractModule,
+    contractModule: input.contractModule, allowContractIndex: true,
     variant: input.variant,
+    runId,
   });
-  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}`);
+    if (input[key] !== undefined && !(fieldModel[field].operations ?? CONTROL_INSPECT_OPERATIONS).includes(operation)) throw new SkillDispatchInputError(field, `Unsupported selector for ${operation}`);
   }
   return Object.freeze({
     schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
@@ -253,11 +336,12 @@ export function normalizeControlInspectInput(input) {
     target_source: targetSource,
     primary_target: primaryTarget,
     run_id: runId,
+    planning,
     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,
+    kind: operation === 'operation-contract' ? input.contractModule.split('/')[1] : undefined, operation_id: operation === 'operation-status' ? input.contractModule.split('/').at(-1) : undefined,
     variant: input.variant,
     contract_module: input.contractModule,
     all_active: input.allActive === true,
@@ -269,10 +353,10 @@ 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);
+// Preserve the result envelope when enforcing the shared 1 MiB output ceiling.
+// space 0 is the compact transport form; the CLI keeps its indented output.
+export function serializeControlInspectResult(result, { space = 2 } = {}) {
+  const output = JSON.stringify(result, null, space);
   if (Buffer.byteLength(output, "utf8") <= SKILL_DISPATCH_MAX_OUTPUT_BYTES) return output;
   return JSON.stringify({
     schema_version: CONTROL_INSPECT_SCHEMA_VERSION,

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

@@ -0,0 +1,91 @@
+import { randomBytes } from 'node:crypto';
+import { ReadWorkerPool } from '../control-read/cockpit-pool.js';
+import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
+
+export function createDoctorObservationService({ budget, gitObservation, verifyRuntime,
+  poolFactory = root => new ReadWorkerPool(root, { workerURL: new URL('../control-read/doctor-worker.js', import.meta.url), timeout: 7000,
+    limits: { timeout: 7000, total: 64 * 1024 ** 2 }, maxOldGenerationSizeMb: 256, budget }), now = Date.now } = {}) {
+  const observations = new Map(); let closed = false;
+  function retire(row) {
+    if (row.retirement) return row.retirement;
+    row.retired = true; clearTimeout(row.timer);
+    row.retirement = Promise.resolve().then(() => row.pool.close()).then(() => observations.delete(row.id));
+    void row.retirement.catch(() => {}); // Unconfirmed retirement retains its counted slot.
+    return row.retirement;
+  }
+  function touch(row) {
+    row.touched = now(); clearTimeout(row.timer);
+    row.timer = setTimeout(() => void retire(row), Math.max(0, Math.min(row.created + 60000, row.touched + 30000) - now()));
+    row.timer.unref?.();
+  }
+  function snapshot(root) {
+    if (!gitObservation) return null;
+    const start = performance.now();
+    const head = gitObservation.gitValue(root, ['rev-parse', 'HEAD']);
+    if (performance.now() - start > 1500 || head === null) return null;
+    const tracked = gitObservation.gitPathList(root, ['diff', 'HEAD', '--name-only']);
+    if (performance.now() - start > 1500 || tracked === null) return null;
+    const untracked = gitObservation.gitPathList(root, ['ls-files', '--others', '--exclude-standard']);
+    if (performance.now() - start > 1500 || untracked === null) return null;
+    return { head, tracked, untracked };
+  }
+  return Object.freeze({
+    async observe(root, input, signal) {
+      const started = performance.now(); let row, provenanceMs = null;
+      const restart = { tool: 'agdf_inspect', arguments: { operation: 'doctor', presentation_language: input.presentation_language,
+        working_directory: input.working_directory, target_source: input.target_source, primary_target: input.primary_target,
+        ...(input.all_active ? { all_active: true } : input.run_id ? { run_id: input.run_id } : {}) } };
+      try {
+        if (closed) throw Object.assign(Error(), { code: 'connection_closed' });
+        if (verifyRuntime) { const start = performance.now(); try { verifyRuntime(); } finally { provenanceMs = performance.now() - start; } }
+        for (const value of observations.values()) if (!value.retired && (now() - value.created >= 60000 || now() - value.touched >= 30000)) void retire(value);
+        let offset = 0;
+        if (input.cursor) {
+          const parts = input.cursor.split(':'), [id, rawOffset] = parts;
+          const selected = observations.get(id); offset = Number(rawOffset);
+          if (!selected || selected.retired || selected.root !== root || selected.kind !== 'inventory' || !input.all_active
+            || parts.length !== 2 || !Number.isSafeInteger(offset) || offset < 0 || String(offset) !== rawOffset) {
+            throw Object.assign(Error(), { code: 'diagnostic_cursor_invalid' });
+          }
+          row = selected;
+        } else {
+          row = !input.all_active ? [...observations.values()].find(r => !r.retired && !r.pending && r.root === root && r.kind === 'selected') : null;
+          if (!row) {
+            if (observations.size >= 2) throw Object.assign(Error(), { code: 'resource_limit' });
+            row = { id: randomBytes(32).toString('hex'), root, kind: input.all_active ? 'inventory' : 'selected',
+              pool: poolFactory(root), created: now(), touched: now(), pending: false, retired: false, retirement: null };
+            observations.set(row.id, row);
+          }
+        }
+        if (row.pending) throw Object.assign(Error(), { code: 'busy' });
+        row.pending = true; touch(row);
+        const git_snapshot = snapshot(root);
+        const remaining = 7000 - (performance.now() - started);
+        if (remaining <= 0) throw Object.assign(Error(), { code: 'timeout' });
+        const report = await row.pool.request({ operation: input.cursor ? 'doctor_page' : 'doctor_open',
+          input: { all_active: input.all_active, run_id: input.run_id, git_snapshot, offset } }, signal, { timeout: remaining });
+        row.pending = false; touch(row); row.last = report;
+        const { next_offset, ...body } = report;
+        return { ...body, target_id: resolveControlCommandTarget(root).target_id, observation_id: row.id,
+          findings_scope: 'current_page', summary_scope: report.completeness === 'complete' ? 'observation' : 'current_page',
+          overall_status: report.completeness === 'complete' ? report.status : null,
+          next_cursor: next_offset === null ? null : `${row.id}:${next_offset}`,
+          next_calls: next_offset === null ? [] : [{ ...restart, arguments: { ...restart.arguments, cursor: `${row.id}:${next_offset}` } }],
+          timing: { ...report.timing, provenance_ms: provenanceMs, provenance_state: verifyRuntime ? 'verified' : 'not_configured',
+            worker_startup_ms: row.pool.lastTiming?.startup_ms ?? null, total_ms: performance.now() - started }, authorizes: false };
+      } catch (e) {
+        if (row && !['busy', 'diagnostic_cursor_invalid'].includes(e.code)) { row.pending = false; void retire(row); }
+        else if (row && e.code === 'diagnostic_cursor_invalid') row.pending = false;
+        return { schema_version: '1', available: false, status: 'incomplete', completeness: 'incomplete', reason: e.code ?? 'read_failed',
+          observed_as_of: row?.last?.observed_as_of ?? null, inventory: row?.last?.inventory ?? null,
+          source_currentness: e.code === 'source_changed' ? 'stale' : 'unconfirmed', overall_status: null,
+          next_cursor: null, next_calls: [restart], authorizes: false,
+          timing: { total_ms: performance.now() - started, provenance_ms: provenanceMs, capture_and_evaluation_ms: null,
+            unavailable_reason: 'operation_did_not_complete' } };
+      }
+    },
+    async close() { closed = true; await Promise.all([...observations.values()].map(retire)); },
+    inspectOwnership() { return { observations: observations.size, active: [...observations.values()].filter(r => !r.retired).length,
+      inflight: [...observations.values()].filter(r => r.pending).length }; },
+  });
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/project-operation-call.js

@@ -0,0 +1,5 @@
+export const projectOperationStatusCall = input => ({ tool: 'agdf_inspect', arguments: {
+  operation: 'operation-status', module: `project.initialize/${input.operation_id}`,
+  presentation_language: input.presentation_language, working_directory: input.working_directory,
+  primary_target: input.primary_target, target_source: input.target_source } });
+

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

@@ -0,0 +1,48 @@
+import { realpathSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { inspectCanonicalProject, inspectCanonicalInitializationPlan } from '../control-state/canonical-initialization.js';
+import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
+
+import { projectOperationStatusCall } from './project-operation-call.js';
+export { projectOperationStatusCall };
+
+export function assertProjectGitRoot(root, gitObservation) {
+  const gitRoot = gitObservation?.gitValue(root, ['rev-parse', '--show-toplevel']);
+  if (!gitRoot) throw Error('confirmed_git_project_required');
+  const confirmedRoot = realpathSync(root), reportedRoot = realpathSync(gitRoot);
+  const rootStat = lstatSync(confirmedRoot, { bigint: true }), reportedStat = lstatSync(reportedRoot, { bigint: true });
+  // Windows realpath preserves spelling/case. Prove the same directory object,
+  // without case folding or rounding its filesystem identity through Number.
+  if (!rootStat.isDirectory() || !reportedStat.isDirectory() || rootStat.ino <= 0n
+    || rootStat.dev !== reportedStat.dev || rootStat.ino !== reportedStat.ino) throw Error('confirmed_git_project_required');
+  const path = join(root, '.git'), stat = lstatSync(path, { bigint: true });
+  if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile() || stat.isFile() && stat.size > 4096n)
+    throw Error('confirmed_git_project_required');
+  return { root: confirmedRoot, root_dev: String(rootStat.dev), root_ino: String(rootStat.ino), git: realpathSync(path), dev: String(stat.dev), ino: String(stat.ino),
+    content: stat.isFile() ? readFileSync(path, 'utf8') : null };
+}
+
+export function inspectProjectState(root, input, gitObservation) {
+  try {
+    const repository = assertProjectGitRoot(root, gitObservation);
+    const target_id = resolveControlCommandTarget(root).target_id;
+    const state = inspectCanonicalProject(root, { operationId: input.operation_id });
+    const common = { presentation_language: input.presentation_language, working_directory: input.working_directory,
+      primary_target: root, target_source: input.target_source };
+    const next = state.status === 'initialized' ? { tool: 'agdf_inspect', arguments: { ...common, operation: 'operation-contract', module: 'agdf_run/run.create' } }
+      : state.status === 'absent' ? { tool: 'agdf_inspect', arguments: { ...common, operation: 'operation-contract', module: 'agdf_project/project.initialize' } }
+      : state.operation && input.operation !== 'operation-status' ? projectOperationStatusCall({ ...input, operation_id: state.operation.operation_id }) : null;
+    const original = state.receipt?.operation?.operation_id;
+    const statusCall = state.status === 'initialized' && original && input.operation !== 'operation-status'
+      ? projectOperationStatusCall({ ...input, operation_id: original }) : null;
+    const report = { available: true, target_id, repository, plan: inspectCanonicalInitializationPlan(), ...state,
+      setup: { tool: 'agdf_project', kind: 'project.initialize', binding: { schema_version: '1', assurance: 'cooperative_local', ...common, target_id },
+        required_agent_fields: ['operation_id'], requires_explicit_intent: true }, next_calls: [...(next ? [next] : []), ...(statusCall ? [statusCall] : [])],
+      ...(input.operation === 'operation-status' ? { operation_id: input.operation_id, status: state.operation_status, current_setup: state.status } : {}),
+      ...(state.status === 'pending' ? { recovery: { action: 'replay_original', operation_id: state.operation.operation_id,
+        request_digest: state.operation.request_digest, instruction: 'Replay only the saved original project.initialize UUID/payload. Owned stage, target, plan and producer are revalidated before any effect.', authorizes: false } } : {}),
+      limits: { result_bytes: 16384, source_bytes: 131072, plan_bytes: 524288, receipt_bytes: 16384 }, authorizes: false };
+    if (Buffer.byteLength(JSON.stringify(report)) > 16384) throw Error('project_result_budget_exceeded');
+    return report;
+  } catch (error) { return { available: false, status: 'blocked', reason: error.code ?? error.message, authorizes: false }; }
+}

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

@@ -0,0 +1,61 @@
+import { CONTROL_INSPECT_SCHEMA_VERSION, CONTROL_INSPECT_CONTRACT_VERSION } from "./contract.js";
+import { emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
+
+export function baseResult({ outcome, operation, runtime, timing }) {
+  return {
+    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
+    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
+    outcome,
+    terminal: outcome !== "inspect_result",
+    authorizes: false,
+    operation: operation ?? null,
+    runtime,
+    target: null,
+    report: null,
+    presentation: null,
+    recovery: null,
+    host_action: null,
+    timing,
+    diagnostics: [],
+  };
+}
+
+export function bindHostAction(result) {
+  if (result.outcome === "inspect_result") {
+    result.host_action = Object.freeze({
+      mode: "consume_report_and_continue",
+      source: result.presentation?.markdown ? "presentation.markdown" : "report",
+      ...(result.presentation?.markdown ? { text: result.presentation.markdown } : {}),
+      allow_surrounding_text: true,
+      may_request_run_or_evidence: false,
+    });
+  } else if (result.presentation?.markdown) {
+    result.host_action = Object.freeze({
+      mode: "transmit_presentation_verbatim_and_stop",
+      source: "presentation.markdown",
+      text: result.presentation.markdown,
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    });
+  } else {
+    result.host_action = Object.freeze({
+      mode: "transmit_recovery_verbatim_and_stop",
+      source: "recovery.action",
+      text: result.recovery?.action ?? "",
+      allow_surrounding_text: false,
+      may_request_run_or_evidence: false,
+    });
+  }
+  return Object.freeze(result);
+}
+
+export function createInspectFailureResult(code, runtime, action, { elapsedMs } = {}) {
+  const timing = Object.fromEntries(Object.keys(emptySkillDispatchTiming()).map(key => [key, null]));
+  timing.total_ms = Number.isFinite(elapsedMs) && elapsedMs >= 0 ? elapsedMs : null;
+  timing.measurement_state = 'unavailable'; timing.unavailable_reason = 'operation_did_not_complete';
+  const result = baseResult({ outcome: "evaluator_error", runtime, timing });
+  result.recovery = { action };
+  result.diagnostics = [{ code }];
+  return bindHostAction(result);
+}
+