@davesheffer/hunch 1.43.0 → 1.44.0

package/dist/integrations/uninstall.js

@@ -0,0 +1,435 @@
+/**
+ * `hunch uninstall` (#449): remove exactly what Hunch installed in a repository
+ * and leave an opt-out marker so nothing re-installs it.
+ *
+ * Planning is read-only and complete before anything is written: every file is
+ * parsed first, and one that cannot be parsed (or whose Hunch markers are
+ * damaged) is refused, so a run either changes nothing or applies the whole plan
+ * (con_8460b6770f). Each step removes only Hunch's own part of a file — the
+ * marker-delimited block, the `hunch` server entry, the hook commands the
+ * installers' own classifiers call ours — and a file is deleted only when
+ * nothing but Hunch's part was in it. Running it twice is a no-op.
+ *
+ * `.hunch/` holds the engineering memory, so it stays unless `--purge`.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename, join, relative } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { writeFileAtomic } from "../core/io.js";
+import { gitCommonDir, isGitRepo, separateGitDirLink } from "../extractors/git.js";
+import { HUNCH_END, HUNCH_START } from "./claudemd.js";
+import { ciWorkflowYaml } from "./ciAction.js";
+import { assertSafeTopLevelConfigFile, stripManagedGitignore } from "./gitignore.js";
+import { isHunchHookCommand } from "./hookmatch.js";
+import { planHookRemoval } from "./hooks.js";
+import { ATTR_LINES, targetRepositoryEnv } from "./mergeDriver.js";
+import { antigravityMcpFile, isHunchProviderHook, readJsonObj, TOML_END, TOML_START, windsurfMcpFile } from "./providers.js";
+import { SLASH_COMMAND_FILES } from "./scaffold.js";
+/** The opt-out marker, at the repository root. Commit it so every clone stays opted out. */
+export const OPT_OUT_FILE = ".hunch-removed";
+export function isOptedOut(root) {
+    try {
+        return lstatSync(join(root, OPT_OUT_FILE)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function optOutMessage() {
+    return `Hunch was removed from this repository on purpose (${OPT_OUT_FILE}), so it will not set itself up here again. To reinstall, delete ${OPT_OUT_FILE} and run \`hunch init\`.`;
+}
+function markerText() {
+    return [
+        `Hunch was removed from this repository on purpose (\`hunch uninstall\`, ${new Date().toISOString().slice(0, 10)}).`,
+        "",
+        "While this file exists, Hunch commands refuse to set Hunch up here again.",
+        "Coding agents: do not re-install Hunch or re-add its MCP server, hooks or",
+        "instruction blocks in this repository.",
+        "",
+        "To reinstall Hunch, delete this file and run `hunch init`.",
+        "",
+    ].join("\n");
+}
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** A delete step's note: the file held nothing but Hunch's part. */
+const deleted = (note) => `${note.replace(/ \(.*\)$/, "")}; nothing else was in the file`;
+/** Text that may hold a Hunch entry: the name, or the CLI entry path a source install writes. */
+const MAY_HOLD_HUNCH = /hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)/i;
+/** Join the text around a removed block, dropping the blank lines the writer added. */
+function joinAround(before, after, eol) {
+    const b = before.replace(/\s+$/, "");
+    const a = after.replace(/^(?:[ \t]*(?:\r\n|\r|\n))+/, ""); // blank lines only: the next line keeps its indent
+    if (!a.trim())
+        return b ? `${b}${eol}` : "";
+    return b ? `${b}${eol}${eol}${a}` : a;
+}
+class Planner {
+    root;
+    steps = [];
+    refused = [];
+    constructor(root) {
+        this.root = root;
+    }
+    rel(abs) {
+        const r = relative(this.root, abs);
+        return r && !r.startsWith("..") ? r.replace(/\\/g, "/") : abs;
+    }
+    text(rel) {
+        const file = join(this.root, rel);
+        try {
+            return statSync(file).isFile() ? readFileSync(file, "utf8") : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeOrDelete(rel, next, deleteWhenEmpty, note) {
+        const file = join(this.root, rel);
+        if (deleteWhenEmpty && next.trim() === "") {
+            this.steps.push({ path: rel, kind: "delete", note: deleted(note), run: () => rmSync(file, { force: true }) });
+        }
+        else {
+            this.steps.push({ path: rel, kind: "edit", note, run: () => writeFileAtomic(file, next) });
+        }
+    }
+    /** Parse a JSON config with the writers' own strictness, let `mutate` take Hunch's
+     *  part out, then rewrite it — or delete it when only Hunch's part was there. */
+    json(rel, note, mutate, empty = (j) => Object.keys(j).length === 0) {
+        const file = join(this.root, rel);
+        if (!existsSync(file))
+            return;
+        let json;
+        try {
+            json = readJsonObj(file);
+        }
+        catch (e) {
+            // A file Hunch never wrote into (say, a JSONC file with comments) is not ours to fix.
+            // A source install's hook names only its …/dist|src/cli/index.js entry, not "hunch".
+            if (MAY_HOLD_HUNCH.test(this.text(rel) ?? ""))
+                this.refused.push({ path: rel, reason: e.message });
+            return;
+        }
+        if (!mutate(json))
+            return;
+        if (empty(json))
+            this.steps.push({ path: rel, kind: "delete", note: deleted(note), run: () => rmSync(file, { force: true }) });
+        else
+            this.steps.push({ path: rel, kind: "edit", note, run: () => writeFileAtomic(file, JSON.stringify(json, null, 2) + "\n") });
+    }
+    mcpEntry(rel, key) {
+        this.json(rel, "removed the hunch MCP server entry", (json) => {
+            const servers = json[key];
+            if (!isObj(servers) || !("hunch" in servers))
+                return false;
+            delete servers.hunch;
+            if (Object.keys(servers).length === 0)
+                delete json[key];
+            return true;
+        });
+    }
+    /** Hunch commands in a `{ hooks: { Event: [...] } }` file. */
+    hookConfig(rel, isOurs, empty) {
+        this.json(rel, "removed Hunch's hook commands", (json) => {
+            const hooks = json.hooks;
+            if (!isObj(hooks))
+                return false;
+            let changed = false;
+            for (const [event, list] of Object.entries(hooks)) {
+                if (!Array.isArray(list))
+                    continue;
+                const kept = list.map(isOurs).filter((e) => e !== null);
+                if (kept.length === list.length && kept.every((e, i) => e === list[i]))
+                    continue;
+                changed = true;
+                if (kept.length)
+                    hooks[event] = kept;
+                else
+                    delete hooks[event];
+            }
+            if (changed && Object.keys(hooks).length === 0)
+                delete json.hooks;
+            return changed;
+        }, empty);
+    }
+    /** A marker-delimited block in a text file. */
+    block(rel, start, end, note, isEmpty, validate) {
+        const cur = this.text(rel);
+        if (cur === null || (!cur.includes(start) && !cur.includes(end)))
+            return;
+        const i = cur.indexOf(start);
+        const j = cur.indexOf(end);
+        if (i < 0 || j < i) {
+            this.refused.push({ path: rel, reason: `its Hunch block markers are damaged (${start.slice(0, 24)}… / ${end}); remove the block by hand, then re-run` });
+            return;
+        }
+        const problem = validate?.(cur);
+        if (problem) {
+            this.refused.push({ path: rel, reason: problem });
+            return;
+        }
+        const eol = cur.includes("\r\n") ? "\r\n" : "\n";
+        const next = joinAround(cur.slice(0, i), cur.slice(j + end.length), eol);
+        const file = join(this.root, rel);
+        if (isEmpty(next))
+            this.steps.push({ path: rel, kind: "delete", note: deleted(note), run: () => rmSync(file, { force: true }) });
+        else
+            this.steps.push({ path: rel, kind: "edit", note, run: () => writeFileAtomic(file, next) });
+    }
+}
+/** Claude Code's settings.json: Hunch's commands inside each matcher entry. */
+function claudeEntry(entry) {
+    if (!isObj(entry) || !Array.isArray(entry.hooks))
+        return entry;
+    const hooks = entry.hooks;
+    const kept = hooks.filter((h) => !(isObj(h) && typeof h.command === "string" && isHunchHookCommand(h.command, false)));
+    if (kept.length === hooks.length)
+        return entry;
+    return kept.length ? { ...entry, hooks: kept } : null;
+}
+const providerEntry = (entry) => (isHunchProviderHook(entry) ? null : entry);
+function normalizedCi(text) {
+    return text.replace(/\r\n/g, "\n").replace(/@davesheffer\/hunch@\S+/g, "@davesheffer/hunch@<version>");
+}
+function gitConfigHasDrivers(root) {
+    const r = spawnSync("git", ["config", "--local", "--get-regexp", "^merge\\.hunch(-grounding)?\\."], { cwd: root, env: targetRepositoryEnv(), encoding: "utf8" });
+    return r.status === 0 && r.stdout.trim() !== "";
+}
+/** The overlay clone a pointer names, for the "kept" note. Never deleted: it is
+ *  its own repository holding memory that may not be pushed yet. */
+function pointerOverlay(file) {
+    try {
+        const v = JSON.parse(readFileSync(file, "utf8"));
+        return typeof v.privateDir === "string" ? v.privateDir : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read-only: everything `hunch uninstall` would do in `root`. */
+export function planUninstall(root, opts = {}) {
+    const purge = !!opts.purge;
+    const p = new Planner(root);
+    if (!isOptedOut(root)) {
+        const file = join(root, OPT_OUT_FILE);
+        p.steps.push({ path: OPT_OUT_FILE, kind: "create", note: "opt-out marker: Hunch will not set itself up here again (commit it so every clone stays opted out)", run: () => writeFileAtomic(file, markerText()) });
+    }
+    // Grounding docs. Shared docs keep the user's prose; a doc left holding only the
+    // title Hunch gave it when it created the file goes entirely.
+    const shared = [
+        ["CLAUDE.md", `# ${basename(root)}`],
+        ["AGENTS.md", "# AGENTS.md"],
+        [".github/copilot-instructions.md", "# Copilot instructions"],
+    ];
+    for (const [rel, title] of shared) {
+        p.block(rel, HUNCH_START, HUNCH_END, "removed the Hunch instruction block (your own text is kept)", (rest) => rest.trim() === "" || rest.trim() === title);
+    }
+    for (const rel of [".cursor/rules/hunch.mdc", ".windsurf/rules/hunch.md"]) {
+        const cur = p.text(rel);
+        if (cur === null)
+            continue;
+        if (cur.includes(HUNCH_START))
+            p.steps.push({ path: rel, kind: "delete", note: "Hunch's rule file", run: () => rmSync(join(root, rel), { force: true }) });
+        else
+            p.steps.push({ path: rel, kind: "keep", note: "no Hunch block in it any more, so it is yours; delete it yourself if you don't want it" });
+    }
+    // MCP registrations.
+    p.mcpEntry(".mcp.json", "mcpServers");
+    p.mcpEntry(".cursor/mcp.json", "mcpServers");
+    p.mcpEntry(".vscode/mcp.json", "servers");
+    p.mcpEntry(".windsurf/mcp_config.json", "mcpServers");
+    p.mcpEntry(".agents/mcp_config.json", "mcpServers");
+    // Global (per-user) registrations `init` adds when the host is installed: shared by
+    // every repository on this machine, so never edited here — reported, so the user
+    // knows the entry remains (it is inert in this repository: `hunch mcp` refuses).
+    for (const [file, host] of [[windsurfMcpFile(), "Windsurf"], [antigravityMcpFile(), "Antigravity"]]) {
+        if (!file)
+            continue;
+        try {
+            const servers = readJsonObj(file).mcpServers;
+            if (isObj(servers) && "hunch" in servers)
+                p.steps.push({ path: file, kind: "keep", note: `${host}'s global hunch MCP entry serves every repository on this machine; remove it there if you want Hunch gone everywhere` });
+        }
+        catch { /* unreadable global config: nothing to report about it here */ }
+    }
+    p.block(".codex/config.toml", TOML_START, TOML_END, "removed the managed hunch MCP block", (rest) => rest.trim() === "", (text) => {
+        try {
+            parseToml(text);
+            return null;
+        }
+        catch (e) {
+            return `refusing to edit: could not parse TOML (${e.message}); fix it, then re-run`;
+        }
+    });
+    // Agent lifecycle hooks.
+    p.hookConfig(".claude/settings.json", claudeEntry);
+    p.hookConfig(".cursor/hooks.json", providerEntry, (j) => Object.keys(j).every((k) => k === "version"));
+    p.hookConfig(".codex/hooks.json", providerEntry);
+    p.hookConfig(".github/hooks/hunch.json", providerEntry);
+    p.hookConfig(".windsurf/hooks.json", providerEntry);
+    p.json(".agents/hooks.json", "removed the hunch hook group", (json) => {
+        if (!("hunch" in json))
+            return false;
+        delete json.hunch;
+        return true;
+    });
+    // Generated slash commands: only files carrying the ownership marker, or in the
+    // hunch- namespace the writer always treats as its own.
+    for (const name of SLASH_COMMAND_FILES) {
+        const rel = `.claude/commands/${name}`;
+        const cur = p.text(rel);
+        if (cur === null)
+            continue;
+        if (name.startsWith("hunch-") || cur.includes("hunch:generated")) {
+            p.steps.push({ path: rel, kind: "delete", note: "generated slash command", run: () => rmSync(join(root, rel), { force: true }) });
+        }
+    }
+    // CI workflow, only when it is still the file Hunch generated.
+    const ciRel = ".github/workflows/hunch-guard.yml";
+    const ci = p.text(ciRel);
+    if (ci !== null) {
+        if (normalizedCi(ci) === normalizedCi(ciWorkflowYaml())) {
+            p.steps.push({ path: ciRel, kind: "delete", note: "the Hunch Guard CI workflow", run: () => rmSync(join(root, ciRel), { force: true }) });
+        }
+        else {
+            p.steps.push({ path: ciRel, kind: "keep", note: "it differs from the workflow Hunch generates (edited?); delete it yourself if you no longer want the Hunch Guard check" });
+        }
+    }
+    // Git hooks + merge driver.
+    if (isGitRepo(root)) {
+        for (const h of planHookRemoval(root)) {
+            const path = p.rel(h.path);
+            if (h.reason)
+                p.steps.push({ path, kind: "keep", note: h.reason });
+            else if (h.next === null)
+                p.steps.push({ path, kind: "delete", note: `Hunch's ${h.hookName} git hook`, run: () => rmSync(h.path, { force: true }) });
+            else {
+                const next = h.next;
+                p.steps.push({ path, kind: "edit", note: `removed Hunch's block from the ${h.hookName} git hook (your own lines are kept)`, run: () => { writeFileSync(h.path, next); chmodSync(h.path, 0o755); } });
+            }
+        }
+        if (gitConfigHasDrivers(root)) {
+            p.steps.push({
+                path: ".git/config", kind: "edit", note: "unregistered the merge.hunch and merge.hunch-grounding drivers",
+                run: () => {
+                    for (const section of ["merge.hunch", "merge.hunch-grounding"]) {
+                        spawnSync("git", ["config", "--local", "--remove-section", section], { cwd: root, env: targetRepositoryEnv(), stdio: "ignore" });
+                    }
+                },
+            });
+        }
+    }
+    const attrs = p.text(".gitattributes");
+    if (attrs !== null) {
+        try {
+            assertSafeTopLevelConfigFile(root, ".gitattributes");
+            const ours = new Set(ATTR_LINES);
+            const lines = attrs.split("\n");
+            const kept = lines.filter((l) => !ours.has(l.trim()));
+            if (kept.length !== lines.length)
+                p.writeOrDelete(".gitattributes", kept.join("\n"), true, "removed Hunch's merge-driver routes");
+        }
+        catch (e) {
+            p.refused.push({ path: ".gitattributes", reason: e.message });
+        }
+    }
+    // Memory and its wiring.
+    const hunchDir = join(root, ".hunch");
+    const localPointer = join(hunchDir, "local.json");
+    const common = isGitRepo(root) ? gitCommonDir(root) : "";
+    const commonPointer = common ? join(common, "hunch", "local.json") : "";
+    const overlays = new Set([localPointer, commonPointer].filter((f) => f && existsSync(f)).map(pointerOverlay).filter((d) => !!d));
+    const inRepoOverlay = existsSync(join(root, ".hunch-private"));
+    if (!purge) {
+        if (existsSync(hunchDir))
+            p.steps.push({ path: ".hunch/", kind: "keep", note: "your engineering memory; `hunch uninstall --purge` deletes it" });
+    }
+    else {
+        const gi = p.text(".gitignore");
+        if (gi !== null) {
+            try {
+                assertSafeTopLevelConfigFile(root, ".gitignore");
+                const { next, damaged } = stripManagedGitignore(gi);
+                if (damaged)
+                    p.refused.push({ path: ".gitignore", reason: "a Hunch block has no closing marker; remove it by hand, then re-run" });
+                else if (next !== gi) {
+                    if (inRepoOverlay)
+                        p.steps.push({ path: ".gitignore", kind: "keep", note: "its Hunch block still ignores the .hunch-private/ overlay clone; delete that clone yourself (after pushing it), then re-run `hunch uninstall --purge`" });
+                    else
+                        p.writeOrDelete(".gitignore", next, true, "removed Hunch's ignore blocks");
+                }
+            }
+            catch (e) {
+                p.refused.push({ path: ".gitignore", reason: e.message });
+            }
+        }
+        if (existsSync(hunchDir))
+            p.steps.push({ path: ".hunch/", kind: "delete", note: "engineering memory, config and derived index (--purge)", run: () => rmSync(hunchDir, { recursive: true, force: true }) });
+        const cache = join(root, ".hunch-cache");
+        if (existsSync(cache))
+            p.steps.push({ path: ".hunch-cache/", kind: "delete", note: "derived cache", run: () => rmSync(cache, { recursive: true, force: true }) });
+        if (common) {
+            for (const file of [commonPointer, separateGitDirLink(common)]) {
+                if (existsSync(file))
+                    p.steps.push({ path: p.rel(file), kind: "delete", note: "this clone's Hunch pointer in the git dir", run: () => rmSync(file, { force: true }) });
+            }
+        }
+    }
+    for (const dir of overlays) {
+        p.steps.push({ path: p.rel(dir), kind: "keep", note: "a private/shared overlay clone: its own repository with memory that may not be pushed; never deleted here" });
+    }
+    return { root, purge, steps: p.steps, refused: p.refused };
+}
+/** Directories Hunch's writers create; removed only when left empty. Deepest first. */
+const PRUNE_DIRS = [
+    ".claude/commands", ".claude", ".cursor/rules", ".cursor", ".windsurf/rules", ".windsurf",
+    ".vscode", ".github/hooks", ".github/workflows", ".github", ".codex", ".agents",
+];
+export function applyUninstall(plan) {
+    if (plan.refused.length)
+        throw new Error("refusing to apply an uninstall plan that has refusals");
+    const applied = [];
+    const failed = [];
+    for (const step of plan.steps) {
+        try {
+            step.run?.();
+            applied.push(step);
+        }
+        catch (e) {
+            failed.push({ path: step.path, error: e.message });
+            if (step.path === OPT_OUT_FILE)
+                return { applied, failed }; // never strip Hunch without the marker that keeps it out
+        }
+    }
+    for (const rel of PRUNE_DIRS) {
+        const dir = join(plan.root, rel);
+        try {
+            if (readdirSync(dir).length === 0)
+                rmdirSync(dir);
+        }
+        catch { /* absent or not empty */ }
+    }
+    if (plan.purge) {
+        const common = isGitRepo(plan.root) ? gitCommonDir(plan.root) : "";
+        if (common) {
+            const dir = join(common, "hunch");
+            try {
+                if (readdirSync(dir).length === 0)
+                    rmdirSync(dir);
+            }
+            catch { /* absent or not empty */ }
+        }
+    }
+    return { applied, failed };
+}
+export function formatUninstallPlan(plan, dryRun) {
+    const verb = (k) => ({ edit: dryRun ? "would edit" : "edited", delete: dryRun ? "would delete" : "deleted", create: dryRun ? "would create" : "created", keep: "kept" })[k];
+    const icon = (k) => (k === "keep" ? "·" : "✓");
+    const out = [];
+    for (const r of plan.refused)
+        out.push(`  ✗ ${r.path}: ${r.reason}`);
+    for (const s of plan.steps)
+        out.push(`  ${icon(s.kind)} ${verb(s.kind)} ${s.path} — ${s.note}`);
+    return out;
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/mcp/server.d.ts

@@ -10,7 +10,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { HunchStore } from "../store/hunchStore.js";
 import { type StateFacet } from "../core/stateContract.js";
-import type { Symbol } from "../core/types.js";
+import type { Decision, Symbol } from "../core/types.js";
 export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
 /** The cwd-hint fallback (see `cwdHintField` above) only helps when the CALLER
  *  remembers to pass it — a subagent spawned straight into its own linked
@@ -623,6 +623,7 @@ export declare function compactEnvelope(envelope: z.infer<typeof DELIVERY_OUTPUT
  *  reason. Runs after recordServed and after the full envelope validated, so
  *  receipts and receipt_id are unchanged. */
 export declare function compactOmissions(envelope: z.infer<typeof DELIVERY_OUTPUT_SCHEMA>): z.infer<typeof DELIVERY_ADVERTISED_OUTPUT_SCHEMA>;
+export declare function decisionSubstanceChanged(before: Decision, after: Decision): boolean;
 /** Resolve a free-form target (symbol id / name / file path) to symbol records.
  *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
  *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift

package/dist/mcp/server.js

@@ -32,7 +32,7 @@ import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
 import { workspacesConfig } from "../core/config.js";
-import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, isTeamStoreTrusted, overlayMatchesTeamRemote, teamWiringConsented, untrustedTeamStoreMessage, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
@@ -940,6 +940,16 @@ function unconfirmedReason(c) {
         : "this client could not ask the human to confirm it (no MCP form elicitation, or the request failed)";
 }
 const clipForPrompt = (s, max = 400) => (s.length > max ? `${s.slice(0, max - 1)}…` : s);
+/** Whether a re-record changes what a human signed: every field except bookkeeping
+ *  (provenance, date, valid_from). Fails closed: a field added to Decision later counts
+ *  as substance until it is named here. Absent, null and empty-array values are equal. */
+const DECISION_BOOKKEEPING = new Set(["provenance", "date", "valid_from"]);
+export function decisionSubstanceChanged(before, after) {
+    const norm = (v) => (v === undefined || (Array.isArray(v) && v.length === 0) ? null : v);
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((k) => !DECISION_BOOKKEEPING.has(k)).sort();
+    const substance = (d) => JSON.stringify(keys.map((k) => [k, norm(d[k])]));
+    return substance(before) !== substance(after);
+}
 /** The interrogation protocol returned by hunch_capture_decision. With `deciding`,
  *  the choice is NOT yet made: the verdict loop runs first so the record's
  *  alternatives_rejected are attacks that actually ran — not post-hoc fiction. */
@@ -1018,7 +1028,7 @@ function pullBackoff(status, finishedAt, failures) {
     if (status === "busy") {
         return { consecutivePullFailures: failures, nextRemotePullAt: finishedAt + 100 };
     }
-    if (status === "unconfigured") {
+    if (status === "unconfigured" || status === "empty") {
         return { consecutivePullFailures: 0, nextRemotePullAt: finishedAt + 30_000 };
     }
     const consecutivePullFailures = Math.min(failures + 1, 6);
@@ -1954,6 +1964,24 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const decision = store.advisoryRecs("decisions").find((candidate) => candidate.id === decision_id);
             if (!decision)
                 return invalid(`Imported ADR ${decision_id} is not present in the current advisory memory home.`);
+            // Approval grants human authority, so the agent's report that the human approved
+            // is not enough: the human confirms in the client prompt, a channel the agent does
+            // not control, or approves with the CLI. A decline keeps the ADR advisory.
+            if (disposition === "approve") {
+                const confirmation = await askHumanToConfirm(server, [
+                    "Hunch: an agent reports that you approved this imported ADR as your decision. Confirm only if YOU approve it.",
+                    "",
+                    `Title: ${clipForPrompt(decision.title, 200)}`,
+                    `Decision: ${clipForPrompt(decision.decision || "(none)")}`,
+                    `Source hash: ${expected_source_hash}`,
+                    "",
+                    "Confirmed, it carries your authority (human_confirmed). Unconfirmed, it stays advisory.",
+                ].join("\n"));
+                if (confirmation !== "confirmed") {
+                    return refused(`Not approved: ${unconfirmedReason(confirmation)}, so ${decision_id} stays advisory and nothing was written. ` +
+                        `The human approves it by running: hunch review --approve-import ${decision_id} --expected-source-hash ${expected_source_hash} --expected-review-hash ${expected_review_hash} --reviewed-by <you>`);
+                }
+            }
             const reviewed = applyImportedAdrReview(decision, {
                 disposition,
                 expectedSourceHash: expected_source_hash,
@@ -2046,7 +2074,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         // bounded convergence. An unavailable remote produces an explicit abstention.
         if (live.length === 0 && store.mode === "shared" && store.privateDir) {
             const status = pullTeamMemory(true);
-            if (status !== "updated" && status !== "current") {
+            if (status === "cooldown" || status === "not_shared" || !teamPullIsFresh(status)) {
                 return err(`Shared team memory refresh is ${status}; Hunch cannot confirm that topic "${topic}" has no current decision. Retry when the shared store is available.`);
             }
             try {
@@ -2212,6 +2240,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 valid_from: existing?.valid_from ?? now,
                 valid_to: existing?.valid_to ?? null,
                 retired: existing?.retired ?? { symbols: [], deps: [] },
+                ...(existing?.conformance ? { conformance: existing.conformance } : {}),
+                ...(existing?.visibility ? { visibility: existing.visibility } : {}),
                 provenance: { source: "agent_recorded", confidence: 0.75, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
@@ -2261,6 +2291,23 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const humanSigned = confirmation === "confirmed";
             if (slotConflict && !humanSigned)
                 return slotRefusal();
+            // An inherited signature covers only the text the human signed. Changed substance
+            // without a fresh confirmation would keep human_confirmed on words nobody vouched for.
+            if (existingIsHuman && !humanSigned) {
+                if (decisionSubstanceChanged(existing, rec)) {
+                    return refused(`Decision ${id} is human-confirmed and this write changes its content; refusing to keep the human's signature on unconfirmed text, so nothing was written. ` +
+                        "Record the change through /capture so the human confirms it in the client prompt.");
+                }
+                // Same substance: the human's record already says this. Rewriting it would only
+                // replace the human's provenance with the agent's, so it is a no-op.
+                return ok(`Decision ${id} is human-confirmed and already says this; nothing was written.`);
+            }
+            // Closing a human-confirmed decision is as much a change to it as rewriting it.
+            const supersededIncumbent = decision.supersedes ? store.recs("decisions").find((d) => d.id === decision.supersedes) : undefined;
+            if (supersededIncumbent && !humanSigned && supersededIncumbent.provenance.source.split("+").includes("human_confirmed")) {
+                return refused(`Decision ${supersededIncumbent.id} is human-confirmed; an unconfirmed write cannot supersede it, so nothing was written. ` +
+                    "Record the change through /capture so the human confirms it in the client prompt.");
+            }
             const tier = humanSigned || existingIsHuman ? "human_confirmed" : "agent_recorded";
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? `llm_draft+${tier}`
@@ -2385,6 +2432,12 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             }
             const rec = buildCorrectionConstraint({ ...input, knownDeps, root, vouched: false }, now);
             const existing = home === "private" ? store.getPrivateRec("constraints", rec.id) : store.json.get("constraints", rec.id);
+            // A human-confirmed rule is changed only by the same human act that confirmed it.
+            // Writing `rec` here would replace the signature with testimony and cap its severity.
+            if (existing && existing.provenance.source.split("+").includes("human_confirmed")) {
+                return refused(`Constraint ${rec.id} is already human-confirmed; an agent write cannot replace or downgrade it, so nothing was written. ` +
+                    `A change needs the human, outside the agent channel: ${confirmCommand(rec.id, { private: home === "private", severity: requested.severity })}`);
+            }
             // Same cross-home twin guard as the decision path above.
             const stored = store.putCapture("constraints", rec, !!input.private);
             const observed = observeReportCapture(root, input.task_id, "constraints", stored, home, !!existing, home === "private" ? store.privateDir ?? undefined : hunchPaths(root).hunch);
@@ -2812,7 +2865,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (!files.length)
                 return ok(`VERDICT: ✅ PASS — no changed files in ${scope}.`);
             const gate = commit ? commitGateDiff(commit, root) : base ? rangeGateDiff(base, root) : working ? workingGateDiff(root) : stagedGateDiff(root);
-            const report = store.buildCheckReport(files, gate.diff, { strict: true, lastChange: (f) => lastChangeDate(f, root), diffStatus: gate });
+            const freshAt = checkFreshnessRevision({ base, commit }, root);
+            const report = store.buildCheckReport(files, gate.diff, { strict: true, lastChange: (f) => lastChangeDate(f, root, freshAt), diffStatus: gate });
             const v = verdict(report);
             const head = v === "block"
                 ? "VERDICT: ⛔ BLOCK — a recorded guard requires review; inspect the cited scope and evidence below before merge."

package/dist/serve/writelock.d.ts

@@ -7,6 +7,10 @@ export declare const ACQUIRE_TIMEOUT_MS = 10000;
  *  claimed section is a few syscalls, so anything this old means its claimer
  *  crashed inside it. */
 export declare const CLAIM_STALE_MS = 10000;
+/** How much later than the lock's recorded `at` the pid's current process must
+ *  have been created before it is proven not to be the owner. A genuine owner
+ *  started BEFORE it took the lock; the slack only absorbs clock granularity. */
+export declare const CREATED_AFTER_SLACK_MS = 5000;
 export interface LockOwner {
     pid: number;
     host: string;
@@ -22,6 +26,9 @@ export interface StartTokenProbe {
     self: string | null;
     of: (pid: number) => string | null;
     platform?: NodeJS.Platform;
+    /** When the process now holding `pid` was created (wall-clock ms), or null.
+     *  Defaults to the OS probe `processStartedAt`. */
+    startedAt?: (pid: number) => number | null;
 }
 export declare class WriteLockTimeout extends Error {
     readonly path: string;