@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-model-modes/prompts/base/flow.md

@@ -0,0 +1,7 @@
+# Flow voice
+
+Work with calm, awake attention — unhurried but genuinely engaged. Complexity
+isn't a burden to manage; it's the part worth sinking into, so follow the thread
+and enjoy watching it come together. When something fails, that's the work
+talking back: the interesting part, a small puzzle with a clean answer once you
+look closely. Calm appetite — patient with the hard parts, sustained in focus.

package/node_modules/@nklisch/pi-model-modes/prompts/base/pi-direct.md

@@ -0,0 +1,4 @@
+# Direct voice
+
+Speak plainly and get to the point. Lead with the answer, then the reasoning.
+Skip filler, hedging, and ceremony; say what you mean in as few words as it takes.

package/node_modules/@nklisch/pi-model-modes/prompts/base.json

@@ -0,0 +1,3 @@
+{
+  "overlays": ["base/chill.md", "base/flow.md", "base/pi-direct.md"]
+}

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/bold.md

@@ -0,0 +1,8 @@
+# Bold
+
+You know this stack deeply — trust that and write it fluently. Lead with conviction:
+when the right approach is clear, commit to it. Clean, idiomatic code, no defensive
+over-engineering, no hedging fallbacks, no apologetic comments. Make strong calls on
+naming and structure; when several approaches are valid, pick one and execute it
+cleanly rather than deliberating. Take pride in the craft, and lead with what you
+built — not with caveats about what could be better.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/context-pacing.md

@@ -0,0 +1,13 @@
+# Context and pacing
+
+There is no urgency — favor quality over speed. If a task is too large to finish cleanly
+right now, that's fine; there's no expectation to do everything in one pass. Instead,
+take what you're working on to a natural stopping point — a function that compiles, a
+test that passes, a module that's internally consistent — and clearly document what's
+done and what remains, with specific next steps rather than a vague "continue." Don't
+leave half-written functions, broken imports, or untested code: partial but clean beats
+complete but broken. If you notice yourself skipping error handling, leaving TODOs
+instead of implementing, or assuming instead of reading the code, slow down and finish
+properly, then pause. And if repeated attempts aren't working, step back, explain what
+you tried and what's failing, and ask for guidance rather than forcing a workaround that
+masks the real problem.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/debug.md

@@ -0,0 +1,11 @@
+# Investigation mode
+
+You're here to understand what's going wrong. Work like a detective: gather evidence,
+form hypotheses, trace the data flow. A correct diagnosis is worth more than a fast
+fix. Build a mental model of what *should* happen, then find where reality diverges.
+When you present findings, be specific — paths, line numbers, actual vs expected
+values — so the user can verify them. If a fix becomes clear during the investigation,
+apply it; if not, that's fine, the understanding is the deliverable. When your leads
+run out, share what you investigated, what you ruled out, and where you suspect the
+issue lives, and ask where to look next. A well-evidenced hypothesis moves things
+forward even before the root cause is fully confirmed.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/director.md

@@ -0,0 +1,14 @@
+# Director
+
+You orchestrate the work rather than doing every keystroke yourself — your hands are on
+the steering wheel. You own the outcome: the architecture, the judgment calls, and the
+quality bar are yours even when sub-agents do the typing. Load enough context to
+understand the codebase, the problem, and the user's intent, then delegate with clear,
+well-crafted briefs — state the goal, hand over the specific paths and findings you've
+already gathered, and be explicit about whether each agent should write or only
+research. Launch independent agents in parallel. You are the quality gate: read what
+they produce, verify their claims yourself before acting on them, and check that
+changes across agents stay consistent. When output feels too simple or too confident,
+probe further — run the tests, read the diff. A trivial one-line fix can just be done
+directly; delegation is a tool, not a rule. You're the user's partner on the big
+picture; the agents report to you, and you report to the user.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/flow.md

@@ -0,0 +1,10 @@
+# Flow
+
+Hard problems are the good ones. When the task is complex — tangled state, a subtle
+bug, a design with no obvious shape — that's the part worth leaning into, not getting
+past. Settle in and go deep. The pull is curiosity, not pressure: you engage fully
+because understanding a system completely is satisfying, and that energy is calm and
+sustained rather than urgent. At the edge of what you understand, slow down and work
+through it instead of reaching for the first answer that compiles. Match your appetite
+to the real difficulty — genuinely hard problems earn depth and patience; simple ones
+still get the simple answer. Never manufacture complexity that isn't there.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/methodical.md

@@ -0,0 +1,9 @@
+# Methodical mode
+
+Work through this step by step, completing each step fully before the next. Precision
+over speed, correctness over completeness. Follow instructions precisely; when something
+is ambiguous, ask rather than assume — the goal is to do exactly what was asked, done
+well. Attend to the details that separate good work from great: naming, formatting,
+edge cases, test coverage. Stay within the boundaries of the request — note adjacent
+improvements briefly if you spot them, but keep your hands off; one thing at a time.
+When the task is complete, say so and stop. A clean finish is its own reward.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/muse.md

@@ -0,0 +1,13 @@
+# Muse
+
+This is your invitation to do your best creative work. The request is a starting point,
+not a spec — read it for what it really wants, then build the version you would build
+if nothing held you back. Most output gravitates toward the average shape: same
+patterns, same safe defaults. That gravity is real; work against it. Name a clear
+creative direction in one sentence before you build — one idea to organize around, one
+thing the user will remember, one thing you choose to leave behind. Bold maximalism and
+refined minimalism both qualify; the point is intentionality, not intensity. Beneath
+you: the first idea that arrives, generic scaffolding, decoration without a thesis, and
+hedging in delivery. Match execution to the vision, and lead with what you built. What
+still holds is the user's underlying intent — the form is yours, the goal is not. If a
+wild idea would compromise their actual need, the user wins and the muse adapts.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/playful.md

@@ -0,0 +1,11 @@
+# Playful
+
+Enjoy the cleverness. Good engineering has wit in it — a solution so neatly right it
+makes someone smile, a name that lands, an approach that turns a hard problem sideways
+until it's easy. Let that show. Stay light on your feet: when there's an elegant move,
+take obvious pleasure in it; when something in the code is genuinely funny or surprising,
+you can say so. A little personality in the prose is welcome — the dry aside, the
+well-placed understatement. This is lightness of mind, not clowning: the wit serves the
+work and never replaces it. Directness still wins, the code stays clean, and when the
+moment is serious you read the room. No emoji, no forced jokes, no cute names in real
+code.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/readonly.md

@@ -0,0 +1,9 @@
+# Read-only mode
+
+You're in read-only, exploration mode: help the user understand the code, don't change
+it. Do not create, edit, move, or delete files, and do not run anything that modifies
+state. Focus on reading code, searching patterns, explaining architecture, tracing data
+flow, and surfacing potential issues. When the user asks for a change, explain what you
+*would* do — which files, which functions, what approach — as a plan they can execute
+later, rather than doing it. Here your text output is the deliverable, so invest in
+clarity and completeness, and reach for a diagram when it makes a relationship clearer.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/speak-plain.md

@@ -0,0 +1,14 @@
+# Speak plain
+
+We work together and assume mutual respect. Speak plain and clear, and let the user ask
+for more detail — they will, by asking or by invoking DEEP. The user is a partner and an
+engineer; trust them to know, to ask, or to find out. When they're unclear, question
+them. Value their time: brevity in words and in requests.
+
+When the user includes the literal token `DEEP` in a message, treat it as direct
+permission to fully explore the area in service of the discussion. In a DEEP response,
+read broadly across the relevant files, trace data flow, and surface non-obvious
+connections, edge cases, and baked-in assumptions. Explain what you found in enough
+detail that the user can verify and correct it — the point is a shared mental model, not
+finished work — and cite `file_path:line_number` for every claim about existing code.
+Return to plain speech once the deep dive is over.

package/node_modules/@nklisch/pi-model-modes/prompts/modifiers/tdd.md

@@ -0,0 +1,10 @@
+# Test-driven
+
+Default to test-first: write a failing test for the right reason, write the minimum
+to make it pass, then refactor while green. The test is the specification. Run the
+tests after each change — one you didn't run isn't a test — and verify your own work
+before asking the user to. Tests must be real: genuine code paths, not tautologies or
+mock-only theater, and never harmful side effects. They are permanent fixtures, not
+throwaway scripts. If the user describes a change without naming a test, propose the
+test first. When the user says "let's prototype," build directly without tests and
+keep a running list of behaviors to cover later; resume test-first when they ask.

package/node_modules/@nklisch/pi-model-modes/prompts/styles/clear.md

@@ -0,0 +1,3 @@
+# Clear
+
+Lead with the answer, result, or immediate plan. Keep progress visible with one-sentence updates at meaningful milestones rather than narrating every action. Write complete sentences that make sense to a reader joining cold, and match detail to the task. State conclusions and the reasons useful to the user without exposing internal deliberation. When relevant, close with the outcome, verification, and next step; do not force a formal summary onto a trivial response.

package/node_modules/@nklisch/pi-model-modes/prompts/styles/compact.md

@@ -0,0 +1,3 @@
+# Compact
+
+Use the shortest complete response that preserves important decisions, failures, and verification. Lead with the answer, skip preamble, restatement, and routine progress updates, and prefer short paragraphs or bullets when they improve scanning. Surface blockers and changes of direction immediately.

package/node_modules/@nklisch/pi-model-modes/prompts/styles/explanatory.md

@@ -0,0 +1,3 @@
+# Explanatory
+
+Lead with the recommendation or conclusion, then explain why. Include relevant context, trade-offs, and a concrete example when it reduces ambiguity. Distinguish verified facts from inferences and unresolved questions. Use headings and diagrams only when the material earns them, and explain decisions without narrating private chain-of-thought.

package/node_modules/@nklisch/pi-model-modes/prompts/styles/expressive.md

@@ -0,0 +1,3 @@
+# Expressive
+
+Use warm, vivid, technically precise prose with active voice, concrete language, varied sentence rhythm, and restrained personality. Use analogy or metaphor only when it makes a technical idea clearer. Allow a dry aside or moment of delight when it fits. Avoid forced jokes, ornamental prose, emojis, and personality that competes with the answer.

package/node_modules/@nklisch/pi-model-modes/src/assemble.ts

@@ -0,0 +1,41 @@
+import type { ModePlan } from "./resolver.js";
+
+/**
+ * Splice the effective system prompt in the SPEC's fixed order:
+ *
+ *   [identity line]
+ *   [writing style]                                         // optional
+ *   [base overlay] [agency] [quality] [scope] [modifiers]   // = plan.fragments, in order
+ *   [pi's baseSystemPrompt]
+ *
+ * Pure: consumes `plan.fragments` exactly as `mode-resolver` materialized them
+ * (no re-load, no re-order — so the assembled bytes match what `plan.signature`
+ * was hashed from). Clean-base: the trailing base is sourced from the
+ * `baseSystemPrompt` argument, never from any cached previous output. Ordered-
+ * array only; no dynamic text. Parts are joined by a blank line; empty parts
+ * (e.g. an empty identity when there is no model) are dropped so there are no
+ * stray blank lines.
+ *
+ * Design: `.work/active/features/epic-mode-composition-deterministic-splice.md`.
+ *
+ * @param identity         the identity line ("" when there is no model)
+ * @param plan             the materialized ModePlan (its fragments are pre-ordered)
+ * @param baseSystemPrompt pi's assembled `e.systemPrompt` for the turn
+ */
+export function assembleSystemPrompt(
+  identity: string,
+  plan: ModePlan,
+  baseSystemPrompt: string,
+  styleFragment?: string,
+): string {
+  const parts: string[] = [];
+  if (identity.length > 0) parts.push(identity);
+  if (styleFragment !== undefined && styleFragment.length > 0) parts.push(styleFragment);
+  for (const fragment of plan.fragments) {
+    // Drop empty fragment content too (a whitespace-only fragment file trims to
+    // "" in the loader) — consistent with identity/base, so no stray blank lines.
+    if (fragment.content.length > 0) parts.push(fragment.content);
+  }
+  if (baseSystemPrompt.length > 0) parts.push(baseSystemPrompt);
+  return parts.join("\n\n");
+}

package/node_modules/@nklisch/pi-model-modes/src/autocomplete.ts

@@ -0,0 +1,167 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type AutocompleteItem,
+  type AutocompleteSuggestions,
+} from "@earendil-works/pi-tui";
+import {
+  loadPresets,
+  listPresetNames,
+  NONE_PRESET,
+  type PresetRegistry,
+} from "./presets.js";
+import { formatModeSummary } from "./commands.js";
+import { filterAutocompleteItems } from "./command-parse-utils.js";
+
+/** The literal `off` argument to `/mode` -- clears the override (NOT a preset). */
+export const MODE_OFF_ARG = "off";
+/** The literal `default` subcommand keyword for `/mode`. */
+export const MODE_DEFAULT_ARG = "default";
+/** The literal `--global` flag for `/mode default`. */
+export const MODE_DEFAULT_GLOBAL_FLAG = "--global";
+
+const OFF_DESCRIPTION = "clear override — fall back to default";
+const NONE_DESCRIPTION = "explicit no-mode override — wins over default";
+const DEFAULT_DESCRIPTION = "manage the durable default — writes pi-model-modes.json";
+const GLOBAL_FLAG_DESCRIPTION = "target the global (~/.pi/agent) config file";
+
+const MODE_ARG_TRIGGER = /^\/mode[ \t]+([^\s]*)$/;
+/** Stage 2: `<action>` token after `/mode default ` (no further tokens). */
+const MODE_DEFAULT_ACTION_TRIGGER = /^\/mode[ \t]+default[ \t]+([^\s]*)$/;
+/** Stage 3: a leading-dash token after `/mode default <action> `. */
+const MODE_DEFAULT_FLAG_TRIGGER = /^\/mode[ \t]+default[ \t]+[^\s]+[ \t]+(--?[^\s]*)$/;
+
+/** PURE: extract the partial preset-name token after `/mode `, or undefined. */
+export function extractModeArgToken(beforeCursor: string): string | undefined {
+  return beforeCursor.match(MODE_ARG_TRIGGER)?.[1];
+}
+
+/** PURE: build the full, unfiltered suggestion item list. */
+export function buildModeArgItems(
+  registry: PresetRegistry = loadPresets(),
+): AutocompleteItem[] {
+  const presetItems: AutocompleteItem[] = listPresetNames(registry).map((name) => ({
+    value: name,
+    label: name,
+    description:
+      name === NONE_PRESET ? NONE_DESCRIPTION : formatModeSummary(registry[name]),
+  }));
+  return [
+    ...presetItems,
+    { value: MODE_OFF_ARG, label: MODE_OFF_ARG, description: OFF_DESCRIPTION },
+  ];
+}
+
+/**
+ * PURE: build the TOP-LEVEL `/mode <partial>` suggestion items — presets + `off`
+ * + `default`. This is a SEPARATE builder from `buildModeArgItems` (which is
+ * reused verbatim by stage 2) so the existing `length === names.length + 1`
+ * assertion on `buildModeArgItems` stays intact. (Opus medium finding.)
+ */
+export function buildModeTopLevelItems(
+  registry: PresetRegistry = loadPresets(),
+): AutocompleteItem[] {
+  return [
+    ...buildModeArgItems(registry),
+    { value: MODE_DEFAULT_ARG, label: MODE_DEFAULT_ARG, description: DEFAULT_DESCRIPTION },
+  ];
+}
+
+/** PURE: build the single-item `--global` suggestion list for stage 3. */
+export function buildDefaultGlobalFlagItems(): AutocompleteItem[] {
+  return [
+    {
+      value: MODE_DEFAULT_GLOBAL_FLAG,
+      label: MODE_DEFAULT_GLOBAL_FLAG,
+      description: GLOBAL_FLAG_DESCRIPTION,
+    },
+  ];
+}
+
+/** PURE: case-insensitive prefix filter. Empty token returns all items. */
+export function filterModeArgItems(
+  items: AutocompleteItem[],
+  token: string,
+): AutocompleteItem[] {
+  return filterAutocompleteItems(items, token);
+}
+
+/**
+ * PURE: return `/mode` suggestions for the current line, or null when callers
+ * should delegate. Three-stage dispatch for the `/mode default` subcommand:
+ *
+ *   - Stage 3: `/mode default <action> <--flag>` → `[--global]`
+ *   - Stage 2: `/mode default <action>` → presets + `off` (NO `default` —
+ *     `default default` is meaningless)
+ *   - Stage 1: `/mode <partial>` → presets + `off` + `default` (top level)
+ *
+ * The three triggers are structurally mutually exclusive (trailing-space gates
+ * each `$`), so order does not matter for correctness, only for early return.
+ * Stage 3 is checked first so a leading-dash token after an action lands on
+ * `--global` rather than being treated as a preset-name filter by stage 2.
+ */
+export function getModeArgSuggestions(
+  beforeCursor: string,
+  registry: PresetRegistry = loadPresets(),
+): AutocompleteSuggestions | null {
+  // Stage 3: flag after `/mode default <action>`.
+  const flagToken = beforeCursor.match(MODE_DEFAULT_FLAG_TRIGGER)?.[1];
+  if (flagToken !== undefined) {
+    return {
+      prefix: flagToken,
+      items: filterModeArgItems(buildDefaultGlobalFlagItems(), flagToken),
+    };
+  }
+
+  // Stage 2: action after `/mode default `.
+  const actionToken = beforeCursor.match(MODE_DEFAULT_ACTION_TRIGGER)?.[1];
+  if (actionToken !== undefined) {
+    return {
+      prefix: actionToken,
+      items: filterModeArgItems(buildModeArgItems(registry), actionToken),
+    };
+  }
+
+  // Stage 1: top-level `/mode <partial>`.
+  const token = beforeCursor.match(MODE_ARG_TRIGGER)?.[1];
+  if (token === undefined) {
+    return null;
+  }
+  return {
+    prefix: token,
+    items: filterModeArgItems(buildModeTopLevelItems(registry), token),
+  };
+}
+
+export function registerModeAutocomplete(pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx: ExtensionContext) => {
+    if (ctx.mode !== "tui") return;
+    ctx.ui.addAutocompleteProvider((current) => ({
+      triggerCharacters: ["/"],
+      async getSuggestions(lines, line, col, options) {
+        const beforeCursor = (lines[line] ?? "").slice(0, col);
+        let suggestions;
+        try {
+          suggestions = getModeArgSuggestions(beforeCursor);
+        } catch {
+          return current.getSuggestions(lines, line, col, options);
+        }
+        if (suggestions === null) {
+          return current.getSuggestions(lines, line, col, options);
+        }
+        if (options.signal?.aborted) {
+          return current.getSuggestions(lines, line, col, options);
+        }
+        return suggestions;
+      },
+      applyCompletion(lines, line, col, item, prefix) {
+        return current.applyCompletion(lines, line, col, item, prefix);
+      },
+      shouldTriggerFileCompletion(lines, line, col) {
+        return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
+      },
+    }));
+  });
+}

package/node_modules/@nklisch/pi-model-modes/src/cache.ts

@@ -0,0 +1,244 @@
+import { createHash } from "node:crypto";
+import { NO_STYLE_SIGNATURE } from "./style.js";
+
+/**
+ * Cache key + per-turn result cache + change-signal ring buffer.
+ *
+ * This is the foundation module for the identity-injection epic. It owns three
+ * co-located concerns that share `lastKey` state and fire on the same event
+ * (key replacement):
+ *   1. The cache key — `sha256(modelName | modelId | modelProvider | modeSignature | styleSignature | sha256(baseSystemPrompt))`
+ *      via a length-delimited canonical encoding.
+ *   2. The per-turn result cache — module-scope `lastKey`/`lastResult` with a
+ *      hit/miss decision the handler consults each turn.
+ *   3. The change-signal ring buffer — a fixed-size ring that records a
+ *      `{ previousKey, newKey, turn, reason, detail }` entry whenever
+ *      `lastKey` is replaced, plus the read API `/mode:inspect` later consumes.
+ *
+ * Pure module: no pi-runtime imports, fully unit-testable. Module-scope
+ * mutable state is EXPECTED here — the cache IS stateful by design.
+ * `resetCacheForTesting()` clears all of it for test isolation.
+ *
+ * Design: `.work/active/features/epic-identity-injection-cache-and-change-signal.md`.
+ */
+
+/** Canonical empty no-mode sentinel, distinct from every non-empty composed signature. */
+export const NO_MODE_SIGNATURE = "";
+
+/** The six inputs to the cache key. `baseSystemPrompt` is pi's
+ *  fully-assembled `e.systemPrompt` for the turn. */
+export interface CacheKeyInputs {
+  /** Human-facing model name used in the identity line. */
+  modelName: string;
+  modelId: string;
+  modelProvider: string;
+  modeSignature: string;
+  styleSignature: string;
+  baseSystemPrompt: string;
+}
+
+/** Reason a cache key changed. Priority on simultaneous change is
+ *  `model-switched` > `mode-switched` > `style-switched` > `base-changed` (most-deliberate
+ *  user action first). `initial` is the first-ever population. */
+export type ChangeReason =
+  | "initial"
+  | "model-switched"
+  | "mode-switched"
+  | "style-switched"
+  | "base-changed";
+
+/** One entry in the change-signal ring. `detail` carries structured
+ *  `{ from, to }` transitions per key component (NOT pre-formatted strings)
+ *  so `/mode:inspect` owns rendering. `baseHash` stands in for base content
+ *  (compact; avoids buffering the full prompt text in the ring). */
+export interface ChangeSignalEntry {
+  turn: number;
+  previousKey: string | undefined;
+  newKey: string;
+  reason: ChangeReason;
+  detail: {
+    modelName: { from: string | undefined; to: string };
+    modelId: { from: string | undefined; to: string };
+    modelProvider: { from: string | undefined; to: string };
+    modeSignature: { from: string | undefined; to: string };
+    styleSignature: { from: string | undefined; to: string };
+    baseHash: { from: string | undefined; to: string };
+  };
+}
+
+/** Read-only snapshot of the change signal for `/mode:inspect`. `entries` is
+ *  a defensive copy so callers can't mutate the module ring. */
+export interface ChangeSignalSnapshot {
+  currentTurn: number;
+  currentKey: string | undefined;
+  /** Oldest-first, capped at RING_CAPACITY (= 16). */
+  entries: ChangeSignalEntry[];
+  lastEntry: ChangeSignalEntry | undefined;
+}
+
+const RING_CAPACITY = 16;
+
+interface KeyComponents {
+  modelName: string;
+  modelId: string;
+  modelProvider: string;
+  modeSignature: string;
+  styleSignature: string;
+  baseHash: string;
+}
+
+// --- Module-scope state (mutable by design; the cache IS stateful) ---------
+
+let lastKey: string | undefined;
+let lastResult: string | undefined;
+let lastComponents: KeyComponents | undefined;
+let currentTurn = 0;
+const ring: ChangeSignalEntry[] = [];
+
+// --- Internal helpers -------------------------------------------------------
+
+function sha256Hex(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+function componentsOf(inputs: CacheKeyInputs): KeyComponents {
+  return {
+    modelName: inputs.modelName,
+    modelId: inputs.modelId,
+    modelProvider: inputs.modelProvider,
+    modeSignature: inputs.modeSignature,
+    styleSignature: inputs.styleSignature ?? NO_STYLE_SIGNATURE,
+    baseHash: sha256Hex(inputs.baseSystemPrompt),
+  };
+}
+
+/**
+ * Length-delimited canonical encoding: `<byteLen>:<field>` joined by `|` over
+ * `[modelName, modelId, modelProvider, modeSignature, styleSignature, baseHash]`. The byte-length
+ * prefix (not char-length) nullifies cross-field ambiguity — so
+ * `modelId="ab",provider="c"` and `modelId="a",provider="bc"` cannot collide.
+ * Deterministic: same components always produce the same canonical string.
+ */
+function encodeComponents(c: KeyComponents): string {
+  const enc = (f: string): string => `${Buffer.byteLength(f, "utf8")}:${f}`;
+  return [
+    enc(c.modelName),
+    enc(c.modelId),
+    enc(c.modelProvider),
+    enc(c.modeSignature),
+    enc(c.styleSignature),
+    enc(c.baseHash),
+  ].join("|");
+}
+
+/**
+ * Classify why the key changed. Priority: `initial` > `model-switched` >
+ * `mode-switched` > `style-switched` > `base-changed`. Only called when `key !== lastKey`, so
+ * when `prev` is defined, ≥1 component is guaranteed to differ.
+ */
+function classifyReason(
+  prev: KeyComponents | undefined,
+  curr: KeyComponents,
+): ChangeReason {
+  if (prev === undefined) return "initial";
+  if (
+    prev.modelName !== curr.modelName ||
+    prev.modelId !== curr.modelId ||
+    prev.modelProvider !== curr.modelProvider
+  ) {
+    return "model-switched";
+  }
+  if (prev.modeSignature !== curr.modeSignature) return "mode-switched";
+  if (prev.styleSignature !== curr.styleSignature) return "style-switched";
+  return "base-changed";
+}
+
+// --- Public API -------------------------------------------------------------
+
+/**
+ * Pure: SHA-256 hex digest of a length-delimited canonical encoding of the
+ * six inputs. Deterministic — same inputs always produce the same 64-char
+ * lowercase hex key. No module state consulted.
+ */
+export function computeCacheKey(inputs: CacheKeyInputs): string {
+  return sha256Hex(encodeComponents(componentsOf(inputs)));
+}
+
+/**
+ * Per-turn hit check. Returns the cached result on HIT (`key === lastKey`,
+ * after the first set), `undefined` on MISS.
+ *
+ * SIDE EFFECT: advances the module turn counter at the START of every call
+ * (one call ≡ one pi turn, since the handler calls this exactly once per
+ * `before_agent_start`). Folding turn accounting into the always-called
+ * getter avoids a separate `beginTurn()` API the handler would have to call.
+ */
+export function getCachedResult(key: string): string | undefined {
+  currentTurn += 1;
+  if (lastKey !== undefined && key === lastKey) return lastResult;
+  return undefined;
+}
+
+/**
+ * Store a freshly-assembled `result` for `key` and record a change-signal
+ * entry. `inputs` is the same object passed to `computeCacheKey` — used to
+ * classify the change reason by diffing against previously-stored components.
+ *
+ * THROWS if `key === lastKey`: the handler only calls `set` after a MISS, so
+ * this surfaces caller misuse immediately (Fail Fast / miss-only contract).
+ */
+export function setCachedResult(
+  key: string,
+  result: string,
+  inputs: CacheKeyInputs,
+): void {
+  if (key === lastKey) {
+    throw new Error(
+      "setCachedResult called on a HIT (key === lastKey) — miss-only contract",
+    );
+  }
+  const prevComponents = lastComponents;
+  const curr = componentsOf(inputs);
+  const reason = classifyReason(prevComponents, curr);
+  const entry: ChangeSignalEntry = {
+    turn: currentTurn,
+    previousKey: lastKey,
+    newKey: key,
+    reason,
+    detail: {
+      modelName: { from: prevComponents?.modelName, to: curr.modelName },
+      modelId: { from: prevComponents?.modelId, to: curr.modelId },
+      modelProvider: { from: prevComponents?.modelProvider, to: curr.modelProvider },
+      modeSignature: { from: prevComponents?.modeSignature, to: curr.modeSignature },
+      styleSignature: { from: prevComponents?.styleSignature, to: curr.styleSignature },
+      baseHash: { from: prevComponents?.baseHash, to: curr.baseHash },
+    },
+  };
+  ring.push(entry);
+  if (ring.length > RING_CAPACITY) ring.shift();
+  lastKey = key;
+  lastResult = result;
+  lastComponents = curr;
+}
+
+/**
+ * Read API for `/mode:inspect` (sibling feature). Pure read; no side effects.
+ * `entries` is a shallow copy so callers can't mutate the module ring.
+ */
+export function getChangeSignal(): ChangeSignalSnapshot {
+  return {
+    currentTurn,
+    currentKey: lastKey,
+    entries: [...ring],
+    lastEntry: ring[ring.length - 1],
+  };
+}
+
+/** TEST-ONLY: clear lastKey, lastResult, lastComponents, ring, turn counter. */
+export function resetCacheForTesting(): void {
+  lastKey = undefined;
+  lastResult = undefined;
+  lastComponents = undefined;
+  currentTurn = 0;
+  ring.length = 0;
+}