iterate-plugin 3.5.6 → 3.6.0

package/src/tools/defense-events.ts

@@ -12,7 +12,9 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec, loadEffectiveConfig } from '../config-loader.ts'
+import { withProjectLock } from '../file-lock.ts'
 import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from './defense-store.ts'
+import { renderedText } from './present.ts'
 import type { DefenseEvent, DefenseEventType } from '../types.ts'
 
 const DEFAULT_LIMIT = 50
@@ -25,8 +27,13 @@ const EVENT_TYPES: DefenseEventType[] = [
   'assumption_falsified',
 ]
 
-/** Clamp a caller-supplied limit to a sane range. */
-function clampLimit(limit: number | undefined): number {
+/**
+ * Clamp a caller-supplied limit to a sane range.
+ * Anything that is not a positive integer falls back to the default — the
+ * parameter schema already rejects non-integers, but hand-constructed args
+ * (and future internal callers) still land here. Pure — exported for unit tests.
+ */
+export function clampLimit(limit: number | undefined): number {
   if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
     return DEFAULT_LIMIT
   }
@@ -73,8 +80,14 @@ function validateRecordInput(args: {
   if (typeof args.outcome !== 'string' || !args.outcome.trim()) {
     errors.push('outcome is required')
   }
-  if (args.line !== undefined && (typeof args.line !== 'number' || !Number.isInteger(args.line) || args.line < 0)) {
-    errors.push('line must be a non-negative integer when present')
+  // Positions are 1-BASED. `line: 0` is not usable here even though the
+  // evidence/review layer treats 0 as "whole file": the renderer prints the
+  // position only for a truthy line (`file + ':' + line`), so a stored 0 would
+  // come back as a bare file path with no indication of what it meant — and
+  // the client-side normalizer already degrades 0 to null ("not a usable
+  // position"). Reject it at the door instead of persisting a silent 0.
+  if (args.line !== undefined && (typeof args.line !== 'number' || !Number.isInteger(args.line) || args.line < 1)) {
+    errors.push('line must be a positive integer (>= 1) when present')
   }
   const severity = args.severity
   if (severity !== 'critical' && severity !== 'high' && severity !== 'medium' && severity !== 'low') {
@@ -91,6 +104,31 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
   ctx.tools.register(
     defineTool({
       name: 'iterate_defense_events',
+      // Result card (#12): the `counts` render is a column of per-type lines —
+      // fold it into one headline ("Defense events: 3 recorded (rollback: 2)").
+      // Only `counts` gets a card; other operations keep the default view.
+      // Pure: parsed from the rendered text; an unreadable shape declines.
+      presentResult: (args, result) => {
+        const a = args as { operation?: unknown }
+        if (a.operation !== 'counts') return undefined
+        const text = renderedText(result)
+        if (!text) return undefined
+        const lines = text.split('\n')
+        const totalLine = lines.find((l) => l.trim().startsWith('Total:'))
+        const totalMatch = totalLine ? /Total:\s*(\d+)/.exec(totalLine) : null
+        const total = totalMatch ? Number(totalMatch[1]) : NaN
+        if (!Number.isFinite(total)) return undefined
+        // Per-type rows ("  rollback: 2"), localized labels included; the zero
+        // rows are dropped so the headline only names types that actually fired.
+        const detail = lines
+          .filter((l) => /^\s{2,}\S.*:\s*\d+\s*$/.test(l))
+          .map((l) => l.trim())
+          .filter((l) => !l.startsWith('Total:') && !/:\s*0\s*$/.test(l))
+        return {
+          card: 'generic',
+          title: `Defense events: ${total} recorded` + (detail.length > 0 ? ` (${detail.join(', ')})` : ''),
+        }
+      },
       // List/counts never write; `record` persists an event and `clear` removes
       // the persisted stream, so only the read shapes may join a parallel
       // dispatch group.
@@ -142,7 +180,7 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
         },
         line: {
           type: 'integer',
-          description: 'Optional line number context (record).',
+          description: 'Optional line number context (record): a 1-based line number (>= 1).',
         },
         language: {
           type: 'string',
@@ -167,7 +205,8 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
             ok: { type: 'boolean', required: true },
             kind: { type: 'string' },
             operation: { type: 'string' },
-            count: { type: 'integer' },
+            count: { type: 'integer', description: 'list: number of events actually returned (after limit truncation).' },
+            total: { type: 'integer', description: 'list: total number of matching events before the limit was applied.' },
             counted: { type: 'boolean', description: 'clear only: true when a persisted stream was removed.' },
             events: { type: 'json' },
             counts: { type: 'json' },
@@ -222,7 +261,10 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
           }
 
           const lines = [
-            `Defense Events (${value.count} total):`,
+            // `total` is the UNTRUNCATED match count; `count` is what survived
+            // the limit. Printing only one number (the old `count` as "total")
+            // hid the real stream size from the reader.
+            `Defense Events (showing ${value.count} of ${value.total}):`,
             '',
             ...events.map((e) => {
               const typeLabel = labelFor(e.type, language)
@@ -251,7 +293,10 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
         if (operation === 'clear') {
           // Reset the persisted event stream so a fresh iteration does not carry
           // stale defensive data (mirrors iterate_quality_gate clear / clearQualityGate).
-          const result = clearDefenseEvents(projectRoot)
+          // Same lock as `record`: clear is a read-modify-write against the same
+          // file, so an unlocked clear racing a locked record could resurrect
+          // the just-cleared events (the record's write lands after the rm).
+          const result = withProjectLock(projectRoot, 'defense-events', () => clearDefenseEvents(projectRoot))
           if (!result.ok) {
             return { ok: false, kind: 'defense_events', operation: 'clear', error: result.error }
           }
@@ -278,30 +323,38 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
               error: `Invalid defense event: ${errors.join('; ')}`,
             }
           }
-          const stream = readDefenseEvents(projectRoot)
-          const next = addDefenseEvent(stream, {
-            round: args.round as number,
-            type: args.type as DefenseEventType,
-            description: args.description as string,
-            defense: args.defense as string,
-            outcome: args.outcome as string,
-            severity: args.severity as DefenseEvent['severity'],
-            ...(typeof args.file === 'string' && args.file.length > 0 ? { file: args.file } : {}),
-            ...(typeof args.line === 'number' ? { line: args.line } : {}),
+          // The read→modify→write below is the exact cross-process race the
+          // decision log documents: two plugin processes reading the same
+          // stream concurrently each append their own event and the second
+          // write silently drops the first. Serialize the whole cycle with the
+          // shared advisory lock (fail-open on timeout is built into the
+          // helper — worst case is the pre-existing unlocked behavior).
+          return withProjectLock(projectRoot, 'defense-events', () => {
+            const stream = readDefenseEvents(projectRoot)
+            const next = addDefenseEvent(stream, {
+              round: args.round as number,
+              type: args.type as DefenseEventType,
+              description: args.description as string,
+              defense: args.defense as string,
+              outcome: args.outcome as string,
+              severity: args.severity as DefenseEvent['severity'],
+              ...(typeof args.file === 'string' && args.file.length > 0 ? { file: args.file } : {}),
+              ...(typeof args.line === 'number' ? { line: args.line } : {}),
+            })
+            const write = writeDefenseEvents(projectRoot, next)
+            if (!write.ok) {
+              return { ok: false, kind: 'defense_events', operation: 'record', error: write.error }
+            }
+            const event = next.events[next.events.length - 1]
+            return {
+              ok: true,
+              kind: 'defense_events',
+              operation: 'record',
+              language,
+              event: event as unknown as JsonValue,
+              counts: next.counts as unknown as JsonValue,
+            }
           })
-          const write = writeDefenseEvents(projectRoot, next)
-          if (!write.ok) {
-            return { ok: false, kind: 'defense_events', operation: 'record', error: write.error }
-          }
-          const event = next.events[next.events.length - 1]
-          return {
-            ok: true,
-            kind: 'defense_events',
-            operation: 'record',
-            language,
-            event: event as unknown as JsonValue,
-            counts: next.counts as unknown as JsonValue,
-          }
         }
 
         const stream = readDefenseEvents(projectRoot)
@@ -337,7 +390,10 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
           kind: 'defense_events',
           operation: 'list',
           language,
+          // `count` = events actually returned (limit-truncated);
+          // `total` = every event matching the filters, before truncation.
           count: Math.min(events.length, limit),
+          total: events.length,
           events: events.slice(0, limit) as unknown as JsonValue,
         }
       },

package/src/tools/defense-store.ts

@@ -50,6 +50,16 @@ function emptyStream(): DefenseEventStream {
 /** Valid severity values (kept in sync with DefenseEvent). */
 const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medium', 'low'])
 
+/**
+ * Sentinel timestamp for events persisted WITHOUT one. Reads must be
+ * deterministic: stamping `new Date()` here meant two reads of the same
+ * hand-edited file produced different JSON, and the next write persisted that
+ * read-time churn as real history. The epoch sentinel is stable across reads
+ * AND sorts as the oldest event (list output is newest-first), so a timestamp-less
+ * event degrades to "the beginning of time" instead of "just now".
+ */
+const MISSING_TIMESTAMP_SENTINEL = '1970-01-01T00:00:00.000Z'
+
 /**
  * Normalize one persisted event. Hand-edited files can carry events missing
  * `timestamp`/`round`/`description`/`defense`/`outcome`/`severity` — readers
@@ -67,14 +77,18 @@ function normalizeEvent(raw: unknown, index: number): DefenseEvent | null {
   const derivedId = `def-${hashString(`${index}|${String(e.timestamp ?? '')}|${e.type}|${String(e.description ?? '')}|${String(e.defense ?? '')}`)}`
   return {
     id: typeof e.id === 'string' && e.id ? e.id : derivedId,
-    timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : new Date().toISOString(),
+    timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : MISSING_TIMESTAMP_SENTINEL,
     round: typeof e.round === 'number' && Number.isFinite(e.round) ? Math.floor(e.round) : 0,
     type: e.type as DefenseEventType,
     description: typeof e.description === 'string' ? e.description : '',
     defense: typeof e.defense === 'string' ? e.defense : '',
     outcome: typeof e.outcome === 'string' ? e.outcome : '',
     ...(typeof e.file === 'string' && e.file.length > 0 ? { file: e.file } : {}),
-    ...(typeof e.line === 'number' && Number.isFinite(e.line) && e.line >= 0 ? { line: e.line } : {}),
+    // Only 1-based lines are a usable position (see the record-side check in
+    // src/tools/defense-events.ts): a hand-edited `line: 0`/negative/non-integer
+    // is dropped rather than echoed back to a renderer that would print the
+    // file WITHOUT a position anyway (`line ? ':' + line : ''`).
+    ...(typeof e.line === 'number' && Number.isInteger(e.line) && e.line >= 1 ? { line: e.line } : {}),
     severity: VALID_SEVERITIES.has(String(e.severity)) ? (e.severity as DefenseEvent['severity']) : 'low',
   }
 }
@@ -99,6 +113,11 @@ export function readDefenseEvents(projectRoot: string): DefenseEventStream {
       const counts = computeCounts(events)
       return {
         events,
+        // Stream-level fallback timestamp: display-only metadata — retention
+        // and sweeps rank per-EVENT `event.timestamp`, never `lastUpdated`, so
+        // a missing/corrupt value degrading to "now" cannot reorder or
+        // resurrect events. (Reaffirmed from the earlier review: comment only,
+        // behavior unchanged.)
         lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyStream().lastUpdated,
         counts,
       }
@@ -160,11 +179,19 @@ export function addDefenseEvent(
   stream: DefenseEventStream,
   event: Omit<DefenseEvent, 'id' | 'timestamp'>
 ): DefenseEventStream {
+  // Storage-side line check, mirroring the tool's record validation: a
+  // non-integer / < 1 line is not a usable position (the renderer prints the
+  // file WITHOUT a position for a falsy line), so it is dropped instead of
+  // being persisted as a silent 0.
+  const { line, ...rest } = event
+  const usableLine = typeof line === 'number' && Number.isInteger(line) && line >= 1 ? line : undefined
+
   // Spread the caller-shaped event FIRST so the store-generated `id` and
   // `timestamp` always win — a caller-supplied id/timestamp must never
   // override the stream's own identity fields.
   const newEvent: DefenseEvent = {
-    ...event,
+    ...rest,
+    ...(usableLine !== undefined ? { line: usableLine } : {}),
     id: `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     timestamp: new Date().toISOString(),
   }

package/src/tools/experience-bank.ts

@@ -9,15 +9,22 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
-import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience } from './experience-store.ts'
+import { withProjectLock } from '../file-lock.ts'
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience, isValidExperienceId, MAX_EXPERIENCE_ID_LENGTH } from './experience-store.ts'
+import { resultHeadline } from './present.ts'
 import type { ExperienceEntryInput } from './experience-store.ts'
 import type { ExperienceEntry } from '../types.ts'
 
 const DEFAULT_LIMIT = 50
 const MAX_LIMIT = 100
 
-/** Clamp a caller-supplied limit to a sane range. */
-function clampLimit(limit: number | undefined): number {
+/**
+ * Clamp a caller-supplied limit to a sane range.
+ * Anything that is not a positive integer falls back to the default — the
+ * parameter schema already rejects non-integers, but hand-constructed args
+ * (and future internal callers) still land here. Pure — exported for unit tests.
+ */
+export function clampLimit(limit: number | undefined): number {
   if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
     return DEFAULT_LIMIT
   }
@@ -72,6 +79,13 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
   ctx.tools.register(
     defineTool({
       name: 'iterate_experience',
+      // Result card (#12): each operation renders a self-describing first line
+      // ("Found 3 experience(s)…", "Recorded new experience: exp-…") — reuse it
+      // as the card title. Pure: rendered result only; failures decline.
+      presentResult: (_args, result) => {
+        const title = resultHeadline(result)
+        return title ? { card: 'generic', title } : undefined
+      },
       // List/search/get never write; `add` upserts the bank and `remove`
       // rewrites it → only the read shapes may join a parallel dispatch group.
       isConcurrencySafe: (args) => {
@@ -107,7 +121,9 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
         },
         id: {
           type: 'string',
-          description: 'Experience ID (for get operation, or to update a specific entry via add).',
+          description:
+            'Experience ID (required for get and remove). For `add`, name the entry via `entry.id` ' +
+            '— a top-level `id` is not read on add.',
         },
         entry: {
           type: 'json',
@@ -203,22 +219,47 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               error: `Invalid experience entry: ${errors.join('; ')}`,
             }
           }
-          const bank = readExperienceBank(projectRoot)
-          const { bank: next, added, entryId } = upsertExperience(bank, normalizeExperienceInput(raw as Record<string, unknown>))
-          const write = writeExperienceBank(projectRoot, next)
-          if (!write.ok) {
-            return { ok: false, kind: 'experience', operation: 'add', error: write.error }
-          }
-          const entry = next.entries.find((e) => e.id === entryId)
-          return {
-            ok: true,
-            kind: 'experience',
-            operation: 'add',
-            added,
-            count: next.entries.length,
-            entry: entry as unknown as JsonValue,
-            totalHits: next.totalHits,
-          }
+          // Serialize the read→modify→write cycle: two processes adding to the
+          // same bank concurrently would otherwise lose one of the entries
+          // (exactly the race the shared advisory lock exists for; fail-open
+          // on lock timeout is built into the helper).
+          return withProjectLock(projectRoot, 'experience-bank', () => {
+            const bank = readExperienceBank(projectRoot)
+            const input = normalizeExperienceInput(raw as Record<string, unknown>)
+            // A caller-supplied id may only NAME a new entry — reject ids that
+            // would not survive contact with disk/output (oversized or
+            // control-byte). An id that matches an EXISTING entry is an update
+            // and keeps working unchanged.
+            if (
+              input.id !== undefined &&
+              !bank.entries.some((e) => e.id === input.id) &&
+              !isValidExperienceId(input.id)
+            ) {
+              return {
+                ok: false,
+                kind: 'experience',
+                operation: 'add',
+                error:
+                  `entry.id must be a printable string of at most ${MAX_EXPERIENCE_ID_LENGTH} characters ` +
+                  '(non-empty, no control characters) when it does not match an existing entry',
+              }
+            }
+            const { bank: next, added, entryId } = upsertExperience(bank, input)
+            const write = writeExperienceBank(projectRoot, next)
+            if (!write.ok) {
+              return { ok: false, kind: 'experience', operation: 'add', error: write.error }
+            }
+            const entry = next.entries.find((e) => e.id === entryId)
+            return {
+              ok: true,
+              kind: 'experience',
+              operation: 'add',
+              added,
+              count: next.entries.length,
+              entry: entry as unknown as JsonValue,
+              totalHits: next.totalHits,
+            }
+          })
         }
 
         if (operation === 'remove') {
@@ -231,35 +272,51 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
               error: 'id is required for remove',
             }
           }
-          const bank = readExperienceBank(projectRoot)
-          const { bank: next, removed } = removeExperience(bank, id)
-          if (!removed) {
+          // Same read→modify→write hazard as `add` — hold the shared lock for
+          // the whole cycle so a concurrent remove cannot resurrect a deleted
+          // entry.
+          return withProjectLock(projectRoot, 'experience-bank', () => {
+            const bank = readExperienceBank(projectRoot)
+            const { bank: next, removed } = removeExperience(bank, id)
+            if (!removed) {
+              return {
+                ok: false,
+                kind: 'experience',
+                operation: 'remove',
+                error: `Experience not found: ${id}`,
+              }
+            }
+            const write = writeExperienceBank(projectRoot, next)
+            if (!write.ok) {
+              return { ok: false, kind: 'experience', operation: 'remove', error: write.error }
+            }
             return {
-              ok: false,
+              ok: true,
               kind: 'experience',
               operation: 'remove',
-              error: `Experience not found: ${id}`,
+              count: next.entries.length,
+              totalHits: next.totalHits,
             }
-          }
-          const write = writeExperienceBank(projectRoot, next)
-          if (!write.ok) {
-            return { ok: false, kind: 'experience', operation: 'remove', error: write.error }
-          }
-          return {
-            ok: true,
-            kind: 'experience',
-            operation: 'remove',
-            count: next.entries.length,
-            totalHits: next.totalHits,
-          }
+          })
         }
 
-        const bank = readExperienceBank(projectRoot)
-
-        if (operation === 'get' && typeof args.id === 'string') {
-          const entry = bank.entries.find((e) => e.id === args.id)
+        // `get`/`search` require their argument: silently falling through to
+        // `list` would answer a get with a DIFFERENT operation's payload
+        // (ok:true + entries) — mirror the `remove` contract and error instead.
+        if (operation === 'get') {
+          const id = typeof args.id === 'string' && args.id ? args.id : ''
+          if (!id) {
+            return {
+              ok: false,
+              kind: 'experience',
+              operation: 'get',
+              error: 'id is required for get',
+            }
+          }
+          const bank = readExperienceBank(projectRoot)
+          const entry = bank.entries.find((e) => e.id === id)
           if (!entry) {
-            return { ok: false, kind: 'experience', error: `Experience not found: ${args.id}` }
+            return { ok: false, kind: 'experience', operation: 'get', error: `Experience not found: ${id}` }
           }
           return {
             ok: true,
@@ -271,8 +328,18 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
           }
         }
 
-        if (operation === 'search' && typeof args.query === 'string') {
-          const entries = searchExperienceEntries(bank.entries, args.query, {
+        if (operation === 'search') {
+          const query = typeof args.query === 'string' && args.query ? args.query : ''
+          if (!query) {
+            return {
+              ok: false,
+              kind: 'experience',
+              operation: 'search',
+              error: 'query is required for search',
+            }
+          }
+          const bank = readExperienceBank(projectRoot)
+          const entries = searchExperienceEntries(bank.entries, query, {
             dimension: typeof args.dimension === 'string' ? args.dimension : undefined,
             tags: Array.isArray(args.tags) ? args.tags : undefined,
           }).slice(0, limit)
@@ -288,6 +355,7 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
         }
 
         // Default: list with optional filters
+        const bank = readExperienceBank(projectRoot)
         let entries = bank.entries
         if (typeof args.dimension === 'string' && args.dimension) {
           entries = entries.filter((e) => e.dimension === args.dimension)

package/src/tools/experience-store.ts

@@ -32,6 +32,41 @@ function stringArray(v: unknown): string[] {
   return v.filter((x): x is string => typeof x === 'string')
 }
 
+/**
+ * Coerce a persisted hit counter to a safe non-negative integer. Hand-edited
+ * banks can carry fractional (4.5), negative (-1), non-finite (Infinity) or
+ * non-numeric ('x') values — the tool output schema declares these fields as
+ * `integer`, so any of them reaching the result would throw ToolOutputError
+ * at runtime. Floors first, then clamps at 0; anything non-finite → 0.
+ */
+function toHitCount(v: unknown): number {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return 0
+  return Math.max(0, Math.floor(v))
+}
+
+/**
+ * Longest caller-supplied experience id we will persist, and the characters
+ * it may contain. Ids surface verbatim in tool output and on disk, so a
+ * hostile "add" must not be able to store a 100 KB blob or control bytes
+ * (NUL/newline) under the id field. Printable characters only (no C0/C1
+ * controls); unicode text is fine.
+ */
+export const MAX_EXPERIENCE_ID_LENGTH = 200
+
+/**
+ * Whether a caller-supplied id may identify a NEW experience entry.
+ * Validated at the tool layer BEFORE the entry reaches `upsertExperience`
+ * (see src/tools/experience-bank.ts): non-empty, ≤ 200 chars, no control
+ * characters. Pure — exported for unit tests.
+ */
+export function isValidExperienceId(id: unknown): id is string {
+  if (typeof id !== 'string') return false
+  if (id.length === 0 || id.length > MAX_EXPERIENCE_ID_LENGTH) return false
+  // Control characters (NUL, newline, …) would corrupt the id wherever it is
+  // echoed (JSON output, file names in renderers) — reject them outright.
+  return !/[\u0000-\u001f\u007f]/.test(id)
+}
+
 /**
  * Normalize one persisted experience entry. A hand-edited bank entry can be
  * missing `files`/`tags` arrays (or `hitCount`) — consumers rendering/searching
@@ -49,7 +84,7 @@ function normalizeEntry(raw: unknown, index: number): ExperienceEntry | null {
   const derivedId = `exp-${hashString(`${index}|${pattern}|${dimension}`)}`
   const id = typeof e.id === 'string' && e.id ? e.id : derivedId
   if (!pattern && !dimension) return null
-  const hitCount = typeof e.hitCount === 'number' && Number.isFinite(e.hitCount) ? e.hitCount : 0
+  const hitCount = toHitCount(e.hitCount)
   return {
     id,
     timestamp: typeof e.timestamp === 'string' ? e.timestamp : new Date().toISOString(),
@@ -78,9 +113,16 @@ export function readExperienceBank(projectRoot: string): ExperienceBank {
         .filter((e): e is ExperienceEntry => e !== null)
       return {
         entries,
+        // Stream-level fallback timestamp: display-only metadata — the entry
+        // sweep ranks per-ENTRY `entry.timestamp`, never `lastUpdated`, so a
+        // missing/corrupt value degrading to "now" cannot reorder or rescue
+        // entries. (Reaffirmed from the earlier review: comment only, behavior
+        // unchanged.)
         lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyBank().lastUpdated,
-        totalHits:
-          typeof parsed.totalHits === 'number' && Number.isFinite(parsed.totalHits) ? parsed.totalHits : 0,
+        // Same contract as per-entry hitCount: a hand-edited totalHits must be
+        // a finite non-negative integer before it reaches the `integer` output
+        // schema (4.5 → 4, -1 → 0, Infinity/NaN/'x' → 0).
+        totalHits: toHitCount(parsed.totalHits),
       }
     }
   } catch {
@@ -214,8 +256,15 @@ export function upsertExperience(
   }
 
   // Add new entry. Spread the caller input FIRST so the store-generated
-  // `id`/`timestamp`/`hitCount`/`lastHitAt` always win — a hostile or
-  // malformed input can never forge its own identity or hit count.
+  // `timestamp`/`hitCount`/`lastHitAt` always win — a hostile or malformed
+  // input can never forge its hit metadata. A caller-supplied `id` IS honored
+  // here (it is the documented "update a specific entry via add"/custom-id
+  // contract), but only after the tool layer validated it with
+  // `isValidExperienceId` (non-empty, ≤ 200 chars, printable) — oversized or
+  // control-byte ids are rejected with a structured error before they reach
+  // this store (see src/tools/experience-bank.ts). Because an EXISTING id
+  // takes the update path above, a new entry can never collide with — or
+  // impersonate — an entry that is already in the bank.
   const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
   const newEntry: ExperienceEntry = {
     ...entry,