@davesheffer/hunch 0.5.0 → 0.9.0

package/dist/store/hunchStore.js

@@ -4,6 +4,7 @@ import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { pathMatchesGlob } from "../core/glob.js";
+import { edgeId } from "../core/ids.js";
 export class HunchStore {
     paths;
     json;
@@ -273,13 +274,17 @@ export class HunchStore {
         return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
     }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
-     *  symbol name (hunch_why). */
-    why(target) {
+     *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
+     *  return only decisions/constraints whose valid-time window contained that
+     *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
+     *  history-inclusive view (backward-compatible default). */
+    why(target, opts = {}) {
         const decisions = this.json.loadAll("decisions");
         const bugs = this.json.loadAll("bugs");
         const constraints = this.json.loadAll("constraints");
         const symbols = this.json.loadAll("symbols");
         const components = this.json.loadAll("components");
+        const asOf = opts.asOf;
         const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
@@ -287,9 +292,11 @@ export class HunchStore {
         const fileMatch = (files) => files.some((f) => f === target || (isPath && (f.endsWith(target) || target.endsWith(f))) || fileSet.has(f));
         return {
             target,
-            decisions: decisions.filter((d) => fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths)))),
+            decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
+                && inWindow(d.valid_from, d.valid_to, asOf)),
             bugs: bugs.filter((b) => fileMatch(b.affected_files) || b.affected_symbols.some((s) => symIds.has(s))),
-            constraints: constraints.filter((c) => c.scope.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+            constraints: constraints.filter((c) => c.scope.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))
+                && inWindow(c.valid_from, c.valid_to, asOf)),
             symbols: matchedSymbols,
             components: components.filter((c) => c.paths.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
         };
@@ -357,13 +364,114 @@ export class HunchStore {
         }
         return [...out.values()].sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
     }
-    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints). */
-    checkConstraints(scope) {
+    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
+     *  By default only ACTIVE invariants are returned — a retired constraint is no
+     *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
+     *  that instant (time-travel: "what must I not have broken as of commit X?"). */
+    checkConstraints(scope, opts = {}) {
         const all = this.json.loadAll("constraints");
+        const asOf = opts.asOf;
         return all
             .filter((c) => c.scope.some((g) => pathMatchesGlob(scope, g) || pathMatchesGlob(g, scope) || g === scope))
+            .filter((c) => (asOf ? inWindow(c.valid_from, c.valid_to, asOf) : c.status !== "retired"))
             .sort((a, b) => sev(b.severity) - sev(a.severity));
     }
+    /** Time-travel: the decision history for a target — every decision touching it,
+     *  newest-first, with its valid-time window and supersession links. Answers
+     *  "what did we believe, and when/why did it change?" (hunch_timeline). */
+    timeline(target) {
+        return this.why(target).decisions.sort((a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date));
+    }
+    /** Invalidate, don't delete (Zep edge-invalidation): close `oldId`'s valid-time
+     *  window at the superseding decision's `valid_from`, mark it superseded + linked,
+     *  and write a `supersedes` edge. Returns the updated old decision, or null if it
+     *  doesn't exist. All writes are atomic via json.put (con_902759b3dc). */
+    supersede(oldId, by) {
+        const old = this.json.get("decisions", oldId);
+        if (!old || old.id === by.id)
+            return null;
+        const closed = {
+            ...old,
+            status: "superseded",
+            superseded_by: by.id,
+            valid_to: old.valid_to ?? by.valid_from ?? null,
+        };
+        this.json.put("decisions", closed);
+        const edge = {
+            id: edgeId(by.id, oldId, "supersedes"),
+            from: by.id,
+            to: oldId,
+            type: "supersedes",
+            reason: `${by.id} supersedes ${oldId}`,
+            strength: 1,
+            provenance: { source: "derived", confidence: 1, evidence: [by.id, oldId] },
+        };
+        this.json.put("edges", edge);
+        return closed;
+    }
+    /** Regression Guard: detect a change RE-INTRODUCING something an in-force
+     *  decision deliberately removed. Matches the added symbols/deps of a diff
+     *  against the `retired` signal of decisions concerning the touched files. A hit
+     *  is `blocking` when the retiring decision is tied to an ACTIVE blocking
+     *  constraint (via source_decision) — that's the only case the strict guard
+     *  fails the commit on; everything else is an advisory warning. */
+    regressionHits(added, files) {
+        const addedSyms = new Set(added.symbols);
+        const addedDeps = new Set(added.deps);
+        if (!addedSyms.size && !addedDeps.size)
+            return [];
+        const fileRelevant = (related) => related.some((f) => files.some((x) => pathRelated(x, f)));
+        const decisions = this.json.loadAll("decisions");
+        // decisions tied to an active blocking constraint via source_decision
+        const blockingDec = new Set(this.json.loadAll("constraints")
+            .filter((c) => c.severity === "blocking" && c.status !== "retired" && c.source_decision)
+            .map((c) => c.source_decision));
+        const out = [];
+        const seen = new Set(); // dedup by kind+name: report each resurrected item once
+        const add = (d, kind, name) => {
+            const key = `${kind}:${name}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            out.push({ decision: d.id, title: d.title, kind, name, blocking: blockingDec.has(d.id), reason: d.decision || d.title });
+        };
+        // Blocking-linked decisions first, so a deduped hit keeps the higher-severity
+        // attribution (the strict guard fails on `blocking`).
+        const ordered = [...decisions].sort((a, b) => Number(blockingDec.has(b.id)) - Number(blockingDec.has(a.id)));
+        for (const d of ordered) {
+            // Only IN-FORCE decisions: re-adding what an OUTDATED (superseded) decision
+            // removed is not a regression against the current design.
+            if (d.superseded_by || d.status === "superseded")
+                continue;
+            if (!d.retired.symbols.length && !d.retired.deps.length)
+                continue;
+            if (!fileRelevant(d.related_files))
+                continue;
+            for (const s of d.retired.symbols)
+                if (addedSyms.has(s))
+                    add(d, "symbol", s);
+            for (const dep of d.retired.deps)
+                if (addedDeps.has(dep))
+                    add(d, "dep", dep);
+        }
+        return out;
+    }
+    /** The symbols/deps an in-force decision deliberately RETIRED from a file — the
+     *  agent-hook grounding ("don't re-add X here; dec_Y removed it"). No diff is
+     *  available at edit time, so this surfaces the risk as context, not a block. */
+    retiredForFile(file) {
+        const out = [];
+        for (const d of this.json.loadAll("decisions")) {
+            if (d.superseded_by || d.status === "superseded")
+                continue;
+            if (!d.retired.symbols.length && !d.retired.deps.length)
+                continue;
+            if (!d.related_files.some((f) => pathRelated(f, file)))
+                continue;
+            out.push({ decision: d.id, title: d.title, symbols: d.retired.symbols, deps: d.retired.deps });
+        }
+        return out;
+    }
     /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
     bugLineage(symptomOrSymbol) {
         const bugs = this.json.loadAll("bugs");
@@ -450,8 +558,8 @@ export class HunchStore {
     /** The Context Assembler (DESIGN §2.1/§6): the MINIMAL relevant Hunch slice for
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
-    assembleContext(target, budget = 1500) {
-        const w = this.why(target);
+    assembleContext(target, budget = 1500, opts = {}) {
+        const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);
         const blast = new Map();
         for (const id of symIds) {
@@ -477,6 +585,25 @@ export class HunchStore {
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
 }
+/** Is a valid-time window open at `asOf`? `valid_from` undefined = always-started
+ *  (legacy records). `valid_to` null = still in force. `asOf` undefined disables
+ *  filtering (the history-inclusive default). Half-open [from, to) so a record and
+ *  the one that supersedes it never both match at the supersession instant. */
+/** Do two repo paths refer to the same file? Exact match, or one is a trailing
+ *  path-SEGMENT suffix of the other (e.g. "x.ts" vs "src/x.ts") — anchored at a
+ *  "/" boundary so "re.ts" never matches "store.ts" (the bare-endsWith hazard). */
+function pathRelated(a, b) {
+    return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
+}
+function inWindow(valid_from, valid_to, asOf) {
+    if (!asOf)
+        return true;
+    if (valid_from && valid_from > asOf)
+        return false;
+    if (valid_to != null && asOf >= valid_to)
+        return false;
+    return true;
+}
 function round(n) {
     return Math.round(n * 100) / 100;
 }

package/dist/synthesis/provider.js

@@ -132,9 +132,55 @@ const BUG_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
+// 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 {
+    /** 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) {
+        const env = { ...process.env };
+        for (const k of stripEnv)
+            delete env[k];
+        const { stdout } = await pexecIn(bin, args, {
+            input: prompt,
+            env,
+            cwd: tmpdir(),
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: timeoutMs,
+        });
+        return stdout;
+    }
+    async draftDecision(input) {
+        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
+        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
+        // provider, whose draft is honestly labeled ("inferred", low confidence).
+        if (!draft)
+            throw new Error(`${this.name}: no usable decision JSON in output`);
+        // For a LARGE diff the model only saw the structured summary + a sample — haircut
+        // the confidence and tag the source so provenance stays honest.
+        if (input.diff.length > LARGE_DIFF_CHARS) {
+            return { ...draft, confidence: Math.min(draft.confidence, 0.5), source: `${draft.source}+summary` };
+        }
+        return draft;
+    }
+    async draftBug(input) {
+        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
+        const draft = bugDraftFromText(text, input.test, input.message);
+        if (!draft)
+            throw new Error(`${this.name}: no usable bug JSON in output`);
+        return draft;
+    }
+}
+// --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
 // --------------------------------------------------------------------------
-class ClaudeCliProvider {
+class ClaudeCliProvider extends CliSynthProvider {
     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.
@@ -190,31 +236,54 @@ class ClaudeCliProvider {
         }
         return envelope.result ?? stdout;
     }
-    async draftDecision(input) {
-        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
-        const draft = decisionDraftFromText(text, input.subject);
-        // No usable LLM JSON (truncation, refusal, prose-only) → THROW so the safe
-        // wrapper falls back to the deterministic provider, whose diff-structured
-        // draft is both more useful AND honestly labeled ("inferred", low confidence)
-        // than a hollow record mislabeled as an LLM draft.
-        if (!draft)
-            throw new Error("claude-cli: no usable decision JSON in output");
-        // For a LARGE diff the model only saw the structured summary + a sample, not
-        // the full patch (commitPrompt → renderDiff). The "why" is therefore lower-
-        // fidelity than a draft made from the whole diff, so haircut the confidence
-        // and tag the source — keeping provenance honest (a summary-sourced draft must
-        // not masquerade as a full-fidelity llm_draft at 0.65).
-        if (input.diff.length > LARGE_DIFF_CHARS) {
-            return { ...draft, confidence: Math.min(draft.confidence, 0.5), source: `${draft.source}+summary` };
+}
+// --------------------------------------------------------------------------
+// Provider B1: OpenAI Codex CLI (`codex exec`) — billed to the ChatGPT subscription
+// --------------------------------------------------------------------------
+class CodexCliProvider extends CliSynthProvider {
+    name = "codex-cli";
+    model = process.env.HUNCH_CODEX_MODEL; // omit → codex uses its configured default
+    async available() {
+        try {
+            await pexecIn("codex", ["--version"], { timeout: 8000 });
+            return true;
+        }
+        catch {
+            return false;
         }
-        return draft;
     }
-    async draftBug(input) {
-        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
-        const draft = bugDraftFromText(text, input.test, input.message);
-        if (!draft)
-            throw new Error("claude-cli: no usable bug JSON in output");
-        return draft;
+    async run(prompt) {
+        // `codex exec --json -` reads the prompt from STDIN (the `-`), emits JSONL
+        // events. Strip OPENAI_API_KEY so it uses ChatGPT (subscription) auth, not the
+        // pay-per-token API — consistent with the subscription-only rule.
+        const args = ["exec", "--json", ...(this.model ? ["-m", this.model] : []), "-"];
+        const out = await this.runCli("codex", args, ["OPENAI_API_KEY"], prompt);
+        return extractCodexText(out);
+    }
+}
+// --------------------------------------------------------------------------
+// Provider B2: Cursor Agent CLI (`cursor-agent -p`) — billed to the Cursor subscription
+// --------------------------------------------------------------------------
+class CursorCliProvider extends CliSynthProvider {
+    name = "cursor-agent";
+    model = process.env.HUNCH_CURSOR_MODEL;
+    async available() {
+        try {
+            await pexecIn("cursor-agent", ["--version"], { timeout: 8000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async run(prompt) {
+        // `-p --output-format text` → final answer as plain text (no event stream to
+        // parse). `--trust` so it runs non-interactively. Prompt over stdin. Cursor's
+        // CLI uses the user's Cursor login (subscription) — no API key to strip.
+        const args = ["-p", "--output-format", "text", "--trust", ...(this.model ? ["-m", this.model] : [])];
+        // Shorter timeout than the others: cursor-agent -p is reported to hang in some
+        // headless setups; cap the stall before degrading to the deterministic provider.
+        return this.runCli("cursor-agent", args, [], prompt, 45_000);
     }
 }
 // --------------------------------------------------------------------------
@@ -269,23 +338,71 @@ export class DeterministicProvider {
         };
     }
 }
-const PROVIDERS = [new ClaudeCliProvider(), new DeterministicProvider()];
+/** Extract the final assistant message from `codex exec --json` output (newline-
+ *  delimited JSON events). Codex tags assistant turns as `item.type ==="agent_message"`,
+ *  but it ALSO emits `item.text` for reasoning and may append trailing events — so we
+ *  prefer the last AGENT message and only fall back to the last any-text when none is
+ *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
+ *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
+export function extractCodexText(out) {
+    const texts = [];
+    const agentTexts = [];
+    for (const line of out.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        try {
+            const o = JSON.parse(t);
+            const item = o.item;
+            const cand = (item?.text ?? o.text ?? o.message);
+            if (typeof cand === "string" && cand.trim()) {
+                texts.push(cand);
+                const ty = (item?.type ?? o.type);
+                if (typeof ty === "string" && /agent|assistant|message\b/.test(ty) && !/reason/.test(ty))
+                    agentTexts.push(cand);
+            }
+        }
+        catch {
+            /* not a JSON event line — skip */
+        }
+    }
+    if (agentTexts.length)
+        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).
+const PROVIDERS = [
+    new ClaudeCliProvider(),
+    new CodexCliProvider(),
+    new CursorCliProvider(),
+    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();
+function isAvailable(p) {
+    let v = availCache.get(p.name);
+    if (!v) {
+        v = p.available().catch(() => false);
+        availCache.set(p.name, 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 p.available()))
+        if (p && (await isAvailable(p)))
             return p;
     }
     for (const p of PROVIDERS) {
-        try {
-            if (await p.available())
-                return p;
-        }
-        catch {
-            /* try next */
-        }
+        if (await isAvailable(p))
+            return p;
     }
     return new DeterministicProvider();
 }

package/dist/synthesis/synthesize.js

@@ -93,8 +93,17 @@ export async function syncCommit(store, root, sha, opts = {}) {
         related_components: relatedComponents,
         related_files: codeFiles,
         supersedes: existing?.supersedes ?? null,
+        superseded_by: existing?.superseded_by ?? null,
         caused_by_bug: existing?.caused_by_bug ?? null,
         commit: meta.shortSha,
+        // Valid-time window is git-anchored: the decision takes effect at its commit
+        // date and stays in force until a later decision supersedes it (preserve any
+        // window an earlier sync/supersession already set on this same commit's record).
+        valid_from: existing?.valid_from ?? meta.date,
+        valid_to: existing?.valid_to ?? null,
+        // What this commit DELETED — the Regression Guard later matches a re-adding
+        // diff against this (recompute from the fresh analysis, even on --force).
+        retired: { symbols: analysis.removedSymbols.map((s) => s.name), deps: analysis.removedDeps },
         provenance: {
             source: draft.source,
             confidence: draft.confidence,
@@ -227,6 +236,9 @@ function promoteConstraint(store, bug) {
         rationale: `Derived from ${bug.id}: ${bug.root_cause || bug.symptom}`,
         source_decision: null,
         violations: [],
+        status: "active",
+        valid_from: new Date().toISOString(),
+        valid_to: null,
         provenance: { source: "derived", confidence: Math.min(0.9, bug.provenance.confidence + 0.2), evidence: [`bug:${bug.id}`] },
     };
     return store.json.put("constraints", con);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",