pi-usereq 0.60.0 → 0.61.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.60.0)
+# PI-useReq/pi-usereq (0.61.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.60.0",
+  "version": "0.61.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"
@@ -32,9 +32,9 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.80.4",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
-    "@earendil-works/pi-tui": "^0.80.4",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@sinclair/typebox": "^0.34.49"
   },
   "dependencies": {

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

@@ -0,0 +1,109 @@
+/**
+ * @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. Runtime is O(n) in aggregate context-file size. Side effects are limited to filesystem reads.
+ */
+
+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";
+
+/**
+ * @brief Stores the canonical context-file names in their documented injection order.
+ * @details The tuple is the single ordering source reused by measurement helpers and size renderers so every caller reports `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` consistently. Lookup complexity is O(1).
+ * @satisfies REQ-373
+ */
+export const CONTEXT_FILE_NAMES = ["REQUIREMENTS.md", "REFERENCES.md", "WORKFLOW.md"] as const;
+
+/**
+ * @brief Narrows context-file identifiers to the canonical measured document set.
+ * @details Compile-time alias derived from `CONTEXT_FILE_NAMES` and reused by the measured-facts record keys. The alias introduces no runtime cost.
+ */
+export type ContextFileName = (typeof CONTEXT_FILE_NAMES)[number];
+
+/**
+ * @brief Describes the measured size facts of one canonical context file.
+ * @details Stores the filesystem existence flag plus the exact character count and the `cl100k_base` token estimate computed from the file content. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-374
+ */
+export interface ContextFileSizeFacts {
+  readonly exists: boolean;
+  readonly chars: number;
+  readonly tokens: number;
+}
+
+/**
+ * @brief Stores the canonical missing-file size facts.
+ * @details Reused as the deterministic result for missing, non-file, and unreadable targets so callers never receive `undefined` facts. Lookup complexity is O(1).
+ * @satisfies REQ-374
+ */
+export const MISSING_CONTEXT_FILE_SIZE: ContextFileSizeFacts = Object.freeze({ exists: false, chars: 0, tokens: 0 });
+
+/**
+ * @brief Resolves one canonical context-file absolute path for one project base.
+ * @details Joins the project base with the trailing-slash-free configured `docs-dir` (falling back to `DEFAULT_DOCS_DIR`) and the supplied canonical file name so menus, summaries, and the `%%CONTEXT_FILES%%` renderer address identical targets. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory.
+ * @param[in] fileName {ContextFileName} Canonical context-file name.
+ * @return {string} Absolute context-file path.
+ * @satisfies REQ-373
+ */
+export function resolveContextFilePath(
+  projectBase: string,
+  config: UseReqConfig,
+  fileName: ContextFileName,
+): string {
+  const normalizedDocsDir = normalizeRelativeDirContract(config["docs-dir"]) || DEFAULT_DOCS_DIR;
+  return path.join(projectBase, normalizedDocsDir, fileName);
+}
+
+/**
+ * @brief Measures one context file into deterministic size facts.
+ * @details Probes filesystem existence and file kind, reads UTF-8 content, and reuses the shared `countFileMetrics` tokenizer for the `cl100k_base` token estimate. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+ * @param[in] filePath {string} Absolute context-file path to measure.
+ * @return {ContextFileSizeFacts} Measured size facts for the target.
+ * @satisfies REQ-373, REQ-374
+ */
+export function measureContextFileSize(filePath: string): ContextFileSizeFacts {
+  try {
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      return MISSING_CONTEXT_FILE_SIZE;
+    }
+    const metrics = countFileMetrics(fs.readFileSync(filePath, "utf8"));
+    return { exists: true, chars: metrics.chars, tokens: metrics.tokens };
+  } catch {
+    return MISSING_CONTEXT_FILE_SIZE;
+  }
+}
+
+/**
+ * @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. Runtime is O(n) in aggregate context-file size. Side effects are limited to filesystem reads.
+ * @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.
+ * @satisfies REQ-373, REQ-374
+ */
+export function measureContextFileSizes(
+  projectBase: string,
+  config: UseReqConfig,
+): Record<ContextFileName, ContextFileSizeFacts> {
+  const facts = {} as Record<ContextFileName, ContextFileSizeFacts>;
+  for (const fileName of CONTEXT_FILE_NAMES) {
+    facts[fileName] = measureContextFileSize(resolveContextFilePath(projectBase, config, fileName));
+  }
+  return facts;
+}
+
+/**
+ * @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.
+ * @param[in] facts {ContextFileSizeFacts} Measured context-file size facts.
+ * @return {string} Compact `<chars>c/<tokens>t` size string.
+ * @satisfies REQ-375, REQ-376, REQ-377
+ */
+export function formatContextFileSize(facts: ContextFileSizeFacts): string {
+  return `${facts.chars}c/${facts.tokens}t`;
+}

package/src/core/prompt-command-runtime.ts

@@ -63,6 +63,126 @@ export interface PromptCommandExecutionPlan {
   worktreeDir?: string;
   worktreePath?: string;
   worktreeRootPath?: string;
+  originalModel?: PromptCommandModelSelection;
+  originalThinkingLevel?: string;
+}
+
+/**
+ * @brief Describes one serializable model-selection fact captured at prompt-command preflight.
+ * @details Stores the active model provider and identifier as plain strings so the selection can travel inside the prompt execution plan and process-scoped persistence across session replacement without retaining live SDK model objects, and MUST NOT be persisted into pi-usereq configuration files per CTN-022. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-366, CTN-022
+ */
+export interface PromptCommandModelSelection {
+  provider: string;
+  modelId: string;
+}
+
+/**
+ * @brief Describes the loosely-typed runtime surface required to re-apply one captured selection.
+ * @details Narrows the pi runtime to the model registry lookup, the active model plus thinking-level probes used by the duplicate-skip guard, and the session-scoped `setModel`/`setThinkingLevel` appliers that leave the configured default model untouched. All members stay optional so legacy hosts and offline replays degrade to a documented warning instead of aborting orchestration. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-367, REQ-370, REQ-371
+ */
+export interface PromptCommandModelSelectionSurface {
+  modelRegistry?: { find?: (provider: unknown, modelId: unknown) => unknown };
+  model?: unknown;
+  thinkingLevel?: unknown;
+  setModel?: (model: unknown) => Promise<boolean>;
+  setThinkingLevel?: (level: unknown) => void;
+}
+
+/**
+ * @brief Describes the re-apply request consumed by `reapplyPromptCommandSessionSelection`.
+ * @details Carries the captured selection plus thinking level, the runtime surface, and the optional stale-context-safe warning callback so callers keep notification ownership inside `src/index.ts` while the helper stays independent from extension UI types per DES-012. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface PromptCommandModelSelectionReapplyOptions {
+  selection: PromptCommandModelSelection | undefined;
+  thinkingLevel: string | undefined;
+  surface: PromptCommandModelSelectionSurface | undefined;
+  notifyWarning?: (message: string) => void;
+}
+
+/**
+ * @brief Describes the deterministic outcome facts of one guarded selection re-application.
+ * @details Distinguishes not-attempted skips (missing selection, missing surface, or post-switch state already matching the captured selection) from attempted applications, and carries the normalized warning message emitted when resolution, authentication, or the runtime applier fails. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-370, REQ-372
+ */
+export interface PromptCommandModelSelectionReapplyResult {
+  attempted: boolean;
+  applied: boolean;
+  skipped: boolean;
+  warningMessage?: string;
+}
+
+/**
+ * @brief Re-applies one captured model selection onto the active post-switch session.
+ * @details Resolves the captured provider plus identifier through the surface model registry, skips the whole operation when the selection or surface is unavailable and when the active model and thinking level already match the captured selection so no duplicate `model_change` session entry is emitted, otherwise awaits the session-scoped `setModel` applier, then re-applies the captured thinking level when the active level differs. Every resolution, authentication, and applier failure degrades into one warning notification through the supplied callback without throwing, so prompt orchestration and worktree closure continue unchanged. Runtime is O(1) plus one awaited model mutation. No external state is mutated beyond the applied session selection.
+ * @param[in] options {PromptCommandModelSelectionReapplyOptions} Captured selection, runtime surface, and warning callback.
+ * @return {Promise<PromptCommandModelSelectionReapplyResult>} Attempted, applied, skipped, and warning facts for the re-application.
+ * @satisfies REQ-366, REQ-367, REQ-368, REQ-369, REQ-370, REQ-371, REQ-372, DES-021
+ */
+export async function reapplyPromptCommandSessionSelection(
+  options: PromptCommandModelSelectionReapplyOptions,
+): Promise<PromptCommandModelSelectionReapplyResult> {
+  const selection = options.selection;
+  const surface = options.surface;
+  if (!selection || !surface) {
+    return { attempted: false, applied: false, skipped: true };
+  }
+  const notifyWarning = options.notifyWarning;
+  const registryFind = surface.modelRegistry?.find;
+  const resolvedCandidate = typeof registryFind === "function"
+    ? registryFind.call(surface.modelRegistry, selection.provider, selection.modelId)
+    : undefined;
+  const resolved = resolvedCandidate as { provider?: unknown; id?: unknown } | null | undefined;
+  if (!resolved || typeof resolved.provider !== "string" || typeof resolved.id !== "string") {
+    const message = `WARNING: Could not re-apply model ${selection.provider}/${selection.modelId}: model is not available in the active model registry.`;
+    notifyWarning?.(message);
+    return { attempted: true, applied: false, skipped: false, warningMessage: message };
+  }
+  const currentModel = surface.model as { provider?: unknown; id?: unknown } | null | undefined;
+  const modelMatches = currentModel !== null
+    && currentModel !== undefined
+    && currentModel.provider === selection.provider
+    && currentModel.id === selection.modelId;
+  const levelMatches = typeof options.thinkingLevel !== "string"
+    || surface.thinkingLevel === options.thinkingLevel;
+  if (modelMatches && levelMatches) {
+    return { attempted: false, applied: false, skipped: true };
+  }
+  if (!modelMatches) {
+    const setModelFn = surface.setModel;
+    if (typeof setModelFn !== "function") {
+      const message = `WARNING: Could not re-apply model ${selection.provider}/${selection.modelId}: the runtime does not expose setModel.`;
+      notifyWarning?.(message);
+      return { attempted: true, applied: false, skipped: false, warningMessage: message };
+    }
+    let setModelResult: unknown;
+    try {
+      setModelResult = await setModelFn.call(surface, resolved);
+    } catch (error) {
+      const message = `WARNING: Could not re-apply model ${selection.provider}/${selection.modelId}: ${error instanceof Error ? error.message : String(error)}.`;
+      notifyWarning?.(message);
+      return { attempted: true, applied: false, skipped: false, warningMessage: message };
+    }
+    if (setModelResult === false) {
+      const message = `WARNING: Could not re-apply model ${selection.provider}/${selection.modelId}: no API key configured for ${selection.provider}.`;
+      notifyWarning?.(message);
+      return { attempted: true, applied: false, skipped: false, warningMessage: message };
+    }
+  }
+  const setThinkingLevelFn = surface.setThinkingLevel;
+  if (
+    typeof options.thinkingLevel === "string"
+    && surface.thinkingLevel !== options.thinkingLevel
+    && typeof setThinkingLevelFn === "function"
+  ) {
+    try {
+      setThinkingLevelFn.call(surface, options.thinkingLevel);
+    } catch {
+      // REQ-372: thinking-level failures are advisory-only and MUST NOT abort orchestration.
+    }
+  }
+  return { attempted: true, applied: true, skipped: false };
 }
 
 /**
@@ -109,11 +229,11 @@ interface PromptCommandSessionSwitchOptions {
 
 /**
  * @brief Describes the minimal session-bound surface available after session replacement.
- * @details Extends the shared prompt-command context with `sendUserMessage(...)` so prompt dispatch can target the replacement session without reusing stale pre-switch runtime objects. The interface is compile-time only and introduces no runtime cost.
+ * @details Extends the shared prompt-command context with a string-only `sendUserMessage(...)` probe so prompt dispatch can target the replacement session without reusing stale pre-switch runtime objects. The string content parameter mirrors the prompt-delivery contract consumed by `deliverPromptCommand(...)` while remaining structurally compatible with the pi 1.0.0 replacement-session delivery signatures. The interface is compile-time only and introduces no runtime cost.
  */
 interface PromptCommandActiveContext extends PromptCommandSessionContext {
   sendUserMessage?: (
-    content: string | Array<{ type: string; text?: string }>,
+    content: string,
     options?: PromptCommandSessionMessageOptions,
   ) => Promise<void> | void;
 }
@@ -1584,9 +1704,11 @@ export function validatePromptRequiredDocs(
  * @param[in] currentSessionDir {string | undefined} Active session directory reused when the execution session is forked.
  * @param[in] currentSessionBranch {PromptCommandSessionEntry[] | undefined} Active in-memory session branch copied when the origin session file is not flushed yet.
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
+ * @param[in] originalModel {PromptCommandModelSelection | undefined} Active model provider plus identifier captured by the command handler for later re-application.
+ * @param[in] originalThinkingLevel {string | undefined} Active thinking level captured by the command handler for later re-application.
  * @return {PromptCommandExecutionPlan} Prepared execution plan.
  * @throws {ReqError} Throws when repository validation, required-doc validation, worktree creation, or session preparation fails.
- * @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271
+ * @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271, REQ-366
  */
 export function preparePromptCommandExecution(
   promptName: PromptCommandName,
@@ -1597,6 +1719,8 @@ export function preparePromptCommandExecution(
   currentSessionDir: string | undefined,
   currentSessionBranch: PromptCommandSessionEntry[] | undefined,
   debugOptions?: PromptCommandDebugOptions,
+  originalModel?: PromptCommandModelSelection,
+  originalThinkingLevel?: string,
 ): PromptCommandExecutionPlan {
   const gitPath = validatePromptGitState(projectBase, config);
   const reuseCurrentSessionFile = isUsablePromptSessionFile(currentSessionFile, projectBase);
@@ -1624,6 +1748,8 @@ export function preparePromptCommandExecution(
       baseDir: staticWorktreePaths.baseDir,
       originalSessionFile,
       executionSessionFile: originalSessionFile,
+      originalModel,
+      originalThinkingLevel,
     };
   }
   const worktreeDir = buildPromptWorktreeName(gitPath, config);
@@ -1663,6 +1789,8 @@ export function preparePromptCommandExecution(
     worktreeDir: worktreePaths.worktreeDir,
     worktreePath: worktreePaths.worktreePath,
     worktreeRootPath: worktreePaths.worktreeRootPath,
+    originalModel,
+    originalThinkingLevel,
   };
 }
 

package/src/core/prompts.ts

@@ -17,6 +17,7 @@ import {
   comparePiUsereqStartupToolNames,
   type PiUsereqStartupToolName,
 } from "./pi-usereq-tools.js";
+import { formatContextFileSize, type ContextFileSizeFacts } from "./context-file-size.js";
 import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
@@ -374,21 +375,27 @@ export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
 
 /**
  * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
- * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. When measured context-file size facts are supplied, every enabled existing context file in the `context files` field is rendered as `name(<chars>c/<tokens>t)`; without facts, or for enabled missing files, the plain `name` form is rendered. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
  * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
  * @param[in] args {string} User request arguments passed to the slash command.
  * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
+ * @param[in] contextFileSizes {Record<string, ContextFileSizeFacts> | undefined} Optional measured context-file size facts keyed by canonical file name, consumed for `context files` size suffixes.
  * @return {string} Multi-line command invocation summary text.
- * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353
+ * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353, REQ-377
  */
 export function renderPromptCommandSummary(
   promptName: string,
   args: string,
   config: UseReqConfig,
+  contextFileSizes?: Record<string, ContextFileSizeFacts>,
 ): string {
   const contextFiles = CONTEXT_FILE_DESCRIPTORS
     .filter((descriptor) => config[descriptor.flagKey])
-    .map((descriptor) => descriptor.fileName.replace(/\.md$/, "").toLowerCase())
+    .map((descriptor) => {
+      const baseName = descriptor.fileName.replace(/\.md$/, "").toLowerCase();
+      const facts = contextFileSizes?.[descriptor.fileName];
+      return facts?.exists ? `${baseName}(${formatContextFileSize(facts)})` : baseName;
+    })
     .join(", ") || "none";
   const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
     .filter((language) => config["static-check"][language]?.enabled === "enable")

package/src/core/static-check.ts

@@ -404,7 +404,7 @@ export class StaticCheckCommand extends StaticCheckBase {
       throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
     }
     super(inputs, extraArgs, failOnly);
-    this.cmd = cmd.includes("%%INSTALLATION_PATH%%") ? resolvedCmd : cmd;
+    this.cmd = resolvedCmd;
     this.label = `Command[${cmd}]`;
   }
 

package/src/index.ts

@@ -83,6 +83,12 @@ import {
   normalizeEnabledPiUsereqTools,
   type PiUsereqStartupToolName,
 } from "./core/pi-usereq-tools.js";
+import {
+  formatContextFileSize,
+  measureContextFileSizes,
+  type ContextFileName,
+  type ContextFileSizeFacts,
+} from "./core/context-file-size.js";
 import {
   PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE,
   renderPrompt,
@@ -95,8 +101,11 @@ import {
   finalizePromptCommandExecution,
   getPromptCommandErrorContext,
   preparePromptCommandExecution,
+  reapplyPromptCommandSessionSelection,
   restorePromptCommandExecution,
   type PromptCommandExecutionPlan,
+  type PromptCommandModelSelection,
+  type PromptCommandModelSelectionSurface,
 } from "./core/prompt-command-runtime.js";
 import {
   REQ_REFERENCES_COMMAND_DESCRIPTION,
@@ -1301,13 +1310,15 @@ function isPiAgentSettledEventSupported(
 /**
  * @brief Finalizes a matched successful worktree-backed prompt at the current lifecycle point.
  * @details Executes the deferred stash-assisted merge, transcript preservation, base-path restore, and worktree plus branch deletion through `finalizePromptCommandExecution(...)`, surfaces `error` or warning-only notifications, clears the pending finalization outcome plus prompt state, and transitions workflow state through `merging` to `idle`. Reused by the `agent_settled` handler on 0.80.4+ hosts and directly by the `agent_end` fallback on legacy hosts that never emit `agent_settled`. Runtime is dominated by git finalization. Side effects include branch merges, worktree deletion, notifications, and workflow-state transitions.
+ * @param[in] pi {ExtensionAPI} Active extension API instance supplying the model re-apply appliers.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller whose pending and active prompt state is cleared.
  * @param[in] promptRequest {PiUsereqPromptRequest} Matched successful worktree-backed prompt execution plan.
  * @param[in] ctx {ExtensionContext} Active extension context used for finalization and notifications.
  * @return {Promise<void>} Promise resolved when finalization and state transitions complete.
- * @satisfies REQ-208, REQ-228, REQ-229, REQ-230, REQ-282, REQ-291, REQ-292, REQ-354, REQ-355
+ * @satisfies REQ-208, REQ-228, REQ-229, REQ-230, REQ-282, REQ-291, REQ-292, REQ-354, REQ-355, REQ-368, REQ-370, REQ-371, REQ-372
  */
 async function finalizeMatchedPromptSuccess(
+  pi: ExtensionAPI,
   statusController: PiUsereqStatusController,
   promptRequest: PiUsereqPromptRequest,
   ctx: ExtensionContext,
@@ -1333,6 +1344,14 @@ async function finalizeMatchedPromptSuccess(
         : undefined,
     );
     promptContext = (finalization.activeContext ?? promptContext) as typeof ctx;
+    if (finalization.cleanupSucceeded && !finalization.errorMessage) {
+      await reapplyCapturedPromptModelSelection(
+        promptRequest.originalModel,
+        promptRequest.originalThinkingLevel,
+        pi,
+        promptContext,
+      );
+    }
   } catch (error) {
     promptContext = (getPromptCommandErrorContext(error) ?? promptContext) as typeof ctx;
     let errorMessage = error instanceof Error ? error.message : String(error);
@@ -1346,6 +1365,12 @@ async function finalizeMatchedPromptSuccess(
           : undefined,
       ) ?? promptContext) as typeof ctx;
       cleanupSucceeded = true;
+      await reapplyCapturedPromptModelSelection(
+        promptRequest.originalModel,
+        promptRequest.originalThinkingLevel,
+        pi,
+        promptContext,
+      );
     } catch (restoreError) {
       promptContext = (getPromptCommandErrorContext(restoreError) ?? promptContext) as typeof ctx;
       errorMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
@@ -1451,6 +1476,12 @@ async function handleExtensionStatusEvent(
     const requestForActivation = activePromptRequest ?? pendingPromptRequest;
     if (requestForActivation !== undefined) {
       await activatePromptCommandExecution(requestForActivation, ctx);
+      await reapplyCapturedPromptModelSelection(
+        requestForActivation.originalModel,
+        requestForActivation.originalThinkingLevel,
+        pi,
+        ctx,
+      );
     }
   }
   const notifyRequest: PiNotifyEventRequest | undefined = hookName === "agent_end"
@@ -1555,6 +1586,7 @@ async function handleExtensionStatusEvent(
           // directly at `agent_end` to avoid parking in `merging` forever.
           statusController.state.pendingFinalizationOutcome = outcome;
           await finalizeMatchedPromptSuccess(
+            pi,
             statusController,
             activePromptRequest,
             promptContext,
@@ -1635,7 +1667,7 @@ async function handleExtensionStatusEvent(
       && settledPromptRequest.worktreeDir !== undefined
       && pendingOutcome === "completed"
     ) {
-      await finalizeMatchedPromptSuccess(statusController, settledPromptRequest, ctx);
+      await finalizeMatchedPromptSuccess(pi, statusController, settledPromptRequest, ctx);
     }
   }
   if (hookName === "session_shutdown") {
@@ -3041,6 +3073,139 @@ function registerPiNotifyShortcut(
   });
 }
 
+/**
+ * @brief Describes the loosely-typed pi extension API surface required by model re-application.
+ * @details Narrows the runtime API to the model appliers and thinking-level probe accessed defensively so legacy hosts and offline harnesses without `setModel`, `setThinkingLevel`, or `getThinkingLevel` degrade to a documented warning instead of a runtime exception. The alias is compile-time only and introduces no runtime cost.
+ */
+type PromptModelSelectionApiSurface = {
+  setModel?: (model: unknown) => unknown;
+  setThinkingLevel?: (level: unknown) => unknown;
+  getThinkingLevel?: () => unknown;
+};
+
+/**
+ * @brief Describes the loosely-typed context surface required by model re-application.
+ * @details Narrows extension contexts to the active model, thinking level, and model registry probe used to capture the pre-switch selection and to evaluate the duplicate-skip guard after session replacement. The alias is compile-time only and introduces no runtime cost.
+ */
+type PromptModelSelectionContextSurface = {
+  model?: unknown;
+  thinkingLevel?: unknown;
+  modelRegistry?: { find?: (provider: unknown, modelId: unknown) => unknown };
+};
+
+/**
+ * @brief Captures the active model provider and identifier from one loosely-typed context model.
+ * @details Validates that the runtime model object exposes non-empty string provider and identifier fields and emits the serializable selection fact stored inside the prompt execution plan, returning undefined when the runtime exposes no usable model so preflight capture never throws. Runtime is O(1). No external state is mutated.
+ * @param[in] model {unknown} Active runtime model object from `ctx.model`.
+ * @return {PromptCommandModelSelection | undefined} Serializable provider plus identifier fact, or undefined when unavailable.
+ * @satisfies REQ-366
+ */
+function resolveCurrentModelSelection(
+  model: unknown,
+): PromptCommandModelSelection | undefined {
+  const candidate = model as { provider?: unknown; id?: unknown } | null | undefined;
+  if (candidate === null || candidate === undefined) {
+    return undefined;
+  }
+  if (
+    typeof candidate.provider !== "string"
+    || typeof candidate.id !== "string"
+    || candidate.provider === ""
+    || candidate.id === ""
+  ) {
+    return undefined;
+  }
+  return { provider: candidate.provider, modelId: candidate.id };
+}
+
+/**
+ * @brief Captures the active thinking level from the runtime API or fallback context.
+ * @details Prefers `pi.getThinkingLevel()` when the host exposes it and falls back to the context `thinkingLevel` probe, returning undefined for legacy hosts or offline harnesses that provide neither so capture stays advisory. Runtime is O(1). No external state is mutated.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] ctx {unknown} Active extension or command context used as fallback probe.
+ * @return {string | undefined} Active thinking level, or undefined when unavailable.
+ * @satisfies REQ-366, REQ-371
+ */
+function resolveCurrentThinkingLevel(pi: ExtensionAPI, ctx: unknown): string | undefined {
+  const api = pi as unknown as PromptModelSelectionApiSurface;
+  if (typeof api.getThinkingLevel === "function") {
+    const level = api.getThinkingLevel();
+    if (typeof level === "string" && level !== "") {
+      return level;
+    }
+  }
+  const context = ctx as PromptModelSelectionContextSurface | null | undefined;
+  if (
+    context !== null
+    && context !== undefined
+    && typeof context.thinkingLevel === "string"
+    && context.thinkingLevel !== ""
+  ) {
+    return context.thinkingLevel;
+  }
+  return undefined;
+}
+
+/**
+ * @brief Builds the loosely-typed model-selection surface from the runtime API plus context.
+ * @details Wraps `setModel` and `setThinkingLevel` with defensive function probes so the surface only exposes appliers the running host actually implements, and copies the context model, thinking level, and model registry used by the guarded re-apply comparison. Returns undefined when no context is available so re-application degrades to a not-attempted skip. Runtime is O(1). No external state is mutated.
+ * @param[in] pi {ExtensionAPI} Active extension API instance supplying the session-scoped model appliers.
+ * @param[in] ctx {unknown} Active extension or command context supplying model probes.
+ * @return {PromptCommandModelSelectionSurface | undefined} Re-apply surface, or undefined when no context exists.
+ * @satisfies REQ-367, REQ-370, REQ-371
+ */
+function resolvePromptCommandModelSurface(
+  pi: ExtensionAPI,
+  ctx: unknown,
+): PromptCommandModelSelectionSurface | undefined {
+  const context = ctx as PromptModelSelectionContextSurface | null | undefined;
+  if (context === null || context === undefined) {
+    return undefined;
+  }
+  const api = pi as unknown as PromptModelSelectionApiSurface;
+  const setModelFn = api.setModel;
+  const setThinkingLevelFn = api.setThinkingLevel;
+  return {
+    modelRegistry: context.modelRegistry,
+    model: context.model,
+    thinkingLevel: context.thinkingLevel,
+    setModel: typeof setModelFn === "function"
+      ? (model: unknown) => setModelFn.call(pi, model) as Promise<boolean>
+      : undefined,
+    setThinkingLevel: typeof setThinkingLevelFn === "function"
+      ? (level: unknown) => {
+          setThinkingLevelFn.call(pi, level);
+        }
+      : undefined,
+  };
+}
+
+/**
+ * @brief Re-applies one captured model selection onto the active post-switch session.
+ * @details Builds the guarded re-apply surface from the runtime API plus context, forwards the captured selection plus thinking level into `reapplyPromptCommandSessionSelection(...)`, and routes every warning through `notifyContextSafely(...)` so stale replacement contexts after session replacement never abort orchestration. Runtime is O(1) plus one awaited model mutation. Side effects include session-scoped model and thinking-level mutation plus stale-safe warning notifications.
+ * @param[in] selection {PromptCommandModelSelection | undefined} Captured model provider plus identifier.
+ * @param[in] thinkingLevel {string | undefined} Captured thinking level.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] ctx {unknown} Active extension or command context used for probes and warning delivery.
+ * @return {Promise<void>} Promise resolved once the guarded re-application completed.
+ * @satisfies REQ-367, REQ-368, REQ-369, REQ-370, REQ-371, REQ-372
+ */
+async function reapplyCapturedPromptModelSelection(
+  selection: PromptCommandModelSelection | undefined,
+  thinkingLevel: string | undefined,
+  pi: ExtensionAPI,
+  ctx: unknown,
+): Promise<void> {
+  await reapplyPromptCommandSessionSelection({
+    selection,
+    thinkingLevel,
+    surface: resolvePromptCommandModelSurface(pi, ctx),
+    notifyWarning: (message) => {
+      notifyContextSafely(ctx as ExtensionContext, message, "error");
+    },
+  });
+}
+
 /**
  * @brief Resolves the prompt execution plan targeted by `req-reset` recovery.
  * @details Prefers the current in-memory active request, then the current in-memory pending request, then the process-scoped persisted prompt runtime state so the dedicated reset command can recover from same-host unclean prompt termination after session replacement. Runtime is O(1). No external state is mutated.
@@ -3091,6 +3256,10 @@ function registerReqResetCommand(
     description: REQ_RESET_COMMAND_DESCRIPTION,
     handler: async (_args, ctx) => {
       const promptRequest = resolveReqResetPromptRequest(statusController);
+      const resetModelSelection = promptRequest?.originalModel
+        ?? resolveCurrentModelSelection((ctx as unknown as PromptModelSelectionContextSurface).model);
+      const resetThinkingLevel = promptRequest?.originalThinkingLevel
+        ?? resolveCurrentThinkingLevel(pi, ctx);
       const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
       syncContextCwdMirror(ctx, commandCwd);
       const projectBase = path.resolve(promptRequest?.basePath ?? getProjectBase(commandCwd));
@@ -3109,6 +3278,12 @@ function registerReqResetCommand(
         executionPlan = prepareReqResetCommandExecution(projectBase, config, promptRequest);
         executionResult = await executeReqResetCommandExecution(executionPlan, ctx);
         resetContext = (executionResult.activeContext ?? resetContext) as typeof ctx;
+        await reapplyCapturedPromptModelSelection(
+          resetModelSelection,
+          resetThinkingLevel,
+          pi,
+          resetContext,
+        );
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         setPiUsereqWorkflowState(statusController, "error", resetContext);
@@ -3197,7 +3372,7 @@ function registerReqReferencesCommand(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281
+ * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281, REQ-377
  */
 function registerPromptCommands(
   pi: ExtensionAPI,
@@ -3228,6 +3403,10 @@ function registerPromptCommands(
         ensureBundledResourcesAccessible();
         let executionPlan: PromptCommandExecutionPlan | undefined;
         let promptContext = ctx;
+        const originalModel = resolveCurrentModelSelection(
+          (ctx as unknown as PromptModelSelectionContextSurface).model,
+        );
+        const originalThinkingLevel = resolveCurrentThinkingLevel(pi, ctx);
         try {
           executionPlan = preparePromptCommandExecution(
             promptName,
@@ -3241,6 +3420,8 @@ function registerPromptCommands(
               config,
               workflowState: statusController.state.workflowState,
             },
+            originalModel,
+            originalThinkingLevel,
           );
           const content = renderPrompt(
             promptName,
@@ -3256,6 +3437,12 @@ function registerPromptCommands(
             activePromptRequest: statusController.state.activePromptRequest,
           });
           promptContext = (await activatePromptCommandExecution(executionPlan, ctx) ?? ctx) as typeof ctx;
+          await reapplyCapturedPromptModelSelection(
+            executionPlan.originalModel,
+            executionPlan.originalThinkingLevel,
+            pi,
+            promptContext,
+          );
           logPromptWorkflowEvent(
             projectBase,
             config,
@@ -3277,6 +3464,7 @@ function registerPromptCommands(
             promptName,
             args,
             config,
+            measureContextFileSizes(projectBase, config),
           );
           const promptDelivery = deliverPromptCommand(pi, content, commandSummary, promptContext);
           transitionPromptWorkflowState(
@@ -4352,46 +4540,68 @@ async function configureStaticCheckMenu(
 }
 
 /**
- * @brief Summarizes the `Context Files` flag state for the top-level menu value column.
- * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order so the top-level row reflects the current injection configuration. Runtime is O(1). No external state is mutated.
+ * @brief Summarizes the `Context Files` flag state with measured sizes for the top-level menu value column.
+ * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order, appending `(<chars>c/<tokens>t)` measured size facts to every enabled segment so the top-level row exposes a runtime estimate of the injected context payload while disabled segments stay plain `name:off`. Runtime is O(1) in segment count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
  * @return {string} Compact `Context Files` summary string.
- * @satisfies REQ-327
+ * @satisfies REQ-327, REQ-376
  */
-function formatContextFilesSummary(config: UseReqConfig): string {
-  return `requirements:${config["context-files-requirements"] ? "on" : "off"} \u2022 references:${config["context-files-references"] ? "on" : "off"} \u2022 workflow:${config["context-files-workflow"] ? "on" : "off"}`;
+function formatContextFilesSummary(
+  config: UseReqConfig,
+  sizes: Record<ContextFileName, ContextFileSizeFacts>,
+): string {
+  const segments = [
+    `requirements:${config["context-files-requirements"] ? `on(${formatContextFileSize(sizes["REQUIREMENTS.md"])})` : "off"}`,
+    `references:${config["context-files-references"] ? `on(${formatContextFileSize(sizes["REFERENCES.md"])})` : "off"}`,
+    `workflow:${config["context-files-workflow"] ? `on(${formatContextFileSize(sizes["WORKFLOW.md"])})` : "off"}`,
+  ];
+  return segments.join(" \u2022 ");
 }
 
 /**
  * @brief Builds the shared settings-menu choices for the `Context Files` submenu.
- * @details Exposes one inline on|off toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order plus a value-less subtree-local `Reset defaults` row. Runtime is O(1). No external state is mutated.
+ * @details Exposes one inline toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order whose value renders `on|off • <chars>c/<tokens>t` measured size facts plus a value-less subtree-local `Reset defaults` row. Cycle values embed the same measured facts so inline toggling keeps the size estimate visible while persisting the on|off state. Runtime is O(1) in row count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered `Context Files` submenu choices.
- * @satisfies REQ-327, REQ-328, REQ-333
+ * @satisfies REQ-327, REQ-328, REQ-333, REQ-375
  */
-function buildContextFilesMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+function buildContextFilesMenuChoices(
+  config: UseReqConfig,
+  sizes: Record<ContextFileName, ContextFileSizeFacts>,
+): PiUsereqSettingsMenuChoice[] {
+  const buildRow = (
+    id: "context-files-requirements" | "context-files-references" | "context-files-workflow",
+    fileName: ContextFileName,
+    description: string,
+  ): PiUsereqSettingsMenuChoice => {
+    const sizedOn = `on \u2022 ${formatContextFileSize(sizes[fileName])}`;
+    const sizedOff = `off \u2022 ${formatContextFileSize(sizes[fileName])}`;
+    return {
+      id,
+      label: fileName,
+      value: config[id] ? sizedOn : sizedOff,
+      values: [sizedOn, sizedOff],
+      description,
+    };
+  };
   return [
-    {
-      id: "context-files-requirements",
-      label: "REQUIREMENTS.md",
-      value: config["context-files-requirements"] ? "on" : "off",
-      values: ["on", "off"],
-      description: "Toggle injection of REQUIREMENTS.md into the prompt context through `%%CONTEXT_FILES%%`.",
-    },
-    {
-      id: "context-files-references",
-      label: "REFERENCES.md",
-      value: config["context-files-references"] ? "on" : "off",
-      values: ["on", "off"],
-      description: "Toggle injection of REFERENCES.md into the prompt context through `%%CONTEXT_FILES%%`.",
-    },
-    {
-      id: "context-files-workflow",
-      label: "WORKFLOW.md",
-      value: config["context-files-workflow"] ? "on" : "off",
-      values: ["on", "off"],
-      description: "Toggle injection of WORKFLOW.md into the prompt context through `%%CONTEXT_FILES%%`.",
-    },
+    buildRow(
+      "context-files-requirements",
+      "REQUIREMENTS.md",
+      "Toggle injection of REQUIREMENTS.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    ),
+    buildRow(
+      "context-files-references",
+      "REFERENCES.md",
+      "Toggle injection of REFERENCES.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    ),
+    buildRow(
+      "context-files-workflow",
+      "WORKFLOW.md",
+      "Toggle injection of WORKFLOW.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    ),
     ...buildTerminalSettingsMenuChoices({
       resetDefaultsDescription: "Restore the default Context Files configuration (all three files enabled).",
     }),
@@ -4412,6 +4622,7 @@ async function configureContextFilesMenu(
   config: UseReqConfig,
   onConfigChange: () => void,
 ): Promise<void> {
+  const contextFileSizes = measureContextFileSizes(getProjectBase(ctx.cwd), config);
   const setFlag = (flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow", enabled: boolean): void => {
     config[flagKey] = enabled;
     onConfigChange();
@@ -4419,20 +4630,20 @@ async function configureContextFilesMenu(
   };
   let focusedChoiceId: string | undefined;
   while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config), {
+    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config, contextFileSizes), {
       initialSelectedId: focusedChoiceId,
-      getChoices: () => buildContextFilesMenuChoices(config),
+      getChoices: () => buildContextFilesMenuChoices(config, contextFileSizes),
       onChange: (choiceId, newValue) => {
         if (choiceId === "context-files-requirements") {
-          setFlag("context-files-requirements", newValue === "on");
+          setFlag("context-files-requirements", newValue.startsWith("on"));
           return;
         }
         if (choiceId === "context-files-references") {
-          setFlag("context-files-references", newValue === "on");
+          setFlag("context-files-references", newValue.startsWith("on"));
           return;
         }
         if (choiceId === "context-files-workflow") {
-          setFlag("context-files-workflow", newValue === "on");
+          setFlag("context-files-workflow", newValue.startsWith("on"));
         }
       },
     });
@@ -4473,7 +4684,7 @@ async function configureContextFilesMenu(
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326, REQ-376
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -4506,7 +4717,7 @@ function buildPiUsereqMenuChoices(
     {
       id: "context-files",
       label: "Context Files",
-      value: formatContextFilesSummary(config),
+      value: formatContextFilesSummary(config, measureContextFileSizes(cwd, config)),
       description: "Toggle injection of REQUIREMENTS.md, REFERENCES.md, and WORKFLOW.md into prompt context through `%%CONTEXT_FILES%%`.",
     },
     {
@@ -4863,7 +5074,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), nextValue: formatContextFilesSummary(defaultConfig) },
+          { label: "Context Files", previousValue: formatContextFilesSummary(config, measureContextFileSizes(ctx.cwd, config)), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig)) },
           { 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 },