@davesheffer/hunch 1.8.0 → 1.8.2

package/dist/synthesis/provider.js

@@ -2,10 +2,11 @@
  * Pluggable synthesis provider for the WRITE path (DESIGN.md §4 / §7).
  *
  * LLM synthesis is driven by the user's chosen coding-assistant subscription
- * CLI — never a pay-per-token API. Claude Code, Codex, and Cursor use different
- * auth surfaces, but every provider returns the same shape. When more than one
- * subscription CLI is available, Hunch deliberately does NOT guess whose plan
- * to spend: the user chooses once with `hunch provider <name>` (stored locally)
+ * CLI or an explicitly configured OpenAI-compatible endpoint. Claude Code,
+ * Codex, and Cursor use different auth surfaces, but every provider returns the
+ * same shape. When more than one non-deterministic provider is available, Hunch
+ * deliberately does NOT guess which one to use: the user chooses once with
+ * `hunch provider <name>` (stored locally)
  * or overrides per shell with HUNCH_SYNTH_PROVIDER. Ambiguous auto mode stays
  * deterministic and free.
  *
@@ -13,11 +14,19 @@
  * child env wherever the CLI would otherwise prefer them. There is intentionally
  * NO direct API-key provider.
  *
+ * A fourth, OPT-IN provider (name "openai-compat", alias "ollama") speaks the
+ * OpenAI chat-completions format over HTTP to a self-hosted endpoint instead of a
+ * subscription CLI. It stays off unless HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL
+ * are both explicitly set. Local/LAN endpoints work directly; every public remote
+ * requires HUNCH_SYNTH_ALLOW_METERED=1 because billing cannot be inferred safely
+ * from a hostname — con_2ce3f2a547's spirit is "never silently bill."
+ *
  * Every provider returns the same shape so the rest of the system never knows
  * (or cares) which one ran.
  */
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { isIP } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
@@ -100,13 +109,16 @@ export function pexecIn(cmd, args, opts = {}) {
     });
 }
 /** Every selectable synthesis mode. `auto` is a preference value rather than a
- * provider: it uses a subscription only when exactly one usable CLI is found. */
-export const SYNTH_PROVIDER_NAMES = ["claude-cli", "codex-cli", "cursor-agent", "deterministic"];
+ * provider: it uses a subscription only when exactly one usable CLI is found.
+ * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+export const SYNTH_PROVIDER_NAMES = ["claude-cli", "codex-cli", "cursor-agent", "openai-compat", "deterministic"];
 export const SYNTH_PREFERENCES = ["auto", ...SYNTH_PROVIDER_NAMES];
 const PROVIDER_INFO = {
     "claude-cli": { label: "Claude Code", subscription: "Claude subscription" },
     "codex-cli": { label: "Codex", subscription: "ChatGPT subscription" },
     "cursor-agent": { label: "Cursor Agent", subscription: "Cursor subscription" },
+    "openai-compat": { label: "Self-hosted / local model (Ollama, vLLM, LM Studio, ...)", subscription: null },
     deterministic: { label: "Deterministic local fallback", subscription: null },
 };
 const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
@@ -179,14 +191,7 @@ const VERIFY_TOOL = {
         required: ["grounded", "unsupported_alternatives", "unsupported_claims"],
     },
 };
-// --------------------------------------------------------------------------
-// Base for headless-CLI SUBSCRIPTION providers. Each one drives a coding-assistant
-// CLI billed to the user's own subscription (never a pay-per-token API key — see
-// dec_65b058de66). The prompt always goes over STDIN (never argv — keeps untrusted
-// diff content out of any shell pexecIn uses on Windows), and the CLI's text output
-// is handed to the SAME mappers, so the rest of the system is provider-agnostic.
-// --------------------------------------------------------------------------
-class CliSynthProvider {
+class PromptSynthProvider {
     /** Run a CLI with the prompt on stdin, stripping API-key env vars so the tool
      *  falls through to its SUBSCRIPTION credentials. Shared by codex/cursor. */
     async runCli(bin, args, stripEnv, prompt, timeoutMs = 120_000) {
@@ -203,7 +208,7 @@ class CliSynthProvider {
         return stdout;
     }
     async draftDecision(input) {
-        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
+        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`, "json");
         const draft = decisionDraftFromText(text, input.subject);
         // No usable LLM JSON (truncation, refusal, prose-only, or a CLI whose output
         // shape we misread) → THROW so the safe wrapper falls back to the deterministic
@@ -218,37 +223,37 @@ class CliSynthProvider {
         return draft;
     }
     async draftBug(input) {
-        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
+        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`, "json");
         const draft = bugDraftFromText(text, input.test, input.message);
         if (!draft)
             throw new Error(`${this.name}: no usable bug JSON in output`);
         return draft;
     }
-    /** Grounded prose for the wiki. Same subscription-only run() path (API keys
-     *  stripped). Throws on empty output so the caller falls back to its
-     *  deterministic template page. */
+    /** Grounded prose for the wiki. Uses text mode rather than the structured JSON
+     *  mode required by the record mappers. Throws on empty output so the caller
+     *  falls back to its deterministic template page. */
     async draftProse(prompt) {
-        const text = (await this.run(prompt)).trim();
+        const text = (await this.run(prompt, "text")).trim();
         if (!text)
             throw new Error(`${this.name}: empty prose output`);
         return text;
     }
-    /** The Critic pass: audit a draft against its commit. Same subscription-only
-     *  run() path (API keys stripped), so this never bills the pay-per-token API.
+    /** The Critic pass: audit a draft against its commit through the provider's
+     *  guarded transport.
      *  Throws on unusable output so verifyDecisionSafe degrades to the un-audited
      *  draft (a verifier failure must never lose the draft — dec_18a81c8291). */
     async verifyDecision(input, draft) {
-        const text = await this.run(`${VERIFY_SYSTEM}\n\n${verifyPrompt(input, draft)}\n\n${jsonInstruction(VERIFY_TOOL.input_schema)}`);
+        const text = await this.run(`${VERIFY_SYSTEM}\n\n${verifyPrompt(input, draft)}\n\n${jsonInstruction(VERIFY_TOOL.input_schema)}`, "json");
         const verdict = verdictFromText(text);
         if (!verdict)
             throw new Error(`${this.name}: no usable verdict JSON in output`);
         return verdict;
     }
     /** Judge whether an auto-drafted decision is worth keeping (for auto-review).
-     *  Same subscription-only run() path (API keys stripped). Throws on unusable
+     *  Uses the provider's guarded transport. Throws on unusable
      *  output so the caller can degrade to a keep-for-human verdict. */
     async judgeDraft(draft, existing) {
-        const text = await this.run(`${RELEVANCE_SYSTEM}\n\n${relevancePrompt(draft, existing)}\n\n${jsonInstruction(RELEVANCE_TOOL.input_schema)}`);
+        const text = await this.run(`${RELEVANCE_SYSTEM}\n\n${relevancePrompt(draft, existing)}\n\n${jsonInstruction(RELEVANCE_TOOL.input_schema)}`, "json");
         const verdict = relevanceFromText(text);
         if (!verdict)
             throw new Error(`${this.name}: no usable relevance JSON in output`);
@@ -267,10 +272,28 @@ const MODEL_RE = /^[A-Za-z0-9._:/-]+$/;
 export function safeModel(v, fallback) {
     return v && MODEL_RE.test(v) ? v : fallback;
 }
+// A timeout comes from a HUNCH_*_TIMEOUT_MS env var and feeds AbortController's
+// delay directly (never a shell argv token, unlike safeModel's model id) — but a
+// non-numeric or nonsensical value (negative, zero, NaN, Infinity) would either
+// abort immediately or never abort at all, so validate the same way: fall back to
+// the provider's default rather than propagate garbage.
+export function safeTimeout(v, fallback) {
+    const n = Number(v);
+    return v && Number.isFinite(n) && n > 0 ? n : fallback;
+}
+// max_tokens caps OUTPUT length (never a shell argv token, unlike safeModel's
+// model id) — same failure modes as a timeout, so validate the same way: fall
+// back to a safe default rather than propagate garbage into the request body
+// (issue #11; orthogonal to the context-window/truncation problem that issue
+// is mainly about — this only bounds how much the model is allowed to WRITE).
+export function safeMaxTokens(v, fallback) {
+    const n = Number(v);
+    return v && Number.isFinite(n) && n > 0 ? n : fallback;
+}
 // --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
 // --------------------------------------------------------------------------
-class ClaudeCliProvider extends CliSynthProvider {
+class ClaudeCliProvider extends PromptSynthProvider {
     name = "claude-cli";
     // Default to the `haiku` alias (cheap/fast, and survives model retirements)
     // rather than a pinned dated id; override with HUNCH_SYNTH_MODEL if needed.
@@ -330,7 +353,7 @@ class ClaudeCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 // Provider B1: OpenAI Codex CLI (`codex exec`) — billed to the ChatGPT subscription
 // --------------------------------------------------------------------------
-class CodexCliProvider extends CliSynthProvider {
+class CodexCliProvider extends PromptSynthProvider {
     name = "codex-cli";
     model = safeModel(process.env.HUNCH_CODEX_MODEL, undefined); // omit → codex uses its configured default
     async available() {
@@ -354,7 +377,7 @@ class CodexCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 // Provider B2: Cursor Agent CLI (`cursor-agent -p`) — billed to the Cursor subscription
 // --------------------------------------------------------------------------
-class CursorCliProvider extends CliSynthProvider {
+class CursorCliProvider extends PromptSynthProvider {
     name = "cursor-agent";
     model = safeModel(process.env.HUNCH_CURSOR_MODEL, undefined);
     async available() {
@@ -377,6 +400,174 @@ class CursorCliProvider extends CliSynthProvider {
     }
 }
 // --------------------------------------------------------------------------
+// Provider D: OpenAI-compatible / local model endpoint (Ollama, vLLM, LM
+// Studio, llama.cpp server, ...) — opt-in, NOT a subscription CLI. Speaks the
+// OpenAI chat-completions wire format over HTTP, so ONE implementation covers
+// any self-hosted server that implements it (Ollama's /v1 compatibility layer
+// included — no separate native /api/chat client). Off by default: available()
+// requires BOTH HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL, so an installation
+// with neither set behaves exactly as it did before this provider existed.
+//
+// Exported (unlike the CLI providers) so tests can construct fresh instances and
+// read process.env at CALL time — see run()/available() below, which read env
+// vars directly rather than caching them in constructor fields. That mirrors
+// selectProvider()'s own style (it re-reads HUNCH_SYNTH_PROVIDER on every call)
+// and avoids a stale-field trap: a module-level PROVIDERS singleton constructed
+// once at import time would otherwise never see env vars a test (or a long-lived
+// process) sets afterward.
+// --------------------------------------------------------------------------
+// con_2ce3f2a547's boundary is "never silently bill." A denylist cannot enforce
+// that boundary: new OpenAI-compatible paid providers appear continually, and a
+// fully-qualified trailing DNS dot can even evade a naive exact-host comparison.
+// Fail closed instead. Loopback, private/link-local IPs, and conventional LAN DNS
+// names work without ceremony; every public remote requires the deliberate,
+// named HUNCH_SYNTH_ALLOW_METERED=1 opt-in. Publicly hosted self-managed servers
+// use that same flag because billing cannot be inferred reliably from a hostname.
+function normalizedHostname(url) {
+    return url.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+}
+/** Parse the exact base-URL shape this provider can safely compose with
+ * `/chat/completions`. Credentials belong in HUNCH_SYNTH_API_KEY; query strings
+ * and fragments are rejected because appending a path to either is ambiguous. */
+function parseOpenAICompatBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        if (!url.hostname || url.username || url.password || url.search || url.hash)
+            return null;
+        return url;
+    }
+    catch {
+        return null;
+    }
+}
+function isPrivateIpv4(hostname) {
+    const [a = -1, b = -1] = hostname.split(".").map(Number);
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 100 && b >= 64 && b <= 127) // shared space, including common tailnets
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168);
+}
+function isPrivateIpv6(hostname) {
+    const host = hostname.toLowerCase();
+    if (host === "::" || host === "::1")
+        return true;
+    if (host.startsWith("::ffff:")) {
+        const mapped = host.slice("::ffff:".length);
+        return isIP(mapped) === 4 && isPrivateIpv4(mapped);
+    }
+    const first = host.split(":", 1)[0] ?? "";
+    return first.startsWith("fc")
+        || first.startsWith("fd")
+        || /^fe[89ab]/.test(first);
+}
+function isLocalOrPrivateHost(hostname) {
+    if (isIP(hostname) === 4)
+        return isPrivateIpv4(hostname);
+    if (isIP(hostname) === 6)
+        return isPrivateIpv6(hostname);
+    if (hostname === "localhost" || !hostname.includes("."))
+        return true;
+    return [".localhost", ".local", ".lan", ".internal", ".home.arpa"].some((suffix) => hostname.endsWith(suffix));
+}
+function requiresMeteredOptIn(url) {
+    return !isLocalOrPrivateHost(normalizedHostname(url));
+}
+export function meteredHostsAllowed(env = process.env) {
+    return env.HUNCH_SYNTH_ALLOW_METERED === "1";
+}
+export class OpenAICompatProvider extends PromptSynthProvider {
+    name = "openai-compat";
+    async available() {
+        const baseUrl = process.env.HUNCH_SYNTH_BASE_URL;
+        const endpoint = baseUrl ? parseOpenAICompatBaseUrl(baseUrl) : null;
+        if (!endpoint || !safeModel(process.env.HUNCH_SYNTH_MODEL, undefined))
+            return false;
+        return meteredHostsAllowed() || !requiresMeteredOptIn(endpoint);
+    }
+    async run(prompt, output = "json") {
+        const baseUrl = process.env.HUNCH_SYNTH_BASE_URL;
+        const model = safeModel(process.env.HUNCH_SYNTH_MODEL, undefined);
+        if (!baseUrl || !model)
+            throw new Error("openai-compat: HUNCH_SYNTH_BASE_URL/HUNCH_SYNTH_MODEL not set");
+        const endpoint = parseOpenAICompatBaseUrl(baseUrl);
+        if (!endpoint) {
+            throw new Error("openai-compat: HUNCH_SYNTH_BASE_URL must be an http(s) base URL without credentials, a query, or a fragment");
+        }
+        if (requiresMeteredOptIn(endpoint) && !meteredHostsAllowed()) {
+            throw new Error(`openai-compat: refusing to call public remote ${normalizedHostname(endpoint)} — it may be metered, and con_2ce3f2a547 blocks silent pay-per-token billing. Set HUNCH_SYNTH_ALLOW_METERED=1 if this is deliberate.`);
+        }
+        endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, "")}/chat/completions`;
+        const apiKey = process.env.HUNCH_SYNTH_API_KEY;
+        const timeoutMs = safeTimeout(process.env.HUNCH_SYNTH_TIMEOUT_MS, 300_000);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [{ role: "user", content: prompt }],
+                    ...(output === "json" ? { response_format: { type: "json_object" } } : {}),
+                    stream: false,
+                    max_tokens: safeMaxTokens(process.env.HUNCH_SYNTH_MAX_TOKENS, 2048),
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw new Error(`openai-compat endpoint returned ${res.status}: ${(await res.text()).slice(0, 300)}`);
+            }
+            const body = (await res.json());
+            const content = body.choices?.[0]?.message?.content;
+            if (!content)
+                throw new Error("openai-compat endpoint returned no message content");
+            return content;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Best-effort: does the configured openai-compat endpoint look like Ollama with
+ *  an UNSET num_ctx? Returns
+ *  an advisory warning string when so, or null when the endpoint isn't reachable,
+ *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
+ *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  report the model's effective context length: modern Ollama defaults may come
+ *  from server configuration or VRAM tiers, and model_info keys are not a stable
+ *  parse target. We therefore report only the observed fact — whether num_ctx is
+ *  pinned in the model — without guessing an effective token count. */
+export async function probeOllamaNumCtx(baseUrl, model) {
+    try {
+        const root = baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+        const res = await fetch(`${root}/api/show`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ name: model }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (typeof body.parameters !== "string")
+            return null;
+        if (/^num_ctx\s+\d+/m.test(body.parameters))
+            return null; // already configured — nothing to warn about
+        return "⚠ This Ollama model does not pin num_ctx; its effective context depends on server/VRAM defaults. For stable large-diff synthesis, see https://hunch-pi.vercel.app/cookbook and pin num_ctx via a custom Modelfile.";
+    }
+    catch {
+        return null; // not Ollama, unreachable, or an unexpected response shape — advisory only, never throw
+    }
+}
+// --------------------------------------------------------------------------
 // Provider C: deterministic fallback (no LLM, always available)
 // --------------------------------------------------------------------------
 export class DeterministicProvider {
@@ -467,12 +658,16 @@ const PROVIDERS = [
     new ClaudeCliProvider(),
     new CodexCliProvider(),
     new CursorCliProvider(),
+    new OpenAICompatProvider(),
     new DeterministicProvider(),
 ];
 // Availability rarely changes within a process (a CLI doesn't get installed mid-run),
 // and selection runs on every sync/recordFailure. Cache by object identity rather than
 // name so injected test registries never inherit a stale result from another provider.
-const availCache = new WeakMap();
+// A plain Map (not WeakMap): __resetAvailabilityCacheForTests below needs .clear(),
+// which WeakMap doesn't support — the module's singleton PROVIDERS array is the only
+// thing that ever populates this in production, so there's no unbounded-growth risk.
+const availCache = new Map();
 function isAvailable(p) {
     let v = availCache.get(p);
     if (!v) {
@@ -481,8 +676,27 @@ function isAvailable(p) {
     }
     return v;
 }
+/** Test-only: clears the availability memoization cache so a test that toggles
+ *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
+ *  cached by an earlier call in the same process. Never call from production code. */
+export function __resetAvailabilityCacheForTests() {
+    availCache.clear();
+}
+/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
+ *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
+ *  server can implement), but Ollama is the most common self-hosted target and
+ *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
+ *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
+ *  command (index.ts) normalizes it the same way before validating/persisting a
+ *  local preference — the two paths must agree, or a user who sets one and reads
+ *  the other back gets a confusing "unknown provider" message for a name that
+ *  actually works. */
+export function normalizeProviderName(v) {
+    return v === "ollama" ? "openai-compat" : v;
+}
 function isSynthPreference(value) {
-    return !!value && SYNTH_PREFERENCES.includes(value);
+    const normalized = normalizeProviderName(value);
+    return !!normalized && SYNTH_PREFERENCES.includes(normalized);
 }
 function fallbackProvider(providers) {
     return providers.find((p) => p.name === "deterministic") ?? new DeterministicProvider();
@@ -499,9 +713,8 @@ export function readSynthesisPreference(root) {
         if (!existsSync(file))
             return "auto";
         const parsed = JSON.parse(readFileSync(file, "utf8"));
-        return typeof parsed.synthProvider === "string" && isSynthPreference(parsed.synthProvider)
-            ? parsed.synthProvider
-            : "auto";
+        const normalized = typeof parsed.synthProvider === "string" ? normalizeProviderName(parsed.synthProvider) : undefined;
+        return isSynthPreference(normalized) ? normalized : "auto";
     }
     catch {
         return "auto";
@@ -510,7 +723,8 @@ export function readSynthesisPreference(root) {
 /** Persist the user's provider choice only in `.hunch/local.json`, which is never a
  * repository policy. That means each developer controls their own subscription spend. */
 export function writeSynthesisPreference(root, preference) {
-    if (!isSynthPreference(preference))
+    const normalized = normalizeProviderName(preference);
+    if (!isSynthPreference(normalized))
         throw new Error(`unknown synthesis provider preference: ${preference}`);
     const file = localPreferencePath(root);
     let local = {};
@@ -529,7 +743,7 @@ export function writeSynthesisPreference(root, preference) {
         }
     }
     mkdirSync(dirname(file), { recursive: true });
-    writeFileAtomic(file, `${JSON.stringify({ ...local, synthProvider: preference }, null, 2)}\n`);
+    writeFileAtomic(file, `${JSON.stringify({ ...local, synthProvider: normalized }, null, 2)}\n`);
 }
 async function statusesFor(providers) {
     const statuses = [];
@@ -555,7 +769,7 @@ export async function resolveSynthesisProvider(opts = {}) {
         const provider = find(name);
         return provider && await isAvailable(provider) ? provider : undefined;
     };
-    const environment = env.HUNCH_SYNTH_PROVIDER?.trim();
+    const environment = normalizeProviderName(env.HUNCH_SYNTH_PROVIDER?.trim());
     if (environment && isSynthPreference(environment) && environment !== "auto") {
         const selected = await usable(environment);
         if (selected)
@@ -591,18 +805,22 @@ export async function resolveSynthesisProvider(opts = {}) {
 export async function selectProvider(opts = {}) {
     return (await resolveSynthesisProvider(opts)).provider;
 }
-// ---- Deep Synthesis: ensemble of subscription CLIs ------------------------
-// Opt-in (backfill/sync --deep): fan a commit out to EVERY available subscription
-// CLI, drop failures, and reconcile the drafts. Subscription-only (the workers are
-// the same CLI providers, so ANTHROPIC_API_KEY stripping is inherited). NEVER used on
-// the guard path; confidence is capped below the strict gate so output stays advisory.
-/** All available subscription-CLI workers (claude/codex/cursor), excluding the
- *  deterministic fallback — the pool Deep Synthesis fans a commit out to. */
+// ---- Deep Synthesis: ensemble of subscription CLIs (+ opt-in openai-compat) ----
+// Opt-in (backfill/sync --deep): fan a commit out to EVERY available worker —
+// the subscription CLIs (ANTHROPIC_API_KEY stripping inherited from them) plus the
+// opt-in openai-compat HTTP provider when configured, which is outside that
+// stripping scope entirely (con_2ce3f2a547 governs the Anthropic API specifically,
+// not a user-configured self-hosted endpoint) — drop failures, reconcile the
+// drafts. NEVER used on the guard path; confidence is capped below the strict gate
+// so output stays advisory.
+/** All available subscription-CLI workers (claude/codex/cursor, plus the opt-in
+ *  openai-compat), excluding the deterministic fallback — the pool Deep Synthesis
+ *  fans a commit out to. */
 export async function selectWorkers(opts = {}) {
     const out = [];
     for (const p of opts.providers ?? PROVIDERS) {
         if (p.name === "deterministic")
-            continue; // workers are real subscription CLIs only
+            continue; // workers are real LLM providers only
         if (await isAvailable(p))
             out.push(p);
     }
@@ -650,8 +868,8 @@ export function mergeDecisionDrafts(drafts) {
         agreement: Math.round(agreement * 100) / 100,
     };
 }
-// Default self-consistency depth when only ONE subscription CLI is installed (the
-// common case): sample it this many times and reconcile, so single-CLI users get
+// Default self-consistency depth when only ONE LLM provider is available (the
+// common case): sample it this many times and reconcile, so single-provider users get
 // ensemble-like robustness. Tunable per-call via `--samples`.
 const DEFAULT_SAMPLES = 2;
 export class EnsembleProvider {
@@ -678,7 +896,7 @@ export class EnsembleProvider {
     }
     async draftDecision(input) {
         if (!this.workers.length)
-            throw new Error("ensemble: no subscription CLI workers available");
+            throw new Error("ensemble: no LLM provider workers available");
         const settled = await Promise.allSettled(this.decisionTasks(input).map((t) => t()));
         const drafts = settled.flatMap((s) => (s.status === "fulfilled" ? [s.value] : []));
         if (!drafts.length)
@@ -696,9 +914,9 @@ export class EnsembleProvider {
         throw new Error("ensemble: all workers failed for bug");
     }
 }
-/** Build the Deep-Synthesis provider, or null if no subscription CLI is available
+/** Build the Deep-Synthesis provider, or null if no LLM provider is available
  *  (the caller then falls back to the normal single-provider path). `samples` sets
- *  the self-consistency depth for the single-CLI case. */
+ *  the self-consistency depth for the single-provider case. */
 export async function selectEnsemble(opts = {}) {
     const workers = await selectWorkers(opts);
     // The self-consistency policy default (DEFAULT_SAMPLES) is applied HERE, not in the
@@ -706,8 +924,10 @@ export async function selectEnsemble(opts = {}) {
     // construction stays passthrough. `--samples 1` opts back out.
     return workers.length ? new EnsembleProvider(workers, { samples: opts.samples ?? DEFAULT_SAMPLES }) : null;
 }
-/** Pick a CLI provider to run the Critic pass (subscription-only, like the workers).
- *  Returns null when no assistant CLI is installed — verification then no-ops and the
+/** Pick a provider to run the Critic pass — the same resolved provider normal
+ *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
+ *  honoring the same env/local-preference/auto policy. Returns null when that
+ *  resolves to the deterministic fallback — verification then no-ops and the
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
 export async function selectVerifier(opts = {}) {
     const { provider } = await resolveSynthesisProvider(opts);

package/dist/synthesis/synthesize.js

@@ -5,12 +5,23 @@ import { decisionId, bugId, constraintId } from "../core/ids.js";
 import { commitCoveredBy } from "../core/dupdetect.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
-const CODE_RE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
-const SKIP_SUBJECT = /^(merge|revert|bump|chore\(deps\)|format|lint|wip)\b/i;
+import { languageFor } from "../extractors/languages.js";
+// "chore(deps):" is anchored separately (not via \b) because \b requires a
+// word/non-word transition, and the character after the closing ")" is ":" or a
+// space — both non-word — so no boundary ever fires there.
+const SKIP_SUBJECT = /^(merge|revert|bump|format|lint|wip)\b|^chore\(deps\):/i;
 // Below this many changed code lines, a commit with no structural change and no
 // explanatory body isn't worth a paid LLM call. Tunable via HUNCH_SIG_MIN_LINES.
 const SIG_MIN_LINES = Number(process.env.HUNCH_SIG_MIN_LINES) || 12;
 const SIG_MIN_BODY = 40;
+/** Trivial-subject commits (merge/revert/bump/format/...) are noise UNLESS the body
+ *  carries real content — a squash/PR description often lands there, not on the
+ *  subject. Gated on body length ALONE (not the full isSignificant() heuristic): a
+ *  large auto-generated reformat or dependency-bump diff with no narrative must stay
+ *  skipped even though it would trip isSignificant()'s line/file/structural checks. */
+export function isTrivialSubject(meta) {
+    return SKIP_SUBJECT.test(meta.subject) && meta.body.trim().length < SIG_MIN_BODY;
+}
 /** Is a commit substantive enough to spend a paid LLM synthesis call on? Pure and
  *  deterministic. Any structural change (symbol/dependency delta), non-trivial
  *  churn, several files, OR an explanatory commit body signals a real decision
@@ -37,9 +48,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const meta = commitMeta(target, root);
     if (!meta)
         return { status: "skipped", reason: "commit not found" };
-    if (SKIP_SUBJECT.test(meta.subject))
+    if (isTrivialSubject(meta))
         return { status: "skipped", reason: `trivial subject: ${meta.subject}` };
-    const codeFiles = meta.files.filter((f) => CODE_RE.test(f));
+    const codeFiles = meta.files.filter((f) => languageFor(f) !== null);
     if (codeFiles.length === 0)
         return { status: "skipped", reason: "no code files changed" };
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title
@@ -84,13 +95,14 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // Significance gate: reserve the paid LLM for substantive commits; trivial ones
     // get the FREE deterministic draft (honestly labeled "inferred"/low-confidence,
     // so the Hunch stays accurate-by-provenance). --force always uses the provider.
-    // Deep Synthesis (--deep): ensemble every available subscription CLI and reconcile
+    // Deep Synthesis (--deep): ensemble every available guarded LLM provider and reconcile
     // their drafts (agreement-weighted, confidence capped below the strict gate). Falls
     // back to the normal single-provider path when no CLI is available. Opt-in only.
     // --verify forces the LLM provider (auditing a deterministic draft is pointless) and,
-    // like --deep, runs the Critic pass below. Subscription-only throughout (con_2ce3f2a547).
+    // like --deep, runs the Critic pass below. Public remotes stay behind the explicit
+    // metered opt-in throughout (con_2ce3f2a547).
     // An explicit private capture is storage-private AND local-only by default:
-    // never send a sensitive diff to a subscription CLI just to create a draft.
+    // never send a sensitive diff to any LLM provider just to create a draft.
     // Shared mode remains an explicit team policy and keeps its existing provider
     // behavior unless the caller asked for a private capture.
     const localOnly = opts.localOnly ?? !!opts.private;

package/dist/wiki/wiki.js

@@ -20,8 +20,8 @@
  *               (`store.recs`, overlay included). Nothing lands in the public
  *               repo; the manifest lives inside the overlay's .hunch/.
  *
- * The prose "Overview" section is optional LLM output (subscription CLI via
- * SynthProvider.draftProse — never a pay-per-token API); everything drift-bearing
+ * The prose "Overview" section is optional LLM output (a guarded configured
+ * SynthProvider.draftProse); everything drift-bearing
  * (anchors, invariants, structure) is rendered deterministically around it, so a
  * missing/failed CLI degrades to a complete template page, and the input hash
  * covers graph inputs only — LLM nondeterminism can never fake staleness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex).",
@@ -58,6 +58,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
+    "tree-sitter-python": "^0.23.2",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"
   },