create-agdf 0.14.4 → 0.20.0

package/generated/plugins/agdf/mcp/server/README.md

@@ -0,0 +1,136 @@
+# @agdf/mcp-server
+
+Local STDIO MCP adapter for AGDF dispatch and control inspection.
+
+MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
+
+The bounded write groups, selected contract/status reads, original-operation recovery and
+focused app-only decision facade are described in [Core and MCP command flow](../../docs/architecture/core-mcp-command-flow.md).
+Host tool permission is separate from a deliberate gate decision. The source candidate's
+click actions remain disabled while native app-only mediation is unqualified.
+
+`agdf_inspect` also exposes read-only draft preflight through `operation: artifact-readiness`:
+
+```json
+{
+  "operation": "artifact-readiness",
+  "presentation_language": "de",
+  "working_directory": "/absolute/repository",
+  "target_source": "explicit_target",
+  "primary_target": "/absolute/repository",
+  "run_id": "selected-run",
+  "gate": "PRD",
+  "expected_revision_id": "00000000-0000-4000-8000-000000000000"
+}
+```
+
+Supply the actual current revision. Supported drafts are UR, PRD, SD and TP; their canonical
+run-local path is derived by Core. `report.ready` means the existing authoring checks passed,
+including required localized summary and applicable product-decision/traceability checks.
+`checks`, `diagnostics` and `next_action` explain failures, with exact source digest and revision
+when available. Core uses a bounded, revalidated read snapshot. The operation never registers,
+reseals, prepares a presentation or approves anything; semantic derivation and reviewed source
+bindings remain separate. An absent or unsafe source, stale revision or current control blocker
+is unready. QA decisions and UAT are outside this authoring preflight.
+
+To read an existing prepared document, obtain the current run revision with `gate-check`, then
+read `operation-contract` with `module: agdf_prepare/presentation.prepare`. Its derived
+`inspect_contract` explains arguments/examples; `presentation_catalog` supplies validated
+`read_arguments`. A complete unique match is readable; several matches require selection.
+Absence or an unavailable/partial catalog cannot justify guessing or preparing another record.
+Follow every returned `next_cursor` with `presentation-document` to reconstruct the frozen bytes.
+Keep the original document revision, including for historical reads. Catalog pages contain at most
+16 candidates; scans stop at 256 records, 1 MiB of record bytes or 1024 directory entries. Catalog,
+document and preview cursors are not interchangeable. Prepared records prove no human approval.
+
+Dispatch follows the canonical skill-dispatch contract;
+inspect exposes read-only doctor, gate-check, delivery-map and contract operations.
+
+The shared Core continuation service may record one previously sealed relationship correction
+for an authorized bound `continue_delivery` request, then route the same run afresh. The routing
+service itself remains read-only. Accordingly, `agdf_dispatch` declares `readOnlyHint: false`;
+`agdf_inspect` declares `readOnlyHint: true`. Neither tool creates an approval.
+
+> [!IMPORTANT]
+> This package documents the repository development build. The previously published AGDF 0.14.5 release
+> did not include the MCP support described here. Repository assemblies and local plugin builds still
+> carry the canonical version `0.14.5`, but can contain these newer MCP features. The version alone
+> does not identify the payload: verify the assembly or installed runtime digests and the loaded session.
+> These development instructions do not establish what a current npm `@latest` resolution contains.
+
+The server requires Node.js 22 or later, exposes no generic shell, filesystem or network operation,
+and never grants AGDF approval or delivery authority. Use the `create-agdf` lifecycle command to
+prepare and register the exact version-matched server for a delivered host adapter. Host support
+remains unverified until direct registration, discovery, invocation, failure and removal evidence exists.
+
+The guided `codex`, `claude`, `copilot` and `opencode` installers can call that same lifecycle after
+the user explicitly chooses complete setup. In non-interactive use this requires `--with-mcp` and
+an entered absolute `--dir`; otherwise installation remains plugin-only. The plugin transaction and
+MCP transaction retain separate results and recovery. A verified plugin is never rolled back only
+because MCP setup fails. Marketplace-only installation has no CLI callback and therefore remains
+plugin-only.
+
+`agdf_dispatch` requires `presentation_language` as one well-formed BCP 47 tag. The host selects it
+from the latest natural-language request: an explicit response-language instruction wins, otherwise
+the dominant language is used, with `en` for mixed or ambiguous input. Missing or invalid input is
+rejected by the MCP schema before governance evaluation. A valid unsupported tag is accepted and
+renders through the complete English locale pack. The production tests exercise this contract
+separately for protocol versions `2025-11-25` and `2026-07-28`.
+
+### Selected Cockpit draft authoring check
+
+`agdf_cockpit_read` additionally supports `artifact_readiness` with exactly `session_id`, `snapshot_id`, `run_id`, `gate` (`UR | PRD | SD | TP`) and `expected_revision_id`. It checks the currently observed, supported unapproved canonical draft, including an unregistered draft where supported. It accepts no target/path/writer/general-inspect override.
+
+The same Core authoring projection serves standalone inspection and the scoped reader. The selected descriptor captures the draft file or absence before the snapshot freezes. The check validates the old binding, replaces the read scope with a same-Run capture, revalidates revision/gate/source before publication, and reissues resource selectors. Session/worker/pool and source observers adopt that capture together; context cleanup quarantine and existing bounds remain enforced.
+
+The optional selected-detail `draft_check` contains source metadata, the unchanged authoring report and a Core-derived display/recovery state. A passed report never grants semantic review, registration, approval, implementation permission or QA. Old operations remain compatible; a client against a server lacking this descriptor shows bounded unavailable without a general-tool fallback.
+
+## Repository test dependencies
+
+Prepare the current source assembly before installing or running MCP package tests:
+
+```sh
+npm run build:prepare
+npm --prefix packages/mcp-server ci --ignore-scripts
+npm --prefix packages/mcp-server run test:protocol
+npm --prefix packages/mcp-server run test:safety
+```
+
+Run these commands from the repository root. The repository lock resolves `create-agdf` from
+`dist/npm/create-agdf`, which includes the assembled Core and generated resources. The published
+package dependency remains version-pinned. Safety and cockpit-gating tests import that assembly
+directly, so rebuilding it cannot leave those tests using an older same-version npm copy.
+Other package-consumer tests create their own isolated runtimes from the same assembly. Installing
+SDK dependencies is a separate preparation step; these tests neither update a host installation
+nor qualify a native session. A direct `node test/...` invocation also requires the preparation.
+
+Business failures use MCP `isError: true`, preserve the public domain result in
+`structuredContent` and the first text block, and append one bounded EN/DE
+explanation with the cause, known effect limit and supported correction. Success
+keeps its existing single block, including exact decision presentation text.
+Successful doctor, readiness, operation-status and freshness observations remain
+successful when they report blocked, not-ready or unknown state. SDK input errors
+and protocol errors retain their SDK-owned behavior.
+
+The producing runtime owns the pure `agdf-tool-result/1` projection. Its checked
+private descriptor travels with an old generation's result and is consumed before
+public serialization; generation qualification includes that contract version.
+Error-domain invariants are checked even though SDK 2 skips output validation for
+error results. Existing response limits include the explanation and fallback.
+Known parse rejection means not dispatched; timeout, cancellation after handoff or
+a lost connection cannot establish rollback. For an uncertain command, inspect
+`operation-status` with the original UUID and retain its exact payload. Recovery,
+receipts, approval eligibility and any permitted replay remain Core-owned.
+
+Worker requests retain a ten-second total deadline, including shutdown confirmation.
+Execution reserves up to one second (one quarter of shorter configured deadlines) for
+termination. Capacity and owned locks are released only after confirmed termination or
+an observed exit, including an exit after a rejected termination request. If shutdown
+remains unconfirmed, the error preserves the typed `cause_code` when one exists and the
+last allowlisted `worker_phase` in diagnostics and the bounded explanation. Result content
+and raw exception text never become a cause; an uncertain worker continues to block reuse.
+
+This follows the [MCP tool error contract](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#error-handling)
+and [SDK error behavior](https://ts.sdk.modelcontextprotocol.io/v2/servers/errors).
+Local protocol, package and browser tests do not establish native host or agent
+performance; the unchanged ergonomics comparison records that evidence separately.

package/generated/plugins/agdf/mcp/server/bin/agdf-mcp.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import process from "node:process";
+
+const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+if (!Number.isInteger(major) || major < 22) {
+  process.stderr.write("AGDF_MCP_NODE_UNSUPPORTED\n");
+  process.exitCode = 1;
+} else {
+  const args = process.argv.slice(2);
+  const valid = (args.length === 2 || args.length === 4 && ['codex', 'claude'].includes(args[1]) && args[2] === '--cockpit-dir')
+    && args[0] === "--surface"
+    && ["codex", "claude", "copilot", "opencode"].includes(args[1]);
+  if (!valid) {
+    process.stderr.write("AGDF_MCP_ARGUMENTS_INVALID\n");
+    process.exitCode = 1;
+  } else {
+    const { runMcpServer } = await import("../src/main.js");
+    try { await runMcpServer({ surface: args[1], cockpitDir: args.length === 4 ? args[3] : undefined }); }
+    catch (error) {
+      process.stderr.write(['AGDF_COCKPIT_TARGET_INVALID', 'AGDF_COCKPIT_UI_INVALID'].includes(error.message) ? `${error.message}\n` : 'AGDF_MCP_STARTUP_FAILED\n');
+      process.exitCode = 1;
+    }
+  }
+}

package/generated/plugins/agdf/mcp/server/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@agdf/mcp-server",
+  "version": "0.20.0",
+  "description": "Local MCP adapter for version-matched AGDF dispatch and control inspection.",
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "NOTICE"
+  ],
+  "bin": {
+    "agdf-mcp": "./bin/agdf-mcp.js"
+  },
+  "exports": {
+    ".": "./src/server.js"
+  },
+  "scripts": {
+    "test:contract": "node ./test/contract.test.js",
+    "test:continuation": "node ./test/continuation.test.js",
+    "test:protocol": "node ./test/protocol.test.js && node ./test/skill-names.test.js && node ./test/tool-errors.test.js",
+    "test:safety": "node ./test/safety.test.js && node ./test/worker-lock-release.test.js && node ./test/worker-deadline.test.js",
+    "test:cockpit-gating": "node ./test/cockpit-gating.test.js",
+    "test:provenance": "node ./test/provenance.test.js",
+    "test:performance": "node ./test/performance.test.js",
+    "test:package": "node ./test/package.test.js",
+    "test": "npm run test:contract && npm run test:continuation && npm run test:late-source-revision && npm run test:run-command-flow && npm run test:protocol && npm run test:cockpit-gating && npm run test:generation && npm run test:safety && npm run test:provenance && npm run test:performance && npm run test:package && npm run test:sdk-digest",
+    "test:sdk-digest": "node ./test/sdk-digest.test.js",
+    "test:late-source-revision": "node ./test/late-source-revision.test.js",
+    "test:run-command-flow": "node ./test/run-command.test.js && node ./test/decision-resource.test.js && node ./test/whole-flow.test.js && node ./test/structured-flow.test.js && node ./test/revision-command.test.js && node ./test/expanded-source-revision.test.js",
+    "test:generation": "node ./test/generation.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "create-agdf": "0.20.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agdf",
+    "mcp",
+    "governance",
+    "coding-agents"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArndtGold/ai-native-governance-delivery-framework.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://agdf.iself.eu"
+}

package/generated/plugins/agdf/mcp/server/src/cockpit-resource.js

@@ -0,0 +1,20 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+export function loadCockpitResource({ uri, mimeType, limit, kind = 'cockpit', directory = new URL('../ui/', import.meta.url) } = {}) {
+  try {
+    if (!['cockpit', 'decision'].includes(kind)) throw Error();
+    const manifestURL = new URL(kind === 'decision' ? 'decision-manifest.json' : 'manifest.json', directory), htmlURL = new URL(kind + '.html', directory);
+    for (const url of [directory, manifestURL, htmlURL]) if (lstatSync(url).isSymbolicLink()) throw Error();
+    const manifest = JSON.parse(readFileSync(manifestURL, 'utf8'));
+    const stat = lstatSync(htmlURL);
+    if (!stat.isFile() || !Number.isSafeInteger(limit) || stat.size > limit) throw Error();
+    const bytes = readFileSync(htmlURL);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (manifest.schema_version !== '1' || manifest.uri !== uri || manifest.mime_type !== mimeType
+      || manifest.bytes !== bytes.length || manifest.digest !== `sha256:${digest}`) throw Error();
+    const text = new TextDecoder('utf8', { fatal: true }).decode(bytes);
+    return { uri, mimeType, text, digest,
+      _meta: { ui: { csp: { connectDomains: [], resourceDomains: [], frameDomains: [], baseUriDomains: [] } } } };
+  } catch { throw new TypeError('AGDF_COCKPIT_UI_INVALID'); }
+}

package/generated/plugins/agdf/mcp/server/src/generation-entry.js

@@ -0,0 +1,86 @@
+// A directly owned private child. It never reads or writes public MCP STDIO.
+import process from 'node:process';
+import { createAgdfWorkerExecutor } from './server.js';
+import { loadCockpitResource } from './cockpit-resource.js';
+import { generationMessage, validGenerationMessage, generationManifest, generationFailureReason } from './generation-protocol.js';
+import { createMcpDispatchRuntime, createMcpDecisionRuntime, createMcpCockpitRuntime, DECISION_UI_URI,
+  inspectMcpDispatcherRuntime, releaseAbandonedOwnedLock } from 'create-agdf/mcp-dispatch-runtime';
+const epoch = process.argv[2], generation = Number(process.argv[3]);
+let runtime, executor, starting = false, closing = false, inflight = 0, serverDigest, sdkDigest, uiDigest;
+const observed = new Set(), unknown = new Set();
+function status() {
+  const owned = runtime?.inspectOwnership?.() ?? { views: 0 };
+  return { ...owned, inflight: inflight + (starting ? 1 : 0) + (owned.inflight ?? 0),
+    executor: executor?.active ? 1 : 0, uncertain: unknown.size + (owned.uncertain ?? 0), closing };
+}
+function send(input, kind, payload) {
+  const reply = generationMessage(epoch, generation, kind, payload, {}, input.original_operation_id, input.request_id);
+  if (validGenerationMessage(reply, { epoch, generation, reply: true })) process.send?.(reply);
+  else process.send?.(generationMessage(epoch, generation, 'failure', { reason: 'generation_result_limit' }, {}, input.original_operation_id, input.request_id));
+}
+process.on('message', async input => {
+  if (!validGenerationMessage(input, { epoch, generation }) || observed.has(input.request_id)) return;
+  if (observed.size >= 8192) { send(input, 'failure', { reason: 'generation_request_capacity' }); return; }
+  observed.add(input.request_id);
+  try {
+    if (input.kind === 'qualify') {
+      if (runtime || starting || closing) throw Error('generation_already_initialized');
+      starting = true;
+      const { surface, commandGroups, cockpitDir, cockpitMode } = input.payload;
+      const inspected = inspectMcpDispatcherRuntime();
+      if (inspected.provenanceStatus !== 'matched') throw Error('runtime_provenance_invalid');
+      runtime = cockpitDir || cockpitMode ? await createMcpCockpitRuntime({ surface, cockpitDir, cockpitMode, inspected })
+        : createMcpDispatchRuntime({ surface, commandGroups, inspected });
+      if (!cockpitDir && !cockpitMode && surface === 'codex') {
+        const ui = { uri: DECISION_UI_URI, mimeType: 'text/html;profile=mcp-app', limit: 4 * 1024 ** 2, kind: 'decision' };
+        ui.digest = loadCockpitResource(ui).digest;
+        runtime = await createMcpDecisionRuntime({ runtime, ui });
+      }
+      if (runtime.ui) uiDigest = loadCockpitResource(runtime.ui).digest;
+      // Inspect reports package-owned immutable identities, not caller evidence.
+      sdkDigest = inspected.generationIdentity.sdk_digest; serverDigest = inspected.generationIdentity.server_digest;
+      executor = runtime.mode === 'cockpit' ? null : createAgdfWorkerExecutor(runtime, { releaseOwnedLock: releaseAbandonedOwnedLock });
+      const support = { ui: Boolean(runtime.ui), app_mediation: runtime.mode === 'decision'
+        && runtime.trustedContext.decisionQualification(input.context.client, uiDigest) === true };
+      starting = false;
+      send(input, 'qualified', { manifest: generationManifest(runtime, uiDigest, sdkDigest),
+        producer: { server_digest: serverDigest, dispatcher_digest: inspected.generationIdentity.dispatcher_digest, sdk_digest: sdkDigest }, support });
+    } else if (input.kind === 'session_inspect') {
+      send(input, 'status', status());
+    } else if (input.kind === 'shutdown') {
+      if (closing || starting || inflight || unknown.size) throw Error('generation_work_protected');
+      closing = true;
+      await executor?.close(); await runtime?.close?.();
+      const remaining = status();
+      if (remaining.views || remaining.inflight || remaining.executor || remaining.uncertain) throw Error('generation_cleanup_unconfirmed');
+      send(input, 'closed', remaining);
+      process.disconnect(); // Natural exit, no kill, after all owned work is closed.
+    } else {
+      if (!runtime || closing) throw Error('generation_unavailable');
+      const { name, arguments: args } = input.payload, tool = runtime.tool?.(name) ?? runtime.tools.find(t => t.name === name);
+      if (!tool || tool.requiresUi && input.context.uiSupported !== true) throw Error('resource_denied');
+      ++inflight;
+      let result, phase = tool.parentOwned || !executor ? 'parse' : 'execute';
+      try {
+        if (tool.parentOwned || !executor) {
+          const parsed = tool.parse(args); phase = 'execute';
+          result = await tool.execute(parsed, undefined, input.context);
+        } else result = await executor.execute(args, { toolName: name });
+        if (runtime.postprocessToolResult) result = await runtime.postprocessToolResult(name, args, result, input.context);
+        if (input.original_operation_id && result.outcome === 'effect_unknown') unknown.add(input.original_operation_id);
+        if (name === 'agdf_inspect' && args.operation === 'operation-status' && result.report?.status === 'recorded'
+          && result.report.receipt?.operation_id === args.module) unknown.delete(args.module);
+        send(input, 'result', runtime.projectToolResult(name, args, result));
+      } catch (error) {
+        const facts = runtime.normalizeFailure(error, { phase });
+        if (input.original_operation_id && facts.dispatch !== 'not_dispatched') unknown.add(input.original_operation_id);
+        send(input, 'result', runtime.projectToolResult(name, args, runtime.failure(facts.code, name, args, facts), facts));
+      } finally { --inflight; }
+    }
+  } catch (error) { if (input.kind === 'qualify') starting = false; send(input, 'failure', { reason: generationFailureReason(error) }); }
+});
+process.on('disconnect', () => {
+  // Loss of the facade does not cancel or replay business effects. Timers and
+  // existing worker/view owners retain their bounds; no process-wide force kill.
+  if (!closing) { void executor?.close().catch(() => {}); void runtime?.close?.().catch(() => {}); }
+});

package/generated/plugins/agdf/mcp/server/src/generation-protocol.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+export const GENERATION_LIMITS = Object.freeze({ slots: 3, input: 65536, result: 1048576, qualify: 30000, close: 10000, receipts: 256, routes: 4096 });
+const uuid = value => typeof value === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/u.test(value);
+const fields = ['schema_version', 'owner_epoch', 'generation_id', 'request_id', 'kind', 'original_operation_id', 'payload', 'context'];
+export function validGenerationMessage(value, { epoch, generation, reply = false } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join() !== [...fields].sort().join()
+    || value.schema_version !== '1' || value.owner_epoch !== epoch || value.generation_id !== generation
+    || !uuid(value.request_id) || !(value.original_operation_id === null || uuid(value.original_operation_id))
+    || !Number.isSafeInteger(value.generation_id) || value.generation_id < 1
+    || !(reply ? ['qualified', 'result', 'status', 'closed', 'failure'] : ['qualify', 'invoke', 'session_inspect', 'shutdown']).includes(value.kind)
+    || !value.context || typeof value.context !== 'object' || Array.isArray(value.context)) return false;
+  try { return Buffer.byteLength(JSON.stringify(value)) <= (reply ? GENERATION_LIMITS.result : GENERATION_LIMITS.input); } catch { return false; }
+}
+export function generationMessage(epoch, generation, kind, payload, context = {}, original = null, requestId) {
+  return { schema_version: '1', owner_epoch: epoch, generation_id: generation, request_id: requestId,
+    kind, original_operation_id: original, payload, context };
+}
+export function generationManifest(runtime, uiDigest, sdkDigest) {
+  if (typeof runtime.toolErrorContract !== 'string' || !runtime.toolErrorContract
+    || typeof runtime.projectToolResult !== 'function' || typeof runtime.consumeToolResult !== 'function'
+    || typeof runtime.normalizeFailure !== 'function') throw Error('generation_manifest_incompatible');
+  // Stable transport shape, never business eligibility or a human-origin proof.
+  return { schema_version: '1', mode: runtime.mode ?? 'headless', sdk_digest: sdkDigest,
+    protocol: 'mcp-sdk/2:stdio-legacy-and-modern', tool_error_contract: runtime.toolErrorContract,
+    tools: runtime.tools.map(tool => ({ name: tool.name, definition: tool.definition })),
+    resource: runtime.ui ? { uri: runtime.ui.uri, mimeType: runtime.ui.mimeType, digest: uiDigest } : null,
+    command_groups: [...(runtime.trustedContext.commandGroups ?? [])] };
+}
+export const manifestDigest = manifest => createHash('sha256').update(JSON.stringify(manifest)).digest('hex');
+
+const FAILURE_REASONS = new Set([
+  'generation_unavailable', 'generation_input_limit', 'generation_response_unknown', 'generation_connection_lost',
+  'generation_capacity_protected', 'generation_manifest_incompatible', 'generation_result_limit',
+  'generation_request_capacity', 'generation_already_initialized', 'generation_work_protected',
+  'generation_cleanup_unconfirmed', 'resource_denied', 'runtime_provenance_invalid', 'runtime_version_mismatch',
+  'dispatch_busy', 'dispatch_cancelled', 'dispatch_timeout', 'dispatch_worker_failed', 'dispatch_worker_termination_unconfirmed',
+  'runtime_publication_unowned', 'runtime_candidate_manifest_invalid', 'runtime_candidate_unowned', 'runtime_candidate_digest_mismatch',
+  'AGDF_MCP_EXECUTABLE_CLAIM_INVALID', 'AGDF_MCP_EXECUTABLE_CLAIM_CONTENDED',
+  'AGDF_MCP_EXECUTABLE_CLAIM_LOCK_UNCONFIRMED', 'AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED',
+]);
+export function generationFailureReason(error) {
+  const reason = error?.code ?? error?.message;
+  return FAILURE_REASONS.has(reason) ? reason : 'generation_runtime_failed';
+}

package/generated/plugins/agdf/mcp/server/src/generation.js

@@ -0,0 +1,211 @@
+import { fork } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { generationMessage, validGenerationMessage, generationManifest, manifestDigest, generationFailureReason, GENERATION_LIMITS as L } from './generation-protocol.js';
+import { loadCockpitResource } from './cockpit-resource.js';
+import { DispatchExecutionError } from './worker.js';
+
+// One live facade, three directly owned children, no process registry or PID
+// discovery. Capacity includes startup and unconfirmed cleanup, not just current.
+export async function createOwnedGenerationFacade({ runtime, publisher, createControlRuntime, surface, cockpitDir, cockpitMode,
+  Fork = fork, qualifyMs = L.qualify, closeMs = L.close, invokeMs = L.qualify, onEvent = () => {} } = {}) {
+  if (![qualifyMs, closeMs, invokeMs].every(value => Number.isSafeInteger(value) && value > 0)
+    || qualifyMs > L.qualify || closeMs > L.close || invokeMs > L.qualify) throw Error('generation_deadline_invalid');
+  const epoch = randomUUID(), slots = new Map(), routes = new Map(), presentations = new Map(), operations = new Map(), receipts = new Map();
+  let current, nextGeneration = 0, replacing = false, closed = false, closing, actualContext = {}, nativeRequired = false;
+  const uiDigest = runtime.ui ? loadCockpitResource(runtime.ui).digest : undefined;
+  const expected = manifestDigest(generationManifest(runtime, uiDigest, publisher.initial.sdkDigest));
+  const event = (row, kind, reason) => onEvent({ owner_epoch: epoch, generation_id: row?.id ?? null, kind, reason: reason ?? null, occupancy: slots.size });
+  const failure = (reason, extra = {}) => ({ outcome: 'rejected', reason, authorizes: false, ...extra });
+  function status() {
+    return { available: true, owner_epoch: epoch, maximum: L.slots, occupancy: slots.size, current_generation: current?.id ?? null,
+      candidate_active: replacing, generations: [...slots.values()].map(row => ({ generation_id: row.id,
+        publication_id: row.package.publication_id, state: row.state, active_requests: row.inflight,
+        uncertain_operations: row.unknown.size, views: row.observed?.views ?? null,
+        confirmed_exit: row.exited, usable: row === current && row.state === 'current' && !row.exited })), authorizes: false };
+  }
+  function request(row, kind, payload, context = {}, original = null, timeout = qualifyMs) {
+    if (row.exited || !row.child?.connected) return Promise.reject(new DispatchExecutionError('generation_unavailable', 'not_dispatched'));
+    const id = randomUUID(), message = generationMessage(epoch, row.id, kind, payload, context, original, id);
+    if (!validGenerationMessage(message, { epoch, generation: row.id })) return Promise.reject(new DispatchExecutionError('generation_input_limit', 'not_dispatched'));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { row.pending.delete(id); reject(new DispatchExecutionError('generation_response_unknown')); }, timeout);
+      row.pending.set(id, { kind, original, resolve, reject, timer });
+      row.child.send(message, error => { if (error) { clearTimeout(timer); row.pending.delete(id); reject(new DispatchExecutionError('generation_connection_lost')); } });
+    });
+  }
+  async function observe(row) {
+    try { const reply = await request(row, 'session_inspect', {}); row.observed = reply.payload; return row.observed; }
+    catch { row.state = 'close_unconfirmed'; return null; }
+  }
+  async function retire(row, teardown = false) {
+    if (row === current || row.inflight || row.unknown.size || row.state === 'closing' || row.state === 'close_unconfirmed') return false;
+    const work = await observe(row);
+    if (!work || !teardown && work.views || work.inflight || work.executor || work.uncertain) return false;
+    row.state = 'closing'; event(row, 'orderly_close');
+    let exitTimer;
+    const ended = new Promise(resolve => {
+      if (row.exited) { resolve(false); return; }
+      row.end = resolve; exitTimer = setTimeout(() => { row.state = 'close_unconfirmed'; event(row, 'close_unconfirmed'); resolve(false); }, closeMs);
+    });
+    try { const ack = await request(row, 'shutdown', {}, {}, null, closeMs);
+      row.closeAck = ack.kind === 'closed' && !ack.payload.views && !ack.payload.inflight && !ack.payload.executor && !ack.payload.uncertain;
+    } catch { row.state = 'close_unconfirmed'; event(row, 'close_unconfirmed'); }
+    const confirmed = await ended; clearTimeout(exitTimer); return confirmed;
+  }
+  async function reserve(packageInfo, context) {
+    if (slots.size >= L.slots) {
+      const candidates = [...slots.values()].filter(row => row !== current && !row.inflight && !row.unknown.size
+        && !['starting', 'qualifying', 'closing', 'close_unconfirmed'].includes(row.state)).sort((a, b) => a.id - b.id);
+      for (const row of candidates) { if (await retire(row)) break; }
+    }
+    if (slots.size >= L.slots) throw Error('generation_capacity_protected');
+    const row = { id: ++nextGeneration, package: packageInfo, state: 'starting', pending: new Map(),
+      unknown: new Set(), inflight: 0, exited: false, closeAck: false, observed: null };
+    slots.set(row.id, row); event(row, 'reserved'); // Reservation precedes acquisition/load/spawn.
+    try {
+      const claim = publisher.acquire(packageInfo, { ownerEpoch: epoch, generation: row.id });
+      row.child = Fork(join(packageInfo.packageRoot, 'src/generation-entry.js'), [epoch, String(row.id)],
+        { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], serialization: 'json', execArgv: [] });
+      claim.bindOwnedChild(row.child, { confirmedEnd: () => row.closeAck && !row.inflight && !row.unknown.size });
+      row.child.on('message', reply => {
+        if (!validGenerationMessage(reply, { epoch, generation: row.id, reply: true })) { event(row, 'invalid_reply'); return; }
+        const pending = row.pending.get(reply.request_id);
+        if (!pending || pending.original !== reply.original_operation_id) { event(row, 'unknown_reply'); return; }
+        const expectedKind = { qualify: 'qualified', invoke: 'result', session_inspect: 'status', shutdown: 'closed' }[pending.kind];
+        if (reply.kind !== expectedKind && reply.kind !== 'failure') return;
+        clearTimeout(pending.timer); row.pending.delete(reply.request_id);
+        if (reply.kind === 'failure') pending.reject(new DispatchExecutionError(reply.payload.reason));
+        else {
+          if (reply.kind === 'closed') row.closeAck = !reply.payload.views && !reply.payload.inflight && !reply.payload.executor && !reply.payload.uncertain;
+          pending.resolve(reply);
+        }
+      });
+      row.child.once('exit', () => {
+        row.exited = true;
+        for (const pending of row.pending.values()) { clearTimeout(pending.timer); pending.reject(new DispatchExecutionError('generation_connection_lost')); }
+        row.pending.clear();
+        if (row.closeAck && !row.inflight && !row.unknown.size) { slots.delete(row.id); row.state = 'closed'; event(row, 'confirmed_exit'); row.end?.(true); }
+        else { row.state = 'close_unconfirmed'; event(row, 'unexpected_exit'); row.end?.(false); }
+      });
+      row.child.once('error', () => { row.state = 'close_unconfirmed'; event(row, 'spawn_failed'); });
+      row.state = 'qualifying'; event(row, 'qualifying');
+      const qualified = (await request(row, 'qualify', { surface, commandGroups: [...(runtime.trustedContext.commandGroups ?? [])],
+        ...(cockpitDir ? { cockpitDir } : {}), ...(cockpitMode ? { cockpitMode } : {}) }, context)).payload;
+      if (manifestDigest(qualified.manifest) !== expected || qualified.producer.server_digest !== packageInfo.digest
+        || qualified.producer.dispatcher_digest !== packageInfo.dispatcherDigest || qualified.producer.sdk_digest !== packageInfo.sdkDigest
+        || nativeRequired && !qualified.support.app_mediation) throw Error('generation_manifest_incompatible');
+      row.state = 'qualified'; event(row, 'qualified'); return row;
+    } catch (error) {
+      event(row, 'qualification_failed', generationFailureReason(error));
+      if (!row.child) { slots.delete(row.id); event(row, 'not_spawned'); }
+      else { row.state = 'draining'; await retire(row); }
+      throw error;
+    }
+  }
+  const control = {
+    status,
+    async refresh() { await Promise.all([...slots.values()].filter(row => !row.exited).map(observe)); return status(); },
+    inspect(id, input) { const record = receipts.get(id);
+      if (record && (record.input.run_id !== input.run_id || record.input.primary_target !== input.primary_target
+        || record.input.expected_revision_id !== input.expected_revision_id)) return { status: 'unknown', reason: 'connection_control_binding_invalid', authorizes: false };
+      return record ? { status: record.result ? 'recorded' : 'pending',
+      request_digest: record.digest, result: record.result, current: status(), authorizes: false }
+      : { status: 'unknown', reason: 'connection_control_record_unavailable', current: status(), authorizes: false }; },
+    async replace({ input, candidate, requestDigest, revalidate }) {
+      const prior = receipts.get(input.operation_id);
+      if (prior) return prior.digest !== requestDigest ? failure('operation_payload_conflict')
+        : prior.result ? { ...prior.result, outcome: prior.result.outcome === 'accepted' ? 'already_applied' : prior.result.outcome, historical_effect: true, current: status() }
+        : { outcome: 'effect_unknown', reason: 'generation_replacement_pending', current: status(), authorizes: false };
+      if (receipts.size >= L.receipts) return failure('connection_control_capacity');
+      if (closed || replacing) return failure(closed ? 'connection_closed' : 'generation_replacement_busy');
+      const record = { digest: requestDigest, input, result: null }; receipts.set(input.operation_id, record); replacing = true;
+      let candidateRow;
+      try {
+        revalidate(); const packageInfo = publisher.resolve(candidate);
+        candidateRow = await reserve(packageInfo, actualContext); revalidate();
+        const previous = current; current = candidateRow; current.state = 'current';
+        if (previous) previous.state = previous.exited ? 'close_unconfirmed' : 'draining';
+        event(current, 'admitted'); record.result = { outcome: 'accepted', reason: null, operation_id: input.operation_id,
+          request_digest: requestDigest, effect: { runtime_replaced: true, generation_id: current.id }, current: status(), authorizes: false };
+      } catch (error) {
+        if (candidateRow && candidateRow !== current) { candidateRow.state = 'draining'; await retire(candidateRow); }
+        record.result = failure(generationFailureReason(error), { operation_id: input.operation_id, current: status() });
+      } finally { replacing = false; }
+      record.result.current = status(); return record.result;
+    },
+  };
+  const controlRuntime = createControlRuntime(control);
+  function operationKey(input, id = input.operation_id) { return JSON.stringify([input.primary_target, input.run_id, id]); }
+  async function invoke(name, args, host = {}, signal) {
+    if (signal?.aborted) throw new DispatchExecutionError('dispatch_cancelled', 'not_dispatched');
+    if (closed) throw new DispatchExecutionError('connection_closed', 'not_dispatched');
+    actualContext = { client: host.client, uiSupported: host.uiSupported === true };
+    if (args.operation_id && name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
+      && operations.has(operationKey(args))) throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
+    if (args.operation_id && args.command?.kind !== 'runtime_generation.replace' && receipts.has(args.operation_id))
+      throw new DispatchExecutionError('operation_payload_conflict', 'not_dispatched');
+    if (name === 'agdf_record' && args.command?.kind === 'runtime_generation.replace'
+      || name === 'agdf_inspect' && args.operation === 'runtime-generations') {
+      const result = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
+      return controlRuntime.projectToolResult(name, args, name === 'agdf_inspect' && result.report?.available ? { ...result, report: await control.refresh() } : result);
+    }
+    if (name === 'agdf_inspect' && args.operation === 'operation-status' && receipts.has(args.module)) {
+      const validated = await controlRuntime.tool(name).execute(controlRuntime.tool(name).parse(args));
+      return controlRuntime.projectToolResult(name, args, validated.report?.status === 'unknown' || validated.report?.status === 'absent'
+        ? { ...validated, report: control.inspect(args.module, args) } : validated);
+    }
+    const knownSession = args.session_id && routes.get(args.session_id);
+    if (args.session_id && !knownSession) throw new DispatchExecutionError('session_expired', 'not_dispatched');
+    const id = name === 'agdf_inspect' && args.operation === 'operation-status' ? args.module : args.operation_id;
+    const key = id && operationKey(args, id), original = key && operations.get(key);
+    const presentationId = args.command?.payload?.presentation_id ?? args.presentation_id;
+    const presentationOwner = presentationId && presentations.get(operationKey(args, presentationId));
+    const row = knownSession ?? original ?? presentationOwner ?? current;
+    if (!row || row.exited) throw new DispatchExecutionError('generation_unavailable', 'not_dispatched');
+    if (args.operation_id && !original) {
+      if (operations.size >= L.routes) throw new DispatchExecutionError('generation_route_capacity', 'not_dispatched');
+      operations.set(key, row);
+    }
+    ++row.inflight; event(row, 'invoke', name);
+    try {
+      const result = (await request(row, 'invoke', { name, arguments: args }, actualContext, args.operation_id ?? null, invokeMs)).payload;
+      if (args.operation_id && result.outcome === 'effect_unknown') row.unknown.add(key);
+      if (name === 'agdf_inspect' && args.operation === 'operation-status' && result.report?.status === 'recorded'
+        && result.report.receipt?.operation_id === args.module) row.unknown.delete(key);
+      if (result.app_capability === 'available') nativeRequired = true;
+      if (result.family_result?.presentation_id && ['accepted', 'already_applied'].includes(result.outcome)) {
+        const presentationKey = operationKey(args, result.family_result.presentation_id);
+        if (!presentations.has(presentationKey) && presentations.size >= L.routes) throw Error('generation_route_capacity');
+        presentations.set(presentationKey, row);
+      }
+      for (const meta of [result._meta?.agdf_decision, result._meta?.agdf_cockpit]) {
+        for (const selector of [meta?.session_id, meta?.read_session_id]) {
+          if (selector) { if (routes.size >= L.routes) throw Error('generation_route_capacity'); routes.set(selector, row); }
+        }
+      }
+      return result;
+    } catch (error) { if (args.operation_id && error.dispatch !== 'not_dispatched') row.unknown.add(key); throw error; }
+    finally { --row.inflight; if (closed && !row.inflight && !row.unknown.size) void retire(row, true); }
+  }
+  current = await reserve(publisher.initial, {}); current.state = 'current'; event(current, 'admitted');
+  // Validate the public request here, but transport that exact public shape.
+  // Core parse results contain trusted runtime context and are executable inputs,
+  // not wire requests; parsing them again in a child both breaks the contract
+  // and copies the entire locale registry into a bounded private message.
+  const tools = runtime.tools.map(tool => ({ ...tool, parentOwned: true,
+    parse: input => { tool.parse(input); return input; }, execute: input => invoke(tool.name, input) }));
+  // The server supplies actual initialize/request context only at this seam.
+  for (const tool of tools) tool.execute = (input, signal, host) => invoke(tool.name, input, host, signal);
+  return Object.freeze({ ...runtime, tools, tool: name => tools.find(tool => tool.name === name),
+    requiresProjectedResult: true, postprocessToolResult: undefined, inspectOwnership: status, runtimeControl: control,
+    close() {
+      return closing ??= (async () => {
+        closed = true;
+        const previous = current; current = null; if (previous && !previous.exited) previous.state = 'draining';
+        await Promise.allSettled([...slots.values()].map(row => retire(row, true)));
+        return status();
+      })();
+    },
+  });
+}