@agdf/mcp-server 0.20.2 → 0.31.0

package/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/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/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/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,
+  });
+}