@titan-design/session-analytics 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -110,8 +110,295 @@ interface ReportWindow {
     since: string | null;
     until: string | null;
 }
+/** An arrival that opens a wake episode: a turn-start record or a mid-loop `queued_command` delivery. */
+interface WakeEventRow {
+    key: string;
+    sessionId: string;
+    cause: string;
+    delivery: string;
+    fromName: string | null;
+    /** The same `msg_id` reached more than one session. */
+    broadcast: boolean;
+}
+/** One agent-chat identity: the name a session carries and how it came to carry it. */
+interface AgentNameRow {
+    sessionId: string;
+    agentName: string;
+    originKind: string | null;
+    profile: string | null;
+}
 
-declare const bucketSchema: z.ZodObject<{
+declare const ACTION_CLASSES: readonly ["journal-write", "pr-ci-check", "merge", "dispatch", "retire", "task-state", "budget-status", "scorer", "message", "read-investigate", "text-only", "other"];
+type ActionClass = (typeof ACTION_CLASSES)[number];
+/** One tool call of a request, with the signals session-read extracted for it. */
+interface ActionCall {
+    tool: string;
+    /** Command heads of a Bash call, such as `gh pr checks`. */
+    heads?: readonly string[];
+    readPaths?: readonly string[];
+    writePaths?: readonly string[];
+}
+/** A rule matches a call when every field it sets matches; list order is the precedence. */
+interface ActionRule {
+    cls: ActionClass;
+    tool?: RegExp;
+    head?: RegExp;
+    readPath?: RegExp;
+    writePath?: RegExp;
+}
+declare const DEFAULT_ACTION_RULES: readonly ActionRule[];
+/** Dispatch is judgment about what to hand out, so it stays out of the mechanical list. */
+declare const DEFAULT_MECHANICAL_CLASSES: readonly ActionClass[];
+declare function classifyRequest(calls: readonly ActionCall[], rules?: readonly ActionRule[]): ActionClass;
+
+/** A dispatch or a send; with any file write, the first such request ends a session's boot. */
+declare const BOOT_TOOL: RegExp;
+/** The charter's `teleport_k` and `retire_k` at the time of the TP-499 plan; callers pass their own. */
+declare const DEFAULT_CONFIGURED_K: readonly number[];
+declare const DEFAULT_K_SWEEP: {
+    readonly fromK: 20000;
+    readonly toK: 1000000;
+    readonly stepK: 5000;
+};
+declare const DEFAULT_REVIEWER_ROLE = "worker:reviewer";
+declare const DEFAULT_STANDING_ROLE = "worker:standing_peer";
+declare const DEFAULT_REVIEWER_PRS = 10;
+/** The broker logs this when a seat starts handing over; `from` is the outgoing agent id. */
+declare const TELEPORT_EVENT = "teleport_started";
+declare const sweepResultSchema: z.ZodObject<{
+    bestK: z.ZodNullable<z.ZodNumber>;
+    bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+    atConfigured: z.ZodArray<z.ZodObject<{
+        k: z.ZodNumber;
+        costPerRequest: z.ZodNullable<z.ZodNumber>;
+        deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const paramsSchema: z.ZodObject<{
+    bootCostUsd: z.ZodNumber;
+    bootFill: z.ZodNumber;
+    growthPerRequest: z.ZodNumber;
+    readPricePerMTok: z.ZodNumber;
+}, z.core.$strip>;
+declare const sessionSchema: z.ZodObject<{
+    bootCostUsd: z.ZodNumber;
+    bootFill: z.ZodNumber;
+    growthPerRequest: z.ZodNumber;
+    readPricePerMTok: z.ZodNumber;
+    sessionId: z.ZodString;
+    role: z.ZodString;
+    model: z.ZodString;
+    requests: z.ZodNumber;
+    bootRequests: z.ZodNumber;
+    exitFill: z.ZodNumber;
+    lastTs: z.ZodString;
+    bestK: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+declare const cohortSchema: z.ZodObject<{
+    bootCostUsd: z.ZodNumber;
+    bootFill: z.ZodNumber;
+    growthPerRequest: z.ZodNumber;
+    readPricePerMTok: z.ZodNumber;
+    halfBoot: z.ZodObject<{
+        bestK: z.ZodNullable<z.ZodNumber>;
+        bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+        atConfigured: z.ZodArray<z.ZodObject<{
+            k: z.ZodNumber;
+            costPerRequest: z.ZodNullable<z.ZodNumber>;
+            deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    bestK: z.ZodNullable<z.ZodNumber>;
+    bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+    atConfigured: z.ZodArray<z.ZodObject<{
+        k: z.ZodNumber;
+        costPerRequest: z.ZodNullable<z.ZodNumber>;
+        deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    role: z.ZodString;
+    model: z.ZodString;
+    sessions: z.ZodNumber;
+}, z.core.$strip>;
+declare const teleportSchema: z.ZodObject<{
+    ts: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    sessionId: z.ZodString;
+    role: z.ZodString;
+    model: z.ZodString;
+    exitFill: z.ZodNumber;
+    bestK: z.ZodNullable<z.ZodNumber>;
+    overConfigured: z.ZodArray<z.ZodObject<{
+        k: z.ZodNumber;
+        over: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `requestsFrom` when the report has no reviewer session at all, so requests per PR is 0. */
+declare const POOLED_REVIEWERS = "pooled";
+declare const reviewerSchema: z.ZodObject<{
+    prs: z.ZodNumber;
+    fresh: z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        model: z.ZodString;
+        sessions: z.ZodNumber;
+        requestsPerPr: z.ZodNumber;
+        requestsFrom: z.ZodString;
+        requestsFromSessions: z.ZodNumber;
+        costUsd: z.ZodNumber;
+    }, z.core.$strip>>;
+    standing: z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        model: z.ZodString;
+        sessions: z.ZodNumber;
+        requestsPerPr: z.ZodNumber;
+        requestsFrom: z.ZodString;
+        requestsFromSessions: z.ZodNumber;
+        costUsd: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const handoffThresholdSchema: z.ZodObject<{
+    configuredK: z.ZodArray<z.ZodNumber>;
+    sweep: z.ZodObject<{
+        fromK: z.ZodNumber;
+        toK: z.ZodNumber;
+        stepK: z.ZodNumber;
+    }, z.core.$strip>;
+    cohorts: z.ZodArray<z.ZodObject<{
+        bootCostUsd: z.ZodNumber;
+        bootFill: z.ZodNumber;
+        growthPerRequest: z.ZodNumber;
+        readPricePerMTok: z.ZodNumber;
+        halfBoot: z.ZodObject<{
+            bestK: z.ZodNullable<z.ZodNumber>;
+            bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+            atConfigured: z.ZodArray<z.ZodObject<{
+                k: z.ZodNumber;
+                costPerRequest: z.ZodNullable<z.ZodNumber>;
+                deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        bestK: z.ZodNullable<z.ZodNumber>;
+        bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+        atConfigured: z.ZodArray<z.ZodObject<{
+            k: z.ZodNumber;
+            costPerRequest: z.ZodNullable<z.ZodNumber>;
+            deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        role: z.ZodString;
+        model: z.ZodString;
+        sessions: z.ZodNumber;
+    }, z.core.$strip>>;
+    sessions: z.ZodArray<z.ZodObject<{
+        bootCostUsd: z.ZodNumber;
+        bootFill: z.ZodNumber;
+        growthPerRequest: z.ZodNumber;
+        readPricePerMTok: z.ZodNumber;
+        sessionId: z.ZodString;
+        role: z.ZodString;
+        model: z.ZodString;
+        requests: z.ZodNumber;
+        bootRequests: z.ZodNumber;
+        exitFill: z.ZodNumber;
+        lastTs: z.ZodString;
+        bestK: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    unbootedSessions: z.ZodNumber;
+    teleports: z.ZodArray<z.ZodObject<{
+        ts: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        sessionId: z.ZodString;
+        role: z.ZodString;
+        model: z.ZodString;
+        exitFill: z.ZodNumber;
+        bestK: z.ZodNullable<z.ZodNumber>;
+        overConfigured: z.ZodArray<z.ZodObject<{
+            k: z.ZodNumber;
+            over: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    unmatchedTeleports: z.ZodNumber;
+    reviewers: z.ZodObject<{
+        prs: z.ZodNumber;
+        fresh: z.ZodArray<z.ZodObject<{
+            role: z.ZodString;
+            model: z.ZodString;
+            sessions: z.ZodNumber;
+            requestsPerPr: z.ZodNumber;
+            requestsFrom: z.ZodString;
+            requestsFromSessions: z.ZodNumber;
+            costUsd: z.ZodNumber;
+        }, z.core.$strip>>;
+        standing: z.ZodArray<z.ZodObject<{
+            role: z.ZodString;
+            model: z.ZodString;
+            sessions: z.ZodNumber;
+            requestsPerPr: z.ZodNumber;
+            requestsFrom: z.ZodString;
+            requestsFromSessions: z.ZodNumber;
+            costUsd: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type HandoffThreshold = z.infer<typeof handoffThresholdSchema>;
+type HandoffCohort = z.infer<typeof cohortSchema>;
+type HandoffSession = z.infer<typeof sessionSchema>;
+type HandoffTeleport = z.infer<typeof teleportSchema>;
+type ReviewerComparison = z.infer<typeof reviewerSchema>;
+type CycleParams = z.infer<typeof paramsSchema>;
+type KSweep = HandoffThreshold["sweep"];
+/** One main-thread request as the handoff model needs it. */
+interface HandoffRequestRow {
+    sessionId: string;
+    role: string;
+    model: string;
+    ts: string;
+    /** Tokens in context: input, cache reads and cache writes. */
+    fill: number;
+    tokens: RequestTokens;
+    bootAction: boolean;
+}
+interface TeleportEvent {
+    ts: string;
+    name: string | null;
+    fromAgentId: string;
+}
+interface HandoffOptions {
+    configuredK?: readonly number[];
+    sweep?: KSweep;
+    reviewerRole?: string;
+    /** The role whose boot, fill and growth price a reviewer that stays up across PRs. */
+    standingRole?: string;
+    reviewerPrs?: number;
+    /** Prices every request and the read rate; the package table, not the graph's stored one. */
+    prices?: readonly PriceRow[];
+}
+declare function isBootAction(calls: readonly ActionCall[]): boolean;
+/** Broker log lines to teleport starts; any other line, or one that is not JSON, is skipped. */
+declare function parseTeleportEvents(lines: Iterable<string>): TeleportEvent[];
+/** One cycle boots to f0 and grows g per request up to K: boot/n + read price x mean fill, with n = (K - f0) / g. */
+declare function costPerRequest(params: CycleParams, k: number): number | null;
+/** The cheapest K on the sweep grid, then each configured K against it. */
+declare function sweepK(params: CycleParams, sweep: KSweep, configuredK: readonly number[]): z.infer<typeof sweepResultSchema>;
+/** Per role and model: boot cost and fill, fill growth and read price from the requests, then the K sweep. */
+declare function handoffThreshold(rows: readonly HandoffRequestRow[], teleports: readonly TeleportEvent[], agentSessions: ReadonlyMap<string, readonly string[]>, options?: HandoffOptions): HandoffThreshold;
+
+/**
+ * Narrows a report to some sessions. Every field left out matches all, and fields combine with AND.
+ * Compactions and coverage stay window-wide: the graph does not key them to a request.
+ */
+interface ReportScope {
+    sessionIds?: readonly string[];
+    /** Keeps sessions whose agent-chat agent name starts with it. */
+    agentPrefix?: string;
+    /** Report roles, as `byRole` names them. */
+    roles?: readonly string[];
+}
+/** A predicate over a request's session and role; with no scope every request passes. */
+declare function scopeFilter(db: Db, scope?: ReportScope): (row: {
+    sessionId: string;
+    role: string;
+}) => boolean;
+
+declare const bucketSchema$1: z.ZodObject<{
     key: z.ZodString;
     requests: z.ZodNumber;
     sessions: z.ZodNumber;
@@ -139,11 +426,11 @@ declare const costReportSchema: z.ZodObject<{
     }, z.core.$strip>;
     byTokenClass: z.ZodArray<z.ZodObject<{
         tokenClass: z.ZodEnum<{
+            output: "output";
             input: "input";
             cache_read: "cache_read";
             cache_write_5m: "cache_write_5m";
             cache_write_1h: "cache_write_1h";
-            output: "output";
         }>;
         tokens: z.ZodNumber;
         costUsd: z.ZodNumber;
@@ -172,6 +459,38 @@ declare const costReportSchema: z.ZodObject<{
         sessions: z.ZodNumber;
         costUsd: z.ZodNumber;
     }, z.core.$strip>>;
+    byAction: z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        buckets: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            requests: z.ZodNumber;
+            sessions: z.ZodNumber;
+            costUsd: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    mechanicalShare: z.ZodObject<{
+        classes: z.ZodArray<z.ZodEnum<{
+            "journal-write": "journal-write";
+            "pr-ci-check": "pr-ci-check";
+            merge: "merge";
+            dispatch: "dispatch";
+            retire: "retire";
+            "task-state": "task-state";
+            "budget-status": "budget-status";
+            scorer: "scorer";
+            message: "message";
+            "read-investigate": "read-investigate";
+            "text-only": "text-only";
+            other: "other";
+        }>>;
+        costUsd: z.ZodNumber;
+        share: z.ZodNumber;
+        byRole: z.ZodArray<z.ZodObject<{
+            role: z.ZodString;
+            costUsd: z.ZodNumber;
+            share: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     byEpisodeCount: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         requests: z.ZodNumber;
@@ -206,6 +525,156 @@ declare const costReportSchema: z.ZodObject<{
             midLoopCostUsd: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    wakeEpisodes: z.ZodObject<{
+        unattributed: z.ZodObject<{
+            requests: z.ZodNumber;
+            costUsd: z.ZodNumber;
+        }, z.core.$strip>;
+        byCause: z.ZodArray<z.ZodObject<{
+            midLoopEpisodes: z.ZodNumber;
+            requestsPerEpisode: z.ZodNumber;
+            costPerEpisode: z.ZodNumber;
+            byFrom: z.ZodArray<z.ZodObject<{
+                episodes: z.ZodNumber;
+                requests: z.ZodNumber;
+                costUsd: z.ZodNumber;
+                noActionEpisodes: z.ZodNumber;
+                noActionCostUsd: z.ZodNumber;
+                key: z.ZodEnum<{
+                    broadcast: "broadcast";
+                    seat: "seat";
+                    agent: "agent";
+                    broker: "broker";
+                    none: "none";
+                }>;
+            }, z.core.$strip>>;
+            episodes: z.ZodNumber;
+            requests: z.ZodNumber;
+            costUsd: z.ZodNumber;
+            noActionEpisodes: z.ZodNumber;
+            noActionCostUsd: z.ZodNumber;
+            key: z.ZodString;
+        }, z.core.$strip>>;
+        pairs: z.ZodArray<z.ZodObject<{
+            episodes: z.ZodNumber;
+            requests: z.ZodNumber;
+            costUsd: z.ZodNumber;
+            noActionEpisodes: z.ZodNumber;
+            noActionCostUsd: z.ZodNumber;
+            from: z.ZodString;
+            fromKind: z.ZodEnum<{
+                broadcast: "broadcast";
+                seat: "seat";
+                agent: "agent";
+                broker: "broker";
+                none: "none";
+            }>;
+            to: z.ZodString;
+        }, z.core.$strip>>;
+        episodes: z.ZodNumber;
+        requests: z.ZodNumber;
+        costUsd: z.ZodNumber;
+        noActionEpisodes: z.ZodNumber;
+        noActionCostUsd: z.ZodNumber;
+        roles: z.ZodArray<z.ZodString>;
+        noActionClasses: z.ZodArray<z.ZodEnum<{
+            "journal-write": "journal-write";
+            "pr-ci-check": "pr-ci-check";
+            merge: "merge";
+            dispatch: "dispatch";
+            retire: "retire";
+            "task-state": "task-state";
+            "budget-status": "budget-status";
+            scorer: "scorer";
+            message: "message";
+            "read-investigate": "read-investigate";
+            "text-only": "text-only";
+            other: "other";
+        }>>;
+    }, z.core.$strip>;
+    handoffThreshold: z.ZodObject<{
+        configuredK: z.ZodArray<z.ZodNumber>;
+        sweep: z.ZodObject<{
+            fromK: z.ZodNumber;
+            toK: z.ZodNumber;
+            stepK: z.ZodNumber;
+        }, z.core.$strip>;
+        cohorts: z.ZodArray<z.ZodObject<{
+            bootCostUsd: z.ZodNumber;
+            bootFill: z.ZodNumber;
+            growthPerRequest: z.ZodNumber;
+            readPricePerMTok: z.ZodNumber;
+            halfBoot: z.ZodObject<{
+                bestK: z.ZodNullable<z.ZodNumber>;
+                bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+                atConfigured: z.ZodArray<z.ZodObject<{
+                    k: z.ZodNumber;
+                    costPerRequest: z.ZodNullable<z.ZodNumber>;
+                    deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            bestK: z.ZodNullable<z.ZodNumber>;
+            bestCostPerRequest: z.ZodNullable<z.ZodNumber>;
+            atConfigured: z.ZodArray<z.ZodObject<{
+                k: z.ZodNumber;
+                costPerRequest: z.ZodNullable<z.ZodNumber>;
+                deltaPerRequest: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+            role: z.ZodString;
+            model: z.ZodString;
+            sessions: z.ZodNumber;
+        }, z.core.$strip>>;
+        sessions: z.ZodArray<z.ZodObject<{
+            bootCostUsd: z.ZodNumber;
+            bootFill: z.ZodNumber;
+            growthPerRequest: z.ZodNumber;
+            readPricePerMTok: z.ZodNumber;
+            sessionId: z.ZodString;
+            role: z.ZodString;
+            model: z.ZodString;
+            requests: z.ZodNumber;
+            bootRequests: z.ZodNumber;
+            exitFill: z.ZodNumber;
+            lastTs: z.ZodString;
+            bestK: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        unbootedSessions: z.ZodNumber;
+        teleports: z.ZodArray<z.ZodObject<{
+            ts: z.ZodString;
+            name: z.ZodNullable<z.ZodString>;
+            sessionId: z.ZodString;
+            role: z.ZodString;
+            model: z.ZodString;
+            exitFill: z.ZodNumber;
+            bestK: z.ZodNullable<z.ZodNumber>;
+            overConfigured: z.ZodArray<z.ZodObject<{
+                k: z.ZodNumber;
+                over: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        unmatchedTeleports: z.ZodNumber;
+        reviewers: z.ZodObject<{
+            prs: z.ZodNumber;
+            fresh: z.ZodArray<z.ZodObject<{
+                role: z.ZodString;
+                model: z.ZodString;
+                sessions: z.ZodNumber;
+                requestsPerPr: z.ZodNumber;
+                requestsFrom: z.ZodString;
+                requestsFromSessions: z.ZodNumber;
+                costUsd: z.ZodNumber;
+            }, z.core.$strip>>;
+            standing: z.ZodArray<z.ZodObject<{
+                role: z.ZodString;
+                model: z.ZodString;
+                sessions: z.ZodNumber;
+                requestsPerPr: z.ZodNumber;
+                requestsFrom: z.ZodString;
+                requestsFromSessions: z.ZodNumber;
+                costUsd: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
     wakeCauseByGapBand: z.ZodArray<z.ZodObject<{
         wakeCause: z.ZodString;
         gapBand: z.ZodString;
@@ -250,9 +719,11 @@ declare const costReportSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 type CostReport = z.infer<typeof costReportSchema>;
-type CostBucket = z.infer<typeof bucketSchema>;
+type CostBucket = z.infer<typeof bucketSchema$1>;
 type WakeCauseBucket = CostReport["byWakeCause"][number];
 type WakeGapCell = z.infer<typeof cellSchema>;
+type RoleActions = CostReport["byAction"][number];
+type MechanicalShare = CostReport["mechanicalShare"];
 interface CostReportOptions {
     /** ISO timestamp or date, inclusive. Overrides `days`. */
     since?: string;
@@ -267,10 +738,172 @@ interface CostReportOptions {
     transcriptsDiscovered?: number;
     /** The extraction version an audit facet must reach to count as current. */
     facetVersion?: number;
+    /** Action rules in precedence order; seat-specific rules belong in the caller's config. */
+    actionRules?: readonly ActionRule[];
+    /** Action classes counted as mechanical in `mechanicalShare`. */
+    mechanicalClasses?: readonly ActionClass[];
+    /** Report roles whose wakes `wakeEpisodes` cuts into episodes. */
+    episodeRoles?: readonly string[];
+    /** A wake is no-action when every one of its requests falls in these action classes. */
+    noActionClasses?: readonly ActionClass[];
+    /** The broker log's lines, read by the caller; its teleport starts give each handoff's exit fill. */
+    brokerLogLines?: () => Iterable<string>;
+    handoff?: HandoffOptions;
+    /** Narrows every request-keyed field to some sessions; absent means all. */
+    scope?: ReportScope;
 }
 /** Reads the graph and never writes it, so a read-only connection is enough. */
 declare function costReport(db: Db, options?: CostReportOptions): CostReport;
 
+/** The tool calls each request in the window issued, keyed by `request_id`; a request with none is absent. */
+declare function readRequestToolCalls(db: Db, window: ReportWindow): Map<string, ActionCall[]>;
+
+declare const WAKE_FROM_KINDS: readonly ["seat", "agent", "broadcast", "broker", "none"];
+type WakeFromKind = (typeof WAKE_FROM_KINDS)[number];
+/** Report roles whose wakes are cut into episodes: a human coordinator and a spawned coordinator seat. */
+declare const DEFAULT_EPISODE_ROLES: readonly string[];
+/** A wake whose requests only read, answer in text, or call tools no rule names changed nothing outside the session. */
+declare const DEFAULT_NO_ACTION_CLASSES: readonly ActionClass[];
+declare const AGENT_LIFECYCLE = "agent_lifecycle";
+declare const causeSchema: z.ZodObject<{
+    midLoopEpisodes: z.ZodNumber;
+    requestsPerEpisode: z.ZodNumber;
+    costPerEpisode: z.ZodNumber;
+    byFrom: z.ZodArray<z.ZodObject<{
+        episodes: z.ZodNumber;
+        requests: z.ZodNumber;
+        costUsd: z.ZodNumber;
+        noActionEpisodes: z.ZodNumber;
+        noActionCostUsd: z.ZodNumber;
+        key: z.ZodEnum<{
+            broadcast: "broadcast";
+            seat: "seat";
+            agent: "agent";
+            broker: "broker";
+            none: "none";
+        }>;
+    }, z.core.$strip>>;
+    episodes: z.ZodNumber;
+    requests: z.ZodNumber;
+    costUsd: z.ZodNumber;
+    noActionEpisodes: z.ZodNumber;
+    noActionCostUsd: z.ZodNumber;
+    key: z.ZodString;
+}, z.core.$strip>;
+declare const pairSchema: z.ZodObject<{
+    episodes: z.ZodNumber;
+    requests: z.ZodNumber;
+    costUsd: z.ZodNumber;
+    noActionEpisodes: z.ZodNumber;
+    noActionCostUsd: z.ZodNumber;
+    from: z.ZodString;
+    fromKind: z.ZodEnum<{
+        broadcast: "broadcast";
+        seat: "seat";
+        agent: "agent";
+        broker: "broker";
+        none: "none";
+    }>;
+    to: z.ZodString;
+}, z.core.$strip>;
+declare const wakeEpisodesSchema: z.ZodObject<{
+    unattributed: z.ZodObject<{
+        requests: z.ZodNumber;
+        costUsd: z.ZodNumber;
+    }, z.core.$strip>;
+    byCause: z.ZodArray<z.ZodObject<{
+        midLoopEpisodes: z.ZodNumber;
+        requestsPerEpisode: z.ZodNumber;
+        costPerEpisode: z.ZodNumber;
+        byFrom: z.ZodArray<z.ZodObject<{
+            episodes: z.ZodNumber;
+            requests: z.ZodNumber;
+            costUsd: z.ZodNumber;
+            noActionEpisodes: z.ZodNumber;
+            noActionCostUsd: z.ZodNumber;
+            key: z.ZodEnum<{
+                broadcast: "broadcast";
+                seat: "seat";
+                agent: "agent";
+                broker: "broker";
+                none: "none";
+            }>;
+        }, z.core.$strip>>;
+        episodes: z.ZodNumber;
+        requests: z.ZodNumber;
+        costUsd: z.ZodNumber;
+        noActionEpisodes: z.ZodNumber;
+        noActionCostUsd: z.ZodNumber;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    pairs: z.ZodArray<z.ZodObject<{
+        episodes: z.ZodNumber;
+        requests: z.ZodNumber;
+        costUsd: z.ZodNumber;
+        noActionEpisodes: z.ZodNumber;
+        noActionCostUsd: z.ZodNumber;
+        from: z.ZodString;
+        fromKind: z.ZodEnum<{
+            broadcast: "broadcast";
+            seat: "seat";
+            agent: "agent";
+            broker: "broker";
+            none: "none";
+        }>;
+        to: z.ZodString;
+    }, z.core.$strip>>;
+    episodes: z.ZodNumber;
+    requests: z.ZodNumber;
+    costUsd: z.ZodNumber;
+    noActionEpisodes: z.ZodNumber;
+    noActionCostUsd: z.ZodNumber;
+    roles: z.ZodArray<z.ZodString>;
+    noActionClasses: z.ZodArray<z.ZodEnum<{
+        "journal-write": "journal-write";
+        "pr-ci-check": "pr-ci-check";
+        merge: "merge";
+        dispatch: "dispatch";
+        retire: "retire";
+        "task-state": "task-state";
+        "budget-status": "budget-status";
+        scorer: "scorer";
+        message: "message";
+        "read-investigate": "read-investigate";
+        "text-only": "text-only";
+        other: "other";
+    }>>;
+}, z.core.$strip>;
+type WakeEpisodes = z.infer<typeof wakeEpisodesSchema>;
+type WakeCauseEpisodes = z.infer<typeof causeSchema>;
+type WakePair = z.infer<typeof pairSchema>;
+/** One request as the episode view needs it. */
+interface EpisodeRequestRow {
+    costUsd: number;
+    action: ActionClass;
+    eventKey: string | null;
+}
+interface WakeEpisode {
+    key: string;
+    cause: string;
+    midLoop: boolean;
+    fromKind: WakeFromKind;
+    from: string;
+    to: string;
+    requests: number;
+    costUsd: number;
+    noAction: boolean;
+}
+interface EpisodeNames {
+    seats: ReadonlySet<string>;
+    /** Each receiving session's agent-chat name. */
+    receivers: ReadonlyMap<string, string>;
+}
+/** A seat is a name some top-level session carries, or one a coordinator profile was spawned under. */
+declare function episodeNames(rows: readonly AgentNameRow[]): EpisodeNames;
+/** Each event with the requests that followed it, flagged no-action when every request's class is listed. */
+declare function buildWakeEpisodes(events: readonly WakeEventRow[], requests: readonly EpisodeRequestRow[], names: EpisodeNames, noActionClasses: readonly ActionClass[]): WakeEpisode[];
+declare function summarizeWakeEpisodes(episodes: readonly WakeEpisode[], requests: readonly EpisodeRequestRow[], roles: readonly string[], noActionClasses: readonly ActionClass[]): WakeEpisodes;
+
 /** Two rule sets on purpose (design section 18): workers segment by assignment, coordinators by work phase. */
 type Heuristic = "worker-v1" | "coordinator-v1";
 declare const HEURISTIC_VERSIONS: Readonly<Record<Heuristic, number>>;
@@ -343,5 +976,684 @@ declare function sessionRole(classification: SessionClassification, worker: Work
 declare const LIST_PRICE_CAVEAT = "List prices, not a bill: the accounts behind these sessions may run on subscription plans. Rankings hold; the absolute figure is not what you paid.";
 /** The same report as plain-text tables, one section per report field, caveat and footer last. */
 declare function renderCostReportText(report: CostReport): string;
+/** The report's sections a caller may render alone, keyed by the field each one shows. */
+declare const COST_REPORT_SECTIONS: {
+    readonly byRole: (report: CostReport) => string;
+    readonly byAction: (report: CostReport) => string;
+    readonly mechanicalShare: (report: CostReport) => string;
+    readonly byWakeCause: (report: CostReport) => string;
+    readonly wakeEpisodes: (report: CostReport) => string;
+    readonly wakePairs: (report: CostReport) => string;
+    readonly handoff: (report: CostReport) => string;
+    readonly teleports: (report: CostReport) => string;
+    readonly reviewers: (report: CostReport) => string;
+};
+type CostReportSection = keyof typeof COST_REPORT_SECTIONS;
+/** Some sections of the report under its header, with the caveat and footer last as in the full text. */
+declare function renderCostReportSections(report: CostReport, sections: readonly CostReportSection[]): string;
+
+/** Gap bands past a 5-minute TTL: the next request finds the cache gone. */
+declare const REBUILD_GAP_BANDS: readonly string[];
+/** One request as the TTL what-if needs it. */
+interface TtlRequestRow {
+    sessionId: string;
+    role: string;
+    profile: string;
+    model: string;
+    ts: string;
+    cacheReadTokens: number;
+    cacheWrite1hTokens: number;
+    /** Milliseconds since the session's previous request; null for its first. */
+    gapMs: number | null;
+}
+declare const bucketSchema: z.ZodObject<{
+    fiveMinuteLoses: z.ZodBoolean;
+    sessions: z.ZodNumber;
+    requests: z.ZodNumber;
+    write1hTokens: z.ZodNumber;
+    repriceSavingUsd: z.ZodNumber;
+    rebuilds: z.ZodNumber;
+    rebuildTokens: z.ZodNumber;
+    rebuildCostUsd: z.ZodNumber;
+    netSavingUsd: z.ZodNumber;
+    netPerSessionUsd: z.ZodNumber;
+    key: z.ZodString;
+}, z.core.$strip>;
+declare const cacheTtlWhatIfSchema: z.ZodObject<{
+    window: z.ZodOptional<z.ZodObject<{
+        since: z.ZodNullable<z.ZodString>;
+        until: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    priceTableVersion: z.ZodNumber;
+    rebuildGapBands: z.ZodArray<z.ZodString>;
+    totals: z.ZodObject<{
+        sessions: z.ZodNumber;
+        requests: z.ZodNumber;
+        write1hTokens: z.ZodNumber;
+        repriceSavingUsd: z.ZodNumber;
+        rebuilds: z.ZodNumber;
+        rebuildTokens: z.ZodNumber;
+        rebuildCostUsd: z.ZodNumber;
+        netSavingUsd: z.ZodNumber;
+        netPerSessionUsd: z.ZodNumber;
+    }, z.core.$strip>;
+    unpricedRequests: z.ZodNumber;
+    byRole: z.ZodArray<z.ZodObject<{
+        fiveMinuteLoses: z.ZodBoolean;
+        sessions: z.ZodNumber;
+        requests: z.ZodNumber;
+        write1hTokens: z.ZodNumber;
+        repriceSavingUsd: z.ZodNumber;
+        rebuilds: z.ZodNumber;
+        rebuildTokens: z.ZodNumber;
+        rebuildCostUsd: z.ZodNumber;
+        netSavingUsd: z.ZodNumber;
+        netPerSessionUsd: z.ZodNumber;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    byProfile: z.ZodArray<z.ZodObject<{
+        fiveMinuteLoses: z.ZodBoolean;
+        sessions: z.ZodNumber;
+        requests: z.ZodNumber;
+        write1hTokens: z.ZodNumber;
+        repriceSavingUsd: z.ZodNumber;
+        rebuilds: z.ZodNumber;
+        rebuildTokens: z.ZodNumber;
+        rebuildCostUsd: z.ZodNumber;
+        netSavingUsd: z.ZodNumber;
+        netPerSessionUsd: z.ZodNumber;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    lossRoles: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type CacheTtlWhatIf = z.infer<typeof cacheTtlWhatIfSchema>;
+type CacheTtlBucket = z.infer<typeof bucketSchema>;
+/** Q3: what each role and profile would have paid with `CLAUDE_CODE_PROMPT_CACHE_TTL=5m` instead of 1h. */
+declare function cacheTtlWhatIf(rows: readonly TtlRequestRow[], prices?: readonly PriceRow[]): CacheTtlWhatIf;
+/** Reads the graph and never writes it; roles are the cost report's. */
+declare function cacheTtlReport(db: Db, options?: CostReportOptions, prices?: readonly PriceRow[]): CacheTtlWhatIf;
+declare function readTtlRows(db: Db, window: ReportWindow): TtlRequestRow[];
+/** One table per dimension; a role or profile 5m would cost money is marked `loss`. */
+declare function renderCacheTtlText(whatIf: CacheTtlWhatIf): string;
+
+/** One reviewer verdict message, as agent-chat's events table records it. */
+interface VerdictRecord {
+    eventId: number;
+    at: string;
+    /** The seat the verdict was sent to. */
+    seat: string;
+    reviewer: string;
+    verdict: string;
+    repo: string;
+    pr: number;
+    head: string;
+}
+/** A PR as GitHub REST reports it at the time of the run. */
+interface PullState {
+    repo: string;
+    pr: number;
+    state: "open" | "closed";
+    mergedAt: string | null;
+    headSha: string;
+}
+type ParsedVerdict = Pick<VerdictRecord, "verdict" | "repo" | "pr" | "head">;
+/** Reads a `Verdict:` message's first three lines; null when any of them is missing. */
+declare function parseVerdict(body: string): ParsedVerdict | null;
+type MergeStatus = "merged" | "open" | "stale-head" | "closed" | "unknown";
+/** A PR holding at least one MERGE verdict, resolved against its GitHub state at `asOf`. */
+interface MergeOutcome {
+    repo: string;
+    pr: number;
+    status: MergeStatus;
+    /** The first MERGE verdict at the PR's final head; null when no verdict names that head. */
+    verdict: VerdictRecord | null;
+    /** Verdict to merge for merged PRs; verdict to `asOf` (a censored age) for open ones. */
+    minutes: number | null;
+}
+declare function mergeOutcomes(verdicts: readonly VerdictRecord[], pulls: readonly PullState[], asOf: string): MergeOutcome[];
+declare function prKey(row: {
+    repo: string;
+    pr: number;
+}): string;
+declare const latencyStatsSchema: z.ZodObject<{
+    merged: z.ZodNumber;
+    medianMin: z.ZodNullable<z.ZodNumber>;
+    meanMin: z.ZodNullable<z.ZodNumber>;
+    p90Min: z.ZodNullable<z.ZodNumber>;
+    maxMin: z.ZodNullable<z.ZodNumber>;
+    censored: z.ZodNumber;
+    oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+    censoredPrMinutes: z.ZodNumber;
+    medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+type LatencyStats = z.infer<typeof latencyStatsSchema>;
+declare function latencyStats(outcomes: readonly MergeOutcome[]): LatencyStats;
+
+/** One action the auto-mode classifier refused, read from a seat's transcript. */
+interface DenialRecord {
+    seat: string;
+    at: string;
+    /** The classifier's bracketed reason, such as "Merge Without Review". */
+    reason: string;
+    /** What the refused call was doing, from its tool input; the reason label alone is loose. */
+    action: string;
+    tool: string;
+    /** The refused call's id; a forked or resumed transcript repeats it, so it is counted once. */
+    toolUseId?: string;
+}
+/** Classifies a refused call by what it did; MCP tools keep their own short name. */
+declare function classifyDeniedAction(tool: string, input: unknown): string;
+/** Scans transcript JSONL for classifier refusals and joins each to the tool call it refused. */
+declare function parseDenials(lines: Iterable<string>, seat: string): DenialRecord[];
+/** One denial per refused call; a record without a tool_use_id cannot be matched and is kept. */
+declare function dedupeDenials(denials: readonly DenialRecord[]): DenialRecord[];
+
+/** A seat journal line that states its implementer slot count, and why it did not fill a free slot. */
+interface SlotTick {
+    seat: string;
+    at: string;
+    used: number;
+    cap: number;
+    reason: string;
+    /** The journal line number, so a row can be checked against its source. */
+    line: number;
+}
+interface SeatJournal {
+    ticks: SlotTick[];
+    /** The journal's last timestamped line; the final tick holds until then. */
+    lastAt: string | null;
+}
+declare const UNSTATED_REASON = "unstated";
+/** A tick's count holds at most this long, so a dark seat is not read as an hour of idle slots. */
+declare const TICK_HOLD_MAX_MIN = 60;
+/**
+ * Reads `HH:MM[:SS] ...` journal lines for the date the journal covers.
+ * `utcOffsetMin` is the journal clock's offset east of UTC, such as -360 for UTC-6.
+ */
+declare function parseSeatJournal(text: string, seat: string, date: string, utcOffsetMin: number): SeatJournal;
+interface IdleSlotRow {
+    seat: string;
+    reason: string;
+    slotMinutes: number;
+    ticks: number;
+    /** Journal line numbers of the ticks counted here. */
+    lines: number[];
+}
+/** Free implementer slots times the minutes each tick's count held, clipped to the window. */
+declare function idleSlotMinutes(journals: readonly SeatJournal[], window: {
+    since?: string;
+    until?: string;
+}): IdleSlotRow[];
+
+/** Where each section's numbers come from: the command that re-reads them and the field it reads. */
+declare const BLOCKED_FLOW_SOURCES: {
+    readonly verdicts: {
+        readonly command: "sqlite3 -readonly <events.db> \"SELECT id, ts, target, body FROM events WHERE kind='message' AND body LIKE 'Verdict:%'\"";
+        readonly field: "events.ts, events.target, events.body lines Verdict:, PR:, Head:";
+    };
+    readonly pulls: {
+        readonly command: "gh api repos/<owner>/<repo>/pulls/<n>";
+        readonly field: ".state, .merged_at, .head.sha";
+    };
+    readonly denials: {
+        readonly command: "grep 'auto mode classifier. Reason: \\[' <seat transcript>.jsonl";
+        readonly field: "tool_result.content Reason: [<class>], joined to tool_use.input by tool_use_id";
+    };
+    readonly journals: {
+        readonly command: "grep -nE 'impl [0-9]+/[0-9]+' <seat journal>.md";
+        readonly field: "impl <used>/<cap>, No dispatch: <reason>";
+    };
+};
+type BlockedFlowSource = keyof typeof BLOCKED_FLOW_SOURCES;
+interface BlockedFlowInput {
+    verdicts: readonly VerdictRecord[];
+    pulls: readonly PullState[];
+    denials: readonly DenialRecord[];
+    journals: readonly SeatJournal[];
+    /** Waits are measured to here; a PR merged later counts as open. */
+    asOf: string;
+    window?: {
+        since?: string;
+        until?: string;
+    };
+    /** Splits verdict-to-merge by verdict time, such as the moment a seat was granted merge authority. */
+    splitAt?: string;
+    /** Keeps only verdicts sent to, and denials and journals of, these seats. */
+    seats?: readonly string[];
+}
+declare const latencyRowSchema: z.ZodObject<{
+    repo: z.ZodString;
+    prs: z.ZodNumber;
+    staleHead: z.ZodNumber;
+    closed: z.ZodNumber;
+    unknown: z.ZodNumber;
+    all: z.ZodObject<{
+        merged: z.ZodNumber;
+        medianMin: z.ZodNullable<z.ZodNumber>;
+        meanMin: z.ZodNullable<z.ZodNumber>;
+        p90Min: z.ZodNullable<z.ZodNumber>;
+        maxMin: z.ZodNullable<z.ZodNumber>;
+        censored: z.ZodNumber;
+        oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+        censoredPrMinutes: z.ZodNumber;
+        medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    before: z.ZodOptional<z.ZodObject<{
+        merged: z.ZodNumber;
+        medianMin: z.ZodNullable<z.ZodNumber>;
+        meanMin: z.ZodNullable<z.ZodNumber>;
+        p90Min: z.ZodNullable<z.ZodNumber>;
+        maxMin: z.ZodNullable<z.ZodNumber>;
+        censored: z.ZodNumber;
+        oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+        censoredPrMinutes: z.ZodNumber;
+        medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    after: z.ZodOptional<z.ZodObject<{
+        merged: z.ZodNumber;
+        medianMin: z.ZodNullable<z.ZodNumber>;
+        meanMin: z.ZodNullable<z.ZodNumber>;
+        p90Min: z.ZodNullable<z.ZodNumber>;
+        maxMin: z.ZodNullable<z.ZodNumber>;
+        censored: z.ZodNumber;
+        oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+        censoredPrMinutes: z.ZodNumber;
+        medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const blockedFlowSchema: z.ZodObject<{
+    asOf: z.ZodString;
+    window: z.ZodObject<{
+        since: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    splitAt: z.ZodOptional<z.ZodString>;
+    sources: z.ZodRecord<z.ZodEnum<{
+        verdicts: "verdicts";
+        pulls: "pulls";
+        denials: "denials";
+        journals: "journals";
+    }>, z.ZodObject<{
+        command: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strip>>;
+    verdictToMerge: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            verdicts: "verdicts";
+            pulls: "pulls";
+            denials: "denials";
+            journals: "journals";
+        }>>;
+        rows: z.ZodArray<z.ZodObject<{
+            repo: z.ZodString;
+            prs: z.ZodNumber;
+            staleHead: z.ZodNumber;
+            closed: z.ZodNumber;
+            unknown: z.ZodNumber;
+            all: z.ZodObject<{
+                merged: z.ZodNumber;
+                medianMin: z.ZodNullable<z.ZodNumber>;
+                meanMin: z.ZodNullable<z.ZodNumber>;
+                p90Min: z.ZodNullable<z.ZodNumber>;
+                maxMin: z.ZodNullable<z.ZodNumber>;
+                censored: z.ZodNumber;
+                oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+                censoredPrMinutes: z.ZodNumber;
+                medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            before: z.ZodOptional<z.ZodObject<{
+                merged: z.ZodNumber;
+                medianMin: z.ZodNullable<z.ZodNumber>;
+                meanMin: z.ZodNullable<z.ZodNumber>;
+                p90Min: z.ZodNullable<z.ZodNumber>;
+                maxMin: z.ZodNullable<z.ZodNumber>;
+                censored: z.ZodNumber;
+                oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+                censoredPrMinutes: z.ZodNumber;
+                medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+            after: z.ZodOptional<z.ZodObject<{
+                merged: z.ZodNumber;
+                medianMin: z.ZodNullable<z.ZodNumber>;
+                meanMin: z.ZodNullable<z.ZodNumber>;
+                p90Min: z.ZodNullable<z.ZodNumber>;
+                maxMin: z.ZodNullable<z.ZodNumber>;
+                censored: z.ZodNumber;
+                oldestCensoredMin: z.ZodNullable<z.ZodNumber>;
+                censoredPrMinutes: z.ZodNumber;
+                medianWithCensoredMin: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    openHoldingMerge: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            verdicts: "verdicts";
+            pulls: "pulls";
+            denials: "denials";
+            journals: "journals";
+        }>>;
+        prMinutes: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            repo: z.ZodString;
+            pr: z.ZodNumber;
+            head: z.ZodString;
+            seat: z.ZodString;
+            verdictAt: z.ZodString;
+            ageMin: z.ZodNumber;
+            eventId: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    denials: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            verdicts: "verdicts";
+            pulls: "pulls";
+            denials: "denials";
+            journals: "journals";
+        }>>;
+        total: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            reason: z.ZodString;
+            action: z.ZodString;
+            seat: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    idleSlots: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            verdicts: "verdicts";
+            pulls: "pulls";
+            denials: "denials";
+            journals: "journals";
+        }>>;
+        holdMaxMin: z.ZodNumber;
+        total: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            seat: z.ZodString;
+            reason: z.ZodString;
+            slotMinutes: z.ZodNumber;
+            ticks: z.ZodNumber;
+            lines: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type BlockedFlowReport = z.infer<typeof blockedFlowSchema>;
+type LatencyRow = z.infer<typeof latencyRowSchema>;
+declare const ALL_REPOS = "all";
+/** Per repo: verdict-to-merge waits, PRs still holding MERGE, classifier denials and idle implementer slots. */
+declare function blockedFlowReport(input: BlockedFlowInput): BlockedFlowReport;
+/** Each table's title names the JSON field its numbers come from; the sources close the report. */
+declare function renderBlockedFlowText(report: BlockedFlowReport): string;
+
+/** One agent-chat broker.log entry and the 1-based line it came from, so each finding can cite it. */
+interface BrokerEntry {
+    line: number;
+    ts: string;
+    event: string;
+    fields: Record<string, unknown>;
+}
+/** Broker log lines to entries; a line that is not a JSON object with `ts` and `event` is skipped but still counted. */
+declare function parseBrokerLog(lines: Iterable<string>): BrokerEntry[];
+
+/**
+ * How a route missed a recipient: `failed` is a `delivered:false` the broker dropped, `partial` reached
+ * others but not this name, and `queued` is a `delivered:false` the broker kept for later delivery.
+ */
+type RouteMissKind = "failed" | "partial" | "queued";
+/** One recipient a routed message did not reach when it was sent. */
+interface RouteMiss {
+    line: number;
+    at: string;
+    recipient: string;
+    from: string;
+    kind: string;
+    miss: RouteMissKind;
+}
+interface RouteFailureRow {
+    recipient: string;
+    failed: number;
+    partial: number;
+    queued: number;
+    first: string;
+    last: string;
+    lines: number[];
+}
+/** Each recipient named in `to` that a route did not reach. */
+declare function routeMisses(entries: readonly BrokerEntry[]): RouteMiss[];
+/** Misses grouped by recipient, most first. */
+declare function routeFailureRows(misses: readonly RouteMiss[]): RouteFailureRow[];
+declare function countMisses(misses: readonly RouteMiss[]): Record<RouteMissKind, number>;
+
+/** A seat off the broker for longer than this is dark; a teleport hand-off takes seconds. */
+declare const DARK_MIN = 5;
+/** A name deregistered from the broker until it registered again, or until asOf if it never did, without exiting in between. */
+interface DarkGap {
+    seat: string;
+    from: string;
+    to: string | null;
+    minutes: number;
+    /** A teleport of this name started after its last registration and before the gap closed. */
+    teleport: boolean;
+    /** Routes to the seat during the gap logged `delivered:false` and dropped. */
+    failedRoutes: number;
+    /** Routes during the gap that reached other recipients but not the seat. */
+    partialRoutes: number;
+    /** Routes the broker held or queued in the seat's inbox for delivery when it returned. */
+    queuedRoutes: number;
+    /** The deregistered and registered lines, then any teleport lines. */
+    lines: number[];
+    routeLines: number[];
+}
+/** Gaps longer than DARK_MIN, skipping a clean exit and later resume; one still open at asOf counts only if a route missed the seat in it. */
+declare function darkGaps(entries: readonly BrokerEntry[], misses: readonly RouteMiss[], asOf: string): DarkGap[];
+
+/** An `agent_spawned` row of agent-chat's events table: the agent id and the profile it ran under. */
+interface SpawnRecord {
+    eventId: number;
+    agentId: string;
+    name: string;
+    profile: string | null;
+}
+/** An agent the broker saw exit without reporting to its spawner. */
+interface UnreportedExit {
+    at: string;
+    line: number;
+    agentId: string;
+    name: string;
+    spawner: string;
+    lastAction: string;
+    /** The `agent_spawned` row the profile came from, or null when none matched the agent id. */
+    spawnEventId: number | null;
+}
+interface UnreportedExitRow {
+    profile: string;
+    count: number;
+    exits: UnreportedExit[];
+}
+declare const UNKNOWN_PROFILE = "unknown";
+/** Broker `unreported-exit` lines grouped by the profile the agent was spawned with, most first. */
+declare function unreportedExitRows(entries: readonly BrokerEntry[], spawns: readonly SpawnRecord[]): UnreportedExitRow[];
+
+/** A prompt this old with nothing after it from the agent is a hang, not a pause for the owner. */
+declare const PROMPT_STALE_MIN = 10;
+/** The newest events-table row an actor wrote before asOf. */
+interface LastEventRecord {
+    eventId: number;
+    at: string;
+    actor: string;
+    kind: string;
+    /** `meta.tool_name` of an approval request. */
+    tool: string | null;
+    /** A `resolution` row whose `ref` is this request's msg_id, written before asOf. */
+    resolutionEventId: number | null;
+    /** An `agent_exited` or `agent_retired` row for this actor after the request and before asOf. */
+    endEventId: number | null;
+}
+interface StalePromptRow {
+    agent: string;
+    at: string;
+    ageMin: number;
+    tool: string | null;
+    eventId: number;
+    resolutionEventId: number | null;
+}
+/** Live agents whose last event is an approval request older than PROMPT_STALE_MIN, oldest first; resolved ones included. */
+declare function stalePromptRows(lastEvents: readonly LastEventRecord[], broker: readonly BrokerEntry[], asOf: string): StalePromptRow[];
+
+/** Where each section's findings come from: the command that re-reads them and the field it reads. */
+declare const LIVENESS_SOURCES: {
+    readonly registrations: {
+        readonly command: "grep -nE '\"event\":\"(registered|deregistered|agent_exited|teleport_started|teleport_completed|teleport_failed|teleport_aborted)\"' <broker.log>";
+        readonly field: "ts, event, name; cited as broker.log line numbers; a gap with a clean agent_exited (code 0, not inferred) and no teleport is a resume";
+    };
+    readonly routes: {
+        readonly command: "grep -n '\"event\":\"route\"' <broker.log>";
+        readonly field: "to, delivered, recipients";
+    };
+    readonly exits: {
+        readonly command: "grep -n '\"event\":\"unreported-exit\"' <broker.log>";
+        readonly field: "agentId, name, spawner, lastAction";
+    };
+    readonly spawns: {
+        readonly command: "sqlite3 -readonly <events.db> \"SELECT id, msg_id, target, json_extract(meta,'$.profile') FROM events WHERE kind='agent_spawned'\"";
+        readonly field: "events.msg_id (agent id), events.meta.profile";
+    };
+    readonly prompts: {
+        readonly command: "sqlite3 -readonly <events.db> \"SELECT e.* FROM events e JOIN (SELECT actor, max(id) id FROM events WHERE ts < <asOf> AND kind != 'resolution' GROUP BY actor) l ON e.id = l.id WHERE e.kind='approval_request'\"";
+        readonly field: "events.ts, events.actor, events.meta.tool_name; a resolution row's events.ref; skipped after the actor's agent_exited or agent_retired, or a broker_started it never re-registered after";
+    };
+};
+type LivenessSource = keyof typeof LIVENESS_SOURCES;
+interface LivenessInput {
+    broker: readonly BrokerEntry[];
+    spawns: readonly SpawnRecord[];
+    lastEvents: readonly LastEventRecord[];
+    /** Gaps still open and prompt ages are measured to here; later entries are ignored. */
+    asOf: string;
+    /** A finding is kept when it starts inside the window; a prompt from a live agent still unanswered at asOf is kept however old. */
+    window?: {
+        since?: string;
+        until?: string;
+    };
+    /** Keeps only findings about these names: the dark seat, route recipient, exiting agent or its spawner, prompting agent. */
+    seats?: readonly string[];
+}
+declare const livenessSchema: z.ZodObject<{
+    asOf: z.ZodString;
+    window: z.ZodObject<{
+        since: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    thresholds: z.ZodObject<{
+        darkMin: z.ZodNumber;
+        promptStaleMin: z.ZodNumber;
+    }, z.core.$strip>;
+    sources: z.ZodRecord<z.ZodEnum<{
+        exits: "exits";
+        registrations: "registrations";
+        routes: "routes";
+        spawns: "spawns";
+        prompts: "prompts";
+    }>, z.ZodObject<{
+        command: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strip>>;
+    darkSeats: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        withTeleport: z.ZodNumber;
+        withoutTeleport: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            seat: z.ZodString;
+            from: z.ZodString;
+            to: z.ZodNullable<z.ZodString>;
+            minutes: z.ZodNumber;
+            teleport: z.ZodBoolean;
+            failedRoutes: z.ZodNumber;
+            partialRoutes: z.ZodNumber;
+            queuedRoutes: z.ZodNumber;
+            lines: z.ZodArray<z.ZodNumber>;
+            routeLines: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    routeFailures: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        failed: z.ZodNumber;
+        partial: z.ZodNumber;
+        queued: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            recipient: z.ZodString;
+            failed: z.ZodNumber;
+            partial: z.ZodNumber;
+            queued: z.ZodNumber;
+            first: z.ZodString;
+            last: z.ZodString;
+            lines: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    unreportedExits: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        total: z.ZodNumber;
+        rows: z.ZodArray<z.ZodObject<{
+            profile: z.ZodString;
+            count: z.ZodNumber;
+            exits: z.ZodArray<z.ZodObject<{
+                at: z.ZodString;
+                line: z.ZodNumber;
+                agentId: z.ZodString;
+                name: z.ZodString;
+                spawner: z.ZodString;
+                lastAction: z.ZodString;
+                spawnEventId: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    stalePrompts: z.ZodObject<{
+        cites: z.ZodArray<z.ZodEnum<{
+            exits: "exits";
+            registrations: "registrations";
+            routes: "routes";
+            spawns: "spawns";
+            prompts: "prompts";
+        }>>;
+        rows: z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            at: z.ZodString;
+            ageMin: z.ZodNumber;
+            tool: z.ZodNullable<z.ZodString>;
+            eventId: z.ZodNumber;
+            resolutionEventId: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        resolvedRows: z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            at: z.ZodString;
+            ageMin: z.ZodNumber;
+            tool: z.ZodNullable<z.ZodString>;
+            eventId: z.ZodNumber;
+            resolutionEventId: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type LivenessReport = z.infer<typeof livenessSchema>;
+/** Seats dark past DARK_MIN, routes that missed their recipient, unreported exits and agents stuck on a prompt. */
+declare function livenessReport(input: LivenessInput): LivenessReport;
+/** Each table's title names the JSON field its rows come from; the sources and the shared caveat close the report. */
+declare function renderLivenessText(report: LivenessReport): string;
 
-export { type Band, CHANNEL_CLUSTER_MS, CONTEXT_BANDS, CONTEXT_RESET_TOKENS, COORDINATOR_MERGE_DEDUPE_REQUESTS, COORDINATOR_MIN_EPISODE_REQUESTS, COORDINATOR_WAVE_QUIET_REQUESTS, type CostBucket, type CostReport, type CostReportOptions, type EpisodeInbound, type EpisodeInput, type EpisodeRequest, type EpisodeSignal, GAP_BANDS, HEURISTIC_VERSIONS, type Heuristic, type HumanRole, IDLE_GAP_MS, LIST_PRICE_CAVEAT, PRICE_TABLE, PRICE_TABLE_VERSION, PROFILE_ROLES, type PriceRow, type PricedRequest, type ReportWindow, type RequestTokens, STANDING_PEER_MIN_ASSIGNMENTS, STANDING_PEER_MIN_HOURS, type SessionClass, type SessionClassification, type SessionFacts, type SessionOrigin, TOKEN_CLASSES, type TaskInitiative, type TokenClass, type WakeCauseBucket, type WakeGapCell, type WorkerFacts, type WorkerRole, type WrittenEpisodes, assignmentCount, bandOf, buildEpisodes, classifySession, contextBand, costReport, costReportSchema, findPrice, gapBand, heuristicFor, initiativeFromCwd, priceRequest, readEpisodeInput, renderCostReportText, roleFromProfile, sessionInitiative, sessionRole, workerRole, writeEpisodes };
+export { ACTION_CLASSES, AGENT_LIFECYCLE, ALL_REPOS, type ActionCall, type ActionClass, type ActionRule, type AgentNameRow, BLOCKED_FLOW_SOURCES, BOOT_TOOL, type Band, type BlockedFlowInput, type BlockedFlowReport, type BlockedFlowSource, type BrokerEntry, CHANNEL_CLUSTER_MS, CONTEXT_BANDS, CONTEXT_RESET_TOKENS, COORDINATOR_MERGE_DEDUPE_REQUESTS, COORDINATOR_MIN_EPISODE_REQUESTS, COORDINATOR_WAVE_QUIET_REQUESTS, COST_REPORT_SECTIONS, type CacheTtlBucket, type CacheTtlWhatIf, type CostBucket, type CostReport, type CostReportOptions, type CostReportSection, type CycleParams, DARK_MIN, DEFAULT_ACTION_RULES, DEFAULT_CONFIGURED_K, DEFAULT_EPISODE_ROLES, DEFAULT_K_SWEEP, DEFAULT_MECHANICAL_CLASSES, DEFAULT_NO_ACTION_CLASSES, DEFAULT_REVIEWER_PRS, DEFAULT_REVIEWER_ROLE, DEFAULT_STANDING_ROLE, type DarkGap, type DenialRecord, type EpisodeInbound, type EpisodeInput, type EpisodeNames, type EpisodeRequest, type EpisodeRequestRow, type EpisodeSignal, GAP_BANDS, HEURISTIC_VERSIONS, type HandoffCohort, type HandoffOptions, type HandoffRequestRow, type HandoffSession, type HandoffTeleport, type HandoffThreshold, type Heuristic, type HumanRole, IDLE_GAP_MS, type IdleSlotRow, type KSweep, LIST_PRICE_CAVEAT, LIVENESS_SOURCES, type LastEventRecord, type LatencyRow, type LatencyStats, type LivenessInput, type LivenessReport, type LivenessSource, type MechanicalShare, type MergeOutcome, type MergeStatus, POOLED_REVIEWERS, PRICE_TABLE, PRICE_TABLE_VERSION, PROFILE_ROLES, PROMPT_STALE_MIN, type ParsedVerdict, type PriceRow, type PricedRequest, type PullState, REBUILD_GAP_BANDS, type ReportScope, type ReportWindow, type RequestTokens, type ReviewerComparison, type RoleActions, type RouteFailureRow, type RouteMiss, type RouteMissKind, STANDING_PEER_MIN_ASSIGNMENTS, STANDING_PEER_MIN_HOURS, type SeatJournal, type SessionClass, type SessionClassification, type SessionFacts, type SessionOrigin, type SlotTick, type SpawnRecord, type StalePromptRow, TELEPORT_EVENT, TICK_HOLD_MAX_MIN, TOKEN_CLASSES, type TaskInitiative, type TeleportEvent, type TokenClass, type TtlRequestRow, UNKNOWN_PROFILE, UNSTATED_REASON, type UnreportedExit, type UnreportedExitRow, type VerdictRecord, WAKE_FROM_KINDS, type WakeCauseBucket, type WakeCauseEpisodes, type WakeEpisode, type WakeEpisodes, type WakeEventRow, type WakeFromKind, type WakeGapCell, type WakePair, type WorkerFacts, type WorkerRole, type WrittenEpisodes, assignmentCount, bandOf, blockedFlowReport, blockedFlowSchema, buildEpisodes, buildWakeEpisodes, cacheTtlReport, cacheTtlWhatIf, cacheTtlWhatIfSchema, classifyDeniedAction, classifyRequest, classifySession, contextBand, costPerRequest, costReport, costReportSchema, countMisses, darkGaps, dedupeDenials, episodeNames, findPrice, gapBand, handoffThreshold, handoffThresholdSchema, heuristicFor, idleSlotMinutes, initiativeFromCwd, isBootAction, latencyStats, latencyStatsSchema, livenessReport, livenessSchema, mergeOutcomes, parseBrokerLog, parseDenials, parseSeatJournal, parseTeleportEvents, parseVerdict, prKey, priceRequest, readEpisodeInput, readRequestToolCalls, readTtlRows, renderBlockedFlowText, renderCacheTtlText, renderCostReportSections, renderCostReportText, renderLivenessText, roleFromProfile, routeFailureRows, routeMisses, scopeFilter, sessionInitiative, sessionRole, stalePromptRows, summarizeWakeEpisodes, sweepK, unreportedExitRows, wakeEpisodesSchema, workerRole, writeEpisodes };