@davesheffer/hunch 1.32.2 → 1.32.3

package/README.md

@@ -183,7 +183,7 @@ Hunch may hold durable state **about** external work with credential-free proven
 
 The first real-world pilot is **Sofia**, a working operations agent over CRM, Gmail and WhatsApp. Sofia's approved actions, follow-ups, customer/source relationships and cited summaries map naturally to action receipts, commitments, entities/relationships and dependency-bound state.
 
-The pilot measures whether Sofia and a second, different agent stop re-deriving contradictory state when the deterministic state is delivered before they answer or act.
+The pilot measures whether Sofia and a second, different agent stop re-deriving contradictory state when the deterministic state is delivered before they answer or act. First live number (2026-09-12, one user): after one CRM read, the next status questions were answered from held state under a receipt, 0 of 3 without a source; the [roadmap](ROADMAP.md) carries the gate table.
 
 ### The state contract, shipped
 
@@ -223,7 +223,7 @@ The current release can keep a team's **repository-scoped** memory in a dedicate
 Today Hunch does not host that shared Git repository; teammates/CI use normal Git access and one maintainer connects it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.28.0
+npm i -g @davesheffer/hunch@1.32.2
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -233,7 +233,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.28.0
+npm i -g @davesheffer/hunch@1.32.2
 git pull
 hunch init
 hunch doctor
@@ -264,6 +264,8 @@ The v1.19 correction-search benchmark remains scoped evidence, but it no longer
 - **v1.21 — Project DNA.** Hunch gained deterministic, revision-specific repository profiles, bounded DNA context delivery, explainable Project Match checks and auditable profile deltas.
 - **v1.22 — authorized collaboration evidence.** Hosts can contribute bounded PR/review evidence to Project DNA through a typed, sealed contract without raw collaboration persistence or policy-authority change.
 - **v1.23 — native change proof and proof-carrying evidence work.** Exact Git change identity, graph before/after, decisions/constraints, blast radius and Change Gate result can be bound into a sealed evidence artifact without granting authority.
+- **v1.25 – v1.30 — the state layer.** `nuryel.state/1` as code, `hunch serve` partitions, union reads, subject identity by external reference, replay determinism, human corrections outranking agent writes.
+- **v1.32 — see what Hunch contributed.** Task contribution reports: what was delivered, what the agent reports it applied, what a rule verified, what a command observed; concise card, local evidence view.
 
 See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.md) for active work.
 
@@ -277,6 +279,9 @@ See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.m
 - [Project DNA](docs/project-dna.md)
 - [Native change proof](docs/change-proof.md)
 - [The autonomy ladder](docs/autonomy-ladder.md)
+- [Task contribution reports](docs/task-reports.md)
+- [Autonomous development](docs/autonomous-development.md)
+- [Local cookbook](docs/cookbook.md)
 - [Engineering Landscape Graph](docs/engineering-landscape.md)
 - [Hunch roadmap](ROADMAP.md)
 - [VS Code extension](vscode-extension/README.md)

package/dist/core/stateContract.d.ts

@@ -961,6 +961,9 @@ export declare const STATE_INVARIANTS: readonly [{
 }, {
     readonly id: "derived-state-writer-owns-currentness";
     readonly statement: "No source writes the drawer. The writer of a current derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. Without this duty an agent may capture source-backed observations only as unknown; observations never assert currentness.";
+}, {
+    readonly id: "one-current-derived-per-subject-transform";
+    readonly statement: "A subject holds at most one current derived statement per transform: a new one must name the incumbent in supersedes (refused 409 with the incumbent named otherwise); the same identity written again updates or replays that record.";
 }];
 /** The memory supply chain's top tier: a record whose provenance a human signed. Same tier rule
  *  as the strict gate's (strictgate.isHumanConfirmed), applied to a record instead of a source. */

package/dist/core/stateContract.js

@@ -306,6 +306,7 @@ export const STATE_INVARIANTS = [
     { id: "one-entity-per-external-ref", statement: "One external record is one entity in a partition: a second active entity carrying an external key an incumbent already carries is refused with the incumbent named, and a subject written as that record's external key is refused with the entity's id named. Identity is explicit refs, never similarity; merge is explicit — a retired entity names the survivor in `merged_into`, the ledger holds the `retired` event, nothing under the old id is rewritten and reads resolve to the survivor — and split is the explicit reverse; never a silent rewrite." },
     { id: "human-correction-outranks-agent-writes", statement: "A record a human confirmed is never overwritten or superseded by an agent or service principal: the agent may replay it, write derived state back stale with the external cause that moved, or close a commitment with a receipt on record. Changing what the human said takes a human." },
     { id: "derived-state-writer-owns-currentness", statement: "No source writes the drawer. The writer of a current derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. Without this duty an agent may capture source-backed observations only as unknown; observations never assert currentness." },
+    { id: "one-current-derived-per-subject-transform", statement: "A subject holds at most one current derived statement per transform: a new one must name the incumbent in supersedes (refused 409 with the incumbent named otherwise); the same identity written again updates or replays that record." },
 ];
 const grantKey = (scope) => scopePath(scope);
 /** The memory supply chain's top tier: a record whose provenance a human signed. Same tier rule

package/dist/extractors/git.js

@@ -509,6 +509,14 @@ const READ_REMOTE_TIMEOUT_MS = 5_000;
 // drains every already-durable JSON write itself. This removes the old "maybe a
 // third capture sweeps it later" liveness hole.
 const CAPTURE_LOCK_HANDOFF_MS = 120_000;
+/** Longest one git call inside a memory flush may take before it is stopped and the flush
+ *  reports durability "local" (HUNCH_COMMIT_GIT_TIMEOUT_MS overrides; tests use a short one). */
+const COMMIT_GIT_TIMEOUT_MS = 60_000;
+const SLOW_FLUSH_MS = 5_000;
+function commitGitTimeoutMs() {
+    const raw = Number(process.env.HUNCH_COMMIT_GIT_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : COMMIT_GIT_TIMEOUT_MS;
+}
 function unsafeOverlayPublication(hunchDir, protectedRepoRoot) {
     let currentOverlayRoot = dirname(resolve(hunchDir));
     try {
@@ -566,10 +574,21 @@ export function commitAndPushHunch(hunchDir, message, opts) {
             for (let attempt = 0; attempt < 2; attempt++) {
                 const startedAt = Date.now();
                 try {
-                    execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+                    // A served write blocks on this call: bound it, and never let a commit trigger git's
+                    // automatic gc (minutes of repacking inside one write, fnd_4318727d35). A timed-out
+                    // call returns false, the flush reports durability "local", and the next flush
+                    // sweeps the same files up — nothing is lost, and the server is not frozen.
+                    execFileSync("git", ["-C", hunchDir, "-c", "gc.auto=0", ...args], { stdio: "ignore", env, timeout: commitGitTimeoutMs() });
+                    const took = Date.now() - startedAt;
+                    if (took > SLOW_FLUSH_MS)
+                        console.error(`hunch: git ${args.find((a) => !a.startsWith("-") && a !== "core.autocrlf=false") ?? args[0]} in "${hunchDir}" took ${took} ms`);
                     return true;
                 }
                 catch (error) {
+                    if (error.signal === "SIGTERM" || error.code === "ETIMEDOUT") {
+                        console.error(`hunch: git ${args.find((a) => !a.startsWith("-")) ?? args[0]} in "${hunchDir}" exceeded ${commitGitTimeoutMs()} ms and was stopped; the write stays local until the next flush`);
+                        return false;
+                    }
                     // best-effort: nothing staged / not a repo / offline — EXCEPT a
                     // stranded index.lock, which would otherwise fail every future
                     // flush silently (issue #53); heal it and retry once.
@@ -623,7 +642,7 @@ export function commitAndPushHunch(hunchDir, message, opts) {
         const staged = stagedMemoryPaths(hunchDir, env, opts.push !== false);
         if (staged === null) {
             try {
-                execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env });
+                execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env, timeout: commitGitTimeoutMs() });
             }
             catch { /* best-effort unstage */ }
             // Public-store commits (push:false) skip QUIETLY: a non-memory staged set there is
@@ -691,8 +710,9 @@ export function commitAndPushHunch(hunchDir, message, opts) {
                     ...(opts.push === false ? [] : ["-c", `core.attributesFile=${gitNullDevice()}`]),
                     "-c", "core.autocrlf=false",
                     "-c", "commit.gpgsign=false",
+                    "-c", "gc.auto=0",
                     "commit", "--no-gpg-sign", "--only", "-m", message, "--", ...commitPaths,
-                ], { stdio: "ignore", env, timeout: 15_000 });
+                ], { stdio: "ignore", env, timeout: commitGitTimeoutMs() });
                 committed = true;
             }
             catch (error) {
@@ -775,7 +795,7 @@ function stagedMemoryPaths(hunchDir, env, allowMemoryDeletions = false) {
     let out = "";
     let prefix = "";
     try {
-        prefix = execFileSync("git", ["-C", hunchDir, "rev-parse", "--show-prefix"], { encoding: "utf8", env }).trim().replace(/\\/g, "/");
+        prefix = execFileSync("git", ["-C", hunchDir, "rev-parse", "--show-prefix"], { encoding: "utf8", env, timeout: commitGitTimeoutMs() }).trim().replace(/\\/g, "/");
     }
     catch {
         return null;
@@ -786,7 +806,7 @@ function stagedMemoryPaths(hunchDir, env, allowMemoryDeletions = false) {
     // heuristic rename presentation so the exact paths remain independently
     // auditable against the contained-memory rules below.
     try {
-        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-renames", "--name-status"], { encoding: "utf8", env });
+        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-renames", "--name-status"], { encoding: "utf8", env, timeout: commitGitTimeoutMs() });
     }
     catch {
         return null;

package/dist/store/stateBinding.js

@@ -806,6 +806,22 @@ export function writeState(store, input, opts = {}) {
             supersedes = null; // already closed by this record: nothing to close again, no second "superseded" event
         }
     }
+    // one-current-derived-per-subject-transform: a NEW current derived statement on a subject that
+    // already holds a current statement under the same transform must name it in `supersedes`.
+    // Otherwise a writer that never names its predecessor leaves a growing pile of "current"
+    // statements that every reader has to reconcile (season finding fnd_1939ced249: up to 58 on
+    // one subject over half a year). Writing the same identity again is an update or a replay of
+    // that record and is not affected; a different transform is a different statement.
+    if (facet === "derived" && record.state === "current") {
+        const d = record;
+        const incumbent = store.recsInHome("derived", home).find((r) => {
+            const x = r;
+            return x.id !== id && x.id !== supersedes && x.subject === d.subject && x.transform_version === d.transform_version && x.state === "current" && x.valid_to === null;
+        });
+        if (incumbent) {
+            throw new StateRefusal("conflict", `${d.subject} already has a current ${d.transform_version} statement ${incumbent.id}; pass supersedes: "${incumbent.id}" to replace it, or write that identity to update it`, { incumbent_id: incumbent.id, reason: "one-current-derived-per-subject-transform" });
+        }
+    }
     // The chain (Gate 4): a receipt names what it rested on, a closure names the receipt.
     // Both are checked against the drawer, grants first, before anything lands.
     if (facet === "receipts")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.32.2",
+  "version": "1.32.3",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.32.2",
+  "version": "1.32.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.32.2",
+      "version": "1.32.3",
       "runtimeHint": "npx",
       "packageArguments": [
         {