charness 3.6.1 → 3.8.0

package/dist/runnerUtility/adminCheck.js

@@ -0,0 +1,68 @@
+"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.checkIsAdminAccount = checkIsAdminAccount;
+exports.readAccountGroups = readAccountGroups;
+exports.readAccountFacts = readAccountFacts;
+exports.formatAdminWarning = formatAdminWarning;
+const child_process_1 = require("child_process");
+const os = __importStar(require("os"));
+/**
+ * @description Is the account that runs the jobs an admin one? The agents' code runs with its rights, so a runner on an account that can
+ * `sudo` (or is root) gets a warning at pairing: make a standard user for it. macOS: member of the `admin` group; Linux: uid 0 or a
+ * member of `sudo`, `wheel` or `admin`.
+ */
+const linuxAdminGroups = ['sudo', 'wheel', 'admin'];
+const macAdminGroup = 'admin';
+function checkIsAdminAccount(account) {
+    if (account.platform === 'darwin')
+        return account.groups.includes(macAdminGroup);
+    return account.uid === 0 || account.groups.some((group) => linuxAdminGroups.includes(group));
+}
+/** @description The account's group names (`id -Gn`), empty when it cannot be asked. */
+function readAccountGroups() {
+    const result = (0, child_process_1.spawnSync)('id', ['-Gn'], { encoding: 'utf8', timeout: 4000 });
+    return result.status === 0 ? result.stdout.trim().split(/\s+/).filter((group) => group !== '') : [];
+}
+function readAccountFacts() {
+    return { platform: process.platform, uid: os.userInfo().uid, groups: readAccountGroups() };
+}
+function formatAdminWarning(accountName) {
+    return [
+        `⚠ «${accountName}» is an admin account: the agents' code would run with its rights.`,
+        '  Create a standard user for runs (System Settings → Users & Groups, or `adduser`) and run the line there.',
+    ];
+}
+//# sourceMappingURL=adminCheck.js.map

package/dist/runnerUtility/adminCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adminCheck.js","sourceRoot":"","sources":["../../src/runnerUtility/adminCheck.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBA,kDAGC;AAGD,8CAGC;AAED,4CAEC;AAED,gDAKC;AAtCD,iDAA0C;AAC1C,uCAAyB;AAEzB;;;;GAIG;AAEH,MAAM,gBAAgB,GAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACvE,MAAM,aAAa,GAAG,OAAO,CAAC;AAQ9B,SAAgB,mBAAmB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC,GAAG,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,wFAAwF;AACxF,SAAgB,iBAAiB;IAC/B,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACtG,CAAC;AAED,SAAgB,gBAAgB;IAC9B,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,EAAE,CAAC;AAC7F,CAAC;AAED,SAAgB,kBAAkB,CAAC,WAAmB;IACpD,OAAO;QACL,MAAM,WAAW,oEAAoE;QACrF,4GAA4G;KAC7G,CAAC;AACJ,CAAC"}

package/dist/runnerUtility/appInstall.d.ts

@@ -0,0 +1,25 @@
+import { type RunnerHomePaths } from './runnerHome';
+/**
+ * @description Installing a copy of the hub's charness package for the runner to run, and switching to it. BUILTINS ONLY: the first
+ * `charness-runner pair` is started from a package that has no `node_modules` yet, and this is the step that makes them.
+ *
+ * An app lives in `app.<random id>/` and is never renamed or changed once it runs; `current` is a symlink that is replaced whole. The
+ * launcher (`launcher.ts`) starts whatever `current` points at, so an update is: install next to the old one, point `current` at it,
+ * exit with {@link restartExitCode}.
+ */
+/** The exit code that asks the launcher to start the app again (EX_TEMPFAIL) — after an update. */
+export declare const restartExitCode = 75;
+/** Test seam, set only by a flow's environment: the folder to link as `node_modules` instead of running `npm install` (no registry in a flow). */
+export declare const testNodeModulesEnvName = "CHARNESS_TEST_RUNNER_NODE_MODULES";
+export declare function createAppId(): string;
+/** Install the production dependencies of the package in `appDir`; scripts are not run (nothing the runner needs builds). Throws with npm's last words. */
+export declare function installDependencies(appDir: string, env?: NodeJS.ProcessEnv): void;
+/** @description Copy an unpacked package into a new app folder and install its dependencies; returns the folder. Removes it again if the install fails. */
+export declare function installAppFromDirectory(sourceDir: string, paths: RunnerHomePaths): string;
+/** @description Unpack a gzip tar archive (the hub's package) into a new app folder with the system `tar`, and install its dependencies. */
+export declare function installAppFromArchive(archivePath: string, paths: RunnerHomePaths): string;
+/** @description Point `current` at `appDir` in one atomic step. */
+export declare function switchCurrentApp(paths: RunnerHomePaths, appDir: string): void;
+/** @description Remove old app folders: all but the one `current` points at and the newest other one (the previous version, in case the new one must be rolled back by hand). */
+export declare function removeOldApps(paths: RunnerHomePaths): void;
+//# sourceMappingURL=appInstall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"appInstall.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/appInstall.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAEnE;;;;;;;GAOG;AAEH,mGAAmG;AACnG,eAAO,MAAM,eAAe,KAAK,CAAC;AAOlC,kJAAkJ;AAClJ,eAAO,MAAM,sBAAsB,sCAAsC,CAAC;AAE1E,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAOD,2JAA2J;AAC3J,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAiB9F;AAED,2JAA2J;AAC3J,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAWzF;AAED,4IAA4I;AAC5I,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAYzF;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAK7E;AAED,iLAAiL;AACjL,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAa1D"}

package/dist/runnerUtility/appInstall.js

@@ -0,0 +1,147 @@
+"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.testNodeModulesEnvName = exports.restartExitCode = void 0;
+exports.createAppId = createAppId;
+exports.installDependencies = installDependencies;
+exports.installAppFromDirectory = installAppFromDirectory;
+exports.installAppFromArchive = installAppFromArchive;
+exports.switchCurrentApp = switchCurrentApp;
+exports.removeOldApps = removeOldApps;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runnerHome_1 = require("./runnerHome");
+/**
+ * @description Installing a copy of the hub's charness package for the runner to run, and switching to it. BUILTINS ONLY: the first
+ * `charness-runner pair` is started from a package that has no `node_modules` yet, and this is the step that makes them.
+ *
+ * An app lives in `app.<random id>/` and is never renamed or changed once it runs; `current` is a symlink that is replaced whole. The
+ * launcher (`launcher.ts`) starts whatever `current` points at, so an update is: install next to the old one, point `current` at it,
+ * exit with {@link restartExitCode}.
+ */
+/** The exit code that asks the launcher to start the app again (EX_TEMPFAIL) — after an update. */
+exports.restartExitCode = 75;
+const npmInstallTimeoutMs = 10 * 60 * 1000;
+const appsToKeep = 2;
+const appDirPattern = /^app\.[0-9a-f]+$/;
+const randomIdBytes = 6;
+const maxBufferBytes = 64 * 1024 * 1024;
+/** Test seam, set only by a flow's environment: the folder to link as `node_modules` instead of running `npm install` (no registry in a flow). */
+exports.testNodeModulesEnvName = 'CHARNESS_TEST_RUNNER_NODE_MODULES';
+function createAppId() {
+    let id = '';
+    for (let index = 0; index < randomIdBytes; index += 1)
+        id += Math.floor(Math.random() * 256).toString(16).padStart(2, '0');
+    return id;
+}
+function findNpm() {
+    const besideNode = path.join(path.dirname(process.execPath), 'npm');
+    return fs.existsSync(besideNode) ? besideNode : 'npm';
+}
+/** Install the production dependencies of the package in `appDir`; scripts are not run (nothing the runner needs builds). Throws with npm's last words. */
+function installDependencies(appDir, env = process.env) {
+    const linked = env[exports.testNodeModulesEnvName];
+    if (linked !== undefined && linked !== '') {
+        fs.symlinkSync(linked, path.join(appDir, 'node_modules'), 'dir');
+        return;
+    }
+    const result = (0, child_process_1.spawnSync)(findNpm(), ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--no-progress'], {
+        cwd: appDir,
+        encoding: 'utf8',
+        timeout: npmInstallTimeoutMs,
+        maxBuffer: maxBufferBytes,
+        env,
+    });
+    if (result.error !== undefined || result.status !== 0) {
+        const detail = `${result.stderr ?? ''}`.trim().split('\n').slice(-3).join(' | ');
+        throw new Error(`npm install failed${result.error === undefined ? '' : ` (${result.error.message})`}${detail === '' ? '' : `: ${detail}`}`);
+    }
+}
+/** @description Copy an unpacked package into a new app folder and install its dependencies; returns the folder. Removes it again if the install fails. */
+function installAppFromDirectory(sourceDir, paths) {
+    const appDir = (0, runnerHome_1.getAppDirPath)(paths, createAppId());
+    fs.mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    fs.cpSync(sourceDir, appDir, { recursive: true });
+    try {
+        installDependencies(appDir);
+    }
+    catch (error) {
+        fs.rmSync(appDir, { recursive: true, force: true });
+        throw error;
+    }
+    return appDir;
+}
+/** @description Unpack a gzip tar archive (the hub's package) into a new app folder with the system `tar`, and install its dependencies. */
+function installAppFromArchive(archivePath, paths) {
+    const appDir = (0, runnerHome_1.getAppDirPath)(paths, createAppId());
+    fs.mkdirSync(appDir, { recursive: true, mode: 0o700 });
+    try {
+        const unpacked = (0, child_process_1.spawnSync)('tar', ['-xzf', archivePath, '-C', appDir], { encoding: 'utf8' });
+        if (unpacked.status !== 0)
+            throw new Error(`could not unpack the package (tar exit ${unpacked.status ?? 'none'})`);
+        installDependencies(appDir);
+    }
+    catch (error) {
+        fs.rmSync(appDir, { recursive: true, force: true });
+        throw error;
+    }
+    return appDir;
+}
+/** @description Point `current` at `appDir` in one atomic step. */
+function switchCurrentApp(paths, appDir) {
+    const temporaryLink = `${paths.currentApp}.${process.pid}.tmp`;
+    fs.rmSync(temporaryLink, { force: true });
+    fs.symlinkSync(appDir, temporaryLink, 'dir');
+    fs.renameSync(temporaryLink, paths.currentApp);
+}
+/** @description Remove old app folders: all but the one `current` points at and the newest other one (the previous version, in case the new one must be rolled back by hand). */
+function removeOldApps(paths) {
+    let currentTarget = null;
+    try {
+        currentTarget = fs.realpathSync(paths.currentApp);
+    }
+    catch {
+        currentTarget = null;
+    }
+    const apps = fs.readdirSync(paths.root)
+        .filter((name) => appDirPattern.test(name))
+        .map((name) => ({ name, dir: path.join(paths.root, name), modifiedAt: fs.statSync(path.join(paths.root, name)).mtimeMs }))
+        .filter((app) => currentTarget === null || fs.realpathSync(app.dir) !== currentTarget)
+        .sort((left, right) => right.modifiedAt - left.modifiedAt);
+    for (const app of apps.slice(appsToKeep - 1))
+        fs.rmSync(app.dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=appInstall.js.map

package/dist/runnerUtility/appInstall.js.map

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

package/dist/runnerUtility/appUpdate.d.ts

@@ -0,0 +1,39 @@
+import { connectToHub } from './hubClient';
+import { type RunnerConfig } from './runnerConfig';
+import type { RunnerHomePaths } from './runnerHome';
+/**
+ * @description Updating the runner to the hub's current package: the hub's `link` answer names the package id; when it is not the one
+ * installed, an IDLE runner fetches the package with the `package` request (a connection of its own), checks that the archive hashes to
+ * the id the hub announced, installs it next to the running copy, points `current` at it and records the id. The caller then exits with
+ * the restart code and the launcher starts the new copy. Nothing is changed in the running copy.
+ */
+export type UpdateOutcome = {
+    ok: true;
+    packageId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface UpdateParams {
+    paths: RunnerHomePaths;
+    config: RunnerConfig;
+    clientPrivateKey: string;
+    connect?: typeof connectToHub;
+}
+/** @description Fetch, verify and install the hub's package; on success `current` and `config.json` point at it. */
+export declare function updateFromHub(params: UpdateParams): Promise<UpdateOutcome>;
+export interface UpdateDecisionInputs {
+    /** What the hub named in the `link` answer (`none`: it could not pack one). */
+    hubPackageId: string | undefined;
+    installedPackageId: string | null;
+    activeExecCount: number;
+    /** The id of an update that already failed, and when — it is not tried again for {@link updateRetryDelayMs}. */
+    failedPackageId: string | null;
+    failedAtMs: number;
+    nowMs: number;
+}
+export declare const updateRetryDelayMs: number;
+export type UpdateDecision = 'none' | 'wait-until-idle' | 'update-now';
+/** @description Update only to a package the hub named and the runner does not have; only while no command runs; not again right after a failure. */
+export declare function decideUpdate(inputs: UpdateDecisionInputs): UpdateDecision;
+//# sourceMappingURL=appUpdate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"appUpdate.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/appUpdate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,YAAY,EAAoB,MAAM,aAAa,CAAC;AAGvE,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;GAKG;AAEH,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC;CAC/B;AAED,oHAAoH;AACpH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA2BhF;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,gHAAgH;IAChH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEvE,qJAAqJ;AACrJ,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAIzE"}

package/dist/runnerUtility/appUpdate.js

@@ -0,0 +1,90 @@
+"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.updateRetryDelayMs = void 0;
+exports.updateFromHub = updateFromHub;
+exports.decideUpdate = decideUpdate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gateProtocol_1 = require("../runners/gateProtocol");
+const hubClient_1 = require("./hubClient");
+const packageId_1 = require("./packageId");
+const appInstall_1 = require("./appInstall");
+const runnerConfig_1 = require("./runnerConfig");
+/** @description Fetch, verify and install the hub's package; on success `current` and `config.json` point at it. */
+async function updateFromHub(params) {
+    const endpoint = { host: params.config.hub.host, port: params.config.hub.port, user: params.config.hub.user, hostKey: params.config.hub.hostKey };
+    const archivePath = path.join(params.paths.root, `package.${process.pid}.tgz`);
+    try {
+        const client = await (params.connect ?? hubClient_1.connectToHub)(endpoint, params.clientPrivateKey);
+        try {
+            const answer = await (0, hubClient_1.callGate)(client, 'package', null);
+            const expectedId = answer?.marker.fields.id;
+            if (answer === null || expectedId === undefined)
+                return { ok: false, reason: 'the hub did not send the package' };
+            const chunks = [];
+            for await (const chunk of answer.channel)
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            const archive = Buffer.concat(chunks);
+            if ((0, packageId_1.getPackageIdOfArchive)(archive) !== expectedId)
+                return { ok: false, reason: 'the package the hub sent does not match the id it announced' };
+            fs.writeFileSync(archivePath, archive, { mode: 0o600 });
+            const appDir = (0, appInstall_1.installAppFromArchive)(archivePath, params.paths);
+            (0, appInstall_1.switchCurrentApp)(params.paths, appDir);
+            (0, runnerConfig_1.writeRunnerConfig)(params.paths, { ...params.config, packageId: expectedId });
+            (0, appInstall_1.removeOldApps)(params.paths);
+            return { ok: true, packageId: expectedId };
+        }
+        finally {
+            client.end();
+        }
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : 'the update failed' };
+    }
+    finally {
+        fs.rmSync(archivePath, { force: true });
+    }
+}
+exports.updateRetryDelayMs = 10 * 60 * 1000;
+/** @description Update only to a package the hub named and the runner does not have; only while no command runs; not again right after a failure. */
+function decideUpdate(inputs) {
+    if (inputs.hubPackageId === undefined || inputs.hubPackageId === gateProtocol_1.noPackageMarker || inputs.hubPackageId === inputs.installedPackageId)
+        return 'none';
+    if (inputs.failedPackageId === inputs.hubPackageId && inputs.nowMs - inputs.failedAtMs < exports.updateRetryDelayMs)
+        return 'none';
+    return inputs.activeExecCount === 0 ? 'update-now' : 'wait-until-idle';
+}
+//# sourceMappingURL=appUpdate.js.map

package/dist/runnerUtility/appUpdate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appUpdate.js","sourceRoot":"","sources":["../../src/runnerUtility/appUpdate.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,sCA2BC;AAkBD,oCAIC;AA3ED,uCAAyB;AACzB,2CAA6B;AAC7B,0DAA0D;AAC1D,2CAAuE;AACvE,2CAAoD;AACpD,6CAAsF;AACtF,iDAAsE;AAmBtE,oHAAoH;AAC7G,KAAK,UAAU,aAAa,CAAC,MAAoB;IACtD,MAAM,QAAQ,GAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAC/J,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,wBAAY,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACzF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAA,oBAAQ,EAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;YACvD,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,IAAI,MAAM,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;YAClH,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3G,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,IAAA,iCAAqB,EAAC,OAAO,CAAC,KAAK,UAAU;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6DAA6D,EAAE,CAAC;YAC/I,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACxD,MAAM,MAAM,GAAG,IAAA,kCAAqB,EAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAChE,IAAA,6BAAgB,EAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACvC,IAAA,gCAAiB,EAAC,MAAM,CAAC,KAAK,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;YAC7E,IAAA,0BAAa,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;IAC7F,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAaY,QAAA,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAIjD,qJAAqJ;AACrJ,SAAgB,YAAY,CAAC,MAA4B;IACvD,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,8BAAe,IAAI,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC,kBAAkB;QAAE,OAAO,MAAM,CAAC;IACrJ,IAAI,MAAM,CAAC,eAAe,KAAK,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,GAAG,0BAAkB;QAAE,OAAO,MAAM,CAAC;IAC3H,OAAO,MAAM,CAAC,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC;AACzE,CAAC"}

package/dist/runnerUtility/execEnv.d.ts

@@ -0,0 +1,21 @@
+import type { RunnerHomePaths } from './runnerHome';
+/** @description `KEY=VALUE` lines; blank lines and `#` comments are skipped, `export ` is allowed, one pair of quotes around a value is removed. A line that is not a pair is returned in `rejected` (its number, never its text — a value may be a secret). */
+export declare function parseEnvFile(text: string): {
+    values: Record<string, string>;
+    rejected: number[];
+};
+/** @description The Android SDK folder if one is where the installers put it (or the environment says), else `null`. */
+export declare function findAndroidSdk(homeDir: string, environment: NodeJS.ProcessEnv, checkExists?: (candidate: string) => boolean): string | null;
+export interface ExecEnvInputs {
+    paths: RunnerHomePaths;
+    accountName: string;
+    /** The utility's own environment: only LANG and TMPDIR are taken from it. */
+    environment: NodeJS.ProcessEnv;
+    nodeDir: string;
+    operatorEnv: Readonly<Record<string, string>>;
+    androidSdk: string | null;
+}
+export declare function buildExecEnv(inputs: ExecEnvInputs): NodeJS.ProcessEnv;
+/** @description The environment for the next command: the `env` file is read fresh each time, so an edit applies to the next job without a restart. */
+export declare function readExecEnv(paths: RunnerHomePaths, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=execEnv.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execEnv.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/execEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,gQAAgQ;AAChQ,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAiBjG;AAED,wHAAwH;AACxH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAuB,GAAG,MAAM,GAAG,IAAI,CAG1J;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,UAAU,CAYrE;AAED,uJAAuJ;AACvJ,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,UAAU,CAenH"}

package/dist/runnerUtility/execEnv.js

@@ -0,0 +1,109 @@
+"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.parseEnvFile = parseEnvFile;
+exports.findAndroidSdk = findAndroidSdk;
+exports.buildExecEnv = buildExecEnv;
+exports.readExecEnv = readExecEnv;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * @description The environment of a command that runs over the link — CLEAN, like a login by a service: the runner's own environment
+ * (a launchd job's, a terminal's) never leaks into the agents' jobs. HOME, USER, LOGNAME, LANG, TMPDIR; a PATH of `~/.charness-runner/bin`
+ * (pueue, rsync), the folder of the `node` that runs the utility, the Homebrew and system folders; the Android SDK when it is where
+ * the usual installers put it; then the operator's own `KEY=VALUE` lines from `~/.charness-runner/env`.
+ */
+const systemPathDirs = ['/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', '/usr/local/sbin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+const defaultLang = 'en_US.UTF-8';
+const envNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** @description `KEY=VALUE` lines; blank lines and `#` comments are skipped, `export ` is allowed, one pair of quotes around a value is removed. A line that is not a pair is returned in `rejected` (its number, never its text — a value may be a secret). */
+function parseEnvFile(text) {
+    const values = {};
+    const rejected = [];
+    text.split('\n').forEach((rawLine, index) => {
+        const line = rawLine.trim().replace(/^export\s+/, '');
+        if (line === '' || line.startsWith('#'))
+            return;
+        const separator = line.indexOf('=');
+        const name = separator === -1 ? '' : line.slice(0, separator).trim();
+        if (!envNamePattern.test(name)) {
+            rejected.push(index + 1);
+            return;
+        }
+        let value = line.slice(separator + 1).trim();
+        if (value.length >= 2 && (value.startsWith('"') || value.startsWith("'")) && value.endsWith(value[0]))
+            value = value.slice(1, -1);
+        values[name] = value;
+    });
+    return { values, rejected };
+}
+/** @description The Android SDK folder if one is where the installers put it (or the environment says), else `null`. */
+function findAndroidSdk(homeDir, environment, checkExists = fs.existsSync) {
+    const candidates = [environment.ANDROID_HOME, environment.ANDROID_SDK_ROOT, path.join(homeDir, 'Library', 'Android', 'sdk'), path.join(homeDir, 'Android', 'Sdk'), '/opt/android-sdk'];
+    return candidates.find((candidate) => candidate !== undefined && candidate !== '' && checkExists(candidate)) ?? null;
+}
+function buildExecEnv(inputs) {
+    const pathDirs = [inputs.paths.binDir, inputs.nodeDir, ...systemPathDirs];
+    return {
+        HOME: inputs.paths.homeDir,
+        USER: inputs.accountName,
+        LOGNAME: inputs.accountName,
+        LANG: inputs.environment.LANG ?? defaultLang,
+        TMPDIR: inputs.environment.TMPDIR ?? os.tmpdir(),
+        PATH: [...new Set(pathDirs)].join(path.delimiter),
+        ...(inputs.androidSdk === null ? {} : { ANDROID_HOME: inputs.androidSdk, ANDROID_SDK_ROOT: inputs.androidSdk }),
+        ...inputs.operatorEnv,
+    };
+}
+/** @description The environment for the next command: the `env` file is read fresh each time, so an edit applies to the next job without a restart. */
+function readExecEnv(paths, environment = process.env) {
+    let operatorEnv = {};
+    try {
+        operatorEnv = parseEnvFile(fs.readFileSync(paths.envFile, 'utf8')).values;
+    }
+    catch {
+        operatorEnv = {};
+    }
+    return buildExecEnv({
+        paths,
+        accountName: os.userInfo().username,
+        environment,
+        nodeDir: path.dirname(process.execPath),
+        operatorEnv,
+        androidSdk: findAndroidSdk(paths.homeDir, environment),
+    });
+}
+//# sourceMappingURL=execEnv.js.map

package/dist/runnerUtility/execEnv.js.map

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

package/dist/runnerUtility/execSession.d.ts

@@ -0,0 +1,13 @@
+import type { ServerChannel } from 'ssh2';
+export interface ExecTracker {
+    started: () => void;
+    ended: () => void;
+}
+export interface ExecOptions {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    tracker: ExecTracker;
+}
+/** @description Run `command` for `channel`. */
+export declare function serveExec(channel: ServerChannel, command: string, options: ExecOptions): void;
+//# sourceMappingURL=execSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execSession.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/execSession.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAe1C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;CACtB;AAYD,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CA2B7F"}

package/dist/runnerUtility/execSession.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveExec = serveExec;
+const child_process_1 = require("child_process");
+/**
+ * @description One `exec` request of a session: the command runs under `bash -c` in a clean environment, its stdin is the channel's
+ * (the client's EOF is the command's EOF — phase 1's lease relies on it), its stdout and stderr go back on the channel's two streams,
+ * and its end is reported as an exit status or a signal.
+ *
+ * Sshd's semantics for a channel that is CLOSED by the client: the pipes close, the command is NOT killed. Here: stdout and stderr are
+ * destroyed (the command's next write fails, as with a closed pipe), its stdin is closed, and the process runs on. Only the real end
+ * of the process closes the books on it ({@link ExecTracker.ended}), which is what «the runner is busy» means.
+ */
+const commandNotFoundStatus = 127;
+const signalPrefix = /^SIG/;
+function sendExitStatus(channel, exitCode, signal) {
+    try {
+        if (signal !== null)
+            channel.exit(signal.replace(signalPrefix, ''), false, '');
+        else
+            channel.exit(exitCode ?? commandNotFoundStatus);
+        channel.end();
+    }
+    catch {
+        // The client closed the channel first: nobody is waiting for the status.
+    }
+}
+/** @description Run `command` for `channel`. */
+function serveExec(channel, command, options) {
+    options.tracker.started();
+    const child = (0, child_process_1.spawn)('bash', ['-c', command], { env: options.env, cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    child.stdin.on('error', () => undefined);
+    channel.on('error', () => undefined);
+    channel.stderr.on('error', () => undefined);
+    channel.pipe(child.stdin);
+    child.stdout.pipe(channel, { end: false });
+    child.stderr.pipe(channel.stderr, { end: false });
+    channel.once('close', () => {
+        child.stdin.destroy();
+        child.stdout.destroy();
+        child.stderr.destroy();
+    });
+    // A failed start emits `error` and then `close`: the command is finished exactly once, or the busy count would go negative.
+    let isFinished = false;
+    const finish = (exitCode, signal) => {
+        if (isFinished)
+            return;
+        isFinished = true;
+        sendExitStatus(channel, exitCode, signal);
+        options.tracker.ended();
+    };
+    child.once('error', (error) => {
+        channel.stderr.write(`charness-runner: cannot start the command (${error.message})\n`);
+        finish(commandNotFoundStatus, null);
+    });
+    child.once('close', (exitCode, signal) => finish(exitCode, signal));
+}
+//# sourceMappingURL=execSession.js.map

package/dist/runnerUtility/execSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execSession.js","sourceRoot":"","sources":["../../src/runnerUtility/execSession.ts"],"names":[],"mappings":";;AAsCA,8BA2BC;AAjED,iDAAsC;AAGtC;;;;;;;;GAQG;AAEH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,YAAY,GAAG,MAAM,CAAC;AAa5B,SAAS,cAAc,CAAC,OAAsB,EAAE,QAAuB,EAAE,MAA6B;IACpG,IAAI,CAAC;QACH,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;;YAC1E,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,qBAAqB,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAgB,SAAS,CAAC,OAAsB,EAAE,OAAe,EAAE,OAAoB;IACrF,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACtH,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;QACzB,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACtB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IACH,4HAA4H;IAC5H,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,CAAC,QAAuB,EAAE,MAA6B,EAAQ,EAAE;QAC9E,IAAI,UAAU;YAAE,OAAO;QACvB,UAAU,GAAG,IAAI,CAAC;QAClB,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;QACvF,MAAM,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}