@aibtc/mcp-server 1.74.0 → 1.76.0

package/README.md

@@ -141,8 +141,8 @@ npx @aibtc/mcp-server@latest --install --profile full   # writes AIBTC_TOOLS=all
 | `identity` | ERC-8004 identity and reputation, message signing |
 | `social` | Nostr, AIBTC inbox |
 | `earn` | Bounty board (create, accept, pay, my views) |
-| `legion` | AIBTC News Legion |
-| `markets` | Stacks prediction market, At Stake |
+| `legion` | AIBTC News Legion, At Stake side legions (El Salvador) |
+| `markets` | Stacks prediction market, At Stake market |
 | `dev` | Scaffolding, OpenRouter, settings, inference marketplace, arXiv |
 
 The server's instructions list the groups that are off, so the agent can tell you which one to enable. The OpenRouter `bridge` starts from the full set and narrows it with its own `--read-only`/`--allow`/`--block` flags.

package/dist/services/btc-spend.d.ts

@@ -8,7 +8,7 @@
  * builder produced it.
  */
 import * as btc from "@scure/btc-signer";
-import type { MempoolApi } from "./mempool-api.js";
+import { type MempoolApi } from "./mempool-api.js";
 import type { Network } from "../config/networks.js";
 /** The wallet a Bitcoin spend is billed to. */
 export interface BtcSpender {
@@ -32,8 +32,9 @@ export declare function btcTxOutflowSats(api: MempoolApi, txHex: string, spender
 export declare function psbtOutflowSats(tx: btc.Transaction, signedInputs: number[], spender: BtcSpender, network: Network): bigint;
 /**
  * Broadcast a signed transaction that spends from this wallet, metered by the
- * spending limit: refused before broadcast when it would exceed the cap,
- * recorded once broadcast.
+ * spending limit: booked before broadcast (refused when it would exceed the
+ * cap), given back only when the node rejects it. A network error leaves it
+ * unknown whether the transaction was relayed, so the booking stands.
  */
 export declare function meteredBtcBroadcast(api: MempoolApi, txHex: string, spender: BtcSpender, network: Network): Promise<string>;
 //# sourceMappingURL=btc-spend.d.ts.map

package/dist/services/btc-spend.js

@@ -10,6 +10,7 @@
 import * as btc from "@scure/btc-signer";
 import { hex } from "@scure/base";
 import { getBtcNetwork } from "../transactions/bitcoin-builder.js";
+import { BroadcastRejectedError } from "./mempool-api.js";
 import { getSpendLimiter } from "./spend-limiter.js";
 function ownAddresses(spender) {
     return [spender.btcAddress, spender.taprootAddress].filter((a) => !!a);
@@ -86,14 +87,21 @@ export function psbtOutflowSats(tx, signedInputs, spender, network) {
 }
 /**
  * Broadcast a signed transaction that spends from this wallet, metered by the
- * spending limit: refused before broadcast when it would exceed the cap,
- * recorded once broadcast.
+ * spending limit: booked before broadcast (refused when it would exceed the
+ * cap), given back only when the node rejects it. A network error leaves it
+ * unknown whether the transaction was relayed, so the booking stands.
  */
 export async function meteredBtcBroadcast(api, txHex, spender, network) {
     const amount = await btcTxOutflowSats(api, txHex, spender, network);
-    await getSpendLimiter().check("sats", amount, spender.address);
-    const txid = await api.broadcastTransaction(txHex);
-    await getSpendLimiter().record("sats", amount, spender.address);
-    return txid;
+    const limiter = getSpendLimiter();
+    const reservation = await limiter.reserve([{ unit: "sats", amount }], spender.address);
+    try {
+        return await api.broadcastTransaction(txHex);
+    }
+    catch (error) {
+        if (error instanceof BroadcastRejectedError)
+            await limiter.release(reservation);
+        throw error;
+    }
 }
 //# sourceMappingURL=btc-spend.js.map

package/dist/services/mempool-api.d.ts

@@ -11,6 +11,10 @@ import type { Network } from "../config/networks.js";
 /**
  * UTXO (Unspent Transaction Output) from mempool.space API
  */
+/** mempool.space answered the broadcast with a 4xx: the transaction was refused, not relayed. */
+export declare class BroadcastRejectedError extends Error {
+    constructor(message: string);
+}
 export interface UTXO {
     /**
      * Transaction ID containing this UTXO

package/dist/services/mempool-api.js

@@ -7,6 +7,16 @@
  *
  * Documentation: https://mempool.space/docs/api
  */
+/**
+ * UTXO (Unspent Transaction Output) from mempool.space API
+ */
+/** mempool.space answered the broadcast with a 4xx: the transaction was refused, not relayed. */
+export class BroadcastRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BroadcastRejectedError";
+    }
+}
 /**
  * Get the mempool.space API base URL for a network
  */
@@ -157,7 +167,11 @@ export class MempoolApi {
         });
         if (!response.ok) {
             const errorText = await response.text().catch(() => "Unknown error");
-            throw new Error(`Failed to broadcast transaction: ${response.status} ${response.statusText} - ${errorText}`);
+            const message = `Failed to broadcast transaction: ${response.status} ${response.statusText} - ${errorText}`;
+            // A 4xx is the node refusing the transaction: it was not relayed.
+            if (response.status < 500)
+                throw new BroadcastRejectedError(message);
+            throw new Error(message);
         }
         // Response is the txid as plain text
         const txid = await response.text();

package/dist/services/spend-limiter.d.ts

@@ -91,6 +91,15 @@ export declare class SpendLimitError extends Error {
     readonly scope: "session" | "day";
     constructor(message: string, unit: SpendUnit, attempted: number, remaining: number, scope: "session" | "day");
 }
+/** What `reserve()` booked, for `release()` to give back. */
+export interface SpendReservation {
+    addr: string;
+    day: string;
+    spends: Array<{
+        unit: SpendUnit;
+        amount: number;
+    }>;
+}
 declare class SpendLimiter {
     private static instance;
     private stateFile;
@@ -105,12 +114,47 @@ declare class SpendLimiter {
     /** Reset the in-memory session ledger for a wallet (call on unlock/lock/switch). */
     resetSession(addr: string): void;
     /**
-     * Throw SpendLimitError if `amount` would push the session OR day total over
-     * its cap. Does NOT record — call recordSpend after a successful broadcast.
+     * Book `spends` against the session and day ledgers, or throw
+     * SpendLimitError if any of them would push a total over its cap. Call this
+     * BEFORE signing, and `release()` the result if the spend then fails before
+     * it leaves this process.
+     *
+     * The cap check and the booking are one step under the shared file lease.
+     * A separate check and record let two processes both pass the check against
+     * the same day total and then both spend (#683). Booked here, a second
+     * process sees this spend in the total before it signs. A process that dies
+     * between reserve and broadcast leaves the spend booked: over-counting is
+     * the safe direction, and the skills engine does the same.
+     *
+     * All units are checked before any is booked, so a contract call moving STX
+     * and sBTC is booked whole or not at all.
+     */
+    reserve(spends: Array<{
+        unit: SpendUnit;
+        amount: bigint;
+    }>, addr: string): Promise<SpendReservation>;
+    /**
+     * Give back a reservation whose spend never left this process (signing or
+     * broadcast failed, or a fallback path books its own). Without the lease
+     * the day ledger is left as is: an unlocked write could drop another
+     * process's booking, while skipping only over-counts.
+     *
+     * Idempotent: a reservation is given back at most once, so a caller that
+     * releases before a fallback and again when that fallback throws does not
+     * subtract twice.
+     *
+     * Never throws. Callers release on their way to rethrowing the real failure
+     * or into a fallback; a ledger write error here must not replace either.
+     * Failing to give budget back only over-counts.
+     */
+    release(reservation: SpendReservation): Promise<void>;
+    /**
+     * Serialize ledger updates inside this process. The file lease excludes the
+     * OTHER process (the skills engine's direct x402 path shares
+     * spend-state.json so one wallet has one daily cap); this chain keeps two
+     * calls in this process from interleaving their read-modify-writes.
      */
-    check(unit: SpendUnit, amount: bigint, addr: string): Promise<void>;
-    /** Record a completed spend against both the session and day ledgers. */
-    record(unit: SpendUnit, amount: bigint, addr: string): Promise<void>;
+    private serialized;
     /** Remaining session/day budget for status reporting. */
     status(addr: string): Promise<{
         enabled: boolean;

package/dist/services/spend-limiter.js

@@ -182,6 +182,21 @@ export class SpendLimitError extends Error {
         this.name = "SpendLimitError";
     }
 }
+/**
+ * Drop every day but `today`, for every wallet, so the file does not grow
+ * unbounded. Runs only under the lease: it walks EVERY address, so an
+ * unlocked write could lose another wallet's day too.
+ */
+function pruneOtherDays(state, today) {
+    for (const a of Object.keys(state)) {
+        for (const day of Object.keys(state[a])) {
+            if (day !== today)
+                delete state[a][day];
+        }
+        if (Object.keys(state[a]).length === 0)
+            delete state[a];
+    }
+}
 class SpendLimiter {
     static instance;
     stateFile = DEFAULT_STATE_FILE;
@@ -226,80 +241,129 @@ class SpendLimiter {
         this.session.delete(addr);
     }
     /**
-     * Throw SpendLimitError if `amount` would push the session OR day total over
-     * its cap. Does NOT record — call recordSpend after a successful broadcast.
+     * Book `spends` against the session and day ledgers, or throw
+     * SpendLimitError if any of them would push a total over its cap. Call this
+     * BEFORE signing, and `release()` the result if the spend then fails before
+     * it leaves this process.
+     *
+     * The cap check and the booking are one step under the shared file lease.
+     * A separate check and record let two processes both pass the check against
+     * the same day total and then both spend (#683). Booked here, a second
+     * process sees this spend in the total before it signs. A process that dies
+     * between reserve and broadcast leaves the spend booked: over-counting is
+     * the safe direction, and the skills engine does the same.
+     *
+     * All units are checked before any is booked, so a contract call moving STX
+     * and sBTC is booked whole or not at all.
      */
-    async check(unit, amount, addr) {
-        if (!isEnabled())
-            return;
-        if (amount <= 0n)
-            return;
-        const amt = Number(amount);
-        const { daily, session } = capsFor(unit);
-        const sessionSpent = this.getSession(addr)[unit];
-        if (sessionSpent + amt > session) {
-            const remaining = Math.max(0, session - sessionSpent);
-            throw new SpendLimitError(this.message(unit, amt, remaining, "session", session), unit, amt, remaining, "session");
-        }
-        const state = await this.readState();
-        const daySpent = state[addr]?.[todayKey()]?.[unit] ?? 0;
-        if (daySpent + amt > daily) {
-            const remaining = Math.max(0, daily - daySpent);
-            throw new SpendLimitError(this.message(unit, amt, remaining, "day", daily), unit, amt, remaining, "day");
+    async reserve(spends, addr) {
+        const booked = spends
+            .filter((s) => s.amount > 0n)
+            .map((s) => ({ unit: s.unit, amount: Number(s.amount) }));
+        if (!isEnabled() || booked.length === 0)
+            return { addr, day: todayKey(), spends: [] };
+        const totals = { ustx: 0, sats: 0 };
+        for (const { unit, amount } of booked)
+            totals[unit] += amount;
+        const run = await this.serialized(() => withSharedStateLock(this.stateFile, async () => {
+            // Read the day under the lease: waiting for it can cross UTC midnight,
+            // and pruning against a stale day would delete the new one.
+            const day = todayKey();
+            const session = this.getSession(addr);
+            const state = await this.readState();
+            for (const unit of ["ustx", "sats"]) {
+                const amt = totals[unit];
+                if (amt === 0)
+                    continue;
+                const { daily, session: sessionCap } = capsFor(unit);
+                if (session[unit] + amt > sessionCap) {
+                    const remaining = Math.max(0, sessionCap - session[unit]);
+                    throw new SpendLimitError(this.message(unit, amt, remaining, "session", sessionCap), unit, amt, remaining, "session");
+                }
+                const daySpent = state[addr]?.[day]?.[unit] ?? 0;
+                if (daySpent + amt > daily) {
+                    const remaining = Math.max(0, daily - daySpent);
+                    throw new SpendLimitError(this.message(unit, amt, remaining, "day", daily), unit, amt, remaining, "day");
+                }
+            }
+            pruneOtherDays(state, day);
+            if (!state[addr])
+                state[addr] = {};
+            if (!state[addr][day])
+                state[addr][day] = { ustx: 0, sats: 0 };
+            for (const unit of ["ustx", "sats"]) {
+                state[addr][day][unit] += totals[unit];
+            }
+            await this.writeState(state);
+            session.ustx += totals.ustx;
+            session.sats += totals.sats;
+            return day;
+        }));
+        if (!run.held) {
+            throw new Error(`Spend refused: could not take the spending-limit lock, so the daily cap cannot be ` +
+                `checked safely: ${run.unavailable}`);
         }
+        return { addr, day: run.value, spends: booked };
     }
-    /** Record a completed spend against both the session and day ledgers. */
-    async record(unit, amount, addr) {
-        if (!isEnabled())
-            return;
-        if (amount <= 0n)
+    /**
+     * Give back a reservation whose spend never left this process (signing or
+     * broadcast failed, or a fallback path books its own). Without the lease
+     * the day ledger is left as is: an unlocked write could drop another
+     * process's booking, while skipping only over-counts.
+     *
+     * Idempotent: a reservation is given back at most once, so a caller that
+     * releases before a fallback and again when that fallback throws does not
+     * subtract twice.
+     *
+     * Never throws. Callers release on their way to rethrowing the real failure
+     * or into a fallback; a ledger write error here must not replace either.
+     * Failing to give budget back only over-counts.
+     */
+    async release(reservation) {
+        if (reservation.spends.length === 0)
             return;
-        const amt = Number(amount);
-        this.getSession(addr)[unit] += amt;
-        // Two locks, for two different races.
-        //
-        // The promise chain serializes concurrent record() calls INSIDE this
-        // process. The file lease excludes the OTHER process writing this file:
-        // the skills engine's direct x402 path shares spend-state.json so one
-        // wallet has one daily cap. Without the lease, its writes and ours
-        // overwrite each other and the day total under-counts, which is the
-        // direction that permits spending past the cap.
-        //
-        // Note the prune below walks EVERY address, so an unlocked concurrent
-        // write can lose another wallet's day too, not just this one's.
-        const write = this.writeLock.then(async () => {
-            const run = await withSharedStateLock(this.stateFile, async () => {
+        const { addr, day } = reservation;
+        const totals = { ustx: 0, sats: 0 };
+        for (const { unit, amount } of reservation.spends)
+            totals[unit] += amount;
+        reservation.spends = [];
+        let run;
+        try {
+            run = await this.serialized(() => withSharedStateLock(this.stateFile, async () => {
                 const state = await this.readState();
-                const today = todayKey();
-                // Prune stale days so the file does not grow unbounded.
-                for (const a of Object.keys(state)) {
-                    for (const day of Object.keys(state[a])) {
-                        if (day !== today)
-                            delete state[a][day];
-                    }
-                    if (Object.keys(state[a]).length === 0)
-                        delete state[a];
+                const ledger = state[addr]?.[day];
+                if (ledger) {
+                    ledger.ustx = Math.max(0, ledger.ustx - totals.ustx);
+                    ledger.sats = Math.max(0, ledger.sats - totals.sats);
+                    await this.writeState(state);
                 }
-                if (!state[addr])
-                    state[addr] = {};
-                if (!state[addr][today])
-                    state[addr][today] = { ustx: 0, sats: 0 };
-                state[addr][today][unit] += amt;
-                await this.writeState(state);
-            });
-            // The spend already happened on chain by the time record() is called, so
-            // an unavailable lease must not throw: that would turn a broadcast
-            // transaction into an unrecorded one. Write anyway and say so, because a
-            // silent under-count is the failure this whole lease exists to prevent.
-            if (!run.held) {
-                console.error(`[spend-limit] Recorded ${amt} ${unit} for ${addr} WITHOUT the shared lock: ` +
-                    `${run.unavailable} The daily total may under-count if another tool wrote ` +
-                    `concurrently.`);
-            }
-        });
-        // A failed write must not poison the chain for every later record().
-        this.writeLock = write.catch(() => { });
-        await write;
+                const session = this.getSession(addr);
+                session.ustx = Math.max(0, session.ustx - totals.ustx);
+                session.sats = Math.max(0, session.sats - totals.sats);
+            }));
+        }
+        catch (error) {
+            console.error(`[spend-limit] Could not release ${totals.ustx} uSTX / ${totals.sats} sats for ${addr}: ` +
+                `${error instanceof Error ? error.message : String(error)}. The day total stays ` +
+                `over-counted by that amount.`);
+            return;
+        }
+        if (!run.held) {
+            console.error(`[spend-limit] Could not release ${totals.ustx} uSTX / ${totals.sats} sats for ${addr}: ` +
+                `${run.unavailable} The day total stays over-counted by that amount.`);
+        }
+    }
+    /**
+     * Serialize ledger updates inside this process. The file lease excludes the
+     * OTHER process (the skills engine's direct x402 path shares
+     * spend-state.json so one wallet has one daily cap); this chain keeps two
+     * calls in this process from interleaving their read-modify-writes.
+     */
+    serialized(fn) {
+        const run = this.writeLock.then(fn);
+        // A failed update must not poison the chain for every later one.
+        this.writeLock = run.then(() => { }, () => { });
+        return run;
     }
     /** Remaining session/day budget for status reporting. */
     async status(addr) {

package/dist/services/state-lock.d.ts

@@ -23,11 +23,13 @@
  * though nothing here is x402: renaming it on this side would silently return
  * both tools to the race above while each believed it held a lock.
  *
- * A STALE LEASE IS NEVER RECLAIMED AUTOMATICALLY. Deleting a lock this process
- * did not create needs an atomic "remove only if unchanged since I looked",
- * which the filesystem does not offer; guessing wrong there is precisely the
- * concurrent write the lock exists to prevent. A dead holder is reported with
- * its pid and left for an operator, who can see whether it is really dead.
+ * A STALE LEASE IS RECLAIMED ONLY WHEN ITS HOLDER IS PROVABLY DEAD, by the
+ * same protocol the skills engine uses: a second mkdir lock (`<lock>.reclaim`)
+ * serializes the removal, and staleness and owner are re-read while holding
+ * it. A dead holder cannot release or heartbeat, so the lease inspected is the
+ * lease removed. Without this, one SIGKILLed holder would refuse every spend
+ * until an operator stepped in. A stale lease whose holder may still be alive
+ * is reported with its pid and left alone.
  */
 /** Mutable so tests do not have to wait real seconds. */
 declare const timing: {
@@ -47,26 +49,25 @@ export declare const _stateLockTesting: {
  * redirects the state file redirects the lock with it.
  */
 declare function lockDirFor(stateFile: string): string;
-export interface LockedRun<T> {
-    /** False when the body ran WITHOUT the lease. */
-    held: boolean;
-    /** Set when `held` is false: why the lease could not be taken. */
-    unavailable?: string;
+export type LockedRun<T> = {
+    held: true;
     value: T;
 }
+/** The lease could not be taken, so `fn` did NOT run. */
+ | {
+    held: false;
+    unavailable: string;
+};
 /**
- * Run `fn` under the shared lease for `stateFile`.
- *
- * `fn` RUNS EITHER WAY. This guards a read-modify-write that records something
- * which has ALREADY HAPPENED on chain, so refusing to run it would turn a
- * broadcast transaction into an unrecorded one — strictly worse than the race
- * it is trying to avoid. The caller is told which case it got and is expected
- * to say so loudly rather than let an under-count pass silently.
+ * Run `fn` under the shared lease for `stateFile`, or not at all.
  *
- * That is the deliberate difference from the skills engine, which takes this
- * same lease and DOES refuse: there the lock guards a payment not yet signed,
- * so refusing costs nothing but a retry. Authorising a future spend and
- * recording a past one fail in opposite directions.
+ * Every write to the spend ledger happens before the money moves: a
+ * reservation authorizes a spend not yet signed, and a release gives back one
+ * that never left. Neither is worth writing without the lease. A reservation
+ * that cannot take it is refused, which costs a retry; a release that cannot
+ * take it is skipped, which leaves the ledger over-counting. Both fail in the
+ * direction that keeps the cap. The skills engine refuses on the same lease
+ * for the same reason.
  */
 export declare function withSharedStateLock<T>(stateFile: string, fn: () => Promise<T>): Promise<LockedRun<T>>;
 export {};

package/dist/services/state-lock.js

@@ -23,15 +23,17 @@
  * though nothing here is x402: renaming it on this side would silently return
  * both tools to the race above while each believed it held a lock.
  *
- * A STALE LEASE IS NEVER RECLAIMED AUTOMATICALLY. Deleting a lock this process
- * did not create needs an atomic "remove only if unchanged since I looked",
- * which the filesystem does not offer; guessing wrong there is precisely the
- * concurrent write the lock exists to prevent. A dead holder is reported with
- * its pid and left for an operator, who can see whether it is really dead.
+ * A STALE LEASE IS RECLAIMED ONLY WHEN ITS HOLDER IS PROVABLY DEAD, by the
+ * same protocol the skills engine uses: a second mkdir lock (`<lock>.reclaim`)
+ * serializes the removal, and staleness and owner are re-read while holding
+ * it. A dead holder cannot release or heartbeat, so the lease inspected is the
+ * lease removed. Without this, one SIGKILLed holder would refuse every spend
+ * until an operator stepped in. A stale lease whose holder may still be alive
+ * is reported with its pid and left alone.
  */
 import os from "os";
 import path from "path";
-import { mkdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync, } from "fs";
+import { mkdirSync, readFileSync, rmdirSync, rmSync, statSync, utimesSync, writeFileSync, } from "fs";
 import { randomBytes } from "crypto";
 /** No heartbeat for this long means the holder is probably dead. */
 const LOCK_STALE_MS = 60_000;
@@ -116,6 +118,70 @@ function ownedBy(dir, token) {
         return false;
     }
 }
+/** "<pid> <token>" from the lease's owner file, or null if it cannot be read. */
+function readOwner(dir) {
+    try {
+        const match = /^(\d+) (\S+)$/.exec(readFileSync(path.join(dir, "owner"), "utf8"));
+        return match ? { pid: Number(match[1]), token: match[2] } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True only when the holder is provably not running on this host: the pid
+ * does not exist (ESRCH), or it is our own pid with a token this process does
+ * not hold (a previous incarnation, e.g. a restarted container reusing pid 1).
+ * EPERM and pid reuse by an unrelated process read as alive, which errs
+ * toward refusing.
+ */
+function holderIsDead(owner) {
+    if (owner.pid === process.pid) {
+        return ![...heldLocks.values()].includes(owner.token);
+    }
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/**
+ * Remove a stale lease whose holder is dead. Byte-compatible with
+ * `reclaimDeadLock` in the skills engine's x402-guards.ts. An ownerless lease
+ * (created, then the creator died before writing its owner) is reclaimable
+ * once stale, since a live creator writes the owner immediately.
+ */
+function reclaimDeadLock(dir) {
+    const reclaimDir = `${dir}.reclaim`;
+    try {
+        mkdirSync(reclaimDir);
+    }
+    catch {
+        return false; // another process is reclaiming; keep waiting
+    }
+    try {
+        if (!lockIsStale(dir))
+            return false;
+        const owner = readOwner(dir);
+        if (owner && !holderIsDead(owner))
+            return false;
+        rmSync(dir, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            rmdirSync(reclaimDir);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
 function describeHolder(dir) {
     try {
         const [pid] = readFileSync(path.join(dir, "owner"), "utf8").split(" ");
@@ -170,47 +236,63 @@ function installExitHooks() {
         });
     }
 }
+function reclaimInProgress(dir) {
+    try {
+        statSync(`${dir}.reclaim`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function acquire(dir, token) {
     const deadline = Date.now() + timing.maxWaitMs;
     for (;;) {
         if (tryLock(dir, token))
             return null;
         if (lockIsStale(dir)) {
-            return {
-                reason: `the lock at ${dir} has had no heartbeat for over ${Math.round(timing.staleMs / 1000)}s ` +
-                    `(${describeHolder(dir)}). If that process is dead, remove the directory; do not remove ` +
-                    `it while a write may still be in progress.`,
-            };
+            if (reclaimDeadLock(dir))
+                continue;
+            if (lockIsStale(`${dir}.reclaim`)) {
+                return {
+                    reason: `a lock reclaim at ${dir}.reclaim was interrupted over ` +
+                        `${Math.round(timing.staleMs / 1000)}s ago. Remove that directory (not the lock itself).`,
+                };
+            }
+            if (lockIsStale(dir) && !reclaimInProgress(dir)) {
+                return {
+                    reason: `the lock at ${dir} has had no heartbeat for over ${Math.round(timing.staleMs / 1000)}s ` +
+                        `(${describeHolder(dir)}) and its holder may still be running. If that process is ` +
+                        `dead, remove the directory; do not remove it while a write may still be in progress.`,
+                };
+            }
         }
         if (Date.now() >= deadline) {
             return {
                 reason: `another writer held the lock at ${dir} for the whole ` +
-                    `${Math.round(timing.maxWaitMs / 1000)}s wait (${describeHolder(dir)}).`,
+                    `${Math.round(timing.maxWaitMs / 1000)}s wait (${describeHolder(dir)}). Retry once it finishes.`,
             };
         }
         await new Promise((r) => setTimeout(r, timing.retryMs));
     }
 }
 /**
- * Run `fn` under the shared lease for `stateFile`.
- *
- * `fn` RUNS EITHER WAY. This guards a read-modify-write that records something
- * which has ALREADY HAPPENED on chain, so refusing to run it would turn a
- * broadcast transaction into an unrecorded one — strictly worse than the race
- * it is trying to avoid. The caller is told which case it got and is expected
- * to say so loudly rather than let an under-count pass silently.
+ * Run `fn` under the shared lease for `stateFile`, or not at all.
  *
- * That is the deliberate difference from the skills engine, which takes this
- * same lease and DOES refuse: there the lock guards a payment not yet signed,
- * so refusing costs nothing but a retry. Authorising a future spend and
- * recording a past one fail in opposite directions.
+ * Every write to the spend ledger happens before the money moves: a
+ * reservation authorizes a spend not yet signed, and a release gives back one
+ * that never left. Neither is worth writing without the lease. A reservation
+ * that cannot take it is refused, which costs a retry; a release that cannot
+ * take it is skipped, which leaves the ledger over-counting. Both fail in the
+ * direction that keeps the cap. The skills engine refuses on the same lease
+ * for the same reason.
  */
 export async function withSharedStateLock(stateFile, fn) {
     const dir = lockDirFor(stateFile);
     const token = randomBytes(12).toString("hex");
     const unavailable = await acquire(dir, token);
     if (unavailable) {
-        return { held: false, unavailable: unavailable.reason, value: await fn() };
+        return { held: false, unavailable: unavailable.reason };
     }
     installExitHooks();
     heldLocks.set(dir, token);