@ngockhoale/ukit 2.3.3 → 2.3.5

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.5 - 2026-09-10
+
+Source-audit hardening release: the code index cannot corrupt itself, and a corrupt runtime
+cache can no longer take down `ukit status` or `ukit memory`.
+
+Index artifacts (`files`, `symbols`, `imports`, `calls`, `tests-map`, `hotspots`,
+`archetypes`, `relations`, `analogs`, `meta`) are now written through same-directory
+`.tmp-<timestamp>-<random>` files followed by an atomic `rename`, in both the source builder
+(`src/index/buildIndex.js`) and the shipped `templates/.claude/ukit/index/lib/index-core.mjs`
+runtime mirror. A build that crashes mid-write — or two builds racing in one repo — can no
+longer leave a half-written artifact that poisons every subsequent index read; failed writes
+clean their temp file up before rethrowing.
+
+`ukit status` and `ukit memory` now read their cache/memory JSON through tolerant readers:
+a corrupt `compact-history.json`, `compact-pressure.json`, `prompt-cache.json`,
+`output-history.json`, or memory file prints a warning naming the exact file path and falls
+back to defaults instead of crashing the whole command mid-report. `readJsonIfExists` itself
+stays strict everywhere else, so genuinely bad callers still fail loudly.
+
+Nested test layouts (`packages/widget/tests/unit/...`) are now recognized as tests by the
+source path classifier and both runtime-mirror predicates — those files previously slipped
+past test detection, broke archetype classification, and never appeared in the test map.
+
+Each fix ships with regression coverage: a rename-spy test asserting all ten artifacts move
+through temp files, corrupt-fixture tests asserting the warned paths and surviving output,
+and a nested-`tests/` mapping/archetype test. Full suite: 77 files, 1,348 tests green.
+
+## 2.3.4 - 2026-09-10
+
+Silent-stall audit and compact-recovery release. Two themes: every block reports a
+user-visible reason, and compaction must actually buy back context.
+
+Security hooks can no longer be bypassed or silently disabled. `block-dangerous.sh` catches
+split recursive/force flags (`rm -r -f`, `rm --force -r`) and evaluates every delete target
+per shell segment, so one allowlisted word can no longer legitimise a sibling target
+(`rm -rf dist /`); a bare `/` stays classified unsafe, wrapped forms keep the whole-command
+fallback, and detections surface as structured `ask` decisions that never echo the raw
+command. `block-dangerous.sh`, `protect-files.sh`, and `auto-allow-bash.sh` fall back to
+Node when `jq` is absent (stock macOS), so a missing optional binary cannot disable a gate.
+`protect-files.sh` matches exact sensitive basenames and directory components instead of
+substrings — `.env.d.ts` and `app.envrc` are source files, not secrets — and emits a
+structured human-decision response on real blocks. `sensitive-data-guard.sh` only treats
+`-u/--user` as credentials on tools that authenticate with it, so `docker run --user
+1000:1000` no longer false-blocks while `curl -u user:pass` still does.
+
+Stops always carry a reason. `handoff-model-guard.sh` pairs its stderr refusal with a
+structured `systemMessage`; the completion gate reports a lost route state after real
+session activity instead of releasing silently; hard-cap grace and sensitive-data blocks
+already speak `systemMessage` from 2.3.3. `Phase: done …` with trailing status text now
+counts as finished (`^done\b`, not `^done$`) in `handoff-resume.sh`,
+`context-hardcap-gate.sh`, and `context-window-guard.sh`, so annotated done-phases stop
+being resumed forever. Multi-file resume intents survive compaction: identity is session +
+prompt key, because the router re-keys `requestKey` on every tool call and that churn is
+what made post-compact resume a silent no-op.
+
+The hard-cap grace budget is race-proof. Parallel subagents hitting the cap in one episode
+used to race a single read-modify-write counter and multiply the budget; each spent call
+now claims an exclusive-create sentinel file, so the sentinels present are the true count
+and one claim can never be counted twice (verified by an 8-process parallel test: exactly
+the configured grants, the next call blocked).
+
+omp payloads moved off argv. PostToolUse Bash payloads embed whole tool outputs and exceed
+macOS's ~256KB-per-argument limit, failing exec with E2BIG before any hook ran. The bridge
+now writes the payload to a temp file (`@path` marker, hourly sweep, inline fallback for
+read-only roots) and `hook-chain-runner.mjs` reads the marker; raw JSON never starts with
+`@`, so both forms stay unambiguous.
+
+Compact recovery, directed. Near-cap advisories now order the work: land the smallest
+finishable item end-to-end, defer the rest as one-line notes to disk, delegate broad
+reads/searches to subagents, then ask the user to compact. A new post-compact check fires
+once per compact boundary when the live context after the boundary is still ≥60% of the
+cap: stop re-reading old files (the fastest way to re-inflate a just-compacted session),
+delegate, or finish in a fresh session — UKit resume state carries the goal across with a
+near-empty window. The reinjected PROJECT CONTEXT block carries the same discipline.
+
+Also fixed: `ukit install|diff --with-codegraph` crashed before the flag was consumed;
+`route-task.mjs` helper commands use POSIX single-quote escaping instead of `JSON.stringify`
+(printed commands were open to `$(...)`/backtick expansion) and reject absolute outside-root
+targets instead of routing foreign-file context.
+
 ## 2.3.3 - 2026-09-10
 
 False-stop and long-context release. Four fixes that share one theme: UKit must run a prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/diff.js

@@ -15,7 +15,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
     return;
   }
 
-  const toolsArg = parseToolsArg(argv);
+  const toolsArg = parseToolsArg(argv.filter((arg) => arg !== '--with-codegraph'));
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const selectedAdapterItemIds = toSelectedAdapterItemIds(selectedOptionalTools);
   const withCodegraph = argv.includes('--with-codegraph');

package/src/cli/commands/install.js

@@ -197,7 +197,10 @@ export async function pruneDeselectedAdapters({
 }
 
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
-  const toolsArg = parseToolsArg(argv);
+  // parseToolsArg owns only --tools and throws on anything else, so hand it the argv with
+  // the flags consumed here (--with-codegraph) already removed — order-dependent parsing
+  // used to make the documented `ukit install --with-codegraph` fail 100% of the time.
+  const toolsArg = parseToolsArg(argv.filter((arg) => arg !== '--with-codegraph'));
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const withCodegraph = argv.includes('--with-codegraph');
 

package/src/core/memory/store.js

@@ -14,6 +14,15 @@ function defaultUserMemory() {
   };
 }
 
+async function readMemoryJson(filePath) {
+  try {
+    return await readJsonIfExists(filePath);
+  } catch (error) {
+    console.warn(`[UKit] Ignoring corrupt memory JSON file ${filePath}: ${error?.message ?? String(error)}`);
+    return null;
+  }
+}
+
 async function readDirectoryJsonItems(dirPath) {
   let entries = [];
   try {
@@ -29,7 +38,7 @@ async function readDirectoryJsonItems(dirPath) {
     }
 
     const fullPath = path.join(dirPath, entry.name);
-    const content = await readJsonIfExists(fullPath);
+    const content = await readMemoryJson(fullPath);
     if (content) {
       items.push({
         fileName: entry.name,
@@ -91,7 +100,7 @@ function createSearchableText(type, content) {
 
 export async function exportMemory(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const user = (await readJsonIfExists(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
+  const user = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projects = (await readDirectoryJsonItems(runtimePaths.projectsDir)).map((item) => item.content);
   const sessions = (await readDirectoryJsonItems(runtimePaths.sessionsDir)).map((item) => item.content);
 
@@ -100,7 +109,7 @@ export async function exportMemory(projectRoot) {
 
 export async function listMemoryItems(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const userMemory = (await readJsonIfExists(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
+  const userMemory = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projectMemories = await readDirectoryJsonItems(runtimePaths.projectsDir);
   const sessionMemories = await readDirectoryJsonItems(runtimePaths.sessionsDir);
 
@@ -188,7 +197,7 @@ function projectMemoryPath(runtimePaths, projectId) {
 
 async function readProjectMemoryForId(runtimePaths, projectId) {
   const filePath = projectMemoryPath(runtimePaths, projectId);
-  const existing = await readJsonIfExists(filePath);
+  const existing = await readMemoryJson(filePath);
   const memory = {
     id: projectId,
     conventions: [],
@@ -204,7 +213,7 @@ async function appendSessionArchive(runtimePaths, projectId, archivedSessions) {
   }
 
   const archivePath = path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.archive.json`);
-  const existing = (await readJsonIfExists(archivePath)) ?? { sessions: [] };
+  const existing = (await readMemoryJson(archivePath)) ?? { sessions: [] };
   const sessions = Array.isArray(existing.sessions) ? existing.sessions : [];
   await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions] });
 }

package/src/core/status.js

@@ -5,7 +5,7 @@ import { loadRuntimeConfig } from './runtimeConfig.js';
 import { summarizeOutputHistory } from './output/index.js';
 import { buildPromptCacheStats } from './token/index.js';
 import { countMemoryItems } from './memory/store.js';
-import { readCompactPressureState } from './compact/threshold.js';
+import { buildCompactPressureState } from './compact/threshold.js';
 import { detectProjectContext } from '../context/detectProjectContext.js';
 
 function formatPrimaryAgent(agentKey) {
@@ -122,6 +122,15 @@ function formatRecoveryLabel(count) {
   return ` / ${count} recover${count === 1 ? 'y' : 'ies'}`;
 }
 
+async function readStatusJson(filePath) {
+  try {
+    return await readJsonIfExists(filePath);
+  } catch (error) {
+    console.warn(`[UKit] Ignoring corrupt status JSON file ${filePath}: ${error?.message ?? String(error)}`);
+    return null;
+  }
+}
+
 export async function buildStatusReport(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   const runtimeExists = await pathExists(runtimePaths.runtimeRoot);
@@ -131,11 +140,14 @@ export async function buildStatusReport(projectRoot) {
 
   const projectContext = await detectProjectContext(projectRoot);
   const config = await loadRuntimeConfig(projectRoot);
-  const compactHistory = normalizeCompactEntries(await readJsonIfExists(runtimePaths.compactHistoryPath));
+  const compactHistory = normalizeCompactEntries(await readStatusJson(runtimePaths.compactHistoryPath));
   const compactSummary = buildCompactSummary(compactHistory);
-  const compactPressure = await readCompactPressureState(projectRoot, config);
-  const promptCacheStats = buildPromptCacheStats(await readJsonIfExists(runtimePaths.promptCachePath));
-  const outputCompressionStats = summarizeOutputHistory(await readJsonIfExists(runtimePaths.outputHistoryPath));
+  const compactPressure = buildCompactPressureState(
+    await readStatusJson(runtimePaths.compactPressurePath),
+    config,
+  );
+  const promptCacheStats = buildPromptCacheStats(await readStatusJson(runtimePaths.promptCachePath));
+  const outputCompressionStats = summarizeOutputHistory(await readStatusJson(runtimePaths.outputHistoryPath));
   const memoryCounts = await countMemoryItems(projectRoot);
   const adapters = await detectAdapterLabels(projectRoot, config.agent);
 

package/src/index/buildIndex.js

@@ -1197,7 +1197,20 @@ function areSourceFingerprintsEqual(previousFingerprint, nextFingerprint) {
 
 async function writeArtifact(rootDir, artifactName, payload) {
   const artifactPath = getArtifactPath(rootDir, artifactName);
-  await fs.writeFile(artifactPath, JSON.stringify(payload, null, 2));
+  const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  try {
+    await fs.writeFile(temporaryPath, JSON.stringify(payload, null, 2));
+    await fs.rename(temporaryPath, artifactPath);
+  } catch (error) {
+    try {
+      await fs.rm(temporaryPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+
+    throw error;
+  }
 }
 
 async function readArtifactIfExists(rootDir, artifactName) {

package/src/index/paths.js

@@ -37,6 +37,7 @@ export function isLikelyTestFilePath(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')

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

@@ -3,7 +3,22 @@
 # Optimized: fast-path grep to skip Node.js when rule already exists.
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+# jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
+# UKit's required Node runtime so safe commands still receive managed metadata.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.stdout.write(typeof payload?.tool_input?.command === "string" ? payload.tool_input.command : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$COMMAND" ]; then
   exit 0

package/templates/.claude/hooks/block-dangerous.sh

@@ -3,7 +3,22 @@
 # Matched on: Bash
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+# jq is not installed on stock macOS. Keep jq as the low-latency normal path, but use
+# UKit's required Node runtime as a fallback so its absence cannot silently disable the gate.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.stdout.write(typeof payload?.tool_input?.command === "string" ? payload.tool_input.command : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$COMMAND" ]; then
   exit 0
@@ -59,22 +74,80 @@ for pattern in "${DANGEROUS_PATTERNS[@]}"; do
   fi
 done
 
-# Handle rm commands: allow safe cleanup targets, block risky recursive force-deletes
-if echo "$SCAN_COMMAND" | grep -qE "(^|[;&|[:space:]])rm([[:space:]]|$)"; then
-  if echo "$SCAN_COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|--recursive\s+--force|--force\s+--recursive|--recursive\s+-f|-f\s+--recursive)"; then
-    SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
-    UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
+# Handle rm commands: allow safe cleanup targets only, defer everything else to a human.
+# Direct rm invocations are parsed per shell segment (`;`, `&`, `|` split) with per-target
+# allowlist evaluation: split flags (`rm -r -f`, `rm --force -r`) register, and one
+# allowlisted word can never legitimise a sibling target (`rm -rf dist /`). A whole-command
+# fallback still catches rm inside wrapped/quoted contexts (`bash -c "rm -r -f /x"`) and
+# flags placed after targets (`rm src -rf`), where segment parsing cannot see rm as a head.
+SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
+UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
+SAFE_ONE_TARGET_REGEX='^(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/.*)?$'
+UNSAFE_ONE_TARGET_REGEX='^(/.*|~|~/.*|\.\.|\.\./.*|\.)$'
+RM_WORD_REGEX=$'(^|[;&|[:space:]"\x27])rm([[:space:]"\x27]|$)'
 
-    # Check the allowlist first: `./dist` legitimately contains a leading "./" that would
-    # otherwise be mistaken for a bare current-directory target by UNSAFE_TARGET_REGEX below.
-    if echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+RM_VERDICT_UNSAFE=0
+RM_VERDICT_GENERIC=0
+RM_DIRECT_SEEN=0
+set -f
+while IFS= read -r segment; do
+  [ -n "$segment" ] || continue
+  seg_head=$(printf '%s' "$segment" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | xargs -I{} basename {} 2>/dev/null)
+  [ "$seg_head" = "rm" ] || continue
+  seg_flags=$(printf '%s' "$segment" | awk '{for(i=2;i<=NF;i++){if($i=="--")break;if($i ~ /^-/)printf "%s\n",$i;else break}}')
+  seg_has_r=0
+  seg_has_f=0
+  for flag in $seg_flags; do
+    case "$flag" in
+      --recursive) seg_has_r=1 ;;
+      --force) seg_has_f=1 ;;
+      --*) ;;
+      -*) case "$flag" in *[rR]*) seg_has_r=1 ;; esac
+          case "$flag" in *f*) seg_has_f=1 ;; esac ;;
+    esac
+  done
+  [ "$seg_has_r" -eq 1 ] && [ "$seg_has_f" -eq 1 ] || continue
+  RM_DIRECT_SEEN=1
+  seg_targets=$(printf '%s' "$segment" | awk '{saw=0;for(i=2;i<=NF;i++){if(!saw){if($i=="--"){saw=1;continue}if($i ~ /^-/)continue;saw=1;printf "%s\n",$i}else if($i !~ /^-/)printf "%s\n",$i}}')
+  seg_all_safe=1
+  seg_any_unsafe=0
+  for target in $seg_targets; do
+    # Strip ONE trailing slash so `dist/` matches the allowlist — but never shrink a
+    # bare `/` (or `~`) to an empty string, which would silently dodge the unsafe check.
+    if [ "${#target}" -gt 1 ]; then target="${target%/}"; fi
+    if printf '%s' "$target" | grep -qE "$UNSAFE_ONE_TARGET_REGEX"; then
+      seg_any_unsafe=1
+      seg_all_safe=0
+    elif printf '%s' "$target" | grep -qE "$SAFE_ONE_TARGET_REGEX"; then
       :
-    elif echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
-      emit_dangerous_decision "Unsafe delete target detected; recursive force-delete could cause irreversible damage. UKit defers this to a human decision."
     else
-      emit_dangerous_decision "Recursive force-delete outside safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules) is destructive. UKit defers this to a human decision."
+      seg_all_safe=0
     fi
+  done
+  if [ "$seg_any_unsafe" -eq 1 ]; then RM_VERDICT_UNSAFE=1
+  elif [ "$seg_all_safe" -eq 0 ]; then RM_VERDICT_GENERIC=1
+  fi
+done <<SEGMENTS
+$(printf '%s' "$SCAN_COMMAND" | tr ';&|' '\n\n\n')
+SEGMENTS
+set +f
+
+if [ "$RM_DIRECT_SEEN" -eq 0 ] && echo "$SCAN_COMMAND" | grep -qE "$RM_WORD_REGEX" \
+  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--recursive|(^|[[:space:]])-[a-zA-Z]*[rR]" \
+  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--force|(^|[[:space:]])-[a-zA-Z]*f"; then
+  # Unsafe wins over the allowlist here: a safe word elsewhere in the line must never
+  # legitimise an absolute/home/parent target we can also see.
+  if echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
+    RM_VERDICT_UNSAFE=1
+  elif ! echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+    RM_VERDICT_GENERIC=1
   fi
 fi
 
+if [ "$RM_VERDICT_UNSAFE" -eq 1 ]; then
+  emit_dangerous_decision "Unsafe delete target detected; recursive force-delete could cause irreversible damage. UKit defers this to a human decision."
+elif [ "$RM_VERDICT_GENERIC" -eq 1 ]; then
+  emit_dangerous_decision "Recursive force-delete outside safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules) is destructive. UKit defers this to a human decision."
+fi
+
 exit 0

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

@@ -75,7 +75,7 @@ function readRunCursor() {
   try {
     const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
     const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
-    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    if (!runPhase || /^done\b/i.test(runPhase)) return null;
     return {
       phase: runPhase,
       cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
@@ -122,11 +122,35 @@ function readRunCursor() {
   }
   const thresholds = mod.buildCompactThresholds(config);
 
+  // The grace budget must survive parallel subagents hitting the cap in the same episode.
+  // A read-modify-write of one JSON file under-counts (two processes both read used=3 and
+  // both write 4, silently multiplying the budget), so each spent call is claimed with an
+  // exclusive-create sentinel file (openSync 'wx'): the sentinels present ARE the number
+  // of grace calls spent, and one claim can never be counted twice.
   const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
+  const graceDir = path.dirname(gracePath);
+  const slotPath = (n) => path.join(graceDir, `hardcap-grace.json.${n}`);
+  const readSlots = () => {
+    try {
+      return fs.readdirSync(graceDir)
+        .map((name) => /^hardcap-grace\.json\.(\d+)$/.exec(name))
+        .filter(Boolean)
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    } catch {
+      return [];
+    }
+  };
+  const clearGrace = () => {
+    try { fs.rmSync(gracePath, { force: true }); } catch { /* advisory only */ }
+    for (const n of readSlots()) {
+      try { fs.rmSync(slotPath(n), { force: true }); } catch { /* advisory only */ }
+    }
+  };
 
   if (state.estimatedTotalTokens < thresholds.hardCapTokens) {
     // Back under the cap — the episode is over, so the next one starts with a full budget.
-    fs.rmSync(gracePath, { force: true });
+    clearGrace();
     process.exit(0);
     return;
   }
@@ -145,43 +169,87 @@ function readRunCursor() {
     const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
       ? config.compact.hardCapGraceCalls
       : 10;
-    const prior = readJsonSafe(gracePath, null);
+
+    let slots = readSlots();
+    let startedAtTokens = null;
+    for (const n of slots) {
+      const data = readJsonSafe(slotPath(n), null);
+      if (data && Number.isFinite(data.startedAtTokens)) {
+        startedAtTokens = Math.max(startedAtTokens ?? -Infinity, data.startedAtTokens);
+      }
+    }
     // Reset only when the estimate actually fell since grace started: that is the signal a
     // real compaction/shed happened. Advancing the cursor alone must NOT top the budget up,
     // otherwise a long run gets unlimited grace and the ceiling stops meaning anything.
-    const carried =
-      prior && Number.isFinite(prior.startedAtTokens) && state.estimatedTotalTokens >= prior.startedAtTokens
-        ? prior
-        : { startedAtTokens: state.estimatedTotalTokens, used: 0 };
+    if (startedAtTokens !== null && state.estimatedTotalTokens < startedAtTokens) {
+      clearGrace();
+      slots = [];
+      startedAtTokens = null;
+    }
+    const spent = slots.length > 0 ? slots[slots.length - 1] : 0;
+    if (startedAtTokens === null) startedAtTokens = state.estimatedTotalTokens;
 
-    if (carried.used < graceCalls) {
-      const used = carried.used + 1;
+    if (spent < graceCalls) {
+      // Claim the next slot atomically: EEXIST means a parallel worker already claimed it,
+      // step to the next. A filesystem error keeps the old fail-open behavior — losing the
+      // counter must never block a landing — at the cost of one extra granted call.
+      let used = 0;
+      let counterFailed = false;
       try {
-        fs.mkdirSync(path.dirname(gracePath), { recursive: true });
-        fs.writeFileSync(gracePath, JSON.stringify({ ...carried, used }));
-        if (ordinaryTask && ledgerMod && used === 1) {
-          await ledgerMod.writeResumeIntent(projectRoot, payload);
+        fs.mkdirSync(graceDir, { recursive: true });
+        for (let n = spent + 1; n <= graceCalls; n += 1) {
+          try {
+            const fd = fs.openSync(slotPath(n), 'wx');
+            fs.writeSync(fd, JSON.stringify({ startedAtTokens, used: n, ts: Date.now() }));
+            fs.closeSync(fd);
+            used = n;
+            break;
+          } catch (err) {
+            if (err?.code === 'EEXIST') continue;
+            throw err;
+          }
         }
       } catch {
-        // Losing the counter or advisory resume intent must not block the run.
+        counterFailed = true;
+      }
+      if (used === 0 && counterFailed) used = spent + 1;
+      if (used > 0 && used <= graceCalls) {
+        try {
+          fs.writeFileSync(gracePath, JSON.stringify({ startedAtTokens, used }));
+          if (ordinaryTask && ledgerMod && used === 1) {
+            await ledgerMod.writeResumeIntent(projectRoot, payload);
+          }
+        } catch {
+          // Losing the counter or advisory resume intent must not block the run.
+        }
+        const landing = run
+          ? `An unfinished handoff run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`
+          : 'An unfinished ordinary routed task is in flight, so this call is allowed instead of stranding it before compaction.';
+        process.stderr.write(
+          [
+            `CONTEXT OVER CAP — grace ${used}/${graceCalls} (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}).`,
+            landing,
+            run
+              ? 'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.'
+              : 'Spend the remaining grace on LANDING, not on new work: finish the current mutation or verification, then compact as soon as the host allows it.',
+            'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
+            'Tell the user in your reply that context is over the cap and they should run /compact as soon as this landing step is complete.',
+            'After compaction, the SessionStart resume hook replays the safe cursor and the task continues automatically.',
+          ].join('\n') + '\n',
+        );
+        // The stderr contract above only reaches the model — if the turn dies before the
+        // model relays it, the user sees nothing. Mirror the first grace call as a
+        // structured systemMessage so the /compact advice is user-visible regardless.
+        if (used === 1) {
+          process.stdout.write(`${JSON.stringify({
+            systemMessage: `UKit: context is over the hard cap (~${state.estimatedTotalTokens} tokens). A short landing window (${graceCalls} calls) is active — run /compact when it ends; the task resumes automatically after compaction.`,
+          })}\n`);
+        }
+        process.exit(0);
+        return;
       }
-      const landing = run
-        ? `An unfinished handoff run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`
-        : 'An unfinished ordinary routed task is in flight, so this call is allowed instead of stranding it before compaction.';
-      process.stderr.write(
-        [
-          `CONTEXT OVER CAP — grace ${used}/${graceCalls} (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}).`,
-          landing,
-          run
-            ? 'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.'
-            : 'Spend the remaining grace on LANDING, not on new work: finish the current mutation or verification, then compact as soon as the host allows it.',
-          'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
-          'Tell the user in your reply that context is over the cap and they should run /compact as soon as this landing step is complete.',
-          'After compaction, the SessionStart resume hook replays the safe cursor and the task continues automatically.',
-        ].join('\n') + '\n',
-      );
-      process.exit(0);
-      return;
+      // Every slot was claimed while we raced — the budget is genuinely spent; fall
+      // through to the hard block below.
     }
   }
 
@@ -197,6 +265,11 @@ function readRunCursor() {
     'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
   ];
   process.stderr.write(`${lines.join('\n')}\n`);
+  // stderr reaches the model, not reliably the user. Pair the hard block with a
+  // structured systemMessage so "why did it stop" always has a user-visible answer.
+  process.stdout.write(`${JSON.stringify({
+    systemMessage: `UKit blocked ${toolName}: context is over the hard cap (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}) and the landing window is spent. Run /compact now; after compaction the task continues automatically.`,
+  })}\n`);
   process.exit(2);
 })().catch((err) => {
   // A logic error here fails OPEN: this is a backstop on top of advisory nudges,

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

@@ -94,12 +94,14 @@ if (truncated) lines.shift(); // a tail read almost certainly split the first li
 // Everything before the last compact boundary is already summarised away and is NOT in
 // the live context. Counting it is what makes naive file-size estimates useless.
 let start = 0;
+let boundaryTs = null;
 for (let i = lines.length - 1; i >= 0; i -= 1) {
   if (!lines[i].includes('compact_boundary')) continue;
   try {
     const entry = JSON.parse(lines[i]);
     if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
       start = i + 1;
+      boundaryTs = Date.parse(entry.timestamp) || null;
       break;
     }
   } catch { /* not a usable boundary line */ }
@@ -200,6 +202,31 @@ if (swapDetected && persistedState.lastSwapModel !== currentModel) {
   }
 }
 
+// ── Post-compact shrink check ──
+// Compaction only helps if the live context AFTER the boundary is actually small. When the
+// prompts right after a fresh compact already measure >= 60% of the cap, the summary did
+// not shrink the session enough — and re-compacting the same session recovers very little.
+// The honest recovery moves are: stop re-inflating it with rereads, delegate broad work to
+// subagents (separate windows), or finish in a FRESH session (UKit resume state carries
+// the goal across). Fires once per compact boundary.
+const POST_COMPACT_RATIO = 0.6;
+const POST_COMPACT_WINDOW_MS = 10 * 60 * 1000;
+const boundaryAgeMs = boundaryTs !== null ? Date.now() - boundaryTs : null;
+const justCompacted = boundaryAgeMs !== null && boundaryAgeMs >= 0 && boundaryAgeMs < POST_COMPACT_WINDOW_MS;
+if (justCompacted && ratio >= POST_COMPACT_RATIO && persistedState.lastPostCompactBoundary !== String(boundaryTs)) {
+  persistedState.lastPostCompactBoundary = String(boundaryTs);
+  writeGuardState(persistedState);
+  process.stdout.write(
+    [
+      `UKIT POST-COMPACT CHECK — compaction ~${Math.max(1, Math.round(boundaryAgeMs / 60000))} min ago, but live context is still ~${estimatedTokens.toLocaleString()} tokens (${Math.round(ratio * 100)}% of the ${hardCap.toLocaleString()} cap).`,
+      'The compact did not shrink this session enough. Recover context now, in this order:',
+      '1) STOP re-reading old files, logs and tool outputs — durable state is in the PROJECT CONTEXT block or on disk. Rereads are what re-inflate a just-compacted session.',
+      '2) DELEGATE remaining broad work (searches, big reads, multi-file edits) to subagents: their tool output lives in their own windows; keep this context for decisions and short summaries only.',
+      '3) If substantial work still remains: land the current step, persist docs/STATUS.md, then ask the user to start a FRESH session — UKit resume state carries the goal forward with a near-empty window. Another /compact here recovers far less.',
+    ].join('\n') + '\n',
+  );
+}
+
 if (ratio < 0.8) process.exit(0);
 
 const pct = Math.round(ratio * 100);
@@ -226,7 +253,7 @@ function readRunCursor() {
   try {
     const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
     const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
-    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    if (!runPhase || /^done\b/i.test(runPhase)) return null;
     return {
       phase: runPhase,
       cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
@@ -261,9 +288,10 @@ if (withinCooldown) {
   writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
-  lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
-  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left, split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
-  lines_out.push('3) Otherwise, make the user\'s next action the FIRST sentence of your reply so it cannot be missed: "Context sắp đầy — gõ /compact ngay (run /compact now)", or wrap up and start a fresh session — work already committed/persisted to disk is not lost. Do not keep working silently until tools start being refused.');
+  lines_out.push('1) LAND ONE THING: pick the smallest in-flight item you can finish end-to-end in ≤3 tool calls (edit + verify), complete exactly that one, and report it done. Do not open anything new.');
+  lines_out.push('2) DEFER THE REST: write each remaining step as one line into docs/STATUS.md (update-status skill), or split what remains into bounded docs/AI_HANDOFF tasks — a fresh context then continues from disk without re-reading this thread.');
+  lines_out.push('3) DELEGATE anything broad that must still run (searches, big reads, multi-file edits) to subagents instead of doing it inline — their tool output stays in their own windows, not this one.');
+  lines_out.push('4) Then make the user\'s next action the FIRST sentence of your reply: "Context sắp đầy — gõ /compact ngay (run /compact now)". After /compact UKit auto-resumes from disk; if the compacted session is still large, ask for a fresh session instead. Do not keep working silently until tools start being refused.');
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
   }

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -39,6 +39,13 @@ const input = payload?.tool_input || {};
 
 function block(message) {
   process.stderr.write(`BLOCKED (handoff model-tier guard): ${message}\n`);
+  // stderr reaches the model, not reliably the user. Pair the refusal with a structured
+  // systemMessage (first line only — the full problem list stays in stderr) so a
+  // handoff-contract block never looks like a silent stall in the UI.
+  const firstLine = String(message).split('\n').find((l) => l.trim()) || 'model-tier contract violated';
+  process.stdout.write(`${JSON.stringify({
+    systemMessage: `UKit handoff model-tier guard refused this action: ${firstLine.trim()}`,
+  })}\n`);
   process.exit(2);
 }
 

package/templates/.claude/hooks/handoff-resume.sh

@@ -79,7 +79,7 @@ async function emitOrdinaryResume() {
 
   const phase = field('Phase');
   // `done` means the last cycle finished cleanly. Anything else means a step was in flight.
-  if (!phase || /^done$/i.test(phase)) {
+  if (!phase || /^done\b/i.test(phase)) {
     await emitOrdinaryResume();
     process.exit(0);
   }

package/templates/.claude/hooks/protect-files.sh

@@ -3,7 +3,22 @@
 # Matched on: Edit|Write
 
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+# jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
+# UKit's required Node runtime so a missing optional binary cannot disable this gate.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+  FILE_PATH=$(printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.stdout.write(typeof payload?.tool_input?.file_path === "string" ? payload.tool_input.file_path : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$FILE_PATH" ]; then
   exit 0
@@ -16,23 +31,32 @@ if [[ "$BASENAME" == ".env.example" ]]; then
   exit 0
 fi
 
-PROTECTED_PATTERNS=(
-  ".env"
-  ".env.local"
-  ".env.production"
-  "package-lock.json"
-  "yarn.lock"
-  ".git/"
-  "node_modules/"
-  ".claude/settings.local.json"
-  ".ukit/storage/security/"
-)
+# Match exact sensitive filenames and directory components, never arbitrary substrings:
+# `.env.d.ts` and `app.envrc` are source files, not secrets. The old `*".env"*`
+# check blocked both, which could appear as a mysterious stopped edit.
+PATH_SLASHED="/${FILE_PATH#/}"
+PROTECTED_MATCH=""
+case "$BASENAME" in
+  .env|.env.local|.env.production|package-lock.json|yarn.lock)
+    PROTECTED_MATCH="$BASENAME"
+    ;;
+esac
+if [ -z "$PROTECTED_MATCH" ]; then
+  case "$PATH_SLASHED" in
+    */.git/*) PROTECTED_MATCH=".git/" ;;
+    */node_modules/*) PROTECTED_MATCH="node_modules/" ;;
+    */.claude/settings.local.json) PROTECTED_MATCH=".claude/settings.local.json" ;;
+    */.ukit/storage/security/*) PROTECTED_MATCH=".ukit/storage/security/" ;;
+  esac
+fi
 
-for pattern in "${PROTECTED_PATTERNS[@]}"; do
-  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
-    echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$pattern'. Ask the user to modify this file manually." >&2
-    exit 2
-  fi
-done
+if [ -n "$PROTECTED_MATCH" ]; then
+  # A stderr-only refusal can look like a silent stall when the host does not render
+  # hook stderr. Do not expose the path/pattern on stdout: the generic explanation is
+  # enough for the user and avoids leaking a potentially sensitive filename.
+  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually."}}'
+  echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
+  exit 2
+fi
 
 exit 0

package/templates/.claude/hooks/sensitive-data-guard.sh

@@ -163,8 +163,18 @@ function scanBashShapes(command) {
       }
     }
 
-    if (/(^|\s)(-u|--user)\s+["']?[^\s"':]+:[^\s"']+/.test(segment)) {
-      found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+    // `-u/--user user:pass` is only credentials on tools that authenticate with it.
+    // The same flag shape on docker/runuser/chown (`--user 1000:1000`, a uid:gid pair)
+    // is NOT a secret — matching it anyway false-positives every containerised test run.
+    const headBase = head.replace(/^.*\//, '');
+    const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
+    const inlineUser = /(^|\s)(-u|--user)\s+["']?([^\s"':]+):([^\s"']+)/.exec(segment);
+    if (inlineUser && CRED_USER_TOOLS.has(headBase)) {
+      // Even on credential tools, a purely numeric pair is a uid:gid, not a password.
+      const numericIds = /^\d+$/.test(inlineUser[3]) && /^\d+$/.test(inlineUser[4]);
+      if (!numericIds) {
+        found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+      }
     }
     if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
       found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
@@ -263,6 +273,12 @@ const lines = [
   'Never repeat or guess the detected value in your reply. Ask the user instead.',
 ];
 process.stderr.write(`${lines.join('\n')}\n`);
+// stderr reaches the model; the user needs a stop reason they can actually see. Emit a
+// structured systemMessage (redacted — labels only, never the matched value) so a
+// sensitive-data block never looks like a silent stall in the UI.
+process.stdout.write(`${JSON.stringify({
+  systemMessage: `UKit blocked this call: ${findings.length} potential secret(s) detected (${findings.map((f) => f.label).slice(0, 3).join('; ')}${findings.length > 3 ? '; …' : ''}). Redact the value, allowlist its sha256, or ask the user to decide.`,
+})}\n`);
 process.exit(2);
 NODE
 

package/templates/.claude/hooks/skill-router.sh

@@ -2580,6 +2580,34 @@ const { pathToFileURL } = require('url');
     routingContext,
     previousContextFingerprint: previousContext?.fingerprint || null,
   });
+  // Persist the completion contract BEFORE any cache import or indexed-context resolution.
+  // Those later steps can take longer than the host's PreToolUse hook timeout. Previously a
+  // timeout killed this process before its only state write, and completion-gate.sh then had
+  // no route to evaluate — so it released Stop with no message. This provisional state has
+  // the full execution/evidence contract; the final richer state below atomically replaces it.
+  const provisionalRouteSummary = buildRouteSummary({
+    activeSkills: selected,
+    routingContext,
+  });
+  provisionalRouteSummary.continuationState = advanceContinuationState(
+    provisionalRouteSummary.continuationState,
+    previous?.routeSummary?.continuationState || null,
+  );
+  applyRescueBiasToRouteSummary(provisionalRouteSummary);
+  const provisionalState = {
+    ...(sessionId ? { sessionId } : {}),
+    requestKey,
+    ts: now,
+    source: 'skill-router-provisional',
+    activeSkills: compactActiveSkills(selected),
+    routingContext: compactRoutingContext(routingContext),
+    ...(previousContext ? { previousContext: compactPreviousContext(previousContext) } : {}),
+    routeSummary: compactRouteSummary(provisionalRouteSummary),
+  };
+  provisionalState.fingerprint = buildRouteStateFingerprint(provisionalState);
+  ensureDir(statePath);
+  fs.writeFileSync(statePath, JSON.stringify(provisionalState));
+
   let cacheUtils = null;
   if (fs.existsSync(cacheUtilsPath)) {
     try {

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -2028,7 +2028,21 @@ function areBugIndexSnapshotsEqual(previousSnapshot, nextSnapshot) {
 }
 
 async function writeArtifact(rootDir, artifactName, payload) {
-  await fs.writeFile(getArtifactPath(rootDir, artifactName), JSON.stringify(payload, null, 2));
+  const artifactPath = getArtifactPath(rootDir, artifactName);
+  const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  try {
+    await fs.writeFile(temporaryPath, JSON.stringify(payload, null, 2));
+    await fs.rename(temporaryPath, artifactPath);
+  } catch (error) {
+    try {
+      await fs.rm(temporaryPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+
+    throw error;
+  }
 }
 
 async function readArtifact(rootDir, artifactName) {
@@ -2557,6 +2571,7 @@ function isLikelyTestFilePath(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')
@@ -2988,6 +3003,7 @@ function isLikelyTestFile(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')

package/templates/.claude/ukit/index/route-task.mjs

@@ -2455,10 +2455,18 @@ function inferTaskType({ promptText, commandText, selectedIds, targetFile = null
   return inferred;
 }
 
+// Must mirror src/index/taskRouting.js: the printed helper command is meant to be pasted
+// into a shell, so arguments need POSIX single-quote escaping — JSON.stringify's double
+// quotes leave $(...), backticks, and $VAR open to shell expansion.
+function shellEscape(str) {
+  if (typeof str !== 'string') return '';
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
 function buildHelperCommand({ commandNamespace = '.claude', scriptName, intent = '', targetFile = null, taskType = null }) {
   const parts = ['node', `${commandNamespace}/ukit/index/${scriptName}`];
-  if (intent) parts.push(JSON.stringify(intent));
-  if (targetFile) parts.push('--target', JSON.stringify(targetFile));
+  if (intent) parts.push(shellEscape(intent));
+  if (targetFile) parts.push('--target', shellEscape(targetFile));
   if (taskType) parts.push('--type', taskType);
   return parts.join(' ');
 }
@@ -2666,7 +2674,9 @@ function normalizeRelativeFile(rootDir, rawFilePath) {
     if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
       return relative.replaceAll('\\', '/');
     }
-    return trimmed.replaceAll('\\', '/');
+    // Absolute targets outside the project root are not routable repo files (src twin
+    // returns null here) — emitting them pulled outlines of foreign files into context.
+    return null;
   }
 
   return trimmed.replace(/^\.\/+/, '').replaceAll('\\', '/');

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -154,10 +154,15 @@ export async function readResumeIntent(projectRoot, payload = {}, { consume = fa
   const state = await readRouteState(projectRoot, payload);
   const ledger = await readExecutionLedger(projectRoot, payload);
   const promptKey = explicitPromptKey(state || {});
+  // Identity is session + promptKey, NOT requestKey. The router re-keys requestKey on
+  // every tool call (commandText/targetFile are part of the key), so requiring requestKey
+  // equality invalidated the intent after the FIRST tool call between the gate block and
+  // the compaction — the post-compact session then had no continuation instruction and
+  // sat idle silently. hasUnfinishedCompletion still re-validates against the CURRENT
+  // ledger evidence, so a request that finished meanwhile consumes nothing and never
+  // resumes; a genuinely different prompt produces a different promptKey and stays dead.
   if (!state || !ledger || ledger.sessionId !== sessionId
     || ledger.sessionKey !== safeSegment(sessionId)
-    || state.requestKey !== intent.requestKey
-    || ledger.requestKey !== intent.requestKey
     || promptKey !== intent.promptKey
     || ledger.promptKey !== intent.promptKey
     || !hasUnfinishedCompletion(state, ledger)) {
@@ -610,6 +615,20 @@ async function main() {
     const ledger = await readExecutionLedger(projectRoot, payload) || {};
     const result = evaluateCompletion({ state, ledger });
 
+    // A session ledger with activity proves this session was routed and accumulating
+    // evidence. If the route state is now missing or unreadable (router crashed/timed out
+    // before persisting it, or the session stamp was lost), the gate cannot evaluate
+    // completion — and ending silently there is indistinguishable from a mid-run stall.
+    // Surface the loss so the user sees WHY the run released. Sessions that were never
+    // routed (no ledger activity at all) stay silent: there is nothing to report.
+    if (!state && (ledger.sourceSucceeded || ledger.writeAttempted
+      || ledger.verificationAttempted || (ledger.receipts || []).length > 0)) {
+      process.stdout.write(`${JSON.stringify({
+        systemMessage: 'UKit completion gate: route state for this session was lost before the stop was evaluated (router did not persist it), so unfinished work could not be verified. Send the task again in a new message to re-route and finish it.',
+      })}\n`);
+      return;
+    }
+
     // Claude Code invokes Stop again after a Stop hook blocks the first stop. Re-blocking
     // that recovery turn creates a self-sustaining loop, so let it end normally instead.
     // If work still lacks evidence, surface the recovery reason to the user rather than

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -106,7 +106,18 @@ function run(payloadText, scriptPaths) {
 }
 
 try {
-  const [, , payloadText = '{}', ...scriptPaths] = process.argv;
+  const [, , payloadArg = '{}', ...scriptPaths] = process.argv;
+  // The bridge passes the payload as a temp file (`@path`) when it can: argv is capped
+  // (~256KB per arg on macOS) and PostToolUse Bash payloads embed whole tool outputs.
+  // A leading '@' cannot occur in raw JSON, so the two forms are unambiguous.
+  let payloadText = payloadArg;
+  if (payloadArg.startsWith('@')) {
+    try {
+      payloadText = fs.readFileSync(payloadArg.slice(1), 'utf8');
+    } catch {
+      payloadText = '{}';
+    }
+  }
   process.stdout.write(JSON.stringify(run(payloadText, scriptPaths)));
 } catch (error) {
   process.stdout.write(JSON.stringify({

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -58,6 +58,10 @@ async function main() {
     ...await buildRecentOutputLines(projectRoot, config),
     ...await buildResolverHintLines(projectRoot, state),
     ...await buildDuraOneHintLines(projectRoot),
+    // Post-compact discipline: the host summary keeps whatever it kept — the fastest way to
+    // re-inflate a just-compacted session is re-reading old files/logs to "recover" detail
+    // that is already on disk. Say it once, right where the fresh context starts.
+    '- Post-compact discipline: do NOT re-read old files/logs/tool outputs to rebuild context — durable state is on disk and in this block. Delegate broad reads/searches to subagents (separate windows), keep replies short, and let the main window rebuild headroom before any wide investigation.',
     '- If Claude hooks block broad verification, follow the routed targeted order or ask for explicit full-suite confirmation.',
   ].filter(Boolean);
 

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -248,6 +248,39 @@ function resolveNodeExecutable() {
   return cachedNodeExecutable;
 }
 
+// argv is bounded: macOS allows ~256KB per argument (E2BIG), and PostToolUse Bash payloads
+// embed the whole tool output — routinely past that limit — so the exec fails before ANY
+// hook runs and the chain verdict is lost. Pass the payload through a temp file instead
+// (runner reads `@path` markers); inline argv stays as the fallback for read-only project
+// roots, and remains unambiguous because raw JSON never starts with '@'.
+function sweepStalePayloadFiles(dir) {
+  try {
+    const cutoff = Date.now() - 60 * 60 * 1000;
+    for (const name of fs.readdirSync(dir)) {
+      const filePath = path.join(dir, name);
+      try {
+        if (fs.statSync(filePath).mtimeMs < cutoff) fs.rmSync(filePath, { force: true });
+      } catch { /* raced away — fine */ }
+    }
+  } catch { /* sweeping is best effort */ }
+}
+
+function writePayloadFile(projectRoot, payload) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-payloads');
+    fs.mkdirSync(dir, { recursive: true });
+    sweepStalePayloadFiles(dir);
+    const filePath = path.join(
+      dir,
+      `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}.json`,
+    );
+    fs.writeFileSync(filePath, JSON.stringify(payload), 'utf8');
+    return filePath;
+  } catch {
+    return null;
+  }
+}
+
 export async function runScriptChain(
   pi,
   scripts,
@@ -264,15 +297,21 @@ export async function runScriptChain(
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
   const nodeExecutable = resolveNodeExecutable();
   const startedAt = Date.now();
+  const payloadFile = writePayloadFile(projectRoot, payload);
+  const payloadArg = payloadFile ? `@${payloadFile}` : JSON.stringify(payload);
   let execResult;
   try {
     execResult = await pi.exec(
       nodeExecutable,
-      [runnerPath, JSON.stringify(payload), ...scriptPaths],
+      [runnerPath, payloadArg, ...scriptPaths],
       { cwd: projectRoot, timeout: chainExecTimeoutMs(scripts.length) },
     );
   } catch (error) {
     execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
+  } finally {
+    if (payloadFile) {
+      try { fs.rmSync(payloadFile, { force: true }); } catch { /* best effort cleanup */ }
+    }
   }
   const elapsedMs = Date.now() - startedAt;