create-agdf 0.20.2 → 0.31.0

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/material-recording-calls.js

@@ -0,0 +1,54 @@
+import { resolveTaskTarget } from '../task-target-resolution.js';
+import { preparedCommandCall } from '../control-state/prepared-control-calls.js';
+import { inspectUxIntentDecision, UX_DECISION_FORMAT } from '../control-evaluation/definition-sources.js';
+import { validateRunCommand } from '../control-state/run-command-schema.js';
+import { inspectAuthoringInputs } from './authoring-inputs.js';
+
+// Mirrors an explicit author declaration; never chooses a judgement or review.
+export function withUxSourceDecision(form, content) {
+  const observed = inspectUxIntentDecision(content);
+  const source_validation = { ...observed, format: UX_DECISION_FORMAT, authorizes: false };
+  if (!observed.well_formed || !observed.supported || observed.decision === 'not_applicable') return {
+    source_validation: { ...source_validation, recordable: false,
+      reason: !observed.well_formed ? 'ux_decision_malformed' : 'ux_decision_not_supported_for_required_analysis',
+      instruction: 'Correct the explicit - decision: field in the authored report, then stage the corrected bytes with the new material_call. No canonical record was attempted; choose ready or blocked from actual analysis, never from this diagnostic.' } };
+  const filled = structuredClone(form);
+  filled.call.arguments.command.payload.decision = observed.decision;
+  filled.required_inputs = filled.required_inputs.filter(p => p !== '/command/payload/decision');
+  filled.state = validateRunCommand(filled.call.tool, filled.call.arguments).length ? 'requires_author_input' : 'ready';
+  return { form: filled, source_validation: { ...source_validation, recordable: true,
+    decision_origin: 'exact explicit author declaration in staged source; not generated judgement' } };
+}
+
+// Reuse the canonical author/source selection, including analytical prerequisites
+// at an outer gate. Transport itself cannot choose a future/protected writer.
+export function withMaterialRecordingCalls(input, result) {
+  if (result.outcome !== 'accepted' || input.planning || !['put', 'seal'].includes(input.command.payload.action)) return result;
+  try {
+    const target = resolveTaskTarget({ workingDirectory: input.working_directory, primaryTarget: input.primary_target, targetSource: input.target_source });
+    if (target.resolution_state !== 'resolved') return result;
+    const authoring = inspectAuthoringInputs(target.governance_target, input);
+    if (!authoring.available || authoring.revision_id !== input.expected_revision_id) return result;
+    const slot = authoring.material_call?.call.arguments.command.payload.files[0].slot;
+    const files = (result.family_result.files ?? []).filter(file => file.reference && file.slot === slot);
+    if (files.length !== 1 || !authoring.formats?.available) return result;
+    const { group, kind } = authoring.formats;
+    if (kind === 'closeout.record') {
+      if (!['structured_delivery', 'structured_slice'].includes(authoring.mode)
+          || authoring.next_operation?.type !== 'record_closeout' || authoring.authoring_owner !== 'OR' || slot !== 'OR') return result;
+    } else if (!['step.record', 'artefact.record', 'ur_draft.replace'].includes(kind)) return result;
+    const form = preparedCommandCall(group, kind, input,
+      { gate: authoring.authoring_owner, material: files[0].reference, recording: authoring.recording });
+    if (kind === 'closeout.record' && form?.state !== 'ready') return result;
+    if (form && authoring.authoring_owner === 'UX Intent Definition' && input.command.payload.action === 'put') {
+      const text = input.command.payload.files.find(file => file.slot === slot)?.content;
+      if (typeof text === 'string') {
+        const checked = withUxSourceDecision(form, text);
+        return { ...result, source_validation: checked.source_validation,
+          ...(checked.form ? { recording_calls: [{ slot, ...checked.form }] }
+            : { recording_calls: [], material_call: authoring.material_call }) };
+      }
+    }
+    return form && !form.required_inputs.includes('/command/payload') ? { ...result, recording_calls: [{ slot, ...form }] } : result;
+  } catch { return result; } // Guidance cannot conceal an accepted private transfer.
+}

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,49 @@
+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 ? { recovery_only: { status_call: statusCall, authorizes: false } } : {}),
+      ...(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/run-classification.js

@@ -0,0 +1,31 @@
+// Read-only run classification shared by the Codex cockpit and the companion run view (companion core
+// SDD-001, SDD-003). It lives apart from the cockpit so every runtime profile carries it, Copilot
+// included, whose projection leaves the private cockpit out. Nothing here evaluates a gate rule.
+import { ENDED_LIFECYCLES } from '../control-state/run-operations.js';
+
+// The read-failure codes passed through unchanged, and every code `boundedCode` can return.
+const READ_FAILURE_CODES = Object.freeze(['resource_denied', 'source_changed', 'timeout', 'resource_limit', 'read_failed']);
+export const BOUNDED_READ_CODES = Object.freeze(['control_layout_unsupported', 'run_version_unsupported', 'control_invalid', ...READ_FAILURE_CODES]);
+
+// Bounded reason code of a read failure.
+export function boundedCode(error) {
+  const code = error.code ?? error.message;
+  if (code === 'AGDF_CONTROL_LAYOUT_UNSUPPORTED' || code === 'control_layout_unsupported') return 'control_layout_unsupported';
+  if (code === 'AGDF_RUN_VERSION_UNSUPPORTED') return 'run_version_unsupported';
+  // The configuration owner's codes (resources/configuration.js configurationError).
+  if (code === 'AGDF_CONTROL_LAYOUT_INVALID' || code === 'configuration_invalid') return 'control_invalid';
+  return READ_FAILURE_CODES.includes(error.code) ? error.code : 'read_failed';
+}
+
+// Read-only projection of the evaluated decision, never a second gate evaluator.
+// Doctor warnings are already considered by evaluateGateCheck; they are not a UI veto.
+export function projectCockpitAssessment(report, lifecycle) {
+  const state = ENDED_LIFECYCLES.includes(lifecycle) ? 'ended'
+    : lifecycle === 'completed' ? report.completion?.fulfilled === true ? 'completed' : 'unconfirmed'
+    : lifecycle !== 'active' ? 'unconfirmed'
+    : report.status === 'blocked' || (report.blocking_reason && report.blocking_reason !== 'none')
+      || (report.missing_approval && report.missing_approval !== 'none') ? 'blocked'
+    : report.status === 'open' && report.blocking_reason === 'none' && report.missing_approval === 'none' ? 'open'
+    : 'unconfirmed';
+  return { state, authorizes: false };
+}

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

@@ -1,9 +1,17 @@
 // 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 CLOSEOUT_AUTHORING_SCOPE = 'delivery-closeout';
+
+export function isCompletedStructuredCloseout(control, mode) {
+  return control.current_gate === 'OR' && control.completion?.fulfilled === true
+    && ['structured_delivery', 'structured_slice'].includes(mode);
+}
 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 +24,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) {