impel-cli 0.19.3 → 0.20.0-beta.0

package/src/cliProfiles.js

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

package/src/commands/launch.js

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

package/src/commands/mcp.js

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

package/src/commands/remote.js

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