miki-moni 0.3.1

package/src/vscode-bridge.ts

@@ -0,0 +1,407 @@
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import type { WebSocket } from "ws";
+import type { ExtRegistry } from "./ext-registry.js";
+import type { MsgSubmit, MsgSubmitAck, ExtMessage } from "./protocol-ext.js";
+
+/**
+ * Hook-reported cwd ≠ where the session's transcript actually lives.
+ * Find the directory under ~/.claude/projects/ that contains `<sessionUuid>.jsonl`,
+ * then read the actual cwd from the JSONL itself (entries carry a `cwd` field
+ * with the real workspace path).
+ *
+ * Why not decode the folder name (e.g. "D--code-miki-moni-tests"): Claude Code
+ * encodes both `\` and `-` as `-`, so the encoding is lossy — "miki-moni" inside
+ * the path becomes ambiguous. The JSONL `cwd` field is the source of truth.
+ *
+ * Falls back to the caller-provided cwd if nothing is found.
+ */
+export async function resolveSessionCwd(sessionUuid: string, fallbackCwd: string): Promise<string> {
+  const projectsRoot = path.join(os.homedir(), ".claude", "projects");
+  let dirs: string[];
+  try {
+    dirs = await fs.readdir(projectsRoot);
+  } catch {
+    return fallbackCwd;
+  }
+  for (const d of dirs) {
+    const candidate = path.join(projectsRoot, d, `${sessionUuid}.jsonl`);
+    try {
+      await fs.access(candidate);
+      // Found the transcript. Read it and pull cwd from the first entry that has one.
+      try {
+        const raw = await fs.readFile(candidate, "utf8");
+        const lines = raw.split(/\r?\n/);
+        for (const line of lines) {
+          if (!line || !line.includes('"cwd"')) continue;
+          try {
+            const e = JSON.parse(line);
+            if (typeof e?.cwd === "string" && e.cwd) return e.cwd;
+          } catch { /* keep scanning */ }
+        }
+      } catch { /* file read failed — fall through */ }
+      // No cwd in JSONL; use fallback rather than guess from folder name.
+      return fallbackCwd;
+    } catch {
+      // not in this dir, keep looking
+    }
+  }
+  return fallbackCwd;
+}
+
+export type LaunchFn = (url: string) => Promise<void>;
+
+export const defaultLaunch: LaunchFn = (url) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(
+      "powershell",
+      ["-NoProfile", "-Command", `Start-Process -FilePath '${url.replace(/'/g, "''")}'`],
+      { stdio: "ignore", windowsHide: true }
+    );
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))));
+    child.on("error", reject);
+  });
+
+// Headless: run `claude -r <session_uuid> -p "<prompt>"` in the session's cwd.
+// Returns Claude's plaintext reply. Throws on non-zero exit or timeout.
+export type HeadlessFn = (opts: {
+  sessionUuid: string;
+  cwd: string;
+  prompt: string;
+  maxBudgetUsd?: number;
+  timeoutMs?: number;
+}) => Promise<{ reply: string; exitCode: number; durationMs: number }>;
+
+// Resolve the `claude` executable to an absolute path so spawn doesn't depend
+// on daemon PATH inheritance (which can be empty depending on how the daemon
+// was launched). Tries common Windows + POSIX install locations.
+let resolvedClaudePathCache: string | null = null;
+async function resolveClaudePath(): Promise<string> {
+  if (resolvedClaudePathCache) return resolvedClaudePathCache;
+  const home = os.homedir();
+  const candidates = process.platform === "win32"
+    ? [
+        path.join(home, ".local", "bin", "claude.exe"),
+        path.join(home, ".local", "bin", "claude.cmd"),
+        path.join(home, "AppData", "Local", "Programs", "claude", "claude.exe"),
+        path.join(home, "AppData", "Roaming", "npm", "claude.cmd"),
+      ]
+    : [
+        "/usr/local/bin/claude",
+        path.join(home, ".local", "bin", "claude"),
+        path.join(home, ".npm-global", "bin", "claude"),
+      ];
+  for (const p of candidates) {
+    try { await fs.access(p); resolvedClaudePathCache = p; return p; } catch { /* try next */ }
+  }
+  // Last resort: trust PATH and hope for the best. spawn will ENOENT clearly.
+  return "claude";
+}
+
+export const defaultHeadless: HeadlessFn = async ({ sessionUuid, cwd, prompt, maxBudgetUsd = 5, timeoutMs = 120_000 }) => {
+  // The session's transcript may live in a different workspace than the cwd
+  // the daemon last saw (hooks fire with whatever sub-dir was active). Find the
+  // real one or `claude -r <id>` will fail with "No conversation found".
+  const actualCwd = await resolveSessionCwd(sessionUuid, cwd);
+  const claudeBin = await resolveClaudePath();
+  return new Promise<{ reply: string; exitCode: number; durationMs: number }>((resolve, reject) => {
+    const start = Date.now();
+    // Spawn claude.exe via absolute path. Pass prompt via STDIN.
+    // KNOWN LIMITATION on Windows: non-ASCII characters in the prompt get
+    // mangled in claude.exe's stdin parsing (system codepage issue).
+    // English prompts work correctly. See README "Known Limitations".
+    const child = spawn(
+      claudeBin,
+      ["-r", sessionUuid, "-p", "--max-budget-usd", String(maxBudgetUsd)],
+      { cwd: actualCwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, shell: false },
+    );
+    child.stdin?.write(Buffer.from(prompt, "utf8"));
+    child.stdin?.end();
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      reject(new Error(`headless claude timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      const durationMs = Date.now() - start;
+      const reply = stdout.trim();
+      // Tolerate non-zero exit when the response was actually generated. Claude
+      // Code's community lifecycle hook (session-lifecycle-hook.mjs SessionEnd)
+      // sometimes fails AFTER the model already produced a response, causing
+      // claude.exe to exit 1 with empty stderr — but the reply IS on stdout
+      // and IS in the transcript. Treat that as success.
+      if (reply) {
+        resolve({ reply, exitCode: code ?? 0, durationMs });
+        return;
+      }
+      reject(new Error(
+        `headless claude exited ${code} (cwd=${actualCwd}, empty stdout): ${stderr.trim().slice(0, 500) || "(empty stderr too — likely SessionEnd hook failure with no response generated)"}`,
+      ));
+    });
+    child.on("error", (err) => { clearTimeout(timer); reject(err); });
+  });
+};
+
+/**
+ * Build a PowerShell script that fires a vscode:// URI, then explicitly finds
+ * a VSCode top-level window via Win32 EnumWindows, force-focuses it (defeating
+ * the foreground-stealing block with AttachThreadInput), and SendKeys ENTER.
+ *
+ * The `'@` here-string terminator MUST be at column 0 in the produced script,
+ * so this function builds the script with no indentation on that line.
+ */
+function buildFocusAndEnterPS(url: string, folderHint: string, delayMs: number): string {
+  const u = url.replace(/'/g, "''");
+  const h = folderHint.replace(/'/g, "''");
+  // Note: the C# signature here-string MUST start with `@'` and end with `'@`
+  // both at column 0 of their line. JS template literal preserves indentation,
+  // so we avoid leading whitespace on those marker lines.
+  return `
+$ErrorActionPreference = 'Stop'
+
+Start-Process -FilePath '${u}'
+Start-Sleep -Milliseconds ${delayMs}
+
+$sig = @'
+[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+[DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr hWnd);
+[DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+[DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
+[DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+[DllImport("user32.dll")] public static extern bool AttachThreadInput(uint idAttach, uint idAttachTo, bool fAttach);
+[DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, IntPtr ProcessId);
+[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+[DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+[DllImport("user32.dll", CharSet=CharSet.Auto)] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder s, int n);
+public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+[DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
+[DllImport("user32.dll")] public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, IntPtr dwExtraInfo);
+[DllImport("user32.dll")] public static extern void SwitchToThisWindow(IntPtr hWnd, bool fAltTab);
+[DllImport("user32.dll")] public static extern bool LockSetForegroundWindow(uint uLockCode);
+[DllImport("user32.dll")] public static extern bool AllowSetForegroundWindow(uint dwProcessId);
+'@
+Add-Type -MemberDefinition $sig -Name 'U' -Namespace 'MikiMoni'
+
+$candidates = New-Object System.Collections.ArrayList
+$proc = [MikiMoni.U+EnumWindowsProc]{
+  param([IntPtr]$h, [IntPtr]$l)
+  if (-not [MikiMoni.U]::IsWindowVisible($h)) { return $true }
+  $sb = New-Object System.Text.StringBuilder 512
+  [MikiMoni.U]::GetWindowText($h, $sb, 512) | Out-Null
+  $title = $sb.ToString()
+  if ($title -match 'Visual Studio Code') {
+    [void]$candidates.Add(@{ Hwnd = $h; Title = $title })
+  }
+  return $true
+}
+[MikiMoni.U]::EnumWindows($proc, [IntPtr]::Zero) | Out-Null
+
+# Pick: (1) workspace-folder-hint match preferred, (2) current foreground if VSCode,
+# (3) first VSCode window.
+$best = $null
+$hint = '${h}'
+if ($hint -ne '') {
+  $best = $candidates | Where-Object { $_.Title -match [regex]::Escape($hint) } | Select-Object -First 1
+}
+if (-not $best) {
+  $fg = [MikiMoni.U]::GetForegroundWindow()
+  $best = $candidates | Where-Object { $_.Hwnd -eq $fg } | Select-Object -First 1
+}
+if (-not $best -and $candidates.Count -gt 0) { $best = $candidates[0] }
+
+Write-Output ("candidates=" + $candidates.Count)
+foreach ($c in $candidates) { Write-Output ("  cand hwnd=" + $c.Hwnd + " title=" + $c.Title) }
+
+if (-not $best) {
+  Write-Error ("No VSCode window found (candidates: " + $candidates.Count + ")")
+  exit 2
+}
+
+$fgBefore = [MikiMoni.U]::GetForegroundWindow()
+$hwnd = $best.Hwnd
+Write-Output ("picked hwnd=" + $hwnd + " title=" + $best.Title)
+Write-Output ("fg-before hwnd=" + $fgBefore)
+
+if ([MikiMoni.U]::IsIconic($hwnd)) { [MikiMoni.U]::ShowWindow($hwnd, 9) | Out-Null }  # SW_RESTORE
+
+# Defeat Win10/11 foreground lock — proven AutoHotkey recipe:
+#   1. LockSetForegroundWindow(LSFW_UNLOCK=2) — explicit unlock
+#   2. keybd_event ALT down/up — simulated user input grants this thread
+#      foreground rights for one SetForegroundWindow call (the classic trick)
+#   3. AttachThreadInput to target VSCode thread (defeats ownership check)
+#   4. SetForegroundWindow + BringWindowToTop
+#   5. SwitchToThisWindow as belt-and-suspenders (undocumented but bypasses lock)
+[MikiMoni.U]::LockSetForegroundWindow(2) | Out-Null  # LSFW_UNLOCK
+[MikiMoni.U]::keybd_event(0x12, 0, 0, [IntPtr]::Zero)             # VK_MENU down
+[MikiMoni.U]::keybd_event(0x12, 0, 2, [IntPtr]::Zero)             # VK_MENU up (KEYEVENTF_KEYUP=2)
+Start-Sleep -Milliseconds 30
+
+$targetTid = [MikiMoni.U]::GetWindowThreadProcessId($hwnd, [IntPtr]::Zero)
+$myTid     = [MikiMoni.U]::GetCurrentThreadId()
+$attachOk  = [MikiMoni.U]::AttachThreadInput($myTid, $targetTid, $true)
+$setFgOk   = [MikiMoni.U]::SetForegroundWindow($hwnd)
+[MikiMoni.U]::BringWindowToTop($hwnd) | Out-Null
+[MikiMoni.U]::SwitchToThisWindow($hwnd, $true)
+[MikiMoni.U]::AttachThreadInput($myTid, $targetTid, $false) | Out-Null
+Start-Sleep -Milliseconds 200
+
+$fgAfter = [MikiMoni.U]::GetForegroundWindow()
+Write-Output ("attach=" + $attachOk + " setFg=" + $setFgOk + " fg-after=" + $fgAfter + " match=" + ($fgAfter -eq $hwnd))
+
+Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.SendKeys]::SendWait('{ENTER}')
+Write-Output "enter-sent"
+`.trim();
+}
+
+export class VscodeBridge {
+  constructor(
+    private launch: LaunchFn = defaultLaunch,
+    private headless: HeadlessFn = defaultHeadless,
+  ) {}
+
+  async focus(sessionUuid: string | null): Promise<void> {
+    const base = "vscode://anthropic.claude-code/open";
+    const url = sessionUuid ? `${base}?session=${sessionUuid}` : base;
+    await this.launch(url);
+  }
+
+  /**
+   * Pre-fill the prompt in the Claude panel input box (does NOT submit).
+   * Uses vscode://anthropic.claude-code/open?session=...&prompt=...
+   */
+  async send(sessionUuid: string | null, prompt: string): Promise<void> {
+    const parts: string[] = [];
+    if (sessionUuid) parts.push(`session=${encodeURIComponent(sessionUuid)}`);
+    parts.push(`prompt=${encodeURIComponent(prompt)}`);
+    const url = `vscode://anthropic.claude-code/open?${parts.join("&")}`;
+    await this.launch(url);
+  }
+
+  /**
+   * Prefill + auto-press Enter — explicitly find a VSCode window and force-focus
+   * it via Win32 P/Invoke before SendKeys, so the Enter cannot land on the
+   * browser the user clicked "送出" from.
+   *
+   * Flow:
+   *   1. Start-Process URI       → Windows dispatches to anthropic.claude-code
+   *                                 extension, which opens/focuses the right tab
+   *   2. Sleep delayMs           → let VSCode prefill the input box
+   *   3. EnumWindows             → find top-level windows with title matching
+   *                                 "Visual Studio Code"; prefer one whose
+   *                                 title contains the workspace folder name
+   *   4. AttachThreadInput trick → defeat foreground-stealing prevention so
+   *                                 SetForegroundWindow actually works even
+   *                                 though this PowerShell process is not fg
+   *   5. SendKeys {ENTER}        → submitted to the now-focused VSCode panel
+   */
+  async prefillAndSubmitLegacy(
+    sessionUuid: string | null,
+    prompt: string,
+    opts: { cwd?: string; delayMs?: number } = {},
+  ): Promise<{ diag: string }> {
+    if (process.platform !== "win32") {
+      await this.send(sessionUuid, prompt);
+      return { diag: "non-win32: prefill only, no SendKeys" };
+    }
+    const delayMs = opts.delayMs ?? 1000;
+    // Workspace folder name hint for title matching.
+    // "d:\code\miki-moni" → "miki-moni" ; "d:\code" → "code"
+    const folderHint = (opts.cwd ?? "").split(/[\\/]/).filter(Boolean).pop() ?? "";
+    const parts: string[] = [];
+    if (sessionUuid) parts.push(`session=${encodeURIComponent(sessionUuid)}`);
+    parts.push(`prompt=${encodeURIComponent(prompt)}`);
+    const url = `vscode://anthropic.claude-code/open?${parts.join("&")}`;
+    const ps = buildFocusAndEnterPS(url, folderHint, delayMs);
+    return new Promise<{ diag: string }>((resolve, reject) => {
+      const child = spawn(
+        "powershell",
+        ["-NoProfile", "-Command", ps],
+        { stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
+      );
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.on("data", (c) => { stdout += c.toString(); });
+      child.stderr?.on("data", (c) => { stderr += c.toString(); });
+      child.on("exit", (code) => {
+        const diag = `exit=${code} stdout=[${stdout.trim()}] stderr=[${stderr.trim()}]`;
+        if (code === 0) resolve({ diag });
+        else reject(new Error(`prefillAndSubmit ${diag}`));
+      });
+      child.on("error", reject);
+    });
+  }
+
+  /**
+   * Headless submit: actually run Claude with the prompt against the given session.
+   * Transcript is appended on disk → VSCode picks up the new user msg + Claude reply.
+   * Costs real API money. Caller chooses this vs prefill.
+   */
+  async submit(args: { sessionUuid: string; cwd: string; prompt: string; maxBudgetUsd?: number; timeoutMs?: number }): Promise<{ reply: string; exitCode: number; durationMs: number }> {
+    return this.headless(args);
+  }
+
+  /**
+   * Send a submit request to the helper extension that owns the given cwd's
+   * workspace, and await its ack. Returns {ok, error?, diag?}.
+   */
+  async submitViaHelper(args: {
+    sessionUuid: string;
+    prompt: string;
+    cwd: string;
+    registry: ExtRegistry;
+    timeoutMs?: number;
+  }): Promise<{ ok: boolean; error?: string; diag?: string }> {
+    const ws = args.registry.findForCwd(args.cwd) as WebSocket | null;
+    if (!ws) {
+      return {
+        ok: false,
+        error: `no miki-helper extension registered for workspace covering ${args.cwd}; install the VSIX into that VSCode window: npm run install-helper`,
+      };
+    }
+    const requestId = randomUUID();
+    const submitMsg: MsgSubmit = {
+      type: "submit",
+      request_id: requestId,
+      session_uuid: args.sessionUuid,
+      prompt: args.prompt,
+    };
+    const timeoutMs = args.timeoutMs ?? 10_000;
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        ws.off("message", onMessage);
+        resolve({ ok: false, error: `submit_ack timeout after ${timeoutMs}ms` });
+      }, timeoutMs);
+
+      const onMessage = (raw: any) => {
+        let msg: ExtMessage;
+        try { msg = JSON.parse(String(raw)); } catch { return; }
+        if (msg.type !== "submit_ack") return;
+        if ((msg as MsgSubmitAck).request_id !== requestId) return;
+        clearTimeout(timer);
+        ws.off("message", onMessage);
+        const ack = msg as MsgSubmitAck;
+        resolve({
+          ok: ack.ok,
+          ...(ack.error !== undefined ? { error: ack.error } : {}),
+          ...(ack.diag !== undefined ? { diag: ack.diag } : {}),
+        });
+      };
+      ws.on("message", onMessage);
+      try { ws.send(JSON.stringify(submitMsg)); }
+      catch (err) {
+        clearTimeout(timer);
+        ws.off("message", onMessage);
+        resolve({ ok: false, error: `ws send failed: ${String(err)}` });
+      }
+    });
+  }
+}

package/src/wrap-process.ts

@@ -0,0 +1,183 @@
+// wrap-process — owns the lifecycle of `miki claude` CLI processes that the
+// daemon itself spawned (via POST /wrap/start). Decoupled from WS bookkeeping
+// so the kill / orphan-detection logic stays testable.
+//
+// Responsibilities:
+//   1. Record each spawn: cwd, intended session_uuid (if -r mode), spawn ts.
+//   2. When a wrap WS register lands, link the connection's reported PID to
+//      that record (so we know which OS process backs which session).
+//   3. On WS close, taskkill /T /F the PID tree → no Windows orphan.
+//   4. On daemon startup, scan for stray `miki claude` processes that aren't
+//      backed by an active WS connection and kill them.
+//
+// Why a module: the daemon will grow more "things daemon owns" (helper exts,
+// pty-mode tabs, future agent-pool workers). Each gets its own lifecycle file
+// rather than scattering PID maps across server.ts.
+
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import os from "node:os";
+
+const execFileP = promisify(execFile);
+
+export interface SpawnRecord {
+  /** Session this spawn is intended to attach to. null = `--fresh` style. */
+  sessionUuid: string | null;
+  cwd: string;
+  spawnedAt: number;
+  /** PID reported by wrap.ts at register time. null until we hear back. */
+  pid: number | null;
+}
+
+type Log = {
+  info: (obj: Record<string, unknown>, msg?: string) => void;
+  warn: (obj: Record<string, unknown>, msg?: string) => void;
+  error: (obj: Record<string, unknown>, msg?: string) => void;
+};
+
+export class WrapProcessRegistry {
+  // Keyed by sessionUuid for -r spawns. For fresh spawns the uuid is unknown
+  // at spawn time, so they get a temporary key until register lands.
+  private bySession = new Map<string, SpawnRecord>();
+  // Fresh-spawn records waiting for their first register. FIFO-ish: oldest
+  // unbound record gets linked to next incoming register without a uuid.
+  private pendingFresh: SpawnRecord[] = [];
+
+  constructor(private log?: Log) {}
+
+  /** Called by /wrap/start. `sessionUuid` is null for `--fresh`. */
+  recordSpawn(opts: { sessionUuid: string | null; cwd: string }): void {
+    const rec: SpawnRecord = {
+      sessionUuid: opts.sessionUuid,
+      cwd: opts.cwd,
+      spawnedAt: Date.now(),
+      pid: null,
+    };
+    if (opts.sessionUuid) {
+      this.bySession.set(opts.sessionUuid, rec);
+    } else {
+      this.pendingFresh.push(rec);
+    }
+    this.log?.info(
+      { sessionUuid: opts.sessionUuid, cwd: opts.cwd },
+      "wrap-process: recorded spawn",
+    );
+  }
+
+  /**
+   * Called when a wrap WS register / late-bind tells us its PID + final UUID.
+   * If we previously had a `--fresh` record awaiting binding, hand it the uuid.
+   */
+  bindPid(sessionUuid: string, pid: number | null): void {
+    if (!pid) return;
+    let rec = this.bySession.get(sessionUuid);
+    if (!rec) {
+      // Promote oldest pending fresh record (if any) to this uuid.
+      rec = this.pendingFresh.shift() ?? null as any;
+      if (rec) {
+        rec.sessionUuid = sessionUuid;
+        this.bySession.set(sessionUuid, rec);
+      }
+    }
+    if (!rec) {
+      // External wrap (user typed `pnpm miki claude` themselves, not via dashboard).
+      // We don't manage its lifecycle; ignore.
+      return;
+    }
+    rec.pid = pid;
+    this.log?.info({ sessionUuid, pid }, "wrap-process: PID bound");
+  }
+
+  /**
+   * Called on wrap WS close. Returns the PID (if any) the caller should
+   * tree-kill, and the SpawnRecord so the caller can decide cleanup policy
+   * (e.g. delete empty session row). Removes the record from the registry.
+   */
+  takeOnClose(sessionUuid: string): SpawnRecord | null {
+    const rec = this.bySession.get(sessionUuid);
+    if (!rec) return null;
+    this.bySession.delete(sessionUuid);
+    return rec;
+  }
+
+  /** Visible for tests / debugging. */
+  list(): SpawnRecord[] {
+    return [...this.bySession.values(), ...this.pendingFresh];
+  }
+
+  /** Visible for tests. */
+  size(): number {
+    return this.bySession.size + this.pendingFresh.length;
+  }
+}
+
+/**
+ * Best-effort tree-kill on Windows. Calls `taskkill /T /F /PID <pid>` which
+ * terminates the process and ALL descendants. Resolves silently on failure
+ * (process already dead, etc.) — caller doesn't care about the distinction
+ * between "killed it" and "it was already gone".
+ */
+export async function killProcessTree(pid: number, log?: Log): Promise<void> {
+  if (!Number.isFinite(pid) || pid <= 0) return;
+  try {
+    if (process.platform === "win32") {
+      await execFileP("taskkill.exe", ["/T", "/F", "/PID", String(pid)]);
+    } else {
+      // POSIX fallback (not used in production for miki, but keeps tests portable)
+      process.kill(pid, "SIGKILL");
+    }
+    log?.info({ pid }, "wrap-process: tree-killed");
+  } catch (err) {
+    // Most common cause: process already exited between our decision to kill
+    // and the syscall actually running. Genuinely fine.
+    log?.info({ pid, error: String(err) }, "wrap-process: kill skipped (likely already dead)");
+  }
+}
+
+/**
+ * Scan the OS for `miki claude` node processes and return their PIDs. Used on
+ * daemon startup to clear out stragglers from a previous daemon session that
+ * left orphans behind. Windows-only implementation; returns [] elsewhere.
+ *
+ * Identifies miki processes by command-line substring match: looks for any
+ * node.exe whose CommandLine contains "miki.ts claude" or "src/cli/miki.ts".
+ * That's specific enough to not accidentally kill unrelated Node tools, and
+ * generic enough to catch both tsx and compiled invocations.
+ */
+export async function findOrphanMikiCli(log?: Log): Promise<number[]> {
+  if (process.platform !== "win32") return [];
+  try {
+    // PowerShell one-liner — return PIDs whose command line matches our pattern.
+    // Output: one PID per line, no headers.
+    const { stdout } = await execFileP("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+      "-Command",
+      "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Where-Object { $_.CommandLine -match 'miki\\.ts.*claude|cli[/\\\\]miki' } | Select-Object -ExpandProperty ProcessId",
+    ]);
+    const pids = stdout.split(/\r?\n/).map((s) => parseInt(s.trim(), 10)).filter((n) => Number.isFinite(n) && n > 0);
+    // Filter out ourselves and any parent of ourselves (defensive — daemon
+    // shouldn't match the pattern, but just in case during dev).
+    const self = process.pid;
+    return pids.filter((p) => p !== self);
+  } catch (err) {
+    log?.warn({ error: String(err) }, "wrap-process: orphan scan failed");
+    return [];
+  }
+}
+
+/** Convenience: scan + kill all orphans. Returns number killed. */
+export async function killOrphans(log?: Log): Promise<number> {
+  const pids = await findOrphanMikiCli(log);
+  if (pids.length === 0) return 0;
+  await Promise.all(pids.map((pid) => killProcessTree(pid, log)));
+  log?.info({ pids, count: pids.length }, "wrap-process: orphans killed at startup");
+  return pids.length;
+}
+
+// Re-export `spawn` for callers that want to launch wt.exe through the same
+// module (kept lightweight on purpose — we don't wrap spawn() because wt.exe
+// is detached and we don't track its launcher PID anyway).
+export { spawn };
+
+// Expose os.platform for tests that want to skip on non-Windows.
+export { os };