@jmcombs/pi-steward 0.0.0

package/server/config-wiring.ts

@@ -0,0 +1,490 @@
+/**
+ * Keeps the live source wired to whatever `steward.json` says RIGHT NOW.
+ *
+ * The artifact is written by `/steward_initialize`, and an operator runs that
+ * with the dashboard open — which is the whole point of a setup flow. Read once
+ * at extension load, the config was baked into a closure: a machine that gained
+ * a collector, a log path, control commands or a launch baseline saw none of it
+ * until the next Pi session, and a machine whose config was deleted kept running
+ * the collector it declared. This module is the seam that makes both take effect
+ * on the next repaint instead.
+ *
+ * WHAT TRIGGERS A RE-READ. `fs.watch` on the config's DIRECTORY, never a timer.
+ * The directory rather than the file because appearing and disappearing are the
+ * two cases that matter most, and a watch on a path that does not exist yet
+ * cannot be armed at all — while a rename-into-place (how any careful writer
+ * updates a config) replaces the inode a file watch was holding. When the
+ * directory itself is missing, the nearest existing ancestor is watched instead
+ * and the watch moves down as the directories appear.
+ *
+ * WHAT SURVIVES A TRIGGER. `fs.watch` is chatty — a single save is routinely two
+ * or three events, and a watch on an ancestor sees traffic that has nothing to do
+ * with us — so every refresh first takes ONE `stat` and compares an identity
+ * tuple: device, inode, mtime, ctime, size, mode and owner. Unchanged means the
+ * file is not re-read, not re-parsed, and nothing is rebuilt or respawned. The
+ * tuple reaches past mtime and size on purpose — a `chmod o+w` moves neither,
+ * and that no-op-looking change is exactly the one the security gate exists to
+ * catch.
+ *
+ * WHAT IT CANNOT SEE. A watch does not begin delivering the instant it is
+ * created — on macOS the FSEvents stream starts on another thread — so the
+ * window this misses is a change that lands between the startup READ and the
+ * watch being armed a moment later, which is not a window an operator can act
+ * in. A watch the platform refuses outright (some network mounts) is warned
+ * about once, and the config read at startup simply stands.
+ *
+ * WHAT IS REBUILT. As little as possible, because rebuilding is not free: the
+ * collector is a detached process group with a warmup, and respawning one drops
+ * the metrics stream. So each part is keyed on the config fields it is actually
+ * built from — the collector on its argv and cadence, the tailer on its path, the
+ * drift probe on the recorded launch argv — and an unchanged key hands back the
+ * SAME instance, which the source reads as "leave this one alone" (see
+ * {@link LlamaLiveParts}). Everything else is rebuilt from the new config, so a
+ * command whose consent hash went missing stops being offered, and a config that
+ * failed to load takes every part down with it.
+ *
+ * Node-only: it stats, watches, spawns and executes. The source it feeds stays
+ * free of all of that.
+ */
+
+import { type FSWatcher, watch as nodeWatch, statSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import type { DriftProbe } from "../core/drift.js";
+import type { HostMetricsProvider } from "../core/host-metrics.js";
+import type { LlamaLiveParts, LogTailer, ServiceController } from "../core/llama-source.js";
+import type { Unsubscribe } from "../core/source.js";
+import type { ServiceAction } from "../core/types.js";
+import { createDriftProbe } from "./drift-probe.js";
+import { createHostCollector } from "./host-collector.js";
+import { createFileTailer, type LogPathConfig, resolveLogPath } from "./log-tailer.js";
+import { createServiceController, type ServiceControlCommands } from "./service-control.js";
+import {
+  consentDrift,
+  consentedControls,
+  hostCollectorConsented,
+  readStewardConfig,
+  type StewardConfig,
+  stewardConfigPath,
+} from "./steward-config.js";
+
+/**
+ * How long a burst of filesystem events is allowed to settle before the config
+ * is re-read.
+ *
+ * This is not a poll — nothing is scheduled until an event arrives — but it does
+ * two useful things when one does. A save is several events, and coalescing them
+ * costs one `stat` instead of three. More importantly, a writer that truncates
+ * and then writes (rather than renaming into place) is briefly holding a file
+ * that parses as malformed JSON, and reading it in that window would tear the
+ * collector down and build it straight back up.
+ */
+const SETTLE_MS = 60;
+
+/** How far up the tree the watch will climb looking for a directory that exists. */
+const MAX_ANCESTORS = 3;
+
+/**
+ * How many times a watch that dies may be re-armed before Steward stops trying.
+ *
+ * A watch the OS drops is worth replacing — one transient EMFILE should not
+ * cost the operator every later config change — but a watch that cannot stay up
+ * must fail honestly rather than re-arm forever, exactly as the host collector's
+ * respawn cap does. Past the cap the config read at startup simply stands, and
+ * the operator is told.
+ */
+const MAX_WATCH_LOSSES = 3;
+
+/** Something with a `close()`; a `fs.watch` handle satisfies it, as does a stub. */
+export interface Closable {
+  close(): void;
+}
+
+/**
+ * Watches `directory`, calling `onEvent` for changes to `filename` within it.
+ *
+ * `lost` says the watch itself has ENDED and delivered its last event — the OS
+ * dropped it, and the handle is already closed. It is a distinct signal because
+ * a dead watch is indistinguishable from a quiet directory from the outside,
+ * and a silently dead one means every later config change is missed.
+ */
+export type WatchDirectory = (
+  directory: string,
+  onEvent: (filename: string | null, lost: boolean) => void,
+) => Closable;
+
+export interface ConfigWiringOptions {
+  /** The artifact to follow. Defaults to {@link stewardConfigPath}. */
+  path?: string;
+  /** Reads and validates the artifact. Injected in tests; defaults to the real gate. */
+  read?: (path: string) => StewardConfig | null;
+  /** Spawns the host collector. Injected in tests, so none is ever spawned there. */
+  createCollector?: (command: string[], intervalMs: number) => HostMetricsProvider;
+  /** Builds the service controller. Injected in tests. */
+  createController?: (commands: ServiceControlCommands) => ServiceController;
+  /** Builds the launch-argv drift probe. Injected in tests. */
+  createProbe?: (launchArgv: string[]) => DriftProbe;
+  /** Opens a log tail. Injected in tests, so no real file is followed there. */
+  createTailer?: (path: string) => LogTailer;
+  /** Resolves the log path from the config, the env, and the convention. Injected in tests. */
+  resolveLog?: (config: LogPathConfig | null) => string | null;
+  /** Watches a directory. Injected in tests, which trigger refreshes by hand. */
+  watch?: WatchDirectory;
+  /** Defers the refresh so a burst of events costs one read. Injected in tests. */
+  settle?: (run: () => void) => Unsubscribe;
+  /** Sink for the "cannot watch" warning. Injected in tests; defaults to `console.warn`. */
+  warn?: (message: string) => void;
+}
+
+/**
+ * A live view of `steward.json`, expressed as the parts a
+ * {@link import("../core/llama-source.js").LlamaSource} is built from.
+ *
+ * One wiring belongs to one source. It is created with the config already read
+ * (so the source starts wired, not empty), and hands over ownership of
+ * everything it builds: the source closes the collector and the tailer it is
+ * holding, whether that happens at a swap or at its own `close()`. The wiring
+ * only ever CREATES, which is what keeps a single owner for a process group.
+ */
+export interface ConfigWiring {
+  /** The parts as of the last read — the source's constructor arguments. */
+  readonly parts: LlamaLiveParts;
+  /**
+   * Registers the source's `reconfigure` and starts watching. The returned
+   * unsubscribe stops the watcher and is called by the source's `close()`, so a
+   * source that is spent can never be handed a newly spawned collector.
+   */
+  rewire(apply: (parts: LlamaLiveParts) => void): Unsubscribe;
+}
+
+/**
+ * The cheap identity of a file: enough to say "nothing about this has changed"
+ * without opening it, and `null` when it is not there at all.
+ *
+ * Content is deliberately not hashed. The point of this gate is that the common
+ * case — a watch event that concerns some other file, or the second and third
+ * events of one save — costs a single `stat` and stops there.
+ *
+ * The tuple is wider than a plain mtime+size for two reasons. `ctime` is what
+ * catches a `chmod o+w` or a `chown`, which change neither of those and are
+ * precisely the edits the security gate exists to refuse; the mode and the
+ * owner ride along beside it because they are what the refusal is ABOUT, and a
+ * filesystem with a coarse `ctime` should not be able to hide them. And the
+ * timestamps are read in nanoseconds rather than milliseconds, which closes the
+ * one blind spot a millisecond tuple has — two writes of equal size, to the
+ * same inode, inside the same millisecond.
+ */
+function readIdentity(path: string): string | null {
+  try {
+    const stat = statSync(path, { bigint: true });
+    return [
+      stat.dev,
+      stat.ino,
+      stat.mtimeNs,
+      stat.ctimeNs,
+      stat.size,
+      stat.mode,
+      stat.uid,
+      stat.gid,
+    ].join(":");
+  } catch {
+    return null;
+  }
+}
+
+/** True when two argvs are the same command, token for token. */
+function sameCommand(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((token, index) => token === b[index]);
+}
+
+/** The control actions, in the order the dashboard renders them. */
+const CONTROL_ACTIONS: readonly ServiceAction[] = ["start", "stop", "restart"];
+
+/** True when two consented control sets declare the same commands for the same actions. */
+function sameControls(a: ServiceControlCommands, b: ServiceControlCommands): boolean {
+  return CONTROL_ACTIONS.every((action) => {
+    const left = a[action];
+    const right = b[action];
+    if (left === undefined || right === undefined) return left === right;
+    return sameCommand(left, right);
+  });
+}
+
+/** The default directory watch: non-persistent, so it never holds the process open. */
+function watchDirectory(
+  directory: string,
+  onEvent: (filename: string | null, lost: boolean) => void,
+): Closable {
+  const watcher: FSWatcher = nodeWatch(directory, { persistent: false }, (_event, filename) =>
+    onEvent(typeof filename === "string" ? filename : null, false),
+  );
+  // A watch that fails — its directory removed, or a transient error on a
+  // filesystem that cannot sustain one — emits an error rather than throwing,
+  // and is finished afterwards. Reported as a LOSS, so the wiring replaces it
+  // instead of holding a closed handle and going quietly deaf.
+  watcher.on("error", () => {
+    watcher.close();
+    onEvent(null, true);
+  });
+  return watcher;
+}
+
+/** The default settle: one unref'd timer, armed by an event and never by a clock. */
+function settleWithTimer(run: () => void): Unsubscribe {
+  const timer = setTimeout(run, SETTLE_MS);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+}
+
+/**
+ * The deepest existing directory at or above `directory`, within
+ * {@link MAX_ANCESTORS} steps, or `null` when none of them exists.
+ *
+ * The climb is bounded because the point of it is a config directory that has
+ * not been created yet (`~/.config/steward`), not a home directory that is
+ * missing — and every step up widens the watch to files that have nothing to do
+ * with Steward.
+ */
+function nearestExistingDirectory(directory: string): string | null {
+  let current = directory;
+  for (let step = 0; step <= MAX_ANCESTORS; step += 1) {
+    try {
+      if (statSync(current).isDirectory()) return current;
+    } catch {
+      // Not there — try its parent.
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+export function createConfigWiring(options: ConfigWiringOptions = {}): ConfigWiring {
+  const path = resolvePath(options.path ?? stewardConfigPath());
+  const read = options.read ?? ((target: string) => readStewardConfig({ path: target }));
+  const createCollector = options.createCollector ?? createHostCollector;
+  const createController = options.createController ?? createServiceController;
+  const createProbe =
+    options.createProbe ?? ((launchArgv: string[]) => createDriftProbe({ launchArgv }));
+  const createTailer =
+    options.createTailer ?? ((target: string) => createFileTailer({ path: target }));
+  const resolveLog =
+    options.resolveLog ?? ((config: LogPathConfig | null) => resolveLogPath({ config }));
+  const watch = options.watch ?? watchDirectory;
+  const settle = options.settle ?? settleWithTimer;
+  const warn = options.warn ?? ((message: string) => console.warn(message));
+
+  /** What each owned part was built from, so an unchanged key is not rebuilt. */
+  let collector: { command: string[]; intervalMs: number; provider: HostMetricsProvider } | null =
+    null;
+  let tailer: { path: string; instance: LogTailer } | null = null;
+  let probe: { launchArgv: string[]; instance: DriftProbe } | null = null;
+  let controller: { commands: ServiceControlCommands; instance: ServiceController } | null = null;
+
+  /**
+   * The parts for one config, reusing every running part whose inputs are
+   * unchanged.
+   *
+   * A part dropped here is NOT closed here: it is left out of the returned
+   * parts, and the source closes what it was holding when it takes them. One
+   * owner, one close — the alternative (closing on the way out AND on the swap)
+   * is how a live collector gets killed by a config edit that did not touch it.
+   */
+  function build(config: StewardConfig | null): LlamaLiveParts {
+    const parts: LlamaLiveParts = {};
+
+    // Topology is declared, not measured, so it is known as soon as the config
+    // is read — independent of whether the collector below was ever consented.
+    // It used to ride along with `host`, which meant a config declaring
+    // `discrete` was ignored until its collector was approved, and the dashboard
+    // drew the wrong gauge set in the meantime.
+    if (config !== null) parts.topology = config.memoryTopology;
+
+    // The collector: keyed on its exact argv and its declared cadence, the two
+    // things the running child was started with. Consent is re-checked here
+    // rather than trusted from last time, so a command whose hash disappeared
+    // from the artifact stops being run instead of riding on the old approval.
+    if (config !== null && hostCollectorConsented(config)) {
+      const { command, intervalMs } = config.hostCollector;
+      if (
+        collector === null ||
+        collector.intervalMs !== intervalMs ||
+        !sameCommand(collector.command, command)
+      ) {
+        collector = {
+          command: [...command],
+          intervalMs,
+          provider: createCollector(command, intervalMs),
+        };
+      }
+      parts.host = {
+        provider: collector.provider,
+        // Topology and the staleness horizon are read from the CURRENT config
+        // even when the child is reused: they are facts about the machine and
+        // the cadence, not state the collector holds.
+        topology: config.memoryTopology,
+        // Stale past 3× the collector's declared cadence — the readings drop to
+        // n/a rather than being held (maintainer decision, plan H3).
+        staleMs: 3 * intervalMs,
+      };
+    } else {
+      collector = null;
+    }
+
+    // Control: per-action, and only what the operator approved. A rewritten
+    // command drops out of this set until its new hash is consented to, which is
+    // the security gate doing its job — and `consentDrift` below is what stops
+    // that looking like a machine that was never set up.
+    const commands = config === null ? {} : consentedControls(config);
+    if (Object.keys(commands).length === 0) {
+      controller = null;
+    } else {
+      if (controller === null || !sameControls(controller.commands, commands)) {
+        controller = { commands, instance: createController(commands) };
+      }
+      parts.control = controller.instance;
+    }
+
+    // The drift baseline: keyed on the recorded argv, because that is all the
+    // probe is built from. Reusing it keeps its per-pid cache, so an unrelated
+    // config edit does not cost a `ps` per snapshot until it warms again.
+    const launchArgv = config?.llama?.launchArgv ?? null;
+    if (launchArgv === null) {
+      probe = null;
+    } else {
+      if (probe === null || !sameCommand(probe.launchArgv, launchArgv)) {
+        probe = { launchArgv: [...launchArgv], instance: createProbe(launchArgv) };
+      }
+      parts.probeDrift = probe.instance;
+    }
+
+    if (config !== null) parts.consentDrift = consentDrift(config);
+
+    // The log path is not config-only: `STEWARD_LOG_FILE` and the platform
+    // convention still resolve without an artifact, so losing the config does
+    // not necessarily lose the console. The tailer is keyed on the resolved
+    // path, so a config that changes anything else leaves the tail — and the
+    // slot occupancy folded out of it — completely untouched.
+    const logPath = resolveLog(config?.log ?? null);
+    if (logPath === null) {
+      tailer = null;
+    } else {
+      if (tailer === null || tailer.path !== logPath) {
+        tailer = { path: logPath, instance: createTailer(logPath) };
+      }
+      parts.logTail = tailer.instance;
+    }
+
+    return parts;
+  }
+
+  let identity = readIdentity(path);
+  let parts = build(identity === null ? null : read(path));
+
+  let sink: ((next: LlamaLiveParts) => void) | null = null;
+  let watcher: Closable | null = null;
+  let watching: string | null = null;
+  let cancelSettle: Unsubscribe | null = null;
+  let stopped = false;
+  /** Watches the OS has dropped on us, capped by {@link MAX_WATCH_LOSSES}. */
+  let losses = 0;
+
+  /**
+   * One re-read, gated on the file's identity.
+   *
+   * The gate is the reason a chatty watcher is cheap, and the reason an event
+   * that concerns some other file in the directory costs a `stat` and nothing
+   * else. Past it, a config that is absent, refused (foreign owner,
+   * world-writable) or malformed all arrive here as `null` — and are treated
+   * identically, because in all three cases Steward has no artifact it is
+   * entitled to act on and must stop acting on the last one.
+   */
+  function refresh(): void {
+    if (stopped) return;
+    const next = readIdentity(path);
+    if (next === identity) return;
+    identity = next;
+    parts = build(next === null ? null : read(path));
+    sink?.(parts);
+  }
+
+  /** Arms (or re-arms) the watch on the deepest directory that exists today. */
+  function arm(): void {
+    if (stopped) return;
+    const directory = nearestExistingDirectory(dirname(path));
+    if (directory === null) {
+      warn(`[steward] cannot watch ${path} for changes: no directory above it exists`);
+      return;
+    }
+    if (watcher !== null && watching === directory) return;
+    watcher?.close();
+    watcher = null;
+    watching = null;
+    try {
+      watcher = watch(directory, (filename, lost) => onEvent(directory, filename, lost));
+      watching = directory;
+    } catch (error) {
+      // A platform or filesystem that cannot watch (some network mounts) is a
+      // degrade, not a failure: the config read at startup stands, and the
+      // operator is told why a later `/steward_initialize` needs a restart.
+      const detail = error instanceof Error ? error.message : String(error);
+      warn(`[steward] cannot watch ${path} for changes (${detail}); a change needs a restart`);
+    }
+  }
+
+  function onEvent(directory: string, filename: string | null, lost = false): void {
+    if (stopped) return;
+    if (lost) {
+      // The handle is already closed and will send nothing more. Dropping the
+      // reference is what lets `arm` replace it — a watch whose directory still
+      // exists would otherwise look like one that is already in the right
+      // place, and Steward would stop noticing config changes without a word.
+      watcher = null;
+      watching = null;
+      losses += 1;
+      if (losses > MAX_WATCH_LOSSES) {
+        warn(
+          `[steward] gave up watching ${path} after ${losses} dropped watches; ` +
+            "a config change now needs a restart",
+        );
+        return;
+      }
+    }
+    // Re-checked on every event, because an event is also how we learn that the
+    // shape of the tree changed: the config's directory may have just been
+    // created under the ancestor we settled for, or removed out from under us.
+    // It costs one `stat` and is a no-op while the right directory is watched.
+    arm();
+    // Inside the config's own directory, only the config's own name is our news
+    // — a `filename` we were not given (some platforms omit it, and the lost
+    // watch above reports none) is treated as ours.
+    if (directory === dirname(path) && filename !== null) {
+      if (resolvePath(directory, filename) !== path) return;
+    }
+    cancelSettle?.();
+    cancelSettle = settle(() => {
+      cancelSettle = null;
+      refresh();
+    });
+  }
+
+  return {
+    get parts(): LlamaLiveParts {
+      return parts;
+    },
+
+    rewire(apply: (next: LlamaLiveParts) => void): Unsubscribe {
+      sink = apply;
+      arm();
+      return () => {
+        stopped = true;
+        sink = null;
+        cancelSettle?.();
+        cancelSettle = null;
+        watcher?.close();
+        watcher = null;
+        watching = null;
+      };
+    },
+  };
+}

package/server/drift-probe.ts

@@ -0,0 +1,150 @@
+/**
+ * Re-validates, every snapshot, that `llama-server` is still running with the
+ * flags `steward.json` says it was launched with — the Node body behind
+ * {@link DriftProbe}.
+ *
+ * It is handed the pid the snapshot ALREADY resolved for the SERVICE block and
+ * reads that process's live command line with `ps`. Taking the pid rather than
+ * a host and port is deliberate: re-running `lsof` here would cost a second
+ * ~60 ms subprocess on every poll, and — because the two lookups would land at
+ * different instants — a restart could leave the SERVICE block and the drift
+ * notice describing two different processes. One lookup, one process, one story.
+ * The comparison itself is pure and lives in `core/drift.ts`, so what counts as
+ * drift can be proven without a real server.
+ *
+ * Two properties matter more than anything this module does:
+ *
+ *   - It NEVER throws and never reports a verdict it did not reach. No pid, no
+ *     `ps`, a permission error, an empty or truncated line — all of them are
+ *     `unknown`, which renders nothing. Fabricating "clean" would restore the
+ *     exact false all-clear this check exists to remove; fabricating "drifted"
+ *     would nag a machine that is configured correctly, which spends the same
+ *     trust.
+ *   - It is cheap enough to run on every poll, without ever going quiet. The
+ *     command line of a process cannot change while it lives, so a SUCCESSFUL
+ *     read is cached and serves every later snapshot; a new (or vanished) pid
+ *     drops it. A FAILED read is never cached as an answer — it backs off and is
+ *     retried, because a check that stopped running while still rendering
+ *     nothing is indistinguishable from a machine that is fine.
+ *
+ * macOS/Linux only, like the service probe: a platform without `ps` simply
+ * reports `unknown`, which is the honest answer.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { DriftProbe, LaunchDrift } from "../core/drift.js";
+import { diffLaunchArgv, unknownLaunchDrift } from "../core/drift.js";
+
+const run = promisify(execFile);
+
+/** No single probe command may hang the metrics poll. */
+const PROBE_TIMEOUT_MS = 1500;
+
+/**
+ * How many polls a failed read waits before it is retried, at most. A read that
+ * keeps failing (a `ps` that is not there, a process we may not inspect) backs
+ * off rather than shelling out every 1.6 s — but it NEVER gives up, because a
+ * check that has quietly stopped running looks exactly like a compliant machine.
+ */
+const MAX_RETRY_SKIP = 8;
+
+/**
+ * Reads one process's live command line — the argv joined on single spaces, as
+ * `ps` prints it — or `null` when it cannot be read. Injected in tests, so the
+ * probe is proven against a fake process list rather than this machine's real
+ * `llama-server`.
+ */
+export type ArgvReader = (pid: number) => Promise<string | null>;
+
+export interface DriftProbeOptions {
+  /** The argv `/steward_initialize` recorded, from `steward.json`'s `llama` block. */
+  launchArgv: readonly string[];
+  /** Overrides the `ps` command-line read. */
+  readArgv?: ArgvReader;
+}
+
+/**
+ * One process's full command line, or `null`.
+ *
+ * `-ww` is not decoration. `ps` truncates to the display width, and while both
+ * macOS and Linux hand back the whole line when stdout is a pipe (verified on
+ * this machine: a 10 KB argv came back whole), `-ww` asks for unlimited width
+ * explicitly rather than relying on that. Anything the flag fails to prevent is
+ * still caught downstream, where a line cut mid-token is reported `unknown`.
+ *
+ * `args=` (rather than `command=`) is the portable spelling of "the argv" on
+ * both platforms; the trailing `=` drops the header row.
+ */
+async function processArgv(pid: number): Promise<string | null> {
+  try {
+    const { stdout } = await run("ps", ["-ww", "-o", "args=", "-p", String(pid)], {
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    // A process that exited between the lsof and the ps prints nothing and
+    // exits non-zero; a header-only read is empty too. Either way: no line.
+    const line = stdout.split("\n")[0]?.trim() ?? "";
+    return line === "" ? null : line;
+  } catch {
+    // ps missing, the pid gone (exit 1), a permission error, or timed out.
+    return null;
+  }
+}
+
+/**
+ * A drift probe over one recorded argv, with a per-pid cache of the live
+ * command line. Build it only when `steward.json` carries a `llama` block: with
+ * nothing recorded there is nothing to compare against, and the caller should
+ * omit the probe entirely rather than pass an empty argv.
+ */
+export function createDriftProbe(options: DriftProbeOptions): DriftProbe {
+  const launchArgv = [...options.launchArgv];
+  const readArgv = options.readArgv ?? processArgv;
+  /**
+   * The command line of the pid we last read SUCCESSFULLY, so `ps` runs once
+   * per process. Only successes are cached: a failed read is a gap in what we
+   * know, and caching it would turn one timed-out `ps` into a check that never
+   * runs again for that process — silently, since `unknown` renders nothing.
+   */
+  let cache: { pid: number; argv: string } | null = null;
+  /** Consecutive failed reads of the current pid, and the polls left to skip. */
+  let failure: { pid: number; consecutive: number; skip: number } | null = null;
+
+  return async (pid: number | null): Promise<LaunchDrift> => {
+    if (pid === null) {
+      // A pid we never resolved is not evidence about the flags. Both caches go
+      // with it: a pid is reused, so the next one is a different process.
+      cache = null;
+      failure = null;
+      return unknownLaunchDrift("the listening process could not be identified");
+    }
+    if (cache !== null && cache.pid !== pid) cache = null;
+    if (failure !== null && failure.pid !== pid) failure = null;
+
+    if (cache !== null) return diffLaunchArgv(launchArgv, cache.argv);
+    if (failure !== null && failure.skip > 0) {
+      // Backing off, not giving up: the read is retried once the skips run out.
+      failure.skip -= 1;
+      return unknownLaunchDrift("the launch command line could not be read");
+    }
+
+    let argv: string | null;
+    try {
+      argv = await readArgv(pid);
+    } catch {
+      argv = null;
+    }
+    if (argv === null) {
+      // A timed-out `ps`, an EAGAIN, or the window between `lsof` finding the
+      // port and the process being inspectable while it starts up: all
+      // transient, all worth another look on a later poll.
+      const consecutive = (failure?.consecutive ?? 0) + 1;
+      failure = { pid, consecutive, skip: Math.min(consecutive - 1, MAX_RETRY_SKIP) };
+      return unknownLaunchDrift("the launch command line could not be read");
+    }
+
+    failure = null;
+    cache = { pid, argv };
+    return diffLaunchArgv(launchArgv, argv);
+  };
+}