@jmtrin/opencode-kevin 1.1.0 → 1.2.0

package/README.md

@@ -159,7 +159,15 @@ kevin_doctor    → health report: hooks, deps, perf, verdict
 ~/.opencode-kevin/
 ├── kevin.db            ← everything Kevin learns (SQLite, WAL)
 ├── skills/             ← generated pull channels
-└── refs/               ← topic reference bundles
+├── refs/               ← topic reference bundles
+└── tui/
+    ├── proposals.json  ← pending proposals projection (512 KiB cap)
+    ├── conflicts.json  ← open conflicts projection
+    ├── health.json     ← doctor+perf snapshot
+    ├── meta.json       ← {generatedAt, versions}
+    ├── dashboard.html  ← static review surface (file://, zero network)
+    ├── actions.json    ← mailbox queue (TUI panels → session.idle)
+    └── results.json    ← last action results (audit)
 
 <repo>/.kevin/
 ├── AGENTS.md           ← curated knowledge (marker block, human-approved)
@@ -180,6 +188,26 @@ kevin_doctor    → health report: hooks, deps, perf, verdict
 
 ---
 
+## 🆕 What's new in 1.2.0 — "Surface"
+
+> 1.2.0 gives the human-in-the-loop a place to stand: every pending proposal is readable with its diff without opening an editor, and every approval rides the same gated handler.
+
+- 🖥️ **Three review surfaces, one projection** — TUI panels (`/kevin` route, `k` to open) where the host renders them, plus a static `dashboard.html` under `~/.opencode-kevin/tui/` that opens via `file://` with zero network, zero fetch, inline CSS/JS and embedded JSON.
+- 💬 **Chat-command bridge `/kevin-*` (universal, immediate)** — `/kevin-approve <id> <token>`, `/kevin-reject <id> <token> [note]`, `/kevin-ack <id>` execute through the existing `kevinApprove` / acknowledge handlers; valid commands are swallowed, invalid/stale ones pass through untouched to the model.
+- 📦 **Mailbox for TUI panels (idle-latency)** — proposals approved from the TUI write `~/.opencode-kevin/tui/actions.json`; the session consumes it at the next `session.idle` before `curator.propose`, then refreshes snapshots (`tui_snapshots_enabled='1'`).
+- ⏱️ **Latency honesty** — chat commands apply this turn; mailbox actions apply at next idle. Both disclosed in-surface (`queued — applies at session idle` toast, copy hint on dashboard).
+- 📦 **Packaging** — new export `opencode-kevin/tui` (`dist/plugin/tui.*`), `engines.opencode ^1.18.0` validated by the host with skip-with-warning.
+
+| Surface | Review | Action | Latency |
+|---|---|---|---|
+| TUI panel (`/kevin`) — CLI/TUI host | Proposals / Conflicts / Health tabs, diff dialog, truncation markers | `a` approve / `r` reject / `x` ack → mailbox | next idle |
+| Static dashboard (`dashboard.html`) | Proposals (+escaped diff `<pre>`), conflicts two-column, health banner | Copy `/kevin-*` button → paste into chat input | immediate (chat bridge) |
+| Any client (Desktop, CLI) | — | Type `/kevin-approve …` etc in chat input | immediate |
+
+Snapshots + dashboard are capped at 512 KiB (diff truncation with `truncated:true`), written atomically via `tmp`+`rename`, and read best-effort with empty-state explanations (`no snapshots yet — open an opencode session…`) when missing/corrupt/stale-token.
+
+---
+
 ## 🆕 What's new in 1.0.0
 
 > 1.0.0 is the **proven release**: the surface is frozen as data, the cost is
@@ -489,6 +517,7 @@ client). All values are TEXT — flags compare with `=== "1"`, never truthiness.
 | `perf_ring_capacity` | `'512'` | Samples per scope (clamped `[64, 8192]`) |
 | `perf_flush_on_idle` | `'1'` | Persist samples at idle |
 | `contract_report_enabled` | `'1'` | Contract block in `kevin_audit` |
+| `tui_snapshots_enabled` | `'1'` | Snapshot + dashboard flush at idle (opencode-kevin/tui) |
 
 ---
 

package/dist/plugin/ChatBridge.d.ts

@@ -0,0 +1,41 @@
+import { type PendingProposal } from "./TuiActions.js";
+export type BridgeDeps = {
+    readonly getPending: () => readonly PendingProposal[];
+    readonly approve: (proposalId: string) => unknown;
+    readonly reject: (proposalId: string, note?: string) => unknown;
+    readonly acknowledge: (conflictId: string) => unknown;
+    readonly metrics?: {
+        incr: (key: "tui_actions_invoked", by?: number) => void;
+    } | null;
+};
+export type ParsedBridgeCommand = {
+    readonly type: "approve";
+    readonly proposalId: string;
+    readonly token: string;
+    readonly note?: string;
+} | {
+    readonly type: "reject";
+    readonly proposalId: string;
+    readonly token: string;
+    readonly note?: string;
+} | {
+    readonly type: "ack";
+    readonly conflictId: string;
+};
+export declare function parseBridgeCommand(text: string): ParsedBridgeCommand | null;
+export declare const KEVIN_COMMAND_RE: RegExp;
+export interface BridgeResult {
+    readonly handled: boolean;
+    readonly status?: "applied" | "rejected" | "stale_skipped" | "error";
+    readonly detail?: string;
+}
+/**
+ * Execute a chat message through the bridge.
+ * - Non-matching → {handled:false} (byte-identical pass-through)
+ * - Matching but stale/invalid → {handled:false, status:"stale_skipped"} (pass-through + counter)
+ * - Valid → executes via deps handlers, {handled:true}
+ *
+ * Valid commands are SWALLOWED — caller must not forward to model.
+ * Invalid/stale commands pass through untouched (D12-09).
+ */
+export declare function handleBridgeCommand(text: string, deps: BridgeDeps): BridgeResult;

package/dist/plugin/ChatBridge.js

@@ -0,0 +1,103 @@
+// v1.2.0 (K12-018 / plan §4.4 R3, D12-09) — chat-command bridge (universal actions).
+// Hot path: ONE regex test on non-match, allocation-free.
+import { verifyFresh, } from "./TuiActions.js";
+// Exact regex for approve/reject (require 16-hex token, optional note capture).
+// Ack variant is token-free (acknowledge is non-destructive, matches mailbox).
+const APPROVE_REJECT_RE = /^\/kevin-(approve|reject)\s+(\S+)\s+([0-9a-f]{16})(?:\s+([\s\S]+))?$/;
+const ACK_RE = /^\/kevin-ack\s+(\S+)\s*$/;
+// Combined pattern for documentation / static analysis (covers both forms).
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _DOC_RE = /^\/kevin-(approve|reject|ack)\s+(\S+)\s+([0-9a-f]{16})(?:\s+([\s\S]+))?$/;
+export function parseBridgeCommand(text) {
+    // Approve / reject — require token
+    const m = APPROVE_REJECT_RE.exec(text);
+    if (m) {
+        const type = m[1];
+        const proposalId = m[2];
+        const token = m[3];
+        const note = m[4] !== undefined ? m[4] : undefined;
+        if (type === "approve")
+            return {
+                type: "approve",
+                proposalId,
+                token,
+                ...(note !== undefined ? { note } : {}),
+            };
+        return {
+            type: "reject",
+            proposalId,
+            token,
+            ...(note !== undefined ? { note } : {}),
+        };
+    }
+    const ack = ACK_RE.exec(text);
+    if (ack) {
+        return { type: "ack", conflictId: ack[1] };
+    }
+    return null;
+}
+// Backward alias for tests that import by plan name
+export const KEVIN_COMMAND_RE = APPROVE_REJECT_RE;
+/**
+ * Execute a chat message through the bridge.
+ * - Non-matching → {handled:false} (byte-identical pass-through)
+ * - Matching but stale/invalid → {handled:false, status:"stale_skipped"} (pass-through + counter)
+ * - Valid → executes via deps handlers, {handled:true}
+ *
+ * Valid commands are SWALLOWED — caller must not forward to model.
+ * Invalid/stale commands pass through untouched (D12-09).
+ */
+export function handleBridgeCommand(text, deps) {
+    const parsed = parseBridgeCommand(text);
+    if (!parsed)
+        return { handled: false };
+    if (parsed.type === "ack") {
+        // Ack is non-destructive, no token verification — matches mailbox acknowledge semantics.
+        try {
+            deps.acknowledge(parsed.conflictId);
+            try {
+                deps.metrics?.incr("tui_actions_invoked", 1);
+            }
+            catch { }
+            return { handled: true, status: "applied" };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { handled: true, status: "error", detail: msg };
+        }
+    }
+    // approve / reject — verify token against CURRENT pending state (same as mailbox)
+    const pending = deps.getPending();
+    const action = {
+        type: parsed.type,
+        proposalId: parsed.proposalId,
+        token: parsed.token,
+        ...(parsed.note !== undefined ? { note: parsed.note } : {}),
+    };
+    const fresh = verifyFresh(action, pending);
+    if (!fresh.ok) {
+        // Invalid/stale → pass-through untouched (do NOT swallow). Caller should forward byte-identically.
+        // Audit counter could be incremented here, but not as contract metric (blockedSnapshot-style internal).
+        return { handled: false, status: "stale_skipped", detail: fresh.reason };
+    }
+    try {
+        if (parsed.type === "approve") {
+            deps.approve(parsed.proposalId);
+            try {
+                deps.metrics?.incr("tui_actions_invoked", 1);
+            }
+            catch { }
+            return { handled: true, status: "applied" };
+        }
+        deps.reject(parsed.proposalId, parsed.note);
+        try {
+            deps.metrics?.incr("tui_actions_invoked", 1);
+        }
+        catch { }
+        return { handled: true, status: "rejected" };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { handled: true, status: "error", detail: msg };
+    }
+}

package/dist/plugin/DashboardHtml.d.ts

@@ -0,0 +1,5 @@
+import type { TuiSnapshotSet } from "./tui-types.js";
+export declare function escapeHtml(text: string): string;
+export declare function proposalToken(proposalId: string, proposedText: string): string;
+export declare function renderDashboard(views: TuiSnapshotSet): string;
+export declare function writeDashboard(root: string, views: TuiSnapshotSet): string;

package/dist/plugin/DashboardHtml.js

@@ -0,0 +1,180 @@
+// v1.2.0 (K12-017 / plan §4.4 R2, D12-10) — static dashboard generator.
+// Single self-contained file: inline CSS/JS, snapshot data embedded as const DATA.
+// Zero network: no fetch, no XHR, no WebSocket, no external asset.
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const CAP_BYTES = 512 * 1024;
+function byteLen(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+// HTML escaping — mirrors escapeInjectedText discipline (C-09 family).
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function proposalToken(proposalId, proposedText) {
+    return createHash("sha256")
+        .update(`${proposalId}\0${proposedText}`, "utf8")
+        .digest("hex")
+        .slice(0, 16);
+}
+function truncateForHtml(views, cap) {
+    // Estimate html size; if over cap, truncate diffs progressively.
+    let html = renderDashboardInner(views, false);
+    if (byteLen(html) <= cap)
+        return views;
+    // First pass: cap diffs to 2000 chars
+    let truncated = {
+        ...views,
+        proposals: views.proposals.map((p) => {
+            if (p.diff.length <= 2000)
+                return p;
+            return {
+                ...p,
+                diff: `${p.diff.slice(0, 2000)}\n…[truncated]`,
+                truncated: true,
+            };
+        }),
+    };
+    html = renderDashboardInner(truncated, false);
+    if (byteLen(html) <= cap)
+        return truncated;
+    // Second: 800 chars
+    truncated = {
+        ...views,
+        proposals: views.proposals.map((p) => ({
+            ...p,
+            diff: p.diff.length > 800 ? `${p.diff.slice(0, 800)}\n…[truncated]` : p.diff,
+            truncated: p.diff.length > 800 ? true : p.truncated,
+        })),
+        conflicts: views.conflicts.map((c) => ({
+            ...c,
+            a_summary: c.a_summary.slice(0, 200),
+            b_summary: c.b_summary.slice(0, 200),
+        })),
+    };
+    html = renderDashboardInner(truncated, false);
+    if (byteLen(html) <= cap)
+        return truncated;
+    // Third: drop diffs to 400 chars
+    truncated = {
+        ...views,
+        proposals: views.proposals.map((p) => ({
+            ...p,
+            diff: `${p.diff.slice(0, 400)}\n…[truncated]`,
+            truncated: true,
+        })),
+    };
+    return truncated;
+}
+function renderDashboardInner(views, _withTruncation) {
+    const css = "*{box-sizing:border-box}body{font-family:ui-monospace,monospace;margin:0;padding:16px;background:#0f1115;color:#e6e6e6}a{color:#8ab4ff}header{border-bottom:1px solid #2a2e39;padding-bottom:12px;margin-bottom:16px}h1{margin:0;font-size:20px}h2{font-size:16px;margin:24px 0 8px;border-bottom:1px solid #222;padding-bottom:4px}.card{border:1px solid #2a2e39;border-radius:8px;padding:12px;margin:8px 0;background:#151821}.muted{color:#9aa0b2;font-size:12px}.badge{display:inline-block;padding:2px 6px;border-radius:999px;font-size:11px;border:1px solid #2a2e39}.badge-healthy{background:#12331a;color:#8ef0a0}.badge-degraded{background:#331a1a;color:#f0a0a0}.badge-unknown{background:#2a2a33;color:#c0c0d0}pre{white-space:pre-wrap;word-break:break-word;background:#0b0d12;padding:8px;border-radius:6px;overflow:auto;max-height:320px;font-size:12px}table{width:100%;border-collapse:collapse;font-size:12px}th,td{border:1px solid #2a2e39;padding:4px 6px;text-align:left}button{cursor:pointer;background:#1f2330;color:#e6e6e6;border:1px solid #2a2e39;border-radius:6px;padding:4px 8px;font-size:12px}button:hover{background:#2a3045}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:8px}.cols{display:grid;grid-template-columns:1fr 1fr;gap:12px}.count{font-size:11px;color:#9aa0b2}";
+    // Build proposals HTML server-side
+    const proposalsHtml = views.proposals.length === 0
+        ? `<div class="muted">No pending proposals.</div>`
+        : views.proposals
+            .map((p) => {
+            const token = p.token ?? proposalToken(p.id, p.diff);
+            const approveCmd = `/kevin-approve ${p.id} ${token}`;
+            const rejectCmd = `/kevin-reject ${p.id} ${token}`;
+            return `<div class="card">
+<div><strong>${escapeHtml(p.kind)}</strong> <span class="muted">${escapeHtml(p.id)}</span> <span class="badge">${escapeHtml(p.target_path)}</span> <span class="muted">${escapeHtml(p.created_at)}</span>${p.truncated ? ` <span class="badge">truncated</span>` : ""}</div>
+<div class="muted">memories: ${escapeHtml(p.memory_ids.join(", "))}</div>
+<pre>${escapeHtml(p.diff)}</pre>
+<div style="display:flex;gap:8px;margin-top:8px">
+<button data-copy="${escapeHtml(approveCmd)}" onclick="copyCmd(this)">Copy approve</button>
+<button data-copy="${escapeHtml(rejectCmd)}" onclick="copyCmd(this)">Copy reject</button>
+</div>
+<div class="muted copy-hint"></div>
+</div>`;
+        })
+            .join("\n");
+    const conflictsHtml = views.conflicts.length === 0
+        ? `<div class="muted">No open conflicts.</div>`
+        : views.conflicts
+            .map((c) => {
+            const ackCmd = `/kevin-ack ${c.id}`;
+            return `<div class="card">
+<div><strong>${escapeHtml(c.kind)}</strong> <span class="muted">${escapeHtml(c.id)}</span> <span class="muted">${escapeHtml(c.opened_at)}</span></div>
+<div class="cols"><div><div class="muted">A</div><pre>${escapeHtml(c.a_summary)}</pre></div><div><div class="muted">B</div><pre>${escapeHtml(c.b_summary)}</pre></div></div>
+<div style="margin-top:8px"><button data-copy="${escapeHtml(ackCmd)}" onclick="copyCmd(this)">Copy ack</button> <span class="muted copy-hint"></span></div>
+</div>`;
+        })
+            .join("\n");
+    const verdictClass = views.health.verdict === "healthy"
+        ? "badge-healthy"
+        : views.health.verdict === "degraded"
+            ? "badge-degraded"
+            : "badge-unknown";
+    const hooksRows = views.health.hooks.length === 0
+        ? `<tr><td colspan="4" class="muted">No hooks</td></tr>`
+        : views.health.hooks
+            .map((h) => `<tr><td>${escapeHtml(h.hook)}</td><td>${escapeHtml(h.state)}</td><td>${h.fire_count}</td><td>${h.expected_count}</td></tr>`)
+            .join("\n");
+    const perfRows = views.health.perf.length === 0
+        ? `<tr><td colspan="4" class="muted">No perf data</td></tr>`
+        : views.health.perf
+            .map((p) => `<tr><td>${escapeHtml(p.scope)}</td><td>${p.p95}</td><td>${p.budget_p95}</td><td>${p.within_budget ? "yes" : "no"}</td></tr>`)
+            .join("\n");
+    const countersHtml = Object.keys(views.health.counters).length === 0
+        ? `<div class="muted">No counters</div>`
+        : `<div class="grid">${Object.entries(views.health.counters)
+            .map(([k, v]) => `<div class="card"><div class="muted">${escapeHtml(k)}</div><div><strong>${v}</strong></div></div>`)
+            .join("\n")}</div>`;
+    // Embedded DATA — escape every "<" to \u003c so hostile "<script>" can never appear verbatim inside the <script> block.
+    const dataJson = JSON.stringify(views).replace(/</g, "\\u003c");
+    const js = `function copyCmd(btn){var cmd=btn.getAttribute('data-copy');var hint=btn.parentElement.nextElementSibling;function done(t){if(hint)hint.textContent=t;setTimeout(function(){if(hint)hint.textContent='';},2500);}if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(cmd).then(function(){done('Copied: '+cmd+' — paste into your opencode session');},function(){fallback(cmd,done);});}else{fallback(cmd,done);}}function fallback(cmd,done){var ta=document.createElement('textarea');ta.value=cmd;ta.style.position='fixed';ta.style.opacity='0';document.body.appendChild(ta);ta.select();try{document.execCommand('copy');done('Copied: '+cmd+' — paste into your opencode session');}catch(e){done('Copy failed — manually copy: '+cmd);}document.body.removeChild(ta);}`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Kevin — Dashboard</title>
+<style>${css}</style>
+</head>
+<body>
+<header>
+<h1>Kevin — Surface Dashboard</h1>
+<div class="muted">Generated at ${escapeHtml(views.generatedAt)} · <span class="badge ${verdictClass}">${escapeHtml(views.health.verdict)}</span> ${escapeHtml(views.health.reason)} · contract ${escapeHtml(views.health.contract_digest)}</div>
+<div class="muted">Proposals ${views.proposals.length} · Conflicts ${views.conflicts.length} · Paste copied <code>/kevin-*</code> commands into your opencode session (Desktop or CLI).</div>
+</header>
+
+<section>
+<h2>Proposals</h2>
+${proposalsHtml}
+</section>
+
+<section>
+<h2>Conflicts</h2>
+${conflictsHtml}
+</section>
+
+<section>
+<h2>Health</h2>
+<table><thead><tr><th>hook</th><th>state</th><th>fires</th><th>expected</th></tr></thead><tbody>${hooksRows}</tbody></table>
+<table style="margin-top:12px"><thead><tr><th>scope</th><th>p95 ms</th><th>budget p95</th><th>within</th></tr></thead><tbody>${perfRows}</tbody></table>
+<div style="margin-top:12px">${countersHtml}</div>
+</section>
+
+<script>const DATA=${dataJson};${js}</script>
+</body>
+</html>`;
+}
+export function renderDashboard(views) {
+    const capped = truncateForHtml(views, CAP_BYTES);
+    return renderDashboardInner(capped, true);
+}
+export function writeDashboard(root, views) {
+    const dir = join(root, "tui");
+    mkdirSync(dir, { recursive: true });
+    const html = renderDashboard(views);
+    const target = join(dir, "dashboard.html");
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, html, "utf8");
+    renameSync(tmp, target);
+    return target;
+}

package/dist/plugin/Retrospective.js

@@ -78,6 +78,9 @@ export const METRIC_KEY_LABELS = {
     bench_regression_failures: "Fallos de regresion de benchmark",
     forget_requests_total: "Solicitudes de olvido totales",
     forget_tombstones_published: "Tombstones publicados por olvido",
+    // v1.2.0 (K12-001 / plan §4) — surface metrics; labels required by BUG-014 regression.
+    tui_snapshots_flushed: "Snapshots TUI generados",
+    tui_actions_invoked: "Acciones TUI invocadas",
 };
 function originLabel(origin) {
     if (origin === "reflector")

package/dist/plugin/TuiActions.d.ts

@@ -0,0 +1,43 @@
+import type { ActionResult, TuiAction } from "./tui-types.js";
+export interface MailboxReadResult {
+    readonly actions: readonly TuiAction[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Read `join(root,"tui","actions.json")` tolerant.
+ * - missing file → {actions:[], warnings:[]}
+ * - malformed JSON → {actions:[], warnings:["malformed_json"]}
+ * - non-object or missing/non-array actions → {actions:[], warnings:["invalid_shape"]}
+ * - unknown type values are dropped with warning per entry
+ * Never deletes the file here.
+ */
+export declare function readMailbox(root: string): MailboxReadResult;
+export declare function proposalToken(proposalId: string, proposedText: string): string;
+export interface PendingProposal {
+    readonly id: string;
+    readonly proposedText: string;
+}
+export declare function verifyFresh(action: TuiAction, currentPending: readonly PendingProposal[]): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ActionStatus = ActionResult["status"];
+export interface ProcessDeps {
+    readonly getPending: () => readonly PendingProposal[];
+    readonly approve: (proposalId: string) => unknown;
+    readonly reject: (proposalId: string, note?: string) => unknown;
+    readonly acknowledge: (conflictId: string) => unknown;
+    readonly metrics?: {
+        incr: (key: "tui_actions_invoked", by?: number) => void;
+    } | null;
+}
+export declare function processActions(actions: readonly TuiAction[], deps: ProcessDeps): ActionResult[];
+export declare function writeResults(root: string, results: readonly ActionResult[]): void;
+export declare function deleteMailbox(root: string): void;
+/**
+ * Convenience: read → process → write results → delete queue.
+ * Returns results (empty if no actions). Mirrors idle-chain usage.
+ */
+export declare function consumeMailbox(root: string, deps: ProcessDeps): ActionResult[];

package/dist/plugin/TuiActions.js

@@ -0,0 +1,181 @@
+// v1.2.0 (K12-005 / plan §4.3) — mailbox tolerant parser (phase F1).
+// v1.2.0 (K12-006 / plan §4.3, D12-04) — token scheme + stale detection
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isValidAction(raw) {
+    if (!isRecord(raw))
+        return null;
+    const t = raw.type;
+    if (t === "approve") {
+        if (typeof raw.proposalId === "string" && typeof raw.token === "string") {
+            return { type: "approve", proposalId: raw.proposalId, token: raw.token };
+        }
+        return null;
+    }
+    if (t === "reject") {
+        if (typeof raw.proposalId === "string" && typeof raw.token === "string") {
+            const note = typeof raw.note === "string" ? raw.note : undefined;
+            return note !== undefined
+                ? { type: "reject", proposalId: raw.proposalId, token: raw.token, note }
+                : { type: "reject", proposalId: raw.proposalId, token: raw.token };
+        }
+        return null;
+    }
+    if (t === "acknowledge") {
+        if (typeof raw.conflictId === "string") {
+            return { type: "acknowledge", conflictId: raw.conflictId };
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Read `join(root,"tui","actions.json")` tolerant.
+ * - missing file → {actions:[], warnings:[]}
+ * - malformed JSON → {actions:[], warnings:["malformed_json"]}
+ * - non-object or missing/non-array actions → {actions:[], warnings:["invalid_shape"]}
+ * - unknown type values are dropped with warning per entry
+ * Never deletes the file here.
+ */
+export function readMailbox(root) {
+    const path = join(root, "tui", "actions.json");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return { actions: [], warnings: [] };
+        return { actions: [], warnings: ["read_error"] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { actions: [], warnings: ["malformed_json"] };
+    }
+    if (!isRecord(parsed)) {
+        return { actions: [], warnings: ["invalid_shape"] };
+    }
+    const maybeActions = parsed.actions;
+    if (!Array.isArray(maybeActions)) {
+        return { actions: [], warnings: ["invalid_shape"] };
+    }
+    const actions = [];
+    const warnings = [];
+    for (const entry of maybeActions) {
+        if (!isRecord(entry)) {
+            warnings.push("dropped_invalid_entry");
+            continue;
+        }
+        const type = entry.type;
+        if (type !== "approve" && type !== "reject" && type !== "acknowledge") {
+            warnings.push(`dropped_unknown_type:${String(type)}`);
+            continue;
+        }
+        const valid = isValidAction(entry);
+        if (!valid) {
+            warnings.push(`dropped_invalid_${String(type)}`);
+            continue;
+        }
+        actions.push(valid);
+    }
+    return { actions, warnings };
+}
+// v1.2.0 (K12-006 / D12-04) — first 16 hex of SHA-256(proposalId + "\0" + proposedText)
+export function proposalToken(proposalId, proposedText) {
+    return createHash("sha256")
+        .update(`${proposalId}\0${proposedText}`, "utf8")
+        .digest("hex")
+        .slice(0, 16);
+}
+export function verifyFresh(action, currentPending) {
+    if (action.type === "acknowledge")
+        return { ok: true };
+    const pending = currentPending.find((p) => p.id === action.proposalId);
+    if (!pending) {
+        return { ok: false, reason: "content_changed_or_absent" };
+    }
+    const expected = proposalToken(pending.id, pending.proposedText);
+    if (expected !== action.token) {
+        return { ok: false, reason: "content_changed_or_absent" };
+    }
+    return { ok: true };
+}
+export function processActions(actions, deps) {
+    const results = [];
+    const pendingSnapshot = deps.getPending();
+    for (const action of actions) {
+        // Stale check for approve/reject
+        if (action.type === "approve" || action.type === "reject") {
+            const fresh = verifyFresh(action, pendingSnapshot);
+            if (!fresh.ok) {
+                results.push({ action, status: "stale_skipped", detail: fresh.reason });
+                try {
+                    deps.metrics?.incr("tui_actions_invoked", 1);
+                }
+                catch { }
+                continue;
+            }
+        }
+        try {
+            if (action.type === "approve") {
+                deps.approve(action.proposalId);
+                results.push({ action, status: "applied" });
+            }
+            else if (action.type === "reject") {
+                deps.reject(action.proposalId, action.note);
+                results.push({ action, status: "rejected" });
+            }
+            else if (action.type === "acknowledge") {
+                deps.acknowledge(action.conflictId);
+                results.push({ action, status: "applied" });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ action, status: "error", detail: msg });
+        }
+        try {
+            deps.metrics?.incr("tui_actions_invoked", 1);
+        }
+        catch { }
+    }
+    return results;
+}
+export function writeResults(root, results) {
+    const dir = join(root, "tui");
+    mkdirSync(dir, { recursive: true });
+    const payload = JSON.stringify({ generatedAt: new Date().toISOString(), results }, null, 2);
+    const target = join(dir, "results.json");
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, payload, "utf8");
+    renameSync(tmp, target);
+}
+export function deleteMailbox(root) {
+    try {
+        unlinkSync(join(root, "tui", "actions.json"));
+    }
+    catch {
+        // missing is fine
+    }
+}
+/**
+ * Convenience: read → process → write results → delete queue.
+ * Returns results (empty if no actions). Mirrors idle-chain usage.
+ */
+export function consumeMailbox(root, deps) {
+    const { actions } = readMailbox(root);
+    if (actions.length === 0)
+        return [];
+    const results = processActions(actions, deps);
+    writeResults(root, results);
+    deleteMailbox(root);
+    return results;
+}

package/dist/plugin/TuiSnapshots.d.ts

@@ -0,0 +1,24 @@
+import type { Metrics } from "./metrics.js";
+import type { ConflictView, HealthView, ProposalView } from "./tui-types.js";
+export interface FlushInput {
+    readonly root: string;
+    readonly proposals: readonly ProposalView[];
+    readonly conflicts: readonly ConflictView[];
+    readonly health: HealthView;
+    readonly metrics?: Metrics | null;
+    readonly version?: string;
+}
+export interface FlushResult {
+    readonly written: string[];
+    readonly skipped: string[];
+}
+export declare function flushSnapshots(input: FlushInput): FlushResult;
+/**
+ * Tolerant JSON reader used by tests and (duplicated) by the TUI.
+ * Returns {data} on success, {error} on missing/corrupt.
+ */
+export declare function readJsonSafe(path: string): {
+    data: unknown;
+} | {
+    error: "missing" | "corrupt";
+};