harnery 0.43.0 → 0.45.0

package/src/core/servers/index.ts

@@ -14,21 +14,25 @@
  *     for `gc` once its starting agent has ended or been unobserved for a long
  *     time AND nobody has used the server for the idle window.
  *
- * Fail-closed rules: a record whose pid was recycled is treated as dead, never
- * signalled; an unreadable coordination view makes every owner `unknown`,
+ * Fail-closed rules: a record whose pid was recycled is never signalled;
+ * an unreadable start token or coordination view is `unknown`,
  * which `gc` never stops; a record without an owner is never stopped
  * automatically.
  */
 
-import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { hostname } from "node:os";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
-import { listStates } from "../../lib/tunnel/state.ts";
 import { resolveCoordRoot } from "../agents/coord-client.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
-import { checkPidToken, processStartToken } from "../agents/state/proc-start.ts";
+import {
+  type ProcessGenerationSignalDependencies,
+  type ProcessGenerationVerdict,
+  processStartToken,
+  signalIfSameGeneration,
+  verifyProcessGeneration,
+} from "../agents/state/proc-start.ts";
 import { serverPortRange } from "../config.ts";
 import {
   readCoordinationViewV3,
@@ -37,6 +41,7 @@ import {
 import { liveInstanceIdV3 } from "../events/v3/live-route-observer.ts";
 import { resolveOwner } from "../hooks/resolve/owner.ts";
 import { writePrivateJsonAtomic } from "../storage/atomic-json.ts";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.ts";
 import {
   ancestry,
   establishedConnectionCounts,
@@ -47,8 +52,13 @@ import {
   type ScanSupport,
   scanSupport,
 } from "./net.ts";
-import { tunnelServerId, tunnelServerInput } from "./tunnels.ts";
 
+export {
+  processStartToken,
+  signalIfSameGeneration,
+  verifyProcessGeneration,
+} from "../agents/state/proc-start.ts";
+export { acquireNoClobberLease } from "../workflow/workspaces/leases.ts";
 export {
   ancestry,
   establishedConnectionCounts,
@@ -64,9 +74,9 @@ export {
   readProcessInfo,
   scanSupport,
 } from "./net.ts";
-export { tunnelServerId, tunnelServerInput } from "./tunnels.ts";
+export { createTunnelReadinessVerifier, tunnelServerId, tunnelServerInput } from "./tunnels.ts";
 
-export const SERVER_RECORD_SCHEMA_VERSION = 1;
+export const SERVER_RECORD_SCHEMA_VERSION = 2;
 export const SERVER_DEFAULT_IDLE_HOURS = 2;
 export const SERVER_DEFAULT_OWNER_STALE_HOURS = 24;
 const TOUCH_INTERVAL_MS = 60_000;
@@ -76,6 +86,7 @@ export type ServerKind = "service" | "session";
 export interface ServerRecord {
   schema_version: typeof SERVER_RECORD_SCHEMA_VERSION;
   id: string;
+  registration_id: string;
   kind: ServerKind;
   /** Free-form family name: `preview`, `tunnel`, `dashboard`, ... */
   type: string;
@@ -87,13 +98,13 @@ export interface ServerRecord {
   start_token?: string;
   /** Further processes that belong to this server (helpers, children). */
   pids?: number[];
+  /** Generation witnesses captured when the further processes registered. */
+  pids_start_tokens?: Record<string, string>;
   host: string;
   /** What the server serves, usually a directory. */
   scope?: string;
   cwd?: string;
   log?: string;
-  /** Graceful stop command; signals are the fallback. */
-  stop_argv?: string[];
   owner?: { instance_id: string; name?: string };
   started_at: string;
   registered_at: string;
@@ -108,11 +119,12 @@ export interface RegisterServerInput {
   url?: string;
   port?: number;
   pid?: number;
+  /** Preserve an observed witness when adopting, rather than probing a new generation. */
+  start_token?: string;
   pids?: number[];
   scope?: string;
   cwd?: string;
   log?: string;
-  stop_argv?: string[];
   started_at?: string;
   /** `null` records no owner; omitted resolves the calling agent session. */
   owner?: { instance_id: string; name?: string } | null;
@@ -122,7 +134,7 @@ export interface ServerOptions {
   coordRoot?: string | null;
 }
 
-export type ServerState = "running" | "dead" | "other-host";
+export type ServerState = "running" | "dead" | "other-host" | "unknown";
 export type OwnerState = "live" | "abandoned" | "ended" | "unknown" | "none";
 
 export interface ServerView {
@@ -136,6 +148,8 @@ export interface ServerView {
 
 export interface UnregisteredListener {
   pid: number;
+  /** Captured during the scan, before a stop can be authorized. */
+  start_token?: string;
   port: number;
   address: string;
   command: string;
@@ -203,34 +217,57 @@ export function registerServer(
   )
     throw new Error(`invalid server port: ${input.port}`);
   const id = input.id ?? serverId(input.type, input.scope);
-  const now = new Date().toISOString();
-  const startToken = processStartToken(pid);
-  const owner = input.owner === undefined ? callingOwner(coordRoot) : (input.owner ?? undefined);
-  const record: ServerRecord = {
-    schema_version: SERVER_RECORD_SCHEMA_VERSION,
-    id,
-    kind: input.kind,
-    type: input.type,
-    label: input.label ?? id,
-    ...(input.url ? { url: input.url } : {}),
-    ...(input.port ? { port: input.port } : {}),
-    pid,
-    ...(startToken ? { start_token: startToken } : {}),
-    ...(input.pids?.length
-      ? { pids: input.pids.filter((p) => Number.isSafeInteger(p) && p > 0) }
-      : {}),
-    host: hostname(),
-    ...(input.scope ? { scope: resolve(input.scope) } : {}),
-    ...(input.cwd ? { cwd: resolve(input.cwd) } : {}),
-    ...(input.log ? { log: resolve(input.log) } : {}),
-    ...(input.stop_argv?.length ? { stop_argv: input.stop_argv } : {}),
-    ...(owner ? { owner } : {}),
-    started_at: input.started_at ?? now,
-    registered_at: now,
-    last_active_at: now,
-  };
-  writePrivateJsonAtomic(recordPath(coordRoot, id), record);
-  return record;
+  return withServerMutation(coordRoot, id, () => {
+    const path = recordPath(coordRoot, id);
+    const now = new Date().toISOString();
+    const startToken = input.start_token ?? processStartToken(pid);
+    const pids = [...new Set(input.pids?.filter((p) => Number.isSafeInteger(p) && p > 0))];
+    const pidsStartTokens: Record<string, string> = {};
+    for (const auxiliaryPid of pids) {
+      const token = processStartToken(auxiliaryPid);
+      if (token) pidsStartTokens[auxiliaryPid] = token;
+    }
+    const owner = input.owner === undefined ? callingOwner(coordRoot) : (input.owner ?? undefined);
+    const record: ServerRecord = {
+      schema_version: SERVER_RECORD_SCHEMA_VERSION,
+      id,
+      registration_id: randomUUID(),
+      kind: input.kind,
+      type: input.type,
+      label: input.label ?? id,
+      ...(input.url ? { url: input.url } : {}),
+      ...(input.port ? { port: input.port } : {}),
+      pid,
+      ...(startToken ? { start_token: startToken } : {}),
+      ...(pids.length ? { pids, pids_start_tokens: pidsStartTokens } : {}),
+      host: hostname(),
+      ...(input.scope ? { scope: resolve(input.scope) } : {}),
+      ...(input.cwd ? { cwd: resolve(input.cwd) } : {}),
+      ...(input.log ? { log: resolve(input.log) } : {}),
+      ...(owner ? { owner } : {}),
+      started_at: input.started_at ?? now,
+      registered_at: now,
+      last_active_at: now,
+    };
+    if (
+      input.start_token !== undefined &&
+      verifyProcessGeneration(pid, input.start_token) !== "same"
+    )
+      throw new Error(`pid ${pid} generation could not be verified before registration`);
+    if (existsSync(path)) {
+      const existing = readRecord(path);
+      if (!existing)
+        throw new Error(
+          `registration ${id} custody is unknown: invalid or older server record retained`,
+        );
+      if (sameProcessCustody(existing, record) && serverState(existing) === "running")
+        return existing;
+      if (existing.host !== hostname() || !allProcessesAbsent(existing))
+        throw new Error(`registration ${id} custody is held by a live or unverifiable server`);
+    }
+    writePrivateJsonAtomic(path, record);
+    return record;
+  });
 }
 
 /** Best-effort registration that never throws (for server start paths). */
@@ -256,39 +293,132 @@ function callingOwner(coordRoot: string): ServerRecord["owner"] {
   }
 }
 
-/**
- * Remove a server's record. With `pid`, only a record still naming that pid
- * is removed, so a replacement that re-registered the same id survives.
- */
-export function unregisterServer(id: string, options?: ServerOptions & { pid?: number }): boolean {
+/** Remove only the exact registration receipt observed by the caller. */
+export function unregisterServer(record: ServerRecord, options?: ServerOptions): boolean {
   const coordRoot = rootOf(options);
-  if (!coordRoot || !isValidServerId(id)) return false;
-  const path = recordPath(coordRoot, id);
-  if (options?.pid !== undefined) {
-    const record = readRecord(path);
-    if (record && record.pid !== options.pid) return false;
+  if (!coordRoot || !record || !isValidServerId(record.id)) return false;
+  return withServerMutation(coordRoot, record.id, () => removeServerReceipt(coordRoot, record));
+}
+
+/** Hold the exact registration receipt until a synchronous or asynchronous effect settles. */
+export function withServerRegistrationCustody<T>(
+  record: ServerRecord,
+  options: ServerOptions,
+  effect: () => PromiseLike<T>,
+): Promise<T>;
+export function withServerRegistrationCustody<T>(
+  record: ServerRecord,
+  options: ServerOptions,
+  effect: () => T,
+): T;
+export function withServerRegistrationCustody<T>(
+  record: ServerRecord,
+  options: ServerOptions,
+  effect: () => T | PromiseLike<T>,
+): T | Promise<T> {
+  const coordRoot = rootOf(options);
+  if (!coordRoot) throw new Error("registration custody root is unavailable");
+  const lease = serverMutationLease(coordRoot, record.id);
+  try {
+    const current = readServer(record.id, { coordRoot });
+    if (
+      !current ||
+      current.registration_id !== record.registration_id ||
+      !sameProcessCustody(current, record)
+    )
+      throw new Error(`registration ${record.id} custody changed`);
+    const result = effect();
+    if (
+      result !== null &&
+      (typeof result === "object" || typeof result === "function") &&
+      typeof (result as PromiseLike<T>).then === "function"
+    )
+      return Promise.resolve(result).finally(() => lease.release());
+    lease.release();
+    return result as T;
+  } catch (error) {
+    lease.release();
+    throw error;
   }
-  if (!existsSync(path)) return false;
-  rmSync(path, { force: true });
+}
+
+function removeServerReceipt(coordRoot: string, record: ServerRecord): boolean {
+  const path = recordPath(coordRoot, record.id);
+  const current = readRecord(path);
+  if (
+    !current ||
+    current.registration_id !== record.registration_id ||
+    !sameProcessCustody(current, record)
+  )
+    return false;
+  rmSync(path);
   return true;
 }
 
+function serverMutationLease(coordRoot: string, id: string) {
+  recordPath(coordRoot, id);
+  const scope = `server-registration-${id}`;
+  return acquireNoClobberLease({
+    path: join(serversDir(coordRoot), ".custody", id),
+    scope,
+    authoritySha256: createHash("sha256").update(scope).digest("hex"),
+    staleAfterMs: 1,
+  });
+}
+
+function withServerMutation<T>(coordRoot: string, id: string, operation: () => T): T {
+  const lease = serverMutationLease(coordRoot, id);
+  try {
+    return operation();
+  } finally {
+    lease.release();
+  }
+}
+
+function sameProcessCustody(a: ServerRecord, b: ServerRecord): boolean {
+  const helpers = (record: ServerRecord) =>
+    [...new Set(record.pids ?? [])]
+      .sort((x, y) => x - y)
+      .map((pid) => [pid, record.pids_start_tokens?.[pid] ?? null]);
+  return (
+    a.schema_version === SERVER_RECORD_SCHEMA_VERSION &&
+    b.schema_version === SERVER_RECORD_SCHEMA_VERSION &&
+    a.id === b.id &&
+    a.pid === b.pid &&
+    a.start_token === b.start_token &&
+    a.host === b.host &&
+    a.kind === b.kind &&
+    a.type === b.type &&
+    a.scope === b.scope &&
+    a.owner?.instance_id === b.owner?.instance_id &&
+    JSON.stringify(helpers(a)) === JSON.stringify(helpers(b))
+  );
+}
+
 export function readServer(id: string, options?: ServerOptions): ServerRecord | null {
   const coordRoot = rootOf(options);
   if (!coordRoot || !isValidServerId(id)) return null;
-  return readRecord(recordPath(coordRoot, id));
+  const path = recordPath(coordRoot, id);
+  const record = readRecord(path);
+  if (!record && existsSync(path))
+    throw new Error(
+      `server record ${id} is invalid or uses an older schema; retained without custody`,
+    );
+  return record;
 }
 
 /** Mark a server as used now. */
 export function touchServer(id: string, options?: ServerOptions & { now?: Date }): void {
   const coordRoot = rootOf(options);
   if (!coordRoot || !isValidServerId(id)) return;
-  const path = recordPath(coordRoot, id);
-  const record = readRecord(path);
-  if (!record) return;
-  writePrivateJsonAtomic(path, {
-    ...record,
-    last_active_at: (options?.now ?? new Date()).toISOString(),
+  withServerMutation(coordRoot, id, () => {
+    const path = recordPath(coordRoot, id);
+    const record = readRecord(path);
+    if (!record) return;
+    writePrivateJsonAtomic(path, {
+      ...record,
+      last_active_at: (options?.now ?? new Date()).toISOString(),
+    });
   });
 }
 
@@ -317,6 +447,8 @@ function readRecord(path: string): ServerRecord | null {
     if (
       value?.schema_version !== SERVER_RECORD_SCHEMA_VERSION ||
       typeof value.id !== "string" ||
+      typeof value.registration_id !== "string" ||
+      !/^[0-9a-f-]{36}$/.test(value.registration_id) ||
       !Number.isSafeInteger(value.pid) ||
       (value.kind !== "service" && value.kind !== "session")
     )
@@ -334,8 +466,14 @@ export function readServerRecords(options?: ServerOptions): ServerRecord[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir)
     .filter((name) => name.endsWith(".json"))
-    .map((name) => readRecord(join(dir, name)))
-    .filter((record): record is ServerRecord => record !== null)
+    .map((name) => {
+      const record = readRecord(join(dir, name));
+      if (!record)
+        throw new Error(
+          `server record ${name} is invalid or uses an older schema; retained without custody`,
+        );
+      return record;
+    })
     .sort(
       (a, b) =>
         a.kind.localeCompare(b.kind) || a.type.localeCompare(b.type) || a.id.localeCompare(b.id),
@@ -343,18 +481,40 @@ export function readServerRecords(options?: ServerOptions): ServerRecord[] {
 }
 
 export function pidAlive(pid: number): boolean {
+  return processPresence(pid) !== "absent";
+}
+
+function processPresence(
+  pid: number,
+  probePid?: (pid: number) => boolean,
+): "present" | "absent" | "unknown" {
   try {
+    if (probePid) return probePid(pid) ? "present" : "absent";
     process.kill(pid, 0);
-    return true;
+    return "present";
   } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "EPERM";
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "ESRCH" ? "absent" : code === "EPERM" ? "present" : "unknown";
   }
 }
 
-export function serverState(record: ServerRecord): ServerState {
+function allProcessesAbsent(record: ServerRecord, probePid?: (pid: number) => boolean): boolean {
+  return [record.pid, ...(record.pids ?? [])].every(
+    (pid) => processPresence(pid, probePid) === "absent",
+  );
+}
+
+export function serverState(
+  record: ServerRecord,
+  readToken?: (pid: number) => string | null,
+  probePid?: (pid: number) => boolean,
+): ServerState {
   if (record.host !== hostname()) return "other-host";
-  if (!pidAlive(record.pid)) return "dead";
-  return checkPidToken(record.pid, record.start_token) === "mismatch" ? "dead" : "running";
+  const presence = processPresence(record.pid, probePid);
+  if (presence === "absent") return allProcessesAbsent(record, probePid) ? "dead" : "unknown";
+  if (presence === "unknown") return "unknown";
+  const verdict = verifyProcessGeneration(record.pid, record.start_token, readToken);
+  return verdict === "same" ? "running" : verdict === "different" ? "dead" : "unknown";
 }
 
 type OwnerReader = (instanceId: string) => OwnerState;
@@ -395,7 +555,6 @@ export function listServers(options?: ListServersOptions): ServersReport {
   const now = options?.now ?? new Date();
   const nowMs = now.getTime();
   const ownerStaleMs = hours(options?.ownerStaleHours ?? SERVER_DEFAULT_OWNER_STALE_HOURS);
-  adoptRunningTunnels(coordRoot);
   const records = readServerRecords({ coordRoot });
   const ownerOf = ownerReader(coordRoot, ownerStaleMs, nowMs);
   const states = records.map((record) => serverState(record));
@@ -407,8 +566,8 @@ export function listServers(options?: ListServersOptions): ServersReport {
   const servers: ServerView[] = [];
   records.forEach((record, i) => {
     const state = states[i]!;
-    if (state === "dead" && options?.prune !== false) {
-      unregisterServer(record.id, { coordRoot, pid: record.pid });
+    if (state === "dead" && allProcessesAbsent(record) && options?.prune !== false) {
+      unregisterServer(record, { coordRoot });
       pruned.push(record.id);
       return;
     }
@@ -446,24 +605,6 @@ export function listServers(options?: ListServersOptions): ServersReport {
   };
 }
 
-/** Register running tunnels that have no current record. Returns adopted ids. */
-export function adoptRunningTunnels(coordRoot: string): string[] {
-  const adopted: string[] = [];
-  let states: ReturnType<typeof listStates>;
-  try {
-    states = listStates(coordRoot);
-  } catch {
-    return adopted;
-  }
-  for (const state of states) {
-    if (!state.gate_pid || !pidAlive(state.gate_pid)) continue;
-    const id = tunnelServerId(state.name);
-    if (readServer(id, { coordRoot })?.pid === state.gate_pid) continue;
-    if (tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot })) adopted.push(id);
-  }
-  return adopted;
-}
-
 /** Processes that browser automation and editors start; never project servers. */
 const IGNORED_LISTENER_COMMANDS = [
   /(^|\/)(chrome|chromium|chrome-headless-shell|headless_shell|msedge|firefox)( |$)/i,
@@ -481,10 +622,10 @@ export function findUnregisteredListeners(
   coordRoot: string,
   servers: Array<Pick<ServerView, "record" | "state">>,
 ): UnregisteredListener[] {
-  const running = servers.filter((server) => server.state === "running");
+  const registered = servers.filter((server) => server.record.host === hostname());
   const covered = new Set<number>();
   const ports = new Set<number>();
-  for (const { record } of running) {
+  for (const { record } of registered) {
     covered.add(record.pid);
     for (const pid of record.pids ?? []) covered.add(pid);
     if (record.port) ports.add(record.port);
@@ -492,7 +633,8 @@ export function findUnregisteredListeners(
   const results: UnregisteredListener[] = [];
   const seenPids = new Map<number, boolean>();
   for (const socket of listListeningSockets()) {
-    if (ports.has(socket.port) || socket.pid === process.pid) continue;
+    if (ports.has(socket.port) || covered.has(socket.pid) || socket.pid === process.pid) continue;
+    const startToken = processStartToken(socket.pid);
     let inside = seenPids.get(socket.pid);
     const info = readProcessInfo(socket.pid);
     if (!info) continue;
@@ -506,6 +648,7 @@ export function findUnregisteredListeners(
     if (!inside) continue;
     results.push({
       pid: socket.pid,
+      ...(startToken ? { start_token: startToken } : {}),
       port: socket.port,
       address: socket.address,
       command: info.command.slice(0, 300),
@@ -568,77 +711,156 @@ export function planServerGc(views: ServerView[], policy?: GcPolicy): GcDecision
 export interface StopResult {
   id: string;
   stopped: boolean;
-  method: "not-running" | "stop-command" | "signal" | "refused";
+  method: "not-running" | "signal" | "refused";
+  generation?: ProcessGenerationVerdict;
   detail?: string;
 }
 
+export interface ServerProcessDependencies extends ProcessGenerationSignalDependencies {
+  probePid?: (pid: number) => boolean;
+}
+
 /**
- * Stop one server: its graceful stop command first when recorded, then
- * SIGTERM to its process group, then SIGKILL after the grace period. A pid
- * whose start token no longer matches is never signalled.
+ * Stop a verified server with SIGTERM, then SIGKILL after the grace period.
+ * Every signal targets one retained process handle, including auxiliary processes.
+ * Each target requires a fresh generation check. Unknown or different generations retain the record.
  */
 export async function stopServer(
   record: ServerRecord,
-  options?: ServerOptions & { graceMs?: number },
+  options?: ServerOptions & {
+    graceMs?: number;
+    signalDependencies?: ServerProcessDependencies;
+  },
 ): Promise<StopResult> {
   const coordRoot = rootOf(options);
+  if (!coordRoot)
+    return {
+      id: record.id,
+      stopped: false,
+      method: "refused",
+      generation: "unknown",
+      detail: "registration custody root is unavailable",
+    };
+  let lease: ReturnType<typeof serverMutationLease>;
+  try {
+    lease = serverMutationLease(coordRoot, record.id);
+  } catch {
+    return {
+      id: record.id,
+      stopped: false,
+      method: "refused",
+      generation: "unknown",
+      detail: "registration custody is unavailable",
+    };
+  }
+  try {
+    const current = readServer(record.id, { coordRoot });
+    if (!current || current.registration_id !== record.registration_id)
+      return {
+        id: record.id,
+        stopped: false,
+        method: "refused",
+        generation: "unknown",
+        detail: "registration custody changed; retained current server",
+      };
+    return await stopServerWithCustody(record, coordRoot, options);
+  } finally {
+    lease.release();
+  }
+}
+
+async function stopServerWithCustody(
+  record: ServerRecord,
+  coordRoot: string,
+  options?: ServerOptions & { graceMs?: number; signalDependencies?: ServerProcessDependencies },
+): Promise<StopResult> {
   const graceMs = options?.graceMs ?? 5_000;
+  const dependencies = options?.signalDependencies ?? {};
+  const targets = [
+    { pid: record.pid, token: record.start_token },
+    ...[...new Set(record.pids ?? [])]
+      .filter((pid) => pid !== record.pid)
+      .map((pid) => ({ pid, token: record.pids_start_tokens?.[pid] })),
+  ];
+  const refuse = (pid: number, generation: ProcessGenerationVerdict): StopResult => ({
+    id: record.id,
+    stopped: false,
+    method: "refused",
+    generation,
+    detail: `pid ${pid} generation is ${generation}; left the server record in place`,
+  });
   const finish = (result: StopResult): StopResult => {
-    if (result.stopped || result.method === "not-running")
-      unregisterServer(record.id, { coordRoot, pid: record.pid });
+    if (result.stopped || result.method === "not-running") removeServerReceipt(coordRoot, record);
     return result;
   };
-  const state = serverState(record);
-  if (state === "other-host")
+  if (record.host !== hostname())
     return { id: record.id, stopped: false, method: "refused", detail: `runs on ${record.host}` };
-  if (state === "dead") return finish({ id: record.id, stopped: false, method: "not-running" });
-
-  if (record.stop_argv?.length) {
-    const [command, ...args] = record.stop_argv;
-    spawnSync(command!, args, { stdio: "ignore", timeout: 30_000, cwd: record.cwd });
-    if (await exited(record, graceMs))
-      return finish({ id: record.id, stopped: true, method: "stop-command" });
+  const leaderPresence = processPresence(record.pid, dependencies.probePid);
+  if (
+    leaderPresence === "unknown" ||
+    (leaderPresence === "absent" && !allProcessesAbsent(record, dependencies.probePid))
+  )
+    return refuse(record.pid, "unknown");
+  // Check every recorded live process before sending the first signal.
+  for (const target of targets) {
+    const presence = processPresence(target.pid, dependencies.probePid);
+    if (presence === "absent") continue;
+    if (presence === "unknown") return refuse(target.pid, "unknown");
+    const verdict = verifyProcessGeneration(target.pid, target.token, dependencies.readToken);
+    if (verdict !== "same") return refuse(target.pid, verdict);
   }
-  signal(record.pid, "SIGTERM");
-  for (const pid of record.pids ?? []) signal(pid, "SIGTERM");
-  if (await exited(record, graceMs))
-    return finish({ id: record.id, stopped: true, method: "signal" });
-  if (serverState(record) === "running") {
-    signal(record.pid, "SIGKILL");
-    for (const pid of record.pids ?? []) signal(pid, "SIGKILL");
+  if (targets.every((target) => processPresence(target.pid, dependencies.probePid) === "absent"))
+    return finish({ id: record.id, stopped: false, method: "not-running" });
+
+  const current = readServer(record.id, { coordRoot });
+  if (!current || !sameProcessCustody(current, record)) return refuse(record.pid, "unknown");
+  for (const name of ["SIGTERM", "SIGKILL"] as const) {
+    for (const target of targets) {
+      const presence = processPresence(target.pid, dependencies.probePid);
+      if (presence === "absent") continue;
+      if (presence === "unknown") return refuse(target.pid, "unknown");
+      const result = signalIfSameGeneration(target.pid, target.token, name, dependencies);
+      if (!result.sent || result.verdict !== "same")
+        return refuse(target.pid, result.verdict === "same" ? "unknown" : result.verdict);
+    }
+    const observed = await waitForExit(targets, name === "SIGTERM" ? graceMs : 2_000, dependencies);
+    if (observed.refused) return refuse(observed.refused.pid, observed.refused.verdict);
+    if (observed.exited)
+      return finish({ id: record.id, stopped: true, method: "signal", generation: "same" });
   }
-  const stopped = await exited(record, 2_000);
-  return finish({
+  return {
     id: record.id,
-    stopped,
+    stopped: false,
     method: "signal",
-    ...(stopped ? {} : { detail: "process survived SIGKILL" }),
-  });
-}
-
-function signal(pid: number, name: NodeJS.Signals): void {
-  // Detached servers lead their own process group; signal the group so a
-  // wrapper (npm, bunx) does not orphan the real listener.
-  try {
-    process.kill(-pid, name);
-    return;
-  } catch {
-    // Not a group leader, or already gone.
-  }
-  try {
-    process.kill(pid, name);
-  } catch {
-    // Already gone.
-  }
+    generation: "same",
+    detail: "process survived SIGKILL",
+  };
 }
 
-async function exited(record: ServerRecord, waitMs: number): Promise<boolean> {
+async function waitForExit(
+  targets: Array<{ pid: number; token: string | undefined }>,
+  waitMs: number,
+  dependencies: ServerProcessDependencies,
+): Promise<{
+  exited: boolean;
+  refused?: { pid: number; verdict: ProcessGenerationVerdict };
+}> {
   const deadline = Date.now() + waitMs;
-  while (Date.now() < deadline) {
-    if (serverState(record) !== "running") return true;
+  while (true) {
+    let live = false;
+    for (const target of targets) {
+      const presence = processPresence(target.pid, dependencies.probePid);
+      if (presence === "absent") continue;
+      if (presence === "unknown")
+        return { exited: false, refused: { pid: target.pid, verdict: "unknown" } };
+      const verdict = verifyProcessGeneration(target.pid, target.token, dependencies.readToken);
+      if (verdict !== "same") return { exited: false, refused: { pid: target.pid, verdict } };
+      live = true;
+    }
+    if (!live) return { exited: true };
+    if (Date.now() >= deadline) return { exited: false };
     await new Promise((r) => setTimeout(r, 100));
   }
-  return serverState(record) !== "running";
 }
 
 /**
@@ -653,7 +875,8 @@ export function allocateServerPort(type: string, options?: ServerOptions): numbe
   if (!range) return null;
   const taken = listListeningPorts();
   for (const record of readServerRecords({ coordRoot })) {
-    if (record.port && serverState(record) === "running") taken.add(record.port);
+    const state = serverState(record);
+    if (record.port && (state === "running" || state === "unknown")) taken.add(record.port);
   }
   for (let port = range[0]; port <= range[1]; port++) if (!taken.has(port)) return port;
   throw new Error(`no free port for ${type} in ${range[0]}-${range[1]}`);
@@ -666,6 +889,10 @@ export interface AdoptOptions extends ServerOptions {
   scope?: string;
   /** `self` (default) records the adopting agent as owner; `none` records no owner. */
   owner?: "self" | "none";
+  dependencies?: {
+    listServers?: typeof listServers;
+    readToken?: (pid: number) => string | null;
+  };
 }
 
 /**
@@ -675,12 +902,19 @@ export interface AdoptOptions extends ServerOptions {
 export function adoptServer(pid: number, options?: AdoptOptions): ServerRecord {
   const coordRoot = rootOf(options);
   if (!coordRoot) throw new Error("no Harnery project found (coordination root did not resolve)");
-  const report = listServers({ coordRoot, sample: false });
+  const report = (options?.dependencies?.listServers ?? listServers)({ coordRoot, sample: false });
   const listeners = report.unregistered.filter((item) => item.pid === pid);
   if (!listeners.length)
     throw new Error(`pid ${pid} is not an unregistered listener inside this project`);
   const ports = listeners.map((item) => item.port).sort((a, b) => a - b);
   const first = listeners[0]!;
+  const generation = verifyProcessGeneration(
+    pid,
+    first.start_token,
+    options?.dependencies?.readToken,
+  );
+  if (generation !== "same")
+    throw new Error(`pid ${pid} generation is ${generation}; adoption refused`);
   const type = options?.type ?? "adopted";
   const scope = options?.scope ?? first.cwd ?? undefined;
   const started = processStartedAt(pid);
@@ -693,6 +927,7 @@ export function adoptServer(pid: number, options?: AdoptOptions): ServerRecord {
       url: `http://127.0.0.1:${ports[0]}/`,
       port: ports[0],
       pid,
+      start_token: first.start_token,
       ...(scope ? { scope } : {}),
       ...(first.cwd ? { cwd: first.cwd } : {}),
       ...(options?.owner === "none" ? { owner: null } : {}),