create-agdf 0.20.2 → 0.30.0

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/service.js

@@ -1,3 +1,4 @@
+import { isRunOwnedDataPath } from '#agdf-core/control-state/run-identity.js';
 import { execHostFileSync } from "../host-command.js";
 import { realpathSync, statSync, readFileSync, lstatSync, existsSync } from "node:fs";
 import { createHash } from 'node:crypto';
@@ -214,8 +215,8 @@ export function runMcpLifecycle({
       runtime: { status: 'not_evaluated', version: expectedVersion }, registration: null };
     try {
       const evidencePath = resolve(selectedTarget, cockpitEvidence);
-      const containment = relative(join(selectedTarget, '.agdf/control/artefacts'), evidencePath);
-      if (containment.startsWith('..') || isAbsolute(containment) || realpathSync(evidencePath) !== evidencePath
+      const containment = relative(selectedTarget, evidencePath).split('\\').join('/');
+      if (!isRunOwnedDataPath(containment) || realpathSync(evidencePath) !== evidencePath
         || lstatSync(evidencePath).size > 65_536) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
       const bytes = readFileSync(evidencePath, 'utf8'), evidence = JSON.parse(bytes);
       const digest = 'sha256:' + createHash('sha256').update(bytes).digest('hex');
@@ -232,8 +233,8 @@ export function runMcpLifecycle({
           return 'sha256:' + createHash('sha256').update(readFileSync(path)).digest('hex');
         };
         for (const ref of evidence.evidence) {
-          const file = resolve(selectedTarget, ref.path), rel = relative(join(selectedTarget, '.agdf/control/artefacts'), file);
-          if (rel.startsWith('..') || isAbsolute(rel) || readDigest(file) !== ref.digest) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
+          const file = resolve(selectedTarget, ref.path), rel = relative(selectedTarget, file).split('\\').join('/');
+          if (!isRunOwnedDataPath(rel) || readDigest(file) !== ref.digest) throw Error('AGDF_MCP_COCKPIT_EVIDENCE_INVALID');
         }
         if (env.AGDF_DISPATCH_PLUGIN_ROOT && (resolve(env.AGDF_DISPATCH_PLUGIN_ROOT) !== evidence.plugin_root
           || existsSync(env.AGDF_DISPATCH_PLUGIN_ROOT) && realpathSync(env.AGDF_DISPATCH_PLUGIN_ROOT) !== evidence.plugin_root))

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

@@ -0,0 +1,164 @@
+import { Worker } from 'node:worker_threads';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import process from 'node:process';
+import { createMcpGenerationPublisher } from './package.js';
+import { GENERATION_LIMITS as L, OWNER_LIMITS, generationMessage, validGenerationMessage,
+  generationFailureReason, ownerFrame, encodeOwnerFrame, decodeOwnerFrame, publicationSelector } from '../mcp-owner-protocol.js';
+
+// The detached retention owner alone owns actual Worker objects and claims.
+// It imports no SDK or domain factory. Protected slots survive uncertain exits.
+export function superviseThreadMcpFacade({ runtime, surface, cockpitDir, cockpitMode, pluginRoot,
+  env, claim, signals = process, deadlineNs } = {}) {
+  const binding = { token: claim.token, connection_epoch: randomUUID(), publication_id: runtime.publication_id };
+  const publicationDeadline = performance.now() + Math.max(0, Number(BigInt(deadlineNs) - process.hrtime.bigint()) / 1e6);
+  const publisher = createMcpGenerationPublisher(runtime, { publicationDeadline });
+  const rows = new Map(), seen = new Set();
+  let generationEpoch, highestGeneration = 0;
+  let facade, facadeExited = false, facadeAck = false, failed = false, pendingBytes = 0, pendingCount = 0;
+  const post = (kind, payload, id, row) => {
+    if (facadeExited) return;
+    facade.postMessage(encodeOwnerFrame(ownerFrame(binding, kind, payload, id, row), binding, { reply: true }));
+  };
+  function release(row, id) {
+    const entry = row.pending.get(id);
+    if (entry) { row.pending.delete(id); pendingBytes -= entry.bytes; --pendingCount; clearTimeout(entry.timer); }
+    return entry;
+  }
+  function transmit(row, message, { orphan = false, bytes = 0 } = {}) {
+    if (!row.worker || row.exited || row.pending.has(message.request_id)
+      || pendingCount >= OWNER_LIMITS.frames || pendingBytes + bytes > OWNER_LIMITS.bytes) throw Error('generation_request_capacity');
+    const entry = { message, orphan, bytes };
+    row.pending.set(message.request_id, entry); ++pendingCount; pendingBytes += bytes;
+    // An expired call is protected, not removed/replayed. A late reply can still
+    // settle ownership; until then its credit and slot remain occupied.
+    entry.timer = setTimeout(() => {
+      // The still-pending exact request protects the slot and claim. A later
+      // validated matching reply can prove completion; timeout alone cannot.
+      if (!orphan) post('failure', { reason: 'generation_response_unknown' }, message.request_id, row);
+    }, message.kind === 'shutdown' ? L.close : L.qualify);
+    row.worker.postMessage(JSON.stringify(message));
+  }
+  function drain(row) {
+    if (!facadeExited || row.exited || row.draining || row.pending.size || row.uncertain) return;
+    row.draining = true;
+    try { transmit(row, generationMessage(row.epoch, row.generation, 'session_inspect', {}, {}, null, randomUUID()), { orphan: true }); }
+    catch { row.uncertain = true; }
+  }
+  function receive(row, wire) {
+    if (typeof wire !== 'string' || Buffer.byteLength(wire) > L.result) { row.uncertain = true; return; }
+    let reply; try { reply = JSON.parse(wire); } catch { row.uncertain = true; return; }
+    if (!validGenerationMessage(reply, { epoch: row.epoch, generation: row.generation, reply: true })) { row.uncertain = true; return; }
+    const entry = row.pending.get(reply.request_id);
+    const expected = { qualify: 'qualified', invoke: 'result', session_inspect: 'status', shutdown: 'closed' }[entry?.message.kind];
+    if (!entry || reply.original_operation_id !== entry.message.original_operation_id
+      || reply.kind !== expected && reply.kind !== 'failure') { row.uncertain = true; return; }
+    release(row, reply.request_id);
+    if (reply.kind === 'closed') row.closeAck = !reply.payload.views && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain;
+    if (entry.message.original_operation_id && (reply.kind === 'failure' || reply.payload?.outcome === 'effect_unknown')) row.unknown.add(entry.message.original_operation_id);
+    const args = entry.message.payload?.arguments;
+    if (entry.message.payload?.name === 'agdf_inspect' && args?.operation === 'operation-status' && reply.payload?.report?.status === 'recorded'
+      && (reply.payload.report.receipt?.operation_id ?? reply.payload.report.receipt?.operation?.operation_id) === args.module.split('/').at(-1)) row.unknown.delete(args.module.split('/').at(-1));
+    if (entry.orphan) {
+      if (reply.kind === 'status' && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain && !row.unknown.size) {
+        try { transmit(row, generationMessage(row.epoch, row.generation, 'shutdown', {}, {}, null, randomUUID()), { orphan: true }); }
+        catch { row.uncertain = true; }
+      } else if (reply.kind !== 'closed') row.uncertain = true;
+    } else {
+      try { post('message', reply, reply.request_id, row); } catch { row.uncertain = true; }
+      drain(row);
+    }
+  }
+  function open(frame) {
+    if (rows.size >= L.slots || rows.has(frame.generation_id) || !frame.generation_epoch
+      || generationEpoch && frame.generation_epoch !== generationEpoch || frame.generation_id <= highestGeneration
+      || highestGeneration === 0 && (frame.generation_id !== 1 || frame.publication_id !== binding.publication_id)
+      || frame.payload?.publication_id !== frame.publication_id) throw Error('generation_capacity_protected');
+    // Re-resolve the actual candidate every time, never reuse the initial image
+    // across async boundaries or accept caller-selected paths.
+    generationEpoch ??= frame.generation_epoch; highestGeneration = frame.generation_id;
+    const initial = frame.generation_id === 1;
+    const expected = publicationSelector(runtime);
+    if (initial && (Object.keys(frame.payload).sort().join() !== Object.keys(expected).sort().join()
+      || Object.keys(expected).some(key => frame.payload[key] !== expected[key]))) throw Error('runtime_candidate_manifest_invalid');
+    // Initial identity is already bound, but never trusted across this async
+    // boundary: acquire below repeats the full fresh inspection under lock.
+    // Replacements additionally resolve through the existing publisher.
+    const selected = initial ? runtime : publisher.resolve(frame.payload);
+    if (selected.executionModel !== 'owner_threads_v1') throw Error('generation_manifest_incompatible');
+    const row = { epoch: frame.generation_epoch, generation: frame.generation_id, publication_id: frame.publication_id,
+      pending: new Map(), unknown: new Set(), uncertain: false, exited: false, closeAck: false };
+    rows.set(row.generation, row);
+    try {
+      const owned = publisher.acquire(selected, { ownerEpoch: row.epoch, generation: row.generation, ...(row.generation === 1 ? { publicationDeadline } : {}) });
+      row.claim = owned;
+      const worker = new Worker(pathToFileURL(join(selected.packageRoot, 'src/generation-thread-entry.js')),
+        { workerData: { epoch: row.epoch, generation: row.generation }, stdin: false, stdout: true, stderr: true, env: { ...env, AGDF_DISPATCH_PLUGIN_ROOT: pluginRoot }, execArgv: [] });
+      row.worker = worker;
+      // Domain output cannot contaminate the facade's public MCP STDOUT.
+      worker.stdout.resume(); worker.stderr.pipe(process.stderr, { end: false });
+      owned.bindOwnedWorker(worker, { confirmedEnd: () => row.closeAck && !row.pending.size && !row.unknown.size && !row.uncertain });
+      worker.on('message', wire => receive(row, wire));
+      worker.once('error', () => { row.uncertain = true; });
+      worker.once('exit', code => {
+        row.exited = true;
+        for (const entry of row.pending.values()) clearTimeout(entry.timer);
+        if (code === 0 && row.closeAck && !row.pending.size && !row.unknown.size && !row.uncertain) rows.delete(row.generation);
+        else { row.uncertain = true; failed = true; }
+        try { post('exit', { code }, randomUUID(), row); } catch { failed = true; }
+      });
+      post('opened', { opened: true }, frame.request_id, row);
+    } catch (error) {
+      if (!row.claim) rows.delete(row.generation);
+      else { row.uncertain = true; failed = true; }
+      throw error;
+    }
+  }
+  return new Promise((resolve, reject) => {
+    facade = new Worker(pathToFileURL(join(runtime.dispatcherRoot, 'lib/mcp-lifecycle/facade-thread-entry.js')),
+      { workerData: { input: { runtime, surface, ...(cockpitDir ? { cockpitDir } : {}), ...(cockpitMode ? { cockpitMode } : {}),
+        pluginRoot, token: claim.token, deadline_ns: deadlineNs }, binding }, env, stdin: true, stdout: true, stderr: true, execArgv: [] });
+    claim.bindOwnedWorker(facade, { confirmedEnd: () => facadeAck && !failed && rows.size === 0 });
+    // Native streams implement actual backpressure in both directions.
+    facade.stdout.pipe(process.stdout, { end: false }); facade.stderr.pipe(process.stderr, { end: false }); process.stdin.pipe(facade.stdin);
+    facade.stdin.on('error', () => {});
+    const stop = () => { try { post('stop', {}, randomUUID()); } catch { failed = true; } };
+    const detach = () => {
+      signals.off('SIGTERM', stop); signals.off('SIGINT', stop); signals.off('disconnect', stop); process.stdin.unpipe(facade.stdin);
+    };
+    signals.on('SIGTERM', stop); signals.on('SIGINT', stop); signals.on('disconnect', stop);
+    facade.on('message', wire => {
+      let frame;
+      try {
+        frame = decodeOwnerFrame(wire, binding);
+        if (seen.has(frame.request_id) || seen.size >= OWNER_LIMITS.history) throw Error('generation_request_capacity');
+        seen.add(frame.request_id);
+        if (frame.kind === 'closed' && frame.generation_id === null && frame.publication_id === binding.publication_id
+          && Object.keys(frame.payload).join() === 'confirmed' && typeof frame.payload.confirmed === 'boolean') {
+          facadeAck = frame.payload.confirmed;
+          // A signalled client may keep public stdin open. After the facade's
+          // own close acknowledgement, finish its real input stream so the
+          // Worker can exit naturally and supply actual lifetime evidence.
+          process.stdin.unpipe(facade.stdin); process.stdin.pause(); facade.stdin.end(); return;
+        }
+        if (frame.kind === 'open') { open(frame); return; }
+        const row = rows.get(frame.generation_id);
+        if (!row || row.epoch !== frame.generation_epoch || row.publication_id !== frame.publication_id
+          || frame.kind !== 'send' || !validGenerationMessage(frame.payload, { epoch: row.epoch, generation: row.generation })
+          || frame.request_id !== frame.payload.request_id) throw Error('generation_input_limit');
+        transmit(row, frame.payload, { bytes: Buffer.byteLength(wire) });
+      } catch (error) {
+        if (frame) try { post('failure', { reason: generationFailureReason(error) }, frame.request_id,
+          { epoch: frame.generation_epoch, generation: frame.generation_id, publication_id: frame.publication_id }); } catch { failed = true; }
+      }
+    });
+    facade.once('error', () => { failed = true; });
+    facade.once('exit', code => {
+      facadeExited = true; detach();
+      for (const row of rows.values()) drain(row);
+      if (code === 0 && facadeAck && !failed && rows.size === 0) resolve({ closed: true, confirmed_exit: true });
+      else reject(Error('AGDF_MCP_FACADE_CLOSE_UNCONFIRMED'));
+    });
+  });
+}

package/lib/mcp-owner-protocol.js

@@ -0,0 +1 @@
+export * from '#agdf-core/runtime/mcp-owner-protocol.js';