@gethmy/mcp 3.3.0 → 3.4.0

package/src/run-state.ts

@@ -0,0 +1,679 @@
+/**
+ * Publishing an MCP session so a hook outside the process can find it (#874).
+ *
+ * ## The problem this solves
+ *
+ * A daemon run streams its whole tool log to `agent_run_events`, so its
+ * timeline reads turn by turn. An MCP session — `/hmy` in a terminal, Cursor,
+ * Claude Desktop — writes only what its own MCP calls carry, so a two-hour run
+ * that pinged progress three times renders three rows. The tool calls the agent
+ * actually made (Read, Edit, Bash, Grep) never reach the MCP server at all;
+ * they belong to the harness, which exposes them as `PostToolUse` hooks.
+ *
+ * A hook is a separate, short-lived process. It has no handle on the MCP
+ * server's memory, so the session identity has to travel **through the
+ * filesystem**. That is what this module is.
+ *
+ * ## Why not `~/.harmony-mcp/`
+ *
+ * `getConfigDir()` is the FIRST entry of `credentialDirectories()`
+ * (`packages/harmony-harness/src/run-containment.ts`) and is read-denied to
+ * every contained spawn, because it holds the API key. Publishing a session
+ * pointer into it would put a file that is meant to be READ into the one
+ * directory the containment design just finished fencing off — and would make
+ * the fence look negotiable to the next reader.
+ *
+ * So the pointer lives under `~/.harmony/`, which already hosts the memory
+ * vault (`getMemoryDir()`, `config.ts`), holds no credential, and appears
+ * nowhere in `credentialDirectories()`. The ruling is narrow and worth stating:
+ * **a session id is not a credential** — it is the id of a row the board
+ * renders publicly to the workspace — but it does not follow that it belongs
+ * beside one.
+ *
+ * ## Concurrency: two `/hmy` sessions in one repo
+ *
+ * The pointer file is named for the PUBLISHER'S PID, so two sessions can never
+ * overwrite each other's state — that is structural, not a convention.
+ *
+ * Routing a hook to the RIGHT pointer is the harder half, and `cwd` cannot do
+ * it: two sessions in one repo share a working directory. What separates them
+ * is process ancestry — each `claude` process spawned both its own MCP server
+ * and its own hooks, so the hook and its MCP server share an ancestor that the
+ * neighbouring session's pair does not.
+ *
+ * Naive set intersection is not enough, because two `claude` processes started
+ * from ONE terminal share that shell as an ancestor too. So the rule is
+ * *nearest* common ancestor: walk the hook's ancestor chain outward and take
+ * the first pointer that claims any pid on it. For the right session that match
+ * lands on `claude` itself; for the neighbour it lands one step further out, at
+ * the shared shell. Nearest wins, and the tie is broken by recency.
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Override for the state root. Exists for tests and for an operator whose home
+ * is not writable; both the publisher and the hook read it, so they agree.
+ */
+export const RUN_STATE_DIR_ENV = "HARMONY_RUN_STATE_DIR";
+
+/**
+ * A pointer older than this is ignored even if its publisher pid looks alive.
+ *
+ * Pids are reused. Without an age bound, a pointer left by a crashed MCP server
+ * whose pid the OS later handed to an unrelated process would keep routing a
+ * hook at a session that ended hours ago. The publisher refreshes its pointer
+ * while it drains (see `run-event-forwarder.ts`), so a live session never ages
+ * out and a dead one always does.
+ */
+export const MAX_POINTER_AGE_MS = 10 * 60_000;
+
+/** How far up the process tree to walk. Deeper than any real hook nesting. */
+const MAX_ANCESTOR_DEPTH = 12;
+
+export interface PublishedRunSession {
+  /** `cards.id` the session is held on. */
+  cardId: string;
+  /** `card_agent_context.id` — the row the run's events attach to. */
+  agentSessionId: string;
+  /** Pid of the MCP server process that published this. */
+  publisherPid: number;
+  /** The publisher's ancestors, nearest first. Used to route a hook. */
+  ancestorPids: number[];
+  /** The publisher's working directory. A weak fallback signal only. */
+  cwd: string;
+  /** ISO timestamp, refreshed while the session is live. */
+  updatedAt: string;
+}
+
+/** Root of the on-disk run state. */
+export function runStateDir(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const override = env[RUN_STATE_DIR_ENV]?.trim();
+  if (override) return override;
+  return join(homedir(), ".harmony", "runs");
+}
+
+/** Where session pointers live. */
+export function sessionsDir(stateDir: string): string {
+  return join(stateDir, "sessions");
+}
+
+/** Where a session's un-posted tool events queue up. */
+export function spoolDir(stateDir: string, agentSessionId: string): string {
+  return join(stateDir, "spool", sanitizeIdForPath(agentSessionId));
+}
+
+/**
+ * A session id is a UUID from the server, but this builds a path from it, so it
+ * is sanitized rather than trusted. A hostile id would otherwise escape the
+ * spool root with `../`.
+ */
+function sanitizeIdForPath(id: string): string {
+  return id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 100);
+}
+
+function pointerFileName(publisherPid: number, cardId: string): string {
+  return `${publisherPid}.${sanitizeIdForPath(cardId)}.json`;
+}
+
+/**
+ * Is this pid still running?
+ *
+ * `EPERM` means the process exists but belongs to another user, which is still
+ * "alive" for our purposes. Only `ESRCH` is a definite no.
+ */
+export function pidIsAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+/**
+ * The parent pid of `pid`, or null.
+ *
+ * Linux is served from `/proc` with no spawn at all. Everything else falls back
+ * to one `ps` call for the WHOLE table — one spawn for the entire walk rather
+ * than one per level, because this runs on the critical path of every tool call
+ * and a per-level spawn would be a visible tax on every `Read`.
+ */
+function readProcParent(pid: number): number | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+    // `comm` is parenthesized and may itself contain spaces or parens, so the
+    // fields are read from after the LAST ')'.
+    const tail = stat
+      .slice(stat.lastIndexOf(")") + 1)
+      .trim()
+      .split(/\s+/);
+    // After comm: state, ppid, …
+    const ppid = Number.parseInt(tail[1] ?? "", 10);
+    return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
+  } catch {
+    return null;
+  }
+}
+
+let psTableCache: Map<number, number> | null = null;
+
+function psParentTable(): Map<number, number> {
+  if (psTableCache) return psTableCache;
+  const table = new Map<number, number>();
+  try {
+    const out = execFileSync("ps", ["-Ao", "pid=,ppid="], {
+      encoding: "utf-8",
+      timeout: 2_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    for (const line of out.split("\n")) {
+      const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+      if (!match) continue;
+      table.set(Number(match[1]), Number(match[2]));
+    }
+  } catch {
+    // No `ps` (Windows, or a stripped container). Routing degrades to the cwd
+    // fallback in `chooseRunSessionForHook`, which is why that fallback exists.
+  }
+  psTableCache = table;
+  return table;
+}
+
+/**
+ * The ancestors of `pid`, nearest first, excluding `pid` itself.
+ *
+ * ## The first hop is free, and that is what usually decides it
+ *
+ * `process.ppid` needs no `/proc` and no `ps`, so when `pid` is this process
+ * the chain is SEEDED with it before any lookup runs. That matters more than it
+ * looks: `ps` is not always available — a hardened sandbox refuses to spawn it,
+ * and macOS has no `/proc` to fall back on — and the immediate parent is
+ * precisely the hop that separates two `/hmy` sessions started from one shell.
+ * So the case this routing exists for resolves at zero cost, and the spawn is
+ * only reached when a deeper hop is genuinely needed.
+ *
+ * `readParent` is injectable so the routing tests can build a synthetic process
+ * tree instead of trying to arrange a real one.
+ */
+export function ancestorPids(
+  pid: number,
+  readParent?: (pid: number) => number | null,
+): number[] {
+  const parentOf =
+    readParent ??
+    ((child: number) => {
+      const viaProc = readProcParent(child);
+      if (viaProc !== null) return viaProc;
+      return psParentTable().get(child) ?? null;
+    });
+
+  const chain: number[] = [];
+  const seen = new Set<number>([pid]);
+  let current = pid;
+
+  if (!readParent && pid === process.pid) {
+    const ppid = process.ppid;
+    if (Number.isInteger(ppid) && ppid > 1) {
+      chain.push(ppid);
+      seen.add(ppid);
+      current = ppid;
+    }
+  }
+
+  for (let depth = chain.length; depth < MAX_ANCESTOR_DEPTH; depth++) {
+    const parent = parentOf(current);
+    // pid 1 is the end of every chain; a cycle means a bad table.
+    if (parent === null || parent <= 1 || seen.has(parent)) break;
+    chain.push(parent);
+    seen.add(parent);
+    current = parent;
+  }
+  return chain;
+}
+
+/**
+ * Publish (or refresh) the pointer for a live session.
+ *
+ * Written to a temp name and renamed, so a hook reading concurrently sees
+ * either the old file or the new one and never a half-written JSON document.
+ *
+ * Never throws: a home directory that is read-only must degrade to "no tool
+ * rows on the timeline", never to a failed `harmony_start_agent_session`.
+ */
+export function publishRunSession(
+  session: Pick<PublishedRunSession, "cardId" | "agentSessionId">,
+  options?: {
+    stateDir?: string;
+    pid?: number;
+    ancestors?: number[];
+    cwd?: string;
+  },
+): PublishedRunSession | null {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const pid = options?.pid ?? process.pid;
+  const record: PublishedRunSession = {
+    cardId: session.cardId,
+    agentSessionId: session.agentSessionId,
+    publisherPid: pid,
+    ancestorPids: options?.ancestors ?? ancestorPids(pid),
+    cwd: options?.cwd ?? process.cwd(),
+    updatedAt: new Date().toISOString(),
+  };
+  try {
+    const dir = sessionsDir(stateDir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = join(dir, pointerFileName(pid, session.cardId));
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(record), { mode: 0o600 });
+    renameSync(temp, target);
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove a session's pointer and drop whatever is left in its spool. */
+export function clearRunSession(
+  cardId: string,
+  options?: {
+    stateDir?: string;
+    pid?: number;
+    agentSessionId?: string;
+    /**
+     * Leave the pointer file in place.
+     *
+     * A pointer is named for `(pid, cardId)` and NOT for the session, so a
+     * second session on the same card in the same process publishes over the
+     * same filename. The forwarder that second session replaces then reaches
+     * this function and, without this flag, unlinks the pointer its successor
+     * just wrote — leaving the live session invisible to every hook until the
+     * next `POINTER_REFRESH_MS`, and silently dropping every tool call in
+     * that window. A handover therefore keeps the pointer and clears only the
+     * spool that belongs to the session going away.
+     */
+    keepPointer?: boolean;
+  },
+): void {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const pid = options?.pid ?? process.pid;
+  if (!options?.keepPointer) {
+    try {
+      unlinkSync(join(sessionsDir(stateDir), pointerFileName(pid, cardId)));
+    } catch {
+      // Already gone. Clearing is idempotent by design — `harmony_end_agent_session`
+      // and process shutdown both call it.
+    }
+  }
+  if (options?.agentSessionId) {
+    try {
+      rmSync(spoolDir(stateDir, options.agentSessionId), {
+        recursive: true,
+        force: true,
+      });
+    } catch {
+      // Best effort; a leftover spool directory is drained-and-empty anyway.
+    }
+  }
+}
+
+/**
+ * Every pointer worth considering: parseable, publisher alive, not stale.
+ *
+ * Dead and stale pointers are unlinked as they are found. A hook is the most
+ * frequent reader in the system, so it is also the cheapest place to garbage
+ * collect — there is no separate sweep to forget to run.
+ */
+export function readPublishedSessions(options?: {
+  stateDir?: string;
+  now?: number;
+}): PublishedRunSession[] {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const now = options?.now ?? Date.now();
+  const dir = sessionsDir(stateDir);
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const live: PublishedRunSession[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const path = join(dir, name);
+    let record: PublishedRunSession;
+    try {
+      record = JSON.parse(readFileSync(path, "utf-8")) as PublishedRunSession;
+    } catch {
+      safeUnlink(path);
+      continue;
+    }
+    if (
+      typeof record?.cardId !== "string" ||
+      typeof record?.agentSessionId !== "string" ||
+      !record.cardId ||
+      !record.agentSessionId
+    ) {
+      safeUnlink(path);
+      continue;
+    }
+    const age = now - Date.parse(record.updatedAt ?? "");
+    if (!Number.isFinite(age) || age > MAX_POINTER_AGE_MS) {
+      safeUnlink(path);
+      continue;
+    }
+    if (!pidIsAlive(record.publisherPid)) {
+      safeUnlink(path);
+      continue;
+    }
+    live.push({ ...record, ancestorPids: record.ancestorPids ?? [] });
+  }
+  return live;
+}
+
+function safeUnlink(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Another reader got there first, or the file is not ours to remove.
+  }
+}
+
+/**
+ * Which published session a hook belongs to. Pure — the process tree and the
+ * pointer list are both arguments.
+ *
+ * The scoring is "distance to the nearest shared ancestor": index 0 means the
+ * hook's immediate parent is (or was spawned by) the publisher's own line.
+ * Two `/hmy` sessions launched from one shell both match that shell, but only
+ * the right one matches the `claude` process below it, so the right one scores
+ * lower and wins.
+ *
+ * **The payload's `cwd` is a NECESSARY condition, not a last-resort fallback.**
+ * The hook is installed in the user layer, so it fires for EVERY Claude Code
+ * session on the machine — including sessions that have never touched Harmony,
+ * in unrelated repositories. Those sessions still share an ancestor with a
+ * publisher (a login shell, `launchd`, pid 1), so ancestry alone answers "some
+ * shared ancestor exists" for practically every pair of processes on one host.
+ * Ranking by distance separates two publishers from each other; it cannot tell
+ * a hook that belongs to NO publisher from one that belongs to the only
+ * publisher there is. Filtering by working directory first is what makes the
+ * match positive evidence rather than a default.
+ *
+ * That is also why there is no "when in doubt, use the only candidate" branch.
+ * It read as generous and was the widest hole in the routing: with one `/hmy`
+ * session published, every unrelated Claude Code session on the same machine
+ * posted its `Bash` command lines and file reads to that session's card. The
+ * same branch is what would let a future contained daemon run — should
+ * `settingSources` ever gain `"user"` — attribute its tool calls to a
+ * neighbouring `/hmy` session's card, so removing it also stops this card's
+ * design depending on that harness knob staying where it is.
+ *
+ * With no ancestry available at all (no `/proc`, no `ps`) every score is
+ * `Infinity` and an unambiguous working directory decides. Genuine ambiguity
+ * returns null. Dropping a row is the correct failure — attributing one
+ * session's `Bash` command to another session's card would put the wrong work
+ * on the wrong board.
+ */
+export function chooseRunSessionForHook(args: {
+  candidates: PublishedRunSession[];
+  hookAncestorPids: number[];
+  cwd?: string;
+}): PublishedRunSession | null {
+  const { candidates, hookAncestorPids } = args;
+  if (candidates.length === 0) return null;
+
+  const hasCwd = typeof args.cwd === "string" && args.cwd.length > 0;
+  // A stdio MCP server is spawned by the client with the client's own working
+  // directory, so a publisher's `cwd` and its hook payloads' `cwd` are the same
+  // string by construction.
+  const pool = hasCwd
+    ? candidates.filter((candidate) => candidate.cwd === args.cwd)
+    : candidates;
+  if (pool.length === 0) return null;
+
+  let best: PublishedRunSession | null = null;
+  let bestScore = Number.POSITIVE_INFINITY;
+
+  for (const candidate of pool) {
+    const claimed = new Set<number>([
+      candidate.publisherPid,
+      ...(candidate.ancestorPids ?? []),
+    ]);
+    let score = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < hookAncestorPids.length; i++) {
+      if (claimed.has(hookAncestorPids[i] as number)) {
+        score = i;
+        break;
+      }
+    }
+    if (score === Number.POSITIVE_INFINITY) continue;
+    if (
+      score < bestScore ||
+      (score === bestScore &&
+        best !== null &&
+        Date.parse(candidate.updatedAt) > Date.parse(best.updatedAt))
+    ) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+
+  if (best) return best;
+
+  // No shared ancestor. A working directory that names exactly one publisher is
+  // the best remaining evidence; anything less than that routes nowhere.
+  if (hasCwd && pool.length === 1) return pool[0] as PublishedRunSession;
+  return null;
+}
+
+/**
+ * Append one batch of events to a session's spool.
+ *
+ * ONE FILE PER CALL, never a shared append-only log. Several hook processes can
+ * be in flight at once, and a concurrent `O_APPEND` write is only atomic below
+ * `PIPE_BUF` (4 KB) — a redacted tool row can exceed that, so an interleaved
+ * write would corrupt a line. A file per batch has no such window, needs no
+ * lock, and lets the drainer delete exactly what it posted.
+ *
+ * The name sorts lexicographically by time, so the drainer replays in order.
+ */
+export function writeSpoolBatch(
+  dir: string,
+  events: unknown[],
+  options?: { now?: number; pid?: number; nonce?: string },
+): string | null {
+  if (events.length === 0) return null;
+  const now = options?.now ?? Date.now();
+  const pid = options?.pid ?? process.pid;
+  const nonce =
+    options?.nonce ?? Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const name = `${String(now).padStart(14, "0")}-${pid}-${nonce}.json`;
+    const target = join(dir, name);
+    const temp = `${target}.tmp`;
+    writeFileSync(temp, JSON.stringify(events), { mode: 0o600 });
+    renameSync(temp, target);
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+export interface SpoolBatch {
+  path: string;
+  events: unknown[];
+}
+
+/**
+ * Read up to `limit` spooled batches in time order, oldest first.
+ *
+ * Reading does NOT delete: the caller removes a batch only once the API has
+ * accepted it, so a failed flush is retried rather than lost. An unparseable
+ * batch is dropped on sight, since retrying it forever would wedge the queue.
+ */
+export function readSpoolBatches(dir: string, limit = 200): SpoolBatch[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const batches: SpoolBatch[] = [];
+  for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+    if (batches.length >= limit) break;
+    const path = join(dir, name);
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf-8"));
+      if (!Array.isArray(parsed)) {
+        safeUnlink(path);
+        continue;
+      }
+      batches.push({ path, events: parsed });
+    } catch {
+      safeUnlink(path);
+    }
+  }
+  return batches;
+}
+
+/** Remove batches the API has accepted. */
+export function removeSpoolBatches(paths: string[]): void {
+  for (const path of paths) safeUnlink(path);
+}
+
+/**
+ * Drop the oldest spooled batches once a session's queue grows past `max`.
+ *
+ * The bound the daemon's in-memory buffer gets from `MAX_BUFFER` has to be
+ * re-established here, because a spool survives the process that filled it: an
+ * offline session would otherwise fill the disk. Oldest-first matches the
+ * daemon, which caps its re-queued buffer from the tail.
+ */
+export function trimSpool(dir: string, max: number): number {
+  let names: string[];
+  try {
+    names = readdirSync(dir)
+      .filter((n) => n.endsWith(".json"))
+      .sort();
+  } catch {
+    return 0;
+  }
+  if (names.length <= max) return 0;
+  const excess = names.slice(0, names.length - max);
+  for (const name of excess) safeUnlink(join(dir, name));
+  return excess.length;
+}
+
+/**
+ * Remember which publisher a harness session routed to, so the ancestry walk
+ * runs once per session rather than once per tool call.
+ *
+ * The walk costs a `ps` spawn on any platform without `/proc`, and it sits on
+ * the critical path of every `Read` the agent performs. The answer cannot
+ * change for the life of a harness session — the `claude` process and its MCP
+ * server both outlive it — so it is computed once and looked up afterwards.
+ *
+ * A memo is a HINT, and it is only ever as good as what it can be confirmed
+ * against. It therefore stores the whole identity it resolved — pid, card and
+ * agent session — because a pid alone cannot be confirmed: one MCP process
+ * routinely holds two live sessions (an explicit `/hmy` session on card A
+ * survives the card-switch sweep while a trigger tool publishes card B), and
+ * on the hosted transport one process serves many. Confirming a pid alone
+ * would then pick whichever pointer happened to be found first and attribute
+ * one card's tool calls to another. A memo that no longer matches a live
+ * pointer costs one ancestry walk, which is the price it was always meant to
+ * risk.
+ */
+function routeMemoPath(stateDir: string, harnessSessionId: string): string {
+  return join(
+    stateDir,
+    "routes",
+    `${sanitizeIdForPath(harnessSessionId)}.json`,
+  );
+}
+
+/** The identity a harness session resolved to, to be re-confirmed on read. */
+export interface RouteMemo {
+  publisherPid: number;
+  cardId: string;
+  agentSessionId: string;
+}
+
+export function readRouteMemo(
+  stateDir: string,
+  harnessSessionId: string,
+): RouteMemo | null {
+  try {
+    const raw = JSON.parse(
+      readFileSync(routeMemoPath(stateDir, harnessSessionId), "utf-8"),
+    ) as { publisherPid?: unknown; cardId?: unknown; agentSessionId?: unknown };
+    const pid = raw?.publisherPid;
+    const cardId = raw?.cardId;
+    const agentSessionId = raw?.agentSessionId;
+    // All three or nothing. A memo written by an older build carries only the
+    // pid; returning it partially would resurrect exactly the pid-only
+    // confirmation this shape exists to prevent, so it reads as absent and the
+    // caller re-resolves and rewrites it.
+    if (typeof pid !== "number" || !Number.isInteger(pid)) return null;
+    if (typeof cardId !== "string" || cardId.length === 0) return null;
+    if (typeof agentSessionId !== "string" || agentSessionId.length === 0) {
+      return null;
+    }
+    return { publisherPid: pid, cardId, agentSessionId };
+  } catch {
+    return null;
+  }
+}
+
+export function writeRouteMemo(
+  stateDir: string,
+  harnessSessionId: string,
+  memo: RouteMemo,
+): void {
+  try {
+    const path = routeMemoPath(stateDir, harnessSessionId);
+    mkdirSync(join(stateDir, "routes"), { recursive: true, mode: 0o700 });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        publisherPid: memo.publisherPid,
+        cardId: memo.cardId,
+        agentSessionId: memo.agentSessionId,
+      }),
+      { mode: 0o600 },
+    );
+  } catch {
+    // A memo is an optimization. Losing it costs one ancestry walk.
+  }
+}
+
+/** True when the state root exists — used to skip work in the common no-op case. */
+export function runStateExists(stateDir = runStateDir()): boolean {
+  try {
+    return (
+      existsSync(sessionsDir(stateDir)) &&
+      statSync(sessionsDir(stateDir)).isDirectory()
+    );
+  } catch {
+    return false;
+  }
+}