@davesheffer/hunch 1.47.0 → 1.47.2

package/dist/core/subagentrole.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Whether a delegated agent can call Hunch's MCP tools. A named role defined in
+ *  `.claude/agents/<type>.md` (project first, then user) with a `tools:` list that
+ *  names no `mcp__hunch` tool and no wildcard cannot: telling it to call
+ *  hunch_why only costs it a failed lookup. Built-in and unknown types inherit
+ *  the parent's tools. */
+export function roleHasHunchTools(root, agentType, home = homedir()) {
+    const type = agentType.trim();
+    if (!type || !/^[\w.-]+$/.test(type))
+        return true;
+    for (const dir of [join(root, ".claude", "agents"), join(home, ".claude", "agents")]) {
+        let text;
+        try {
+            text = readFileSync(join(dir, `${type}.md`), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const front = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+        if (!front)
+            return true;
+        // A block list continues on indented "- x" lines; a flow list runs to its "]".
+        const tools = /^tools:[ \t]*(\[[^\]]*\]?|.*(?:\r?\n[ \t]+-.*)*)/m.exec(front)?.[1];
+        if (tools === undefined || !tools.trim())
+            return true;
+        return /\*|mcp__hunch/.test(tools);
+    }
+    return true;
+}
+//# sourceMappingURL=subagentrole.js.map

package/dist/core/taskRecord.d.ts

@@ -35,7 +35,7 @@ export declare function computeSupersedes(record: TaskRecord, others: readonly T
 export interface PersistedTaskRecord {
     record: TaskRecord;
     home: TaskRecordHome;
-    flushed: "pushed" | "committed" | null;
+    flushed: "pushed" | "committed" | "held" | null;
     /** False when the same report revision was already in the graph. */
     changed: boolean;
 }

package/dist/core/taskRecord.js

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { flushCapture } from "../integrations/sync.js";
 import { hunchPaths } from "./paths.js";
 import { episodeTasks, isEmptyTaskReport, readTaskReport, reportHash, sessionsOverlap } from "./taskReport.js";
-import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { currentSource } from "./taskReportEvidence.js";
 import { ENTITY_KINDS, TaskRecordSchema } from "./types.js";
 import { refreshRankEval } from "./taskRankingMode.js";
 import { gitTouchedFiles } from "./taskTouched.js";
@@ -172,7 +172,7 @@ export function computeSupersedes(record, others, limit = 20) {
 export function persistTaskRecord(root, store, taskId, options = {}) {
     if (!taskRecordsEnabled(root))
         return null;
-    const snapshot = reportSourceSnapshot(root).hash;
+    const snapshot = currentSource(root);
     const own = readTaskReport(root, taskId, snapshot);
     if (own.task.state === "open")
         return null;

package/dist/core/taskReport.d.ts

@@ -30,6 +30,7 @@ export declare const ReportCheckSchema: z.ZodObject<{
     snapshot_limitations: z.ZodArray<z.ZodString>;
     timed_out: z.ZodBoolean;
     cancelled: z.ZodOptional<z.ZodBoolean>;
+    work_root: z.ZodOptional<z.ZodString>;
     source: z.ZodLiteral<"local-command-runner">;
 }, z.core.$strict>;
 export type ReportCheck = z.infer<typeof ReportCheckSchema>;
@@ -321,8 +322,8 @@ export interface TaskSummary {
 }
 /** One bounded summary per recent task for status lines and host views; the
  * card and evidence view remain the authoritative renderings. */
-export declare function summarizeTaskReport(root: string, taskId: string, currentSnapshot?: string | null): TaskSummary;
-export declare function listTaskSummaries(root: string, limit?: number, currentSnapshot?: string | null): TaskSummary[];
+export declare function summarizeTaskReport(root: string, taskId: string, currentSnapshot?: CurrentSnapshot): TaskSummary;
+export declare function listTaskSummaries(root: string, limit?: number, currentSnapshot?: CurrentSnapshot): TaskSummary[];
 /** One line for a terminal status line. Empty string when nothing was observed
  * for the task, so a bare prompt shows no Hunch noise at all. */
 export declare function renderTaskStatusLine(summary: TaskSummary | null): string;
@@ -348,5 +349,9 @@ export declare function reportActivity(root: string): string;
 export declare function forgetReportTask(root: string, taskId: string): void;
 export declare function pruneReportHistory(root: string, olderThanDays?: number): number;
 export declare function reportPresentationEnabled(root: string): boolean;
-export declare function readTaskReport(root: string, taskId: string, currentSnapshot?: string | null): TaskReport;
+/** What a reader compares evidence snapshots against: the report root's current source
+ *  hash, or a resolver that also hashes another worktree a check ran in. A plain hash
+ *  never vouches for a check that ran elsewhere. */
+export type CurrentSnapshot = string | null | ((dir?: string) => string | null);
+export declare function readTaskReport(root: string, taskId: string, currentSnapshot?: CurrentSnapshot): TaskReport;
 export {};

package/dist/core/taskReport.js

@@ -43,6 +43,9 @@ export const ReportCheckSchema = z.object({
     snapshot_limitations: z.array(z.string().max(300)).max(16),
     timed_out: z.boolean(),
     cancelled: z.boolean().optional(),
+    /** Where the command ran, recorded only when that is not this ledger's root (a
+     *  sibling worktree): its currentness is judged against that tree's source. */
+    work_root: z.string().min(1).max(4_096).optional(),
     source: z.literal("local-command-runner"),
 }).strict();
 export const ReportSaveSchema = z.object({
@@ -717,6 +720,7 @@ export function reportPresentationEnabled(root) {
     }
 }
 export function readTaskReport(root, taskId, currentSnapshot = null) {
+    const snapshotAt = (dir) => typeof currentSnapshot === "function" ? currentSnapshot(dir) : dir === undefined ? currentSnapshot : null;
     const { task, events } = taskDb(root, db => transaction(db, () => {
         const task = readTask(db, root, taskId);
         const { bytes } = db.prepare("SELECT COALESCE(SUM(length(CAST(body AS BLOB))), 0) AS bytes FROM report_events WHERE task_id = ?").get(taskId);
@@ -743,7 +747,7 @@ export function readTaskReport(root, taskId, currentSnapshot = null) {
             claims.push({ ...ReportClaimSchema.parse(value), at: event.at, attribution: "agent-reported", supported_by: null });
         else if (event.kind === "conformance") {
             const rule = ReportConformanceSchema.parse(value);
-            conformance.push({ ...rule, event_id: event.event_id, at: event.at, current: currentSnapshot !== null && rule.snapshot === currentSnapshot });
+            conformance.push({ ...rule, event_id: event.event_id, at: event.at, current: snapshotAt() !== null && rule.snapshot === snapshotAt() });
         }
         else if (event.kind === "save")
             saves.push({ ...ReportSaveSchema.parse(value), event_id: event.event_id, at: event.at, durability: "local", proofs: [] });
@@ -760,7 +764,8 @@ export function readTaskReport(root, taskId, currentSnapshot = null) {
             refusals.push({ ...ReportRefusalSchema.parse(value), event_id: event.event_id, at: event.at });
         else if (event.kind === "check") {
             const check = ReportCheckSchema.parse(value);
-            checks.push({ ...check, at: event.at, current: currentSnapshot !== null && check.before_snapshot === currentSnapshot && check.after_snapshot === currentSnapshot });
+            const now = snapshotAt(check.work_root);
+            checks.push({ ...check, at: event.at, current: now !== null && check.before_snapshot === now && check.after_snapshot === now });
         }
         else if (event.kind !== "check-start")
             throw new Error("unsupported report event kind; update Hunch before reading this report");

package/dist/core/taskReportEvidence.d.ts

@@ -9,6 +9,9 @@ export interface ReportSnapshot {
 /** Bounded source snapshot, not a committed change proof. Ignored files and
  * Hunch's own memory/cache are excluded and explicitly disclosed. */
 export declare function reportSourceSnapshot(root: string): ReportSnapshot;
+/** The current source of `root` for report readers, as a resolver that also hashes the
+ *  sibling worktree a check ran in (its `work_root`). Each tree is hashed at most once. */
+export declare function currentSource(root: string): (dir?: string) => string | null;
 /** Evaluate every delivered lesson's DECLARED rule against the files this task
  * changed (working tree vs HEAD). Deterministic and Hunch-owned: the agent
  * neither chooses the rule nor submits the verdict. A constraint is judged by its
@@ -28,4 +31,8 @@ export declare function runReportCheck(root: string, taskId: string, command: st
     signal?: AbortSignal;
     onStdout?: (chunk: Buffer) => void;
     onStderr?: (chunk: Buffer) => void;
+    /** Where the command runs and whose source is snapshotted, when the task's
+     *  ledger lives in a sibling worktree of the same repository (the hook opened
+     *  the task at the main checkout, the agent works in a linked one). */
+    workRoot?: string;
 }): Promise<ReportCheck>;

package/dist/core/taskReportEvidence.js

@@ -87,6 +87,16 @@ export function reportSourceSnapshot(root) {
         return { hash: null, limitations: [...limitations, "A complete bounded source snapshot was unavailable; no current-change verification is claimed."] };
     }
 }
+/** The current source of `root` for report readers, as a resolver that also hashes the
+ *  sibling worktree a check ran in (its `work_root`). Each tree is hashed at most once. */
+export function currentSource(root) {
+    const seen = new Map();
+    return (dir = root) => {
+        if (!seen.has(dir))
+            seen.set(dir, reportSourceSnapshot(dir).hash);
+        return seen.get(dir);
+    };
+}
 /** Evaluate every delivered lesson's DECLARED rule against the files this task
  * changed (working tree vs HEAD). Deterministic and Hunch-owned: the agent
  * neither chooses the rule nor submits the verdict. A constraint is judged by its
@@ -210,7 +220,8 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
     const task = readTaskReport(root, taskId).task;
     if (task.state !== "open" && task.closed_by !== "host")
         throw new Error("cannot verify a closed task");
-    const before = reportSourceSnapshot(root);
+    const workRoot = options.workRoot ?? root;
+    const before = reportSourceSnapshot(workRoot);
     // Validate sensitive arguments before executing or writing anything.
     ReportCheckSchema.parse({ label, command, exit_code: null, output_hash: reportHash(""), before_snapshot: before.hash, after_snapshot: null, snapshot_limitations: before.limitations, timed_out: false, source: "local-command-runner" });
     const checkId = beginReportCheck(root, taskId, label, timeoutMs);
@@ -228,7 +239,7 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
         const started = (() => {
             try {
                 const resolved = resolveSpawnCommand(command);
-                return spawn(resolved.file, resolved.args, { cwd: root, shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32", windowsVerbatimArguments: resolved.windowsVerbatimArguments === true });
+                return spawn(resolved.file, resolved.args, { cwd: workRoot, shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32", windowsVerbatimArguments: resolved.windowsVerbatimArguments === true });
             }
             catch (error) {
                 // An argument the launcher cannot carry, or a synchronous spawn refusal
@@ -319,9 +330,10 @@ export async function runReportCheck(root, taskId, command, label, timeoutMs = D
         if (options.signal?.aborted)
             cancel();
     });
-    const after = reportSourceSnapshot(root);
+    const after = reportSourceSnapshot(workRoot);
     const check = { check_id: checkId, label, command, exit_code: result.code, output_hash: result.hash, before_snapshot: before.hash, after_snapshot: after.hash,
-        snapshot_limitations: [...new Set([...before.limitations, ...after.limitations])], timed_out: result.timedOut, cancelled: result.cancelled, source: "local-command-runner" };
+        snapshot_limitations: [...new Set([...before.limitations, ...after.limitations])], timed_out: result.timedOut, cancelled: result.cancelled,
+        ...(workRoot !== root ? { work_root: workRoot } : {}), source: "local-command-runner" };
     recordReportCheck(root, taskId, check);
     return check;
 }

package/dist/core/taskReportHook.js

@@ -6,7 +6,7 @@ import { findRoot } from "./paths.js";
 import { canonicalReportRoot } from "./taskReportPaths.js";
 import { isCredentialFreeText } from "./types.js";
 import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport, latestSessionTask, readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, reportTaskExists, resolveReportTask, settleSessionTasks, startReportTask } from "./taskReport.js";
-import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { currentSource } from "./taskReportEvidence.js";
 import { renderTaskReport } from "./taskReportRender.js";
 import { verificationLauncher } from "./verifyLauncher.js";
 import { injectionMode } from "./hookcache.js";
@@ -290,7 +290,7 @@ export function stopHookReport(root, provider, event) {
     if (id === "legacy")
         return { systemMessage: "Hunch hook active. This host version does not provide an exact prompt identifier, so contribution for this response is unverified. Explicit task reports remain available with hunch report." };
     try {
-        const report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+        const report = readTaskReport(root, id, currentSource(root));
         if (isEmptyTaskReport(report))
             return null;
         // The HTML evidence view is a rendering of the local ledger, generated on

package/dist/core/taskReportPublic.js

@@ -3,9 +3,9 @@
 import { JsonStore } from "../store/jsonStore.js";
 import { hunchPaths } from "./paths.js";
 import { readTaskReport, reportHash } from "./taskReport.js";
-import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { currentSource } from "./taskReportEvidence.js";
 export function publicTaskReport(root, taskId) {
-    const report = readTaskReport(root, taskId, reportSourceSnapshot(root).hash);
+    const report = readTaskReport(root, taskId, currentSource(root));
     const publicStore = new JsonStore(hunchPaths(root));
     const records = new Map();
     const deliveries = [];

package/dist/core/taskReportRender.js

@@ -1,11 +1,11 @@
 import { mkdirSync } from "node:fs";
 import { writeFileAtomic } from "./io.js";
 import { readTaskReport, readLessonHistory } from "./taskReport.js";
-import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { currentSource } from "./taskReportEvidence.js";
 import { assertReportPath } from "./taskReportPaths.js";
 import { publicTaskReport, renderPublicTaskReportHtml } from "./taskReportPublic.js";
 export function writeTaskReportHtml(root, taskId, publicOnly = false) {
-    const report = readTaskReport(root, taskId, reportSourceSnapshot(root).hash);
+    const report = readTaskReport(root, taskId, currentSource(root));
     const directory = assertReportPath(root, ".hunch-cache", "reports");
     mkdirSync(directory, { recursive: true });
     const file = assertReportPath(root, ".hunch-cache", "reports", `${report.task.task_id}${publicOnly ? ".public" : ""}.html`);

package/dist/extractors/git.d.ts

@@ -266,6 +266,16 @@ export declare function pathKnownToHistory(root: string, file: string): boolean;
 /** 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 declare function currentBranch(cwd: string): string;
+/** Whether `cwd` has its repository's default branch checked out: origin/HEAD's branch
+ *  when the remote names one, else `main` or `master`. False on a detached HEAD or
+ *  outside a repository, so a caller keeps its pre-existing behavior there. */
+export declare function onDefaultBranch(cwd: string): boolean;
+/** Whether a memory commit of `hunchDir` would have anything to stage: a tracked file git
+ *  sees as changed (after its own line-ending normalization) or an untracked, non-ignored
+ *  file, skipping the derived artifacts and the per-machine local.json the commit never
+ *  stages. A hook's inherited GIT_DIR/GIT_WORK_TREE is stripped, so the repository is
+ *  resolved from `hunchDir` itself. False when git cannot answer. */
+export declare function hunchDirHasChanges(hunchDir: string): boolean;
 /** Whether HEAD is somewhere a write must not land: mid rebase/merge/cherry-pick/revert/bisect
  *  ("git-operation-in-progress", which wins when both hold), or detached ("detached-head").
  *  null when HEAD is a settled branch — and also when git cannot answer at all (not a repo,

package/dist/extractors/git.js

@@ -2283,6 +2283,33 @@ 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
 }
+/** Whether `cwd` has its repository's default branch checked out: origin/HEAD's branch
+ *  when the remote names one, else `main` or `master`. False on a detached HEAD or
+ *  outside a repository, so a caller keeps its pre-existing behavior there. */
+export function onDefaultBranch(cwd) {
+    const branch = currentBranch(cwd);
+    if (!branch)
+        return false;
+    const remoteHead = gitSafe(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"], cwd);
+    if (remoteHead)
+        return branch === remoteHead.replace(/^origin\//, "");
+    return branch === "main" || branch === "master";
+}
+/** Whether a memory commit of `hunchDir` would have anything to stage: a tracked file git
+ *  sees as changed (after its own line-ending normalization) or an untracked, non-ignored
+ *  file, skipping the derived artifacts and the per-machine local.json the commit never
+ *  stages. A hook's inherited GIT_DIR/GIT_WORK_TREE is stripped, so the repository is
+ *  resolved from `hunchDir` itself. False when git cannot answer. */
+export function hunchDirHasChanges(hunchDir) {
+    const changed = [
+        ...gitSafeIsolated(["diff", "--name-only", "--relative", "--no-renames", "HEAD", "--", "."], hunchDir).split("\n"),
+        ...gitSafeIsolated(["ls-files", "--others", "--exclude-standard", "--", "."], hunchDir).split("\n"),
+    ];
+    return changed.some((raw) => {
+        const path = raw.trim().replace(/\\/g, "/");
+        return path !== "" && path !== "local.json" && !isDerivedStoreArtifact(path);
+    });
+}
 /** The state files git writes while it is replaying history. `git rev-parse --git-path`
  *  resolves each against THIS worktree's private git dir (a linked worktree keeps its own
  *  rebase-merge/MERGE_HEAD), so a rebase in one worktree never reads as one in another. */

package/dist/integrations/health.js

@@ -197,7 +197,7 @@ export function inspectIntegrations(root, selected) {
         try {
             const launcher = readLauncher(root, harness);
             recordPins(spec.mcp, [launcher.command, ...launcher.args]);
-            capabilities.mcp.detail = "Configured locally; use --probe to verify a fresh server, then reconnect the host";
+            capabilities.mcp.detail = `Configured locally; run \`hunch integrations check --probe --harness ${harness}\` to verify a fresh server, then reconnect the host`;
         }
         catch (e) {
             // A harness can be detected here via its hooks file alone —

package/dist/integrations/probe.d.ts

@@ -1,4 +1,15 @@
 import { type Harness, type IntegrationHealth } from "./health.js";
+/** A launcher that runs THIS Hunch build directly (`node <build>/cli/index.js mcp`) —
+ *  a local checkout or an unpacked test build. It is exactly the code already
+ *  running the probe, so starting it executes nothing new; any other custom
+ *  command stays inspect-only. The server identity/version check still applies.
+ *  The command is a bare `node` (PATH lookup) or this exact Node binary — a
+ *  directory-qualified `./tools/node` in a cloned repo is not, whatever its name —
+ *  and the probe spawns process.execPath itself, never the configured name. */
+export declare function isSelfLauncher(launcher: {
+    command: string;
+    args: string[];
+}, entry?: string): boolean;
 /** 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/probe.js

@@ -1,6 +1,27 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sameFilesystemEntry } from "../extractors/git.js";
 import { HARNESSES, readLauncher } from "./health.js";
+/** A launcher that runs THIS Hunch build directly (`node <build>/cli/index.js mcp`) —
+ *  a local checkout or an unpacked test build. It is exactly the code already
+ *  running the probe, so starting it executes nothing new; any other custom
+ *  command stays inspect-only. The server identity/version check still applies.
+ *  The command is a bare `node` (PATH lookup) or this exact Node binary — a
+ *  directory-qualified `./tools/node` in a cloned repo is not, whatever its name —
+ *  and the probe spawns process.execPath itself, never the configured name. */
+export function isSelfLauncher(launcher, entry = fileURLToPath(new URL("../cli/index.js", import.meta.url))) {
+    const bareNode = /^node(?:\.exe)?$/i.test(launcher.command);
+    const node = bareNode || (isAbsolute(launcher.command) && existsSync(launcher.command) && sameFilesystemEntry(launcher.command, process.execPath));
+    if (!node || launcher.args.length !== 2 || launcher.args[1] !== "mcp")
+        return false;
+    const script = launcher.args[0];
+    // Generated launchers name the build entry absolutely; a relative script would resolve
+    // against whatever cwd the host spawns in.
+    return isAbsolute(script) && existsSync(script) && existsSync(entry) && sameFilesystemEntry(script, entry);
+}
 /** 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 async function probeIntegration(root, harness, report, timeoutMs = 15_000) {
@@ -16,11 +37,15 @@ export async function probeIntegration(root, harness, report, timeoutMs = 15_000
             throw new Error("custom MCP environment or working directory requires a host-side probe; no settings were ignored");
         // Only execute the exact published launcher Hunch generates. Custom
         // commands may need credentials or have unrelated effects; inspect only.
-        if (!/^npx(?:\.cmd)?$/.test(launcher.command) || JSON.stringify(launcher.args) !== JSON.stringify([
+        const generated = /^npx(?:\.cmd)?$/.test(launcher.command) && JSON.stringify(launcher.args) === JSON.stringify([
             "-y", `--package=hunch-exact@npm:@davesheffer/hunch@${report.expectedVersion}`, "hunch", "mcp",
-        ]))
-            throw new Error("probe requires the generated exact-version npx launcher; repair stale pins first; custom launchers remain untested");
-        transport = new StdioClientTransport({ ...launcher, cwd: root, stderr: "pipe" });
+        ]);
+        const self = !generated && isSelfLauncher(launcher);
+        if (!generated && !self)
+            throw new Error("probe requires the generated exact-version npx launcher, or a `node <build>/cli/index.js mcp` launcher probed by that same build; repair stale pins first; other custom launchers remain untested");
+        // A self launcher runs this exact Node binary: no PATH/cwd lookup of `node` can
+        // resolve to an executable planted in the repository.
+        transport = new StdioClientTransport({ ...launcher, ...(self ? { command: process.execPath } : {}), cwd: root, stderr: "pipe" });
         transport.stderr?.on("data", () => { });
         await Promise.race([
             (async () => {

package/dist/integrations/sync.d.ts

@@ -11,11 +11,11 @@ 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;
+export declare function flushMemoryHome(store: HunchStore, publicHunchDir: string, home: MemoryHome, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | "held" | 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>>;
+export declare function flushMemoryHomes(store: HunchStore, publicHunchDir: string, homes: Iterable<MemoryHome>, message: string, remoteOverride?: HunchRemoteContract): Partial<Record<MemoryHome, "pushed" | "committed" | "held" | 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;
@@ -24,7 +24,19 @@ export declare function flushPrivate(store: HunchStore, message: string): void;
  *  "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). */
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up),
+ *  or "held" (a public capture left uncommitted because the default branch is checked
+ *  out; callers say so with HELD_ON_DEFAULT_BRANCH). */
 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;
+remoteOverride?: HunchRemoteContract, observe?: GitMemoryObserver): "pushed" | "committed" | "held" | null;
+/** Auto-commit a state-contract write (`nuryel_write`, `hunch serve`). A state root is a
+ *  dedicated data repository whose writes commit on whatever branch it serves, so the
+ *  default-branch hold for captures never applies; outcomes as flushCapture otherwise. */
+export declare function flushStateWrite(store: HunchStore, publicHunchDir: string, isPrivate: boolean, message: string, remoteOverride?: HunchRemoteContract): "pushed" | "committed" | null;
+/** What a caller prints for a "held" flush, so a solo user on main is never left
+ *  wondering why the capture commit stopped appearing. */
+export declare const HELD_ON_DEFAULT_BRANCH = "not auto-committed: the default branch is checked out \u2014 your next commit that adds .hunch/ carries it (to restore auto-commit there, set \"autoCommitDefaultBranch\": true in .hunch/local.json)";
+/** Whether an automatic public memory commit must be held: the default branch is checked
+ *  out and the user has not opted back in. Shared by flushStore and `hunch sync`. */
+export declare function holdsOnDefaultBranch(publicHunchDir: string): boolean;

package/dist/integrations/sync.js

@@ -7,8 +7,9 @@
  * commits (bug_overlay_clobber); the memory commit rides their next push instead.
  * Used by every CLI/MCP path that writes a record.
  */
-import { dirname } from "node:path";
-import { commitAndPushHunch } from "../extractors/git.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { commitAndPushHunch, hunchDirHasChanges, onDefaultBranch } from "../extractors/git.js";
 import { refreshCommittableGrounding } from "./providers.js";
 import { advertisedTeamRemoteContract } from "./team.js";
 const pinnedSharedRoutes = new WeakMap();
@@ -41,6 +42,10 @@ export function flushMemoryHome(store, publicHunchDir, home, message, remoteOver
     }
     if (!store.autoCommit)
         return null;
+    // Same hold as flushCapture: the public commit stages all of .hunch/, so it would
+    // otherwise sweep a capture that was just reported as held onto the default branch.
+    if (holdsOnDefaultBranch(publicHunchDir))
+        return heldOrNothing(publicHunchDir);
     const grounding = refreshCommittableGrounding(dirname(publicHunchDir), store);
     return commitAndPushHunch(publicHunchDir, message, { push: false, alsoStage: grounding });
 }
@@ -70,10 +75,21 @@ export function flushPrivate(store, message) {
  *  "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). */
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up),
+ *  or "held" (a public capture left uncommitted because the default branch is checked
+ *  out; callers say so with HELD_ON_DEFAULT_BRANCH). */
 export function flushCapture(store, publicHunchDir, isPrivate, message, 
 /** Long-lived callers can pin the route snapshot that admitted the write. */
 remoteOverride, observe) {
+    return flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, observe, true);
+}
+/** Auto-commit a state-contract write (`nuryel_write`, `hunch serve`). A state root is a
+ *  dedicated data repository whose writes commit on whatever branch it serves, so the
+ *  default-branch hold for captures never applies; outcomes as flushCapture otherwise. */
+export function flushStateWrite(store, publicHunchDir, isPrivate, message, remoteOverride) {
+    return flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, undefined, false);
+}
+function flushStore(store, publicHunchDir, isPrivate, message, remoteOverride, observe, holdOnDefaultBranch) {
     // 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") {
@@ -89,10 +105,45 @@ remoteOverride, observe) {
     }
     if (!store.autoCommit)
         return null;
+    // A capture never commits onto the default branch by itself: task and capture commits
+    // landed on main between the user's own. The record stays on disk; the user's next
+    // commit carries it, or the next capture on a feature branch sweeps it up. Held before
+    // the grounding refresh, so an automatic capture (hook sync, MCP) leaves tracked docs at
+    // HEAD instead of counting a record that `git commit -a` would leave behind; by-hand CLI
+    // commands refresh them on disk themselves (publicFlushCommitsGrounding in the CLI).
+    if (holdOnDefaultBranch && holdsOnDefaultBranch(publicHunchDir))
+        return heldOrNothing(publicHunchDir);
     // A public capture changes record counts, so refresh git-clean grounding docs and fold
     // 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, observe });
 }
+/** What a caller prints for a "held" flush, so a solo user on main is never left
+ *  wondering why the capture commit stopped appearing. */
+export const HELD_ON_DEFAULT_BRANCH = "not auto-committed: the default branch is checked out — your next commit that adds .hunch/ carries it (to restore auto-commit there, set \"autoCommitDefaultBranch\": true in .hunch/local.json)";
+/** A hold reports "held" only when there is something left for the next commit; a clean
+ *  .hunch/ is null, as an unheld flush with nothing staged would be. */
+function heldOrNothing(publicHunchDir) {
+    return hunchDirHasChanges(publicHunchDir) ? "held" : null;
+}
+/** Whether an automatic public memory commit must be held: the default branch is checked
+ *  out and the user has not opted back in. Shared by flushStore and `hunch sync`. */
+export function holdsOnDefaultBranch(publicHunchDir) {
+    return !defaultBranchCommitsAllowed(publicHunchDir) && onDefaultBranch(dirname(publicHunchDir));
+}
+/** Opt back in to capture commits on the default branch: `autoCommitDefaultBranch: true`
+ *  in the per-machine .hunch/local.json, or HUNCH_AUTO_COMMIT_DEFAULT_BRANCH=1. */
+function defaultBranchCommitsAllowed(publicHunchDir) {
+    if (process.env.HUNCH_AUTO_COMMIT_DEFAULT_BRANCH === "1")
+        return true;
+    try {
+        const raw = readFileSync(join(publicHunchDir, "local.json"), "utf8");
+        const local = JSON.parse(raw.startsWith("\uFEFF") ? raw.slice(1) : raw);
+        return !!local && typeof local === "object" && local.autoCommitDefaultBranch === true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=sync.js.map

package/dist/integrations/workspaceLedger.d.ts

@@ -47,7 +47,7 @@ export type SnapshotOutcome = {
     status: "written";
     record: Workspace;
     home: "private" | "public";
-    flushed: "pushed" | "committed" | null;
+    flushed: "pushed" | "committed" | "held" | null;
 };
 /** Record this machine's snapshot. Honors `workspaces.publish`, skips a write when the
  *  content is unchanged and the stored record is under a day old (an idle machine's hooks

package/dist/mcp/server.js

@@ -34,7 +34,7 @@ import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
 import { workspacesConfig } from "../core/config.js";
 import { revParse, asOfDate, revExists, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatusDetailed, describePullFailure, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
-import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
+import { flushCapture, flushStateWrite, flushMemoryHome, pinSharedRemote, HELD_ON_DEFAULT_BRANCH } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, isTeamStoreTrusted, overlayMatchesTeamRemote, teamWiringConsented, untrustedTeamStoreMessage, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
 import { formatSearchHit, formatStructure } from "../core/format.js";
@@ -113,12 +113,13 @@ function cwdHintOf(input) {
 /** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
  *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
  *  next flush sweeps it up; claiming "auto-committed" there would be a lie. */
-const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
-    : flush === "committed"
-        ? home === "private"
-            ? " (committed to the overlay repo — push deferred: offline, no upstream, or merge conflict; the next capture or `hunch private --sync` retries)"
-            : " (auto-committed to .hunch/ — rides your next push)"
-        : "";
+const flushNote = (flush, home, mode) => flush === "held" ? ` (${HELD_ON_DEFAULT_BRANCH})`
+    : flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
+        : flush === "committed"
+            ? home === "private"
+                ? " (committed to the overlay repo — push deferred: offline, no upstream, or merge conflict; the next capture or `hunch private --sync` retries)"
+                : " (auto-committed to .hunch/ — rides your next push)"
+            : "";
 /** When an overlay exists, a PUBLIC write deserves one visible line: a record that
  *  lands in the committed store publishes on the next push, and an agent writing
  *  strategy/competitive content there is a leak nobody notices until it ships
@@ -2767,7 +2768,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 // not race the HTTP server between the ledger read and the record write.
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, result);
             }
@@ -2784,7 +2785,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             try {
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} observation ${result.record_id} (${result.durability}); this does not assert currentness. ${result.record_hash}`, result);
             }
@@ -2801,7 +2802,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             try {
                 const { hunchDir } = stateHomeFor(store, input.scope);
                 const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
+                    flush: (isPrivate, message) => flushStateWrite(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`Capture batch: ${result.results.filter(r => r.status === "saved").length} saved/replayed, ${result.results.filter(r => r.status === "refused").length} refused.${result.reviews ? ` Reviews: ${result.reviews.filter(r => r.status === "saved").length} withdrawn/replayed, ${result.reviews.filter(r => r.status === "refused").length} refused.` : ''} Inspect each indexed result.`, result);
             }

package/dist/mcp/taskReportTools.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { verificationLauncherFor } from "../core/verifyLauncher.js";
 import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
-import { reportSourceSnapshot, runReportConformance } from "../core/taskReportEvidence.js";
+import { currentSource, runReportConformance } from "../core/taskReportEvidence.js";
 import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.js";
 function applicationReferences(report) {
     return report.deliveries.flatMap(d => d.records.map(r => ({ occurrence_id: d.occurrence_id, record_id: r.record_id, content_hash: r.content_hash, title: r.title }))).slice(-100);
@@ -85,7 +85,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                     // from the model must not fork a second report or fail the start.
                     if (!task_id || !/different title/.test(error.message))
                         throw error;
-                    task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
+                    task = readTaskReport(root, task_id, currentSource(root)).task;
                 }
                 const launcher = verificationLauncher();
                 // Compact by design (#370): the rules an agent needs to act, and exact
@@ -120,7 +120,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             catch (error) {
                 graphNote = `\nGraph     not saved: ${error.message}`;
             }
-            const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
+            const report = readTaskReport(root, task_id, currentSource(root));
             const show = reportPresentationEnabled(root);
             // The HTML evidence view is rendered on demand (hunch_report(html: true),
             // `hunch report <id> --html`, or the VS Code view); finish writes no file.
@@ -165,7 +165,7 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                 const tasks = listReportTasks(root);
                 return { content: [{ type: "text", text: tasks.length ? tasks.map(t => `${t.task_id} · ${t.state} · ${t.title}`).join("\n") : "No task reports yet. Start with hunch_task." }], structuredContent: { tasks } };
             }
-            const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
+            const report = readTaskReport(root, task_id, currentSource(root));
             const file = html ? writeTaskReportHtml(root, task_id) : null;
             return { content: [{ type: "text", text: `${renderTaskReport(report)}${file ? `\nLocal evidence view: ${file}` : ""}` }], structuredContent: { ...boundedTaskReportForHost(report), application_references: applicationReferences(report), contribution_card: renderTaskReport(report), report_path: file } };
         }