@ngockhoale/ukit 3.4.1 → 3.4.2

package/src/diagnostics/routeOutcomes.js

@@ -53,17 +53,50 @@ async function readJson(filePath) {
 // shape as ring entries; malformed lines are skipped like parseSidecarLines.
 const SEGMENTS_REL = 'route-audit.segments.jsonl';
 
+// C92-H-05: the sidecar is append-only with no writer-side cap, so the readers
+// bound consumption instead — at most the newest SEGMENTS_MAX_BYTES tail. Same
+// 256 KiB as RETRIEVER_LANES_MAX_BYTES (src/core/codeintel/retriever.js:273),
+// the sibling JSONL budget. A mid-slice read starts on a partial line — the
+// first fragment is dropped, mirroring the truncated-tail tolerance below.
+// Keeping the tail (not the head) is load-bearing: a head-anchored read would
+// report year-old routing accuracy as current.
+export const SEGMENTS_MAX_BYTES = 256 * 1024;
+
 async function readJsonLines(filePath) {
   const rows = [];
   try {
-    const raw = await fs.readFile(filePath, 'utf8');
-    for (const line of raw.split('\n')) {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile() || stat.size <= 0) {
+      return rows;
+    }
+    let raw;
+    if (stat.size <= SEGMENTS_MAX_BYTES) {
+      raw = await fs.readFile(filePath, 'utf8');
+    } else {
+      // Tail-anchored read: newest bytes only, so cost stays flat no matter
+      // how old the sidecar gets.
+      const handle = await fs.open(filePath, 'r');
+      let bytesRead = 0;
+      const buffer = Buffer.allocUnsafe(SEGMENTS_MAX_BYTES);
+      try {
+        ({ bytesRead } = await handle.read(buffer, 0, SEGMENTS_MAX_BYTES, stat.size - SEGMENTS_MAX_BYTES));
+      } finally {
+        await handle.close().catch(() => {});
+      }
+      raw = buffer.toString('utf8', 0, bytesRead);
+    }
+    const lines = raw.split('\n');
+    if (stat.size > SEGMENTS_MAX_BYTES) {
+      // First line of a byte-offset slice is a fragment — always drop it.
+      lines.shift();
+    }
+    for (const line of lines) {
       if (!line.trim()) continue;
       try {
         const item = JSON.parse(line);
         if (item && typeof item === 'object' && !Array.isArray(item)) rows.push(item);
       } catch {
-        // skip malformed segment lines
+        // skip malformed segment lines (incl. a truncated tail mid-append)
       }
     }
   } catch {
@@ -123,9 +156,14 @@ export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } =
       }
     }
     const ledgerKeys = new Set();
+    // C92-H-05: keyed Map replaces the per-row ledgers.find — O(ledgers) once
+    // instead of O(rows × ledgers) inside the join loop (mirrors
+    // skillAccuracy.js's ledgerByKey).
+    const ledgerByKey = new Map();
     for (const ledger of ledgers) {
       if (ledger && typeof ledger.requestKey === 'string' && ledger.requestKey) {
         ledgerKeys.add(ledger.requestKey);
+        ledgerByKey.set(ledger.requestKey, ledger);
       }
     }
 
@@ -139,7 +177,7 @@ export async function collectRouteOutcomes(projectRoot, { limitLedgers = 500 } =
       modeBucket.routes += 1;
       taskBucket.routes += 1;
       modeTierBucket.routes += 1;
-      const ledger = ledgers.find((candidate) => candidate.requestKey === entry.requestKey);
+      const ledger = ledgerByKey.get(entry.requestKey);
       if (!ledger) continue;
       result.joined += 1;
       result.joinedRows.push({ audit: entry, ledger });

package/src/diagnostics/skillAccuracy.js

@@ -24,6 +24,13 @@ const AUDIT_REL = path.join(CACHE_DIR_REL, 'route-audit.json');
 // BL-004: rows evicted past the 40-entry ring cap spill to this append-only
 // JSONL sidecar — same row shape; malformed lines skipped like parseSidecarLines.
 const SEGMENTS_REL = path.join(CACHE_DIR_REL, 'route-audit.segments.jsonl');
+
+// C92-H-05: the sidecar is append-only with no writer-side cap, so the readers
+// bound consumption instead — at most the newest SEGMENTS_MAX_BYTES tail. Same
+// 256 KiB as RETRIEVER_LANES_MAX_BYTES (src/core/codeintel/retriever.js:273) and
+// routeOutcomes.js's SEGMENTS_MAX_BYTES. Tail-anchored (newest rows kept): a
+// head-anchored read would report year-old trigger accuracy as current.
+export const SEGMENTS_MAX_BYTES = 256 * 1024;
 const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'skill-accuracy.json');
 const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
 const MAX_SKILL_IDS = 8;
@@ -68,14 +75,38 @@ async function readJson(filePath) {
 async function readJsonLines(filePath) {
   const rows = [];
   try {
-    const raw = await fs.readFile(filePath, 'utf8');
-    for (const line of raw.split('\n')) {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile() || stat.size <= 0) {
+      return rows;
+    }
+    let raw;
+    if (stat.size <= SEGMENTS_MAX_BYTES) {
+      raw = await fs.readFile(filePath, 'utf8');
+    } else {
+      // Tail-anchored read: newest bytes only, so cost stays flat no matter
+      // how old the sidecar gets.
+      const handle = await fs.open(filePath, 'r');
+      let bytesRead = 0;
+      const buffer = Buffer.allocUnsafe(SEGMENTS_MAX_BYTES);
+      try {
+        ({ bytesRead } = await handle.read(buffer, 0, SEGMENTS_MAX_BYTES, stat.size - SEGMENTS_MAX_BYTES));
+      } finally {
+        await handle.close().catch(() => {});
+      }
+      raw = buffer.toString('utf8', 0, bytesRead);
+    }
+    const lines = raw.split('\n');
+    if (stat.size > SEGMENTS_MAX_BYTES) {
+      // First line of a byte-offset slice is a fragment — always drop it.
+      lines.shift();
+    }
+    for (const line of lines) {
       if (!line.trim()) continue;
       try {
         const item = JSON.parse(line);
         if (item && typeof item === 'object') rows.push(item);
       } catch {
-        // skip malformed segment lines
+        // skip malformed segment lines (incl. a truncated tail mid-append)
       }
     }
   } catch {
@@ -99,7 +130,7 @@ function skillIdsOf(entry) {
 
 async function writeArtifact(filePath, result) {
   const dir = path.dirname(filePath);
-  const tmp = path.join(dir, `.skill-accuracy-${process.pid}.tmp`);
+  const tmp = path.join(dir, `.skill-accuracy-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`);
   try {
     await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(tmp, JSON.stringify(result, null, 2));

package/src/index/buildIndex.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 
+// Cross-process build serialization (C92-B-01): the same withAsyncLock
+// protocol ensureIndexFresh uses in the installed index-core mirror, so every
+// buildCodeIndex caller — CLI, git hook, install — serializes without needing
+// its own call-site lock.
+import { withAsyncLock } from '../../template_project/.claude/ukit/runtime/async-lock.mjs';
+
 import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath, normalizeRelative } from './paths.js';
 import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpecifier } from './importResolution.js';
 import { clearIndexArtifactCache } from './queryIndex.js';
@@ -105,6 +111,23 @@ export class IndexDiscoveryTimeoutError extends Error {
   }
 }
 
+/**
+ * Fail-closed lock timeout (C92-B-01): a contended index-build lock that stays
+ * held past INDEX_BUILD_LOCK_WAIT_MS means another builder is still publishing
+ * (or a dead holder's lock could not be reclaimed). Building unlocked would
+ * interleave tmp+rename writes into a torn artifact set, so the caller gets a
+ * typed failure instead of a race.
+ */
+export class IndexBuildLockTimeoutError extends Error {
+  constructor({ waitedMs, lockPath }) {
+    super(`Index build lock ${lockPath} was still held after ${waitedMs}ms; refusing to publish unlocked.`);
+    this.name = 'IndexBuildLockTimeoutError';
+    this.code = 'INDEX_BUILD_LOCK_TIMEOUT';
+    this.waitedMs = waitedMs;
+    this.lockPath = lockPath;
+  }
+}
+
 const EXCLUDED_DIR_NAMES = new Set([
   'node_modules',
   '.git',
@@ -142,7 +165,56 @@ const CALL_IGNORE_WORDS = new Set([
   'if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof',
 ]);
 
+export const INDEX_BUILD_LOCK_NAME = 'index-build';
+
+/**
+ * How long a builder waits for a build already in flight before failing
+ * closed. Must comfortably cover a worst-case build of a large repo — the
+ * wait replaces what used to be a silent interleaved publish, so an overly
+ * short budget would trade torn artifacts for spurious timeouts.
+ */
+export const INDEX_BUILD_LOCK_WAIT_MS = 60_000;
+
+/**
+ * C92-B-01: every buildCodeIndex entry point publishes under the shared
+ * `index-build` lock. Per-artifact tmp+rename was never the problem — two
+ * builders with ASYMMETRIC write sets interleaved their renames, so a reader
+ * (or the next incremental merge) could consume meta.json from build A and
+ * files.json from build B. The lock lives inside the builder because the
+ * callers (refresh-index.mjs, build-index.mjs, indexTools, install) were all
+ * unlocked; ensureIndexFresh's own lock on the same path stays compatible —
+ * it drives buildCodeIndexInner directly while it holds the lock.
+ * Fail-closed: a lock that cannot be acquired inside the wait budget throws
+ * IndexBuildLockTimeoutError instead of publishing unlocked.
+ */
 export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = null, discoverySnapshot = null, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
+  // A signal aborted before we even look at the lock must classify exactly
+  // like a discovery cancellation: callers/tests rely on the typed
+  // IndexDiscoveryTimeoutError(aborted) and on no artifact directory ever
+  // appearing for a build that never started.
+  if (signal?.aborted) {
+    throw new IndexDiscoveryTimeoutError({ deadlineMs, phase: 'build', elapsedMs: 0, aborted: true });
+  }
+  const absoluteRoot = path.resolve(rootDir);
+  const lockBase = path.join(getIndexDir(absoluteRoot), INDEX_BUILD_LOCK_NAME);
+  const outcome = await withAsyncLock(
+    lockBase,
+    { signal, deadlineMs: INDEX_BUILD_LOCK_WAIT_MS },
+    () => buildCodeIndexInner({ rootDir: absoluteRoot, changedFiles, discoverySnapshot, signal, deadlineMs }),
+  );
+  if (outcome?.ok === true) {
+    return outcome.value;
+  }
+  if (outcome?.reason === 'aborted') {
+    throw new IndexCancelledError({ phase: 'build-lock' });
+  }
+  throw new IndexBuildLockTimeoutError({
+    waitedMs: outcome?.waitedMs ?? INDEX_BUILD_LOCK_WAIT_MS,
+    lockPath: `${lockBase}.lock`,
+  });
+}
+
+async function buildCodeIndexInner({ rootDir = process.cwd(), changedFiles = null, discoverySnapshot = null, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const indexDir = getIndexDir(absoluteRoot);
 
@@ -153,11 +225,22 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
   // full path below — correctness wins over the optimization, and incremental
   // output must stay equivalent to a clean full rebuild.
   const changedHintPlan = normalizeChangedFileHints(changedFiles);
-  if (changedHintPlan) {
-    const incremental = changedHintPlan.ok
-      ? await tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths: changedHintPlan.paths, signal })
-      : null;
-    if (incremental) {
+  let incrementalFallbackReason = changedHintPlan && !changedHintPlan.ok
+    ? 'unsafe-changed-file-hints'
+    : null;
+  if (changedHintPlan?.ok) {
+    const incremental = await tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths: changedHintPlan.paths, signal });
+    if (incremental?.rejected) {
+      // C92-B-02: a rejected merge is no longer silent. The reason lands on the
+      // build summary, and corruption-class rejections are also warned so the
+      // CLI callers that ignore the summary still surface it.
+      incrementalFallbackReason = incremental.detail
+        ? `${incremental.rejected} (${incremental.detail})`
+        : incremental.rejected;
+      if (incremental.detail) {
+        console.warn(`[index] incremental refresh rejected: meta.artifactItemCounts ${incremental.rejected} (${incremental.detail}) — falling back to full rebuild`);
+      }
+    } else if (incremental) {
       return incremental;
     }
   }
@@ -531,6 +614,11 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     reusedAnalogs: canReuseAnalogs,
     preservedRuntimeCaches,
     mode: 'full',
+    // C92-B-02: when changed-file hints were offered but the incremental merge
+    // refused them, this names the rejection (e.g.
+    // 'artifact-item-counts-mismatch (files.json: recorded 4, actual 5)') so
+    // the fallback is diagnosable instead of silently returning 'full' forever.
+    incrementalFallbackReason,
     parsedFiles: filesToParse.slice(),
     removedFiles: [],
   };
@@ -654,20 +742,11 @@ function isValidCoveredItems(items, fileRecords, keyFn) {
 }
 
 /**
- * Item shapes alone cannot detect a schema-current artifact whose `items` array
- * lost entries: every surviving entry still looks valid, yet the merge would
- * reuse it verbatim and publish an artifact missing the unchanged files. Each
- * required artifact therefore records its item count in meta, and the count must
- * match the array actually loaded — a mismatch (or a pre-count meta) falls back
- * to full discovery.
+ * C92-B-02: every rejection from tryIncrementalIndexUpdate carries a reason
+ * (and, for integrity failures, a detail string) instead of a bare null, so a
+ * torn or corrupted artifact set lands on the build summary as
+ * incrementalFallbackReason rather than silently forcing 'full' forever.
  */
-function artifactItemCountsMatch(metaArtifact, counts) {
-  const recorded = metaArtifact?.artifactItemCounts;
-  if (!recorded || typeof recorded !== 'object' || Array.isArray(recorded)) {
-    return false;
-  }
-  return Object.entries(counts).every(([name, count]) => Number(recorded[name]) === count);
-}
 
 /**
  * Stat every hinted path and classify it as an upsert, a removal, or — for
@@ -801,7 +880,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     [INDEX_ARTIFACTS.calls]: callsArtifact?.items?.length ?? -1,
     [INDEX_ARTIFACTS.relations]: relationsArtifact?.items?.length ?? -1,
   };
-  const previousArtifactsUsable = [
+  const previousArtifactsSchemaAndShapeUsable = [
     metaArtifact,
     filesArtifact,
     symbolsArtifact,
@@ -816,16 +895,29 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     && isValidCoveredItems(importsArtifact.items, filesArtifact.items, (item) => item.from)
     && isValidCoveredItems(callsArtifact.items, filesArtifact.items, (item) => item.filePath)
     && isValidCoveredItems(relationsArtifact.items, filesArtifact.items, (item) => item.filePath)
-    && Array.isArray(relationsArtifact?.sourceSnapshot?.styleFiles)
-    && artifactItemCountsMatch(metaArtifact, artifactItemCounts);
-  if (!previousArtifactsUsable) {
-    return null;
+    && Array.isArray(relationsArtifact?.sourceSnapshot?.styleFiles);
+  if (!previousArtifactsSchemaAndShapeUsable) {
+    return { rejected: 'previous-artifacts-unusable' };
+  }
+  // C92-B-02: the count gate used to fold silently into the same null as every
+  // other unusability, so a torn publish permanently disabled incremental
+  // refresh with no diagnostic. Name the artifacts that disagree with meta.
+  const recordedCounts = metaArtifact?.artifactItemCounts;
+  const countsRecorded = recordedCounts && typeof recordedCounts === 'object' && !Array.isArray(recordedCounts);
+  const countMismatchDetail = !countsRecorded
+    ? 'artifactItemCounts missing from meta.json'
+    : Object.entries(artifactItemCounts)
+        .filter(([name, actual]) => Number(recordedCounts[name]) !== actual)
+        .map(([name, actual]) => `${name}: recorded ${recordedCounts[name] ?? 'missing'}, actual ${actual}`)
+        .join(', ');
+  if (!countsRecorded || countMismatchDetail) {
+    return { rejected: 'artifact-item-counts-mismatch', detail: countMismatchDetail };
   }
 
   const previousRecordsByPath = new Map(filesArtifact.items.map((item) => [item.filePath, item]));
   const hintUpdates = await resolveChangedHintUpdates(absoluteRoot, changedPaths, previousRecordsByPath);
   if (!hintUpdates) {
-    return null;
+    return { rejected: 'changed-hints-unresolvable' };
   }
 
   // Merge the hint outcome into one sorted record set — the same shape and
@@ -894,7 +986,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     }
   }, signal, 'stat-style'));
   if (styleEntries.some((entry) => entry?.statError)) {
-    return null;
+    return { rejected: 'style-stat-unresolvable' };
   }
   const styleFilePaths = styleEntries.filter(Boolean).map((entry) => normalizeRelative(absoluteRoot, entry.absolutePath));
 
@@ -2869,7 +2961,12 @@ async function evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, e
     || Number.isNaN(maxAgeMs)
     || maxAgeMs < 0
     || (now - effectiveGeneratedAtMs) >= maxAgeMs
-    || !metaArtifact?.sourceFingerprint;
+    || !metaArtifact?.sourceFingerprint
+    // C92-B-03: an artifact set written under a different INDEX_SCHEMA_VERSION
+    // — older OR newer — is not fresh. `!==` covers the package-downgrade
+    // direction too; serving the old schema made `outline:` silently vanish
+    // while ranking kept answering.
+    || metaArtifact?.schemaVersion !== INDEX_SCHEMA_VERSION;
 
   // Legacy boolean callers (query-index, triage, verify-context) stop here and
   // let buildCodeIndex do its own discovery when a rebuild is needed.

package/src/index/fixLoopEscalation.js

@@ -377,6 +377,9 @@ export async function applyFixLoopEscalation({
     } catch {
       batchResult = null;
     }
+    if (!isPlainObject(batchResult)) {
+      batchResult = { status: 'unavailable', fallbackCode: 'adapter-failed', answers: [] };
+    }
   }
 
   const modelLane = batchResult

package/src/index/gitHooks.js

@@ -1,14 +1,15 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { escapeRegExp } from '../core/fileOps.js';
+import { escapeRegExp, writeFileAtomic, withFileLock } from '../core/fileOps.js';
 
 const HOOK_NAMES = ['post-commit', 'post-merge', 'post-checkout'];
 const BEGIN = '# UKit index auto-refresh (begin)';
 const END = '# UKit index auto-refresh (end)';
 
 export async function installIndexRefreshHooks({ projectRoot }) {
-  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  const hooksDir = resolveHooksDir(projectRoot);
   await ensureHooksDir(hooksDir);
 
   let installed = 0;
@@ -16,19 +17,31 @@ export async function installIndexRefreshHooks({ projectRoot }) {
 
   for (const hookName of HOOK_NAMES) {
     const hookPath = path.join(hooksDir, hookName);
-    const existing = await readTextOrEmpty(hookPath);
-    const base = existing || '#!/bin/sh\n';
-
-    if (hasCompleteManagedBlock(base)) {
-      unchanged += 1;
-      continue;
-    }
-
-    const cleanedBase = removeManagedBlockFragments(base);
-    const next = `${cleanedBase.trimEnd()}\n\n${buildManagedBlock()}\n`;
-    await fs.writeFile(hookPath, next, { mode: 0o755 });
-    await fs.chmod(hookPath, 0o755);
-    installed += 1;
+    // C90-20: serialize the read-modify-write — two ukit processes touching the
+    // same hook file interleave without a lock, and writeFileAtomic's tmp+rename
+    // guarantees a crash mid-write never publishes a torn hook to git.
+    const result = await withFileLock(hookPath, async () => {
+      const existing = await readTextOrEmpty(hookPath);
+      const base = existing || '#!/bin/sh\n';
+
+      // C91-007 review fix: a COMPLETE block is only 'unchanged' when its content
+      // matches the current generated block byte-for-byte. Pre-C90-17 installs
+      // produced a complete but synchronous, deadline-free block — marker-only
+      // detection would keep counting it 'unchanged' forever and the deadline
+      // fix would never reach exactly the users who already installed.
+      const existingBlock = extractManagedBlock(base);
+      const wanted = buildManagedBlock();
+      if (existingBlock === wanted) return 'unchanged';
+
+      const cleanedBase = removeManagedBlockFragments(base);
+      const next = `${cleanedBase.trimEnd()}\n\n${wanted}\n`;
+      await writeFileAtomic(hookPath, next);
+      await fs.chmod(hookPath, 0o755);
+      return 'installed';
+    });
+
+    if (result === 'installed') installed += 1;
+    else unchanged += 1; // includes lock-wait-expired (dropped mutation, journaled)
   }
 
   return {
@@ -39,7 +52,7 @@ export async function installIndexRefreshHooks({ projectRoot }) {
 }
 
 export async function removeIndexRefreshHooks({ projectRoot }) {
-  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  const hooksDir = resolveHooksDir(projectRoot);
   await ensureHooksDir(hooksDir);
 
   let removed = 0;
@@ -47,17 +60,19 @@ export async function removeIndexRefreshHooks({ projectRoot }) {
 
   for (const hookName of HOOK_NAMES) {
     const hookPath = path.join(hooksDir, hookName);
-    const existing = await readTextOrEmpty(hookPath);
-    if (!existing || !hasCompleteManagedBlock(existing)) {
-      unchanged += 1;
-      continue;
-    }
-
-    const next = removeManagedBlock(existing);
-    const cleaned = next.trim().length === 0 ? '#!/bin/sh\n' : `${next.trimEnd()}\n`;
-    await fs.writeFile(hookPath, cleaned, { mode: 0o755 });
-    await fs.chmod(hookPath, 0o755);
-    removed += 1;
+    const result = await withFileLock(hookPath, async () => {
+      const existing = await readTextOrEmpty(hookPath);
+      if (!existing || !hasCompleteManagedBlock(existing)) return 'unchanged';
+
+      const next = removeManagedBlock(existing);
+      const cleaned = next.trim().length === 0 ? '#!/bin/sh\n' : `${next.trimEnd()}\n`;
+      await writeFileAtomic(hookPath, cleaned);
+      await fs.chmod(hookPath, 0o755);
+      return 'removed';
+    });
+
+    if (result === 'removed') removed += 1;
+    else unchanged += 1;
   }
 
   return {
@@ -73,11 +88,40 @@ function buildManagedBlock() {
     'ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0',
     'SCRIPT="$ROOT/.claude/ukit/index/refresh-index.mjs"',
     '[ -f "$SCRIPT" ] || exit 0',
-    'node "$SCRIPT" >/dev/null 2>&1 || true',
+    // C90-17: never run the rebuild synchronously inside a git operation — the
+    // refresh is backgrounded (`&`) and armed with the same UKIT_HOOK_DEADLINE_MS
+    // convention other UKit hooks use. The sleeper kills the node child if it
+    // wedges (stalled mount, pathological enumeration); the env var also reaches
+    // the child so a deadline-aware script can exit cleanly first.
+    // Non-numeric or empty env values are sanitized to the default (same
+    // ''|*[!0-9]* guard as completion-gate.sh) — otherwise `sleep $((...))`
+    // aborts the killer subshell and the refresh runs unbounded.
+    'case "$UKIT_HOOK_DEADLINE_MS" in \'\'|*[!0-9]*) UKIT_HOOK_DEADLINE_MS=30000 ;; esac',
+    'export UKIT_HOOK_DEADLINE_MS',
+    'node "$SCRIPT" >/dev/null 2>&1 &',
+    'UKIT_REFRESH_PID=$!',
+    // The killer sleeps past the deadline before signaling, so the PID was
+    // captured before the delay — a recycled PID is only at risk in the narrow
+    // window after node exits, and `kill -0` closes most of it (kills the
+    // signal if our child is already gone; a recycled PID reused in-window is
+    // a documented theoretical residual).
+    '( sleep $((UKIT_HOOK_DEADLINE_MS / 1000 + 1)) 2>/dev/null; kill -0 "$UKIT_REFRESH_PID" 2>/dev/null && kill -9 "$UKIT_REFRESH_PID" 2>/dev/null ) </dev/null >/dev/null 2>&1 &',
     END,
   ].join('\n');
 }
 
+/**
+ * Extract the complete managed block (BEGIN..END inclusive), or null when the
+ * block is absent, partial, or the markers are misordered.
+ */
+function extractManagedBlock(content) {
+  const beginIndex = content.indexOf(BEGIN);
+  if (beginIndex < 0) return null;
+  const endIndex = content.indexOf(END, beginIndex + BEGIN.length);
+  if (endIndex < 0) return null;
+  return content.slice(beginIndex, endIndex + END.length);
+}
+
 function hasCompleteManagedBlock(content) {
   const beginIndex = content.indexOf(BEGIN);
   const endIndex = content.indexOf(END, beginIndex + BEGIN.length);
@@ -113,6 +157,32 @@ function removeManagedBlockFragments(content) {
   return kept.join('\n').replace(/\n{3,}/g, '\n\n');
 }
 
+/**
+ * C90-03: resolve the hooks dir through git, never from `.git` layout — linked
+ * worktrees have a `.git` FILE and `core.hooksPath` relocates the dir entirely.
+ * `git rev-parse --git-path hooks` honors both. Output may be relative (resolved
+ * against the cwd we spawned in = projectRoot) or absolute. Falls back to the
+ * classic `<root>/.git/hooks` when git isn't usable in this root, preserving
+ * the pre-C90 behavior for stub fixtures.
+ */
+function resolveHooksDir(projectRoot) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 5000,
+      maxBuffer: 64 * 1024,
+    });
+    const resolved = (result.stdout ?? '').trim();
+    if (!result.error && result.status === 0 && resolved) {
+      return path.isAbsolute(resolved) ? resolved : path.resolve(projectRoot, resolved);
+    }
+  } catch {
+    // git unavailable — fall through to the legacy path
+  }
+  return path.join(projectRoot, '.git', 'hooks');
+}
+
 async function ensureHooksDir(hooksDir) {
   try {
     const stat = await fs.stat(hooksDir);
@@ -120,7 +190,7 @@ async function ensureHooksDir(hooksDir) {
       throw new Error();
     }
   } catch {
-    throw new Error('No .git/hooks directory found. Run this inside a git project.');
+    throw new Error(`No git hooks directory found at ${hooksDir}. Run this inside a git project.`);
   }
 }
 

package/src/index/importResolution.js

@@ -111,11 +111,17 @@ export function resolveImportSpecifier({
   indexedFileSet,
   aliasContext,
 }) {
-  if (!specifier?.trim()) {
+  if (typeof specifier !== 'string' || !specifier.trim()) {
     return null;
   }
 
   if (specifier.startsWith('.')) {
+    // A relative specifier cannot be resolved without the importing file, so a
+    // malformed (non-string) edge.from must skip the edge instead of throwing
+    // inside path.posix.dirname.
+    if (typeof fromFilePath !== 'string') {
+      return null;
+    }
     const fromDir = path.posix.dirname(fromFilePath);
     const base = path.posix.normalize(path.posix.join(fromDir, specifier));
     return resolveCandidateBase(base, indexedFileSet);

package/src/index/playbookRegistry.js

@@ -18,7 +18,6 @@
 // locked by tests/consistency/registryParity.test.js.
 
 import fs from 'node:fs/promises';
-import fsSync from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -78,12 +77,14 @@ const AUTONOMOUS_TRIGGER_RE = /\b(finish (?:this|the) backlog|bounded (?:long )?
 const RELEASE_TRIGGER_RE = /\b(publish|ship it|release|bump (?:the )?version|deploy|cut a release|tag (?:the )?release)\b/i;
 const HANDOFF_CYCLE_TRIGGER_RE = /\b(handoff|multi[- ]?task cycle|task pipeline|execute the plan|worktree)\b/i;
 
-// session-pickup discriminator needs the resumable-record check.
-function hasResumableRecord(projectRoot) {
+// session-pickup discriminator needs the resumable-record check. ASYNC scan
+// (W3-PB2): the resolve path runs inside hook processes where a sync
+// readdirSync parks the event loop and can starve the hook self-deadline.
+async function hasResumableRecord(projectRoot) {
   if (!projectRoot) return false;
   try {
     const runsDir = path.join(projectRoot, '.ukit', 'storage', 'runs');
-    const entries = fsSync.readdirSync(runsDir, { withFileTypes: true });
+    const entries = await fs.readdir(runsDir, { withFileTypes: true });
     return entries.some((entry) => entry.isFile() && entry.name.endsWith('.json'));
   } catch {
     return false;
@@ -289,7 +290,7 @@ function matchFirst(text, regexes) {
   return -1;
 }
 
-function buildRouteSignals({
+async function buildRouteSignals({
   signalText,
   executionMode,
   escalationTriggers,
@@ -358,7 +359,7 @@ function buildRouteSignals({
     testHarness: TEST_HARNESS_RE.test(signalText),
     measurable: /\d/.test(signalText) || MEASURABLE_RE.test(signalText),
     dataMove: DATA_MOVE_RE.test(signalText),
-    hasResumableRecord: hasResumableRecord(projectRoot),
+    hasResumableRecord: await hasResumableRecord(projectRoot),
     // BL-026 review fix: ask to convert/author a skill — beats defect verbs in
     // the same sentence ("make this repeated fix flow a skill").
     skillAsk: SKILL_ASK_RE.test(signalText),
@@ -376,14 +377,17 @@ const MEASURABLE_RE = /\b(latency|baseline|benchmark|profile|cpu|memory|heap|tak
 // REQUIRED — a registry file without them is malformed (FR-007), where the
 // workflow-policy loader tolerates filename-stem ids.
 function parsePlaybookMeta(raw, filePath) {
-  if (!raw.startsWith('---\n')) {
+  // W3-PB1: normalize CRLF before fence matching — a Windows-authored
+  // frontmatter block is still frontmatter, not malformed.
+  const text = String(raw).replace(/\r\n/g, '\n');
+  if (!text.startsWith('---\n')) {
     return null;
   }
-  const fenceIndex = raw.indexOf('\n---', 3);
+  const fenceIndex = text.indexOf('\n---', 3);
   if (fenceIndex === -1) {
     return null; // unterminated frontmatter
   }
-  const metaText = raw.slice(4, fenceIndex);
+  const metaText = text.slice(4, fenceIndex);
   const meta = {};
   for (const line of metaText.split('\n')) {
     const match = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
@@ -408,7 +412,7 @@ function parsePlaybookMeta(raw, filePath) {
   if (lanes.length === 0) {
     return null;
   }
-  const body = raw.slice(fenceIndex + 4).replace(/^\n/, '');
+  const body = text.slice(fenceIndex + 4).replace(/^\n/, '');
   if (body.trim() === '') {
     return null; // empty body → not a playbook
   }
@@ -553,7 +557,7 @@ export async function resolvePlaybookId({
       ...(Array.isArray(escalationTriggers) ? escalationTriggers : []),
       ...deriveEscalationTriggers(floor),
     ])];
-    const signals = buildRouteSignals({
+    const signals = await buildRouteSignals({
       signalText,
       executionMode,
       escalationTriggers: mergedTriggers,