harnery 0.43.0 → 0.45.0

package/dist/core/servers/index.js

@@ -14,30 +14,30 @@
  *     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.js";
 import { resolveCoordRoot } from "../agents/coord-client.js";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
-import { checkPidToken, processStartToken } from "../agents/state/proc-start.js";
+import { processStartToken, signalIfSameGeneration, verifyProcessGeneration, } from "../agents/state/proc-start.js";
 import { serverPortRange } from "../config.js";
 import { readCoordinationViewV3, requireAuthoritySafeCoordinationViewV3, } from "../events/v3/coordination-view.js";
 import { liveInstanceIdV3 } from "../events/v3/live-route-observer.js";
 import { resolveOwner } from "../hooks/resolve/owner.js";
 import { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+import { acquireNoClobberLease } from "../workflow/workspaces/leases.js";
 import { ancestry, establishedConnectionCounts, listListeningPorts, listListeningSockets, processStartedAt, readProcessInfo, scanSupport, } from "./net.js";
-import { tunnelServerId, tunnelServerInput } from "./tunnels.js";
+export { processStartToken, signalIfSameGeneration, verifyProcessGeneration, } from "../agents/state/proc-start.js";
+export { acquireNoClobberLease } from "../workflow/workspaces/leases.js";
 export { ancestry, establishedConnectionCounts, listListeningPorts, listListeningSockets, lsofConnectionCounts, lsofListeningSockets, parseElapsed, parseLsofListen, parseProcNetTcp, processStartedAt, psProcessInfo, readProcessInfo, scanSupport, } from "./net.js";
-export { tunnelServerId, tunnelServerInput } from "./tunnels.js";
-export const SERVER_RECORD_SCHEMA_VERSION = 1;
+export { createTunnelReadinessVerifier, tunnelServerId, tunnelServerInput } from "./tunnels.js";
+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;
@@ -86,34 +86,54 @@ export function registerServer(input, options) {
         !(Number.isInteger(input.port) && input.port > 0 && input.port < 65536))
         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 = {
-        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 = {};
+        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 = {
+            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). */
 export function tryRegisterServer(input, options) {
@@ -136,43 +156,106 @@ function callingOwner(coordRoot) {
         return undefined;
     }
 }
-/**
- * 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, options) {
+/** Remove only the exact registration receipt observed by the caller. */
+export function unregisterServer(record, options) {
     const coordRoot = rootOf(options);
-    if (!coordRoot || !isValidServerId(id))
+    if (!coordRoot || !record || !isValidServerId(record.id))
         return false;
-    const path = recordPath(coordRoot, id);
-    if (options?.pid !== undefined) {
-        const record = readRecord(path);
-        if (record && record.pid !== options.pid)
-            return false;
+    return withServerMutation(coordRoot, record.id, () => removeServerReceipt(coordRoot, record));
+}
+export function withServerRegistrationCustody(record, options, effect) {
+    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.then === "function")
+            return Promise.resolve(result).finally(() => lease.release());
+        lease.release();
+        return result;
+    }
+    catch (error) {
+        lease.release();
+        throw error;
     }
-    if (!existsSync(path))
+}
+function removeServerReceipt(coordRoot, record) {
+    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, { force: true });
+    rmSync(path);
     return true;
 }
+function serverMutationLease(coordRoot, id) {
+    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(coordRoot, id, operation) {
+    const lease = serverMutationLease(coordRoot, id);
+    try {
+        return operation();
+    }
+    finally {
+        lease.release();
+    }
+}
+function sameProcessCustody(a, b) {
+    const helpers = (record) => [...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, options) {
     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, options) {
     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(),
+        });
     });
 }
 /**
@@ -201,6 +284,8 @@ function readRecord(path) {
         const value = JSON.parse(readFileSync(path, "utf8"));
         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"))
             return null;
@@ -219,25 +304,42 @@ export function readServerRecords(options) {
         return [];
     return readdirSync(dir)
         .filter((name) => name.endsWith(".json"))
-        .map((name) => readRecord(join(dir, name)))
-        .filter((record) => 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));
 }
 export function pidAlive(pid) {
+    return processPresence(pid) !== "absent";
+}
+function processPresence(pid, probePid) {
     try {
+        if (probePid)
+            return probePid(pid) ? "present" : "absent";
         process.kill(pid, 0);
-        return true;
+        return "present";
     }
     catch (error) {
-        return error.code === "EPERM";
+        const code = error.code;
+        return code === "ESRCH" ? "absent" : code === "EPERM" ? "present" : "unknown";
     }
 }
-export function serverState(record) {
+function allProcessesAbsent(record, probePid) {
+    return [record.pid, ...(record.pids ?? [])].every((pid) => processPresence(pid, probePid) === "absent");
+}
+export function serverState(record, readToken, probePid) {
     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";
 }
 function ownerReader(coordRoot, ownerStaleMs, nowMs) {
     let view = null;
@@ -268,7 +370,6 @@ export function listServers(options) {
     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));
@@ -278,8 +379,8 @@ export function listServers(options) {
     const servers = [];
     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;
         }
@@ -316,27 +417,6 @@ export function listServers(options) {
         pruned,
     };
 }
-/** Register running tunnels that have no current record. Returns adopted ids. */
-export function adoptRunningTunnels(coordRoot) {
-    const adopted = [];
-    let states;
-    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,
@@ -350,10 +430,10 @@ const IGNORED_LISTENER_COMMANDS = [
  * a recorded port.
  */
 export function findUnregisteredListeners(coordRoot, servers) {
-    const running = servers.filter((server) => server.state === "running");
+    const registered = servers.filter((server) => server.record.host === hostname());
     const covered = new Set();
     const ports = new Set();
-    for (const { record } of running) {
+    for (const { record } of registered) {
         covered.add(record.pid);
         for (const pid of record.pids ?? [])
             covered.add(pid);
@@ -363,8 +443,9 @@ export function findUnregisteredListeners(coordRoot, servers) {
     const results = [];
     const seenPids = new Map();
     for (const socket of listListeningSockets()) {
-        if (ports.has(socket.port) || socket.pid === process.pid)
+        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)
@@ -380,6 +461,7 @@ export function findUnregisteredListeners(coordRoot, servers) {
             continue;
         results.push({
             pid: socket.pid,
+            ...(startToken ? { start_token: startToken } : {}),
             port: socket.port,
             address: socket.address,
             command: info.command.slice(0, 300),
@@ -430,72 +512,138 @@ export function planServerGc(views, policy) {
     });
 }
 /**
- * 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, options) {
     const coordRoot = rootOf(options);
+    if (!coordRoot)
+        return {
+            id: record.id,
+            stopped: false,
+            method: "refused",
+            generation: "unknown",
+            detail: "registration custody root is unavailable",
+        };
+    let lease;
+    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, coordRoot, options) {
     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, generation) => ({
+        id: record.id,
+        stopped: false,
+        method: "refused",
+        generation,
+        detail: `pid ${pid} generation is ${generation}; left the server record in place`,
+    });
     const finish = (result) => {
         if (result.stopped || result.method === "not-running")
-            unregisterServer(record.id, { coordRoot, pid: record.pid });
+            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"]) {
+        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, name) {
-    // 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, waitMs) {
+async function waitForExit(targets, waitMs, dependencies) {
     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";
 }
 /**
  * The first free port in the configured range for `type`
@@ -510,7 +658,8 @@ export function allocateServerPort(type, options) {
         return null;
     const taken = listListeningPorts();
     for (const record of readServerRecords({ coordRoot })) {
-        if (record.port && serverState(record) === "running")
+        const state = serverState(record);
+        if (record.port && (state === "running" || state === "unknown"))
             taken.add(record.port);
     }
     for (let port = range[0]; port <= range[1]; port++)
@@ -526,12 +675,15 @@ export function adoptServer(pid, options) {
     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);
@@ -543,6 +695,7 @@ export function adoptServer(pid, options) {
         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 } : {}),

package/dist/core/servers/tunnels.d.ts

@@ -1,14 +1,14 @@
 /**
  * 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 { type TunnelState } from "../../lib/tunnel/state.js";
-import type { RegisterServerInput } from "./index.js";
+import { type TunnelReadinessVerifier, type TunnelState } from "../../lib/tunnel/state.js";
+import { type RegisterServerInput, type ServerOptions } from "./index.js";
+/** Verify only witnesses saved by the original tunnel registration. */
+export declare function createTunnelReadinessVerifier(options: ServerOptions): TunnelReadinessVerifier;
 export declare function tunnelServerId(name: string): string;
-/** The registry input for one tunnel instance. */
+/** Register the new gate; saved helper PIDs have no generation witnesses. */
 export declare function tunnelServerInput(state: TunnelState, coordRoot: string): RegisterServerInput;
 //# sourceMappingURL=tunnels.d.ts.map

package/dist/core/servers/tunnels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnels.d.ts","sourceRoot":"","sources":["../../../src/core/servers/tunnels.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAmB5F"}
+{"version":3,"file":"tunnels.d.ts","sourceRoot":"","sources":["../../../src/core/servers/tunnels.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,mBAAmB,EAExB,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAEpB,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,aAAa,GAAG,uBAAuB,CAiC7F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAmB5F"}