charness 3.7.0 → 3.8.0

package/dist/runners/hubPaths.js

@@ -0,0 +1,94 @@
+"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.getHandMadeRunnersPath = getHandMadeRunnersPath;
+exports.createHubContext = createHubContext;
+exports.getHubFilePaths = getHubFilePaths;
+exports.getRunnerLinkPaths = getRunnerLinkPaths;
+exports.getRunnerHostAlias = getRunnerHostAlias;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+/**
+ * @description Where the hub keeps what paired runners need. ONE folder per OS user — `~/.config/charness/runners/`, beside the
+ * hand-made `runners.json` — and every `authorized_keys` line NAMES it (`gate --dir <dir>`), so nothing the gate does depends on
+ * `$HOME`, `DATA_DIR` or which instance runs it: any charness instance of the user, the bot and the CLI alike, shares one registry.
+ */
+const runnersDirName = 'runners';
+const sshDirName = '.ssh';
+const authorizedKeysFileName = 'authorized_keys';
+const cliFileName = 'cli.js';
+/** @description The hand-made `runners.json` that sits beside the registry folder (see {@link createHubContext}). */
+function getHandMadeRunnersPath(dir) {
+    return path.join(path.dirname(dir), 'runners.json');
+}
+/** @description `dist/cli.js` of the running charness: this file is `dist/runners/hubPaths.js`. */
+function getOwnCliPath() {
+    return path.resolve(__dirname, '..', cliFileName);
+}
+/** @description The context of the real machine for `homeDir`; every field can be overridden. */
+function createHubContext(overrides = {}) {
+    const homeDir = overrides.homeDir ?? os.homedir();
+    const cliPath = overrides.cliPath ?? getOwnCliPath();
+    return {
+        dir: overrides.dir ?? path.join(path.dirname((0, runnersConfig_1.getRunnersConfigPath)(homeDir)), runnersDirName),
+        authorizedKeysPath: overrides.authorizedKeysPath ?? path.join(homeDir, sshDirName, authorizedKeysFileName),
+        nodePath: overrides.nodePath ?? process.execPath,
+        cliPath,
+        packageRoot: overrides.packageRoot ?? path.resolve(path.dirname(cliPath), '..'),
+    };
+}
+function getHubFilePaths(dir) {
+    return {
+        paired: path.join(dir, 'paired.json'),
+        pending: path.join(dir, 'pending.json'),
+        hubKey: path.join(dir, 'hub_ed25519'),
+        hubPublicKey: path.join(dir, 'hub_ed25519.pub'),
+        knownHosts: path.join(dir, 'known_hosts'),
+        gate: path.join(dir, 'gate'),
+        linkDir: path.join(dir, 'link'),
+        packageDir: path.join(dir, 'package'),
+    };
+}
+/** @description The socket the gate of runner `runnerId` listens on, and the file that says who holds it. */
+function getRunnerLinkPaths(dir, runnerId) {
+    const linkDir = getHubFilePaths(dir).linkDir;
+    return { socket: path.join(linkDir, `${runnerId}.sock`), state: path.join(linkDir, `${runnerId}.json`) };
+}
+/** @description The host alias of a runner in the hub's `known_hosts` (and the `HostKeyAlias` of the ssh calls to it). */
+function getRunnerHostAlias(runnerId) {
+    return `charness-runner-${runnerId}`;
+}
+//# sourceMappingURL=hubPaths.js.map

package/dist/runners/hubPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubPaths.js","sourceRoot":"","sources":["../../src/runners/hubPaths.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,wDAEC;AAaD,4CAUC;AAED,0CAWC;AAGD,gDAGC;AAGD,gDAEC;AAzFD,uCAAyB;AACzB,2CAA6B;AAC7B,8DAAkE;AAElE;;;;GAIG;AAEH,MAAM,cAAc,GAAG,SAAS,CAAC;AACjC,MAAM,UAAU,GAAG,MAAM,CAAC;AAC1B,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AACjD,MAAM,WAAW,GAAG,QAAQ,CAAC;AA0B7B,qHAAqH;AACrH,SAAgB,sBAAsB,CAAC,GAAW;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;AACtD,CAAC;AAOD,mGAAmG;AACnG,SAAS,aAAa;IACpB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,iGAAiG;AACjG,SAAgB,gBAAgB,CAAC,YAAwD,EAAE;IACzF,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,aAAa,EAAE,CAAC;IACrD,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAA,oCAAoB,EAAC,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC;QAC5F,kBAAkB,EAAE,SAAS,CAAC,kBAAkB,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,sBAAsB,CAAC;QAC1G,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;QAChD,OAAO;QACP,WAAW,EAAE,SAAS,CAAC,WAAW,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,SAAgB,eAAe,CAAC,GAAW;IACzC,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC;QACrC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC;QACvC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC;QACrC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC;QAC/C,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC;QACzC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;QAC5B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;QAC/B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,6GAA6G;AAC7G,SAAgB,kBAAkB,CAAC,GAAW,EAAE,QAAgB;IAC9D,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;IAC7C,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,OAAO,CAAC,EAAE,CAAC;AAC3G,CAAC;AAED,0HAA0H;AAC1H,SAAgB,kBAAkB,CAAC,QAAgB;IACjD,OAAO,mBAAmB,QAAQ,EAAE,CAAC;AACvC,CAAC"}

package/dist/runners/hubRegistry.d.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { type HubContext } from './hubPaths';
+/** @description How the runner utility says it is kept running (reported at pairing). */
+export declare const runnerServiceKinds: readonly ["foreground", "user-service", "system-service", "unknown"];
+export type RunnerServiceKind = (typeof runnerServiceKinds)[number];
+declare const pairedRunnerSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    publicKey: z.ZodString;
+    keyFingerprint: z.ZodString;
+    hostKey: z.ZodString;
+    workDir: z.ZodString;
+    os: z.ZodString;
+    arch: z.ZodString;
+    version: z.ZodString;
+    serviceKind: z.ZodEnum<{
+        unknown: "unknown";
+        foreground: "foreground";
+        "user-service": "user-service";
+        "system-service": "system-service";
+    }>;
+    pairedAtMs: z.ZodNumber;
+    pairId: z.ZodString;
+    label: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    isPaused: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const pairedFileSchema: z.ZodObject<{
+    rev: z.ZodNumber;
+    runners: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        publicKey: z.ZodString;
+        keyFingerprint: z.ZodString;
+        hostKey: z.ZodString;
+        workDir: z.ZodString;
+        os: z.ZodString;
+        arch: z.ZodString;
+        version: z.ZodString;
+        serviceKind: z.ZodEnum<{
+            unknown: "unknown";
+            foreground: "foreground";
+            "user-service": "user-service";
+            "system-service": "system-service";
+        }>;
+        pairedAtMs: z.ZodNumber;
+        pairId: z.ZodString;
+        label: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        isPaused: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const pendingPairingSchema: z.ZodObject<{
+    pairId: z.ZodString;
+    publicKey: z.ZodString;
+    keyFingerprint: z.ZodString;
+    expiresAtMs: z.ZodNumber;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    label: z.ZodString;
+    messageRef: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+declare const pendingFileSchema: z.ZodObject<{
+    pending: z.ZodArray<z.ZodObject<{
+        pairId: z.ZodString;
+        publicKey: z.ZodString;
+        keyFingerprint: z.ZodString;
+        expiresAtMs: z.ZodNumber;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        label: z.ZodString;
+        messageRef: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** @name PairedRunner @description One attached machine. */
+export type PairedRunner = z.infer<typeof pairedRunnerSchema>;
+/** @name PairedFile @description `paired.json`. */
+export type PairedFile = z.infer<typeof pairedFileSchema>;
+/** @name PendingPairing @description One pairing code that is out. */
+export type PendingPairing = z.infer<typeof pendingPairingSchema>;
+/** @name PendingFile @description `pending.json`. */
+export type PendingFile = z.infer<typeof pendingFileSchema>;
+export declare class HubRegistryError extends Error {
+    constructor(message: string);
+}
+/** @description The registry files were written but a file derived from them could not be; the next locked operation repairs it. */
+export declare class HubDerivedFilesError extends HubRegistryError {
+    constructor(fileName: string, errnoCode: string);
+}
+/** @description `paired.json` right now (missing = nobody paired). */
+export declare function readPairedFile(dir: string): PairedFile;
+/** @description `pending.json` right now (missing = no code out). */
+export declare function readPendingFile(dir: string): PendingFile;
+/** @description Write `paired.json`; the registry lock must be held. */
+export declare function writePairedFile(dir: string, file: PairedFile): void;
+/** @description Write `pending.json`; the registry lock must be held. */
+export declare function writePendingFile(dir: string, file: PendingFile): void;
+/** @description The `known_hosts` text for the ssh calls through the links: one line per runner, under its alias. */
+export declare function renderKnownHosts(runners: readonly PairedRunner[]): string;
+/** @description The lines of the managed `authorized_keys` block: every pairing code still open, then every paired runner. */
+export declare function renderManagedBlockLines(ctx: HubContext, pending: readonly PendingPairing[], runners: readonly PairedRunner[], nowMs: number): string[];
+/**
+ * @description Bring the derived files in line with the two registry files: `known_hosts` and the `authorized_keys` block, each written
+ * only when it differs. The registry lock must be held. The block goes LAST, so a key is never allowed before the files its gate reads
+ * are in place. The registry files are authoritative and are written BEFORE this runs; a failure here is reported as
+ * {@link HubDerivedFilesError} and mends itself, because every locked operation ends with this same call.
+ */
+export declare function syncDerivedHubFiles(ctx: HubContext, pending: PendingFile, paired: PairedFile, nowMs: number): void;
+export {};
+//# sourceMappingURL=hubRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubRegistry.d.ts","sourceRoot":"","sources":["../../src/runners/hubRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAqBlF,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,sEAAuE,CAAC;AACvG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;kBAsBtB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;kBAI3B,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;;;;;;;kBAYxB,CAAC;AAEH,QAAA,MAAM,iBAAiB;;;;;;;;;;;kBAA6D,CAAC;AAErF,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,oIAAoI;AACpI,qBAAa,oBAAqB,SAAQ,gBAAgB;gBAC5C,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAIhD;AAqBD,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAEtD;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAExD;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAGnE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAGrE;AAED,qHAAqH;AACrH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAEzE;AAED,8HAA8H;AAC9H,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtJ;AAUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAalH"}

package/dist/runners/hubRegistry.js

@@ -0,0 +1,210 @@
+"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.HubDerivedFilesError = exports.HubRegistryError = exports.pairedFileSchema = exports.runnerServiceKinds = void 0;
+exports.readPairedFile = readPairedFile;
+exports.readPendingFile = readPendingFile;
+exports.writePairedFile = writePairedFile;
+exports.writePendingFile = writePendingFile;
+exports.renderKnownHosts = renderKnownHosts;
+exports.renderManagedBlockLines = renderManagedBlockLines;
+exports.syncDerivedHubFiles = syncDerivedHubFiles;
+const fs = __importStar(require("fs"));
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+const authorizedKeys_1 = require("./authorizedKeys");
+const hubIds_1 = require("./hubIds");
+const hubPaths_1 = require("./hubPaths");
+const hubLock_1 = require("./hubLock");
+const configDirFile_2 = require("../configDirFile");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The hub's two registry files and what is derived from them. `paired.json` is the machines that are attached,
+ * `pending.json` the pairing codes that are out. Both are read freely (every write is a rename, a reader sees a whole file) and
+ * written only under the registry lock (`hubLock.ts`). `known_hosts` (the runners' host keys, for the ssh calls through the link)
+ * and the managed `authorized_keys` block are DERIVED from the two on every change — never edited on their own.
+ *
+ * A file that does not parse or validate stops the caller with the problem named (field and rule, no values): a registry that is
+ * silently treated as empty would be rewritten empty and lose every pairing.
+ */
+const registryFileMode = 0o600;
+const knownHostsMode = 0o644;
+const maxTextLength = 200;
+const publicKeySchema = zod_1.z.string().refine(sshKeys_1.checkIsEd25519PublicKey, 'must be an ed25519 public key (type and key, no comment)');
+/** @description How the runner utility says it is kept running (reported at pairing). */
+exports.runnerServiceKinds = ['foreground', 'user-service', 'system-service', 'unknown'];
+const pairedRunnerSchema = zod_1.z.strictObject({
+    id: hubIds_1.hubIdSchema,
+    name: zod_1.z.string().regex(runnersConfig_1.runnerNamePattern, 'must be lowercase letters, digits and single dashes').max(40),
+    /** The runner's own client key: what its `authorized_keys` line holds. */
+    publicKey: publicKeySchema,
+    keyFingerprint: zod_1.z.string().max(maxTextLength),
+    /** The host key of the runner's built-in ssh server: pinned by the gate and by `known_hosts`. */
+    hostKey: publicKeySchema,
+    workDir: runnersConfig_1.runnerWorkDirSchema,
+    os: zod_1.z.string().max(maxTextLength),
+    arch: zod_1.z.string().max(maxTextLength),
+    version: zod_1.z.string().max(maxTextLength),
+    serviceKind: zod_1.z.enum(exports.runnerServiceKinds),
+    pairedAtMs: zod_1.z.number().int().nonnegative(),
+    /** The pairing that made it: how the instance that offered the code finds out that it was used, and what makes a retry of `redeem` idempotent. */
+    pairId: hubIds_1.hubIdSchema,
+    /** What the runner was told about this hub (kept so a retried `redeem` is answered the same way after the pending entry is gone). */
+    label: zod_1.z.string().min(1).max(maxTextLength),
+    host: hubIds_1.hubHostSchema,
+    port: hubIds_1.hubPortSchema,
+    /** Set from the hub: the runner stays attached, but no job is sent to it. */
+    isPaused: zod_1.z.boolean(),
+});
+exports.pairedFileSchema = zod_1.z.strictObject({
+    /** Counts every change: a keyboard built from one revision never acts on a later list. */
+    rev: zod_1.z.number().int().nonnegative(),
+    runners: zod_1.z.array(pairedRunnerSchema),
+});
+const pendingPairingSchema = zod_1.z.strictObject({
+    pairId: hubIds_1.hubIdSchema,
+    /** The temporary key's PUBLIC half (the private half is in the code only). */
+    publicKey: publicKeySchema,
+    keyFingerprint: zod_1.z.string().max(maxTextLength),
+    expiresAtMs: zod_1.z.number().int().nonnegative(),
+    host: hubIds_1.hubHostSchema,
+    port: hubIds_1.hubPortSchema,
+    /** Whose charness it is, as the runner shows it (`@ExampleBot`, a host name). */
+    label: zod_1.z.string().min(1).max(maxTextLength),
+    /** The message the offering instance edits when the code is used or expires (opaque to the hub); `null` for the CLI. */
+    messageRef: zod_1.z.string().max(maxTextLength).nullable(),
+});
+const pendingFileSchema = zod_1.z.strictObject({ pending: zod_1.z.array(pendingPairingSchema) });
+class HubRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HubRegistryError';
+    }
+}
+exports.HubRegistryError = HubRegistryError;
+/** @description The registry files were written but a file derived from them could not be; the next locked operation repairs it. */
+class HubDerivedFilesError extends HubRegistryError {
+    constructor(fileName, errnoCode) {
+        super(`the registry was updated but ${fileName} could not be written (${errnoCode}); the next runners command repairs it`);
+        this.name = 'HubDerivedFilesError';
+    }
+}
+exports.HubDerivedFilesError = HubDerivedFilesError;
+function readRegistryFile(filePath, fileName, schema, createEmpty) {
+    let text;
+    try {
+        text = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return createEmpty();
+        throw new HubRegistryError(`${fileName} could not be read`);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(text);
+    }
+    catch {
+        throw new HubRegistryError(`${fileName} is not valid JSON; fix or remove it by hand (nothing was changed)`);
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (parsed.success)
+        return parsed.data;
+    throw new HubRegistryError(`${fileName} is invalid: ${parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; ')}`);
+}
+/** @description `paired.json` right now (missing = nobody paired). */
+function readPairedFile(dir) {
+    return readRegistryFile((0, hubPaths_1.getHubFilePaths)(dir).paired, 'paired.json', exports.pairedFileSchema, () => ({ rev: 0, runners: [] }));
+}
+/** @description `pending.json` right now (missing = no code out). */
+function readPendingFile(dir) {
+    return readRegistryFile((0, hubPaths_1.getHubFilePaths)(dir).pending, 'pending.json', pendingFileSchema, () => ({ pending: [] }));
+}
+/** @description Write `paired.json`; the registry lock must be held. */
+function writePairedFile(dir, file) {
+    (0, hubLock_1.ensureHubDir)(dir);
+    (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getHubFilePaths)(dir).paired, exports.pairedFileSchema.parse(file), registryFileMode);
+}
+/** @description Write `pending.json`; the registry lock must be held. */
+function writePendingFile(dir, file) {
+    (0, hubLock_1.ensureHubDir)(dir);
+    (0, configDirFile_1.writeJsonFileAtomically)((0, hubPaths_1.getHubFilePaths)(dir).pending, pendingFileSchema.parse(file), registryFileMode);
+}
+/** @description The `known_hosts` text for the ssh calls through the links: one line per runner, under its alias. */
+function renderKnownHosts(runners) {
+    return runners.map((runner) => `${(0, hubPaths_1.getRunnerHostAlias)(runner.id)} ${runner.hostKey}\n`).join('');
+}
+/** @description The lines of the managed `authorized_keys` block: every pairing code still open, then every paired runner. */
+function renderManagedBlockLines(ctx, pending, runners, nowMs) {
+    const gatePath = (0, hubPaths_1.getHubFilePaths)(ctx.dir).gate;
+    const common = { gatePath, keysPath: ctx.authorizedKeysPath, dir: ctx.dir };
+    return [
+        ...pending.filter((pairing) => pairing.expiresAtMs > nowMs).map((pairing) => (0, authorizedKeys_1.buildTempKeyLine)({ ...common, publicKey: pairing.publicKey, expiresAtMs: pairing.expiresAtMs, pairId: pairing.pairId })),
+        ...runners.map((runner) => (0, authorizedKeys_1.buildRunnerKeyLine)({ ...common, publicKey: runner.publicKey, runnerId: runner.id })),
+    ];
+}
+function readTextIfPresent(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description Bring the derived files in line with the two registry files: `known_hosts` and the `authorized_keys` block, each written
+ * only when it differs. The registry lock must be held. The block goes LAST, so a key is never allowed before the files its gate reads
+ * are in place. The registry files are authoritative and are written BEFORE this runs; a failure here is reported as
+ * {@link HubDerivedFilesError} and mends itself, because every locked operation ends with this same call.
+ */
+function syncDerivedHubFiles(ctx, pending, paired, nowMs) {
+    const knownHostsPath = (0, hubPaths_1.getHubFilePaths)(ctx.dir).knownHosts;
+    const knownHosts = renderKnownHosts(paired.runners);
+    try {
+        if (readTextIfPresent(knownHostsPath) !== knownHosts)
+            (0, configDirFile_1.writeTextFileAtomically)(knownHostsPath, knownHosts, knownHostsMode);
+    }
+    catch (error) {
+        throw new HubDerivedFilesError('known_hosts', (0, configDirFile_2.getCaughtErrnoCode)(error));
+    }
+    try {
+        (0, authorizedKeys_1.writeManagedBlock)(ctx.authorizedKeysPath, renderManagedBlockLines(ctx, pending.pending, paired.runners, nowMs));
+    }
+    catch (error) {
+        throw new HubDerivedFilesError('authorized_keys', (0, configDirFile_2.getCaughtErrnoCode)(error));
+    }
+}
+//# sourceMappingURL=hubRegistry.js.map

package/dist/runners/hubRegistry.js.map

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

package/dist/runners/linkControl.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+declare const linkStateSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    sinceMs: z.ZodNumber;
+    lastBeatMs: z.ZodNumber;
+    endedAtMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+/** @name LinkState @description `link/<id>.json`. */
+export type LinkState = z.infer<typeof linkStateSchema>;
+export interface RunnerLinkStatus {
+    isOnline: boolean;
+    /** When the link in force started (only while online). */
+    sinceMs: number | null;
+    /** The last time the hub knew the link alive; `null` if it never was. */
+    lastSeenMs: number | null;
+}
+export declare function readLinkState(dir: string, runnerId: string): LinkState | null;
+export declare function writeLinkState(dir: string, runnerId: string, state: LinkState): void;
+/** @description Does anything accept a connection on the unix socket `socketPath` right now? */
+export declare function probeSocket(socketPath: string, timeoutMs?: number): Promise<boolean>;
+export declare function getRunnerLinkStatus(dir: string, runnerId: string): Promise<RunnerLinkStatus>;
+/** @description Is `pid` a charness gate serving runner `runnerId`? (A pid in an old json may belong to anything by now.) */
+export declare function checkIsGateProcessOf(pid: number, runnerId: string): boolean;
+/** @description Cut the link of a runner that was removed: no new connection reaches it, and its gate leaves. */
+export declare function cutRunnerLink(dir: string, runnerId: string): void;
+export {};
+//# sourceMappingURL=linkControl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"linkControl.d.ts","sourceRoot":"","sources":["../../src/runners/linkControl.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,QAAA,MAAM,eAAe;;;;;kBAMnB,CAAC;AAEH,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO7E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAGpF;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,MAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAYpG;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQlG;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED,iHAAiH;AACjH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAcjE"}

package/dist/runners/linkControl.js

@@ -0,0 +1,124 @@
+"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;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const hubPaths_1 = require("./hubPaths");
+/**
+ * @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.
+ */
+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, and its gate leaves. */
+function cutRunnerLink(dir, runnerId) {
+    const state = readLinkState(dir, runnerId);
+    try {
+        fs.rmSync((0, hubPaths_1.getRunnerLinkPaths)(dir, runnerId).socket, { force: true });
+    }
+    catch (error) {
+        if ((0, configDirFile_1.getCaughtErrnoCode)(error) !== 'ENOENT')
+            throw error;
+    }
+    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;
+        }
+    }
+}
+//# 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"}