@ngockhoale/ukit 2.4.2 → 2.4.3

package/manifests/platform.full.yaml

@@ -1059,7 +1059,7 @@ items:
     sourceTemplate: .claude/hooks/record-execution.sh
     targetPath: .claude/hooks/record-execution.sh
     requires:
-      - ukit-runtime-execution-ledger-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1071,7 +1071,7 @@ items:
     sourceTemplate: .claude/hooks/completion-gate.sh
     targetPath: .claude/hooks/completion-gate.sh
     requires:
-      - ukit-runtime-execution-ledger-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1139,7 +1139,7 @@ items:
     targetPath: .claude/hooks/skill-router.sh
     requires:
       - ukit-index-route-catalog-script
-      - ukit-runtime-compact-threshold-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1164,7 +1164,7 @@ items:
     sourceTemplate: .claude/hooks/context-hardcap-gate.sh
     targetPath: .claude/hooks/context-hardcap-gate.sh
     requires:
-      - ukit-runtime-compact-threshold-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1204,10 +1204,16 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-task-watchdog-script
+  # One directory item ships the whole runtime dir. autoDiscoverTemplates:false silently
+  # skips any template file without an explicit item, which is exactly how later-wave
+  # runtime modules (async-lock.mjs, hook-process.mjs, transcript-tail.mjs, hook-input.*)
+  # never reached installed projects and broke execution-ledger.mjs imports at hook time.
+  # A directory scan keeps every new runtime module shipping without a manifest edit; the
+  # walker preserves per-file modes (hook-input.sh keeps its exec bit).
+  - id: ukit-runtime-scripts
     type: config
-    sourceTemplate: .claude/ukit/runtime/task-watchdog.mjs
-    targetPath: .claude/ukit/runtime/task-watchdog.mjs
+    sourceTemplate: .claude/ukit/runtime
+    targetPath: .claude/ukit/runtime
     requires: []
     mergeStrategy: overwrite_with_backup
     variables: []
@@ -1231,7 +1237,7 @@ items:
     sourceTemplate: .claude/hooks/compress-output.sh
     targetPath: .claude/hooks/compress-output.sh
     requires:
-      - ukit-runtime-output-compression-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1273,58 +1279,12 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-text-profile-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/text-profile.mjs
-    targetPath: .claude/ukit/runtime/text-profile.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-execution-ledger-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/execution-ledger.mjs
-    targetPath: .claude/ukit/runtime/execution-ledger.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-hook-chain-runner-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/hook-chain-runner.mjs
-    targetPath: .claude/ukit/runtime/hook-chain-runner.mjs
-    requires: []
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-safe-patch-core-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs
-    targetPath: .claude/ukit/runtime/safe-patch-core.mjs
-    requires:
-      - ukit-runtime-text-profile-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: ukit-index-anchor-search-script
     type: config
     sourceTemplate: .claude/ukit/index/anchor-search.mjs
     targetPath: .claude/ukit/index/anchor-search.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1348,8 +1308,7 @@ items:
     sourceTemplate: .claude/ukit/index/provision-worktree.mjs
     targetPath: .claude/ukit/index/provision-worktree.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1361,8 +1320,7 @@ items:
     sourceTemplate: .claude/ukit/index/stale-spec-check.mjs
     targetPath: .claude/ukit/index/stale-spec-check.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1374,8 +1332,7 @@ items:
     sourceTemplate: .claude/ukit/index/pre-edit-backup.mjs
     targetPath: .claude/ukit/index/pre-edit-backup.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1387,8 +1344,7 @@ items:
     sourceTemplate: .claude/ukit/index/post-edit-verify.mjs
     targetPath: .claude/ukit/index/post-edit-verify.mjs
     requires:
-      - ukit-runtime-text-profile-script
-      - ukit-runtime-safe-patch-core-script
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1549,54 +1505,6 @@ items:
     packs:
       - core
 
-  - id: ukit-runtime-token-utils-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/token-utils.mjs
-    targetPath: .claude/ukit/runtime/token-utils.mjs
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-compact-threshold-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/compact-threshold.mjs
-    targetPath: .claude/ukit/runtime/compact-threshold.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-reinject-context-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/reinject-context.mjs
-    targetPath: .claude/ukit/runtime/reinject-context.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-      - ukit-runtime-compact-threshold-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
-  - id: ukit-runtime-output-compression-script
-    type: config
-    sourceTemplate: .claude/ukit/runtime/output-compression.mjs
-    targetPath: .claude/ukit/runtime/output-compression.mjs
-    requires:
-      - ukit-runtime-token-utils-script
-      - ukit-runtime-compact-threshold-script
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: ukit-index-reset-auto-permissions-script
     type: config
     sourceTemplate: .claude/ukit/index/reset-auto-permissions.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",
     "test": "vitest run",
+    "test:liveness": "vitest run tests/liveness/",
     "test:watch": "vitest"
   },
   "engines": {

package/scripts/index/refresh-index.mjs

@@ -19,39 +19,64 @@ const changedFiles = changedArg
 
 const force = readBooleanFlag(args, '--force');
 const lastRefreshMs = await getLastRefreshTime(rootDir);
-const staleness = force
-  ? null
-  : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
-const stale = force || staleness.stale;
 
-if (!stale) {
-  console.log('[index:refresh] skipped (cache fresh)');
-  if (lastRefreshMs !== null) {
-    console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
-  }
-  if (changedFiles.length > 0) {
-    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  }
-  console.log(`root: ${rootDir}`);
-} else {
-  // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
-  const summary = await buildCodeIndex({
-    rootDir,
-    discoverySnapshot: staleness ? staleness.snapshot : null,
-  });
+if (changedFiles.length > 0 && !force) {
+  // Hints carry the change set, so no staleness enumeration is needed:
+  // buildCodeIndex merges the hinted paths into the existing artifacts and
+  // falls back to the bounded full discovery path on its own when the hints
+  // are unsafe or the previous artifacts cannot be merged (TASK-023).
+  const summary = await buildCodeIndex({ rootDir, changedFiles });
 
   console.log('[index:refresh] completed');
+  console.log(`mode: ${summary.mode}`);
   if (lastRefreshMs !== null) {
     console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
   }
-  if (changedFiles.length > 0) {
-    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  }
+  console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
   console.log(`root: ${rootDir}`);
   console.log(`files: ${summary.fileCount}`);
   console.log(`parsed: ${summary.parsedCodeFileCount}`);
   console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (summary.removedFiles.length > 0) {
+    console.log(`removed: ${summary.removedFiles.length}`);
+  }
   console.log(`indexDir: ${summary.indexDir}`);
+} else {
+  const staleness = force
+    ? null
+    : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+  const stale = force || staleness.stale;
+
+  if (!stale) {
+    console.log('[index:refresh] skipped (cache fresh)');
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    if (changedFiles.length > 0) {
+      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    }
+    console.log(`root: ${rootDir}`);
+  } else {
+    // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
+    const summary = await buildCodeIndex({
+      rootDir,
+      discoverySnapshot: staleness ? staleness.snapshot : null,
+    });
+
+    console.log('[index:refresh] completed');
+    console.log(`mode: ${summary.mode}`);
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    if (changedFiles.length > 0) {
+      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    }
+    console.log(`root: ${rootDir}`);
+    console.log(`files: ${summary.fileCount}`);
+    console.log(`parsed: ${summary.parsedCodeFileCount}`);
+    console.log(`reused: ${summary.reusedCodeFileCount}`);
+    console.log(`indexDir: ${summary.indexDir}`);
+  }
 }
 
 function readFlagValue(argv, flag) {

package/src/core/compact/threshold.js

@@ -1,4 +1,11 @@
 import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
+// The installed runtime is the single implementation of capacity negotiation; this source
+// twin consumes it rather than re-deriving the precedence rules. Both files ship together.
+import {
+  readContextCapacityRecord,
+  SOFT_TO_CAP_RATIO,
+} from '../../../templates/.claude/ukit/runtime/compact-threshold.mjs';
+import { resolveContextCapTokens } from '../../../templates/.claude/ukit/runtime/context-capacity.mjs';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
@@ -436,22 +443,45 @@ function computeEstimatedTotalTokens({
   return baselineTokens + estimatedContextTokens + windowTokens + sessionExcess;
 }
 
+// The record the advisory guard published for this project, or null when nothing has been
+// negotiated yet (fresh install, non-project caller, tests).
+function readNegotiatedCapacity(config = {}) {
+  const record = readContextCapacityRecord(config?.projectRoot);
+  if (!record) return null;
+  return resolveContextCapTokens({
+    env: process.env,
+    config,
+    modelMetadata: { model: record.model },
+  });
+}
+
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(
-    1,
-    finiteNumber(config?.compact?.tokenThreshold, loadShippedCompactBudget().tokenThreshold),
+  const shippedHardCap = positiveInteger(
+    config?.compact?.hardCapTokens,
+    loadShippedCompactBudget().hardCapTokens,
   );
+  const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
+  // Negotiated capacity (H22): the guard publishes what it derived from the live route and
+  // this shared path consumes it; without a record the shipped tuning applies unchanged.
+  const negotiated = readNegotiatedCapacity(config);
+  const hardCapTokens = negotiated
+    ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
+    : shippedHardCap;
+  // An explicit operator tokenThreshold is honored as-is; otherwise the advisory phase is
+  // derived from the negotiating cap so it can never sit above the cap it precedes.
+  const softThreshold = explicitSoftThreshold > 0
+    ? Math.max(1, explicitSoftThreshold)
+    : Math.max(1, Math.round(hardCapTokens * SOFT_TO_CAP_RATIO));
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
-  // Keep the source mirror's config contract aligned with the installed runtime: malformed
-  // caps fall back to a safe ceiling rather than turning every mutation into an over-cap call.
-  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, loadShippedCompactBudget().hardCapTokens);
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
     hardCapTokens,
+    capacitySource: negotiated?.capacity?.source ?? 'shipped',
+    capacityTokens: negotiated?.capacity?.tokens ?? null,
   };
 }
 

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' }),
+]);