@davesheffer/hunch 0.31.0 → 0.33.0

package/README.md

@@ -185,6 +185,16 @@ is **OS-agnostic**: paths are stored in POSIX form and an installed Hunch regist
 server by package name, so Windows / macOS / Linux teammates share one memory without
 per-machine fixups. → [docs](https://hunch-pi.vercel.app/docs#team)
 
+### Branches & worktrees
+
+Memory follows you across every branch and **git worktree**, with no per-worktree setup. The
+private overlay is registered once at the repo's **git common dir** (shared by all worktrees), so
+a fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
+already wired in with **`hunch worktree <path> [-b <branch>]`**, or just run `hunch init` / `hunch
+private` once and every worktree picks it up. Auto-captured decisions are tagged with their branch,
+and concurrent overlay writes are serialized — so parallel worktrees never corrupt or lose memory.
+`hunch doctor` confirms a worktree is sharing.
+
 ## Private memory (public repo, private context)
 
 Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a

package/dist/cli/index.js

@@ -28,12 +28,13 @@ 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 { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, gitUntrackCached } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree } from "../extractors/git.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
+import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
@@ -154,6 +155,15 @@ program
     // case-split in ~/.claude.json, merge it so hunch resolves under either casing.
     // No-op (silent) off Windows.
     reportClaudeConfigHeal();
+    // Worktree-seamless: register any configured overlay at the git common dir so EVERY
+    // worktree of this repo auto-discovers it (also backfills pre-0.32 single-worktree setups),
+    // and note when we're initializing inside a linked worktree (memory is shared, not separate).
+    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit)) {
+        console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
+    }
+    if (isLinkedWorktree(root)) {
+        console.log(`  ✓ linked worktree — sharing the repo's hooks + memory (no separate setup needed)`);
+    }
     store.close();
     console.log("\nNext: make a commit (the hook captures a decision), then ask your coding assistant \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
@@ -344,6 +354,14 @@ program
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
     writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
+    // Also register the overlay at the SHARED git common dir, so EVERY worktree of this repo
+    // (current + future, any branch) auto-discovers the same memory with zero per-worktree
+    // setup. Stored ABSOLUTE — a linked worktree resolves relative paths from its OWN root, so
+    // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
+    let worktreeNote = "";
+    if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit)) {
+        worktreeNote = `  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n`;
+    }
     // 4) route post-commit synthesis to the overlay (local hook, never committed)
     let hookNote = "";
     if (opts.hook && isGitRepo(root)) {
@@ -379,11 +397,53 @@ program
     }
     console.log(`✓ private overlay enabled → ${hunchDir}\n` +
         `  ✓ recorded in .hunch/local.json (gitignored) — auto-detected, no env var or shell-profile edit\n` +
+        worktreeNote +
         hookNote +
         migrateNote +
         `  record sensitive items with private:true (hunch_record_decision / hunch_record_correction)\n` +
         `  override per-shell with HUNCH_PRIVATE_DIR; CI / public PR comments stay public-only.`);
 });
+// ---- worktree (one-command worktree wired into Hunch) ----------------------
+program
+    .command("worktree <path>")
+    .description("Create a git worktree already wired into Hunch — it shares this repo's memory (the private overlay), with zero per-worktree setup.")
+    .option("-b, --branch <name>", "create the worktree on a NEW branch")
+    .option("--no-share", "don't register the overlay at the git common dir (the worktree won't see private memory)")
+    .action((path, opts) => {
+    const root = findRoot();
+    if (!isGitRepo(root))
+        return fail("`hunch worktree` needs a git repo");
+    const dest = resolve(root, path);
+    if (existsSync(dest))
+        return fail(`path already exists: ${dest}`);
+    // 1) create the worktree (on a new branch if asked, else a checkout of HEAD)
+    const r = spawnSync("git", ["-C", root, "worktree", "add", ...(opts.branch ? ["-b", opts.branch] : []), dest], { stdio: "inherit" });
+    if (r.status !== 0)
+        return fail("git worktree add failed");
+    // 2) register the overlay at the SHARED git common dir so the new worktree (and every
+    //    other) auto-discovers the same memory — also backfills pre-0.32 single-worktree setups.
+    const store = new HunchStore(hunchPaths(root));
+    const overlay = store.privateDir;
+    const autoCommit = store.privateAutoCommit;
+    store.close();
+    let shareNote;
+    if (!opts.share) {
+        shareNote = `  · --no-share — the worktree will NOT see private memory`;
+    }
+    else if (overlay && ensureSharedOverlayPointer(root, overlay, autoCommit)) {
+        shareNote = `  ✓ memory shared via the git common dir — this worktree sees the same decisions / bugs / constraints`;
+    }
+    else if (overlay) {
+        shareNote = `  · could not register the shared overlay pointer (no git common dir?)`;
+    }
+    else {
+        shareNote = `  · no private overlay configured — run \`hunch private\` to share memory across worktrees`;
+    }
+    console.log(`✓ worktree created → ${dest}${opts.branch ? ` (new branch ${opts.branch})` : ""}\n` +
+        `${shareNote}\n` +
+        `  hooks + MCP server are shared (worktree-aware) — open your assistant in the new worktree to start.\n` +
+        `  (needs \`hunch\` installed globally; a worktree has no node_modules of its own)`);
+});
 // ---- query ----------------------------------------------------------------
 program
     .command("query")
@@ -1467,6 +1527,16 @@ program
     console.log(store.privateDir
         ? `private:    on → ${store.privateDir} (local overlay — unioned into queries; never committed or posted publicly)`
         : dim(`private:    off — run \`hunch private\` to keep sensitive memory in a separate repo (or set HUNCH_PRIVATE_DIR)`));
+    // Worktree posture: linked worktrees share ONE memory via the git common dir. Only
+    // surfaced in a linked worktree (no noise in a normal single checkout), so a
+    // "memory missing here" symptom has an obvious cause + fix.
+    if (isLinkedWorktree(root)) {
+        const common = gitCommonDir(root);
+        const sharedPtr = !!common && existsSync(join(common, "hunch", "local.json"));
+        console.log(store.privateDir
+            ? `worktree:   linked — sharing the repo's memory${sharedPtr ? " via the git common dir" : ""}`
+            : dim(`worktree:   linked, but no overlay resolved here — run \`hunch private\` once (any worktree) so all worktrees share it`));
+    }
     // Semantic search is opt-in and local. Report availability + coverage without
     // loading the model (selectEmbedder only probes; embeddingStats just counts rows).
     const emb = await selectEmbedder();

package/dist/extractors/git.js

@@ -1,6 +1,8 @@
 /** Deterministic git introspection for the extractor + learning loop.
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
+import { isAbsolute, resolve, join } from "node:path";
+import { mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
@@ -25,16 +27,50 @@ export function isGitRepo(cwd) {
  *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
  *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops. */
 export function commitAndPushHunch(hunchDir, message) {
-    const env = { ...process.env, HUNCH_SYNC: "1" };
-    const run = (args) => {
+    // Serialize across worktrees: several worktrees auto-committing the SAME overlay repo
+    // at once would race git's index.lock. An atomic-mkdir lock lets one proceed; the others
+    // skip — safe because each record is already written to disk, so `git add .` here sweeps
+    // up anything a skipped run left pending (eventually-consistent, never lost).
+    const lock = join(hunchDir, ".hunch-commit.lock");
+    if (!acquireCommitLock(lock))
+        return;
+    try {
+        const env = { ...process.env, HUNCH_SYNC: "1" };
+        const run = (args) => {
+            try {
+                execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+            }
+            catch { /* best-effort: nothing staged / not a repo / offline */ }
+        };
+        run(["add", "--", "."]);
+        run(["commit", "-m", message]);
+        run(["push"]);
+    }
+    finally {
         try {
-            execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+            rmSync(lock, { recursive: true, force: true });
         }
-        catch { /* best-effort: nothing staged / not a repo / offline */ }
-    };
-    run(["add", "--", "."]);
-    run(["commit", "-m", message]);
-    run(["push"]);
+        catch { /* released best-effort */ }
+    }
+}
+/** Atomic mkdir lock; reclaims a stale lock (a crashed holder) older than 60s. Returns
+ *  false when another live holder owns it — the caller skips rather than blocks. */
+function acquireCommitLock(lock) {
+    try {
+        mkdirSync(lock);
+        return true;
+    }
+    catch {
+        try {
+            if (Date.now() - statSync(lock).mtimeMs > 60_000) {
+                rmSync(lock, { recursive: true, force: true });
+                mkdirSync(lock);
+                return true;
+            }
+        }
+        catch { /* lock vanished or races another reclaimer — treat as held */ }
+        return false;
+    }
 }
 export function headSha(cwd) {
     return gitSafe(["rev-parse", "HEAD"], cwd);
@@ -65,6 +101,39 @@ export function hooksDir(cwd) {
 export function gitDir(cwd) {
     return gitSafe(["rev-parse", "--git-dir"], cwd) || ".git";
 }
+/** The SHARED git dir for the repo — identical across ALL linked worktrees (unlike
+ *  `gitDir`, which is per-worktree). Absolute, so callers can anchor worktree-shared
+ *  state (the private-overlay pointer) at one stable place. "" when not a git repo. */
+export function gitCommonDir(cwd) {
+    const p = gitSafe(["rev-parse", "--git-common-dir"], cwd);
+    if (!p)
+        return "";
+    return isAbsolute(p) ? p : resolve(cwd, p);
+}
+/** True when `cwd` is inside a LINKED worktree (not the main checkout): its own git
+ *  dir differs from the shared common dir. Used by `hunch doctor` and setup messaging. */
+export function isLinkedWorktree(cwd) {
+    const common = gitCommonDir(cwd);
+    const own = gitSafe(["rev-parse", "--absolute-git-dir"], cwd);
+    if (!common || !own)
+        return false;
+    // realpath BOTH before comparing: `--absolute-git-dir` is symlink-resolved while
+    // gitCommonDir is not, so on macOS the main checkout would otherwise mismatch on
+    // /var vs /private/var and falsely read as "linked".
+    const norm = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    return norm(own) !== norm(common);
+}
+/** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
+ *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
+export function currentBranch(cwd) {
+    const b = gitSafe(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    return b === "HEAD" ? "" : b; // detached HEAD reports "HEAD" — treat as no branch
+}
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export function commitFiles(sha, cwd) {

package/dist/integrations/worktree.js

@@ -0,0 +1,33 @@
+/**
+ * Worktree wiring — make a repo's private-overlay memory seamless across every git
+ * worktree (v0.32+). A worktree's gitignored `.hunch/local.json` pointer doesn't exist
+ * in a fresh checkout, so we register the overlay at the SHARED git common dir
+ * (`git rev-parse --git-common-dir`), which every linked worktree resolves identically.
+ */
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { gitCommonDir } from "../extractors/git.js";
+import { writeFileAtomic } from "../core/io.js";
+/** Register the resolved private overlay at the shared git common dir, so every worktree
+ *  of this repo auto-discovers the same memory. Idempotent (writes only when missing or
+ *  changed). Stored ABSOLUTE — a worktree resolves relative paths from its OWN root.
+ *  Returns true once the shared pointer is in place (memory is worktree-shared), false when
+ *  there's no overlay configured or no git common dir. Reused by `init`/`worktree`/`private`. */
+export function ensureSharedOverlayPointer(root, overlayDir, autoCommit) {
+    const common = overlayDir ? gitCommonDir(root) : "";
+    if (!common || !overlayDir)
+        return false;
+    const file = join(common, "hunch", "local.json");
+    const want = JSON.stringify({ privateDir: resolve(overlayDir), autoCommit }, null, 2) + "\n";
+    try {
+        if (!(existsSync(file) && readFileSync(file, "utf8") === want)) {
+            mkdirSync(join(common, "hunch"), { recursive: true });
+            writeFileAtomic(file, want);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/store/hunchStore.js

@@ -18,6 +18,7 @@ import { openDb } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
+import { gitCommonDir } from "../extractors/git.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { edgeId } from "../core/ids.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
@@ -57,17 +58,33 @@ export class HunchStore {
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
      *  never committed). Tolerant: returns {} on missing/invalid so reads never crash. */
     localConfig() {
-        try {
-            const f = join(this.paths.hunch, "local.json");
-            if (!existsSync(f))
+        const read = (file) => {
+            try {
+                if (!existsSync(file))
+                    return {};
+                const v = JSON.parse(readFileSync(file, "utf8"));
+                const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
+                return { privateDir, autoCommit: v.autoCommit === true };
+            }
+            catch {
                 return {};
-            const v = JSON.parse(readFileSync(f, "utf8"));
-            const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
-            return { privateDir, autoCommit: v.autoCommit === true };
-        }
-        catch {
-            return {};
+            }
+        };
+        // Per-worktree pointer first (explicit / back-compat). If it names no overlay, fall back to
+        // the SHARED pointer in the git common dir — identical across ALL worktrees, so a freshly
+        // added worktree (whose gitignored .hunch/local.json doesn't exist yet) still auto-discovers
+        // the same memory. The git lookup runs ONLY when the cheap per-worktree read is empty, keeping
+        // it off the hot path for already-configured checkouts.
+        const perWorktree = read(join(this.paths.hunch, "local.json"));
+        if (perWorktree.privateDir)
+            return perWorktree;
+        const common = gitCommonDir(this.paths.root);
+        if (common) {
+            const shared = read(join(common, "hunch", "local.json"));
+            if (shared.privateDir)
+                return shared;
         }
+        return perWorktree;
     }
     /** Merged read: public ∪ private overlay (private wins on id collision). Every
      *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-

package/dist/synthesis/synthesize.js

@@ -1,4 +1,4 @@
-import { commitMeta, commitDiff, headSha } from "../extractors/git.js";
+import { commitMeta, commitDiff, headSha, currentBranch } from "../extractors/git.js";
 import { analyzeDiff } from "../extractors/diff.js";
 import { selectProvider, selectEnsemble, selectVerifier, verifyDecisionSafe, DeterministicProvider } from "./provider.js";
 import { decisionId, bugId, constraintId } from "../core/ids.js";
@@ -101,6 +101,11 @@ export async function syncCommit(store, root, sha, opts = {}) {
     if (draft.pruned)
         synthBits.push(`pruned=${draft.pruned}`); // the Critic's visible value
     const synthEvidence = `synth:${synthBits.join(" ")}`;
+    // Tag the capturing branch so branch-scoped work stays FILTERABLE in the one shared store
+    // (every worktree/branch writes to the same overlay — this keeps "what was decided on
+    // feature-x?" answerable without fragmenting memory per branch). Empty in detached HEAD.
+    const branch = currentBranch(root);
+    const branchTag = branch ? [`branch:${branch}`] : [];
     const components = store.json.loadAll("components");
     const relatedComponents = components
         .filter((c) => codeFiles.some((f) => c.paths.some((g) => pathMatchesGlob(f, g))))
@@ -144,7 +149,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
         provenance: {
             source: draft.source,
             confidence: draft.confidence,
-            evidence: [`commit:${meta.shortSha}`, synthEvidence, ...codeFiles.slice(0, 8)],
+            evidence: [`commit:${meta.shortSha}`, synthEvidence, ...branchTag, ...codeFiles.slice(0, 8)],
             last_verified: new Date().toISOString(), // when the Hunch last re-derived this
         },
         date: meta.date, // the commit date

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "license": "Apache-2.0",
   "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.",