@love-moon/conductor-cli 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @love-moon/conductor-cli
 
+## 0.12.0
+
+### Minor Changes
+
+- b749180: Add `conductor remote cp` for copying a single file to or from another daemon's
+  host, and fold the existing `remote-exec` command into a `conductor remote`
+  umbrella alongside it.
+
+  - `conductor remote exec ...` replaces `conductor remote-exec ...`. Behaviour is
+    unchanged; only the command path moved.
+  - `conductor remote cp <src> <dst>` follows scp: exactly one side is written as
+    `<daemon>:<path>`, and that decides the direction. Contents are verified end
+    to end with SHA-256 and written via a temporary file plus rename, so an
+    interrupted copy never truncates an existing file.
+  - `conductor remote cp -r` copies a directory, matching scp's destination
+    rules. It packs with `tar`, moves the one tarball through the ordinary
+    transfer and unpacks on the other side, so permissions and symlinks survive
+    and the wire protocol is unchanged. Needs `tar` and `remote_exec` on the
+    target; the limit applies to the compressed size.
+  - New `remote_file` daemon capability, declinable with `remote_file: false` in
+    the config or `CONDUCTOR_REMOTE_FILE=0`, kept separate from `remote_exec` so
+    version skew fails with a clean 409 instead of a timeout.
+  - Transfers are chunked at 32 MiB with `Content-Range` and resume automatically
+    after a network blip, from the server's offset going up and from the local
+    partial file coming down. Chunking is also what keeps the server safe at the
+    raised limit: no single request is large or long-lived.
+  - The per-file limit is now 1 GiB, bounded by a global staged-bytes budget
+    (8 GiB), a per-user budget (2 GiB), a free-disk floor, and reservation by
+    declared size at creation.
+  - Bytes travel over HTTP through the backend rather than the agent WebSocket.
+    The socket only carries a small control message. See RFC 0037.
+
+  Deploying this needs the updated `web/nginx_conf`: the file-transfer routes set
+  `client_max_body_size` to 64m — a per-chunk cap, not a per-file one — and turn
+  off `proxy_request_buffering`.
+
+### Patch Changes
+
+- @love-moon/conductor-sdk@0.12.0
+- @love-moon/ai-sdk@0.12.0
+
 ## 0.11.2
 
 ### Patch Changes

package/bin/conductor-config.js

@@ -387,6 +387,10 @@ async function main() {
     "# Env: CONDUCTOR_REMOTE_EXEC",
     "# remote_exec: true",
     "",
+    "# Accept `conductor remote cp` file transfers for this host.",
+    "# Env: CONDUCTOR_REMOTE_FILE",
+    "# remote_file: true",
+    "",
     "# Launch each Fire process inside a detached tmux session so it survives a",
     "# daemon restart. Requires tmux on PATH. Env: CONDUCTOR_FIRE_TMUX_MODE",
     "# fire_tmux_mode: false",

package/bin/conductor-remote.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * conductor remote — act on another daemon's host.
+ *
+ *   conductor remote exec --target ubuntu -- bash -lc "pnpm build 2>&1 | tail -20"
+ *   conductor remote cp ./build.tar.gz ubuntu:/srv/app/build.tar.gz
+ *   conductor remote cp ubuntu:/var/log/conductor.log ./conductor.log
+ *
+ * Verb dispatch is hand-rolled rather than delegated to yargs on purpose:
+ * `exec` has to hand an arbitrary remote argv through untouched, and yargs'
+ * `strict()` would try to interpret the remote command's own flags.
+ */
+
+import path from "node:path";
+import process from "node:process";
+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";
+
+export { EXIT };
+
+const VERBS = new Map([
+  ["exec", runRemoteExec],
+  ["cp", runRemoteCp],
+]);
+
+const isMainModule = (() => {
+  const currentFile = fileURLToPath(import.meta.url);
+  const entryFile = process.argv[1] ? path.resolve(process.argv[1]) : "";
+  return entryFile === currentFile;
+})();
+
+export function showHelp(consoleImpl = console) {
+  consoleImpl.log(`conductor remote - act on another daemon's host
+
+Usage:
+  conductor remote <verb> [options]
+
+Verbs:
+  exec   Run a command on another daemon's host
+  cp     Copy a file to or from another daemon's host
+
+Options:
+  -h, --help   Show this help
+
+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
+
+For verb-specific help:
+  conductor remote exec --help
+  conductor remote cp --help
+`);
+}
+
+export async function runRemote(argv, deps = {}) {
+  const consoleImpl = deps.console || console;
+
+  if (argv.length === 0) {
+    showHelp(consoleImpl);
+    return EXIT.CLI_ERROR;
+  }
+
+  const verb = argv[0];
+  if (verb === "--help" || verb === "-h") {
+    showHelp(consoleImpl);
+    return EXIT.OK;
+  }
+
+  const handler = VERBS.get(verb);
+  if (!handler) {
+    // `--help` on a verb belongs to the verb, but a bare flag in the verb slot
+    // is a usage mistake worth naming precisely.
+    consoleImpl.error(`Error: unknown verb '${verb}'`);
+    consoleImpl.error(`Valid verbs: ${[...VERBS.keys()].join(", ")}`);
+    showHelp(consoleImpl);
+    return EXIT.CLI_ERROR;
+  }
+
+  return handler(argv.slice(1), deps);
+}
+
+export { showExecHelp, showCpHelp };
+
+if (isMainModule) {
+  // `process.exitCode` rather than `process.exit()`: writes to a pipe are async,
+  // and exiting outright truncates them. Let the loop drain and end naturally.
+  process.exitCode = await runRemote(process.argv.slice(2));
+}

package/bin/conductor-send-file.js

@@ -182,34 +182,56 @@ export async function sendFileToTask(options) {
   body.set("file", new Blob([fileBuffer], { type: mimeType }), fileName);
 
   const content = typeof options.content === "string" ? options.content.trim() : "";
-  if (content) {
-    body.set("content", content);
-  }
-
   const role = typeof options.role === "string" && options.role.trim()
     ? options.role.trim().toLowerCase()
     : "sdk";
-  body.set("role", role);
+  const authHeaders = {
+    Authorization: `Bearer ${config.agentToken}`,
+    Accept: "application/json",
+  };
 
-  const url = new URL(`/api/tasks/${encodeURIComponent(taskId)}/attachments`, config.backendUrl);
-  const response = await fetchImpl(String(url), {
+  // Phase 1 stages the bytes. This endpoint only stores the file; the row it
+  // creates carries no message and expires within the attachment TTL.
+  const uploadUrl = new URL(`/api/tasks/${encodeURIComponent(taskId)}/attachments`, config.backendUrl);
+  const uploadResponse = await fetchImpl(String(uploadUrl), {
     method: "POST",
-    headers: {
-      Authorization: `Bearer ${config.agentToken}`,
-      Accept: "application/json",
-    },
+    headers: authHeaders,
     body,
   });
 
-  const rawText = await response.text();
-  if (!response.ok) {
-    const details = formatErrorBody(rawText);
-    throw new Error(`Upload failed (${response.status})${details ? `: ${details}` : ""}`);
+  const uploadText = await uploadResponse.text();
+  if (!uploadResponse.ok) {
+    const details = formatErrorBody(uploadText);
+    throw new Error(`Upload failed (${uploadResponse.status})${details ? `: ${details}` : ""}`);
+  }
+  const attachment = (uploadText ? JSON.parse(uploadText) : {}).attachment;
+  if (!attachment || !attachment.id) {
+    throw new Error("Upload succeeded but the server returned no attachment id");
+  }
+
+  // Phase 2 binds the staged file to a message. Without it the attachment
+  // never reaches the chat UI and the janitor deletes it when staging expires.
+  const messageUrl = new URL(`/api/tasks/${encodeURIComponent(taskId)}/messages`, config.backendUrl);
+  const messageResponse = await fetchImpl(String(messageUrl), {
+    method: "POST",
+    headers: { ...authHeaders, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      content: content || `Attached file: ${attachment.name}`,
+      role,
+      attachmentIds: [attachment.id],
+    }),
+  });
+
+  const messageText = await messageResponse.text();
+  if (!messageResponse.ok) {
+    const details = formatErrorBody(messageText);
+    throw new Error(`Attach failed (${messageResponse.status})${details ? `: ${details}` : ""}`);
   }
 
   return {
     taskId,
-    response: rawText ? JSON.parse(rawText) : {},
+    attachment,
+    response: messageText ? JSON.parse(messageText) : {},
   };
 }
 

package/bin/conductor.js

@@ -15,7 +15,7 @@
  *   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-exec - Run a command on another daemon's host
+ *   remote   - Run commands and copy files on another daemon's host
  */
 
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -51,7 +51,7 @@ export function runConductorCli(args = argv, deps = {}) {
     "project",
     "issue",
     "task",
-    "remote-exec",
+    "remote",
   ];
 
   if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
@@ -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-exec Run a command on another daemon's host
+  remote    Run commands and copy files on another daemon's host (exec/cp)
 
 Options:
   -h, --help     Show this help message
@@ -162,7 +162,8 @@ Examples:
   conductor task create --title "Refactor module" --prompt "Extract the parser" --backend codex
   conductor task send <task-id> "please add a unit test"
   conductor task schedule create <task-id> "follow up" --delay 10m
-  conductor remote-exec --target ubuntu --workspace /home/duino/ws/holomotion ls .
+  conductor remote exec --target ubuntu --workspace /home/duino/ws/holomotion ls .
+  conductor remote cp ./build.tar.gz ubuntu:/srv/app/build.tar.gz
 
 For subcommand-specific help:
   conductor fire --help
@@ -176,7 +177,7 @@ For subcommand-specific help:
   conductor project --help
   conductor issue --help
   conductor task --help
-  conductor remote-exec --help
+  conductor remote --help
 
 Version: ${pkgJson.version}
 `);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.11.2",
-  "gitCommitId": "067735d",
+  "version": "0.12.0",
+  "gitCommitId": "c1047e8",
   "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.11.2",
-    "@love-moon/conductor-sdk": "0.11.2",
+    "@love-moon/ai-sdk": "0.12.0",
+    "@love-moon/conductor-sdk": "0.12.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.11.2"
+    "@love-moon/chat-web": "0.12.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/daemon.js

@@ -42,6 +42,11 @@ import {
   createRemoteExecHandlers,
   handleRemoteExecRequest,
 } from "./remote-exec-handlers.js";
+import {
+  REMOTE_FILE_CAPABILITY,
+  createRemoteFileHandlers,
+  handleRemoteFileRequest,
+} from "./remote-file-handlers.js";
 import {
   UPDATE_DAEMON_CAPABILITY,
   createDaemonUpdateHandlers,
@@ -288,6 +293,33 @@ function getRemoteExecEnabled(userConfig) {
   return true;
 }
 
+// Whether this host will accept `conductor remote cp` file transfers (RFC
+// 0037). Kept separate from `remote_exec` on purpose: the two are not distinct
+// trust levels — anyone with exec can already `base64` a file — but a host may
+// well want scripted commands without letting the account push bytes onto its
+// disk, and a separate flag is the only way to say that.
+//
+// Resolution order:
+//   1. CONDUCTOR_REMOTE_FILE env var ("1"/"true"/"on" enable, "0"/"false"/"off" disable)
+//   2. remote_file boolean in the resolved Conductor config.yaml
+//   3. Default: true
+function getRemoteFileEnabled(userConfig) {
+  const rawEnv = process.env.CONDUCTOR_REMOTE_FILE;
+  if (typeof rawEnv === "string" && rawEnv.trim()) {
+    const normalized = rawEnv.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true" || normalized === "on" || normalized === "yes") {
+      return true;
+    }
+    if (normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no") {
+      return false;
+    }
+  }
+  if (userConfig && typeof userConfig === "object" && userConfig.remote_file === false) {
+    return false;
+  }
+  return true;
+}
+
 function normalizePlanLimitType(limitType) {
   if (typeof limitType !== "string") {
     return null;
@@ -1154,6 +1186,10 @@ export function startDaemon(config = {}, deps = {}) {
   // path would cost function without removing reach (RFC 0034 makes the same
   // argument). An owner who wants it off can set `remote_exec: false`.
   const remoteExecEnabled = getRemoteExecEnabled(userConfig);
+  // Same reasoning for file transfer, with one addition: when the share scoped
+  // the guest to a root, transfers are confined to it (`isPathInsideGuestRoot`,
+  // a lexical check — misuse prevention, not a security boundary).
+  const remoteFileEnabled = getRemoteFileEnabled(userConfig);
 
   // Get allow_cli_list from config
   const RAW_ALLOW_CLI_LIST = getRawAllowCliList(userConfig);
@@ -3764,6 +3800,11 @@ export function startDaemon(config = {}, deps = {}) {
   } else {
     log("[remote-exec] Disabled by config (remote_exec: false); capability not advertised");
   }
+  if (remoteFileEnabled) {
+    advertisedCapabilities.push(REMOTE_FILE_CAPABILITY);
+  } else {
+    log("[remote-file] Disabled by config (remote_file: false); capability not advertised");
+  }
   if (ptyTaskCapabilityEnabled) {
     advertisedCapabilities.push("pty_task", "terminal_snapshot");
   }
@@ -3831,6 +3872,13 @@ export function startDaemon(config = {}, deps = {}) {
   const remoteExecHandlers = remoteExecEnabled
     ? createRemoteExecHandlers({ defaultWorkspace: homeDir })
     : null;
+  const remoteFileHandlers = remoteFileEnabled
+    ? createRemoteFileHandlers({
+        config: sdkConfig,
+        agentHost: AGENT_NAME,
+        guestRoot: IS_GUEST_DAEMON ? GUEST_ROOT : null,
+      })
+    : null;
 
   const client = createWebSocketClient(sdkConfig, {
     extraHeaders,
@@ -6334,6 +6382,50 @@ export function startDaemon(config = {}, deps = {}) {
         logError(`Unhandled remote_exec_request failure: ${error?.message || error}`);
       });
     }
+    if (event.type === "remote_file_request") {
+      // Same reason as remote exec: a transfer leaves no Task row and no
+      // per-run log, so it would be invisible after a restart. Only the action,
+      // the path and the byte count are recorded — never file contents, and
+      // never the transfer token, because this log is collected by
+      // `collect_logs`.
+      const fileArgs = event?.payload?.args && typeof event.payload.args === "object" ? event.payload.args : {};
+      log(
+        `[remote-file] ${event?.payload?.action || "?"} path=${fileArgs.remotePath || fileArgs.remote_path || ""} ` +
+          `bytes=${fileArgs.sizeBytes ?? fileArgs.size_bytes ?? "?"}`,
+      );
+      // Fail fast rather than letting the caller wait out its full timeout —
+      // it has no other way to learn that this daemon will never answer.
+      const rejectReason = !remoteFileHandlers
+        ? "remote file transfer is disabled on this daemon (remote_file: false)"
+        : daemonShuttingDown
+          ? "daemon is shutting down"
+          : "";
+      if (rejectReason) {
+        void client
+          .sendJson({
+            type: "remote_file_response",
+            payload: {
+              request_id: event?.payload?.request_id ? String(event.payload.request_id) : "",
+              action: event?.payload?.action ? String(event.payload.action) : "",
+              error: rejectReason,
+            },
+          })
+          .catch(() => {});
+        return;
+      }
+      handleRemoteFileRequest(client, remoteFileHandlers, event.payload)
+        .then((response) => {
+          if (response?.result) {
+            log(
+              `[remote-file] ${event?.payload?.action || "?"} ok path=${response.result.path || ""} ` +
+                `bytes=${response.result.bytesWritten ?? response.result.sizeBytes ?? "?"}`,
+            );
+          }
+        })
+        .catch((error) => {
+          logError(`Unhandled remote_file_request failure: ${error?.message || error}`);
+        });
+    }
     if (event.type === "restart_daemon") {
       void handleRestartDaemon(event.payload).catch((error) => {
         logError(`Unhandled restart_daemon failure: ${error?.message || error}`);
@@ -7258,6 +7350,49 @@ export function startDaemon(config = {}, deps = {}) {
       });
   }
 
+  /**
+   * Recover the workspace of a resumable session from the backend's own
+   * session store. Used when neither a launch-config cwd nor a bound project
+   * path is available -- the Default Project resuming a local session -- so the
+   * task runs (and logs) where the conversation actually lives instead of an
+   * unrelated scratch directory.
+   *
+   * Returns "" when the session cannot be located; callers keep their own
+   * fallbacks. `runtimeBackend` short-circuits the alias lookup for callers
+   * that already resolved it.
+   */
+  async function resolveSessionResumeCwd({ backendType, runtimeBackend = "", sessionId }) {
+    const normalizedSessionId = typeof sessionId === "string" ? sessionId.trim() : "";
+    const normalizedBackend = normalizeRuntimeBackendName(backendType);
+    // opencode has no resumable local session store to look the cwd up in.
+    if (!normalizedSessionId || !normalizedBackend || normalizedBackend === "opencode") {
+      return "";
+    }
+    try {
+      let resumeBackend = normalizeOptionalString(runtimeBackend);
+      if (!resumeBackend) {
+        const configuredBackend = await resolveConfiguredRuntimeBackend(normalizedBackend, ALLOW_CLI_LIST, {
+          configFilePath: config.CONFIG_FILE,
+        });
+        resumeBackend = configuredBackend?.runtimeBackend ||
+          await normalizeRuntimeBackendAlias(normalizedBackend, { configFilePath: config.CONFIG_FILE });
+      }
+      const resumeContext = await (deps.resolveResumeContext || resolveResumeContext)(
+        resumeBackend,
+        normalizedSessionId,
+        {
+          cwd: process.cwd(),
+          configFilePath: config.CONFIG_FILE,
+        },
+      );
+      return normalizeOptionalString(resumeContext?.cwd) || "";
+    } catch {
+      // Provider lookup failed (unknown id, unreadable store): let the caller
+      // fall back rather than failing the task here.
+      return "";
+    }
+  }
+
   async function resolveRestartCwd({
     taskId,
     projectId,
@@ -7291,29 +7426,9 @@ export function startDaemon(config = {}, deps = {}) {
       return boundPath;
     }
 
-    const normalizedBackend = normalizeRuntimeBackendName(backendType);
-    const normalizedSessionId = typeof sessionId === "string" ? sessionId.trim() : "";
-    if (normalizedSessionId && normalizedBackend && normalizedBackend !== "opencode") {
-      try {
-        const configuredBackend = await resolveConfiguredRuntimeBackend(normalizedBackend, ALLOW_CLI_LIST, {
-          configFilePath: config.CONFIG_FILE,
-        });
-        const resumeBackend = configuredBackend?.runtimeBackend ||
-          await normalizeRuntimeBackendAlias(normalizedBackend, { configFilePath: config.CONFIG_FILE });
-        const resumeContext = await (deps.resolveResumeContext || resolveResumeContext)(
-          resumeBackend,
-          normalizedSessionId,
-          {
-            cwd: process.cwd(),
-            configFilePath: config.CONFIG_FILE,
-          },
-        );
-        if (typeof resumeContext?.cwd === "string" && resumeContext.cwd.trim()) {
-          return resumeContext.cwd.trim();
-        }
-      } catch {
-        // ignore provider-specific fallback failure here; we'll try the remaining fallbacks
-      }
+    const sessionCwd = await resolveSessionResumeCwd({ backendType, sessionId });
+    if (sessionCwd) {
+      return sessionCwd;
     }
 
     const normalizedSessionPath =
@@ -7474,7 +7589,14 @@ export function startDaemon(config = {}, deps = {}) {
           launchConfig,
         })) ||
         normalizeOptionalString(launchConfig.cwd) ||
-        boundPath;
+        boundPath ||
+        (await resolveSessionResumeCwd({
+          backendType: requestedBackend,
+          runtimeBackend: effectiveBackend,
+          sessionId:
+            normalizeOptionalString(launchConfig?.resumeSessionId) ||
+            normalizeOptionalString(launchConfig?.resume_session_id),
+        }));
 
       if (resolvedTaskWorkspace) {
         taskDir = resolvedTaskWorkspace;
@@ -8567,6 +8689,9 @@ export function startDaemon(config = {}, deps = {}) {
         clearInterval(tmuxLivenessTimer);
         tmuxLivenessTimer = null;
       }
+      // An in-flight transfer holds an open socket and a `.part` file; abort
+      // them so shutdown is not gated on a multi-gigabyte download finishing.
+      remoteFileHandlers?.abortAll();
       const activeProcessEntries = [...activeTaskProcesses.entries()];
       const activePtyEntries = [...activePtySessions.entries()];
       const activeEntries = [...activeProcessEntries, ...activePtyEntries];

package/src/remote/archive.js

@@ -0,0 +1,129 @@
+/**
+ * Directory transfer, built on the single-file path plus `tar`.
+ *
+ * `remote cp -r` packs a directory locally (or remotely), moves the one
+ * resulting tarball through the ordinary transfer, then unpacks it on the other
+ * side. No new protocol: the wire still only ever carries one file.
+ *
+ * The remote halves run through `sh -c` with the paths passed as **positional
+ * arguments**, never interpolated into the script text. A directory literally
+ * named `; rm -rf /` is therefore just an awkward directory name.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+/** Where the target stages its tarball. Overridable for hosts without /tmp. */
+export function remoteTempPath(env = process.env) {
+  const root = (env.CONDUCTOR_REMOTE_TMP || "/tmp").replace(/\/+$/, "") || "/tmp";
+  return `${root}/.conductor-rcp-${randomUUID()}.tgz`;
+}
+
+export function localTempPath() {
+  return path.join(os.tmpdir(), `.conductor-rcp-${randomUUID()}.tgz`);
+}
+
+/**
+ * Unpack `$1` into `$2`, following scp: an existing destination directory
+ * receives the source *inside* it; a missing one becomes the copy itself.
+ * `$3` is the source's basename, which is the top-level entry in the tarball.
+ */
+export const EXTRACT_SCRIPT = `
+set -e
+tmp=$1; dest=$2; base=$3
+if [ -d "$dest" ]; then
+  tar xzf "$tmp" -C "$dest"
+else
+  parent=$(dirname "$dest")
+  mkdir -p "$parent"
+  # Unpack into a private staging dir, never straight into the parent: the
+  # tarball's top entry is the SOURCE's name, and an unrelated neighbour of
+  # the destination could already have it. Extracting in place would clobber
+  # that neighbour, and the rename below would then carry it off.
+  # Staging inside the parent keeps the final mv on one filesystem.
+  stage=$(mktemp -d "$parent/.conductor-rcp-XXXXXX")
+  tar xzf "$tmp" -C "$stage"
+  rm -rf "$dest"
+  mv "$stage/$base" "$dest"
+  rmdir "$stage"
+fi
+`.trim();
+
+/** Pack directory `$1` into tarball `$2`, keeping `$1`'s own name inside. */
+export const PACK_SCRIPT = `
+set -e
+src=$1; tmp=$2
+if [ ! -d "$src" ]; then
+  echo "not a directory: $src" >&2
+  exit 1
+fi
+tar czf "$tmp" -C "$(dirname "$src")" "$(basename "$src")"
+`.trim();
+
+/** Remove the staged tarball. Never fails the transfer. */
+export const CLEANUP_SCRIPT = 'rm -f "$1"';
+
+/** `sh -c <script> sh <args...>` — the `sh` placeholder becomes $0. */
+export function shellArgs(script, ...args) {
+  return ["-c", script, "sh", ...args];
+}
+
+function runLocal(command, args, { spawnFn = spawn } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnFn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      // Bounded: a pathological tar could otherwise stream forever.
+      if (stderr.length < 8192) stderr += String(chunk);
+    });
+    child.on("error", (error) =>
+      reject(new Error(`failed to run ${command}: ${error.message}`)));
+    child.on("close", (code) => {
+      if (code === 0) return resolve();
+      reject(new Error(`${command} exited ${code}${stderr.trim() ? `: ${stderr.trim()}` : ""}`));
+    });
+  });
+}
+
+/** Pack a local directory, preserving its own name as the top-level entry. */
+export async function packLocalDirectory(sourceDir, tarball, deps = {}) {
+  await runLocal(
+    "tar",
+    ["czf", tarball, "-C", path.dirname(sourceDir), path.basename(sourceDir)],
+    deps,
+  );
+  return tarball;
+}
+
+/** Unpack locally with the same scp semantics as `EXTRACT_SCRIPT`. */
+export async function unpackLocalDirectory(tarball, destination, baseName, deps = {}) {
+  const fsp = deps.fsp || fs.promises;
+  let destStat = null;
+  try {
+    destStat = await fsp.stat(destination);
+  } catch {
+    destStat = null;
+  }
+
+  if (destStat?.isDirectory()) {
+    await runLocal("tar", ["xzf", tarball, "-C", destination], deps);
+    return path.join(destination, baseName);
+  }
+
+  const parent = path.dirname(destination);
+  await fsp.mkdir(parent, { recursive: true });
+  // Same reasoning as EXTRACT_SCRIPT: stage in a private directory so an
+  // existing neighbour that happens to share the source's name survives.
+  const stage = await fsp.mkdtemp(path.join(parent, ".conductor-rcp-"));
+  try {
+    await runLocal("tar", ["xzf", tarball, "-C", stage], deps);
+    await fsp.rm(destination, { recursive: true, force: true });
+    await fsp.rename(path.join(stage, baseName), destination);
+  } finally {
+    await fsp.rm(stage, { recursive: true, force: true }).catch(() => {});
+  }
+  return destination;
+}