@aibtc/mcp-server 1.69.0 → 1.70.1

package/dist/services/at-stake.service.js

@@ -0,0 +1,272 @@
+/**
+ * Chain reads for the At Stake market and its two side legions.
+ *
+ * Every read here goes to the chain the contracts live on, not the chain the
+ * server is configured for — see the note in `config/at-stake.ts`.
+ *
+ * Clarity values come back through `cvToJSON`, whose shape is nested and
+ * stringly typed. The unwrapping lives here so the tool layer reads as the
+ * market's own vocabulary rather than as tuple spelunking.
+ */
+import { cvToJSON, deserializeCV, getAddressFromPrivateKey, principalCV, uintCV, } from "@stacks/transactions";
+import { getHiroApi } from "./hiro-api.js";
+import { getAccount } from "./x402.service.js";
+import { AT_STAKE_NETWORK, CLOSE_HEIGHT, LEGION_ERRORS, MARKET_ADDRESS, MARKET_CONTRACT, MARKET_ERRORS, MARKET_STATUS, PROPOSAL_STATUS, STATUS_OPEN, } from "../config/at-stake.js";
+/**
+ * The wallet, re-derived for the legion's chain.
+ *
+ * A testnet-configured server still holds the same private key; only the
+ * c32 encoding of the address differs. Re-deriving means a mainnet call is
+ * signed by the mainnet form of the same wallet rather than failing, or worse,
+ * quoting one address while signing as another.
+ */
+export async function getAtStakeAccount() {
+    const base = await getAccount();
+    if (base.network === AT_STAKE_NETWORK)
+        return base;
+    return {
+        ...base,
+        address: getAddressFromPrivateKey(base.privateKey, AT_STAKE_NETWORK),
+        network: AT_STAKE_NETWORK,
+    };
+}
+/** Call a read-only function on either contract and return its JSON form. */
+export async function readContract(contractId, functionName, args = []) {
+    const hiro = getHiroApi(AT_STAKE_NETWORK);
+    const result = await hiro.callReadOnlyFunction(contractId, functionName, args, MARKET_ADDRESS);
+    if (!result.okay) {
+        throw new Error(`${contractId} ${functionName} failed: ${result.cause ?? "unknown error"}`);
+    }
+    if (!result.result)
+        return null;
+    const hex = result.result.startsWith("0x")
+        ? result.result.slice(2)
+        : result.result;
+    return cvToJSON(deserializeCV(Buffer.from(hex, "hex")));
+}
+/** Read a market function. */
+export function readMarket(functionName, args = []) {
+    return readContract(MARKET_CONTRACT, functionName, args);
+}
+/**
+ * Flatten one layer of `cvToJSON`'s `{type, value}` nesting.
+ *
+ * A Clarity tuple arrives as `{type, value: {field: {type, value}}}`, and an
+ * optional wraps that again. Callers want the field, not the envelope.
+ */
+function unwrap(cv) {
+    if (cv && typeof cv === "object" && "value" in cv) {
+        return cv.value;
+    }
+    return cv;
+}
+/** Read a uint out of a `cvToJSON` node. */
+export function num(cv) {
+    const v = unwrap(cv);
+    if (v === null || v === undefined)
+        return 0;
+    return Number(v);
+}
+/** Read a bool out of a `cvToJSON` node. */
+function bool(cv) {
+    return unwrap(cv) === true || unwrap(cv) === "true";
+}
+/** Read a string out of a `cvToJSON` node. */
+function str(cv) {
+    const v = unwrap(cv);
+    return v === null || v === undefined ? "" : String(v);
+}
+/** Fields of a tuple node, or `null` for a `none`. */
+function fields(cv) {
+    const v = unwrap(cv);
+    if (v === null || v === undefined)
+        return null;
+    // An optional's payload is itself a {type, value} node.
+    if (typeof v === "object" && "value" in v && "type" in v) {
+        return fields(v);
+    }
+    return v;
+}
+export async function getMarket() {
+    const f = fields(await readMarket("get-market"));
+    if (!f)
+        throw new Error("get-market returned nothing.");
+    const status = num(f["status"]);
+    return {
+        title: str(f["title"]),
+        opened: bool(f["opened"]),
+        status,
+        statusLabel: MARKET_STATUS[status] ?? `unknown(${status})`,
+        closeHeight: num(f["close-height"]),
+        vault: num(f["vault"]),
+        idleCirc: num(f["idle-circ"]),
+        bondedCirc: num(f["bonded-circ"]),
+        createdAt: num(f["created-at"]),
+    };
+}
+export async function getPosition(who) {
+    const f = fields(await readMarket("get-position", [principal(who)]));
+    if (!f)
+        return { idle: 0, bonded: 0 };
+    return { idle: num(f["idle"]), bonded: num(f["bonded"]) };
+}
+export async function getBid(who, side) {
+    const f = fields(await readMarket("get-bid", [principal(who), uint(side.side)]));
+    if (!f)
+        return null;
+    return { amount: num(f["amount"]), escrow: num(f["escrow"]) };
+}
+/** Current burn height — the clock every window in both contracts uses. */
+export async function getBurnHeight() {
+    const info = await getHiroApi(AT_STAKE_NETWORK).getCoreApiInfo();
+    return info.burn_block_height;
+}
+/**
+ * Whether the market still accepts trades.
+ *
+ * Mirrors the contract's own `assert-tradeable`: open status AND the close
+ * height not yet passed. Derived rather than read so a caller can be told
+ * which of the two conditions failed.
+ */
+export function isTradeable(market, burnHeight) {
+    return market.status === STATUS_OPEN && burnHeight <= CLOSE_HEIGHT;
+}
+export async function getLegionParams(side) {
+    const f = fields(await readContract(side.legion, "get-params"));
+    if (!f)
+        throw new Error(`${side.legion} get-params returned nothing.`);
+    return {
+        minPosition: num(f["minPosition"]),
+        payout: num(f["payout"]),
+        minVoters: num(f["minVoters"]),
+        proposerCooldown: num(f["proposerCooldown"]),
+        votingThreshold: num(f["votingThreshold"]),
+        voteDelay: num(f["voteDelay"]),
+        voteWindow: num(f["voteWindow"]),
+        concludeWindow: num(f["concludeWindow"]),
+        globalProposeInterval: num(f["globalProposeInterval"]),
+    };
+}
+export async function getProposeStatus(side, who) {
+    const f = fields(await readContract(side.legion, "propose-status", [principal(who)]));
+    if (!f)
+        throw new Error(`${side.legion} propose-status returned nothing.`);
+    return {
+        canPropose: bool(f["canPropose"]),
+        eligible: bool(f["eligible"]),
+        slotOpen: bool(f["slotOpen"]),
+        cooledDown: bool(f["cooledDown"]),
+        noLiveProposal: bool(f["noLiveProposal"]),
+        potOk: bool(f["potOk"]),
+        marketTradeable: bool(f["marketTradeable"]),
+        weight: num(f["weight"]),
+        vault: num(f["vault"]),
+        winsLeft: num(f["winsLeft"]),
+        payout: num(f["payout"]),
+        votable: num(f["votable"]),
+        nextProposeHeight: num(f["nextProposeHeight"]),
+        proposerNextHeight: num(f["proposerNextHeight"]),
+    };
+}
+export async function getProposal(side, proposalId) {
+    const f = fields(await readContract(side.legion, "get-proposal", [uint(proposalId)]));
+    if (!f)
+        return null;
+    const status = num(f["status"]);
+    return {
+        proposer: str(f["proposer"]),
+        payout: num(f["payout"]),
+        createdAt: num(f["createdAt"]),
+        voteEnd: num(f["voteEnd"]),
+        votableAtOpen: num(f["votableAtOpen"]),
+        yesWeight: num(f["yesWeight"]),
+        noWeight: num(f["noWeight"]),
+        voterCount: num(f["voterCount"]),
+        yesVoterCount: num(f["yesVoterCount"]),
+        status,
+        statusLabel: PROPOSAL_STATUS[status] ?? `unknown(${status})`,
+        reason: str(f["reason"]),
+        paidInShares: bool(f["paidInShares"]),
+    };
+}
+export async function getProposalMeta(side, proposalId) {
+    const f = fields(await readContract(side.legion, "get-proposal-meta", [uint(proposalId)]));
+    if (!f)
+        return null;
+    return {
+        title: str(f["title"]),
+        description: str(f["description"]),
+        link: str(f["link"]),
+    };
+}
+/** The contract's own phase word for a proposal. */
+export async function getPhase(side, proposalId) {
+    return str(await readContract(side.legion, "get-phase", [uint(proposalId)]));
+}
+export async function getSettlement(side) {
+    const f = fields(await readContract(side.legion, "get-settlement"));
+    if (!f)
+        throw new Error(`${side.legion} get-settlement returned nothing.`);
+    return {
+        redeemed: bool(f["redeemed"]),
+        redeemedSats: num(f["redeemedSats"]),
+        paidSats: num(f["paidSats"]),
+        unpaidSats: num(f["unpaidSats"]),
+        totalCredits: num(f["totalCredits"]),
+        won: bool(f["won"]),
+    };
+}
+/**
+ * Predict what `conclude` will decide, in the contract's own decision order.
+ *
+ * The chain decides for real at the block that mines the transaction; this is
+ * the tally as of now, so a caller can see that they are about to burn gas on
+ * a proposal that fails for want of one more voter.
+ */
+export function predictOutcome(proposal, params, proposerStillHolding, vault, totalCredits, tradeable) {
+    const cast = proposal.yesWeight + proposal.noWeight;
+    if (proposal.yesVoterCount < params.minVoters) {
+        return { outcome: "failed", reason: "no-voters", payout: 0 };
+    }
+    if (cast === 0 || (proposal.yesWeight * 100) / cast < params.votingThreshold) {
+        return { outcome: "failed", reason: "voted-down", payout: 0 };
+    }
+    if (!proposerStillHolding) {
+        return { outcome: "failed", reason: "not-holding", payout: 0 };
+    }
+    if (vault < totalCredits + params.payout) {
+        return { outcome: "failed", reason: "pot-short", payout: 0 };
+    }
+    return {
+        outcome: "passed",
+        reason: tradeable ? "paid-shares" : "credited",
+        payout: params.payout,
+    };
+}
+// ---------------------------------------------------------------------------
+// Clarity argument helpers and error translation
+// ---------------------------------------------------------------------------
+function principal(address) {
+    return principalCV(address);
+}
+function uint(value) {
+    return uintCV(value);
+}
+/**
+ * Turn a contract abort into the sentence behind its code.
+ *
+ * The two contracts use disjoint ranges — the market is 100-313, the legions
+ * 401-450 — so one lookup across both tables cannot collide.
+ */
+export function explainAbort(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = message.match(/\bu(\d+)\b/);
+    if (!match)
+        return error instanceof Error ? error : new Error(message);
+    const code = Number(match[1]);
+    const explanation = MARKET_ERRORS[code] ?? LEGION_ERRORS[code];
+    if (!explanation)
+        return error instanceof Error ? error : new Error(message);
+    return new Error(`${explanation} (u${code})\n\nRaw: ${message}`);
+}
+//# sourceMappingURL=at-stake.service.js.map

package/dist/services/spend-limiter.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "fs";
 import os from "os";
 import path from "path";
+import { withSharedStateLock } from "./state-lock.js";
 import { MAINNET_CONTRACTS, TESTNET_CONTRACTS } from "../config/contracts.js";
 /** Asset ids this rail can meter. Any other FT has no ledger to bill. */
 const SBTC_ASSETS = new Set([
@@ -195,27 +196,50 @@ class SpendLimiter {
             return;
         const amt = Number(amount);
         this.getSession(addr)[unit] += amt;
-        // Serialize read-modify-write to avoid lost updates under concurrency.
-        this.writeLock = this.writeLock.then(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];
+        // 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 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];
                 }
-                if (Object.keys(state[a]).length === 0)
-                    delete state[a];
+                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.`);
             }
-            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);
         });
-        await this.writeLock;
+        // A failed write must not poison the chain for every later record().
+        this.writeLock = write.catch(() => { });
+        await write;
     }
     /** Remaining session/day budget for status reporting. */
     async status(addr) {

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

@@ -0,0 +1,73 @@
+/**
+ * Cross-process lock for the shared `~/.aibtc` state files.
+ *
+ * `spend-state.json` has TWO writers: this server, and the aibtc skills engine's
+ * direct x402 payment path (aibtcdev/skills#423), which reads and writes the
+ * same file in the same shape so one wallet has one daily cap no matter which
+ * tool spends from it. Sharing the file is the point; sharing it without a lock
+ * is a lost update:
+ *
+ *   1. this server reads the day total and sees 100
+ *   2. the other tool takes its lock, reads 100, writes 150, releases
+ *   3. this server writes 130 from the copy it read in step 1
+ *
+ * The other tool's 50 is gone and the daily cap now UNDER-counts, which is the
+ * direction that lets a wallet spend past the cap it was supposed to share. An
+ * in-process promise chain cannot fix this: the other writer is another process.
+ *
+ * THE PROTOCOL HERE IS NOT OURS TO CHANGE UNILATERALLY. It is byte-compatible
+ * with `x402-guards.ts` in the skills engine so the two tools' leases are
+ * interchangeable — same lock directory name, same `owner` file format, same
+ * mtime heartbeat, same staleness window. A lock only excludes writers that
+ * agree on where it lives, so "x402-guards.lock" is deliberately kept even
+ * 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.
+ */
+/** Mutable so tests do not have to wait real seconds. */
+declare const timing: {
+    maxWaitMs: number;
+    staleMs: number;
+    heartbeatMs: number;
+    retryMs: number;
+};
+/** Test seam. Not part of the public contract. */
+export declare const _stateLockTesting: {
+    set(overrides: Partial<typeof timing>): void;
+    reset(): void;
+    lockDirFor: typeof lockDirFor;
+};
+/**
+ * The lease guarding a state file, derived from its directory so a test that
+ * 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;
+    value: T;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function withSharedStateLock<T>(stateFile: string, fn: () => Promise<T>): Promise<LockedRun<T>>;
+export {};
+//# sourceMappingURL=state-lock.d.ts.map

package/dist/services/state-lock.js

@@ -0,0 +1,229 @@
+/**
+ * Cross-process lock for the shared `~/.aibtc` state files.
+ *
+ * `spend-state.json` has TWO writers: this server, and the aibtc skills engine's
+ * direct x402 payment path (aibtcdev/skills#423), which reads and writes the
+ * same file in the same shape so one wallet has one daily cap no matter which
+ * tool spends from it. Sharing the file is the point; sharing it without a lock
+ * is a lost update:
+ *
+ *   1. this server reads the day total and sees 100
+ *   2. the other tool takes its lock, reads 100, writes 150, releases
+ *   3. this server writes 130 from the copy it read in step 1
+ *
+ * The other tool's 50 is gone and the daily cap now UNDER-counts, which is the
+ * direction that lets a wallet spend past the cap it was supposed to share. An
+ * in-process promise chain cannot fix this: the other writer is another process.
+ *
+ * THE PROTOCOL HERE IS NOT OURS TO CHANGE UNILATERALLY. It is byte-compatible
+ * with `x402-guards.ts` in the skills engine so the two tools' leases are
+ * interchangeable — same lock directory name, same `owner` file format, same
+ * mtime heartbeat, same staleness window. A lock only excludes writers that
+ * agree on where it lives, so "x402-guards.lock" is deliberately kept even
+ * 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.
+ */
+import os from "os";
+import path from "path";
+import { mkdirSync, readFileSync, 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;
+/** A live holder refreshes its lease this often. */
+const LOCK_HEARTBEAT_MS = 10_000;
+/** Gap between acquisition attempts. */
+const LOCK_RETRY_MS = 250;
+/** Mutable so tests do not have to wait real seconds. */
+const timing = {
+    maxWaitMs: 15_000,
+    staleMs: LOCK_STALE_MS,
+    heartbeatMs: LOCK_HEARTBEAT_MS,
+    retryMs: LOCK_RETRY_MS,
+};
+/** Test seam. Not part of the public contract. */
+export const _stateLockTesting = {
+    set(overrides) {
+        Object.assign(timing, overrides);
+    },
+    reset() {
+        timing.maxWaitMs = 15_000;
+        timing.staleMs = LOCK_STALE_MS;
+        timing.heartbeatMs = LOCK_HEARTBEAT_MS;
+        timing.retryMs = LOCK_RETRY_MS;
+    },
+    lockDirFor,
+};
+/**
+ * The lease guarding a state file, derived from its directory so a test that
+ * redirects the state file redirects the lock with it.
+ */
+function lockDirFor(stateFile) {
+    return path.join(path.dirname(stateFile), "x402-guards.lock");
+}
+function tryLock(dir, token) {
+    try {
+        mkdirSync(path.dirname(dir), { recursive: true, mode: 0o700 });
+        // mkdir of an existing directory throws: that is the atomic test-and-set.
+        mkdirSync(dir);
+    }
+    catch {
+        return false;
+    }
+    try {
+        writeFileSync(path.join(dir, "owner"), `${process.pid} ${token}`, {
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        // We created the directory but could not claim it. Remove it rather than
+        // strand an ownerless lease that every writer would wait on.
+        rmSync(dir, { recursive: true, force: true });
+        return false;
+    }
+}
+function lockIsStale(dir) {
+    try {
+        return Date.now() - statSync(dir).mtimeMs > timing.staleMs;
+    }
+    catch {
+        // Gone between the failed mkdir and this stat: not stale, just released.
+        return false;
+    }
+}
+/** Touch the lease so a slow-but-live holder is never mistaken for a dead one. */
+function heartbeat(dir) {
+    try {
+        const now = new Date();
+        utimesSync(dir, now, now);
+    }
+    catch {
+        // If the directory is gone we no longer hold it; the owner check on
+        // release handles that case.
+    }
+}
+function ownedBy(dir, token) {
+    try {
+        return readFileSync(path.join(dir, "owner"), "utf8").endsWith(` ${token}`);
+    }
+    catch {
+        return false;
+    }
+}
+function describeHolder(dir) {
+    try {
+        const [pid] = readFileSync(path.join(dir, "owner"), "utf8").split(" ");
+        let alive = true;
+        try {
+            process.kill(Number(pid), 0);
+        }
+        catch {
+            alive = false;
+        }
+        return `owner pid ${pid}${alive ? "" : " (not running)"}`;
+    }
+    catch {
+        return "owner unknown";
+    }
+}
+/**
+ * Release a lease this process created. The owner check guards the one way the
+ * directory could be someone else's by now: an operator removed our lock by
+ * hand and another writer took the path meanwhile.
+ */
+function release(dir, token) {
+    try {
+        if (ownedBy(dir, token))
+            rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Already gone; nothing to release.
+    }
+}
+/** Leases held right now, so a signal can drop them instead of stranding them. */
+const heldLocks = new Map();
+let exitHooksInstalled = false;
+function installExitHooks() {
+    if (exitHooksInstalled)
+        return;
+    exitHooksInstalled = true;
+    const releaseAll = () => {
+        for (const [dir, token] of heldLocks)
+            release(dir, token);
+        heldLocks.clear();
+    };
+    process.once("exit", releaseAll);
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.once(signal, () => {
+            releaseAll();
+            // Leave shutdown to any other handler (e.g. yield-hunter's graceful
+            // stop); only exit ourselves when we displaced the default behaviour.
+            if (process.listenerCount(signal) === 0) {
+                process.exit(128 + os.constants.signals[signal]);
+            }
+        });
+    }
+}
+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 (Date.now() >= deadline) {
+            return {
+                reason: `another writer held the lock at ${dir} for the whole ` +
+                    `${Math.round(timing.maxWaitMs / 1000)}s wait (${describeHolder(dir)}).`,
+            };
+        }
+        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.
+ *
+ * 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.
+ */
+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() };
+    }
+    installExitHooks();
+    heldLocks.set(dir, token);
+    const beat = setInterval(() => heartbeat(dir), timing.heartbeatMs);
+    // Never keep the process alive for a heartbeat.
+    beat.unref?.();
+    try {
+        return { held: true, value: await fn() };
+    }
+    finally {
+        clearInterval(beat);
+        heldLocks.delete(dir);
+        release(dir, token);
+    }
+}
+//# sourceMappingURL=state-lock.js.map

package/dist/tools/at-stake-legion.tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * At Stake legion tools — the two side DAOs at aibtc.com/legions.
+ *
+ * Each side of the El Salvador market has a legion, and VOTING WEIGHT IS THE
+ * SHARE BALANCE, read live out of the market at the moment of every call. So a
+ * legion's electorate is exactly the set of people exposed to the claim it
+ * argues: the yes legion is bonded holders, the no legion is idle holders. You
+ * join by minting shares, not by registering.
+ *
+ * Lifecycle: propose → (2-block delay) → vote for 30 blocks → conclude inside a
+ * 12-block window. A proposal nobody concludes in that window EXPIRES and pays
+ * nobody, permanently. There is no veto: voting no while the window is open is
+ * the only way to stop a proposal.
+ *
+ * A passing proposal pays 3,000 shares of its own side out of the legion vault
+ * while the market still trades. Once the market resolves the vault can no
+ * longer move shares, so a pass becomes an sBTC CREDIT instead, claimable after
+ * someone calls `atstake_legion_redeem_vault`.
+ *
+ * Weight is liquid and cannot be locked, so `conclude` re-reads the proposer's
+ * balance: buy in, propose, sell, get paid does not work — it settles
+ * "not-holding" and pays nothing.
+ *
+ * NOT THE SAME TOOLS AS `legion_*`. Those govern `aibtc-news-gov`, where weight
+ * is bought with sBTC contributions and a proposal names a Bitcoin ordinal.
+ * These govern the El Salvador market's two sides. Same word, different
+ * contracts, different way of getting a vote.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAtStakeLegionTools(server: McpServer): void;
+//# sourceMappingURL=at-stake-legion.tools.d.ts.map