claude-mem-lite 3.82.0 → 3.84.0

package/hook.mjs

@@ -29,6 +29,13 @@ import {
   formatErrorRecallHints,
   MAX_HOOK_STDIN_BYTES,
 } from './utils.mjs';
+// Direct import (not via the utils.mjs barrel): the barrel's re-exports are a v2.21
+// backward-compat surface that knip already lists as unused; new shared symbols go to
+// their canonical module.
+import { inferProjectDir } from './project-utils.mjs';
+// Aliased: `acquireLock` from hook-episode.mjs below is the episode buffer's own
+// (argument-less) lock — a different mutex with a different staleness policy.
+import { acquireLock as acquireProcLock } from './lib/proc-lock.mjs';
 import {
   readEpisodeRaw, episodeFile,
   acquireLock, releaseLock, readEpisode, writeEpisode,
@@ -39,7 +46,7 @@ import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-con
 import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
-  SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS,
+  SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS, AUTO_MAINTAIN_LOCK,
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT,
   sessionFile, getSessionId, createSessionId, openDb,
   spawnBackground, sweepOrphanEpisodeFiles, sweepStaleProjectMarkers,
@@ -56,6 +63,7 @@ import { snapshotDb } from './lib/db-backup.mjs';
 import {
   extractCitationsFromTranscript,
   extractInjectedBySurface,
+  buildCitationRelevanceSet,
   unionSurfaces,
   extractInjectedFromKeyContext,
   bumpCitationAccess,
@@ -70,6 +78,7 @@ import { resolveEdgeAttribution, readPreRecallFileEdges } from './lib/edge-attri
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
 import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from './hook-memory.mjs';
 import { searchInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
+import { upsFtsQuery } from './lib/ups-query.mjs';
 import { formatTaskImperative } from './lib/task-imperative.mjs';
 import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
@@ -216,27 +225,124 @@ function flushEpisode(episode, hookEventName = 'PostToolUse') {
   }
 }
 
-function flushEpisodeWithDb(db, episode, hookEventName) {
-  // Collect Read file paths tracked by post-tool-use.sh
-  // Use rename to atomically collect — prevents losing concurrent appends
-  const readsFile = join(RUNTIME_DIR, `reads-${episode.project || inferProject()}.txt`);
-  const readsCollect = readsFile + `.collect-${Date.now()}`;
+// D#178 safety valve. With CLAUDE_MEM_READS_CARRY on, an insignificant flush leaves
+// `reads-<project>.txt` in place, so a long insignificant streak keeps appending to it.
+//
+// THE CAP COUNTS LINES, NOT DISTINCT PATHS, and that is the whole point. The writer
+// (`scripts/post-tool-use.sh`) appends one line per Read with no dedup, so the file grows
+// by REPEATED lines — a session re-reading the same five files forever. The first draft
+// compared the DISTINCT set against the cap, which is the quantity that stays tiny
+// (measured on the live corpus: median 1, p95 6, max 21 carried paths), so the valve could
+// not fire on the growth mode it exists to bound. That is this repo's recurring
+// "predicate that cannot return true reports the defect as absent" shape, and the pre-tag
+// review caught it here.
+//
+// Still a backstop and not a relevance bound — the same distinction
+// IMPERATIVE_POOL_BACKSTOP documents for its pool.
+const READS_CARRY_MAX_LINES = 20000;
+
+/**
+ * Bound the reads file when an insignificant flush leaves it in place. Rewrites it only
+ * when it is over READS_CARRY_MAX_LINES raw lines, keeping the newest distinct paths.
+ *
+ * @param {string} readsFile
+ * @returns {number} distinct paths now held; 0 when there is no reads file (the COMMON
+ *   case — no Read since the last collect); -1 only when the file exists but could not be
+ *   read or the trim threw. The three-way split is the point: `episode_reads` is the ruler
+ *   for this flag, and folding "nothing to hold" together with "could not look" would put
+ *   the normal case and the broken case on the same value. A first draft returned -1 for
+ *   both, which made -1 the overwhelmingly common reading and hid the failure inside it.
+ */
+function trimReadsFile(readsFile) {
+  let raw;
   try {
-    renameSync(readsFile, readsCollect);
-    const raw = readFileSync(readsCollect, 'utf8');
-    const paths = [...new Set(raw.split('\n').filter(Boolean))];
-    episode.filesRead = paths;
-    try { unlinkSync(readsCollect); } catch {}
+    raw = readFileSync(readsFile, 'utf8');
+  } catch (e) {
+    return e?.code === 'ENOENT' ? 0 : -1;
+  }
+  try {
+    const lines = raw.split('\n').filter(Boolean);
+    const paths = [...new Set(lines)];
+    if (lines.length <= READS_CARRY_MAX_LINES) return paths.length;
+    const keep = paths.slice(-READS_CARRY_MAX_LINES);
+    const tmp = readsFile + `.trim-${process.pid}`;
+    writeFileSync(tmp, keep.join('\n') + '\n', { mode: 0o600 });
+    renameSync(tmp, readsFile);
+    return keep.length;
   } catch {
-    episode.filesRead = episode.filesRead || [];
+    return -1;
   }
+}
 
+function flushEpisodeWithDb(db, episode, hookEventName) {
   // Split by CC session so concurrent same-project sessions flush as separate
   // observations. planEpisodeFlush returns [episode] BY REFERENCE for the common
   // single-session (or all-legacy) case → flushEpisodeGroup(episode) is identical
   // to pre-grouping. Two+ interleaved sessions each get their own sub-episode.
   const subs = planEpisodeFlush(episode);
+
+  // D#178. The reads file used to be consumed right here, unconditionally, BEFORE
+  // anything knew whether this flush would persist an observation — and an
+  // insignificant flush then dropped every path it had just swept up, leaving the
+  // next observation that DID save with files_read = []. Measured over 1122 real
+  // transcripts (benchmark/episode-flush-replay.mjs): 42.2% of the reads a flush
+  // consumed died that way, and 72.7% of significant flushes carried none at all.
+  //
+  // The fix is an ORDERING, not a buffer: explainSignificance reads only `entries`
+  // and `files`, never `filesRead`, so the verdict is available before the file is
+  // touched. An insignificant flush now leaves the file alone and the next
+  // significant one collects the union. Ages measured on the same corpus: the reads
+  // that survive attach a median 1.7 minutes and p90 10.1 minutes later than they do
+  // today, which is the whole cost — a read carried across two insignificant flushes
+  // lands on the edit it preceded rather than on nothing.
+  //
+  // ON by default since v3.83.0. `CLAUDE_MEM_READS_CARRY=0` restores the pre-D#178
+  // behavior byte for byte — kept as an off switch because this changes what a released
+  // artifact stores, and a defect here is invisible from the outside (the symptom is an
+  // absent field, which reads exactly like "there was nothing to record").
+  const carryReads = !['0', 'off', 'false', 'no'].includes(
+    String(process.env.CLAUDE_MEM_READS_CARRY ?? '').toLowerCase());
+  const willPersist = !carryReads || subs.some((s) => episodeHasSignificantContent(s));
+
+  // Collect Read file paths tracked by post-tool-use.sh
+  // Use rename to atomically collect — prevents losing concurrent appends
+  const readsFile = join(RUNTIME_DIR, `reads-${episode.project || inferProject()}.txt`);
+  const readsCollect = readsFile + `.collect-${Date.now()}`;
+  let readsHeld = 0;
+  if (willPersist) {
+    try {
+      renameSync(readsFile, readsCollect);
+      const raw = readFileSync(readsCollect, 'utf8');
+      const paths = [...new Set(raw.split('\n').filter(Boolean))];
+      episode.filesRead = paths;
+      try { unlinkSync(readsCollect); } catch {}
+    } catch {
+      episode.filesRead = episode.filesRead || [];
+    }
+  } else {
+    episode.filesRead = [];
+    // Not collecting means the file keeps growing across an insignificant streak, and a
+    // project that never flushes significantly would grow it without bound. Trim it.
+    //
+    // The trim's race window is WIDER than the collect path's, and saying otherwise (the
+    // first draft did) is the kind of comfortable claim that stops anyone checking: the
+    // collect path is a single atomic `renameSync`, while this is read → dedup → write tmp
+    // → rename, and a `>>` append from the bash prefilter landing inside that span is lost
+    // to the final rename. Accepted rather than fixed: the trim only runs above
+    // READS_CARRY_MAX_LINES, which no observed session approaches, so the exposure is a
+    // path or two in a session that has already read 20000 times.
+    readsHeld = trimReadsFile(readsFile);
+  }
+  // planEpisodeFlush now runs BEFORE the collection, so the multi-session branch — the
+  // one that builds fresh objects rather than returning [episode] by reference — copied
+  // whatever filesRead the buffer happened to carry, not what was just collected. The
+  // single-group path is identity and unaffected; this line is what keeps the two paths
+  // saying the same thing, and without it concurrent same-project sessions would lose
+  // their reads while a solo session kept them.
+  for (const sub of subs) if (sub !== episode) sub.filesRead = episode.filesRead;
+
   let anySignificant = false;
+  let writefail = false;
   for (const sub of subs) {
     const r = flushEpisodeGroup(sub, db);
     if (r === 'writefail') {
@@ -245,12 +351,39 @@ function flushEpisodeWithDb(db, episode, hookEventName) {
       // keep the rest. The asymmetry is safe: each group's immediate obs is persisted
       // BEFORE its flush-file write, so re-flushing the whole buffer would re-emit
       // already-saved groups as duplicate observations.
-      if (subs.length === 1) return;
+      if (subs.length === 1) { writefail = true; break; }
       continue;
     }
     if (r === 'significant') anySignificant = true;
   }
 
+  // D#178 instrument, and the ruler for the flag above. With CLAUDE_MEM_READS_CARRY
+  // off, a row with `significant: false` and `readsConsumed > 0` is that many Read
+  // paths collected and dropped on the floor. With it on, those rows become
+  // `readsConsumed: 0, readsHeld: N` — the same event, now recording a deferral
+  // instead of a loss, so one query over this sink covers both arms.
+  // Emitted HERE and not in flushEpisodeGroup on purpose: planEpisodeFlush copies
+  // the SAME filesRead array into every sub, so a per-group counter double-counts
+  // the multi-session case, and the destroyed/kept decision is `anySignificant`,
+  // which only exists at this level. `writefail` is its own arm because on the SIGNIFICANT
+  // path it keeps the episode buffer for a retry the reads file can no longer serve — it
+  // was already unlinked, so the retry re-collects nothing. A writefail flush is NOT
+  // necessarily one whose significance said collect: `flushEpisodeGroup` writes its flush
+  // file outside the significance branch, so an insignificant flush can fail there too —
+  // and with the flag on that case is strictly better than before, because the reads file
+  // was never touched and the retry still finds it.
+  // Off unless CLAUDE_MEM_METRICS=1, like every other row in this sink.
+  recordMetric(join(RUNTIME_DIR, '..'), {
+    event: 'episode_reads',
+    readsConsumed: (episode.filesRead || []).length,
+    readsHeld,
+    carry: carryReads,
+    significant: anySignificant,
+    subs: subs.length,
+    writefail,
+  });
+  if (writefail) return;
+
   // Aggregate receipt over the whole episode, gated exactly as before
   // (isSignificant → anySignificant). v2.33.4: Stop rejects hookSpecificOutput.
   if (anySignificant && RECEIPT_EVENTS.has(hookEventName)) {
@@ -807,10 +940,34 @@ async function handleStop() {
       // applyCitationDecay checks separately.
       try {
         if (transcriptPath && !process.env.CLAUDE_MEM_NO_CITATION_TRACK) {
+          // D#152/D#177: the `subagent` face, collected ONCE, up front, and used twice —
+          // by the decay block below (only under CLAUDE_MEM_SUBAGENT_DECAY) and by its own
+          // metering call at the tail. It used to be collected at the tail only, with a
+          // comment saying the position was load-bearing because lib/transcript-scan.mjs
+          // memoizes ONE file and reading the sidechains evicts the parent. That constraint
+          // is real but it is not "last" — it is "not BETWEEN two parent scans". Running it
+          // FIRST parses the sidechains before anything has memoized the parent, so the
+          // parent is then parsed once and stays memoized for every scanner after it:
+          // still one parent parse per Stop, the property the tail comment was protecting.
+          let sub = { injected: new Set(), cited: new Set(), files: 0 };
+          try { sub = collectSubagentSurface(transcriptPath); }
+          catch (e) { debugCatch(e, 'handleStop-subagent-collect'); }
+
           const ids = extractCitationsFromTranscript(transcriptPath);
           if (ids.size > 0) {
-            const n = bumpCitationAccess(db, ids, project);
-            debugLog('DEBUG', 'handleStop', `citations: ${ids.size} ids scanned, ${n} obs bumped`);
+            // Gate the access-count channel on relevance (audit FLOW-2 / D#179). The cited
+            // set is every `#NN` in this session's assistant text and cannot tell a
+            // citation from a mention; in this repository a CHANGELOG or audit-writing
+            // session names dozens of ids in prose, and access_count > 3 promotes a row a
+            // tier via boostAccessed. The population to credit — all seven faces, and why
+            // extractAllInjected alone is the wrong five — lives in the builder.
+            const relevant = buildCitationRelevanceSet({
+              transcriptPath, runtimeDir: RUNTIME_DIR, project,
+              sessionId: ccSessionId, subagentInjected: sub.injected,
+            });
+            const n = bumpCitationAccess(db, ids, project, relevant);
+            debugLog('DEBUG', 'handleStop',
+              `citations: ${ids.size} ids scanned, ${relevant.size} relevant, ${n} obs bumped`);
           }
 
           // v32 citation-decay: tighter feedback loop on top of P4. Re-scan
@@ -854,7 +1011,15 @@ async function handleStop() {
             const keyCtxIds = extractInjectedFromKeyContext({
               runtimeDir: RUNTIME_DIR, project, sessionId: ccSessionId,
             });
-            if (injected.size > 0 || keyCtxIds.size > 0) {
+            // D#177: `sub.injected` counts toward the entry gate when the face is admitted.
+            // Without this a session whose ONLY injection was a dispatched agent's prompt
+            // would return here with injected.size === 0 and the face would be "in the
+            // denominator" in name only — the failure mode where a face is wired at one
+            // level and gated out at another, which is how UPS went unmetered for a whole
+            // minor version.
+            const subDecayOn = !['0', 'off', 'false', 'no'].includes(
+              String(process.env.CLAUDE_MEM_SUBAGENT_DECAY ?? '').toLowerCase());
+            if (injected.size > 0 || keyCtxIds.size > 0 || (subDecayOn && sub.injected.size > 0)) {
               // Text-floor gate: skip decay on tool-only Stops. Without this,
               // a turn that ends on tool_use locks every injected obs as
               // uncited (last_decided_session_id set), so a later turn that
@@ -867,17 +1032,71 @@ async function handleStop() {
               } else {
                 const citedMain = extractCitationsFromTranscript(transcriptPath, { mainOnly: true });
                 for (const id of citeBackIds) citedMain.add(id);
+                // D#177: admit the `subagent` face to the decay loop. It cannot ride the
+                // normal path because its injection lands in a dispatched agent's PROMPT
+                // and its citation lands in that agent's OWN transcript — so its ids enter
+                // the denominator AND its receiver-attributed cites enter the numerator,
+                // asymmetrically, together. Feeding only the first half would mark every
+                // subagent-only injection uncited by construction (that is why the face was
+                // metered-but-excluded since v3.77); feeding only the second half would
+                // credit the main-thread faces for citations the main thread never made.
+                //
+                // `sub.cited` is already the per-FILE intersection with `sub.injected`
+                // (collectSubagentSurface), so this cannot credit an id the subagent surface
+                // did not itself inject. Measured on the live corpus (1122 transcripts, 34
+                // subagent-bearing sessions): 33 marginal (session,id) pairs enter the
+                // denominator, 21.2% of them cited; 21 distinct observations behind the
+                // uncited ones, FIVE at uncited_streak = 2. Four are 3->2 down-ranks (#8597,
+                // #8847 with cited_count 56, #8948, #10246). At 2026-08-25 18:00Z #10716 was
+                // at importance 2 — one miss from a 2->1 eviction out of
+                // rankImperativeCandidates' own `importance >= 2` pool, the case
+                // IMPERATIVE_POOL_BACKSTOP does not cover, and the reason "down-ranks, not
+                // evictions" is wrong as a blanket claim. That row has since been promoted by
+                // the very session that documented it (D#179: this loop cannot tell writing
+                // `#NN` from applying it), so re-check the CLASS, not the row.
+                // Cross-crediting is 3 pairs of 1181 DISTINCT (session,id) across the five
+                // decay faces inside subagent-bearing sessions (0.25%), or 3 of 2738 the same
+                // way corpus-wide (0.11%) — ids the main thread never cited but a subagent did.
+                //
+                // ON by default since v3.83.0; `CLAUDE_MEM_SUBAGENT_DECAY=0` restores the
+                // metered-but-never-decaying state the face sat in from v3.77 to v3.82.
+                //
+                // The denominator is a COPY, not a mutation of `injected`: the edge
+                // attribution below takes `mainInjectedIds: injected` to keep sidechain-only
+                // injections from accruing file-edge misses (review D#78), and folding the
+                // subagent ids into that set would undo exactly that guard.
                 // The promotion-only half: a Key Context row the agent actually
                 // cited joins the decay set (and takes the promote branch); one
                 // it ignored is never entered, so it cannot streak or demote.
                 for (const id of keyCtxIds) if (citedMain.has(id)) injected.add(id);
+                // BOTH halves of the merge are COPIES, built AFTER the keyctx promotion above
+                // so they carry it too. When the flag is off each IS the original object, so
+                // every consumer below is byte identical to the pre-D#177 path.
+                //
+                // The copies are the whole safety property. `injected` and `citedMain` have
+                // four consumers between them and only `applyCitationDecay` should see the
+                // subagent ids; the first draft of this change mutated `citedMain` in place
+                // and the pre-tag review measured both leaks it caused:
+                //   • recordCitationSurfaces (below) scored a `pretool` row the main thread
+                //     never cited as a pretool HIT — `pretool.cited_n` 0 -> 1 on a
+                //     two-observation probe. That is the caliber CLAUDE.md publishes for the
+                //     funnel ("cited as #NN in the session's own MAIN-THREAD text"), so it
+                //     would have made citation_surface_log and citation-live-replay.mjs
+                //     permanently different rulers — the v3.81.0 cross-agent defect, mirrored.
+                //   • resolveEdgeAttribution gates sidechain edges on
+                //     `!mainInjected.has(id) && !cited.has(id)`, so a file edge flipped MISS
+                //     -> HIT (`miss_streak` 1 -> 0). The comment there defends the DENOMINATOR
+                //     half of that gate and says nothing about the numerator, which is exactly
+                //     how the leak got past a reading of it.
+                const decayInjected = subDecayOn ? new Set([...injected, ...sub.injected]) : injected;
+                const decayCited = subDecayOn ? new Set([...citedMain, ...sub.cited]) : citedMain;
                 // D#60: the idempotency key must be the CC session UUID, NOT the
                 // project-scoped memory sessionId — concurrent same-project CC
                 // sessions share the latter, so the second session's decay pass
                 // read "already decided" and silently undercounted decay_seen /
                 // streaks / adoption denominators. Fallback keeps legacy
                 // stdin-less invocations on the old key.
-                const r = applyCitationDecay(db, project, injected, citedMain, ccSessionId || sessionId);
+                const r = applyCitationDecay(db, project, decayInjected, decayCited, ccSessionId || sessionId);
                 debugLog('DEBUG', 'handleStop', `citation-decay: touched=${r.touched} promoted=${r.promoted} demoted=${r.demoted}`);
                 // R1: persist this session's invocation→cite funnel row. touched =
                 // obs resolved this run (denominator), promoted = obs cited this run
@@ -968,11 +1187,19 @@ async function handleStop() {
           // construction; folding its cites INTO citedMain would credit the
           // main-thread faces for citations the main thread never made. The
           // upsert key is (project, session, surface), so two calls with
-          // disjoint face sets do not collide. Metering only — `subagent` is in
-          // NON_ATTACHMENT_SURFACES and never reaches applyCitationDecay.
+          // disjoint face sets do not collide.
+          //
+          // SINCE v3.83.0 (D#177) this is no longer metering-only: the face DOES reach
+          // applyCitationDecay, through the `decayInjected` / `decayCited` copies above.
+          // The sentence above about folding cites into `citedMain` still holds and is the
+          // reason those are copies — this call, `resolveEdgeAttribution` and the keyctx
+          // promotion all keep the un-widened set. `CLAUDE_MEM_SUBAGENT_DECAY=0` returns
+          // the face to metering-only.
           //
-          // Placed LAST on purpose: lib/transcript-scan.mjs memoizes ONE file,
-          // so reading the sidechain files evicts the parent transcript. Run
+          // The "placed LAST" note below is now historical: `collectSubagentSurface` runs
+          // at the HEAD of this block (the decay loop needs its result), and `sub` here is
+          // that same object rather than a second call. The parse-count property the note
+          // defends is unchanged — see the comment at the collection site.
           // earlier, this block costs ONE extra parse of the parent — the memo
           // re-caches on the first re-read, so it is one, not one per later
           // scanner — and breaks the "one parse per Stop" property the block
@@ -985,7 +1212,9 @@ async function handleStop() {
           // must not enter the funnel's session denominator either.
           try {
             if (hasMainThreadAssistantText(transcriptPath)) {
-              const sub = collectSubagentSurface(transcriptPath);
+              // `sub` is the one collected at the top of this block — a second
+              // collectSubagentSurface call here would re-parse every sidechain file and,
+              // worse, could disagree with the set the decay loop above just scored.
               if (sub.injected.size > 0) {
                 recordCitationSurfaces(db, project, ccSessionId || sessionId,
                   { subagent: sub.injected }, sub.cited);
@@ -1341,14 +1570,52 @@ function scheduleSessionStartAutoMaintain(project) {
   if (!process.env.CLAUDE_MEM_SKIP_MAINTAIN) spawnBackground('auto-maintain', project);
 }
 
+// The maintenance mutex deliberately does NOT end in `.lock`: cleanStaleLockFiles()
+// below unlinks every `*.lock` in RUNTIME_DIR whose age exceeds STALE_LOCK_MS (30s)
+// WITHOUT consulting the holder's pid — a policy written for the episode lock, whose
+// critical section is milliseconds. A maintenance pass is seconds to minutes (VACUUM INTO
+// snapshot, purge, decay, dedup over the whole DB), so that sweeper would strip this lock
+// mid-pass and hand the exclusion straight back to the race it exists to close.
+// proc-lock brings its own staleness policy (age OR provably-dead pid), which is the
+// correct one here.
+// Generous upper bound on one pass; a crashed holder is normally reclaimed sooner via the
+// dead-pid check, so this only matters for a holder killed on another host.
+const AUTO_MAINTAIN_LOCK_STALE_MS = 10 * 60 * 1000;
+
 // Detached `auto-maintain` worker entry: opens its own DB and runs the maintenance
 // pass off the interactive boot path. runSessionStartAutoMaintain still owns the 24h
 // gate + the compress/optimize spawns at its tail.
+//
+// Cross-process mutual exclusion (2026-08-29 audit FLOW-1). The pass is shaped
+// read-gate → long work → write-gate, so two Claude Code windows booting either side of
+// the 24h boundary both see "due" and both spawn a worker. That breaks a documented
+// in-process invariant: decayAndMarkIdle marks BEFORE it decays precisely so an imp-2 row
+// cannot be decayed 2→1 and marked COMPRESSED_PENDING_PURGE in the same pass (MED-1, see
+// its docblock — each importance tier is supposed to buy a grace cycle). Across two
+// processes the ordering is gone: worker A decays 2→1, worker B's mark-idle then sees a
+// qualifying imp-1 row and hides it, 37 days from a hard delete. The same overlap
+// double-runs the cascade below it (duplicate weekly summaries from compressGroup, whose
+// UPDATE has no compressed_into guard; doubled llm-optimize spend).
+//
+// Lock at the worker entry rather than around the individual ops: the cascade spawns sit
+// inside the pass, so one gate covers the whole family. Not acquiring is a plain no-op —
+// a peer is already doing exactly this work.
 function handleAutoMaintain(project) {
-  const db = openDb();
-  if (!db) return;
-  try { runSessionStartAutoMaintain(db, project); }
-  finally { try { db.close(); } catch { /* ignore */ } }
+  const release = acquireProcLock(join(RUNTIME_DIR, AUTO_MAINTAIN_LOCK), {
+    staleMs: AUTO_MAINTAIN_LOCK_STALE_MS,
+  });
+  if (!release) {
+    debugLog('DEBUG', 'auto-maintain', 'skipped — a live peer holds the maintenance lock');
+    return;
+  }
+  try {
+    const db = openDb();
+    if (!db) return;
+    try { runSessionStartAutoMaintain(db, project); }
+    finally { try { db.close(); } catch { /* ignore */ } }
+  } finally {
+    release();
+  }
 }
 
 function saveHandoffAndFastSummary(db, { prevSessionId, prevProject, project, ccSessionId, episodeSnapshot, now }) {
@@ -1477,7 +1744,11 @@ async function buildStartupDashboardText(db, project) {
   // tests/session-start-stdout-envelope.test.mjs.
   try {
     const { buildDashboard } = await import('./lib/startup-dashboard.mjs');
-    let dashboardText = buildDashboard({ db, project, projectPath: process.cwd() });
+    // projectPath MUST come from the same place `project` does (inferProjectDir), not from
+    // process.cwd(): otherwise the dashboard renders directory A's git state and task list
+    // under directory B's project name whenever the hook process was not spawned at the
+    // project root. See inferProjectDir()'s docblock for the case this closed.
+    let dashboardText = buildDashboard({ db, project, projectPath: inferProjectDir() });
     const citeNudge = buildCiteRecallNudge(project);
     if (citeNudge) {
       dashboardText = dashboardText ? `${citeNudge}\n${dashboardText}` : citeNudge;
@@ -1949,7 +2220,14 @@ async function handleUserPrompt() {
       // ranking and citation extractors (bare-`#` anchored) never read an event id as
       // an obs id. Nested try so an events failure can't suppress the imperative pick.
       try {
-        const events = searchInjectableEvents(db, { prompt: promptText, project });
+        // upsFtsQuery, not the raw prompt (audit ALGO-1). lib/ups-query.mjs declares
+        // itself "the ONE query-cap definition for the UserPromptSubmit event", and both
+        // OTHER legs of this same event go through it — but this leg, wired in v3.48
+        // before that module existed, handed searchInjectableEvents the whole prompt and
+        // let it call the uncapped sanitizeFtsQuery. Measured here: a 250KB CJK prompt
+        // (path B's stdin cap is 256KB) costs 356ms uncapped against 5.5ms capped, all of
+        // it synchronous, before the model sees the turn.
+        const events = searchInjectableEvents(db, { ftsQuery: upsFtsQuery(promptText), project });
         if (events.length > 0) {
           const elines = ['<memory-context relevance="events">'];
           for (const e of events) elines.push(`- ${renderInjectableEvent(e)}`);