charness 3.6.1 → 3.8.0

package/dist/remoteRun/remoteRunCli.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remoteRunUsage = exports.createProcessIo = void 0;
+exports.readCurrentRunners = readCurrentRunners;
+exports.runRemoteRunCli = runRemoteRunCli;
+const commands_1 = require("./commands");
+const cliArgs_1 = require("./cliArgs");
+const exitCodes_1 = require("./exitCodes");
+const interrupts_1 = require("./interrupts");
+const leaseTiming_1 = require("./leaseTiming");
+const output_1 = require("./output");
+Object.defineProperty(exports, "createProcessIo", { enumerable: true, get: function () { return output_1.createProcessIo; } });
+const remoteRunError_1 = require("./remoteRunError");
+const runnerClient_1 = require("./runnerClient");
+const runnersConfig_1 = require("./runnersConfig");
+const runnersCatalog_1 = require("./runnersCatalog");
+const runnerWait_1 = require("./runnerWait");
+const runnerWaitTiming_1 = require("./runnerWaitTiming");
+const ssh_1 = require("./ssh");
+exports.remoteRunUsage = `Usage:
+  charness remote-run [--runner <name>] [--needs android|ios|docker|playwright] [--runner-wait <dur>] [--group <g>]
+                      [--timeout <dur>] [--with-git] [-e NAME=VALUE]… [--bg] <command…>
+                              run <command> on a runner, in the same folder of a copy of this git project;
+                              output and exit code come back, interrupt or timeout kills the remote job.
+                              --bg prints a job id and returns (long runs).
+                              --needs with a paired runner that has it but is offline waits for it up to --runner-wait
+                              (default 15m, 0 = fail at once).
+                              Options go BEFORE the command; a command that starts with a subcommand name goes after --
+  charness remote-run runners                 the runners: online, hardware, load, what each can do
+  charness remote-run ls [--all]              jobs of this project (all projects with --all)
+  charness remote-run status <id>             one job
+  charness remote-run logs <id> [-f] [--tail N]
+  charness remote-run wait <id>               block until the job ends, fetch its files, exit with its code
+  charness remote-run kill <id>
+  charness remote-run fetch <id>              bring a finished job's result files back (again)
+  charness remote-run exec [--runner <name>] <command…>
+                              one-off command in the runner's copy as the last job left it (no sync)
+Exit codes: the command's own; 125 remote-run failed, 124 timeout, 130/143/129 interrupted (SIGINT/SIGTERM/SIGHUP), 137 job killed, 2 bad usage.
+Setup: docs/remote-run.md
+`;
+/**
+ * @description The runners as they are right now, for a look in the middle of a command (the wait for an offline runner re-reads them at
+ * every look). A file that is half-way through an edit, or a name that clashes for a moment, must not end a wait that may be 15 minutes
+ * in: the list that last loaded is used. Only when nothing ever loaded does a broken file or registry stop the caller with its errors.
+ * No runner at all is an empty list.
+ */
+function readCurrentRunners(homeDir) {
+    const load = (0, runnersCatalog_1.loadRunnersCatalog)(homeDir);
+    if (load.status === 'invalid') {
+        if (load.config !== null)
+            return load.config;
+        throw new remoteRunError_1.RemoteRunError(load.errors.join('\n'));
+    }
+    return load.config;
+}
+function createContext(io) {
+    const load = (0, runnersCatalog_1.loadRunnersCatalog)(io.homeDir);
+    if (load.status === 'missing') {
+        throw new remoteRunError_1.RemoteRunError(`no runners are set up: ${(0, runnersConfig_1.getRunnersConfigPath)(io.homeDir)} does not exist and none is paired (docs/remote-run.md explains how to add one; \`charness runners pair\` pairs one)`);
+    }
+    if (load.status === 'invalid')
+        throw new remoteRunError_1.RemoteRunError(load.errors.join('\n'));
+    if (load.config.runners.length === 0)
+        throw new remoteRunError_1.RemoteRunError(`${(0, runnersConfig_1.getRunnersConfigPath)(io.homeDir)} lists no runners and none is paired`);
+    const cacheDir = (0, ssh_1.getRemoteRunCacheDir)(io.env, io.homeDir);
+    (0, ssh_1.ensureRemoteRunCacheDir)(cacheDir);
+    return {
+        io,
+        config: load.config,
+        cacheDir,
+        script: (0, runnerClient_1.readRunnerScript)(),
+        leaseMs: (0, leaseTiming_1.readRemoteRunLeaseMs)(io.env),
+        now: Date.now,
+        loadRunners: () => readCurrentRunners(io.homeDir),
+        runnerPollMs: (0, runnerWaitTiming_1.readRunnerWaitPollMs)(io.env),
+        sleep: runnerWait_1.sleepUntilStopped,
+        watchInterrupts: interrupts_1.addInterruptHandlerWithHardStop,
+    };
+}
+/** @description Run the command line (the words after `remote-run`); resolves with the exit code. */
+async function runRemoteRunCli(argv, io = (0, output_1.createProcessIo)()) {
+    const parsed = (0, cliArgs_1.parseRemoteRunArgs)(argv);
+    if (!parsed.ok) {
+        io.stderr(`remote-run: ${parsed.error}\n\n${exports.remoteRunUsage}`);
+        return exitCodes_1.remoteRunExitCodes.usage;
+    }
+    const { command } = parsed;
+    if (command.kind === 'help') {
+        if (argv.length === 0) {
+            io.stderr(exports.remoteRunUsage);
+            return exitCodes_1.remoteRunExitCodes.usage;
+        }
+        io.stdout(exports.remoteRunUsage);
+        return 0;
+    }
+    try {
+        const context = createContext(io);
+        switch (command.kind) {
+            case 'run': return await (0, commands_1.runRunCommand)(command, context);
+            case 'runners': return await (0, commands_1.runRunnersCommand)(context);
+            case 'ls': return await (0, commands_1.runLsCommand)(command, context);
+            case 'status': return await (0, commands_1.runStatusCommand)(command, context);
+            case 'logs': return await (0, commands_1.runLogsCommand)(command, context);
+            case 'wait': return await (0, commands_1.runWaitCommand)(command, context);
+            case 'fetch': return await (0, commands_1.runFetchCommand)(command, context);
+            case 'kill': return await (0, commands_1.runKillCommand)(command, context);
+            case 'exec': return await (0, commands_1.runExecCommand)(command, context);
+        }
+    }
+    catch (error) {
+        if (error instanceof remoteRunError_1.RemoteRunError) {
+            io.stderr(`remote-run: ${error.message}\n`);
+            return error.exitCode;
+        }
+        io.stderr(`remote-run: unexpected error: ${error instanceof Error ? error.message : 'unknown'}\n`);
+        return exitCodes_1.remoteRunExitCodes.failed;
+    }
+}
+//# sourceMappingURL=remoteRunCli.js.map

package/dist/remoteRun/remoteRunCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteRunCli.js","sourceRoot":"","sources":["../../src/remoteRun/remoteRunCli.ts"],"names":[],"mappings":";;;AAgEA,gDAOC;AA0BD,0CAoCC;AArID,yCAWoB;AACpB,uCAA+C;AAC/C,2CAAiD;AACjD,6CAA+D;AAC/D,+CAAqD;AACrD,qCAAuD;AAkB9C,gGAlBA,wBAAe,OAkBA;AAjBxB,qDAAkD;AAClD,iDAAkD;AAClD,mDAA2E;AAC3E,qDAAsD;AACtD,6CAAiD;AACjD,yDAA0D;AAC1D,+BAAsE;AAazD,QAAA,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;CAoB7B,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,OAAe;IAChD,MAAM,IAAI,GAAG,IAAA,mCAAkB,EAAC,OAAO,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAC7C,MAAM,IAAI,+BAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAED,SAAS,aAAa,CAAC,EAAS;IAC9B,MAAM,IAAI,GAAG,IAAA,mCAAkB,EAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,+BAAc,CAAC,0BAA0B,IAAA,oCAAoB,EAAC,EAAE,CAAC,OAAO,CAAC,sHAAsH,CAAC,CAAC;IAC7M,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,+BAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChF,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,+BAAc,CAAC,GAAG,IAAA,oCAAoB,EAAC,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC;IAC1I,MAAM,QAAQ,GAAG,IAAA,0BAAoB,EAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;IAC1D,IAAA,6BAAuB,EAAC,QAAQ,CAAC,CAAC;IAClC,OAAO;QACL,EAAE;QACF,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ;QACR,MAAM,EAAE,IAAA,+BAAgB,GAAE;QAC1B,OAAO,EAAE,IAAA,kCAAoB,EAAC,EAAE,CAAC,GAAG,CAAC;QACrC,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,WAAW,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,CAAC;QACjD,YAAY,EAAE,IAAA,uCAAoB,EAAC,EAAE,CAAC,GAAG,CAAC;QAC1C,KAAK,EAAE,8BAAiB;QACxB,eAAe,EAAE,4CAA+B;KACjD,CAAC;AACJ,CAAC;AAED,qGAAqG;AAC9F,KAAK,UAAU,eAAe,CAAC,IAAuB,EAAE,KAAY,IAAA,wBAAe,GAAE;IAC1F,MAAM,MAAM,GAAG,IAAA,4BAAkB,EAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,eAAe,MAAM,CAAC,KAAK,OAAO,sBAAc,EAAE,CAAC,CAAC;QAC9D,OAAO,8BAAkB,CAAC,KAAK,CAAC;IAClC,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC3B,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,EAAE,CAAC,MAAM,CAAC,sBAAc,CAAC,CAAC;YAC1B,OAAO,8BAAkB,CAAC,KAAK,CAAC;QAClC,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,sBAAc,CAAC,CAAC;QAC1B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;QAClC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,KAAK,CAAC,CAAC,OAAO,MAAM,IAAA,wBAAa,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzD,KAAK,SAAS,CAAC,CAAC,OAAO,MAAM,IAAA,4BAAiB,EAAC,OAAO,CAAC,CAAC;YACxD,KAAK,IAAI,CAAC,CAAC,OAAO,MAAM,IAAA,uBAAY,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACvD,KAAK,QAAQ,CAAC,CAAC,OAAO,MAAM,IAAA,2BAAgB,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/D,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC3D,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC3D,KAAK,OAAO,CAAC,CAAC,OAAO,MAAM,IAAA,0BAAe,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7D,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC3D,KAAK,MAAM,CAAC,CAAC,OAAO,MAAM,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,+BAAc,EAAE,CAAC;YACpC,EAAE,CAAC,MAAM,CAAC,eAAe,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YAC5C,OAAO,KAAK,CAAC,QAAQ,CAAC;QACxB,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,iCAAiC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC;QACnG,OAAO,8BAAkB,CAAC,MAAM,CAAC;IACnC,CAAC;AACH,CAAC"}

package/dist/remoteRun/remoteRunError.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @description A failure remote-run reports as its own (never the command's): the message goes to stderr, the exit code is the
+ * given one (125 unless the cause is a usage mistake or a timeout).
+ */
+export declare class RemoteRunError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** @description The runner could not be reached (ssh failed before the script ran): `reason` is the short ssh-side cause the `runners` view shows. */
+export declare class RunnerUnreachableError extends RemoteRunError {
+    readonly reason: string;
+    constructor(runnerName: string, reason: string);
+}
+//# sourceMappingURL=remoteRunError.d.ts.map

package/dist/remoteRun/remoteRunError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteRunError.d.ts","sourceRoot":"","sources":["../../src/remoteRun/remoteRunError.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkC;CAK1E;AAED,sJAAsJ;AACtJ,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK/C"}

package/dist/remoteRun/remoteRunError.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunnerUnreachableError = exports.RemoteRunError = void 0;
+const exitCodes_1 = require("./exitCodes");
+/**
+ * @description A failure remote-run reports as its own (never the command's): the message goes to stderr, the exit code is the
+ * given one (125 unless the cause is a usage mistake or a timeout).
+ */
+class RemoteRunError extends Error {
+    exitCode;
+    constructor(message, exitCode = exitCodes_1.remoteRunExitCodes.failed) {
+        super(message);
+        this.name = 'RemoteRunError';
+        this.exitCode = exitCode;
+    }
+}
+exports.RemoteRunError = RemoteRunError;
+/** @description The runner could not be reached (ssh failed before the script ran): `reason` is the short ssh-side cause the `runners` view shows. */
+class RunnerUnreachableError extends RemoteRunError {
+    reason;
+    constructor(runnerName, reason) {
+        super(`runner "${runnerName}" is unreachable — ${reason}`);
+        this.name = 'RunnerUnreachableError';
+        this.reason = reason;
+    }
+}
+exports.RunnerUnreachableError = RunnerUnreachableError;
+//# sourceMappingURL=remoteRunError.js.map

package/dist/remoteRun/remoteRunError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteRunError.js","sourceRoot":"","sources":["../../src/remoteRun/remoteRunError.ts"],"names":[],"mappings":";;;AAAA,2CAAiD;AAEjD;;;GAGG;AACH,MAAa,cAAe,SAAQ,KAAK;IAC9B,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,WAAmB,8BAAkB,CAAC,MAAM;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AARD,wCAQC;AAED,sJAAsJ;AACtJ,MAAa,sBAAuB,SAAQ,cAAc;IAC/C,MAAM,CAAS;IAExB,YAAY,UAAkB,EAAE,MAAc;QAC5C,KAAK,CAAC,WAAW,UAAU,sBAAsB,MAAM,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AARD,wDAQC"}

package/dist/remoteRun/rsync.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @description `rsync` as a spawned process with a deadline. Exit 24 ("some source files vanished", a file edited while it was being
+ * sent) is not a failure: the next submit sends the new state. The ssh half is the `-e` command the caller built.
+ */
+/** A first send of a large project is the slowest thing remote-run does. */
+export declare const syncTimeoutMs: number;
+export interface RsyncResult {
+    isOk: boolean;
+    /** The last of rsync's stderr, for a message. */
+    errorTail: string;
+}
+/** @description Run rsync with `args`, `input` on its stdin (the NUL-separated file list). */
+export declare function runRsync(args: readonly string[], options?: {
+    input?: string;
+    timeoutMs?: number;
+}): Promise<RsyncResult>;
+//# sourceMappingURL=rsync.d.ts.map

package/dist/remoteRun/rsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsync.d.ts","sourceRoot":"","sources":["../../src/remoteRun/rsync.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,aAAa,QAAiB,CAAC;AAI5C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB5H"}

package/dist/remoteRun/rsync.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTimeoutMs = void 0;
+exports.runRsync = runRsync;
+const child_process_1 = require("child_process");
+/**
+ * @description `rsync` as a spawned process with a deadline. Exit 24 ("some source files vanished", a file edited while it was being
+ * sent) is not a failure: the next submit sends the new state. The ssh half is the `-e` command the caller built.
+ */
+/** A first send of a large project is the slowest thing remote-run does. */
+exports.syncTimeoutMs = 30 * 60 * 1000;
+const rsyncVanishedFilesExitCode = 24;
+const stderrTailLength = 600;
+/** @description Run rsync with `args`, `input` on its stdin (the NUL-separated file list). */
+function runRsync(args, options = {}) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)('rsync', [...args], { stdio: ['pipe', 'ignore', 'pipe'] });
+        let stderr = '';
+        let isTimedOut = false;
+        const timer = setTimeout(() => {
+            isTimedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeoutMs ?? exports.syncTimeoutMs);
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.stdin.on('error', () => { });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            resolve({ isOk: false, errorTail: `could not start rsync: ${error.message}` });
+        });
+        child.on('close', (exitCode) => {
+            clearTimeout(timer);
+            const isOk = exitCode === 0 || exitCode === rsyncVanishedFilesExitCode;
+            resolve({ isOk, errorTail: isTimedOut ? 'rsync ran past its deadline' : stderr.trim().slice(-stderrTailLength) });
+        });
+        child.stdin.end(options.input ?? '');
+    });
+}
+//# sourceMappingURL=rsync.js.map

package/dist/remoteRun/rsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsync.js","sourceRoot":"","sources":["../../src/remoteRun/rsync.ts"],"names":[],"mappings":";;;AAmBA,4BAuBC;AA1CD,iDAAsC;AAEtC;;;GAGG;AAEH,4EAA4E;AAC/D,QAAA,aAAa,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC5C,MAAM,0BAA0B,GAAG,EAAE,CAAC;AACtC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAQ7B,8FAA8F;AAC9F,SAAgB,QAAQ,CAAC,IAAuB,EAAE,UAAkD,EAAE;IACpG,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/E,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,UAAU,GAAG,IAAI,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC,EAAE,OAAO,CAAC,SAAS,IAAI,qBAAa,CAAC,CAAC;QACvC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAmD,CAAC,CAAC,CAAC;QACnF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,0BAA0B,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACjF,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE;YAC7B,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,IAAI,GAAG,QAAQ,KAAK,CAAC,IAAI,QAAQ,KAAK,0BAA0B,CAAC;YACvE,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;QACpH,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/remoteRun/runnerClient.d.ts

@@ -0,0 +1,52 @@
+import type { RunnerConfig } from './runnersConfig';
+import { spawnSshStream, type SshRunResult } from './ssh';
+/** An ordinary call: a prepare may start the Pueue daemon, a result or a kill is quicker. */
+export declare const shortCallTimeoutMs: number;
+export interface RunnerScript {
+    /** `runner-<sha8>.sh` */
+    name: string;
+    text: string;
+}
+/** @description `remoteRun/runner.sh` at the package root, resolved from both `src/remoteRun` (tsx) and `dist/remoteRun` (built): two levels up. */
+export declare function getRunnerScriptPath(): string;
+export declare function readRunnerScript(scriptPath?: string): RunnerScript;
+export interface RunnerClient {
+    readonly runner: RunnerConfig;
+    readonly cacheDir: string;
+    /** The `-e` command of rsync for this runner. */
+    readonly rsyncSshCommand: string;
+    /**
+     * Upload the script when the runner does not have this version; throws a {@link RunnerUnreachableError} when the runner cannot be
+     * reached. `signal` ends the ssh calls it makes from outside (a shared deadline).
+     */
+    ensureScript: (signal?: AbortSignal) => Promise<void>;
+    /** The runner's work dir as an absolute path (a configured `~/…` is resolved on the runner once). */
+    getAbsoluteWorkDir: () => Promise<string>;
+    /** One subcommand of the script; never throws for a non-zero exit (the caller reads it). */
+    call: (subcommand: string, args: readonly string[], options?: {
+        input?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<SshRunResult>;
+    /** The same, but a non-zero exit or a timeout is a {@link RemoteRunError} carrying the runner's own message. */
+    callOrThrow: (subcommand: string, args: readonly string[], options?: {
+        input?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<string>;
+    /** The long-lived form: a spawned ssh whose streams the caller handles. */
+    stream: (subcommand: string, args: readonly string[]) => ReturnType<typeof spawnSshStream>;
+}
+/** Why a paired runner whose link is down is offline — the words `charness runner-proxy` (`runners/runnerProxy.ts`) puts on stderr when nothing listens on the link's socket. */
+export declare const notConnectedReason = "the runner is not connected";
+/**
+ * @description The first useful line of a failed ssh's stderr, for a message (never the whole text: it may quote the destination). A
+ * rejected key from a process with no ssh-agent (`SSH_AUTH_SOCK` unset — a tracker agent such as Jira's starts with a minimal environment
+ * that has none) says what that means and the way out: a key that is only held by an agent works for a Telegram agent and not for that one.
+ */
+export declare function describeSshFailure(result: SshRunResult, env?: NodeJS.ProcessEnv): string;
+/** @description The runner script's own refusal in a stderr text («remote-run-runner: no such job: x» → «no such job: x»): the last line, without the script's prefix. */
+export declare function describeRunnerRefusal(stderr: string, fallback: string): string;
+/** @description Create the client of `runner`. `script` and the spawn functions are injectable for the tests. */
+export declare function createRunnerClient(runner: RunnerConfig, cacheDir: string, script?: RunnerScript): RunnerClient;
+//# sourceMappingURL=runnerClient.d.ts.map

package/dist/remoteRun/runnerClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerClient.d.ts","sourceRoot":"","sources":["../../src/remoteRun/runnerClient.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAOL,cAAc,EACd,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAUf,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAG5C,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oJAAoJ;AACpJ,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,UAAU,GAAE,MAA8B,GAAG,YAAY,CAGzF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,qGAAqG;IACrG,kBAAkB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,4FAA4F;IAC5F,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACrJ,gHAAgH;IAChH,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtJ,2EAA2E;IAC3E,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;CAC5F;AAED,iLAAiL;AACjL,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAarG;AAED,0KAA0K;AAC1K,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9E;AAED,iHAAiH;AACjH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,YAAiC,GAAG,YAAY,CA8ClI"}

package/dist/remoteRun/runnerClient.js

@@ -0,0 +1,143 @@
+"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.notConnectedReason = exports.shortCallTimeoutMs = void 0;
+exports.getRunnerScriptPath = getRunnerScriptPath;
+exports.readRunnerScript = readRunnerScript;
+exports.describeSshFailure = describeSshFailure;
+exports.describeRunnerRefusal = describeRunnerRefusal;
+exports.createRunnerClient = createRunnerClient;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const remoteRunError_1 = require("./remoteRunError");
+const ssh_1 = require("./ssh");
+/**
+ * @description One runner as the rest of remote-run uses it: the uploaded script's subcommands as calls, Pueue through the same
+ * script, and the pieces rsync needs. The script is `remoteRun/runner.sh` at the package root (shipped in `files`, like the STT
+ * sidecar); it is uploaded to `<workDir>/bin/runner-<sha8>.sh` when that file is missing, so two versions of charness on one
+ * runner never clash.
+ */
+const scriptHashLength = 8;
+/** An ordinary call: a prepare may start the Pueue daemon, a result or a kill is quicker. */
+exports.shortCallTimeoutMs = 60 * 1000;
+const scriptUploadTimeoutMs = 60 * 1000;
+/** @description `remoteRun/runner.sh` at the package root, resolved from both `src/remoteRun` (tsx) and `dist/remoteRun` (built): two levels up. */
+function getRunnerScriptPath() {
+    return path.join(fs.realpathSync(__dirname), '..', '..', 'remoteRun', 'runner.sh');
+}
+function readRunnerScript(scriptPath = getRunnerScriptPath()) {
+    const text = fs.readFileSync(scriptPath, 'utf8');
+    return { name: `runner-${(0, crypto_1.createHash)('sha256').update(text).digest('hex').slice(0, scriptHashLength)}.sh`, text };
+}
+/** Why a paired runner whose link is down is offline — the words `charness runner-proxy` (`runners/runnerProxy.ts`) puts on stderr when nothing listens on the link's socket. */
+exports.notConnectedReason = 'the runner is not connected';
+/**
+ * @description The first useful line of a failed ssh's stderr, for a message (never the whole text: it may quote the destination). A
+ * rejected key from a process with no ssh-agent (`SSH_AUTH_SOCK` unset — a tracker agent such as Jira's starts with a minimal environment
+ * that has none) says what that means and the way out: a key that is only held by an agent works for a Telegram agent and not for that one.
+ */
+function describeSshFailure(result, env = process.env) {
+    if (result.isTimedOut)
+        return 'ssh: the command ran past its deadline';
+    if (result.stderr.includes(exports.notConnectedReason))
+        return exports.notConnectedReason;
+    const lines = result.stderr.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+    const text = lines.length === 0 ? `ssh exited with ${result.exitCode ?? 'a signal'}` : lines[lines.length - 1];
+    if (/host key verification failed/i.test(result.stderr))
+        return `ssh: the host key is not trusted yet — connect once by hand (ssh to this runner) so it is known`;
+    if (/permission denied/i.test(result.stderr)) {
+        const hasAgent = env.SSH_AUTH_SOCK !== undefined && env.SSH_AUTH_SOCK !== '';
+        return hasAgent
+            ? 'ssh: the key was rejected (permission denied)'
+            : 'ssh: the key was rejected (permission denied) — this process has no ssh-agent (SSH_AUTH_SOCK is unset, as for a Jira agent), so the key must work without one: a key file with no passphrase, given as "sshOptions": ["-i", "<path>"] in runners.json';
+    }
+    return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+/** @description The runner script's own refusal in a stderr text («remote-run-runner: no such job: x» → «no such job: x»): the last line, without the script's prefix. */
+function describeRunnerRefusal(stderr, fallback) {
+    const lastLine = stderr.split('\n').map((line) => line.trim()).filter((line) => line !== '').pop();
+    return lastLine === undefined ? fallback : lastLine.replace(/^remote-run-runner: /, '');
+}
+/** @description Create the client of `runner`. `script` and the spawn functions are injectable for the tests. */
+function createRunnerClient(runner, cacheDir, script = readRunnerScript()) {
+    const call = (subcommand, args, options = {}) => (0, ssh_1.runSshCommand)({
+        runner,
+        cacheDir,
+        remoteCommand: (0, ssh_1.buildRunnerScriptCommand)({ runner, scriptName: script.name, subcommand, args }),
+        input: options.input,
+        timeoutMs: options.timeoutMs ?? exports.shortCallTimeoutMs,
+        signal: options.signal,
+    });
+    let absoluteWorkDir = runner.workDir.startsWith('/') ? runner.workDir : null;
+    return {
+        runner,
+        cacheDir,
+        rsyncSshCommand: (0, ssh_1.buildRsyncSshCommand)(runner, cacheDir),
+        async getAbsoluteWorkDir() {
+            if (absoluteWorkDir === null) {
+                const resolved = await call('workdir', []);
+                const first = resolved.stdout.trim().split('\n')[0];
+                if (resolved.exitCode !== 0 || !first.startsWith('/'))
+                    throw new remoteRunError_1.RemoteRunError(`runner "${runner.name}": could not resolve its work dir ${runner.workDir} — ${describeSshFailure(resolved)}`);
+                absoluteWorkDir = first;
+            }
+            return absoluteWorkDir;
+        },
+        async ensureScript(signal) {
+            const exists = await (0, ssh_1.runSshCommand)({ runner, cacheDir, remoteCommand: (0, ssh_1.buildScriptExistsCommand)(runner, script.name), timeoutMs: scriptUploadTimeoutMs, signal });
+            if (exists.exitCode === 0)
+                return;
+            if ((0, ssh_1.checkIsConnectionLost)(exists.exitCode))
+                throw new remoteRunError_1.RunnerUnreachableError(runner.name, describeSshFailure(exists));
+            const upload = await (0, ssh_1.runSshCommand)({ runner, cacheDir, remoteCommand: (0, ssh_1.buildScriptUploadCommand)(runner, script.name), input: script.text, timeoutMs: scriptUploadTimeoutMs, signal });
+            if (upload.exitCode !== 0)
+                throw new remoteRunError_1.RemoteRunError(`could not put the runner script on "${runner.name}" (${runner.workDir}/bin) — ${describeSshFailure(upload)}`);
+        },
+        call,
+        async callOrThrow(subcommand, args, options) {
+            const result = await call(subcommand, args, options);
+            if (result.exitCode !== 0) {
+                const detail = result.stderr.trim() === '' ? describeSshFailure(result) : result.stderr.trim().split('\n').slice(-3).join(' / ');
+                throw new remoteRunError_1.RemoteRunError(`runner "${runner.name}": ${subcommand} failed — ${detail}`);
+            }
+            return result.stdout;
+        },
+        stream(subcommand, args) {
+            return (0, ssh_1.spawnSshStream)({ runner, cacheDir, remoteCommand: (0, ssh_1.buildRunnerScriptCommand)({ runner, scriptName: script.name, subcommand, args }) });
+        },
+    };
+}
+//# sourceMappingURL=runnerClient.js.map

package/dist/remoteRun/runnerClient.js.map

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

package/dist/remoteRun/runnerSummary.d.ts

@@ -0,0 +1,24 @@
+import { type RunnerCapability, type RunnerProbe } from './probe';
+import type { RunnerConfig } from './runnersConfig';
+/** @description The OS text of a runner as a short plain label: letters, digits and a few signs; no line break, no markup, 40 characters at most. */
+export declare function sanitizeOsLabel(reportedOs: string): string;
+/** @name RunnerSummary @description What the instructions say of one runner. */
+export interface RunnerSummary {
+    name: string;
+    osLabel: string;
+    /** The capabilities it had when last probed, in the order `--needs` lists them. */
+    capabilities: RunnerCapability[];
+    /** Paused from the hub, or on the runner itself when last seen: not used for new jobs. */
+    isPaused: boolean;
+}
+/** @description The summary of `runner`; `probe` is its last snapshot, if it has one. */
+export declare function summarizeRunner(runner: RunnerConfig, probe: RunnerProbe | null): RunnerSummary;
+/** @description `mac — macOS 15.1, android, playwright`; `box1 (paused) — Ubuntu 24.04`; just the name when nothing else is known. */
+export declare function formatRunnerSummaryLine(summary: RunnerSummary): string;
+/**
+ * @description The lines for the instructions of a session that connects now: one per runner of the catalog (hand-made first, then paired; a
+ * catalog with an error still gives the runners that last loaded). Empty = no runner, and remote-run is not mentioned. The snapshots are
+ * read from the cache `env` names — the bot's own, which the agents share (`XDG_CACHE_HOME` is on the tracker agents' allowlist).
+ */
+export declare function getRunnerSummaryLines(homeDir?: string, env?: NodeJS.ProcessEnv): string[];
+//# sourceMappingURL=runnerSummary.d.ts.map

package/dist/remoteRun/runnerSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerSummary.d.ts","sourceRoot":"","sources":["../../src/remoteRun/runnerSummary.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAiBpD,qJAAqJ;AACrJ,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,0FAA0F;IAC1F,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,aAAa,CAQ9F;AAED,sIAAsI;AACtI,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAqB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAIpH"}

package/dist/remoteRun/runnerSummary.js

@@ -0,0 +1,86 @@
+"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.sanitizeOsLabel = sanitizeOsLabel;
+exports.summarizeRunner = summarizeRunner;
+exports.formatRunnerSummaryLine = formatRunnerSummaryLine;
+exports.getRunnerSummaryLines = getRunnerSummaryLines;
+const os = __importStar(require("os"));
+const probe_1 = require("./probe");
+const runners_1 = require("./runners");
+const runnersCatalog_1 = require("./runnersCatalog");
+const ssh_1 = require("./ssh");
+/**
+ * @description The one line per runner that the bot MCP's instructions give an agent — `mac — macOS 15.1, android, playwright`: the name, the
+ * OS and what the runner could do when it was last probed (`remote-run`'s own snapshot, so a runner nobody has probed yet shows only its name
+ * and the OS it reported at pairing). It is a hint for choosing `--needs`, read once per connect; the live state — online, load, jobs — stays
+ * in `charness remote-run runners`, which the bullet tells the agent to look at first.
+ *
+ * What a runner machine reported (its OS name) goes into an agent's instructions, so it is reduced to a short plain label here: a runner is
+ * code the operator attached, not a voice the agent should obey.
+ */
+const maxOsLabelLength = 40;
+/** `/` stays: `/etc/os-release` names are «Debian GNU/Linux 12»; a slash cannot start a line, a bullet or markup. */
+const unsafeLabelCharacters = /[^A-Za-z0-9 ._+()/-]/g;
+/** @description The OS text of a runner as a short plain label: letters, digits and a few signs; no line break, no markup, 40 characters at most. */
+function sanitizeOsLabel(reportedOs) {
+    return reportedOs.replace(unsafeLabelCharacters, '').replace(/\s+/g, ' ').trim().slice(0, maxOsLabelLength).trim();
+}
+/** @description The summary of `runner`; `probe` is its last snapshot, if it has one. */
+function summarizeRunner(runner, probe) {
+    const probedOs = probe === null ? '' : [probe.osName, probe.osVersion].filter((part) => part !== '').join(' ');
+    return {
+        name: runner.name,
+        osLabel: sanitizeOsLabel(probedOs !== '' ? probedOs : (runner.paired?.os ?? '')),
+        capabilities: probe === null ? [] : probe_1.runnerCapabilities.filter((capability) => probe.capabilities[capability].isAvailable),
+        isPaused: runner.paired?.isPausedByHub === true || probe?.isPaused === true,
+    };
+}
+/** @description `mac — macOS 15.1, android, playwright`; `box1 (paused) — Ubuntu 24.04`; just the name when nothing else is known. */
+function formatRunnerSummaryLine(summary) {
+    const details = [...(summary.osLabel === '' ? [] : [summary.osLabel]), ...summary.capabilities];
+    return `${summary.name}${summary.isPaused ? ' (paused)' : ''}${details.length === 0 ? '' : ` — ${details.join(', ')}`}`;
+}
+/**
+ * @description The lines for the instructions of a session that connects now: one per runner of the catalog (hand-made first, then paired; a
+ * catalog with an error still gives the runners that last loaded). Empty = no runner, and remote-run is not mentioned. The snapshots are
+ * read from the cache `env` names — the bot's own, which the agents share (`XDG_CACHE_HOME` is on the tracker agents' allowlist).
+ */
+function getRunnerSummaryLines(homeDir = os.homedir(), env = process.env) {
+    const runners = (0, runnersCatalog_1.loadRunnersCatalog)(homeDir).config?.runners ?? [];
+    const cacheDir = (0, ssh_1.getRemoteRunCacheDir)(env, homeDir);
+    return runners.map((runner) => formatRunnerSummaryLine(summarizeRunner(runner, (0, runners_1.readLastProbe)(cacheDir, runner.name)?.probe ?? null)));
+}
+//# sourceMappingURL=runnerSummary.js.map

package/dist/remoteRun/runnerSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerSummary.js","sourceRoot":"","sources":["../../src/remoteRun/runnerSummary.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBA,0CAEC;AAaD,0CAQC;AAGD,0DAGC;AAOD,sDAIC;AA9DD,uCAAyB;AACzB,mCAAsF;AACtF,uCAA0C;AAC1C,qDAAsD;AAEtD,+BAA6C;AAE7C;;;;;;;;GAQG;AAEH,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,qHAAqH;AACrH,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAEtD,qJAAqJ;AACrJ,SAAgB,eAAe,CAAC,UAAkB;IAChD,OAAO,UAAU,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;AACrH,CAAC;AAYD,yFAAyF;AACzF,SAAgB,eAAe,CAAC,MAAoB,EAAE,KAAyB;IAC7E,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/G,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,eAAe,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAChF,YAAY,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,0BAAkB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC;QACzH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,IAAI,KAAK,EAAE,QAAQ,KAAK,IAAI;KAC5E,CAAC;AACJ,CAAC;AAED,sIAAsI;AACtI,SAAgB,uBAAuB,CAAC,OAAsB;IAC5D,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAChG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;AAC1H,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,UAAkB,EAAE,CAAC,OAAO,EAAE,EAAE,MAAyB,OAAO,CAAC,GAAG;IACxG,MAAM,OAAO,GAAG,IAAA,mCAAkB,EAAC,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC;IAClE,MAAM,QAAQ,GAAG,IAAA,0BAAoB,EAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,uBAAuB,CAAC,eAAe,CAAC,MAAM,EAAE,IAAA,uBAAa,EAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;AACxI,CAAC"}