impel-cli 0.19.2-beta.0 → 0.20.0

package/README.md

@@ -228,6 +228,30 @@ impel remote dispatch --provider claude --session <session-id> --fork
 impel remote dispatch --provider codex --session <session-id> --fork
 ```
 
+The installable `remote-control` skill turns this into an in-app handoff. Ask
+Claude Code or Codex to run the current session remotely, or invoke the skill
+directly, and it resolves the current Claude session/Codex thread id before
+running:
+
+```sh
+impel remote handoff . --provider <codex|claude> --session <session-id>
+```
+
+Unlike `up` or `dispatch`, `handoff` launches a detached headless worker inside
+Fargate and follows the provider's structured event stream. Inference, tools,
+commands, and edits execute in the runner; the local app only displays the
+stream. Normal completion stops the task, revokes its disposable PAT, and
+removes its SSH alias. To let the task continue without keeping the stream
+open, add `--detach`, then reconnect later:
+
+```sh
+impel remote follow <run-id>
+```
+
+If the viewer disconnects, the detached worker keeps running and its normal
+session hooks continue syncing the remote transcript to `impel-sessions`. The
+task TTL remains the fallback stop and credential-revocation boundary.
+
 Remote vendor commands run in dangerous/bypass mode as the unprivileged
 `agent` user; the disposable Fargate task is the isolation boundary. Existing
 Impel lifecycle hooks continue mirroring remote transcripts to
@@ -326,6 +350,37 @@ impel tasks delete IMP-123 --yes
 Use `--json` when exact machine-readable fields matter. Gateway-only members
 cannot use task CRUD.
 
+### Native Tasks MCP App
+
+Setup and update register a second tenant-bound MCP server named
+`impel-tasks` in Impel-managed Claude and Codex/ChatGPT profiles. It is separate
+from the existing `impel` specialist server: removing or disabling Tasks does
+not change specialist routing or approvals.
+
+The managed entry launches an absolute, upgrade-stable invocation equivalent
+to:
+
+```sh
+impel mcp --target tasks --tenant <fixed-tenant>
+```
+
+This is an internal transport command, not an interactive PAT interface. The
+child process reads the PAT from Impel's private config, sends it only as the
+control-plane HTTP bearer credential, and fixes tenant selection in the
+transport header. Generated Claude/Codex MCP entries contain neither the PAT
+nor a tenant-derived credential.
+
+- The pinned Impel Claude Desktop can render the standard MCP Apps Tasks
+  resource when its host supports that protocol.
+- Claude Code and stable Codex receive complete headless task tools and text
+  results; no experimental Codex MCP Apps flag is enabled.
+- Profiles preserve unrelated MCP servers. If a user-authored server already
+  owns the `impel-tasks` name, setup/update fails with remediation instead of
+  overwriting it.
+- The Tasks bridge accepts Streamable HTTP's required JSON/SSE media types but
+  deliberately requires bounded JSON responses from the control plane. It
+  does not establish an SSE session or persist protocol state.
+
 ## PAT lifecycle
 
 Minting and revocation remain explicit account operations:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.19.2-beta.0",
+  "version": "0.20.0",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -12,15 +12,6 @@ import path from "node:path";
 import { normalizeGatewayUrl, redactSecretText } from "./config.js";
 import { impelMcpInvocation } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
-import {
-  adapterCallerSpawnGuidance,
-  adapterHardCompletionGuidance,
-  adapterSoftCompletionGuidance,
-  claudeHardCompletionGuidance,
-  claudeSoftCompletionGuidance,
-  customAgentVerbatimDescriptionLead,
-  usesVerbatimRelay,
-} from "./verbatimRelay.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 
 export const AGENT_SYNC_TTL_MS = 6 * 60 * 60 * 1000;
@@ -30,7 +21,7 @@ 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 MANAGED_AGENT_MCP_SERVER = "impel_agent";
-export const MANAGED_AGENT_MANIFEST_VERSION = 5;
+export const MANAGED_AGENT_MANIFEST_VERSION = 4;
 
 const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_LIST_TOOL,
@@ -134,9 +125,6 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
       throw new Error(`native-agent catalog returned duplicate binding ${binding}`);
     }
     seenBindings.add(binding);
-    if (agent.verbatimRelay !== undefined && typeof agent.verbatimRelay !== "boolean") {
-      throw new Error("native-agent catalog returned an invalid verbatimRelay");
-    }
     return {
       agentId,
       title: boundedString(agent.title, "title", { max: 160 }),
@@ -147,7 +135,6 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
       exclusions: stringList(agent.exclusions, "exclusions"),
       requiredContext: stringList(agent.requiredContext, "requiredContext"),
       sideEffects: enumString(agent.sideEffects, "sideEffects", ["read-only", "writes"]),
-      ...(agent.verbatimRelay === true ? { verbatimRelay: true } : {}),
     };
   });
   return { orgId: tenantId, agents };
@@ -342,21 +329,14 @@ function claudeAdapterInstructions(tenantId, agent) {
   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.`;
-  const callerSpawnGuidance = usesVerbatimRelay(agent)
-    ? adapterCallerSpawnGuidance("Claude")
-    : null;
-  const completionGuidance = usesVerbatimRelay(agent)
-    ? claudeHardCompletionGuidance()
-    : claudeSoftCompletionGuidance();
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
-    ...(callerSpawnGuidance ? [callerSpawnGuidance] : []),
     `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.`,
     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.`,
-    completionGuidance,
+    `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.`,
   ].join(" ");
 }
 
@@ -514,36 +494,22 @@ function codexAdapterInstructions(tenantId, agent) {
     ? `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);
-  const callerSpawnGuidance = usesVerbatimRelay(agent)
-    ? adapterCallerSpawnGuidance("Codex")
-    : null;
-  const completionGuidance = usesVerbatimRelay(agent)
-    ? adapterHardCompletionGuidance()
-    : adapterSoftCompletionGuidance();
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
-    ...(callerSpawnGuidance ? [callerSpawnGuidance] : []),
+    `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.`,
-    completionGuidance,
+    `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,
   ].join("\n\n");
 }
 
-function customAgentDescription(tenantId, agent) {
-  const sideEffectsLabel = agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)";
-  return (usesVerbatimRelay(agent)
-    ? `${customAgentVerbatimDescriptionLead()}. Runs ${agent.title} for Impel tenant ${tenantId}${sideEffectsLabel}: ${agent.description}`
-    : `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${sideEffectsLabel}: ${agent.description}`
-  ).slice(0, 900);
-}
-
 function renderClaudeAgent({ tenantId, agent, name, invocation }) {
-  const description = customAgentDescription(tenantId, agent);
+  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);
   const lines = [
     "---",
     `name: ${JSON.stringify(name)}`,
@@ -568,7 +534,7 @@ function renderClaudeAgent({ tenantId, agent, name, invocation }) {
 }
 
 function renderCodexAgent({ tenantId, agent, name, invocation }) {
-  const description = customAgentDescription(tenantId, agent);
+  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);
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
@@ -662,7 +628,7 @@ export function syncAgentProfile({ client, root, label, tenantId, agents, now =
   const prior = readManifest(manifestPath);
   const rendered = renderManagedAgents(client, tenantId, agents);
   const priorFiles = new Set(prior?.files || []);
-  const priorUsesDiscoveryRoot = [2, 3, 4, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
+  const priorUsesDiscoveryRoot = [2, 3, 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

package/src/apps.js

@@ -10,13 +10,18 @@ import {
   secureManagedCodexHome,
 } from "./codexSecurity.js";
 import { normalizeTenantId } from "./tenants.js";
-import { IMPEL_CLI_ENTRYPOINT, impelCliInvocation } from "./selfInvocation.js";
+import {
+  IMPEL_CLI_ENTRYPOINT,
+  IMPEL_TASKS_MCP_SERVER_NAME,
+  impelCliInvocation,
+  impelTasksMcpInvocation,
+  isImpelTasksMcpInvocation,
+} from "./selfInvocation.js";
 import { crossAppModelsEnabled, redactSecretText } from "./config.js";
 import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
-import { IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS } from "./commands/launch.js";
 
 export const CLAUDE_CONFIG_ID = "1ced0000-0000-4000-8000-000000000001";
 const CHATGPT_CONFIG_START = `# >>> ${RUNTIME_BRAND.cli.command} app managed gateway >>>`;
@@ -267,7 +272,8 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 // 26: remember the managed provider defaults and move legacy GPT-5.5 profiles
 // onto GPT-5.6 Sol so ChatGPT's compact Work picker does not fall back to its
 // unsupported-selection "Reset to default" treatment.
-// 27: add managed ChatGPT parent delegation instructions, including custom-agent verbatim relay opt-in.
+// 27: register the separate tenant-bound Tasks MCP server in managed Claude
+// and ChatGPT/Codex profiles without changing the specialist MCP server.
 export const CURRENT_CONFIG_VERSION = 27;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
@@ -809,7 +815,7 @@ export function installManagedAppFiles({
     }
     if (target === "claude") {
       migrateLegacyClaudeAppSessions(paths.claude.userData, homeDir);
-      writeClaudeNative3PSelection(paths);
+      writeClaudeNative3PSelection(paths, config);
       writeClaudeCodeSettings(paths);
       writeClaudeConfig(paths, config, models);
       if (RUNTIME_BRAND.features.sessions) ensureClaudeSessionHooks(paths.claude.userData, config.tenantId, "claude_desktop");
@@ -1155,7 +1161,7 @@ function writeClaudeCodeSettings(paths) {
   writeAtomic(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 0o600);
 }
 
-function writeClaudeNative3PSelection(paths) {
+function writeClaudeNative3PSelection(paths, config) {
   const configPath = path.join(paths.claude.userData, "claude_desktop_config.json");
   let current = {};
   if (fs.existsSync(configPath)) {
@@ -1168,15 +1174,64 @@ function writeClaudeNative3PSelection(paths) {
   if (!current || typeof current !== "object" || Array.isArray(current)) {
     throw new Error(`Claude desktop config must contain a JSON object: ${configPath}`);
   }
-  // Mirror the pinned app's native "select 3P" persistence contract. This
-  // marks the first-run choice complete and clears a pending 1P sign-in while
-  // leaving Claude-owned preferences (including sidebarMode) untouched.
-  if (current.deploymentMode === "3p" && !Object.hasOwn(current, "awaitingSignIn")) return;
+  if (Object.hasOwn(current, "mcpServers") && (
+    !current.mcpServers
+    || typeof current.mcpServers !== "object"
+    || Array.isArray(current.mcpServers)
+  )) {
+    throw new Error(`Claude desktop config has an invalid mcpServers value: ${configPath}`);
+  }
+  const currentMcpServers = current.mcpServers
+    && typeof current.mcpServers === "object"
+    && !Array.isArray(current.mcpServers)
+    ? current.mcpServers
+    : {};
+  const currentTasksServer = currentMcpServers[IMPEL_TASKS_MCP_SERVER_NAME];
+  if (RUNTIME_BRAND.features.mcp && config.tenantId) {
+    if (Object.hasOwn(currentMcpServers, IMPEL_TASKS_MCP_SERVER_NAME)
+      && !isImpelTasksMcpInvocation(currentTasksServer)) {
+      throw new Error(
+        `${configPath} already has an mcpServers.${IMPEL_TASKS_MCP_SERVER_NAME} entry `
+        + "that wasn't written by impel-cli. Remove or rename it, then re-run."
+      );
+    }
+  }
+
+  // Mirror the pinned app's native "select 3P" persistence contract and add
+  // only the tenant-bound Tasks entry we own. Claude-owned preferences and
+  // foreign MCP entries remain untouched.
   const next = { ...current, deploymentMode: "3p" };
   delete next.awaitingSignIn;
+  if (RUNTIME_BRAND.features.mcp && config.tenantId) {
+    next.mcpServers = {
+      ...currentMcpServers,
+      [IMPEL_TASKS_MCP_SERVER_NAME]: impelTasksMcpInvocation(config.tenantId),
+    };
+  } else if (isImpelTasksMcpInvocation(currentTasksServer)) {
+    next.mcpServers = { ...currentMcpServers };
+    delete next.mcpServers[IMPEL_TASKS_MCP_SERVER_NAME];
+    if (Object.keys(next.mcpServers).length === 0) delete next.mcpServers;
+  }
   writeAtomic(configPath, `${JSON.stringify(next, null, 2)}\n`, 0o600);
 }
 
+function tasksInvocationFromBaseMcp(mcp, tenantId) {
+  if (!mcp || typeof mcp.command !== "string" || !Array.isArray(mcp.args)) {
+    return impelTasksMcpInvocation(tenantId);
+  }
+  const mcpIndex = mcp.args.lastIndexOf("mcp");
+  if (mcpIndex === -1) return impelTasksMcpInvocation(tenantId);
+  return {
+    command: mcp.command,
+    args: [
+      ...mcp.args.slice(0, mcpIndex + 1),
+      "--target",
+      "tasks",
+      ...mcp.args.slice(mcpIndex + 1),
+    ],
+  };
+}
+
 function writeChatGPTConfig(
   paths,
   config,
@@ -1258,6 +1313,25 @@ function writeChatGPTConfig(
     command: mcpInvocation.command,
     args: [...mcpInvocation.args],
   };
+  const tasksMcp = invocations?.tasksMcp
+    || tasksInvocationFromBaseMcp(mcp, config.tenantId);
+
+  if (RUNTIME_BRAND.features.mcp && config.tenantId) {
+    const unmanagedToml = stripManagedChatGPTToml(currentToml);
+    const tasksName = escapeRegex(IMPEL_TASKS_MCP_SERVER_NAME);
+    const mcpServersKey = `(?:mcp_servers|"mcp_servers"|'mcp_servers')`;
+    const tasksKey = `(?:${tasksName}|"${tasksName}"|'${tasksName}')`;
+    const foreignTasksTable = new RegExp(
+      `^[ \\t]*\\[[ \\t]*${mcpServersKey}[ \\t]*\\.[ \\t]*${tasksKey}(?:[ \\t]*\\.[ \\t]*|[ \\t]*\\])`,
+      "mu",
+    );
+    if (foreignTasksTable.test(unmanagedToml)) {
+      throw new Error(
+        `${configPath} already has an mcp_servers.${IMPEL_TASKS_MCP_SERVER_NAME} table `
+        + "outside the impel-cli managed block. Remove or rename it, then re-run."
+      );
+    }
+  }
 
   const managedToml = [
     CHATGPT_CONFIG_START,
@@ -1271,9 +1345,6 @@ function writeChatGPTConfig(
     `model_catalog_json = ${tomlString(paths.chatgpt.catalog)}`,
     ...(selectedEffort ? [`model_reasoning_effort = ${tomlString(selectedEffort)}`] : []),
     ...(selectedTier ? [`service_tier = ${tomlString(selectedTier)}`] : []),
-    ...(RUNTIME_BRAND.features.agents
-      ? [`developer_instructions = ${tomlString(IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS)}`]
-      : []),
     "",
     // The built-in ChatGPT provider derives its inference endpoint from
     // chatgpt.com even when chatgpt_base_url points at the gateway. Keep the
@@ -1301,6 +1372,12 @@ function writeChatGPTConfig(
       `[mcp_servers.${RUNTIME_BRAND.cli.providerId}]`,
       `command = ${tomlString(mcp.command)}`,
       `args = [${mcp.args.map((argument) => tomlString(argument)).join(", ")}]`,
+      ...(config.tenantId ? [
+        "",
+        `[mcp_servers.${IMPEL_TASKS_MCP_SERVER_NAME}]`,
+        `command = ${tomlString(tasksMcp.command)}`,
+        `args = [${tasksMcp.args.map((argument) => tomlString(argument)).join(", ")}]`,
+      ] : []),
     ] : []),
     CHATGPT_CONFIG_END,
   ].join("\n");
@@ -1474,7 +1551,7 @@ function readVendorCodexModels(vendorPath) {
   return new Map();
 }
 
-function mergeManagedChatGPTToml(current, managed) {
+function stripManagedChatGPTToml(current) {
   let remainder = current;
   const start = current.indexOf(CHATGPT_CONFIG_START);
   const end = current.indexOf(CHATGPT_CONFIG_END);
@@ -1484,7 +1561,11 @@ function mergeManagedChatGPTToml(current, managed) {
     const legacyEnd = current.match(/refresh_interval_ms = \d+\r?\n/u);
     if (legacyEnd?.index != null) remainder = current.slice(legacyEnd.index + legacyEnd[0].length);
   }
-  remainder = remainder.replace(/^\s+/u, "");
+  return remainder.replace(/^\s+/u, "");
+}
+
+function mergeManagedChatGPTToml(current, managed) {
+  const remainder = stripManagedChatGPTToml(current);
   return `${managed}\n${remainder ? `\n${remainder.replace(/\s*$/u, "")}\n` : ""}`;
 }
 

package/src/cliProfiles.js

@@ -10,7 +10,13 @@ import {
 } from "./codexSecurity.js";
 import { CONFIG_DIR } from "./config.js";
 import { normalizeTenantId } from "./tenants.js";
-import { impelCliInvocation, impelMcpInvocation } from "./selfInvocation.js";
+import {
+  IMPEL_TASKS_MCP_SERVER_NAME,
+  impelCliInvocation,
+  impelMcpInvocation,
+  impelTasksMcpInvocation,
+  isImpelTasksMcpInvocation,
+} from "./selfInvocation.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
@@ -132,13 +138,30 @@ export function ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels
   settings.env = managedEnvironment;
   applyImpelClaudeSandbox(settings);
   if (RUNTIME_BRAND.features.mcp) {
+    if (Object.hasOwn(userConfig, "mcpServers") && (
+      !userConfig.mcpServers
+      || typeof userConfig.mcpServers !== "object"
+      || Array.isArray(userConfig.mcpServers)
+    )) {
+      throw new Error(`${userConfigPath} has an invalid mcpServers value. Fix or remove it, then re-run.`);
+    }
+    const existingServers = userConfig.mcpServers
+      && typeof userConfig.mcpServers === "object"
+      && !Array.isArray(userConfig.mcpServers)
+      ? userConfig.mcpServers
+      : {};
+    const existingTasksServer = existingServers[IMPEL_TASKS_MCP_SERVER_NAME];
+    if (Object.hasOwn(existingServers, IMPEL_TASKS_MCP_SERVER_NAME)
+      && !isImpelTasksMcpInvocation(existingTasksServer)) {
+      throw new Error(
+        `${userConfigPath} already has an mcpServers.${IMPEL_TASKS_MCP_SERVER_NAME} entry `
+        + "that wasn't written by impel-cli. Remove or rename it, then re-run."
+      );
+    }
     userConfig.mcpServers = {
-      ...(userConfig.mcpServers &&
-      typeof userConfig.mcpServers === "object" &&
-      !Array.isArray(userConfig.mcpServers)
-        ? userConfig.mcpServers
-        : {}),
+      ...existingServers,
       [RUNTIME_BRAND.cli.providerId]: impelMcpInvocation(["--tenant", tenantId]),
+      [IMPEL_TASKS_MCP_SERVER_NAME]: impelTasksMcpInvocation(tenantId),
     };
   }
 
@@ -194,6 +217,13 @@ function codexManagedBlock(gatewayUrl, tenantId) {
         "",
       );
     }
+    const tasksMcp = impelTasksMcpInvocation(tenantId);
+    lines.push(
+      `[mcp_servers.${IMPEL_TASKS_MCP_SERVER_NAME}]`,
+      `command = ${JSON.stringify(tasksMcp.command)}`,
+      `args = [${tasksMcp.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+      "",
+    );
   }
   lines.push(CODEX_END_MARK);
   return lines.join("\n");
@@ -208,9 +238,18 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
   const withoutManagedBlock = stripCodexManagedBlock(original, configPath);
 
   const providerPattern = RUNTIME_BRAND.cli.providerId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-  if (new RegExp(`^(\\[model_providers\\.${providerPattern}(?:\\.|\\])|\\[mcp_servers\\.${providerPattern}\\])`, "m").test(withoutManagedBlock)) {
+  const tasksPattern = IMPEL_TASKS_MCP_SERVER_NAME.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const providerKey = `(?:${providerPattern}|"${providerPattern}"|'${providerPattern}')`;
+  const tasksKey = `(?:${tasksPattern}|"${tasksPattern}"|'${tasksPattern}')`;
+  const modelProvidersKey = `(?:model_providers|"model_providers"|'model_providers')`;
+  const mcpServersKey = `(?:mcp_servers|"mcp_servers"|'mcp_servers')`;
+  const dot = "[ \\t]*\\.[ \\t]*";
+  if (new RegExp(
+    `^[ \\t]*\\[[ \\t]*(?:${modelProvidersKey}${dot}${providerKey}|${mcpServersKey}${dot}(?:${providerKey}|${tasksKey}))(?:${dot}|[ \\t]*\\])`,
+    "m",
+  ).test(withoutManagedBlock)) {
     throw new Error(
-      `${configPath} contains a ${RUNTIME_BRAND.product.displayName} provider or MCP table outside the managed profile block. ` +
+      `${configPath} contains a ${RUNTIME_BRAND.product.displayName} provider or managed MCP table outside the managed profile block. ` +
         "Remove or rename that table, then re-run."
     );
   }

package/src/commands/launch.js

@@ -14,7 +14,6 @@ import {
   resolveDefaultGateway,
   saveConfig,
 } from "../config.js";
-import { parentVerbatimRelayAppendix } from "../verbatimRelay.js";
 import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.js";
 import { withGitEnvironment } from "../skills.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
@@ -50,18 +49,10 @@ export {
 
 export const IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS = `You are running in an Impel tenant-scoped session. Before starting any non-trivial task, call the Impel MCP tool list_specialists. If exactly one available specialist clearly matches the user's request, its capabilities and its exclusions, delegate the complete request by calling start_specialist_run exactly once with a stable idempotency key, then call read_specialist_run until it reaches a terminal state. When the run succeeds, use the specialist's result as your response instead of redoing the work. If no specialist clearly matches, the tools are unavailable, or the run fails, continue normally yourself. Do not delegate trivial requests, do not call a specialist excluded from the request, and never invent a specialist result.`;
 
-export const IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX = parentVerbatimRelayAppendix();
-
-export const IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS =
-  `${IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS} ${IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX}`;
-
 export const IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS =
   `${IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS} ` +
   `Codex can defer MCP tools behind tool_search. If an Impel specialist tool is not directly visible, call tool_search for its exact name before treating it as unavailable: impel_specialists-list_specialists for discovery, impel_specialists-start_specialist_run to delegate, and impel_specialists-read_specialist_run to poll the result. Use the returned tool for the same one-run delegation flow.`;
 
-export const IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS =
-  `${IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS} ${IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX}`;
-
 const IMPEL_CODEX_RUNTIME_OVERRIDES = [
   // Codex models may select code mode even when the standalone
   // `codex-code-mode-host` companion is not present in the vendor install.
@@ -73,14 +64,14 @@ const IMPEL_CODEX_RUNTIME_OVERRIDES = [
 export function impelLaunchArguments(tool, argv) {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
-    return ["--append-system-prompt", IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS, ...argv];
+    return ["--append-system-prompt", IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS, ...argv];
   }
   if (tool === "codex") {
     // `-c` is a Codex global option, so it must precede subcommands such as
     // `exec`, `resume`, and `mcp`. JSON strings are valid TOML basic strings.
     return [
       "-c",
-      `developer_instructions=${JSON.stringify(IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS)}`,
+      `developer_instructions=${JSON.stringify(IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS)}`,
       ...IMPEL_CODEX_RUNTIME_OVERRIDES.flatMap((override) => ["-c", override]),
       ...argv,
     ];

package/src/commands/mcp.js

@@ -1,9 +1,20 @@
 import readline from "node:readline";
 
-import { loadConfig, resolveDefaultGateway } from "../config.js";
+import {
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultAppUrl,
+  resolveDefaultGateway,
+} from "../config.js";
 import { parseFlags } from "../args.js";
 import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
 
+const TASKS_TARGET = "tasks";
+const TASKS_TENANT_HEADER = "X-Impel-Tenant";
+const TASKS_ERROR_MESSAGE_MAX_LENGTH = 512;
+const TASKS_ERROR_TOKEN_MAX_LENGTH = 128;
+
 function rpcError(id, message) {
   return JSON.stringify({
     jsonrpc: "2.0",
@@ -12,6 +23,28 @@ function rpcError(id, message) {
   });
 }
 
+function tasksJsonRpcRequestId(message) {
+  if (
+    !message
+    || typeof message !== "object"
+    || Array.isArray(message)
+    || message.jsonrpc !== "2.0"
+    || typeof message.method !== "string"
+  ) {
+    return { valid: false, id: null };
+  }
+  if (!Object.hasOwn(message, "id")) return { valid: true, id: null };
+  const id = message.id;
+  if (
+    id === null
+    || typeof id === "string"
+    || (typeof id === "number" && Number.isFinite(id))
+  ) {
+    return { valid: true, id };
+  }
+  return { valid: false, id: null };
+}
+
 function responseLines(contentType, body) {
   if (!contentType.toLowerCase().includes("text/event-stream")) {
     return body.trim() ? [JSON.stringify(JSON.parse(body))] : [];
@@ -24,18 +57,146 @@ function responseLines(contentType, body) {
     .map((line) => JSON.stringify(JSON.parse(line)));
 }
 
+function isApplicationJson(contentType) {
+  return contentType.split(";", 1)[0].trim().toLowerCase() === "application/json";
+}
+
+function jsonResponseLines(contentType, body) {
+  if (!body.trim()) return [];
+  if (!isApplicationJson(contentType)) {
+    throw new Error("Impel Tasks MCP returned a non-JSON response.");
+  }
+  try {
+    return [JSON.stringify(JSON.parse(body))];
+  } catch {
+    throw new Error("Impel Tasks MCP returned invalid JSON.");
+  }
+}
+
+function tasksHttpError(status) {
+  if (status === 401 || status === 403) {
+    return `Impel Tasks MCP authentication failed (HTTP ${status}). Run \`impel setup\` to refresh access.`;
+  }
+  return `Impel Tasks MCP returned HTTP ${status}.`;
+}
+
+function loadTasksMcpConnection() {
+  const config = loadConfig();
+  if (
+    !config
+    || typeof config.pat !== "string"
+    || !config.pat.trim()
+    || config.pat !== config.pat.trim()
+  ) {
+    throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  }
+  const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
+  let endpoint;
+  try {
+    endpoint = new URL("/api/mcp/tasks", `${appUrl}/`);
+  } catch {
+    throw new Error("Tasks MCP app URL is invalid; run `impel setup` to repair it");
+  }
+  if (
+    !["http:", "https:"].includes(endpoint.protocol)
+    || endpoint.username
+    || endpoint.password
+  ) {
+    throw new Error("Tasks MCP app URL is invalid; run `impel setup` to repair it");
+  }
+  return { credential: config.pat, endpoint: endpoint.href };
+}
+
+function safeTasksErrorToken(value) {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || value.length > TASKS_ERROR_TOKEN_MAX_LENGTH
+    || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)
+    || redactSecretText(value) !== value
+  ) {
+    return undefined;
+  }
+  return value;
+}
+
+function safeTasksErrorData(value, httpStatus) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const data = {};
+  const schemaVersion = safeTasksErrorToken(value.schemaVersion);
+  const code = safeTasksErrorToken(value.code);
+  if (schemaVersion !== undefined) data.schemaVersion = schemaVersion;
+  if (code !== undefined) data.code = code;
+  if (Number.isSafeInteger(value.status) && value.status === httpStatus) {
+    data.status = value.status;
+  }
+  if (typeof value.retryable === "boolean") data.retryable = value.retryable;
+  return Object.keys(data).length > 0 ? data : undefined;
+}
+
+function tasksJsonRpcHttpError(id, contentType, body, httpStatus) {
+  if (!isApplicationJson(contentType)) return null;
+  let response;
+  try {
+    response = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (
+    !response
+    || typeof response !== "object"
+    || Array.isArray(response)
+    || response.jsonrpc !== "2.0"
+    || !response.error
+    || typeof response.error !== "object"
+    || Array.isArray(response.error)
+    || !Number.isSafeInteger(response.error.code)
+    || typeof response.error.message !== "string"
+  ) {
+    return null;
+  }
+  const message = redactSecretText(response.error.message).trim();
+  if (!message) return null;
+  const error = {
+    code: response.error.code,
+    message: message.length <= TASKS_ERROR_MESSAGE_MAX_LENGTH
+      ? message
+      : `${message.slice(0, TASKS_ERROR_MESSAGE_MAX_LENGTH - 1)}…`,
+  };
+  const data = safeTasksErrorData(response.error.data, httpStatus);
+  if (data) error.data = data;
+  return JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error });
+}
+
 export async function cmdMcp(argv = []) {
-  const { flags } = parseFlags(argv, { tenant: { type: "string" } });
+  const { flags, positionals } = parseFlags(argv, {
+    target: { type: "string" },
+    tenant: { type: "string" },
+  });
+  const targetSpecified = Object.hasOwn(flags, "target");
+  if (targetSpecified && flags.target !== TASKS_TARGET) {
+    throw new Error("unsupported MCP target; expected `--target tasks`");
+  }
+  const tasksTarget = flags.target === TASKS_TARGET;
+  if (tasksTarget) {
+    const unsupportedFlags = Object.keys(flags).filter((name) => !["target", "tenant"].includes(name));
+    if (unsupportedFlags.length > 0 || positionals.length > 0) {
+      throw new Error("unsupported Tasks MCP arguments; use `--target tasks --tenant <tenant>`");
+    }
+    if (typeof flags.tenant !== "string" || !flags.tenant.trim()) {
+      throw new Error("Tasks MCP requires a fixed `--tenant <tenant>` argument");
+    }
+  }
   const config = loadConfig();
   if (!config?.pat) {
     throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
   }
-  const gatewayUrl = config.gatewayUrl || resolveDefaultGateway();
   const tenantId = flags.tenant
     ? normalizeTenantId(flags.tenant)
     : (await ensureTenantSelection(config)).tenantId;
-  const gatewayCredential = tenantCredential(config.pat, tenantId);
-  const endpoint = `${gatewayUrl}/mcp`;
+  const gatewayUrl = config.gatewayUrl || resolveDefaultGateway();
+  const credential = tasksTarget ? null : tenantCredential(config.pat, tenantId);
+  const endpoint = tasksTarget ? null : `${gatewayUrl}/mcp`;
   const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
   let sessionId;
 
@@ -49,19 +210,30 @@ export async function cmdMcp(argv = []) {
       process.stdout.write(`${rpcError(null, "Invalid JSON-RPC request.")}\n`);
       continue;
     }
+    const tasksRequest = tasksTarget
+      ? tasksJsonRpcRequestId(message)
+      : null;
+    if (tasksTarget && !tasksRequest.valid) {
+      process.stdout.write(`${rpcError(tasksRequest.id, "Invalid JSON-RPC request.")}\n`);
+      continue;
+    }
 
     try {
+      const tasksConnection = tasksTarget ? loadTasksMcpConnection() : null;
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 70_000);
       let response;
       try {
-        response = await fetch(endpoint, {
+        response = await fetch(tasksConnection?.endpoint || endpoint, {
           method: "POST",
           headers: {
-            Authorization: `Bearer ${gatewayCredential}`,
+            Authorization: `Bearer ${tasksConnection?.credential || credential}`,
             "Content-Type": "application/json",
+            // Streamable HTTP requires clients to advertise both media types
+            // even when the server is configured to emit bounded JSON only.
             Accept: "application/json, text/event-stream",
-            ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}),
+            ...(tasksTarget ? { [TASKS_TENANT_HEADER]: tenantId } : {}),
+            ...(!tasksTarget && sessionId ? { "Mcp-Session-Id": sessionId } : {}),
           },
           body: JSON.stringify(message),
           signal: controller.signal,
@@ -69,26 +241,38 @@ export async function cmdMcp(argv = []) {
       } finally {
         clearTimeout(timeout);
       }
-      sessionId = response.headers.get("mcp-session-id") || sessionId;
+      if (!tasksTarget) sessionId = response.headers.get("mcp-session-id") || sessionId;
       const body = await response.text();
+      const contentType = response.headers.get("content-type")
+        || (tasksTarget ? "" : "application/json");
       if (!response.ok) {
+        const tasksError = tasksTarget
+          ? tasksJsonRpcHttpError(tasksRequest.id, contentType, body, response.status)
+          : null;
         process.stdout.write(
-          `${rpcError(message.id, `Impel MCP gateway returned HTTP ${response.status}.`)}\n`
+          `${tasksError || rpcError(
+            tasksTarget ? tasksRequest.id : message.id,
+            tasksTarget
+              ? tasksHttpError(response.status)
+              : `Impel MCP gateway returned HTTP ${response.status}.`
+          )}\n`
         );
         continue;
       }
-      for (const output of responseLines(
-        response.headers.get("content-type") || "application/json",
-        body
-      )) {
+      const outputs = tasksTarget
+        ? jsonResponseLines(contentType, body)
+        : responseLines(contentType, body);
+      for (const output of outputs) {
         process.stdout.write(`${output}\n`);
       }
     } catch (error) {
       const messageText =
         error?.name === "AbortError"
-          ? "Impel MCP gateway timed out."
-          : `Impel MCP gateway request failed: ${error?.message || error}`;
-      process.stdout.write(`${rpcError(message.id, messageText)}\n`);
+          ? tasksTarget ? "Impel Tasks MCP timed out." : "Impel MCP gateway timed out."
+          : tasksTarget
+            ? `Impel Tasks MCP request failed: ${redactSecretText(error?.message || error)}`
+            : `Impel MCP gateway request failed: ${redactSecretText(error?.message || error)}`;
+      process.stdout.write(`${rpcError(tasksTarget ? tasksRequest.id : message.id, messageText)}\n`);
     }
   }
 }

package/src/commands/remote.js

@@ -61,6 +61,8 @@ Usage:
   impel remote status [run-id] [--json]
   impel remote attach [run-id] [--provider codex|claude] [--desktop]
   impel remote dispatch [path] --provider codex|claude --session <id> [--fork]
+  impel remote handoff [path] --provider codex|claude --session <id> [--detach]
+  impel remote follow [run-id]
   impel remote proxy <run-id> --port <port>
   impel remote down [run-id] --yes
   impel remote down --all --yes
@@ -77,6 +79,9 @@ Lifecycle options:
   --timeout <seconds>     Runner startup timeout from 30 through 900. Default: 300.
   --json                  Emit machine-readable state where supported.
 
+Handoff options:
+  --detach                Start remote execution and return immediately.
+
 Attach options:
   --session <id>          Resume a transferred provider session.
   --fork                  Fork instead of continuing the transferred session.
@@ -85,8 +90,10 @@ Attach options:
 The live UI uses native SSH: Codex Desktop starts remote codex app-server and can
 hand off an existing chat and Git state. Claude Desktop can start an SSH session;
 existing Claude sessions use dispatch/resume because Claude has no arbitrary-host
-desktop handoff API. Credentials, ignored files, SSH agents, and environment
-variables are never copied implicitly.
+desktop handoff API. Handoff starts a headless worker inside Fargate and streams
+its structured events back; the local app is only the control/viewer process.
+Credentials, ignored files, SSH agents, and environment variables are never
+copied implicitly.
 `;
 
 class RemoteCommandError extends Error {}
@@ -124,6 +131,7 @@ function rejectMissingFlagValues(flags, spec, action) {
 function lifecycleSpec() {
   return {
     env: { type: "string" },
+    detach: { type: "boolean" },
     help: { type: "boolean" },
     install: { type: "string" },
     json: { type: "boolean" },
@@ -346,6 +354,47 @@ async function cmdUp(argv, { dispatch = false } = {}) {
   return state;
 }
 
+async function stopAndCleanRun(config, state) {
+  const context = awsContext(state);
+  if (state.status !== "stopped" && state.aws?.taskArn) {
+    try { stopTask(context, state); } catch (error) {
+      const current = describeTask(context, state);
+      if (current.lastStatus !== "STOPPED") throw error;
+    }
+  }
+  let revokeError = null;
+  if (!state.credential?.revokedAt) {
+    if (!config?.pat) {
+      revokeError = new Error("no local Impel credential is available to revoke the remote PAT");
+    } else {
+      try { state = await revokeRunCredential(config, state); } catch (error) { revokeError = error; }
+    }
+  }
+  removeSshAlias(state.runId);
+  removeRunSecrets(state.runId);
+  state = writeRunState({
+    ...state,
+    status: "stopped",
+    stoppedAt: state.stoppedAt || new Date().toISOString(),
+    ...(revokeError ? {
+      credential: {
+        ...state.credential,
+        revokeError: redactSecretText(revokeError?.message || revokeError),
+      },
+    } : {}),
+  });
+  return { state, revokeError };
+}
+
+function printCleanupResult(state, revokeError) {
+  if (revokeError) {
+    console.warn(`Stopped remote run ${state.runId} and removed its SSH alias, but credential revocation must be retried: ${redactSecretText(revokeError?.message || revokeError)}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`Stopped remote run ${state.runId}; revoked its credential and removed its SSH alias.`);
+  }
+}
+
 function syncTaskStatus(state) {
   if (!state?.aws?.taskArn || ["failed", "stopped"].includes(state.status)) return state;
   const context = awsContext(state);
@@ -456,6 +505,116 @@ async function cmdDispatch(argv) {
   ]);
 }
 
+function workerCommand(action, state) {
+  const command = ["impel-remote-worker", action];
+  if (action === "start") {
+    command.push(state.provider, state.session.id, state.repository.remoteProjectPath);
+  }
+  return command.map(shellQuote).join(" ");
+}
+
+function readWorkerStatus(state) {
+  const result = runCapture(
+    process.env.IMPEL_REMOTE_SSH_BIN || "ssh",
+    [state.alias, workerCommand("status", state)],
+    { allowFailure: true },
+  );
+  if (result.status !== 0) return null;
+  try {
+    const value = JSON.parse(result.stdout.trim());
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function followRemoteWorker(state) {
+  console.log(`Remote execution ${state.runId} is running in Fargate. Streaming structured events:`);
+  console.log("");
+  runInteractive(
+    process.env.IMPEL_REMOTE_SSH_BIN || "ssh",
+    [state.alias, workerCommand("follow", state)],
+    { allowFailure: true },
+  );
+  const worker = readWorkerStatus(state);
+  if (!worker || !["completed", "failed"].includes(worker.status)) {
+    state = writeRunState({
+      ...state,
+      execution: { ...state.execution, status: "running", lastFollowEndedAt: new Date().toISOString() },
+    });
+    console.warn(`Remote execution is still running or its status could not be read. Reconnect with: impel remote follow ${state.runId}`);
+    return { state, completed: false };
+  }
+  const exitCode = Number.isInteger(worker.exitCode) ? worker.exitCode : 1;
+  state = writeRunState({
+    ...state,
+    execution: {
+      ...state.execution,
+      status: worker.status,
+      exitCode,
+      finishedAt: worker.finishedAt || new Date().toISOString(),
+    },
+  });
+  const cleaned = await stopAndCleanRun(loadConfig(), state);
+  printCleanupResult(cleaned.state, cleaned.revokeError);
+  if (exitCode !== 0) process.exitCode = exitCode;
+  return { state: cleaned.state, completed: true };
+}
+
+async function cmdHandoff(argv) {
+  const spec = lifecycleSpec();
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set([
+    "detach", "env", "help", "install", "json", "profile", "provider", "region", "session", "setup", "stack", "timeout", "ttl",
+  ]), "handoff");
+  rejectMissingFlagValues(flags, spec, "handoff");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length > 1) fail("impel remote handoff: expected at most one repository path");
+  if (!flags.session) fail("impel remote handoff: --session is required");
+
+  let state = await createRemoteRun({ ...flags, path: positionals[0] });
+  try {
+    runCapture(
+      process.env.IMPEL_REMOTE_SSH_BIN || "ssh",
+      [state.alias, workerCommand("start", state)],
+    );
+    state = writeRunState({
+      ...state,
+      execution: {
+        mode: flags.detach ? "detached" : "follow",
+        status: "running",
+        startedAt: new Date().toISOString(),
+      },
+    });
+  } catch (error) {
+    const cleaned = await stopAndCleanRun(loadConfig(), state);
+    printCleanupResult(cleaned.state, cleaned.revokeError);
+    throw error;
+  }
+
+  if (flags.detach) {
+    printRun(state, flags.json === true);
+    if (!flags.json) {
+      console.log(`Worker:    running remotely; follow with impel remote follow ${state.runId}`);
+      console.log("Results:   the transferred provider session continues syncing through impel-sessions.");
+    }
+    return;
+  }
+  await followRemoteWorker(state);
+}
+
+async function cmdFollow(argv) {
+  const spec = { help: { type: "boolean" } };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["help"]), "follow");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length > 1) fail("impel remote follow: expected at most one run id");
+  const state = syncTaskStatus(readRunState(resolveRunId(positionals[0])));
+  if (state.status !== "running") fail(`impel remote follow: run ${state.runId} is ${state.status}, not running`);
+  if (!state.execution) fail(`impel remote follow: run ${state.runId} has no headless execution`);
+  await followRemoteWorker(state);
+}
+
 async function cmdDown(argv) {
   const { flags, positionals } = parseFlags(argv, {
     all: { type: "boolean" },
@@ -472,40 +631,9 @@ async function cmdDown(argv) {
     : [readRunState(resolveRunId(positionals[0], { includeStopped: true }))];
   const config = loadConfig();
   for (let state of states) {
-    const context = awsContext(state);
-    if (state.status !== "stopped" && state.aws?.taskArn) {
-      try { stopTask(context, state); } catch (error) {
-        const current = describeTask(context, state);
-        if (current.lastStatus !== "STOPPED") throw error;
-      }
-    }
-    let revokeError = null;
-    if (!state.credential?.revokedAt) {
-      if (!config?.pat) {
-        revokeError = new Error("no local Impel credential is available to revoke the remote PAT");
-      } else {
-        try { state = await revokeRunCredential(config, state); } catch (error) { revokeError = error; }
-      }
-    }
-    removeSshAlias(state.runId);
-    removeRunSecrets(state.runId);
-    state = writeRunState({
-      ...state,
-      status: "stopped",
-      stoppedAt: state.stoppedAt || new Date().toISOString(),
-      ...(revokeError ? {
-        credential: {
-          ...state.credential,
-          revokeError: redactSecretText(revokeError?.message || revokeError),
-        },
-      } : {}),
-    });
-    if (revokeError) {
-      console.warn(`Stopped remote run ${state.runId} and removed its SSH alias, but credential revocation must be retried: ${redactSecretText(revokeError?.message || revokeError)}`);
-      process.exitCode = 1;
-    } else {
-      console.log(`Stopped remote run ${state.runId}; revoked its credential and removed its SSH alias.`);
-    }
+    const cleaned = await stopAndCleanRun(config, state);
+    state = cleaned.state;
+    printCleanupResult(state, cleaned.revokeError);
   }
 }
 
@@ -543,6 +671,8 @@ export async function cmdRemote(argv) {
       case "status": return await cmdStatus(rest);
       case "attach": return await cmdAttach(rest);
       case "dispatch": return await cmdDispatch(rest);
+      case "handoff": return await cmdHandoff(rest);
+      case "follow": return await cmdFollow(rest);
       case "down": return await cmdDown(rest);
       case "proxy": return cmdProxy(rest);
       default: fail(`impel remote: unknown subcommand ${JSON.stringify(action)}`);

package/src/remote/transfer.js

@@ -40,6 +40,14 @@ function writePrivate(filePath, contents) {
   try { fs.chmodSync(filePath, 0o600); } catch { /* Best effort on Windows. */ }
 }
 
+function localTarEnvironment() {
+  // macOS libarchive serializes extended attributes into AppleDouble `._*`
+  // entries unless copyfile metadata is explicitly disabled. Those synthetic
+  // files make a clean transferred repository appear dirty on Linux even when
+  // tar's --no-xattrs option is present.
+  return { ...process.env, COPYFILE_DISABLE: "1" };
+}
+
 export function inspectRepository(requestedPath = process.cwd()) {
   const requested = path.resolve(requestedPath);
   const candidate = fs.realpathSync(requested);
@@ -98,7 +106,7 @@ export function createRepositoryTransfer(state, repository) {
     "--no-xattrs",
     "--null",
     "-T", paths.fileList,
-  ], { cwd: repository.root });
+  ], { cwd: repository.root, env: localTarEnvironment() });
   return paths;
 }
 
@@ -119,6 +127,18 @@ function joinNullBuffer(entries) {
   return Buffer.concat(entries.flatMap((entry) => [entry, Buffer.from([0])]));
 }
 
+function claudeProjectStorageKey(projectPath) {
+  return String(projectPath).replace(/[^A-Za-z0-9]/gu, "-");
+}
+
+export function checkpointRemoteRelativePath(provider, relativePath, remoteProjectPath) {
+  const normalized = String(relativePath).split(path.sep).join("/");
+  if (provider !== "claude") return normalized;
+  const segments = normalized.split("/");
+  if (segments[0] !== "projects" || segments.length < 3) return normalized;
+  return ["projects", claudeProjectStorageKey(remoteProjectPath), ...segments.slice(2)].join("/");
+}
+
 export async function waitForSsh(state, timeoutSeconds = 120) {
   const deadline = Date.now() + timeoutSeconds * 1000;
   let lastError = "SSH did not accept a connection";
@@ -274,15 +294,46 @@ export function transferSessionCheckpoint(state, { provider, sessionId, tenantId
   }
   const checkpointList = path.join(runPaths(state.runId).root, `checkpoint-${provider}.list`);
   const checkpointArchive = path.join(runPaths(state.runId).root, `checkpoint-${provider}.tar`);
+  const mappings = files.map((relative) => ({
+    source: relative.split(path.sep).join("/"),
+    destination: checkpointRemoteRelativePath(provider, relative, state.repository.remoteProjectPath),
+  }));
   writePrivate(checkpointList, Buffer.from(`${files.join("\0")}\0`, "utf8"));
   try {
     runCapture(process.env.IMPEL_REMOTE_TAR_BIN || "tar", [
       "-cf", checkpointArchive, "--no-xattrs", "--null", "-T", checkpointList,
-    ], { cwd: localRoot });
+    ], { cwd: localRoot, env: localTarEnvironment() });
     sshCapture(state, `mkdir -p ${remoteRoot}`);
     runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", sshArgs(state, `tar -xf - -C ${remoteRoot}`), {
       inputFile: checkpointArchive,
     });
+    if (provider === "claude") {
+      remoteNode(state, String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+const root = path.resolve(payload.root);
+for (const mapping of payload.mappings) {
+  const source = path.resolve(root, mapping.source);
+  const destination = path.resolve(root, mapping.destination);
+  if (!source.startsWith(root + path.sep) || !destination.startsWith(root + path.sep)) {
+    throw new Error("unsafe checkpoint path");
+  }
+  if (source === destination) continue;
+  if (!fs.statSync(source, { throwIfNoEntry: false })?.isFile()) {
+    throw new Error("checkpoint source is missing");
+  }
+  if (fs.existsSync(destination)) throw new Error("checkpoint destination already exists");
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  fs.renameSync(source, destination);
+  let emptyParent = path.dirname(source);
+  while (emptyParent !== root && emptyParent.startsWith(root + path.sep)) {
+    try { fs.rmdirSync(emptyParent); } catch { break; }
+    emptyParent = path.dirname(emptyParent);
+  }
+}
+`, { root: remoteRoot, mappings });
+    }
   } finally {
     fs.rmSync(checkpointList, { force: true });
     fs.rmSync(checkpointArchive, { force: true });

package/src/selfInvocation.js

@@ -65,6 +65,7 @@ export function impelCliInvocation(args = [], options = {}) {
 }
 
 export const IMPEL_MANAGED_MCP_ENV = brandedEnvironmentName("MANAGED_MCP");
+export const IMPEL_TASKS_MCP_SERVER_NAME = `${RUNTIME_BRAND.cli.providerId}-tasks`;
 
 export function impelMcpInvocation(args = [], options = {}) {
   return {
@@ -73,3 +74,29 @@ export function impelMcpInvocation(args = [], options = {}) {
     env: { [IMPEL_MANAGED_MCP_ENV]: "1" },
   };
 }
+
+/**
+ * The tenant-bound Tasks MCP process launched by managed Claude/Codex hosts.
+ * The PAT remains in Impel's private config and is read by the child process;
+ * it must never be baked into this invocation or a vendor profile.
+ */
+export function impelTasksMcpInvocation(tenantId, options = {}) {
+  if (typeof tenantId !== "string" || !tenantId.trim()) {
+    throw new Error("a tenant is required for the managed Tasks MCP invocation");
+  }
+  return impelMcpInvocation(["--target", "tasks", "--tenant", tenantId], options);
+}
+
+/** Recognize only the marker-bearing Tasks invocation that impel-cli owns. */
+export function isImpelTasksMcpInvocation(value) {
+  if (!value || typeof value !== "object" || !Array.isArray(value.args)) return false;
+  const suffix = value.args.slice(-5);
+  return value.type === "stdio"
+    && value.env?.[IMPEL_MANAGED_MCP_ENV] === "1"
+    && suffix[0] === "mcp"
+    && suffix[1] === "--target"
+    && suffix[2] === "tasks"
+    && suffix[3] === "--tenant"
+    && typeof suffix[4] === "string"
+    && suffix[4].length > 0;
+}

package/src/verbatimRelay.js

@@ -1,64 +0,0 @@
-export const VERBATIM_RELAY_OPT_IN_MARKER = "verbatimRelay enabled";
-
-export const VERBATIM_SPAWN_REQUIREMENT = 'fork_turns="none"';
-
-export const VERBATIM_FINAL_TEXT_CONSTRAINTS =
-  "no preface, rewriting, Markdown changes, or independent synthesis";
-
-export function usesVerbatimRelay(agent) {
-  return agent?.verbatimRelay === true;
-}
-
-export function parentVerbatimRelayAppendix() {
-  return (
-    `When an explicit custom agent's catalog-derived description declares ${VERBATIM_RELAY_OPT_IN_MARKER}, ` +
-    `spawn it with ${VERBATIM_SPAWN_REQUIREMENT} and relay its finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}; ` +
-    "preserve Sources sections and citations exactly. " +
-    "Custom agents without that declaration keep the default delegation behavior."
-  );
-}
-
-export function customAgentVerbatimDescriptionLead() {
-  return (
-    `Explicit custom agent with ${VERBATIM_RELAY_OPT_IN_MARKER}: ` +
-    `callers must use ${VERBATIM_SPAWN_REQUIREMENT} and relay its result verbatim`
-  );
-}
-
-export function adapterCallerSpawnGuidance(clientLabel) {
-  return (
-    `Callers must spawn this explicit custom ${clientLabel} agent with ${VERBATIM_SPAWN_REQUIREMENT} ` +
-    "and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior."
-  );
-}
-
-export function adapterHardCompletionGuidance() {
-  return (
-    `After the orchestration completes, return its single text output verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
-    "A successful output is result.finalText exactly. A failure output preserves the durable runId, output, and error."
-  );
-}
-
-export function adapterSoftCompletionGuidance() {
-  return (
-    "After the orchestration completes, return its single text output as the answer. " +
-    "A successful output is result.finalText. A failure output preserves the durable runId, output, and error. " +
-    "Never invent or independently synthesize a replacement result."
-  );
-}
-
-export function claudeHardCompletionGuidance() {
-  return (
-    `When it succeeds, return result.finalText exactly with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
-    "When it fails, return the durable runId, preserved output, and error. " +
-    "Never invent or independently synthesize a replacement result."
-  );
-}
-
-export function claudeSoftCompletionGuidance() {
-  return (
-    "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."
-  );
-}