@haywoodmarx/agent-pager 0.1.0

package/dist/src/launch/broker-lock.js

@@ -0,0 +1,644 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { PROTOCOL_VERSION, ProtocolError, SCHEMA_MARKER } from "../broker/protocol.js";
+import { LOOPBACK_HOST } from "../configuration-defaults.js";
+import { PAGER_VERSION } from "../version.js";
+import { satisfiesBunVersionFloor } from "./runtime.js";
+/** Identifies the ownership schema understood by this release. */
+export const SERVICE_PROTOCOL_VERSION = 1;
+/** Identifies the package build that owns production service state. */
+export const SERVICE_BUILD_ID = `agent-pager@${PAGER_VERSION}`;
+/** Identifies the production runtime required to own SQLite. */
+export const SERVICE_RUNTIME = "bun";
+/**
+ * Returns the identity published by the current Bun service build.
+ * @returns - Runtime, build, and wire-protocol ownership fields.
+ */
+export function currentBrokerServiceIdentity() {
+    return {
+        serviceProtocolVersion: SERVICE_PROTOCOL_VERSION,
+        runtime: SERVICE_RUNTIME,
+        runtimeVersion: Bun.version,
+        buildId: SERVICE_BUILD_ID,
+        protocolVersion: PROTOCOL_VERSION,
+        schemaMarker: SCHEMA_MARKER,
+    };
+}
+/** Sole per-field currency check for {@link BrokerServiceIdentity}. */
+const BROKER_SERVICE_IDENTITY_CHECKS = {
+    serviceProtocolVersion: (actual) => actual === SERVICE_PROTOCOL_VERSION,
+    runtime: (actual) => actual === SERVICE_RUNTIME,
+    runtimeVersion: (actual) => typeof actual === "string" && satisfiesBunVersionFloor(actual),
+    buildId: (actual) => actual === SERVICE_BUILD_ID,
+    protocolVersion: (actual) => actual === PROTOCOL_VERSION,
+    schemaMarker: (actual) => actual === SCHEMA_MARKER,
+};
+function hasCurrentBrokerServiceIdentity(candidate) {
+    return Object.keys(BROKER_SERVICE_IDENTITY_CHECKS).every((field) => BROKER_SERVICE_IDENTITY_CHECKS[field](candidate[field]));
+}
+/**
+ * Report whether a lock belongs to the current production service contract.
+ * @param lock - Candidate lock identity from an untrusted adjacent file.
+ * @returns - True only for the current Bun build and wire protocol.
+ */
+export function brokerLockHasCurrentIdentity(lock) {
+    return lock !== undefined && hasCurrentBrokerServiceIdentity(lock);
+}
+/**
+ * Validate an untrusted health payload against the current service contract.
+ * @param value - Parsed health response or lock-shaped object.
+ * @returns - True when it names a supported Bun and the current build/protocol.
+ */
+export function isCurrentBrokerServiceIdentity(value) {
+    return (typeof value === "object" && value !== null && hasCurrentBrokerServiceIdentity(value));
+}
+/**
+ * Report whether a lock names a live, current-build service that has left its starting epoch.
+ * @param lock - Candidate lock identity from an untrusted adjacent file.
+ * @param isAlive - Operating-system liveness boundary.
+ * @returns - True only for a live service whose published endpoints a reader may use.
+ */
+export function brokerLockIsLive(lock, isAlive) {
+    return lock !== undefined && brokerLockHasCurrentIdentity(lock) && isAlive(lock.pid) && lock.epoch !== "starting";
+}
+/**
+ * Read only the process id from any structurally valid current or legacy lock.
+ * @param lockPath - File containing a candidate ownership record.
+ * @returns - Positive process id when the file carries one.
+ */
+export function readBrokerOwnerPid(lockPath) {
+    return readBrokerOwner(lockPath)?.pid;
+}
+/**
+ * Read the owning process from any structurally valid current or legacy lock.
+ *
+ * Reads only the fields every build has written, so a lock left by a build whose full record this
+ * one no longer accepts still names its owner.
+ * @param lockPath - File containing a candidate ownership record.
+ * @returns - The owner's positive process id, with the start time the lock recorded for it when it
+ *   recorded one.
+ */
+export function readBrokerOwner(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || !("pid" in parsed))
+            return undefined;
+        const { pid } = parsed;
+        if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0)
+            return undefined;
+        const startedAt = "ownerStartedAt" in parsed && typeof parsed.ownerStartedAt === "string" ? parsed.ownerStartedAt : undefined;
+        return { pid, ...(startedAt === undefined ? {} : { startedAt }) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the service lock beside its durable database.
+ * @param databasePath - Durable SQLite file whose owning service publishes the lock.
+ * @returns - Path of the lock file beside the database.
+ */
+export function brokerLockPath(databasePath) {
+    return `${databasePath}.lock`;
+}
+/**
+ * Read a valid broker lock record without importing the SQLite-backed service.
+ * @param lockPath - File containing the candidate lock record.
+ * @returns - Valid parsed lock data when the file is well-formed.
+ */
+export function readBrokerLock(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf8"));
+        return isBrokerLock(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Structural gate, not a currency check: `serviceProtocolVersion`, `runtime`, and `protocolVersion`
+ * must equal the current build's because a mismatch there means the rest of the shape cannot be
+ * trusted to mean what the fields below assume it means. `buildId` and `schemaMarker` identify which
+ * build and database schema wrote the record — readable from a foreign build's lock so a reclaim
+ * decision can report it — so both are shape-checked only; {@link brokerLockHasCurrentIdentity} is
+ * where their currency against the running build is decided.
+ * @param value - Candidate lock record parsed from an untrusted adjacent file.
+ * @returns - True when the value is structurally a lock record this build can read.
+ */
+function isBrokerLock(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "pid" in value &&
+        typeof value.pid === "number" &&
+        Number.isSafeInteger(value.pid) &&
+        value.pid > 0 &&
+        "epoch" in value &&
+        typeof value.epoch === "string" &&
+        "serviceProtocolVersion" in value &&
+        value.serviceProtocolVersion === SERVICE_PROTOCOL_VERSION &&
+        "runtime" in value &&
+        value.runtime === SERVICE_RUNTIME &&
+        "runtimeVersion" in value &&
+        typeof value.runtimeVersion === "string" &&
+        /^\d+\.\d+\.\d+/u.test(value.runtimeVersion) &&
+        "buildId" in value &&
+        typeof value.buildId === "string" &&
+        "protocolVersion" in value &&
+        value.protocolVersion === PROTOCOL_VERSION &&
+        "schemaMarker" in value &&
+        typeof value.schemaMarker === "string" &&
+        (!("holder" in value) || typeof value.holder === "string") &&
+        (!("ownerStartedAt" in value) || typeof value.ownerStartedAt === "string") &&
+        (!("mcpUrl" in value) || isLoopbackUrl(value.mcpUrl, "/mcp")) &&
+        (!("snapshotUrl" in value) || isLoopbackUrl(value.snapshotUrl)) &&
+        (!("operatorUrl" in value) || isLoopbackTcpUrl(value.operatorUrl)));
+}
+function isLoopbackTcpUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "tcp:" &&
+            (url.hostname === LOOPBACK_HOST || url.hostname === "[::1]" || url.hostname === "::1") &&
+            url.pathname === "");
+    }
+    catch {
+        return false;
+    }
+}
+function isLoopbackUrl(value, pathname) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "http:" &&
+            url.hostname === LOOPBACK_HOST &&
+            (pathname === undefined || url.pathname === pathname));
+    }
+    catch {
+        return false;
+    }
+}
+/** Bounds how many times acquisition re-attempts after losing a lock-file race. */
+export const BROKER_LOCK_ACQUISITION_ATTEMPTS = 5;
+/** Sets the entropy of a lock holder token, in bytes. */
+const HOLDER_TOKEN_BYTES = 12;
+/** Delays one re-attempt after losing a lock-file race, in milliseconds. */
+const RECLAIM_RETRY_DELAY_MS = 20;
+/** Names the reading behind a Linux start time, which pairs boot time with ticks since boot. */
+const LINUX_START_TIME_TAG = "l1";
+/** Names the reading behind a macOS start time, which is an instant in milliseconds. */
+const DARWIN_START_TIME_TAG = "d1";
+/** Reports that the lock is held by a live service of the current build. */
+export class BrokerServiceAlreadyRunningError extends ProtocolError {
+    pid;
+    /**
+     * Construct the failure naming the live owner a second service must defer to.
+     * @param pid - Process id recorded by the lock this process could not take.
+     */
+    constructor(
+    /** Identifies the live process that owns the lock. */
+    pid) {
+        super("conflict", `Broker service already running with pid ${String(pid)}`);
+        this.pid = pid;
+        this.name = "BrokerServiceAlreadyRunningError";
+    }
+}
+/** Reports that the lock is held by a live service this build must not displace. */
+export class BrokerServiceLockOwnedError extends ProtocolError {
+    pid;
+    /**
+     * Construct the failure naming the incompatible owner an operator must resolve.
+     * @param pid - Process id recorded by the lock this process could not take.
+     */
+    constructor(
+    /** Identifies the live process that owns the lock. */
+    pid) {
+        super("validation_failed", `Broker service lock is owned by pid ${String(pid)}; run pager exit to stop the legacy or incompatible service, then retry`);
+        this.pid = pid;
+        this.name = "BrokerServiceLockOwnedError";
+    }
+}
+/** Reports that acquisition kept losing the lock file to another writer. */
+export class BrokerLockContendedError extends ProtocolError {
+    lockPath;
+    attempts;
+    blockedBy;
+    /**
+     * Construct the failure that ends a bounded acquisition rather than retrying forever.
+     * @param lockPath - Lock file this process was trying to take.
+     * @param attempts - Number of acquisition attempts that were made and lost.
+     * @param blockedBy - File that was still held or recreated on the final attempt, which is the one
+     * an operator has to deal with and is not always the lock itself.
+     */
+    constructor(
+    /** Names the contended lock file. */
+    lockPath, 
+    /** Records how many attempts were made before giving up. */
+    attempts, 
+    /** Names the file that blocked the final attempt. */
+    blockedBy) {
+        super("conflict", `Broker service lock ${lockPath} could not be taken in ${String(attempts)} attempts because ${blockedBy} ` +
+            `was held or recreated by another writer every time; find and stop whatever owns that file, then retry`);
+        this.lockPath = lockPath;
+        this.attempts = attempts;
+        this.blockedBy = blockedBy;
+        this.name = "BrokerLockContendedError";
+    }
+}
+/** Reports that the lock this process acquired is no longer the one on disk. */
+export class BrokerLockLostError extends ProtocolError {
+    lockPath;
+    /**
+     * Construct the failure that stops a service publishing endpoints it no longer owns.
+     * @param lockPath - Lock file whose holder token stopped matching this acquisition.
+     */
+    constructor(
+    /** Names the lock file this process no longer holds. */
+    lockPath) {
+        super("conflict", `Broker service lock ${lockPath} is no longer held by this process; another service has taken ownership of the database`);
+        this.lockPath = lockPath;
+        this.name = "BrokerLockLostError";
+    }
+}
+/**
+ * Report whether a process id names a running process.
+ * @param pid - Process id to probe.
+ * @returns - True unless the operating system reports no such process.
+ */
+export function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Only ESRCH proves absence. EPERM means the process exists and belongs to another user, and
+        // reclaiming a lock on that evidence would displace a running service.
+        return !isErrno(error, "ESRCH");
+    }
+}
+/**
+ * Read a process's start time from the platform, where the platform can report one.
+ *
+ * The value is tagged with the reading that produced it. A record carrying a tag this build does not
+ * produce describes a moment measured some other way, and comparing the two would be meaningless.
+ * @param pid - Process id to describe.
+ * @returns - The start time, or an explicit absence on a platform that cannot supply one.
+ */
+export function processStartedAt(pid) {
+    try {
+        if (process.platform === "linux") {
+            const stat = readFileSync(`/proc/${String(pid)}/stat`, "utf8");
+            // The command field is parenthesised and may itself contain spaces and brackets, so the
+            // numeric fields are only unambiguous after the last ")".
+            const startTicks = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+            // Those ticks are counted from boot, so processes either side of a reboot can carry the same
+            // count. Pairing them with the boot time makes the reading absolute without needing the
+            // kernel's tick rate.
+            const bootTime = /^btime (\d+)$/mu.exec(readFileSync("/proc/stat", "utf8"))?.[1];
+            return startTicks === undefined || startTicks === "" || bootTime === undefined
+                ? { known: false }
+                : { known: true, value: `${LINUX_START_TIME_TAG}:${bootTime}:${startTicks}` };
+        }
+        if (process.platform === "darwin") {
+            // ps renders lstart through LC_TIME and TZ, so the same process reads differently from a
+            // launchd service and from a user shell. Both are pinned, and the rendering is reduced to an
+            // instant, so no two spellings of one moment can reach a comparison.
+            const rendered = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+            }).trim();
+            const started = Date.parse(`${rendered} UTC`);
+            return Number.isFinite(started)
+                ? { known: true, value: `${DARWIN_START_TIME_TAG}:${String(started)}` }
+                : { known: false };
+        }
+    }
+    catch {
+        return { known: false };
+    }
+    return { known: false };
+}
+/**
+ * Report whether a recorded start time still describes whichever process now holds a process id.
+ * @param recorded - Start time captured when the record was written.
+ * @param actual - Start time read from the platform now.
+ * @returns - False only when both readings are the same kind and disagree.
+ */
+export function startTimeStillMatches(recorded, actual) {
+    if (!actual.known)
+        return true;
+    // Every disagreement this cannot account for has to read as the same process. Reclaiming is the
+    // destructive answer, and a record written by a build that measured start times some other way is
+    // no evidence that the process id has been reused.
+    if (startTimeReading(actual.value) !== startTimeReading(recorded))
+        return true;
+    if (actual.value === recorded)
+        return true;
+    // A Linux reading pairs a boot time with a tick count. The ticks come straight from the process
+    // and are exact, so a difference there is a different process. The boot time is derived from the
+    // clock and two readings of one boot need not agree to the second, so a difference in that alone
+    // says nothing, and the safe answer to saying nothing is to leave the owner alone.
+    if (startTimeReading(actual.value) === LINUX_START_TIME_TAG) {
+        return linuxStartTicks(actual.value) === linuxStartTicks(recorded);
+    }
+    return false;
+}
+function linuxStartTicks(value) {
+    return value.split(":")[2];
+}
+function startTimeReading(value) {
+    const separator = value.indexOf(":");
+    return separator < 0 ? "" : value.slice(0, separator);
+}
+/**
+ * Build the operating-system boundaries used by a production lock acquisition.
+ * @returns - Ports backed by the operating system's process table, a random token source, and a sleep that blocks the thread.
+ */
+export function systemBrokerLockPorts() {
+    return {
+        processIsAlive,
+        processStartedAt,
+        newHolderToken: () => randomBytes(HOLDER_TOKEN_BYTES).toString("hex"),
+        sleep: (milliseconds) => {
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+        },
+    };
+}
+/**
+ * Owns one process's exclusive claim on a broker database.
+ *
+ * Creation links a staged record into place and fails on a name another process holds, so
+ * uncontended acquisition already selects one winner. Reclaiming a stale lock cannot be, because it
+ * spans a read and an unlink: two processes that each read the same dead owner would each remove
+ * whatever lock was present by the time they got to the unlink, including the other's fresh one. A
+ * separate reclaim file, claimed the same way, serialises that span, and the owner is re-read inside
+ * it, so a reclaimer that lost the race sees the winner rather than deleting it.
+ */
+export class BrokerLockGuard {
+    #lockPath;
+    #reclaimPath;
+    #ports;
+    #holder;
+    #startedAt = { known: false };
+    /**
+     * Construct a guard over one lock file.
+     * @param lockPath - Lock file adjacent to the database this process wants to own.
+     * @param ports - Operating-system boundaries, replaced only by this module's own tests.
+     */
+    constructor(lockPath, ports = systemBrokerLockPorts()) {
+        this.#lockPath = lockPath;
+        this.#reclaimPath = `${lockPath}.reclaim`;
+        this.#ports = ports;
+    }
+    /**
+     * Names the lock file this guard claims.
+     * @returns - Path the guard was constructed over.
+     */
+    get path() {
+        return this.#lockPath;
+    }
+    /**
+     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone.
+     *
+     * Terminates in every case: each attempt either wins the lock, throws because a live owner holds
+     * it, or consumes one of a fixed number of attempts.
+     * @throws {BrokerServiceAlreadyRunningError} - A live service of this build holds the lock.
+     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the lock.
+     * @throws {BrokerLockContendedError} - Another writer kept recreating the lock.
+     */
+    acquire() {
+        mkdirSync(dirname(this.#lockPath), { recursive: true });
+        this.#startedAt = this.#ports.processStartedAt(process.pid);
+        let unreadableLockReads = 0;
+        let unreadableReclaimReads = 0;
+        let blockedBy = this.#lockPath;
+        for (let attempt = 0; attempt < BROKER_LOCK_ACQUISITION_ATTEMPTS; attempt += 1) {
+            const holder = this.#ports.newHolderToken();
+            if (this.#create(holder)) {
+                this.#holder = holder;
+                // A reclaimer killed after removing the lock and before creating its own leaves its reclaim
+                // file behind, and nothing on the uncontended path would ever look at it again.
+                if (existsSync(this.#reclaimPath))
+                    this.#dropAbandonedReclaimFile(0);
+                this.#sweepStagingFiles();
+                return;
+            }
+            const observed = this.#observe();
+            if (observed.state === "live")
+                throw ownerError(observed.pid, observed.current);
+            if (observed.state === "absent")
+                continue;
+            if (observed.state === "unreadable") {
+                unreadableLockReads += 1;
+                // A writer outside this build may replace the lock without an atomic rename, so a single
+                // unreadable read can be a half-written document rather than an abandoned one.
+                if (unreadableLockReads < 2) {
+                    this.#ports.sleep(RECLAIM_RETRY_DELAY_MS);
+                    continue;
+                }
+            }
+            else {
+                unreadableLockReads = 0;
+            }
+            const outcome = this.#reclaim(holder, unreadableReclaimReads);
+            if (outcome === "acquired") {
+                this.#holder = holder;
+                return;
+            }
+            unreadableReclaimReads = outcome === "reclaim-unreadable" ? unreadableReclaimReads + 1 : 0;
+            blockedBy = outcome === "lock-taken" ? this.#lockPath : this.#reclaimPath;
+            this.#ports.sleep(RECLAIM_RETRY_DELAY_MS);
+        }
+        throw new BrokerLockContendedError(this.#lockPath, BROKER_LOCK_ACQUISITION_ATTEMPTS, blockedBy);
+    }
+    /**
+     * Replace the acquired lock with the record readers adopt.
+     *
+     * Written to a scratch file and renamed, so no reader can observe a partial document and treat
+     * the database as unowned.
+     * @param lock - Ownership record naming this process's published endpoints.
+     * @throws {BrokerLockLostError} - The lock on disk is no longer the one this guard acquired.
+     */
+    publish(lock) {
+        const holder = this.#holder;
+        if (holder === undefined || readLockHolder(this.#lockPath) !== holder) {
+            throw new BrokerLockLostError(this.#lockPath);
+        }
+        const stagingPath = `${this.#lockPath}.${holder}.tmp`;
+        try {
+            writeFileSync(stagingPath, JSON.stringify({
+                ...lock,
+                holder,
+                ...(this.#startedAt.known ? { ownerStartedAt: this.#startedAt.value } : {}),
+            }), { mode: 0o600 });
+            renameSync(stagingPath, this.#lockPath);
+        }
+        finally {
+            removeIfPresent(stagingPath);
+        }
+    }
+    /**
+     * Give up ownership, leaving any lock this guard does not hold untouched.
+     *
+     * A service that failed to acquire, or whose lock was reclaimed while it shut down, must not
+     * delete the record naming whichever process owns the database now.
+     */
+    release() {
+        const holder = this.#holder;
+        this.#holder = undefined;
+        if (holder === undefined || readLockHolder(this.#lockPath) !== holder)
+            return;
+        removeIfPresent(this.#lockPath);
+    }
+    #create(holder) {
+        return this.#claim(this.#lockPath, holder, JSON.stringify({
+            ...currentBrokerServiceIdentity(),
+            pid: process.pid,
+            epoch: "starting",
+            holder,
+            ...(this.#startedAt.known ? { ownerStartedAt: this.#startedAt.value } : {}),
+        }));
+    }
+    /**
+     * Claim a name for this process, or report that another process already holds it.
+     *
+     * Staging the record and then linking it into place publishes the name and its contents in one
+     * step, so a reader never sees the name without a record. `link` fails `EEXIST` on a name another
+     * process holds, so at most one claimant takes it.
+     * @param path - Name to claim.
+     * @param holder - Token identifying this attempt, which keeps the staging file to itself.
+     * @param content - Record the name carries from the instant it exists.
+     * @returns - True when this process took the name, false when another process holds it.
+     */
+    #claim(path, holder, content) {
+        const stagingPath = `${path}.${holder}.new`;
+        try {
+            writeFileSync(stagingPath, content, { mode: 0o600 });
+            try {
+                linkSync(stagingPath, path);
+            }
+            catch (error) {
+                // EEXIST is another process holding the name. ENOENT is this attempt's staging file having
+                // been swept as a crash leftover, which loses the attempt rather than failing it.
+                if (isErrno(error, "EEXIST") || isErrno(error, "ENOENT"))
+                    return false;
+                throw error;
+            }
+            return true;
+        }
+        finally {
+            removeIfPresent(stagingPath);
+        }
+    }
+    /**
+     * Clear staging files left behind by a process killed between writing one and linking it.
+     *
+     * Their names are unique to the attempt that made them, so nothing else revisits them and they
+     * would accumulate in the state directory. Removing one a live claim still holds costs that claim
+     * its attempt and no more, because its link then fails and it retries under a new name.
+     */
+    #sweepStagingFiles() {
+        const directory = dirname(this.#lockPath);
+        const prefix = `${basename(this.#lockPath)}.`;
+        for (const entry of readdirSync(directory)) {
+            if (!entry.startsWith(prefix))
+                continue;
+            if (entry.endsWith(".new") || entry.endsWith(".tmp"))
+                removeIfPresent(join(directory, entry));
+        }
+    }
+    #observe() {
+        const record = readJsonObject(this.#lockPath);
+        if (!record)
+            return existsSync(this.#lockPath) ? { state: "unreadable" } : { state: "absent" };
+        const pid = ownerPidOf(record);
+        if (pid === undefined)
+            return { state: "unreadable" };
+        if (!this.#ownerIsLive(pid, record))
+            return { state: "stale" };
+        return { state: "live", pid, current: brokerLockHasCurrentIdentity(readBrokerLock(this.#lockPath)) };
+    }
+    #ownerIsLive(pid, record) {
+        if (!this.#ports.processIsAlive(pid))
+            return false;
+        const recorded = record.ownerStartedAt;
+        if (typeof recorded !== "string")
+            return true;
+        return startTimeStillMatches(recorded, this.#ports.processStartedAt(pid));
+    }
+    #reclaim(holder, unreadableReclaimReads) {
+        if (!this.#takeReclaimFile(holder))
+            return this.#dropAbandonedReclaimFile(unreadableReclaimReads);
+        try {
+            const observed = this.#observe();
+            if (observed.state === "live")
+                throw ownerError(observed.pid, observed.current);
+            if (observed.state !== "absent")
+                removeIfPresent(this.#lockPath);
+            return this.#create(holder) ? "acquired" : "lock-taken";
+        }
+        finally {
+            removeIfPresent(this.#reclaimPath);
+        }
+    }
+    #takeReclaimFile(holder) {
+        return this.#claim(this.#reclaimPath, holder, JSON.stringify({
+            pid: process.pid,
+            holder,
+            ...(this.#startedAt.known ? { ownerStartedAt: this.#startedAt.value } : {}),
+        }));
+    }
+    #dropAbandonedReclaimFile(unreadableReclaimReads) {
+        const record = readJsonObject(this.#reclaimPath);
+        if (!record) {
+            // The reclaim file's name and record appear in one step, so an unreadable one is a foreign
+            // writer, corruption, or a file removed since the failed link, not a holder mid-write. Deleting it on a single reading could still put
+            // two processes inside the span this file exists to serialise, so only a reading that stays
+            // unreadable across attempts is treated as abandonment.
+            if (unreadableReclaimReads >= 1)
+                removeIfPresent(this.#reclaimPath);
+            return "reclaim-unreadable";
+        }
+        const pid = ownerPidOf(record);
+        if (pid === undefined || !this.#ownerIsLive(pid, record))
+            removeIfPresent(this.#reclaimPath);
+        return "reclaim-held";
+    }
+}
+function ownerError(pid, current) {
+    return current ? new BrokerServiceAlreadyRunningError(pid) : new BrokerServiceLockOwnedError(pid);
+}
+function ownerPidOf(record) {
+    const pid = record.pid;
+    return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+function readJsonObject(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readLockHolder(lockPath) {
+    const record = readJsonObject(lockPath);
+    return record && typeof record.holder === "string" ? record.holder : undefined;
+}
+function removeIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        // Whatever this call would have removed is already gone, which is the outcome it wanted.
+        if (!isErrno(error, "ENOENT"))
+            throw error;
+    }
+}
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/dist/src/launch/cli.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+import type { ImplementationId } from "../implementations/model.js";
+import { type ImplementationRegistry } from "../implementations/registry.js";
+/**
+ * Run the operational CLI.
+ *
+ * Most commands write one `{ ok, … }` envelope to stdout on success. An invocation naming no command at all renders the operator TUI on the terminal instead of
+ * writing an envelope; the bare `<implementation-id>` wrapper hands or inherits stdio to the child
+ * process, and the wrapper's own failure path writes to stderr instead of stdout. `--help`, `-h`,
+ * and `help` write only to stderr, through `usage()`. Any other thrown failure is caught here and
+ * written to stderr as `{ ok: false, … }`.
+ * @param argv - Command tokens supplied after the executable name.
+ */
+export declare function main(argv?: string[]): Promise<void>;
+/**
+ * Reject installed implementation identities that would be shadowed by a reserved subcommand.
+ * @param implementations - Registry whose open ids share the first CLI argument slot.
+ */
+export declare function assertNoReservedImplementationIds(implementations: ImplementationRegistry): void;
+/**
+ * Parse a bare implementation wrapper command without naming a concrete provider.
+ * @param command - First command token already known not to be a reserved subcommand.
+ * @param args - Wrapper options and implementation passthrough arguments.
+ * @param implementations - Registry used to distinguish valid-but-uninstalled ids.
+ * @returns - Resolved implementation, optional stable session name, and passthrough arguments.
+ */
+export declare function parseWrapperCommand(command: string, args: string[], implementations: ImplementationRegistry): {
+    selectedImplementation: ImplementationId;
+    sessionName?: string;
+    passthrough: string[];
+};
+/**
+ * Return the canonical encoded file URL used to compare a CLI process entrypoint.
+ * @param path - Existing filesystem path supplied by the process argument vector.
+ * @returns - URL-safe identity after resolving filesystem links.
+ */
+export declare function canonicalFileUrl(path: string): string;