impel-cli 0.18.18-beta.0 → 0.19.0

package/src/remote/process.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { redactSecretText } from "../config.js";
+
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+
+export class RemoteProcessError extends Error {
+  constructor(command, args, result) {
+    const rendered = [command, ...args].map((value) => JSON.stringify(String(value))).join(" ");
+    const detail = redactSecretText(result?.stderr || result?.error?.message || "command failed").trim();
+    super(`${rendered} failed${detail ? `: ${detail}` : ""}`);
+    this.command = command;
+    this.args = [...args];
+    this.status = Number.isInteger(result?.status) ? result.status : 1;
+  }
+}
+
+export function findExecutable(command, environment = process.env) {
+  if (path.isAbsolute(command)) {
+    try {
+      fs.accessSync(command, fs.constants.X_OK);
+      return command;
+    } catch {
+      return null;
+    }
+  }
+  const pathValue = environment.PATH || "";
+  for (const directory of pathValue.split(path.delimiter)) {
+    if (!directory) continue;
+    const candidate = path.join(directory, command);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // Keep searching PATH.
+    }
+  }
+  return null;
+}
+
+export function requireExecutables(commands, environment = process.env) {
+  const missing = commands.filter((command) => !findExecutable(command, environment));
+  if (missing.length > 0) {
+    throw new Error(`required command${missing.length === 1 ? " is" : "s are"} not installed: ${missing.join(", ")}`);
+  }
+}
+
+export function runCapture(command, args = [], {
+  cwd,
+  env = process.env,
+  input,
+  maxBuffer = DEFAULT_MAX_BUFFER,
+  allowFailure = false,
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    input,
+    encoding: "utf8",
+    maxBuffer,
+    windowsHide: true,
+  });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    throw new RemoteProcessError(command, args, result);
+  }
+  return {
+    status: Number.isInteger(result.status) ? result.status : 1,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    error: result.error || null,
+  };
+}
+
+export function runBuffer(command, args = [], {
+  cwd,
+  env = process.env,
+  input,
+  maxBuffer = DEFAULT_MAX_BUFFER,
+  allowFailure = false,
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    input,
+    encoding: null,
+    maxBuffer,
+    windowsHide: true,
+  });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    throw new RemoteProcessError(command, args, {
+      ...result,
+      stderr: result.stderr?.toString("utf8") || "",
+    });
+  }
+  return {
+    status: Number.isInteger(result.status) ? result.status : 1,
+    stdout: result.stdout || Buffer.alloc(0),
+    stderr: result.stderr || Buffer.alloc(0),
+    error: result.error || null,
+  };
+}
+
+export function runInteractive(command, args = [], {
+  cwd,
+  env = process.env,
+  inputFile,
+  allowFailure = false,
+} = {}) {
+  let descriptor;
+  try {
+    if (inputFile) descriptor = fs.openSync(inputFile, "r");
+    const result = spawnSync(command, args, {
+      cwd,
+      env,
+      stdio: [descriptor ?? "inherit", "inherit", "inherit"],
+      windowsHide: false,
+    });
+    if (!allowFailure && (result.error || result.status !== 0)) {
+      throw new RemoteProcessError(command, args, result);
+    }
+    return Number.isInteger(result.status) ? result.status : 1;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+export function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/src/remote/state.js

@@ -0,0 +1,202 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { CONFIG_DIR } from "../config.js";
+import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
+import { renameWithWindowsRetry } from "../windowsFs.js";
+
+export const REMOTE_STATE_VERSION = 1;
+export const REMOTE_ROOT = process.env.IMPEL_REMOTE_STATE_DIR || path.join(CONFIG_DIR, "remote");
+export const REMOTE_RUNS_DIR = path.join(REMOTE_ROOT, "runs");
+export const SSH_CONFIG_PATH = process.env.IMPEL_REMOTE_SSH_CONFIG || path.join(os.homedir(), ".ssh", "config");
+
+const RUN_ID_RE = /^run_[a-z0-9]{16}$/u;
+const SSH_START_PREFIX = "# >>> impel remote ";
+const SSH_END_PREFIX = "# <<< impel remote ";
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function ensurePrivateDirectory(directory) {
+  const existing = lstatOrNull(directory);
+  if (existing?.isSymbolicLink()) throw new Error(`${directory} must not be a symbolic link`);
+  if (existing && !existing.isDirectory()) throw new Error(`${directory} must be a directory`);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(directory, 0o700); } catch { /* Best effort on Windows. */ }
+}
+
+function atomicWrite(filePath, contents, mode = 0o600) {
+  ensurePrivateDirectory(path.dirname(filePath));
+  const existing = lstatOrNull(filePath);
+  if (existing?.isSymbolicLink()) throw new Error(`${filePath} must not be a symbolic link`);
+  if (existing && !existing.isFile()) throw new Error(`${filePath} must be a regular file`);
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode });
+    renameWithWindowsRetry(temporaryPath, filePath);
+    try { fs.chmodSync(filePath, mode); } catch { /* Best effort on Windows. */ }
+  } finally {
+    try { fs.rmSync(temporaryPath, { force: true }); } catch { /* Rename removed it. */ }
+  }
+}
+
+export function newRunId() {
+  return `run_${crypto.randomBytes(10).toString("hex").slice(0, 16)}`;
+}
+
+export function validateRunId(runId) {
+  const normalized = String(runId || "").trim();
+  if (!RUN_ID_RE.test(normalized)) throw new Error(`invalid remote run id ${JSON.stringify(normalized)}`);
+  return normalized;
+}
+
+export function runDirectory(runId) {
+  return path.join(REMOTE_RUNS_DIR, validateRunId(runId));
+}
+
+export function runPaths(runId) {
+  const root = runDirectory(runId);
+  return {
+    root,
+    state: path.join(root, "run.json"),
+    privateKey: path.join(root, "id_ed25519"),
+    publicKey: path.join(root, "id_ed25519.pub"),
+    knownHosts: path.join(root, "known_hosts"),
+    bundle: path.join(root, "repo.bundle"),
+    fileList: path.join(root, "files.list"),
+    archive: path.join(root, "working-tree.tar"),
+    deletedList: path.join(root, "deleted.list"),
+  };
+}
+
+export function initializeRun(runId) {
+  const paths = runPaths(runId);
+  ensurePrivateDirectory(paths.root);
+  return paths;
+}
+
+export function writeRunState(state) {
+  const runId = validateRunId(state?.runId);
+  const next = { ...state, schemaVersion: REMOTE_STATE_VERSION, updatedAt: new Date().toISOString() };
+  atomicWrite(runPaths(runId).state, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+export function readRunState(runId) {
+  const statePath = runPaths(runId).state;
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`remote run ${runId} does not exist`);
+    throw new Error(`${statePath} is not a valid remote run state file`);
+  }
+  if (value?.schemaVersion !== REMOTE_STATE_VERSION || value?.runId !== runId) {
+    throw new Error(`${statePath} has an unsupported remote run state version`);
+  }
+  return value;
+}
+
+export function listRunStates() {
+  let entries;
+  try {
+    entries = fs.readdirSync(REMOTE_RUNS_DIR, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const states = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !RUN_ID_RE.test(entry.name)) continue;
+    try { states.push(readRunState(entry.name)); } catch { /* A corrupt run is not selected implicitly. */ }
+  }
+  return states.sort((left, right) => String(right.createdAt).localeCompare(String(left.createdAt)));
+}
+
+export function resolveRunId(requested, { includeStopped = false } = {}) {
+  if (requested) return validateRunId(requested);
+  const current = listRunStates().find((state) => includeStopped || state.status !== "stopped");
+  if (!current) throw new Error("no active remote run found; start one with `impel remote up`");
+  return current.runId;
+}
+
+export function sshAlias(runId) {
+  return `impel-${validateRunId(runId).replaceAll("_", "-")}`;
+}
+
+function sshQuote(value) {
+  const text = String(value);
+  if (/[\r\n\0]/u.test(text)) throw new Error("unsafe value in managed SSH configuration");
+  return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function removeManagedBlock(text, runId) {
+  const startMarker = `${SSH_START_PREFIX}${runId} >>>`;
+  const endMarker = `${SSH_END_PREFIX}${runId} <<<`;
+  const start = text.indexOf(startMarker);
+  if (start === -1) return text;
+  const end = text.indexOf(endMarker, start + startMarker.length);
+  if (end === -1) throw new Error(`${SSH_CONFIG_PATH} has an incomplete Impel remote block for ${runId}`);
+  const after = end + endMarker.length;
+  return `${text.slice(0, start).trimEnd()}${text.slice(after).trimStart() ? `\n${text.slice(after).trimStart()}` : ""}`;
+}
+
+export function installSshAlias(state) {
+  const { runId } = state;
+  const paths = runPaths(runId);
+  const alias = state.alias || sshAlias(runId);
+  const current = fs.existsSync(SSH_CONFIG_PATH) ? fs.readFileSync(SSH_CONFIG_PATH, "utf8") : "";
+  const preserved = removeManagedBlock(current, runId).trimEnd();
+  const proxyTokens = [process.execPath, IMPEL_CLI_ENTRYPOINT, "remote", "proxy", runId, "--port", "%p"];
+  const block = [
+    `${SSH_START_PREFIX}${runId} >>>`,
+    `Host ${alias}`,
+    `  HostName ${runId}.remote.impel.invalid`,
+    "  User agent",
+    "  Port 22",
+    `  IdentityFile ${sshQuote(paths.privateKey)}`,
+    "  IdentitiesOnly yes",
+    "  BatchMode yes",
+    "  StrictHostKeyChecking accept-new",
+    `  UserKnownHostsFile ${sshQuote(paths.knownHosts)}`,
+    `  ProxyCommand ${proxyTokens.map(sshQuote).join(" ")}`,
+    `${SSH_END_PREFIX}${runId} <<<`,
+  ].join("\n");
+  // OpenSSH keeps the first value it obtains for most settings. Put concrete
+  // Impel hosts before user wildcard blocks so a preceding `Host *` cannot
+  // replace this run's user, hostname, key, or ProxyCommand.
+  atomicWrite(SSH_CONFIG_PATH, `${block}${preserved ? `\n\n${preserved}` : ""}\n`);
+  return alias;
+}
+
+export function removeSshAlias(runId) {
+  if (!fs.existsSync(SSH_CONFIG_PATH)) return false;
+  const current = fs.readFileSync(SSH_CONFIG_PATH, "utf8");
+  const next = removeManagedBlock(current, validateRunId(runId));
+  if (next === current) return false;
+  atomicWrite(SSH_CONFIG_PATH, next.trim() ? `${next.trimEnd()}\n` : "");
+  return true;
+}
+
+export function removeRunSecrets(runId) {
+  const paths = runPaths(runId);
+  for (const target of [
+    paths.privateKey,
+    paths.publicKey,
+    paths.knownHosts,
+    paths.bundle,
+    paths.fileList,
+    paths.archive,
+    paths.deletedList,
+  ]) {
+    try { fs.rmSync(target, { force: true }); } catch { /* Best-effort local cleanup. */ }
+  }
+}

package/src/remote/transfer.js

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { tenantCliProfilePaths } from "../cliProfiles.js";
+import { redactSecretText } from "../config.js";
+import { runBuffer, runCapture, runInteractive, sleep } from "./process.js";
+import { runPaths } from "./state.js";
+
+const REMOTE_REPO = "/workspace/repo";
+const REMOTE_BUNDLE = "/tmp/impel-remote-repo.bundle";
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+function git(args, options = {}) {
+  return runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", args, options).stdout.trim();
+}
+
+function sshArgs(state, command) {
+  return [state.alias, command];
+}
+
+function sshCapture(state, command, options = {}) {
+  return runCapture(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", sshArgs(state, command), options);
+}
+
+function remoteShellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function remoteNode(state, source, payload) {
+  const evaluator = "eval(Buffer.from(process.argv[1],'base64').toString('utf8'))";
+  const encodedSource = Buffer.from(source, "utf8").toString("base64");
+  return sshCapture(state, `node -e ${remoteShellQuote(evaluator)} ${remoteShellQuote(encodedSource)}`, {
+    input: `${JSON.stringify(payload)}\n`,
+  });
+}
+
+function writePrivate(filePath, contents) {
+  fs.writeFileSync(filePath, contents, { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch { /* Best effort on Windows. */ }
+}
+
+export function inspectRepository(requestedPath = process.cwd()) {
+  const requested = path.resolve(requestedPath);
+  const candidate = fs.realpathSync(requested);
+  const root = fs.realpathSync(git(["-C", candidate, "rev-parse", "--show-toplevel"]));
+  const head = git(["-C", root, "rev-parse", "HEAD"]);
+  const branchResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", root, "symbolic-ref", "--quiet", "--short", "HEAD",
+  ], { allowFailure: true });
+  const originResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", root, "remote", "get-url", "origin",
+  ], { allowFailure: true });
+  const userNameResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", root, "config", "--get", "user.name",
+  ], { allowFailure: true });
+  const userEmailResult = runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", root, "config", "--get", "user.email",
+  ], { allowFailure: true });
+  const relativeProjectPath = path.relative(root, candidate) || ".";
+  if (relativeProjectPath === ".." || relativeProjectPath.startsWith(`..${path.sep}`)) {
+    throw new Error(`${candidate} is not inside its Git repository`);
+  }
+  return {
+    root,
+    head,
+    branch: branchResult.status === 0 ? branchResult.stdout.trim() : null,
+    origin: originResult.status === 0 ? originResult.stdout.trim() : null,
+    userName: userNameResult.status === 0 ? userNameResult.stdout.trim() : null,
+    userEmail: userEmailResult.status === 0 ? userEmailResult.stdout.trim() : null,
+    relativeProjectPath: relativeProjectPath.split(path.sep).join("/"),
+    remoteProjectPath: relativeProjectPath === "."
+      ? REMOTE_REPO
+      : `${REMOTE_REPO}/${relativeProjectPath.split(path.sep).join("/")}`,
+  };
+}
+
+export function createRepositoryTransfer(state, repository) {
+  const paths = runPaths(state.runId);
+  runCapture(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", repository.root, "bundle", "create", paths.bundle, "--all",
+  ]);
+
+  const deleted = runBuffer(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", repository.root, "ls-files", "--deleted", "-z",
+  ]).stdout;
+  writePrivate(paths.deletedList, deleted);
+  const deletedPaths = new Set(splitNullBuffer(deleted).map((entry) => entry.toString("base64")));
+  const listedFiles = runBuffer(process.env.IMPEL_REMOTE_GIT_BIN || "git", [
+    "-C", repository.root, "ls-files", "--cached", "--others", "--exclude-standard", "-z",
+  ]).stdout;
+  const files = joinNullBuffer(splitNullBuffer(listedFiles).filter(
+    (entry) => !deletedPaths.has(entry.toString("base64")),
+  ));
+  writePrivate(paths.fileList, files);
+  runCapture(process.env.IMPEL_REMOTE_TAR_BIN || "tar", [
+    "-cf", paths.archive,
+    "--no-xattrs",
+    "--null",
+    "-T", paths.fileList,
+  ], { cwd: repository.root });
+  return paths;
+}
+
+function splitNullBuffer(buffer) {
+  const entries = [];
+  let start = 0;
+  while (start < buffer.length) {
+    const end = buffer.indexOf(0, start);
+    if (end === -1) throw new Error("Git returned a malformed NUL-delimited path list");
+    if (end > start) entries.push(buffer.subarray(start, end));
+    start = end + 1;
+  }
+  return entries;
+}
+
+function joinNullBuffer(entries) {
+  if (entries.length === 0) return Buffer.alloc(0);
+  return Buffer.concat(entries.flatMap((entry) => [entry, Buffer.from([0])]));
+}
+
+export async function waitForSsh(state, timeoutSeconds = 120) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let lastError = "SSH did not accept a connection";
+  while (Date.now() < deadline) {
+    const result = sshCapture(state, "true", { allowFailure: true });
+    if (result.status === 0) return;
+    lastError = redactSecretText(result.stderr || lastError).trim();
+    await sleep(Number(process.env.IMPEL_REMOTE_SSH_POLL_MS || 2000));
+  }
+  throw new Error(`remote runner did not become SSH-ready within ${timeoutSeconds} seconds: ${lastError}`);
+}
+
+export function uploadRemoteConfiguration(state, {
+  config,
+  credential,
+  tenant,
+  environmentNames = [],
+}) {
+  const remoteConfig = {
+    pat: credential.token,
+    gatewayUrl: config.gatewayUrl,
+    appUrl: config.appUrl,
+    ...(config.sessionsUrl ? { sessionsUrl: config.sessionsUrl } : {}),
+    tenantId: tenant.tenantId,
+    tenantName: tenant.tenantName,
+    ...(tenant.productAccess ? { productAccess: tenant.productAccess } : {}),
+    scopes: [...credential.scopes],
+    remoteRunId: state.runId,
+    updatedAt: new Date().toISOString(),
+  };
+  const selectedEnvironment = {
+    IMPEL_REMOTE_RUN_ID: state.runId,
+    IMPEL_REMOTE_DANGEROUS_MODE: "1",
+  };
+  for (const name of environmentNames) {
+    if (!ENV_NAME_RE.test(name)) throw new Error(`invalid environment variable name ${JSON.stringify(name)}`);
+    if (!Object.hasOwn(process.env, name)) throw new Error(`environment variable ${name} is not set`);
+    selectedEnvironment[name] = process.env[name];
+  }
+  const shellQuote = (value) => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  const environmentFile = Object.entries(selectedEnvironment)
+    .map(([name, value]) => `export ${name}=${shellQuote(value)}`)
+    .join("\n") + "\n";
+  const profileRoot = `/home/agent/.config/impel/cli/tenants/${tenant.tenantId}`;
+  const claudeSettings = {
+    permissions: { defaultMode: "bypassPermissions" },
+    sandbox: { enabled: false },
+  };
+  const files = [
+    { path: "/home/agent/.config/impel/config.json", contents: `${JSON.stringify(remoteConfig, null, 2)}\n` },
+    { path: "/home/agent/.config/impel/remote/env.sh", contents: environmentFile },
+    {
+      path: "/home/agent/.config/impel/remote/run.json",
+      contents: `${JSON.stringify({
+        runId: state.runId,
+        credentialTokenId: credential.tokenId,
+        expiresAt: state.expiresAt,
+      }, null, 2)}\n`,
+    },
+    { path: `${profileRoot}/claude/settings.json`, contents: `${JSON.stringify(claudeSettings, null, 2)}\n` },
+  ];
+  remoteNode(state, String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+for (const file of payload.files) {
+  const target = path.resolve(file.path);
+  if (!target.startsWith("/home/agent/.config/impel/")) throw new Error("refusing remote path");
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(target, file.contents, { mode: 0o600 });
+  fs.chmodSync(target, 0o600);
+}
+`, { files });
+}
+
+export function uploadRepository(state, repository) {
+  const paths = runPaths(state.runId);
+  runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", sshArgs(state, `cat > ${REMOTE_BUNDLE}`), {
+    inputFile: paths.bundle,
+  });
+  remoteNode(state, String.raw`
+const fs = require("node:fs");
+const cp = require("node:child_process");
+const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+const repo = "/workspace/repo";
+fs.rmSync(repo, { recursive: true, force: true });
+fs.mkdirSync("/workspace", { recursive: true });
+cp.execFileSync("git", ["clone", "/tmp/impel-remote-repo.bundle", repo], { stdio: "inherit" });
+cp.execFileSync("git", ["-C", repo, "checkout", "--detach", payload.head], { stdio: "inherit" });
+if (payload.branch) cp.execFileSync("git", ["-C", repo, "checkout", "-B", payload.branch, payload.head], { stdio: "inherit" });
+if (payload.origin) cp.execFileSync("git", ["-C", repo, "remote", "set-url", "origin", payload.origin], { stdio: "inherit" });
+if (payload.userName) cp.execFileSync("git", ["-C", repo, "config", "user.name", payload.userName]);
+if (payload.userEmail) cp.execFileSync("git", ["-C", repo, "config", "user.email", payload.userEmail]);
+`, repository);
+
+  runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", sshArgs(state, `tar -xf - -C ${REMOTE_REPO}`), {
+    inputFile: paths.archive,
+  });
+  const deleted = fs.readFileSync(paths.deletedList);
+  remoteNode(state, String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+const root = "/workspace/repo";
+for (const relative of payload.deleted) {
+  const target = path.resolve(root, relative);
+  if (target !== root && !target.startsWith(root + path.sep)) throw new Error("unsafe deleted path");
+  fs.rmSync(target, { recursive: true, force: true });
+}
+fs.rmSync("/tmp/impel-remote-repo.bundle", { force: true });
+`, { deleted: deleted.toString("utf8").split("\0").filter(Boolean) });
+}
+
+export function prepareWorkspace(state, { installMode = "auto", setupCommand = null } = {}) {
+  if (!new Set(["auto", "skip"]).has(installMode)) throw new Error("--install must be auto or skip");
+  if (installMode === "auto") {
+    runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", ["-t", state.alias, "impel-remote-prepare", REMOTE_REPO]);
+  }
+  if (setupCommand) {
+    const encodedCommand = Buffer.from(setupCommand, "utf8").toString("base64");
+    const source = "const cp=require('node:child_process');const command=Buffer.from(process.argv[1],'base64').toString('utf8');const child=cp.spawnSync('/bin/bash',['-lc',command],{cwd:'/workspace/repo',stdio:'inherit'});process.exit(Number.isInteger(child.status)?child.status:1)";
+    runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", [
+      "-t", state.alias, `node -e ${remoteShellQuote(source)} ${remoteShellQuote(encodedCommand)}`,
+    ]);
+  }
+}
+
+function collectSessionFiles(root, sessionId) {
+  const files = [];
+  const visit = (directory, relative = "") => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const childRelative = relative ? path.join(relative, entry.name) : entry.name;
+      const child = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) visit(child, childRelative);
+      else if (entry.isFile() && childRelative.includes(sessionId)) files.push(childRelative);
+    }
+  };
+  if (fs.existsSync(root)) visit(root);
+  return files;
+}
+
+export function transferSessionCheckpoint(state, { provider, sessionId, tenantId }) {
+  if (!SESSION_ID_RE.test(String(sessionId || ""))) throw new Error("--session must be a safe provider session id");
+  const profiles = tenantCliProfilePaths(tenantId);
+  const localRoot = provider === "claude" ? profiles.claudeConfigDir : profiles.codexHome;
+  const remoteRoot = provider === "claude"
+    ? `/home/agent/.config/impel/cli/tenants/${tenantId}/claude`
+    : `/home/agent/.config/impel/cli/tenants/${tenantId}/codex`;
+  const files = collectSessionFiles(localRoot, sessionId);
+  if (files.length === 0) {
+    throw new Error(`could not find ${provider} session ${sessionId} in the selected Impel CLI profile`);
+  }
+  const checkpointList = path.join(runPaths(state.runId).root, `checkpoint-${provider}.list`);
+  const checkpointArchive = path.join(runPaths(state.runId).root, `checkpoint-${provider}.tar`);
+  writePrivate(checkpointList, Buffer.from(`${files.join("\0")}\0`, "utf8"));
+  try {
+    runCapture(process.env.IMPEL_REMOTE_TAR_BIN || "tar", [
+      "-cf", checkpointArchive, "--no-xattrs", "--null", "-T", checkpointList,
+    ], { cwd: localRoot });
+    sshCapture(state, `mkdir -p ${remoteRoot}`);
+    runInteractive(process.env.IMPEL_REMOTE_SSH_BIN || "ssh", sshArgs(state, `tar -xf - -C ${remoteRoot}`), {
+      inputFile: checkpointArchive,
+    });
+  } finally {
+    fs.rmSync(checkpointList, { force: true });
+    fs.rmSync(checkpointArchive, { force: true });
+  }
+  return files.length;
+}
+
+export const REMOTE_PROJECT_ROOT = REMOTE_REPO;

package/src/verbatimRelay.js

@@ -1,64 +0,0 @@
-export const VERBATIM_RELAY_OPT_IN_MARKER = "verbatimRelay enabled";
-
-export const VERBATIM_SPAWN_REQUIREMENT = 'fork_turns="none"';
-
-export const VERBATIM_FINAL_TEXT_CONSTRAINTS =
-  "no preface, rewriting, Markdown changes, or independent synthesis";
-
-export function usesVerbatimRelay(agent) {
-  return agent?.verbatimRelay === true;
-}
-
-export function parentVerbatimRelayAppendix() {
-  return (
-    `When an explicit custom agent's catalog-derived description declares that verbatimRelay is enabled, ` +
-    `spawn it with ${VERBATIM_SPAWN_REQUIREMENT} and relay its finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}; ` +
-    "preserve Sources sections and citations exactly. " +
-    "Custom agents without that declaration keep the default delegation behavior."
-  );
-}
-
-export function customAgentVerbatimDescriptionLead() {
-  return (
-    `Explicit custom agent with ${VERBATIM_RELAY_OPT_IN_MARKER}: ` +
-    `callers must use ${VERBATIM_SPAWN_REQUIREMENT} and relay its result verbatim`
-  );
-}
-
-export function adapterCallerSpawnGuidance(clientLabel) {
-  return (
-    `Callers must spawn this explicit custom ${clientLabel} agent with ${VERBATIM_SPAWN_REQUIREMENT} ` +
-    "and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior."
-  );
-}
-
-export function adapterHardCompletionGuidance() {
-  return (
-    `After the orchestration completes, return its single text output verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
-    "A successful output is result.finalText exactly. A failure output preserves the durable runId, output, and error."
-  );
-}
-
-export function adapterSoftCompletionGuidance() {
-  return (
-    "After the orchestration completes, return its single text output as the answer. " +
-    "A successful output is result.finalText. A failure output preserves the durable runId, output, and error. " +
-    "Never invent or independently synthesize a replacement result."
-  );
-}
-
-export function claudeHardCompletionGuidance() {
-  return (
-    `When it succeeds, return result.finalText exactly with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}. ` +
-    "When it fails, return the durable runId, preserved output, and error. " +
-    "Never invent or independently synthesize a replacement result."
-  );
-}
-
-export function claudeSoftCompletionGuidance() {
-  return (
-    "When it succeeds, return result.finalText faithfully as the answer. " +
-    "When it fails, return the durable runId, preserved output, and error. " +
-    "Never invent or independently synthesize a replacement result."
-  );
-}