@blackbelt-technology/pi-agent-dashboard 0.5.1 → 0.5.3

package/packages/extension/src/__tests__/bridge-slash-command-routing.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Regression test pinning the slash-command routing contract.
+ * Drives `command-handler.handle({type:"send_prompt"...})` against a stub pi
+ * and asserts the call counts + emitted command_feedback events from
+ * `design.md` Decision 5 table.
+ *
+ * regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createCommandHandler } from "../command-handler.js";
+import { hasDispatchCommand } from "../bridge-context.js";
+import { tryDispatchExtensionCommand, type DispatchConnection } from "../slash-dispatch.js";
+import type { ExtensionToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+
+interface StubOpts {
+  withDispatch?: boolean;
+  dispatchRejects?: Error;
+  getCommandsThrows?: boolean;
+  commands?: Array<{ name: string; source: string }>;
+}
+
+function makeStubPi(opts: StubOpts = {}) {
+  const dispatchCommand = opts.withDispatch
+    ? vi.fn(async (_text: string, _options?: any) => {
+        if (opts.dispatchRejects) throw opts.dispatchRejects;
+      })
+    : undefined;
+  const sendUserMessage = vi.fn();
+  const setSessionName = vi.fn();
+  const events = { emit: vi.fn() };
+  const getCommands = vi.fn(() => {
+    if (opts.getCommandsThrows) throw new Error("stale ctx");
+    return opts.commands ?? [
+      { name: "ctx-stats", source: "extension" },
+      { name: "skill:foo", source: "skill" },
+      { name: "review", source: "prompt" },
+      { name: "__dashboard_reload", source: "extension" },
+    ];
+  });
+  const pi: any = {
+    sendUserMessage,
+    getCommands,
+    setSessionName,
+    events,
+  };
+  if (dispatchCommand) pi.dispatchCommand = dispatchCommand;
+  return { pi, sendUserMessage, dispatchCommand, getCommands, events };
+}
+
+function feedbackEvents(sink: ReturnType<typeof vi.fn>, command: string) {
+  return sink.mock.calls
+    .map((c) => c[0] as ExtensionToServerMessage)
+    .filter(
+      (m) =>
+        m.type === "event_forward" &&
+        (m as any).event?.eventType === "command_feedback" &&
+        ((m as any).event?.data?.command === command),
+    )
+    .map((m) => (m as any).event.data);
+}
+
+async function drive(text: string, stub: ReturnType<typeof makeStubPi>) {
+  const sink = vi.fn();
+  const handler = createCommandHandler(stub.pi as any, "s1", { eventSink: sink });
+  await handler.handle({ type: "send_prompt", sessionId: "s1", text } as any);
+  return sink;
+}
+
+describe("bridge slash command routing (regression contract)", () => {
+  it("extension cmd with dispatchCommand → dispatch called, no sendUserMessage, started+completed", async () => {
+    // regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/ctx-stats", stub);
+
+    expect(stub.dispatchCommand).toHaveBeenCalledTimes(1);
+    expect(stub.dispatchCommand).toHaveBeenCalledWith("/ctx-stats", { streamingBehavior: "followUp" });
+    expect(stub.sendUserMessage).not.toHaveBeenCalled();
+
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.map((e) => e.status)).toEqual(["started", "completed"]);
+  });
+
+  it("extension cmd, NO dispatchCommand → stopgap error, no sendUserMessage, started+error", async () => {
+    // regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+    const stub = makeStubPi({ withDispatch: false });
+    const sink = await drive("/ctx-stats", stub);
+
+    expect(stub.sendUserMessage).not.toHaveBeenCalled();
+
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.map((e) => e.status)).toEqual(["started", "error"]);
+    expect(evs[1].message).toMatch(/pi 0\.71\+/);
+  });
+
+  it("extension cmd dispatch rejects → started+error with err.message, no sendUserMessage", async () => {
+    const stub = makeStubPi({ withDispatch: true, dispatchRejects: new Error("boom") });
+    const sink = await drive("/ctx-stats", stub);
+
+    expect(stub.dispatchCommand).toHaveBeenCalledTimes(1);
+    expect(stub.sendUserMessage).not.toHaveBeenCalled();
+
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.map((e) => e.status)).toEqual(["started", "error"]);
+    expect(evs[1].message).toBe("boom");
+  });
+
+  it("skill command → no dispatch, sendUserMessage called once, no command_feedback", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/skill:foo", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+
+    expect(feedbackEvents(sink, "/skill:foo")).toEqual([]);
+  });
+
+  it("prompt template → no dispatch, sendUserMessage called once, no command_feedback", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/review", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(feedbackEvents(sink, "/review")).toEqual([]);
+  });
+
+  it("passthrough text → no dispatch, sendUserMessage called once, no command_feedback", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("hello world", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it("unrecognized slash → no dispatch, sendUserMessage called once, no command_feedback", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/totally-unknown-command", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(feedbackEvents(sink, "/totally-unknown-command")).toEqual([]);
+  });
+
+  it("bridge-native /__dashboard_reload → no dispatch, no error feedback, sendUserMessage fallback", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/__dashboard_reload", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    // It IS in the command list with source: extension, but DASHBOARD_NATIVE_COMMANDS
+    // / __-prefix exclusion suppresses it. The slash branch falls through to sendUserMessage.
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(feedbackEvents(sink, "/__dashboard_reload")).toEqual([]);
+  });
+
+  it("getCommands throws → no crash, no command_feedback, sendUserMessage fallback fires", async () => {
+    const stub = makeStubPi({ withDispatch: true, getCommandsThrows: true });
+    const sink = await drive("/ctx-stats", stub);
+
+    expect(stub.dispatchCommand).not.toHaveBeenCalled();
+    // helper returns false on throw → caller falls through to sendUserMessage path
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(feedbackEvents(sink, "/ctx-stats")).toEqual([]);
+  });
+
+  it("never duplicates command_feedback on dispatch path (success)", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/ctx-stats", stub);
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.filter((e) => e.status === "started")).toHaveLength(1);
+    expect(evs.filter((e) => e.status === "completed" || e.status === "error")).toHaveLength(1);
+  });
+
+  it("never duplicates command_feedback on stopgap path", async () => {
+    const stub = makeStubPi({ withDispatch: false });
+    const sink = await drive("/ctx-stats", stub);
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.filter((e) => e.status === "started")).toHaveLength(1);
+    expect(evs.filter((e) => e.status === "completed" || e.status === "error")).toHaveLength(1);
+  });
+
+  it("anti-regression: /ctx-stats NEVER reaches sendUserMessage", async () => {
+    // regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+    for (const withDispatch of [true, false]) {
+      const stub = makeStubPi({ withDispatch });
+      await drive("/ctx-stats", stub);
+      expect(stub.sendUserMessage, `withDispatch=${withDispatch}`).not.toHaveBeenCalled();
+    }
+  });
+});
+
+// See change: add-rpc-stdin-dispatch-with-keeper-sidecar (task 7.7 + 9.1).
+// Direct-driver tests for tryDispatchExtensionCommand covering the
+// three-way decision (Paths B / C / D) and asserting mutual exclusion:
+// for any single dispatch, EXACTLY ONE of (pi.dispatchCommand call,
+// connection.send dispatch_extension_command, sink error feedback) fires.
+describe("tryDispatchExtensionCommand: Path B/C/D mutual exclusion", () => {
+  const ORIGINAL_ENV_FLAG = process.env.PI_DASHBOARD_SPAWNED;
+  const ORIGINAL_ARGV = process.argv;
+
+  function setHeadless(headless: boolean) {
+    if (headless) {
+      process.env.PI_DASHBOARD_SPAWNED = "1";
+      process.argv = ["node", "pi", "--mode", "rpc"];
+    } else {
+      delete process.env.PI_DASHBOARD_SPAWNED;
+      process.argv = ["node", "pi"];
+    }
+  }
+
+  beforeEach(() => { setHeadless(false); });
+  afterEach(() => {
+    if (ORIGINAL_ENV_FLAG === undefined) delete process.env.PI_DASHBOARD_SPAWNED;
+    else process.env.PI_DASHBOARD_SPAWNED = ORIGINAL_ENV_FLAG;
+    process.argv = ORIGINAL_ARGV;
+  });
+
+  function makePi(opts: { withDispatch?: boolean } = {}) {
+    const dispatchCommand = opts.withDispatch ? vi.fn(async () => undefined) : undefined;
+    const getCommands = vi.fn(() => [{ name: "ctx-stats", source: "extension" }]);
+    const pi: any = { getCommands };
+    if (dispatchCommand) pi.dispatchCommand = dispatchCommand;
+    return { pi, dispatchCommand };
+  }
+
+  function makeConn(): { conn: DispatchConnection; sent: ExtensionToServerMessage[] } {
+    const sent: ExtensionToServerMessage[] = [];
+    return { conn: { send: (m) => sent.push(m) }, sent };
+  }
+
+  it("Path B: pi.dispatchCommand present → dispatch called; no connection.send; sink gets started+completed", async () => {
+    const { pi, dispatchCommand } = makePi({ withDispatch: true });
+    const sink = vi.fn();
+    const { conn, sent } = makeConn();
+    setHeadless(true); // headless detection irrelevant when dispatchCommand exists
+
+    const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
+    expect(handled).toBe(true);
+    expect(dispatchCommand).toHaveBeenCalledTimes(1);
+    expect(sent.filter((m) => m.type === "dispatch_extension_command")).toEqual([]);
+    const evs = sink.mock.calls
+      .map((c: any[]) => c[0])
+      .filter((m: any) => m?.event?.eventType === "command_feedback")
+      .map((m: any) => m.event.data.status);
+    expect(evs).toEqual(["started", "completed"]);
+  });
+
+  it("Path C: no dispatchCommand + headless + connection → dispatch_extension_command emitted; no terminal feedback from bridge", async () => {
+    const { pi, dispatchCommand } = makePi({ withDispatch: false });
+    expect(dispatchCommand).toBeUndefined();
+    const sink = vi.fn();
+    const { conn, sent } = makeConn();
+    setHeadless(true);
+
+    const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid-abc", sink, conn);
+    expect(handled).toBe(true);
+
+    // Exactly one dispatch_extension_command emission with the right shape.
+    const dispatches = sent.filter((m): m is Extract<ExtensionToServerMessage, { type: "dispatch_extension_command" }> =>
+      m.type === "dispatch_extension_command");
+    expect(dispatches).toHaveLength(1);
+    expect(dispatches[0].sessionId).toBe("sid-abc");
+    expect(dispatches[0].command).toBe("/ctx-stats");
+    expect(typeof dispatches[0].requestId).toBe("string");
+    expect(dispatches[0].requestId.length).toBeGreaterThan(0);
+
+    // Bridge emitted started ONLY — server is responsible for the terminal event.
+    const evs = sink.mock.calls
+      .map((c: any[]) => c[0])
+      .filter((m: any) => m?.event?.eventType === "command_feedback")
+      .map((m: any) => m.event.data.status);
+    expect(evs).toEqual(["started"]);
+  });
+
+  it("Path D: no dispatchCommand + non-headless + connection → stopgap error; no connection.send", async () => {
+    const { pi } = makePi({ withDispatch: false });
+    const sink = vi.fn();
+    const { conn, sent } = makeConn();
+    setHeadless(false);
+
+    const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
+    expect(handled).toBe(true);
+    expect(sent.filter((m) => m.type === "dispatch_extension_command")).toEqual([]);
+    const evs = sink.mock.calls
+      .map((c: any[]) => c[0])
+      .filter((m: any) => m?.event?.eventType === "command_feedback");
+    expect(evs).toHaveLength(2);
+    expect(evs[0].event.data.status).toBe("started");
+    expect(evs[1].event.data.status).toBe("error");
+    expect(evs[1].event.data.message).toMatch(/pi 0\.71\+/);
+  });
+
+  it("Path C degrades to Path D when connection arg is undefined", async () => {
+    const { pi } = makePi({ withDispatch: false });
+    const sink = vi.fn();
+    setHeadless(true);
+
+    const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, undefined);
+    expect(handled).toBe(true);
+    const evs = sink.mock.calls
+      .map((c: any[]) => c[0])
+      .filter((m: any) => m?.event?.eventType === "command_feedback");
+    // started + error (Path D fallback) — NOT just started.
+    expect(evs.map((e: any) => e.event.data.status)).toEqual(["started", "error"]);
+  });
+
+  it("non-extension /skill:foo → returns false; no path fires; no events", async () => {
+    const pi: any = {
+      getCommands: () => [{ name: "skill:foo", source: "skill" }],
+      dispatchCommand: vi.fn(),
+    };
+    const sink = vi.fn();
+    const { conn, sent } = makeConn();
+    setHeadless(true);
+
+    const handled = await tryDispatchExtensionCommand(pi, "/skill:foo", "sid", sink, conn);
+    expect(handled).toBe(false);
+    expect(pi.dispatchCommand).not.toHaveBeenCalled();
+    expect(sent).toEqual([]);
+    expect(sink).not.toHaveBeenCalled();
+  });
+
+  it("mutual exclusion: across all single-dispatch invocations, exactly one of (B, C, D) fires", async () => {
+    type Scenario = { withDispatch: boolean; headless: boolean; expect: "B" | "C" | "D" };
+    const scenarios: Scenario[] = [
+      { withDispatch: true,  headless: true,  expect: "B" },
+      { withDispatch: true,  headless: false, expect: "B" },
+      { withDispatch: false, headless: true,  expect: "C" },
+      { withDispatch: false, headless: false, expect: "D" },
+    ];
+    for (const s of scenarios) {
+      const { pi, dispatchCommand } = makePi({ withDispatch: s.withDispatch });
+      const sink = vi.fn();
+      const { conn, sent } = makeConn();
+      setHeadless(s.headless);
+
+      await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
+
+      const dispatchedB = !!dispatchCommand && dispatchCommand.mock.calls.length > 0;
+      const dispatchedC = sent.some((m) => m.type === "dispatch_extension_command");
+      const errorD = sink.mock.calls.some((c: any[]) =>
+        (c[0] as any)?.event?.data?.status === "error");
+
+      const fired = [dispatchedB && "B", dispatchedC && "C", errorD && "D"].filter(Boolean);
+      expect(fired, JSON.stringify(s)).toEqual([s.expect]);
+    }
+  });
+});
+
+describe("hasDispatchCommand", () => {
+  it("returns true when field is a function", () => {
+    expect(hasDispatchCommand({ dispatchCommand: () => {} })).toBe(true);
+  });
+  it("returns false when field is absent", () => {
+    expect(hasDispatchCommand({})).toBe(false);
+  });
+  it("returns false when field is not a function", () => {
+    expect(hasDispatchCommand({ dispatchCommand: "yes" })).toBe(false);
+  });
+  it("returns false on null/undefined", () => {
+    expect(hasDispatchCommand(null)).toBe(false);
+    expect(hasDispatchCommand(undefined)).toBe(false);
+  });
+});

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

@@ -502,20 +502,22 @@ describe("CommandHandler", () => {
       }));
     });
 
-    it("should emit command_feedback for slash commands even without sessionPrompt", async () => {
+    it("should NOT emit command_feedback for unrecognized slash commands (no sessionPrompt)", async () => {
+      // Per fix-extension-slash-commands-in-dashboard, unrecognized slashes
+      // (not extension commands, not bridge-handled) fall through to
+      // sendUserMessage with NO command_feedback events. Only registered
+      // extension commands emit started/{completed,error}.
       const pi = createMockPi();
       const eventSink = vi.fn();
       const handler = createCommandHandler(pi as any, "s1", { eventSink });
 
       await handler.handle({ type: "send_prompt", sessionId: "s1", text: "/some-command" });
 
-      expect(eventSink).toHaveBeenCalledWith(expect.objectContaining({
-        type: "event_forward",
-        event: expect.objectContaining({
-          eventType: "command_feedback",
-          data: expect.objectContaining({ command: "/some-command", status: "completed" }),
-        }),
-      }));
+      expect(pi.sendUserMessage).toHaveBeenCalledWith("/some-command");
+      const feedbackCalls = eventSink.mock.calls.filter(
+        (c) => (c[0] as any)?.event?.eventType === "command_feedback",
+      );
+      expect(feedbackCalls).toHaveLength(0);
     });
 
     it("should fallback to sendUserMessage when sessionPrompt is not available for slash commands", async () => {

package/packages/extension/src/__tests__/extension-slash-command-detection.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure-predicate tests for `isExtensionSlashCommand`.
+ * One scenario per ADDED Requirement in
+ * openspec/changes/fix-extension-slash-commands-in-dashboard/specs/command-routing/spec.md.
+ *
+ * regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+ */
+import { describe, it, expect } from "vitest";
+import { isExtensionSlashCommand, isHeadlessRpcSession } from "../bridge-context.js";
+
+describe("isExtensionSlashCommand", () => {
+  it("detects a bare extension command", () => {
+    expect(
+      isExtensionSlashCommand("/ctx-stats", [{ name: "ctx-stats", source: "extension" }]),
+    ).toBe(true);
+  });
+
+  it("detects an extension command with arguments", () => {
+    expect(
+      isExtensionSlashCommand("/ctx-stats verbose=1", [
+        { name: "ctx-stats", source: "extension" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("rejects a skill command (source: skill)", () => {
+    expect(
+      isExtensionSlashCommand("/skill:foo", [{ name: "skill:foo", source: "skill" }]),
+    ).toBe(false);
+  });
+
+  it("rejects a prompt template (source: prompt)", () => {
+    expect(
+      isExtensionSlashCommand("/review", [{ name: "review", source: "prompt" }]),
+    ).toBe(false);
+  });
+
+  it("rejects bridge-native dashboard command (DASHBOARD_NATIVE_COMMANDS)", () => {
+    // `roles` is in DASHBOARD_NATIVE_COMMANDS even though pi-flows registers it
+    // with source: extension.
+    expect(
+      isExtensionSlashCommand("/roles", [{ name: "roles", source: "extension" }]),
+    ).toBe(false);
+  });
+
+  it("rejects __-prefixed bridge-native command", () => {
+    expect(
+      isExtensionSlashCommand("/__dashboard_reload", [
+        { name: "__dashboard_reload", source: "extension" },
+      ]),
+    ).toBe(false);
+  });
+
+  it("rejects an unknown slash", () => {
+    expect(isExtensionSlashCommand("/totally-unknown", [])).toBe(false);
+  });
+
+  it("rejects multi-line input", () => {
+    expect(
+      isExtensionSlashCommand("/ctx-stats\nuser context", [
+        { name: "ctx-stats", source: "extension" },
+      ]),
+    ).toBe(false);
+  });
+
+  it("rejects non-slash input", () => {
+    expect(
+      isExtensionSlashCommand("hello world", [{ name: "ctx-stats", source: "extension" }]),
+    ).toBe(false);
+  });
+
+  it("rejects empty slash `/`", () => {
+    expect(
+      isExtensionSlashCommand("/", [{ name: "ctx-stats", source: "extension" }]),
+    ).toBe(false);
+  });
+});
+
+// See change: add-rpc-stdin-dispatch-with-keeper-sidecar (task 7.2).
+describe("isHeadlessRpcSession", () => {
+  it("returns true when env=1 AND argv contains --mode rpc", () => {
+    expect(
+      isHeadlessRpcSession(
+        { PI_DASHBOARD_SPAWNED: "1" },
+        ["node", "pi", "--mode", "rpc"],
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when env unset (non-dashboard RPC)", () => {
+    expect(isHeadlessRpcSession({}, ["node", "pi", "--mode", "rpc"])).toBe(false);
+  });
+
+  it("returns false when argv has no --mode rpc (dashboard tmux)", () => {
+    expect(isHeadlessRpcSession({ PI_DASHBOARD_SPAWNED: "1" }, ["node", "pi"])).toBe(false);
+  });
+
+  it("returns false when neither env nor argv match", () => {
+    expect(isHeadlessRpcSession({}, ["node", "pi"])).toBe(false);
+  });
+
+  it("returns false when --mode is followed by non-rpc value", () => {
+    expect(
+      isHeadlessRpcSession({ PI_DASHBOARD_SPAWNED: "1" }, ["node", "pi", "--mode", "interactive"]),
+    ).toBe(false);
+  });
+});

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { expandPromptTemplateFromDisk } from "../prompt-expander.js";
 import { parseSkillBlock } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
@@ -96,4 +96,113 @@ describe("expandPromptTemplateFromDisk", () => {
     const result = expandPromptTemplateFromDisk("/opsx:continue x", tmpDir);
     expect(result).not.toContain("<skill name=");
   });
+
+  // Change: unify-opsx-colon-hyphen-aliases — symmetric : ↔ - resolution.
+
+  function makeSkillFile(relPath: string, body = "skill body"): string {
+    const abs = join(tmpDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, `---\nname: ignored\n---\n${body}`);
+    return abs;
+  }
+
+  it("expands hyphen-typed slash command resolving a colon-registered pi.getCommands skill", () => {
+    const skillPath = makeSkillFile("registry/colon/SKILL.md");
+    const pi = {
+      getCommands: () => [{ name: "opsx:archive", source: "skill", path: skillPath }],
+    };
+    const result = expandPromptTemplateFromDisk("/opsx-archive my-change", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx:archive" location="')).toBe(true);
+    expect(result.endsWith("\n\nmy-change")).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx:archive");
+    expect(parsed!.args).toBe("my-change");
+  });
+
+  it("expands colon-typed slash command resolving a hyphen-registered pi.getCommands skill", () => {
+    const skillPath = makeSkillFile("registry/hyphen/SKILL.md");
+    const pi = {
+      getCommands: () => [{ name: "opsx-archive", source: "skill", path: skillPath }],
+    };
+    const result = expandPromptTemplateFromDisk("/opsx:archive my-change", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx-archive" location="')).toBe(true);
+    expect(result.endsWith("\n\nmy-change")).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx-archive");
+  });
+
+  it("expands colon-typed slash command resolving a hyphen-named local SKILL.md directory", () => {
+    mkdirSync(join(skillsDir, "opsx-archive"), { recursive: true });
+    writeFileSync(join(skillsDir, "opsx-archive", "SKILL.md"), "---\nname: x\n---\nbody");
+    const result = expandPromptTemplateFromDisk("/opsx:archive arg", tmpDir);
+    expect(result.startsWith('<skill name="opsx-archive" location="')).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx-archive");
+    expect(parsed!.args).toBe("arg");
+  });
+
+  it("expands hyphen-typed slash command resolving a colon-named local SKILL.md directory", () => {
+    mkdirSync(join(skillsDir, "opsx:archive"), { recursive: true });
+    writeFileSync(join(skillsDir, "opsx:archive", "SKILL.md"), "---\nname: x\n---\nbody");
+    const result = expandPromptTemplateFromDisk("/opsx-archive arg", tmpDir);
+    expect(result.startsWith('<skill name="opsx:archive" location="')).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx:archive");
+  });
+
+  it("original-form precedence: colon-typed prefers colon-registered skill over hyphen-form prompt template", () => {
+    // Local prompt opsx-foo.md exists; registry has skill opsx:foo.
+    writeFileSync(join(promptsDir, "opsx-foo.md"), "prompt body");
+    const skillPath = makeSkillFile("registry/precedence/SKILL.md", "skill body");
+    const pi = {
+      getCommands: () => [{ name: "opsx:foo", source: "skill", path: skillPath }],
+    };
+    // /opsx:foo → must wrap as skill (registry hit on original form).
+    const colon = expandPromptTemplateFromDisk("/opsx:foo", tmpDir, pi);
+    expect(colon.startsWith('<skill name="opsx:foo" location="')).toBe(true);
+    // /opsx-foo → must NOT wrap (local prompt hit on original form).
+    const hyphen = expandPromptTemplateFromDisk("/opsx-foo", tmpDir, pi);
+    expect(hyphen).not.toContain("<skill name=");
+    expect(hyphen).toContain("prompt body");
+  });
+
+  it("original-form-first across distinct pi.getCommands entries", () => {
+    const aPath = makeSkillFile("registry/A/SKILL.md", "A body");
+    const bPath = makeSkillFile("registry/B/SKILL.md", "B body");
+    const pi = {
+      getCommands: () => [
+        { name: "opsx:foo", source: "skill", path: aPath },
+        { name: "opsx-foo", source: "skill", path: bPath },
+      ],
+    };
+    const colon = expandPromptTemplateFromDisk("/opsx:foo arg", tmpDir, pi);
+    expect(colon).toContain(`location="${aPath}"`);
+    expect(colon).toContain('name="opsx:foo"');
+    expect(colon).not.toContain(`location="${bPath}"`);
+    const hyphen = expandPromptTemplateFromDisk("/opsx-foo arg", tmpDir, pi);
+    expect(hyphen).toContain(`location="${bPath}"`);
+    expect(hyphen).toContain('name="opsx-foo"');
+    expect(hyphen).not.toContain(`location="${aPath}"`);
+  });
+
+  it("original form in pi-registry beats remapped form in local-scan", () => {
+    // Local prompt opsx-foo.md exists; registry has skill opsx:foo.
+    writeFileSync(join(promptsDir, "opsx-foo.md"), "prompt body");
+    const skillPath = makeSkillFile("registry/outer/SKILL.md", "skill body");
+    const pi = {
+      getCommands: () => [{ name: "opsx:foo", source: "skill", path: skillPath }],
+    };
+    // /opsx:foo: outer-loop probes original form across ALL stores first.
+    // Step 3 hit on registry — must NOT fall through to remapped opsx-foo local prompt.
+    const result = expandPromptTemplateFromDisk("/opsx:foo", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx:foo" location="')).toBe(true);
+    expect(result).not.toContain("prompt body");
+  });
+
+  it("misspelled name with wrong separator returns input unchanged", () => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    mkdirSync(tmpDir, { recursive: true });
+    const result = expandPromptTemplateFromDisk("/opsx:nonexistent foo", tmpDir);
+    expect(result).toBe("/opsx:nonexistent foo");
+  });
 });