iterate-plugin 3.5.3 → 3.5.4

package/src/client/index.ts

@@ -244,6 +244,8 @@ interface ObsManifest {
   timeline?: ObsEntry[]
   nudge?: ObsNudge | null
   approval?: ObsApproval
+  /** Why the run ended: converged / max_rounds_reached / aborted_by_validation. */
+  stoppedReason?: string | null
 }
 
 // ─── Quality command center data types (v3.1+; mirrors src/types.ts) ────────
@@ -735,6 +737,24 @@ function severityLabel(severity: string | undefined): string {
   return SEVERITY_LABEL[coerceSeverity(severity)]
 }
 
+/** Human label for WHY a finished run stopped (transcript manifest). */
+function stoppedReasonLabel(reason: string | null | undefined): string {
+  switch (reason) {
+    case 'converged': return '已结束 · 已收敛（无新发现）'
+    case 'max_rounds_reached': return '已结束 · 达到轮数上限'
+    case 'aborted_by_validation': return '已结束 · 验证失败后回滚停止'
+    case 'aborted_by_config': return '已结束 · 验证命令不在白名单（配置需修复）'
+    default: return reason ? `已结束 · ${reason}` : '已结束'
+  }
+}
+
+/** Badge text for the run's live/finished state, annotated with the stop reason. */
+function runStatusText(live: boolean, manifest: ObsManifest | null | undefined): string {
+  if (live) return '运行中'
+  const reason = manifest && typeof manifest.stoppedReason === 'string' ? manifest.stoppedReason : ''
+  return reason ? stoppedReasonLabel(reason) : '已结束'
+}
+
 /** Resolve the slots service: prefer the typed `ctx.slots`, fall back to `ctx.get`. */
 function readSlots(ctx: ClientContext): SlotsService | undefined {
   if (ctx && ctx.slots && typeof ctx.slots.inject === 'function' && typeof ctx.slots.register === 'function') {
@@ -940,7 +960,7 @@ function ConvergenceDashboard(props: SlotProps) {
         title: transcript.active === true
           ? `当前处于「${phase}」阶段（运行中）`
           : `最近一次执行停留在「${phase}」阶段（已结束）`,
-      }, `${phase} · ${transcript.active === true ? '运行中' : '已结束'}`)
+      }, `${phase} · ${runStatusText(transcript.active === true, transcript)}`)
     : null
 
   // v3.0: task_mode indicator (code/iterate)
@@ -2224,7 +2244,7 @@ function ObservatoryPanel(props: SlotProps) {
     return React.createElement('div', { className: 'iterate-obs-block' },
       React.createElement('div', { className: 'iterate-obs-block-head' },
         React.createElement('span', {}, '运行控制台'),
-        React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, live ? '运行中' : '已结束'),
+        React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, runStatusText(live, manifest)),
         React.createElement('span', { className: 'iterate-obs-head-meta' }, `批准策略：${policyLabel}`),
       ),
       React.createElement('div', { className: 'iterate-obs-block-body' },
@@ -2731,7 +2751,7 @@ function ObservatoryPanel(props: SlotProps) {
   return React.createElement('div', { 'data-iterate-root': '', 'data-iterate': 'obs', className: 'iterate-obs' },
     React.createElement('div', { className: 'iterate-obs-head', 'data-closed': open ? undefined : '', onClick: () => setOpen((v) => !v) },
       React.createElement('span', { className: 'iterate-obs-title' }, 'iterate 观测台'),
-      React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, live ? '运行中' : '已结束'),
+      React.createElement('span', { className: 'iterate-obs-badge', 'data-live': live ? '' : undefined }, runStatusText(live, manifest)),
       React.createElement('span', { className: 'iterate-obs-head-meta' }, headMeta || 'runtime'),
       React.createElement('button', {
         className: 'iterate-btn', 'data-ghost': '',

package/src/session-hooks.ts

@@ -7,12 +7,22 @@
  *
  *   - `allow` policy      → the call runs.
  *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
- *                           error to the model.
+ *                           error to the model. Since dsh 0.1.6-alpha.1 the
+ *                           denial carries a structured `info` (name
+ *                           `iterate-approval-gate`, code `APPROVAL_DENIED`,
+ *                           plus the human-readable reason) so durable
+ *                           projections can route it distinctly from a normal
+ *                           tool failure.
  *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
  *                           scheduler routes it through the `approval` service
  *                           (see `@deepseek-ai/dsh-user-approval`), which
  *                           prompts the human and audits an approve/deny pair
  *                           on the session.
+ *   - canceled            → if the caller aborted the invocation before
+ *                           dispatch, return `{ kind: 'cancel' }` (the
+ *                           canonical 0.1.6-alpha.1 cancellation result) so a
+ *                           destructive call never runs (or asks) for a dead
+ *                           request.
  *
  * We deliberately do NOT also add `approved` flags inside the tool bodies:
  * the pre-execute waterfall consumes the human decision before the tool runs,
@@ -29,7 +39,15 @@
 import { loadEffectiveConfig, resolveProjectRoot } from './config-loader.ts'
 import { decideApproval, isDestructiveIterateTool } from './approval-gate.ts'
 import type { Context } from '@deepseek-ai/cordis'
-import type { ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
+import type { ToolErrorInfo, ToolExecution, PreToolDecision } from '@deepseek-ai/dsh-tools'
+
+/** Structured error identity attached to policy denials (dsh 0.1.6-alpha.1:
+ *  `deny.info` lets durable projections / retry / replay distinguish an
+ *  approval-policy denial from a tool-thrown failure). */
+const DENY_INFO: ToolErrorInfo = {
+  name: 'iterate-approval-gate',
+  code: 'APPROVAL_DENIED',
+}
 
 /**
  * Build the per-call approval decision for a tool execution.
@@ -49,6 +67,20 @@ export function gateDecision(exec: ToolExecution): PreToolDecision {
   }
   if (!isDestructiveIterateTool(name)) return { kind: 'allow' }
 
+  // dsh 0.1.6-alpha.1: if the caller already aborted this invocation before
+  // dispatch, there is nothing to gate — select the canonical cancellation
+  // result (`cancel`) rather than prompting a human for a dead call or running
+  // `next()` (which would allow) on an aborted one.
+  let signal: Readonly<AbortSignal> | undefined
+  try {
+    signal = exec.signal
+  } catch {
+    signal = undefined
+  }
+  if (signal && typeof signal.aborted === 'boolean' && signal.aborted) {
+    return { kind: 'cancel' }
+  }
+
   // Resolve the project root (use the call's own `path` arg, else the agent's
   // session cwd) to read the effective observatory policy.
   let argPath: string | undefined
@@ -74,7 +106,18 @@ export function gateDecision(exec: ToolExecution): PreToolDecision {
   }
 
   const decision = decideApproval(exec, policy)
-  if (decision.kind === 'deny') return { kind: 'deny', reason: decision.reason }
+  if (decision.kind === 'deny') {
+    return {
+      kind: 'deny',
+      reason: decision.reason,
+      info: {
+        ...DENY_INFO,
+        // ToolErrorInfo.reason (0.1.6-alpha.1): raw user-facing detail kept in
+        // durable state; the model-facing text still only sees `reason` above.
+        reason: decision.reason,
+      },
+    }
+  }
   if (decision.kind === 'ask') return { kind: 'ask', reason: decision.reason }
   return { kind: 'allow' }
 }
@@ -104,7 +147,10 @@ export function registerSessionHooks(ctx: Context): void {
       // to allow, which would bypass consent — so return our ask decision.
       return Promise.resolve(decision)
     }
-    if (decision.kind === 'deny') {
+    if (decision.kind === 'deny' || decision.kind === 'cancel') {
+      // deny: refuse the call. cancel: the caller already aborted this
+      // invocation — selecting the canonical cancellation result instead of
+      // letting `next()` allow it or prompting consent for a dead request.
       return Promise.resolve(decision)
     }
     return next()

package/src/skill-prompt.ts

@@ -95,10 +95,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 => () => {
@@ -135,11 +136,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
@@ -270,6 +275,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.
@@ -289,10 +295,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 => () => {
@@ -328,11 +335,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)
@@ -387,18 +398,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
@@ -459,17 +485,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,
@@ -478,6 +510,8 @@ return {
   converged: converged,
   abortedByValidation: abortedByValidation,
   failedCommands: failedCommands,
+  configErrors: configErrors,
+  stoppedReason: stopReason,
   findingsFixed: fixedCount,
   remainingArchitecturalCount: architectural.length,
   remainingArchitectural: architectural,
@@ -495,10 +529,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/src/tools/context.ts

@@ -336,7 +336,11 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
               // 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 {
               // unreadable/invalid skillDir — skip it

package/src/tools/defense-events.ts

@@ -91,9 +91,13 @@ export function registerDefenseEventsTool(ctx: { tools: { register: (def: Return
   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 as { operation?: unknown }).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 as { operation?: unknown }).operation
+        return op !== 'record' && op !== 'clear'
+      },
       description:
         'Query, record, or clear defense events: precondition failures, rollbacks, invariant violations, ' +
         'and assumption falsifications. ' +

package/src/tools/defense-store.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { iterateDir } from '../paths.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { hashString } from './fix.ts'
 import type { DefenseEvent, DefenseEventStream, DefenseEventType } from '../types.ts'
 
 const DEFENSE_EVENTS_FILE = 'defense-events.json'
@@ -54,14 +55,18 @@ const VALID_SEVERITIES: ReadonlySet<string> = new Set(['critical', 'high', 'medi
  * `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: unknown): DefenseEvent | null {
+function normalizeEvent(raw: unknown, index: number): DefenseEvent | null {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
   const e = raw as Record<string, unknown>
   if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type as DefenseEventType)) 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 as DefenseEventType,
@@ -89,7 +94,7 @@ export function readDefenseEvents(projectRoot: string): DefenseEventStream {
     const parsed = JSON.parse(content) as Partial<DefenseEventStream>
     if (parsed && Array.isArray(parsed.events)) {
       const events = parsed.events
-        .map(normalizeEvent)
+        .map((raw, i) => normalizeEvent(raw, i))
         .filter((e): e is DefenseEvent => e !== null)
       const counts = computeCounts(events)
       return {
@@ -155,11 +160,13 @@ export function addDefenseEvent(
   stream: DefenseEventStream,
   event: Omit<DefenseEvent, 'id' | 'timestamp'>
 ): DefenseEventStream {
-  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: DefenseEvent = {
-    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

package/src/tools/experience-bank.ts

@@ -72,9 +72,12 @@ export function registerExperienceBankTool(ctx: { tools: { register: (def: Retur
   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 as { operation?: unknown }).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 as { operation?: unknown }).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"). ' +

package/src/tools/experience-store.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs'
 import * as path from 'node:path'
 import { iterateDir } from '../paths.ts'
 import { writeJsonAtomic } from '../atomic-fs.ts'
+import { hashString } from './fix.ts'
 import type { ExperienceBank, ExperienceEntry } from '../types.ts'
 
 const EXPERIENCE_FILE = 'experience.json'
@@ -38,12 +39,15 @@ function stringArray(v: unknown): string[] {
  * throw or emit NaN. Returns null for non-object entries; every required field
  * gets a safe default.
  */
-function normalizeEntry(raw: unknown): ExperienceEntry | null {
+function normalizeEntry(raw: unknown, index: number): ExperienceEntry | null {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
   const e = raw as Record<string, unknown>
   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
   return {
@@ -70,7 +74,7 @@ export function readExperienceBank(projectRoot: string): ExperienceBank {
     const parsed = JSON.parse(content) as Partial<ExperienceBank>
     if (parsed && Array.isArray(parsed.entries)) {
       const entries = parsed.entries
-        .map(normalizeEntry)
+        .map((raw, i) => normalizeEntry(raw, i))
         .filter((e): e is ExperienceEntry => e !== null)
       return {
         entries,
@@ -167,8 +171,11 @@ export type ExperienceEntryInput = Omit<
 /**
  * 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.
@@ -186,11 +193,14 @@ export function upsertExperience(
     : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension)
 
   if (existing) {
-    const updated: ExperienceEntry = {
-      ...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: ExperienceEntry = byId
+      ? { ...existing, ...entry, id: existing.id, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
+      : { ...existing, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
     return {
       bank: {
         ...bank,
@@ -203,14 +213,16 @@ export function upsertExperience(
     }
   }
 
-  // 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: ExperienceEntry = {
+    ...entry,
     id,
     timestamp: lastUpdated,
     hitCount: 1,
     lastHitAt: lastUpdated,
-    ...entry,
   }
 
   return {