agentwrangler 0.1.0

package/dist/query/api/hook-config.js

@@ -0,0 +1,75 @@
+/** Runtime configuration for the local context-budget hook. */
+import { isHookInstalled } from "../../hook/install.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+export const DEFAULT_HOOK_CONFIG = {
+    context_window: 200_000,
+    soft_pct: 0.6,
+    hard_pct: 0.8,
+    stale_s: 300,
+    d7_fail_count: 3,
+    d7_window_turns: 10,
+    d9_idle_seconds: 1800,
+};
+const CONFIG_PREFIX = "hook_config.";
+const CONFIG_KEYS = Object.keys(DEFAULT_HOOK_CONFIG);
+function configKey(key) {
+    return `${CONFIG_PREFIX}${key}`;
+}
+function isValidConfig(config) {
+    return (Number.isFinite(config.context_window) &&
+        config.context_window > 0 &&
+        Number.isFinite(config.soft_pct) &&
+        config.soft_pct > 0 &&
+        Number.isFinite(config.hard_pct) &&
+        config.hard_pct > config.soft_pct &&
+        config.hard_pct <= 1 &&
+        Number.isFinite(config.stale_s) &&
+        config.stale_s > 0 &&
+        Number.isInteger(config.d7_fail_count) &&
+        config.d7_fail_count >= 3 &&
+        Number.isInteger(config.d7_window_turns) &&
+        config.d7_window_turns > 0 &&
+        Number.isInteger(config.d9_idle_seconds) &&
+        config.d9_idle_seconds > 0);
+}
+/** Read each dedicated user_config key, degrading corrupt values to defaults. */
+export function readHookConfig(db) {
+    const read = db.prepare("SELECT value FROM user_config WHERE key = ?");
+    const config = { ...DEFAULT_HOOK_CONFIG };
+    for (const key of CONFIG_KEYS) {
+        const row = read.get(configKey(key));
+        if (row?.value === null || row?.value === undefined)
+            continue;
+        const value = Number(row.value);
+        if (Number.isFinite(value))
+            config[key] = value;
+    }
+    return isValidConfig(config) ? config : { ...DEFAULT_HOOK_CONFIG };
+}
+export function getHookConfig() {
+    return buildResponse({ ...readHookConfig(getQueryDb()), installed: isHookInstalled() }, { claim_kind: "N_A", n: 1 });
+}
+/** Validate and atomically persist a partial update to dedicated config keys. */
+export function updateHookConfig(update) {
+    if (update === null || typeof update !== "object" || Array.isArray(update)) {
+        throw new Error("Invalid hook config");
+    }
+    for (const key of Object.keys(update)) {
+        if (!CONFIG_KEYS.includes(key))
+            throw new Error("Invalid hook config key");
+    }
+    const db = getQueryDb();
+    const next = { ...readHookConfig(db), ...update };
+    if (!isValidConfig(next))
+        throw new Error("Invalid hook config");
+    const write = db.prepare(`INSERT INTO user_config (key, value, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`);
+    db.transaction(() => {
+        for (const key of CONFIG_KEYS) {
+            if (update[key] !== undefined)
+                write.run(configKey(key), String(next[key]), new Date().toISOString());
+        }
+    })();
+    return buildResponse(next, { claim_kind: "N_A", n: 1 });
+}

package/dist/query/api/hook-install.js

@@ -0,0 +1,8 @@
+/** Local-only wrappers for the Claude Code hook installer. */
+import { installHook, uninstallHook } from "../../hook/install.js";
+export function installHookRoute() {
+    return installHook();
+}
+export function uninstallHookRoute() {
+    return uninstallHook();
+}

package/dist/query/api/hot-sessions.js

@@ -0,0 +1,17 @@
+import { getQueryDb } from "../db-context.js";
+import { hotSessionsByCost } from "../spend.js";
+import { getSessionSpendPercentile } from "./self-percentiles.js";
+export function getHotSessions(window, limit = 20) {
+    const db = getQueryDb();
+    // One query for the ranked rows, then one cheap percentile lookup per row
+    // (<= limit rows, so no N-per-row HTTP calls). Reuses the per-session query
+    // so the two BM3 surfaces stay identical.
+    return hotSessionsByCost(db, limit, window).map((row) => {
+        const percentile = getSessionSpendPercentile(db, row.session_id);
+        return {
+            ...row,
+            spend_percentile: percentile.percentile,
+            spend_percentile_n: percentile.n,
+        };
+    });
+}

package/dist/query/api/idle-sessions.js

@@ -0,0 +1,52 @@
+/** Fail-open idle background-session measurements for the local dashboard. */
+import { capWeightExprSql, resolveCapReadCoeff } from "../cap-weighted.js";
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { readHookConfig } from "./hook-config.js";
+function response(rows) {
+    return buildResponse(rows, { claim_kind: "OBS_PROXY", n: rows.length });
+}
+/**
+ * Return idle sessions whose reconciled cap-weighted usage is dominated by
+ * sidechain turns. This is display-only metadata: no session control occurs.
+ */
+export function getIdleSessions() {
+    try {
+        const db = getQueryDb();
+        const config = readHookConfig(db);
+        const expr = capWeightExprSql("t", resolveCapReadCoeff(db));
+        const rawRows = db
+            .prepare(`SELECT t.session_id AS session_id,
+                MAX(t.workspace_id) AS workspace_id,
+                MAX(t.ts) AS last_activity_ts,
+                SUM(${expr}) AS cap_weighted_raw
+           FROM turns t
+          WHERE t.provisional = 0
+          GROUP BY t.session_id
+         HAVING SUM(CASE WHEN t.is_sidechain = 1 THEN ${expr} ELSE 0 END)
+                  > SUM(${expr}) / 2`)
+            .all();
+        const now = Date.now();
+        const rows = [];
+        for (const row of rawRows) {
+            const lastActivityMs = Date.parse(row.last_activity_ts);
+            if (!Number.isFinite(lastActivityMs))
+                continue;
+            const idleSeconds = Math.floor(Math.max(0, now - lastActivityMs) / 1_000);
+            if (idleSeconds < config.d9_idle_seconds)
+                continue;
+            rows.push({
+                session_id: row.session_id,
+                workspace_id: row.workspace_id,
+                last_activity_ts: row.last_activity_ts,
+                idle_seconds: idleSeconds,
+                cap_weighted_tokens: Math.round(row.cap_weighted_raw ?? 0),
+                sidechain: true,
+            });
+        }
+        return response(rows);
+    }
+    catch {
+        return response([]);
+    }
+}

package/dist/query/api/index.js

@@ -0,0 +1,40 @@
+/**
+ * src/query/api/index.ts — LocalQueryAPI barrel.
+ *
+ * The stable read seam between the daemon and the SPA.
+ * FROZEN in WP0 — method names and return-type shapes must not change without
+ * a plan decision (changing them breaks WP2/WP3/WP4 concurrently in flight).
+ *
+ * Ownership split (for parallel fan-out per §12):
+ *  - overview.ts: WP2 (getGlobalOverview, listWorkspaces, getWorkspace,
+ *                      listSessions, getSession, getTurnTimeline)
+ *  - settings.ts: WP4 (getSettings, updateSettings)
+ *
+ * The UI never imports sql or better-sqlite3 directly. All data access goes
+ * through this barrel.
+ */
+export { stubResponse, buildResponse } from "../envelope.js";
+export { getGlobalOverview, listWorkspaces, getWorkspace, listSessions, getSession, getTurnTimeline, listLiveSessions, } from "./overview.js";
+export { getSettings, updateSettings, resetDatabase, calibrateLimit, calibrateBytesPerToken, } from "./settings.js";
+export { listRecommendations, getRecommendationCard, dismissRecommendation, adoptRecommendation, deriveActiveGroups, buildSeededPrompt, } from "./recommendations.js";
+export { startApplyJob, getApplyJob, confirmApplyJob, rollbackApplyJob } from "../../apply/jobs.js";
+export { openTerminalForRec } from "../../apply/open-terminal.js";
+export { listLedger } from "./recommendations-ledger.js";
+export { getSuccessRate, listWorkspaceOutcomes, getWorkspaceOutcomeDetail, getLinkageRate, } from "./outcomes.js";
+export { generateWeeklyReport, listReports, getReport } from "./reports.js";
+export { classifyCacheEfficiency, getFlavorDecomposition, getCacheEfficiency, } from "./spend-flavor.js";
+export { getCacheWriteTrend, detectSpikes } from "./trends.js";
+export { getContextComposition } from "./context-composition.js";
+export { getContextBudget } from "./context-budget.js";
+export { getDeliveryMetrics } from "./delivery.js";
+export { computeSessionDelivery, getAbandonedSpendSplit, getClosureProxy, getSessionClosureStatus, } from "./effectiveness.js";
+export { getSessionDrivers } from "./session-drivers.js";
+export { getLoopGuard } from "./loop-guard.js";
+export { getHookConfig, updateHookConfig } from "./hook-config.js";
+export { installHookRoute, uninstallHookRoute } from "./hook-install.js";
+export { getIdleSessions } from "./idle-sessions.js";
+export { getBurnStatus } from "./burn-status.js";
+export { getSelfChurn } from "./self-churn.js";
+export { getOffloadShare } from "./offload-share.js";
+export { getSessionSpendPercentile, getWeeklySelfPercentile } from "./self-percentiles.js";
+export { getCostPerSuccess } from "./cost-per-success.js";

package/dist/query/api/loop-guard.js

@@ -0,0 +1,90 @@
+/** Fail-open D7 repeated-failure circuit breaker for the local hook. */
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { DEFAULT_HOOK_CONFIG, readHookConfig } from "./hook-config.js";
+function response(data) {
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.failing_run_len,
+        drilldown_ids: { session_id: data.session_id },
+    });
+}
+function okGuard(sessionId, reason, failCountThreshold = DEFAULT_HOOK_CONFIG.d7_fail_count, windowTurns = DEFAULT_HOOK_CONFIG.d7_window_turns) {
+    return {
+        stage: "ok",
+        session_id: sessionId,
+        identical_run_len: 0,
+        failing_run_len: 0,
+        fail_count_threshold: failCountThreshold,
+        window_turns: windowTurns,
+        reason,
+        ts: new Date().toISOString(),
+    };
+}
+function isFailingExitClass(exitClass) {
+    return exitClass === "TEST_FAIL" || exitClass === "ERROR";
+}
+/**
+ * Return a bounded, strictly fail-open D7 guard result. The endpoint returns
+ * only measured counts and identifiers; tool input and transcript text remain
+ * outside this query and response.
+ */
+export function getLoopGuard(sessionId) {
+    try {
+        const db = getQueryDb();
+        const config = readHookConfig(db);
+        const events = db
+            .prepare(`SELECT event_id, ts, input_hash, exit_class
+           FROM tool_events INDEXED BY idx_tool_ts_session_event
+          WHERE session_id = ?
+          ORDER BY ts DESC, event_id DESC
+          LIMIT ?`)
+            .all(sessionId, config.d7_window_turns * 8);
+        if (events.length === 0) {
+            const session = db
+                .prepare("SELECT 1 AS present FROM sessions WHERE session_id = ? LIMIT 1")
+                .get(sessionId);
+            return response(okGuard(sessionId, session === undefined ? "unknown_session" : "no_events", config.d7_fail_count, config.d7_window_turns));
+        }
+        if (events.some((event) => !Number.isFinite(Date.parse(event.ts)))) {
+            return response(okGuard(sessionId, "invalid_timestamp", config.d7_fail_count, config.d7_window_turns));
+        }
+        const latest = events[0];
+        if (latest === undefined) {
+            return response(okGuard(sessionId, "no_events", config.d7_fail_count, config.d7_window_turns));
+        }
+        const inputHash = latest.input_hash;
+        const trailingRun = [];
+        if (inputHash !== null) {
+            for (const event of events) {
+                if (event.input_hash !== inputHash)
+                    break;
+                trailingRun.push(event);
+            }
+        }
+        const identicalRunLen = trailingRun.length;
+        const failingRunLen = trailingRun.filter((event) => isFailingExitClass(event.exit_class)).length;
+        const stage = failingRunLen >= config.d7_fail_count
+            ? "block"
+            : failingRunLen >= Math.max(2, config.d7_fail_count - 1)
+                ? "warn"
+                : "ok";
+        return response({
+            stage,
+            session_id: sessionId,
+            identical_run_len: identicalRunLen,
+            failing_run_len: failingRunLen,
+            fail_count_threshold: config.d7_fail_count,
+            window_turns: config.d7_window_turns,
+            reason: stage === "block"
+                ? "repeated_identical_failures"
+                : stage === "warn"
+                    ? "near_repeated_identical_failures"
+                    : "below_threshold",
+            ts: latest.ts,
+        });
+    }
+    catch {
+        return response(okGuard(sessionId, "unavailable"));
+    }
+}

package/dist/query/api/offload-share.js

@@ -0,0 +1,41 @@
+/**
+ * src/query/api/offload-share.ts — query-only L2c subagent offload metrics.
+ *
+ * Offload share uses structural turn counts only; no transcript, tool text,
+ * or paths leave this surface (SEC-101).
+ */
+import { buildResponse } from "../envelope.js";
+/**
+ * Derive subagent offload share for non-provisional turns in [from, to).
+ */
+export function getOffloadShare(db, opts) {
+    const workspaceFilter = opts.workspaceId === null ? "" : " AND workspace_id = ?";
+    const params = opts.workspaceId === null ? [opts.from, opts.to] : [opts.from, opts.to, opts.workspaceId];
+    const totals = db
+        .prepare(`SELECT COUNT(DISTINCT session_id) AS session_count,
+              COUNT(DISTINCT CASE WHEN is_sidechain = 1 THEN session_id END) AS sidechain_session_count,
+              COUNT(*) AS total_turns,
+              COALESCE(SUM(CASE WHEN is_sidechain = 1 THEN 1 ELSE 0 END), 0) AS sidechain_turns
+         FROM turns
+        WHERE ts >= ? AND ts < ? AND provisional = 0${workspaceFilter}`)
+        .get(...params);
+    const data = {
+        ...totals,
+        offload_share: totals.total_turns === 0 ? null : totals.sidechain_turns / totals.total_turns,
+        from: opts.from,
+        to: opts.to,
+        workspace_id: opts.workspaceId,
+    };
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.total_turns,
+        window: { from: opts.from, to: opts.to },
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Within-session subagent offload share: is_sidechain turns / all turns (structural).",
+        },
+        ...(opts.workspaceId === null ? {} : { drilldown_ids: { workspace_id: opts.workspaceId } }),
+    });
+}

package/dist/query/api/outcomes.js

@@ -0,0 +1,218 @@
+/**
+ * src/query/api/outcomes.ts — LocalQueryAPI: outcomes surface.
+ *
+ * Mirrors settings.ts pattern: getQueryDb() + buildResponse + typed payload.
+ *
+ * All responses carry claim_kind:'EXPERIMENTAL' + the 73% methodology
+ * disclosure (plan §3 + §6 Q2). COND-1 gate applied in denominators.
+ *
+ * 73% note: fixed "73% (validation corpus)" methodology disclosure shown
+ * ALONGSIDE the live per-workspace getLinkageRate number — never conflated.
+ *
+ * SQL references: Data Model v2 §2 lines 261-275 / 303-314 / 329-334.
+ */
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+// ---------------------------------------------------------------------------
+// Methodology disclosure (fixed — plan §6 Q2)
+// ---------------------------------------------------------------------------
+const LINKAGE_METHODOLOGY_NOTE = "73% (validation corpus): linkage methodology validated on a sample corpus. " +
+    "Live linkage rate is per-workspace and shown separately in getLinkageRate. " +
+    "All findings are EXPERIMENTAL and excluded from gated denominators (COND-1).";
+// ---------------------------------------------------------------------------
+// Helper: experimental envelope meta
+// ---------------------------------------------------------------------------
+function experimentalMeta(n, from) {
+    const now = new Date().toISOString();
+    return {
+        claim_kind: "EXPERIMENTAL",
+        n,
+        window: { from: from ?? "1970-01-01T00:00:00Z", to: now },
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: LINKAGE_METHODOLOGY_NOTE,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// getSuccessRate
+// ---------------------------------------------------------------------------
+/**
+ * Return the global observed success rate.
+ * Denominator: terminal (non-IN_PROGRESS) work_items with ≥1 session_work_links.
+ * COND-1: findings from EXPERIMENTAL extractors excluded from deferral check.
+ */
+export function getSuccessRate() {
+    const db = getQueryDb();
+    const now = new Date().toISOString();
+    const windowStart = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+    // SQL from Data Model v2 §2 lines 261-275
+    const row = db
+        .prepare(`SELECT
+         COUNT(*) AS terminal_n,
+         AVG(outcome IN ('OBSERVED_SUCCESS','OBSERVED_SUCCESS_WITH_DEFERRALS')) AS success_rate,
+         SUM(outcome = 'OBSERVED_SUCCESS')                AS clean_success_n,
+         SUM(outcome = 'OBSERVED_SUCCESS_WITH_DEFERRALS') AS with_deferrals_n,
+         SUM(outcome IN ('OBSERVED_SUCCESS','OBSERVED_SUCCESS_WITH_DEFERRALS')
+             AND wi.checks_conclusion = 'NONE')           AS no_ci_success_n
+       FROM observed_outcomes o JOIN work_items wi USING (work_item_id)
+       WHERE o.outcome != 'IN_PROGRESS'
+         AND COALESCE(wi.merged_at, wi.closed_at) >= ?
+         AND COALESCE(wi.merged_at, wi.closed_at) <  ?
+         AND EXISTS (SELECT 1 FROM session_work_links l WHERE l.work_item_id = o.work_item_id)`)
+        .get(windowStart, now);
+    // SQL from Data Model v2 §2 lines 329-334
+    const lrRow = db
+        .prepare(`SELECT AVG(EXISTS(SELECT 1 FROM session_work_links l WHERE l.session_id = s.session_id))
+              AS linkage_rate
+       FROM sessions s WHERE s.state='RECONCILED'
+         AND EXISTS (SELECT 1 FROM tool_events te WHERE te.session_id = s.session_id
+                    AND te.tool_name = 'Bash')`)
+        .get();
+    if (row === undefined || row.terminal_n === 0) {
+        const data = {
+            terminal_n: 0,
+            success_rate: null,
+            clean_success_n: 0,
+            with_deferrals_n: 0,
+            no_ci_success_n: 0,
+            linkage_rate: lrRow?.linkage_rate ?? null,
+            methodology_note: LINKAGE_METHODOLOGY_NOTE,
+        };
+        return buildResponse(data, experimentalMeta(0, windowStart));
+    }
+    const data = {
+        terminal_n: row.terminal_n,
+        success_rate: row.success_rate,
+        clean_success_n: row.clean_success_n,
+        with_deferrals_n: row.with_deferrals_n,
+        no_ci_success_n: row.no_ci_success_n,
+        linkage_rate: lrRow?.linkage_rate ?? null,
+        methodology_note: LINKAGE_METHODOLOGY_NOTE,
+    };
+    return buildResponse(data, experimentalMeta(row.terminal_n, windowStart));
+}
+// ---------------------------------------------------------------------------
+// listWorkspaceOutcomes
+// ---------------------------------------------------------------------------
+/**
+ * Return per-workspace outcome summaries.
+ */
+export function listWorkspaceOutcomes() {
+    const db = getQueryDb();
+    const rows = db
+        .prepare(`WITH linked_items AS (
+         SELECT wi.*, o.outcome
+           FROM work_items wi
+           LEFT JOIN observed_outcomes o ON o.work_item_id = wi.work_item_id
+          WHERE EXISTS (
+            SELECT 1 FROM session_work_links l WHERE l.work_item_id = wi.work_item_id
+          )
+       )
+       SELECT w.workspace_id, w.project_slug,
+              COUNT(li.work_item_id) AS total_n,
+              SUM(CASE WHEN li.state = 'OPEN' THEN 1 ELSE 0 END) AS in_progress_n,
+              SUM(CASE WHEN li.state IN ('MERGED', 'CLOSED') THEN 1 ELSE 0 END) AS terminal_n,
+              SUM(CASE WHEN li.outcome IN ('OBSERVED_SUCCESS','OBSERVED_SUCCESS_WITH_DEFERRALS')
+                       THEN 1 ELSE 0 END) AS success_n,
+              SUM(CASE WHEN li.outcome = 'OBSERVED_FAILURE' THEN 1 ELSE 0 END) AS failure_n
+       FROM workspaces w
+       LEFT JOIN linked_items li ON li.workspace_id = w.workspace_id
+       GROUP BY w.workspace_id, w.project_slug
+       ORDER BY w.project_slug, w.workspace_id`)
+        .all();
+    // Compute per-workspace linkage rates
+    const lrRows = db
+        .prepare(`SELECT s.workspace_id,
+              AVG(EXISTS(SELECT 1 FROM session_work_links l WHERE l.session_id = s.session_id))
+              AS linkage_rate
+       FROM sessions s WHERE s.state='RECONCILED'
+         AND EXISTS (SELECT 1 FROM tool_events te WHERE te.session_id = s.session_id
+                    AND te.tool_name = 'Bash')
+       GROUP BY s.workspace_id`)
+        .all();
+    const lrByWs = new Map(lrRows.map((r) => [r.workspace_id, r.linkage_rate]));
+    const adherenceRows = db
+        .prepare(`SELECT workspace_id, COUNT(*) AS n,
+              AVG(CASE WHEN model LIKE '%opus%' THEN 1.0 ELSE 0.0 END) AS premium_share
+         FROM turns
+        WHERE is_sidechain = 0 AND provisional = 0
+        GROUP BY workspace_id`)
+        .all();
+    const adherenceByWs = new Map(adherenceRows.map((r) => [
+        r.workspace_id,
+        r.n > 0 && r.premium_share !== null ? Math.round(100 * (1 - r.premium_share)) : null,
+    ]));
+    const data = rows.map((r) => ({
+        ...r,
+        success_rate: r.terminal_n > 0 ? r.success_n / r.terminal_n : null,
+        linkage_rate: lrByWs.get(r.workspace_id) ?? null,
+        adherence_score: adherenceByWs.get(r.workspace_id) ?? null,
+    }));
+    return buildResponse(data, experimentalMeta(data.length));
+}
+// ---------------------------------------------------------------------------
+// getWorkspaceOutcomeDetail
+// ---------------------------------------------------------------------------
+/**
+ * Return detail for a single work item (findings + linked sessions).
+ */
+export function getWorkspaceOutcomeDetail(workItemId) {
+    const db = getQueryDb();
+    const wi = db
+        .prepare(`SELECT wi.work_item_id, wi.number, wi.state, wi.checks_conclusion,
+              wi.merged_at, wi.closed_at, o.outcome
+       FROM work_items wi
+       LEFT JOIN observed_outcomes o USING (work_item_id)
+       WHERE wi.work_item_id = ?`)
+        .get(workItemId);
+    if (wi === undefined) {
+        return buildResponse(null, experimentalMeta(0));
+    }
+    const findings = db
+        .prepare(`SELECT finding_id, source, severity, status, evidence_ref,
+              raised_at, cleared_at, extractor_version
+       FROM review_findings WHERE work_item_id = ? ORDER BY raised_at`)
+        .all(workItemId);
+    const linkedSessions = db
+        .prepare("SELECT session_id FROM session_work_links WHERE work_item_id = ?")
+        .all(workItemId).map((r) => r.session_id);
+    const data = {
+        ...wi,
+        findings,
+        linked_sessions: linkedSessions,
+    };
+    return buildResponse(data, experimentalMeta(1));
+}
+// ---------------------------------------------------------------------------
+// getLinkageRate
+// ---------------------------------------------------------------------------
+/**
+ * Return the live linkage rate (per §6 Q2: separate from the 73% disclosure).
+ * SQL from Data Model v2 §2 lines 329-334.
+ */
+export function getLinkageRate(workspaceId) {
+    const db = getQueryDb();
+    const whereExtra = workspaceId !== undefined ? " AND s.workspace_id = ?" : "";
+    const params = workspaceId !== undefined ? [workspaceId] : [];
+    const row = db
+        .prepare(`SELECT AVG(EXISTS(SELECT 1 FROM session_work_links l WHERE l.session_id = s.session_id))
+              AS linkage_rate,
+              COUNT(*) AS denominator_n
+       FROM sessions s WHERE s.state='RECONCILED'
+         AND EXISTS (SELECT 1 FROM tool_events te WHERE te.session_id = s.session_id
+                    AND te.tool_name = 'Bash')${whereExtra}`)
+        .get(...params);
+    const data = {
+        linkage_rate: row?.linkage_rate ?? null,
+        denominator_n: row?.denominator_n ?? 0,
+        methodology_note: "Live per-workspace linkage rate. Denominator: RECONCILED sessions with ≥1 Bash tool_event. " +
+            "See also the fixed 73% validation corpus disclosure in getSuccessRate.",
+    };
+    return buildResponse(data, {
+        ...experimentalMeta(data.denominator_n),
+        ...(workspaceId !== undefined ? { drilldown_ids: { workspace_id: workspaceId } } : {}),
+    });
+}