pi-usereq 0.67.0 → 0.69.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.67.0)
+# PI-useReq/pi-usereq (0.69.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/context-file-size.ts

@@ -1,14 +1,14 @@
 /**
  * @file
  * @brief Measures runtime character and token sizes of the canonical context files.
- * @details Provides reusable helpers that compute character and `cl100k_base` token estimates for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` under `<base-path>/<docs-dir>` so configuration menus and command summaries share one measurement contract. Measurements are memoized per resolved path against the file `mtimeMs` plus `size` signature and reuses the process-cached shared tokenizer, so repeated menu renders resolve unchanged files through filesystem stats only. Runtime is O(n) on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and module-local cache mutation.
+ * @details Provides reusable helpers that compute character and `cl100k_base` token estimates for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` under `<base-path>/<docs-dir>` so configuration menus and command summaries share one measurement contract. Measurements are memoized per resolved path against the file `mtimeMs` plus `size` signature inside a process-scoped cache that survives extension rebinds, reuse the lean process-cached shared tokenizer counter, and expose idle-time pre-warm scheduling plus a yielding async measurement variant so the one-time tokenizer module load and per-revision content encodes never execute inside a synchronous menu critical path. Runtime is O(n) on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and process-scoped cache mutation.
  */
 
 import fs from "node:fs";
 import path from "node:path";
 import { DEFAULT_DOCS_DIR, type UseReqConfig } from "./config.js";
 import { normalizeRelativeDirContract } from "./path-context.js";
-import { countFileMetrics } from "./token-counter.js";
+import { countTextTokensAndChars, prewarmTokenCounterEncoder } from "./token-counter.js";
 import { ReqError } from "./errors.js";
 
 /**
@@ -58,10 +58,29 @@ interface CachedContextFileSizeEntry {
 const CONTEXT_FILE_SIZE_CACHE_LIMIT = 64;
 
 /**
- * @brief Stores the module-local context-file measurement cache keyed by resolved path.
- * @details Maps each measured absolute context-file path to its stat-signed facts so repeated configuration-menu renders and command summaries reuse identical measurements while any content revision invalidates only the affected entry. Cache state is module-local and never serialized into configuration.
+ * @brief Describes the process-scoped context-file measurement state persisted across extension rebinds.
+ * @details Stores the stat-signed measurement cache plus the pending pre-warm schedule guards on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, while the hosting process persists across those operations, so session rebinds never re-trigger the heavy first-measurement path for unchanged context files. The interface is compile-time only and introduces no runtime cost.
  */
-const contextFileSizeCache = new Map<string, CachedContextFileSizeEntry>();
+interface ProcessScopedContextFileSizeStore {
+  readonly contextFileSizeCache: Map<string, CachedContextFileSizeEntry>;
+  readonly scheduledPrewarmBases: Set<string>;
+}
+
+/**
+ * @brief Returns the process-scoped context-file measurement store.
+ * @details Lazily initializes one `globalThis` record so session rebinds reuse already measured facts and never double-schedule the idle-time pre-warm for one project base. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedContextFileSizeStore} Mutable process-scoped measurement store.
+ */
+function getProcessScopedContextFileSizeStore(): ProcessScopedContextFileSizeStore {
+  const globalScope = globalThis as typeof globalThis & { __piUsereqContextFileSizeStore?: ProcessScopedContextFileSizeStore };
+  if (!globalScope.__piUsereqContextFileSizeStore) {
+    globalScope.__piUsereqContextFileSizeStore = {
+      contextFileSizeCache: new Map<string, CachedContextFileSizeEntry>(),
+      scheduledPrewarmBases: new Set<string>(),
+    };
+  }
+  return globalScope.__piUsereqContextFileSizeStore;
+}
 
 /**
  * @brief Resolves one canonical context-file absolute path for one project base.
@@ -83,7 +102,7 @@ export function resolveContextFilePath(
 
 /**
  * @brief Measures one context file into deterministic size facts.
- * @details Probes the target with one `stat` call, returns the memoized facts when the observed `mtimeMs` plus `size` signature matches the cached entry, and otherwise reads UTF-8 content and reuses the process-cached shared tokenizer behind `countFileMetrics` for the `cl100k_base` token estimate before storing the fresh facts in the bounded cache. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing and without caching. Runtime is O(1) for unchanged remeasures and O(n) in file size on first measurement per content revision. Side effects are limited to filesystem reads and module-local cache mutation.
+ * @details Probes the target with one `stat` call, returns the memoized facts when the observed `mtimeMs` plus `size` signature matches the cached entry, and otherwise reads UTF-8 content and reuses the lean process-cached shared tokenizer counter behind `countTextTokensAndChars` for the `cl100k_base` token estimate before storing the fresh facts in the bounded process-scoped cache. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing and without caching. Runtime is O(1) for unchanged remeasures and O(n) in file size on first measurement per content revision. Side effects are limited to filesystem reads and process-scoped cache mutation.
  * @param[in] filePath {string} Absolute context-file path to measure.
  * @return {ContextFileSizeFacts} Measured size facts for the target.
  * @satisfies REQ-373, REQ-374
@@ -99,17 +118,18 @@ export function measureContextFileSize(filePath: string): ContextFileSizeFacts {
     return MISSING_CONTEXT_FILE_SIZE;
   }
   const statSignature = `${stat.mtimeMs}:${stat.size}`;
-  const cachedEntry = contextFileSizeCache.get(filePath);
+  const cache = getProcessScopedContextFileSizeStore().contextFileSizeCache;
+  const cachedEntry = cache.get(filePath);
   if (cachedEntry && cachedEntry.statSignature === statSignature) {
     return cachedEntry.facts;
   }
   try {
-    const metrics = countFileMetrics(fs.readFileSync(filePath, "utf8"));
+    const metrics = countTextTokensAndChars(fs.readFileSync(filePath, "utf8"));
     const facts: ContextFileSizeFacts = { exists: true, chars: metrics.chars, tokens: metrics.tokens };
-    if (contextFileSizeCache.size >= CONTEXT_FILE_SIZE_CACHE_LIMIT) {
-      contextFileSizeCache.clear();
+    if (cache.size >= CONTEXT_FILE_SIZE_CACHE_LIMIT) {
+      cache.clear();
     }
-    contextFileSizeCache.set(filePath, { statSignature, facts });
+    cache.set(filePath, { statSignature, facts });
     return facts;
   } catch {
     return MISSING_CONTEXT_FILE_SIZE;
@@ -118,7 +138,7 @@ export function measureContextFileSize(filePath: string): ContextFileSizeFacts {
 
 /**
  * @brief Measures every canonical context file for one project base.
- * @details Iterates `CONTEXT_FILE_NAMES` in documented order, resolves each configured `<base-path>/<docs-dir>` target through `resolveContextFilePath`, and returns the keyed facts record consumed by configuration menus and command summaries. Repeated invocations with unchanged files resolve through the stat-signed measurement cache. Runtime is O(n) in aggregate context-file size on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and module-local cache mutation.
+ * @details Iterates `CONTEXT_FILE_NAMES` in documented order, resolves each configured `<base-path>/<docs-dir>` target through `resolveContextFilePath`, and returns the keyed facts record consumed by configuration menus and command summaries. Repeated invocations with unchanged files resolve through the process-scoped stat-signed measurement cache. Runtime is O(n) in aggregate context-file size on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and process-scoped cache mutation.
  * @param[in] projectBase {string} Absolute project root path.
  * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory.
  * @return {Record<ContextFileName, ContextFileSizeFacts>} Measured size facts keyed by canonical file name.
@@ -135,6 +155,107 @@ export function measureContextFileSizes(
   return facts;
 }
 
+/**
+ * @brief Yields one macrotask turn to the host event loop.
+ * @details Resolves after `setImmediate`, letting pending UI renders, lifecycle callbacks, and input events process between CPU-bound measurement slices. Runtime is O(1). Side effect: schedules one process task.
+ * @return {Promise<void>} Promise resolved on the next macrotask turn.
+ */
+function yieldToEventLoop(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+/**
+ * @brief Measures one context file into deterministic size facts with an event-loop yield before re-encoding.
+ * @details Applies the identical stat-signature freshness contract as `measureContextFileSize`, but awaits one macrotask yield between the stat probe and the read-plus-encode slice when the signature misses, so the TUI can process pending events instead of blocking for the full CPU-bound encode. Cache hits resolve synchronously without yielding. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing and without caching. Runtime is O(1) for unchanged remeasures and O(n) in file size on first measurement per content revision, plus one deferred macrotask per re-encode. Side effects are limited to filesystem reads and process-scoped cache mutation.
+ * @param[in] filePath {string} Absolute context-file path to measure.
+ * @return {Promise<ContextFileSizeFacts>} Measured size facts for the target.
+ * @satisfies REQ-373, REQ-374
+ */
+export async function measureContextFileSizeAsync(filePath: string): Promise<ContextFileSizeFacts> {
+  let stat: fs.Stats | undefined;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    stat = undefined;
+  }
+  if (!stat || !stat.isFile()) {
+    return MISSING_CONTEXT_FILE_SIZE;
+  }
+  const statSignature = `${stat.mtimeMs}:${stat.size}`;
+  const cache = getProcessScopedContextFileSizeStore().contextFileSizeCache;
+  const cachedEntry = cache.get(filePath);
+  if (cachedEntry && cachedEntry.statSignature === statSignature) {
+    return cachedEntry.facts;
+  }
+  await yieldToEventLoop();
+  try {
+    const metrics = countTextTokensAndChars(fs.readFileSync(filePath, "utf8"));
+    const facts: ContextFileSizeFacts = { exists: true, chars: metrics.chars, tokens: metrics.tokens };
+    if (cache.size >= CONTEXT_FILE_SIZE_CACHE_LIMIT) {
+      cache.clear();
+    }
+    cache.set(filePath, { statSignature, facts });
+    return facts;
+  } catch {
+    return MISSING_CONTEXT_FILE_SIZE;
+  }
+}
+
+/**
+ * @brief Measures every canonical context file for one project base with event-loop yields between files.
+ * @details Iterates `CONTEXT_FILE_NAMES` in documented order, resolves each configured `<base-path>/<docs-dir>` target through `resolveContextFilePath`, and awaits `measureContextFileSizeAsync` per file so CPU-bound re-encode slices are separated by macrotask turns consumed by configuration-menu and command-summary rendering. Returned facts are bit-identical to `measureContextFileSizes`. Runtime is O(n) in aggregate context-file size on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and process-scoped cache mutation.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory.
+ * @return {Promise<Record<ContextFileName, ContextFileSizeFacts>>} Measured size facts keyed by canonical file name.
+ * @satisfies REQ-373, REQ-374
+ */
+export async function measureContextFileSizesAsync(
+  projectBase: string,
+  config: UseReqConfig,
+): Promise<Record<ContextFileName, ContextFileSizeFacts>> {
+  const facts = {} as Record<ContextFileName, ContextFileSizeFacts>;
+  for (const fileName of CONTEXT_FILE_NAMES) {
+    facts[fileName] = await measureContextFileSizeAsync(resolveContextFilePath(projectBase, config, fileName));
+  }
+  return facts;
+}
+
+/**
+ * @brief Schedules idle-time pre-warm measurement of the canonical context files for one project base.
+ * @details Chains one `setImmediate` task per canonical context file plus one encoder pre-warm task, so the one-time `js-tiktoken` module load, bundled BPE-rank parse, and first per-file content encodes execute outside any synchronous menu or preflight critical path and later menu renders resolve through stat-signed cache hits. Duplicate scheduling for one resolved project base is suppressed through a process-scoped pending set until the chain completes. The operation is best-effort: every measurement failure is swallowed because measurement already degrades to `MISSING_CONTEXT_FILE_SIZE` facts and later renders re-measure through the identical stat-signature contract. Runtime is O(1) for scheduling; deferred cost is the standard first-measurement cost per file. Side effects include scheduled process tasks, filesystem reads, encoder construction, and process-scoped cache mutation.
+ * @param[in] projectBase {string} Absolute project root path whose canonical context files should pre-warm.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory.
+ * @return {void} No return value.
+ */
+export function prewarmContextFileMeasurements(projectBase: string, config: UseReqConfig): void {
+  const store = getProcessScopedContextFileSizeStore();
+  const normalizedBase = path.resolve(projectBase);
+  if (store.scheduledPrewarmBases.has(normalizedBase)) {
+    return;
+  }
+  store.scheduledPrewarmBases.add(normalizedBase);
+  const releaseSchedule = (): void => {
+    store.scheduledPrewarmBases.delete(normalizedBase);
+  };
+  prewarmTokenCounterEncoder();
+  const filePaths = CONTEXT_FILE_NAMES.map((fileName) => resolveContextFilePath(normalizedBase, config, fileName));
+  const measureRemaining = (index: number): void => {
+    if (index >= filePaths.length) {
+      releaseSchedule();
+      return;
+    }
+    setImmediate(() => {
+      try {
+        measureContextFileSize(filePaths[index]);
+      } catch {
+        // Best-effort pre-warm: measurement failures surface unchanged at render time.
+      }
+      measureRemaining(index + 1);
+    });
+  };
+  measureRemaining(0);
+}
+
 /**
  * @brief Formats one measured context-file size as a compact character and token estimate.
  * @details Emits the deterministic `<chars>c/<tokens>t` shape reused by menu rows, the top-level summary, and the command invocation summary so every surface exposes identical size facts. Runtime is O(n) in rendered length. No external state is mutated.

package/src/core/token-counter.ts

@@ -196,22 +196,42 @@ function defaultJsTiktokenModuleLoader(): JsTiktokenModule {
 
 let jsTiktokenModuleLoader: () => JsTiktokenModule = defaultJsTiktokenModuleLoader;
 
-const cachedTokenCounterEncodings = new Map<string, TokenCounterEncoding>();
+/**
+ * @brief Describes the process-scoped tokenizer state persisted across extension rebinds.
+ * @details Stores the per-encoding shared encoders on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, while the hosting process persists across those operations, so session rebinds reuse already parsed encoders instead of re-parsing the bundled BPE ranks. The interface is compile-time only and introduces no runtime cost.
+ */
+interface ProcessScopedTokenCounterStore {
+  readonly cachedTokenCounterEncodings: Map<string, TokenCounterEncoding>;
+}
+
+/**
+ * @brief Returns the process-scoped tokenizer encoding cache.
+ * @details Lazily initializes one `globalThis` record so session rebinds never re-trigger the heavy encoder construction. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedTokenCounterStore} Mutable process-scoped tokenizer store.
+ */
+function getProcessScopedTokenCounterStore(): ProcessScopedTokenCounterStore {
+  const globalScope = globalThis as typeof globalThis & { __piUsereqTokenCounterStore?: ProcessScopedTokenCounterStore };
+  if (!globalScope.__piUsereqTokenCounterStore) {
+    globalScope.__piUsereqTokenCounterStore = { cachedTokenCounterEncodings: new Map<string, TokenCounterEncoding>() };
+  }
+  return globalScope.__piUsereqTokenCounterStore;
+}
 
 /**
  * @brief Resolves one shared tokenizer encoding for a `TokenCounter` construction.
- * @details Checks the process-scoped per-encoding cache first and constructs the `js-tiktoken` encoding only on the first request per encoding name, so repeated `TokenCounter` construction across the `files-tokens` runner, canonical-doc counting, and context-file measurement reuses one parsed encoder instead of re-parsing the bundled BPE ranks each time. Runtime is O(1) after the first construction for the encoding and dominated by the single deferred `getEncoding` construction otherwise. Side effect: mutates the module-local encoding cache on first resolution per encoding name.
+ * @details Checks the process-scoped per-encoding cache first and constructs the `js-tiktoken` encoding only on the first request per encoding name, so repeated `TokenCounter` construction across the `files-tokens` runner, canonical-doc counting, and context-file measurement reuses one parsed encoder instead of re-parsing the bundled BPE ranks each time. Runtime is O(1) after the first construction for the encoding and dominated by the single deferred `getEncoding` construction otherwise. Side effect: mutates the process-scoped encoding cache on first resolution per encoding name.
  * @param[in] encodingName {string} `js-tiktoken` encoding identifier.
  * @return {TokenCounterEncoding} Cached or newly constructed tokenizer encoding.
  * @throws {ReqError} Propagates the deterministic unavailable-dependency failure when `js-tiktoken` cannot be loaded.
  */
 function resolveTokenCounterEncoding(encodingName: string): TokenCounterEncoding {
-  const cachedEncoding = cachedTokenCounterEncodings.get(encodingName);
+  const encodings = getProcessScopedTokenCounterStore().cachedTokenCounterEncodings;
+  const cachedEncoding = encodings.get(encodingName);
   if (cachedEncoding) {
     return cachedEncoding;
   }
   const encoding = loadJsTiktokenModule().getEncoding(encodingName);
-  cachedTokenCounterEncodings.set(encodingName, encoding);
+  encodings.set(encodingName, encoding);
   return encoding;
 }
 
@@ -223,7 +243,23 @@ function resolveTokenCounterEncoding(encodingName: string): TokenCounterEncoding
  */
 export function setJsTiktokenModuleLoaderForTests(loader?: () => JsTiktokenModule): void {
   jsTiktokenModuleLoader = loader ?? defaultJsTiktokenModuleLoader;
-  cachedTokenCounterEncodings.clear();
+  getProcessScopedTokenCounterStore().cachedTokenCounterEncodings.clear();
+}
+
+/**
+ * @brief Pre-warms the shared tokenizer encoder during idle time.
+ * @details Schedules one `setImmediate` task that resolves the shared encoding through the process-scoped cache, so the one-time `require("js-tiktoken")` plus bundled BPE-rank parse never executes inside a synchronous menu or preflight critical path. The task is best-effort: loader and encoding failures are swallowed because real failures still surface deterministically at measurement time. Runtime is O(1) for scheduling plus the deferred one-time construction cost. Side effect: schedules one process task and mutates the process-scoped encoding cache when the construction succeeds.
+ * @param[in] encodingName {string} `js-tiktoken` encoding identifier. Defaults to `cl100k_base`.
+ * @return {void} No return value.
+ */
+export function prewarmTokenCounterEncoder(encodingName = TOKEN_COUNTER_ENCODING): void {
+  setImmediate(() => {
+    try {
+      resolveTokenCounterEncoding(encodingName);
+    } catch {
+      // Best-effort pre-warm: dependency failures surface unchanged at measurement time.
+    }
+  });
 }
 
 /**
@@ -446,30 +482,62 @@ function buildCountFileMetricsResult(filePath: string, content: string, counter:
 }
 
 /**
- * @brief Counts tokens, characters, bytes, and lines for one in-memory content string.
- * @details Resolves the process-cached shared `TokenCounter` encoder for the encoding, tokenizes the supplied text once, and pairs the result with raw character length, UTF-8 byte size, and logical line count. Runtime is O(n) after the one-time per-encoding encoder construction. No filesystem I/O occurs.
+ * @brief Counts only tokenizer tokens and characters for one in-memory content string.
+ * @details Lean variant of the former full-metrics counter used by context-file sizing: resolves the process-cached shared `TokenCounter` encoder, tokenizes the supplied text once, and pairs the result with the raw character length while skipping UTF-8 byte sizing and the logical-line regex allocation. Token and character semantics are bit-identical to the full metrics contract. Runtime is O(n) after the one-time per-encoding encoder construction. No filesystem I/O occurs.
  * @param[in] content {string} Text payload to measure.
  * @param[in] encodingName {string} Tokenizer identifier. Defaults to `cl100k_base`.
- * @return {{ tokens: number; chars: number; bytes: number; lines: number }} Aggregate metrics for the supplied content.
+ * @return {{ tokens: number; chars: number }} Token estimate and character count for the supplied content.
  */
-export function countFileMetrics(content: string, encodingName = TOKEN_COUNTER_ENCODING): {
+export function countTextTokensAndChars(content: string, encodingName = TOKEN_COUNTER_ENCODING): {
   tokens: number;
   chars: number;
-  bytes: number;
-  lines: number;
 } {
   const counter = new TokenCounter(encodingName);
   return {
     tokens: counter.countTokens(content),
     chars: TokenCounter.countChars(content),
-    bytes: Buffer.byteLength(content, "utf8"),
-    lines: countLines(content),
   };
 }
 
+/**
+ * @brief Describes one stat-signed full-metrics cache entry.
+ * @details Pairs one computed `CountFileMetricsResult` with the `mtimeMs` plus `size` filesystem signature observed at computation time so later invocations can reuse the record through one stat call. The interface is compile-time only and introduces no runtime cost.
+ */
+interface FileMetricsCacheEntry {
+  readonly statSignature: string;
+  readonly result: CountFileMetricsResult;
+}
+
+/**
+ * @brief Bounds the process-scoped per-file metrics cache.
+ * @details Explicit-file and canonical-doc token requests measure bounded path sets per invocation, so unbounded caching would accumulate stale entries in long-lived pi hosts. Exceeding the bound clears the cache completely, which only costs one re-measurement per live path. Lookup complexity is O(1).
+ */
+const FILE_METRICS_CACHE_LIMIT = 128;
+
+/**
+ * @brief Describes the process-scoped per-file metrics state persisted across extension rebinds.
+ * @details Stores the stat-signed full-metric records on `globalThis` because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, while the hosting process persists across those operations, so repeated `files-tokens` and canonical-doc `tokens` invocations reuse already encoded documents instead of re-encoding unchanged content. The interface is compile-time only and introduces no runtime cost.
+ */
+interface ProcessScopedFileMetricsStore {
+  readonly statSignedMetrics: Map<string, FileMetricsCacheEntry>;
+}
+
+/**
+ * @brief Returns the process-scoped per-file metrics cache.
+ * @details Lazily initializes one `globalThis` record so session rebinds never re-trigger the heavy per-file encode path. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedFileMetricsStore} Mutable process-scoped metrics store.
+ */
+function getProcessScopedFileMetricsStore(): ProcessScopedFileMetricsStore {
+  const globalScope = globalThis as typeof globalThis & { __piUsereqFileMetricsStore?: ProcessScopedFileMetricsStore };
+  if (!globalScope.__piUsereqFileMetricsStore) {
+    globalScope.__piUsereqFileMetricsStore = { statSignedMetrics: new Map<string, FileMetricsCacheEntry>() };
+  }
+  return globalScope.__piUsereqFileMetricsStore;
+}
+
 /**
  * @brief Counts tokens, characters, bytes, and lines for multiple files.
- * @details Reuses a single `TokenCounter`, reads each file as UTF-8, and returns per-file metrics plus direct-access metadata such as heading and Doxygen file fields. Read failures are captured as error strings instead of aborting the entire batch. Runtime is O(F + S). Side effects are limited to filesystem reads.
+ * @details Reuses a single `TokenCounter`, reuses stat-signed cached metric records for unchanged files through one stat call per path, reads changed files as UTF-8, and returns per-file metrics plus direct-access metadata such as heading and Doxygen file fields. Read failures are captured as error strings instead of aborting the entire batch, and failed targets are never cached. Runtime is O(F + S) on first measurement per content revision and O(F) in stat calls per unchanged remeasure. Side effects are limited to filesystem reads and process-scoped cache mutation.
  * @param[in] filePaths {string[]} File paths to measure.
  * @param[in] encodingName {string} Tokenizer identifier. Defaults to `cl100k_base`.
  * @return {CountFileMetricsResult[]} Per-file metrics and optional read errors.
@@ -477,10 +545,31 @@ export function countFileMetrics(content: string, encodingName = TOKEN_COUNTER_E
  */
 export function countFilesMetrics(filePaths: string[], encodingName = TOKEN_COUNTER_ENCODING): CountFileMetricsResult[] {
   const counter = new TokenCounter(encodingName);
+  const metricsCache = getProcessScopedFileMetricsStore().statSignedMetrics;
   return filePaths.map((filePath) => {
+    let statSignature: string | undefined;
+    try {
+      const stat = fs.statSync(filePath);
+      if (stat.isFile()) {
+        statSignature = `${stat.mtimeMs}:${stat.size}`;
+        const cachedEntry = metricsCache.get(filePath);
+        if (cachedEntry && cachedEntry.statSignature === statSignature) {
+          return { ...cachedEntry.result };
+        }
+      }
+    } catch {
+      statSignature = undefined;
+    }
     try {
       const content = fs.readFileSync(filePath, "utf8");
-      return buildCountFileMetricsResult(filePath, content, counter);
+      const result = buildCountFileMetricsResult(filePath, content, counter);
+      if (statSignature !== undefined) {
+        if (metricsCache.size >= FILE_METRICS_CACHE_LIMIT) {
+          metricsCache.clear();
+        }
+        metricsCache.set(filePath, { statSignature, result });
+      }
+      return result;
     } catch (error) {
       return {
         file: filePath,

package/src/index.ts

@@ -87,6 +87,8 @@ import {
   computeContextOccupancyFacts,
   formatContextFileSize,
   measureContextFileSizes,
+  measureContextFileSizesAsync,
+  prewarmContextFileMeasurements,
   sumEnabledContextFileTokens,
   type ContextFileName,
   type ContextFileSizeFacts,
@@ -1436,7 +1438,7 @@ async function finalizeMatchedPromptSuccess(
 
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful closure handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Applies session-start-specific resource validation, project-config refresh, idle-time shared-tokenizer and context-file measurement pre-warm, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, classifies the prompt outcome, and for every matched successful worktree-backed completion defers the restore switch, stash-assisted merge, and worktree deletion to `agent_settled` when the running pi host supports that 0.80.4+ event (because its `switchSession` awaits the active agent run to become idle and would deadlock inside `agent_end`), or executes the finalization directly at `agent_end` when the host does not emit `agent_settled`. On `agent_settled`, reuses persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the deferred stash-assisted merge-and-delete finalization path, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful closure handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
@@ -1468,6 +1470,7 @@ async function handleExtensionStatusEvent(
       gitPath: resolveRuntimeGitPath(startupCwd),
     });
     const config = loadProjectConfig(startupCwd);
+    prewarmContextFileMeasurements(startupCwd, config);
     applyConfiguredPiUsereqTools(pi, config);
     setPiUsereqStatusConfig(statusController, config);
     const missingCheckers = checkDefaultCheckersAvailability(config);
@@ -3474,7 +3477,7 @@ function registerPromptCommands(
             promptName,
             args,
             config,
-            measureContextFileSizes(projectBase, config),
+            await measureContextFileSizesAsync(projectBase, config),
             maxContextTokens,
           );
           const promptDelivery = deliverPromptCommand(pi, content, commandSummary, promptContext);
@@ -4632,7 +4635,7 @@ function buildContextFilesMenuChoices(
 
 /**
  * @brief Runs the `Context Files` configuration submenu.
- * @details Loads the shared settings menu with the three context-file toggle rows, persists each inline toggle immediately through the shared change callback, restores all three flags to enabled on approved subtree reset, preserves focus on the toggled row, and returns to the top-level menu on cancel. Runtime depends on user interaction count. Side effects include config writes and UI notifications.
+ * @details Measures the context files through the yielding async measurement helper, then loads the shared settings menu with the three context-file toggle rows, persists each inline toggle immediately through the shared change callback, restores all three flags to enabled on approved subtree reset, preserves focus on the toggled row, and returns to the top-level menu on cancel. Runtime depends on user interaction count. Side effects include config writes and UI notifications.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable effective project configuration.
  * @param[in] onConfigChange {() => void} Shared persistence-plus-status callback.
@@ -4646,7 +4649,7 @@ async function configureContextFilesMenu(
   onConfigChange: () => void,
   maxContextTokens?: number | undefined,
 ): Promise<void> {
-  const contextFileSizes = measureContextFileSizes(getProjectBase(ctx.cwd), config);
+  const contextFileSizes = await measureContextFileSizesAsync(getProjectBase(ctx.cwd), config);
   const setFlag = (flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow", enabled: boolean): void => {
     config[flagKey] = enabled;
     onConfigChange();
@@ -4869,7 +4872,7 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
 
 /**
  * @brief Runs the top-level pi-usereq configuration menu.
- * @details Loads the effective merged config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show local configuration` or `Show global configuration`, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
+ * @details Loads the effective merged config, performs one yielding async context-file measurement warm pass so menu renders resolve through stat-signed cache hits instead of first-measurement encodes, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show local configuration` or `Show global configuration`, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
@@ -4887,6 +4890,7 @@ async function configurePiUsereq(
   let config = loadProjectConfig(ctx.cwd);
   const projectBase = getProjectBase(ctx.cwd);
   const maxContextTokens = resolveModelContextWindowTokens(statusController.state.contextUsage);
+  await measureContextFileSizesAsync(projectBase, config);
   const initialShortcut = config["notify-sound-toggle-shortcut"];
   const persistConfigChange = () => {
     Object.assign(config, normalizeConfigPaths(projectBase, config));
@@ -5094,6 +5098,7 @@ async function configurePiUsereq(
     }
     if (choice === "reset-defaults") {
       const defaultConfig = getDefaultConfig(projectBase);
+      const resetContextFileSizes = measureContextFileSizes(ctx.cwd, config);
       const approved = await confirmResetChanges(
         ctx,
         "Confirm pi-usereq reset",
@@ -5101,7 +5106,7 @@ async function configurePiUsereq(
           { label: "Document directory", previousValue: config["docs-dir"], nextValue: defaultConfig["docs-dir"] },
           { label: "Source-code directories", previousValue: config["src-dir"].join(", "), nextValue: defaultConfig["src-dir"].join(", ") },
           { label: "Unit tests directory", previousValue: config["tests-dir"], nextValue: defaultConfig["tests-dir"] },
-          { label: "Context Files", previousValue: formatContextFilesSummary(config, measureContextFileSizes(ctx.cwd, config), maxContextTokens), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig), maxContextTokens) },
+          { label: "Context Files", previousValue: formatContextFilesSummary(config, resetContextFileSizes, maxContextTokens), nextValue: formatContextFilesSummary(defaultConfig, resetContextFileSizes, maxContextTokens) },
           { label: "Auto git commit", previousValue: config.AUTO_GIT_COMMIT, nextValue: defaultConfig.AUTO_GIT_COMMIT },
           { label: "Git worktree", previousValue: config.GIT_WORKTREE_ENABLED, nextValue: defaultConfig.GIT_WORKTREE_ENABLED },
           { label: "Worktree prefix", previousValue: config.GIT_WORKTREE_PREFIX, nextValue: defaultConfig.GIT_WORKTREE_PREFIX },
@@ -5159,7 +5164,7 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
+ * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325, REQ-326, REQ-327
@@ -5168,6 +5173,11 @@ export default function piUsereqExtension(pi: ExtensionAPI): void {
   writePersistedPromptCommandRuntimeApi(pi as unknown as PersistedPromptCommandRuntimeApi);
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
+  try {
+    prewarmContextFileMeasurements(getProcessCwdSafe(), loadProjectConfig(getProcessCwdSafe()));
+  } catch {
+    // Best-effort idle-time pre-warm: measurement failures surface unchanged at render time.
+  }
   registerReqResetCommand(pi, statusController);
   registerReqReferencesCommand(pi, statusController);
   registerPromptCommands(pi, statusController);