@dzhechkov/harness-core 0.8.34 → 0.8.35

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7fb2af101753ac28e469a24a8f15789d0235d5749dd3a3cda42422d61ff13c0d"
+          "content": "37a3aab588b4b12b15d2d67a014abec49ae38615a1d28816310d5f2e6ad29f79"
         }
       ]
     },
@@ -75,7 +75,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6e86eca1e1b3db58f83c5e60b3af2943cb97a7365eb9754825b3e2fcdde5fe22"
+          "content": "179cd2dee305664b3c8365b4a8dcd64015b4e226b2753c6dd1e42769b4d0c96f"
         }
       ]
     },
@@ -85,7 +85,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "601500870a060848fd75912b8473b1d715ab4c97ea1d8c91db0711e0a0ebf352"
+          "content": "1e366365fadabe345c7d128da0250a4a21dc7e4924d1cc04f457fd38b40d3c72"
         }
       ]
     },
@@ -95,7 +95,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fdb88618197b66d9b107c50ac75b625e23a4498ddb20d13d8e9168d7e6aee790"
+          "content": "bbcee70ee0aa52d95960956a5692cff81d296e49083487c0bbfd3c3d93c94f9c"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8ada5fd59f070ece1436c97b0d4e96bc9067a2ab042a06637a4592ee9fcf74e9"
+          "content": "02208be0504446c12852720a17f99df8d64e69ba759a55f2ea4095ea19fa2f37"
         }
       ]
     },
@@ -315,7 +315,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7d405581035820ac6e35fc3acf30685fb66f97120f4222d4389e81182cb234b6"
+          "content": "9cc4cf39b4ef8479eba5745c767c60a8a331f777e19251ec9faf42530f16b7c7"
         }
       ]
     },
@@ -325,7 +325,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1ec81dba7e182385ee9cebd1d4c41128915549797fb07bbff0cc540b7f72287a"
+          "content": "5204913b80c8748926f20a1632658720b75336fcd7bdf15114ceb1707fde804c"
         }
       ]
     },
@@ -335,7 +335,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "94a7c64d577a8134413cd508b37ec346cf729571b86b0d0cb55168d9a67f7a76"
+          "content": "f3e74e03e325569237340aace076e4e0507d12b48d47dcced7a836242ae13ac9"
         }
       ]
     },
@@ -345,7 +345,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cc1ed9820f186de277c75bbcffd102e651e34283a7728307d4c377ad7e207b7a"
+          "content": "300050992853dba6e5cdd4dc54e66d77a506ac3750d81ed2d3da560086830e99"
         }
       ]
     },
@@ -2595,7 +2595,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0ec8aabd62c19b421d56b9ddfc3a769ca88a6edad072e6b458a9ec0dce144847"
+          "content": "5476546b291c2df0a0a4e3afd7b64900ada0b7ab26d400ae6fb6985853466c72"
         }
       ]
     },
@@ -2605,7 +2605,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d55811cc24161673964196697f78774b618ceff986f12d61233129af1309a06e"
+          "content": "593859b38d79431517940bccf25f5e8ae079e142ac6cb66396b38421555a1d17"
         }
       ]
     },
@@ -2615,7 +2615,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "db5d3897a75a8b5f41e4d63fc2b89e1ba0ad59d81c9ec7409f4a4e4bcaef3ed2"
+          "content": "a7264b451ffa98a04e54d23e83312abe3afe1f380b088e386841ea4325938596"
         }
       ]
     },
@@ -2625,7 +2625,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7ed1c3d692bf9f60b3239b2ec714552c524139f98a666529c1c614c00b1928a2"
+          "content": "67861fde05a1927927ab1951738fbed427a2d016b22433603136041df21b3f0d"
         }
       ]
     },
@@ -3515,7 +3515,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "815a03f89f6cae322f4cb0d84ef58823bdb8fae9a18889cde68b8d6e878dc736"
+          "content": "a77bd4063914f6dc09487990423e64c8186c5bc48b5285867852c905653605f4"
         }
       ]
     },
@@ -3525,7 +3525,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "de00794a601552c629e2a588de98b3a03a58c00ec73d87167dc8df430ae09a29"
+          "content": "6e414fbaee4a6ed940620fb44cb8c39a2fd945e32a966f8141f1923ec242bed3"
         }
       ]
     },
@@ -3535,7 +3535,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "88e9371ce15d5ead058a597dc49db25d2ef988479dcb278929559e851088206c"
+          "content": "36dc04b58621a090dadaeefbd8d40e73196875f28a84f130f08bcad9b3ebcb53"
         }
       ]
     },
@@ -3545,7 +3545,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "25379eb4fbe99792355a8164cab04f68585b9450ae3426109eefd0ee4b10da6b"
+          "content": "64c71e44dd9635b4480f0e64c27cf510c2859890b03f1a00ce555b438e365090"
         }
       ]
     },
@@ -3715,7 +3715,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7e2c8371b6ef88ab84ec325d54b0c89c1cb6825bc4b953d134f5fb36368038db"
+          "content": "60bd3d2d8ddc18535260e2b790ee25e6ddb77eab597248f05948987d7d5a39eb"
         }
       ]
     },
@@ -3725,7 +3725,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5e21fd824b54842ab455e1c2b4d381d3ba81eaefb37ee525ab44b61f3e1a4719"
+          "content": "f8021977e02820666664922176bca714047fc544c8b466f3956aae854e53dd53"
         }
       ]
     },
@@ -3735,7 +3735,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cb895bd26042f722c29594f1c5d0db6471146516745de6b366ed3b1a06af1906"
+          "content": "76105d806137ef947694e1cb10b2e8360411bd873e74386e87d933c99f53bbb3"
         }
       ]
     },
@@ -3745,7 +3745,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3d7103bd1f9c96aefe9ade44d53a321ae5c057171a6556b228350fc3faf74f33"
+          "content": "acbb9920848e738a286eff1f45ebdd3a9f5e3b09fec879567072573df15d171b"
         }
       ]
     },
@@ -5445,7 +5445,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "baefa9d4a927880e51b8dc9ec4b899e7625c029de82ed397501b32cb1d3e925a"
+          "content": "3b8f5dc584a26b53be9f1e68cb8fffaaf68decbe1cf4b634f78c8ec0f3725b3d"
         }
       ]
     },
@@ -5455,7 +5455,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6f8cbb59ffc98b5f8722134b9b28b4d2bd5d847fe50edc38d2f539ebc9980151"
+          "content": "8644f836c6236867d8f238cf48465506361647f11bc58b50134a7a862b7e711a"
         }
       ]
     },
@@ -5465,7 +5465,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f859ac7532e6b9d2232fbdbe6f7b3cb5e0a739842bc70024544c9263f78ec67e"
+          "content": "3bafd2f8eb1c3305be28c42d59365dc58751d199b5e702b69c581c5df7b97560"
         }
       ]
     },
@@ -5755,7 +5755,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8b3b61f8d0bb9ff1a9426f8721cda72b6685a7097153f52e31b73854a570d9f1"
+          "content": "e2ee030cc763d5e909855239129aad5275aa42c9128458320759d321174fd697"
         }
       ]
     },
@@ -5765,7 +5765,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "485f603831e9a2feea38f7a4c7ed0c45f530c1ff8a2ac1d5cd04b3498d40f465"
+          "content": "857485e66830cc7a31e80a9a1b86614c5a02ceb074e7b209dbe62f12059f3198"
         }
       ]
     },
@@ -5775,7 +5775,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e72d99a4e16bf0c4d483e4b1b9aafee2c3a38a4861cddd8be81d20ccbe240613"
+          "content": "9659576b23f1c2f47cf5f6f78857495e44c89fffa4fc2010f6ded703e126738d"
         }
       ]
     },
@@ -5785,7 +5785,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "27188e499f4d04661dbb8ba6da4a8eb3d94fccd4171b3059c4e26334aae9f946"
+          "content": "f51408fe56f037d19219a828a5adba28f2bbe05337c3042d4fa25888ab31101b"
         }
       ]
     },
@@ -6645,7 +6645,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2943b848f7af427dcfecf801a778fe7eb2a6f899e395956aca5f45a9fcce3d79"
+          "content": "8c504e223d4d78a29a24993078f4a90e771f56d6a62b310ab90b7ba44f1a6bd5"
         }
       ]
     },
@@ -6655,7 +6655,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a48e13d799185bc95134a23cbe7d9ee91f9dcaf64c1c7c5faa4cf45a4cf94d08"
+          "content": "6554f0bd2566ac10e6c841732210daa2412028e520ce49acf197451024161382"
         }
       ]
     },
@@ -6665,7 +6665,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9a74e49879f494f01aec757b4efe0f41245cf20cf1cc4e07123852f6939463cf"
+          "content": "23de503688790bbe679dae6c72b3c77faa43a14d4d0fbc54946c2e35cfd2d543"
         }
       ]
     },
@@ -6839,7 +6839,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "26a1b1c5cd3d01ea854d9fb9ef126fe3cfd6580a52d0a1c7b60f4dffcc280d8d"
+          "value": "273067dfe330063f7f449dea7480208e147a20eb7b554f921d1eb9ee33cb8ca4"
         }
       ]
     },
@@ -6859,7 +6859,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f3b7a86fc7ec49fc7b47d69a6beb4ace4e193f9a4b63237b257a7cae1879d4f7"
+          "content": "388fce3f17382373d5864dccc0c8685c1779d1101a490399ccbacb3bd6c1a2f5"
         }
       ]
     },
@@ -6919,7 +6919,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d0bc07ff16397b8d0d6b26fd72a770553f421902b81e3d5e775e08b4db4710a3"
+          "content": "9391b6e0d9f6ef3f39662d4f3c89dbc173881584c6956ad5add2ebd54cdc85cf"
         }
       ]
     },
@@ -7499,7 +7499,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a2ae53ebaa9993545153419f615db85f7a2d412f61deddb44780773e8ea52be2"
+          "content": "f248dbc9f0fc735dcfe11ae399c8f7c52b4053bb10e29234dc27c6c9581b7945"
         }
       ]
     },
@@ -7739,7 +7739,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7a26f7f745ca6f8d0a3dcf9d32ff8b9acc9c37c106b411ff292690544ac1ddd5"
+          "content": "0e777534524e5042bcdb8eef9c5f3d23c5fd0f94e2fe45a52623f3122a5dedef"
         }
       ]
     },
@@ -7789,7 +7789,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9f20a5a9c3e6ff41245612f74f04f62e719744fab2f97ee9d93fcdf4fa52668b"
+          "content": "8143fae14dbfcf0e87bf148add74e16e0ee8c2f8064fd2bfb0f90fbf1a21889b"
         }
       ]
     },
@@ -8209,7 +8209,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "795f796ad5093244807d5fd0c80478c89e28e3e3ef26540e8f636eb24d517038"
+          "content": "0f44ef0d05c0ffabffe5e0f4fb4539b67fd72f62b42206d68bc98199ea718dcd"
         }
       ]
     },
@@ -8289,7 +8289,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cb1fc2b2f904e6c40ef7ba481c4ca2e9072b31302015134f4e636f67323c89d8"
+          "content": "1dac38f95d956aa315554f6d7559e141a7acbebdab8c39d7f9880c3eae0f1f28"
         }
       ]
     },
@@ -8519,7 +8519,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6086c8aabf98d69d9fc7d8b22d88dfbe1588ac1a4e2ddae66a3738e02dc638f2"
+          "content": "6607b712f768be25a140f224dc6c3c80d25e0e5144898fb819d488da7f0cd600"
         }
       ]
     },

package/src/agentdb-index.ts

@@ -12,7 +12,7 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, copyFileSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, realpathSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
 import { join, dirname, resolve, relative, isAbsolute, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -23,7 +23,7 @@ import { applyReadonlyPragmas } from './sqlite-read-helpers.js';
 import { rotatePreReindexSnapshotsUnlocked, type SnapshotRotationReport } from './agentdb-snapshot-rotation.js';
 import { snapshotSqliteDatabase, restoreSqliteSnapshot, type SnapshotMethod, type SnapshotDbCtor } from './agentdb-snapshot.js';
 import { withAgentdbSnapshotLock, writeReindexMarker, clearReindexMarker, markReindexMarkerRecoveryRequired, reindexMarkerPath, msFromBackupPath } from './agentdb-reindex-marker.js';
-import { NamedLockTimeoutError } from './named-lock.js';
+import { NamedLockTimeoutError, withNamedLockSync } from './named-lock.js';
 import type { StoreLockOptions } from './store-lock.js';
 // The backlog dedup embed form (PURE, zero-dep — no cycle): dz-backlog rows must be embedded in the
 // SAME bounded form the dedup query uses, including through the reindex path.
@@ -48,10 +48,14 @@ export interface AgentdbRow {
   readonly avgReward?: number;
 }
 
-/** Outcome of {@link indexPatternsToAgentdb}. */
+/** Outcome of {@link indexPatternsToAgentdb}. `generationBumped`/`generationReason` are present only
+ * when a store write actually happened (`indexed > 0`) — FR-4: a failed counter write NEVER fails
+ * the indexing call itself, it is only reported so a caller (`dz doctor`, telemetry) can see it. */
 export interface AgentdbIndexResult {
   readonly indexed: number;
   readonly error?: string | undefined;
+  readonly generationBumped?: boolean;
+  readonly generationReason?: string;
 }
 
 interface NativeDb {
@@ -135,6 +139,112 @@ export function ensureAgentdbSchema(projectRoot: string, dbPath?: string): { rea
   }
 }
 
+/** `<dbFile>.generation` — a sidecar counter next to the store itself, so it travels with any copy
+ * of `.dz/agentdb.db` (backup, mirror sync) without a separate path to keep in sync. */
+function generationFilePath(dbFile: string): string {
+  return `${dbFile}.generation`;
+}
+
+/** AM-5 (fix-round): the ONLY shape {@link readStoreGeneration} trusts — one or more ASCII digits,
+ * nothing else. `Number.parseInt` alone accepts a leading-numeric-with-trailing-junk string like
+ * `"12junk"` as `12`; that reads a corrupt sidecar as a plausible generation instead of degrading to
+ * the documented `0` compatibility floor. */
+const STRICT_GENERATION = /^\d+$/;
+
+/**
+ * FR-2/FR-3 (`store-generation-counter`): the store's write-generation counter, read back. A
+ * missing file (a store that predates this feature, or one that has never been written through
+ * {@link bumpStoreGeneration}) reads as `0` — the compatibility floor {@link getOrOpenEngine}'s
+ * caller compares against, never an error. A corrupt/non-numeric file degrades the same way (best
+ * effort — a bad counter must never crash a read path), never a throw. AM-5: the content must match
+ * {@link STRICT_GENERATION} exactly — `Number.parseInt`'s leading-digits-only tolerance is NOT used
+ * to decide validity, only to convert an already-validated string.
+ */
+export function readStoreGeneration(projectRoot: string, dbPath?: string): number {
+  try {
+    const raw = readFileSync(generationFilePath(resolveAgentdbPath(projectRoot, dbPath)), 'utf8').trim();
+    if (!STRICT_GENERATION.test(raw)) return 0;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * FR-1 (`store-generation-counter`): monotonically advance the store's write-generation counter by
+ * one (absent file ⇒ starts at 1), atomically (tmp + rename — the same durability discipline every
+ * other sidecar file in this module uses; a reader can never observe a half-written counter) AND
+ * under mutual exclusion (AM-2, fix-round after Codex review). A bare read→compute→rename with no
+ * lock lets two concurrent writers both read the same current value and both publish `current+1` —
+ * one bump is lost — or lets a DELAYED writer overwrite a later value with an earlier one (the
+ * counter briefly goes backwards on disk). `withNamedLockSync` (`named-lock.ts`, the repo's
+ * advisory lock for a read-modify-write file store — `.claude/rules/cross-runtime-concurrency.md`)
+ * serializes the critical section; the counter is RE-READ from disk *inside* the lock (never trusted
+ * from before acquisition), so the sequence every process observes is strictly monotonic
+ * (`agentdb-reindex-marker.ts`'s `withAgentdbSnapshotLock` is the precedent this mirrors — a lock
+ * addressed by `dirname(dbFile)`, a pure function of the store's own directory, never of
+ * `process.cwd()`).
+ *
+ * NEVER throws (FR-4): a write failure (read-only `.dz`, a full disk, a permissions error, an
+ * unresolvable path, OR a lock that could not be acquired by its deadline) is reported honestly as
+ * `{ok:false, error}` so the caller can log it — the store write it accompanies must stay successful
+ * regardless, telemetry is never a gate. AM-4: {@link resolveAgentdbPath} itself now runs INSIDE this
+ * function's outer `try` — an unresolvable path can no longer throw OUT of `bumpStoreGeneration`
+ * either; "never throws" now covers the whole function, not just the file-write tail.
+ */
+/** Codex round-2 (NEW HIGH): most mutators discard the bump result, so a failed bump must be
+ * VISIBLE on its own — one stderr line, written by the helper itself. Telemetry never throws. */
+function reportBumpFailure(error: string): { readonly ok: false; readonly error: string } {
+  try { process.stderr.write(`dz: store generation not bumped — ${error}\n`); } catch { /* telemetry never throws */ }
+  return { ok: false, error };
+}
+
+export function bumpStoreGeneration(
+  projectRoot: string,
+  dbPath?: string,
+): { readonly ok: true; readonly generation: number } | { readonly ok: false; readonly error: string } {
+  try {
+    const dbFile = resolveAgentdbPath(projectRoot, dbPath);
+    const genFile = generationFilePath(dbFile);
+    return withNamedLockSync(
+      dirname(dbFile),
+      'store-generation',
+      (): { readonly ok: true; readonly generation: number } | { readonly ok: false; readonly error: string } => {
+        // AM-2: re-read the CURRENT value from disk while holding the lock — a value observed before
+        // acquisition may already be stale, another holder may have advanced it in the meantime.
+        let current = readStoreGeneration(projectRoot, dbPath);
+        const tmp = `${genFile}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        try {
+          // Codex round-2 (AM-2 residual): a sidecar that EXISTS but is corrupt reads as 0 and would
+          // reset the counter to 1 — a value an engine-cache entry may already be keyed on. Floor a
+          // corrupt value at a wall-clock stamp instead: still monotonic (ms since epoch exceeds any
+          // count reached by bumping) and never colliding with an earlier generation. Absent file ⇒ 1.
+          if (current === 0 && existsSync(genFile)) {
+            const raw = readFileSync(genFile, 'utf8').trim();
+            if (raw !== '0' && !STRICT_GENERATION.test(raw)) current = Date.now();
+          }
+          const next = current + 1;
+          mkdirSync(dirname(genFile), { recursive: true });
+          writeFileSync(tmp, String(next), { encoding: 'utf8', flag: 'wx' });
+          renameSync(tmp, genFile);
+          return { ok: true, generation: next };
+        } catch (err) {
+          // Best-effort cleanup of a half-written temp file (e.g. rename failed after a successful
+          // write) so it never lingers as clutter — never lets a cleanup failure mask the real error.
+          try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* best-effort only */ }
+          return reportBumpFailure(`store generation bump failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      },
+    );
+  } catch (err) {
+    // AM-2/FR-4: a lock that could not be acquired by its deadline (`NamedLockTimeoutError`) — and
+    // any other failure reaching this point (an unresolvable path, AM-4) — degrades to the same
+    // honest `{ok:false, error}` shape; it never throws into the store write it accompanies.
+    return reportBumpFailure(`store generation bump failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 /**
  * Index `rows` into the shared AgentDB vector store. Returns `{indexed:0}` for an empty input and
  * `{indexed:0, error}` when `agentdb`/`better-sqlite3` cannot be resolved from the project.
@@ -218,8 +328,19 @@ export async function indexPatternsToAgentdb(
         return prepared.length;
       });
       const indexed = commit() as number;
+      // AM-3 (fix-round): bump the generation IMMEDIATELY after the commit — BEFORE
+      // `writeEmbedManifest` — not after it. The store already changed on disk the instant `commit()`
+      // returned; if the manifest write throws (a jammed manifest path, a full disk), the OLD order
+      // left the DB changed with no generation ever published — a stale-cache read would then serve
+      // an engine that never saw this write, with no signal anywhere that anything went wrong. Moving
+      // the bump here makes "the store changed" and "the generation reflects it" atomic in effect:
+      // whichever of the two calls below throws, the generation is already correct for the rows that
+      // are already on disk.
+      const bump = bumpStoreGeneration(projectRoot, opts.dbPath);
       writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
-      return { indexed };
+      return bump.ok
+        ? { indexed, generationBumped: true }
+        : { indexed, generationBumped: false, generationReason: bump.error };
     } finally {
       db.close();
     }
@@ -726,6 +847,12 @@ export async function importVectorsToAgentdb(
         return imported;
       });
       const imported = commit();
+      // AM-1 (fix-round): `importVectorsToAgentdb` is the write-half of `dz vector import` — it
+      // changes `pattern_embeddings`/`reasoning_patterns` exactly like `indexPatternsToAgentdb`, so
+      // it must bump the SAME counter (the whole point of a single "did the store change" signal is
+      // that every writer feeds it, not just one). Ordered before `writeEmbedManifest`, same AM-3
+      // rationale: the rows are already on disk by the time `commit()` returns.
+      bumpStoreGeneration(projectRoot, opts.dbPath);
       writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
       return { imported };
     } finally {
@@ -773,7 +900,14 @@ export function clearAgentdbQuarantine(
         }
         return cleared;
       });
-      return { cleared: tx() };
+      const cleared = tx();
+      // AM-1 (fix-round): a quarantine clear mutates `metadata` on rows the hook daemon reads
+      // straight from this mirror (see the doc comment above) — it changes what a query returns, so
+      // it must bump too, exactly like every other mutator. Only when something actually changed
+      // (`cleared > 0`) — same "no write, no bump" discipline as `indexPatternsToAgentdb`'s
+      // empty-rows case (AC-2).
+      if (cleared > 0) bumpStoreGeneration(projectRoot, opts.dbPath);
+      return { cleared };
     } finally {
       db.close();
     }
@@ -829,7 +963,11 @@ export function deleteAgentdbByDzIds(
         }
         return deleted;
       });
-      return { deleted: tx() };
+      const deleted = tx();
+      // AM-1 (fix-round): a DELETE removes rows from a query's result set exactly as surely as an
+      // INSERT adds them — it must bump too. Only when rows actually left the store (`deleted > 0`).
+      if (deleted > 0) bumpStoreGeneration(projectRoot, opts.dbPath);
+      return { deleted };
     } finally {
       db.close();
     }
@@ -874,7 +1012,13 @@ export function bumpAgentdbUses(
         }
         return bumped;
       });
-      return { bumped: tx() };
+      const bumped = tx();
+      // AM-1 (fix-round): `uses`/`avg_reward` feed reward-weighted ranking — a change here is a real
+      // store mutation, so it bumps the SAME counter (deliberately NOT named `bump` — that identifier
+      // is this function's own return value; the counter helper is called by its full name below to
+      // avoid the collision). Only when a row actually changed (`bumped > 0`).
+      if (bumped > 0) bumpStoreGeneration(projectRoot, opts.dbPath);
+      return { bumped };
     } finally {
       db.close();
     }
@@ -1157,6 +1301,13 @@ export async function reindexAgentdbRows(
       if (!(err instanceof NamedLockTimeoutError)) throw err;
       snapshots = { kept: [], removed: [], removedBytes: 0, keep: keepSnapshots, errors: [`lock busy: ${err.message}`] };
     }
+    // AM-1 (fix-round): `reindexAgentdbRows` is itself a mutator (the DELETE above rebuilds the
+    // owned task types) — it must not rely SOLELY on `indexPatternsToAgentdb`'s own internal bump,
+    // because that call is a no-op (and bumps nothing) when `rows` is empty, yet the DELETE it ran
+    // just above unconditionally changed the store. Bumping again here when `rows` was non-empty
+    // (the common case, already bumped once inside `indexPatternsToAgentdb`) is harmless — the
+    // counter is a monotonic "did anything change" signal, not a per-operation tally.
+    bumpStoreGeneration(projectRoot, opts.dbPath);
     return {
       reembedded: indexed.indexed,
       model: model.model,