@davesheffer/hunch 1.32.3 → 1.32.4

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", ""] },
@@ -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);

package/dist/integrations/providers.d.ts

@@ -49,6 +49,13 @@ export declare function writeWindsurfRule(root: string, store: HunchStore): stri
  * registration remain the durable grounding path if a Cursor build suppresses
  * a hook's agent_message. */
 export declare function writeCursorHooks(root: string, inv: Invocation): string;
+/** Codex CLI hooks (0.153+): `.codex/hooks.json`, the same event names, stdin
+ * payload, and stdout contract as Claude Code, with `turn_id` as the per-prompt
+ * identity and `apply_patch` as the edit tool. Project-layer hooks load only for
+ * a trusted project and must be trusted once in Codex (`/hooks`), which the
+ * scaffold output says. Codex's PreToolUse rejects `continue:false`, so the
+ * strict gate answers with `permissionDecision` — the shape Hunch already emits. */
+export declare function writeCodexHooks(root: string, inv: Invocation): string;
 /** VS Code's native workspace hook location. It supports all lifecycle events
  * Hunch needs and uses the same stdout contract as Claude Code, with different
  * camelCase tool fields normalized in core/agenthook.ts. */

package/dist/integrations/providers.js

@@ -89,6 +89,10 @@ function hookCommand(inv, provider) {
 }
 function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
+    // Codex (like Claude Code) nests commands under a matcher entry: an entry
+    // whose every nested hook is ours is ours; a mixed entry stays foreign.
+    if (e && Array.isArray(e.hooks) && e.hooks.length && typeof e.command !== "string")
+        return e.hooks.every(isHunchProviderHook);
     const command = typeof e?.command === "string" ? e.command : "";
     // Anchored to the shapes hookCommand() writes — a Hunch launcher (the pinned
     // npm package spec, or a …/index.js|ts path for source installs) plus a tail
@@ -189,6 +193,8 @@ export function writeCodexConfig(root, inv) {
         "[mcp_servers.hunch]",
         `command = ${tomlStr(inv.command)}`,
         `args = [${argsToml}]`,
+        "# A cold npx install can exceed Codex's 10 s default; a slow start must not drop Hunch from the tool catalog.",
+        "startup_timeout_sec = 60",
         TOML_END,
     ].join("\n");
     // Strip any prior managed block first, so `base` is the user's own TOML.
@@ -286,6 +292,26 @@ export function writeCursorHooks(root, inv) {
     }
     return written;
 }
+/** Codex CLI hooks (0.153+): `.codex/hooks.json`, the same event names, stdin
+ * payload, and stdout contract as Claude Code, with `turn_id` as the per-prompt
+ * identity and `apply_patch` as the edit tool. Project-layer hooks load only for
+ * a trusted project and must be trusted once in Codex (`/hooks`), which the
+ * scaffold output says. Codex's PreToolUse rejects `continue:false`, so the
+ * strict gate answers with `permissionDecision` — the shape Hunch already emits. */
+export function writeCodexHooks(root, inv) {
+    const file = join(root, ".codex", "hooks.json");
+    const command = hookCommand(inv, "codex");
+    const entry = (matcher) => ({ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command }] });
+    return writeHookConfig(file, {
+        SessionStart: [entry()],
+        UserPromptSubmit: [entry()],
+        PreToolUse: [entry("apply_patch")],
+        PostToolUse: [entry("apply_patch|shell|local_shell")],
+        Stop: [entry()],
+        PreCompact: [entry()],
+        SubagentStart: [entry()],
+    });
+}
 /** VS Code's native workspace hook location. It supports all lifecycle events
  * Hunch needs and uses the same stdout contract as Claude Code, with different
  * camelCase tool fields normalized in core/agenthook.ts. */
@@ -470,7 +496,7 @@ export function scaffoldProviders(root, inv, store, options = {}) {
     const tasks = [
         ["Cursor", () => runProvider([() => writeCursorMcp(root, inv), () => writeCursorRule(root, store), ...(hooks ? [() => writeCursorHooks(root, inv)] : [])])],
         ["VS Code (Copilot)", () => runProvider([() => writeVscodeMcp(root, inv), () => writeCopilotInstructions(root, store), ...(hooks ? [() => writeVscodeHooks(root, inv)] : [])])],
-        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv)])],
+        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv), ...(hooks ? [() => writeCodexHooks(root, inv)] : [])])],
         ["Windsurf", () => {
                 return runProvider([
                     () => writeWindsurfMcp(root, inv),

package/dist/integrations/registry.d.ts

@@ -0,0 +1,15 @@
+export type PublishedStatus = "published" | "unpublished" | "unknown";
+export interface NpmResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type NpmRunner = (args: string[]) => NpmResult;
+export declare function defaultNpmRunner(timeoutMs: number): NpmRunner;
+/** Whether npm can serve `@davesheffer/hunch@<version>`. "unknown" covers offline,
+ * timeouts, and unexpected output; callers must never read it as unpublished. */
+export declare function publishedStatus(version: string, opts?: {
+    timeoutMs?: number;
+    run?: NpmRunner;
+}): PublishedStatus;

package/dist/integrations/registry.js

@@ -0,0 +1,41 @@
+/** Bounded npm registry lookups that never throw. A pin npm cannot serve makes
+ * every `npx --package=…` launcher (hooks and MCP) fail before Hunch runs, and
+ * the hosts report nothing — so the CLI must be able to name that state. */
+import { spawnSync } from "node:child_process";
+const exactVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function defaultNpmRunner(timeoutMs) {
+    return (args) => {
+        const windows = process.platform === "win32";
+        const r = spawnSync(windows ? `npm ${args.join(" ")}` : "npm", windows ? [] : args, {
+            shell: windows, windowsHide: true, encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error };
+    };
+}
+/** Whether npm can serve `@davesheffer/hunch@<version>`. "unknown" covers offline,
+ * timeouts, and unexpected output; callers must never read it as unpublished. */
+export function publishedStatus(version, opts = {}) {
+    if (!exactVersion.test(version))
+        return "unknown";
+    const run = opts.run ?? defaultNpmRunner(opts.timeoutMs ?? 8000);
+    let r;
+    try {
+        r = run(["view", `@davesheffer/hunch@${version}`, "version", "--json"]);
+    }
+    catch {
+        return "unknown";
+    }
+    if (r.error)
+        return "unknown";
+    if (r.status === 0) {
+        try {
+            const v = JSON.parse(r.stdout.trim() || "null");
+            return v === version || (Array.isArray(v) && v.includes(version)) ? "published" : "unknown";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    return /\b(?:ETARGET|E404|notarget)\b/.test(r.stderr) ? "unpublished" : "unknown";
+}
+//# sourceMappingURL=registry.js.map

package/dist/mcp/server.d.ts

@@ -25,6 +25,10 @@ export interface RootControlOptions {
     /** Serve exactly `initialRoot`; never re-home to client roots or `cwd` hints. */
     pinned?: boolean;
 }
+/** Delivered to every MCP client at initialize — the one grounding channel that
+ * needs no host hook or instruction file. Host-neutral by design (con_e04226bd05);
+ * per-host prose (CLAUDE.md, AGENTS.md) and hooks add to it, never replace it. */
+export declare const MCP_INSTRUCTIONS: string;
 export declare function buildServerWithRootControl(initialRoot: string, options?: RootControlOptions): RootControlledServer;
 /** Back-compatible server construction for tests and callers that do not need
  *  to drive roots directly. The server still owns and closes its active store. */