create-agdf 0.20.2 → 0.31.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/mcp-input-hints.js

@@ -0,0 +1,75 @@
+import { isAbsolute } from 'node:path';
+import { CONTROL_INSPECT_FUNCTION_DEFINITION, inspectInputValidationHint } from './control-inspect/contract.js';
+import { RUN_COMMAND_DESCRIPTORS, RUN_COMMAND_GROUPS, PLANNING_COMMAND_KINDS, TARGET_SCOPED_COMMAND_KINDS, schemaDiagnostics } from './control-state/run-command-schema.js';
+import { RUN_ID_PATTERN } from './control-state/run-identity.js';
+
+function unboundCreationHelp(input) {
+  const fields = CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema.properties;
+  const keys = ['working_directory', 'primary_target', 'target_source'];
+  if (!keys.every(key => Object.hasOwn(input, key) && !schemaDiagnostics(input[key], fields[key]).length)
+    || !isAbsolute(input.working_directory) || !isAbsolute(input.primary_target)
+    || input.presentation_language !== undefined && schemaDiagnostics(input.presentation_language, fields.presentation_language).length) return null;
+  return { tool: 'agdf_inspect', arguments: { operation: 'operation-contract', module: 'agdf_run/run.create',
+    ...Object.fromEntries(keys.map(key => [key, input[key]])),
+    ...(input.presentation_language === undefined ? {} : { presentation_language: input.presentation_language }) } };
+}
+
+// Presentation only: never repairs an argument or decides permission. The SDK
+// and the canonical Core owners still validate the original request unchanged.
+export function mcpInputValidationHint(name, input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return '';
+  const messages = [];
+  if (name === 'agdf_inspect') {
+    if (input.operation === 'status') messages.push('Run status uses agdf_inspect operation gate-check. status is invalid; never dispatch a skill for a read.');
+    const hint = inspectInputValidationHint(input);
+    if (hint) messages.push(hint);
+    if (['status', 'gate-check', 'presentation-document', 'presentation-preview'].includes(input.operation)) {
+      // A new *read* suggestion, not a repaired/replayed original request. Copy
+      // only explicit locators; never infer a target, select a Run, refresh a
+      // write revision, fabricate a presentation ID or invoke a tool here.
+      const keys = ['working_directory', 'primary_target', 'target_source', 'run_id'];
+      const fields = CONTROL_INSPECT_FUNCTION_DEFINITION.inputSchema.properties;
+      if (keys.every(key => Object.hasOwn(input, key) && !schemaDiagnostics(input[key], fields[key]).length)
+        && isAbsolute(input.working_directory) && isAbsolute(input.primary_target)
+        && (input.presentation_language === undefined || !schemaDiagnostics(input.presentation_language, fields.presentation_language).length)) {
+        const args = { operation: 'gate-check', ...Object.fromEntries(keys.map(key => [key, input[key]])),
+          ...(input.presentation_language === undefined ? {} : { presentation_language: input.presentation_language }) };
+        const correction = ` Next read-only call (preserve the requested document selection): ${JSON.stringify({ tool: 'agdf_inspect', arguments: args })}`;
+        if (messages.join(' ').length + correction.length <= 768) return messages.join(' ') + correction;
+      }
+    }
+  } else if (name === 'agdf_dispatch' || Object.hasOwn(RUN_COMMAND_GROUPS, name)) {
+    if (name === 'agdf_dispatch' && input.intake_mode !== undefined && !input.run_id) {
+      messages.push('intake_mode requires intake:true and a nonempty run_id; null is invalid. Initial unbound intake omits BOTH run_id and intake_mode. For a new MCP Run, use the supplied agdf_run/run.create form and its returned binding; never invent a Run ID. A requested resume must keep its confirmed Run/revision, not switch to new.');
+      if (input.skill_id === 'gate-check' && input.intake === true && input.intake_mode === 'new'
+        && !['run_id', 'expected_revision_id', 'planning', 'ur_action', 'prd_action', 'sd_action', 'tp_action'].some(key => Object.hasOwn(input, key))
+        && !input.continue_delivery) {
+        const help = unboundCreationHelp(input);
+        const correction = help && ` Next read-only schema call (no Run creation): ${JSON.stringify(help)}`;
+        if (correction && messages.join(' ').length + correction.length <= 768) return messages.join(' ') + correction;
+      }
+    }
+    if (name === 'agdf_dispatch' && ['ur_action', 'prd_action', 'sd_action', 'tp_action'].some(k => input[k] !== undefined))
+      messages.push('Source revision actions use skill_id gate-check, intake:true, intake_mode:resume and expected_revision_id (never revision). An already bound incomplete-draft authoring continuation needs no additional author dispatch/intake: use its supplied writer forms.');
+    for (const key of name === 'agdf_dispatch' ? ['skill_id'] : ['command', 'operation_id', 'target_id', 'primary_target', 'target_source'])
+      if (!Object.hasOwn(input, key)) messages.push(`Supply ${key}.`);
+    const kind = input.command?.kind, descriptor = RUN_COMMAND_DESCRIPTORS[kind];
+    if (descriptor?.group === name) {
+      if (kind === 'run.create') messages.push('run.create accepts only command.payload.title, with the supplied original operation UUID and target. Omit run_id and expected_revision_id; do not add source, language or other payload fields. Use the returned canonical Run/revision after creation.');
+      if (['material.stage', 'planned_material.stage'].includes(kind) && input.command.payload?.action === 'put') {
+        const limit = RUN_COMMAND_DESCRIPTORS['material.stage'].payload_schema.oneOf[0].properties.files.items.properties.content.maxLength;
+        const oversized = Array.isArray(input.command.payload.files) && input.command.payload.files.find(file => typeof file?.content === 'string' && Buffer.byteLength(file.content, 'utf8') > limit);
+        if (oversized) messages.push(`put file is ${Buffer.byteLength(oversized.content, 'utf8')} UTF-8 bytes; maximum ${limit}. Preserve the entire text and use multipart begin/append/seal; measure bytes before submitting. No transfer was dispatched by this validation failure.`);
+      }
+      if (!['project.initialize', 'run.create', ...PLANNING_COMMAND_KINDS, ...TARGET_SCOPED_COMMAND_KINDS].includes(kind))
+        for (const key of ['run_id', 'expected_revision_id']) if (!Object.hasOwn(input, key)) messages.push(`Supply ${key} for ${kind}.`);
+      if (PLANNING_COMMAND_KINDS.includes(kind) && !input.planning) messages.push(`Supply planning for ${kind}; no Run/revision.`);
+      messages.push(`Read agdf_inspect operation-contract module ${name}/${kind} for this payload. Preserve the original operation UUID and requested revision.`);
+    }
+  } else return '';
+  if (Object.hasOwn(input, 'run_id') && (typeof input.run_id !== 'string' || !RUN_ID_PATTERN.test(input.run_id)))
+    messages.push('run_id must match ^[a-z0-9][a-z0-9._-]{0,127}$. Select the canonical Run ID from the request or confirmed inventory; do not guess another Run.');
+  if (Object.hasOwn(input, 'primary_target') !== Object.hasOwn(input, 'target_source'))
+    messages.push('Supply primary_target and target_source together from the confirmed task target; working_directory alone is not target authority.');
+  return messages.join(' ').slice(0, 768);
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/mcp-input-resolution.js

@@ -0,0 +1,98 @@
+import { isAbsolute, relative } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { resolveTaskTarget } from './task-target-resolution.js';
+import { COOPERATIVE_ASSURANCE, resolveControlCommandTarget } from './control-state/approval-command-contract.js';
+import { schemaDiagnostics, RUN_COMMAND_VERSION } from './control-state/run-command-schema.js';
+import { resolveConfiguration } from './resources/configuration.js';
+import { createInputResolution, restoreResolvedInput, validInputResolution } from './control-state/input-resolution.js';
+import { canonicalizeLanguageTag } from './interaction-presentation.js';
+import { validExecutionFacts } from './mcp-tool-errors.js';
+
+function reject(code, field) {
+  return Object.assign(Error(code), { code, facts: { code, dispatch: 'not_dispatched', ...(field ? { field } : {}) } });
+}
+// Called only by the serving adapter. Context and original-operation observations
+// are injected privately; neither can be supplied in public tool arguments.
+export function resolveMcpInput(definition, original, { defaults, executionContext, runtimeRoots = [], lookupOriginal = () => null } = {}) {
+  const diagnostics = schemaDiagnostics(original, definition.inputSchema);
+  if (diagnostics.length) {
+    const code = definition.name === 'agdf_inspect' ? 'inspect_input_invalid' : definition.name === 'agdf_dispatch' ? 'dispatch_input_invalid' : 'command_schema_invalid';
+    const field = diagnostics[0].path.match(/^\$\.([a-z_]+)$/u)?.[1];
+    throw reject(code, field && validExecutionFacts({ code, dispatch: 'not_dispatched', field }) ? field : undefined);
+  }
+  let effective = structuredClone(original);
+  if (effective.working_directory === undefined) {
+    if (executionContext?.source !== 'task_execution' || typeof executionContext.invocation_id !== 'string' || !executionContext.invocation_id
+      || !isAbsolute(executionContext.working_directory ?? '')) throw reject('working_directory_required', 'working_directory');
+    let directory;
+    try {
+      directory = realpathSync(executionContext.working_directory);
+      if (!statSync(directory).isDirectory() || runtimeRoots.some(root => {
+        const path = relative(realpathSync(root), directory); return path === '' || !path.startsWith('..') && !isAbsolute(path);
+      })) throw Error();
+    } catch { throw reject('working_directory_required', 'working_directory'); }
+    effective.working_directory = directory;
+  }
+  if (!isAbsolute(effective.working_directory)) throw reject('working_directory_required', 'working_directory');
+  let root = null;
+  if (effective.target_source !== undefined || effective.primary_target !== undefined) {
+    const target = resolveTaskTarget({ workingDirectory: effective.working_directory, targetSource: effective.target_source, primaryTarget: effective.primary_target });
+    if (target.resolution_state !== 'resolved') {
+      if (effective.command) throw reject('target_unresolved');
+      // Read/dispatch retain the Core's existing unresolved-target result plane.
+      // An unconfirmed target cannot supply project settings.
+    } else root = target.governance_target;
+    if (effective.command && effective.target_id !== undefined && resolveControlCommandTarget(root).target_id !== effective.target_id) throw reject('target_binding_mismatch');
+  }
+  let readLocator;
+  if (root && effective.operation === 'operation-status') {
+    const id = effective.module?.split('/').at(-1);
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(id ?? '')) readLocator = {
+      ...effective, operation_id: id, target_id: resolveControlCommandTarget(root).target_id,
+      command: { kind: ['project.initialize', 'planned_ur.create', 'planned_ur.replace', 'run.create_from_planned'].includes(effective.module?.split('/')[0])
+        ? effective.module.split('/')[0] : effective.run_id ? 'status.inspect' : 'run.create' },
+    };
+  } else if (root && ['presentation-document', 'presentation-preview'].includes(effective.operation)) readLocator = {
+    ...effective, operation_id: effective.presentation_id, command: { kind: 'presentation.prepare' },
+  };
+  const previous = root && (effective.operation_id || readLocator) ? lookupOriginal(root, readLocator ?? effective) : null;
+  if (readLocator && previous?.resolution) {
+    const c = previous.resolution.configuration;
+    if (c.root !== root) throw reject('target_binding_mismatch');
+    effective.presentation_language ??= previous.resolution.fields.presentation_language ?? c.values.chat_language;
+    const configuration = original.presentation_language === undefined ? c : { ...c,
+      values: { ...c.values, chat_language: canonicalizeLanguageTag(original.presentation_language) }, sources: { ...c.sources, chat_language: { kind: 'explicit' } } };
+    return { arguments: effective, resolution: createInputResolution(original, effective, configuration), original: true };
+  }
+  if (readLocator && previous?.known) throw reject('original_operation_unconfirmed');
+  if (!readLocator && previous?.resolution) {
+    if (['operation.recover', 'source_revision.recover'].includes(effective.command?.kind)) {
+      const c = previous.resolution;
+      for (const key of ['presentation_language', 'working_directory', 'schema_version', 'assurance']) effective[key] ??= c.fields[key];
+      effective.presentation_language ??= c.configuration.values.chat_language;
+      effective.schema_version ??= RUN_COMMAND_VERSION;
+      effective.assurance ??= COOPERATIVE_ASSURANCE.lane;
+      const resolution = createInputResolution(original, effective, c.configuration);
+      if (!validInputResolution(resolution)) throw reject('command_schema_invalid');
+      return { arguments: effective, resolution, original: true };
+    }
+    try { effective = restoreResolvedInput(original, previous.resolution); }
+    catch { throw reject('operation_payload_conflict'); }
+    return { arguments: effective, resolution: previous.resolution, original: true };
+  }
+  if (!readLocator && previous?.known) throw reject('original_operation_unconfirmed');
+  const explicit = { ...(original.presentation_language === undefined ? {} : { chat_language: original.presentation_language }),
+    ...(original.command?.kind === 'presentation.deliver' && original.command.payload.route !== undefined ? { presentation_route: original.command.payload.route } : {}),
+    ...(original.operation === 'gate-check' && original.variant !== undefined ? { gate_check_variant: original.variant } : {}) };
+  const configuration = resolveConfiguration(root, defaults, explicit);
+  effective.presentation_language ??= configuration.values.chat_language;
+  if (effective.command) {
+    effective.schema_version ??= RUN_COMMAND_VERSION;
+    effective.assurance ??= COOPERATIVE_ASSURANCE.lane;
+    if (effective.command.kind === 'presentation.deliver') effective.command.payload.route ??= configuration.values.presentation_route;
+  }
+  if (effective.operation === 'gate-check' && configuration.values.gate_check_variant !== null) effective.variant ??= configuration.values.gate_check_variant;
+  const resolution = createInputResolution(original, effective, configuration);
+  if (!validInputResolution(resolution)) throw reject('command_schema_invalid');
+  return { arguments: effective, resolution, original: false };
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/mcp-input-schema.js

@@ -0,0 +1,15 @@
+// The public projection expands only eligible omissions. Complete Core contracts
+// still validate the adapter-produced envelope, including every explicit value.
+export function projectMcpInputSchema(complete) {
+  const schema = structuredClone(complete);
+  if (Array.isArray(schema.required)) schema.required = schema.required.filter(key => !['presentation_language', 'working_directory', 'schema_version', 'assurance'].includes(key));
+  function visit(value) {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) { value.forEach(visit); return; }
+    if (value.properties?.route?.enum?.slice().sort().join(',') === 'automatic,fallback,markdown' && Array.isArray(value.required))
+      value.required = value.required.filter(key => key !== 'route');
+    Object.values(value).forEach(visit);
+  }
+  visit(schema);
+  return schema;
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/mcp-resource-contract.js

@@ -1,4 +1,4 @@
 // Pure resource identities shared by serving and build owners. Importing an
 // address must never load a control-state reader, writer or generated catalog.
-export const COCKPIT_UI_URI = 'ui://agdf/cockpit/v1.html';
+export const COCKPIT_UI_URI = 'ui://agdf/cockpit/v2.html';
 export const DECISION_UI_URI = 'ui://agdf/decision/v1.html';

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/mcp-tool-errors.js

@@ -4,24 +4,28 @@ export const TOOL_ERROR_CONTRACT = 'agdf-tool-result/1';
 export const TOOL_RESULT_META = 'agdf/tool-result';
 const fields = ['schema_version', 'failed', 'code', 'category', 'effect_state', 'action', 'message', 'authorizes'];
 const actions = {
-  correct_input: ['input', ['invalid_input', 'dispatch_input_invalid', 'inspect_input_invalid', 'command_schema_invalid', 'decision_schema_invalid', 'operation_source_invalid']],
-  confirm_target: ['binding', ['target_unresolved', 'target_binding_mismatch', 'no_reliable_target', 'explicit_target_required', 'target_invalid']],
-  refresh_binding: ['binding', ['stale_revision', 'revision_mismatch', 'operation_binding_stale_or_invalid', 'artifact_revision_stale', 'decision_binding_changed', 'decision_binding_invalid', 'presentation_state_changed', 'presentation_version_decided', 'presentation_not_found', 'presentation_missing', 'operation_source_changed', 'session_expired', 'source_changed', 'snapshot_stale', 'run_missing', 'invalid_run', 'document_missing', 'read_unavailable', 'recovery_binding_invalid', 'run_path_invalid']],
+  correct_input: ['input', ['AGDF_PLANNED_METADATA_INVALID', 'planning_identity_mismatch', 'configuration_invalid', 'working_directory_required', 'invalid_input', 'dispatch_input_invalid', 'inspect_input_invalid', 'command_schema_invalid', 'decision_schema_invalid', 'operation_source_invalid', 'material_binding_invalid', 'material_binding_mismatch', 'material_part_invalid', 'material_part_conflict', 'material_part_offset_invalid', 'material_incomplete', 'authoring_binding_stale_or_invalid', 'authoring_cursor_stale_or_invalid']],
+  confirm_target: ['binding', ['control_layout_unsupported', 'run_version_unsupported', 'target_unresolved', 'target_binding_mismatch', 'no_reliable_target', 'explicit_target_required', 'target_invalid']],
+  refresh_binding: ['binding', ['stale_revision', 'material_transfer_expired', 'planning_source_stale', 'planned_entry_missing', 'planned_document_missing', 'revision_mismatch', 'operation_binding_stale_or_invalid', 'artifact_revision_stale', 'decision_binding_changed', 'decision_binding_invalid', 'presentation_state_changed', 'presentation_version_decided', 'presentation_not_found', 'presentation_missing', 'operation_source_changed', 'session_expired', 'prepared_call_unknown', 'source_changed', 'snapshot_stale', 'run_missing', 'invalid_run', 'document_missing', 'recovery_binding_invalid', 'run_path_invalid', 'confirmed_git_project_required', 'AGDF_CANONICAL_SCAFFOLD_REQUIRED', 'AGDF_CANONICAL_INIT_CONFLICT', 'AGDF_CANONICAL_INIT_PARTIAL_UNOWNED', 'AGDF_CANONICAL_INIT_ORIGINAL_OPERATION_REQUIRED', 'AGDF_CANONICAL_INIT_PLAN_DRIFT', 'AGDF_CANONICAL_INIT_TARGET_DRIFT']],
   obtain_authority: ['permission', ['resource_denied', 'host_ui_unsupported', 'app_only_mediation_not_qualified', 'approval_required', 'confirmation_required', 'command_group_disabled', 'permission_denied', 'closeout_not_ready']],
   inspect_operation: ['uncertain', ['effect_unknown', 'recovery_required', 'original_operation_unconfirmed', 'operation_payload_conflict', 'another_pending_operation', 'decision_pending', 'decision_result_unknown', 'dispatch_timeout', 'dispatch_worker_termination_unconfirmed', 'generation_connection_lost', 'generation_response_unknown', 'generation_result_limit', 'command_result_budget_exceeded']],
-  retry_after_prerequisite: ['runtime', ['dispatch_busy', 'busy', 'dispatch_cancelled', 'cancelled', 'resource_limit', 'timeout', 'dispatch_output_too_large', 'inspect_output_too_large', 'lifecycle_ineligible', 'generation_unavailable', 'generation_capacity_protected', 'generation_input_limit', 'connection_closed', 'connection_control_unavailable', 'generation_route_capacity', 'generation_replacement_busy', 'connection_control_capacity']],
+  retry_after_prerequisite: ['runtime', ['dispatch_busy', 'busy', 'dispatch_cancelled', 'cancelled', 'resource_limit', 'timeout', 'dispatch_output_too_large', 'inspect_output_too_large', 'lifecycle_ineligible', 'generation_unavailable', 'generation_capacity_protected', 'generation_input_limit', 'connection_closed', 'connection_control_unavailable', 'generation_route_capacity', 'generation_replacement_busy', 'connection_control_capacity', 'prepared_call_store_unavailable', 'read_unavailable', 'read_failed', 'diagnostic_cursor_invalid', 'material_resource_limit', 'material_state_unavailable', 'delivery_state_unavailable', 'delivery_already_selected', 'decision_display_unconfirmed']],
   repair_runtime: ['runtime', ['runtime_version_mismatch', 'runtime_provenance_invalid']],
   stop: ['unknown', ['dispatch_worker_failed', 'generation_runtime_failed', 'tool_result_invalid', 'unclassified_tool_failure', 'generation_manifest_incompatible']],
 };
 const causes = new Map(Object.entries(actions).flatMap(([action, [category, codes]]) => codes.map(code => [code, { action, category }])));
-const commandNames = new Set(['agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout', 'agdf_decision_action']);
+// The command tools of the MCP tool-error contract; every other tool is a read. Companion events use the same list.
+export const COMMAND_TOOL_NAMES = Object.freeze(['agdf_project', 'agdf_run', 'agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout', 'agdf_decision_action']);
+const commandNames = new Set(COMMAND_TOOL_NAMES);
+export const isEphemeralControlCommand = (name, input = {}) => commandNames.has(name)
+  && ['presentation.deliver', 'material.stage', 'planned_material.stage'].includes(input.command?.kind);
 const commandOutcomes = new Set(['accepted', 'already_applied', 'rejected', 'recovery_required', 'effect_unknown']);
 const dispatchOutcomes = new Set(['invalid_input', 'target_unresolved', 'control_result', 'skill_continuation', 'intake_continuation', 'evaluator_error']);
 const inspectOutcomes = new Set(['invalid_input', 'target_unresolved', 'inspect_result', 'evaluator_error']);
-const exactReads = new Set(['presentation-document', 'presentation-preview', 'operation-contract', 'runtime-generations']);
-const reportReads = new Set(['doctor', 'gate-check', 'delivery-map', 'artifact-readiness', 'operation-status', 'native-qualification', 'contract']);
+const exactReads = new Set(['presentation-document', 'presentation-preview', 'operation-contract', 'runtime-generations', 'authoring-inputs', 'project-state', 'planned-entry']);
+const reportReads = new Set(['doctor', 'gate-check', 'delivery-map', 'artifact-readiness', 'operation-status', 'native-qualification', 'contract', 'inventory', 'planned-inventory']);
 const readStates = new Set(['available', 'empty', 'partial', 'invalid', 'missing', 'unsupported', 'blocked', 'stale', 'error']);
-const safeFields = new Set(['arguments', 'working_directory', 'primary_target', 'target_source', 'presentation_language', 'skill_id', 'run_id', 'expected_revision_id', 'operation_id', 'command', 'module', 'gate', 'cursor', 'operation', 'all_active', 'variant']);
+const safeFields = new Set(['arguments', 'working_directory', 'primary_target', 'target_source', 'target_id', 'presentation_language', 'skill_id', 'run_id', 'expected_revision_id', 'operation_id', 'command', 'module', 'gate', 'cursor', 'operation', 'all_active', 'variant', 'planning']);
 const plain = value => !!value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
 const invalid = () => { throw Object.assign(new Error('tool_result_invalid'), { code: 'tool_result_invalid', facts: { code: 'tool_result_invalid', dispatch: 'unknown' } }); };
 const textBytes = value => new TextEncoder().encode(JSON.stringify(value)).length;
@@ -44,11 +48,17 @@ export function executionFacts(error, { phase = 'execute' } = {}) {
 }
 
 export function validateToolDomain(name, result) {
-  if (!plain(result) || result.schema_version !== '1' || result._meta !== undefined && !plain(result._meta)) invalid();
+  // Only the paired Cockpit reading envelope moves to v2. Bootstrap, decision
+  // sessions and every control tool retain their existing v1 domain contract.
+  const cockpitEnvelope = ['agdf_cockpit', 'agdf_cockpit_read'].includes(name) && plain(result)
+    && Object.hasOwn(result, 'snapshot_id') && Object.hasOwn(result, 'target');
+  if (!plain(result) || result.schema_version !== (cockpitEnvelope ? '2' : '1')
+    || result._meta !== undefined && !plain(result._meta)) invalid();
   if (name === 'agdf_dispatch' || name === 'agdf_inspect') {
     const outcomes = name === 'agdf_dispatch' ? dispatchOutcomes : inspectOutcomes;
     if (result.contract_version !== 1 || !plain(result.runtime) || !plain(result.timing)
-      || !['wrapper_ms', 'input_ms', 'target_ms', 'control_ms', 'render_ms', 'total_ms'].every(key => Number.isFinite(result.timing[key]) && result.timing[key] >= 0)) invalid();
+      || !['wrapper_ms', 'input_ms', 'target_ms', 'control_ms', 'render_ms', 'total_ms'].every(key => Number.isFinite(result.timing[key]) && result.timing[key] >= 0
+        || name === 'agdf_inspect' && result.timing.measurement_state === 'unavailable' && result.timing.unavailable_reason === 'operation_did_not_complete' && result.timing[key] === null)) invalid();
     if (!outcomes.has(result.outcome) || result.authorizes !== false || typeof result.terminal !== 'boolean'
       || !Array.isArray(result.diagnostics) || !result.diagnostics.every(plain)) invalid();
     if (name === 'agdf_dispatch' && ['skill', 'control', 'continuation'].some(key => result[key] !== null && !plain(result[key]))) invalid();
@@ -70,6 +80,9 @@ export function validateToolDomain(name, result) {
   } else if (commandNames.has(name)) {
     if (!commandOutcomes.has(result.outcome) || result.authorizes !== false) invalid();
     if (['accepted', 'already_applied'].includes(result.outcome) ? !(result.receipt === null || plain(result.receipt)) : typeof result.reason !== 'string' || !result.reason) invalid();
+  } else if (name === 'agdf_decision_view') {
+    if (!['accepted', 'rejected'].includes(result.outcome) || result.authorizes !== false
+      || result.outcome === 'rejected' && typeof result.reason !== 'string') invalid();
   } else if (name === 'agdf_cockpit' || name === 'agdf_cockpit_read') {
     if (name === 'agdf_cockpit' && result.state === undefined && result.outcome === undefined) {
       const view = result._meta?.agdf_cockpit;
@@ -87,7 +100,10 @@ export function validateToolDomain(name, result) {
         && typeof preview.resource_id === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(preview.resource_id)
         && typeof preview.content === 'string' && /^sha256:[0-9a-f]{64}$/u.test(preview.content_digest)
         && typeof preview.version === 'string' && preview.version.length > 0;
-      if (result.authorizes !== false || !closed && !rendered
+      const display = plain(result.data) && ['preview', 'ui_primary'].includes(result.data.delivery_state)
+        && ['confirmed', 'unconfirmed'].includes(result.data.display) && /^sha256:[a-f0-9]{64}$/.test(result.data.document_digest)
+        && Array.isArray(result.data.enabled_actions) && result.data.enabled_actions.every(a => a === 'approve');
+      if (result.authorizes !== false || !closed && !rendered && !display
         || Object.keys(result).some(key => !['schema_version', 'state', 'data', 'authorizes', '_meta'].includes(key))) invalid();
     } else if (result.outcome === 'rejected') { if (result.authorizes !== false || typeof result.reason !== 'string') invalid(); }
     else if (!readStates.has(result.state) || !(result.code === null || typeof result.code === 'string')
@@ -102,7 +118,7 @@ function isFailure(name, input, result) {
   if (name === 'agdf_inspect') {
     if (result.outcome !== 'inspect_result') return true;
     if (exactReads.has(input.operation)) return result.report.available !== true;
-    if (reportReads.has(input.operation)) return input.operation === 'native-qualification' && result.report.available === false;
+    if (reportReads.has(input.operation)) return result.report.available === false;
     invalid();
   }
   if (commandNames.has(name)) return !['accepted', 'already_applied'].includes(result.outcome);
@@ -119,15 +135,17 @@ export function describeToolResult(name, input, result, pack, facts) {
   const descriptor = { schema_version: '1', failed, code: null, category: null, effect_state: null, action: null, message: null, authorizes: false };
   if (!failed) return descriptor;
   const candidate = result.reason ?? result.code ?? result.diagnostics?.[0]?.code ?? result.report?.reason ?? result.target?.reason_code ?? result.outcome;
-  const code = causes.has(candidate) ? candidate : result.outcome === 'target_unresolved' ? 'target_unresolved'
+  let code = causes.has(candidate) ? candidate : result.outcome === 'target_unresolved' ? 'target_unresolved'
     : result.outcome === 'invalid_input' ? 'invalid_input' : result.report?.available === false ? 'read_unavailable' : 'unclassified_tool_failure';
-  const uncertain = ['effect_unknown', 'recovery_required'].includes(result.outcome);
+  const canonicalWrite = commandNames.has(name) && !isEphemeralControlCommand(name, input);
+  const uncertain = canonicalWrite && ['effect_unknown', 'recovery_required'].includes(result.outcome);
+  if (['agdf_inspect', 'agdf_cockpit_read', 'agdf_decision_view'].includes(name) && causes.get(code).action === 'inspect_operation') code = 'read_unavailable';
   let { action, category } = causes.get(code);
   if (uncertain) { action = 'inspect_operation'; category = 'uncertain'; }
   const effect = validExecutionFacts(facts) ? facts.dispatch : result.dispatch === 'not_dispatched' ? 'not_dispatched'
     : commandNames.has(name) ? (uncertain ? 'unknown' : 'owner_reported') : 'owner_reported';
   // A cancelled/disconnected write cannot be offered a blind retry.
-  if (commandNames.has(name) && effect === 'unknown') { action = 'inspect_operation'; category = 'uncertain'; }
+  if (canonicalWrite && effect === 'unknown') { action = 'inspect_operation'; category = 'uncertain'; }
   const copy = pack?.mcpErrors;
   if (!copy?.actions?.[action] || !copy?.effects?.[effect]) invalid();
   const field = safeFields.has(facts?.field) ? facts.field : safeFields.has(result.diagnostics?.[0]?.field) ? result.diagnostics[0].field : null;

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/owned-file-lock.js

@@ -0,0 +1,266 @@
+import { randomUUID } from "node:crypto";
+import { channel } from "node:diagnostics_channel";
+import { closeSync, fchmodSync, fstatSync, fsyncSync, existsSync, lstatSync, linkSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { renameSyncWithRetry } from "./fs-swap.js";
+
+// Shared durable file primitives. Run semantics remain in control-state/run-state-writer.js.
+export function fsyncDirectory(path) {
+  if (process.platform === "win32") return;
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function atomicWrite(path, content, { checkpoint = () => {}, temporaryPath } = {}) {
+  let previousMode;
+  if (existsSync(path)) {
+    const destination = lstatSync(path);
+    if (destination.isSymbolicLink() || !destination.isFile()) {
+      throw new Error("AGDF_RUN_PATH_INVALID");
+    }
+    previousMode = destination.mode & 0o777;
+  }
+
+  const parent = lstatSync(dirname(path));
+  if (parent.isSymbolicLink() || !parent.isDirectory()) {
+    throw new Error("AGDF_RUN_PATH_INVALID");
+  }
+
+  const temp = temporaryPath ?? `${path}.tmp-${process.pid}-${randomUUID()}`;
+  if (typeof temp !== 'string' || temp === path || dirname(temp) !== dirname(path)) throw new Error('AGDF_RUN_PATH_INVALID');
+  let descriptor;
+
+  try {
+    descriptor = openSync(temp, "wx", 0o600);
+    checkpoint("temp_opened");
+    writeFileSync(descriptor, content, "utf8");
+    checkpoint("temp_written");
+    if (previousMode !== undefined && process.platform !== "win32") fchmodSync(descriptor, previousMode);
+    fsyncSync(descriptor);
+    checkpoint("after_file_sync");
+    closeSync(descriptor);
+    descriptor = undefined;
+
+    // Windows scanners briefly lock fresh files; the same bounded retry as the marketplace swap.
+    checkpoint("before_rename");
+    renameSyncWithRetry(temp, path);
+    checkpoint("after_rename");
+    fsyncDirectory(dirname(path));
+    checkpoint("after_directory_sync");
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor);
+    try {
+      unlinkSync(temp);
+    } catch (cleanupError) {
+      if (cleanupError.code !== "ENOENT") throw cleanupError;
+    }
+    throw error;
+  }
+}
+
+function lockError(path) {
+  const error = new Error("AGDF_RUN_WRITE_LOCKED");
+  error.lock_path = path;
+  // A simultaneous reclaim inspection can hold the short guard while the real
+  // publication owner is live. Classify only a stable, regular, bounded owner
+  // record; this does not reclaim, remove or authorize a wait for an unknown lock.
+  try {
+    const before = lstatSync(path);
+    if (before.isFile() && !before.isSymbolicLink() && before.size <= 4096) {
+      const bytes = readFileSync(path, 'utf8'), owner = JSON.parse(bytes), after = lstatSync(path);
+      if (before.dev === after.dev && before.ino === after.ino && !after.isSymbolicLink()
+        && readFileSync(path, 'utf8') === bytes && ownerState(owner) === 'live') error.lock_owner_status = 'live';
+    }
+  } catch {}
+  return error;
+}
+
+const LOCK_TOKEN = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu;
+
+function validOwnerRecord(owner) {
+  return Boolean(owner) && Object.keys(owner).sort().join(',') === 'pid,schema_version,started_at,token'
+    && owner.schema_version === 1 && typeof owner.started_at === 'string'
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(owner.started_at)
+    && Number.isFinite(Date.parse(owner.started_at)) && new Date(owner.started_at).toISOString() === owner.started_at
+    && Number.isSafeInteger(owner.pid) && owner.pid > 0
+    && typeof owner.token === "string" && LOCK_TOKEN.test(owner.token);
+}
+
+function ownerState(owner) {
+  if (!validOwnerRecord(owner)) return "unknown";
+  try {
+    process.kill(owner.pid, 0);
+    return "live";
+  } catch (error) {
+    return error?.code === "ESRCH" ? "gone" : "unknown";
+  }
+}
+
+function reclaimAbandonedLock(path) {
+  const guard = `${path}.reclaim`;
+  let descriptor;
+  try {
+    descriptor = openSync(guard, "wx");
+  } catch {
+    throw lockError(path);
+  }
+  try {
+    let original;
+    try {
+      const file = lstatSync(path);
+      if (!file.isFile() || file.size > 4096) throw lockError(path);
+      original = readFileSync(path, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+    let owner;
+    try { owner = JSON.parse(original); } catch { owner = null; }
+    const status = ownerState(owner);
+    if (status !== "gone") {
+      const error = lockError(path);
+      error.lock_owner_status = status;
+      throw error;
+    }
+    if (!lstatSync(path).isFile() || readFileSync(path, "utf8") !== original) throw lockError(path);
+    unlinkSync(path);
+    fsyncDirectory(dirname(path));
+  } finally {
+    closeSync(descriptor);
+    unlinkSync(guard);
+  }
+}
+
+function publishOwnedLock(lockPath, owner, checkpoint) {
+  const stagedPath = `${lockPath}.${owner.token}.pending`;
+  const descriptor = openSync(stagedPath, 'wx', 0o600);
+  const created = fstatSync(descriptor);
+  let published = false;
+  try {
+    writeFileSync(descriptor, `${JSON.stringify(owner)}\n`, 'utf8'); fsyncSync(descriptor);
+    checkpoint('owner_staged');
+    // Exclusive hard-link publication exposes one complete record or EEXIST,
+    // never the previous visible-but-empty owner window. Both names are local
+    // to this directory and inode; a changed staging path cannot be adopted.
+    const staged = lstatSync(stagedPath);
+    if (staged.isSymbolicLink() || staged.dev !== created.dev || staged.ino !== created.ino) throw lockError(lockPath);
+    linkSync(stagedPath, lockPath);
+    published = true;
+    checkpoint('owner_published');
+    unlinkSync(stagedPath);
+    return descriptor;
+  } catch (error) {
+    // Failure before handing off the descriptor must not strand our live lock.
+    // Never unlink a replaced or modified owner record.
+    try {
+      if (published) {
+        const current = lstatSync(lockPath);
+        if (!current.isSymbolicLink() && current.dev === created.dev && current.ino === created.ino
+          && readFileSync(lockPath, 'utf8') === `${JSON.stringify(owner)}\n`) unlinkSync(lockPath);
+      }
+    } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') throw cleanupError; }
+    finally { closeSync(descriptor); }
+    try {
+      const staged = lstatSync(stagedPath);
+      if (!staged.isSymbolicLink() && staged.dev === created.dev && staged.ino === created.ino) unlinkSync(stagedPath);
+    } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') throw cleanupError; }
+    throw error;
+  }
+}
+
+// Ownership announcements let a host that runs writers on threads (the MCP worker
+// executor) release a lock whose owning thread was terminated before its finally
+// block ran. Owner records keep their format; without subscribers nothing happens.
+export const OWNED_LOCK_CHANNEL = "agdf:owned-file-lock";
+const ownedLockChannel = channel(OWNED_LOCK_CHANNEL);
+function announceOwnedLock(phase, lockPath, token) {
+  if (ownedLockChannel.hasSubscribers) ownedLockChannel.publish({ phase, lock_path: lockPath, token });
+}
+
+// Releases a lock whose owning thread has actually exited; the caller proves the exit.
+// This function proves the record is that thread's own (exact token, this process,
+// unchanged bytes) under the same guard as reclaimAbandonedLock. It never throws for
+// a foreign, guarded or unknown lock: it reports the outcome and leaves it in place.
+export function releaseAbandonedOwnedLock(lockPath, token) {
+  if (typeof lockPath !== "string" || !lockPath.endsWith(".lock") || typeof token !== "string" || !LOCK_TOKEN.test(token)) return "unknown";
+  try {
+    const staged = `${lockPath}.${token}.pending`, file = lstatSync(staged);
+    if (file.isFile() && !file.isSymbolicLink()) unlinkSync(staged);
+  } catch (error) { if (error?.code !== "ENOENT") return "unknown"; }
+  const guard = `${lockPath}.reclaim`;
+  let descriptor;
+  try { descriptor = openSync(guard, "wx"); } catch (error) { return error?.code === "EEXIST" ? "guarded" : "unknown"; }
+  try {
+    let original;
+    try {
+      const file = lstatSync(lockPath);
+      if (!file.isFile() || file.size > 4096) return "unknown";
+      original = readFileSync(lockPath, "utf8");
+    } catch (error) { return error?.code === "ENOENT" ? "absent" : "unknown"; }
+    let owner;
+    try { owner = JSON.parse(original); } catch { return "unknown"; }
+    if (!validOwnerRecord(owner)) return "unknown";
+    if (owner.token !== token || owner.pid !== process.pid) return "foreign";
+    if (!lstatSync(lockPath).isFile() || readFileSync(lockPath, "utf8") !== original) return "foreign";
+    unlinkSync(lockPath);
+    fsyncDirectory(dirname(lockPath));
+    return "released";
+  } catch { return "unknown"; }
+  finally {
+    closeSync(descriptor);
+    try { unlinkSync(guard); } catch {}
+  }
+}
+
+export function withOwnedFileLock(path, work, { checkpoint = () => {} } = {}) {
+  const lockPath = `${path}.lock`;
+  const owner = { schema_version: 1, pid: process.pid, token: randomUUID(), started_at: new Date().toISOString() };
+  let lockDescriptor;
+  // Announce before staging: a thread stopped right after publication is still known.
+  announceOwnedLock("intent", lockPath, owner.token);
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        lockDescriptor = publishOwnedLock(lockPath, owner, checkpoint); break;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        try { reclaimAbandonedLock(lockPath); }
+        catch (locked) {
+          if (attempt < 2 && !existsSync(lockPath)) continue; // Fresh proven absence; no wait/reclaim of an unknown owner.
+          throw locked;
+        }
+        if (attempt === 2) throw lockError(lockPath);
+      }
+    }
+  } catch (error) {
+    // No "released" here: if publishOwnedLock's own cleanup failed, the record may still
+    // exist, and the host must keep the token to release it after the thread exits.
+    throw error;
+  }
+  const created = fstatSync(lockDescriptor);
+  try {
+    checkpoint("lock_acquired");
+    const result = work(owner);
+    checkpoint("before_lock_release");
+    return result;
+  } finally {
+    closeSync(lockDescriptor);
+    // A changed lock does not belong to this invocation and must never be removed by it.
+    try {
+      const currentFile = lstatSync(lockPath);
+      if (currentFile.dev === created.dev && currentFile.ino === created.ino) {
+        const current = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (current.token === owner.token) unlinkSync(lockPath);
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT" && error instanceof SyntaxError === false) throw error;
+    }
+    announceOwnedLock("released", lockPath, owner.token);
+    checkpoint("after_lock_release");
+  }
+}
+