impel-cli 0.19.2-beta.0 → 0.20.0-beta.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,8 +1,9 @@
 {
   "name": "impel-cli",
-  "version": "0.19.2-beta.0",
+  "version": "0.20.0-beta.0",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
+  "packageManager": "pnpm@11.17.0",
   "bin": {
     "impel": "bin/impel.js"
   },
@@ -19,6 +20,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public",
@@ -27,8 +31,5 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/UseImpel/impel-cli.git"
-  },
-  "scripts": {
-    "test": "node --test"
   }
-}
+}

package/src/agents.js

@@ -10,6 +10,13 @@ import os from "node:os";
 import path from "node:path";
 
 import { normalizeGatewayUrl, redactSecretText } from "./config.js";
+import {
+  adapterAnswerHardCompletionGuidance,
+  adapterAnswerSoftCompletionGuidance,
+  claudeAnswerHardCompletionGuidance,
+  claudeAnswerSoftCompletionGuidance,
+  usesDirectAnswer,
+} from "./directAnswer.js";
 import { impelMcpInvocation } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import {
@@ -29,14 +36,22 @@ 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_ANSWER_TOOL = "impel_specialists-answer_native_agent";
 export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
-export const MANAGED_AGENT_MANIFEST_VERSION = 5;
+export const MANAGED_AGENT_MANIFEST_VERSION = 6;
 
-const NATIVE_AGENT_TOOL_NAMES = [
+const NATIVE_AGENT_SESSION_TOOL_NAMES = [
   NATIVE_AGENT_LIST_TOOL,
   NATIVE_AGENT_START_TOOL,
   NATIVE_AGENT_READ_TOOL,
 ];
+
+function nativeAgentToolNames(agent) {
+  return usesDirectAnswer(agent)
+    ? [NATIVE_AGENT_ANSWER_TOOL]
+    : NATIVE_AGENT_SESSION_TOOL_NAMES;
+}
+
 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;
@@ -137,6 +152,9 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
     if (agent.verbatimRelay !== undefined && typeof agent.verbatimRelay !== "boolean") {
       throw new Error("native-agent catalog returned an invalid verbatimRelay");
     }
+    if (agent.directAnswer !== undefined && typeof agent.directAnswer !== "boolean") {
+      throw new Error("native-agent catalog returned an invalid directAnswer");
+    }
     return {
       agentId,
       title: boundedString(agent.title, "title", { max: 160 }),
@@ -148,6 +166,7 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
       requiredContext: stringList(agent.requiredContext, "requiredContext"),
       sideEffects: enumString(agent.sideEffects, "sideEffects", ["read-only", "writes"]),
       ...(agent.verbatimRelay === true ? { verbatimRelay: true } : {}),
+      ...(agent.directAnswer === true ? { directAnswer: true } : {}),
     };
   });
   return { orgId: tenantId, agents };
@@ -345,6 +364,20 @@ function claudeAdapterInstructions(tenantId, agent) {
   const callerSpawnGuidance = usesVerbatimRelay(agent)
     ? adapterCallerSpawnGuidance("Claude")
     : null;
+  if (usesDirectAnswer(agent)) {
+    const completionGuidance = usesVerbatimRelay(agent)
+      ? claudeAnswerHardCompletionGuidance()
+      : claudeAnswerSoftCompletionGuidance();
+    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, do not delegate to any other agent, and do not call Impel start_native_agent_run or read_native_agent_run.`,
+      `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before answering.${contextRequirement}`,
+      sideEffectInstruction,
+      `Call ${toolName(NATIVE_AGENT_ANSWER_TOOL)} exactly once with agentId ${JSON.stringify(agent.agentId)}, scopeParam ${JSON.stringify(agent.scopeParam)}, question 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, and confirmedSideEffects as directed above.`,
+      completionGuidance,
+    ].join(" ");
+  }
   const completionGuidance = usesVerbatimRelay(agent)
     ? claudeHardCompletionGuidance()
     : claudeSoftCompletionGuidance();
@@ -369,7 +402,96 @@ 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__";
 
+function renderCodexDirectAnswerOrchestration(tenantId, agent) {
+  const expectedTenantId = normalizeTenantId(tenantId);
+  const nestedToolName = (toolName) => nativeToolName(toolName).replaceAll("-", "_");
+  const answerTool = nestedToolName(NATIVE_AGENT_ANSWER_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 answerToolName = ${JSON.stringify(answerTool)};`,
+    "",
+    "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 extractAnswerFinalText(payload) {",
+    '  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;',
+    '  for (const key of ["forUser", "answer"]) {',
+    "    const value = payload[key];",
+    '    if (typeof value === "string" && value.trim()) return value;',
+    "  }",
+    "  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() {",
+    "  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");',
+    "    const missingContext = expectedAgent.requiredContext.filter((key) =>",
+    "      !suppliedContextKeys.includes(key)",
+    "    );",
+    '    if (missingContext.length) throw new Error("missing required context: " + missingContext.join(", "));',
+    "",
+    "    const answerArguments = {",
+    "      agentId: expectedAgent.agentId,",
+    "      scopeParam: expectedAgent.scopeParam,",
+    "      question: assignedTask,",
+    "      contextKeys: suppliedContextKeys,",
+    "    };",
+    "    if (suppliedContext !== null) answerArguments.context = suppliedContext;",
+    '    if (expectedAgent.sideEffects === "writes") answerArguments.confirmedSideEffects = true;',
+    "    const answered = toolPayload(await tools[answerToolName](answerArguments), \"native-agent answer\");",
+    "    const finalText = extractAnswerFinalText(answered);",
+    '    if (typeof finalText !== "string") throw new Error("native-agent answer returned no forUser/answer");',
+    "    text(finalText);",
+    "  } catch (error) {",
+    "    text(JSON.stringify({",
+    '      error: errorValue(error, "native-agent answer adapter failed"),',
+    "      tenantId: expectedTenantId,",
+    "      agentId: expectedAgent.agentId,",
+    "    }));",
+    "  }",
+    "}",
+    "",
+    "await orchestrate();",
+  ].join("\n");
+}
+
 export function renderCodexAdapterOrchestration(tenantId, agent) {
+  if (usesDirectAnswer(agent)) {
+    return renderCodexDirectAnswerOrchestration(tenantId, agent);
+  }
   const expectedTenantId = normalizeTenantId(tenantId);
   const nestedToolName = (toolName) => nativeToolName(toolName).replaceAll("-", "_");
   const listTool = nestedToolName(NATIVE_AGENT_LIST_TOOL);
@@ -517,6 +639,23 @@ function codexAdapterInstructions(tenantId, agent) {
   const callerSpawnGuidance = usesVerbatimRelay(agent)
     ? adapterCallerSpawnGuidance("Codex")
     : null;
+  if (usesDirectAnswer(agent)) {
+    const completionGuidance = usesVerbatimRelay(agent)
+      ? adapterAnswerHardCompletionGuidance()
+      : adapterAnswerSoftCompletionGuidance();
+    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, do not delegate to any other agent, do not independently synthesize or rewrite the result, and do not call Impel start_native_agent_run or read_native_agent_run.`,
+      `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before answering.${contextRequirement}`,
+      sideEffectInstruction,
+      `Invoke functions.exec exactly once for the orchestration below. Do not call the MCP tools directly. 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 (unused by the answer tool but kept for adapter parity): choose it exactly once. Then pass the raw JavaScript without Markdown fences.`,
+      `The JavaScript validates required context and calls Impel answer_native_agent exactly once, returning forUser (else answer). 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 open an Impel/Eve session.`,
+      completionGuidance,
+      "",
+      source,
+    ].join("\n\n");
+  }
   const completionGuidance = usesVerbatimRelay(agent)
     ? adapterHardCompletionGuidance()
     : adapterSoftCompletionGuidance();
@@ -544,13 +683,14 @@ function customAgentDescription(tenantId, agent) {
 
 function renderClaudeAgent({ tenantId, agent, name, invocation }) {
   const description = customAgentDescription(tenantId, agent);
+  const toolNames = nativeAgentToolNames(agent);
   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",
@@ -569,6 +709,7 @@ function renderClaudeAgent({ tenantId, agent, name, invocation }) {
 
 function renderCodexAgent({ tenantId, agent, name, invocation }) {
   const description = customAgentDescription(tenantId, agent);
+  const toolNames = nativeAgentToolNames(agent);
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
@@ -581,11 +722,11 @@ function renderCodexAgent({ tenantId, agent, name, invocation }) {
     `[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");
@@ -662,7 +803,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, 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

package/src/apps.js

@@ -10,7 +10,13 @@ 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";
@@ -267,8 +273,11 @@ 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.
-export const CURRENT_CONFIG_VERSION = 27;
+// 27: register the separate tenant-bound Tasks MCP server in managed Claude
+// and ChatGPT/Codex profiles without changing the specialist MCP server.
+// 28: add managed ChatGPT parent delegation instructions, including custom-agent
+// verbatim relay opt-in and directAnswer one-shot MCP answer routing.
+export const CURRENT_CONFIG_VERSION = 28;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -809,7 +818,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 +1164,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 +1177,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 +1316,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,
@@ -1301,6 +1378,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 +1557,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 +1567,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/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/directAnswer.js

@@ -0,0 +1,59 @@
+/**
+ * Catalog opt-in for Impel MCP `answer_native_agent`.
+ *
+ * When `directAnswer` is true, managed Claude/Codex adapters call that one-shot
+ * tool (Impel auth → Eve `/eve/v1/answer`) and return forUser/answer instead of
+ * list → start → poll. Distinct from agent-internal retrieve shortcuts.
+ *
+ * Does not replace the verbatimRelay description / fork_turns override: when an
+ * agent also sets verbatimRelay, keep that marker and spawn guidance so parents
+ * still use fork_turns="none" and relay the adapter result verbatim.
+ */
+
+import {
+  VERBATIM_FINAL_TEXT_CONSTRAINTS,
+} from "./verbatimRelay.js";
+
+export function usesDirectAnswer(agent) {
+  return agent?.directAnswer === true;
+}
+
+export function extractAnswerFinalText(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  for (const key of ["forUser", "answer"]) {
+    const text = payload[key];
+    if (typeof text === "string" && text.trim()) return text;
+  }
+  return null;
+}
+
+export function claudeAnswerHardCompletionGuidance() {
+  return (
+    `When it succeeds, return forUser if present, otherwise answer, exactly with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "When it fails, return the tool error without inventing a replacement result. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}
+
+export function claudeAnswerSoftCompletionGuidance() {
+  return (
+    "When it succeeds, return forUser if present, otherwise answer, faithfully as the answer. " +
+    "When it fails, return the tool error without inventing a replacement result. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}
+
+export function adapterAnswerHardCompletionGuidance() {
+  return (
+    `After the orchestration completes, return its single text output verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
+    "A successful output is forUser (else answer) exactly. A failure output preserves the error payload."
+  );
+}
+
+export function adapterAnswerSoftCompletionGuidance() {
+  return (
+    "After the orchestration completes, return its single text output as the answer. " +
+    "A successful output is forUser (else answer). A failure output preserves the error payload. " +
+    "Never invent or independently synthesize a replacement result."
+  );
+}

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;
+}