@promptctl/cc-candybar 1.0.0

package/src/daemon/debug-types.ts

@@ -0,0 +1,91 @@
+// [LAW:types-are-the-program] Wire-level snapshot shapes for the `debug`
+// protocol message. The `what` discriminator carries the response shape
+// forward — a client requesting "vars" gets vars data, "segments" gets
+// segments data, "config" gets config data. There is no `data: unknown`
+// field that callers must shape-check.
+//
+// [LAW:one-source-of-truth] These types are the single contract between the
+// daemon's introspection layer (src/daemon/debug.ts) and any external
+// consumer (the future `cc-candybar vars` / `lint` CLIs, debug tooling).
+// The protocol wraps them; the introspector produces them.
+//
+// Lives in its own module to break a potential cycle: protocol.ts re-exports
+// these for the wire type, debug.ts produces them, and both could otherwise
+// pull each other in.
+
+import type { VarType, VarValue } from "../var-system/types";
+import type { DslConfig, SourceKind } from "../config/dsl-types";
+
+// [LAW:one-source-of-truth] DEBUG_WHATS is the canonical list; DebugWhat is
+// *derived* from it via indexed access on the `as const` tuple type. Adding
+// a new entry to the array automatically expands DebugWhat — and the switch
+// in buildDebugSnapshot (src/daemon/debug.ts) becomes non-exhaustive,
+// failing the typecheck until a new arm is added. The dispatcher arm and
+// the canonical list are kept in lockstep by the type system, not by
+// human discipline.
+export const DEBUG_WHATS = ["vars", "segments", "config"] as const;
+export type DebugWhat = (typeof DEBUG_WHATS)[number];
+
+// Wire-side type guard for an untrusted JSON value. Used by the daemon at
+// the request boundary; symmetrically usable by future CLI shims that
+// validate user input before sending the frame.
+// [LAW:one-source-of-truth] Implemented in terms of DEBUG_WHATS so the
+// guard cannot drift from the canonical list — a new `what` added to
+// DEBUG_WHATS becomes accepted by isDebugWhat with no second-site edit.
+export function isDebugWhat(v: unknown): v is DebugWhat {
+  return (
+    typeof v === "string" && (DEBUG_WHATS as readonly string[]).includes(v)
+  );
+}
+
+// One row of the `vars` snapshot. Captures everything an operator needs to
+// answer "is this variable computing? did it fail? when did it last update?"
+// without re-reading config or grepping logs.
+export interface VarSnapshot {
+  readonly name: string;
+  // The DSL source kind that declared this variable (literal/env/input/...).
+  // null when a variable exists in the store but was not declared via DSL —
+  // present for completeness so a programmatic-only var still shows up in
+  // introspection rather than being silently invisible.
+  readonly source: SourceKind | null;
+  readonly type: VarType;
+  // Current store value. For Computed nodes this triggers re-evaluation if
+  // MobX has invalidated the cache; for Box nodes it is the last value set.
+  readonly value: VarValue;
+  readonly lastError: {
+    readonly timestampMs: number;
+    readonly message: string;
+  } | null;
+  // Wall-clock ms since the box was last set (Box) or null for Computed
+  // nodes whose freshness is governed by MobX invalidation, not a single
+  // timestamp. Null is structurally distinct from 0 so consumers can
+  // distinguish "no age tracking applies" from "just updated."
+  readonly ageMs: number | null;
+}
+
+// One row of the `segments` snapshot.
+export interface SegmentSnapshot {
+  readonly name: string;
+  // The template source string (verbatim, as authored in the config).
+  readonly template: string;
+  // Names of variables potentially referenced by the template, found via
+  // static analysis: dotted paths inside `{{ ... }}` actions, matched
+  // against the store's declared names. Exact runtime deps may be a subset
+  // (branches not taken), but every name returned IS in the store.
+  readonly referencedVars: readonly string[];
+  // The last rendered output for this segment, when the daemon has captured
+  // one. null today — the daemon does not yet render through the DSL spine
+  // (see bzh.2). Populated when the daemon flips to renderDsl.
+  readonly lastRender: string | null;
+}
+
+// [LAW:types-are-the-program] The discriminated union ensures every response
+// carries exactly the data shape its `what` promises. There is no path that
+// produces e.g. `{ what: "vars", segments: [...] }` — the type forbids it.
+export type DebugSnapshot =
+  | { readonly what: "vars"; readonly vars: readonly VarSnapshot[] }
+  | {
+      readonly what: "segments";
+      readonly segments: readonly SegmentSnapshot[];
+    }
+  | { readonly what: "config"; readonly config: DslConfig | null };

package/src/daemon/debug.ts

@@ -0,0 +1,264 @@
+// [LAW:single-enforcer] One module owns the projection from daemon DSL
+// state (VariableStore + SourceRegistry + DslConfig + CompiledConfig) to
+// the wire-level DebugSnapshot. buildDebugSnapshot dispatches via an
+// exhaustive switch on `what` — TypeScript enforces every DebugWhat arm
+// at compile time (the function's return-type narrowing fails if a case
+// is missing), so adding a new `what` requires one new arm here, one new
+// DEBUG_WHATS entry, and one new DebugSnapshot variant — the type system
+// keeps the three sites in lockstep.
+//
+// [LAW:one-source-of-truth] The introspector reads through the live
+// VariableStore (current values), SourceRegistry (lastErrors), VarNode
+// (lastUpdatedMs), and DslConfig (declared source kinds, segment templates).
+// There is no parallel cache, no shadow snapshot kept in sync — the daemon
+// has one DSL state and this module projects it.
+//
+// [LAW:dataflow-not-control-flow] The state slot (DaemonDslState | null) is
+// the only branch: null state → empty snapshots; populated state → real
+// snapshots. No special-case introspection paths for the "DSL not active
+// yet" case — the same code produces both outcomes from the same data.
+//
+// Today the daemon does not yet hold a DSL state (bzh.2 has not fired); all
+// snapshots are empty in production. When bzh.2 wires the store, the
+// snapshots populate without any change to this module or the protocol.
+
+import type { VariableStore } from "../var-system/store";
+import type { SourceRegistry } from "../var-system/sources";
+import type { DslConfig, SourceKind, VariableDecl } from "../config/dsl-types";
+import { walkNodes } from "../config/dsl-types";
+import { extractTemplateRefs } from "../config/dsl-loader";
+import type { CompiledConfig } from "../dsl/render";
+import type {
+  DebugSnapshot,
+  DebugWhat,
+  SegmentSnapshot,
+  VarSnapshot,
+} from "./debug-types";
+
+// The daemon's DSL state. Bundled because the four fields are co-installed
+// by registerDslConfig — exposing them as independently-optional would let
+// callers represent illegal combinations (e.g. store with no config).
+export interface DaemonDslState {
+  readonly store: VariableStore;
+  readonly registry: SourceRegistry;
+  readonly config: DslConfig;
+  readonly compiled: CompiledConfig;
+  // [LAW:dataflow-not-control-flow] Per-segment last-render strings live in
+  // the same state bundle the renderer mutates. Today (legacy renderer) it
+  // is empty; bzh.2 populates it from inside renderDsl.
+  readonly lastRenderBySegment: ReadonlyMap<string, string>;
+}
+
+// ─── Dispatcher ──────────────────────────────────────────────────────────────
+
+// [LAW:dataflow-not-control-flow] One arm per `what` — the discriminator is
+// data; the branch chooses the projection function, not whether projection
+// runs. Adding a new `what` is one new arm + one new projection + one new
+// DebugSnapshot variant — the type system enforces all three.
+export function buildDebugSnapshot(
+  what: DebugWhat,
+  state: DaemonDslState | null,
+): DebugSnapshot {
+  switch (what) {
+    case "vars":
+      return { what, vars: introspectVars(state) };
+    case "segments":
+      return { what, segments: introspectSegments(state) };
+    case "config":
+      return { what, config: introspectConfig(state) };
+  }
+}
+
+// ─── vars ────────────────────────────────────────────────────────────────────
+
+// Project every variable currently registered in the store into one
+// VarSnapshot. Names sorted for deterministic snapshot tests. Source kind
+// is looked up from the DslConfig (top-level variables + per-segment
+// `vars` blocks); a variable not found in either is reported with
+// source=null so it still appears in introspection.
+export function introspectVars(
+  state: DaemonDslState | null,
+): readonly VarSnapshot[] {
+  if (state === null) return [];
+
+  const { store, registry, config } = state;
+  const sourceByName = buildSourceKindIndex(config);
+  const names = store.names().sort();
+
+  const out: VarSnapshot[] = [];
+  for (const name of names) {
+    // [LAW:single-enforcer] One requireNode lookup per row. Reading the
+    // value through node.read() instead of store.read(name) avoids a
+    // second Map.get + requireNode round-trip in the inner loop and
+    // makes the per-row data dependency obvious: every field below
+    // comes from this one node.
+    const node = store.getNode(name);
+    const err = registry.getLastError(name);
+    // [LAW:no-defensive-null-guards] No try/catch around node.read():
+    // every SourceRegistry-declared variable either holds a typed
+    // fallback (declareShell/declareFile/declareGit/declareInput catch
+    // internally and write a fallback) or is a computed whose deriver
+    // also catches (declareTemplate). Cycles are detected eagerly at
+    // register time (declareTemplate's force-read). So a read-throw
+    // here would be a *programming* error, not a runtime condition
+    // the snapshot should mask. Letting it propagate keeps the failure
+    // loud at the source instead of laundering it as a synthesized
+    // lastError with an unstable Date.now() timestamp.
+    //
+    // [LAW:single-enforcer] lastError is sourced from SourceRegistry
+    // only. There is no second timestamp-producer that could drift
+    // from the registry's record.
+    out.push({
+      name,
+      source: sourceByName.get(name) ?? null,
+      type: node.type,
+      value: node.read(),
+      lastError:
+        err !== undefined
+          ? { timestampMs: err.timestamp, message: err.message }
+          : null,
+      ageMs: ageFromNode(node.lastUpdatedMs()),
+    });
+  }
+  return out;
+}
+
+function ageFromNode(lastUpdatedMs: number | null): number | null {
+  if (lastUpdatedMs === null) return null;
+  return Math.max(0, Date.now() - lastUpdatedMs);
+}
+
+// Build a name → SourceKind index from the DslConfig. Walks top-level
+// variables and each segment's per-segment vars block; segment-local vars
+// live under the namespaced key `<segName>.<varName>` in the store (same
+// shape registerDslConfig uses to declare them).
+function buildSourceKindIndex(
+  config: DslConfig,
+): ReadonlyMap<string, SourceKind> {
+  const index = new Map<string, SourceKind>();
+  for (const [name, decl] of Object.entries(config.variables)) {
+    index.set(name, sourceKindOf(decl));
+  }
+  for (const [segName, seg] of Object.entries(config.segments)) {
+    if (!seg.vars) continue;
+    for (const [varName, decl] of Object.entries(seg.vars)) {
+      index.set(`${segName}.${varName}`, sourceKindOf(decl));
+    }
+  }
+  return index;
+}
+
+function sourceKindOf(decl: VariableDecl): SourceKind {
+  return decl.kind;
+}
+
+// ─── segments ────────────────────────────────────────────────────────────────
+
+export function introspectSegments(
+  state: DaemonDslState | null,
+): readonly SegmentSnapshot[] {
+  if (state === null) return [];
+
+  const { store, config, lastRenderBySegment } = state;
+  const declaredNames = new Set(store.names());
+  // [LAW:dataflow-not-control-flow] Walk in layout order so the introspection
+  // snapshot mirrors render order — operators reading the snapshot see the
+  // same sequence the bar produces, not an alphabetical reshuffling.
+  const segNames = orderedSegmentNames(config);
+
+  const out: SegmentSnapshot[] = [];
+  for (const name of segNames) {
+    const seg = config.segments[name];
+    if (!seg) continue;
+    out.push({
+      name,
+      template: seg.template,
+      referencedVars: extractReferencedVars(seg.template, declaredNames),
+      lastRender: lastRenderBySegment.get(name) ?? null,
+    });
+  }
+  return out;
+}
+
+// Layout order, with any declared-but-not-laid-out segments appended in
+// declaration order so they still appear in the snapshot (an operator
+// debugging "why isn't this rendering" wants to see the segment, not have
+// it filtered out for being absent from layout).
+function orderedSegmentNames(config: DslConfig): readonly string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const node of walkNodes(config.root)) {
+    if (node.kind !== "segment") continue;
+    if (config.segments[node.name] && !seen.has(node.name)) {
+      out.push(node.name);
+      seen.add(node.name);
+    }
+  }
+  for (const name of Object.keys(config.segments)) {
+    if (!seen.has(name)) {
+      out.push(name);
+      seen.add(name);
+    }
+  }
+  return out;
+}
+
+// [LAW:single-enforcer] Static analysis of which variables a segment
+// template references. Raw candidate extraction (find dotted paths inside
+// `{{ ... }}` actions, strip string literals so `{{ printf ".foo" }}`
+// does not falsely match a declared `foo`) is delegated to
+// extractTemplateRefs in src/config/dsl-loader.ts — that helper already
+// owns the template-ref parsing rules and is exercised by the loader's
+// cycle detector. Reusing it means a future improvement to the parser
+// (e.g. supporting `$x.field` variable references) lands here for free.
+//
+// Static analysis (not runtime evaluation) is the right tool here:
+// evaluation would couple introspection to a working store and would
+// vary by current values (if/with branches taken). Static finds every
+// potentially-referenced name regardless of current state — which is
+// what an operator debugging "what does this segment depend on" needs.
+//
+// This function adds the introspection-specific layers on top of the raw
+// extraction:
+//   1. Intersect with the declared-name set (only report names that exist).
+//   2. Ancestor credit: a candidate `.session.id.extra` resolves to the
+//      declared `session.id` if `extra` is not declared.
+//   3. Sort the result for deterministic snapshots.
+export function extractReferencedVars(
+  template: string,
+  declared: ReadonlySet<string>,
+): readonly string[] {
+  const found = new Set<string>();
+  for (const candidate of extractTemplateRefs(template)) {
+    if (declared.has(candidate)) {
+      found.add(candidate);
+      continue;
+    }
+    // Drop trailing segments until we hit a declared name. Handles
+    // `.session.id.something_extra` where only `session.id` is declared —
+    // still credit it as a reference to `session.id`.
+    const parts = candidate.split(".");
+    while (parts.length > 1) {
+      parts.pop();
+      const prefix = parts.join(".");
+      if (declared.has(prefix)) {
+        found.add(prefix);
+        break;
+      }
+    }
+  }
+  return Array.from(found).sort();
+}
+
+// ─── config ──────────────────────────────────────────────────────────────────
+
+// [LAW:no-defensive-null-guards] No defensive copy. DslConfig is `readonly`
+// throughout and the wire-encoder JSON-serializes it; downstream callers
+// see a fresh value. Returning the live reference is the cheapest correct
+// answer.
+export function introspectConfig(
+  state: DaemonDslState | null,
+): DslConfig | null {
+  if (state === null) return null;
+  return state.config;
+}

package/src/daemon/limits.ts

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+import v8 from "node:v8";
+import { daemonDir } from "./paths";
+import { dlog, type DaemonLogger } from "./log";
+
+// [LAW:single-enforcer] One module owns "when does the daemon plan to die".
+// Only the RSS trigger remains — idle and age limits were removed because they
+// interrupted active sessions. The RSS limit is a true anomaly backstop; normal
+// operation should never approach it now that transcript parsing is pruned.
+const DEFAULT_RSS_LIMIT =
+  (parseInt(process.env["CC_CANDYBAR_RSS_LIMIT_MB"] ?? "", 10) || 512) *
+  1024 *
+  1024;
+const DEFAULT_CHECK_INTERVAL = 60 * 1000;
+const HEAP_SNAPSHOT_KEEP = 3;
+
+export interface LimitsDeps {
+  now: () => number;
+  // [LAW:locality-or-seam] The snapshot directory, the log sink, and the
+  // writer's identity are injected, not reached for ambiently. Without these,
+  // unit tests of checkRss compute filenames against the real daemonDir() and
+  // emit real dlog lines into the user's production daemon.log — the seam must
+  // cover every dependency or it isn't a seam.
+  pid: number;
+  snapshotDir: string;
+  log: DaemonLogger;
+  rssBytes: () => number;
+  writeHeapSnapshot: (filePath: string) => string;
+  listSnapshots: () => string[];
+  removeFile: (filePath: string) => void;
+  shutdown: (code: number) => void;
+  startedAtMs: number;
+  rssLimitBytes?: number;
+  snapshotsKeep?: number;
+}
+
+export interface LimitsHandle {
+  checkRss(): boolean;
+  describeNextRestart(): string | null;
+  arm(intervalMs?: number): { disarm(): void };
+}
+
+export function makeLimits(deps: LimitsDeps): LimitsHandle {
+  const rssLimit = deps.rssLimitBytes ?? DEFAULT_RSS_LIMIT;
+  const keep = deps.snapshotsKeep ?? HEAP_SNAPSHOT_KEEP;
+  let triggered = false;
+
+  function checkRss(): boolean {
+    if (triggered) return true;
+    const rss = deps.rssBytes();
+    if (rss <= rssLimit) return false;
+    triggered = true;
+    deps.log(
+      "warn",
+      `RSS ${rss} > limit ${rssLimit}; writing heap snapshot then shutting down`,
+    );
+    try {
+      // [LAW:types-are-the-program] Uniqueness is by construction (the writer's
+      // pid), not by trusting the clock to be real and sub-ms-distinct. Two
+      // overlapping daemons hitting the wall in the same millisecond — or a
+      // frozen `now` — still produce distinct files; the timestamp stays the
+      // leading component so rotateSnapshots' newest-first ordering holds.
+      const stamp = new Date(deps.now()).toISOString().replace(/[:.]/g, "-");
+      const file = path.join(
+        deps.snapshotDir,
+        `heap-${stamp}-${deps.pid}.heapsnapshot`,
+      );
+      const written = deps.writeHeapSnapshot(file);
+      deps.log("info", `heap snapshot written: ${written}`);
+      rotateSnapshots(deps.listSnapshots(), keep, deps.removeFile);
+    } catch (e) {
+      deps.log("warn", `heap snapshot failed: ${(e as Error).message}`);
+    }
+    deps.shutdown(0);
+    return true;
+  }
+
+  function describeNextRestart(): string | null {
+    const rss = deps.rssBytes();
+    if (rss > rssLimit * 0.75) {
+      return `rss ${rss} approaching limit ${rssLimit}`;
+    }
+    return null;
+  }
+
+  function arm(intervalMs: number = DEFAULT_CHECK_INTERVAL): {
+    disarm(): void;
+  } {
+    const timer = setInterval(() => {
+      checkRss();
+    }, intervalMs);
+    timer.unref();
+    return {
+      disarm: () => clearInterval(timer),
+    };
+  }
+
+  return { checkRss, describeNextRestart, arm };
+}
+
+function rotateSnapshots(
+  files: string[],
+  keep: number,
+  remove: (p: string) => void,
+): void {
+  // Newest-first by basename (the leading ISO timestamp is lexically ordered;
+  // the trailing -<pid> only tiebreaks same-instant writes). Sort by basename
+  // so paths with different parent dirs still order correctly when the test
+  // mock and production use different prefixes.
+  const sorted = [...files].sort((a, b) => {
+    const aBase = a.slice(a.lastIndexOf("/") + 1);
+    const bBase = b.slice(b.lastIndexOf("/") + 1);
+    return bBase.localeCompare(aBase);
+  });
+  for (const f of sorted.slice(keep)) {
+    try {
+      remove(f);
+    } catch {}
+  }
+}
+
+// Default real-fs deps for the daemon. Test code constructs its own.
+export function realLimitsDeps(
+  startedAtMs: number,
+  shutdown: (code: number) => void,
+  overrides: Partial<LimitsDeps> = {},
+): LimitsDeps {
+  // [LAW:one-source-of-truth] One captured dir backs both the new-snapshot path
+  // and the listing used for rotation, so they can never read different dirs.
+  const dir = daemonDir();
+  return {
+    now: () => Date.now(),
+    pid: process.pid,
+    snapshotDir: dir,
+    log: dlog,
+    rssBytes: () => process.memoryUsage().rss,
+    writeHeapSnapshot: (file) => v8.writeHeapSnapshot(file),
+    listSnapshots: () => {
+      try {
+        return fs
+          .readdirSync(dir)
+          .filter((f) => f.startsWith("heap-") && f.endsWith(".heapsnapshot"))
+          .map((f) => path.join(dir, f));
+      } catch {
+        return [];
+      }
+    },
+    removeFile: (file) => fs.unlinkSync(file),
+    shutdown,
+    startedAtMs,
+    ...overrides,
+  };
+}

package/src/daemon/log.ts

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logPath } from "./paths";
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const KEEP_GENERATIONS = 3;
+
+let stream: fs.WriteStream | null = null;
+let bytesWritten = 0;
+
+function ensureStream(): fs.WriteStream {
+  if (stream) return stream;
+  const filePath = logPath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  // Pre-load size so rotation triggers correctly across daemon restarts.
+  try {
+    bytesWritten = fs.statSync(filePath).size;
+  } catch {
+    bytesWritten = 0;
+  }
+  stream = fs.createWriteStream(filePath, { flags: "a" });
+  return stream;
+}
+
+// Self-rotation: when daemon.log exceeds MAX_BYTES, shift .1→.2, .2→.3, drop
+// the oldest, and start fresh. Daemon-internal so we don't depend on any
+// external rotator. Cheap because rotation only runs at the rollover boundary.
+function rotate(): void {
+  const filePath = logPath();
+  if (stream) {
+    stream.end();
+    stream = null;
+  }
+  for (let i = KEEP_GENERATIONS - 1; i >= 1; i--) {
+    const src = `${filePath}.${i}`;
+    const dst = `${filePath}.${i + 1}`;
+    try {
+      fs.renameSync(src, dst);
+    } catch {}
+  }
+  try {
+    fs.renameSync(filePath, `${filePath}.1`);
+  } catch {}
+  bytesWritten = 0;
+}
+
+// [LAW:locality-or-seam] The logging capability daemon components depend on.
+// `dlog` is the daemon's implementation (writes to daemon.log); consumers that
+// inject a different impl (a quiet default in tests) take this shape.
+export type DaemonLogger = (
+  level: "info" | "warn" | "error",
+  msg: string,
+) => void;
+
+export function dlog(level: "info" | "warn" | "error", msg: string): void {
+  const line = `${new Date().toISOString()} [${level}] ${msg}\n`;
+  const buf = Buffer.from(line, "utf8");
+  const s = ensureStream();
+  s.write(buf);
+  bytesWritten += buf.length;
+  if (bytesWritten >= MAX_BYTES) rotate();
+}
+
+export function closeLog(): void {
+  if (stream) {
+    stream.end();
+    stream = null;
+  }
+}

package/src/daemon/parent-watchdog.ts

@@ -0,0 +1,80 @@
+import process from "node:process";
+
+// [LAW:single-enforcer] One owner of the invariant "I must not outlive the
+// process that spawned me." A *production* daemon is spawned detached and is
+// SUPPOSED to outlive its spawner — the render-tick client exits, leaving a
+// warm daemon — so it is anchored to nobody and this watchdog never fires. A
+// daemon spawned by a *transient* process (the Jest worker) must die WITH it:
+// on abnormal exit (SIGKILL, worker crash, suite timeout) the OS reparents the
+// orphan to init and it survives forever. That orphan-to-init survival is the
+// test-daemon leak. The spawner publishes its pid in the environment and every
+// descendant inherits it, so even a detached grand-child daemon stays anchored
+// to the original runner.
+//
+// [LAW:dataflow-not-control-flow] The watchdog runs the same poll every tick;
+// whether it ever trips lives in the anchor VALUE (a pid to outlive, or
+// nobody), derived once from the environment — never in a branch wrapped around
+// the spawn path. Like the RSS backstop in `limits.ts`, it calls `onOrphaned`
+// (the lifecycle `shutdown`) rather than exiting itself, so every daemon-death
+// path funnels through the one enforcer.
+
+export const PARENT_PID_ENV = "CC_CANDYBAR_PARENT_PID";
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+export type LivenessAnchor =
+  | { kind: "outlives-nobody" }
+  | { kind: "anchored"; pid: number };
+
+// [LAW:no-silent-fallbacks] Three inputs, three outcomes, no overlap: absent →
+// production (outlive nobody); a positive integer → anchor to it; present but
+// malformed → throw. Only the test harness ever sets this variable, so a
+// malformed value is a harness bug; silently degrading to "outlives-nobody"
+// would re-open the very leak this module closes.
+export function anchorFromEnv(env: NodeJS.ProcessEnv): LivenessAnchor {
+  const raw = env[PARENT_PID_ENV];
+  if (raw === undefined) return { kind: "outlives-nobody" };
+  const pid = Number.parseInt(raw, 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(
+      `${PARENT_PID_ENV} must be a positive integer pid, got ${JSON.stringify(raw)}`,
+    );
+  }
+  return { kind: "anchored", pid };
+}
+
+export interface ParentWatchdogDeps {
+  anchor: LivenessAnchor;
+  isAlive: (pid: number) => boolean;
+  onOrphaned: (reason: string) => void;
+  intervalMs?: number;
+}
+
+export function armParentWatchdog(deps: ParentWatchdogDeps): {
+  disarm(): void;
+} {
+  // An unanchored daemon has nothing to poll — arming a perpetual no-op timer on
+  // the user's always-running daemon would be pure waste. Returning an inert
+  // handle is the consequence of the data, not a special case in the spawn path.
+  if (deps.anchor.kind === "outlives-nobody") return { disarm: () => {} };
+
+  const { pid } = deps.anchor;
+  const timer = setInterval(() => {
+    if (!deps.isAlive(pid)) deps.onOrphaned(`spawner pid ${pid} gone`);
+  }, deps.intervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+  timer.unref();
+  return { disarm: () => clearInterval(timer) };
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH: the process is gone — orphaned, trip the watchdog. EPERM: a live
+    // process we don't own (the pid was reused by another user) — treat as
+    // alive so a reused pid can never make us shut down a daemon whose real
+    // spawner is still running.
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}