@jmtrin/opencode-kevin 1.1.0 → 1.2.0

package/dist/plugin/TuiSnapshots.js

@@ -0,0 +1,158 @@
+// v1.2.0 (K12-003 / plan §4.2, D12-05) — snapshot flush (pure serialization + atomic write).
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const CAP_BYTES = 512 * 1024;
+const SNAP_FILES = [
+    "proposals.json",
+    "conflicts.json",
+    "health.json",
+    "meta.json",
+];
+function byteLen(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+function atomicWrite(target, content) {
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, target);
+}
+function truncateProposals(proposals, cap) {
+    // Estimate JSON overhead without diffs to compute available budget.
+    // We truncate diff fields proportionally to fit cap.
+    const serialized = JSON.stringify(proposals);
+    if (byteLen(serialized) <= cap)
+        return proposals;
+    // Compute total diff length
+    const totalDiff = proposals.reduce((acc, p) => acc + byteLen(p.diff), 0);
+    if (totalDiff === 0)
+        return proposals;
+    const overhead = byteLen(serialized) - totalDiff;
+    const budget = Math.max(0, cap - overhead - 1024); // leave margin
+    // Distribute budget proportionally
+    const out = [];
+    for (let i = 0; i < proposals.length; i++) {
+        const p = proposals[i];
+        const diffBytes = byteLen(p.diff);
+        const share = Math.floor((diffBytes / totalDiff) * budget);
+        // Ensure at least 100 bytes per entry if possible, else share
+        const sliceBytes = Math.min(diffBytes, Math.max(share, 100));
+        // Slice diff by bytes approximated via string length; diff is ascii mostly
+        // so byte length ~ char length. Use char slice.
+        const approxChars = Math.floor((sliceBytes / Math.max(diffBytes, 1)) * p.diff.length);
+        const truncatedDiff = p.diff.slice(0, Math.max(0, approxChars));
+        const needsTrunc = truncatedDiff.length < p.diff.length;
+        out.push({
+            ...p,
+            diff: needsTrunc ? `${truncatedDiff}\n…[truncated]` : p.diff,
+            truncated: needsTrunc ? true : p.truncated,
+        });
+    }
+    // If still over cap after proportional truncation, iteratively trim more
+    let result = out;
+    let ser = JSON.stringify(result);
+    let iter = 0;
+    while (byteLen(ser) > cap && iter < 5) {
+        result = result.map((p) => {
+            if (!p.diff || p.diff.length < 200)
+                return p;
+            const half = Math.floor(p.diff.length / 2);
+            return {
+                ...p,
+                diff: `${p.diff.slice(0, half)}\n…[truncated]`,
+                truncated: true,
+            };
+        });
+        ser = JSON.stringify(result);
+        iter++;
+    }
+    return result;
+}
+export function flushSnapshots(input) {
+    const { root, proposals, conflicts, health, metrics, version } = input;
+    const dir = join(root, "tui");
+    mkdirSync(dir, { recursive: true });
+    const generatedAt = new Date().toISOString();
+    const written = [];
+    const skipped = [];
+    // Proposals — cap with truncation
+    let propToWrite = proposals;
+    let propJson = JSON.stringify(propToWrite, null, 2);
+    if (byteLen(propJson) > CAP_BYTES) {
+        propToWrite = truncateProposals(proposals, CAP_BYTES - 1024);
+        propJson = JSON.stringify(propToWrite, null, 2);
+        if (byteLen(propJson) > CAP_BYTES) {
+            // Still over after truncation: truncate further by dropping diffs entirely
+            const minimal = propToWrite.map((p) => ({
+                ...p,
+                diff: `${p.diff.slice(0, 500)}\n…[truncated]`,
+                truncated: true,
+            }));
+            propJson = JSON.stringify(minimal, null, 2);
+        }
+    }
+    atomicWrite(join(dir, "proposals.json"), propJson);
+    written.push("proposals.json");
+    // Conflicts
+    let conflictsJson = JSON.stringify(conflicts, null, 2);
+    if (byteLen(conflictsJson) > CAP_BYTES) {
+        // Truncate summaries if needed
+        const truncated = conflicts.map((c) => ({
+            ...c,
+            a_summary: c.a_summary.slice(0, 500),
+            b_summary: c.b_summary.slice(0, 500),
+        }));
+        conflictsJson = JSON.stringify(truncated, null, 2);
+    }
+    atomicWrite(join(dir, "conflicts.json"), conflictsJson);
+    written.push("conflicts.json");
+    // Health
+    let healthJson = JSON.stringify(health, null, 2);
+    if (byteLen(healthJson) > CAP_BYTES) {
+        // Health should never exceed cap, but truncate counters if it does
+        const truncatedHealth = {
+            ...health,
+            counters: {},
+        };
+        healthJson = JSON.stringify(truncatedHealth, null, 2);
+    }
+    atomicWrite(join(dir, "health.json"), healthJson);
+    written.push("health.json");
+    // Meta
+    const meta = {
+        generatedAt,
+        version: version ?? "1.2.0",
+        files: SNAP_FILES.slice(0, 3),
+    };
+    atomicWrite(join(dir, "meta.json"), JSON.stringify(meta, null, 2));
+    written.push("meta.json");
+    if (metrics) {
+        try {
+            metrics.incr("tui_snapshots_flushed");
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return { written, skipped };
+}
+/**
+ * Tolerant JSON reader used by tests and (duplicated) by the TUI.
+ * Returns {data} on success, {error} on missing/corrupt.
+ */
+export function readJsonSafe(path) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        try {
+            return { data: JSON.parse(raw) };
+        }
+        catch {
+            return { error: "corrupt" };
+        }
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { error: "missing" };
+        return { error: "corrupt" };
+    }
+}

package/dist/plugin/capabilities.d.ts

@@ -11,5 +11,7 @@ export interface Capabilities {
     readonly skills: boolean;
     readonly references: boolean;
     readonly apiVersion: string | null;
+    /** v1.2.0 (K12-012 / plan D12-03) — additive probe for permission.ask. */
+    readonly permissionAsk?: boolean;
 }
 export declare function probe(input: unknown): Capabilities;

package/dist/plugin/capabilities.js

@@ -11,6 +11,7 @@ const ALL_FALSE = {
     skills: false,
     references: false,
     apiVersion: null,
+    permissionAsk: false,
 };
 function hasCallable(input, domainKey, memberKey) {
     const domain = input[domainKey];
@@ -27,10 +28,12 @@ export function probe(input) {
         const apiVersion = typeof record.apiVersion === "string"
             ? record.apiVersion
             : null;
+        const permissionAsk = hasCallable(record, "permission", "ask");
         return {
             skills: hasCallable(record, "skill", "source"),
             references: hasCallable(record, "reference", "add"),
             apiVersion,
+            permissionAsk,
         };
     }
     catch {

package/dist/plugin/contract.js

@@ -53,6 +53,9 @@ export const CONTRACT_METRIC_ADDITIONS = [
     { name: "bench_regression_failures", since: "1.1.0" },
     { name: "forget_requests_total", since: "1.1.0" },
     { name: "forget_tombstones_published", since: "1.1.0" },
+    // v1.2.0 (K12-001 / plan §4, D12-??) — surface metrics (no migration this release)
+    { name: "tui_snapshots_flushed", since: "1.2.0" },
+    { name: "tui_actions_invoked", since: "1.2.0" },
 ];
 /**
  * v1.0.0 (K10-027 / plan §5.7) — the C-09 boundary addition. Stored is

package/dist/plugin/index.d.ts

@@ -16,10 +16,10 @@ export interface KevinPluginOptions {
  * v0.4.0 (K4-021) — settings surfaced by `kevin_config` (plan §8.8).
  * Unknown keys are rejected on `set` unless `strict: false`.
  */
-export declare const KEVIN_CONFIG_KEYS: readonly ["quality_gate_enabled", "lesson_snippet_injection", "patternminer_enabled", "cross_project_enabled", "llm_reflection_enabled", "tool_calls_dedup_enabled", "deterministic_retrieval", "pre_prompt_budget_tokens", "archive_after_days", "curation_enabled", "agents_md_path", "skill_emission_enabled", "reference_emission_enabled", "injection_confidence_floor", "repo_truth_enabled", "convention_mining_enabled", "conflict_detection_enabled", "error_lesson_mode", "shared_layer_enabled", "okf_path", "share_requires_approval", "author_identity_mode", "shared_confidence_floor", "hook_liveness_enabled", "native_registration_enabled", "host_probe_history_enabled", "dead_hook_report_threshold", "perf_enabled", "perf_ring_capacity", "perf_flush_on_idle", "contract_report_enabled"];
+export declare const KEVIN_CONFIG_KEYS: readonly ["quality_gate_enabled", "lesson_snippet_injection", "patternminer_enabled", "cross_project_enabled", "llm_reflection_enabled", "tool_calls_dedup_enabled", "deterministic_retrieval", "pre_prompt_budget_tokens", "archive_after_days", "curation_enabled", "agents_md_path", "skill_emission_enabled", "reference_emission_enabled", "injection_confidence_floor", "repo_truth_enabled", "convention_mining_enabled", "conflict_detection_enabled", "error_lesson_mode", "shared_layer_enabled", "okf_path", "share_requires_approval", "author_identity_mode", "shared_confidence_floor", "hook_liveness_enabled", "native_registration_enabled", "host_probe_history_enabled", "dead_hook_report_threshold", "perf_enabled", "perf_ring_capacity", "perf_flush_on_idle", "contract_report_enabled", "tui_snapshots_enabled"];
 export declare const ERROR_LESSON_MODE_VALUES: readonly ["all", "triage_only"];
 /** Plugin release version — stamped into generated files (K8-021/027). */
-export declare const KEVIN_VERSION = "1.1.0";
+export declare const KEVIN_VERSION = "1.2.0";
 export interface RekeyCounts {
     memories: number;
     shared_entries: number;

package/dist/plugin/index.js

@@ -6,10 +6,12 @@ import { tool } from "@opencode-ai/plugin";
 import { Archiver } from "./Archiver.js";
 import { ArtifactWriter } from "./ArtifactWriter.js";
 import { CausalChain } from "./CausalChain.js";
+import { handleBridgeCommand } from "./ChatBridge.js";
 import { ConflictDetector } from "./ConflictDetector.js";
 import { ContextInjector } from "./ContextInjector.js";
 import { ConventionMiner } from "./ConventionMiner.js";
 import { Curator } from "./Curator.js";
+import { writeDashboard } from "./DashboardHtml.js";
 import { Feedback } from "./Feedback.js";
 import { HookLiveness } from "./HookLiveness.js";
 import { InjectionLedger } from "./InjectionLedger.js";
@@ -24,8 +26,11 @@ import { Retrospective } from "./Retrospective.js";
 import { SharedLayer } from "./SharedLayer.js";
 import { Store } from "./Store.js";
 import { ToolCallObserver } from "./ToolCallObserver.js";
+import { deleteMailbox, processActions, readMailbox, writeResults, } from "./TuiActions.js";
+import { flushSnapshots } from "./TuiSnapshots.js";
 import { probe } from "./capabilities.js";
 import { computeConfidence } from "./confidence.js";
+import { contractDigest, describeContract } from "./contract.js";
 import { probeHost, summarize } from "./host.js";
 import { kevinApprove } from "./kevin_approve.js";
 import { buildAudit } from "./kevin_audit.js";
@@ -112,6 +117,11 @@ export const KEVIN_CONFIG_KEYS = [
     "perf_ring_capacity",
     "perf_flush_on_idle",
     "contract_report_enabled",
+    // v1.2.0 (K12-001 / plan §4) — the single setting seeded by runtime
+    // (no migration this release). Omitting makes `kevin_config set`
+    // return { error: "unknown_key" } while `kevin_config list` still
+    // shows it.
+    "tui_snapshots_enabled",
 ];
 // v1.1.0 (K11-007 / D11-08) — no new settings in 1.1.0; thresholds are constants (D11-03)
 // v0.7.0 (K7-003 / plan §5.6, D7-12) — the explicit VALUE domain for
@@ -122,7 +132,7 @@ export const KEVIN_CONFIG_KEYS = [
 // behaviour on the next reflection.
 export const ERROR_LESSON_MODE_VALUES = ["all", "triage_only"];
 /** Plugin release version — stamped into generated files (K8-021/027). */
-export const KEVIN_VERSION = "1.1.0";
+export const KEVIN_VERSION = "1.2.0";
 function resolveMigrationsDir() {
     const here = dirname(fileURLToPath(import.meta.url));
     return join(here, "..", "migrations");
@@ -258,6 +268,17 @@ export const KevinPlugin = async (input, options) => {
     const store = new Store({ path: dbPath });
     const migrationsDir = opts.migrationsDir ?? resolveMigrationsDir();
     await new Migrate(store, migrationsDir).run();
+    // v1.2.0 (K12-001 / D12-??) — no migration this release: ensure the
+    // new setting exists with its default so `kevin_config list` shows it
+    // on a database that was already at 012.
+    try {
+        store
+            .prepare("INSERT OR IGNORE INTO kevin_settings (key, value) VALUES (?, ?)")
+            .run("tui_snapshots_enabled", "1");
+    }
+    catch {
+        // pre-003 DB without kevin_settings — nothing to seed
+    }
     const metrics = new Metrics(store);
     // v0.4.0 (K4-019): the plugin hooks expose no project field, so the
     // project id is derived once from the plugin host's working directory
@@ -397,6 +418,10 @@ export const KevinPlugin = async (input, options) => {
     mkdirSync(join(materializerRoot, "skills"), { recursive: true });
     mkdirSync(join(materializerRoot, "refs"), { recursive: true });
     const capabilities = probe(input);
+    // v1.2.0 (K12-012 / D12-03) — permission.ask probe (best-effort, additive).
+    // When the host exposes permission.ask, the presence is noted; absence is silent no-op.
+    // No new setting — bounded to tui_snapshots_enabled host-support check per spec.
+    void capabilities.permissionAsk;
     const materializer = new Materializer(store, { root: materializerRoot });
     // v0.9.0 (K9-016 / plan §5.4, D9-10) — native registration replaces
     // file emission. When attachNative returns a registration for a
@@ -1675,15 +1700,80 @@ export const KevinPlugin = async (input, options) => {
             });
         },
         "chat.message": async (hookInput, output) => {
+            const rawText = output.parts
+                .map((p) => p)
+                .filter((p) => p.type === "text")
+                .map((p) => p.text ?? "")
+                .join(" ");
+            const trimmed = rawText.trim();
+            // v1.2.0 (K12-018 / D12-09) — chat-command bridge BEFORE deriveQuery.
+            // Valid commands are SWALLOWED (parts cleared) and never reach the model.
+            // Must run outside perf.measure so early return actually exits the hook.
+            if (trimmed.length > 0) {
+                try {
+                    const bridgeDeps = {
+                        getPending: () => {
+                            try {
+                                const maybe = curator.pending;
+                                if (typeof maybe === "function") {
+                                    const rows = maybe.call(curator);
+                                    return rows.map((p) => ({
+                                        id: p.id,
+                                        proposedText: String(p.proposed_text ?? p.proposedText ?? ""),
+                                    }));
+                                }
+                            }
+                            catch { }
+                            try {
+                                const rows = store
+                                    .prepare("SELECT id, proposed_text FROM curation_proposals WHERE status = 'pending'")
+                                    .all();
+                                return rows.map((r) => ({
+                                    id: r.id,
+                                    proposedText: r.proposed_text,
+                                }));
+                            }
+                            catch {
+                                return [];
+                            }
+                        },
+                        approve: (id) => kevinApprove(store, memoryService, curator, writer, metrics, {
+                            proposalId: id,
+                            decision: "approve",
+                        }),
+                        reject: (id, note) => kevinApprove(store, memoryService, curator, writer, metrics, {
+                            proposalId: id,
+                            decision: "reject",
+                        }) && void note,
+                        acknowledge: (conflictId) => {
+                            try {
+                                const cd = conflictDetector;
+                                if (typeof cd.acknowledge === "function")
+                                    cd.acknowledge(conflictId);
+                                else if (typeof cd.resolve === "function")
+                                    cd.resolve(conflictId, "a");
+                            }
+                            catch { }
+                        },
+                        metrics,
+                    };
+                    const br = handleBridgeCommand(trimmed, bridgeDeps);
+                    if (br.handled) {
+                        try {
+                            output.parts = [];
+                        }
+                        catch { }
+                        return;
+                    }
+                }
+                catch {
+                    // best-effort — bridge failure must not break chat flow
+                }
+            }
             perf.measure("chat.message", () => {
-                const text = output.parts
-                    .map((p) => p)
-                    .filter((p) => p.type === "text")
-                    .map((p) => p.text ?? "")
-                    .join(" ");
-                if (text.trim()) {
+                if (trimmed.length > 0) {
                     const derived = injector.deriveQuery([
-                        { role: "user", content: text },
+                        { role: "user", content: rawText },
                     ]);
                     lastUserQuery = derived.length > 0 ? derived : null;
                     if (hookInput.sessionID && lastUserQuery) {
@@ -1809,6 +1899,61 @@ export const KevinPlugin = async (input, options) => {
                             // (legacy DBs pre-005 lack the recurrence_count
                             // column)
                             .catch(() => { }));
+                        // v1.2.0 (K12-007/K12-011 / D12-05) — TUI mailbox: actions→curate ordering.
+                        // Process mailbox BEFORE curator.propose so a fresh proposal created this idle
+                        // is NOT visible to a stale token (D12-04). Best-effort, never breaks idle.
+                        try {
+                            const mb = readMailbox(materializerRoot);
+                            if (mb.actions.length) {
+                                const tuiDeps = {
+                                    getPending: () => {
+                                        try {
+                                            const maybe = curator.pending;
+                                            if (typeof maybe === "function") {
+                                                const rows = maybe.call(curator);
+                                                return rows.map((p) => ({
+                                                    id: p.id,
+                                                    proposedText: String(p.proposed_text ?? p.proposedText ?? ""),
+                                                }));
+                                            }
+                                        }
+                                        catch { }
+                                        try {
+                                            const rows = store
+                                                .prepare("SELECT id, proposed_text FROM curation_proposals WHERE status = 'pending'")
+                                                .all();
+                                            return rows.map((r) => ({
+                                                id: r.id,
+                                                proposedText: r.proposed_text,
+                                            }));
+                                        }
+                                        catch {
+                                            return [];
+                                        }
+                                    },
+                                    approve: (id) => kevinApprove(store, memoryService, curator, writer, metrics, {
+                                        proposalId: id,
+                                        decision: "approve",
+                                    }),
+                                    reject: (id, _note) => kevinApprove(store, memoryService, curator, writer, metrics, {
+                                        proposalId: id,
+                                        decision: "reject",
+                                    }),
+                                    acknowledge: (conflictId) => {
+                                        const cd = conflictDetector;
+                                        if (typeof cd.acknowledge === "function")
+                                            cd.acknowledge(conflictId);
+                                    },
+                                    metrics,
+                                };
+                                const tuiResults = processActions(mb.actions, tuiDeps);
+                                writeResults(materializerRoot, tuiResults);
+                                deleteMailbox(materializerRoot);
+                            }
+                        }
+                        catch {
+                            // best-effort
+                        }
                         // v0.6.0 (K6-015 / plan §8.14) — session-idle curation
                         // generation. Dry-run only: `propose()` calls `plan()`
                         // and never `apply()`, so nothing here can touch disk
@@ -1850,6 +1995,145 @@ export const KevinPlugin = async (input, options) => {
                             // best-effort, same pattern as ledger.settle — a
                             // sync failure must not break the idle path
                         }
+                        // v1.2.0 (K12-003/K12-011/K12-017 / D12-05) — snapshot flush gated by tui_snapshots_enabled.
+                        // Order: actions→curate→syncSharedLayer→snapshots (D12-05) — snapshots reflect post-action truth.
+                        try {
+                            if (memoryService.getSetting("tui_snapshots_enabled", "1") === "1") {
+                                // Proposals
+                                let proposals = [];
+                                try {
+                                    const rawPending = (() => {
+                                        try {
+                                            const maybe = curator.pending;
+                                            if (typeof maybe === "function")
+                                                return maybe.call(curator);
+                                        }
+                                        catch { }
+                                        return store
+                                            .prepare("SELECT id, kind, target_path, proposed_text, diff, memory_id, created_at FROM curation_proposals WHERE status = 'pending' ORDER BY created_at")
+                                            .all();
+                                    })();
+                                    const { proposalToken } = await import("./TuiActions.js");
+                                    proposals = rawPending.map((r) => {
+                                        const row = r;
+                                        const id = String(row.id ?? "");
+                                        const proposed = String(row.proposed_text ?? row.proposedText ?? "");
+                                        return {
+                                            id,
+                                            kind: String(row.kind ?? "agents_md"),
+                                            target_path: String(row.target_path ?? row.targetPath ?? "AGENTS.md"),
+                                            diff: String(row.diff ?? ""),
+                                            memory_ids: String(row.memory_id ?? row.memoryIds ?? "")
+                                                .split(",")
+                                                .filter((s) => s.length > 0),
+                                            created_at: String(row.created_at ??
+                                                row.createdAt ??
+                                                new Date().toISOString()),
+                                            token: proposalToken(id, proposed),
+                                        };
+                                    });
+                                }
+                                catch { }
+                                // Conflicts
+                                let conflicts = [];
+                                try {
+                                    const maybe = conflictDetector.openConflicts;
+                                    if (typeof maybe === "function") {
+                                        const raw = maybe.call(conflictDetector);
+                                        conflicts = raw.map((c) => {
+                                            const row = c;
+                                            return {
+                                                id: String(row.id ?? ""),
+                                                kind: String(row.kind ?? ""),
+                                                a_summary: String(row.a_summary ?? row.aSummary ?? ""),
+                                                b_summary: String(row.b_summary ?? row.bSummary ?? ""),
+                                                opened_at: String(row.opened_at ??
+                                                    row.openedAt ??
+                                                    new Date().toISOString()),
+                                            };
+                                        });
+                                    }
+                                }
+                                catch {
+                                    conflicts = [];
+                                }
+                                // Health
+                                let health;
+                                try {
+                                    const doc = buildDoctor(store, host, memoryService);
+                                    let perfRows = [];
+                                    try {
+                                        const stats = perf.stats?.();
+                                        if (Array.isArray(stats)) {
+                                            perfRows = stats.map((p) => {
+                                                const row = p;
+                                                const budget = row.budget;
+                                                return {
+                                                    scope: String(row.scope ?? ""),
+                                                    p95: Number(row.p95 ?? 0),
+                                                    budget_p95: Number(budget?.p95Ms ??
+                                                        row.budget_p95 ??
+                                                        row.budgetP95 ??
+                                                        0),
+                                                    within_budget: Boolean(row.withinBudget ?? row.within_budget ?? true),
+                                                };
+                                            });
+                                        }
+                                    }
+                                    catch {
+                                        perfRows = [];
+                                    }
+                                    let digest = "unknown";
+                                    try {
+                                        digest = contractDigest(describeContract());
+                                    }
+                                    catch { }
+                                    health = {
+                                        verdict: doc.verdict,
+                                        reason: doc.reason,
+                                        hooks: doc.hooks.map((h) => ({
+                                            hook: h.hook,
+                                            state: h.state,
+                                            fire_count: h.fire_count,
+                                            expected_count: h.expected_count,
+                                        })),
+                                        perf: perfRows,
+                                        contract_digest: digest,
+                                        counters: metrics.snapshot(),
+                                    };
+                                }
+                                catch {
+                                    health = {
+                                        verdict: "unknown",
+                                        reason: "health unavailable",
+                                        hooks: [],
+                                        perf: [],
+                                        contract_digest: "unknown",
+                                        counters: {},
+                                    };
+                                }
+                                flushSnapshots({
+                                    root: materializerRoot,
+                                    proposals,
+                                    conflicts,
+                                    health,
+                                    metrics,
+                                    version: KEVIN_VERSION,
+                                });
+                                try {
+                                    writeDashboard(materializerRoot, {
+                                        generatedAt: new Date().toISOString(),
+                                        proposals,
+                                        conflicts,
+                                        health,
+                                    });
+                                }
+                                catch { }
+                            }
+                        }
+                        catch {
+                            // best-effort — snapshot failure must not break idle
+                        }
                         // v1.0.0 (K10-013 / D10-08) — the session recorded work:
                         // arm the deferred dispose settlement. The ISO timestamp
                         // lets the next session.start compare it against

package/dist/plugin/kevin_audit.d.ts

@@ -153,6 +153,22 @@ export interface AuditReport {
         clause_count: number;
         deprecated_count: number;
     };
+    /**
+     * v1.2.0 (K12-014 / D12-??) — TUI surface block. Read-only introspection:
+     * enabled_setting is the kevin_settings value, last_flush_age_s is seconds
+     * since meta.json generatedAt (null when absent/corrupt), mailbox_depth is
+     * queue length (null when file missing), last_results is the parsed
+     * results.json array (null when absent). Dashboard age and bridge counters
+     * added in K12-019.
+     */
+    tui?: {
+        enabled_setting: string;
+        last_flush_age_s: number | null;
+        mailbox_depth: number | null;
+        last_results: unknown | null;
+        dashboard_last_write_age_s: number | null;
+        bridge_interceptions: number;
+    };
     partial: boolean;
 }
 /**
@@ -210,4 +226,4 @@ export interface TruthReport {
         is_truncated: false;
     };
 }
-export declare function buildAudit(store: Store, metrics: Metrics, capabilities?: Capabilities, projectId?: string, repoId?: string | null): AuditReport;
+export declare function buildAudit(store: Store, metrics: Metrics, capabilities?: Capabilities, projectId?: string, repoId?: string | null, tuiRoot?: string): AuditReport;