@jmtrin/opencode-kevin 0.8.0 → 0.9.0

package/README.md

@@ -51,7 +51,7 @@ For a **single project**, put the same `plugin` array in `./opencode.json` or `.
 
 ### 2. Restart OpenCode
 
-Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, Kevin exposes 21 tools, including `kevin_facts`, `kevin_conflicts`, `kevin_project`, `kevin_share` and `kevin_sync`.
+Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, Kevin exposes 23 tools, including `kevin_facts`, `kevin_conflicts`, `kevin_project`, `kevin_share`, `kevin_sync`, `kevin_doctor` and `kevin_native`.
 
 Contradictions de-rank memories and surface conflicts. They never delete, stale, archive, or auto-resolve a memory.
 
@@ -156,7 +156,7 @@ Since v0.8.0, memories live in one of two layers: **local** (private to this ins
 
 ## Tools
 
-Kevin exposes 21 tools callable by the agent.
+Kevin exposes 23 tools callable by the agent.
 
 ### `kevin_save`
 
@@ -210,8 +210,8 @@ Global counts and metrics: memory census, the precision block, the six blocked-g
 ```
 kevin_status({})
 // → { "memories": 42, "memories_reflector": 12, "memories_agent": 30,
-//      "memories_pattern": 0, "memories_causal": 1, "tool_calls": 318,
-//      "retrospectives": 7, "tool_count": 21,
+ //      "memories_pattern": 0, "memories_causal": 1, "tool_calls": 318,
+ //      "retrospectives": 7, "tool_count": 23,
 //      "metrics": { "tokens_injected_pre_prompt": 51, "tokens_injected_compacting": 0,
 //                   "reflections_throttled": 3, "duplicate_suppressions": 2,
 //                   "tool_calls_deduped": 0, "patterns_mined": 0,
@@ -384,11 +384,45 @@ Ingests the OKF file (asserts → shared-layer projections; tombstones → archi
 ```
 kevin_sync({})
 // → { "path": ".kevin/knowledge.okf", "fileHash": "3d2f...", "parsed": 1,
-//      "folded": 0, "rejected": 0, "imported": 1, "tombstoned": 0,
-//      "skipped": false }
+ //      "folded": 0, "rejected": 0, "imported": 1, "tombstoned": 0,
+ //      "skipped": false }
 ```
 
----
+### `kevin_doctor`
+
+Read-only health check — no writes, no probe re-run, no model call. Returns `host`, `hooks`, `dependencies`, `native`, `verdict` and `reason`; `hooks` is sorted dead first so the failure is the first thing on screen. Output contains no filesystem paths or session ids — paste it into an issue report.
+
+```
+kevin_doctor({})
+// → { "host": { "plugin_version": "1.18.18", "flavour": "v1+v2", "shell_available": true,
+//                "v2": { "skill": true, "reference": true } },
+//      "hooks": [{ "hook": "experimental.chat.system.transform", "state": "dead",
+//                  "fire_count": 0, "expected_count": 3, "since": "2026-08-20T10:00:00Z" },
+//                { "hook": "tool.execute.after", "state": "live", "fire_count": 42, "expected_count": 42 }],
+//      "dependencies": { "declared": ["@opencode-ai/plugin"], "zod_copies": 1 },
+//      "native": { "enabled": true, "registered": { "skill": true, "reference": true },
+//                  "verified": { "skill": true, "reference": true } },
+//      "verdict": "degraded", "reason": "experimental.chat.system.transform dead since 2026-08-20T10:00:00Z; 1 affected hook(s)", "partial": false }
+```
+
+One dead hook is enough for `degraded`; every hook `live` is `healthy`; otherwise `unknown` — `unknown` is never rounded to `healthy` (D9-09). With no sessions yet, `verdict` is `unknown`.
+
+### `kevin_native`
+
+Controls the additive v2 attachment (D9-01): `show` reports the setting, the frozen probe result and the latest `native_registrations` rows; `enable`/`disable` write `kevin_settings` only and never re-probe — a restart is required for the change to take effect. The value is TEXT `"1"`/`"0"`; `enable` on a host without the v2 subpath succeeds and reports `effective: false` (inert) rather than refusing.
+
+```
+kevin_native({ action: "show" })
+// → { "action": "show", "value": "0", "effective": true,
+//      "registrations": [{ "surface": "skill", "registered": true, "verified": true, "attached_at": "2026-08-20T10:00:00Z" }] }
+
+kevin_native({ action: "enable" })
+// → { "action": "enable", "value": "1", "effective": false,
+//      "reason": "v2 subpath absent from the resolved host package — registration would be inert",
+//      "note": "the probe is frozen for the process lifetime — restart the host for the change to take effect" }
+```
+
+---
 
 ## How Kevin measures itself
 
@@ -645,7 +679,7 @@ KevinPlugin(input, {
 
 ### Settings
 
-Read/write via `kevin_config({ action: "list" | "set", ... })`. All 23 values are TEXT; booleans compare against `"1"`.
+Read/write via `kevin_config({ action: "list" | "set", ... })`. All 27 values are TEXT; booleans compare against `"1"`.
 
 | Setting | Default | Effect |
 |---|---|---|
@@ -672,8 +706,12 @@ Read/write via `kevin_config({ action: "list" | "set", ... })`. All 23 values ar
 | `share_requires_approval` | `"1"` | When `"1"`, `kevin_share` writes only with `confirm: true`; un-curated memories are refused with `not_curated` |
 | `author_identity_mode` | `"hashed"` | Author attribution in exports: `"hashed"` or `"none"` (**string** enum) |
 | `shared_confidence_floor` | `"0.7"` | Gate for `kevin_share` selection and export — a **string**, read with `Number.parseFloat` and clamped to `[0, 1]`. Deliberately stricter than `injection_confidence_floor` (`0.6`): sharing is a commitment, injecting is a suggestion. `parseInt` on this setting would yield `0` and share everything |
+| `hook_liveness_enabled` | `"1"` | Master switch for the liveness instrument. When `"0"`, `HookLiveness.wrap()` returns hooks untouched and no counters are recorded — compare with `=== "1"` |
+| `native_registration_enabled` | `"0"` | Opt-in for the additive v2 attachment (`skill.transform`/`reference.transform` via `define()`). Default `"0"` keeps the release byte-identical to v0.8.0; `kevin_native enable` sets `"1"` (TEXT) but the probe is frozen — restart required (D9-01) |
+| `host_probe_history_enabled` | `"0"` | When `"1"`, one `host_probes` row per construction is appended (version, flavour, v2 flags, notes). Off by default because it is unbounded append-only |
+| `dead_hook_report_threshold` | `"3"` | How many checkpointed sessions without a hook firing before it is `dead`. TEXT holding a number, read with `Number.parseInt(v, 10)`, clamped to `[1, 1000]`, `NaN` → `3` |
 
-All 23 settings are TEXT values; booleans and flags compare against `"1"`; the three v0.8 **string-valued** settings are `okf_path`, `author_identity_mode` and `shared_confidence_floor`.
+All 27 settings are TEXT values; booleans and flags compare against `"1"`; the three v0.8 **string-valued** settings are `okf_path`, `author_identity_mode` and `shared_confidence_floor`, and `dead_hook_report_threshold` is a numeric string.
 
 ---
 
@@ -686,10 +724,25 @@ npm install
 npm run typecheck   # tsc --noEmit (strict)
 npm run lint        # biome check .
 npm test            # vitest run (unit + integration + e2e + replay)
-npm run verify      # post-install verification
+npm run verify      # post-install verification (also checks DB migrations)
 npm run replay      # replay report over tests/replay/fixtures
 ```
 
+### Quick diagnostic
+
+```bash
+# One read-only command that tells you whether Kevin is healthy:
+# host surface, every hook's state, dependency check, and native registration.
+kevin_doctor({})
+# → { host: { flavour: "v1+v2", v2: { skill: true, reference: true } },
+#      hooks: [{ hook: "experimental.chat.system.transform", state: "dead", ... }],
+#      verdict: "degraded", reason: "experimental.chat.system.transform dead since ..." }
+
+# Native registration is opt-in (default off). Enable, restart, check again:
+kevin_native({ action: "enable" })   # writes native_registration_enabled="1" (TEXT), no re-probe
+kevin_native({ action: "show" })     # → { effective: false, reason: "v2 subpath absent …" } on 1.17.x
+```
+
 ### Publishing (maintainer)
 
 ```bash

package/dist/migrations/010_v09_native.sql

@@ -0,0 +1,78 @@
+-- ============================================================
+-- Kevin v0.9.0 "Native" — host surface and hook liveness
+-- Migration 010. Additive only. No table rebuild.
+-- ============================================================
+
+-- 1. Hook liveness. Deliberately NOT project-scoped: a hook is a
+--    property of the host binary, not of a checkout. One row per
+--    hook name, updated in place. See D9-08.
+CREATE TABLE IF NOT EXISTS hook_liveness (
+	hook            TEXT PRIMARY KEY,
+	experimental    INTEGER NOT NULL DEFAULT 0,
+	fire_count      INTEGER NOT NULL DEFAULT 0,
+	error_count     INTEGER NOT NULL DEFAULT 0,
+	expected_count  INTEGER NOT NULL DEFAULT 0,
+	first_seen_at   TEXT,
+	last_seen_at    TEXT,
+	dead_since      TEXT,
+	plugin_version  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_hook_liveness_dead
+	ON hook_liveness(dead_since);
+
+-- 2. Host probe history. Append-only. Off by default; exists so a
+--    user chasing an intermittent fault can turn it on and get a
+--    timeline instead of a single current value.
+CREATE TABLE IF NOT EXISTS host_probes (
+	id              TEXT PRIMARY KEY,
+	probed_at       TEXT NOT NULL DEFAULT (datetime('now')),
+	plugin_version  TEXT,
+	flavour         TEXT NOT NULL,
+	has_shell       INTEGER NOT NULL DEFAULT 0,
+	v2_skill        INTEGER NOT NULL DEFAULT 0,
+	v2_reference    INTEGER NOT NULL DEFAULT 0,
+	notes           TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_host_probes_at
+	ON host_probes(probed_at);
+
+-- 3. Native registration outcomes. One row per attach attempt, so
+--    "registered but unverified" is a queryable state rather than a
+--    log line.
+CREATE TABLE IF NOT EXISTS native_registrations (
+	id              TEXT PRIMARY KEY,
+	attached_at     TEXT NOT NULL DEFAULT (datetime('now')),
+	surface         TEXT NOT NULL CHECK (surface IN ('skill', 'reference')),
+	registered      INTEGER NOT NULL DEFAULT 0,
+	verified        INTEGER NOT NULL DEFAULT 0,
+	note            TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_native_registrations_surface
+	ON native_registrations(surface, attached_at);
+
+-- 4. Metric seeds (39 -> 45).
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+	('hook_fires_total',                0),
+	('hook_errors_total',               0),
+	('hooks_dead_total',                0),
+	('injections_suppressed_dead_hook', 0),
+	('native_registrations_total',      0),
+	('native_registration_failures',    0);
+
+-- 5. Setting seeds (23 -> 27).
+--    hook_liveness_enabled defaults ON: it is a read-only instrument
+--    on the success path, and an instrument nobody switches on is an
+--    instrument nobody has.
+--    native_registration_enabled defaults OFF: it changes where a
+--    curated skill comes from, and that is a change a user opts into.
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+	('hook_liveness_enabled',       '1'),
+	('native_registration_enabled', '0'),
+	('host_probe_history_enabled',  '0'),
+	('dead_hook_report_threshold',  '3');
+
+-- 6. Version marker.
+INSERT OR IGNORE INTO schema_version (version) VALUES ('010');

package/dist/plugin/HookLiveness.d.ts

@@ -0,0 +1,81 @@
+import { HOOK_NAMES } from "./Migrate.js";
+import type { Store } from "./Store.js";
+export type HookName = (typeof HOOK_NAMES)[number];
+export type LivenessState = "live" | "dead" | "unknown";
+export interface HookReport {
+    hook: HookName;
+    experimental: boolean;
+    state: LivenessState;
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+    fireCount: number;
+    expectedCount: number;
+    /** v0.9.0 (K9-012) — set once when the hook went dead; never cleared. */
+    deadSince: string | null;
+}
+/**
+ * v0.9.0 (K9-010 / plan §5.3, D9-09) — parse the TEXT setting
+ * `dead_hook_report_threshold` into the [1, 1000] clamp. NaN and empty
+ * fall back to 3 (never 0: a zero threshold would report every hook dead
+ * before a single session completes a checkpoint).
+ */
+export declare function parseThreshold(text: string | null | undefined): number;
+interface HookLivenessOptions {
+    /** `hook_liveness_enabled === "1"` (TEXT comparison, decided at construction). */
+    enabled: boolean;
+    /** Raw TEXT of `dead_hook_report_threshold`; parsed+clamped in report(). */
+    thresholdText: string | null | undefined;
+    /** `host.pluginVersion` at construction, stored on every flushed row. */
+    pluginVersion: string | null;
+}
+/**
+ * v0.9.0 (K9-009/K9-010 / plan §5.3) — wraps the plugin's hooks with a
+ * success-path recorder, dedups per-session checkpoints, and reports each
+ * hook's liveness state. Persistence is machine-scoped: the hook_liveness
+ * table carries no project_id or repo_id (D9-08).
+ */
+export declare class HookLiveness {
+    private readonly store;
+    private readonly options;
+    private readonly counters;
+    private readonly seenSessions;
+    private readonly suppressedSessions;
+    private readonly threshold;
+    private readonly pluginVersion;
+    constructor(store: Store, options: HookLivenessOptions);
+    /**
+     * Returns a new object with the same keys; function values are replaced
+     * by delegating wrappers, non-function values (the tool map) pass by
+     * reference. When liveness is disabled, returns the argument unchanged —
+     * the same object, not a copy.
+     */
+    wrap<T>(hooks: T): T;
+    /**
+     * v0.9.0 (K9-010 / plan §5.3) — a checkpoint: the session reached a
+     * model turn (tool.execute.after fired), so the system prompt was
+     * assembled and `experimental.chat.system.transform` MUST have been
+     * offered. Deduped per session: 20 tool calls in one session count
+     * exactly one expectation.
+     */
+    expect(hook: HookName, sessionID: string): void;
+    /**
+     * Per-hook liveness verdicts in canonical HOOK_NAMES order.
+     * A hook that fired once is live forever; dead requires both zero fires
+     * and `expectedCount >= threshold`; everything else is unknown — and
+     * unknown is never rounded to healthy (D9-09).
+     */
+    report(): HookReport[];
+    /** Persists every counter row. Called on the metrics.flush() cadence. */
+    flush(): void;
+    private makeWrapper;
+    private recordSuccess;
+    private recordError;
+    private loadFromDb;
+}
+export type HostVerdict = "healthy" | "degraded" | "unknown";
+export interface HostVerdictResult {
+    verdict: HostVerdict;
+    reason: string;
+}
+export declare function reduceVerdict(reports: readonly HookReport[]): HostVerdictResult;
+export {};

package/dist/plugin/HookLiveness.js

@@ -0,0 +1,324 @@
+import { HOOK_NAMES } from "./Migrate.js";
+const DEFAULT_THRESHOLD = 3;
+/**
+ * v0.9.0 (K9-010 / plan §5.3, D9-09) — parse the TEXT setting
+ * `dead_hook_report_threshold` into the [1, 1000] clamp. NaN and empty
+ * fall back to 3 (never 0: a zero threshold would report every hook dead
+ * before a single session completes a checkpoint).
+ */
+export function parseThreshold(text) {
+    if (text === null || text === undefined || text === "")
+        return DEFAULT_THRESHOLD;
+    const n = Number.parseInt(text, 10);
+    // NaN → default; 0 is not a valid threshold (K9-010 AC: 'abc'/''/'0'
+    // all clamp to the default of three — never zero).
+    if (Number.isNaN(n) || n === 0)
+        return DEFAULT_THRESHOLD;
+    return Math.min(1000, Math.max(1, n));
+}
+/**
+ * v0.9.0 (K9-009/K9-010 / plan §5.3) — wraps the plugin's hooks with a
+ * success-path recorder, dedups per-session checkpoints, and reports each
+ * hook's liveness state. Persistence is machine-scoped: the hook_liveness
+ * table carries no project_id or repo_id (D9-08).
+ */
+export class HookLiveness {
+    store;
+    options;
+    counters;
+    seenSessions;
+    suppressedSessions = new Set();
+    threshold;
+    pluginVersion;
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+        this.threshold = parseThreshold(options.thresholdText);
+        this.pluginVersion = options.pluginVersion;
+        this.counters = new Map();
+        this.seenSessions = new Map();
+        for (const hook of HOOK_NAMES) {
+            this.counters.set(hook, {
+                fireCount: 0,
+                errorCount: 0,
+                expectedCount: 0,
+                firstSeenAt: null,
+                lastSeenAt: null,
+                deadSince: null,
+            });
+            this.seenSessions.set(hook, new Set());
+        }
+        this.loadFromDb();
+    }
+    /**
+     * Returns a new object with the same keys; function values are replaced
+     * by delegating wrappers, non-function values (the tool map) pass by
+     * reference. When liveness is disabled, returns the argument unchanged —
+     * the same object, not a copy.
+     */
+    wrap(hooks) {
+        if (!this.options.enabled)
+            return hooks;
+        const out = {};
+        for (const [key, value] of Object.entries(hooks)) {
+            if (typeof value === "function") {
+                out[key] = this.makeWrapper(key, value);
+            }
+            else {
+                out[key] = value;
+            }
+        }
+        return out;
+    }
+    /**
+     * v0.9.0 (K9-010 / plan §5.3) — a checkpoint: the session reached a
+     * model turn (tool.execute.after fired), so the system prompt was
+     * assembled and `experimental.chat.system.transform` MUST have been
+     * offered. Deduped per session: 20 tool calls in one session count
+     * exactly one expectation.
+     */
+    expect(hook, sessionID) {
+        const seen = this.seenSessions.get(hook);
+        if (!seen || seen.has(sessionID))
+            return;
+        seen.add(sessionID);
+        const counters = this.counters.get(hook);
+        if (!counters)
+            return;
+        counters.expectedCount += 1;
+        // The dead flag is materialized here (not only in report()) so that
+        // flush() persists dead_since even when no report() was ever called:
+        // kevin_doctor's PURE-SQL blocks read dead_since from the table.
+        if (counters.fireCount === 0 &&
+            counters.expectedCount >= this.threshold &&
+            counters.deadSince === null) {
+            counters.deadSince = counters.lastSeenAt ?? new Date().toISOString();
+        }
+        // v0.9.0 (K9-011 / plan §5.3) — when the injection hook is dead, the
+        // checkpointed session was suppressed: the host stopped offering the
+        // transform, so no injection could happen. Counted once per session
+        // (same dedup as expected_count) and persisted by flush(). This is
+        // the counter that turns "zero injections" from an ambiguous number
+        // into a diagnosis.
+        if (hook === "experimental.chat.system.transform" &&
+            counters.deadSince !== null &&
+            !this.suppressedSessions.has(sessionID)) {
+            this.suppressedSessions.add(sessionID);
+        }
+    }
+    /**
+     * Per-hook liveness verdicts in canonical HOOK_NAMES order.
+     * A hook that fired once is live forever; dead requires both zero fires
+     * and `expectedCount >= threshold`; everything else is unknown — and
+     * unknown is never rounded to healthy (D9-09).
+     */
+    report() {
+        const out = [];
+        for (const hook of HOOK_NAMES) {
+            const c = this.counters.get(hook);
+            if (!c)
+                continue;
+            let state;
+            if (c.fireCount > 0) {
+                state = "live";
+            }
+            else if (c.expectedCount >= this.threshold) {
+                // dead_since is set ONCE and never cleared: it documents the
+                // historical death even if the hook later recovers.
+                if (c.deadSince === null) {
+                    c.deadSince = c.lastSeenAt ?? new Date().toISOString();
+                }
+                state = "dead";
+            }
+            else {
+                state = "unknown";
+            }
+            out.push({
+                hook,
+                experimental: hook.startsWith("experimental."),
+                state,
+                firstSeenAt: c.firstSeenAt,
+                lastSeenAt: c.lastSeenAt,
+                fireCount: c.fireCount,
+                expectedCount: c.expectedCount,
+                deadSince: c.deadSince,
+            });
+        }
+        return out;
+    }
+    /** Persists every counter row. Called on the metrics.flush() cadence. */
+    flush() {
+        const store = this.store;
+        store.transaction(() => {
+            // Created lazily on first flush, mirroring Metrics.flush(): the
+            // migration guarantees the table in production, but unit tests
+            // against pre-010 DBs must not explode at dispose.
+            store.exec(`CREATE TABLE IF NOT EXISTS hook_liveness (
+				    hook          TEXT PRIMARY KEY,
+				    experimental  INTEGER NOT NULL DEFAULT 0,
+				    fire_count    INTEGER NOT NULL DEFAULT 0,
+				    error_count   INTEGER NOT NULL DEFAULT 0,
+				    expected_count INTEGER NOT NULL DEFAULT 0,
+				    first_seen_at TEXT,
+				    last_seen_at  TEXT,
+				    dead_since    TEXT,
+				    plugin_version TEXT
+				  )`);
+            const upsert = store.prepare(`INSERT INTO hook_liveness (hook, experimental, fire_count, error_count,
+				  expected_count, first_seen_at, last_seen_at, dead_since, plugin_version)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT(hook) DO UPDATE SET
+				   experimental = excluded.experimental,
+				   fire_count = excluded.fire_count,
+				   error_count = excluded.error_count,
+				   expected_count = excluded.expected_count,
+				   first_seen_at = excluded.first_seen_at,
+				   last_seen_at = excluded.last_seen_at,
+				   dead_since = excluded.dead_since,
+				   plugin_version = excluded.plugin_version`);
+            for (const [hook, c] of this.counters) {
+                upsert.run(hook, hook.startsWith("experimental.") ? 1 : 0, c.fireCount, c.errorCount, c.expectedCount, c.firstSeenAt, c.lastSeenAt, c.deadSince, this.pluginVersion);
+            }
+            // v0.9.0 (K9-011 / plan §5.3) — the four v0.9.0 counters are
+            // re-derived here, on the metrics cadence, exactly like the 009
+            // post-apply hook re-derives hooks_dead_total: SUM(fire_count),
+            // SUM(error_count), COUNT(dead_since) and the per-session
+            // suppression count. No Metrics dependency, no writes in the hot
+            // path — flush() is the single persistence point.
+            let fireSum = 0;
+            let errorSum = 0;
+            let deadCount = 0;
+            for (const c of this.counters.values()) {
+                fireSum += c.fireCount;
+                errorSum += c.errorCount;
+                if (c.deadSince !== null)
+                    deadCount += 1;
+            }
+            store.exec(`CREATE TABLE IF NOT EXISTS kevin_metrics (
+				    key        TEXT PRIMARY KEY,
+				    value      INTEGER NOT NULL DEFAULT 0,
+				    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+				  )`);
+            const derive = store.prepare(`INSERT INTO kevin_metrics (key, value, updated_at)
+				 VALUES (?, ?, datetime('now'))
+				 ON CONFLICT(key) DO UPDATE SET
+				   value = excluded.value,
+				   updated_at = datetime('now')`);
+            derive.run("hook_fires_total", fireSum);
+            derive.run("hook_errors_total", errorSum);
+            derive.run("hooks_dead_total", deadCount);
+            derive.run("injections_suppressed_dead_hook", this.suppressedSessions.size);
+        });
+    }
+    makeWrapper(key, delegate) {
+        const record = () => {
+            if (HOOK_NAMES.includes(key)) {
+                this.recordSuccess(key);
+            }
+        };
+        const recordError = (e) => {
+            if (HOOK_NAMES.includes(key)) {
+                this.recordError(key);
+            }
+            throw e;
+        };
+        const n = delegate.length;
+        if (n === 0) {
+            return async () => {
+                try {
+                    const result = await delegate();
+                    record();
+                    return result;
+                }
+                catch (e) {
+                    return recordError(e);
+                }
+            };
+        }
+        if (n === 1) {
+            return async (a) => {
+                try {
+                    const result = await delegate(a);
+                    record();
+                    return result;
+                }
+                catch (e) {
+                    return recordError(e);
+                }
+            };
+        }
+        return async (a, b) => {
+            try {
+                const result = await delegate(a, b);
+                record();
+                return result;
+            }
+            catch (e) {
+                return recordError(e);
+            }
+        };
+    }
+    recordSuccess(hook) {
+        const c = this.counters.get(hook);
+        if (!c)
+            return;
+        c.fireCount += 1;
+        const now = new Date().toISOString();
+        if (c.firstSeenAt === null)
+            c.firstSeenAt = now;
+        c.lastSeenAt = now;
+    }
+    recordError(hook) {
+        const c = this.counters.get(hook);
+        if (!c)
+            return;
+        c.errorCount += 1;
+    }
+    loadFromDb() {
+        let rows = [];
+        try {
+            rows = this.store
+                .prepare("SELECT hook, fire_count, error_count, expected_count, first_seen_at, last_seen_at, dead_since FROM hook_liveness")
+                .all();
+        }
+        catch {
+            // Graceful: pre-010 DBs have no hook_liveness table; the seeded
+            // zeros remain until the first flush creates rows.
+            rows = [];
+        }
+        for (const row of rows) {
+            if (!HOOK_NAMES.includes(row.hook))
+                continue;
+            const c = this.counters.get(row.hook);
+            if (!c)
+                continue;
+            c.fireCount = row.fire_count;
+            c.errorCount = row.error_count;
+            c.expectedCount = row.expected_count;
+            c.firstSeenAt = row.first_seen_at;
+            c.lastSeenAt = row.last_seen_at;
+            c.deadSince = row.dead_since;
+        }
+    }
+}
+export function reduceVerdict(reports) {
+    if (reports.length === 0) {
+        return { verdict: "unknown", reason: "no hook reports yet" };
+    }
+    const dead = reports.filter((r) => r.state === "dead");
+    if (dead.length > 0) {
+        return {
+            verdict: "degraded",
+            reason: `${dead.map((r) => r.hook).join(", ")} dead since ${dead[0].deadSince ?? "unknown"}; ${dead.length} affected hook(s)`,
+        };
+    }
+    if (reports.every((r) => r.state === "live")) {
+        return { verdict: "healthy", reason: "all hooks live" };
+    }
+    const pending = reports.filter((r) => r.state === "unknown").length;
+    return {
+        verdict: "unknown",
+        reason: `${pending} hook(s) without checkpoint`,
+    };
+}
+//# sourceMappingURL=HookLiveness.js.map

package/dist/plugin/HookLiveness.js.map

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

package/dist/plugin/Materializer.d.ts

@@ -30,13 +30,32 @@ export interface BundleTarget {
     readonly path: string;
 }
 export declare const SKILL_TOPIC = "project-knowledge";
+/**
+ * v0.9.0 (K9-016 / plan §5.4, D9-10) — the native registration surfaces.
+ * Registration replaces emission; they are never both active.
+ */
+export type NativeSurface = "skill" | "reference";
 export declare class Materializer {
     private readonly store;
     /** `root` is injectable for tests; production defaults to ~/.opencode-kevin. */
     private readonly root;
+    /**
+     * v0.9.0 (K9-016 / plan §5.4, D9-10) — the mutual-exclusion guard.
+     * A surface `attachNative()` registered is skipped by `materialize()`
+     * for that surface only; the other surface keeps emitting.
+     */
+    private readonly nativeRegistered;
     constructor(store: Store, options?: {
         root?: string;
     });
+    /**
+     * v0.9.0 (K9-016 / plan §5.4, D9-10) — record whether the surface was
+     * registered natively. Called at attach time (index.ts wiring, K9-018)
+     * with each `NativeRegistration.registered` flag.
+     */
+    markNativeRegistered(surface: NativeSurface, registered: boolean): void;
+    /** v0.9.0 (K9-016 / plan §5.4, D9-10) — is the surface registered natively? */
+    hasNativeRegistration(surface: NativeSurface): boolean;
     /** The curated, active memories — the knowledge the pull channels publish. */
     private curatedRows;
     /** The rendered skill body over all curated memories; "" when empty. */
@@ -53,6 +72,12 @@ export declare class Materializer {
      * a call site of `write()` — the single write FUNCTION with two
      * constrained targets: `kevin_approve` reaches `agents_md_path`, this
      * module reaches `~/.opencode-kevin` only (D6-07; enforced by K6-020).
+     *
+     * v0.9.0 (K9-016 / plan §5.4, D9-10) — the guard: a surface registered
+     * natively by `attachNative()` is skipped here for that surface only.
+     * Both active would put the curated skill in front of the model twice
+     * from two sources that can disagree; neither active would silently
+     * remove the feature on hosts that gained the subpath.
      */
     materialize(writer: ArtifactWriter): MaterializedBundle[];
 }