@davesheffer/hunch 1.6.0 → 1.7.0

package/README.md

@@ -62,6 +62,12 @@ it adds a native lifecycle adapter too.
 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

package/dist/cli/index.js

@@ -28,7 +28,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 { selectProvider } from "../synthesis/provider.js";
+import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, } from "../synthesis/provider.js";
 import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
@@ -445,7 +445,20 @@ function configureOverlay(dir, opts, mode) {
     // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
     const rel = relative(root, hunchDir);
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
-    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
+    const localFile = join(paths.hunch, "local.json");
+    let existingLocal = {};
+    if (existsSync(localFile)) {
+        try {
+            const parsed = JSON.parse(readFileSync(localFile, "utf8"));
+            if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                throw new Error("not an object");
+            existingLocal = parsed;
+        }
+        catch {
+            return fail(`refusing to overwrite malformed local configuration: ${localFile}`);
+        }
+    }
+    writeFileAtomic(localFile, JSON.stringify({ ...existingLocal, privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
     // SHARED mode with a remote: publish the store's URL in a COMMITTED team.json, so a
     // fresh clone / new teammate / headless agent auto-connects on `hunch init` (or MCP
@@ -1543,6 +1556,48 @@ 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) -------------------
+program
+    .command("provider")
+    .description("Show or set the local coding-assistant subscription 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();
+        if (!SYNTH_PREFERENCES.includes(preference)) {
+            return fail(`provider must be one of: ${SYNTH_PREFERENCES.join(", ")}`);
+        }
+        try {
+            writeSynthesisPreference(root, preference);
+        }
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+        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 local = readSynthesisPreference(root);
+    const hasValidEnv = !!envValue && SYNTH_PREFERENCES.includes(envValue);
+    console.log(`selected:    ${resolution.provider.name} (${resolution.source})`);
+    console.log(`preference:  ${hasValidEnv ? `environment: ${envValue}` : `local: ${local}`}`);
+    if (envValue && !hasValidEnv)
+        console.log(dim(`HUNCH_SYNTH_PROVIDER=${envValue} is unknown and is being ignored.`));
+    console.log("available:");
+    for (const status of resolution.statuses) {
+        const billing = status.subscription ? ` — ${status.subscription}` : "";
+        console.log(`  ${status.available ? "✓" : "·"} ${status.name}: ${status.label}${billing}`);
+    }
+    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(`choose one:  ${choices.join("  or  ")}`);
+    }
+    else if (resolution.source === "unavailable-preference") {
+        console.log(dim(`Your ${resolution.preference} preference is not available; Hunch is using the local deterministic fallback.`));
+    }
+});
 // ---- status (enforcement readiness at a glance) ---------------------------
 program
     .command("status")
@@ -1965,7 +2020,7 @@ program
         // and any per-draft failure degrades to "not judged" (kept for a human).
         const verdicts = new Map();
         if (opts.llm !== false && !opts.private) {
-            const provider = await selectProvider();
+            const provider = await selectProvider({ root });
             if (provider.judgeDraft) {
                 // The candidate pool for duplicate_of / restatement: the LIVE, vouched records.
                 const existing = all
@@ -2284,7 +2339,7 @@ program
         let prose;
         let adoptionProse;
         if (opts.llm !== false) {
-            const provider = await selectProvider();
+            const provider = await selectProvider({ root });
             if (provider.draftProse) {
                 console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
@@ -2516,24 +2571,24 @@ program
     const onDisk = readManifest(hunchPaths(root)).schema_version;
     const schemaNote = onDisk === SCHEMA_VERSION ? "" : onDisk > SCHEMA_VERSION ? `  ⚠ newer than this Hunch (v${SCHEMA_VERSION}) — upgrade hunch` : `  ⚠ run \`hunch migrate\``;
     console.log(`schema:     v${onDisk} (hunch v${SCHEMA_VERSION})${schemaNote}`);
-    const provider = await selectProvider();
-    console.log(`synthesis:  ${provider.name}`);
-    // Synthesis is billed to the user's SUBSCRIPTION via a coding-assistant CLI,
-    // never a pay-per-token API key. Surface which one — or what's missing.
-    const SUB = {
-        "claude-cli": { label: "Claude subscription (claude CLI)", strip: "ANTHROPIC_API_KEY" },
-        "codex-cli": { label: "ChatGPT subscription (codex CLI)", strip: "OPENAI_API_KEY" },
-        "cursor-agent": { label: "Cursor subscription (cursor-agent CLI)" },
-    };
-    const sub = SUB[provider.name];
-    if (sub) {
-        const hadKey = sub.strip && !!process.env[sub.strip];
-        console.log(`            ↳ LLM synthesis billed to your ${sub.label}` +
-            (hadKey ? ` (${sub.strip} in env is stripped — never billed to the API)` : ``));
+    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(`              for full synthesis install one: Claude Code (\`claude /login\`), Codex (\`codex login\`), or Cursor (\`cursor-agent login\`)`));
+        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>\`.`));
     }
     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`);

package/dist/synthesis/provider.js

@@ -1,23 +1,26 @@
 /**
  * Pluggable synthesis provider for the WRITE path (DESIGN.md §4 / §7).
  *
- * LLM synthesis is driven by the user's Claude **subscription** via the `claude`
- * CLI — never the pay-per-token Anthropic API. We try, in order:
- * claude-cli → deterministic-fallback. The fallback always works (no creds, no
- * network) and emits a LOW-confidence draft, honoring the design rule that
- * auto-captured memory is advisory and cheap to discard.
+ * 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)
+ * or overrides per shell with HUNCH_SYNTH_PROVIDER. Ambiguous auto mode stays
+ * deterministic and free.
  *
- * Subscription, not API: Claude Code's auth precedence puts `ANTHROPIC_API_KEY`
- * (and `ANTHROPIC_AUTH_TOKEN`) ABOVE subscription OAuth, and in headless `-p`
- * mode the API key is *always* used when present. So we strip those vars from
- * the child env (see ClaudeCliProvider.run) to force the CLI down to subscription
- * OAuth / CLAUDE_CODE_OAUTH_TOKEN. There is intentionally NO API-key provider.
+ * Subscription, not API: provider-specific API credentials are removed from the
+ * child env wherever the CLI would otherwise prefer them. There is intentionally
+ * NO direct API-key provider.
  *
  * 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 { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "../core/io.js";
 import { summarizeDiff } from "../extractors/diff.js";
 const IS_WIN = process.platform === "win32";
 /**
@@ -96,6 +99,16 @@ export function pexecIn(cmd, args, opts = {}) {
         child.stdin.end();
     });
 }
+/** 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"];
+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" },
+    deterministic: { label: "Deterministic local fallback", subscription: null },
+};
 const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
 developer activity (a git commit diff, or a test failure) into a single structured
 "why" record. Be precise and evidence-grounded; never invent facts not supported by
@@ -169,7 +182,7 @@ const VERIFY_TOOL = {
 // --------------------------------------------------------------------------
 // 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_5a7c0733f7). The prompt always goes over STDIN (never argv — keeps untrusted
+// 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.
 // --------------------------------------------------------------------------
@@ -447,9 +460,9 @@ export function extractCodexText(out) {
         return agentTexts[agentTexts.length - 1];
     return texts.length ? texts[texts.length - 1] : out;
 }
-// Priority order: try each subscription CLI, then the always-available heuristic.
-// HUNCH_SYNTH_PROVIDER forces one by name (claude-cli / codex-cli / cursor-agent /
-// deterministic).
+// This registry is deliberately NOT a priority order. Auto mode only spends a
+// subscription when it can identify exactly one usable CLI; see
+// resolveSynthesisProvider below.
 const PROVIDERS = [
     new ClaudeCliProvider(),
     new CodexCliProvider(),
@@ -457,31 +470,126 @@ const PROVIDERS = [
     new DeterministicProvider(),
 ];
 // Availability rarely changes within a process (a CLI doesn't get installed mid-run),
-// and selectProvider() runs on every sync/recordFailure — so memoize each probe.
-// Especially matters in the long-lived MCP server and on machines with NO assistant
-// CLI, where an uncached pass spawns one failing `--version` per provider every time.
-const availCache = new Map();
+// 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();
 function isAvailable(p) {
-    let v = availCache.get(p.name);
+    let v = availCache.get(p);
     if (!v) {
         v = p.available().catch(() => false);
-        availCache.set(p.name, v);
+        availCache.set(p, v);
     }
     return v;
 }
-/** Choose the first available provider, honoring HUNCH_SYNTH_PROVIDER override. */
-export async function selectProvider() {
-    const forced = process.env.HUNCH_SYNTH_PROVIDER;
-    if (forced) {
-        const p = PROVIDERS.find((x) => x.name === forced);
-        if (p && (await isAvailable(p)))
-            return p;
+function isSynthPreference(value) {
+    return !!value && SYNTH_PREFERENCES.includes(value);
+}
+function fallbackProvider(providers) {
+    return providers.find((p) => p.name === "deterministic") ?? new DeterministicProvider();
+}
+function localPreferencePath(root) {
+    return join(root, ".hunch", "local.json");
+}
+/** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
+ * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
+ * never destroys someone else's local settings. */
+export function readSynthesisPreference(root) {
+    try {
+        const file = localPreferencePath(root);
+        if (!existsSync(file))
+            return "auto";
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return typeof parsed.synthProvider === "string" && isSynthPreference(parsed.synthProvider)
+            ? parsed.synthProvider
+            : "auto";
     }
-    for (const p of PROVIDERS) {
-        if (await isAvailable(p))
-            return p;
+    catch {
+        return "auto";
+    }
+}
+/** 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))
+        throw new Error(`unknown synthesis provider preference: ${preference}`);
+    const file = localPreferencePath(root);
+    let local = {};
+    if (existsSync(file)) {
+        const raw = readFileSync(file, "utf8");
+        if (raw.trim()) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                    throw new Error("not an object");
+                local = parsed;
+            }
+            catch {
+                throw new Error(`refusing to overwrite malformed local configuration: ${file}`);
+            }
+        }
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify({ ...local, synthProvider: preference }, null, 2)}\n`);
+}
+async function statusesFor(providers) {
+    const statuses = [];
+    for (const provider of providers) {
+        if (!SYNTH_PROVIDER_NAMES.includes(provider.name))
+            continue;
+        const name = provider.name;
+        const info = PROVIDER_INFO[name];
+        statuses.push({ name, ...info, available: await isAvailable(provider) });
+    }
+    return statuses;
+}
+/** Resolve the provider without ever inferring which of several installed products is
+ * the one the user intends to spend. Precedence is deliberate: a one-shell override,
+ * then a per-user local preference, then safe auto-detection. */
+export async function resolveSynthesisProvider(opts = {}) {
+    const providers = opts.providers ?? PROVIDERS;
+    const env = opts.env ?? process.env;
+    const statuses = await statusesFor(providers);
+    const fallback = fallbackProvider(providers);
+    const find = (name) => providers.find((p) => p.name === name);
+    const usable = async (name) => {
+        const provider = find(name);
+        return provider && await isAvailable(provider) ? provider : undefined;
+    };
+    const environment = env.HUNCH_SYNTH_PROVIDER?.trim();
+    if (environment && isSynthPreference(environment) && environment !== "auto") {
+        const selected = await usable(environment);
+        if (selected)
+            return { provider: selected, source: "environment", preference: environment, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference: environment, statuses };
+    }
+    // `HUNCH_SYNTH_PROVIDER=auto` is useful in CI or a shell profile: it explicitly
+    // suppresses the local preference and re-enters the safe auto policy.
+    const preference = environment === "auto"
+        ? "auto"
+        : opts.root ? readSynthesisPreference(opts.root) : "auto";
+    if (preference !== "auto") {
+        const selected = await usable(preference);
+        if (selected)
+            return { provider: selected, source: "local", preference, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference, statuses };
+    }
+    const available = statuses.filter((status) => status.name !== "deterministic" && status.available);
+    if (available.length === 1) {
+        const selected = await usable(available[0].name);
+        if (selected)
+            return { provider: selected, source: "single-available", preference, statuses };
     }
-    return new DeterministicProvider();
+    return {
+        provider: fallback,
+        source: available.length > 1 ? "ambiguous" : "none",
+        preference,
+        statuses,
+    };
+}
+/** The provider used by normal synthesis. See `resolveSynthesisProvider` for a
+ * diagnosable result with the selection source and every candidate's availability. */
+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
@@ -490,9 +598,9 @@ export async function selectProvider() {
 // 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. */
-export async function selectWorkers() {
+export async function selectWorkers(opts = {}) {
     const out = [];
-    for (const p of PROVIDERS) {
+    for (const p of opts.providers ?? PROVIDERS) {
         if (p.name === "deterministic")
             continue; // workers are real subscription CLIs only
         if (await isAvailable(p))
@@ -592,7 +700,7 @@ export class EnsembleProvider {
  *  (the caller then falls back to the normal single-provider path). `samples` sets
  *  the self-consistency depth for the single-CLI case. */
 export async function selectEnsemble(opts = {}) {
-    const workers = await selectWorkers();
+    const workers = await selectWorkers(opts);
     // The self-consistency policy default (DEFAULT_SAMPLES) is applied HERE, not in the
     // provider — so a single CLI under --deep is sampled N times, while direct
     // construction stays passthrough. `--samples 1` opts back out.
@@ -601,9 +709,9 @@ export async function selectEnsemble(opts = {}) {
 /** 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
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
-export async function selectVerifier() {
-    const workers = await selectWorkers();
-    return workers[0] ?? null;
+export async function selectVerifier(opts = {}) {
+    const { provider } = await resolveSynthesisProvider(opts);
+    return provider.name === "deterministic" ? null : provider;
 }
 // ---- Verification (the Critic pass) ---------------------------------------
 // Audit a draft against the commit it came from, then PRUNE unsupported

package/dist/synthesis/synthesize.js

@@ -98,9 +98,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const provider = localOnly
         ? new DeterministicProvider()
         : opts.deep
-            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
+            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider({ root })
             : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
-                ? await selectProvider()
+                ? await selectProvider({ root })
                 : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
@@ -108,7 +108,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // (BEFORE they scaffold tripwires below) and consequences, and lower confidence on weak
     // grounding. No-ops when no assistant CLI is available; never raises trust (dec_9a2f2fe72a).
     if (wantVerify)
-        draft = await verifyDecisionSafe(await selectVerifier(), input, draft);
+        draft = await verifyDecisionSafe(await selectVerifier({ root }), input, draft);
     // Advisory synthesis telemetry for `hunch review` — which provider ran, how many drafts
     // were reconciled, their agreement, and the verifier's grounding. Rides in `evidence`
     // (no schema change → respects forward-migration invariant con_947c578b2c).
@@ -199,7 +199,7 @@ export async function recordFailure(store, root, failure, opts = {}) {
     // A private bug may contain a stack trace, customer data, or secrets. Keep the
     // whole capture local unless the caller deliberately routes it through a shared
     // (non-private) workflow.
-    const provider = opts.private ? new DeterministicProvider() : await selectProvider();
+    const provider = opts.private ? new DeterministicProvider() : await selectProvider({ root });
     const input = {
         test: failure.test,
         message: failure.message,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "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).",