@ngockhoale/ukit 2.3.9 → 2.3.10

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

@@ -13,6 +13,21 @@ const RESUME_INTENT_TTL_MS = 30 * 60 * 1000;
 const MAX_RECEIPTS = 24;
 const MAX_SOURCE_FILES = 16;
 const MAX_CONTINUATIONS = 6;
+// Two adjacent identical failed verifications (no edit attempt between them) are a loop;
+// vibecode routes — which bypass the cap and every reentrant valve — additionally get a
+// cumulative escape after the same verification failed this many times across edits.
+const VERIFICATION_LOOP_STREAK = 2;
+const VIBECODE_VERIFICATION_FAILURE_LIMIT = 4;
+const MAX_TRACKED_VERIFICATIONS = 8;
+// hook-chain-runner.mjs gives every hook script a 4s child budget, and omp blocks Edit|Write
+// when a chain script is killed. Waiting longer than that for a contended lock got the
+// recording hook killed mid-chain (receipt lost, edit blocked). Give up and fail open well
+// inside the budget instead — under extreme contention a receipt may be lost, but the hook
+// is never killed by its own chain.
+const HOOK_SAFE_LOCK_WAIT_MS = 2500;
+function withLedgerLock(target, fn) {
+  return withFileLock(target, fn, { maxWaitMs: HOOK_SAFE_LOCK_WAIT_MS });
+}
 const IMPLEMENT_MODES = new Set([
   'tiny-fix',
   'local-fix',
@@ -86,9 +101,14 @@ async function readJson(filePath, fallback = null) {
   }
 }
 
+// Parallel writers in one process (subagent Stop hooks, concurrent receipts) used to share
+// a single `pid`-suffixed temp path: one rename removed the file under the other and the
+// writer crashed with ENOENT mid-hook. Make every write's temp path unique.
+let atomicWriteCounter = 0;
 async function writeJsonAtomic(filePath, value) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.tmp`;
+  atomicWriteCounter += 1;
+  const tempPath = `${filePath}.${process.pid}-${atomicWriteCounter}-${Math.random().toString(16).slice(2)}.tmp`;
   await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
   await fs.rename(tempPath, filePath);
 }
@@ -276,8 +296,129 @@ function fileMatchesExpected(receiptFile, expectedFile) {
   return false;
 }
 
+// Piping a verification command into a read-only consumer (`yarn test 2>&1 | tail -6`) is
+// the standard idiom for trimming output. The FIRST pipe segment is still the planned
+// verification, so it may mint targeted evidence — but only when every later segment is a
+// benign text consumer. Anything that can reinterpret or execute output (sh, xargs, tee)
+// keeps the receipt broad.
+const BENIGN_OUTPUT_CONSUMERS = new Set([
+  'tail', 'head', 'grep', 'egrep', 'fgrep', 'rg', 'ag', 'sed', 'cat',
+  'awk', 'cut', 'wc', 'sort', 'uniq', 'tr', 'nl',
+]);
+
+function isBenignOutputConsumer(segment) {
+  const firstWord = String(segment || '').trim().split(/\s+/)[0] || '';
+  return BENIGN_OUTPUT_CONSUMERS.has(firstWord);
+}
+
+function terminalShellCommandUnit(command) {
+  const text = String(command || '').trim();
+  if (!text) return null;
+
+  let quote = null;
+  let escaped = false;
+  let pipeBuffer = '';
+  let currentPipes = [];
+  const segments = [];
+
+  const closePipe = () => {
+    const trimmed = pipeBuffer.trim();
+    if (!trimmed) return null;
+    currentPipes.push(trimmed);
+    pipeBuffer = '';
+    return trimmed;
+  };
+  const closeSegment = () => {
+    if (!closePipe()) return false;
+    segments.push(currentPipes);
+    currentPipes = [];
+    return true;
+  };
+  // Redirections (`> file`, `2>&1`, `>> x`, `&> y`, `< in`) modify the current command's
+  // streams; they are consumed so the fd digits/paths do not corrupt the unit text.
+  const skipRedirectionTarget = (index) => {
+    let next = index;
+    while (next < text.length && /\s/.test(text[next])) next += 1;
+    while (
+      next < text.length
+      && !/\s/.test(text[next])
+      && !'&|;()<>`\n\r'.includes(text[next])
+    ) next += 1;
+    return next;
+  };
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (escaped) {
+      escaped = false;
+      pipeBuffer += char;
+      continue;
+    }
+    if (char === '\\') {
+      escaped = true;
+      pipeBuffer += char;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      pipeBuffer += char;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      pipeBuffer += char;
+      continue;
+    }
+
+    // This deliberately recognizes only simple top-level `&&` chains and pipes into
+    // benign consumers. Other shell control/grouping syntax can mask a terminal
+    // command's status, so it must remain broad rather than targeted evidence.
+    if (char === ';' || char === '`' || char === '(' || char === ')' || char === '\n' || char === '\r') {
+      return null;
+    }
+    if (char === '$' && text[index + 1] === '(') return null;
+    if (char === '>' || char === '<') {
+      let next = index + 1;
+      if (text[next] === '>' && char === '>') next += 1;
+      if (text[next] === '&') next += 1;
+      index = skipRedirectionTarget(next) - 1;
+      continue;
+    }
+    if (char === '&' && text[index + 1] === '>') {
+      let next = index + 2;
+      if (text[next] === '>') next += 1;
+      index = skipRedirectionTarget(next) - 1;
+      continue;
+    }
+    if (char === '|') {
+      if (text[index + 1] === '|') return null;
+      if (!closePipe()) return null;
+      continue;
+    }
+    if (char === '&') {
+      if (text[index + 1] !== '&') return null;
+      if (!closeSegment()) return null;
+      index += 1;
+      continue;
+    }
+    pipeBuffer += char;
+  }
+
+  if (quote || escaped) return null;
+  if (!closeSegment()) return null;
+
+  const terminalSegment = segments[segments.length - 1];
+  if (terminalSegment.length > 1) {
+    const consumers = terminalSegment.slice(1);
+    if (!consumers.every((consumer) => isBenignOutputConsumer(consumer))) {
+      return null;
+    }
+  }
+  return terminalSegment[0];
+}
+
 function matchesRoutedCommand(command, routedCommand) {
-  const receipt = String(command || '').trim();
+  const receipt = terminalShellCommandUnit(command);
   const routed = String(routedCommand || '').trim();
   if (!receipt || !routed) return false;
   return receipt === routed || receipt.startsWith(routed) || routed.startsWith(receipt);
@@ -317,6 +458,17 @@ function carriedEvidenceLedger(fresh, current) {
     verificationSucceeded: fresh.verificationSucceeded || current.verificationSucceeded === true,
     verificationFailed: fresh.verificationFailed || current.verificationFailed === true,
     receipts: [...(current.receipts || [])].slice(-MAX_RECEIPTS),
+    // The continuation budget belongs to the same logical request (promptKey), so a re-key
+    // must keep counting toward the cap. Resetting it here made the cap unreachable and the
+    // Stop gate loop forever on harnesses without a stop_hook_active valve.
+    continuationCount: Math.max(Number(fresh.continuationCount || 0), Number(current.continuationCount || 0)),
+    continuationRequestKey: current.continuationRequestKey || fresh.continuationRequestKey || null,
+    notified: fresh.notified === true || current.notified === true,
+    // Verification-loop tracking and any minted blocker belong to the same logical request
+    // too — dropping a blocker on re-key would resume the exact loop it recorded.
+    failedVerificationStreak: current.failedVerificationStreak || null,
+    verificationFailureCounts: current.verificationFailureCounts || {},
+    blocker: current.blocker || null,
   };
 }
 
@@ -331,6 +483,7 @@ function evidencePromptKey(routeState) {
   if (!promptText) return null;
   return `prompt-${crypto.createHash('sha256').update(promptText).digest('hex').slice(0, 20)}`;
 }
+export { evidencePromptKey };
 
 function freshLedger(payload, routeState, harness) {
   return {
@@ -364,61 +517,123 @@ export async function recordExecutionReceipt({
   harness = 'unknown',
 } = {}) {
   if (!projectRoot || !toolName) return null;
-  const routeState = await readRouteState(projectRoot, payload);
-  const current = await readExecutionLedger(projectRoot, payload);
-  const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
-    ? carriedEvidenceLedger(freshLedger(payload, routeState, harness), current)
-    : { ...current, harness: current.harness || harness };
-
-  const failed = explicitError(payload);
-  const exitCode = extractExitCode(payload);
-  const success = !failed && (exitCode === null || exitCode === 0);
-  const toolInput = payload.tool_input || {};
-  const receipt = {
-    ts: Date.now(),
-    toolName,
-    toolUseId: payload.tool_use_id || null,
-    success,
-    exitCode,
-  };
+  // The whole read-modify-write is locked: parallel subagents record receipts through the
+  // same session ledger file, and an unlocked snapshot rewrite dropped whichever receipts
+  // landed between the read and the write.
+  return withLedgerLock(ledgerPath(projectRoot, payload), async () => {
+    const routeState = await readRouteState(projectRoot, payload);
+    const current = await readExecutionLedger(projectRoot, payload);
+    const nextRequestKey = routeState?.requestKey || null;
+    // A missing/foreign route state must never blank the evidence this session already
+    // banked. The shared state slot is single-owner (a parallel subagent re-stamps it), so
+    // routeState === null is routine mid-request — rebuilding from fresh there re-demanded
+    // every evidence the request had produced and froze the run. Without a live requestKey
+    // the only safe move is to keep appending to the current ledger.
+    const ledger = current && !nextRequestKey
+      ? { ...current, harness: current.harness || harness }
+      : (!current || current.requestKey !== nextRequestKey
+        ? carriedEvidenceLedger(freshLedger(payload, routeState, harness), current)
+        : { ...current, harness: current.harness || harness });
+
+    const failed = explicitError(payload);
+    const exitCode = extractExitCode(payload);
+    const success = !failed && (exitCode === null || exitCode === 0);
+    const toolInput = payload.tool_input || {};
+    const receipt = {
+      ts: Date.now(),
+      toolName,
+      toolUseId: payload.tool_use_id || null,
+      success,
+      exitCode,
+    };
 
-  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
-    receipt.kind = 'source';
-    receipt.file = toolInput.file_path || toolInput.path || null;
-    ledger.sourceSucceeded ||= success;
-    if (success && receipt.file) {
-      ledger.sourceFiles = [...new Set([...(ledger.sourceFiles || []), receipt.file])].slice(-MAX_SOURCE_FILES);
-    }
-  } else if (toolName === 'Edit' || toolName === 'Write') {
-    receipt.kind = 'write';
-    receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
-    ledger.writeAttempted = true;
-    ledger.writeSucceeded ||= success;
-  } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
-    receipt.kind = 'verification';
-    receipt.command = String(toolInput.command || '').trim();
-    // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
-    // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
-    // as broad — counted only when the route carried no commands at all.
-    const routedCommands = routedVerificationCommands(routeState?.routeSummary);
-    if (routedCommands.length > 0) {
-      const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
-      receipt.scope = matched ? 'targeted' : 'broad';
-      if (receipt.scope === 'targeted') {
-        ledger.targetedVerificationSucceeded ||= success;
+    if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+      receipt.kind = 'source';
+      receipt.file = toolInput.file_path || toolInput.path || null;
+      ledger.sourceSucceeded ||= success;
+      if (success && receipt.file) {
+        ledger.sourceFiles = [...new Set([...(ledger.sourceFiles || []), receipt.file])].slice(-MAX_SOURCE_FILES);
+      }
+    } else if (toolName === 'Edit' || toolName === 'Write') {
+      receipt.kind = 'write';
+      receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+      ledger.writeAttempted = true;
+      ledger.writeSucceeded ||= success;
+      // A mutation attempt between failures breaks the "no change in between" loop shape.
+      if (ledger.failedVerificationStreak) ledger.failedVerificationStreak = null;
+    } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
+      receipt.kind = 'verification';
+      receipt.command = String(toolInput.command || '').trim();
+      // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
+      // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
+      // as broad — counted only when the route carried no commands at all.
+      const routedCommands = routedVerificationCommands(routeState?.routeSummary);
+      if (routedCommands.length > 0) {
+        const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
+        receipt.scope = matched ? 'targeted' : 'broad';
+        if (receipt.scope === 'targeted') {
+          ledger.targetedVerificationSucceeded ||= success;
+        }
       }
+      ledger.verificationAttempted = true;
+      ledger.verificationSucceeded ||= success;
+      ledger.verificationFailed ||= !success;
+
+      // Verification-loop tracking. `terminalShellCommandUnit` gives the loop identity:
+      // the same failing check rerun — `setup && yarn test` and `yarn test 2>&1 | tail`
+      // both count as the same command, while a different check resets the streak.
+      const fingerprint = terminalShellCommandUnit(receipt.command) || receipt.command;
+      const counts = { ...(ledger.verificationFailureCounts || {}) };
+      if (success) {
+        delete counts[fingerprint];
+        ledger.verificationFailureCounts = counts;
+        if (ledger.failedVerificationStreak?.fingerprint === fingerprint) {
+          ledger.failedVerificationStreak = null;
+        }
+      } else {
+        const streakFingerprint = ledger.failedVerificationStreak?.fingerprint;
+        const streakCount = streakFingerprint === fingerprint
+          ? Number(ledger.failedVerificationStreak.count || 0) + 1
+          : 1;
+        ledger.failedVerificationStreak = { fingerprint, count: streakCount };
+        counts[fingerprint] = Number(counts[fingerprint] || 0) + 1;
+        const trackedKeys = Object.keys(counts);
+        if (trackedKeys.length > MAX_TRACKED_VERIFICATIONS) {
+          for (const key of trackedKeys.slice(0, trackedKeys.length - MAX_TRACKED_VERIFICATIONS)) {
+            delete counts[key];
+          }
+        }
+        ledger.verificationFailureCounts = counts;
+
+        const vibecode = routeState?.routeSummary?.autonomyLevel === 'vibecode';
+        const shortCommand = fingerprint.length > 80 ? `${fingerprint.slice(0, 77)}…` : fingerprint;
+        if (streakCount >= VERIFICATION_LOOP_STREAK) {
+          ledger.blocker = {
+            kind: 'verification-loop',
+            visible: true,
+            detail: `verification "${shortCommand}" failed ${streakCount} times in a row with no edit in between — this is a loop, not progress. Report the failing output as a concrete blocker instead of rerunning it.`,
+            command: fingerprint,
+            ts: Date.now(),
+          };
+        } else if (vibecode && counts[fingerprint] >= VIBECODE_VERIFICATION_FAILURE_LIMIT) {
+          ledger.blocker = {
+            kind: 'verification-loop',
+            visible: true,
+            detail: `verification "${shortCommand}" failed ${counts[fingerprint]} times in continuous (vibecode) execution — report the failing output as a concrete blocker instead of retrying.`,
+            command: fingerprint,
+            ts: Date.now(),
+          };
+        }
+      }
+    } else {
+      return ledger;
     }
-    ledger.verificationAttempted = true;
-    ledger.verificationSucceeded ||= success;
-    ledger.verificationFailed ||= !success;
-  } else {
-    return ledger;
-  }
 
-  ledger.receipts = appendReceipt(ledger.receipts, receipt);
-  ledger.updatedAt = Date.now();
-  await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
-  return ledger;
+    ledger.receipts = appendReceipt(ledger.receipts, receipt);
+    ledger.updatedAt = Date.now();
+    await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
+    return ledger;
+  });
 }
 
 function requiredEvidence(state = {}) {
@@ -500,13 +715,30 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
   const evidence = requiredEvidence(state);
   if (ledger?.blocker) {
+    // A blocker minted by the gate itself (verification loop) is the run's exit path — it
+    // must be user-visible or the release is indistinguishable from a stall. A blocker
+    // minted by a permission decision is already named in the model's own reply and stays
+    // silent here.
+    if (ledger.blocker.visible === true) {
+      return {
+        continue: false,
+        notify: true,
+        missingEvidence: [],
+        reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
+      };
+    }
     return { continue: false, notify: false, missingEvidence: [] };
   }
   if (evidence.length === 0) {
     return { continue: false, notify: false, missingEvidence: [] };
   }
 
-  const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
+  // Request identity is the prompt (see evidencePromptKey): the router re-keys requestKey on
+  // every Edit/Write, so a requestKey mismatch alone must not discard the evidence — and the
+  // continuation budget — the request already accumulated. A different prompt keeps a clean slate.
+  const sameRequest = !ledger?.requestKey || !state?.requestKey
+    || ledger.requestKey === state.requestKey
+    || (ledger.promptKey && evidencePromptKey(state) === ledger.promptKey);
   const effectiveLedger = sameRequest ? ledger : {};
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, routeSummary));
   if (missingEvidence.length === 0) {
@@ -535,6 +767,28 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     };
   }
 
+  // Same reasoning as find-cause, for the analysis-shaped end of map-impact: an impact map
+  // whose honest outcome is "analysis complete, no change warranted" must be able to end
+  // visibly. The contract's completionRule only demands impact evidence BEFORE an edit claim
+  // — it does not make a mutation mandatory — but the gate treated missing write evidence as
+  // an order to edit, and an analysis-only request looped Stop → "make an Edit" → Stop
+  // forever. The valve opens only when the analysis half actually finished (impact evidence
+  // satisfied), no mutation was attempted, and no verification failed; anything less has
+  // concrete unfinished work and keeps recovering.
+  if (
+    mode === 'map-impact'
+    && !missingEvidence.includes('impact-evidence')
+    && effectiveLedger.writeAttempted !== true
+    && effectiveLedger.verificationFailed !== true
+  ) {
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence,
+      reason: 'UKit impact analysis ended without a mutation. A completed impact map with no warranted change is valid; report the findings and whether a follow-up edit is needed. Do not claim any fix without write and verification evidence.',
+    };
+  }
+
   const gated = IMPLEMENT_MODES.has(mode);
   if (!gated) {
     return {
@@ -547,10 +801,12 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
 
   // Continuation attempts only make sense within the request that minted them: a new
   // routed request in the same session must start with a fresh budget, otherwise a cap
-  // exhausted on task A suppresses recovery for task B.
+  // exhausted on task A suppresses recovery for task B. A requestKey mismatch within the
+  // same promptKey is just the router re-keying mid-request — not a new request.
   const staleContinuations = effectiveLedger?.continuationRequestKey
     && state?.requestKey
-    && effectiveLedger.continuationRequestKey !== state.requestKey;
+    && effectiveLedger.continuationRequestKey !== state.requestKey
+    && !(effectiveLedger.promptKey && evidencePromptKey(state) === effectiveLedger.promptKey);
   const continuationCount = staleContinuations
     ? 0
     : Number(effectiveLedger?.continuationCount || 0);
@@ -588,19 +844,21 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   };
 }
 
-export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null) {
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null, promptKey = null) {
   const target = ledgerPath(projectRoot, payload);
   // Locked re-read: parallel subagents firing Stop hooks share one ledger file, and a
   // stale-snapshot rewrite would reset each other's continuationCount — the budget would
   // never advance and the gate would keep issuing continuations.
-  return withFileLock(target, async () => {
+  return withLedgerLock(target, async () => {
     const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
     // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
     // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
-    // persist says 7) and the next request inherits a nearly exhausted budget.
+    // persist says 7) and the next request inherits a nearly exhausted budget. Same-prompt
+    // re-keys are the same request, so their budget must keep counting toward the cap.
     const stale = requestKey
       && current?.continuationRequestKey
-      && current.continuationRequestKey !== requestKey;
+      && current.continuationRequestKey !== requestKey
+      && !(promptKey && current.promptKey && promptKey === current.promptKey);
     const next = {
       ...current,
       continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
@@ -615,7 +873,7 @@ export async function incrementContinuation(projectRoot, payload = {}, ledger =
 
 export async function markNotified(projectRoot, payload = {}, ledger = null) {
   const target = ledgerPath(projectRoot, payload);
-  return withFileLock(target, async () => {
+  return withLedgerLock(target, async () => {
     const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
     const next = { ...current, notified: true, updatedAt: Date.now() };
     await writeJsonAtomic(target, next);
@@ -623,6 +881,25 @@ export async function markNotified(projectRoot, payload = {}, ledger = null) {
   });
 }
 
+// omp's session_stop carries no stop_hook_active marker, so reentrancy must be detected from
+// the ledger itself: a stop whose recovery turn produced no new receipts is the reentrant
+// shape Claude Code flags natively. The fingerprint deliberately excludes continuation
+// bookkeeping fields (count/notified/updatedAt) so this call's own writes stay invisible to
+// the next comparison — only real receipts change it.
+export async function noteStopProgress(projectRoot, payload = {}) {
+  const target = ledgerPath(projectRoot, payload);
+  return withLedgerLock(target, async () => {
+    const current = await readExecutionLedger(projectRoot, payload);
+    if (!current) return { reentrant: false };
+    const receipts = Array.isArray(current.receipts) ? current.receipts : [];
+    const fingerprint = `${receipts.length}:${receipts[receipts.length - 1]?.ts || 0}`;
+    const reentrant = typeof current.stopProgressFingerprint === 'string'
+      && current.stopProgressFingerprint === fingerprint;
+    await writeJsonAtomic(target, { ...current, stopProgressFingerprint: fingerprint, updatedAt: Date.now() });
+    return { reentrant };
+  });
+}
+
 async function readStdin() {
   if (process.stdin.isTTY) return '';
   const chunks = [];
@@ -681,7 +958,7 @@ async function main() {
 
     if (result.continue) {
       if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null);
+      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
       process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
     } else if (result.capped || result.notify) {
       // Non-blocking endings (non-gated modes, or cap reached after the final notice) must

package/templates/.claude/ukit/runtime/token-utils.mjs

@@ -82,17 +82,49 @@ 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;
+  }
+}
+
+// In-process holder registry: same-pid holders are parallel async flows whose liveness a
+// pid probe cannot prove, so the module tracks them itself.
+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 means a pre-token holder and keeps the legacy mtime-only
+ * reclaim), so a slow-but-alive holder on a crawling disk is waited out, not stolen.
+ * Release only removes a dir this acquisition still owns, so a reclaimed-then-
+ * re-acquired 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.
  * Protocol-compatible with src/core/fileOps.js withFileLock (same `<file>.lock`
- * path), so CLI processes and hook processes serialize against each other.
+ * path and owner-file format), so CLI processes 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
@@ -100,24 +132,48 @@ 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 fs.mkdir(path.dirname(lockPath), { recursive: true });
       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);
+        // Stealing a live holder reintroduces the exact interleaved-write race this
+        // lock exists to prevent, and the stolen holder's release then deleted the
+        // successor's lock. Only a dead pid (or a leaked same-pid dir with no live
+        // registered flow) may be reclaimed.
+        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
@@ -132,7 +188,14 @@ export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxW
   } finally {
     if (locked) {
       try {
-        await fs.rm(lockPath, { recursive: true, force: true });
+        // Remove the lock only if THIS acquisition still owns it: after a stale reclaim
+        // another holder may already own the dir, and deleting it would unlock their
+        // critical section for a third waiter.
+        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
       }