@haywoodmarx/agent-pager 0.1.3 → 0.2.1

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.

package/dist/src/launch/on-demand.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ProtocolError } from "../broker/protocol.js";
 import { resolveBunExecutable } from "./runtime.js";
-import { brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockPath, isCurrentBrokerServiceIdentity, processIsAlive, processStartedAt, readBrokerLock, startTimeStillMatches, readBrokerOwner, readBrokerOwnerPid, } from "./broker-lock.js";
+import { BROKER_EXIT_POLL_MS, BROKER_EXIT_TIMEOUT_MS, BrokerServiceExitTimeoutError, brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockIsReplaceable, brokerLockPath, isCurrentBrokerServiceIdentity, processIsAlive, processStartedAt, readBrokerLock, startTimeStillMatches, readBrokerOwner, SERVICE_BUILD_ID, } from "./broker-lock.js";
 /** Bounds one loopback endpoint probe, which either answers promptly or is treated as unreachable. */
 export const BROKER_PROBE_TIMEOUT_MS = 2_000;
 /**
@@ -99,17 +99,6 @@ export class BrokerServiceUnreachableError extends ProtocolError {
         this.name = "BrokerServiceUnreachableError";
     }
 }
-/** 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";
-    }
-}
 /** Named failure raised when an upgrade encounters a live pre-identity service. */
 export class LegacyBrokerServiceError extends ProtocolError {
     /**
@@ -143,6 +132,9 @@ export function liveBrokerEndpoints(lock, isAlive, startedAt) {
 }
 /**
  * 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.
@@ -150,11 +142,10 @@ export function liveBrokerEndpoints(lock, isAlive, startedAt) {
 export async function ensureBrokerService(environment, overrides = {}) {
     const dependencies = { ...defaultDependencies(), ...overrides };
     const lockPath = brokerLockPath(environment.dbPath);
-    const ownerPid = readBrokerOwnerPid(lockPath);
     const candidate = readBrokerLock(lockPath);
-    if (ownerPid && dependencies.processIsAlive(ownerPid) && !brokerLockHasCurrentIdentity(candidate)) {
-        throw new LegacyBrokerServiceError(ownerPid);
-    }
+    const refused = refusedForeignOwner(lockPath, readBrokerOwner(lockPath), candidate, dependencies);
+    if (refused !== undefined)
+        throw new LegacyBrokerServiceError(refused);
     const existing = liveBrokerEndpoints(candidate, dependencies.processIsAlive, dependencies.processStartedAt);
     if (existing) {
         // The lock already proved this is the current build, so a probe that misses is a slow or
@@ -189,11 +180,12 @@ export async function ensureBrokerService(environment, overrides = {}) {
     let unanswered;
     try {
         while (dependencies.now() <= deadline) {
-            const loopOwnerPid = readBrokerOwnerPid(lockPath);
+            const loopOwner = readBrokerOwner(lockPath);
+            const loopOwnerPid = loopOwner?.pid;
             const loopCandidate = readBrokerLock(lockPath);
-            if (loopOwnerPid && dependencies.processIsAlive(loopOwnerPid) && !brokerLockHasCurrentIdentity(loopCandidate)) {
-                throw new LegacyBrokerServiceError(loopOwnerPid);
-            }
+            const loopRefused = refusedForeignOwner(lockPath, loopOwner, loopCandidate, dependencies);
+            if (loopRefused !== undefined)
+                throw new LegacyBrokerServiceError(loopRefused);
             const endpoints = liveBrokerEndpoints(loopCandidate, dependencies.processIsAlive, dependencies.processStartedAt);
             unanswered = undefined;
             if (endpoints) {
@@ -243,13 +235,6 @@ export async function ensureBrokerService(environment, overrides = {}) {
         child.releaseOutput();
     }
 }
-/**
- * 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.
- */
-const BROKER_EXIT_TIMEOUT_MS = 10_000;
-/** Spaces the liveness polls made while a signalled owner shuts down. */
-const BROKER_EXIT_POLL_MS = 50;
 /**
  * Stop the broker service that owns the configured database, whichever build started it.
  *
@@ -261,13 +246,10 @@ const BROKER_EXIT_POLL_MS = 50;
  */
 export async function stopBrokerService(environment, overrides = {}) {
     const dependencies = {
-        processIsAlive,
-        processStartedAt,
+        ...systemProcessDependencies(),
         signal: (pid, signal) => {
             process.kill(pid, signal);
         },
-        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
-        now: Date.now,
         ...overrides,
     };
     const owner = readBrokerOwner(brokerLockPath(environment.dbPath));
@@ -376,8 +358,21 @@ function spawnCapturingStderr(command, args, environment) {
         },
     };
 }
+/**
+ * Build the operating-system process and timing seams shared by starting and stopping a service.
+ * @returns - Seams backed by the process table, timers and the wall clock.
+ */
+function systemProcessDependencies() {
+    return {
+        processIsAlive,
+        processStartedAt,
+        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        now: Date.now,
+    };
+}
 function defaultDependencies() {
     return {
+        ...systemProcessDependencies(),
         spawnService: spawnCapturingStderr,
         report: (message) => {
             process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
@@ -386,8 +381,7 @@ function defaultDependencies() {
             command: resolveBunExecutable(environment.processEnv),
             args: [fileURLToPath(new URL("./cli.js", import.meta.url)), "serve"],
         }),
-        processIsAlive,
-        processStartedAt,
+        buildId: SERVICE_BUILD_ID,
         endpointsReady: async ({ mcpUrl, snapshotUrl }) => {
             let health;
             let snapshot;
@@ -421,8 +415,6 @@ function defaultDependencies() {
                 return "unhealthy";
             }
         },
-        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
-        now: Date.now,
     };
 }
 function adoptionRetryDelayMs(probes) {
@@ -433,3 +425,30 @@ function ownerStartTimeMatches(lock, startedAt) {
         return true;
     return startTimeStillMatches(lock.ownerStartedAt, startedAt(lock.pid));
 }
+/**
+ * Name the live foreign owner this caller must refuse.
+ *
+ * An owner counts as live only when its process started at the time its lock records.
+ * @param lockPath - Lock file both records were read from, read again before refusing.
+ * @param owner - Owner read from any structurally valid lock, current or legacy.
+ * @param lock - The same file read as a lock record this build accepts, when it is one.
+ * @param dependencies - Process seams reading liveness and start times.
+ * @returns - The owner's pid when it must be refused, or undefined when it is absent, stale, current,
+ * or replaceable.
+ */
+function refusedForeignOwner(lockPath, owner, lock, dependencies) {
+    if (owner === undefined || !dependencies.processIsAlive(owner.pid))
+        return undefined;
+    const startedAt = dependencies.processStartedAt(owner.pid);
+    if (owner.startedAt !== undefined && !startTimeStillMatches(owner.startedAt, startedAt))
+        return undefined;
+    if (brokerLockHasCurrentIdentity(lock))
+        return undefined;
+    if (lock?.pid === owner.pid && brokerLockIsReplaceable(lock, startedAt, dependencies.buildId))
+        return undefined;
+    // An owner that another starting service is replacing can exit, or remove its lock, between the
+    // reads above, leaving no start time or record to judge. It is a departing owner, not a foreign one.
+    if (!dependencies.processIsAlive(owner.pid) || readBrokerOwner(lockPath)?.pid !== owner.pid)
+        return undefined;
+    return owner.pid;
+}

package/dist/src/launch/runtime-composition.js

@@ -15,6 +15,7 @@ import { discoverImplementationRegistry, implementationId, } from "../implementa
 import { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, } from "./launch.js";
 import { spawnForegroundProcess } from "./terminal.js";
 import { systemWorkspaceBranch } from "./workspace-branch.js";
+import { systemWorkspaceRoot } from "./workspace-root.js";
 import { initializePagerStore } from "../configuration.js";
 import { isPlainObject } from "../shared/guards.js";
 export { readRuntimeEnvironment } from "./environment.js";
@@ -33,6 +34,7 @@ export function createBroker(environment) {
     return new Broker(environment.dbPath, {
         now: Date.now,
         workspaceBranch: systemWorkspaceBranch,
+        workspaceRoot: systemWorkspaceRoot,
         report: (message) => {
             process.stderr.write(`${message}\n`);
         },

package/dist/src/launch/runtime.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, realpathSync } from "node:fs";
 import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { compareNumericVersions, parseNumericVersion } from "../shared/versions.js";
 import { readRuntimeEnvironment } from "./environment.js";
 /** Bounds one probe of an external runtime executable. */
 const RUNTIME_PROBE_TIMEOUT_MS = 10_000;
@@ -32,22 +33,11 @@ export class BunRuntimeError extends Error {
  * @returns - True when the version is at or above the supported floor.
  */
 export function satisfiesBunVersionFloor(version) {
-    const candidate = numericVersion(version);
-    const minimum = numericVersion(MINIMUM_BUN_VERSION);
+    const candidate = parseNumericVersion(version, "prefix");
+    const minimum = parseNumericVersion(MINIMUM_BUN_VERSION, "prefix");
     if (!candidate || !minimum)
         return false;
-    for (let index = 0; index < minimum.length; index += 1) {
-        const difference = (candidate[index] ?? 0) - (minimum[index] ?? 0);
-        if (difference !== 0)
-            return difference > 0;
-    }
-    return true;
-}
-function numericVersion(version) {
-    const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(version);
-    if (!match)
-        return undefined;
-    return [Number(match[1]), Number(match[2]), Number(match[3])];
+    return compareNumericVersions(candidate, minimum) >= 0;
 }
 /**
  * Fail fast when the current process is not a supported Bun runtime.

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

@@ -10,6 +10,7 @@ import { type OperatorTransportSchedulerPort } from "../operator/transport.js";
 import { type OperatorUpdateSourcePort } from "../operator/updates.js";
 import { type BrokerLockOwner } from "./broker-lock.js";
 export { systemWorkspaceBranch } from "./workspace-branch.js";
+export { systemWorkspaceRoot } from "./workspace-root.js";
 /** Schedules the service's timers, none of which may keep the process alive. */
 export interface BrokerServiceSchedulerPort extends OperatorTransportSchedulerPort {
     /**

package/dist/src/launch/service.js

@@ -9,13 +9,16 @@ import { startMcpServer } from "../messaging/mcp.js";
 import { NotificationHub, NotificationScheduler } from "../messaging/notifications.js";
 import { PushDeliveryService } from "../messaging/push-delivery.js";
 import { OperatorCommandService } from "../operator/commands.js";
+import { rememberRepositoryInspections } from "../operator/repository.js";
 import { createSystemRepositoryProjectionDependencies } from "../operator/repository-system.js";
 import { issueOperatorClientId, startOperatorTransport, } from "../operator/transport.js";
 import { SqliteOperatorEventStore } from "../operator/update-store.js";
 import { OperatorUpdateService } from "../operator/updates.js";
 import { currentBrokerServiceIdentity } from "./broker-lock.js";
 import { systemWorkspaceBranch } from "./workspace-branch.js";
+import { systemWorkspaceRoot } from "./workspace-root.js";
 export { systemWorkspaceBranch } from "./workspace-branch.js";
+export { systemWorkspaceRoot } from "./workspace-root.js";
 /** Tables whose rows can move the moment a sweep next has work to do. */
 const SWEEP_DEADLINE_TABLES = ["agents", "sessions", "messages", "wakes"];
 /** Sets how often the watchdog checks that the database this service serves still exists. */
@@ -26,6 +29,10 @@ const OPERATOR_HEARTBEAT_INTERVAL_MS = 5_000;
 const OPERATOR_LIVENESS_TIMEOUT_MS = 15_000;
 /** Sets the entropy of an operator control id, in bytes. */
 const CONTROL_ID_BYTES = 12;
+/** Bounds how long one directory's Git inspection stands in for a fresh one in operator projections. */
+const REPOSITORY_INSPECTION_TTL_MS = 30_000;
+/** Bounds each Git command the operator projection runs; one that runs longer is treated as having failed. */
+const REPOSITORY_DISCOVERY_TIMEOUT_MS = 2_000;
 /** Delays the retry after a sweep failed, so a persistent failure cannot spin on a due deadline. */
 const SWEEP_FAILURE_RETRY_MS = 1_000;
 /** Reports that a configured loopback endpoint could not take its port. */
@@ -137,6 +144,7 @@ export class BrokerService {
             this.#broker = this.#options.openBroker(this.#databasePath, {
                 now,
                 workspaceBranch: systemWorkspaceBranch,
+                workspaceRoot: systemWorkspaceRoot,
                 report: this.#report,
                 ...(config
                     ? {
@@ -194,6 +202,13 @@ export class BrokerService {
                     forgetDeliveryAddress: (agentId) => {
                         pushDelivery.forget(agentId);
                     },
+                    notifySessionClaimed: (claim) => {
+                        notifications.publishSessionClaimed(claim.agentId, {
+                            claimedAddress: claim.address,
+                            claimantAddress: claim.retiredAddress,
+                            claimantId: claim.retiredId,
+                        });
+                    },
                 },
                 host: bindHost,
                 healthIdentity: currentBrokerServiceIdentity(),
@@ -423,12 +438,19 @@ export class BrokerService {
             const descriptors = new Map();
             for (const descriptor of this.#implementations.descriptors())
                 descriptors.set(descriptor.id, descriptor);
+            const repositoryDiscovery = createSystemRepositoryProjectionDependencies({
+                gitTimeoutMs: REPOSITORY_DISCOVERY_TIMEOUT_MS,
+            });
             const operatorUpdates = new OperatorUpdateService({
                 source: broker,
                 store,
                 now: this.#now,
                 projection: {
-                    ...createSystemRepositoryProjectionDependencies(),
+                    fileSystem: repositoryDiscovery.fileSystem,
+                    git: rememberRepositoryInspections(repositoryDiscovery.git, {
+                        now: this.#now,
+                        ttlMs: REPOSITORY_INSPECTION_TTL_MS,
+                    }),
                     implementations: {
                         find: (implementationId) => {
                             const descriptor = descriptors.get(implementationId);

package/dist/src/launch/workspace-branch.d.ts

@@ -1,10 +1,10 @@
 /**
- * Report the branch checked out at a workspace path.
+ * Report the branch checked out at an agent's working directory.
  *
  * A standalone module so a caller composing only the broker itself avoids pulling in the whole
  * `BrokerService` module graph for one `git` lookup.
- * @param path - Absolute workspace path to inspect.
+ * @param path - Absolute working directory to inspect.
  * @returns - Current branch name, or null when the path is not a repository, is detached, or the
- * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ * lookup failed or did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
  */
 export declare function systemWorkspaceBranch(path: string): string | null;

package/dist/src/launch/workspace-branch.js

@@ -1,27 +1,19 @@
-import { execFileSync } from "node:child_process";
-/**
- * Bounds the branch lookup, which runs a subprocess against a path this process does not control.
- *
- * The branch is a label on a workspace row; nothing waits on it, so a slow answer is discarded
- * rather than waited for.
- */
+import { runGit } from "../operator/repository-system.js";
+/** Bounds the branch lookup; a lookup that runs longer is treated as having failed. */
 const WORKSPACE_BRANCH_TIMEOUT_MS = 2_000;
 /**
- * Report the branch checked out at a workspace path.
+ * Report the branch checked out at an agent's working directory.
  *
  * A standalone module so a caller composing only the broker itself avoids pulling in the whole
  * `BrokerService` module graph for one `git` lookup.
- * @param path - Absolute workspace path to inspect.
+ * @param path - Absolute working directory to inspect.
  * @returns - Current branch name, or null when the path is not a repository, is detached, or the
- * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ * lookup failed or did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
  */
 export function systemWorkspaceBranch(path) {
     try {
-        return (execFileSync("git", ["-C", path, "branch", "--show-current"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: WORKSPACE_BRANCH_TIMEOUT_MS,
-        }).trim() || null);
+        const result = runGit("git", ["-C", path, "branch", "--show-current"], WORKSPACE_BRANCH_TIMEOUT_MS);
+        return result.kind === "ok" ? result.stdout.trim() || null : null;
     }
     catch {
         return null;

package/dist/src/launch/workspace-root.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Report the directory that names the workspace a working directory belongs to.
+ *
+ * Inside a Git repository that is one directory for every worktree of the repository, so the main
+ * worktree, every linked worktree, and every subdirectory of any of them share one workspace: the
+ * directory holding the repository's `.git` or `.bare` directory.
+ * @param path - Absolute working directory to inspect.
+ * @returns - Canonical directory naming the repository containing the path, or the path itself when
+ * it is not inside a repository, its Git directory is not named `.git` or `.bare`, or it does not exist.
+ * @throws {RepositoryDiscoveryError} When Git cannot answer: it is missing, failed, or did not answer
+ * within {@link WORKSPACE_ROOT_TIMEOUT_MS}.
+ */
+export declare function systemWorkspaceRoot(path: string): string;