impel-cli 0.18.17 → 0.19.0

package/README.md

@@ -180,6 +180,68 @@ impel claude --model opus
 impel codex exec "review this repository"
 ```
 
+## Remote Fargate sessions
+
+Start a disposable AWS Fargate runner for the current Git repository:
+
+```sh
+impel remote up --provider codex
+```
+
+The command creates a one-day, provider-scoped disposable PAT, starts the
+TTL-bounded task, installs a concrete SSH alias, transfers Git history plus the
+tracked and nonignored working tree, restores recognized Node/Python lockfile
+dependencies, and uploads the disposable credential only through encrypted
+SSH. The user's stored PAT, ignored files, SSH agent, Keychain, and environment
+are not copied. Select variables explicitly when they are genuinely required:
+
+```sh
+impel remote up --provider claude --env API_HOST,FEATURE_FLAG
+```
+
+Use the remote session from a terminal:
+
+```sh
+impel remote status
+impel remote attach --provider codex
+impel remote attach --provider claude
+```
+
+For Codex Desktop on macOS, open the native connection flow:
+
+```sh
+impel remote attach --provider codex --desktop
+```
+
+Save `/workspace/repo` as the remote project. In an existing Codex chat, use
+the footer's run-location picker and choose the generated SSH host. Codex then
+uses its supported SSH app-server transport to move the chat and Git state and
+stream prompts, approvals, tools, diffs, and output in the local app.
+
+Claude Desktop can open a new native SSH session on the same alias. Claude does
+not expose an arbitrary-host equivalent of Codex's exact chat handoff. To move
+an existing Impel Claude/Codex CLI session, checkpoint it and create a remote
+continuation or fork:
+
+```sh
+impel remote dispatch --provider claude --session <session-id> --fork
+impel remote dispatch --provider codex --session <session-id> --fork
+```
+
+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
+`impel-sessions`. Stop the task and revoke its credential when finished:
+
+```sh
+impel remote down --yes
+```
+
+The current lifecycle client requires macOS or Linux, OpenSSH, the AWS CLI, the
+AWS Session Manager plugin, and permission to use the deployed
+`impel-remote-dev` stack. Use `impel remote help` for region, profile, TTL,
+dependency, and setup overrides.
+
 Changing the selected tenant does not install, remove, or rewrite any other
 tenant. It changes only the default used by CLI launches and selected-tenant
 workspace commands.

package/package.json

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

package/src/cli.js

@@ -20,6 +20,7 @@ import { cmdUpdate } from "./commands/update.js";
 import { cmdNuke } from "./commands/nuke.js";
 import { cmdExperimental } from "./commands/experimental.js";
 import { cmdConverge } from "./commands/converge.js";
+import { cmdRemote } from "./commands/remote.js";
 import { ensureMacDeveloperTools } from "./macDeveloperTools.js";
 import { refuseElevatedMacExecution } from "./privileges.js";
 
@@ -34,6 +35,7 @@ Get started:
 Work:
   impel claude [args...]                      Launch Claude Code with an isolated Impel profile
   impel codex [args...]                       Launch Codex with an isolated Impel profile
+  impel remote up|status|attach|down          Run a local repository on AWS Fargate
   impel tenant list                           List accessible organizations
   impel tenant current                        Show the CLI's current organization
   impel tenant use <org>                      Select the organization for CLI launches
@@ -120,6 +122,9 @@ export async function main(argv) {
     case "codex":
       return cmdLaunch(cmd, rest);
 
+    case "remote":
+      return cmdRemote(rest);
+
     case "status":
       return cmdStatus();
 

package/src/commands/pat.js

@@ -302,7 +302,7 @@ async function requestControlPlane({ appUrl, currentPat, path, method, body, fea
   return payload;
 }
 
-async function createPat({ appUrl, currentPat, body }) {
+export async function createPat({ appUrl, currentPat, body }) {
   const payload = await requestControlPlane({
     appUrl,
     currentPat,
@@ -318,7 +318,7 @@ async function createPat({ appUrl, currentPat, body }) {
   return created;
 }
 
-async function revokePat({ appUrl, currentPat, tokenId }) {
+export async function revokePat({ appUrl, currentPat, tokenId }) {
   await requestControlPlane({
     appUrl,
     currentPat,

package/src/commands/remote.js

@@ -0,0 +1,559 @@
+import fs from "node:fs";
+
+import { parseFlags } from "../args.js";
+import {
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultAppUrl,
+  resolveDefaultGateway,
+} from "../config.js";
+import { createPat, revokePat } from "./pat.js";
+import {
+  assertProviderScopes,
+  ensureTenantSelection,
+  PAT_SCOPE_CLAUDE,
+  PAT_SCOPE_CODEX,
+} from "../tenants.js";
+import {
+  awsContext,
+  describeTask,
+  readStack,
+  startSshProxy,
+  startTask,
+  stopTask,
+  waitForTaskReady,
+} from "../remote/aws.js";
+import { requireExecutables, runCapture, runInteractive } from "../remote/process.js";
+import {
+  initializeRun,
+  installSshAlias,
+  listRunStates,
+  newRunId,
+  readRunState,
+  removeRunSecrets,
+  removeSshAlias,
+  resolveRunId,
+  runPaths,
+  sshAlias,
+  writeRunState,
+} from "../remote/state.js";
+import {
+  createRepositoryTransfer,
+  inspectRepository,
+  prepareWorkspace,
+  transferSessionCheckpoint,
+  uploadRemoteConfiguration,
+  uploadRepository,
+  waitForSsh,
+} from "../remote/transfer.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 HELP = `impel remote - run an Impel session on an isolated AWS Fargate runner
+
+Usage:
+  impel remote up [path] [options]
+  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 proxy <run-id> --port <port>
+  impel remote down [run-id] --yes
+  impel remote down --all --yes
+
+Lifecycle options:
+  --provider <name>       Provider prepared for the run. Default: codex.
+  --ttl <seconds>         Task lifetime from 300 through 86400. Default: 3600.
+  --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.
+
+Attach options:
+  --session <id>          Resume a transferred provider session.
+  --fork                  Fork instead of continuing the transferred session.
+  --desktop               Open the native desktop connection flow instead of a terminal.
+
+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.
+`;
+
+class RemoteCommandError extends Error {}
+
+function fail(message) {
+  throw new RemoteCommandError(message);
+}
+
+function integerFlag(value, name, fallback, minimum, maximum) {
+  if (value === undefined) return fallback;
+  if (!/^\d+$/u.test(String(value))) fail(`impel remote: --${name} must be an integer from ${minimum} through ${maximum}`);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
+    fail(`impel remote: --${name} must be an integer from ${minimum} through ${maximum}`);
+  }
+  return number;
+}
+
+function providerFlag(value, fallback = "codex") {
+  const provider = String(value || fallback).trim().toLowerCase();
+  if (!PROVIDERS.has(provider)) fail("impel remote: --provider must be codex or claude");
+  return provider;
+}
+
+function rejectFlags(flags, allowed, action) {
+  const unsupported = Object.keys(flags).find((name) => !allowed.has(name));
+  if (unsupported) fail(`impel remote ${action}: unknown option --${unsupported}`);
+}
+
+function rejectMissingFlagValues(flags, spec, action) {
+  const missing = Object.keys(flags).find((name) => spec[name]?.type === "string" && flags[name] === undefined);
+  if (missing) fail(`impel remote ${action}: --${missing} requires a value`);
+}
+
+function lifecycleSpec() {
+  return {
+    env: { type: "string" },
+    help: { type: "boolean" },
+    install: { type: "string" },
+    json: { type: "boolean" },
+    profile: { type: "string" },
+    provider: { type: "string" },
+    region: { type: "string" },
+    session: { type: "string" },
+    setup: { type: "string" },
+    stack: { type: "string" },
+    timeout: { type: "string" },
+    ttl: { type: "string" },
+    fork: { type: "boolean" },
+  };
+}
+
+function requiredConfig() {
+  const config = loadConfig();
+  if (!config?.pat) fail("impel remote: not authenticated; run `impel setup` first");
+  return {
+    ...config,
+    appUrl: normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl()),
+    gatewayUrl: normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway()),
+  };
+}
+
+function credentialScopes(provider) {
+  return provider === "claude" ? [PAT_SCOPE_CLAUDE] : [PAT_SCOPE_CODEX];
+}
+
+function cleanTransferArtifacts(runId) {
+  const paths = runPaths(runId);
+  for (const target of [paths.bundle, paths.fileList, paths.archive, paths.deletedList]) {
+    try { fs.rmSync(target, { force: true }); } catch { /* Best effort after a successful upload. */ }
+  }
+}
+
+async function revokeRunCredential(config, state, { tolerateFailure = false } = {}) {
+  if (!state?.credential?.tokenId || state.credential.revokedAt) return state;
+  try {
+    await revokePat({
+      appUrl: normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl()),
+      currentPat: config.pat,
+      tokenId: state.credential.tokenId,
+    });
+    return writeRunState({
+      ...state,
+      credential: { ...state.credential, revokedAt: new Date().toISOString() },
+    });
+  } catch (error) {
+    if (!tolerateFailure) throw error;
+    return writeRunState({
+      ...state,
+      credential: {
+        ...state.credential,
+        revokeError: redactSecretText(error?.message || error),
+      },
+    });
+  }
+}
+
+async function createRemoteRun(options) {
+  if (process.platform === "win32") {
+    fail("impel remote lifecycle is not yet supported on Windows; use macOS or Linux with OpenSSH and the AWS Session Manager plugin");
+  }
+  requireExecutables(["aws", "git", "session-manager-plugin", "ssh", "ssh-keygen", "tar"]);
+  const provider = providerFlag(options.provider);
+  const ttlSeconds = integerFlag(options.ttl, "ttl", DEFAULT_TTL_SECONDS, 300, 86400);
+  const startupTimeout = integerFlag(options.timeout, "timeout", DEFAULT_STARTUP_TIMEOUT_SECONDS, 30, 900);
+  const config = requiredConfig();
+  const selection = await ensureTenantSelection(config, { refresh: !Array.isArray(config.scopes) });
+  assertProviderScopes(selection.scopes, [provider], { requireLive: true });
+  const repository = inspectRepository(options.path || process.cwd());
+  const runId = newRunId();
+  const paths = initializeRun(runId);
+  const createdAt = new Date().toISOString();
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString();
+  const context = awsContext({
+    region: options.region || process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || DEFAULT_REGION,
+    profile: options.profile || process.env.AWS_PROFILE || null,
+    stackName: options.stack || DEFAULT_STACK,
+  });
+  let state = writeRunState({
+    runId,
+    alias: sshAlias(runId),
+    status: "preparing",
+    provider,
+    createdAt,
+    expiresAt,
+    ttlSeconds,
+    aws: { ...context },
+    repository,
+  });
+  let credential = null;
+  let taskStarted = false;
+  try {
+    runCapture(process.env.IMPEL_REMOTE_SSH_KEYGEN_BIN || "ssh-keygen", [
+      "-q", "-t", "ed25519", "-N", "", "-C", `impel-remote-${runId}`, "-f", paths.privateKey,
+    ]);
+    fs.writeFileSync(paths.knownHosts, "", { mode: 0o600 });
+    createRepositoryTransfer(state, repository);
+
+    credential = await createPat({
+      appUrl: config.appUrl,
+      currentPat: config.pat,
+      body: {
+        orgId: selection.tenantId,
+        label: `Remote · ${runId}`,
+        scopes: credentialScopes(provider),
+        ttlDays: 1,
+      },
+    });
+    state = writeRunState({
+      ...state,
+      credential: {
+        tokenId: credential.tokenId,
+        expiresAt: credential.expiresAt === null ? null : new Date(credential.expiresAt).toISOString(),
+        scopes: credential.scopes,
+      },
+    });
+
+    const outputs = readStack(context);
+    const publicKey = fs.readFileSync(paths.publicKey, "utf8");
+    const started = startTask(context, { outputs, publicKey, ttlSeconds, runId });
+    taskStarted = true;
+    state = writeRunState({
+      ...state,
+      status: "starting",
+      aws: {
+        ...state.aws,
+        clusterName: started.clusterName,
+        taskArn: started.taskArn,
+        taskDefinitionArn: outputs.TaskDefinitionArn,
+      },
+    });
+    const ready = await waitForTaskReady(context, state, startupTimeout);
+    state = writeRunState({
+      ...state,
+      status: "bootstrapping",
+      aws: { ...state.aws, ...ready },
+    });
+    installSshAlias(state);
+    await waitForSsh(state, Math.min(startupTimeout, 180));
+    uploadRemoteConfiguration(state, {
+      config,
+      credential,
+      tenant: selection,
+      environmentNames: String(options.env || "").split(",").map((name) => name.trim()).filter(Boolean),
+    });
+    uploadRepository(state, repository);
+    if (options.session) {
+      transferSessionCheckpoint(state, {
+        provider,
+        sessionId: options.session,
+        tenantId: selection.tenantId,
+      });
+    }
+    prepareWorkspace(state, {
+      installMode: options.install || "auto",
+      setupCommand: options.setup || null,
+    });
+    state = writeRunState({
+      ...state,
+      status: "running",
+      readyAt: new Date().toISOString(),
+      session: options.session ? { provider, id: options.session, fork: options.fork === true } : null,
+    });
+    cleanTransferArtifacts(runId);
+    return state;
+  } catch (error) {
+    let cleanupError = null;
+    if (taskStarted) {
+      try { stopTask(context, state, "Impel remote startup failed"); } catch (stopError) { cleanupError = stopError; }
+    }
+    removeSshAlias(runId);
+    if (credential) {
+      try { state = await revokeRunCredential(config, state); } catch (revokeError) { cleanupError ||= revokeError; }
+    }
+    removeRunSecrets(runId);
+    writeRunState({
+      ...state,
+      status: "failed",
+      failedAt: new Date().toISOString(),
+      error: redactSecretText(error?.message || error),
+      ...(cleanupError ? { cleanupError: redactSecretText(cleanupError?.message || cleanupError) } : {}),
+    });
+    throw error;
+  }
+}
+
+function printRun(state, json = false) {
+  if (json) {
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+  console.log(`Remote run ${state.runId} is ${state.status}.`);
+  console.log(`SSH alias: ${state.alias}`);
+  console.log(`Project:   ${state.repository.remoteProjectPath}`);
+  console.log(`Expires:   ${state.expiresAt}`);
+  if (state.status === "running") {
+    console.log("");
+    console.log(`Terminal:  impel remote attach ${state.runId} --provider ${state.provider}`);
+    const appLabel = state.provider === "codex" ? "Codex app" : "Claude app";
+    console.log(`${appLabel}: impel remote attach ${state.runId} --provider ${state.provider} --desktop`);
+  }
+}
+
+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",
+  ]), dispatch ? "dispatch" : "up");
+  rejectMissingFlagValues(flags, spec, dispatch ? "dispatch" : "up");
+  if (flags.help) { console.log(HELP); return null; }
+  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");
+  const state = await createRemoteRun({ ...flags, path: positionals[0] });
+  printRun(state, flags.json === true);
+  return state;
+}
+
+function syncTaskStatus(state) {
+  if (!state?.aws?.taskArn || ["failed", "stopped"].includes(state.status)) return state;
+  const context = awsContext(state);
+  const remote = describeTask(context, state);
+  const status = remote.lastStatus === "STOPPED"
+    ? "stopped"
+    : state.status;
+  return writeRunState({
+    ...state,
+    status,
+    ...(status === "stopped" && !state.stoppedAt ? { stoppedAt: new Date().toISOString() } : {}),
+    aws: { ...state.aws, ...remote },
+  });
+}
+
+async function cmdStatus(argv) {
+  const spec = { json: { type: "boolean" }, help: { type: "boolean" } };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["help", "json"]), "status");
+  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) };
+      }
+    });
+    console.log(JSON.stringify(states, null, 2));
+    return;
+  }
+  const runId = resolveRunId(positionals[0], { includeStopped: true });
+  const state = syncTaskStatus(readRunState(runId));
+  printRun(state, flags.json === true);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function providerCommand(provider, { session, fork }) {
+  if (provider === "codex") {
+    if (!session) return ["codex"];
+    return ["codex", fork ? "fork" : "resume", session];
+  }
+  return [
+    "claude",
+    ...(session ? ["--resume", session] : []),
+    ...(fork ? ["--fork-session"] : []),
+  ];
+}
+
+function openDesktop(state, provider) {
+  if (process.platform !== "darwin") {
+    fail("impel remote attach --desktop currently supports macOS; use the printed SSH alias in the desktop app on other platforms");
+  }
+  if (provider === "codex") {
+    const uri = `codex://settings/connections/ssh/add?name=${encodeURIComponent(state.alias)}`;
+    runCapture("open", [uri]);
+    console.log(`Opened Codex SSH connection setup for ${state.alias}.`);
+    console.log(`Save ${state.repository.remoteProjectPath} as the remote project, then use the chat footer's run-location picker to hand off the chat.`);
+    return;
+  }
+  runCapture("open", ["-a", "Claude"]);
+  console.log(`Opened Claude. Choose the environment menu, Add SSH connection, and select ${state.alias}.`);
+  console.log("Claude can start a native SSH session there; use `impel remote dispatch` to checkpoint and fork an existing Claude CLI session.");
+}
+
+async function cmdAttach(argv) {
+  const spec = {
+    desktop: { type: "boolean" },
+    fork: { type: "boolean" },
+    help: { type: "boolean" },
+    provider: { type: "string" },
+    session: { type: "string" },
+  };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["desktop", "fork", "help", "provider", "session"]), "attach");
+  rejectMissingFlagValues(flags, spec, "attach");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length > 1) fail("impel remote attach: expected at most one run id");
+  const state = syncTaskStatus(readRunState(resolveRunId(positionals[0])));
+  if (state.status !== "running") fail(`impel remote attach: run ${state.runId} is ${state.status}, not running`);
+  const provider = providerFlag(flags.provider, state.provider);
+  const requiredScope = credentialScopes(provider)[0];
+  if (!state.credential?.scopes?.includes(requiredScope)) {
+    fail(`impel remote attach: run ${state.runId} was scoped for ${state.provider}, not ${provider}; start a ${provider} run instead`);
+  }
+  if (flags.desktop) return openDesktop(state, provider);
+  const session = flags.session || state.session?.id || null;
+  const fork = flags.fork === true || state.session?.fork === true;
+  if (fork && !session) fail("impel remote attach: --fork requires --session");
+  const command = providerCommand(provider, { session, fork });
+  const remoteCommand = `cd ${shellQuote(state.repository.remoteProjectPath)} && exec ${command.map(shellQuote).join(" ")}`;
+  const exitCode = runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", ["-t", state.alias, remoteCommand], { allowFailure: true });
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+async function cmdDispatch(argv) {
+  const state = await cmdUp(argv, { dispatch: true });
+  if (!state) return;
+  const { flags } = parseFlags(argv, lifecycleSpec());
+  if (flags.json) return;
+  await cmdAttach([
+    state.runId,
+    "--provider", state.provider,
+    "--session", state.session.id,
+    ...(state.session.fork ? ["--fork"] : []),
+  ]);
+}
+
+async function cmdDown(argv) {
+  const { flags, positionals } = parseFlags(argv, {
+    all: { type: "boolean" },
+    help: { type: "boolean" },
+    yes: { type: "boolean" },
+  });
+  rejectFlags(flags, new Set(["all", "help", "yes"]), "down");
+  if (flags.help) { console.log(HELP); return; }
+  if (flags.yes !== true) fail("impel remote down: refusing to stop the task and revoke its credential without --yes");
+  if (flags.all && positionals.length > 0) fail("impel remote down: use a run id or --all, not both");
+  if (positionals.length > 1) fail("impel remote down: expected at most one run id");
+  const states = flags.all
+    ? listRunStates().filter((state) => state.status !== "stopped")
+    : [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.`);
+    }
+  }
+}
+
+function cmdProxy(argv) {
+  const spec = {
+    help: { type: "boolean" },
+    port: { type: "string" },
+  };
+  const { flags, positionals } = parseFlags(argv, spec);
+  rejectFlags(flags, new Set(["help", "port"]), "proxy");
+  rejectMissingFlagValues(flags, spec, "proxy");
+  if (flags.help) { console.log(HELP); return; }
+  if (positionals.length !== 1) fail("impel remote proxy: a run id is required");
+  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") {
+    fail(`impel remote proxy: run ${state.runId} is ${state.status}`);
+  }
+  const exitCode = startSshProxy(awsContext(state), state, port);
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+export async function cmdRemote(argv) {
+  const [action, ...rest] = argv;
+  try {
+    switch (action) {
+      case undefined:
+      case "help":
+      case "--help":
+      case "-h":
+        console.log(HELP);
+        return;
+      case "up": return await cmdUp(rest);
+      case "status": return await cmdStatus(rest);
+      case "attach": return await cmdAttach(rest);
+      case "dispatch": return await cmdDispatch(rest);
+      case "down": return await cmdDown(rest);
+      case "proxy": return cmdProxy(rest);
+      default: fail(`impel remote: unknown subcommand ${JSON.stringify(action)}`);
+    }
+  } catch (error) {
+    if (error instanceof RemoteCommandError) {
+      console.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    console.error(`impel remote: ${redactSecretText(error?.message || error)}`);
+    process.exitCode = 1;
+  }
+}