tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/lib/update-check.ts

@@ -0,0 +1,298 @@
+/**
+ * The built-in update check — "you're on an old tmux-ide" surfaced where
+ * everyone already looks: the dock.
+ *
+ * Once a day the chrome updater asks npm for the latest published version, caches
+ * the answer in `~/.tmux-ide/update-check.json` (overridable via `TMUX_IDE_HOME`,
+ * consistent with {@link ../tui/chrome/welcome.ts}), and — when the cached latest
+ * is newer than what's running — every surface reads that ONE cache to decide
+ * whether to nudge: the dock's `⬆ v<latest>` segment, a one-time toast per
+ * version, `tmux-ide doctor`, the actions menu, and the `tmux-ide` start hint.
+ *
+ * The split, as elsewhere: {@link compareSemver} / {@link isNewer} /
+ * {@link shouldCheck} / {@link parseRegistryResponse} are PURE (unit-tested, never
+ * throw); {@link fetchLatestVersion}, the cache read/write, and the throttled
+ * {@link runUpdateCheck} are the thin — and strictly OFFLINE-SAFE — io wrappers.
+ * Nothing here ever throws into the updater loop: a failed fetch, an unreadable
+ * cache, or a garbage registry body all degrade to "no update known".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The npm dist-tag endpoint that returns `{ "version": "x.y.z", … }`. */
+export const REGISTRY_URL = "https://registry.npmjs.org/tmux-ide/latest";
+
+/** Re-check no more than once per this window (24h). */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** The cheap, cache-derived answer every surface reads. */
+export interface UpdateStatus {
+  /** The latest published version the last check saw, or null when unknown. */
+  latest: string | null;
+  /** True when {@link latest} is strictly newer than the running version. */
+  updateAvailable: boolean;
+}
+
+/** The on-disk cache shape (`~/.tmux-ide/update-check.json`). */
+export interface UpdateCache {
+  /** Epoch ms of the last network check (throttles {@link shouldCheck}). */
+  lastCheckedAt: number | null;
+  /** The latest version that check saw, or null. */
+  latest: string | null;
+  /** Versions we've already toasted about (one-time-per-version debounce). */
+  notified?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+interface ParsedSemver {
+  nums: [number, number, number];
+  /** The prerelease tag (`1.0.0-rc.1` → `rc.1`), or "" for a release. */
+  pre: string;
+}
+
+/**
+ * PURE — split `[v]MAJOR.MINOR.PATCH[-prerelease][+build]` into its numeric core
+ * and prerelease tag. Lenient: a leading `v`, build metadata (`+…`), and missing
+ * or non-numeric core parts are all tolerated (coerced to 0), so a malformed
+ * version compares as `0.0.0` instead of throwing.
+ */
+function parseSemver(version: string): ParsedSemver {
+  const core = version.trim().replace(/^v/i, "").split("+")[0] ?? "";
+  const dash = core.indexOf("-");
+  const main = dash === -1 ? core : core.slice(0, dash);
+  const pre = dash === -1 ? "" : core.slice(dash + 1);
+  const parts = main.split(".");
+  const num = (i: number): number => {
+    const n = Number.parseInt(parts[i] ?? "", 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+  };
+  return { nums: [num(0), num(1), num(2)], pre };
+}
+
+/**
+ * PURE — order two semver strings: `-1` if `a < b`, `1` if `a > b`, else `0`.
+ *
+ * Numeric core (major, minor, patch) compares field-by-field, so `2.10.0` sorts
+ * ABOVE `2.6.0` (numeric, not lexical). Prerelease follows semver's rule: a
+ * release outranks a prerelease of the same core (`1.0.0` > `1.0.0-rc`); two
+ * prereleases fall back to a plain lexical compare of their tags (a simple, good-
+ * enough ordering — we never need to rank `rc.2` vs `rc.10` precisely).
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i]! !== pb.nums[i]!) return pa.nums[i]! < pb.nums[i]! ? -1 : 1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === "") return 1; // release > prerelease of same core
+  if (pb.pre === "") return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+}
+
+/** PURE — is `latest` strictly newer than `current`? */
+export function isNewer(latest: string, current: string): boolean {
+  return compareSemver(latest, current) === 1;
+}
+
+/**
+ * PURE — should we hit the network again? True when we've never checked
+ * (`lastCheckedAt` null) or the last check was at least {@link CHECK_INTERVAL_MS}
+ * ago. A future `lastCheckedAt` (clock skew) reads as "recent" and skips — the
+ * daily tick self-heals once the clock passes it.
+ */
+export function shouldCheck(lastCheckedAt: number | null, nowMs: number): boolean {
+  if (lastCheckedAt === null) return true;
+  return nowMs - lastCheckedAt >= CHECK_INTERVAL_MS;
+}
+
+/**
+ * PURE — pull the `version` string out of a raw npm dist-tag response body.
+ * Returns null (never throws) for malformed JSON, a non-object, or a
+ * missing/empty/non-string `version`.
+ */
+export function parseRegistryResponse(json: string): string | null {
+  try {
+    const parsed = JSON.parse(json) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const version = (parsed as { version?: unknown }).version;
+    return typeof version === "string" && version.length > 0 ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * PURE — derive the {@link UpdateStatus} for a running version from a (possibly
+ * null) cached latest. The single place "is there an update?" is decided, so
+ * every surface agrees.
+ */
+export function deriveStatus(latest: string | null, currentVersion: string): UpdateStatus {
+  return {
+    latest,
+    updateAvailable: latest !== null && isNewer(latest, currentVersion),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// io — cache + network (all offline-safe, never throw)
+// ---------------------------------------------------------------------------
+
+/**
+ * Absolute path to the cache file: `<home>/update-check.json`, where `<home>` is
+ * `TMUX_IDE_HOME` when set (tests / per-run overrides), else `~/.tmux-ide` — the
+ * same home resolution the welcome marker uses.
+ */
+export function updateCachePath(): string {
+  const home = process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+  return join(home, "update-check.json");
+}
+
+/** io — read + parse the cache, or null when absent/unreadable/malformed. */
+export function readUpdateCache(): UpdateCache | null {
+  const path = updateCachePath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const obj = parsed as Record<string, unknown>;
+    const lastCheckedAt = typeof obj.lastCheckedAt === "number" ? obj.lastCheckedAt : null;
+    const latest = typeof obj.latest === "string" && obj.latest.length > 0 ? obj.latest : null;
+    const notified = Array.isArray(obj.notified)
+      ? obj.notified.filter((v): v is string => typeof v === "string")
+      : undefined;
+    return { lastCheckedAt, latest, ...(notified ? { notified } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+/** io — write the cache (creating `<home>` if needed). Best-effort, never throws. */
+export function writeUpdateCache(cache: UpdateCache): void {
+  const path = updateCachePath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cache));
+  } catch {
+    // an unwritable cache just means we re-check next tick — never fatal
+  }
+}
+
+/**
+ * io — ask npm for the latest published version, or null on ANY failure (offline,
+ * timeout, non-200, garbage body). Aborts after `timeoutMs` so a slow registry
+ * can never stall the updater tick. This is the ONLY network call in the module.
+ */
+export async function fetchLatestVersion(timeoutMs = 3000): Promise<string | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    return parseRegistryResponse(await res.text());
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The running tmux-ide version, read from the nearest `package.json`. Handles
+ * BOTH the bundled CLI (`bin/cli.js`, so the repo-root package.json is one level
+ * up) AND the dev source tree (this file at `packages/daemon/src/lib/`, so the
+ * root is four levels up). The workspace `packages/daemon/package.json` is
+ * deliberately NOT a candidate — it carries a placeholder version. Falls back to
+ * `"0.0.0"` when nothing is readable (so an unknown version simply never shows an
+ * update rather than crashing).
+ */
+export function getCurrentVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "../package.json"), // bundled bin/cli.js → repo root
+    join(here, "../../../../package.json"), // dev src/lib → repo root
+  ];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, "utf-8")) as { version?: unknown };
+      if (typeof parsed.version === "string" && parsed.version.length > 0) return parsed.version;
+    } catch {
+      // try the next candidate
+    }
+  }
+  return "0.0.0";
+}
+
+/**
+ * The cheap, network-FREE status read every surface uses: derive
+ * {@link UpdateStatus} from the cache against the current version. `now`/
+ * `currentVersion` are injectable for tests; the defaults read the live clock +
+ * package version.
+ */
+export function getUpdateStatus({
+  currentVersion = getCurrentVersion(),
+}: { now?: number; currentVersion?: string } = {}): UpdateStatus {
+  const cache = readUpdateCache();
+  return deriveStatus(cache?.latest ?? null, currentVersion);
+}
+
+/**
+ * io — the throttled network refresh (called fire-and-forget from the updater
+ * tick). Does nothing if the last check was inside {@link CHECK_INTERVAL_MS};
+ * otherwise fetches the latest version and rewrites the cache with a fresh
+ * `lastCheckedAt`. On a failed fetch it still stamps `lastCheckedAt` (so we don't
+ * hammer a flaky/offline registry every tick) while KEEPING the previously known
+ * `latest`. Never throws.
+ */
+export async function runUpdateCheck({ now = Date.now() }: { now?: number } = {}): Promise<void> {
+  const cache = readUpdateCache();
+  if (!shouldCheck(cache?.lastCheckedAt ?? null, now)) return;
+  const fetched = await fetchLatestVersion();
+  writeUpdateCache({
+    lastCheckedAt: now,
+    latest: fetched ?? cache?.latest ?? null,
+    ...(cache?.notified ? { notified: cache.notified } : {}),
+  });
+}
+
+/**
+ * The tick's entry point: return the cheap cache-derived {@link UpdateStatus} NOW,
+ * and (when `enabled`) kick off the throttled network refresh in the background so
+ * the NEXT tick sees a fresh answer. Disabled (`updates.check: false`) → always
+ * "no update", no network. The background refresh is deliberately un-awaited: the
+ * tick must never block on the registry.
+ */
+export function maybeCheckForUpdate({
+  enabled,
+  now = Date.now(),
+  currentVersion = getCurrentVersion(),
+}: {
+  enabled: boolean;
+  now?: number;
+  currentVersion?: string;
+}): UpdateStatus {
+  if (!enabled) return { latest: null, updateAvailable: false };
+  const status = getUpdateStatus({ now, currentVersion });
+  void runUpdateCheck({ now }).catch(() => {});
+  return status;
+}
+
+/**
+ * io — record that we've toasted about `version` and report whether this is the
+ * FIRST time (so the caller should actually toast). Persisted in the cache file's
+ * `notified` list so the one-time guarantee survives updater restarts — the old
+ * in-memory notify debounce would re-fire on every respawn. Best-effort: if the
+ * cache can't be written we still return the in-memory verdict.
+ */
+export function markUpdateNotified(version: string): boolean {
+  const cache = readUpdateCache() ?? { lastCheckedAt: null, latest: null };
+  const notified = cache.notified ?? [];
+  if (notified.includes(version)) return false;
+  writeUpdateCache({ ...cache, notified: [...notified, version] });
+  return true;
+}

package/packages/daemon/src/lib/update.ts

@@ -0,0 +1,158 @@
+/**
+ * `tmux-ide update [--dry-run]` — act on the update the dock surfaces.
+ *
+ * The dock's `⬆ v<latest>` chip (see {@link ./update-check.ts}) tells you an
+ * update is out; this closes the loop with the ONE command that installs it. The
+ * catch is that "the command" depends on how tmux-ide was installed — a cloned
+ * dev checkout updates with `git pull`, a global install with its package
+ * manager (npm/pnpm/bun) — so the command DETECTS the install method from the
+ * running CLI's real path before printing (or, without `--dry-run`, running) it.
+ *
+ * The detection + rendering are PURE ({@link detectPackageManager},
+ * {@link planUpdate}, {@link renderPlan}), so they're unit-tested without a live
+ * filesystem; {@link findGitCheckoutRoot} and {@link runUpdate} are the io — the
+ * latter is the only place a real global install is ever spawned, and only when
+ * `--dry-run` is absent.
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getCurrentVersion, getUpdateStatus, isNewer } from "./update-check.ts";
+
+/** The package managers a global install can come from. */
+export type PackageManager = "npm" | "pnpm" | "bun";
+
+/** The resolved way to update this install. */
+export interface UpdatePlan {
+  /** `dev` = a git checkout (`git pull`); otherwise the global package manager. */
+  method: "dev" | PackageManager;
+  /** The shell command to run, or null for a dev checkout (manual `git pull`). */
+  command: string | null;
+  /** A short human note on WHY this method was chosen (the detection evidence). */
+  reason: string;
+}
+
+/** The exact global-install command per package manager. */
+export const UPDATE_COMMANDS: Record<PackageManager, string> = {
+  npm: "npm install -g tmux-ide@latest",
+  pnpm: "pnpm add -g tmux-ide@latest",
+  bun: "bun add -g tmux-ide@latest",
+};
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — infer the package manager from a global CLI path. The global bin lives
+ * under a manager-specific directory, so the path is the tell: a `bun`/`.bun`
+ * segment → bun, a `pnpm` segment → pnpm, else npm (the default global installer,
+ * incl. nvm's `.../node/vX/lib/node_modules/...`). Checked bun→pnpm→npm so the
+ * more specific segments win.
+ */
+export function detectPackageManager(cliPath: string): PackageManager {
+  const p = cliPath.toLowerCase();
+  if (/(^|\/)\.?bun(\/|$)/.test(p)) return "bun";
+  if (p.includes("pnpm")) return "pnpm";
+  return "npm";
+}
+
+/**
+ * PURE — the {@link UpdatePlan} for a CLI at `cliPath`. When `gitRoot` is set (a
+ * `.git` was found at/above the CLI — a cloned checkout) the plan is a manual
+ * `git pull`; otherwise it's the detected package manager's global-install
+ * command.
+ */
+export function planUpdate(input: { cliPath: string; gitRoot: string | null }): UpdatePlan {
+  if (input.gitRoot) {
+    return { method: "dev", command: null, reason: `git checkout at ${input.gitRoot}` };
+  }
+  const pm = detectPackageManager(input.cliPath);
+  return {
+    method: pm,
+    command: UPDATE_COMMANDS[pm],
+    reason: `global ${pm} install (${input.cliPath})`,
+  };
+}
+
+/**
+ * PURE — the human-readable block the CLI prints for a plan. Leads with the
+ * version delta (or "up to date"/"unknown"), then the command to run — for a dev
+ * checkout that's the `git pull` hint, for a global install the exact package-
+ * manager line. `dryRun` only changes the framing ("would run" vs "run"); the
+ * command shown is identical either way. Ends with the re-adopt note: the running
+ * updater keeps the OLD code until `_tmux-ide-chrome` is killed and a session
+ * re-adopted, so a fresh dock reflects the new version.
+ */
+export function renderPlan(
+  plan: UpdatePlan,
+  { current, latest, dryRun }: { current: string; latest: string | null; dryRun: boolean },
+): string {
+  const lines: string[] = [];
+  // isNewer, not inequality — the registry can lag the checkout (a dev build
+  // is AHEAD of the published version), and that must not read as an update.
+  if (latest && isNewer(latest, current)) {
+    lines.push(`tmux-ide v${current} → v${latest} available`);
+  } else if (latest) {
+    lines.push(`tmux-ide v${current} is up to date (registry: v${latest})`);
+  } else {
+    lines.push(`tmux-ide v${current} (latest version unknown — run \`tmux-ide doctor\`)`);
+  }
+  lines.push("");
+  if (plan.method === "dev") {
+    lines.push("Detected a cloned checkout — update with git:");
+    lines.push("  git pull");
+    lines.push(`  (${plan.reason})`);
+  } else {
+    const verb = dryRun ? "Would run" : "Running";
+    lines.push(`Detected a global ${plan.method} install — ${verb}:`);
+    lines.push(`  ${plan.command}`);
+  }
+  lines.push("");
+  lines.push("After updating, refresh the dock so it runs the new code:");
+  lines.push("  tmux kill-session -t _tmux-ide-chrome   # stop the old updater");
+  lines.push("  tmux-ide adopt <session>                # re-adopt to relaunch it");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/**
+ * io — walk up from `startDir` looking for a `.git` entry; return the first
+ * directory that has one (a cloned checkout root) or null at the filesystem root.
+ * A global install under `node_modules` has no `.git` above it, so this cleanly
+ * separates "dev checkout" from "installed package".
+ */
+export function findGitCheckoutRoot(startDir: string): string | null {
+  let dir = startDir;
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * io — run (or, with `dryRun`, just print) the update.
+ *
+ * `cliDir` is the directory of the running CLI (`bin/`), the anchor for both the
+ * git-checkout probe and the package-manager path heuristic. The plan is printed
+ * either way; only a non-dry-run global install actually spawns the installer
+ * (`execSync`, output inherited). A dev checkout NEVER auto-runs `git pull` — it
+ * only prints the hint. Returns the plan so the CLI/tests can assert on it.
+ */
+export function runUpdate({ cliDir, dryRun }: { cliDir: string; dryRun: boolean }): UpdatePlan {
+  const current = getCurrentVersion();
+  const { latest } = getUpdateStatus({ currentVersion: current });
+  const gitRoot = findGitCheckoutRoot(cliDir);
+  const plan = planUpdate({ cliPath: cliDir, gitRoot });
+  console.log(renderPlan(plan, { current, latest, dryRun }));
+  if (!dryRun && plan.command) {
+    console.log("");
+    execSync(plan.command, { stdio: "inherit" });
+  }
+  return plan;
+}

package/packages/daemon/src/lib/workspace-registry.ts

@@ -0,0 +1,229 @@
+/**
+ * Workspace registry — runtime list of projects the daemon is serving.
+ *
+ * Replaces the legacy single-session TMUX_IDE_SESSION env coupling so a
+ * single daemon can host N concurrent projects (goal 12, T065).
+ *
+ * Persisted at ~/.tmux-ide/workspaces.json via atomic temp+rename. On
+ * `load()` the registry reconciles itself against `tmux list-sessions`
+ * output and drops entries whose session no longer exists.
+ *
+ * Distinct from project-registry.ts — that one is a long-lived
+ * "bookmark list" of projects the user knows about (probed metadata).
+ * This one tracks live workspaces and is reconciled with tmux on boot.
+ */
+
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { WorkspaceSchemaZ, type Workspace } from "@tmux-ide/contracts";
+
+const REGISTRY_DIR_ENV = "TMUX_IDE_REGISTRY_DIR";
+
+const RegistryFileSchemaZ = z.object({
+  version: z.literal(1),
+  workspaces: z.array(WorkspaceSchemaZ),
+});
+
+type RegistryFile = z.infer<typeof RegistryFileSchemaZ>;
+
+export type ListSessionsFn = () => readonly string[];
+
+export interface WorkspaceRegistryOptions {
+  /** Override registry dir for tests. Defaults to ~/.tmux-ide. */
+  dir?: string;
+  /** Inject a tmux list-sessions implementation (defaults to bridge). */
+  listSessions?: ListSessionsFn;
+}
+
+export interface AddWorkspaceInput {
+  name: string;
+  sessionName?: string;
+  projectDir: string;
+  ideConfigPath?: string | null;
+  /** Override Date.now() for deterministic tests. */
+  now?: () => Date;
+}
+
+export class WorkspaceAlreadyExistsError extends Error {
+  readonly code = "ALREADY_EXISTS";
+  constructor(name: string) {
+    super(`Workspace "${name}" already exists`);
+    this.name = "WorkspaceAlreadyExistsError";
+  }
+}
+
+export class WorkspaceNotFoundError extends Error {
+  readonly code = "NOT_FOUND";
+  constructor(name: string) {
+    super(`Workspace "${name}" not found`);
+    this.name = "WorkspaceNotFoundError";
+  }
+}
+
+/**
+ * Thin wrapper around the shared module emitter so consumers can subscribe
+ * with typed events without depending on EventEmitter directly.
+ */
+export type WorkspaceEvent =
+  | { type: "workspace.added"; workspace: Workspace }
+  | { type: "workspace.removed"; name: string };
+
+export class WorkspaceRegistry {
+  private readonly dir: string;
+  private readonly listSessions: ListSessionsFn;
+  private readonly emitter = new EventEmitter();
+  private workspaces: Workspace[] = [];
+  private loaded = false;
+
+  constructor(options: WorkspaceRegistryOptions = {}) {
+    this.dir = options.dir ?? process.env[REGISTRY_DIR_ENV] ?? join(homedir(), ".tmux-ide");
+    this.listSessions = options.listSessions ?? defaultListSessions;
+    this.emitter.setMaxListeners(0);
+  }
+
+  /**
+   * Load workspaces from disk and reconcile against live tmux sessions.
+   * Drops entries whose tmux session is gone (silently — they were
+   * persisted by a prior daemon invocation that may have crashed).
+   *
+   * Safe to call repeatedly; subsequent calls re-reconcile.
+   */
+  async load(): Promise<void> {
+    const fromDisk = this.readDisk();
+    let live: Set<string>;
+    try {
+      live = new Set(this.listSessions());
+    } catch {
+      // tmux is unavailable — keep all entries; reconcile when we can.
+      live = new Set(fromDisk.map((w) => w.sessionName));
+    }
+    const reconciled = fromDisk.filter((w) => live.has(w.sessionName));
+    this.workspaces = reconciled;
+    this.loaded = true;
+    if (reconciled.length !== fromDisk.length) {
+      this.writeDisk();
+    }
+  }
+
+  list(): Workspace[] {
+    return [...this.workspaces];
+  }
+
+  get(name: string): Workspace | null {
+    return this.workspaces.find((w) => w.name === name) ?? null;
+  }
+
+  has(name: string): boolean {
+    return this.workspaces.some((w) => w.name === name);
+  }
+
+  add(input: AddWorkspaceInput): Workspace {
+    if (this.has(input.name)) {
+      throw new WorkspaceAlreadyExistsError(input.name);
+    }
+    const now = (input.now ?? (() => new Date()))();
+    const workspace: Workspace = {
+      name: input.name,
+      sessionName: input.sessionName ?? input.name,
+      projectDir: input.projectDir,
+      ideConfigPath: input.ideConfigPath ?? null,
+      addedAt: now.toISOString(),
+    };
+    this.workspaces = [...this.workspaces, workspace];
+    this.writeDisk();
+    this.emitter.emit("workspace.added", workspace);
+    return workspace;
+  }
+
+  remove(name: string): void {
+    if (!this.has(name)) {
+      throw new WorkspaceNotFoundError(name);
+    }
+    this.workspaces = this.workspaces.filter((w) => w.name !== name);
+    this.writeDisk();
+    this.emitter.emit("workspace.removed", name);
+  }
+
+  /** Subscribe to workspace.added | workspace.removed events. */
+  on<E extends WorkspaceEvent["type"]>(
+    event: E,
+    handler: (
+      payload: Extract<WorkspaceEvent, { type: E }> extends { workspace: Workspace }
+        ? Workspace
+        : string,
+    ) => void,
+  ): () => void {
+    this.emitter.on(event, handler as (...args: unknown[]) => void);
+    return () => this.emitter.off(event, handler as (...args: unknown[]) => void);
+  }
+
+  // ----------------- io -----------------
+
+  private filePath(): string {
+    return join(this.dir, "workspaces.json");
+  }
+
+  private readDisk(): Workspace[] {
+    const path = this.filePath();
+    if (!existsSync(path)) return [];
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf-8"));
+    } catch {
+      return [];
+    }
+    const result = RegistryFileSchemaZ.safeParse(parsed);
+    if (!result.success) return [];
+    return result.data.workspaces;
+  }
+
+  private writeDisk(): void {
+    const path = this.filePath();
+    mkdirSync(dirname(path), { recursive: true });
+    const file: RegistryFile = { version: 1, workspaces: this.workspaces };
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n");
+    renameSync(tmp, path);
+  }
+
+  /** @internal Test-only: assert the registry is loaded. */
+  _isLoaded(): boolean {
+    return this.loaded;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default singleton — the daemon process holds one registry; HTTP handlers
+// import it via getDefaultWorkspaceRegistry().
+// ---------------------------------------------------------------------------
+
+let _default: WorkspaceRegistry | null = null;
+
+export function getDefaultWorkspaceRegistry(): WorkspaceRegistry {
+  if (!_default) _default = new WorkspaceRegistry();
+  return _default;
+}
+
+/** @internal Test hook: replace the singleton. */
+export function _setDefaultWorkspaceRegistryForTests(registry: WorkspaceRegistry | null): void {
+  _default = registry;
+}
+
+function defaultListSessions(): string[] {
+  // Lazy import keeps tmux-bridge optional for test environments that
+  // don't have tmux available; tests inject a stub instead.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
+  try {
+    const raw = execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }) as string;
+    return raw.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}