harnery 0.45.1 → 0.45.2

package/src/core/context/observation.ts

@@ -1,11 +1,13 @@
 /**
  * Repository observation contract shared by context recovery and workflow proof.
  *
- * This module has no runtime imports so read-only consumers (the Codec
- * dashboard, proof readers) can use it without reaching the Git-running
- * snapshot code in ./index.ts.
+ * This module runs no Git and touches no files, so read-only consumers (the
+ * Codec dashboard, proof readers) can use it without reaching the
+ * Git-running snapshot code in ./index.ts.
  */
 
+import { isAbsolute } from "node:path";
+
 export type RepoObservation = "ok" | "unavailable" | "partial";
 
 export interface RepoSnapshot {
@@ -20,10 +22,39 @@ export interface RepoSnapshot {
   dirty_paths_truncated?: boolean;
 }
 
-/** Only explicitly successful observations can establish repository drift. */
-export function observationsComparable(
-  a: { observation?: string },
-  b: { observation?: string },
-): boolean {
-  return a.observation === "ok" && b.observation === "ok";
+/**
+ * Every reason two snapshots cannot establish repository drift. Only an empty
+ * list lets a caller compare branch, HEAD and dirty paths; anything else
+ * leaves the whole comparison unknown.
+ */
+export function repoComparisonProblems(
+  a: RepoSnapshot,
+  b: RepoSnapshot,
+  labels: readonly [string, string],
+): string[] {
+  const sides = [
+    [labels[0], a],
+    [labels[1], b],
+  ] as const;
+  const failed = sides.flatMap(([label, repo]) =>
+    repo.observation === "ok"
+      ? []
+      : [
+          // Snapshots recorded before observations existed carry none.
+          `${label} snapshot is ${repo.observation ?? "unavailable"}${repo.observation_detail ? ` (${repo.observation_detail})` : ""}`,
+        ],
+  );
+  if (failed.length > 0) return failed;
+  const problems: string[] = [];
+  if (a.dirty_paths_truncated || b.dirty_paths_truncated) {
+    problems.push("dirty path list is truncated");
+  }
+  if (!a.root || !b.root || !isAbsolute(a.root) || !isAbsolute(b.root)) {
+    problems.push("repository root is unknown");
+  } else if (a.root !== b.root) {
+    problems.push("repository roots differ");
+  }
+  if (!a.branch?.trim() || !b.branch?.trim()) problems.push("branch is unknown");
+  if (!a.head?.trim() || !b.head?.trim()) problems.push("HEAD is unknown");
+  return problems;
 }

package/src/core/events/v3/runtime-build.ts

@@ -40,3 +40,65 @@ export function currentHarneryRuntimeBuild(): string {
 export function harneryPackageRoot(): string {
   return resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
 }
+
+export interface HarneryBuild {
+  version: string;
+  revision: string;
+}
+
+/** The installed package version and runtime revision; "unknown" when unreadable. */
+export function installedHarneryBuild(): HarneryBuild {
+  let version = "unknown";
+  let revision = "unknown";
+  try {
+    const manifest = JSON.parse(
+      readFileSync(resolve(harneryPackageRoot(), "package.json"), "utf8"),
+    ) as { version?: unknown };
+    if (typeof manifest.version === "string" && manifest.version.length <= 100)
+      version = manifest.version;
+  } catch {
+    // Missing package metadata cannot establish that a running build is current.
+  }
+  try {
+    revision = currentHarneryRuntimeBuild();
+  } catch {
+    // Status still reports the unavailable build instead of guessing a match.
+  }
+  return { version, revision };
+}
+
+export interface ServiceBuildStatus {
+  running_build: HarneryBuild | null;
+  installed_build: HarneryBuild;
+  restart_needed: boolean;
+  build_status: string;
+}
+
+/** A missing or unknown running build, or any difference, means restart. */
+export function serviceBuildStatus(recorded: unknown): ServiceBuildStatus {
+  const installed_build = installedHarneryBuild();
+  const candidate = recorded as Partial<HarneryBuild> | undefined;
+  const known = (value: unknown): value is string =>
+    typeof value === "string" && value.length > 0 && value.length <= 100 && value !== "unknown";
+  const running_build =
+    candidate && known(candidate.version) && known(candidate.revision)
+      ? { version: candidate.version, revision: candidate.revision }
+      : null;
+  const restart_needed =
+    running_build === null ||
+    installed_build.version === "unknown" ||
+    installed_build.revision === "unknown" ||
+    running_build.version !== installed_build.version ||
+    running_build.revision !== installed_build.revision;
+  return {
+    running_build,
+    installed_build,
+    restart_needed,
+    build_status:
+      running_build === null
+        ? "running build unknown; restart needed"
+        : restart_needed
+          ? "restart needed"
+          : "current",
+  };
+}

package/src/core/governor/index.ts

@@ -63,13 +63,12 @@ export {
   type RunGovernorServiceDaemonInput,
   type RunGovernorServiceSweepInput,
   readGovernorServiceConfig,
-  readGovernorServiceRuntime,
-  readGovernorServiceStatus,
   requestGovernorServiceStop,
   runGovernorServiceDaemon,
   runGovernorServiceSweep,
   spawnGovernorService,
 } from "./service.ts";
+export { readGovernorServiceRuntime, readGovernorServiceStatus } from "./service-read.ts";
 export {
   assertGovernorId,
   type CreateGovernorInput,

package/src/core/governor/service-read.ts

@@ -1,21 +1,20 @@
 import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
-import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { gunzipSync } from "node:zlib";
 import { coordEnv } from "../../lib/env.ts";
+import type { ProcessGenerationVerdict } from "../agents/state/proc-start.ts";
 import {
-  type ProcessGenerationVerdict,
-  verifyProcessGeneration,
-} from "../agents/state/proc-start.ts";
-import { currentHarneryRuntimeBuild } from "../events/v3/runtime-build.ts";
+  observeServiceProcess,
+  type ServiceLiveness,
+  type ServiceProcessDependencies,
+} from "../agents/state/service-process.ts";
+import { serviceBuildStatus } from "../events/v3/runtime-build.ts";
 import { createStorageCatalog } from "../storage/catalog.ts";
 import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
 import { parseLogRecord } from "../storage/jsonl.ts";
 import { familyLogDirectory, readSegmentManifest } from "../storage/segments.ts";
 import type {
-  GovernorServiceBuild,
   GovernorServiceConfig,
-  GovernorServiceProcessDependencies,
   GovernorServiceRuntime,
   GovernorServiceStatus,
   GovernorServiceStatusRecord,
@@ -25,106 +24,6 @@ const MAX_FILE_BYTES = 512 * 1024;
 const MAX_LOG_RECORDS = 10_000;
 const MAX_GOALS = 100;
 
-export function currentGovernorServiceBuild(): GovernorServiceBuild {
-  let version = "unknown";
-  let revision = "unknown";
-  try {
-    const manifest = JSON.parse(
-      readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),
-    ) as {
-      version?: unknown;
-    };
-    if (typeof manifest.version === "string" && manifest.version.length <= 100) {
-      version = manifest.version;
-    }
-  } catch {
-    // Missing package metadata cannot establish that the running build is current.
-  }
-  try {
-    revision = currentHarneryRuntimeBuild();
-  } catch {
-    // Status still reports the unavailable build instead of guessing a match.
-  }
-  return { version, revision };
-}
-
-export function governorServiceBuildStatus(
-  record: GovernorServiceStatusRecord | undefined,
-): Pick<
-  GovernorServiceStatus,
-  "running_build" | "installed_build" | "restart_needed" | "build_status"
-> {
-  const installed_build = currentGovernorServiceBuild();
-  const candidate = record?.running_build;
-  const running_build =
-    candidate &&
-    typeof candidate.version === "string" &&
-    candidate.version.length > 0 &&
-    candidate.version.length <= 100 &&
-    typeof candidate.revision === "string" &&
-    candidate.revision.length > 0 &&
-    candidate.revision.length <= 100 &&
-    candidate.version !== "unknown" &&
-    candidate.revision !== "unknown"
-      ? candidate
-      : null;
-  const restart_needed =
-    running_build === null ||
-    installed_build.version === "unknown" ||
-    installed_build.revision === "unknown" ||
-    running_build.version !== installed_build.version ||
-    running_build.revision !== installed_build.revision;
-  return {
-    running_build,
-    installed_build,
-    restart_needed,
-    build_status:
-      running_build === null
-        ? "running build unknown; restart needed"
-        : restart_needed
-          ? "restart needed"
-          : "current",
-  };
-}
-
-/** An unknown token or process probe cannot establish a running or stopped owner. */
-export function observeGovernorServiceProcess(
-  record: Pick<GovernorServiceStatusRecord, "pid" | "host" | "state" | "start_token"> | undefined,
-  dependencies: GovernorServiceProcessDependencies = {},
-): { generation: ProcessGenerationVerdict; liveness: GovernorServiceStatus["liveness"] } {
-  if (!record) return { generation: "unknown", liveness: "stopped" };
-  const generation =
-    record.host === hostname()
-      ? verifyProcessGeneration(record.pid, record.start_token, dependencies.readToken)
-      : "unknown";
-  if (record.host !== hostname()) return { generation, liveness: "unknown" };
-  try {
-    const present = (dependencies.probePid ?? probePid)(record.pid);
-    if (!present) return { generation, liveness: "stopped" };
-  } catch (error) {
-    return {
-      generation,
-      liveness: (error as NodeJS.ErrnoException).code === "ESRCH" ? "stopped" : "unknown",
-    };
-  }
-  return {
-    generation,
-    liveness:
-      generation === "same"
-        ? record.state === "stopped"
-          ? "stopped"
-          : "running"
-        : generation === "different"
-          ? "stopped"
-          : "unknown",
-  };
-}
-
-function probePid(pid: number): boolean {
-  process.kill(pid, 0);
-  return true;
-}
-
 export function readGovernorServiceConfig(coordRootRaw: string): GovernorServiceConfig {
   const coordRoot = resolve(coordRootRaw);
   const config = readBoundedJson<GovernorServiceConfig>(
@@ -175,7 +74,7 @@ export function readGovernorServiceRuntime(
 
 export function readGovernorServiceStatus(
   coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): GovernorServiceStatus {
   const coordRoot = resolve(coordRootRaw);
   const record = readStatusRecord(coordRoot);
@@ -191,15 +90,17 @@ export function readGovernorServiceStatus(
   } catch {
     // Runtime is recoverable and must not make the dashboard unreadable.
   }
-  const observation = observeGovernorServiceProcess(record, dependencies);
-  if (!record && existsSync(join(serviceDir(coordRoot), "status.json"))) {
-    observation.liveness = "unknown";
-  }
+  const observation: { generation: ProcessGenerationVerdict; liveness: ServiceLiveness } = record
+    ? observeServiceProcess(record, dependencies)
+    : {
+        generation: "unknown",
+        liveness: existsSync(join(serviceDir(coordRoot), "status.json")) ? "unknown" : "stopped",
+      };
   return {
-    running: observation.liveness === "running" && record?.state !== "stopped",
+    running: observation.liveness === "running",
     stale: observation.liveness === "stopped" && record !== undefined && record.state !== "stopped",
     ...observation,
-    ...governorServiceBuildStatus(record),
+    ...serviceBuildStatus(record?.running_build),
     record,
     config,
     runtime,

package/src/core/governor/service.ts

@@ -10,30 +10,28 @@ import {
   renameSync,
   rmSync,
   statSync,
-  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
+import { type ProcessGenerationVerdict, processStartToken } from "../agents/state/proc-start.ts";
 import {
-  type ProcessGenerationSignalDependencies,
-  type ProcessGenerationVerdict,
-  processStartToken,
-  signalIfSameGeneration,
-} from "../agents/state/proc-start.ts";
+  acquireServiceLease,
+  requestServiceStop,
+  type ServiceLiveness,
+  type ServiceProcessDependencies,
+  serviceStartRefusal,
+} from "../agents/state/service-process.ts";
 import { resolveBinName } from "../config.ts";
+import { installedHarneryBuild } from "../events/v3/runtime-build.ts";
 import { type NormalizedPolicy, normalizePolicy, type PolicyIsolation } from "../policy/index.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
 import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import { RotatingTextSink } from "../storage/process-log.ts";
 import type { RunWorkItemInput } from "../work/index.ts";
 import { type GovernorRunReport, type GovernorStopReason, runGovernor } from "./runner.ts";
-import {
-  currentGovernorServiceBuild,
-  governorServiceBuildStatus,
-  observeGovernorServiceProcess,
-} from "./service-read.ts";
+import { readGovernorServiceRuntime, readGovernorServiceStatus } from "./service-read.ts";
 import { type GovernorRecord, readGovernor } from "./state.ts";
 
 export const GOVERNOR_SERVICE_CONFIG_SCHEMA_VERSION = 1 as const;
@@ -101,10 +99,6 @@ export interface GovernorServiceBuild {
   revision: string;
 }
 
-export interface GovernorServiceProcessDependencies extends ProcessGenerationSignalDependencies {
-  probePid?: (pid: number) => boolean;
-}
-
 export interface GovernorServiceStatusRecord {
   schema_version: typeof GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION;
   pid: number;
@@ -173,27 +167,13 @@ export interface RunGovernorServiceDaemonInput {
   onLog?: (line: string) => void;
 }
 
-interface ServiceLease {
-  pid: number;
-  start_token?: string;
-  running_build?: GovernorServiceBuild;
-  host: string;
-  nonce: string;
-  created_at: string;
-}
-
 export function configureGovernorService(
   input: ConfigureGovernorServiceInput,
 ): GovernorServiceConfig {
   const coordRoot = resolve(input.coordRoot);
-  const active = readStatusRecord(coordRoot);
-  if (!active && existsSync(serviceStatusPath(coordRoot))) {
-    throw serviceStartRefusal(coordRoot, undefined, "unknown");
-  }
-  if (active) {
-    const liveness = statusOwnerIsLive(active);
-    if (liveness !== "stopped") throw serviceStartRefusal(coordRoot, active.pid, liveness);
-  }
+  const current = readGovernorServiceStatus(coordRoot);
+  if (current.liveness !== "stopped")
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
   const goalIds = unique(input.goalIds.map((value) => value.trim()).filter(Boolean));
   if (goalIds.length < 1 || goalIds.length > MAX_GOALS) {
     throw new Error(`governor service requires from 1 to ${MAX_GOALS} unique goal ids`);
@@ -249,65 +229,12 @@ export function readGovernorServiceConfig(coordRootRaw: string): GovernorService
   return config;
 }
 
-export function readGovernorServiceRuntime(
-  coordRootRaw: string,
-): GovernorServiceRuntime | undefined {
-  const coordRoot = resolve(coordRootRaw);
-  if (!existsSync(serviceRuntimePath(coordRoot))) return undefined;
-  const runtime = readBoundedJson<GovernorServiceRuntime>(
-    serviceRuntimePath(coordRoot),
-    "governor service runtime",
-  );
-  if (
-    runtime.schema_version !== GOVERNOR_SERVICE_RUNTIME_SCHEMA_VERSION ||
-    !validTimestamp(runtime.config_created_at) ||
-    !validTimestamp(runtime.updated_at) ||
-    !runtime.goals ||
-    typeof runtime.goals !== "object" ||
-    Array.isArray(runtime.goals)
-  ) {
-    throw new Error("governor service runtime has an unsupported schema");
-  }
-  return runtime;
-}
-
-export function readGovernorServiceStatus(
-  coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
-): GovernorServiceStatus {
-  const coordRoot = resolve(coordRootRaw);
-  const record = readStatusRecord(coordRoot);
-  let config: GovernorServiceConfig | undefined;
-  let runtime: GovernorServiceRuntime | undefined;
-  try {
-    config = readGovernorServiceConfig(coordRoot);
-  } catch {
-    // A service has no usable configuration until explicitly configured.
-  }
-  try {
-    runtime = readGovernorServiceRuntime(coordRoot);
-  } catch {
-    // Status remains readable when recoverable runtime state is corrupt.
-  }
-  const observation = observeGovernorServiceProcess(record, dependencies);
-  if (!record && existsSync(serviceStatusPath(coordRoot))) observation.liveness = "unknown";
-  return {
-    running: observation.liveness === "running" && record?.state !== "stopped",
-    stale: observation.liveness === "stopped" && record !== undefined && record.state !== "stopped",
-    ...observation,
-    ...governorServiceBuildStatus(record),
-    record,
-    config,
-    runtime,
-  };
-}
-
 export async function spawnGovernorService(coordRootRaw: string): Promise<GovernorServiceStatus> {
   const coordRoot = resolve(coordRootRaw);
   readGovernorServiceConfig(coordRoot);
   const current = readGovernorServiceStatus(coordRoot);
   if (current.liveness !== "stopped") {
-    throw serviceStartRefusal(coordRoot, current.record?.pid, current.liveness);
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
   }
   mkdirSync(serviceDir(coordRoot), { recursive: true, mode: stateDirMode() });
   const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
@@ -347,31 +274,19 @@ export async function spawnGovernorService(coordRootRaw: string): Promise<Govern
 
 export function requestGovernorServiceStop(
   coordRootRaw: string,
-  dependencies: GovernorServiceProcessDependencies = {},
+  dependencies: ServiceProcessDependencies = {},
 ): GovernorServiceStatus {
   const coordRoot = resolve(coordRootRaw);
   const status = readGovernorServiceStatus(coordRoot, dependencies);
   if ((status.record?.state === "stopped" || !status.record) && status.liveness === "stopped") {
     return { ...status, signal_sent: false, signal_verdict: status.generation };
   }
-  writePrivateJsonAtomic(serviceStopPath(coordRoot), {
-    requested_at: new Date().toISOString(),
-    requested_by_pid: process.pid,
-  });
-  const signal =
-    status.record?.host === hostname() && status.record.state !== "stopped"
-      ? signalIfSameGeneration(
-          status.record.pid,
-          status.record.start_token,
-          "SIGTERM",
-          dependencies,
-        )
-      : { sent: false, verdict: status.generation };
-  return {
-    ...readGovernorServiceStatus(coordRoot, dependencies),
-    signal_sent: signal.sent,
-    signal_verdict: signal.verdict,
-  };
+  return requestServiceStop(
+    status,
+    () => readGovernorServiceStatus(coordRoot, dependencies),
+    serviceStopPath(coordRoot),
+    dependencies,
+  );
 }
 
 export async function runGovernorServiceSweep(
@@ -519,22 +434,21 @@ export async function runGovernorServiceDaemon(
 ): Promise<GovernorServiceStatusRecord> {
   const coordRoot = resolve(input.coordRoot);
   const config = readGovernorServiceConfig(coordRoot);
-  const existing = readStatusRecord(coordRoot);
-  if (!existing && existsSync(serviceStatusPath(coordRoot))) {
-    throw serviceStartRefusal(coordRoot, undefined, "unknown");
-  }
-  if (existing) {
-    const liveness = statusOwnerIsLive(existing);
-    if (liveness !== "stopped") throw serviceStartRefusal(coordRoot, existing.pid, liveness);
-  }
-  const release = acquireServiceLease(coordRoot);
+  const current = readGovernorServiceStatus(coordRoot);
+  if (current.liveness !== "stopped")
+    throw startRefusal(coordRoot, current.record?.pid, current.liveness);
+  const { release } = acquireServiceLease(
+    serviceLeasePath(coordRoot),
+    (pid, liveness) => startRefusal(coordRoot, pid, liveness),
+    { running_build: installedHarneryBuild() },
+  );
   rmSync(serviceStopPath(coordRoot), { force: true });
   const now = new Date().toISOString();
   const status: GovernorServiceStatusRecord = {
     schema_version: GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION,
     pid: process.pid,
     start_token: processStartToken(process.pid) ?? undefined,
-    running_build: currentGovernorServiceBuild(),
+    running_build: installedHarneryBuild(),
     host: hostname(),
     nonce: randomUUID(),
     state: "starting",
@@ -781,114 +695,16 @@ function normalizeIsolation(value: unknown): PolicyIsolation | undefined {
   throw new Error("service isolation must be shared, worktree, sandbox, or remote");
 }
 
-function acquireServiceLease(coordRoot: string): () => void {
-  const path = serviceLeasePath(coordRoot);
-  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
-  const owner: ServiceLease = {
-    pid: process.pid,
-    start_token: processStartToken(process.pid) ?? undefined,
-    running_build: currentGovernorServiceBuild(),
-    host: hostname(),
-    nonce: randomUUID(),
-    created_at: new Date().toISOString(),
-  };
-  const acquire = (): boolean => {
-    try {
-      const fd = openSync(path, "wx", stateFileMode());
-      try {
-        writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
-      } finally {
-        closeSync(fd);
-      }
-      return true;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-      return false;
-    }
-  };
-  if (!acquire()) {
-    const existing = readLease(path);
-    const liveness = existing ? leaseOwnerIsLive(existing) : "unknown";
-    if (liveness !== "stopped") {
-      throw serviceStartRefusal(coordRoot, existing?.pid, liveness);
-    }
-    unlinkSync(path);
-    if (!acquire()) throw new Error("governor service lease raced with another process");
-  }
-  return () => {
-    try {
-      const existing = readLease(path);
-      if (existing?.nonce === owner.nonce) unlinkSync(path);
-    } catch {
-      // A stale lease is recoverable by the next explicit service start.
-    }
-  };
-}
-
-function readLease(path: string): ServiceLease | null {
-  try {
-    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<ServiceLease>;
-    return Number.isSafeInteger(value.pid) &&
-      (value.pid ?? 0) > 0 &&
-      typeof value.host === "string" &&
-      typeof value.nonce === "string" &&
-      typeof value.created_at === "string"
-      ? ({
-          ...value,
-          start_token: typeof value.start_token === "string" ? value.start_token : undefined,
-        } as ServiceLease)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function leaseOwnerIsLive(lease: ServiceLease): GovernorServiceStatus["liveness"] {
-  return observeGovernorServiceProcess({ ...lease, state: "running" }).liveness;
-}
-
-function readStatusRecord(coordRoot: string): GovernorServiceStatusRecord | undefined {
-  if (!existsSync(serviceStatusPath(coordRoot))) return undefined;
-  try {
-    const value = readBoundedJson<GovernorServiceStatusRecord>(
-      serviceStatusPath(coordRoot),
-      "governor service status",
-    );
-    if (
-      value.schema_version !== GOVERNOR_SERVICE_STATUS_SCHEMA_VERSION ||
-      !Number.isSafeInteger(value.pid) ||
-      value.pid < 1 ||
-      typeof value.host !== "string" ||
-      typeof value.nonce !== "string" ||
-      !validTimestamp(value.started_at) ||
-      !validTimestamp(value.heartbeat_at)
-    ) {
-      return undefined;
-    }
-    return {
-      ...value,
-      start_token: typeof value.start_token === "string" ? value.start_token : undefined,
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-function statusOwnerIsLive(record: GovernorServiceStatusRecord): GovernorServiceStatus["liveness"] {
-  return observeGovernorServiceProcess(record).liveness;
-}
-
-function serviceStartRefusal(
+function startRefusal(
   coordRoot: string,
   pid: number | undefined,
-  liveness: GovernorServiceStatus["liveness"],
+  liveness: ServiceLiveness,
 ): Error {
-  const reason =
-    liveness === "unknown"
-      ? `governor service process generation is unknown${pid ? ` for pid ${pid}` : ""}`
-      : `governor service process is still running under pid ${pid}`;
-  return new Error(
-    `${reason}; run \`${resolveBinName(coordRoot)} governor service stop\` to write a durable stop request before starting or reconfiguring it`,
+  return serviceStartRefusal(
+    "governor service",
+    `${resolveBinName(coordRoot)} governor service stop`,
+    pid,
+    liveness,
   );
 }
 

package/src/core/hooks/resolve/owner.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.ts";
 import { resolveOwnerBySessionEnv } from "../../agents/coord-client.ts";
 import { readLiveCoordinationRow } from "../../agents/state/live-coordination-view.ts";
-import { checkPidToken } from "../../agents/state/proc-start.ts";
+import { verifyProcessGeneration } from "../../agents/state/proc-start.ts";
 
 /**
  * Resolve the canonical `instance_id` for the current hook invocation.
@@ -98,7 +98,7 @@ export function resolveOwner(opts: {
           // A row whose start token disagrees with the process now holding this
           // pid is about a different, earlier process. Believing it hands this
           // session another agent's identity, so walk past it.
-          const recycled = checkPidToken(pid, startToken || undefined) === "mismatch";
+          const recycled = verifyProcessGeneration(pid, startToken) === "different";
           if (owner && owner.length > 0 && !recycled) {
             return {
               instance_id: owner,