charness 3.7.0 → 3.9.0

package/dist/runnerUtility/toolInstall.d.ts

@@ -0,0 +1,95 @@
+import { type CommandRunner } from '../selfUpdate/commandRunner';
+import type { RunnerHomePaths } from './runnerHome';
+/**
+ * @description The two tools phase 1 needs on a runner besides Node, `ssh` and `tar`.
+ *
+ * PUEUE is installed by the utility from the pinned release binaries of Nukesor/pueue, each checked against a sha256 written here
+ * (a download that does not match is thrown away — nothing is ever executed unchecked). The hashes were taken from the release assets
+ * of v4.0.4 on 2026-11-01. They go into `~/.charness-runner/bin/`, no admin needed.
+ *
+ * RSYNC ≥ 3.1 is FOUND (PATH, Homebrew, /usr/local, /usr/bin). macOS 15.4 and later ship `openrsync`, which lacks the options phase 1
+ * uses (`--copy-dest`, `--modify-window=-1`), so it does not count. Without a usable one, rsync 3.4.1 is BUILT from its pinned source
+ * with the machine's C compiler (Xcode's command line tools on a Mac); without a compiler the check names the one command to run.
+ */
+export declare const pueueVersion = "4.0.4";
+export declare const rsyncVersion = "3.4.1";
+export interface PueueAsset {
+    pueueUrl: string;
+    pueueSha256: string;
+    pueuedUrl: string;
+    pueuedSha256: string;
+}
+/** The pinned binaries by `${process.platform}-${process.arch}`. */
+export declare const pueueAssets: Readonly<Record<string, PueueAsset>>;
+export declare function getPueueAsset(platform: NodeJS.Platform, arch: string, table?: Readonly<Record<string, PueueAsset>>): PueueAsset | undefined;
+export type FetchFunction = (url: string, init: {
+    signal: AbortSignal;
+    redirect: 'follow';
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+}>;
+/**
+ * @description Download `url` to `destinationPath` (mode 755) only if its sha256 is `expectedSha256`: the bytes are checked in memory
+ * first, so a wrong file never exists on disk under the final name.
+ */
+export declare function downloadVerified(url: string, expectedSha256: string, destinationPath: string, fetchImpl?: FetchFunction): Promise<void>;
+/** @description The first `x.y.z` in a tool's `--version` output, or `null`. */
+export declare function parseToolVersion(output: string): string | null;
+export interface RsyncInfo {
+    /** `openrsync` is Apple's reimplementation; it lacks what phase 1 needs. */
+    flavor: 'rsync' | 'openrsync';
+    version: string | null;
+}
+export declare function parseRsyncVersion(output: string): RsyncInfo | null;
+export declare function checkIsRsyncUsable(info: RsyncInfo): boolean;
+export interface ToolFound {
+    path: string;
+    version: string;
+}
+export interface ToolDeps {
+    runner: CommandRunner;
+    platform: NodeJS.Platform;
+    arch: string;
+    environment: NodeJS.ProcessEnv;
+    fetchImpl: FetchFunction;
+    /** The pinned binaries to choose from; a test supplies its own. */
+    pueueAssetTable: Readonly<Record<string, PueueAsset>>;
+    checkExists: (candidate: string) => boolean;
+    cpuCount: number;
+}
+export declare function createToolDeps(): ToolDeps;
+/** @description A usable rsync from PATH, Homebrew or the system folders, with the one `<root>/bin/rsync` (built earlier) first. */
+export declare function findRsync(paths: RunnerHomePaths, deps: ToolDeps): Promise<ToolFound | null>;
+/** @description Our pueue in `<root>/bin`, when it is there and runs. */
+export declare function findPueue(paths: RunnerHomePaths, deps: ToolDeps): Promise<ToolFound | null>;
+export type ToolInstallOutcome = {
+    ok: true;
+    tool: ToolFound;
+    wasInstalled: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** @description Make sure `<root>/bin/pueue` and `pueued` are there (downloaded and verified when not). */
+export declare function ensurePueue(paths: RunnerHomePaths, deps: ToolDeps): Promise<ToolInstallOutcome>;
+/** @description The one thing to tell the operator when rsync cannot be built here. */
+export declare function describeRsyncRemedy(platform: NodeJS.Platform): string;
+/** @description The build steps of rsync, in order (pure, so a test can read them). */
+export declare function planRsyncBuild(paths: RunnerHomePaths, cpuCount: number): Array<{
+    file: string;
+    args: string[];
+    cwd: string;
+}>;
+/** @description Build rsync from the pinned source and link it as `<root>/bin/rsync`. */
+export declare function buildRsync(paths: RunnerHomePaths, deps: ToolDeps): Promise<ToolInstallOutcome>;
+/**
+ * @description Make `<root>/bin/<name>` the tool at `targetPath`. Jobs get `~/.charness-runner/bin` FIRST on their PATH, so what is linked
+ * there is what every job (and phase 1's runner script) runs — discovery that only looked at the caller's PATH would report a tool that
+ * the jobs never see.
+ */
+export declare function linkToolIntoBin(paths: RunnerHomePaths, name: string, targetPath: string): void;
+/** @description rsync: the usable one that is there — linked into the runner's bin folder so jobs run exactly that one — else a built one. */
+export declare function ensureRsync(paths: RunnerHomePaths, deps: ToolDeps): Promise<ToolInstallOutcome>;
+//# sourceMappingURL=toolInstall.d.ts.map

package/dist/runnerUtility/toolInstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolInstall.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/toolInstall.ts"],"names":[],"mappings":"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"}

package/dist/runnerUtility/toolInstall.js

@@ -0,0 +1,232 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pueueAssets = exports.rsyncVersion = exports.pueueVersion = void 0;
+exports.getPueueAsset = getPueueAsset;
+exports.downloadVerified = downloadVerified;
+exports.parseToolVersion = parseToolVersion;
+exports.parseRsyncVersion = parseRsyncVersion;
+exports.checkIsRsyncUsable = checkIsRsyncUsable;
+exports.createToolDeps = createToolDeps;
+exports.findRsync = findRsync;
+exports.findPueue = findPueue;
+exports.ensurePueue = ensurePueue;
+exports.describeRsyncRemedy = describeRsyncRemedy;
+exports.planRsyncBuild = planRsyncBuild;
+exports.buildRsync = buildRsync;
+exports.linkToolIntoBin = linkToolIntoBin;
+exports.ensureRsync = ensureRsync;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const commandRunner_1 = require("../selfUpdate/commandRunner");
+/**
+ * @description The two tools phase 1 needs on a runner besides Node, `ssh` and `tar`.
+ *
+ * PUEUE is installed by the utility from the pinned release binaries of Nukesor/pueue, each checked against a sha256 written here
+ * (a download that does not match is thrown away — nothing is ever executed unchecked). The hashes were taken from the release assets
+ * of v4.0.4 on 2026-11-01. They go into `~/.charness-runner/bin/`, no admin needed.
+ *
+ * RSYNC ≥ 3.1 is FOUND (PATH, Homebrew, /usr/local, /usr/bin). macOS 15.4 and later ship `openrsync`, which lacks the options phase 1
+ * uses (`--copy-dest`, `--modify-window=-1`), so it does not count. Without a usable one, rsync 3.4.1 is BUILT from its pinned source
+ * with the machine's C compiler (Xcode's command line tools on a Mac); without a compiler the check names the one command to run.
+ */
+exports.pueueVersion = '4.0.4';
+exports.rsyncVersion = '3.4.1';
+const pueueBaseUrl = `https://github.com/Nukesor/pueue/releases/download/v${exports.pueueVersion}`;
+const rsyncSourceUrl = `https://download.samba.org/pub/rsync/src/rsync-${exports.rsyncVersion}.tar.gz`;
+const rsyncSourceSha256 = '2924bcb3a1ed8b551fc101f740b9f0fe0a202b115027647cf69850d65fd88c52';
+const downloadTimeoutMs = 3 * 60 * 1000;
+const maxDownloadBytes = 64 * 1024 * 1024;
+const versionProbeTimeoutMs = 4000;
+const buildStepTimeoutMs = 15 * 60 * 1000;
+const executableMode = 0o755;
+const minRsync = { major: 3, minor: 1 };
+const extraRsyncDirs = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'];
+function createPueueAsset(target, pueueSha256, pueuedSha256) {
+    return { pueueUrl: `${pueueBaseUrl}/pueue-${target}`, pueueSha256, pueuedUrl: `${pueueBaseUrl}/pueued-${target}`, pueuedSha256 };
+}
+/** The pinned binaries by `${process.platform}-${process.arch}`. */
+exports.pueueAssets = {
+    'linux-x64': createPueueAsset('x86_64-unknown-linux-musl', 'c1b10d7e4e62211075ddd0e1dc3e8cbfc5a43d662cb3be7402a28504e23fcb51', '5afeff6adbafb909e8d54e2caff158e6966c2adffa2c09e60fd631cc51b60390'),
+    'linux-arm64': createPueueAsset('aarch64-unknown-linux-musl', '759bf5100a51024997111c6913aaf3330a0cdfd893ff552dcf429ae9b5e01e09', '332c5ef74270b64aeaf04894c8c04826f3422eb7d50dbd1a8e0706d74a42f653'),
+    'darwin-x64': createPueueAsset('x86_64-apple-darwin', 'c5b89a2f9f9d355b33880735a1f12a8b8d09002f95cc7d2e5f3294e313fb8540', '4de7c4790989198007c6c0789c56606237d0456a2ce3666b5a0b198478c06263'),
+    'darwin-arm64': createPueueAsset('aarch64-apple-darwin', '7780dbd21e3a4106e88a57396d6dc2dbcbbae253c7e00d92d994902896b8cb82', 'bf5a1151d70c328dd036fb6d786fba53a68d8574c12391d04db3d08b04079205'),
+};
+function getPueueAsset(platform, arch, table = exports.pueueAssets) {
+    return table[`${platform}-${arch}`];
+}
+/**
+ * @description Download `url` to `destinationPath` (mode 755) only if its sha256 is `expectedSha256`: the bytes are checked in memory
+ * first, so a wrong file never exists on disk under the final name.
+ */
+async function downloadVerified(url, expectedSha256, destinationPath, fetchImpl = fetch) {
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(downloadTimeoutMs), redirect: 'follow' });
+    if (!response.ok)
+        throw new Error(`download failed (HTTP ${response.status}): ${url}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > maxDownloadBytes)
+        throw new Error(`download is larger than expected: ${url}`);
+    const actualSha256 = (0, crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    if (actualSha256 !== expectedSha256)
+        throw new Error(`checksum mismatch for ${url}: expected ${expectedSha256.slice(0, 12)}…, got ${actualSha256.slice(0, 12)}…`);
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${destinationPath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryPath, bytes, { mode: executableMode });
+    fs.renameSync(temporaryPath, destinationPath);
+}
+/** @description The first `x.y.z` in a tool's `--version` output, or `null`. */
+function parseToolVersion(output) {
+    return /(\d+\.\d+(?:\.\d+)?)/.exec(output)?.[1] ?? null;
+}
+function parseRsyncVersion(output) {
+    if (/openrsync/i.test(output))
+        return { flavor: 'openrsync', version: null };
+    const match = /rsync\s+version\s+v?(\d+\.\d+(?:\.\d+)?)/i.exec(output);
+    return match === null ? null : { flavor: 'rsync', version: match[1] };
+}
+function checkIsRsyncUsable(info) {
+    if (info.flavor !== 'rsync' || info.version === null)
+        return false;
+    const [major, minor] = info.version.split('.').map(Number);
+    return major > minRsync.major || (major === minRsync.major && minor >= minRsync.minor);
+}
+function createToolDeps() {
+    return { runner: commandRunner_1.runCommand, platform: process.platform, arch: process.arch, environment: process.env, fetchImpl: fetch, pueueAssetTable: exports.pueueAssets, checkExists: fs.existsSync, cpuCount: os.cpus().length };
+}
+/** @description A usable rsync from PATH, Homebrew or the system folders, with the one `<root>/bin/rsync` (built earlier) first. */
+async function findRsync(paths, deps) {
+    const pathDirs = (deps.environment.PATH ?? '').split(path.delimiter).filter((dir) => dir !== '');
+    const candidates = [...new Set([paths.binDir, ...pathDirs, ...extraRsyncDirs])].map((dir) => path.join(dir, 'rsync')).filter(deps.checkExists);
+    for (const candidate of candidates) {
+        const result = await deps.runner(candidate, ['--version'], { timeoutMs: versionProbeTimeoutMs });
+        const info = result.ok ? parseRsyncVersion(result.stdout) : null;
+        if (info !== null && checkIsRsyncUsable(info) && info.version !== null)
+            return { path: candidate, version: info.version };
+    }
+    return null;
+}
+/** @description Our pueue in `<root>/bin`, when it is there and runs. */
+async function findPueue(paths, deps) {
+    const candidate = path.join(paths.binDir, 'pueue');
+    if (!deps.checkExists(candidate))
+        return null;
+    const result = await deps.runner(candidate, ['--version'], { timeoutMs: versionProbeTimeoutMs });
+    const version = result.ok ? parseToolVersion(result.stdout) : null;
+    return version === null ? null : { path: candidate, version };
+}
+/** @description Make sure `<root>/bin/pueue` and `pueued` are there (downloaded and verified when not). */
+async function ensurePueue(paths, deps) {
+    const existing = await findPueue(paths, deps);
+    if (existing !== null && deps.checkExists(path.join(paths.binDir, 'pueued')))
+        return { ok: true, tool: existing, wasInstalled: false };
+    const asset = getPueueAsset(deps.platform, deps.arch, deps.pueueAssetTable);
+    if (asset === undefined)
+        return { ok: false, reason: `no pinned Pueue binary for ${deps.platform}/${deps.arch}; install Pueue ${exports.pueueVersion} by hand into ${paths.binDir}` };
+    try {
+        await downloadVerified(asset.pueueUrl, asset.pueueSha256, path.join(paths.binDir, 'pueue'), deps.fetchImpl);
+        await downloadVerified(asset.pueuedUrl, asset.pueuedSha256, path.join(paths.binDir, 'pueued'), deps.fetchImpl);
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : 'the Pueue download failed' };
+    }
+    const installed = await findPueue(paths, deps);
+    return installed === null ? { ok: false, reason: 'the downloaded pueue does not run on this machine' } : { ok: true, tool: installed, wasInstalled: true };
+}
+/** @description The one thing to tell the operator when rsync cannot be built here. */
+function describeRsyncRemedy(platform) {
+    return platform === 'darwin'
+        ? 'rsync 3.1 or newer is missing (macOS\'s own is openrsync). Install the compiler tools with `xcode-select --install` and run `charness-runner check` again, or `brew install rsync`.'
+        : 'rsync 3.1 or newer is missing. Install it with your package manager (for example `sudo apt install rsync`) and run `charness-runner check` again.';
+}
+/** @description The build steps of rsync, in order (pure, so a test can read them). */
+function planRsyncBuild(paths, cpuCount) {
+    const sourceDir = path.join(paths.buildDir, `rsync-${exports.rsyncVersion}`);
+    const prefix = path.join(paths.root, 'rsync');
+    return [
+        { file: 'tar', args: ['-xzf', path.join(paths.buildDir, `rsync-${exports.rsyncVersion}.tar.gz`), '-C', paths.buildDir], cwd: paths.buildDir },
+        { file: './configure', args: [`--prefix=${prefix}`, '--disable-md2man', '--disable-xxhash', '--disable-zstd', '--disable-lz4', '--disable-openssl', '--with-included-popt', '--with-included-zlib'], cwd: sourceDir },
+        { file: 'make', args: [`-j${Math.max(1, cpuCount)}`], cwd: sourceDir },
+        { file: 'make', args: ['install'], cwd: sourceDir },
+    ];
+}
+/** @description Build rsync from the pinned source and link it as `<root>/bin/rsync`. */
+async function buildRsync(paths, deps) {
+    const compiler = await deps.runner('cc', ['--version'], { timeoutMs: versionProbeTimeoutMs });
+    const make = await deps.runner('make', ['--version'], { timeoutMs: versionProbeTimeoutMs });
+    if (!compiler.ok || !make.ok)
+        return { ok: false, reason: describeRsyncRemedy(deps.platform) };
+    fs.mkdirSync(paths.buildDir, { recursive: true, mode: 0o700 });
+    try {
+        await downloadVerified(rsyncSourceUrl, rsyncSourceSha256, path.join(paths.buildDir, `rsync-${exports.rsyncVersion}.tar.gz`), deps.fetchImpl);
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : 'the rsync download failed' };
+    }
+    for (const step of planRsyncBuild(paths, deps.cpuCount)) {
+        const result = await deps.runner(step.file, step.args, { cwd: step.cwd, timeoutMs: buildStepTimeoutMs });
+        if (!result.ok)
+            return { ok: false, reason: `building rsync failed at «${step.file} ${step.args[0] ?? ''}»: ${result.stderr.trim().split('\n').slice(-2).join(' | ')}` };
+    }
+    const built = path.join(paths.root, 'rsync', 'bin', 'rsync');
+    fs.mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+    fs.rmSync(path.join(paths.binDir, 'rsync'), { force: true });
+    fs.symlinkSync(built, path.join(paths.binDir, 'rsync'));
+    const found = await findRsync(paths, deps);
+    return found === null ? { ok: false, reason: 'the rsync that was built does not run' } : { ok: true, tool: found, wasInstalled: true };
+}
+/**
+ * @description Make `<root>/bin/<name>` the tool at `targetPath`. Jobs get `~/.charness-runner/bin` FIRST on their PATH, so what is linked
+ * there is what every job (and phase 1's runner script) runs — discovery that only looked at the caller's PATH would report a tool that
+ * the jobs never see.
+ */
+function linkToolIntoBin(paths, name, targetPath) {
+    const linkPath = path.join(paths.binDir, name);
+    if (linkPath === targetPath)
+        return;
+    fs.mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+    fs.rmSync(linkPath, { force: true });
+    fs.symlinkSync(targetPath, linkPath);
+}
+/** @description rsync: the usable one that is there — linked into the runner's bin folder so jobs run exactly that one — else a built one. */
+async function ensureRsync(paths, deps) {
+    const found = await findRsync(paths, deps);
+    if (found === null)
+        return buildRsync(paths, deps);
+    linkToolIntoBin(paths, 'rsync', found.path);
+    return { ok: true, tool: found, wasInstalled: false };
+}
+//# sourceMappingURL=toolInstall.js.map

package/dist/runnerUtility/toolInstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolInstall.js","sourceRoot":"","sources":["../../src/runnerUtility/toolInstall.ts"],"names":[],"mappings":"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"}

package/dist/runnerUtility/versionPollTiming.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description How often a LINKED runner asks the hub which package it has now (the `version` request, over the connection it already
+ * holds). A link that stays healthy for days would otherwise never learn of a hub update: the `link` answer names the package once, when
+ * the link starts. In a module of its own so the runner utility reads it without loading the bot.
+ *
+ * The test seam `CHARNESS_TEST_TIMINGS` (`testTimings.ts`) may only SHORTEN it (key `runnerVersionPollMs`); like the remote-run lease it
+ * is read tolerantly here, because this module cannot import `testTimings.ts` (its graph reaches the bot) — the boot of an instance that
+ * carries a bad value is what refuses it by name.
+ */
+/** Production: ask every five minutes. */
+export declare const runnerVersionPollMs: number;
+/** A shorter poll than this is a request loop, not a check. */
+export declare const runnerVersionPollMinMs = 1000;
+/** @description The poll interval in force: the production one, or the seam's shorter `runnerVersionPollMs` when it is a whole number of ms within [min, production]. */
+export declare function readRunnerVersionPollMs(env: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=versionPollTiming.d.ts.map

package/dist/runnerUtility/versionPollTiming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionPollTiming.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/versionPollTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0CAA0C;AAC1C,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AACjD,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAI3C,yKAAyK;AACzK,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAYtE"}

package/dist/runnerUtility/versionPollTiming.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @description How often a LINKED runner asks the hub which package it has now (the `version` request, over the connection it already
+ * holds). A link that stays healthy for days would otherwise never learn of a hub update: the `link` answer names the package once, when
+ * the link starts. In a module of its own so the runner utility reads it without loading the bot.
+ *
+ * The test seam `CHARNESS_TEST_TIMINGS` (`testTimings.ts`) may only SHORTEN it (key `runnerVersionPollMs`); like the remote-run lease it
+ * is read tolerantly here, because this module cannot import `testTimings.ts` (its graph reaches the bot) — the boot of an instance that
+ * carries a bad value is what refuses it by name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runnerVersionPollMinMs = exports.runnerVersionPollMs = void 0;
+exports.readRunnerVersionPollMs = readRunnerVersionPollMs;
+/** Production: ask every five minutes. */
+exports.runnerVersionPollMs = 5 * 60 * 1000;
+/** A shorter poll than this is a request loop, not a check. */
+exports.runnerVersionPollMinMs = 1000;
+const testTimingsVariableName = 'CHARNESS_TEST_TIMINGS';
+/** @description The poll interval in force: the production one, or the seam's shorter `runnerVersionPollMs` when it is a whole number of ms within [min, production]. */
+function readRunnerVersionPollMs(env) {
+    const rawTestTimings = env[testTimingsVariableName];
+    if (rawTestTimings === undefined || rawTestTimings.trim() === '')
+        return exports.runnerVersionPollMs;
+    let overrides;
+    try {
+        overrides = JSON.parse(rawTestTimings);
+    }
+    catch {
+        return exports.runnerVersionPollMs;
+    }
+    const overrideMs = overrides?.runnerVersionPollMs;
+    if (overrideMs === undefined || !Number.isInteger(overrideMs))
+        return exports.runnerVersionPollMs;
+    return overrideMs >= exports.runnerVersionPollMinMs && overrideMs <= exports.runnerVersionPollMs ? overrideMs : exports.runnerVersionPollMs;
+}
+//# sourceMappingURL=versionPollTiming.js.map

package/dist/runnerUtility/versionPollTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionPollTiming.js","sourceRoot":"","sources":["../../src/runnerUtility/versionPollTiming.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAUH,0DAYC;AApBD,0CAA0C;AAC7B,QAAA,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACjD,+DAA+D;AAClD,QAAA,sBAAsB,GAAG,IAAI,CAAC;AAE3C,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAExD,yKAAyK;AACzK,SAAgB,uBAAuB,CAAC,GAAsB;IAC5D,MAAM,cAAc,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACpD,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,2BAAmB,CAAC;IAC7F,IAAI,SAAkD,CAAC;IACvD,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,2BAAmB,CAAC;IAC7B,CAAC;IACD,MAAM,UAAU,GAAG,SAAS,EAAE,mBAAmB,CAAC;IAClD,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,2BAAmB,CAAC;IAC1F,OAAO,UAAU,IAAI,8BAAsB,IAAI,UAAU,IAAI,2BAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,2BAAmB,CAAC;AACtH,CAAC"}

package/dist/runners/authorizedKeys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @description The part of the account's `authorized_keys` that charness owns: ONE marked block, replaced as a whole and derived from
+ * the registry (`hubRegistry.ts` renders it), so the file and the registry never drift apart. Every line outside the markers is the
+ * operator's and is kept byte for byte. A file with a damaged block (a marker without its twin, two blocks) is NOT edited — guessing
+ * which lines are ours could delete a key of the operator.
+ *
+ * A runner's key is a forced-command key with NO forwarding of any kind: `restrict` turns off port, unix-socket, agent and X11
+ * forwarding, ptys and `~/.ssh/rc`; OpenSSH cannot limit forwarding of unix sockets in any finer way, and a key that could forward
+ * one could open the bot's tmux sockets.
+ */
+export declare const authorizedKeysBlockStart = "# charness runners: managed block, do not edit between the markers";
+export declare const authorizedKeysBlockEnd = "# charness runners: end of the managed block";
+export declare class AuthorizedKeysBlockError extends Error {
+    constructor(message: string);
+}
+/** @description The lines between the markers (none when there is no block). */
+export declare function extractManagedBlock(text: string): string[];
+/**
+ * @description `text` with the managed block holding exactly `blockLines`: an existing block is replaced in place, a new one is
+ * appended, and no lines remove the block (the file is returned as it was when there is none). Nothing outside the block changes.
+ */
+export declare function replaceManagedBlock(text: string, blockLines: readonly string[]): string;
+/** @description `YYYYMMDDHHMMSSZ` (UTC), the form of sshd's `expiry-time` option. */
+export declare function formatExpiryTime(epochMs: number): string;
+export interface TempKeyLineParams {
+    publicKey: string;
+    expiresAtMs: number;
+    gatePath: string;
+    keysPath: string;
+    dir: string;
+    pairId: string;
+}
+/** @description The line of a pairing's temporary key: it may log in until `expiresAtMs` and only to be handed to the gate's `redeem` mode. */
+export declare function buildTempKeyLine(params: TempKeyLineParams): string;
+export interface RunnerKeyLineParams {
+    publicKey: string;
+    gatePath: string;
+    keysPath: string;
+    dir: string;
+    runnerId: string;
+}
+/** @description The line of a paired runner's key: no expiry, the gate's `runner` mode. */
+export declare function buildRunnerKeyLine(params: RunnerKeyLineParams): string;
+/** @description Throws {@link AuthorizedKeysBlockError} when the file holds a damaged block — asked BEFORE a change is committed, so a block that cannot be edited never leaves a half-done change behind. */
+export declare function assertManagedBlockIntact(authorizedKeysPath: string): void;
+/**
+ * @description Make the managed block of `authorizedKeysPath` hold exactly `blockLines`. The folder is created 0700 when missing
+ * (sshd's StrictModes refuses a writable one), the file is written 0600 through a temp file and a rename — into the file a symlink
+ * points to, never over the link (a dotfile manager keeps the real file elsewhere). Nothing is written when nothing changes.
+ */
+export declare function writeManagedBlock(authorizedKeysPath: string, blockLines: readonly string[]): void;
+//# sourceMappingURL=authorizedKeys.d.ts.map

package/dist/runners/authorizedKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizedKeys.d.ts","sourceRoot":"","sources":["../../src/runners/authorizedKeys.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH,eAAO,MAAM,wBAAwB,uEAAuE,CAAC;AAC7G,eAAO,MAAM,sBAAsB,iDAAiD,CAAC;AAOrF,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAiBD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAUvF;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD;AAUD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+IAA+I;AAC/I,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAWD,8MAA8M;AAC9M,wBAAgB,wBAAwB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAOjG"}

package/dist/runners/authorizedKeys.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthorizedKeysBlockError = exports.authorizedKeysBlockEnd = exports.authorizedKeysBlockStart = void 0;
+exports.extractManagedBlock = extractManagedBlock;
+exports.replaceManagedBlock = replaceManagedBlock;
+exports.formatExpiryTime = formatExpiryTime;
+exports.buildTempKeyLine = buildTempKeyLine;
+exports.buildRunnerKeyLine = buildRunnerKeyLine;
+exports.assertManagedBlockIntact = assertManagedBlockIntact;
+exports.writeManagedBlock = writeManagedBlock;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const configDirFile_1 = require("../configDirFile");
+const ssh_1 = require("../remoteRun/ssh");
+/**
+ * @description The part of the account's `authorized_keys` that charness owns: ONE marked block, replaced as a whole and derived from
+ * the registry (`hubRegistry.ts` renders it), so the file and the registry never drift apart. Every line outside the markers is the
+ * operator's and is kept byte for byte. A file with a damaged block (a marker without its twin, two blocks) is NOT edited — guessing
+ * which lines are ours could delete a key of the operator.
+ *
+ * A runner's key is a forced-command key with NO forwarding of any kind: `restrict` turns off port, unix-socket, agent and X11
+ * forwarding, ptys and `~/.ssh/rc`; OpenSSH cannot limit forwarding of unix sockets in any finer way, and a key that could forward
+ * one could open the bot's tmux sockets.
+ */
+exports.authorizedKeysBlockStart = '# charness runners: managed block, do not edit between the markers';
+exports.authorizedKeysBlockEnd = '# charness runners: end of the managed block';
+const sshDirectoryMode = 0o700;
+const authorizedKeysMode = 0o600;
+/** What may not appear in the folder path inside `command="…"`: sshd cannot escape a backslash, and a quote ends the option. */
+const unsafeCommandCharacters = /["'\\\n\r]/;
+const msPerSecond = 1000;
+class AuthorizedKeysBlockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthorizedKeysBlockError';
+    }
+}
+exports.AuthorizedKeysBlockError = AuthorizedKeysBlockError;
+function findBlock(lines) {
+    const starts = lines.flatMap((line, index) => (line.trimEnd() === exports.authorizedKeysBlockStart ? [index] : []));
+    const ends = lines.flatMap((line, index) => (line.trimEnd() === exports.authorizedKeysBlockEnd ? [index] : []));
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
+        throw new AuthorizedKeysBlockError('authorized_keys holds a damaged charness block (the two marker lines do not pair up); fix it by hand — nothing was changed');
+    }
+    return { startIndex: starts[0], endIndex: ends[0] };
+}
+/** @description The lines between the markers (none when there is no block). */
+function extractManagedBlock(text) {
+    const lines = text.split('\n');
+    const block = findBlock(lines);
+    return block === null ? [] : lines.slice(block.startIndex + 1, block.endIndex);
+}
+/**
+ * @description `text` with the managed block holding exactly `blockLines`: an existing block is replaced in place, a new one is
+ * appended, and no lines remove the block (the file is returned as it was when there is none). Nothing outside the block changes.
+ */
+function replaceManagedBlock(text, blockLines) {
+    const lines = text.split('\n');
+    const block = findBlock(lines);
+    if (block === null) {
+        if (blockLines.length === 0)
+            return text;
+        const prefix = text === '' || text.endsWith('\n') ? text : `${text}\n`;
+        return `${prefix}${[exports.authorizedKeysBlockStart, ...blockLines, exports.authorizedKeysBlockEnd].join('\n')}\n`;
+    }
+    const replacement = blockLines.length === 0 ? [] : [exports.authorizedKeysBlockStart, ...blockLines, exports.authorizedKeysBlockEnd];
+    return [...lines.slice(0, block.startIndex), ...replacement, ...lines.slice(block.endIndex + 1)].join('\n');
+}
+/** @description `YYYYMMDDHHMMSSZ` (UTC), the form of sshd's `expiry-time` option. */
+function formatExpiryTime(epochMs) {
+    const iso = new Date(Math.floor(epochMs / msPerSecond) * msPerSecond).toISOString();
+    return `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}Z`;
+}
+function buildGateCommand(gatePath, keysPath, dir, kind, id) {
+    for (const value of [gatePath, keysPath, dir]) {
+        if (unsafeCommandCharacters.test(value))
+            throw new AuthorizedKeysBlockError('the charness folder path holds a quote, a backslash or a line break, which an authorized_keys command cannot carry');
+    }
+    const command = [(0, ssh_1.quoteShellWord)(gatePath), '--dir', (0, ssh_1.quoteShellWord)(dir), '--keys', (0, ssh_1.quoteShellWord)(keysPath), kind, id].join(' ');
+    return `command="${command}"`;
+}
+/** @description The line of a pairing's temporary key: it may log in until `expiresAtMs` and only to be handed to the gate's `redeem` mode. */
+function buildTempKeyLine(params) {
+    return `restrict,expiry-time="${formatExpiryTime(params.expiresAtMs)}",${buildGateCommand(params.gatePath, params.keysPath, params.dir, 'redeem', params.pairId)} ${params.publicKey} charness-pairing:${params.pairId}`;
+}
+/** @description The line of a paired runner's key: no expiry, the gate's `runner` mode. */
+function buildRunnerKeyLine(params) {
+    return `restrict,${buildGateCommand(params.gatePath, params.keysPath, params.dir, 'runner', params.runnerId)} ${params.publicKey} charness-runner:${params.runnerId}`;
+}
+function readTextIfPresent(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+/** @description Throws {@link AuthorizedKeysBlockError} when the file holds a damaged block — asked BEFORE a change is committed, so a block that cannot be edited never leaves a half-done change behind. */
+function assertManagedBlockIntact(authorizedKeysPath) {
+    extractManagedBlock(readTextIfPresent(authorizedKeysPath));
+}
+/**
+ * @description Make the managed block of `authorizedKeysPath` hold exactly `blockLines`. The folder is created 0700 when missing
+ * (sshd's StrictModes refuses a writable one), the file is written 0600 through a temp file and a rename — into the file a symlink
+ * points to, never over the link (a dotfile manager keeps the real file elsewhere). Nothing is written when nothing changes.
+ */
+function writeManagedBlock(authorizedKeysPath, blockLines) {
+    fs.mkdirSync(path.dirname(authorizedKeysPath), { recursive: true, mode: sshDirectoryMode });
+    const targetPath = fs.existsSync(authorizedKeysPath) ? fs.realpathSync(authorizedKeysPath) : authorizedKeysPath;
+    const current = readTextIfPresent(targetPath);
+    const next = replaceManagedBlock(current, blockLines);
+    if (next === current)
+        return;
+    (0, configDirFile_1.writeTextFileAtomically)(targetPath, next, authorizedKeysMode);
+}
+//# sourceMappingURL=authorizedKeys.js.map