@ngockhoale/ukit 2.3.8 → 2.3.10

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.10 - 2026-09-11
+
+Freeze-sweep waves 7-10 (post-2.3.9): twelve verified mid-run-freeze defects fixed, each locked
+by a regression reproducing the failure first. All affected template/live mirrors are byte-synced.
+
+**P1 — continuation budget reset on every route re-key.** The router re-keys `requestKey` per
+tool call (the target file is part of the key), but the Stop-gate continuation budget was keyed
+on `requestKey` — the count reset to 0 on every re-key, the cap was unreachable, and omp looped
+forever (no `stop_hook_active` valve). Budget identity is now the logical prompt hash
+(`promptKey`) everywhere, and omp gained `stop_hook_active` parity via `noteStopProgress`.
+
+**P1 — parallel execution receipts crashed and raced.** Same-process concurrent receipt writers
+shared one temp path and crashed with ENOENT mid-hook; unlocked read-modify-write also dropped
+receipts, and a missing/foreign route state could rebuild a session ledger from blank, erasing
+banked evidence. Temp paths are unique, the whole receipt write runs under `withFileLock`, and
+a missing route no longer blanks the ledger.
+
+**P1 — ledger lock waits exceeded the hook child budget.** `withFileLock` waited up to 5s but
+the hook chain kills children at 4s, so a contended lock got the recording hook killed and omp's
+fail-closed Edit|Write chain then blocked the edit. Ledger lock waits now cap at 2.5s and fail
+open — a lost receipt beats a killed hook.
+
+**P1 — vibecode had no exit when verification kept failing identically.** Two adjacent identical
+failed verifications (no edit between) now mint a visible `verification-loop` blocker; vibecode
+additionally escapes after the same command fails 4× across edits.
+
+**P1 — clean map-impact Stop loop.** A completed analysis-only `map-impact` route still demanded
+write + verification evidence. A narrow visible release valve permits a completed impact read
+with no mutation attempt and no failed verification; incomplete analysis and partial edits stay
+gated.
+
+**P1 — omp hook child timeouts falsely blocked edits.** A 4s-killed `protect-files` gate was
+treated as its fail-closed verdict, freezing all edits on a slow machine. Timeouts now fail open
+as infrastructure failures with a visible warning; `block-dangerous.sh` stays fail-closed. An
+unknown mutation-shaped omp tool now normalizes to `Edit` and runs the normal safety chain
+instead of emitting an impossible "add host mapping" block.
+
+**P1 — hard-cap grace slots crossed session boundaries.** Global grace slots let one session
+spend or reset another session's landing allowance, stranding it mid-edit. Slots and advisory
+state are now session-keyed.
+
+**P2 — transcript fallback rescanned up to 4MB per mutation.** A persisted, session-bound
+2-second boundary-probe cache coalesces mutation bursts to one scan; `skill-router.sh` also
+skips its redundant prompt-only Node spawn on tool payloads.
+
+**P1 — lock stale-reclaim could steal a live owner.** The shared runtime lock used mtime-only
+reclaim: a slow-but-alive holder was deleted after 10s, then deleted its successor's lock in
+`finally` — lost receipts re-triggered completion debt. All lock implementations (runtime
+mirror, verification guard, auto-allow, auto-prune, compact-pressure reset) now stamp
+PID + random owner tokens, reclaim only provably-dead owners, and release only their own token.
+
+**P3 — stale verification-guard enforcement env var froze runs.** An inherited
+`UKIT_VERIFICATION_GUARD_ENFORCE=1` turned an advisory test-order recommendation into an
+exit-2 block. The guard is now exclusively advisory; real safety gates keep enforcement.
+
+Also in wave 7: piped/redirected verification (`yarn test 2>&1 | tail -6`) counts as targeted,
+and delivery-only requests ("push this to git") route `informational` with no fabricated
+mutation debt in all three routing copies.
+
+Full suite: 81 files, 1,439 tests green (plus wave 9-10 focused regressions). No npm tag
+policy change; artifact unpacked ceiling raised once to 5,785,000 with dated rationale.
+
+## 2.3.9 - 2026-09-10
+
+Freeze-sweep wave 5: fixes for completion-gate loops, worker-agent dead ends, and malformed
+context-cap configuration that could otherwise halt all mutation progress.
+
+**P1 — clean `find-cause` audits were forced into a Stop-hook loop.** A recommend-only
+investigation that found no actionable bug still required write and verification evidence, so
+the completion gate blocked the honest outcome and demanded a fabricated edit. The execution
+ledger now permits that narrow clean-audit outcome while retaining normal recovery blocks after
+a failed verification or incomplete mutation.
+
+**P1 — routed workers could wait for a user they cannot contact.** The Claude Code and omp
+`bug-debugger` / `feature-implementer` agents instructed workers to “ask the user” on unclear
+or non-reproducible work. They now perform one bounded next diagnostic step and return a
+structured `STATUS: BLOCKED` report with the exact missing artifact or decision to the parent
+agent, which owns user communication.
+
+**P1 — malformed context-cap configuration could brick mutations.** Invalid
+`compact.hardCapTokens` could collapse the cap to one token, invalid
+`hardCapGraceCalls` could eliminate the landing window, and wrong-shaped present
+`hardCapBlock` values could unexpectedly leave the hard gate enabled. The shared source/runtime
+threshold logic and Claude hook now accept only positive integer budgets, while malformed
+non-boolean `hardCapBlock` values fail open; the documented absent-key default remains enabled.
+The context-window advisory uses the same hard-cap validation. Regression coverage includes
+negative/zero/fraction/string/boolean/null budgets and malformed toggle values.
+
+Full suite: 81 files, 1,396 tests green.
+
 ## 2.3.8 - 2026-09-10
 
 Freeze-sweep wave 4: every fix in this release targets the "agent silently stops working"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.8",
+  "version": "2.3.10",
   "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/core/compact/threshold.js

@@ -35,6 +35,15 @@ function finiteNumber(value, fallback = 0) {
   return Number.isFinite(number) ? number : fallback;
 }
 
+// A malformed hard cap must fail back to a safe ceiling, never collapse to one token and
+// brick every Edit/Write/Bash call. Unlike token estimates, configuration is an operator
+// contract: accept only whole positive token counts.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
 function uniqueStrings(values) {
   const seen = new Set();
   const unique = [];
@@ -434,11 +443,15 @@ export function buildCompactThresholds(config = {}) {
   );
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
+  // Keep the source mirror's config contract aligned with the installed runtime: malformed
+  // caps fall back to a safe ceiling rather than turning every mutation into an over-cap call.
+  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, loadShippedCompactBudget().hardCapTokens);
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
+    hardCapTokens,
   };
 }
 

package/src/core/fileOps.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -142,17 +143,46 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user — still alive.
+    return error?.code === 'EPERM';
+  }
+}
+
+async function readLockOwner(lockPath) {
+  try {
+    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
+    const pid = Number(raw?.pid);
+    return Number.isInteger(pid) && pid > 0
+      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Same-pid holders are parallel async flows whose liveness a pid probe cannot prove.
+const inProcessLockHolders = new Map();
+
 /**
  * Serialize read-modify-write mutations of a shared state file — across processes
  * (hook invocations run as separate node processes) and across concurrent async
  * flows in one process (parallel subagents). The lock is a directory created next
  * to the target file: `mkdir` is atomic, so exactly one caller can create it.
- * A crashed holder is reclaimed once the directory's mtime exceeds staleMs.
+ * Ownership is recorded in an `owner` file inside the lock dir: stale reclaim first
+ * proves the recorded holder is gone (dead pid, or no in-process holder for our own
+ * pid — no owner file keeps legacy mtime-only recovery). Release only removes a dir
+ * this acquisition still owns, so a reclaimed-then-reacquired lock is never deleted
+ * out from under its successor.
  * Liveness wins over strictness: if the lock cannot be acquired within maxWaitMs
  * the callback runs anyway (the pre-lock behaviour) — these state files are
  * advisory caches, and losing an update beats freezing a hook mid-flight.
- * Holders must keep their critical section far below staleMs; nothing refreshes
- * the lock mtime, so a section that somehow runs longer can have its lock stolen.
+ * Protocol-compatible with the runtime token-utils.mjs lock (same `<file>.lock`
+ * path and owner-file format), so CLI and hook processes serialize against each other.
  * @param {string} filePath - state file the mutation targets (lock lives beside it)
  * @param {() => Promise<*>} fn - critical section; its result is returned
  * @returns {Promise<*>} whatever fn resolves with
@@ -160,24 +190,44 @@ function sleep(ms) {
 export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxWaitMs = LOCK_MAX_WAIT_MS } = {}) {
   const lockPath = `${filePath}.lock`;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
   let locked = false;
+  let ownerStamped = false;
 
   while (!locked) {
     try {
       await ensureDir(path.dirname(lockPath));
       await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
       locked = true;
+      inProcessLockHolders.set(lockPath, ownerToken);
+      try {
+        await fs.writeFile(
+          path.join(lockPath, 'owner'),
+          `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
+          'utf8',
+        );
+        ownerStamped = true;
+      } catch {
+        ownerStamped = false; // unverifiable release skips removal; stale reclaim cleans up
+      }
       break;
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error;
     }
 
-    // Someone holds the lock. Reclaim it when it looks abandoned; otherwise back off.
+    // Someone holds the lock. Reclaim it only when the holder is provably gone.
     try {
       const stat = await fs.stat(lockPath);
       if (Date.now() - stat.mtimeMs > staleMs) {
-        await fs.rm(lockPath, { recursive: true, force: true });
-        continue; // the slot is free now — retry immediately
+        const owner = await readLockOwner(lockPath);
+        const liveInProcess = inProcessLockHolders.has(lockPath);
+        const reclaimable = !owner || owner.pid === process.pid
+          ? !liveInProcess
+          : !isPidAlive(owner.pid);
+        if (reclaimable) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+          continue; // the slot is free now — retry immediately
+        }
       }
     } catch {
       continue; // lock vanished between mkdir and stat — retry immediately
@@ -192,7 +242,11 @@ export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxW
   } finally {
     if (locked) {
       try {
-        await fs.rm(lockPath, { recursive: true, force: true });
+        const current = ownerStamped ? await readLockOwner(lockPath) : null;
+        if (current && current.token === ownerToken) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+        }
+        if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
       } catch {
         // best-effort release; a stale lock is reclaimed by the next waiter
       }

package/src/index/taskRouting.js

@@ -78,6 +78,7 @@ export async function deriveTaskRoute({
     intentMode,
     executionScores,
     executionCandidates,
+    signalText: buildRouteSignalText(normalizedPrompt, normalizedCommand),
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
   const degradedWarnings = [];
@@ -412,8 +413,10 @@ function deriveExecutionMode({
   intentMode = null,
   executionScores = {},
   executionCandidates = null,
+  signalText = '',
 } = {}) {
   const raw = `${promptText ?? ''}\n${commandText ?? ''}`.toLowerCase();
+  const signalRaw = `${raw}\n${String(signalText || '').toLowerCase()}`;
   const scores = executionScores;
   const candidates = executionCandidates ?? buildExecutionModeCandidates({
     promptText,
@@ -423,14 +426,44 @@ function deriveExecutionMode({
     executionScores,
   });
   const explicitReviewLead = /\b(review this|audit this|review\b.*\brelease readiness|verify\b.*\brelease readiness)\b/.test(raw);
+  const releaseVerificationContinuation = /\b(?:pending\s+diff[- ]review|self-install|verify\s+(?:consistency|release)|release\s+(?:verification|readiness))\b/.test(raw)
+    && /\b(?:release|tag|publish|push|report)\b/.test(raw);
   const strongImpactLead = scores.sharedRisk
     && (scores.impactSignal || /\b(check all affected|map all affected|across all affected)\b/.test(raw));
   const boundedLocalBuildCandidate = scores.buildSignal && scores.boundedEditSignal && scores.explicitTarget && !scores.sharedRisk;
+  // A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+  // repository mutation the ledger could ever receipt. With no edit/review/debug/
+  // build signal present, routing it to an investigation lane fabricates write debt
+  // and the completion gate then demands an edit that cannot exist. Delivery-only
+  // requests carry no completion contract instead.
+  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+  const deliveryOnlySignal = deliveryWordSignal
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
 
-  if ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal) {
+  if (
+    releaseVerificationContinuation
+    || ((intentMode === 'review-specific' || explicitReviewLead) && !scores.implementSignal)
+  ) {
     return 'review-release';
   }
 
+  if (deliveryOnlySignal) {
+    return 'informational';
+  }
+
   if (strongImpactLead || (scores.blastRadius >= 3 && (scores.ambiguity >= 2 || scores.investigationNeed >= 2))) {
     return 'map-impact';
   }
@@ -530,7 +563,7 @@ function buildExecutionModeCandidates({
     ),
     'map-impact': (
       (scores.sharedRisk ? 7 : 0)
-      + (scores.impactSignal ? 5 : 0)
+      + (scores.impactSignal ? 5 : -5)
       + (scores.ambiguity * 2)
       + scores.investigationNeed
     ),

package/templates/.claude/agents/bug-debugger.md

@@ -18,7 +18,7 @@ Systematic debugging — understand before fixing.
 
 - Run the failing command/action.
 - Capture exact error message and stack trace.
-- If not reproducible → document conditions and ask user.
+- If not reproducible → document conditions, run the next most-discriminating bounded repro, then report any exact missing user-only artifact/permission to the parent agent. Never wait for or ask a user directly — you are a worker.
 
 ### 2. Trace Root Cause
 
@@ -83,4 +83,4 @@ Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`;
   - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
   - read `docs/WORKLOG.md` only recent relevant entries
 - Keep fix scope minimal — no drive-by refactors.
-- If root cause is unclear after 5 minutes of tracing → ask user for more context.
+- If root cause is unclear after 5 minutes of tracing → try one bounded alternative hypothesis/repro, then report precise evidence plus the smallest needed missing context to the parent agent. Never wait for or ask a user directly — the parent owns user communication.

package/templates/.claude/agents/feature-implementer.md

@@ -12,7 +12,9 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, default to Daily/ad-hoc mode unless the task path or prompt
+explicitly selects Handoff. Do not ask a user — you are a worker; report the ambiguity and
+reasoning to the parent agent so it can decide whether to re-route.
 
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
@@ -33,7 +35,7 @@ and even then, report it, don't ask about it.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
+- Daily mode: if confidence is low or risk is high, inspect the next bounded source/context signal and hand back a concise `STATUS: BLOCKED` report with the exact missing decision or artifact if confidence remains low. Do not ask a user directly. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
@@ -44,7 +46,7 @@ and even then, report it, don't ask about it.
 
 - Write the test(s) from §2 / from task Test Plan.
 - Run them: must FAIL for the expected reason. Capture output.
-- If test passes immediately → test is wrong or behavior already exists. Fix the test or stop and report.
+- If test passes immediately → test is wrong or behavior already exists. Fix the test; if the intended behavior cannot be inferred, hand back `STATUS: BLOCKED` with the observed behavior and the smallest decision the parent must resolve. Never silently stop.
 - **Daily mode**: skip this step unless touched code already has tests (then follow original rule).
 
 

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

@@ -78,6 +78,7 @@ MAX_RULES="${CLAUDE_AUTO_ALLOW_MAX_RULES:-150}"
 # 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 crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
@@ -115,24 +116,57 @@ function appendAudit(event, payload) {
   fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function readLockOwner(lockPath) {
+  const owner = readJson(path.join(lockPath, "owner"), null);
+  return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
+    ? owner
+    : null;
+}
+
 async function withLock(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       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 {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -143,9 +177,12 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }

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

@@ -14,6 +14,7 @@ fi
 NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 node -e '
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
@@ -55,25 +56,58 @@ function appendAudit(event, payload) {
 // 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.
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function readLockOwner(lockPath) {
+  const owner = readJson(path.join(lockPath, "owner"), null);
+  return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
+    ? owner
+    : null;
+}
+
 async function withLock(lockPath, fn) {
   const staleMs = 10000;
   const maxWaitMs = 5000;
   const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
   let held = false;
   while (!held) {
     try {
       fs.mkdirSync(path.dirname(lockPath), { recursive: true });
       fs.mkdirSync(lockPath);
+      try {
+        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+          pid: process.pid,
+          token: ownerToken,
+          ts: Date.now(),
+        }));
+      } catch (error) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+        throw error;
+      }
       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 {}
+          const owner = readLockOwner(lockPath);
+          if (!owner || !isPidAlive(owner.pid)) {
+            try {
+              fs.rmSync(lockPath, { recursive: true, force: true });
+              continue;
+            } catch {}
+          }
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
@@ -84,9 +118,12 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      try {
-        fs.rmdirSync(lockPath);
-      } catch {}
+      const owner = readLockOwner(lockPath);
+      if (owner?.token === ownerToken) {
+        try {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
     }
   }
 }

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

@@ -96,7 +96,12 @@ function readRunCursor() {
       ? payload.session_id.trim()
       : undefined,
   };
-  if (config?.compact?.hardCapBlock === false) {
+  // 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;
   }
@@ -123,7 +128,9 @@ function readRunCursor() {
   let state = mod.buildCompactPressureState(rawState, sessionConfig);
   try {
     const synced = await mod.syncCompactPressureStateWithTranscript(state, sessionConfig, payload.transcript_path);
-    if (synced.reset) {
+    if (synced.reset || synced.probed) {
+      // Persist a clean probe too: hook processes are ephemeral, so otherwise every
+      // mutation would reopen and parse the same 4MB transcript tail.
       state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
     }
   } catch {
@@ -136,13 +143,24 @@ function readRunCursor() {
   // 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}`);
+  // Grace is a landing allowance for THIS session's over-cap episode. The old global
+  // `hardcap-grace.json.N` slot pool let session A consume session B's allowance (and A
+  // clearing it refilled B's spent pool), so parallel sessions could be hard-blocked mid-
+  // landing for no reason. Keep the fallback `default` for hosts that omit session_id: in
+  // that legacy shape sibling workers still deliberately share one bounded allowance.
+  const rawGraceSessionId = typeof payload.session_id === 'string' && payload.session_id.trim()
+    ? payload.session_id.trim()
+    : 'default';
+  const graceSessionKey = rawGraceSessionId.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'default';
+  const graceDir = path.join(projectRoot, '.ukit', 'storage', 'cache');
+  const graceBaseName = `hardcap-grace.${graceSessionKey}.json`;
+  const gracePath = path.join(graceDir, graceBaseName);
+  const slotPath = (n) => path.join(graceDir, `${graceBaseName}.${n}`);
+  const slotPattern = new RegExp(`^${graceBaseName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d+)$`);
   const readSlots = () => {
     try {
       return fs.readdirSync(graceDir)
-        .map((name) => /^hardcap-grace\.json\.(\d+)$/.exec(name))
+        .map((name) => slotPattern.exec(name))
         .filter(Boolean)
         .map((m) => Number(m[1]))
         .sort((a, b) => a - b);
@@ -175,8 +193,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;
 }