@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/outposts.ts

@@ -1,1935 +0,0 @@
-/**
- * `hq outposts` — manage your personal HQ Outposts (EC2 boxes) from the
- * terminal instead of the web console. Targets the hq-pro `/outpost/*`
- * control plane on `DEFAULT_VAULT_API_URL` via the shared `vaultApiFetch`
- * helper — the same routes the console's outpost panel calls.
- *
- * Outposts are PERSONAL / caller-scoped: hq-pro keys every `/outpost/*` route
- * on the caller's Cognito sub, so there is no `--company`. `--id <outpostId>`
- * selects a specific box (passed as the `outpostId` query param); when omitted
- * hq-pro targets the caller's primary slot.
- *
- * Subcommands:
- *   hq outposts list                — every Outpost you own (row summaries)
- *   hq outposts status [--id]       — live detail for one box
- *   hq outposts codex-enable [--id] — enable / retry Codex on the box
- *   hq outposts login [--id]        — request a fresh login URL
- *   hq outposts destroy [--id] --yes — tear the box down (destructive; flag-guarded)
- *
- * NOTE: hq-pro exposes no rename or settings-mutation route for Outposts (the
- * web console can't rename them either), so this CLI wraps only the lifecycle
- * and status routes that exist. Renaming an Outpost is not a backend capability.
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import * as readline from "node:readline";
-import { randomBytes } from "node:crypto";
-import * as yaml from "js-yaml";
-import { loadCachedTokens } from "@indigoai-us/hq-cloud";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
-import { registerHeartbeatCommand } from "./outposts-heartbeat.js";
-import {
-  OUTPOST_PRICE_CENTS,
-  confirmChargeOrExit,
-  parseBillingPayload,
-  surfaceBillingBlocked,
-  type BillingErrorPayload,
-} from "../utils/billing-gate.js";
-
-/**
- * hq-pro's per-person cap envelope on a `409` provision block. Unlike every
- * other `/outpost/*` failure this body carries NO `message`/`error` field —
- * only the cap facts — so it has to be decoded structurally or the reason
- * degrades to a bare `res.statusText` ("Conflict").
- */
-export interface OutpostCappedPayload {
-  limit: number;
-  outposts: OutpostSummary[];
-}
-
-/** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
-export function parseCappedPayload(
-  body: unknown,
-): OutpostCappedPayload | undefined {
-  if (!body || typeof body !== "object") return undefined;
-  const b = body as { capped?: unknown; limit?: unknown; outposts?: unknown };
-  if (b.capped !== true) return undefined;
-  return {
-    limit: typeof b.limit === "number" ? b.limit : 0,
-    outposts: Array.isArray(b.outposts) ? (b.outposts as OutpostSummary[]) : [],
-  };
-}
-
-/** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
-export class OutpostHttpError extends Error {
-  status: number;
-  step?: string;
-  /** hq-pro's billing envelope on a `402 billing_required` provision block. */
-  billing?: BillingErrorPayload;
-  /** hq-pro's cap envelope on a `409` provision block. */
-  capped?: OutpostCappedPayload;
-  constructor(
-    status: number,
-    message: string,
-    step?: string,
-    billing?: BillingErrorPayload,
-    capped?: OutpostCappedPayload,
-  ) {
-    super(message);
-    this.name = "OutpostHttpError";
-    this.status = status;
-    this.step = step;
-    this.billing = billing;
-    this.capped = capped;
-  }
-}
-
-/** Row summary from `GET /outpost/list`. */
-export interface OutpostSummary {
-  outpostId: string;
-  state: string;
-  instanceName: string;
-  region: string;
-  agentRuntime: string;
-  platform: string;
-  createdAt: string;
-  [key: string]: unknown;
-}
-
-/**
- * Authenticated JSON round-trip against the outpost control plane. Throws
- * `OutpostHttpError` on any non-2xx (never swallows — hq-never-swallow-errors),
- * decoding hq-pro's `{ error | message, step }` envelope for the reason. The
- * `step` is preserved so callers can recognise the `destroy` route's
- * `teardown-incomplete` 409 (which means "retry", not "failed").
- */
-export async function outpostRequest<T>(opts: {
-  token: string;
-  path: string;
-  method?: string;
-  body?: Record<string, unknown>;
-  query?: Record<string, string>;
-}): Promise<T> {
-  const res = await vaultApiFetch(opts);
-  if (!res.ok) {
-    const body = (await res.json().catch(() => ({}))) as {
-      error?: unknown;
-      message?: string;
-      step?: string;
-    };
-    const message =
-      typeof body.message === "string"
-        ? body.message
-        : typeof body.error === "string"
-          ? body.error
-          : res.statusText;
-    throw new OutpostHttpError(
-      res.status,
-      message,
-      body.step,
-      parseBillingPayload(body),
-      parseCappedPayload(body),
-    );
-  }
-  return (await res.json()) as T;
-}
-
-/**
- * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
- * box can authenticate AS the caller (the same body the console's
- * `provisionMyOutpost` sends). No duplicate is ever created: a caller already at
- * their per-person cap gets a `409` whose body lists their existing boxes —
- * thrown here as an `OutpostHttpError` carrying `capped` (hq-pro checks the cap
- * BEFORE activation billing, so a capped call is never charged). The refresh
- * token is sent over HTTPS and NEVER printed.
- */
-export async function provisionOutpost(
-  token: string,
-  input: {
-    refreshToken: string;
-    clientIp?: string;
-    diskSizeGb?: number;
-    agentRuntime?: "claude" | "codex";
-  },
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/provision",
-    method: "POST",
-    body: {
-      refreshToken: input.refreshToken,
-      ...(input.clientIp ? { clientIp: input.clientIp } : {}),
-      ...(input.diskSizeGb ? { diskSizeGb: input.diskSizeGb } : {}),
-      ...(input.agentRuntime ? { agentRuntime: input.agentRuntime } : {}),
-    },
-  });
-}
-
-export async function listOutposts(token: string): Promise<OutpostSummary[]> {
-  const data = await outpostRequest<{ outposts: OutpostSummary[] }>({
-    token,
-    path: "/outpost/list",
-  });
-  return data.outposts ?? [];
-}
-
-export async function getOutpostStatus(
-  token: string,
-  outpostId?: string,
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/status",
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-export async function enableCodex(
-  token: string,
-  outpostId?: string,
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/codex/enable",
-    method: "POST",
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-export async function regenerateLoginUrl(
-  token: string,
-  outpostId?: string,
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/regenerate-login-url",
-    method: "POST",
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-/**
- * Hand the box the one-time Claude sign-in code the operator got from the login
- * URL. hq-pro stores it as the row's pending code; the box polls for it, feeds
- * it to `claude`, and flips itself `awaiting-claude-login → ready`. This is the
- * terminal-native equivalent of pasting the code into the web console.
- */
-export async function submitLoginCode(
-  token: string,
-  code: string,
-  outpostId?: string,
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/login-code",
-    method: "POST",
-    body: { code },
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-export async function destroyOutpost(
-  token: string,
-  outpostId?: string,
-): Promise<Record<string, unknown>> {
-  return outpostRequest({
-    token,
-    path: "/outpost/destroy",
-    method: "POST",
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-/** Result of `POST /outpost/exec` — a terminal SSM invocation on the box. */
-export interface OutpostExecResult {
-  ok: true;
-  outpostId: string;
-  instanceId: string;
-  commandId: string;
-  /** SSM invocation status (Success | Failed | Cancelled). */
-  status: string;
-  /** Remote process exit code, or null when SSM reported none. */
-  exitCode: number | null;
-  stdout: string;
-  stderr: string;
-  /** True when SSM clipped stdout/stderr at its inline output limit. */
-  truncated: boolean;
-}
-
-/**
- * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
- * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
- * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
- */
-export async function execOutpost(
-  token: string,
-  command: string,
-  outpostId?: string,
-): Promise<OutpostExecResult> {
-  return outpostRequest({
-    token,
-    path: "/outpost/exec",
-    method: "POST",
-    body: { command },
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-/** Presigned input-upload details from `mode: "stage"`. */
-export interface OutpostExecStage {
-  ok: true;
-  userId: string;
-  outpostId: string;
-  key: string;
-  putUrl: string;
-  getUrl: string;
-  expiresInSeconds: number;
-}
-
-/** Asynchronous SSM command details from `mode: "submit"`. */
-export interface OutpostExecSubmission {
-  ok: true;
-  userId: string;
-  outpostId: string;
-  instanceId: string;
-  commandId: string;
-  outputPrefix: string;
-  /** Shell budget applied server-side (AWS-RunShellScript executionTimeout). */
-  executionTimeoutSeconds?: number;
-}
-
-/** Poll response from `mode: "result"`; streams arrive only when terminal. */
-export interface OutpostExecAsyncResult {
-  ok: true;
-  userId: string;
-  outpostId: string;
-  status: string;
-  done: boolean;
-  exitCode?: number | null;
-  stdout?: string;
-  stderr?: string;
-  truncated?: boolean;
-}
-
-export async function stageExecInput(
-  token: string,
-  outpostId?: string,
-): Promise<OutpostExecStage> {
-  return outpostRequest({
-    token,
-    path: "/outpost/exec",
-    method: "POST",
-    body: { mode: "stage" },
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-export async function submitExec(
-  token: string,
-  command: string,
-  outpostId?: string,
-  timeoutSeconds?: number,
-): Promise<OutpostExecSubmission> {
-  return outpostRequest({
-    token,
-    path: "/outpost/exec",
-    method: "POST",
-    body: {
-      mode: "submit",
-      command,
-      ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
-    },
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-export async function fetchExecResult(
-  token: string,
-  commandId: string,
-  outpostId?: string,
-): Promise<OutpostExecAsyncResult> {
-  return outpostRequest({
-    token,
-    path: "/outpost/exec",
-    method: "POST",
-    body: { mode: "result", commandId },
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-function shellQuote(part: string): string {
-  return `'${part.replace(/'/g, `'\\''`)}'`;
-}
-
-/** Preserve a single command string; safely join argv when Commander split it. */
-export function joinCommandParts(commandParts: string[]): string {
-  if (commandParts.length === 1) return commandParts[0];
-  return commandParts.map(shellQuote).join(" ");
-}
-
-const EXEC_RESULT_INITIAL_POLL_MS = 500;
-const EXEC_RESULT_MAX_POLL_MS = 5_000;
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function waitForExecResult(
-  token: string,
-  commandId: string,
-  outpostId?: string,
-): Promise<OutpostExecAsyncResult> {
-  let delayMs = EXEC_RESULT_INITIAL_POLL_MS;
-  while (true) {
-    try {
-      const result = await fetchExecResult(token, commandId, outpostId);
-      if (result.done) return result;
-    } catch (err) {
-      if (!(err instanceof OutpostHttpError) || err.status !== 429) throw err;
-    }
-    await sleep(delayMs);
-    delayMs = Math.min(delayMs * 2, EXEC_RESULT_MAX_POLL_MS);
-  }
-}
-
-/**
- * Prefix that best-effort `cd`s into the box's HQ checkout before running the
- * caller's command. `exec` runs over two transports with two different default
- * working directories — SSM runs as root with no `$HOME` (cwd `/usr/bin`) and
- * SSH lands in the login user's home — so without this, `hq outposts exec -- pwd`
- * printed an unhelpful, transport-dependent directory. Initialize a real root
- * home for the SSM case before resolving the HQ folder: tools run by the caller
- * (notably `gh`) otherwise treat the HQ checkout as their home and can create
- * root-owned machine state inside it. The trailing `|| true` keeps the command
- * running from the default directory when no HQ checkout is present, so exec
- * never fails merely because the box has no HQ folder.
- */
-export const REMOTE_HQ_DIR_PREFIX =
-  'export HOME="${HOME:-/root}"; cd "$HOME/hq" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true';
-
-/** Wrap `command` so it runs from the box's HQ folder (see REMOTE_HQ_DIR_PREFIX). */
-export function withRemoteHqDir(command: string): string {
-  return `${REMOTE_HQ_DIR_PREFIX}; ${command}`;
-}
-
-/** SSH connection details vended by `POST /outpost/ssh-access`. */
-export interface OutpostSshAccess {
-  outpostId: string;
-  platform: "ec2" | "lightsail";
-  host: string;
-  port: number;
-  username: string;
-  /** PEM private key for the box. SENSITIVE — never printed or logged. */
-  privateKey: string;
-}
-
-/**
- * Fetch SSH connection info + key for the caller's Outpost and open the caller's
- * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
- * `OutpostHttpError` on a non-2xx.
- */
-export async function getOutpostSshAccess(
-  token: string,
-  outpostId?: string,
-): Promise<OutpostSshAccess> {
-  return outpostRequest({
-    token,
-    path: "/outpost/ssh-access",
-    method: "POST",
-    body: {},
-    query: outpostId ? { outpostId } : undefined,
-  });
-}
-
-/**
- * Run `command` on the box over SSH using vended access details. Writes the
- * private key to a locked-down temp file, runs a non-interactive `ssh`, and
- * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
- * are always cleaned up; the key is never printed. `exitCode` is `null` only
- * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
- */
-export function execViaSsh(
-  access: OutpostSshAccess,
-  command: string,
-): { stdout: string; stderr: string; exitCode: number | null; error?: string } {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-outpost-ssh-"));
-  const keyPath = path.join(dir, `id_${randomBytes(6).toString("hex")}`);
-  const knownHosts = path.join(dir, "known_hosts");
-  try {
-    fs.writeFileSync(keyPath, ensureTrailingNewline(access.privateKey), {
-      mode: 0o600,
-    });
-    const result = spawnSync(
-      "ssh",
-      [
-        "-i",
-        keyPath,
-        "-p",
-        String(access.port),
-        "-o",
-        "BatchMode=yes",
-        "-o",
-        "StrictHostKeyChecking=accept-new",
-        "-o",
-        `UserKnownHostsFile=${knownHosts}`,
-        "-o",
-        "ConnectTimeout=15",
-        "-o",
-        "LogLevel=ERROR",
-        `${access.username}@${access.host}`,
-        command,
-      ],
-      { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
-    );
-    if (result.error) {
-      const hint =
-        (result.error as NodeJS.ErrnoException).code === "ENOENT"
-          ? "the `ssh` client is not installed or not on PATH"
-          : result.error.message;
-      return { stdout: "", stderr: "", exitCode: null, error: hint };
-    }
-    return {
-      stdout: result.stdout ?? "",
-      stderr: result.stderr ?? "",
-      exitCode: result.status,
-    };
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-function ensureTrailingNewline(s: string): string {
-  return s.endsWith("\n") ? s : s + "\n";
-}
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-/**
- * Explain a `409` per-person cap. hq-pro checks the cap BEFORE activation
- * billing, so nothing was charged — worth saying, since the caller just
- * confirmed a recurring charge to get here.
- */
-function surfaceOutpostCapped(capped: OutpostCappedPayload): void {
-  const owned = capped.outposts.length;
-  console.error(
-    chalk.yellow(
-      `You're already at your Outpost limit (${owned} of ${capped.limit}). ` +
-        `No new box was provisioned and you have not been charged.`,
-    ),
-  );
-  for (const o of capped.outposts) {
-    const detail = [o.state, o.instanceName, o.region]
-      .filter(Boolean)
-      .join("  ");
-    console.error(`  ${o.outpostId}  ${detail}`);
-  }
-  console.error(chalk.dim("Inspect it: hq outposts status"));
-  console.error(
-    chalk.dim("Or tear it down first: hq outposts destroy --id <id> --yes"),
-  );
-}
-
-function fail(err: unknown): never {
-  if (err instanceof OutpostHttpError) {
-    console.error(chalk.red(err.message));
-  } else {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-  }
-  process.exit(1);
-}
-
-/** Print a top-level object as `key: value`, JSON-ifying nested values. */
-function printKeyValues(obj: Record<string, unknown>): void {
-  for (const [k, v] of Object.entries(obj)) {
-    const rendered = v && typeof v === "object" ? JSON.stringify(v) : String(v);
-    console.log(`${chalk.bold(k)}: ${rendered}`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Hidden local self-deploy command
-// ---------------------------------------------------------------------------
-
-/** The small local-environment surface used by `outposts self-deploy`. */
-export interface SelfDeployDependencies {
-  spawnSync: (
-    command: string,
-    args: string[],
-    options?: Parameters<typeof spawnSync>[2],
-  ) => ReturnType<typeof spawnSync>;
-  readTextFile: (file: string) => string;
-  loadCachedTokens: () =>
-    { refreshToken?: string; idToken?: string } | undefined;
-  getUid: () => number | undefined;
-  isStdinTty: () => boolean;
-  confirm: () => Promise<boolean>;
-  defaultHqRoot: () => string;
-  invokingUser: () => string;
-}
-
-const defaultSelfDeployDependencies: SelfDeployDependencies = {
-  spawnSync: (command, args, options) => spawnSync(command, args, options),
-  readTextFile: (file) => fs.readFileSync(file, "utf8"),
-  loadCachedTokens: () => loadCachedTokens() ?? undefined,
-  getUid: () => process.getuid?.(),
-  isStdinTty: () => process.stdin.isTTY === true,
-  confirm: async () => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    return new Promise((resolve) => {
-      rl.question("", (answer) => {
-        rl.close();
-        resolve(/^y(es)?$/i.test(answer.trim()));
-      });
-    });
-  },
-  defaultHqRoot: () => process.env.HQ_ROOT ?? path.join(os.homedir(), "hq"),
-  invokingUser: () =>
-    process.env.SUDO_USER ?? process.env.USER ?? os.userInfo().username,
-};
-
-function selfDeployError(message: string): Error {
-  return new Error(`Self-deploy preflight failed: ${message}`);
-}
-
-function commandSucceeded(
-  deps: SelfDeployDependencies,
-  command: string,
-  args: string[],
-): boolean {
-  try {
-    const result = deps.spawnSync(command, args, { encoding: "utf8" });
-    return !!result && !result.error && result.status === 0;
-  } catch {
-    return false;
-  }
-}
-
-function commandOutput(
-  deps: SelfDeployDependencies,
-  command: string,
-  args: string[],
-): string | undefined {
-  try {
-    const result = deps.spawnSync(command, args, { encoding: "utf8" });
-    if (!result || result.error || result.status !== 0) return undefined;
-    return String(result.stdout ?? "").trim();
-  } catch {
-    return undefined;
-  }
-}
-
-function parseOsRelease(source: string): Map<string, string> {
-  const values = new Map<string, string>();
-  for (const line of source.split("\n")) {
-    const match = /^([A-Z_]+)=(.*)$/.exec(line);
-    if (!match) continue;
-    const [, key, rawValue] = match;
-    values.set(key, rawValue.replace(/^['"]|['"]$/g, ""));
-  }
-  return values;
-}
-
-function hqIdentityFromSession(session: {
-  refreshToken?: string;
-  idToken?: string;
-}): string {
-  if (!session.idToken) return "your cached HQ session";
-  try {
-    const payload = session.idToken.split(".")[1];
-    if (!payload) return "your cached HQ session";
-    const claims = JSON.parse(
-      Buffer.from(payload, "base64url").toString("utf8"),
-    ) as Record<string, unknown>;
-    for (const key of [
-      "email",
-      "preferred_username",
-      "cognito:username",
-      "username",
-      "sub",
-    ]) {
-      const value = claims[key];
-      if (typeof value === "string" && value) return value;
-    }
-  } catch {
-    // A cache that has a refresh token remains valid for this local setup. The
-    // identity banner is informational, so never expose a token parse failure.
-  }
-  return "your cached HQ session";
-}
-
-function bashSingleQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
-function systemdQuoted(value: string): string {
-  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-function renderSelfDeploySyncScript(hqRoot: string): string {
-  return `#!/usr/bin/env bash
-set -u
-# Persistent all-membership sync for a locally self-hosted HQ outpost. The
-# watch runner event-pushes local changes and polls remote changes every minute.
-HQ_ROOT=${bashSingleQuote(hqRoot)}
-cd "$HQ_ROOT"
-while true; do
-  hq auth refresh || echo "[outpost-sync] auth refresh failed, continuing"
-  npx -y --package=@indigoai-us/hq-cloud@latest hq-sync-runner \\
-    --companies \\
-    --direction both \\
-    --on-conflict keep \\
-    --hq-root "$HQ_ROOT" \\
-    --watch \\
-    --event-push \\
-    --poll-remote-ms 60000
-  echo "[outpost-sync] watch runner exited; restarting in 10 seconds"
-  sleep 10
-done
-`;
-}
-
-function renderSelfDeployService(hqRoot: string, user: string): string {
-  return `[Unit]
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-User=${user}
-WorkingDirectory=${systemdQuoted(hqRoot)}
-ExecStart=/usr/local/bin/outpost-sync.sh
-Restart=always
-RestartSec=10s
-
-[Install]
-WantedBy=multi-user.target
-`;
-}
-
-function runChecked(
-  deps: SelfDeployDependencies,
-  command: string,
-  args: string[],
-  description: string,
-  options?: Parameters<typeof spawnSync>[2],
-): void {
-  let result: ReturnType<typeof spawnSync>;
-  try {
-    result = deps.spawnSync(command, args, options);
-  } catch {
-    throw new Error(`${description} could not be started.`);
-  }
-  if (!result || result.error || result.status !== 0) {
-    // Do not include child process output here: even though this command never
-    // passes credentials to children, it keeps the error path secret-safe.
-    throw new Error(`${description} failed. Resolve the error and try again.`);
-  }
-}
-
-function runPrivileged(
-  deps: SelfDeployDependencies,
-  command: string,
-  args: string[],
-  description: string,
-  options?: Parameters<typeof spawnSync>[2],
-): void {
-  if (deps.getUid() === 0) {
-    runChecked(deps, command, args, description, options);
-    return;
-  }
-  runChecked(deps, "sudo", [command, ...args], description, options);
-}
-
-function selfDeployPreflight(deps: SelfDeployDependencies): {
-  refreshToken?: string;
-  idToken?: string;
-} {
-  let osRelease: string;
-  try {
-    osRelease = deps.readTextFile("/etc/os-release");
-  } catch {
-    throw selfDeployError(
-      "could not read /etc/os-release. This command only supports Amazon Linux 2023 x86_64.",
-    );
-  }
-  const release = parseOsRelease(osRelease);
-  if (
-    release.get("ID") !== "amzn" ||
-    !release.get("VERSION_ID")?.startsWith("2023")
-  ) {
-    throw selfDeployError(
-      "this command only supports Amazon Linux 2023 x86_64. Use an Amazon Linux 2023 EC2 instance.",
-    );
-  }
-
-  const architecture = commandOutput(deps, "uname", ["-m"]);
-  if (architecture !== "x86_64") {
-    throw selfDeployError(
-      "this command only supports x86_64 EC2 instances. Use an Amazon Linux 2023 x86_64 instance.",
-    );
-  }
-
-  if (!commandSucceeded(deps, "systemctl", ["--version"])) {
-    throw selfDeployError(
-      "systemd is required but `systemctl --version` failed. Run this on an Amazon Linux 2023 EC2 host with systemd.",
-    );
-  }
-
-  if (deps.getUid() !== 0 && !commandSucceeded(deps, "sudo", ["-n", "true"])) {
-    throw selfDeployError(
-      "root or passwordless sudo is required. Configure passwordless sudo or run this command as root.",
-    );
-  }
-
-  const session = deps.loadCachedTokens();
-  if (!session?.refreshToken) {
-    throw selfDeployError(
-      "no HQ login session was found. Run `hq login`, then re-run this command.",
-    );
-  }
-  return session;
-}
-
-async function selfDeployOutpost(
-  opts: { yes?: boolean; hqRoot?: string },
-  deps: SelfDeployDependencies,
-): Promise<void> {
-  const session = selfDeployPreflight(deps);
-  const hqRoot = opts.hqRoot ?? deps.defaultHqRoot();
-  const user = deps.invokingUser();
-
-  if (!opts.yes) {
-    console.log(`HQ identity: ${hqIdentityFromSession(session)}`);
-    console.log(
-      chalk.yellow(
-        "This machine will run as a SELF-HOSTED HQ outpost under YOUR identity, continuously syncing ALL your company vaults. " +
-          "It is NOT registered with or managed by hq-pro (no console entry, no remote management, no metering). " +
-          "Anyone with root on this box can act as you. Continue? [y/N]",
-      ),
-    );
-    if (!deps.isStdinTty()) {
-      throw new Error(
-        "Confirmation requires a TTY. Pass --yes to continue non-interactively.",
-      );
-    }
-    if (!(await deps.confirm())) {
-      throw new Error("Self-deploy cancelled.");
-    }
-  }
-
-  runChecked(
-    deps,
-    "hq",
-    ["rescue", "--hq-root", hqRoot, "--yes"],
-    "HQ kernel rescue",
-    { stdio: "inherit" },
-  );
-
-  runPrivileged(
-    deps,
-    "tee",
-    ["/usr/local/bin/outpost-sync.sh"],
-    "Writing /usr/local/bin/outpost-sync.sh",
-    {
-      encoding: "utf8",
-      input: renderSelfDeploySyncScript(hqRoot),
-      stdio: ["pipe", "ignore", "pipe"],
-    },
-  );
-  runPrivileged(
-    deps,
-    "chmod",
-    ["+x", "/usr/local/bin/outpost-sync.sh"],
-    "Making /usr/local/bin/outpost-sync.sh executable",
-  );
-  runPrivileged(
-    deps,
-    "tee",
-    ["/etc/systemd/system/outpost-sync.service"],
-    "Writing /etc/systemd/system/outpost-sync.service",
-    {
-      encoding: "utf8",
-      input: renderSelfDeployService(hqRoot, user),
-      stdio: ["pipe", "ignore", "pipe"],
-    },
-  );
-  runPrivileged(deps, "systemctl", ["daemon-reload"], "Reloading systemd");
-  runPrivileged(
-    deps,
-    "systemctl",
-    ["enable", "--now", "outpost-sync.service"],
-    "Enabling outpost-sync.service",
-  );
-
-  console.log(
-    chalk.green(
-      "This box is now a self-hosted HQ outpost and will sync all your company vaults continuously.",
-    ),
-  );
-  console.log(
-    chalk.dim("Check it with: systemctl status outpost-sync.service"),
-  );
-  console.log(
-    chalk.dim(
-      "It is unregistered and unmanaged by hq-pro (no console entry or remote management).",
-    ),
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Hidden replica-sync command (box-side full-replica timer target)
-// ---------------------------------------------------------------------------
-//
-// A MANAGED outpost (provisioned via `hq outposts provision`) runs this on a
-// systemd timer to make the box a full replica of the operator's HQ:
-//   1. hq auth refresh        — freshen the seeded Cognito session
-//   2. hq sync pull --personal — the personal vault (repos.yaml, policies, …)
-//   3. hq rescue              — re-lay the core kernel (needs companies/)
-//   4. clone repos.yaml       — the operator's OWN repos, gh-authed via vault
-//
-// Unlike `self-deploy` (which is a manual, unmanaged, all-company watcher on a
-// box you own), replica-sync is GENERIC: it works for every HQ user off their
-// own personal vault — no per-operator setup script. It is deliberately
-// best-effort end to end: a repeating timer must never leave the systemd unit
-// in `failed` just because one transient step (a mirror blip, a not-yet-signed
-// box) didn't complete this cycle.
-
-/**
- * The extra local surface `replica-sync` needs on top of the self-deploy set:
- * two filesystem probes for the repos clone. Kept as an extension so the
- * `self-deploy` dependency surface stays minimal.
- */
-export interface ReplicaSyncDependencies extends SelfDeployDependencies {
-  pathExists: (p: string) => boolean;
-  mkdirp: (p: string) => void;
-}
-
-const defaultReplicaSyncDependencies: ReplicaSyncDependencies = {
-  ...defaultSelfDeployDependencies,
-  pathExists: (p) => fs.existsSync(p),
-  mkdirp: (p) => {
-    fs.mkdirSync(p, { recursive: true });
-  },
-};
-
-/** One repo entry resolved from `personal/data/repos.yaml`. */
-export interface ReplicaRepo {
-  url: string;
-  visibility: "public" | "private";
-  name: string;
-}
-
-function repoNameFromUrl(url: string): string {
-  const tail = url.split("/").pop() ?? "";
-  return tail.replace(/\.git$/, "").trim();
-}
-
-/**
- * A repo `name` becomes a path segment under repos/<visibility>/. A synced
- * repos.yaml is operator data, but a malformed or hostile name must never
- * escape that directory, so constrain it to a single, non-traversal component.
- */
-function isSafePathComponent(value: string): boolean {
-  return (
-    value.length > 0 &&
-    !value.includes("/") &&
-    !value.includes("\\") &&
-    value !== "." &&
-    value !== ".."
-  );
-}
-
-/**
- * Parse `personal/data/repos.yaml` into a clone list. Pure + exported for
- * tests. Mirrors setup.sh's `clone_repos`: `visibility` defaults to public,
- * `name` defaults to the URL basename. Malformed entries are skipped, never
- * thrown.
- */
-export function parseReposManifest(yamlText: string): ReplicaRepo[] {
-  let doc: unknown;
-  try {
-    doc = yaml.load(yamlText);
-  } catch {
-    return [];
-  }
-  const rawRepos = (doc as { repos?: unknown } | null)?.repos;
-  if (!Array.isArray(rawRepos)) return [];
-
-  const out: ReplicaRepo[] = [];
-  for (const entry of rawRepos) {
-    if (!entry || typeof entry !== "object") continue;
-    const e = entry as Record<string, unknown>;
-    const url = typeof e.url === "string" ? e.url.trim() : "";
-    if (!url) continue;
-    const visibility = e.visibility === "private" ? "private" : "public";
-    const name =
-      typeof e.name === "string" && e.name.trim()
-        ? e.name.trim()
-        : repoNameFromUrl(url);
-    if (!isSafePathComponent(name)) continue;
-    out.push({ url, visibility, name });
-  }
-  return out;
-}
-
-/**
- * Best-effort spawn: log a one-line outcome and carry on. NEVER throws and
- * NEVER echoes child output — the same secret-safety stance as `runChecked`,
- * since these children (auth refresh, secrets exec) touch credentials.
- */
-function runBestEffort(
-  deps: ReplicaSyncDependencies,
-  command: string,
-  args: string[],
-  description: string,
-  options?: Parameters<typeof spawnSync>[2],
-): boolean {
-  let result: ReturnType<typeof spawnSync>;
-  try {
-    result = deps.spawnSync(command, args, options ?? { stdio: "inherit" });
-  } catch {
-    console.warn(`replica-sync: ${description} could not run — continuing.`);
-    return false;
-  }
-  if (!result || result.error || result.status !== 0) {
-    console.warn(
-      `replica-sync: ${description} did not complete cleanly — continuing.`,
-    );
-    return false;
-  }
-  return true;
-}
-
-/**
- * Authenticate `gh` for private clones by streaming GITHUB_TOKEN through the
- * vault into the child's ENV ONLY, unsetting it in-shell, and piping it to
- * `gh auth login --with-token` over stdin. The token never touches argv or
- * this process's logs. Mirrors personal/scripts/setup.sh's `configure_gh`.
- */
-function authGitHubViaVault(deps: ReplicaSyncDependencies): void {
-  const ghLogin = [
-    'TOKEN="$GITHUB_TOKEN"',
-    "unset GITHUB_TOKEN",
-    'printf "%s" "$TOKEN" | gh auth login --with-token',
-  ].join("\n");
-  const authed = runBestEffort(
-    deps,
-    "hq",
-    [
-      "secrets",
-      "--personal",
-      "exec",
-      "--only",
-      "GITHUB_TOKEN",
-      "--",
-      "bash",
-      "-c",
-      ghLogin,
-    ],
-    "GitHub auth via vault",
-  );
-  if (authed) {
-    // Let plain `git clone https://github.com/...` reuse gh's token so private
-    // repos don't prompt for a username/password.
-    runBestEffort(deps, "gh", ["auth", "setup-git"], "gh auth setup-git");
-  }
-}
-
-/** Clone any repos from `personal/data/repos.yaml` that aren't on disk yet. */
-function replicateRepos(deps: ReplicaSyncDependencies, hqRoot: string): void {
-  const manifestPath = path.join(hqRoot, "personal", "data", "repos.yaml");
-  let manifestText: string;
-  try {
-    manifestText = deps.readTextFile(manifestPath);
-  } catch {
-    console.log(
-      "replica-sync: no personal/data/repos.yaml — skipping repo clone.",
-    );
-    return;
-  }
-
-  const repos = parseReposManifest(manifestText);
-  if (repos.length === 0) {
-    console.log("replica-sync: repos.yaml lists no repos — skipping.");
-    return;
-  }
-
-  const missing = repos.filter(
-    (repo) =>
-      !deps.pathExists(
-        path.join(hqRoot, "repos", repo.visibility, repo.name, ".git"),
-      ),
-  );
-  if (missing.length === 0) {
-    console.log("replica-sync: all repos already present.");
-    return;
-  }
-
-  // Private repos need gh auth first; public-only manifests skip the vault call.
-  if (missing.some((repo) => repo.visibility === "private")) {
-    authGitHubViaVault(deps);
-  }
-
-  for (const repo of missing) {
-    deps.mkdirp(path.join(hqRoot, "repos", repo.visibility));
-    const dest = path.join(hqRoot, "repos", repo.visibility, repo.name);
-    console.log(`replica-sync: cloning ${repo.visibility}/${repo.name}…`);
-    runBestEffort(
-      deps,
-      "git",
-      ["clone", "--recurse-submodules", repo.url, dest],
-      `clone ${repo.visibility}/${repo.name}`,
-    );
-  }
-}
-
-async function replicaSyncOutpost(
-  opts: { hqRoot?: string },
-  deps: ReplicaSyncDependencies,
-): Promise<void> {
-  const hqRoot = opts.hqRoot ?? deps.defaultHqRoot();
-
-  // Gate: only replicate on a box that has an HQ session. A box that was never
-  // signed in has nothing to pull — exit cleanly so the timer stays green.
-  const session = deps.loadCachedTokens();
-  if (!session?.refreshToken) {
-    console.log(
-      "replica-sync: no HQ session on this box yet — nothing to replicate.",
-    );
-    return;
-  }
-
-  // Auth refresh gates the run: if the seeded refresh token is dead, every
-  // authenticated step below (pull, secrets exec) would just cascade 401s.
-  // Stop the cycle cleanly instead — the timer retries next tick.
-  if (!runBestEffort(deps, "hq", ["auth", "refresh"], "HQ auth refresh")) {
-    console.warn(
-      "replica-sync: auth refresh failed — skipping this cycle (token likely expired).",
-    );
-    return;
-  }
-  runBestEffort(
-    deps,
-    "hq",
-    [
-      "sync",
-      "pull",
-      "--personal",
-      "--hq-root",
-      hqRoot,
-      "--on-conflict",
-      "keep",
-    ],
-    "personal vault pull",
-  );
-
-  // rescue lays down the core kernel and expects companies/ to exist.
-  deps.mkdirp(path.join(hqRoot, "companies"));
-  runBestEffort(
-    deps,
-    "hq",
-    ["rescue", "--hq-root", hqRoot, "--yes"],
-    "HQ kernel rescue",
-  );
-
-  replicateRepos(deps, hqRoot);
-  console.log("replica-sync: complete.");
-}
-
-export function registerOutpostsCommand(
-  program: Command,
-  selfDeployOverrides: Partial<ReplicaSyncDependencies> = {},
-): void {
-  const deps: ReplicaSyncDependencies = {
-    ...defaultReplicaSyncDependencies,
-    ...selfDeployOverrides,
-  };
-  const outposts = program
-    .command("outposts")
-    .description("Manage your personal HQ Outposts (EC2 boxes)");
-
-  // On-box session heartbeat (systemd). Hidden — operators never run it.
-  registerHeartbeatCommand(outposts);
-
-  outposts
-    .command("self-deploy", { hidden: true })
-    .description("Configure this EC2 host as a locally self-hosted HQ outpost")
-    .option("--yes", "Skip the self-hosting confirmation")
-    .option("--hq-root <path>", "HQ root to sync", deps.defaultHqRoot())
-    .action(async (opts: { yes?: boolean; hqRoot?: string }) => {
-      try {
-        await selfDeployOutpost(opts, deps);
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("replica-sync", { hidden: true })
-    .description(
-      "Replicate your full HQ onto this box (personal pull + core rescue + repos). Runs on a timer.",
-    )
-    .option(
-      "--hq-root <path>",
-      "HQ root to replicate into",
-      deps.defaultHqRoot(),
-    )
-    .action(async (opts: { hqRoot?: string }) => {
-      // Best-effort background job: never hard-fail the systemd unit on a
-      // transient step. Swallow, log, and exit 0.
-      try {
-        await replicaSyncOutpost(opts, deps);
-      } catch (err) {
-        console.warn(
-          `replica-sync: unexpected error — ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
-    });
-
-  outposts
-    .command("provision")
-    .alias("create")
-    .description("Provision a new Outpost ($80/month — requires --yes)")
-    .option(
-      "--runtime <runtime>",
-      "Agent runtime: claude | codex (default claude)",
-    )
-    .option("--disk <gb>", "Root disk size in GB (EC2 only)")
-    .option(
-      "--client-ip <ip>",
-      "Your public IP for the box's SSH ingress (optional; server derives it otherwise)",
-    )
-    .option("--yes", "Confirm the $80/month charge (required to provision)")
-    .action(async function (
-      this: Command,
-      opts: {
-        runtime?: string;
-        disk?: string;
-        clientIp?: string;
-        yes?: boolean;
-      },
-    ) {
-      try {
-        // Reject an unrecognized runtime rather than resolving it to claude:
-        // `--runtime codx` would otherwise hand back a silently Claude box.
-        if (
-          opts.runtime !== undefined &&
-          opts.runtime !== "claude" &&
-          opts.runtime !== "codex"
-        ) {
-          console.error(
-            chalk.red(
-              `Invalid --runtime '${opts.runtime}': must be 'claude' or 'codex'.`,
-            ),
-          );
-          process.exit(1);
-        }
-        const agentRuntime =
-          opts.runtime === "codex"
-            ? "codex"
-            : opts.runtime === "claude"
-              ? "claude"
-              : undefined;
-        let diskSizeGb: number | undefined;
-        if (opts.disk !== undefined) {
-          diskSizeGb = Number(opts.disk);
-          if (!Number.isFinite(diskSizeGb) || diskSizeGb <= 0) {
-            console.error(
-              chalk.red(
-                `Invalid --disk '${opts.disk}': must be a positive number of GB.`,
-              ),
-            );
-            process.exit(1);
-          }
-        }
-
-        // Paid gate: print the monthly cost and require --yes before any call.
-        confirmChargeOrExit({
-          resource: "Outpost",
-          unitCents: OUTPOST_PRICE_CENTS,
-          yes: opts.yes,
-        });
-
-        // The box authenticates AS the caller using the cached refresh token —
-        // the same body the console sends. Never printed.
-        const refreshToken = loadCachedTokens()?.refreshToken;
-        if (!refreshToken) {
-          console.error(
-            chalk.red(
-              "No cached session found — run `hq login` first, then re-run.",
-            ),
-          );
-          process.exit(1);
-        }
-
-        const token = await ensureCognitoToken();
-        try {
-          await provisionOutpost(token, {
-            refreshToken,
-            ...(opts.clientIp ? { clientIp: opts.clientIp } : {}),
-            ...(diskSizeGb ? { diskSizeGb } : {}),
-            ...(agentRuntime ? { agentRuntime } : {}),
-          });
-          console.log(chalk.green("Provisioning started for your Outpost."));
-          console.log(chalk.dim("Track it: hq outposts status"));
-        } catch (err) {
-          // No card on file → surface the shareable payment link, not an opaque 402.
-          if (
-            err instanceof OutpostHttpError &&
-            err.status === 402 &&
-            err.billing
-          ) {
-            await surfaceBillingBlocked(token, err.billing, err.message);
-            process.exit(1);
-          }
-          // Already at the per-person cap → say so and name the box they own,
-          // not a bare "Conflict".
-          if (
-            err instanceof OutpostHttpError &&
-            err.status === 409 &&
-            err.capped
-          ) {
-            surfaceOutpostCapped(err.capped);
-            process.exit(1);
-          }
-          throw err;
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("list")
-    .description("List every Outpost you own")
-    .option("--json", "Emit raw JSON")
-    .action(async function (this: Command, opts: { json?: boolean }) {
-      try {
-        const token = await ensureCognitoToken();
-        const rows = await listOutposts(token);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
-          return;
-        }
-        if (rows.length === 0) {
-          console.log(chalk.gray("You don't own any Outposts yet."));
-          return;
-        }
-        const idW = Math.max(2, ...rows.map((r) => (r.outpostId ?? "").length));
-        const stateW = Math.max(5, ...rows.map((r) => (r.state ?? "").length));
-        const nameW = Math.max(
-          4,
-          ...rows.map((r) => (r.instanceName ?? "").length),
-        );
-        const regionW = Math.max(
-          6,
-          ...rows.map((r) => (r.region ?? "").length),
-        );
-        const rtW = Math.max(
-          7,
-          ...rows.map((r) => (r.agentRuntime ?? "").length),
-        );
-        console.log(
-          chalk.bold(
-            [
-              "ID".padEnd(idW),
-              "STATE".padEnd(stateW),
-              "INSTANCE".padEnd(nameW),
-              "REGION".padEnd(regionW),
-              "RUNTIME".padEnd(rtW),
-              "PLATFORM",
-            ].join("  "),
-          ),
-        );
-        for (const r of rows) {
-          console.log(
-            [
-              (r.outpostId ?? "").padEnd(idW),
-              (r.state ?? "").padEnd(stateW),
-              (r.instanceName ?? "").padEnd(nameW),
-              (r.region ?? "").padEnd(regionW),
-              (r.agentRuntime ?? "").padEnd(rtW),
-              r.platform ?? "",
-            ].join("  "),
-          );
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("status")
-    .description("Show live detail for one Outpost")
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      opts: { id?: string; json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const status = await getOutpostStatus(token, opts.id);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(status, null, 2) + "\n");
-          return;
-        }
-        printKeyValues(status);
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("exec <command...>")
-    .description(
-      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). " +
-        "Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.",
-    )
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option(
-      "--async",
-      "Submit via the async transport and wait for completion (bypasses the ~20s sync cap; shell budget defaults to 48h)",
-    )
-    .option(
-      "--detach",
-      "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)",
-    )
-    .option(
-      "--timeout-seconds <n>",
-      "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.",
-      (v: string) => {
-        const n = Number(v);
-        if (!Number.isInteger(n)) {
-          throw new Error("--timeout-seconds must be an integer");
-        }
-        return n;
-      },
-    )
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      commandParts: string[],
-      opts: {
-        id?: string;
-        json?: boolean;
-        async?: boolean;
-        detach?: boolean;
-        timeoutSeconds?: number;
-      },
-    ) {
-      try {
-        const command = joinCommandParts(commandParts);
-        if (!command.trim()) {
-          console.error(
-            chalk.red("No command given. Usage: hq outposts exec -- <command>"),
-          );
-          process.exit(1);
-        }
-        if (opts.async && opts.detach) {
-          console.error(
-            chalk.red("Use either --async (submit + wait) or --detach (submit only), not both."),
-          );
-          process.exit(1);
-        }
-        // --timeout-seconds only applies to the async path; bare use implies --async.
-        const useAsync =
-          Boolean(opts.async) ||
-          Boolean(opts.detach) ||
-          opts.timeoutSeconds !== undefined;
-        if (opts.timeoutSeconds !== undefined) {
-          if (
-            !Number.isInteger(opts.timeoutSeconds) ||
-            opts.timeoutSeconds < 1 ||
-            opts.timeoutSeconds > 172_800
-          ) {
-            console.error(
-              chalk.red(
-                "--timeout-seconds must be an integer between 1 and 172800 (48h, the AWS-RunShellScript max)",
-              ),
-            );
-            process.exit(1);
-          }
-        }
-        const token = await ensureCognitoToken();
-
-        // Run from the box's HQ folder by default (works over both SSM and SSH).
-        const remoteCommand = withRemoteHqDir(command);
-
-        if (useAsync) {
-          try {
-            const submitted = await submitExec(
-              token,
-              remoteCommand,
-              opts.id,
-              opts.timeoutSeconds,
-            );
-            if (opts.detach) {
-              const output = {
-                commandId: submitted.commandId,
-                ...(submitted.executionTimeoutSeconds !== undefined
-                  ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
-                  : opts.timeoutSeconds !== undefined
-                    ? { executionTimeoutSeconds: opts.timeoutSeconds }
-                    : {}),
-              };
-              if (opts.json) {
-                process.stdout.write(JSON.stringify(output) + "\n");
-              } else {
-                printKeyValues(output);
-                console.error(
-                  chalk.dim(
-                    "Submitted. Poll with: hq outposts exec-result --command-id " +
-                      submitted.commandId +
-                      (opts.id ? ` --id ${opts.id}` : "") +
-                      " --wait",
-                  ),
-                );
-              }
-              return;
-            }
-
-            // --async (or --timeout-seconds without --detach): wait for terminal.
-            if (!opts.json) {
-              console.error(
-                chalk.dim(
-                  `Submitted ${submitted.commandId}; waiting for completion…`,
-                ),
-              );
-            }
-            const result = await waitForExecResult(
-              token,
-              submitted.commandId,
-              opts.id,
-            );
-            if (opts.json) {
-              process.stdout.write(
-                JSON.stringify(
-                  {
-                    commandId: submitted.commandId,
-                    done: result.done,
-                    status: result.status,
-                    exitCode: result.exitCode ?? null,
-                    stdout: result.stdout ?? "",
-                    stderr: result.stderr ?? "",
-                    truncated: result.truncated ?? false,
-                  },
-                  null,
-                  2,
-                ) + "\n",
-              );
-            } else {
-              if (result.stdout) process.stdout.write(result.stdout);
-              if (result.stderr) process.stderr.write(result.stderr);
-              if (result.truncated) {
-                console.error(
-                  chalk.yellow(
-                    "(output truncated — redirect to a file on the box for full output)",
-                  ),
-                );
-              }
-              if (result.status !== "Success" && result.exitCode === null) {
-                console.error(
-                  chalk.yellow(`(command ended with SSM status: ${result.status})`),
-                );
-              }
-            }
-            process.exitCode =
-              typeof result.exitCode === "number" ? result.exitCode : 0;
-            return;
-          } catch (err) {
-            // Async requires EC2/SSM. Lightsail has no async channel — refuse
-            // rather than silently falling back to a live SSH hold, which is
-            // the exact timeout failure mode --async is meant to escape.
-            if (
-              err instanceof OutpostHttpError &&
-              err.step === "platform-unsupported"
-            ) {
-              console.error(
-                chalk.red(
-                  "Async exec requires an EC2 Outpost (SSM). This box is Lightsail — " +
-                    "re-provision on EC2, or run a short sync command / SSH session instead.",
-                ),
-              );
-              process.exit(1);
-            }
-            throw err;
-          }
-        }
-
-        try {
-          const result = await execOutpost(token, remoteCommand, opts.id);
-          if (opts.json) {
-            process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          } else {
-            // Stream the remote streams to ours so the command feels local.
-            if (result.stdout) process.stdout.write(result.stdout);
-            if (result.stderr) process.stderr.write(result.stderr);
-            if (result.truncated) {
-              console.error(
-                chalk.yellow(
-                  "(output truncated by SSM's inline limit — redirect to a file on the box for full output)",
-                ),
-              );
-            }
-            if (result.status !== "Success" && result.exitCode === null) {
-              console.error(
-                chalk.yellow(
-                  `(command ended with SSM status: ${result.status})`,
-                ),
-              );
-            }
-          }
-          // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
-          process.exitCode =
-            typeof result.exitCode === "number" ? result.exitCode : 0;
-        } catch (err) {
-          // Lightsail boxes have no SSM agent — transparently fall back to SSH.
-          if (
-            err instanceof OutpostHttpError &&
-            err.step === "platform-unsupported"
-          ) {
-            const access = await getOutpostSshAccess(token, opts.id);
-            const ssh = execViaSsh(access, remoteCommand);
-            if (ssh.error) {
-              console.error(
-                chalk.red(`Could not run the command over SSH: ${ssh.error}`),
-              );
-              process.exit(1);
-            }
-            if (opts.json) {
-              process.stdout.write(
-                JSON.stringify(
-                  {
-                    via: "ssh",
-                    platform: access.platform,
-                    host: access.host,
-                    exitCode: ssh.exitCode,
-                    stdout: ssh.stdout,
-                    stderr: ssh.stderr,
-                  },
-                  null,
-                  2,
-                ) + "\n",
-              );
-            } else {
-              if (ssh.stdout) process.stdout.write(ssh.stdout);
-              if (ssh.stderr) process.stderr.write(ssh.stderr);
-            }
-            process.exitCode =
-              typeof ssh.exitCode === "number" ? ssh.exitCode : 1;
-            return;
-          }
-          throw err;
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("exec-stage")
-    .description("Stage a file for an asynchronous Outpost command")
-    .requiredOption("--file <path>", "File to upload")
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      opts: { file: string; id?: string; json?: boolean },
-    ) {
-      try {
-        const bytes = fs.readFileSync(opts.file);
-        const token = await ensureCognitoToken();
-        const staged = await stageExecInput(token, opts.id);
-        const upload = await fetch(staged.putUrl, {
-          method: "PUT",
-          headers: { "Content-Length": String(bytes.byteLength) },
-          body: bytes,
-        });
-        if (!upload.ok) {
-          throw new Error(
-            `Could not upload exec input: HTTP ${upload.status} ${upload.statusText}`,
-          );
-        }
-        const output = { key: staged.key, getUrl: staged.getUrl };
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(output) + "\n");
-        } else {
-          printKeyValues(output);
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("exec-submit <command...>")
-    .description(
-      "Submit an asynchronous shell command to an Outpost (returns immediately with commandId; shell budget defaults to 48h)",
-    )
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option(
-      "--timeout-seconds <n>",
-      "Shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)",
-      (v: string) => {
-        const n = Number(v);
-        if (!Number.isInteger(n)) {
-          throw new Error("--timeout-seconds must be an integer");
-        }
-        return n;
-      },
-    )
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      commandParts: string[],
-      opts: { id?: string; json?: boolean; timeoutSeconds?: number },
-    ) {
-      try {
-        const command = joinCommandParts(commandParts);
-        if (!command.trim()) {
-          console.error(
-            chalk.red(
-              "No command given. Usage: hq outposts exec-submit -- <command>",
-            ),
-          );
-          process.exit(1);
-        }
-        if (opts.timeoutSeconds !== undefined) {
-          if (
-            !Number.isInteger(opts.timeoutSeconds) ||
-            opts.timeoutSeconds < 1 ||
-            opts.timeoutSeconds > 172_800
-          ) {
-            console.error(
-              chalk.red(
-                "--timeout-seconds must be an integer between 1 and 172800 (48h)",
-              ),
-            );
-            process.exit(1);
-          }
-        }
-        const token = await ensureCognitoToken();
-        // exec-submit is the raw fire-and-forget path — do NOT wrap with
-        // withRemoteHqDir here (callers that want the HQ cwd use `exec --async`
-        // or prefix their own cd). Matches the existing contract.
-        const submitted = await submitExec(
-          token,
-          command,
-          opts.id,
-          opts.timeoutSeconds,
-        );
-        const output = {
-          commandId: submitted.commandId,
-          ...(submitted.executionTimeoutSeconds !== undefined
-            ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
-            : opts.timeoutSeconds !== undefined
-              ? { executionTimeoutSeconds: opts.timeoutSeconds }
-              : {}),
-        };
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(output) + "\n");
-        } else {
-          printKeyValues(output);
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("exec-result")
-    .description("Fetch the result of an asynchronous Outpost command")
-    .requiredOption(
-      "--command-id <commandId>",
-      "Command id returned by exec-submit",
-    )
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--wait", "Poll until the command reaches a terminal state")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      opts: { commandId: string; id?: string; wait?: boolean; json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const result = opts.wait
-          ? await waitForExecResult(token, opts.commandId, opts.id)
-          : await fetchExecResult(token, opts.commandId, opts.id);
-        const output = {
-          done: result.done,
-          status: result.status,
-          exitCode: result.exitCode ?? null,
-          stdout: result.stdout ?? "",
-          stderr: result.stderr ?? "",
-        };
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(output) + "\n");
-        } else {
-          printKeyValues(output);
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("codex-enable")
-    .description("Enable (or retry) Codex on an Outpost")
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      opts: { id?: string; json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const result = await enableCodex(token, opts.id);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          return;
-        }
-        console.log(chalk.green("Codex enablement requested for the Outpost."));
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("login")
-    .description("Request a fresh login URL for an Outpost")
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      opts: { id?: string; json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const result = await regenerateLoginUrl(token, opts.id);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          return;
-        }
-        console.log(
-          chalk.green(
-            "Login-URL regeneration requested. The box mints a fresh URL shortly.",
-          ),
-        );
-        console.log(
-          chalk.dim(
-            "Next: `hq outposts status" +
-              (opts.id ? ` --id ${opts.id}` : "") +
-              "` to read the login URL, open it and sign in, then paste the code back with " +
-              "`hq outposts login-code <code>" +
-              (opts.id ? ` --id ${opts.id}` : "") +
-              "`.",
-          ),
-        );
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("login-code <code>")
-    .description(
-      "Submit the Claude sign-in code for an Outpost that is awaiting login",
-    )
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      code: string,
-      opts: { id?: string; json?: boolean },
-    ) {
-      try {
-        const trimmed = code.trim();
-        if (!trimmed) {
-          console.error(
-            chalk.red(
-              "Provide the sign-in code: hq outposts login-code <code>",
-            ),
-          );
-          process.exit(1);
-        }
-        const token = await ensureCognitoToken();
-        const result = await submitLoginCode(token, trimmed, opts.id);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          return;
-        }
-        console.log(
-          chalk.green(
-            "Code submitted — the box will finish signing in shortly.",
-          ),
-        );
-        console.log(
-          chalk.dim(
-            "Track it: `hq outposts status" +
-              (opts.id ? ` --id ${opts.id}` : "") +
-              "` (it flips to `ready` once Claude auth completes).",
-          ),
-        );
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  outposts
-    .command("destroy")
-    .description("Tear down (permanently destroy) an Outpost")
-    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
-    .option("--yes", "Confirm the irreversible teardown (required)")
-    .action(async function (
-      this: Command,
-      opts: { id?: string; yes?: boolean },
-    ) {
-      const target = opts.id ?? "your primary Outpost";
-      if (!opts.yes) {
-        console.error(
-          chalk.yellow(
-            `This will permanently destroy ${target} and delete its cloud resources. ` +
-              `This cannot be undone.\n` +
-              `Re-run with --yes to confirm: hq outposts destroy${opts.id ? ` --id ${opts.id}` : ""} --yes`,
-          ),
-        );
-        process.exit(1);
-      }
-      try {
-        const token = await ensureCognitoToken();
-        await destroyOutpost(token, opts.id);
-        console.log(chalk.green(`Destroyed ${target}.`));
-      } catch (err) {
-        // A 409 teardown-incomplete is not a failure — the gateway's 30s cap
-        // fired while the Lambda keeps working. The row is preserved and the
-        // operation is idempotent, so tell the caller to retry.
-        if (
-          err instanceof OutpostHttpError &&
-          (err.status === 409 || err.step === "teardown-incomplete")
-        ) {
-          console.log(
-            chalk.yellow(
-              `Teardown still in progress for ${target} — this is expected for large boxes. ` +
-                `Re-run the same destroy command to finish (it's idempotent).`,
-            ),
-          );
-          return;
-        }
-        fail(err);
-      }
-    });
-}