@davesheffer/hunch 1.32.3 → 1.32.5

package/dist/core/io.js

@@ -1,5 +1,5 @@
 /** Durable file writes for the Hunch. */
-import { closeSync, fsyncSync, linkSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+import { closeSync, fchmodSync, fsyncSync, linkSync, lstatSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 let counter = 0;
 const renameRetryDelaysMs = [10, 20, 40, 80];
@@ -24,20 +24,17 @@ const renameRetryWaiter = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_
  */
 export function writeFileAtomic(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    let mode;
     try {
-        const fd = openSync(tmp, "w");
-        try {
-            writeSync(fd, data);
-            fsyncSync(fd); // data blocks reach disk before the rename's metadata can
-        }
-        finally {
-            closeSync(fd);
-        }
+        const existing = lstatSync(file);
+        if (existing.isFile())
+            mode = existing.mode & 0o777;
     }
-    catch (e) {
-        cleanupTmp(tmp);
-        throw e;
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
     }
+    writeFileAtomicTmp(tmp, data, mode);
     try {
         renameWithContentionRetry(tmp, file);
     }
@@ -85,8 +82,10 @@ function isRenameContention(error) {
  * semantics, so concurrent lifecycle writers can never be overwritten. */
 export function writeFileAtomicIfAbsent(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    // An occupied temp path is an error, not evidence that the target exists.
+    // Only enter the publication/cleanup block once we own the temporary file.
+    writeFileAtomicTmp(tmp, data);
     try {
-        writeFileAtomicTmp(tmp, data);
         linkSync(tmp, file);
         return true;
     }
@@ -104,14 +103,26 @@ export function writeFileAtomicIfAbsent(file, data) {
     }
 }
 /** Write + fsync a fresh temp file (shared by both atomic writers). */
-function writeFileAtomicTmp(tmp, data) {
-    const fd = openSync(tmp, "w");
+function writeFileAtomicTmp(tmp, data, mode) {
+    // Exclusive creation rejects stale files and links without truncating their
+    // contents. If open fails, the path belongs to somebody else: never unlink it.
+    const fd = openSync(tmp, "wx", mode ?? 0o666);
     try {
-        writeSync(fd, data);
-        fsyncSync(fd);
+        try {
+            writeFileSync(fd, data);
+            // The replacement inode must retain an existing file's permissions,
+            // including private config files that contain credentials.
+            if (mode !== undefined)
+                fchmodSync(fd, mode);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
     }
-    finally {
-        closeSync(fd);
+    catch (error) {
+        cleanupTmp(tmp);
+        throw error;
     }
 }
 /** Remove a temp file, riding out a transient external hold (AV/indexer) with one

package/dist/core/jsonc.js

@@ -24,7 +24,7 @@ export function parseJsonc(raw) {
             continue;
         }
         if (char === "/" && next === "/") {
-            while (index < raw.length && raw[index] !== "\n")
+            while (index < raw.length && raw[index] !== "\n" && raw[index] !== "\r")
                 index += 1;
             withoutComments += "\n";
             continue;
@@ -33,7 +33,12 @@ export function parseJsonc(raw) {
             index += 2;
             while (index < raw.length && !(raw[index] === "*" && raw[index + 1] === "/"))
                 index += 1;
+            if (index >= raw.length)
+                throw new SyntaxError("unterminated JSONC block comment");
             index += 1;
+            // A comment separates tokens. Removing it outright would silently turn
+            // invalid input such as 1/* comment */2 into the valid number 12.
+            withoutComments += " ";
             continue;
         }
         withoutComments += char;
@@ -62,8 +67,13 @@ export function parseJsonc(raw) {
             let cursor = index + 1;
             while (cursor < withoutComments.length && /\s/.test(withoutComments[cursor]))
                 cursor += 1;
-            if (withoutComments[cursor] === "}" || withoutComments[cursor] === "]")
-                continue;
+            if (withoutComments[cursor] === "}" || withoutComments[cursor] === "]") {
+                const previous = normalized.trimEnd().at(-1);
+                // A trailing comma must follow a value, never an empty collection or
+                // another comma. Keep malformed input intact for JSON.parse to reject.
+                if (previous && !"[{,:".includes(previous))
+                    continue;
+            }
         }
         normalized += char;
     }

package/dist/core/storeArtifact.d.ts

@@ -0,0 +1,7 @@
+/** Containment for store artifacts outside JsonStore's entity registry (ledgers,
+ * policy proofs, and local audit logs). The explicitly selected store's parent
+ * may have a platform alias, but no component inside that store may be a link. */
+export declare function storeArtifactPath(hunchDir: string, ...parts: string[]): string;
+/** A missing artifact is distinct from an unsafe/unreadable artifact. Reuse the
+ * scanner's bounded descriptor read; policy and ledger corruption must fail visibly. */
+export declare function readStoreArtifact(hunchDir: string, parts: string[], maxBytes?: number): string | null;

package/dist/core/storeArtifact.js

@@ -0,0 +1,62 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { createRepoFileReader } from "./safeRepoFile.js";
+/** Containment for store artifacts outside JsonStore's entity registry (ledgers,
+ * policy proofs, and local audit logs). The explicitly selected store's parent
+ * may have a platform alias, but no component inside that store may be a link. */
+export function storeArtifactPath(hunchDir, ...parts) {
+    let path = resolve(hunchDir);
+    let parent;
+    try {
+        parent = realpathSync(dirname(path));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        parent = dirname(path);
+    }
+    let expected = join(parent, basename(path));
+    const check = (directory) => {
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() && !stat.isDirectory())
+                || (stat.isFile() && stat.nlink !== 1) || realpathSync(path) !== expected) {
+                throw new Error(`unsafe store artifact path ${path}: symlinks, hard links and special files are refused`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    };
+    check(true);
+    for (let index = 0; index < parts.length; index++) {
+        const part = parts[index];
+        if (!/^[A-Za-z0-9._-]+$/.test(part) || part === "." || part === "..")
+            throw new Error("unsafe store artifact path component");
+        path = join(path, part);
+        expected = join(expected, part);
+        check(index < parts.length - 1);
+    }
+    return path;
+}
+/** A missing artifact is distinct from an unsafe/unreadable artifact. Reuse the
+ * scanner's bounded descriptor read; policy and ledger corruption must fail visibly. */
+export function readStoreArtifact(hunchDir, parts, maxBytes = 256 * 1024 * 1024) {
+    const file = storeArtifactPath(hunchDir, ...parts);
+    try {
+        if (!lstatSync(file).isFile())
+            throw new Error(`unsafe store artifact path ${file}: expected an ordinary file`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const text = createRepoFileReader(dirname(resolve(hunchDir)), { maxBytes })(file);
+    if (text === null)
+        throw new Error(`unsafe or unreadable store artifact ${file}`);
+    storeArtifactPath(hunchDir, ...parts);
+    return text;
+}
+//# sourceMappingURL=storeArtifact.js.map

package/dist/core/taskReport.d.ts

@@ -222,6 +222,55 @@ export declare function recordReportConformance(root: string, taskId: string, co
 export declare function recordReportCheck(root: string, taskId: string, check: ReportCheck): string;
 export declare function beginReportCheck(root: string, taskId: string, label: string): string;
 export declare function finishReportTask(root: string, taskId: string, state?: "completed" | "interrupted"): ReportTask;
+/** A report with no observation of any kind. Presentation surfaces may stay
+ * silent for it; the task row itself is retained so "never touched Hunch" is
+ * still countable (hunch report / the VS Code view / task list). */
+export declare function isEmptyTaskReport(report: Pick<TaskReport, "deliveries" | "claims" | "checks" | "conformance" | "saves" | "refusals">): boolean;
+export interface TaskSummary {
+    task: ReportTask;
+    deliveries: number;
+    lessons: number;
+    claims: number;
+    saves: number;
+    refusals: number;
+    /** Standing of the last recorded check, or null when none ran. */
+    check: {
+        label: string;
+        state: "passed" | "failed" | "timed out" | "cancelled";
+        current: boolean;
+    } | null;
+    /** Any delivered rule evaluated as violated on the changed files. */
+    violated: boolean;
+    coverage: TaskReport["coverage"];
+    empty: boolean;
+    /** Generated evidence view, when one has been written for this task. */
+    report_html: string | null;
+    /** Set when the observation ledger could not be read for this task. */
+    error: string | null;
+}
+/** One bounded summary per recent task for status lines and host views; the
+ * card and evidence view remain the authoritative renderings. */
+export declare function summarizeTaskReport(root: string, taskId: string, currentSnapshot?: string | null): TaskSummary;
+export declare function listTaskSummaries(root: string, limit?: number, currentSnapshot?: string | null): TaskSummary[];
+/** One line for a terminal status line. Empty string when nothing was observed
+ * for the task, so a bare prompt shows no Hunch noise at all. */
+export declare function renderTaskStatusLine(summary: TaskSummary | null): string;
+export interface TaskReportStats {
+    since: string;
+    tasks: number;
+    completed: number;
+    with_delivery: number;
+    with_check: number;
+    with_claim: number;
+    with_save: number;
+    with_refusal: number;
+    empty: number;
+    /** with_delivery / tasks, the adherence number worth watching; null when no tasks. */
+    delivery_rate: number | null;
+}
+/** Adherence over a window: how many prompts Hunch actually reached. Counts
+ * come from the ledger, never from agent claims; a claim is counted as a claim. */
+export declare function taskReportStats(root: string, days?: number): TaskReportStats;
 export declare function listReportTasks(root: string): ReportTask[];
 export declare function reportActivity(root: string): string;
 /** Exact task deletion is a user-invoked operation, never a memory deletion. */

package/dist/core/taskReport.js

@@ -368,6 +368,105 @@ export function finishReportTask(root, taskId, state = "completed") {
         return finished;
     }));
 }
+/** A report with no observation of any kind. Presentation surfaces may stay
+ * silent for it; the task row itself is retained so "never touched Hunch" is
+ * still countable (hunch report / the VS Code view / task list). */
+export function isEmptyTaskReport(report) {
+    return !report.deliveries.length && !report.claims.length && !report.checks.length && !report.conformance.length && !report.saves.length && !report.refusals.length;
+}
+/** One bounded summary per recent task for status lines and host views; the
+ * card and evidence view remain the authoritative renderings. */
+export function summarizeTaskReport(root, taskId, currentSnapshot = null) {
+    const html = join(root, ".hunch-cache", "reports", `${taskId}.html`);
+    try {
+        const report = readTaskReport(root, taskId, currentSnapshot);
+        const last = report.checks.at(-1);
+        const standing = new Map(report.conformance.map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r]));
+        return {
+            task: report.task,
+            deliveries: report.deliveries.length,
+            lessons: new Set(report.deliveries.flatMap(d => d.records).map(r => `${r.kind}:${r.record_id}`)).size,
+            claims: report.claims.length,
+            saves: report.saves.length,
+            refusals: report.refusals.length,
+            check: last ? { label: last.label, state: last.cancelled ? "cancelled" : last.timed_out ? "timed out" : last.exit_code === 0 ? "passed" : "failed", current: last.current } : null,
+            violated: [...standing.values()].some(r => r.outcome === "violated"),
+            coverage: report.coverage,
+            empty: isEmptyTaskReport(report),
+            report_html: existsSync(html) ? html : null,
+            error: null,
+        };
+    }
+    catch (e) {
+        return taskDb(root, db => {
+            const row = db.prepare("SELECT body FROM report_tasks WHERE task_id = ?").get(taskId);
+            if (!row)
+                throw e;
+            return { task: TaskSchema.parse(JSON.parse(row.body)), deliveries: 0, lessons: 0, claims: 0, saves: 0, refusals: 0, check: null, violated: false, coverage: "no-delivery-observed", empty: true, report_html: existsSync(html) ? html : null, error: e.message };
+        });
+    }
+}
+export function listTaskSummaries(root, limit = 30, currentSnapshot = null) {
+    if (!existsSync(join(root, ".hunch-cache", "served.db")))
+        return [];
+    return listReportTasks(root).slice(0, Math.max(1, Math.min(limit, 30))).map(task => summarizeTaskReport(root, task.task_id, currentSnapshot));
+}
+/** One line for a terminal status line. Empty string when nothing was observed
+ * for the task, so a bare prompt shows no Hunch noise at all. */
+export function renderTaskStatusLine(summary) {
+    if (!summary || summary.empty)
+        return "";
+    const parts = [`Hunch`];
+    parts.push(summary.lessons ? `${summary.lessons} lesson${summary.lessons === 1 ? "" : "s"} recalled` : summary.deliveries ? "memory delivered" : "no delivery");
+    if (summary.violated)
+        parts.push("rule violated");
+    else if (summary.claims)
+        parts.push(`${summary.claims} applied`);
+    if (summary.saves)
+        parts.push(`${summary.saves} saved`);
+    if (summary.refusals)
+        parts.push("edit denied");
+    if (summary.check)
+        parts.push(`${summary.check.label}: ${summary.check.state}${summary.check.current ? "" : " (source changed)"}`);
+    else
+        parts.push("no check recorded");
+    return parts.join(" · ");
+}
+/** Adherence over a window: how many prompts Hunch actually reached. Counts
+ * come from the ledger, never from agent claims; a claim is counted as a claim. */
+export function taskReportStats(root, days = 7) {
+    const since = new Date(Date.now() - Math.max(1, days) * 86_400_000).toISOString();
+    const empty = { since, tasks: 0, completed: 0, with_delivery: 0, with_check: 0, with_claim: 0, with_save: 0, with_refusal: 0, empty: 0, delivery_rate: null };
+    if (!existsSync(join(root, ".hunch-cache", "served.db")))
+        return empty;
+    return taskDb(root, db => {
+        const tasks = db.prepare("SELECT body FROM report_tasks WHERE scope = ? AND json_extract(body, '$.started_at') >= ?").all(scopeOf(root), since)
+            .map(r => TaskSchema.parse(JSON.parse(r.body)));
+        if (!tasks.length)
+            return empty;
+        const kinds = (taskId) => new Set(db.prepare("SELECT DISTINCT kind FROM report_events WHERE task_id = ?").all(taskId).map(r => r.kind));
+        const stats = { ...empty, tasks: tasks.length };
+        for (const task of tasks) {
+            const k = kinds(task.task_id);
+            if (task.state === "completed")
+                stats.completed++;
+            if (k.has("delivery"))
+                stats.with_delivery++;
+            if (k.has("check") || k.has("check-start"))
+                stats.with_check++;
+            if (k.has("claim"))
+                stats.with_claim++;
+            if (k.has("save"))
+                stats.with_save++;
+            if (k.has("refusal"))
+                stats.with_refusal++;
+            if (!k.size)
+                stats.empty++;
+        }
+        stats.delivery_rate = stats.with_delivery / stats.tasks;
+        return stats;
+    });
+}
 export function listReportTasks(root) {
     return taskDb(root, db => db.prepare("SELECT body FROM report_tasks WHERE scope = ? ORDER BY rowid DESC LIMIT 30").all(scopeOf(root)).map(r => TaskSchema.parse(JSON.parse(r.body))));
 }

package/dist/core/taskReportHook.d.ts

@@ -1,10 +1,16 @@
 import type { HookProvider, HunchHookInput } from "./agenthook.js";
+/** The exact task identity a Claude Code prompt maps to. The status line receives
+ * the same session_id/prompt_id on stdin, so it can name the prompt's task too. */
+export declare function promptTaskId(root: string, sessionId: string, promptId: string, agentId?: string | null, provider?: HookProvider): string;
 export declare function hookReportTaskId(root: string, provider: HookProvider, event: HunchHookInput): string | null;
 /** Every prompt receives its exact ID, even when ambient reminders were deduped.
  * No raw prompt, host session identifier, or transcript is retained. */
 export declare function startHookReport(root: string, provider: HookProvider, event: HunchHookInput): string | null;
 /** A presentation notice never denies Stop or injects another model turn. Stop
- * can precede another hook's continuation, so it does not close an open task. */
+ * can precede another hook's continuation, so it does not close an open task.
+ * A prompt with no observation at all prints nothing: the empty task row stays
+ * in the ledger (hunch task list, the VS Code Contribution view) so "never
+ * touched Hunch" remains countable without a five-line notice per prompt. */
 export declare function stopHookReport(root: string, provider: HookProvider, event: HunchHookInput): {
     systemMessage: string;
 } | null;

package/dist/core/taskReportHook.js

@@ -3,11 +3,19 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { findRoot } from "./paths.js";
-import { readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, startReportTask } from "./taskReport.js";
+import { isEmptyTaskReport, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, startReportTask } from "./taskReport.js";
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { renderTaskReport, writeTaskReportHtml } from "./taskReportRender.js";
+/** The exact task identity a Claude Code prompt maps to. The status line receives
+ * the same session_id/prompt_id on stdin, so it can name the prompt's task too. */
+export function promptTaskId(root, sessionId, promptId, agentId = null, provider = "claude") {
+    return `htask_${reportHash([realpathSync(root), provider, sessionId, promptId, agentId]).slice(7, 31)}`;
+}
+/** Hosts whose hooks deliver a native per-prompt identity (Claude Code's
+ * prompt_id, Codex's turn_id). Others get no task from a hook. */
+const NATIVE_PROMPT_HOSTS = new Set(["claude", "codex"]);
 function identity(root, provider, event) {
-    if (provider !== "claude" || !event.cwd || realpathSync(findRoot(event.cwd)) !== realpathSync(root))
+    if (!NATIVE_PROMPT_HOSTS.has(provider) || !event.cwd || realpathSync(findRoot(event.cwd)) !== realpathSync(root))
         return null;
     for (const value of [event.session_id, event.prompt_id, event.agent_id]) {
         if (value !== undefined && (!value.length || value.length > 1024 || /[\u0000-\u001f\u007f]/.test(value)))
@@ -17,7 +25,7 @@ function identity(root, provider, event) {
         return null;
     if (!event.prompt_id)
         return "legacy";
-    return `htask_${reportHash([realpathSync(root), provider, event.session_id, event.prompt_id, event.agent_id ?? null]).slice(7, 31)}`;
+    return promptTaskId(root, event.session_id, event.prompt_id, event.agent_id ?? null, provider);
 }
 export function hookReportTaskId(root, provider, event) {
     try {
@@ -38,7 +46,10 @@ export function startHookReport(root, provider, event) {
     return `Hunch has opened this prompt's report: ${task.task_id}. Reuse this exact ID for this prompt. Call hunch_task(action: "start", task_id: "${task.task_id}", title: "Claude task") to obtain verification_argv; do not create another report. Pass this task_id to hunch_context and decision/correction/finding captures, and finish with hunch_task before responding. A host Stop notice will show the evidence even if no task-linked memory was observed.`;
 }
 /** A presentation notice never denies Stop or injects another model turn. Stop
- * can precede another hook's continuation, so it does not close an open task. */
+ * can precede another hook's continuation, so it does not close an open task.
+ * A prompt with no observation at all prints nothing: the empty task row stays
+ * in the ledger (hunch task list, the VS Code Contribution view) so "never
+ * touched Hunch" remains countable without a five-line notice per prompt. */
 export function stopHookReport(root, provider, event) {
     if (!reportPresentationEnabled(root))
         return null;
@@ -46,9 +57,11 @@ export function stopHookReport(root, provider, event) {
     if (!id)
         return null;
     if (id === "legacy")
-        return { systemMessage: "Hunch hook active. This Claude version does not provide an exact prompt identifier, so contribution for this response is unverified. Explicit task reports remain available with hunch report." };
+        return { systemMessage: "Hunch hook active. This host version does not provide an exact prompt identifier, so contribution for this response is unverified. Explicit task reports remain available with hunch report." };
     try {
         const report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+        if (isEmptyTaskReport(report))
+            return null;
         let card = renderTaskReport(report);
         try {
             const file = writeTaskReportHtml(root, id);

package/dist/integrations/claudeConfig.js

@@ -146,12 +146,29 @@ export function healClaudeConfigCaseSplit(opts = {}) {
         if (keys.length < 2)
             continue; // no casing split for this directory
         keys.sort(); // deterministic first-wins union
-        const blocks = keys.map((k) => (isPlainObject(projects[k]) ? projects[k] : {}));
+        // A root object can still contain malformed project blocks. Do not replace a
+        // user's scalar/array block, or normalize malformed nested MCP/list fields,
+        // merely because another drive-letter casing is valid.
+        for (const key of keys) {
+            const block = projects[key];
+            if (!isPlainObject(block)) {
+                throw new Error(`refusing to modify ${file}: project ${key} is not an object; fix it, then re-run.`);
+            }
+            const mcp = block.mcpServers;
+            if (mcp !== undefined && !isPlainObject(mcp)) {
+                throw new Error(`refusing to modify ${file}: project ${key}.mcpServers must be an object; fix it, then re-run.`);
+            }
+            for (const listKey of ["enabledMcpjsonServers", "disabledMcpjsonServers"]) {
+                const list = block[listKey];
+                if (list !== undefined && (!Array.isArray(list) || !list.every((value) => typeof value === "string"))) {
+                    throw new Error(`refusing to modify ${file}: project ${key}.${listKey} must be a string array; fix it, then re-run.`);
+                }
+            }
+        }
+        const blocks = keys.map((k) => projects[k]);
         const u = unionConfig(blocks);
         let groupChanged = false;
         for (const k of keys) {
-            if (!isPlainObject(projects[k]))
-                projects[k] = {};
             if (applyUnion(projects[k], u))
                 groupChanged = true;
         }

package/dist/integrations/claudemd.js

@@ -47,7 +47,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
-    lines.push("- For a new user task, call `hunch_task(action: \"start\", title: <short task title>)` once and retain its `task_id`. If a native prompt hook already supplied a task ID, reuse its exact start arguments instead of creating another task; each new native prompt has its own ID. Otherwise reuse the ID for follow-up work on the same task; never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
+    lines.push("- For a new user task, call `hunch_task(action: \"start\", title: <short task title>)` once and retain its `task_id`. Claude Code's prompt hook supplies a task ID natively — reuse its exact start arguments instead of creating another task (each new prompt has its own ID). Codex supplies one the same way once its `.codex/hooks.json` is trusted (`/hooks`). Hosts without prompt hooks (Windsurf, Cursor) never receive one: start the task yourself. Reuse the ID for follow-up work on the same task; never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
     lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target, task_id)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST** for memory. Include the current task ID on each context call so its contribution is inspectable.");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");

package/dist/integrations/health.d.ts

@@ -10,9 +10,9 @@ export declare const HARNESSES: {
     };
     readonly codex: {
         readonly mcp: ".codex/config.toml";
-        readonly hooks: "";
-        readonly key: "";
-        readonly events: readonly [];
+        readonly hooks: ".codex/hooks.json";
+        readonly key: "hooks";
+        readonly events: readonly ["SessionStart", "PreToolUse", "PostToolUse", "PreCompact"];
     };
     readonly cursor: {
         readonly mcp: ".cursor/mcp.json";
@@ -58,6 +58,11 @@ export interface IntegrationHealth {
     scope: "repository-config";
     issues: HealthIssue[];
     harnesses: HarnessHealth[];
+    /** Every exact Hunch pin found in repository launch config, once per file+version. */
+    pins: Array<{
+        file: string;
+        version: string;
+    }>;
 }
 export declare function readLauncher(root: string, harness: Harness): {
     command: string;
@@ -65,9 +70,18 @@ export declare function readLauncher(root: string, harness: Harness): {
     customEnvironment: boolean;
 };
 export declare function inspectIntegrations(root: string, selected?: Harness): IntegrationHealth;
+/** Harness launch files git ignores: this machine's config, never the tag's. A
+ * release cut may keep these at the last published version (see
+ * tooling/sync-version-pins.mjs) so hooks and MCP never point at a version npm
+ * cannot serve. Unknown git state yields [] — callers then treat nothing as local. */
+export declare function machineLocalIntegrationFiles(root: string): string[];
 /** Repair only exact published pins. Preserve formatting and all other values.
- * Preflight every affected file before writing any; reject malformed JSON/TOML. */
-export declare function repairIntegrationPins(root: string): string[];
+ * Preflight every affected file before writing any; reject malformed JSON/TOML.
+ * `skip` leaves a file untouched (used to keep machine-local pins on a version
+ * npm can actually serve while a release is still publishing). */
+export declare function repairIntegrationPins(root: string, opts?: {
+    skip?: (file: string) => boolean;
+}): string[];
 export declare function integrationHealthFails(report: IntegrationHealth, required?: readonly Capability[]): boolean;
 export declare function formatIntegrationHealth(report: IntegrationHealth): string;
 /** Bounded session warning; diagnostics must never break hook execution. */

package/dist/integrations/health.js

@@ -1,6 +1,7 @@
 /** Repository integration checks. Configuration is evidence of wiring, never
  * evidence that a host delivered context or enforced a decision. */
 import { existsSync, readFileSync, lstatSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { parseJsonc } from "../core/jsonc.js";
@@ -20,7 +21,7 @@ const OBSERVATION_FRESH_MS = 30 * 86_400_000;
 export const CAPABILITIES = ["mcp", "context", "edit-blocking", "failure-capture", "compaction"];
 export const HARNESSES = {
     claude: { mcp: ".mcp.json", hooks: ".claude/settings.json", key: "mcpServers", events: ["SessionStart", "PreToolUse", "PostToolUseFailure", "PreCompact"] },
-    codex: { mcp: ".codex/config.toml", hooks: "", key: "", events: [] },
+    codex: { mcp: ".codex/config.toml", hooks: ".codex/hooks.json", key: "hooks", events: ["SessionStart", "PreToolUse", "PostToolUse", "PreCompact"] },
     cursor: { mcp: ".cursor/mcp.json", hooks: ".cursor/hooks.json", key: "mcpServers", events: ["sessionStart", "preToolUse", "postToolUse", ""] },
     vscode: { mcp: ".vscode/mcp.json", hooks: ".github/hooks/hunch.json", key: "servers", events: ["SessionStart", "PreToolUse", "PostToolUse", ""] },
     windsurf: { mcp: ".windsurf/mcp_config.json", hooks: ".windsurf/hooks.json", key: "mcpServers", events: ["", "pre_write_code", "post_run_command", ""] },
@@ -51,7 +52,7 @@ function hookCommands(value) {
     if (obj.enabled === false || (obj.type !== undefined && obj.type !== "command"))
         return [];
     const command = typeof obj.command === "string" ? obj.command : "";
-    const own = /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command)
+    const own = /(?:@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts))/.test(command)
         && /\s"?hook"?(?:\s+"?--provider"?\s+"?[a-z]+"?)?\s*$/.test(command);
     return [...(own ? [command] : []), ...(obj.hooks ? hookCommands(obj.hooks) : [])];
 }
@@ -102,7 +103,7 @@ function expectedVersion(root) {
     return version;
 }
 export function inspectIntegrations(root, selected) {
-    const report = { schema: "hunch.integration-health/1", expectedVersion: HUNCH_VERSION, scope: "repository-config", issues: [], harnesses: [] };
+    const report = { schema: "hunch.integration-health/1", expectedVersion: HUNCH_VERSION, scope: "repository-config", issues: [], harnesses: [], pins: [] };
     try {
         report.expectedVersion = expectedVersion(root);
     }
@@ -115,7 +116,9 @@ export function inspectIntegrations(root, selected) {
             const pins = [...value.matchAll(pinPattern)];
             if (value.includes("@davesheffer/hunch") && !pins.length)
                 report.issues.push({ file, code: "unpinned-package", detail: "Hunch npm launcher has no exact version; run hunch init with the intended version" });
-            for (const [, version] of pins) {
+            for (const [, version = ""] of pins) {
+                if (!report.pins.some(p => p.file === file && p.version === version))
+                    report.pins.push({ file, version });
                 if (version !== report.expectedVersion)
                     report.issues.push({ file, code: "version-drift", detail: `Hunch ${version} differs from expected ${report.expectedVersion}; run hunch integrations repair-pins` });
             }
@@ -146,7 +149,11 @@ export function inspectIntegrations(root, selected) {
         }
         let events = {};
         let disabled = false;
-        if (spec.hooks) {
+        // A hooks file that was never written is a coverage gap (the adapter is
+        // not installed), not configuration drift: report it, never fail on it.
+        // `--require` still refuses, because nothing unverified counts.
+        const hooksAbsent = !!spec.hooks && !existsSync(join(root, spec.hooks));
+        if (spec.hooks && !hooksAbsent) {
             try {
                 const config = object(parseJsonc(readFileSync(join(root, spec.hooks), "utf8")));
                 disabled = config.disableAllHooks === true;
@@ -164,6 +171,9 @@ export function inspectIntegrations(root, selected) {
                 status.status = capability === "context" ? "advisory-only" : "unsupported";
                 status.detail = capability === "context" ? "Hunch relies on instructions and voluntary MCP calls on this adapter" : "No Hunch lifecycle adapter for this capability";
             }
+            else if (hooksAbsent) {
+                status.detail = `No ${spec.hooks}; run hunch init to install this host's lifecycle hooks`;
+            }
             else if (disabled || firmness === "off" || ((capability === "failure-capture") && process.env.HUNCH_PIPELINE === "0")) {
                 status.status = "unsupported";
                 status.detail = "Disabled by local hook settings, firmness, or HUNCH_PIPELINE";
@@ -201,15 +211,30 @@ export function inspectIntegrations(root, selected) {
         report.issues.push({ file: ".", code: "no-integrations", detail: "No repository integrations found; global and managed host settings are not inspected" });
     return report;
 }
+/** Harness launch files git ignores: this machine's config, never the tag's. A
+ * release cut may keep these at the last published version (see
+ * tooling/sync-version-pins.mjs) so hooks and MCP never point at a version npm
+ * cannot serve. Unknown git state yields [] — callers then treat nothing as local. */
+export function machineLocalIntegrationFiles(root) {
+    const files = Object.values(HARNESSES).flatMap(s => [s.mcp, s.hooks]).filter(f => f && existsSync(join(root, f)));
+    if (!files.length)
+        return [];
+    const r = spawnSync("git", ["check-ignore", "--", ...files], { cwd: root, encoding: "utf8", windowsHide: true });
+    if (r.error || (r.status !== 0 && r.status !== 1))
+        return [];
+    return (r.stdout ?? "").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+}
 /** Repair only exact published pins. Preserve formatting and all other values.
- * Preflight every affected file before writing any; reject malformed JSON/TOML. */
-export function repairIntegrationPins(root) {
+ * Preflight every affected file before writing any; reject malformed JSON/TOML.
+ * `skip` leaves a file untouched (used to keep machine-local pins on a version
+ * npm can actually serve while a release is still publishing). */
+export function repairIntegrationPins(root, opts = {}) {
     const version = expectedVersion(root);
     const pending = [];
     for (const [name, spec] of Object.entries(HARNESSES)) {
         for (const file of [spec.mcp, spec.hooks].filter(Boolean)) {
             const path = join(root, file);
-            if (!existsSync(path))
+            if (!existsSync(path) || opts.skip?.(file))
                 continue;
             // Never follow a config symlink or symlinked parent into another project.
             let current = resolve(root);
@@ -225,15 +250,15 @@ export function repairIntegrationPins(root) {
                 return `@davesheffer/hunch@${version}`;
             });
             let after;
-            if (name === "codex") {
+            if (name === "codex" && file === spec.mcp) {
                 readLauncher(root, "codex");
                 const block = codexBlock(before);
                 const table = object(object(parseToml(block).mcp_servers).hunch);
-                if (Object.keys(table).some(key => !["command", "args"].includes(key)))
+                if (Object.keys(table).some(key => !["command", "args", "startup_timeout_sec"].includes(key)))
                     throw new Error(`custom managed settings require manual pin repair: ${file}`);
                 // Replace only the canonical args line, never comments or another table.
                 const lines = block.split("\n");
-                if (lines.some(line => line.trim() && !line.trim().startsWith("#") && !/^\s*(?:\[mcp_servers\.hunch\]|command\s*=|args\s*=)/.test(line)))
+                if (lines.some(line => line.trim() && !line.trim().startsWith("#") && !/^\s*(?:\[mcp_servers\.hunch\]|command\s*=|args\s*=|startup_timeout_sec\s*=)/.test(line)))
                     throw new Error(`custom managed TOML requires manual pin repair: ${file}`);
                 const next = lines.map(line => /^\s*args\s*=/.test(line) ? replace(line.split("#")[0]) + (line.includes("#") ? `#${line.split("#").slice(1).join("#")}` : "") : line).join("\n");
                 after = before.replace(block, next);