@jmtrin/opencode-kevin 0.8.0 → 1.0.0

package/dist/plugin/HookLiveness.js

@@ -0,0 +1,338 @@
+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 = () => {
+            // v1.0.0 (K10-013) — dispose is recorded inside its own delegate
+            // (via recordDispose()) rather than here: the wrapper's post-return
+            // record would land after the store is closed and could never be
+            // persisted — the event being detected is the process ending.
+            if (key === "dispose")
+                return;
+            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);
+            }
+        };
+    }
+    /**
+     * v1.0.0 (K10-013 / plan §5.3) — records the `dispose` fire and
+     * flushes immediately, from inside the dispose delegate: this is the
+     * last write of the process, and nothing after it can persist.
+     */
+    recordDispose() {
+        this.recordSuccess("dispose");
+        this.flush();
+    }
+    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`,
+    };
+}

package/dist/plugin/InjectionLedger.js

@@ -246,4 +246,3 @@ function readOriginCallId(store, memoryId) {
         return null;
     }
 }
-//# sourceMappingURL=InjectionLedger.js.map

package/dist/plugin/LessonFixer.js

@@ -43,4 +43,3 @@ export async function enrichAtPromotion(pattern, enrichFn) {
     }
     return deterministicFixLine(pattern);
 }
-//# sourceMappingURL=LessonFixer.js.map

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[];
 }

package/dist/plugin/Materializer.js

@@ -141,10 +141,31 @@ export class Materializer {
     store;
     /** `root` is injectable for tests; production defaults to ~/.opencode-kevin. */
     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.
+     */
+    nativeRegistered = new Set();
     constructor(store, options = {}) {
         this.store = store;
         this.root = options.root ?? join(homedir(), ".opencode-kevin");
     }
+    /**
+     * 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, registered) {
+        if (registered)
+            this.nativeRegistered.add(surface);
+        else
+            this.nativeRegistered.delete(surface);
+    }
+    /** v0.9.0 (K9-016 / plan §5.4, D9-10) — is the surface registered natively? */
+    hasNativeRegistration(surface) {
+        return this.nativeRegistered.has(surface);
+    }
     /** The curated, active memories — the knowledge the pull channels publish. */
     curatedRows() {
         return this.store
@@ -204,27 +225,35 @@ export 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) {
         const pending = [];
         const rows = this.curatedRows();
         const skillBody = renderRows(rows);
-        if (skillBody !== "") {
+        if (skillBody !== "" && !this.nativeRegistered.has("skill")) {
             pending.push({
                 topic: SKILL_TOPIC,
                 path: join(this.root, "skills", "project-knowledge.md"),
                 body: skillBody,
             });
         }
-        for (const group of this.groupByTopic(rows)) {
-            const body = renderRows(group.rows);
-            if (body === "")
-                continue;
-            pending.push({
-                topic: group.topic,
-                path: join(this.root, "refs", `${group.topic}.md`),
-                body,
-            });
+        if (!this.nativeRegistered.has("reference")) {
+            for (const group of this.groupByTopic(rows)) {
+                const body = renderRows(group.rows);
+                if (body === "")
+                    continue;
+                pending.push({
+                    topic: group.topic,
+                    path: join(this.root, "refs", `${group.topic}.md`),
+                    body,
+                });
+            }
         }
         return pending.map((bundle) => ({
             topic: bundle.topic,
@@ -237,4 +266,3 @@ export class Materializer {
         }));
     }
 }
-//# sourceMappingURL=Materializer.js.map

package/dist/plugin/MemoryService.js

@@ -1333,4 +1333,3 @@ function rankCompare(a, b, nowMs, deterministic) {
     }
     return sqliteUtcToMs(b.createdAt) - sqliteUtcToMs(a.createdAt); // newer first
 }
-//# sourceMappingURL=MemoryService.js.map

package/dist/plugin/Migrate.d.ts

@@ -5,6 +5,7 @@ export interface MigrateResult {
     applied: string[];
 }
 export type PostApplyHook = (store: Store) => void;
+export declare const HOOK_NAMES: readonly ["tool.execute.before", "tool.execute.after", "chat.message", "experimental.chat.system.transform", "experimental.session.compacting", "event", "dispose"];
 export declare class Migrate {
     private store;
     private migrationsDir;

package/dist/plugin/Migrate.js

@@ -1,5 +1,20 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+// v0.9.0 (K9-001 / plan §5.3, D9-08) — the six hooks Kevin registers, in
+// hook-object order, plus `dispose` (v1.0.0 K10-013): the seventh
+// instrumented hook. Canonical list: the "010" post-apply hook seeds
+// hook_liveness from it, and HookLiveness (K9-009) wraps exactly these
+// names, so a future hook added here is visible in the table on the next
+// migration run.
+export const HOOK_NAMES = [
+    "tool.execute.before",
+    "tool.execute.after",
+    "chat.message",
+    "experimental.chat.system.transform",
+    "experimental.session.compacting",
+    "event",
+    "dispose",
+];
 // Built-in post-apply hooks, keyed by migration version. Each hook runs inside
 // the same transaction as the migration's DDL, so a hook failure rolls back the
 // whole migration. Hooks run when their version is applied. Migration 008's
@@ -125,6 +140,49 @@ const DEFAULT_POST_APPLY_HOOKS = {
             .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM shared_entries) WHERE key = 'shared_entries_total'")
             .run();
     },
+    // v0.9.0 (K9-001 / plan §6.1, D9-08) — Native: three operations, all
+    // idempotent by design.
+    // 1. Seed one hook_liveness row per name in HOOK_NAMES, with the
+    //    experimental flag derived from the hook's own `experimental.`
+    //    prefix and every counter at zero. Seeding eagerly (INSERT OR
+    //    IGNORE) makes a hook that has never fired a visible row with
+    //    fire_count = 0, not an absent row indistinguishable from a hook
+    //    Kevin does not register.
+    // 2. Re-derive hooks_dead_total from hook_liveness state rather than
+    //    trusting an incremented value (same discipline as "006"-"009").
+    // 3. Normalize any experimental flag that disagrees with its own
+    //    hook column's prefix — cheap, and it repairs a row hand-edited
+    //    during debugging.
+    "010": (store) => {
+        const seed = store.prepare("INSERT OR IGNORE INTO hook_liveness (hook, experimental) VALUES (?, ?)");
+        for (const name of HOOK_NAMES) {
+            seed.run(name, name.startsWith("experimental.") ? 1 : 0);
+        }
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM hook_liveness WHERE dead_since IS NOT NULL) WHERE key = 'hooks_dead_total'")
+            .run();
+        store
+            .prepare("UPDATE hook_liveness SET experimental = CASE WHEN hook LIKE 'experimental.%' THEN 1 ELSE 0 END")
+            .run();
+    },
+    // v1.0.0 (K10-005 / plan §6.1) — Proven: four operations, all idempotent.
+    // 1. Seed dispose row defensively.
+    // 2-3. Re-derive perf_budget_breaches and bench_runs_total.
+    // 4. Normalise NULL within_budget to 1.
+    "011": (store) => {
+        store
+            .prepare("INSERT OR IGNORE INTO hook_liveness (hook) VALUES ('dispose')")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM perf_samples WHERE within_budget = 0) WHERE key = 'perf_budget_breaches'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM bench_runs) WHERE key = 'bench_runs_total'")
+            .run();
+        store
+            .prepare("UPDATE perf_samples SET within_budget = 1 WHERE within_budget IS NULL")
+            .run();
+    },
 };
 export class Migrate {
     store;
@@ -155,11 +213,17 @@ export class Migrate {
             // v0.7.0 (K7-002) — heal drift in the 008 counters on a no-op
             // startup while preserving `applied: []` idempotency. v0.8.0
             // (K8-002 / plan §6.1) extends the same repair to the 009
-            // back-fill and the shared_entries_total re-derivation: both
-            // hooks are idempotent by guarded updates and re-derivation,
-            // so a no-op startup can heal a crash that landed between the
-            // ALTER and the hook without re-applying DDL.
-            if (from === "008" || from === "009") {
+            // back-fill and the shared_entries_total re-derivation, and
+            // v0.9.0 (K9-001 / plan §6.1) to the 010 seeding,
+            // hooks_dead_total re-derivation and experimental
+            // normalization: all three hooks are idempotent by guarded
+            // updates and re-derivation, so a no-op startup can heal a
+            // crash that landed between the DDL and the hook without
+            // re-applying DDL.
+            if (from === "008" ||
+                from === "009" ||
+                from === "010" ||
+                from === "011") {
                 const repairHook = this.postApplyHooks.get(from);
                 if (repairHook)
                     this.store.transaction(() => repairHook(this.store));
@@ -200,4 +264,3 @@ export class Migrate {
             .filter((m) => m !== null && m.version > current);
     }
 }
-//# sourceMappingURL=Migrate.js.map

package/dist/plugin/PatternMiner.js

@@ -130,4 +130,3 @@ export class PatternMiner {
         return Array.from(map.values());
     }
 }
-//# sourceMappingURL=PatternMiner.js.map

package/dist/plugin/QualityGate.js

@@ -117,4 +117,3 @@ export const QualityGate = {
         return { allowed: true, reason: "ok" };
     },
 };
-//# sourceMappingURL=QualityGate.js.map

package/dist/plugin/Reflector.js

@@ -305,4 +305,3 @@ export class Reflector {
         return "";
     }
 }
-//# sourceMappingURL=Reflector.js.map

package/dist/plugin/RepoIdentity.d.ts

@@ -1,8 +1,9 @@
 import type { ArtifactWriter } from "./ArtifactWriter.js";
+import type { HostSurface } from "./host.js";
 /**
- * The three sources `resolve()` tries, in order (plan §5.1).
+ * The four sources `resolve()` tries, in order (plan §5.2, D9-13).
  */
-export type IdentitySource = "declared" | "remote" | "path";
+export type IdentitySource = "declared" | "remote" | "host" | "path";
 /**
  * The outcome of resolving a repository identity.
  */
@@ -58,8 +59,8 @@ export declare function normalizeRemote(url: string): string | null;
  */
 export declare function computeRepoId(normalized: string): string;
 /**
- * Resolve the repository identity for `cwd`, trying the three
- * sources in order (plan §5.1):
+ * Resolve the repository identity for `cwd`, trying the four
+ * sources in order (plan §5.2, D9-13):
  *
  *   1. `declared` — `.kevin/project.json` → `id` (validated as
  *      exactly 16 lowercase hex characters; anything else is ignored
@@ -68,14 +69,24 @@ export declare function computeRepoId(normalized: string): string;
  *      onto a typo);
  *   2. `remote` — `.git/config` → `[remote "origin"] url`,
  *      normalized and hashed;
- *   3. `path` — `fingerprint(cwd)`, the v0.7.0 behaviour.
+ *   3. `host` — the value the host resolved for this directory,
+ *      `host.project.worktree` first, `host.project.directory` as
+ *      fallback; both empty or absent falls through to `path`.
+ *      This is strictly better than `process.cwd()` — the host's own
+ *      ToolContext documents "prefer this over `process.cwd()`" —
+ *      but it sits below the explicit sources, because monorepos and
+ *      D8-03's confirmed re-keying depend on `.kevin/project.json`
+ *      winning;
+ *   4. `path` — `fingerprint(cwd)`, the v0.7.0 behaviour, preserved
+ *      exactly when `host` is absent.
  *
  * Never throws: a directory that is not a git repository, an
- * unreadable `.git/config`, and a malformed `project.json` all fall
- * through to source 3. `projectId` is always returned alongside
- * `repoId`, regardless of which source won.
+ * unreadable `.git/config`, a malformed `project.json`, and a host
+ * with no usable project fields all fall through to source 4.
+ * `projectId` is always returned alongside `repoId`, regardless of
+ * which source won.
  */
-export declare function resolve(cwd: string): ResolvedIdentity;
+export declare function resolve(cwd: string, host?: HostSurface): ResolvedIdentity;
 /**
  * The outcome of `initProjectFile` (K8-008).
  */