@haywoodmarx/agent-pager 0.1.3 → 0.2.0

package/dist/src/messaging/notifications.d.ts

@@ -43,10 +43,24 @@ export type OperatorPingChanged = InboxChangedBase & {
     /** Preserves every additional command correlation represented by a coalesced wake. */
     coalescedControlIds: string[];
 };
-/** Represents exactly one mutually exclusive message or operator-control wake. */
-export type InboxChanged = InboxMessageChanged | OperatorPingChanged;
+/**
+ * Tells the process connected to an identity that another process took the identity over, and that
+ * its session has ended.
+ */
+export type SessionClaimedChanged = InboxChangedBase & {
+    /** Records that the identity's alias was claimed by another process. */
+    reason: "session_claimed";
+    /** Address that was taken, as it reached the identity. */
+    claimedAddress: string;
+    /** Address the claiming process held before the claim. */
+    claimantAddress: string;
+    /** Identity the claiming process held before the claim. */
+    claimantId: AgentId;
+};
+/** Represents exactly one mutually exclusive message, operator-control, or session-claimed wake. */
+export type InboxChanged = InboxMessageChanged | OperatorPingChanged | SessionClaimedChanged;
 /** Records a message-related reason that may optionally carry one durable message identity. */
-export type InboxMessageReason = Exclude<InboxChanged["reason"], "operator_ping">;
+export type InboxMessageReason = Exclude<InboxChanged["reason"], "operator_ping" | "session_claimed">;
 /** Classifies scheduler admission without claiming adapter delivery. */
 export type OperatorPingAdmission = {
     /** Reports an exact durable retry for which no second wake was admitted. */
@@ -150,6 +164,20 @@ export declare class NotificationHub {
      * @returns - Copy of the published event; changing it does not alter what subscribers received.
      */
     publishOperatorPing(agentId: AgentId, controlId: string, coalescedControlIds?: readonly string[]): OperatorPingChanged;
+    /**
+     * Publish the one wake a process receives when another process has taken its identity over.
+     *
+     * Published to the identity's address as the displaced process registered it; the scheduler's
+     * budget does not apply, since nothing is offered again later.
+     * @param agentId - Identity that was taken over, which the displaced process still addresses.
+     * @param claim - Address taken, and the address and identity the claiming process held before.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publishSessionClaimed(agentId: AgentId, claim: {
+        claimedAddress: string;
+        claimantAddress: string;
+        claimantId: AgentId;
+    }): SessionClaimedChanged;
     /**
      * Subscribe an adapter to body-free notification events.
      * @param agentId - Agent whose operational events the listener receives.

package/dist/src/messaging/notifications.js

@@ -71,6 +71,31 @@ export class NotificationHub {
         this.#fanOut(agentId, event);
         return cloneInboxChanged(event);
     }
+    /**
+     * Publish the one wake a process receives when another process has taken its identity over.
+     *
+     * Published to the identity's address as the displaced process registered it; the scheduler's
+     * budget does not apply, since nothing is offered again later.
+     * @param agentId - Identity that was taken over, which the displaced process still addresses.
+     * @param claim - Address taken, and the address and identity the claiming process held before.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publishSessionClaimed(agentId, claim) {
+        const sequence = (this.#sequences.get(agentId) ?? 0) + 1;
+        this.#sequences.set(agentId, sequence);
+        const event = {
+            type: "inbox_changed",
+            agentId,
+            sequence,
+            epoch: this.#epoch,
+            reason: "session_claimed",
+            claimedAddress: claim.claimedAddress,
+            claimantAddress: claim.claimantAddress,
+            claimantId: claim.claimantId,
+        };
+        this.#fanOut(agentId, event);
+        return cloneInboxChanged(event);
+    }
     /**
      * Subscribe an adapter to body-free notification events.
      * @param agentId - Agent whose operational events the listener receives.

package/dist/src/messaging/push-delivery.d.ts

@@ -50,7 +50,8 @@ export declare class PushDeliveryService {
     /**
      * Hold the address a session registered, and deliver anything already waiting for it.
      *
-     * An unchanged address is a no-op.
+     * An unchanged address is a no-op. A session-claimed wake is the last thing written to an address,
+     * which is dropped once it is written.
      * @param agentId - Recipient whose session supplied the address.
      * @param raw - Untrusted address text exactly as the session supplied it.
      * @returns - What the registration changed.

package/dist/src/messaging/push-delivery.js

@@ -36,7 +36,8 @@ export class PushDeliveryService {
     /**
      * Hold the address a session registered, and deliver anything already waiting for it.
      *
-     * An unchanged address is a no-op.
+     * An unchanged address is a no-op. A session-claimed wake is the last thing written to an address,
+     * which is dropped once it is written.
      * @param agentId - Recipient whose session supplied the address.
      * @param raw - Untrusted address text exactly as the session supplied it.
      * @returns - What the registration changed.
@@ -67,7 +68,7 @@ export class PushDeliveryService {
         const unsubscribe = this.#dependencies.hub.subscribe(agentId, (event) => {
             this.#enqueue(agentId, event);
         });
-        this.#registrations.set(agentId, { raw, address: parsed.value, capability, unsubscribe });
+        this.#registrations.set(agentId, { open: true, raw, address: parsed.value, capability, unsubscribe });
         this.#dependencies.scheduler.declareAdapter(agentId, { coalescing: true, maxProtocolVersion: 1 });
         if (this.#dependencies.broker.hasQueuedMessages(agentId))
             this.#dependencies.scheduler.notify(agentId, "resync");
@@ -78,7 +79,11 @@ export class PushDeliveryService {
      * @param agentId - Recipient whose address is no longer usable.
      */
     forget(agentId) {
-        this.#registrations.get(agentId)?.unsubscribe();
+        const registration = this.#registrations.get(agentId);
+        if (registration) {
+            registration.open = false;
+            registration.unsubscribe();
+        }
         this.#registrations.delete(agentId);
     }
     /**
@@ -104,16 +109,19 @@ export class PushDeliveryService {
     }
     #enqueue(agentId, event) {
         const previous = this.#chains.get(agentId) ?? Promise.resolve();
-        const next = previous.then(() => this.#deliver(agentId, event));
+        const registeredAtPublish = this.#registrations.get(agentId);
+        const next = previous.then(() => this.#deliver(agentId, event, registeredAtPublish));
         this.#chains.set(agentId, next);
         void next.finally(() => {
             if (this.#chains.get(agentId) === next)
                 this.#chains.delete(agentId);
         });
     }
-    async #deliver(agentId, event) {
-        const registration = this.#registrations.get(agentId);
-        if (!registration)
+    async #deliver(agentId, event, registeredAtPublish) {
+        // A session-claimed wake is for the process that held the identity when it was published; one that
+        // registers under the identity afterwards is the claimant.
+        const registration = event.reason === "session_claimed" ? registeredAtPublish : this.#registrations.get(agentId);
+        if (!registration?.open)
             return;
         // A shed wake is the scheduler recording that budget refused this one; the schedule offers the
         // inbox again later, so nothing is written now.
@@ -125,6 +133,14 @@ export class PushDeliveryService {
                 await this.#write(agentId, registration, event, []);
                 return;
             }
+            if (event.reason === "session_claimed") {
+                await this.#write(agentId, registration, event, []);
+                // The address belongs to the displaced process, which no longer acts as this identity, so
+                // nothing further for the identity goes there; the claiming process registers its own.
+                if (this.#registrations.get(agentId) === registration)
+                    this.forget(agentId);
+                return;
+            }
             const claims = this.#dependencies.broker
                 .fetch({ agentId, limit: FETCH_LIMIT_DEFAULT, claimedBy: "delivery" })
                 .map(({ id, fromAddress, broadcastAddress, subject, type, body, claimToken }) => ({
@@ -171,6 +187,7 @@ export class PushDeliveryService {
                 return;
             case "undelivered":
                 this.#release(agentId, claims, reach.cause);
+                registration.open = false;
                 // The session re-registers on its next request if it is still alive.
                 if (this.#registrations.get(agentId) === registration)
                     this.forget(agentId);

package/dist/src/messaging/tools.js

@@ -17,23 +17,43 @@ const messageContent = {
     },
     body: { description: "Message payload retained for the recipient to claim." },
 };
+const forceProperty = {
+    type: "boolean",
+    description: "Take the alias over from the agent holding it, when you are certain that identity is yours: its id, alias, inbox and history become yours, it joins your workspace, or the one you move to, its session is told and ended so its next call runs as a fresh unnamed agent, and your previous alias is redirected to it.",
+};
 /** Supplies the single discovery declaration consumed by every Pager MCP server. */
 export const MCP_TOOLS = [
     {
         name: "whoami",
-        description: "Return the authenticated agent id, current alias, and prior aliases.",
+        description: "Return the authenticated agent id, current alias, workspace, the address that reaches it from any workspace, and prior aliases.",
         inputSchema: noArguments,
     },
     {
         name: "update_agent_alias",
-        description: "Replace this agent's workspace-unique alias and durable session name. The alias is lowercased and inner whitespace becomes hyphens, so use the alias returned in the result rather than the one requested.",
+        description: "Replace this agent's workspace-unique alias and durable session name, and return the identity whoami now reports. The sanitised alias is returned in the result. Use the returned value rather than the requested one. An alias another agent holds, or holds as a retired name, fails with alias_conflict naming that agent unless force is set.",
         inputSchema: schema({
             alias: {
                 type: "string",
                 description: "New workspace-unique alias, with an optional leading @. Lowercased, and inner whitespace becomes hyphens.",
             },
+            force: forceProperty,
         }, ["alias"]),
     },
+    {
+        name: "move_to_workspace",
+        description: "Move this agent into another workspace, keeping its id, inbox and history, and return the identity whoami now reports. Every alias it held stays reserved in the workspace it leaves, so a send to its old address is redirected to its new one. An alias another agent in the target holds, or holds as a retired name, fails with alias_conflict naming that agent unless force is set.",
+        inputSchema: schema({
+            workspace: {
+                type: "string",
+                description: "Workspace name as list_agents reports it, or an absolute directory, which names the workspace a session started there would join and may create one.",
+            },
+            alias: {
+                type: "string",
+                description: "Alias to hold in the target workspace, replacing the current one in the same step; defaults to the current alias.",
+            },
+            force: forceProperty,
+        }, ["workspace"]),
+    },
     {
         name: "list_team_members",
         description: "List agents in this agent's own workspace.",

package/dist/src/messaging/wake.js

@@ -23,6 +23,13 @@ export function wakeMetadata(event, brokerEpoch) {
                 coalesced_control_ids: JSON.stringify(event.coalescedControlIds),
             }
             : {}),
+        ...(event.reason === "session_claimed"
+            ? {
+                claimed_address: event.claimedAddress,
+                claimant_address: event.claimantAddress,
+                claimant_id: event.claimantId,
+            }
+            : {}),
     };
 }
 /**

package/dist/src/operator/agent-projection.d.ts

@@ -35,6 +35,9 @@ export declare class OperatorAgentProjectionError extends Error {
 }
 /**
  * Project broker snapshot repositories and agents without changing broker identities.
+ *
+ * An agent groups under the repository its workspace projects to. Its worktree, and whether its
+ * directory still resolves, are projected from its own working directory.
  * @param snapshot - Authoritative broker state containing durable identity and attachment facts.
  * @param dependencies - Explicit repository and implementation collaborators.
  * @returns Bounded repositories and agents suitable for an operator snapshot.
@@ -59,16 +62,16 @@ export type OperatorAgentHealth = {
 /**
  * Report why an agent belongs to the operator archive rather than the active list.
  *
- * Archive membership is not lifecycle alone: an agent whose workspace directory has been removed
+ * Archive membership is not lifecycle alone: an agent whose working directory has been removed
  * can no longer be worked in, so it archives while the broker still holds it active and routable.
- * An operator-archived agent whose workspace is still there did not lose its workspace, so a surface
- * naming the cause must be told which one it is. The causes can hold together, and the first that holds
- * is reported, in this order: the operator's archive, then lifecycle, then a removed workspace. The
+ * An operator-archived agent whose directory is still there did not lose it, so a surface naming
+ * the cause must be told which one it is. The causes can hold together, and the first that holds
+ * is reported, in this order: the operator's archive, then lifecycle, then a removed directory. The
  * operator's own action comes first because it is why they see the agent archived.
  * @param agent - Projected agent whose archive cause is requested.
  * @returns The first cause that holds, or null when the agent is still active.
  */
-export declare function operatorArchiveReason(agent: OperatorAgent): "operator" | "lifecycle" | "workspace_removed" | null;
+export declare function operatorArchiveReason(agent: OperatorAgent): "operator" | "lifecycle" | "directory_removed" | null;
 /**
  * Decide whether an agent belongs to the operator archive rather than the active list.
  * @param agent - Projected agent whose archive membership is requested.

package/dist/src/operator/agent-projection.js

@@ -1,12 +1,15 @@
 import { uniquePathNames } from "../broker/address.js";
 import { operatorDiagnostic } from "./diagnostics.js";
-import { projectRepositoryLocation } from "./repository.js";
+import { projectRepositoryLocation, } from "./repository.js";
 import { OPERATOR_ARRAY_LENGTH_LIMIT, validateOperatorAgent, validateOperatorRepository } from "./validation.js";
 /** Reports an invalid or unbounded projection source. */
 export class OperatorAgentProjectionError extends Error {
 }
 /**
  * Project broker snapshot repositories and agents without changing broker identities.
+ *
+ * An agent groups under the repository its workspace projects to. Its worktree, and whether its
+ * directory still resolves, are projected from its own working directory.
  * @param snapshot - Authoritative broker state containing durable identity and attachment facts.
  * @param dependencies - Explicit repository and implementation collaborators.
  * @returns Bounded repositories and agents suitable for an operator snapshot.
@@ -15,6 +18,15 @@ export function projectOperatorAgents(snapshot, dependencies) {
     assertBounded(snapshot.workspaces.length, "workspace projection");
     assertBounded(snapshot.agents.length, "agent projection");
     const connections = snapshot.connections;
+    const locationsByPath = new Map();
+    const locate = (path) => {
+        const known = locationsByPath.get(path);
+        if (known)
+            return known;
+        const location = projectRepositoryLocation(path, dependencies);
+        locationsByPath.set(path, location);
+        return location;
+    };
     const locationsByWorkspace = new Map();
     const rootPathsById = new Map();
     const admitted = [];
@@ -22,7 +34,14 @@ export function projectOperatorAgents(snapshot, dependencies) {
         if (locationsByWorkspace.has(workspace.id)) {
             throw new OperatorAgentProjectionError(`duplicate broker workspace identity: ${workspace.id}`);
         }
-        const location = projectRepositoryLocation(workspace.path, dependencies);
+        let location;
+        try {
+            location = locate(workspace.path);
+        }
+        catch (error) {
+            reportSkipped(dependencies, "repository", index, error);
+            continue;
+        }
         const existing = rootPathsById.get(location.repository.id);
         if (existing !== undefined && existing !== location.repository.rootPath) {
             throw new OperatorAgentProjectionError(`repository identity collision: ${location.repository.id}`);
@@ -55,6 +74,7 @@ export function projectOperatorAgents(snapshot, dependencies) {
             continue;
         }
         try {
+            const workingLocation = locate(agent.workingDirectory);
             agents.push(validateOperatorAgent({
                 id: agent.id,
                 alias: bareAlias(agent.alias),
@@ -62,10 +82,10 @@ export function projectOperatorAgents(snapshot, dependencies) {
                 registeredAt: agent.createdAt,
                 lifecycle: agent.state,
                 archivedAt: agent.archivedAt,
-                workspaceAvailable: location.available,
+                workspaceAvailable: workingLocation.available,
                 workspace: workspaceNames.get(agent.workspaceId) ?? agent.workspaceId,
                 brokerIdentity: { teamId: agent.teamId, workspaceId: agent.workspaceId },
-                repository: { repositoryId: location.repository.id, worktree: location.worktree },
+                repository: { repositoryId: location.repository.id, worktree: workingLocation.worktree },
                 adapter: adapterFromConnection(connectionsByAgent.get(agent.id)),
                 implementation: projectImplementation(agent, dependencies.implementations),
             }));
@@ -114,11 +134,11 @@ function reportSkipped(dependencies, scope, index, error) {
 /**
  * Report why an agent belongs to the operator archive rather than the active list.
  *
- * Archive membership is not lifecycle alone: an agent whose workspace directory has been removed
+ * Archive membership is not lifecycle alone: an agent whose working directory has been removed
  * can no longer be worked in, so it archives while the broker still holds it active and routable.
- * An operator-archived agent whose workspace is still there did not lose its workspace, so a surface
- * naming the cause must be told which one it is. The causes can hold together, and the first that holds
- * is reported, in this order: the operator's archive, then lifecycle, then a removed workspace. The
+ * An operator-archived agent whose directory is still there did not lose it, so a surface naming
+ * the cause must be told which one it is. The causes can hold together, and the first that holds
+ * is reported, in this order: the operator's archive, then lifecycle, then a removed directory. The
  * operator's own action comes first because it is why they see the agent archived.
  * @param agent - Projected agent whose archive cause is requested.
  * @returns The first cause that holds, or null when the agent is still active.
@@ -129,7 +149,7 @@ export function operatorArchiveReason(agent) {
     if (agent.lifecycle !== "active")
         return "lifecycle";
     if (!agent.workspaceAvailable)
-        return "workspace_removed";
+        return "directory_removed";
     return null;
 }
 /**

package/dist/src/operator/protocol.d.ts

@@ -143,9 +143,9 @@ export type OperatorAgent = {
      */
     archivedAt: number | null;
     /**
-     * Reports whether the recorded workspace path still resolves on the broker's machine.
+     * Reports whether the agent's recorded working directory still resolves on the broker's machine.
      *
-     * Presentation-only, like the rest of repository grouping: a removed workspace archives its
+     * Presentation-only, like the rest of repository grouping: a removed directory archives its
      * agents in the operator view without changing broker lifecycle, routing, or addressability.
      */
     workspaceAvailable: boolean;

package/dist/src/operator/repository-system.d.ts

@@ -5,6 +5,8 @@ export declare const REPOSITORY_GIT_OUTPUT_LIMIT = 65536;
 export type SystemRepositoryProjectionOptions = {
     /** Selects the Git executable without mutating process PATH. */
     gitExecutable?: string;
+    /** Bounds each Git command's run time in milliseconds; unbounded when omitted. */
+    gitTimeoutMs?: number;
 };
 /**
  * Compose production filesystem and Git discovery adapters.
@@ -12,3 +14,30 @@ export type SystemRepositoryProjectionOptions = {
  * @returns Dependencies whose process execution is isolated from pure projection logic.
  */
 export declare function createSystemRepositoryProjectionDependencies(options?: SystemRepositoryProjectionOptions): RepositoryProjectionDependencies;
+/** Reports how one Git command ended, separating the two answers Git gives for a path it cannot serve. */
+export type GitCommandResult = {
+    kind: "ok";
+    stdout: string;
+} | {
+    kind: "not_git";
+} | {
+    kind: "no_worktree";
+};
+/**
+ * Report the Git directory every worktree of the repository containing a directory shares.
+ * @param path - Absolute directory inside a worktree, or inside a bare repository.
+ * @param options - Executable and time bound for the Git command.
+ * @returns The repository's common Git directory, canonical and absolute, or null when the directory
+ * is not inside a Git repository.
+ * @throws {RepositoryDiscoveryError} When Git is unavailable, times out, or answers with something other than one absolute path.
+ */
+export declare function discoverRepositoryCommonDirectory(path: string, options?: SystemRepositoryProjectionOptions): string | null;
+/**
+ * Run one Git command about the repository its arguments name, with a bounded, captured output.
+ * @param executable - Git executable to spawn.
+ * @param args - Arguments, including the `-C` directory the command is about.
+ * @param timeoutMs - Milliseconds the command may run before it is treated as unavailable; unbounded when undefined.
+ * @returns The command's output, or which of Git's two refusals it answered with.
+ * @throws {RepositoryDiscoveryError} When Git cannot be run, exceeds the timeout or the output limit, or fails for any other reason.
+ */
+export declare function runGit(executable: string, args: string[], timeoutMs: number | undefined): GitCommandResult;

package/dist/src/operator/repository-system.js

@@ -11,6 +11,7 @@ export const REPOSITORY_GIT_OUTPUT_LIMIT = 65_536;
  */
 export function createSystemRepositoryProjectionDependencies(options = {}) {
     const gitExecutable = options.gitExecutable ?? "git";
+    const timeoutMs = options.gitTimeoutMs;
     return {
         fileSystem: {
             canonicalPath: (path) => realpathSync(path),
@@ -18,25 +19,52 @@ export function createSystemRepositoryProjectionDependencies(options = {}) {
         },
         git: {
             inspect: (workspacePath) => {
-                const topLevel = runGit(gitExecutable, ["-C", workspacePath, "rev-parse", "--show-toplevel"], true);
+                const topLevel = runGit(gitExecutable, ["-C", workspacePath, "rev-parse", "--show-toplevel"], timeoutMs);
                 if (topLevel.kind === "not_git")
                     return topLevel;
-                const worktreeRoot = parseSingleAbsolutePath(topLevel.stdout, "Git top-level output is invalid");
-                const topology = runGit(gitExecutable, ["-C", workspacePath, "worktree", "list", "--porcelain", "-z"], false);
-                if (topology.kind === "not_git")
+                const topology = runGit(gitExecutable, ["-C", workspacePath, "worktree", "list", "--porcelain", "-z"], timeoutMs);
+                if (topology.kind !== "ok")
                     throw new RepositoryDiscoveryError("invalid", "Git topology disappeared");
-                const repositoryRoot = parsePrimaryWorktree(topology.stdout, worktreeRoot);
+                const repositoryRoot = parsePrimaryWorktree(topology.stdout);
+                if (topLevel.kind === "no_worktree")
+                    return { kind: "git", repositoryRoot, worktreeRoot: repositoryRoot };
+                const worktreeRoot = parseSingleAbsolutePath(topLevel.stdout, "Git top-level output is invalid");
                 return { kind: "git", repositoryRoot, worktreeRoot };
             },
         },
     };
 }
-function runGit(executable, args, allowNotGit) {
+/**
+ * Report the Git directory every worktree of the repository containing a directory shares.
+ * @param path - Absolute directory inside a worktree, or inside a bare repository.
+ * @param options - Executable and time bound for the Git command.
+ * @returns The repository's common Git directory, canonical and absolute, or null when the directory
+ * is not inside a Git repository.
+ * @throws {RepositoryDiscoveryError} When Git is unavailable, times out, or answers with something other than one absolute path.
+ */
+export function discoverRepositoryCommonDirectory(path, options = {}) {
+    const answer = runGit(options.gitExecutable ?? "git", ["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"], options.gitTimeoutMs);
+    if (answer.kind !== "ok")
+        return null;
+    return parseSingleAbsolutePath(answer.stdout, "Git common directory output is invalid");
+}
+/**
+ * Run one Git command about the repository its arguments name, with a bounded, captured output.
+ * @param executable - Git executable to spawn.
+ * @param args - Arguments, including the `-C` directory the command is about.
+ * @param timeoutMs - Milliseconds the command may run before it is treated as unavailable; unbounded when undefined.
+ * @returns The command's output, or which of Git's two refusals it answered with.
+ * @throws {RepositoryDiscoveryError} When Git cannot be run, exceeds the timeout or the output limit, or fails for any other reason.
+ */
+export function runGit(executable, args, timeoutMs) {
+    // Git redirects itself to whatever these name, which would answer for a repository other than the one asked about.
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"].includes(name)));
     const result = spawnSync(executable, args, {
         encoding: "utf8",
-        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        env: { ...environment, LC_ALL: "C", LANG: "C" },
         maxBuffer: REPOSITORY_GIT_OUTPUT_LIMIT,
         stdio: ["ignore", "pipe", "pipe"],
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     });
     if (result.error) {
         const code = "code" in result.error ? result.error.code : undefined;
@@ -53,8 +81,10 @@ function runGit(executable, args, allowNotGit) {
     if (result.signal !== null)
         throw new RepositoryDiscoveryError("unavailable", "Git discovery process was interrupted");
     if (result.status !== 0) {
-        if (allowNotGit && result.status === 128 && /not a git repository/u.test(stderr))
+        if (result.status === 128 && /not a git repository/u.test(stderr))
             return { kind: "not_git" };
+        if (result.status === 128 && /must be run in a work tree/u.test(stderr))
+            return { kind: "no_worktree" };
         throw new RepositoryDiscoveryError("unavailable", "Git discovery command failed");
     }
     return { kind: "ok", stdout };
@@ -66,7 +96,7 @@ function parseSingleAbsolutePath(output, message) {
     }
     return normalized;
 }
-function parsePrimaryWorktree(output, currentWorktree) {
+function parsePrimaryWorktree(output) {
     if (!output.endsWith("\0\0"))
         throw new RepositoryDiscoveryError("invalid", "Git topology output is truncated");
     const tokens = output.split("\0");
@@ -100,9 +130,6 @@ function parsePrimaryWorktree(output, currentWorktree) {
             throw new RepositoryDiscoveryError("invalid", "Only the primary Git topology record may be bare");
         }
     }
-    if (!worktrees.has(currentWorktree)) {
-        throw new RepositoryDiscoveryError("invalid", "Git topology omitted the current worktree");
-    }
     const primary = topology[0]?.path;
     if (!primary)
         throw new RepositoryDiscoveryError("invalid", "Git topology omitted its primary worktree");

package/dist/src/operator/repository.d.ts

@@ -3,7 +3,7 @@ import type { OperatorRepository, OperatorWorktree } from "./protocol.js";
 export type RepositoryGitLocation = {
     /** Supplies the root of the primary repository worktree. */
     repositoryRoot: string;
-    /** Supplies the root of the worktree containing the inspected workspace. */
+    /** Supplies the root of the worktree containing the inspected directory. */
     worktreeRoot: string;
 };
 /** Reports either confirmed Git topology or a confirmed non-Git workspace. */
@@ -16,13 +16,13 @@ export type RepositoryGitInspection = ({
 export interface RepositoryFileSystemPort {
     /**
      * Resolve aliases and symbolic links in one existing path.
-     * @param path - Absolute workspace or Git root to canonicalize.
+     * @param path - Absolute path or Git root to canonicalize.
      * @returns The canonical absolute filesystem path.
      */
     canonicalPath(path: string): string;
     /**
      * Report whether one recorded path still resolves on this machine.
-     * @param path - Absolute broker workspace path recorded when the agent registered.
+     * @param path - Absolute path recorded at registration.
      * @returns True when the path resolves through any symbolic links, false when it has been removed, is a dangling link, or is unreachable.
      */
     exists(path: string): boolean;
@@ -30,12 +30,28 @@ export interface RepositoryFileSystemPort {
 /** Discovers Git topology without granting it broker routing authority. */
 export interface RepositoryGitPort {
     /**
-     * Inspect one canonical workspace for Git repository topology.
-     * @param workspacePath - Canonical absolute workspace path.
+     * Inspect one canonical directory for Git repository topology.
+     * @param path - Canonical absolute directory to inspect.
      * @returns Confirmed Git topology or a confirmed non-Git result.
      */
-    inspect(workspacePath: string): RepositoryGitInspection;
+    inspect(path: string): RepositoryGitInspection;
 }
+/** Configures how long one Git inspection answers for its path. */
+export type RememberedInspectionOptions = {
+    /** Supplies the clock the expiry is measured against. */
+    now: () => number;
+    /** Milliseconds an inspection answers for before the path is inspected again. */
+    ttlMs: number;
+};
+/**
+ * Wrap a Git port so each path is inspected at most once per expiry window.
+ *
+ * A thrown inspection is remembered like an answered one, and rethrown for the rest of its window.
+ * @param git - Port that performs the inspection when nothing current is remembered.
+ * @param options - Clock and expiry window.
+ * @returns A port answering repeated requests for one path from the last inspection within the window.
+ */
+export declare function rememberRepositoryInspections(git: RepositoryGitPort, options: RememberedInspectionOptions): RepositoryGitPort;
 /** Supplies filesystem and Git collaborators to repository projection. */
 export type RepositoryProjectionDependencies = {
     /** Canonicalizes discovered paths. */
@@ -49,7 +65,7 @@ export type ProjectedRepositoryLocation = {
     repository: Omit<OperatorRepository, "name">;
     /** Carries worktree detail for the inspected workspace. */
     worktree: OperatorWorktree;
-    /** Reports whether the workspace path still resolves, which decides operator archive membership. */
+    /** Reports whether the inspected path still resolves, which decides operator archive membership. */
     available: boolean;
 };
 /** Reports invalid or unavailable repository projection inputs. */
@@ -66,14 +82,15 @@ export declare class RepositoryDiscoveryError extends RepositoryProjectionError
     constructor(code: "unavailable" | "invalid" | "output_limit", message: string);
 }
 /**
- * Project one broker workspace into repository grouping and worktree detail.
+ * Project one directory, a broker workspace or an agent's working directory, into repository
+ * grouping and worktree detail.
  *
- * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * A directory whose path no longer resolves is projected from its recorded path alone. Neither
  * canonicalization nor Git discovery can run against a removed directory, and both throw rather
  * than reporting absence, so the removal is detected before either is attempted.
- * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param workspacePath - Absolute broker workspace path, or agent working directory, to inspect.
  * @param dependencies - Explicit filesystem and Git discovery collaborators.
- * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ * @returns Presentation-only repository and worktree values, and whether the directory still resolves.
  */
 export declare function projectRepositoryLocation(workspacePath: string, dependencies: RepositoryProjectionDependencies): ProjectedRepositoryLocation;
 export {};