vouchington-tooling 0.0.0

package/README.md

@@ -0,0 +1,38 @@
+# vouchington-tooling
+
+Libraries and the `vouchington` CLI.
+
+```bash
+npm install vouchington-tooling
+# optional, only if you import vouchington-tooling/sql-ast
+npm install @libpg-query/parser
+```
+
+## CLI
+
+```bash
+vouchington --help
+vouchington runner-port-policy
+vouchington runner-port-policy --file ./policy.json
+vouchington runner-port-policy --reserved 2200
+vouchington with-host-lock --name expensive-build --timeout-seconds 60 -- make build
+```
+
+Host-lock environment:
+
+| Variable                                | Default               | Meaning                                     |
+| --------------------------------------- | --------------------- | ------------------------------------------- |
+| `HOST_LOCK_ROOT`                        | `/tmp/host-lock-$UID` | Absolute lock directory root                |
+| `HOST_LOCK_LEASE_SECONDS`               | `60`                  | Reclaim ceiling for a held lock             |
+| `HOST_LOCK_PROCESS_GROUP_DRAIN_SECONDS` | `30`                  | Time to wait for the command process group  |
+| `HOST_LOCK_ACTIVE`                      | unset                 | Set while a lock is held; nested locks fail |
+
+## Library
+
+```ts
+import {
+  isRunnerReservedPort,
+  listenOnRunnerUnreservedEphemeralPort,
+  runnerPortPolicy,
+} from 'vouchington-tooling/runner-port-policy'
+```

package/dist/cli/commands/runner-port-policy.d.mts

@@ -0,0 +1,4 @@
+export declare function runRunnerPortPolicy(options: {
+    file?: string;
+    reserved?: number;
+}): number;

package/dist/cli/commands/runner-port-policy.mjs

@@ -0,0 +1,11 @@
+import { pathToFileURL } from 'node:url';
+import { isRunnerReservedPort, loadRunnerPortPolicy, runnerPortPolicy, } from '../../runner-port-policy/index.mjs';
+export function runRunnerPortPolicy(options) {
+    const policy = options.file ? loadRunnerPortPolicy(pathToFileURL(options.file)) : runnerPortPolicy;
+    if (options.reserved !== undefined) {
+        process.stdout.write(`${String(isRunnerReservedPort(options.reserved, policy))}\n`);
+        return 0;
+    }
+    process.stdout.write(`${JSON.stringify(policy, null, 2)}\n`);
+    return 0;
+}

package/dist/cli/commands/with-host-lock.d.mts

@@ -0,0 +1,6 @@
+import { type SpawnSyncReturns } from 'node:child_process';
+export type HostLockSpawn = (command: string, args: readonly string[], options: {
+    stdio: 'inherit';
+}) => Pick<SpawnSyncReturns<Buffer>, 'error' | 'status'>;
+export declare function hostLockScriptPath(): string;
+export declare function runWithHostLock(args: readonly string[], spawn?: HostLockSpawn): number;

package/dist/cli/commands/with-host-lock.mjs

@@ -0,0 +1,14 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const scriptUrl = new URL('../../../scripts/host-lock/with-host-lock.sh', import.meta.url);
+export function hostLockScriptPath() {
+    return fileURLToPath(scriptUrl);
+}
+export function runWithHostLock(args, spawn = spawnSync) {
+    const result = spawn('bash', [hostLockScriptPath(), ...args], {
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}

package/dist/cli/index.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: readonly string[]): number;
+export declare function isMainModule(metaUrl: string, argv1: string | undefined): boolean;

package/dist/cli/index.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { readPackageVersion } from '../package-version.mjs';
+import { runRunnerPortPolicy } from './commands/runner-port-policy.mjs';
+import { runWithHostLock } from './commands/with-host-lock.mjs';
+import { parseCli } from './parse.mjs';
+import { printUsage } from './usage.mjs';
+export function runCli(argv = process.argv) {
+    const parsed = parseCli(argv);
+    switch (parsed.kind) {
+        case 'help':
+            printUsage();
+            return 0;
+        case 'version':
+            process.stdout.write(`${readInstalledVersion()}\n`);
+            return 0;
+        case 'error':
+            process.stderr.write(`vouchington: ${parsed.message}\n`);
+            printUsage(process.stderr);
+            return 2;
+        case 'runner-port-policy':
+            return runRunnerPortPolicy(parsed);
+        case 'with-host-lock':
+            return runWithHostLock(parsed.args);
+    }
+}
+function readInstalledVersion() {
+    return readPackageVersion(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')));
+}
+export function isMainModule(metaUrl, argv1) {
+    return argv1 !== undefined && metaUrl === pathToFileURL(argv1).href;
+}
+/* v8 ignore next 3 */
+if (isMainModule(import.meta.url, process.argv[1])) {
+    process.exitCode = runCli();
+}

package/dist/cli/parse.d.mts

@@ -0,0 +1,16 @@
+export type ParsedCli = {
+    kind: 'help';
+} | {
+    kind: 'version';
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'runner-port-policy';
+    file?: string;
+    reserved?: number;
+} | {
+    kind: 'with-host-lock';
+    args: string[];
+};
+export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -0,0 +1,47 @@
+export function parseCli(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h')
+        return { kind: 'help' };
+    if (args[0] === '--version' || args[0] === '-v')
+        return { kind: 'version' };
+    const [command, ...rest] = args;
+    if (command === 'runner-port-policy')
+        return parseRunnerPortPolicy(rest);
+    if (command === 'with-host-lock')
+        return { kind: 'with-host-lock', args: rest };
+    return { kind: 'error', message: `unknown command: ${command}` };
+}
+function parseRunnerPortPolicy(args) {
+    let file;
+    let reserved;
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--file') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: '--file requires a path' };
+            file = value;
+            index += 1;
+            continue;
+        }
+        if (flag === '--reserved') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: '--reserved requires a port' };
+            const port = Number(value);
+            if (!Number.isInteger(port))
+                return { kind: 'error', message: '--reserved must be an integer' };
+            reserved = port;
+            index += 1;
+            continue;
+        }
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        return { kind: 'error', message: `unknown runner-port-policy option: ${flag}` };
+    }
+    return {
+        kind: 'runner-port-policy',
+        ...(file === undefined ? {} : { file }),
+        ...(reserved === undefined ? {} : { reserved }),
+    };
+}

package/dist/cli/usage.d.mts

@@ -0,0 +1,2 @@
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n";
+export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -0,0 +1,27 @@
+export const USAGE = `Usage: vouchington <command> [options]
+
+Commands:
+  runner-port-policy   Print or validate a runner port policy
+  with-host-lock       Run a command under a host-wide lock
+
+Options:
+  -h, --help       Show this help
+  -v, --version    Print the package version
+
+runner-port-policy
+  (no args)              Print the shipped policy as JSON
+  --file <path>          Validate and print a policy file
+  --reserved <port>      Print true if the port is reserved
+
+with-host-lock
+  --name <family>
+  [--slots <n>]
+  --timeout-seconds <n>
+  [--command-timeout-seconds <n>]
+  [--failure-diagnostics <absolute-script>]
+  [--on-acquire-timeout fail|run-unlocked]
+  -- <command> [args...]
+`;
+export function printUsage(stream = process.stdout) {
+    stream.write(USAGE);
+}

package/dist/host-lock/with-host-lock.test-helpers.d.mts

@@ -0,0 +1,21 @@
+import { execFile, type ChildProcess } from 'node:child_process';
+export declare const execFileAsync: typeof execFile.__promisify__;
+export declare const hostLockScript: string;
+export declare function makeHome(): Promise<string>;
+export declare function hostLockEnv(home: string, overrides?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function hostLockArgs(name: string, timeoutSeconds: number, command: string[], extraArgs?: string[]): string[];
+export declare function spawnHostLock(home: string, name: string, timeoutSeconds: number, command: string[], env?: NodeJS.ProcessEnv, extraArgs?: string[]): ChildProcess;
+export declare function completion(child: ChildProcess): Promise<{
+    code: number | null;
+    stderr: string;
+}>;
+export declare function waitForPath(path: string): Promise<void>;
+export declare function cleanupTestHomes(): Promise<void>;
+export declare function withFinalTimeoutProbe(home: string, assertProbe: ({ lock, marker, contenderDone, }: {
+    lock: string;
+    marker: string;
+    contenderDone: Promise<{
+        code: number | null;
+        stderr: string;
+    }>;
+}) => Promise<void>): Promise<void>;

package/dist/host-lock/with-host-lock.test-helpers.mjs

@@ -0,0 +1,124 @@
+import { execFile, spawn } from 'node:child_process';
+import { mkdtemp, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+export const execFileAsync = promisify(execFile);
+export const hostLockScript = join(process.cwd(), 'packages/vouchington-tooling/scripts/host-lock/with-host-lock.sh');
+const testHomes = [];
+export async function makeHome() {
+    const home = await mkdtemp(join(tmpdir(), 'host-lock-'));
+    testHomes.push(home);
+    return home;
+}
+function hostLockRoot(home) {
+    return join(home, '.cache/host-lock');
+}
+export function hostLockEnv(home, overrides = {}) {
+    return {
+        ...process.env,
+        HOME: home,
+        HOST_LOCK_ROOT: hostLockRoot(home),
+        ...overrides,
+    };
+}
+export function hostLockArgs(name, timeoutSeconds, command, extraArgs = []) {
+    return [
+        hostLockScript,
+        '--name',
+        name,
+        '--timeout-seconds',
+        String(timeoutSeconds),
+        ...extraArgs,
+        '--',
+        ...command,
+    ];
+}
+export function spawnHostLock(home, name, timeoutSeconds, command, env = {}, extraArgs = []) {
+    return spawn('bash', hostLockArgs(name, timeoutSeconds, command, extraArgs), {
+        env: hostLockEnv(home, env),
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+export function completion(child) {
+    return new Promise((resolve, reject) => {
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ code, stderr }));
+    });
+}
+export async function waitForPath(path) {
+    const deadline = Date.now() + 5e3;
+    while (Date.now() < deadline) {
+        try {
+            await stat(path);
+            return;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    throw new Error(`Timed out waiting for ${path}`);
+}
+export async function cleanupTestHomes() {
+    await Promise.all(testHomes.splice(0).map((home) => rm(home, { force: true, recursive: true })));
+}
+export async function withFinalTimeoutProbe(home, assertProbe) {
+    const lock = join(home, '.cache/host-lock/expensive-build.lock.d');
+    const sleepBin = join(home, 'sleep-bin');
+    const acquisitionWaitMarker = join(home, 'acquisition-wait-started');
+    const acquisitionWaitRelease = join(home, 'acquisition-wait-release');
+    const marker = join(home, 'ran');
+    const acquireTimeoutS = 2;
+    const { stdout: realSleep } = await execFileAsync('which', ['sleep']);
+    const owner = spawn(realSleep.trim(), ['30'], { stdio: 'ignore' });
+    const ownerDone = completion(owner);
+    let contender;
+    let contenderDone;
+    try {
+        if (owner.pid == null)
+            throw new Error('Could not start final-timeout-probe owner.');
+        await mkdir(lock, { recursive: true });
+        await Promise.all([
+            writeFile(join(lock, 'owner.pid'), `${owner.pid}\n`),
+            writeFile(join(lock, 'owner.token'), 'live-owner\n'),
+            mkdir(sleepBin),
+        ]);
+        const sleepShim = join(sleepBin, 'sleep');
+        await writeFile(sleepShim, String.raw `#!/usr/bin/env bash
+if [ ! -f "$HOST_LOCK_ACQUISITION_WAIT_RELEASE" ] && [ "$#" -eq 1 ] && [[ "$1" =~ ^[0-9]*[1-9][0-9]*$ ]]; then
+  : >"$HOST_LOCK_ACQUISITION_WAIT_MARKER"
+  while [ ! -f "$HOST_LOCK_ACQUISITION_WAIT_RELEASE" ]; do
+    "$HOST_LOCK_REAL_SLEEP" 0.02
+  done
+fi
+exec "$HOST_LOCK_REAL_SLEEP" "$@"
+`, { mode: 0o755 });
+        contender = spawnHostLock(home, 'expensive-build', acquireTimeoutS, ['touch', marker], {
+            PATH: `${sleepBin}:${process.env.PATH ?? ''}`,
+            HOST_LOCK_REAL_SLEEP: realSleep.trim(),
+            HOST_LOCK_ACQUISITION_WAIT_MARKER: acquisitionWaitMarker,
+            HOST_LOCK_ACQUISITION_WAIT_RELEASE: acquisitionWaitRelease,
+        });
+        const activeContenderDone = completion(contender);
+        contenderDone = activeContenderDone;
+        await waitForPath(acquisitionWaitMarker);
+        owner.kill('SIGTERM');
+        await Promise.all([
+            ownerDone,
+            new Promise((resolve) => setTimeout(resolve, acquireTimeoutS * 1000 + 200)),
+        ]);
+        await writeFile(acquisitionWaitRelease, '');
+        const probe = { lock, marker, contenderDone: activeContenderDone };
+        await assertProbe(probe);
+    }
+    finally {
+        await writeFile(acquisitionWaitRelease, '').catch(() => undefined);
+        owner.kill('SIGKILL');
+        contender?.kill('SIGKILL');
+        await Promise.all([ownerDone, ...(contenderDone ? [contenderDone] : [])]);
+    }
+}

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
+export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
+export { extractAlterTableAddColumnLocations, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, } from './sql-ast/index.mts';

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';
+export { extractAlterTableAddColumnLocations, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, } from './sql-ast/index.mjs';

package/dist/package-version.d.mts

@@ -0,0 +1 @@
+export declare function readPackageVersion(parsed: unknown): string;

package/dist/package-version.mjs

@@ -0,0 +1,9 @@
+export function readPackageVersion(parsed) {
+    if (typeof parsed !== 'object' || parsed === null || !('version' in parsed)) {
+        throw new Error('package.json is missing version');
+    }
+    const { version } = parsed;
+    if (typeof version !== 'string')
+        throw new Error('package.json version must be a string');
+    return version;
+}

package/dist/runner-port-policy/index.d.mts

@@ -0,0 +1,25 @@
+import type { Server } from 'node:net';
+export interface RunnerPortPolicy {
+    reservedPortStart: number;
+    reservedPortEnd: number;
+    portsPerRunner: number;
+    minimumRunnerSlot: number;
+    maximumRunnerSlot: number;
+}
+type ListenOnHost = (server: Server, host: string) => Promise<void>;
+export interface EphemeralListenerOptions {
+    isAllowedPort?: (port: number) => boolean;
+    listen?: ListenOnHost;
+    maxBindAttempts?: number;
+    policy?: RunnerPortPolicy;
+}
+export declare class EphemeralListenerAttemptsExhaustedError extends Error {
+    readonly maxBindAttempts: number;
+    constructor(maxBindAttempts: number);
+}
+export declare const runnerPortPolicy: RunnerPortPolicy;
+export declare function isRunnerReservedPort(port: number, policy?: RunnerPortPolicy): boolean;
+export declare function listenOnRunnerUnreservedEphemeralPort(server: Server, host: string, options?: EphemeralListenerOptions): Promise<number>;
+export declare function loadRunnerPortPolicy(policyUrl?: URL): RunnerPortPolicy;
+export declare function validateRunnerPortPolicy(parsedPolicy: unknown, policyUrl?: URL): RunnerPortPolicy;
+export {};

package/dist/runner-port-policy/index.mjs

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+const shippedPolicyUrl = new URL('runner-port-policy.json', import.meta.url);
+const MAX_EPHEMERAL_BIND_ATTEMPTS = 100;
+export class EphemeralListenerAttemptsExhaustedError extends Error {
+    maxBindAttempts;
+    constructor(maxBindAttempts) {
+        super(`Failed to bind an allowed port outside the reserved runner range after ${maxBindAttempts} attempts`);
+        this.name = 'EphemeralListenerAttemptsExhaustedError';
+        this.maxBindAttempts = maxBindAttempts;
+    }
+}
+export const runnerPortPolicy = loadRunnerPortPolicy();
+export function isRunnerReservedPort(port, policy = runnerPortPolicy) {
+    return port >= policy.reservedPortStart && port <= policy.reservedPortEnd;
+}
+export async function listenOnRunnerUnreservedEphemeralPort(server, host, options = {}) {
+    const policy = options.policy ?? runnerPortPolicy;
+    const maxBindAttempts = options.maxBindAttempts ?? MAX_EPHEMERAL_BIND_ATTEMPTS;
+    for (let attempt = 0; attempt < maxBindAttempts; attempt += 1) {
+        await (options.listen ?? listenOnHost)(server, host);
+        const port = getBoundPort(server);
+        if (!isRunnerReservedPort(port, policy) && (options.isAllowedPort?.(port) ?? true)) {
+            return port;
+        }
+        await closeServer(server);
+    }
+    throw new EphemeralListenerAttemptsExhaustedError(maxBindAttempts);
+}
+export function loadRunnerPortPolicy(policyUrl = shippedPolicyUrl) {
+    return validateRunnerPortPolicy(JSON.parse(readFileSync(policyUrl, 'utf8')), policyUrl);
+}
+export function validateRunnerPortPolicy(parsedPolicy, policyUrl) {
+    if (typeof parsedPolicy !== 'object' || parsedPolicy === null || Array.isArray(parsedPolicy)) {
+        throwInvalidPolicy(policyUrl);
+    }
+    const policy = parsedPolicy;
+    const requiredKeys = [
+        'reservedPortStart',
+        'reservedPortEnd',
+        'portsPerRunner',
+        'minimumRunnerSlot',
+        'maximumRunnerSlot',
+    ];
+    if (Object.keys(policy).length !== requiredKeys.length ||
+        requiredKeys.some((key) => !Number.isInteger(policy[key]))) {
+        throwInvalidPolicy(policyUrl);
+    }
+    const validatedPolicy = policy;
+    const { reservedPortStart: start, reservedPortEnd: end, portsPerRunner, minimumRunnerSlot, maximumRunnerSlot, } = validatedPolicy;
+    if (start < 1 ||
+        end > 65_535 ||
+        start > end ||
+        portsPerRunner <= 0 ||
+        minimumRunnerSlot !== 1 ||
+        maximumRunnerSlot < minimumRunnerSlot ||
+        end - start + 1 !== portsPerRunner * maximumRunnerSlot) {
+        throwInvalidPolicy(policyUrl);
+    }
+    return Object.freeze(validatedPolicy);
+}
+function throwInvalidPolicy(policyUrl) {
+    const location = policyUrl?.pathname ?? 'runner-port-policy';
+    throw new Error(`Invalid CI runner port policy at ${location}`);
+}
+function listenOnHost(server, host) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+}
+function getBoundPort(server) {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to allocate listener port');
+    }
+    return address.port;
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}

package/dist/runner-port-policy/runner-port-policy.json

@@ -0,0 +1,7 @@
+{
+  "reservedPortStart": 2200,
+  "reservedPortEnd": 2999,
+  "portsPerRunner": 16,
+  "minimumRunnerSlot": 1,
+  "maximumRunnerSlot": 50
+}

package/dist/sql-ast/index.d.mts

@@ -0,0 +1,12 @@
+type LibPgQuery = typeof import('@libpg-query/parser');
+export declare class MissingSqlAstParserError extends Error {
+    constructor();
+}
+export declare function extractAlterTableAddColumnLocations(content: string): number[];
+/**
+ * Ensures the @libpg-query/parser WASM module is loaded.
+ * Must be awaited once before any synchronous parseSync() calls.
+ */
+export declare function initSqlAst(importer?: () => Promise<LibPgQuery>): Promise<void>;
+export declare function lineOfUtf8ByteOffset(content: string | Buffer, byteOffset: number): number;
+export {};

package/dist/sql-ast/index.mjs

@@ -0,0 +1,79 @@
+let parser;
+let moduleLoad;
+export class MissingSqlAstParserError extends Error {
+    constructor() {
+        super('vouchington-tooling/sql-ast requires the optional dependency @libpg-query/parser. Install it in the consuming package.');
+        this.name = 'MissingSqlAstParserError';
+    }
+}
+export function extractAlterTableAddColumnLocations(content) {
+    const locations = [];
+    const parseResult = requireParser().parseSync(content);
+    for (const rawStmt of parseResult.stmts ?? []) {
+        const node = rawStmt.stmt;
+        if (!node || !('AlterTableStmt' in node))
+            continue;
+        for (const rawCommand of node.AlterTableStmt.cmds ?? []) {
+            if (!rawCommand || !('AlterTableCmd' in rawCommand))
+                continue;
+            const command = rawCommand.AlterTableCmd;
+            if (command.subtype !== 'AT_AddColumn')
+                continue;
+            const definition = command.def;
+            if (!definition || !('ColumnDef' in definition))
+                continue;
+            locations.push(rawStmt.stmt_location ?? 0);
+        }
+    }
+    return locations;
+}
+/**
+ * Ensures the @libpg-query/parser WASM module is loaded.
+ * Must be awaited once before any synchronous parseSync() calls.
+ */
+export function initSqlAst(importer = () => import('@libpg-query/parser')) {
+    return (moduleLoad ??= loadParser(importer)
+        .then(async (loaded) => {
+        await loaded.loadModule();
+        parser = loaded;
+    })
+        .catch((error) => {
+        moduleLoad = undefined;
+        parser = undefined;
+        throw error;
+    }));
+}
+export function lineOfUtf8ByteOffset(content, byteOffset) {
+    const buffer = typeof content === 'string' ? Buffer.from(content, 'utf8') : content;
+    if (byteOffset > buffer.length) {
+        throw new RangeError(`byteOffset ${byteOffset} is out of range for buffer length ${buffer.length}`);
+    }
+    let line = 1;
+    for (let i = 0; i < byteOffset; i++) {
+        if (buffer[i] === 10)
+            line++;
+    }
+    return line;
+}
+function requireParser() {
+    if (!parser) {
+        throw new Error('initSqlAst() must be awaited before calling parse helpers');
+    }
+    return parser;
+}
+async function loadParser(importer) {
+    try {
+        return await importer();
+    }
+    catch (error) {
+        if (isModuleNotFound(error))
+            throw new MissingSqlAstParserError();
+        throw error;
+    }
+}
+function isModuleNotFound(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ERR_MODULE_NOT_FOUND');
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "vouchington-tooling",
+  "version": "0.0.0",
+  "description": "Vouchington CLI and extractable tooling libraries.",
+  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-tooling/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-tooling.git",
+    "directory": "packages/vouchington-tooling"
+  },
+  "bin": {
+    "vouchington": "dist/cli/index.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./runner-port-policy": {
+      "types": "./dist/runner-port-policy/index.d.mts",
+      "import": "./dist/runner-port-policy/index.mjs",
+      "default": "./dist/runner-port-policy/index.mjs"
+    },
+    "./sql-ast": {
+      "types": "./dist/sql-ast/index.d.mts",
+      "import": "./dist/sql-ast/index.mjs",
+      "default": "./dist/sql-ast/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "optionalDependencies": {
+    "@libpg-query/parser": "^17.6.10"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process'
+import { chmod, copyFile, mkdir, rm } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = new URL('..', import.meta.url)
+const dist = new URL('../dist', import.meta.url)
+
+await rm(dist, { recursive: true, force: true })
+execFileSync('tsc', ['--project', 'tsconfig.build.json'], {
+  stdio: 'inherit',
+  cwd: fileURLToPath(packageRoot),
+})
+await mkdir(new URL('../dist/runner-port-policy', import.meta.url), { recursive: true })
+await copyFile(
+  new URL('../src/runner-port-policy/runner-port-policy.json', import.meta.url),
+  new URL('../dist/runner-port-policy/runner-port-policy.json', import.meta.url),
+)
+await chmod(new URL('../dist/cli/index.mjs', import.meta.url), 0o755)

package/scripts/host-lock/with-host-lock.sh

@@ -0,0 +1,537 @@
+#!/usr/bin/env bash
+
+set -u
+
+usage() {
+  echo 'usage: with-host-lock.sh --name <family> [--slots <positive-int>] --timeout-seconds <positive-int> [--command-timeout-seconds <nonnegative-int>] [--failure-diagnostics <absolute-script-path>] [--on-acquire-timeout fail|run-unlocked] -- <command> [args...]' >&2
+}
+
+fail() {
+  echo "with-host-lock: $1" >&2
+  exit 2
+}
+
+[ -z "${HOST_LOCK_ACTIVE:-}" ] || fail 'nested host locks are not allowed'
+
+name=''
+slot_count=1
+slots_explicit=0
+timeout_seconds=''
+command_timeout_seconds=0
+failure_diagnostics=''
+on_acquire_timeout=fail
+process_group_drain_seconds=${HOST_LOCK_PROCESS_GROUP_DRAIN_SECONDS:-30}
+lease_seconds=${HOST_LOCK_LEASE_SECONDS:-60}
+
+case "$process_group_drain_seconds" in
+  '' | *[!0-9]*) fail 'HOST_LOCK_PROCESS_GROUP_DRAIN_SECONDS must be a nonnegative integer' ;;
+esac
+
+case "$lease_seconds" in
+  '' | *[!0-9]*) fail 'HOST_LOCK_LEASE_SECONDS must be a positive integer of at least 4' ;;
+esac
+[ "$lease_seconds" -ge 4 ] || fail 'HOST_LOCK_LEASE_SECONDS must be a positive integer of at least 4'
+# Refresh at a quarter of the lease so three consecutive missed refreshes still
+# precede expiry; the margin survives any change to the lease.
+lease_refresh_seconds=$((lease_seconds / 4))
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --name)
+      [ "$#" -ge 2 ] || fail '--name requires a lock family name'
+      name=$2
+      shift 2
+      ;;
+    --slots)
+      [ "$#" -ge 2 ] || fail '--slots requires a positive integer'
+      slot_count=$2
+      slots_explicit=1
+      shift 2
+      ;;
+    --timeout-seconds)
+      [ "$#" -ge 2 ] || fail '--timeout-seconds requires a positive integer'
+      timeout_seconds=$2
+      shift 2
+      ;;
+    --command-timeout-seconds)
+      [ "$#" -ge 2 ] || fail '--command-timeout-seconds requires a nonnegative integer'
+      command_timeout_seconds=$2
+      shift 2
+      ;;
+    --failure-diagnostics)
+      [ "$#" -ge 2 ] || fail '--failure-diagnostics requires an absolute script path'
+      failure_diagnostics=$2
+      shift 2
+      ;;
+    --on-acquire-timeout)
+      [ "$#" -ge 2 ] || fail "--on-acquire-timeout requires 'fail' or 'run-unlocked'"
+      on_acquire_timeout=$2
+      shift 2
+      ;;
+    --)
+      shift
+      break
+      ;;
+    *)
+      usage
+      fail "unknown argument: $1"
+      ;;
+  esac
+done
+
+[ -n "$name" ] || {
+  usage
+  fail 'missing --name'
+}
+case "$name" in
+  *[!A-Za-z0-9._-]* | '' | [.-]*) fail "invalid lock family name: $name" ;;
+esac
+
+case "$slot_count" in
+  '' | *[!0-9]* | 0) fail '--slots must be a positive integer' ;;
+esac
+
+case "$timeout_seconds" in
+  '' | *[!0-9]* | 0) fail '--timeout-seconds must be a positive integer' ;;
+esac
+
+case "$command_timeout_seconds" in
+  '' | *[!0-9]*) fail '--command-timeout-seconds must be a nonnegative integer' ;;
+esac
+
+case "$failure_diagnostics" in
+  '') ;;
+  /*) ;;
+  *) fail '--failure-diagnostics must be an absolute script path' ;;
+esac
+
+case "$on_acquire_timeout" in
+  fail | run-unlocked) ;;
+  *) fail "--on-acquire-timeout must be 'fail' or 'run-unlocked'" ;;
+esac
+
+[ "$#" -gt 0 ] || {
+  usage
+  fail 'missing command after --'
+}
+
+run_failure_diagnostics() {
+  [ -n "$failure_diagnostics" ] || return 0
+  bash "$failure_diagnostics" || true
+}
+
+lock_root=${HOST_LOCK_ROOT:-/tmp/host-lock-$UID}
+case "$lock_root" in
+  /*) ;;
+  *) fail 'HOST_LOCK_ROOT must be an absolute path' ;;
+esac
+selected_name=$name
+lock_dir=''
+reap_dir=''
+
+select_slot() {
+  slot_number=$1
+  if [ "$slots_explicit" -eq 0 ]; then
+    selected_name=$name
+  else
+    selected_name=$name-slot-$slot_number
+  fi
+  lock_dir=$lock_root/$selected_name.lock.d
+  reap_dir=$lock_root/$selected_name.lock.reap.d
+}
+
+[ ! -L "$lock_root" ] || fail "lock root must not be a symbolic link: $lock_root"
+old_umask=$(umask)
+umask 077
+mkdir -p "$lock_root" || fail "cannot create lock root: $lock_root"
+umask "$old_umask"
+[ ! -L "$lock_root" ] || fail "lock root must not be a symbolic link: $lock_root"
+lock_root_uid=$(stat -f '%u' "$lock_root" 2>/dev/null) ||
+  lock_root_uid=$(stat -c '%u' "$lock_root" 2>/dev/null) ||
+  fail "cannot inspect lock root ownership: $lock_root"
+[ "$lock_root_uid" = "$UID" ] || fail "lock root is not owned by uid $UID: $lock_root"
+chmod 700 "$lock_root" || fail "cannot make lock root private: $lock_root"
+
+process_is_live() {
+  candidate_pid=$1
+  candidate_kill_error=$(kill -0 "$candidate_pid" 2>&1) && return 0
+  case "$candidate_kill_error" in
+    *[Oo]peration*not*permitted* | *[Pp]ermission*denied*) return 0 ;;
+  esac
+  ps -p "$candidate_pid" -o pid= 2>/dev/null | awk 'NF { found = 1 } END { exit !found }'
+}
+
+process_group_is_live() {
+  candidate_pgid=$1
+  candidate_kill_error=$(kill -0 -- "-$candidate_pgid" 2>&1) && return 0
+  case "$candidate_kill_error" in
+    *[Oo]peration*not*permitted* | *[Pp]ermission*denied*) return 0 ;;
+  esac
+  ps -e -o pgid= 2>/dev/null |
+    awk -v candidate_pgid="$candidate_pgid" '$1 == candidate_pgid { found = 1; exit } END { exit !found }'
+}
+
+directory_mtime() {
+  directory=$1
+  mtime=$(stat -f '%m' "$directory" 2>/dev/null) ||
+    mtime=$(stat -c '%Y' "$directory" 2>/dev/null) || return 1
+  case "$mtime" in
+    '' | *[!0-9]*) return 1 ;;
+  esac
+  printf '%s\n' "$mtime"
+}
+
+owned_directory_is_stale() {
+  owned_directory=$1
+  ownerless_grace_seconds=$2
+  valid_owner_metadata=0
+  if [ -f "$owned_directory/owner.pid" ] || [ -f "$owned_directory/owner.pgid" ]; then
+    recorded_pid=$(sed -n '1p' "$owned_directory/owner.pid" 2>/dev/null || true)
+    case "$recorded_pid" in
+      '' | *[!0-9]*) ;;
+      *)
+        valid_owner_metadata=1
+        process_is_live "$recorded_pid" && return 1
+        ;;
+    esac
+    recorded_pgid=$(sed -n '1p' "$owned_directory/owner.pgid" 2>/dev/null || true)
+    case "$recorded_pgid" in
+      '' | *[!0-9]*) ;;
+      *)
+        valid_owner_metadata=1
+        process_group_is_live "$recorded_pgid" && return 1
+        ;;
+    esac
+    [ "$valid_owner_metadata" -eq 0 ] || return 0
+  fi
+
+  mtime=$(directory_mtime "$owned_directory") || return 1
+  now=$(date +%s)
+  [ $((now - mtime)) -gt "$ownerless_grace_seconds" ]
+}
+
+reaper_owner_pid=''
+reaper_owner_token=''
+
+owns_reaper() {
+  current_reaper_pid=$(sed -n '1p' "$reap_dir/owner.pid" 2>/dev/null || true)
+  current_reaper_token=$(sed -n '1p' "$reap_dir/owner.token" 2>/dev/null || true)
+  [ "$current_reaper_pid" = "$reaper_owner_pid" ] &&
+    [ "$current_reaper_token" = "$reaper_owner_token" ]
+}
+
+cleanup_reaper() {
+  if [ -n "$reaper_owner_token" ] && owns_reaper; then
+    rm -rf "$reap_dir"
+  fi
+  reaper_owner_pid=''
+  reaper_owner_token=''
+}
+
+recover_stale_reaper() {
+  [ -d "$reap_dir" ] || return 0
+  stale_reaper_pid=$(sed -n '1p' "$reap_dir/owner.pid" 2>/dev/null || true)
+  stale_reaper_token=$(sed -n '1p' "$reap_dir/owner.token" 2>/dev/null || true)
+  owned_directory_is_stale "$reap_dir" 10 || return 1
+
+  current_reaper_pid=$(sed -n '1p' "$reap_dir/owner.pid" 2>/dev/null || true)
+  current_reaper_token=$(sed -n '1p' "$reap_dir/owner.token" 2>/dev/null || true)
+  if [ "$current_reaper_pid" = "$stale_reaper_pid" ] &&
+    [ "$current_reaper_token" = "$stale_reaper_token" ]; then
+    rm -rf "$reap_dir"
+  fi
+}
+
+# Owner liveness may only accelerate reclamation, never delay it past the lease:
+# owned_directory_is_stale reclaims a provably-dead or metadata-less owner
+# immediately, and the mtime check below is an unconditional ceiling regardless
+# of what the owner metadata claims. This is what recovers a crash that killed
+# the wrapper between `mkdir "$lock_dir"` and the owner.pid/owner.token writes
+# (dead-but-valid metadata reclaims immediately; ownerless metadata otherwise
+# would not) and a live-but-stale holder whose PID has been reused by the OS.
+lock_is_reclaimable() {
+  owned_directory_is_stale "$lock_dir" "$lease_seconds" && return 0
+  mtime=$(directory_mtime "$lock_dir") || return 1
+  [ $(($(date +%s) - mtime)) -gt "$lease_seconds" ]
+}
+
+reclaim_stale_lock() {
+  recover_stale_reaper || true
+  mkdir "$reap_dir" 2>/dev/null || return 1
+  reaper_owner_pid=$$
+  reaper_owner_token="reaper-$$-$(date +%s)-$RANDOM"
+  printf '%s\n' "$reaper_owner_pid" >"$reap_dir/owner.pid"
+  printf '%s\n' "$reaper_owner_token" >"$reap_dir/owner.token"
+
+  if [ -d "$lock_dir" ] && lock_is_reclaimable && owns_reaper; then
+    rm -rf "$lock_dir"
+  fi
+  cleanup_reaper
+}
+
+try_acquire_selected_slot() {
+  [ ! -d "$reap_dir" ] || return 1
+  mkdir "$lock_dir" 2>/dev/null || return 1
+  acquired=1
+}
+
+report_acquire_timeout_owners() {
+  waited_seconds=$(($(date +%s) - start_time))
+  slot_number=1
+  while [ "$slot_number" -le "$slot_count" ]; do
+    select_slot "$slot_number"
+    recorded_pid=$(sed -n '1p' "$lock_dir/owner.pid" 2>/dev/null || true)
+    recorded_pgid=$(sed -n '1p' "$lock_dir/owner.pgid" 2>/dev/null || true)
+    case "$recorded_pid" in
+      '' | *[!0-9]*) recorded_pid=missing ;;
+    esac
+    case "$recorded_pgid" in
+      '' | *[!0-9]*) recorded_pgid=missing ;;
+    esac
+    echo "with-host-lock: $name waited ${waited_seconds}s; $selected_name owner pid=$recorded_pid pgid=$recorded_pgid" >&2
+    slot_number=$((slot_number + 1))
+  done
+}
+
+start_time=$(date +%s)
+deadline=$((start_time + timeout_seconds))
+acquired=0
+
+while :; do
+  slot_number=1
+  while [ "$slot_number" -le "$slot_count" ]; do
+    select_slot "$slot_number"
+    try_acquire_selected_slot && break
+    reclaim_stale_lock || true
+    try_acquire_selected_slot && break
+    slot_number=$((slot_number + 1))
+  done
+  [ "$acquired" -eq 0 ] || break
+
+  now=$(date +%s)
+  if [ "$now" -ge "$deadline" ]; then
+    if [ "$on_acquire_timeout" = 'run-unlocked' ]; then
+      echo "with-host-lock: $name lock not acquired within ${timeout_seconds}s; running unlocked" >&2
+      report_acquire_timeout_owners
+      break
+    fi
+    echo "with-host-lock: $name lock not acquired within ${timeout_seconds}s" >&2
+    report_acquire_timeout_owners
+    run_failure_diagnostics
+    exit 1
+  fi
+  remaining_seconds=$((deadline - now))
+  sleep_seconds=2
+  if [ "$remaining_seconds" -lt "$sleep_seconds" ]; then
+    sleep_seconds=$remaining_seconds
+  fi
+  [ "$sleep_seconds" -gt 0 ] && sleep "$sleep_seconds"
+done
+
+owner_pid=$$
+owner_token=''
+temporary_start_release=''
+if [ "$acquired" -eq 1 ]; then
+  owner_token="$$-$(date +%s)-$RANDOM"
+  printf '%s\n' "$owner_pid" >"$lock_dir/owner.pid"
+  printf '%s\n' "$owner_token" >"$lock_dir/owner.token"
+  waited_seconds=$(($(date +%s) - start_time))
+  echo "with-host-lock: $name acquired after ${waited_seconds}s" >&2
+fi
+
+cleanup_lock() {
+  stop_lease_heartbeat
+  if [ -n "$temporary_start_release" ]; then
+    rm -f "$temporary_start_release" 2>/dev/null || true
+    temporary_start_release=''
+  fi
+  [ "$acquired" -eq 1 ] || return 0
+  current_pid=$(sed -n '1p' "$lock_dir/owner.pid" 2>/dev/null || true)
+  current_token=$(sed -n '1p' "$lock_dir/owner.token" 2>/dev/null || true)
+  if [ "$current_pid" = "$owner_pid" ] && [ "$current_token" = "$owner_token" ]; then
+    rm -rf "$lock_dir"
+  fi
+  acquired=0
+}
+
+child_pid=''
+signal_forwarded=0
+pending_signal=''
+watchdog_pid=''
+command_timeout_marker=''
+lease_heartbeat_pid=''
+
+# shellcheck disable=SC2329 # Invoked by the INT and TERM traps below.
+forward_signal() {
+  pending_signal=$1
+  if [ -n "$child_pid" ]; then
+    kill -s "$pending_signal" -- "-$child_pid" 2>/dev/null || true
+  fi
+}
+
+wait_for_process_group_until() {
+  deadline=$1
+  while process_group_is_live "$child_pid"; do
+    [ "$(date +%s)" -lt "$deadline" ] || return 1
+    sleep 0.1
+  done
+}
+
+# Escalates TERM then KILL against the command's process group, giving it up to
+# grace_seconds to drain at each step. Shared by the post-command drain below and
+# by the command-timeout watchdog, so there is exactly one kill/verify sequence.
+terminate_process_group() {
+  grace_seconds=$1
+  kill -s TERM -- "-$child_pid" 2>/dev/null || true
+  term_deadline=$(($(date +%s) + grace_seconds))
+  wait_for_process_group_until "$term_deadline" && return 0
+  kill -s KILL -- "-$child_pid" 2>/dev/null || true
+  kill_deadline=$(($(date +%s) + grace_seconds))
+  wait_for_process_group_until "$kill_deadline"
+}
+
+start_command_timeout_watchdog() {
+  [ "$command_timeout_seconds" -gt 0 ] || return 0
+  # Create a unique marker filename without leaving a file behind — the
+  # watchdog recreates it via : > only when the timeout actually fires.
+  command_timeout_marker=$(mktemp "${TMPDIR:-/tmp}/with-host-lock-timeout.XXXXXX") ||
+    fail 'cannot create command-timeout marker file'
+  rm -f "$command_timeout_marker"
+  set -m
+  (
+    sleep "$command_timeout_seconds"
+    if kill -0 "$child_pid" 2>/dev/null; then
+      : >"$command_timeout_marker"
+      echo "with-host-lock: $name command exceeded ${command_timeout_seconds}s; terminating its process group" >&2
+      terminate_process_group 5 || true
+    fi
+  ) &
+  watchdog_pid=$!
+  set +m
+}
+
+stop_command_timeout_watchdog() {
+  [ -n "$watchdog_pid" ] || return 0
+  kill -s KILL -- "-$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+  watchdog_pid=''
+}
+
+# Keeps the held lock directory's mtime within the reclamation lease while this
+# wrapper owns it. Re-reads the lock metadata every tick (rather than trusting a
+# snapshot) so it stops touching as soon as the lock is reclaimed, handed to a
+# replacement owner, or its recorded owner dies — an orphaned heartbeat must let
+# the lease lapse, not hold it open forever.
+#
+# Closes its own stdout/stderr instead of inheriting the wrapper's: a SIGKILL of
+# the wrapper cannot run the EXIT trap that would otherwise stop this subshell,
+# so it can outlive the wrapper as an orphan. An orphan that still held the
+# wrapper's piped stdout/stderr open would wedge any caller waiting on those
+# pipes to reach EOF (e.g. a `child_process` "close" event) until the command it
+# is heartbeating for eventually exits too.
+start_lease_heartbeat() {
+  [ "$acquired" -eq 1 ] || return 0
+  set -m
+  (
+    while sleep "$lease_refresh_seconds"; do
+      current_token=$(sed -n '1p' "$lock_dir/owner.token" 2>/dev/null || true)
+      [ "$current_token" = "$owner_token" ] || exit 0
+      current_pid=$(sed -n '1p' "$lock_dir/owner.pid" 2>/dev/null || true)
+      current_pgid=$(sed -n '1p' "$lock_dir/owner.pgid" 2>/dev/null || true)
+      owner_live=0
+      case "$current_pid" in
+        '' | *[!0-9]*) ;;
+        *) process_is_live "$current_pid" && owner_live=1 ;;
+      esac
+      case "$current_pgid" in
+        '' | *[!0-9]*) ;;
+        *) process_group_is_live "$current_pgid" && owner_live=1 ;;
+      esac
+      [ "$owner_live" -eq 1 ] || exit 0
+      touch "$lock_dir" 2>/dev/null || exit 0
+    done
+  ) </dev/null >/dev/null 2>&1 &
+  lease_heartbeat_pid=$!
+  set +m
+}
+
+stop_lease_heartbeat() {
+  [ -n "$lease_heartbeat_pid" ] || return 0
+  kill -s KILL -- "-$lease_heartbeat_pid" 2>/dev/null || true
+  wait "$lease_heartbeat_pid" 2>/dev/null || true
+  lease_heartbeat_pid=''
+}
+
+trap cleanup_lock EXIT
+trap 'signal_forwarded=1; forward_signal INT' INT
+trap 'signal_forwarded=1; forward_signal TERM' TERM
+
+if [ "$acquired" -eq 1 ]; then
+  start_release=$lock_dir/start.release
+else
+  start_release=$(mktemp "${TMPDIR:-/tmp}/with-host-lock-release.XXXXXX") ||
+    fail 'cannot create release marker file'
+  temporary_start_release=$start_release
+fi
+
+export HOST_LOCK_ACTIVE=1
+
+# Job control keeps an asynchronous command's SIGINT disposition intact. Without
+# it, non-interactive Bash starts background commands with SIGINT ignored.
+set -m
+bash -c '
+  wrapper_pid=$1
+  start_release=$2
+  shift 2
+  while [ ! -f "$start_release" ]; do
+    kill -0 "$wrapper_pid" 2>/dev/null || exit 1
+    sleep 0.05
+  done
+  exec "$@"
+' with-host-lock-child "$$" "$start_release" "$@" &
+child_pid=$!
+if [ "$acquired" -eq 1 ]; then
+  owner_pid=$child_pid
+  printf '%s\n' "$owner_pid" >"$lock_dir/owner.pid"
+  printf '%s\n' "$child_pid" >"$lock_dir/owner.pgid"
+fi
+: >"$start_release"
+if [ -n "$pending_signal" ]; then
+  kill -s "$pending_signal" -- "-$child_pid" 2>/dev/null || true
+fi
+set +m
+
+start_command_timeout_watchdog
+start_lease_heartbeat
+
+while :; do
+  signal_forwarded=0
+  wait "$child_pid"
+  status=$?
+  if [ "$signal_forwarded" -eq 0 ] || ! kill -0 "$child_pid" 2>/dev/null; then
+    break
+  fi
+done
+
+stop_command_timeout_watchdog
+
+process_group_drain_deadline=$(($(date +%s) + process_group_drain_seconds))
+if ! wait_for_process_group_until "$process_group_drain_deadline"; then
+  echo "with-host-lock: $name command left processes running; terminating its process group" >&2
+  if ! terminate_process_group 5; then
+    echo "with-host-lock: $name process group survived SIGKILL; retaining lock ownership" >&2
+    acquired=0
+    exit 1
+  fi
+fi
+
+if [ -n "$command_timeout_marker" ] && [ -f "$command_timeout_marker" ]; then
+  status=124
+fi
+if [ "$status" -ne 0 ]; then
+  run_failure_diagnostics
+fi
+[ -z "$command_timeout_marker" ] || rm -f "$command_timeout_marker" 2>/dev/null || true
+cleanup_lock
+trap - EXIT INT TERM
+exit "$status"