create-agdf 0.20.1 → 0.30.0

package/lib/mcp-lifecycle/adapters/opencode.js

@@ -1,4 +1,4 @@
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -6,7 +6,6 @@ import {
   atomicWrite,
   fileSnapshot,
   inheritedPermissionEffect,
-  readJsonObject,
   referenceIdentityForSurface,
   restoreSnapshot,
 } from "./file-utils.js";
@@ -15,8 +14,75 @@ const OWNER = "create-agdf:mcp-runtime";
 const CREATED_CONFIG = "AGDF_MCP_CREATED_CONFIG";
 const SCHEMA = "https://opencode.ai/config.json";
 
+// Preserve offsets: comments and trailing commas are syntax, never string data.
+function jsonc(content) {
+  const tokens = [], clean = content.split('');
+  for (const match of content.matchAll(/"(?:\\[\s\S]|[^"\\])*"|\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|[{}\[\]:,]|[^\s{}\[\]:,/"']+|[^\s]/gu)) {
+    const text = match[0], start = match.index, end = start + text.length;
+    if (text.startsWith('//') || text.startsWith('/*')) {
+      for (let i = start; i < end; ++i) if (!/[\r\n]/u.test(clean[i])) clean[i] = ' ';
+    } else tokens.push({ text, start, end });
+  }
+  for (let i = 0; i < tokens.length - 1; ++i) {
+    if (i > 0 && tokens[i].text === ',' && ['}', ']'].includes(tokens[i + 1].text)
+      && !['{', '[', ':', ','].includes(tokens[i - 1].text)) clean[tokens[i].start] = ' ';
+  }
+  const sanitized = clean.join(''), config = JSON.parse(sanitized);
+  let cursor = 0;
+  function node() {
+    const first = tokens[cursor++], properties = [];
+    if (!['{', '['].includes(first.text)) return { ...first };
+    const object = first.text === '{', close = object ? '}' : ']';
+    while (tokens[cursor].text !== close) {
+      const key = object ? tokens[cursor++] : null;
+      if (object) ++cursor; // colon; JSON.parse already validated the grammar
+      const value = node(), comma = tokens[cursor].text === ',' ? tokens[cursor++] : null;
+      if (object) {
+        const name = JSON.parse(key.text);
+        if (properties.some(row => row.name === name)) throw Error('duplicate_key');
+        properties.push({ name, start: key.start, value, comma });
+      }
+    }
+    return { start: first.start, end: tokens[cursor++].end, ...(object ? { properties } : {}) };
+  }
+  return { config, tree: node(), preserveSyntax: sanitized !== content };
+}
+
+function editJsonc(content, path, value) {
+  let { tree } = jsonc(content);
+  for (let i = 0; i < path.length; ++i) {
+    if (!tree.properties) throw Error('invalid_object');
+    const index = tree.properties.findIndex(row => row.name === path[i]), property = tree.properties[index];
+    if (property && i < path.length - 1) { tree = property.value; continue; }
+    const edits = [];
+    if (property) {
+      if (value !== undefined) edits.push([property.value.start, property.value.end, JSON.stringify(value, null, 2)]);
+      else {
+        edits.push([property.start, property.comma?.end ?? property.value.end, '']);
+        const previous = tree.properties[index - 1]?.comma;
+        if (!property.comma && previous) edits.push([previous.start, previous.end, '']);
+      }
+    } else {
+      if (value === undefined) return content;
+      for (const key of path.slice(i + 1).reverse()) value = { [key]: value };
+      const last = tree.properties.at(-1);
+      if (last && !last.comma) edits.push([last.value.end, last.value.end, ',']);
+      edits.push([tree.end - 1, tree.end - 1, `\n${'  '.repeat(i + 1)}${JSON.stringify(path[i])}: ${JSON.stringify(value, null, 2)}\n${'  '.repeat(i)}`]);
+    }
+    for (const [start, end, text] of edits.sort((a, b) => b[0] - a[0])) content = content.slice(0, start) + text + content.slice(end);
+    return content;
+  }
+  throw Error('invalid_path');
+}
+
 function readConfig(path) {
-  const value = readJsonObject(path, "AGDF_MCP_OPENCODE_CONFIG_INVALID");
+  let value;
+  try {
+    const content = existsSync(path) ? readFileSync(path, 'utf8') : '{}';
+    const parsed = jsonc(content);
+    value = { content, config: parsed.config, preserveSyntax: path.endsWith('.jsonc') || parsed.preserveSyntax };
+    if (!value.config || typeof value.config !== 'object' || Array.isArray(value.config)) throw Error('invalid');
+  } catch { throw Error('AGDF_MCP_OPENCODE_CONFIG_INVALID'); }
   if (value.config.mcp !== undefined && (!value.config.mcp || typeof value.config.mcp !== "object" || Array.isArray(value.config.mcp))) {
     throw new Error("AGDF_MCP_OPENCODE_CONFIG_INVALID");
   }
@@ -64,13 +130,26 @@ function inspectPath(path, expected) {
 }
 
 function sources({ scope, target, env }) {
+  const user = env.OPENCODE_CONFIG_DIR || join(homedir(), '.config', 'opencode');
+  const files = (id, directory, priority) => {
+    const paths = ['opencode.jsonc', 'opencode.json'].map(name => join(directory, name)).filter(existsSync);
+    if (!paths.length) paths.push(join(directory, 'opencode.json'));
+    // JSONC wins conflicting keys. Otherwise update the file owning the entry,
+    // rather than silently shadowing it by creating a second registration.
+    const selected = paths.find(path => {
+      const { config } = readConfig(path);
+      return config.mcp?.agdf !== undefined || config.mcp?.servers?.agdf !== undefined;
+    }) ?? paths[0];
+    return paths.map((path, index) => ({ id: path === selected ? id : `${id}_${path.endsWith('.jsonc') ? 'jsonc' : 'json'}`,
+      path, priority: priority + index, selected: scope === id && path === selected }));
+  };
   return [
     ...(typeof env.OPENCODE_CONFIG_CONTENT === "string" && env.OPENCODE_CONFIG_CONTENT.trim()
       ? [{ id: "inline", path: "env:OPENCODE_CONFIG_CONTENT", priority: 0, selected: false, inline: env.OPENCODE_CONFIG_CONTENT }] : []),
     ...(typeof env.OPENCODE_CONFIG === "string" && env.OPENCODE_CONFIG.trim()
       ? [{ id: "custom", path: env.OPENCODE_CONFIG, priority: 5, selected: false }] : []),
-    { id: "project", path: join(target, "opencode.json"), priority: 10, selected: scope === "project" },
-    { id: "user", path: join(env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode"), "opencode.json"), priority: 20, selected: scope === "user" },
+    ...files('project', target, 10),
+    ...files('user', user, 20),
   ];
 }
 
@@ -80,7 +159,7 @@ function inspect(input) {
   const states = new Map(list.map((source) => {
     if (!source.inline) return [source.id, inspectPath(source.path, input.spec)];
     try {
-      const config = JSON.parse(source.inline);
+      const config = jsonc(source.inline).config;
       if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error("invalid");
       return [source.id, inspectConfig(config, source.path, input.spec)];
     } catch { return [source.id, { status: "invalid", path: source.path, identity: null }]; }
@@ -96,7 +175,7 @@ function transaction({ action, scope, target, spec, previousSpec, env }) {
     return { status: "unchanged", path: current.path, apply() {}, rollback() {} };
   }
   const snapshot = fileSnapshot(current.path);
-  const { config } = readConfig(current.path);
+  const { config, content, preserveSyntax } = readConfig(current.path);
   const mcp = { ...(config.mcp ?? {}) };
   const nested = spec.host?.config_variant === "nested_v2";
   const createdConfig = !snapshot.existed || current.created_config === true;
@@ -117,7 +196,17 @@ function transaction({ action, scope, target, spec, previousSpec, env }) {
   const remaining = Object.keys(next);
   const removable = current.created_config === true
     && (remaining.length === 0 || (remaining.length === 1 && remaining[0] === "$schema" && next.$schema === SCHEMA));
-  const after = action === "disable" && removable ? null : `${JSON.stringify(next, null, 2)}\n`;
+  let after = `${JSON.stringify(next, null, 2)}\n`;
+  if (snapshot.existed && preserveSyntax) {
+    after = content;
+    for (const keys of [['mcp', 'agdf'], ['mcp', 'servers', 'agdf'], ['mcp', 'servers'], ['mcp']]) {
+      const beforeValue = keys.reduce((row, key) => row?.[key], config), nextValue = keys.reduce((row, key) => row?.[key], next);
+      if ((keys.length > 2 || keys.at(-1) === 'agdf' || nextValue === undefined) && JSON.stringify(beforeValue) !== JSON.stringify(nextValue)) {
+        after = editJsonc(after, keys, nextValue);
+      }
+    }
+  }
+  if (action === 'disable' && removable) after = null;
   return { status: "changed", path: current.path,
     apply() { if (after === null) rmSync(current.path, { force: true }); else atomicWrite(current.path, after); },
     rollback() { restoreSnapshot(snapshot); },

package/lib/mcp-lifecycle/evidence.js

@@ -1,3 +1,4 @@
+import { isRunOwnedDataPath } from '#agdf-core/control-state/run-identity.js';
 const SURFACES = new Set(["codex", "claude", "opencode", "copilot"]);
 const SCOPES = new Set(["project", "user"]);
 const QUALIFICATION_FIELDS = Object.freeze([
@@ -28,7 +29,7 @@ function plainObject(value) {
 }
 
 function evidenceRef(value) {
-  return typeof value === "string" && value.startsWith(".agdf/control/artefacts/") && !value.includes("..");
+  return isRunOwnedDataPath(value);
 }
 
 export function validateMcpQualificationRecord(record) {

package/lib/mcp-lifecycle/facade-entry.js

@@ -1,26 +1,5 @@
-// Private child of the installed launcher. Public input remains MCP STDIO only.
+// Explicit process adapter retained for historical owned packages.
 import process from 'node:process';
-import { dirname, join } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { inspectMcpServerPackage, createMcpGenerationPublisher } from './package.js';
-
+import { startFacadeRuntime } from './facade-runtime.js';
 if (!process.send || !process.argv[2] || process.argv[2].length > 65536) throw Error('AGDF_MCP_FACADE_INPUT_INVALID');
-const { runtime: expected, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns } = JSON.parse(process.argv[2]);
-let handle, stopRequested = false;
-const stop = () => { stopRequested = true; if (handle) void handle.close(); };
-process.on('message', message => { if (message?.kind === 'facade_stop' && message.token === token) stop(); });
-process.on('disconnect', stop); process.on('SIGINT', stop); process.on('SIGTERM', stop);
-const actual = inspectMcpServerPackage({ dataRoot: dirname(expected.root), expectedVersion: expected.version });
-if (actual.status !== 'matched' || actual.root !== expected.root || actual.digest !== expected.digest
-  || actual.dispatcherDigest !== expected.dispatcherDigest || actual.sdkDigest !== expected.sdkDigest) throw Error('AGDF_MCP_FACADE_IDENTITY_INVALID');
-const runtime = { ...actual, immutable: true, publication_id: expected.publication_id, publisher_root: expected.publisher_root };
-process.env.AGDF_DISPATCH_PLUGIN_ROOT = pluginRoot;
-const { runMcpServer } = await import(pathToFileURL(join(runtime.packageRoot, 'src/main.js')));
-handle = await runMcpServer({ surface, cockpitDir, cockpitMode, ownedPublication: runtime,
-  ownedPublisher: createMcpGenerationPublisher(runtime, {
-    publicationDeadline: performance.now() + Math.max(0, Number(BigInt(deadline_ns) - process.hrtime.bigint()) / 1e6),
-  }), onClosed(result) {
-    process.send?.({ kind: 'facade_closed', token, confirmed: result?.confirmed === true }, () => process.disconnect());
-  } });
-if (!handle) throw Error('AGDF_MCP_FACADE_START_UNCONFIRMED');
-if (stopRequested) await handle.close();
+await startFacadeRuntime({ input: JSON.parse(process.argv[2]), channel: { on: (...args) => process.on(...args), send: (...args) => process.send(...args), close: () => process.disconnect() } });

package/lib/mcp-lifecycle/facade-owner-entry.js

@@ -1,29 +1,45 @@
 // Stable launcher-side owner; it loads no immutable SDK code itself. Loss of
 // its host parent requests orderly shutdown, never deletion of active bytes.
 import process from 'node:process';
-import { dirname } from 'node:path';
 import { EventEmitter } from 'node:events';
-import { inspectMcpServerPackage, acquireMcpExecutableClaim } from './package.js';
+import { acquireMcpExecutableClaim } from './package.js';
 import { supervisePluginMcpFacade } from './plugin-runtime.js';
+import { superviseThreadMcpFacade } from './thread-owner.js';
 
 if (!process.send || !process.connected || !process.argv[2] || process.argv[2].length > 65536) throw Error('AGDF_MCP_FACADE_INPUT_INVALID');
-const input = JSON.parse(process.argv[2]), expected = input.runtime;
+const input = JSON.parse(process.argv[2]);
 const signals = new EventEmitter();
-let stopRequested = false, supervising = false;
-const stop = () => { stopRequested = true; if (supervising) signals.emit('SIGTERM'); };
+let stopRequested = false, supervising = false, releaseWaiting;
+const stop = () => { stopRequested = true; releaseWaiting?.(null); if (supervising) signals.emit('SIGTERM'); };
 process.on('disconnect', stop); process.on('SIGINT', stop); process.on('SIGTERM', stop);
 process.on('message', message => { if (message?.kind === 'owner_stop' && message.token === input.token) stop(); });
 try {
-  const actual = inspectMcpServerPackage({ dataRoot: dirname(expected.root), expectedVersion: expected.version });
-  if (actual.status !== 'matched' || actual.root !== expected.root || actual.digest !== expected.digest
-    || actual.dispatcherDigest !== expected.dispatcherDigest || actual.sdkDigest !== expected.sdkDigest) throw Error('AGDF_MCP_FACADE_IDENTITY_INVALID');
-  const runtime = { ...actual, immutable: true, publication_id: expected.publication_id, publisher_root: expected.publisher_root };
-  const publicationDeadline = performance.now() + Math.max(0, Number(BigInt(input.deadline_ns) - process.hrtime.bigint()) / 1e6);
-  const claim = acquireMcpExecutableClaim(runtime, { publicationDeadline });
-  const ended = supervisePluginMcpFacade({ ...input, runtime, env: process.env, claim, signals, deadlineNs: input.deadline_ns });
-  supervising = true;
-  if (stopRequested) signals.emit('SIGTERM');
-  await ended;
+  const expected = input.await_runtime === true ? await new Promise((resolve, reject) => {
+    const remaining = Math.max(0, Number(BigInt(input.deadline_ns) - process.hrtime.bigint()) / 1e6);
+    const timer = setTimeout(() => finish(null, Error('AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED')), remaining);
+    const start = message => { if (message?.kind === 'owner_start' && message.token === input.token) finish(message.runtime); };
+    const finish = (runtime, error) => {
+      clearTimeout(timer); process.off('message', start); releaseWaiting = undefined;
+      if (error) reject(error); else resolve(runtime);
+    };
+    releaseWaiting = finish; process.on('message', start);
+    if (stopRequested) finish(null);
+    else process.send({ kind: 'owner_ready', token: input.token });
+  }) : input.runtime;
+  if (expected) {
+    const publicationDeadline = performance.now() + Math.max(0, Number(BigInt(input.deadline_ns) - process.hrtime.bigint()) / 1e6);
+    // Claim acquisition performs the full current server/dispatcher/SDK inspection
+    // under the publication lock. Continue with its canonical observed paths.
+    const claim = acquireMcpExecutableClaim(expected, { publicationDeadline });
+    const runtime = { ...claim.verifiedRuntime, immutable: true, publication_id: expected.publication_id, publisher_root: expected.publisher_root };
+    // Both SDK-free adapters load during owner bootstrap. There is no await
+    // between the fresh lock-bound claim and actual executable Worker creation.
+    const supervise = runtime.executionModel === 'owner_threads_v1' ? superviseThreadMcpFacade : supervisePluginMcpFacade;
+    const ended = supervise({ ...input, runtime, env: process.env, claim, signals, deadlineNs: input.deadline_ns });
+    supervising = true;
+    if (stopRequested) signals.emit('SIGTERM');
+    await ended;
+  }
   if (process.connected) process.send({ kind: 'owner_closed', token: input.token, confirmed: true }, () => process.disconnect());
 } catch (error) {
   process.exitCode = 1;

package/lib/mcp-lifecycle/facade-runtime.js

@@ -0,0 +1,29 @@
+// Private child of the installed launcher. Public input remains MCP STDIO only.
+import process from 'node:process';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createMcpGenerationPublisher } from './package.js';
+
+export async function startFacadeRuntime({ input, channel, generationTransport, signals = process }) {
+  const { runtime: expected, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns } = input;
+  let handle, stopRequested = false;
+  const stop = () => { stopRequested = true; if (handle) void handle.close(); };
+  channel.on('message', message => { if (message?.kind === 'facade_stop' && message.token === token) stop(); });
+  channel.on('disconnect', stop); signals.on('SIGINT', stop); signals.on('SIGTERM', stop);
+  // The parent freshly claims the complete immutable image immediately before
+  // creating this actual executable. These are expected identities, not a reused
+  // observation. The SDK-free main/protocol load performs its own full fresh
+  // inspection and binds that producer below, before any SDK import/service.
+  const runtime = { ...expected, immutable: true };
+  process.env.AGDF_DISPATCH_PLUGIN_ROOT = pluginRoot;
+  const { runMcpServer } = await import(pathToFileURL(join(runtime.packageRoot, 'src/main.js')));
+  handle = await runMcpServer({ surface, cockpitDir, cockpitMode, ownedPublication: runtime,
+    generationTransport, ownedPublisher: createMcpGenerationPublisher(runtime, {
+      publicationDeadline: performance.now() + Math.max(0, Number(BigInt(deadline_ns) - process.hrtime.bigint()) / 1e6),
+    }), onClosed(result) {
+      channel.send({ kind: 'facade_closed', token, confirmed: result?.confirmed === true }, () => channel.close());
+    } });
+  if (!handle) throw Error('AGDF_MCP_FACADE_START_UNCONFIRMED');
+  if (stopRequested) await handle.close();
+
+}

package/lib/mcp-lifecycle/facade-thread-entry.js

@@ -0,0 +1,11 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { createOwnerClient } from './owner-client.js';
+import { startFacadeRuntime } from './facade-runtime.js';
+if (!parentPort) throw Error('AGDF_MCP_FACADE_INPUT_INVALID');
+const client = createOwnerClient(parentPort, workerData.binding);
+await startFacadeRuntime({ input: workerData.input, generationTransport: client,
+  channel: { ...client.lifecycle, close() {
+    // Node's Worker stdin retains its internal port until readable EOF. The SDK
+    // has stopped reading after close; drain the owner's final EOF naturally.
+    process.stdin.resume(); client.lifecycle.close();
+  } } });

package/lib/mcp-lifecycle/owner-client.js

@@ -0,0 +1,79 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { GENERATION_LIMITS as L, OWNER_LIMITS, ownerFrame, encodeOwnerFrame, decodeOwnerFrame,
+  validGenerationMessage, generationMessage, publicationSelector } from '../mcp-owner-protocol.js';
+
+// Logical connections only. The remote owner holds the genuine Worker objects.
+export function createOwnerClient(port, binding) {
+  const rows = new Map(), pending = new Map(), lifecycle = new EventEmitter();
+  let bytes = 0, disconnected = false;
+  function send(kind, payload, requestId, row) {
+    if (disconnected) throw Error('generation_connection_lost');
+    const frame = ownerFrame(binding, kind, payload, requestId, row);
+    const wire = encodeOwnerFrame(frame, binding);
+    if (pending.size >= OWNER_LIMITS.frames || bytes + Buffer.byteLength(wire) > OWNER_LIMITS.bytes) throw Error('generation_request_capacity');
+    return wire;
+  }
+  const generationFailure = (frame, p) => generationMessage(p.row.epoch, p.row.generation, 'failure', { reason: frame.payload.reason }, {}, p.original, frame.request_id);
+  function release(id) { const p = pending.get(id); if (p) { pending.delete(id); bytes -= p.bytes; clearTimeout(p.timer); } return p; }
+  port.on('message', wire => {
+    let frame; try { frame = decodeOwnerFrame(wire, binding, { reply: true }); } catch { return; }
+    if (frame.kind === 'stop' && frame.generation_id === null && frame.publication_id === binding.publication_id) {
+      lifecycle.emit('message', { kind: 'facade_stop', token: binding.token }); return;
+    }
+    const row = rows.get(frame.generation_id);
+    if (!row || row.epoch !== frame.generation_epoch || row.publication_id !== frame.publication_id) return;
+    const p = pending.get(frame.request_id);
+    if (frame.kind === 'exit' && Object.keys(frame.payload).sort().join() === 'code' && Number.isInteger(frame.payload.code)) {
+      row.connected = false; if (frame.payload.code === 0) rows.delete(row.generation); row.emit('exit', frame.payload.code, null); return;
+    }
+    if (!p || p.row !== row) return;
+    if (frame.kind === 'failure' && typeof frame.payload?.reason === 'string') {
+      release(frame.request_id); p.reject?.(Error(frame.payload.reason)); if (p.kind === 'send') row.emit('message', generationFailure(frame, p));
+    } else if (frame.kind === 'opened' && p.kind === 'open' && frame.payload?.opened === true) {
+      release(frame.request_id); p.resolve(row);
+    } else if (frame.kind === 'message' && p.kind === 'send'
+      && validGenerationMessage(frame.payload, { epoch: row.epoch, generation: row.generation, reply: true })
+      && frame.payload.request_id === frame.request_id && frame.payload.original_operation_id === p.original) {
+      release(frame.request_id); row.emit('message', frame.payload);
+    }
+  });
+  port.on('close', () => {
+    disconnected = true;
+    for (const [id] of pending) { const p = release(id); p.reject?.(Error('generation_connection_lost')); }
+    for (const row of rows.values()) if (row.connected) { row.connected = false; row.emit('disconnect'); }
+    lifecycle.emit('disconnect');
+  });
+  return Object.freeze({
+    lifecycle: {
+      on: (...args) => lifecycle.on(...args),
+      send(value, callback) {
+        if (value?.kind !== 'facade_closed' || value.token !== binding.token || typeof value.confirmed !== 'boolean') throw Error('generation_input_limit');
+        port.postMessage(encodeOwnerFrame(ownerFrame(binding, 'closed', { confirmed: value.confirmed }, randomUUID()), binding)); callback?.();
+      },
+      close: () => port.close(),
+    },
+    async open({ packageInfo, epoch, generation }) {
+      if (rows.size >= L.slots || rows.has(generation)) throw Error('generation_capacity_protected');
+      const row = new EventEmitter(); Object.assign(row, { epoch, generation, publication_id: packageInfo.publication_id, connected: true });
+      rows.set(generation, row);
+      row.send = (message, callback) => {
+        try {
+          if (!row.connected || !validGenerationMessage(message, { epoch, generation }) || pending.has(message.request_id)) throw Error('generation_input_limit');
+          const wire = send('send', message, message.request_id, row);
+          const entry = { kind: 'send', row, original: message.original_operation_id, bytes: Buffer.byteLength(wire) };
+          // Expiry retains the row; uncertainty is handled by the generation router.
+          entry.timer = setTimeout(() => { release(message.request_id); row.emit('message', generationFailure({ payload: { reason: 'generation_response_unknown' }, request_id: message.request_id }, entry)); }, L.qualify);
+          pending.set(message.request_id, entry); bytes += entry.bytes; port.postMessage(wire); callback?.();
+        } catch (error) { callback?.(error); }
+      };
+      const id = randomUUID(), wire = send('open', publicationSelector(packageInfo), id, row);
+      return new Promise((resolve, reject) => {
+        const entry = { kind: 'open', row, resolve, reject, bytes: Buffer.byteLength(wire) };
+        entry.timer = setTimeout(() => { release(id); row.connected = false; reject(Error('generation_response_unknown')); }, L.qualify);
+        pending.set(id, entry); bytes += entry.bytes;
+        try { port.postMessage(wire); } catch (error) { release(id); reject(error); }
+      });
+    },
+  });
+}

package/lib/mcp-lifecycle/package.js

@@ -1,3 +1,4 @@
+import { Worker } from 'node:worker_threads';
 import { ChildProcess, execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import {
@@ -16,16 +17,17 @@ import {
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 import {
+  MCP_RUNTIME_OWNER as OWNER,
+  MCP_RUNTIME_MARKER as MARKER,
+  inspectOwnedMcpRuntimeRoot as inspectPackageRoot,
   digestDirectory,
   digestMcpDispatcherPackage,
   digestMcpSdkRuntime,
 } from "#agdf-core/runtime/plugin-provenance.js";
 import { defaultNpmInstallRoot, npmInvocation } from "../npm-invocation.js";
 import { renameSyncWithRetry } from "#agdf-core/fs-swap.js";
-import { fsyncDirectory, withOwnedFileLock } from '#agdf-core/control-state/run-state-writer.js';
+import { fsyncDirectory, withOwnedFileLock } from '#agdf-core/owned-file-lock.js';
 
-const OWNER = "create-agdf:mcp-runtime";
-const MARKER = ".agdf-mcp-owned.json";
 const CLAIMS = '.agdf-executable-claims';
 
 // Claims are package-local retention evidence, never a PID liveness ledger.
@@ -62,7 +64,7 @@ export function acquireMcpExecutableClaim(runtime, { ownerEpoch = randomUUID(),
     if (realpathSync(root) !== root || lstatSync(root).isSymbolicLink()) throw Error('AGDF_MCP_EXECUTABLE_CLAIM_INVALID');
     const fresh = inspectMcpServerPackage({ dataRoot: dirname(root), expectedVersion: runtime.version });
     if (fresh.status !== 'matched' || fresh.digest !== runtime.digest || fresh.dispatcherDigest !== runtime.dispatcherDigest
-      || fresh.sdkDigest !== runtime.sdkDigest) throw Error('AGDF_MCP_EXECUTABLE_CLAIM_INVALID');
+      || fresh.sdkDigest !== runtime.sdkDigest || fresh.markerPath !== runtime.markerPath) throw Error('AGDF_MCP_EXECUTABLE_CLAIM_INVALID');
     const marker = readJson(runtime.markerPath, 'AGDF_MCP_RUNTIME_MARKER_INVALID');
     if (marker.owner !== OWNER || marker.executable_retention !== 'claimed_immutable'
       || marker.server_digest !== runtime.digest || marker.dispatcher_digest !== runtime.dispatcherDigest
@@ -96,7 +98,14 @@ export function acquireMcpExecutableClaim(runtime, { ownerEpoch = randomUUID(),
         }
       }
     };
-    return Object.freeze({ token, owner_epoch: ownerEpoch, generation,
+    // Reuse this actual, lock-bound inspection in the supervising owner. It
+    // is an observation from this acquisition, never caller-supplied trust.
+    return Object.freeze({ token, owner_epoch: ownerEpoch, generation, verifiedRuntime: fresh,
+      bindOwnedWorker(worker, { confirmedEnd = () => false } = {}) {
+        if (bound || !(worker instanceof Worker) || worker.threadId <= 0) throw Error('AGDF_MCP_EXECUTABLE_CLAIM_INVALID');
+        bound = true;
+        worker.once('exit', code => { try { if (code === 0 && confirmedEnd() === true) releaseConfirmed(); } catch {} });
+      },
       bindOwnedChild(child, { confirmedEnd = () => true } = {}) {
         if (bound || !(child instanceof ChildProcess)) throw Error('AGDF_MCP_EXECUTABLE_CLAIM_INVALID');
         bound = true;
@@ -166,81 +175,6 @@ export function inspectMcpExecutableRoot({ root, expectedVersion } = {}) {
 
 // Retirement checks the same verified package after its owned atomic rename.
 // It must not accidentally inspect a new package at the former version path.
-function inspectPackageRoot(root, expectedVersion) {
-  const markerPath = join(root, MARKER);
-  if (!existsSync(root)) return Object.freeze({ status: "absent", root, entrypoint: null, digest: null });
-  if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink() || !existsSync(markerPath)) {
-    return Object.freeze({ status: "foreign", root, entrypoint: null, digest: null });
-  }
-  try {
-    const marker = readJson(markerPath, "AGDF_MCP_RUNTIME_MARKER_INVALID");
-    const packageRoot = join(root, "node_modules", "@agdf", "mcp-server");
-    const dispatcherRoot = join(root, "node_modules", "create-agdf");
-    const sdkServerRoot = join(root, "node_modules", "@modelcontextprotocol", "server");
-    const sdkCoreRoot = join(root, "node_modules", "@modelcontextprotocol", "core");
-    const sdkClientRoot = join(root, "node_modules", "@modelcontextprotocol", "client");
-    const sdkV1Root = join(root, "node_modules", "@modelcontextprotocol", "sdk");
-    const manifestPath = join(packageRoot, "package.json");
-    const dispatcherManifestPath = join(dispatcherRoot, "package.json");
-    if (marker.owner !== OWNER || marker.version !== expectedVersion
-        || !existsSync(manifestPath) || !existsSync(dispatcherManifestPath)) {
-      return Object.freeze({ status: "mismatch", root, entrypoint: null, digest: null });
-    }
-    for (const ownedRoot of [packageRoot, dispatcherRoot, sdkServerRoot, sdkCoreRoot]) {
-      if (!existsSync(ownedRoot) || !lstatSync(ownedRoot).isDirectory() || lstatSync(ownedRoot).isSymbolicLink()) {
-        return Object.freeze({ status: "mismatch", root, entrypoint: null, digest: null });
-      }
-    }
-    const manifest = readJson(manifestPath, "AGDF_MCP_SERVER_MANIFEST_INVALID");
-    const dispatcherManifest = readJson(dispatcherManifestPath, "AGDF_MCP_DISPATCHER_MANIFEST_INVALID");
-    const sdkServerManifest = readJson(join(sdkServerRoot, "package.json"), "AGDF_MCP_SDK_MANIFEST_INVALID");
-    const sdkCoreManifest = readJson(join(sdkCoreRoot, "package.json"), "AGDF_MCP_SDK_MANIFEST_INVALID");
-    const entrypoint = join(packageRoot, "bin", "agdf-mcp.js");
-    const serverDigest = digestDirectory(packageRoot);
-    const dispatcherDigest = digestMcpDispatcherPackage(dispatcherRoot);
-    const sdkDigest = digestMcpSdkRuntime(root);
-    const valid = [1, 2].includes(marker.schema_version)
-      && typeof marker.node_executable === "string"
-      && isAbsolute(marker.node_executable)
-      && manifest.name === "@agdf/mcp-server"
-      && manifest.version === expectedVersion
-      && manifest.dependencies?.["create-agdf"] === expectedVersion
-      && manifest.dependencies?.["@modelcontextprotocol/server"] === "2.0.0"
-      && manifest.engines?.node === ">=22"
-      && dispatcherManifest.name === "create-agdf"
-      && dispatcherManifest.version === expectedVersion
-      && sdkServerManifest.name === "@modelcontextprotocol/server"
-      && sdkServerManifest.version === "2.0.0"
-      && sdkCoreManifest.name === "@modelcontextprotocol/core"
-      && sdkCoreManifest.version === "2.0.0"
-      && !existsSync(sdkClientRoot)
-      && !existsSync(sdkV1Root)
-      && existsSync(entrypoint)
-      && lstatSync(entrypoint).isFile()
-      && !lstatSync(entrypoint).isSymbolicLink()
-      && marker.server_digest === serverDigest
-      && marker.dispatcher_digest === dispatcherDigest
-      && marker.sdk_digest === sdkDigest;
-    return Object.freeze({
-      status: valid ? "matched" : "mismatch",
-      version: expectedVersion,
-      root,
-      packageRoot,
-      dispatcherRoot,
-      markerPath,
-      entrypoint: valid ? entrypoint : null,
-      digest: serverDigest,
-      dispatcherDigest,
-      sdkDigest,
-      nodeExecutable: typeof marker.node_executable === "string" ? marker.node_executable : null,
-      references: Object.freeze(Array.isArray(marker.references) ? marker.references : []),
-      markerSchemaVersion: marker.schema_version,
-      sdkVerification: typeof marker.sdk_verification === "string" ? marker.sdk_verification : null,
-    });
-  } catch {
-    return Object.freeze({ status: "mismatch", root, entrypoint: null, digest: null });
-  }
-}
 
 // Names of all packages installed under root/node_modules, scoped included; npm's dot entries
 // (.bin, .package-lock.json) are bookkeeping, not packages.

package/lib/mcp-lifecycle/plugin-runtime.js

@@ -3,7 +3,7 @@ import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, re
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 import { createHash, randomUUID } from 'node:crypto';
-import { digestDirectory, digestPluginMcpDispatcherSource, MCP_DISPATCHER_RUNTIME_ENTRIES } from "#agdf-core/runtime/plugin-provenance.js";
+import { digestDirectory, digestPluginMcpDispatcherSource, mcpDispatcherRuntimeEntries, mcpDispatcherPackageExports } from "#agdf-core/runtime/plugin-provenance.js";
 import { acquireMcpExecutableClaim, inspectMcpServerPackage, mcpPackageConstants, mcpRuntimeRetirementState, prepareMcpServerPackage, createMcpRuntimeRetirementTransaction } from "./package.js";
 
 // Plugin-local AGDF MCP runtime shared by the hosts whose runtime plugin declares the server itself:
@@ -39,7 +39,7 @@ function copyPluginPackages({ pluginRoot, stage, version }) {
   }
   cpSync(serverSource, join(stage, "node_modules", "@agdf", "mcp-server"), { recursive: true });
   const dispatcherRoot = join(stage, "node_modules", "create-agdf");
-  for (const entry of MCP_DISPATCHER_RUNTIME_ENTRIES.filter((item) => item !== "package.json")) {
+  for (const entry of mcpDispatcherRuntimeEntries(runtimePackage).filter((item) => item !== "package.json")) {
     cpSync(join(runtimePackage, entry), join(dispatcherRoot, entry), { recursive: true });
   }
   writeFileSync(join(dispatcherRoot, "package.json"), `${JSON.stringify({
@@ -47,7 +47,7 @@ function copyPluginPackages({ pluginRoot, stage, version }) {
     version,
     private: true,
     type: "module",
-    exports: { "./mcp-dispatch-runtime": "./lib/mcp-dispatch-runtime.js" },
+    exports: mcpDispatcherPackageExports(runtimePackage),
     imports: { "#agdf-core": "./runtime/core/lib/index.js", "#agdf-core/*": "./runtime/core/lib/*" },
   }, null, 2)}\n`, "utf8");
 }
@@ -250,8 +250,13 @@ export async function launchPluginMcpServer({
   }
   const { surface, dataRoot, cockpitDir, cockpitMode, prepareOnly } = invocation;
   const publicationDeadline = performance.now() + CONCURRENT_PUBLICATION_WAIT_MS;
-  let runtime;
+  let runtime, waitingOwner;
   try {
+    // Bootstrap only the existing SDK-free owner while this process performs
+    // preparation. It cannot claim or start a facade until the private message
+    // carries the successfully verified publication.
+    if (!prepareOnly && !startFacade && acquireClaim === acquireMcpExecutableClaim && ensure === ensurePluginMcpRuntime)
+      waitingOwner = startFacadeOwner({ surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline });
     // Reject a damaged installed dispatcher before publication, claim acquisition
     // or SDK execution. Its downstream resource context cannot qualify a facade;
     // starting one first would correctly retain its unconfirmed executable use.
@@ -262,6 +267,7 @@ export async function launchPluginMcpServer({
     }
     runtime = ensure({ pluginRoot, dataRoot, env, publicationDeadline });
   } catch (error) {
+    if (waitingOwner) { waitingOwner.stop(); await waitingOwner.settled.catch(() => {}); }
     const code = /^AGDF_[A-Z_]+/.exec(error?.message ?? "")?.[0] ?? 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
     stderr.write(`${launcherFailureLine(code, code === 'AGDF_MCP_PLUGIN_RUNTIME_FAILED' ? 'preparation' : undefined)}\n`);
     process.exitCode = 1;
@@ -278,7 +284,11 @@ export async function launchPluginMcpServer({
   // The stable launcher directly owns the facade process. It retains its exact
   // executable before fork and releases only after orderly teardown AND exit.
   if (!startFacade && acquireClaim === acquireMcpExecutableClaim) {
-    try { return await startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline }); }
+    try {
+      const owner = waitingOwner ?? startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline });
+      waitingOwner?.activate(runtime);
+      return await owner.settled;
+    }
     catch (error) { const code = Object.hasOwn(LAUNCHER_FAILURES, error?.message) ? error.message : 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
       stderr.write(`${launcherFailureLine(code, code === 'AGDF_MCP_PLUGIN_RUNTIME_FAILED' ? 'facade' : undefined)}\n`); process.exitCode = 1; return null; }
   }
@@ -326,15 +336,21 @@ export function supervisePluginMcpFacade({ runtime, surface, cockpitDir, cockpit
 function startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline }) {
   const token = randomUUID();
   const deadline = (process.hrtime.bigint() + BigInt(Math.floor(Math.max(0, publicationDeadline - performance.now()) * 1e6))).toString();
-  return new Promise((resolve, reject) => {
+  let activate, stop;
+  const settled = new Promise((resolve, reject) => {
     const child = fork(join(pluginRoot, 'runtime/create-agdf/lib/mcp-lifecycle/facade-owner-entry.js'),
-      [JSON.stringify({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns: deadline })],
+      [JSON.stringify({ runtime, await_runtime: runtime === undefined, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns: deadline })],
       { env, detached: true, windowsHide: true, stdio: ['inherit', 'inherit', 'inherit', 'ipc'], execArgv: [] });
-    let confirmed = false, failure;
-    const stop = () => { if (child.connected) child.send({ kind: 'owner_stop', token }, () => {}); };
+    let confirmed = false, failure, ready = runtime !== undefined, pending, stopped = false;
+    const send = message => { if (child.connected) child.send(message, error => { if (error) reject(error); }); };
+    stop = () => { stopped = true; if (ready && child.connected) child.send({ kind: 'owner_stop', token }, () => {}); };
+    activate = publication => { pending = publication; if (ready && !stopped) send({ kind: 'owner_start', token, runtime: pending }); };
     process.once('SIGTERM', stop); process.once('SIGINT', stop);
     const detach = () => { process.off('SIGTERM', stop); process.off('SIGINT', stop); };
     child.on('message', message => {
+      if (message?.kind === 'owner_ready' && message.token === token && !ready) {
+        ready = true; if (stopped) stop(); else if (pending) activate(pending);
+      }
       if (message?.kind === 'owner_closed' && message.token === token && message.confirmed === true) confirmed = true;
       if (message?.kind === 'owner_failed' && message.token === token && Object.hasOwn(LAUNCHER_FAILURES, message.code)) failure = message.code;
     });
@@ -344,6 +360,10 @@ function startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoo
       else reject(Error(failure ?? 'AGDF_MCP_FACADE_CLOSE_UNCONFIRMED'));
     });
   });
+  // Preparation is synchronous; the owner can fail first while its promise is
+  // intentionally not awaited yet. Keep that rejection observed in both phases.
+  settled.catch(() => {});
+  return Object.freeze({ settled, activate: publication => activate(publication), stop: () => stop() });
 }
 
 export function claudePluginDataRoot({ claudeConfigDir, pluginId = "agdf@agdf" }) {

package/lib/mcp-lifecycle/profile.js

@@ -1,4 +1,5 @@
 import { mcpQualificationFields, validateMcpQualificationRecord } from "./evidence.js";
+import { SKILL_DISPATCH_FUNCTION_DEFINITION } from '#agdf-core/skill-dispatch/contract.js';
 
 const CAPABILITY_STATES = new Set(["supported", "manual_compatible", "unavailable", "unsupported", "unverified"]);
 const REGISTRATION_STATES = new Set(["absent", "matched", "foreign", "owned_mismatch", "precedence_conflict", "invalid"]);
@@ -26,7 +27,7 @@ export function validateMcpCapabilityProfile(profile, { expectedVersion } = {})
   if (profile?.tool?.semantic_owner !== "packages/core/lib/skill-dispatch/contract.js") errors.push("semantic_owner");
   if (Object.hasOwn(profile?.tool ?? {}, "description") || Object.hasOwn(profile?.tool ?? {}, "input_schema")
       || Object.hasOwn(profile?.tool ?? {}, "output_schema")) errors.push("duplicated_tool_semantics");
-  if (profile?.tool?.authorizes !== false || profile?.tool?.read_only !== true) errors.push("tool_boundary");
+  if (profile?.tool?.authorizes !== false || profile?.tool?.read_only !== SKILL_DISPATCH_FUNCTION_DEFINITION.annotations.readOnlyHint) errors.push("tool_boundary");
   if (profile?.package?.name !== "@agdf/mcp-server" || profile?.package?.sdk_server !== "2.0.0") errors.push("package");
   if (profile?.lifecycle?.owner !== "create-agdf" || profile?.lifecycle?.default_scope !== "project") errors.push("lifecycle");
   if (profile?.lifecycle?.result_contract_version !== 2) errors.push("result_contract_version");