claude-flow 3.14.4 → 3.16.0

package/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "Bash(mkdir -p /tmp/ruflo-smoke)",
       "Bash(rm -rf /tmp/ruflo-smoke/*)",
       "Read(//tmp/**)",
-      "Bash(npm pack *)"
+      "Bash(npm pack *)",
+      "WebFetch(domain:www.npmjs.com)"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.14.4",
+  "version": "3.16.0",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/business-pods/bbs-budget-tracker.d.ts

@@ -0,0 +1,139 @@
+/**
+ * BbsRoomBudgetTracker — Atomic reserve / commit / release token-bucket
+ * backed by better-sqlite3 (ADR-164.1 §3-§5).
+ *
+ * Closes the read-then-write race in ADR-164's first-draft tracker by routing
+ * every state transition through a single `BEGIN IMMEDIATE` transaction that
+ * acquires the SQLite write lock atomically with the gate check. The
+ * `_lock_bump` column write is a belt-and-suspenders explicit write inside
+ * the transaction so the lock acquisition is visible to code review and
+ * query-log analysis (§3.2 peer-review clarification).
+ *
+ * Architectural constraints (ADR-164.1):
+ *   - Default OFF: this module is opt-in behind `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`.
+ *     The pod-tick.mjs file-based stub remains the default until the flag is
+ *     flipped per ADR-164.1 §12.4.
+ *   - `committed_post_expiry` state machine implemented per §5.3 — late
+ *     commits on expired reservations ARE accepted (the API spend already
+ *     happened), transition to `committed_post_expiry`, charge the budget,
+ *     and return `warned: 'COMMIT_AFTER_EXPIRY'`. This closes the §8.1
+ *     Expired Commit Leak surfaced by peer review on 2026-06-29.
+ *   - `expires_at` is clamped to [5_000, 300_000] ms (§3.2).
+ *   - WAL + synchronous=NORMAL + busy_timeout=500 for write throughput.
+ *
+ * The sweeper interval (`sweepExpired()`) is exposed as a manual method;
+ * callers are expected to drive it on a setInterval — that integration lives
+ * at the call site, not in this file, per ADR-164.1 §7.1.
+ *
+ * @module @claude-flow/cli/business-pods/bbs-budget-tracker
+ */
+export interface SqliteDatabase {
+    pragma(name: string): unknown;
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): void;
+    close(): void;
+}
+export interface SqliteStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): Record<string, unknown> | undefined;
+    all(...params: unknown[]): Record<string, unknown>[];
+}
+export declare const RESERVATION_EXPIRY_FLOOR_MS = 5000;
+export declare const RESERVATION_EXPIRY_CEILING_MS = 300000;
+export declare const RESERVATION_EXPIRY_DEFAULT_MS = 60000;
+export declare function clampReservationExpiry(raw: number | undefined): number;
+export type ReserveResult = {
+    ok: true;
+    reservationId: string;
+    remainingAfterReserve: number;
+} | {
+    ok: false;
+    error: 'BUDGET_EXCEEDED' | 'ROOM_NOT_FOUND';
+};
+export type CommitResult = {
+    ok: true;
+    committed: true;
+    finalRemaining: number;
+} | {
+    ok: true;
+    warned: 'COMMIT_AFTER_EXPIRY';
+    finalRemaining: number;
+} | {
+    ok: false;
+    error: 'NOT_FOUND' | 'ALREADY_FINALIZED';
+};
+export type ReleaseResult = {
+    ok: true;
+    released: true;
+} | {
+    ok: false;
+    error: 'NOT_FOUND' | 'ALREADY_FINALIZED';
+};
+export declare const SCHEMA_SQL = "\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA busy_timeout = 500;\n\nCREATE TABLE IF NOT EXISTS bbs_budget_rooms (\n  room_id         TEXT NOT NULL PRIMARY KEY,\n  monthly_cap_usd REAL NOT NULL CHECK (monthly_cap_usd >= 0),\n  billing_month   TEXT NOT NULL,\n  _lock_bump      INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE TABLE IF NOT EXISTS bbs_budget_reservations (\n  reservation_id    TEXT NOT NULL PRIMARY KEY,\n  room_id           TEXT NOT NULL REFERENCES bbs_budget_rooms(room_id),\n  caller_node_id    TEXT NOT NULL,\n  estimated_usd     REAL NOT NULL CHECK (estimated_usd >= 0),\n  actual_usd        REAL,\n  state             TEXT NOT NULL\n                    CHECK (state IN ('reserved','committed','released','expired','committed_post_expiry')),\n  reserved_at       INTEGER NOT NULL,\n  expires_at        INTEGER NOT NULL,\n  committed_at      INTEGER,\n  audit_envelope_id TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_reservations_room_month\n  ON bbs_budget_reservations (room_id, reserved_at);\n\nCREATE INDEX IF NOT EXISTS idx_reservations_expiry\n  ON bbs_budget_reservations (state, expires_at);\n";
+export interface BudgetAuditSink {
+    emit(eventType: 'reservation.committed_post_expiry' | 'reservation.committed' | 'reservation.released' | 'reservation.reserved' | 'reservation.budget_exceeded', payload: Record<string, unknown>): void;
+}
+export interface AtomicBbsRoomBudgetTrackerOptions {
+    /** SQLite database handle (caller-owned, opened in WAL mode). */
+    db: SqliteDatabase;
+    /** Override the default 60s reservation window (clamped to [5s, 300s]). */
+    defaultExpiryMs?: number;
+    /** Audit sink — receives reservation lifecycle events. */
+    audit?: BudgetAuditSink;
+    /** Inject Date.now() for tests. */
+    clock?: () => number;
+}
+export declare class AtomicBbsRoomBudgetTracker {
+    private readonly db;
+    private readonly defaultExpiryMs;
+    private readonly audit;
+    private readonly clock;
+    constructor(opts: AtomicBbsRoomBudgetTrackerOptions);
+    /**
+     * Register (or update) a room and its monthly cap. Idempotent.
+     */
+    registerRoom(roomId: string, monthlyCapUsd: number): void;
+    /**
+     * Atomically check budget and insert a reservation row in a single
+     * BEGIN IMMEDIATE transaction. See ADR-164.1 §5.2.
+     */
+    reserve(roomId: string, callerId: string, estimatedUsd: number, opts?: {
+        auditEnvelopeId?: string;
+        expiryMs?: number;
+    }): ReserveResult;
+    /**
+     * Commit the reservation with the actual cost. Late commits (expired
+     * before commit landed) ARE accepted, transitioned to
+     * 'committed_post_expiry', charged to the budget, and surfaced via
+     * `warned: 'COMMIT_AFTER_EXPIRY'` plus a `reservation.committed_post_expiry`
+     * audit emit. See ADR-164.1 §5.3 + §8.1.
+     */
+    commit(reservationId: string, actualUsd: number): CommitResult;
+    /**
+     * Release a reservation (caller decided not to proceed). State must be
+     * 'reserved'; any other state is ALREADY_FINALIZED.
+     */
+    release(reservationId: string): ReleaseResult;
+    /**
+     * Sweep expired reservations: transition 'reserved' rows whose expiry has
+     * passed to 'expired'. Callers should drive this on a setInterval per
+     * ADR-164.1 §7.1 (default cadence 5s; this method does NOT install the
+     * timer — that's the integration site's responsibility).
+     * Returns the number of rows updated.
+     */
+    sweepExpired(): number;
+    /**
+     * Diagnostic read: list reservations for a room. Not on the hot path.
+     */
+    listReservations(roomId: string): Array<Record<string, unknown>>;
+}
+/**
+ * Feature-flagged factory per ADR-164.1 §12.3. Returns an atomic tracker
+ * when `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`, otherwise returns null so the
+ * caller can keep using the file-based stub in pod-tick.mjs.
+ */
+export declare function createAtomicTrackerIfEnabled(opts: AtomicBbsRoomBudgetTrackerOptions): AtomicBbsRoomBudgetTracker | null;
+//# sourceMappingURL=bbs-budget-tracker.d.ts.map

package/v3/@claude-flow/cli/dist/src/business-pods/bbs-budget-tracker.js

@@ -0,0 +1,358 @@
+/**
+ * BbsRoomBudgetTracker — Atomic reserve / commit / release token-bucket
+ * backed by better-sqlite3 (ADR-164.1 §3-§5).
+ *
+ * Closes the read-then-write race in ADR-164's first-draft tracker by routing
+ * every state transition through a single `BEGIN IMMEDIATE` transaction that
+ * acquires the SQLite write lock atomically with the gate check. The
+ * `_lock_bump` column write is a belt-and-suspenders explicit write inside
+ * the transaction so the lock acquisition is visible to code review and
+ * query-log analysis (§3.2 peer-review clarification).
+ *
+ * Architectural constraints (ADR-164.1):
+ *   - Default OFF: this module is opt-in behind `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`.
+ *     The pod-tick.mjs file-based stub remains the default until the flag is
+ *     flipped per ADR-164.1 §12.4.
+ *   - `committed_post_expiry` state machine implemented per §5.3 — late
+ *     commits on expired reservations ARE accepted (the API spend already
+ *     happened), transition to `committed_post_expiry`, charge the budget,
+ *     and return `warned: 'COMMIT_AFTER_EXPIRY'`. This closes the §8.1
+ *     Expired Commit Leak surfaced by peer review on 2026-06-29.
+ *   - `expires_at` is clamped to [5_000, 300_000] ms (§3.2).
+ *   - WAL + synchronous=NORMAL + busy_timeout=500 for write throughput.
+ *
+ * The sweeper interval (`sweepExpired()`) is exposed as a manual method;
+ * callers are expected to drive it on a setInterval — that integration lives
+ * at the call site, not in this file, per ADR-164.1 §7.1.
+ *
+ * @module @claude-flow/cli/business-pods/bbs-budget-tracker
+ */
+import { randomUUID } from 'node:crypto';
+// ---------- expiry-window clamp -------------------------------------------
+export const RESERVATION_EXPIRY_FLOOR_MS = 5_000;
+export const RESERVATION_EXPIRY_CEILING_MS = 300_000;
+export const RESERVATION_EXPIRY_DEFAULT_MS = 60_000;
+export function clampReservationExpiry(raw) {
+    if (raw === undefined || !Number.isFinite(raw)) {
+        const envVal = Number(process.env.CLAUDE_FLOW_BBS_RESERVATION_EXPIRY_MS);
+        if (Number.isFinite(envVal) && envVal > 0) {
+            return Math.max(RESERVATION_EXPIRY_FLOOR_MS, Math.min(RESERVATION_EXPIRY_CEILING_MS, envVal));
+        }
+        return RESERVATION_EXPIRY_DEFAULT_MS;
+    }
+    return Math.max(RESERVATION_EXPIRY_FLOOR_MS, Math.min(RESERVATION_EXPIRY_CEILING_MS, raw));
+}
+// ---------- schema migration ----------------------------------------------
+export const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA busy_timeout = 500;
+
+CREATE TABLE IF NOT EXISTS bbs_budget_rooms (
+  room_id         TEXT NOT NULL PRIMARY KEY,
+  monthly_cap_usd REAL NOT NULL CHECK (monthly_cap_usd >= 0),
+  billing_month   TEXT NOT NULL,
+  _lock_bump      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS bbs_budget_reservations (
+  reservation_id    TEXT NOT NULL PRIMARY KEY,
+  room_id           TEXT NOT NULL REFERENCES bbs_budget_rooms(room_id),
+  caller_node_id    TEXT NOT NULL,
+  estimated_usd     REAL NOT NULL CHECK (estimated_usd >= 0),
+  actual_usd        REAL,
+  state             TEXT NOT NULL
+                    CHECK (state IN ('reserved','committed','released','expired','committed_post_expiry')),
+  reserved_at       INTEGER NOT NULL,
+  expires_at        INTEGER NOT NULL,
+  committed_at      INTEGER,
+  audit_envelope_id TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_reservations_room_month
+  ON bbs_budget_reservations (room_id, reserved_at);
+
+CREATE INDEX IF NOT EXISTS idx_reservations_expiry
+  ON bbs_budget_reservations (state, expires_at);
+`;
+// ---------- helpers --------------------------------------------------------
+function currentBillingMonth(now) {
+    const d = new Date(now);
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+function billingMonthStartMs(billingMonth) {
+    const [y, m] = billingMonth.split('-').map((n) => Number(n));
+    return Date.UTC(y, (m - 1), 1, 0, 0, 0, 0);
+}
+const noopAudit = { emit: () => undefined };
+export class AtomicBbsRoomBudgetTracker {
+    db;
+    defaultExpiryMs;
+    audit;
+    clock;
+    constructor(opts) {
+        this.db = opts.db;
+        this.defaultExpiryMs = clampReservationExpiry(opts.defaultExpiryMs);
+        this.audit = opts.audit ?? noopAudit;
+        this.clock = opts.clock ?? Date.now;
+        // Ensure schema is present. exec() is a no-op for tables that already
+        // exist due to IF NOT EXISTS.
+        this.db.exec(SCHEMA_SQL);
+    }
+    /**
+     * Register (or update) a room and its monthly cap. Idempotent.
+     */
+    registerRoom(roomId, monthlyCapUsd) {
+        const billingMonth = currentBillingMonth(this.clock());
+        this.db
+            .prepare(`INSERT INTO bbs_budget_rooms (room_id, monthly_cap_usd, billing_month, _lock_bump)
+         VALUES (?, ?, ?, 0)
+         ON CONFLICT(room_id) DO UPDATE SET monthly_cap_usd = excluded.monthly_cap_usd`)
+            .run(roomId, monthlyCapUsd, billingMonth);
+    }
+    /**
+     * Atomically check budget and insert a reservation row in a single
+     * BEGIN IMMEDIATE transaction. See ADR-164.1 §5.2.
+     */
+    reserve(roomId, callerId, estimatedUsd, opts) {
+        if (!Number.isFinite(estimatedUsd) || estimatedUsd < 0) {
+            throw new Error('estimatedUsd must be a non-negative finite number');
+        }
+        const auditEnvelopeId = opts?.auditEnvelopeId ?? `audit-${randomUUID()}`;
+        const expiryMs = clampReservationExpiry(opts?.expiryMs ?? this.defaultExpiryMs);
+        const nowMs = this.clock();
+        const billingMonth = currentBillingMonth(nowMs);
+        const billingMonthStart = billingMonthStartMs(billingMonth);
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            // Step 1: touch the room header row (the _lock_bump write makes the
+            // lock acquisition visible per §3.2 peer-review note).
+            const bumpRes = this.db
+                .prepare(`UPDATE bbs_budget_rooms
+             SET _lock_bump = _lock_bump + 1,
+                 billing_month = CASE WHEN billing_month = ? THEN billing_month ELSE ? END
+             WHERE room_id = ?`)
+                .run(billingMonth, billingMonth, roomId);
+            if (bumpRes.changes === 0) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ROOM_NOT_FOUND' };
+            }
+            const roomRow = this.db
+                .prepare(`SELECT monthly_cap_usd, billing_month FROM bbs_budget_rooms WHERE room_id = ?`)
+                .get(roomId);
+            if (!roomRow) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ROOM_NOT_FOUND' };
+            }
+            const monthlyCap = roomRow.monthly_cap_usd;
+            // Step 3: compute committed + live-reserved totals within this billing month.
+            const totals = this.db
+                .prepare(`SELECT
+             COALESCE(SUM(CASE WHEN state IN ('committed','committed_post_expiry') THEN actual_usd ELSE 0 END), 0) AS committed_total,
+             COALESCE(SUM(CASE WHEN state = 'reserved' AND expires_at > ? THEN estimated_usd ELSE 0 END), 0) AS reserved_total
+           FROM bbs_budget_reservations
+           WHERE room_id = ? AND reserved_at >= ?`)
+                .get(nowMs, roomId, billingMonthStart);
+            const committedTotal = totals.committed_total ?? 0;
+            const reservedTotal = totals.reserved_total ?? 0;
+            const projected = committedTotal + reservedTotal + estimatedUsd;
+            if (projected > monthlyCap + 1e-9) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                this.audit.emit('reservation.budget_exceeded', {
+                    roomId, callerId, estimatedUsd, committedTotal, reservedTotal, monthlyCap,
+                });
+                return { ok: false, error: 'BUDGET_EXCEEDED' };
+            }
+            // Step 5: insert the reservation.
+            const reservationId = `res-${randomUUID()}`;
+            const expiresAt = nowMs + expiryMs;
+            this.db
+                .prepare(`INSERT INTO bbs_budget_reservations
+             (reservation_id, room_id, caller_node_id, estimated_usd, actual_usd,
+              state, reserved_at, expires_at, committed_at, audit_envelope_id)
+           VALUES (?, ?, ?, ?, NULL, 'reserved', ?, ?, NULL, ?)`)
+                .run(reservationId, roomId, callerId, estimatedUsd, nowMs, expiresAt, auditEnvelopeId);
+            commitStmt.run();
+            transactionOpen = false;
+            const remaining = monthlyCap - (committedTotal + reservedTotal + estimatedUsd);
+            this.audit.emit('reservation.reserved', {
+                reservationId, roomId, callerId, estimatedUsd, expiresAt, remaining,
+            });
+            return { ok: true, reservationId, remainingAfterReserve: remaining };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Commit the reservation with the actual cost. Late commits (expired
+     * before commit landed) ARE accepted, transitioned to
+     * 'committed_post_expiry', charged to the budget, and surfaced via
+     * `warned: 'COMMIT_AFTER_EXPIRY'` plus a `reservation.committed_post_expiry`
+     * audit emit. See ADR-164.1 §5.3 + §8.1.
+     */
+    commit(reservationId, actualUsd) {
+        if (!Number.isFinite(actualUsd) || actualUsd < 0) {
+            throw new Error('actualUsd must be a non-negative finite number');
+        }
+        const nowMs = this.clock();
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            const row = this.db
+                .prepare(`SELECT state, room_id, estimated_usd, reserved_at, expires_at
+             FROM bbs_budget_reservations
+             WHERE reservation_id = ?`)
+                .get(reservationId);
+            if (!row) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'NOT_FOUND' };
+            }
+            if (row.state === 'committed' || row.state === 'committed_post_expiry' ||
+                row.state === 'released' || row.state === 'expired') {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ALREADY_FINALIZED' };
+            }
+            // state is 'reserved' here. Decide committed vs committed_post_expiry.
+            const lateCommit = row.expires_at <= nowMs;
+            const newState = lateCommit ? 'committed_post_expiry' : 'committed';
+            this.db
+                .prepare(`UPDATE bbs_budget_reservations
+             SET state = ?, actual_usd = ?, committed_at = ?
+             WHERE reservation_id = ?`)
+                .run(newState, actualUsd, nowMs, reservationId);
+            // Re-compute remaining for the return value.
+            const billingMonth = currentBillingMonth(nowMs);
+            const billingMonthStart = billingMonthStartMs(billingMonth);
+            const totals = this.db
+                .prepare(`SELECT
+             COALESCE(SUM(CASE WHEN state IN ('committed','committed_post_expiry') THEN actual_usd ELSE 0 END), 0) AS committed_total,
+             COALESCE(SUM(CASE WHEN state = 'reserved' AND expires_at > ? THEN estimated_usd ELSE 0 END), 0) AS reserved_total
+           FROM bbs_budget_reservations
+           WHERE room_id = ? AND reserved_at >= ?`)
+                .get(nowMs, row.room_id, billingMonthStart);
+            const roomRow = this.db
+                .prepare(`SELECT monthly_cap_usd FROM bbs_budget_rooms WHERE room_id = ?`)
+                .get(row.room_id);
+            const monthlyCap = roomRow?.monthly_cap_usd ?? 0;
+            const finalRemaining = monthlyCap - ((totals.committed_total ?? 0) + (totals.reserved_total ?? 0));
+            commitStmt.run();
+            transactionOpen = false;
+            if (lateCommit) {
+                // Emit the high-priority audit envelope per §8.1.
+                this.audit.emit('reservation.committed_post_expiry', {
+                    reservationId, roomId: row.room_id, actualUsd, finalRemaining,
+                    reservedAt: row.reserved_at, expiresAt: row.expires_at, committedAt: nowMs,
+                });
+                return { ok: true, warned: 'COMMIT_AFTER_EXPIRY', finalRemaining };
+            }
+            this.audit.emit('reservation.committed', {
+                reservationId, roomId: row.room_id, actualUsd, finalRemaining,
+            });
+            return { ok: true, committed: true, finalRemaining };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Release a reservation (caller decided not to proceed). State must be
+     * 'reserved'; any other state is ALREADY_FINALIZED.
+     */
+    release(reservationId) {
+        const beginStmt = this.db.prepare('BEGIN IMMEDIATE');
+        const commitStmt = this.db.prepare('COMMIT');
+        const rollbackStmt = this.db.prepare('ROLLBACK');
+        beginStmt.run();
+        let transactionOpen = true;
+        try {
+            const row = this.db
+                .prepare(`SELECT state, room_id FROM bbs_budget_reservations WHERE reservation_id = ?`)
+                .get(reservationId);
+            if (!row) {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'NOT_FOUND' };
+            }
+            if (row.state !== 'reserved') {
+                rollbackStmt.run();
+                transactionOpen = false;
+                return { ok: false, error: 'ALREADY_FINALIZED' };
+            }
+            this.db
+                .prepare(`UPDATE bbs_budget_reservations SET state = 'released' WHERE reservation_id = ?`)
+                .run(reservationId);
+            commitStmt.run();
+            transactionOpen = false;
+            this.audit.emit('reservation.released', { reservationId, roomId: row.room_id });
+            return { ok: true, released: true };
+        }
+        catch (err) {
+            if (transactionOpen) {
+                try {
+                    rollbackStmt.run();
+                }
+                catch { /* already-rolled */ }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Sweep expired reservations: transition 'reserved' rows whose expiry has
+     * passed to 'expired'. Callers should drive this on a setInterval per
+     * ADR-164.1 §7.1 (default cadence 5s; this method does NOT install the
+     * timer — that's the integration site's responsibility).
+     * Returns the number of rows updated.
+     */
+    sweepExpired() {
+        const result = this.db
+            .prepare(`UPDATE bbs_budget_reservations
+           SET state = 'expired'
+           WHERE state = 'reserved' AND expires_at < ?`)
+            .run(this.clock());
+        return result.changes;
+    }
+    /**
+     * Diagnostic read: list reservations for a room. Not on the hot path.
+     */
+    listReservations(roomId) {
+        return this.db
+            .prepare(`SELECT * FROM bbs_budget_reservations WHERE room_id = ? ORDER BY reserved_at`)
+            .all(roomId);
+    }
+}
+/**
+ * Feature-flagged factory per ADR-164.1 §12.3. Returns an atomic tracker
+ * when `CLAUDE_FLOW_BBS_ATOMIC_BUDGET=1`, otherwise returns null so the
+ * caller can keep using the file-based stub in pod-tick.mjs.
+ */
+export function createAtomicTrackerIfEnabled(opts) {
+    if (process.env.CLAUDE_FLOW_BBS_ATOMIC_BUDGET !== '1')
+        return null;
+    return new AtomicBbsRoomBudgetTracker(opts);
+}
+//# sourceMappingURL=bbs-budget-tracker.js.map

package/v3/@claude-flow/cli/dist/src/business-pods/domain-affinity-policy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Domain-affinity routing policy — ADR-164 §3.4.
+ *
+ * Surfaces a deterministic routing decision for `@metaharness/router` to use
+ * before its KRR cost-optimal step. The policy is intentionally tiny —
+ * three branches over `preferLocalExecution` and `budgetUsdMonthly` — so the
+ * decision is auditable from the pod template alone, no learned-weight side
+ * effects.
+ *
+ * Rules (per the Phase-3 brief):
+ *   1. `preferLocalExecution === true`                                  → 'local-stdio'
+ *   2. `preferLocalExecution === false` AND `budgetUsdMonthly >= 50`    → 'cloud-managed'
+ *   3. otherwise                                                        → 'remote-peer'
+ *
+ * The boundary `>= 50` matches the Phase-2 sales template (budget 50/month) —
+ * it routes the canonical reference pod to the cloud-managed backend. Pods
+ * below the threshold default to the federation peer-node backend.
+ *
+ * Wire point: `@metaharness/router` reads the result and supplies it as a
+ * routing hint *before* its KRR step. The router is free to override on
+ * latency/cost grounds — domain affinity is a policy floor, not a hard gate.
+ *
+ * @module @claude-flow/cli/business-pods/domain-affinity-policy
+ */
+import type { PodTemplate } from './pod-schema.js';
+/** Three backends @metaharness/router can target for a pod tick. */
+export type AgentBackend = 'local-stdio' | 'remote-peer' | 'cloud-managed';
+/** Threshold for `cloud-managed` routing. Pods at or above this monthly
+ *  spend default to cloud-managed when they are *not* local-pinned. */
+export declare const CLOUD_BUDGET_THRESHOLD_USD = 50;
+/** Structured routing decision. `reason` is rendered into the routing
+ *  rationale via `hooks_explain` so operators can see why each pod was
+ *  routed where it was. */
+export interface BackendDecision {
+    backend: AgentBackend;
+    reason: string;
+}
+/**
+ * Decide which backend `@metaharness/router` should prefer for a pod tick.
+ *
+ * @param pod  A validated PodTemplate. Validation is the caller's
+ *             responsibility; this function will throw on malformed input
+ *             (specifically on missing `preferLocalExecution` or
+ *             `budgetUsdMonthly`).
+ */
+export declare function selectAgentBackend(pod: PodTemplate): BackendDecision;
+//# sourceMappingURL=domain-affinity-policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/business-pods/domain-affinity-policy.js

@@ -0,0 +1,65 @@
+/**
+ * Domain-affinity routing policy — ADR-164 §3.4.
+ *
+ * Surfaces a deterministic routing decision for `@metaharness/router` to use
+ * before its KRR cost-optimal step. The policy is intentionally tiny —
+ * three branches over `preferLocalExecution` and `budgetUsdMonthly` — so the
+ * decision is auditable from the pod template alone, no learned-weight side
+ * effects.
+ *
+ * Rules (per the Phase-3 brief):
+ *   1. `preferLocalExecution === true`                                  → 'local-stdio'
+ *   2. `preferLocalExecution === false` AND `budgetUsdMonthly >= 50`    → 'cloud-managed'
+ *   3. otherwise                                                        → 'remote-peer'
+ *
+ * The boundary `>= 50` matches the Phase-2 sales template (budget 50/month) —
+ * it routes the canonical reference pod to the cloud-managed backend. Pods
+ * below the threshold default to the federation peer-node backend.
+ *
+ * Wire point: `@metaharness/router` reads the result and supplies it as a
+ * routing hint *before* its KRR step. The router is free to override on
+ * latency/cost grounds — domain affinity is a policy floor, not a hard gate.
+ *
+ * @module @claude-flow/cli/business-pods/domain-affinity-policy
+ */
+/** Threshold for `cloud-managed` routing. Pods at or above this monthly
+ *  spend default to cloud-managed when they are *not* local-pinned. */
+export const CLOUD_BUDGET_THRESHOLD_USD = 50;
+/**
+ * Decide which backend `@metaharness/router` should prefer for a pod tick.
+ *
+ * @param pod  A validated PodTemplate. Validation is the caller's
+ *             responsibility; this function will throw on malformed input
+ *             (specifically on missing `preferLocalExecution` or
+ *             `budgetUsdMonthly`).
+ */
+export function selectAgentBackend(pod) {
+    if (pod === null || typeof pod !== 'object') {
+        throw new TypeError('selectAgentBackend: pod must be a validated PodTemplate object');
+    }
+    if (typeof pod.preferLocalExecution !== 'boolean') {
+        throw new TypeError('selectAgentBackend: pod.preferLocalExecution must be boolean (validate via pod-schema first)');
+    }
+    if (typeof pod.budgetUsdMonthly !== 'number' || !Number.isFinite(pod.budgetUsdMonthly)) {
+        throw new TypeError('selectAgentBackend: pod.budgetUsdMonthly must be a finite number (validate via pod-schema first)');
+    }
+    if (pod.preferLocalExecution) {
+        return {
+            backend: 'local-stdio',
+            reason: `pod "${pod.name}" preferLocalExecution=true — domain-affinity policy pins to local stdio`,
+        };
+    }
+    if (pod.budgetUsdMonthly >= CLOUD_BUDGET_THRESHOLD_USD) {
+        return {
+            backend: 'cloud-managed',
+            reason: `pod "${pod.name}" preferLocalExecution=false and budgetUsdMonthly=${pod.budgetUsdMonthly} ` +
+                `>= ${CLOUD_BUDGET_THRESHOLD_USD} — routes to cloud Managed Agents`,
+        };
+    }
+    return {
+        backend: 'remote-peer',
+        reason: `pod "${pod.name}" preferLocalExecution=false and budgetUsdMonthly=${pod.budgetUsdMonthly} ` +
+            `< ${CLOUD_BUDGET_THRESHOLD_USD} — routes to federation peer node`,
+    };
+}
+//# sourceMappingURL=domain-affinity-policy.js.map