@groeponline/pi-wishcraft 1.4.11 → 1.4.13

package/src/motion/policy.ts

@@ -8,7 +8,7 @@
  */
 
 import { CADENCE_MS, CHANNEL_MATRIX, PREVIEW_INTERVAL_MS } from "./catalog.ts";
-import type { MotionChannel, MotionEvent, MotionLevel, MotionPolicy, MotionToggles } from "./types.ts";
+import type { MotionChannel, MotionDef, MotionEvent, MotionLevel, MotionPolicy, MotionToggles } from "./types.ts";
 
 const CHANNEL_TOGGLE: Record<MotionChannel, keyof MotionToggles> = {
   workingGlyph: "state",
@@ -53,6 +53,33 @@ export function effectiveLevel(policy: MotionPolicy): MotionLevel {
   return policy.level;
 }
 
+/**
+ * Channels a motion is allowed to drive under the current policy.
+ *
+ * Same a11y filter as `allowedChannels`, but the source is the **motion's own
+ * declared channels** instead of the event table. This is what makes an
+ * explicit motion choice (preset signature or `appearance.motion` override)
+ * actually runnable: the event no longer vetoes a motion it wasn't paired
+ * with by the default matrix — the motion decides, the policy still filters.
+ */
+export function channelsForMotion(
+  motion: MotionDef,
+  policy: MotionPolicy,
+): MotionChannel[] {
+  if (policy.screenReader || policy.level === "off") return [];
+
+  const effective = effectiveLevel(policy);
+  return motion.channels.filter((channel) => {
+    if (effective === "functional") {
+      return channel === "workingGlyph" || channel === "panelIndicator";
+    }
+    if (effective === "reduced") {
+      if (channel === "ambient" || channel === "signal") return false;
+    }
+    return policy.toggles[CHANNEL_TOGGLE[channel]];
+  });
+}
+
 export function cadenceFor(
   channel: MotionChannel,
   policy: MotionPolicy,

package/src/render/motion-rail.ts

@@ -6,7 +6,8 @@
  * rail, streaming = travelling head + trail, compacting = inward heads.
  */
 
-import { sweepPosition, trailGlyph } from "../motion/index.ts";
+import { defaultMotionFor, getMotion } from "../motion/catalog.ts";
+import { frameAt, framesOf, sweepPosition, trailGlyph } from "../motion/frames.ts";
 import type { SignalRuntime } from "../signal/controller.ts";
 import type { SignalSpec } from "../config/types.ts";
 import { ansi, colorEnabled, getFgAnsiCode } from "../theme/colors.ts";
@@ -16,6 +17,7 @@ export function renderActivity(
   runtime: SignalRuntime,
   spec: SignalSpec,
   ascii = false,
+  width = 80,
 ): string {
   const label = runtime.activity || "ready";
   const open = spec.caps.leftOpen ?? "";
@@ -23,28 +25,70 @@ export function renderActivity(
   const dim = getFgAnsiCode("sep");
   const hot = getFgAnsiCode("accent");
   const reset = colorEnabled() ? ansi.reset : "";
-  // One glyph family, directional comet: light `─` track, fixed solid
-  // head, and a short box-drawing trail ONLY behind the head. Idle is a
-  // calm flat rail (no cycling glyphs — the old shade-block cloud read
-  // muddy across three unrelated glyph families).
-  const RAIL_WIDTH = 12;
+  // Adaptive rail width: ~20% of terminal, clamped [16, 40]. Wider
+  // terminals get a longer sweep so the motion reads at a glance.
+  const RAIL_WIDTH = Math.max(16, Math.min(40, Math.round(width * 0.2)));
   const track = ascii ? "-" : "─";
   const head = ascii ? "o" : "●";
   const railColor = runtime.active ? hot : dim;
+  const def = getMotion(runtime.motionId);
+  // The head glyph is the chosen motion's own frame — so ember-relay
+  // sweeps a ◇→◈→◆ sequence and hex-relay carries #-density, instead of
+  // every motion wearing the same generic comet. The trail reuses the
+  // motion's own past frames too, so each motion leaves its own wake.
+  // ASCII terminals fall back to the clean box-drawing comet — motion
+  // frames are a color-font feature.
+  const headGlyph = (tick: number, distance: number) => {
+    if (def && !ascii) return frameAt(def, Math.max(0, tick - distance), false);
+    return distance === 0 ? head : trailGlyph(distance, ascii);
+  };
+  const trailDepth = def?.generator?.trail ?? 4;
+  // Per-cell color gradient: hot head fading to dim through the palette.
+  // Distance 0 = accent, then model → path → sep so the wake cools off.
+  const cellColor = (distance: number): string => {
+    if (!colorEnabled()) return "";
+    if (distance <= 0) return hot;
+    if (distance <= 1) return getFgAnsiCode("model");
+    if (distance <= 2) return getFgAnsiCode("path");
+    return dim;
+  };
   let railBlock: string;
   if (!runtime.active) {
-    railBlock = track.repeat(RAIL_WIDTH);
+    // Idle: a frozen breathing wave of the ambient motion (wisp) frames.
+    // No animation consumer at idle, but a sine-sampled wave reads as
+    // "resting, not dead" — calmer than a full sweep, warmer than a flat track.
+    const ambient = getMotion(defaultMotionFor("idle"));
+    const ambientFrames = ambient ? framesOf(ambient) : null;
+    if (ambientFrames && colorEnabled()) {
+      const phase = Date.now() % 4000 / 4000;
+      const built: string[] = [];
+      for (let i = 0; i < RAIL_WIDTH; i++) {
+        const wave = Math.sin((i / RAIL_WIDTH) * Math.PI * 2 + phase * Math.PI * 2);
+        const frameIdx = Math.floor(((wave + 1) / 2) * ambientFrames.length) % ambientFrames.length;
+        const color = wave > 0.3 ? hot : dim;
+        built.push(`${color}${ambientFrames[frameIdx]}${reset}`);
+      }
+      railBlock = built.join("");
+    } else {
+      railBlock = track.repeat(RAIL_WIDTH);
+    }
   } else if (runtime.activity === "compacting") {
-    // Compact state: two heads travel inward and compress a heavy core —
-    // visually distinct from the sweep so compaction reads at a glance.
-    railBlock = renderCompactRail(runtime.tick, RAIL_WIDTH, ascii);
+    railBlock = renderCompactRail(runtime.tick, RAIL_WIDTH, ascii, headGlyph, cellColor);
   } else {
     const pos = sweepPosition(runtime.tick, RAIL_WIDTH, true);
     const built: string[] = [];
     for (let i = 0; i < RAIL_WIDTH; i++) {
-      if (i === pos) built.push(head);
-      else if (i < pos) built.push(trailGlyph(Math.min(pos - i, 4), ascii));
-      else built.push(track);
+      if (i === pos) built.push(`${cellColor(0)}${headGlyph(runtime.tick, 0)}${reset}`);
+      else if (i < pos) {
+        const distance = pos - i;
+        if (distance <= trailDepth) {
+          built.push(`${cellColor(distance)}${headGlyph(runtime.tick, distance)}${reset}`);
+        } else {
+          built.push(track);
+        }
+      } else {
+        built.push(track);
+      }
     }
     railBlock = built.join("");
   }
@@ -79,6 +123,8 @@ function renderCompactRail(
   tick: number,
   width: number,
   ascii: boolean,
+  headGlyph: (tick: number, i: number) => string,
+  cellColor: (distance: number) => string,
 ): string {
   const half = Math.floor(width / 2);
   // Heads oscillate from the edges toward center and back.
@@ -87,13 +133,21 @@ function renderCompactRail(
   const inward = phase < span ? phase : span * 2 - phase;
   const leftPos = inward;
   const rightPos = width - 1 - inward;
-  const head = ascii ? "*" : "●";
   const core = ascii ? "=" : "━";
   const track = ascii ? "-" : "─";
+  const reset = colorEnabled() ? ansi.reset : "";
+  // Color the core by distance from the nearest head — hottest at the
+  // heads, cooling toward center, so the compression reads thermally.
   let built = "";
   for (let i = 0; i < width; i++) {
-    if (i === leftPos || i === rightPos) built += head;
-    else built += i > leftPos && i < rightPos ? core : track;
+    if (i === leftPos || i === rightPos) {
+      built += `${cellColor(0)}${headGlyph(tick, 0)}${reset}`;
+    } else if (i > leftPos && i < rightPos) {
+      const nearestHead = Math.min(Math.abs(i - leftPos), Math.abs(i - rightPos));
+      built += `${cellColor(nearestHead)}${core}${reset}`;
+    } else {
+      built += track;
+    }
   }
   return built;
 }

package/src/render/v2-entry.ts

@@ -97,7 +97,7 @@ export function renderStatusLineV2(
 
   merged.leftSegments.forEach((id, i) => pushSegment(id, 10_000 - i));
 
-  const rail = renderActivity(runtime, options.signal, options.ascii);
+  const rail = renderActivity(runtime, options.signal, options.ascii, width);
   segments.push({ id: "signal", text: rail, priority: 5_000 });
   primary.push("signal");
 

package/src/signal/controller.ts

@@ -6,7 +6,7 @@
  */
 
 import {
-  allowedChannels,
+  channelsForMotion,
   defaultMotionFor,
   getMotion,
   type MotionEvent,
@@ -61,17 +61,17 @@ export function setSignalEvent(
   runtime.tick = 0;
   runtime.startedAt = Date.now();
   runtime.activity = options.activity ?? activityForEvent(event);
-  runtime.active = event !== "idle";
-
-  if (
-    event === "idle" ||
-    !allowedChannels(event, policy).includes("signal")
-  ) {
-    runtime.active = false;
-    return;
-  }
 
   const def = getMotion(runtime.motionId);
+  // The chosen motion's own channel declaration decides whether the rail
+  // runs — not the event table. `CHANNEL_MATRIX` still picks the default
+  // motion per event, but an explicit choice (preset signature or an
+  // `appearance.motion` override) is never vetoed by the matrix afterwards.
+  // The a11y policy (screen-reader, full→reduced, functional, toggles)
+  // filters both paths identically via `channelsForMotion`.
+  runtime.active =
+    def !== undefined && channelsForMotion(def, policy).includes("signal");
+  if (!runtime.active) return;
   // Wrap subscribe so a throw doesn't leave runtime.active=true with
   // release=null (a leaked state that would survive stopSignal).
   let release: (() => void) | null = null;

package/src/studio/component.ts

@@ -1,19 +1,24 @@
-/**
- * Fullscreen studio component (U5, KTD3). Non-overlay `ctx.ui.custom()` —
- * the editor-replacing variant, unlike the Deck's centered overlay. Panes are
- * placeholders here; U6-U10 fill list/detail/actions/advice content.
- */
+/** Fullscreen Skill Studio workbench. The component owns presentation and input;
+ * the existing skills modules remain the only discovery and mutation backend. */
 
 import { matchesKey } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  buildListRows,
+  filterListRows,
+} from "./list.ts";
+import { resolveReferences, type ResolvedReference } from "./inspect.ts";
+import { readSkillBody, type SkillEntry, type SkillUsage } from "../extension/skills/skill-registry.ts";
+import type { AdvicePane } from "./advice-pane.ts";
+import type { AdviseMode } from "./advise/prompts.ts";
 import {
   createStudioState,
   handleStudioKey,
   STUDIO_PANES,
 } from "./state.ts";
-import type { StudioKeyEvent, StudioState } from "./types.ts";
+import type { StudioKeyEvent, StudioPaneId, StudioState } from "./types.ts";
 
-const PANE_LABELS: Record<string, string> = {
+const PANE_LABELS: Record<StudioPaneId, string> = {
   list: "Skills",
   detail: "Detail",
   actions: "Actions",
@@ -25,11 +30,31 @@ const HELP_LINES: readonly string[] = [
   "",
   "  j / k or arrows   Move selection",
   "  /                 Filter skills",
-  "  Tab               Cycle pane focus",
+  "  Tab or 1-4        Focus a pane",
+  "  Enter             Open the selected skill",
+  "  n                 Create a skill",
+  "  e                 Edit the selected skill",
+  "  d                 Run doctor",
+  "  a                 Focus AI advice",
+  "  r                 Run advice · i insert answer",
   "  ?                 Toggle this help",
   "  q / Esc           Exit studio",
 ];
 
+export interface StudioComponentOptions {
+  entries?: readonly SkillEntry[];
+  usage?: ReadonlyMap<string, SkillUsage>;
+  advicePane?: AdvicePane;
+  adviceMode?: AdviseMode;
+  onRefresh?: () => readonly SkillEntry[];
+  onCreate?: () => Promise<void> | void;
+  onEdit?: (entry: SkillEntry) => Promise<void> | void;
+  onDoctor?: () => Promise<void> | void;
+  onAdvice?: (entry: SkillEntry, mode: AdviseMode, pane: AdvicePane) => Promise<void> | void;
+  onInsert?: (pane: AdvicePane) => Promise<void> | void;
+  onError?: (error: unknown) => void;
+}
+
 export function mapRawInput(data: string): StudioKeyEvent {
   if (matchesKey(data, "escape")) return { key: "escape" };
   if (matchesKey(data, "return")) return { key: "return" };
@@ -45,36 +70,132 @@ export function mapRawInput(data: string): StudioKeyEvent {
   return { key: "other" };
 }
 
-export function renderStudioFrame(theme: Theme, width: number, state: StudioState): string[] {
-  if (state.mode === "help") {
-    const lines = [theme.fg("accent", HELP_LINES[0] ?? ""), ""];
-    for (const line of HELP_LINES.slice(2)) {
-      lines.push(theme.fg("muted", line));
-    }
-    lines.push("", theme.fg("dim", "Press q, Esc, or Enter to close help"));
+function fit(text: string, width: number): string {
+  if (width <= 0) return "";
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`;
+}
+
+function safeReadReferences(entry: SkillEntry): ResolvedReference[] {
+  return resolveReferences(readSkillBody(entry.filePath), entry.baseDir);
+}
+
+function selectedEntry(
+  entries: readonly SkillEntry[],
+  query: string,
+  selectedIndex: number,
+): SkillEntry | null {
+  const rows = filterListRows(buildListRows(entries), query);
+  const row = rows[selectedIndex] ?? rows[0];
+  return entries.find((entry) => entry.filePath === row?.filePath) ?? null;
+}
+
+function renderHelp(theme: Theme): string[] {
+  return HELP_LINES.map((line, index) => {
+    if (index === 0) return theme.fg("accent", line);
+    return theme.fg(index === HELP_LINES.length - 1 ? "dim" : "muted", line);
+  });
+}
+
+function renderList(
+  theme: Theme,
+  width: number,
+  entries: readonly SkillEntry[],
+  state: StudioState,
+): string[] {
+  const rows = filterListRows(buildListRows(entries), state.filterQuery);
+  const visible = rows.slice(Math.max(0, state.selectedIndex - 5), state.selectedIndex + 7);
+  const lines = [theme.fg("accent", `SKILLS · ${rows.length}/${entries.length}`)];
+  if (state.filterQuery) lines.push(theme.fg("muted", `filter: ${state.filterQuery}`));
+  if (rows.length === 0) {
+    lines.push(theme.fg("warning", "No skills match this filter"));
     return lines;
   }
+  for (const row of visible) {
+    const absolute = rows.indexOf(row);
+    const marker = absolute === state.selectedIndex ? "›" : " ";
+    const warning = row.warning ? theme.fg("warning", " ⚠") : "";
+    lines.push(
+      `${theme.fg(absolute === state.selectedIndex ? "accent" : "text", `${marker} ${fit(row.name, Math.max(8, width - 18))}`)} ${theme.fg("dim", `[${row.badge}]`)}${warning}`,
+    );
+    if (absolute === state.selectedIndex && row.description) {
+      lines.push(theme.fg("muted", `  ${fit(row.description, Math.max(8, width - 4))}`));
+    }
+  }
+  return lines;
+}
 
-  const focusMark = (pane: string): string =>
-    state.focus === pane ? theme.fg("accent", `[${PANE_LABELS[pane] ?? pane}]`) : theme.fg("dim", ` ${PANE_LABELS[pane] ?? pane} `);
+function renderDetail(theme: Theme, width: number, entry: SkillEntry | null, usage: ReadonlyMap<string, SkillUsage>): string[] {
+  if (!entry) return [theme.fg("accent", "DETAIL"), theme.fg("dim", "Select a skill from the list")];
+  const body = readSkillBody(entry.filePath);
+  const refs = safeReadReferences(entry);
+  const use = usage.get(entry.name);
+  const health = entry.warning ? theme.fg("warning", "warn") : theme.fg("success", "ok");
+  const override = entry.category === "project" ? "project override" : entry.category === "global" ? "global default" : "standalone";
+  const lines = [
+    theme.fg("accent", `DETAIL · ${fit(entry.name, Math.max(8, width - 10))}`),
+    theme.fg("muted", fit(entry.description || "No description", width)),
+    theme.fg("dim", `health: ${health} · ${override} · used: ${use?.count ?? 0}×`),
+    theme.fg("dim", `file: ${fit(entry.filePath, Math.max(8, width - 6))}`),
+    theme.fg("dim", `frontmatter: ${entry.frontmatterKeys.join(", ") || "none"}`),
+    theme.fg("dim", `model invocation: ${entry.disableModelInvocation ? "off" : "on"}`),
+    theme.fg("accent", `REFERENCES · ${refs.length}`),
+  ];
+  if (refs.length === 0) lines.push(theme.fg("dim", "  none detected"));
+  for (const ref of refs.slice(0, 5)) {
+    lines.push(theme.fg(ref.exists ? "muted" : "warning", `  ${ref.exists ? "✓" : "✗"} ${fit(ref.href, Math.max(8, width - 6))}`));
+  }
+  return lines;
+}
+
+function adviceModeLabel(mode: AdviseMode): string {
+  return mode === "explain" ? "explain" : mode === "integrate" ? "integrate" : mode === "examples" ? "examples" : "improve";
+}
 
-  const header = STUDIO_PANES.map((pane) => focusMark(pane)).join(" ");
-  const filterLine = state.mode === "filter"
-    ? theme.fg("accent", `filter: ${state.filterQuery}_`)
-    : state.filterQuery
-      ? theme.fg("muted", `filter: ${state.filterQuery}`)
-      : theme.fg("dim", "press / to filter, ? for help");
+function renderAdvice(theme: Theme, width: number, entry: SkillEntry | null, pane: AdvicePane, mode: AdviseMode): string[] {
+  const lines = [
+    theme.fg("accent", `AI ADVICE · ${adviceModeLabel(mode)}`),
+    entry ? theme.fg("muted", `skill: ${entry.name}`) : theme.fg("dim", "Select a skill first"),
+    theme.fg("dim", "r run · e explain · g integrate · x examples · m improve · i insert"),
+  ];
+  if (pane.state === "running") lines.push(theme.fg("accent", "Thinking…"));
+  if (pane.state === "unavailable") lines.push(theme.fg("warning", `Advice unavailable: ${pane.error ?? "unknown error"}`));
+  const text = pane.text.trim();
+  if (text) {
+    lines.push(theme.fg("text", fit(text.replace(/\n/g, " "), Math.max(8, width - 2))));
+  } else if (pane.state === "idle") {
+    lines.push(theme.fg("dim", "Advice uses the selected skill and its local references."));
+  }
+  return lines;
+}
 
-  const lines: string[] = [
+export function renderStudioFrame(
+  theme: Theme,
+  width: number,
+  state: StudioState,
+  options: Pick<StudioComponentOptions, "entries" | "usage" | "advicePane" | "adviceMode"> = {},
+): string[] {
+  if (state.mode === "help") return renderHelp(theme);
+  const entries = options.entries ?? [];
+  const usage = options.usage ?? new Map<string, SkillUsage>();
+  const pane = options.advicePane ?? { state: "idle", text: "", error: null } as AdvicePane;
+  const entry = selectedEntry(entries, state.filterQuery, state.selectedIndex);
+  const mode: AdviseMode = options.adviceMode ?? "explain";
+  const innerWidth = Math.max(20, width - 2);
+  const lines = [
     theme.fg("accent", "Skill Studio"),
-    header,
-    filterLine,
-    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
-    theme.fg("muted", `selected: ${state.selectedIndex}`),
-    theme.fg("dim", "panes populate in upcoming units (browse, actions, advice)"),
-    theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 60)))),
-    theme.fg("dim", "q/Esc exit · / filter · Tab focus · ? help"),
+    STUDIO_PANES.map((paneId) => state.focus === paneId ? theme.fg("accent", `[${PANE_LABELS[paneId]}]`) : theme.fg("dim", ` ${PANE_LABELS[paneId]} `)).join(" "),
+    theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))),
   ];
+  lines.push(...renderList(theme, innerWidth, entries, state));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(...renderDetail(theme, innerWidth, entry, usage));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(theme.fg("accent", "ACTIONS"));
+  lines.push(theme.fg("muted", "n create · e edit · d doctor · Enter detail"));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(...renderAdvice(theme, innerWidth, entry, pane, mode));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(theme.fg("dim", "q/Esc exit · / filter · Tab focus · ? help"));
   return lines;
 }
 
@@ -82,22 +203,77 @@ export function createStudioComponent(
   theme: Theme,
   done: (value: string | null) => void,
   onStateChange?: (state: StudioState) => void,
+  options: StudioComponentOptions = {},
 ) {
   let state = createStudioState();
+  let entries = [...(options.entries ?? [])];
+  let adviceMode: AdviseMode = "explain";
+  let finished = false;
+  const pane = options.advicePane ?? {
+    state: "idle",
+    text: "",
+    error: null,
+    run: async () => {},
+    reset: () => {},
+  } as AdvicePane;
+
+  const refresh = () => {
+    const next = options.onRefresh?.();
+    if (next) entries = [...next];
+  };
+  const current = () => selectedEntry(entries, state.filterQuery, state.selectedIndex);
+  const notifyChange = (next: StudioState) => {
+    state = next;
+    onStateChange?.(state);
+  };
+  const invoke = (work: () => Promise<void> | void) => {
+    void Promise.resolve(work()).then(() => {
+      refresh();
+    }).catch((error: unknown) => options.onError?.(error));
+  };
+  const focus = (paneId: StudioPaneId) => notifyChange({ ...state, focus: paneId });
+  const runAdvice = () => {
+    const entry = current();
+    if (!entry || !options.onAdvice) return;
+    invoke(() => options.onAdvice!(entry, adviceMode, pane));
+  };
 
   return {
     focused: true,
     invalidate() {},
     render(width: number) {
-      return renderStudioFrame(theme, width, state);
+      return renderStudioFrame(theme, width, state, { entries, usage: options.usage, advicePane: pane, adviceMode });
     },
     handleInput(data: string) {
-      const next = handleStudioKey(state, mapRawInput(data));
-      if (next !== state) {
-        state = next;
-        onStateChange?.(state);
+      if (state.mode === "normal") {
+        if (data >= "1" && data <= "4") {
+          focus(STUDIO_PANES[Number(data) - 1] ?? "list");
+          return;
+        }
+        if (data === "\r" || matchesKey(data, "return")) {
+          if (state.focus === "list") focus("detail");
+          return;
+        }
+        if (state.focus === "advice") {
+          if (data === "e") adviceMode = "explain";
+          else if (data === "g") adviceMode = "integrate";
+          else if (data === "x") adviceMode = "examples";
+          else if (data === "m") adviceMode = "improve";
+          else if (data === "r") runAdvice();
+          else if (data === "i" && options.onInsert) invoke(() => options.onInsert!(pane));
+        } else if (state.focus === "actions" || state.focus === "detail" || state.focus === "list") {
+          if (data === "n" && options.onCreate) invoke(() => options.onCreate!());
+          else if (data === "e" && current() && options.onEdit) invoke(() => options.onEdit!(current()!));
+          else if (data === "d" && options.onDoctor) invoke(() => options.onDoctor!());
+          else if (data === "a") focus("advice");
+          else if (data === "i" && pane.state === "ok" && options.onInsert) invoke(() => options.onInsert!(pane));
+          else if (state.focus === "detail" && data === "r") runAdvice();
+        }
       }
-      if (state.exitRequested) {
+      const next = handleStudioKey(state, mapRawInput(data));
+      if (next !== state) notifyChange(next);
+      if (state.exitRequested && !finished) {
+        finished = true;
         done(null);
       }
     },

package/src/studio/deepwiki/cache.ts

@@ -1,11 +1,21 @@
-/** DeepWiki disk cache (U9). TTL + stale fallback, no LRU (ponytail: add when
- *  the cache directory count actually grows). */
+/** DeepWiki disk cache (U9). TTL + stale fallback + bounded LRU eviction. */
 
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 import { getAgentPath } from "../../paths/agent-dirs.ts";
 import type { RepoRef } from "./extract.ts";
 
+const DEFAULT_MAX_ENTRIES = 64;
+
 export function resolveCacheDir(override?: string): string {
   return override ?? getAgentPath("wishcraft-cache", "deepwiki");
 }
@@ -21,32 +31,96 @@ export interface CacheReadResult<T> {
   entry: CacheFile<T> | null;
 }
 
+export interface CacheOptions {
+  ttlMs: number;
+  now?: number;
+  maxEntries?: number;
+}
+
 function fileFor(dir: string, repo: RepoRef): string {
   return join(dir, repo.owner, `${repo.repo}.json`);
 }
 
+function cacheFiles(dir: string): string[] {
+  const files: string[] = [];
+  let owners: string[];
+  try {
+    owners = readdirSync(dir);
+  } catch {
+    return files;
+  }
+  for (const owner of owners) {
+    const ownerDir = join(dir, owner);
+    let entries: string[];
+    try {
+      entries = readdirSync(ownerDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith(".json")) files.push(join(ownerDir, entry));
+    }
+  }
+  return files;
+}
+
+/** Remove least-recently-used entries until the cache is within its cap. */
+export function evictCacheEntries(dir: string, maxEntries = DEFAULT_MAX_ENTRIES): void {
+  const cap = Math.max(1, Math.floor(maxEntries));
+  const files = cacheFiles(dir);
+  if (files.length <= cap) return;
+  const ordered = files
+    .map((file) => {
+      try {
+        return { file, atimeMs: statSync(file).atimeMs, mtimeMs: statSync(file).mtimeMs };
+      } catch {
+        return { file, atimeMs: 0, mtimeMs: 0 };
+      }
+    })
+    .sort((a, b) => (a.atimeMs - b.atimeMs) || (a.mtimeMs - b.mtimeMs));
+  for (const item of ordered.slice(0, files.length - cap)) {
+    try {
+      unlinkSync(item.file);
+    } catch {
+      // A concurrent cleanup must not break advice or cache reads.
+    }
+  }
+}
+
+function touch(file: string, now: number): void {
+  try {
+    const date = new Date(now);
+    utimesSync(file, date, date);
+  } catch {
+    // Cache recency is best-effort metadata.
+  }
+}
+
 export async function writeCacheEntry<T>(
   dir: string,
   repo: RepoRef,
   data: T,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
 ): Promise<void> {
   const now = options.now ?? Date.now();
   const file = fileFor(dir, repo);
   mkdirSync(join(dir, repo.owner), { recursive: true });
   writeFileSync(file, JSON.stringify({ savedAt: now, data }), "utf8");
+  touch(file, now);
+  evictCacheEntries(dir, options.maxEntries);
 }
 
 export async function readCacheEntry<T>(
   dir: string,
   repo: RepoRef,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
 ): Promise<CacheReadResult<T>> {
   const now = options.now ?? Date.now();
   const file = fileFor(dir, repo);
   if (!existsSync(file)) return { status: "miss", stale: false, entry: null };
   try {
     const raw = JSON.parse(readFileSync(file, "utf8")) as CacheFile<T>;
+    touch(file, now);
     const fresh = now - raw.savedAt <= options.ttlMs;
     return { status: fresh ? "hit" : "miss", stale: !fresh, entry: raw };
   } catch {
@@ -57,7 +131,7 @@ export async function readCacheEntry<T>(
 export async function withCache<T>(
   dir: string,
   repo: RepoRef,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
   networkFetch: () => Promise<T>,
 ): Promise<CacheReadResult<T>> {
   const fresh = await readCacheEntry<T>(dir, repo, options);