@ngockhoale/ukit 2.4.2 → 2.5.0

package/src/core/sensitiveValueScanner.js

@@ -0,0 +1,118 @@
+/**
+ * sensitiveValueScanner.js (TASK-036)
+ *
+ * Shared source-side extraction of the high-confidence secret *value* scanner
+ * that lives in templates/.claude/hooks/sensitive-data-guard.sh. One semantic
+ * implementation is consumed by the runtime hook mirror (TASK-038/039) and the
+ * PROJECT_IMPORTANT.md renderer (TASK-037).
+ *
+ * Scope is the value scanner only: vendor/API-key patterns, JWT, private-key
+ * block, SHA-256 exact-value allowlist matching, and the
+ * security.sensitiveDataGate config read. File/path classification and Bash
+ * command-shape logic stay in the hook.
+ *
+ * Leak-safety contract: return values carry labels only — never a secret
+ * value, prefix, suffix, excerpt, or hash of a matched secret.
+ */
+
+import { createHash } from 'node:crypto';
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+// --- high-confidence secret value patterns ---
+// Semantically identical to TOKEN_PATTERNS in sensitive-data-guard.sh.
+// AKIA/ASIA/AIza prefixes are pure base64-compatible text, so an encoded blob
+// can contain a coincidental key-shaped substring — those rules must stand
+// alone with no base64/base64url character on either side.
+const TOKEN_PATTERNS = [
+  { label: 'OpenAI/Anthropic-style API key', re: /\bsk-(?:proj-|ant-|svc-|acct-|admin-)?[A-Za-z0-9_-]{20,}/g },
+  { label: 'AWS access key id', re: /(?<![A-Za-z0-9+/_-])(?:AKIA|ASIA)[0-9A-Z]{16}(?![A-Za-z0-9+/_-])/g },
+  { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
+  { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
+  { label: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+  { label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { label: 'Google API key', re: /(?<![A-Za-z0-9+/_-])AIza[0-9A-Za-z_-]{20,}(?![A-Za-z0-9+/_-])/g },
+  { label: 'Stripe live key', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
+  { label: 'JWT', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  { label: 'private key block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+];
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/i;
+
+/**
+ * Scan text for high-confidence secret values.
+ *
+ * @param {string} text
+ * @param {{ allowlistHashes?: string[], gateEnabled?: boolean }} [options]
+ *   allowlistHashes: SHA-256 hex digests of explicitly approved exact values.
+ *   gateEnabled: pass isSensitiveDataGateEnabled(config); when false the scan
+ *   reports the gate's exit-0 semantics (no detection) like today's hook.
+ * @returns {{ hasSecret: boolean, allowed: boolean, labels: string[] }}
+ *   labels only — never values, excerpts, or hashes.
+ */
+export function scanText(text, options = {}) {
+  const { allowlistHashes = [], gateEnabled = true } = options || {};
+  const clean = { hasSecret: false, allowed: false, labels: [] };
+  if (gateEnabled === false) return clean;
+  if (typeof text !== 'string' || text.length === 0) return clean;
+
+  const allowed = new Set(
+    Array.isArray(allowlistHashes) ? allowlistHashes.filter((h) => typeof h === 'string') : [],
+  );
+
+  const labels = new Set();
+  let sawAllowlisted = false;
+  for (const { label, re } of TOKEN_PATTERNS) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+      if (allowed.has(sha256(match[0]))) {
+        sawAllowlisted = true;
+        continue;
+      }
+      labels.add(label);
+    }
+  }
+
+  if (labels.size === 0) {
+    return { hasSecret: false, allowed: sawAllowlisted, labels: [] };
+  }
+  return { hasSecret: true, allowed: false, labels: [...labels] };
+}
+
+/**
+ * Gate toggle: enabled unless security.sensitiveDataGate === false
+ * (mirrors the hook's explicit-false check on .ukit/storage/config.json).
+ *
+ * @param {object|null|undefined} config injected config object
+ * @returns {boolean}
+ */
+export function isSensitiveDataGateEnabled(config) {
+  if (config && config.security && config.security.sensitiveDataGate === false) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Load the SHA-256 exact-value allowlist from an injected config object.
+ * Accepts security.allowlist.values (mirror of allowlist.json) or
+ * security.sensitiveDataAllowlist; keeps only well-formed 64-hex digests.
+ *
+ * @param {object|null|undefined} config
+ * @returns {string[]} SHA-256 hex digests
+ */
+export function loadSensitiveAllowlist(config) {
+  if (!config || typeof config !== 'object') return [];
+  const security = config.security && typeof config.security === 'object' ? config.security : {};
+  const candidates = [];
+  if (security.allowlist && Array.isArray(security.allowlist.values)) {
+    candidates.push(...security.allowlist.values);
+  }
+  if (Array.isArray(security.sensitiveDataAllowlist)) {
+    candidates.push(...security.sensitiveDataAllowlist);
+  }
+  return candidates.filter((v) => typeof v === 'string' && SHA256_HEX_RE.test(v));
+}

package/src/core/status.js

@@ -7,6 +7,7 @@ import { buildPromptCacheStats } from './token/index.js';
 import { countMemoryItems } from './memory/store.js';
 import { buildCompactPressureState } from './compact/threshold.js';
 import { detectProjectContext } from '../context/detectProjectContext.js';
+import { inspectProjectImportant, inspectProjectImportantWiring } from './projectImportant.js';
 
 function formatPrimaryAgent(agentKey) {
   if (agentKey === 'claude-code') return 'Claude Code';
@@ -151,6 +152,29 @@ export async function buildStatusReport(projectRoot) {
   const memoryCounts = await countMemoryItems(projectRoot);
   const adapters = await detectAdapterLabels(projectRoot, config.agent);
 
+  // TASK-044 — typed projectImportant state + conditional adapter wiring (spec §13).
+  const installMeta = await readStatusJson(
+    path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json'),
+  );
+  const trackedPaths = Array.isArray(installMeta?.files)
+    ? installMeta.files
+      .map((entry) => (typeof entry === 'string' ? entry : entry?.p))
+      .filter((entry) => typeof entry === 'string')
+    : [];
+  const piInspection = await inspectProjectImportant({ projectRoot, config });
+  const piWiring = await inspectProjectImportantWiring(projectRoot, { trackedPaths });
+  const projectImportant = {
+    state: piInspection.state,
+    codePointCount: piInspection.codePointCount,
+    oversized: piInspection.oversized,
+    wiring: {
+      claude: piWiring.claude.wired,
+      omp: piWiring.omp.installed ? piWiring.omp.wired : undefined,
+      codex: piWiring.codex.installed ? piWiring.codex.wired : undefined,
+      opencode: piWiring.opencode.installed ? piWiring.opencode.wired : undefined,
+    },
+  };
+
   return {
     version: config.version,
     projectName: projectContext.project.name,
@@ -176,14 +200,43 @@ export async function buildStatusReport(projectRoot) {
     ),
     defaultModel: config.router.defaultModel,
     advisorEnabled: Boolean(config.router.advisorEnabled),
+    projectImportant,
   };
 }
 
+const PROJECT_IMPORTANT_STATE_LABELS = {
+  ready: (pi) => `ready / ${pi.codePointCount.toLocaleString('en-US')} of 6,000 code points`,
+  oversized: () => 'oversized / >6,000 code points / injects first 6,000',
+  empty: () => 'empty / not injected',
+  missing: () => 'missing / not injected',
+  'invalid-utf8': () => 'invalid UTF-8 / not injected',
+  'unsafe-control': () => 'unsupported control characters / not injected',
+  'secret-blocked': () => 'secret-blocked / not injected',
+  'unsafe-type': () => 'unsafe symlink / not injected',
+  unreadable: () => 'unreadable / not injected',
+};
+
+function formatProjectImportantRules(pi) {
+  const formatter = PROJECT_IMPORTANT_STATE_LABELS[pi?.state] ?? (() => 'unreadable / not injected');
+  return formatter(pi);
+}
+
+function formatProjectImportantWiring(pi) {
+  const mark = (wired) => (wired ? '✓' : '✗');
+  const parts = [`Claude runtime ${mark(pi.wiring.claude)}`];
+  if (pi.wiring.omp !== undefined) parts.push(`omp runtime ${mark(pi.wiring.omp)}`);
+  if (pi.wiring.codex !== undefined) parts.push(`Codex fallback ${mark(pi.wiring.codex)}`);
+  if (pi.wiring.opencode !== undefined) parts.push(`OpenCode fallback ${mark(pi.wiring.opencode)}`);
+  return parts.join(' / ');
+}
+
 export function formatStatusReport(report) {
   return [
     `UKit v${report.version} — Status`,
     '─────────────────────',
     `${padLabel('Project')} ${report.projectName}`,
+    `${padLabel('Project rules')} ${formatProjectImportantRules(report.projectImportant)}`,
+    `${padLabel('Rule wiring')} ${formatProjectImportantWiring(report.projectImportant)}`,
     `${padLabel('Adapters')} ${report.adapters.join(', ')}`,
     `${padLabel('Memory items')} ${report.memoryCounts.projectCount} project / ${report.memoryCounts.sessionCount} session / ${report.memoryCounts.userCount} user`,
     `${padLabel('Last compact')} ${report.lastCompact}`,
@@ -191,7 +244,8 @@ export function formatStatusReport(report) {
     `${padLabel('Compact lanes')} ${report.compactLanes}`,
     `${padLabel('Ctx pressure')} ${report.contextPressure}`,
     `${padLabel('Threshold cmp')} ${report.thresholdCompact}`,
-    `${padLabel('Prompt cache')} ${report.promptCache}`,
+    `${padLabel('Local p-cache')} ${report.promptCache}`,
+    `${padLabel('Provider cache')} unknown (host telemetry unavailable)`,
     `${padLabel('Cache lanes')} ${report.cacheLanes}`,
     `${padLabel('Output comp.')} ${report.outputCompression}`,
     `${padLabel('Output lanes')} ${report.outputLanes}`,

package/src/core/uninstall.js

@@ -2,12 +2,154 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
   cleanupEmptyParents,
+  copyFileRawExclusive,
   readJsonIfExists,
   removeLinkOrDir,
   removeLinkOnly,
   resolveProjectRelativePath,
 } from './fileOps.js';
 import { removeGitignoreBlock } from './ensureGitignore.js';
+import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
+
+// PROJECT_IMPORTANT.md is owner content, never UKit-managed. It must NEVER appear
+// in ALLOWED_UNINSTALL_PREFIXES and is never deleted/renamed/chmodded/rewritten/
+// tracked/followed. Before any destructive uninstall step a regular source gets a
+// raw-byte backup beside it at the project root (never under .claude/.ukit/.codex/
+// .omp — those may be deleted): `<name>.ukit-backup`, then `.ukit-backup.1`, `.2`, …
+// via bounded exclusive-create collision walk. See docs/PROJECT_IMPORTANT_SPEC.md §15.
+const IMPORTANT_BACKUP_SUFFIX = '.ukit-backup';
+const IMPORTANT_BACKUP_COLLISION_LIMIT = 100;
+
+function importantBackupCandidateName(index) {
+  return index === 0
+    ? `${PROJECT_IMPORTANT_FILENAME}${IMPORTANT_BACKUP_SUFFIX}`
+    : `${PROJECT_IMPORTANT_FILENAME}${IMPORTANT_BACKUP_SUFFIX}.${index}`;
+}
+
+// Read-only inspection used by BOTH dry-run and real runs: resolves which backup
+// candidate would be used without creating anything. An existing backup whose
+// bytes already match the source is reused; a different-bytes or non-regular
+// occupant pushes the walk to the next suffix. Nothing is ever overwritten.
+async function planImportantBackup(projectRoot) {
+  const sourcePath = path.join(projectRoot, PROJECT_IMPORTANT_FILENAME);
+  const plan = {
+    sourcePath,
+    sourceBytes: null,
+    sourceExists: false,
+    sourceIsRegular: false,
+    wouldBackup: false,
+    backupPath: null,
+    reused: false,
+    exhausted: false,
+    preservedPaths: [],
+    backupWarnings: [],
+  };
+
+  let stat;
+  try {
+    stat = await fs.lstat(sourcePath); // lstat: never follow a source symlink
+  } catch {
+    return plan; // no source — nothing to preserve or back up
+  }
+  plan.sourceExists = true;
+  plan.preservedPaths.push(sourcePath);
+
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    // Symlink/non-regular source: never followed or copied — preserved in place.
+    plan.backupWarnings.push(
+      `[UKit] ${PROJECT_IMPORTANT_FILENAME} is not a regular file; preserved in place without a backup. Run \`ukit doctor\`.`,
+    );
+    return plan;
+  }
+  plan.sourceIsRegular = true;
+  plan.sourceBytes = await fs.readFile(sourcePath); // raw bytes, no decode
+
+  for (let index = 0; index <= IMPORTANT_BACKUP_COLLISION_LIMIT; index += 1) {
+    const candidatePath = path.join(projectRoot, importantBackupCandidateName(index));
+    let candidateStat;
+    try {
+      candidateStat = await fs.lstat(candidatePath);
+    } catch {
+      candidateStat = null;
+    }
+    if (!candidateStat) {
+      plan.wouldBackup = true;
+      plan.backupPath = candidatePath;
+      return plan;
+    }
+    if (candidateStat.isFile() && !candidateStat.isSymbolicLink()) {
+      const existingBytes = await fs.readFile(candidatePath).catch(() => null);
+      if (existingBytes && existingBytes.equals(plan.sourceBytes)) {
+        plan.backupPath = candidatePath;
+        plan.reused = true;
+        return plan;
+      }
+    }
+    // different bytes or non-regular — try next suffix
+  }
+
+  plan.exhausted = true;
+  return plan;
+}
+
+// Real-run backup: byte-identical raw copy via exclusive create (COPYFILE_EXCL —
+// never overwrites). EEXIST means the slot filled between plan and copy; the walk
+// re-checks it (equal bytes → reuse, else next suffix). Any other failure cleans
+// up a possible partial copy and ABORTS uninstall before managed deletion.
+async function createImportantBackup(projectRoot, sourcePath, sourceBytes) {
+  for (let index = 0; index <= IMPORTANT_BACKUP_COLLISION_LIMIT; index += 1) {
+    const candidatePath = path.join(projectRoot, importantBackupCandidateName(index));
+    let candidateStat;
+    try {
+      candidateStat = await fs.lstat(candidatePath);
+    } catch {
+      candidateStat = null;
+    }
+    if (candidateStat) {
+      if (candidateStat.isFile() && !candidateStat.isSymbolicLink()) {
+        const existingBytes = await fs.readFile(candidatePath).catch(() => null);
+        if (existingBytes && existingBytes.equals(sourceBytes)) {
+          return candidatePath; // reused — already byte-identical
+        }
+      }
+      continue;
+    }
+    try {
+      await copyFileRawExclusive(sourcePath, candidatePath); // preserves mode where supported
+      return candidatePath;
+    } catch (error) {
+      if (error?.code === 'EEXIST') {
+        // Lost the race — the slot now exists. Reuse it when its bytes match the
+        // source; otherwise advance to the next suffix.
+        try {
+          const racedStat = await fs.lstat(candidatePath);
+          if (racedStat.isFile() && !racedStat.isSymbolicLink()) {
+            const racedBytes = await fs.readFile(candidatePath).catch(() => null);
+            if (racedBytes && racedBytes.equals(sourceBytes)) {
+              return candidatePath;
+            }
+          }
+        } catch {
+          // vanished again — either way, move on
+        }
+        continue;
+      }
+      try {
+        await fs.rm(candidatePath, { force: true }); // clean partial backup
+      } catch {
+        // best-effort cleanup only
+      }
+      // Error carries no source content — only the failing operation.
+      throw new Error(
+        `[UKit] Uninstall aborted: could not back up ${PROJECT_IMPORTANT_FILENAME} (${error?.code || error?.message}). Managed paths were not removed.`,
+        { cause: error },
+      );
+    }
+  }
+  throw new Error(
+    `[UKit] Uninstall aborted: no free backup name for ${PROJECT_IMPORTANT_FILENAME} after ${IMPORTANT_BACKUP_COLLISION_LIMIT} collisions. Managed paths were not removed.`,
+  );
+}
 
 // Use lstat (not access) so broken symlinks are also detected as existing.
 async function pathExistsLstat(targetPath) {
@@ -254,13 +396,42 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     );
   }
 
+  // PROJECT_IMPORTANT.md preservation — read-only plan first (spec §15). The
+  // source is never touched: only inspected via lstat + readFile.
+  const importantPlan = await planImportantBackup(projectRoot);
+
   if (dryRun) {
-    // Use lstat (not access) so broken symlinks are included in the report.
+    // Dry run creates nothing: report the collision-resolved candidate and the
+    // preserved/refused state only. lstat (not access) keeps broken symlinks visible.
     const wouldRemove = [];
     for (const { abs } of safeEntries) {
       if (await pathExistsLstat(abs)) wouldRemove.push(abs);
     }
-    return { removed: 0, attempted: allEntries.length, wasInstalled: true, wouldRemove, skippedSymlinkParents };
+    return {
+      removed: 0,
+      attempted: allEntries.length,
+      wasInstalled: true,
+      wouldRemove,
+      wouldBackup: importantPlan.wouldBackup,
+      backupPaths: importantPlan.backupPath ? [importantPlan.backupPath] : [],
+      preservedPaths: importantPlan.preservedPaths,
+      backupWarnings: importantPlan.backupWarnings,
+      skippedSymlinkParents,
+    };
+  }
+
+  // Backup runs BEFORE any destructive step. A failure here aborts uninstall —
+  // managed paths stay intact and the source is never modified.
+  const backupPaths = [];
+  if (importantPlan.wouldBackup) {
+    const backupPath = await createImportantBackup(
+      projectRoot,
+      importantPlan.sourcePath,
+      importantPlan.sourceBytes,
+    );
+    backupPaths.push(backupPath);
+  } else if (importantPlan.backupPath && importantPlan.reused) {
+    backupPaths.push(importantPlan.backupPath); // existing byte-identical backup
   }
 
   // Remove all paths in parallel
@@ -289,5 +460,14 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     await cleanupEmptyParents(removedPath, projectRoot);
   }
 
-  return { removed, attempted: allEntries.length, wasInstalled: true, skippedSymlinkParents };
+  return {
+    removed,
+    attempted: allEntries.length,
+    wasInstalled: true,
+    wouldBackup: importantPlan.wouldBackup,
+    backupPaths,
+    preservedPaths: importantPlan.preservedPaths,
+    backupWarnings: importantPlan.backupWarnings,
+    skippedSymlinkParents,
+  };
 }

package/src/diagnostics/classifyHang.js

@@ -0,0 +1,246 @@
+// classifyHang.js — evidence-only hang classifier for the C19 liveness wave (TASK-032).
+//
+// What this is for: C19 removed a family of unbounded paths, and the remaining failure
+// mode is telling ONE stall class apart from another. A prompt freeze used to be
+// indistinguishable from an indexing freeze or a gateway stall, so operators had no
+// evidence-based next step. This module turns an evidence bundle into exactly one
+// declared lane, or `unknown` when the evidence cannot prove any of them.
+//
+// Contracts (asserted by tests/liveness/classifyHang.test.js):
+//   * PURE and CLOCK-FREE. Every rule is a function of the bundle only, so identical
+//     evidence always produces byte-identical output. No Date.now(), no randomness, no
+//     I/O — the caller supplies both the measurement and the clock.
+//   * NEVER GUESSES. A lane is only named when the evidence PROVES it:
+//       - `deadline` with zero survivors is a clean reap, not a process-tree leak;
+//       - survivors beside `failureKind: 'signal'` are NOT a leak: `signal` is documented
+//         by the runner as a signal IT DID NOT SEND, so there is no escalation to blame
+//         and the bundle is `unknown` (the runner's own `deadline` verdict is the only
+//         escalation proof);
+//       - a non-zero hook exit that finished inside its budget is a verdict, not a hang;
+//       - a non-typed index error is not a discovery deadline.
+//     Everything else is `unknown` with a concrete next check.
+//   * The UPSTREAM lane is never a hook. Stream idle with no hook active classifies
+//     `gateway-stream-idle`; the presence of hook evidence removes that lane entirely, so
+//     a gateway stall can no longer be reported as UKit's fault (or the reverse).
+//   * Exactly four fields, always: `{class, confidence, evidenceIds, recommendedNextCheck}`.
+//     `evidenceIds` names the fields the decision rests on, so a reviewer can re-derive it.
+
+/**
+ * The six declared stall lanes. One bundle resolves to at most one of these.
+ * Ordered by decision precedence (see LANE_PRECEDENCE) — the first lane whose evidence
+ * is present AND conclusive owns the classification.
+ */
+export const HANG_CLASSES = Object.freeze([
+  'process-tree-leak',
+  'hook-overrun',
+  'index-deadline',
+  'lock-contention',
+  'context-capacity',
+  'gateway-stream-idle',
+]);
+
+/** The explicit "could not prove a lane" result. Never a member of HANG_CLASSES. */
+export const UNKNOWN_CLASS = 'unknown';
+
+/**
+ * Evidence kinds a bundle may carry. Exported so callers and diagnostics can enumerate
+ * what the classifier understands instead of guessing at field names.
+ */
+export const EVIDENCE_KINDS = Object.freeze([
+  'hook-telemetry',
+  'hook-active',
+  'process-result',
+  'index-error',
+  'lock-outcome',
+  'context-capacity',
+  'stream-idle',
+]);
+
+// Hook-runner outcomes that PROVE the runner ended the child (TASK-018 taxonomy). These
+// are kill verdicts, so they name a lane; `ok` / `exit-code` are verdicts about the hook's
+// own decision and prove nothing about liveness.
+const KILL_OUTCOMES = new Set(['timeout', 'output-overflow', 'budget-exhausted']);
+
+// A leak only exists AFTER the runner's OWN escalation attempt, and only if something is
+// still alive. `failureKind: 'deadline'` is the runner's kill verdict — the deadline timer
+// armed the TERM → KILL sequence, so survivors beside it really are an escapee (H03).
+//
+// `signal` is explicitly NOT escalation evidence: the runner documents it as "the child
+// died from a signal this runner did not send" (hook-process.mjs), which is an unprompted
+// EXTERNAL kill. Survivors beside an external signal may be unrelated processes, and naming
+// a lane off it would fabricate a TERM → KILL diagnosis the evidence cannot support. Such a
+// bundle is `unknown`, never `process-tree-leak`.
+const RUNNER_ESCALATION_KINDS = new Set(['deadline']);
+
+const UNKNOWN_CHECK = 'Collect hook telemetry, process-exit evidence, or an index/lock/context measurement for this stall — none of the current evidence proves a lane.';
+
+const NEXT_CHECK = Object.freeze({
+  'process-tree-leak': 'Re-run the failing command with the process-tree runner and list the surviving PIDs: a process group survived its TERM→KILL escalation (check for a child that ignores or detaches from SIGTERM).',
+  'hook-overrun': 'Inspect the cited hook telemetry row: the hook was killed at its deadline or overflowed its output cap. Measure that hook alone and reduce its work below its budget.',
+  'index-deadline': 'Re-run discovery with a bounded deadline and inspect the recorded phase: git enumeration or the filesystem fallback consumed the whole budget.',
+  'lock-contention': 'Inspect the lock holder state for the named target: the acquisition budget expired or was aborted before the critical section ran (fail-closed, no mutation happened).',
+  'context-capacity': 'Re-check the negotiated context capacity against the estimate: the session reached its advisory cap, so compaction must run before more context is added.',
+  'gateway-stream-idle': 'Watch the stream idle window: no hook was active while the stream went silent, so treat this as an upstream/gateway stall and verify CLAUDE_STREAM_IDLE_TIMEOUT_MS and the non-streaming fallback.',
+});
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isPositiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function resultFor(cls, confidence, evidenceIds, recommendedNextCheck) {
+  return { class: cls, confidence, evidenceIds, recommendedNextCheck };
+}
+
+function unknown(evidenceIds = []) {
+  return resultFor(UNKNOWN_CLASS, 'none', evidenceIds, UNKNOWN_CHECK);
+}
+
+// ─── per-lane evidence evaluators ────────────────────────────────────────────
+// Each returns { evidenceIds, confidence } when the evidence PROVES the lane, else null.
+
+function detectProcessTreeLeak(bundle) {
+  const processResult = bundle.processResult;
+  if (!isObject(processResult)) return null;
+  const survivors = processResult.survivors;
+  // `survivors` must be an explicit, non-empty array: a missing field is unknown
+  // evidence (the caller never probed), and an empty array is a clean reap.
+  if (!Array.isArray(survivors) || survivors.length === 0) return null;
+  // Survivors alone proves nothing — the runner must have escalated. `signal` is an
+  // external kill, so it stays `unknown` rather than claiming a leak.
+  if (!RUNNER_ESCALATION_KINDS.has(processResult.failureKind)) return null;
+  return { evidenceIds: ['process-result'], confidence: 'high' };
+}
+
+function detectHookOverrun(bundle) {
+  const rows = bundle.hookTelemetry;
+  if (!Array.isArray(rows)) return null;
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i];
+    if (isObject(row) && KILL_OUTCOMES.has(row.outcome)) {
+      // Cite only the failing row — the row index is the evidence locator.
+      return { evidenceIds: [`hook-telemetry[${i}]`], confidence: 'high' };
+    }
+  }
+  return null;
+}
+
+function detectIndexDeadline(bundle) {
+  const indexError = bundle.indexError;
+  if (!isObject(indexError)) return null;
+  // Only the typed liveness failure is proof; a message alone could be anything.
+  const typed = indexError.name === 'IndexDiscoveryTimeoutError'
+    || indexError.code === 'INDEX_DISCOVERY_TIMEOUT';
+  if (!typed) return null;
+  return { evidenceIds: ['index-error'], confidence: 'high' };
+}
+
+function detectLockContention(bundle) {
+  const lockOutcome = bundle.lockOutcome;
+  if (!isObject(lockOutcome) || lockOutcome.ok !== false) return null;
+  // TASK-028's typed envelope: the callback never ran, so no mutation was lost.
+  if (lockOutcome.reason !== 'busy' && lockOutcome.reason !== 'aborted') return null;
+  return { evidenceIds: ['lock-outcome'], confidence: 'high' };
+}
+
+function detectContextCapacity(bundle) {
+  const context = bundle.context;
+  if (!isObject(context)) return null;
+  const capTokens = context.capTokens;
+  const estimatedTokens = context.estimatedTokens;
+  if (!isPositiveNumber(capTokens) || !isPositiveNumber(estimatedTokens)) return null;
+  if (estimatedTokens < capTokens) return null;
+  return { evidenceIds: ['context-capacity'], confidence: 'high' };
+}
+
+function detectGatewayStreamIdle(bundle) {
+  const stream = bundle.stream;
+  if (!isObject(stream)) return null;
+  const idleMs = stream.idleMs;
+  const idleTimeoutMs = stream.idleTimeoutMs;
+  // Both numbers are required: without the negotiated timeout there is nothing to
+  // compare against, and an idle duration alone proves no stall.
+  if (!isPositiveNumber(idleMs) || !isPositiveNumber(idleTimeoutMs)) return null;
+  if (idleMs < idleTimeoutMs) return null;
+  // A hook was active while the stream was silent → the silence may be UKit's, so the
+  // upstream lane is removed entirely. Never blame the gateway over hook evidence.
+  // `null`/`undefined` both mean "no hook was active" — only a real value withholds it.
+  if (bundle.hookActive !== null && bundle.hookActive !== undefined) return null;
+  return { evidenceIds: ['stream-idle'], confidence: 'high' };
+}
+
+// Precedence: the most specific, evidence-backed lane wins. The upstream lane is LAST —
+// it is the only lane whose proof is the ABSENCE of other evidence, so it may only be
+// reached once every hook/index/lock/context claim had its chance.
+const LANE_PRECEDENCE = Object.freeze([
+  ['process-tree-leak', detectProcessTreeLeak],
+  ['hook-overrun', detectHookOverrun],
+  ['index-deadline', detectIndexDeadline],
+  ['lock-contention', detectLockContention],
+  ['context-capacity', detectContextCapacity],
+  ['gateway-stream-idle', detectGatewayStreamIdle],
+]);
+
+// Evidence that was considered but is NOT sufficient to name a lane. Reported on the
+// `unknown` result so a caller sees what was looked at, never just "nothing".
+function inconclusiveEvidenceIds(bundle) {
+  const ids = [];
+  if (Array.isArray(bundle.hookTelemetry) && bundle.hookTelemetry.length > 0) {
+    ids.push('hook-telemetry');
+  }
+  if (isObject(bundle.hookActive)) ids.push('hook-active');
+  if (isObject(bundle.stream)) ids.push('stream-idle');
+  if (isObject(bundle.processResult)) ids.push('process-result');
+  if (isObject(bundle.indexError)) ids.push('index-error');
+  if (isObject(bundle.lockOutcome)) ids.push('lock-outcome');
+  if (isObject(bundle.context)) ids.push('context-capacity');
+  return ids;
+}
+
+/**
+ * Classify ONE stall from an evidence bundle.
+ *
+ * @param {object} [bundle] evidence collected by a scenario or a live diagnostic:
+ *   `hookTelemetry`  — redacted telemetry rows (TASK-019 schema; `outcome` is the
+ *                      runner's taxonomy, `hook` names the emitter).
+ *   `hookActive`     — `{hook, activeMs}` when a hook held the hot path. Presence alone
+ *                      removes the upstream lane.
+ *   `processResult`  — `{failureKind, signal, code, elapsedMs, survivors}` from the
+ *                      process-tree runner. `survivors` is the escalation probe.
+ *   `indexError`     — the thrown error (or its shape) from index discovery.
+ *   `lockOutcome`    — the typed `{ok:false, reason:'busy'|'aborted', waitedMs}` envelope.
+ *   `context`        — `{capTokens, estimatedTokens, ...}` from capacity negotiation.
+ *   `stream`         — `{idleMs, idleTimeoutMs, ...}` from stream timing.
+ * @returns {{ class: string, confidence: 'high'|'none', evidenceIds: string[],
+ *             recommendedNextCheck: string }} exactly four fields; `class` is either a
+ *   member of HANG_CLASSES or UNKNOWN_CLASS.
+ */
+export function classifyHang(bundle = {}) {
+  if (!isObject(bundle)) return unknown();
+
+  for (const [lane, detect] of LANE_PRECEDENCE) {
+    const evidence = detect(bundle);
+    if (evidence) return resultFor(lane, evidence.confidence, evidence.evidenceIds, NEXT_CHECK[lane]);
+  }
+
+  return unknown(inconclusiveEvidenceIds(bundle));
+}
+
+/**
+ * C19 finding → lane map. Every finding this cycle addressed has a lane whose evidence a
+ * scenario in `tests/liveness/hangScenarios.test.js` produces, so no finding is left
+ * without a classifier answer. Exposed as data (not prose) so the liveness suite can fail
+ * when coverage regresses.
+ */
+export const C19_LANE_MAP = Object.freeze([
+  Object.freeze({ findings: Object.freeze(['H01', 'H02', 'H05', 'H08', 'H21']), lane: 'hook-overrun' }),
+  Object.freeze({ findings: Object.freeze(['H03']), lane: 'process-tree-leak' }),
+  Object.freeze({ findings: Object.freeze(['H09', 'H10', 'H11', 'H12', 'H13', 'H14', 'H15']), lane: 'index-deadline' }),
+  Object.freeze({ findings: Object.freeze(['H16', 'H17', 'H18', 'H19', 'H20']), lane: 'lock-contention' }),
+  Object.freeze({ findings: Object.freeze(['H04', 'H22']), lane: 'context-capacity' }),
+  Object.freeze({ findings: Object.freeze(['H23', 'H24']), lane: 'hook-overrun' }),
+  Object.freeze({ findings: Object.freeze(['H25']), lane: 'gateway-stream-idle' }),
+]);