@haywoodmarx/agent-pager 0.1.0

package/dist/src/broker/broker.js

@@ -0,0 +1,2270 @@
+import { createHash } from "node:crypto";
+import { 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 { assertDurableOperatorId, readStoredAgentId, readStoredEnum, BrokerOperatorProjection, } from "./operator-projection.js";
+const notificationDisplay = {
+    delivered: { text: "notify delivered", tone: "ok" },
+    shed: { text: "notify shed — budget exceeded", tone: "warn" },
+    failed: { text: "notify failed", tone: "danger" },
+    deferred: { text: "notify deferred — agent busy", tone: "warn" },
+};
+/**
+ * Matches an identity that has attached at least once and has no live attachment, detached since
+ * before the second bound parameter; the first is the current time.
+ */
+const DETACHED_SINCE_SQL = "not exists (select 1 from sessions s where s.agent_id = a.id and s.active = 1 and s.expires_at > ?) and exists (select 1 from sessions s where s.agent_id = a.id) and (select max(s.expires_at) from sessions s where s.agent_id = a.id) <= ?";
+/**
+ * How long a detached, unnamed, resumable identity is retained before reaping. It outlives the
+ * attachment lease by orders of magnitude because a conversation is resumed by a person hours or
+ * days later, while the lease only measures whether a process is currently answering.
+ */
+const RESUMABLE_RETENTION_MS = 86_400_000;
+/** How long a named identity stays detached before the sweep archives it. */
+const NAMED_ARCHIVE_AFTER_MS = 86_400_000;
+/** How long an archived identity of any kind is kept, measured from its archival, before reaping. */
+const ARCHIVED_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+/**
+ * How long a detached, unnamed, resumable identity that has never sent or received a message is
+ * retained. Every directly started session registers one whether or not it will ever use a
+ * channel, so an identity with no traffic is not worth a day of the operator's attention; a
+ * conversation resumed after this window loses only an alias number it never used.
+ */
+const UNUSED_RESUMABLE_RETENTION_MS = 300_000;
+/**
+ * Bounds a message body when no configuration overrides it.
+ *
+ * Set well above `MESSAGE_BODY_LIMIT_BYTES`, which `encodeMessageBody` already enforces
+ * unconditionally: at this default, the check below only binds when a caller configures it tighter.
+ * A default below `MESSAGE_BODY_LIMIT_BYTES` would shed a body the protocol admits.
+ */
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+/**
+ * Retains a settled message for a week before the sweep deletes it and its dependent rows.
+ *
+ * This is what bounds the database, and so the cost of every operator projection: the broker holds
+ * one retention window of traffic and nothing older.
+ */
+const SETTLED_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
+/** Lifecycle text for a message dead-lettered because its stored recipient identity cannot be read. */
+const UNREADABLE_RECIPIENT_REASON = "dead-lettered — stored recipient identity is unreadable";
+/**
+ * Attempt at which the redelivery delay stops doubling.
+ *
+ * Expressed as a count rather than a duration so the ceiling stays a fixed multiple of whatever
+ * base delay is configured, and the shape of the schedule does not change when the base is tuned.
+ */
+const REDELIVERY_DOUBLING_LIMIT = 6;
+/** Answer to a session the broker holds no reason to describe further: unknown, lapsed, or not proven to be the caller's. */
+const SESSION_EXPIRED_MESSAGE = "MCP session expired; re-attach required";
+/**
+ * Selects, with one `now` parameter, an ephemeral identity that never attached and holds no
+ * reservation still able to: nothing is or will be answering for it.
+ */
+const UNATTACHED_EPHEMERAL_LAPSED_SQL = "a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 1 and not exists (select 1 from sessions s where s.agent_id = a.id) and not exists (select 1 from reservations r where r.agent_id = a.id and r.consumed_at is null and r.expires_at > ?)";
+/**
+ * Selects, with one `now` parameter, an identity `a` something may be answering for: a named
+ * identity, or an ephemeral one that is attached now or has never attached.
+ */
+const ANSWERABLE_AGENT_SQL = "(a.registration_ephemeral = 0 or not exists (select 1 from sessions s where s.agent_id = a.id) or exists (select 1 from sessions s where s.agent_id = a.id and s.active = 1 and s.expires_at > ?))";
+/**
+ * Selects a message that counts as use of identity `a`: one it sent, or one sent to it alone. A
+ * broadcast copy it received was addressed to its workspace, not to it.
+ */
+const MESSAGE_USING_AGENT_SQL = "select 1 from messages m where m.sender_id = a.id or (m.recipient_id = a.id and m.address_outcome != 'broadcast')";
+/** Precedes the workspace name in the address every copy of a broadcast carries. */
+const BROADCAST_ADDRESS_PREFIX = "*@";
+/**
+ * Precedes the target workspace and the caller's key in a broadcast's stored idempotency key, so a
+ * broadcast never matches a direct send that carried the same key.
+ */
+const BROADCAST_KEY_PREFIX = "broadcast:";
+/** Durable single-writer SQLite broker for Pager. */
+export class Broker {
+    #db;
+    #now;
+    #visibilityTimeoutMs;
+    #redeliveryBaseDelayMs;
+    #redeliveryGiveUpMs;
+    #reservationTtlMs;
+    #leaseTtlMs;
+    #resumableRetentionMs;
+    #namedArchiveAfterMs;
+    #archivedRetentionMs;
+    #unusedResumableRetentionMs;
+    #epoch;
+    #perPairRateLimit;
+    #perPairRateWindowMs;
+    #maxBodyBytes;
+    #maxInboxMessages;
+    #epochOwner;
+    #lifecycleSynchronization;
+    #workspaceBranch;
+    #report;
+    #projection;
+    #commitListeners = new Set();
+    #writeStatements = new Map();
+    #writtenTables;
+    #declaredRowChanges = 0;
+    /**
+     * 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.
+     */
+    constructor(path, options) {
+        this.#db = (options.openDatabase ?? openBrokerDatabase)(path);
+        this.#now = options.now;
+        this.#workspaceBranch = options.workspaceBranch;
+        this.#report = options.report;
+        this.#visibilityTimeoutMs = options.visibilityTimeoutMs ?? PAGER_DEFAULTS.visibilityTimeoutMs;
+        this.#redeliveryBaseDelayMs = options.redeliveryBaseDelayMs ?? PAGER_DEFAULTS.redeliveryBaseDelayMs;
+        this.#redeliveryGiveUpMs = options.redeliveryGiveUpMs ?? PAGER_DEFAULTS.redeliveryGiveUpMs;
+        this.#reservationTtlMs = options.reservationTtlMs ?? PAGER_DEFAULTS.reservationTtlMs;
+        this.#leaseTtlMs = options.leaseTtlMs ?? PAGER_DEFAULTS.leaseTtlMs;
+        this.#resumableRetentionMs = options.resumableRetentionMs ?? RESUMABLE_RETENTION_MS;
+        this.#namedArchiveAfterMs = options.namedArchiveAfterMs ?? NAMED_ARCHIVE_AFTER_MS;
+        this.#archivedRetentionMs = options.archivedRetentionMs ?? ARCHIVED_RETENTION_MS;
+        this.#unusedResumableRetentionMs = options.unusedResumableRetentionMs ?? UNUSED_RESUMABLE_RETENTION_MS;
+        this.#perPairRateLimit = options.perPairRateLimit ?? PAGER_DEFAULTS.perPairRateLimit;
+        this.#perPairRateWindowMs = options.perPairRateWindowMs ?? PAGER_DEFAULTS.perPairRateWindowMs;
+        this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        this.#maxInboxMessages = options.maxInboxMessages ?? PAGER_DEFAULTS.maxInboxMessages;
+        this.#epochOwner = options.epochOwner ?? true;
+        this.#lifecycleSynchronization = options.lifecycleSynchronization;
+        // A constructor that throws hands its caller nothing to close, so the connection is closed here.
+        try {
+            this.#epoch = new BrokerSchema(this.#db, {
+                now: this.#now,
+                epochOwner: this.#epochOwner,
+                report: (message) => this.#reportSafely(message),
+            }).prepare();
+            this.#projection = new BrokerOperatorProjection(this.#db, this.#now);
+        }
+        catch (error) {
+            this.#db.close();
+            throw error;
+        }
+    }
+    /** Close the broker database connection. */
+    close() {
+        this.#db.close();
+    }
+    /**
+     * Report the durability settings of the connection that owns broker writes.
+     *
+     * `synchronous` and `busy_timeout` are connection-local, so a second connection opened elsewhere
+     * cannot attest to them and must ask the running service instead.
+     * @returns - Journal mode, synchronous level, busy timeout, and foreign-key enforcement.
+     */
+    durability() {
+        return this.#db.durability();
+    }
+    /**
+     * Report broker generation and durability without projecting any traffic.
+     *
+     * Liveness callers poll this on a deadline, so it must not depend on how much history the
+     * database holds.
+     * @param generatedAt - Observation time to stamp, defaulting to now.
+     * @returns - Epoch, observation time, and live durability settings.
+     */
+    snapshotHealth(generatedAt = this.#now()) {
+        return {
+            brokerEpoch: publicEpoch(this.#epoch),
+            generatedAt,
+            durability: this.#db.durability(),
+        };
+    }
+    /**
+     * Return the current singleton epoch for local service ownership.
+     * @returns - Opaque generation identifier owned by this broker process.
+     */
+    epoch() {
+        return this.#epoch;
+    }
+    /**
+     * Observe successful broker commits after their SQLite transaction is durable.
+     * @param listener - Isolated observer that cannot change the committed caller outcome.
+     * @returns A callback that removes this observer.
+     */
+    subscribeCommits(listener) {
+        this.#commitListeners.add(listener);
+        return () => this.#commitListeners.delete(listener);
+    }
+    /**
+     * Register a concrete agent under one workspace-unique session name.
+     * @param args - Caller-supplied identity, topology, and implementation values.
+     * @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));
+    }
+    /**
+     * 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 `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.
+     * @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 ephemeral = args.sessionName === undefined;
+        validateImplementationId(args.implementation.id);
+        const sessionKey = args.sessionKey === undefined ? undefined : validateSessionKey(args.sessionKey);
+        const continuesSessionKey = args.continuesSessionKey === undefined ? undefined : validateSessionKey(args.continuesSessionKey);
+        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)
+            : 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);
+        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;
+            if (resumable) {
+                this.#displaceHolder(resumable.agentId);
+                return {
+                    agentId: resumable.agentId,
+                    reservation: this.#reserveAttachment(resumable.agentId, "messaging"),
+                    sessionName: resumable.sessionName,
+                    ephemeral: resumable.ephemeral,
+                    resumed: true,
+                };
+            }
+            // Validated here rather than beside the key and the implementation id, because a resume never
+            // reaches this line: a returning conversation keeps the alias it already owns, and refusing its
+            // 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,
+                workspaceId,
+                teamId,
+                sessionName,
+                ephemeral,
+                implementation: args.implementation,
+                branch,
+            });
+            if (sessionKey)
+                this.#bindSessionKey(agentId, sessionKey, true);
+            return {
+                agentId,
+                reservation: this.#reserveAttachment(agentId, "messaging"),
+                sessionName,
+                ephemeral,
+                resumed: false,
+            };
+        });
+    }
+    /**
+     * Replace an agent's routable alias and durable reconnection name.
+     * @param agentId - Authenticated identity whose name is changing.
+     * @param requestedAlias - Workspace-unique name, with an optional leading at-sign.
+     * @returns - Current identity and alias history after the replacement.
+     */
+    updateAgentAlias(agentId, requestedAlias) {
+        const sessionName = validateRegistrationSessionName(requestedAlias.replace(/^@/u, ""), "agent alias");
+        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);
+            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)),
+            };
+        });
+    }
+    /**
+     * Return the authenticated identity, current alias, and prior routable names.
+     * @param agentId - Stable identity to inspect.
+     * @returns - Identity details safe to return to the owning agent.
+     */
+    agentIdentity(agentId) {
+        const agent = this.#agent(agentId);
+        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);
+        return {
+            id: agentId,
+            alias: normalizeAlias(String(agent.registration_name)),
+            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.
+     * @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);
+        return this.#transaction(() => {
+            const agentId = this.#registerAgent({
+                teamId: args.teamId,
+                parentId: args.parentId,
+                workspacePath: args.workspacePath,
+                ...(args.implementation !== undefined ? { implementation: args.implementation } : {}),
+            }, identity, branch);
+            return { agentId, reservation: this.#reserveAttachment(agentId, "messaging") };
+        });
+    }
+    /**
+     * Issue an additional single-use attach reservation for an existing broker identity.
+     * @param agentId - Registered agent the new reservation attaches.
+     * @param channel - Attachment channel the reservation may occupy; a new session evicts only its own channel.
+     * @returns - One-time reservation that can attach the registered agent.
+     */
+    reserveAttachment(agentId, channel = "messaging") {
+        return this.#transaction(() => this.#reserveAttachment(agentId, channel));
+    }
+    /**
+     * Consume a single-use reservation and bind it to an agent identity plus fenced session.
+     *
+     * A launch reserves an identity before the harness has started, so it cannot know which conversation
+     * will occupy it. Presenting `sessionKey` here closes that gap: an unclaimed key is bound to the
+     * reserved identity, and a key already held by another identity attaches to its owner instead, so
+     * relaunching a harness against an existing conversation rejoins rather than forking a duplicate.
+     *
+     * A durable session name outlives the conversation that first claimed it. When a new conversation
+     * rejoins that name, it takes the identity over: the prior session is deactivated and loses its
+     * fencing token, rather than the attach being refused and the caller left with no channel at all.
+     * @param reservationId - One-time secret used to attach a reserved agent.
+     * @param options - Optional resumable session key presented by the attaching conversation.
+     * @returns - Attached identity, which is the key's owner when adoption occurred, plus its session.
+     */
+    attach(reservationId, options = {}) {
+        return this.#transaction(() => this.#attach(reservationId, options));
+    }
+    /**
+     * Runs the attach logic inside a caller-supplied transaction; see {@link attach}.
+     * @param reservationId - One-time secret used to attach a reserved agent.
+     * @param options - Optional session key under which the attaching identity should be resolved.
+     * @returns - Attached session identity and the epoch that issued it.
+     */
+    #attach(reservationId, options = {}) {
+        if (!this.#writtenTables)
+            throw new Error("Broker#attach must run inside #transaction");
+        const sessionKey = options.sessionKey === undefined ? undefined : validateSessionKey(options.sessionKey);
+        const reservation = this.#db.prepare("select * from reservations where reservation_id = ?").get(reservationId);
+        if (!reservation)
+            throw new ProtocolError("validation_failed", "Attach reservation is unknown");
+        if (typeof reservation.consumed_at === "number")
+            throw new ProtocolError("conflict", "Attach reservation is already consumed");
+        if (Number(reservation.expires_at) <= this.#now())
+            throw new ProtocolError("expired", "Attach reservation is expired");
+        // Hard-fail: a reservation naming an unreadable agent cannot attach anything, and this answers one caller.
+        const reserved = readStoredAgentId(reservation.agent_id, "reservations.agent_id");
+        const agentId = sessionKey ? this.#resolveSessionKeyAtAttach(reserved, sessionKey) : reserved;
+        this.#activeAgent(agentId);
+        const channel = readStoredEnum(reservation.channel, ATTACHMENT_CHANNELS, "reservations.channel");
+        const sessionId = issueOpaqueToken("session");
+        const fencingToken = issueOpaqueToken("session");
+        this.#write("update reservations set consumed_at = ? where reservation_id = ?", this.#now(), reservationId);
+        this.#write("update sessions set active = 0 where agent_id = ? and channel = ?", agentId, channel);
+        // Attaching is how an archived identity comes back: the operator put it away, and the
+        // conversation returning under the same key or name takes it out again.
+        this.#write("update agents set archived_at = null where id = ? and archived_at is not null", agentId);
+        this.#write("insert into sessions(id, agent_id, channel, fencing_token, expires_at, active, created_at, epoch) values (?, ?, ?, ?, ?, 1, ?, ?)", sessionId, agentId, channel, fencingToken, this.#now() + this.#leaseTtlMs, this.#now(), this.#epoch);
+        return { agentId, sessionId, fencingToken, epoch: this.#epoch };
+    }
+    /**
+     * Claim a conversation key for an already attached identity, or move to the identity that holds it.
+     *
+     * A harness whose channels are attached by the editor rather than by us cannot present its key at
+     * attach time, so it says who it is once it is connected. When the key belongs to another identity,
+     * that identity is the real one: this one is a launch artefact, and it is removed along with its
+     * connections after its outstanding reservations move across. An identity that has already sent or
+     * received a message is never removed: the call throws `conflict` and nothing is bound.
+     * @param agentId - Authenticated identity making the claim.
+     * @param sessionKey - Resumable key identifying the caller's conversation.
+     * @returns - Resolved identity, and fresh attachments for both channels when it moved.
+     */
+    adoptSessionKey(agentId, sessionKey) {
+        const key = validateSessionKey(sessionKey);
+        return this.#transaction(() => {
+            const agent = this.#db
+                .prepare("select workspace_id, 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);
+            if (!owner || owner.agentId === agentId) {
+                this.#bindSessionKey(agentId, key, false);
+                return { agentId, adopted: false };
+            }
+            this.#displaceHolder(owner.agentId);
+            this.#discardUnusedIdentity(agentId, owner.agentId, { allowConnections: true });
+            return {
+                agentId: owner.agentId,
+                adopted: true,
+                reservation: this.#reserveAttachment(owner.agentId, "messaging"),
+                deliveryReservation: this.#reserveAttachment(owner.agentId, "delivery"),
+            };
+        });
+    }
+    /**
+     * Renew an active attachment when its complete broker-issued identity is presented.
+     * @param sessionId - Attached session identity being renewed.
+     * @param fencingToken - Token proving ownership of the active attachment generation.
+     * @param epoch - Broker generation that issued the attachment.
+     * @returns - Agent identity whose durable attachment lease was renewed.
+     */
+    renewAttachment(sessionId, fencingToken, epoch) {
+        return this.#transaction(() => {
+            const row = this.#activeAttachment(sessionId, fencingToken, epoch);
+            this.#lifecycleSynchronization?.checkpoint("attachment_renewal_active");
+            this.#write("update sessions set expires_at = ? where id = ?", this.#now() + this.#leaseTtlMs, sessionId);
+            return readStoredAgentId(row.agent_id, "sessions.agent_id");
+        });
+    }
+    /**
+     * Close one active attachment by its own session identity, leaving any other session of the same
+     * agent untouched.
+     *
+     * No production path calls this: a harness ends every attachment of its identity together, through
+     * `releaseAttachments` or a lapsed lease. It stays as the one way a test can end a single session
+     * of a multi-session agent without ending the others, which neither of those offers.
+     * @param sessionId - Attached session identity being closed.
+     * @param fencingToken - Token proving ownership of the active attachment generation.
+     * @param epoch - Broker generation that issued the attachment.
+     * @internal
+     */
+    closeAttachment(sessionId, fencingToken, epoch) {
+        this.#transaction(() => {
+            this.#activeAttachment(sessionId, fencingToken, epoch);
+            this.#lifecycleSynchronization?.checkpoint("attachment_close_active");
+            this.#write("update sessions set active = 0 where id = ?", sessionId);
+        });
+    }
+    /**
+     * End every active attachment of an agent whose harness is shutting down, leaving the identity in place.
+     *
+     * The caller must have authenticated as this agent over one of those attachments. This is the graceful
+     * shutdown path for a harness whose messaging attachment is held by a client the connector cannot
+     * reach into, so an attachment the connector never opened still ends before its lease lapses.
+     * @param agentId - Identity whose harness is shutting down.
+     */
+    releaseAttachments(agentId) {
+        this.#transaction(() => {
+            this.#agent(agentId);
+            this.#displaceHolder(agentId);
+        });
+    }
+    /**
+     * Persist terminal disposition and detach every active connection for an agent.
+     * @param agentId - Stable identity whose process reached terminal disposition.
+     */
+    markAgentTerminal(agentId) {
+        this.#transaction(() => {
+            this.#agent(agentId);
+            this.#lifecycleSynchronization?.checkpoint("agent_terminal_present");
+            this.#write("update agents set state = 'terminal' where id = ?", agentId);
+            this.#write("update sessions set active = 0 where agent_id = ?", agentId);
+        });
+    }
+    /** Enqueue terminal outcomes for parents and persist the completed disposition. */
+    reapTerminalAgents() {
+        const terminal = this.#db
+            .prepare("select rowid, id, parent_id from agents where state = 'terminal' order by id")
+            .all();
+        for (const row of terminal) {
+            // Settle-and-name: a terminal row makes `nextSweepDelayMs` answer zero, so a skip alone would
+            // spin. The parent notification and the session close do not run; both need the unreadable id.
+            const agentId = this.#readableAgentId(row.id, "agents.id", String(row.rowid));
+            if (agentId === null) {
+                this.#transaction(() => {
+                    this.#write("update agents set state = 'reaped' where rowid = ?", Number(row.rowid));
+                });
+                continue;
+            }
+            if (typeof row.parent_id === "string")
+                this.#notifyParent(agentId, row.parent_id, "terminal", `agent-terminal:${agentId}`);
+            this.#transaction(() => {
+                const current = this.#db.prepare("select id from agents where id = ? and state = 'terminal'").get(agentId);
+                if (!current)
+                    return;
+                this.#lifecycleSynchronization?.checkpoint("terminal_reap_selected");
+                this.#reapAgent(agentId);
+            });
+        }
+        this.#reapExpiredEphemeralAgents();
+        this.#pruneSettledMessages();
+    }
+    /**
+     * Report how long until a sweep could next find work.
+     *
+     * A sweep scheduled from this value does nothing on an idle broker. Zero means work is already due.
+     * @returns - Delay in milliseconds, or null when nothing is pending.
+     */
+    nextSweepDelayMs() {
+        const now = this.#now();
+        const terminal = this.#db.prepare("select 1 as pending from agents where state = 'terminal' limit 1").get();
+        if (terminal)
+            return 0;
+        const deadlines = [
+            this.#earliestDeadline(
+            // Mirrors #reapExpiredEphemeralAgents: only a live session defers the sweep, so an agent
+            // whose attachment was closed while its lease still ran is due now, not at that lease.
+            // An archived identity is left out of both agent deadlines and due when its retention window ends.
+            "select min(deadline) as deadline from (select coalesce(max(case when s.active = 1 then s.expires_at end), 0) as deadline from agents a join sessions s on s.agent_id = a.id where a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 1 and a.session_key is null group by a.id)"),
+            this.#earliestDeadline(
+            // Mirrors the never-attached reap: due when the last unconsumed reservation lapses, or now
+            // when none is left.
+            "select min(deadline) as deadline from (select coalesce(max(case when r.consumed_at is null then r.expires_at end), 0) as deadline from agents a left join reservations r on r.agent_id = a.id where a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 1 and not exists (select 1 from sessions s where s.agent_id = a.id) group by a.id)"),
+            this.#earliestDeadline("select min(deadline) as deadline from (select max(s.expires_at) + ? as deadline from agents a join sessions s on s.agent_id = a.id where a.state = 'active' and a.archived_at is null and a.session_key is not null and a.registration_ephemeral = 1 group by a.id)", this.#resumableRetentionMs),
+            this.#earliestDeadline(`select min(deadline) as deadline from (select max(s.expires_at) + ? as deadline from agents a join sessions s on s.agent_id = a.id where a.state = 'active' and a.archived_at is null and a.session_key is not null and a.registration_ephemeral = 1 and not exists (${MESSAGE_USING_AGENT_SQL}) group by a.id)`, this.#unusedResumableRetentionMs),
+            this.#earliestDeadline("select min(deadline) as deadline from (select max(s.expires_at) + ? as deadline from agents a join sessions s on s.agent_id = a.id where a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 0 group by a.id)", this.#namedArchiveAfterMs),
+            this.#earliestDeadline("select min(archived_at) + ? as deadline from agents where state = 'active' and archived_at is not null", this.#archivedRetentionMs),
+            this.#earliestDeadline("select min(created_at) + ? as deadline from messages where state in ('acknowledged', 'expired', 'dead_lettered', 'failed')", SETTLED_MESSAGE_RETENTION_MS),
+            this.#earliestDeadline("select min(next_wake_at) as deadline from wakes"),
+            this.#earliestDeadline("select min(claim_expires_at) as deadline from messages where state = 'claimed'"),
+        ].filter((deadline) => deadline !== null);
+        if (deadlines.length === 0)
+            return null;
+        return Math.max(0, Math.min(...deadlines) - now);
+    }
+    #earliestDeadline(sql, ...parameters) {
+        const row = this.#db.prepare(sql).get(...parameters);
+        return typeof row?.deadline === "number" ? row.deadline : null;
+    }
+    /**
+     * Tell a parent what became of its child, without letting an unreachable parent stop the sweep.
+     *
+     * The notification is sent from the child and so must precede any reap, which leaves it unable to
+     * send. A parent that has itself been reaped or detached is unroutable, and an escaping throw
+     * would leave the child terminal forever, which a deadline-scheduled sweep retries without ever
+     * draining.
+     *
+     * The two outcomes scope their idempotency differently because they recur differently. An identity
+     * reaches `terminal` once and stays there, so its key is the child alone and a terminal row still
+     * present on a later tick is suppressed — until the notification itself passes the retention window
+     * and `#pruneSettledMessages` deletes the idempotency row naming it, after which the same key sends
+     * again. An inbox can be dead-lettered more than once, because {@link reapExpiredReservations} is
+     * called from outside the sweep, and a child can hold a reservation on each attachment channel; so
+     * that key names the reap it belongs to, collapsing the several rows one reap finds while leaving a
+     * later one free to report itself. Each reap is identified by a token minted per call, so two reaps
+     * within one millisecond stay two outcomes.
+     * @param agentId - Child identity the outcome happened to.
+     * @param parentId - Parent to notify.
+     * @param outcome - Which outcome to report, selecting the subject and type.
+     * @param idempotencyKey - Scope over which repeats of this outcome collapse into one notification.
+     */
+    #notifyParent(agentId, parentId, outcome, idempotencyKey) {
+        const notification = outcome === "terminal"
+            ? { subject: "Agent session ended", type: "terminal", log: `${agentId} ended` }
+            : { subject: "Agent inbox dead-lettered", type: "dead", log: `${agentId}'s inbox was dead-lettered` };
+        try {
+            this.send({
+                from: agentId,
+                to: parentId,
+                subject: notification.subject,
+                type: notification.type,
+                body: { agentId },
+                idempotencyKey,
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error ? error.message : String(error);
+            this.#reportSafely(`pager: ${notification.log} and its parent ${parentId} could not be told (${cause})`);
+        }
+    }
+    /**
+     * Remove settled messages past the retention window along with every row that depends on them.
+     *
+     * An idempotency record is deleted with its message: a key outliving the message it names would
+     * answer a retry with an identifier that no longer resolves.
+     */
+    #pruneSettledMessages() {
+        this.#transaction(() => {
+            const cutoff = this.#now() - SETTLED_MESSAGE_RETENTION_MS;
+            const settled = this.#db
+                .prepare("select id from messages where state in ('acknowledged', 'expired', 'dead_lettered', 'failed') and created_at <= ?")
+                .all(cutoff);
+            for (const row of settled) {
+                const messageId = String(row.id);
+                this.#write("delete from message_events where message_id = ?", messageId);
+                this.#write("delete from claims where message_id = ?", messageId);
+                this.#write("delete from idempotency where message_id = ?", messageId);
+                this.#write("delete from messages where id = ?", messageId);
+            }
+        });
+    }
+    /**
+     * Resume an MCP attachment while rotating a lapsed or prior-epoch session generation.
+     * @param request - Session, fencing proof, and last-seen generation the caller resumes with.
+     * @returns - Current attachment credentials and the stable owning agent identity.
+     */
+    resumeSession({ sessionId, fencingToken, epoch }) {
+        return this.#transaction(() => {
+            const row = this.#db.prepare("select * from sessions where id = ?").get(sessionId);
+            if (!row)
+                throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+            if (Number(row.active) === 0) {
+                // A losing racer's fencing token still proves the same attachment as whichever caller won the
+                // rotation below, so it is walked forward instead of refused. Bounded to one lease past when
+                // THIS row was rotated away, not past its own lease: elapsed wall time since last renewal
+                // includes any broker downtime, which the caller had no opportunity to renew through, and
+                // downtime longer than one lease is the ordinary case a restart produces. The rotation event is
+                // what a race is relative to, so it is the only clock this bound may read.
+                if (!fencingToken || fencingToken !== String(row.fencing_token))
+                    throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+                if (row.superseded_at === null || Number(row.superseded_at) + this.#leaseTtlMs <= this.#now())
+                    throw this.#sessionEndedError(row);
+                const live = this.#liveSuccessor(row);
+                return this.#rotateOrRenew(live, String(live.epoch) !== this.#epoch, true);
+            }
+            return this.#rotateOrRenew(row, (epoch !== undefined && epoch !== this.#epoch) || String(row.epoch) !== this.#epoch, fencingToken !== undefined && fencingToken === String(row.fencing_token));
+        });
+    }
+    /**
+     * Renew a live row's lease, or rotate it to a fresh generation, by the same trigger the direct and
+     * walked-forward resume paths both apply: an already-lapsed lease, or a stale epoch. Ownership is
+     * checked once, ahead of that choice, so neither branch can return a fencing token — the row's
+     * existing one or a freshly minted one — to a caller who has not proven it holds the current one.
+     * @param row - Live session row to renew or rotate.
+     * @param epochStale - Whether the epoch this row is pinned to is behind the broker's current one.
+     * @param ownershipProven - Whether the caller has already been shown to hold the fencing token for
+     * this exact row (directly) or for a superseded ancestor of it (walked forward).
+     * @returns - Current attachment credentials for the row or its replacement.
+     */
+    #rotateOrRenew(row, epochStale, ownershipProven) {
+        if (!ownershipProven)
+            throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+        // Only a sweep archive reaches here archived: an operator archive ends every attachment.
+        this.#write("update agents set archived_at = null where id = ? and archived_at is not null", String(row.agent_id));
+        const rotate = Number(row.expires_at) <= this.#now() || epochStale;
+        if (!rotate) {
+            this.#write("update sessions set expires_at = ? where id = ?", this.#now() + this.#leaseTtlMs, String(row.id));
+            return {
+                agentId: readStoredAgentId(row.agent_id, "sessions.agent_id"),
+                sessionId: String(row.id),
+                fencingToken: String(row.fencing_token),
+                epoch: this.#epoch,
+            };
+        }
+        const replacementSessionId = issueOpaqueToken("session");
+        const replacementFencingToken = issueOpaqueToken("session");
+        this.#write("update sessions set active = 0, superseded_by = ?, superseded_at = ? where id = ?", replacementSessionId, this.#now(), String(row.id));
+        this.#write("insert into sessions(id, agent_id, channel, fencing_token, expires_at, active, created_at, epoch) values (?, ?, ?, ?, ?, 1, ?, ?)", replacementSessionId, String(row.agent_id), String(row.channel), replacementFencingToken, this.#now() + this.#leaseTtlMs, this.#now(), this.#epoch);
+        return {
+            agentId: readStoredAgentId(row.agent_id, "sessions.agent_id"),
+            sessionId: replacementSessionId,
+            fencingToken: replacementFencingToken,
+            epoch: this.#epoch,
+        };
+    }
+    /**
+     * Follow a superseded session's rotation lineage to the generation currently active for it.
+     * @param row - Superseded row whose fencing token the caller already proved ownership of.
+     * @returns - The lineage's active row.
+     */
+    #liveSuccessor(row) {
+        let current = row;
+        const visited = new Set([String(current.id)]);
+        while (Number(current.active) === 0) {
+            const nextId = current.superseded_by;
+            if (typeof nextId !== "string" || nextId === "" || visited.has(nextId))
+                throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+            const next = this.#db.prepare("select * from sessions where id = ?").get(nextId);
+            if (!next)
+                throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+            visited.add(nextId);
+            current = next;
+        }
+        return current;
+    }
+    /**
+     * Name why a known session no longer resolves, so its holder is not told it merely expired.
+     *
+     * An archive and a newer attachment both deactivate a session while its lease still has time
+     * left; reporting either as an expiry sends the holder looking for a timing problem. A session
+     * rotated to a new generation of the same attachment carries `superseded_by` and is not a
+     * replacement by another holder.
+     * @param row - The session row the caller presented, inactive or past its lease.
+     * @returns - The error to raise: the archive or the replacement when that ended it, otherwise an expiry.
+     */
+    #sessionEndedError(row) {
+        const archived = this.#db.prepare("select archived_at from agents where id = ?").get(String(row.agent_id));
+        if (typeof archived?.archived_at === "number")
+            return new ProtocolError("expired", "MCP session ended because an operator archived this agent; re-attach required");
+        const replaced = this.#db
+            .prepare("select 1 as present from sessions where agent_id = ? and channel = ? and rowid > (select rowid from sessions where id = ?) limit 1")
+            .get(String(row.agent_id), String(row.channel), String(row.id));
+        if (Number(row.active) === 0 && row.superseded_by === null && replaced)
+            return new ProtocolError("expired", "MCP session ended because a newer attachment replaced it; re-attach required");
+        return new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+    }
+    /**
+     * Return the configured lifetime of an authenticated MCP attachment.
+     * @returns - Milliseconds from successful authentication until renewal is required.
+     */
+    sessionLeaseTtlMs() {
+        return this.#leaseTtlMs;
+    }
+    /**
+     * Resolve a live session ID to an agent identity, expiring sessions on timeout or restart epoch mismatch.
+     *
+     * Resolving renews the session lease. The lease reaps sessions whose process is gone, and a caller
+     * presenting the session is evidence its process is not; an attach reservation is single-use, so a
+     * session allowed to lapse under continuous use could never be re-established.
+     * @param sessionId - Session id presented by the attached process.
+     * @param epoch - Broker generation used to fence stale sessions, when the client protocol carries one.
+     * @returns - Agent identity owned by the current fenced session.
+     */
+    resolveSession(sessionId, epoch) {
+        if (epoch !== undefined && epoch !== this.#epoch)
+            throw new ProtocolError("expired", "Broker epoch changed; re-attach required");
+        return this.#transaction(() => {
+            const row = this.#db.prepare("select * from sessions where id = ?").get(sessionId);
+            if (!row)
+                throw new ProtocolError("expired", SESSION_EXPIRED_MESSAGE);
+            if (Number(row.active) !== 1 || Number(row.expires_at) <= this.#now())
+                throw this.#sessionEndedError(row);
+            // The row's own recorded epoch fences it even when the caller sends none: a client that never
+            // learned this custom header cannot otherwise be told a restart happened, and would resolve a
+            // pre-restart session indefinitely.
+            if (String(row.epoch) !== this.#epoch)
+                throw new ProtocolError("expired", "Broker epoch changed; re-attach required");
+            this.#lifecycleSynchronization?.checkpoint("session_resolution_active");
+            this.#write("update sessions set expires_at = ? where id = ?", this.#now() + this.#leaseTtlMs, sessionId);
+            return readStoredAgentId(row.agent_id, "sessions.agent_id");
+        });
+    }
+    /**
+     * Send a message from an agent to a concrete recipient or alias address.
+     * `from` is taken as given: the broker looks the agent up and does not authenticate the caller, so
+     * the caller must have authenticated the identity itself and never pass one read from request
+     * content. An alias resolves to a concrete recipient here, at send time, and a
+     * queued message keeps that recipient rather than following a later rebinding. Only an explicit
+     * send creates a message; assistant output is never forwarded automatically.
+     * @param args - Sender identity, address, subject, type, and body of the message to send.
+     * @returns - Durable message identity, the resolved recipient, and whether that recipient is archived.
+     */
+    send(args) {
+        const sender = this.#messageSender(args.from);
+        const key = args.idempotencyKey ?? issueOpaqueToken("idem");
+        const content = this.#messageContent(args);
+        return this.#transaction(() => {
+            const to = this.#resolveRecipientIdentity(sender.workspaceId, args.to);
+            const repeated = this.#repeatedMessage(sender.id, to, key);
+            if (repeated)
+                return { ...repeated, recipientArchived: this.#isArchived(repeated.to) };
+            // Asserted only once the send is known not to be a replay. A retry carrying a key the broker
+            // already answered must return that answer, including after the recipient detached; the key
+            // exists for exactly that window.
+            this.#assertRoutableRecipient(to);
+            const refusal = this.#limitRefusal(sender.id, to);
+            if (refusal)
+                throw new ProtocolError("conflict", refusal);
+            const messageId = this.#queue(sender, to, key, content, {
+                addressedTo: args.to,
+                outcome: isDirectAgentAddress(args.to) ? "direct" : "resolved",
+            });
+            return { messageId, to, recipientArchived: this.#isArchived(to) };
+        });
+    }
+    /**
+     * Send one message from an agent to the other agents in a workspace.
+     *
+     * `from` is taken as given, as for {@link Broker.send}. The recipients are the workspace's active,
+     * unarchived agents other than the sender that are named, attached now, or still able to attach
+     * for the first time; an agent that joins later receives nothing. Each recipient gets its own
+     * message. A recipient refused by its pair rate or inbox limit is reported and the others still
+     * receive. A repeat carrying an earlier broadcast's key to the same workspace returns the message
+     * that broadcast queued for each recipient it reached, whatever has become of that recipient
+     * since, and sends to every other recipient. A key a direct send carried names a different send.
+     * @param args - Sender identity, subject, type, and body of the message, and the name of the
+     * workspace to broadcast to, the sender's own when absent.
+     * @returns - The broadcast address, the message sent to each recipient, and each recipient refused.
+     */
+    broadcast(args) {
+        const sender = this.#messageSender(args.from);
+        const requestedKey = args.idempotencyKey ?? issueOpaqueToken("idem");
+        const content = this.#messageContent(args);
+        const requestedWorkspace = args.workspace === undefined ? undefined : parseWorkspaceName(args.workspace);
+        return this.#transaction(() => {
+            const names = this.workspaceNames();
+            const target = requestedWorkspace === undefined
+                ? { id: sender.workspaceId, name: names.get(sender.workspaceId) }
+                : { id: this.#workspaceForName(requestedWorkspace, names), name: requestedWorkspace };
+            if (target.name === undefined)
+                throw new Error("The sender's workspace has no registered path");
+            const address = `${BROADCAST_ADDRESS_PREFIX}${target.name}`;
+            const key = `${BROADCAST_KEY_PREFIX}${target.id}:${requestedKey}`;
+            const result = { address, sent: [], refused: [] };
+            for (const to of this.#broadcastRecipients(target.id, sender.id, key)) {
+                const repeated = this.#repeatedMessage(sender.id, to, key);
+                const refusal = repeated ? undefined : this.#limitRefusal(sender.id, to);
+                if (refusal)
+                    result.refused.push({ to, code: "conflict", message: refusal });
+                else
+                    result.sent.push(repeated ?? {
+                        messageId: this.#queue(sender, to, key, content, { addressedTo: address, outcome: "broadcast" }),
+                        to,
+                    });
+            }
+            return result;
+        });
+    }
+    #messageSender(agentId) {
+        const row = this.#agent(agentId);
+        return { id: agentId, teamId: String(row.team_id), workspaceId: String(row.workspace_id) };
+    }
+    /**
+     * Conform a send's content, refusing a body over the configured size before any transaction opens.
+     * @param args - Sender identity and the content it supplied.
+     * @returns - Content in the form every message the send queues stores it.
+     */
+    #messageContent(args) {
+        const subject = normalizeMessageSubject(args.subject);
+        const type = normalizeMessageType(args.type);
+        const body = encodeMessageBody(args.body);
+        if (Buffer.byteLength(body) > this.#maxBodyBytes) {
+            this.#projection.recordShed({
+                type: "message_shed",
+                reason: "body_size",
+                agentId: args.from,
+                limit: this.#maxBodyBytes,
+            });
+            throw new ProtocolError("validation_failed", "Message body exceeds the configured size limit");
+        }
+        return { subject, type, body, contentType: contentType(args.body) };
+    }
+    /**
+     * Find the message an earlier send carrying the same key queued for a recipient, recording the
+     * repeat on that message's lifecycle. A key names one send to one recipient, so the same key sends
+     * anew to a different recipient.
+     * @param senderId - Agent repeating the send.
+     * @param to - Recipient the repeat is addressed to.
+     * @param key - Idempotency key as stored, scoped to its kind of send.
+     * @returns - The earlier message and its recipient, or nothing when the key names no send to this
+     * recipient.
+     */
+    #repeatedMessage(senderId, to, key) {
+        const existing = this.#db
+            .prepare("select message_id from idempotency where agent_id = ? and recipient_id = ? and key = ?")
+            .get(senderId, to, key);
+        if (!existing)
+            return undefined;
+        const messageId = String(existing.message_id);
+        const recipient = this.#message(messageId).to;
+        this.#appendEvent(messageId, "broker", "duplicate_ignored", "duplicate send ignored", "muted");
+        return { messageId, to: recipient };
+    }
+    /**
+     * Report the limit that refuses one more message from a sender to a recipient, recording the shed.
+     * @param senderId - Agent the message would be from.
+     * @param to - Recipient the message would be queued for.
+     * @returns - The refusal's message, or nothing when neither the pair rate nor the inbox limit is
+     * reached.
+     */
+    #limitRefusal(senderId, to) {
+        if (this.#pairSendCount(senderId, to) >= this.#perPairRateLimit) {
+            this.#projection.recordShed({
+                type: "message_shed",
+                reason: "per_pair_rate",
+                agentId: senderId,
+                peerId: to,
+                limit: this.#perPairRateLimit,
+            });
+            return "Per-pair rate limit exceeded";
+        }
+        if (this.#inboxMessageCount(to) >= this.#maxInboxMessages) {
+            this.#projection.recordShed({
+                type: "message_shed",
+                reason: "queue_limit",
+                agentId: senderId,
+                peerId: to,
+                limit: this.#maxInboxMessages,
+            });
+            return "Recipient inbox limit exceeded";
+        }
+        return undefined;
+    }
+    /**
+     * Queue one message for a recipient every check has already admitted, inside the caller's
+     * transaction.
+     * @param sender - Agent the message is from, whose team and workspace it is recorded under.
+     * @param to - Recipient the message is queued for.
+     * @param key - Idempotency key a repeat of this send will present, as stored.
+     * @param content - Subject, type, and encoded body, already conformed.
+     * @param routing - Address the sender used and how it reached this recipient, recorded on the
+     * message and its lifecycle.
+     * @returns - Identity of the queued message.
+     */
+    #queue(sender, to, key, content, routing) {
+        const messageId = issueOpaqueToken("msg");
+        const trafficPosition = this.#allocateTrafficPosition();
+        this.#write("insert into messages(id, team_id, workspace_id, sender_id, recipient_id, addressed_to, address_outcome, subject, type, body, body_size, content_type, state, created_at, sequence) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'queued', ?, ?)", messageId, sender.teamId, sender.workspaceId, sender.id, to, routing.addressedTo, routing.outcome, content.subject, content.type, content.body, Buffer.byteLength(content.body), content.contentType, this.#now(), trafficPosition);
+        this.#write("insert into idempotency(agent_id, recipient_id, key, message_id, created_at) values (?, ?, ?, ?, ?)", sender.id, to, key, messageId, this.#now());
+        this.#appendEvent(messageId, "broker", "enqueued", "enqueued", "neutral");
+        const routed = routingEvent(routing, to);
+        this.#appendEvent(messageId, "broker", routed.type, routed.text, "neutral");
+        this.#syncRedelivery(to);
+        return messageId;
+    }
+    /**
+     * List who a broadcast reaches: every agent it may send to now, and every agent an earlier
+     * broadcast carrying the same key already reached.
+     * @param workspaceId - Workspace the broadcast targets.
+     * @param senderId - Agent broadcasting, which is never its own recipient.
+     * @param key - The broadcast's idempotency key, as stored.
+     * @returns - Recipient identities, ordered by id.
+     */
+    #broadcastRecipients(workspaceId, senderId, key) {
+        const rows = this.#db
+            .prepare(`select rowid, id from agents a where a.workspace_id = ? and a.id != ? and a.state = 'active' and a.archived_at is null and ${ANSWERABLE_AGENT_SQL} and not (${UNATTACHED_EPHEMERAL_LAPSED_SQL}) union select a.rowid, a.id from agents a join idempotency i on i.recipient_id = a.id where i.agent_id = ? and i.key = ? order by id`)
+            .all(workspaceId, senderId, this.#now(), this.#now(), senderId, key);
+        return this.#readableAgentRows(rows).map(({ id }) => id);
+    }
+    /**
+     * Claim queued messages for an agent atomically, returning opaque acknowledgement metadata.
+     * @param request - Agent to claim for, the claim cap, and the path making the claim.
+     * @returns - Messages claimed for the agent with fresh claim tokens.
+     */
+    fetch({ agentId, limit = FETCH_LIMIT_DEFAULT, claimedBy = "fetch" }) {
+        this.expireClaims();
+        const claimed = [];
+        this.#transaction(() => {
+            const workspaces = this.workspaceNames();
+            const broadcastAddress = this.#currentBroadcastAddress(agentId, workspaces);
+            const rows = this.#db
+                .prepare("select * from messages where recipient_id = ? and state = 'queued' order by sender_id, sequence limit ?")
+                .all(agentId, limit);
+            for (const row of rows) {
+                const from = row.sender_id;
+                if (!isAgentId(from)) {
+                    // Dead-letter: a skipped row is selected again by every fetch, and a throw rolls back the
+                    // claims taken beside it.
+                    this.#deadLetter([row], "dead-lettered — stored sender identity is unreadable");
+                    continue;
+                }
+                let body;
+                try {
+                    body = decodeMessageBody(row.body);
+                }
+                catch {
+                    this.#deadLetter([row], "dead-lettered — stored message body is not valid JSON");
+                    continue;
+                }
+                const token = issueOpaqueToken("claim");
+                const expires = this.#now() + this.#visibilityTimeoutMs;
+                this.#write("insert into claims(message_id, token, agent_id, expires_at, created_at) values (?, ?, ?, ?, ?)", String(row.id), token, agentId, expires, this.#now());
+                this.#write("update messages set state = 'claimed', claim_token = ?, claim_expires_at = ? where id = ? and state = 'queued'", token, expires, String(row.id));
+                this.#appendEvent(String(row.id), "broker", "claimed", claimedBy === "delivery" ? "claimed by delivery" : "claimed", "neutral");
+                claimed.push({
+                    id: String(row.id),
+                    from,
+                    fromAddress: this.#agentAddress(from, workspaces),
+                    // The select above constrains this column to the agent it was given, so it needs no read.
+                    to: agentId,
+                    // The address it was sent under stands in when the recipient's workspace has no name now.
+                    ...(row.address_outcome === "broadcast"
+                        ? { broadcastAddress: broadcastAddress ?? String(row.addressed_to) }
+                        : {}),
+                    subject: String(row.subject),
+                    type: String(row.type),
+                    body,
+                    claimToken: token,
+                    claimExpiresAt: expires,
+                });
+            }
+            this.#syncRedelivery(agentId);
+        });
+        return claimed;
+    }
+    /**
+     * Acknowledge claims while preserving their bodies for later inspection or explicit expiry.
+     *
+     * A token identifies both its message and its claim generation, so a token superseded by a re-claim
+     * after expiry matches nothing and leaves the live claim outstanding.
+     * @param agentId - Agent acknowledging its own claimed messages.
+     * @param claimTokens - Claim tokens proving ownership of fetched messages; a token repeated in one call counts once.
+     * @returns - The tokens acknowledged and, for each token that was not, the reason.
+     */
+    ack(agentId, claimTokens) {
+        const acked = [];
+        const rejected = [];
+        this.#transaction(() => {
+            for (const claimToken of new Set(claimTokens)) {
+                const row = this.#db
+                    .prepare("select id from messages where recipient_id = ? and state = 'claimed' and claim_token = ?")
+                    .get(agentId, claimToken);
+                if (!row) {
+                    rejected.push({ claimToken, reason: this.#ackRejectionReason(agentId, claimToken) });
+                    continue;
+                }
+                const messageId = String(row.id);
+                this.#write("update messages set state = 'acknowledged', claim_token = null, claim_expires_at = null where id = ?", messageId);
+                this.#appendEvent(messageId, "broker", "acknowledged", "consumed", "ok");
+                acked.push(claimToken);
+            }
+            this.#syncRedelivery(agentId);
+        });
+        return { acked, rejected };
+    }
+    /**
+     * Explain why a token matched no live claim of the acknowledging agent.
+     *
+     * Every token ever issued stays in `claims` until its message is pruned, so the token names its
+     * message and the message's state says what is left to do. A token the message has moved past, by a
+     * later claim that was itself acknowledged, is reported by that state rather than as a lapse.
+     * @param agentId - Agent that presented the token.
+     * @param claimToken - Token that matched no claimed message of that agent.
+     * @returns - The reason the acknowledgement did nothing.
+     */
+    #ackRejectionReason(agentId, claimToken) {
+        const claim = this.#db.prepare("select message_id, agent_id from claims where token = ?").get(claimToken);
+        if (!claim)
+            return "unknown_token";
+        if (claim.agent_id !== agentId)
+            return "foreign_token";
+        const message = this.#db.prepare("select state from messages where id = ?").get(String(claim.message_id));
+        if (!message)
+            return "claim_expired";
+        switch (readStoredEnum(message.state, MESSAGE_STATES, "messages.state")) {
+            case "acknowledged":
+                return "already_acknowledged";
+            case "expired":
+            case "dead_lettered":
+            case "failed":
+                return "message_settled";
+            case "queued":
+            case "claimed":
+                return "claim_expired";
+        }
+    }
+    /**
+     * Return claims the broker made on a recipient's behalf whose delivery never reached the host.
+     *
+     * Waiting out the visibility window would hold a message the recipient never saw for the whole
+     * window; the transport has already said nothing arrived, so the queue gets it back now. The
+     * redelivery schedule armed when the message was queued is still in place, because a claimed
+     * message keeps its inbox's schedule, and it decides when the message is offered again.
+     * @param agentId - Recipient the claims were made for.
+     * @param claimTokens - Claim tokens the failed delivery carried.
+     * @returns - Message identities returned to the queue; a claim already acknowledged or expired is skipped.
+     */
+    releaseClaims(agentId, claimTokens) {
+        const released = [];
+        this.#transaction(() => {
+            for (const claimToken of claimTokens) {
+                const row = this.#db
+                    .prepare("select id from messages where recipient_id = ? and state = 'claimed' and claim_token = ?")
+                    .get(agentId, claimToken);
+                if (!row)
+                    continue;
+                const messageId = String(row.id);
+                this.#write("update messages set state = 'queued', claim_token = null, claim_expires_at = null where id = ?", messageId);
+                this.#appendEvent(messageId, "broker", "claim_released", "delivery failed · still queued", "warn");
+                this.#appendEvent(messageId, "broker", "queued", "queued after delivery failed", "neutral");
+                released.push(messageId);
+            }
+        });
+        return released;
+    }
+    /**
+     * Return whether an agent has queued durable inbox messages without claiming them.
+     * @param agentId - Agent whose queue is checked.
+     * @returns - Whether the agent has at least one deliverable queued message.
+     */
+    hasQueuedMessages(agentId) {
+        const row = this.#db
+            .prepare("select 1 from messages where recipient_id = ? and state = 'queued' limit 1")
+            .get(agentId);
+        return Boolean(row);
+    }
+    /**
+     * Expire active claims back to the durable queue for redelivery.
+     *
+     * The only thing that settles a lapsed claim, and so the only thing that makes {@link snapshot}'s
+     * claim states current: a reader that never runs it sees a dead claimant's claim as `claimed`.
+     */
+    expireClaims() {
+        this.#transaction(() => {
+            const expired = this.#db
+                .prepare("select id, recipient_id from messages where state = 'claimed' and claim_expires_at <= ?")
+                .all(this.#now());
+            for (const row of expired) {
+                const messageId = String(row.id);
+                this.#write("update messages set state = 'queued', claim_token = null, claim_expires_at = null where id = ?", messageId);
+                this.#appendEvent(messageId, "broker", "claim_expired", `still queued · ttl ${formatDurationLabel(this.#redeliveryGiveUpMs)}`, "warn");
+                this.#appendEvent(messageId, "broker", "queued", "queued after claim expiry", "neutral");
+                // Skip-and-name: a throw would roll back every claim this sweep settles.
+                this.#syncSkippingUnreadable(row.recipient_id, "messages.recipient_id", messageId);
+            }
+        });
+    }
+    /**
+     * Advance the redelivery schedule and report the inboxes now owed another wake.
+     *
+     * Claims are expired first, so an inbox whose messages are merely in flight is distinguished from
+     * one whose recipient stopped answering: only the second spends an attempt. An inbox that has been
+     * retried past the give-up budget is dead-lettered here rather than retried again, because a
+     * sender waiting on a delivery outcome is owed a terminal state. An inbox whose stored recipient
+     * cannot be read is dead-lettered on its first due wake, claimed messages included, since none can
+     * be fetched or acknowledged.
+     * @returns - Recipients whose queued messages should be notified again, in no guaranteed order.
+     */
+    dueRedeliveryWakes() {
+        this.expireClaims();
+        const due = [];
+        this.#transaction(() => {
+            const now = this.#now();
+            const rows = this.#db
+                .prepare("select rowid, agent_id, attempts from wakes where next_wake_at <= ?")
+                .all(now);
+            for (const row of rows) {
+                // Settle-and-name, by rowid: a row left due holds `nextSweepDelayMs` at zero, and the column
+                // that would address it is the unreadable one.
+                const agentId = this.#readableAgentId(row.agent_id, "wakes.agent_id", String(row.rowid));
+                if (agentId === null) {
+                    this.#deadLetter(this.#db
+                        .prepare("select m.id from messages m join wakes w on m.recipient_id = w.agent_id where w.rowid = ? and m.state in ('queued','claimed') order by m.sequence")
+                        .all(Number(row.rowid)), UNREADABLE_RECIPIENT_REASON);
+                    this.#write("delete from wakes where rowid = ?", Number(row.rowid));
+                    continue;
+                }
+                this.#abandonExhaustedMessages(agentId, now);
+                if (this.#inboxMessageCount(agentId) === 0) {
+                    this.#write("delete from wakes where agent_id = ?", agentId);
+                    continue;
+                }
+                // An unclaimed message is what the backoff measures, so a tick that finds every message
+                // claimed reschedules without spending an attempt. Leaving the row due instead would make
+                // the deadline permanently zero and turn the sweep into a spin.
+                const owed = this.hasQueuedMessages(agentId);
+                const attempts = owed ? Number(row.attempts) + 1 : Number(row.attempts);
+                this.#write("update wakes set attempts = ?, next_wake_at = ? where agent_id = ?", attempts, this.#nextWakeAt(agentId, now, attempts), agentId);
+                if (owed)
+                    due.push(agentId);
+            }
+        });
+        return due;
+    }
+    /**
+     * Record that a redelivery wake reached one recipient, against each message it covered.
+     *
+     * Separate from scheduling because only the caller that published the wake knows whether it was
+     * admitted: a wake the budget shed still costs an attempt, but writing it to the lifecycle would
+     * tell an operator a message was delivered again when nothing left the broker.
+     * @param agentId - Recipient the wake was published for.
+     */
+    recordRedeliveryAttempt(agentId) {
+        this.#transaction(() => {
+            const row = this.#db.prepare("select attempts from wakes where agent_id = ?").get(agentId);
+            if (!row)
+                return;
+            const queued = this.#db
+                .prepare("select id from messages where recipient_id = ? and state = 'queued' order by sequence")
+                .all(agentId);
+            for (const message of queued) {
+                this.#appendEvent(String(message.id), "broker", "redelivery", `redelivery attempt ${String(Number(row.attempts))}`, "warn");
+            }
+        });
+    }
+    /**
+     * Mark expired unattached reservations and parent-visible dead-letter outcomes.
+     *
+     * Scoped to an agent with no active session at all: an agent already attached on one channel can
+     * hold an unconsumed reservation on another (its delivery channel, when its implementation has no
+     * host-push capability and so never attaches it) that outlives the reservation TTL forever. That
+     * reservation expiring is not the agent going unanswered — it is alive and reachable — so treating
+     * it as a never-attached identity would dead-letter its live mail out from under it.
+     */
+    reapExpiredReservations() {
+        const expired = [];
+        const sweep = issueOpaqueToken("sweep");
+        this.#transaction(() => {
+            const expiredAt = this.#now();
+            const rows = this.#db
+                .prepare("select r.rowid as reservation_rowid, r.agent_id, a.parent_id from reservations r join agents a on a.id = r.agent_id where r.consumed_at is null and r.expires_at <= ? and not exists (select 1 from sessions s where s.agent_id = a.id and s.active = 1)")
+                .all(expiredAt);
+            this.#lifecycleSynchronization?.checkpoint("expired_reservations_scanned");
+            for (const row of rows) {
+                const agentId = this.#readableAgentId(row.agent_id, "reservations.agent_id", String(row.reservation_rowid));
+                if (agentId === null) {
+                    // Settle-and-name, by rowid; its messages are dead-lettered by the stored value.
+                    this.#deadLetter(this.#db
+                        .prepare("select m.id from messages m join reservations r on m.recipient_id = r.agent_id where r.rowid = ? and m.state in ('queued','claimed') order by m.sequence")
+                        .all(Number(row.reservation_rowid)), UNREADABLE_RECIPIENT_REASON);
+                    this.#write("delete from reservations where rowid = ?", Number(row.reservation_rowid));
+                    continue;
+                }
+                expired.push({ agentId, parentId: typeof row.parent_id === "string" ? row.parent_id : null });
+                this.#deadLetter(this.#db
+                    .prepare("select id from messages where recipient_id = ? and state in ('queued','claimed') order by sequence")
+                    .all(agentId), "dead-lettered");
+                this.#write("delete from reservations where agent_id = ? and consumed_at is null and expires_at <= ?", agentId, expiredAt);
+                this.#syncRedelivery(agentId);
+            }
+        });
+        for (const { agentId, parentId } of expired) {
+            if (parentId === null)
+                continue;
+            this.#notifyParent(agentId, parentId, "dead_lettered", `agent-dead_lettered:${agentId}:${sweep}`);
+        }
+    }
+    /**
+     * Mark a message expired, retaining the stored body and the sender-visible status of its row.
+     * @param messageId - Message being marked expired.
+     * @param actor - Identity performing the audited action.
+     */
+    expireMessage(messageId, actor) {
+        this.#transaction(() => {
+            this.#transitionTerminalInTransaction(messageId, { state: "expired", actor });
+        });
+    }
+    /**
+     * Mark a message failed, retaining the stored body and the sender-visible status of its row.
+     * @param messageId - Message being marked failed.
+     */
+    failMessage(messageId) {
+        this.#transaction(() => {
+            const current = this.#db.prepare("select state from messages where id = ?").get(messageId);
+            if (!current)
+                throw new ProtocolError("validation_failed", "Unknown message");
+            if (current.state === "failed")
+                return;
+            this.#transitionTerminalInTransaction(messageId, { state: "failed" });
+        });
+    }
+    /**
+     * Return body-free status for a sender-visible message.
+     * @param messageId - Message whose status is read.
+     * @param requester - Agent identity authorized to inspect sender-visible status.
+     * @returns - Sender-visible delivery status without retained message content.
+     */
+    status(messageId, requester) {
+        const row = this.#message(messageId);
+        if (requester && row.from !== requester)
+            throw new ProtocolError("validation_failed", "Message status is sender-visible only");
+        return { messageId, state: row.state, to: row.to };
+    }
+    /**
+     * Return the broker's observable operational events.
+     * @returns - Copy of accumulated operational events, safe for caller inspection.
+     */
+    operationalEvents() {
+        return this.#projection.operationalEvents();
+    }
+    /**
+     * Append an operational event recording the outcome of a delivery notification attempt.
+     * @param messageId - Message the notification outcome is recorded against.
+     * @param outcome - Observed notification result recorded for diagnostics.
+     */
+    recordNotification(messageId, outcome) {
+        const display = notificationDisplay[outcome];
+        this.#transaction(() => {
+            this.#appendEvent(messageId, "notify", `notify_${outcome}`, display.text, display.tone);
+        });
+    }
+    /**
+     * Reads a message's retained body, available until the settled-message prune deletes its row.
+     * @param messageId - Message whose retained body is read.
+     * @returns - Retained body content and its stored representation metadata.
+     */
+    readMessageBody(messageId) {
+        return this.#projection.readMessageBody(messageId);
+    }
+    /**
+     * Read bounded durable traffic without claiming, acknowledging, or changing retained bodies.
+     * @returns Traffic source rows in their single broker-owned durable order.
+     */
+    operatorTrafficRecords() {
+        return this.#projection.operatorTrafficRecords();
+    }
+    /**
+     * Return a prior operator command acceptance for idempotent request handling.
+     * @param commandId - Opaque command correlation supplied by the operator boundary.
+     * @returns Stored acceptance, or null when this command has not been accepted.
+     */
+    operatorCommand(commandId) {
+        return this.#projection.operatorCommand(commandId);
+    }
+    /**
+     * Persist ping request acceptance and its audit before the scheduler publishes a wake.
+     * @param commandId - Opaque idempotency correlation for the operator request.
+     * @param targetAgentId - Active broker agent requested by the operator.
+     * @param controlId - Opaque correlation carried by the body-free wake.
+     * @returns Newly persisted command acceptance.
+     */
+    acceptOperatorPing(commandId, targetAgentId, controlId) {
+        assertDurableOperatorId(commandId, "command");
+        assertDurableOperatorId(controlId, "control");
+        return this.#transaction(() => {
+            const prior = this.operatorCommand(commandId);
+            if (prior) {
+                if (prior.type !== "ping_agent" || prior.targetId !== targetAgentId) {
+                    throw new ProtocolError("conflict", "Operator command already exists");
+                }
+                return { status: "existing", record: prior };
+            }
+            this.#activeAgent(targetAgentId);
+            const acceptedAt = this.#now();
+            const trafficPosition = this.#allocateTrafficPosition();
+            const auditId = issueOpaqueToken("audit");
+            this.#write("insert into operator_commands(command_id, type, target_id, accepted_at, control_id) values (?, 'ping_agent', ?, ?, ?)", commandId, targetAgentId, acceptedAt, controlId);
+            this.#write("insert into operator_ping_audits(audit_id, command_id, control_id, target_agent_id, actor, accepted_at, traffic_position) values (?, ?, ?, ?, 'operator', ?, ?)", auditId, commandId, controlId, targetAgentId, acceptedAt, trafficPosition);
+            return {
+                status: "created",
+                record: { type: "ping_agent", commandId, targetId: targetAgentId, acceptedAt, controlId },
+            };
+        });
+    }
+    /**
+     * Atomically expire one retained message and persist command acceptance for idempotent retry.
+     * @param commandId - Opaque idempotency correlation for the operator request.
+     * @param messageId - Accepted message whose retained body stays readable until the settled-message prune.
+     * @returns Newly persisted command acceptance.
+     */
+    acceptOperatorExpiry(commandId, messageId) {
+        assertDurableOperatorId(commandId, "command");
+        assertDurableOperatorId(messageId, "message");
+        return this.#transaction(() => {
+            const prior = this.operatorCommand(commandId);
+            if (prior) {
+                if (prior.type !== "expire_message" || prior.targetId !== messageId) {
+                    throw new ProtocolError("conflict", "Operator command already exists");
+                }
+                return { status: "existing", record: prior };
+            }
+            this.#transitionTerminalInTransaction(messageId, { state: "expired", actor: "operator" });
+            const acceptedAt = this.#now();
+            this.#write("insert into operator_commands(command_id, type, target_id, accepted_at, control_id) values (?, 'expire_message', ?, ?, null)", commandId, messageId, acceptedAt);
+            return {
+                status: "created",
+                record: { type: "expire_message", commandId, targetId: messageId, acceptedAt },
+            };
+        });
+    }
+    /**
+     * Accept one operator archive request, putting the agent away without disturbing its mail.
+     *
+     * The same lifecycle holds for every identity, ephemeral or named: active, archived, then reaped.
+     * Until the reaper takes it, once `archivedRetentionMs` has passed since this acceptance, the
+     * identity keeps its name, its conversation key, its inbox and its addressability, so the ordinary
+     * reconnection path is what brings it back and everything queued for it, before or since, is
+     * waiting when it does. Attaching un-archives it and stops the clock. Archiving an identity that is
+     * already archived keeps the first `archived_at`, so a repeat request never extends the window.
+     * @param commandId - Correlates retries of the same operator request.
+     * @param agentId - Agent the operator asked to archive.
+     * @returns - Durable acceptance, reporting whether this call created it.
+     */
+    acceptOperatorArchive(commandId, agentId) {
+        assertDurableOperatorId(commandId, "command");
+        const target = agentId;
+        const acceptance = this.#transaction(() => {
+            const prior = this.operatorCommand(commandId);
+            if (prior) {
+                if (prior.type !== "archive_agent" || prior.targetId !== agentId) {
+                    throw new ProtocolError("conflict", "Operator command already exists");
+                }
+                return { status: "existing", record: prior };
+            }
+            const row = this.#db.prepare("select id from agents where id = ? and state != 'reaped'").get(target);
+            if (!row)
+                throw new ProtocolError("validation_failed", "Unknown agent");
+            const acceptedAt = this.#now();
+            // The identity is otherwise left as a detached one: archiving ends its attachments and marks it.
+            this.#write("update agents set archived_at = coalesce(archived_at, ?) where id = ?", acceptedAt, target);
+            this.#write("update sessions set active = 0 where agent_id = ?", target);
+            this.#write("insert into operator_commands(command_id, type, target_id, accepted_at, control_id) values (?, 'archive_agent', ?, ?, null)", commandId, agentId, acceptedAt);
+            return {
+                status: "created",
+                record: { type: "archive_agent", commandId, targetId: agentId, acceptedAt },
+            };
+        });
+        return acceptance;
+    }
+    /**
+     * Returns the broker snapshot, optionally scoped to one workspace.
+     *
+     * A read: it writes nothing and publishes no commit. Claim states are as current as the last
+     * {@link expireClaims}.
+     * @param workspaceId - Workspace whose agents, and the messages they sent or received, the
+     * snapshot is scoped to; every workspace when absent.
+     * @returns - Broker snapshot, optionally scoped to the requested workspace.
+     */
+    snapshot(workspaceId) {
+        const now = this.#now();
+        return this.#projection.readSnapshot(workspaceId, now, this.snapshotHealth(now));
+    }
+    /**
+     * Return the agent-derived state an operator projection reads, without any delivery.
+     * @returns - The snapshot's workspace, agent, and connection sections; deliveries and diagnostics are omitted.
+     */
+    operatorAgentSource() {
+        return this.#projection.readAgentSource();
+    }
+    /**
+     * Return the concrete team for a registered agent.
+     * @param agentId - Registered agent whose team is looked up.
+     * @returns - Team identity that owns the registered agent.
+     */
+    teamForAgent(agentId) {
+        return String(this.#agent(agentId).team_id);
+    }
+    /**
+     * Return the implementation identity recorded for an agent when it was registered.
+     * @param agentId - Registered agent whose implementation is looked up.
+     * @returns - Implementation recorded by the composition boundary, or null when none was supplied.
+     */
+    implementationForAgent(agentId) {
+        const agent = this.#agent(agentId);
+        if (typeof agent.implementation_id !== "string")
+            return null;
+        return {
+            id: agent.implementation_id,
+            ...(typeof agent.implementation_version === "string" ? { version: agent.implementation_version } : {}),
+        };
+    }
+    /**
+     * Return team directory entries visible to the attached agent.
+     *
+     * A reaped identity is omitted, since a send to it is refused.
+     * @param agentId - Attached agent whose team roster is listed.
+     * @returns - Registered identities and current aliases visible within the agent team.
+     */
+    listTeamMembers(agentId) {
+        const agent = this.#agent(agentId);
+        const agents = this.#db
+            .prepare("select rowid, id, registration_name from agents where team_id = ? and state != 'reaped' order by id")
+            .all(String(agent.team_id));
+        return this.#readableAgentRows(agents).map(({ id, row }) => ({
+            id,
+            alias: normalizeAlias(String(row.registration_name)),
+        }));
+    }
+    /**
+     * Return every agent a sender can currently reach, with the address that reaches it from any workspace.
+     *
+     * A reaped identity is omitted, since a send to it is refused. So is a detached ephemeral identity
+     * that is not archived: it is retained only so its own conversation can resume, and offering it
+     * here invites a sender to address an inbox nothing will ever claim. An archived identity is listed
+     * because a send to it is accepted and waits.
+     * @returns - Registered identities, aliases, workspace names, and routable addresses.
+     */
+    listAgents() {
+        const names = this.workspaceNames();
+        const agents = this.#db
+            .prepare(`select rowid, id, registration_name, workspace_id from agents a where state != 'reaped' and (archived_at is not null or ${ANSWERABLE_AGENT_SQL}) order by workspace_id, id`)
+            .all(this.#now());
+        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}` };
+        });
+    }
+    /**
+     * Settle and validate the identity a registration will write, before any port or transaction runs.
+     *
+     * The single producer of the identity {@link Broker.registerAgent} accepts, so the `agents.id` it
+     * writes has passed the protocol's rule whatever the caller supplied. The implementation id is
+     * checked here too, so a provider identity the operator wire would refuse to carry is never written.
+     *
+     * `parentId` is not checked here. It is typed {@link AgentId}, so only a caller that casts past the
+     * type can put an unaddressable value in `agents.parent_id`.
+     * @param requested - Caller-supplied identity, or nothing when the broker mints one.
+     * @param requestedName - Caller-supplied alias, or nothing to derive one from the identity.
+     * @param implementation - Caller-supplied implementation, when the registration records one.
+     * @returns - Validated identity and the alias that will be written beside it.
+     */
+    #registrationIdentity(requested, requestedName, implementation) {
+        const agentId = requested ?? mintAgentId(issueOpaqueToken("agent"));
+        assertAgentId(agentId, "registration agent id");
+        if (implementation)
+            validateImplementationId(implementation.id);
+        return {
+            agentId,
+            sessionName: validateRegistrationSessionName(requestedName ?? defaultAgentSessionName(agentId)),
+        };
+    }
+    #registerAgent(args, identity, branch) {
+        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 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);
+        return agentId;
+    }
+    /**
+     * Hand one diagnostic to the report port, absorbing whatever the port does with it.
+     *
+     * Callers are draining a loop whose earlier steps have already committed — the reap has deleted
+     * the reservations it settled — so a sink that throws must not cost the parents further down that
+     * loop their notifications. A sink that cannot accept a message is its own problem, not theirs.
+     * @param message - Operator-facing diagnostic to report.
+     */
+    #reportSafely(message) {
+        try {
+            this.#report(message);
+        }
+        catch {
+            // A diagnostic that cannot be delivered is not worth failing the sweep that raised it.
+        }
+    }
+    /**
+     * Read the branch checked out at a workspace path, for every registration that reaches it.
+     *
+     * 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.
+     */
+    #currentWorkspaceBranch(workspacePath) {
+        return this.#workspaceBranch(workspacePath);
+    }
+    /**
+     * Record the workspace and team a registration lands in, and refresh a known workspace's branch.
+     *
+     * 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.
+     * @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);
+        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);
+        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);
+        if (existing) {
+            if (existing.implementation_id !== args.implementation.id) {
+                throw new ProtocolError("alias_conflict", "Agent alias is already in use in this workspace");
+            }
+            const agentId = readStoredAgentId(existing.id, "agents.id");
+            this.#assertNameAvailable(args.workspaceId, args.sessionName, agentId);
+            this.#assertHolderDetached(agentId, args.sessionName);
+            this.#displaceHolder(agentId);
+            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);
+        return agentId;
+    }
+    /**
+     * Refuse to rejoin a session name whose holder is still attached.
+     *
+     * Rejoining deactivates the holder's sessions and hands its inbox to the newcomer, so the holder's
+     * next call fails with no way back. A holder whose lease has lapsed, or that was archived (which
+     * ends its attachments), is not answering and may be rejoined.
+     * @param holderId - Identity currently registered under the name.
+     * @param sessionName - Name the caller asked to rejoin, for the error.
+     */
+    #assertHolderDetached(holderId, sessionName) {
+        const live = this.#db
+            .prepare("select 1 as present from sessions where agent_id = ? and active = 1 and expires_at > ? limit 1")
+            .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`);
+    }
+    #agentForSessionKey(workspaceId, 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);
+        if (!row)
+            return undefined;
+        return {
+            agentId: readStoredAgentId(row.id, "agents.id"),
+            sessionName: String(row.registration_name),
+            ephemeral: Number(row.registration_ephemeral) === 1,
+        };
+    }
+    /**
+     * Point an identity at a conversation key, optionally retiring the attachments of the previous one.
+     * @param agentId - Identity whose key is being set.
+     * @param sessionKey - Conversation key to bind.
+     * @param evictExistingSessions - Whether to retire the identity's current attachments. Only a
+     * caller that hands back a fresh attachment may pass true: retiring them for a caller that does
+     * not leaves it holding a session the broker will refuse and no reservation to replace it with.
+     */
+    #bindSessionKey(agentId, sessionKey, evictExistingSessions) {
+        const row = this.#db.prepare("select session_key from agents where id = ?").get(agentId);
+        if (!row)
+            throw new ProtocolError("unknown_recipient", "Agent identity is unknown");
+        const current = typeof row.session_key === "string" ? row.session_key : undefined;
+        if (current === sessionKey)
+            return;
+        if (current !== undefined && evictExistingSessions) {
+            this.#write("update sessions set active = 0 where agent_id = ?", agentId);
+        }
+        this.#write("update agents set session_key = ? where id = ?", sessionKey, agentId);
+    }
+    #resolveSessionKeyAtAttach(reserved, sessionKey) {
+        const reservedAgent = this.#db
+            .prepare("select workspace_id, 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);
+        if (!owner || owner.agentId === reserved) {
+            this.#bindSessionKey(reserved, sessionKey, true);
+            return reserved;
+        }
+        this.#displaceHolder(owner.agentId);
+        this.#discardUnusedIdentity(reserved, owner.agentId);
+        return owner.agentId;
+    }
+    /**
+     * End what a process holds on an identity it is leaving or losing: its sessions, so a lapsed one
+     * cannot be resumed and act as the identity or detach it, and its unconsumed reservations, which
+     * outlive a lease and would attach the same way. On a hand-over this runs before the newcomer's
+     * reservations are made or moved onto the identity, so nothing of the newcomer's is touched.
+     * @param agentId - Identity being left or taken over.
+     */
+    #displaceHolder(agentId) {
+        this.#write("update sessions set active = 0 where agent_id = ? and active = 1", agentId);
+        this.#write("delete from reservations where agent_id = ? and consumed_at is null", agentId);
+    }
+    /**
+     * Remove an identity a launch minted for a conversation that turned out to already own one. It is
+     * deleted rather than reaped so it never reaches operator projection: nothing ever used it, and an
+     * archived row for a duplicate that never existed is noise a person would have to interpret.
+     *
+     * A launch reserves one reservation per channel and the process consumes them one at a time, so any
+     * reservation still outstanding moves to the adopting identity. Without that, the second channel of a
+     * multi-channel harness would attach against an identity that no longer exists.
+     * @param agentId - Reserved identity that has never carried traffic.
+     * @param adoptedBy - Identity that takes over this one's outstanding attachment reservations.
+     * @param options - Whether the caller has proven it owns this identity's live connections.
+     */
+    #discardUnusedIdentity(agentId, adoptedBy, options = {}) {
+        const attached = this.#db.prepare("select 1 as present from sessions where agent_id = ? limit 1").get(agentId);
+        const routed = this.#db
+            .prepare("select 1 as present from messages where sender_id = ? or recipient_id = ? limit 1")
+            .get(agentId, agentId);
+        if ((attached !== undefined && options.allowConnections !== true) || routed !== undefined)
+            throw new ProtocolError("conflict", "Reserved identity has already been used");
+        this.#write("update sessions set active = 0 where agent_id = ?", agentId);
+        this.#write("delete from alias_history where agent_id = ?", agentId);
+        this.#write("update reservations set agent_id = ? where agent_id = ? and consumed_at is null", adoptedBy, agentId);
+        this.#write("delete from reservations where agent_id = ?", agentId);
+        this.#write("delete from agents where id = ?", agentId);
+    }
+    #reserveAttachment(agentId, channel) {
+        const reservationId = issueOpaqueToken("attach");
+        this.#activeAgent(agentId);
+        this.#lifecycleSynchronization?.checkpoint("attachment_reservation_active");
+        this.#write("insert into reservations(reservation_id, agent_id, channel, expires_at, consumed_at) values (?, ?, ?, ?, null)", reservationId, agentId, channel, this.#now() + this.#reservationTtlMs);
+        return reservationId;
+    }
+    /**
+     * Execute one write and declare the table it changed to the surrounding transaction.
+     *
+     * Every broker write goes through here. A write that reaches the connection directly is invisible
+     * to the changeset, which is why `check:broker-writes` rejects one.
+     * @param sql - Single insert, update, or delete statement.
+     * @param parameters - Values bound to the statement's positional placeholders.
+     * @returns - Change count and inserted row identity.
+     */
+    #write(sql, ...parameters) {
+        let statement = this.#writeStatements.get(sql);
+        if (!statement) {
+            statement = this.#db.prepare(sql);
+            this.#writeStatements.set(sql, statement);
+        }
+        const result = statement.run(...parameters);
+        if (result.changes > 0) {
+            this.#declaredRowChanges += result.changes;
+            this.#writtenTables?.add(mutatedTable(sql));
+        }
+        return result;
+    }
+    #rowChanges() {
+        return Number(this.#db.prepare("select total_changes() as changes").get().changes);
+    }
+    #transaction(fn) {
+        if (this.#writtenTables)
+            throw new Error("Broker#transaction does not nest");
+        const tables = new Set();
+        this.#writtenTables = tables;
+        this.#declaredRowChanges = 0;
+        this.#db.exec("begin immediate");
+        const rowChangesBefore = this.#rowChanges();
+        try {
+            const result = fn();
+            const declared = this.#declaredRowChanges;
+            const changed = this.#rowChanges() - rowChangesBefore;
+            this.#db.exec("commit");
+            this.#writtenTables = undefined;
+            this.#declaredRowChanges = 0;
+            if (changed > 0)
+                this.#publishCommitted({ tables: changed === declared ? tables : undefined });
+            return result;
+        }
+        catch (error) {
+            this.#db.exec("rollback");
+            this.#writtenTables = undefined;
+            this.#declaredRowChanges = 0;
+            throw error;
+        }
+    }
+    #publishCommitted(commit) {
+        for (const listener of [...this.#commitListeners]) {
+            try {
+                listener(commit);
+            }
+            catch {
+                // A post-commit observer cannot retroactively reject an already durable broker mutation.
+            }
+        }
+    }
+    #appendEvent(messageId, source, type, text, tone) {
+        this.#write("insert into message_events(message_id, at, source, type, text, tone) values (?, ?, ?, ?, ?, ?)", messageId, this.#now(), source, type, text, tone);
+    }
+    #nextImplementationAlias(workspaceId, implementationId) {
+        for (let ordinal = 1; ordinal <= IMPLEMENTATION_ALIAS_LIMIT; ordinal += 1) {
+            const candidate = `${implementationId}-${String(ordinal)}`;
+            if (this.#nameHeldInWorkspace(workspaceId, candidate))
+                continue;
+            try {
+                this.#assertNameAvailable(workspaceId, candidate);
+                return candidate;
+            }
+            catch {
+                continue;
+            }
+        }
+        return defaultAgentSessionName(issueOpaqueToken("agent"));
+    }
+    #nameHeldInWorkspace(workspaceId, sessionName) {
+        const row = this.#db
+            .prepare("select 1 from agents where workspace_id = ? and registration_name = ? limit 1")
+            .get(workspaceId, sessionName);
+        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");
+        }
+    }
+    #pairSendCount(from, to) {
+        const row = this.#db
+            .prepare("select count(*) as count from messages where sender_id = ? and recipient_id = ? and created_at > ?")
+            .get(from, to, this.#now() - this.#perPairRateWindowMs);
+        return Number(row?.count ?? 0);
+    }
+    /**
+     * Hold the redelivery schedule to one row per recipient with undelivered messages.
+     *
+     * Arming is conditional so a second send cannot restart a schedule already in progress: a chatty
+     * sender would otherwise hold its recipient at the first interval forever.
+     * @param agentId - Recipient whose undelivered set just changed.
+     */
+    #syncRedelivery(agentId) {
+        if (this.#inboxMessageCount(agentId) === 0) {
+            this.#write("delete from wakes where agent_id = ?", agentId);
+            return;
+        }
+        const now = this.#now();
+        this.#write("insert or ignore into wakes(agent_id, attempts, next_wake_at) values (?, 0, ?)", agentId, now + this.#redeliveryDelayMs(0));
+    }
+    /**
+     * Report how long to wait before the next redelivery wake.
+     * @param attempts - Redelivery wakes already spent on this inbox.
+     * @returns - Delay in milliseconds, doubling from the base until it reaches the ceiling.
+     */
+    #redeliveryDelayMs(attempts) {
+        return this.#redeliveryBaseDelayMs * 2 ** Math.min(attempts, REDELIVERY_DOUBLING_LIMIT);
+    }
+    /**
+     * Report when the next redelivery wake for one recipient is due.
+     *
+     * The give-up horizon of the oldest queued message caps the doubling, so abandonment lands on the
+     * budget rather than up to one whole interval past it. A claimed message is excluded because its
+     * own claim already schedules a sweep, and a horizon that has passed would make this deadline
+     * permanently due.
+     * @param agentId - Recipient whose schedule is being advanced.
+     * @param now - Current time, already read once by the caller.
+     * @param attempts - Redelivery wakes spent on this inbox including the one just scheduled.
+     * @returns - Timestamp of the next wake.
+     */
+    #nextWakeAt(agentId, now, attempts) {
+        const scheduled = now + this.#redeliveryDelayMs(attempts);
+        const oldest = this.#db
+            .prepare("select min(created_at) as oldest from messages where recipient_id = ? and state = 'queued'")
+            .get(agentId);
+        if (typeof oldest?.oldest !== "number")
+            return scheduled;
+        return Math.min(scheduled, oldest.oldest + this.#redeliveryGiveUpMs);
+    }
+    /**
+     * Move every message that outlived the redelivery budget to its terminal dead-lettered state.
+     *
+     * The budget is measured per message rather than per inbox, so a message that arrived while an
+     * older one was still being retried gets the whole budget of its own. Only queued messages are
+     * abandoned: dead-lettering one a recipient currently holds would make its acknowledgement match
+     * nothing and be reported as success while the sender read the delivery as abandoned.
+     * @param agentId - Recipient whose oldest messages are being abandoned.
+     * @param now - Current time, already read once by the caller.
+     */
+    #abandonExhaustedMessages(agentId, now) {
+        this.#deadLetter(this.#db
+            .prepare("select id from messages where recipient_id = ? and state = 'queued' and created_at <= ? order by sequence")
+            .all(agentId, now - this.#redeliveryGiveUpMs), "dead-lettered after redelivery gave up");
+    }
+    /**
+     * Move messages to their terminal dead-lettered state, releasing any claim outstanding on them.
+     * @param messages - Rows carrying the message identities to abandon.
+     * @param reason - Operator-facing lifecycle text naming why they were abandoned.
+     */
+    #deadLetter(messages, reason) {
+        for (const row of messages) {
+            const messageId = String(row.id);
+            this.#write("update messages set state = 'dead_lettered', claim_token = null, claim_expires_at = null where id = ?", messageId);
+            this.#appendEvent(messageId, "broker", "dead_lettered", reason, "danger");
+        }
+    }
+    /**
+     * Report whether an identity is currently archived.
+     *
+     * An archived agent stays addressable until it is reaped, so a sender is told rather than refused:
+     * the mail waits for the conversation to come back and claim it.
+     * @param agentId - Identity being addressed.
+     * @returns - Whether an operator has archived it.
+     */
+    #isArchived(agentId) {
+        const row = this.#db.prepare("select archived_at from agents where id = ?").get(agentId);
+        return typeof row?.archived_at === "number";
+    }
+    #inboxMessageCount(agentId) {
+        const row = this.#db
+            .prepare("select count(*) as count from messages where recipient_id = ? and state in ('queued', 'claimed')")
+            .get(agentId);
+        return Number(row?.count ?? 0);
+    }
+    /**
+     * Settle one message into a terminal state from within an open transaction.
+     *
+     * Only a live message settles: a source outside `queued` and `claimed` is refused with `conflict`,
+     * so a terminal state is never rewritten by a later expiry. The sender reads delivery state back
+     * through {@link status}, and rewriting an `acknowledged` message as `expired` would tell it the
+     * work it already had consumed was abandoned.
+     * @param messageId - Message being settled.
+     * @param outcome - Terminal state to settle into; an expiry also names who asked, distinguishing
+     * an operator command from the broker's own ttl sweep in the operator-facing lifecycle text. A
+     * failure carries no actor: every caller settles it the same way.
+     */
+    #transitionTerminalInTransaction(messageId, outcome) {
+        const { state } = outcome;
+        const current = this.#db.prepare("select state, body, recipient_id from messages where id = ?").get(messageId);
+        if (!current)
+            throw new ProtocolError("validation_failed", "Unknown message");
+        if (current.state !== "queued" && current.state !== "claimed") {
+            throw new ProtocolError("conflict", `Message state cannot transition to ${state}`);
+        }
+        const changed = this.#write("update messages set state = ?, claim_token = null, claim_expires_at = null where id = ?", state, messageId);
+        if (changed.changes === 0)
+            throw new ProtocolError("validation_failed", "Unknown message");
+        this.#appendEvent(messageId, "broker", state, outcome.state === "expired"
+            ? outcome.actor === "operator"
+                ? "expired by operator"
+                : "expired at ttl"
+            : "failed", state === "expired" ? "muted" : "danger");
+        this.#syncSkippingUnreadable(current.recipient_id, "messages.recipient_id", messageId);
+    }
+    /**
+     * Read a stored agent id, reporting one it cannot read rather than throwing.
+     *
+     * Reports through the projection's ring, and writes the diagnostic line only when the ring did not
+     * already hold this row and column.
+     * @param value - Column value as the driver returned it.
+     * @param column - Column named in the diagnostic, qualified by its table.
+     * @param rowKey - Identifies the row within that table, so two bad rows are two reports.
+     * @returns - The identity, or null when the value is not one.
+     */
+    #readableAgentId(value, column, rowKey) {
+        if (isAgentId(value))
+            return value;
+        if (this.#projection.recordStoredRowSkip({ type: "stored_row_skipped", column, rowKey })) {
+            this.#reportSafely(`pager: ${column} of row ${rowKey} cannot be read`);
+        }
+        return null;
+    }
+    /**
+     * Pair each readable `agents.id` with its row, skipping and reporting every row whose id cannot be
+     * read. For a read that answers which agents exist: one unreadable row must not fail it for every
+     * caller.
+     * @param rows - Rows of `agents`, each carrying its `rowid` and `id`.
+     * @returns - The readable rows, in the order given.
+     */
+    #readableAgentRows(rows) {
+        return rows.flatMap((row) => {
+            const id = this.#readableAgentId(row.id, "agents.id", String(row.rowid));
+            return id === null ? [] : [{ id, row }];
+        });
+    }
+    /**
+     * Name the broadcast a copy queued for this recipient belongs to, by the recipient's workspace.
+     * @param recipientId - Agent whose copies are being claimed.
+     * @param workspaces - Current name of each workspace.
+     * @returns - The broadcast address under the workspace's current name, or nothing when the
+     * recipient or its workspace has none.
+     */
+    #currentBroadcastAddress(recipientId, workspaces) {
+        const row = this.#db.prepare("select workspace_id from agents where id = ?").get(recipientId);
+        const name = row ? workspaces.get(String(row.workspace_id)) : undefined;
+        return name === undefined ? undefined : `${BROADCAST_ADDRESS_PREFIX}${name}`;
+    }
+    /**
+     * Start a recipient's redelivery schedule if it has none, or clear it once the inbox is empty,
+     * skipping a row whose recipient cannot be read.
+     * @param value - Stored recipient identity as the driver returned it.
+     * @param column - Column named in the diagnostic.
+     * @param rowKey - Identifies the row the value came from.
+     */
+    #syncSkippingUnreadable(value, column, rowKey) {
+        const agentId = this.#readableAgentId(value, column, rowKey);
+        if (agentId !== null)
+            this.#syncRedelivery(agentId);
+    }
+    #allocateTrafficPosition() {
+        const result = this.#write("insert into traffic_positions default values");
+        const position = Number(result.lastInsertRowid);
+        if (!Number.isSafeInteger(position) || position < 1) {
+            throw new ProtocolError("validation_failed", "Could not allocate operator traffic position");
+        }
+        return position;
+    }
+    #activeAttachment(sessionId, fencingToken, epoch) {
+        if (epoch !== this.#epoch)
+            throw new ProtocolError("expired", "Broker epoch changed; re-attach required");
+        const row = this.#db
+            .prepare("select * from sessions where id = ? and fencing_token = ? and active = 1")
+            .get(sessionId, fencingToken);
+        if (!row || Number(row.expires_at) <= this.#now())
+            throw new ProtocolError("expired", "Attachment expired; re-attach required");
+        // The row's own recorded epoch fences it independent of what the caller claims, matching
+        // resolveSession: a caller presenting the current epoch by other means cannot renew a row minted
+        // under a superseded one.
+        if (String(row.epoch) !== this.#epoch)
+            throw new ProtocolError("expired", "Broker epoch changed; re-attach required");
+        return row;
+    }
+    #agent(agentId) {
+        const row = this.#db.prepare("select * from agents where id = ? and state != 'reaped'").get(agentId);
+        if (!row)
+            throw new ProtocolError("unknown_recipient", "Unknown agent");
+        return row;
+    }
+    #activeAgent(agentId) {
+        const row = this.#db.prepare("select * from agents where id = ? and state = 'active'").get(agentId);
+        if (!row)
+            throw new ProtocolError("conflict", "Agent identity is not active");
+        return row;
+    }
+    #message(messageId) {
+        const row = this.#db.prepare("select * from messages where id = ?").get(messageId);
+        if (!row)
+            throw new ProtocolError("validation_failed", "Unknown message");
+        return {
+            state: readStoredEnum(row.state, MESSAGE_STATES, "messages.state"),
+            to: readStoredAgentId(row.recipient_id, "messages.recipient_id"),
+            // Null rather than a throw: only the sender check in `status()` reads it, and a sender that
+            // cannot be identified fails that check, which is the same answer as not being the sender.
+            from: isAgentId(row.sender_id) ? row.sender_id : null,
+        };
+    }
+    /**
+     * Reject an ephemeral recipient no process is answering for.
+     *
+     * An ephemeral identity is auto-named and anonymous: nobody addresses one intending it to be read
+     * after the conversation behind it has gone. Its row outlives its attachment only so a resume can
+     * rejoin it, so accepting a send against a detached one queues a message that is never claimed.
+     * A named identity is the opposite case and keeps its durable inbox while it is offline.
+     *
+     * An archived identity, of either kind, is accepted: the operator put it away deliberately and
+     * attaching takes it back out, so what is queued for it waits until then or until it is reaped.
+     * @param agentId - Resolved recipient identity.
+     */
+    #assertRoutableRecipient(agentId) {
+        const agent = this.#db
+            .prepare("select registration_ephemeral, archived_at from agents where id = ?")
+            .get(agentId);
+        if (!agent || Number(agent.registration_ephemeral) !== 1 || typeof agent.archived_at === "number")
+            return;
+        const attached = this.#db.prepare("select 1 as present from sessions where agent_id = ? limit 1").get(agentId);
+        // An identity that has never attached is still starting up; only a lapsed one is a dead end.
+        if (!attached)
+            return;
+        const live = this.#db
+            .prepare("select 1 as present from sessions where agent_id = ? and active = 1 and expires_at > ? limit 1")
+            .get(agentId, this.#now());
+        if (!live)
+            throw new ProtocolError("unknown_recipient", "Recipient session has ended");
+    }
+    #resolveRecipientIdentity(workspaceId, recipient) {
+        if (isDirectAgentAddress(recipient)) {
+            const row = this.#db.prepare("select id from agents where id = ? and state != 'reaped'").get(recipient);
+            if (row)
+                return readStoredAgentId(row.id, "agents.id");
+            throw new ProtocolError("unknown_recipient", "Unknown recipient");
+        }
+        // A parser rejection and a name that resolves to nobody are the same routing failure to the sender.
+        let address;
+        try {
+            address = parseAgentAddress(recipient);
+        }
+        catch {
+            throw new ProtocolError("unknown_recipient", "Unknown recipient");
+        }
+        const targetWorkspace = address.workspace === null ? workspaceId : this.#workspaceForName(address.workspace, this.workspaceNames());
+        const current = this.#db
+            .prepare("select id from agents where workspace_id = ? and registration_name = ? and state != 'reaped'")
+            .get(targetWorkspace, address.sessionName);
+        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'")
+            .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`);
+        }
+        throw new ProtocolError("unknown_recipient", "Unknown recipient");
+    }
+    /**
+     * Name every registered workspace by the shortest trailing path segments unique across the broker.
+     * @returns - Addressable workspace name for each workspace identity.
+     */
+    workspaceNames() {
+        const rows = this.#db.prepare("select id, path from workspaces order by path").all();
+        return uniquePathNames(rows.map((row) => ({ id: String(row.id), path: String(row.path) })));
+    }
+    #agentAddress(agentId, workspaces) {
+        const row = this.#db.prepare("select registration_name, workspace_id from agents where id = ?").get(agentId);
+        if (!row)
+            return agentId;
+        const alias = row.registration_name;
+        if (typeof alias !== "string" || alias === "")
+            return agentId;
+        const workspace = workspaces.get(String(row.workspace_id)) ?? String(row.workspace_id);
+        return `${normalizeAlias(alias)}@${workspace}`;
+    }
+    #workspaceForName(name, names) {
+        for (const [workspaceId, workspaceName] of names) {
+            if (workspaceName === name)
+                return workspaceId;
+        }
+        throw new ProtocolError("unknown_recipient", `Unknown workspace ${name}`);
+    }
+    #reapExpiredEphemeralAgents() {
+        this.#transaction(() => {
+            const expiredAt = this.#now();
+            const expired = this.#db
+                .prepare("select a.id from agents a where a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 1 and a.session_key is null and exists (select 1 from sessions s where s.agent_id = a.id) and not exists (select 1 from sessions s where s.agent_id = a.id and s.active = 1 and s.expires_at > ?)")
+                .all(expiredAt);
+            this.#lifecycleSynchronization?.checkpoint("ephemeral_expiry_scanned");
+            for (const row of expired)
+                this.#reapAgent(String(row.id));
+            const unattached = this.#db
+                .prepare(`select a.id from agents a where ${UNATTACHED_EPHEMERAL_LAPSED_SQL}`)
+                .all(expiredAt);
+            for (const row of unattached)
+                this.#reapAgent(String(row.id));
+        });
+        this.#reapAbandonedResumableAgents();
+        this.#archiveDetachedNamedAgents();
+        this.#reapExpiredArchivedAgents();
+    }
+    /**
+     * Retire one identity: it stops resolving, its attachments and reserved names are released, any
+     * reservation nobody consumed is discarded, and the messages still waiting for it are dead-lettered.
+     *
+     * Reaping settles the inbox at once rather than leaving it to the redelivery give-up budget, and
+     * deletes the wakes row so no further wake targets a reaped identity. The archive mark is cleared:
+     * the identity is no longer archived, it is gone.
+     * @param agentId - Identity being retired.
+     */
+    #reapAgent(agentId) {
+        this.#write("update agents set state = 'reaped', archived_at = null where id = ?", agentId);
+        this.#write("update sessions set active = 0 where agent_id = ?", agentId);
+        this.#write("delete from alias_history where agent_id = ?", agentId);
+        this.#write("delete from reservations where agent_id = ? and consumed_at is null", agentId);
+        this.#deadLetter(this.#db
+            .prepare("select id from messages where recipient_id = ? and state in ('queued','claimed') order by sequence")
+            .all(agentId), "dead-lettered — recipient was reaped");
+        this.#write("delete from wakes where agent_id = ?", agentId);
+    }
+    /**
+     * Retire unnamed resumable identities whose conversation never came back. Detachment alone never
+     * reaps one, because a person resumes a conversation long after its process stopped answering; it
+     * is held for the retention window, or for the shorter unused window when it never sent or
+     * received a message. A named identity is archived instead, by `#archiveDetachedNamedAgents`, and
+     * an archived identity is not measured here; `#reapExpiredArchivedAgents` owns it.
+     */
+    #reapAbandonedResumableAgents() {
+        this.#transaction(() => {
+            const unnamedResumable = "a.state = 'active' and a.archived_at is null and a.session_key is not null and a.registration_ephemeral = 1";
+            const abandoned = this.#db
+                .prepare(`select a.id from agents a where ${unnamedResumable} and ${DETACHED_SINCE_SQL}`)
+                .all(this.#now(), this.#now() - this.#resumableRetentionMs);
+            const unused = this.#db
+                .prepare(`select a.id from agents a where ${unnamedResumable} and ${DETACHED_SINCE_SQL} and not exists (${MESSAGE_USING_AGENT_SQL})`)
+                .all(this.#now(), this.#now() - this.#unusedResumableRetentionMs);
+            this.#lifecycleSynchronization?.checkpoint("resumable_abandonment_scanned");
+            for (const row of [...abandoned, ...unused])
+                this.#reapAgent(String(row.id));
+        });
+    }
+    /**
+     * Archive named identities detached for longer than the named archive window. The identity keeps
+     * its name, conversation key, and inbox, and its attachments are left as they are, so a holder
+     * that resumes one, or a conversation that attaches again, un-archives it.
+     */
+    #archiveDetachedNamedAgents() {
+        this.#transaction(() => {
+            const detached = this.#db
+                .prepare(`select a.id from agents a where a.state = 'active' and a.archived_at is null and a.registration_ephemeral = 0 and ${DETACHED_SINCE_SQL}`)
+                .all(this.#now(), this.#now() - this.#namedArchiveAfterMs);
+            for (const row of detached)
+                this.#write("update agents set archived_at = ? where id = ?", this.#now(), String(row.id));
+        });
+    }
+    /**
+     * Retire archived identities whose archive window has run out.
+     *
+     * One rule for every identity, ephemeral or named, resumable or not, and however it was archived:
+     * an archived identity is kept for the archive window measured from the moment it was archived,
+     * and attaching within it un-archives the identity.
+     */
+    #reapExpiredArchivedAgents() {
+        this.#transaction(() => {
+            const archivedBefore = this.#now() - this.#archivedRetentionMs;
+            const expired = this.#db
+                .prepare("select id from agents where state = 'active' and archived_at is not null and archived_at <= ?")
+                .all(archivedBefore);
+            for (const row of expired)
+                this.#reapAgent(String(row.id));
+        });
+    }
+}
+/**
+ * Render a millisecond duration as an operator-facing label, in the largest unit that divides it
+ * evenly so a configured value round-trips exactly instead of losing precision to rounding.
+ * @param ms - Duration in milliseconds.
+ * @returns - Duration suffixed with its unit (h, m, s, or ms).
+ */
+function formatDurationLabel(ms) {
+    if (ms % 3_600_000 === 0)
+        return `${String(ms / 3_600_000)}h`;
+    if (ms % 60_000 === 0)
+        return `${String(ms / 60_000)}m`;
+    if (ms % 1_000 === 0)
+        return `${String(ms / 1_000)}s`;
+    return `${String(ms)}ms`;
+}
+/** Ordinals tried before a generated default alias falls back to an identity-derived name. */
+const IMPLEMENTATION_ALIAS_LIMIT = 512;
+function defaultAgentSessionName(seed) {
+    return `agent-${createHash("sha256").update(seed).digest("hex").slice(0, 12)}`;
+}
+/**
+ * Name the table one write statement changes.
+ * @param sql - Single insert, update, or delete statement.
+ * @returns - Table the statement writes to.
+ */
+function mutatedTable(sql) {
+    const match = /^\s*(?:insert(?:\s+or\s+\w+)?\s+into|update|delete\s+from)\s+([A-Za-z_][A-Za-z0-9_]*)/iu.exec(sql);
+    if (!match?.[1])
+        throw new Error(`Broker write statement names no table: ${sql}`);
+    return match[1];
+}
+function contentType(body) {
+    return typeof body === "string" ? "text" : "json";
+}
+function routingEvent(routing, to) {
+    switch (routing.outcome) {
+        case "direct":
+            return { type: "direct", text: "direct id" };
+        case "resolved":
+            return { type: "alias_resolved", text: `alias resolved to ${to}` };
+        case "broadcast":
+            return { type: "broadcast", text: `broadcast to ${routing.addressedTo}` };
+    }
+}