@monster-orange/den 0.2.2 → 0.2.4

package/src/shared/environment-manager/service-runner.ts

@@ -27,6 +27,15 @@ import {
   shellQuote,
 } from "../terminal/tabs.js";
 import { readCatalog } from "./catalog.js";
+import { getSecretsProvider } from "../secrets/index.js";
+import {
+  assertSecretEnvSpec,
+  resolveSecretEnv,
+  secretEnvKeys,
+  type SecretEnvSpec,
+} from "../secrets/secret-env.js";
+import type { SecretsProvider } from "../secrets/types.js";
+import { composeCommands } from "../stacks/manifest-commands.js";
 import { buildServiceEnv } from "./service-env.js";
 import {
   devOpContainerNames,
@@ -35,6 +44,8 @@ import {
   inspectOpctlContainer,
   isOpctlAvailable,
   listRunningOpctlContainers,
+  listRunningOpctlContainersAsync,
+  isOpctlAvailableAsync,
 } from "./opctl.js";
 import {
   getActiveWorkspace,
@@ -348,6 +359,24 @@ export function activeDaemonOwners(
   return (record?.workspaces ?? []).filter((w) => active.has(w));
 }
 
+/** Whether workspace `name`'s current config lists `daemon`'s service. */
+function workspaceContainsDaemon(
+  name: string,
+  daemon: Pick<DaemonRecord, "address" | "repoName">,
+): boolean {
+  const services = getWorkspaceByName(name)?.config.services ?? {};
+  return daemon.address in services || daemon.repoName in services;
+}
+
+/** Replace a running daemon's owners (re-derived from membership). */
+function setDaemonOwners(address: string, workspaces: string[]): void {
+  loadDaemonsFromFile();
+  const existing = _daemonRegistry.get(address);
+  if (!existing) return;
+  _daemonRegistry.set(address, { ...existing, workspaces });
+  saveDaemonsFile(getDaemonsFile());
+}
+
 /** Outcome of releasing one daemon during a workspace deactivation. */
 export interface DaemonRelease {
   address: string;
@@ -373,15 +402,19 @@ export async function releaseWorkspaceDaemons(
   const owned = listDaemons().filter((d) =>
     (d.workspaces ?? []).includes(workspace),
   );
-  const active = new Set(getActiveWorkspaces());
+  const active = getActiveWorkspaces();
   const releases: DaemonRelease[] = [];
 
   for (const daemon of owned) {
-    const remaining = activeDaemonOwners(daemon, active).filter(
-      (w) => w !== workspace,
+    // Owners re-derived from the CURRENT membership, not the ones recorded at
+    // start: a repo moved into another workspace while its daemon ran belongs
+    // to that workspace now, and one moved out no longer belongs to this one.
+    // Stopped only when no active workspace still contains it.
+    const remaining = active.filter(
+      (w) => w !== workspace && workspaceContainsDaemon(w, daemon),
     );
     if (remaining.length > 0) {
-      detachDaemonOwner(daemon.address, workspace);
+      setDaemonOwners(daemon.address, remaining);
       onLine(
         `detached "${workspace}" from ${daemon.address} — still running for [${remaining.join(", ")}]`,
       );
@@ -630,6 +663,27 @@ export function pruneDeadDaemons(): string[] {
   const running = isOpctlAvailable()
     ? new Set(listRunningOpctlContainers().map((c) => c.base))
     : null;
+  return pruneAgainst(daemons, running);
+}
+
+/**
+ * pruneDeadDaemons without blocking: the container listing runs as async
+ * child processes (the web server's startup, which used to hold the event
+ * loop for the `docker ps`).
+ */
+export async function pruneDeadDaemonsAsync(): Promise<string[]> {
+  const daemons = listDaemons();
+  if (daemons.length === 0) return [];
+  const running = (await isOpctlAvailableAsync())
+    ? new Set((await listRunningOpctlContainersAsync()).map((c) => c.base))
+    : null;
+  return pruneAgainst(daemons, running);
+}
+
+function pruneAgainst(
+  daemons: DaemonRecord[],
+  running: Set<string> | null,
+): string[] {
   const pruned: string[] = [];
   for (const d of daemons) {
     try {
@@ -1069,6 +1123,12 @@ export interface RunCommandOptions {
    * the detach window is invisible to fail-fast callers.
    */
   onServiceExit?: (exitCode: number) => void;
+  /**
+   * R16: the service's resolved `secret_env` (see prepareServiceSecretEnv),
+   * set only in the spawned process's env. An up/restart of a service that
+   * declares secret_env is refused unless every key is here.
+   */
+  secretEnv?: Record<string, string>;
 }
 
 export interface RunCommandResult {
@@ -1135,6 +1195,108 @@ function repoStartedFallback(
       };
 }
 
+// ── secret_env (R16) ─────────────────────────────────────────────────────────
+
+/** Commands that start a service process, and so get its secret_env. */
+function startsService(command: string): boolean {
+  return command === "up" || command === "restart";
+}
+
+/** A service's declared `services.<svc>.secret_env` (validated), or undefined. */
+function serviceSecretEnvSpec(
+  resolved: ResolvedService,
+): SecretEnvSpec | undefined {
+  const raw = readManifest(resolved.repoPath)?.services?.[resolved.subsystem]
+    ?.secret_env;
+  return assertSecretEnvSpec(
+    raw,
+    `${resolved.address}: services.${resolved.subsystem}.secret_env`,
+  );
+}
+
+/**
+ * The address whose command a run of `command` on `address` actually spawns
+ * (a service with no up of its own runs its repo's up), or null when none.
+ */
+function spawningAddress(
+  address: string,
+  command: string,
+  workspace?: string,
+): string | null {
+  const p = previewServiceCommand(address, command, workspace);
+  return p.kind === "run" || p.kind === "via-repo" ? p.address : null;
+}
+
+/**
+ * The secret_env key NAMES a run of `command` on `address` would inject,
+ * for a dry run or status: never a value, and the provider is never asked.
+ * `service` is the service's own secret_env (set in its command's env);
+ * `compose` is the repo's compose.secret_env, which Den's synthesized stack
+ * command resolves for the docker compose process.
+ */
+export function previewServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+): { address: string; service: string[]; compose: string[] } | null {
+  if (!startsService(command)) return null;
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return null;
+  const manifest = readManifest(resolved.repoPath);
+  const service = Object.keys(
+    manifest?.services?.[resolved.subsystem]?.secret_env ?? {},
+  ).sort();
+  const declared = manifest?.services?.[resolved.subsystem]?.commands?.local;
+  const synthesized =
+    manifest?.compose && !declared?.[command]
+      ? composeCommands(
+          manifest,
+          resolved.subsystem,
+          resolved.repoName,
+          workspace ?? "default",
+        )[command]
+      : undefined;
+  const compose = synthesized
+    ? Object.keys(manifest?.compose?.secret_env ?? {}).sort()
+    : [];
+  if (!service.length && !compose.length) return null;
+  return { address: resolved.address, service, compose };
+}
+
+export type ServiceSecretEnvResult =
+  | { ok: true; secretEnv: Record<string, string> }
+  | { ok: false; message: string };
+
+/**
+ * Resolve the `secret_env` of the service a run of `command` on `address`
+ * spawns, for runServiceCommand's `secretEnv`. All or nothing; the provider
+ * is only asked when the service declares secret_env, and only for up and
+ * restart. Messages name keys, refs and the provider, never values.
+ */
+export async function prepareServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+  provider: () => SecretsProvider = getSecretsProvider,
+): Promise<ServiceSecretEnvResult> {
+  if (!startsService(command)) return { ok: true, secretEnv: {} };
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return { ok: true, secretEnv: {} };
+  let spec: SecretEnvSpec | undefined;
+  try {
+    spec = serviceSecretEnvSpec(resolved);
+  } catch (e) {
+    return { ok: false, message: (e as Error).message };
+  }
+  if (!secretEnvKeys(spec).length) return { ok: true, secretEnv: {} };
+  const r = await resolveSecretEnv(spec, provider(), resolved.address);
+  return r.ok
+    ? { ok: true, secretEnv: r.env }
+    : { ok: false, message: r.message };
+}
+
 /** What a run of `command` on `address` would do, without running it. */
 export type ServiceCommandPreview =
   | { kind: "run"; address: string }
@@ -1516,6 +1678,41 @@ export function runServiceCommand(
     onLine,
   );
 
+  // R16: a service that declares secret_env never starts without every key
+  // (a caller that did not resolve them is refused, not run without them).
+  let secretEnv: Record<string, string> = {};
+  if (startsService(command)) {
+    let declared: string[];
+    try {
+      declared = secretEnvKeys(serviceSecretEnvSpec(resolved));
+    } catch (e) {
+      onLine(`Error: ${(e as Error).message}`);
+      closeAsync(1);
+      return dummy();
+    }
+    const missing = declared.filter((k) => !options.secretEnv?.[k]);
+    if (missing.length) {
+      onLine(
+        `Error: ${resolved.address} declares secret_env ${missing.join(", ")}, which were not resolved; not starting it`,
+      );
+      closeAsync(1);
+      return dummy();
+    }
+    secretEnv = Object.fromEntries(
+      declared.map((k) => [k, options.secretEnv?.[k] as string]),
+    );
+  }
+  const hasSecrets = Object.keys(secretEnv).length > 0;
+  // Secrets go only in the spawned process's env. A tab would need them in
+  // its command line (and so its shell history), so such a start runs as a
+  // daemon instead.
+  const runEnv: NodeJS.ProcessEnv = { ...env, ...secretEnv };
+  if (hasSecrets && runtime === "tab" && startsService(command))
+    onLine(
+      `${resolved.address} has secret_env: running as a daemon, not in a tab, to keep the values out of the tab's shell`,
+    );
+  const useTab = runtime === "tab" && !hasSecrets;
+
   // Manifest downs that are just `opctl container down <name>` must not be
   // spawned raw: opctl re-elevates with `sudo -E` and fails on sudoers without
   // SETENV even when there is nothing to stop — which is why files-api/api
@@ -1571,7 +1768,7 @@ export function runServiceCommand(
     // HITL command — inherit the full TTY; onLine is not called.
     const proc = spawnInteractive(
       cmdString,
-      { ...process.env, ...env },
+      { ...process.env, ...runEnv },
       onClose,
       repoPath,
     );
@@ -1621,11 +1818,11 @@ export function runServiceCommand(
     }
   };
 
-  if (runtime === "tab" && command === "up") {
+  if (useTab && command === "up") {
     return openCommandInTab(cmdString);
   }
 
-  if (runtime === "tab" && command === "restart") {
+  if (useTab && command === "restart") {
     closeExistingTab();
     if (requestedCmdDef) return openCommandInTab(cmdString);
 
@@ -1743,7 +1940,7 @@ export function runServiceCommand(
   const proc = spawnStreaming(
     cmdString,
     [],
-    { ...process.env, ...env },
+    { ...process.env, ...runEnv },
     onLine,
     wrappedOnClose,
     repoPath,

package/src/shared/git/origin-url.ts

@@ -0,0 +1,77 @@
+/**
+ * A checkout's `origin` URL, read from its git config file instead of by
+ * running `git`. Callers on the web server's request path (manifest
+ * resolution for every repo without its own manifest) used to spawn
+ * `git config --get remote.origin.url` synchronously, one repo after another:
+ * ~40-100ms each, which held the event loop for a second on a cold server.
+ *
+ * Same answer as `git -C <dir> config --get remote.origin.url` for ordinary
+ * checkouts and linked worktrees: the repo is found by walking up from `dir`
+ * to the first `.git` (a directory, or a `gitdir:` file), and a worktree's
+ * config is its common dir's.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** The git directory for `start` (walking up), or null outside a repo. */
+export function findGitDir(start: string): string | null {
+  let dir = path.resolve(start);
+  for (;;) {
+    const dotGit = path.join(dir, ".git");
+    try {
+      const st = fs.statSync(dotGit);
+      if (st.isDirectory()) return dotGit;
+      if (st.isFile()) {
+        const m = /^gitdir:\s*(.+?)\s*$/m.exec(
+          fs.readFileSync(dotGit, "utf-8"),
+        );
+        if (m) return path.resolve(dir, m[1]);
+      }
+    } catch {
+      /* no .git here: keep walking */
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** The `url` of `[remote "origin"]` in a git config file's text, or null. */
+export function originUrlFromConfig(text: string): string | null {
+  let inOrigin = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+    if (line.startsWith("[")) {
+      inOrigin = /^\[\s*remote\s+"origin"\s*\]$/i.test(line);
+      continue;
+    }
+    if (!inOrigin) continue;
+    const m = /^url\s*=\s*(.*)$/i.exec(line);
+    if (m) {
+      const value = m[1].replace(/\s+[#;].*$/, "").trim();
+      return value.replace(/^"(.*)"$/, "$1") || null;
+    }
+  }
+  return null;
+}
+
+/** `dir`'s origin URL, or null (not a checkout, or no origin). Never spawns. */
+export function readOriginUrl(dir: string): string | null {
+  const gitDir = findGitDir(dir);
+  if (!gitDir) return null;
+  let common = gitDir;
+  try {
+    const rel = fs.readFileSync(path.join(gitDir, "commondir"), "utf-8").trim();
+    if (rel) common = path.resolve(gitDir, rel);
+  } catch {
+    /* not a linked worktree */
+  }
+  try {
+    return originUrlFromConfig(
+      fs.readFileSync(path.join(common, "config"), "utf-8"),
+    );
+  } catch {
+    return null;
+  }
+}

package/src/shared/manifest/read-manifest.ts

@@ -15,7 +15,8 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { execFileSync } from "child_process";
+import { readOriginUrl } from "../git/origin-url.js";
+import { cachedRead } from "../read-cache.js";
 import { getDistRoot } from "../paths.js";
 import { parse as parseYaml } from "yaml";
 import type { RawManifest } from "../types/index.js";
@@ -48,21 +49,15 @@ const originCache = new Map<string, string | null>();
 /** Repo name of `repoPath`'s git origin (`…/<name>.git`), cached. */
 export function originRepoName(repoPath: string): string | null {
   if (originCache.has(repoPath)) return originCache.get(repoPath)!;
-  let name: string | null = null;
-  try {
-    const url = execFileSync(
-      "git",
-      ["-C", repoPath, "config", "--get", "remote.origin.url"],
-      { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 },
-    ).trim();
-    name =
-      url
+  // Read from the git config file, never by spawning git: this runs on the
+  // web server's request path for every repo without its own manifest.
+  const url = readOriginUrl(repoPath);
+  const name = url
+    ? url
         .replace(/\.git$/, "")
         .split(/[/:]/)
-        .pop() || null;
-  } catch {
-    /* not a git checkout, or no origin */
-  }
+        .pop() || null
+    : null;
   originCache.set(repoPath, name);
   return name;
 }
@@ -169,6 +164,29 @@ export function parseManifestText(
   return parsed as Record<string, unknown>;
 }
 
+/**
+ * Parsed manifests by file, reused while the file's text is unchanged. A
+ * single web request reads the same manifests several times (kind, health
+ * plan, stack names, edge links), and parsing YAML is the expensive part:
+ * it held the event loop ~100-200ms per /api/health run. Callers get their
+ * own copy, so mutating a result never leaks into the cache.
+ */
+const parsedCache = new Map<
+  string,
+  { raw: string; parsed: Record<string, unknown> | null }
+>();
+
+function parseCached(
+  file: string,
+  raw: string,
+): Record<string, unknown> | null {
+  const hit = parsedCache.get(file);
+  if (hit && hit.raw === raw) return hit.parsed && structuredClone(hit.parsed);
+  const parsed = parseManifestText(file, raw);
+  parsedCache.set(file, { raw, parsed });
+  return parsed && structuredClone(parsed);
+}
+
 /** The message for an override that has no base to apply to. */
 export function orphanOverrideMessage(): string {
   return `an override with no base manifest is not a manifest: add a ${product().manifestYml} to the repo, or to manifests/`;
@@ -198,7 +216,7 @@ function combine(
 ): ManifestLoad {
   const out: ManifestLoad = { manifest: null, layers: [], ...at };
   const parse = (file: string, raw: string): Record<string, unknown> => {
-    const parsed = parseManifestText(file, raw);
+    const parsed = parseCached(file, raw);
     if (!parsed) throw new Error(`${file}: not a map`);
     return parsed;
   };
@@ -224,6 +242,12 @@ function combine(
 
 /** Resolve, read and merge `repoPath`'s manifest layers. Never throws. */
 export function loadManifest(repoPath: string): ManifestLoad {
+  // The web server resolves the same manifests many times per request; it
+  // reuses them for the read cache's TTL (see read-cache.ts).
+  return cachedRead(`manifest:${repoPath}`, () => loadManifestFresh(repoPath));
+}
+
+function loadManifestFresh(repoPath: string): ManifestLoad {
   const at = locate(repoPath);
   try {
     return combine(

package/src/shared/manifest/schema.ts

@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 import { journeysAppSchema } from "../../pillars/journeys/app-config.js";
+import { SECRET_ENV_KEY_RE, secretEnvRefError } from "../secrets/secret-env.js";
 
 export const CURRENT_SCHEMA_VERSION = 1;
 export const KNOWN_VERSIONS = [1] as const;
@@ -69,6 +70,16 @@ const logSource = z.union([
   }),
 ]);
 
+// secret_env (R16): ENV_NAME → "<vault>/<item>/<field>", resolved through the
+// secrets provider at up/restart and passed only in the process env.
+const secretEnvConfig = z.record(
+  z.string().regex(SECRET_ENV_KEY_RE, "must be a valid env var name"),
+  z.string().superRefine((ref, ctx) => {
+    const err = secretEnvRefError(ref);
+    if (err) ctx.addIssue({ code: z.ZodIssueCode.custom, message: err });
+  }),
+);
+
 // ── Service management config ─────────────────────────────────────────────────
 //
 // Keys for commands/logs/health are environment names (local, dev, …).
@@ -105,6 +116,7 @@ const serviceTarget = z
 const serviceManagementConfig = z.object({
   runs: z.record(z.string(), z.enum(["local", "remote"])).optional(),
   target: serviceTarget.optional(),
+  secret_env: secretEnvConfig.optional(),
   depends_on: z.array(dependsOnEntry).optional(),
   commands: z.record(z.string(), z.record(z.string(), commandDef)).optional(),
   logs: z.record(z.string(), logSource).optional(),
@@ -280,6 +292,9 @@ const composeConfig = z.object({
       z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
     )
     .optional(),
+  // Env vars resolved from the secrets provider into the docker compose
+  // process's env at up/restart. Never written to the override.
+  secret_env: secretEnvConfig.optional(),
 });
 
 // ── v1 manifest schema ────────────────────────────────────────────────────────

package/src/shared/paths.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import {
   loadProfile,
+  onProfileCacheReset,
   PROFILE_FILE,
   readEnv,
   type ProductProfile,
@@ -74,6 +75,34 @@ function rootFromEnv(): string | null {
  * anchor fails loudly.
  */
 export function getDistRoot(): string {
+  // Resolved once per set of inputs: the walk and its den.yml checks used to
+  // run on every call (hundreds per web request, via product()). The inputs
+  // are the env vars it reads and the entry script; change any and it
+  // re-resolves. A failure is never cached.
+  const key = distRootKey();
+  if (distRootMemo?.key === key) return distRootMemo.root;
+  const root = resolveDistRoot();
+  distRootMemo = { key, root };
+  return root;
+}
+
+let distRootMemo: { key: string; root: string } | null = null;
+
+/** Everything getDistRoot's answer depends on, as one string. */
+function distRootKey(): string {
+  let key = `${process.argv[1] ?? ""}\0${process.env.DEN_PROFILE ?? ""}`;
+  for (const name in process.env)
+    if (name.endsWith("_ROOT")) key += `\0${name}=${process.env[name]}`;
+  return key;
+}
+
+/** Forget the resolved root (tests that rebuild a root in place). */
+export function resetDistRootCache(): void {
+  distRootMemo = null;
+}
+onProfileCacheReset(resetDistRootCache);
+
+function resolveDistRoot(): string {
   const fromEnv = rootFromEnv();
   if (fromEnv) return fromEnv;
   const start = entryDir();
@@ -128,6 +157,19 @@ function isProductRootVar(dir: string, key: string): boolean {
  * node_modules/@monster-orange/den; in Den's own checkout, its root.
  */
 export function getEngineRoot(): string {
+  const key = `${process.env.DEN_ENGINE_ROOT ?? ""}\0${process.argv[1] ?? ""}\0${process.cwd()}`;
+  if (engineRootMemo?.key === key) return engineRootMemo.root;
+  const root = resolveEngineRoot();
+  engineRootMemo = { key, root };
+  return root;
+}
+
+let engineRootMemo: { key: string; root: string } | null = null;
+onProfileCacheReset(() => {
+  engineRootMemo = null;
+});
+
+function resolveEngineRoot(): string {
   const env = process.env.DEN_ENGINE_ROOT?.trim();
   if (env) return path.resolve(env);
   for (const start of [entryDir(), process.cwd()]) {

package/src/shared/product.ts

@@ -35,10 +35,16 @@ function withDerived(p: ProductProfile): Product {
   };
 }
 
+let derived: { profile: ProductProfile; product: Product } | null = null;
+
 /** The running product. Never throws. */
 export function product(): Product {
   try {
-    return withDerived(loadProfile(getDistRoot()));
+    const profile = loadProfile(getDistRoot());
+    // Same profile object (loadProfile caches it): same derived names.
+    if (derived?.profile !== profile)
+      derived = { profile, product: withDerived(profile) };
+    return derived.product;
   } catch {
     const pinned = process.env.DEN_PROFILE?.trim();
     try {

package/src/shared/profile.ts

@@ -122,8 +122,16 @@ export function loadProfile(root: string): ProductProfile {
   return cached.profile;
 }
 
+const resetHooks: (() => void)[] = [];
+
+/** Run `hook` whenever resetProfileCache runs (caches derived from it). */
+export function onProfileCacheReset(hook: () => void): void {
+  resetHooks.push(hook);
+}
+
 export function resetProfileCache(): void {
   cached = null;
+  for (const hook of resetHooks) hook();
 }
 
 /** `${PREFIX}_${key}`: the env-var name this distribution uses for `key`. */

package/src/shared/read-cache.ts

@@ -0,0 +1,77 @@
+/**
+ * A short-lived cache for the web server's repeated reads (manifests, the
+ * edge config, the derived graph), so a request does not re-stat and
+ * re-read the same files dozens of times, and polls a few seconds apart
+ * share one read.
+ *
+ * Off unless the web server enables it: a CLI command and the tests read
+ * fresh every time, as before. The server clears it on every mutating
+ * request, so a write made through the UI is seen by the very next read;
+ * an edit made outside the server (an editor, the CLI) is seen within the
+ * TTL. Values are cloned on the way out, so a caller that mutates its copy
+ * never changes what the next caller gets.
+ */
+
+let ttlMs = 0;
+const entries = new Map<string, { at: number; value: unknown }>();
+/** cachedReadStale's values: kept across a clear, only marked stale. */
+const stale = new Map<string, { at: number; value: unknown }>();
+const refreshing = new Set<string>();
+
+/** Turn the cache on (web server only). */
+export function enableReadCache(ms: number): void {
+  ttlMs = ms;
+}
+
+/** Drop every cached read (after a mutation, or in tests). */
+export function clearReadCache(): void {
+  entries.clear();
+  for (const e of stale.values()) e.at = 0;
+}
+
+function copy<T>(v: T): T {
+  return v !== null && typeof v === "object" ? structuredClone(v) : v;
+}
+
+/** `load()`'s value for `key`, reused for the TTL when the cache is on. */
+export function cachedRead<T>(key: string, load: () => T): T {
+  if (ttlMs <= 0) return load();
+  const hit = entries.get(key);
+  if (hit && Date.now() - hit.at < ttlMs) return copy(hit.value as T);
+  const value = load();
+  entries.set(key, { at: Date.now(), value });
+  return copy(value);
+}
+
+/**
+ * Like cachedRead, but past the TTL it still answers with the last value at
+ * once and recomputes after the current request (setImmediate), so no
+ * request waits on the recompute. For expensive, slow-changing results
+ * (the derived dependency graph) whose staleness only affects ordering.
+ */
+export function cachedReadStale<T>(
+  key: string,
+  maxAgeMs: number,
+  load: () => T,
+): T {
+  if (ttlMs <= 0) return load();
+  const hit = stale.get(key);
+  if (!hit) {
+    const value = load();
+    stale.set(key, { at: Date.now(), value });
+    return copy(value);
+  }
+  if (Date.now() - hit.at >= maxAgeMs && !refreshing.has(key)) {
+    refreshing.add(key);
+    setImmediate(() => {
+      try {
+        stale.set(key, { at: Date.now(), value: load() });
+      } catch {
+        /* keep the last good value */
+      } finally {
+        refreshing.delete(key);
+      }
+    });
+  }
+  return copy(hit.value as T);
+}