@ngockhoale/ukit 2.4.2 → 2.5.0

package/templates/.claude/ukit/runtime/async-lock.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// TASK-028: the one async lock utility for hook processes. Every hook lock used to
+// carry its own inline mkdir/owner/backoff copy (auto-allow-bash, verification-guard,
+// token-utils withFileLock, src/core/fileOps) with slightly divergent policies; this
+// module is the shared protocol-compatible implementation for hook-side callers:
+//
+// - Acquisition is an atomic `mkdir` of `<target>.lock`; the owner is stamped into
+//   `owner` (pid + random token + ts) so stale reclaim can be validated instead of
+//   guessed. Same lock path and owner format as token-utils withFileLock, so hook
+//   processes and runtime/CLI processes serialize against each other.
+// - Reclaim happens only after the stale threshold AND only when the recorded holder
+//   is provably gone (dead pid; a same-pid dir must also have no live in-process
+//   holder). A stale-LOOKING lock owned by a live process is never stolen.
+// - Waiting polls with a jittered ASYNC backoff — never a blocking shared-memory
+//   wait, so the unref'd hook self-deadline timer keeps firing while a contended
+//   lock is being polled.
+// - The acquisition budget is `deadlineMs`: callers derive it from the remaining
+//   hook deadline minus a cleanup reserve with lockBudgetMs (capped at a short
+//   slice), so a contended lock can never hold a hook near its own deadline.
+// - Timeout/abort NEVER run the callback: the outcome is a typed envelope
+//   `{ ok: false, reason: 'busy' | 'aborted' }` and the caller picks its policy.
+//   Sensitive mutations (permission settings) stay fail-closed on lock failure;
+//   never write state "just unlocked" because a budget expired.
+// - An acquisition only counts once the owner stamp is durably on disk. A failed
+//   stamp undoes the mkdir and fails closed (no callback) instead of running under an
+//   ownerless lock: a contender reads a missing owner as reclaimable after `staleMs`,
+//   so an unstamped live holder could have its lock deleted mid-critical-section.
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// Protocol-compatible with token-utils withFileLock.
+export const LOCK_STALE_MS = 10_000;
+// Reserve of the hook deadline kept free for release/cleanup I/O after the wait.
+export const LOCK_RESERVE_MS = 500;
+// Short configured acquisition slice: a contended lock gives up here, far inside a
+// typical hook deadline, instead of riding the deadline out.
+export const LOCK_MAX_SLICE_MS = 1_200;
+
+const BACKOFF_MIN_MS = 3;
+const BACKOFF_SPREAD_MS = 9;
+
+/**
+ * Derive the lock acquisition budget from a hook's wall-clock deadline: the time
+ * remaining before that deadline, minus a reserve for release/cleanup, capped at the
+ * short configured slice (maxWaitMs). Always >= 0 — a budget smaller than the reserve
+ * budgets zero (single attempt, no waiting).
+ * @param {{ hookDeadlineMs?: number, startedAt?: number, reserveMs?: number, maxWaitMs?: number }} options
+ * @returns {number} budget in milliseconds
+ */
+export function lockBudgetMs({
+  hookDeadlineMs,
+  startedAt = Date.now(),
+  reserveMs = LOCK_RESERVE_MS,
+  maxWaitMs = LOCK_MAX_SLICE_MS,
+} = {}) {
+  const slice = Number.isFinite(maxWaitMs) && maxWaitMs >= 0 ? maxWaitMs : LOCK_MAX_SLICE_MS;
+  if (!Number.isFinite(hookDeadlineMs) || hookDeadlineMs < 0) {
+    return slice;
+  }
+  const elapsed = Math.max(0, Date.now() - startedAt);
+  const reserve = Number.isFinite(reserveMs) && reserveMs >= 0 ? reserveMs : LOCK_RESERVE_MS;
+  const remaining = Math.max(0, hookDeadlineMs - elapsed - reserve);
+  return Math.min(remaining, slice);
+}
+
+function lockBackoffDelayMs() {
+  return BACKOFF_MIN_MS + Math.floor(Math.random() * BACKOFF_SPREAD_MS);
+}
+
+// Resolves true when the sleep elapsed fully, false when the signal aborted first —
+// an abort cancels the pending timer immediately instead of waiting out the slice.
+function sleepWithAbort(ms, signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    let timer = null;
+    const onAbort = () => {
+      if (timer) clearTimeout(timer);
+      resolve(false);
+    };
+    timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve(true);
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user — still alive.
+    return error?.code === 'EPERM';
+  }
+}
+
+async function readLockOwner(lockPath) {
+  try {
+    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
+    const pid = Number(raw?.pid);
+    return Number.isInteger(pid) && pid > 0
+      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+const RECLAIM_FILE = 'reclaim';
+
+function sameLockOwner(left, right) {
+  if (!left || !right) return left === right;
+  return left.pid === right.pid && left.token === right.token;
+}
+
+async function readReclaimOwner(lockPath) {
+  try {
+    const raw = JSON.parse(await fs.readFile(path.join(lockPath, RECLAIM_FILE), 'utf8'));
+    const pid = Number(raw?.pid);
+    return Number.isInteger(pid) && pid > 0
+      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Stale observers must claim the existing lock before removing it. The claim lives
+// inside the old generation, so a second observer cannot remove that generation while
+// the first observer is between its owner check and rm(). This closes the TOCTOU race
+// where a delayed stale observer deleted a freshly acquired successor lock.
+async function claimReclaim(lockPath, ownerToken, staleMs) {
+  const reclaimPath = path.join(lockPath, RECLAIM_FILE);
+  try {
+    const handle = await fs.open(reclaimPath, 'wx');
+    try {
+      await handle.writeFile(
+        `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
+        'utf8',
+      );
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') return false;
+
+    // A killed reclaimer can leave its claim behind. Only clear an old claim whose
+    // recorded process is gone; a live claim remains the exclusive reclaim authority.
+    try {
+      const stat = await fs.stat(reclaimPath);
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        const claim = await readReclaimOwner(lockPath);
+        if (!claim || !isPidAlive(claim.pid)) {
+          await fs.rm(reclaimPath, { force: true });
+        }
+      }
+    } catch {
+      // The lock or claim vanished; the caller's normal retry handles it.
+    }
+    return false;
+  }
+}
+
+async function releaseReclaimClaim(lockPath, ownerToken) {
+  try {
+    const claim = await readReclaimOwner(lockPath);
+    if (claim?.token === ownerToken) {
+      await fs.rm(path.join(lockPath, RECLAIM_FILE), { force: true });
+    }
+  } catch {
+    // best-effort claim release; the stale-claim path handles an interrupted cleanup
+  }
+}
+
+async function quarantineReclaim(lockPath, owner, ownerToken) {
+  const quarantinePath = `${lockPath}.reclaim-${ownerToken}`;
+  try {
+    // The claim serializes stale observers. Re-read before the atomic rename so an
+    // observer never detaches a generation different from the one it validated.
+    const current = await readLockOwner(lockPath);
+    if (!sameLockOwner(current, owner)) {
+      await releaseReclaimClaim(lockPath, ownerToken);
+      return false;
+    }
+    // Rename is atomic within the lock's parent directory: the old generation is
+    // detached as one filesystem operation, so a successor created at lockPath can
+    // never be reached by cleanup of this quarantined generation.
+    await fs.rename(lockPath, quarantinePath);
+    await fs.rm(quarantinePath, { recursive: true, force: true });
+    return true;
+  } catch {
+    // Never recursively remove lockPath here. If rename lost a race or failed, the
+    // original path belongs to whoever currently holds it; a later poll can retry.
+    try {
+      await fs.rm(quarantinePath, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup of only this acquisition's quarantine path
+    }
+    return false;
+  }
+}
+
+// In-process holder registry: same-pid holders are parallel async flows whose liveness
+// a pid probe cannot prove, so the module tracks them itself (same as withFileLock).
+const inProcessLockHolders = new Map();
+
+/**
+ * Serialize a mutation of a shared state file across hook processes and concurrent
+ * async flows. Protocol-compatible with token-utils withFileLock (`<file>.lock`
+ * directory + `owner` file). Unlike withFileLock this NEVER runs the callback
+ * unlocked: an expired budget or an aborted signal resolves with a typed outcome and
+ * the caller decides the fail-safe policy.
+ * @param {string} filePath - state file the mutation targets (lock lives beside it)
+ * @param {{
+ *   signal?: AbortSignal,
+ *   deadlineMs?: number,
+ *   staleMs?: number,
+ * }} [options]
+ * @param {() => Promise<*>} fn - critical section
+ * @returns {Promise<{ ok: true, value: * } | { ok: false, reason: 'busy' | 'aborted', waitedMs: number }>}
+ *   fn result wrapped on success, or a typed busy/abort outcome (fn never ran)
+ */
+export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SLICE_MS, staleMs = LOCK_STALE_MS } = {}, fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('withAsyncLock(filePath, options, fn) requires a callback');
+  }
+  if (signal?.aborted) {
+    return { ok: false, reason: 'aborted', waitedMs: 0 };
+  }
+
+  const lockPath = `${filePath}.lock`;
+  const budget = Number.isFinite(deadlineMs) && deadlineMs >= 0 ? deadlineMs : LOCK_MAX_SLICE_MS;
+  const stale = Number.isFinite(staleMs) && staleMs >= 0 ? staleMs : LOCK_STALE_MS;
+  const startedAt = Date.now();
+  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  // True only when THIS acquisition holds a lock it can prove it owns: the atomic
+  // mkdir succeeded AND the owner stamp is on disk. Release is verified against it.
+  let owned = false;
+
+  while (true) {
+    try {
+      // The lock parent must exist before the atomic acquire — a first-ever run in a
+      // fresh project would otherwise fail mkdir with ENOENT.
+      await fs.mkdir(path.dirname(lockPath), { recursive: true });
+      await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
+      inProcessLockHolders.set(lockPath, ownerToken);
+      try {
+        await fs.writeFile(
+          path.join(lockPath, 'owner'),
+          `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
+          'utf8',
+        );
+      } catch {
+        // Fail closed: an unstamped lock is not ours to enter. Running the callback
+        // anyway would leave an ownerless directory, and every other process reads a
+        // missing owner as reclaimable once `staleMs` passes — deleting a LIVE holder's
+        // lock mid-critical-section and letting two mutations interleave. Undo the
+        // acquire and report the typed busy outcome callers already handle.
+        try {
+          const current = await readLockOwner(lockPath);
+          // Never remove a directory some other holder has since stamped (only
+          // possible if this one was reclaimed in the window above).
+          if (!current || current.token === ownerToken) {
+            await fs.rm(lockPath, { recursive: true, force: true });
+          }
+        } catch {
+          // best-effort undo; a leftover dir is unheld and reclaimed by the next waiter
+        }
+        if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
+        return { ok: false, reason: 'busy', waitedMs: Date.now() - startedAt };
+      }
+      owned = true;
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+
+    // Someone holds the lock. Reclaim it only after the stale threshold AND only when
+    // the holder is provably gone — stealing a live holder reintroduces the exact
+    // interleaved-write race this lock exists to prevent.
+    let reclaimed = false;
+    try {
+      const stat = await fs.stat(lockPath);
+      if (Date.now() - stat.mtimeMs > stale) {
+        const owner = await readLockOwner(lockPath);
+        const liveInProcess = inProcessLockHolders.has(lockPath);
+        const reclaimable = !owner || owner.pid === process.pid
+          ? !liveInProcess
+          : !isPidAlive(owner.pid);
+        if (reclaimable && await claimReclaim(lockPath, ownerToken, stale)) {
+          // Detach and clean only the generation that was validated. The atomic rename
+          // makes this safe even when another process acquires lockPath immediately
+          // after the stale generation is removed.
+          reclaimed = await quarantineReclaim(lockPath, owner, ownerToken);
+        }
+      }
+    } catch {
+      reclaimed = false; // lock vanished between mkdir and stat — plain retry handles it
+    }
+    if (reclaimed) continue;
+
+    const waitedMs = Date.now() - startedAt;
+    if (waitedMs >= budget) {
+      // Fail closed: the caller's policy decides what a busy lock means. The callback
+      // is NOT invoked unlocked.
+      return { ok: false, reason: 'busy', waitedMs };
+    }
+
+    // Jittered async backoff, clamped so a sleep never overshoots the budget.
+    const remaining = budget - (Date.now() - startedAt);
+    const sleptFully = await sleepWithAbort(Math.min(lockBackoffDelayMs(), Math.max(1, remaining)), signal);
+    if (!sleptFully) {
+      return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+    }
+  }
+
+  try {
+    return { ok: true, value: await fn() };
+  } finally {
+    // `owned` is only true when the mkdir AND the owner stamp both succeeded, so a
+    // failed stamp never reaches the critical section and never needs releasing here.
+    if (owned) {
+      try {
+        // Remove the lock only if THIS acquisition still owns it: after a stale
+        // reclaim another holder may already own the dir, and deleting it would
+        // unlock their critical section for a third waiter.
+        const current = await readLockOwner(lockPath);
+        if (current && current.token === ownerToken) {
+          await fs.rm(lockPath, { recursive: true, force: true });
+        }
+      } catch {
+        // best-effort release; a leaked dir is reclaimed by the next waiter
+      }
+      if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
+    }
+  }
+}

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
@@ -11,6 +12,9 @@ import {
   withFileLock,
   writeJson,
 } from './token-utils.mjs';
+// Sibling runtime module: installs copy the whole runtime dir, so the negotiated-capacity
+// resolver is always present next to this file.
+import { resolveContextCapTokens } from './context-capacity.mjs';
 
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
 const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
@@ -444,30 +448,64 @@ function computeEstimatedTotalTokens({
   return baselineTokens + estimatedContextTokens + windowTokens + sessionExcess;
 }
 
+// Live capacity evidence published by context-window-guard.sh — the only hook that sees the
+// real serving model. This record is how negotiated capacity reaches the shared
+// threshold/gate path; without it a verified 200k route would still compact at 240k.
+export const CAPACITY_RECORD_SEGMENTS = ['.ukit', 'storage', 'cache', 'context-capacity.json'];
+// Shipped tuning as a ratio of the absolute cap (150_000 soft of a 500_000 cap), so a
+// smaller verified window moves the advisory phases down with the cap they precede.
+export const SOFT_TO_CAP_RATIO = 0.3;
+
+export function readContextCapacityRecord(projectRoot) {
+  const root = projectRoot
+    || process.env.CLAUDE_PROJECT_DIR
+    || process.env.PROJECT_ROOT
+    || process.cwd();
+  try {
+    const parsed = JSON.parse(fsSync.readFileSync(path.join(root, ...CAPACITY_RECORD_SEGMENTS), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Negotiated capacity: env override > config override > the model the guard last observed >
+// conservative fallback. Exported so the source twin and diagnostics read the same number.
+export function resolveCompactCapacity(config = {}) {
+  const record = readContextCapacityRecord(config?.projectRoot);
+  return resolveContextCapTokens({
+    env: process.env,
+    config,
+    modelMetadata: { model: record?.model },
+  });
+}
+
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 150_000));
+  const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
+  const shippedHardCap = positiveInteger(config?.compact?.hardCapTokens, 500_000);
+  // Only tighten once a record exists: an install with no evidence yet (and every caller
+  // that passes no project root) keeps the shipped tuning unchanged.
+  const record = readContextCapacityRecord(config?.projectRoot);
+  const negotiated = record ? resolveCompactCapacity(config) : null;
+  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 cap it precedes, so a soft phase can never sit above the cap (150k of
+  // advisory over a negotiated 100k cap would simply never fire).
+  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)));
-  // Deliberately NOT coupled to hardThreshold: this is an absolute ceiling, so raising
-  // the advisory tokenThreshold must never silently raise the cap along with it.
-  //
-  // Must stay BELOW the model's real context window or the cap is unreachable: the API
-  // rejects the request with "input exceeds the context window" long before an estimate
-  // climbing toward a higher number ever trips this. 500_000 is half of a 1M window, which
-  // leaves ample headroom for the response plus the estimator's own undercount. On any
-  // smaller model this default sits ABOVE the window, so the gate can never fire and is
-  // dead code in exactly the situation it exists to prevent — set compact.hardCapTokens to
-  // 100_000 (200k model) or 128_000 (256k model) for those. Both
-  // env.CLAUDE_CODE_AUTO_COMPACT_WINDOW and omp's compaction.thresholdTokens are rendered
-  // from this number at install time (70% of it), so the client auto-compacts before the
-  // gate blocks tools without anyone hand-syncing a second value.
-  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, 500_000);
 
   return {
     softThreshold,
     hardThreshold,
     baselineTokens,
     hardCapTokens,
+    capacitySource: negotiated?.capacity?.source ?? 'shipped',
+    capacityTokens: negotiated?.capacity?.tokens ?? null,
   };
 }
 
@@ -1175,14 +1213,21 @@ export async function readCompactPressureState(projectRoot, config = {}) {
 // their read-modify-write cycles and silently drop each other's sessionTokens.
 // Mutations are session-scoped: only the calling session's record is rewritten;
 // sibling session records pass through untouched.
+// Every async entry point already knows the project root; carry it into the config so the
+// negotiated-capacity lookup reads THIS project's record rather than guessing from cwd.
+function scopeCapacityConfig(config, projectRoot) {
+  return projectRoot ? { ...config, projectRoot } : config;
+}
+
 async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  const scopedConfig = scopeCapacityConfig(config, projectRoot);
   return withFileLock(runtimePaths.compactPressurePath, async () => {
     const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
     const { id, record } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
-    const current = buildCompactPressureState(record, config);
+    const current = buildCompactPressureState(record, scopedConfig);
     const next = mutator(current);
-    const normalized = buildCompactPressureState(next, config);
+    const normalized = buildCompactPressureState(next, scopedConfig);
     sessions[id] = { ...normalized, updatedAt: Date.now() };
     await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
@@ -1191,10 +1236,11 @@ async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
 
 export async function writeCompactPressureState(projectRoot, state, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
+  const scopedConfig = scopeCapacityConfig(config, projectRoot);
   return withFileLock(runtimePaths.compactPressurePath, async () => {
     const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
     const { id } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
-    const normalized = buildCompactPressureState(state, config);
+    const normalized = buildCompactPressureState(state, scopedConfig);
     sessions[id] = { ...normalized, updatedAt: Date.now() };
     await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
@@ -1209,24 +1255,24 @@ function pressureSessionConfig(payload = {}, config = {}) {
 export async function updateCompactPressureFromPrompt(projectRoot, payload, config = {}) {
   return mutateCompactPressureState(
     projectRoot,
-    (current) => registerPromptPressure(current, payload, config),
-    pressureSessionConfig(payload, config),
+    (current) => registerPromptPressure(current, payload, scopeCapacityConfig(config, projectRoot)),
+    pressureSessionConfig(payload, scopeCapacityConfig(config, projectRoot)),
   );
 }
 
 export async function updateCompactPressureFromOutput(projectRoot, payload, config = {}) {
   return mutateCompactPressureState(
     projectRoot,
-    (current) => registerOutputPressure(current, payload, config),
-    pressureSessionConfig(payload, config),
+    (current) => registerOutputPressure(current, payload, scopeCapacityConfig(config, projectRoot)),
+    pressureSessionConfig(payload, scopeCapacityConfig(config, projectRoot)),
   );
 }
 
 export async function writeThresholdCompactPlan(projectRoot, plan, config = {}) {
   return mutateCompactPressureState(
     projectRoot,
-    (current) => registerThresholdCompactPlan(current, plan, config),
-    pressureSessionConfig(plan, config),
+    (current) => registerThresholdCompactPlan(current, plan, scopeCapacityConfig(config, projectRoot)),
+    pressureSessionConfig(plan, scopeCapacityConfig(config, projectRoot)),
   );
 }
 
@@ -1288,6 +1334,9 @@ async function runCli() {
     // this session's pressure history.
     const sessionConfig = {
       ...config,
+      // Thread the resolved project root so the negotiated-capacity lookup reads THIS
+      // project's record instead of guessing from cwd.
+      projectRoot,
       sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
         ? payload.session_id.trim()
         : undefined,

package/templates/.claude/ukit/runtime/context-capacity.mjs

@@ -0,0 +1,144 @@
+// Negotiated context capacity (H22) — UKit must never assume one fixed model window.
+//
+// The advisory context guard and compact thresholds used to hard-code a 500k cap. That
+// number was tuned for a 1M-class window: on a smaller model the cap sat ABOVE the real
+// window, so the gate was dead code in exactly the situation it exists to prevent. This
+// module instead NEGOTIATES the capacity from the best evidence available, in a fixed,
+// documented precedence, and reports where the number came from so diagnostics can show
+// it:
+//
+//   1. env.UKIT_CONTEXT_WINDOW_TOKENS   — operator override for this session/route.
+//   2. config.compact.contextWindowTokens — operator override in .ukit/storage/config.json.
+//   3. verified model metadata          — exact-prefix lookup in the verified window table.
+//   4. conservative default             — smallest verified window, source `default`.
+//
+// Rules this module enforces:
+//   - Never infer capacity from a provider name alone. A model id must match a verified
+//     table entry by prefix (so dated suffixes like `-20250929` still match); anything
+//     else — including an explicit `verified: false` — uses the conservative fallback.
+//   - Malformed values skip ONE source and fall through to the next; they never poison
+//     the resolution and never throw.
+//   - Verified capacities are clamped to [MIN_CAPACITY_TOKENS, MAX_CAPACITY_TOKENS] so a
+//     typo cannot produce a zero-token session or an unbounded one.
+
+export const CAPACITY_ENV_VAR = 'UKIT_CONTEXT_WINDOW_TOKENS';
+// Unverified fallback CAP: what the guard assumes when nothing is known about the route.
+// Deliberately BELOW every verified window (smallest is gpt-4o, 128k), so an unknown route
+// is warned before its provider limit, not after — the old 500k sat above a 128k/200k
+// window and gave such a route no warning at all until the API rejected the request. A
+// known bigger-but-unlisted route is raised via UKIT_CONTEXT_WINDOW_TOKENS.
+export const DEFAULT_CAPACITY_TOKENS = 100_000;
+// The shipped operator ceiling (compact.hardCapTokens) — only ever an UPPER bound; negotiated
+// capacity can tighten it but never raise it.
+export const SHIPPED_HARD_CAP_TOKENS = 500_000;
+// A verified window is only ever usable as an estimate: the response itself plus the
+// char/token estimator's own undercount must fit too, so only half the window becomes
+// the advisory cap (500k cap from a 1M window — the original tuning, made explicit).
+export const CAPACITY_TO_CAP_RATIO = 0.5;
+export const MIN_CAPACITY_TOKENS = 1_000;
+export const MAX_CAPACITY_TOKENS = 2_000_000;
+
+// Verified model context windows. Longest-prefix match on the lowercased model id; a
+// bare provider prefix ("gpt", "claude", "gemini") is deliberately NOT a table entry.
+const VERIFIED_MODEL_CONTEXT_WINDOWS = [
+  ['claude-opus-4-1', 200_000],
+  ['claude-opus-4', 200_000],
+  ['claude-sonnet-4-5', 200_000],
+  ['claude-sonnet-4', 200_000],
+  ['claude-haiku-4-5', 200_000],
+  ['claude-haiku-4', 200_000],
+  ['claude-3-7-sonnet', 200_000],
+  ['claude-3-5-sonnet', 200_000],
+  ['claude-3-5-haiku', 200_000],
+  ['claude-3-opus', 200_000],
+  ['claude-3-haiku', 200_000],
+  ['gpt-4.1', 1_000_000],
+  ['gpt-4o', 128_000],
+  ['o4-mini', 200_000],
+  ['o3', 200_000],
+  ['gemini-2.5-pro', 1_000_000],
+  ['gemini-2.5-flash', 1_000_000],
+];
+
+// Env vars are always strings: only strict digit strings count as evidence.
+// Anything else (floats, scientific notation, signed/garbage strings) returns null so
+// the resolver falls through to the next source.
+function parseEnvTokenCount(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const parsed = Number(trimmed);
+  return parsed > 0 ? parsed : null;
+}
+
+// Config values are typed JSON: mirror compact-threshold.mjs's number-only contract so a
+// string that happens to look numeric can never silently become a real ceiling.
+function parseConfigTokenCount(value) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : null;
+}
+
+function clampCapacity(tokens) {
+  return Math.min(MAX_CAPACITY_TOKENS, Math.max(MIN_CAPACITY_TOKENS, tokens));
+}
+
+function lookupVerifiedModelWindow(model) {
+  if (typeof model !== 'string') return null;
+  const normalized = model.trim().toLowerCase();
+  if (!normalized) return null;
+  let best = null;
+  for (const entry of VERIFIED_MODEL_CONTEXT_WINDOWS) {
+    const [prefix, windowTokens] = entry;
+    if (normalized.startsWith(prefix) && (!best || prefix.length > best[0].length)) {
+      best = entry;
+    }
+  }
+  return best ? best[1] : null;
+}
+
+// Resolve the model context capacity from the best available evidence.
+// Returns `{tokens, source, confidence}`:
+//   source     — 'env' | 'config' | 'model' | 'default'
+//   confidence — 'verified' for the first three, 'fallback' for the default.
+export function resolveContextCapacity({ env = {}, config = {}, modelMetadata = {} } = {}) {
+  const fromEnv = parseEnvTokenCount(env?.[CAPACITY_ENV_VAR]);
+  if (fromEnv !== null) {
+    return { tokens: clampCapacity(fromEnv), source: 'env', confidence: 'verified' };
+  }
+  const fromConfig = parseConfigTokenCount(config?.compact?.contextWindowTokens);
+  if (fromConfig !== null) {
+    return { tokens: clampCapacity(fromConfig), source: 'config', confidence: 'verified' };
+  }
+  // An explicit `verified: false` on the route metadata means the caller already knows
+  // this route is unverified — do not even try the table.
+  if (modelMetadata?.verified === false) {
+    return { tokens: DEFAULT_CAPACITY_TOKENS, source: 'default', confidence: 'fallback' };
+  }
+  const fromModel = lookupVerifiedModelWindow(modelMetadata?.model);
+  if (fromModel !== null) {
+    return { tokens: fromModel, source: 'model', confidence: 'verified' };
+  }
+  return { tokens: DEFAULT_CAPACITY_TOKENS, source: 'default', confidence: 'fallback' };
+}
+
+// Compose the advisory cap for the context guard from the negotiated capacity plus the
+// operator's absolute ceiling (compact.hardCapTokens). The derived cap never exceeds the
+// operator ceiling and never lands at zero.
+//
+// An explicit compact.hardCapTokens IS a capacity declaration (an operator who wrote
+// 120_000 for their 200k model knows their window), so the conservative fallback only
+// applies when NOTHING is declared — no env, no contextWindowTokens, no hardCapTokens and
+// no verified model. Anything verified is halved (CAPACITY_TO_CAP_RATIO).
+export function resolveContextCapTokens({ env, config, modelMetadata } = {}) {
+  const capacity = resolveContextCapacity({ env, config, modelMetadata });
+  const operatorHardCap = parseConfigTokenCount(config?.compact?.hardCapTokens);
+  const ceiling = operatorHardCap ?? SHIPPED_HARD_CAP_TOKENS;
+  const derived = capacity.source === 'default'
+    ? (operatorHardCap ?? capacity.tokens)
+    : Math.round(capacity.tokens * CAPACITY_TO_CAP_RATIO);
+  return {
+    capacity,
+    capTokens: Math.max(1, Math.min(ceiling, derived)),
+  };
+}