create-agdf 0.20.2 → 0.31.0

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

@@ -1,23 +1,53 @@
+import { createPreparedCallTransport, preparedTransportSchema } from './prepared-call-transport.js';
+import { appendSafeReadContinuation, nextActionOutputSchema } from './safe-read-continuation.js';
+import { createNextActionProjection } from './next-action.js';
+import { boundStdioOutput } from './stdio-output.js';
 import { McpServer, ProtocolError, ProtocolErrorCode, fromJsonSchema } from "@modelcontextprotocol/server";
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { DispatchExecutionError, createWorkerDispatchExecutor } from "./worker.js";
+import { DispatchExecutionError } from "./worker.js";
 import { loadCockpitResource } from './cockpit-resource.js';
 import { requestDeclaresMcpAppUi, requestMcpClientInfo, requestMcpClientCapabilities, requiresMcpAppUi,
   missingMcpAppUi, capabilityTransport, modernToolUiDenial } from "./ui-capability.js";
 
 export const SERVER_NAME = "agdf-mcp";
 
-function toolResult(runtime, name, input, result, serialize = runtime.serialize, provider, peer, facts) {
+// A folded follow-up read is a convenience. Hosts move large tool output into
+// files (Claude Code from roughly 80 KB of text), which costs the model more
+// round trips than a separate read, so a read is inlined only below this size.
+const INLINE_READ_TEXT_BYTES = 48 * 1024;
+const byteLength = value => Buffer.byteLength(typeof value === 'string' ? value : JSON.stringify(value), 'utf8');
+
+function omittedFollowup(nextRead) {
+  return { ...nextRead, result: null, failure: {
+    code: 'read_followup_output_limit', phase: 'wire_budget', original_effect_unchanged: true,
+    instruction: 'The original result and receipt are unchanged. Its follow-up read was not inlined to keep this response small; run only that supplied read call separately.',
+  } };
+}
+
+function toolResult(runtime, name, input, result, { serialize = runtime.serialize, consume = runtime.consumeToolResult,
+  provider, peer, facts, preparedCalls, actions, nextRead } = {}) {
   // A generation must supply its own descriptor. Never reinterpret old results
   // with the facade's current runtime. Local owners project after postprocessing.
-  const emit = value => {
+  const emit = (value, { followup, decorate = true } = {}) => {
     const projected = Object.hasOwn(value._meta ?? {}, 'agdf/tool-result') || runtime.requiresProjectedResult ? value
       : runtime.projectToolResult(name, input, value, facts);
-    const { domain, metadata, descriptor } = runtime.consumeToolResult(name, projected);
-    const text = serialize(domain);
+    const { domain, metadata, descriptor } = consume(name, projected);
+    // Validate and bound the canonical domain with its existing owner first.
+    // Additive MCP navigation has its own explicit wire projection; it is not
+    // passed back into a closed Core result serializer as canonical state.
+    const canonical = JSON.parse(serialize(domain));
+    const navigable = followup ? { ...canonical, next_read: followup } : canonical;
+    const decorated = decorate && preparedCalls ? preparedCalls.decorate(navigable) : navigable;
+    if (decorated.next_read?.result?.report?.material_transport?.instructions) {
+      const transport = decorated.next_read.result.report.material_transport;
+      transport.instructions = transport.instructions.replaceAll('response.structuredContent.report',
+        'response.structuredContent.next_read.result.report').replaceAll('JSON.parse(response.content[0].text).report',
+        'JSON.parse(response.content[0].text).next_read.result.report');
+    }
+    const text = JSON.stringify(actions ? actions.project(decorated) : decorated);
     const response = {
       content: [{ type: 'text', text: domain.presentation_delivery?.text ?? text },
         ...(descriptor.failed ? [{ type: 'text', text: descriptor.message }] : [])],
@@ -28,18 +58,29 @@ function toolResult(runtime, name, input, result, serialize = runtime.serialize,
     };
     return response;
   };
-  let response = emit(result);
-  if (runtime.responseLimit && Buffer.byteLength(JSON.stringify(response), 'utf8') > runtime.responseLimit) {
-    // The fallback itself is projected, checked and measured; no recursive call.
-    const limitFacts = { code: 'resource_limit', dispatch: 'unknown' };
-    const failure = runtime.projectToolResult(name, input, runtime.failure('resource_limit', name, input, limitFacts), limitFacts);
-    response = emit(failure);
-    if (Buffer.byteLength(JSON.stringify(response), 'utf8') > runtime.responseLimit) throw Error('tool_result_invalid');
+  const withinLimit = response => !runtime.responseLimit || byteLength(response) <= runtime.responseLimit;
+  // Optional additions are dropped before the result itself is touched: first the
+  // inlined read, then the transport decoration (whose recovery copies can double
+  // large forms). Only a canonical result that alone exceeds the limit becomes
+  // resource_limit, so navigation can never turn a committed write into unknown.
+  const variants = [
+    ...(nextRead?.result ? [{ followup: nextRead, inlineRead: true }] : []),
+    ...(nextRead ? [{ followup: nextRead.result ? omittedFollowup(nextRead) : nextRead }] : []),
+    {}, { decorate: false },
+  ];
+  for (const { inlineRead, ...variant } of variants) {
+    const response = emit(result, variant);
+    if (withinLimit(response) && (!inlineRead || byteLength(response.content[0].text) <= INLINE_READ_TEXT_BYTES)) return response;
   }
+  // The fallback itself is projected, checked and measured; no recursive call.
+  const limitFacts = { code: 'resource_limit', dispatch: 'unknown' };
+  const failure = runtime.projectToolResult(name, input, runtime.failure('resource_limit', name, input, limitFacts), limitFacts);
+  const response = emit(failure);
+  if (!withinLimit(response)) throw Error('tool_result_invalid');
   return response;
 }
 
-export function buildAgdfServer({ runtime, executor, era } = {}) {
+export function buildAgdfServer({ runtime, executor, era, preparedCallStore } = {}) {
   if (!runtime?.definition || typeof runtime.serialize !== "function") {
     throw new TypeError("AGDF MCP runtime is required");
   }
@@ -47,6 +88,15 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
     throw new TypeError("AGDF MCP owned runtime is required");
   }
   const tools = runtime.tools ?? [{ name: runtime.definition.name, definition: runtime.definition, parse: runtime.parse, execute: runtime.execute }];
+  // Discovery and retained reads share the original SDK validators. Compile
+  // lazily; constructing the transport never validates or executes a request.
+  const schemaProvider = new AjvJsonSchemaValidator();
+  const deferredSchemas = { getValidator(schema) {
+    let validate;
+    return value => (validate ??= schemaProvider.getValidator(schema))(value);
+  } };
+  const inspectTool = tools.find(tool => tool.name === 'agdf_inspect');
+  const validateInspect = inspectTool && deferredSchemas.getValidator(inspectTool.definition.inputSchema);
   const dispatchExecutor = executor ?? {
     execute: async (argumentsValue, { toolName, signal } = {}) => {
       const tool = tools.find((entry) => entry.name === (toolName ?? runtime.definition.name));
@@ -58,7 +108,14 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
     },
     close: async () => runtime.close?.(),
   };
-  const registrations = new Map();
+  const registrations = new Map(), preparedCalls = createPreparedCallTransport({
+    store: preparedCallStore,
+    // A read reference retains a supplied canonical request, never an inferred
+    // target. Validate the unwrapped arguments with the original SDK schema.
+    validateRead: call => inspectTool?.definition.annotations?.readOnlyHint === true
+      && validateInspect(call.arguments).valid,
+  }),
+    actions = createNextActionProjection({ isAvailable: call => preparedCalls.isAvailable(call) });
   class AgdfServer extends McpServer {
     async connect(transport) {
       return super.connect(capabilityTransport(transport, message => modernToolUiDenial(message,
@@ -67,7 +124,8 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
   }
   const server = new AgdfServer(
     { name: SERVER_NAME, version: runtime.trustedContext.expectedVersion },
-    { capabilities: { tools: {}, ...(runtime.ui ? { resources: {} } : {}) } },
+    { capabilities: { tools: {}, ...(runtime.ui ? { resources: {} } : {}) },
+      instructions: 'Use the returned next_action.call as the normal path for reads and writes. Fill only its named inputs from actual authored content, review or a new deliberate reply; ready calls retain inputs:{} and are forwarded unchanged. The adapter retains the exact target, Run, revision, selectors and original operation identity. Do not reconstruct raw reads or status requests, retype references or use cloning helpers. Owned plugin references retain their original lifetime across reconnects at the same runtime; other connections use explicit recovery_only instructions and the saved original request. A safe inspect may already be included as next_read.result; consume it without repeating it. next_read.tool/arguments describe that executed read; next_read.call is its supplied retry only. A terminal action stops work. No reference or continuation grants authority or approval.' },
   );
   // Capability checks guard execution and resource access. Codex must first
   // discover the plugin tool metadata before selecting its UI-capable route.
@@ -80,32 +138,76 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
     connection_id: randomUUID(), server_module: fileURLToPath(import.meta.url),
     version: runtime.trustedContext.expectedVersion,
   }) : undefined;
-  const respond = (name, input, result, serialize, context, facts) => toolResult(runtime, name, input, result, serialize, provider, provider ? {
-    client_info: requestMcpClientInfo(server.server, context), capabilities: requestMcpClientCapabilities(server.server, context),
-  } : undefined, facts);
+  // The handler validates a result before choosing its follow-up read; the
+  // response variants then reuse that validation instead of repeating it.
+  const consumed = new WeakMap();
+  const consume = (name, value) => {
+    if (!consumed.has(value)) consumed.set(value, runtime.consumeToolResult(name, value));
+    return consumed.get(value);
+  };
+  const respond = (name, input, result, serialize, context, facts, nextRead) => toolResult(runtime, name, input, result, {
+    serialize, consume, provider, facts, preparedCalls, actions, nextRead, peer: provider ? {
+      client_info: requestMcpClientInfo(server.server, context), capabilities: requestMcpClientCapabilities(server.server, context),
+    } : undefined });
+  // Companion events (SD SDD-006): only the process that executed a call journals its final result.
+  // Behind the generation facade (projected results) the generation has journaled every result it
+  // produced; a failure thrown here (lost connection, unknown response, unavailable generation,
+  // expired session) never reached a generation result, so the facade journals it itself.
+  const journaling = () => !runtime.requiresProjectedResult && typeof runtime.observeOutcome === 'function';
+  const journalingFailures = () => typeof runtime.observeOutcome === 'function';
+  const journal = (name, input, projected) => {
+    try { runtime.observeOutcome(name, input, projected); } catch { /* notification only */ }
+  };
   const uiAllowed = (context) => !gated || requestDeclaresMcpAppUi(server.server, context, runtime.ui.mimeType);
   const supportsUi = context => !!runtime.ui && requestDeclaresMcpAppUi(server.server, context, runtime.ui.mimeType);
-  // Discovery needs the exact schemas, but does not execute any tool. Compile
-  // each validator on its first validation, using the same SDK provider/options.
-  // Input validation still precedes execution; successful output is still checked.
-  const schemaProvider = new AjvJsonSchemaValidator();
-  const deferredSchemas = { getValidator(schema) {
-    let validate;
-    return value => (validate ??= schemaProvider.getValidator(schema))(value);
-  } };
+  const nextRead = async (result, context) => appendSafeReadContinuation(result, {
+    allowed: !context.signal?.aborted && !!inspectTool && inspectTool.definition.annotations?.readOnlyHint === true
+      && uiAllowed(context) && (!inspectTool.requiresUi || supportsUi(context)),
+    validate: call => ['working_directory', 'presentation_language', 'primary_target', 'target_source']
+      .every(key => typeof call.arguments[key] === 'string' && call.arguments[key].length)
+      && validateInspect(call.arguments).valid,
+    execute: async call => {
+      const name = call.tool;
+      const input = runtime.prepareInput?.(name, call.arguments) ?? call.arguments;
+      const parentOwned = typeof inspectTool.parentOwned === 'function' ? inspectTool.parentOwned(input) : inspectTool.parentOwned;
+      let observed = parentOwned
+        ? await inspectTool.execute(inspectTool.parse(input), context.signal,
+          { client: requestMcpClientInfo(server.server, context), uiSupported: supportsUi(context) })
+        : await dispatchExecutor.execute(input, { signal: context.signal, toolName: name,
+          trusted: runtime.prepareDispatch?.(name, input) });
+      if (runtime.postprocessToolResult) observed = await runtime.postprocessToolResult(name, input, observed,
+        { uiSupported: supportsUi(context), client: requestMcpClientInfo(server.server, context) });
+      const projected = runtime.projectToolResult(name, input, observed);
+      const { domain } = runtime.consumeToolResult(name, projected);
+      return JSON.parse((inspectTool.serialize ?? runtime.serialize)(domain));
+    },
+  });
   for (const tool of tools) {
     const { name, definition, serialize } = tool;
-    const schema = fromJsonSchema(definition.inputSchema, deferredSchemas);
+    const schema = fromJsonSchema(preparedTransportSchema(name, definition.inputSchema), { getValidator(inputSchema) {
+      const validate = deferredSchemas.getValidator(inputSchema);
+      return input => {
+        const checked = validate(input);
+        if (checked.valid) return checked;
+        const preparedHint = preparedCalls.validationHint(name, input);
+        // Validation has already failed. The exact transport correction is more
+        // useful here than every unrelated alternative in the raw-command union.
+        if (preparedHint) return { ...checked, errorMessage: preparedHint };
+        const hint = runtime.inputValidationHint?.(name, input);
+        return hint ? { ...checked, errorMessage: `${hint} Schema: ${checked.errorMessage}` } : checked;
+      };
+    } });
     const registered = server.registerTool(
       name,
       {
         description: definition.description,
         annotations: definition.annotations,
         inputSchema: schema,
-        ...(definition.outputSchema ? { outputSchema: fromJsonSchema(definition.outputSchema, deferredSchemas) } : {}),
+        ...(definition.outputSchema ? { outputSchema: fromJsonSchema(nextActionOutputSchema(name, definition.outputSchema), deferredSchemas) } : {}),
         ...(definition._meta ? { _meta: definition._meta } : {}),
       },
       async (argumentsValue, context) => {
+        const started = performance.now();
         const denied = !uiAllowed(context) ? runtime.unsupportedUiCode ?? 'resource_denied'
           : tool.requiresUi && !supportsUi(context) ? 'host_ui_unsupported' : null;
         if (denied) {
@@ -113,23 +215,40 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
           const failure = runtime.projectToolResult(name, argumentsValue, runtime.failure(denied, name, argumentsValue, facts), facts);
           return respond(name, argumentsValue, failure, serialize ?? runtime.serialize, context, facts);
         }
-        let phase = tool.parentOwned ? 'parse' : 'execute';
+        let parentOwned;
+        let phase = 'parse';
         try {
+          phase = 'parse';
+          argumentsValue = preparedCalls.resolve(name, argumentsValue);
+          parentOwned = typeof tool.parentOwned === 'function' ? tool.parentOwned(argumentsValue) : tool.parentOwned;
+          argumentsValue = runtime.prepareInput?.(name, argumentsValue) ?? argumentsValue;
+          phase = parentOwned ? 'parse' : 'execute';
           let result;
-          if (tool.parentOwned) {
+          if (parentOwned) {
             const parsed = tool.parse(argumentsValue); phase = 'execute';
             result = await tool.execute(parsed, context.signal,
               { client: requestMcpClientInfo(server.server, context), uiSupported: supportsUi(context) });
-          } else result = await dispatchExecutor.execute(argumentsValue, { signal: context.signal, toolName: name });
+          } else result = await dispatchExecutor.execute(argumentsValue, { signal: context.signal, toolName: name,
+            trusted: runtime.prepareDispatch?.(name, argumentsValue) });
           if (runtime.postprocessToolResult) result = await runtime.postprocessToolResult(name, argumentsValue, result,
             { uiSupported: supportsUi(context), client: requestMcpClientInfo(server.server, context) });
-          return respond(name, argumentsValue, result, serialize ?? runtime.serialize, context);
+          // Validate the producer and its canonical domain before consuming any
+          // supplied continuation. Malformed output must not start another read.
+          const checked = Object.hasOwn(result._meta ?? {}, 'agdf/tool-result') || runtime.requiresProjectedResult ? result
+            : runtime.projectToolResult(name, argumentsValue, result);
+          const { domain } = consume(name, checked);
+          if (journaling()) journal(name, argumentsValue, checked);
+          const continued = await nextRead(domain, context);
+          return respond(name, argumentsValue, checked, serialize ?? runtime.serialize, context, undefined, continued.next_read);
         } catch (error) {
           const facts = runtime.normalizeFailure(error, { phase });
-          const failure = runtime.failure(facts.code, name, argumentsValue, facts);
+          const help = phase === 'parse' ? preparedCalls.validationHint(name, argumentsValue) : '';
+          const failure = { ...runtime.failure(facts.code, name, argumentsValue, { ...facts, elapsed_ms: performance.now() - started }),
+            ...(help ? { prepared_call_help: help } : {}) };
           // A local execution/delivery failure is owned here, including malformed
           // producer output. It never causes re-execution or a second write.
           const projected = runtime.projectToolResult(name, argumentsValue, failure, facts);
+          if (journalingFailures()) journal(name, argumentsValue, projected);
           return respond(name, argumentsValue, projected, serialize ?? runtime.serialize, context, facts);
         }
       },
@@ -151,7 +270,7 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
       const listedTools = tools.map(({ name, definition }) => ({
         name, description: definition.description, inputSchema: server.toolInputSchemaJson(name),
         annotations: definition.annotations, ...(definition._meta ? { _meta: definition._meta } : {}),
-        ...(definition.outputSchema ? { outputSchema: definition.outputSchema } : {}),
+        ...(definition.outputSchema ? { outputSchema: nextActionOutputSchema(name, definition.outputSchema) } : {}),
       }));
       const listedResource = { uri: resource.uri, name: runtime.ui.label ?? 'AGDF Cockpit', mimeType: resource.mimeType, _meta: resource._meta };
       server.server.removeRequestHandler("tools/list");
@@ -162,18 +281,19 @@ export function buildAgdfServer({ runtime, executor, era } = {}) {
     }
   }
   return Object.assign(server, {
-    closeAgdfRuntime: async () => { await dispatchExecutor.close(); return runtime.close?.(); },
+    closeAgdfRuntime: async () => { preparedCalls.close(); actions.close(); await dispatchExecutor.close(); return runtime.close?.(); },
   });
 }
 
-export function serveAgdfStdio({ runtime, executor, onerror } = {}) {
+export function serveAgdfStdio({ runtime, executor, onerror, preparedCallStore } = {}) {
   const instances = new Set();
   const handle = serveStdio(({ era }) => {
-    const server = buildAgdfServer({ runtime, executor, era });
+    const server = buildAgdfServer({ runtime, executor, era, preparedCallStore });
     instances.add(server);
     return server;
   }, {
     legacy: "serve",
+    transport: boundStdioOutput(new StdioServerTransport()),
     onerror: () => onerror?.("AGDF_MCP_TRANSPORT_ERROR"),
   });
   return Object.freeze({
@@ -190,11 +310,4 @@ export function serveAgdfStdio({ runtime, executor, onerror } = {}) {
   });
 }
 
-export function createAgdfWorkerExecutor(runtime, options = {}) {
-  return createWorkerDispatchExecutor({
-    surface: runtime.trustedContext.surface,
-    expectedVersion: runtime.trustedContext.expectedVersion,
-    commandGroups: runtime.trustedContext.commandGroups,
-    ...options,
-  });
-}
+export { createAgdfWorkerExecutor } from './worker.js';

package/generated/plugins/copilot/agdf/mcp/server/src/stdio-output.js

@@ -0,0 +1,42 @@
+import { OWNER_LIMITS } from './generation-protocol.js';
+
+// One entry-owned SDK wire, one active write. Concurrent SDK responses must not
+// attach one drain/error listener per result to a blocked native Worker stream.
+// Capture exact JSON at admission. Existing result/resource owners bound the
+// one active message; the additional queue has its own strict byte/frame cap.
+// A legal large UI response must still work without lowering its resource cap.
+export function boundStdioOutput(transport) {
+  const originalSend = transport.send.bind(transport), originalClose = transport.close.bind(transport);
+  const queue = [];
+  let active, queuedBytes = 0, closed = false, closing;
+  const capacityError = () => Error('AGDF_MCP_STDIO_CAPACITY');
+  function pump() {
+    if (active || closed || !queue.length) return;
+    const entry = active = queue.shift(); queuedBytes -= entry.bytes;
+    Promise.resolve().then(() => originalSend(entry.message)).then(entry.resolve, entry.reject).finally(() => {
+      active = undefined; pump();
+    });
+  }
+  transport.send = message => {
+    if (closed) return Promise.reject(Error('AGDF_MCP_STDIO_CLOSED'));
+    let snapshot, size;
+    try {
+      const json = JSON.stringify(message); size = Buffer.byteLength(json) + 1;
+      if (queue.length + (active ? 1 : 0) >= OWNER_LIMITS.frames || active && queuedBytes + size > OWNER_LIMITS.bytes) return Promise.reject(capacityError());
+      snapshot = JSON.parse(json); // Preserve SDK JSON semantics and call-time bytes.
+    } catch (error) { return Promise.reject(error); }
+    return new Promise((resolve, reject) => {
+      queuedBytes += size; queue.push({ message: snapshot, bytes: size, resolve, reject }); pump();
+    });
+  };
+  transport.close = () => {
+    if (closing) return closing;
+    closed = true;
+    for (const entry of queue.splice(0)) { queuedBytes -= entry.bytes; entry.reject(Error('AGDF_MCP_STDIO_CLOSED')); }
+    // Close does not prove that an active write drained. Its SDK promise stays
+    // observed; genuine Worker exit is still required by the lifecycle owner.
+    active?.reject(Error('AGDF_MCP_STDIO_CLOSED'));
+    closing = Promise.resolve().then(originalClose); return closing;
+  };
+  return transport;
+}

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

@@ -1,6 +1,6 @@
 import { subscribe } from "node:diagnostics_channel";
 import { parentPort, workerData } from "node:worker_threads";
-import { OWNED_LOCK_CHANNEL, createMcpDispatchRuntime } from "create-agdf/mcp-dispatch-runtime";
+import { OWNED_LOCK_CHANNEL, createMcpDispatchRuntime } from "#agdf-dispatch-worker";
 import { ownedLockForwarder } from "./worker.js";
 
 function send(message) {
@@ -14,7 +14,7 @@ subscribe(OWNED_LOCK_CHANNEL, ownedLockForwarder(send));
 let runtime, phase = 'setup';
 try {
   send({ type: 'phase', phase: 'runtime_provenance' });
-  runtime = createMcpDispatchRuntime({ surface: workerData.surface, ...(workerData.commandGroups !== undefined ? { commandGroups: workerData.commandGroups } : {}) });
+  runtime = createMcpDispatchRuntime({ surface: workerData.surface, materialGrants: workerData.materialGrants, inputContext: workerData.inputContext, ...(workerData.commandGroups !== undefined ? { commandGroups: workerData.commandGroups } : {}) });
   if (runtime.trustedContext.provenanceStatus !== "matched") {
     send({ type: "failure", code: "runtime_provenance_invalid", dispatch: "not_dispatched" });
   } else if (runtime.trustedContext.expectedVersion !== workerData.expectedVersion) {

package/generated/plugins/copilot/agdf/mcp/server/src/worker.js

@@ -30,21 +30,30 @@ export function createWorkerDispatchExecutor({
   // Reserve up to one second instead of beginning shutdown at the deadline.
   const terminationReserveMs = Math.min(1_000, Math.max(1, Math.floor(timeoutMs / 4)));
   let active = null;
+  let closed = false;
+  const waiting = [];
+  const rejectWaiting = error => { for (const job of waiting.splice(0)) { job.cleanup(); job.reject(error); } };
+  const drain = () => {
+    if (active || closed || !waiting.length) return;
+    const job = waiting.shift(); job.cleanup();
+    execute(job.argumentsValue, { ...job.options, deadline: job.deadline }).then(job.resolve, job.reject).finally(drain);
+  };
   const event = (phase, started) => {
     try { onEvent({ phase, elapsed_ms: performance.now() - started }); } catch {}
   };
-  return Object.freeze({
-    async execute(argumentsValue, { signal, toolName } = {}) {
+  const execute = async (argumentsValue, { signal, toolName, trusted, deadline: queuedDeadline } = {}) => {
       if (active) throw new DispatchExecutionError("dispatch_busy", 'not_dispatched');
       if (signal?.aborted) throw new DispatchExecutionError("dispatch_cancelled", 'not_dispatched');
       return new Promise((resolve, reject) => {
         let settled = false, exited = false, completion, workerPhase = 'worker_start';
         let confirmExit;
         const actualExit = new Promise(resolve => { confirmExit = resolve; });
-        const started = performance.now(), deadline = started + timeoutMs;
+        const started = performance.now(), deadline = queuedDeadline ?? started + timeoutMs;
+        const budget = deadline - started;
+        if (budget <= 0) { reject(new DispatchExecutionError('dispatch_timeout', 'not_dispatched')); return; }
         let worker;
         try { worker = new WorkerClass(WORKER_URL, {
-          workerData: { surface, expectedVersion, commandGroups, argumentsValue, toolName: toolName ?? null },
+          workerData: { surface, expectedVersion, commandGroups, argumentsValue, toolName: toolName ?? null, materialGrants: trusted?.materialGrants, inputContext: trusted?.inputContext },
         }); } catch { reject(new DispatchExecutionError('dispatch_worker_failed', 'not_dispatched')); return; }
         event('worker_start', started);
         const current = { worker, timer: null, cleanupSignal: null, cancel: () => finish(reject, new DispatchExecutionError("dispatch_cancelled")) };
@@ -62,7 +71,7 @@ export function createWorkerDispatchExecutor({
           try { onEvent({ phase: 'locks_released', elapsed_ms: performance.now() - started, count: released }); } catch {}
         };
         // Called only after actual exit or confirmed termination: the thread no longer runs.
-        const release = () => { releaseHeldLocks(); if (active === current) active = null; };
+        const release = () => { releaseHeldLocks(); if (active === current) { active = null; queueMicrotask(drain); } };
         const finish = (callback, value) => {
           if (settled) return completion;
           settled = true;
@@ -87,6 +96,8 @@ export function createWorkerDispatchExecutor({
             } else {
               // A late actual exit may release capacity; rejection alone never proves termination.
               event('termination_unconfirmed', started);
+              current.unconfirmed = true;
+              rejectWaiting(new DispatchExecutionError('dispatch_busy', 'not_dispatched'));
               reject(new DispatchExecutionError('dispatch_worker_termination_unconfirmed', 'unknown', undefined, {
                 ...(callback === reject && value instanceof DispatchExecutionError ? { cause_code: value.code } : {}),
                 worker_phase: workerPhase,
@@ -100,7 +111,8 @@ export function createWorkerDispatchExecutor({
           current.cleanupSignal = () => signal.removeEventListener("abort", cancel);
           signal.addEventListener("abort", cancel, { once: true });
         }
-        current.timer = setTimeout(() => finish(reject, new DispatchExecutionError("dispatch_timeout")), timeoutMs - terminationReserveMs);
+        current.timer = setTimeout(() => finish(reject, new DispatchExecutionError("dispatch_timeout")),
+          budget - Math.min(terminationReserveMs, Math.max(1, Math.floor(budget / 4))));
         worker.on("message", message => {
           // Lock messages also arrive after settlement while the worker drains.
           if (message?.type === 'lock') {
@@ -127,8 +139,42 @@ export function createWorkerDispatchExecutor({
         // Cover an abort racing listener installation.
         if (signal?.aborted) cancel();
       });
+    };
+  return Object.freeze({
+    execute(argumentsValue, options = {}) {
+      if (closed) return Promise.reject(new DispatchExecutionError(active ? 'dispatch_busy' : 'dispatch_cancelled', 'not_dispatched'));
+      if (options.signal?.aborted) return Promise.reject(new DispatchExecutionError('dispatch_cancelled', 'not_dispatched'));
+      const deadline = performance.now() + timeoutMs;
+      if (!active && !waiting.length) return execute(argumentsValue, { ...options, deadline });
+      // Only immutable Inspect requests wait. Commands still report contention;
+      // no write is replayed, parallelized or admitted after unknown termination.
+      if (options.toolName !== 'agdf_inspect' || active?.unconfirmed)
+        return Promise.reject(new DispatchExecutionError('dispatch_busy', 'not_dispatched'));
+      if (waiting.length >= 8) return Promise.reject(new DispatchExecutionError('resource_limit', 'not_dispatched'));
+      return new Promise((resolve, reject) => {
+        const job = { argumentsValue, options, deadline, resolve, reject };
+        const remove = error => {
+          const index = waiting.indexOf(job);
+          if (index < 0) return;
+          waiting.splice(index, 1); job.cleanup(); reject(error);
+        };
+        const abort = () => remove(new DispatchExecutionError('dispatch_cancelled', 'not_dispatched'));
+        const timer = setTimeout(() => remove(new DispatchExecutionError('dispatch_timeout', 'not_dispatched')), timeoutMs);
+        job.cleanup = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', abort); };
+        waiting.push(job); options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted) abort();
+      });
     },
-    async close() { await active?.cancel(); },
+    async close() { closed = true; rejectWaiting(new DispatchExecutionError('dispatch_cancelled', 'not_dispatched')); await active?.cancel(); },
     get active() { return Boolean(active); },
   });
 }
+
+export function createAgdfWorkerExecutor(runtime, options = {}) {
+  return createWorkerDispatchExecutor({
+    surface: runtime.trustedContext.surface,
+    expectedVersion: runtime.trustedContext.expectedVersion,
+    commandGroups: runtime.trustedContext.commandGroups,
+    ...options,
+  });
+}

package/generated/plugins/copilot/agdf/meta/agdf-agent-router.md

@@ -109,7 +109,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 | `clean-implementation-review` | evidence dimension: inspect whether the solution is structurally clean | supports Quality Readiness; not a TP or QA substitute |
 | `code-review` | evidence dimension: review the actual diff for defects, regression and security findings | supports Quality Readiness; does not replace QA |
 | `delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
-| `ur-definition` | bound UR drafting, clarification or revision | content only; preserves approved intent |
+| `ur-definition` | UR drafting in planning scope or a bound Run | content only; no start or approval authority |
 | `prd-definition` | bound PRD drafting, clarification or revision | content only; preserves approved intent |
 | `sd-definition` | bound SD content | content only; preserves approved intent |
 | `tp-definition` | bound TP content | content only; preserves approved sources |
@@ -120,7 +120,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 <!-- AGDF-SKILL-ROUTING:END -->
 
 For named operations, use the catalog owner in `contracts/request-activation.md`; active-run
-inventory uses `control.doctor` with all-active inspection.
+inventory uses `control.inventory`.
 For skill or delivery routes, select exactly one primary skill first.
 Add more only when they cover a distinct concrete risk dimension.
 Do not choose `brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
@@ -148,7 +148,7 @@ When the target repository uses the AGDF control scaffold, keep live control fil
 Use templates as starting points only.
 
 Do not let chat history become the source of truth for gate state, approvals, evidence, backlog status or durable Brownfield knowledge.
-After editing a run or its listed artefacts, record the revision with the dispatch validator's `run-update` before `gate-check`; record an exact gate reply only with `run-approve`, never by editing Approvals.
+Stage current reviewed material and record it through the inspected typed owner; never edit a bound document or Run and reseal it. Current control, approvals and document references derive from canonical typed records. Only a fresh deliberate reply to the frozen presentation records an approval.
 
 AGDF is agent-native first and CLI-verifiable by design: read the live control state, apply the active skill and make the next allowed step explicit.
 Use `init` only when durable control state is explicitly requested, the repository already uses `.agdf/control/` as its live AGDF working state, or a deterministic CLI/CI setup path is being executed.

package/generated/plugins/copilot/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,12 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.20.2",
+  "version": "0.31.0",
+  "planning": {
+    "schema": "planned-ur-v1",
+    "protocol_version": 1,
+    "authoring_owner": "ur-definition"
+  },
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Control layer for governed AI-assisted delivery.",
@@ -440,8 +445,8 @@
         "ur-definition"
       ],
       "discovery": "automatic",
-      "useFor": "bound UR drafting, clarification or revision",
-      "boundary": "content only; preserves approved intent",
+      "useFor": "UR drafting in planning scope or a bound Run",
+      "boundary": "content only; no start or approval authority",
       "dispatch": {
         "mode": "judgement_required",
         "requiresControlSnapshot": true

package/generated/plugins/copilot/agdf/meta/distribution-profile-history.json

@@ -148,6 +148,20 @@
       "profile_id": "runtime-plugin",
       "entry_digest": "1b194df6abf5de884b4d69ab38cde567b5c28674f392ef853678800e05de7e65",
       "status": "supported"
+    },
+    "0.30.0": {
+      "contract_id": "five-profile-v1",
+      "provenance_schema_version": 1,
+      "profile_id": "runtime-plugin",
+      "entry_digest": "05a4645b92ab7f33c40ae676f7e92c95f618b86e3fc031684cfbac8bf6b21ce6",
+      "status": "supported"
+    },
+    "0.31.0": {
+      "contract_id": "five-profile-v1",
+      "provenance_schema_version": 1,
+      "profile_id": "runtime-plugin",
+      "entry_digest": "d3a3b0a1fc9e3312cb8a9437a4acf8ba99a563b2dab665b38feec8e2257e4f23",
+      "status": "supported"
     }
   }
 }

package/generated/plugins/copilot/agdf/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agdf",
-  "version": "0.20.2",
+  "version": "0.31.0",
   "description": "Control layer for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",