create-agdf 0.20.2 → 0.30.0

package/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;
 // Shared discovery budget across hosts (SDD-005).
-export const CONTROL_INSPECT_MAX_DEFINITION_BYTES = 5000;
+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}`)));
 
@@ -27,44 +27,57 @@ function deepFreeze(value) {
 
 // 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; never prepare or approve.', schema: { enum: [...CONTROL_INSPECT_OPERATIONS] }, description: 'Read action.' },
-  presentation_language: { help: 'Required BCP47 tag; unsupported valid languages fall back to complete English.', schema: { type: 'string', maxLength: 64, pattern: PRESENTATION_LANGUAGE_TAG_PATTERN_SOURCE }, description: 'Reply BCP47 tag.' },
+  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.' },
-  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. Never with gate-check.', operations: ['artifact-readiness', 'operation-contract', ...PRESENTATION_OPERATIONS] },
+  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: 'Copy target hash from operation-contract binding or catalog read_arguments; never grants authority.', schema: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, description: 'Target hash: operation-contract.', operations: PRESENTATION_OPERATIONS },
-  cursor: { help: 'Omit initially; copy next_cursor. Catalog cursors: only operation-contract module=agdf_prepare/presentation.prepare. Never exchange cursor types.', schema: cursorSchema, description: 'Copy next_cursor.', operations: [...PRESENTATION_OPERATIONS, 'operation-contract'] },
+  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.', 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: 'All runs: doctor/delivery-map.' },
+  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' };
+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'] } },
   ],
@@ -72,12 +85,23 @@ const inputSchema = {
 
 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: language, cwd, target_source+primary_target, Run; omit gate/module. Follow navigation.next_calls sequentially; read all pages.",
+  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: {
@@ -112,7 +136,7 @@ export const CONTROL_INSPECT_OUTPUT_SCHEMA = deepFreeze(inspectContract.outputSc
 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' } } },
@@ -123,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)}` } ],
+      { ...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");
 }
@@ -201,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");
@@ -222,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");
@@ -231,11 +320,12 @@ export function normalizeControlInspectInput(input) {
   validateReadSelection({
     operation,
     allActive: input.allActive === true,
-    contractModule: input.contractModule,
+    contractModule: input.contractModule, allowContractIndex: true,
     variant: input.variant,
+    runId,
   });
   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,
@@ -246,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,
@@ -263,8 +354,9 @@ 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.";
 
 // Preserve the result envelope when enforcing the shared 1 MiB output ceiling.
-export function serializeControlInspectResult(result) {
-  const output = JSON.stringify(result, null, 2);
+// 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/runtime/core/lib/control-inspect/decision-session.js

@@ -1,3 +1,5 @@
+import { resolutionRecordVersion } from '../control-state/input-resolution.js';
+import { createPresentationDelivery } from '../control-state/presentation-delivery.js';
 import { randomUUID, createHash } from 'node:crypto';
 import { createCockpitSessionService } from './cockpit-session.js';
 import { COCKPIT_LIMITS, parseCockpitArguments } from './cockpit-contract.js';
@@ -19,15 +21,26 @@ 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),
+  delivery = createPresentationDelivery({ now }), appOnlyMediationQualified = false, readServiceFactory = root => createCockpitSessionService(root),
+  // Only a host adapter with actual current-surface identity may supply this
+  // private observation. Client name/version, tool arguments and UI capability
+  // cannot supply it. The current SDK adapter has no such observation.
+  surfaceBinding = () => null,
   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 currentMaterial(row) {
+    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 false;
+    const material = decisionMaterial(row.root, prepareRunContentState(row.root, run.content, run.path), row.binding.gate);
+    return material.available && material.material_version === row.binding.material_version;
+  }
   function retire(row) {
     if (row.retirement) return row.retirement;
+    row.primary = false; row.displayed = false;
     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.
@@ -45,12 +58,14 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
     row.timer.unref?.();
   }
   return Object.freeze({
+    remember: delivery.remember, prepared: delivery.prepared, deliver: delivery.deliver,
     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 = {}) {
+      delivery.remember(input, result);
       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);
@@ -65,7 +80,7 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
       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'
+      if (resolutionRecordVersion(presentation.record) === 7 && (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' };
       }
@@ -74,14 +89,22 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
         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 };
+        expires: now() + COCKPIT_LIMITS.lifetime, generation: ++generation, retired: false, retirement: null, readId: null, timer: null, pending: null,
+        nonce: randomUUID(), surface: surfaceBinding(host), displayed: false, primary: false };
+      const preparedDelivery = delivery.prepared({ ...input, operation_id: prepared.presentation_id });
+      if (!preparedDelivery || preparedDelivery.selected) return { ...result, app_capability: 'unavailable', app_reason: 'delivery_already_selected' };
+      preparedDelivery.view = {
+        confirm: host => active(row.id) === row && Boolean(row.displayed) && row.surface !== null && row.surface === surfaceBinding(host)
+          && now() - row.displayed < 10000 && currentMaterial(row),
+        select: () => { row.primary = true; }, retire: () => retire(row),
+      };
       // 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.hasSnapshot = resolutionRecordVersion(presentation.record) === 7;
+      row.previewRecord = (resolutionRecordVersion(presentation.record) === 7 && presentation.record.preview_review) ? presentation.record : null;
       row.previewResourceId = row.previewRecord ? randomUUID() : null;
       row.presentationText = row.presentationDocument ? prepared.text : null;
       row.presentedContentSeal = presentation.record.content_digest;
@@ -116,10 +139,11 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
         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,
+            delivery_state: 'preview', display_nonce: row.nonce, surface_id: row.surface,
             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),
+            summary: row.presentationText ?? prepared.text,
+            decision_brief: 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]
@@ -128,6 +152,7 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
               ?? interactionLocales.locales.en.primary.afterApproval[binding.gate]),
             snapshot_id: snapshot.snapshot_id, resource_id: resource?.resource_id ?? null,
             document_digest: row.documentDigest,
+            source_digest: presentation.record.artefact_digest,
             ...(row.previewRecord ? { preview: { resource_id: row.previewResourceId,
               version: row.previewRecord.preview_review.descriptor.version,
               task: row.previewRecord.preview_review.descriptor.review_task,
@@ -135,9 +160,9 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
               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') : [],
+            enabled_actions: [],
             capability: row.qualified ? 'available' : 'not_qualified',
-            comparison: presentationVersionComparison(root, state, binding.gate, row.documentDigest) } } };
+            comparison: presentationVersionComparison(root, state, binding.gate, presentation.record.artefact_digest) } } };
       } catch (error) {
         await retire(row).catch(() => {});
         return { ...result, app_capability: 'unavailable', app_reason: error.message };
@@ -151,6 +176,7 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
       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 (!row.primary || !row.displayed || row.surface !== surfaceBinding(host)) return failure('decision_display_unconfirmed');
       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;
@@ -161,11 +187,27 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
       if (active(row.id) !== row || row.generation !== captured) return { ...result, view_state: 'closed' };
       touch(row); return { ...result, view_state: 'active' };
     },
-    async read(input, signal) {
+    async read(input, signal, host = {}) {
       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 (['decision_display', 'decision_state'].includes(input.operation)) {
+        if (!currentMaterial(row)) { await retire(row).catch(() => {}); return failure('decision_binding_changed'); }
+        if (delivery.prepared(row.binding)?.selected && !row.primary) { await retire(row).catch(() => {}); return failure('delivery_already_selected'); }
+        if (input.operation === 'decision_display') {
+          if (!row.surface || row.surface !== surfaceBinding(host) || input.surface_id !== row.surface || input.owner_epoch !== epoch
+            || input.nonce !== row.nonce || input.document_digest !== row.documentDigest || input.visible !== true) return failure('decision_display_unconfirmed');
+          const preparedDelivery = delivery.prepared(row.binding);
+          if (preparedDelivery?.selected) return failure('delivery_already_selected');
+          row.displayed = now();
+        }
+        if (row.primary && row.surface === surfaceBinding(host)) row.displayed = now();
+        touch(row);
+        return { schema_version: '1', state: 'available', data: { delivery_state: row.primary ? 'ui_primary' : 'preview',
+          display: row.displayed ? 'confirmed' : 'unconfirmed', document_digest: row.documentDigest,
+          enabled_actions: row.primary && row.qualified ? enabledDecisionActions(groups).filter(a => a === 'approve') : [] }, 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');
@@ -238,6 +280,6 @@ export function createDecisionSessionService({ groups = Object.keys(RUN_COMMAND_
       }
       return result;
     },
-    async close() { closed = true; await Promise.allSettled([...sessions.values()].map(retire)); },
+    async close() { closed = true; delivery.close(); await Promise.allSettled([...sessions.values()].map(retire)); },
   });
 }

package/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/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 } });
+