agent-relay 12.2.7 → 12.3.0

package/dist/cli/lib/node-claim.js

@@ -0,0 +1,1338 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * The machine-global Relay home that holds `fleet-enrollments.json`.
+ *
+ * Deliberately not imported from `@agent-relay/cloud`: that barrel pulls the
+ * Cloud SSH runtime, and a claim check must stay a couple of syscalls that any
+ * command can make. `node-claim.test.ts` pins this to the enrollment store's
+ * own directory so the two cannot drift apart.
+ */
+function relayHome(env) {
+    return env.AGENT_RELAY_HOME ?? path.join(os.homedir(), '.agentworkforce/relay');
+}
+/** Filename the broker writes its API endpoint and pid into, inside its state dir. */
+const BROKER_CONNECTION_FILENAME = 'connection.json';
+/** Thrown when a live local broker already serves the requested node id. */
+export class NodeClaimConflictError extends Error {
+    nodeId;
+    claim;
+    constructor(nodeId, claim) {
+        super(`node ${nodeId} is already served by a live local broker (pid ${claim.pid}, state dir ${claim.state_dir}). ` +
+            'Stop it with `agent-relay node down --state-dir <dir>`, serve a different enrolled node, or re-run with --force.');
+        this.nodeId = nodeId;
+        this.claim = claim;
+        this.name = 'NodeClaimConflictError';
+    }
+}
+/**
+ * Thrown when the kernel-level ownership fence could not be established.
+ *
+ * The hold descriptor is what makes a claim survive its own supervisor, so a
+ * start that cannot open one cannot honour the guarantee it is claiming under.
+ * It refuses instead of spawning an unfenced broker.
+ */
+export class NodeClaimHoldError extends Error {
+    nodeId;
+    holdPath;
+    constructor(nodeId, holdPath, cause) {
+        super(`could not establish the ownership fence for node ${nodeId} at ${holdPath}: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}. ` +
+            'Startup was stopped rather than run a broker that another start could silently take the node from. ' +
+            'Ensure the claims directory is writable and has free space, then retry.', { cause });
+        this.nodeId = nodeId;
+        this.holdPath = holdPath;
+        this.name = 'NodeClaimHoldError';
+    }
+}
+/**
+ * Thrown when ownership could not be established because other starts kept
+ * winning the exclusive create.
+ *
+ * Each attempt is a handful of syscalls, so exhausting them means a pathological
+ * amount of contention on one node id. Ownership cannot be established in that
+ * state, and starting anyway is exactly the double registration this module
+ * exists to prevent.
+ */
+export class NodeClaimContentionError extends Error {
+    nodeId;
+    claimsDir;
+    constructor(nodeId, claimsDir, cause) {
+        super(`could not take ownership of node ${nodeId}: other agent-relay starts kept winning the claim in ${claimsDir}. ` +
+            'Retry, or run `agent-relay node down` on the state dir that should keep the node.', { cause });
+        this.nodeId = nodeId;
+        this.claimsDir = claimsDir;
+        this.name = 'NodeClaimContentionError';
+    }
+}
+/**
+ * The enrolled node id a start will register as, or `undefined` when it will
+ * mint its own identity.
+ *
+ * `RELAY_NODE_ID` is sent verbatim in `node.register` (`resolve_broker_node_id`,
+ * crates/broker/src/runtime/init.rs), so an explicit node id IS the identity
+ * that can evict another broker, and it is claimed on that basis alone.
+ *
+ * This deliberately does not try to predict whether the broker will manage to
+ * authenticate as it. An earlier version claimed the id only when a token was
+ * in the environment or already in the broker's on-disk cache, and that was a
+ * hole: `init.rs` also wires a workspace-key token minter, and
+ * `node_control.rs` mints and connects with no cached token at all, so a start
+ * carrying nothing but `RELAY_NODE_ID` and workspace credentials walked past a
+ * live claim and took the node's delivery socket — the incident this module
+ * exists to close. Enumerating the credential routes instead of the identity
+ * just moves the hole to the next route that gets added.
+ *
+ * The cost is a start that could not have registered at all (no token, no
+ * workspace key, nothing to mint with) being refused when some other broker
+ * genuinely holds the id. That is recoverable in one flag (`--force`) and the
+ * start it refuses was headed for local-only operation anyway, while the
+ * opposite error is a silent delivery outage. `--local-only` starts register
+ * nothing and are excluded by the callers, not here.
+ */
+export function enrolledNodeIdForClaim(env) {
+    return env.RELAY_NODE_ID?.trim() || undefined;
+}
+/* ------------------------------------------------------------------ *
+ * Claim files and generations
+ * ------------------------------------------------------------------ */
+/** Zero padding, so claim generations sort lexically as well as numerically. */
+const GENERATION_DIGITS = 6;
+/** Matches `<stem>.<generation>.json` for any node. */
+const CLAIM_FILENAME_PATTERN = new RegExp(`^(.+)\\.(\\d{${GENERATION_DIGITS},})\\.json$`);
+/** Directory holding the claim files for every node id served on this machine. */
+export function nodeClaimsDir(env = process.env) {
+    return path.join(relayHome(env), 'node-claims');
+}
+/**
+ * Filename stem for a node id's claims. Node ids are engine-issued
+ * (`node_<digits>`), but the stem is sanitized anyway so a hand-edited
+ * enrollment store cannot write outside the claims directory. Readers verify
+ * `node_id` from the file contents, so a sanitized collision is reported as a
+ * conflict rather than silently overwriting another node's claim.
+ */
+function nodeClaimStem(nodeId) {
+    return (nodeId
+        .trim()
+        .replace(/[^\w.-]/g, '-')
+        .slice(0, 96) || 'unnamed');
+}
+/**
+ * Path of one generation of a node id's claim.
+ *
+ * Every write this module makes is the exclusive creation of a NEW generation,
+ * never an overwrite of an existing one — that is what makes takeover safe
+ * without a lock file (see {@link acquireNodeClaim}).
+ */
+export function nodeClaimPath(nodeId, env = process.env, generation = 1) {
+    const suffix = String(generation).padStart(GENERATION_DIGITS, '0');
+    return path.join(nodeClaimsDir(env), `${nodeClaimStem(nodeId)}.${suffix}.json`);
+}
+/**
+ * Sibling of a claim generation whose OPEN DESCRIPTORS are the ownership
+ * evidence, held by the kernel rather than written by a process.
+ *
+ * `<stem>.<generation>.hold` is created and opened by the supervising CLI
+ * BEFORE it spawns a broker, and the descriptor is inherited by the child
+ * across `fork`. From the instant a broker child exists — long before it binds
+ * its API, writes `connection.json` or queues `node.register` — some live
+ * process holds this file open, and the kernel drops the last reference the
+ * moment both of them die. That is what closes the window a supervisor
+ * SIGKILLed between the spawn and the broker's first write used to leave: there
+ * is no interval in which a competing start can see "dead supervisor, nothing
+ * published" and conclude the node id is free while the orphan is on its way to
+ * registering.
+ *
+ * Not matched by {@link CLAIM_FILENAME_PATTERN} (which requires `.json`), so it
+ * never counts as a generation of its own.
+ */
+export function nodeClaimHoldPath(nodeId, env = process.env, generation = 1) {
+    return `${nodeClaimPath(nodeId, env, generation).slice(0, -'.json'.length)}.hold`;
+}
+/** Single-quote a path for a shell command (`AGENT_RELAY_HOME` is operator input). */
+function shellQuote(value) {
+    // Close the quoted run, emit an escaped quote, reopen: '  ->  '\''
+    return `'${value.split("'").join("'\\''")}'`;
+}
+/** Resolve a state dir to its canonical path so two spellings compare equal. */
+export function normalizeClaimStateDir(stateDir) {
+    try {
+        return fs.realpathSync(stateDir);
+    }
+    catch {
+        return path.resolve(stateDir);
+    }
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalPositiveInteger(value) {
+    return value === undefined || (Number.isSafeInteger(value) && value > 0);
+}
+function hasValidOptionalClaimFields(record) {
+    return ((record.api_port === undefined || Number.isSafeInteger(record.api_port)) &&
+        isOptionalString(record.broker_name) &&
+        isOptionalString(record.broker_binary) &&
+        isOptionalString(record.broker_executable) &&
+        isOptionalString(record.process_started_at) &&
+        isOptionalString(record.supervisor_started_at) &&
+        isOptionalString(record.owner_token) &&
+        isOptionalPositiveInteger(record.supervisor_pid) &&
+        isOptionalPositiveInteger(record.broker_child_pid) &&
+        isOptionalPositiveInteger(record.generation) &&
+        (record.status === undefined || record.status === 'reserved' || record.status === 'active'));
+}
+function isNodeClaim(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    // A tombstone occupies a generation number so it can never be reissued, but
+    // it is evidence of nothing. Rejecting it here is what makes it read as an
+    // unclaimed node id everywhere a claim is read.
+    if (record.released === true)
+        return false;
+    return (record.version === 1 &&
+        typeof record.node_id === 'string' &&
+        record.node_id.trim().length > 0 &&
+        Number.isSafeInteger(record.pid) &&
+        record.pid > 0 &&
+        typeof record.state_dir === 'string' &&
+        record.state_dir.length > 0 &&
+        typeof record.claimed_at === 'string' &&
+        hasValidOptionalClaimFields(record));
+}
+/** Exact bytes of a claim file, or `null` when it cannot be read at all. */
+function readClaimBytes(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function parseClaim(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return isNodeClaim(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readClaimFile(file) {
+    return parseClaim(readClaimBytes(file));
+}
+/**
+ * Every generation file present for `nodeId`, ascending.
+ *
+ * Unreadable files are kept in the list with a `null` claim: they must still
+ * raise the next generation number (or an exclusive create would collide with
+ * them forever) even though they are no evidence of a live broker.
+ */
+function readClaimGenerations(nodeId, env) {
+    const dir = nodeClaimsDir(env);
+    const stem = nodeClaimStem(nodeId);
+    let filenames;
+    try {
+        filenames = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const generations = [];
+    for (const filename of filenames) {
+        const match = CLAIM_FILENAME_PATTERN.exec(filename);
+        if (!match || match[1] !== stem)
+            continue;
+        const file = path.join(dir, filename);
+        const raw = readClaimBytes(file);
+        generations.push({ generation: Number.parseInt(match[2], 10), file, raw, claim: parseClaim(raw) });
+    }
+    return generations.sort((left, right) => left.generation - right.generation);
+}
+/** The generation that currently owns the node id: the highest readable one. */
+function currentGeneration(generations) {
+    for (let index = generations.length - 1; index >= 0; index -= 1) {
+        if (generations[index].claim)
+            return generations[index];
+    }
+    return undefined;
+}
+function highestGenerationNumber(generations) {
+    return generations.length === 0 ? 0 : generations[generations.length - 1].generation;
+}
+/**
+ * The claim that currently owns `nodeId`, or `null`.
+ *
+ * A missing, unreadable, or malformed file reads as `null`: an unparseable
+ * claim is no evidence of a live broker, and treating it as one would brick
+ * every later `node up` for that node id.
+ */
+export function readNodeClaim(nodeId, env = process.env) {
+    return currentGeneration(readClaimGenerations(nodeId, env))?.claim ?? null;
+}
+/** The current claim for every node id on this machine, newest first. */
+export function listNodeClaims(env = process.env) {
+    const dir = nodeClaimsDir(env);
+    let filenames;
+    try {
+        filenames = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const newestByStem = new Map();
+    for (const filename of filenames) {
+        const match = CLAIM_FILENAME_PATTERN.exec(filename);
+        if (!match)
+            continue;
+        const claim = readClaimFile(path.join(dir, filename));
+        if (!claim)
+            continue;
+        const generation = Number.parseInt(match[2], 10);
+        const seen = newestByStem.get(match[1]);
+        if (!seen || seen.generation < generation) {
+            newestByStem.set(match[1], { generation, claim });
+        }
+    }
+    return [...newestByStem.values()]
+        .map((entry) => entry.claim)
+        .sort((left, right) => right.claimed_at.localeCompare(left.claimed_at));
+}
+/**
+ * Every readable claim on this machine, across ALL generations, newest first.
+ *
+ * `listNodeClaims` reports only the current generation per node id, but a
+ * `--force` takeover can leave a still-held incumbent beneath the
+ * replacement's file. Callers that diagnose or release by broker identity must
+ * see every generation, or that hidden claim never surfaces.
+ */
+function listAllNodeClaims(env) {
+    const dir = nodeClaimsDir(env);
+    let filenames;
+    try {
+        filenames = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const claims = [];
+    for (const filename of filenames) {
+        const match = CLAIM_FILENAME_PATTERN.exec(filename);
+        if (!match)
+            continue;
+        const claim = readClaimFile(path.join(dir, filename));
+        if (claim)
+            claims.push(claim);
+    }
+    return claims.sort((left, right) => right.claimed_at.localeCompare(left.claimed_at) || (right.generation ?? 0) - (left.generation ?? 0));
+}
+/* ------------------------------------------------------------------ *
+ * Liveness
+ * ------------------------------------------------------------------ */
+function isProcessAlive(pid, deps) {
+    const kill = deps.killProcess ??
+        ((target, signal) => {
+            process.kill(target, signal);
+        });
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Permission denial proves the process exists and is not ours to inspect;
+        // that must read as live, never as a free node id.
+        return error?.code === 'EPERM';
+    }
+}
+/**
+ * `ps` birth time for a pid, or `null` when it cannot be read. Mirrors the
+ * command `broker-process-identity` uses so both agree on the format.
+ */
+async function readProcessStartedAt(pid, deps) {
+    const execCommand = deps.execCommand;
+    if (!execCommand) {
+        return null;
+    }
+    try {
+        const { stdout } = await execCommand(`LC_ALL=C TZ=UTC ps -p ${pid} -o lstart=`);
+        const normalized = stdout.trim().replace(/\s+/g, ' ');
+        return normalized.length > 0 ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether `pid` is still the process that was recorded with `startedAt`.
+ * A pid that is gone, or one whose birth time moved (the number was recycled),
+ * no longer holds anything.
+ */
+async function isRecordedProcessAlive(pid, startedAt, deps) {
+    if (!isProcessAlive(pid, deps)) {
+        return { alive: false, reason: `pid ${pid} is no longer running` };
+    }
+    if (startedAt) {
+        const current = await readProcessStartedAt(pid, deps);
+        if (current && current !== startedAt) {
+            return { alive: false, reason: `pid ${pid} was recycled by a process started ${current}` };
+        }
+    }
+    return { alive: true, reason: `pid ${pid} is running` };
+}
+/** The owning pid plus, when the claim records one, its supervising CLI. */
+function claimProcesses(claim) {
+    const processes = [
+        {
+            pid: claim.pid,
+            startedAt: claim.process_started_at,
+            role: claim.status === 'reserved' ? 'supervisor' : 'broker',
+        },
+    ];
+    if (claim.supervisor_pid !== undefined && claim.supervisor_pid !== claim.pid) {
+        processes.push({
+            pid: claim.supervisor_pid,
+            startedAt: claim.supervisor_started_at,
+            role: 'supervisor',
+        });
+    }
+    return processes;
+}
+/** Pid recorded in `<state dir>/connection.json`, which the broker writes itself. */
+function readStateDirBrokerPid(stateDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(stateDir, BROKER_CONNECTION_FILENAME), 'utf-8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const pid = parsed.pid;
+        return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function brokerExecutableHint(claim) {
+    return {
+        stateDir: claim.state_dir,
+        ...(claim.broker_binary ? { binary: claim.broker_binary } : {}),
+        ...(claim.broker_executable ? { object: claim.broker_executable } : {}),
+        ...(claim.broker_child_pid ? { childPid: claim.broker_child_pid } : {}),
+    };
+}
+/**
+ * Identity of the executable file a claim's start was going to run, for the
+ * record. `realpathSync` first so a claim written through a symlinked install
+ * path still names the file a running broker maps.
+ */
+/**
+ * `<device>:<inode>` of a file on this machine, in the encoding `lsof -d txt`
+ * reports and the claim records, or `null` when it cannot be stat'ed.
+ */
+function executableObjectOf(file) {
+    try {
+        const stats = fs.statSync(file, { bigint: true });
+        return `0x${stats.dev.toString(16)}:${stats.ino.toString()}`;
+    }
+    catch {
+        return null;
+    }
+}
+function describeBrokerExecutable(binary) {
+    if (!binary)
+        return {};
+    try {
+        const resolved = fs.realpathSync(binary);
+        const object = executableObjectOf(resolved);
+        return {
+            broker_binary: resolved,
+            ...(object ? { broker_executable: object } : {}),
+        };
+    }
+    catch {
+        // The path is still worth recording: a process running it is recognisable
+        // by argv even when the file cannot be stat'ed from here.
+        return path.isAbsolute(binary) ? { broker_binary: binary } : {};
+    }
+}
+/**
+ * The executable objects `pid` is running, as `<device>:<inode>` pairs, or
+ * `null` when they cannot be read.
+ *
+ * `txt` mappings identify an executable by device and inode on both macOS and
+ * Linux, which is the only handle on "what is this process running" that does
+ * not go through a filename. Same command and same field encoding as
+ * `readBrokerProcessIdentity` in `broker-process-identity.ts`, so the two agree
+ * on what an executable's identity is.
+ */
+async function readExecutableObjects(pid, deps) {
+    const execCommand = deps.execCommand;
+    if (!execCommand)
+        return null;
+    let stdout;
+    try {
+        ({ stdout } = await execCommand(`LC_ALL=C lsof -nP -a -p ${pid} -d txt -FfDi`));
+    }
+    catch {
+        return null;
+    }
+    const fields = stdout.trim().split('\n');
+    if (fields.shift() !== `p${pid}`)
+        return null;
+    const objects = new Set();
+    for (let index = 0; index < fields.length; index += 3) {
+        const [descriptor, device, inode] = fields.slice(index, index + 3);
+        if (descriptor !== 'ftxt' || !/^D0x[0-9a-f]+$/i.test(device ?? '') || !/^i[1-9]\d*$/.test(inode ?? '')) {
+            return null;
+        }
+        objects.add(`${device.slice(1).toLowerCase()}:${inode.slice(1)}`);
+    }
+    return objects.size > 0 ? objects : null;
+}
+/**
+ * Whether a command line names the executable the claim recorded, in a
+ * position an interpreter would put it.
+ *
+ * A shebang launcher does not RUN the file the claim recorded — the kernel runs
+ * the interpreter from its `#!` line and passes the script as an argument, so
+ * `lsof -d txt` reports `/bin/sh` and the recorded device/inode matches
+ * nothing. The script path is still right there in argv, and the file it names
+ * has exactly the identity the claim recorded. Comparing that file rather than
+ * the string is what keeps this working through a symlinked install path, the
+ * same reason the claim records an inode instead of a name.
+ *
+ * Only the first two arguments are considered: `argv[0]` is the program and
+ * `argv[1]` is where an interpreter puts its script. Anything further along is
+ * a broker's own argument and proves nothing about what it is running.
+ */
+function runsRecordedExecutable(args, hint) {
+    if (!hint.binary && !hint.object)
+        return false;
+    for (const token of args.split(/\s+/, 2)) {
+        if (!token.startsWith('/'))
+            continue;
+        if (hint.binary && token === hint.binary)
+            return true;
+        if (!hint.object)
+            continue;
+        const object = executableObjectOf(token);
+        if (object !== null && object === hint.object)
+            return true;
+    }
+    return false;
+}
+/**
+ * Everything a command line can say IN FAVOUR of a process being this claim's
+ * broker. Nothing here is ever read the other way round: a command line that
+ * matches none of it is not evidence of anything, because the broker binary is
+ * operator-selectable and a start on the default state dir passes no
+ * `--state-dir` for argv to carry.
+ */
+function argvIdentifiesBroker(args, hint) {
+    if (hint.binary && (args === hint.binary || args.startsWith(`${hint.binary} `)))
+        return true;
+    if (runsRecordedExecutable(args, hint))
+        return true;
+    return args.includes('agent-relay') || args.includes('relay-broker') || args.includes(hint.stateDir);
+}
+/**
+ * Whether `pid` maps the executable object the claim recorded.
+ *
+ * Mappings that cannot be read are NOT a mismatch — the process may simply not
+ * be ours to inspect — so they answer yes, like every other unanswerable probe
+ * in this module.
+ */
+async function mapsRecordedExecutable(pid, object, deps) {
+    const objects = await readExecutableObjects(pid, deps);
+    return objects === null || objects.has(object);
+}
+/**
+ * Whether `pid` is the broker a claim names, an unrelated process that merely
+ * inherited its descriptor or its pid number, or something this claim has no
+ * way to tell apart.
+ *
+ * Executable identity decides it: the device and inode of the file the process
+ * is running, against the broker executable the claim recorded. Command lines
+ * are consulted only as further POSITIVE evidence and never to rule a process
+ * out. `AGENT_RELAY_BIN` / `BROKER_BINARY_PATH` let a supported deployment run
+ * the broker under any filename, and with the default state dir such a broker
+ * carries neither `agent-relay` nor its state dir in argv — so the name test
+ * that used to decide this classified a real, live broker as unrelated and
+ * handed its node id to the next start.
+ *
+ * Those same overrides accept a LAUNCHER — a shell script that sets something
+ * up and `exec`s the broker is the ordinary shape of a custom install — and a
+ * launcher is not the file the running process maps. Before its `exec` the
+ * process runs the interpreter from the script's `#!` line; after it, the
+ * binary the script chose. Neither is the file recorded before the spawn, so
+ * executable identity alone ruled a live, fenced startup launcher out and
+ * reopened exactly the eviction this claim exists to prevent. Two further
+ * pieces of positive evidence close that: the recorded file appearing in argv
+ * where an interpreter puts its script ({@link runsRecordedExecutable}), which
+ * needs nothing recorded after the spawn, and the pid of the child this start
+ * spawned ({@link NodeClaim.broker_child_pid}), which `execve` preserves
+ * whatever the launcher turns into.
+ *
+ * Anything that cannot be consulted — no runner, an `lsof` or `ps` that fails —
+ * reads as `broker`: this only ever decides whether to KEEP guarding a node id,
+ * and a spurious refusal is recoverable (`--force`, `node down`) while a wrong
+ * "free" verdict is the silent delivery outage.
+ */
+async function classifyHolderProcess(pid, hint, deps) {
+    // Recorded at the spawn itself, so it is the one piece of evidence that is
+    // immune to whatever the child turns into afterwards.
+    if (hint.childPid !== undefined && pid === hint.childPid)
+        return 'broker';
+    const execCommand = deps.execCommand;
+    if (!execCommand)
+        return 'broker';
+    if (hint.object && (await mapsRecordedExecutable(pid, hint.object, deps)))
+        return 'broker';
+    let args;
+    try {
+        const { stdout } = await execCommand(`LC_ALL=C ps -p ${pid} -o args=`);
+        args = stdout.trim();
+    }
+    catch {
+        return 'broker';
+    }
+    // `ps` answered with nothing: the pid is gone, so it holds nothing.
+    if (!args)
+        return 'unrelated';
+    if (argvIdentifiesBroker(args, hint))
+        return 'broker';
+    return hint.object || hint.binary ? 'unrelated' : 'unidentified';
+}
+/**
+ * Whether any live process still holds this generation's hold file open.
+ *
+ * `lsof -t` answers from the kernel's open-file table, so this reports the
+ * broker child a SIGKILLed supervisor left behind from the instant that child
+ * exists — there is no publish step to wait for and nothing to go stale. The
+ * exit status is read from an explicit marker rather than from the runner's
+ * error shape: `lsof` exits 1 with no output when a file simply has no holders,
+ * and that has to be told apart from an `lsof` that could not run at all.
+ *
+ * An `lsof` that cannot be consulted reads as HELD, matching the rest of this
+ * module: `node up` already refuses to start without a usable `lsof` (it is how
+ * broker process identity is verified), and a spurious refusal is recoverable
+ * with `--force` or `node down` while a wrong "free" verdict is the silent
+ * delivery outage the claim exists to prevent.
+ *
+ * Holders are classified by {@link classifyHolderProcess}, exactly as the
+ * connection file's pid is. An inherited descriptor is not close-on-exec, so
+ * anything the broker itself spawns inherits it too; a harness left running by
+ * a SIGKILLed broker would otherwise pin the node id with no broker anywhere
+ * near it. Dropping one is a positive determination and needs BOTH halves of
+ * the evidence: the holder identified as some other executable, AND a claim
+ * that durably recorded the child it spawned. Without the second half the first
+ * cannot be trusted — a process that has `exec`d is not the file the claim
+ * recorded — so every holder stays a holder, as one does when the claim cannot
+ * classify it at all. Nothing but a Relay start ever passes this descriptor on,
+ * and a spurious refusal is recoverable where a wrong "free" verdict is not.
+ *
+ * `selfPids` are dropped from the holder set: a start re-reading its own
+ * reservation still has that generation's descriptor open, and its own
+ * descriptor is not evidence that somebody else owns the node id.
+ */
+async function inspectClaimHold(claim, env, deps, selfPids) {
+    const file = nodeClaimHoldPath(claim.node_id, env, claim.generation ?? 1);
+    if (!fs.existsSync(file)) {
+        return { held: false, reason: `no start holds ${file}`, pids: [] };
+    }
+    const execCommand = deps.execCommand;
+    if (!execCommand) {
+        return { held: true, reason: `open descriptors on ${file} could not be checked`, pids: [] };
+    }
+    let stdout;
+    try {
+        ({ stdout } = await execCommand(`LC_ALL=C lsof -t -- ${shellQuote(file)} 2>/dev/null; printf 'rc=%d' "$?"`));
+    }
+    catch {
+        return { held: true, reason: `open descriptors on ${file} could not be checked`, pids: [] };
+    }
+    const status = /rc=(\d+)/.exec(stdout);
+    const pids = stdout
+        .replace(/rc=\d+/, '')
+        .split(/\s+/)
+        .map((value) => value.trim())
+        .filter((value) => /^\d+$/.test(value))
+        .filter((value) => !selfPids?.has(Number(value)));
+    const hint = brokerExecutableHint(claim);
+    // Ruling a holder OUT requires the claim to know which process this start
+    // actually spawned. Everything recorded before a spawn describes a FILE, and
+    // `execve` swaps the file while keeping the descriptor: a launcher that has
+    // already exec'd the real broker maps a binary the claim never recorded and
+    // no longer carries the launcher anywhere in its argv. `broker_child_pid` is
+    // what covers that — but it is published after the spawn, so a supervisor
+    // SIGKILLed in between leaves a claim that can never identify its own broker,
+    // and the one live process holding the node's fence classifies as
+    // `unrelated`. The node id then reads free while that broker is on its way to
+    // registering, which is the eviction this module exists to prevent.
+    //
+    // So until child identity is durably established, a holder of this descriptor
+    // keeps the node guarded whatever it is running. Nothing but a Relay start
+    // ever passes this descriptor on, and the bias is the module's usual one: a
+    // refusal costs one `--force`, a wrong "free" verdict costs deliveries.
+    const childEstablished = claim.broker_child_pid !== undefined;
+    const brokers = [];
+    const unprovable = [];
+    for (const pid of pids) {
+        const verdict = await classifyHolderProcess(Number(pid), hint, deps);
+        if (verdict !== 'unrelated')
+            brokers.push(pid);
+        else if (!childEstablished)
+            unprovable.push(pid);
+    }
+    if (brokers.length > 0) {
+        return {
+            held: true,
+            reason: `pid ${brokers.join(', ')} still holds ${file} open`,
+            pids: brokers.map(Number),
+        };
+    }
+    if (unprovable.length > 0) {
+        return {
+            held: true,
+            reason: `pid ${unprovable.join(', ')} still holds ${file} open, and the start that created it ` +
+                'never recorded the broker child it spawned, so that process cannot be ruled out',
+            pids: unprovable.map(Number),
+        };
+    }
+    if (pids.length > 0) {
+        return {
+            held: false,
+            reason: `only unrelated processes (pid ${pids.join(', ')}) hold ${file} open`,
+            pids: [],
+        };
+    }
+    // `lsof` exits 1 for "no holders"; anything else means it could not answer.
+    if (!status || (status[1] !== '0' && status[1] !== '1')) {
+        return { held: true, reason: `open descriptors on ${file} could not be checked`, pids: [] };
+    }
+    return { held: false, reason: `no process holds ${file} open`, pids: [] };
+}
+/**
+ * Whether anything other than `selfPids` still holds this claim's generation
+ * fenced, for a caller deciding whether ownership may be dropped.
+ *
+ * A release has to consult this, not just the pids on the record. The record
+ * names a broker only once a start got far enough to capture one: a spawn that
+ * rejects before it returns a client — a handshake that never completed, a
+ * SIGTERM the child outlived — leaves a broker child that no pid anywhere names,
+ * and releasing on "no live pid recorded" tombstones the claim and unlinks the
+ * hold file out from under a process that is still fenced by it. The next start
+ * then reads the node id as free while that child can still register. The
+ * descriptor is the one piece of evidence that exists from the instant the child
+ * does, so it is what decides.
+ *
+ * Holders are filtered exactly as {@link inspectNodeClaim} filters them, so a
+ * release never frees a node id that another start would still read as held.
+ */
+export async function inspectNodeClaimHold(claim, deps = {}, selfPids) {
+    return inspectClaimHold(claim, deps.env ?? process.env, deps, selfPids);
+}
+/**
+ * Create and open this generation's hold file, handing the supervising CLI the
+ * descriptor it passes to the broker child.
+ *
+ * Created exclusively (`wx`): only the acquisition that won the generation ever
+ * creates it, so a concurrent start can never replace the inode a live child is
+ * holding. Opened BEFORE the spawn, because a fence established after `fork`
+ * would leave exactly the gap it exists to close.
+ *
+ * Failing to establish the hold is FATAL to the start, which is why this throws
+ * rather than reporting a missing fence. Without the descriptor, a supervisor
+ * killed between the fork and the broker's `connection.json` write leaves a
+ * claim with only dead pids and no evidence at all — so the next start reads
+ * the node id as free and evicts a broker that is about to register. Continuing
+ * would mean spawning a broker under a guarantee that is not actually in force,
+ * which is worse than not starting: the operator can see and fix a refusal.
+ *
+ * @throws NodeClaimHoldError when the hold could not be established. Any
+ * partially created file and descriptor are cleaned up first, so a retry (or a
+ * later start, on the next generation) is not blocked by this one's debris.
+ */
+export function openNodeClaimHold(claim, env = process.env) {
+    const generation = claim.generation ?? 1;
+    const file = nodeClaimHoldPath(claim.node_id, env, generation);
+    let fd;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fd = fs.openSync(file, 'wx', 0o600);
+        // Contents are operator-facing only; the evidence is the open descriptor.
+        fs.writeSync(fd, `${JSON.stringify({ node_id: claim.node_id, generation, supervisor_pid: claim.pid, state_dir: claim.state_dir }, null, 2)}\n`);
+        return fd;
+    }
+    catch (error) {
+        // Drop our reference before unlinking: an fd we opened and then abandoned
+        // would keep answering `lsof` for as long as this process lives, pinning a
+        // node id behind a fence nothing is actually being fenced by.
+        closeNodeClaimHold(fd);
+        if (fd !== undefined)
+            safeUnlinkClaim(file);
+        throw new NodeClaimHoldError(claim.node_id, file, error);
+    }
+}
+/** Drop this process's reference to a hold file. Other holders keep it alive. */
+export function closeNodeClaimHold(fd) {
+    if (fd === undefined)
+        return;
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // Already closed, or never ours.
+    }
+}
+/**
+ * A live broker serving `stateDir`, discovered from the connection file the
+ * broker writes itself.
+ *
+ * This is the ownership evidence that survives the supervising CLI. The Rust
+ * broker writes `<state dir>/connection.json` (with its own pid) as soon as its
+ * API listener binds — BEFORE `connect_relay` and before `node.register` is
+ * queued (crates/broker/src/runtime/init.rs) — so a broker that was orphaned by
+ * a SIGKILLed supervisor before the CLI could record its pid is still
+ * discoverable by every other start on the machine. Without it, such an orphan
+ * reads as "nobody home" and the next `node up` evicts its delivery socket.
+ */
+export async function findLiveStateDirBroker(stateDir, deps = {}, 
+/** What the claim for this state dir knows about its broker executable. */
+hint = {}) {
+    const pid = readStateDirBrokerPid(stateDir);
+    if (pid === null || !isProcessAlive(pid, deps)) {
+        return null;
+    }
+    // Unlike the hold descriptor, this pid was read from a file and can have been
+    // recycled by any process on the machine, with no relationship to Relay at
+    // all. Only a positive identification keeps the node id guarded here.
+    if ((await classifyHolderProcess(pid, { stateDir, ...hint }, deps)) !== 'broker') {
+        return null;
+    }
+    const startedAt = await readProcessStartedAt(pid, deps);
+    return { pid, ...(startedAt ? { startedAt } : {}) };
+}
+/**
+ * Classify a claim for `nodeId` — the read-only view used by preflight guards
+ * and diagnostics.
+ *
+ * A claim is retired only when every process it names is provably gone (the pid
+ * no longer exists, or its birth time no longer matches the one recorded) AND
+ * no live broker occupies its state dir. Everything else — including a `ps` we
+ * cannot run — reads as held, because refusing is recoverable (`--force`,
+ * `node down`) while a wrong "free" verdict silently cuts delivery to a live
+ * broker.
+ */
+export async function inspectNodeClaim(nodeId, deps = {}) {
+    const env = deps.env ?? process.env;
+    const generations = readClaimGenerations(nodeId, env);
+    // A held generation can sit beneath a stale top claim: a `--force` takeover
+    // preserves the incumbent's record while its broker lives, and a failed
+    // takeover leaves it under the replacement's tombstone. Any live holder is
+    // a conflict for a new start, so report the newest held generation rather
+    // than only judging the top file. Newest-first keeps the diagnosis pointed
+    // at the most recent owner.
+    let fallback = null;
+    for (let index = generations.length - 1; index >= 0; index -= 1) {
+        const entry = generations[index];
+        if (!entry.claim)
+            continue;
+        const status = await classifyNodeClaim(nodeId, entry.claim, env, deps);
+        if (status.state === 'held')
+            return status;
+        fallback ??= status;
+    }
+    return fallback ?? { state: 'unclaimed' };
+}
+/**
+ * Decide whether `claim` still names a live owner.
+ *
+ * `selfPids` names processes that ARE the caller. They are skipped as recorded
+ * holders — a process cannot be a competing broker against itself — but they
+ * suppress nothing else: the orphan fences below still run in full, because a
+ * pid the caller happens to share (its own, or one recycled from the dead
+ * supervisor this claim records) says nothing about the broker that supervisor
+ * may have left registered.
+ */
+async function classifyNodeClaim(nodeId, claim, env, deps, selfPids) {
+    if (claim.node_id.trim() !== nodeId.trim()) {
+        // Sanitized filenames can collide. Report it instead of overwriting the
+        // other node's claim, which would leave that broker unguarded.
+        return {
+            state: 'held',
+            claim,
+            reason: `claim file ${nodeClaimPath(nodeId, env, claim.generation ?? 1)} records node ${claim.node_id}`,
+        };
+    }
+    const reasons = [];
+    for (const candidate of claimProcesses(claim)) {
+        if (selfPids?.has(candidate.pid)) {
+            reasons.push(`${candidate.role} pid ${candidate.pid} is this start itself`);
+            continue;
+        }
+        const status = await isRecordedProcessAlive(candidate.pid, candidate.startedAt, deps);
+        if (status.alive) {
+            return { state: 'held', claim, reason: `${candidate.role} ${status.reason}` };
+        }
+        reasons.push(`${candidate.role} ${status.reason}`);
+    }
+    // Every recorded pid is gone, but a broker this claim started can have
+    // outlived them: the supervisor may have been SIGKILLed between the spawn and
+    // the moment it could record the broker's pid.
+    //
+    // The hold descriptor is checked FIRST because it is the only evidence that
+    // exists for the whole life of that orphan. A broker child inherits it across
+    // `fork`, so it answers even while the child is still paused before binding
+    // its API — the window in which `connection.json` does not exist yet and the
+    // old "dead supervisor, nothing published" reading let a second broker start.
+    const hold = await inspectClaimHold(claim, env, deps, selfPids);
+    if (hold.held) {
+        return {
+            state: 'held',
+            // Report the pid that is actually holding the node, not the supervisor
+            // the record still names — that one is what was just proven dead, and an
+            // operator told to stop it would be chasing a process that is gone.
+            claim: {
+                ...claim,
+                ...(hold.pids[0] !== undefined ? { pid: hold.pids[0] } : {}),
+                supervisor_pid: undefined,
+            },
+            reason: `${reasons.join('; ')}, but ${hold.reason}`,
+        };
+    }
+    // Then the broker's own connection file, which survives a supervisor that
+    // died after its child had published but before it could record the pid.
+    const orphan = await findLiveStateDirBroker(claim.state_dir, deps, {
+        binary: claim.broker_binary,
+        object: claim.broker_executable,
+    });
+    if (orphan) {
+        return {
+            state: 'held',
+            claim: {
+                ...claim,
+                pid: orphan.pid,
+                ...(orphan.startedAt ? { process_started_at: orphan.startedAt } : {}),
+                supervisor_pid: undefined,
+                status: 'active',
+            },
+            reason: `${reasons.join('; ')}, but broker pid ${orphan.pid} recorded in ` +
+                `${path.join(claim.state_dir, BROKER_CONNECTION_FILENAME)} is still running`,
+        };
+    }
+    return { state: 'stale', claim, reason: reasons.join('; ') };
+}
+/** Live claims on this machine, for locating a broker across state dirs. */
+export async function listHeldNodeClaims(deps = {}) {
+    const env = deps.env ?? process.env;
+    const held = [];
+    for (const claim of listAllNodeClaims(env)) {
+        const status = await classifyNodeClaim(claim.node_id, claim, env, deps);
+        if (status.state === 'held') {
+            held.push(status.claim);
+        }
+    }
+    return held;
+}
+/* ------------------------------------------------------------------ *
+ * Acquire / adopt / release
+ * ------------------------------------------------------------------ */
+/**
+ * How many generations to try before giving up. Each attempt only loses to a
+ * start that genuinely won the node id, so more than a couple means the machine
+ * is starting brokers for one node id in a tight loop.
+ */
+const CLAIM_ACQUIRE_ATTEMPTS = 8;
+/**
+ * Create a claim file that does not exist yet, with its full contents already
+ * in place.
+ *
+ * The record is written to a private temp file and hard-linked into its
+ * generation path: `link(2)` fails with `EEXIST` rather than clobbering, so the
+ * create is both exclusive AND atomic. A reader can therefore never observe a
+ * half-written claim — which matters, because a torn read of a live broker's
+ * claim would read as "node id free".
+ *
+ * @returns False when that generation already exists.
+ */
+function createClaimGeneration(file, claim) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temporary = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    fs.writeFileSync(temporary, `${JSON.stringify(claim, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.linkSync(temporary, file);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch {
+            // Already gone; the hard link (if any) keeps the contents alive.
+        }
+    }
+}
+/** Replace a claim file in place, atomically, so no reader sees a partial write. */
+function writeClaimRecordAtomically(file, record) {
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+}
+function safeUnlinkClaim(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch {
+        // Already gone, or not ours to remove.
+    }
+}
+/**
+ * Remove a generation this acquisition has superseded, and its hold file.
+ *
+ * Only removed while the file still holds the exact bytes the scan classified.
+ * Generation numbers are never reissued (see {@link NodeClaimTombstone}), so a
+ * path cannot come back as somebody else's claim — but the scan that chose
+ * these files happened before an `await`, and pruning by path alone is what
+ * deleted a live successor's record when a number COULD be reissued. Comparing
+ * the bytes makes the check local instead of resting on that invariant.
+ */
+function pruneSupersededGeneration(entry, nodeId, env) {
+    if (readClaimBytes(entry.file) !== entry.raw) {
+        return;
+    }
+    safeUnlinkClaim(entry.file);
+    safeUnlinkClaim(nodeClaimHoldPath(nodeId, env, entry.generation));
+}
+async function buildClaim(input, generation, deps) {
+    const startedAt = await readProcessStartedAt(input.pid, deps);
+    const supervisorPid = input.supervisorPid ?? input.pid;
+    const supervisorStartedAt = supervisorPid === input.pid ? startedAt : await readProcessStartedAt(supervisorPid, deps);
+    return {
+        version: 1,
+        node_id: input.nodeId.trim(),
+        pid: input.pid,
+        state_dir: normalizeClaimStateDir(input.stateDir),
+        ...describeBrokerExecutable(input.brokerBinary),
+        ...(input.apiPort !== undefined ? { api_port: input.apiPort } : {}),
+        ...(input.brokerName ? { broker_name: input.brokerName } : {}),
+        ...(startedAt ? { process_started_at: startedAt } : {}),
+        supervisor_pid: supervisorPid,
+        ...(supervisorStartedAt ? { supervisor_started_at: supervisorStartedAt } : {}),
+        status: input.status ?? 'active',
+        claimed_at: new Date().toISOString(),
+        generation,
+        owner_token: crypto.randomUUID(),
+    };
+}
+/**
+ * Record ownership of `nodeId`, refusing if a live local broker already holds
+ * it.
+ *
+ * Ownership IS the exclusive creation of the next generation file. Generations
+ * only increase and each one is created exactly once — for the whole life of
+ * the stem, not just while a claim is live: {@link releaseNodeClaim} leaves a
+ * tombstone in place of the record it drops, so the highest number on disk
+ * never falls back. Taking a node id over therefore never involves deleting a
+ * file another process might have replaced in the meantime — the failure mode
+ * that makes "validate the holder, then remove its record, then write ours"
+ * unsafe no matter how the validation is fenced.
+ *
+ * Without that, a start suspended between the scan and the create could wake up
+ * after a complete release-and-reacquire cycle, re-create a number that had
+ * been reissued to a live successor, pass the higher-generation check because
+ * its own file was the highest again, and then prune that successor's claim
+ * from its own stale scan. Both would stay alive with one of them recorded —
+ * exactly the double registration this module exists to prevent.
+ *
+ * Two starts that both observe the same stale claim therefore cannot both win:
+ * one creates generation N+1, the other collides (`EEXIST`) and re-reads, now
+ * seeing the winner's live claim. A start that created its generation while a
+ * third one was creating a higher one loses the confirm step below, removes its
+ * own file and refuses. Exactly one — the highest generation NUMBER ever issued
+ * for the stem, live claim or spent tombstone — can own the node id, which is
+ * the invariant the post-create check below enforces.
+ *
+ * Callers reserve with `status: 'reserved'` and their own pid BEFORE spawning a
+ * broker, open the generation's hold descriptor with {@link openNodeClaimHold}
+ * so the child inherits it, and then hand ownership to the verified broker with
+ * {@link adoptNodeClaim}.
+ *
+ * @throws NodeClaimConflictError when a live local broker holds the node id and
+ * `force` was not requested.
+ * @throws NodeClaimContentionError when no generation could be won at all.
+ */
+export async function acquireNodeClaim(input) {
+    const env = input.env ?? process.env;
+    const deps = { ...input, env };
+    const nodeId = input.nodeId.trim();
+    const selfPids = new Set([input.pid]);
+    for (let attempt = 0; attempt < CLAIM_ACQUIRE_ATTEMPTS; attempt += 1) {
+        const generations = readClaimGenerations(nodeId, env);
+        if (!input.force) {
+            // Our own pid is never evidence that somebody else holds the node id, so
+            // a start may re-take a claim that records it. That exemption is scoped
+            // to the pid AS A RECORDED HOLDER and nothing more: the fence still runs.
+            //
+            // Exempting the whole check on pid equality (as this once did) was
+            // unsound, because a pid is not an identity. A supervisor that died
+            // leaving a registered broker behind records a pid the OS is free to
+            // reissue, and the next start to be handed that number would have walked
+            // straight past the orphan its own claim was pointing at.
+            //
+            // EVERY live claim refuses, not just the current one: a `--force`
+            // takeover preserves a held generation it supersedes (see the prune
+            // below), so more than one generation can record a live broker. Checking
+            // only the highest would let a stale top claim mask a held one beneath.
+            // Scan newest-first so a conflict names the most recent owner.
+            for (let index = generations.length - 1; index >= 0; index -= 1) {
+                const entry = generations[index];
+                if (!entry.claim)
+                    continue;
+                const status = await classifyNodeClaim(nodeId, entry.claim, env, deps, selfPids);
+                if (status.state === 'held') {
+                    throw new NodeClaimConflictError(nodeId, status.claim);
+                }
+            }
+        }
+        const generation = highestGenerationNumber(generations) + 1;
+        const file = nodeClaimPath(nodeId, env, generation);
+        const claim = await buildClaim(input, generation, deps);
+        if (!createClaimGeneration(file, claim)) {
+            // Another start took this generation between the scan and the create.
+            // Re-read: its claim is what decides whether we may continue at all.
+            continue;
+        }
+        const after = readClaimGenerations(nodeId, env);
+        if (highestGenerationNumber(after) > generation) {
+            // Somebody else has already been ISSUED a higher generation number, so
+            // this one cannot be the owner — whatever that higher file holds now.
+            //
+            // The test is the highest NUMBER on disk and not the highest live claim:
+            // a spent generation is a file too. A start suspended since before a
+            // release cycle could otherwise wake up, re-create a low number in the
+            // gap the cycle's pruning left, see only tombstones above it and declare
+            // itself the owner — while the start that had already read those
+            // tombstones goes on to create `max + 1`. Neither one's prune list names
+            // the other (each scanned before the other's file existed), so both stay
+            // live and both spawn. Only the record with the highest number ever
+            // issued can own the node id.
+            safeUnlinkClaim(file);
+            const winner = currentGeneration(after);
+            if (winner && winner.generation > generation) {
+                // A live claim above ours: that start legitimately won the node id.
+                throw new NodeClaimConflictError(nodeId, winner.claim ?? claim);
+            }
+            // Only spent or unreadable generations sit above ours, so the node id
+            // itself is free — this number just is not ours to hold. Re-scan and take
+            // one above the highest file on disk instead.
+            continue;
+        }
+        for (const superseded of generations) {
+            if (!superseded.claim) {
+                pruneSupersededGeneration(superseded, nodeId, env);
+                continue;
+            }
+            // A generation whose holder is still alive is not garbage: it is the
+            // only record guarding that broker's node id. A `--force` takeover that
+            // pruned it here and then failed to start left the incumbent running and
+            // unguarded — the next plain `node up` took the node id from under a
+            // live, still-registered broker. Held generations stay until their
+            // holder exits (a later acquisition prunes them as stale) or their
+            // broker is stopped (releaseNodeClaimsForBroker retires them); our own
+            // superseded generations are exempted from "held" the same way the
+            // conflict check above exempts them, so a re-acquire still cleans up.
+            const status = await classifyNodeClaim(nodeId, superseded.claim, env, deps, selfPids);
+            if (status.state !== 'held') {
+                pruneSupersededGeneration(superseded, nodeId, env);
+            }
+        }
+        return claim;
+    }
+    throw new NodeClaimContentionError(nodeId, nodeClaimsDir(env));
+}
+function isSameAcquisition(current, claim) {
+    if (!current)
+        return false;
+    if (claim.owner_token)
+        return current.owner_token === claim.owner_token;
+    // Claims written before this process (or by hand) carry no token; fall back
+    // to the identity the record does have.
+    return (current.node_id === claim.node_id && current.pid === claim.pid && current.state_dir === claim.state_dir);
+}
+/**
+ * Record the pid of the child this reservation just handed its hold descriptor
+ * to, so a later start can recognise that process no matter what it becomes.
+ *
+ * Deliberately synchronous, and called from the spawn itself rather than from
+ * the adoption that follows it: the whole point is to have the pid on disk
+ * before the child can `exec` into something the recorded executable no longer
+ * describes, and before this supervisor can be killed. It is a plain write of
+ * OUR OWN generation with no `await` between the read and the write, so it
+ * cannot interleave with anything.
+ *
+ * A failure is never fatal. This is additional positive evidence layered on top
+ * of a fence that is already in place — the descriptor was inherited at the
+ * spawn — so losing it costs the launcher/exec case, not the guarantee. The
+ * caller keeps the returned claim, which is unchanged when nothing was written.
+ */
+export function recordSpawnedBrokerChild(reservation, pid, env = process.env) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return reservation;
+    const generation = reservation.generation ?? 1;
+    const file = nodeClaimPath(reservation.node_id, env, generation);
+    try {
+        // A `--force` takeover that landed during the spawn owns the node id now.
+        // Rewriting its record would be this module's one forbidden move; the
+        // adoption below will fail this start on the same evidence.
+        if (!isSameAcquisition(readClaimFile(file), reservation))
+            return reservation;
+        const claim = { ...reservation, broker_child_pid: pid };
+        writeClaimRecordAtomically(file, claim);
+        return claim;
+    }
+    catch {
+        return reservation;
+    }
+}
+/**
+ * Hand a reservation to the verified broker process that now owns the state
+ * dir.
+ *
+ * Only the acquisition that created a generation ever rewrites it, so this is a
+ * conflict-free in-place update — but it is still conditional on that
+ * generation still being the highest: a `--force` takeover that landed while
+ * this broker was starting has already won the node id, and continuing would
+ * put two brokers back on one delivery socket. Losing here fails startup, which
+ * tears this broker down.
+ *
+ * @throws NodeClaimConflictError when the reservation no longer owns the node id.
+ */
+export async function adoptNodeClaim(input) {
+    const env = input.env ?? process.env;
+    const deps = { ...input, env };
+    const { reservation } = input;
+    const generation = reservation.generation ?? 1;
+    const file = nodeClaimPath(reservation.node_id, env, generation);
+    const before = readClaimGenerations(reservation.node_id, env);
+    if (highestGenerationNumber(before) > generation || !isSameAcquisition(readClaimFile(file), reservation)) {
+        throw new NodeClaimConflictError(reservation.node_id, currentGeneration(before)?.claim ?? reservation);
+    }
+    const startedAt = await readProcessStartedAt(input.pid, deps);
+    const claim = {
+        ...reservation,
+        pid: input.pid,
+        ...(input.apiPort !== undefined ? { api_port: input.apiPort } : {}),
+        ...(input.brokerName ? { broker_name: input.brokerName } : {}),
+        ...(startedAt ? { process_started_at: startedAt } : {}),
+        supervisor_pid: reservation.pid,
+        ...(reservation.process_started_at ? { supervisor_started_at: reservation.process_started_at } : {}),
+        status: 'active',
+    };
+    if (!startedAt)
+        delete claim.process_started_at;
+    // Atomic replace of OUR generation only: readers see the reservation or the
+    // adopted record, never a partial write, and never another start's file.
+    writeClaimRecordAtomically(file, claim);
+    const after = readClaimGenerations(reservation.node_id, env);
+    if (highestGenerationNumber(after) > generation) {
+        // A takeover landed during the write. It owns the node id; give ours up
+        // rather than leaving a second live-looking record behind.
+        safeUnlinkClaim(file);
+        safeUnlinkClaim(nodeClaimHoldPath(reservation.node_id, env, generation));
+        throw new NodeClaimConflictError(reservation.node_id, currentGeneration(after)?.claim ?? claim);
+    }
+    return claim;
+}
+/**
+ * Drop a claim this start owns, leaving its generation number spent.
+ *
+ * The record is REPLACED by a tombstone rather than removed. Removing it made
+ * the number reusable, and a suspended start could then re-create a generation
+ * that had since been handed to somebody else: it would pass the
+ * higher-generation check (its own file was the highest again) and prune the
+ * successor's live claim from its own stale scan, leaving two brokers alive on
+ * one node id with only one of them recorded. A tombstone keeps
+ * `max(generation)` from ever decreasing, so no number is issued twice; it
+ * parses as no claim at all, so the node id reads free immediately; and the
+ * next acquisition prunes it, so at most one spent file per node id is ever on
+ * disk.
+ *
+ * Only the acquisition that created a generation ever rewrites it, proven by
+ * `owner_token`, and the read and the write are adjacent syscalls with no await
+ * in between.
+ */
+export async function releaseNodeClaim(claim, env = process.env) {
+    const generation = claim.generation ?? 1;
+    const file = nodeClaimPath(claim.node_id, env, generation);
+    if (!isSameAcquisition(readClaimFile(file), claim)) {
+        return false;
+    }
+    try {
+        writeClaimRecordAtomically(file, {
+            version: 1,
+            released: true,
+            node_id: claim.node_id,
+            generation,
+            released_at: new Date().toISOString(),
+        });
+    }
+    catch {
+        return false;
+    }
+    // The hold descriptor protected this generation only; both processes it
+    // fenced are gone by the time a release is allowed to run.
+    safeUnlinkClaim(nodeClaimHoldPath(claim.node_id, env, generation));
+    return true;
+}
+/**
+ * Release the claims a broker pid held in a state dir. `node down` stops a
+ * broker it did not start, so it cannot name the node id the claim was written
+ * for — the pid and state dir it verified are what it has.
+ *
+ * A claim for that state dir whose every recorded pid is already dead is
+ * released too: that is the orphan left by a supervisor that was killed before
+ * it could record its broker's pid, and `down` has just proven the state dir's
+ * broker is gone.
+ */
+export async function releaseNodeClaimsForBroker(input) {
+    const env = input.env ?? process.env;
+    const deps = { ...input, env };
+    const stateDir = normalizeClaimStateDir(input.stateDir);
+    const released = [];
+    for (const claim of listAllNodeClaims(env)) {
+        if (claim.state_dir !== stateDir)
+            continue;
+        const namesThisBroker = claim.pid === input.pid || claim.supervisor_pid === input.pid;
+        if (!namesThisBroker) {
+            const status = await classifyNodeClaim(claim.node_id, claim, env, deps);
+            if (status.state !== 'stale')
+                continue;
+        }
+        if (await releaseNodeClaim(claim, env)) {
+            released.push(claim);
+        }
+    }
+    return released;
+}
+/** One-line description of the broker holding a claim, for operator output. */
+export function describeNodeClaimHolder(claim) {
+    const parts = [`pid ${claim.pid}`, `state dir ${claim.state_dir}`];
+    if (claim.api_port !== undefined)
+        parts.push(`API port ${claim.api_port}`);
+    if (claim.broker_name)
+        parts.push(`broker name ${claim.broker_name}`);
+    if (claim.status === 'reserved')
+        parts.push('starting up');
+    return parts.join(', ');
+}
+//# sourceMappingURL=node-claim.js.map