impel-cli 0.20.1 → 0.20.2-beta.0

package/src/nativeAgentTransport.js

@@ -0,0 +1,1962 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  CONFIG_DIR,
+  normalizeGatewayUrl,
+  redactCredentialText,
+  redactSecretText,
+} from "./config.js";
+import {
+  NATIVE_AGENT_LIST_TOOL,
+  NATIVE_AGENT_READ_TOOL,
+  NATIVE_AGENT_RECOVER_TOOL,
+  NATIVE_AGENT_RESUME_TOOL,
+  NATIVE_AGENT_RUN_TOOL,
+  NATIVE_AGENT_START_TOOL,
+  nativeAgentPolicyFingerprint,
+  normalizeNativeAgentCatalog,
+} from "./agents.js";
+import { normalizeTenantId } from "./tenants.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export { NATIVE_AGENT_RECOVER_TOOL, NATIVE_AGENT_RESUME_TOOL, NATIVE_AGENT_RUN_TOOL };
+export const NATIVE_AGENT_HANDLE_SCHEMA = "impel.native-agent-run.v1";
+export const NATIVE_AGENT_RESULT_SCHEMA = "impel.native-agent-result.v1";
+export const NATIVE_AGENT_RECOVERY_SCHEMA = "impel.native-agent-recovery.v1";
+
+const STATE_SCHEMA = "impel.native-agent-state.v1";
+const DELETION_SCHEMA = "impel.native-agent-deletion.v1";
+const FENCE_MARKER_SCHEMA = "impel.native-agent-fence.v1";
+const SAFE_BINDING_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
+const SAFE_FINGERPRINT_RE = /^[a-f0-9]{64}$/u;
+const SAFE_INVOCATION_RE = /^[a-f0-9-]{36}$/u;
+const DEFAULT_WAIT_SECONDS = 20;
+const MAX_WAIT_SECONDS = 50;
+const DEFAULT_ATTACHMENT_WINDOW_MS = 55_000;
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 55_000;
+const DEFAULT_MAX_POLLS = 8;
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_RETAINED_RUNS = 500;
+const DEFAULT_MAX_RECOVERY_RESULTS = 20;
+const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_STATE_BYTES = 512 * 1024;
+const DEFAULT_LOCK_LEASE_MS = 75_000;
+const DEFAULT_ADMISSION_LEASE_MS = 10_000;
+const STATE_COMMIT_LEASE_MARGIN_MS = 5_000;
+const CIBI_START_IN_PROGRESS_CODE = "eve_run_drain_start_in_progress";
+const CIBI_START_IN_PROGRESS_MESSAGE = "The durable Eve drain workflow is still being enqueued; retry this idempotent start.";
+const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  const result = {};
+  for (const key of Object.keys(value).sort()) result[key] = stableValue(value[key]);
+  return result;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function revisionCoordinatesForName(name) {
+  const match = /^(\d{16})-(\d{16})-[a-f0-9]{32}\.json$/u.exec(name);
+  if (!match || path.basename(name) !== name) return null;
+  const coordinates = [Number(match[1]), Number(match[2])];
+  return coordinates.every(Number.isSafeInteger) ? coordinates : null;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function redactOpaqueValue(value, opaque) {
+  if (typeof value === "string") return opaque ? value.replaceAll(opaque, "[REDACTED IDEMPOTENCY KEY]") : value;
+  if (Array.isArray(value)) return value.map((item) => redactOpaqueValue(item, opaque));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactOpaqueValue(item, opaque)]));
+}
+
+function diagnosticValue(value, opaque, depth = 0) {
+  if (depth > 6) return "[TRUNCATED]";
+  if (typeof value === "string") {
+    return redactOpaqueValue(redactSecretText(value), opaque).slice(0, 4_000);
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((item) => diagnosticValue(item, opaque, depth + 1));
+  }
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .slice(0, 50)
+      .map(([key, item]) => [key, diagnosticValue(item, opaque, depth + 1)]),
+  );
+}
+
+function diagnosticFor(error, opaque) {
+  const diagnostic = {
+    message: diagnosticValue(error?.message || error || "native-agent attachment failed", opaque),
+  };
+  if (error?.code !== undefined) diagnostic.code = diagnosticValue(error.code, opaque);
+  if (error?.data !== undefined) diagnostic.data = diagnosticValue(error.data, opaque);
+  return diagnostic;
+}
+
+function replaceObject(target, source) {
+  for (const key of Object.keys(target)) delete target[key];
+  Object.assign(target, source);
+}
+
+function requestFingerprintFor({ tenantId, agentId, scopeParam, policyFingerprint, startArguments }) {
+  return sha256(stableJson({
+    tenantId,
+    agentId,
+    scopeParam,
+    policyFingerprint,
+    arguments: startArguments,
+  }));
+}
+
+function exactObject(value, allowed, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new Error(`${label} contains unsupported properties`);
+  return value;
+}
+
+function boundedString(value, label, max, { nonblank = true } = {}) {
+  if (typeof value !== "string" || value.length > max || (nonblank && !value.trim())) {
+    throw new Error(`${label} is invalid`);
+  }
+  return value;
+}
+
+function contextKeys(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 30) throw new Error("contextKeys is invalid");
+  const seen = new Set();
+  return value.map((item) => {
+    const key = boundedString(item, "contextKeys", 160);
+    if (seen.has(key)) throw new Error("contextKeys contains a duplicate");
+    seen.add(key);
+    return key;
+  });
+}
+
+function abortError() {
+  const error = new Error("native-agent attachment cancelled");
+  error.name = "AbortError";
+  return error;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError();
+}
+
+function boundedAttachmentSignal(parentSignal, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const onAbort = () => controller.abort();
+  parentSignal?.addEventListener("abort", onAbort, { once: true });
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  if (parentSignal?.aborted) controller.abort();
+  return {
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    dispose: () => {
+      clearTimeout(timeout);
+      parentSignal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but is owned by another principal.
+    return error?.code !== "ESRCH";
+  }
+}
+
+function privateDirectory(directory) {
+  if (fs.existsSync(directory)) {
+    const stat = fs.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`refusing to use unsafe native-agent run directory ${directory}`);
+    }
+  } else {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`refusing to use unsafe native-agent run directory ${directory}`);
+    }
+  }
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // chmod is best effort on Windows.
+  }
+}
+
+export class NativeAgentStateSizeError extends Error {
+  constructor(message = "native-agent run state exceeds the configured size limit") {
+    super(message);
+    this.name = "NativeAgentStateSizeError";
+  }
+}
+
+function safeStateJson(state, maxBytes) {
+  const serialized = `${JSON.stringify(state, null, 2)}\n`;
+  if (redactCredentialText(serialized) !== serialized) {
+    throw new Error("refusing to persist a credential in native-agent run state");
+  }
+  if (Buffer.byteLength(serialized, "utf8") > maxBytes) {
+    throw new NativeAgentStateSizeError();
+  }
+  return serialized;
+}
+
+function atomicPrivateWrite(filePath, state, maxBytes, { beforeRename } = {}) {
+  privateDirectory(path.dirname(filePath));
+  if (fs.existsSync(filePath) && fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error("refusing to write symlinked native-agent run state");
+  }
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  try {
+    fs.writeFileSync(temporaryPath, safeStateJson(state, maxBytes), { mode: 0o600, flag: "wx" });
+    beforeRename?.();
+    renameWithWindowsRetry(temporaryPath, filePath);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // chmod is best effort on Windows.
+    }
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The rename removes the temporary file on the normal path.
+    }
+  }
+}
+
+function readPrivateState(filePath, maxBytes) {
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > maxBytes) {
+    throw new Error("native-agent run state is unsafe or invalid");
+  }
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    throw new Error("native-agent run state is invalid");
+  }
+  if (!state || typeof state !== "object" || Array.isArray(state) || state.schema !== STATE_SCHEMA) {
+    throw new Error("native-agent run state is invalid");
+  }
+  try {
+    exactObject(state, [
+      "schema",
+      "invocationId",
+      "tenantId",
+      "agentId",
+      "scopeParam",
+      "policyFingerprint",
+      "requestFingerprint",
+      "idempotencyKey",
+      "startArguments",
+      "upstreamRunId",
+      "status",
+      "startAttempts",
+      "createdAt",
+      "updatedAt",
+      "fence",
+      "sequence",
+      "lastTransportError",
+      "result",
+      "output",
+      "error",
+    ], "native-agent run state");
+    if (!SAFE_INVOCATION_RE.test(state.invocationId)
+      || normalizeTenantId(state.tenantId) !== state.tenantId
+      || !SAFE_BINDING_RE.test(state.agentId)
+      || !SAFE_BINDING_RE.test(state.scopeParam)
+      || !SAFE_FINGERPRINT_RE.test(state.policyFingerprint)
+      || !SAFE_FINGERPRINT_RE.test(state.requestFingerprint)
+      || typeof state.idempotencyKey !== "string"
+      || !/^[A-Za-z0-9._:-]{16,200}$/u.test(state.idempotencyKey)
+      || typeof state.status !== "string"
+      || !state.status
+      || !Number.isSafeInteger(state.startAttempts)
+      || state.startAttempts < 0
+      || !Number.isFinite(Date.parse(state.createdAt))
+      || !Number.isFinite(Date.parse(state.updatedAt))
+      || (state.fence !== undefined && (!Number.isSafeInteger(state.fence) || state.fence < 0))
+      || (state.sequence !== undefined && (!Number.isSafeInteger(state.sequence) || state.sequence < 0))
+      || (state.upstreamRunId !== null && (typeof state.upstreamRunId !== "string" || !state.upstreamRunId))) {
+      throw new Error("invalid field");
+    }
+    exactObject(state.startArguments, [
+      "agentId",
+      "scopeParam",
+      "task",
+      "context",
+      "contextKeys",
+      "confirmedSideEffects",
+      "idempotencyKey",
+    ], "native-agent start arguments");
+    boundedString(state.startArguments.task, "task", 40_000);
+    if (state.startArguments.context !== undefined) {
+      boundedString(state.startArguments.context, "context", 40_000, { nonblank: false });
+    }
+    contextKeys(state.startArguments.contextKeys);
+    if (state.startArguments.confirmedSideEffects !== undefined
+      && typeof state.startArguments.confirmedSideEffects !== "boolean") {
+      throw new Error("invalid side-effect confirmation");
+    }
+    if (state.startArguments.agentId !== state.agentId
+      || state.startArguments.scopeParam !== state.scopeParam
+      || state.startArguments.idempotencyKey !== state.idempotencyKey
+      || requestFingerprintFor(state) !== state.requestFingerprint) {
+      throw new Error("fingerprint mismatch");
+    }
+  } catch {
+    throw new Error("native-agent run state failed integrity validation");
+  }
+  return state;
+}
+
+function handleForState(state) {
+  return {
+    schema: NATIVE_AGENT_HANDLE_SCHEMA,
+    tenantId: state.tenantId,
+    agentId: state.agentId,
+    scopeParam: state.scopeParam,
+    policyFingerprint: state.policyFingerprint,
+    invocationId: state.invocationId,
+    requestFingerprint: state.requestFingerprint,
+  };
+}
+
+function normalizeHandle(value) {
+  exactObject(value, [
+    "schema",
+    "tenantId",
+    "agentId",
+    "scopeParam",
+    "policyFingerprint",
+    "invocationId",
+    "requestFingerprint",
+  ], "native-agent handle");
+  if (value.schema !== NATIVE_AGENT_HANDLE_SCHEMA) throw new Error("native-agent handle schema is invalid");
+  const tenantId = normalizeTenantId(value.tenantId);
+  for (const [field, item] of Object.entries({ agentId: value.agentId, scopeParam: value.scopeParam })) {
+    if (typeof item !== "string" || !SAFE_BINDING_RE.test(item)) {
+      throw new Error(`native-agent handle ${field} is invalid`);
+    }
+  }
+  for (const field of ["policyFingerprint", "requestFingerprint"]) {
+    if (typeof value[field] !== "string" || !SAFE_FINGERPRINT_RE.test(value[field])) {
+      throw new Error(`native-agent handle ${field} is invalid`);
+    }
+  }
+  if (typeof value.invocationId !== "string" || !SAFE_INVOCATION_RE.test(value.invocationId)) {
+    throw new Error("native-agent handle invocationId is invalid");
+  }
+  return { ...value, tenantId };
+}
+
+function preservedOutput(payload) {
+  if (payload && Object.hasOwn(payload, "output")) return payload.output;
+  if (payload && Object.hasOwn(payload, "result")) return payload.result;
+  return null;
+}
+
+function resultForState(state) {
+  if (state.status === "succeeded") {
+    const finalText = state.result?.finalText;
+    if (typeof finalText !== "string") {
+      // A crash can occur after the upstream identity is made durable but
+      // before its terminal payload is committed. Reattach instead of turning
+      // that narrow window into an unrecoverable terminal snapshot.
+      return handleForState(state);
+    }
+    return {
+      schema: NATIVE_AGENT_RESULT_SCHEMA,
+      status: "succeeded",
+      runId: state.upstreamRunId,
+      finalText,
+    };
+  }
+  if (TERMINAL_STATUSES.has(state.status)) {
+    return {
+      schema: NATIVE_AGENT_RESULT_SCHEMA,
+      status: state.status,
+      runId: state.upstreamRunId || null,
+      output: Object.hasOwn(state, "output")
+        ? state.output
+        : typeof state.result?.finalText === "string"
+          ? state.result.finalText
+          : preservedOutput(state),
+      error: Object.hasOwn(state, "error") ? state.error : "native-agent run failed",
+    };
+  }
+  return handleForState(state);
+}
+
+function applyUpstreamPayload(state, payload, now) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("native-agent upstream returned an invalid run");
+  }
+  if (payload.runId !== undefined) {
+    boundedString(payload.runId, "native-agent runId", 512);
+    if (state.upstreamRunId && payload.runId !== state.upstreamRunId) {
+      throw new Error("native-agent upstream returned a different runId");
+    }
+    state.upstreamRunId = payload.runId;
+  }
+  if (typeof payload.status === "string" && payload.status) state.status = payload.status;
+  else if (state.upstreamRunId && state.status === "starting") state.status = "queued";
+  if (Object.hasOwn(payload, "result")) state.result = payload.result;
+  if (Object.hasOwn(payload, "output")) state.output = payload.output;
+  else if (TERMINAL_STATUSES.has(state.status)
+    && state.status !== "succeeded"
+    && typeof payload.result?.finalText === "string") {
+    // Hosted/CIBI failure payloads carry their authoritative partial text in
+    // result.finalText rather than output; replace any older running snapshot.
+    state.output = payload.result.finalText;
+  }
+  if (Object.hasOwn(payload, "error")) {
+    state.error = redactOpaqueValue(payload.error, state.idempotencyKey);
+  }
+  state.updatedAt = new Date(now).toISOString();
+}
+
+/** Use the read tool's advertised integer maximum, never exceeding 50 seconds. */
+export function negotiateNativeAgentWaitSeconds(tools) {
+  const readTool = Array.isArray(tools)
+    ? tools.find((tool) => tool?.name === NATIVE_AGENT_READ_TOOL)
+    : null;
+  const maximum = readTool?.inputSchema?.properties?.waitSeconds?.maximum;
+  if (typeof maximum !== "number" || !Number.isFinite(maximum) || maximum < 1) {
+    return DEFAULT_WAIT_SECONDS;
+  }
+  return Math.min(MAX_WAIT_SECONDS, Math.max(1, Math.floor(maximum)));
+}
+
+export class NativeAgentUpstreamError extends Error {
+  constructor(message, {
+    ambiguous = false,
+    code,
+    data,
+    incompleteResponse = false,
+  } = {}) {
+    super(message);
+    this.name = "NativeAgentUpstreamError";
+    this.ambiguous = ambiguous;
+    this.incompleteResponse = incompleteResponse;
+    if (code !== undefined) this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
+async function readBoundedResponseBody(response, maxBytes) {
+  if (!response.body || typeof response.body.getReader !== "function") {
+    const body = await response.text();
+    if (Buffer.byteLength(body, "utf8") > maxBytes) {
+      throw new NativeAgentUpstreamError("native-agent MCP response exceeded the size limit", {
+        ambiguous: true,
+        incompleteResponse: true,
+      });
+    }
+    return body;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let body = "";
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {
+          // Cancelling an already failed response body is best effort.
+        }
+        throw new NativeAgentUpstreamError("native-agent MCP response exceeded the size limit", {
+          ambiguous: true,
+          incompleteResponse: true,
+        });
+      }
+      body += decoder.decode(value, { stream: true });
+    }
+    body += decoder.decode();
+    return body;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function decodeMcpResponse(contentType, body) {
+  if (!body.trim()) return [];
+  if (!String(contentType || "").toLowerCase().includes("text/event-stream")) {
+    return [JSON.parse(body)];
+  }
+  return body
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trim())
+    .filter((line) => line && line !== "[DONE]")
+    .map((line) => JSON.parse(line));
+}
+
+function toolPayload(message) {
+  if (!message) {
+    throw new NativeAgentUpstreamError("native-agent MCP returned no matching response", {
+      incompleteResponse: true,
+    });
+  }
+  if (message.error) {
+    throw new NativeAgentUpstreamError(
+      redactSecretText(message.error.message || "native-agent MCP tool failed"),
+      { code: message.error.code, data: message.error.data },
+    );
+  }
+  const result = message.result;
+  const text = result?.content?.find((item) => item?.type === "text" && typeof item.text === "string")?.text;
+  if (result?.isError) {
+    throw new NativeAgentUpstreamError(redactSecretText(text || "native-agent MCP tool failed"));
+  }
+  if (result?.structuredContent && typeof result.structuredContent === "object") {
+    return result.structuredContent;
+  }
+  if (text !== undefined) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new NativeAgentUpstreamError("native-agent MCP tool returned invalid JSON", {
+        incompleteResponse: true,
+      });
+    }
+  }
+  return result;
+}
+
+export class NativeAgentUpstreamSession {
+  constructor({
+    gatewayUrl,
+    credential,
+    fetchImpl = fetch,
+    timeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES,
+    signal,
+  }) {
+    this.endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
+    this.credential = credential;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this.maxResponseBytes = maxResponseBytes;
+    this.signal = signal;
+    this.sessionId = null;
+    this.nextId = 1;
+  }
+
+  async post(message) {
+    throwIfAborted(this.signal);
+    const controller = new AbortController();
+    let timedOut = false;
+    const onAbort = () => controller.abort();
+    this.signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeoutMs);
+    let response;
+    let body;
+    try {
+      response = await this.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.credential}`,
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          ...(this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {}),
+        },
+        body: JSON.stringify(message),
+        signal: controller.signal,
+      });
+      body = await readBoundedResponseBody(response, this.maxResponseBytes);
+    } catch (error) {
+      if (this.signal?.aborted) throw abortError();
+      const detail = timedOut ? "request timed out" : redactSecretText(error?.message || error);
+      throw new NativeAgentUpstreamError(`native-agent MCP request failed: ${detail}`, { ambiguous: true });
+    } finally {
+      clearTimeout(timeout);
+      this.signal?.removeEventListener("abort", onAbort);
+    }
+    this.sessionId = response.headers.get("mcp-session-id") || this.sessionId;
+    if (!response.ok) {
+      throw new NativeAgentUpstreamError(`native-agent MCP returned HTTP ${response.status}`, {
+        ambiguous: response.status === 408 || response.status === 429 || response.status >= 500,
+      });
+    }
+    try {
+      return decodeMcpResponse(response.headers.get("content-type"), body);
+    } catch {
+      throw new NativeAgentUpstreamError("native-agent MCP returned invalid JSON", {
+        incompleteResponse: true,
+      });
+    }
+  }
+
+  async initialize() {
+    const id = this.nextId++;
+    const initialized = await this.post({
+      jsonrpc: "2.0",
+      id,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "impel-cli-native-agent-transport", version: "1.0.0" },
+      },
+    });
+    const response = initialized.find((message) => message?.id === id);
+    if (!response?.result || response.error) {
+      throw new NativeAgentUpstreamError("native-agent MCP initialization failed");
+    }
+    await this.post({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+    const toolsId = this.nextId++;
+    const listed = await this.post({ jsonrpc: "2.0", id: toolsId, method: "tools/list", params: {} });
+    const toolsResponse = listed.find((message) => message?.id === toolsId);
+    if (toolsResponse?.error || !Array.isArray(toolsResponse?.result?.tools)) {
+      throw new NativeAgentUpstreamError("native-agent MCP returned no tool catalog");
+    }
+    return toolsResponse.result.tools;
+  }
+
+  async call(name, args) {
+    const id = this.nextId++;
+    try {
+      const messages = await this.post({
+        jsonrpc: "2.0",
+        id,
+        method: "tools/call",
+        params: { name, arguments: args },
+      });
+      return toolPayload(messages.find((message) => message?.id === id));
+    } catch (error) {
+      if (name === NATIVE_AGENT_START_TOOL
+        && error instanceof NativeAgentUpstreamError
+        && (error.incompleteResponse
+          || error.code === CIBI_START_IN_PROGRESS_CODE
+          || error.data?.code === CIBI_START_IN_PROGRESS_CODE
+          || error.message === CIBI_START_IN_PROGRESS_MESSAGE)) {
+        error.ambiguous = true;
+      }
+      throw error;
+    }
+  }
+}
+
+export class NativeAgentCompositeTransport {
+  constructor({
+    tenantId,
+    agentId,
+    scopeParam,
+    policyFingerprint,
+    gatewayUrl,
+    credential,
+    runsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
+    attachmentWindowMs = DEFAULT_ATTACHMENT_WINDOW_MS,
+    maxPolls = DEFAULT_MAX_POLLS,
+    now = Date.now,
+    randomUUID = crypto.randomUUID,
+    randomBytes = crypto.randomBytes,
+    sessionFactory,
+    fetchImpl = fetch,
+    upstreamTimeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS,
+    maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES,
+    maxStateBytes = DEFAULT_MAX_STATE_BYTES,
+    maxRetainedRuns = DEFAULT_MAX_RETAINED_RUNS,
+    retentionMs = DEFAULT_RETENTION_MS,
+    maxRecoveryResults = DEFAULT_MAX_RECOVERY_RESULTS,
+    lockLeaseMs = DEFAULT_LOCK_LEASE_MS,
+    isProcessAlive = processIsAlive,
+    beforeFenceMarkerPublish,
+    beforeFenceMarkerCompaction,
+    beforeStateRename,
+    beforeRevisionCompaction,
+    beforePruneDelete,
+  }) {
+    this.tenantId = normalizeTenantId(tenantId);
+    for (const [field, value] of Object.entries({ agentId, scopeParam })) {
+      if (typeof value !== "string" || !SAFE_BINDING_RE.test(value)) {
+        throw new Error(`native-agent ${field} binding is invalid`);
+      }
+    }
+    if (typeof policyFingerprint !== "string" || !SAFE_FINGERPRINT_RE.test(policyFingerprint)) {
+      throw new Error("native-agent policy fingerprint is invalid");
+    }
+    this.agentId = agentId;
+    this.scopeParam = scopeParam;
+    this.policyFingerprint = policyFingerprint;
+    this.gatewayUrl = gatewayUrl;
+    this.credential = credential;
+    this.runsRoot = runsRoot;
+    this.tenantRoot = path.join(runsRoot, this.tenantId);
+    this.attachmentWindowMs = Math.max(1, attachmentWindowMs);
+    this.maxPolls = Math.max(1, maxPolls);
+    this.now = now;
+    this.randomUUID = randomUUID;
+    this.randomBytes = randomBytes;
+    this.fetchImpl = fetchImpl;
+    this.upstreamTimeoutMs = upstreamTimeoutMs;
+    this.maxResponseBytes = Math.max(1024, maxResponseBytes);
+    this.maxStateBytes = Math.max(1024, maxStateBytes);
+    this.maxRetainedRuns = Math.max(1, maxRetainedRuns);
+    this.retentionMs = Math.max(0, retentionMs);
+    this.maxRecoveryResults = Math.max(1, maxRecoveryResults);
+    // Keep a healthy owner fenced through its full attachment window plus the
+    // platform's bounded atomic-replace retry window.
+    this.lockLeaseMs = Math.max(
+      this.attachmentWindowMs + STATE_COMMIT_LEASE_MARGIN_MS,
+      lockLeaseMs,
+    );
+    this.isProcessAlive = isProcessAlive;
+    this.beforeFenceMarkerPublish = beforeFenceMarkerPublish;
+    this.beforeFenceMarkerCompaction = beforeFenceMarkerCompaction;
+    this.beforeStateRename = beforeStateRename;
+    this.beforeRevisionCompaction = beforeRevisionCompaction;
+    this.beforePruneDelete = beforePruneDelete;
+    this.sessionFactory = sessionFactory || (({ signal }) => new NativeAgentUpstreamSession({
+      gatewayUrl: this.gatewayUrl,
+      credential: this.credential,
+      fetchImpl: this.fetchImpl,
+      timeoutMs: this.upstreamTimeoutMs,
+      maxResponseBytes: this.maxResponseBytes,
+      signal,
+    }));
+  }
+
+  statePath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.json`);
+  }
+
+  lockPath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.lock`);
+  }
+
+  stateVersionsPath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.state-versions`);
+  }
+
+  fencePath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.fence`);
+  }
+
+  fenceVersionsPath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.fence-versions`);
+  }
+
+  deletionPath(invocationId) {
+    return path.join(this.tenantRoot, `${invocationId}.tombstone`);
+  }
+
+  admissionLockPath() {
+    return path.join(this.tenantRoot, ".allocation.lock");
+  }
+
+  ensureRoots() {
+    privateDirectory(this.runsRoot);
+    privateDirectory(this.tenantRoot);
+  }
+
+  readLegacyLockOwner(lockPath) {
+    const stat = fs.lstatSync(lockPath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+      throw new Error("native-agent run lock is unsafe or invalid");
+    }
+    let owner;
+    try {
+      owner = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    } catch {
+      throw new Error("native-agent run lock is invalid");
+    }
+    if (!Number.isSafeInteger(owner?.pid)
+      || owner.pid < 1
+      || !Number.isFinite(Date.parse(owner.createdAt))) {
+      throw new Error("native-agent run lock is invalid");
+    }
+    return { owner, stat };
+  }
+
+  readLockClaim(lockPath) {
+    const stat = fs.lstatSync(lockPath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+      throw new Error("native-agent run lock is unsafe or invalid");
+    }
+    let claim;
+    try {
+      claim = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+      exactObject(claim, ["schema", "nonce", "generation"], "native-agent run lock claim");
+    } catch {
+      throw new Error("native-agent run lock is invalid");
+    }
+    if (claim.schema !== "impel.native-agent-lock-claim.v2"
+      || typeof claim.nonce !== "string"
+      || !/^[a-f0-9]{32}$/u.test(claim.nonce)
+      || path.basename(claim.generation) !== claim.generation
+      || !claim.generation.endsWith(`.generation-${claim.nonce}`)) {
+      throw new Error("native-agent run lock is invalid");
+    }
+    return { claim, stat };
+  }
+
+  readClaimedLock(lockPath) {
+    const { claim, stat: claimStat } = this.readLockClaim(lockPath);
+    const generationPath = path.join(path.dirname(lockPath), claim.generation);
+    const generationStat = fs.lstatSync(generationPath);
+    if (generationStat.isSymbolicLink() || !generationStat.isDirectory()) {
+      throw new Error("native-agent run lock generation is unsafe or invalid");
+    }
+    const ownerPath = path.join(generationPath, `owner-${claim.nonce}.json`);
+    const stat = fs.lstatSync(ownerPath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+      throw new Error("native-agent run lock is unsafe or invalid");
+    }
+    let owner;
+    try {
+      owner = JSON.parse(fs.readFileSync(ownerPath, "utf8"));
+      exactObject(owner, ["pid", "nonce", "createdAt", "fence"], "native-agent run lock");
+    } catch {
+      throw new Error("native-agent run lock is invalid");
+    }
+    if (!Number.isSafeInteger(owner.pid)
+      || owner.pid < 1
+      || typeof owner.nonce !== "string"
+      || !/^[a-f0-9]{32}$/u.test(owner.nonce)
+      || !Number.isFinite(Date.parse(owner.createdAt))
+      || (owner.fence !== null && (!Number.isSafeInteger(owner.fence) || owner.fence < 1))) {
+      throw new Error("native-agent run lock is invalid");
+    }
+    if (owner.nonce !== claim.nonce) throw new Error("native-agent run lock generation is invalid");
+    return {
+      claim,
+      claimStat,
+      generationPath,
+      generationStat,
+      owner,
+      ownerPath,
+      stat,
+    };
+  }
+
+  lockIsStale(owner, heartbeatMs, leaseMs, now = this.now()) {
+    const createdAge = now - Date.parse(owner.createdAt);
+    const heartbeatAge = now - heartbeatMs;
+    return !this.isProcessAlive(owner.pid)
+      || createdAge < -leaseMs
+      || heartbeatAge > leaseMs
+      || heartbeatAge < -leaseMs;
+  }
+
+  readFence(invocationId) {
+    const fencePath = this.fencePath(invocationId);
+    if (!fs.existsSync(fencePath)) return 0;
+    const stat = fs.lstatSync(fencePath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 128) {
+      throw new Error("native-agent run fence is unsafe or invalid");
+    }
+    const fence = Number(fs.readFileSync(fencePath, "utf8").trim());
+    if (!Number.isSafeInteger(fence) || fence < 0) {
+      throw new Error("native-agent run fence is invalid");
+    }
+    return fence;
+  }
+
+  readDeletionTombstone(invocationId) {
+    const deletionPath = this.deletionPath(invocationId);
+    let stat;
+    try {
+      stat = fs.lstatSync(deletionPath);
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+      throw new Error("native-agent deletion tombstone is unsafe or invalid");
+    }
+    let tombstone;
+    try {
+      tombstone = JSON.parse(fs.readFileSync(deletionPath, "utf8"));
+      exactObject(
+        tombstone,
+        ["schema", "invocationId", "fence", "deletedAt"],
+        "native-agent deletion tombstone",
+      );
+    } catch {
+      throw new Error("native-agent deletion tombstone is invalid");
+    }
+    if (tombstone.schema !== DELETION_SCHEMA
+      || tombstone.invocationId !== invocationId
+      || !Number.isSafeInteger(tombstone.fence)
+      || tombstone.fence < 1
+      || !Number.isFinite(Date.parse(tombstone.deletedAt))) {
+      throw new Error("native-agent deletion tombstone is invalid");
+    }
+    return tombstone;
+  }
+
+  writeDeletionTombstone(invocationId, lock) {
+    lock.assert();
+    const deletionPath = this.deletionPath(invocationId);
+    const tombstone = {
+      schema: DELETION_SCHEMA,
+      invocationId,
+      fence: lock.fence,
+      deletedAt: new Date(this.now()).toISOString(),
+    };
+    const temporaryPath = `${deletionPath}.tmp-${process.pid}-${lock.nonce}`;
+    try {
+      fs.writeFileSync(temporaryPath, safeStateJson(tombstone, 1024), { mode: 0o600, flag: "wx" });
+      try {
+        // Publish a fully written marker once. The marker and fence are never
+        // removed, so no delayed lower-fence state can resurrect this id.
+        fs.linkSync(temporaryPath, deletionPath);
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        this.readDeletionTombstone(invocationId);
+      }
+      try {
+        fs.chmodSync(deletionPath, 0o600);
+      } catch {
+        // chmod is best effort on Windows.
+      }
+    } finally {
+      fs.rmSync(temporaryPath, { force: true });
+    }
+  }
+
+  cleanupTombstonedState(invocationId) {
+    for (const [target, options] of [
+      [this.statePath(invocationId), { force: true }],
+      [this.stateVersionsPath(invocationId), { recursive: true, force: true }],
+    ]) {
+      try {
+        fs.rmSync(target, options);
+      } catch {
+        // The persistent tombstone is already authoritative. A later prune
+        // retries physical cleanup without charging this id to capacity.
+      }
+    }
+  }
+
+  readFenceMarker(filePath, invocationId, expectedFence, expectedNonce) {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+      throw new Error("native-agent fence marker is unsafe or invalid");
+    }
+    let marker;
+    try {
+      marker = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      exactObject(
+        marker,
+        ["schema", "invocationId", "fence", "nonce", "createdAt"],
+        "native-agent fence marker",
+      );
+    } catch {
+      throw new Error("native-agent fence marker is invalid");
+    }
+    if (marker.schema !== FENCE_MARKER_SCHEMA
+      || marker.invocationId !== invocationId
+      || marker.fence !== expectedFence
+      || marker.nonce !== expectedNonce
+      || !Number.isFinite(Date.parse(marker.createdAt))) {
+      throw new Error("native-agent fence marker is invalid");
+    }
+    return marker;
+  }
+
+  fenceMarkers(invocationId) {
+    const versionsPath = this.fenceVersionsPath(invocationId);
+    if (!fs.existsSync(versionsPath)) return [];
+    const stat = fs.lstatSync(versionsPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error("native-agent fence markers are unsafe or invalid");
+    }
+    const markers = [];
+    for (const name of fs.readdirSync(versionsPath)) {
+      if (!name.endsWith(".json")) continue;
+      const match = /^(\d{16})-([a-f0-9]{32})\.json$/u.exec(name);
+      const fence = match ? Number(match[1]) : Number.NaN;
+      if (!match || path.basename(name) !== name || !Number.isSafeInteger(fence)) {
+        throw new Error("native-agent fence marker is invalid");
+      }
+      const filePath = path.join(versionsPath, name);
+      markers.push({
+        filePath,
+        marker: this.readFenceMarker(filePath, invocationId, fence, match[2]),
+      });
+    }
+    return markers;
+  }
+
+  highestImmutableFence(invocationId) {
+    return this.fenceMarkers(invocationId)
+      .reduce((highest, { marker }) => Math.max(highest, marker.fence), 0);
+  }
+
+  publishFenceMarker(invocationId, fence, nonce) {
+    const versionsPath = this.fenceVersionsPath(invocationId);
+    privateDirectory(versionsPath);
+    const markerPath = path.join(
+      versionsPath,
+      `${String(fence).padStart(16, "0")}-${nonce}.json`,
+    );
+    const temporaryPath = `${markerPath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    const marker = {
+      schema: FENCE_MARKER_SCHEMA,
+      invocationId,
+      fence,
+      nonce,
+      createdAt: new Date(this.now()).toISOString(),
+    };
+    try {
+      fs.writeFileSync(temporaryPath, safeStateJson(marker, 1024), { mode: 0o600, flag: "wx" });
+      this.beforeFenceMarkerPublish?.({ invocationId, fence, nonce });
+      try {
+        fs.linkSync(temporaryPath, markerPath);
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      this.readFenceMarker(markerPath, invocationId, fence, nonce);
+    } finally {
+      fs.rmSync(temporaryPath, { force: true });
+    }
+    const lower = this.fenceMarkers(invocationId)
+      .filter(({ marker: candidate }) => candidate.fence < fence)
+      .map(({ filePath }) => filePath);
+    this.beforeFenceMarkerCompaction?.({ invocationId, fence, nonce });
+    for (const obsolete of lower) fs.rmSync(obsolete, { force: true });
+  }
+
+  writeFenceCache(invocationId, fence) {
+    const fencePath = this.fencePath(invocationId);
+    const temporaryPath = `${fencePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    try {
+      fs.writeFileSync(temporaryPath, `${fence}\n`, { mode: 0o600, flag: "wx" });
+      renameWithWindowsRetry(temporaryPath, fencePath);
+    } finally {
+      fs.rmSync(temporaryPath, { force: true });
+    }
+  }
+
+  reserveFence(invocationId, nonce) {
+    const tombstone = this.readDeletionTombstone(invocationId);
+    if (tombstone) throw new Error("native-agent run handle is unknown or expired");
+    const authoritativeState = this.readLatestState(invocationId, { allowMissing: true });
+    const fence = Math.max(
+      this.highestImmutableFence(invocationId),
+      authoritativeState?.fence ?? 0,
+      tombstone?.fence ?? 0,
+      this.readFence(invocationId),
+    ) + 1;
+    if (!Number.isSafeInteger(fence)) throw new Error("native-agent run fence is exhausted");
+    this.publishFenceMarker(invocationId, fence, nonce);
+    // Compatibility cache only. Immutable markers and state remain the
+    // authority if a delayed lower owner rolls this mutable file backward.
+    this.writeFenceCache(invocationId, fence);
+    return fence;
+  }
+
+  readLatestState(invocationId, { allowMissing = false } = {}) {
+    if (this.readDeletionTombstone(invocationId)) {
+      if (allowMissing) return null;
+      throw new Error("native-agent run handle is unknown or expired");
+    }
+    const candidates = [];
+    const basePath = this.statePath(invocationId);
+    if (fs.existsSync(basePath)) candidates.push({ filePath: basePath, expected: null });
+    const versionsPath = this.stateVersionsPath(invocationId);
+    if (fs.existsSync(versionsPath)) {
+      const stat = fs.lstatSync(versionsPath);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error("native-agent state revisions are unsafe or invalid");
+      }
+      for (const name of fs.readdirSync(versionsPath)) {
+        if (!name.endsWith(".json")) continue;
+        const expected = revisionCoordinatesForName(name);
+        if (!expected) {
+          throw new Error("native-agent state revision is invalid");
+        }
+        candidates.push({
+          filePath: path.join(versionsPath, name),
+          expected,
+        });
+      }
+    }
+    if (!candidates.length) {
+      if (allowMissing) return null;
+      throw new Error("native-agent run handle is unknown or expired");
+    }
+    let latest = null;
+    for (const candidate of candidates) {
+      const state = readPrivateState(candidate.filePath, this.maxStateBytes);
+      if (state.invocationId !== invocationId) {
+        throw new Error("native-agent state revision failed integrity validation");
+      }
+      const coordinates = [state.fence ?? 0, state.sequence ?? 0];
+      if (candidate.expected
+        && (coordinates[0] !== candidate.expected[0]
+          || coordinates[1] !== candidate.expected[1])) {
+        throw new Error("native-agent state revision failed integrity validation");
+      }
+      if (!latest
+        || coordinates[0] > latest.coordinates[0]
+        || (coordinates[0] === latest.coordinates[0] && coordinates[1] > latest.coordinates[1])) {
+        latest = { state, coordinates };
+      } else if (coordinates[0] === latest.coordinates[0]
+        && coordinates[1] === latest.coordinates[1]
+        && stableJson(state) !== stableJson(latest.state)) {
+        throw new Error("native-agent state revisions conflict");
+      }
+    }
+    return latest.state;
+  }
+
+  lowerRevisionPaths(invocationId, publishedCoordinates) {
+    const versionsPath = this.stateVersionsPath(invocationId);
+    const lower = [];
+    for (const name of fs.readdirSync(versionsPath)) {
+      if (!name.endsWith(".json")) continue;
+      const coordinates = revisionCoordinatesForName(name);
+      if (!coordinates) throw new Error("native-agent state revision is invalid");
+      const filePath = path.join(versionsPath, name);
+      const state = readPrivateState(filePath, this.maxStateBytes);
+      if (state.invocationId !== invocationId
+        || (state.fence ?? 0) !== coordinates[0]
+        || (state.sequence ?? 0) !== coordinates[1]) {
+        throw new Error("native-agent state revision failed integrity validation");
+      }
+      if (coordinates[0] < publishedCoordinates[0]
+        || (coordinates[0] === publishedCoordinates[0]
+          && coordinates[1] < publishedCoordinates[1])) {
+        lower.push(filePath);
+      }
+    }
+    return lower;
+  }
+
+  writeRevision(state, lock, { invokeHook = true } = {}) {
+    const next = structuredClone(state);
+    next.fence = lock.fence;
+    next.sequence = lock.nextSequence + 1;
+    const versionsPath = this.stateVersionsPath(next.invocationId);
+    privateDirectory(versionsPath);
+    const revisionName = `${String(next.fence).padStart(16, "0")}-${String(next.sequence).padStart(16, "0")}-${lock.nonce}.json`;
+    const revisionPath = path.join(versionsPath, revisionName);
+    atomicPrivateWrite(revisionPath, next, this.maxStateBytes, {
+      beforeRename: invokeHook ? this.beforeStateRename : undefined,
+    });
+    const published = readPrivateState(revisionPath, this.maxStateBytes);
+    if (stableJson(published) !== stableJson(next)) {
+      throw new Error("native-agent state revision failed publication validation");
+    }
+    // The immutable revision is authoritative. A takeover that occurs during
+    // the write has already allocated and snapshotted a higher fence, so this
+    // late lower-fence revision can never become visible to readers.
+    lock.assert();
+    const lower = this.lowerRevisionPaths(next.invocationId, [next.fence, next.sequence]);
+    if (invokeHook) {
+      this.beforeRevisionCompaction?.({
+        invocationId: next.invocationId,
+        fence: next.fence,
+        sequence: next.sequence,
+        lock,
+      });
+    }
+    for (const obsolete of lower) fs.rmSync(obsolete, { force: true });
+    atomicPrivateWrite(this.statePath(next.invocationId), next, this.maxStateBytes);
+    lock.assert();
+    lock.nextSequence = next.sequence;
+    replaceObject(state, next);
+  }
+
+  acquireLeaseDirectory(lockPath, {
+    invocationId = null,
+    leaseMs = this.lockLeaseMs,
+  } = {}) {
+    this.ensureRoots();
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const nonce = this.randomBytes(16).subarray(0, 16).toString("hex");
+      const generationName = `${path.basename(lockPath)}.generation-${nonce}`;
+      const generationPath = path.join(path.dirname(lockPath), generationName);
+      const claimPath = `${lockPath}.claim-${process.pid}-${nonce}`;
+      let published = false;
+      try {
+        fs.mkdirSync(generationPath, { mode: 0o700 });
+        let owner = {
+          pid: process.pid,
+          nonce,
+          createdAt: new Date(this.now()).toISOString(),
+          fence: null,
+        };
+        const ownerPath = path.join(generationPath, `owner-${nonce}.json`);
+        fs.writeFileSync(ownerPath, `${JSON.stringify(owner)}\n`, { mode: 0o600, flag: "wx" });
+        const createdHeartbeat = new Date(this.now());
+        fs.utimesSync(ownerPath, createdHeartbeat, createdHeartbeat);
+        fs.writeFileSync(claimPath, `${JSON.stringify({
+          schema: "impel.native-agent-lock-claim.v2",
+          nonce,
+          generation: generationName,
+        })}\n`, { mode: 0o600, flag: "wx" });
+        // Hard-link publication is an atomic create-if-absent operation. A
+        // visible claim always names a fully populated immutable generation.
+        fs.linkSync(claimPath, lockPath);
+        published = true;
+        fs.rmSync(claimPath, { force: true });
+        if (invocationId && this.readDeletionTombstone(invocationId)) {
+          throw new Error("native-agent run handle is unknown or expired");
+        }
+        const fence = invocationId ? this.reserveFence(invocationId, nonce) : null;
+        owner = { ...owner, fence };
+        atomicPrivateWrite(ownerPath, owner, 1024);
+        const finalizedHeartbeat = new Date(this.now());
+        fs.utimesSync(ownerPath, finalizedHeartbeat, finalizedHeartbeat);
+        const lock = {
+          nonce,
+          fence,
+          nextSequence: -1,
+          assert: () => {
+            if (invocationId && this.readDeletionTombstone(invocationId)) {
+              throw new Error("native-agent run lock ownership was lost");
+            }
+            let current;
+            try {
+              current = this.readClaimedLock(lockPath);
+            } catch {
+              throw new Error("native-agent run lock ownership was lost");
+            }
+            if (current.claim.nonce !== nonce
+              || current.owner.nonce !== nonce
+              || current.owner.fence !== fence
+              || fs.existsSync(path.join(generationPath, `released-${nonce}`))
+              || this.lockIsStale(current.owner, current.stat.mtimeMs, leaseMs)) {
+              throw new Error("native-agent run lock ownership was lost");
+            }
+            const heartbeat = new Date(this.now());
+            fs.utimesSync(current.ownerPath, heartbeat, heartbeat);
+            const verified = this.readClaimedLock(lockPath);
+            if (verified.claim.nonce !== nonce
+              || verified.owner.nonce !== nonce
+              || verified.owner.fence !== fence) {
+              throw new Error("native-agent run lock ownership was lost");
+            }
+          },
+          release: () => {
+            const marker = path.join(generationPath, `released-${nonce}`);
+            try {
+              fs.writeFileSync(marker, `${nonce}\n`, { mode: 0o600, flag: "wx" });
+            } catch {
+              // The marker is owner-specific. If takeover already moved this
+              // generation, a delayed release cannot affect its successor.
+            }
+          },
+        };
+        lock.assert();
+        if (invocationId) {
+          const prior = this.readLatestState(invocationId, { allowMissing: true });
+          if (prior) this.writeRevision(prior, lock, { invokeHook: false });
+        }
+        return lock;
+      } catch (error) {
+        fs.rmSync(claimPath, { force: true });
+        if (error?.code !== "EEXIST") {
+          if (published) {
+            try {
+              fs.writeFileSync(path.join(generationPath, `released-${nonce}`), `${nonce}\n`, {
+                mode: 0o600,
+                flag: "wx",
+              });
+            } catch {
+              // The published incomplete generation remains safely fenced.
+            }
+          } else {
+            try {
+              fs.rmSync(generationPath, { recursive: true, force: true });
+            } catch {
+              // Preserve the original construction failure.
+            }
+          }
+          throw error;
+        }
+        fs.rmSync(generationPath, { recursive: true, force: true });
+        const stat = fs.lstatSync(lockPath);
+        if (stat.isSymbolicLink()) throw new Error("refusing to use symlinked native-agent run lock");
+        let current = null;
+        let legacy = null;
+        if (stat.isFile()) {
+          try {
+            current = this.readClaimedLock(lockPath);
+          } catch (claimError) {
+            try {
+              legacy = this.readLegacyLockOwner(lockPath);
+            } catch {
+              if (this.now() - stat.mtimeMs <= leaseMs) throw claimError;
+            }
+          }
+          const released = current
+            && fs.existsSync(path.join(current.generationPath, `released-${current.owner.nonce}`));
+          if (current && !released && !this.lockIsStale(current.owner, current.stat.mtimeMs, leaseMs)) return null;
+          if (legacy && !this.lockIsStale(legacy.owner, legacy.stat.mtimeMs, leaseMs)) return null;
+        } else if (!stat.isDirectory()) {
+          throw new Error("native-agent run lock is unsafe or invalid");
+        } else if (this.now() - stat.mtimeMs <= leaseMs) {
+          // A pre-v2 interrupted directory is busy for one full lease, but it
+          // is never accepted as a valid owner generation.
+          return null;
+        }
+        const retiredPath = `${lockPath}.retired-${process.pid}-${nonce}`;
+        try {
+          fs.renameSync(lockPath, retiredPath);
+        } catch (error) {
+          if (error?.code === "ENOENT" || error?.code === "EEXIST") continue;
+          throw error;
+        }
+        let restored = false;
+        try {
+          if (current) {
+            try {
+              const retired = this.readClaimedLock(retiredPath);
+              const released = fs.existsSync(path.join(retired.generationPath, `released-${retired.owner.nonce}`));
+              if (!released && !this.lockIsStale(retired.owner, retired.stat.mtimeMs, leaseMs)) {
+                try {
+                  fs.linkSync(retiredPath, lockPath);
+                  restored = true;
+                } catch {
+                  // Another contender won; fencing makes the retired owner safe.
+                }
+                return null;
+              }
+            } catch {
+              // The claim was replaced between inspection and retirement.
+            }
+          }
+        } finally {
+          fs.rmSync(retiredPath, { recursive: true, force: true });
+          if (current && !restored) {
+            fs.rmSync(current.generationPath, { recursive: true, force: true });
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  prune(now = this.now(), { reserve = 0, guard = null } = {}) {
+    this.ensureRoots();
+    const retained = [];
+    for (const name of fs.readdirSync(this.tenantRoot)) {
+      guard?.();
+      if (!name.endsWith(".json")) continue;
+      const candidate = path.join(this.tenantRoot, name);
+      const stat = fs.lstatSync(candidate);
+      if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error("refusing to retain unsafe native-agent run state");
+      }
+      const invocationId = path.basename(candidate, ".json");
+      const state = this.readLatestState(invocationId, { allowMissing: true });
+      if (!state) {
+        // A tombstone is the durable deletion commit point. Interrupted
+        // physical cleanup and delayed stale files do not consume capacity.
+        this.cleanupTombstonedState(invocationId);
+        continue;
+      }
+      if (state.invocationId !== invocationId) {
+        throw new Error("native-agent run state failed integrity validation");
+      }
+      retained.push({
+        candidate,
+        invocationId,
+        terminal: TERMINAL_STATUSES.has(state.status),
+        updatedAt: Date.parse(state.updatedAt),
+      });
+    }
+    const terminalOldestFirst = retained
+      .filter((item) => item.terminal)
+      .sort((left, right) => left.updatedAt - right.updatedAt);
+    const removed = new Set();
+    const removeTerminal = (item) => {
+      guard?.();
+      const lock = this.acquireLock(item.invocationId);
+      if (!lock) return false;
+      try {
+        const current = this.readState(item.invocationId, lock);
+        if (!TERMINAL_STATUSES.has(current.status)) return false;
+        this.beforePruneDelete?.({ invocationId: item.invocationId, lock });
+        this.writeDeletionTombstone(item.invocationId, lock);
+        this.cleanupTombstonedState(item.invocationId);
+      } finally {
+        lock.release();
+      }
+      removed.add(item.candidate);
+      return true;
+    };
+    for (const item of terminalOldestFirst) {
+      if (now - item.updatedAt > this.retentionMs) removeTerminal(item);
+    }
+    let retainedCount = retained.length - removed.size;
+    for (const item of terminalOldestFirst) {
+      if (retainedCount + reserve <= this.maxRetainedRuns) break;
+      if (removed.has(item.candidate)) continue;
+      if (removeTerminal(item)) retainedCount -= 1;
+    }
+    if (retainedCount + reserve > this.maxRetainedRuns) {
+      throw new Error("native-agent run retention is full of resumable runs");
+    }
+    return retainedCount;
+  }
+
+  acquireLock(invocationId) {
+    if (this.readDeletionTombstone(invocationId)) {
+      throw new Error("native-agent run handle is unknown or expired");
+    }
+    return this.acquireLeaseDirectory(this.lockPath(invocationId), { invocationId });
+  }
+
+  acquireAdmissionLock() {
+    return this.acquireLeaseDirectory(this.admissionLockPath(), {
+      leaseMs: Math.max(DEFAULT_ADMISSION_LEASE_MS, this.lockLeaseMs),
+    });
+  }
+
+  persist(state, lock = null) {
+    if (lock) {
+      lock.assert();
+      this.writeRevision(state, lock);
+      return;
+    }
+    const initial = structuredClone(state);
+    if (this.readDeletionTombstone(initial.invocationId)
+      || fs.existsSync(this.statePath(initial.invocationId))
+      || fs.existsSync(this.stateVersionsPath(initial.invocationId))
+      || fs.existsSync(this.fenceVersionsPath(initial.invocationId))
+      || fs.existsSync(this.fencePath(initial.invocationId))) {
+      throw new Error("native-agent invocation id already exists");
+    }
+    initial.fence = 0;
+    initial.sequence = 0;
+    atomicPrivateWrite(this.statePath(initial.invocationId), initial, this.maxStateBytes);
+    replaceObject(state, initial);
+  }
+
+  readState(invocationId, lock = null) {
+    try {
+      lock?.assert();
+      return this.readLatestState(invocationId);
+    } catch (error) {
+      if (error?.code === "ENOENT") throw new Error("native-agent run handle is unknown or expired");
+      throw error;
+    }
+  }
+
+  validateBoundState(state, handle) {
+    const expected = {
+      tenantId: this.tenantId,
+      agentId: this.agentId,
+      scopeParam: this.scopeParam,
+    };
+    for (const [field, value] of Object.entries(expected)) {
+      if (state[field] !== value || handle[field] !== value) {
+        throw new Error("native-agent run handle does not match this fixed binding");
+      }
+    }
+    if (stableJson(handleForState(state)) !== stableJson(handle)) {
+      throw new Error("native-agent run handle was altered");
+    }
+  }
+
+  async prepareExistingSession(signal) {
+    const session = await this.sessionFactory({ signal });
+    const tools = await session.initialize();
+    return { session, waitSeconds: negotiateNativeAgentWaitSeconds(tools) };
+  }
+
+  async prepareNewSession(signal) {
+    const prepared = await this.prepareExistingSession(signal);
+    const catalog = normalizeNativeAgentCatalog(
+      await prepared.session.call(NATIVE_AGENT_LIST_TOOL, {}),
+      this.tenantId,
+    );
+    const matches = catalog.agents.filter((agent) =>
+      agent.agentId === this.agentId && agent.scopeParam === this.scopeParam
+    );
+    if (matches.length !== 1) throw new Error("exact native-agent binding is unavailable");
+    if (nativeAgentPolicyFingerprint(matches[0]) !== this.policyFingerprint) {
+      throw new Error("native-agent catalog policy fingerprint changed; synchronize agents again");
+    }
+    return { ...prepared, agent: matches[0] };
+  }
+
+  async preparePersistedStartSession(signal, state) {
+    const prepared = await this.prepareExistingSession(signal);
+    const catalog = normalizeNativeAgentCatalog(
+      await prepared.session.call(NATIVE_AGENT_LIST_TOOL, {}),
+      this.tenantId,
+    );
+    const matches = catalog.agents.filter((agent) =>
+      agent.agentId === state.agentId && agent.scopeParam === state.scopeParam
+    );
+    if (matches.length !== 1) {
+      const error = new Error("exact native-agent binding is unavailable; the persisted start was not retried");
+      error.code = "LOCAL_POLICY_CHANGED_BEFORE_START";
+      throw error;
+    }
+    if (nativeAgentPolicyFingerprint(matches[0]) !== state.policyFingerprint) {
+      const error = new Error("native-agent catalog policy fingerprint changed; the persisted start was not retried");
+      error.code = "LOCAL_POLICY_CHANGED_BEFORE_START";
+      throw error;
+    }
+    return prepared;
+  }
+
+  normalizeRunArguments(args, agent) {
+    exactObject(args, ["task", "context", "contextKeys"], "run_native_agent arguments");
+    const task = boundedString(args.task, "task", 40_000);
+    const keys = contextKeys(args.contextKeys);
+    const missing = agent.requiredContext.filter((key) => !keys.includes(key));
+    if (missing.length) throw new Error(`missing required context: ${missing.join(", ")}`);
+    if (args.context !== undefined) boundedString(args.context, "context", 40_000, { nonblank: false });
+    if (agent.requiredContext.length && (typeof args.context !== "string" || !args.context.trim())) {
+      throw new Error("nonblank context is required for this native agent");
+    }
+    return {
+      agentId: this.agentId,
+      scopeParam: this.scopeParam,
+      task,
+      ...(args.context !== undefined ? { context: args.context } : {}),
+      contextKeys: keys,
+      ...(agent.sideEffects === "writes" ? { confirmedSideEffects: true } : {}),
+    };
+  }
+
+  async run(args, { signal, onProgress } = {}) {
+    throwIfAborted(signal);
+    this.ensureRoots();
+    const attachment = boundedAttachmentSignal(signal, this.attachmentWindowMs);
+    let state = null;
+    let lock = null;
+    let admission = null;
+    try {
+      const prepared = await this.prepareNewSession(attachment.signal);
+      const startArguments = this.normalizeRunArguments(args, prepared.agent);
+      admission = this.acquireAdmissionLock();
+      if (!admission) throw new Error("native-agent run allocation is busy; retry without changing the request");
+      this.prune(this.now(), { reserve: 1, guard: () => admission.assert() });
+      admission.assert();
+      const invocationId = this.randomUUID();
+      const idempotencyKey = `impel-native-${this.randomBytes(24).toString("hex")}`;
+      startArguments.idempotencyKey = idempotencyKey;
+      const requestFingerprint = requestFingerprintFor({
+        tenantId: this.tenantId,
+        agentId: this.agentId,
+        scopeParam: this.scopeParam,
+        policyFingerprint: this.policyFingerprint,
+        startArguments,
+      });
+      const timestamp = new Date(this.now()).toISOString();
+      state = {
+        schema: STATE_SCHEMA,
+        invocationId,
+        tenantId: this.tenantId,
+        agentId: this.agentId,
+        scopeParam: this.scopeParam,
+        policyFingerprint: this.policyFingerprint,
+        requestFingerprint,
+        idempotencyKey,
+        startArguments,
+        upstreamRunId: null,
+        status: "starting",
+        startAttempts: 0,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      };
+      // The durable identity and exact retry arguments exist before the first
+      // upstream byte is sent.
+      this.persist(state);
+      admission.release();
+      admission = null;
+      lock = this.acquireLock(invocationId);
+      if (!lock) return handleForState(state);
+      return await this.attach(state, prepared, {
+        signal: attachment.signal,
+        onProgress,
+        lock,
+      });
+    } catch (error) {
+      // Once state exists, cancellation or the local attachment deadline must
+      // hand the caller the only handle that can resume it.
+      if (error?.name === "AbortError" && state) return handleForState(state);
+      if (error?.name === "AbortError" && attachment.timedOut()) {
+        throw new Error("native-agent attachment window elapsed before a resumable run was created");
+      }
+      throw error;
+    } finally {
+      admission?.release();
+      lock?.release();
+      attachment.dispose();
+    }
+  }
+
+  async resume(args, { signal, onProgress } = {}) {
+    exactObject(args, ["handle"], "resume_native_agent_run arguments");
+    if (!Object.hasOwn(args, "handle")) throw new Error("resume_native_agent_run requires a handle");
+    const handle = normalizeHandle(args.handle);
+    if (handle.tenantId !== this.tenantId) {
+      throw new Error("native-agent run handle does not match this fixed tenant");
+    }
+    this.ensureRoots();
+    throwIfAborted(signal);
+    const attachment = boundedAttachmentSignal(signal, this.attachmentWindowMs);
+    let lock = null;
+    let state = null;
+    let validated = false;
+    try {
+      lock = this.acquireLock(handle.invocationId);
+      if (!lock) return handle;
+      // The lock must precede the authoritative read. Another attachment may
+      // have completed the run after the caller obtained its stale snapshot.
+      state = this.readState(handle.invocationId, lock);
+      this.validateBoundState(state, handle);
+      validated = true;
+      if (state.status === "succeeded"
+        && (!state.result
+          || typeof state.result !== "object"
+          || Array.isArray(state.result)
+          || typeof state.result.finalText !== "string")) {
+        this.compactTerminalFailure(
+          state,
+          state,
+          "LOCAL_MALFORMED_TERMINAL_RESULT",
+          "The native-agent success payload did not contain a string finalText.",
+          lock,
+        );
+      }
+      const terminal = resultForState(state);
+      if (terminal.schema === NATIVE_AGENT_RESULT_SCHEMA) return terminal;
+      const prepared = state.upstreamRunId
+        ? await this.prepareExistingSession(attachment.signal)
+        : await this.preparePersistedStartSession(attachment.signal, state);
+      return await this.attach(state, prepared, {
+        signal: attachment.signal,
+        onProgress,
+        lock,
+      });
+    } catch (error) {
+      if (error?.name === "AbortError") return handle;
+      if (validated && !state?.upstreamRunId && error?.code === "LOCAL_POLICY_CHANGED_BEFORE_START") {
+        this.compactTerminalFailure(
+          state,
+          state,
+          error.code,
+          error.message,
+          lock,
+        );
+        return resultForState(state);
+      }
+      if (validated && state?.upstreamRunId) {
+        try {
+          this.persistDiagnostic(state, error, lock);
+        } catch {
+          // Never write after losing ownership of the bounded lease.
+        }
+        return handle;
+      }
+      throw error;
+    } finally {
+      lock?.release();
+      attachment.dispose();
+    }
+  }
+
+  recover(args = {}) {
+    exactObject(args, [], "recover_native_agent_runs arguments");
+    this.ensureRoots();
+    const states = [];
+    for (const name of fs.readdirSync(this.tenantRoot)) {
+      if (!name.endsWith(".json")) continue;
+      let state;
+      try {
+        const invocationId = path.basename(name, ".json");
+        state = this.readLatestState(invocationId);
+        if (state.invocationId !== invocationId) continue;
+      } catch {
+        // Recovery never returns an unvalidated or partially written handle.
+        continue;
+      }
+      if (state.tenantId !== this.tenantId
+        || state.agentId !== this.agentId
+        || state.scopeParam !== this.scopeParam
+        || TERMINAL_STATUSES.has(state.status)) {
+        continue;
+      }
+      states.push(state);
+    }
+    states.sort((left, right) => {
+      const byTime = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+      return byTime || left.invocationId.localeCompare(right.invocationId);
+    });
+    return {
+      schema: NATIVE_AGENT_RECOVERY_SCHEMA,
+      handles: states.slice(0, this.maxRecoveryResults).map(handleForState),
+    };
+  }
+
+  persistDiagnostic(state, error, lock) {
+    const next = structuredClone(state);
+    next.lastTransportError = diagnosticFor(error, state.idempotencyKey);
+    next.updatedAt = new Date(this.now()).toISOString();
+    try {
+      this.persist(next, lock);
+    } catch (persistError) {
+      if (!(persistError instanceof NativeAgentStateSizeError)) throw persistError;
+      // A near-limit nonterminal snapshot may sacrifice partial output so the
+      // durable identity and the actionable local diagnostic remain readable.
+      delete next.result;
+      delete next.output;
+      if (!TERMINAL_STATUSES.has(next.status)) delete next.error;
+      next.lastTransportError = {
+        message: String(next.lastTransportError?.message || "native-agent attachment failed").slice(0, 1_000),
+      };
+      this.persist(next, lock);
+    }
+    replaceObject(state, next);
+  }
+
+  compactTerminalFailure(state, next, code, message, lock) {
+    const compact = structuredClone(state);
+    if (next.upstreamRunId) compact.upstreamRunId = next.upstreamRunId;
+    compact.status = "failed";
+    delete compact.result;
+    delete compact.output;
+    compact.error = { code, message };
+    compact.lastTransportError = { message };
+    compact.updatedAt = new Date(this.now()).toISOString();
+    this.persist(compact, lock);
+    replaceObject(state, compact);
+  }
+
+  commitPayload(state, payload, lock) {
+    const next = structuredClone(state);
+    applyUpstreamPayload(next, payload, this.now());
+    delete next.lastTransportError;
+    if (next.status === "succeeded"
+      && (!next.result
+        || typeof next.result !== "object"
+        || Array.isArray(next.result)
+        || typeof next.result.finalText !== "string")) {
+      this.compactTerminalFailure(
+        state,
+        next,
+        "LOCAL_MALFORMED_TERMINAL_RESULT",
+        "The native-agent success payload did not contain a string finalText.",
+        lock,
+      );
+      return;
+    }
+    try {
+      this.persist(next, lock);
+    } catch (error) {
+      if (!TERMINAL_STATUSES.has(next.status)) throw error;
+      const oversized = error instanceof NativeAgentStateSizeError;
+      this.compactTerminalFailure(
+        state,
+        next,
+        oversized ? "LOCAL_RESULT_TOO_LARGE" : "LOCAL_TERMINAL_PERSISTENCE_REJECTED",
+        oversized
+          ? "The terminal native-agent result exceeded the local durable-state limit."
+          : "The terminal native-agent result was rejected by local persistence safety checks.",
+        lock,
+      );
+      return;
+    }
+    replaceObject(state, next);
+  }
+
+  persistStartedIdentity(state, payload, lock) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("native-agent upstream returned an invalid run");
+    }
+    const runId = boundedString(payload.runId, "native-agent runId", 512);
+    const next = structuredClone(state);
+    next.upstreamRunId = runId;
+    next.status = typeof payload.status === "string"
+      && payload.status.length <= 160
+      && payload.status
+      && !TERMINAL_STATUSES.has(payload.status)
+      ? payload.status
+      : "queued";
+    next.updatedAt = new Date(this.now()).toISOString();
+    delete next.lastTransportError;
+    this.persist(next, lock);
+    replaceObject(state, next);
+  }
+
+  async attach(state, { session, waitSeconds }, { signal, onProgress, lock } = {}) {
+    const deadline = this.now() + this.attachmentWindowMs;
+    try {
+      throwIfAborted(signal);
+      if (!state.upstreamRunId) {
+        let started = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+          state.startAttempts += 1;
+          state.updatedAt = new Date(this.now()).toISOString();
+          this.persist(state, lock);
+          try {
+            started = await session.call(NATIVE_AGENT_START_TOOL, state.startArguments);
+            break;
+          } catch (error) {
+            if (error?.name === "AbortError") throw error;
+            if (!error?.ambiguous) {
+              const diagnostic = diagnosticFor(error, state.idempotencyKey);
+              throw new NativeAgentUpstreamError(String(diagnostic.message), {
+                code: diagnostic.code,
+                data: diagnostic.data,
+              });
+            }
+            this.persistDiagnostic(state, error, lock);
+          }
+        }
+        if (!started) return handleForState(state);
+
+        // Persist the upstream identity before accepting any optional or large
+        // response fields. From this point every attachment failure is safely
+        // recoverable without another start call.
+        this.persistStartedIdentity(state, started, lock);
+        this.commitPayload(state, started, lock);
+        onProgress?.({ status: state.status, runId: state.upstreamRunId });
+      }
+
+      let result = resultForState(state);
+      if (result.schema === NATIVE_AGENT_RESULT_SCHEMA) return result;
+      for (let poll = 0; poll < this.maxPolls; poll += 1) {
+        throwIfAborted(signal);
+        const remainingMs = deadline - this.now();
+        if (remainingMs <= 1_500) return handleForState(state);
+        const boundedWait = Math.max(1, Math.min(waitSeconds, Math.floor((remainingMs - 1_000) / 1000)));
+        const observed = await session.call(NATIVE_AGENT_READ_TOOL, {
+          runId: state.upstreamRunId,
+          waitSeconds: boundedWait,
+        });
+        this.commitPayload(state, observed, lock);
+        onProgress?.({ status: state.status, runId: state.upstreamRunId, poll: poll + 1 });
+        result = resultForState(state);
+        if (result.schema === NATIVE_AGENT_RESULT_SCHEMA) return result;
+      }
+      return handleForState(state);
+    } catch (error) {
+      if (!state.upstreamRunId) throw error;
+      try {
+        this.persistDiagnostic(state, error, lock);
+      } catch {
+        // A lost lease forbids stale writes. The already-persisted handle is
+        // still the only safe return value.
+      }
+      return handleForState(state);
+    }
+  }
+}
+
+const HANDLE_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "schema",
+    "tenantId",
+    "agentId",
+    "scopeParam",
+    "policyFingerprint",
+    "invocationId",
+    "requestFingerprint",
+  ],
+  properties: {
+    schema: { type: "string", const: NATIVE_AGENT_HANDLE_SCHEMA },
+    tenantId: { type: "string" },
+    agentId: { type: "string" },
+    scopeParam: { type: "string" },
+    policyFingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    invocationId: { type: "string" },
+    requestFingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
+  },
+};
+
+export function nativeAgentCompositeTools({ recoveryOnly = false } = {}) {
+  const tools = [
+    {
+      name: NATIVE_AGENT_RUN_TOOL,
+      description: "Start the one native agent fixed by this MCP server and remain attached for a bounded interval.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["task"],
+        properties: {
+          task: { type: "string", minLength: 1, maxLength: 40_000 },
+          context: { type: "string", maxLength: 40_000 },
+          contextKeys: {
+            type: "array",
+            maxItems: 30,
+            uniqueItems: true,
+            items: { type: "string", minLength: 1, maxLength: 160 },
+          },
+        },
+      },
+    },
+    {
+      name: NATIVE_AGENT_RESUME_TOOL,
+      description: "Resume only the durable native-agent invocation identified by the supplied typed handle.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["handle"],
+        properties: { handle: HANDLE_SCHEMA },
+      },
+    },
+    {
+      name: NATIVE_AGENT_RECOVER_TOOL,
+      description: "Recover bounded, integrity-validated pending handles for this MCP server's fixed native-agent binding.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {},
+      },
+    },
+  ];
+  return recoveryOnly ? tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL) : tools;
+}
+
+export function nativeAgentToolCallResult(value) {
+  if (value?.schema === NATIVE_AGENT_RESULT_SCHEMA && value.status === "succeeded") {
+    return {
+      content: [{ type: "text", text: value.finalText }],
+      structuredContent: value,
+    };
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    structuredContent: value,
+  };
+}