Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

prevent concurrent daemon supervisors after updates (#396)

ktf64f660fbdd3
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index e0e62a2db8..9a2424649f 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -7,6 +7,7 @@
- Added compact file change stats to collapsed tool calls and an agent-run edit total above the recap.
- Changed tool expansion hints to appear only on the latest tool row instead of every tool call ([ENG-4583](https://linear.app/primeintellect/issue/ENG-4583/too-many-ctrlo-alerts)).
- Changed IPython kernels to set `NO_COLOR=1`, preventing ANSI color escapes from inflating `%%bash` output.
+- Fixed update restarts starting concurrent daemon supervisors or unlinking a replacement supervisor's socket ([ENG-4600](https://linear.app/primeintellect/issue/ENG-4600/prevent-concurrent-daemon-supervisors-after-update-restart)).
- Changed provider, model, and MCP setup to use one tabbed configuration menu ([ENG-4539](https://linear.app/primeintellect/issue/ENG-4539/unify-providers-models-and-mcp-connections-menu)).
- Changed the shared configuration menu to show prominent, responsive tabs with configurable navigation shortcuts ([ENG-4534](https://linear.app/primeintellect/issue/ENG-4534/make-login-tabs-more-obvious)).
- Fixed Prime Inference login leaving new sessions without a persisted model selection ([ENG-4573](https://linear.app/primeintellect/issue/ENG-4573/prompt-for-model-selection-after-prime-inference-login)).
diff --git a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts b/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
index 212eddbafa..5044dd4bd1 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-protocol.ts
@@ -534,6 +534,12 @@ export type DaemonOutbound =
supervisorGeneration?: string;
/** Diagnostic process identity for attributing supervisor replacement. */
supervisorPid?: number;
+ /** Durable owner marker for validating update handoff fences. */
+ supervisorOwnerToken?: string;
+ /** Process start identity captured when the durable owner was published. */
+ supervisorProcessStartId?: string;
+ /** Normalized socket identity stored in the durable owner record. */
+ supervisorSocketPath?: string;
clientId: DaemonClientId;
serverCapabilities: readonly DaemonClientCapability[];
}
diff --git a/packages/coding-agent/src/modes/daemon/daemon-socket.ts b/packages/coding-agent/src/modes/daemon/daemon-socket.ts
index 8a79157295..970cbd049d 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-socket.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-socket.ts
@@ -11,6 +11,23 @@ const DAEMON_SOCKET_RELEASE_POLL_MS = 25;
const DAEMON_SOCKET_LOCK_STALE_MS = 5000;
const DAEMON_SOCKET_LOCK_UPDATE_MS = 1000;
+export class DaemonSocketPathLease {
+ private released = false;
+
+ constructor(
+ readonly socketPath: string,
+ private readonly releaseLock: () => Promise<void>,
+ ) {}
+
+ async release(): Promise<void> {
+ if (this.released) {
+ return;
+ }
+ this.released = true;
+ await this.releaseLock();
+ }
+}
+
export interface DaemonSocketIdentity {
dev: number;
ino: number;
@@ -23,17 +40,10 @@ export function defaultDaemonSocketPath(): string {
return join(defaultDaemonSocketDir(), "daemon.sock");
}
-export async function prepareDaemonSocketPath(socketPath: string): Promise<void> {
+export async function acquireDaemonSocketPathLease(socketPath: string): Promise<DaemonSocketPathLease | undefined> {
ensureDefaultDaemonSocketDir(socketPath);
-
if (process.platform === "win32") {
- return;
- }
- if (!existsSync(socketPath)) {
- return;
- }
- if (await canConnectToUnixSocket(socketPath)) {
- throw new Error(`Daemon socket already in use: ${socketPath}`);
+ return undefined;
}
const releaseLock = await lockfile.lock(socketPath, {
realpath: false,
@@ -46,10 +56,31 @@ export async function prepareDaemonSocketPath(socketPath: string): Promise<void>
maxTimeout: DAEMON_SOCKET_RELEASE_POLL_MS,
},
});
+ return new DaemonSocketPathLease(socketPath, releaseLock);
+}
+
+export async function prepareDaemonSocketPath(socketPath: string, lease?: DaemonSocketPathLease): Promise<void> {
+ ensureDefaultDaemonSocketDir(socketPath);
+
+ if (process.platform === "win32") {
+ return;
+ }
+ if (lease) {
+ assertSocketLease(socketPath, lease);
+ await prepareUnixDaemonSocketPath(socketPath);
+ return;
+ }
+ if (!existsSync(socketPath)) {
+ return;
+ }
+ if (await canConnectToUnixSocket(socketPath)) {
+ throw new Error(`Daemon socket already in use: ${socketPath}`);
+ }
+ const ownedLease = await acquireDaemonSocketPathLease(socketPath);
try {
await prepareUnixDaemonSocketPath(socketPath);
} finally {
- await releaseLock();
+ await ownedLease?.release();
}
}
@@ -116,10 +147,23 @@ export function getDaemonSocketIdentity(socketPath: string): DaemonSocketIdentit
return { dev: stat.dev, ino: stat.ino };
}
-export function cleanupDaemonSocketPath(socketPath: string, expectedIdentity?: DaemonSocketIdentity): void {
+export function cleanupDaemonSocketPath(
+ socketPath: string,
+ expectedIdentity?: DaemonSocketIdentity,
+ lease?: DaemonSocketPathLease,
+): void {
if (process.platform === "win32") {
return;
}
+ if (lease) {
+ assertSocketLease(socketPath, lease);
+ try {
+ cleanupUnixDaemonSocketPath(socketPath, expectedIdentity);
+ } catch {
+ // Best effort cleanup; shutdown should not be blocked by socket unlink failures.
+ }
+ return;
+ }
let releaseLock: (() => void) | undefined;
try {
releaseLock = lockfile.lockSync(socketPath, {
@@ -132,20 +176,7 @@ export function cleanupDaemonSocketPath(socketPath: string, expectedIdentity?: D
return;
}
try {
- if (!existsSync(socketPath)) {
- return;
- }
- if (expectedIdentity) {
- const currentIdentity = getDaemonSocketIdentity(socketPath);
- if (
- !currentIdentity ||
- currentIdentity.dev !== expectedIdentity.dev ||
- currentIdentity.ino !== expectedIdentity.ino
- ) {
- return;
- }
- }
- unlinkSync(socketPath);
+ cleanupUnixDaemonSocketPath(socketPath, expectedIdentity);
} catch {
// Best effort cleanup; shutdown should not be blocked by socket unlink failures.
} finally {
@@ -157,6 +188,29 @@ export function cleanupDaemonSocketPath(socketPath: string, expectedIdentity?: D
}
}
+function cleanupUnixDaemonSocketPath(socketPath: string, expectedIdentity?: DaemonSocketIdentity): void {
+ if (!existsSync(socketPath)) {
+ return;
+ }
+ if (expectedIdentity) {
+ const currentIdentity = getDaemonSocketIdentity(socketPath);
+ if (
+ !currentIdentity ||
+ currentIdentity.dev !== expectedIdentity.dev ||
+ currentIdentity.ino !== expectedIdentity.ino
+ ) {
+ return;
+ }
+ }
+ unlinkSync(socketPath);
+}
+
+function assertSocketLease(socketPath: string, lease: DaemonSocketPathLease): void {
+ if (lease.socketPath !== socketPath) {
+ throw new Error(`Daemon socket lease does not match ${socketPath}`);
+ }
+}
+
export function defaultDaemonSocketDir(): string {
const suffix = typeof process.getuid === "function" ? String(process.getuid()) : "user";
return join(tmpdir(), `prime-agent-${suffix}`);
diff --git a/packages/coding-agent/src/modes/daemon/daemon-supervisor-ownership.ts b/packages/coding-agent/src/modes/daemon/daemon-supervisor-ownership.ts
new file mode 100644
index 0000000000..3e989e0fc9
--- /dev/null
+++ b/packages/coding-agent/src/modes/daemon/daemon-supervisor-ownership.ts
@@ -0,0 +1,556 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ realpathSync,
+ renameSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import { getProcessStartId } from "../../core/session-lease.js";
+import { defaultDaemonSocketDir } from "./daemon-socket.js";
+
+const DAEMON_SUPERVISOR_REGISTRY_DIR_ENV = "PRIME_AGENT_INTERNAL_DAEMON_SUPERVISOR_REGISTRY_DIR";
+
+const OWNER_VERSION = 1;
+const REGISTRY_LOCK_STALE_MS = 5000;
+const REGISTRY_LOCK_UPDATE_MS = 1000;
+const REGISTRY_LOCK_RETRIES = 500;
+const REGISTRY_LOCK_RETRY_MS = 10;
+const STARTUP_FENCE_POLL_MS = 250;
+
+type DaemonSupervisorOwnerPhase = "starting" | "owner" | "stopping";
+
+interface ProcessIdentity {
+ pid: number;
+ processStartId?: string;
+}
+
+interface DaemonSupervisorOwnerRecord extends ProcessIdentity {
+ version: 1;
+ role: "supervisor";
+ token: string;
+ generation: string;
+ socketPath: string;
+ descriptorDir: string;
+ agentDir: string;
+ appVersion: string;
+ phase: DaemonSupervisorOwnerPhase;
+ createdAt: string;
+ updatedAt: string;
+}
+
+interface DaemonSupervisorOwnerScope {
+ version: 1;
+ role: "supervisor";
+ token: string;
+ generation: string;
+ socketPath: string;
+ descriptorDir: string;
+}
+
+interface DaemonStartupFenceRecord extends ProcessIdentity {
+ version: 1;
+ token: string;
+ ownerToken: string;
+ socketPath: string;
+ supervisorGeneration: string;
+ createdAt: string;
+}
+
+interface DaemonSupervisorHelloIdentity {
+ supervisorGeneration?: string;
+ supervisorOwnerToken?: string;
+ supervisorPid?: number;
+ supervisorProcessStartId?: string;
+ supervisorSocketPath?: string;
+}
+
+interface AcquireDaemonSupervisorOwnershipOptions {
+ socketPath: string;
+ descriptorDir: string;
+ agentDir: string;
+ generation: string;
+ appVersion: string;
+ registryDir?: string;
+}
+
+class DaemonSupervisorAlreadyRunningError extends Error {
+ readonly code = "daemon_supervisor_already_running" as const;
+
+ constructor(readonly owner: DaemonSupervisorOwnerRecord) {
+ super(`Daemon supervisor ${owner.generation} already owns ${owner.socketPath}`);
+ this.name = "DaemonSupervisorAlreadyRunningError";
+ }
+}
+
+class DaemonSupervisorOwnership {
+ private released = false;
+
+ constructor(
+ readonly record: DaemonSupervisorOwnerRecord,
+ private readonly registryDir: string,
+ private readonly ownerDirectory: string,
+ ) {}
+
+ async updatePhase(phase: DaemonSupervisorOwnerPhase): Promise<void> {
+ if (this.released) {
+ return;
+ }
+ const updated = await mutateDaemonSupervisorOwner(
+ this.record.generation,
+ this.record.token,
+ (owner) => {
+ owner.phase = phase;
+ },
+ this.registryDir,
+ );
+ if (!updated) {
+ throw new Error(`Daemon supervisor ownership was lost for ${this.record.socketPath}`);
+ }
+ this.record.phase = phase;
+ this.record.updatedAt = updated.updatedAt;
+ }
+
+ async release(): Promise<void> {
+ if (this.released) {
+ return;
+ }
+ let releasedDirectory: string | undefined;
+ try {
+ await withDaemonSupervisorRegistryGuard(this.registryDir, () => {
+ const current = readOwnerRecord(this.ownerDirectory);
+ if (!current || current.token !== this.record.token) {
+ return;
+ }
+ releasedDirectory = `${this.ownerDirectory}.released-${randomUUID()}`;
+ renameSync(this.ownerDirectory, releasedDirectory);
+ });
+ this.released = true;
+ } finally {
+ if (releasedDirectory) {
+ rmSync(releasedDirectory, { recursive: true, force: true });
+ }
+ }
+ }
+}
+
+function defaultDaemonSupervisorRegistryDir(environment: NodeJS.ProcessEnv = process.env): string {
+ return environment[DAEMON_SUPERVISOR_REGISTRY_DIR_ENV] ?? resolve(defaultDaemonSocketDir(), "supervisor-owners");
+}
+
+async function withDaemonSupervisorRegistryGuard<T>(registryDir: string, action: () => T | Promise<T>): Promise<T> {
+ mkdirSync(registryDir, { recursive: true, mode: 0o700 });
+ const release = await lockfile.lock(registryDir, {
+ realpath: false,
+ lockfilePath: resolve(registryDir, ".guard"),
+ stale: REGISTRY_LOCK_STALE_MS,
+ update: REGISTRY_LOCK_UPDATE_MS,
+ retries: {
+ retries: REGISTRY_LOCK_RETRIES,
+ factor: 1,
+ minTimeout: REGISTRY_LOCK_RETRY_MS,
+ maxTimeout: REGISTRY_LOCK_RETRY_MS,
+ },
+ });
+ try {
+ return await action();
+ } finally {
+ await release();
+ }
+}
+
+async function mutateDaemonSupervisorOwner(
+ generation: string,
+ expectedToken: string,
+ mutation: (owner: DaemonSupervisorOwnerRecord) => void,
+ registryDir: string = defaultDaemonSupervisorRegistryDir(),
+): Promise<DaemonSupervisorOwnerRecord | undefined> {
+ return withDaemonSupervisorRegistryGuard(registryDir, () => {
+ const directory = ownerDirectoryPath(registryDir, generation);
+ if (!existsSync(directory)) {
+ return undefined;
+ }
+ const current = requireOwnerRecord(directory);
+ if (current.token !== expectedToken) {
+ return undefined;
+ }
+ mutation(current);
+ current.updatedAt = new Date().toISOString();
+ if (
+ !isDaemonSupervisorOwnerRecord(current) ||
+ current.generation !== generation ||
+ current.token !== expectedToken
+ ) {
+ throw new Error(`Invalid mutation for daemon supervisor owner ${generation}`);
+ }
+ writeOwnerRecord(directory, current);
+ return current;
+ });
+}
+
+export async function acquireDaemonSupervisorOwnership(
+ options: AcquireDaemonSupervisorOwnershipOptions,
+): Promise<DaemonSupervisorOwnership> {
+ const registryDir = options.registryDir ?? defaultDaemonSupervisorRegistryDir();
+ mkdirSync(registryDir, { recursive: true, mode: 0o700 });
+ const token = randomUUID();
+ const processStartId = getProcessStartId(process.pid);
+ const now = new Date().toISOString();
+ const record: DaemonSupervisorOwnerRecord = {
+ version: OWNER_VERSION,
+ role: "supervisor",
+ token,
+ generation: options.generation,
+ pid: process.pid,
+ ...(processStartId ? { processStartId } : {}),
+ socketPath: normalizeSocketPath(options.socketPath),
+ descriptorDir: canonicalizeFilesystemPath(options.descriptorDir),
+ agentDir: canonicalizeFilesystemPath(options.agentDir),
+ appVersion: options.appVersion,
+ phase: "starting",
+ createdAt: now,
+ updatedAt: now,
+ };
+ const candidateDirectory = resolve(registryDir, `.candidate-${process.pid}-${token}`);
+ const ownerDirectory = ownerDirectoryPath(registryDir, options.generation);
+ mkdirSync(candidateDirectory, { mode: 0o700 });
+ const staleDirectories: string[] = [];
+ try {
+ writeOwnerScope(candidateDirectory, record);
+ writeOwnerRecord(candidateDirectory, record);
+ await withDaemonSupervisorRegistryGuard(registryDir, () => {
+ for (const directory of listOwnerDirectories(registryDir)) {
+ const owner = readOwnerRecordForScope(directory, (scope) => ownerConflicts(scope, record));
+ if (!owner) {
+ continue;
+ }
+ if (!ownerConflicts(owner, record)) {
+ continue;
+ }
+ if (isProcessIdentityAlive(owner)) {
+ throw new DaemonSupervisorAlreadyRunningError(owner);
+ }
+ const staleDirectory = `${directory}.stale-${randomUUID()}`;
+ renameSync(directory, staleDirectory);
+ staleDirectories.push(staleDirectory);
+ }
+ renameSync(candidateDirectory, ownerDirectory);
+ });
+ } catch (error) {
+ rmSync(candidateDirectory, { recursive: true, force: true });
+ throw error;
+ } finally {
+ for (const directory of staleDirectories) {
+ rmSync(directory, { recursive: true, force: true });
+ }
+ }
+ return new DaemonSupervisorOwnership(record, registryDir, ownerDirectory);
+}
+
+export async function persistDaemonStartupFenceFromOwner(
+ socketPath: string,
+ hello: DaemonSupervisorHelloIdentity,
+ registryDir: string = defaultDaemonSupervisorRegistryDir(),
+): Promise<void> {
+ mkdirSync(registryDir, { recursive: true, mode: 0o700 });
+ const fenceDirectory = resolve(registryDir, "startup-fences");
+ mkdirSync(fenceDirectory, { recursive: true, mode: 0o700 });
+ const path = startupFencePath(fenceDirectory, socketPath);
+ const normalizedSocketPath = normalizeSocketPath(socketPath);
+ return withDaemonSupervisorRegistryGuard(registryDir, () => {
+ const owners = listOwnerDirectories(registryDir).flatMap((directory) => {
+ const owner = readOwnerRecordForScope(directory, (scope) => scope.socketPath === normalizedSocketPath);
+ return owner ? [owner] : [];
+ });
+ const matchingOwners = owners.filter((owner) => owner.socketPath === normalizedSocketPath);
+ if (matchingOwners.length === 0) {
+ throw new Error(`Daemon supervisor owner does not match ${socketPath}`);
+ }
+ if (matchingOwners.length > 1) {
+ throw new Error(`Multiple daemon supervisor owners match ${socketPath}`);
+ }
+ const owner = matchingOwners[0];
+ if (!owner) {
+ throw new Error(`Daemon supervisor owner disappeared for ${socketPath}`);
+ }
+ const helloSocketPath = hello.supervisorSocketPath;
+ if (
+ !Number.isInteger(hello.supervisorPid) ||
+ hello.supervisorPid !== owner.pid ||
+ hello.supervisorGeneration !== owner.generation ||
+ hello.supervisorOwnerToken !== owner.token ||
+ typeof helloSocketPath !== "string" ||
+ normalizeSocketPath(helloSocketPath) !== owner.socketPath ||
+ typeof owner.processStartId !== "string" ||
+ hello.supervisorProcessStartId !== owner.processStartId
+ ) {
+ throw new Error(`Daemon supervisor hello does not match its durable owner for ${socketPath}`);
+ }
+ const observedProcessStartId = getProcessStartId(owner.pid);
+ if (observedProcessStartId !== owner.processStartId) {
+ throw new Error(`Daemon supervisor process identity changed for ${socketPath}`);
+ }
+ const record: DaemonStartupFenceRecord = {
+ version: OWNER_VERSION,
+ token: randomUUID(),
+ ownerToken: owner.token,
+ pid: owner.pid,
+ processStartId: owner.processStartId,
+ socketPath: owner.socketPath,
+ supervisorGeneration: owner.generation,
+ createdAt: new Date().toISOString(),
+ };
+ writeJsonAtomically(path, record);
+ });
+}
+
+export async function waitForDaemonStartupFence(
+ socketPath: string,
+ timeoutMs = 10_000,
+ registryDir: string = defaultDaemonSupervisorRegistryDir(),
+): Promise<void> {
+ const path = startupFencePath(resolve(registryDir, "startup-fences"), socketPath);
+ const deadline = Date.now() + timeoutMs;
+ while (true) {
+ const fence = readStartupFence(path);
+ if (!fence) {
+ return;
+ }
+ if (fence.socketPath !== normalizeSocketPath(socketPath)) {
+ throw new Error(`Daemon startup fence does not match ${socketPath}`);
+ }
+ if (!isProcessIdentityAlive(fence)) {
+ const cleared = await withDaemonSupervisorRegistryGuard(registryDir, () => {
+ const current = readStartupFence(path);
+ if (!current) {
+ return true;
+ }
+ if (current?.token === fence.token) {
+ rmSync(path, { force: true });
+ return true;
+ }
+ return false;
+ });
+ if (cleared) {
+ return;
+ }
+ continue;
+ }
+ if (Date.now() >= deadline) {
+ throw new Error(`Timed out waiting for predecessor daemon process ${fence.pid} to exit`);
+ }
+ await delay(STARTUP_FENCE_POLL_MS);
+ }
+}
+
+function isProcessIdentityAlive(identity: ProcessIdentity): boolean {
+ try {
+ process.kill(identity.pid, 0);
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code !== "ESRCH";
+ }
+ if (!identity.processStartId) {
+ return true;
+ }
+ const observed = getProcessStartId(identity.pid);
+ return observed === undefined || observed === identity.processStartId;
+}
+
+function normalizeSocketPath(socketPath: string): string {
+ if (process.platform === "win32") {
+ return socketPath.toLowerCase();
+ }
+ return resolve(socketPath);
+}
+
+function canonicalizeFilesystemPath(path: string): string {
+ let existingAncestor = resolve(path);
+ const missingSuffix: string[] = [];
+ while (true) {
+ try {
+ const physicalAncestor = realpathSync.native(existingAncestor);
+ const canonical = join(physicalAncestor, ...missingSuffix);
+ return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+ throw error;
+ }
+ const parent = dirname(existingAncestor);
+ if (parent === existingAncestor) {
+ const unresolved = resolve(path);
+ return process.platform === "win32" ? unresolved.toLowerCase() : unresolved;
+ }
+ missingSuffix.unshift(basename(existingAncestor));
+ existingAncestor = parent;
+ }
+ }
+}
+
+function ownerConflicts(left: DaemonSupervisorOwnerScope, right: DaemonSupervisorOwnerScope): boolean {
+ return left.socketPath === right.socketPath || left.descriptorDir === right.descriptorDir;
+}
+
+function listOwnerDirectories(registryDir: string): string[] {
+ return readdirSync(registryDir)
+ .filter((name) => name.endsWith(".owner"))
+ .map((name) => resolve(registryDir, name));
+}
+
+function ownerDirectoryPath(registryDir: string, generation: string): string {
+ if (!/^[A-Za-z0-9._-]+$/.test(generation)) {
+ throw new Error(`Invalid daemon supervisor generation: ${generation}`);
+ }
+ return resolve(registryDir, `${generation}.owner`);
+}
+
+function requireOwnerRecord(directory: string): DaemonSupervisorOwnerRecord {
+ const owner = readOwnerRecord(directory);
+ if (!owner) {
+ throw new Error(`Invalid daemon supervisor owner record: ${directory}`);
+ }
+ return owner;
+}
+
+function readOwnerRecordForScope(
+ directory: string,
+ isRelevant: (scope: DaemonSupervisorOwnerScope) => boolean,
+): DaemonSupervisorOwnerRecord | undefined {
+ const owner = readOwnerRecord(directory);
+ if (owner) {
+ return owner;
+ }
+ const scope = readOwnerScope(directory);
+ if (!scope || isRelevant(scope)) {
+ throw new Error(`Invalid daemon supervisor owner record: ${directory}`);
+ }
+ return undefined;
+}
+
+function readOwnerRecord(directory: string): DaemonSupervisorOwnerRecord | undefined {
+ try {
+ const value = JSON.parse(readFileSync(resolve(directory, "owner.json"), "utf8")) as unknown;
+ return isDaemonSupervisorOwnerRecord(value) ? value : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function isDaemonSupervisorOwnerRecord(value: unknown): value is DaemonSupervisorOwnerRecord {
+ if (!value || typeof value !== "object") {
+ return false;
+ }
+ const record = value as Partial<DaemonSupervisorOwnerRecord>;
+ return (
+ record.version === OWNER_VERSION &&
+ record.role === "supervisor" &&
+ typeof record.token === "string" &&
+ typeof record.generation === "string" &&
+ Number.isInteger(record.pid) &&
+ (record.pid ?? 0) > 0 &&
+ (record.processStartId === undefined || typeof record.processStartId === "string") &&
+ typeof record.socketPath === "string" &&
+ typeof record.descriptorDir === "string" &&
+ typeof record.agentDir === "string" &&
+ typeof record.appVersion === "string" &&
+ (record.phase === "starting" || record.phase === "owner" || record.phase === "stopping") &&
+ typeof record.createdAt === "string" &&
+ typeof record.updatedAt === "string"
+ );
+}
+
+function readOwnerScope(directory: string): DaemonSupervisorOwnerScope | undefined {
+ try {
+ const value = JSON.parse(readFileSync(resolve(directory, "scope.json"), "utf8")) as unknown;
+ if (!isDaemonSupervisorOwnerScope(value)) {
+ return undefined;
+ }
+ return ownerDirectoryPath(dirname(directory), value.generation) === directory ? value : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function isDaemonSupervisorOwnerScope(value: unknown): value is DaemonSupervisorOwnerScope {
+ if (!value || typeof value !== "object") {
+ return false;
+ }
+ const scope = value as Partial<DaemonSupervisorOwnerScope>;
+ return (
+ scope.version === OWNER_VERSION &&
+ scope.role === "supervisor" &&
+ typeof scope.token === "string" &&
+ typeof scope.generation === "string" &&
+ typeof scope.socketPath === "string" &&
+ typeof scope.descriptorDir === "string"
+ );
+}
+
+function writeOwnerScope(directory: string, owner: DaemonSupervisorOwnerRecord): void {
+ const scope: DaemonSupervisorOwnerScope = {
+ version: owner.version,
+ role: owner.role,
+ token: owner.token,
+ generation: owner.generation,
+ socketPath: owner.socketPath,
+ descriptorDir: owner.descriptorDir,
+ };
+ writeJsonAtomically(resolve(directory, "scope.json"), scope);
+}
+
+function writeOwnerRecord(directory: string, record: DaemonSupervisorOwnerRecord): void {
+ writeJsonAtomically(resolve(directory, "owner.json"), record);
+}
+
+function readStartupFence(path: string): DaemonStartupFenceRecord | undefined {
+ try {
+ const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+ if (!value || typeof value !== "object") {
+ throw new Error(`Invalid daemon startup fence: ${path}`);
+ }
+ const fence = value as Partial<DaemonStartupFenceRecord>;
+ if (
+ fence.version !== OWNER_VERSION ||
+ typeof fence.token !== "string" ||
+ typeof fence.ownerToken !== "string" ||
+ !Number.isInteger(fence.pid) ||
+ (fence.pid ?? 0) <= 0 ||
+ typeof fence.processStartId !== "string" ||
+ typeof fence.socketPath !== "string" ||
+ typeof fence.supervisorGeneration !== "string" ||
+ typeof fence.createdAt !== "string"
+ ) {
+ throw new Error(`Invalid daemon startup fence: ${path}`);
+ }
+ return fence as DaemonStartupFenceRecord;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ return undefined;
+ }
+ throw error;
+ }
+}
+
+function writeJsonAtomically(path: string, value: unknown): void {
+ const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+ try {
+ writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+ renameSync(tempPath, path);
+ } catch (error) {
+ rmSync(tempPath, { force: true });
+ throw error;
+ }
+}
+
+function startupFencePath(directory: string, socketPath: string): string {
+ const key = createHash("sha256").update(normalizeSocketPath(socketPath)).digest("hex");
+ return resolve(directory, `${key}.json`);
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
diff --git a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
index abe731a4e0..97df573266 100644
--- a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
+++ b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts
@@ -55,12 +55,17 @@ import {
import { matchesSessionIdSuffix } from "./daemon-session-id.js";
import { type SessionSummary, summaryForInactiveSession } from "./daemon-session-list.js";
import {
+ acquireDaemonSocketPathLease,
cleanupDaemonSocketPath,
+ type DaemonSocketIdentity,
+ type DaemonSocketPathLease,
defaultDaemonSocketDir,
defaultDaemonSocketPath,
+ getDaemonSocketIdentity,
prepareDaemonSocketPath,
restrictDaemonSocketPath,
} from "./daemon-socket.js";
+import { acquireDaemonSupervisorOwnership, waitForDaemonStartupFence } from "./daemon-supervisor-ownership.js";
import { DaemonWorkerClient } from "./daemon-worker-client.js";
import {
DAEMON_WORKER_ACTIVE_SESSION_ID_ENV,
@@ -434,7 +439,12 @@ export class DaemonSupervisor {
private server?: Server;
private readonly ready: Promise<void>;
private markReady: () => void = () => {};
+ private rejectReady: (error: Error) => void = () => {};
private ownsSocketPath = false;
+ private socketIdentity?: DaemonSocketIdentity;
+ private socketLease?: DaemonSocketPathLease;
+ private ownership?: Awaited<ReturnType<typeof acquireDaemonSupervisorOwnership>>;
+ private cleanupPromise?: Promise<void>;
private shuttingDown = false;
private readonly clients = new Set<DaemonSocketClient>();
private readonly workers = new Map<string, ResidentWorker>();
@@ -445,7 +455,7 @@ export class DaemonSupervisor {
private readonly supervisorConfigPath: string;
private readonly defaultSessionConfig: AgentSessionRuntimeConfig;
private readonly snapshotCacheRoot: string;
- private readonly commandJournal: CommandRecoveryJournal;
+ private commandJournal!: CommandRecoveryJournal;
private readonly streamReconstructor = new CompactAssistantStreamReconstructor();
private readonly compactCatchupInProgress = new Set<string>();
private readonly pendingReplacementSnapshots = new WeakMap<
@@ -459,9 +469,11 @@ export class DaemonSupervisor {
private readonly socketPath: string,
options: DaemonSupervisorOptions,
) {
- this.ready = new Promise<void>((resolveReady) => {
+ this.ready = new Promise<void>((resolveReady, rejectReady) => {
this.markReady = resolveReady;
+ this.rejectReady = rejectReady;
});
+ void this.ready.catch(() => undefined);
const agentDir = options.defaultSessionConfig.agentDir;
if (!agentDir) {
throw new Error("Daemon supervisor config is missing agentDir");
@@ -469,66 +481,102 @@ export class DaemonSupervisor {
this.descriptorDir = options.descriptorDir ?? defaultWorkerDescriptorDir(agentDir, socketPath);
this.supervisorConfigPath = join(this.descriptorDir, SUPERVISOR_CONFIG_FILE_NAME);
this.defaultSessionConfig = this.loadPersistedSupervisorConfig() ?? options.defaultSessionConfig;
- this.snapshotCacheRoot = join(this.descriptorDir, "snapshot-cache");
- this.commandJournal = new CommandRecoveryJournal(join(this.descriptorDir, "command-journal.jsonl"));
+ this.snapshotCacheRoot = join(this.descriptorDir, "snapshot-cache", this.generation);
this.catalog = new DaemonCatalogClient((message) => this.log(message));
}
async start(): Promise<void> {
- await prepareDaemonSocketPath(this.socketPath);
- mkdirSync(this.descriptorDir, { recursive: true, mode: 0o700 });
- chmodSync(this.descriptorDir, 0o700);
- this.persistSupervisorConfig();
- rmSync(this.snapshotCacheRoot, { recursive: true, force: true });
- mkdirSync(this.snapshotCacheRoot, { recursive: true, mode: 0o700 });
- this.loadWorkerDescriptors();
- const workersToAdopt = [...this.workers.values()];
-
- this.server = createServer((socket) => this.handleConnection(socket));
- await new Promise<void>((resolveListen, rejectListen) => {
+ try {
+ const agentDir = this.defaultSessionConfig.agentDir;
+ if (!agentDir) {
+ throw new Error("Daemon supervisor config is missing agentDir");
+ }
+ this.socketLease = await acquireDaemonSocketPathLease(this.socketPath);
+ await waitForDaemonStartupFence(this.socketPath);
+ this.ownership = await acquireDaemonSupervisorOwnership({
+ socketPath: this.socketPath,
+ descriptorDir: this.descriptorDir,
+ agentDir,
+ generation: this.generation,
+ appVersion: VERSION,
+ });
+ await prepareDaemonSocketPath(this.socketPath, this.socketLease);
+
+ mkdirSync(this.descriptorDir, { recursive: true, mode: 0o700 });
+ chmodSync(this.descriptorDir, 0o700);
+ this.persistSupervisorConfig();
+ rmSync(this.snapshotCacheRoot, { recursive: true, force: true });
+ mkdirSync(this.snapshotCacheRoot, { recursive: true, mode: 0o700 });
+ this.commandJournal = new CommandRecoveryJournal(join(this.descriptorDir, "command-journal.jsonl"));
+ this.loadWorkerDescriptors();
+ const workersToAdopt = [...this.workers.values()];
+
+ this.server = createServer((socket) => this.handleConnection(socket));
+ await this.listen();
+ this.socketIdentity = getDaemonSocketIdentity(this.socketPath);
+ if (process.platform !== "win32" && !this.socketIdentity) {
+ throw new Error(`Could not capture daemon socket identity: ${this.socketPath}`);
+ }
+ this.ownsSocketPath = true;
+ restrictDaemonSocketPath(this.socketPath);
+
+ this.registerSignalHandlers();
+ const ownedSessionFiles = new Set(
+ [...this.workers.values()]
+ .flatMap((worker) => [worker.descriptor.sessionFile, worker.descriptor.createCommand.sessionPath])
+ .filter((path): path is string => typeof path === "string")
+ .map((path) => resolve(path)),
+ );
+ const migratedJobs = migrateLegacyCronJobsToSessionArtifacts(getCronJobsPath(agentDir), {
+ isSessionOwned: (job) => ownedSessionFiles.has(resolve(job.sessionFile)),
+ });
+ if (migratedJobs > 0) {
+ this.log(`Migrated ${migratedJobs} scheduled jobs into session artifacts`);
+ }
+ await this.catalog.start().catch((error) => this.log(`Could not start daemon catalog: ${String(error)}`));
+ let adoptionFailure: unknown;
+ let adoptionFailed = false;
+ await Promise.all(
+ workersToAdopt.map(async (worker) => {
+ try {
+ await this.adoptOrRecoverWorker(worker);
+ } catch (error) {
+ if (!adoptionFailed) {
+ adoptionFailed = true;
+ adoptionFailure = error;
+ }
+ }
+ }),
+ );
+ if (adoptionFailed) {
+ throw adoptionFailure;
+ }
+ await this.syncAgentPeers().catch((error) => this.log(`Could not synchronize agent peers: ${String(error)}`));
+ await this.ownership.updatePhase("owner");
+ this.log(`Prime Agent daemon supervisor ${this.generation} listening on ${this.socketPath}`);
+ this.markReady();
+ } catch (error) {
+ const startupError = error instanceof Error ? error : new Error(String(error));
+ await this.cleanupSupervisorResources();
+ this.rejectReady(startupError);
+ throw startupError;
+ }
+ }
+
+ private listen(): Promise<void> {
+ return new Promise<void>((resolveListen, rejectListen) => {
const onError = (error: Error) => {
this.server?.off("listening", onListening);
rejectListen(error);
};
const onListening = () => {
this.server?.off("error", onError);
- try {
- this.ownsSocketPath = true;
- if (process.platform !== "win32") {
- restrictDaemonSocketPath(this.socketPath);
- }
- resolveListen();
- } catch (error) {
- rejectListen(error);
- }
+ resolveListen();
};
this.server?.once("error", onError);
this.server?.once("listening", onListening);
this.server?.listen(this.socketPath);
});
-
- this.registerSignalHandlers();
- const agentDir = this.defaultSessionConfig.agentDir;
- if (!agentDir) {
- throw new Error("Daemon supervisor config is missing agentDir");
- }
- const ownedSessionFiles = new Set(
- [...this.workers.values()]
- .flatMap((worker) => [worker.descriptor.sessionFile, worker.descriptor.createCommand.sessionPath])
- .filter((path): path is string => typeof path === "string")
- .map((path) => resolve(path)),
- );
- const migratedJobs = migrateLegacyCronJobsToSessionArtifacts(getCronJobsPath(agentDir), {
- isSessionOwned: (job) => ownedSessionFiles.has(resolve(job.sessionFile)),
- });
- if (migratedJobs > 0) {
- this.log(`Migrated ${migratedJobs} scheduled jobs into session artifacts`);
- }
- await this.catalog.start().catch((error) => this.log(`Could not start daemon catalog: ${String(error)}`));
- await Promise.all(workersToAdopt.map((worker) => this.adoptOrRecoverWorker(worker)));
- await this.syncAgentPeers().catch((error) => this.log(`Could not synchronize agent peers: ${String(error)}`));
- this.markReady();
- this.log(`Prime Agent daemon supervisor ${this.generation} listening on ${this.socketPath}`);
}
private log(message: string): void {
@@ -642,26 +690,32 @@ export class DaemonSupervisor {
capabilities: new Set(DAEMON_DEFAULT_CLIENT_CAPABILITIES),
};
this.clients.add(client);
- void this.ready.then(() => {
- if (!client.socket.destroyed && this.clients.has(client)) {
- this.write(client, {
- type: "daemon_hello",
- socketPath: this.socketPath,
- protocol: DAEMON_PROTOCOL_INFO,
- appVersion: VERSION,
- supervisorGeneration: this.generation,
- supervisorPid: process.pid,
- clientId: client.id,
- serverCapabilities: [
- "attach_snapshot",
- "event_sequence",
- "extension_ui",
- "slim_attach",
- "chunked_snapshot",
- ],
- });
- }
- });
+ void this.ready.then(
+ () => {
+ if (!client.socket.destroyed && this.clients.has(client)) {
+ this.write(client, {
+ type: "daemon_hello",
+ socketPath: this.socketPath,
+ protocol: DAEMON_PROTOCOL_INFO,
+ appVersion: VERSION,
+ supervisorGeneration: this.generation,
+ supervisorOwnerToken: this.ownership?.record.token,
+ supervisorPid: process.pid,
+ supervisorProcessStartId: this.ownership?.record.processStartId,
+ supervisorSocketPath: this.ownership?.record.socketPath,
+ clientId: client.id,
+ serverCapabilities: [
+ "attach_snapshot",
+ "event_sequence",
+ "extension_ui",
+ "slim_attach",
+ "chunked_snapshot",
+ ],
+ });
+ }
+ },
+ () => client.socket.destroy(),
+ );
client.detachInput = attachJsonlLineReader(socket, (line) => void this.handleLine(client, line));
let cleaned = false;
@@ -690,7 +744,11 @@ export class DaemonSupervisor {
}
private async handleLine(client: DaemonSocketClient, line: string): Promise<void> {
- await this.ready;
+ try {
+ await this.ready;
+ } catch {
+ return;
+ }
let command: DaemonCommand;
let envelopeClientId: string | undefined;
try {
@@ -2804,7 +2862,88 @@ export class DaemonSupervisor {
return;
}
this.ownsSocketPath = false;
- cleanupDaemonSocketPath(this.socketPath);
+ const identity = this.socketIdentity;
+ this.socketIdentity = undefined;
+ cleanupDaemonSocketPath(this.socketPath, identity, this.socketLease);
+ }
+
+ private async cleanupSupervisorResources(): Promise<void> {
+ if (this.cleanupPromise) {
+ return this.cleanupPromise;
+ }
+ this.cleanupPromise = this.cleanupSupervisorResourcesOnce();
+ return this.cleanupPromise;
+ }
+
+ private async cleanupSupervisorResourcesOnce(): Promise<void> {
+ this.shuttingDown = true;
+ for (const cleanup of this.signalCleanupHandlers.splice(0)) {
+ await this.runCleanupStep("signal handler", cleanup);
+ }
+ const server = this.server;
+ this.server = undefined;
+ const serverClosed = new Promise<void>((resolveClose) => {
+ if (!server?.listening) {
+ resolveClose();
+ return;
+ }
+ try {
+ server.close(() => resolveClose());
+ } catch (error) {
+ this.reportCleanupFailure("daemon server", error);
+ resolveClose();
+ }
+ });
+ for (const client of this.clients) {
+ client.attachedActiveSessionIds.clear();
+ await this.runCleanupStep(`daemon client input ${client.id}`, () => client.detachInput());
+ await this.runCleanupStep(`daemon client socket ${client.id}`, () => {
+ client.socket.destroy();
+ });
+ }
+ this.clients.clear();
+ for (const worker of this.workers.values()) {
+ await this.runCleanupStep(`worker client ${worker.descriptor.workerId}`, () => worker.client?.close());
+ worker.client = undefined;
+ for (const transcript of worker.transcriptCaches.values()) {
+ await this.runCleanupStep(`worker transcript ${worker.descriptor.workerId}`, () => transcript.dispose());
+ }
+ worker.transcriptCaches.clear();
+ worker.incomingTranscriptActiveSessionIds.clear();
+ worker.snapshotCache.clear();
+ worker.snapshotLoads.clear();
+ }
+ this.workers.clear();
+ this.openingWorkers.clear();
+ await this.runCleanupStep("daemon catalog", () => this.catalog.stop());
+ await this.runCleanupStep("daemon server", () => serverClosed);
+ await this.runCleanupStep("daemon socket", () => this.cleanupSocket());
+ await this.runCleanupStep("supervisor cache", () => {
+ rmSync(this.snapshotCacheRoot, { recursive: true, force: true });
+ });
+ const lease = this.socketLease;
+ this.socketLease = undefined;
+ await this.runCleanupStep("daemon socket lock", async () => lease?.release());
+ const ownership = this.ownership;
+ this.ownership = undefined;
+ await this.runCleanupStep("daemon ownership", async () => ownership?.release());
+ }
+
+ private async runCleanupStep(label: string, action: () => void | Promise<void>): Promise<void> {
+ try {
+ await action();
+ } catch (error) {
+ this.reportCleanupFailure(label, error);
+ }
+ }
+
+ private reportCleanupFailure(label: string, error: unknown): void {
+ const message = `Failed to clean up ${label}: ${String(error)}`;
+ try {
+ this.log(message);
+ } catch {
+ console.error(message);
+ }
}
private async shutdown(
@@ -2841,7 +2980,16 @@ export class DaemonSupervisor {
client.socket.end();
}
await new Promise<void>((resolveClose) => this.server?.close(() => resolveClose()) ?? resolveClose());
- this.cleanupSocket();
+ await this.runCleanupStep("daemon socket", () => this.cleanupSocket());
+ await this.runCleanupStep("supervisor cache", () => {
+ rmSync(this.snapshotCacheRoot, { recursive: true, force: true });
+ });
+ const lease = this.socketLease;
+ this.socketLease = undefined;
+ await this.runCleanupStep("daemon socket lock", async () => lease?.release());
+ const ownership = this.ownership;
+ this.ownership = undefined;
+ await this.runCleanupStep("daemon ownership", async () => ownership?.release());
if (relaunch) {
const launch = createCliSubprocessLaunchSpec(["--mode", "daemon", "--daemon-socket", this.socketPath]);
const environment = { ...process.env };
diff --git a/packages/coding-agent/src/package-manager-cli.ts b/packages/coding-agent/src/package-manager-cli.ts
index 7987688258..4d25a702d3 100644
--- a/packages/coding-agent/src/package-manager-cli.ts
+++ b/packages/coding-agent/src/package-manager-cli.ts
@@ -38,6 +38,7 @@ import {
isUnknownDaemonCommandError,
} from "./modes/daemon/daemon-protocol.js";
import { defaultDaemonSocketPath } from "./modes/daemon/daemon-socket.js";
+import { persistDaemonStartupFenceFromOwner } from "./modes/daemon/daemon-supervisor-ownership.js";
import { shouldUseWindowsShell } from "./utils/child-process.js";
import { getLatestPiRelease, isNewerPackageVersion } from "./utils/version-check.js";
@@ -694,6 +695,28 @@ function responseHasActiveDaemonSessions(data: unknown): boolean {
return data.sessions.length > 0;
}
+interface FixedDaemonSupervisorOwnerIdentity {
+ supervisorGeneration: string;
+ supervisorOwnerToken: string;
+ supervisorPid: number;
+ supervisorProcessStartId: string;
+ supervisorSocketPath: string;
+}
+
+function hasFixedDaemonSupervisorOwnerIdentity(value: unknown): value is FixedDaemonSupervisorOwnerIdentity {
+ if (!isRecord(value)) {
+ return false;
+ }
+ return (
+ typeof value.supervisorGeneration === "string" &&
+ typeof value.supervisorOwnerToken === "string" &&
+ Number.isInteger(value.supervisorPid) &&
+ (value.supervisorPid as number) > 0 &&
+ typeof value.supervisorProcessStartId === "string" &&
+ typeof value.supervisorSocketPath === "string"
+ );
+}
+
export async function prepareDaemonUpdateRestart(
socketPath: string,
agentDir: string,
@@ -702,16 +725,33 @@ export async function prepareDaemonUpdateRestart(
const client = new DaemonClient(socketPath);
let connected = false;
let startedAt: number | undefined;
+ let fixedOwnerIdentity: FixedDaemonSupervisorOwnerIdentity | undefined;
+ let fencePersistenceStarted = false;
+ const persistPreparedRestartFence = async () => {
+ const currentHello = client.hello;
+ if (hasFixedDaemonSupervisorOwnerIdentity(currentHello)) {
+ fixedOwnerIdentity = currentHello;
+ }
+ if (!fixedOwnerIdentity) {
+ return;
+ }
+ fencePersistenceStarted = true;
+ await persistDaemonStartupFenceFromOwner(socketPath, fixedOwnerIdentity);
+ };
try {
await client.connect(1000);
connected = true;
const hello = await client.waitForHello(2000).catch(() => undefined);
+ if (hasFixedDaemonSupervisorOwnerIdentity(hello)) {
+ fixedOwnerIdentity = hello;
+ }
const useLegacyProtocol = hello !== undefined && hello.protocol.version < DAEMON_PROTOCOL_VERSION;
if (pendingManifest && pendingManifest.sessions.length > 0) {
const listResponse = useLegacyProtocol
? await client.requestLegacy({ type: "list" }, 30000)
: await client.request({ type: "list" }, 30000);
if (listResponse.success && !responseHasActiveDaemonSessions(listResponse.data)) {
+ await persistPreparedRestartFence();
return pendingManifest;
}
}
@@ -723,11 +763,17 @@ export async function prepareDaemonUpdateRestart(
if (!response.success) {
throw new Error(response.error);
}
- return parseDaemonUpdateRestartManifest(response.data);
+ const manifest = parseDaemonUpdateRestartManifest(response.data);
+ await persistPreparedRestartFence();
+ return manifest;
} catch (error) {
+ if (fencePersistenceStarted) {
+ throw error;
+ }
if (startedAt !== undefined) {
const fallback = readPreparedDaemonUpdateRestartManifest(agentDir, startedAt);
if (fallback) {
+ await persistPreparedRestartFence();
return fallback;
}
}
diff --git a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
index 7fd72e5586..7de450c045 100644
--- a/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
+++ b/packages/coding-agent/test/daemon-supervisor-monitor.test.ts
@@ -34,6 +34,52 @@ describe("daemon worker supervisor monitoring", () => {
vi.useRealTimers();
});
+ it("attempts every shutdown cleanup step before exiting", async () => {
+ const cleanupSocket = vi.fn(() => {
+ throw new Error("daemon socket cleanup failed");
+ });
+ const leaseRelease = vi.fn(async () => {
+ throw new Error("lease cleanup failed");
+ });
+ const ownershipRelease = vi.fn(async () => undefined);
+ const log = vi.fn();
+ const exit = vi.spyOn(process, "exit").mockImplementation(((code?: string | number | null) => {
+ throw new Error(`exit ${code}`);
+ }) as typeof process.exit);
+ type ShutdownHarness = {
+ socketLease?: { release(): Promise<void> };
+ ownership?: { release(): Promise<void> };
+ shutdown(exitCode: number, stopWorkers: boolean, relaunch?: boolean, forceWorkers?: boolean): Promise<never>;
+ };
+ const supervisor = Object.assign(Object.create(DaemonSupervisor.prototype), {
+ shuttingDown: false,
+ signalCleanupHandlers: [],
+ workers: new Map(),
+ clients: new Set(),
+ catalog: { stop: vi.fn(async () => undefined) },
+ cleanupSocket,
+ snapshotCacheRoot: "\0",
+ socketLease: { release: leaseRelease },
+ ownership: { release: ownershipRelease },
+ log,
+ }) as ShutdownHarness;
+
+ try {
+ await expect(supervisor.shutdown(42, false)).rejects.toThrow("exit 42");
+ expect(cleanupSocket).toHaveBeenCalledOnce();
+ expect(leaseRelease).toHaveBeenCalledOnce();
+ expect(ownershipRelease).toHaveBeenCalledOnce();
+ expect(log).toHaveBeenCalledWith(expect.stringContaining("daemon socket"));
+ expect(log).toHaveBeenCalledWith(expect.stringContaining("supervisor cache"));
+ expect(log).toHaveBeenCalledWith(expect.stringContaining("daemon socket lock"));
+ expect(supervisor.socketLease).toBeUndefined();
+ expect(supervisor.ownership).toBeUndefined();
+ expect(exit).toHaveBeenCalledWith(42);
+ } finally {
+ exit.mockRestore();
+ }
+ });
+
it("does not poll a healthy supervisor after the startup check", async () => {
vi.useFakeTimers();
const daemon = createHarness(async () => true);
diff --git a/packages/coding-agent/test/fixtures/eng-4600-faux-extension.ts b/packages/coding-agent/test/fixtures/eng-4600-faux-extension.ts
new file mode 100644
index 0000000000..431e834822
--- /dev/null
+++ b/packages/coding-agent/test/fixtures/eng-4600-faux-extension.ts
@@ -0,0 +1,31 @@
+import { fauxAssistantMessage, getApiProvider, registerFauxProvider } from "../../../ai/src/index.js";
+import type { ExtensionAPI } from "../../src/index.js";
+
+export default function registerEng4600FauxProvider(pi: ExtensionAPI): void {
+ const faux = registerFauxProvider({
+ provider: "faux",
+ models: [{ id: "faux", reasoning: false }],
+ });
+ faux.setResponses(Array.from({ length: 16 }, (_, index) => fauxAssistantMessage(`upgrade response ${index + 1}`)));
+ const apiProvider = getApiProvider(faux.api);
+ if (!apiProvider) {
+ throw new Error("Faux API provider was not registered");
+ }
+ pi.registerProvider(faux.getModel().provider, {
+ api: faux.api,
+ apiKey: "faux-key",
+ baseUrl: faux.getModel().baseUrl,
+ streamSimple: apiProvider.streamSimple,
+ models: faux.models.map((model) => ({
+ api: model.api,
+ baseUrl: model.baseUrl,
+ contextWindow: model.contextWindow,
+ cost: model.cost,
+ id: model.id,
+ input: model.input,
+ maxTokens: model.maxTokens,
+ name: model.name,
+ reasoning: model.reasoning,
+ })),
+ });
+}
diff --git a/packages/coding-agent/test/fixtures/eng-4600-supervisor-fixture.ts b/packages/coding-agent/test/fixtures/eng-4600-supervisor-fixture.ts
new file mode 100644
index 0000000000..43742d6130
--- /dev/null
+++ b/packages/coding-agent/test/fixtures/eng-4600-supervisor-fixture.ts
@@ -0,0 +1,135 @@
+import { existsSync, unlinkSync } from "node:fs";
+import lockfile from "proper-lockfile";
+import { isDaemonCatalogProcess, runDaemonCatalogProcess } from "../../src/modes/daemon/daemon-catalog-process.js";
+import { DaemonSupervisor } from "../../src/modes/daemon/daemon-supervisor.js";
+import { acquireDaemonSupervisorOwnership } from "../../src/modes/daemon/daemon-supervisor-ownership.js";
+
+type ControlMessage = { type: "go" | "probe" | "release" | "shutdown" | "cleanup" };
+
+function requiredEnvironment(name: string): string {
+ const value = process.env[name];
+ if (!value) {
+ throw new Error(`Missing ${name}`);
+ }
+ return value;
+}
+
+function send(message: Record<string, unknown>): void {
+ process.send?.(message);
+}
+
+function waitForControl(type: ControlMessage["type"]): Promise<void> {
+ return new Promise((resolve) => {
+ const onMessage = (message: unknown) => {
+ if (!message || typeof message !== "object" || (message as Partial<ControlMessage>).type !== type) {
+ return;
+ }
+ process.off("message", onMessage);
+ resolve();
+ };
+ process.on("message", onMessage);
+ });
+}
+
+async function runOwnershipHolder(): Promise<never> {
+ const ownership = await acquireDaemonSupervisorOwnership({
+ socketPath: requiredEnvironment("ENG_4600_SOCKET_PATH"),
+ descriptorDir: requiredEnvironment("ENG_4600_DESCRIPTOR_DIR"),
+ agentDir: requiredEnvironment("ENG_4600_AGENT_DIR"),
+ generation: requiredEnvironment("ENG_4600_GENERATION"),
+ appVersion: "test",
+ registryDir: requiredEnvironment("ENG_4600_REGISTRY_DIR"),
+ });
+ send({ type: "ready", owner: ownership.record });
+ await waitForControl("release");
+ await ownership.release();
+ send({ type: "owner_released" });
+ await waitForControl("shutdown");
+ process.exit(0);
+}
+
+async function runSupervisor(): Promise<never> {
+ const socketPath = requiredEnvironment("ENG_4600_SOCKET_PATH");
+ const agentDir = requiredEnvironment("ENG_4600_AGENT_DIR");
+ const descriptorDir = requiredEnvironment("ENG_4600_DESCRIPTOR_DIR");
+ const supervisor = new DaemonSupervisor(socketPath, {
+ descriptorDir,
+ defaultSessionConfig: {
+ agentDir,
+ cwd: agentDir,
+ noContextFiles: true,
+ noExtensions: true,
+ noSkills: true,
+ noTools: true,
+ },
+ });
+ try {
+ await supervisor.start();
+ send({ type: "ready" });
+ return await new Promise<never>(() => {});
+ } catch (error) {
+ send({ type: "failed", error: error instanceof Error ? error.message : String(error) });
+ process.exit(0);
+ }
+}
+
+async function runLegacyCleanup(): Promise<never> {
+ const socketPath = requiredEnvironment("ENG_4600_SOCKET_PATH");
+ send({ type: "ready" });
+ await waitForControl("cleanup");
+ let skipped = false;
+ // This lock/unlink sequence is frozen from the v0.3.0 daemon socket cleanup.
+ if (process.platform !== "win32") {
+ let releaseLock: (() => void) | undefined;
+ try {
+ releaseLock = lockfile.lockSync(socketPath, {
+ realpath: false,
+ stale: 5000,
+ update: 1000,
+ retries: 0,
+ });
+ } catch {
+ skipped = true;
+ }
+ if (releaseLock) {
+ try {
+ if (existsSync(socketPath)) {
+ unlinkSync(socketPath);
+ }
+ } finally {
+ releaseLock();
+ }
+ }
+ }
+ send({ type: "cleanup_complete", skipped });
+ process.exit(0);
+}
+
+async function main(): Promise<never> {
+ if (isDaemonCatalogProcess()) {
+ return runDaemonCatalogProcess();
+ }
+ send({ type: "booted" });
+ process.on("message", (message: unknown) => {
+ if (message && typeof message === "object" && (message as Partial<ControlMessage>).type === "probe") {
+ send({ type: "probe_ack" });
+ }
+ });
+ const mode = requiredEnvironment("ENG_4600_FIXTURE_MODE");
+ if (mode === "legacy_cleanup") {
+ return runLegacyCleanup();
+ }
+ await waitForControl("go");
+ if (mode === "owner") {
+ return runOwnershipHolder();
+ }
+ if (mode === "supervisor") {
+ return runSupervisor();
+ }
+ throw new Error(`Unknown fixture mode: ${mode}`);
+}
+
+void main().catch((error) => {
+ send({ type: "failed", error: error instanceof Error ? error.message : String(error) });
+ process.exit(1);
+});
diff --git a/packages/coding-agent/test/package-self-update-daemon.test.ts b/packages/coding-agent/test/package-self-update-daemon.test.ts
index 0323c75aca..bfd71be7b8 100644
--- a/packages/coding-agent/test/package-self-update-daemon.test.ts
+++ b/packages/coding-agent/test/package-self-update-daemon.test.ts
@@ -4,12 +4,14 @@ import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
ENV_AGENT_DIR,
+ getDaemonUpdateRestartManifestPath,
PACKAGE_NAME,
SELF_UPDATE_INTERACTIVE_CHILD_ENV,
SELF_UPDATE_NOT_ATTEMPTED_EXIT_CODE,
} from "../src/config.js";
import type { AgentSessionRuntimeMetadata } from "../src/core/agent-session-runtime.js";
-import { handlePackageCommand } from "../src/package-manager-cli.js";
+import type * as DaemonSocketModule from "../src/modes/daemon/daemon-socket.js";
+import { handlePackageCommand, prepareDaemonUpdateRestart } from "../src/package-manager-cli.js";
interface MockSessionSummary {
id: string;
@@ -89,15 +91,38 @@ const mockState = vi.hoisted(() => ({
createThrowSessionPaths: [] as string[],
daemonProbe: { reachable: true, activeSessions: [] } as MockRunningDaemonProbe,
globalPackageRoot: "",
+ hello: { protocol: { version: 2 } } as {
+ protocol: { version: number };
+ supervisorGeneration?: string;
+ supervisorOwnerToken?: string;
+ supervisorPid?: number;
+ supervisorProcessStartId?: string;
+ supervisorSocketPath?: string;
+ },
+ listResponse: undefined as MockDaemonResponse | undefined,
prepareManifest: { createdAt: "2026-07-07T00:00:00.000Z", sessions: [] } as MockUpdateRestartManifest,
+ prepareResponse: undefined as MockDaemonResponse | undefined,
promptFailures: 0,
+ requestThrowTypes: [] as string[],
requestPayloads: [] as MockDaemonRequest[],
+ helloWaitFailures: 0,
restoreNextTurnFailures: 0,
socketPath: "",
spawnExitCodes: [] as number[],
shutdownResult: true,
}));
+function useFixedOwnerHello(): void {
+ mockState.hello = {
+ protocol: { version: 2 },
+ supervisorGeneration: "fixed-owner",
+ supervisorOwnerToken: "owner-token",
+ supervisorPid: process.pid,
+ supervisorProcessStartId: "process-start",
+ supervisorSocketPath: mockState.socketPath,
+ };
+}
+
vi.mock("child_process", () => ({
spawn: vi.fn((command: string, args: string[]) => {
mockState.calls.push(`spawn:${command} ${args.join(" ")}`);
@@ -121,10 +146,17 @@ vi.mock("child_process", () => ({
})),
}));
-vi.mock("../src/modes/daemon/daemon-socket.js", () => ({
+vi.mock("../src/modes/daemon/daemon-socket.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof DaemonSocketModule>()),
defaultDaemonSocketPath: () => mockState.socketPath,
}));
+vi.mock("../src/modes/daemon/daemon-supervisor-ownership.js", () => ({
+ persistDaemonStartupFenceFromOwner: vi.fn(async () => {
+ mockState.calls.push("persist-daemon-startup-fence");
+ }),
+}));
+
vi.mock("../src/cli/daemon-launch.js", () => ({
ensureInteractiveDaemonRunning: vi.fn(async () => {
mockState.calls.push("ensure-daemon");
@@ -154,21 +186,39 @@ vi.mock("../src/cli/daemon-launch.js", () => ({
vi.mock("../src/modes/daemon/daemon-client.js", () => ({
DaemonClient: class {
+ private observedHello: typeof mockState.hello | undefined;
+
constructor(readonly socketPath: string) {}
+ get hello(): typeof mockState.hello | undefined {
+ return this.observedHello;
+ }
+
async connect(): Promise<void> {
mockState.calls.push(`daemon-connect:${this.socketPath}`);
}
- async waitForHello(): Promise<{ protocol: { version: number } }> {
- return { protocol: { version: 2 } };
+ async waitForHello(): Promise<typeof mockState.hello> {
+ if (mockState.helloWaitFailures > 0) {
+ mockState.helloWaitFailures--;
+ throw new Error("hello timed out");
+ }
+ this.observedHello = mockState.hello;
+ return mockState.hello;
}
async request(request: MockDaemonRequest): Promise<MockDaemonResponse> {
+ this.observedHello ??= mockState.hello;
mockState.calls.push(`daemon-request:${request.type}`);
mockState.requestPayloads.push(request);
+ if (mockState.requestThrowTypes.includes(request.type)) {
+ throw new Error(`${request.type} failed`);
+ }
+ if (request.type === "list" && mockState.listResponse) {
+ return mockState.listResponse;
+ }
if (request.type === "prepare_update_restart") {
- return { success: true, data: mockState.prepareManifest };
+ return mockState.prepareResponse ?? { success: true, data: mockState.prepareManifest };
}
if (request.type === "create") {
if (request.sessionPath && mockState.createThrowSessionPaths.includes(request.sessionPath)) {
@@ -209,13 +259,18 @@ describe("self-update daemon restart", () => {
projectDir = join(tempDir, "project");
packageDir = join(tempDir, "global-prefix", "lib", "node_modules", PACKAGE_NAME);
mockState.globalPackageRoot = join(tempDir, "global-prefix", "lib", "node_modules");
+ mockState.hello = { protocol: { version: 2 } };
+ mockState.listResponse = undefined;
mockState.socketPath = join(tempDir, "daemon.sock");
mockState.calls = [];
mockState.createActiveSessionIds = [];
mockState.createThrowSessionPaths = [];
mockState.daemonProbe = { reachable: true, activeSessions: [] };
mockState.prepareManifest = { createdAt: "2026-07-07T00:00:00.000Z", sessions: [] };
+ mockState.prepareResponse = undefined;
+ mockState.helloWaitFailures = 0;
mockState.promptFailures = 0;
+ mockState.requestThrowTypes = [];
mockState.requestPayloads = [];
mockState.restoreNextTurnFailures = 0;
mockState.spawnExitCodes = [];
@@ -321,6 +376,7 @@ describe("self-update daemon restart", () => {
});
it("restarts the daemon only after the package update succeeds", async () => {
+ useFixedOwnerHello();
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
@@ -329,12 +385,14 @@ describe("self-update daemon restart", () => {
expect(process.exitCode).toBeUndefined();
const spawnIndex = mockState.calls.findIndex((call) => call.startsWith("spawn:npm "));
+ const fenceIndex = mockState.calls.indexOf("persist-daemon-startup-fence");
const prepareIndex = mockState.calls.indexOf("daemon-request:prepare_update_restart");
const shutdownIndex = mockState.calls.indexOf("shutdown-daemon");
const ensureIndex = mockState.calls.indexOf("ensure-daemon");
expect(spawnIndex).toBeGreaterThanOrEqual(0);
expect(prepareIndex).toBeGreaterThan(spawnIndex);
- expect(shutdownIndex).toBeGreaterThan(prepareIndex);
+ expect(fenceIndex).toBeGreaterThan(prepareIndex);
+ expect(shutdownIndex).toBeGreaterThan(fenceIndex);
expect(ensureIndex).toBeGreaterThan(shutdownIndex);
} finally {
errorSpy.mockRestore();
@@ -342,6 +400,89 @@ describe("self-update daemon restart", () => {
}
});
+ it("does not persist a predecessor fence when restart preparation fails", async () => {
+ useFixedOwnerHello();
+
+ for (const prepareResponse of [
+ { success: false, error: "prepare failed" } as const,
+ { success: true, data: { createdAt: "2026-07-07T00:00:00.000Z", sessions: "invalid" } } as const,
+ ]) {
+ mockState.calls = [];
+ mockState.prepareResponse = prepareResponse;
+ await expect(prepareDaemonUpdateRestart(mockState.socketPath, agentDir)).rejects.toThrow();
+ expect(mockState.calls).toContain("daemon-request:prepare_update_restart");
+ expect(mockState.calls).not.toContain("persist-daemon-startup-fence");
+ }
+ });
+
+ it("persists a fixed predecessor fence when the hello arrives after the initial probe", async () => {
+ useFixedOwnerHello();
+ mockState.helloWaitFailures = 1;
+
+ await expect(prepareDaemonUpdateRestart(mockState.socketPath, agentDir)).resolves.toEqual(
+ mockState.prepareManifest,
+ );
+
+ const prepareIndex = mockState.calls.indexOf("daemon-request:prepare_update_restart");
+ const fenceIndex = mockState.calls.indexOf("persist-daemon-startup-fence");
+ expect(prepareIndex).toBeGreaterThanOrEqual(0);
+ expect(fenceIndex).toBeGreaterThan(prepareIndex);
+ });
+
+ it("fences a pending prepared restart only after verifying the live daemon is empty", async () => {
+ useFixedOwnerHello();
+ const pendingManifest: MockUpdateRestartManifest = {
+ createdAt: "2026-07-07T00:00:00.000Z",
+ sessions: [
+ {
+ activeSessionId: "pending-active",
+ sessionId: "pending-session",
+ sessionFile: join(projectDir, "pending.jsonl"),
+ cwd: projectDir,
+ config: { cwd: projectDir, agentDir },
+ queue: { steering: [], followUp: [], nextTurn: [] },
+ shouldResume: false,
+ wasStreaming: false,
+ wasCompacting: false,
+ wasBashRunning: false,
+ hadRunningRlmChildren: false,
+ wasRetrying: false,
+ hadAcceptedPromptInFlight: false,
+ },
+ ],
+ };
+ writeFileSync(getDaemonUpdateRestartManifestPath(agentDir), JSON.stringify(pendingManifest));
+ mockState.requestThrowTypes = ["list"];
+
+ await expect(prepareDaemonUpdateRestart(mockState.socketPath, agentDir)).rejects.toThrow("list failed");
+ expect(mockState.calls).not.toContain("persist-daemon-startup-fence");
+
+ mockState.calls = [];
+ mockState.requestThrowTypes = [];
+ mockState.listResponse = { success: true, data: { sessions: [] } };
+ await expect(prepareDaemonUpdateRestart(mockState.socketPath, agentDir)).resolves.toEqual(pendingManifest);
+ const listIndex = mockState.calls.indexOf("daemon-request:list");
+ const fenceIndex = mockState.calls.indexOf("persist-daemon-startup-fence");
+ expect(listIndex).toBeGreaterThanOrEqual(0);
+ expect(fenceIndex).toBeGreaterThan(listIndex);
+ expect(mockState.calls).not.toContain("daemon-request:prepare_update_restart");
+ });
+
+ it("skips predecessor fencing when the daemon hello has no fixed-owner identity", async () => {
+ const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+ const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+ try {
+ await expect(handlePackageCommand(["update", "--self"])).resolves.toBe(true);
+
+ expect(mockState.calls).not.toContain("persist-daemon-startup-fence");
+ expect(mockState.calls).toContain("daemon-request:prepare_update_restart");
+ } finally {
+ errorSpy.mockRestore();
+ logSpy.mockRestore();
+ }
+ });
+
it("still resumes accepted prompts when accepted context restore fails", async () => {
mockState.restoreNextTurnFailures = 1;
mockState.prepareManifest = {
diff --git a/packages/coding-agent/test/suite/regressions/4600-supervisor-singleton.test.ts b/packages/coding-agent/test/suite/regressions/4600-supervisor-singleton.test.ts
new file mode 100644
index 0000000000..6822ce4d19
--- /dev/null
+++ b/packages/coding-agent/test/suite/regressions/4600-supervisor-singleton.test.ts
@@ -0,0 +1,1134 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ENV_AGENT_DIR, getCronJobsPath } from "../../../src/config.js";
+import { getProcessStartId } from "../../../src/core/session-lease.js";
+import { DaemonAgentConnection } from "../../../src/modes/agent-connection/daemon-agent-connection.js";
+import { DaemonClient } from "../../../src/modes/daemon/daemon-client.js";
+import type { SessionSummary } from "../../../src/modes/daemon/daemon-session-list.js";
+import {
+ acquireDaemonSupervisorOwnership,
+ persistDaemonStartupFenceFromOwner,
+ waitForDaemonStartupFence,
+} from "../../../src/modes/daemon/daemon-supervisor-ownership.js";
+import { createHarness, type Harness } from "../harness.js";
+
+type FixtureMessage =
+ | { type: "booted" }
+ | { type: "ready"; owner?: OwnerRecord }
+ | { type: "failed"; error: string }
+ | { type: "probe_ack" }
+ | { type: "owner_released" }
+ | { type: "cleanup_complete"; skipped: boolean };
+
+interface OwnerRecord {
+ version: 1;
+ role: "supervisor";
+ token: string;
+ generation: string;
+ pid: number;
+ processStartId?: string;
+ socketPath: string;
+ descriptorDir: string;
+ agentDir: string;
+ appVersion: string;
+ phase: "starting" | "owner" | "stopping";
+ createdAt: string;
+ updatedAt: string;
+}
+
+interface FixtureHandle {
+ child: ChildProcess;
+ diagnostics: { stdout: string; stderr: string };
+ messages: FixtureMessage[];
+ waiters: Array<{
+ predicate: (message: FixtureMessage) => boolean;
+ resolve: (message: FixtureMessage) => void;
+ reject: (error: Error) => void;
+ timeout: ReturnType<typeof setTimeout>;
+ }>;
+}
+
+interface CleanupProcessIdentity {
+ pid: number;
+ processStartId: string;
+ label: string;
+}
+
+const fixturePath = resolve(__dirname, "../../fixtures/eng-4600-supervisor-fixture.ts");
+const fauxExtensionPath = resolve(__dirname, "../../fixtures/eng-4600-faux-extension.ts");
+const cliPath = resolve(__dirname, "../../../src/cli.ts");
+const tsxPath = resolve(__dirname, "../../../../../node_modules/tsx/dist/cli.mjs");
+const tsconfigPath = resolve(__dirname, "../../../../../tsconfig.json");
+const supervisorRegistryDirEnv = "PRIME_AGENT_INTERNAL_DAEMON_SUPERVISOR_REGISTRY_DIR";
+const handles = new Set<FixtureHandle>();
+const harnesses: Harness[] = [];
+const cleanupProcesses = new Map<string, CleanupProcessIdentity>();
+const cleanupRegistryDirs = new Set<string>();
+const cleanupSupervisorSockets = new Set<string>();
+
+afterEach(async () => {
+ for (const registryDir of cleanupRegistryDirs) {
+ registerOwnerRecordsForCleanup(registryDir);
+ }
+ await cleanupRegisteredProcesses();
+ for (const handle of handles) {
+ if (handle.child.exitCode === null && handle.child.signalCode === null) {
+ handle.child.kill("SIGKILL");
+ await waitForExit(handle).catch(() => undefined);
+ }
+ }
+ handles.clear();
+ cleanupProcesses.clear();
+ cleanupRegistryDirs.clear();
+ cleanupSupervisorSockets.clear();
+ while (harnesses.length > 0) {
+ harnesses.pop()?.cleanup();
+ }
+});
+
+function dispatchMessage(handle: FixtureHandle, message: FixtureMessage): void {
+ const waiterIndex = handle.waiters.findIndex((waiter) => waiter.predicate(message));
+ if (waiterIndex === -1) {
+ handle.messages.push(message);
+ return;
+ }
+ const [waiter] = handle.waiters.splice(waiterIndex, 1);
+ if (!waiter) {
+ return;
+ }
+ clearTimeout(waiter.timeout);
+ waiter.resolve(message);
+}
+
+function spawnFixture(
+ mode: "legacy_cleanup" | "owner" | "supervisor",
+ paths: { agentDir: string; descriptorDir: string; registryDir: string; socketPath: string },
+ options: { extraEnv?: NodeJS.ProcessEnv; generation?: string } = {},
+): FixtureHandle {
+ const child = spawn(process.execPath, [tsxPath, fixturePath], {
+ cwd: paths.agentDir,
+ env: {
+ ...process.env,
+ ...options.extraEnv,
+ [supervisorRegistryDirEnv]: paths.registryDir,
+ [ENV_AGENT_DIR]: paths.agentDir,
+ ENG_4600_AGENT_DIR: paths.agentDir,
+ ENG_4600_DESCRIPTOR_DIR: paths.descriptorDir,
+ ENG_4600_FIXTURE_MODE: mode,
+ ENG_4600_GENERATION: options.generation,
+ ENG_4600_REGISTRY_DIR: paths.registryDir,
+ ENG_4600_SOCKET_PATH: paths.socketPath,
+ PI_OFFLINE: "1",
+ TSX_TSCONFIG_PATH: tsconfigPath,
+ },
+ stdio: ["ignore", "pipe", "pipe", "ipc"],
+ });
+ const handle: FixtureHandle = {
+ child,
+ diagnostics: { stdout: "", stderr: "" },
+ messages: [],
+ waiters: [],
+ };
+ handles.add(handle);
+ child.stdout?.on("data", (chunk: Buffer) => {
+ handle.diagnostics.stdout += chunk.toString("utf8");
+ });
+ child.stderr?.on("data", (chunk: Buffer) => {
+ handle.diagnostics.stderr += chunk.toString("utf8");
+ });
+ child.on("message", (message: FixtureMessage) => dispatchMessage(handle, message));
+ return handle;
+}
+
+function spawnRealSupervisor(
+ paths: { agentDir: string; registryDir: string; socketPath: string },
+ extraEnv: NodeJS.ProcessEnv,
+): FixtureHandle {
+ const child = spawn(
+ process.execPath,
+ [tsxPath, cliPath, "--mode", "daemon", "--daemon-socket", paths.socketPath, "--offline"],
+ {
+ cwd: paths.agentDir,
+ env: {
+ ...process.env,
+ ...extraEnv,
+ [supervisorRegistryDirEnv]: paths.registryDir,
+ [ENV_AGENT_DIR]: paths.agentDir,
+ PI_OFFLINE: "1",
+ TSX_TSCONFIG_PATH: tsconfigPath,
+ },
+ stdio: ["ignore", "pipe", "pipe"],
+ },
+ );
+ const handle: FixtureHandle = {
+ child,
+ diagnostics: { stdout: "", stderr: "" },
+ messages: [],
+ waiters: [],
+ };
+ handles.add(handle);
+ child.stdout?.on("data", (chunk: Buffer) => {
+ handle.diagnostics.stdout += chunk.toString("utf8");
+ });
+ child.stderr?.on("data", (chunk: Buffer) => {
+ handle.diagnostics.stderr += chunk.toString("utf8");
+ });
+ return handle;
+}
+
+function waitForMessage(
+ handle: FixtureHandle,
+ predicate: (message: FixtureMessage) => boolean,
+ timeoutMs = 20_000,
+): Promise<FixtureMessage> {
+ const queuedIndex = handle.messages.findIndex(predicate);
+ if (queuedIndex !== -1) {
+ const [message] = handle.messages.splice(queuedIndex, 1);
+ if (message) {
+ return Promise.resolve(message);
+ }
+ }
+ return new Promise((resolveMessage, rejectMessage) => {
+ const timeout = setTimeout(() => {
+ handle.waiters = handle.waiters.filter((waiter) => waiter.timeout !== timeout);
+ rejectMessage(
+ new Error(
+ `Timed out waiting for fixture message (exit=${handle.child.exitCode}/${handle.child.signalCode})\n${handle.diagnostics.stderr}`,
+ ),
+ );
+ }, timeoutMs);
+ handle.waiters.push({ predicate, resolve: resolveMessage, reject: rejectMessage, timeout });
+ });
+}
+
+function waitForType<T extends FixtureMessage["type"]>(
+ handle: FixtureHandle,
+ type: T,
+ timeoutMs?: number,
+): Promise<Extract<FixtureMessage, { type: T }>> {
+ return waitForMessage(handle, (message) => message.type === type, timeoutMs) as Promise<
+ Extract<FixtureMessage, { type: T }>
+ >;
+}
+
+function waitForExit(handle: FixtureHandle, timeoutMs = 20_000): Promise<void> {
+ if (handle.child.exitCode !== null || handle.child.signalCode !== null) {
+ return Promise.resolve();
+ }
+ return new Promise((resolveExit, rejectExit) => {
+ const timeout = setTimeout(
+ () => rejectExit(new Error(`Timed out waiting for fixture exit\n${handle.diagnostics.stderr}`)),
+ timeoutMs,
+ );
+ handle.child.once("exit", () => {
+ clearTimeout(timeout);
+ resolveExit();
+ });
+ });
+}
+
+function send(handle: FixtureHandle, type: "cleanup" | "go" | "probe" | "release" | "shutdown"): void {
+ handle.child.send({ type });
+}
+
+async function createPaths(): Promise<{
+ agentDir: string;
+ descriptorDir: string;
+ registryDir: string;
+ socketPath: string;
+}> {
+ const harness = await createHarness();
+ harnesses.push(harness);
+ return {
+ agentDir: harness.tempDir,
+ descriptorDir: join(harness.tempDir, "workers"),
+ registryDir: join(harness.tempDir, "registry"),
+ socketPath:
+ process.platform === "win32"
+ ? `\\\\.\\pipe\\prime-agent-eng-4600-${process.pid}-${Date.now()}`
+ : join(harness.tempDir, "daemon.sock"),
+ };
+}
+
+async function assertConnectable(socketPath: string): Promise<void> {
+ await new Promise<void>((resolveConnect, rejectConnect) => {
+ const socket = createConnection(socketPath);
+ socket.once("connect", () => {
+ socket.destroy();
+ resolveConnect();
+ });
+ socket.once("error", rejectConnect);
+ });
+}
+
+async function connectEventually(socketPath: string): Promise<DaemonClient> {
+ const deadline = Date.now() + 30_000;
+ let lastError: unknown;
+ while (Date.now() < deadline) {
+ const client = new DaemonClient(socketPath);
+ try {
+ await client.connect(500);
+ await client.waitForHello(2000);
+ return client;
+ } catch (error) {
+ lastError = error;
+ client.close();
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+ }
+ throw new Error(`Timed out connecting to replacement supervisor: ${String(lastError)}`);
+}
+
+function waitForConnectionStatus(
+ connection: DaemonAgentConnection,
+ status: "reconnecting" | "connected",
+ timeoutMs = 30_000,
+): Promise<void> {
+ return new Promise((resolveStatus, rejectStatus) => {
+ const timeout = setTimeout(() => {
+ unsubscribe();
+ rejectStatus(new Error(`Timed out waiting for daemon client status ${status}`));
+ }, timeoutMs);
+ const unsubscribe = connection.subscribe((event) => {
+ if (event.type !== "connection_status" || event.status !== status) {
+ return;
+ }
+ clearTimeout(timeout);
+ unsubscribe();
+ resolveStatus();
+ });
+ });
+}
+
+function readStableIdentity(target: object, property: "clientId" | "protocolClientId"): string {
+ const identity: unknown = Reflect.get(target, property);
+ if (typeof identity !== "string") {
+ throw new Error(`Missing daemon client identity ${property}`);
+ }
+ return identity;
+}
+
+function requireSessionSummary(value: unknown): SessionSummary {
+ if (!value || typeof value !== "object" || typeof (value as Partial<SessionSummary>).id !== "string") {
+ throw new Error("Fixture did not return a session summary");
+ }
+ return value as SessionSummary;
+}
+
+function ownerRecordPath(registryDir: string, generation: string): string {
+ return join(registryDir, `${generation}.owner`, "owner.json");
+}
+
+function ownerScopePath(registryDir: string, generation: string): string {
+ return join(registryDir, `${generation}.owner`, "scope.json");
+}
+
+function readOwnerRecord(registryDir: string, generation: string): OwnerRecord | undefined {
+ try {
+ return JSON.parse(readFileSync(ownerRecordPath(registryDir, generation), "utf8")) as OwnerRecord;
+ } catch {
+ return undefined;
+ }
+}
+
+function listOwnerRecords(registryDir: string): OwnerRecord[] {
+ if (!existsSync(registryDir)) {
+ return [];
+ }
+ return readdirSync(registryDir)
+ .filter((name) => name.endsWith(".owner"))
+ .map((name) => JSON.parse(readFileSync(join(registryDir, name, "owner.json"), "utf8")) as OwnerRecord);
+}
+
+async function waitForOwnerCount(registryDir: string, count: number, timeoutMs = 20_000): Promise<OwnerRecord[]> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ const owners = listOwnerRecords(registryDir);
+ if (owners.length === count) {
+ return owners;
+ }
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+ throw new Error(`Timed out waiting for ${count} supervisor owner records`);
+}
+
+function cleanupIdentityKey(identity: Pick<CleanupProcessIdentity, "pid" | "processStartId">): string {
+ return `${identity.pid}:${identity.processStartId}`;
+}
+
+function registerCleanupProcess(identity: CleanupProcessIdentity): CleanupProcessIdentity {
+ cleanupProcesses.set(cleanupIdentityKey(identity), identity);
+ return identity;
+}
+
+async function captureCleanupProcess(pid: number, label: string, timeoutMs = 5000): Promise<CleanupProcessIdentity> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ const processStartId = getProcessStartId(pid);
+ if (processStartId) {
+ return registerCleanupProcess({ pid, processStartId, label });
+ }
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+ throw new Error(`Could not capture the process-start identity for ${label} ${pid}`);
+}
+
+function registerOwnerRecordsForCleanup(registryDir: string): void {
+ for (const owner of listOwnerRecords(registryDir)) {
+ cleanupSupervisorSockets.add(owner.socketPath);
+ if (owner.processStartId) {
+ registerCleanupProcess({
+ pid: owner.pid,
+ processStartId: owner.processStartId,
+ label: `supervisor ${owner.generation}`,
+ });
+ }
+ }
+}
+
+function cleanupProcessState(identity: CleanupProcessIdentity): "exited" | "matching" | "unknown" {
+ try {
+ process.kill(identity.pid, 0);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "EPERM") {
+ return "exited";
+ }
+ }
+ const observedStartId = getProcessStartId(identity.pid);
+ if (observedStartId === undefined) {
+ return "unknown";
+ }
+ return observedStartId === identity.processStartId ? "matching" : "exited";
+}
+
+function removeDeadFixtureOwnerRecords(registryDir: string): void {
+ for (const owner of listOwnerRecords(registryDir)) {
+ if (!owner.processStartId) {
+ throw new Error(`Cannot clean owner ${owner.generation} without an exact process-start identity`);
+ }
+ const identity = {
+ pid: owner.pid,
+ processStartId: owner.processStartId,
+ label: `supervisor ${owner.generation}`,
+ };
+ const state = cleanupProcessState(identity);
+ if (state !== "exited") {
+ throw new Error(
+ `Refusing to clean ${identity.label} owner for ${identity.pid} (${identity.processStartId}): ${state}`,
+ );
+ }
+
+ const current = readOwnerRecord(registryDir, owner.generation);
+ if (!current) {
+ continue;
+ }
+ if (
+ current.token !== owner.token ||
+ current.pid !== owner.pid ||
+ current.processStartId !== owner.processStartId
+ ) {
+ throw new Error(`Refusing to clean changed owner ${owner.generation}`);
+ }
+ const ownerDir = join(registryDir, `${owner.generation}.owner`);
+ const quarantineDir = join(registryDir, `.${owner.generation}.owner.test-cleanup-${owner.token}`);
+ renameSync(ownerDir, quarantineDir);
+ rmSync(quarantineDir, { recursive: true });
+ }
+}
+
+async function waitForCleanupProcessExit(identity: CleanupProcessIdentity, timeoutMs = 20_000): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (cleanupProcessState(identity) !== "exited" && Date.now() < deadline) {
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+ if (cleanupProcessState(identity) !== "exited") {
+ throw new Error(`Timed out waiting for ${identity.label} ${identity.pid} (${identity.processStartId}) to exit`);
+ }
+ cleanupProcesses.delete(cleanupIdentityKey(identity));
+}
+
+async function waitForCleanupGracePeriod(timeoutMs = 5000): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ for (const identity of [...cleanupProcesses.values()]) {
+ if (cleanupProcessState(identity) === "exited") {
+ cleanupProcesses.delete(cleanupIdentityKey(identity));
+ }
+ }
+ if (cleanupProcesses.size === 0) {
+ return;
+ }
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+}
+
+async function cleanupRegisteredProcesses(existingClient?: DaemonClient): Promise<void> {
+ for (const socketPath of cleanupSupervisorSockets) {
+ await forceShutdownReachableSupervisor(socketPath, existingClient);
+ }
+ await waitForCleanupGracePeriod();
+ const errors: unknown[] = [];
+ for (const identity of [...cleanupProcesses.values()]) {
+ try {
+ if (cleanupProcessState(identity) === "matching") {
+ process.kill(identity.pid, "SIGKILL");
+ }
+ await waitForCleanupProcessExit(identity);
+ } catch (error) {
+ errors.push(error);
+ }
+ }
+ if (errors.length > 0) {
+ throw new AggregateError(errors, "Failed to clean up ENG-4600 fixture processes");
+ }
+}
+
+async function forceShutdownReachableSupervisor(socketPath: string, existingClient?: DaemonClient): Promise<void> {
+ if (existingClient?.isConnected) {
+ try {
+ await existingClient.request({ type: "shutdown", force: true }, 5000);
+ return;
+ } catch {
+ // Retry through a fresh connection before exact-identity process cleanup.
+ }
+ }
+ const cleanupClient = new DaemonClient(socketPath);
+ try {
+ await cleanupClient.connect(1000);
+ await cleanupClient.waitForHello(2000);
+ await cleanupClient.request({ type: "shutdown", force: true }, 5000);
+ } catch {
+ // The exact-identity fallback handles an unreachable supervisor.
+ } finally {
+ cleanupClient.close();
+ }
+}
+
+async function waitForPath(path: string, timeoutMs = 20_000): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (!existsSync(path) && Date.now() < deadline) {
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+ }
+ if (!existsSync(path)) {
+ throw new Error(`Timed out waiting for ${path}`);
+ }
+}
+
+function writeOwnerRecord(registryDir: string, owner: OwnerRecord): void {
+ writeFileSync(ownerRecordPath(registryDir, owner.generation), `${JSON.stringify(owner, null, 2)}\n`);
+}
+
+async function releaseOwnershipHolder(handle: FixtureHandle): Promise<void> {
+ send(handle, "release");
+ await waitForType(handle, "owner_released");
+ send(handle, "shutdown");
+ await waitForExit(handle);
+}
+
+async function stopSupervisor(handle: FixtureHandle, socketPath: string): Promise<void> {
+ const client = new DaemonClient(socketPath);
+ try {
+ await client.connect(1000);
+ await client.waitForHello(2000);
+ await client.request({ type: "shutdown" }, 5000);
+ } finally {
+ client.close();
+ }
+ await waitForExit(handle);
+}
+
+describe("ENG-4600 daemon supervisor ownership", () => {
+ it("elects one listener while 16 contenders atomically reclaim a stale owner", async () => {
+ const paths = await createPaths();
+ const stale = spawnFixture("owner", paths, { generation: "stale-owner" });
+ await waitForType(stale, "booted");
+ send(stale, "go");
+ await waitForType(stale, "ready");
+ stale.child.kill("SIGKILL");
+ await waitForExit(stale);
+
+ const contenders = Array.from({ length: 16 }, () => spawnFixture("supervisor", paths));
+ await Promise.all(contenders.map((contender) => waitForType(contender, "booted", 60_000)));
+ for (const contender of contenders) {
+ send(contender, "go");
+ }
+ const outcomes = await Promise.all(
+ contenders.map((contender) =>
+ waitForMessage(contender, (message) => message.type === "ready" || message.type === "failed", 120_000),
+ ),
+ );
+ expect(outcomes.filter((message) => message.type === "ready")).toHaveLength(1);
+ expect(outcomes.filter((message) => message.type === "failed")).toHaveLength(15);
+ const winner = contenders[outcomes.findIndex((message) => message.type === "ready")];
+ if (!winner) {
+ throw new Error("No supervisor contender won ownership");
+ }
+ await assertConnectable(paths.socketPath);
+ const [owner] = listOwnerRecords(paths.registryDir);
+ expect(owner).toBeDefined();
+ if (!owner) {
+ throw new Error("Winning supervisor did not publish an owner record");
+ }
+ expect(readOwnerRecord(paths.registryDir, owner.generation)).toEqual(owner);
+ await stopSupervisor(winner, paths.socketPath);
+ expect(await waitForOwnerCount(paths.registryDir, 0)).toEqual([]);
+ }, 180_000);
+
+ it("preserves a real resident faux worker and client across delayed exact v0.3.0 cleanup", async () => {
+ if (process.platform === "win32") {
+ return;
+ }
+ const paths = await createPaths();
+ const legacyCleanup = spawnFixture("legacy_cleanup", paths);
+ await waitForType(legacyCleanup, "booted");
+ await waitForType(legacyCleanup, "ready");
+ const predecessor = spawnRealSupervisor(paths, {});
+ cleanupRegistryDirs.add(paths.registryDir);
+ cleanupSupervisorSockets.add(paths.socketPath);
+ let client: DaemonClient | undefined;
+ let connection: DaemonAgentConnection | undefined;
+ try {
+ client = await connectEventually(paths.socketPath);
+ let created: Awaited<ReturnType<DaemonClient["request"]>>;
+ try {
+ created = await client.request(
+ {
+ type: "create",
+ config: {
+ agentDir: paths.agentDir,
+ apiKey: "faux-key",
+ cwd: paths.agentDir,
+ extensions: [fauxExtensionPath],
+ model: "faux",
+ noContextFiles: true,
+ noExtensions: false,
+ noSkills: true,
+ noTools: true,
+ provider: "faux",
+ },
+ },
+ 60_000,
+ );
+ } catch (error) {
+ const logsDir = join(paths.agentDir, "logs");
+ const logs = existsSync(logsDir)
+ ? readdirSync(logsDir)
+ .map((name) => `${name}:\n${readFileSync(join(logsDir, name), "utf8")}`)
+ .join("\n")
+ : "no daemon logs";
+ throw new Error(`${String(error)}\nfixture stderr:\n${predecessor.diagnostics.stderr}\n${logs}`);
+ }
+ if (!created.success) {
+ throw new Error(`${created.error}\nfixture stderr:\n${predecessor.diagnostics.stderr}`);
+ }
+ const summary = requireSessionSummary(created.data);
+ if (!summary.workerPid) {
+ throw new Error("Real resident worker did not expose its pid");
+ }
+ const workerCleanupIdentity = await captureCleanupProcess(summary.workerPid, "resident worker");
+ const activeSessionId = summary.activeSessionId ?? summary.id;
+ connection = await DaemonAgentConnection.attach(client, activeSessionId, { recoverDaemon: async () => {} });
+ await connection.getInitialSnapshot();
+ await connection.prompt("before replacement");
+ await connection.waitForIdle();
+ expect(await connection.getMessages()).toContainEqual(
+ expect.objectContaining({
+ role: "assistant",
+ content: [expect.objectContaining({ text: "upgrade response 1" })],
+ }),
+ );
+ const originalClient = client;
+ const originalConnection = connection;
+ const originalProtocolClientId = readStableIdentity(client, "protocolClientId");
+ const originalAttachedClientId = readStableIdentity(connection, "clientId");
+ const originalWorkerPid = summary.workerPid;
+ const originalState = await connection.getState();
+ const reconnecting = waitForConnectionStatus(connection, "reconnecting");
+ const reconnected = waitForConnectionStatus(connection, "connected", 60_000);
+ const restarted = await client.request({ type: "restart" }, 10_000);
+ expect(restarted.success).toBe(true);
+ await reconnecting;
+ await waitForExit(predecessor);
+ await reconnected;
+ const [successorOwner] = await waitForOwnerCount(paths.registryDir, 1);
+ if (!successorOwner) {
+ throw new Error("Replacement supervisor did not publish its owner record");
+ }
+ if (!successorOwner.processStartId) {
+ await captureCleanupProcess(
+ successorOwner.pid,
+ `replacement supervisor ${successorOwner.generation}`,
+ ).catch(() => undefined);
+ throw new Error("Replacement supervisor did not publish a process-start identity");
+ }
+ const successorCleanupIdentity = registerCleanupProcess({
+ pid: successorOwner.pid,
+ processStartId: successorOwner.processStartId,
+ label: `replacement supervisor ${successorOwner.generation}`,
+ });
+ if (cleanupProcessState(successorCleanupIdentity) !== "matching") {
+ throw new Error("Replacement supervisor owner identity does not match its live process");
+ }
+ expect(client).toBe(originalClient);
+ expect(connection).toBe(originalConnection);
+ expect(readStableIdentity(client, "protocolClientId")).toBe(originalProtocolClientId);
+ expect(readStableIdentity(connection, "clientId")).toBe(originalAttachedClientId);
+ expect((await connection.getState()).activeSessionId).toBe(originalState.activeSessionId);
+ const successorIdentity = statSync(paths.socketPath);
+ send(legacyCleanup, "cleanup");
+ const cleanup = await waitForType(legacyCleanup, "cleanup_complete");
+ expect(cleanup.skipped).toBe(true);
+ const identityAfterLegacyCleanup = statSync(paths.socketPath);
+ expect(identityAfterLegacyCleanup.dev).toBe(successorIdentity.dev);
+ expect(identityAfterLegacyCleanup.ino).toBe(successorIdentity.ino);
+ expect(readdirSync(successorOwner.descriptorDir).filter((name) => name.endsWith(".json"))).toHaveLength(1);
+ const listed = await client.request({ type: "list" });
+ if (!listed.success) {
+ throw new Error(listed.error);
+ }
+ const listedSessions = (listed.data as { sessions: unknown[] }).sessions;
+ expect(listedSessions).toHaveLength(1);
+ const restored = requireSessionSummary(listedSessions[0]);
+ expect(restored.workerPid).toBe(originalWorkerPid);
+ expect(restored.activeSessionId ?? restored.id).toBe(activeSessionId);
+ expect((await connection.getState()).activeSessionId).toBe(originalState.activeSessionId);
+ await connection.prompt("after replacement");
+ await connection.waitForIdle();
+ expect(await connection.getMessages()).toContainEqual(
+ expect.objectContaining({
+ role: "assistant",
+ content: [expect.objectContaining({ text: "upgrade response 2" })],
+ }),
+ );
+ await connection.dispose();
+ connection = undefined;
+ await client.request({ type: "shutdown", force: true }, 10_000);
+ client.close();
+ await waitForExit(legacyCleanup);
+ await waitForCleanupProcessExit(workerCleanupIdentity);
+ await waitForCleanupProcessExit(successorCleanupIdentity);
+ registerOwnerRecordsForCleanup(paths.registryDir);
+ await cleanupRegisteredProcesses(client);
+ removeDeadFixtureOwnerRecords(paths.registryDir);
+ expect(listOwnerRecords(paths.registryDir)).toEqual([]);
+ } finally {
+ await connection?.dispose().catch(() => undefined);
+ registerOwnerRecordsForCleanup(paths.registryDir);
+ await cleanupRegisteredProcesses(client);
+ client?.close();
+ }
+ }, 90_000);
+
+ it("waits for the exact persisted predecessor identity during update handoff", async () => {
+ if (process.platform === "win32") {
+ return;
+ }
+ const paths = await createPaths();
+ const predecessor = spawnFixture("owner", paths, { generation: "fixed-predecessor" });
+ await waitForType(predecessor, "booted");
+ send(predecessor, "go");
+ const predecessorReady = await waitForType(predecessor, "ready");
+ const owner = predecessorReady.owner;
+ if (!owner?.processStartId) {
+ throw new Error("Fixed predecessor did not publish a process start identity");
+ }
+ await persistDaemonStartupFenceFromOwner(
+ paths.socketPath,
+ {
+ supervisorGeneration: owner.generation,
+ supervisorOwnerToken: owner.token,
+ supervisorPid: owner.pid,
+ supervisorProcessStartId: owner.processStartId,
+ supervisorSocketPath: owner.socketPath,
+ },
+ paths.registryDir,
+ );
+ send(predecessor, "release");
+ await waitForType(predecessor, "owner_released");
+
+ const replacement = spawnFixture("supervisor", paths);
+ await waitForType(replacement, "booted");
+ send(replacement, "go");
+ await waitForPath(`${paths.socketPath}.lock`);
+ send(replacement, "probe");
+ await waitForType(replacement, "probe_ack");
+ expect(replacement.messages.some((message) => message.type === "ready")).toBe(false);
+ expect(listOwnerRecords(paths.registryDir)).toEqual([]);
+ expect(existsSync(paths.socketPath)).toBe(false);
+ send(predecessor, "shutdown");
+ await waitForExit(predecessor);
+ await waitForType(replacement, "ready");
+ await assertConnectable(paths.socketPath);
+ await stopSupervisor(replacement, paths.socketPath);
+ }, 30_000);
+
+ it("rejects malformed or mismatched fixed-owner fences and preserves timed-out fences", async () => {
+ const missingPaths = await createPaths();
+ await expect(
+ persistDaemonStartupFenceFromOwner(
+ missingPaths.socketPath,
+ {
+ supervisorGeneration: "missing-owner",
+ supervisorOwnerToken: "missing-owner",
+ supervisorPid: process.pid,
+ supervisorProcessStartId: "missing-owner",
+ supervisorSocketPath: missingPaths.socketPath,
+ },
+ missingPaths.registryDir,
+ ),
+ ).rejects.toThrow(/does not match/);
+
+ const paths = await createPaths();
+ const predecessor = spawnFixture("owner", paths, { generation: "validated-predecessor" });
+ await waitForType(predecessor, "booted");
+ send(predecessor, "go");
+ const predecessorReady = await waitForType(predecessor, "ready");
+ const owner = predecessorReady.owner;
+ if (!owner) {
+ throw new Error("Owner fixture did not publish its durable record");
+ }
+ if (!owner.processStartId) {
+ await expect(
+ persistDaemonStartupFenceFromOwner(
+ paths.socketPath,
+ {
+ supervisorGeneration: owner.generation,
+ supervisorOwnerToken: owner.token,
+ supervisorPid: owner.pid,
+ supervisorSocketPath: owner.socketPath,
+ },
+ paths.registryDir,
+ ),
+ ).rejects.toThrow(/does not match/);
+ await releaseOwnershipHolder(predecessor);
+ return;
+ }
+ const hello = {
+ supervisorGeneration: owner.generation,
+ supervisorOwnerToken: owner.token,
+ supervisorPid: owner.pid,
+ supervisorProcessStartId: owner.processStartId,
+ supervisorSocketPath: owner.socketPath,
+ };
+ for (const mismatch of [
+ { ...hello, supervisorPid: owner.pid + 1 },
+ { ...hello, supervisorGeneration: "wrong-generation" },
+ { ...hello, supervisorOwnerToken: "wrong-token" },
+ { ...hello, supervisorProcessStartId: "wrong-start" },
+ { ...hello, supervisorSocketPath: `${owner.socketPath}.other` },
+ {},
+ ]) {
+ await expect(
+ persistDaemonStartupFenceFromOwner(paths.socketPath, mismatch, paths.registryDir),
+ ).rejects.toThrow();
+ }
+ await expect(
+ persistDaemonStartupFenceFromOwner(`${paths.socketPath}.other`, hello, paths.registryDir),
+ ).rejects.toThrow(/does not match/);
+
+ const ownerPath = ownerRecordPath(paths.registryDir, owner.generation);
+ writeFileSync(ownerPath, "{ malformed\n");
+ await expect(persistDaemonStartupFenceFromOwner(paths.socketPath, hello, paths.registryDir)).rejects.toThrow(
+ /Invalid daemon supervisor owner record/,
+ );
+ writeOwnerRecord(paths.registryDir, { ...owner, processStartId: "recycled-process" });
+ await expect(
+ persistDaemonStartupFenceFromOwner(
+ paths.socketPath,
+ { ...hello, supervisorProcessStartId: "recycled-process" },
+ paths.registryDir,
+ ),
+ ).rejects.toThrow(/process identity changed/);
+ writeOwnerRecord(paths.registryDir, owner);
+ await persistDaemonStartupFenceFromOwner(paths.socketPath, hello, paths.registryDir);
+ await expect(waitForDaemonStartupFence(paths.socketPath, 50, paths.registryDir)).rejects.toThrow(/Timed out/);
+ expect(readdirSync(join(paths.registryDir, "startup-fences"))).toHaveLength(1);
+ await releaseOwnershipHolder(predecessor);
+ await waitForDaemonStartupFence(paths.socketPath, 5000, paths.registryDir);
+ expect(readdirSync(join(paths.registryDir, "startup-fences"))).toEqual([]);
+ }, 30_000);
+
+ it("admits unrelated ownership when immutable scope proves a corrupt owner is unrelated", async () => {
+ const paths = await createPaths();
+ const corruptOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, "corrupt-agent"),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, "corrupt-workers"),
+ generation: "corrupt-unrelated-owner",
+ registryDir: paths.registryDir,
+ socketPath: `${paths.socketPath}.corrupt`,
+ });
+ const originalOwner = { ...corruptOwner.record };
+ let unrelatedOwner: Awaited<ReturnType<typeof acquireDaemonSupervisorOwnership>> | undefined;
+ writeFileSync(ownerRecordPath(paths.registryDir, originalOwner.generation), "{ malformed\n");
+ try {
+ unrelatedOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, "healthy-agent"),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, "healthy-workers"),
+ generation: "healthy-unrelated-owner",
+ registryDir: paths.registryDir,
+ socketPath: `${paths.socketPath}.healthy`,
+ });
+ expect(unrelatedOwner.record.generation).toBe("healthy-unrelated-owner");
+ } finally {
+ await unrelatedOwner?.release();
+ writeOwnerRecord(paths.registryDir, originalOwner);
+ await corruptOwner.release();
+ }
+ });
+
+ it("persists a fence when immutable scope proves a corrupt owner is unrelated", async () => {
+ const paths = await createPaths();
+ const targetOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: paths.agentDir,
+ appVersion: "test",
+ descriptorDir: paths.descriptorDir,
+ generation: "fence-target-owner",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ });
+ const corruptOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, "fence-corrupt-agent"),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, "fence-corrupt-workers"),
+ generation: "fence-corrupt-unrelated-owner",
+ registryDir: paths.registryDir,
+ socketPath: `${paths.socketPath}.corrupt`,
+ });
+ const originalCorruptOwner = { ...corruptOwner.record };
+ writeFileSync(ownerRecordPath(paths.registryDir, originalCorruptOwner.generation), "{ malformed\n");
+ try {
+ if (!targetOwner.record.processStartId) {
+ return;
+ }
+ await persistDaemonStartupFenceFromOwner(
+ paths.socketPath,
+ {
+ supervisorGeneration: targetOwner.record.generation,
+ supervisorOwnerToken: targetOwner.record.token,
+ supervisorPid: targetOwner.record.pid,
+ supervisorProcessStartId: targetOwner.record.processStartId,
+ supervisorSocketPath: targetOwner.record.socketPath,
+ },
+ paths.registryDir,
+ );
+ expect(readdirSync(join(paths.registryDir, "startup-fences"))).toHaveLength(1);
+ } finally {
+ rmSync(join(paths.registryDir, "startup-fences"), { recursive: true, force: true });
+ writeOwnerRecord(paths.registryDir, originalCorruptOwner);
+ await corruptOwner.release();
+ await targetOwner.release();
+ }
+ });
+
+ it("fails closed when a corrupt owner has matching immutable scope", async () => {
+ const paths = await createPaths();
+ const owner = await acquireDaemonSupervisorOwnership({
+ agentDir: paths.agentDir,
+ appVersion: "test",
+ descriptorDir: paths.descriptorDir,
+ generation: "matching-corrupt-owner",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ });
+ const originalOwner = { ...owner.record };
+ writeFileSync(ownerRecordPath(paths.registryDir, originalOwner.generation), "{ malformed\n");
+ try {
+ await expect(
+ acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, "matching-contender-agent"),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, "matching-contender-workers"),
+ generation: "matching-corrupt-contender",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ }),
+ ).rejects.toThrow(/Invalid daemon supervisor owner record/);
+ await expect(persistDaemonStartupFenceFromOwner(paths.socketPath, {}, paths.registryDir)).rejects.toThrow(
+ /Invalid daemon supervisor owner record/,
+ );
+ } finally {
+ writeOwnerRecord(paths.registryDir, originalOwner);
+ await owner.release();
+ }
+ });
+
+ it("fails closed when corrupt owners have missing or corrupt scope metadata", async () => {
+ const paths = await createPaths();
+ const targetOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: paths.agentDir,
+ appVersion: "test",
+ descriptorDir: paths.descriptorDir,
+ generation: "scope-failure-target",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ });
+ const corruptOwner = await acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, "scope-failure-agent"),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, "scope-failure-workers"),
+ generation: "scope-failure-unrelated",
+ registryDir: paths.registryDir,
+ socketPath: `${paths.socketPath}.scope-failure`,
+ });
+ const originalCorruptOwner = { ...corruptOwner.record };
+ const scopePath = ownerScopePath(paths.registryDir, originalCorruptOwner.generation);
+ const originalScope = readFileSync(scopePath, "utf8");
+ const expectBlocked = async (generation: string) => {
+ await expect(
+ acquireDaemonSupervisorOwnership({
+ agentDir: join(paths.agentDir, `${generation}-agent`),
+ appVersion: "test",
+ descriptorDir: join(paths.agentDir, `${generation}-workers`),
+ generation,
+ registryDir: paths.registryDir,
+ socketPath: `${paths.socketPath}.${generation}`,
+ }),
+ ).rejects.toThrow(/Invalid daemon supervisor owner record/);
+ await expect(persistDaemonStartupFenceFromOwner(paths.socketPath, {}, paths.registryDir)).rejects.toThrow(
+ /Invalid daemon supervisor owner record/,
+ );
+ };
+ writeFileSync(ownerRecordPath(paths.registryDir, originalCorruptOwner.generation), "{ malformed\n");
+ try {
+ rmSync(scopePath);
+ await expectBlocked("missing-scope-contender");
+ writeFileSync(scopePath, "{ malformed\n");
+ await expectBlocked("corrupt-scope-contender");
+ } finally {
+ writeFileSync(scopePath, originalScope);
+ writeOwnerRecord(paths.registryDir, originalCorruptOwner);
+ await corruptOwner.release();
+ await targetOwner.release();
+ }
+ });
+
+ it("treats physical descriptor aliases as one owner even with different sockets", async () => {
+ const paths = await createPaths();
+ const physicalRoot = join(paths.agentDir, "physical-root");
+ const aliasRoot = join(paths.agentDir, "physical-root-alias");
+ mkdirSync(physicalRoot, { recursive: true });
+ symlinkSync(physicalRoot, aliasRoot, process.platform === "win32" ? "junction" : "dir");
+ const physicalPaths = { ...paths, descriptorDir: join(physicalRoot, "future", "workers") };
+ const first = spawnFixture("owner", physicalPaths, { generation: "physical-owner" });
+ await waitForType(first, "booted");
+ send(first, "go");
+ await waitForType(first, "ready");
+ const aliasDescriptorDir = join(aliasRoot, "future", "workers");
+ const aliasPaths = {
+ ...paths,
+ descriptorDir: process.platform === "win32" ? aliasDescriptorDir.toUpperCase() : aliasDescriptorDir,
+ socketPath: `${paths.socketPath}.alias`,
+ };
+ const alias = spawnFixture("owner", aliasPaths, { generation: "alias-owner" });
+ await waitForType(alias, "booted");
+ send(alias, "go");
+ expect(await waitForType(alias, "failed")).toMatchObject({ error: expect.stringContaining("already owns") });
+ await waitForExit(alias);
+ await releaseOwnershipHolder(first);
+ });
+
+ it("rejects the same descriptor directory paired with a different socket", async () => {
+ const paths = await createPaths();
+ const first = spawnFixture("owner", paths, { generation: "descriptor-owner" });
+ await waitForType(first, "booted");
+ send(first, "go");
+ await waitForType(first, "ready");
+ const secondPaths = { ...paths, socketPath: `${paths.socketPath}.second` };
+ const second = spawnFixture("owner", secondPaths, { generation: "descriptor-contender" });
+ await waitForType(second, "booted");
+ send(second, "go");
+ expect(await waitForType(second, "failed")).toMatchObject({ error: expect.stringContaining("already owns") });
+ await waitForExit(second);
+ await releaseOwnershipHolder(first);
+ });
+
+ it("retries ownership release after guarded removal fails", async () => {
+ const paths = await createPaths();
+ const ownership = await acquireDaemonSupervisorOwnership({
+ agentDir: paths.agentDir,
+ appVersion: "test",
+ descriptorDir: paths.descriptorDir,
+ generation: "retryable-release",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ });
+ const movedRegistry = `${paths.registryDir}.moved`;
+ renameSync(paths.registryDir, movedRegistry);
+ writeFileSync(paths.registryDir, "blocked");
+ await expect(ownership.release()).rejects.toThrow();
+ rmSync(paths.registryDir, { force: true });
+ renameSync(movedRegistry, paths.registryDir);
+ await ownership.release();
+ expect(listOwnerRecords(paths.registryDir)).toEqual([]);
+ });
+
+ it("does not remove an owner record whose token changed", async () => {
+ const paths = await createPaths();
+ const ownership = await acquireDaemonSupervisorOwnership({
+ agentDir: paths.agentDir,
+ appVersion: "test",
+ descriptorDir: paths.descriptorDir,
+ generation: "token-checked-release",
+ registryDir: paths.registryDir,
+ socketPath: paths.socketPath,
+ });
+ writeOwnerRecord(paths.registryDir, { ...ownership.record, token: "replacement-token" });
+
+ await ownership.release();
+
+ expect(readOwnerRecord(paths.registryDir, ownership.record.generation)?.token).toBe("replacement-token");
+ rmSync(join(paths.registryDir, `${ownership.record.generation}.owner`), { recursive: true, force: true });
+ });
+
+ it("unwinds real pre-bind and post-bind startup failures before retry", async () => {
+ const paths = await createPaths();
+ writeFileSync(paths.socketPath, "not a socket");
+ const preBindFailure = spawnFixture("supervisor", paths);
+ await waitForType(preBindFailure, "booted");
+ send(preBindFailure, "go");
+ expect(await waitForType(preBindFailure, "failed")).toMatchObject({
+ error: expect.stringContaining("is not a socket"),
+ });
+ await waitForExit(preBindFailure);
+ expect(listOwnerRecords(paths.registryDir)).toEqual([]);
+ expect(existsSync(`${paths.socketPath}.lock`)).toBe(false);
+ rmSync(paths.socketPath, { force: true });
+
+ writeFileSync(getCronJobsPath(paths.agentDir), "{ malformed\n");
+ const postBindFailure = spawnFixture("supervisor", paths);
+ await waitForType(postBindFailure, "booted");
+ send(postBindFailure, "go");
+ expect(await waitForType(postBindFailure, "failed")).toMatchObject({
+ error: expect.stringContaining("JSON"),
+ });
+ await waitForExit(postBindFailure);
+ expect(listOwnerRecords(paths.registryDir)).toEqual([]);
+ expect(existsSync(`${paths.socketPath}.lock`)).toBe(false);
+ expect(existsSync(paths.socketPath)).toBe(false);
+ const cacheRoot = join(paths.descriptorDir, "snapshot-cache");
+ expect(existsSync(cacheRoot) ? readdirSync(cacheRoot) : []).toEqual([]);
+ rmSync(getCronJobsPath(paths.agentDir), { force: true });
+
+ const healthy = spawnFixture("supervisor", paths);
+ await waitForType(healthy, "booted");
+ send(healthy, "go");
+ await waitForType(healthy, "ready");
+ await assertConnectable(paths.socketPath);
+ await stopSupervisor(healthy, paths.socketPath);
+ }, 60_000);
+});