@haywoodmarx/agent-pager 0.1.3 → 0.2.0

package/dist/src/implementations/pi/broker-client.js

@@ -1,5 +1,5 @@
 import { ATTACH_HEADER, isAgentId } from "../../broker/protocol.js";
-import { adoptRotation, asRecord, BrokerDeliveryClient, exactRecord, registerAgent, rpcEnvelope, } from "../../messaging/delivery-client.js";
+import { adoptRotation, asRecord, BrokerDeliveryClient, exactRecord, isExpiredRefusal, registerAgent, rpcEnvelope, } from "../../messaging/delivery-client.js";
 import { PAGER_VERSION } from "../../version.js";
 /**
  * Register a directly started Pi session through the unauthenticated broker boundary.
@@ -10,23 +10,37 @@ export async function registerPiAgent({ request, brokerUrl, workspacePath, sessi
     return registerAgent(request, brokerUrl, {
         workspacePath,
         implementationId: "pi",
-        sessionName,
+        ...(sessionName ? { sessionName } : {}),
         ...(sessionKey ? { sessionKey } : {}),
     });
 }
-/** Authenticated messaging and delivery operations used by the Pi extension. */
+/**
+ * Authenticated messaging and delivery operations used by the Pi extension.
+ *
+ * When the broker refuses the attachments this client holds as `expired` and a rejoin was supplied, a
+ * call registers the conversation again, attaches both channels with the reservations that return,
+ * and is retried once; calls refused together share one rejoin. Any other refusal reaches the caller
+ * unchanged.
+ */
 export class PiBrokerClient {
     #brokerUrl;
-    #agentId;
     #request;
+    #sessionKey;
+    #rejoin;
+    #agentId;
     #messaging;
     #delivery;
-    constructor(brokerUrl, agentId, request, messaging, delivery) {
+    #deliveryAddress;
+    #rejoining;
+    #attachments = 0;
+    constructor(brokerUrl, agentId, request, messaging, delivery, sessionKey, rejoin) {
         this.#brokerUrl = brokerUrl;
         this.#agentId = agentId;
         this.#request = request;
         this.#messaging = messaging;
         this.#delivery = delivery;
+        this.#sessionKey = sessionKey;
+        this.#rejoin = rejoin;
     }
     /**
      * Consume a Pi identity's messaging and delivery reservations.
@@ -34,9 +48,11 @@ export class PiBrokerClient {
      * @param identity - Reserved or directly registered broker identity.
      * @param request - HTTP operation used to reach the loopback broker.
      * @param sessionKey - Resumable conversation key, which the broker may resolve to another identity.
+     * @param rejoin - Registers this conversation again by its key and returns the attachments for the
+     * identity that results; absent when nothing identifies the conversation to register.
      * @returns - Connected client whose identity is the one the broker resolved, not the one requested.
      */
-    static async connect(brokerUrl, identity, request, sessionKey) {
+    static async connect(brokerUrl, identity, request, sessionKey, rejoin) {
         const messaging = await initializeMessaging(request, brokerUrl, identity.messagingReservation, sessionKey);
         const delivery = await BrokerDeliveryClient.attach({
             brokerUrl,
@@ -45,7 +61,7 @@ export class PiBrokerClient {
             request,
             sessionKey,
         });
-        return new PiBrokerClient(brokerUrl, messaging.agentId ?? delivery.agentId(), request, messaging, delivery);
+        return new PiBrokerClient(brokerUrl, messaging.agentId ?? delivery.agentId(), request, messaging, delivery, sessionKey, rejoin);
     }
     /**
      * Invoke one model-callable Pager MCP tool.
@@ -53,7 +69,10 @@ export class PiBrokerClient {
      * @param args - Validated Pi tool arguments.
      * @returns - Decoded broker tool result.
      */
-    async callTool(name, args) {
+    callTool(name, args) {
+        return this.#recovering(() => this.#callMessagingTool(name, args));
+    }
+    async #callMessagingTool(name, args) {
         const response = await this.#request(this.#brokerUrl, {
             method: "POST",
             headers: messagingHeaders(this.#messaging),
@@ -86,11 +105,54 @@ export class PiBrokerClient {
      * @param address - Address text the session's inbox produced.
      */
     presentDeliveryAddress(address) {
+        this.#deliveryAddress = address;
         this.#delivery.presentDeliveryAddress(address);
     }
     /** Renew both independently fenced broker attachment leases. */
     async heartbeat() {
-        await Promise.all([this.callTool("whoami", {}), this.#delivery.heartbeat()]);
+        await this.#recovering(async () => {
+            await Promise.all([this.#callMessagingTool("whoami", {}), this.#delivery.heartbeat()]);
+        });
+    }
+    async #recovering(call) {
+        await this.#rejoining?.catch(() => undefined);
+        const presentedAttachments = this.#attachments;
+        try {
+            return await call();
+        }
+        catch (error) {
+            const rejoin = this.#rejoin;
+            if (!rejoin || !isExpiredRefusal(error))
+                throw error;
+            if (this.#rejoining)
+                await this.#rejoining;
+            else if (this.#attachments === presentedAttachments)
+                await this.#startRejoin(rejoin);
+            return call();
+        }
+    }
+    #startRejoin(rejoin) {
+        this.#rejoining = this.#registerAgain(rejoin).finally(() => {
+            this.#rejoining = undefined;
+        });
+        return this.#rejoining;
+    }
+    async #registerAgain(rejoin) {
+        const identity = await rejoin();
+        const messaging = await initializeMessaging(this.#request, this.#brokerUrl, identity.messagingReservation, this.#sessionKey);
+        const delivery = await BrokerDeliveryClient.attach({
+            brokerUrl: this.#brokerUrl,
+            agentId: identity.agentId,
+            reservation: identity.deliveryReservation,
+            request: this.#request,
+            sessionKey: this.#sessionKey,
+        });
+        if (this.#deliveryAddress)
+            delivery.presentDeliveryAddress(this.#deliveryAddress);
+        this.#messaging = messaging;
+        this.#delivery = delivery;
+        this.#agentId = messaging.agentId ?? delivery.agentId();
+        this.#attachments += 1;
     }
     /** Tell the broker Pi is shutting down, ending both attachments so the session name is free at once. */
     async detach() {

package/dist/src/implementations/pi/extension.d.ts

@@ -34,8 +34,13 @@ export interface PiExtensionScheduler {
 export type PiExtensionDependencies = {
     /** Reads service configuration without opening the broker database. */
     readEnvironment(): RuntimeEnvironment;
-    /** Starts or adopts the shared broker service. */
-    ensureService(environment: RuntimeEnvironment): Promise<BrokerEndpoints>;
+    /**
+     * Starts or adopts the shared broker service.
+     * @param environment - Resolved configuration naming the database the service owns.
+     * @param report - Receives what a service this call started wrote while starting.
+     * @returns - The live service's endpoints.
+     */
+    ensureService(environment: RuntimeEnvironment, report: (message: string) => void): Promise<BrokerEndpoints>;
     /** Supplies launch identity and runtime selection values. */
     processEnv: NodeJS.ProcessEnv;
     /** Performs one broker HTTP request. */

package/dist/src/implementations/pi/extension.js

@@ -87,7 +87,14 @@ export function createPiExtension(dependencies) {
                 // A direct-mode registration displaced whatever the identity held, so its fresh reservations
                 // are the only working ones.
                 if (!runtime.client || runtime.connectionKey !== connection.key || connection.directCwd !== undefined) {
-                    runtime.client = await PiBrokerClient.connect(connection.brokerUrl, connection.identity, dependencies.fetch, connection.sessionKey);
+                    runtime.client = await PiBrokerClient.connect(connection.brokerUrl, connection.identity, dependencies.fetch, connection.sessionKey, connection.sessionKey
+                        ? () => registerPiAgent({
+                            request: dependencies.fetch,
+                            brokerUrl: connection.brokerUrl,
+                            workspacePath: ctx.cwd,
+                            sessionKey: connection.sessionKey,
+                        })
+                        : undefined);
                     runtime.connectionKey = connection.key;
                     runtime.directCwd = connection.directCwd;
                 }
@@ -175,7 +182,12 @@ async function resolveConnection(dependencies, ctx) {
             directCwd: undefined,
         };
     }
-    const endpoints = await dependencies.ensureService(dependencies.readEnvironment());
+    const endpoints = await dependencies.ensureService(dependencies.readEnvironment(), (message) => {
+        if (ctx.hasUI)
+            ctx.ui.notify(message.trim(), "info");
+        else
+            process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
+    });
     const identity = await registerPiAgent({
         request: dependencies.fetch,
         brokerUrl: endpoints.mcpUrl,
@@ -236,7 +248,7 @@ function hasLaunchIdentity(environment) {
 }
 const defaultDependencies = {
     readEnvironment: () => readEmbeddedRuntimeEnvironment(process.env, resolveBunExecutable),
-    ensureService: (environment) => ensureBrokerService(environment),
+    ensureService: (environment, report) => ensureBrokerService(environment, { report }),
     processEnv: process.env,
     fetch: (url, init) => globalThis.fetch(url, init),
     runtimeSlot: systemPiRuntimeSlot(),

package/dist/src/index.d.ts

@@ -10,7 +10,7 @@ export { createImplementationRegistry } from "./launch/runtime-composition.js";
 export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, type PagerConfig, type ConfigurationLoadOptions, type ConfigurationSettingPrecedence, type LoadedConfiguration, } from "./configuration.js";
 export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, type AttachState, type ForegroundProcessSpawner, type LaunchDiagnostic, type LaunchRequest, type LaunchResult, type ProcessSpawner, type ProcessState, type TerminalLaunch, type TerminalProvider, type TerminalProviderName, type TerminalSession, type TerminalTaskCompletion, } from "./launch/launch.js";
 export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, type RuntimeProbe, } from "./launch/runtime.js";
-export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, type BrokerServiceOptions, type BrokerServiceStatus, } from "./launch/service.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, systemWorkspaceRoot, type BrokerServiceOptions, type BrokerServiceStatus, } from "./launch/service.js";
 export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
 export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
 export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, type RuntimeEnvironment, } from "./launch/environment.js";

package/dist/src/index.js

@@ -9,7 +9,7 @@ export { createImplementationRegistry } from "./launch/runtime-composition.js";
 export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, } from "./configuration.js";
 export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, } from "./launch/launch.js";
 export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, } from "./launch/runtime.js";
-export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, } from "./launch/service.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, systemWorkspaceRoot, } from "./launch/service.js";
 export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
 export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
 export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, } from "./launch/environment.js";

package/dist/src/launch/broker-lock.d.ts

@@ -1,7 +1,12 @@
 import { ProtocolError, type BrokerServiceIdentity } from "../broker/protocol.js";
 /** Identifies the ownership schema understood by this release. */
 export declare const SERVICE_PROTOCOL_VERSION = 1;
-/** Identifies the package build that owns production service state. */
+/**
+ * Identifies the package build that owns production service state.
+ *
+ * A source checkout carries a `+checkout` suffix, so its service and a published release of the same
+ * version never adopt each other, and neither is taken for an older release the other may replace.
+ */
 export declare const SERVICE_BUILD_ID: string;
 /** Identifies the production runtime required to own SQLite. */
 export declare const SERVICE_RUNTIME = "bun";
@@ -83,6 +88,29 @@ export declare function brokerLockPath(databasePath: string): string;
  * @returns - Valid parsed lock data when the file is well-formed.
  */
 export declare function readBrokerLock(lockPath: string): BrokerLock | undefined;
+/**
+ * Report whether one service build id names an older release of this package than another.
+ *
+ * Only a build id naming an exact `major.minor.patch` version compares, so a prerelease or a source
+ * checkout on either side is never called older.
+ * @param buildId - Build id read from a lock record, possibly written by a foreign build.
+ * @param currentBuildId - Build id of the caller.
+ * @returns - True only when both name releases of this package and `buildId`'s is lower.
+ */
+export declare function isOlderServiceBuild(buildId: string, currentBuildId: string): boolean;
+/**
+ * Report whether a live lock owner is one a starting service of this build may stop and replace.
+ *
+ * The lock must carry this build's lock format, runtime and wire protocol, as {@link readBrokerLock}
+ * requires, and an older release of this package must have written it, whatever its database schema.
+ * The platform must confirm that the process holding the lock's pid started when the lock records, so
+ * a reused pid, or one whose start time cannot be read, is never signalled.
+ * @param lock - Lock record, possibly written by a foreign build.
+ * @param ownerStartedAt - Start time the platform reports now for the lock's pid.
+ * @param currentBuildId - Build id of the service that would replace the owner.
+ * @returns - True only when every condition holds.
+ */
+export declare function brokerLockIsReplaceable(lock: BrokerLock | undefined, ownerStartedAt: ProcessStartTime, currentBuildId?: string): boolean;
 /**
  * Name the package version of the build that wrote a lock record.
  * @param lock - Lock record, possibly written by a foreign build.
@@ -91,6 +119,13 @@ export declare function readBrokerLock(lockPath: string): BrokerLock | undefined
 export declare function brokerLockVersion(lock: Pick<BrokerLock, "buildId">): string;
 /** Bounds how many times acquisition re-attempts after losing a lock-file race. */
 export declare const BROKER_LOCK_ACQUISITION_ATTEMPTS = 5;
+/**
+ * Bounds waiting for a signalled owner to exit. It must exceed `SHUTDOWN_GRACE_MS` in `cli.ts`, the
+ * time a stopping service allows its endpoints to close before it exits on its own.
+ */
+export declare const BROKER_EXIT_TIMEOUT_MS = 10000;
+/** Spaces the liveness polls made while a signalled owner shuts down. */
+export declare const BROKER_EXIT_POLL_MS = 50;
 /** Reports the start time of a process, or that this platform cannot supply one. */
 export type ProcessStartTime = {
     known: true;
@@ -108,6 +143,13 @@ export type BrokerLockPorts = {
     newHolderToken(): string;
     /** Blocks the calling thread, because lock acquisition runs before the service has an event loop. */
     sleep(milliseconds: number): void;
+    /** Delivers a signal to an older-release owner being replaced. */
+    signal(pid: number, signal: NodeJS.Signals): void;
+    /**
+     * Tells the operator about an owner acquisition stopped on their behalf.
+     * @param message - One line naming the stopped process and the versions involved.
+     */
+    report(message: string): void;
 };
 /** Reports that the lock is held by a live service of the current build. */
 export declare class BrokerServiceAlreadyRunningError extends ProtocolError {
@@ -133,6 +175,14 @@ export declare class BrokerServiceLockOwnedError extends ProtocolError {
     /** Identifies the live process that owns the lock. */
     pid: number);
 }
+/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
+export declare class BrokerServiceExitTimeoutError extends ProtocolError {
+    /**
+     * Construct the failure reported when the owner ignores or outlasts its termination signal.
+     * @param pid - Process id of the owner that was signalled.
+     */
+    constructor(pid: number);
+}
 /** Reports that acquisition kept losing the lock file to another writer. */
 export declare class BrokerLockContendedError extends ProtocolError {
     /** Names the contended lock file. */
@@ -227,20 +277,24 @@ export declare class BrokerLockGuard implements BrokerLockOwner {
      * Construct a guard over one lock file.
      * @param lockPath - Lock file adjacent to the database this process wants to own.
      * @param ports - Operating-system boundaries, replaced only by this module's own tests.
+     * @param buildId - Build id deciding which older-release owners this guard may replace.
      */
-    constructor(lockPath: string, ports?: BrokerLockPorts);
+    constructor(lockPath: string, ports?: BrokerLockPorts, buildId?: string);
     /**
      * Names the lock file this guard claims.
      * @returns - Path the guard was constructed over.
      */
     get path(): string;
     /**
-     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone.
+     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone and stopping
+     * one {@link brokerLockIsReplaceable} accepts.
      *
      * Terminates in every case: each attempt either wins the lock, throws because a live owner holds
      * it, or consumes one of a fixed number of attempts.
      * @throws {BrokerServiceAlreadyRunningError} - A live service of this build holds the lock.
-     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the lock.
+     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the
+     * lock, or a replaceable one refused the signal.
+     * @throws {BrokerServiceExitTimeoutError} - A replaceable owner outlasted its termination signal.
      * @throws {BrokerLockContendedError} - Another writer kept recreating the lock.
      */
     acquire(): void;

package/dist/src/launch/broker-lock.js

@@ -4,12 +4,20 @@ import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync,
 import { basename, dirname, join } from "node:path";
 import { PROTOCOL_VERSION, ProtocolError, SCHEMA_MARKER } from "../broker/protocol.js";
 import { LOOPBACK_HOST } from "../configuration-defaults.js";
-import { PAGER_VERSION } from "../version.js";
+import { compareNumericVersions, parseNumericVersion } from "../shared/versions.js";
+import { PAGER_SOURCE_CHECKOUT, PAGER_VERSION } from "../version.js";
 import { satisfiesBunVersionFloor } from "./runtime.js";
 /** Identifies the ownership schema understood by this release. */
 export const SERVICE_PROTOCOL_VERSION = 1;
-/** Identifies the package build that owns production service state. */
-export const SERVICE_BUILD_ID = `@haywoodmarx/agent-pager@${PAGER_VERSION}`;
+/** Names the package whose builds write service build ids. */
+const SERVICE_PACKAGE = "@haywoodmarx/agent-pager";
+/**
+ * Identifies the package build that owns production service state.
+ *
+ * A source checkout carries a `+checkout` suffix, so its service and a published release of the same
+ * version never adopt each other, and neither is taken for an older release the other may replace.
+ */
+export const SERVICE_BUILD_ID = `${SERVICE_PACKAGE}@${PAGER_VERSION}${PAGER_SOURCE_CHECKOUT ? "+checkout" : ""}`;
 /** Identifies the production runtime required to own SQLite. */
 export const SERVICE_RUNTIME = "bun";
 /**
@@ -117,6 +125,43 @@ export function readBrokerLock(lockPath) {
         return undefined;
     }
 }
+/**
+ * Report whether one service build id names an older release of this package than another.
+ *
+ * Only a build id naming an exact `major.minor.patch` version compares, so a prerelease or a source
+ * checkout on either side is never called older.
+ * @param buildId - Build id read from a lock record, possibly written by a foreign build.
+ * @param currentBuildId - Build id of the caller.
+ * @returns - True only when both name releases of this package and `buildId`'s is lower.
+ */
+export function isOlderServiceBuild(buildId, currentBuildId) {
+    const owner = packageRelease(buildId);
+    const current = packageRelease(currentBuildId);
+    return owner !== undefined && current !== undefined && compareNumericVersions(owner, current) < 0;
+}
+function packageRelease(buildId) {
+    if (!buildId.startsWith(`${SERVICE_PACKAGE}@`))
+        return undefined;
+    return parseNumericVersion(brokerLockVersion({ buildId }), "exact");
+}
+/**
+ * Report whether a live lock owner is one a starting service of this build may stop and replace.
+ *
+ * The lock must carry this build's lock format, runtime and wire protocol, as {@link readBrokerLock}
+ * requires, and an older release of this package must have written it, whatever its database schema.
+ * The platform must confirm that the process holding the lock's pid started when the lock records, so
+ * a reused pid, or one whose start time cannot be read, is never signalled.
+ * @param lock - Lock record, possibly written by a foreign build.
+ * @param ownerStartedAt - Start time the platform reports now for the lock's pid.
+ * @param currentBuildId - Build id of the service that would replace the owner.
+ * @returns - True only when every condition holds.
+ */
+export function brokerLockIsReplaceable(lock, ownerStartedAt, currentBuildId = SERVICE_BUILD_ID) {
+    return (lock !== undefined &&
+        isOlderServiceBuild(lock.buildId, currentBuildId) &&
+        lock.ownerStartedAt !== undefined &&
+        startTimeConfirms(lock.ownerStartedAt, ownerStartedAt));
+}
 /**
  * Name the package version of the build that wrote a lock record.
  * @param lock - Lock record, possibly written by a foreign build.
@@ -196,6 +241,13 @@ export const BROKER_LOCK_ACQUISITION_ATTEMPTS = 5;
 const HOLDER_TOKEN_BYTES = 12;
 /** Delays one re-attempt after losing a lock-file race, in milliseconds. */
 const RECLAIM_RETRY_DELAY_MS = 20;
+/**
+ * Bounds waiting for a signalled owner to exit. It must exceed `SHUTDOWN_GRACE_MS` in `cli.ts`, the
+ * time a stopping service allows its endpoints to close before it exits on its own.
+ */
+export const BROKER_EXIT_TIMEOUT_MS = 10_000;
+/** Spaces the liveness polls made while a signalled owner shuts down. */
+export const BROKER_EXIT_POLL_MS = 50;
 /** Names the reading behind a Linux start time, which pairs boot time with ticks since boot. */
 const LINUX_START_TIME_TAG = "l1";
 /** Names the reading behind a macOS start time, which is an instant in milliseconds. */
@@ -230,6 +282,17 @@ export class BrokerServiceLockOwnedError extends ProtocolError {
         this.name = "BrokerServiceLockOwnedError";
     }
 }
+/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
+export class BrokerServiceExitTimeoutError extends ProtocolError {
+    /**
+     * Construct the failure reported when the owner ignores or outlasts its termination signal.
+     * @param pid - Process id of the owner that was signalled.
+     */
+    constructor(pid) {
+        super("validation_failed", `broker service pid ${String(pid)} was signalled to exit and is still running`);
+        this.name = "BrokerServiceExitTimeoutError";
+    }
+}
 /** Reports that acquisition kept losing the lock file to another writer. */
 export class BrokerLockContendedError extends ProtocolError {
     lockPath;
@@ -356,6 +419,20 @@ export function startTimeStillMatches(recorded, actual) {
     }
     return false;
 }
+/**
+ * Report whether a platform reading positively identifies the process a record describes.
+ *
+ * Unlike {@link startTimeStillMatches}, an unknown reading, or one measured another way, is not a
+ * match.
+ * @param recorded - Start time captured when the record was written.
+ * @param actual - Start time read from the platform now.
+ * @returns - True only for a known reading of the recorded kind that agrees with it.
+ */
+function startTimeConfirms(recorded, actual) {
+    return (actual.known &&
+        startTimeReading(actual.value) === startTimeReading(recorded) &&
+        startTimeStillMatches(recorded, actual));
+}
 function linuxStartTicks(value) {
     return value.split(":")[2];
 }
@@ -375,6 +452,12 @@ export function systemBrokerLockPorts() {
         sleep: (milliseconds) => {
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
         },
+        signal: (pid, signal) => {
+            process.kill(pid, signal);
+        },
+        report: (message) => {
+            process.stderr.write(`${message}\n`);
+        },
     };
 }
 /**
@@ -391,17 +474,20 @@ export class BrokerLockGuard {
     #lockPath;
     #reclaimPath;
     #ports;
+    #buildId;
     #holder;
     #startedAt = { known: false };
     /**
      * Construct a guard over one lock file.
      * @param lockPath - Lock file adjacent to the database this process wants to own.
      * @param ports - Operating-system boundaries, replaced only by this module's own tests.
+     * @param buildId - Build id deciding which older-release owners this guard may replace.
      */
-    constructor(lockPath, ports = systemBrokerLockPorts()) {
+    constructor(lockPath, ports = systemBrokerLockPorts(), buildId = SERVICE_BUILD_ID) {
         this.#lockPath = lockPath;
         this.#reclaimPath = `${lockPath}.reclaim`;
         this.#ports = ports;
+        this.#buildId = buildId;
     }
     /**
      * Names the lock file this guard claims.
@@ -411,12 +497,15 @@ export class BrokerLockGuard {
         return this.#lockPath;
     }
     /**
-     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone.
+     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone and stopping
+     * one {@link brokerLockIsReplaceable} accepts.
      *
      * Terminates in every case: each attempt either wins the lock, throws because a live owner holds
      * it, or consumes one of a fixed number of attempts.
      * @throws {BrokerServiceAlreadyRunningError} - A live service of this build holds the lock.
-     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the lock.
+     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the
+     * lock, or a replaceable one refused the signal.
+     * @throws {BrokerServiceExitTimeoutError} - A replaceable owner outlasted its termination signal.
      * @throws {BrokerLockContendedError} - Another writer kept recreating the lock.
      */
     acquire() {
@@ -439,6 +528,10 @@ export class BrokerLockGuard {
             const observed = this.#observe();
             if (observed.state === "live")
                 throw ownerError(observed.pid, observed.current);
+            if (observed.state === "replaceable") {
+                this.#replace(observed);
+                continue;
+            }
             if (observed.state === "absent")
                 continue;
             if (observed.state === "unreadable") {
@@ -569,7 +662,43 @@ export class BrokerLockGuard {
             return { state: "unreadable" };
         if (!this.#ownerIsLive(pid, record))
             return { state: "stale" };
-        return { state: "live", pid, current: brokerLockHasCurrentIdentity(readBrokerLock(this.#lockPath)) };
+        const lock = isBrokerLock(record) ? record : undefined;
+        if (brokerLockHasCurrentIdentity(lock))
+            return { state: "live", pid, current: true };
+        if (lock?.ownerStartedAt !== undefined &&
+            brokerLockIsReplaceable(lock, this.#ports.processStartedAt(pid), this.#buildId)) {
+            return { state: "replaceable", pid, version: brokerLockVersion(lock), startedAt: lock.ownerStartedAt };
+        }
+        // An owner that another service is replacing can exit after the liveness check above, leaving no
+        // start time to confirm. It is a departing owner, not one to refuse.
+        if (!this.#ports.processIsAlive(pid))
+            return { state: "stale" };
+        return { state: "live", pid, current: false };
+    }
+    /**
+     * Stop an older-release owner and wait for it to exit.
+     *
+     * Reports only when this guard's own signal was delivered.
+     * @param owner - The owner {@link brokerLockIsReplaceable} accepted, with its recorded start time.
+     * @param owner.pid - Process id to signal.
+     * @param owner.version - Version of the owner, named in the report.
+     * @param owner.startedAt - Start time the lock records, which a reused pid would not match.
+     */
+    #replace(owner) {
+        try {
+            this.#ports.signal(owner.pid, "SIGTERM");
+        }
+        catch {
+            if (!this.#ports.processIsAlive(owner.pid))
+                return;
+            throw new BrokerServiceLockOwnedError(owner.pid);
+        }
+        for (let waited = 0; this.#ownerIsLive(owner.pid, { ownerStartedAt: owner.startedAt }); waited += BROKER_EXIT_POLL_MS) {
+            if (waited >= BROKER_EXIT_TIMEOUT_MS)
+                throw new BrokerServiceExitTimeoutError(owner.pid);
+            this.#ports.sleep(BROKER_EXIT_POLL_MS);
+        }
+        this.#ports.report(`stopped broker service pid ${String(owner.pid)} running pager ${owner.version} to start pager ${PAGER_VERSION}`);
     }
     #ownerIsLive(pid, record) {
         if (!this.#ports.processIsAlive(pid))
@@ -586,6 +715,10 @@ export class BrokerLockGuard {
             const observed = this.#observe();
             if (observed.state === "live")
                 throw ownerError(observed.pid, observed.current);
+            // An owner that appeared since the caller's observation is replaced by the caller's next
+            // attempt, outside this span, so the reclaim file is not held while it exits.
+            if (observed.state === "replaceable")
+                return "lock-taken";
             if (observed.state !== "absent")
                 removeIfPresent(this.#lockPath);
             return this.#create(holder) ? "acquired" : "lock-taken";

package/dist/src/launch/launch.d.ts

@@ -32,7 +32,7 @@ export type LaunchRequest = {
     terminalProvider?: TerminalProviderName;
     /** Supplies the broker endpoint injected into implementation configuration. */
     brokerUrl: string;
-    /** Supplies the workspace path associated with the launch. */
+    /** Supplies the directory the launched agent works in, which places it in that directory's workspace. */
     workspacePath: string;
     /** Requests reservationless workspace registration for an interactive wrapper session. */
     selfRegistration?: boolean;

package/dist/src/launch/on-demand.d.ts

@@ -77,6 +77,11 @@ export type OnDemandServiceDependencies = {
     processIsAlive(pid: number): boolean;
     /** Reports when a process started, so a recycled process id is not mistaken for the owner. */
     processStartedAt(pid: number): ProcessStartTime;
+    /**
+     * Names the build this caller starts, which decides which foreign owners this caller leaves for
+     * its service to replace.
+     */
+    buildId: string;
     /** Reports whether published endpoints answer. */
     endpointsReady(endpoints: BrokerEndpoints): Promise<BrokerProbeOutcome>;
     /** Delays one bounded discovery attempt. */
@@ -143,14 +148,6 @@ export declare class BrokerServiceUnreachableError extends ProtocolError {
     /** Records which kind of failure the last probe saw. */
     outcome: "unreachable" | "unhealthy");
 }
-/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
-export declare class BrokerServiceExitTimeoutError extends ProtocolError {
-    /**
-     * Construct the failure reported when the owner ignores or outlasts its termination signal.
-     * @param pid - Process id of the owner that was signalled.
-     */
-    constructor(pid: number);
-}
 /** Named failure raised when an upgrade encounters a live pre-identity service. */
 export declare class LegacyBrokerServiceError extends ProtocolError {
     /**
@@ -170,6 +167,9 @@ export declare class LegacyBrokerServiceError extends ProtocolError {
 export declare function liveBrokerEndpoints(lock: BrokerLock | undefined, isAlive: (pid: number) => boolean, startedAt?: (pid: number) => ProcessStartTime): BrokerEndpoints | undefined;
 /**
  * Adopt a running broker service or start one detached and wait for its endpoints.
+ *
+ * Never signals a running service itself. A foreign owner that {@link brokerLockIsReplaceable}
+ * accepts is left for the started service to stop while it takes the lock; any other is refused.
  * @param environment - Resolved configuration shared by the caller and service process.
  * @param overrides - Optional process and timing seams for isolated verification.
  * @returns - Live loopback endpoints owned by the singleton service process.