ispyx 0.0.0-stage → 1.0.1

package/src/core/guard.js

@@ -0,0 +1,287 @@
+// Safety layer: config, process denylist, emergency stop, action log.
+import fs from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import w from '../platform/index.js';
+const { chordDown, parseChord } = w;
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export class ToolError extends Error {}
+
+const DEFAULTS = {
+  // acts anywhere on the desktop; only the denylist (password managers) is refused
+  denylist: w.name === 'darwin'
+    ? ['1password', 'bitwarden', 'keepassxc', 'keychain access', 'enpass']
+    : ['keepass.exe', 'keepassxc.exe', '1password.exe', 'bitwarden.exe'],
+  // inside Ispyx.app the source tree is read-only and signed: keep the log in the per-user data directory there
+  logPath: w.name === 'darwin' ? path.join(w.dataDir(), 'logs', 'actions.jsonl') : path.join(ROOT, 'logs', 'actions.jsonl'),
+  stopChord: 'alt+esc', // emergency stop keys (env WIN_INPUT_STOP_CHORD, meant for tests)
+  overlay: true, // banner on screen while a tool runs
+  animations: true, // eye + scan line after a screenshot (the next call waits for it)
+  typeSpeed: 1, // default speed multiplier for typing waits (2 = half the waits, 0 = fixed 8 ms); env WIN_INPUT_TYPE_SPEED
+  typeMinMs: 40,
+  typeMaxMs: 120,
+  typeCapMs: 60000, // longer texts are sped up to finish within this
+  moveMinMs: 300,
+  moveMaxMs: 1000,
+  maxTypeLength: 10000,
+  auth: false, // ask for a password (src/auth.js) before the first tool call; env WIN_INPUT_AUTH
+  authFile: '', // where the password hash and unlock time live; default %APPDATA%\ispyx\auth.json
+};
+
+/**
+ * Reads a setting from the environment: ISPYX_<NAME> wins, the old WIN_INPUT_<NAME> is the fallback.
+ * (The old config variable was WIN_INPUT_MCP_CONFIG; ISPYX_CONFIG falls back to it.)
+ */
+export function env(name, source = process.env) {
+  const v = source[`ISPYX_${name}`];
+  if (v !== undefined && v !== '') return v;
+  const old = source[`WIN_INPUT_${name}`] ?? (name === 'CONFIG' ? source.WIN_INPUT_MCP_CONFIG : undefined);
+  return old === '' ? undefined : old;
+}
+
+export const userConfigPath = () => { try { return path.join(w.dataDir(), 'config.json'); } catch { return null; } };
+
+/** Writes settings changed in the panel (denylist, auth, animations) into the per-user config.json, keeping other keys. */
+export function saveUserConfig(patch) {
+  const file = userConfigPath();
+  if (!file) throw new Error('No place to save settings.');
+  let cur = {};
+  try { cur = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* new file */ }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ ...cur, ...patch }, null, 2));
+}
+
+export function loadConfig(source = process.env) {
+  const e = (name) => env(name, source);
+  let cfg = { ...DEFAULTS };
+  // The package folder is read-only on macOS and gets replaced on update everywhere, so what the panel saves lives
+  // in the per-user data folder (config.json there). On macOS it replaces the package config, elsewhere it is
+  // layered on top of it.
+  const userCfg = e('CONFIG') ? null : userConfigPath();
+  const files = e('CONFIG') ? [e('CONFIG')] : [path.join(ROOT, 'config.json'), userCfg];
+  for (const file of files) {
+    if (!file || !fs.existsSync(file) || (w.name === 'darwin' && file !== userCfg && fs.existsSync(userCfg))) continue;
+    try {
+      cfg = { ...cfg, ...JSON.parse(fs.readFileSync(file, 'utf8')) };
+    } catch (e) {
+      throw new Error(`Config file ${file} is not valid JSON: ${e.message}`);
+    }
+  }
+  if (e('DENYLIST')) cfg.denylist = e('DENYLIST').split(',');
+  // test-only knob: lets a test server use its own stop chord, so tests never press Alt+Esc,
+  // which would also stop every other running server
+  if (e('STOP_CHORD')) cfg.stopChord = e('STOP_CHORD');
+  if (e('AUTH')) cfg.auth = !/^(0|false|no)$/i.test(e('AUTH'));
+  if (e('AUTH_FILE')) cfg.authFile = e('AUTH_FILE');
+  if (e('TYPE_SPEED')) cfg.typeSpeed = Number(e('TYPE_SPEED'));
+  if (e('OVERLAY')) cfg.overlay = !/^(0|false|no)$/i.test(e('OVERLAY'));
+  if (e('ANIMATIONS')) cfg.animations = !/^(0|false|no)$/i.test(e('ANIMATIONS'));
+  cfg.denylist = cfg.denylist.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
+  if (e('LOG')) cfg.logPath = e('LOG');
+  cfg.logPath = path.resolve(ROOT, cfg.logPath);
+  return cfg;
+}
+
+export const callContext = new AsyncLocalStorage(); // { epoch } of the tool call being served
+const SHUTDOWN_WINDOW_MS = 5000;
+
+export class Guard {
+  constructor(config) {
+    this.config = config;
+    this.epoch = 0; // bumped by every stop press; a call that started under an older epoch is cancelled
+    this.lastStopAt = 0;
+    this.chordSeen = false;
+    this.onShutdown = () => process.exit(0);
+    this.stopVks = parseChord(config.stopChord);
+    this.stopIsDefault = config.stopChord === 'alt+esc';
+    // the default chord is shown with the platform's own name (Alt+Esc / Option+Esc)
+    this.stopLabel = this.stopIsDefault ? (w.stopLabel ?? 'Alt+Esc') : config.stopChord.split('+').map((s) => s[0].toUpperCase() + s.slice(1)).join('+');
+    this.overlay = null;
+    this.lastWindow = 0;
+    this.shots = new Map(); // hwnd -> { scale, ox, oy } of the last window screenshot (ox/oy: crop origin in window pixels)
+    this.lastShot = null; // { rect, scale } of the last global screenshot
+    this.heldKeys = new Set();
+    this.heldButtons = new Set();
+    fs.mkdirSync(path.dirname(config.logPath), { recursive: true });
+  }
+
+  /** Poll the stop chord, as a fallback for moments when the keyboard hook is not serviced. */
+  startWatching() {
+    const t = setInterval(() => this.pollChord(), 15);
+    t.unref();
+  }
+
+  /** One physical press of the chord seen by polling (edge only, so holding the keys counts once). */
+  pollChord() {
+    const down = chordDown(this.stopVks) && !this.heldKeys.has(this.stopVks[this.stopVks.length - 1]);
+    if (down && !this.chordSeen) this.trigger(this.stopLabel);
+    this.chordSeen = down;
+  }
+
+  /**
+   * The user pressed the stop chord. First press: cancel every running or queued call (the next call works
+   * normally). A second press within SHUTDOWN_WINDOW_MS: release everything and shut this server down.
+   */
+  trigger(reason) {
+    const now = Date.now();
+    if (now - this.lastStopAt < 250) return; // hook and polling saw the same press
+    const second = this.lastStopAt && now - this.lastStopAt < SHUTDOWN_WINDOW_MS;
+    this.lastStopAt = now;
+    this.chordSeen = true;
+    this.epoch++;
+    this.releaseAll();
+    if (second) {
+      this.log({ tool: 'kill_switch', note: reason + ' twice: shutting down' });
+      this.overlay?.stop('shutting down');
+      setTimeout(() => this.onShutdown(), 1200);
+    } else {
+      this.log({ tool: 'kill_switch', note: reason + ': cancelled' });
+      this.overlay?.cancel(reason, SHUTDOWN_WINDOW_MS);
+    }
+  }
+
+  /** Throws when the user pressed the stop chord since the current call was received. */
+  checkKill() {
+    this.pollChord();
+    const ctx = callContext.getStore();
+    if (ctx && ctx.epoch !== this.epoch) {
+      throw new ToolError(`CANCELLED BY THE USER (${this.stopLabel}). The action was interrupted. Stop what you were doing and tell the user; carry on only if they ask. ` +
+        `(Pressing ${this.stopLabel} again within ${SHUTDOWN_WINDOW_MS / 1000} s shuts the server down.)`);
+    }
+  }
+
+  checkSession() {
+    if (w.isScreenLocked()) throw new ToolError('The screen is locked (or a secure prompt is showing), so no input can be sent or captured. Unlock it and try again.');
+  }
+
+  denied(win) {
+    if (!win.process) return false;
+    if (w.name !== 'darwin') return this.config.denylist.includes(win.process);
+    // macOS: app names ("1Password") match case-insensitively, also helpers like "1Password Mini"
+    const p = win.process.toLowerCase();
+    return this.config.denylist.some((d) => p === d || p.startsWith(d + ' '));
+  }
+
+  /** Release anything this server still holds down (kill switch, shutdown, errors). */
+  releaseAll() {
+    try {
+      if (this.heldKeys.size) w.keysUp([...this.heldKeys]);
+      for (const b of this.heldButtons) w.mouseUp(b);
+    } catch { /* nothing more to do */ }
+    this.heldKeys.clear();
+    this.heldButtons.clear();
+  }
+
+  /** Throws a plain error unless the window may be acted on. */
+  assertUsable(win, { needVisible = true } = {}) {
+    if (!win.process) {
+      throw new ToolError(`Cannot identify the program that owns "${win.title}"${w.capabilities?.elevation === false ? '' : '; it may be elevated'}. Refused.`);
+    }
+    if (this.denied(win)) {
+      throw new ToolError(`Refused: "${win.title}" belongs to ${win.process}, which is on the denylist.`);
+    }
+    if (w.capabilities?.elevation !== false && win.elevated && !w.selfIsElevated()) {
+      throw new ToolError(`"${win.title}" is running as administrator, and Windows blocks input from a normal program to an elevated window. Run it without elevation, or start this server elevated.`);
+    }
+    if (needVisible && win.minimized) {
+      throw new ToolError(`"${win.title}" is minimized. Use focus_window first.`);
+    }
+  }
+
+  /** Resolve {hwnd,title} (or the last used window) to a described window. */
+  resolve({ hwnd, title } = {}) {
+    if (hwnd) {
+      if (!w.windowExists(hwnd)) throw new ToolError(`Window ${hwnd} no longer exists.`);
+      return w.describeWindow(hwnd);
+    }
+    if (title) {
+      const q = title.toLowerCase();
+      const hits = w.listWindows().filter((x) => x.title.toLowerCase().includes(q));
+      if (!hits.length) throw new ToolError(`No visible window title contains "${title}". Call list_windows to see what is open.`);
+      return hits.find((x) => !this.denied(x)) || hits[0];
+    }
+    if (this.lastWindow && w.windowExists(this.lastWindow)) return w.describeWindow(this.lastWindow);
+    const fg = w.foregroundWindow();
+    if (fg) return w.describeWindow(fg);
+    throw new ToolError('No window given. Pass hwnd or title, or use list_windows first.');
+  }
+
+  /** Window-relative screenshot pixels -> absolute screen pixels, with safety checks. */
+  toScreen(win, x, y, { scale } = {}) {
+    const rect = w.getRect(win.hwnd);
+    if (!rect) throw new ToolError(`Cannot read the position of "${win.title}".`);
+    const shot = this.shots.get(win.hwnd) || { scale: 1, ox: 0, oy: 0 };
+    const s = scale || shot.scale;
+    const sx = Math.round(rect.left + shot.ox + x / s);
+    const sy = Math.round(rect.top + shot.oy + y / s);
+    if (sx < rect.left || sy < rect.top || sx >= rect.left + rect.width || sy >= rect.top + rect.height) {
+      throw new ToolError(`Point (${x}, ${y}) is outside "${win.title}" (window is ${Math.round(rect.width)}x${Math.round(rect.height)} px).`);
+    }
+    return { sx, sy, rect, scale: s };
+  }
+
+  /** Absolute / last-screenshot coordinates -> virtual-desktop pixels, with safety checks. */
+  toScreenGlobal(x, y, space) {
+    let sx = x;
+    let sy = y;
+    if (space === 'shot') {
+      if (!this.lastShot) throw new ToolError('No screenshot_screen taken yet, so there is nothing to map "shot" coordinates from.');
+      sx = this.lastShot.rect.left + x / this.lastShot.scale;
+      sy = this.lastShot.rect.top + y / this.lastShot.scale;
+    }
+    sx = Math.round(sx);
+    sy = Math.round(sy);
+    const v = w.virtualScreen();
+    if (sx < v.x || sy < v.y || sx >= v.x + v.width || sy >= v.y + v.height) {
+      throw new ToolError(`Point (${sx}, ${sy}) is outside the desktop (${v.x},${v.y} to ${v.x + v.width - 1},${v.y + v.height - 1}).`);
+    }
+    return { sx, sy };
+  }
+
+  /** Whatever window sits under a screen point must be usable (denylist, elevation). */
+  assertPointUsable(sx, sy) {
+    const top = w.rootWindowAt(sx, sy);
+    if (!top) return null;
+    const o = w.describeWindow(top);
+    this.assertUsable(o, { needVisible: false });
+    return o;
+  }
+
+  /** The point must really belong to the target window, not to something covering it. */
+  assertPointOwned(win, sx, sy) {
+    const top = w.rootWindowAt(sx, sy);
+    if (top !== win.hwnd) {
+      const o = top ? w.describeWindow(top) : null;
+      throw new ToolError(`At that point another window is in front ("${o ? o.title : 'unknown'}"). Focus "${win.title}" or move the covering window first.`);
+    }
+  }
+
+  async focus(win) {
+    if (this.denied(win)) this.assertUsable(win, { needVisible: false });
+    const ok = await w.bringToForeground(win.hwnd);
+    if (!ok) {
+      throw new ToolError(`${w.name === 'darwin' ? 'macOS' : 'Windows'} refused to bring "${win.title}" to the front${w.name === 'darwin' ? '' : ' (foreground lock)'}. Click the window yourself once, then retry.`);
+    }
+    this.lastWindow = win.hwnd;
+  }
+
+  /** Make `win` the foreground window and verify the denylist against what is really in front. */
+  async prepareKeyboard(win) {
+    await this.focus(win);
+    const fg = w.describeWindow(w.foregroundWindow());
+    this.assertUsable(fg);
+  }
+
+  log(entry) {
+    try {
+      fs.appendFileSync(this.config.logPath, JSON.stringify({ time: new Date().toISOString(), ...entry }) + '\n');
+    } catch (e) {
+      process.stderr.write(`ispyx: could not write action log: ${e.message}\n`);
+    }
+  }
+}
+
+export const winSummary = (x) => (x ? { hwnd: x.hwnd, title: x.title, process: x.process } : null);

package/src/core/image.js

@@ -0,0 +1,117 @@
+// BGRA pixel buffers -> downscaled PNG. No dependencies beyond node:zlib.
+import zlib from 'node:zlib';
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+export function encodePng(rgba, width, height) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0; // filter: none
+    rgba.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // RGBA
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** Area-average downscale of a top-down BGRA buffer to outW x outH, returned as opaque RGBA. */
+export function toRgbaScaled(bgra, w, h, outW, outH) {
+  const out = Buffer.alloc(outW * outH * 4);
+  const xr = w / outW;
+  const yr = h / outH;
+  for (let oy = 0; oy < outH; oy++) {
+    const y0 = Math.floor(oy * yr);
+    const y1 = Math.max(y0 + 1, Math.min(h, Math.floor((oy + 1) * yr)));
+    for (let ox = 0; ox < outW; ox++) {
+      const x0 = Math.floor(ox * xr);
+      const x1 = Math.max(x0 + 1, Math.min(w, Math.floor((ox + 1) * xr)));
+      let r = 0, g = 0, b = 0, n = 0;
+      for (let y = y0; y < y1; y++) {
+        let i = (y * w + x0) * 4;
+        for (let x = x0; x < x1; x++, i += 4) {
+          b += bgra[i]; g += bgra[i + 1]; r += bgra[i + 2]; n++;
+        }
+      }
+      const o = (oy * outW + ox) * 4;
+      out[o] = Math.round(r / n);
+      out[o + 1] = Math.round(g / n);
+      out[o + 2] = Math.round(b / n);
+      out[o + 3] = 255;
+    }
+  }
+  return out;
+}
+
+/** Crop a capture to region {x,y,width,height} (window pixels), clamped to its bounds. Returns null if nothing is left. */
+export function cropCapture(cap, region) {
+  const x0 = Math.max(0, Math.round(region.x));
+  const y0 = Math.max(0, Math.round(region.y));
+  const x1 = Math.min(cap.width, Math.round(region.x + region.width));
+  const y1 = Math.min(cap.height, Math.round(region.y + region.height));
+  if (x1 <= x0 || y1 <= y0) return null;
+  const w = x1 - x0;
+  const h = y1 - y0;
+  const bits = Buffer.alloc(w * h * 4);
+  // subarray + set: cap.bits may be a plain Uint8Array (macOS), which has no Buffer.copy.
+  for (let y = 0; y < h; y++) bits.set(cap.bits.subarray(((y0 + y) * cap.width + x0) * 4, ((y0 + y) * cap.width + x1) * 4), y * w * 4);
+  return { ...cap, bits, width: w, height: h, region: { x: x0, y: y0, width: w, height: h } };
+}
+
+/** Capture result -> { png, width, height, scale } where scale = output pixels per screen pixel. */
+export function shrinkToPng(cap, maxWidth) {
+  const outW = Math.max(1, Math.min(cap.width, Math.floor(maxWidth)));
+  const scale = outW / cap.width;
+  const outH = Math.max(1, Math.round(cap.height * scale));
+  const rgba = toRgbaScaled(cap.bits, cap.width, cap.height, outW, outH);
+  return { png: encodePng(rgba, outW, outH), width: outW, height: outH, scale, rgba };
+}
+
+/** Minimal decoder for PNGs written by encodePng (filter 0, RGBA 8-bit). Used by tests. */
+export function decodePng(png) {
+  let p = 8, w = 0, h = 0;
+  const idat = [];
+  while (p < png.length) {
+    const len = png.readUInt32BE(p);
+    const type = png.toString('ascii', p + 4, p + 8);
+    const data = png.subarray(p + 8, p + 8 + len);
+    if (type === 'IHDR') { w = data.readUInt32BE(0); h = data.readUInt32BE(4); }
+    if (type === 'IDAT') idat.push(data);
+    p += 12 + len;
+  }
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const rgba = Buffer.alloc(w * h * 4);
+  for (let y = 0; y < h; y++) raw.copy(rgba, y * w * 4, y * (w * 4 + 1) + 1, (y + 1) * (w * 4 + 1));
+  return { width: w, height: h, rgba };
+}

package/src/core/ipc.js

@@ -0,0 +1,139 @@
+// One working server per desktop: the first ispyx process listens on a named pipe and does the work;
+// every other process (one per Claude instance) stays a normal MCP server toward its own Claude and forwards
+// the tool calls over the pipe. Protocol: one JSON line each way per call.
+import net from 'node:net';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Same user + same ISPYX_* (or legacy WIN_INPUT_*) settings = same endpoint, so test servers with their own env never meet the live one.
+ * Windows: a named pipe. Elsewhere: a unix socket in the temp directory (per user on macOS), mode 0600.
+ * ISPYX_PIPE names the endpoint outright (Ispyx.app: its resident and the MCP clients' forwarders start in different
+ * environments, so a temp-directory path could differ between them).
+ */
+export function pipeName() {
+  if (process.env.ISPYX_PIPE) return process.env.ISPYX_PIPE;
+  const env = Object.entries(process.env).filter(([k]) => k.startsWith('ISPYX_') || k.startsWith('WIN_INPUT_')).sort().map(([k, v]) => `${k}=${v}`).join('\n');
+  const user = os.userInfo().username.replace(/[^\w.-]/g, '_');
+  const id = `ispyx-${user}-${crypto.createHash('sha1').update(env).digest('hex').slice(0, 8)}`;
+  if (process.platform === 'win32') return `\\\\.\\pipe\\${id}`;
+  return path.join(os.tmpdir(), `${id}.sock`); // keep short: unix socket paths are limited to ~104 bytes on macOS
+}
+
+const isPipe = (name) => name.startsWith('\\\\.\\pipe\\');
+
+/** True when something accepts connections at the unix socket path. */
+function answers(name) {
+  return new Promise((resolve) => {
+    const s = net.connect(name);
+    s.once('connect', () => { s.destroy(); resolve(true); });
+    s.once('error', () => { s.destroy(); resolve(false); });
+  });
+}
+
+/** Reads newline-delimited JSON from a stream. */
+function lines(stream, onLine) {
+  let buf = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (d) => {
+    buf += d;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const l = buf.slice(0, i);
+      buf = buf.slice(i + 1);
+      if (l) onLine(l);
+    }
+  });
+}
+
+/**
+ * Tries to become the owner. Resolves with { close, clients() } when this process now listens,
+ * or null when another process already owns the pipe.
+ */
+export function listenOwner(name, run) {
+  return new Promise((resolve, reject) => {
+    let clients = 0;
+    const watchers = new Set(); // other servers waiting for a shutdown order
+    const socks = new Set();
+    const srv = net.createServer((sock) => {
+      clients++;
+      socks.add(sock);
+      sock.on('close', () => { clients--; watchers.delete(sock); socks.delete(sock); });
+      sock.on('error', () => {});
+      lines(sock, async (l) => {
+        let req;
+        try { req = JSON.parse(l); } catch { return; }
+        if (req.watch) { watchers.add(sock); return; }
+        let reply;
+        try { reply = { id: req.id, result: await run(req.name, req.args ?? {}) }; }
+        catch (e) { reply = { id: req.id, error: e.message }; }
+        if (!sock.destroyed) sock.write(JSON.stringify(reply) + '\n');
+      });
+    });
+    let retried = false;
+    srv.on('error', async (e) => {
+      if (e.code !== 'EADDRINUSE') return reject(e);
+      // a unix socket file outlives a crashed owner: when nobody answers, remove it and try once more
+      if (!isPipe(name) && !retried && !(await answers(name))) {
+        retried = true;
+        try { fs.unlinkSync(name); } catch { /* already gone */ }
+        return srv.listen(name);
+      }
+      resolve(null);
+    });
+    srv.on('listening', () => {
+      if (!isPipe(name)) { try { fs.chmodSync(name, 0o600); } catch { /* best effort */ } }
+      resolve({
+        close: () => { srv.close(); for (const s of socks) s.destroy(); },
+        clients: () => clients,
+        /** Servers holding a watch connection (resident model: one per connected `ispyx mcp`). */
+        watchers: () => watchers.size,
+        /** Tells every other server on this pipe to exit. */
+        broadcastShutdown: () => { for (const s of watchers) { try { s.write(JSON.stringify({ shutdown: true }) + '\n'); } catch { /* gone */ } } },
+      });
+    });
+    srv.listen(name);
+  });
+}
+
+/**
+ * Keeps a connection to the owner open so it can order this server to exit (the owner's second stop press).
+ * Reconnects when the owner changes. Stops retrying once onShutdown ran or isOwner() is true.
+ */
+export function watchOwner(name, onShutdown, isOwner) {
+  const attempt = () => {
+    if (isOwner()) return;
+    const sock = net.connect(name);
+    sock.on('connect', () => sock.write(JSON.stringify({ watch: true }) + '\n'));
+    sock.on('error', () => {});
+    sock.on('close', () => { const t = setTimeout(attempt, 1000); t.unref(); });
+    lines(sock, (l) => { try { if (JSON.parse(l).shutdown) onShutdown(); } catch { /* ignore */ } });
+    sock.unref();
+  };
+  attempt();
+}
+
+export class OwnerGone extends Error {}
+
+/** Forwards one call to the owner. Throws OwnerGone when nobody listens (so the caller can take over). */
+export function callOwner(name, tool, args) {
+  return new Promise((resolve, reject) => {
+    const sock = net.connect(name);
+    let connected = false;
+    let done = false;
+    const finish = (fn, v) => { if (!done) { done = true; sock.destroy(); fn(v); } };
+    sock.on('connect', () => {
+      connected = true;
+      sock.write(JSON.stringify({ id: 1, name: tool, args }) + '\n');
+    });
+    sock.on('error', (e) => finish(reject, connected ? new Error(`The ispyx server that was doing the work went away (${e.code ?? e.message}). Try the call again.`) : new OwnerGone(e.code)));
+    sock.on('close', () => finish(reject, connected ? new Error('The ispyx server that was doing the work went away. Try the call again.') : new OwnerGone('closed')));
+    lines(sock, (l) => {
+      const r = JSON.parse(l);
+      if (r.error !== undefined) finish(reject, new Error(r.error));
+      else finish(resolve, r.result);
+    });
+  });
+}

package/src/core/launcher.js

@@ -0,0 +1,70 @@
+// Starting and reaching the resident app (resident model). No platform import: usable before anything is loaded.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { callOwner, OwnerGone, pipeName } from './ipc.js';
+
+const ENTRY = fileURLToPath(new URL('../server.js', import.meta.url));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Inside Ispyx.app (macOS) the app starts and watches the resident: the bundle path, else null. */
+function macApp() {
+  if (process.platform !== 'darwin') return null;
+  const m = /^(.*?\.app)\/Contents\/Resources\//.exec(ENTRY);
+  return m ? m[1] : null;
+}
+
+/** Starts `ispyx --resident` detached and hidden, with this process's environment (same pipe). Inside Ispyx.app it
+ * opens the app instead, which starts the resident itself. */
+export function spawnResident() {
+  const app = macApp();
+  const child = app
+    ? spawn('open', ['-g', app, '--args', '--background'], { stdio: 'ignore', detached: true })
+    : spawn(process.execPath, [ENTRY, '--resident'], { detached: true, windowsHide: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+}
+
+/** True when a resident answers on the pipe. */
+export async function residentRunning(pipe = pipeName()) {
+  try { await callOwner(pipe, '__ping', {}); return true; } catch (e) { if (e instanceof OwnerGone) return false; return true; }
+}
+
+/** Makes sure a resident listens, starting one if needed; waits up to timeoutMs. Resolves true when it answers. */
+export async function ensureResident(pipe = pipeName(), timeoutMs = 10000) {
+  if (await residentRunning(pipe)) return true;
+  spawnResident();
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    await sleep(150);
+    if (await residentRunning(pipe)) return true;
+  }
+  return false;
+}
+
+/** Opens a URL in the default browser (Windows). */
+export function openUrl(url) {
+  const c = spawn('cmd.exe', ['/c', 'start', '', url], { windowsHide: true, stdio: 'ignore', detached: true });
+  c.on('error', () => {});
+  c.unref();
+}
+
+/** `ispyx` with a console: start the resident if none runs, open its panel, leave. */
+export async function runLauncher() {
+  const pipe = pipeName();
+  const wasRunning = await residentRunning(pipe);
+  if (!(await ensureResident(pipe))) {
+    process.stderr.write('ispyx: could not start the resident app (see %APPDATA%\\ispyx\\ispyx.log).\n');
+    process.exit(1);
+  }
+  // Starting it (login, first click) just puts the icon in the tray; clicking the shortcut again opens the panel.
+  if (wasRunning) {
+    try { await callOwner(pipe, '__panel', {}); } catch { /* no panel: the tray icon is enough */ }
+  }
+  process.exit(0);
+}
+
+/** `ispyx quit`: asks the resident to exit; exits 0 either way. */
+export async function runQuit() {
+  try { await callOwner(pipeName(), '__quit', {}); } catch { /* not running, or gone before answering */ }
+  process.exit(0);
+}

package/src/core/mode.js

@@ -0,0 +1,17 @@
+// Which role this process plays. Pure (no platform import), so the entry point can decide before loading anything.
+//   classic   npx on macOS / Linux / fake: every process is an MCP server, one of them owns the pipe
+//             (Ispyx.app passes --resident / mcp explicitly)
+//   launcher  Windows, no args, console attached: start the resident app if needed, then exit
+//   resident  `--resident`: the single owner of the pipe (tray, panel, tool queue); no stdio
+//   mcp       `mcp`: thin stdio MCP server forwarding every call to the resident
+//   quit      `quit`: ask the resident to exit
+// Explicit arguments work on any platform (tests use them with the fake platform). Without arguments only
+// Windows changes: a console means launcher, a pipe on stdin (an old MCP registration) means mcp.
+export function resolveMode(argv = process.argv.slice(2), env = process.env, platform = process.platform, isTTY = !!process.stdin.isTTY) {
+  if (argv.includes('--resident')) return 'resident';
+  if (argv.includes('mcp')) return 'mcp';
+  if (argv.includes('quit') || argv.includes('--quit')) return 'quit';
+  const target = env.ISPYX_PLATFORM || platform;
+  if (target === 'win32') return isTTY ? 'launcher' : 'mcp';
+  return 'classic';
+}