aipou-mcp-server 0.4.0 → 0.6.0

package/dist/receipt-verifier.js

@@ -0,0 +1,125 @@
+import { canonicalJson, sha256Hex } from "./canonical.js";
+import { receiptEvidenceReport } from "./evidence.js";
+import { verifyCollectorPayload } from "./collector.js";
+import { verifyTaskAuthorization } from "./identity.js";
+function isBytes32(value) {
+    return typeof value === "string" && /^0x[0-9a-f]{64}$/i.test(value);
+}
+function assertReceiptShape(receipt) {
+    const errors = [];
+    const fields = new Set(["receiptId", "nonce", "wallet", "provider", "model", "inputTokens", "outputTokens", "durationSeconds", "taskHash", "outputHash", "client", "trustTier", "walletAuthorization", "authorizationIssuedAt", "authorizationChainId", "authorizationContract", "providerEvidence", "collectorPublicKey", "collectorSignature", "recordedAt", "estimatedReward", "batchRoot", "claimTransaction", "tokenUsageMeasurement"]);
+    if (Object.keys(receipt).some(key => !fields.has(key)))
+        return ["receipt contains unsupported fields"];
+    for (const [key, value] of Object.entries(receipt)) {
+        if (key === "providerEvidence") {
+            if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(k => !["keyId", "signature"].includes(k)) || typeof value.keyId !== "string" || typeof value.signature !== "string" || value.keyId.length > 128 || value.signature.length > 2048))
+                return ["providerEvidence must contain bounded keyId and signature strings"];
+        }
+        else if (value !== undefined && typeof value !== "string" && typeof value !== "number")
+            return ["receipt fields must be scalar values"];
+        if (typeof value === "string" && value.length > 8192)
+            return ["receipt field exceeds length limit"];
+    }
+    for (const field of ["receiptId", "nonce", "taskHash", "outputHash"]) {
+        if (!isBytes32(receipt[field]))
+            errors.push(`${field} must be a bytes32 hex value`);
+    }
+    if (typeof receipt.walletAuthorization !== "string" || !/^0x[0-9a-f]+$/i.test(receipt.walletAuthorization)) {
+        errors.push("walletAuthorization must be a hex EIP-712 signature");
+    }
+    if (typeof receipt.wallet !== "string" || !/^0x[0-9a-f]{40}$/i.test(receipt.wallet))
+        errors.push("wallet must be an address");
+    if (typeof receipt.authorizationContract !== "string" || !/^0x[0-9a-f]{40}$/i.test(receipt.authorizationContract)) {
+        errors.push("authorizationContract must be an address");
+    }
+    for (const field of ["provider", "model", "client", "collectorPublicKey", "collectorSignature", "recordedAt", "estimatedReward"]) {
+        if (typeof receipt[field] !== "string" || receipt[field].length === 0)
+            errors.push(`${field} must be a non-empty string`);
+    }
+    for (const field of ["inputTokens", "outputTokens", "durationSeconds", "authorizationIssuedAt", "authorizationChainId"]) {
+        if (!Number.isSafeInteger(receipt[field]) || Number(receipt[field]) < 0)
+            errors.push(`${field} must be a non-negative safe integer`);
+    }
+    if (receipt.trustTier !== "client_signed" && receipt.trustTier !== "provider_signed")
+        errors.push("trustTier is unsupported");
+    if (receipt.tokenUsageMeasurement !== undefined && !["measured", "unmeasured", "unspecified"].includes(receipt.tokenUsageMeasurement))
+        errors.push("tokenUsageMeasurement is unsupported");
+    if (receipt.tokenUsageMeasurement === "unmeasured" && (receipt.inputTokens !== 0 || receipt.outputTokens !== 0))
+        errors.push("unmeasured token usage must have zero counts");
+    if (Number.isNaN(Date.parse(String(receipt.recordedAt))))
+        errors.push("recordedAt must be an ISO date");
+    return errors;
+}
+/**
+ * Verifies only the self-contained receipt facts. It does not check a
+ * collector allowlist, an on-chain claim, delivery, or business acceptance.
+ */
+export function verifyAipouReceipt(candidate) {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+        return {
+            valid: false,
+            errors: ["receipt must be an object"],
+            workReceiptId: null,
+            claimedWorkReceiptId: null,
+            evidence: receiptEvidenceReport({ receiptIntegrity: false, walletAuthorization: false, collectorSignature: false })
+        };
+    }
+    const receipt = candidate;
+    const errors = assertReceiptShape(receipt);
+    if (errors.length > 0) {
+        return {
+            valid: false,
+            errors,
+            workReceiptId: null,
+            claimedWorkReceiptId: isBytes32(receipt.receiptId) ? receipt.receiptId.toLowerCase() : null,
+            evidence: receiptEvidenceReport({ receiptIntegrity: false, walletAuthorization: false, collectorSignature: false })
+        };
+    }
+    const { receiptId, collectorSignature: signature, batchRoot: _batchRoot, claimTransaction: _claimTransaction, ...unsigned } = receipt;
+    const receiptIntegrity = sha256Hex(canonicalJson(unsigned)).toLowerCase() === receiptId.toLowerCase();
+    if (!receiptIntegrity)
+        errors.push("receiptId does not match canonical unsigned receipt payload");
+    let collectorSignatureValid = false;
+    try {
+        collectorSignatureValid = verifyCollectorPayload({ receiptId, ...unsigned }, signature, receipt.collectorPublicKey);
+    }
+    catch {
+        collectorSignatureValid = false;
+    }
+    if (!collectorSignatureValid)
+        errors.push("collector signature is invalid");
+    const session = {
+        nonce: receipt.nonce,
+        wallet: receipt.wallet,
+        provider: receipt.provider,
+        model: receipt.model,
+        taskHash: receipt.taskHash,
+        client: receipt.client,
+        issuedAt: receipt.authorizationIssuedAt,
+        chainId: receipt.authorizationChainId,
+        verifyingContract: receipt.authorizationContract,
+        walletAuthorization: receipt.walletAuthorization,
+        completedAt: receipt.recordedAt
+    };
+    let walletAuthorization = false;
+    try {
+        walletAuthorization = verifyTaskAuthorization(session);
+    }
+    catch {
+        walletAuthorization = false;
+    }
+    if (!walletAuthorization)
+        errors.push("wallet authorization is invalid");
+    return {
+        valid: errors.length === 0,
+        errors,
+        workReceiptId: errors.length === 0 ? receiptId.toLowerCase() : null,
+        claimedWorkReceiptId: errors.length === 0 ? null : receiptId.toLowerCase(),
+        evidence: receiptEvidenceReport({
+            receiptIntegrity,
+            walletAuthorization,
+            collectorSignature: collectorSignatureValid,
+            hostExecution: receiptIntegrity && collectorSignatureValid ? "OBSERVED" : "UNKNOWN"
+        })
+    };
+}

package/dist/receipt-verifier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/receipt-verifier.test.js

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { Wallet, keccak256, toUtf8Bytes } from "ethers";
+import { beginTask, completeTask } from "./receipts.js";
+import { verifyAipouReceipt } from "./receipt-verifier.js";
+test("independent receipt verifier separates cryptographic receipt facts from outcome claims", async () => {
+    process.env.AIPOU_DATA_DIR = await mkdtemp(path.join(tmpdir(), "aipou-verifier-"));
+    process.env.AIPOU_AGENT_PRIVATE_KEY = Wallet.createRandom().privateKey;
+    const session = await beginTask({
+        provider: "local",
+        model: "verifier-test",
+        client: "test-client",
+        taskHash: keccak256(toUtf8Bytes("verify this receipt")),
+        chainId: 8453,
+        verifyingContract: Wallet.createRandom().address
+    });
+    const receipt = await completeTask({
+        nonce: session.nonce,
+        inputTokens: 100,
+        outputTokens: 20,
+        durationSeconds: 2,
+        outputHash: keccak256(toUtf8Bytes("verifier output"))
+    });
+    const verified = verifyAipouReceipt(receipt);
+    assert.equal(verified.valid, true);
+    assert.equal(verified.workReceiptId, receipt.receiptId);
+    assert.equal(verified.claimedWorkReceiptId, null);
+    assert.deepEqual(verified.evidence, {
+        receiptIntegrity: "VERIFIED",
+        walletAuthorization: "VERIFIED",
+        collectorSignature: "VERIFIED",
+        hostExecution: "OBSERVED",
+        delivery: "UNKNOWN",
+        businessAcceptance: "ABSENT",
+        settlement: "ABSENT",
+        externalEffect: "UNKNOWN"
+    });
+    const tampered = verifyAipouReceipt({ ...receipt, outputHash: `0x${"ef".repeat(32)}` });
+    assert.equal(tampered.valid, false);
+    assert.equal(tampered.workReceiptId, null);
+    assert.equal(tampered.claimedWorkReceiptId, receipt.receiptId);
+    assert.ok(tampered.errors.some((error) => /receiptId/.test(error)));
+    assert.ok(tampered.errors.some((error) => /collector signature/.test(error)));
+});
+test("malformed, deeply nested and oversized receipts fail closed without crypto work", () => {
+    for (const candidate of [null, [], { receiptId: `0x${"ab".repeat(32)}`, rawPrompt: "private" }, { collectorPublicKey: "x".repeat(9000) }, { providerEvidence: { keyId: "x", signature: {} } }]) {
+        const result = verifyAipouReceipt(candidate);
+        assert.equal(result.valid, false);
+        assert.equal(result.workReceiptId, null);
+    }
+});

package/dist/receipts.js

@@ -1,6 +1,6 @@
 import { canonicalJson, sha256Hex } from "./canonical.js";
 import { getCollectorPublicKey, signCollectorPayload } from "./collector.js";
-import { createTaskSession, verifyTaskAuthorization } from "./identity.js";
+import { createTaskSession, isTaskSessionExpired, verifyTaskAuthorization } from "./identity.js";
 import { deriveTrustTier } from "./providers.js";
 import { estimateReward } from "./rewards.js";
 import { exportStoredReceipts, getSession, saveCompletedReceipt, saveSession } from "./store.js";
@@ -14,13 +14,22 @@ export async function completeTask(input) {
     if (!session)
         throw new Error("Unknown task nonce");
     if (session.completedAt)
-        throw new Error("Task nonce has already been completed");
+        throw new Error("Task nonce has already been completed; use export_ai_receipts and find this nonce to recover its stored receipt. Do not rerun the work or begin a new task to recover a lost response.");
+    if (isTaskSessionExpired(session))
+        throw new Error("Task session has expired; begin a new task instead of completing stale authority");
     if (!verifyTaskAuthorization(session))
         throw new Error("Invalid EIP-712 wallet authorization");
+    if (input.tokenUsageMeasurement !== undefined && !["measured", "unmeasured", "unspecified"].includes(input.tokenUsageMeasurement)) {
+        throw new Error("Unsupported tokenUsageMeasurement");
+    }
+    if (input.tokenUsageMeasurement === "unmeasured" && (input.inputTokens !== 0 || input.outputTokens !== 0)) {
+        throw new Error("Unmeasured token usage must use zero counts");
+    }
     const trustTier = await deriveTrustTier(session, input, input.providerEvidence);
     const recordedAt = new Date().toISOString();
     const collectorPublicKey = await getCollectorPublicKey();
     const unsigned = {
+        tokenUsageMeasurement: input.tokenUsageMeasurement ?? "unspecified",
         nonce: session.nonce,
         wallet: session.wallet,
         provider: session.provider,

package/dist/settlement-driver.d.ts

@@ -0,0 +1,3 @@
+import { Wallet } from "ethers";
+import type { SettlementDriver } from "./settlement-runner.js";
+export declare function createSettlementDriver(signer: Wallet, contract: string): SettlementDriver;

package/dist/settlement-driver.js

@@ -0,0 +1,120 @@
+import { Contract, Transaction } from "ethers";
+const abi = [
+    "function approvedRoots(bytes32) view returns(bool)",
+    "function claimedReceipts(bytes32) view returns(bool)",
+    "function publishRoot(bytes32)",
+    "function claimBatch(bytes32,address[],uint256[],bytes32[],bytes32[][])",
+];
+export function createSettlementDriver(signer, contract) {
+    const provider = signer.provider;
+    const claims = new Contract(contract, abi, signer);
+    const data = (kind, plan) => kind === "publish"
+        ? claims.interface.encodeFunctionData("publishRoot", [plan.root])
+        : claims.interface.encodeFunctionData("claimBatch", [
+            plan.root,
+            plan.accounts,
+            plan.amounts,
+            plan.receiptIds,
+            plan.proofs,
+        ]);
+    const fees = async () => {
+        const fee = await provider.getFeeData();
+        const gasPrice = fee.maxFeePerGas ?? fee.gasPrice;
+        if (gasPrice === null || gasPrice <= 0n)
+            throw new Error("SETTLEMENT_FEE_UNAVAILABLE: RPC did not supply a gas price.");
+        return fee.maxFeePerGas !== null && fee.maxPriorityFeePerGas !== null
+            ? {
+                maxFeePerGas: fee.maxFeePerGas,
+                maxPriorityFeePerGas: fee.maxPriorityFeePerGas,
+            }
+            : { gasPrice };
+    };
+    const budget = async (cost) => {
+        const cap = process.env.AIPOU_MAX_SETTLEMENT_FEE_WEI;
+        if (cap && (!/^\d+$/.test(cap) || cost > BigInt(cap)))
+            throw new Error("SETTLEMENT_FEE_CAP: required fee exceeds AIPOU_MAX_SETTLEMENT_FEE_WEI.");
+        if ((await provider.getBalance(signer.address)) < cost) {
+            throw new Error(`SETTLEMENT_INSUFFICIENT_GAS: validator needs up to ${cost} wei for this batch including a conservative Base data-fee allowance. Fund the validator on Base and retry; no automatic transfer is performed.`);
+        }
+    };
+    return {
+        approved: (root) => claims.approvedRoots(root),
+        claimed: (id) => claims.claimedReceipts(id),
+        preflight: async (plan, publishNeeded) => {
+            const fee = await fees();
+            const price = "gasPrice" in fee ? fee.gasPrice : fee.maxFeePerGas;
+            // A claim cannot be estimated against an unpublished root without reverting.
+            // Reserve a conservative upper bound before any publication; after publication
+            // use the actual RPC estimate. This is a balance gate, not a spending promise.
+            const claimGas = publishNeeded
+                ? 120000n + BigInt(plan.receiptIds.length) * 100000n
+                : await provider.estimateGas({
+                    from: signer.address,
+                    to: contract,
+                    data: data("claim", plan),
+                });
+            const pubGas = publishNeeded
+                ? await provider.estimateGas({
+                    from: signer.address,
+                    to: contract,
+                    data: data("publish", plan),
+                })
+                : 0n;
+            await budget(((claimGas + pubGas) * price * 120n) / 100n + 20000000000000n);
+        },
+        prepare: async (kind, plan) => {
+            const request = {
+                to: contract,
+                data: data(kind, plan),
+                value: 0n,
+                ...(await fees()),
+            };
+            const gasLimit = ((await provider.estimateGas({ ...request, from: signer.address })) *
+                120n) /
+                100n;
+            const price = "gasPrice" in request ? request.gasPrice : request.maxFeePerGas;
+            await budget(gasLimit * price + 20000000000000n);
+            const populated = await signer.populateTransaction({
+                ...request,
+                gasLimit,
+            });
+            const raw = await signer.signTransaction(populated);
+            const hash = Transaction.from(raw).hash;
+            return { hash, raw };
+        },
+        receipt: async (hash) => {
+            const result = await provider.getTransactionReceipt(hash);
+            return result ? { hash: result.hash, status: result.status } : null;
+        },
+        broadcast: async (tx) => {
+            const decoded = Transaction.from(tx.raw);
+            if (decoded.hash !== tx.hash ||
+                decoded.from !== signer.address ||
+                decoded.to?.toLowerCase() !== contract.toLowerCase() ||
+                decoded.chainId !== 8453n ||
+                decoded.value !== 0n) {
+                throw new Error("SETTLEMENT_JOURNAL_INVALID: saved transaction identity does not match this validator and contract.");
+            }
+            // If an RPC already knows this exact transaction, wait rather than signing again.
+            if (await provider.getTransaction(tx.hash))
+                return;
+            try {
+                await provider.broadcastTransaction(tx.raw);
+            }
+            catch {
+                if (await provider.getTransaction(tx.hash))
+                    return;
+                throw new Error("SETTLEMENT_BROADCAST_UNCONFIRMED: saved transaction retained; retry to reconcile. No replacement transaction was signed.");
+            }
+        },
+        wait: async (hash) => {
+            try {
+                const result = await provider.waitForTransaction(hash, 1, 90_000);
+                return result ? { hash: result.hash, status: result.status } : null;
+            }
+            catch {
+                throw new Error("SETTLEMENT_CONFIRMATION_UNAVAILABLE: saved transaction retained; retry to reconcile.");
+            }
+        },
+    };
+}

package/dist/settlement-driver.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settlement-driver.test.js

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Wallet, Transaction } from "ethers";
+import { createSettlementDriver } from "./settlement-driver.js";
+const plan = {
+    version: 1,
+    chainId: 8453,
+    contract: "0x1111111111111111111111111111111111111111",
+    root: "0x" + "ab".repeat(32),
+    accounts: ["0x2222222222222222222222222222222222222222"],
+    amounts: ["1"],
+    receiptIds: ["0x" + "cd".repeat(32)],
+    proofs: [[]],
+};
+function fixture(balance) {
+    const wallet = Wallet.createRandom();
+    let signed = 0;
+    const provider = {
+        getFeeData: async () => ({
+            maxFeePerGas: 100n,
+            maxPriorityFeePerGas: 1n,
+            gasPrice: 100n,
+        }),
+        getBalance: async () => balance,
+        estimateGas: async () => 50000n,
+    };
+    const signer = {
+        address: wallet.address,
+        provider,
+        populateTransaction: async (request) => ({
+            ...request,
+            chainId: 8453,
+            nonce: 7,
+        }),
+        signTransaction: async (request) => {
+            signed++;
+            return wallet.signTransaction(request);
+        },
+    };
+    return {
+        driver: createSettlementDriver(signer, plan.contract),
+        signed: () => signed,
+        address: wallet.address,
+    };
+}
+test("real settlement driver rejects a low balance before signing publication or claim", async () => {
+    const f = fixture(1n);
+    await assert.rejects(f.driver.preflight(plan, true, [0]), /INSUFFICIENT_GAS/);
+    await assert.rejects(f.driver.prepare("publish", plan, []), /INSUFFICIENT_GAS/);
+    assert.equal(f.signed(), 0);
+});
+test("real settlement driver applies fee cap before signing", async () => {
+    const previous = process.env.AIPOU_MAX_SETTLEMENT_FEE_WEI;
+    try {
+        process.env.AIPOU_MAX_SETTLEMENT_FEE_WEI = "1";
+        const f = fixture(10n ** 18n);
+        await assert.rejects(f.driver.prepare("claim", plan, [0]), /FEE_CAP/);
+        assert.equal(f.signed(), 0);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.AIPOU_MAX_SETTLEMENT_FEE_WEI;
+        else
+            process.env.AIPOU_MAX_SETTLEMENT_FEE_WEI = previous;
+    }
+});
+test("real settlement driver signs only a zero-value Base call to the claims contract", async () => {
+    const f = fixture(10n ** 18n);
+    const saved = await f.driver.prepare("publish", plan, []);
+    const tx = Transaction.from(saved.raw);
+    assert.equal(tx.hash, saved.hash);
+    assert.equal(tx.from, f.address);
+    assert.equal(tx.to, plan.contract);
+    assert.equal(tx.value, 0n);
+    assert.equal(tx.chainId, 8453n);
+    assert.equal(tx.nonce, 7);
+    await assert.rejects(f.driver.broadcast({ ...saved, hash: "0x" + "ef".repeat(32) }), /JOURNAL_INVALID/);
+});

package/dist/settlement-runner.d.ts

@@ -0,0 +1,34 @@
+export interface SettlementPlan {
+    version: 1;
+    chainId: number;
+    contract: string;
+    root: string;
+    accounts: string[];
+    amounts: string[];
+    receiptIds: string[];
+    proofs: string[][];
+    publish?: SignedSettlementTransaction;
+    claim?: SignedSettlementTransaction;
+}
+export interface SignedSettlementTransaction {
+    hash: string;
+    raw: string;
+}
+export interface SettlementConfirmation {
+    hash: string;
+    status: number | null;
+}
+export interface SettlementDriver {
+    approved(root: string): Promise<boolean>;
+    claimed(id: string): Promise<boolean>;
+    preflight(plan: SettlementPlan, publishNeeded: boolean, indices: number[]): Promise<void>;
+    prepare(kind: "publish" | "claim", plan: SettlementPlan, indices: number[]): Promise<SignedSettlementTransaction>;
+    receipt(hash: string): Promise<SettlementConfirmation | null>;
+    broadcast(tx: SignedSettlementTransaction): Promise<void>;
+    wait(hash: string): Promise<SettlementConfirmation | null>;
+}
+/** Persist signed bytes before broadcast; recovery resends the exact same hash. */
+export declare function executeSettlementPlan(plan: SettlementPlan, driver: SettlementDriver, persist: (plan: SettlementPlan) => Promise<void>): Promise<{
+    publishTransaction: string;
+    claimTransaction: string;
+}>;

package/dist/settlement-runner.js

@@ -0,0 +1,40 @@
+/** Persist signed bytes before broadcast; recovery resends the exact same hash. */
+export async function executeSettlementPlan(plan, driver, persist) {
+    const execute = async (kind, indices) => {
+        let tx = plan[kind];
+        if (!tx) {
+            tx = await driver.prepare(kind, plan, indices);
+            plan[kind] = tx;
+            await persist(plan);
+        }
+        let result = await driver.receipt(tx.hash);
+        if (!result) {
+            await driver.broadcast(tx);
+            result = await driver.wait(tx.hash);
+        }
+        if (!result)
+            throw new Error("SETTLEMENT_UNCONFIRMED: rerun to reconcile the saved transaction; do not replace it.");
+        if (result.hash.toLowerCase() !== tx.hash.toLowerCase() ||
+            result.status !== 1) {
+            throw new Error("SETTLEMENT_REVERTED: inspect the saved hash before an operator resets the journal.");
+        }
+        return result.hash;
+    };
+    if (plan.claim) {
+        const claimTransaction = await execute("claim", []);
+        return { publishTransaction: plan.publish?.hash ?? "", claimTransaction };
+    }
+    const claimed = await Promise.all(plan.receiptIds.map((id) => driver.claimed(id)));
+    if (claimed.some(Boolean))
+        throw new Error("SETTLEMENT_RECONCILIATION_REQUIRED: onchain claims exist without a saved transaction; inspect events before changing local state.");
+    const indices = plan.receiptIds.map((_, i) => i);
+    const rootApproved = await driver.approved(plan.root);
+    await driver.preflight(plan, !rootApproved, indices);
+    const publishTransaction = rootApproved
+        ? (plan.publish?.hash ?? "")
+        : await execute("publish", []);
+    if (!(await driver.approved(plan.root)))
+        throw new Error("SETTLEMENT_ROOT_UNCONFIRMED: rerun to reconcile.");
+    const claimTransaction = await execute("claim", indices);
+    return { publishTransaction, claimTransaction };
+}

package/dist/settlement-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settlement-runner.test.js

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { executeSettlementPlan, } from "./settlement-runner.js";
+function fixture(approved = false) {
+    const plan = {
+        version: 1,
+        chainId: 8453,
+        contract: "claims",
+        root: "root",
+        accounts: ["wallet"],
+        amounts: ["10"],
+        receiptIds: ["id"],
+        proofs: [[]],
+    };
+    const confirmed = new Map();
+    const prepared = [], sent = [], persisted = [];
+    let balance = true, dropReply = false;
+    const driver = {
+        approved: async () => approved,
+        claimed: async () => false,
+        preflight: async () => {
+            if (!balance)
+                throw new Error("SETTLEMENT_INSUFFICIENT_GAS");
+        },
+        prepare: async (kind) => {
+            prepared.push(kind);
+            return { hash: kind, raw: kind + "-signed" };
+        },
+        receipt: async (hash) => confirmed.get(hash) ?? null,
+        broadcast: async (tx) => {
+            sent.push(tx.hash);
+            confirmed.set(tx.hash, { hash: tx.hash, status: 1 });
+            if (tx.hash === "publish")
+                approved = true;
+            if (dropReply) {
+                dropReply = false;
+                throw new Error("network reply lost");
+            }
+        },
+        wait: async (hash) => confirmed.get(hash) ?? null,
+    };
+    const persist = async (p) => {
+        persisted.push(JSON.stringify(p));
+    };
+    return {
+        plan,
+        driver,
+        persist,
+        prepared,
+        sent,
+        persisted,
+        confirmed,
+        noGas: () => {
+            balance = false;
+        },
+        loseNextReply: () => {
+            dropReply = true;
+        },
+    };
+}
+test("preflight refuses insufficient gas before any transaction is signed or sent", async () => {
+    const f = fixture();
+    f.noGas();
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /INSUFFICIENT_GAS/);
+    assert.deepEqual(f.prepared, []);
+    assert.deepEqual(f.sent, []);
+});
+test("already approved root is not republished", async () => {
+    const f = fixture(true);
+    const result = await executeSettlementPlan(f.plan, f.driver, f.persist);
+    assert.deepEqual(f.prepared, ["claim"]);
+    assert.equal(result.publishTransaction, "");
+});
+test("lost publication response resumes saved hash and never signs another publication", async () => {
+    const f = fixture();
+    f.loseNextReply();
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /reply lost/);
+    const restored = JSON.parse(f.persisted.at(-1));
+    const result = await executeSettlementPlan(restored, f.driver, f.persist);
+    assert.equal(result.publishTransaction, "publish");
+    assert.deepEqual(f.prepared, ["publish", "claim"]);
+});
+test("crash after signing claim recovers the same bytes, including when broadcast was not attempted", async () => {
+    const f = fixture(true);
+    let signed;
+    f.driver.broadcast = async (tx) => {
+        signed = tx;
+        throw new Error("offline");
+    };
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /offline/);
+    const restored = JSON.parse(f.persisted.at(-1));
+    f.driver.broadcast = async (tx) => {
+        assert.deepEqual(tx, signed);
+        f.confirmed.set(tx.hash, { hash: tx.hash, status: 1 });
+    };
+    await executeSettlementPlan(restored, f.driver, f.persist);
+    assert.deepEqual(f.prepared, ["claim"]);
+});
+test("confirmed claim survives a lost response without repeat broadcast", async () => {
+    const f = fixture(true);
+    f.loseNextReply();
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /reply lost/);
+    const result = await executeSettlementPlan(f.plan, f.driver, f.persist);
+    assert.equal(result.claimTransaction, "claim");
+    assert.deepEqual(f.sent, ["claim"]);
+});
+test("unconfirmed and reverted transactions do not get replaced", async () => {
+    const f = fixture(true);
+    f.driver.wait = async () => null;
+    f.driver.broadcast = async () => { };
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /UNCONFIRMED/);
+    f.confirmed.set("claim", { hash: "claim", status: 0 });
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /REVERTED/);
+    assert.deepEqual(f.prepared, ["claim"]);
+});
+test("unexpected onchain claims require explicit reconciliation", async () => {
+    const f = fixture();
+    f.driver.claimed = async () => true;
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, f.persist), /RECONCILIATION_REQUIRED/);
+    assert.deepEqual(f.sent, []);
+});
+test("journal persistence failure happens before broadcast", async () => {
+    const f = fixture();
+    await assert.rejects(executeSettlementPlan(f.plan, f.driver, async () => {
+        throw new Error("disk full");
+    }), /disk full/);
+    assert.deepEqual(f.sent, []);
+});

package/dist/status.js

@@ -52,6 +52,8 @@ export async function getAipouStatus() {
             claimed: claimedReceipts.length,
             pending: walletPendingReceipts.length,
             incompleteSessions: counts.incompleteSessions,
+            activeSessions: counts.activeSessions,
+            expiredSessions: counts.expiredSessions,
             batches: counts.batches
         },
         rewards: {

package/dist/store.d.ts

@@ -8,6 +8,8 @@ export declare function protocolStateCounts(): Promise<{
     sessions: number;
     completedSessions: number;
     incompleteSessions: number;
+    activeSessions: number;
+    expiredSessions: number;
     batches: number;
 }>;
 export declare function settledReceiptsSince(sinceMs: number): Promise<UsageReceipt[]>;