charness 3.7.0 → 3.8.0

package/dist/runners/pairCode.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pairCodePrefix = void 0;
+exports.encodePairCode = encodePairCode;
+exports.decodePairCode = decodePairCode;
+const zod_1 = require("zod");
+const hubIds_1 = require("./hubIds");
+/**
+ * @description The pairing code: everything a runner needs to reach the hub ONCE — the address, the hub's ssh host key to pin, the
+ * account to log in as, a private key that is good for one `redeem` (and the package download), and the pairing's id. Text
+ * `cr1.<base64url of a JSON object>`; the `1` is the format version. It is a secret until it is used or has expired: it is never
+ * logged, and a decode error names a field, never a value.
+ */
+exports.pairCodePrefix = 'cr1.';
+const maxCodeLength = 4096;
+const privateKeyPattern = /^-----BEGIN OPENSSH PRIVATE KEY-----\n[A-Za-z0-9+/=\n]+\n-----END OPENSSH PRIVATE KEY-----\n?$/;
+const pairCodePayloadSchema = zod_1.z.strictObject({
+    host: hubIds_1.hubHostSchema,
+    port: hubIds_1.hubPortSchema,
+    user: hubIds_1.hubSshUserSchema,
+    hostKey: hubIds_1.hubHostKeySchema,
+    privateKey: zod_1.z.string().max(2048).regex(privateKeyPattern, 'must be an OpenSSH private key'),
+    pairId: hubIds_1.hubIdSchema,
+});
+function encodePairCode(payload) {
+    return `${exports.pairCodePrefix}${Buffer.from(JSON.stringify(pairCodePayloadSchema.parse(payload)), 'utf8').toString('base64url')}`;
+}
+/** @description The payload of `code`, or why it is not one (the reason never quotes the code). */
+function decodePairCode(code) {
+    if (!code.startsWith(exports.pairCodePrefix))
+        return { ok: false, error: `a pairing code starts with ${exports.pairCodePrefix}` };
+    if (code.length > maxCodeLength)
+        return { ok: false, error: 'the pairing code is too long' };
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(Buffer.from(code.slice(exports.pairCodePrefix.length), 'base64url').toString('utf8'));
+    }
+    catch {
+        return { ok: false, error: 'the pairing code is damaged (not a copy of the whole line?)' };
+    }
+    const parsed = pairCodePayloadSchema.safeParse(parsedJson);
+    if (parsed.success)
+        return { ok: true, payload: parsed.data };
+    return { ok: false, error: `the pairing code is damaged: ${parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; ')}` };
+}
+//# sourceMappingURL=pairCode.js.map

package/dist/runners/pairCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairCode.js","sourceRoot":"","sources":["../../src/runners/pairCode.ts"],"names":[],"mappings":";;;AA4BA,wCAEC;AAGD,wCAYC;AA7CD,6BAAwB;AACxB,qCAAyG;AAEzG;;;;;GAKG;AAEU,QAAA,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,iBAAiB,GAAG,gGAAgG,CAAC;AAE3H,MAAM,qBAAqB,GAAG,OAAC,CAAC,YAAY,CAAC;IAC3C,IAAI,EAAE,sBAAa;IACnB,IAAI,EAAE,sBAAa;IACnB,IAAI,EAAE,yBAAgB;IACtB,OAAO,EAAE,yBAAgB;IACzB,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,iBAAiB,EAAE,gCAAgC,CAAC;IAC3F,MAAM,EAAE,oBAAW;CACpB,CAAC,CAAC;AAOH,SAAgB,cAAc,CAAC,OAAwB;IACrD,OAAO,GAAG,sBAAc,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AAC/H,CAAC;AAED,mGAAmG;AACnG,SAAgB,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,sBAAc,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,8BAA8B,sBAAc,EAAE,EAAE,CAAC;IAClH,IAAI,IAAI,CAAC,MAAM,GAAG,aAAa;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC;IAC7F,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,sBAAc,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACxG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6DAA6D,EAAE,CAAC;IAC7F,CAAC;IACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gCAAgC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;AACvK,CAAC"}

package/dist/runners/pairingTiming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @description How long a pairing code works. In a module of its own so the headless CLI reads it without loading the bot.
+ *
+ * The test seam `CHARNESS_TEST_TIMINGS` (`testTimings.ts`) may only SHORTEN it (key `pairingLifetimeMs`, at least
+ * {@link pairingLifetimeMinMs}: sshd's `expiry-time` has a granularity of a second). 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.
+ */
+export declare const pairingLifetimeMinutes = 10;
+/** Production: a code works for ten minutes, once. */
+export declare const pairingLifetimeMs: number;
+/** sshd compares `expiry-time` in whole seconds: a shorter window would be rounding. */
+export declare const pairingLifetimeMinMs = 5000;
+/** @description The lifetime in force: the production one, or the seam's shorter `pairingLifetimeMs` when it is a whole number of ms within [min, production]. */
+export declare function readPairingLifetimeMs(env: NodeJS.ProcessEnv): number;
+/** @description «10 minutes», or «5 seconds» for a window shorter than a minute (only a test's). */
+export declare function formatLifetime(lifetimeMs: number): string;
+//# sourceMappingURL=pairingTiming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pairingTiming.d.ts","sourceRoot":"","sources":["../../src/runners/pairingTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,QAAuC,CAAC;AACtE,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAIzC,kKAAkK;AAClK,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAYpE;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/runners/pairingTiming.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * @description How long a pairing code works. In a module of its own so the headless CLI reads it without loading the bot.
+ *
+ * The test seam `CHARNESS_TEST_TIMINGS` (`testTimings.ts`) may only SHORTEN it (key `pairingLifetimeMs`, at least
+ * {@link pairingLifetimeMinMs}: sshd's `expiry-time` has a granularity of a second). 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.pairingLifetimeMinMs = exports.pairingLifetimeMs = exports.pairingLifetimeMinutes = void 0;
+exports.readPairingLifetimeMs = readPairingLifetimeMs;
+exports.formatLifetime = formatLifetime;
+const msPerMinute = 60 * 1000;
+exports.pairingLifetimeMinutes = 10;
+/** Production: a code works for ten minutes, once. */
+exports.pairingLifetimeMs = exports.pairingLifetimeMinutes * msPerMinute;
+/** sshd compares `expiry-time` in whole seconds: a shorter window would be rounding. */
+exports.pairingLifetimeMinMs = 5000;
+const testTimingsVariableName = 'CHARNESS_TEST_TIMINGS';
+/** @description The lifetime in force: the production one, or the seam's shorter `pairingLifetimeMs` when it is a whole number of ms within [min, production]. */
+function readPairingLifetimeMs(env) {
+    const rawTestTimings = env[testTimingsVariableName];
+    if (rawTestTimings === undefined || rawTestTimings.trim() === '')
+        return exports.pairingLifetimeMs;
+    let overrides;
+    try {
+        overrides = JSON.parse(rawTestTimings);
+    }
+    catch {
+        return exports.pairingLifetimeMs;
+    }
+    const overrideMs = overrides?.pairingLifetimeMs;
+    if (overrideMs === undefined || !Number.isInteger(overrideMs))
+        return exports.pairingLifetimeMs;
+    return overrideMs >= exports.pairingLifetimeMinMs && overrideMs <= exports.pairingLifetimeMs ? overrideMs : exports.pairingLifetimeMs;
+}
+/** @description «10 minutes», or «5 seconds» for a window shorter than a minute (only a test's). */
+function formatLifetime(lifetimeMs) {
+    return lifetimeMs >= msPerMinute ? `${Math.round(lifetimeMs / msPerMinute)} minutes` : `${Math.round(lifetimeMs / 1000)} seconds`;
+}
+//# sourceMappingURL=pairingTiming.js.map

package/dist/runners/pairingTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingTiming.js","sourceRoot":"","sources":["../../src/runners/pairingTiming.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAYH,sDAYC;AAGD,wCAEC;AA3BD,MAAM,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC;AACjB,QAAA,sBAAsB,GAAG,EAAE,CAAC;AACzC,sDAAsD;AACzC,QAAA,iBAAiB,GAAG,8BAAsB,GAAG,WAAW,CAAC;AACtE,wFAAwF;AAC3E,QAAA,oBAAoB,GAAG,IAAI,CAAC;AAEzC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAExD,kKAAkK;AAClK,SAAgB,qBAAqB,CAAC,GAAsB;IAC1D,MAAM,cAAc,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACpD,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,yBAAiB,CAAC;IAC3F,IAAI,SAAgD,CAAC;IACrD,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,yBAAiB,CAAC;IAC3B,CAAC;IACD,MAAM,UAAU,GAAG,SAAS,EAAE,iBAAiB,CAAC;IAChD,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC;QAAE,OAAO,yBAAiB,CAAC;IACxF,OAAO,UAAU,IAAI,4BAAoB,IAAI,UAAU,IAAI,yBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,yBAAiB,CAAC;AAChH,CAAC;AAED,oGAAoG;AACpG,SAAgB,cAAc,CAAC,UAAkB;IAC/C,OAAO,UAAU,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;AACpI,CAAC"}

package/dist/runners/runnerProxy.d.ts

@@ -0,0 +1,9 @@
+import type { Readable, Writable } from 'stream';
+export interface RunnerProxyIo {
+    stdin: Readable;
+    stdout: Writable;
+    stderr: Writable;
+}
+/** @description Join `io` to the socket; resolves with the exit code when either side ends. */
+export declare function runRunnerProxy(socketPath: string, io: RunnerProxyIo): Promise<number>;
+//# sourceMappingURL=runnerProxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnerProxy.d.ts","sourceRoot":"","sources":["../../src/runners/runnerProxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAWjD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBrF"}

package/dist/runners/runnerProxy.js

@@ -0,0 +1,67 @@
+"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.runRunnerProxy = runRunnerProxy;
+const net = __importStar(require("net"));
+/**
+ * @description `charness runner-proxy <socket>` — the `ProxyCommand` of the ssh calls to a paired runner: it joins ssh's stdin and
+ * stdout to the unix socket that the runner's gate listens on (`gateLink.ts`). When nothing listens, the runner is offline: the
+ * proxy says so on stderr, which ssh shows as the reason, and exits 255 — the status ssh itself uses for a failed connection, which
+ * remote-run already treats as «the connection was lost».
+ */
+const connectionFailedExitCode = 255;
+/** @description Join `io` to the socket; resolves with the exit code when either side ends. */
+function runRunnerProxy(socketPath, io) {
+    return new Promise((resolve) => {
+        const socket = net.connect(socketPath);
+        let isConnected = false;
+        socket.once('connect', () => {
+            isConnected = true;
+            io.stdin.pipe(socket);
+            socket.pipe(io.stdout, { end: false });
+        });
+        socket.once('error', () => {
+            if (!isConnected)
+                io.stderr.write('charness runner-proxy: the runner is not connected\n');
+            socket.destroy();
+        });
+        socket.once('close', () => {
+            io.stdin.unpipe(socket);
+            resolve(isConnected ? 0 : connectionFailedExitCode);
+        });
+        io.stdin.once('end', () => socket.end());
+    });
+}
+//# sourceMappingURL=runnerProxy.js.map

package/dist/runners/runnerProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerProxy.js","sourceRoot":"","sources":["../../src/runners/runnerProxy.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBA,wCAmBC;AAtCD,yCAA2B;AAG3B;;;;;GAKG;AAEH,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAQrC,+FAA+F;AAC/F,SAAgB,cAAc,CAAC,UAAkB,EAAE,EAAiB;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;YAC1B,WAAW,GAAG,IAAI,CAAC;YACnB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,IAAI,CAAC,WAAW;gBAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;YAC1F,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runners/runnerRemoval.d.ts

@@ -0,0 +1,21 @@
+import { runSshCommand } from '../remoteRun/ssh';
+import type { HubContext } from './hubPaths';
+import { type PairedRunner } from './hubRegistry';
+/** What became of the jobs on the removed runner: ended through the link; could not be ended from here; or the runner was offline. */
+export type RunnerJobsStop = 'stopped' | 'failed' | 'offline';
+export interface RunnerRemovalDeps {
+    isLinkOnline: (ctx: HubContext, runnerId: string) => Promise<boolean>;
+    runSsh: typeof runSshCommand;
+    cacheDir: string;
+    log: (line: string) => void;
+}
+/**
+ * @description Remove `nameOrId`: while it is still paired, pause it and stop its jobs through the link (when it is online); then drop it
+ * from the registry (its key line goes with it) and cut the link. `null` when no such runner is paired. A registry that cannot be
+ * written stops the call before the link is touched.
+ */
+export declare function removeRunnerAndEndItsWork(ctx: HubContext, nameOrId: string, nowMs: number, deps?: RunnerRemovalDeps): Promise<{
+    runner: PairedRunner;
+    jobs: RunnerJobsStop;
+} | null>;
+//# sourceMappingURL=runnerRemoval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnerRemoval.d.ts","sourceRoot":"","sources":["../../src/runners/runnerRemoval.ts"],"names":[],"mappings":"AACA,OAAO,EAAiE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEhH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAiBlE,sIAAsI;AACtI,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,EAAE,OAAO,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AA0CD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG,IAAI,CAAC,CAc1L"}

package/dist/runners/runnerRemoval.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeRunnerAndEndItsWork = removeRunnerAndEndItsWork;
+const pairedRunners_1 = require("../remoteRun/pairedRunners");
+const ssh_1 = require("../remoteRun/ssh");
+const hubPairing_1 = require("./hubPairing");
+const hubRegistry_1 = require("./hubRegistry");
+const linkControl_1 = require("./linkControl");
+/**
+ * @description Removing a runner from the hub, and ending the work the hub's agents left on it. Pueue outlives any link by design, so
+ * cutting the link leaves their background jobs running on a machine that is no longer theirs. When the runner is ONLINE the hub says so
+ * itself, over the link that is still open: it runs `pueue reset --force` there (the queue's private Pueue, found from the work dir the
+ * runner reported). That is certain — unlike the runner's own inference from a refused key, which a hub with a locked home folder or a
+ * wrong file mode produces too (see `runnerUtility/linkLoop.ts`) — and it works whatever the runner's version.
+ *
+ * The ORDER matters: the gate ends a link as soon as its runner has left `paired.json`, which would cut the reset off half-way, so the
+ * runner is paused (no new job is sent to it meanwhile) and its jobs are stopped while it is still paired; only then it is removed and
+ * its link cut.
+ */
+const stopJobsTimeoutMs = 20 * 1000;
+function createRemovalDeps() {
+    return {
+        isLinkOnline: async (ctx, runnerId) => (await (0, linkControl_1.getRunnerLinkStatus)(ctx.dir, runnerId)).isOnline,
+        runSsh: ssh_1.runSshCommand,
+        cacheDir: (0, ssh_1.getRemoteRunCacheDir)(),
+        log: (line) => { console.error(line); },
+    };
+}
+/** Is the runner's link up? `null` when that could not be read (logged): a runner nobody can tell about is not «offline». */
+async function checkIsLinkOnline(ctx, runner, deps) {
+    try {
+        return await deps.isLinkOnline(ctx, runner.id);
+    }
+    catch (error) {
+        deps.log(`runners: could not tell whether "${runner.name}" is online (${error instanceof Error ? error.message : 'unknown error'}); its jobs are not stopped from here`);
+        return null;
+    }
+}
+/** Reset the queue of a runner whose link is up. Never throws: a failure is logged and told as `failed`. */
+async function resetQueueOverLink(ctx, runner, deps) {
+    try {
+        const config = (0, pairedRunners_1.buildPairedRunnerConfig)(runner, { hubDir: ctx.dir, nodePath: ctx.nodePath, cliPath: ctx.cliPath });
+        if (config.pueue?.bin === undefined || config.pueue.config === undefined) {
+            deps.log(`runners: cannot stop the jobs of "${runner.name}" from here: its work folder does not follow the runner utility's layout`);
+            return 'failed';
+        }
+        (0, ssh_1.ensureRemoteRunCacheDir)(deps.cacheDir);
+        // No shared connection: this one call must not leave a master behind for the link that is about to be cut.
+        const noMaster = { ...config, sshOptions: ['-o', 'ControlMaster=no', ...(config.sshOptions ?? [])] };
+        const result = await deps.runSsh({ runner: noMaster, cacheDir: deps.cacheDir, remoteCommand: (0, ssh_1.joinShellWords)([config.pueue.bin, '--config', config.pueue.config, 'reset', '--force']), timeoutMs: stopJobsTimeoutMs });
+        if (result.exitCode === 0)
+            return 'stopped';
+        deps.log(`runners: the jobs of "${runner.name}" were not stopped (${result.isTimedOut ? 'no answer in time' : `exit ${result.exitCode ?? 'none'}`})`);
+        return 'failed';
+    }
+    catch (error) {
+        deps.log(`runners: could not stop the jobs of "${runner.name}" (${error instanceof Error ? error.message : 'unknown error'})`);
+        return 'failed';
+    }
+}
+/**
+ * @description Remove `nameOrId`: while it is still paired, pause it and stop its jobs through the link (when it is online); then drop it
+ * from the registry (its key line goes with it) and cut the link. `null` when no such runner is paired. A registry that cannot be
+ * written stops the call before the link is touched.
+ */
+async function removeRunnerAndEndItsWork(ctx, nameOrId, nowMs, deps) {
+    const resolvedDeps = deps ?? createRemovalDeps();
+    const found = (0, hubPairing_1.findPairedRunner)((0, hubRegistry_1.readPairedFile)(ctx.dir).runners, nameOrId);
+    if (found === undefined)
+        return null;
+    const isOnline = await checkIsLinkOnline(ctx, found, resolvedDeps);
+    let jobs = isOnline === null ? 'failed' : 'offline';
+    if (isOnline === true) {
+        // No agent is sent to it from now on; the reset below takes seconds.
+        await (0, hubPairing_1.setPairedRunnerPaused)(ctx, found.id, true).catch((error) => { resolvedDeps.log(`runners: could not pause "${found.name}" before stopping its jobs (${error instanceof Error ? error.message : 'unknown error'})`); });
+        jobs = await resetQueueOverLink(ctx, found, resolvedDeps);
+    }
+    const removed = await (0, hubPairing_1.removePairedRunner)(ctx, found.id, nowMs);
+    (0, linkControl_1.cutRunnerLink)(ctx.dir, found.id);
+    return removed === null ? null : { runner: removed, jobs };
+}
+//# sourceMappingURL=runnerRemoval.js.map

package/dist/runners/runnerRemoval.js.map

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

package/dist/runners/runnersCli.d.ts

@@ -0,0 +1,16 @@
+import type { CliIo } from '../remoteRun/output';
+import { type HostKeyScanner } from './hubAddress';
+import { type HubContext } from './hubPaths';
+export declare const runnersUsage = "Usage:\n  charness runners [ls]                       the machines paired as runners: online or not, OS, how they are kept running\n  charness runners pair --host <host[:port]> [--label <text>] [--wait]\n                                              make a pairing line (valid 10 minutes, single use) to run on the runner machine;\n                                              <host[:port]> is the address the runner dials to reach this machine's sshd;\n                                              --wait blocks until the line is used or expires\n  charness runners remove <name>              detach a runner: its key is deleted and its link cut\n  charness runners pause <name>               keep a runner attached but send it no jobs\n  charness runners resume <name>\n";
+/** @description What the CLI needs from outside; tests replace the scanner, the clock and the wait. */
+export interface RunnersCliDeps {
+    ctx: HubContext;
+    scanHostKey: HostKeyScanner;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    sshUser?: string;
+}
+export declare function createRunnersCliDeps(io: Pick<CliIo, 'homeDir'>): RunnersCliDeps;
+/** @description Run the command line (the words after `runners`); resolves with the exit code. */
+export declare function runRunnersCli(argv: readonly string[], io: CliIo, deps?: RunnersCliDeps): Promise<number>;
+//# sourceMappingURL=runnersCli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnersCli.d.ts","sourceRoot":"","sources":["../../src/runners/runnersCli.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAGjD,OAAO,EAAiD,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAkB/D,eAAO,MAAM,YAAY,2wBASxB,CAAC;AAEF,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,UAAU,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,cAAc,CAO/E;AAmHD,kGAAkG;AAClG,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,GAAE,cAAyC,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BxI"}

package/dist/runners/runnersCli.js

@@ -0,0 +1,214 @@
+"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.runnersUsage = void 0;
+exports.createRunnersCliDeps = createRunnersCliDeps;
+exports.runRunnersCli = runRunnersCli;
+const os = __importStar(require("os"));
+const bootstrapLine_1 = require("./bootstrapLine");
+const gateWrapper_1 = require("./gateWrapper");
+const hubAddress_1 = require("./hubAddress");
+const hubPaths_1 = require("./hubPaths");
+const hubPairing_1 = require("./hubPairing");
+const pairingTiming_1 = require("./pairingTiming");
+const hubRegistry_1 = require("./hubRegistry");
+const linkControl_1 = require("./linkControl");
+const runnerRemoval_1 = require("./runnerRemoval");
+const runnersList_1 = require("./runnersList");
+/**
+ * @description `charness runners [ls | pair | remove <name> | pause <name> | resume <name>]` — the headless twin of `/runners`, for an
+ * instance without Telegram (a Jira-only one) and for the flow tests. It works on the registry of the OS user
+ * (`~/.config/charness/runners/`), loads no env file and never touches `DATA_DIR`.
+ */
+const usageExitCode = 2;
+const failedExitCode = 1;
+const waitPollMs = 1000;
+exports.runnersUsage = `Usage:
+  charness runners [ls]                       the machines paired as runners: online or not, OS, how they are kept running
+  charness runners pair --host <host[:port]> [--label <text>] [--wait]
+                                              make a pairing line (valid 10 minutes, single use) to run on the runner machine;
+                                              <host[:port]> is the address the runner dials to reach this machine's sshd;
+                                              --wait blocks until the line is used or expires
+  charness runners remove <name>              detach a runner: its key is deleted and its link cut
+  charness runners pause <name>               keep a runner attached but send it no jobs
+  charness runners resume <name>
+`;
+function createRunnersCliDeps(io) {
+    return {
+        ctx: (0, hubPaths_1.createHubContext)({ homeDir: io.homeDir }),
+        scanHostKey: hubAddress_1.scanHostKey,
+        now: Date.now,
+        sleep: (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
+    };
+}
+function parsePairOptions(args) {
+    const options = { host: null, label: null, isWaiting: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--wait') {
+            options.isWaiting = true;
+        }
+        else if (argument === '--host' || argument === '--label') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return `${argument} needs a value`;
+            if (argument === '--host')
+                options.host = value;
+            else
+                options.label = value;
+            index += 1;
+        }
+        else {
+            return `unknown argument: ${argument}`;
+        }
+    }
+    return options;
+}
+async function runPairCommand(args, io, deps) {
+    const options = parsePairOptions(args);
+    if (typeof options === 'string' || options.host === null) {
+        io.stderr(`runners: ${typeof options === 'string' ? options : '--host <host[:port]> is required (the address runners dial to reach this machine over ssh)'}\n\n${exports.runnersUsage}`);
+        return usageExitCode;
+    }
+    const parsedAddress = (0, hubAddress_1.parseHubAddress)(options.host);
+    if (!parsedAddress.ok) {
+        io.stderr(`runners: ${parsedAddress.error}\n`);
+        return usageExitCode;
+    }
+    const check = await (0, hubAddress_1.checkHubAddress)(parsedAddress.address, deps.scanHostKey);
+    if (!check.ok) {
+        io.stderr(`runners: ${check.error}\n`);
+        return failedExitCode;
+    }
+    if (check.note !== null)
+        io.stderr(`runners: ${check.note}\n`);
+    (0, gateWrapper_1.ensureGateWrapper)(deps.ctx);
+    const pairing = await (0, hubPairing_1.createPairing)(deps.ctx, {
+        host: parsedAddress.address.host,
+        port: parsedAddress.address.port,
+        hostKey: check.hostKey,
+        label: options.label ?? os.hostname(),
+        nowMs: deps.now(),
+        lifetimeMs: (0, pairingTiming_1.readPairingLifetimeMs)(io.env),
+        sshUser: deps.sshUser,
+    });
+    io.stdout(`Pair a runner — valid ${(0, pairingTiming_1.formatLifetime)((0, pairingTiming_1.readPairingLifetimeMs)(io.env))}, single use.\n\n` +
+        `Run this on the runner machine, as the account that will run jobs\n` +
+        `(not your main account — it runs the agents' code):\n\n` +
+        `${(0, bootstrapLine_1.buildBootstrapLine)(pairing.payload)}\n\n` +
+        `Anyone with this line can attach a machine to this charness until it is used or expires.\n`);
+    return options.isWaiting ? waitForPairing(pairing.pairId, io, deps) : 0;
+}
+async function waitForPairing(pairId, io, deps) {
+    for (;;) {
+        const runner = (0, hubRegistry_1.readPairedFile)(deps.ctx.dir).runners.find((candidate) => candidate.pairId === pairId);
+        if (runner !== undefined) {
+            io.stdout(`Runner "${runner.name}" paired ${(0, runnersList_1.formatListTimestamp)(runner.pairedAtMs)}.\n`);
+            return 0;
+        }
+        const pairing = (0, hubRegistry_1.readPendingFile)(deps.ctx.dir).pending.find((candidate) => candidate.pairId === pairId);
+        if (pairing === undefined || pairing.expiresAtMs <= deps.now()) {
+            await (0, hubPairing_1.sweepExpiredPairings)(deps.ctx, deps.now());
+            io.stderr('runners: the pairing code expired unused.\n');
+            return failedExitCode;
+        }
+        await deps.sleep(waitPollMs);
+    }
+}
+async function runListCommand(io, deps) {
+    await (0, hubPairing_1.sweepExpiredPairings)(deps.ctx, deps.now());
+    const paired = (0, hubRegistry_1.readPairedFile)(deps.ctx.dir);
+    const entries = await Promise.all(paired.runners.map(async (runner) => ({ runner, status: await (0, linkControl_1.getRunnerLinkStatus)(deps.ctx.dir, runner.id) })));
+    io.stdout((0, runnersList_1.formatRunnerList)(entries, (0, hubRegistry_1.readPendingFile)(deps.ctx.dir).pending, deps.now()));
+    return 0;
+}
+async function runRemoveCommand(name, io, deps) {
+    const removal = await (0, runnerRemoval_1.removeRunnerAndEndItsWork)(deps.ctx, name, deps.now());
+    if (removal === null) {
+        io.stderr(`runners: no runner named "${name}"\n`);
+        return failedExitCode;
+    }
+    const jobsNote = {
+        stopped: 'the jobs it had running are stopped',
+        failed: 'the jobs it had running could not be stopped from here (it stops them itself once it finds out it was removed)',
+        offline: 'it is offline: it stops the jobs it had running itself once it finds out it was removed',
+    }[removal.jobs];
+    io.stdout(`Runner "${removal.runner.name}" removed: its key is deleted and its link cut; ${jobsNote}.\n`);
+    return 0;
+}
+async function runPauseCommand(name, isPaused, io, deps) {
+    const runner = (0, hubPairing_1.findPairedRunner)((0, hubRegistry_1.readPairedFile)(deps.ctx.dir).runners, name);
+    const updated = runner === undefined ? null : await (0, hubPairing_1.setPairedRunnerPaused)(deps.ctx, runner.id, isPaused);
+    if (updated === null) {
+        io.stderr(`runners: no runner named "${name}"\n`);
+        return failedExitCode;
+    }
+    io.stdout(`Runner "${updated.name}" ${isPaused ? 'paused: it gets no jobs until resumed' : 'resumed'}.\n`);
+    return 0;
+}
+/** @description Run the command line (the words after `runners`); resolves with the exit code. */
+async function runRunnersCli(argv, io, deps = createRunnersCliDeps(io)) {
+    const [command = 'ls', ...args] = argv;
+    try {
+        switch (command) {
+            case 'ls':
+                return await runListCommand(io, deps);
+            case 'pair':
+                return await runPairCommand(args, io, deps);
+            case 'remove':
+            case 'pause':
+            case 'resume': {
+                if (args.length !== 1) {
+                    io.stderr(`runners: ${command} needs exactly one runner name\n\n${exports.runnersUsage}`);
+                    return usageExitCode;
+                }
+                return command === 'remove' ? await runRemoveCommand(args[0], io, deps) : await runPauseCommand(args[0], command === 'pause', io, deps);
+            }
+            case '--help':
+            case '-h':
+            case 'help':
+                io.stdout(exports.runnersUsage);
+                return 0;
+            default:
+                io.stderr(`runners: unknown command: ${command}\n\n${exports.runnersUsage}`);
+                return usageExitCode;
+        }
+    }
+    catch (error) {
+        io.stderr(`runners: ${error instanceof hubRegistry_1.HubRegistryError ? error.message : `failed (${error instanceof Error ? error.name : 'unknown error'}: ${error instanceof Error ? error.message : ''})`}\n`);
+        return failedExitCode;
+    }
+}
+//# sourceMappingURL=runnersCli.js.map

package/dist/runners/runnersCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnersCli.js","sourceRoot":"","sources":["../../src/runners/runnersCli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,oDAOC;AAoHD,sCA8BC;AApMD,uCAAyB;AAEzB,mDAAqD;AACrD,+CAAkD;AAClD,6CAAkG;AAClG,yCAA+D;AAC/D,6CAA4G;AAC5G,mDAAwE;AACxE,+CAAkF;AAClF,+CAAoD;AACpD,mDAA4D;AAC5D,+CAAsE;AAEtE;;;;GAIG;AAEH,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,UAAU,GAAG,IAAI,CAAC;AAEX,QAAA,YAAY,GAAG;;;;;;;;;CAS3B,CAAC;AAWF,SAAgB,oBAAoB,CAAC,EAA0B;IAC7D,OAAO;QACL,GAAG,EAAE,IAAA,2BAAgB,EAAC,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC;QAC9C,WAAW,EAAX,wBAAW;QACX,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;KACtE,CAAC;AACJ,CAAC;AAQD,SAAS,gBAAgB,CAAC,IAAuB;IAC/C,MAAM,OAAO,GAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC3E,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;QAC3B,CAAC;aAAM,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,GAAG,QAAQ,gBAAgB,CAAC;YAC5D,IAAI,QAAQ,KAAK,QAAQ;gBAAE,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC;;gBAC3C,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;YAC3B,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,CAAC;YACN,OAAO,qBAAqB,QAAQ,EAAE,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,IAAuB,EAAE,EAAS,EAAE,IAAoB;IACpF,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACzD,EAAE,CAAC,MAAM,CAAC,YAAY,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,4FAA4F,OAAO,oBAAY,EAAE,CAAC,CAAC;QACjL,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,MAAM,aAAa,GAAG,IAAA,4BAAe,EAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;QACtB,EAAE,CAAC,MAAM,CAAC,YAAY,aAAa,CAAC,KAAK,IAAI,CAAC,CAAC;QAC/C,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,IAAA,4BAAe,EAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7E,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,EAAE,CAAC,MAAM,CAAC,YAAY,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;QAAE,EAAE,CAAC,MAAM,CAAC,YAAY,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;IAC/D,IAAA,+BAAiB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,IAAA,0BAAa,EAAC,IAAI,CAAC,GAAG,EAAE;QAC5C,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,IAAI;QAChC,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,IAAI;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,EAAE;QACrC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE;QACjB,UAAU,EAAE,IAAA,qCAAqB,EAAC,EAAE,CAAC,GAAG,CAAC;QACzC,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;IACH,EAAE,CAAC,MAAM,CACP,yBAAyB,IAAA,8BAAc,EAAC,IAAA,qCAAqB,EAAC,EAAE,CAAC,GAAG,CAAC,CAAC,mBAAmB;QACvF,qEAAqE;QACrE,yDAAyD;QACzD,GAAG,IAAA,kCAAkB,EAAC,OAAO,CAAC,OAAO,CAAC,MAAM;QAC5C,4FAA4F,CAC/F,CAAC;IACF,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,MAAc,EAAE,EAAS,EAAE,IAAoB;IAC3E,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,IAAA,4BAAc,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACrG,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,EAAE,CAAC,MAAM,CAAC,WAAW,MAAM,CAAC,IAAI,YAAY,IAAA,iCAAmB,EAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACzF,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,OAAO,GAAG,IAAA,6BAAe,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACvG,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAC/D,MAAM,IAAA,iCAAoB,EAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YACjD,EAAE,CAAC,MAAM,CAAC,6CAA6C,CAAC,CAAC;YACzD,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,EAAS,EAAE,IAAoB;IAC3D,MAAM,IAAA,iCAAoB,EAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAA,4BAAc,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAA,iCAAmB,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAClJ,EAAE,CAAC,MAAM,CAAC,IAAA,8BAAgB,EAAC,OAAO,EAAE,IAAA,6BAAe,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,EAAS,EAAE,IAAoB;IAC3E,MAAM,OAAO,GAAG,MAAM,IAAA,yCAAyB,EAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,EAAE,CAAC,MAAM,CAAC,6BAA6B,IAAI,KAAK,CAAC,CAAC;QAClD,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,QAAQ,GAAG;QACf,OAAO,EAAE,qCAAqC;QAC9C,MAAM,EAAE,gHAAgH;QACxH,OAAO,EAAE,yFAAyF;KACnG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChB,EAAE,CAAC,MAAM,CAAC,WAAW,OAAO,CAAC,MAAM,CAAC,IAAI,mDAAmD,QAAQ,KAAK,CAAC,CAAC;IAC1G,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,QAAiB,EAAE,EAAS,EAAE,IAAoB;IAC7F,MAAM,MAAM,GAAG,IAAA,6BAAgB,EAAC,IAAA,4BAAc,EAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAA,kCAAqB,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzG,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,EAAE,CAAC,MAAM,CAAC,6BAA6B,IAAI,KAAK,CAAC,CAAC;QAClD,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,WAAW,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC;IAC3G,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kGAAkG;AAC3F,KAAK,UAAU,aAAa,CAAC,IAAuB,EAAE,EAAS,EAAE,OAAuB,oBAAoB,CAAC,EAAE,CAAC;IACrH,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACvC,IAAI,CAAC;QACH,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,IAAI;gBACP,OAAO,MAAM,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACxC,KAAK,MAAM;gBACT,OAAO,MAAM,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;YAC9C,KAAK,QAAQ,CAAC;YACd,KAAK,OAAO,CAAC;YACb,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACtB,EAAE,CAAC,MAAM,CAAC,YAAY,OAAO,qCAAqC,oBAAY,EAAE,CAAC,CAAC;oBAClF,OAAO,aAAa,CAAC;gBACvB,CAAC;gBACD,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;YAC1I,CAAC;YACD,KAAK,QAAQ,CAAC;YACd,KAAK,IAAI,CAAC;YACV,KAAK,MAAM;gBACT,EAAE,CAAC,MAAM,CAAC,oBAAY,CAAC,CAAC;gBACxB,OAAO,CAAC,CAAC;YACX;gBACE,EAAE,CAAC,MAAM,CAAC,6BAA6B,OAAO,OAAO,oBAAY,EAAE,CAAC,CAAC;gBACrE,OAAO,aAAa,CAAC;QACzB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,YAAY,KAAK,YAAY,8BAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACnM,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/runners/runnersList.d.ts

@@ -0,0 +1,17 @@
+import type { RunnerLinkStatus } from './linkControl';
+import type { PairedRunner, PendingPairing, RunnerServiceKind } from './hubRegistry';
+/**
+ * @description The text of `charness runners ls`: one line per paired runner (name, online or offline since when, paused, OS, how it
+ * is kept running, version) and a line for each pairing code still open. Pure: the status is read by the caller.
+ */
+export declare const serviceKindLabels: Record<RunnerServiceKind, string>;
+export interface RunnerListEntry {
+    runner: PairedRunner;
+    status: RunnerLinkStatus;
+}
+/** @description `2026-11-01 14:05` in the zone of this process. */
+export declare function formatListTimestamp(epochMs: number): string;
+export declare function formatRunnerListLine(entry: RunnerListEntry): string;
+/** @description The whole `ls` output. */
+export declare function formatRunnerList(entries: readonly RunnerListEntry[], pending: readonly PendingPairing[], nowMs: number): string;
+//# sourceMappingURL=runnersList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnersList.d.ts","sourceRoot":"","sources":["../../src/runners/runnersList.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAErF;;;GAGG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAK/D,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI3D;AAOD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAWnE;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/H"}