@haywoodmarx/agent-pager 0.1.3 → 0.2.1

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

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { discoverRepositoryCommonDirectory } from "../operator/repository-system.js";
+/** Bounds the repository lookup; a lookup that runs longer is treated as having failed. */
+const WORKSPACE_ROOT_TIMEOUT_MS = 2_000;
+/** Git directory names whose containing directory is the checkout or project they belong to. */
+const REPOSITORY_DIRECTORY_NAMES = new Set([".git", ".bare"]);
+/**
+ * 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 function systemWorkspaceRoot(path) {
+    if (!existsSync(path))
+        return path;
+    const commonDirectory = discoverRepositoryCommonDirectory(path, { gitTimeoutMs: WORKSPACE_ROOT_TIMEOUT_MS });
+    if (commonDirectory === null)
+        return path;
+    return REPOSITORY_DIRECTORY_NAMES.has(basename(commonDirectory)) ? dirname(commonDirectory) : path;
+}

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

@@ -90,6 +90,23 @@ export declare class BrokerDeliveryClient {
      */
     call(tool: string, args: Record<string, unknown>): Promise<unknown>;
 }
+/** A failure the broker answered with its own error code. */
+export declare class BrokerRefusal extends Error {
+    /** The broker's error code, such as `expired`. */
+    readonly code: string;
+    /**
+     * Construct a refusal carrying the broker's message and code.
+     * @param message - The broker's own explanation.
+     * @param code - The broker's error code for the refusal.
+     */
+    constructor(message: string, code: string);
+}
+/**
+ * Report whether a failure is the broker refusing the session presented as expired.
+ * @param error - Rejection from a broker request.
+ * @returns - True only for a refusal the broker coded `expired`.
+ */
+export declare function isExpiredRefusal(error: unknown): boolean;
 /**
  * Build one compatibility-path tool call, without session headers.
  * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.

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

@@ -118,6 +118,29 @@ export class BrokerDeliveryClient {
         return compatibilityPayload(response, `Broker ${tool}`);
     }
 }
+/** A failure the broker answered with its own error code. */
+export class BrokerRefusal extends Error {
+    /** The broker's error code, such as `expired`. */
+    code;
+    /**
+     * Construct a refusal carrying the broker's message and code.
+     * @param message - The broker's own explanation.
+     * @param code - The broker's error code for the refusal.
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = "BrokerRefusal";
+        this.code = code;
+    }
+}
+/**
+ * Report whether a failure is the broker refusing the session presented as expired.
+ * @param error - Rejection from a broker request.
+ * @returns - True only for a refusal the broker coded `expired`.
+ */
+export function isExpiredRefusal(error) {
+    return error instanceof BrokerRefusal && error.code === "expired";
+}
 /**
  * Build one compatibility-path tool call, without session headers.
  * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.
@@ -227,7 +250,14 @@ async function parseEnvelopeBody(response, operation) {
 function envelopeFailure(response, payload, operation) {
     const error = asRecord(payload?.error);
     const message = typeof error?.message === "string" ? error.message : `${operation} failed (${String(response.status)})`;
-    return new Error(message);
+    const code = refusalCode(error);
+    return code === undefined ? new Error(message) : new BrokerRefusal(message, code);
+}
+function refusalCode(error) {
+    const rpcData = asRecord(error?.data);
+    if (typeof rpcData?.code === "string")
+        return rpcData.code;
+    return typeof error?.code === "string" ? error.code : undefined;
 }
 /**
  * Accept an object carrying only permitted fields, rejecting anything additional.

package/dist/src/messaging/identity-statement.d.ts

@@ -0,0 +1,7 @@
+import type { AgentIdentity } from "../broker/broker.js";
+/**
+ * State the identity a session acts as, in the words the broker uses for it.
+ * @param identity - Identity as `whoami` reports it.
+ * @returns - Text naming the alias, workspace, address and agent id, and nothing else.
+ */
+export declare function agentIdentityStatement(identity: AgentIdentity): string;

package/dist/src/messaging/identity-statement.js

@@ -0,0 +1,8 @@
+/**
+ * State the identity a session acts as, in the words the broker uses for it.
+ * @param identity - Identity as `whoami` reports it.
+ * @returns - Text naming the alias, workspace, address and agent id, and nothing else.
+ */
+export function agentIdentityStatement(identity) {
+    return `You are ${identity.alias} in workspace ${identity.workspace}, reachable from any workspace at ${identity.address}. Your agent id is ${identity.id}.`;
+}

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

@@ -1,4 +1,4 @@
-import type { Broker } from "../broker/broker.js";
+import type { AliasClaim, Broker } from "../broker/broker.js";
 import { type AgentId } from "../broker/protocol.js";
 import type { NotificationScheduler } from "./notifications.js";
 /** Supplies notification and push-address operations to the MCP transport. */
@@ -17,11 +17,17 @@ export type McpNotificationPort = {
      * @param agentId - Identity whose address is no longer answered.
      */
     forgetDeliveryAddress?: (agentId: AgentId) => void;
+    /**
+     * Tells the process displaced from an identity that another process took the identity over,
+     * at the address that process registered for it. Called after the takeover committed.
+     * @param claim - The identity taken and what the claiming process gave up.
+     */
+    notifySessionClaimed?: (claim: AliasClaim) => void;
 };
 /** Names the request header an attached session presents its host delivery address in. */
 export declare const DELIVERY_ADDRESS_HEADER = "x-pager-delivery-address";
 /** Broker operations the MCP server reaches. */
-export type McpBrokerPort = Pick<Broker, "ack" | "adoptSessionKey" | "agentIdentity" | "attach" | "broadcast" | "fetch" | "listAgents" | "listTeamMembers" | "registerAgentWithoutReservation" | "releaseAttachments" | "reserveAttachment" | "resolveSession" | "resumeSession" | "send" | "sessionLeaseTtlMs" | "status" | "updateAgentAlias">;
+export type McpBrokerPort = Pick<Broker, "ack" | "adoptSessionKey" | "agentIdentity" | "attach" | "broadcast" | "fetch" | "listAgents" | "listTeamMembers" | "registerAgentWithoutReservation" | "releaseAttachments" | "relocateAgent" | "reserveAttachment" | "resolveSession" | "resumeSession" | "send" | "sessionLeaseTtlMs" | "status">;
 /** Represents a running MCP server and the operation that stops it. */
 export type McpServerHandle = {
     /** Locates the MCP endpoint the server is bound to. */

package/dist/src/messaging/mcp.js

@@ -4,6 +4,7 @@ import { LOOPBACK_HOST } from "../configuration-defaults.js";
 import { closeServer, listenServer, urlHost, writeJson } from "../shared/http.js";
 import { isPlainObject } from "../shared/guards.js";
 import { assertProtocolVersion, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_MAX, normalizeMessageSubject, normalizeMessageType, ATTACH_HEADER, ProtocolError, validateImplementationId, validateSessionKey, } from "../broker/protocol.js";
+import { agentIdentityStatement } from "./identity-statement.js";
 import { MCP_TOOLS } from "./tools.js";
 import { PAGER_VERSION } from "../version.js";
 /**
@@ -234,7 +235,19 @@ function runTool(context, attached, tool, args, surface) {
         case "update_agent_alias":
             if (typeof args.alias !== "string")
                 throw new ProtocolError("validation_failed", "Agent alias is required");
-            return broker.updateAgentAlias(attached.agentId, args.alias);
+            return relocate(context, attached.agentId, { alias: args.alias, force: forceFlag(args.force) });
+        case "move_to_workspace":
+            if (typeof args.workspace !== "string" || args.workspace === "") {
+                throw new ProtocolError("validation_failed", "Target workspace is required");
+            }
+            if (args.alias !== undefined && typeof args.alias !== "string") {
+                throw new ProtocolError("validation_failed", "Agent alias must be a string");
+            }
+            return relocate(context, attached.agentId, {
+                workspace: args.workspace,
+                ...(typeof args.alias === "string" ? { alias: args.alias } : {}),
+                force: forceFlag(args.force),
+            });
         case "adopt_session_key": {
             return broker.adoptSessionKey(attached.agentId, validateSessionKey(args.sessionKey));
         }
@@ -283,6 +296,32 @@ function runTool(context, attached, tool, args, surface) {
             throw new ProtocolError("validation_failed", "Unknown tool");
     }
 }
+/**
+ * Move or rename the caller, and tell a displaced process once the takeover is durable.
+ *
+ * The claiming process's own address is still registered under the identity it gave up; its next
+ * request registers it under the identity it now acts as.
+ * @param context - Server context carrying the broker and the optional notification port.
+ * @param agentId - Identity the caller authenticated as.
+ * @param request - Target workspace, alias, and whether to take the alias over.
+ * @returns - The identity the caller now acts as, as `whoami` reports it.
+ */
+function relocate(context, agentId, request) {
+    const { broker, notifications } = context;
+    const relocation = broker.relocateAgent(agentId, request);
+    if (relocation.claim) {
+        notifications?.notifySessionClaimed?.(relocation.claim);
+        notifications?.forgetDeliveryAddress?.(relocation.claim.retiredId);
+    }
+    return relocation.identity;
+}
+function forceFlag(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean")
+        throw new ProtocolError("validation_failed", "force must be a boolean");
+    return value;
+}
 /**
  * Report whether a decoded body claims to be a JSON-RPC request.
  *
@@ -302,6 +341,17 @@ function isMcpRequest(value) {
 function namedParameter(params, name) {
     return isPlainObject(params) ? params[name] : undefined;
 }
+/**
+ * Answer one JSON-RPC request on the broker's MCP endpoint.
+ *
+ * An `initialize` request attaches a new session, or resumes the one it presents, and its result's
+ * `instructions` is {@link agentIdentityStatement} for the identity the session now acts as, the
+ * same text for an attach and a resume.
+ * @param context - Broker, notification and diagnostics collaborators the server runs with.
+ * @param request - HTTP request carrying the JSON-RPC body and the session headers.
+ * @param response - HTTP response the result or error is written to.
+ * @param rpc - Decoded JSON-RPC request.
+ */
 function handleMcpRequest(context, request, response, rpc) {
     const { broker } = context;
     if (rpc.method === "initialize") {
@@ -324,8 +374,10 @@ function handleMcpRequest(context, request, response, rpc) {
         // The session above is already established by the time this can throw, so an internal failure here
         // must still carry its headers — otherwise a client that just attached or transparently resumed is
         // left presenting credentials the server has already superseded.
+        let instructions;
         try {
             registerDeliveryAddress(context, request, attached.agentId);
+            instructions = agentIdentityStatement(broker.agentIdentity(attached.agentId));
         }
         catch (error) {
             if (error instanceof ProtocolError) {
@@ -340,6 +392,7 @@ function handleMcpRequest(context, request, response, rpc) {
             protocolVersion: typeof declared === "string" ? declared : DEFAULT_MCP_PROTOCOL_VERSION,
             capabilities: { tools: {} },
             serverInfo: { name: "pager", version: PAGER_VERSION },
+            instructions,
         }, headers);
         return;
     }

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/commands.d.ts

@@ -12,6 +12,8 @@ export interface OperatorCommandBrokerPort {
     acceptOperatorExpiry(commandId: string, messageId: string): BrokerOperatorCommandAcceptance;
     /** Mark an agent archived and persist command acceptance in one transaction, ending its attachments but leaving its inbox and addressability intact. */
     acceptOperatorArchive(commandId: string, targetAgentId: AgentId): BrokerOperatorCommandAcceptance;
+    /** Delete agents and their records, and persist command acceptance, in one transaction. */
+    acceptOperatorPurge(commandId: string, targetAgentIds: readonly AgentId[]): BrokerOperatorCommandAcceptance;
 }
 /** Supplies non-reentrant notification admission around durable ping acceptance. */
 export interface OperatorPingSchedulerPort {