@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/extension/src/bridge-context.ts

@@ -2,7 +2,7 @@
  * Shared mutable state for bridge modules.
  * Avoids passing 14+ closure variables to every extracted function.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ConnectionManager } from "./connection.js";
 
 export interface BridgeContext {
@@ -40,9 +40,11 @@ export interface BridgeContext {
   hasRegisteredOnce: boolean;
 }
 
-// Commands that the dashboard handles natively with superior UX.
-// These are filtered from the command list sent to dashboard clients.
-const DASHBOARD_NATIVE_COMMANDS = new Set(["roles"]);
+// Commands that the dashboard handles natively with superior UX, filtered from
+// the command list sent to dashboard clients AND from extension-slash detection.
+// Current set: { "roles" }. Bridge-registered `__dashboard_reload` is filtered
+// separately by the `__`-prefix rule. See change: fix-extension-slash-commands-in-dashboard.
+export const DASHBOARD_NATIVE_COMMANDS = new Set(["roles"]);
 
 /** Filter out hidden commands (names starting with __) and dashboard-native commands from commands list */
 export function filterHiddenCommands(commands: any[]): any[] {
@@ -52,6 +54,68 @@ export function filterHiddenCommands(commands: any[]): any[] {
   );
 }
 
+/**
+ * Pure predicate: does `text` name an extension-registered slash command?
+ *
+ * Returns true iff:
+ *   - `text` starts with `/` and contains no embedded newline
+ *   - the token after `/` (up to first space or end) appears in `commandList`
+ *     with `source === "extension"`
+ *   - that token is NOT in `DASHBOARD_NATIVE_COMMANDS` (and not `__`-prefixed)
+ *
+ * Pure: no pi calls, no mutation. See change: fix-extension-slash-commands-in-dashboard.
+ */
+export function isExtensionSlashCommand(
+  text: string,
+  commandList: ReadonlyArray<{ name: string; source?: string }>,
+): boolean {
+  if (typeof text !== "string" || !text.startsWith("/")) return false;
+  if (text.includes("\n")) return false;
+  const rest = text.slice(1);
+  const spaceIdx = rest.indexOf(" ");
+  const cmdName = spaceIdx === -1 ? rest : rest.slice(0, spaceIdx);
+  if (!cmdName) return false;
+  if (cmdName.startsWith("__")) return false;
+  if (DASHBOARD_NATIVE_COMMANDS.has(cmdName)) return false;
+  return commandList.some((c) => c?.name === cmdName && c?.source === "extension");
+}
+
+/**
+ * Feature-detect upstream `pi.dispatchCommand(text, opts)` (pi 0.71+).
+ * Returns true iff the field is a function on the supplied object.
+ * See change: fix-extension-slash-commands-in-dashboard.
+ */
+export function hasDispatchCommand(pi: unknown): boolean {
+  return typeof (pi as any)?.dispatchCommand === "function";
+}
+
+/**
+ * Pure predicate: is this bridge running inside a dashboard-spawned
+ * headless `pi --mode rpc` session?
+ *
+ * Both probes MUST be true:
+ *  1. `process.env.PI_DASHBOARD_SPAWNED === "1"` (set by
+ *     `process-manager.ts::buildSpawnEnv` for every dashboard-spawned session).
+ *  2. `process.argv` contains `--mode` adjacent to `rpc`.
+ *
+ * Either alone is insufficient: env-only matches dashboard-spawned tmux
+ * sessions; argv-only matches non-dashboard RPC invocations.
+ *
+ * Optional `env` / `argv` parameters exist purely for unit testing
+ * (defaulting to the live process state). See change:
+ * add-rpc-stdin-dispatch-with-keeper-sidecar (task 7.1).
+ */
+export function isHeadlessRpcSession(
+  env: NodeJS.ProcessEnv = process.env,
+  argv: ReadonlyArray<string> = process.argv,
+): boolean {
+  if (env.PI_DASHBOARD_SPAWNED !== "1") return false;
+  for (let i = 0; i < argv.length - 1; i++) {
+    if (argv[i] === "--mode" && argv[i + 1] === "rpc") return true;
+  }
+  return false;
+}
+
 /** Extract first user message text from session entries */
 export function extractFirstMessage(ctx: any): string | undefined {
   try {

package/packages/extension/src/bridge.ts

@@ -4,12 +4,14 @@
  * Global extension that connects to the dashboard server,
  * forwards all pi events, and relays commands back.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Loader } from "@mariozechner/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Loader } from "@earendil-works/pi-tui";
 import { ConnectionManager } from "./connection.js";
 import { detectSessionSource } from "./source-detector.js";
 import { mapEventToProtocol } from "./event-forwarder.js";
 import { createCommandHandler } from "./command-handler.js";
+import { RetryTracker } from "./retry-tracker.js";
+import { UsageLimitOrderer } from "./usage-limit-orderer.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -33,6 +35,7 @@ import { startMetricsMonitor, stopMetricsMonitor, collectMetrics } from "./proce
 import { scanChildProcesses } from "./process-scanner.js";
 import type { BridgeContext } from "./bridge-context.js";
 import { filterHiddenCommands, extractFirstMessage, getCurrentModelString } from "./bridge-context.js";
+import { tryDispatchExtensionCommand } from "./slash-dispatch.js";
 import { sendStateSync as _sendStateSync, replaySessionEntries as _replaySessionEntries, handleSessionChange as _handleSessionChange } from "./session-sync.js";
 import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged, sendJjStateIfChanged as _sendJjStateIfChanged, resetReconnectCaches as _resetReconnectCaches } from "./model-tracker.js";
 import { registerFlowEventListeners, FLOW_EVENT_MAP, SUBAGENT_EVENT_MAP } from "./flow-event-wiring.js";
@@ -191,6 +194,22 @@ function initBridge(pi: ExtensionAPI) {
   let hasRegisteredOnce = false; // see change: reattach-move-to-front
   let promptBus: PromptBus | undefined;
 
+  // Provider-retry synthesis trackers. pi's ExtensionAPI does not expose
+  // `auto_retry_*` events, so the bridge synthesizes them from observed
+  // `message_end` / `agent_end` events. See change: fix-provider-retry-infinite-loop.
+  const retryTracker = new RetryTracker();
+  const usageLimitOrderer = new UsageLimitOrderer();
+
+  /** Forward a synthesized auto_retry_* event using the standard event_forward shape. */
+  const sendSyntheticRetryEvent = (eventType: string, data: Record<string, unknown>): void => {
+    if (!isActive() || !sessionReady) return;
+    connection.send({
+      type: "event_forward",
+      sessionId,
+      event: { eventType, timestamp: Date.now(), data },
+    });
+  };
+
   // ── Per-message entry id tracking (for fix-per-message-fork) ──
   // Pi 0.69+ awaits extension handlers BEFORE sessionManager.appendMessage runs,
   // which means getLeafId() at emit time returns the previous leaf, not the
@@ -648,6 +667,14 @@ function initBridge(pi: ExtensionAPI) {
       if (cachedCtx?.abort) {
         cachedCtx.abort();
       }
+      // Clear retry-synthesis trackers — the user-initiated abort path
+      // already synthesizes its own auto_retry_end via command-handler.
+      // See change: fix-provider-retry-infinite-loop.
+      retryTracker.noteAbort(sessionId);
+      usageLimitOrderer.noteRetryEnd(sessionId);
+    },
+    isIdle: () => {
+      try { return cachedCtx?.isIdle?.() ?? false; } catch { return false; }
     },
     eventSink: (msg) => connection.send(msg),
     compact: (opts) => {
@@ -668,26 +695,37 @@ function initBridge(pi: ExtensionAPI) {
     spawnNew: () => {
       connection.send({ type: "spawn_new_session", sessionId, cwd: process.cwd() });
     },
-    sessionPrompt: (text) => {
-      // Route slash commands: management events, flow:run, then fallback
+    sessionPrompt: async (text) => {
+      // Route slash commands: management events, flow:run, extension dispatch, then fallback.
+      // See change: fix-extension-slash-commands-in-dashboard.
       if (text.startsWith("/") && pi.events) {
         const cmdText = text.slice(1);
         const spaceIdx = cmdText.indexOf(" ");
         const cmdName = spaceIdx === -1 ? cmdText : cmdText.slice(0, spaceIdx);
         const cmdArgs = spaceIdx === -1 ? "" : cmdText.slice(spaceIdx + 1);
 
-        // Flow management commands from buttons use flow_management message type.
-        // Typed /flows:new, /flows:edit, /flows:delete in chat input fall through
-        // to the slash command handler below, which invokes pi's command system
-        // via pi.sendUserMessage (with ui-proxy handling ctx.ui calls).
-
-        // Check if it's a user-defined flow via flow:list-flows
+        // Flow fast-path: typed /<user-defined-flow-name> wins over extension dispatch.
         const flowsList = getFlowsList();
         if (flowsList.some(f => f.name === cmdName)) {
           pi.events.emit("flow:run", { flowName: cmdName, task: cmdArgs.trim() || undefined });
           return;
         }
       }
+
+      // Extension-command dispatch (routing step 9). When matched, the helper
+      // emits its own command_feedback events and we MUST NOT fall through.
+      // The `connection` arg enables Path C (headless RPC → server-routed
+      // dispatch via the keeper UDS); see change:
+      // add-rpc-stdin-dispatch-with-keeper-sidecar.
+      const handled = await tryDispatchExtensionCommand(
+        pi,
+        text,
+        sessionId,
+        (msg) => connection.send(msg),
+        connection,
+      );
+      if (handled) return;
+
       // Fallback: send as user message (template-expanded).
       // Uses deliverAs:followUp so it queues properly when agent is streaming.
       // expandPromptTemplateFromDisk handles skill commands (/skill:xxx) and
@@ -802,7 +840,25 @@ function initBridge(pi: ExtensionAPI) {
       if (!sessionReady) return;
       // Track agent streaming state (survives reconnect/reload)
       if (eventType === "agent_start") getBridgeState().isAgentStreaming = true;
-      if (eventType === "agent_end") getBridgeState().isAgentStreaming = false;
+      if (eventType === "agent_end") {
+        getBridgeState().isAgentStreaming = false;
+        // Provider-retry synthesis: forward auto_retry_end BEFORE agent_end
+        // when retries were in flight, so the dashboard's retry banner
+        // clears before the error banner appears. The usage-limit orderer
+        // takes precedence (it carries the actual error string); the retry
+        // tracker handles the non-usage-limit case. See change:
+        // fix-provider-retry-infinite-loop.
+        const orderedSynth = usageLimitOrderer.maybeSynthesize(sessionId, (event as any));
+        if (orderedSynth) {
+          sendSyntheticRetryEvent(orderedSynth.eventType, orderedSynth.data);
+          retryTracker.noteAbort(sessionId); // clear tracker; orderer's event is authoritative
+        } else {
+          const trackerSynth = retryTracker.observeAgentEnd(sessionId, event as any);
+          if (trackerSynth) {
+            sendSyntheticRetryEvent(trackerSynth.eventType, trackerSynth.data);
+          }
+        }
+      }
       // For model_select, enrich the event data with thinkingLevel
       if (eventType === "model_select") {
         const enriched = { ...event, thinkingLevel: (pi as any).getThinkingLevel?.() };
@@ -872,6 +928,18 @@ function initBridge(pi: ExtensionAPI) {
           const enriched = { ...event, entryId, nonce };
           const protoMsg = mapEventToProtocol(sessionId, enriched);
           connection.send(protoMsg);
+          // After forwarding the original message_end, ask the retry tracker
+          // whether to synthesize an auto_retry_* event. See change:
+          // fix-provider-retry-infinite-loop.
+          const synthetic = retryTracker.observeMessageEnd(sessionId, messageRef as any);
+          if (synthetic) {
+            sendSyntheticRetryEvent(synthetic.eventType, synthetic.data);
+            if (synthetic.eventType === "auto_retry_start") {
+              usageLimitOrderer.noteRetryStart(sessionId);
+            } else {
+              usageLimitOrderer.noteRetryEnd(sessionId);
+            }
+          }
         }, 0);
         return;
       }

package/packages/extension/src/command-handler.ts

@@ -3,7 +3,7 @@
  */
 import { readdirSync } from "node:fs";
 import { join, relative } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type {
   ServerToExtensionMessage,
   ExtensionToServerMessage,
@@ -12,6 +12,7 @@ import { killProcessByPgid } from "./process-scanner.js";
 import type { FileEntry, PiSessionInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { filterHiddenCommands } from "./bridge-context.js";
 import { expandPromptTemplateFromDisk } from "./prompt-expander.js";
+import { tryDispatchExtensionCommand } from "./slash-dispatch.js";
 import { buildProviderCatalogue } from "./provider-register.js";
 
 const IGNORE_DIRS = new Set([".git", "node_modules", ".next", "dist", "build", ".cache", "__pycache__", ".venv"]);
@@ -145,6 +146,11 @@ export function createCommandHandler(
     getThinkingLevel?: () => string | undefined;
     shutdown?: () => void;
     abort?: () => void;
+    /**
+     * Probe agent idleness for the persistent-abort scheduler.
+     * See change: fix-provider-retry-infinite-loop.
+     */
+    isIdle?: () => boolean;
     getCwd?: () => string;
     /** Callback to send events (e.g., bash_output, command_feedback) back to server */
     eventSink?: (msg: ExtensionToServerMessage) => void;
@@ -156,11 +162,44 @@ export function createCommandHandler(
     spawnNew?: () => void;
     /** Switch model via pi.setModel() */
     setModel?: (provider: string, modelId: string) => Promise<void>;
-    /** Route slash commands through session.prompt() */
-    sessionPrompt?: (text: string) => void;
+    /**
+     * Route slash commands through pi's command system. May be sync or async.
+     * In bridge wiring this also runs the extension-command dispatch branch
+     * (see slash-dispatch.ts). The handler awaits the result so command_feedback
+     * events emitted by the dispatch path arrive before this turn returns.
+     * See change: fix-extension-slash-commands-in-dashboard.
+     */
+    sessionPrompt?: (text: string) => void | Promise<void>;
   },
 ): CommandHandler {
   const getSessionId = typeof sessionIdOrGetter === "function" ? sessionIdOrGetter : () => sessionIdOrGetter;
+
+  /**
+   * Persistent-abort scheduler. Re-invokes `options.abort()` at 200ms
+   * intervals for up to 2 seconds, breaking early when `options.isIdle()`
+   * returns true. Closes the retry race window in pi-coding-agent.
+   * See change: fix-provider-retry-infinite-loop.
+   */
+  const PERSISTENT_ABORT_INTERVAL_MS = 200;
+  const PERSISTENT_ABORT_MAX_MS = 2000;
+  function schedulePersistentAbort(opts: NonNullable<typeof options>): void {
+    if (!opts.abort) return;
+    const startedAt = Date.now();
+    const interval = setInterval(() => {
+      if (Date.now() - startedAt >= PERSISTENT_ABORT_MAX_MS) {
+        clearInterval(interval);
+        return;
+      }
+      try {
+        if (opts.isIdle?.()) {
+          clearInterval(interval);
+          return;
+        }
+      } catch { /* probe failure — keep trying */ }
+      try { opts.abort?.(); } catch { /* idempotent */ }
+    }, PERSISTENT_ABORT_INTERVAL_MS);
+  }
+
   return {
     async handle(msg: ServerToExtensionMessage): Promise<ExtensionToServerMessage | undefined> {
       const sessionId = getSessionId();
@@ -260,19 +299,29 @@ export function createCommandHandler(
 
           if (parsed.type === "slash") {
             if (options?.sessionPrompt) {
-              options.sessionPrompt(parsed.text);
+              // sessionPrompt (bridge) owns slash-dispatch + flow fast-path +
+              // template expansion. It also owns command_feedback emission for
+              // extension-command dispatch. Do NOT emit completed here — would
+              // duplicate the dispatch path's terminal event.
+              // See change: fix-extension-slash-commands-in-dashboard.
+              await options.sessionPrompt(parsed.text);
             } else {
-              pi.sendUserMessage(parsed.text);
+              // Test / non-bridge callers: apply the extension-command dispatch
+              // branch inline before falling through to sendUserMessage. Keeps
+              // both call sites in lockstep per spec routing-step 9.
+              const handled = await tryDispatchExtensionCommand(
+                pi,
+                parsed.text,
+                sessionId,
+                options?.eventSink,
+              );
+              if (!handled) {
+                // sendUserMessage exempt from gating: only typed single-line
+                // slashes that are NOT extension commands reach this — i.e.
+                // skills, prompt templates, unrecognized slashes.
+                pi.sendUserMessage(parsed.text);
+              }
             }
-            options?.eventSink?.({
-              type: "event_forward",
-              sessionId,
-              event: {
-                eventType: "command_feedback",
-                timestamp: Date.now(),
-                data: { command: parsed.text, status: "completed" },
-              },
-            });
             return undefined;
           }
 
@@ -280,6 +329,12 @@ export function createCommandHandler(
           // Multi-line slash commands (e.g. "/skill:foo\nuser text") are classified as
           // passthrough by parseSendPrompt to preserve images (the slash route strips them),
           // so we expand prompt templates / skills here before sending.
+          //
+          // sendUserMessage exempt from extension-dispatch gating: this path handles
+          // multi-line slashes and image-bearing messages. Per spec, only typed
+          // single-line slash text gates through extension dispatch — multi-line and
+          // image-bearing messages go raw to the LLM as before.
+          // See change: fix-extension-slash-commands-in-dashboard.
           let outgoing = msg.text;
           if (outgoing.startsWith("/")) {
             outgoing = expandPromptTemplateFromDisk(outgoing, process.cwd(), pi);
@@ -292,6 +347,31 @@ export function createCommandHandler(
           if (options?.abort) {
             options.abort();
           }
+          // Synthesize an immediate auto_retry_end so the dashboard clears
+          // any in-flight retry banner without waiting for pi's natural
+          // auto_retry_end (which is delayed by the abortable-sleep cancel
+          // window AND, on extension API, never reaches us at all — see
+          // https://github.com/badlogic/pi-mono/discussions/2073). The
+          // reducer no-ops auto_retry_end when retryState is undefined,
+          // so this is idempotent against later events.
+          if (options?.eventSink) {
+            options.eventSink({
+              type: "event_forward",
+              sessionId,
+              event: {
+                eventType: "auto_retry_end",
+                timestamp: Date.now(),
+                data: { success: false, attempt: -1, finalError: "Aborted by user" },
+              },
+            });
+          }
+          // Persistent-abort scheduler: pi-coding-agent's _retryAbortController
+          // is briefly `undefined` between sleep-end and the next
+          // agent.continue() call. An abort that arrives in that window is
+          // a no-op against the retry. Re-invoke abort every 200ms for up
+          // to 2s, breaking early when the agent is idle.
+          // See change: fix-provider-retry-infinite-loop.
+          if (options) schedulePersistentAbort(options);
           return undefined;
 
         case "request_commands": {
@@ -394,7 +474,7 @@ export function createCommandHandler(
         case "list_sessions": {
           try {
             // Dynamic import to avoid hard dependency at module load
-            const { SessionManager } = await import("@mariozechner/pi-coding-agent") as any;
+            const { SessionManager } = await import("@earendil-works/pi-coding-agent") as any;
             const cwd = msg.cwd || options?.getCwd?.() || process.cwd();
             const sessionInfos = await SessionManager.list(cwd);
             const sessions: PiSessionInfo[] = (sessionInfos || []).map((s: any) => ({

package/packages/extension/src/flow-event-wiring.ts

@@ -2,7 +2,7 @@
  * Flow event wiring: registers listeners for pi-flows events
  * and forwards them as protocol messages to the dashboard server.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { BridgeContext } from "./bridge-context.js";
 import { filterHiddenCommands } from "./bridge-context.js";
 import type { FlowInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";

package/packages/extension/src/multiselect-list.ts

@@ -23,7 +23,7 @@ interface Item {
 
 /**
  * Minimal shape of pi-tui's `Component` interface — we avoid importing from
- * `@mariozechner/pi-tui` directly so this module stays compile-friendly when
+ * `@earendil-works/pi-tui` directly so this module stays compile-friendly when
  * that peer dep isn't present (e.g. in unit tests running via vitest without
  * the full pi runtime).
  */

package/packages/extension/src/pi-env.d.ts

@@ -1,15 +1,8 @@
 // Ambient declarations for pi runtime packages.
-// The actual types are provided by whichever host (pi or OMP) loads this extension.
+// The actual types are provided by whichever host loads this extension.
 // tsconfig paths handles resolution when one of the packages is installed;
 // these declarations serve as fallback when neither is available (e.g. CI, dev without pi).
-declare module "@mariozechner/pi-coding-agent" {
-  export type ExtensionAPI = import("@oh-my-pi/pi-coding-agent").ExtensionAPI;
-}
-declare module "@mariozechner/pi-ai" {
-  export function StringEnum<T extends readonly string[]>(values: T, schema?: Record<string, unknown>): any;
-}
-
-declare module "@oh-my-pi/pi-coding-agent" {
+declare module "@earendil-works/pi-coding-agent" {
   export interface ModelRegistry {
     getAvailable(): Array<{ provider: string; id: string }>;
     refresh(): void;
@@ -35,3 +28,17 @@ declare module "@oh-my-pi/pi-coding-agent" {
     events: EventBus;
   }
 }
+
+// Legacy fork — re-exports the same ExtensionAPI shape so existing installs still type-check.
+declare module "@mariozechner/pi-coding-agent" {
+  export type ExtensionAPI = import("@earendil-works/pi-coding-agent").ExtensionAPI;
+  export type ModelRegistry = import("@earendil-works/pi-coding-agent").ModelRegistry;
+  export type EventBus = import("@earendil-works/pi-coding-agent").EventBus;
+}
+
+declare module "@earendil-works/pi-ai" {
+  export function StringEnum<T extends readonly string[]>(values: T, schema?: Record<string, unknown>): any;
+}
+declare module "@mariozechner/pi-ai" {
+  export function StringEnum<T extends readonly string[]>(values: T, schema?: Record<string, unknown>): any;
+}

package/packages/extension/src/prompt-expander.ts

@@ -6,7 +6,7 @@
  * by reading template/skill files directly and expanding them.
  */
 import { readFileSync, existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { readdirSync, statSync } from "node:fs";
 import { buildSkillBlock } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
@@ -54,6 +54,69 @@ function readTemplate(filePath: string): string {
   return match ? match[1].trim() : content.trim();
 }
 
+/**
+ * Build the deduped, ordered list of candidate names for `:` ↔ `-` alias resolution.
+ * Original form always comes first, preserving the user's typed punctuation as
+ * authoritative intent (see design Decision 4: original-form-first precedence).
+ */
+function candidateNames(name: string): string[] {
+  const variants = new Set<string>();
+  variants.add(name);
+  if (name.includes(":")) variants.add(name.replace(/:/g, "-"));
+  if (name.includes("-")) variants.add(name.replace(/-/g, ":"));
+  return [...variants];
+}
+
+type Resolution = {
+  filePath: string;
+  source: "prompt" | "skill";
+  resolvedName: string;
+};
+
+/**
+ * Resolve `templateName` against (a) local prompt/skill scan and (b) pi.getCommands().
+ *
+ * Probe order is OUTER-loop over candidate-name variants, INNER probe over the
+ * three stores. This guarantees original-form-first precedence: every store is
+ * consulted on the typed form before any remapped variant is consulted on any
+ * store. See design Decision 4.
+ */
+function resolveTemplate(
+  templateName: string,
+  templates: Map<string, string>,
+  pi: any | undefined,
+): Resolution | null {
+  for (const cand of candidateNames(templateName)) {
+    // Step 1: local-scan prompt/skill key (may be `skill:<dir>` for SKILL.md dirs).
+    const local = templates.get(cand);
+    if (local) {
+      return {
+        filePath: local,
+        source: cand.startsWith("skill:") ? "skill" : "prompt",
+        resolvedName: cand,
+      };
+    }
+    // Step 2: local SKILL.md directory keyed as `skill:<cand>`.
+    const localSkill = templates.get(`skill:${cand}`);
+    if (localSkill) {
+      return { filePath: localSkill, source: "skill", resolvedName: cand };
+    }
+    // Step 3: pi.getCommands() registry skill.
+    if (pi?.getCommands) {
+      try {
+        const commands = pi.getCommands();
+        const skill = commands.find(
+          (c: any) => c.name === cand && c.source === "skill" && c.path,
+        );
+        if (skill?.path && existsSync(skill.path)) {
+          return { filePath: skill.path, source: "skill", resolvedName: cand };
+        }
+      } catch { /* ignore */ }
+    }
+  }
+  return null;
+}
+
 /**
  * Expand a slash command by finding and reading the prompt template from disk.
  * Returns the expanded text, or the original text if no template found.
@@ -73,45 +136,21 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
   const argsString = m?.[2] ?? "";
 
   const templates = findPromptTemplates(cwd);
-  let filePath = templates.get(templateName);
-
-  // Support colon as alias for hyphen (e.g. /opsx:continue → opsx-continue)
-  if (!filePath && templateName.includes(":")) {
-    filePath = templates.get(templateName.replace(/:/g, "-"));
-  }
-
-  // Fallback: check pi.getCommands() for globally installed skills and package skills
-  // that aren't in the local .pi/skills/ directory.
-  if (!filePath && pi?.getCommands) {
-    try {
-      const commands = pi.getCommands();
-      const skill = commands.find(
-        (c: any) => c.name === templateName && c.source === "skill" && c.path,
-      );
-      if (skill?.path && existsSync(skill.path)) {
-        filePath = skill.path;
-      }
-    } catch { /* ignore */ }
-  }
-
-  if (!filePath) return text;
+  const resolution = resolveTemplate(templateName, templates, pi);
+  if (!resolution) return text;
 
   try {
-    const content = readTemplate(filePath);
+    const content = readTemplate(resolution.filePath);
 
-    // Skill detection: either the local-scan key starts with `skill:` or the
-    // pi.getCommands() fallback resolved a command whose `source === "skill"`
-    // (we re-check below). Skill expansions wrap in pi's `<skill>` envelope so
-    // the dashboard ingress path is byte-identical to pi's own _expandSkillCommand,
-    // which lets the client and server recover the slash-command form.
-    // See change: render-skill-invocations-collapsibly.
-    const isSkill = isSkillResolution(templateName, filePath, pi);
-    if (isSkill) {
-      const bareName = templateName.replace(/^skill:/, "");
+    if (resolution.source === "skill") {
+      // Strip leading `skill:` prefix (only present for local-scan step-1 hits
+      // whose key was `skill:<dir>`); registry hits and step-2 hits already
+      // hold the bare name.
+      const bareName = resolution.resolvedName.replace(/^skill:/, "");
       return buildSkillBlock({
         name: bareName,
-        filePath,
-        baseDir: dirname(filePath),
+        filePath: resolution.filePath,
+        baseDir: dirname(resolution.filePath),
         body: content,
         userArgs: argsString || undefined,
       });
@@ -126,31 +165,3 @@ export function expandPromptTemplateFromDisk(text: string, cwd: string, pi?: any
     return text;
   }
 }
-
-/**
- * Detect whether the resolved `filePath` came from a skill source.
- *
- * The local-scan key tells us directly when it starts with `skill:`. For the
- * pi.getCommands() fallback we re-query and check `source === "skill"` against
- * the same templateName.
- */
-function isSkillResolution(
-  templateName: string,
-  filePath: string,
-  pi: any | undefined,
-): boolean {
-  if (templateName.startsWith("skill:")) return true;
-  // The colon-alias path (e.g. /opsx:continue) maps to a hyphen filename and is
-  // a prompt template, not a skill. Skills always use the `skill:` prefix in
-  // both the local scan and pi.getCommands().
-  if (!pi?.getCommands) return false;
-  try {
-    const commands = pi.getCommands();
-    const match = commands.find(
-      (c: any) => c.name === templateName && c.source === "skill" && c.path === filePath,
-    );
-    return !!match;
-  } catch {
-    return false;
-  }
-}