@fiale-plus/pi-rogue 0.2.0

package/node_modules/@fiale-plus/pi-rogue-advisor/src/index.ts

@@ -0,0 +1,3 @@
+export { default, registerAdvisor } from "./extension.js";
+export { requestAdvisorLoopCheckin } from "./extension.js";
+export * from "./router.js";

package/node_modules/@fiale-plus/pi-rogue-advisor/src/internal.ts

@@ -0,0 +1,63 @@
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+const ROOT_DIR = join(homedir(), ".pi", "agent", "pi-rogue");
+
+export function appDir(): string {
+  mkdirSync(ROOT_DIR, { recursive: true });
+  return ROOT_DIR;
+}
+
+export function featureDir(feature: string): string {
+  const dir = join(appDir(), feature);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function featureFile(feature: string, filename: string): string {
+  return join(featureDir(feature), filename);
+}
+
+export function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+
+export function readText(filePath: string, fallback = ""): string {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+function ensureParent(filePath: string): string {
+  mkdirSync(dirname(filePath), { recursive: true });
+  return filePath;
+}
+
+export function writeText(filePath: string, text: string): void {
+  ensureParent(filePath);
+  writeFileSync(filePath, text, "utf8");
+}
+
+export function appendText(filePath: string, text: string): void {
+  ensureParent(filePath);
+  appendFileSync(filePath, text, "utf8");
+}
+
+/** Write text atomically: write to temp file, then rename. Falls back to direct write on failure. */
+export function atomicWriteText(filePath: string, text: string): void {
+  const tempPath = filePath + ".tmp";
+  try {
+    writeText(tempPath, text);
+    try { renameSync(tempPath, filePath); } catch {
+      // If rename fails (e.g., cross-device), fall back to overwrite
+      writeText(filePath, text);
+    }
+  } catch {
+    // If temp write fails, try direct write
+    writeText(filePath, text);
+  }
+}

package/node_modules/@fiale-plus/pi-rogue-advisor/src/loop-convergence.test.ts

@@ -0,0 +1,512 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { completeSimple } from "@earendil-works/pi-ai";
+import { registerAdvisor } from "./extension.js";
+
+const testHome = vi.hoisted(() => `/tmp/pi-rogue-advisor-loop-convergence-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+vi.mock("node:os", async () => {
+  const actual = await vi.importActual<typeof import("node:os")>("node:os");
+  return { ...actual, homedir: () => testHome };
+});
+
+vi.mock("@earendil-works/pi-ai", async () => {
+  const actual = await vi.importActual<typeof import("@earendil-works/pi-ai")>("@earendil-works/pi-ai");
+  return {
+    ...actual,
+    completeSimple: vi.fn(),
+  };
+});
+
+type Handler = (event: any, ctx: any) => any;
+
+type HandlerMap = Record<string, Handler[]>;
+type CommandMap = Record<string, { handler: (args: string, ctx: any) => any }>;
+type MessageRendererMap = Record<string, (message: any, options: { expanded?: boolean }, theme: any) => any>;
+
+function makeHandlers() {
+  const handlers: HandlerMap = {};
+  const commands: CommandMap = {};
+  const messageRenderers: MessageRendererMap = {};
+  const sendMessage = vi.fn();
+
+  const pi = {
+    on: (event: string, handler: Handler) => {
+      handlers[event] ??= [];
+      handlers[event].push(handler);
+    },
+    registerMessageRenderer: (customType: string, renderer: MessageRendererMap[string]) => {
+      messageRenderers[customType] = renderer;
+    },
+    registerCommand: (name: string, command: { handler: (args: string, ctx: any) => any }) => {
+      commands[name] = command;
+    },
+    registerTool: vi.fn(),
+    sendMessage,
+    sendUserMessage: () => undefined,
+    ui: {
+      setStatus: () => undefined,
+      notify: () => undefined,
+    },
+  };
+
+  return { handlers, commands, messageRenderers, pi: pi as any, sendMessage };
+}
+
+const ADVISOR_STATE_DIR = join(homedir(), ".pi", "agent", "pi-rogue", "advisor");
+const ADVISOR_STATE_PATH = join(ADVISOR_STATE_DIR, "state.json");
+const ADVISOR_CONFIG_PATH = join(ADVISOR_STATE_DIR, "config.json");
+const ADVISOR_CACHE_PATH = join(ADVISOR_STATE_DIR, "cache.json");
+
+function readAdvisorState(): any {
+  return JSON.parse(readFileSync(ADVISOR_STATE_PATH, "utf8"));
+}
+
+function mkCtx() {
+  return {
+    sessionManager: {
+      getSessionFile: () => join(homedir(), ".pi", "agent", "pi-rogue", "advisor", "session.jsonl"),
+    },
+    isIdle: () => true,
+    modelRegistry: {
+      find: (provider: string, model: string) => {
+        if (provider === "openai-codex") return { id: `${provider}/${model}`, provider, input: ["text"] };
+        return null;
+      },
+      getAvailable: () => [{ id: "provider/text-light", provider: "provider", input: ["text"] }],
+      getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "k", headers: {} }),
+    },
+    ui: {
+      setStatus: () => undefined,
+      notify: () => undefined,
+    },
+  } as any;
+}
+
+describe("advisor two-agent convergence", () => {
+  let ctx: any;
+  let handlers: HandlerMap;
+  let commands: CommandMap;
+  let messageRenderers: MessageRendererMap;
+  let sendMessageMock: ReturnType<typeof vi.fn>;
+  let completeSimpleMock: ReturnType<typeof vi.fn>;
+  let piMock: any;
+  let priorState: string | null = null;
+  let priorConfig: string | null = null;
+  let priorCache: string | null = null;
+
+  beforeEach(() => {
+    priorState = existsSync(ADVISOR_STATE_PATH) ? readFileSync(ADVISOR_STATE_PATH, "utf8") : null;
+    priorConfig = existsSync(ADVISOR_CONFIG_PATH) ? readFileSync(ADVISOR_CONFIG_PATH, "utf8") : null;
+    priorCache = existsSync(ADVISOR_CACHE_PATH) ? readFileSync(ADVISOR_CACHE_PATH, "utf8") : null;
+
+    const setup = makeHandlers();
+    handlers = setup.handlers;
+    commands = setup.commands;
+    messageRenderers = setup.messageRenderers;
+    sendMessageMock = setup.sendMessage;
+    piMock = setup.pi;
+
+    mkdirSync(dirname(ADVISOR_STATE_PATH), { recursive: true });
+    writeFileSync(ADVISOR_CONFIG_PATH, JSON.stringify({ mode: "auto", review: "light", checkins: "off", checkinIntervalMinutes: 30 }, null, 2), "utf8");
+    writeFileSync(ADVISOR_CACHE_PATH, "{}", "utf8");
+    writeFileSync(ADVISOR_STATE_PATH, JSON.stringify({
+      turns: 0,
+      lastTask: "",
+      notes: [],
+      files: [],
+      errors: [],
+      advisorCalls: 0,
+      cacheHits: 0,
+      followUp: "",
+      router: {},
+      checkin: { queued: false },
+      reviewControl: {
+        status: "idle",
+        pending: false,
+        consumed: true,
+        running: false,
+      },
+    }, null, 2), "utf8");
+
+    registerAdvisor(setup.pi);
+
+    ctx = mkCtx();
+    completeSimpleMock = vi.mocked(completeSimple as any);
+    completeSimpleMock.mockReset();
+
+    const verdict = {
+      verdict: "not_done",
+      summary: "Closeout is incomplete",
+      reason: "Please run one concrete check and report the result",
+      actions: ["run focused check"],
+      checklist: [],
+      notify: true,
+    };
+    completeSimpleMock.mockResolvedValue({ content: [{ type: "text", text: JSON.stringify(verdict) }] });
+  });
+
+  afterEach(() => {
+    if (priorState === null) {
+      writeFileSync(ADVISOR_STATE_PATH, "{}", "utf8");
+    } else {
+      writeFileSync(ADVISOR_STATE_PATH, priorState, "utf8");
+    }
+
+    if (priorConfig === null) {
+      writeFileSync(ADVISOR_CONFIG_PATH, "{}", "utf8");
+    } else {
+      writeFileSync(ADVISOR_CONFIG_PATH, priorConfig, "utf8");
+    }
+
+    if (priorCache === null) {
+      writeFileSync(ADVISOR_CACHE_PATH, "{}", "utf8");
+    } else {
+      writeFileSync(ADVISOR_CACHE_PATH, priorCache, "utf8");
+    }
+  });
+
+  it("does not re-run advisory review on repeated material snapshots", async () => {
+    const preflight = handlers.before_agent_start;
+    const turnEnd = handlers.turn_end;
+    expect(preflight?.length).toBe(1);
+    expect(turnEnd?.length).toBe(1);
+
+    await handlers.session_start?.[0]?.({}, ctx);
+
+    const basePrompt = "Continue the current goal";
+    const statusText = "Repo-side autoresearch is verified closed. Only optional external rollout/CI smoke remains.";
+
+    const firstPrompt = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    expect(typeof firstPrompt).toBe("object");
+
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: statusText },
+    }, ctx);
+
+    const firstState = readAdvisorState();
+    expect(firstState.reviewControl.lastDecision).toBe("review");
+    expect(firstState.followUp).toContain("Closeout is incomplete");
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customType: "advisor:llm",
+        content: expect.stringContaining("Summary: Closeout is incomplete"),
+      }),
+      expect.anything(),
+    );
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({ content: expect.stringContaining("Actions: run focused check") }),
+      expect.anything(),
+    );
+    expect(completeSimpleMock).toHaveBeenCalledTimes(1);
+
+    const consumedPrompt = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    expect(String(consumedPrompt?.systemPrompt)).toContain("Advisor follow-up");
+
+    const consumedState = readAdvisorState();
+    expect(consumedState.reviewControl.status).toBe("consumed");
+    expect(consumedState.followUp).toBe("");
+
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: statusText },
+    }, ctx);
+
+    const secondState = readAdvisorState();
+    expect(completeSimpleMock).toHaveBeenCalledTimes(1);
+    expect(secondState.reviewControl.status).toBe("consumed");
+    expect(["repeated material snapshot", firstState.reviewControl.lastReason]).toContain(secondState.reviewControl.lastReason);
+
+    const withoutFollowUp = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    expect(String(withoutFollowUp?.systemPrompt)).not.toContain("Advisor follow-up");
+  });
+
+  it("normalizes string actions in advisor handoffs", async () => {
+    const preflight = handlers.before_agent_start;
+    const turnEnd = handlers.turn_end;
+    expect(preflight?.length).toBe(1);
+    expect(turnEnd?.length).toBe(1);
+
+    completeSimpleMock.mockResolvedValue({
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          verdict: "not_done",
+          summary: "Closeout is incomplete",
+          reason: "Verification is missing",
+          actions: "run focused check",
+          checklist: [],
+          notify: true,
+        }),
+      }],
+    });
+
+    await handlers.session_start?.[0]?.({}, ctx);
+    await preflight![0]({ systemPrompt: "SYS", prompt: "Continue the current goal" }, ctx);
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: "Repo-side autoresearch is verified closed. Only optional external rollout/CI smoke remains." },
+    }, ctx);
+
+    const state = readAdvisorState();
+    expect(completeSimpleMock).toHaveBeenCalledTimes(1);
+    expect(state.followUp).toBe("Closeout is incomplete — run focused check");
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customType: "advisor:llm",
+        content: expect.stringContaining("Actions: run focused check"),
+        details: expect.objectContaining({ actions: ["run focused check"] }),
+      }),
+      expect.anything(),
+    );
+  });
+
+  it("redacts transient clipboard image paths from emitted advisor handoffs", async () => {
+    const preflight = handlers.before_agent_start;
+    const turnEnd = handlers.turn_end;
+    const clipboardPath = "/var/folders/fm/rwczdnws5j58x7kbyn3vcx_h0000gn/T/clipboard-2026-06-04-012248-DEE3A154.png";
+
+    completeSimpleMock.mockResolvedValue({
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          verdict: "not_done",
+          summary: `The visible handoff should not include ${clipboardPath}`,
+          reason: `Expanded Ctrl+O output leaks ${clipboardPath}`,
+          actions: [`redact ${clipboardPath}`],
+          checklist: [],
+          notify: true,
+        }),
+      }],
+    });
+
+    await handlers.session_start?.[0]?.({}, ctx);
+    await preflight![0]({ systemPrompt: "SYS", prompt: `Continue the current goal ${clipboardPath}` }, ctx);
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: "Repo-side autoresearch is verified closed. Only optional external rollout/CI smoke remains." },
+    }, ctx);
+
+    expect(sendMessageMock).toHaveBeenCalled();
+    const sent = sendMessageMock.mock.calls[0]?.[0];
+    expect(JSON.stringify(sent)).not.toContain(clipboardPath);
+    expect(sent.content).toContain("[clipboard image]");
+    expect(readAdvisorState().followUp).toContain("[clipboard image]");
+
+    const theme = {
+      fg: (_name: string, text: string) => text,
+      bg: (_name: string, text: string) => text,
+      bold: (text: string) => text,
+    };
+    const expanded = messageRenderers["advisor:llm"](sent, { expanded: true }, theme).render(120).join("\n");
+    expect(expanded).toContain("full handoff:");
+    expect(expanded).toContain("Advisor verdict: review.");
+    expect(expanded).toContain("[clipboard image]");
+    expect(expanded).not.toContain(clipboardPath);
+  });
+
+  it("suppresses duplicate reason and summary in advisor handoffs", async () => {
+    const preflight = handlers.before_agent_start;
+    const turnEnd = handlers.turn_end;
+    const duplicate = "The agent made a safe attempt, but it did not demonstrate that the advisor post-turn review was induced.";
+
+    completeSimpleMock.mockResolvedValue({
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          verdict: "not_done",
+          reason: duplicate,
+          summary: duplicate,
+          actions: ["Invoke the real review hook if available."],
+          checklist: [],
+          notify: true,
+        }),
+      }],
+    });
+
+    await handlers.session_start?.[0]?.({}, ctx);
+    await preflight![0]({ systemPrompt: "SYS", prompt: "Continue the current goal" }, ctx);
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: "Repo-side autoresearch is verified closed. Only optional external rollout/CI smoke remains." },
+    }, ctx);
+
+    const sent = sendMessageMock.mock.calls[0]?.[0];
+    expect(sent.content).toContain(`Reason: ${duplicate}`);
+    expect(sent.content).not.toContain("Summary:");
+    expect(sent.details.summary).toBe("");
+
+    const theme = {
+      fg: (_name: string, text: string) => text,
+      bg: (_name: string, text: string) => text,
+      bold: (text: string) => text,
+    };
+    const collapsed = messageRenderers["advisor:llm"](sent, { expanded: false }, theme).render(120).join("\n");
+    const expanded = messageRenderers["advisor:llm"](sent, { expanded: true }, theme).render(120).join("\n");
+    expect(collapsed).toContain("reason:");
+    expect(collapsed).not.toContain("summary:");
+    expect(expanded).toContain("Reason:");
+    expect(expanded).not.toContain("reason:");
+    expect(expanded).not.toContain("Summary:");
+  });
+
+  it("renders manual advisor answers as advisor custom messages", async () => {
+    expect(commands.advisor).toBeTruthy();
+
+    completeSimpleMock.mockResolvedValue({
+      content: [{
+        type: "text",
+        text: "Post-turn review: no merge blockers identified from the session brief.",
+      }],
+    });
+
+    await commands.advisor.handler("should we merge this pr?", ctx);
+
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customType: "advisor:llm",
+        content: "Post-turn review: no merge blockers identified from the session brief.",
+        display: true,
+        details: expect.objectContaining({
+          kind: "answer",
+          summary: "Post-turn review: no merge blockers identified from the session brief.",
+        }),
+      }),
+    );
+  });
+
+  it("includes broker briefs in manual advisor context when available", async () => {
+    expect(commands.advisor).toBeTruthy();
+    piMock.__piRogueContextBroker = {
+      renderBrief: () => "## Context Broker\nHot:\n- ctx://session/s/tool_output/abc/ctx-1 summary=\"npm test passed\"",
+    };
+    completeSimpleMock.mockResolvedValue({ content: [{ type: "text", text: "Use the broker handle as evidence." }] });
+
+    await commands.advisor.handler("should we use broker context", ctx);
+
+    const messages = completeSimpleMock.mock.calls.at(-1)?.[1]?.messages;
+    const promptText = JSON.stringify(messages ?? completeSimpleMock.mock.calls.at(-1));
+    expect(promptText).toContain("Context broker brief");
+    expect(promptText).toContain("ctx://session/s/tool_output/abc/ctx-1");
+  });
+
+  it("does not re-run advisory review on repeated agent-end material snapshots", async () => {
+    const preflight = handlers.before_agent_start;
+    const agentEnd = handlers.agent_end;
+    expect(preflight?.length).toBe(1);
+    expect(agentEnd?.length).toBe(1);
+
+    await handlers.session_start?.[0]?.({}, ctx);
+
+    const basePrompt = "Continue the current goal";
+    const statusText = "Repo-side autoresearch is verified closed. Only optional external rollout/CI smoke remains.";
+
+    const firstPrompt = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    expect(typeof firstPrompt).toBe("object");
+
+    await agentEnd![0]({
+      messages: [
+        { role: "assistant", content: statusText },
+        { role: "toolResult", content: "edit tool changed file" },
+      ],
+    }, ctx);
+
+    const firstState = readAdvisorState();
+    expect(firstState.reviewControl).toBeTruthy();
+    const callsBeforeSecond = completeSimpleMock.mock.calls.length;
+
+    const consumedPrompt = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    if (firstState.followUp) {
+      expect(String(consumedPrompt?.systemPrompt)).toContain("Advisor follow-up");
+    } else {
+      expect(String(consumedPrompt?.systemPrompt)).not.toContain("Advisor follow-up");
+    }
+
+    const consumedState = readAdvisorState();
+    expect(consumedState.reviewControl.status).toBe("consumed");
+    expect(consumedState.followUp).toBe("");
+
+    await agentEnd![0]({
+      messages: [
+        { role: "assistant", content: statusText },
+        { role: "toolResult", content: "edit tool changed file" },
+      ],
+    }, ctx);
+
+    const secondState = readAdvisorState();
+    expect(completeSimpleMock).toHaveBeenCalledTimes(callsBeforeSecond);
+    expect(secondState.reviewControl.status).toBe("consumed");
+    expect(secondState.reviewControl.lastReason).toBe("repeated material snapshot");
+
+    const withoutFollowUp = await preflight![0]({ systemPrompt: "SYS", prompt: basePrompt }, ctx);
+    expect(String(withoutFollowUp?.systemPrompt)).not.toContain("Advisor follow-up");
+  });
+
+  it("records on-track reviews silently instead of emitting repetitive continue hints", async () => {
+    const preflight = handlers.before_agent_start;
+    const turnEnd = handlers.turn_end;
+    expect(preflight?.length).toBe(1);
+    expect(turnEnd?.length).toBe(1);
+
+    completeSimpleMock.mockResolvedValue({
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          verdict: "on_track",
+          summary: "Implementation aligns with the requested advisor check-in behavior",
+          actions: [],
+          checklist: [],
+          notify: true,
+        }),
+      }],
+    });
+
+    await handlers.session_start?.[0]?.({}, ctx);
+    await preflight![0]({ systemPrompt: "SYS", prompt: "Continue the current goal" }, ctx);
+    await turnEnd![0]({
+      toolResults: [{ toolName: "edit" }],
+      message: { role: "assistant", content: "Secret token handling was reviewed and the safety fix is complete." },
+    }, ctx);
+
+    const state = readAdvisorState();
+    expect(completeSimpleMock).toHaveBeenCalledTimes(1);
+    expect(state.reviewControl.lastDecision).toBe("continue");
+    expect(sendMessageMock).not.toHaveBeenCalledWith(
+      expect.objectContaining({ customType: "advisor:llm" }),
+      expect.anything(),
+    );
+  });
+
+  it("recovers running review control state on session start", async () => {
+    const preflight = handlers.before_agent_start;
+    const sessionStart = handlers.session_start;
+    expect(sessionStart?.length).toBe(1);
+    expect(preflight?.length).toBe(1);
+
+    const state = readAdvisorState();
+    state.reviewControl = {
+      status: "running",
+      pending: true,
+      consumed: false,
+      running: true,
+      lastMaterialSignature: "stale",
+      lastTrigger: "turn-1",
+    };
+    writeFileSync(ADVISOR_STATE_PATH, JSON.stringify(state, null, 2), "utf8");
+
+    await sessionStart![0]({}, ctx);
+
+    const recovered = readAdvisorState();
+    expect(recovered.reviewControl.running).toBe(false);
+    expect(recovered.reviewControl.status).toBe("needed");
+    expect(recovered.reviewControl.pending).toBe(true);
+    expect(recovered.reviewControl.consumed).toBe(false);
+
+    const status = await preflight![0]({ systemPrompt: "SYS", prompt: "Continue the current goal" }, ctx);
+    expect(status?.systemPrompt).toContain("Review-control: needed");
+  });
+});

package/node_modules/@fiale-plus/pi-rogue-advisor/src/preflight-signals.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { classifyIntent, classifyMode } from "./preflight-signals.js";
+
+describe("preflight signal classifiers", () => {
+  it("classifies planning prompts", () => {
+    expect(classifyIntent("what should we do next, design the architecture")).toBe("plan");
+  });
+
+  it("classifies implementation prompts", () => {
+    expect(classifyIntent("implement the auth flow and add tests")).toBe("implement");
+  });
+
+  it("classifies review prompts", () => {
+    expect(classifyIntent("please review this PR and check the diff")).toBe("review");
+  });
+
+  it("classifies questions vs commands", () => {
+    expect(classifyMode("what should we do next?")).toBe("question");
+    expect(classifyMode("run the tests and fix the bug")).toBe("command");
+    expect(classifyMode("hello there")).toBe("neutral");
+  });
+});

package/node_modules/@fiale-plus/pi-rogue-advisor/src/preflight-signals.ts

@@ -0,0 +1,21 @@
+/** Lightweight intent classifier for preflight signal enrichment */
+export function classifyIntent(text: string): string {
+  const t = ` ${String(text ?? "").toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ")} `;
+  if (/\b(plan|design|architecture|scope|next step|strategy|proposal|should we|what should|tradeoff|decision|path forward|how to approach)\b/.test(t)) return "plan";
+  if (/\b(debug|bug|error|fail|broken|crash|stack|traceback|investigate|why (is|was|does|did|are) )/.test(t)) return "debug";
+  if (/\b(review|check |verify|validate|look at|diff|pr |pull request|feedback)\b/i.test(t)) return "review";
+  if (/\b(research|compare|difference|which (one|model|lib|is better)|how does|documentation|read (about|the)|what is)\b/i.test(t)) return "research";
+  if (/\b(implement|build|write|create|add|make|refactor|rename|extract|migrate|fix|patch)\b/i.test(t)) return "implement";
+  if (/\b(install|config|setup|run|build|deploy|ssh|status|stats|logs?|theme|terminal|shell|brew|npm|git)\b/i.test(t)) return "ops";
+  if (/\b(continue|resume|compact|summarize|after compact|move on)\b/i.test(t)) return "handoff";
+  return "";
+}
+
+/** Classify prompt as question/command/neutral for signal enrichment */
+export function classifyMode(text: string): string {
+  const t = String(text ?? "").trim();
+  if (!t) return "";
+  if (/^(create|add|make|change|write|fix|update|remove|delete|run|install|set[\s-]?up|build|deploy|check|investigate|debug|review|test|refactor|merge|close|open|start|stop|restart|continue|show|list|compact|setup)\b/i.test(t)) return "command";
+  if (t.includes("?") || /^(what|why|how|when|where|who|which|is there|can we|should|does|did|are we|is it|do you|would you|could we)\b/i.test(t)) return "question";
+  return "neutral";
+}