@haywoodmarx/agent-pager 0.1.3 → 0.2.0

package/dist/src/broker/broker.js

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { openBrokerDatabase, } from "./database.js";
 import { decodeMessageBody, encodeMessageBody, issueOpaqueToken, assertAgentId, FETCH_LIMIT_DEFAULT, isAgentId, isDirectAgentAddress, mintAgentId, normalizeMessageSubject, normalizeMessageType, ProtocolError, validateImplementationId, validateSessionKey, } from "./protocol.js";
 import { PAGER_DEFAULTS } from "../configuration-defaults.js";
 import { publicEpoch } from "./snapshot.js";
-import { normalizeAlias, parseAgentAddress, parseWorkspaceName, uniquePathNames, validateRegistrationSessionName, workspaceIdentity, workspaceTeamId, } from "./address.js";
-import { ATTACHMENT_CHANNELS, BrokerSchema, MESSAGE_STATES } from "./schema.js";
+import { formatAgentAddress, normalizeAlias, parseAgentAddress, parseWorkspaceName, uniquePathNames, validateRegistrationSessionName, workspaceIdentity, workspaceTeamId, } from "./address.js";
+import { ATTACHMENT_CHANNELS, BrokerSchema, MESSAGE_STATES, } from "./schema.js";
 import { assertDurableOperatorId, readStoredAgentId, readStoredEnum, BrokerOperatorProjection, } from "./operator-projection.js";
 const notificationDisplay = {
     delivered: { text: "notify delivered", tone: "ok" },
@@ -104,6 +104,7 @@ export class Broker {
     #epochOwner;
     #lifecycleSynchronization;
     #workspaceBranch;
+    #workspaceRoot;
     #report;
     #projection;
     #commitListeners = new Set();
@@ -113,12 +114,13 @@ export class Broker {
     /**
      * Opens a durable broker database with the supplied timing and routing policies.
      * @param path - SQLite database location, or memory sentinel, for durable state.
-     * @param options - Clock, workspace-branch lookup, and diagnostics sink are required; see {@link BrokerOptions} for its optional fields.
+     * @param options - Clock, workspace-branch and workspace-root lookups, and diagnostics sink are required; see {@link BrokerOptions} for its optional fields.
      */
     constructor(path, options) {
         this.#db = (options.openDatabase ?? openBrokerDatabase)(path);
         this.#now = options.now;
         this.#workspaceBranch = options.workspaceBranch;
+        this.#workspaceRoot = options.workspaceRoot;
         this.#report = options.report;
         this.#visibilityTimeoutMs = options.visibilityTimeoutMs ?? PAGER_DEFAULTS.visibilityTimeoutMs;
         this.#redeliveryBaseDelayMs = options.redeliveryBaseDelayMs ?? PAGER_DEFAULTS.redeliveryBaseDelayMs;
@@ -196,34 +198,34 @@ export class Broker {
     }
     /**
      * Register a concrete agent under one workspace-unique session name.
-     * @param args - Caller-supplied identity, topology, and implementation values.
+     * @param args - Caller-supplied identity, topology, and implementation values. `workspacePath` is
+     * the directory the agent works in, which registers it in the workspace that directory belongs to.
      * @returns - Stable agent identity registered in the requested team.
      */
     registerAgent(args) {
-        const workspacePath = resolve(args.workspacePath);
         const identity = this.#registrationIdentity(args.agentId, args.sessionName, args.implementation);
-        // Validated before the port runs, so a rejected registration never pays for a git subprocess.
-        const branch = this.#currentWorkspaceBranch(workspacePath);
-        return this.#transaction(() => this.#registerAgent(args, identity, branch));
+        // Validated before the ports run, so a rejected registration never pays for a git subprocess.
+        const location = this.#locate(resolve(args.workspacePath));
+        return this.#transaction(() => this.#registerAgent(args, identity, location));
     }
     /**
      * Register or rejoin an implementation identity without a prior launch reservation.
      *
-     * A `sessionKey` makes the identity resumable: the same harness conversation returning after a
-     * restart resolves to the identity it already owns, keeping its alias, inbox, and traffic, whatever
-     * the caller passes as `sessionName`. Without one, rejoining still falls back to matching the alias.
+     * A `sessionKey` makes the identity resumable: the same harness conversation returning to the same
+     * working directory after a restart resolves to the identity it already owns, keeping its alias,
+     * inbox, and traffic, whatever the caller passes as `sessionName`. Without one, rejoining still
+     * falls back to matching the alias.
      *
      * A `continuesSessionKey` is the key a conversation was known by before it continued under
      * `sessionKey`. When `sessionKey` owns no identity yet, the identity the continued key owns moves
      * to `sessionKey`, its holder displaced, so the alias, inbox, and traffic follow the conversation.
-     * @param args - Validated workspace, implementation, optional alias, optional resumable key, and
-     * the key of the conversation that one continues, which requires the resumable key.
+     * @param args - Directory the agent works in, which registers it in the workspace that directory
+     * belongs to; implementation; optional alias; optional resumable key; and the key of the
+     * conversation that one continues, which requires the resumable key.
      * @returns - Stable agent identity, its current alias, and a fresh single-use attachment reservation.
      */
     registerAgentWithoutReservation(args) {
-        const workspacePath = resolve(args.workspacePath);
-        const workspaceId = workspaceIdentity(workspacePath);
-        const teamId = workspaceTeamId(workspacePath);
+        const workingDirectory = resolve(args.workspacePath);
         const ephemeral = args.sessionName === undefined;
         validateImplementationId(args.implementation.id);
         const sessionKey = args.sessionKey === undefined ? undefined : validateSessionKey(args.sessionKey);
@@ -231,32 +233,38 @@ export class Broker {
         if (continuesSessionKey !== undefined && sessionKey === undefined) {
             throw new ProtocolError("validation_failed", "A continued session key requires the conversation's own session key");
         }
-        // A cheap read, ahead of the branch lookup below and outside its transaction, so a session key
-        // that will resume an existing identity can skip that lookup entirely: the resumable path below
-        // never writes a workspace row, so a branch read for it would only pay for a discarded answer.
-        // Re-read inside the transaction, since this and the branch lookup can both race a row that
-        // starts or stops resolving between here and there; harmless either way, per #ensureWorkspaceAndTeam.
-        const resumableAhead = sessionKey
-            ? this.#agentForSessionKey(workspaceId, args.implementation.id, sessionKey)
+        const keys = { implementationId: args.implementation.id, sessionKey, continuesSessionKey };
+        // Read ahead of the workspace lookup, which a resume skips when it keeps the workspace it registered in.
+        // Re-read inside the transaction, where a registration that loses the race to resume takes the
+        // location this identity registered from.
+        const resumableAhead = this.#resumableIdentity(workingDirectory, keys);
+        const registered = resumableAhead && this.#registeredLocation(resumableAhead.agent.agentId);
+        const registeredAhead = resumableAhead && registered
+            ? { agentId: resumableAhead.agent.agentId, workspaceRoot: registered.workspaceRoot }
             : undefined;
-        // Read before the transaction opens: the port's real implementation is a subprocess, and holding
-        // SQLite's write lock across it stalls every other connection for as long as git takes.
-        const branch = resumableAhead ? null : this.#currentWorkspaceBranch(workspacePath);
+        const location = registered
+            ? {
+                ...registered,
+                workspaceRoot: this.#confirmedWorkspaceRoot(registered),
+                branch: this.#workspaceBranch(workingDirectory),
+            }
+            : this.#locate(workingDirectory);
+        const workspaceId = workspaceIdentity(location.workspaceRoot);
+        const teamId = workspaceTeamId(location.workspaceRoot);
         return this.#transaction(() => {
-            const owned = sessionKey ? this.#agentForSessionKey(workspaceId, args.implementation.id, sessionKey) : undefined;
-            const continued = sessionKey && !owned && continuesSessionKey
-                ? this.#agentForSessionKey(workspaceId, args.implementation.id, continuesSessionKey)
-                : undefined;
-            if (sessionKey && continued)
-                this.#bindSessionKey(continued.agentId, sessionKey, false);
-            const resumable = owned ?? continued;
+            const resumable = this.#resumableIdentity(workingDirectory, keys);
             if (resumable) {
-                this.#displaceHolder(resumable.agentId);
+                const { agent } = resumable;
+                if (sessionKey && resumable.byContinuedKey)
+                    this.#bindSessionKey(agent.agentId, sessionKey, false);
+                this.#displaceHolder(agent.agentId);
+                this.#recordBranch(agent.agentId, location.branch);
+                this.#followWorkspace(agent, this.#workspaceRootToFollow(agent.agentId, registeredAhead, location));
                 return {
-                    agentId: resumable.agentId,
-                    reservation: this.#reserveAttachment(resumable.agentId, "messaging"),
-                    sessionName: resumable.sessionName,
-                    ephemeral: resumable.ephemeral,
+                    agentId: agent.agentId,
+                    reservation: this.#reserveAttachment(agent.agentId, "messaging"),
+                    sessionName: agent.sessionName,
+                    ephemeral: agent.ephemeral,
                     resumed: true,
                 };
             }
@@ -265,13 +273,12 @@ export class Broker {
             // request over a name it will not be given would cost it that identity, its inbox and its traffic.
             const sessionName = validateRegistrationSessionName(args.sessionName ?? this.#nextImplementationAlias(workspaceId, args.implementation.id));
             const agentId = this.#registerAgentWithoutReservation({
-                workspacePath,
+                location,
                 workspaceId,
                 teamId,
                 sessionName,
                 ephemeral,
                 implementation: args.implementation,
-                branch,
             });
             if (sessionKey)
                 this.#bindSessionKey(agentId, sessionKey, true);
@@ -291,66 +298,272 @@ export class Broker {
      * @returns - Current identity and alias history after the replacement.
      */
     updateAgentAlias(agentId, requestedAlias) {
-        const sessionName = validateRegistrationSessionName(requestedAlias.replace(/^@/u, ""), "agent alias");
+        return this.relocateAgent(agentId, { alias: requestedAlias }).identity;
+    }
+    /**
+     * Move an agent to another workspace, rename it, or both, in one step.
+     *
+     * The alias must be free in the target workspace: held by nobody else and reserved as nobody
+     * else's retired name. Without `force` a taken alias fails with `alias_conflict` naming its holder
+     * and changes nothing. With `force` the caller takes the holder's identity over: its id, alias,
+     * inbox and alias history become the caller's, and the identity joins the target workspace, which
+     * is the caller's own when the request names none; the caller's own connections and
+     * conversation key move onto it, and the caller's previous identity is retired with its messages
+     * moved across and its aliases reserved as redirects to the claimed identity. The holder's own
+     * sessions and unconsumed attach reservations end, so a session or resume token it presents is
+     * refused as expired, and a claim token it held acknowledges nothing.
+     *
+     * A move keeps every alias the agent held reserved in the workspace it leaves, redirecting to its
+     * current address, and carries its alias history into the workspace it joins.
+     * @param agentId - Authenticated identity asking to move or rename.
+     * @param request - Target workspace, alias, and whether to take the alias over from its holder.
+     * @returns - The identity the caller now acts as, and the takeover when one was performed.
+     */
+    relocateAgent(agentId, request) {
+        const sessionName = request.alias === undefined
+            ? undefined
+            : validateRegistrationSessionName(request.alias.replace(/^@/u, ""), "agent alias");
+        const names = this.workspaceNames();
+        // Resolved before the write transaction opens: a directory lookup may block on a subprocess.
+        const requestedRoot = request.workspace === undefined ? undefined : this.#requestedWorkspaceRoot(request.workspace, names);
         return this.#transaction(() => {
             const agent = this.#activeAgent(agentId);
             this.#lifecycleSynchronization?.checkpoint("agent_alias_active");
-            const workspaceId = String(agent.workspace_id);
-            this.#assertNameAvailable(workspaceId, sessionName, agentId);
-            const currentAlias = normalizeAlias(String(agent.registration_name));
-            const nextAlias = normalizeAlias(sessionName);
-            if (currentAlias !== nextAlias) {
-                this.#write("insert or ignore into alias_history(workspace_id, alias, agent_id) values (?, ?, ?)", workspaceId, currentAlias, agentId);
-                this.#write("delete from alias_history where workspace_id = ? and alias = ? and agent_id = ?", workspaceId, nextAlias, agentId);
-            }
-            this.#write("update agents set registration_name = ?, registration_ephemeral = 0 where id = ?", sessionName, agentId);
+            const targetName = sessionName ?? String(agent.registration_name);
+            const workspaceRoot = requestedRoot ?? this.#workspacePath(String(agent.workspace_id));
+            const workspaceId = workspaceIdentity(workspaceRoot);
+            const holder = this.#aliasHolder(workspaceId, targetName, agentId);
+            if (holder && request.force !== true)
+                throw this.#aliasHeldError(targetName, holder, names);
+            const claim = holder ? this.#claimIdentity(agentId, holder.agentId, names) : null;
+            const actingId = claim ? claim.agentId : agentId;
+            this.#moveToWorkspace(actingId, workspaceRoot, targetName);
+            this.#renameAgent(actingId, workspaceId, targetName);
             this.#lifecycleSynchronization?.checkpoint("agent_alias_updated");
-            const previous = this.#db
-                .prepare("select alias from alias_history where workspace_id = ? and agent_id = ? order by id")
-                .all(workspaceId, agentId);
-            return {
-                id: agentId,
-                alias: normalizeAlias(sessionName),
-                previousAliases: previous.map((row) => String(row.alias)),
-            };
+            // A trigger on the rename can reap the agent within the transaction, so its row is not read back.
+            // Joining a workspace no agent had registered in can change the names of the others.
+            const namesNow = requestedRoot === undefined ? names : this.workspaceNames();
+            return { identity: this.#identity(actingId, workspaceId, targetName, namesNow), claim };
         });
     }
     /**
-     * Return the authenticated identity, current alias, and prior routable names.
+     * Resolve the workspace a relocation names to the path that identifies it.
+     *
+     * A name a listing reports wins over a directory of the same spelling; the two agree whenever
+     * both apply, since a name spanning a whole path is that path.
+     * @param requested - Workspace name, or absolute directory.
+     * @param names - Workspace names as {@link Broker.workspaceNames} reports them.
+     * @returns - Path of the named workspace, or the path naming the workspace the directory belongs to.
+     */
+    #requestedWorkspaceRoot(requested, names) {
+        const named = this.#workspacePathForName(requested, names);
+        if (named !== undefined)
+            return named;
+        if (isAbsolute(requested))
+            return this.#workspaceRootOf(resolve(requested));
+        throw new ProtocolError("validation_failed", `Unknown workspace ${requested}; name one a listing reports, or give an absolute directory`);
+    }
+    #workspacePathForName(requested, names) {
+        let name;
+        try {
+            name = parseWorkspaceName(requested);
+        }
+        catch {
+            return undefined;
+        }
+        for (const [workspaceId, workspaceName] of names) {
+            if (workspaceName === name)
+                return this.#workspacePath(workspaceId);
+        }
+        return undefined;
+    }
+    #workspacePath(workspaceId) {
+        const row = this.#db.prepare("select path from workspaces where id = ?").get(workspaceId);
+        if (row === undefined)
+            throw new Error(`Workspace ${workspaceId} is not recorded`);
+        return String(row.path);
+    }
+    /**
+     * Find who stands between an agent and an alias in a workspace.
+     * @param workspaceId - Workspace the alias would be held in.
+     * @param sessionName - Alias asked for, without its at-sign.
+     * @param owner - Agent asking, whose own registration and retired names are not in its way, or
+     * nothing for an agent not yet registered.
+     * @returns - The identity registered under the alias or holding it as a retired name, or nothing.
+     */
+    #aliasHolder(workspaceId, sessionName, owner) {
+        const registration = this.#db
+            .prepare("select id from agents where workspace_id = ? and registration_name = ? and state != 'reaped'")
+            .get(workspaceId, sessionName);
+        if (registration && registration.id !== owner) {
+            return { agentId: readStoredAgentId(registration.id, "agents.id"), retired: false };
+        }
+        const historical = this.#db
+            .prepare("select h.agent_id from alias_history h join agents a on a.id = h.agent_id where h.workspace_id = ? and h.alias = ? and a.state != 'reaped'")
+            .get(workspaceId, normalizeAlias(sessionName));
+        if (historical && historical.agent_id !== owner) {
+            return { agentId: readStoredAgentId(historical.agent_id, "alias_history.agent_id"), retired: true };
+        }
+        return undefined;
+    }
+    #aliasHeldError(sessionName, holder, names) {
+        const described = this.#describeAgent(holder.agentId, names);
+        return new ProtocolError("alias_conflict", holder.retired
+            ? `Agent alias ${normalizeAlias(sessionName)} is a retired name that stays reserved in this workspace for ${described}; pass force to claim it`
+            : `Agent alias ${normalizeAlias(sessionName)} is already in use in this workspace by ${described}; pass force to claim it`);
+    }
+    /**
+     * Name an identity as an error does: its address, then its implementation and id in parentheses.
+     * @param agentId - Identity to describe.
+     * @param names - Workspace names as {@link Broker.workspaceNames} reports them.
+     * @returns - `address (implementation, id)`, or `address (id)` when no implementation is recorded.
+     */
+    #describeAgent(agentId, names) {
+        const row = this.#db.prepare("select implementation_id from agents where id = ?").get(agentId);
+        const implementation = typeof row?.implementation_id === "string" ? `${row.implementation_id}, ` : "";
+        return `${this.#agentAddress(agentId, names)} (${implementation}${agentId})`;
+    }
+    /**
+     * Give an identity a new registration name in the workspace it is in, retiring the one it had.
+     *
+     * The retired name stays reserved as a redirect to this identity. A reservation this identity held
+     * on the new name is released, since the name is current again.
+     * @param agentId - Identity being renamed.
+     * @param workspaceId - Workspace the identity is in.
+     * @param sessionName - Name to register, already validated.
+     */
+    #renameAgent(agentId, workspaceId, sessionName) {
+        const row = this.#db.prepare("select registration_name from agents where id = ?").get(agentId);
+        const currentAlias = normalizeAlias(String(row?.registration_name));
+        const nextAlias = normalizeAlias(sessionName);
+        if (currentAlias !== nextAlias)
+            this.#reserveAlias(workspaceId, currentAlias, agentId);
+        this.#releaseOwnReservation(agentId, workspaceId, nextAlias);
+        this.#write("update agents set registration_name = ?, registration_ephemeral = 0 where id = ?", sessionName, agentId);
+    }
+    /**
+     * Drop the redirect an identity holds from an alias it now registers under, since the name is current again.
+     * @param agentId - Identity registered under the alias.
+     * @param workspaceId - Workspace the identity is in.
+     * @param alias - Alias with its at-sign.
+     */
+    #releaseOwnReservation(agentId, workspaceId, alias) {
+        this.#write("delete from alias_history where workspace_id = ? and alias = ? and agent_id = ?", workspaceId, alias, agentId);
+    }
+    /**
+     * Reserve a retired alias in a workspace as a redirect to an identity, unless another identity is
+     * registered under it there or already holds it as a retired name.
+     * @param workspaceId - Workspace the alias is reserved in.
+     * @param alias - Alias with its at-sign.
+     * @param agentId - Identity a send to the alias is redirected to.
+     */
+    #reserveAlias(workspaceId, alias, agentId) {
+        this.#write("insert or ignore into alias_history(workspace_id, alias, agent_id) select ?, ?, ? where not exists (select 1 from agents where workspace_id = ? and registration_name = ? and state != 'reaped' and id != ?)", workspaceId, alias, agentId, workspaceId, alias.slice(1), agentId);
+    }
+    /**
+     * Take over another identity for the caller's process.
+     *
+     * The claimed identity keeps its id, alias, inbox, history and workspace, and takes the caller's
+     * working directory, branch, implementation, parent and conversation key. The holder's sessions
+     * and unconsumed attach reservations end, and no identity is created for it.
+     * @param claimantId - Active identity giving itself up.
+     * @param holderId - Identity being taken over.
+     * @param names - Workspace names as {@link Broker.workspaceNames} reports them, as the addresses are read.
+     * @returns - What was taken and what was given up.
+     */
+    #claimIdentity(claimantId, holderId, names) {
+        const claimant = this.#activeAgent(claimantId);
+        const holder = this.#agent(holderId);
+        const address = this.#agentAddress(holderId, names);
+        const retiredAddress = this.#agentAddress(claimantId, names);
+        this.#endHolderSessions(holderId);
+        const claimantWorkspaceId = String(claimant.workspace_id);
+        const holderWorkspaceId = String(holder.workspace_id);
+        // The claimant's row is retired before the claimed one takes its conversation key: the key is
+        // unique among active identities of one directory and implementation.
+        this.#write("update agents set state = 'reaped', session_key = null, archived_at = null where id = ?", claimantId);
+        this.#write("update alias_history set agent_id = ? where agent_id = ?", holderId, claimantId);
+        this.#reserveAlias(claimantWorkspaceId, normalizeAlias(String(claimant.registration_name)), holderId);
+        if (claimantWorkspaceId !== holderWorkspaceId) {
+            this.#copyAliasHistory(holderId, claimantWorkspaceId, holderWorkspaceId);
+        }
+        this.#moveTraffic(claimantId, holderId);
+        this.#write("update sessions set agent_id = ? where agent_id = ?", holderId, claimantId);
+        this.#write("update reservations set agent_id = ? where agent_id = ?", holderId, claimantId);
+        this.#write("update agents set state = 'active', archived_at = null, registration_ephemeral = 0, working_directory = ?, branch = ?, parent_id = ?, implementation_id = ?, implementation_version = ?, session_key = ? where id = ?", String(claimant.working_directory), textOrNull(claimant.branch), textOrNull(claimant.parent_id), textOrNull(claimant.implementation_id), textOrNull(claimant.implementation_version), textOrNull(claimant.session_key), holderId);
+        return { address, agentId: holderId, retiredId: claimantId, retiredAddress };
+    }
+    /**
+     * End every session and unconsumed attach reservation of an identity being claimed, recording
+     * the claim as the cause on each session it ends, so every session or resume token its process
+     * presents is refused as expired.
+     * @param holderId - Identity being claimed.
+     */
+    #endHolderSessions(holderId) {
+        const cause = "claimed";
+        this.#write("update sessions set end_cause = ? where agent_id = ? and active = 1", cause, holderId);
+        this.#displaceHolder(holderId);
+    }
+    /**
+     * Move every message one identity sent or was sent, with the claims and send keys on them, to
+     * another, so the second can acknowledge, read status and repeat sends the first could.
+     * @param fromId - Identity giving its traffic up.
+     * @param toId - Identity receiving it.
+     */
+    #moveTraffic(fromId, toId) {
+        // A send key names one sender, recipient and key; the receiving identity's own record wins a tie.
+        this.#write("delete from idempotency where agent_id = ? and exists (select 1 from idempotency i where i.agent_id = ? and i.recipient_id = idempotency.recipient_id and i.key = idempotency.key)", fromId, toId);
+        this.#write("delete from idempotency where recipient_id = ? and exists (select 1 from idempotency i where i.recipient_id = ? and i.agent_id = idempotency.agent_id and i.key = idempotency.key)", fromId, toId);
+        this.#write("update idempotency set agent_id = ? where agent_id = ?", toId, fromId);
+        this.#write("update idempotency set recipient_id = ? where recipient_id = ?", toId, fromId);
+        this.#write("update messages set sender_id = ? where sender_id = ?", toId, fromId);
+        this.#write("update messages set recipient_id = ? where recipient_id = ?", toId, fromId);
+        this.#write("update claims set agent_id = ? where agent_id = ?", toId, fromId);
+        this.#write("delete from wakes where agent_id = ?", fromId);
+        this.#syncRedelivery(toId);
+    }
+    /**
+     * Return an agent's identity as reported to that agent.
      * @param agentId - Stable identity to inspect.
      * @returns - Identity details safe to return to the owning agent.
      */
     agentIdentity(agentId) {
         const agent = this.#agent(agentId);
+        return this.#identity(agentId, String(agent.workspace_id), String(agent.registration_name));
+    }
+    #identity(agentId, workspaceId, registrationName, names = this.workspaceNames()) {
         const previous = this.#db
             .prepare("select alias from alias_history where workspace_id = ? and agent_id = ? order by id")
-            .all(String(agent.workspace_id), agentId);
+            .all(workspaceId, agentId);
+        const alias = normalizeAlias(registrationName);
+        const workspace = names.get(workspaceId) ?? workspaceId;
         return {
             id: agentId,
-            alias: normalizeAlias(String(agent.registration_name)),
+            alias,
+            workspace,
+            address: formatAgentAddress(alias, workspace),
             previousAliases: previous.map((row) => String(row.alias)),
         };
     }
     /**
      * Reserve an identity and single-use attach reservation for a future process.
-     * @param args - Registration name, team, and workspace the reservation is created under.
+     * @param args - Registration name, team, and the directory the future process works in, which
+     * creates the reservation in the workspace that directory belongs to.
      * @returns - Reservation identity and one-time reservation for the future agent.
      */
     reserveAgent(args) {
-        const workspacePath = resolve(args.workspacePath);
         // A reservation is made for a process that has not started, so a caller with no name to give may
         // send an empty one and mean "derive it"; only a name with content is held to the alias rule.
         const requestedName = args.sessionName === undefined || args.sessionName === "" ? undefined : args.sessionName;
         const identity = this.#registrationIdentity(undefined, requestedName, args.implementation);
-        // Validated before the port runs, so a rejected reservation never pays for a git subprocess.
-        const branch = this.#currentWorkspaceBranch(workspacePath);
+        // Validated before the ports run, so a rejected reservation never pays for a git subprocess.
+        const location = this.#locate(resolve(args.workspacePath));
         return this.#transaction(() => {
             const agentId = this.#registerAgent({
                 teamId: args.teamId,
                 parentId: args.parentId,
-                workspacePath: args.workspacePath,
                 ...(args.implementation !== undefined ? { implementation: args.implementation } : {}),
-            }, identity, branch);
+            }, identity, location);
             return { agentId, reservation: this.#reserveAttachment(agentId, "messaging") };
         });
     }
@@ -429,14 +642,14 @@ export class Broker {
         const key = validateSessionKey(sessionKey);
         return this.#transaction(() => {
             const agent = this.#db
-                .prepare("select workspace_id, implementation_id from agents where id = ? and state = 'active'")
+                .prepare("select working_directory, implementation_id from agents where id = ? and state = 'active'")
                 .get(agentId);
             if (!agent)
                 throw new ProtocolError("conflict", "Only an active agent identity can claim a session key");
             if (typeof agent.implementation_id !== "string") {
                 throw new ProtocolError("validation_failed", "A session key requires a registered implementation");
             }
-            const owner = this.#agentForSessionKey(String(agent.workspace_id), agent.implementation_id, key);
+            const owner = this.#agentForSessionKey(String(agent.working_directory), agent.implementation_id, key);
             if (!owner || owner.agentId === agentId) {
                 this.#bindSessionKey(agentId, key, false);
                 return { agentId, adopted: false };
@@ -728,12 +941,15 @@ export class Broker {
      * Name why a known session no longer resolves.
      * @param row - The session row the caller presented, inactive or past its lease.
      * @returns - `ended` when the newest generation of the row's rotation lineage was deactivated by an
-     * operator archive or by a newer attachment of the same identity and channel, otherwise `expired`.
+     * operator archive or by a newer attachment of the same identity and channel, otherwise `expired`,
+     * which includes a lineage whose end cause is a claim of its identity.
      */
     #sessionEndedError(row) {
         const newest = this.#newestGeneration(row);
         if (Number(newest.active) === 1)
             return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+        if (newest.end_cause === "claimed")
+            return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
         const archived = this.#db.prepare("select archived_at from agents where id = ?").get(String(newest.agent_id));
         if (typeof archived?.archived_at === "number")
             return new ProtocolError("ended", "MCP session ended because an operator archived this agent");
@@ -1520,7 +1736,7 @@ export class Broker {
         return this.#readableAgentRows(agents).map(({ id, row }) => {
             const workspace = names.get(String(row.workspace_id)) ?? String(row.workspace_id);
             const alias = normalizeAlias(String(row.registration_name));
-            return { id, alias, workspace, address: `${alias}@${workspace}` };
+            return { id, alias, workspace, address: formatAgentAddress(alias, workspace) };
         });
     }
     /**
@@ -1547,18 +1763,17 @@ export class Broker {
             sessionName: validateRegistrationSessionName(requestedName ?? defaultAgentSessionName(agentId)),
         };
     }
-    #registerAgent(args, identity, branch) {
+    #registerAgent(args, identity, location) {
         const { agentId, sessionName } = identity;
         const registeredAt = this.#now();
-        const workspacePath = resolve(args.workspacePath);
-        const workspaceId = workspaceIdentity(workspacePath);
-        this.#ensureWorkspaceAndTeam(workspaceId, workspacePath, args.teamId, registeredAt, branch);
+        const workspaceId = workspaceIdentity(location.workspaceRoot);
+        this.#ensureWorkspaceAndTeam(workspaceId, location.workspaceRoot, args.teamId, registeredAt);
         const existing = this.#db.prepare("select state from agents where id = ?").get(agentId);
         if (existing && existing.state !== "active") {
             throw new ProtocolError("conflict", "Only an active agent identity can be reused");
         }
         this.#assertNameAvailable(workspaceId, sessionName, agentId);
-        this.#write("insert or ignore into agents(id, team_id, workspace_id, parent_id, state, created_at, implementation_id, implementation_version, registration_name, registration_ephemeral) values (?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)", agentId, args.teamId, workspaceId, args.parentId ?? null, registeredAt, args.implementation?.id ?? null, args.implementation?.version ?? null, sessionName, args.ephemeral ? 1 : 0);
+        this.#write("insert or ignore into agents(id, team_id, workspace_id, working_directory, branch, parent_id, state, created_at, implementation_id, implementation_version, registration_name, registration_ephemeral) values (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)", agentId, args.teamId, workspaceId, location.workingDirectory, location.branch, args.parentId ?? null, registeredAt, args.implementation?.id ?? null, args.implementation?.version ?? null, sessionName, args.ephemeral ? 1 : 0);
         return agentId;
     }
     /**
@@ -1578,39 +1793,186 @@ export class Broker {
         }
     }
     /**
-     * Read the branch checked out at a workspace path, for every registration that reaches it.
+     * Locate the directory a registering agent works in.
      *
-     * Read before the transaction opens, same as for a new workspace: the port's real implementation is
-     * a subprocess, and holding the write lock across it stalls every other connection. A resumed
-     * session never reaches this — `registerAgentWithoutReservation`'s resumable branch returns before
-     * any workspace write — so the hottest registration path still pays no I/O; only a genuinely new
-     * registration does, which is also the only moment a later `git checkout` on that workspace could
-     * otherwise go unseen forever.
-     * @param workspacePath - Absolute path the port inspects.
-     * @returns - Branch currently checked out at that path, or null when it is not a repository.
+     * Call it before the write transaction opens: both ports may block on a subprocess, and holding the
+     * write lock across them stalls every other connection.
+     * @param workingDirectory - Absolute directory the registering agent works in.
+     * @returns - That directory, the path of the workspace it belongs to, and the branch checked out
+     * there, or a null branch when it is not a repository.
      */
-    #currentWorkspaceBranch(workspacePath) {
-        return this.#workspaceBranch(workspacePath);
+    #locate(workingDirectory) {
+        return {
+            workingDirectory,
+            workspaceRoot: this.#workspaceRootOf(workingDirectory),
+            branch: this.#workspaceBranch(workingDirectory),
+        };
     }
     /**
-     * Record the workspace and team a registration lands in, and refresh a known workspace's branch.
+     * Ask the workspace-root port which directory names a working directory's workspace.
      *
-     * A `null` branch never overwrites one already stored: the caller's lookup collapses "not a
-     * repository" and "the git subprocess failed" into the same answer, and a transient failure must
-     * not blank out a branch a prior registration actually observed.
+     * A port that throws is reported, and the working directory stands in as its own workspace, so a
+     * registration is never refused over a lookup. A worktree registered this way shares its repository's
+     * workspace once a later registration or resume from it finds the repository.
+     * @param workingDirectory - Absolute directory the registering agent works in.
+     * @returns - The directory naming its workspace, resolved.
+     */
+    #workspaceRootOf(workingDirectory) {
+        try {
+            return resolve(this.#workspaceRoot(workingDirectory));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            this.#reportSafely(`Workspace lookup for ${workingDirectory} failed (${detail}); registering it as its own workspace`);
+            return workingDirectory;
+        }
+    }
+    /**
+     * Read the location an identity last registered from.
+     * @param agentId - Identity whose recorded location is read.
+     * @returns - Its working directory and its workspace's path, or nothing once its row is gone.
+     */
+    #registeredLocation(agentId) {
+        const row = this.#db
+            .prepare("select a.working_directory, w.path from agents a join workspaces w on w.id = a.workspace_id where a.id = ?")
+            .get(agentId);
+        if (!row)
+            return undefined;
+        return { workingDirectory: String(row.working_directory), workspaceRoot: String(row.path) };
+    }
+    /**
+     * Choose the workspace a resume inside the write transaction follows.
+     *
+     * The location settled before the transaction applies only to the identity, still in the workspace,
+     * that the lookup before the transaction saw. Any other identity, or one moved since, keeps the
+     * workspace it is registered in.
+     * @param agentId - Identity being resumed.
+     * @param registeredAhead - The identity the lookup before the transaction found and the location it
+     * was registered at then, or nothing when that lookup found none.
+     * @param location - Location settled before the transaction opened.
+     * @returns - Path of the workspace to follow.
+     */
+    #workspaceRootToFollow(agentId, registeredAhead, location) {
+        const registeredNow = this.#registeredLocation(agentId)?.workspaceRoot;
+        const unmovedSinceLookup = registeredAhead?.agentId === agentId && registeredAhead.workspaceRoot === registeredNow;
+        return unmovedSinceLookup || registeredNow === undefined ? location.workspaceRoot : registeredNow;
+    }
+    /**
+     * Settle the workspace a resuming identity belongs to.
+     *
+     * An identity whose workspace is its own working directory may be a stand-in from a lookup that
+     * failed when it registered, which looks exactly like a directory outside any repository or a
+     * repository's own root. The port is asked again for all three; only a different answer moves it.
+     * @param registered - Location the identity last registered from.
+     * @returns - The workspace path the identity belongs to now.
+     */
+    #confirmedWorkspaceRoot(registered) {
+        if (registered.workspaceRoot !== registered.workingDirectory)
+            return registered.workspaceRoot;
+        return this.#workspaceRootOf(registered.workingDirectory);
+    }
+    /**
+     * Move a resuming identity into the workspace its directory now resolves to, when it can take its
+     * alias there; otherwise it keeps the workspace it has and the conflict is reported.
+     * @param agent - Identity being resumed.
+     * @param workspaceRoot - Path of the workspace it belongs to now.
+     */
+    #followWorkspace(agent, workspaceRoot) {
+        try {
+            const workspaceId = workspaceIdentity(workspaceRoot);
+            const current = this.#db.prepare("select workspace_id from agents where id = ?").get(agent.agentId);
+            if (!current || String(current.workspace_id) === workspaceId)
+                return;
+            this.#assertNameAvailable(workspaceId, agent.sessionName, agent.agentId);
+            this.#moveToWorkspace(agent.agentId, workspaceRoot, agent.sessionName);
+        }
+        catch (error) {
+            if (!(error instanceof ProtocolError && error.code === "alias_conflict"))
+                throw error;
+            this.#reportSafely(`Workspace move of ${normalizeAlias(agent.sessionName)} (${agent.agentId}) to ${workspaceRoot} refused (${error.message}); it keeps its current workspace`);
+        }
+    }
+    /**
+     * Move an identity into another workspace under the alias it will hold there.
+     *
+     * Every alias it held in the workspace it leaves, its current one included, stays reserved there
+     * as a redirect to it, and its retired aliases, and the alias it held before the move when that
+     * differs from the one it takes, are reserved in the workspace it joins. A reservation the identity
+     * itself holds on the alias it takes is released. Messages it has already sent or received keep the
+     * workspace they were recorded under. The caller has settled that the alias is free in the target.
+     * @param agentId - Identity to move.
+     * @param workspaceRoot - Path naming the target workspace, created when no agent has registered in it yet.
+     * @param sessionName - Name the identity registers under in the target workspace, already validated.
+     */
+    #moveToWorkspace(agentId, workspaceRoot, sessionName) {
+        const workspaceId = workspaceIdentity(workspaceRoot);
+        const current = this.#db.prepare("select workspace_id, registration_name from agents where id = ?").get(agentId);
+        if (!current || String(current.workspace_id) === workspaceId)
+            return;
+        const previousWorkspaceId = String(current.workspace_id);
+        const previousAlias = normalizeAlias(String(current.registration_name));
+        const nextAlias = normalizeAlias(sessionName);
+        const teamId = workspaceTeamId(workspaceRoot);
+        this.#ensureWorkspaceAndTeam(workspaceId, workspaceRoot, teamId, this.#now());
+        // A single update, so the unique alias index sees only the final workspace and alias.
+        this.#write("update agents set workspace_id = ?, team_id = ?, registration_name = ? where id = ?", workspaceId, teamId, sessionName, agentId);
+        this.#copyAliasHistory(agentId, previousWorkspaceId, workspaceId);
+        this.#reserveAlias(previousWorkspaceId, previousAlias, agentId);
+        if (previousAlias !== nextAlias)
+            this.#reserveAlias(workspaceId, previousAlias, agentId);
+        this.#releaseOwnReservation(agentId, workspaceId, nextAlias);
+    }
+    /**
+     * Reserve, in one workspace, every retired alias an identity holds in another.
+     * @param agentId - Identity whose retired aliases are copied.
+     * @param fromWorkspaceId - Workspace the aliases are held in.
+     * @param toWorkspaceId - Workspace they are reserved in as well.
+     */
+    #copyAliasHistory(agentId, fromWorkspaceId, toWorkspaceId) {
+        const rows = this.#db
+            .prepare("select alias from alias_history where agent_id = ? and workspace_id = ? order by id")
+            .all(agentId, fromWorkspaceId);
+        for (const row of rows)
+            this.#reserveAlias(toWorkspaceId, String(row.alias), agentId);
+    }
+    /**
+     * Record the branch an identity's working directory has checked out.
+     *
+     * A `null` branch keeps the one already stored: the lookup collapses "not a repository" and "the git
+     * subprocess failed" into the same answer, and a transient failure must not blank out a branch an
+     * earlier registration actually observed.
+     * @param agentId - Identity whose branch is recorded.
+     * @param branch - Branch read before this transaction opened, or null when none was observed.
+     */
+    #recordBranch(agentId, branch) {
+        this.#write("update agents set branch = coalesce(?, branch) where id = ?", branch, agentId);
+    }
+    /**
+     * Record that a rejoined identity now works where its new holder does.
+     *
+     * The identity gives up its conversation key when the directory changes: the key names a
+     * conversation in the directory it was bound in, and the holder that displaced it brings its own.
+     * A `null` branch keeps the stored one only while the directory is unchanged.
+     * @param agentId - Identity being rejoined.
+     * @param location - Where the rejoining holder works, read before this transaction opened.
+     */
+    #rejoinFromLocation(agentId, location) {
+        this.#write("update agents set session_key = case when working_directory = ? then session_key end, branch = coalesce(?, case when working_directory = ? then branch end), working_directory = ? where id = ?", location.workingDirectory, location.branch, location.workingDirectory, location.workingDirectory, agentId);
+    }
+    /**
+     * Record the workspace and team a registration lands in.
      * @param workspaceId - Identity derived from the workspace path.
      * @param workspacePath - Absolute path the workspace identity was derived from.
      * @param teamId - Team the registering agent joins.
      * @param registeredAt - Broker-clock timestamp shared with the agent row this registration writes.
-     * @param branch - Branch checked out at that path, read before this transaction opened.
      */
-    #ensureWorkspaceAndTeam(workspaceId, workspacePath, teamId, registeredAt, branch) {
-        this.#write("insert into workspaces(id, path, branch, created_at) values (?, ?, ?, ?) on conflict(id) do update set branch = coalesce(excluded.branch, workspaces.branch)", workspaceId, workspacePath, branch, registeredAt);
+    #ensureWorkspaceAndTeam(workspaceId, workspacePath, teamId, registeredAt) {
+        this.#write("insert or ignore into workspaces(id, path, created_at) values (?, ?, ?)", workspaceId, workspacePath, registeredAt);
         this.#write("insert or ignore into teams(id, workspace_id, created_at) values (?, ?, ?)", teamId, workspaceId, registeredAt);
     }
     #registerAgentWithoutReservation(args) {
         const registeredAt = this.#now();
-        this.#ensureWorkspaceAndTeam(args.workspaceId, args.workspacePath, args.teamId, registeredAt, args.branch);
+        this.#ensureWorkspaceAndTeam(args.workspaceId, args.location.workspaceRoot, args.teamId, registeredAt);
         const existing = this.#db
             .prepare("select id, implementation_id from agents where workspace_id = ? and registration_name = ? and state = 'active'")
             .get(args.workspaceId, args.sessionName);
@@ -1622,11 +1984,12 @@ export class Broker {
             this.#assertNameAvailable(args.workspaceId, args.sessionName, agentId);
             this.#assertHolderDetached(agentId, args.sessionName);
             this.#displaceHolder(agentId);
+            this.#rejoinFromLocation(agentId, args.location);
             return agentId;
         }
         this.#assertNameAvailable(args.workspaceId, args.sessionName);
         const agentId = mintAgentId(issueOpaqueToken("agent"));
-        this.#write("insert into agents(id, team_id, workspace_id, parent_id, state, created_at, implementation_id, implementation_version, registration_name, registration_ephemeral) values (?, ?, ?, null, 'active', ?, ?, ?, ?, ?)", agentId, args.teamId, args.workspaceId, registeredAt, args.implementation.id, args.implementation.version ?? null, args.sessionName, args.ephemeral ? 1 : 0);
+        this.#write("insert into agents(id, team_id, workspace_id, working_directory, branch, parent_id, state, created_at, implementation_id, implementation_version, registration_name, registration_ephemeral) values (?, ?, ?, ?, ?, null, 'active', ?, ?, ?, ?, ?)", agentId, args.teamId, args.workspaceId, args.location.workingDirectory, args.location.branch, registeredAt, args.implementation.id, args.implementation.version ?? null, args.sessionName, args.ephemeral ? 1 : 0);
         return agentId;
     }
     /**
@@ -1644,15 +2007,32 @@ export class Broker {
             .get(holderId, this.#now());
         if (!live)
             return;
-        const holder = this.#db.prepare("select implementation_id from agents where id = ?").get(holderId);
-        const address = this.#agentAddress(holderId, this.workspaceNames());
-        const implementation = typeof holder?.implementation_id === "string" ? `${holder.implementation_id}, ` : "";
-        throw new ProtocolError("alias_conflict", `Session name ${sessionName} is held by ${address} (${implementation}${holderId}), whose attachment is live; choose another name, or end that session first`);
+        throw new ProtocolError("alias_conflict", `Session name ${sessionName} is held by ${this.#describeAgent(holderId, this.workspaceNames())}, whose attachment is live; choose another name, or end that session first`);
     }
-    #agentForSessionKey(workspaceId, implementationId, sessionKey) {
+    /**
+     * Find the identity a conversation registering from a directory resumes.
+     *
+     * The conversation's own key is looked up first. Only when it owns nothing is the key of the
+     * conversation it continues tried.
+     * @param workingDirectory - Absolute directory the conversation registers from.
+     * @param keys - Implementation and the conversation's keys; no key means nothing is resumable.
+     * @returns - The identity and whether the continued key, rather than the conversation's own, found it.
+     */
+    #resumableIdentity(workingDirectory, keys) {
+        if (keys.sessionKey === undefined)
+            return undefined;
+        const owned = this.#agentForSessionKey(workingDirectory, keys.implementationId, keys.sessionKey);
+        if (owned)
+            return { agent: owned, byContinuedKey: false };
+        if (keys.continuesSessionKey === undefined)
+            return undefined;
+        const continued = this.#agentForSessionKey(workingDirectory, keys.implementationId, keys.continuesSessionKey);
+        return continued && { agent: continued, byContinuedKey: true };
+    }
+    #agentForSessionKey(workingDirectory, implementationId, sessionKey) {
         const row = this.#db
-            .prepare("select id, registration_name, registration_ephemeral from agents where workspace_id = ? and implementation_id = ? and session_key = ? and state = 'active'")
-            .get(workspaceId, implementationId, sessionKey);
+            .prepare("select id, registration_name, registration_ephemeral from agents where working_directory = ? and implementation_id = ? and session_key = ? and state = 'active'")
+            .get(workingDirectory, implementationId, sessionKey);
         if (!row)
             return undefined;
         return {
@@ -1683,14 +2063,14 @@ export class Broker {
     }
     #resolveSessionKeyAtAttach(reserved, sessionKey) {
         const reservedAgent = this.#db
-            .prepare("select workspace_id, implementation_id, session_key from agents where id = ?")
+            .prepare("select working_directory, implementation_id, session_key from agents where id = ?")
             .get(reserved);
         if (!reservedAgent)
             throw new ProtocolError("unknown_recipient", "Agent identity is unknown");
         if (typeof reservedAgent.implementation_id !== "string") {
             throw new ProtocolError("validation_failed", "A session key requires a registered implementation");
         }
-        const owner = this.#agentForSessionKey(String(reservedAgent.workspace_id), reservedAgent.implementation_id, sessionKey);
+        const owner = this.#agentForSessionKey(String(reservedAgent.working_directory), reservedAgent.implementation_id, sessionKey);
         if (!owner || owner.agentId === reserved) {
             this.#bindSessionKey(reserved, sessionKey, true);
             return reserved;
@@ -1828,19 +2208,12 @@ export class Broker {
         return Boolean(row);
     }
     #assertNameAvailable(workspaceId, sessionName, owner) {
-        const alias = normalizeAlias(sessionName);
-        const registration = this.#db
-            .prepare("select id from agents where workspace_id = ? and registration_name = ? and state != 'reaped'")
-            .get(workspaceId, sessionName);
-        const historical = this.#db
-            .prepare("select agent_id from alias_history where workspace_id = ? and alias = ?")
-            .get(workspaceId, alias);
-        if (registration && registration.id !== owner) {
-            throw new ProtocolError("alias_conflict", "Agent alias is already in use in this workspace");
-        }
-        if (historical && historical.agent_id !== owner) {
-            throw new ProtocolError("alias_conflict", "Agent alias is a retired name that stays reserved in this workspace");
-        }
+        const holder = this.#aliasHolder(workspaceId, sessionName, owner);
+        if (!holder)
+            return;
+        throw new ProtocolError("alias_conflict", holder.retired
+            ? "Agent alias is a retired name that stays reserved in this workspace"
+            : "Agent alias is already in use in this workspace");
     }
     #pairSendCount(from, to) {
         const row = this.#db
@@ -2119,10 +2492,11 @@ export class Broker {
         if (current)
             return readStoredAgentId(current.id, "agents.id");
         const historical = this.#db
-            .prepare("select a.registration_name from alias_history h join agents a on a.id = h.agent_id where h.workspace_id = ? and h.alias = ? and a.state != 'reaped'")
+            .prepare("select a.id from alias_history h join agents a on a.id = h.agent_id where h.workspace_id = ? and h.alias = ? and a.state != 'reaped'")
             .get(targetWorkspace, normalizeAlias(address.sessionName));
-        if (typeof historical?.registration_name === "string") {
-            throw new ProtocolError("recipient_alias_changed", `Agent alias changed to ${normalizeAlias(historical.registration_name)}; try that alias instead`);
+        if (historical) {
+            const current = this.#agentAddress(readStoredAgentId(historical.id, "alias_history.agent_id"), this.workspaceNames());
+            throw new ProtocolError("recipient_alias_changed", `Agent alias changed to ${current}; try that address instead`);
         }
         throw new ProtocolError("unknown_recipient", "Unknown recipient");
     }
@@ -2142,7 +2516,7 @@ export class Broker {
         if (typeof alias !== "string" || alias === "")
             return agentId;
         const workspace = workspaces.get(String(row.workspace_id)) ?? String(row.workspace_id);
-        return `${normalizeAlias(alias)}@${workspace}`;
+        return formatAgentAddress(alias, workspace);
     }
     #workspaceForName(name, names) {
         for (const [workspaceId, workspaceName] of names) {
@@ -2273,6 +2647,14 @@ function mutatedTable(sql) {
         throw new Error(`Broker write statement names no table: ${sql}`);
     return match[1];
 }
+/**
+ * Read a nullable text column.
+ * @param value - Column value as the driver returned it.
+ * @returns - The text, or null for any other value.
+ */
+function textOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
 function contentType(body) {
     return typeof body === "string" ? "text" : "json";
 }