@takara-ai/miru-code 1.9.0 → 1.10.1

package/src/installer/installer.ts

@@ -30,7 +30,7 @@ import {
   replaceOrAppendMarked,
   stripJsonComments,
 } from "./config.ts";
-import { mergeHooks, removeHooks } from "./hooks/install.ts";
+import { removeLegacySearchHooks } from "./legacy-hooks.ts";
 import { promptConfirm, promptMultiSelect, requireInteractiveTerminal } from "./prompt.ts";
 import { CURSOR_RULES_MDC } from "./search-policy.ts";
 import {
@@ -56,7 +56,7 @@ export type IntegrationId =
   | "mcp"
   | "instructions"
   | "subagent"
-  | "hooks"
+  | "legacy-hooks"
   | "rules"
   | "caveman"
   | "ste";
@@ -72,6 +72,21 @@ export interface ApplyCtx {
   isDetected?: (agent: AgentTarget) => Promise<boolean>;
 }
 
+type InstallerMultiSelect = <T>(
+  title: string,
+  items: Array<{ label: string; value: T; checked: boolean }>,
+) => Promise<T[] | null>;
+
+export interface RunInstallerDependencies {
+  requireInteractiveTerminal?: (command: string) => void;
+  ensureCredentials?: typeof ensureCredentials;
+  agents?: AgentTarget[];
+  isAgentDetected?: (agent: AgentTarget) => Promise<boolean>;
+  promptMultiSelect?: InstallerMultiSelect;
+  promptConfirm?: typeof promptConfirm;
+  removeUninstallLocalData?: typeof removeUninstallLocalData;
+}
+
 interface Integration {
   id: IntegrationId;
   label: string;
@@ -110,10 +125,12 @@ async function readExistingJsonMcpEntry(
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return null;
     }
-    const section = (parsed as Record<string, unknown>)[sectionKey];
-    if (!section || typeof section !== "object" || Array.isArray(section)) {
-      return null;
+    let section: unknown = parsed;
+    for (const key of sectionKey.split(".")) {
+      if (!section || typeof section !== "object" || Array.isArray(section)) return null;
+      section = (section as Record<string, unknown>)[key];
     }
+    if (!section || typeof section !== "object" || Array.isArray(section)) return null;
     const entry = (section as Record<string, unknown>)[memberKey];
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
       return null;
@@ -161,18 +178,13 @@ async function applyInstructions(
   return { path, action };
 }
 
-async function applyHooks(agent: AgentTarget, mode: InstallMode): Promise<WriteResult | null> {
-  const path = agent.hooksPath;
-  const format = agent.hooksFormat;
+async function removeLegacyHooks(agent: AgentTarget): Promise<WriteResult | null> {
+  const path = agent.legacyHooksPath;
+  const format = agent.legacyHooksFormat;
   if (!path || !format) {
     return null;
   }
-
-  const action =
-    mode === "install"
-      ? await mergeHooks(format, path, agent.id)
-      : await removeHooks(format, path, agent.id);
-
+  const action = await removeLegacySearchHooks(format, path, agent.id);
   return { path, action };
 }
 
@@ -311,9 +323,6 @@ async function applyCaveman(
 
 async function stePackMatches(skillDir: string): Promise<boolean> {
   const skillPath = join(skillDir, "SKILL.md");
-  if (!(await Bun.file(skillPath).exists())) {
-    return false;
-  }
   if ((await Bun.file(skillPath).text()) !== STE_SKILL_MD) {
     return false;
   }
@@ -449,13 +458,12 @@ const INTEGRATIONS: Integration[] = [
     apply: applyCursorRules,
   },
   {
-    id: "hooks",
-    label: "Search hooks",
-    description: "blocks built-in search; routes to Miru MCP",
-    experimental: true,
-    defaultChecked: false,
-    planPath: (agent) => agent.hooksPath,
-    apply: applyHooks,
+    id: "legacy-hooks",
+    label: "Remove old Miru hooks",
+    description: "clean up stale search hooks from older releases",
+    defaultChecked: true,
+    planPath: (agent) => agent.legacyHooksPath,
+    apply: removeLegacyHooks,
   },
   {
     id: "caveman",
@@ -593,12 +601,25 @@ export async function removeUninstallLocalData(): Promise<{
   };
 }
 
-export async function runInstaller(mode: InstallMode): Promise<void> {
+export async function runInstaller(
+  mode: InstallMode,
+  dependencies: RunInstallerDependencies = {},
+): Promise<void> {
+  const deps = {
+    requireInteractiveTerminal,
+    ensureCredentials,
+    agents: AGENT_TARGETS,
+    isAgentDetected,
+    promptMultiSelect,
+    promptConfirm,
+    removeUninstallLocalData,
+    ...dependencies,
+  };
   const install = mode === "install";
-  requireInteractiveTerminal(`miru ${mode}`);
+  deps.requireInteractiveTerminal(`miru ${mode}`);
 
   if (install) {
-    await ensureCredentials({ interactive: true });
+    await deps.ensureCredentials({ interactive: true });
   }
 
   writeStdout("");
@@ -607,9 +628,9 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
   hint("↑↓ move  space select  enter confirm");
 
   const detected = await Promise.all(
-    AGENT_TARGETS.map(async (agent) => ({
+    deps.agents.map(async (agent) => ({
       agent,
-      detected: await isAgentDetected(agent),
+      detected: await deps.isAgentDetected(agent),
     })),
   );
 
@@ -619,7 +640,7 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
     checked: isDetected && install,
   }));
 
-  const chosenAgents = await promptMultiSelect(
+  const chosenAgents = await deps.promptMultiSelect(
     `Agents to ${install ? "configure" : "clean up"}`,
     agentItems,
   );
@@ -641,7 +662,7 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
     checked: install ? (integration.defaultChecked ?? true) : true,
   }));
 
-  const chosenIntegrations = await promptMultiSelect(
+  const chosenIntegrations = await deps.promptMultiSelect(
     `Integrations to ${install ? "enable" : "remove"}`,
     integrationItems,
   );
@@ -653,7 +674,10 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
 
   await printPlan(mode, chosenAgents, chosenIntegrations);
 
-  const proceed = await promptConfirm(install ? "Proceed?" : "Remove miru configuration?", install);
+  const proceed = await deps.promptConfirm(
+    install ? "Proceed?" : "Remove miru configuration?",
+    install,
+  );
   if (!proceed) {
     hint("Cancelled.");
     return;
@@ -662,7 +686,7 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
   await apply(mode, chosenAgents, chosenIntegrations);
 
   if (!install) {
-    const local = await removeUninstallLocalData();
+    const local = await deps.removeUninstallLocalData();
     if (local.benchmarkHistoryCleared) {
       info(`Removed benchmark report ${local.benchmarkHistoryPath}`);
     }
@@ -674,7 +698,6 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
 
 export {
   applyCaveman,
-  applyHooks,
   applyInstructions,
   applyMcp,
   applySte,
@@ -684,3 +707,5 @@ export {
   mergeJsonMember as mergeMcpJson,
   removeJsonMember as removeMcpJson,
 };
+
+export const installerTestUtils = { applyCursorRules, printPlan };

package/src/installer/legacy-hooks.ts

@@ -0,0 +1,131 @@
+import { unlink } from "node:fs/promises";
+import type { InstallAction, LegacyHooksFormat } from "./agents.ts";
+import { stripJsonComments } from "./config.ts";
+import { isCopilotFamilyId } from "./copilot-family.ts";
+
+const LEGACY_MARKERS = ["hook-guard", "miru-search"];
+const VSCODE_OWNERS_KEY = "miruOwners";
+
+function isLegacyCommand(value: unknown): boolean {
+  return typeof value === "string" && LEGACY_MARKERS.some((marker) => value.includes(marker));
+}
+
+function parseObject(text: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = JSON.parse(stripJsonComments(text));
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function hasOnlyMiruConfig(data: Record<string, unknown>): boolean {
+  const keys = Object.keys(data);
+  if (keys.length === 0 || keys.every((key) => key === "version")) return true;
+  const hooks = object(data.hooks);
+  return (
+    !!hooks &&
+    Object.keys(data).every((key) => key === "version" || key === "hooks") &&
+    Object.keys(hooks).length === 0
+  );
+}
+
+async function writeResult(path: string, data: Record<string, unknown>): Promise<void> {
+  if (hasOnlyMiruConfig(data)) {
+    await unlink(path);
+  } else {
+    await Bun.write(path, `${JSON.stringify(data, null, 2)}\n`);
+  }
+}
+
+function isMiruEntry(format: LegacyHooksFormat, entry: Record<string, unknown>): boolean {
+  if (format === "claude") {
+    const nested = Array.isArray(entry.hooks) ? entry.hooks : [];
+    return nested.some((hook) => isLegacyCommand(object(hook)?.command));
+  }
+  return isLegacyCommand(entry.command);
+}
+
+/** Remove search hooks installed by older Miru releases; Miru no longer installs hooks. */
+export async function removeLegacySearchHooks(
+  format: LegacyHooksFormat,
+  path: string,
+  owner?: string,
+): Promise<InstallAction> {
+  if (!(await Bun.file(path).exists())) return "not-found";
+
+  if (format === "opencode") {
+    await unlink(path);
+    return "removed";
+  }
+
+  const text = await Bun.file(path).text();
+  const data = parseObject(text);
+  if (!data) return "error";
+
+  const hooks = object(data.hooks);
+
+  let ownerChanged = false;
+  if (format === "vscode") {
+    const owners = Array.isArray(data[VSCODE_OWNERS_KEY])
+      ? (data[VSCODE_OWNERS_KEY] as unknown[]).filter(
+          (value): value is string => typeof value === "string" && isCopilotFamilyId(value),
+        )
+      : null;
+    if (owners && owner) {
+      const remaining = owners.filter((value) => value !== owner);
+      if (remaining.length > 0) {
+        data[VSCODE_OWNERS_KEY] = remaining;
+        await Bun.write(path, `${JSON.stringify(data, null, 2)}\n`);
+        return "updated";
+      }
+      delete data[VSCODE_OWNERS_KEY];
+      ownerChanged = true;
+    }
+  }
+
+  if (!hooks) {
+    if (!ownerChanged) return "not-found";
+    await writeResult(path, data);
+    return "removed";
+  }
+
+  const eventKey = {
+    claude: "PreToolUse",
+    cursor: "preToolUse",
+    gemini: "BeforeTool",
+    vscode: "PreToolUse",
+    kiro: "preToolUse",
+    windsurf: "pre_run_command",
+    opencode: "",
+  }[format];
+  const entries = Array.isArray(hooks[eventKey]) ? (hooks[eventKey] as unknown[]) : null;
+  if (!entries) {
+    if (!ownerChanged) return "not-found";
+    await writeResult(path, data);
+    return "removed";
+  }
+
+  const retained = entries.filter((entry) => {
+    const record = object(entry);
+    return !record || !isMiruEntry(format, record);
+  });
+  if (retained.length === entries.length) {
+    if (!ownerChanged) return "not-found";
+    await writeResult(path, data);
+    return "removed";
+  }
+  if (retained.length === 0) delete hooks[eventKey];
+  else hooks[eventKey] = retained;
+  if (Object.keys(hooks).length === 0) delete data.hooks;
+  await writeResult(path, data);
+  return "removed";
+}

package/src/installer/prompt.ts

@@ -113,18 +113,9 @@ function parseArrowKey(chunk: Buffer, text: string): string | null {
     const introducer = text.charAt(1);
     if (introducer === "[" || introducer === "O") {
       const arrow = text.charAt(text.length - 1);
-      if (arrow === "A") {
-        return "up";
-      }
-      if (arrow === "B") {
-        return "down";
-      }
-      if (arrow === "C") {
-        return "right";
-      }
-      if (arrow === "D") {
-        return "left";
-      }
+      return (
+        ({ A: "up", B: "down", C: "right", D: "left" } as Record<string, string>)[arrow] ?? null
+      );
     }
   }
 
@@ -308,9 +299,13 @@ function updateConfirmPromptLine(question: string, yesSelected: boolean): void {
   );
 }
 
-export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
+export async function promptConfirm(
+  question: string,
+  defaultYes = true,
+  io: { input?: typeof input; output?: typeof output } = {},
+): Promise<boolean> {
   if (!input.isTTY) {
-    const rl = readline.createInterface({ input, output });
+    const rl = readline.createInterface({ input: io.input ?? input, output: io.output ?? output });
     try {
       const hintText = defaultYes ? dim("[Y/n]") : dim("[y/N]");
       const answer = (await rl.question(`${question} ${hintText} `)).trim().toLowerCase();
@@ -354,10 +349,13 @@ export async function promptConfirm(question: string, defaultYes = true): Promis
 export async function promptMultiSelectLegacy<T>(
   title: string,
   items: Array<{ label: string; value: T; checked: boolean }>,
+  io: { input?: typeof input; output?: typeof output } = {},
 ): Promise<T[] | null> {
-  output.write("\n");
-  output.write(`${bold(title)}\n`);
-  divider("─", 48, output);
+  const promptInput = io.input ?? input;
+  const promptOutput = io.output ?? output;
+  promptOutput.write("\n");
+  promptOutput.write(`${bold(title)}\n`);
+  divider("─", 48, promptOutput);
 
   for (let i = 0; i < items.length; i++) {
     const item = items[i];
@@ -365,13 +363,13 @@ export async function promptMultiSelectLegacy<T>(
       continue;
     }
     const mark = item.checked ? cyan("[x]") : dim("[ ]");
-    output.write(`  ${dim(String(i + 1).padStart(2))}. ${mark} ${item.label}\n`);
+    promptOutput.write(`  ${dim(String(i + 1).padStart(2))}. ${mark} ${item.label}\n`);
   }
 
-  output.write("\n");
-  hint("Enter numbers (1,3), 'all', or press Enter for defaults", output);
+  promptOutput.write("\n");
+  hint("Enter numbers (1,3), 'all', or press Enter for defaults", promptOutput);
 
-  const rl = readline.createInterface({ input, output });
+  const rl = readline.createInterface({ input: promptInput, output: promptOutput });
   try {
     const answer = (await rl.question(`${dim("> ")}`)).toLowerCase();
     if (!answer) {
@@ -390,7 +388,7 @@ export async function promptMultiSelectLegacy<T>(
     }
 
     if (indices.size === 0) {
-      warn("No valid selection.", output);
+      warn("No valid selection.", promptOutput);
       return null;
     }
 

package/src/installer/search-policy.ts

@@ -28,15 +28,17 @@ export function buildSearchPolicyBody(native: NativeToolNames): string {
 
 ${SNIPPET_GUIDANCE}
 
+\`repo\` is optional, set it for another repo.
+
 Use Miru MCP tools:
 - \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
-- \`search\` — one call per conceptual question; pass project root as \`repo\`; use \`include\` / \`exclude\` Gitignore-style globs to scope files (same syntax as \`locate\`)
+- \`search\` — one call per conceptual question; use \`include\` / \`exclude\` Gitignore-style globs to scope files (same syntax as \`locate\`)
 - \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
 - \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
 Call shapes:
-- \`locate(literal="<exact substring>", repo="<project root>")\` — prefer \`mode="locations"\`/\`"count"\`
-- \`search(query="<natural language>", repo="<project root>", include=["src/auth/**"])\` — use the same \`include\` / \`exclude\` globs on \`locate\` when scoping an exact-string search
+- \`locate(literal="<exact substring>")\` — prefer \`mode="locations"\`/\`"count"\`
+- \`search(query="<natural language>", include=["src/auth/**"])\` — use the same \`include\` / \`exclude\` globs on \`locate\` when scoping an exact-string search
 
 Stop rules:
 - Literal in the request → \`locate\`, not \`search\`
@@ -54,7 +56,7 @@ ${buildSearchPolicyTable(native)}`;
 export function buildMcpWorkflow(native: NativeToolNames): string {
   return `### MCP workflow
 
-1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
+1. Call \`search\`; add \`repo\` only for another repo.
 2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
 3. On \`truncated: true\`, call \`expand\` — only if the snippet doesn't already answer.
 4. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
@@ -71,7 +73,7 @@ miru find-related src/auth.ts 42 .
 \`\`\`
 
 After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code@latest\`.`;
 
 export function buildSubagentBody(native: NativeToolNames): string {
   return `When Miru MCP is available, use MCP \`search\`, \`locate\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
@@ -118,7 +120,7 @@ export const MCP_SERVER_INSTRUCTIONS =
   "Exact token (identifier, quoted string, env var, error code) → `locate`; everything else → `search` once, no paraphrase retries. " +
   `${SNIPPET_GUIDANCE} ` +
   "`find_related` traces similar code elsewhere, not more context in the same file. " +
-  "Always pass the project root as `repo`; local repos return `absolute_path` — use Read only to edit. " +
+  "`repo` is optional, good for multi repo workflows. " +
   "Native Grep/Glob only outside the indexed repo or for non-code tasks. " +
   "Default indexed scope is code, config, and docs; an empty result can mean out-of-scope, not nonexistent. " +
   "On credential errors, call this server's `auth` tool — not the host `mcp_auth` tool.";
@@ -161,5 +163,3 @@ export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
 export const MCP_READ_BENCHMARK_TOOL_DESCRIPTION =
   "Cumulative Miru vs Grep token savings from saved `search` and `locate` calls. Returns compact totals {n,saved,save_pct,miru,grep}. " +
   "Do not call unless the user asks about savings.";
-
-export const SEARCH_GUARD_EXPAND_HINT = SNIPPET_GUIDANCE;

package/src/mcp/auth-tool.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import {
   checkDeviceAuthorizationOnce,
   type DeviceAuthConfig,
+  type DeviceAuthorizationCheck,
   type DeviceAuthorizationStart,
   openBrowserForDeviceLogin,
   resolveDeviceAuthConfig,
@@ -15,24 +16,37 @@ import type { MiruMcpServer } from "./runtime.ts";
 type ToolResult = ReturnType<typeof toolText>;
 
 const CHECK_HINT =
-  'Once the user approves, call `auth` again with action "check" to finish signing in.';
+  "If the user has not approved yet, call `auth` again to keep waiting; it will not open a second tab.";
+
+/**
+ * How long one `auth` call waits for the user to approve in the browser. Kept well under
+ * typical MCP client tool timeouts; a slower login just takes another call.
+ */
+const DEFAULT_WAIT_MS = 45_000;
+const SLOW_DOWN_STEP_MS = 5_000;
+/** The server may advertise `interval: 0`; never poll the token endpoint faster than this. */
+const MIN_POLL_INTERVAL_MS = 1_000;
 
 /** Appended to credentials failures so an agent knows Miru's own recovery step. */
 const RECOVERY_HINT =
-  'Miru could not authorize its current credentials. Call the `auth` tool with action "start" ' +
-  'to open the Takara device-login page, then action "check" once the user approves. If access ' +
-  "is still denied after signing in, check the account token balance.";
+  "Miru could not authorize its current credentials. Call the `auth` tool to open the Takara " +
+  "device-login page; it waits for the user to approve. If access is still denied after " +
+  "signing in, check the account token balance.";
 
 const AUTH_TOOL_DESCRIPTION =
   "Sign in with Takara credentials via device-code login — no terminal required. " +
   "Only call this in direct response to a tool error mentioning missing, expired, rejected, or " +
   "invalid credentials — never speculatively, since it starts a real sign-in prompt for the " +
-  'user. Call with no arguments (or action "start") to begin: it opens the device-login ' +
-  `page in the user's browser and returns that URL plus a short code. ${CHECK_HINT}`;
+  "user. Call with no arguments: it opens the device-login page in the user's browser, then " +
+  "waits (up to about 45 seconds) for them to approve and returns once they have. If it " +
+  'returns "still waiting", tell the user the URL and code and call `auth` again.';
 
 /** Browser opener seam; the real one spawns a detached `open`/`xdg-open`/`start`. */
 export type BrowserOpener = (url: string) => boolean;
 
+/** Sleep seam so tests can drive the wait loop without real delays. */
+export type Sleeper = (ms: number) => Promise<void>;
+
 /** Opening is on unless MIRU_OPEN_BROWSER is set to something other than "1" (matches `miru setup`). */
 function openIfAllowed(open: BrowserOpener, url: string): boolean {
   const raw = process.env.MIRU_OPEN_BROWSER;
@@ -42,8 +56,14 @@ function openIfAllowed(open: BrowserOpener, url: string): boolean {
   return open(url);
 }
 
-function approvalText(link: string, userCode: string, opened: boolean): string {
-  const lead = opened ? `A browser tab is open at ${link}` : `Ask the user to open ${link}`;
+/** `opened` is null when resuming an existing login (no new tab was opened). */
+function approvalText(link: string, userCode: string, opened: boolean | null): string {
+  const lead =
+    opened === null
+      ? `Still waiting for approval at ${link}`
+      : opened
+        ? `A browser tab is open at ${link}`
+        : `Ask the user to open ${link}`;
   return `${lead}. Code: ${userCode}. ${CHECK_HINT}`;
 }
 
@@ -71,11 +91,17 @@ function isExpired(entry: PendingDeviceAuth): boolean {
 class AuthToolState {
   private pending: PendingDeviceAuth | null = null;
 
-  constructor(private readonly openBrowser: BrowserOpener) {}
+  constructor(
+    private readonly openBrowser: BrowserOpener,
+    private readonly waitMs: number,
+    private readonly sleep: Sleeper,
+  ) {}
 
   async start(): Promise<ToolResult> {
     let pending = this.pending;
+    let fresh = false;
     if (!pending || isExpired(pending)) {
+      fresh = true;
       const config = resolveDeviceAuthConfig();
       const start = await startDeviceAuthorization({ config });
       pending = { start, config, startedAtMs: Date.now() };
@@ -84,21 +110,33 @@ class AuthToolState {
 
     const { verificationUriComplete, verificationUri, userCode } = pending.start;
     const link = verificationUriComplete ?? verificationUri;
-    // Reopening on a repeat call is deliberate: the user may have closed the first tab.
-    return toolText(approvalText(link, userCode, openIfAllowed(this.openBrowser, link)));
+    // Only a new login opens a tab; a repeat call just resumes the wait.
+    const opened = fresh ? openIfAllowed(this.openBrowser, link) : null;
+
+    const settled = await this.waitForApproval(pending);
+    return settled ?? toolText(approvalText(link, userCode, opened));
   }
 
-  async check(): Promise<ToolResult> {
-    if (!this.pending) {
-      return toolText('No device login is pending. Call `auth` with action "start" first.');
+  /** Poll until approved, denied or expired, or the wait budget runs out (then null). */
+  private async waitForApproval(entry: PendingDeviceAuth): Promise<ToolResult | null> {
+    const deadline = Date.now() + this.waitMs;
+    let intervalMs = Math.max(entry.start.interval * 1000, MIN_POLL_INTERVAL_MS);
+    while (Date.now() + intervalMs <= deadline) {
+      await this.sleep(intervalMs);
+      const result = await checkDeviceAuthorizationOnce(entry.start, { config: entry.config });
+      const settled = await this.settle(result);
+      if (settled) {
+        return settled;
+      }
+      if (result.status === "slow_down") {
+        intervalMs += SLOW_DOWN_STEP_MS;
+      }
     }
+    return null;
+  }
 
-    const { start, config } = this.pending;
-    // Errors (network failure, unrecognized OAuth error code) intentionally leave
-    // `pending` intact — a transient failure shouldn't force the user to restart
-    // the whole login, just retry the check.
-    const result = await checkDeviceAuthorizationOnce(start, { config });
-
+  /** Handle a final poll result; null means the login is still pending. */
+  private async settle(result: DeviceAuthorizationCheck): Promise<ToolResult | null> {
     switch (result.status) {
       case "success": {
         this.pending = null;
@@ -114,31 +152,51 @@ class AuthToolState {
         setStoredCredentialsEnvToken(tokens.accessToken);
         return toolText("Signed in successfully. Miru tools are now ready to use.");
       }
-      case "pending":
-        return toolText(
-          'Still waiting for approval. Ask the user to confirm they clicked and approved, then call `auth` again with action "check".',
-        );
-      case "slow_down":
-        return toolText(
-          'Checking too soon — wait a bit before calling `auth` again with action "check".',
-        );
       case "denied":
         this.pending = null;
-        return toolText('Sign-in was denied. Call `auth` with action "start" to try again.');
+        return toolText("Sign-in was denied. Call `auth` again to try again.");
       case "expired":
         this.pending = null;
         return toolText(
-          'The device code expired before it was approved. Call `auth` with action "start" to try again.',
+          "The device code expired before it was approved. Call `auth` again to get a new one.",
         );
+      default:
+        return null;
+    }
+  }
+
+  async check(): Promise<ToolResult> {
+    if (!this.pending) {
+      return toolText('No device login is pending. Call `auth` with action "start" first.');
     }
+
+    const { start, config } = this.pending;
+    // Errors (network failure, unrecognized OAuth error code) intentionally leave
+    // `pending` intact — a transient failure shouldn't force the user to restart
+    // the whole login, just retry the check.
+    const result = await checkDeviceAuthorizationOnce(start, { config });
+
+    const settled = await this.settle(result);
+    if (settled) {
+      return settled;
+    }
+    return toolText(
+      result.status === "slow_down"
+        ? "Checking too soon — wait a bit before calling `auth` again."
+        : "Still waiting for approval. Ask the user to confirm they clicked and approved, then call `auth` again.",
+    );
   }
 }
 
 export function registerAuthTool(
   server: MiruMcpServer,
-  options?: { openBrowser?: BrowserOpener },
+  options?: { openBrowser?: BrowserOpener; waitMs?: number; sleep?: Sleeper },
 ): void {
-  const state = new AuthToolState(options?.openBrowser ?? openBrowserForDeviceLogin);
+  const state = new AuthToolState(
+    options?.openBrowser ?? openBrowserForDeviceLogin,
+    options?.waitMs ?? DEFAULT_WAIT_MS,
+    options?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+  );
 
   server.registerTool(
     "auth",
@@ -148,7 +206,9 @@ export function registerAuthTool(
         action: z
           .enum(["start", "check"])
           .optional()
-          .describe('"start" begins a device-code login (default); "check" completes it.'),
+          .describe(
+            '"start" begins or resumes a device-code login and waits for approval (default); "check" is a single non-blocking poll.',
+          ),
       },
     },
     async ({ action }) => {