create-agdf 0.20.1 → 0.30.0

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

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

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

@@ -1,9 +1,11 @@
 // Shared read-only selection policy for CLI and MCP; evaluation never writes control state.
 
-export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations"]);
+export const ARTIFACT_READINESS_GATES = Object.freeze(['UR', 'PRD', 'SD', 'TP']);
+export const CONTROL_INSPECT_OPERATIONS = Object.freeze(["doctor", "gate-check", "delivery-map", "contract", "artifact-readiness", "authoring-inputs", "operation-contract", "operation-status", "native-qualification", "presentation-document", "presentation-preview", "runtime-generations", "project-state", "inventory", "planned-inventory", "planned-entry"]);
 export const ALL_ACTIVE_OPERATIONS = Object.freeze(["doctor", "delivery-map"]);
 export const VARIANT_OPERATION = "gate-check";
 export const MODULE_OPERATION = "contract";
+export const INVENTORY_OPERATION = "inventory";
 export const GATE_CHECK_VARIANTS = Object.freeze(["status-card", "approval-envelope"]);
 
 export class ReadSelectionError extends Error {
@@ -16,14 +18,18 @@ export class ReadSelectionError extends Error {
 
 // `operation` is the CLI command name or the MCP operation. Rules apply to every command so that a
 // write command carrying a read-only flag is rejected exactly as before the extraction.
-export function validateReadSelection({ operation, allActive = false, contractModule, variant } = {}) {
+export function validateReadSelection({ operation, allActive = false, contractModule, variant, runId, allowContractIndex = false } = {}) {
+  // The inventory always lists every run; a run selection would silently narrow it.
+  if (runId && [INVENTORY_OPERATION, 'planned-inventory', 'planned-entry'].includes(operation)) {
+    throw new ReadSelectionError("run_id", "--run is not supported by inventory; it lists every run");
+  }
   if (allActive && !ALL_ACTIVE_OPERATIONS.includes(operation)) {
     throw new ReadSelectionError("all_active", "--all-active is supported only by doctor and delivery-map");
   }
   if (contractModule !== undefined && ![MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation)) {
     throw new ReadSelectionError("module", "--module is supported only by contract");
   }
-  if ([MODULE_OPERATION, 'operation-contract', 'operation-status'].includes(operation) && !contractModule) {
+  if ((operation === MODULE_OPERATION && !allowContractIndex || ['operation-contract', 'operation-status'].includes(operation)) && !contractModule) {
     throw new ReadSelectionError("module", "contract requires --module");
   }
   if (variant !== undefined && operation !== VARIANT_OPERATION) {

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

@@ -1,17 +1,21 @@
+import { baseResult, bindHostAction } from "./result.js";
+import { inspectArtefactRecordingMode } from '../control-state/run-artefact-recording.js';
+import { inspectProjectState } from './project-state.js';
 import process from "node:process";
 import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
 import { buildStatusCard, evaluateGateCheck, postApprovalTransition, printApprovalEnvelope, printGateCheckReport } from "../control-evaluation/gate-check.js";
 import { evaluateDoctor } from "../control-evaluation/doctor.js";
 import { evaluateDeliveryMap } from "../control-evaluation/delivery-map.js";
-import { readRuntimeContract } from "../resources/contracts.js";
-import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory } from "../interaction-presentation.js";
+import { readRuntimeContract, runtimeContractModules } from "../resources/contracts.js";
+import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory, renderRunInventory } from "../interaction-presentation.js";
 import { resolveTaskTarget, TaskTargetInputError } from "../task-target-resolution.js";
 import { SKILL_DISPATCH_PRESENTATION_LANGUAGE_RECOVERY, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
-import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, PRESENTATION_CATALOG_MODULE } from "./contract.js";
-import { operationContract } from '../control-state/run-command-contract.js';
+import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, OPERATION_CONTRACT_MODULES, PRESENTATION_CATALOG_MODULE } from "./contract.js";
+import { RUN_COMMAND_DESCRIPTORS, operationContract } from '../control-state/run-command-contract.js';
 import { inspectRunOperation } from '../control-state/run-operation-status.js';
 import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
 import { readRunState } from '../control-evaluation/run-state.js';
+import { readRunInventory } from '../control-state/run-inventory-reader.js';
 import { inspectArtifactReadiness } from "./artifact-readiness.js";
 import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
 import { parseRunState } from '../control-state/run-state-parser.js';
@@ -21,12 +25,19 @@ import { readPresentationDocument, readPresentationPreview, readPresentationCata
 import { sourceRevisionBoundary } from '../control-state/run-revision-boundary.js';
 import { sourceRevisionQualityFacts } from '../control-state/run-source-revisions.js';
 import { readHistoryBytes } from '../control-state/run-revision-history.js';
+import { creationRunId } from '../control-state/run-create-command.js';
+import { inspectAuthoringInputs } from './authoring-inputs.js';
+import { PLANNING_COMMAND_KINDS } from '../control-state/run-command-schema.js';
+import { inspectPlannedEntry, inspectPlannedOperation, plannedEntryPath } from '../control-state/planned-entry.js';
+import { controlPathPresent } from '../control-read/snapshot.js';
+import { inspectPlannedHandoffOperation } from '../control-state/planned-handoff.js';
+import { readPlannedInventory, readWorkInventory } from '../control-state/planned-inventory.js';
+import { readControlLayout, CURRENT_LAYOUT } from '../control-state/control-layout.js';
+import { existsSync } from '../control-read/fs.js';
+import { join } from 'node:path';
 
-// The MCP read tool is a projection over the existing evaluators. It calls exactly the functions the
-// CLI handlers call and returns their --json report. Draft preflight additionally composes those
-// existing content validators through its read-only Core owner; it adds no CLI command. It never writes,
-// never selects a run on its own and never prepares an approval binding. Evaluators run with the
-// dispatcher's dependency set: no git child process, so verified_change git observation is absent.
+// Read-only projection of canonical CLI evaluators and Core validators. It never
+// writes, selects a Run or prepares approval. Git observations are unavailable.
 
 const defaultNow = () => process.hrtime.bigint();
 const milliseconds = (start, end) => Number(end - start) / 1_000_000;
@@ -67,61 +78,6 @@ function runtimeEvidence(expectedVersion, evidence, env) {
   });
 }
 
-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: [],
-  };
-}
-
-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) {
-  const result = baseResult({ outcome: "evaluator_error", runtime, timing: emptySkillDispatchTiming() });
-  result.recovery = { action };
-  result.diagnostics = [{ code }];
-  return bindHostAction(result);
-}
-
 function gateCheckPresentation(report, variant, reEvaluate) {
   if (variant === "approval-envelope" || variant === "status-card") {
     const lines = [];
@@ -146,10 +102,11 @@ export function createControlInspectService(dependencies = {}) {
   const gateCheck = dependencies.evaluateGateCheck ?? evaluateGateCheck;
   const deliveryMap = dependencies.evaluateDeliveryMap ?? evaluateDeliveryMap;
   const readContract = dependencies.readRuntimeContract ?? readRuntimeContract;
+  const readModules = dependencies.runtimeContractModules ?? runtimeContractModules;
   const validateControlReadBoundary = dependencies.validateControlReadBoundary;
   const deliveryMapDependencies = Object.freeze({ evaluateDoctor: doctor, buildStatusCard, postApprovalTransition });
 
-  return function executeControlInspect(rawInput) {
+  return function executeControlInspect(rawInput, { signal } = {}) {
     const started = now();
     const timing = emptySkillDispatchTiming();
     const runtime = runtimeEvidence(rawInput.expectedVersion, dependencies.runtimeEvidence, env);
@@ -199,8 +156,35 @@ export function createControlInspectService(dependencies = {}) {
         timing.total_ms = round(milliseconds(started, now()));
         return bindHostAction(result);
       }
+      if (input.target_id && resolveControlCommandTarget(target.governance_target).target_id !== input.target_id) {
+        const result = baseResult({ outcome: 'invalid_input', operation: input.operation, runtime, timing });
+        result.target = target;
+        result.diagnostics = [{ code: 'target_binding_mismatch', field: 'target_id' }];
+        result.recovery = { action: renderInputRecovery({ field: 'target_id', allowedValues: [] },
+          { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language }) };
+        timing.total_ms = round(milliseconds(started, now()));
+        return bindHostAction(result);
+      }
+      if (input.operation === 'doctor' && dependencies.observeDoctor) {
+        const controlStarted = now();
+        return Promise.resolve(dependencies.observeDoctor(target.governance_target, input, signal)).then(report => {
+          timing.control_ms = round(milliseconds(controlStarted, now()));
+          const result = baseResult({ outcome: 'inspect_result', operation: input.operation, runtime, timing });
+          result.target = target; result.report = report;
+          // Reuse the existing localized inventory only when this reply holds
+          // the complete inventory. Paged replies remain explicit scoped data;
+          // the agent follows every advertised cursor before summarizing them.
+          if (input.all_active && report.available && report.completeness === 'complete'
+            && report.inventory?.accounted_count === report.runs?.length + (report.invalid_entries?.length ?? 0)) {
+            const renderStarted = now();
+            result.presentation = renderActiveRunInventory(report, rawInput.interactionLocales, input.presentation_language);
+            timing.render_ms = round(milliseconds(renderStarted, now()));
+          }
+          timing.total_ms = round(milliseconds(started, now())); return bindHostAction(result);
+        });
+      }
       const controlStarted = now();
-      const { report, presentation, invalidModule } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
+      const { report, presentation, invalidModule, navigation } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
         validateControlReadBoundary?.(target.governance_target);
         const selection = {
           ...(input.run_id ? { runId: input.run_id } : {}),
@@ -208,11 +192,14 @@ export function createControlInspectService(dependencies = {}) {
         };
         switch (input.operation) {
           case 'presentation-document':
-          case 'presentation-preview':
-            return { report: (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
+          case 'presentation-preview': {
+            const report = (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
               runId: input.run_id, gate: input.gate, revisionId: input.expected_revision_id,
               presentationId: input.presentation_id, targetId: input.target_id, cursor: input.cursor,
-            }), presentation: null };
+            });
+            if (input.operation === 'presentation-document' && report.available) report.delivery_instruction = 'If full text is requested and an explicitly configured verified host renderer consumes these MCP pages, fetch all next_cursor pages with the exact original binding; let that renderer verify and output the bytes. Otherwise send this content verbatim in a user-visible agent message BEFORE fetching next_cursor, repeating in byte order. Tool output alone is not delivery. Retain already read pages. Never claim complete delivery from a successful read alone. Rendering is not human approval.';
+            return { report, presentation: null };
+          }
           case 'runtime-generations':
           case 'native-qualification': {
             const state = readRunState(target.governance_target, { runId: input.run_id });
@@ -228,11 +215,21 @@ export function createControlInspectService(dependencies = {}) {
                 next_operation: decision.next_operation, blocking_reason: decision.blocking_reason }, authorizes: false }, presentation: null };
           }
           case 'operation-contract': {
+            if (PLANNING_COMMAND_KINDS.includes(input.kind) && !input.run_id) {
+              const contract = operationContract(input.group, input.kind);
+              return { report: { ...contract, binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+                next_calls: [{ tool: input.group, kind: input.kind, instruction: contract.planning_capture?.instructions
+                  ?? 'Use the confirmed planning scope and original UUID; no Run/revision. Planning never approves a gate. Start a Run only from a deliberately selected complete source.' }] }, presentation: null };
+            }
+            if (['agdf_run', 'agdf_project'].includes(input.group) && !input.run_id) return { report: { ...operationContract(input.group, input.kind),
+              binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+              next_calls: [{ tool: input.group, kind: input.kind, instruction: input.group === 'agdf_project' ? 'Explicit fixed setup only. Use the confirmed existing Git root and one original UUID. No Run/revision, force, repair, install or approval.' : 'Use a new original operation UUID and confirmed title; there is no prior Run/revision.' }] }, presentation: null };
             const state = readRunState(target.governance_target, { runId: input.run_id });
             const targetId = resolveControlCommandTarget(target.governance_target).target_id;
             const valid = parseRunState(state.content, input.run_id).valid && state.meta?.revision_id === input.expected_revision_id
               && runSealState(target.governance_target, state.content).status === 'valid';
-            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate }),
+            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate ?? state.current_gate }),
+              ...(input.kind === 'artefact.record' ? { recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) } : {}),
               ...(input.contract_module === PRESENTATION_CATALOG_MODULE ? {
                 inspect_contract: inspectContractHelp(),
                 presentation_catalog: readPresentationCatalog(target.governance_target, { runId: input.run_id,
@@ -255,13 +252,46 @@ export function createControlInspectService(dependencies = {}) {
                   source_bindings: readArtefactBindings(state.content).active.map(row => ({ binding_id: row.binding_id, source: row.source, destination: row.destination, relationship: row.relationship })) }; })() }
               : { available: false, authorizes: false, reason: 'operation_binding_stale_or_invalid' }, presentation: null };
           }
+          case 'project-state':
+            return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
           case 'operation-status':
-            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id, operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id }, presentation: null };
+            if (input.planning) return { report: input.contract_module.startsWith('run.create_from_planned/')
+              ? inspectPlannedHandoffOperation(target.governance_target, input.planning.plan_id, input.operation_id)
+              : inspectPlannedOperation(target.governance_target, input.planning.plan_id, input.operation_id), presentation: null };
+            if (input.contract_module.startsWith('project.initialize/')) return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
+            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id ?? creationRunId(input.operation_id), operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id ?? null,
+              ...(!input.run_id ? { lookup_scope: 'run_creation', recovery_instruction: 'This target-only lookup is for Run creation. For a write to an existing Run, inspect operation-status with the original run_id, original expected_revision_id and the same original UUID in module. An unavailable creation lookup does not prove an approval effect. Never substitute a fresh UUID or infer success from a changed gate alone.' } : {}) }, presentation: null };
           case "artifact-readiness":
             return { report: inspectArtifactReadiness(target.governance_target, {
               runId: input.run_id, gate: input.gate, expectedRevisionId: input.expected_revision_id,
               presentationLanguage: input.presentation_language,
             }), presentation: null };
+          case 'authoring-inputs':
+            return { report: inspectAuthoringInputs(target.governance_target, input, { gitObservation: dependencies.gitObservation }), presentation: null };
+          case 'planned-inventory': {
+            const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+            return { report: { ...inventory, available: inventory.state !== 'unavailable' }, presentation: null };
+          }
+          case 'planned-entry': {
+            const path = plannedEntryPath(input.planning.plan_id);
+            if (!controlPathPresent(target.governance_target, `${path}/UR.md`)) {
+              const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+              const unavailable = inventory.state === 'unavailable', incomplete = existsSync(join(target.governance_target, path));
+              return { report: { available: false, state: unavailable ? 'unavailable' : 'missing',
+                reason: unavailable ? 'planning_store_unavailable' : incomplete ? 'planned_document_missing' : 'planned_entry_missing',
+                plan_id: input.planning.plan_id, authorizes: false,
+                ...(unavailable ? { findings: inventory.findings } : {}),
+                ...(!unavailable && !incomplete && input.planning.expected_digest === null ? { next_calls: [{ tool: 'agdf_inspect',
+                  arguments: { operation: 'authoring-inputs', working_directory: input.working_directory,
+                    target_source: input.target_source, primary_target: input.primary_target,
+                    presentation_language: input.presentation_language, planning: input.planning },
+                  instruction: 'Read the version-matched UR inputs before capture. Planning authoring needs no module, gate, Run or revision.' }] } : {}) }, presentation: null };
+            }
+            const entry = inspectPlannedEntry(target.governance_target, input.planning.plan_id, { presentationLanguage: input.presentation_language });
+            return { report: input.planning.expected_digest && input.planning.expected_digest !== entry.digest
+              ? { available: false, reason: 'planning_source_stale', plan_id: input.planning.plan_id, authorizes: false }
+              : { ...entry, available: true }, presentation: null };
+          }
           case "doctor": {
             const evaluated = doctor(target.governance_target, selection);
             return { report: evaluated, presentation: input.all_active
@@ -270,13 +300,50 @@ export function createControlInspectService(dependencies = {}) {
           case "gate-check": {
             const evaluate = () => gateCheck(target.governance_target, { ...selection, presentationLanguage: input.presentation_language });
             const evaluated = evaluate();
-            return { report: evaluated, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
+            let navigation;
+            // Optional hints never replace the canonical report.
+            try {
+              if (input.run_id && input.target_source && input.primary_target && evaluated.status_card?.run_id === input.run_id) {
+                const revisionId = evaluated.status_card.runState?.meta?.revision_id;
+                const targetId = resolveControlCommandTarget(target.governance_target).target_id;
+                const common = Object.fromEntries(['presentation_language', 'working_directory', 'target_source', 'primary_target', 'run_id'].map(key => [key, input[key]]));
+                common.expected_revision_id = revisionId;
+                const catalog = readPresentationCatalog(target.governance_target, { runId: input.run_id, revisionId, targetId,
+                  gate: evaluated.current_gate, workingDirectory: input.working_directory, targetSource: input.target_source,
+                  primaryTarget: input.primary_target, language: input.presentation_language });
+                const kind = evaluated.next_operation?.operation_key;
+                const group = RUN_COMMAND_DESCRIPTORS[kind]?.group;
+                const nextCalls = [];
+                // Read the selected immutable document first. Operation help is
+                // optional and must not delay a user's read-only document task.
+                if (catalog.state === 'unique' && catalog.complete_scan && catalog.page_complete)
+                  nextCalls.push({ tool: 'agdf_inspect', arguments: catalog.candidates[0].read_arguments });
+                if (catalog.state !== 'unavailable' && group) nextCalls.push({ tool: 'agdf_inspect', arguments: {
+                  operation: 'operation-contract', ...common, module: `${group}/${kind}` } });
+                // An explicit reusable locator, not retained connection state or
+                // authority. Reuse passes through the ordinary target/Run checks.
+                const { expected_revision_id: _revision, ...readContext } = common;
+                navigation = { read_context: readContext, presentation_catalog: catalog, next_calls: nextCalls };
+              }
+            } catch { /* Advisory navigation unavailable. */ }
+            return { report: evaluated, navigation, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
+          }
+          case "inventory": {
+            // Read-only inventory also works before control initialization. An
+            // existing config still goes through strict layout validation.
+            if (existsSync(join(target.governance_target, '.agdf/control/config.json'))
+              && readControlLayout(target.governance_target).layout === CURRENT_LAYOUT) return { report: readWorkInventory(target.governance_target, { language: input.presentation_language }), presentation: null };
+            const inventory = readRunInventory(target.governance_target, { language: input.presentation_language });
+            return { report: inventory, presentation: renderRunInventory(inventory, rawInput.interactionLocales, input.presentation_language) };
           }
           case "delivery-map": {
             const evaluated = deliveryMap(target.governance_target, selection, deliveryMapDependencies);
             return { report: evaluated, presentation: null };
           }
           case "contract": {
+            if (!input.contract_module) return { report: { available: true, modules: readModules(),
+              operation_modules: OPERATION_CONTRACT_MODULES, inspect_contract: inspectContractHelp(),
+              instruction: 'contract reads a listed runtime module. operation-contract reads an exact listed group/kind; omit planning, gate and Run/revision for creation help. Copy operation-specific arguments; never copy whole command bindings.', authorizes: false }, presentation: null };
             const read = readContract(input.contract_module, { pluginRoot: null });
             if (!read.ok) return { report: null, presentation: null, invalidModule: read };
             return { report: { module: read.module, content: read.content }, presentation: { markdown: read.content, authorizes: false } };
@@ -299,6 +366,7 @@ export function createControlInspectService(dependencies = {}) {
       result.target = target;
       result.report = report;
       result.presentation = presentation;
+      if (navigation) result.navigation = navigation;
       timing.total_ms = round(milliseconds(started, now()));
       return bindHostAction(result);
     } catch (error) {
@@ -317,3 +385,5 @@ export function createControlInspectService(dependencies = {}) {
     }
   };
 }
+
+export { createInspectFailureResult } from "./result.js";