impel-cli 0.20.0 → 0.20.2-beta.0

package/src/agents.js

@@ -9,8 +9,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { normalizeGatewayUrl, redactSecretText } from "./config.js";
-import { impelMcpInvocation } from "./selfInvocation.js";
+import {
+  CONFIG_DIR,
+  normalizeGatewayUrl,
+  redactCredentialText,
+  redactSecretText,
+} from "./config.js";
+import {
+  IMPEL_NATIVE_AGENT_MCP_TARGET,
+  impelNativeAgentMcpInvocation,
+} from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 
@@ -20,14 +28,21 @@ export const MANAGED_AGENT_MANIFEST = ".manifest.json";
 export const NATIVE_AGENT_LIST_TOOL = "impel_specialists-list_native_agents";
 export const NATIVE_AGENT_START_TOOL = "impel_specialists-start_native_agent_run";
 export const NATIVE_AGENT_READ_TOOL = "impel_specialists-read_native_agent_run";
+export const NATIVE_AGENT_RUN_TOOL = "run_native_agent";
+export const NATIVE_AGENT_RESUME_TOOL = "resume_native_agent_run";
+export const NATIVE_AGENT_RECOVER_TOOL = "recover_native_agent_runs";
 export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
-export const MANAGED_AGENT_MANIFEST_VERSION = 4;
+export const MANAGED_AGENT_MANIFEST_VERSION = 6;
 
 const NATIVE_AGENT_TOOL_NAMES = [
-  NATIVE_AGENT_LIST_TOOL,
-  NATIVE_AGENT_START_TOOL,
-  NATIVE_AGENT_READ_TOOL,
+  NATIVE_AGENT_RUN_TOOL,
+  NATIVE_AGENT_RESUME_TOOL,
+  NATIVE_AGENT_RECOVER_TOOL,
 ];
+const NATIVE_AGENT_RECOVERY_TOOL_NAMES = [NATIVE_AGENT_RESUME_TOOL, NATIVE_AGENT_RECOVER_TOOL];
+const MAX_RETIRED_AGENT_BINDINGS = 50;
+const MAX_NATIVE_AGENT_STATE_BYTES = 512 * 1024;
+const TERMINAL_NATIVE_AGENT_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
 const SAFE_AGENT_ID_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const SAFE_SCOPE_PARAM_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 const MAX_CATALOG_ITEMS = 500;
@@ -284,6 +299,222 @@ function agentBindingHash(agent) {
     .slice(0, 8);
 }
 
+function stablePolicyValue(value) {
+  if (Array.isArray(value)) return value.map(stablePolicyValue);
+  if (!value || typeof value !== "object") return value;
+  const result = {};
+  for (const key of Object.keys(value).sort()) result[key] = stablePolicyValue(value[key]);
+  return result;
+}
+
+/** Fingerprint the complete synchronized routing and side-effect policy. */
+export function nativeAgentPolicyFingerprint(agent) {
+  return crypto.createHash("sha256")
+    .update(JSON.stringify(stablePolicyValue(agent)))
+    .digest("hex");
+}
+
+function validatedPendingState(filePath, invocationId) {
+  let serialized;
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_NATIVE_AGENT_STATE_BYTES) {
+      throw new Error("unsafe state file");
+    }
+    serialized = fs.readFileSync(filePath, "utf8");
+  } catch {
+    throw new Error("native-agent run state is unsafe or invalid during profile sync");
+  }
+  if (redactCredentialText(serialized) !== serialized) {
+    throw new Error("native-agent run state is unsafe or invalid during profile sync");
+  }
+  let state;
+  try {
+    state = JSON.parse(serialized);
+  } catch {
+    throw new Error("native-agent run state is invalid during profile sync");
+  }
+  let stateTenant;
+  try {
+    stateTenant = normalizeTenantId(state?.tenantId);
+  } catch {
+    throw new Error("native-agent run state failed integrity validation during profile sync");
+  }
+  const allowed = new Set([
+    "schema", "invocationId", "tenantId", "agentId", "scopeParam", "policyFingerprint",
+    "requestFingerprint", "idempotencyKey", "startArguments", "upstreamRunId", "status",
+    "startAttempts", "createdAt", "updatedAt", "fence", "sequence", "lastTransportError",
+    "result", "output", "error",
+  ]);
+  if (!state || typeof state !== "object" || Array.isArray(state)
+    || Object.keys(state).some((key) => !allowed.has(key))
+    || state.schema !== "impel.native-agent-state.v1"
+    || state.invocationId !== invocationId
+    || !/^[a-f0-9-]{36}$/u.test(state.invocationId)
+    || stateTenant !== state.tenantId
+    || !SAFE_AGENT_ID_RE.test(state.agentId)
+    || !SAFE_SCOPE_PARAM_RE.test(state.scopeParam)
+    || !/^[a-f0-9]{64}$/u.test(state.policyFingerprint)
+    || !/^[a-f0-9]{64}$/u.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("native-agent run state failed integrity validation during profile sync");
+  }
+  const args = state.startArguments;
+  const allowedArgs = new Set([
+    "agentId", "scopeParam", "task", "context", "contextKeys", "confirmedSideEffects", "idempotencyKey",
+  ]);
+  if (!args || typeof args !== "object" || Array.isArray(args)
+    || Object.keys(args).some((key) => !allowedArgs.has(key))
+    || args.agentId !== state.agentId
+    || args.scopeParam !== state.scopeParam
+    || args.idempotencyKey !== state.idempotencyKey
+    || typeof args.task !== "string"
+    || !args.task.trim()
+    || args.task.length > 40_000
+    || (args.context !== undefined && (typeof args.context !== "string" || args.context.length > 40_000))
+    || !Array.isArray(args.contextKeys)
+    || args.contextKeys.length > 30
+    || args.contextKeys.some((key) => typeof key !== "string" || !key.trim() || key.length > 160)
+    || new Set(args.contextKeys).size !== args.contextKeys.length
+    || (args.confirmedSideEffects !== undefined && typeof args.confirmedSideEffects !== "boolean")) {
+    throw new Error("native-agent run state failed integrity validation during profile sync");
+  }
+  const fingerprint = crypto.createHash("sha256").update(JSON.stringify(stablePolicyValue({
+    tenantId: state.tenantId,
+    agentId: state.agentId,
+    scopeParam: state.scopeParam,
+    policyFingerprint: state.policyFingerprint,
+    arguments: args,
+  }))).digest("hex");
+  if (fingerprint !== state.requestFingerprint) {
+    throw new Error("native-agent run state failed integrity validation during profile sync");
+  }
+  return state;
+}
+
+function hasNativeAgentDeletionTombstone(tenantRoot, invocationId) {
+  const tombstonePath = path.join(tenantRoot, `${invocationId}.tombstone`);
+  if (!fs.existsSync(tombstonePath)) return false;
+  const stat = fs.lstatSync(tombstonePath);
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) {
+    throw new Error("native-agent deletion tombstone is unsafe or invalid during profile sync");
+  }
+  let tombstone;
+  try {
+    tombstone = JSON.parse(fs.readFileSync(tombstonePath, "utf8"));
+  } catch {
+    throw new Error("native-agent deletion tombstone is invalid during profile sync");
+  }
+  const allowed = new Set(["schema", "invocationId", "fence", "deletedAt"]);
+  if (!tombstone
+    || typeof tombstone !== "object"
+    || Array.isArray(tombstone)
+    || Object.keys(tombstone).some((key) => !allowed.has(key))
+    || tombstone.schema !== "impel.native-agent-deletion.v1"
+    || 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 during profile sync");
+  }
+  return true;
+}
+
+/** Discover only pending bindings from the highest valid fenced state revision. */
+export function pendingNativeAgentBindings(tenantId, {
+  runsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
+} = {}) {
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const tenantRoot = path.join(runsRoot, normalizedTenant);
+  if (!fs.existsSync(tenantRoot)) return [];
+  const rootStat = fs.lstatSync(tenantRoot);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new Error("native-agent run directory is unsafe or invalid");
+  }
+  const bindings = new Map();
+  for (const name of fs.readdirSync(tenantRoot)) {
+    if (!/^[a-f0-9-]{36}\.json$/u.test(name)) continue;
+    const invocationId = path.basename(name, ".json");
+    if (hasNativeAgentDeletionTombstone(tenantRoot, invocationId)) continue;
+    const candidates = [{ filePath: path.join(tenantRoot, name), expected: null }];
+    const versionsPath = path.join(tenantRoot, `${invocationId}.state-versions`);
+    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 during profile sync");
+      }
+      for (const revision of fs.readdirSync(versionsPath)) {
+        if (!revision.endsWith(".json")) continue;
+        const match = /^(\d{16})-(\d{16})-[a-f0-9]{32}\.json$/u.exec(revision);
+        const expected = match ? [Number(match[1]), Number(match[2])] : null;
+        if (!match
+          || path.basename(revision) !== revision
+          || !expected.every(Number.isSafeInteger)) {
+          throw new Error("native-agent state revision is invalid during profile sync");
+        }
+        candidates.push({
+          filePath: path.join(versionsPath, revision),
+          expected,
+        });
+      }
+    }
+    let latest = null;
+    for (const candidate of candidates) {
+      const state = validatedPendingState(candidate.filePath, invocationId);
+      if (state.tenantId !== normalizedTenant) {
+        throw new Error("native-agent run state failed tenant validation during profile sync");
+      }
+      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 during profile sync");
+      }
+      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]
+        && JSON.stringify(stablePolicyValue(state)) !== JSON.stringify(stablePolicyValue(latest.state))) {
+        throw new Error("native-agent state revisions conflict during profile sync");
+      }
+    }
+    if (!latest || TERMINAL_NATIVE_AGENT_STATUSES.has(latest.state.status)) continue;
+    const state = latest.state;
+    const key = `${state.agentId}\0${state.scopeParam}\0${state.policyFingerprint}`;
+    const prior = bindings.get(key);
+    if (!prior || Date.parse(state.updatedAt) > Date.parse(prior.updatedAt)) {
+      bindings.set(key, {
+        agentId: state.agentId,
+        scopeParam: state.scopeParam,
+        policyFingerprint: state.policyFingerprint,
+        updatedAt: state.updatedAt,
+      });
+    }
+  }
+  const result = [...bindings.values()].sort((left, right) =>
+    Date.parse(right.updatedAt) - Date.parse(left.updatedAt)
+      || left.agentId.localeCompare(right.agentId)
+      || left.scopeParam.localeCompare(right.scopeParam)
+  );
+  if (result.length > MAX_RETIRED_AGENT_BINDINGS) {
+    throw new Error("too many pending native-agent bindings to preserve recovery adapters");
+  }
+  return result;
+}
+
 function generatedAgentFileStems(tenantId, agents) {
   const used = new Map();
   return agents.map((agent) => {
@@ -322,21 +553,20 @@ function generatedClientAgentNames(client, agents) {
 }
 
 function claudeAdapterInstructions(tenantId, agent) {
-  const toolName = nativeToolName;
   const contextRequirement = agent.requiredContext.length
     ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
     : "";
   const sideEffectInstruction = agent.sideEffects === "writes"
-    ? `The catalog declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request; that explicit selection is the required side-effect confirmation, so pass confirmedSideEffects true. If the agent was chosen automatically or the selection is ambiguous, do not start it and ask the user to select it explicitly.`
-    : `The catalog declares that this agent is read-only; omit confirmedSideEffects.`;
+    ? `The synchronized policy declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request. If the agent was chosen automatically or the selection is ambiguous, do not start it and ask the user to select it explicitly.`
+    : `The synchronized policy declares that this agent is read-only.`;
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
     `Do not perform the assigned task yourself and do not delegate to any other agent.`,
-    `First call ${toolName(NATIVE_AGENT_LIST_TOOL)} and verify that the exact agentId is still available with sideEffects ${JSON.stringify(agent.sideEffects)}. If it is unavailable or its policy excludes the request, stop with that explicit error.`,
+    `Confirm that the request fits the synchronized capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)}.${contextRequirement}`,
     sideEffectInstruction,
-    `Call ${toolName(NATIVE_AGENT_START_TOOL)} exactly once with agentId ${JSON.stringify(agent.agentId)}, scopeParam ${JSON.stringify(agent.scopeParam)}, task set to the complete assigned task, optional context set to one string containing all supplied context (omit it when no context was supplied), contextKeys naming the context fields present in that string, confirmedSideEffects as directed above, and one stable idempotencyKey that you reuse for this logical task.${contextRequirement}`,
-    `Then call ${toolName(NATIVE_AGENT_READ_TOOL)} with the returned runId and waitSeconds 20 until the run reaches a terminal state.`,
-    `When it succeeds, return result.finalText faithfully as the answer. When it fails, return the durable runId, preserved output, and error. Never invent or independently synthesize a replacement result.`,
+    `Call ${nativeToolName(NATIVE_AGENT_RUN_TOOL)} exactly once with task set to the complete assigned task, optional context set to one string containing all supplied context, and contextKeys naming the fields present in that string.`,
+    `If that call returns an ${JSON.stringify("impel.native-agent-run.v1")} handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that same handle until the transport returns a terminal result. If the call is cancelled, the connection closes, or its result is unknown before you receive a handle, call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} and resume the newest returned pending handle; if multiple handles cannot be safely associated with this request, report them instead of choosing. Never call run_native_agent again for this request, and never restart, nudge, replace, or independently poll the upstream run.`,
+    `When it succeeds, return finalText byte-for-byte as the answer with no preface or rewriting. When it fails, return the preserved runId, output, and error. Never invent or independently synthesize a replacement result.`,
   ].join(" ");
 }
 
@@ -344,179 +574,46 @@ function nativeToolName(toolName) {
   return `mcp__${MANAGED_AGENT_MCP_SERVER}__${toolName}`;
 }
 
-const CODEX_TASK_PLACEHOLDER = "__IMPEL_COMPLETE_ASSIGNED_TASK_JSON__";
-const CODEX_CONTEXT_PLACEHOLDER = "__IMPEL_OPTIONAL_CONTEXT_STRING_OR_NULL_JSON__";
-const CODEX_CONTEXT_KEYS_PLACEHOLDER = "__IMPEL_SUPPLIED_CONTEXT_KEYS_JSON__";
-const CODEX_IDEMPOTENCY_KEY_PLACEHOLDER = "__IMPEL_LOGICAL_INVOCATION_IDEMPOTENCY_KEY_JSON__";
-
-export function renderCodexAdapterOrchestration(tenantId, agent) {
-  const expectedTenantId = normalizeTenantId(tenantId);
-  const nestedToolName = (toolName) => nativeToolName(toolName).replaceAll("-", "_");
-  const listTool = nestedToolName(NATIVE_AGENT_LIST_TOOL);
-  const startTool = nestedToolName(NATIVE_AGENT_START_TOOL);
-  const readTool = nestedToolName(NATIVE_AGENT_READ_TOOL);
-  return [
-    '// @exec: {"yield_time_ms": 30000, "max_output_tokens": 30000}',
-    `const assignedTask = ${CODEX_TASK_PLACEHOLDER};`,
-    `const suppliedContext = ${CODEX_CONTEXT_PLACEHOLDER};`,
-    `const suppliedContextKeys = ${CODEX_CONTEXT_KEYS_PLACEHOLDER};`,
-    `const idempotencyKey = ${CODEX_IDEMPOTENCY_KEY_PLACEHOLDER};`,
-    `const expectedTenantId = ${JSON.stringify(expectedTenantId)};`,
-    `const expectedAgent = ${JSON.stringify(agent)};`,
-    "const waitSeconds = 20; // Compatible fallback until the bound server advertises a larger ceiling.",
-    `const listToolName = ${JSON.stringify(listTool)};`,
-    `const startToolName = ${JSON.stringify(startTool)};`,
-    `const readToolName = ${JSON.stringify(readTool)};`,
-    "",
-    "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 contentText(response) {",
-    '  return response?.content?.find((item) => item?.type === "text" && typeof item.text === "string")?.text;',
-    "}",
-    "",
-    "function toolPayload(response, label) {",
-    '  if (!response || typeof response !== "object") throw new Error(label + " returned no result");',
-    '  if (response.isError) throw new Error(contentText(response) || label + " failed");',
-    '  if (response.structuredContent && typeof response.structuredContent === "object") return response.structuredContent;',
-    "  const serialized = contentText(response);",
-    "  if (serialized !== undefined) {",
-    "    try {",
-    "      return JSON.parse(serialized);",
-    "    } catch {",
-    '      throw new Error(label + " returned invalid JSON");',
-    "    }",
-    "  }",
-    "  return response;",
-    "}",
-    "",
-    "function preservedOutput(run) {",
-    '  if (run && Object.prototype.hasOwnProperty.call(run, "output")) return run.output;',
-    '  if (run && Object.prototype.hasOwnProperty.call(run, "result")) return run.result;',
-    "  return null;",
-    "}",
-    "",
-    "function errorValue(error, fallback) {",
-    "  if (error === undefined || error === null) return fallback;",
-    '  if (error instanceof Error) return error.message;',
-    "  return error;",
-    "}",
-    "",
-    "async function orchestrate() {",
-    "  let runId = null;",
-    "  let latestRun = null;",
-    "  try {",
-    '    if (typeof assignedTask !== "string" || !assignedTask.trim()) throw new Error("the complete assigned task is required");',
-    '    if (suppliedContext !== null && typeof suppliedContext !== "string") throw new Error("supplied context must be a string or null");',
-    '    if (expectedAgent.requiredContext.length && (typeof suppliedContext !== "string" || !suppliedContext.trim())) {',
-    '      throw new Error("nonblank supplied context is required for required context keys");',
-    "    }",
-    '    if (!Array.isArray(suppliedContextKeys)) throw new Error("supplied context keys must be an array");',
-    '    if (typeof idempotencyKey !== "string" || !/^[A-Za-z0-9._:-]{16,160}$/u.test(idempotencyKey)) {',
-    '      throw new Error("a unique stable logical-invocation idempotencyKey is required");',
-    "    }",
-    "    const missingContext = expectedAgent.requiredContext.filter((key) =>",
-    "      !suppliedContextKeys.includes(key)",
-    "    );",
-    '    if (missingContext.length) throw new Error("missing required context: " + missingContext.join(", "));',
-    "",
-    "    const catalog = toolPayload(await tools[listToolName]({}), \"native-agent catalog\");",
-    '    if (catalog.orgId !== expectedTenantId) throw new Error("native-agent catalog tenant mismatch");',
-    '    if (!Array.isArray(catalog.agents)) throw new Error("native-agent catalog returned no agents");',
-    "    const matches = catalog.agents.filter((candidate) =>",
-    "      candidate?.agentId === expectedAgent.agentId && candidate?.scopeParam === expectedAgent.scopeParam",
-    "    );",
-    '    if (matches.length !== 1) throw new Error("exact native-agent binding is unavailable");',
-    "    const actualAgent = {};",
-    "    for (const key of Object.keys(expectedAgent)) actualAgent[key] = matches[0][key];",
-    "    if (JSON.stringify(stableValue(actualAgent)) !== JSON.stringify(stableValue(expectedAgent))) {",
-    '      throw new Error("native-agent catalog policy mismatch");',
-    "    }",
-    "",
-    "    const startArguments = {",
-    "      agentId: expectedAgent.agentId,",
-    "      scopeParam: expectedAgent.scopeParam,",
-    "      task: assignedTask,",
-    "      contextKeys: suppliedContextKeys,",
-    "      idempotencyKey,",
-    "    };",
-    "    if (suppliedContext !== null) startArguments.context = suppliedContext;",
-    '    if (expectedAgent.sideEffects === "writes") startArguments.confirmedSideEffects = true;',
-    "    latestRun = toolPayload(await tools[startToolName](startArguments), \"native-agent start\");",
-    '    if (typeof latestRun.runId !== "string" || !latestRun.runId) throw new Error("native-agent start returned no runId");',
-    "    runId = latestRun.runId;",
-    "",
-    "    for (;;) {",
-    "      const observed = toolPayload(",
-    "        await tools[readToolName]({ runId, waitSeconds }),",
-    '        "native-agent read",',
-    "      );",
-    '      if (observed.runId !== undefined && observed.runId !== runId) throw new Error("native-agent read returned a different runId");',
-    "      latestRun = observed;",
-    '      if (observed.status === "succeeded") {',
-    '        const finalText = observed.result?.finalText;',
-    '        if (typeof finalText !== "string") throw new Error("succeeded native-agent run returned no finalText");',
-    "        text(finalText);",
-    "        return;",
-    "      }",
-    '      if (observed.status === "failed") {',
-    "        text(JSON.stringify({",
-    "          runId,",
-    "          output: preservedOutput(observed),",
-    '          error: errorValue(observed.error, "native-agent run failed"),',
-    "        }));",
-    "        return;",
-    "      }",
-    "    }",
-    "  } catch (error) {",
-    "    text(JSON.stringify({",
-    "      runId,",
-    "      output: preservedOutput(latestRun),",
-    '      error: errorValue(error, "native-agent adapter failed"),',
-    "    }));",
-    "  }",
-    "}",
-    "",
-    "await orchestrate();",
-  ].join("\n");
-}
-
 function codexAdapterInstructions(tenantId, agent) {
   const contextRequirement = agent.requiredContext.length
     ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
     : "";
   const sideEffectInstruction = agent.sideEffects === "writes"
-    ? `The catalog declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request; that explicit selection is the required side-effect confirmation. If the agent was chosen automatically or the selection is ambiguous, do not run the orchestration and ask the user to select this exact agent explicitly.`
-    : `The catalog declares that this agent is read-only; the orchestration omits confirmedSideEffects.`;
-  const source = renderCodexAdapterOrchestration(tenantId, agent);
+    ? `The synchronized policy declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request. If the agent was chosen automatically or the selection is ambiguous, ask the user to select this exact agent explicitly.`
+    : `The synchronized policy declares that this agent is read-only.`;
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
     `Callers must spawn this explicit custom Codex agent with fork_turns="none" and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior.`,
     `Do not perform the assigned task yourself, do not delegate to any other agent, and do not independently synthesize or rewrite the result.`,
     `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before starting.${contextRequirement}`,
     sideEffectInstruction,
-    `Invoke functions.exec exactly once for the orchestration below. Do not call the MCP tools directly or select a separate MCP call for any poll. Replace ${CODEX_TASK_PLACEHOLDER} with a JSON string literal for the complete assigned task. Replace ${CODEX_CONTEXT_PLACEHOLDER} with one JSON string literal containing all supplied caller context, or with null when no context was supplied; never use an object or array. Replace ${CODEX_CONTEXT_KEYS_PLACEHOLDER} with a JSON array naming the context fields present in that string, or [] when context is absent. Replace ${CODEX_IDEMPOTENCY_KEY_PLACEHOLDER} with one new opaque idempotency key for this logical invocation: choose it exactly once, reuse it unchanged for any retry of this invocation, and never reuse it for a separate request even when task and context are identical. Then pass the raw JavaScript without Markdown fences.`,
-    `The JavaScript validates the exact tenant, agent binding, and catalog policy; passes the one stable logical-invocation idempotencyKey; starts exactly once; and polls deterministically with the compatible 20-second server wait until status is succeeded or failed. If functions.exec yields a running cell, use functions.wait with max_tokens 30000 only to resume that same orchestration; never start another orchestration or poll the MCP tool yourself.`,
-    `After the orchestration completes, return its single text output verbatim with no preface, rewriting, Markdown changes, or independent synthesis. A successful output is result.finalText exactly. A failure output preserves the durable runId, output, and error.`,
-    "",
-    source,
+    `Call ${nativeToolName(NATIVE_AGENT_RUN_TOOL)} exactly once with the complete task, optional context string, and supplied context keys. If it returns an ${JSON.stringify("impel.native-agent-run.v1")} handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that same handle until the transport returns a terminal result. If the call is cancelled, the connection closes, or its result is unknown before you receive a handle, call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} and resume the newest returned pending handle; if multiple handles cannot be safely associated with this request, report them instead of choosing. Never call run_native_agent again for this request, and never restart, nudge, replace, or independently poll the upstream run.`,
+    `While a remote wait is healthy, the parent must not message, follow up with, or interrupt this adapter.`,
+    `Return successful finalText byte-for-byte with no preface, rewriting, Markdown changes, or independent synthesis. A failure preserves the durable runId, output, and error.`,
   ].join("\n\n");
 }
 
-function renderClaudeAgent({ tenantId, agent, name, invocation }) {
-  const description = `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
+function retiredAdapterInstructions(tenantId, agent) {
+  return [
+    `You are a recovery-only transport adapter for retired Impel native-agent binding ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+    `You cannot start new work. Never call run_native_agent and never perform or recreate the assigned task yourself.`,
+    `Call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} to obtain integrity-validated pending handles for this fixed binding, then call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with the intended handle until it returns a terminal result. If multiple handles cannot be safely associated with the request, report them instead of choosing.`,
+    `Return successful finalText byte-for-byte. For failure, return the preserved runId, output, and error without inventing a replacement result.`,
+  ].join(" ");
+}
+
+function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
+  const description = recoveryOnly
+    ? `Recovery-only access to pending runs for retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
+    : `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
+  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : NATIVE_AGENT_TOOL_NAMES;
   const lines = [
     "---",
     `name: ${JSON.stringify(name)}`,
     `description: ${JSON.stringify(description)}`,
     "model: inherit",
     "tools:",
-    ...NATIVE_AGENT_TOOL_NAMES.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
+    ...toolNames.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
     "mcpServers:",
     `  - ${MANAGED_AGENT_MCP_SERVER}:`,
     "      type: stdio",
@@ -527,14 +624,17 @@ function renderClaudeAgent({ tenantId, agent, name, invocation }) {
     ...Object.entries(invocation.env || {}).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
     "---",
     "",
-    claudeAdapterInstructions(tenantId, agent),
+    recoveryOnly ? retiredAdapterInstructions(tenantId, agent) : claudeAdapterInstructions(tenantId, agent),
     "",
   ];
   return lines.join("\n");
 }
 
-function renderCodexAgent({ tenantId, agent, name, invocation }) {
-  const description = `Explicit custom agent: callers must use fork_turns="none" and relay its result verbatim. Runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
+function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
+  const description = recoveryOnly
+    ? `Recovery-only custom agent for pending runs from retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
+    : `Explicit custom agent: callers must use fork_turns="none" and relay its result verbatim. Runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
+  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : NATIVE_AGENT_TOOL_NAMES;
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
@@ -542,22 +642,51 @@ function renderCodexAgent({ tenantId, agent, name, invocation }) {
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
     'sandbox_mode = "read-only"',
-    `developer_instructions = ${JSON.stringify(codexAdapterInstructions(tenantId, agent))}`,
+    `developer_instructions = ${JSON.stringify(recoveryOnly ? retiredAdapterInstructions(tenantId, agent) : codexAdapterInstructions(tenantId, agent))}`,
     "",
     `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
     `command = ${JSON.stringify(invocation.command)}`,
     `args = [${invocation.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
-    `enabled_tools = [${NATIVE_AGENT_TOOL_NAMES.map((tool) => JSON.stringify(tool)).join(", ")}]`,
+    `enabled_tools = [${toolNames.map((tool) => JSON.stringify(tool)).join(", ")}]`,
     ...(envEntries ? [`env = { ${envEntries} }`] : []),
     "",
   ];
-  for (const tool of NATIVE_AGENT_TOOL_NAMES) {
+  for (const tool of toolNames) {
     lines.push(`[mcp_servers.${MANAGED_AGENT_MCP_SERVER}.tools.${JSON.stringify(tool)}]`, 'approval_mode = "approve"', "");
   }
   return lines.join("\n");
 }
 
-export function renderManagedAgents(client, tenantId, agents, invocation = impelMcpInvocation(["--tenant", tenantId])) {
+function boundNativeAgentInvocation(tenantId, agent, invocation, {
+  policyFingerprint = nativeAgentPolicyFingerprint(agent),
+  recoveryOnly = false,
+} = {}) {
+  if (!invocation) {
+    return impelNativeAgentMcpInvocation({
+      tenantId,
+      agentId: agent.agentId,
+      scopeParam: agent.scopeParam,
+      policyFingerprint,
+      recoveryOnly,
+    });
+  }
+  const mcpIndex = invocation.args?.lastIndexOf("mcp") ?? -1;
+  if (mcpIndex < 0) throw new Error("native-agent MCP invocation has no mcp command");
+  return {
+    ...invocation,
+    args: [
+      ...invocation.args.slice(0, mcpIndex + 1),
+      "--target", IMPEL_NATIVE_AGENT_MCP_TARGET,
+      "--tenant", tenantId,
+      "--agent-id", agent.agentId,
+      "--scope-param", agent.scopeParam,
+      "--policy-fingerprint", policyFingerprint,
+      ...(recoveryOnly ? ["--recovery-only"] : []),
+    ],
+  };
+}
+
+export function renderManagedAgents(client, tenantId, agents, invocation = null) {
   if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
   const normalizedTenant = normalizeTenantId(tenantId);
   const fileStems = generatedAgentFileStems(normalizedTenant, agents);
@@ -571,10 +700,73 @@ export function renderManagedAgents(client, tenantId, agents, invocation = impel
     // builtin and remove it from the @ mention picker. Claude names are already
     // collision-safe, filesystem-safe identifiers, so use them as filenames.
     const fileStem = client === "claude" ? name : fileStems[index];
+    const boundInvocation = boundNativeAgentInvocation(normalizedTenant, agent, invocation);
     const contents = client === "claude"
-      ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation })
-      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation });
-    return { agentId: agent.agentId, name, fileName: `${fileStem}${extension}`, contents };
+      ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation })
+      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation });
+    return {
+      agentId: agent.agentId,
+      scopeParam: agent.scopeParam,
+      policyFingerprint: nativeAgentPolicyFingerprint(agent),
+      retired: false,
+      name,
+      fileName: `${fileStem}${extension}`,
+      contents,
+    };
+  });
+}
+
+function renderRetiredManagedAgents(client, tenantId, bindings, active, invocation = null) {
+  const usedNames = new Set(active.map(({ name }) => name));
+  const usedFiles = new Set(active.map(({ fileName }) => fileName));
+  return bindings.map((binding) => {
+    const hash = binding.policyFingerprint.slice(0, 8);
+    const safeAgent = binding.agentId.toLowerCase().replace(/[^a-z0-9-]+/gu, "-").replace(/^-+|-+$/gu, "") || "agent";
+    const baseName = client === "claude"
+      ? `impel-recover-${safeAgent.slice(0, 35)}-${hash}`
+      : `Recover ${binding.agentId} (${hash})`;
+    const baseFileStem = client === "claude" ? baseName : `impel-${tenantId}-recovery-${hash}`;
+    const extension = client === "claude" ? ".md" : ".toml";
+    let name = baseName;
+    let fileName = `${baseFileStem}${extension}`;
+    for (let collision = 1; usedNames.has(name) || usedFiles.has(fileName); collision += 1) {
+      const suffix = `retired-${hash}-${collision}`;
+      name = client === "claude"
+        ? `${baseName.slice(0, Math.max(1, 63 - suffix.length - 1))}-${suffix}`
+        : `${baseName} [${suffix}]`;
+      fileName = client === "claude"
+        ? `${name}${extension}`
+        : `${baseFileStem}-${suffix}${extension}`;
+    }
+    usedNames.add(name);
+    usedFiles.add(fileName);
+    const agent = {
+      agentId: binding.agentId,
+      title: `Retired ${binding.agentId}`,
+      description: "Recovery-only access to pending durable runs.",
+      scopeParam: binding.scopeParam,
+      provider: "recovery",
+      capabilities: [],
+      exclusions: ["starting new runs"],
+      requiredContext: [],
+      sideEffects: "read-only",
+    };
+    const boundInvocation = boundNativeAgentInvocation(tenantId, agent, invocation, {
+      policyFingerprint: binding.policyFingerprint,
+      recoveryOnly: true,
+    });
+    const contents = client === "claude"
+      ? renderClaudeAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true })
+      : renderCodexAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true });
+    return {
+      agentId: binding.agentId,
+      scopeParam: binding.scopeParam,
+      policyFingerprint: binding.policyFingerprint,
+      retired: true,
+      name,
+      fileName,
+      contents,
+    };
   });
 }
 
@@ -615,7 +807,15 @@ function profileIsFresh(profile, tenantId, now, ttlMs) {
   );
 }
 
-export function syncAgentProfile({ client, root, label, tenantId, agents, now = Date.now() }) {
+export function syncAgentProfile({
+  client,
+  root,
+  label,
+  tenantId,
+  agents,
+  now = Date.now(),
+  nativeAgentRunsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
+}) {
   const agentsDir = path.join(root, "agents");
   for (const candidate of [root, agentsDir]) {
     if (fs.existsSync(candidate) && fs.lstatSync(candidate).isSymbolicLink()) {
@@ -626,9 +826,22 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
   privateDirectory(managedDir);
   const manifestPath = path.join(managedDir, MANAGED_AGENT_MANIFEST);
   const prior = readManifest(manifestPath);
-  const rendered = renderManagedAgents(client, tenantId, agents);
+  const active = renderManagedAgents(client, tenantId, agents);
+  const activeBindings = new Set(active.map((agent) =>
+    `${agent.agentId}\0${agent.scopeParam}\0${agent.policyFingerprint}`
+  ));
+  const retiredBindings = pendingNativeAgentBindings(tenantId, { runsRoot: nativeAgentRunsRoot })
+    .filter((binding) => !activeBindings.has(
+      `${binding.agentId}\0${binding.scopeParam}\0${binding.policyFingerprint}`,
+    ));
+  const retired = renderRetiredManagedAgents(client, tenantId, retiredBindings, active);
+  const rendered = [...active, ...retired];
+  if (new Set(rendered.map(({ name }) => name)).size !== rendered.length
+    || new Set(rendered.map(({ fileName }) => fileName)).size !== rendered.length) {
+    throw new Error("generated native-agent destinations are not unique");
+  }
   const priorFiles = new Set(prior?.files || []);
-  const priorUsesDiscoveryRoot = [2, 3, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
+  const priorUsesDiscoveryRoot = [2, 3, 4, 5, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
 
   // Native clients discover standalone definitions directly under `agents/`.
   // Preflight every destination before writing so an unmanaged file with the
@@ -675,13 +888,23 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
     client,
     syncedAt: new Date(now).toISOString(),
     files: [...currentFiles].sort(),
-    agents: rendered.map(({ agentId, name }, index) => ({
-      agentId,
-      scopeParam: agents[index].scopeParam,
-      name,
+    agents: rendered.map((agent) => ({
+      agentId: agent.agentId,
+      scopeParam: agent.scopeParam,
+      policyFingerprint: agent.policyFingerprint,
+      retired: agent.retired,
+      name: agent.name,
     })),
   }, null, 2)}\n`);
-  return { client, root, label, synced: true, count: rendered.length, files: [...currentFiles] };
+  return {
+    client,
+    root,
+    label,
+    synced: true,
+    count: active.length,
+    recoveryCount: retired.length,
+    files: [...currentFiles],
+  };
 }
 
 export async function syncAgentProfiles({
@@ -694,6 +917,7 @@ export async function syncAgentProfiles({
   now = Date.now(),
   fetchCatalog = fetchNativeAgentCatalog,
   logger = console,
+  nativeAgentRunsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
 }) {
   if (process.env.IMPEL_SKIP_AGENT_SYNC === "1" || process.env.IMPEL_SKIP_AGENT_SYNC === "true") {
     return profiles.map((profile) => ({ ...profile, skipped: true, reason: "disabled" }));
@@ -722,6 +946,7 @@ export async function syncAgentProfiles({
       tenantId: normalizedTenant,
       agents: catalog.agents,
       now,
+      nativeAgentRunsRoot,
     });
     logger.log(`Agents: ${profile.label || profile.client} up to date (${result.count} explicit tenant agent${result.count === 1 ? "" : "s"}).`);
     results.push(result);