@fiale-plus/pi-rogue-bundle 0.1.9 → 0.1.10

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/advisor-checkins.test.ts

@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it } from "vitest";
+import { resetAdvisorSessionContext, setAdvisorCheckinsEnabled } from "./advisor-checkins.js";
+
+const dirs: string[] = [];
+
+function tempConfig() {
+  const dir = mkdtempSync(join(tmpdir(), "pi-rogue-advisor-checkins-"));
+  dirs.push(dir);
+  const file = join(dir, "advisor", "config.json");
+  mkdirSync(join(dir, "advisor"), { recursive: true });
+  return file;
+}
+
+function tempState() {
+  const dir = mkdtempSync(join(tmpdir(), "pi-rogue-advisor-state-"));
+  dirs.push(dir);
+  const base = join(dir, "advisor");
+  mkdirSync(base, { recursive: true });
+  return {
+    config: join(base, "config.json"),
+    state: join(base, "state.json"),
+  };
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("advisor check-in lifecycle bridge", () => {
+  it("turns advisor check-ins on while preserving existing config and captures start time", () => {
+    const file = tempConfig();
+    writeFileSync(file, JSON.stringify({
+      mode: "auto",
+      review: "light",
+      model: "openai-codex/gpt-5.5",
+      checkinIntervalTurns: 3,
+    }), "utf8");
+    const startedAt = Date.now();
+
+    const next = setAdvisorCheckinsEnabled(true, file);
+
+    expect(next).toMatchObject({ mode: "auto", review: "light", model: "openai-codex/gpt-5.5", checkins: "mid-hour" });
+    expect(next.checkinIntervalTurns).toBeUndefined();
+    expect(next.checkinStartedAt).toBeTypeOf("number");
+    expect(next.checkinStartedAt).toBeGreaterThanOrEqual(startedAt);
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    expect(parsed.checkins).toBe("mid-hour");
+    expect(parsed.checkinIntervalTurns).toBeUndefined();
+    expect(parsed.checkinStartedAt).toBeGreaterThanOrEqual(startedAt);
+  });
+
+  it("turns advisor check-ins off", () => {
+    const file = tempConfig();
+    writeFileSync(file, JSON.stringify({ checkins: "mid-hour", checkinIntervalMinutes: 30 }), "utf8");
+
+    const next = setAdvisorCheckinsEnabled(false, file);
+
+    expect(next).toMatchObject({ checkins: "off", checkinIntervalMinutes: 30 });
+    expect(JSON.parse(readFileSync(file, "utf8")).checkins).toBe("off");
+  });
+
+  it("resets advisor brief context and check-in timing for a new goal", () => {
+    const { config, state } = tempState();
+    const startedAt = Date.now();
+    writeFileSync(config, JSON.stringify({
+      mode: "auto",
+      review: "light",
+      checkins: "mid-hour",
+      checkinIntervalMinutes: 30,
+      checkinIntervalTurns: 3,
+      checkinStartedAt: 1,
+    }), "utf8");
+    writeFileSync(state, JSON.stringify({
+      turns: 9,
+      lastTask: "old task",
+      notes: ["old note"],
+      files: ["old.ts"],
+      errors: ["old error"],
+      advisorCalls: 3,
+      cacheHits: 7,
+      followUp: "old follow-up",
+      reviewControl: {
+        status: "running",
+        pending: true,
+        consumed: false,
+        running: true,
+        lastDecision: "review",
+        lastReason: "manual checkpoint",
+      },
+      router: { preflight: { label: "continue" } },
+      checkin: {
+        lastAt: "2026-05-29T00:00:00.000Z",
+        lastTurn: 8,
+        lastReason: "mid-hour check-in after 1 new turn(s)",
+        queued: true,
+        queuedReason: "queued mid-session check-in",
+      },
+    }), "utf8");
+
+    const next = resetAdvisorSessionContext(config, state);
+
+    expect(next.state).toMatchObject({
+      turns: 0,
+      lastTask: "",
+      notes: [],
+      files: [],
+      errors: [],
+      advisorCalls: 3,
+      cacheHits: 7,
+      followUp: "",
+      router: {},
+      checkin: { queued: false },
+      reviewControl: {
+        status: "idle",
+        pending: false,
+        consumed: true,
+        running: false,
+      },
+    });
+    expect(next.config.checkinStartedAt).toBeTypeOf("number");
+    expect(next.config.checkinStartedAt).toBeGreaterThanOrEqual(startedAt);
+
+    const parsedState = JSON.parse(readFileSync(state, "utf8"));
+    expect(parsedState.lastTask).toBe("");
+    expect(parsedState.notes).toEqual([]);
+    expect(parsedState.checkin).toEqual({ queued: false });
+    expect(parsedState.reviewControl).toEqual({
+      status: "idle",
+      pending: false,
+      consumed: true,
+      running: false,
+    });
+
+    const parsedConfig = JSON.parse(readFileSync(config, "utf8"));
+    expect(parsedConfig.checkins).toBe("mid-hour");
+    expect(parsedConfig.checkinIntervalTurns).toBeUndefined();
+    expect(parsedConfig.checkinStartedAt).toBeGreaterThanOrEqual(startedAt);
+  });
+});

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

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+type AdvisorConfig = Record<string, unknown> & { checkins?: "mid-hour" | "off"; checkinStartedAt?: number };
+type AdvisorState = Record<string, unknown> & {
+  turns?: number;
+  lastTask?: string;
+  notes?: unknown[];
+  files?: unknown[];
+  errors?: unknown[];
+  advisorCalls?: number;
+  cacheHits?: number;
+  followUp?: string;
+  router?: Record<string, unknown>;
+  checkin?: Record<string, unknown>;
+  reviewControl?: {
+    status?: "idle" | "needed" | "running" | "consumed";
+    pending?: boolean;
+    consumed?: boolean;
+    running?: boolean;
+    lastDecision?: string;
+    lastMaterialSignature?: string;
+    lastReason?: string;
+    lastTrigger?: string;
+    lastAppliedAt?: string;
+  };
+};
+
+const ADVISOR_DIR = join(homedir(), ".pi", "agent", "pi-rogue", "advisor");
+const ADVISOR_CONFIG_PATH = join(homedir(), ".pi", "agent", "pi-rogue", "advisor", "config.json");
+const ADVISOR_STATE_PATH = join(ADVISOR_DIR, "state.json");
+
+function readJson<T>(file: string): T {
+  if (!existsSync(file)) return {} as T;
+  try {
+    return JSON.parse(readFileSync(file, "utf8") || "{}") as T;
+  } catch {
+    return {} as T;
+  }
+}
+
+function cleanAdvisorConfig(config: AdvisorConfig): AdvisorConfig {
+  const cleaned = { ...config };
+  delete cleaned.checkinIntervalTurns;
+  delete cleaned.advisorAutoRunCooldownUntilTurn;
+  return cleaned;
+}
+
+export function setAdvisorCheckinsEnabled(enabled: boolean, configPath = ADVISOR_CONFIG_PATH): AdvisorConfig {
+  const current = cleanAdvisorConfig(readJson<AdvisorConfig>(configPath));
+  const next: AdvisorConfig = {
+    ...current,
+    checkins: enabled ? "mid-hour" : "off",
+    checkinStartedAt: enabled ? Date.now() : undefined,
+  };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return next;
+}
+
+export function resetAdvisorSessionContext(
+  configPath = ADVISOR_CONFIG_PATH,
+  statePath = ADVISOR_STATE_PATH,
+): { config: AdvisorConfig; state: AdvisorState } {
+  const currentConfig = cleanAdvisorConfig(readJson<AdvisorConfig>(configPath));
+  const nextConfig: AdvisorConfig = {
+    ...currentConfig,
+    checkinStartedAt: currentConfig.checkins === "mid-hour" ? Date.now() : undefined,
+  };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+
+  const currentState = readJson<AdvisorState>(statePath);
+  const nextState: AdvisorState = {
+    ...currentState,
+    turns: 0,
+    lastTask: "",
+    notes: [],
+    files: [],
+    errors: [],
+    followUp: "",
+    reviewControl: {
+      status: "idle",
+      pending: false,
+      consumed: true,
+      running: false,
+    },
+    router: {},
+    checkin: { queued: false },
+  };
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, `${JSON.stringify(nextState, null, 2)}\n`, "utf8");
+
+  return { config: nextConfig, state: nextState };
+}

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/autoresearch-state.ts

@@ -0,0 +1,70 @@
+import { truncate } from "./internal.js";
+import { readSessionJson, writeSessionJson } from "./state.js";
+
+export const FEATURE = "orchestration";
+export const RESEARCH_FILE = "autoresearch.json";
+export const DEFAULT_RESEARCH_INTERVAL = "5m";
+
+export type ResearchKind = "autoresearch" | "autoresearch-lab";
+
+export type ResearchState = {
+  kind: ResearchKind;
+  instruction: string;
+  goal?: string;
+  loopInstruction?: string;
+  interval?: string;
+  cycles?: number;
+  lastResult?: "done" | "continue" | "unknown";
+  updatedAt: string;
+};
+
+export function defaultResearchState(kind: ResearchKind = "autoresearch"): ResearchState {
+  return {
+    kind,
+    instruction: "",
+    goal: "",
+    loopInstruction: "",
+    interval: DEFAULT_RESEARCH_INTERVAL,
+    cycles: 0,
+    updatedAt: "",
+  };
+}
+
+export function readResearchState(ctx: any): ResearchState {
+  return readSessionJson(FEATURE, ctx, RESEARCH_FILE, defaultResearchState("autoresearch"));
+}
+
+export function writeResearchState(ctx: any, state: ResearchState): ResearchState {
+  const next: ResearchState = { ...state, updatedAt: new Date().toISOString() };
+  writeSessionJson(FEATURE, ctx, RESEARCH_FILE, next);
+  return next;
+}
+
+export function clearResearchState(ctx: any): ResearchState {
+  return writeResearchState(ctx, defaultResearchState("autoresearch"));
+}
+
+export function clearResearchStateForGoal(ctx: any, goal: string): boolean {
+  const state = readResearchState(ctx);
+  if (!state.instruction || !state.goal || state.goal !== goal) return false;
+  clearResearchState(ctx);
+  return true;
+}
+
+export function hasActiveResearch(ctx: any): boolean {
+  return Boolean(readResearchState(ctx).instruction);
+}
+
+export function label(kind: ResearchKind): string {
+  return kind === "autoresearch-lab" ? "🧪 Autoresearch lab" : "🔎 Autoresearch";
+}
+
+export function formatResearchState(state: ResearchState): string {
+  if (!state.instruction) {
+    return `${label(state.kind)} is off.`;
+  }
+
+  const cycles = state.cycles ?? 0;
+  const last = state.lastResult ? `, last=${state.lastResult}` : "";
+  return `${label(state.kind)} active: ${truncate(state.instruction, 160)} — /loop ${state.interval || DEFAULT_RESEARCH_INTERVAL}; cycles=${cycles}${last}`;
+}

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/autoresearch.test.ts

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { setAdvisorCheckinsEnabled } from "./advisor-checkins.js";
+import { buildResearchGoal, buildResearchLoopInstruction, registerAutoresearch } from "./autoresearch.js";
+import { formatResearchState, type ResearchState } from "./autoresearch-state.js";
+import { clearLoop } from "./loop.js";
+
+vi.mock("./advisor-checkins.js", () => ({
+  resetAdvisorSessionContext: vi.fn(),
+  setAdvisorCheckinsEnabled: vi.fn(),
+}));
+
+const setAdvisorCheckinsEnabledMock = vi.mocked(setAdvisorCheckinsEnabled);
+
+function fakeCtx(id = randomUUID()) {
+  const notifications: string[] = [];
+  return {
+    notifications,
+    isIdle: () => true,
+    sessionManager: {
+      getSessionFile: () => `/tmp/pi-rogue-autoresearch-test-${id}.jsonl`,
+    },
+    ui: {
+      setStatus: () => undefined,
+      notify: (message: string) => notifications.push(message),
+    },
+  };
+}
+
+describe("autoresearch status", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("surfaces backing loop and cycle count", () => {
+    const state: ResearchState = {
+      kind: "autoresearch",
+      instruction: "possible improvements for pi-rogue-orchestration",
+      goal: "Autoresearch: possible improvements for pi-rogue-orchestration",
+      loopInstruction: "Run one autoresearch cycle",
+      interval: "5m",
+      cycles: 1,
+      lastResult: "done",
+      updatedAt: "2026-05-26T00:00:00.000Z",
+    };
+
+    const text = formatResearchState(state);
+
+    expect(text).toContain("/loop 5m");
+    expect(text).toContain("cycles=1");
+    expect(text).toContain("last=done");
+  });
+
+  it("keeps empty state concise", () => {
+    expect(formatResearchState({ kind: "autoresearch", instruction: "", updatedAt: "" })).toBe("🔎 Autoresearch is off.");
+  });
+
+  it("keeps autoresearch prompts direct", () => {
+    const goal = buildResearchGoal("autoresearch", "improve advisor escalation");
+    const loop = buildResearchLoopInstruction("autoresearch", "improve advisor escalation");
+
+    expect(goal).toContain("measurable target");
+    expect(goal).toContain("eval/check command");
+    expect(goal).toContain("durable artifact/log");
+    expect(goal).toContain("Preserve the user objective");
+    expect(goal).toContain("summarized with evidence");
+    expect(loop).toContain("Confirm/update hypothesis");
+    expect(loop).toContain("take one concrete high-leverage step");
+    expect(loop).toContain("record result");
+    expect(loop).toContain("Do not simplify or re-aim");
+  });
+
+  it("keeps autoresearch-lab prompts direct", () => {
+    const goal = buildResearchGoal("autoresearch-lab", "compare advisor lanes");
+    const loop = buildResearchLoopInstruction("autoresearch-lab", "compare advisor lanes");
+
+    expect(goal).toContain("source objective");
+    expect(goal).toContain("lane split");
+    expect(goal).toContain("evaluate evidence before integration");
+    expect(goal).toContain("convergent findings");
+    expect(loop).toContain("Advance the most useful lane comparison");
+    expect(loop).toContain("integrate only safe improvements");
+    expect(loop).toContain("Do not simplify or re-aim");
+  });
+
+  it("does not queue a duplicate cycle for the same active autoresearch instruction", async () => {
+    let handler: ((args: string, ctx: any) => Promise<void>) | undefined;
+    const sent: string[] = [];
+    const pi = {
+      registerCommand: (name: string, command: { handler: (args: string, ctx: any) => Promise<void> }) => {
+        if (name === "autoresearch") handler = command.handler;
+      },
+      sendUserMessage: (text: string) => sent.push(text),
+    } as any;
+    const ctx = fakeCtx();
+
+    registerAutoresearch(pi);
+    expect(handler).toBeTypeOf("function");
+    await handler?.("improve repetition handling", ctx);
+    await handler?.("improve repetition handling", ctx);
+
+    expect(sent).toHaveLength(1);
+    expect(ctx.notifications.at(-1)).toContain("already active");
+  });
+
+  it("requeues the same autoresearch instruction when the backing loop is stale", async () => {
+    let handler: ((args: string, ctx: any) => Promise<void>) | undefined;
+    const sent: string[] = [];
+    const pi = {
+      registerCommand: (name: string, command: { handler: (args: string, ctx: any) => Promise<void> }) => {
+        if (name === "autoresearch") handler = command.handler;
+      },
+      sendUserMessage: (text: string) => sent.push(text),
+    } as any;
+    const ctx = fakeCtx();
+
+    registerAutoresearch(pi);
+    await handler?.("improve stale loop recovery", ctx);
+    clearLoop(ctx, { preserveCheckins: true });
+    await handler?.("improve stale loop recovery", ctx);
+
+    expect(sent).toHaveLength(2);
+    expect(sent[1]).toContain("improve stale loop recovery");
+  });
+
+  it("disables advisor check-ins when /autoresearch clear stops the loop", async () => {
+    let handler: ((args: string, ctx: any) => Promise<void>) | undefined;
+    const pi = {
+      registerCommand: (name: string, command: { handler: (args: string, ctx: any) => Promise<void> }) => {
+        if (name === "autoresearch") handler = command.handler;
+      },
+      sendUserMessage: () => undefined,
+    } as any;
+    const ctx = fakeCtx();
+
+    registerAutoresearch(pi);
+    await handler?.("improve lifecycle cleanup", ctx);
+    setAdvisorCheckinsEnabledMock.mockClear();
+    await handler?.("clear", ctx);
+
+    expect(setAdvisorCheckinsEnabledMock).toHaveBeenCalledWith(false);
+  });
+});

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/autoresearch.ts

@@ -0,0 +1,139 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { activeGoal, clearGoal, setGoal, setGoalStatus } from "./goal.js";
+import { clearLoop, readLoopState, startLoop } from "./loop.js";
+import {
+  DEFAULT_RESEARCH_INTERVAL,
+  formatResearchState,
+  label,
+  readResearchState,
+  writeResearchState,
+  type ResearchKind,
+} from "./autoresearch-state.js";
+import { autoresearchArgumentCompletions } from "./completions.js";
+
+export function buildResearchGoal(kind: ResearchKind, instruction: string): string {
+  if (kind === "autoresearch-lab") {
+    return [
+      `Autoresearch lab: ${instruction}`,
+      "Define source objective, hypotheses, lane split, measurement method, baseline, artifacts, and stop condition.",
+      "Run independent lanes where useful; evaluate evidence before integration; preserve the user objective unless explicitly changed.",
+      "Finish with convergent findings, rejected hypotheses, limitations, checks, and follow-up seeds.",
+    ].join("\n");
+  }
+
+  return [
+    `Autoresearch: ${instruction}`,
+    "Define hypothesis/objective, measurable target, baseline, eval/check command, durable artifact/log, and stop condition.",
+    "Iterate: inspect evidence, make one high-leverage change, run the relevant check/eval, record result, choose next hypothesis.",
+    "Preserve the user objective unless explicitly changed; stop only when materially improved and summarized with evidence.",
+  ].join("\n");
+}
+
+export function buildResearchLoopInstruction(kind: ResearchKind, instruction: string): string {
+  if (kind === "autoresearch-lab") {
+    return [
+      "Run one autoresearch-lab cycle toward the active goal.",
+      `User instruction: ${instruction}`,
+      "Confirm/update source objective, hypotheses, lane split, measurement method, baseline, artifacts, and stop condition.",
+      "Advance the most useful lane comparison, evaluate evidence, integrate only safe improvements, run checks, and record the next hypothesis.",
+      "Do not simplify or re-aim the objective unless the user explicitly asks.",
+    ].join("\n");
+  }
+
+  return [
+    "Run one autoresearch cycle toward the active goal.",
+    `User instruction: ${instruction}`,
+    "Confirm/update hypothesis, measurable target, baseline, eval/check command, artifact/log, and stop condition.",
+    "Inspect evidence, take one concrete high-leverage step, run the relevant check/eval when possible, record result, and choose the next hypothesis.",
+    "Do not simplify or re-aim the objective unless the user explicitly asks.",
+  ].join("\n");
+}
+
+function registerResearchCommand(pi: ExtensionAPI, commandName: ResearchKind): void {
+  const prefix = label(commandName);
+
+  pi.registerCommand(commandName, {
+    description: commandName === "autoresearch-lab"
+      ? "Parallel multi-agent research mode backed by goal + loop"
+      : "Iterative optimization/research mode backed by goal + loop",
+    getArgumentCompletions: (prefix: string) => autoresearchArgumentCompletions(prefix),
+    handler: async (args, ctx) => {
+      const input = String(args ?? "").trim();
+      const [cmd] = input.split(/\s+/);
+      const resolved = !input ? "status" : ["status", "show"].includes(cmd) ? cmd : ["off", "clear", "stop"].includes(cmd) ? "clear" : "set";
+
+      if (resolved === "status" || resolved === "show") {
+        ctx.ui.notify(formatResearchState(readResearchState(ctx)), "info");
+        return;
+      }
+
+      if (resolved === "clear") {
+        const previous = readResearchState(ctx);
+        clearLoop(ctx, { clearResearch: true });
+        const clearedGoal = Boolean(previous.goal && activeGoal(ctx) === previous.goal);
+        if (clearedGoal) {
+          clearGoal(ctx);
+          setGoalStatus(ctx, null);
+        }
+        ctx.ui.notify(`${prefix} cleared; underlying loop stopped${clearedGoal ? " and matching goal cleared" : ""}.`, "info");
+        return;
+      }
+
+      const instruction = input;
+      if (!instruction) {
+        ctx.ui.notify(`Usage: /${commandName} <instruction>`, "error");
+        return;
+      }
+
+      const goal = buildResearchGoal(commandName, instruction);
+      const loopInstruction = buildResearchLoopInstruction(commandName, instruction);
+      const previous = readResearchState(ctx);
+      const currentLoop = readLoopState(ctx);
+      if (
+        previous.kind === commandName
+        && previous.instruction === instruction
+        && previous.goal === goal
+        && activeGoal(ctx) === goal
+        && currentLoop.enabled
+        && currentLoop.instruction === loopInstruction
+      ) {
+        ctx.ui.notify(`${prefix} already active for this instruction. No duplicate cycle queued.`, "info");
+        return;
+      }
+
+      const restartSameGoal = activeGoal(ctx) === goal;
+      setGoal(ctx, goal, { restartDuplicate: restartSameGoal });
+
+      setGoalStatus(ctx, goal);
+      const next = writeResearchState(ctx, {
+        kind: commandName,
+        instruction,
+        goal,
+        loopInstruction,
+        interval: DEFAULT_RESEARCH_INTERVAL,
+        cycles: 0,
+        updatedAt: "",
+      });
+      const loop = startLoop(pi, ctx, DEFAULT_RESEARCH_INTERVAL, loopInstruction, { triggerNow: true });
+      if (!loop) {
+        ctx.ui.notify(`${prefix} could not start: invalid loop interval.`, "error");
+        return;
+      }
+      ctx.ui.notify(`${formatResearchState(next)}. First cycle queued now.`, "info");
+    },
+  });
+}
+
+export function registerAutoresearch(pi: ExtensionAPI): void {
+  const p = pi as any;
+  if (p.__piRogueAutoresearchRegistered) return;
+  p.__piRogueAutoresearchRegistered = true;
+  registerResearchCommand(pi, "autoresearch");
+}
+
+export function registerAutoresearchLab(pi: ExtensionAPI): void {
+  const p = pi as any;
+  if (p.__piRogueAutoresearchLabRegistered) return;
+  p.__piRogueAutoresearchLabRegistered = true;
+  registerResearchCommand(pi, "autoresearch-lab");
+}

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/completions.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { autoresearchArgumentCompletions, goalArgumentCompletions, loopArgumentCompletions } from "./completions.js";
+
+describe("goal completions", () => {
+  it("offers goal management choices", () => {
+    const values = goalArgumentCompletions("")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["show", "clear", "list", "set"]));
+  });
+});
+
+describe("loop completions", () => {
+  it("offers loop management and cadence choices", () => {
+    const values = loopArgumentCompletions("")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["status", "off", "1m", "5m", "1h"]));
+  });
+});
+
+describe("autoresearch completions", () => {
+  it("offers research management choices", () => {
+    const values = autoresearchArgumentCompletions("")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["status", "clear"]));
+  });
+});

package/node_modules/@fiale-plus/pi-rogue-orchestration/src/completions.ts

@@ -0,0 +1,53 @@
+type CompletionItem = { value: string; label: string; description?: string };
+
+function item(value: string, description?: string): CompletionItem {
+  return { value, label: value, ...(description ? { description } : {}) };
+}
+
+function complete(values: Array<[string, string?]>, prefix: string): CompletionItem[] | null {
+  const q = prefix.trimStart().toLowerCase();
+  const items = values.map(([value, description]) => item(value, description));
+  const filtered = q ? items.filter((i) => i.value.startsWith(q)) : items;
+  return filtered.length > 0 ? filtered : null;
+}
+
+export function goalArgumentCompletions(prefix: string): CompletionItem[] | null {
+  return complete(
+    [
+      ["show", "show current goal"],
+      ["status", "show current goal"],
+      ["clear", "clear current goal"],
+      ["list", "list recent goals"],
+      ["set", "set a goal"],
+    ],
+    prefix,
+  );
+}
+
+export function loopArgumentCompletions(prefix: string): CompletionItem[] | null {
+  return complete(
+    [
+      ["status", "show current loop"],
+      ["show", "show current loop"],
+      ["off", "clear current loop"],
+      ["clear", "clear current loop"],
+      ["stop", "clear current loop"],
+      ["1m", "minimum cadence"],
+      ["5m", "default cadence"],
+      ["1h", "slower cadence"],
+    ],
+    prefix,
+  );
+}
+
+export function autoresearchArgumentCompletions(prefix: string): CompletionItem[] | null {
+  return complete(
+    [
+      ["status", "show research status"],
+      ["show", "show research status"],
+      ["clear", "clear research state"],
+      ["stop", "clear research state"],
+    ],
+    prefix,
+  );
+}