@indigoai-us/hq-cli 5.70.0 → 5.71.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.71.0]
+
+### Added
+
+- **Async Outpost exec.** `hq outposts` gained three verbs for running commands
+  that exceed the synchronous `exec` limits (long-running turns, large payloads
+  and outputs), backed by the `mode` flag on `POST /outpost/exec`:
+  - `hq outposts exec-stage --file <path>` — upload an input payload to a
+    short-lived presigned URL and print `{ key, getUrl }`.
+  - `hq outposts exec-submit -- <command>` — submit an asynchronous command and
+    print `{ commandId }` immediately (no blocking).
+  - `hq outposts exec-result --command-id <id> [--wait]` — fetch the result;
+    non-terminal returns `{ done: false }`, `--wait` polls to completion.
+
+### Fixed
+
+- `outposts exec` / `exec-submit` now shell-quote multi-argument commands before
+  joining, so `-- bash -c "$script" a b` survives instead of collapsing on a
+  naive space-join. A single command string still passes through verbatim.
+
 ## [5.70.0]
 
 ### Added

package/dist/commands/outposts.d.ts

@@ -95,6 +95,42 @@ export interface OutpostExecResult {
  * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
  */
 export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
+/** 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;
+}
+/** 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 declare function stageExecInput(token: string, outpostId?: string): Promise<OutpostExecStage>;
+export declare function submitExec(token: string, command: string, outpostId?: string): Promise<OutpostExecSubmission>;
+export declare function fetchExecResult(token: string, commandId: string, outpostId?: string): Promise<OutpostExecAsyncResult>;
+/** Preserve a single command string; safely join argv when Commander split it. */
+export declare function joinCommandParts(commandParts: string[]): string;
 /**
  * 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

package/dist/commands/outposts.js

@@ -21,7 +21,7 @@
  * and status routes that exist. Renaming an Outpost is not a backend capability.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ff8d1d83-feab-5f6f-bf48-e4fde1a8d449")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="839f8f76-584d-5ea8-b86e-a92a55c32a16")}catch(e){}}();
 import chalk from "chalk";
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
@@ -139,6 +139,63 @@ export async function execOutpost(token, command, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+export async function stageExecInput(token, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/exec",
+        method: "POST",
+        body: { mode: "stage" },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
+export async function submitExec(token, command, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/exec",
+        method: "POST",
+        body: { mode: "submit", command },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
+export async function fetchExecResult(token, commandId, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/exec",
+        method: "POST",
+        body: { mode: "result", commandId },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
+function shellQuote(part) {
+    return `'${part.replace(/'/g, `'\\''`)}'`;
+}
+/** Preserve a single command string; safely join argv when Commander split it. */
+export function joinCommandParts(commandParts) {
+    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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForExecResult(token, commandId, outpostId) {
+    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
@@ -602,8 +659,8 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
         .option("--json", "Emit raw JSON")
         .action(async function (commandParts, opts) {
         try {
-            const command = commandParts.join(" ").trim();
-            if (!command) {
+            const command = joinCommandParts(commandParts);
+            if (!command.trim()) {
                 console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
                 process.exit(1);
             }
@@ -669,6 +726,94 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
             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 (opts) {
+        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")
+        .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (commandParts, opts) {
+        try {
+            const command = joinCommandParts(commandParts);
+            if (!command.trim()) {
+                console.error(chalk.red("No command given. Usage: hq outposts exec-submit -- <command>"));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            const submitted = await submitExec(token, command, opts.id);
+            const output = { commandId: submitted.commandId };
+            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 (opts) {
+        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")
@@ -741,4 +886,4 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=ff8d1d83-feab-5f6f-bf48-e4fde1a8d449
+//# debugId=839f8f76-584d-5ea8-b86e-a92a55c32a16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.70.0",
+  "version": "5.71.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/outposts.test.ts

@@ -50,9 +50,18 @@ vi.mock("node:child_process", async (importOriginal) => {
   return { ...original, spawnSync: vi.fn() };
 });
 
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { registerOutpostsCommand, withRemoteHqDir } from "./outposts.js";
+import {
+  fetchExecResult,
+  joinCommandParts,
+  registerOutpostsCommand,
+  stageExecInput,
+  submitExec,
+  withRemoteHqDir,
+} from "./outposts.js";
 
 const mockSpawnSync = vi.mocked(spawnSync);
 
@@ -299,7 +308,7 @@ describe("hq outposts exec", () => {
     expect(init?.method).toBe("POST");
     // The command is wrapped so it runs from the box's HQ folder.
     expect(JSON.parse(init?.body as string)).toEqual({
-      command: withRemoteHqDir("echo hello world"),
+      command: withRemoteHqDir("'echo' 'hello' 'world'"),
     });
     const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
     expect(printed).toContain("hello world\n");
@@ -431,7 +440,7 @@ describe("hq outposts exec — Lightsail SSH fallback", () => {
     const args = mockSpawnSync.mock.calls[0][1] as string[];
     expect(mockSpawnSync.mock.calls[0][0]).toBe("ssh");
     expect(args).toContain("ec2-user@52.2.2.2");
-    expect(args[args.length - 1]).toBe(withRemoteHqDir("uname -a"));
+    expect(args[args.length - 1]).toBe(withRemoteHqDir("'uname' '-a'"));
     expect(args).toContain("BatchMode=yes");
     const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
     expect(printed).toContain("lightsail-out\n");
@@ -489,3 +498,242 @@ describe("hq outposts exec — Lightsail SSH fallback", () => {
     expect(mockSpawnSync).not.toHaveBeenCalled();
   });
 });
+
+describe("hq outposts asynchronous exec", () => {
+  it("sends the stage, submit, and result mode request bodies", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u1",
+          outpostId: "2",
+          key: "input-key",
+          putUrl: "https://upload.invalid/put",
+          getUrl: "https://download.invalid/get",
+          expiresInSeconds: 300,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u1",
+          outpostId: "2",
+          instanceId: "i-2",
+          commandId: "cmd-1",
+          outputPrefix: "output-prefix",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u1",
+          outpostId: "2",
+          status: "InProgress",
+          done: false,
+        }),
+      );
+
+    await stageExecInput("test-token", "2");
+    await submitExec("test-token", "cd /tmp && run-worker", "2");
+    await fetchExecResult("test-token", "cmd-1", "2");
+
+    expect(fetchSpy.mock.calls.map(([url]) => String(url))).toEqual([
+      expect.stringContaining("/outpost/exec?outpostId=2"),
+      expect.stringContaining("/outpost/exec?outpostId=2"),
+      expect.stringContaining("/outpost/exec?outpostId=2"),
+    ]);
+    expect(fetchSpy.mock.calls.map(([, init]) => JSON.parse(init?.body as string))).toEqual([
+      { mode: "stage" },
+      { mode: "submit", command: "cd /tmp && run-worker" },
+      { mode: "result", commandId: "cmd-1" },
+    ]);
+  });
+
+  it("exec-stage PUTs the exact file bytes and prints only key + getUrl JSON", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    const file = path.join(process.cwd(), "package.json");
+    const expectedBytes = fs.readFileSync(file);
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u1",
+          outpostId: "2",
+          key: "input-key",
+          putUrl: "https://upload.invalid/put",
+          getUrl: "https://download.invalid/get",
+          expiresInSeconds: 300,
+        }),
+      )
+      .mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+    await run(["outposts", "exec-stage", "--id", "2", "--file", file, "--json"]);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    const [uploadUrl, uploadInit] = fetchSpy.mock.calls[1];
+    expect(String(uploadUrl)).toBe("https://upload.invalid/put");
+    expect(uploadInit?.method).toBe("PUT");
+    expect(uploadInit?.headers).toEqual({
+      "Content-Length": String(expectedBytes.byteLength),
+    });
+    expect(Buffer.from(uploadInit?.body as Uint8Array)).toEqual(expectedBytes);
+    const printed = stdoutSpy.mock.calls.map((call) => String(call[0])).join("");
+    expect(JSON.parse(printed)).toEqual({
+      key: "input-key",
+      getUrl: "https://download.invalid/get",
+    });
+  });
+
+  it("exec-stage exits non-zero when the presigned upload fails", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u1",
+          outpostId: "primary",
+          key: "input-key",
+          putUrl: "https://upload.invalid/put",
+          getUrl: "https://download.invalid/get",
+          expiresInSeconds: 300,
+        }),
+      )
+      .mockResolvedValueOnce(new Response(null, { status: 503 }));
+
+    await expect(
+      run([
+        "outposts",
+        "exec-stage",
+        "--file",
+        path.join(process.cwd(), "package.json"),
+        "--json",
+      ]),
+    ).rejects.toThrow("process.exit(1)");
+  });
+
+  it("exec-submit shell-quotes multiple argv parts without adding the HQ-directory wrapper", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    const script = 'printf "%s\\n" "$0" "$1" "$2"';
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        ok: true,
+        userId: "u1",
+        outpostId: "primary",
+        instanceId: "i-1",
+        commandId: "cmd-submit",
+        outputPrefix: "output-prefix",
+      }),
+    );
+
+    await run([
+      "outposts",
+      "exec-submit",
+      "--json",
+      "--",
+      "bash",
+      "-c",
+      script,
+      "marker",
+      "a b",
+      "quote's",
+    ]);
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body).toEqual({
+      mode: "submit",
+      command: joinCommandParts([
+        "bash",
+        "-c",
+        script,
+        "marker",
+        "a b",
+        "quote's",
+      ]),
+    });
+    expect(body.command).not.toContain("cd ~ec2-user/hq");
+    expect(JSON.parse(String(stdoutSpy.mock.calls[0][0]))).toEqual({
+      commandId: "cmd-submit",
+    });
+  });
+
+  it("preserves one command part verbatim and round-trips quoted bash argv", () => {
+    const single = "  printf 'already formed'  ";
+    expect(joinCommandParts([single])).toBe(single);
+
+    const script = 'printf "%s\\n" "$0" "$1" "$2"';
+    const command = joinCommandParts([
+      "bash",
+      "-c",
+      script,
+      "marker",
+      "a b",
+      "quote's",
+    ]);
+    expect(execFileSync("bash", ["-c", command], { encoding: "utf8" })).toBe(
+      "marker\na b\nquote's\n",
+    );
+  });
+
+  it("exec-result --wait retries a 429, polls until done, and prints the result contract", async () => {
+    vi.useFakeTimers();
+    try {
+      const stdoutSpy = vi
+        .spyOn(process.stdout, "write")
+        .mockImplementation(() => true);
+      fetchSpy
+        .mockResolvedValueOnce(
+          jsonResponse(429, { error: true, step: "rate", message: "slow down" }),
+        )
+        .mockResolvedValueOnce(
+          jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            status: "InProgress",
+            done: false,
+          }),
+        )
+        .mockResolvedValueOnce(
+          jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            status: "Success",
+            done: true,
+            exitCode: 0,
+            stdout: "finished\n",
+            stderr: "",
+            truncated: false,
+          }),
+        );
+
+      const pending = run([
+        "outposts",
+        "exec-result",
+        "--id",
+        "2",
+        "--command-id",
+        "cmd-1",
+        "--wait",
+        "--json",
+      ]);
+      await vi.advanceTimersByTimeAsync(500);
+      await vi.advanceTimersByTimeAsync(1_000);
+      await pending;
+
+      expect(fetchSpy).toHaveBeenCalledTimes(3);
+      expect(JSON.parse(String(stdoutSpy.mock.calls[0][0]))).toEqual({
+        done: true,
+        status: "Success",
+        exitCode: 0,
+        stdout: "finished\n",
+        stderr: "",
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/commands/outposts.ts

@@ -228,6 +228,116 @@ export async function execOutpost(
   });
 }
 
+/** 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;
+}
+
+/** 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,
+): Promise<OutpostExecSubmission> {
+  return outpostRequest({
+    token,
+    path: "/outpost/exec",
+    method: "POST",
+    body: { mode: "submit", command },
+    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
@@ -876,8 +986,8 @@ export function registerOutpostsCommand(
       opts: { id?: string; json?: boolean },
     ) {
       try {
-        const command = commandParts.join(" ").trim();
-        if (!command) {
+        const command = joinCommandParts(commandParts);
+        if (!command.trim()) {
           console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
           process.exit(1);
         }
@@ -948,6 +1058,105 @@ export function registerOutpostsCommand(
       }
     });
 
+  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")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      commandParts: string[],
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const command = joinCommandParts(commandParts);
+        if (!command.trim()) {
+          console.error(
+            chalk.red("No command given. Usage: hq outposts exec-submit -- <command>"),
+          );
+          process.exit(1);
+        }
+        const token = await ensureCognitoToken();
+        const submitted = await submitExec(token, command, opts.id);
+        const output = { commandId: submitted.commandId };
+        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")