@davesheffer/hunch 1.31.1 → 1.32.1

package/dist/integrations/madrExport.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MADR export (the MADR bridge, export half — roadmap's "compiler" projection).
+ *
+ * Renders the PUBLIC decision graph as a regenerated MADR 3.x corpus: one
+ * NNNN-slug.md per decision, superseded links derived from superseded_by /
+ * valid_to, rejected alternatives under Considered Options. The projection is a
+ * DISPOSABLE build artifact — the graph stays the source of truth, numbers are
+ * assigned per export (date order), and every emitted file carries a generated
+ * marker. The writer only ever overwrites files bearing that marker: a
+ * hand-written ADR corpus in the target directory is untouchable (refused with
+ * a warning), so `hunch import-adr` + `hunch export-adr` can share a repo
+ * without the export eating its own import source.
+ *
+ * Privacy boundary: rendering takes an explicit PUBLIC-only decision list —
+ * callers must pass store.json.loadAll("decisions"), never the overlay union.
+ */
+import type { Decision } from "../core/types.js";
+export declare const MADR_EXPORT_MARKER = "<!-- hunch:generated madr-export \u2014 regenerated by `hunch export-adr`; edits will be overwritten -->";
+export interface MadrFile {
+    /** file name only, NNNN-slug.md */
+    name: string;
+    text: string;
+    decisionId: string;
+}
+export interface MadrExportResult {
+    files: MadrFile[];
+    /** the one-line Backstage catalog-info annotation for this corpus */
+    backstageAnnotation: string;
+}
+/** Render one decision as a MADR 3.x document. Deterministic: content depends
+ *  only on the decision record and the corpus's name map. */
+export declare function renderMadr(d: Decision, nameOf: Map<string, string>): string;
+/** Project a PUBLIC decision list into a MADR corpus. Numbering is date order
+ *  (valid_from, then date, then id for determinism) and assigned per export —
+ *  the projection is disposable, links inside it are internally consistent. */
+export declare function exportMadrCorpus(decisions: readonly Decision[], dirForAnnotation: string): MadrExportResult;
+/** True when an existing file may be overwritten by the export: only our own
+ *  generated output ever qualifies. */
+export declare function isRegenerableMadr(existingText: string): boolean;

package/dist/integrations/madrManifest.d.ts

@@ -0,0 +1,69 @@
+import type { Decision } from "../core/types.js";
+import type { DriftFinding } from "../core/drift.js";
+export interface MadrManifest {
+    version: 1;
+    /** repo-relative POSIX dir the corpus was exported to */
+    dir: string;
+    /** keyed by file name (NNNN-slug.md) — the export assigns numbers per run */
+    files: Record<string, {
+        decision: string;
+        hash: string;
+        bytes: string;
+        generated: string;
+    }>;
+}
+export declare function madrManifestPath(root: string): string;
+export declare function readMadrManifest(root: string): MadrManifest | null;
+export declare function writeMadrManifest(root: string, manifest: MadrManifest): void;
+/** The projected-content hash for one file. Content, not mtime: a re-export that
+ *  changes nothing must not read as drift. */
+export declare const madrContentHash: (text: string) => string;
+/**
+ * Build the manifest for a corpus that was just written.
+ *
+ * `written` carries the bytes actually placed on disk, which may differ from the
+ * rendered text when a file was refused (hand-written corpus in the target dir).
+ * Refused files are absent from the manifest, so they are never later reported
+ * as edited — they were never ours.
+ */
+export declare function buildMadrManifest(dir: string, entries: ReadonlyArray<{
+    name: string;
+    text: string;
+    decisionId: string;
+}>, generatedAt: string): MadrManifest;
+/**
+ * Drift for the MADR projection. Fires ONLY where a manifest exists — a repo that
+ * never ran `hunch export-adr` sees zero noise, matching the wiki's rule.
+ *
+ * Takes the PUBLIC decision list, never the overlay union: the projection is a
+ * committable artifact, so its freshness must be computed from exactly the
+ * records that are allowed to reach it. Passing the union here would leak the
+ * existence of overlay decisions into a public drift report.
+ */
+export declare function computeMadrDrift(publicDecisions: readonly Decision[], root: string): DriftFinding[];
+/**
+ * Keep an adopted corpus fresh automatically.
+ *
+ * Called from the post-commit sync path (and from any writer that changes the
+ * public graph out of band, such as the memory service's HTTP write path), so a
+ * user who ran `hunch export-adr` once never has to run it again — the
+ * projection tracks the graph the way the SQLite index does.
+ *
+ * Deliberately narrow:
+ *   - No manifest → no-op. Adoption stays an explicit act.
+ *   - Refuses to touch a file that was hand-edited, because silently discarding
+ *     someone's edit is worse than a stale file; `madr-edited` drift reports it
+ *     and the human decides.
+ *   - Removes generated files the new numbering dropped, so the corpus stays
+ *     internally consistent, but never removes a file it did not generate.
+ *
+ * Returns what changed so callers can log it; throws nothing the caller must
+ * handle — a projection refresh must never take down a commit or an HTTP write.
+ */
+export interface MadrRefreshResult {
+    dir: string;
+    written: number;
+    removed: number;
+    skippedEdited: string[];
+}
+export declare function refreshMadrCorpus(publicDecisions: readonly Decision[], root: string, now: string): MadrRefreshResult | null;

package/dist/integrations/mergeDriver.d.ts

@@ -0,0 +1,3 @@
+export declare function installMergeDriver(root: string, invShell: string): {
+    action: string;
+};

package/dist/integrations/mergeDriver.js

@@ -1,17 +1,30 @@
 /**
- * Wires up the structured `.hunch/` git merge driver (store/merge.ts):
- *   - `.gitattributes` (committed) routes the .hunch JSON files through merge=hunch,
- *   - local git config maps merge=hunch to `hunch merge-driver …` (per clone, so
- *     each teammate runs `hunch init` to register it).
+ * Wires up two independent git merge drivers:
+ *   - `merge=hunch` — the structured `.hunch/` JSON driver (store/merge.ts):
+ *     resolves concurrent edits by record id.
+ *   - `merge=hunch-grounding` — the generated grounding docs (core/groundingMerge.ts):
+ *     auto-resolves a hard conflict confined to the record-counts sentence,
+ *     leaving any other conflict untouched (dec_ba5b0dfa22).
+ * Both routes live in `.gitattributes` (committed, travels with the repo);
+ * both drivers are registered in LOCAL git config only (per-clone, since each
+ * references this machine's node + cli path — teammates re-run `hunch init`).
  */
 import { execFileSync } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { assertSafeTopLevelConfigFile } from "./gitignore.js";
+import { GROUNDING_DOC_PATHS } from "./providers.js";
 // Route the .hunch JSON records through the structured driver — but NOT the
 // manifest (an id-less `{schema_version}` object the driver can't merge by id; a
 // normal text merge with conflict markers is the right behavior for it).
-const ATTR_LINES = [".hunch/**/*.json merge=hunch", ".hunch/manifest.json merge=text"];
+//
+// The five generated grounding docs get the OTHER driver — narrower in scope
+// (it only ever touches a hard conflict confined to the counts sentence).
+const ATTR_LINES = [
+    ".hunch/**/*.json merge=hunch",
+    ".hunch/manifest.json merge=text",
+    ...GROUNDING_DOC_PATHS.map((f) => `${f} merge=hunch-grounding`),
+];
 function targetRepositoryEnv() {
     const env = { ...process.env };
     for (const key of [
@@ -43,17 +56,21 @@ export function installMergeDriver(root, invShell) {
         assertSafeTopLevelConfigFile(root, ".gitattributes");
         writeFileAtomic(attrPath, text);
     }
-    // 2. Local git config — the driver definition is per-clone (it references this
-    //    machine's node + cli path), so it is NOT committed; teammates re-run init.
+    // 2. Local git config — the driver definitions are per-clone (they reference
+    //    this machine's node + cli path), so they are NOT committed; teammates
+    //    re-run init.
     const driver = `${invShell} merge-driver "%O" "%A" "%B" "%P"`;
+    const groundingDriver = `${invShell} merge-driver-grounding "%O" "%A" "%B" "%P"`;
     const env = targetRepositoryEnv();
     try {
         execFileSync("git", ["config", "merge.hunch.name", "hunch structured JSON merge"], { cwd: root, env });
         execFileSync("git", ["config", "merge.hunch.driver", driver], { cwd: root, env });
+        execFileSync("git", ["config", "merge.hunch-grounding.name", "hunch grounding-counts merge"], { cwd: root, env });
+        execFileSync("git", ["config", "merge.hunch-grounding.driver", groundingDriver], { cwd: root, env });
     }
     catch {
         return { action: `${attrAction} .gitattributes — but \`git config\` failed (not a git repo?)` };
     }
-    return { action: `${attrAction} .gitattributes + registered merge.hunch driver` };
+    return { action: `${attrAction} .gitattributes + registered merge.hunch + merge.hunch-grounding drivers` };
 }
 //# sourceMappingURL=mergeDriver.js.map

package/dist/integrations/probe.d.ts

@@ -0,0 +1,4 @@
+import { type Harness, type IntegrationHealth } from "./health.js";
+/** Opt-in: starts a fresh configured MCP process, never claims the current
+ * harness connection or hook delivery has been tested. No model is invoked. */
+export declare function probeIntegration(root: string, harness: Harness, report: IntegrationHealth, timeoutMs?: number): Promise<void>;

package/dist/integrations/providers.d.ts

@@ -0,0 +1,103 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import type { Invocation } from "./scaffold.js";
+/** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
+export declare function writeCursorMcp(root: string, inv: Invocation): string;
+/** VS Code (Copilot agent mode): .vscode/mcp.json — root key is `servers`, and
+ *  each stdio entry carries an explicit `type: "stdio"` (VS Code's schema). */
+export declare function writeVscodeMcp(root: string, inv: Invocation): string;
+/** Google Antigravity's global MCP config moved between releases. Resolve
+ * adaptively: an existing config wins, else an existing parent dir, else null
+ * (Antigravity not installed — we never create a global config for an absent
+ * tool). The current project-local config is handled separately below. `home`
+ * is injectable for tests so we never touch the real ~/.gemini. */
+export declare function antigravityMcpFile(home?: string): string | null;
+/** Antigravity: merge the hunch stdio server into the global mcp_config.json — same
+ *  `mcpServers` { command, args } shape as Cursor/Claude (stdio; `serverUrl` is only for
+ *  HTTP servers). Returns null when Antigravity isn't detected. Grounding needs nothing
+ *  extra: Antigravity reads the project-root AGENTS.md Hunch already writes. */
+export declare function writeAntigravityMcp(inv: Invocation, home?: string): string | null;
+/** Current Antigravity IDE/CLI project config. Unlike a global config this is
+ * committed with the repository, so every clone gets the same private/local
+ * Hunch server without touching a user's home directory. */
+export declare function writeAntigravityWorkspaceMcp(root: string, inv: Invocation): string;
+/** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
+ *  a marker-delimited block; any other TOML the user has is preserved. Paths use
+ *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */
+export declare function writeCodexConfig(root: string, inv: Invocation): string;
+/** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
+ *  set of assistants read it). Marker-delimited so user prose is preserved. */
+export declare function writeAgentsMd(root: string, store: HunchStore): string;
+/** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
+export declare function writeCopilotInstructions(root: string, store: HunchStore): string;
+/** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
+ *  grounding in context for every request. Fully managed by Hunch (overwritten). */
+export declare function writeCursorRule(root: string, store: HunchStore): string;
+/** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
+ *  Cursor. Repo-local (committed, shared via git) to match Hunch's other configs,
+ *  rather than the global ~/.codeium/windsurf path. Merges; refuses to clobber. */
+export declare function writeWindsurfMcp(root: string, inv: Invocation): string;
+/** Current Windsurf also discovers a user config at ~/.codeium/windsurf. Only
+ * touch it when the tool is already installed/configured; Hunch never creates a
+ * global configuration for an application the user does not have. */
+export declare function windsurfMcpFile(home?: string): string | null;
+export declare function writeWindsurfGlobalMcp(inv: Invocation, home?: string): string | null;
+/** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
+ *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
+export declare function writeWindsurfRule(root: string, store: HunchStore): string;
+/** Cursor's hook API is beta, but its project-level config accepts this standard
+ * event map. Context delivery is opportunistic; the always-on rule and MCP
+ * registration remain the durable grounding path if a Cursor build suppresses
+ * a hook's agent_message. */
+export declare function writeCursorHooks(root: string, inv: Invocation): string;
+/** VS Code's native workspace hook location. It supports all lifecycle events
+ * Hunch needs and uses the same stdout contract as Claude Code, with different
+ * camelCase tool fields normalized in core/agenthook.ts. */
+export declare function writeVscodeHooks(root: string, inv: Invocation): string;
+/** Windsurf's documented workspace hooks. It only supports deterministic
+ * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
+ * reserves the hook for strict edit protection and pipeline observation. */
+export declare function writeWindsurfHooks(root: string, inv: Invocation): string;
+/** Antigravity keeps hook groups at the top level (not under `hooks`). Hunch
+ * owns only the `hunch` group and replaces its own old entries idempotently. */
+export declare function writeAntigravityHooks(root: string, inv: Invocation): string;
+/** Rewrite the auto-maintained Hunch section in EVERY assistant grounding doc
+ *  (CLAUDE.md, AGENTS.md, Copilot instructions, Cursor + Windsurf rules) from the
+ *  current store — without touching the MCP/provider config files. `hunch private
+ *  --migrate` calls this AFTER emptying the public store so the committed public
+ *  docs reflect that no engineering memory is published here (renderHunchSection
+ *  reads the public store only, so private records never leak into them). */
+export declare function regenerateGrounding(root: string, store: HunchStore): string[];
+/** The five grounding docs, repo-relative (POSIX separators, as git prints them). */
+export declare const GROUNDING_DOC_PATHS: readonly string[];
+/** Self-heal: refresh the Hunch section in each grounding doc that ALREADY exists,
+ *  and report which ones actually changed. Unlike regenerateGrounding it NEVER creates
+ *  a file (so it can't scaffold grounding into a project that opted out of an
+ *  assistant). Run by `hunch index` and non-hook `hunch sync` so a project silently
+ *  picks up generator fixes (e.g. corrected MCP tool param names) and fresh record
+ *  counts on the next refresh — no manual `hunch init`. */
+export declare function refreshExistingGrounding(root: string, store: HunchStore): string[];
+/** Capture-commit refresh: rewrite grounding docs that are git-clean OR whose only
+ *  divergence from HEAD is generated content, and return the absolute paths to fold
+ *  into the memory commit (commitAndPushHunch alsoStage). This keeps committed record
+ *  counts permanently true — every capture used to bump the count and re-stale the
+ *  committed docs, failing the release gate's clean-tree check on the next CI index
+ *  (the refresh-counts treadmill). The generated-dirt branch closes the second half
+ *  (fnd_b269d5c422): once a doc went stale-dirty, the clean-only rule skipped it on
+ *  every later flush FOREVER, and each release needed a manual chore commit. A doc
+ *  whose USER PROSE differs from HEAD is still left completely untouched. */
+export declare function refreshCommittableGrounding(root: string, store: HunchStore): string[];
+export interface ProviderScaffold {
+    assistant: string;
+    files: string[];
+    /** Set when this assistant was skipped (e.g. an unparseable existing config we
+     *  refused to clobber) — surfaced as a warning, not a fatal init failure. */
+    error?: string;
+}
+/** Scaffold MCP config + grounding for all supported assistants. Returns a
+ *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
+ *  a writer that refuses to clobber a malformed file degrades to a warning rather
+ *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
+export declare function scaffoldProviders(root: string, inv: Invocation, store: HunchStore, options?: {
+    agentHooks?: boolean;
+    home?: string;
+}): ProviderScaffold[];

package/dist/integrations/scaffold.d.ts

@@ -0,0 +1,29 @@
+export interface Invocation {
+    command: string;
+    args: string[];
+}
+/** Merge a `hunch` server entry into .mcp.json, preserving other servers.
+ *  A non-empty file we cannot parse THROWS instead of being silently replaced
+ *  (con_8460b6770f — it may hold the user's other MCP servers); the caller
+ *  degrades that to a warning. */
+export declare function writeMcpJson(root: string, inv: Invocation): string;
+export interface ClaudeHookInstall {
+    path: string;
+    action: "created" | "updated" | "unchanged";
+}
+/**
+ * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent
+ * is grounded in Hunch automatically (not by remembering to call the tools):
+ *   - PreToolUse (Edit|Write|MultiEdit) → inject the relevant Hunch slice before
+ *     an edit, and (at strict firmness) deny edits that hit a blocking invariant.
+ *   - UserPromptSubmit → remind the agent to consult Hunch.
+ * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
+ * at run time — so changing firmness needs no settings.json edit. We own only our
+ * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * non-empty file we cannot parse THROWS rather than clobbering the user's config.
+ */
+export declare function installClaudeHooks(root: string, hookCmd: string): ClaudeHookInstall;
+export declare function writeSlashCommands(root: string): {
+    written: string[];
+    skipped: string[];
+};

package/dist/integrations/sync.d.ts

@@ -0,0 +1,30 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type HunchRemoteContract, type GitMemoryObserver } from "../extractors/git.js";
+/** Bind one command/server Store instance to the graph epoch that admitted it.
+ * Every later flush from that instance reuses the same verifying contract. */
+export declare function pinSharedRemote(store: HunchStore, remote: HunchRemoteContract): void;
+/** Return the route admitted for this Store instance. Command paths that flush
+ * directly (rather than through flushCapture) must use this accessor too, or a
+ * coherent team.json/origin rewrite could switch graphs mid-command. */
+export declare function sharedRemoteFor(store: HunchStore): HunchRemoteContract | undefined;
+export type MemoryHome = "public" | "private";
+/** Flush one exact artifact home. Constitution repositories can explicitly
+ * choose public even in unified mode, so this must not infer routing through
+ * captureHome(isPrivate). The caller supplies the repository's actual home. */
+export declare function flushMemoryHome(store: HunchStore, publicHunchDir: string, home: MemoryHome, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | null;
+/** One completion flush per touched home. A mixed ingest/bootstrap can write
+ * both homes; unchanged homes are cheap no-ops after the memory-only stage
+ * check, while each real home becomes durable exactly once. */
+export declare function flushMemoryHomes(store: HunchStore, publicHunchDir: string, homes: Iterable<MemoryHome>, message: string, remoteOverride?: HunchRemoteContract): Partial<Record<MemoryHome, "pushed" | "committed" | null>>;
+/** Auto-commit + push the overlay after a private write, when auto-commit is on. No-op
+ *  otherwise (manual `hunch private --sync` still works). Never throws. */
+export declare function flushPrivate(store: HunchStore, message: string): void;
+/** Auto-commit the store a capture landed in. Returns what ACTUALLY happened so callers
+ *  never report a commit that was skipped: "pushed" (overlay committed + pushed),
+ *  "committed" (commit created but not pushed — public .hunch/ rides the next push; an
+ *  overlay commit whose merge/push failed retries on the next flush), or null (auto-commit
+ *  off, no overlay for a private record, or the commit was skipped — lock held, safety
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up). */
+export declare function flushCapture(store: HunchStore, publicHunchDir: string, isPrivate: boolean, message: string, 
+/** Long-lived callers can pin the route snapshot that admitted the write. */
+remoteOverride?: HunchRemoteContract, observe?: GitMemoryObserver): "pushed" | "committed" | null;

package/dist/integrations/sync.js

@@ -73,13 +73,14 @@ export function flushPrivate(store, message) {
  *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up). */
 export function flushCapture(store, publicHunchDir, isPrivate, message, 
 /** Long-lived callers can pin the route snapshot that admitted the write. */
-remoteOverride) {
+remoteOverride, observe) {
     // Follow the same routing as HunchStore.captureHome: unified ("shared") mode homes
     // EVERY capture in the overlay, so the flush must go there too — one source of truth.
     if (store.captureHome(isPrivate) === "private") {
         if (store.privateAutoCommit && store.privateDir) {
             return commitAndPushHunch(store.privateDir, message, {
                 push: true,
+                observe,
                 protectedRepoRoot: store.publicRoot,
                 remote: remoteOverride ?? sharedRemoteFor(store),
             });
@@ -92,6 +93,6 @@ remoteOverride) {
     // them into the SAME memory commit — otherwise every capture re-stales the committed
     // counts and the release gate's clean-tree check fails on the next CI index.
     const grounding = refreshCommittableGrounding(dirname(publicHunchDir), store);
-    return commitAndPushHunch(publicHunchDir, message, { push: false, alsoStage: grounding });
+    return commitAndPushHunch(publicHunchDir, message, { push: false, alsoStage: grounding, observe });
 }
 //# sourceMappingURL=sync.js.map

package/dist/integrations/team.d.ts

@@ -0,0 +1,70 @@
+import { type HunchRemoteContract } from "../extractors/git.js";
+export interface TeamConfig {
+    shared_repo: string;
+    /** Canonical remote branch for the one shared graph. Legacy files omit it;
+     * route proof then derives the sole existing/upstream branch from the clone. */
+    shared_ref?: string;
+}
+export declare const DEFAULT_TEAM_REF = "refs/heads/main";
+export declare function safeTeamRef(value: string): string | null;
+export declare function teamSharedRef(team: TeamConfig): string;
+/** SECURITY GATE for team.json's URL. team.json is COMMITTED — in a freshly cloned
+ *  (possibly untrusted) repo it is attacker-controlled, and ensureTeamOverlay auto-clones
+ *  it on MCP server start. Without this gate a value like `--upload-pack=…` (argument
+ *  smuggling) or `ext::sh -c …` (git's ext transport) is remote code execution from
+ *  merely opening a repo. Allow only credential-free https://, ssh://, git://,
+ *  scp-style git@host:path, and never anything that could parse as a Git flag. */
+export declare function safeGitUrl(url: string): string | null;
+/** The committed team pointer, or null. Tolerant — an invalid file reads as absent, and
+ *  a URL that fails the safety gate reads as absent too (never propagated to a consumer). */
+export declare function readTeamConfig(root: string): TeamConfig | null;
+/** Publish the team's shared-store URL (atomic; committed with the repo). */
+export declare function writeTeamConfig(root: string, cfg: TeamConfig): void;
+/** Git environment for every shared-route setup operation. Preserve ordinary
+ * credential configuration, but discard inherited repository/object selectors
+ * and executable transport/prompt/template overrides from the caller. */
+export declare function boundedTeamGitEnv(): NodeJS.ProcessEnv;
+/** Prove that the physical overlay reads from and writes to the repository
+ * advertised by the committed team config. Path/mode checks alone are not
+ * enough: an old healthy clone can otherwise report "current" against a stale
+ * origin after team.json changes, silently splitting the team graph.
+ *
+ * Require one exact fetch URL and one exact push URL for origin, plus an origin
+ * upstream/push selector when those branch-level overrides exist. Git's
+ * Applicable local or global URL rewrite rules are rejected, so the exact URLs
+ * captured from local config remain the URLs handed to Git at the network seam. */
+export declare function overlayMatchesTeamRemote(root: string, overlayRoot: string): boolean;
+/** Snapshot the effective URLs after proving the committed pointer, local
+ * transport configuration, and canonical ref all agree. Sync commands receive
+ * this object and re-run `verify` immediately around every network operation. */
+export declare function teamRemoteContract(root: string, overlayRoot: string): HunchRemoteContract | null;
+/** Setup-time form of the same contract, used before team.json is published.
+ * It proves the existing overlay's physical origin/config against the explicit
+ * command arguments so attach/refresh cannot traverse an ambient refspec or
+ * transport override during the setup command itself. */
+export declare function explicitTeamRemoteContract(overlayRoot: string, sharedRepo: string, sharedRepoCwd: string, sharedRef: string): HunchRemoteContract | null;
+/** Undefined means this checkout does not advertise team routing. Once the
+ * committed file exists, failure to prove it returns an always-refusing
+ * contract so a late config change can strand a local commit but can never fall
+ * through to ambient `git push`. */
+export declare function advertisedTeamRemoteContract(root: string, overlayRoot: string): HunchRemoteContract | undefined;
+export type ValidatedTeamClone = {
+    sharedRef: string;
+    empty: boolean;
+};
+/** Clone a shared memory repository without checking out attacker-controlled
+ * paths, validate its exact route/OID/tree/attributes, and only then publish the
+ * fully materialized clone at `destination`. Failure removes both quarantine and
+ * destination so callers cannot accidentally wire a partially validated graph. */
+export declare function cloneValidatedTeamOverlay(sharedRepo: string, sharedRepoCwd: string, destination: string, opts?: {
+    sharedRef?: string;
+    timeoutMs?: number;
+}): ValidatedTeamClone | null;
+/** Auto-wire this checkout to the team's shared store advertised in `.hunch/team.json`:
+ *  clone it to the worktree-stable anchor, and register the gitignored local pointer +
+ *  the git-common-dir pointer (mode "shared", auto-commit on) so every consumer — CLI,
+ *  MCP server, hooks, all worktrees — resolves the same single source of truth.
+ *  No-op (null) when an overlay is already configured, there's no team.json, or the
+ *  clone fails (best-effort: never throws, never blocks startup). Returns the overlay
+ *  hunch dir when wired. */
+export declare function ensureTeamOverlay(root: string): string | null;

package/dist/integrations/worktree.d.ts

@@ -0,0 +1,8 @@
+/** 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.
+ *  Carries the overlay MODE so every worktree routes captures identically (shared =
+ *  unified store, private = split). 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`/`shared`. */
+export declare function ensureSharedOverlayPointer(root: string, overlayDir: string | undefined, autoCommit: boolean, mode?: "private" | "shared"): boolean;

package/dist/mcp/roots.d.ts

@@ -0,0 +1,16 @@
+/** One canonical spelling per directory. `findRoot` only resolve()s, but a
+ *  client's roots/list URI can spell the same repo differently — VS Code sends
+ *  a lowercase drive letter (`c:\…`) while the spawn cwd has `C:\…`, and Git
+ *  for Windows can surface 8.3/short names. Raw string comparison then treats
+ *  ONE repo as different roots: a full re-prepare (new store + reindex) on
+ *  every connect, or a false "multiple roots equally plausible" refusal
+ *  (issue #54). realpathSync.native returns the on-disk spelling for all of
+ *  these; fall back to the input when the path is transiently unreadable. */
+export declare function canonicalRootPath(root: string): string;
+/**
+ * Returns null when several advertised repositories are equally plausible.
+ * The roots protocol exposes a set of URI/name pairs, not an "active root" bit;
+ * choosing the first Hunch store in that case could silently write repo B's
+ * decision into repo A.
+ */
+export declare function resolveActiveRoot(rootUris: readonly string[], fallbackCwd: string): string | null;

package/dist/mcp/server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
+ * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
+ * a write tool (record_decision). Registered with Claude Code via .mcp.json.
+ *
+ * STDIO PROTOCOL RULE: stdout carries JSON-RPC — never console.log here. All
+ * diagnostics go to stderr.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
+export type RootControlledServer = {
+    server: McpServer;
+    getRoot: () => string;
+    setRoot: (next: string) => void;
+    /** True when the root was pinned at launch (`hunch mcp --root`): client roots and per-call
+     *  `cwd` hints are ignored, so a served partition stays the partition whatever workspace
+     *  the client opened. */
+    pinned: boolean;
+    /** Drop a swap parked by `setRoot` while a request was in flight. The roots
+     *  wiring calls this when a LATER resolution is ambiguous, so a stale parked
+     *  swap can never apply after the client stopped unambiguously advertising it. */
+    cancelPendingRoot: () => void;
+};
+export interface RootControlOptions {
+    /** Serve exactly `initialRoot`; never re-home to client roots or `cwd` hints. */
+    pinned?: boolean;
+}
+export declare function buildServerWithRootControl(initialRoot: string, options?: RootControlOptions): RootControlledServer;
+/** Back-compatible server construction for tests and callers that do not need
+ *  to drive roots directly. The server still owns and closes its active store. */
+export declare function buildServer(root: string): McpServer;
+/** Query client roots after initialization and follow later list changes.
+ *  Generation ordering prevents a slow stale roots/list response from winning. */
+export declare function wireClientRoots(control: RootControlledServer, fallback: string): void;
+/** Start the stdio server (called by `hunch mcp`). */
+export declare function startServer(cwd?: string, options?: RootControlOptions): Promise<void>;