create-agdf 0.20.1 → 0.30.0

package/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/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/runtime/core/lib/mcp-tool-errors.js

@@ -4,24 +4,26 @@ 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', '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', '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', 'read_unavailable', 'read_failed', 'diagnostic_cursor_invalid', 'material_transfer_expired', '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']);
+const commandNames = new Set(['agdf_project', 'agdf_run', 'agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout', 'agdf_decision_action']);
+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 +46,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 +78,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 +98,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 +116,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 +133,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/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");
+  }
+}
+

package/runtime/core/lib/owner-placement.js

@@ -0,0 +1,50 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+// Internal fixed owner roles. The owner binds bytes, intent and producer; this
+// helper binds existing objects across mount-session device-number changes.
+const anchors = Object.freeze({ 'canonical-control': '.agdf-canonical-init.json', 'marketplace-publication': '.agdf-owned.json' });
+const inode = value => typeof value === 'bigint' && value > 0n ? String(value) : (() => { throw Error('owner_placement_unsupported'); })();
+function directory(path) {
+  const resolved = resolve(path), real = realpathSync(path);
+  // Preserve the platform's fixed system aliases used by existing CLI/installer
+  // temp paths. A linked target entry or any additional linked ancestor rejects.
+  if (real !== resolved && !(process.platform === 'darwin'
+    && real === resolved.replace(/^\/(var|tmp|etc)(?=\/|$)/u, '/private/$1'))) throw Error('owner_placement_unsafe');
+  const stat = lstatSync(path, { bigint: true });
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error('owner_placement_unsafe');
+  inode(stat.ino); return stat;
+}
+const sameLive = (a, b) => a.dev === b.dev && a.ino === b.ino;
+export function directoryPlacement(path) {
+  const stat = directory(path);
+  return Object.freeze({ location: realpathSync(path), ino: inode(stat.ino) });
+}
+export function ownerPlacement(path, role, logicalPath = path) {
+  const name = anchors[role];
+  if (!name) throw Error('owner_placement_role_invalid');
+  const before = directory(path), anchorPath = join(path, name);
+  let fd;
+  try {
+    const entry = lstatSync(anchorPath, { bigint: true });
+    if (!entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1n) throw Error('owner_placement_unsafe');
+    fd = openSync(anchorPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(fd, { bigint: true });
+    const after = lstatSync(anchorPath, { bigint: true });
+    if (!opened.isFile() || opened.nlink !== 1n || !sameLive(entry, opened)
+      || !after.isFile() || after.isSymbolicLink() || after.nlink !== 1n
+      || !sameLive(opened, after) || !sameLive(before, directory(path))) throw Error('owner_placement_changed');
+    return Object.freeze({ schema_version: 1, role, location: join(realpathSync(dirname(logicalPath)), basename(logicalPath)), directory_ino: inode(before.ino),
+      anchor: Object.freeze({ name, ino: inode(opened.ino) }) });
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+export function assertOwnerPlacement(binding, path, role, logicalPath = path) {
+  const actual = ownerPlacement(path, role, logicalPath);
+  if (!binding || JSON.stringify(binding) !== JSON.stringify(actual)) throw Error('owner_placement_changed');
+  return actual;
+}
+export function assertDirectoryPlacement(binding, path) {
+  const actual = directoryPlacement(path);
+  if (!binding || JSON.stringify(binding) !== JSON.stringify(actual)) throw Error('owner_placement_changed');
+  return actual;
+}

package/runtime/core/lib/resources/canonical-init-plan.js

@@ -0,0 +1,34 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resources } from './context.js';
+import { resolveLanguagePreference, languageConfigContent } from './language-preference.js';
+import { resolveArtefactTemplatePath } from './artefact-templates.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { CURRENT_LAYOUT } from '../control-state/run-identity.js';
+
+// Fixed canonical seeds; callers supply only language.
+export function canonicalInitPlan(languagePreference, context = resources, { layout = CURRENT_LAYOUT } = {}) {
+  if (layout !== CURRENT_LAYOUT) throw Error('canonical_layout_unsupported');
+  const language = typeof languagePreference === 'object' && languagePreference !== null
+    ? languagePreference : resolveLanguagePreference(languagePreference, undefined, context);
+  const root = context.templatesRoot;
+  if (!root || lstatSync(root).isSymbolicLink()) throw Error('canonical_init_resources_unavailable');
+  const load = (base, relative) => {
+    if (hasSymlinkComponent(base, relative)) throw Error('canonical_init_resources_unsafe');
+    const file = containedRegularFile(base, relative);
+    if (file.status !== 'valid' || lstatSync(file.path).size > 131072) throw Error('canonical_init_resources_unavailable');
+    return readFileSync(file.path, 'utf8');
+  };
+  const files = [{ path: '.agdf/control/config.json', content: languageConfigContent(language, { control_layout: layout }) },
+    { path: '.agdf/control/README.md', content: load(dirname(root), 'README.md') }];
+  for (const store of ['runs', 'planned'])
+    files.push({ path: `.agdf/control/${store}/.gitkeep`, content: '' });
+  for (const name of ['SOT_REGISTRY.md', 'CONTEXT_GRAPH.md', 'AGENT_QUALITY_CONTRACTS.json'])
+    files.push({ path: `.agdf/control/${name}`, content: load(root, name) });
+  for (const id of ['UR', 'BROWNFIELD_REVIEW', 'VERIFIED_CHANGE', 'PRD', 'UX_INTENT_DEFINITION', 'SD', 'TP', 'QA_REPORT', 'OR']) {
+    resolveArtefactTemplatePath(id, context);
+    files.push({ path: `.agdf/control/templates/artefacts/${id}.md`, content: load(root, `artefacts/${id}.md`) });
+  }
+  if (files.reduce((n, f) => n + Buffer.byteLength(f.content), 0) > 524288) throw Error('canonical_init_plan_budget_exceeded');
+  return files;
+}

package/runtime/core/lib/resources/configuration.js

@@ -0,0 +1,92 @@
+import { CURRENT_LAYOUT } from '../control-state/run-identity.js';
+import { readFileSync, existsSync, statSync } from '../control-read/fs.js';
+import { join } from 'node:path';
+import { canonicalizeLanguageTag } from '../interaction-presentation.js';
+import { schemaDiagnostics, RUN_COMMAND_DESCRIPTORS } from '../control-state/run-command-schema.js';
+import { GATE_CHECK_VARIANTS } from '../control-inspect/selection.js';
+import { digest } from '../control-state/approval-command-contract.js';
+import { containedRegularFile, hasSymlinkComponent } from '../control-state/contained-file.js';
+import { currentInputResolution, isOriginalInputResolution } from '../control-state/input-resolution.js';
+
+export const PREFERENCE_KEYS = Object.freeze(['chat_language', 'artifact_language', 'presentation_route', 'gate_check_variant']);
+export const CONFIGURATION_PATH = '.agdf/control/config.json';
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+export function configurationError(source, field, action = 'Correct the named configuration field and retry the original operation safely.') {
+  const code = field === 'control_layout' ? 'control_layout_unsupported' : 'configuration_invalid';
+  return Object.assign(Error(code), { code, facts: { code, dispatch: 'not_dispatched' },
+    diagnostic: { code, source, field, action } });
+}
+export function readPluginDefaults(generatedURL) {
+  try {
+    const bytes = readFileSync(new URL('plugins/agdf/meta/agdf-defaults.json', generatedURL), 'utf8');
+    const schema = JSON.parse(readFileSync(new URL('plugins/agdf/meta/agdf-defaults.schema.json', generatedURL), 'utf8'));
+    const document = JSON.parse(bytes);
+    if (schemaDiagnostics(document, schema).length || !PREFERENCE_KEYS.every(key => Object.hasOwn(schema.properties.preferences.properties, key))) throw Error();
+    const fields = schema.properties.preferences.properties;
+    if (JSON.stringify(fields.presentation_route.enum.slice().sort()) !== JSON.stringify(RUN_COMMAND_DESCRIPTORS['presentation.deliver'].payload_schema.properties.route.enum.slice().sort())
+      || JSON.stringify(fields.gate_check_variant.enum) !== JSON.stringify([null, ...GATE_CHECK_VARIANTS])) throw Error();
+    for (const key of ['chat_language', 'artifact_language']) if (!canonicalizeLanguageTag(document.preferences[key])) throw Error();
+    return { document, schema, digest: digest(bytes) };
+  } catch { throw Error('runtime_resources_unavailable'); }
+}
+export function resolveConfiguration(root, defaults, explicit = {}) {
+  const bound = currentInputResolution()?.configuration;
+  if (bound && bound.root === (root ?? null) && Object.keys(explicit).length === 0) return bound;
+  const source = { kind: 'plugin', path: 'meta/agdf-defaults.json', digest: defaults.digest };
+  let project = {}, configDigest = null, control = 'inactive';
+  if (root && existsSync(join(root, CONFIGURATION_PATH))) {
+    const projectSource = { kind: 'project', path: CONFIGURATION_PATH };
+    if (hasSymlinkComponent(root, CONFIGURATION_PATH) || containedRegularFile(root, CONFIGURATION_PATH).status !== 'valid') throw configurationError(projectSource, 'config', 'Use a regular contained project configuration file.');
+    let bytes;
+    try {
+      if (statSync(join(root, CONFIGURATION_PATH)).size > 65536) throw Error();
+      bytes = readFileSync(join(root, CONFIGURATION_PATH));
+      if (bytes.length > 65536) throw Error();
+      project = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    } catch { throw configurationError(projectSource, 'config', 'Correct the project configuration JSON; no operation was dispatched.'); }
+    if (!plain(project))
+      throw configurationError(projectSource, 'config', 'Restore the existing required language fields; defaults do not initialize project control.');
+    if (project.control_layout !== CURRENT_LAYOUT)
+      throw configurationError(projectSource, 'control_layout', 'Use the current explicit run-folders-v1 layout; old control stores are unsupported.');
+    for (const key of ['chat_language', 'artifact_language', 'runtime_language'])
+      if (typeof project[key] !== 'string' || !project[key].trim()) throw configurationError(projectSource, key, 'Restore the named required language field; defaults do not initialize project control.');
+    configDigest = digest(bytes); control = 'active';
+    if (!canonicalizeLanguageTag(project.runtime_language)) throw configurationError({ ...projectSource, digest: configDigest }, 'runtime_language');
+    for (const key of PREFERENCE_KEYS) if (Object.hasOwn(project, key)) {
+      if (schemaDiagnostics(project[key], defaults.schema.properties.preferences.properties[key]).length
+        || key.endsWith('_language') && !canonicalizeLanguageTag(project[key])) throw configurationError({ ...projectSource, digest: configDigest }, key);
+    }
+  }
+  const values = {}, sources = {};
+  for (const key of PREFERENCE_KEYS) {
+    let value;
+    if (Object.hasOwn(explicit, key)) {
+      value = explicit[key]; sources[key] = { kind: 'explicit' };
+      if (schemaDiagnostics(value, defaults.schema.properties.preferences.properties[key]).length) throw configurationError(sources[key], key, 'Correct the explicit value; an invalid value is never defaulted.');
+    } else if (Object.hasOwn(project, key)) { value = project[key]; sources[key] = { kind: 'project', path: CONFIGURATION_PATH, digest: configDigest }; }
+    else { value = defaults.document.preferences[key]; sources[key] = source; }
+    values[key] = key.endsWith('_language') ? canonicalizeLanguageTag(value) : value;
+    if (key.endsWith('_language') && !values[key]) throw configurationError(sources[key], key);
+  }
+  return Object.freeze({ root: root ?? null, control, config_digest: configDigest, values: Object.freeze(values), sources: Object.freeze(sources),
+    control_layout: control === 'active' ? project.control_layout : null,
+    defaults_digest: defaults.digest });
+}
+export function assertConfigurationCurrent(snapshot) {
+  if (!snapshot?.root) return;
+  const path = join(snapshot.root, CONFIGURATION_PATH);
+  try {
+    if (existsSync(path) && statSync(path).size > 65536) throw Error();
+    const current = existsSync(path) ? digest(readFileSync(path)) : null;
+    if (current === snapshot.config_digest && (!existsSync(path) || !hasSymlinkComponent(snapshot.root, CONFIGURATION_PATH))) return;
+  } catch { /* Changed/unreadable configuration cannot select new values mid-effect. */ }
+  throw Object.assign(Error('snapshot_stale'), { facts: { code: 'snapshot_stale', dispatch: 'not_dispatched' } });
+}
+export function assertInputConfigurationCurrent(root) {
+  const snapshot = currentInputResolution()?.configuration;
+  if (snapshot?.root && snapshot.root !== root) throw Error('target_binding_mismatch');
+  if (snapshot && !isOriginalInputResolution()) assertConfigurationCurrent(snapshot);
+}
+export function effectiveConfiguration(snapshot, binding = 'current') {
+  return { binding, values: snapshot.values, sources: snapshot.sources, constants: 'contract_owned', authorizes: false };
+}

package/runtime/core/lib/resources/context.js

@@ -1,9 +1,9 @@
-import { existsSync, readFileSync } from "../control-read/fs.js";
-import { join } from "node:path";
+import { readFileSync } from "../control-read/fs.js";
 import { fileURLToPath } from "node:url";
 import { canonicalizeLanguageTag, resolvePresentationLocale } from "../interaction-presentation.js";
 import { validateInteractionCatalog } from "../interaction-catalog-validation.js";
 import { packageURL, generatedURL, contractsURL, templatesURL } from "./binding.js";
+import { readPluginDefaults, resolveConfiguration } from './configuration.js';
 
 function freeze(value) {
   if (value && typeof value === "object") { for (const entry of Object.values(value)) freeze(entry); Object.freeze(value); }
@@ -30,6 +30,7 @@ export function createResourceContext({ packageURL, generatedURL, contractsURL,
     templatesRoot: templatesURL instanceof URL ? fileURLToPath(templatesURL) : null,
     pluginDefinition,
     interactionLocales,
+    defaults: readPluginDefaults(generatedURL),
   });
 }
 export const resources = createResourceContext({ packageURL, generatedURL, contractsURL, templatesURL });
@@ -42,21 +43,16 @@ export function configuredLanguage(value, context = resources) {
   return normalized;
 }
 export function resolveConfiguredChatLanguage(targetDir, context = resources) {
-  const configPath = join(targetDir, ".agdf", "control", "config.json");
-  if (!existsSync(configPath)) return context.interactionLocales.fallbackLocale;
-  try { return resolvePresentationLocale(context.interactionLocales, JSON.parse(readFileSync(configPath, "utf8")).chat_language); }
-  catch { return context.interactionLocales.fallbackLocale; }
+  return resolvePresentationLocale(context.interactionLocales, resolveConfiguration(targetDir, context.defaults).values.chat_language);
 }
-// Missing or invalid config means English artefacts.
-export function resolveConfiguredArtifactLanguage(targetDir) {
-  try { return canonicalizeLanguageTag(JSON.parse(readFileSync(join(targetDir, ".agdf", "control", "config.json"), "utf8")).artifact_language).split("-")[0] || "en"; }
-  catch { return "en"; }
+export function resolveConfiguredArtifactLanguage(targetDir, context = resources) {
+  return resolveConfiguration(targetDir, context.defaults).values.artifact_language.split('-')[0];
 }
 
 // Shared by artefact authoring and approval rendering; the selected locale may override
 // the configured chat default, but never changes the persisted artefact language.
 export function resolveArtifactPresentationLanguages(targetDir, requestedLanguage, context = resources) {
-  const artifactLanguage = resolveConfiguredArtifactLanguage(targetDir);
+  const artifactLanguage = resolveConfiguredArtifactLanguage(targetDir, context);
   const presentationLanguage = requestedLanguage
     ? resolvePresentationLocale(context.interactionLocales, requestedLanguage)
     : resolveConfiguredChatLanguage(targetDir, context);