miki-moni 0.3.1

package/src/config.ts

@@ -0,0 +1,121 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { generateKeypair, generateSigningKeypair, toBase64 } from "./crypto.js";
+
+export interface PairedPeer {
+  peer_id: string;
+  peer_name: string;
+  peer_pubkey: string;          // X25519 encryption pubkey (base64) — for shared secret
+  peer_sign_pubkey?: string;    // Ed25519 signing pubkey (base64) — keys the relay's
+                                // paired_phones map; required for revoke_phone RPC
+  shared_secret: string;        // base64 (32 bytes)
+  paired_at: number;
+  last_seen_at: number | null;
+}
+
+export interface RemoteEndpoint {
+  worker_url: string;          // wss://...
+  /** Where the QR points. Defaults to the hosted PWA (https://miki-moni.pages.dev/);
+   *  self-hosters get their own *.pages.dev written here by the setup wizard. */
+  phone_pwa_url?: string;
+  /** Persistent pairing token. Once set, the daemon registers this same token
+   *  with the relay coordinator every restart, so the QR is permanent until
+   *  the user explicitly rotates it with `pnpm pair --rotate`. 16-char
+   *  Crockford base32. Optional for back-compat with old configs and for users
+   *  who prefer ephemeral pair tokens via `pnpm pair --new`. */
+  pair_token?: string;
+}
+
+/** UI language for setup wizard, CLI banner, dashboard. Persisted across runs. */
+export type Locale = "en" | "zh-CN" | "zh-TW";
+
+export interface Config {
+  device: {
+    name: string;
+    pubkey: string;             // X25519 box pub, base64
+    privkey: string;            // X25519 box priv, base64
+    signing_pubkey: string;     // Ed25519 sign pub, base64
+    signing_privkey: string;    // Ed25519 sign priv (64B), base64
+    created_at: number;
+  };
+  /** Preferred UI language. Set by the setup wizard's first step; can be
+   *  overridden anytime by editing config.json or via a future `miki locale`
+   *  command. Defaults to "en" if missing (e.g. older configs). */
+  locale?: Locale;
+  remote?: RemoteEndpoint;
+  paired_peers: PairedPeer[];
+}
+
+function defaultDeviceName(): string {
+  return os.hostname() || `device-${Date.now()}`;
+}
+
+function makeDefaultConfig(): Config {
+  const box = generateKeypair();
+  const sign = generateSigningKeypair();
+  return {
+    device: {
+      name: defaultDeviceName(),
+      pubkey: toBase64(box.pubkey),
+      privkey: toBase64(box.privkey),
+      signing_pubkey: toBase64(sign.pubkey),
+      signing_privkey: toBase64(sign.privkey),
+      created_at: Date.now(),
+    },
+    paired_peers: [],
+  };
+}
+
+/** Load config; migrate older configs lacking signing keys; return final. */
+export async function loadOrInitConfig(filePath: string): Promise<Config> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      const cfg = makeDefaultConfig();
+      await saveConfig(filePath, cfg);
+      return cfg;
+    }
+    throw err;
+  }
+  let parsed: Config;
+  try {
+    parsed = JSON.parse(raw) as Config;
+  } catch (err) {
+    throw new Error(`Failed to parse config at ${filePath}: ${(err as Error).message}`);
+  }
+  // Migrate: add signing keys if missing
+  if (!parsed.device.signing_pubkey || !parsed.device.signing_privkey) {
+    const sign = generateSigningKeypair();
+    parsed.device.signing_pubkey = toBase64(sign.pubkey);
+    parsed.device.signing_privkey = toBase64(sign.privkey);
+    await saveConfig(filePath, parsed);
+  }
+  // Migrate: remove deprecated x_daemon_auth_token from remote if present
+  if (parsed.remote && (parsed.remote as any).x_daemon_auth_token) {
+    delete (parsed.remote as any).x_daemon_auth_token;
+    await saveConfig(filePath, parsed);
+  }
+  return parsed;
+}
+
+export async function saveConfig(filePath: string, cfg: Config): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await fs.writeFile(tmp, JSON.stringify(cfg, null, 2));
+  await fs.rename(tmp, filePath);
+}
+
+export function addPairedPeer(cfg: Config, peer: PairedPeer): Config {
+  return { ...cfg, paired_peers: [...cfg.paired_peers, peer] };
+}
+
+export function removePairedPeer(cfg: Config, peerId: string): Config {
+  return { ...cfg, paired_peers: cfg.paired_peers.filter((p) => p.peer_id !== peerId) };
+}
+
+export function findPeerById(cfg: Config, peerId: string): PairedPeer | null {
+  return cfg.paired_peers.find((p) => p.peer_id === peerId) ?? null;
+}

package/src/crypto.ts

@@ -0,0 +1,66 @@
+import nacl from "tweetnacl";
+import naclUtil from "tweetnacl-util";
+
+export interface Keypair {
+  pubkey: Uint8Array;  // 32 bytes
+  privkey: Uint8Array; // 32 bytes
+}
+
+export function generateKeypair(): Keypair {
+  const kp = nacl.box.keyPair();
+  return { pubkey: kp.publicKey, privkey: kp.secretKey };
+}
+
+export function deriveSharedSecret(myPrivkey: Uint8Array, theirPubkey: Uint8Array): Uint8Array {
+  // X25519 ECDH; same output for both sides
+  return nacl.box.before(theirPubkey, myPrivkey);
+}
+
+export interface Encrypted {
+  ct: string;     // base64
+  nonce: string;  // base64 (24 bytes)
+}
+
+export function encrypt(plaintext: string, sharedSecret: Uint8Array): Encrypted {
+  const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
+  const ptBytes = naclUtil.decodeUTF8(plaintext);
+  const ctBytes = nacl.secretbox(ptBytes, nonce, sharedSecret);
+  return { ct: toBase64(ctBytes), nonce: toBase64(nonce) };
+}
+
+export function decrypt(ct: string, nonce: string, sharedSecret: Uint8Array): string | null {
+  const ctBytes = fromBase64(ct);
+  const nonceBytes = fromBase64(nonce);
+  if (nonceBytes.length !== nacl.secretbox.nonceLength) return null;
+  const ptBytes = nacl.secretbox.open(ctBytes, nonceBytes, sharedSecret);
+  if (!ptBytes) return null;
+  return naclUtil.encodeUTF8(ptBytes);
+}
+
+export function toBase64(bytes: Uint8Array): string {
+  return naclUtil.encodeBase64(bytes);
+}
+
+export function fromBase64(s: string): Uint8Array {
+  return naclUtil.decodeBase64(s);
+}
+
+// ── Ed25519 signing (separate keypair from X25519 encryption keypair) ──────
+
+export interface SigningKeypair {
+  pubkey: Uint8Array;   // 32 bytes
+  privkey: Uint8Array;  // 64 bytes (nacl.sign secret = priv ++ pub)
+}
+
+export function generateSigningKeypair(): SigningKeypair {
+  const kp = nacl.sign.keyPair();
+  return { pubkey: kp.publicKey, privkey: kp.secretKey };
+}
+
+export function sign(message: Uint8Array, privkey: Uint8Array): Uint8Array {
+  return nacl.sign.detached(message, privkey);
+}
+
+export function verify(message: Uint8Array, sig: Uint8Array, pubkey: Uint8Array): boolean {
+  return nacl.sign.detached.verify(message, sig, pubkey);
+}

package/src/data-dir.ts

@@ -0,0 +1,31 @@
+import path from "node:path";
+import os from "node:os";
+import { promises as fs } from "node:fs";
+
+// Central runtime-data location for the Miki-Moni daemon.
+// Single source of truth — every component derives port file, config, sqlite,
+// log file from here.
+export const HUB_HOME = path.join(os.homedir(), ".miki-moni");
+export const PORT_FILE = path.join(HUB_HOME, "port");
+export const CONFIG_FILE = path.join(HUB_HOME, "config.json");
+export const DB_FILE = path.join(HUB_HOME, "state.db");
+export const LOG_FILE = path.join(HUB_HOME, "miki-moni.log");
+
+// One-shot migration from the legacy `~/.cc-hub` directory that pre-2026-05-17
+// installs used. If the legacy dir exists and the new one doesn't, rename
+// (preserves pairing keys, sessions DB, port file). Safe to call repeatedly —
+// after the first run the legacy dir is gone and this is a no-op.
+//
+// Must be invoked before any code reads or writes inside HUB_HOME.
+export async function migrateLegacyHubHome(): Promise<{ migrated: boolean }> {
+  const legacy = path.join(os.homedir(), ".cc-hub");
+  const [legacyExists, currentExists] = await Promise.all([
+    fs.access(legacy).then(() => true, () => false),
+    fs.access(HUB_HOME).then(() => true, () => false),
+  ]);
+  if (legacyExists && !currentExists) {
+    await fs.rename(legacy, HUB_HOME);
+    return { migrated: true };
+  }
+  return { migrated: false };
+}

package/src/ext-registry.ts

@@ -0,0 +1,47 @@
+import type { WebSocket } from "ws";
+import { normalizePath } from "./protocol-ext.js";
+
+export interface ExtInfo {
+  workspace_root: string;   // will be re-normalized inside add() — caller can pass raw
+  version: string;
+  registered_at: number;
+}
+
+interface InternalEntry {
+  ws: WebSocket | any;      // `any` to keep tests trivially mockable
+  info: ExtInfo;            // info.workspace_root is normalized
+}
+
+export class ExtRegistry {
+  private entries: InternalEntry[] = [];
+
+  add(ws: WebSocket | any, info: ExtInfo): void {
+    const normalized: ExtInfo = { ...info, workspace_root: normalizePath(info.workspace_root) };
+    // Replace existing entry for same ws (defensive — re-register on reconnect)
+    this.entries = this.entries.filter((e) => e.ws !== ws);
+    this.entries.push({ ws, info: normalized });
+  }
+
+  remove(ws: WebSocket | any): void {
+    this.entries = this.entries.filter((e) => e.ws !== ws);
+  }
+
+  findForCwd(cwd: string): WebSocket | null {
+    const target = normalizePath(cwd);
+    const matches = this.entries
+      .filter((e) => isAncestor(e.info.workspace_root, target))
+      .sort((a, b) => b.info.workspace_root.length - a.info.workspace_root.length);
+    return matches[0]?.ws ?? null;
+  }
+
+  list(): Array<{ info: ExtInfo }> {
+    return this.entries.map((e) => ({ info: e.info }));
+  }
+}
+
+// True when `cwd` equals `root` OR is a path-descendant of it.
+// Critically guards against false prefix matches: "d:/codex" must NOT match "d:/code".
+function isAncestor(root: string, cwd: string): boolean {
+  if (root === cwd) return true;
+  return cwd.startsWith(root + "/");
+}

package/src/hook-handler.ts

@@ -0,0 +1,86 @@
+import path from "node:path";
+import type { HookEvent, Session, SessionStatus } from "./types.js";
+import type { SessionStore } from "./session-store.js";
+import type { SessionResolver } from "./session-resolver.js";
+import type { Notifier } from "./notifier.js";
+
+const STATUS_BY_EVENT: Record<HookEvent["event_type"], SessionStatus> = {
+  session_start: "active",
+  user_prompt: "active",
+  pre_tool_use: "active",
+  post_tool_use: "active",
+  stop: "waiting",
+};
+
+function basename(cwd: string): string {
+  const normalized = cwd.replace(/\\/g, "/");
+  return path.posix.basename(normalized);
+}
+
+// On Windows, paths like "D:\code\x" and "d:/code/x" point to the same place.
+// Normalize: lowercase the drive letter and use backslashes consistently.
+export function normalizeCwd(cwd: string): string {
+  let n = cwd.replace(/\//g, "\\");
+  // Lowercase Windows drive letter (e.g. "D:\..." → "d:\...")
+  if (/^[A-Za-z]:/.test(n)) n = n[0]!.toLowerCase() + n.slice(1);
+  // Trim trailing backslash unless it's just a drive root like "c:\"
+  if (n.length > 3 && n.endsWith("\\")) n = n.replace(/\\+$/, "");
+  return n;
+}
+
+export class HookHandler {
+  constructor(
+    private store: SessionStore,
+    private resolver: SessionResolver,
+    private notifier?: Notifier,
+  ) {}
+
+  async handle(ev: HookEvent): Promise<void> {
+    const cwd = normalizeCwd(ev.cwd);
+
+    // session_uuid is the primary identity. Hooks should always provide it
+    // (Claude Code sends session_id in every hook event per the official docs).
+    // If absent, try resolver as a last resort; otherwise drop the event silently.
+    let sessionUuid = ev.session_uuid;
+    if (!sessionUuid) {
+      sessionUuid = await this.resolver.resolveLatest(cwd);
+      if (!sessionUuid) return;  // cannot insert without a primary key
+    }
+
+    const existing = this.store.get(sessionUuid);
+    if (existing && existing.last_event_at > ev.timestamp) return;  // last-write-wins
+
+    // cwd is IMMUTABLE once the row exists. Claude Code's projects-dir
+    // encoding is derived from the cwd-at-session-start; the SDK's
+    // `resume: uuid` only works if you pass that same cwd. If we let later
+    // hook events overwrite (e.g. the agent cd'd into a subfolder, or a
+    // tool runs in a different working dir), /wrap/start later uses the
+    // wrong cwd → SDK throws "No conversation found with session ID".
+    // The very first event for a uuid sets cwd; every subsequent event
+    // keeps it. Bug repro: agent cd'd from d:\code into d:\code\cc-hub →
+    // hook events flipped DB.cwd → wrap-spawn looked in d--code-cc-hub/
+    // for a transcript that actually lived in d--code/.
+    const cwdToStore = existing?.cwd ?? cwd;
+    const next: Session = {
+      cwd: cwdToStore,
+      session_uuid: sessionUuid,
+      project_name: existing?.project_name ?? basename(cwdToStore),
+      status: STATUS_BY_EVENT[ev.event_type],
+      last_event_at: ev.timestamp,
+      last_message_preview: existing?.last_message_preview ?? "",
+      tokens_in: existing?.tokens_in ?? 0,
+      tokens_out: existing?.tokens_out ?? 0,
+      vscode_pid: existing?.vscode_pid ?? null,
+    };
+    this.store.upsert(next);
+
+    const wasWaiting = existing?.status === "waiting";
+    const isWaiting = next.status === "waiting";
+    if (this.notifier && isWaiting && !wasWaiting) {
+      void this.notifier.notify({
+        project: next.project_name,
+        message: "Claude is waiting for you",
+      });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,279 @@
+import path from "node:path";
+import os from "node:os";
+import http from "node:http";
+import { promises as fs, appendFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import pino from "pino";
+import { createApp } from "./server.js";
+import { SessionStore } from "./session-store.js";
+import { SessionResolver } from "./session-resolver.js";
+import { HookHandler } from "./hook-handler.js";
+import { VscodeBridge } from "./vscode-bridge.js";
+import { Notifier } from "./notifier.js";
+import { loadOrInitConfig } from "./config.js";
+import { RelayClient } from "./relay-client.js";
+import { HUB_HOME, PORT_FILE, DB_FILE, CONFIG_FILE, LOG_FILE, migrateLegacyHubHome } from "./data-dir.js";
+import { killOrphans } from "./wrap-process.js";
+
+const PROJECTS_ROOT = path.join(os.homedir(), ".claude", "projects");
+const DEFAULT_PORT = 8765;
+
+async function findFreePort(start: number, maxTries = 10): Promise<number> {
+  const net = await import("node:net");
+  for (let i = 0; i < maxTries; i++) {
+    const port = start + i;
+    const free = await new Promise<boolean>((resolve) => {
+      const srv = net.createServer();
+      srv.once("error", () => resolve(false));
+      srv.once("listening", () => srv.close(() => resolve(true)));
+      srv.listen(port, "127.0.0.1");
+    });
+    if (free) return port;
+  }
+  throw new Error(`no free port in [${start}, ${start + maxTries})`);
+}
+
+// HTTP-probe a daemon on the given port. Returns true if it answers /sessions
+// within 800ms. Used as the singleton guard so a second `pnpm start` (or
+// wrap's auto-spawn) doesn't fork a duplicate daemon on a different port that
+// would race over PORT_FILE.
+async function pingDaemon(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${port}/sessions`, { timeout: 800 }, (res) => {
+      res.resume();
+      resolve((res.statusCode ?? 0) > 0);
+    });
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+async function readPortFile(): Promise<number | null> {
+  try {
+    const raw = await fs.readFile(PORT_FILE, "utf8");
+    const n = parseInt(raw.trim(), 10);
+    return Number.isFinite(n) ? n : null;
+  } catch { return null; }
+}
+
+async function main(): Promise<void> {
+  // Move legacy ~/.cc-hub into ~/.miki-moni on first boot after rename.
+  // Idempotent: no-op once new dir exists.
+  const mig = await migrateLegacyHubHome();
+  if (mig.migrated) {
+    console.log("migrated ~/.cc-hub → ~/.miki-moni (legacy install detected)");
+  }
+  await fs.mkdir(HUB_HOME, { recursive: true });
+
+  // Multi-stream: file gets the full debug trace for post-hoc support; stdout
+  // is quiet by default ("warn") so a normal end-user only sees genuine
+  // problems. Power users override with MIKI_LOG_LEVEL=info / debug etc.
+  const fileStream = (await import("node:fs")).createWriteStream(LOG_FILE, { flags: "a" });
+  const log = pino(
+    { level: "debug" },
+    pino.multistream([
+      { stream: process.stdout, level: process.env.MIKI_LOG_LEVEL ?? "warn" },
+      { stream: fileStream, level: "debug" },
+    ]),
+  );
+
+  // Singleton guard. PORT_FILE is shared global state; if another daemon is
+  // already alive, claiming a different port and overwriting PORT_FILE causes
+  // the dashboard and CLIs to split-brain across two daemons. Probe the
+  // currently-recorded port first, then the canonical default, then bail.
+  //
+  // The "two-daemons" race used to surface like this:
+  //   1. Daemon A runs on 8765, PORT_FILE=8765
+  //   2. A crashes; PORT_FILE still points at 8765 but no one's home
+  //   3. `miki claude` wrap reads 8765, ping fails, autostarts Daemon B
+  //   4. B's findFreePort skips 8765 (TIME_WAIT) → binds 8766 → writes
+  //      PORT_FILE=8766
+  //   5. A's old socket clears, user runs `pnpm start` again → Daemon C binds
+  //      8765 → writes PORT_FILE=8765 → race over PORT_FILE
+  // Refusing to start when a live daemon is detected eliminates the race
+  // entirely. Set MIKI_FORCE_RESTART=1 to skip the guard (e.g. for debugging).
+  if (!process.env.MIKI_FORCE_RESTART) {
+    for (const candidate of [await readPortFile(), DEFAULT_PORT]) {
+      if (candidate && await pingDaemon(candidate)) {
+        console.log(`miki-moni daemon already running on http://127.0.0.1:${candidate} — exiting (set MIKI_FORCE_RESTART=1 to override)`);
+        // Reconcile PORT_FILE in case it drifted (e.g. step 4 above): if the
+        // live port doesn't match PORT_FILE, fix it so the next CLI finds
+        // home on the first try.
+        const recorded = await readPortFile();
+        if (recorded !== candidate) {
+          await fs.writeFile(PORT_FILE, String(candidate));
+          log.info({ from: recorded, to: candidate }, "reconciled stale PORT_FILE");
+        }
+        process.exit(0);
+      }
+    }
+  }
+
+  const port = await findFreePort(DEFAULT_PORT);
+  await fs.writeFile(PORT_FILE, String(port));
+
+  const store = new SessionStore(DB_FILE);
+  // On daemon startup we don't know what's still alive. Mark everything stale
+  // (but DON'T delete) — dashboard can filter them out; hook events + wrap
+  // reconnects will upgrade the row back to "active" on next signal. This is
+  // safer than truncate(), which lost the row entirely and prevented /send
+  // routing for wrap sessions until they fired another hook.
+  const staled = store.markAllStale();
+  log.info({ staled }, "marked all sessions stale on startup");
+
+  // Opt-in orphan sweep. The `taskkill /T /F` in killProcessTree turned out
+  // to bring down the *current* daemon when the matched orphan happened to
+  // share a Windows job object with us (reproducible inside Claude Code's
+  // bash sandbox + likely the user's terminal too — daemon would die ~1.5s
+  // after listen with no exception, no signal, just TerminateProcess).
+  // Until killOrphans uses a safer mechanism (skip /T, or verify parent is
+  // dead before killing), it stays off by default. Wraps left over from a
+  // crashed daemon session just sit there — annoying but not fatal.
+  if (process.env.MIKI_KILL_ORPHANS === "1") {
+    killOrphans(log).then((n) => {
+      if (n > 0) log.info({ killed: n }, "swept orphan `miki claude` processes from previous daemon");
+    }).catch((err) => log.warn({ error: String(err) }, "orphan sweep failed (non-fatal)"));
+  }
+  const resolver = new SessionResolver(PROJECTS_ROOT);
+  const notifier = new Notifier();
+  const handler = new HookHandler(store, resolver, notifier);
+  const bridge = new VscodeBridge();
+  // Resolve dist/web relative to this source file. After a global npm install
+  // the daemon's process.cwd() is the user's calling dir, not the package
+  // root, so path.resolve("dist/web") would point at the wrong place.
+  const _moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const webDir = path.resolve(_moduleDir, "..", "dist", "web");
+
+  const { app, server } = createApp({ store, handler, bridge, notifier, webDir, log });
+
+  // Serve web UI if built
+  const express = (await import("express")).default;
+  app.use(express.static(webDir, { fallthrough: true }));
+
+  // Phase 2: optional remote relay to user's Cloudflare Worker
+  const config = await loadOrInitConfig(CONFIG_FILE);
+  let relay: RelayClient | null = null;
+  if (config.remote && config.paired_peers.length > 0) {
+    relay = new RelayClient({ config, store, bridge });
+    await relay.start();
+    log.info({ worker_url: config.remote.worker_url, peers: config.paired_peers.length }, "relay started");
+    console.log(`relay -> ${config.remote.worker_url} (${config.paired_peers.length} peer${config.paired_peers.length === 1 ? "" : "s"})`);
+  } else {
+    log.info("relay disabled (no remote configured or no paired peers)");
+  }
+
+  server.listen(port, "127.0.0.1", () => {
+    log.info({ port }, "miki-moni listening");
+    console.log(`miki-moni listening on http://127.0.0.1:${port}`);
+    // Windows-only: spawn the sleeping-cat tray icon so the user has a
+    // visible reminder the daemon is alive. Detached + unref'd so it owns
+    // its own lifetime; the script watches our PID and self-exits when we
+    // die. Failures here are non-fatal — the daemon is fully usable
+    // without the tray icon.
+    // Skip if MIKI_NO_TRAY_SPAWN=1 — set by /admin/restart / /admin/rotate-pair
+    // so respawned daemons don't duplicate the cat icon (the previous tray
+    // follows us via /admin/pid).
+    if (process.platform === "win32" && process.env.MIKI_NO_TRAY_SPAWN !== "1") {
+      spawnTrayHelper(port, log).catch((err) => {
+        log.warn({ err: String(err) }, "tray helper spawn failed (non-fatal)");
+      });
+    }
+  });
+
+  const shutdown = async () => {
+    log.info("shutting down");
+    if (relay) { try { await relay.stop(); } catch { /* ignore */ } }
+    server.close(() => { store.close(); process.exit(0); });
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+// Spawn tools/tray.ps1 as a detached child. The script renders a tray icon
+// with right-click menu (Open / Restart / Quit) and self-exits when our PID
+// disappears. Resolved relative to this file so it works whether the daemon
+// was launched from the repo or via a packaged `miki` global install.
+async function spawnTrayHelper(port: number, log: pino.Logger): Promise<void> {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  // src/index.ts compiled lives one level under repo root; tools/tray.ps1
+  // lives at the repo root. Two candidate paths so this works both in
+  // tsx-direct and in a built dist/ layout.
+  const candidates = [
+    path.resolve(here, "..", "tools", "tray.ps1"),
+    path.resolve(here, "..", "..", "tools", "tray.ps1"),
+  ];
+  let scriptPath: string | null = null;
+  for (const p of candidates) {
+    try { await fs.access(p); scriptPath = p; break; } catch { /* try next */ }
+  }
+  if (!scriptPath) {
+    log.warn({ candidates }, "tray.ps1 not found — skipping tray icon");
+    return;
+  }
+  // Two Windows-spawn quirks fixed here:
+  //
+  // 1. PowerShell's argv parser mangles Windows-style backslash paths when
+  //    they come through Node's CreateProcess wrapping ("D:\code\..."
+  //    became "D:codec..."). Forward slashes work natively on every
+  //    Windows tool and don't get eaten by escape processing.
+  //
+  // 2. STA is required for WinForms NotifyIcon (default MTA caused silent
+  //    exit on Application.Run when spawned from Node's CreateProcess
+  //    DETACHED_PROCESS flag).
+  //
+  // 3. Going through `cmd /c start /B` instead of spawning powershell.exe
+  //    directly side-steps a subtler Node-on-Windows issue where the
+  //    detached child still inherits CreateProcess flags that prevent
+  //    PowerShell from running a WinForms message pump. Direct spawn died
+  //    silently within ~1s; `Start-Process` from PowerShell worked fine,
+  //    and so does the cmd /c start indirection — both yield a process
+  //    with the flags Application.Run() expects.
+  const scriptForPs = scriptPath.replace(/\\/g, "/");
+  // -ExecutionPolicy Bypass: many users have the default `Restricted` policy
+  // which silently refuses to run .ps1 files. Bypass only applies to this one
+  // process invocation (we don't touch their system-wide policy).
+  // Capture stdout/stderr to the daemon log so silent crashes are debuggable.
+  const trayLog = path.join(path.dirname(LOG_FILE), "tray.log");
+  const child = spawn(
+    "cmd.exe",
+    [
+      "/c", "start", "/B", "",
+      "powershell.exe",
+      "-NoProfile", "-STA",
+      "-ExecutionPolicy", "Bypass",
+      "-WindowStyle", "Hidden",
+      "-File", scriptForPs,
+      "-DaemonPid", String(process.pid),
+      "-Port", String(port),
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", "ignore", "ignore"],
+      windowsHide: true,
+    },
+  );
+  child.on("error", (err) => log.warn({ err: String(err) }, "tray helper error"));
+  child.unref();
+  log.info({ scriptPath, pid: child.pid, trayLog }, "tray helper spawned");
+}
+
+// Catch silent crashes (Node's default for uncaughtException is to exit
+// with no error message). Write to LOG_FILE directly because pino's stream
+// may not flush before exit. ONLY catch — do NOT subscribe to beforeExit /
+// exit, which fire on every normal Node tick when the loop drains and
+// produce noise that looks like crashes.
+function logFatal(kind: string, err: unknown): void {
+  try {
+    const line = JSON.stringify({ level: 60, time: Date.now(), pid: process.pid, kind, err: String(err), stack: (err as Error)?.stack }) + "\n";
+    appendFileSync(LOG_FILE, line);
+    process.stderr.write(line);
+  } catch { /* nothing we can do */ }
+}
+process.on("uncaughtException", (err) => { logFatal("uncaughtException", err); process.exit(1); });
+process.on("unhandledRejection", (reason) => { logFatal("unhandledRejection", reason); });
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});