@davesheffer/hunch 1.41.5 → 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/docanchors.js

@@ -1,4 +1,5 @@
 import { currentForTopic, rejectedForTopic } from "./topics.js";
+import { normalizeEol } from "./eol.js";
 const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
 /** Expand the leading whitespace of a line to columns. A tab advances to the
  *  NEXT 4-column tab stop (CommonMark), not a flat 4 columns: after two
@@ -238,7 +239,7 @@ export function parseDocAnchors(text) {
     // a live, pinned anchor. Normalizing both CRLF and lone CR once here keeps
     // fencedRanges/inlineSpanRanges/MARKER offsets consistent with each other
     // and with the line numbers reported below.
-    text = text.replace(/\r\n?/g, "\n");
+    text = normalizeEol(text);
     const out = [];
     const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
     MARKER.lastIndex = 0;

package/dist/core/eol.d.ts

@@ -0,0 +1,10 @@
+/** Canonical line endings for parsers that do not expose source offsets. */
+export declare function normalizeEol(text: string): string;
+/** Remove the CR retained by split("\n") without changing source offsets. */
+export declare function lineContent(line: string): string;
+/** Read logical lines while keeping offsets in the original UTF-16 source. */
+export declare function sourceLines(text: string): Generator<{
+    content: string;
+    start: number;
+    end: number;
+}>;

package/dist/core/eol.js

@@ -0,0 +1,23 @@
+/** Canonical line endings for parsers that do not expose source offsets. */
+export function normalizeEol(text) {
+    return text.replace(/\r\n?|\n/g, "\n");
+}
+/** Remove the CR retained by split("\n") without changing source offsets. */
+export function lineContent(line) {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+/** Read logical lines while keeping offsets in the original UTF-16 source. */
+export function* sourceLines(text) {
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "\r" && text[i] !== "\n")
+            continue;
+        const end = i;
+        if (text[i] === "\r" && text[i + 1] === "\n")
+            i++;
+        yield { content: text.slice(start, end), start, end };
+        start = i + 1;
+    }
+    yield { content: text.slice(start), start, end: text.length };
+}
+//# sourceMappingURL=eol.js.map

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/groundingMerge.js

@@ -20,15 +20,15 @@
  */
 import { execFileSync } from "node:child_process";
 import { parseGroundingCounts, stripCountsMatch, renderCountsMatch } from "./groundingLag.js";
-// `\r?\n` (not a bare `\n`) throughout: on a CRLF worktree every diff3 marker
-// line is itself `\r\n`-terminated, and a bare `\n` fails to match ANY of
-// them. `^...$` with /m anchor each marker at its own line start rather than
+import { normalizeEol } from "./eol.js";
+// The entry point normalizes EOL before matching. `^...$` with /m anchors
+// each marker at its own line start rather than
 // requiring a specific preceding/following literal newline, so a hunk whose
 // ours or theirs side is EMPTY (one side deleted the line, the other edited
 // it) still matches — with a literal `\n` requirement there, git's real
 // output for that shape has no such newline to match, so the whole hunk
 // silently fails to match at all.
-const CONFLICT_RE = /^<<<<<<< ours\r?\n([\s\S]*?)^\|\|\|\|\|\|\| base\r?\n[\s\S]*?^=======\r?\n([\s\S]*?)^>>>>>>> theirs[^\n]*\r?\n?/gm;
+const CONFLICT_RE = /^<<<<<<< ours\n([\s\S]*?)^\|\|\|\|\|\|\| base\n[\s\S]*?^=======\n([\s\S]*?)^>>>>>>> theirs[^\n]*\n?/gm;
 /** `null` when the hunk isn't confined to the counts sentence; otherwise the
  *  resolved sentence text, with each field taken as max(ours, theirs). */
 function resolveCountsOnlyHunk(ours, theirs) {
@@ -52,8 +52,10 @@ function resolveCountsOnlyHunk(ours, theirs) {
 export function resolveGroundingConflicts(diff3Text) {
     if (!diff3Text.includes("<<<<<<< ours"))
         return { conflict: false, text: diff3Text };
+    const eol = diff3Text.includes("\r\n") ? "\r\n" : diff3Text.includes("\r") ? "\r" : "\n";
+    const normalized = normalizeEol(diff3Text);
     let allResolved = true;
-    const resolved = diff3Text.replace(CONFLICT_RE, (whole, ours, theirs) => {
+    const resolved = normalized.replace(CONFLICT_RE, (whole, ours, theirs) => {
         const merged = resolveCountsOnlyHunk(ours, theirs);
         if (merged === null) {
             allResolved = false;
@@ -66,7 +68,7 @@ export function resolveGroundingConflicts(diff3Text) {
     // marker survives, this is a real conflict, full stop.
     if (!allResolved || resolved.includes("<<<<<<< ours"))
         return { conflict: true, text: diff3Text };
-    return { conflict: false, text: resolved };
+    return { conflict: false, text: eol === "\n" ? resolved : resolved.replace(/\n/g, eol) };
 }
 /** Run `git merge-file --diff3` on real files and resolve the result.
  *  `write: null` means git itself errored (e.g. one side is binary) — never

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[];