@williamthorsen/nmr 0.48.0 → 0.49.0

package/dist/esm/remote-probe.d.ts

@@ -0,0 +1,31 @@
+import { type HostList } from './remote-run.js';
+/** What a probe found on a host: whether a delegation started now would wait there, or that the host did not answer. */
+export type ProbeResult = 'busy' | 'free' | 'no-answer';
+/**
+ * Probes every host at once and resolves to the one on which to run, per `selectHost`, as soon as the results that
+ * have arrived settle it. Reports each result that arrives before then, and aborts the probes still running once it
+ * has chosen.
+ */
+export declare function chooseHost(options: {
+    hosts: HostList;
+    onSettled: (host: string, result: ProbeResult) => void;
+    probe: (host: string, signal: AbortSignal) => Promise<ProbeResult>;
+}): Promise<string>;
+/**
+ * Asks `host` whether a delegation from this checkout would wait there: whether its machine lock, or the lock of the
+ * checkout at `checkoutPath`, has a live holder. A host that fails to run the probe, or does not print its report,
+ * did not answer.
+ */
+export declare function probeHost(options: {
+    checkoutPath: string;
+    env: NodeJS.ProcessEnv;
+    host: string;
+    signal: AbortSignal;
+}): Promise<ProbeResult>;
+/**
+ * Returns the host on which to run, or `undefined` while a host whose result could change the choice has not
+ * answered: the first free host in list order, otherwise the first busy one, otherwise the first host.
+ *
+ * @internal
+ */
+export declare function selectHost(hosts: HostList, results: ReadonlyMap<string, ProbeResult>): string | undefined;

package/dist/esm/remote-probe.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { isObject } from "./helpers/type-guards.js";
+import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "./machine-lock.js";
+import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
+import { probeHostLocks } from "./remote-probe-host.js";
+import { runSsh } from "./remote-run.js";
+export function chooseHost(options) {
+    const { hosts, onSettled, probe } = options;
+    const controller = new AbortController();
+    const results = new Map();
+    return new Promise((resolve) => {
+        for (const host of hosts) {
+            void settle(host, resolve);
+        }
+    });
+    async function settle(host, resolve) {
+        let result;
+        try {
+            result = await probe(host, controller.signal);
+        }
+        catch {
+            result = 'no-answer';
+        }
+        if (controller.signal.aborted)
+            return;
+        results.set(host, result);
+        onSettled(host, result);
+        const chosen = selectHost(hosts, results);
+        if (chosen === undefined)
+            return;
+        controller.abort();
+        resolve(chosen);
+    }
+}
+export async function probeHost(options) {
+    const { checkoutPath, env, host, signal } = options;
+    const params = {
+        checkoutLockPath: path.posix.join(checkoutPath, CHECKOUT_LOCK_PATH),
+        lockDirEnvVar: LOCK_DIR_ENV_VAR,
+        machineLockFile: LOCK_FILE,
+        staleAfterMs: STALE_AFTER_MS,
+    };
+    const source = `(${probeHostLocks.toString()})(JSON.parse(process.argv[1]));`;
+    const { exitCode, output } = await runSsh(host, `exec node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`, env, signal);
+    if (exitCode !== 0) {
+        return 'no-answer';
+    }
+    const busy = output
+        .split('\n')
+        .map(readBusyField)
+        .findLast((value) => value !== undefined);
+    if (busy === undefined) {
+        return 'no-answer';
+    }
+    return busy ? 'busy' : 'free';
+}
+export function selectHost(hosts, results) {
+    for (const host of hosts) {
+        const result = results.get(host);
+        if (result === undefined) {
+            return undefined;
+        }
+        if (result === 'free') {
+            return host;
+        }
+    }
+    return hosts.find((host) => results.get(host) === 'busy') ?? hosts[0];
+}
+function readBusyField(line) {
+    try {
+        const value = JSON.parse(line);
+        return isObject(value) && typeof value['busy'] === 'boolean' ? value['busy'] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/remote-run.d.ts

@@ -1,78 +1,38 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-/** Names the host to which nmr delegates a command when the invocation does not say otherwise. */
+/** Names the hosts to which nmr delegates a command when the invocation does not say otherwise. */
 export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
-/** The flag that names the host on which to run the command. */
+/** The flag that runs the command on a host that `NMR_DELEGATE` or the user config names. */
 export declare const DELEGATE_FLAG = "--delegate";
+/** The flag that names the hosts on which to run the command. */
+export declare const DELEGATE_TO_FLAG = "--delegate-to";
 /** The exit status of a delegation that failed outside its command, which matches `ssh`'s own. */
 export declare const DELEGATION_FAILURE_EXIT_CODE = 255;
-/** The flag that runs the command here, whatever `NMR_DELEGATE` names. */
+/** The flag that runs the command here, whatever `NMR_DELEGATE` or the user config says. */
 export declare const NO_DELEGATE_FLAG = "--no-delegate";
 /** Keeps `ssh` from prompting or waiting on a terminal, and bounds the wait for a host that does not answer. */
 export declare const SSH_OPTIONS: readonly string[];
-/** Where a delegation runs, or why the invocation cannot run where it asked to. */
-export type DelegationTarget = {
-    kind: 'local';
-} | {
-    kind: 'remote';
-    host: string;
-    source: 'env' | 'flag';
-} | {
-    kind: 'refused';
-    error: string;
-};
+/** Candidate hosts in order of preference. */
+export type HostList = readonly [string, ...string[]];
 /** The phases of a delegation that run on the host, each reported by name when it fails. */
 export type RemotePhase = 'check out' | 'install' | 'prepare' | 'push' | 'run';
-/** The status of a delegated command, or the phase that kept it from finishing and what that phase printed. */
+/**
+ * The status of a delegated command and the pass-manifest entries that its run reported, unvalidated, or the phase
+ * that kept it from finishing and what that phase printed, with how long the delegation waited for another
+ * delegation's checkout.
+ */
 export type RemoteRunResult = {
     ok: true;
     exitCode: number;
+    passes: unknown[];
+    waitedMs: number;
 } | {
     ok: false;
     message: string;
     output: string;
     phase: RemotePhase;
-};
-/** A commit that records the working tree, or why one could not be made. */
-export type SnapshotResult = {
-    ok: true;
-    sha: string;
-    toplevel: string;
-} | {
-    ok: false;
-    isUnsupported: boolean;
-    reason: string;
+    waitedMs: number;
 };
-/**
- * Composes the script that runs nmr on the host, from the directory that corresponds to the local one.
- *
- * A Node launcher starts nmr in its own process group, with stdin closed, and reads the connection's stdin, which the
- * local `ssh` holds open and closes when it exits, as on Ctrl-C; on that end of input, the launcher stops nmr's whole
- * group, so that an interrupted run does not continue on the host. The launcher rather than the shell's job control
- * makes the group, because a shell such as dash refuses job control without a terminal. `--no-delegate` keeps a host
- * whose environment sets `NMR_DELEGATE` from passing the command on again.
- *
- * The script writes nmr's status to `statusPath` before it exits, so that a 255 from `ssh` can be told apart: It is
- * nmr's own when the file records it, and a dropped connection otherwise.
- *
- * @internal
- */
-export declare function composeRunScript(options: {
-    nmrArgs: readonly string[];
-    remoteEnv: Readonly<Record<string, string>>;
-    runDir: string;
-    statusPath: string;
-}): string;
-/**
- * Builds a commit whose tree is the working tree as it is on disk: tracked changes, staged or not, and untracked
- * files that git does not ignore. The commit is built in a temporary index, so the repository's index, refs, and
- * stash are untouched; the only write is to the object database.
- *
- * The identity and date are fixed, so that the same tree on the same `HEAD` always yields the same commit and a
- * repeated push transfers nothing. A submodule, or a nested repository that `git add` would record as one, is
- * refused: Its content is in a repository that the snapshot does not include.
- */
-export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): SnapshotResult;
 /**
  * Returns the checkout's path on the host, relative to its home directory: a key derived from this machine and the
  * repository, followed by the repository's own directory name, which nmr on the host reports as the root's scope.
@@ -81,34 +41,22 @@ export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): Sna
  */
 export declare function deriveCheckoutPath(hostname: string, toplevel: string): string;
 /**
- * Renders the warning for a `--delegate` or `--no-delegate` that appears after the command name, which makes it an
- * argument to the command rather than a flag to nmr.
+ * Renders the warning for a delegation flag that appears after the command name, which makes it an argument to the
+ * command rather than a flag to nmr.
  */
 export declare function formatMisplacedDelegationWarning(command: string, style: OutputStyle): string;
-/**
- * Decides where an invocation runs. `--no-delegate` outranks `--delegate`, which outranks `NMR_DELEGATE`.
- *
- * A command that rewrites the tree, or that runs until it is stopped, cannot be delegated, and neither can `--log`,
- * which reads this machine's recordings. Asked for by the flag, such an invocation is refused; asked for by the
- * variable, which sets a default for every invocation, it runs here.
- */
-export declare function resolveDelegationTarget(options: {
-    command: string;
-    env: NodeJS.ProcessEnv;
-    flagHost: string | undefined;
-    isOptedOut: boolean;
-    isReading: boolean;
-}): DelegationTarget;
 /**
  * Runs an nmr invocation on `host` against a snapshot of the local working tree, streaming the command's output to
  * `stdout` and `stderr` and returning its exit status.
  *
  * The host keeps one checkout per local repository and host name, under `~/.cache/nmr/delegate/`, so concurrent
  * delegations from different worktrees do not share a checkout, and `node_modules` and build output persist
- * between runs. Each phase is its own connection, so that a failure names its phase; what a phase other than `run`
- * prints is returned rather than streamed, because it matters only when the phase fails.
+ * between runs. Check out, install, and run take one connection, whose session holds the checkout's lock, so that two
+ * delegations from one worktree run one after the other; what a phase other than `run` prints is returned rather than
+ * streamed, because it matters only when the phase fails.
  */
 export declare function runRemotely(options: {
+    command: string;
     cwd: string;
     env: NodeJS.ProcessEnv;
     host: string;
@@ -122,6 +70,13 @@ export declare function runRemotely(options: {
     stderr: Writable;
     stdout: Writable;
 }): Promise<RemoteRunResult>;
+/**
+ * Runs a script on the host through `wrapRemoteScript`, capturing what it prints. An abort stops the `ssh` process.
+ */
+export declare function runSsh(host: string, script: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
+    exitCode: number;
+    output: string;
+}>;
 /**
  * Wraps a script to run under `/bin/sh` with the `PATH` that the user's interactive login shell sets. pnpm's own
  * installer and the common version managers set it up in the interactive startup file, such as `~/.zshrc`, which a

package/dist/esm/remote-run.js

@@ -1,124 +1,37 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
-import { GIT_OUTPUT_LIMIT, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import process from 'node:process';
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
 import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
+import { STALE_AFTER_MS } from "./machine-lock.js";
+import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
+import { composeSessionScript, createSessionDemultiplexer, formatDelegationWaitingLine } from "./remote-session.js";
 export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
 export const DELEGATE_FLAG = '--delegate';
+export const DELEGATE_TO_FLAG = '--delegate-to';
 export const DELEGATION_FAILURE_EXIT_CODE = 255;
 export const NO_DELEGATE_FLAG = '--no-delegate';
 export const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10'];
-export function composeRunScript(options) {
-    const { nmrArgs, remoteEnv, runDir, statusPath } = options;
-    const assignments = Object.entries(remoteEnv).map(([name, value]) => `${name}=${quoteForShell(value)}`);
-    const invocation = [
-        ...assignments,
-        'node',
-        '-e',
-        quoteForShell(RUN_LAUNCHER_SOURCE),
-        'pnpm',
-        'exec',
-        'nmr',
-        '--no-delegate',
-        ...nmrArgs.map(quoteForShell),
-    ].join(' ');
-    return [
-        `rm -f ${statusPath}`,
-        `mkdir -p ${runDir} && cd ${runDir} || exit 1`,
-        invocation,
-        'nmr_status=$?',
-        String.raw `printf '%s\n' "$nmr_status" > ${statusPath}`,
-        'exit "$nmr_status"',
-    ].join('\n');
-}
-export function createSnapshot(cwd, env) {
-    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
-    if (!toplevelResult.ok) {
-        return { ok: false, isUnsupported: true, reason: `not a git repository: ${toplevelResult.error}` };
-    }
-    const toplevel = toplevelResult.stdout.trim();
-    if (fs.existsSync(path.join(toplevel, '.gitmodules'))) {
-        return { ok: false, isUnsupported: true, reason: 'the repository declares submodules' };
-    }
-    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, env);
-    if (!indexPathResult.ok) {
-        return { ok: false, isUnsupported: false, reason: indexPathResult.error };
-    }
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nmr-snapshot-'));
-    try {
-        const tempIndex = path.join(tempDir, 'index');
-        const indexPath = path.resolve(toplevel, indexPathResult.stdout.trim());
-        if (fs.existsSync(indexPath)) {
-            fs.copyFileSync(indexPath, tempIndex);
-        }
-        const indexEnv = { ...env, GIT_INDEX_FILE: tempIndex };
-        const addResult = runGit(['add', '--all'], toplevel, indexEnv);
-        if (!addResult.ok) {
-            return { ok: false, isUnsupported: false, reason: addResult.error };
-        }
-        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, indexEnv);
-        if (!stageResult.ok) {
-            return { ok: false, isUnsupported: false, reason: stageResult.error };
-        }
-        if (stageResult.stdout.split('\0').some((entry) => entry.startsWith('160000 '))) {
-            return { ok: false, isUnsupported: true, reason: 'the working tree contains a submodule or a nested repository' };
-        }
-        const treeResult = runGit(['write-tree'], toplevel, indexEnv);
-        if (!treeResult.ok) {
-            return { ok: false, isUnsupported: false, reason: treeResult.error };
-        }
-        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, env);
-        const parentArgs = headResult.ok ? ['-p', headResult.stdout.trim()] : [];
-        const commitResult = runGit(['commit-tree', treeResult.stdout.trim(), ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, { ...env, ...SNAPSHOT_IDENTITY_ENV });
-        if (!commitResult.ok) {
-            return { ok: false, isUnsupported: false, reason: commitResult.error };
-        }
-        return { ok: true, sha: commitResult.stdout.trim(), toplevel };
-    }
-    finally {
-        fs.rmSync(tempDir, { force: true, recursive: true });
-    }
-}
 export function deriveCheckoutPath(hostname, toplevel) {
     const key = createHash('sha256').update(`${hostname}\0${toplevel}`).digest('hex').slice(0, 16);
     return path.posix.join('.cache/nmr/delegate', key, path.basename(toplevel));
 }
 export function formatMisplacedDelegationWarning(command, style) {
-    return (`${STATUS_GLYPHS[style].warning.text} ${DELEGATE_FLAG} and ${NO_DELEGATE_FLAG} after the command name are passed ` +
-        `to \`${command}\`, not read by nmr. Did you mean \`nmr ${DELEGATE_FLAG} <host> ${command}\`?`);
-}
-export function resolveDelegationTarget(options) {
-    const { command, env, flagHost, isOptedOut, isReading } = options;
-    if (isOptedOut) {
-        return { kind: 'local' };
-    }
-    const isDelegable = !isReading && !NON_DELEGABLE_COMMANDS.has(command);
-    if (flagHost !== undefined) {
-        if (isDelegable) {
-            return { kind: 'remote', host: flagHost, source: 'flag' };
-        }
-        const subject = isReading ? '--log' : `\`${command}\``;
-        return {
-            kind: 'refused',
-            error: `${subject} cannot be delegated: it ${isReading ? "reads this machine's recordings" : 'rewrites the working tree or runs until stopped'}. Run it without ${DELEGATE_FLAG}.`,
-        };
-    }
-    const envHost = env[DELEGATE_ENV_VAR];
-    if (envHost !== undefined && envHost !== '' && isDelegable) {
-        return { kind: 'remote', host: envHost, source: 'env' };
-    }
-    return { kind: 'local' };
+    return (`${STATUS_GLYPHS[style].warning.text} ${DELEGATE_FLAG}, ${DELEGATE_TO_FLAG}, and ${NO_DELEGATE_FLAG} after the ` +
+        `command name are passed to \`${command}\`, not read by nmr. Write them before it: ` +
+        `\`nmr ${DELEGATE_TO_FLAG} <host> ${command}\`.`);
 }
 export async function runRemotely(options) {
-    const { cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, snapshot, stderr, stdout } = options;
+    const { command, cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, snapshot, stderr, stdout } = options;
     const checkoutPath = deriveCheckoutPath(os.hostname(), snapshot.toplevel);
     const checkoutDir = `"$HOME"/${quoteForShell(checkoutPath)}`;
     const prepare = await runSsh(host, `mkdir -p ${checkoutDir} && cd ${checkoutDir} && { [ -d .git ] || git init --quiet; }`, env);
     if (prepare.exitCode !== 0) {
-        return { ok: false, message: `could not prepare ${host}`, output: prepare.output, phase: 'prepare' };
+        return { ok: false, message: `could not prepare ${host}`, output: prepare.output, phase: 'prepare', waitedMs: 0 };
     }
     const push = await runProcess([
         'git',
@@ -131,35 +44,84 @@ export async function runRemotely(options) {
         `${snapshot.sha}:${SNAPSHOT_REF}`,
     ], { cwd: snapshot.toplevel, env: { ...env, GIT_SSH_COMMAND: ['ssh', ...SSH_OPTIONS].join(' ') } });
     if (push.exitCode !== 0) {
-        return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push' };
-    }
-    const checkout = await runSsh(host, `cd ${checkoutDir} && git checkout --quiet --force --detach ${snapshot.sha} && git clean --force -d --quiet`, env);
-    if (checkout.exitCode !== 0) {
-        return { ok: false, message: `could not check out on ${host}`, output: checkout.output, phase: 'check out' };
-    }
-    const rootDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, monorepoRoot));
-    const install = await runSsh(host, `cd ${rootDir} && CI=true pnpm install --frozen-lockfile`, env);
-    if (install.exitCode !== 0) {
-        const message = install.exitCode === COMMAND_NOT_FOUND_EXIT_CODE
-            ? `could not install on ${host}: pnpm is not on the PATH that the interactive login shell sets there`
-            : `could not install on ${host}`;
-        return { ok: false, message, output: install.output, phase: 'install' };
-    }
-    const runDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, cwd));
-    const statusPath = `${checkoutDir}/.git/${quoteForShell(RUN_STATUS_FILE)}`;
-    const run = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(composeRunScript({ nmrArgs, remoteEnv, runDir, statusPath }))], {
+        return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push', waitedMs: 0 };
+    }
+    const nonce = randomUUID();
+    const marker = `__NMR_DELEGATE_${nonce}__`;
+    const statusFile = `.git/nmr-run-status-${nonce}`;
+    const passes = [];
+    let waitStartedAtMs;
+    let waitedMs = 0;
+    let failure;
+    const demultiplexer = createSessionDemultiplexer({
+        marker,
+        onRecord(record) {
+            if (record.kind === 'waiting') {
+                waitStartedAtMs ??= Date.now();
+                stderr.write(`${formatDelegationWaitingLine(record.holder, host)}\n`);
+            }
+            else if (record.kind === 'locked' && waitStartedAtMs !== undefined) {
+                waitedMs = Date.now() - waitStartedAtMs;
+            }
+            else if (record.kind === 'failed') {
+                failure = record;
+            }
+            else if (record.kind === 'passes') {
+                passes.push(...record.entries);
+            }
+        },
+        onMalformedRecord() {
+            writeDebugNote(`discarded a malformed pass manifest from ${host}`, env, stderr);
+        },
+        stderr,
+    });
+    const script = composeSessionScript({
+        checkoutDir,
+        params: {
+            holder: { command, dir: cwd, pid: process.pid },
+            lockPath: CHECKOUT_LOCK_PATH,
+            marker,
+            nmrArgs,
+            passManifestDir: `.git/nmr-passes-${nonce}`,
+            passManifestEnvVar: PASS_MANIFEST_DIR_ENV_VAR,
+            remoteEnv,
+            rootDir: toRemoteRelativeDir(path.relative(snapshot.toplevel, monorepoRoot)),
+            runDir: toRemoteRelativeDir(path.relative(snapshot.toplevel, cwd)),
+            sha: snapshot.sha,
+            staleAfterMs: STALE_AFTER_MS,
+            statusFile,
+        },
+    });
+    const session = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], {
         env,
         isStreaming: true,
-        stderr,
+        stderr: demultiplexer.stream,
         stdout,
     });
-    if (run.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
-        const recorded = await runSsh(host, `cat ${statusPath}`, env);
+    demultiplexer.flush();
+    if (failure !== undefined) {
+        const output = [demultiplexer.readOutput(), failure.output].filter((text) => text !== '').join('\n');
+        return { ok: false, message: describeFailedPhase(failure, host), output, phase: failure.phase, waitedMs };
+    }
+    if (!demultiplexer.hasStarted()) {
+        return {
+            ok: false,
+            message: describeUnfinishedSession(session.exitCode, host),
+            output: demultiplexer.readOutput(),
+            phase: 'check out',
+            waitedMs,
+        };
+    }
+    if (session.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
+        const recorded = await runSsh(host, `cd ${checkoutDir} && cat ${quoteForShell(statusFile)} && rm -f ${quoteForShell(statusFile)}`, env);
         if (recorded.exitCode !== 0 || recorded.output.trim() !== String(DELEGATION_FAILURE_EXIT_CODE)) {
-            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run' };
+            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run', waitedMs };
         }
     }
-    return { ok: true, exitCode: run.exitCode };
+    return { ok: true, exitCode: session.exitCode, passes, waitedMs };
+}
+export function runSsh(host, script, env, signal) {
+    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env, signal });
 }
 export function wrapRemoteScript(script) {
     return `exec /bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}\n${script}`)}`;
@@ -171,33 +133,23 @@ const LOGIN_PATH_PREAMBLE = [
     'export PATH',
 ].join('; ');
 const RECEIVE_PACK_COMMAND = `/bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}; exec git receive-pack "$1"`)} nmr-receive-pack`;
-const RUN_LAUNCHER_SOURCE = [
-    "const { spawn } = require('node:child_process');",
-    "const { constants } = require('node:os');",
-    'const [file, ...args] = process.argv.slice(1);',
-    "const child = spawn(file, args, { detached: true, stdio: ['ignore', 'inherit', 'inherit'] });",
-    "const stop = () => { try { process.kill(-child.pid, 'SIGTERM'); } catch {} };",
-    "process.stdin.on('end', stop).on('error', stop).resume();",
-    "child.on('error', (error) => { console.error(file + ': ' + error.message); process.exit(127); });",
-    "child.on('close', (code, signal) => process.exit(code ?? 128 + (constants.signals[signal] ?? 0)));",
-].join('\n');
-const RUN_STATUS_FILE = 'nmr-run-status';
 const COMMAND_NOT_FOUND_EXIT_CODE = 127;
 const PHASE_OUTPUT_LIMIT_BYTES = 65_536;
-const NON_DELEGABLE_BASE_COMMANDS = ['build', 'clean', 'compile', 'fix', 'fmt', 'lint', 'test:watch', 'upgrade'];
-const NON_DELEGABLE_COMMANDS = new Set([
-    ...NON_DELEGABLE_BASE_COMMANDS,
-    ...NON_DELEGABLE_BASE_COMMANDS.map((command) => `root:${command}`),
-]);
-const SNAPSHOT_IDENTITY_ENV = {
-    GIT_AUTHOR_DATE: '@0 +0000',
-    GIT_AUTHOR_EMAIL: 'nmr@localhost',
-    GIT_AUTHOR_NAME: 'nmr delegate',
-    GIT_COMMITTER_DATE: '@0 +0000',
-    GIT_COMMITTER_EMAIL: 'nmr@localhost',
-    GIT_COMMITTER_NAME: 'nmr delegate',
-};
 const SNAPSHOT_REF = 'refs/nmr/delegate';
+function describeFailedPhase(failure, host) {
+    if (failure.phase === 'check out') {
+        return `could not check out on ${host}`;
+    }
+    return failure.exitCode === COMMAND_NOT_FOUND_EXIT_CODE
+        ? `could not install on ${host}: pnpm is not on the PATH that the interactive login shell sets there`
+        : `could not install on ${host}`;
+}
+function describeUnfinishedSession(exitCode, host) {
+    if (exitCode === COMMAND_NOT_FOUND_EXIT_CODE) {
+        return `could not check out on ${host}: node is not on the PATH that the interactive login shell sets there`;
+    }
+    return exitCode === DELEGATION_FAILURE_EXIT_CODE ? `lost connection to ${host}` : `could not check out on ${host}`;
+}
 function forwardChunk(chunk, stream, buffer) {
     if (stream === undefined) {
         buffer.append(chunk);
@@ -205,29 +157,15 @@ function forwardChunk(chunk, stream, buffer) {
     }
     stream.write(chunk);
 }
-function joinRemotePath(checkoutDir, relativeDir) {
-    const posixDir = relativeDir.split(path.sep).join('/');
-    return posixDir === '' ? checkoutDir : `${checkoutDir}/${quoteForShell(posixDir)}`;
-}
-function runGit(args, cwd, env) {
-    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT });
-    if (result.error !== undefined) {
-        return { ok: false, error: result.error.message };
-    }
-    if (result.status !== 0) {
-        return { ok: false, error: result.stderr.trim() || `git ${args[0] ?? ''} exited ${result.status ?? 'abnormally'}` };
-    }
-    return { ok: true, stdout: result.stdout };
-}
 function runProcess(argv, options) {
-    const { cwd, env, isStreaming = false, stderr, stdout } = options;
+    const { cwd, env, isStreaming = false, signal, stderr, stdout } = options;
     const [file = '', ...args] = argv;
     const buffer = createBoundedBuffer({
         headLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
         tailLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
     });
     return new Promise((resolve) => {
-        const child = spawn(file, args, { cwd, env, stdio: [isStreaming ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+        const child = spawn(file, args, { cwd, env, signal, stdio: [isStreaming ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
         child.stdout?.on('data', (chunk) => {
             forwardChunk(chunk, isStreaming ? stdout : undefined, buffer);
         });
@@ -246,6 +184,6 @@ function runProcess(argv, options) {
         });
     });
 }
-function runSsh(host, script, env) {
-    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env });
+function toRemoteRelativeDir(relativeDir) {
+    return relativeDir === '' ? '.' : relativeDir.split(path.sep).join('/');
 }

package/dist/esm/remote-session.d.ts

@@ -0,0 +1,40 @@
+import { Writable } from 'node:stream';
+import { type DelegationHolder, type HostSessionParams, type SessionRecord } from './remote-host-session.js';
+/**
+ * Reads a host session's stderr: its records until the run starts, then the run's own output, and the session's
+ * report of the passes that the run recorded once it has ended.
+ */
+export interface SessionDemultiplexer {
+    /** Forwards what the stream held back as the possible start of a record, once the session has ended. */
+    flush: () => void;
+    /** Whether the session reported that the run started. */
+    hasStarted: () => boolean;
+    /** Returns what the session printed before the run started, other than its records. */
+    readOutput: () => string;
+    stream: Writable;
+}
+/**
+ * Composes the script that runs the host session from the checkout. `checkoutDir` is a shell expression, so that it
+ * can name the host's home directory.
+ */
+export declare function composeSessionScript(options: {
+    checkoutDir: string;
+    params: HostSessionParams;
+}): string;
+/**
+ * Returns a demultiplexer that passes each of the session's records to `onRecord` until the `run` record, keeps the
+ * other text that arrives before it as the session's output, and forwards everything after it to `stderr` as it
+ * arrives, except a `passes` record, which it passes to `onRecord` too. A `passes` record whose entries are not a list
+ * goes to `onMalformedRecord` instead.
+ *
+ * The run's output is forwarded as bytes, so that a character split across chunks arrives unchanged. Only trailing bytes
+ * that may still begin a record are held back, until they turn out not to or the record's newline arrives.
+ */
+export declare function createSessionDemultiplexer(options: {
+    marker: string;
+    onMalformedRecord?: () => void;
+    onRecord: (record: SessionRecord) => void;
+    stderr: Writable;
+}): SessionDemultiplexer;
+/** Renders the line that a delegation prints when it starts waiting for another delegation's checkout. */
+export declare function formatDelegationWaitingLine(holder: DelegationHolder | undefined, host: string): string;