harnery 0.43.0 → 0.45.0

package/src/core/servers/tunnels.ts

@@ -1,26 +1,71 @@
 /**
  * Tunnels as registry services.
  *
- * `tunnel up` and `tunnel reload` register the instance; `tunnel down`
- * removes it. Tunnels started before the registry existed are adopted the next
- * time the registry is read, so a long-lived tunnel never shows as an
- * unregistered listener.
+ * `tunnel up` and `tunnel reload` register the new gate; `tunnel down` removes
+ * its record. Missing original witnesses remain unknown and cannot authorize actions.
  */
 
+import { hostname } from "node:os";
 import { resolve } from "node:path";
-import { gateLogFile, type TunnelState } from "../../lib/tunnel/state.ts";
-import { resolveBinName } from "../config.ts";
-import type { RegisterServerInput } from "./index.ts";
+import {
+  gateLogFile,
+  type TunnelReadinessVerifier,
+  type TunnelState,
+} from "../../lib/tunnel/state.ts";
+import {
+  type RegisterServerInput,
+  readServer,
+  type ServerOptions,
+  verifyProcessGeneration,
+  withServerRegistrationCustody,
+} from "./index.ts";
+
+/** Verify only witnesses saved by the original tunnel registration. */
+export function createTunnelReadinessVerifier(options: ServerOptions): TunnelReadinessVerifier {
+  return {
+    observeProcess(pid, originalToken) {
+      try {
+        process.kill(pid, 0);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ESRCH") return "absent";
+        return "unknown";
+      }
+      return verifyProcessGeneration(pid, originalToken);
+    },
+    withRegistration(state, inspect) {
+      try {
+        const original = readServer(tunnelServerId(state.name), options);
+        if (
+          !original ||
+          original.host !== hostname() ||
+          original.kind !== "service" ||
+          original.type !== "tunnel" ||
+          original.registration_id !== state.registration_id ||
+          original.pid !== state.gate_pid ||
+          original.start_token !== state.gate_start_token ||
+          original.port !== state.gate_port ||
+          original.url !== state.url
+        )
+          return "unknown";
+        return withServerRegistrationCustody(original, options, inspect);
+      } catch {
+        return "unknown";
+      }
+    },
+  };
+}
 
 export function tunnelServerId(name: string): string {
   return `tunnel-${name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-")}`;
 }
 
-/** The registry input for one tunnel instance. */
+/** Register the new gate; saved helper PIDs have no generation witnesses. */
 export function tunnelServerInput(state: TunnelState, coordRoot: string): RegisterServerInput {
-  const helpers = [state.cloudflared_pid, state.provider_pid].filter(
-    (pid): pid is number => typeof pid === "number" && pid > 0,
-  );
+  if (Object.hasOwn(state, "provider_pid") || Object.hasOwn(state, "provider_start_token"))
+    throw new Error("obsolete tunnel provider authority is unknown; state retained");
+  if (!state.gate_start_token)
+    throw new Error("tunnel gate generation witness is unavailable; state retained");
   return {
     id: tunnelServerId(state.name),
     kind: "service",
@@ -29,10 +74,9 @@ export function tunnelServerInput(state: TunnelState, coordRoot: string): Regist
     url: state.url,
     port: state.gate_port,
     pid: state.gate_pid,
-    ...(helpers.length ? { pids: helpers } : {}),
+    start_token: state.gate_start_token,
     log: resolve(coordRoot, ".cache", "tunnel", gateLogFile(state.name)),
     cwd: coordRoot,
-    stop_argv: [resolveBinName(coordRoot), "tunnel", "down", "--name", state.name],
     started_at: state.started_at,
     owner: null,
   };

package/src/core/supervisor/contract.ts

@@ -1,3 +1,4 @@
+import type { ProcessGenerationVerdict } from "../agents/state/proc-start.ts";
 import type {
   PressureAssessment,
   PressureHysteresisState,
@@ -47,10 +48,16 @@ export const SUPERVISOR_RESOURCE_BUDGET = {
 
 export type SupervisorProcessState = "starting" | "running" | "stopping" | "stopped" | "error";
 
+export interface SupervisorBuild {
+  version: string;
+  revision: string;
+}
+
 export interface SupervisorServiceStatusRecord {
   schema_version: typeof SUPERVISOR_STATUS_SCHEMA_VERSION;
   pid: number;
   start_token?: string;
+  running_build?: SupervisorBuild;
   host: string;
   nonce: string;
   state: SupervisorProcessState;
@@ -70,6 +77,12 @@ export interface SupervisorServiceStatusRecord {
 export interface SupervisorStatus {
   running: boolean;
   stale: boolean;
+  generation: ProcessGenerationVerdict;
+  liveness: "running" | "stopped" | "unknown";
+  running_build: SupervisorBuild | null;
+  installed_build: SupervisorBuild;
+  restart_needed: boolean;
+  build_status: string;
   record?: SupervisorServiceStatusRecord;
   status_path: string;
   snapshot_path: string;

package/src/core/supervisor/explanations.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { canonicalizeDiagnosticIdentity } from "../diagnostics/path-identity.ts";
 import {
   SUPERVISOR_DIAGNOSTIC_LIMITS,
   SUPERVISOR_EXPLANATION_SCHEMA_VERSION,
@@ -94,7 +95,9 @@ function statement(
 ): SupervisorExplanationStatement {
   return {
     id: `ex_${createHash("sha256")
-      .update(`${code}\u0000${summary}\u0000${evidenceIds.join(",")}`)
+      .update(
+        canonicalizeDiagnosticIdentity(`${code}\u0000${summary}\u0000${evidenceIds.join(",")}`),
+      )
       .digest("hex")
       .slice(0, 24)}`,
     code,

package/src/core/supervisor/findings.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import type { CoordinationHealthSnapshot } from "../agents/health.ts";
+import { canonicalizeDiagnosticIdentity } from "../diagnostics/path-identity.ts";
 import type {
   ResourceProcessGroup,
   ResourceProcessSample,
@@ -96,15 +97,17 @@ export function updateSupervisorFindings(
   const candidates = evaluateCandidates(input)
     .sort((left, right) => severityRank(right.severity) - severityRank(left.severity))
     .slice(0, SUPERVISOR_DIAGNOSTIC_LIMITS.max_active_findings);
-  const priorActive = new Map(previous.active.map((entry) => [entry.fingerprint, entry]));
+  const priorActive = new Map(previous.active.map((entry) => [findingFingerprint(entry), entry]));
   const current = new Set<string>();
   const active: SupervisorFinding[] = [];
   const transitions = new Map(previous.transitions.map((entry) => [entry.id, entry]));
 
-  for (const candidate of candidates) {
-    const fingerprint = findingFingerprint(candidate);
-    current.add(fingerprint);
-    const prior = priorActive.get(fingerprint) ?? recentResolved(previous, fingerprint, observedAt);
+  for (const observed of candidates) {
+    const identity = findingFingerprint(observed);
+    current.add(identity);
+    const prior = priorActive.get(identity) ?? recentResolved(previous, identity, observedAt);
+    const candidate = preserveEpisodeReferences(observed, prior);
+    const fingerprint = prior?.fingerprint ?? identity;
     const openedAt = prior?.opened_at ?? candidate.primary_source.observed_at;
     const occurrenceCount = prior
       ? prior.state === "resolved"
@@ -114,7 +117,7 @@ export function updateSupervisorFindings(
     const peak = peakEvidence(prior, candidate.evidence, observedAt);
     const finding: SupervisorFinding = {
       schema_version: SUPERVISOR_FINDING_SCHEMA_VERSION,
-      id: deterministicId("find", `${fingerprint}\u0000${openedAt}`),
+      id: prior?.id ?? deterministicId("find", `${fingerprint}\u0000${openedAt}`),
       fingerprint,
       source_kind: candidate.source_kind,
       finding_kind: candidate.finding_kind,
@@ -139,7 +142,7 @@ export function updateSupervisorFindings(
   }
 
   for (const prior of priorActive.values()) {
-    if (current.has(prior.fingerprint)) continue;
+    if (current.has(findingFingerprint(prior))) continue;
     transitions.set(prior.id, {
       ...prior,
       state: "resolved",
@@ -859,7 +862,7 @@ function recentResolved(
   return findings.transitions
     .filter(
       (entry) =>
-        entry.fingerprint === fingerprint &&
+        findingFingerprint(entry) === fingerprint &&
         entry.state === "resolved" &&
         entry.resolved_at !== undefined &&
         observedMs - Date.parse(entry.resolved_at) >= 0 &&
@@ -898,7 +901,12 @@ function peakEvidence(
     : {};
 }
 
-function findingFingerprint(candidate: Candidate): string {
+function findingFingerprint(
+  candidate: Pick<
+    Candidate,
+    "source_kind" | "finding_kind" | "scope_kind" | "scope_id" | "primary_source"
+  >,
+): string {
   return digest(
     [
       candidate.source_kind,
@@ -915,7 +923,57 @@ function deterministicId(prefix: string, value: string): string {
 }
 
 function digest(value: string): string {
-  return createHash("sha256").update(value).digest("hex");
+  return createHash("sha256").update(canonicalizeDiagnosticIdentity(value)).digest("hex");
+}
+
+/** Keep opaque episode links when the same source observation is replayed privately. */
+function preserveEpisodeReferences(candidate: Candidate, prior?: SupervisorFinding): Candidate {
+  if (!prior) return candidate;
+  const sources = [
+    prior.primary_source,
+    ...prior.evidence.map((entry) => entry.source),
+    ...(prior.workload_context ? [prior.workload_context.source] : []),
+  ];
+  const byIdentity = new Map(sources.map((source) => [sourceIdentity(source), source]));
+  const retainSource = (source: SupervisorSourceReference): SupervisorSourceReference => {
+    const captured = byIdentity.get(sourceIdentity(source));
+    return captured ? { ...source, id: captured.id } : source;
+  };
+  return {
+    ...candidate,
+    primary_source: retainSource(candidate.primary_source),
+    evidence: candidate.evidence.map((entry) => {
+      const captured = prior.evidence.find(
+        (previous) =>
+          sourceIdentity(previous.source) === sourceIdentity(entry.source) &&
+          previous.unit === entry.unit &&
+          previous.observed_value === entry.observed_value &&
+          canonicalizeDiagnosticIdentity(previous.summary) ===
+            canonicalizeDiagnosticIdentity(entry.summary),
+      );
+      return {
+        ...entry,
+        ...(captured ? { id: captured.id } : {}),
+        source: retainSource(entry.source),
+      };
+    }),
+    ...(candidate.workload_context
+      ? {
+          workload_context: {
+            ...candidate.workload_context,
+            source: retainSource(candidate.workload_context.source),
+          },
+        }
+      : {}),
+  };
+}
+
+function sourceIdentity(source: SupervisorSourceReference): string {
+  return canonicalizeDiagnosticIdentity(
+    [source.source_kind, source.source_id, source.record_id ?? "", source.observed_at].join(
+      "\u0000",
+    ),
+  );
 }
 
 function validFindings(value: SupervisorFindings | undefined): value is SupervisorFindings {

package/src/core/supervisor/service.ts

@@ -16,7 +16,13 @@ import { resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { collectCoordinationHealthSnapshot } from "../agents/health.ts";
-import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
+import {
+  type ProcessGenerationSignalDependencies,
+  type ProcessGenerationVerdict,
+  processStartToken,
+  signalIfSameGeneration,
+} from "../agents/state/proc-start.ts";
+import { resolveBinName } from "../config.ts";
 import { pressureHistoryFromSupervisor } from "../diagnostics/advice.ts";
 import { assessPressure } from "../diagnostics/pressure.ts";
 import { readEventV3ControlState } from "../events/v3/control.ts";
@@ -52,7 +58,12 @@ import type {
 } from "./ledger-state.ts";
 import { SupervisorLogCollector } from "./log-feed.ts";
 import { collectServiceHealth } from "./services.ts";
-import { readSupervisorStatus } from "./status.ts";
+import {
+  installedSupervisorBuild,
+  readSupervisorStatus,
+  type SupervisorProcessDependencies,
+  supervisorProcessLiveness,
+} from "./status.ts";
 import {
   readSupervisorFindings,
   readSupervisorHistory,
@@ -97,15 +108,16 @@ export async function spawnSupervisor(
 ): Promise<SupervisorStatus> {
   const coordRoot = resolve(coordRootRaw);
   const current = readSupervisorStatus(coordRoot);
-  if (current.running) {
+  if (current.liveness === "unknown") throw unknownOwnerError();
+  if (current.liveness === "running") {
     throw new Error(`local supervisor is already running under pid ${current.record?.pid}`);
   }
+  const paths = supervisorPaths(coordRoot);
+  assertLeaseAvailable(paths.lease);
   await stopLegacyResourceObserver(coordRoot);
   const intervalMs = normalizeInterval(options.intervalMs);
   const idleExitMs = normalizeIdleExit(options.idleExitMs);
-  const paths = supervisorPaths(coordRoot);
   mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
-  rmSync(paths.stop, { force: true });
   const cliPath = fileURLToPath(
     new URL(import.meta.url.endsWith(".ts") ? "../../cli.ts" : "../../cli.js", import.meta.url),
   );
@@ -167,29 +179,55 @@ export async function ensureSupervisorRunning(coordRoot: string): Promise<Ensure
   }
 }
 
-export function requestSupervisorStop(coordRootRaw: string): SupervisorStatus {
+export interface SupervisorStopResult extends SupervisorStatus {
+  signal_sent: boolean;
+  signal_verdict: ProcessGenerationVerdict;
+}
+
+export function requestSupervisorStop(
+  coordRootRaw: string,
+  dependencies: SupervisorProcessDependencies & ProcessGenerationSignalDependencies = {},
+): SupervisorStopResult {
   const coordRoot = resolve(coordRootRaw);
   const paths = supervisorPaths(coordRoot);
-  const status = readSupervisorStatus(coordRoot);
+  const status = readSupervisorStatus(coordRoot, Date.now(), dependencies);
   mkdirSync(paths.root, { recursive: true, mode: stateDirMode() });
   writePrivateJsonAtomic(paths.stop, {
     requested_at: new Date().toISOString(),
     requested_by_pid: process.pid,
   });
-  if (status.running && status.record?.host === hostname() && process.platform !== "win32") {
-    try {
-      process.kill(status.record.pid, "SIGTERM");
-    } catch {
-      // The durable stop file handles a racing exit.
-    }
+  const legacyPaths = resourcePaths(coordRoot);
+  if (existsSync(legacyPaths.service) || existsSync(legacyPaths.lease))
+    requestResourceServiceStop(coordRoot, dependencies);
+  let signal = { sent: false, verdict: status.generation };
+  if (
+    status.liveness === "running" &&
+    status.record?.host === hostname() &&
+    process.platform !== "win32"
+  ) {
+    signal = signalIfSameGeneration(
+      status.record.pid,
+      status.record.start_token,
+      "SIGTERM",
+      dependencies,
+    );
   }
-  return readSupervisorStatus(coordRoot);
+  return {
+    ...readSupervisorStatus(coordRoot, Date.now(), dependencies),
+    signal_sent: signal.sent,
+    signal_verdict: signal.verdict,
+  };
 }
 
 export async function runSupervisor(
   input: RunSupervisorInput,
 ): Promise<SupervisorServiceStatusRecord> {
   const coordRoot = resolve(input.coordRoot);
+  const current = readSupervisorStatus(coordRoot);
+  if (current.liveness === "unknown") throw unknownOwnerError();
+  if (current.liveness === "running") {
+    throw new Error(`local supervisor is already running under pid ${current.record?.pid}`);
+  }
   const paths = supervisorPaths(coordRoot);
   const intervalMs = normalizeInterval(input.intervalMs);
   const idleExitMs = normalizeIdleExit(input.idleExitMs);
@@ -204,6 +242,7 @@ export async function runSupervisor(
     schema_version: SUPERVISOR_STATUS_SCHEMA_VERSION,
     pid: process.pid,
     ...(startToken ? { start_token: startToken } : {}),
+    running_build: installedSupervisorBuild(),
     host: hostname(),
     nonce: lease.nonce,
     state: "starting",
@@ -517,7 +556,9 @@ function acquireLease(coordRoot: string, now: Date): SupervisorLease {
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
       const existing = readLease(paths.lease);
-      if (existing && leaseIsLive(existing)) {
+      const liveness = existing ? leaseIsLive(existing) : "unknown";
+      if (liveness === "unknown") throw unknownOwnerError();
+      if (existing && liveness === "running") {
         throw new Error(`local supervisor lease is held by pid ${existing.pid}`);
       }
       try {
@@ -554,7 +595,13 @@ function releaseLease(path: string, nonce: string): void {
 function readLease(path: string): SupervisorLease | undefined {
   try {
     const value = JSON.parse(readFileSync(path, "utf8")) as SupervisorLease;
-    return value && Number.isSafeInteger(value.pid) && typeof value.nonce === "string"
+    return value &&
+      Number.isSafeInteger(value.pid) &&
+      value.pid > 0 &&
+      typeof value.host === "string" &&
+      value.host.length > 0 &&
+      typeof value.nonce === "string" &&
+      value.nonce.length > 0
       ? value
       : undefined;
   } catch {
@@ -562,22 +609,36 @@ function readLease(path: string): SupervisorLease | undefined {
   }
 }
 
-function leaseIsLive(lease: SupervisorLease): boolean {
-  if (lease.host !== hostname()) return true;
-  try {
-    process.kill(lease.pid, 0);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
-  }
-  return checkPidToken(lease.pid, lease.start_token) !== "mismatch";
+function leaseIsLive(lease: SupervisorLease): SupervisorStatus["liveness"] {
+  return supervisorProcessLiveness(lease).liveness;
+}
+
+function assertLeaseAvailable(path: string): void {
+  if (!existsSync(path)) return;
+  const lease = readLease(path);
+  const liveness = lease ? leaseIsLive(lease) : "unknown";
+  if (liveness === "unknown") throw unknownOwnerError();
+  if (liveness === "running")
+    throw new Error(`local supervisor lease is held by pid ${lease?.pid}`);
+}
+
+function unknownOwnerError(): Error {
+  return new Error(
+    `local supervisor process identity is unknown; run ${resolveBinName()} supervisor stop to write the durable stop request before starting again`,
+  );
 }
 
 async function stopLegacyResourceObserver(coordRoot: string): Promise<void> {
   const legacy = readResourceServiceStatus(coordRoot);
-  if (!legacy.running) return;
+  if (legacy.liveness === "stopped") return;
   requestResourceServiceStop(coordRoot);
   const deadline = Date.now() + 2_000;
-  while (readResourceServiceStatus(coordRoot).running && Date.now() < deadline) await delay(50);
+  while (readResourceServiceStatus(coordRoot).liveness !== "stopped" && Date.now() < deadline)
+    await delay(50);
+  if (readResourceServiceStatus(coordRoot).liveness !== "stopped")
+    throw new Error(
+      "legacy resource observer has not stopped after its durable stop request; its process identity may be unknown",
+    );
 }
 
 function log(

package/src/core/supervisor/services.ts

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
+import { readGovernorServiceStatus } from "../governor/service-read.ts";
 import { writePrivateJsonAtomic } from "../storage/atomic-json.ts";
 import {
   type ObservedServiceHealth,
@@ -41,10 +42,7 @@ export function collectServiceHealth(
     join(coordRoot, ".harnery", "semantic", "v2", "service.json"),
     "semantic-reader",
   );
-  const governor = readDetachedService(
-    join(coordRoot, ".harnery", "governor-service", "service.json"),
-    "governor",
-  );
+  const governor = readGovernorHealth(coordRoot);
   const relay = readPresenceRelay(join(coordRoot, ".harnery", "presence", "relay-daemon.json"));
   const dashboard = consumers.find((consumer) => consumer.id === "dashboard");
   const services: ObservedServiceHealth[] = [
@@ -118,10 +116,7 @@ interface DetachedServiceRecord {
   heartbeat_at?: string;
 }
 
-function readDetachedService(
-  path: string,
-  id: "semantic-reader" | "governor",
-): ObservedServiceHealth {
+function readDetachedService(path: string, id: "semantic-reader"): ObservedServiceHealth {
   const record = readBoundedJson<DetachedServiceRecord>(path);
   if (!record || !Number.isSafeInteger(record.pid) || record.pid < 1) {
     return { id, state: "stopped" };
@@ -150,6 +145,29 @@ function readDetachedService(
   );
 }
 
+function readGovernorHealth(coordRoot: string): ObservedServiceHealth {
+  const status = readGovernorServiceStatus(coordRoot);
+  const state =
+    status.liveness === "unknown"
+      ? "unknown"
+      : status.running
+        ? "running"
+        : status.stale
+          ? "stale"
+          : "stopped";
+  const reason =
+    state === "unknown"
+      ? "governor-process-generation-unknown"
+      : status.generation === "different"
+        ? "recorded-process-generation-different"
+        : status.stale
+          ? "recorded-running-process-missing"
+          : undefined;
+  return status.record
+    ? projection("governor", state, status.record, reason)
+    : { id: "governor", state, ...(reason ? { reason } : {}) };
+}
+
 function readPresenceRelay(path: string): ObservedServiceHealth {
   const record = readBoundedJson<{ pid: number; started_at?: string }>(path);
   if (!record || !Number.isSafeInteger(record.pid) || record.pid < 1) {

package/src/core/supervisor/status.ts

@@ -1,7 +1,14 @@
+import { existsSync, readFileSync } from "node:fs";
 import { hostname } from "node:os";
-import { checkPidToken } from "../agents/state/proc-start.ts";
+import { join } from "node:path";
+import {
+  type ProcessGenerationVerdict,
+  verifyProcessGeneration,
+} from "../agents/state/proc-start.ts";
+import { currentHarneryRuntimeBuild, harneryPackageRoot } from "../events/v3/runtime-build.ts";
 import {
   SUPERVISOR_STATUS_SCHEMA_VERSION,
+  type SupervisorBuild,
   type SupervisorServiceStatusRecord,
   type SupervisorStatus,
 } from "./contract.ts";
@@ -9,27 +16,71 @@ import { readSupervisorServiceRecord, supervisorPaths } from "./storage.ts";
 
 const STALE_HEARTBEAT_MS = 15_000;
 
-export function readSupervisorStatus(coordRoot: string, nowMs = Date.now()): SupervisorStatus {
+export interface SupervisorProcessDependencies {
+  readToken?: (pid: number) => string | null;
+  probePid?: (pid: number) => unknown;
+}
+
+export function installedSupervisorBuild(): SupervisorBuild {
+  let version = "unknown";
+  let revision = "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync(join(harneryPackageRoot(), "package.json"), "utf8"));
+    if (typeof pkg.version === "string") version = pkg.version;
+    revision = currentHarneryRuntimeBuild();
+  } catch {
+    // Missing build evidence must still produce an inspectable status.
+  }
+  return { version, revision };
+}
+
+export function readSupervisorStatus(
+  coordRoot: string,
+  nowMs = Date.now(),
+  dependencies: SupervisorProcessDependencies = {},
+): SupervisorStatus {
   const paths = supervisorPaths(coordRoot);
   const record = readSupervisorServiceRecord(coordRoot);
+  const installedBuild = installedSupervisorBuild();
+  const runningBuild = validBuild(record?.running_build) ? record.running_build : null;
+  const restartNeeded =
+    !runningBuild ||
+    installedBuild.version === "unknown" ||
+    installedBuild.revision === "unknown" ||
+    runningBuild.version !== installedBuild.version ||
+    runningBuild.revision !== installedBuild.revision;
+  const build = {
+    running_build: runningBuild,
+    installed_build: installedBuild,
+    restart_needed: restartNeeded,
+    build_status: !runningBuild
+      ? "running build unknown; restart needed"
+      : restartNeeded
+        ? "restart needed"
+        : "current",
+  };
   if (!validRecord(record)) {
     return {
       running: false,
       stale: false,
+      generation: "unknown",
+      liveness: existsSync(paths.service) ? "unknown" : "stopped",
+      ...build,
       status_path: paths.service,
       snapshot_path: paths.snapshot,
     };
   }
   const heartbeatAt = Date.parse(record.heartbeat_at);
   const stale = !Number.isFinite(heartbeatAt) || nowMs - heartbeatAt > STALE_HEARTBEAT_MS;
-  const running =
-    record.host === hostname() &&
-    !stale &&
-    (record.state === "starting" || record.state === "running" || record.state === "stopping") &&
-    pidStillMatches(record.pid, record.start_token);
+  const owner = supervisorProcessLiveness(record, dependencies);
+  const liveness =
+    owner.generation === "same" && record.state === "stopped" ? "stopped" : owner.liveness;
   return {
-    running,
+    running: liveness === "running" && !stale && record.state !== "stopped",
     stale,
+    generation: owner.generation,
+    liveness,
+    ...build,
     record,
     status_path: paths.service,
     snapshot_path: paths.snapshot,
@@ -49,11 +100,37 @@ function validRecord(
   );
 }
 
-function pidStillMatches(pid: number, startToken: string | undefined): boolean {
+/** A stale heartbeat does not prove that a process has exited. */
+export function supervisorProcessLiveness(
+  owner: { pid: number; host: string; start_token?: string },
+  dependencies: SupervisorProcessDependencies = {},
+): { liveness: SupervisorStatus["liveness"]; generation: ProcessGenerationVerdict } {
+  if (owner.host !== hostname()) return { liveness: "unknown", generation: "unknown" };
   try {
-    process.kill(pid, 0);
+    (dependencies.probePid ?? ((pid) => process.kill(pid, 0)))(owner.pid);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EPERM") return false;
+    return {
+      liveness: (error as NodeJS.ErrnoException).code === "ESRCH" ? "stopped" : "unknown",
+      generation: "unknown",
+    };
   }
-  return checkPidToken(pid, startToken) !== "mismatch";
+  const generation = verifyProcessGeneration(owner.pid, owner.start_token, dependencies.readToken);
+  return {
+    generation,
+    liveness:
+      generation === "same" ? "running" : generation === "different" ? "stopped" : "unknown",
+  };
+}
+
+function validBuild(value: unknown): value is SupervisorBuild {
+  if (!value || typeof value !== "object") return false;
+  const build = value as Partial<SupervisorBuild>;
+  return (
+    typeof build.version === "string" &&
+    !!build.version &&
+    build.version !== "unknown" &&
+    typeof build.revision === "string" &&
+    !!build.revision &&
+    build.revision !== "unknown"
+  );
 }