@davesheffer/hunch 1.41.6 → 1.43.0

package/dist/cli/index.js

@@ -43,13 +43,13 @@ import { isParserLoadError, loadNativeTreeSitter } from "../extractors/nativeTre
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
-import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatus, mergeRangeChanges, commitsExist } from "../extractors/git.js";
+import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeSubjects, revExists, revParse, commitAndPushHunch, pullHunchStatus, syncExistingHunch, gitUntrackCached, gitCommonDir, checkoutCommonDir, separateGitDirCandidate, separateGitDirLink, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatus, mergeRangeChanges, commitsExist } from "../extractors/git.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
 import { orphanedCommitDecisions, planCommitRepair, repairDecisionCommit, pickRewrite, commitRepairReviewHash, mergeRewrites, firstFor, deadRewrites, resolvedRewriteIds, withoutDropped, addDropped, withheldForUnresolvableTo } from "../core/commitrepair.js";
 import { readPendingRepairs, writePendingRepairs, readDroppedRepairs, writeDroppedRepairs, readActivePendingRepairs, withheldRewrites } from "../core/repairqueue.js";
 import { planPolicyRepair, repairPolicySpec } from "../constitution/repairPolicies.js";
-import { writeTeamConfig, ensureTeamOverlay, readTeamConfig, safeGitUrl, safeTeamRef, overlayMatchesTeamRemote, advertisedTeamRemoteContract, boundedTeamGitEnv, cloneValidatedTeamOverlay, explicitTeamRemoteContract, teamRemoteContract } from "../integrations/team.js";
+import { writeTeamConfig, ensureTeamOverlay, readTeamConfig, isTeamStoreTrusted, teamWiringConsented, trustTeamStore, teamTrustFile, untrustedTeamStoreMessage, safeGitUrl, safeTeamRef, overlayMatchesTeamRemote, advertisedTeamRemoteContract, boundedTeamGitEnv, cloneValidatedTeamOverlay, explicitTeamRemoteContract, teamRemoteContract } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
 import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
@@ -62,6 +62,8 @@ import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS, upgradeManagedGitignore, describeGitignoreUpgrade } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd, renderHunchSection } from "../integrations/claudemd.js";
+import { HOOK_REMINDER } from "../core/hookText.js";
+import { measureFootprint } from "../core/footprint.js";
 import { classifyGroundingBlock, describeGroundingFreshness } from "../core/groundingLag.js";
 import { mergeGroundingFile } from "../core/groundingMerge.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
@@ -89,16 +91,17 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 import { isHumanConfirmed } from "../core/strictgate.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
-import { injectionMode, resetSessionInjections } from "../core/hookcache.js";
+import { clearTaskSelection, injectionMode, loadTaskSelection, resetSessionInjections, saveTaskSelection, taskSelectionEnabled } from "../core/hookcache.js";
+import { isBareFollowUp, isFilterableSelectionId, liveSelectionRecords, selectForTask } from "../core/taskSelection.js";
 import { recordServed, servedSummary } from "../core/served.js";
-import { recordTaskDelivery, reportActivity, reportHash, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
+import { readTaskReport, recordTaskDelivery, reportActivity, reportHash, reportPresentationEnabled, unseenLessons } from "../core/taskReport.js";
 import { snapshotDeliveredRecords } from "../core/taskReportEvidence.js";
 import { renderRecalledLine } from "../core/taskReportRender.js";
-import { closeHookTask, hookReportTaskId, nativeHookCwd, settleHookSession, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
+import { closeHookTask, hookReportTaskId, isNotificationPrompt, nativeHookCwd, settleHookSession, startHookReport, stopHookReport, observeHookDenial } from "../core/taskReportHook.js";
 import { persistTaskRecord } from "../core/taskRecord.js";
 import { recordHookObservation } from "../core/hookObservations.js";
 import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
-import { PIPELINE_LOOP, armExecutionObligations, beforeEditProbeVerdict, compileExecutableProbes, environmentExecutableProbes, environmentExecutionObligations, executionObligationBrief, isProductPath, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, proofCheckpoint, savePipelineState, stopVerdict, unverifiedNag, } from "../core/pipeline.js";
+import { PIPELINE_LOOP, armExecutionObligations, beforeEditProbeVerdict, compileExecutableProbes, environmentExecutableProbes, environmentExecutionObligations, executionObligationBrief, isProductPath, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, proofCheckpoint, savePipelineState, stopVerdict, onLessonsDelivered, lessonReminder, unverifiedNag, } from "../core/pipeline.js";
 import { draftDuplicateOf, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
 import { loadGoldenSet, evaluateRetrieval, evaluateTraversalLift } from "../eval/harness.js";
@@ -116,6 +119,9 @@ import { buildMadrManifest, writeMadrManifest, refreshMadrCorpus } from "../inte
 import { pendingEscalations, policyEscalations, commitRepairEscalations, actionableEscalations, escalationHeadline } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
+import { pathMatchesGlob } from "../core/glob.js";
+import { SIBLING_HEADING, functionBodyHash, siblingGrounding } from "../core/siblingfix.js";
+import { refreshShellBaseline, shellWrittenFiles } from "../core/shellwrites.js";
 import { compareCandidates } from "../core/compare.js";
 import { compareCodeUnits } from "../core/canonicalOrder.js";
 import { MAX_LANDSCAPE_REFRESH_REVISIONS, planLandscapeAdoption, } from "../core/landscapeAdoption.js";
@@ -246,7 +252,8 @@ function openTeamStore(root, opts = {}) {
     const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
     const teamFile = join(hunchPaths(root).hunch, "team.json");
     const teamAdvertised = !explicitOverlay && existsSync(teamFile);
-    if (teamAdvertised && !readTeamConfig(root)) {
+    const advertisedTeam = teamAdvertised ? readTeamConfig(root) : null;
+    if (teamAdvertised && !advertisedTeam) {
         throw new Error(".hunch/team.json is invalid or unsafe; refusing to fall back to public memory");
     }
     const teamWired = ensureTeamOverlay(root);
@@ -255,12 +262,16 @@ function openTeamStore(root, opts = {}) {
     const overlayWarning = store.overlayResolutionWarning(explicitOverlay && existsSync(teamFile));
     if (overlayWarning)
         console.error(`[hunch] ⚠ ${overlayWarning}`);
-    if (teamAdvertised && (store.mode !== "shared"
+    if (advertisedTeam && (store.mode !== "shared"
         || !store.privateDir
         || !existsSync(store.privateDir)
+        || !teamWiringConsented(root, advertisedTeam, store.privateDir)
         || !overlayMatchesTeamRemote(root, dirname(store.privateDir)))) {
+        const consented = !!store.privateDir && teamWiringConsented(root, advertisedTeam, store.privateDir);
         store.close();
         openStore = null;
+        if (!consented && !isTeamStoreTrusted(root, advertisedTeam))
+            throw new Error(untrustedTeamStoreMessage(advertisedTeam));
         throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to read or write another graph");
     }
     // Short-lived CLI processes need the same live edge as the long-lived MCP
@@ -487,7 +498,7 @@ program
     // Worktree-seamless: register any configured overlay at the git common dir so EVERY
     // worktree of this repo auto-discovers it (also backfills pre-0.32 single-worktree setups),
     // and note when we're initializing inside a linked worktree (memory is shared, not separate).
-    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private")) {
+    if (ensureSharedOverlayPointer(root, store.privateDir, store.privateAutoCommit, store.mode === "shared" ? "shared" : "private", true)) {
         console.log(`  ✓ private overlay registered at the git common dir — shared by every worktree of this repo`);
     }
     for (const line of sharedHooksNote(root, installs))
@@ -1014,15 +1025,18 @@ function beginFreshOverlaySetup(root, dest, existingLocal, includeHook) {
     const localFile = join(hunchPaths(root).hunch, "local.json");
     const teamFile = join(hunchPaths(root).hunch, "team.json");
     const codeGitignore = join(root, ".gitignore");
-    const commonDir = gitCommonDir(root);
+    const commonDir = checkoutCommonDir(root) || separateGitDirCandidate(root)?.gitDir || "";
     const sharedPointer = commonDir ? join(commonDir, "hunch", "local.json") : "";
+    // Registering the shared pointer can also claim a separate git dir (claimSeparateGitDir),
+    // writing its checkout back-link beside the pointer; a failed setup must not leave it.
+    const backLink = commonDir ? separateGitDirLink(commonDir) : "";
     const configuredHooks = includeHook ? hooksDir(root) : "";
     const hookDir = configuredHooks ? (isAbsolute(configuredHooks) ? configuredHooks : join(root, configuredHooks)) : "";
     // Setup installs post-commit AND post-merge together, so both must be in the
     // ledger — restoring one while leaving the other pointing at a just-deleted
     // overlay is not a rollback.
     const hookFiles = hookDir ? [join(hookDir, "post-commit"), join(hookDir, "post-merge")] : [];
-    const paths = [localFile, codeGitignore, teamFile, ...(sharedPointer ? [sharedPointer] : []), ...hookFiles];
+    const paths = [localFile, codeGitignore, teamFile, ...(sharedPointer ? [sharedPointer, backLink] : []), ...hookFiles];
     const snapshots = new Map(paths.map((path) => [path, setupPathSnapshot(path)]));
     const parentExisted = new Map([
         [dirname(localFile), existsSync(dirname(localFile))],
@@ -1041,7 +1055,7 @@ function beginFreshOverlaySetup(root, dest, existingLocal, includeHook) {
         markLocalWrite: () => mark(localFile),
         markGitignoreWrite: () => mark(codeGitignore),
         markTeamWrite: () => mark(teamFile),
-        markSharedPointerWrite: () => mark(sharedPointer),
+        markSharedPointerWrite: () => { mark(backLink); mark(sharedPointer); },
         markHookWrite: () => hookFiles.forEach(mark),
         // Migration is a one-way ownership handoff. Once public records have been
         // durably copied into this clone, a later setup failure may restore routing
@@ -1070,6 +1084,74 @@ function beginFreshOverlaySetup(root, dest, existingLocal, includeHook) {
         },
     };
 }
+/** `hunch shared --trust`: the one explicit step that lets this machine auto-wire
+ *  the store a committed team.json advertises. Shows the exact URL being trusted. */
+function trustAdvertisedTeamStore(root, dir, opts) {
+    if (dir || opts.repo || opts.sync || opts.migrate) {
+        return fail("--trust takes no directory and cannot be combined with --repo, --sync, or --migrate");
+    }
+    if (process.env.HUNCH_PRIVATE_DIR?.trim()) {
+        return fail("HUNCH_PRIVATE_DIR is set, so .hunch/team.json is bypassed; unset it before trusting the team store");
+    }
+    const team = readTeamConfig(root);
+    if (!team) {
+        return fail(existsSync(join(hunchPaths(root).hunch, "team.json"))
+            ? ".hunch/team.json is invalid or unsafe; refusing to trust it"
+            : "no .hunch/team.json in this repository; nothing to trust");
+    }
+    // Consent persists only after a successful connect: openTeamStore reads the trust
+    // entry, so it is written first and restored to the exact prior state on failure.
+    // The connect can also write routing BEFORE it fails (this checkout's pointer, the
+    // registered common-dir pointer, a separate git dir's back-link), and a registered
+    // pointer is itself consent, so those are snapshotted and restored too — otherwise
+    // "trust was NOT recorded" would be false in substance.
+    const priorTrust = isTeamStoreTrusted(root, team);
+    const commonDir = checkoutCommonDir(root) || separateGitDirCandidate(root)?.gitDir || "";
+    const routing = [
+        join(hunchPaths(root).hunch, "local.json"),
+        ...(commonDir ? [join(commonDir, "hunch", "local.json"), separateGitDirLink(commonDir)] : []),
+    ];
+    const routingBefore = routing.map((path) => [path, setupPathSnapshot(path)]);
+    const undoTrust = trustTeamStore(root, team);
+    let opened;
+    try {
+        opened = openTeamStore(root);
+    }
+    catch (error) {
+        let reverted = true;
+        for (const [path, before] of routingBefore) {
+            try {
+                restoreSetupPath(path, before);
+            }
+            catch {
+                reverted = false;
+            }
+        }
+        try {
+            undoTrust();
+        }
+        catch {
+            reverted = false;
+        }
+        // The undo only removes THIS invocation's own entry: a trust entry this checkout
+        // already had stays, and a concurrent process may have recorded (and kept) its own.
+        const stillConsented = reverted && isTeamStoreTrusted(root, team);
+        return fail(`could not connect to the team store: ${error instanceof Error ? error.message : String(error)}\n` +
+            (stillConsented
+                ? priorTrust
+                    ? `  · this checkout's earlier trust entry is kept (${teamTrustFile()})\n`
+                    : `  · trust for this checkout was recorded by another process meanwhile (${teamTrustFile()})\n`
+                : reverted
+                    ? `  · trust was NOT recorded for this checkout (${teamTrustFile()} and its store pointers are unchanged)\n`
+                    : `  · trust could not be fully rolled back: remove this checkout's entry from ${teamTrustFile()} and its .hunch/local.json store pointer\n`) +
+            "  · retry: `hunch shared --trust` once the store is reachable");
+    }
+    console.log(`✓ trusted the team memory store on this machine → ${team.shared_repo}`);
+    const { store, teamWired } = opened;
+    console.log(teamWired
+        ? `  ✓ connected to the team's shared memory store → ${teamWired}`
+        : `  · already connected → ${store.privateDir}`);
+}
 function configureOverlay(dir, opts, mode) {
     let freshSetup = null;
     let setupComplete = false;
@@ -1077,6 +1159,8 @@ function configureOverlay(dir, opts, mode) {
         const root = findRoot();
         const paths = hunchPaths(root);
         const commandName = mode === "private" ? "private" : "shared";
+        if (opts.trust)
+            return trustAdvertisedTeamStore(root, dir, opts);
         // A repository URL reaches Git before the overlay is trusted in BOTH modes.
         // Keep private split stores private by omitting team.json, not by weakening the
         // clone transport gate: credentials stay in normal Git helpers and every setup
@@ -1261,6 +1345,10 @@ function configureOverlay(dir, opts, mode) {
                 return fail("could not select one canonical branch for the shared memory repository");
             freshSetup?.markTeamWrite();
             writeTeamConfig(root, { shared_repo: opts.repo, shared_ref: sharedRef });
+            // The author typed this URL, which is the consent teammates give with --trust.
+            const published = readTeamConfig(root);
+            if (published)
+                trustTeamStore(root, published);
             // Bind the graph epoch immediately, in clone-local Git metadata. Waiting
             // until the next command would let a coherent team.json+origin repoint
             // relabel this clone after setup but before its first normal open.
@@ -1276,9 +1364,12 @@ function configureOverlay(dir, opts, mode) {
         // only an absolute path survives the move. Lives under .git/ (never tracked; nothing to ignore).
         let worktreeNote = "";
         freshSetup?.markSharedPointerWrite();
-        if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit, mode)) {
+        if (ensureSharedOverlayPointer(root, hunchDir, !!opts.autoCommit, mode, true)) {
             worktreeNote = "  ✓ registered in the git common dir — shared by every worktree of this repo, on any branch\n";
         }
+        else {
+            worktreeNote = "  ⚠ could not register the overlay in this checkout's git common dir, so Hunch will not use .hunch/local.json here; set HUNCH_PRIVATE_DIR to this overlay instead\n";
+        }
         // 4) route post-commit synthesis to the overlay (local hook, never committed)
         let hookNote = "";
         if (opts.hook && isGitRepo(root)) {
@@ -1393,6 +1484,7 @@ program
     .option("--no-auto-commit", "DON'T auto commit+push the overlay after each capture (default: ON — fully automated two-way sync)")
     .option("--sync", "flush the configured overlay store now (git add+commit+push)")
     .option("--migrate", "ONE-TIME: move this repo's EXISTING public .hunch memory into the shared overlay, then make the public repo code-only")
+    .option("--trust", "trust the shared store advertised in the committed .hunch/team.json on this machine, then connect to it")
     .action((dir, opts) => configureOverlay(dir, opts, "shared"));
 // ---- worktree (one-command worktree wired into Hunch) ----------------------
 program
@@ -1427,7 +1519,7 @@ program
     if (!opts.share) {
         shareNote = `  · --no-share — the worktree will NOT see private memory`;
     }
-    else if (overlay && ensureSharedOverlayPointer(root, overlay, autoCommit, overlayMode)) {
+    else if (overlay && ensureSharedOverlayPointer(root, overlay, autoCommit, overlayMode, true)) {
         shareNote = `  ✓ memory shared via the git common dir — this worktree sees the same decisions / bugs / constraints`;
     }
     else if (overlay) {
@@ -4452,6 +4544,7 @@ program
     .option("--profile <profile>", "delivery role: builder, reviewer, or architect", "builder")
     .option("--as-of <ref>", "time-travel: assemble the slice as it stood at a commit/tag/branch")
     .option("--task <id>", "retain the exact context delivery for this task's contribution report")
+    .option("--include <kinds>", "opt-in extras (comma list): recent-tasks,project-dna — omitted by default to keep the brief small")
     .action(async (target, opts) => {
     if (!DELIVERY_PROFILES.includes(opts.profile)) {
         return fail(`--profile must be one of: ${DELIVERY_PROFILES.join(", ")}`);
@@ -4477,6 +4570,27 @@ program
     // receipts matching the target — the same slice and render as hunch_context.
     const slice = asOf ? null : store.stateSlice(target);
     const stateGrounding = slice ? stateSupplements(slice, target) : [];
+    // Both extras below cost brief tokens (and, for DNA/recent-tasks selection, extra
+    // latency) — opt-in only via --include, omitted from the default brief.
+    // Accept the MCP spelling (recent_tasks) too, so a name copied from the tool schema works.
+    const include = opts.include ? opts.include.split(",").map((s) => s.trim().replace(/_/g, "-")).filter(Boolean) : [];
+    const unknownInclude = include.filter((k) => k !== "recent-tasks" && k !== "project-dna");
+    if (unknownInclude.length)
+        return fail(`--include accepts recent-tasks, project-dna (got: ${unknownInclude.join(", ")})`);
+    const recentTasks = (asOf || !include.includes("recent-tasks"))
+        ? []
+        : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, opts.task ?? null, target)), target);
+    let dnaSupplement = null;
+    if (!asOf && include.includes("project-dna")) {
+        try {
+            dnaSupplement = projectDnaDeliverySupplement(discoverProjectDna(root, "HEAD"));
+        }
+        catch {
+            // Same graceful behavior as hunch_context: a missing/unreadable Git checkout
+            // must not break the CLI brief; the dedicated `hunch project-dna` command
+            // reports the exact derivation error when a caller needs diagnostics.
+        }
+    }
     if (empty && !asOf && opts.task) {
         const resolved = store.rankedSearch(target, 8).map(hit => ({ hit, record: store.resolve(hit.ref)?.record }));
         ctx = { ...ctx,
@@ -4512,7 +4626,7 @@ program
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
         profile: opts.profile,
-        supplements: [...stateGrounding, ...(asOf ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, opts.task ?? null, target)), target))],
+        supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...recentTasks],
     });
     process.stdout.write(envelope.text);
     if (opts.task) {
@@ -4856,10 +4970,39 @@ program
         // Verification pipeline (delivery enforced, not hoped for — see core/pipeline.ts).
         // PostToolUse records facts; Stop gates on them. Both are pipeline-only events,
         // handled before the grounding dispatch below.
-        if ((evt.hook_event_name === "PostToolUse" || evt.hook_event_name === "PostToolUseFailure") && evt.session_id && pipelineEnabled()) {
+        const postTool = evt.hook_event_name === "PostToolUse" || evt.hook_event_name === "PostToolUseFailure" ? evt.hook_event_name : null;
+        // A shell command can edit files without the edit tools ever firing: ground
+        // what it wrote now. Every other tool call just moves the baseline.
+        let shellGround = "";
+        if (postTool) {
+            // Fail-open on its own: a grounding error must not cost the pipeline
+            // bookkeeping below (a missed check would wrongly hold the Stop gate).
+            try {
+                if (evt.tool_name === "Bash" || evt.tool_name === "PowerShell") {
+                    const written = shellWrittenFiles(root, evt.session_id, evt.agent_id);
+                    if (written.length) {
+                        const opened = openTeamStore(root, { requireFreshTeamMemory: firmness === "strict" });
+                        store = opened.store;
+                        // Same rule as the pre-edit path: strict never grounds from stale team rules.
+                        const stale = firmness === "strict" && opened.teamPullStatus
+                            && opened.teamPullStatus !== "updated" && opened.teamPullStatus !== "current";
+                        if (!stale)
+                            shellGround = shellWriteGrounding(root, store, provider, evt, written);
+                    }
+                }
+                else {
+                    refreshShellBaseline(root, evt.session_id, evt.agent_id);
+                }
+            }
+            catch {
+                shellGround = "";
+            }
+        }
+        if (postTool && evt.session_id && pipelineEnabled()) {
             let st = loadPipelineState(evt.session_id);
             const before = st;
             let activity = null;
+            let lessonNote = "";
             if (/^(Edit|Write|MultiEdit)$/.test(evt.tool_name ?? "")) {
                 // A Codex apply_patch touches every file it lists (and each Move-to
                 // destination); the Stop gate must see all of them, not only the first.
@@ -4876,6 +5019,13 @@ program
                 const command = String(evt.tool_input?.command ?? "");
                 st = onCommand(st, command, evt.tool_outcome);
                 activity = { kind: "command", command };
+                // A command that both wrote the file and ran a check just received the
+                // lesson itself; the follow-up waits for the next check.
+                if (!shellGround) {
+                    const followUp = lessonReminder(st, command, (l) => functionBodyHash(root, l.file, l.symbol));
+                    st = followUp.state;
+                    lessonNote = followUp.reminder;
+                }
             }
             else if (evt.tool_name === "Skill") {
                 st = onSkill(st, String(evt.tool_input?.skill ?? ""));
@@ -4885,11 +5035,19 @@ program
                 const checkpoint = proofCheckpoint(before, st, activity);
                 st = checkpoint.state;
                 savePipelineState(evt.session_id, st);
-                if (checkpoint.reminder)
-                    emitContext(provider, evt.hook_event_name, checkpoint.reminder);
+                const post = [shellGround, lessonNote, checkpoint.reminder].filter(Boolean).join("\n\n");
+                if (post)
+                    emitContext(provider, postTool, post);
                 return;
             }
             savePipelineState(evt.session_id, st);
+            if (shellGround)
+                emitContext(provider, postTool, shellGround);
+            return;
+        }
+        if (postTool) {
+            if (shellGround)
+                emitContext(provider, postTool, shellGround);
             return;
         }
         if (evt.hook_event_name === "Stop") {
@@ -4922,21 +5080,33 @@ program
             // When the prompt reads like a correction ("no / that's wrong / never X"),
             // nudge the agent to PERSIST it as an enforced constraint (Never Twice) —
             // not just obey it this once and forget it next session.
+            // Shell writes are measured from the start of each prompt.
+            refreshShellBaseline(root, evt.session_id);
             const isCorrection = looksLikeCorrection(evt.prompt);
-            let text = isCorrection ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
-            // Payloads that must NEVER be deduped away. The dedup key hashes CONTENT, and
-            // this content is assembled from constants — so two back-to-back corrections
-            // produce byte-identical text and the second (usually the escalating one) was
-            // silently swallowed, never becoming an enforced rule. Same for the unverified
-            // nag, which is documented as the one nag that must repeat but rode the same
-            // deduped payload and so fired once per streak.
-            let mustDeliver = isCorrection;
+            // Once per session is enough for the bare availability reminder — repeating it
+            // every prompt burns context for zero information (dec_244397d920). It is deduped
+            // on its OWN key: hashed together with the per-prompt task report (a new ID each
+            // prompt) it was re-sent on every prompt. A correction is never deduped: two
+            // back-to-back corrections are byte-identical, and the second (usually the
+            // escalating one) must still become an enforced rule. Neither is the unverified
+            // nag below, the one nag that must repeat.
+            const parts = [];
+            // Always stamp the key, so a correction that delivers the reminder counts as
+            // this session's one delivery.
+            const reminderDue = injectionMode(evt.session_id, "prompt-reminder", HOOK_REMINDER) === "full";
+            if (isCorrection)
+                parts.push(`${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}`);
+            else if (reminderDue)
+                parts.push(HOOK_REMINDER);
             // Reporting failure must not suppress the existing correction/policy reminder.
             try {
                 const report = startHookReport(root, provider, evt);
                 if (report) {
-                    text += `\n\n${report}`;
-                    mustDeliver = true;
+                    parts.push(report);
+                    store ??= new HunchStore(paths);
+                    const selected = promptTaskSelection(root, store, provider, evt);
+                    if (selected)
+                        parts.push(selected);
                 }
             }
             catch { /* passive reporting remains fail-open */ }
@@ -4957,16 +5127,12 @@ program
                 const st = onPrompt(loadPipelineState(evt.session_id));
                 savePipelineState(evt.session_id, st);
                 if (!st.verifyAfterEdit || st.obligations.some((item) => item.status !== "satisfied")) {
-                    text += `\n\n${unverifiedNag(st)}`;
-                    mustDeliver = true;
+                    parts.push(unverifiedNag(st));
                 }
             }
-            // Once per session is enough for the bare availability reminder — repeating it
-            // every prompt burns context for zero information (dec_244397d920). Only that
-            // ambient case is deduped.
-            if (!mustDeliver && injectionMode(evt.session_id, "prompt-reminder", text) === "delta")
+            if (!parts.length)
                 return;
-            emitContext(provider, "UserPromptSubmit", text);
+            emitContext(provider, "UserPromptSubmit", parts.join("\n\n"));
             return;
         }
         if (evt.hook_event_name === "PreCompact") {
@@ -4991,6 +5157,12 @@ program
             // would cross worktrees; stay silent instead of guessing which side is right.
             if ((provider === "claude" || provider === "codex") && evt.cwd !== undefined && !routedCwd)
                 return;
+            // The prompt's baseline is the session's, not this agent's: without its
+            // own, a first tool call that is a shell write would go ungrounded.
+            // Without an agent id the key would be the SESSION's baseline, and
+            // refreshing it here could swallow a parent write not yet grounded.
+            if (evt.agent_id)
+                refreshShellBaseline(root, evt.session_id, evt.agent_id);
             const s = new HunchStore(paths);
             try {
                 const clip1 = (text, max) => {
@@ -5081,10 +5253,11 @@ program
             return;
         }
         if (evt.hook_event_name === "SessionStart") {
-            // A compact-resume means everything injected so far was just summarized
-            // away — the dedup map must forget it delivered anything, or the rest of
-            // the session gets delta one-liners against grounding that is gone.
-            if (evt.source === "compact")
+            // A compact-resume (or a cleared context that keeps its session id) means
+            // everything injected so far is gone — the dedup map must forget it
+            // delivered anything, or the rest of the session gets delta one-liners
+            // against grounding and task rules the agent no longer has.
+            if (evt.source === "compact" || evt.source === "clear")
                 resetSessionInjections(evt.session_id);
             // Orientation at the moment it matters: what just happened + what's next,
             // straight from the graph — the agent sits down already knowing where it
@@ -5108,7 +5281,7 @@ program
                 // in the overlay. Private mode stays public-only: session transcripts travel
                 // further than a terminal.
                 const decisions = s.advisoryRecs("decisions");
-                const { recent, roadmap, pendingReview } = nowData(decisions, 3);
+                const { pendingReview } = nowData(decisions, 3);
                 const escalations = pendingEscalations(decisions);
                 escalations.push(...premiseEscalations(decisions, { now: new Date().toISOString(), exists: (p) => existsSync(join(paths.root, p)) }));
                 // liveness checked against the full store even in private mode — a
@@ -5145,17 +5318,6 @@ program
                 }
                 const L = [];
                 L.push(`🧠 Hunch orientation — ${decisions.length} decision(s) in the graph.`);
-                if (recent.length) {
-                    L.push("Recent:");
-                    for (const r of recent)
-                        L.push(`  ${r.date} [${r.status}] ${r.title} (${r.id})`);
-                }
-                if (roadmap.length) {
-                    L.push(`Roadmap (${roadmap.length} live proposed): ${roadmap.slice(0, 3).map((r) => (r.unconfirmed ? `${r.title} [unconfirmed, ${r.id}]` : r.title)).join(" · ")}${roadmap.length > 3 ? " · …" : ""}`);
-                    const unconfirmed = roadmap.filter((r) => r.unconfirmed).length;
-                    if (unconfirmed)
-                        L.push(`${unconfirmed} roadmap item(s) are unconfirmed agent testimony — the human confirms each with \`hunch review --confirm <id>${s.unified ? " --private" : ""}\`.`);
-                }
                 if (pendingReview > 0)
                     L.push(`${pendingReview} legacy un-vouched draft(s) — adopt as advisory memory with \`hunch adopt-drafts\` (new captures auto-trust).`);
                 if (actionableEsc.length) {
@@ -5183,6 +5345,13 @@ program
         }
         if (evt.hook_event_name !== "PreToolUse")
             return;
+        // A shell command's writes are measured from its own start: a file written
+        // before it (a parallel tool call, another process, a host that skipped the
+        // last PostToolUse) is not this command's to be blamed for.
+        if (evt.tool_name === "Bash" || evt.tool_name === "PowerShell") {
+            refreshShellBaseline(root, evt.session_id, evt.agent_id);
+            return;
+        }
         const targets = editTargets(root, evt.tool_input);
         // Nothing inside the repo → nothing for Hunch to say.
         if (!targets.length)
@@ -5250,115 +5419,10 @@ program
             }
         }
         // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
-        // Decision-grounding for PROSE (doc≠graph): a markdown target that declares
-        // <!-- hunch:topic … --> anchors gets each topic's CURRENT decision — the
-        // graph outranks the prose being edited, and a stale pin is called out inline.
-        let docGround = "";
-        if (/\.(md|mdx)$/i.test(target)) {
-            try {
-                docGround = renderDocGrounding(parseDocAnchors(readFileSync(abs, "utf8")), store.recs("decisions"));
-            }
-            catch { /* unreadable / not yet created — no doc grounding */ }
-        }
-        const ctx = store.assembleContext(target);
-        // Regression Guard (edit-time grounding): what an in-force decision retired
-        // from this file. No diff exists yet, so this is context — "don't re-add X" —
-        // not a block; the commit-time `hunch check` does the actual gating.
-        const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-        const recentTasks = taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
-        const hasContent = ctx.constraints.length ||
-            ctx.decisions.length ||
-            ctx.bugs.length ||
-            ctx.blast_radius.length ||
-            ctx.findings.length ||
-            ctx.landscape?.resources.length ||
-            ctx.landscape?.relationships.length ||
-            retired.length ||
-            recentTasks.length ||
-            docGround;
-        if (!hasContent)
+        const grounded = fileGrounding(root, store, provider, evt, target, abs);
+        if (!grounded)
             return; // no noise on files Hunch hasn't learned yet
-        const supplements = [
-            ...(retired.length ? [{
-                    id: "retired-code",
-                    kind: "retired-code",
-                    priority: 200,
-                    text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
-                }] : []),
-            ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
-            ...recentTasks,
-        ];
-        const envelope = buildDeliveryEnvelope(ctx, {
-            profile: "builder",
-            root,
-            symbols: store.recs("symbols"),
-            components: store.recs("components"),
-            decisionCorpus: store.recs("decisions"),
-            supplements,
-        });
-        const text = envelope.text.trim();
-        // Identical grounding already shown this session → one-line delta instead of
-        // the full 10-16KB block. Any record change re-sends the full text; the
-        // strict-gate deny path above never routes through this (dec_244397d920).
-        // Delivery receipts (dec_925f4bcaad): the ledger of what actually reached
-        // an agent. A full injection is a serve; a delta one-liner attests the
-        // earlier serve is still standing. Never throws, never blocks.
-        const receipts = (event) => recordServed(root, [
-            ...envelope.delivered.map((item) => ({
-                event,
-                kind: item.kind,
-                record_id: item.record_id,
-                target,
-                session_id: evt.session_id,
-                rank: item.rank,
-                delivery_reason: item.delivery_reason,
-                provenance_status: item.provenance_status,
-                token_cost: item.token_cost,
-                delivery_profile: envelope.profile,
-                ranking_policy: envelope.ranking_policy,
-            })),
-            // Delivered task lines are receipts too: they feed access-based recency.
-            ...envelope.supplements.filter((s) => s.kind === "recent-task" && s.delivered).map((s) => ({
-                event, kind: "tasks", record_id: s.id, target, session_id: evt.session_id,
-                rank: s.rank, delivery_reason: "supplemental", token_cost: s.token_cost,
-                delivery_profile: envelope.profile, ranking_policy: envelope.ranking_policy,
-            })),
-        ]);
-        const reportTaskId = hookReportTaskId(root, provider, evt);
-        // A new authoritative prompt gets its own full delivery. An earlier
-        // prompt's session-level delta cannot establish this task's receipt.
-        // A subagent reports to the prompt's task but starts with FRESH context:
-        // it never saw that grounding, so its dedup is scoped by its own agent
-        // identity (hashed — the raw agent_id is never retained in the key).
-        const agentKey = evt.agent_id ? `:${reportHash(evt.agent_id).slice(7, 19)}` : "";
-        // Dedup on the envelope's stable IDENTITY projection, never on the
-        // rendered block: serving the full text writes delivery receipts, and the
-        // next call's task ranking reads them back and moves the wording ("today"
-        // → "delivered today"), so hashing the presentation made this grounding
-        // self-invalidating and re-sent the full block for unchanged records.
-        if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}${agentKey}`, text, deliveryDedupeInput(envelope, supplements)) === "delta") {
-            receipts("refreshed");
-            emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${envelope.delivered.filter((item) => item.kind === "decisions").length} decision(s), ${envelope.delivered.filter((item) => item.kind === "constraints").length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
-            return;
-        }
-        receipts("served");
-        let reportNotice = "";
-        let recalled = null;
-        if (reportTaskId) {
-            try {
-                const snapshots = snapshotDeliveredRecords(store, envelope);
-                // The first time a lesson reaches this prompt's task, tell the USER in one
-                // line (systemMessage); repeats of the same revision stay silent.
-                recalled = reportPresentationEnabled(root) ? renderRecalledLine(unseenLessons(root, reportTaskId, snapshots)) : null;
-                const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots, undefined, target);
-                reportNotice = `\n\nHunch task ${reportTaskId} · delivery ${occurrence}. Inspect exact application references with hunch_report(task_id).`;
-            }
-            catch {
-                reportNotice = "\n\nTask report observation unavailable; this delivery's task contribution remains unverified.";
-                recalled = null;
-            }
-        }
-        emitContext(provider, "PreToolUse", text + reportNotice, recalled ?? undefined);
+        emitContext(provider, "PreToolUse", grounded.text, grounded.mode === "full" ? grounded.recalled ?? undefined : undefined);
     }
     catch (e) {
         // Never block an edit on a hook failure — and never go silent either: an
@@ -6551,6 +6615,24 @@ program
         return fail("push failed — no upstream, offline, or nothing to push.");
     console.log("✓ pushed the current branch to its remote.");
 });
+// ---- footprint (how much text Hunch injects into an agent's context) -------
+program
+    .command("footprint")
+    .description("Measure how much text Hunch injects into an agent's context — MCP tool list, hunch_context brief, grounding block, hook text — from the same code paths the product serves. Tokens are estimated as characters / 4.")
+    .option("--json", "emit the report (hunch.footprint/1) as JSON")
+    .option("--target <file>", "file to measure the hunch_context result for (default: the file most decisions cite)")
+    .action(async (opts) => {
+    const report = await measureFootprint(findRoot(), { target: opts.target });
+    if (opts.json)
+        return console.log(JSON.stringify(report, null, 2));
+    const width = Math.max(...report.surfaces.map((s) => s.id.length));
+    for (const s of report.surfaces)
+        console.log(`${s.id.padEnd(width)}  ${String(s.chars).padStart(7)}  ~${s.est_tokens}`);
+    console.log("\nNot measured in-process:");
+    for (const u of report.unmeasured)
+        console.log(`· ${u}`);
+    console.log(dim("\nTokens estimated as characters / 4, not a tokenizer."));
+});
 // ---- drift (doc≠graph detector; advisory + CI-gateable) -------------------
 program
     .command("drift")
@@ -6607,10 +6689,13 @@ program
     .command("grounding")
     .description("Check the committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions, hunch.mdc, hunch.md) against what the PUBLIC graph generates — direction-aware: counts that merely LAG a merge are reported, counts AHEAD of the store (a record never committed) or divergent prose fail. --refresh regenerates every existing doc from the public store (never the overlay union, never a doc the project lacks). Exits 1 on ahead/diverged unless refreshed.")
     .option("--refresh", "regenerate the existing grounding docs from the public store (what the post-merge hook and the release remedy run)")
+    .option("--force", "with --refresh: re-render even a block written by a newer Hunch template")
     .option("--json", "machine-readable verdicts")
     .option("--quiet", "print nothing on success")
     .action((opts) => {
     const root = findRoot();
+    if (opts.force && !opts.refresh)
+        console.error("hunch grounding: --force only applies with --refresh; checking without re-rendering.");
     // PUBLIC-ONLY by construction, exactly as the release gate and the freshness test
     // read it: HUNCH_PRIVATE_DIR at an empty overlay beats .hunch/local.json and the
     // shared pointer, so a dev machine with an overlay attached can never write union
@@ -6631,7 +6716,8 @@ program
                 return { doc: rel, verdict: { kind: "diverged", reason: "no managed HUNCH block" } };
             return { doc: rel, verdict: classifyGroundingBlock(committed, generated) };
         });
-        const refreshed = opts.refresh ? refreshExistingGrounding(root, store) : [];
+        const refreshed = opts.refresh ? refreshExistingGrounding(root, store, { force: opts.force }) : [];
+        // `newer` (a block from a newer Hunch template) is reported, never failing.
         const failing = verdicts.filter((v) => v.verdict.kind === "ahead" || v.verdict.kind === "diverged");
         const lagging = verdicts.filter((v) => v.verdict.kind === "lagging");
         if (opts.json) {
@@ -6647,12 +6733,15 @@ program
                     continue;
                 if (v.verdict.kind === "fresh" && opts.quiet)
                     continue;
-                console.log(`${v.verdict.kind === "fresh" ? "✓" : v.verdict.kind === "lagging" ? "·" : "✗"} ${describeGroundingFreshness(v.doc, v.verdict)}`);
+                console.log(`${v.verdict.kind === "fresh" ? "✓" : v.verdict.kind === "lagging" || v.verdict.kind === "newer" ? "·" : "✗"} ${describeGroundingFreshness(v.doc, v.verdict)}`);
             }
             if (!opts.quiet && !failing.length) {
+                const newer = verdicts.filter((v) => v.verdict.kind === "newer");
                 console.log(lagging.length
                     ? `\n${lagging.length} doc(s) lag a merge — transient; the next capture commit or \`hunch grounding --refresh\` heals it.`
-                    : "✓ grounding docs are fresh.");
+                    : newer.length
+                        ? `\n${newer.length} doc(s) written by a newer Hunch — kept as written; upgrade Hunch to check them fully.`
+                        : "✓ grounding docs are fresh.");
             }
         }
         if (!opts.refresh && failing.length)
@@ -7315,7 +7404,7 @@ program
     else {
         const team = readTeamConfig(root);
         console.log(team
-            ? `overlay:    off, but .hunch/team.json advertises the team store (${team.shared_repo}) — run \`hunch init\` to auto-connect`
+            ? `overlay:    off, but .hunch/team.json advertises the team store (${team.shared_repo}) — ${isTeamStoreTrusted(root, team) ? "run \`hunch init\` to auto-connect" : "if it is your team's store, run \`hunch shared --trust\` to connect"}`
             : dim(`private:    off — run \`hunch shared\` (or \`hunch private\`) to use one overlay repo across teammates/worktrees (or set HUNCH_PRIVATE_DIR)`));
     }
     // Worktree posture: linked worktrees share ONE memory via the git common dir. Only
@@ -7389,10 +7478,6 @@ function fail(msg) {
     process.exitCode = 1;
 }
 // --- agent-hook helpers (used by `hunch hook`) -----------------------------
-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.";
 /** Read all of stdin (the hook event JSON). A TTY (no piped input) resolves to ""
  *  so an accidental interactive `hunch hook` exits cleanly instead of hanging. */
 function readStdin() {
@@ -7419,6 +7504,243 @@ function toRepoRel(root, abs) {
     const rel = repoRelativeTarget(abs, root);
     return isAbsolute(rel) || /^[a-zA-Z]:/.test(rel) ? "" : rel;
 }
+/** Files a shell command wrote get the grounding the edit tools would have
+ *  delivered before the edit — late, but while the agent can still revise.
+ *  Already-served grounding (a delta) is not repeated. */
+const MAX_SHELL_GROUNDED = 3;
+function shellWriteGrounding(root, store, provider, evt, written) {
+    const parts = [];
+    const grounded = [];
+    for (const target of written.slice(0, MAX_SHELL_GROUNDED)) {
+        const g = fileGrounding(root, store, provider, evt, target, join(root, target));
+        if (g?.mode === "full") {
+            parts.push(g.text);
+            grounded.push(target);
+        }
+    }
+    if (!parts.length)
+        return "";
+    const more = written.length > MAX_SHELL_GROUNDED ? ` (${written.length - MAX_SHELL_GROUNDED} more written file(s) not checked)` : "";
+    const sibling = parts.some((p) => p.startsWith(SIBLING_HEADING)) ? " It starts with a fix a same-shaped function elsewhere received and this file's copy never did: resolve it before you finish." : "";
+    return `Hunch: this shell command wrote ${grounded.join(", ")}${more}. Edits made outside the Edit/Write tools skip the pre-edit grounding, so it arrives now: re-check the change against it before relying on it.${sibling}\n\n${parts.join("\n\n")}`;
+}
+/** Score the store against this prompt once per task (taskSelection.ts) and keep
+ *  the selected ids — never the prompt — for the task's file grounding. Returns
+ *  the short prompt-time list, or "" when nothing clears the threshold (silence).
+ *  A follow-up prompt widens the qualifying set rather than replacing it, so a
+ *  "go" cannot unselect the task's memory. */
+const TASK_SELECTION_TITLE_CHARS = 80;
+function promptTaskSelection(root, store, provider, evt) {
+    // A host notification is not a task prompt: the earlier selection stands untouched.
+    if (!taskSelectionEnabled() || isNotificationPrompt(evt.prompt))
+        return "";
+    const taskId = hookReportTaskId(root, provider, evt);
+    if (!taskId)
+        return "";
+    const selection = selectForTask(liveSelectionRecords({
+        decisions: store.recs("decisions"),
+        bugs: store.recs("bugs"),
+        constraints: store.recs("constraints"),
+        findings: store.recs("findings"),
+    }), evt.prompt ?? "", { root, pathExists: (p) => existsSync(join(root, p)) });
+    // Same task id again (a notification alias) keeps its own earlier selection; a
+    // new task that CONTINUES the session's previous one inherits that task's
+    // selection only on a bare follow-up ("continue", "go on"), so it is not left
+    // ungrounded. A substantive prompt names its own task: a same-session prompt
+    // inside the continuation window must not hide memory behind an old selection.
+    let previous = loadTaskSelection(taskId);
+    if (!previous && isBareFollowUp(evt.prompt ?? "")) {
+        try {
+            const continues = readTaskReport(root, taskId).task.continues;
+            previous = continues ? loadTaskSelection(continues) : null;
+        }
+        catch { /* no continuity; the prompt's own selection stands */ }
+    }
+    const qualifying = [...new Set([...(previous?.qualifying ?? []), ...selection.qualifying])];
+    // An empty selection is no selection: the task keeps the unfiltered grounding.
+    // Emptiness counts only the kinds grounding filters (decisions, bugs,
+    // findings): constraints always pass, so a constraint-only set would hide every
+    // other record anchored to the file. The prompt-time list may still print.
+    if (!qualifying.some(isFilterableSelectionId)) {
+        clearTaskSelection(taskId);
+    }
+    else {
+        saveTaskSelection({
+            task_id: taskId,
+            qualifying,
+            top: selection.qualifying.length ? selection.top.map((item) => item.id) : previous?.top ?? [],
+        });
+    }
+    // An inherited selection was listed when its own prompt ran: not again.
+    if (!selection.top.length)
+        return "";
+    const clip = (text) => {
+        const flat = text.replace(/\s+/g, " ").trim();
+        return flat.length > TASK_SELECTION_TITLE_CHARS ? `${flat.slice(0, TASK_SELECTION_TITLE_CHARS - 1).trimEnd()}…` : flat;
+    };
+    return `Hunch memory for this task: ${selection.top.map((item) => `${item.id} — ${clip(item.title)}`).join(" · ")} (hunch_why(id) for detail)`;
+}
+/** Memory budget beside a sibling lesson (the default is 1500 tokens). */
+const SIBLING_MEMORY_BUDGET_TOKENS = 800;
+/** The advisory grounding for one repo-relative file: the ranked memory slice,
+ *  retired code, doc anchors, recent tasks and sibling-fix lessons. `delta` when
+ *  identical grounding was already served this session, null when Hunch knows
+ *  nothing about the file. Serves the pre-edit hook and files a shell command
+ *  wrote (which never pass through the edit tools). */
+function fileGrounding(root, store, provider, evt, target, abs) {
+    // Decision-grounding for PROSE (doc≠graph): a markdown target that declares
+    // <!-- hunch:topic … --> anchors gets each topic's CURRENT decision — the
+    // graph outranks the prose being edited, and a stale pin is called out inline.
+    let docGround = "";
+    if (/\.(md|mdx)$/i.test(target)) {
+        try {
+            docGround = renderDocGrounding(parseDocAnchors(readFileSync(abs, "utf8")), store.recs("decisions"));
+        }
+        catch { /* unreadable / not yet created — no doc grounding */ }
+    }
+    // A task whose prompt was scored (promptTaskSelection) gets the file's
+    // decisions, bugs and findings conditioned on it. Constraints always pass (any
+    // severity): they are scoped rules, including agent-recorded corrections capped
+    // at warning, not relevance guesses. No selection (a host without a prompt
+    // hook, a legacy session, a prompt that selected nothing) keeps the unfiltered
+    // grounding.
+    const selection = loadTaskSelection(hookReportTaskId(root, provider, evt));
+    const assembled = store.assembleContext(target);
+    const selected = selection ? new Set(selection.qualifying) : null;
+    const ctx = selected ? {
+        ...assembled,
+        decisions: assembled.decisions.filter((d) => selected.has(d.id)),
+        bugs: assembled.bugs.filter((b) => selected.has(b.id)),
+        findings: assembled.findings.filter((f) => selected.has(f.id)),
+    } : assembled;
+    // Sibling fixes: a same-shaped function elsewhere was fixed and this copy
+    // never was — the concrete lesson a scoped constraint cannot carry.
+    const siblings = siblingGrounding(root, target, store.recs("symbols"), ctx.constraints.filter((c) => c.severity === "blocking" && c.scope.some((g) => pathMatchesGlob(target, g))).map((c) => ({ id: c.id, statement: c.statement })));
+    // Remember what was delivered, so the first check the agent runs can follow
+    // up if the function is still untouched (pipeline.ts lessonReminder).
+    if (siblings.lessons.length && evt.session_id && pipelineEnabled()) {
+        try {
+            savePipelineState(evt.session_id, onLessonsDelivered(loadPipelineState(evt.session_id), siblings.lessons.map((l) => ({
+                id: `${l.file}:${l.symbol}~${l.siblingFile}:${l.sibling}`,
+                file: l.file,
+                symbol: l.symbol,
+                sibling: l.sibling,
+                siblingFile: l.siblingFile,
+                change: l.commits.map((c) => `${c.sha.slice(0, 8)} ${c.subject}`).join("; "),
+                callers: [...(siblings.callers.get(l.symbol) ?? [])],
+                hash: functionBodyHash(root, l.file, l.symbol),
+            }))));
+        }
+        catch { /* the reminder is a convenience; the lesson itself was delivered */ }
+    }
+    // Regression Guard (edit-time grounding): what an in-force decision retired
+    // from this file. No diff exists yet, so this is context — "don't re-add X" —
+    // not a block; the commit-time `hunch check` does the actual gating.
+    const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
+    // Recent-task history is advisory; under a task selection it is dropped
+    // (`hunch task list` still has it).
+    const recentTasks = selected ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
+    const hasContent = ctx.constraints.length ||
+        ctx.decisions.length ||
+        ctx.bugs.length ||
+        ctx.blast_radius.length ||
+        ctx.findings.length ||
+        ctx.landscape?.resources.length ||
+        ctx.landscape?.relationships.length ||
+        retired.length ||
+        recentTasks.length ||
+        docGround ||
+        siblings.text;
+    if (!hasContent)
+        return null;
+    const supplements = [
+        ...(retired.length ? [{
+                id: "retired-code",
+                kind: "retired-code",
+                priority: 200,
+                text: `⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ")}.`,
+            }] : []),
+        ...(docGround ? [{ id: "doc-grounding", kind: "doc-grounding", priority: 100, text: docGround }] : []),
+        ...recentTasks,
+    ];
+    // A sibling lesson is the most specific thing Hunch knows about this edit:
+    // it leads, and the ranked memory gets a smaller budget so it cannot bury it.
+    const envelope = buildDeliveryEnvelope(siblings.text ? { ...ctx, budget_tokens: Math.min(ctx.budget_tokens, SIBLING_MEMORY_BUDGET_TOKENS) } : ctx, {
+        profile: "builder",
+        root,
+        symbols: store.recs("symbols"),
+        components: store.recs("components"),
+        decisionCorpus: store.recs("decisions"),
+        supplements,
+    });
+    // Outside the envelope's budget on purpose: the lesson is a code change, not a
+    // one-line supplement, and memory records must not crowd it out.
+    const text = [siblings.text, envelope.text.trim()].filter(Boolean).join("\n\n");
+    // Identical grounding already shown this session → one-line delta instead of
+    // the full 10-16KB block. Any record change re-sends the full text; the
+    // strict-gate deny path above never routes through this (dec_244397d920).
+    // Delivery receipts (dec_925f4bcaad): the ledger of what actually reached
+    // an agent. A full injection is a serve; a delta one-liner attests the
+    // earlier serve is still standing. Never throws, never blocks.
+    const receipts = (event) => recordServed(root, [
+        ...envelope.delivered.map((item) => ({
+            event,
+            kind: item.kind,
+            record_id: item.record_id,
+            target,
+            session_id: evt.session_id,
+            rank: item.rank,
+            delivery_reason: item.delivery_reason,
+            provenance_status: item.provenance_status,
+            token_cost: item.token_cost,
+            delivery_profile: envelope.profile,
+            ranking_policy: envelope.ranking_policy,
+        })),
+        // Delivered task lines are receipts too: they feed access-based recency.
+        ...envelope.supplements.filter((s) => s.kind === "recent-task" && s.delivered).map((s) => ({
+            event, kind: "tasks", record_id: s.id, target, session_id: evt.session_id,
+            rank: s.rank, delivery_reason: "supplemental", token_cost: s.token_cost,
+            delivery_profile: envelope.profile, ranking_policy: envelope.ranking_policy,
+        })),
+    ]);
+    const reportTaskId = hookReportTaskId(root, provider, evt);
+    // A new authoritative prompt gets its own full delivery. An earlier
+    // prompt's session-level delta cannot establish this task's receipt.
+    // A subagent reports to the prompt's task but starts with FRESH context:
+    // it never saw that grounding, so its dedup is scoped by its own agent
+    // identity (hashed — the raw agent_id is never retained in the key).
+    const agentKey = evt.agent_id ? `:${reportHash(evt.agent_id).slice(7, 19)}` : "";
+    // Dedup on the envelope's stable IDENTITY projection, never on the
+    // rendered block: serving the full text writes delivery receipts, and the
+    // next call's task ranking reads them back and moves the wording ("today"
+    // → "delivered today"), so hashing the presentation made this grounding
+    // self-invalidating and re-sent the full block for unchanged records.
+    if (injectionMode(evt.session_id, `pre:${target}${reportTaskId ? `:${reportTaskId}` : ""}${agentKey}`, text, deliveryDedupeInput(envelope, supplements) + (siblings.identity ? `\u0000sibling-fix\u0000${siblings.identity}` : "")) === "delta") {
+        receipts("refreshed");
+        return {
+            mode: "delta",
+            text: `Hunch grounding for ${target}: unchanged this session (${envelope.delivered.filter((item) => item.kind === "decisions").length} decision(s), ${envelope.delivered.filter((item) => item.kind === "constraints").length} invariant(s)${siblings.identity ? ", sibling-fix lesson" : ""} shown earlier — still current; hunch_why("${target}") to re-expand).`,
+        };
+    }
+    receipts("served");
+    let reportNotice = "";
+    let recalled = null;
+    if (reportTaskId) {
+        try {
+            const snapshots = snapshotDeliveredRecords(store, envelope);
+            // The first time a lesson reaches this prompt's task, tell the USER in one
+            // line (systemMessage); repeats of the same revision stay silent.
+            recalled = reportPresentationEnabled(root) ? renderRecalledLine(unseenLessons(root, reportTaskId, snapshots)) : null;
+            const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots, undefined, target);
+            reportNotice = `\n\nHunch task ${reportTaskId} · delivery ${occurrence}. Inspect exact application references with hunch_report(task_id).`;
+        }
+        catch {
+            reportNotice = "\n\nTask report observation unavailable; this delivery's task contribution remains unverified.";
+            recalled = null;
+        }
+    }
+    return { mode: "full", text: text + reportNotice, recalled };
+}
 /** The in-repo files a pre-edit event would change, each with the lines the edit
  *  ADDS to that file. A Codex apply_patch yields one entry per touched path (a
  *  Move-to destination is its own entry, carrying the section's added lines);