iterate-plugin 3.5.3 → 3.5.5

package/dist/skill-prompt.js

@@ -94,10 +94,11 @@ for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -134,11 +135,15 @@ for (let r = 1; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
   // list stays bounded and reviewers never see the same issue twice.
   if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
@@ -269,6 +274,7 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+let configErrors = []          // validation commands NOT in validation.commands (config gap, no rollback)
 const fixRecords = []        // observatory fix records collected round by round
 
 // Read any steering nudge intended for this run's reviewers.
@@ -288,10 +294,11 @@ for (let r = startRound; r <= maxRounds; r++) {
   )
   let agg = null
   let schemaInvalid = false
-  let retries = 0
+  let attempts = 0
   do {
+    attempts += 1
     // Schema validation retry: on the 2nd+ pass, nudge reviewers toward strict JSON.
-    const nudge = retries > 0
+    const nudge = attempts > 1
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => {
@@ -327,11 +334,15 @@ for (let r = startRound; r <= maxRounds; r++) {
     schemaInvalid = agg && agg.schemaValidation && agg.schemaValidation.length > 0
       ? agg.schemaValidation[agg.schemaValidation.length - 1].valid === false
       : false
-    if (schemaInvalid && retries < 2) {
-      retries += 1
-      log('retry ' + retries + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
+    if (schemaInvalid && attempts < 3) {
+      log('retry ' + attempts + ': round ' + r + ' output failed schema validation — re-running reviewers with strict-JSON emphasis')
     }
-  } while (schemaInvalid && retries <= 2)
+  } while (schemaInvalid && attempts < 3)
+  if (schemaInvalid) {
+    // Bounded exit: never loop forever. Surface the failure so the run's
+    // final summary can explain WHY the round was inconclusive.
+    log('round ' + r + ' output STILL schema-invalid after 3 attempts — marking round inconclusive (NOT converged)')
+  }
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
   const atomic = findings.filter(f => f.is_atomic === true)
   const remaining = findings.filter(f => f.is_atomic !== true)
@@ -345,10 +356,10 @@ for (let r = startRound; r <= maxRounds; r++) {
     const byFile = {}
     atomic.forEach(f => { (byFile[f.file] = byFile[f.file] || []).push(f) })
     const fixRes = await parallel(Object.keys(byFile).map(file => () => agent(
-      'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
+      'Apply the fixes for ' + JSON.stringify(file) + ' using iterate_fix. For EACH finding in this list, ' +
       'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
-      'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
-      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff and ' +
+      'iterate_fix({ file: ' + JSON.stringify(file) + ', content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: ' + JSON.stringify(file) + ' }) to verify the accumulated diff and ' +
       'read its line statistics (lines added/removed). ' +
       'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error, file, linesAdded, linesRemoved} per iterate_fix call ' +
       '(id/ok required; put the file-wide line stats from iterate_diff on each record, or on the last record and 0 elsewhere).',
@@ -386,18 +397,33 @@ for (let r = startRound; r <= maxRounds; r++) {
     if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
   }
 
-  // Validate every configured command; on ANY failure roll back this round's fixes.
+  // Validate every configured command; on ANY *executed* failure roll back this
+  // round's fixes. iterate_validate returns \`allowed:false\` + \`rejectReason\`
+  // when a command is NOT in validation.commands (a config gap, NOT a code
+  // failure) — those abort the run WITHOUT rolling back (the code changes are
+  // fine; the trust list just needs fixing).
   const valRes = await agent(
     'Read iterate.config.yaml validation.commands, then call iterate_validate({ command: <cmd> }) for EACH configured command ' +
-    '(one tool call per command). Return all results as {command, exitCode} entries.',
+    '(one tool call per command). Return all results as {command, exitCode, allowed, rejectReason} entries — include \`allowed\` and \`rejectReason\` exactly as returned by iterate_validate (allowed:false means the command is not in validation.commands).',
     Object.assign({ label: 'validate:r' + r, phase: 'validate', schema: {
       type: 'object', additionalProperties: false,
       properties: {
-        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' } }, required: ['command', 'exitCode'] } }
+        results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' }, allowed: { type: 'boolean' }, rejectReason: { type: 'string' } }, required: ['command', 'exitCode'] } }
       },
       required: ['results'] } }, backend)
   )
-  failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
+  const valResults = (valRes && Array.isArray(valRes.results)) ? valRes.results : []
+  configErrors = valResults.filter(v => v.allowed === false).map(v => v.rejectReason || (v.command + ' was rejected'))
+  failedCommands = valResults.filter(v => !(v.allowed === false) && v.exitCode !== 0).map(v => v.command)
+  if (configErrors.length > 0) {
+    log('round ' + r + ' validation CONFIG error (not in validation.commands): ' + configErrors.join(' | ') + ' — aborting WITHOUT rollback (code changes are kept; the command trust list needs updating)')
+    abortedByValidation = true
+    await agent(
+      'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{configErrors:' + JSON.stringify(configErrors) + ', rolledBack:0, reason:"command not in validation.commands"}})',
+      Object.assign({ label: 'log:configError:r' + r }, backend)
+    )
+    break
+  }
   if (failedCommands.length > 0) {
     log('round ' + r + ' validation FAILED on: ' + failedCommands.join(', ') + ' — rolling back this round')
     abortedByValidation = true
@@ -458,17 +484,23 @@ if (!abortedByValidation) {
 }
 // Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
 // so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
-const obsCheckpoint = abortedByValidation ? null : {
-  mode: 'normal',
-  round: rounds.length,
-  maxRounds: maxRounds,
-  fixedCount: fixedCount,
-  resumeCount: effectiveResumeCount,
-}
-await agent(
-  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
-  { label: 'transcript:capture' }
-)
+// The checkpoint survives on disk for aborted runs (that is how resumption
+  // works), so the transcript must mirror that reality — a null checkpoint here
+  // would hide the very thing F5 is meant to resume. Reflect what is on disk.
+  const obsCheckpoint = {
+    mode: 'normal',
+    round: rounds.length,
+    maxRounds: maxRounds,
+    fixedCount: fixedCount,
+    resumeCount: effectiveResumeCount,
+  }
+  const stopReason = abortedByValidation
+    ? (configErrors.length > 0 ? 'aborted_by_config' : 'aborted_by_validation')
+    : (converged ? 'converged' : 'max_rounds_reached')
+  await agent(
+    'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', stoppedReason:"' + stopReason + '", fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+    { label: 'transcript:capture' }
+  )
 return {
   mode: 'normal',
   goal: plan.goal,
@@ -477,6 +509,8 @@ return {
   converged: converged,
   abortedByValidation: abortedByValidation,
   failedCommands: failedCommands,
+  configErrors: configErrors,
+  stoppedReason: stopReason,
   findingsFixed: fixedCount,
   remainingArchitecturalCount: architectural.length,
   remainingArchitectural: architectural,
@@ -494,10 +528,10 @@ return {
 Key rules for normal mode:
 - Fixers are the ONLY agents allowed to write files, and they must go through \`iterate_fix\` — never edit files directly. That is what gives every change a backup, a diff, and a rollback path. Reviewers read only. Architectural findings are reported, never auto-fixed.
 - Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
-- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`.
+- **Schema validation & retry**: when \`reviewer.output_schema_validation\` is on (default), retry the round's reviewers up to 2 times (3 attempts total) when \`aggregate\` reports \`schemaValidation\` valid=false for it, then re-aggregate. Never forward schema-invalid findings into \`iterate_fix\`. If the output is still schema-invalid after the 3rd attempt, mark the round inconclusive (never report it as a clean convergence).
 - Apply atomic fixes **per file**: one fixer agent handles all findings for a given file serially (so the same file is never edited concurrently); different files are fixed in parallel.
 - **Resume**: load the checkpoint first; if a previous run left one, continue from \`checkpoint.round + 1\` (its \`fixedCount\` and deduped \`findings\` are carried forward).
-- **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed).
+- **Validate after every round** of fixes; on ANY validation failure, roll back the round's fixes via \`iterate_rollback\` and stop (the checkpoint is left in place so the run can be resumed). EXCEPTION: \`iterate_validate\` returning \`allowed:false\` means the command is simply not in \`validation.commands\` — a config gap, not broken code. In that case abort WITHOUT rolling back the round's fixes and surface the missing command + file so the user can fix the trust list.
 - **Checkpoint after every round**; clear it only when the iteration completes cleanly.
 - Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
 - Every round, every rollback, and the final report go to the append-only decision log.

package/dist/tools/context.js

@@ -306,7 +306,11 @@ export function registerContextTool(ctx) {
                         // skillDir point at arbitrary filesystem locations (e.g. /etc)
                         // whose contents would be injected wholesale into the context.
                         if (isAllowedSkillDir(args.skillDir, [projectRoot, PLUGIN_SRC_DIR])) {
-                            candidates.push(resolve(args.skillDir));
+                            // Read from the REAL (symlink-resolved) path that was actually
+                            // validated — never the raw path. Validating one path and then
+                            // reading through a different (swappable) symlink would leave a
+                            // check-vs-read TOCTOU gap; using the realpath here closes it.
+                            candidates.push(realpathSync(resolve(args.skillDir)));
                         }
                     }
                     catch {

package/dist/tools/decision-log.js

@@ -1,9 +1,127 @@
-import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { appendFileSync, readFileSync, mkdirSync, existsSync, openSync, writeSync, closeSync, unlinkSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRootForExec } from "../config-loader.js";
 const LOG_DIR = '.iterate';
 const LOG_FILE = 'decision-log.jsonl';
+// ─── Cross-process log mutex ────────────────────────────────────────────────
+//
+// The prune rewrite (temp + atomic rename) can silently discard an audit line
+// from a CONCURRENT appender whose fd was opened against the pre-rename inode:
+// the appender writes to the unlinked inode, the post-rewrite re-read sees a
+// "stable" file, and the fresh entry is lost. In-process safety is guaranteed
+// by synchronous I/O, but a second plugin process appending to the same
+// project realises the race. The log is serialized with a tiny advisory lock
+// file (exclusive create, pid stamped, stale-stealable) so `append` and the
+// prune rewrite mutually exclude across processes. Best-effort: contention
+// timeouts degrade to "proceed unlocked" (the bounded retry loop in prune.ts
+// stays as defense-in-depth), never to a crash.
+const LOCK_FILE = '.decision-log.lock';
+const LOCK_WAIT_MS = 5000;
+const LOCK_STALE_MS = 10000;
+const LOCK_POLL_MS = 25;
+/** True when a pid refers to a live process (or we lack permission to tell). */
+function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Synchronous busy-wait sleep (Atomics.wait is a reliable sleep in Node). */
+function sleepSync(ms) {
+    const sab = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(sab, 0, 0, ms);
+}
+/**
+ * Acquire the decision-log lock for `projectRoot`.
+ * Returns a release function (always callable; a no-op when the lock could
+ * not be taken — never wedge an append behind a vanished holder).
+ */
+export function acquireLogLock(projectRoot) {
+    const dir = join(projectRoot, LOG_DIR);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return () => { };
+        }
+    }
+    const lockPath = join(dir, LOCK_FILE);
+    const start = Date.now();
+    for (;;) {
+        let fd = null;
+        try {
+            fd = openSync(lockPath, 'wx');
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                return () => { };
+            // Lock exists — steal it when the owner is gone or the lock is ancient.
+            let stale = false;
+            try {
+                const st = statSync(lockPath);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS)
+                    stale = true;
+                else {
+                    const pid = Number(readFileSync(lockPath, 'utf-8'));
+                    if (!processAlive(pid))
+                        stale = true;
+                }
+            }
+            catch {
+                stale = true; // unreadable/vanishing lock → retry as stale
+            }
+            if (stale) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { /* another holder stole it */ }
+                continue;
+            }
+            if (Date.now() - start > LOCK_WAIT_MS)
+                return () => { };
+            sleepSync(LOCK_POLL_MS);
+            continue;
+        }
+        // Owned the lock: stamp the holder pid, then release once on return.
+        try {
+            writeSync(fd, String(process.pid));
+        }
+        catch { /* pid stamp is advisory */ }
+        try {
+            closeSync(fd);
+        }
+        catch { /* best-effort */ }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* already gone */ }
+        };
+    }
+}
+// ─── Entry-count cache (avoid an O(n) full re-read per append) ─────────────
+const entryCountCache = new Map();
+/** Line-count the log file from scratch (entries = non-empty JSON lines). */
+function recountEntries(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return content.split('\n').filter((l) => l.trim().length > 0).length;
+    }
+    catch {
+        return 1;
+    }
+}
 /** All valid DecisionLogEntry `type` values (must stay in sync with Types). */
 const VALID_ENTRY_TYPES = new Set([
     'round_start',
@@ -50,25 +168,32 @@ function logPath(projectRoot) {
  * miss without failing the mutation they already performed.
  */
 export function appendDecisionEntry(projectRoot, entry) {
-    let filePath;
-    try {
-        filePath = logPath(projectRoot);
-        const line = JSON.stringify(entry) + '\n';
-        appendFileSync(filePath, line, 'utf-8');
-    }
-    catch (err) {
-        return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` };
-    }
-    // Count entries
-    let count = 0;
+    // Serialize with the cross-process log lock so an append can never interleave
+    // with a prune rewrite (which renames the file under us).
+    const release = acquireLogLock(projectRoot);
     try {
-        const content = readFileSync(filePath, 'utf-8');
-        count = content.split('\n').filter((l) => l.trim().length > 0).length;
+        const filePath = logPath(projectRoot);
+        try {
+            const line = JSON.stringify(entry) + '\n';
+            const prevSize = existsSync(filePath) ? statSync(filePath).size : 0;
+            appendFileSync(filePath, line, 'utf-8');
+            // Count entries via the size/count cache: when nothing else changed the
+            // file since our last append (same byte size), count is just +1 — no full
+            // re-read. Falls back to a full re-count whenever the cache is stale.
+            const cached = entryCountCache.get(filePath);
+            const count = cached && cached.size === prevSize
+                ? cached.count + 1
+                : recountEntries(filePath);
+            entryCountCache.set(filePath, { size: existsSync(filePath) ? statSync(filePath).size : prevSize, count });
+            return { count, path: filePath };
+        }
+        catch (err) {
+            return { count: 0, path: join(projectRoot, LOG_DIR, LOG_FILE), error: `failed to append decision log: ${String(err)}` };
+        }
     }
-    catch {
-        count = 1;
+    finally {
+        release();
     }
-    return { count, path: filePath };
 }
 /**
  * Read all entries from the decision log, plus the count of corrupt lines.

package/dist/tools/defense-events.js

@@ -72,9 +72,13 @@ function validateRecordInput(args) {
 export function registerDefenseEventsTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_defense_events',
-        // List/counts never write; only `record` persists an event → read shapes
-        // join a parallel dispatch group.
-        isConcurrencySafe: (args) => args.operation !== 'record',
+        // 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.
+        isConcurrencySafe: (args) => {
+            const op = args.operation;
+            return op !== 'record' && op !== 'clear';
+        },
         description: 'Query, record, or clear defense events: precondition failures, rollbacks, invariant violations, ' +
             'and assumption falsifications. ' +
             'List/counts return events with descriptions, outcomes, and summary counts; ' +

package/dist/tools/defense-store.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { iterateDir } from "../paths.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { hashString } from "./fix.js";
 const DEFENSE_EVENTS_FILE = 'defense-events.json';
 /** Valid defense event types (must stay in sync with DefenseEventType). */
 const VALID_EVENT_TYPES = new Set([
@@ -46,16 +47,20 @@ const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
  * `timestamp`/`round`/`description`/`defense`/`outcome`/`severity` — readers
  * (list sort by timestamp, render label selection) must never crash or emit
  * NaN for those. Returns null when the entry is not an object or has no usable
- * `type`; otherwise fills every required field with a safe default.
+ * `type`; otherwise fills every required field with a safe default. An event
+ * missing its `id` gets a DETERMINISTIC id derived from its content and
+ * position (never a random one) so a read→write cycle cannot silently churn
+ * ids on every mutation.
  */
-function normalizeEvent(raw) {
+function normalizeEvent(raw, index) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
     const e = raw;
     if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type))
         return 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 : `def-${Math.random().toString(36).slice(2, 8)}`,
+        id: typeof e.id === 'string' && e.id ? e.id : derivedId,
         timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : new Date().toISOString(),
         round: typeof e.round === 'number' && Number.isFinite(e.round) ? Math.floor(e.round) : 0,
         type: e.type,
@@ -82,7 +87,7 @@ export function readDefenseEvents(projectRoot) {
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.events)) {
             const events = parsed.events
-                .map(normalizeEvent)
+                .map((raw, i) => normalizeEvent(raw, i))
                 .filter((e) => e !== null);
             const counts = computeCounts(events);
             return {
@@ -140,11 +145,13 @@ export function clearDefenseEvents(projectRoot) {
 }
 /** Add a defense event to the stream. */
 export function addDefenseEvent(stream, event) {
-    const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // 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 = {
-        id,
-        timestamp: new Date().toISOString(),
         ...event,
+        id: `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        timestamp: new Date().toISOString(),
     };
     // Always recompute from the events array instead of mutating a possibly
     // stale/malformed persisted `counts` object — guarantees the stream counts

package/dist/tools/experience-bank.js

@@ -67,9 +67,12 @@ function normalizeExperienceInput(raw) {
 export function registerExperienceBankTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_experience',
-        // List/search/get never write; only `add` upserts the bank → read shapes
-        // join a parallel dispatch group.
-        isConcurrencySafe: (args) => args.operation !== 'add',
+        // 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) => {
+            const op = args.operation;
+            return op !== 'add' && op !== 'remove';
+        },
         description: 'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
             'or record a new verified fix (operation:"add"). ' +
             'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +

package/dist/tools/experience-store.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { iterateDir } from "../paths.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { hashString } from "./fix.js";
 const EXPERIENCE_FILE = 'experience.json';
 /** Default empty experience bank. */
 function emptyBank() {
@@ -32,13 +33,16 @@ function stringArray(v) {
  * throw or emit NaN. Returns null for non-object entries; every required field
  * gets a safe default.
  */
-function normalizeEntry(raw) {
+function normalizeEntry(raw, index) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
     const e = raw;
     const pattern = typeof e.pattern === 'string' ? e.pattern : '';
     const dimension = typeof e.dimension === 'string' ? e.dimension : '';
-    const id = typeof e.id === 'string' && e.id ? e.id : `exp-${Math.random().toString(36).slice(2, 8)}`;
+    // Deterministic id (content + position based) so a read→write cycle never
+    // churns random ids on entries that were hand-edited without one.
+    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;
@@ -65,7 +69,7 @@ export function readExperienceBank(projectRoot) {
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.entries)) {
             const entries = parsed.entries
-                .map(normalizeEntry)
+                .map((raw, i) => normalizeEntry(raw, i))
                 .filter((e) => e !== null);
             return {
                 entries,
@@ -142,8 +146,11 @@ export function searchExperienceEntries(entries, query, opts = {}) {
 /**
  * Add or update an experience entry.
  *
- * An entry with an `id` that already exists, OR a new entry whose
- * `pattern`+`dimension` pair matches an existing entry, is treated as a HIT:
+ * An entry with an `id` that already exists is treated as an UPDATE + HIT:
+ * the caller-supplied fields replace the stored ones and the hitCount is
+ * incremented (lastHitAt refreshed) — this fulfills the documented
+ * "update a specific entry via add" contract. A NEW entry whose
+ * `pattern`+`dimension` pair matches an existing entry is treated as a HIT:
  * the matching entry's hitCount is incremented (lastHitAt refreshed) so
  * repeated encounters of the same pattern do not create duplicates. Otherwise
  * a fresh entry is appended with hitCount 1. Never mutates the input bank.
@@ -157,11 +164,14 @@ export function upsertExperience(bank, entry) {
         ? bank.entries.find((e) => e.id === entry.id)
         : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension);
     if (existing) {
-        const updated = {
-            ...existing,
-            hitCount: (existing.hitCount ?? 0) + 1,
-            lastHitAt: lastUpdated,
-        };
+        // Explicit-id updates REPLACE the editable fields (fulfilling the
+        // documented "update a specific entry via add" contract); a pattern+
+        // dimension HIT only bumps the hit metadata so a repeat encounter never
+        // overwrites the curated entry.
+        const byId = typeof entry.id === 'string' && entry.id.length > 0;
+        const updated = byId
+            ? { ...existing, ...entry, id: existing.id, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
+            : { ...existing, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated };
         return {
             bank: {
                 ...bank,
@@ -173,14 +183,16 @@ export function upsertExperience(bank, entry) {
             entryId: existing.id,
         };
     }
-    // Add new 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.
     const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const newEntry = {
+        ...entry,
         id,
         timestamp: lastUpdated,
         hitCount: 1,
         lastHitAt: lastUpdated,
-        ...entry,
     };
     return {
         bank: {

package/dist/tools/fix.js

@@ -364,6 +364,7 @@ export function registerFixTool(ctx) {
                     linesRemoved: { type: 'integer' },
                     diffSummary: { type: 'string' },
                     backupPath: { type: 'string' },
+                    warning: { type: 'string' },
                     error: { type: 'string' },
                 },
             },
@@ -451,6 +452,16 @@ export function registerFixTool(ctx) {
                 if (findFixRecord(registry, id)) {
                     return { ok: false, error: `finding already fixed this run (id: ${id})`, id };
                 }
+                // No-op guard: content-identical "fixes" (e.g. a fixer that re-sent the
+                // file unchanged) must never burn a backup, a write, or a registry/success
+                // record. Placed after the registry check so a re-sent fix of an id that
+                // was ALREADY fixed is still reported as "already fixed this run".
+                if (added === 0 && removed === 0) {
+                    return {
+                        ok: false,
+                        error: `no changes: the supplied content for ${file} is identical to the current content — apply a real edit`,
+                    };
+                }
                 const target = resolveProjectFile(projectRoot, file);
                 if (!target.ok)
                     return { ok: false, error: target.reason };
@@ -521,12 +532,15 @@ export function registerFixTool(ctx) {
                     }
                     return { ok: false, error: `failed to write fix registry: ${String(err)} (file restored from backup)` };
                 }
-                appendDecisionEntry(projectRoot, {
+                const logRes = appendDecisionEntry(projectRoot, {
                     timestamp,
                     round: args.round,
                     type: 'atomic_fix',
                     data: { id, file, finding: finding.summary, linesAdded: added, linesRemoved: removed },
                 });
+                // The fix itself succeeded, but a decision-log write failure would leave
+                // the audit trail incomplete — surface it (warning, not fatal) so the
+                // model/UI knows the record was not persisted.
                 return {
                     ok: true,
                     id,
@@ -536,6 +550,7 @@ export function registerFixTool(ctx) {
                     linesRemoved: removed,
                     diffSummary: record.diffSummary,
                     backupPath,
+                    ...(logRes.error ? { warning: logRes.error } : {}),
                 };
             });
             return result;
@@ -696,6 +711,7 @@ export function registerRollbackTool(ctx) {
                     ok: { type: 'boolean', required: true },
                     id: { type: 'string' },
                     file: { type: 'string' },
+                    warning: { type: 'string' },
                     error: { type: 'string' },
                 },
             },
@@ -736,7 +752,7 @@ export function registerRollbackTool(ctx) {
             catch (err) {
                 return { ok: false, error: `failed to update fix registry: ${String(err)}` };
             }
-            appendDecisionEntry(projectRoot, {
+            const logRes = appendDecisionEntry(projectRoot, {
                 timestamp: new Date().toISOString(),
                 round: record.round,
                 type: 'revert',
@@ -747,7 +763,12 @@ export function registerRollbackTool(ctx) {
             // a missing/corrupt transcript is left untouched and never breaks the
             // rollback flow.
             await markFixRolledBackInTranscript(projectRoot, id);
-            return { ok: true, id, file: record.finding.file };
+            return {
+                ok: true,
+                id,
+                file: record.finding.file,
+                ...(logRes.error ? { warning: logRes.error } : {}),
+            };
         },
     }));
 }