@ngockhoale/ukit 2.3.7 → 2.3.9

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,7 +87,21 @@ function readRunCursor() {
 
 (async () => {
   const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
-  if (config?.compact?.hardCapBlock === false) {
+  // 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,
+  };
+  // This is a liveness backstop, not a security control. A present value with the wrong
+  // JSON shape must never leave the gate unexpectedly enabled and brick every mutation once
+  // the cap is reached. Only an explicitly configured boolean `true` enables the gate;
+  // missing preserves the documented default-on behavior for existing installations.
+  const rawHardCapBlock = config?.compact?.hardCapBlock;
+  if (rawHardCapBlock === false || (rawHardCapBlock !== undefined && typeof rawHardCapBlock !== 'boolean')) {
     process.exit(0);
     return;
   }
@@ -111,14 +125,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);
 
@@ -166,8 +180,15 @@ function readRunCursor() {
   }
   const resumable = run || ordinaryTask;
   if (resumable) {
-    const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
-      ? config.compact.hardCapGraceCalls
+    // Invalid config must not turn the landing allowance negative/zero (which makes every
+    // unfinished run hard-block immediately). This hook is a liveness backstop, so malformed
+    // values deliberately fall back to the documented default rather than fail closed.
+    const configuredGraceCalls = config?.compact?.hardCapGraceCalls;
+    const graceCalls = typeof configuredGraceCalls === 'number'
+      && Number.isFinite(configuredGraceCalls)
+      && Number.isInteger(configuredGraceCalls)
+      && configuredGraceCalls > 0
+      ? configuredGraceCalls
       : 10;
 
     let slots = readSlots();

package/templates/.claude/hooks/context-window-guard.sh

@@ -73,7 +73,7 @@ function loadHardCap() {
   try {
     const raw = fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8');
     const value = JSON.parse(raw)?.compact?.hardCapTokens;
-    if (Number.isFinite(value) && value > 0) return value;
+    if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0) return value;
   } catch { /* fall through to the default */ }
   return 500_000;
 }

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,
+    });
   });
 }
 

package/templates/.claude/ukit/index/cache-utils.mjs

@@ -1,6 +1,30 @@
 #!/usr/bin/env node
+// Cache read-modify-write cycles run in separate node processes (query/triage/route/
+// resolve-context hooks and CLI calls can fire concurrently). They must serialize on
+// withFileLock — without it, concurrent writers each append against a stale snapshot
+// and silently drop each other's entries (verified: 20 concurrent writers kept 2).
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { readJson, withFileLock } from '../runtime/token-utils.mjs';
+
+// Cache files stay single-line compact JSON (locked by tests): they sit inside .claude/
+// and pretty-printing them would turn every cache touch into a noisy multi-line diff.
+// Atomic like token-utils writeJson (tmp + rename), only compact.
+async function writeCacheJson(cachePath, value) {
+  await fs.mkdir(path.dirname(cachePath), { recursive: true });
+  const tempPath = `${cachePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await fs.writeFile(tempPath, JSON.stringify(value), 'utf8');
+    await fs.rename(tempPath, cachePath);
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+    throw error;
+  }
+}
 
 export const DEFAULT_RECENT_CACHE_MAX_ENTRIES = 6;
 
@@ -36,14 +60,25 @@ export async function readRecentCacheEntry(
     ...entry,
     updatedAt: Date.now(),
   };
-  const entries = [
-    touchedEntry,
-    ...cache.entries.slice(0, entryIndex),
-    ...cache.entries.slice(entryIndex + 1),
-  ].slice(0, maxEntries);
-  const document = buildCacheDocument(entries, { maxEntries });
-  await writeJson(cachePath, document);
-  return document.entries[0] ?? touchedEntry;
+  return withFileLock(cachePath, async () => {
+    const locked = await readRecentCache(cachePath, { maxEntries });
+    const lockedIndex = locked.entries.findIndex((lockedEntry) => lockedEntry.requestKey === requestKey);
+    if (lockedIndex < 0) {
+      return touchedEntry;
+    }
+    const lockedEntry = {
+      ...locked.entries[lockedIndex],
+      updatedAt: touchedEntry.updatedAt,
+    };
+    const entries = [
+      lockedEntry,
+      ...locked.entries.slice(0, lockedIndex),
+      ...locked.entries.slice(lockedIndex + 1),
+    ].slice(0, maxEntries);
+    const document = buildCacheDocument(entries, { maxEntries });
+    await writeCacheJson(cachePath, document);
+    return document.entries[0] ?? lockedEntry;
+  });
 }
 
 export async function writeRecentCacheEntry(
@@ -56,14 +91,16 @@ export async function writeRecentCacheEntry(
     return readRecentCache(cachePath, { maxEntries });
   }
 
-  const cache = await readRecentCache(cachePath, { maxEntries });
-  const entries = [
-    normalizedEntry,
-    ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
-  ].slice(0, maxEntries);
-  const document = buildCacheDocument(entries, { maxEntries });
-  await writeJson(cachePath, document);
-  return document;
+  return withFileLock(cachePath, async () => {
+    const cache = await readRecentCache(cachePath, { maxEntries });
+    const entries = [
+      normalizedEntry,
+      ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
+    ].slice(0, maxEntries);
+    const document = buildCacheDocument(entries, { maxEntries });
+    await writeCacheJson(cachePath, document);
+    return document;
+  });
 }
 
 function normalizeCacheDocument(raw, { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {}) {
@@ -125,16 +162,3 @@ function normalizeCacheEntry(entry) {
   delete normalizedEntry.entries;
   return normalizedEntry;
 }
-
-async function readJson(filePath, fallback = null) {
-  try {
-    return JSON.parse(await fs.readFile(filePath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-async function writeJson(filePath, value) {
-  await fs.mkdir(path.dirname(typeof filePath === 'string' && filePath ? filePath : '.'), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(value), 'utf8');
-}