sensorium-mcp 3.1.2 → 3.1.3-board.10

package/dist/services/board/worker-spawn.js

@@ -0,0 +1,177 @@
+/**
+ * Card-worker spawn path (design §3.1). The ordered bracket a worker is born
+ * through — mint identity → topic for that id → pre-queue payload → claim →
+ * registerThread → launch window → spawn → commit — lives in `worker-birth.ts` and
+ * is shared with `start_thread`'s `mode=worker` arm; what remains here is what is
+ * genuinely board-specific: the worktree isolation around it and the card bind
+ * passed as the claim. Giving a started — or possibly started — worker up is NOT
+ * board-specific and no longer lives here: the bracket owns that rung, and the
+ * board only hands it the kill, liveness and worktree wiring it already had.
+ *
+ * `bindWorker` is the claim for the reason the shared bracket runs claims where it
+ * does: dispatch ownership must be DURABLE before registerThread makes the worker
+ * observable, so no orchestrator — not even a second one overlapping a self-update —
+ * can ever see a badged worker that no card owns. That ordering is what lets the
+ * orphan sweep identify an orphan by ownership alone, with no age heuristic.
+ */
+import { getAgentType } from "../../config/index.js";
+import { log } from "../../lib/logger.js";
+import { errorMessage } from "../../lib/utils.js";
+import { BOARD_WORKER_BADGE, getThread } from "../../data/memory/thread-registry.js";
+import { getProfile } from "../../data/board/profile-defaults.js";
+import { Optional } from "../../data/optional.js";
+import { dispatchSpawn } from "../agent-spawn.service.js";
+import { deletePendingTaskMailboxAsync } from "../process.service.js";
+import { birthWorker } from "../worker-birth.js";
+import { renderCardBriefing } from "./card-briefing.js";
+import { createCardWorktree, removeWorktreeIfLinked, worktreeEnabled } from "./worktree.js";
+/**
+ * How a failed birth reads on a card. The shared bracket names the STEP that
+ * refused; the wording stays here, because this is the only place that knows the
+ * refused step was a card dispatch. `spawn` carries the launcher's own message
+ * through unprefixed — it already names what failed to start.
+ */
+const DISPATCH_FAILURE_PREFIX = {
+    mint: "Worker id allocation failed",
+    topic: "Topic creation failed",
+    payload: "Failed to pre-queue card payload",
+    claim: "Failed to bind card worker",
+    register: "Failed to register card worker",
+    window: "Failed to open the card worker launch window",
+    spawn: "",
+    commit: "Failed to commit the card worker launch",
+};
+function dispatchFailureMessage(stage, detail) {
+    const prefix = DISPATCH_FAILURE_PREFIX[stage];
+    return prefix ? `${prefix}: ${detail}` : detail;
+}
+/** Select an existing source without changing thread state. */
+export function resolveMemorySource(profile, deps) {
+    const memory = profile.memory;
+    if (!memory || memory.mode === "Ephemeral")
+        return Optional.empty();
+    if (memory.mode === "Existing thread") {
+        const threadId = memory.threadId;
+        if (typeof threadId === "number" && deps.getThread(threadId))
+            return Optional.of(threadId);
+        deps.warn(`[board] correlation=${deps.correlationId} card ${deps.cardId}: memory thread ${String(threadId)} was not found — using ephemeral memory.`);
+    }
+    return Optional.empty();
+}
+/** Windows drive-letter or POSIX absolute path → usable as a working directory. */
+const looksLikeLocalPath = (s) => /^([A-Za-z]:[\\/]|\/)/.test(s);
+/** Resolve the persisted named profile at dispatch time, never from card type. */
+export function resolveCardForDispatch(db, card) {
+    const namedProfile = getProfile(db, card.profileId);
+    const memory = card.profile.memory;
+    return {
+        ...card,
+        profileId: namedProfile.id,
+        profile: memory?.mode === "Existing thread"
+            ? { ...namedProfile.profile, memory }
+            : namedProfile.profile,
+    };
+}
+/** The provider a resolved card's worker runs on — every rate-limit read must agree with spawn. */
+export function dispatchAgentType(resolvedCard) {
+    return resolvedCard.profile.agentType ?? getAgentType();
+}
+/** Spawn from the profile snapshot resolved by the dispatch guard. */
+export async function spawnCardWorker(deps, resolvedCard, comments) {
+    const { db, telegram, chatId, threadLifecycle } = deps;
+    const spawn = deps.dispatchSpawn ?? dispatchSpawn;
+    const agentType = dispatchAgentType(resolvedCard);
+    const shortTitle = resolvedCard.title.length > 40 ? resolvedCard.title.slice(0, 37) + "…" : resolvedCard.title;
+    const name = `Card #${resolvedCard.cardId} ${shortTitle}`;
+    // 1. Working directory: explicit local repo path on the card wins, else the
+    //    process working directory.
+    const baseDirectory = resolvedCard.profile.repository && looksLikeLocalPath(resolvedCard.profile.repository)
+        ? resolvedCard.profile.repository
+        : process.cwd();
+    // 1b. Spawn isolation: unless the operator opted out, run the worker in a
+    //     dedicated git worktree rooted at the repo so its branch/changes never
+    //     touch the main checkout until merged. If isolation cannot be created,
+    //     do not dispatch: falling back would let the worker mutate the main checkout.
+    let workingDirectory = baseDirectory;
+    let createdWorktree = Optional.empty();
+    if (worktreeEnabled(resolvedCard.profile)) {
+        try {
+            const worktreePath = Optional.fromNullable(await (deps.createCardWorktree ?? createCardWorktree)(baseDirectory, resolvedCard.cardId, resolvedCard.title));
+            if (worktreePath.has()) {
+                workingDirectory = worktreePath.get();
+                createdWorktree = Optional.of(workingDirectory);
+            }
+            else {
+                return {
+                    error: `Worktree isolation required but ${baseDirectory} is not a git work tree`,
+                };
+            }
+        }
+        catch (err) {
+            return { error: `Worktree creation failed: ${errorMessage(err)}` };
+        }
+    }
+    const cleanupWorktreeAfterFailure = async () => {
+        if (createdWorktree.has()) {
+            try {
+                const removal = await (deps.removeWorktreeIfLinked ?? removeWorktreeIfLinked)(createdWorktree);
+                if (removal === "remove-failed") {
+                    await telegram.sendMessage(chatId, `Card worker dispatch failed: worktree ${createdWorktree.get()} could not be removed — clean up manually.`);
+                }
+            }
+            catch (err) {
+                log.warn(`[board] correlation=${resolvedCard.correlationId} failed-dispatch worktree cleanup: ${errorMessage(err)}`);
+            }
+        }
+    };
+    // 2. The shared birth bracket. The board supplies the card bind as the claim, the
+    //    briefing as the required payload, the card as the launch-window owner, the
+    //    worktree removal as the pre-spawn cleanup, and the decommission wiring the
+    //    give-up rung needs — the same wiring releaseWorkerForCard uses, because a
+    //    launch given up IS a release and is torn down by the operator Stop's own path.
+    const birth = await birthWorker({
+        db,
+        telegram,
+        chatId,
+        threadLifecycle,
+        name,
+        topicName: `[Board] ${name}`,
+        aliases: [name],
+        agentType,
+        workingDirectory,
+        badge: BOARD_WORKER_BADGE,
+        // A card worker is stateless: its registry root is itself, and the memory it
+        // bootstraps from is whatever the profile selected — not the same thing.
+        registryRoot: (workerThreadId) => Optional.of(workerThreadId),
+        memorySourceThreadId: resolveMemorySource(resolvedCard.profile, {
+            getThread: (threadId) => getThread(db, threadId),
+            warn: (message) => log.warn(message),
+            correlationId: resolvedCard.correlationId,
+            cardId: resolvedCard.cardId,
+        }),
+        notifyThreadId: Optional.fromNullable(deps.notifyThreadId),
+        payload: Optional.of({
+            render: (workerThreadId) => renderCardBriefing(resolvedCard, comments, workerThreadId),
+            required: true,
+        }),
+        claim: Optional.of((workerThreadId) => deps.bindWorker(workerThreadId)),
+        launchCardId: Optional.of(resolvedCard.cardId),
+        modelOverride: Optional.fromNullable(resolvedCard.profile.model).map((model) => model.trim()),
+        spawn,
+        deleteMailbox: deps.deletePendingTaskMailboxAsync ?? deletePendingTaskMailboxAsync,
+        cleanup: cleanupWorktreeAfterFailure,
+        ...(deps.decommission ? { decommission: deps.decommission } : {}),
+        ...(deps.killWorker ? { killWorker: deps.killWorker } : {}),
+        ...(deps.removeWorktreeIfLinked ? { removeWorktree: deps.removeWorktreeIfLinked } : {}),
+        logPrefix: `[board] correlation=${resolvedCard.correlationId}`,
+    });
+    if ("claimLost" in birth)
+        return { bindLost: true };
+    if ("launchLost" in birth)
+        return { launchLost: true };
+    if ("failed" in birth)
+        return { error: dispatchFailureMessage(birth.failed, birth.detail) };
+    log.info(`[board] correlation=${resolvedCard.correlationId} card ${resolvedCard.cardId} dispatched → worker thread ${birth.workerThreadId} (PID ${birth.pid}, agent ${agentType})`);
+    return { workerThreadId: birth.workerThreadId };
+}
+//# sourceMappingURL=worker-spawn.js.map

package/dist/services/board/worker-spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-spawn.js","sourceRoot":"","sources":["../../../src/services/board/worker-spawn.ts"],"names":[],"mappings":"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"}

package/dist/services/board/worktree.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Board card-worker git-worktree isolation (DD 1.1 §11.3 item 8).
+ *
+ * When a card's execution profile leaves `worktree` unset or true, the
+ * card-worker runs inside a dedicated git worktree instead of the raw repository
+ * directory, so its branch and working changes never touch the operator's main
+ * checkout until merged. The worktree is auto-named `<cardId>-<slug(title)>`,
+ * rooted at the profile repository, and torn down with the worker
+ * (worker-cleanup.service.ts). This is a spawn-time isolation flag, not a
+ * prompt directive — the baseline briefing stays vendor-neutral.
+ */
+import { Optional } from "../../data/optional.js";
+import type { ExecutionProfile } from "../../data/board/board-types.js";
+/** The worktree flag is default-ON per the mockup toggle: only an explicit
+ *  `false` opts out of isolation. */
+export declare function worktreeEnabled(profile: ExecutionProfile): boolean;
+/** Lowercase; every run of non-alphanumeric characters collapses to a single
+ *  dash; leading/trailing dashes are trimmed; capped at MAX_SLUG_LEN (re-trimming
+ *  a dash left at the cut boundary). */
+export declare function slugify(title: string): string;
+/** Immutable card identity used as the worktree directory name. */
+export declare function buildWorktreeName(cardId: number): string;
+/** Inverse of buildWorktreeName: the card a worktree directory belongs to. */
+export declare function worktreeCardId(dir: string): Optional<number>;
+/** Deterministic location of a card's isolated board worktree. */
+export declare function buildCardWorktreePath(cardId: number): string;
+/** True only when `dir` is a board-owned worktree path (under the board
+ *  worktree root). The teardown gate: an operator's own, manually-created
+ *  worktree used as a worker cwd must NEVER be force-removed. */
+export declare function isBoardOwnedWorktreePath(dir: string): boolean;
+export type WorktreeRemovalResult = "removed" | "preserved-dirty" | "absent" | "remove-failed";
+/**
+ * Create (or reset) the card's isolated git worktree rooted at `repo` and return
+ * its path, or null when `repo` is not a git working tree. The branch is force-created at HEAD (`-B`) so a
+ * re-dispatch of the same card gets a clean isolated branch instead of colliding
+ * with a stale one left by a prior run.
+ */
+export declare function createCardWorktree(repo: string, cardId: number, title: string): Promise<string | null>;
+/**
+ * Remove the git worktree a decommissioned worker ran in, given its working
+ * directory. A no-op unless `dir` is a *linked* worktree — never the main
+ * checkout — so it is safe to call for every worker on the shared teardown path.
+ */
+export declare function removeWorktreeIfLinked(dir: Optional<string>): Promise<WorktreeRemovalResult>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/services/board/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../../src/services/board/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAsBxE;qCACqC;AACrC,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAElE;AAED;;wCAEwC;AACxC,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAG5D;AAOD,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iEAEiE;AACjE,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI7D;AAoBD,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,iBAAiB,GAAG,QAAQ,GAAG,eAAe,CAAC;AA0B/F;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAaxB;AAuBD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,GACpB,OAAO,CAAC,qBAAqB,CAAC,CAYhC"}

package/dist/services/board/worktree.js

@@ -0,0 +1,183 @@
+/**
+ * Board card-worker git-worktree isolation (DD 1.1 §11.3 item 8).
+ *
+ * When a card's execution profile leaves `worktree` unset or true, the
+ * card-worker runs inside a dedicated git worktree instead of the raw repository
+ * directory, so its branch and working changes never touch the operator's main
+ * checkout until merged. The worktree is auto-named `<cardId>-<slug(title)>`,
+ * rooted at the profile repository, and torn down with the worker
+ * (worker-cleanup.service.ts). This is a spawn-time isolation flag, not a
+ * prompt directive — the baseline briefing stays vendor-neutral.
+ */
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { dataPath } from "../../lib/paths.js";
+import { log } from "../../lib/logger.js";
+import { errorMessage } from "../../lib/utils.js";
+import { Optional } from "../../data/optional.js";
+const GIT_TIMEOUT_MS = 30_000;
+/** Promisified execFile so git I/O runs off the event loop — a synchronous
+ *  execFileSync would block Node's single thread for the whole command (up to
+ *  GIT_TIMEOUT_MS), stalling the MCP server's polling/delivery on every dispatch
+ *  and teardown. */
+const execFileAsync = promisify(execFile);
+/** Cap the slug so a very long title can't push the worktree path past Windows'
+ *  MAX_PATH (260) and silently disable isolation. */
+const MAX_SLUG_LEN = 60;
+/** Worktrees live under the data dir, not inside the operator's repo, so the
+ *  main checkout is never polluted with nested worktree directories. Resolved
+ *  per call, not at module load, so a `SENSORIUM_BASE_DIR` set by the host
+ *  process is honoured however late this module is imported. */
+function worktreesDir() {
+    return dataPath("board-worktrees");
+}
+/** The worktree flag is default-ON per the mockup toggle: only an explicit
+ *  `false` opts out of isolation. */
+export function worktreeEnabled(profile) {
+    return profile.worktree !== false;
+}
+/** Lowercase; every run of non-alphanumeric characters collapses to a single
+ *  dash; leading/trailing dashes are trimmed; capped at MAX_SLUG_LEN (re-trimming
+ *  a dash left at the cut boundary). */
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, MAX_SLUG_LEN)
+        .replace(/-$/, "");
+}
+/** Immutable card identity used as the worktree directory name. */
+export function buildWorktreeName(cardId) {
+    return `card-${cardId}`;
+}
+/** Inverse of buildWorktreeName: the card a worktree directory belongs to. */
+export function worktreeCardId(dir) {
+    const match = /^card-(\d+)$/.exec(basename(dir));
+    return match ? Optional.of(Number(match[1])) : Optional.empty();
+}
+function buildCardBranchName(cardId, title) {
+    const slug = slugify(title);
+    return slug ? `${cardId}-${slug}` : String(cardId);
+}
+/** Deterministic location of a card's isolated board worktree. */
+export function buildCardWorktreePath(cardId) {
+    return join(worktreesDir(), buildWorktreeName(cardId));
+}
+/** True only when `dir` is a board-owned worktree path (under the board
+ *  worktree root). The teardown gate: an operator's own, manually-created
+ *  worktree used as a worker cwd must NEVER be force-removed. */
+export function isBoardOwnedWorktreePath(dir) {
+    const root = resolve(worktreesDir());
+    const target = resolve(dir);
+    return target === root || target.startsWith(root + sep);
+}
+async function runGit(cwd, args) {
+    const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+        encoding: "utf-8",
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    return stdout;
+}
+/** True when `dir` is inside a git working tree (a worktree can be rooted at it). */
+async function isGitWorkTree(dir) {
+    try {
+        return (await runGit(dir, ["rev-parse", "--is-inside-work-tree"])).trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove a registered clean worktree. A dirty worktree is deliberately retained
+ * so teardown can never discard a worker's uncommitted changes. */
+async function removeWorktreeAt(repo, path) {
+    if (!existsSync(path))
+        return "absent";
+    try {
+        const status = await runGit(path, ["status", "--porcelain"]);
+        if (status.trim())
+            return "preserved-dirty";
+    }
+    catch (err) {
+        // Failing closed protects data in a malformed or partially removed worktree.
+        log.warn(`[board] worktree status ${path} could not be inspected; preserving it: ${errorMessage(err)}`);
+        return "preserved-dirty";
+    }
+    try {
+        await runGit(repo, ["worktree", "remove", path]);
+        return "removed";
+    }
+    catch (err) {
+        if (!existsSync(path))
+            return "absent";
+        log.warn(`[board] worktree remove ${path} (repo ${repo}) failed: ${errorMessage(err)}`);
+        return "remove-failed";
+    }
+}
+/**
+ * Create (or reset) the card's isolated git worktree rooted at `repo` and return
+ * its path, or null when `repo` is not a git working tree. The branch is force-created at HEAD (`-B`) so a
+ * re-dispatch of the same card gets a clean isolated branch instead of colliding
+ * with a stale one left by a prior run.
+ */
+export async function createCardWorktree(repo, cardId, title) {
+    if (!(await isGitWorkTree(repo)))
+        return null;
+    const name = buildCardBranchName(cardId, title);
+    const path = buildCardWorktreePath(cardId);
+    // A stale worktree at this path (prior run whose teardown was skipped) would
+    // make `worktree add` fail — clear it first, unless it contains worker changes.
+    if ((await removeWorktreeAt(repo, path)) === "preserved-dirty") {
+        throw new Error(`previous run left uncommitted changes in the worktree at ${path}; resolve them before re-dispatch`);
+    }
+    await runGit(repo, ["worktree", "add", "--force", "-B", name, path]);
+    return path;
+}
+/** The main checkout a linked worktree belongs to, or null when `dir` is the
+ *  main checkout itself (git-dir === git-common-dir) or not a git dir at all. */
+async function linkedWorktreeMainRepo(dir) {
+    try {
+        const out = await runGit(dir, [
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-dir",
+            "--git-common-dir",
+        ]);
+        const [gitDir, commonDir] = out
+            .trim()
+            .split(/\r?\n/)
+            .map((s) => s.trim());
+        if (!gitDir || !commonDir || gitDir === commonDir)
+            return null;
+        return dirname(commonDir);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove the git worktree a decommissioned worker ran in, given its working
+ * directory. A no-op unless `dir` is a *linked* worktree — never the main
+ * checkout — so it is safe to call for every worker on the shared teardown path.
+ */
+export async function removeWorktreeIfLinked(dir) {
+    if (!dir.has())
+        return "absent";
+    const path = dir.get();
+    if (!existsSync(path))
+        return "absent";
+    // Only ever touch board-owned worktrees. Teardown runs for EVERY worker, and a
+    // worker whose cwd is an operator's own manually-created worktree (outside
+    // the board worktree root) must never be force-removed — that would destroy
+    // their data.
+    if (!isBoardOwnedWorktreePath(path))
+        return "absent";
+    const mainRepo = await linkedWorktreeMainRepo(path);
+    if (!mainRepo)
+        return "absent";
+    return removeWorktreeAt(mainRepo, path);
+}
+//# sourceMappingURL=worktree.js.map

package/dist/services/board/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../../../src/services/board/worktree.ts"],"names":[],"mappings":"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"}

package/dist/services/broker-client.d.ts

@@ -10,9 +10,11 @@
  * Degradation contract (the audited-safe direction, same as the old breakers):
  * every function returns `null` when the broker cannot answer (unreachable,
  * auth-rejected, timeout) and the caller MUST treat null as "cannot confirm
- * → assume alive / kill not performed". Communication is strictly one-way
- * MCP → supervisor.
+ * → assume alive / kill not performed". Communication through this client is
+ * strictly one-way MCP → broker; the supervisor as a whole is not only called
+ * by MCP, because its watchdog and Telegram front-end roles separately call MCP.
  */
+import { Optional } from "../data/optional.js";
 /**
  * How a failed broker call failed — the distinction the spawn contract pivots on:
  *   "no-connection"  the TCP connection was never established (refused, host
@@ -25,6 +27,15 @@
  *                    could create a duplicate and is forbidden.
  */
 export type BrokerFetchFailure = "no-connection" | "uncertain";
+/**
+ * The supervisor's HTTP port, from SUPERVISOR_HTTP_PORT — the ONLY source. The
+ * supervisor exports it to the MCP it launches whenever its endpoint is enabled
+ * (ProcessManager.cs), so an unset or invalid value means no broker is
+ * configured for this process. There is deliberately no default port: a
+ * default made a process started outside the supervisor (a test, a shell)
+ * reach whichever live supervisor happened to own it.
+ */
+export declare function supervisorHttpPort(): Optional<number>;
 export interface BrokerAliveResult {
     alive: boolean;
     pidFound: boolean;
@@ -216,7 +227,78 @@ export declare function brokerGetKeeperState(threadId: number): Promise<BrokerKe
  *  write degrades to today's in-memory behavior, already logged at WARN by the
  *  unreachable path). */
 export declare function brokerSaveKeeperState(state: BrokerKeeperState): Promise<void>;
+/**
+ * One provider's latest usage reading, mirroring the supervisor's `UsageSnapshot`
+ * record. The camelCase field names ARE the frozen `/usage` JSON contract
+ * (spec §A.6) — do not reshape. `agentType` is a plain string (not the AgentType
+ * union) to keep the OCP seam open for future providers.
+ */
+export interface BrokerUsageSnapshot {
+    agentType: string;
+    ok: boolean;
+    utilization5h: number | null;
+    reset5hAt: string | null;
+    utilization7d: number | null;
+    reset7dAt: string | null;
+    overageUtilization: number | null;
+    representativeClaim: string | null;
+    probedAt: string;
+    error: string | null;
+}
+/** One proactive usage window from the additive rate-limit contract. */
+export interface BrokerUsageWindow {
+    kind: string;
+    used_percent: number | null;
+    threshold_percent: number | null;
+    window_minutes: number | null;
+    resets_at: number | null;
+}
+export interface BrokerRateLimitUsage {
+    supported: boolean;
+    active: boolean | null;
+    scope: string | null;
+    resets_at: number | null;
+    raw_reason: string | null;
+}
+export interface BrokerCredits {
+    has_credits: boolean;
+    unlimited: boolean;
+    balance: string | null;
+}
+/** Provider-specific limit state supplied by the supervisor. */
+export interface BrokerProviderUsage {
+    provider: string;
+    captured_at: string;
+    source: string;
+    rate_limited: BrokerRateLimitUsage | null;
+    windows: BrokerUsageWindow[] | null;
+    plan: string | null;
+    credits: BrokerCredits | null;
+}
+/** Additive universal usage contract emitted alongside legacy `sources`. */
+export interface BrokerUsageContract {
+    contract_version: number;
+    providers: BrokerProviderUsage[];
+}
+/** Full `/usage` response, retaining legacy snapshots for existing consumers. */
+export interface BrokerUsageResponse {
+    sources: BrokerUsageSnapshot[];
+    contract: Optional<BrokerUsageContract>;
+}
+/**
+ * Pull the latest per-agentType usage snapshots from the supervisor (one-way IPC:
+ * MCP → supervisor only). Mirrors `brokerGetKeeperState` — base URL, bearer,
+ * timeout, and unreachable-cooldown all come from `brokerFetch`.
+ *
+ * Returns `null` on ANY failure (unreachable, non-OK status, or unparseable body):
+ * null means "cannot confirm", NEVER "usage is zero". Callers must treat null as
+ * "leave the last known state untouched" and never fabricate a zeroed snapshot.
+ * An inert monitor answers `{ "sources": [] }` (200) → an empty array, which is a
+ * confirmed "no sources", distinct from null.
+ */
+export declare function brokerGetUsage(): Promise<BrokerUsageResponse | null>;
 /** Test hook: reset the unreachable-cooldown state. */
 export declare function resetBrokerClientState(): void;
 export declare function brokerSpawnTimeoutForTest(ms: number | null): void;
+export declare function brokerTransportForTest(transport: Optional<typeof fetch>): void;
 //# sourceMappingURL=broker-client.d.ts.map

package/dist/services/broker-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-client.d.ts","sourceRoot":"","sources":["../../src/services/broker-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"broker-client.d.ts","sourceRoot":"","sources":["../../src/services/broker-client.ts"],"names":[],"mappings":"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"}