@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/constitution/experiment.d.ts

@@ -59,8 +59,8 @@ export declare const ExperimentCaseBankSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     preregistration_id: z.ZodString;
     preregistration_hash: z.ZodString;
@@ -137,8 +137,8 @@ export declare const ExperimentRunSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     preregistration_id: z.ZodString;
     preregistration_hash: z.ZodString;
@@ -210,8 +210,8 @@ export declare const ExperimentOutcomeSchema: z.ZodObject<{
     run_id: z.ZodString;
     assignment_id: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     arm: z.ZodString;
     status: z.ZodEnum<{

package/dist/constitution/g3.d.ts

@@ -42,8 +42,8 @@ export declare const ExperimentPreregistrationSchema: z.ZodObject<{
     id: z.ZodString;
     content_hash: z.ZodString;
     experiment: z.ZodEnum<{
-        "EXP-03": "EXP-03";
         "EXP-01": "EXP-01";
+        "EXP-03": "EXP-03";
     }>;
     revision: z.ZodNumber;
     hypothesis: z.ZodString;

package/dist/core/footprint.d.ts

@@ -0,0 +1,15 @@
+export interface FootprintSurface {
+    id: string;
+    chars: number;
+    est_tokens: number;
+    detail?: Record<string, number>;
+}
+export interface FootprintReport {
+    schema: "hunch.footprint/1";
+    estimate: "chars/4";
+    surfaces: FootprintSurface[];
+    unmeasured: string[];
+}
+export declare function measureFootprint(root: string, opts?: {
+    target?: string;
+}): Promise<FootprintReport>;

package/dist/core/footprint.js

@@ -0,0 +1,167 @@
+// Context footprint (#372): how much text Hunch injects into an agent's
+// context, measured deterministically from the same code paths the product
+// serves. Tokens are an estimate (characters / 4), not a tokenizer.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { buildServer } from "../mcp/server.js";
+import { renderHunchSection } from "../integrations/claudemd.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { hunchPaths } from "./paths.js";
+import { PIPELINE_LOOP } from "./pipeline.js";
+import { HOOK_REMINDER } from "./hookText.js";
+import { taskInstruction } from "./taskReportHook.js";
+const CONTEXT_BUDGET = 1500;
+const estTokens = (chars) => Math.ceil(chars / 4);
+const surface = (id, chars, detail) => ({ id, chars, est_tokens: estTokens(chars), ...(detail ? { detail } : {}) });
+const jsonChars = (v) => (v === undefined ? 0 : JSON.stringify(v).length);
+/** A host shows one channel of a tool result: Claude Code shows only
+ * structuredContent, text-only hosts only content. The larger one is the cost. */
+function hostVisible(id, result) {
+    const content = jsonChars(result.content), structured = jsonChars(result.structuredContent);
+    return surface(id, Math.max(content, structured), { content_chars: content, structured_chars: structured });
+}
+/** The hunch_task start and finish results for a task with one delivered lesson.
+ * Driven in a throwaway store, never `root`: a task writes a ledger row, and
+ * `taskRecords: false` keeps finish from writing or committing a graph record. */
+async function measureTaskLifecycle() {
+    const dir = mkdtempSync(join(tmpdir(), "hunch-footprint-"));
+    try {
+        // A real task runs in a git repo; the source snapshot reads git.
+        try {
+            execFileSync("git", ["init", "-q", dir], { stdio: "ignore" });
+        }
+        catch { /* measured without git */ }
+        const store = new HunchStore(hunchPaths(dir));
+        try {
+            store.json.ensureDirs();
+            writeFileSync(join(dir, ".hunch", "local.json"), JSON.stringify({ taskRecords: false, autoCommit: false }));
+            store.json.put("constraints", {
+                id: "con_footprint_sample", type: "architecture", statement: "Tool results stay machine-readable.",
+                scope: ["src/sample.ts"], severity: "blocking", enforcement: "advisory_v1", match: null, forbids: null,
+                rationale: "Orchestrators must not parse prose.", source_decision: null, violations: [], status: "active",
+                valid_from: "2026-01-01T00:00:00.000Z", valid_to: null,
+                provenance: { source: "human_confirmed", confidence: 1, evidence: [] },
+            });
+            store.reindex();
+        }
+        finally {
+            store.close();
+        }
+        const server = buildServer(dir);
+        const [ct, st] = InMemoryTransport.createLinkedPair();
+        const client = new Client({ name: "hunch-footprint", version: "1" });
+        await Promise.all([server.connect(st), client.connect(ct)]);
+        try {
+            const start = await client.callTool({ name: "hunch_task", arguments: { action: "start", title: "Assistant task" } });
+            const taskId = start.structuredContent?.task?.task_id;
+            if (start.isError || !taskId)
+                throw new Error("hunch_task start failed");
+            await client.callTool({ name: "hunch_context", arguments: { target: "src/sample.ts", task_id: taskId } });
+            const finish = await client.callTool({ name: "hunch_task", arguments: { action: "finish", task_id: taskId } });
+            if (finish.isError)
+                throw new Error("hunch_task finish failed");
+            return [hostVisible("mcp.hunch_task.start", start), hostVisible("mcp.hunch_task.finish", finish)];
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Surfaces built inline from live host/session state; not measurable in-process. */
+const UNMEASURED = [
+    "hook.session.orientation — SessionStart text is built inline in the `hook` command action (src/cli/index.ts) from live session state",
+    "hook.pre_edit.grounding — PreToolUse grounding is built per edited file and event",
+];
+/** The file most decisions cite — a FILE target, so the brief carries per-record
+ *  lines and omissions the way a pre-edit call does. "src" when no decision names one. */
+function busiestFile(store) {
+    const counts = new Map();
+    for (const d of store.advisoryRecs("decisions")) {
+        for (const f of new Set(d.related_files))
+            if (!f.includes("*"))
+                counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0] ?? "src";
+}
+export async function measureFootprint(root, opts = {}) {
+    const surfaces = [];
+    let target = opts.target;
+    if (!target) {
+        const store = new HunchStore(hunchPaths(root));
+        try {
+            target = busiestFile(store);
+        }
+        finally {
+            store.close();
+        }
+    }
+    const server = buildServer(root);
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "hunch-footprint", version: "1" });
+    await Promise.all([server.connect(st), client.connect(ct)]);
+    try {
+        const tools = (await client.listTools()).tools;
+        let outputChars = 0, inputChars = 0, descriptionChars = 0, largest = 0;
+        for (const t of tools) {
+            outputChars += jsonChars(t.outputSchema);
+            inputChars += jsonChars(t.inputSchema);
+            descriptionChars += (t.description ?? "").length;
+            largest = Math.max(largest, jsonChars(t));
+        }
+        surfaces.push(surface("mcp.tools_list", jsonChars(tools), {
+            output_schema_chars: outputChars,
+            input_schema_chars: inputChars,
+            description_chars: descriptionChars,
+            tools: tools.length,
+            largest_tool_chars: largest,
+        }));
+        // What hosts that drop outputSchema actually pay.
+        const core = tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+        surfaces.push(surface("mcp.tools_list.core", jsonChars(core)));
+        const result = await client.callTool({ name: "hunch_context", arguments: { target, budget_tokens: CONTEXT_BUDGET } });
+        // A host shows the model one channel — structuredContent when it reads it,
+        // content otherwise — so the cost it pays is the larger, not the sum.
+        const contentChars = jsonChars(result.content);
+        const structuredChars = jsonChars(result.structuredContent);
+        const chars = Math.max(contentChars, structuredChars);
+        surfaces.push(surface("mcp.hunch_context", chars, {
+            content_chars: contentChars,
+            structured_chars: structuredChars,
+            budget_tokens: CONTEXT_BUDGET,
+            // est_tokens / budget, ×100 as an integer percentage.
+            budget_ratio_pct: Math.round((estTokens(chars) / CONTEXT_BUDGET) * 100),
+        }));
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+    surfaces.push(...await measureTaskLifecycle());
+    const store = new HunchStore(hunchPaths(root));
+    try {
+        surfaces.push(surface("grounding.block", renderHunchSection(store, root).length));
+    }
+    finally {
+        store.close();
+    }
+    surfaces.push(surface("hook.session.pipeline_loop", PIPELINE_LOOP.length));
+    surfaces.push(surface("hook.prompt.reminder", HOOK_REMINDER.length));
+    // Every prompt gets a task instruction: full once per session, compact after.
+    // Measured for a host whose stop hook closes the task, with a fixed installed
+    // launcher and cwd so the number does not move with the checkout path.
+    const sampleTask = { task_id: "htask_" + "0".repeat(24), title: "Assistant task" };
+    const sampleCwd = JSON.stringify("/home/user/repo");
+    const sampleLauncher = () => ({ shell: "node /home/user/repo/node_modules/@davesheffer/hunch/dist/cli/index.js" });
+    surfaces.push(surface("hook.prompt.task_instruction", taskInstruction(sampleTask, sampleCwd, "claude", sampleLauncher).length));
+    surfaces.push(surface("hook.prompt.task_instruction.compact", taskInstruction(sampleTask, sampleCwd, "claude", sampleLauncher, "compact").length));
+    return { schema: "hunch.footprint/1", estimate: "chars/4", surfaces, unmeasured: [...UNMEASURED] };
+}
+//# sourceMappingURL=footprint.js.map

package/dist/core/groundingLag.d.ts

@@ -25,6 +25,9 @@
  * run ahead (missing record). Open findings move both ways (a finding resolved on one
  * branch, a finding recorded on another), so a differing findings count alone is lag.
  */
+/** The block's prose template version (claudemd.ts GROUNDING_TEMPLATE). A block
+ *  without the stamp is template 1. */
+export declare function groundingTemplate(block: string): number;
 export interface GroundingCounts {
     decisions: number;
     bugs: number;
@@ -71,11 +74,23 @@ export type GroundingFreshness =
     committed: GroundingCounts;
     generated: GroundingCounts;
     ahead: string[];
+    newerTemplate?: {
+        committed: number;
+        renderer: number;
+    };
 }
 /** The block differs outside the counts sentence (or a counts sentence is missing). */
  | {
     kind: "diverged";
     reason: string;
+}
+/** The committed block was written by a newer renderer template than this
+ *  version's: its prose is preserved (preserveNewerTemplate), never a failure. */
+ | {
+    kind: "newer";
+    committedTemplate: number;
+    rendererTemplate: number;
+    countsReadable: boolean;
 };
 /** Classify a committed managed block against the one the graph generates NOW.
  *  Both inputs are block CONTENT (markers stripped, trimmed). */

package/dist/core/groundingLag.js

@@ -25,6 +25,13 @@
  * run ahead (missing record). Open findings move both ways (a finding resolved on one
  * branch, a finding recorded on another), so a differing findings count alone is lag.
  */
+const TEMPLATE_RE = /<!-- hunch:template (\d+) -->/;
+/** The block's prose template version (claudemd.ts GROUNDING_TEMPLATE). A block
+ *  without the stamp is template 1. */
+export function groundingTemplate(block) {
+    const m = TEMPLATE_RE.exec(block);
+    return m ? Number(m[1]) : 1;
+}
 const COUNTS_RE = /\*\*(\d+) decisions?, (\d+) bugs?, (\d+) constraints?, (\d+) components?, (\d+) polic(?:y|ies)(?:, (\d+) open findings?)?\*\*/;
 /** Record kinds whose committed count may only ever lag behind the store. */
 export const APPEND_ONLY_COUNT_KINDS = ["decisions", "bugs", "constraints", "components", "policies"];
@@ -64,8 +71,19 @@ export function parseGroundingCounts(block) {
 export function classifyGroundingBlock(committed, generated) {
     if (committed === generated)
         return { kind: "fresh" };
+    const committedTemplate = groundingTemplate(committed);
+    const rendererTemplate = groundingTemplate(generated);
     const c = parseGroundingCounts(committed);
     const g = parseGroundingCounts(generated);
+    if (committedTemplate > rendererTemplate) {
+        // A newer template may reword the prose, but a count AHEAD of the store still
+        // means the doc knows a record this repository does not carry.
+        const ahead = c && g ? APPEND_ONLY_COUNT_KINDS.filter((k) => c.counts[k] > g.counts[k]) : [];
+        if (c && g && ahead.length) {
+            return { kind: "ahead", committed: c.counts, generated: g.counts, ahead, newerTemplate: { committed: committedTemplate, renderer: rendererTemplate } };
+        }
+        return { kind: "newer", committedTemplate, rendererTemplate, countsReadable: c !== null };
+    }
     if (!c)
         return { kind: "diverged", reason: "the committed block carries no record-counts sentence" };
     if (!g)
@@ -88,9 +106,18 @@ export function describeGroundingFreshness(doc, verdict) {
         case "lagging":
             return `${doc}: counts lag the store (${delta(verdict.committed, verdict.generated, verdict.behind)}) — records merged in behind the doc; heals on the next capture or \`hunch grounding --refresh\``;
         case "ahead":
+            // A newer Hunch may have written records this version skips as unreadable, and a
+            // plain refresh keeps a newer block's prose: only an upgrade or --force settles it.
+            if (verdict.newerTemplate) {
+                return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) in a block written by a newer Hunch (template ${verdict.newerTemplate.committed} > ${verdict.newerTemplate.renderer}) — this version may skip records it cannot read, or the record was removed; upgrade Hunch, or run \`hunch grounding --refresh --force\` and commit`;
+            }
             return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) — the doc counted a record this repository does not carry; commit the missing .hunch/ record or regenerate`;
         case "diverged":
             return `${doc}: stale — ${verdict.reason}; regenerate with \`hunch grounding --refresh\` and commit`;
+        case "newer":
+            return `${doc}: written by a newer Hunch (template ${verdict.committedTemplate} > ${verdict.rendererTemplate}); ${verdict.countsReadable
+                ? "its prose is kept and a refresh updates only the counts"
+                : "this version cannot read its counts sentence, so a refresh leaves the block as written"}. Upgrade Hunch, or run \`hunch grounding --refresh --force\` to re-render with this version`;
     }
 }
 //# sourceMappingURL=groundingLag.js.map

package/dist/core/hookText.d.ts

@@ -0,0 +1,4 @@
+/** The UserPromptSubmit reminder `hunch hook` injects once per session (and with
+ *  every correction). Lives in
+ *  core so `hunch footprint` measures the exact text the hook sends. */
+export declare const HOOK_REMINDER: string;

package/dist/core/hookText.js

@@ -0,0 +1,8 @@
+/** The UserPromptSubmit reminder `hunch hook` injects once per session (and with
+ *  every correction). Lives in
+ *  core so `hunch footprint` measures the exact text the hook sends. */
+export const HOOK_REMINDER = "Hunch (engineering memory) is available for this repo. Before editing, call " +
+    "hunch_check_constraints(scope) for do-not-break invariants and hunch_why(target) " +
+    "for the rationale; use hunch_get_dependents for blast radius and hunch_bug_lineage " +
+    "for prior root causes. After a non-trivial choice, record it with hunch_record_decision.";
+//# sourceMappingURL=hookText.js.map

package/dist/core/pipeline.d.ts

@@ -150,6 +150,23 @@ export interface PipelineState {
     /** Activity index and count for bounded mid-flight reminders. */
     proofReminderActivity: number;
     proofReminders: number;
+    /** Sibling-fix lessons delivered this session (see core/siblingfix.ts). */
+    lessons: PendingLesson[];
+}
+/** A delivered lesson the agent has not visibly acted on yet. `hash` is the
+ *  target function's body at delivery; a different body later means the agent
+ *  touched it, so the lesson is no longer pending. */
+export interface PendingLesson {
+    id: string;
+    file: string;
+    symbol: string;
+    sibling: string;
+    siblingFile: string;
+    /** "<sha8> <subject>" of the change the sibling received. */
+    change: string;
+    callers: string[];
+    hash: string | null;
+    reminded: boolean;
 }
 export declare const emptyState: () => PipelineState;
 /** Validate untrusted MCP/env episode data. Invalid entries are ignored so the
@@ -273,6 +290,17 @@ export declare function proofCheckpoint(before: PipelineState, after: PipelineSt
 export declare const PIPELINE_LOOP: string;
 export declare const UNVERIFIED_NAG = "Hunch pipeline: earlier product edits are still UNVERIFIED \u2014 run the relevant test/build/typecheck before claiming anything about them.";
 export declare function unverifiedNag(state: PipelineState): string;
+/** Record lessons the grounding just delivered (dedup by id; first delivery keeps its baseline). */
+export declare function onLessonsDelivered(state: PipelineState, lessons: readonly Omit<PendingLesson, "reminded">[]): PipelineState;
+/** The one follow-up an advisory lesson gets. It fires when the agent runs a
+ *  check (test/build/typecheck) while a delivered lesson's function is still
+ *  untouched: the moment the agent thinks it is done, which is when an ignored
+ *  lesson would otherwise ship. Once per lesson, never a block. `hashOf`
+ *  returns the function's current body hash (null: cannot tell, stay silent). */
+export declare function lessonReminder(state: PipelineState, command: string, hashOf: (lesson: PendingLesson) => string | null): {
+    state: PipelineState;
+    reminder: string;
+};
 /** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
  *  edits, and at most twice per turn. */
 export declare function stopVerdict(state: PipelineState, firmness: Firmness): {

package/dist/core/pipeline.js

@@ -63,6 +63,7 @@ export const emptyState = () => ({
     proofActivity: 0,
     proofReminderActivity: 0,
     proofReminders: 0,
+    lessons: [],
 });
 const MAX_OBLIGATIONS = 12;
 const MAX_ALTERNATIVES = 6;
@@ -1033,6 +1034,51 @@ export function unverifiedNag(state) {
         return generic;
     return `${generic} Controller obligations still pending: ${pending.slice(0, 4).map((item) => `[${item.category}] ${item.description}`).join("; ")}.`;
 }
+const MAX_LESSONS = 6;
+/** Any profile's check shape: the reminder fires when the agent starts proving
+ *  its work, whatever the domain. */
+const CHECK_SHAPE = new RegExp([...Object.values(DEFAULT_PROFILES).map((p) => p.verify.source), "node (--test|-e\\b)"].join("|"), "i");
+/** Record lessons the grounding just delivered (dedup by id; first delivery keeps its baseline). */
+export function onLessonsDelivered(state, lessons) {
+    const known = new Set(state.lessons.map((l) => l.id));
+    const added = lessons.filter((l) => !known.has(l.id)).map((l) => ({ ...l, reminded: false }));
+    return added.length ? { ...state, lessons: [...state.lessons, ...added].slice(-MAX_LESSONS) } : state;
+}
+/** The one follow-up an advisory lesson gets. It fires when the agent runs a
+ *  check (test/build/typecheck) while a delivered lesson's function is still
+ *  untouched: the moment the agent thinks it is done, which is when an ignored
+ *  lesson would otherwise ship. Once per lesson, never a block. `hashOf`
+ *  returns the function's current body hash (null: cannot tell, stay silent). */
+export function lessonReminder(state, command, hashOf) {
+    if (!CHECK_SHAPE.test(command) || !state.lessons.some((l) => !l.reminded))
+        return { state, reminder: "" };
+    const due = [];
+    const lessons = state.lessons.map((l) => {
+        if (l.reminded)
+            return l;
+        const now = hashOf(l);
+        if (now === null || l.hash === null)
+            return l;
+        if (now !== l.hash)
+            return { ...l, reminded: true };
+        due.push(l);
+        return { ...l, reminded: true };
+    });
+    if (!due.length)
+        return { state: { ...state, lessons }, reminder: "" };
+    const lines = due.map((l) => {
+        const via = l.callers.length ? ` ${l.callers.slice(0, 3).map((c) => `\`${c}\``).join(", ")} call${l.callers.length === 1 ? "s" : ""} it, so your change runs through the copy that lacks the fix.` : "";
+        return `- \`${l.symbol}\` (${l.file}) is unchanged since Hunch showed you the change its same-shaped sibling \`${l.sibling}\` (${l.siblingFile}) received: ${l.change}.${via}`;
+    });
+    return {
+        state: { ...state, lessons },
+        reminder: [
+            "Hunch — before you finish: a lesson delivered earlier is still open.",
+            ...lines,
+            "The checks you are running were written before this lesson; unless one feeds this function the input the sibling's change handles, they do not show it is covered. Carry the change with a test. It does not apply only if that input cannot reach the function or is already handled another way; then say which in your final answer. \"Pre-existing\" or \"outside this task\" does not count: your change runs through this copy, so leaving it ships the gap again inside your change.",
+        ].join("\n"),
+    };
+}
 /** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
  *  edits, and at most twice per turn. */
 export function stopVerdict(state, firmness) {
@@ -1071,6 +1117,10 @@ export function loadPipelineState(sessionId) {
         state.proofReminderActivity = Number.isSafeInteger(raw.proofReminderActivity) && raw.proofReminderActivity >= 0 ? raw.proofReminderActivity : 0;
         state.proofReminders = Number.isSafeInteger(raw.proofReminders) && raw.proofReminders >= 0 ? raw.proofReminders : 0;
         state.probeBlocks = Number.isSafeInteger(raw.probeBlocks) && raw.probeBlocks >= 0 ? raw.probeBlocks : 0;
+        state.lessons = (Array.isArray(raw.lessons) ? raw.lessons : []).filter((l) => !!l && typeof l === "object"
+            && typeof l.id === "string" && typeof l.file === "string" && typeof l.symbol === "string" && typeof l.sibling === "string"
+            && typeof l.siblingFile === "string" && typeof l.change === "string" && Array.isArray(l.callers)
+            && (l.hash === null || typeof l.hash === "string") && typeof l.reminded === "boolean").slice(-MAX_LESSONS);
         const specs = normalizeExecutionObligations(raw.obligations);
         const tracked = new Map((Array.isArray(raw.obligations) ? raw.obligations : []).map((item) => {
             const candidate = item;

package/dist/core/shellwrites.d.ts

@@ -0,0 +1,7 @@
+/** Record the working tree as it stands, so later shell writes are measured
+ *  from here (a prompt, or any tool call that is not a shell command). */
+export declare function refreshShellBaseline(root: string, sessionId: string | undefined, agentId?: string): void;
+/** Repo-relative files the shell command that just ran wrote (created or
+ *  modified), and the baseline moves forward. Empty without a baseline: a
+ *  session's first observation cannot tell its own writes from earlier ones. */
+export declare function shellWrittenFiles(root: string, sessionId: string | undefined, agentId?: string): string[];

package/dist/core/shellwrites.js

@@ -0,0 +1,131 @@
+/** Files a shell command wrote.
+ *
+ * Pre-edit grounding keys on the host's edit tools (Edit/Write/apply_patch).
+ * An agent that edits through the shell — a `python` heredoc, `sed -i`, `perl
+ * -pi`, a PowerShell `Set-Content` — never passes through them, so the file it
+ * changed arrives with no grounding at all. The shell tool's post-execution
+ * hook sees every command, but not what the command touched; parsing arbitrary
+ * shell for write targets is guesswork.
+ *
+ * Instead: fingerprint the working tree's dirty files (`git status`, then
+ * mtime+size) per session, repository and agent. A prompt and every tool call refresh
+ * the fingerprint; after a shell command, a dirty file whose fingerprint moved
+ * was written by that command. Deterministic, shell-agnostic, and bounded by the
+ * dirty set (never a tree walk). Any failure yields no files — never an error. */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Dirty paths fingerprinted; beyond it the rest are ignored (a vendored
+ *  untracked tree must not make every command slow). */
+const MAX_PATHS = 2000;
+/** Hunch's own state: written by the hook itself and by capture tools. */
+const OWN_STATE = /^\.hunch(?:-cache)?\//;
+/** Concurrent subagents share the session but not their commands: each keeps
+ *  its own baseline, keyed by its agent id (hashed with the rest, never kept
+ *  raw) like the pre-edit dedupe. No agent id keeps the session's baseline. */
+function snapshotFile(root, sessionId, agentId) {
+    const key = createHash("sha256").update(`${sessionId}\u0000${root}${agentId ? `\u0000${agentId}` : ""}`).digest("hex").slice(0, 24);
+    // Same directory as the session injection cache: its sweep drops stale files.
+    return join(tmpdir(), "hunch-hookcache", `shell-${key}.json`);
+}
+/** Repo-relative dirty paths (tracked changes and untracked files), NUL-safe. */
+function dirtyPaths(root) {
+    let raw;
+    try {
+        raw = execFileSync("git", ["-C", root, "status", "--porcelain=v1", "-z", "--untracked-files=all"], {
+            encoding: "utf8",
+            timeout: 2_000,
+            maxBuffer: 8_000_000,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+        });
+    }
+    catch {
+        return null;
+    }
+    // Porcelain paths are relative to the git toplevel, which can sit above the
+    // Hunch root (a package inside a monorepo): re-relativize, drop the outside.
+    let prefix = "";
+    try {
+        prefix = execFileSync("git", ["-C", root, "rev-parse", "--show-prefix"], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    const fields = raw.split("\u0000");
+    for (let i = 0; i < fields.length && out.length < MAX_PATHS; i++) {
+        const entry = fields[i];
+        if (entry.length < 4)
+            continue;
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path.startsWith(prefix))
+            out.push(path.slice(prefix.length));
+        // A rename/copy entry is followed by its source path.
+        if (status.includes("R") || status.includes("C"))
+            i++;
+    }
+    return out;
+}
+function fingerprint(root) {
+    const paths = dirtyPaths(root);
+    if (!paths)
+        return null;
+    const fp = {};
+    for (const p of paths) {
+        if (OWN_STATE.test(p))
+            continue;
+        try {
+            const st = statSync(join(root, p));
+            if (st.isFile())
+                fp[p] = `${st.mtimeMs}:${st.size}`;
+        }
+        catch { /* deleted: nothing to ground */ }
+    }
+    return fp;
+}
+function load(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function save(file, fp) {
+    try {
+        mkdirSync(join(tmpdir(), "hunch-hookcache"), { recursive: true });
+        writeFileSync(file, JSON.stringify(fp));
+    }
+    catch { /* the next refresh retries */ }
+}
+/** Record the working tree as it stands, so later shell writes are measured
+ *  from here (a prompt, or any tool call that is not a shell command). */
+export function refreshShellBaseline(root, sessionId, agentId) {
+    if (!sessionId)
+        return;
+    const fp = fingerprint(root);
+    if (fp)
+        save(snapshotFile(root, sessionId, agentId), fp);
+}
+/** Repo-relative files the shell command that just ran wrote (created or
+ *  modified), and the baseline moves forward. Empty without a baseline: a
+ *  session's first observation cannot tell its own writes from earlier ones. */
+export function shellWrittenFiles(root, sessionId, agentId) {
+    if (!sessionId)
+        return [];
+    const file = snapshotFile(root, sessionId, agentId);
+    const before = load(file);
+    const now = fingerprint(root);
+    if (!now)
+        return [];
+    save(file, now);
+    if (!before)
+        return [];
+    return Object.keys(now).filter((p) => before[p] !== now[p]).sort();
+}
+//# sourceMappingURL=shellwrites.js.map