iterate-plugin 3.5.7 → 3.6.0

package/dist/tools/defense-events.js

@@ -10,7 +10,9 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec, loadEffectiveConfig } from "../config-loader.js";
+import { withProjectLock } from "../file-lock.js";
 import { readDefenseEvents, writeDefenseEvents, addDefenseEvent, clearDefenseEvents } from "./defense-store.js";
+import { renderedText } from "./present.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
 const EVENT_TYPES = [
@@ -19,8 +21,13 @@ const EVENT_TYPES = [
     'invariant_violated',
     'assumption_falsified',
 ];
-/** Clamp a caller-supplied limit to a sane range. */
-function clampLimit(limit) {
+/**
+ * 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) {
     if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
         return DEFAULT_LIMIT;
     }
@@ -56,8 +63,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') {
@@ -72,6 +85,34 @@ function validateRecordInput(args) {
 export function registerDefenseEventsTool(ctx) {
     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;
+            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.
@@ -122,7 +163,7 @@ export function registerDefenseEventsTool(ctx) {
             },
             line: {
                 type: 'integer',
-                description: 'Optional line number context (record).',
+                description: 'Optional line number context (record): a 1-based line number (>= 1).',
             },
             language: {
                 type: 'string',
@@ -146,7 +187,8 @@ export function registerDefenseEventsTool(ctx) {
                     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' },
@@ -195,7 +237,10 @@ export function registerDefenseEventsTool(ctx) {
                     return [{ type: 'text', text: 'No defense events recorded.' }];
                 }
                 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);
@@ -221,7 +266,10 @@ export function registerDefenseEventsTool(ctx) {
             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 };
                 }
@@ -247,30 +295,38 @@ export function registerDefenseEventsTool(ctx) {
                         error: `Invalid defense event: ${errors.join('; ')}`,
                     };
                 }
-                const stream = readDefenseEvents(projectRoot);
-                const next = addDefenseEvent(stream, {
-                    round: args.round,
-                    type: args.type,
-                    description: args.description,
-                    defense: args.defense,
-                    outcome: args.outcome,
-                    severity: args.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,
+                        type: args.type,
+                        description: args.description,
+                        defense: args.defense,
+                        outcome: args.outcome,
+                        severity: args.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,
+                        counts: next.counts,
+                    };
                 });
-                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,
-                    counts: next.counts,
-                };
             }
             const stream = readDefenseEvents(projectRoot);
             if (operation === 'counts') {
@@ -300,7 +356,10 @@ export function registerDefenseEventsTool(ctx) {
                 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),
             };
         },

package/dist/tools/defense-store.js

@@ -42,6 +42,15 @@ function emptyStream() {
 }
 /** Valid severity values (kept in sync with DefenseEvent). */
 const VALID_SEVERITIES = 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
@@ -61,14 +70,18 @@ function normalizeEvent(raw, index) {
     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,
         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 : 'low',
     };
 }
@@ -92,6 +105,11 @@ export function readDefenseEvents(projectRoot) {
             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,
             };
@@ -145,11 +163,18 @@ export function clearDefenseEvents(projectRoot) {
 }
 /** Add a defense event to the stream. */
 export function addDefenseEvent(stream, event) {
+    // 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 = {
-        ...event,
+        ...rest,
+        ...(usableLine !== undefined ? { line: usableLine } : {}),
         id: `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
         timestamp: new Date().toISOString(),
     };

package/dist/tools/experience-bank.js

@@ -7,11 +7,18 @@
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
-import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience } from "./experience-store.js";
+import { withProjectLock } from "../file-lock.js";
+import { readExperienceBank, writeExperienceBank, searchExperienceEntries, upsertExperience, removeExperience, isValidExperienceId, MAX_EXPERIENCE_ID_LENGTH } from "./experience-store.js";
+import { resultHeadline } from "./present.js";
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 100;
-/** Clamp a caller-supplied limit to a sane range. */
-function clampLimit(limit) {
+/**
+ * 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) {
     if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
         return DEFAULT_LIMIT;
     }
@@ -67,6 +74,13 @@ function normalizeExperienceInput(raw) {
 export function registerExperienceBankTool(ctx) {
     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) => {
@@ -101,7 +115,8 @@ export function registerExperienceBankTool(ctx) {
             },
             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',
@@ -194,22 +209,44 @@ export function registerExperienceBankTool(ctx) {
                         error: `Invalid experience entry: ${errors.join('; ')}`,
                     };
                 }
-                const bank = readExperienceBank(projectRoot);
-                const { bank: next, added, entryId } = upsertExperience(bank, normalizeExperienceInput(raw));
-                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,
-                    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);
+                    // 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,
+                        totalHits: next.totalHits,
+                    };
+                });
             }
             if (operation === 'remove') {
                 const id = typeof args.id === 'string' && args.id ? args.id : '';
@@ -221,33 +258,50 @@ export function registerExperienceBankTool(ctx) {
                         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,
@@ -258,8 +312,18 @@ export function registerExperienceBankTool(ctx) {
                     totalHits: bank.totalHits ?? 0,
                 };
             }
-            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);
@@ -273,6 +337,7 @@ export function registerExperienceBankTool(ctx) {
                 };
             }
             // 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/dist/tools/experience-store.js

@@ -26,6 +26,41 @@ function stringArray(v) {
         return [];
     return v.filter((x) => 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) {
+    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) {
+    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
@@ -45,7 +80,7 @@ function normalizeEntry(raw, index) {
     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(),
@@ -73,8 +108,16 @@ export function readExperienceBank(projectRoot) {
                 .filter((e) => 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),
             };
         }
     }
@@ -184,8 +227,15 @@ export function upsertExperience(bank, entry) {
         };
     }
     // 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 = {
         ...entry,