charness 3.7.0 → 3.9.0

package/dist/runners/linkControl.js

@@ -0,0 +1,171 @@
+"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.readLinkState = readLinkState;
+exports.writeLinkState = writeLinkState;
+exports.probeSocket = probeSocket;
+exports.getRunnerLinkStatus = getRunnerLinkStatus;
+exports.checkIsGateProcessOf = checkIsGateProcessOf;
+exports.cutRunnerLink = cutRunnerLink;
+exports.sweepOrphanLinkRecords = sweepOrphanLinkRecords;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const hubPaths_1 = require("./hubPaths");
+const hubIds_1 = require("./hubIds");
+/**
+ * @description The hub's view of a runner's link: the gate that holds it writes `link/<id>.json` (its pid, since when, a heartbeat) and
+ * listens on `link/<id>.sock`. A runner is ONLINE when its socket accepts a connection; the json only says who holds the socket and
+ * when it was last seen. A removed runner's link is cut by deleting the socket (the gate notices within one check interval and
+ * leaves) and, when the recorded pid still is that runner's gate, by stopping it at once; its two link files go with it, and any left behind
+ * for a runner the registry does not know are swept by {@link sweepOrphanLinkRecords}.
+ */
+const stateFileMode = 0o600;
+const probeTimeoutMs = 1000;
+const linkStateSchema = zod_1.z.strictObject({
+    pid: zod_1.z.number().int().positive(),
+    sinceMs: zod_1.z.number().int().nonnegative(),
+    lastBeatMs: zod_1.z.number().int().nonnegative(),
+    /** Set by the gate when it leaves; `null` while it holds the link. */
+    endedAtMs: zod_1.z.number().int().nonnegative().nullable(),
+});
+function readLinkState(dir, runnerId) {
+    try {
+        const parsed = linkStateSchema.safeParse(JSON.parse(fs.readFileSync((0, hubPaths_1.getRunnerLinkPaths)(dir, runnerId).state, 'utf8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLinkState(dir, runnerId, state) {
+    fs.mkdirSync((0, hubPaths_1.getHubFilePaths)(dir).linkDir, { recursive: true, mode: 0o700 });
+    (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getRunnerLinkPaths)(dir, runnerId).state, linkStateSchema.parse(state), stateFileMode);
+}
+/** @description Does anything accept a connection on the unix socket `socketPath` right now? */
+function probeSocket(socketPath, timeoutMs = probeTimeoutMs) {
+    return new Promise((resolve) => {
+        const socket = net.connect(socketPath);
+        const settle = (isAccepted) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(isAccepted);
+        };
+        const timer = setTimeout(() => settle(false), timeoutMs);
+        socket.once('connect', () => settle(true));
+        socket.once('error', () => settle(false));
+    });
+}
+async function getRunnerLinkStatus(dir, runnerId) {
+    const state = readLinkState(dir, runnerId);
+    const isOnline = await probeSocket((0, hubPaths_1.getRunnerLinkPaths)(dir, runnerId).socket);
+    return {
+        isOnline,
+        sinceMs: isOnline ? (state?.sinceMs ?? null) : null,
+        lastSeenMs: state === null ? null : (state.endedAtMs ?? state.lastBeatMs),
+    };
+}
+/** @description Is `pid` a charness gate serving runner `runnerId`? (A pid in an old json may belong to anything by now.) */
+function checkIsGateProcessOf(pid, runnerId) {
+    const listing = (0, child_process_1.spawnSync)('ps', ['-p', pid.toString(), '-o', 'command='], { encoding: 'utf8', timeout: probeTimeoutMs * 5 });
+    return listing.status === 0 && listing.stdout.includes('runner-gate') && listing.stdout.includes(` runner ${runnerId}`);
+}
+/** @description Cut the link of a runner that was removed: no new connection reaches it, its gate leaves, and its link files are deleted. */
+function cutRunnerLink(dir, runnerId) {
+    const state = readLinkState(dir, runnerId);
+    const paths = (0, hubPaths_1.getRunnerLinkPaths)(dir, runnerId);
+    fs.rmSync(paths.socket, { force: true });
+    if (state !== null && state.endedAtMs === null && checkIsGateProcessOf(state.pid, runnerId)) {
+        try {
+            process.kill(state.pid, 'SIGTERM');
+        }
+        catch (error) {
+            if ((0, configDirFile_1.getCaughtErrnoCode)(error) !== 'ESRCH')
+                throw error;
+        }
+    }
+    // Nobody reads the status of a runner that is gone, and a gate that leaves because of the removal writes none (`gateLink.ts`).
+    fs.rmSync(paths.state, { force: true });
+}
+const linkRecordExtensions = ['json', 'sock'];
+/** @description The runner id a link file belongs to (`<id>.json`, `<id>.sock`); `null` for anything else in the folder (a temp file of an atomic write, a gate's pending socket). */
+function getLinkRecordRunnerId(fileName) {
+    const [runnerId, extension, ...rest] = fileName.split('.');
+    return hubIds_1.hubIdPattern.test(runnerId) && linkRecordExtensions.includes(extension) && rest.length === 0 ? runnerId : null;
+}
+/**
+ * @description Delete the link files (`<id>.json`, `<id>.sock`) of every runner that is not in `registeredRunnerIds`: a removal that was cut
+ * short, a gate that wrote its status after the removal, a runner dropped from the registry by hand. Records of a runner whose gate is still
+ * running are kept — it is on its way out, and {@link cutRunnerLink} still needs the pid to stop it.
+ *
+ * Best effort, and it NEVER throws: the registry operation that calls it has already written its files, and a folder that cannot be listed
+ * or a file that cannot be deleted is only leftover clutter, tried again by the next operation. What went wrong is handed to `onProblem`,
+ * which the caller must give (a sweep that cannot say what failed would hide exactly what it exists to report); a missing folder is not a
+ * problem: nothing was ever linked. Returns the names deleted.
+ */
+function sweepOrphanLinkRecords(dir, registeredRunnerIds, onProblem) {
+    const linkDir = (0, hubPaths_1.getHubFilePaths)(dir).linkDir;
+    let names;
+    try {
+        names = fs.readdirSync(linkDir);
+    }
+    catch (error) {
+        const code = (0, configDirFile_1.getCaughtErrnoCode)(error);
+        if (code !== 'ENOENT')
+            onProblem(`the link folder could not be listed (${code}); leftover link files stay until it can be`);
+        return [];
+    }
+    const deleted = [];
+    for (const name of names) {
+        const runnerId = getLinkRecordRunnerId(name);
+        if (runnerId === null || registeredRunnerIds.includes(runnerId))
+            continue;
+        const state = readLinkState(dir, runnerId);
+        if (state !== null && state.endedAtMs === null && checkIsGateProcessOf(state.pid, runnerId))
+            continue;
+        try {
+            fs.rmSync(path.join(linkDir, name), { force: true });
+            deleted.push(name);
+        }
+        catch (error) {
+            onProblem(`the leftover link file ${name} could not be deleted (${(0, configDirFile_1.getCaughtErrnoCode)(error)})`);
+        }
+    }
+    return deleted;
+}
+//# sourceMappingURL=linkControl.js.map

package/dist/runners/linkControl.js.map

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

package/dist/runners/pairCode.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/**
+ * @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.
+ */
+export declare const pairCodePrefix = "cr1.";
+declare const pairCodePayloadSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodNumber;
+    user: z.ZodString;
+    hostKey: z.ZodString;
+    privateKey: z.ZodString;
+    pairId: z.ZodString;
+}, z.core.$strict>;
+/** @name PairCodePayload @description What a pairing code carries. */
+export type PairCodePayload = z.infer<typeof pairCodePayloadSchema>;
+export type PairCodeDecoding = {
+    ok: true;
+    payload: PairCodePayload;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function encodePairCode(payload: PairCodePayload): string;
+/** @description The payload of `code`, or why it is not one (the reason never quotes the code). */
+export declare function decodePairCode(code: string): PairCodeDecoding;
+export {};
+//# sourceMappingURL=pairCode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pairCode.d.ts","sourceRoot":"","sources":["../../src/runners/pairCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,eAAO,MAAM,cAAc,SAAS,CAAC;AAIrC,QAAA,MAAM,qBAAqB;;;;;;;kBAOzB,CAAC;AAEH,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErG,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAE/D;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAY7D"}

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/removalTiming.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @description How long the hub must have been refusing a runner's key, without ever saying «this runner is not paired», before the runner takes
+ * the refusal for a removal worth killing its jobs for. A refused key alone is also what a hub with a locked home folder, a changed file mode or an
+ * edited sshd setting looks like, and those last hours (a night, until someone unlocks the volume); killing a long run for them is the
+ * wrong mistake. A hub that removes an ONLINE runner stops its jobs itself over the link (`runners/runnerRemoval.ts`), and a hub that can
+ * answer says so (`identity`), so this only covers a machine that was off when it was removed.
+ *
+ * The one source of the delay: the runner's link loop (`runnerUtility/linkLoop.ts`) waits this long, and the texts that tell the operator what
+ * a removal of an offline machine leaves behind (`/runners`) name the same number of hours.
+ */
+export declare const unconfirmedRemovalStopAfterHours = 12;
+export declare const unconfirmedRemovalStopAfterMs: number;
+//# sourceMappingURL=removalTiming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"removalTiming.d.ts","sourceRoot":"","sources":["../../src/runners/removalTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD,eAAO,MAAM,6BAA6B,QAA+C,CAAC"}

package/dist/runners/removalTiming.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @description How long the hub must have been refusing a runner's key, without ever saying «this runner is not paired», before the runner takes
+ * the refusal for a removal worth killing its jobs for. A refused key alone is also what a hub with a locked home folder, a changed file mode or an
+ * edited sshd setting looks like, and those last hours (a night, until someone unlocks the volume); killing a long run for them is the
+ * wrong mistake. A hub that removes an ONLINE runner stops its jobs itself over the link (`runners/runnerRemoval.ts`), and a hub that can
+ * answer says so (`identity`), so this only covers a machine that was off when it was removed.
+ *
+ * The one source of the delay: the runner's link loop (`runnerUtility/linkLoop.ts`) waits this long, and the texts that tell the operator what
+ * a removal of an offline machine leaves behind (`/runners`) name the same number of hours.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unconfirmedRemovalStopAfterMs = exports.unconfirmedRemovalStopAfterHours = void 0;
+const msPerHour = 60 * 60 * 1000;
+exports.unconfirmedRemovalStopAfterHours = 12;
+exports.unconfirmedRemovalStopAfterMs = exports.unconfirmedRemovalStopAfterHours * msPerHour;
+//# sourceMappingURL=removalTiming.js.map

package/dist/runners/removalTiming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"removalTiming.js","sourceRoot":"","sources":["../../src/runners/removalTiming.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,MAAM,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEpB,QAAA,gCAAgC,GAAG,EAAE,CAAC;AAEtC,QAAA,6BAA6B,GAAG,wCAAgC,GAAG,SAAS,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;AAGhH,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;AAmDD;;;;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,CAe1L"}

package/dist/runners/runnerRemoval.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeRunnerAndEndItsWork = removeRunnerAndEndItsWork;
+const pairedRunners_1 = require("../remoteRun/pairedRunners");
+const ssh_1 = require("../remoteRun/ssh");
+const runners_1 = require("../remoteRun/runners");
+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';
+    }
+}
+/** The removed runner's last saved report goes with it: the name is free again, and the next machine to get it must not start with this one's report. Never fails the removal. */
+function forgetLastReport(runner, deps) {
+    try {
+        (0, runners_1.removeLastProbe)(deps.cacheDir, runner.name);
+    }
+    catch (error) {
+        deps.log(`runners: could not delete the saved report of "${runner.name}" (${error instanceof Error ? error.message : 'unknown error'}); a machine paired under that name later ignores it anyway`);
+    }
+}
+/**
+ * @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);
+    if (removed !== null)
+        forgetLastReport(removed, resolvedDeps);
+    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/runnerServiceKind.d.ts

@@ -0,0 +1,10 @@
+import type { RunnerProbe } from '../remoteRun/probe';
+import type { PairedRunner, RunnerServiceKind } from './hubRegistry';
+/**
+ * @description How a runner is kept running as it is NOW. What the machine reported in its latest probe comes first (the live one while it is
+ * online, the last snapshot for a machine that is off): the registry holds only what the runner said when it was paired — «run by hand», since
+ * `service install` comes after — and never learns of an install, an uninstall or a move to a system service. The registry's own word stands
+ * where the probe has none (never probed, or a runner too old to report it). The one rule behind `/runners` and `charness runners ls`.
+ */
+export declare function getCurrentServiceKind(runner: PairedRunner, probe: RunnerProbe | null): RunnerServiceKind;
+//# sourceMappingURL=runnerServiceKind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runnerServiceKind.d.ts","sourceRoot":"","sources":["../../src/runners/runnerServiceKind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,iBAAiB,CAExG"}

package/dist/runners/runnerServiceKind.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentServiceKind = getCurrentServiceKind;
+/**
+ * @description How a runner is kept running as it is NOW. What the machine reported in its latest probe comes first (the live one while it is
+ * online, the last snapshot for a machine that is off): the registry holds only what the runner said when it was paired — «run by hand», since
+ * `service install` comes after — and never learns of an install, an uninstall or a move to a system service. The registry's own word stands
+ * where the probe has none (never probed, or a runner too old to report it). The one rule behind `/runners` and `charness runners ls`.
+ */
+function getCurrentServiceKind(runner, probe) {
+    return probe?.serviceKind ?? runner.serviceKind;
+}
+//# sourceMappingURL=runnerServiceKind.js.map