@davesheffer/hunch 1.8.1 → 1.8.2

package/README.md

@@ -1,388 +1,108 @@
 # Hunch
 
-## Your AI can write code. Hunch makes it remember the consequences.
+## Your repo remembers why.
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-**Hunch is engineering memory and a deterministic Change Gate for AI-assisted codebases.**
-It captures the decisions, rejected approaches, and bug history behind your code—then gives every
-assistant the same evidence before it changes anything.
+Hunch is engineering memory for AI-assisted codebases. It records the decisions, constraints,
+rejected approaches, and bug history behind your code, then gives every connected assistant the
+relevant context before it makes a change.
 
-Not another chat history. Not a wiki your team must remember to update. A git-native reasoning
-graph that turns “we already learned this the hard way” into something your tools can actually use.
+Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
+strict enforcement.
+
+## Start in five minutes
+
+Requires Node 22.13+ and a git repository.
 
 ```bash
 npm i -g @davesheffer/hunch
 cd your-repo
 hunch init
+hunch backfill --since 90d   # optional: seed memory from recent history
 ```
 
-Then ask any connected assistant: **“Why is this built this way?”**
-
-## The problem Hunch solves
-
-AI can read your current code. It does not know the decision you made six months ago, the incident
-that made it necessary, or the approach you deliberately rejected yesterday.
-
-That gap is where architectural drift starts:
+Reload your coding assistant, then ask:
 
-| Without Hunch | With Hunch |
-| --- | --- |
-| A refactor passes tests but bypasses a hard-won service boundary. | The change is checked against the decision, its constraint, and the incident behind it. |
-| A new coding session starts from scratch. | Claude Code, Cursor, Copilot, Windsurf, Antigravity, and Codex retrieve the same project memory over MCP. |
-| A correction disappears into a chat transcript. | “Never do that again” becomes a scoped, auditable guard. |
-| Code review sees a diff, not the reason behind it. | Change Gate produces a PASS / WARN / BLOCK receipt with causal evidence. |
+> Why is this built this way?
 
-## What you get in five minutes
+`hunch init` indexes the repo, installs the local memory hooks, and connects supported assistants
+to the same graph. It merges into existing configuration instead of replacing it.
 
-```bash
-hunch init                         # index code + wire supported assistants
-hunch backfill --since 90d         # optional: seed memory from recent history
-hunch check --working --strict     # review the whole working tree before a commit
-```
+## What Hunch gives you
 
-Hunch creates a local graph of:
-
-- **Decisions** — what was chosen, why, and what alternatives were rejected.
-- **Constraints** — the invariants a change must not violate.
-- **Bug lineage** — the root cause behind fixes, recurrences, and regression guards.
-- **Architecture** — symbols, components, dependencies, blast radius, and fragility.
-  Deep code-structure parsing covers **TypeScript, JavaScript, and Python** (via a language
-  registry — each new language is one entry); the "why" layer works for any language.
-
-It then puts that context where work happens: MCP tools, the CLI, a VS Code Change Gate, git hooks,
-and an optional pull-request guard.
-
-## Memory that runs itself (v1.8)
-
-There is no review queue to manage. Hunch's memory loop is fully automated, and the rare decision
-that genuinely needs a human is asked **inline, at the moment** — never parked in a backlog:
-
-- **Auto-trust** — every captured decision enters the graph as live advisory memory the moment it
-  lands. It grounds and ranks immediately; it can never hard-block anything until a human
-  explicitly vouches for it. Migrate an old draft backlog once with `hunch adopt-drafts`.
-- **A source-control panel for memory** — the VS Code **Hunch Memory** view shows every move
-  Hunch makes (capture / adopt / supersede / prune / repair) as a timeline: click for the diff,
-  right-click to revert locally. `hunch log` is the same spine in the terminal.
-- **Inline escalations** — `hunch escalations` (and the `hunch_escalations` MCP tool) lists only
-  what the graph cannot resolve itself: a topic conflict, a candidate rule awaiting review, a
-  proposed rule ready to activate. Each entry is a question with its resolution verb. Normally
-  empty.
-- **Self-repair** — rename a file and the next sync automatically heals every decision binding,
-  tripwire scope, constraint scope, and policy selector that matched it exactly (git's own rename
-  detection, zero guessing). Repairs land as revertable timeline moves; a repaired *policy* asks
-  once, inline, for a fresh proof.
-- **Local-first by design** — memory auto-commits locally and rides your next push;
-  `hunch push` (or the panel's Approve-to-push) is the one deliberate outward step.
+- **Durable context** — decisions and corrections survive the chat session that produced them.
+- **One memory for every assistant** — Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex,
+  and any MCP client see the same evidence.
+- **Change receipts** — review a working tree, commit, or branch against recorded intent and get a
+  cited PASS / WARN / BLOCK result.
+- **Bug lineage** — understand which old incident a line fixed before accidentally undoing it.
+- **Code awareness** — TypeScript, JavaScript, and Python structure feed dependency, blast-radius,
+  and redundancy checks. The reasoning layer works with any language.
 
-```bash
-hunch log              # the memory timeline (what Hunch did, when, revertable)
-hunch escalations      # the decisions only you can make — normally empty
-hunch repair --apply   # heal bindings after a rename (sync does this automatically)
-```
+The source of truth is readable JSON in `.hunch/`. A local SQLite index makes retrieval fast but
+is always rebuildable.
 
-## One graph. Every assistant. No lock-in.
+## Day-to-day
 
-Hunch is agent-agnostic by design. It scaffolds MCP and grounding for Claude Code, Cursor, VS Code / Copilot,
-Windsurf, Google Antigravity, Codex, and any agent that can read `AGENTS.md`; where a client exposes hooks,
-it adds a native lifecycle adapter too.
+Most memory work happens automatically after commits. These commands cover the common manual paths:
 
-Your memory is plain JSON that you own. Hunch adds a SQLite index only as a rebuildable derived
-layer—your decisions never disappear into a proprietary hosted memory system.
-
-Synthesis is just as portable: Hunch can use Claude Code, Codex, or Cursor through the subscription
-CLI you choose. It never guesses which of several installed subscriptions to bill—set your local,
-gitignored preference with `hunch provider codex-cli` (or `claude-cli` / `cursor-agent`); otherwise
-Hunch uses a subscription only when exactly one is available, and falls back to deterministic local
-drafting when the choice is ambiguous.
-
-```text
-Claude Code  ─┐
-Cursor       ├── MCP ──> .hunch/ reasoning graph ──> deterministic checks
-Copilot      ┤
-Codex        ┤
-Windsurf     ┤
-Antigravity  ┘
-```
-
-## The Change Gate: review intent, not just code
-
-Before you commit, ask Hunch to review staged files, your working tree, or a branch against its
-base. It returns a receipt your human reviewer or any coding agent can understand:
-
-```text
-BLOCK  src/payments/charge.ts
-
-  [blocking] Controllers must not reach the database directly
-  why: dec_service_boundary → bug_n_plus_one_2025
-  evidence: charge() now imports dbQuery
-```
+| Command | Use it for |
+| --- | --- |
+| `hunch why <file>` | Decisions, bugs, constraints, and blast radius behind a file |
+| `hunch query "<question>"` | Search project memory |
+| `hunch check --working` | Review all current changes against recorded intent |
+| `hunch log` | See the memory timeline and its reversible moves |
+| `hunch escalations` | See the rare decisions only a human can make |
+| `hunch doctor` | Diagnose setup, provider, index, or private-overlay problems |
 
-The gate is deterministic: no prompt-quality lottery and no model call in the enforcement path.
-Start advisory. Turn on strictness only when the rules have earned it.
+Corrections can become scoped rules, but captured memory cannot hard-block on its own. Enforcement is
+deterministic and opt-in:
 
 ```bash
 hunch firmness strict
 hunch check --staged --strict
-hunch conform --strict
 ```
 
-### Hunch Constitution — experimental Gate G1 + evidence bootstrap
+## Synthesis without surprise billing
 
-Hunch can now lift one structured architectural decision into versioned Policy IR, prove its
-deterministic behavior with a clean baseline plus a mutation, and require an explicit human event
-before it becomes enforceable:
+Hunch can draft structured memory through:
 
-```bash
-hunch constitution bootstrap --public-only --since 90d --max-candidates 3
-hunch constitution ingest --public-only --since 90d
-hunch constitution ingest --public-only --instructions --from pr-export.json
-hunch constitution delta dec_fix_or_revert --public-only
-hunch constitution bootstrap --history --public-only --since 90d --max-candidates 3
-hunch policy compile dec_service_boundary --through OrderService
-hunch policy corpus pol_… --import corpus.json
-hunch policy plan pol_… --history 20 --mutations 3
-hunch policy prove pol_…
-hunch policy history pol_…
-hunch policy history pol_… --commit <full-sha> --classify true_positive_actionable --actor github:your-name --reason "Confirmed historical violation"
-hunch policy shadow pol_… --record
-hunch policy shadow pol_…
-hunch policy card pol_…
-hunch policy relations pol_…
-hunch policy accept pol_… --blocking --actor github:your-name
-hunch policy evaluate pol_… --json
-hunch policy evaluate pol_… --working --json
-hunch policy evaluate pol_… --staged --json
-```
-
-Private G2 dogfood stays evidence-only until a separate human signoff. An exact private plan selects
-at least ten P3+ policies and seven category-specific runbooks; drills write no evidence by
-themselves, rehearsals bind the resulting hashes, and historical shadow backfill commits only after
-the complete policy/commit matrix has produced no unknown or error result:
-
-```bash
-hunch constitution g2 --plan private-g2-plan.json
-hunch constitution g2 --drill all
-hunch constitution g2 --rehearse rb_g2_evaluator_error_01 --result passed \
-  --actor human:owner --evidence sha1:… --notes "Exact recovery drill passed."
-hunch constitution g2 --backfill 20
-hunch constitution g2 --queue 20
-hunch constitution g2 --strict
-```
-
-Backfill uses distinct real first-parent commits, excludes commits predating an executable policy's
-fixing commit, and deduplicates by exact policy/proof/repository/graph identity. A failed preflight
-writes nothing. Neither a ready packet nor a passed drill activates, warns, blocks, or claims G2;
-the strongest machine result is `eligible_for_human_g2_signoff`.
-
-The model-free bootstrap considers only current, accepted, human-confirmed decisions carrying
-exactly one structured `conformance` predicate. It normalizes auditable evidence and keeps a bounded
-queue of at most three unreviewed candidates. Re-running is idempotent, private evidence inherits
-private storage, and every candidate starts with `authority: null`—bootstrap can never activate or
-block on its own.
-
-The opt-in history path reads the exact blobs for a human-confirmed fix/revert commit and its first
-parent—without checking out code or running hooks. It also admits an architectural replacement
-when a human-confirmed decision carries an explicit `retired.deps` entry that exactly matches a
-removed external package. It enumerates only assertions the current graph can bind exactly and
-whose symbol/call/package identifiers the human judgment explicitly names. One
-supported meaning may become a compiled candidate; zero, multiple, missing,
-or ambiguous meanings are stored as `uncompilable`, never silently approximated. `constitution
-delta` previews that evidence and candidate set without writing policy state.
-
-The external-import slice is deliberately narrow: removing a human-named static ESM package
-specifier can compile into a file-scoped `not-reaches(..., external:<package>)` boundary. Package
-subpaths canonicalize to their package root, the anchor must exist before and after the change, and
-an explicitly retired dependency filters unrelated call/symbol facts from the same replacement
-commit. Exact relative JS/TS imports across two derived components can also compile to direct
-`reaches`/`not-reaches` policies over `depends_on` edges when both component meanings are explicitly
-human-grounded. Same-component imports, ambiguous/missing targets, import-map aliases, `require()`,
-dynamic `import()`, runtime loading, and positive external-package requirements remain visibly
-unsupported.
-
-Local correction, incident, and test-failure records can be normalized with `constitution ingest`.
-The adapter stores references and hashes, inherits private storage, and creates no policy authority.
-Add `--instructions` to hash committed AGENTS/CLAUDE/Copilot/Cursor/Windsurf instructions and ADRs
-from immutable Git blobs. Add `--from` for one or more strict local review, conversation, or PR
-export JSON files. Raw prose is never copied into EvidenceEvents; only bounded metadata, references,
-and content hashes persist. Mixed batches validate before the first write, public-only mode refuses
-private/secret items, and unsupported meaning stays explicitly `uncompilable` instead of being
-approximated into a policy.
-
-```json
-{
-  "version": 1,
-  "source": "pr_export",
-  "items": [{
-    "id": "pr-431-review-7",
-    "kind": "review",
-    "occurred_at": "2026-07-10T10:10:00Z",
-    "actor": "maintainer:alice",
-    "commit": "abc1234",
-    "files": ["src/orders.ts"],
-    "text": "Use OrderService; do not call persistence here.",
-    "data_class": "private",
-    "maintainer_confirmed": true
-  }]
-}
-```
-
-`policy plan` then writes a content-addressed ProofPlan before execution: exact source/current commits,
-known-good/known-bad corpus, deterministic mutation operators, expectations, and resource budgets.
-`policy corpus --import` accepts bounded labeled `known_bad`/`known_good` Git refs, resolves them
-once to full immutable commit SHAs, stores the manifest in the policy's public/private home, and
-hash-binds it into every resulting plan. A commit cannot be labeled both good and bad, and stale
-policy-bound corpora must be re-imported after semantic policy changes. A `known_good` fixture may
-also carry an explicit human attestation—`{ "actor": "github:your-name", "reason": "…" }`—to
-document why that accepted variant belongs in the corpus. Attested fixtures are replayed once as
-named corpus evidence and excluded from accepted-history sampling; the attestation cannot waive a
-policy result or create authority.
-`policy relations` is a read-only view of those explicit exception-parent links. It shows the
-selected policy, its parent if any, linked narrower exceptions, and a visible missing-parent marker
-for a manually damaged record. When the broad parent is planned, proved, or evaluated, every linked
-exception descendant is instead hash-bound into one canonical composition. The deepest applicable
-explicit scope selects the result; equal-scope ambiguity, missing bindings, or unsupported component
-path precision stays unknown/error rather than falling through to the broad rule.
-`policy consolidation` is also read-only. When a compiler-produced advisory scope suggestion exists,
-it groups only matching narrow policies with the same assertion/data class and syntactically contained
-scopes, then requires three independent decision references with no exception, active-policy,
-conflict, or counterexample signal before marking the packet reviewable. It never merges or widens a
-policy.
-`policy history` inspects every violated accepted-history receipt and its current human disposition.
-Disposition records are strict, content-addressed, stored in the policy's public/private home, and
-bound to the exact policy hash, proof, plan, commit, and replay receipt. Corrections append a new
-record with `--supersedes`; prior judgments remain auditable. Only `true_positive_actionable` clears
-the history-evidence gate. False positives, insufficient-parser unknowns, and accepted exceptions
-remain blockers until the policy/evaluator or combined exception semantics are repaired and
-re-proved. A disposition never activates policy: blocking still requires a separate explicit human
-`policy accept`, and a later corrected disposition is rechecked on every gate evaluation.
-`policy shadow --record` appends one content-addressed evaluation for the exact current graph and
-deduplicates retries of the same receipt. Violations use a separate append-only human disposition
-chain, while `policy shadow` reports raw recent-window counts, confirmed and lower-bound precision,
-unknown/error rate, mutation sensitivity, thresholds, and P4-review eligibility. Shadow records
-never warn, block, change proof class, or activate policy; the MCP shadow tool is read-only.
-Planning runs no replay, test, model, or activation; `policy prove` binds its receipt to that plan.
-Proof execution checks out each unique immutable commit into a disposable worktree with hooks,
-user-global Git configuration, private-overlay discovery, and provider selection disabled. It
-indexes cold snapshots through a bounded four-worker pool (hard maximum eight), reuses
-content-validated data-class-separated graph caches, records canonical current/known-good/
-known-bad/accepted-history receipts, then removes every checkout and transient graph. Scheduling
-and cache statistics never enter proof hashes. Project code, builds, and tests are never executed.
-Timeouts, worker failures, unresolved refs, unknowns, and errors remain explicit.
-
-Level-1 evaluators include `must-pass-through` (every statically discovered path from A to C must
-contain B), exact external-package boundaries, and component/component-id selectors over static
-`depends_on` edges. CLI, MCP (`hunch_policy_evaluate`), and strict CI share the exact canonical
-receipt. Direct `reaches`/`not-reaches` contradictions are stored as conflict evidence without
-minting a second policy or changing authority. Candidate records retain the exact alternatives,
-unsupported facts, incumbent, and conflict IDs for proof-card review. Equivalent evidence enriches
-the incumbent idempotently without changing its assertion, scope, proof, lifecycle, or authority.
-Three independently grounded component-policy sources may add an advisory common-path scope
-suggestion, while same-named behavior outside a narrow symbol scope is surfaced as a counterexample.
-Suggestions and counterexamples are review evidence only: the compiled scope is never widened
-automatically.
-
-Executable-behavior policies keep their proof and history replay bound to immutable commits and
-exact dependency snapshots. For advisory delivery, `policy evaluate --staged`, `--working`, the MCP
-workspace option, and the pre-commit `check` path materialize the selected pending snapshot in a
-disposable checkout before running the same hash-pinned test. The receipt binds the base commit,
-snapshot hash, and changed paths; untracked regular files are included, repository hooks and global
-Git configuration remain disabled, and dependency-manifest changes return an explicit error rather
-than using stale dependencies. Advisory violations warn but never block, and `--public-only` never
-loads private policies.
-An intentional narrow opposite can be linked explicitly with `hunch policy exception <child>
---parent <parent> --actor human:<identity> --reason "…"`. The relationship requires identical
-bindings/relation, opposite `reaches` semantics, matching data class/home, and a strictly contained
-scope. Linking invalidates the child's prior proof and authority and returns it to non-blocking
-`compiled` state. The broad parent remains the enforcement unit: its plan, proof, replay and mutation
-receipts bind the full exception tree, and any later exception change retracts blocking eligibility
-until a fresh composite proof is generated. Proof never activates the parent; a separate human
-`policy accept` remains mandatory.
-Models do not participate in evaluation or activation. Plan-bound proofs cover the committed current
-baseline, known-good/known-bad fixtures, bounded accepted history, and a canonical mutation
-manifest. The primary mutation is applied to an immutable disposable source checkout, must remain
-parseable, and persists its exact Git diff plus resulting graph diff. Comment/string parser and
-same-name ambiguity controls remain separate; any failed required receipt prevents blocking review.
-Optional project build/test status is reported separately and is never required for evaluator
-sensitivity. Historical hits are
-not called false positives until classified, and unclassified hits or replay errors prevent
-blocking approval. Shadow evidence and broader compiler inference remain follow-on work and are
-reported as limitations in the proof artifact.
-
-`policy card` (also `hunch_policy_card` over MCP) renders the same deterministic review surface for
-every client: exact assertion and scope, raw evidence vector, unclassified hits, unknown/errors,
-blocking readiness, current authority, limitations, and next actions. It never averages evidence
-into a confidence score and never grants authority.
-
-The versioned 20-case EXP-03 compiler bank is recomputed with:
+- a selected Claude Code, Codex, or Cursor subscription CLI;
+- an opt-in OpenAI-compatible local endpoint such as Ollama, vLLM, LM Studio, or llama.cpp; or
+- the built-in deterministic fallback when no model is available.
 
-```bash
-hunch constitution scorecard
-```
-
-The scorecard reports the raw numerator/denominator, the absolute difference from the preregistered
-70% threshold, a Wilson 95% interval, per-outcome counts, and silent semantic substitutions. One
-unsupported-to-assertion substitution fails the gate even when the aggregate rate remains above the
-threshold. This curated scorecard measures deterministic compiler classification, not real-user
-authoring speed or acceptance; those human-review arms remain a separate EXP-03 study.
-
-## Private when the reasoning is sensitive
-
-Open-source the code without open-sourcing the reasoning.
+When several subscription CLIs are installed, Hunch does not guess which plan to use:
 
 ```bash
-hunch private ~/work/hunch-private/.hunch
-hunch record-bug --private --test "billing regression" --message "…"
-hunch review --private
+hunch provider codex-cli
 ```
 
-Private decisions, bugs, constraints, and wiki pages live in a separate overlay you control.
-Local checks enforce them; public CI reports use `--public-only`, so private memory never appears in
-a pull-request comment or committed grounding file. Private captures default to deterministic local
-synthesis, keeping sensitive diffs and failure messages out of subscription-model drafting.
-
-## A workflow your team can trust
-
-Hunch is deliberately conservative:
-
-- **Human-confirmed rules get the teeth.** Drafted memory advises; confirmed, precise invariants can block.
-- **Every result carries receipts.** Decisions, constraints, bugs, confidence, and evidence are connected.
-- **Drift is visible.** `hunch doctor` catches stale references, stale generated docs, and broken overlay pointers.
-- **Public surfaces are public-only.** Private overlay data stays local unless you explicitly choose to share it.
-- **No magic rewrite bot.** Hunch proposes and checks; you decide what becomes truth.
-
-## Try the moment it earns its keep
+Local and private-network endpoints work without a billing flag. Every public remote requires the
+explicit `HUNCH_SYNTH_ALLOW_METERED=1` opt-in, because Hunch cannot infer cost from a hostname.
+See [Synthesis & billing](https://hunch-pi.vercel.app/docs#synthesis) for setup details.
 
-Imagine an assistant “simplifies” a controller by querying the database directly. Linters are green.
-Unit tests pass. The architecture is still wrong.
+## Local-first and portable
 
-Hunch can answer with the actual context: this boundary exists because of the N+1 incident, the
-service layer was the chosen repair, and the direct import violates a confirmed constraint. That is
-the missing layer between fast code generation and durable engineering judgment.
+Hunch has no hosted memory service or telemetry. Your graph travels with git and speaks MCP, so it
+is not tied to one editor or model provider.
 
-## Certify a release candidate
+Sensitive reasoning can live in a separate private overlay:
 
 ```bash
-npm run gate:release
+hunch private --repo git@github.com:you/project-memory.git
 ```
 
-The same fail-closed runner gates pull requests, main, and npm publication. It binds the package
-version and optional release tag to HEAD; runs typecheck, the full suite, core and VS Code builds,
-a fresh public repository index plus strict architectural conformance, a clean-installed tarball replay/privacy rehearsal, and the
-production dependency audit; then writes a content-addressed receipt under
-`.hunch-cache/release/`. A failed prerequisite stops later commands, a tag/version/commit mismatch
-refuses before execution, and publication remains unreachable unless the exact tagged checkout is
-clean and every gate passes. The receipt includes the prior-version rollback command; it never
-activates, promotes, warns, or blocks a Constitution policy.
+Local tools see the combined graph; public CI and committed documentation stay public-only.
 
 ## Learn more
 
 - [Full documentation](https://hunch-pi.vercel.app/docs)
-- [Interactive product site](https://hunch-pi.vercel.app)
+- [Copy-paste cookbook](https://hunch-pi.vercel.app/cookbook)
 - [VS Code extension](vscode-extension/README.md)
+- [Contributing](CONTRIBUTING.md)
 - [Architecture benchmark](bench/architectural-conformance.md)
-- [15-second demo](demo/architectural-conformance.sh)
 
 Apache-2.0

package/dist/cli/index.js

@@ -29,7 +29,7 @@ import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
-import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, } from "../synthesis/provider.js";
+import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
 import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges } from "../extractors/git.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
@@ -85,7 +85,7 @@ import { movePublicMemoryToPrivate } from "../store/privateMigrate.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
 import { repairDecisionReference } from "../core/refrepair.js";
-import { resolveInvocation } from "./invocation.js";
+import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
 const program = new Command();
 program.name("hunch").description("Hunch — an Engineering Memory OS: a git-native reasoning graph for your codebase.").version(HUNCH_VERSION);
 let openStore = null;
@@ -272,8 +272,8 @@ program
     .option("--since <spec>", "how far back, e.g. 90d", "90d")
     .option("--max <n>", "max commits to process", "40")
     .option("--concurrency <n>", "commits to synthesize in parallel (the LLM call is the bottleneck)", "4")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI per commit and reconcile their drafts (slower, higher-quality; advisory)")
-    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider per commit and reconcile their drafts (slower, higher-quality; advisory)")
+    .option("--verify", "Critic pass: audit each draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times per commit and reconcile (default 2 under --deep)")
     .action(async (opts) => {
     const { store, root } = storeFor();
@@ -283,6 +283,15 @@ program
     const commits = logSince(opts.since, root, Number(opts.max));
     const conc = Math.max(1, Math.min(16, Number(opts.concurrency) || 4));
     console.log(`Backfilling from ${commits.length} commit(s) since ${opts.since} (concurrency ${conc})…`);
+    // Best-effort context-window advisory (issue #11): printed ONCE, before any
+    // commit is drafted — not per-commit, and not under --deep (an ensemble may
+    // fan out to several distinct workers, each with its own configuration).
+    if (!opts.deep && commits.length > 0) {
+        const ctxProvider = await selectProvider();
+        const ctxWarning = await maybeWarnOllamaContext(ctxProvider.name, process.env);
+        if (ctxWarning)
+            console.log(ctxWarning);
+    }
     let written = 0, skipped = 0, llm = 0, heuristic = 0;
     // The per-commit cost is the Claude synthesis spawn; run several at once. Safe:
     // each commit drafts independently and writes its OWN decision file atomically,
@@ -322,8 +331,8 @@ program
     .option("--overlay", "alias of --private")
     .option("--commit", "after a capture, also git add+commit the repo the decision landed in (default: follows auto-commit, ON unless opted out) — the overlay is also pushed; the public .hunch/ rides your next push")
     .option("--no-commit", "skip the auto-commit for this capture even when auto-commit is on")
-    .option("--deep", "Deep Synthesis: ensemble every available subscription CLI and reconcile their drafts (agreement-weighted, advisory). Slower; subscription-only")
-    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra subscription call; advisory)")
+    .option("--deep", "Deep Synthesis: ensemble every available LLM provider and reconcile their drafts (agreement-weighted, advisory). Slower; uses configured subscriptions/local endpoint")
+    .option("--verify", "Critic pass: audit the draft against its commit, prune unsupported alternatives/consequences, down-weight weak grounding (extra provider call; advisory)")
     .option("--samples <n>", "self-consistency depth when only one CLI is installed: sample it n times and reconcile (default 2 under --deep)")
     .action(async (sha, opts) => {
     const { store, root } = storeFor();
@@ -2744,15 +2753,15 @@ program
     const next = writeConfig(paths, { firmness: level }).firmness;
     console.log(`✓ firmness set to ${next} (takes effect on the next agent edit — no restart needed).`);
 });
-// ---- provider (per-user synthesis subscription choice) -------------------
+// ---- provider (per-user synthesis provider choice) -----------------------
 program
     .command("provider")
-    .description("Show or set the local coding-assistant subscription Hunch may use for synthesis. Never changes team config.")
+    .description("Show or set the local LLM provider Hunch may use for synthesis. Never changes team config.")
     .argument("[name]", `auto | ${SYNTH_PREFERENCES.filter((p) => p !== "auto").join(" | ")} (omit to inspect)`)
     .action(async (value) => {
     const root = findRoot();
     if (value != null) {
-        const preference = value.trim();
+        const preference = normalizeProviderName(value.trim()) ?? value.trim();
         if (!SYNTH_PREFERENCES.includes(preference)) {
             return fail(`provider must be one of: ${SYNTH_PREFERENCES.join(", ")}`);
         }
@@ -2765,7 +2774,7 @@ program
         console.log(`✓ local synthesis preference set to ${preference} (gitignored; it never changes a teammate's billing choice).`);
     }
     const resolution = await resolveSynthesisProvider({ root });
-    const envValue = process.env.HUNCH_SYNTH_PROVIDER?.trim();
+    const envValue = normalizeProviderName(process.env.HUNCH_SYNTH_PROVIDER?.trim());
     const local = readSynthesisPreference(root);
     const hasValidEnv = !!envValue && SYNTH_PREFERENCES.includes(envValue);
     console.log(`selected:    ${resolution.provider.name} (${resolution.source})`);
@@ -2779,7 +2788,7 @@ program
     }
     if (resolution.source === "ambiguous") {
         const choices = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => `hunch provider ${s.name}`);
-        console.log(dim("Multiple subscription CLIs are available, so Hunch uses the free deterministic fallback rather than guessing which plan to spend."));
+        console.log(dim("Multiple LLM providers are available, so Hunch uses the free deterministic fallback rather than guessing which subscription or endpoint to use."));
         console.log(`choose one:  ${choices.join("  or  ")}`);
     }
     else if (resolution.source === "unavailable-preference") {
@@ -3313,7 +3322,7 @@ program
             console.log("✓ No drafts to auto-review.");
             return;
         }
-        // Delegate relevance to the harness (subscription CLI) — feature-detected.
+        // Delegate relevance to the configured LLM provider — feature-detected.
         // A dry-run may remain partial (missing verdicts are kept), but --apply is
         // all-or-nothing when judgment was requested: a provider outage must never
         // turn an incomplete batch into an apparently safe mutation plan.
@@ -3342,7 +3351,7 @@ program
                 }
             }
             else {
-                console.log(dim("No subscription CLI available — relevance judgment skipped (dedup + grounding only)."));
+                console.log(dim("No LLM synthesis provider available — relevance judgment skipped (dedup + grounding only)."));
                 judgmentFailures.push(...drafts.map((d) => ({ id: d.id, error: "no subscription relevance judge available" })));
             }
         }
@@ -3779,7 +3788,7 @@ program
 // ---- wiki (generated component wiki — a derived VIEW of the graph) ----------
 program
     .command("wiki")
-    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via a subscription CLI when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
+    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via the configured LLM provider when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
     .option("--dir <dir>", "output directory (default: wiki/, or the manifest's dir once adopted)")
     .option("--heal", "regenerate only new/stale pages (manifest hash mismatch) and remove orphans")
     .option("--check", "report stale pages and exit non-zero (CI gate); writes nothing")
@@ -3844,8 +3853,8 @@ program
         // otherwise: drift says "remove with --heal", --heal refuses to run).
         if (!status.entries.length && !opts.heal)
             return fail("no active components in the graph — run `hunch index` first.");
-        // Prose is optional garnish on the deterministic skeleton: subscription CLI
-        // only (same rule as synthesis), feature-detected, and any failure degrades
+        // Prose is optional garnish on the deterministic skeleton: configured LLM
+        // provider only (same guards as synthesis), feature-detected, and any failure degrades
         // to a template page — generation never depends on a model being present.
         if (opts.proseHeal && opts.llm === false)
             return fail("--prose-heal needs the LLM — drop --no-llm.");
@@ -3854,13 +3863,13 @@ program
         if (opts.llm !== false) {
             const provider = await selectProvider({ root });
             if (provider.draftProse) {
-                console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
+                console.log(`Prose via ${provider.name}; the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
                 if (opts.proseHeal)
                     adoptionProse = (doc, content) => provider.draftProse(adoptProsePrompt(doc, content, status.decisions));
             }
             else {
-                console.log(`No subscription CLI available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
+                console.log(`No LLM synthesis provider available — deterministic template pages${opts.proseHeal ? " (prose-heal skipped)" : ""}.`);
             }
         }
         const res = await generateWiki(store, root, home, {
@@ -4087,22 +4096,16 @@ program
     const resolution = await resolveSynthesisProvider({ root });
     const provider = resolution.provider;
     console.log(`synthesis:  ${provider.name} (${resolution.source})`);
-    const selected = resolution.statuses.find((s) => s.name === provider.name);
-    if (selected?.subscription) {
-        console.log(`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`);
-    }
-    else if (resolution.source === "ambiguous") {
-        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
-        console.log(dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which subscription to spend.`));
-        console.log(dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`));
-    }
-    else if (resolution.source === "unavailable-preference") {
-        console.log(dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`));
-    }
-    else {
-        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`));
-        console.log(dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`));
-    }
+    // Synthesis uses the user's SUBSCRIPTION via a coding-assistant CLI or a
+    // configured local/self-hosted endpoint. Public remotes require the named
+    // metered opt-in. Surface which one — or what's missing (issue #9:
+    // openai-compat has no `subscription` and must not fall through to the
+    // "no assistant CLI found" branch).
+    for (const line of synthesisStatusLines(resolution, process.env))
+        console.log(line);
+    const ctxWarning = await maybeWarnOllamaContext(provider.name, process.env);
+    if (ctxWarning)
+        console.log(ctxWarning);
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
     try {
@@ -4199,9 +4202,6 @@ function reportClaudeConfigHeal() {
     }
     console.log(dim(`  ↳ backup: ${res.backup}`));
 }
-function dim(s) {
-    return `\x1b[2m${s}\x1b[0m`;
-}
 function fail(msg) {
     console.error(`error: ${msg}`);
     process.exitCode = 1;

package/dist/cli/invocation.js

@@ -1,8 +1,61 @@
-/** Figures out how to re-invoke this CLI from a git hook / .mcp.json, working
- *  both when running the built dist (plain node) and in dev via tsx. */
+/** Side-effect-free shared CLI logic — safe for any module (including tests)
+ *  to import, unlike src/cli/index.ts, which runs the whole program at
+ *  import time. Holds: how to re-invoke this CLI from a git hook / .mcp.json
+ *  (working both when running the built dist and in dev via tsx), plus small
+ *  formatting helpers (dim(), doctor's synthesisStatusLines()) that need the
+ *  same import-safety to be unit-testable. */
 import { fileURLToPath } from "node:url";
+import { probeOllamaNumCtx } from "../synthesis/provider.js";
 /** Published package name — used for OS-agnostic invocations (see below). */
 const PKG = "@davesheffer/hunch";
+export function dim(s) {
+    return `\x1b[2m${s}\x1b[0m`;
+}
+/** The doctor command's synthesis-status line(s) for a resolved provider.
+ *  Exported for testing — the previous version (a bare provider-name switch,
+ *  before the resolveSynthesisProvider preference system existed) had zero
+ *  test coverage, which is how issue #8 (openai-compat misreported as "no
+ *  assistant CLI found") shipped unnoticed through three review passes. That
+ *  bug resurfaces here for the same reason: resolution.statuses carries a
+ *  `subscription` field for the CLI providers but openai-compat's is null (it
+ *  isn't a subscription), so it must be special-cased explicitly rather than
+ *  falling through to the "no assistant CLI" branch. */
+export function synthesisStatusLines(resolution, env) {
+    const provider = resolution.provider;
+    const selected = resolution.statuses.find((s) => s.name === provider.name);
+    if (selected?.subscription) {
+        return [`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`];
+    }
+    if (provider.name === "openai-compat") {
+        const base = env.HUNCH_SYNTH_BASE_URL ?? "(unset)";
+        const model = env.HUNCH_SYNTH_MODEL ?? "(unset)";
+        const keyNote = env.HUNCH_SYNTH_API_KEY ? " (HUNCH_SYNTH_API_KEY set)" : " (no API key)";
+        return [`            ↳ LLM synthesis via local/self-hosted endpoint ${base} (model: ${model})${keyNote}`];
+    }
+    if (resolution.source === "ambiguous") {
+        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
+        return [
+            dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which provider to use.`),
+            dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`),
+        ];
+    }
+    if (resolution.source === "unavailable-preference") {
+        return [dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`)];
+    }
+    return [
+        dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`),
+        dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`),
+    ];
+}
+/** Gate + fetch the Ollama context-window advisory (issue #11): only relevant
+ *  for the openai-compat provider, so every other provider is a no-op. Kept
+ *  separate from synthesisStatusLines (sync, already fully covered) because
+ *  this one makes a best-effort network call. */
+export async function maybeWarnOllamaContext(providerName, env) {
+    if (providerName !== "openai-compat")
+        return null;
+    return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL ?? "", env.HUNCH_SYNTH_MODEL ?? "");
+}
 export function resolveInvocation() {
     const entry = fileURLToPath(import.meta.url).replace(/invocation\.(js|ts)$/, "index.$1");
     const isDev = entry.endsWith(".ts");

package/dist/store/embedder.js

@@ -3,7 +3,7 @@
  * "add embeddings once keyword search proves insufficient" upgrade).
  *
  * Embeddings are LOCAL and FREE. Anthropic has no embeddings endpoint and the
- * project is subscription-only (see synthesis/provider.ts), so we run a small
+ * project avoids implicit metered inference (see synthesis/provider.ts), so we run a small
  * sentence-transformer locally via transformers.js. That library is an OPTIONAL
  * dependency, dynamically imported — if it isn't installed, `selectEmbedder()`
  * returns null and the whole feature degrades to pure FTS (the lean-install

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

@@ -95,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.1",
+  "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).",