impel-cli 0.20.2 → 0.20.4

package/src/commands/remote.js

@@ -1,4 +1,7 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
 
 import { parseFlags } from "../args.js";
 import {
@@ -19,11 +22,18 @@ import {
   awsContext,
   describeTask,
   readStack,
+  startBrokerSshProxy,
   startSshProxy,
   startTask,
   stopTask,
   waitForTaskReady,
 } from "../remote/aws.js";
+import { isSessionsUUID, RemoteBrokerClient, newMutationKey } from "../remote/broker.js";
+import { prepareProviderCheckpoint, exactCheckpointRequiredMessage } from "../remote/checkpoint.js";
+import {
+  assertRemoteCommandContract,
+  capabilityFailureMessage,
+} from "../remote/contracts.js";
 import { requireExecutables, runCapture, runInteractive } from "../remote/process.js";
 import {
   initializeRun,
@@ -32,6 +42,7 @@ import {
   newRunId,
   readRunState,
   removeRunSecrets,
+  removeTransferArtifacts,
   removeSshAlias,
   resolveRunId,
   runPaths,
@@ -47,51 +58,74 @@ import {
   uploadRepository,
   waitForSsh,
 } from "../remote/transfer.js";
+import { recordPortableLegacyInvocation } from "../remote/telemetry.js";
+import { createWorkspaceArtifact } from "../remote/workspace.js";
 
 const DEFAULT_REGION = "eu-west-2";
 const DEFAULT_STACK = "impel-remote-dev";
 const DEFAULT_TTL_SECONDS = 3600;
 const DEFAULT_STARTUP_TIMEOUT_SECONDS = 300;
 const PROVIDERS = new Set(["claude", "codex"]);
+const LEGACY_MODE = "portable-legacy";
+const LEGACY_FLAG = "IMPEL_REMOTE_ENABLE_PORTABLE_LEGACY";
 
 const HELP = `impel remote - run an Impel session on an isolated AWS Fargate runner
 
 Usage:
-  impel remote up [path] [options]
+  impel remote dispatch [path] --provider codex|claude --mode fork|portable --session <sessions-uuid>
+  impel remote handoff [path] --provider codex --mode native --session <sessions-uuid>
   impel remote status [run-id] [--json]
+  impel remote viewer [run-id] [--json]
+  impel remote proxy <run-id> --port <port>
+  impel remote handback [run-id] --yes [--abandon]
+
+Legacy rollback commands (require ${LEGACY_FLAG}=1; removal scheduled for 2026-10-31):
+  impel remote up [path] --mode portable-legacy [options]
   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
 
-Lifecycle options:
+Broker lifecycle options:
   --provider <name>       Provider prepared for the run. Default: codex.
   --ttl <seconds>         Task lifetime from 300 through 86400. Default: 3600.
+  --timeout <seconds>     Runner startup timeout from 30 through 900. Default: 300.
+  --json                  Emit machine-readable state where supported.
+  --mode <mode>           Public modes: native, fork, or portable.
+  --source <surface>      Explicit source: desktop, cli, or app-server. Default: cli.
+  --broker <url>          Remote broker origin. Defaults to config remoteUrl/appUrl.
+  --checkpoint <path>     Closed exact provider archive for fork.
+  --checkpoint-manifest <path>  Closed capture manifest; CLI binds it to the broker run.
+  --session <uuid>        Required Sessions binding UUID for every brokered run.
+                          This is not a provider-native thread/session ID.
+
+Legacy rollback options:
   --region <region>       AWS region. Default: eu-west-2.
   --profile <profile>     AWS CLI profile. Defaults to AWS_PROFILE/current AWS config.
   --stack <name>          CloudFormation stack. Default: impel-remote-dev.
   --install auto|skip     Restore recognized lockfile dependencies. Default: auto.
   --setup <command>       Additional explicit setup command to run after transfer.
   --env <csv>             Explicit environment variable names to copy; none by default.
-  --timeout <seconds>     Runner startup timeout from 30 through 900. Default: 300.
-  --json                  Emit machine-readable state where supported.
+  --detach                Start the legacy remote worker and return immediately.
 
-Handoff options:
-  --detach                Start remote execution and return immediately.
+Migration rollback (temporary; removal scheduled for 2026-10-31):
+  --mode portable-legacy  Use the former one-shot worker only when
+                          ${LEGACY_FLAG}=1 is also set.
 
 Attach options:
-  --session <id>          Resume a transferred provider session.
+  --session <id>          Legacy attach: resume a transferred provider session.
   --fork                  Fork instead of continuing the transferred session.
   --desktop               Open the native desktop connection flow instead of a terminal.
 
+Native availability:
+  Codex Desktop and its SSH tunnel must remain awake and online for ChatGPT Remote.
+  Laptop-independent control requires Codex App Server or Claude through the Impel viewer.
+
 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. Handoff starts a headless worker inside Fargate and streams
-its structured events back; the local app is only the control/viewer process.
+gateway-backed Claude has no native arbitrary-host handoff. The former one-shot
+worker is not a handoff and is available only as the explicitly flagged,
+short-lived portable-legacy rollback mode.
 Credentials, ignored files, SSH agents, and environment variables are never
 copied implicitly.
 `;
@@ -118,6 +152,15 @@ function providerFlag(value, fallback = "codex") {
   return provider;
 }
 
+function sessionsUUIDFlag(value, action) {
+  if (!value) fail(`impel remote ${action}: --session <sessions-uuid> is required for every brokered run`);
+  const sessionId = String(value);
+  if (!isSessionsUUID(sessionId)) {
+    fail(`impel remote ${action}: --session must be a lowercase Sessions UUID, not a provider thread/session ID`);
+  }
+  return sessionId;
+}
+
 function rejectFlags(flags, allowed, action) {
   const unsupported = Object.keys(flags).find((name) => !allowed.has(name));
   if (unsupported) fail(`impel remote ${action}: unknown option --${unsupported}`);
@@ -130,16 +173,22 @@ function rejectMissingFlagValues(flags, spec, action) {
 
 function lifecycleSpec() {
   return {
+    broker: { type: "string" },
+    checkpoint: { type: "string" },
+    "checkpoint-manifest": { type: "string" },
+    "desktop-confirmed": { type: "boolean" },
     env: { type: "string" },
     detach: { type: "boolean" },
     help: { type: "boolean" },
     install: { type: "string" },
     json: { type: "boolean" },
+    mode: { type: "string" },
     profile: { type: "string" },
     provider: { type: "string" },
     region: { type: "string" },
     session: { type: "string" },
     setup: { type: "string" },
+    source: { type: "string" },
     stack: { type: "string" },
     timeout: { type: "string" },
     ttl: { type: "string" },
@@ -147,6 +196,258 @@ function lifecycleSpec() {
   };
 }
 
+function brokerClient(config, brokerOverride) {
+  return new RemoteBrokerClient({
+    baseUrl: normalizeGatewayUrl(brokerOverride || config.remoteUrl || config.appUrl || resolveDefaultAppUrl()),
+    pat: config.pat,
+  });
+}
+
+function brokerRunState(remote, prior = {}) {
+  const remoteState = remote.state || remote.status;
+  return {
+    ...prior,
+    runId: remote.runId,
+    backend: "broker",
+    alias: prior.alias || sshAlias(remote.runId),
+    status: remoteState,
+    provider: remote.provider || prior.provider,
+    mode: remote.mode || prior.mode,
+    sourceSurface: remote.sourceSurface || prior.sourceSurface,
+    session: remote.sessionId ? { provider: remote.provider || prior.provider, id: remote.sessionId } : prior.session || null,
+    createdAt: remote.createdAt || prior.createdAt,
+    expiresAt: remote.expiresAt || prior.expiresAt,
+    brokerUrl: prior.brokerUrl,
+    repository: prior.repository ? {
+      head: prior.repository.head,
+      branch: prior.repository.branch,
+      relativeProjectPath: prior.repository.relativeProjectPath,
+      remoteProjectPath: prior.repository.remoteProjectPath,
+    } : null,
+    remote: {
+      state: remoteState,
+      version: remote.version ?? null,
+      workspaceClosed: typeof remote.workspace?.closedAt === "string"
+        && Date.parse(remote.workspace.closedAt) > 0,
+      inputCheckpointClosed: typeof remote.inputCheckpoint?.closedAt === "string"
+        && Date.parse(remote.inputCheckpoint.closedAt) > 0,
+      taskState: remote.task?.state || null,
+      connectionState: remote.connection?.state || null,
+      reasonCode: remote.stateReason || remote.reasonCode || null,
+    },
+  };
+}
+
+function persistBrokerRun(remote, prior) {
+  return writeRunState(brokerRunState(remote, prior));
+}
+
+function sourceSurfaceFlag(value) {
+  return value || process.env.IMPEL_REMOTE_SOURCE_SURFACE || "cli";
+}
+
+function terminalBrokerState(state) {
+  return new Set(["stopped", "failed", "expired", "cancelled"]).has(state);
+}
+
+async function waitForDesktopConfirmation(flags) {
+  if (flags["desktop-confirmed"] === true) return;
+  console.log("Codex CLI native handoff first requires the same saved session in Desktop. Run `/app`, confirm that Desktop opened this chat, then continue.");
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail("impel remote handoff: Desktop confirmation is required; complete `/app`, then rerun with --source desktop (or --desktop-confirmed from a trusted interactive wrapper)");
+  }
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try { await prompt.question("Press Enter after Desktop shows the same chat: "); }
+  finally { prompt.close(); }
+}
+
+async function negotiateCapability(client, contract, flags) {
+  let current = contract;
+  let capability = await client.capability(current);
+  if (
+    current.provider === "codex" && current.mode === "native" && current.sourceSurface === "cli"
+    && !capability.supported && capability.reasonCode === "DESKTOP_HANDOFF_REQUIRED"
+  ) {
+    await waitForDesktopConfirmation(flags);
+    current = { ...current, sourceSurface: "desktop" };
+    capability = await client.capability(current);
+  }
+  if (!capability.supported) fail(`impel remote ${contract.action}: ${capabilityFailureMessage(capability)} No fallback was selected.`);
+  return { contract: current, capability };
+}
+
+async function waitForBrokerRun(client, state, timeoutSeconds, { json = false } = {}) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let lastState = state.status;
+  while (Date.now() < deadline) {
+    const remote = await client.getRun(state.runId);
+    state = persistBrokerRun(remote, state);
+    if (!json && state.status !== lastState) console.log(`Remote run ${state.runId}: ${state.status}`);
+    lastState = state.status;
+    if (new Set(["ready", "running"]).has(state.status)) return state;
+    if (terminalBrokerState(state.status)) {
+      throw new Error(`remote run ${state.runId} became ${state.status}${state.remote.reasonCode ? ` (${state.remote.reasonCode})` : ""}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, Number(process.env.IMPEL_REMOTE_BROKER_POLL_MS || 1000)));
+  }
+  throw new Error(`remote run ${state.runId} did not become ready within ${timeoutSeconds} seconds`);
+}
+
+function generateNativeSshKey() {
+  requireExecutables(["ssh-keygen", "session-manager-plugin"]);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "impel-native-ssh-"));
+  const privateKey = path.join(root, "id_ed25519");
+  runCapture(process.env.IMPEL_REMOTE_SSH_KEYGEN_BIN || "ssh-keygen", [
+    "-q", "-t", "ed25519", "-N", "", "-C", "impel-remote-native", "-f", privateKey,
+  ]);
+  const publicKey = fs.readFileSync(`${privateKey}.pub`, "utf8").trim();
+  if (!/^ssh-ed25519 [A-Za-z0-9+/]+={0,2}(?: [^\r\n]+)?$/u.test(publicKey)) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw new Error("ssh-keygen returned an invalid Ed25519 public key");
+  }
+  return { root, privateKey, publicKey: `${publicKey}\n` };
+}
+
+function retainNativeSshKey(generated, runId) {
+  const paths = initializeRun(runId);
+  fs.renameSync(generated.privateKey, paths.privateKey);
+  fs.renameSync(`${generated.privateKey}.pub`, paths.publicKey);
+  fs.writeFileSync(paths.knownHosts, "", { mode: 0o600 });
+  fs.rmSync(generated.root, { recursive: true, force: true });
+}
+
+async function createBrokerRun(argv, action) {
+  const spec = lifecycleSpec();
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set([
+    "broker", "checkpoint", "checkpoint-manifest", "desktop-confirmed", "help", "json", "mode", "provider", "session", "source", "timeout", "ttl",
+  ]), action);
+  rejectMissingFlagValues(flags, spec, action);
+  if (flags.help) { console.log(HELP); return null; }
+  if (positionals.length > 1) fail(`impel remote ${action}: expected at most one repository path`);
+  if (!flags.mode) {
+    fail(`impel remote ${action}: --mode is required; no legacy or fallback mode is selected implicitly`);
+  }
+  const contract = assertRemoteCommandContract({
+    action,
+    provider: providerFlag(flags.provider),
+    mode: flags.mode,
+    sourceSurface: sourceSurfaceFlag(flags.source),
+  });
+  const sessionId = sessionsUUIDFlag(flags.session, action);
+  if ((flags.checkpoint && !flags["checkpoint-manifest"]) || (!flags.checkpoint && flags["checkpoint-manifest"])) {
+    fail("impel remote dispatch: --checkpoint and --checkpoint-manifest must be provided together");
+  }
+  if (contract.mode === "fork" && !flags.checkpoint) fail(`impel remote dispatch: ${exactCheckpointRequiredMessage(contract.provider)}`);
+  if (contract.mode !== "fork" && flags.checkpoint) fail("impel remote: provider checkpoints are accepted only for --mode fork");
+  const config = requiredConfig();
+  const client = brokerClient(config, flags.broker);
+  const negotiated = await negotiateCapability(client, contract, flags);
+  const selected = await ensureTenantSelection(config, { refresh: !Array.isArray(config.scopes) });
+  assertProviderScopes(selected.scopes, [contract.provider], { requireLive: true });
+  const repository = inspectRepository(positionals[0] || process.cwd());
+  const ttlSeconds = integerFlag(flags.ttl, "ttl", DEFAULT_TTL_SECONDS, 300, 86400);
+  const timeoutSeconds = integerFlag(flags.timeout, "timeout", DEFAULT_STARTUP_TIMEOUT_SECONDS, 30, 900);
+  let generatedKey = null;
+  let state = null;
+  let cancelled = false;
+  let cancellation = null;
+  try {
+    if (negotiated.contract.mode === "native") generatedKey = generateNativeSshKey();
+    const remote = await client.createRun({
+      provider: negotiated.contract.provider,
+      mode: negotiated.contract.mode,
+      sourceSurface: negotiated.contract.sourceSurface,
+      sessionId,
+      ...(repository.relativeProjectPath !== "." ? { repositorySubdir: repository.relativeProjectPath } : {}),
+      ttlSeconds,
+      ...(generatedKey ? { sshPublicKey: generatedKey.publicKey } : {}),
+    }, newMutationKey("create"));
+    initializeRun(remote.runId);
+    if (generatedKey) {
+      retainNativeSshKey(generatedKey, remote.runId);
+      generatedKey = null;
+    }
+    state = persistBrokerRun(remote, {
+      runId: remote.runId,
+      backend: "broker",
+      brokerUrl: client.baseUrl,
+      provider: negotiated.contract.provider,
+      mode: negotiated.contract.mode,
+      sourceSurface: negotiated.contract.sourceSurface,
+      repository,
+      createdAt: new Date().toISOString(),
+    });
+    const onInterrupt = () => {
+      cancelled = true;
+      cancellation ||= client.cancelRun(state.runId, { reason: "client_interrupt" }, newMutationKey("sigint-cancel"))
+        .then((value) => { state = persistBrokerRun(value, state); })
+        .catch(() => {});
+    };
+    process.once("SIGINT", onInterrupt);
+    try {
+      if (negotiated.contract.mode !== "native") {
+        if (!flags.json) console.log("Capturing immutable workspace state…");
+        const workspace = createWorkspaceArtifact(repository, runPaths(state.runId).workspaceRoot);
+        state = persistBrokerRun(await client.uploadWorkspace(state.runId, workspace), state);
+        if (cancelled) throw new Error("remote run cancelled after interrupt");
+      }
+      if (negotiated.contract.mode === "fork") {
+        const checkpoint = prepareProviderCheckpoint({
+          archivePath: path.resolve(flags.checkpoint),
+          manifestPath: path.resolve(flags["checkpoint-manifest"]),
+          outputPath: runPaths(state.runId).providerCheckpoint,
+          provider: negotiated.contract.provider,
+          mode: "fork",
+          runId: state.runId,
+          sessionId,
+        });
+        state = persistBrokerRun(await client.uploadProviderCheckpoint(state.runId, checkpoint), state);
+      }
+      if (cancelled) throw new Error("remote run cancelled after interrupt");
+      state = await waitForBrokerRun(client, state, timeoutSeconds, { json: flags.json === true });
+      if (cancelled) throw new Error("remote run cancelled after interrupt");
+    } finally {
+      process.removeListener("SIGINT", onInterrupt);
+      if (cancellation) await cancellation;
+    }
+    if (negotiated.contract.mode === "native") installSshAlias(state);
+    removeTransferArtifacts(state.runId);
+    printRun(state, flags.json === true);
+    if (!flags.json && negotiated.contract.mode === "native") {
+      console.log("");
+      console.log(`In Codex Desktop, add/open SSH host ${state.alias} and project ${state.repository.remoteProjectPath}.`);
+      console.log("Use the chat footer run-location picker to move this chat. Active generation will be interrupted.");
+      console.log("Desktop and this tunnel must stay awake/online for ChatGPT Remote. Detached control requires App Server plus the Impel viewer.");
+      console.log(`For handback, select “This computer” in Desktop, wait for the remote child to exit, then run: impel remote handback ${state.runId} --yes`);
+    }
+    return state;
+  } catch (error) {
+    if (state && !terminalBrokerState(state.status)) {
+      try { state = persistBrokerRun(await client.cancelRun(state.runId, { reason: "client_setup_failed" }), state); } catch { /* Broker sweeper remains authoritative. */ }
+    }
+    if (state) {
+      removeSshAlias(state.runId);
+      removeRunSecrets(state.runId);
+    }
+    throw error;
+  } finally {
+    if (generatedKey) fs.rmSync(generatedKey.root, { recursive: true, force: true });
+  }
+}
+
+function requirePortableLegacy(flags, action) {
+  if (flags.mode !== LEGACY_MODE) {
+    const suffix = action === "handoff"
+      ? "The old one-shot worker did not transfer a live session. Use `--mode native` for a supported native handoff, or `impel remote dispatch --mode fork|portable`."
+      : "The direct AWS runner is now a rollback-only path. Use a broker-backed `handoff --mode native` or `dispatch --mode fork|portable`.";
+    fail(`impel remote ${action}: ${suffix}`);
+  }
+  if (process.env[LEGACY_FLAG] !== "1") {
+    fail(`impel remote ${action}: portable-legacy is disabled; set ${LEGACY_FLAG}=1 only for the temporary rollback path (removal 2026-10-31)`);
+  }
+}
+
 function requiredConfig() {
   const config = loadConfig();
   if (!config?.pat) fail("impel remote: not authenticated; run `impel setup` first");
@@ -218,6 +519,8 @@ async function createRemoteRun(options) {
     alias: sshAlias(runId),
     status: "preparing",
     provider,
+    mode: LEGACY_MODE,
+    legacyOnly: true,
     createdAt,
     expiresAt,
     ttlSeconds,
@@ -227,6 +530,7 @@ async function createRemoteRun(options) {
   let credential = null;
   let taskStarted = false;
   try {
+    recordPortableLegacyInvocation({ tenantId: selection.tenantId, runId });
     runCapture(process.env.IMPEL_REMOTE_SSH_KEYGEN_BIN || "ssh-keygen", [
       "-q", "-t", "ed25519", "-N", "", "-C", `impel-remote-${runId}`, "-f", paths.privateKey,
     ]);
@@ -342,10 +646,11 @@ async function cmdUp(argv, { dispatch = false } = {}) {
   const spec = lifecycleSpec();
   const { flags, positionals } = parseFlags(argv, spec);
   rejectFlags(flags, new Set([
-    "env", "help", "install", "json", "profile", "provider", "region", "session", "setup", "stack", "timeout", "ttl", "fork",
+    "env", "help", "install", "json", "mode", "profile", "provider", "region", "session", "setup", "stack", "timeout", "ttl", "fork",
   ]), dispatch ? "dispatch" : "up");
   rejectMissingFlagValues(flags, spec, dispatch ? "dispatch" : "up");
   if (flags.help) { console.log(HELP); return null; }
+  requirePortableLegacy(flags, dispatch ? "dispatch" : "up");
   if (positionals.length > 1) fail(`impel remote ${dispatch ? "dispatch" : "up"}: expected at most one repository path`);
   if (!dispatch && (flags.session || flags.fork)) fail("impel remote up: --session and --fork are only supported by `impel remote dispatch`");
   if (dispatch && !flags.session) fail("impel remote dispatch: --session is required");
@@ -417,19 +722,55 @@ async function cmdStatus(argv) {
   if (flags.help) { console.log(HELP); return; }
   if (positionals.length > 1) fail("impel remote status: expected at most one run id");
   if (!positionals[0] && flags.json) {
-    const states = listRunStates().map((state) => {
-      try { return syncTaskStatus(state); } catch (error) {
-        return { ...state, statusError: redactSecretText(error?.message || error) };
+    const states = [];
+    const config = loadConfig();
+    for (const local of listRunStates()) {
+      try {
+        states.push(local.backend === "broker"
+          ? persistBrokerRun(await brokerClient(config, local.brokerUrl).getRun(local.runId), local)
+          : syncTaskStatus(local));
+      } catch (error) {
+        states.push({ ...local, statusError: redactSecretText(error?.message || error) });
       }
-    });
+    }
     console.log(JSON.stringify(states, null, 2));
     return;
   }
   const runId = resolveRunId(positionals[0], { includeStopped: true });
-  const state = syncTaskStatus(readRunState(runId));
+  let state = readRunState(runId);
+  if (state.backend === "broker") {
+    const config = requiredConfig();
+    state = persistBrokerRun(await brokerClient(config, state.brokerUrl).getRun(runId), state);
+  } else {
+    state = syncTaskStatus(state);
+  }
   printRun(state, flags.json === true);
 }
 
+async function cmdViewer(argv) {
+  const spec = { json: { type: "boolean" }, help: { type: "boolean" } };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["help", "json"]), "viewer");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length > 1) fail("impel remote viewer: expected at most one run id");
+  let state = readRunState(resolveRunId(positionals[0]));
+  if (state.backend !== "broker") fail("impel remote viewer: the legacy runner has no Impel viewer");
+  const config = requiredConfig();
+  const client = brokerClient(config, state.brokerUrl);
+  state = persistBrokerRun(await client.getRun(state.runId), state);
+  if (state.status !== "running") {
+    fail(`impel remote viewer: run ${state.runId} is ${state.status}, not running`);
+  }
+  const viewer = await client.createViewerLink(state.runId);
+  if (flags.json) {
+    console.log(JSON.stringify({ runId: state.runId, ...viewer }, null, 2));
+    return;
+  }
+  console.log(`Viewer link (one-time, expires ${viewer.expiresAt}):`);
+  console.log(viewer.url);
+  console.log("The exchange secret stays in the URL fragment and is removed by the viewer after exchange.");
+}
+
 function shellQuote(value) {
   return `'${String(value).replaceAll("'", `'"'"'`)}'`;
 }
@@ -492,7 +833,7 @@ async function cmdAttach(argv) {
   if (exitCode !== 0) process.exitCode = exitCode;
 }
 
-async function cmdDispatch(argv) {
+async function cmdLegacyDispatch(argv) {
   const state = await cmdUp(argv, { dispatch: true });
   if (!state) return;
   const { flags } = parseFlags(argv, lifecycleSpec());
@@ -561,14 +902,15 @@ async function followRemoteWorker(state) {
   return { state: cleaned.state, completed: true };
 }
 
-async function cmdHandoff(argv) {
+async function cmdLegacyHandoff(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",
+    "detach", "env", "help", "install", "json", "mode", "profile", "provider", "region", "session", "setup", "stack", "timeout", "ttl",
   ]), "handoff");
   rejectMissingFlagValues(flags, spec, "handoff");
   if (flags.help) { console.log(HELP); return; }
+  requirePortableLegacy(flags, "handoff");
   if (positionals.length > 1) fail("impel remote handoff: expected at most one repository path");
   if (!flags.session) fail("impel remote handoff: --session is required");
 
@@ -603,6 +945,18 @@ async function cmdHandoff(argv) {
   await followRemoteWorker(state);
 }
 
+async function cmdDispatch(argv) {
+  const { flags } = parseFlags(argv, lifecycleSpec());
+  if (flags.mode === LEGACY_MODE) return cmdLegacyDispatch(argv);
+  return createBrokerRun(argv, "dispatch");
+}
+
+async function cmdHandoff(argv) {
+  const { flags } = parseFlags(argv, lifecycleSpec());
+  if (flags.mode === LEGACY_MODE) return cmdLegacyHandoff(argv);
+  return createBrokerRun(argv, "handoff");
+}
+
 async function cmdFollow(argv) {
   const spec = { help: { type: "boolean" } };
   const { flags, positionals } = parseFlags(argv, spec);
@@ -631,13 +985,22 @@ async function cmdDown(argv) {
     : [readRunState(resolveRunId(positionals[0], { includeStopped: true }))];
   const config = loadConfig();
   for (let state of states) {
+    if (state.backend === "broker") {
+      if (!config?.pat) fail("impel remote down: not authenticated; run `impel setup` first");
+      const remote = await brokerClient(config, state.brokerUrl).stopRun(state.runId, { reason: "user_stop", abandon: true });
+      state = persistBrokerRun(remote, state);
+      removeSshAlias(state.runId);
+      if (terminalBrokerState(state.status)) removeRunSecrets(state.runId);
+      console.log(`Remote run ${state.runId} is ${state.status}; broker cleanup and credential revocation are authoritative.`);
+      continue;
+    }
     const cleaned = await stopAndCleanRun(config, state);
     state = cleaned.state;
     printCleanupResult(state, cleaned.revokeError);
   }
 }
 
-function cmdProxy(argv) {
+async function cmdProxy(argv) {
   const spec = {
     help: { type: "boolean" },
     port: { type: "string" },
@@ -650,13 +1013,52 @@ function cmdProxy(argv) {
   const port = integerFlag(flags.port, "port", 22, 1, 65535);
   if (port !== 22) fail("impel remote proxy: the runner only exposes SSH port 22");
   const state = readRunState(positionals[0]);
-  if (state.status === "stopped" || state.status === "failed") {
+  if (state.backend === "broker" ? terminalBrokerState(state.status) : state.status === "stopped" || state.status === "failed") {
     fail(`impel remote proxy: run ${state.runId} is ${state.status}`);
   }
-  const exitCode = startSshProxy(awsContext(state), state, port);
+  let exitCode;
+  if (state.backend === "broker") {
+    const config = requiredConfig();
+    const client = brokerClient(config, state.brokerUrl);
+    const connection = await client.createConnection(state.runId);
+    try {
+      exitCode = startBrokerSshProxy(connection);
+    } finally {
+      try { await client.closeConnection(state.runId, connection.leaseId); }
+      catch { exitCode ||= 1; }
+    }
+  } else {
+    exitCode = startSshProxy(awsContext(state), state, port);
+  }
   if (exitCode !== 0) process.exitCode = exitCode;
 }
 
+async function cmdHandback(argv) {
+  const spec = { abandon: { type: "boolean" }, help: { type: "boolean" }, yes: { type: "boolean" } };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["abandon", "help", "yes"]), "handback");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length > 1) fail("impel remote handback: expected at most one run id");
+  if (flags.yes !== true) {
+    fail("impel remote handback: first select “This computer” in Desktop and wait for the remote child to exit, then confirm with --yes");
+  }
+  let state = readRunState(resolveRunId(positionals[0], { includeStopped: true }));
+  if (state.backend !== "broker" || state.mode !== "native") fail("impel remote handback: run is not a broker-backed native handoff");
+  const config = requiredConfig();
+  const client = brokerClient(config, state.brokerUrl);
+  const remote = flags.abandon
+    ? await client.stopRun(state.runId, { reason: "user_abandon", abandon: true })
+    : await client.handbackRun(state.runId);
+  state = persistBrokerRun(remote, state);
+  if (terminalBrokerState(state.status)) {
+    removeSshAlias(state.runId);
+    removeRunSecrets(state.runId);
+    console.log(`Native run ${state.runId} is ${state.status}; its remote writer lease and credential are closed.`);
+  } else {
+    console.log(`Handback confirmation recorded for ${state.runId}; state is ${state.status}. The broker will stop only after the remote child/SSH signal also closes.`);
+  }
+}
+
 export async function cmdRemote(argv) {
   const [action, ...rest] = argv;
   try {
@@ -669,12 +1071,14 @@ export async function cmdRemote(argv) {
         return;
       case "up": return await cmdUp(rest);
       case "status": return await cmdStatus(rest);
+      case "viewer": return await cmdViewer(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);
+      case "handback": return await cmdHandback(rest);
+      case "proxy": return await cmdProxy(rest);
       default: fail(`impel remote: unknown subcommand ${JSON.stringify(action)}`);
     }
   } catch (error) {