@ngockhoale/ukit 2.3.6 → 2.3.8

package/templates/.claude/hooks/auto-allow-bash.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # PreToolUse hook: auto-add Bash(<binary>:*) allow rules for frequently used commands.
-# Optimized: fast-path grep to skip Node.js when rule already exists.
+# Settings/usage updates run as ONE locked, atomic read-modify-write (see node block).
 
 INPUT=$(cat)
 # jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
@@ -61,30 +61,22 @@ RULE="Bash(${BIN}:*)"
 NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 MAX_RULES="${CLAUDE_AUTO_ALLOW_MAX_RULES:-150}"
 
-# Fast path: if rule already exists in allow list, just update usage and exit
-if [ -f "$SETTINGS_LOCAL" ] && grep -Fq -- "\"$RULE\"" "$SETTINGS_LOCAL" 2>/dev/null; then
-  # Only update usage timestamp (lighter than full Node.js logic)
-  node -e '
-    const fs = require("fs");
-    const usagePath = process.argv[1];
-    const rule = process.argv[2];
-    const nowUtc = process.argv[3];
-    if (!fs.existsSync(usagePath)) {
-      fs.mkdirSync(require("path").dirname(usagePath), { recursive: true });
-      fs.writeFileSync(usagePath, "{}");
-    }
-    try {
-      const usage = JSON.parse(fs.readFileSync(usagePath, "utf8"));
-      if (!usage.managedRules) usage.managedRules = {};
-      const prev = usage.managedRules[rule] || {};
-      usage.managedRules[rule] = { firstSeen: prev.firstSeen || nowUtc, lastSeen: nowUtc };
-      fs.writeFileSync(usagePath, JSON.stringify(usage, null, 2) + "\n");
-    } catch {}
-  ' "$USAGE_FILE" "$RULE" "$NOW_UTC" >/dev/null 2>&1 || true
-  exit 0
-fi
-
-# Slow path: rule is new, need full Node.js processing
+# Single locked read-modify-write for settings.local.json + permission-usage.json.
+#
+# Why the lock: parallel hook invocations (main session + subagents) each used to read a
+# stale snapshot and rewrite the whole file, silently dropping each other's allow rules
+# (verified: 30 concurrent invocations kept 26/30 rules and 23/30 usage records). A lost
+# rule means the NEXT invocation of that command prompts for permission again — the agent
+# stalls waiting for a human click. The lock protocol below is protocol-compatible with
+# runtime token-utils withFileLock / src/core/fileOps.js (mkdir-based `<file>.lock`),
+# with the usage file as the single serialization point for both files this hook writes.
+#
+# Why atomic writes: Claude Code re-reads settings.local.json to decide permissions.
+# A torn/partial write would fail JSON parsing and drop the ENTIRE allow list — every
+# command would prompt. tmp+rename makes readers see old-or-new, never half.
+#
+# Liveness over strictness: if the lock cannot be acquired within maxWaitMs the mutation
+# runs anyway (pre-lock behaviour) — this hook must never hang a PreToolUse chain.
 node -e '
 const fs = require("fs");
 const path = require("path");
@@ -105,66 +97,118 @@ function readJson(filePath, fallback) {
   }
 }
 
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n");
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {}
+    throw error;
+  }
+}
+
 function appendAudit(event, payload) {
   fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
-const settingsDir = path.dirname(settingsPath);
-const usageDir = path.dirname(usagePath);
-fs.mkdirSync(settingsDir, { recursive: true });
-fs.mkdirSync(usageDir, { recursive: true });
-
-const settings = readJson(settingsPath, {});
-if (!settings.permissions || typeof settings.permissions !== "object") {
-  settings.permissions = {};
-}
-if (!Array.isArray(settings.permissions.allow)) {
-  settings.permissions.allow = [];
+async function withLock(lockPath, fn) {
+  const staleMs = 10000;
+  const maxWaitMs = 5000;
+  const startedAt = Date.now();
+  let held = false;
+  while (!held) {
+    try {
+      fs.mkdirSync(lockPath);
+      held = true;
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") return fn();
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > staleMs) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            continue;
+          } catch {}
+        }
+      } catch {}
+      if (Date.now() - startedAt > maxWaitMs) break;
+      await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (held) {
+      try {
+        fs.rmdirSync(lockPath);
+      } catch {}
+    }
+  }
 }
 
-const usage = readJson(usagePath, {});
-if (!usage.managedRules || typeof usage.managedRules !== "object") {
-  usage.managedRules = {};
-}
+// The lock directory lives beside the usage file, so its parent must exist BEFORE the
+// lock is taken — a first-ever run in a fresh project would otherwise fail mkdir with
+// ENOENT, fail open, and race.
+fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+fs.mkdirSync(path.dirname(usagePath), { recursive: true });
 
-const allow = settings.permissions.allow;
-let changed = false;
+withLock(`${usagePath}.lock`, () => {
+  const settings = readJson(settingsPath, {});
+  if (!settings.permissions || typeof settings.permissions !== "object") {
+    settings.permissions = {};
+  }
+  if (!Array.isArray(settings.permissions.allow)) {
+    settings.permissions.allow = [];
+  }
 
-if (!allow.includes(rule)) {
-  allow.push(rule);
-  changed = true;
-  appendAudit("auto_add", { rule });
-}
+  const usage = readJson(usagePath, {});
+  if (!usage.managedRules || typeof usage.managedRules !== "object") {
+    usage.managedRules = {};
+  }
 
-const prevMeta = usage.managedRules[rule] || {};
-usage.managedRules[rule] = {
-  firstSeen: prevMeta.firstSeen || nowUtc,
-  lastSeen: nowUtc,
-};
+  const allow = settings.permissions.allow;
+  let settingsChanged = false;
 
-const managedSorted = Object.entries(usage.managedRules).sort((a, b) => {
-  const ta = Date.parse(a[1]?.lastSeen || "") || 0;
-  const tb = Date.parse(b[1]?.lastSeen || "") || 0;
-  return tb - ta;
-});
+  if (!allow.includes(rule)) {
+    allow.push(rule);
+    settingsChanged = true;
+    appendAudit("auto_add", { rule });
+  }
 
-if (managedSorted.length > maxRules) {
-  const evict = managedSorted.slice(maxRules);
-  for (const [evictRule] of evict) {
-    delete usage.managedRules[evictRule];
-    const idx = allow.indexOf(evictRule);
-    if (idx !== -1) {
-      allow.splice(idx, 1);
-      changed = true;
+  const prevMeta = usage.managedRules[rule] || {};
+  usage.managedRules[rule] = {
+    firstSeen: prevMeta.firstSeen || nowUtc,
+    lastSeen: nowUtc,
+  };
+
+  const managedSorted = Object.entries(usage.managedRules).sort((a, b) => {
+    const ta = Date.parse(a[1]?.lastSeen || "") || 0;
+    const tb = Date.parse(b[1]?.lastSeen || "") || 0;
+    return tb - ta;
+  });
+
+  if (managedSorted.length > maxRules) {
+    const evict = managedSorted.slice(maxRules);
+    for (const [evictRule] of evict) {
+      delete usage.managedRules[evictRule];
+      const idx = allow.indexOf(evictRule);
+      if (idx !== -1) {
+        allow.splice(idx, 1);
+        settingsChanged = true;
+      }
+      appendAudit("auto_prune_cap", { rule: evictRule, maxRules });
     }
-    appendAudit("auto_prune_cap", { rule: evictRule, maxRules });
   }
-}
 
-if (changed) {
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-}
-fs.writeFileSync(usagePath, JSON.stringify(usage, null, 2) + "\n");
+  if (settingsChanged) {
+    writeJsonAtomic(settingsPath, settings);
+  }
+  writeJsonAtomic(usagePath, usage);
+}).catch(() => {});
 ' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$RULE" "$NOW_UTC" "$MAX_RULES" >/dev/null 2>&1 || true
 
 exit 0

package/templates/.claude/hooks/auto-prune-bash.sh

@@ -15,6 +15,7 @@ NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 node -e '
 const fs = require("fs");
+const path = require("path");
 
 const settingsPath = process.argv[1];
 const usagePath = process.argv[2];
@@ -31,45 +32,102 @@ function readJson(filePath) {
   }
 }
 
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n");
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {}
+    throw error;
+  }
+}
+
 function appendAudit(event, payload) {
   fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
-const settings = readJson(settingsPath);
-const usage = readJson(usagePath);
-if (!settings || !usage) process.exit(0);
-if (!settings.permissions || typeof settings.permissions !== "object") process.exit(0);
-if (!Array.isArray(settings.permissions.allow)) process.exit(0);
-if (!usage.managedRules || typeof usage.managedRules !== "object") process.exit(0);
-
-const allow = settings.permissions.allow;
-let changedSettings = false;
-let prunedCount = 0;
-
-for (const [rule, meta] of Object.entries(usage.managedRules)) {
-  const lastSeen = Date.parse(meta?.lastSeen || "");
-  if (!Number.isFinite(lastSeen) || lastSeen >= cutoff) continue;
-
-  const idx = allow.indexOf(rule);
-  if (idx !== -1) {
-    allow.splice(idx, 1);
-    changedSettings = true;
+// Same lock point as auto-allow-bash.sh (<usage>.lock): the two hooks serialize their
+// settings/usage rewrites against each other and against parallel invocations. Atomic
+// writes because Claude Code re-reads settings.local.json — a torn write would drop the
+// ENTIRE allow list and every command would prompt again. Fail-open after 5s: a hook
+// must never hang the chain.
+async function withLock(lockPath, fn) {
+  const staleMs = 10000;
+  const maxWaitMs = 5000;
+  const startedAt = Date.now();
+  let held = false;
+  while (!held) {
+    try {
+      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+      fs.mkdirSync(lockPath);
+      held = true;
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") return fn();
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > staleMs) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            continue;
+          } catch {}
+        }
+      } catch {}
+      if (Date.now() - startedAt > maxWaitMs) break;
+      await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (held) {
+      try {
+        fs.rmdirSync(lockPath);
+      } catch {}
+    }
   }
-  delete usage.managedRules[rule];
-  prunedCount += 1;
-  appendAudit("auto_prune_ttl", { rule, ttlDays });
 }
 
-usage.lastPruneAt = nowUtc;
+withLock(`${usagePath}.lock`, async () => {
+  const settings = readJson(settingsPath);
+  const usage = readJson(usagePath);
+  if (!settings || !usage) return;
+  if (!settings.permissions || typeof settings.permissions !== "object") return;
+  if (!Array.isArray(settings.permissions.allow)) return;
+  if (!usage.managedRules || typeof usage.managedRules !== "object") return;
 
-if (changedSettings) {
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-}
-fs.writeFileSync(usagePath, JSON.stringify(usage, null, 2) + "\n");
+  const allow = settings.permissions.allow;
+  let changedSettings = false;
+  let prunedCount = 0;
 
-if (prunedCount > 0) {
-  appendAudit("auto_prune_summary", { prunedCount, ttlDays });
-}
+  for (const [rule, meta] of Object.entries(usage.managedRules)) {
+    const lastSeen = Date.parse(meta?.lastSeen || "");
+    if (!Number.isFinite(lastSeen) || lastSeen >= cutoff) continue;
+
+    const idx = allow.indexOf(rule);
+    if (idx !== -1) {
+      allow.splice(idx, 1);
+      changedSettings = true;
+    }
+    delete usage.managedRules[rule];
+    prunedCount += 1;
+    appendAudit("auto_prune_ttl", { rule, ttlDays });
+  }
+
+  usage.lastPruneAt = nowUtc;
+
+  if (changedSettings) {
+    writeJsonAtomic(settingsPath, settings);
+  }
+  writeJsonAtomic(usagePath, usage);
+
+  if (prunedCount > 0) {
+    appendAudit("auto_prune_summary", { prunedCount, ttlDays });
+  }
+}).catch(() => {});
 ' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$TTL_DAYS" "$NOW_UTC" >/dev/null 2>&1 || true
 
 exit 0

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -87,6 +87,15 @@ function readRunCursor() {
 
 (async () => {
   const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
+  // Session-scoped pressure bookkeeping: the gate decides for THIS session's record, so a
+  // sibling session starting (SessionStart reset) or compacting never trips or clears
+  // this gate for the wrong session.
+  const sessionConfig = {
+    ...config,
+    sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
+      ? payload.session_id.trim()
+      : undefined,
+  };
   if (config?.compact?.hardCapBlock === false) {
     process.exit(0);
     return;
@@ -111,14 +120,14 @@ function readRunCursor() {
   // bricks a healthy session at this cap. The transcript's own compact_boundary entries
   // are the reliable record of real compactions, so sync before deciding, and persist the
   // reset so it re-arms exactly once per boundary instead of disabling the gate.
-  let state = mod.buildCompactPressureState(rawState, config);
+  let state = mod.buildCompactPressureState(rawState, sessionConfig);
   try {
-    const synced = await mod.syncCompactPressureStateWithTranscript(rawState, config, payload.transcript_path);
+    const synced = await mod.syncCompactPressureStateWithTranscript(state, sessionConfig, payload.transcript_path);
     if (synced.reset) {
-      state = await mod.writeCompactPressureState(projectRoot, synced.state, config);
+      state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
     }
   } catch {
-    state = mod.buildCompactPressureState(rawState, config);
+    state = mod.buildCompactPressureState(rawState, sessionConfig);
   }
   const thresholds = mod.buildCompactThresholds(config);
 

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -1,25 +1,129 @@
 #!/bin/bash
-# SessionStart hook: zero the compact pressure tracker at the start of every session.
+# SessionStart hook: clear THIS session's compact pressure record at session start.
 #
-# compact-pressure.json is a single per-project file whose sessionTokens counter only ever
-# accumulates (see registerPromptPressure/registerOutputPressure in compact-threshold.mjs).
-# Without this reset it sums every prompt and every command output across the entire
-# lifetime of the project, so it eventually crosses compact.hardCapTokens and permanently
-# blocks Edit/Write/Bash in every future session -- even when actual context is tiny.
-# That is a deadlock: the gate blocks Bash, so the documented remedies (ukit install,
-# ukit doctor) cannot run, and compaction never fires because real context is small.
+# compact-pressure.json stores one record per session id (see compact-threshold.mjs).
+# sessionTokens accumulates within a record, so a record left over from a previous
+# session would keep counting against this one — eventually crossing
+# compact.hardCapTokens and blocking Edit/Write/Bash even when actual context is tiny.
+# Clearing the calling session's record at start makes the counter measure THIS session,
+# and gives the gate a guaranteed escape hatch: restarting the session always clears a
+# stuck gate, with no manual file surgery.
 #
-# Resetting here makes the counter measure THIS session only, which is what the hard cap
-# is actually trying to approximate. It also gives the gate a guaranteed escape hatch:
-# restarting the session always clears a stuck gate, with no manual file surgery.
+# Session-scoped (P1 fix): an earlier version deleted the whole file, which also erased
+# the pressure history of any OTHER live session in this project — that session silently
+# lost its near-cap warnings and could run into the real context cap. Now only the
+# calling session's record is removed; sibling records and the legacy flat file content
+# are preserved.
 #
 # Always exits 0 -- a failure here must never prevent a session from starting.
 
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 PRESSURE_FILE="$PROJECT_ROOT/.ukit/storage/cache/compact-pressure.json"
 
-if [ -f "$PRESSURE_FILE" ]; then
-  rm -f "$PRESSURE_FILE" 2>/dev/null || true
+if [ ! -f "$PRESSURE_FILE" ]; then
+  exit 0
 fi
 
+# The lock directory lives beside the state file; its parent exists because the file does.
+node -e '
+const fs = require("fs");
+
+async function withLock(lockPath, fn) {
+  const staleMs = 10000;
+  const maxWaitMs = 5000;
+  const startedAt = Date.now();
+  let held = false;
+  while (!held) {
+    try {
+      fs.mkdirSync(lockPath);
+      held = true;
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") return fn();
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > staleMs) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            continue;
+          } catch {}
+        }
+      } catch {}
+      if (Date.now() - startedAt > maxWaitMs) break;
+      await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (held) {
+      try {
+        fs.rmdirSync(lockPath);
+      } catch {}
+    }
+  }
+}
+
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  const payload = (() => {
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    } catch {
+      return {};
+    }
+  })();
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
+  const pressurePath = process.argv[1];
+
+  withLock(`${pressurePath}.lock`, () => {
+    const raw = (() => {
+      try {
+        return JSON.parse(fs.readFileSync(pressurePath, "utf8"));
+      } catch {
+        return null;
+      }
+    })();
+    if (!raw || typeof raw !== "object") {
+      try {
+        fs.rmSync(pressurePath, { force: true });
+      } catch {}
+      return;
+    }
+
+    // Without a session id (unknown caller) keep the old whole-file reset: this hook is
+    // the documented escape hatch for a bricked gate, and it must stay one.
+    if (!sessionId || !raw.sessions || typeof raw.sessions !== "object") {
+      try {
+        fs.rmSync(pressurePath, { force: true });
+      } catch {}
+      return;
+    }
+
+    const sessions = { ...raw.sessions };
+    delete sessions[sessionId];
+    const newest = Object.entries(sessions)
+      .sort(([, a], [, b]) => (b?.updatedAt ?? 0) - (a?.updatedAt ?? 0))[0]?.[1] ?? null;
+    const tempPath = `${pressurePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    try {
+      fs.writeFileSync(
+        tempPath,
+        JSON.stringify({
+          ...(newest && typeof newest === "object" ? newest : {}),
+          updatedAt: newest?.updatedAt ?? Date.now(),
+          v: 2,
+          sessions,
+        }, null, 2) + "\n",
+      );
+      fs.renameSync(tempPath, pressurePath);
+    } catch (error) {
+      try {
+        fs.rmSync(tempPath, { force: true });
+      } catch {}
+      throw error;
+    }
+  }).catch(() => {});
+});
+' "$PRESSURE_FILE" >/dev/null 2>&1 || true
+
 exit 0

package/templates/.claude/hooks/verification-guard.sh

@@ -20,9 +20,64 @@ function readJson(filePath, fallback = null) {
   }
 }
 
-function writeJson(filePath, value) {
+function writeJsonAtomic(filePath, value) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(value));
+  const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + '\n');
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {}
+    throw error;
+  }
+}
+
+// Sync sleep without burning CPU — the hook's flow calls process.exit right after
+// persistAttempt, so the critical section must complete synchronously.
+function sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
+// mkdir-based lock, protocol-compatible with runtime token-utils withFileLock. Sync on
+// purpose (see sleepSync). Fail-open after 5s: this hook must never hang a PreToolUse
+// chain, and a lost progress entry only costs one repeated advisory.
+function withLockSync(lockPath, fn) {
+  const staleMs = 10000;
+  const maxWaitMs = 5000;
+  const startedAt = Date.now();
+  let held = false;
+  while (!held) {
+    try {
+      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+      fs.mkdirSync(lockPath);
+      held = true;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') return fn();
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > staleMs) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            continue;
+          } catch {}
+        }
+      } catch {}
+      if (Date.now() - startedAt > maxWaitMs) break;
+      sleepSync(3 + Math.floor(Math.random() * 9));
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    if (held) {
+      try {
+        fs.rmdirSync(lockPath);
+      } catch {}
+    }
+  }
 }
 
 function normalizeCommand(value) {
@@ -316,23 +371,36 @@ function persistAttempt(commandText) {
   const normalizedCommandText = normalizeCommand(commandText);
   attemptedCommands.add(normalizedCommandText);
   const now = Date.now();
-  const recentAttempts = [
-    ...(progress?.recentAttempts ?? []),
-    { command: normalizedCommandText, ts: now },
-  ]
-    .map((entry) => ({
-      command: normalizeCommand(entry?.command),
-      ts: Number(entry?.ts ?? now),
-    }))
-    .filter((entry) => entry.command && Number.isFinite(entry.ts) && now - entry.ts <= STATE_FRESH_MS)
-    .filter((entry, index, list) => (
-      list.findLastIndex((candidate) => candidate.command === entry.command) === index
-    ));
-  writeJson(progressPath, {
-    fingerprint: state?.fingerprint || null,
-    updatedAt: now,
-    attemptedCommands: [...attemptedCommands],
-    recentAttempts,
+  // Locked re-read + merge: parallel subagents record attempts concurrently, and a
+  // stale-snapshot rewrite would silently drop their entries — the guard would then keep
+  // advising instead of allowing, re-litigating verification order forever.
+  withLockSync(`${progressPath}.lock`, () => {
+    const current = readJson(progressPath, {});
+    const mergedAttempts = new Set(collectAttemptedCommands(current, {
+      currentFingerprint: state?.fingerprint || null,
+      maxAgeMs: STATE_FRESH_MS,
+    }));
+    for (const command of attemptedCommands) {
+      mergedAttempts.add(command);
+    }
+    const recentAttempts = [
+      ...(current?.recentAttempts ?? []),
+      { command: normalizedCommandText, ts: now },
+    ]
+      .map((entry) => ({
+        command: normalizeCommand(entry?.command),
+        ts: Number(entry?.ts ?? now),
+      }))
+      .filter((entry) => entry.command && Number.isFinite(entry.ts) && now - entry.ts <= STATE_FRESH_MS)
+      .filter((entry, index, list) => (
+        list.findLastIndex((candidate) => candidate.command === entry.command) === index
+      ));
+    writeJsonAtomic(progressPath, {
+      fingerprint: state?.fingerprint || null,
+      updatedAt: now,
+      attemptedCommands: [...mergedAttempts],
+      recentAttempts,
+    });
   });
 }