impel-cli 0.19.3 → 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.3",
+  "version": "0.20.0",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

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";
@@ -266,7 +272,9 @@ 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.
-export const CURRENT_CONFIG_VERSION = 26;
+// 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,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -807,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");
@@ -1153,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)) {
@@ -1166,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,
@@ -1256,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,
@@ -1296,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");
@@ -1469,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);
@@ -1479,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/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/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;
+}