@ngockhoale/ukit 2.4.1 → 2.4.3

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to UKit are documented here.
 
+## 2.4.2 - 2026-09-16
+
+Fix: the gateway resilience posture disabled the only recovery path a buffering gateway
+leaves open — the direct client-side cause of the recurring "session stands still mid-turn
+until the user interrupts and re-prompts" freeze. Live probes of the stall-class gateway on
+2026-09-16 proved the full chain: the gateway still buffers entire streams (a 16-token
+probe returned 23 SSE events in ONE body read), so a long generation is silent until it
+finishes; the non-streaming route is healthy (HTTP 200 + valid Anthropic Message); and the
+managed env shipped since 2.3.16 kept the non-streaming fallback DISABLED with a 10-minute
+stream-idle watchdog — meaning the client sat in dead air and, on abort, had no recovery
+path at all. The managed posture now flips to fail-fast-and-recover.
+
+- **Posture flip** (`src/core/gatewayResilienceEnv.js`): `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`
+  managed default `'1'` → `'0'` (fallback stays enabled — on a buffering gateway a
+  non-streaming POST is the one request shape without an idle watchdog), and
+  `CLAUDE_STREAM_IDLE_TIMEOUT_MS` `'600000'` → `'120000'` (a silent stream aborts after
+  2 minutes and recovers via the healthy non-streaming route instead of hanging for 10).
+  Values equal to the previously shipped defaults are UKit's own earlier writes and are
+  migrated on the next `ukit install` (new `GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS` map +
+  `migrated` report field, backup written as usual); genuinely user-tuned values are still
+  never touched.
+- **Probe misdiagnosis fixed** (`src/core/gatewayProbe.js`): the probe 404'd healthy
+  alias-based gateways because it POSTed the built-in default `claude-sonnet-4-5`, which is
+  not provisioned there ("No active credentials for provider: claude", `model_not_found`,
+  reproduced live) while real sessions run on the `ANTHROPIC_DEFAULT_*_MODEL` lane aliases.
+  The probe now resolves `ANTHROPIC_MODEL` → `ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL`
+  before the built-in default and reports the probed model. `anthropic-version` is now sent
+  for the Bearer scheme too (live-verified accepted), and the API key is resolved through
+  the same 3-tier order as the base URL (env → project settings → home settings) so plain
+  terminals no longer probe keyless (`resolveGatewayApiKey`).
+- **request-id re-classified** (same file, `docs/GATEWAY.md` §3): a missing `request-id`
+  on an HTTP 200 + valid Anthropic Message is an advisory hint, not a FAIL — the real
+  gateway ships no request-id even on healthy responses and sessions complete fine. The
+  Message-shape hard gate still catches the 888-byte error-envelope class from 2.3.16.
+- **Docs**: `docs/GATEWAY.md` intro/§1/§2/§3/§4/§5 updated for the fail-fast posture,
+  the 2026-09-16 buffering reconfirmation, the legacy-value migration, and the probe's
+  alias-model + key resolution.
+- **Verification**: focused suites green (gatewayProbe 14, gatewayResilienceEnv 23,
+  packageVersion 3); full `yarn test` green; live re-probe after the fix reports the alias
+  model, a healthy non-streaming route, and the still-present buffering signature.
+- **Orphan-leak class closed for the remaining hooks (2.4.1 follow-up)**: the 2.4.1 watchdog
+  shipped in exactly one hook (`skill-router.sh`); the other 18 node-spawning hooks could still
+  orphan a node grandchild to launchd when their work hung (wedged import, stalled mount — this
+  repo lives on an external volume). Every remaining hook now arms the same wall-clock
+  self-deadline: inline heredoc/`node -e` blocks carry
+  `setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref()` directly, wrapper hooks pass
+  `UKIT_HOOK_DEADLINE_MS` (default 3000 ms) and their runtime scripts (`execution-ledger`,
+  `output-compression`, `reinject-context`, `post-edit-verify`, `pre-edit-backup`,
+  `stale-spec-check`) self-exit only when that env var is present, so CLI usage is never
+  self-killed. Lock-mutation blocks with a 5000 ms bounded wait (auto-allow-bash,
+  auto-prune-bash, reset-compact-pressure) use an 8000 ms deadline so the watchdog can never
+  fire while the mutation is legally waiting for the lock.
+  `tests/consistency/hookWatchdogCoverage.test.js` enforces the coverage for every future hook.
+- **Bounded stdin transport for the hook chain (C19 wave 1, H01)**: hook payloads no longer
+  materialize unbounded in a shell variable or the exec environment — the exec-env path that
+  made large PreToolUse payloads fail `exec` outright (E2BIG) on macOS. New
+  `templates/.claude/ukit/runtime/hook-input.sh` (`ukit_stage_hook_input` via `mktemp` +
+  byte-capped `head`, drained producer, overflow policies `truncate`/`temp-file`/`refuse`)
+  and `hook-input.mjs` (streaming reader + CLI) stage every payload to a bounded temp file;
+  all 16 node-spawning wrapper hooks now pass `INPUT_FILE`, never the payload, with a
+  bounded inline fallback when the helper is absent. Sensitive-data-guard overflow is
+  fail-closed (`refuse`, silent exit 2); 32 MiB receipts verified < 10 s.
+
+- Machine-envelope lane in the sensitive-data gate: harness-injected notifications (task-notification / system-reminder / cross-session-message tags) now deliver with a redacted labels/counts advisory instead of being blocked when they quote secret-shaped test fixtures — ends the silent "Waiting for N background agents" stall. User-typed prompts, file/grep/bash channels, allowlist and overflow-refuse posture unchanged (fail-closed, default-ON, never echoes values).
+
 ## 2.4.1 - 2026-09-14
 
 Fix: the skill-router hook could hang the session and leak an orphaned process. `skill-router.sh`

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.1",
+  "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

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import {
   buildCodeIndex,
-  isIndexStale,
+  inspectIndexStaleness,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 
@@ -19,34 +19,64 @@ const changedFiles = changedArg
 
 const force = readBooleanFlag(args, '--force');
 const lastRefreshMs = await getLastRefreshTime(rootDir);
-const stale = force
-  ? true
-  : await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
 
-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 {
-  const summary = await buildCodeIndex({ rootDir });
+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/cli/commands/doctor.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import { pathExists, readJsonIfExists } from '../../core/fileOps.js';
 import { buildPathConfig } from '../../core/paths.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -10,8 +11,13 @@ import { detectProviders } from '../../context/detectProviders.js';
 import { profileSkills } from '../../core/skillProfile.js';
 import {
   resolveGatewayBaseUrl,
+  resolveGatewayApiKey,
   probeGateway,
 } from '../../core/gatewayProbe.js';
+import {
+  GATEWAY_RESILIENCE_ENV_DEFAULTS,
+  scanProfileResilienceEnv,
+} from '../../core/gatewayResilienceEnv.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
@@ -28,7 +34,7 @@ export function printDoctorHelp() {
   console.log('  --gateway       Live gateway probe (streaming + non-streaming); advisory only');
 }
 
-export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
+export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir() }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
     throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: ${SUPPORTED_FLAGS_LIST}`);
@@ -158,6 +164,40 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   if (argv.includes('--gateway')) {
     console.log('');
     console.log('[UKit] Gateway probe (advisory — does not affect exit code):');
+
+    // Per-profile resilience scan. A session launched with
+    // `--settings ~/.claude/profile/<name>.json` bypasses ~/.claude/settings.json, so the
+    // managed keys can be missing exactly where they matter while the main settings file
+    // looks healthy. Advisory only: this never enters `checks` and never touches exitCode.
+    console.log(
+      `[UKit]   Profile resilience scan (advisory) — managed keys: ${Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS).join(', ')}`,
+    );
+    let profileScan = null;
+    try {
+      profileScan = await scanProfileResilienceEnv({ homeDir });
+    } catch {
+      profileScan = null;
+    }
+    if (!profileScan || profileScan.scanned.length === 0) {
+      console.log('[UKit]   -  No profile files found (nothing to check).');
+    } else {
+      for (const entry of profileScan.scanned) {
+        if (entry.missing.length === 0) {
+          console.log(`[UKit]   ✓  ${entry.file}`);
+          continue;
+        }
+        console.log(
+          `[UKit]   ✗  ${entry.file} — ${entry.validJson ? `missing ${entry.missing.join(', ')}` : 'not valid JSON (assuming every managed key missing)'}`,
+        );
+        console.log(
+          `[UKit]      remedy: add ${entry.missing.join(', ')} to the profile's "env" block; see docs/GATEWAY.md`,
+        );
+      }
+      if (profileScan.compliant) {
+        console.log('[UKit]   All scanned profile files carry the managed resilience keys.');
+      }
+    }
+
     let resolved;
     try {
       resolved = await resolveGatewayBaseUrl({ projectRoot });
@@ -168,9 +208,25 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
       console.log('[UKit]   -  Gateway probe skipped — no custom gateway configured (ANTHROPIC_BASE_URL not set in env, project .claude/settings.json, or ~/.claude/settings.json).');
     } else {
       console.log(`[UKit]   baseUrl: ${resolved.baseUrl} (source: ${resolved.source})`);
+      // Plain terminals do not export ANTHROPIC_* (the key lives in settings.json env and is
+      // only injected into Claude Code sessions), so resolve the key through the same 3-tier
+      // order as the baseUrl — otherwise the probe authenticates keyless and misreports.
+      let keyInfo = null;
+      try {
+        keyInfo = await resolveGatewayApiKey({ projectRoot });
+      } catch {
+        keyInfo = null;
+      }
+      if (!keyInfo?.value) {
+        console.log('[UKit]   -  No API key found (env, project settings, home settings) — probe runs unauthenticated and may 401/404.');
+      }
       let result;
       try {
-        result = await probeGateway({ baseUrl: resolved.baseUrl });
+        result = await probeGateway({
+          baseUrl: resolved.baseUrl,
+          apiKey: keyInfo?.value ?? null,
+          apiKeySource: keyInfo?.scheme ?? null,
+        });
       } catch (error) {
         result = null;
         console.log(`[UKit]   ✗  Gateway probe threw: ${error?.message ?? String(error)}`);
@@ -178,6 +234,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
       if (result) {
         const s = result.streaming;
         const n = result.nonStreaming;
+        console.log(`[UKit]   probed model: ${result.model}`);
         const streamingLabel = s.ok
           ? `streaming OK (events=${s.eventsReceived}, chunks=${s.chunks})`
           : `streaming FAIL (events=${s.eventsReceived}, chunks=${s.chunks}, buffered=${s.buffered}${s.error ? `, error=${s.error}` : ''})`;

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,
   };
 }