@love-moon/conductor-cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @love-moon/conductor-cli
 
+## 0.13.0
+
+### Minor Changes
+
+- 8edbed5: `conductor remote exec` is safer to drive from an agent, and gains a `wait` verb.
+
+  - New `conductor remote wait -t <daemon> <runId>` re-attaches to a command that
+    `exec` left running past its `--timeout`, polling and reporting it exactly as
+    `exec` would have. `exec` now prints that command in its "still running" hint
+    instead of a raw API path.
+  - `exec` retries the initial request on `429 too many concurrent remote exec
+requests` with backoff (up to ~15 s), so a burst of parallel short commands no
+    longer fails outright. Other errors are still not retried: a 5xx may already
+    have started the command.
+  - `exec` and `wait` handle SIGINT/SIGTERM: the run id is printed before exiting,
+    and with `--kill-on-timeout` the remote command is cancelled as well. Before,
+    a tool timeout that killed the CLI silently orphaned the remote process.
+
+### Patch Changes
+
+- Updated dependencies [80ab13e]
+  - @love-moon/conductor-sdk@0.13.0
+  - @love-moon/ai-sdk@0.13.0
+
 ## 0.12.0
 
 ### Minor Changes

package/bin/conductor-remote.js

@@ -19,12 +19,14 @@ import { fileURLToPath } from "node:url";
 import { EXIT } from "../src/remote/client.js";
 import { runRemoteExec, showHelp as showExecHelp } from "../src/remote/exec.js";
 import { runRemoteCp, showHelp as showCpHelp } from "../src/remote/cp.js";
+import { runRemoteWait, showHelp as showWaitHelp } from "../src/remote/wait.js";
 
 export { EXIT };
 
 const VERBS = new Map([
   ["exec", runRemoteExec],
   ["cp", runRemoteCp],
+  ["wait", runRemoteWait],
 ]);
 
 const isMainModule = (() => {
@@ -42,6 +44,7 @@ Usage:
 Verbs:
   exec   Run a command on another daemon's host
   cp     Copy a file to or from another daemon's host
+  wait   Wait for a command that \`exec\` left running (by run id)
 
 Options:
   -h, --help   Show this help
@@ -50,10 +53,12 @@ Examples:
   conductor remote exec --target ubuntu --workspace /srv/app -- git log --oneline -5
   conductor remote cp ./build.tar.gz ubuntu:/srv/app/build.tar.gz
   conductor remote cp ubuntu:/var/log/conductor.log ./conductor.log
+  conductor remote wait --target ubuntu <runId>
 
 For verb-specific help:
   conductor remote exec --help
   conductor remote cp --help
+  conductor remote wait --help
 `);
 }
 
@@ -84,7 +89,7 @@ export async function runRemote(argv, deps = {}) {
   return handler(argv.slice(1), deps);
 }
 
-export { showExecHelp, showCpHelp };
+export { showExecHelp, showCpHelp, showWaitHelp };
 
 if (isMainModule) {
   // `process.exitCode` rather than `process.exit()`: writes to a pipe are async,

package/bin/conductor.js

@@ -137,7 +137,7 @@ Subcommands:
   project   Manage Conductor projects (list/show/create/...)
   issue     Manage issues (list/show/create/update/start/done)
   task      Manage tasks (create/list/show/send/messages/schedule)
-  remote    Run commands and copy files on another daemon's host (exec/cp)
+  remote    Run commands and copy files on another daemon's host (exec/cp/wait)
 
 Options:
   -h, --help     Show this help message

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.12.0",
-  "gitCommitId": "c1047e8",
+  "version": "0.13.0",
+  "gitCommitId": "e1e507f",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -24,8 +24,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-sdk": "0.12.0",
-    "@love-moon/conductor-sdk": "0.12.0",
+    "@love-moon/ai-sdk": "0.13.0",
+    "@love-moon/conductor-sdk": "0.13.0",
     "@github/copilot-sdk": "^0.3.0",
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0",
@@ -38,7 +38,7 @@
   },
   "optionalDependencies": {
     "@roamhq/wrtc": "^0.10.0",
-    "@love-moon/chat-web": "0.12.0"
+    "@love-moon/chat-web": "0.13.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/daemon.js

@@ -26,6 +26,7 @@ import {
 } from "./conductor-paths.js";
 import {
   deleteFireSessionRecord,
+  listFireSessionTaskIds,
   pruneFireSessionRecords,
   readFireSessionRecord,
   resolveFireSessionRegistryDir,
@@ -2306,6 +2307,30 @@ export function startDaemon(config = {}, deps = {}) {
     return FIRE_TMUX_MODE_ENABLED && !FIRE_TMUX_MODE_ACTIVE && isTmuxAvailable();
   }
 
+  // The third door into the same mass kill: `tmux` genuinely absent from PATH.
+  // A daemon restarted by launchd/systemd/cron — or during a `brew upgrade
+  // tmux` — logs the direct-spawn fallback and then cannot enumerate sessions
+  // by any means, so the guard above (which needs tmux to answer) declines and
+  // every Fire the predecessor deliberately left running gets killed.
+  //
+  // The hand-off records on disk are the remaining evidence: they name exactly
+  // the tasks whose liveness this process is unable to answer for. Scoped to
+  // those rather than skipping the sweep wholesale, because a host that simply
+  // never installs tmux spawns its Fires directly and those DO die with their
+  // daemon — blanket-skipping would strand them at `running` with nobody left
+  // to report their death, which is worse than killing them. Nothing prunes
+  // the registry in this state (the prune needs a conclusive listing), so a
+  // later start with a healthy tmux still adopts or reaps them properly.
+  function taskIdsWithUnverifiableTmuxFire() {
+    if (!FIRE_TMUX_MODE_ENABLED || FIRE_TMUX_MODE_ACTIVE) return new Set();
+    try {
+      return listFireSessionTaskIds(FIRE_SESSION_REGISTRY_DIR);
+    } catch (error) {
+      logError(`Failed to read tmux hand-off records: ${error?.message || error}`);
+      return new Set();
+    }
+  }
+
   // Sessions already identified as orphaned shells and killed. `tmux
   // kill-session` is asynchronous, so a sweep running moments later still
   // sees the name in `list-sessions` — and by then the hand-off record is
@@ -4856,12 +4881,26 @@ export function startDaemon(config = {}, deps = {}) {
         );
         return;
       }
+      const unverifiableTmuxTaskIds = taskIdsWithUnverifiableTmuxFire();
+      const skippedUnverifiable = [];
       const deadTasks = staleTasks.filter((task) => {
+        const taskId = String(task?.id || "");
         // A spawn already in flight has no record yet either; killing it
         // would shoot down a Fire this daemon is in the middle of starting.
-        if (pendingTaskStarts.has(String(task?.id || ""))) return false;
+        if (pendingTaskStarts.has(taskId)) return false;
+        if (unverifiableTmuxTaskIds.has(taskId)) {
+          skippedUnverifiable.push(taskId);
+          return false;
+        }
         return !adoptLiveTmuxFireForTask(task, tmuxSessions?.sessions || []);
       });
+      if (skippedUnverifiable.length) {
+        logError(
+          `tmux is not on PATH, so the Fires a previous daemon left for ${skippedUnverifiable.length} ` +
+            `task(s) cannot be checked; skipping stale recovery for them rather than killing what this ` +
+            `daemon cannot see. Restart with tmux available to adopt or reap them.`,
+        );
+      }
 
       if (deadTasks.length === 0) {
         return;
@@ -4960,12 +4999,23 @@ export function startDaemon(config = {}, deps = {}) {
         );
         return;
       }
+      const unverifiableTmuxTaskIds = taskIdsWithUnverifiableTmuxFire();
       for (const task of assigned) {
         const taskId = String(task?.id || "");
         if (!taskId) continue;
         if (localTaskIds.has(taskId) || pendingTaskStarts.has(taskId)) {
           continue;
         }
+        // No tmux binary to ask, but a predecessor filed a hand-off record for
+        // this task: we cannot see its Fire, which is not the same as it being
+        // dead. See taskIdsWithUnverifiableTmuxFire.
+        if (unverifiableTmuxTaskIds.has(taskId)) {
+          logError(
+            `Task ${taskId} has a tmux hand-off record but tmux is not on PATH; skipping reconcile ` +
+              `rather than killing a Fire this daemon cannot see`,
+          );
+          continue;
+        }
         // Adopts on the spot rather than merely skipping: a survivor that
         // dodges the kill but gains no watcher would sit at `running`
         // forever, because nothing else reports a tmux Fire's death.

package/src/fire-session-registry.js

@@ -134,3 +134,22 @@ export function pruneFireSessionRecords(dir, liveSessionNames, { fsImpl = fs } =
   }
   return pruned;
 }
+
+// Task ids a previous daemon left a tmux Fire running for. This is the only
+// evidence available to a successor that has no `tmux` binary to enumerate
+// sessions with, so it is what scopes that daemon's refusal to kill.
+export function listFireSessionTaskIds(dir, { fsImpl = fs } = {}) {
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir);
+  } catch {
+    return new Set();
+  }
+  const taskIds = new Set();
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const record = readFireSessionRecord(dir, entry.slice(0, -".json".length), { fsImpl });
+    if (record?.taskId) taskIds.add(record.taskId);
+  }
+  return taskIds;
+}

package/src/remote/client.js

@@ -97,8 +97,14 @@ export function isRetryable(error) {
   return status >= 500 || status === 429;
 }
 
-/** Retry `fn` on transient failures, handing it the attempt number. */
-export async function withRetry(fn, { attempts = 4, baseDelayMs = 500, sleep = delay } = {}) {
+/**
+ * Retry `fn` on transient failures, handing it the attempt number. `retryable`
+ * narrows what counts as transient: a caller whose request is not idempotent
+ * (starting a command) must not retry a 5xx that may already have taken effect.
+ */
+export async function withRetry(fn, {
+  attempts = 4, baseDelayMs = 500, sleep = delay, retryable = isRetryable,
+} = {}) {
   let lastError;
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
@@ -106,7 +112,7 @@ export async function withRetry(fn, { attempts = 4, baseDelayMs = 500, sleep = d
     } catch (error) {
       lastError = error;
       // An aborted transfer is the caller's own deadline firing, not a blip.
-      if (error?.name === "AbortError" || !isRetryable(error)) throw error;
+      if (error?.name === "AbortError" || !retryable(error)) throw error;
       if (attempt === attempts - 1) break;
       await sleep(baseDelayMs * 2 ** attempt);
     }

package/src/remote/exec.js

@@ -15,6 +15,7 @@ import {
   delay,
   loadCliConfig,
   parseTimeoutMs as parseSharedTimeoutMs,
+  withRetry,
 } from "./client.js";
 
 export { EXIT, UsageError };
@@ -23,6 +24,14 @@ const DEFAULT_TIMEOUT_MS = 60_000;
 const POLL_INTERVAL_MS = 1_000;
 /** How long a single request may block server-side before we switch to polling. */
 const POST_WAIT_MS = 10_000;
+/**
+ * A 429 means the per-user in-flight cap (8) is full — nothing was started, so
+ * retrying is safe. Six attempts at 500ms doubling waits out ~15s, longer than
+ * one saturating POST can block (POST_WAIT_MS). Nothing else is retried here:
+ * a 5xx may have started the command already, and a second POST would run it twice.
+ */
+const POST_RETRY = { attempts: 6, retryable: (error) => error?.status === 429 };
+const INTERRUPT_SIGNALS = ["SIGINT", "SIGTERM"];
 
 const VALUE_FLAGS = new Map([
   ["--target", "target"],
@@ -120,7 +129,8 @@ Options:
       --timeout <dur>     Overall deadline, e.g. 30s, 2m, 500ms (default: 60s)
   -e, --env KEY=VALUE     Extra environment variable (repeatable)
       --json              Print the raw run result as JSON
-      --kill-on-timeout   Stop the remote command when --timeout is reached
+      --kill-on-timeout   Stop the remote command when --timeout is reached or
+                          this CLI is interrupted (Ctrl-C, SIGTERM)
                           (default: it keeps running on the target)
       --config-file <p>   Conductor config file to authenticate with
   -h, --help              Show this help
@@ -132,6 +142,9 @@ Notes:
   Exit codes follow ssh: the remote command's own code is passed through, and
   255 means this CLI failed (bad usage, daemon offline, network error).
 
+  A command that outlives --timeout keeps running on the target; the run id is
+  printed and \`conductor remote wait -t <daemon> <runId>\` picks it up again.
+
 Examples:
   conductor remote exec --target ubuntu --workspace /home/duino/ws/holomotion ls .
   conductor remote exec -t ubuntu -w /srv/app -- git log --oneline -5
@@ -139,40 +152,23 @@ Examples:
 }
 
 /**
- * Run one command on `target` and return the final run record.
- *
- * This is the programmatic half of `runRemoteExec`: same two-phase POST-then-poll
- * behaviour, no argv parsing and no printing. `remote cp -r` uses it to drive
- * `tar` on the target.
+ * Poll `run` until it leaves `running`, the deadline passes, or `signal`
+ * aborts. With `killOnTimeout` a run that is still going at that point is
+ * cancelled on the target. Shared by `exec` (after its POST) and `wait`.
  */
-export async function execRemote(config, target, command, options = {}) {
+export async function waitForRun(config, basePath, initialRun, options = {}) {
   const {
-    args = [],
-    workspace,
-    env,
-    timeoutMs = DEFAULT_TIMEOUT_MS,
+    deadline,
     fetchImpl = globalThis.fetch,
     sleep = delay,
     now = () => Date.now(),
     killOnTimeout = false,
+    signal,
   } = options;
 
-  const basePath = `/api/agents/${encodeURIComponent(target)}/exec`;
-  const deadline = now() + timeoutMs;
-
-  let run = await callApi(config, "POST", basePath, {
-    command,
-    args,
-    ...(workspace ? { workspace } : {}),
-    ...(env && Object.keys(env).length > 0 ? { env } : {}),
-    // Deliberately short, and independent of the overall deadline: that is
-    // owned by the poll loop below. Handing the daemon the full budget would
-    // make one HTTP request block for it and leave the loop unreachable.
-    timeoutMs: Math.min(timeoutMs, POST_WAIT_MS),
-  }, fetchImpl);
-
+  let run = initialRun;
   let pollError = null;
-  while (run?.status === "running" && now() < deadline) {
+  while (run?.status === "running" && now() < deadline && !signal?.aborted) {
     if (!run.runId) {
       pollError = new Error("daemon reported a running command but returned no runId");
       break;
@@ -211,7 +207,47 @@ export async function execRemote(config, target, command, options = {}) {
     }
   }
 
-  return { run, pollError, killError, basePath };
+  return { run, pollError, killError };
+}
+
+/**
+ * Run one command on `target` and return the final run record.
+ *
+ * This is the programmatic half of `runRemoteExec`: same two-phase POST-then-poll
+ * behaviour, no argv parsing and no printing. `remote cp -r` uses it to drive
+ * `tar` on the target.
+ */
+export async function execRemote(config, target, command, options = {}) {
+  const {
+    args = [],
+    workspace,
+    env,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl = globalThis.fetch,
+    sleep = delay,
+    now = () => Date.now(),
+    killOnTimeout = false,
+    signal,
+  } = options;
+
+  const basePath = `/api/agents/${encodeURIComponent(target)}/exec`;
+  const deadline = now() + timeoutMs;
+
+  const started = await withRetry(() => callApi(config, "POST", basePath, {
+    command,
+    args,
+    ...(workspace ? { workspace } : {}),
+    ...(env && Object.keys(env).length > 0 ? { env } : {}),
+    // Deliberately short, and independent of the overall deadline: that is
+    // owned by the poll loop below. Handing the daemon the full budget would
+    // make one HTTP request block for it and leave the loop unreachable.
+    timeoutMs: Math.min(timeoutMs, POST_WAIT_MS),
+  }, fetchImpl), { ...POST_RETRY, sleep });
+
+  const waited = await waitForRun(config, basePath, started, {
+    deadline, fetchImpl, sleep, now, killOnTimeout, signal,
+  });
+  return { ...waited, basePath };
 }
 
 /**
@@ -229,6 +265,60 @@ export async function execRemoteOrThrow(config, target, command, options = {}) {
   throw new Error(detail ? `${what} on ${target}: ${detail}` : `${what} on ${target}`);
 }
 
+/**
+ * An AbortSignal that fires on Ctrl-C / SIGTERM. Installing a listener also
+ * stops Node from exiting on the signal, which is the point: the CLI gets to
+ * print the run id (and cancel the run with --kill-on-timeout) before it goes.
+ * Callers must `release()` so the default behaviour comes back.
+ */
+export function interruptSignal(proc = process) {
+  const controller = new AbortController();
+  const onSignal = () => controller.abort();
+  for (const name of INTERRUPT_SIGNALS) proc.on(name, onSignal);
+  return {
+    signal: controller.signal,
+    release: () => {
+      for (const name of INTERRUPT_SIGNALS) proc.off(name, onSignal);
+    },
+  };
+}
+
+/** Print a finished (or abandoned) run the way `exec` and `wait` both do, and pick the exit code. */
+export function reportRun(run, { consoleImpl, json, target, pollError, waitedMs, interrupted }) {
+  if (json) {
+    consoleImpl.log(JSON.stringify(run, null, 2));
+  } else {
+    if (run?.stdoutTail) process.stdout.write(run.stdoutTail);
+    if (run?.stderrTail) process.stderr.write(run.stderrTail);
+    if (run?.truncated) {
+      consoleImpl.error(`[conductor] output truncated; showing the tail only`);
+    }
+    if (run?.error) {
+      consoleImpl.error(`Error: ${run.error}`);
+    }
+  }
+
+  if (run?.status === "running") {
+    if (pollError) {
+      consoleImpl.error(`[conductor] last status poll failed: ${pollError.message}`);
+    }
+    const why = interrupted ? "interrupted" : `still running on ${target} after ${waitedMs}ms`;
+    consoleImpl.error(
+      `[conductor] ${why}; it keeps going on ${target} — ` +
+        `resume with: conductor remote wait -t ${target} ${run.runId} ` +
+        `(add --kill-on-timeout to stop it instead)`,
+    );
+    return EXIT.CLI_ERROR;
+  }
+  if (run?.status === "cancelled") {
+    return EXIT.CLI_ERROR;
+  }
+  if (typeof run?.exitCode === "number") {
+    return run.exitCode;
+  }
+  return run?.status === "completed" ? EXIT.OK : EXIT.CLI_ERROR;
+}
+
 export async function runRemoteExec(argv, deps = {}) {
   const consoleImpl = deps.console || console;
   const fetchImpl = deps.fetch || globalThis.fetch;
@@ -278,12 +368,12 @@ export async function runRemoteExec(argv, deps = {}) {
     return EXIT.CLI_ERROR;
   }
 
+  const interrupt = interruptSignal(deps.process);
   let run;
   let pollError = null;
-  let basePath;
   try {
     let killError;
-    ({ run, pollError, killError, basePath } = await execRemote(config, target, command[0], {
+    ({ run, pollError, killError } = await execRemote(config, target, command[0], {
       args: command.slice(1),
       workspace: options.workspace,
       env: options.env,
@@ -292,46 +382,27 @@ export async function runRemoteExec(argv, deps = {}) {
       sleep,
       now,
       killOnTimeout: options.killOnTimeout,
+      signal: interrupt.signal,
     }));
     if (killError) {
       consoleImpl.error(`[conductor] failed to stop the run on ${target}: ${killError.message}`);
     } else if (options.killOnTimeout && run?.status === "cancelled") {
-      consoleImpl.error(`[conductor] deadline reached; stopped the command on ${target}`);
+      const why = interrupt.signal.aborted ? "interrupted" : "deadline reached";
+      consoleImpl.error(`[conductor] ${why}; stopped the command on ${target}`);
     }
   } catch (error) {
     consoleImpl.error(`Error: ${error.message}`);
     return EXIT.CLI_ERROR;
+  } finally {
+    interrupt.release();
   }
 
-  if (options.json) {
-    consoleImpl.log(JSON.stringify(run, null, 2));
-  } else {
-    if (run?.stdoutTail) process.stdout.write(run.stdoutTail);
-    if (run?.stderrTail) process.stderr.write(run.stderrTail);
-    if (run?.truncated) {
-      consoleImpl.error(`[conductor] output truncated; showing the tail only`);
-    }
-    if (run?.error) {
-      consoleImpl.error(`Error: ${run.error}`);
-    }
-  }
-
-  if (run?.status === "running") {
-    if (pollError) {
-      consoleImpl.error(`[conductor] last status poll failed: ${pollError.message}`);
-    }
-    consoleImpl.error(
-      `[conductor] still running on ${target} after ${timeoutMs}ms; ` +
-        `it keeps going there — poll GET ${basePath}/runs/${run.runId}, ` +
-        `stop it with DELETE on the same path, or use --kill-on-timeout`,
-    );
-    return EXIT.CLI_ERROR;
-  }
-  if (run?.status === "cancelled") {
-    return EXIT.CLI_ERROR;
-  }
-  if (typeof run?.exitCode === "number") {
-    return run.exitCode;
-  }
-  return run?.status === "completed" ? EXIT.OK : EXIT.CLI_ERROR;
+  return reportRun(run, {
+    consoleImpl,
+    json: options.json,
+    target,
+    pollError,
+    waitedMs: timeoutMs,
+    interrupted: interrupt.signal.aborted,
+  });
 }

package/src/remote/wait.js

@@ -0,0 +1,133 @@
+/**
+ * `conductor remote wait` — pick up a command started by `remote exec` that
+ * outlived its deadline (or the process that started it).
+ *
+ * `exec` prints the run id whenever it leaves a command behind; this verb
+ * polls that run the same way `exec` would have and reports it identically,
+ * so a caller can always finish what it started.
+ */
+
+import process from "node:process";
+
+import { EXIT, callApi, delay, loadCliConfig } from "./client.js";
+import {
+  interruptSignal,
+  parseArgs,
+  parseTimeoutMs,
+  reportRun,
+  waitForRun,
+} from "./exec.js";
+
+export function showHelp(consoleImpl = console) {
+  consoleImpl.log(`conductor remote wait - wait for a command left running by \`remote exec\`
+
+Usage:
+  conductor remote wait --target <daemon> [options] <runId>
+
+Options:
+  -t, --target <daemon>   Daemon the command is running on (required)
+      --timeout <dur>     How long to wait this time, e.g. 30s, 2m (default: 60s)
+      --json              Print the raw run result as JSON
+      --kill-on-timeout   Stop the remote command when --timeout is reached or
+                          this CLI is interrupted (default: it keeps running)
+      --config-file <p>   Conductor config file to authenticate with
+  -h, --help              Show this help
+
+Output and exit codes match \`conductor remote exec\`: the command's own exit
+code is passed through, 255 means this CLI failed or the command is still running.
+
+Example:
+  conductor remote exec -t ubuntu --timeout 30s -- make build
+  # ... [conductor] still running on ubuntu after 30000ms; resume with:
+  conductor remote wait -t ubuntu --timeout 20m 3f9c1b2e-...
+`);
+}
+
+export async function runRemoteWait(argv, deps = {}) {
+  const consoleImpl = deps.console || console;
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const env = deps.env || process.env;
+  const sleep = deps.sleep || delay;
+  const now = deps.now || (() => Date.now());
+
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  }
+  const { options, command } = parsed;
+
+  if (options.help) {
+    showHelp(consoleImpl);
+    return EXIT.OK;
+  }
+
+  const target = typeof options.target === "string" ? options.target.trim() : "";
+  if (!target) {
+    consoleImpl.error("Error: --target <daemon> is required");
+    showHelp(consoleImpl);
+    return EXIT.CLI_ERROR;
+  }
+  if (command.length !== 1) {
+    consoleImpl.error(command.length === 0 ? "Error: no runId given" : "Error: expected exactly one runId");
+    showHelp(consoleImpl);
+    return EXIT.CLI_ERROR;
+  }
+  const runId = command[0];
+
+  let timeoutMs;
+  try {
+    timeoutMs = parseTimeoutMs(options.timeout);
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  }
+
+  let config;
+  try {
+    config = deps.config || loadCliConfig(options.configFile, env);
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  }
+
+  const basePath = `/api/agents/${encodeURIComponent(target)}/exec`;
+  const interrupt = interruptSignal(deps.process);
+  let run;
+  let pollError = null;
+  try {
+    const deadline = now() + timeoutMs;
+    run = await callApi(config, "GET", `${basePath}/runs/${encodeURIComponent(runId)}`, null, fetchImpl);
+    let killError;
+    ({ run, pollError, killError } = await waitForRun(config, basePath, run, {
+      deadline,
+      fetchImpl,
+      sleep,
+      now,
+      killOnTimeout: options.killOnTimeout,
+      signal: interrupt.signal,
+    }));
+    if (killError) {
+      consoleImpl.error(`[conductor] failed to stop the run on ${target}: ${killError.message}`);
+    } else if (options.killOnTimeout && run?.status === "cancelled") {
+      const why = interrupt.signal.aborted ? "interrupted" : "deadline reached";
+      consoleImpl.error(`[conductor] ${why}; stopped the command on ${target}`);
+    }
+  } catch (error) {
+    consoleImpl.error(`Error: ${error.message}`);
+    return EXIT.CLI_ERROR;
+  } finally {
+    interrupt.release();
+  }
+
+  return reportRun(run, {
+    consoleImpl,
+    json: options.json,
+    target,
+    pollError,
+    waitedMs: timeoutMs,
+    interrupted: interrupt.signal.aborted,
+  });
+}