@williamthorsen/nmr 0.47.0 → 0.49.0

package/dist/esm/pass-manifest.d.ts

@@ -0,0 +1,53 @@
+import type { Writable } from 'node:stream';
+import { type ReplayLine } from './check-cache-entries.js';
+import type { CheckCacheConfig } from './types.js';
+/**
+ * One pass that an nmr process on a host recorded or recalled during a delegated run, as the host session returns it
+ * to the delegating machine.
+ */
+export interface PassManifestEntry {
+    command: string;
+    commandString: string;
+    /** How long the pass took when it was earned, which a recall reports as the time that it saved. */
+    durationMs: number;
+    replay?: ReplayLine[];
+    /** The scope's directory, in the form that `formatManifestScope` renders. */
+    scope: string;
+    treeHash: string;
+}
+/** Renders a scope's directory as a manifest entry names it: relative to the root, `.` for the root itself. */
+export declare function formatManifestScope(monorepoRoot: string, anchorDir: string): string;
+/**
+ * Returns the entries of a host's pass manifest that this machine may record, dropping each of the others with a debug
+ * note. The manifest is untrusted, so an entry is kept only when it has the entry's shape, names the monorepo root or
+ * one of its workspace packages by a relative path, names a command that is cacheable here, describes `treeId`, and
+ * replays only excerpts that a pass could have recorded.
+ *
+ * A manifest of more entries than any run produces is rejected whole, so that a hostile one cannot fill the cache.
+ */
+export declare function validatePassManifest(options: {
+    checkCache: CheckCacheConfig | undefined;
+    entries: readonly unknown[];
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+    stderr: Writable;
+    treeId: string;
+    workspacePackageDirs: readonly string[];
+}): PassManifestEntry[];
+/**
+ * Writes one entry into the directory that `NMR_PASS_MANIFEST_DIR` names, and does nothing when it is unset. Each
+ * entry is a file of its own, so that the processes of a fan-out cannot interleave their writes.
+ *
+ * A manifest that cannot be written is not worth failing a green run over: the failure goes to the debug note.
+ */
+export declare function writePassManifestEntry(options: {
+    anchorDir: string;
+    command: string;
+    commandString: string;
+    durationMs: number;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+    replay: ReplayLine[] | undefined;
+    stderr: Writable;
+    treeHash: string;
+}): Promise<void>;

package/dist/esm/pass-manifest.js

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isCacheableCommand, PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
+import { isReplayLine } from "./check-cache-entries.js";
+import { MAX_EXCERPT_BYTES } from "./helpers/deriveExcerpt.js";
+import { isObject } from "./helpers/type-guards.js";
+export function formatManifestScope(monorepoRoot, anchorDir) {
+    const scope = path.relative(monorepoRoot, anchorDir);
+    return scope === '' ? '.' : scope.split(path.sep).join('/');
+}
+export function validatePassManifest(options) {
+    const { entries, env, stderr } = options;
+    if (entries.length > MAX_MANIFEST_ENTRIES) {
+        writeDebugNote(`not learning from a pass manifest of ${entries.length} entries`, env, stderr);
+        return [];
+    }
+    const scopeDirs = new Set([options.monorepoRoot, ...options.workspacePackageDirs].map((dir) => path.resolve(dir)));
+    return entries.filter((entry) => {
+        const reason = findRejection(entry, { ...options, scopeDirs });
+        if (reason !== undefined) {
+            writeDebugNote(`not learning a pass from the manifest: ${reason}`, env, stderr);
+        }
+        return reason === undefined;
+    });
+}
+export async function writePassManifestEntry(options) {
+    const { command, env, stderr } = options;
+    const manifestDir = env[PASS_MANIFEST_DIR_ENV_VAR];
+    if (manifestDir === undefined || manifestDir === '') {
+        return;
+    }
+    const entry = {
+        command,
+        commandString: options.commandString,
+        durationMs: options.durationMs,
+        ...(options.replay !== undefined && options.replay.length > 0 && { replay: options.replay }),
+        scope: formatManifestScope(options.monorepoRoot, options.anchorDir),
+        treeHash: options.treeHash,
+    };
+    try {
+        await writeFile(path.join(manifestDir, `${process.pid}-${randomUUID()}.json`), JSON.stringify(entry), {
+            flag: 'wx',
+        });
+    }
+    catch (error) {
+        writeDebugNote(`could not report ${command} to the delegating machine: ${describeError(error)}`, env, stderr);
+    }
+}
+const MAX_MANIFEST_ENTRIES = 1_000;
+function findRejection(entry, options) {
+    if (!isPassManifestEntry(entry)) {
+        return 'the entry is malformed';
+    }
+    const { command, scope } = entry;
+    if (!isRelativeScope(scope) || !options.scopeDirs.has(path.resolve(options.monorepoRoot, scope))) {
+        return `${command} names a scope outside the workspace (${scope})`;
+    }
+    if (!isCacheableCommand(options.checkCache, command)) {
+        return `${command} is not cacheable here`;
+    }
+    if (entry.treeHash !== options.treeId) {
+        return `${command} passed on another tree`;
+    }
+    if (entry.replay?.some((line) => Buffer.byteLength(line.excerpt) > MAX_EXCERPT_BYTES) === true) {
+        return `${command} replays an excerpt longer than a pass records`;
+    }
+    return undefined;
+}
+function isPassManifestEntry(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['commandString'] === 'string' &&
+        typeof value['durationMs'] === 'number' &&
+        Number.isFinite(value['durationMs']) &&
+        value['durationMs'] >= 0 &&
+        (value['replay'] === undefined || (Array.isArray(value['replay']) && value['replay'].every(isReplayLine))) &&
+        typeof value['scope'] === 'string' &&
+        typeof value['treeHash'] === 'string');
+}
+function isRelativeScope(scope) {
+    if (scope === '.') {
+        return true;
+    }
+    return (!path.posix.isAbsolute(scope) &&
+        scope.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
+}

package/dist/esm/presentation.d.ts

@@ -0,0 +1,47 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
+import { type ReportFormat } from './report-format.js';
+import { type CommandVerbosity, type ResolveVerbosityOptions } from './verbosity.js';
+import { type Verdict } from './verdict.js';
+/**
+ * Reads everything that decides how a run presents itself: the two inherited variables, and the style that each
+ * output stream resolves to. Reports the first value that cannot be read.
+ *
+ * The style is resolved here rather than beside its use, so that a value that does not name a style is rejected
+ * at the same point as an unreadable variable, which is ahead of `--version` and of the config load.
+ */
+export declare function readPresentation(options: {
+    env: NodeJS.ProcessEnv;
+    flagValue: string | undefined;
+    stderrIsTty: boolean;
+    stdoutIsTty: boolean;
+}): PresentationRead;
+/**
+ * Reports an invocation's verdict, unless the levels around it already report for it.
+ *
+ * A hook leaf reports none: it is not a command that anyone asked for, but part of the chain on which the level
+ * that wrapped it reports, and a line here would say the same thing twice under a different name. A delegating
+ * invocation returns before composing a verdict, and every scope to which it fans out reports its own.
+ */
+export declare function reportVerdict(verdict: Verdict, stdout: Writable, format: ReportFormat, style: OutputStyle): void;
+/**
+ * Resolves how loudly this run reports the output of the commands that it runs.
+ *
+ * A machine-readable run reports on stdout and nothing else may, so it withholds that output whatever the
+ * loudness ladder would have resolved to. A failure still prints it on stderr, as under any quiet run. Because the
+ * two leave the child on the same channels, a machine-readable run and a quiet one share a retention key.
+ */
+export declare function resolveReportingVerbosity(options: ResolveVerbosityOptions & {
+    format: ReportFormat;
+}): CommandVerbosity;
+/** What the presentation sources came to, or the message naming why one of them could not be read. */
+type PresentationRead = {
+    ok: true;
+    format: ReportFormat | undefined;
+    styles: StreamStyles;
+    verbosity: CommandVerbosity | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+export {};

package/dist/esm/presentation.js

@@ -0,0 +1,32 @@
+import { describeInvalidOutputStyle } from '@williamthorsen/nmr-core';
+import { isHookName } from "./helpers/hook-name.js";
+import { resolveOutputStyles } from "./output-style.js";
+import { readReportFormatEnv } from "./report-format.js";
+import { readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
+import { writeVerdict } from "./verdict.js";
+export function readPresentation(options) {
+    const { env } = options;
+    const verbosity = readVerbosityEnv(env);
+    if (!verbosity.ok) {
+        return verbosity;
+    }
+    const format = readReportFormatEnv(env);
+    if (!format.ok) {
+        return format;
+    }
+    const { invalid: invalidStyle, styles } = resolveOutputStyles(options);
+    if (invalidStyle !== undefined) {
+        return { ok: false, error: describeInvalidOutputStyle(invalidStyle) };
+    }
+    return { ok: true, format: format.format, styles, verbosity: verbosity.verbosity };
+}
+export function reportVerdict(verdict, stdout, format, style) {
+    if (isHookName(verdict.command)) {
+        return;
+    }
+    writeVerdict(verdict, stdout, format, style);
+}
+export function resolveReportingVerbosity(options) {
+    const { format, ...ladder } = options;
+    return format === 'json' ? 'quiet' : resolveVerbosity(ladder);
+}

package/dist/esm/recording.d.ts

@@ -1,5 +1,5 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-import { type CheckCacheEntry } from './check-cache.js';
+import { type CheckCacheEntry } from './check-cache-entries.js';
 /**
  * What this invocation would be recorded under, insofar as an entry records the same facts. A mismatch is read
  * against these so that a refusal names the ingredient that moved rather than blaming the tree for all of them.

package/dist/esm/recording.js

@@ -1,12 +1,12 @@
 import { formatGlyphLine, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
-import { readCheckCacheEntry, readTranscript } from "./check-cache.js";
+import { readCheckCacheEntry, readTranscript } from "./check-cache-entries.js";
 import { NMR_GLYPHS } from "./glyphs.js";
 import { formatDuration } from "./helpers/duration.js";
 export function renderRecording(options) {
     const { entry } = options.recording;
     const age = formatDuration(Math.max(0, Date.now() - Date.parse(entry.recordedAt)));
     const header = formatGlyphLine(NMR_GLYPHS, options.style, 'recording', `${options.scope}: ${options.command} — recorded ${entry.recordedAt} (${age} ago), ` +
-        `ran in ${formatDuration(entry.durationMs)}`) + `\n$ ${entry.commandString}\n\n`;
+        `ran in ${formatDuration(entry.durationMs)}${entry.host === undefined ? '' : ` on ${entry.host}`}`) + `\n$ ${entry.commandString}\n\n`;
     return `${header}${appendNewline(renderBody(options.recording))}`;
 }
 export function renderRefusal(options) {

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

@@ -0,0 +1,62 @@
+/** The checkout's lock, which a host session holds and the lock probe reads, relative to the checkout. */
+export declare const CHECKOUT_LOCK_PATH = ".git/nmr-delegate.lock";
+/** The local delegation on whose behalf a host session runs, as a waiting session names it. */
+export interface DelegationHolder {
+    command: string;
+    dir: string;
+    pid: number;
+}
+/** What the host session needs, sent to it as JSON. Every directory is relative to the checkout. */
+export interface HostSessionParams {
+    holder: DelegationHolder;
+    lockPath: string;
+    /** Begins each record line on stderr; it contains a per-delegation nonce, so that a command cannot forge one. */
+    marker: string;
+    nmrArgs: readonly string[];
+    /** The directory, created for this delegation, into which every nmr process of the run reports its passes. */
+    passManifestDir: string;
+    /** The variable that names the pass-manifest directory to nmr. */
+    passManifestEnvVar: string;
+    remoteEnv: Readonly<Record<string, string>>;
+    rootDir: string;
+    runDir: string;
+    sha: string;
+    /** Age at which an unrefreshed lock file is abandoned. */
+    staleAfterMs: number;
+    /** Where the session records nmr's status when it is 255, so that it can be told apart from a dropped connection. */
+    statusFile: string;
+}
+/** A phase of the host session that can fail before the run starts. */
+export type SessionPhase = 'check out' | 'install';
+/**
+ * A line in which the host session reports to the local side: its progress before the run starts, and the passes that
+ * the run reported once it has ended.
+ */
+export type SessionRecord = {
+    kind: 'failed';
+    exitCode: number;
+    output: string;
+    phase: SessionPhase;
+} | {
+    kind: 'locked';
+} | {
+    kind: 'passes';
+    entries: unknown[];
+} | {
+    kind: 'run';
+} | {
+    kind: 'waiting';
+    holder: DelegationHolder | undefined;
+};
+/**
+ * Runs on the host, from the checkout, as the whole of a delegation after the push: takes the checkout's lock, checks
+ * out the snapshot, installs, runs nmr, and reports the passes that nmr wrote to the pass manifest. It is sent as
+ * source, so it refers to nothing outside its own body.
+ *
+ * The lock follows the machine lock's rules: A waiter reclaims it at once when the holder's pid is gone, and once the
+ * holder has stopped refreshing it for a minute otherwise. When the session's stdin ends, which the local `ssh` causes
+ * by exiting, the session stops its current phase's process group, releases the lock, and exits.
+ *
+ * @internal
+ */
+export declare function runHostSession(params: HostSessionParams): void;

package/dist/esm/remote-host-session.js

@@ -0,0 +1,277 @@
+export const CHECKOUT_LOCK_PATH = '.git/nmr-delegate.lock';
+export function runHostSession(params) {
+    const fs = process.getBuiltinModule('node:fs');
+    const childProcess = process.getBuiltinModule('node:child_process');
+    const crypto = process.getBuiltinModule('node:crypto');
+    const os = process.getBuiltinModule('node:os');
+    const path = process.getBuiltinModule('node:path');
+    const LOCK_PATH = params.lockPath;
+    const RECLAIM_GUARD_PATH = `${params.lockPath}.reclaim`;
+    const HEARTBEAT_INTERVAL_MS = 10_000;
+    const POLL_INTERVAL_MS = 1_000;
+    const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
+    const OUTPUT_LIMIT_BYTES = 65_536;
+    const COMMAND_NOT_FOUND_EXIT_CODE = 127;
+    const DELEGATION_FAILURE_EXIT_CODE = 255;
+    const STOP_GRACE_MS = 5_000;
+    const token = crypto.randomUUID();
+    let isHolding = false;
+    let activeChild;
+    let isStopping = false;
+    process.on('exit', releaseLock);
+    process.stdin.on('end', stop).on('error', stop).resume();
+    void main();
+    async function main() {
+        await acquireLock();
+        emit({ kind: 'locked' });
+        for (const args of [
+            ['checkout', '--quiet', '--force', '--detach', params.sha],
+            ['clean', '--force', '-d', '--quiet'],
+        ]) {
+            const result = await runPhase('git', args, '.', process.env);
+            if (isStopping)
+                return;
+            if (result.exitCode !== 0) {
+                fail('check out', result);
+                return;
+            }
+        }
+        const install = await runPhase('pnpm', ['install', '--frozen-lockfile'], params.rootDir, {
+            ...process.env,
+            CI: 'true',
+        });
+        if (isStopping)
+            return;
+        if (install.exitCode !== 0) {
+            fail('install', install);
+            return;
+        }
+        emit({ kind: 'run' });
+        fs.mkdirSync(params.runDir, { recursive: true });
+        fs.mkdirSync(params.passManifestDir, { recursive: true });
+        process.on('exit', () => fs.rmSync(params.passManifestDir, { force: true, recursive: true }));
+        const manifestEnv = { [params.passManifestEnvVar]: path.resolve(process.cwd(), params.passManifestDir) };
+        const child = childProcess.spawn('pnpm', ['exec', 'nmr', '--no-delegate', ...params.nmrArgs], {
+            cwd: params.runDir,
+            detached: true,
+            env: { ...process.env, ...params.remoteEnv, ...manifestEnv },
+            stdio: ['ignore', 'inherit', 'inherit'],
+        });
+        activeChild = child;
+        child.on('error', (error) => {
+            process.stderr.write(`pnpm: ${error.message}\n`, () => {
+                process.exit(COMMAND_NOT_FOUND_EXIT_CODE);
+            });
+        });
+        child.on('close', (code, signal) => {
+            const status = code ?? 128 + (signal === null ? 0 : os.constants.signals[signal]);
+            if (status === DELEGATION_FAILURE_EXIT_CODE) {
+                fs.writeFileSync(params.statusFile, `${status}\n`);
+            }
+            emit({ kind: 'passes', entries: readPassManifest() }, () => {
+                process.exit(status);
+            });
+        });
+    }
+    async function acquireLock() {
+        const record = {
+            command: params.holder.command,
+            dir: params.holder.dir,
+            localPid: params.holder.pid,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            token,
+        };
+        let reportedToken;
+        for (;;) {
+            try {
+                fs.writeFileSync(LOCK_PATH, JSON.stringify(record), { flag: 'wx' });
+                isHolding = true;
+                setInterval(refreshLock, HEARTBEAT_INTERVAL_MS).unref();
+                return;
+            }
+            catch (error) {
+                if (readErrorCode(error) !== 'EEXIST')
+                    throw error;
+            }
+            const state = readLockState();
+            if (state === undefined)
+                continue;
+            if (isStale(state)) {
+                reclaimStaleLock(state);
+                continue;
+            }
+            const holderToken = state.holder?.token ?? 'unreadable';
+            if (holderToken !== reportedToken) {
+                const holder = state.holder;
+                emit({
+                    kind: 'waiting',
+                    holder: holder === undefined ? undefined : { command: holder.command, dir: holder.dir, pid: holder.localPid },
+                });
+                reportedToken = holderToken;
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+    }
+    function emit(record, onWritten) {
+        process.stderr.write(`${params.marker} ${JSON.stringify(record)}\n`, onWritten);
+    }
+    function fail(phase, result) {
+        emit({ kind: 'failed', exitCode: result.exitCode, output: result.output, phase }, () => {
+            process.exit(1);
+        });
+    }
+    function isLockFile(value) {
+        if (typeof value !== 'object' || value === null)
+            return false;
+        const fields = { ...value };
+        return (typeof fields['command'] === 'string' &&
+            typeof fields['dir'] === 'string' &&
+            typeof fields['localPid'] === 'number' &&
+            typeof fields['pid'] === 'number' &&
+            typeof fields['startedAt'] === 'string' &&
+            typeof fields['token'] === 'string');
+    }
+    function isProcessGone(pid) {
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return readErrorCode(error) === 'ESRCH';
+        }
+    }
+    function isStale(state) {
+        if (Date.now() - state.mtimeMs > params.staleAfterMs)
+            return true;
+        return state.holder !== undefined && isProcessGone(state.holder.pid);
+    }
+    function readErrorCode(error) {
+        return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+    }
+    function readLockState() {
+        try {
+            const content = fs.readFileSync(LOCK_PATH, 'utf8');
+            const { mtimeMs } = fs.statSync(LOCK_PATH);
+            let holder;
+            try {
+                const value = JSON.parse(content);
+                holder = isLockFile(value) ? value : undefined;
+            }
+            catch {
+                holder = undefined;
+            }
+            return { holder, mtimeMs };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function reclaimStaleLock(observed) {
+        try {
+            fs.mkdirSync(RECLAIM_GUARD_PATH);
+        }
+        catch {
+            try {
+                if (Date.now() - fs.statSync(RECLAIM_GUARD_PATH).mtimeMs > RECLAIM_GUARD_STALE_AFTER_MS) {
+                    fs.rmSync(RECLAIM_GUARD_PATH, { force: true, recursive: true });
+                }
+            }
+            catch {
+            }
+            return;
+        }
+        try {
+            const current = readLockState();
+            if (current !== undefined && current.holder?.token === observed.holder?.token && isStale(current)) {
+                fs.rmSync(LOCK_PATH, { force: true });
+            }
+        }
+        finally {
+            fs.rmSync(RECLAIM_GUARD_PATH, { force: true, recursive: true });
+        }
+    }
+    function refreshLock() {
+        const now = new Date();
+        try {
+            fs.utimesSync(LOCK_PATH, now, now);
+        }
+        catch {
+        }
+    }
+    function readPassManifest() {
+        const names = fs.existsSync(params.passManifestDir) ? fs.readdirSync(params.passManifestDir) : [];
+        return names.flatMap((name) => {
+            try {
+                return [JSON.parse(fs.readFileSync(path.join(params.passManifestDir, name), 'utf8'))];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    function releaseLock() {
+        if (!isHolding)
+            return;
+        isHolding = false;
+        if (readLockState()?.holder?.token === token) {
+            fs.rmSync(LOCK_PATH, { force: true });
+        }
+    }
+    function runPhase(file, args, cwd, env) {
+        const head = [];
+        const tail = [];
+        let headBytes = 0;
+        let tailBytes = 0;
+        let droppedBytes = 0;
+        return new Promise((resolve) => {
+            const child = childProcess.spawn(file, args, { cwd, detached: true, env, stdio: ['ignore', 'pipe', 'pipe'] });
+            activeChild = child;
+            child.stdout.on('data', capture);
+            child.stderr.on('data', capture);
+            child.on('error', (error) => {
+                activeChild = undefined;
+                resolve({ exitCode: COMMAND_NOT_FOUND_EXIT_CODE, output: `${file}: ${error.message}` });
+            });
+            child.on('close', (code, signal) => {
+                activeChild = undefined;
+                resolve({ exitCode: code ?? 128 + (signal === null ? 0 : os.constants.signals[signal]), output: readOutput() });
+            });
+        });
+        function capture(chunk) {
+            const headPart = chunk.subarray(0, Math.max(0, OUTPUT_LIMIT_BYTES - headBytes));
+            head.push(headPart);
+            headBytes += headPart.length;
+            const rest = chunk.subarray(headPart.length);
+            tail.push(rest);
+            tailBytes += rest.length;
+            while (tailBytes > OUTPUT_LIMIT_BYTES) {
+                const first = tail.shift() ?? Buffer.alloc(0);
+                const dropped = Math.min(tailBytes - OUTPUT_LIMIT_BYTES, first.length);
+                if (dropped < first.length)
+                    tail.unshift(first.subarray(dropped));
+                tailBytes -= dropped;
+                droppedBytes += dropped;
+            }
+        }
+        function readOutput() {
+            const marker = droppedBytes > 0 ? [Buffer.from(`\n[… ${droppedBytes} bytes omitted …]\n`)] : [];
+            return Buffer.concat([...head, ...marker, ...tail]).toString('utf8');
+        }
+    }
+    function stop() {
+        isStopping = true;
+        const child = activeChild;
+        const pid = child?.pid;
+        if (child === undefined || pid === undefined) {
+            process.exit(DELEGATION_FAILURE_EXIT_CODE);
+        }
+        child.on('close', () => process.exit(DELEGATION_FAILURE_EXIT_CODE));
+        setTimeout(() => process.exit(DELEGATION_FAILURE_EXIT_CODE), STOP_GRACE_MS);
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+/** What the host probe needs, sent to it as JSON. */
+export interface HostProbeParams {
+    /** The checkout's lock file, relative to the host's home directory. */
+    checkoutLockPath: string;
+    /** The variable that overrides the machine lock's directory. */
+    lockDirEnvVar: string;
+    /** The machine lock's file name in its directory. */
+    machineLockFile: string;
+    /** Age at which an unrefreshed lock file is abandoned. */
+    staleAfterMs: number;
+}
+/**
+ * Runs on the host and prints, as one JSON line, whether a delegation started now would wait: whether the machine
+ * lock or the checkout's lock has a live holder. It applies the locks' own staleness rules and changes nothing. It is
+ * sent as source, so it refers to nothing outside its own body.
+ *
+ * The machine lock's directory is resolved as the host's nmr resolves it, from the environment that `ssh` gives the
+ * session.
+ *
+ * @internal
+ */
+export declare function probeHostLocks(params: HostProbeParams): void;

package/dist/esm/remote-probe-host.js

@@ -0,0 +1,50 @@
+export function probeHostLocks(params) {
+    const fs = process.getBuiltinModule('node:fs');
+    const os = process.getBuiltinModule('node:os');
+    const path = process.getBuiltinModule('node:path');
+    const lockDir = resolveLockDir();
+    const lockPaths = [path.join(lockDir, params.machineLockFile), path.join(os.homedir(), params.checkoutLockPath)];
+    process.stdout.write(`${JSON.stringify({ busy: lockPaths.some(isHeld) })}\n`);
+    function isHeld(lockPath) {
+        let content;
+        let mtimeMs;
+        try {
+            content = fs.readFileSync(lockPath, 'utf8');
+            ({ mtimeMs } = fs.statSync(lockPath));
+        }
+        catch {
+            return false;
+        }
+        if (Date.now() - mtimeMs > params.staleAfterMs)
+            return false;
+        const pid = readHolderPid(content);
+        return pid === undefined || !isProcessGone(pid);
+    }
+    function isProcessGone(pid) {
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH';
+        }
+    }
+    function readHolderPid(content) {
+        try {
+            const value = JSON.parse(content);
+            if (typeof value !== 'object' || value === null || !('pid' in value))
+                return undefined;
+            return typeof value.pid === 'number' ? value.pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function resolveLockDir() {
+        const override = process.env[params.lockDirEnvVar];
+        if (override !== undefined && override !== '')
+            return override;
+        const uid = process.getuid?.();
+        return uid === undefined ? path.join(os.tmpdir(), 'nmr') : `/tmp/nmr-${uid}`;
+    }
+}