@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/link/store.ts

@@ -0,0 +1,139 @@
+import { chmodSync, mkdirSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import { isLinkPort } from "./ports";
+import { assertSshAlias } from "./ssh-argv";
+
+/**
+ * Persisted machine links. The file names hosts, ports, host-key fingerprints and data-key ids.
+ * It never holds a key: keys live in the running proxy's `apiKeys`, and admission reads them there.
+ */
+export type LinkDirection = "hub-initiated" | "client-initiated";
+
+export interface LinkRecord {
+  id: string;
+  alias: string;
+  direction: LinkDirection;
+  /**
+   * `ssh-keygen -lf` fingerprint the user confirmed for the client host, e.g. "SHA256:…".
+   * Null only for client-initiated links: the hub never opens SSH to that client.
+   */
+  hostKeyFingerprint: string | null;
+  /** Port the tunnel listens on at the client machine's 127.0.0.1. */
+  tunnelPort: number;
+  /** Id of the data key issued for this link. */
+  apiKeyId: string;
+  createdAt: string;
+}
+
+export interface LinkStore {
+  version: 1;
+  /** Port of the link listener at this machine's 127.0.0.1, fixed once chosen. */
+  listenerPort: number | null;
+  links: LinkRecord[];
+}
+
+export class LinkStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LinkStoreError";
+  }
+}
+
+export function emptyLinkStore(): LinkStore {
+  return { version: 1, listenerPort: null, links: [] };
+}
+
+export function newLinkId(): string {
+  return `lnk_${randomBytes(8).toString("hex")}`;
+}
+
+const RECORD_KEYS = new Set(["id", "alias", "direction", "hostKeyFingerprint", "tunnelPort", "apiKeyId", "createdAt"]);
+const STORE_KEYS = new Set(["version", "listenerPort", "links"]);
+const API_KEY_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+const FINGERPRINT = /^[A-Z0-9]+:[A-Za-z0-9+/=]{16,128}$/;
+
+/** A trust-boundary file: an unknown field is an error, not something to drop silently. */
+function assertOnlyKeys(raw: Record<string, unknown>, allowed: Set<string>, where: string): void {
+  for (const key of Object.keys(raw)) {
+    if (!allowed.has(key)) throw new LinkStoreError(`${where} has an unknown field ${JSON.stringify(key)}`);
+  }
+}
+
+const isListenerPort = (value: unknown): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
+
+function parseRecord(value: unknown, index: number): LinkRecord {
+  const fail = (field: string): never => { throw new LinkStoreError(`links[${index}].${field} is invalid`); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new LinkStoreError(`links[${index}] is not an object`);
+  const raw = value as Record<string, unknown>;
+  assertOnlyKeys(raw, RECORD_KEYS, `links[${index}]`);
+  if (typeof raw.id !== "string" || !/^lnk_[0-9a-f]{16}$/.test(raw.id)) fail("id");
+  if (typeof raw.alias !== "string") fail("alias");
+  try { assertSshAlias(raw.alias as string); } catch { fail("alias"); }
+  if (raw.direction !== "hub-initiated" && raw.direction !== "client-initiated") fail("direction");
+  const fingerprint = raw.hostKeyFingerprint;
+  if (fingerprint === null ? raw.direction !== "client-initiated"
+    : typeof fingerprint !== "string" || !FINGERPRINT.test(fingerprint)) fail("hostKeyFingerprint");
+  if (!isLinkPort(raw.tunnelPort)) fail("tunnelPort");
+  if (typeof raw.apiKeyId !== "string" || !API_KEY_ID.test(raw.apiKeyId)) fail("apiKeyId");
+  if (typeof raw.createdAt !== "string" || Number.isNaN(Date.parse(raw.createdAt))) fail("createdAt");
+  return {
+    id: raw.id as string,
+    alias: raw.alias as string,
+    direction: raw.direction as LinkDirection,
+    hostKeyFingerprint: fingerprint as string | null,
+    tunnelPort: raw.tunnelPort as number,
+    apiKeyId: raw.apiKeyId as string,
+    createdAt: raw.createdAt as string,
+  };
+}
+
+export function parseLinkStore(text: string): LinkStore {
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new LinkStoreError("links.json is not valid JSON"); }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new LinkStoreError("links.json is not an object");
+  const body = raw as Record<string, unknown>;
+  assertOnlyKeys(body, STORE_KEYS, "links.json");
+  if (body.version !== 1) throw new LinkStoreError("links.json has an unsupported version");
+  if (body.listenerPort !== null && !isListenerPort(body.listenerPort)) throw new LinkStoreError("listenerPort is invalid");
+  if (!Array.isArray(body.links)) throw new LinkStoreError("links is not an array");
+  const links = body.links.map(parseRecord);
+  const ids = new Set(links.map(link => link.id));
+  if (ids.size !== links.length) throw new LinkStoreError("links.json has duplicate link ids");
+  return { version: 1, listenerPort: body.listenerPort as number | null, links };
+}
+
+/** A missing file is an empty store. A damaged file is an error, never silently empty. */
+export function readLinkStore(path: string): LinkStore {
+  let text: string;
+  try { text = readFileSync(path, "utf8"); } catch (error) {
+    if (isMissingPathError(error)) return emptyLinkStore();
+    throw error;
+  }
+  return parseLinkStore(text);
+}
+
+export function writeLinkStore(path: string, store: LinkStore): void {
+  const normalized = parseLinkStore(JSON.stringify(store));
+  const dir = dirname(path);
+  assertNotRealHomeUnderTest(dirname(dir));
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  else chmodSync(dir, 0o700);
+  // atomicWriteFile hardens its private temp on Windows before the rename, so only POSIX needs
+  // the explicit mode here.
+  atomicWriteFile(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+/**
+ * Activation gate for the link listener: true only for a readable store with at least one link.
+ * A damaged store keeps the listener closed rather than guessing.
+ */
+export function hasLinks(path: string): boolean {
+  try { return readLinkStore(path).links.length > 0; } catch { return false; }
+}

package/src/link/supervisor.ts

@@ -0,0 +1,404 @@
+import { mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../config/atomic-write";
+import { linkDir, linkKnownHostsPath, linkStorePath } from "./paths";
+import { buildTunnelArgv } from "./ssh-argv";
+import { createSshRunner, type SshChild, type SshRunner } from "./ssh-runner";
+import {
+  classifySshStderr,
+  dueForSpawn,
+  IDLE,
+  reduceTunnel,
+  type TunnelState,
+} from "./tunnel-state";
+import { emptyLinkStore, readLinkStore, type LinkRecord, type LinkStore } from "./store";
+
+export type LinkTunnelStatus =
+  | {
+    linkId: string;
+    direction: "hub-initiated";
+    state: TunnelState;
+    pid: number | null;
+    orphan?: "orphan-unverified";
+  }
+  | {
+    linkId: string;
+    direction: "client-initiated";
+    state: "client-owned";
+    pid: null;
+  };
+
+export interface LinkSupervisor {
+  start(): void;
+  ensureStarted(): Promise<void>;
+  reload(): Promise<void>;
+  stopLink(linkId: string): Promise<void>;
+  status(): readonly LinkTunnelStatus[];
+  notifyAuthenticatedRequest?(apiKeyId: string): void;
+  stop(): Promise<void>;
+}
+
+interface Pidfile {
+  version: 1;
+  linkId: string;
+  pid: number;
+  argv: string[];
+}
+
+export interface LinkSupervisorDeps {
+  readStore?: () => LinkStore;
+  writeStore?: (store: LinkStore) => void;
+  runner?: SshRunner;
+  now?: () => number;
+  setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setInterval>;
+  clearTimer?: (timer: ReturnType<typeof setInterval>) => void;
+  readProcessArgv?: (pid: number) => readonly string[] | null;
+  killProcess?: (pid: number) => void;
+  pidfileDir?: string;
+  readPidfile?: (path: string) => Pidfile | null;
+  writePidfile?: (path: string, pidfile: Pidfile) => void;
+  removePidfile?: (path: string) => void;
+  platform?: NodeJS.Platform;
+  random?: () => number;
+  apiKeys?: () => readonly { id: string; name: string }[];
+  revokeApiKey?: (id: string) => boolean;
+  warn?: (message: string) => void;
+}
+
+const TIMER_MS = 1_000;
+const SPAWN_GRACE_MS = 5_000;
+
+function sameArgv(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function parsePidfile(text: string): Pidfile | null {
+  try {
+    const raw: unknown = JSON.parse(text);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const body = raw as Record<string, unknown>;
+    if (body.version !== 1 || typeof body.linkId !== "string" || typeof body.pid !== "number"
+      || !Number.isSafeInteger(body.pid) || body.pid < 1 || !Array.isArray(body.argv)
+      || body.argv.some(value => typeof value !== "string")) return null;
+    return { version: 1, linkId: body.linkId, pid: body.pid, argv: body.argv as string[] };
+  } catch {
+    return null;
+  }
+}
+
+function linuxProcessArgv(pid: number): readonly string[] | null {
+  try {
+    const values = readFileSync(`/proc/${pid}/cmdline`).toString().split("\0");
+    if (values.at(-1) === "") values.pop();
+    return values.length > 0 ? values : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultKillProcess(pid: number): void {
+  try { process.kill(pid, "SIGTERM"); } catch { /* the process may already have exited */ }
+}
+
+export function createLinkSupervisor(deps: LinkSupervisorDeps = {}): LinkSupervisor {
+  const storePath = linkStorePath();
+  const storeDir = deps.pidfileDir ?? linkDir();
+  const readStore = deps.readStore ?? (() => readLinkStore(storePath));
+  const runner = deps.runner ?? createSshRunner();
+  const now = deps.now ?? (() => Date.now());
+  const setTimer = deps.setTimer ?? ((callback, ms) => setInterval(callback, ms));
+  const clearTimer = deps.clearTimer ?? ((timer: ReturnType<typeof setInterval>) => clearInterval(timer));
+  const platform = deps.platform ?? process.platform;
+  const readProcessArgv = deps.readProcessArgv ?? (platform === "linux" ? linuxProcessArgv : () => null);
+  const killProcess = deps.killProcess ?? defaultKillProcess;
+  const readPidfile = deps.readPidfile ?? ((path: string) => {
+    try { return parsePidfile(readFileSync(path, "utf8")); } catch { return null; }
+  });
+  const writePidfile = deps.writePidfile ?? ((path: string, pidfile: Pidfile) => {
+    mkdirSync(storeDir, { recursive: true, mode: 0o700 });
+    atomicWriteFile(path, `${JSON.stringify(pidfile)}\n`);
+  });
+  const removePidfile = deps.removePidfile ?? ((path: string) => {
+    try { unlinkSync(path); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  });
+  const warn = deps.warn ?? ((message: string) => console.warn(message));
+
+  let store: LinkStore = emptyLinkStore();
+  let started = false;
+  let stopping = false;
+  let lifecycleFlight: Promise<void> | undefined;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const states = new Map<string, TunnelState>();
+  const children = new Map<string, { child: SshChild; argv: readonly string[] }>();
+  const orphanUnverified = new Set<string>();
+  const recordInstances = new Map<string, string>();
+
+  const reconcileApiKeys = (): void => {
+    const keys = deps.apiKeys?.() ?? [];
+    if (!deps.revokeApiKey || keys.length === 0) return;
+    const referenced = new Set(store.links.map(link => link.apiKeyId));
+    for (const key of keys) {
+      if (!key.name.startsWith("link:") || referenced.has(key.id)) continue;
+      try {
+        if (deps.revokeApiKey(key.id)) warn(`[link] revoked orphaned link key id=${key.id}`);
+      } catch (error) {
+        warn(`[link] orphaned link key revoke failed id=${key.id}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  };
+
+  const pidfilePath = (linkId: string): string => join(storeDir, `${linkId}.pid`);
+
+  const recordInstance = (record: LinkRecord, listenerPort: number | null): string => JSON.stringify([
+    record.id,
+    record.alias,
+    record.direction,
+    record.hostKeyFingerprint,
+    record.tunnelPort,
+    record.apiKeyId,
+    record.createdAt,
+    listenerPort,
+  ]);
+
+  const conditionalRemovePidfile = (linkId: string, pid: number): void => {
+    const path = pidfilePath(linkId);
+    const current = readPidfile(path);
+    if (current?.linkId === linkId && current.pid === pid) removePidfile(path);
+  };
+
+  const reapOrphans = (): void => {
+    for (const record of store.links) {
+      const pidfile = readPidfile(pidfilePath(record.id));
+      if (!pidfile || pidfile.linkId !== record.id) continue;
+      // macOS deliberately has no exact argv source here. A ps rendering is not an identity proof.
+      if (platform !== "linux") {
+        orphanUnverified.add(record.id);
+        continue;
+      }
+      const actualArgv = readProcessArgv(pidfile.pid);
+      if (actualArgv && sameArgv(actualArgv, pidfile.argv)) {
+        try { killProcess(pidfile.pid); } finally { removePidfile(pidfilePath(record.id)); }
+      } else {
+        orphanUnverified.add(record.id);
+      }
+    }
+  };
+
+  const setEvent = (linkId: string, event: Parameters<typeof reduceTunnel>[1]): TunnelState => {
+    const next = reduceTunnel(states.get(linkId) ?? IDLE, event, deps.random);
+    states.set(linkId, next);
+    return next;
+  };
+
+  const spawnFor = (record: LinkRecord): void => {
+    if (stopping || record.direction !== "hub-initiated" || children.has(record.id)) return;
+    if (states.get(record.id)?.kind === "failed") return;
+    if (store.listenerPort === null) {
+      states.set(record.id, { kind: "failed", since: now(), reason: "forward" });
+      return;
+    }
+    let argv: string[];
+    try {
+      argv = buildTunnelArgv({
+        alias: record.alias,
+        direction: "R",
+        bindPort: record.tunnelPort,
+        targetPort: store.listenerPort,
+        knownHostsFile: linkKnownHostsPath(),
+      });
+      const child = runner.spawnTunnel(argv);
+      children.set(record.id, { child, argv });
+      orphanUnverified.delete(record.id);
+      setEvent(record.id, { type: "spawn", now: now() });
+      writePidfile(pidfilePath(record.id), { version: 1, linkId: record.id, pid: child.pid, argv });
+      void child.exited.then(async () => {
+        if (children.get(record.id)?.child !== child) return;
+        children.delete(record.id);
+        conditionalRemovePidfile(record.id, child.pid);
+        if (stopping) return;
+        const stderr = child.stderr ? await child.stderr : "";
+        const next = setEvent(record.id, { type: "exit", now: now(), stderrClass: classifySshStderr(stderr) });
+        if (next.kind === "failed") return;
+      }).catch(() => {
+        if (children.get(record.id)?.child !== child) return;
+        children.delete(record.id);
+        conditionalRemovePidfile(record.id, child.pid);
+        if (!stopping) setEvent(record.id, { type: "exit", now: now(), stderrClass: "network" });
+      });
+    } catch {
+      states.set(record.id, { kind: "failed", since: now(), reason: "forward" });
+    }
+  };
+
+  const tick = (): void => {
+    if (stopping) return;
+    const current = now();
+    for (const record of store.links) {
+      if (record.direction !== "hub-initiated") continue;
+      const next = setEvent(record.id, { type: "tick", now: current });
+      const child = children.get(record.id);
+      if (next.kind === "failed" && child) {
+        child.child.kill("SIGTERM");
+        children.delete(record.id);
+        conditionalRemovePidfile(record.id, child.child.pid);
+      } else if (next.kind === "connecting" && child && current - next.since >= SPAWN_GRACE_MS) {
+        setEvent(record.id, { type: "ready", now: current });
+      } else if (dueForSpawn(next, current)) {
+        spawnFor(record);
+      }
+    }
+  };
+
+  const syncTimer = (): void => {
+    const hasHubLinks = store.links.some(record => record.direction === "hub-initiated");
+    if (hasHubLinks && timer === undefined && !stopping) timer = setTimer(tick, TIMER_MS);
+    if (!hasHubLinks && timer !== undefined) {
+      clearTimer(timer);
+      timer = undefined;
+    }
+  };
+
+  const begin = (): void => {
+    if (started || stopping) return;
+    store = readStore();
+    reconcileApiKeys();
+    reapOrphans();
+    started = true;
+    for (const record of store.links) recordInstances.set(record.id, recordInstance(record, store.listenerPort));
+    for (const record of store.links) {
+      if (record.direction === "hub-initiated") spawnFor(record);
+    }
+    syncTimer();
+  };
+
+  let queuedLifecycle: (() => void | Promise<void>) | undefined;
+  const runLifecycle = (operation: () => void | Promise<void>): Promise<void> => {
+    if (lifecycleFlight) {
+      queuedLifecycle = operation;
+      return lifecycleFlight;
+    }
+    lifecycleFlight = (async () => {
+      let next: (() => void | Promise<void>) | undefined = operation;
+      while (next) {
+        await next();
+        next = queuedLifecycle;
+        queuedLifecycle = undefined;
+      }
+    })().finally(() => {
+      lifecycleFlight = undefined;
+      queuedLifecycle = undefined;
+    });
+    return lifecycleFlight;
+  };
+
+  const stopLink = async (linkId: string): Promise<void> => {
+    const current = children.get(linkId);
+    if (!current) {
+      states.set(linkId, IDLE);
+      return;
+    }
+    children.delete(linkId);
+    current.child.kill("SIGTERM");
+    await current.child.exited;
+    conditionalRemovePidfile(linkId, current.child.pid);
+    states.set(linkId, IDLE);
+  };
+
+  return {
+    start() {
+      if (lifecycleFlight) return;
+      begin();
+    },
+    ensureStarted() {
+      return runLifecycle(begin);
+    },
+    async reload() {
+      await runLifecycle(async () => {
+        if (stopping) return;
+        if (!started) {
+          begin();
+          return;
+        }
+        const nextStore = readStore();
+        const nextInstances = new Map(nextStore.links.map(record => [record.id, recordInstance(record, nextStore.listenerPort)]));
+        const changed = new Set<string>();
+        for (const record of nextStore.links) {
+          if (recordInstances.get(record.id) !== undefined && recordInstances.get(record.id) !== nextInstances.get(record.id)) {
+            changed.add(record.id);
+          }
+        }
+        store = nextStore;
+        for (const [linkId] of [...children]) {
+          if (nextInstances.has(linkId) && !changed.has(linkId)) continue;
+          await stopLink(linkId);
+          states.delete(linkId);
+          orphanUnverified.delete(linkId);
+          recordInstances.delete(linkId);
+          if (stopping) return;
+        }
+        for (const record of nextStore.links) {
+          if (changed.has(record.id)) {
+            states.delete(record.id);
+            orphanUnverified.delete(record.id);
+          }
+        }
+        recordInstances.clear();
+        for (const [linkId, instance] of nextInstances) recordInstances.set(linkId, instance);
+        for (const record of nextStore.links) {
+          if (stopping || record.direction !== "hub-initiated" || children.has(record.id)) continue;
+          spawnFor(record);
+        }
+        syncTimer();
+      });
+    },
+    stopLink,
+    notifyAuthenticatedRequest(apiKeyId: string) {
+      for (const record of store.links) {
+        if (record.direction === "hub-initiated" && record.apiKeyId === apiKeyId && children.has(record.id)) {
+          const state = states.get(record.id);
+          if (state?.kind === "connecting" || state?.kind === "reconnecting") setEvent(record.id, { type: "ready", now: now() });
+        }
+      }
+    },
+    status() {
+      return store.links.map(record => {
+        if (record.direction === "client-initiated") {
+          return { linkId: record.id, direction: record.direction, state: "client-owned", pid: null };
+        }
+        const child = children.get(record.id);
+        return {
+          linkId: record.id,
+          direction: record.direction,
+          state: states.get(record.id) ?? IDLE,
+          pid: child?.child.pid ?? null,
+          ...(orphanUnverified.has(record.id) ? { orphan: "orphan-unverified" as const } : {}),
+        };
+      });
+    },
+    async stop() {
+      stopping = true;
+      if (timer !== undefined) {
+        clearTimer(timer);
+        timer = undefined;
+      }
+      const active = [...children.entries()];
+      for (const [linkId, current] of active) {
+        children.delete(linkId);
+        current.child.kill("SIGTERM");
+      }
+      await Promise.all(active.map(async ([linkId, current]) => {
+        await current.child.exited;
+        conditionalRemovePidfile(linkId, current.child.pid);
+        states.set(linkId, IDLE);
+      }));
+      for (const record of store.links) {
+        if (record.direction === "hub-initiated") states.set(record.id, IDLE);
+      }
+      if (lifecycleFlight) await lifecycleFlight;
+    },
+  };
+}
+
+export type { Pidfile };

package/src/link/tunnel-state.ts

@@ -0,0 +1,91 @@
+/**
+ * Lifecycle of one link tunnel as a pure reducer. The supervisor that spawns ssh feeds events in
+ * and reads decisions out; nothing here touches a process, a timer or the clock.
+ *
+ * - connected: the forward is up.
+ * - reconnecting: a transient failure; requests through the link fail with 503 meanwhile, and a
+ *   new attempt is due at `retryAt`.
+ * - failed: needs the user. Auth, host key and forward failures are not retried, and neither is a
+ *   link that stayed down for FAILED_AFTER_MS.
+ */
+
+export type TunnelFailure = "auth" | "hostkey" | "forward" | "timeout";
+export type StderrClass = "auth" | "hostkey" | "forward" | "network" | "unknown";
+
+export type TunnelState =
+  | { kind: "idle" }
+  | { kind: "connecting"; since: number }
+  | { kind: "connected"; since: number }
+  | { kind: "reconnecting"; since: number; attempt: number; retryAt: number; inFlight: boolean }
+  | { kind: "failed"; since: number; reason: TunnelFailure };
+
+export type TunnelEvent =
+  | { type: "spawn"; now: number }
+  | { type: "ready"; now: number }
+  | { type: "exit"; now: number; stderrClass: StderrClass }
+  | { type: "tick"; now: number }
+  | { type: "stop" };
+
+export const FAILED_AFTER_MS = 5 * 60_000;
+export const BASE_DELAY_MS = 1_000;
+export const MAX_DELAY_MS = 30_000;
+
+export const IDLE: TunnelState = { kind: "idle" };
+
+/** Capped exponential backoff with ±20% jitter. `random` is injectable for tests. */
+export function nextDelayMs(attempt: number, random: () => number = Math.random): number {
+  const exponent = Math.max(0, Math.min(attempt - 1, 16));
+  const base = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** exponent);
+  const jitter = 0.8 + random() * 0.4;
+  return Math.round(Math.min(MAX_DELAY_MS, base * jitter));
+}
+
+export function reduceTunnel(state: TunnelState, event: TunnelEvent, random?: () => number): TunnelState {
+  if (event.type === "stop") return IDLE;
+  switch (event.type) {
+    case "spawn":
+      if (state.kind === "idle" || state.kind === "failed") return { kind: "connecting", since: event.now };
+      if (state.kind === "reconnecting") return { ...state, inFlight: true };
+      return state;
+    case "ready":
+      if (state.kind === "connecting" || state.kind === "reconnecting") return { kind: "connected", since: event.now };
+      return state;
+    case "exit": {
+      if (state.kind === "idle" || state.kind === "failed") return state;
+      const cls = event.stderrClass;
+      if (cls === "auth" || cls === "hostkey" || cls === "forward") return { kind: "failed", since: event.now, reason: cls };
+      const since = state.kind === "reconnecting" || state.kind === "connecting" ? state.since : event.now;
+      if (event.now - since >= FAILED_AFTER_MS) return { kind: "failed", since: event.now, reason: "timeout" };
+      const attempt = state.kind === "reconnecting" ? state.attempt + 1 : 1;
+      return { kind: "reconnecting", since, attempt, retryAt: event.now + nextDelayMs(attempt, random), inFlight: false };
+    }
+    case "tick":
+      // An attempt in flight does not pause the clock: a first attempt or a retry that hangs past
+      // the limit still fails the link, and the supervisor kills the child on seeing `failed`.
+      if ((state.kind === "reconnecting" || state.kind === "connecting") && event.now - state.since >= FAILED_AFTER_MS) {
+        return { kind: "failed", since: event.now, reason: "timeout" };
+      }
+      return state;
+  }
+}
+
+/** Whether the supervisor should start a new ssh attempt now. */
+export function dueForSpawn(state: TunnelState, now: number): boolean {
+  return state.kind === "reconnecting" && !state.inFlight && now >= state.retryAt;
+}
+
+/** Classify ssh stderr. Anything unrecognised is treated as transient. */
+export function classifySshStderr(stderr: string): StderrClass {
+  const text = stderr.toLowerCase();
+  if (text.includes("host key verification failed") || text.includes("remote host identification has changed")
+    || text.includes("no ecdsa host key is known") || text.includes("no ed25519 host key is known")
+    || text.includes("no rsa host key is known") || text.includes("host key is known for")) return "hostkey";
+  if (text.includes("permission denied") || text.includes("too many authentication failures")) return "auth";
+  if (text.includes("remote port forwarding failed") || text.includes("port forwarding failed")
+    || text.includes("address already in use") || text.includes("cannot listen to port")
+    || text.includes("could not request local forwarding")) return "forward";
+  if (text.includes("connection refused") || text.includes("timed out") || text.includes("could not resolve")
+    || text.includes("network is unreachable") || text.includes("connection closed") || text.includes("broken pipe")
+    || text.includes("connection reset") || text.includes("no route to host")) return "network";
+  return "unknown";
+}