@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/lib/socks5-fetch.ts

@@ -1,5 +1,6 @@
 import net, { type Socket } from "node:net";
 import tls, { type TLSSocket } from "node:tls";
+import { classifyContentCoding, isNullBodyStatus } from "./http-response-semantics";
 
 const DEFAULT_SOCKS5_PORT = 1080;
 const SOCKS5_CONNECT_TIMEOUT_MS = 30_000;
@@ -510,7 +511,9 @@ function responseBody(
 
 /** Statuses and methods that carry no response body, whatever the headers say about one. */
 function bodylessResponse(method: string, status: number): boolean {
-  return method === "HEAD" || status === 204 || status === 304 || (status >= 100 && status < 200);
+  // 205 belongs here for the same reason 204 does, and leaving it out was not a judgement call:
+  // a peer that resets the caller's view sends no body, so the Response constructor rejects one.
+  return method === "HEAD" || isNullBodyStatus(status) || (status >= 100 && status < 200);
 }
 
 /**
@@ -528,11 +531,121 @@ function bodylessResponse(method: string, status: number): boolean {
  * the coded path would fail responses that succeed uncompressed.
  */
 function contentCodingFormat(headers: Headers): "gzip" | "deflate" | undefined {
-  const coding = (headers.get("content-encoding") ?? "").trim().toLowerCase();
-  if (coding === "" || coding === "identity") return undefined;
-  if (coding === "gzip" || coding === "x-gzip") return "gzip";
-  if (coding === "deflate") return "deflate";
-  throw new Socks5FetchError("SOCKS5 upstream returned an unsupported content-encoding: " + coding);
+  const coding = classifyContentCoding(headers);
+  if (coding.kind === "identity") return undefined;
+  if (coding.kind === "decodable") return coding.format;
+  throw new Socks5FetchError("SOCKS5 upstream returned an unsupported content-encoding: " + coding.coding);
+}
+
+/** Read response heads until the final one, consuming the interim informational answers. */
+async function finalResponseHead(
+  reader: SocketReader,
+  signal: AbortSignal,
+): Promise<{ status: number; statusText: string; headers: Headers }> {
+  let head = parseResponseHead(await reader.readUntil(HEADER_END, MAX_RESPONSE_HEADER_BYTES, signal));
+  while (head.status >= 100 && head.status < 200 && head.status !== 101) {
+    head = parseResponseHead(await reader.readUntil(HEADER_END, MAX_RESPONSE_HEADER_BYTES, signal));
+  }
+  return head;
+}
+
+/**
+ * A promise that rejects with the caller's abort reason, and a way to stop listening.
+ *
+ * Destroying the socket is not enough to end a pending `bodyReader.read()`: that promise belongs
+ * to the caller's body stream, which knows nothing about this socket. Racing it against this one
+ * is what turns an abort into a settled fetch instead of a permanently pending one.
+ */
+function abortRejection(signal: AbortSignal): { promise: Promise<never>; dispose: () => void } {
+  let onAbort = (): void => { /* replaced below */ };
+  const promise = new Promise<never>((_resolve, reject) => {
+    // Reject with the caller's reason exactly, including `null` and `false`. A real
+    // `AbortSignal` always has one — `abort()` with no argument supplies an AbortError — so
+    // the fallback covers only a hand-built signal that exposes none.
+    onAbort = () => reject(signal.reason === undefined ? new Error("The operation was aborted") : signal.reason);
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+  // The race below may settle on another branch first; this rejection must not be reported as
+  // unhandled when nobody is left waiting for it.
+  promise.catch(() => { /* surfaced by whoever loses the race */ });
+  return { promise, dispose: () => signal.removeEventListener("abort", onAbort) };
+}
+
+/**
+ * The two races below have different possible outcomes, so they have different result types.
+ * One union covering both would let the compiler accept reading `value` off a drain result,
+ * which is the kind of mistake a type is supposed to catch rather than describe.
+ */
+type Answered = { kind: "answered" };
+type BodyStep = { kind: "chunk"; value: Uint8Array } | { kind: "end" } | Answered;
+type DrainStep = { kind: "drained" } | Answered;
+
+/**
+ * Send the request body, settling on caller abort or on an answer that arrives first.
+ *
+ * A peer is entitled to answer a request it has not finished receiving — a 413 or a 401 lands
+ * while a large body is still going out — and a body stream is entitled to stall. Waiting for
+ * the upload to finish before looking at the socket made those two facts combine into a fetch
+ * that never settles, with the answer already sitting in the receive buffer.
+ *
+ * `answered` covers the head settling either way: a final response means the peer has stopped
+ * reading, and a terminal socket failure means nothing more can be written. Which of the two it
+ * was belongs to whoever awaits the head, so this only needs to know that it happened.
+ */
+async function uploadRequestBody(
+  socket: Socket,
+  request: Request,
+  chunked: boolean,
+  head: Promise<unknown>,
+): Promise<void> {
+  const body = request.body;
+  if (!body) return;
+  const signal = request.signal;
+  const bodyReader = body.getReader();
+  const abort = abortRejection(signal);
+  const answered: Promise<Answered> = head.then(
+    (): Answered => ({ kind: "answered" }),
+    (): Answered => ({ kind: "answered" }),
+  );
+  let completed = false;
+  try {
+    for (;;) {
+      const read: Promise<BodyStep> = bodyReader.read().then(
+        (result): BodyStep => (result.done ? { kind: "end" } : { kind: "chunk", value: result.value }),
+      );
+      // Releasing the lock below rejects a read still waiting on a source that stopped
+      // producing. That rejection is this function's own doing, not a failure to report.
+      read.catch(() => { /* settled by releasing the reader */ });
+      const step = await Promise.race([read, answered, abort.promise]);
+      if (step.kind === "answered") break;
+      if (step.kind === "end") {
+        completed = true;
+        break;
+      }
+      const payload = chunked
+        ? Buffer.concat([Buffer.from(`${step.value.byteLength.toString(16)}\r\n`), Buffer.from(step.value), CRLF])
+        : step.value;
+      if (socket.write(payload)) continue;
+      const drain: Promise<DrainStep> = waitForDrain(socket, signal).then((): DrainStep => ({ kind: "drained" }));
+      if ((await Promise.race([drain, answered, abort.promise])).kind === "answered") break;
+    }
+    // A terminating chunk written after the peer has already answered goes into a conversation
+    // that is over, and a peer that has moved on may read it as the head of the next request.
+    if (completed && chunked && !socket.write("0\r\n\r\n")) {
+      const drain: Promise<DrainStep> = waitForDrain(socket, signal).then((): DrainStep => ({ kind: "drained" }));
+      await Promise.race([drain, answered, abort.promise]);
+    }
+  } finally {
+    abort.dispose();
+    if (!completed) {
+      // Cancelling runs the caller's own cancel algorithm, which is free to never settle, so it
+      // is started rather than awaited. Releasing the lock is what actually frees a read still
+      // waiting on a body that stopped producing.
+      void bodyReader.cancel().catch(() => { /* the caller's stream owns this outcome */ });
+    }
+    try { bodyReader.releaseLock(); } catch { /* already released */ }
+  }
 }
 
 export async function socks5Fetch(
@@ -570,26 +683,16 @@ export async function socks5Fetch(
     const headers = requestHeaders(request, target);
     const head = `${request.method} ${target.pathname}${target.search} HTTP/1.1\r\n${headers.text}\r\n`;
     socket.write(head);
-    if (request.body) {
-      const bodyReader = request.body.getReader();
-      try {
-        while (true) {
-          const next = await bodyReader.read();
-          if (next.done) break;
-          const body = headers.chunked
-            ? Buffer.concat([Buffer.from(`${next.value.byteLength.toString(16)}\r\n`), Buffer.from(next.value), CRLF])
-            : next.value;
-          if (!socket.write(body)) await waitForDrain(socket, request.signal);
-        }
-        if (headers.chunked && !socket.write("0\r\n\r\n")) await waitForDrain(socket, request.signal);
-      } finally {
-        bodyReader.releaseLock();
-      }
-    }
-    let responseHead = parseResponseHead(await reader.readUntil(HEADER_END, MAX_RESPONSE_HEADER_BYTES, request.signal));
-    while (responseHead.status >= 100 && responseHead.status < 200 && responseHead.status !== 101) {
-      responseHead = parseResponseHead(await reader.readUntil(HEADER_END, MAX_RESPONSE_HEADER_BYTES, request.signal));
-    }
+    // Start reading the answer before the upload finishes, and keep one consumer of the socket
+    // reader for the whole exchange. The upload races this promise so an early final response or
+    // a terminal socket failure ends it, instead of leaving it waiting on a body chunk that is
+    // never coming while the answer sits in the receive buffer.
+    const pendingHead = finalResponseHead(reader, request.signal);
+    // The upload observes this promise through a handler of its own; this one keeps a rejection
+    // from being reported as unhandled in the window before the await below.
+    pendingHead.catch(() => { /* rethrown by the await below */ });
+    await uploadRequestBody(socket, request, headers.chunked, pendingHead);
+    const responseHead = await pendingHead;
     // A bodyless response has no coded bytes to undo, so its `content-encoding` describes the
     // representation it would have sent and must neither be decoded nor refused — a HEAD whose
     // peer advertises brotli is a correct answer, not an unreadable body. For everything else,
@@ -626,6 +729,13 @@ export async function socks5Fetch(
     request.signal.removeEventListener("abort", onAbort);
     reader?.dispose();
     socket.destroy();
+    // An aborted caller gets its own reason back. Several waiters inside this transport can win
+    // the race that settles an abort, and they do not agree on what to do with a reason they
+    // consider absent: the socket reader substitutes an Error for a null reason, others coerce
+    // anything that is not an Error. Without this, the same `abort(null)` surfaces as an Error
+    // or as null depending on scheduling. `undefined` is left alone so a hand-built signal
+    // still reaches the thrown cause below.
+    if (request.signal.aborted && request.signal.reason !== undefined) throw request.signal.reason;
     throw error;
   }
 }

package/src/lib/spend-ledger-owner.ts

@@ -0,0 +1,364 @@
+/** Process-lifetime single-writer ownership for the shared spend journal. */
+import { Database } from "bun:sqlite";
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { recordOwnedConfigPath } from "./config-ownership";
+import { assertNotRealHomeUnderTest } from "./test-home-guard";
+import { hardenSecretDir, hardenSecretPath } from "./windows-secret-acl";
+
+export const SPEND_LEDGER_OWNER_FILENAME = "spend-ledger-owner.sqlite";
+export const SPEND_LEDGER_RESTART_PARENT_ENV = "OCX_SPEND_LEDGER_RESTART_PARENT_PID";
+export const SPEND_LEDGER_RESTART_WAIT_MS = 5_000;
+const OWNER_SIDECARS = ["-journal", "-wal", "-shm"] as const;
+
+export type SpendLedgerOwnerErrorCode =
+  | "SPEND_LEDGER_OWNER_BUSY"
+  | "SPEND_LEDGER_OWNER_UNAVAILABLE"
+  | "SPEND_LEDGER_OWNER_HOME_CONFLICT"
+  | "SPEND_LEDGER_OWNER_NOT_HELD";
+
+export class SpendLedgerOwnerError extends Error {
+  constructor(readonly code: SpendLedgerOwnerErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SpendLedgerOwnerError";
+  }
+}
+
+export interface SpendLedgerOwnerLease {
+  release(): void;
+}
+
+interface ActiveOwner {
+  readonly home: string;
+  readonly database: Database;
+  references: number;
+}
+
+let activeOwner: ActiveOwner | null = null;
+let boundLedgerHome: string | null = null;
+/**
+ * Identity of the current ownership, not just of the home it covers.
+ *
+ * A home name alone cannot tell "still the lease I was built under" from "the same directory,
+ * owned again since". A ledger that only checked the home therefore came back to life across a
+ * release and a reacquire, writing totals it had accumulated before another writer owned the
+ * journal. Every acquisition that actually takes the lock mints a new value.
+ */
+let ownerGeneration = 0;
+const releaseHooks: Array<() => void> = [];
+
+/**
+ * Run when the last lease on a state directory goes away.
+ *
+ * The ledger singleton is bound to the home it was built for, so it has to go when ownership
+ * does; otherwise a process that starts a second server against a different state directory
+ * either writes the old home's journal or is refused for a conflict it no longer has. The
+ * journal on disk is the durable record and construction replays it, so nothing is lost.
+ */
+export function onSpendLedgerOwnerReleased(hook: () => void): void {
+  releaseHooks.push(hook);
+}
+
+function errorCode(error: unknown): unknown {
+  return error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+}
+
+function assertPrivateFile(path: string): void {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger ownership could not be established safely.",
+    );
+  }
+  if (process.platform !== "win32" && stat.uid !== process.getuid!()) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger ownership could not be established safely.",
+    );
+  }
+}
+
+function prepareOwnerPath(configDir: string): { home: string; path: string } {
+  const requested = resolve(configDir);
+  // First statement before mutation: tests must never acquire against the real user home.
+  assertNotRealHomeUnderTest(requested);
+  mkdirSync(requested, { recursive: true, mode: 0o700 });
+  const home = realpathSync.native(requested);
+  if (process.platform !== "win32") chmodSync(home, 0o700);
+  hardenSecretDir(home, { required: true });
+  const path = join(home, SPEND_LEDGER_OWNER_FILENAME);
+  // Registered while the directory is still EMPTY. Config ownership refuses to claim a
+  // directory that already has contents, so creating the database first meant a fresh home
+  // never got an ownership marker at all: the manifest was never written, and the database and
+  // its sidecars were left behind by a later uninstall because nothing recorded them.
+  recordOwnedConfigPath(home, path);
+  for (const suffix of OWNER_SIDECARS) recordOwnedConfigPath(home, `${path}${suffix}`);
+  try { closeSync(openSync(path, "wx", 0o600)); }
+  catch (error) { if (errorCode(error) !== "EEXIST") throw error; }
+  assertPrivateFile(path);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+  hardenSecretPath(path, { required: true });
+  assertPrivateFile(path);
+  return { home: process.platform === "win32" ? home.toLowerCase() : home, path };
+}
+
+function isBusy(error: unknown): boolean {
+  const code = errorCode(error);
+  const message = error instanceof Error ? error.message : "";
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+function stateDirectoryIdentity(configDir: string): string {
+  const requested = resolve(configDir);
+  assertNotRealHomeUnderTest(requested);
+  let canonical = requested;
+  try { canonical = realpathSync.native(requested); } catch { /* acquisition owns creation */ }
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+function restartHandoffWaitMs(): number {
+  const markedParent = process.env[SPEND_LEDGER_RESTART_PARENT_ENV];
+  delete process.env[SPEND_LEDGER_RESTART_PARENT_ENV];
+  return markedParent === String(process.ppid) ? SPEND_LEDGER_RESTART_WAIT_MS : 0;
+}
+
+/** Mark only a parent-exit restart child for bounded lease acquisition. */
+export function spendLedgerRestartEnvironment(
+  source: NodeJS.ProcessEnv,
+  parentPid?: number,
+): NodeJS.ProcessEnv {
+  const env = { ...source };
+  if (parentPid === undefined) delete env[SPEND_LEDGER_RESTART_PARENT_ENV];
+  else env[SPEND_LEDGER_RESTART_PARENT_ENV] = String(parentPid);
+  return env;
+}
+
+/**
+ * Hold one SQLite write transaction until the final in-process reference releases it.
+ * SQLite and the OS release a crashed process; no PID, timestamp, TTL or lock-file unlink
+ * can evict a live owner or mistake a reused process identity for this lease.
+ */
+export function acquireSpendLedgerOwner(configDir = getConfigDir()): SpendLedgerOwnerLease {
+  const requestedHome = stateDirectoryIdentity(configDir);
+  const busyTimeout = restartHandoffWaitMs();
+  if (boundLedgerHome !== null && boundLedgerHome !== requestedHome) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_HOME_CONFLICT",
+      "This process already owns the spend ledger for a different state directory.",
+    );
+  }
+  if (activeOwner) {
+    if (activeOwner.home !== requestedHome) {
+      throw new SpendLedgerOwnerError(
+        "SPEND_LEDGER_OWNER_HOME_CONFLICT",
+        "This process already owns the spend ledger for a different state directory.",
+      );
+    }
+    activeOwner.references += 1;
+    return leaseFor(activeOwner);
+  }
+
+  let prepared: { home: string; path: string };
+  try {
+    prepared = prepareOwnerPath(configDir);
+  } catch (cause) {
+    if (cause instanceof SpendLedgerOwnerError) throw cause;
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger ownership could not be established safely.",
+      { cause },
+    );
+  }
+
+  let database: Database | undefined;
+  try {
+    database = new Database(prepared.path, { create: true });
+    database.exec(`PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = ${busyTimeout}; BEGIN IMMEDIATE`);
+  } catch (cause) {
+    try { database?.close(); } catch { /* preserve acquisition failure */ }
+    if (isBusy(cause)) {
+      throw new SpendLedgerOwnerError(
+        "SPEND_LEDGER_OWNER_BUSY",
+        "Another OpenCodex process already owns this spend ledger. Use a separate OPENCODEX_HOME for an independent instance.",
+      );
+    }
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger ownership could not be established safely.",
+      { cause },
+    );
+  }
+
+  activeOwner = { home: prepared.home, database, references: 1 };
+  ownerGeneration += 1;
+  return leaseFor(activeOwner);
+}
+
+function leaseFor(owner: ActiveOwner): SpendLedgerOwnerLease {
+  let released = false;
+  return Object.freeze({
+    release(): void {
+      if (released) return;
+      released = true;
+      if (activeOwner !== owner || owner.references < 1) return;
+      owner.references -= 1;
+      if (owner.references > 0) return;
+      activeOwner = null;
+      boundLedgerHome = null;
+      for (const hook of releaseHooks) {
+        try { hook(); } catch { /* a discard hook must not mask a release failure */ }
+      }
+      let failure: unknown;
+      try { owner.database.exec("ROLLBACK"); } catch (error) { failure = error; }
+      try { owner.database.close(); } catch (error) { failure ??= error; }
+      if (failure !== undefined) {
+        throw new SpendLedgerOwnerError(
+          "SPEND_LEDGER_OWNER_UNAVAILABLE",
+          "Spend-ledger ownership could not be released cleanly.",
+          { cause: failure },
+        );
+      }
+    },
+  });
+}
+
+/** The ownership a ledger was built under, to be handed back on every later use. */
+export function currentSpendLedgerOwnerGeneration(): number {
+  return ownerGeneration;
+}
+
+/**
+ * Permission to touch one file under the owned state directory, for as long as this exact
+ * ownership lasts.
+ *
+ * A callback supplied by the caller cannot be this proof: the caller can pass one that does
+ * nothing, which is how a "required guard" still allowed an unowned write. A marker carried ON
+ * the object is not proof either, because an object spread copies it: `{ ...minted, path:
+ * elsewhere, assert() {} }` would look minted while pointing somewhere else. So the token
+ * carries nothing. The path and the ownership it was minted under live in a table only this
+ * module can read, keyed by the token's identity, and a copy is simply not that key.
+ */
+export interface SpendLedgerStorage {
+  readonly __spendLedgerStorage: unique symbol;
+}
+
+const mintedStorage = new WeakMap<object, { readonly path: string; readonly generation: number; readonly home: string }>();
+
+function trustedStorage(storage: SpendLedgerStorage): { readonly path: string; readonly generation: number; readonly home: string } {
+  const entry = typeof storage === "object" && storage !== null ? mintedStorage.get(storage) : undefined;
+  if (!entry) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_NOT_HELD",
+      "Spend-ledger ownership is required before the shared ledger can be used.",
+    );
+  }
+  return entry;
+}
+
+/**
+ * Mint storage permission for one file name directly under the owned state directory.
+ *
+ * The name is a file name, never a path: joining a caller-supplied path would let the caller
+ * choose the destination, which is the thing ownership is supposed to decide.
+ */
+export function mintSpendLedgerStorage(fileName: string): SpendLedgerStorage {
+  if (fileName.includes("/") || fileName.includes("\\") || fileName === "." || fileName === "..") {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger storage could not be established safely.",
+    );
+  }
+  assertSpendLedgerOwnerHeld();
+  const owner = activeOwner;
+  if (!owner) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_NOT_HELD",
+      "Spend-ledger ownership is required before the shared ledger can be used.",
+    );
+  }
+  const generation = ownerGeneration;
+  const home = owner.home;
+  // The token is deliberately empty: everything trustworthy about it is held here, under its
+  // identity, where a spread cannot reach.
+  const token = Object.freeze({}) as unknown as SpendLedgerStorage;
+  mintedStorage.set(token, { path: join(home, fileName), generation, home });
+  return token;
+}
+
+/** The file this token stands for, as this module recorded it at mint time. */
+export function spendLedgerStoragePath(storage: SpendLedgerStorage): string {
+  return trustedStorage(storage).path;
+}
+
+/**
+ * Refuse unless this exact token was minted here and its ownership is still current.
+ *
+ * Both halves matter: identity rules out a copy or a look-alike, and the generation rules out a
+ * token minted before the lock was dropped and taken again.
+ */
+export function assertStorageOwned(storage: SpendLedgerStorage): void {
+  const entry = trustedStorage(storage);
+  assertSpendLedgerOwnerGeneration(entry.generation, entry.home);
+}
+
+/**
+ * Refuse a handle built under an ownership that has since ended.
+ *
+ * The state directory may be the same one; what matters is that the lock was dropped and taken
+ * again in between, because another process could have written the journal while it was free.
+ */
+export function assertSpendLedgerOwnerGeneration(generation: number, configDir = getConfigDir()): void {
+  assertSpendLedgerOwnerHeld(configDir);
+  if (generation !== ownerGeneration) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_NOT_HELD",
+      "Spend-ledger ownership is required before the shared ledger can be used.",
+    );
+  }
+}
+
+/** The singleton journal may be touched only while its matching state directory is owned. */
+export function assertSpendLedgerOwnerHeld(configDir = getConfigDir()): void {
+  let home: string;
+  try {
+    const canonical = realpathSync.native(resolve(configDir));
+    home = process.platform === "win32" ? canonical.toLowerCase() : canonical;
+  } catch (cause) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_NOT_HELD",
+      "Spend-ledger ownership is required before the shared ledger can be used.",
+      { cause },
+    );
+  }
+  if (!activeOwner || activeOwner.home !== home || activeOwner.references < 1) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_NOT_HELD",
+      "Spend-ledger ownership is required before the shared ledger can be used.",
+    );
+  }
+}
+
+/** Permanently bind the live process-wide singleton to its first constructed home. */
+export function bindSpendLedgerOwnerHome(configDir = getConfigDir()): void {
+  assertSpendLedgerOwnerHeld(configDir);
+  const home = stateDirectoryIdentity(configDir);
+  if (boundLedgerHome !== null && boundLedgerHome !== home) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_HOME_CONFLICT",
+      "This process already owns the spend ledger for a different state directory.",
+    );
+  }
+  boundLedgerHome = home;
+}
+
+export function spendLedgerOwnerSnapshot(): { readonly ownership: "held" | "unheld" } {
+  return { ownership: activeOwner ? "held" : "unheld" };
+}
+
+/** Test seam paired with discarding the process-wide ledger singleton. */
+export function resetSpendLedgerOwnerBindingForTest(): void {
+  boundLedgerHome = null;
+}