viewable-one 0.0.0-stage → 0.12.2

package/lib/multiwatch.mjs

@@ -0,0 +1,428 @@
+// ONE DAEMON, EVERY REGISTERED FOLDER.
+//
+// The runner was written to watch the folder it was started in, because it
+// was started by a person standing in that folder. A LaunchAgent is started
+// by launchd at login, standing nowhere, so something has to say which
+// folders it is for - the registry (lib/registry.mjs) - and the watcher has
+// to hold all of them at once.
+//
+// WHAT DOES NOT CHANGE, and this is the part that matters: each folder gets
+// the SAME `watch()` it always got, writing its own mark file in its own
+// `.glytch/inbox/spawn/.runner.json`. The app's contract is per folder and
+// it is untouched - an app that has never heard of this module reads exactly
+// the file it read before. Nothing about a session, a claim, a receipt or a
+// budget becomes machine-wide.
+//
+// ONE RUNNER ID FOR THE PROCESS (#813). Every folder used to get its own, but
+// one `register` names every folder with the id of whichever folder sent it,
+// so the rows' runner id flipped between them. The app now matches the
+// runner's presence on its push topic against that id, so it is one id.
+//
+// A FOLDER THAT HAS DISAPPEARED IS ONE LOG LINE, NEVER AN EXIT. A machine-
+// wide daemon meets deleted and moved project folders as an ordinary event,
+// and quitting over one would stop the other five.
+//
+// PM_BOARD_ROOT is NOT handled here: with it set, `glytch runner watch` hands
+// straight over to spawn-runner.mjs, so that path is exactly today's, down to
+// the same process.
+//
+// THE REGISTRY IS READ AGAIN WHILE THE DAEMON RUNS (2026-09-06, ruling
+// B). The first test pass of brief 19 found the install-once promise broken
+// for the SECOND project on a machine: `glytch init` there added the folder
+// to folders.json and said "folder registered", `glytch doctor` said "the
+// daemon watches this folder", and nothing did - this module read the
+// registry once at start, so the new folder needed `launchctl kickstart -k`
+// by hand. Option A, having `init` restart the daemon, was rejected: a
+// restart kills whatever session is running under it in another project. So
+// the daemon watches the registry FILE, and a folder registered while it runs
+// gets its sync and its watcher without anything being restarted.
+
+import { makeRunnerHealth } from "./runner-health.mjs";
+import { watch as fsWatch } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { makeAgentProbe } from "./detect.mjs";
+import { platformMark } from "./platform.mjs";
+import { ensureViewableFolder } from "./viewableFolder.mjs";
+import { readRegistryChecked, registryPath } from "./registry.mjs";
+import { watch, newRunnerId } from "./runner.mjs";
+import { RUNNER_BEAT_MS } from "./spawn.mjs";
+import { makeHeartbeatHub, makeRegistrar, REGISTER_REFRESH_MS } from "./runnerPace.mjs";
+import { beatBaseMs, makeRunnerRealtime } from "./runnerRealtime.mjs";
+import { sweepAll } from "./sweep.mjs";
+import { syncFolder } from "./sync.mjs";
+import { makeUpdateChecker, packageVersion } from "./update.mjs";
+
+export const SWEEP_INTERVAL_MS = 86_400_000;
+/** How often the registry is re-read when fs.watch tells us nothing. The
+ * floor, not the mechanism: fs.watch answers in milliseconds when it fires at
+ * all, and this is what catches the cases where it does not - a network home
+ * directory, an editor that swaps the file in a way the watch misses, a
+ * platform that drops the event. A minute is invisible to a person typing
+ * `viewable init` and then switching to the app. */
+export const REGISTRY_POLL_MS = 60_000;
+
+const isDir = async (path) => {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/** Watch every registered folder until `signal` aborts.
+ *
+ * Returns {watched, missing} after signal-driven shutdown and after every
+ * folder's watch has ended. An empty registry still waits for new folders. */
+export async function watchRegistered({
+  env = process.env,
+  settings,
+  signal,
+  log = () => {},
+  folders,
+  sweep = sweepAll,
+  sync = syncFolder,
+  updater = makeUpdateChecker({ log }),
+  // WHAT CODING AGENTS THIS MACHINE HAS (brief 19 stage 2). Same shape as
+  // `updater`: a cache with its own clock, so the liveness beat never waits
+  // on `claude --version`. Injected for the tests, which must not spawn three
+  // child processes to find out which folders got watched.
+  probe = makeAgentProbe({ log }),
+  // WHAT MACHINE THIS IS (brief 21 session 5, ruling 3A). Injected for
+  // the same reason `probe` is, and for one more: the mark's contents are
+  // asserted verbatim in the tests, and a key whose value is whichever
+  // machine the suite happens to be running on would make those assertions
+  // say something different on the windows-latest runner.
+  platform = platformMark(),
+  sweepIntervalMs = SWEEP_INTERVAL_MS,
+  registryPollMs = REGISTRY_POLL_MS,
+  // The one seam the tests use. `watch()` polls until it is aborted and does
+  // real filesystem and process work per pass; what this module has to be
+  // held to is WHICH folders it starts one for, with what settings - so the
+  // watcher itself is injectable and the default is the real one.
+  watchOne = watch,
+  // THE PUSH CHANNEL (#813), one per process. Injected for the tests, which
+  // pass a fake, or `() => null` for none (every 10 s, as before).
+  makeRealtime = makeRunnerRealtime,
+} = {}) {
+  // An injected list is the whole list: a caller that says which folders to
+  // watch is not asking the registry anything, so the live re-read below
+  // stands down for it. Nothing in the package passes this; the tests do.
+  const pinned = folders !== undefined;
+  // The Glytch folder (viewableFolder.mjs) is made and registered first, so a
+  // computer with no folder linked yet still has one to work in.
+  if (!pinned) await ensureViewableFolder(env, log);
+  // When the registry file was last written, read before the list is: a
+  // rewrite that keeps the same folders is `glytch init` asking for a beat.
+  const registryStamp = async () => (await stat(registryPath(env)).catch(() => null))?.mtimeMs ?? null;
+  let stampSeen = pinned ? null : await registryStamp();
+  const registered = folders ?? (await readRegistryChecked(env)).folders;
+  const watched = [];
+  const missing = [];
+  const first = [];
+  for (const folder of registered) {
+    if (await isDir(folder)) first.push(folder);
+    else missing.push(folder);
+  }
+  for (const gone of missing) log(`skipping ${gone}: the folder no longer exists`);
+
+  if (first.length === 0) {
+    log("no folders registered - run `viewable init` in a project folder first.");
+  }
+
+  // SYNC ON EVERY START (ruling 5), and on every folder that joins later.
+  // Put back .mcp.json, the opencode registration, the registry entry and the
+  // login daemon's captured PATH before the first session of the day rather
+  // than after it fails.
+  //
+  // daemon:true is load-bearing (2026-09-06 finding): THIS process is the
+  // login daemon the OS is holding, so if the sync's fourth row ever
+  // restarted it from in here, it would stop the very process running this
+  // loop mid-sync. `daemon:true` keeps that row read-only for this one
+  // caller; `glytch init` and `glytch doctor`, which are never the daemon,
+  // still restart a stopped one.
+  //
+  // 2026-09-07, brief 21 session 4: the row now goes through
+  // lib/logindaemon.mjs, and the guard covers all three implementations
+  // rather than launchd alone - `launchctl load`, `schtasks /run` and
+  // `systemctl --user enable --now` would each restart this process.
+  const syncOne = async (folder) => {
+    try {
+      for (const r of await sync(folder, { env, daemon: true })) {
+        if (!r.ok) log(`[${folder}] ${r.label}: ${r.detail}`);
+      }
+    } catch (error) {
+      log(`[${folder}] sync failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  for (const folder of first) await syncOne(folder);
+
+  // THE SWEEP, on start and once a day. Both are the same call; nothing about
+  // it is a schedule the app can see.
+  const runSweep = async () => {
+    try {
+      await sweep({ env, log });
+    } catch (error) {
+      log(`sweep failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+  await runSweep();
+  const sweeping = setInterval(() => void runSweep(), sweepIntervalMs);
+  sweeping.unref?.();
+
+  // AT START, per the brief, and every five minutes after: the probe's own
+  // timer does the second half, and this await does the first, so the very
+  // first mark a person sees already carries the `agents` block rather than
+  // arriving bare and filling in a beat later.
+  await probe.once();
+
+  // The mark file gains `version`, `updateAvailable`, `agents` and (brief 21
+  // session 5, ruling 3A) `platform` here, and only here: `watch()`
+  // writes whatever `markExtra()` returns beside `at`, and both caches answer
+  // from memory so the liveness beat never waits on npm or on a child
+  // process. `platform` is the machine the SESSION will run on, which is the
+  // only thing the app can use to pick the words a spawn prompt carries for
+  // starting a detached dev server - the browser may be on another box
+  // entirely (lib/platform.mjs says why it is not `navigator`).
+  const health = makeRunnerHealth({ env, version: updater.state?.().version ?? packageVersion() });
+  const markExtra = () => ({ ...platform, ...updater.mark(), ...probe.mark(), ...health.mark() });
+
+  // ONE REGISTER AND ONE HEARTBEAT FOR THE WHOLE PROCESS (ticket e8,
+  // 2026-10-03; #616, 2026-10-16). Every folder's beat registers the whole
+  // folder list and heartbeats its own folder, so five folders sent the same
+  // register five times and five heartbeats every ten seconds, and tripped
+  // Cloudflare's per-IP rate limit. The folders share one registrar, which
+  // repeats an unchanged list every 5 minutes, and one heartbeat hub, which
+  // sends one heartbeat for all of them per beat (lib/runnerPace.mjs).
+  const beatMs = settings?.beatMs ?? RUNNER_BEAT_MS;
+  const registrar = makeRegistrar({ ttlMs: REGISTER_REFRESH_MS, failureTtlMs: 0.9 * beatMs });
+  const runnerId = settings?.runnerId ?? newRunnerId();
+  // PUSH (#813): joined, every folder beats every 5 minutes and the hub's
+  // shared answer lives as long, so the folders still share one heartbeat.
+  const realtime = makeRealtime({
+    runnerId,
+    version: updater.state?.().version ?? packageVersion(),
+    runnerApi: settings?.runnerApi,
+    env,
+    fetchImpl: settings?.fetchImpl,
+    log,
+  });
+  const heartbeats = makeHeartbeatHub({
+    ttlMs: () => 0.9 * beatBaseMs(realtime, beatMs, settings?.pushBeatMs),
+    failureTtlMs: 0.9 * beatMs,
+  });
+  realtime?.start();
+  // A BEAT ON REQUEST (#813 review). `glytch init` in a folder this daemon
+  // already watches leaves it running and waits for a beat that came after
+  // it started (runner-health.mjs); joined, the next one could be 5 minutes
+  // away. init rewrites the registry instead, and every watcher beats once,
+  // sharing one heartbeat (one `at` for all of them).
+  const beatAsks = new Set();
+  const beatRequests = { subscribe: (fn) => { beatAsks.add(fn); return () => beatAsks.delete(fn); } };
+  const askBeat = () => {
+    const at = Date.now();
+    for (const fn of [...beatAsks]) fn(at);
+  };
+
+  // ONE ENTRY PER FOLDER, AND NEVER TWO. `running` is what makes "never watch
+  // a folder twice" a fact rather than an intention: every start goes through
+  // startFolder, and startFolder returns at once if the folder is already in
+  // here. A dead watcher retries after one ordinary heartbeat, independently
+  // of registry polling or push availability. The delay prevents a broken
+  // folder from spinning; removal and shutdown cancel it.
+  const running = new Map();
+  // Woken whenever the set of watchers changes, so the wait at the bottom
+  // notices a folder that joined after it started waiting.
+  let wake;
+  let fireWake = () => {};
+  const armWake = () => {
+    wake = new Promise((resolve) => {
+      fireWake = resolve;
+    });
+  };
+  armWake();
+  const bump = () => {
+    const fire = fireWake;
+    armWake();
+    fire();
+  };
+  signal?.addEventListener("abort", bump, { once: true });
+
+  const startFolder = (folder) => {
+    if (running.has(folder)) return;
+    if (signal?.aborted) return;
+    // A STOP THAT IS A REAL STOP. `watch()`'s only way out is its signal (see
+    // its doc comment: "there is no other way out, because a runner that
+    // stops itself on a condition is a runner that starts itself on one"), so
+    // each folder gets its own AbortController chained to the daemon's. That
+    // is a clean stop and not a leak: the watcher drains the sessions it
+    // already started, writes their receipts, and clears the folder's mark
+    // file on the way out, exactly as Ctrl-C does today.
+    const controller = new AbortController();
+    const onParentAbort = () => controller.abort();
+    signal?.addEventListener("abort", onParentAbort, { once: true });
+    const entry = { controller, done: false, leaving: false };
+    let started;
+    try {
+      started = watchOne(folder, { ...settings, runnerId, realtime, onHealthy: (path) => health.beat(path), markExtra, registrar, heartbeats, beatRequests, refreshAgents: () => probe.once() }, {
+        signal: controller.signal,
+        log: (line) => log(`[${folder}] ${line}`),
+      });
+    } catch (error) {
+      started = Promise.reject(error);
+    }
+    entry.promise = Promise.resolve(started)
+      .catch((error) => {
+        // One folder's watcher dying must not take the others down: a board
+        // root that becomes unreadable is exactly the case this daemon
+        // exists to survive.
+        log(`[${folder}] watcher stopped: ${error instanceof Error ? error.message : String(error)}`);
+      })
+      .finally(() => {
+        entry.done = true;
+        signal?.removeEventListener("abort", onParentAbort);
+        if (entry.leaving && running.get(folder) === entry) running.delete(folder);
+        else if (!signal?.aborted) {
+          entry.retry = setTimeout(() => {
+            if (entry.leaving || signal?.aborted || running.get(folder) !== entry) return;
+            running.delete(folder);
+            startFolder(folder);
+          }, beatMs);
+          entry.retry.unref?.();
+        }
+        bump();
+      });
+    running.set(folder, entry);
+    if (!watched.includes(folder)) watched.push(folder);
+    bump();
+  };
+
+  for (const folder of first) startFolder(folder);
+
+  // THE REGISTRY, RE-READ. Everything below exists so that `glytch init` in a
+  // second project is watched without a restart (2026-09-06, ruling B).
+  const announcedMissing = new Set(missing); // logged once each, not once a minute
+  let complained = false;
+  let refreshing = false;
+  let refreshAgain = false;
+  const refresh = async () => {
+    if (pinned) return;
+    if (refreshing) {
+      refreshAgain = true;
+      return;
+    }
+    refreshing = true;
+    try {
+      do {
+        refreshAgain = false;
+        const stamp = await registryStamp();
+        const rewritten = stamp !== null && stamp !== stampSeen;
+        stampSeen = stamp;
+        const { folders: now, ok } = await readRegistryChecked(env);
+        if (!ok) {
+          // A REGISTRY WE CANNOT READ IS NOT NEWS. Half-written, hand-edited
+          // into invalid JSON, briefly absent: none of those mean the folders
+          // were unregistered, and acting on the empty list they parse to
+          // would stop every watcher on the machine. Keep the last good list,
+          // say so once, and let the next good read speak.
+          if (!complained) {
+            complained = true;
+            log(`${registryPath(env)} could not be read as a folder list - keeping the folders already watched`);
+          }
+          continue;
+        }
+        complained = false;
+        const wanted = new Set(now);
+        for (const [folder, entry] of running) {
+          if (wanted.has(folder) || entry.leaving) continue;
+          entry.leaving = true;
+          clearTimeout(entry.retry);
+          if (entry.done) running.delete(folder);
+          log(`${folder} left the registry - stopping its watcher`);
+          entry.controller.abort();
+        }
+        for (const folder of now) {
+          if (running.has(folder)) continue;
+          if (!(await isDir(folder))) {
+            if (!announcedMissing.has(folder)) {
+              announcedMissing.add(folder);
+              missing.push(folder);
+              log(`skipping ${folder}: the folder no longer exists`);
+            }
+            continue;
+          }
+          announcedMissing.delete(folder);
+          log(`${folder} joined the registry - syncing and watching it`);
+          await syncOne(folder);
+          startFolder(folder);
+        }
+        if (rewritten) askBeat();
+      } while (refreshAgain);
+    } catch (error) {
+      // Never an exit. The poll comes round again in a minute.
+      log(`re-reading the registry failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      refreshing = false;
+    }
+  };
+
+  // BOTH THE FILE AND ITS DIRECTORY. `folders.json` is written by
+  // writeFileAtomic, which renames a temp file over it, so the inode a watch
+  // on the file is holding is not the one the next read opens - the file
+  // watch sees the first write and then nothing. The directory watch sees the
+  // rename. Neither is trusted: setInterval below is the floor, and a
+  // platform where fs.watch does nothing at all still picks a new folder up
+  // within registryPollMs.
+  const regPath = registryPath(env);
+  const regName = basename(regPath);
+  const fsWatchers = [];
+  const attach = (target, onlyRegistry) => {
+    try {
+      const w = fsWatch(target, (_event, filename) => {
+        if (onlyRegistry && filename && basename(String(filename)) !== regName) return;
+        void refresh();
+      });
+      w.on("error", () => {}); // a dead watch is not an exit; the poll covers it
+      w.unref?.();
+      fsWatchers.push(w);
+    } catch {
+      // The file may not exist yet, the directory may not be watchable: the
+      // poll is the answer to both.
+    }
+  };
+  if (!pinned) {
+    attach(regPath, false);
+    attach(dirname(regPath), true);
+  }
+  const polling = setInterval(() => void refresh(), registryPollMs);
+  polling.unref?.();
+
+  // Registry watches, polling and wake promises are unref'd or bare. Keep
+  // the daemon alive even before its first folder or after its last watcher.
+  const keepAlive = setInterval(() => {}, 2 ** 30);
+  try {
+    // Wait for abort, then drain every watcher. Until then an empty set must
+    // still wait for registry changes rather than ending the daemon.
+    for (;;) {
+      const pending = [];
+      for (const entry of running.values()) if (!entry.done) pending.push(entry.promise);
+      if (signal?.aborted && pending.length === 0) break;
+      await Promise.race([...pending, wake]);
+    }
+  } finally {
+    clearInterval(keepAlive);
+    for (const entry of running.values()) clearTimeout(entry.retry);
+    await realtime?.close();
+    signal?.removeEventListener("abort", bump);
+    clearInterval(sweeping);
+    clearInterval(polling);
+    for (const w of fsWatchers) {
+      try {
+        w.close();
+      } catch {
+        // closing twice, or after an error, is not a failure worth a line
+      }
+    }
+  }
+  return { watched, missing };
+}