@timqi/pier 0.0.29 → 0.1.1

package/dist/core/router.js

@@ -7,37 +7,25 @@ import { SenderPrefix, withPrefix } from "./identity.js";
 import { decide } from "./queue.js";
 import { splitReply } from "./reply.js";
 const log = logger("core");
-/** How long a session may sit idle in memory before it is let go. Generous on
- *  purpose: eviction is a memory measure, and re-opening one costs a Pi
- *  resume plus the transcript being read back. */
+/** Generous: eviction is a memory measure, and re-opening costs a Pi resume
+ *  plus a transcript read. */
 const IDLE_TTL_MS = 30 * 60_000;
-/** Sweep interval. Nothing here is urgent, so it is coarse. */
 const SWEEP_MS = 5 * 60_000;
 /** An error goes into a chat window, so it is trimmed to something readable. */
 const truncate = (message) => message.length > 600 ? `${message.slice(0, 600)}…` : message;
-/** What a chat window gets of a system input, and how much it may stand in
- *  for. A task callback carries up to 8000 characters of result text
- *  (tasks/callbacks.ts). */
+/** What a chat window gets of a system input; a task callback carries up to
+ *  8000 characters of result text (tasks/callbacks.ts). */
 const NOTE_CHARS = 200;
 const NOTE_LINES = 4;
-/**
- * The head of a system input plus a count of what was left out.
- *
- * A note is *context* for the turn it precedes, not the message: pasted whole,
- * a run result buries the conversation it was meant to explain — and on IM
- * that is the one surface with no way to collapse it. The hub, the web
- * timeline and the Pi transcript keep every character.
- *
- * Cut on a line boundary and then on a word, so the head reads as text rather
- * than as a string that ran out.
- */
+/** A note is context for the turn it precedes, not the message: pasted whole,
+ *  a run result buries the chat on IM, which cannot collapse it. The hub and
+ *  the transcript keep every character. */
 function digest(text) {
     const body = text.trimEnd();
     let head = body.split("\n").slice(0, NOTE_LINES).join("\n");
     if (head.length > NOTE_CHARS) {
         const capped = head.slice(0, NOTE_CHARS);
-        // Only a boundary in the second half is worth taking: cutting further back
-        // than that loses more than the ragged edge was costing.
+        // A boundary before the midpoint loses more than the ragged edge costs.
         const boundary = Math.max(capped.lastIndexOf("\n"), capped.lastIndexOf(" "));
         head = capped.slice(0, boundary > NOTE_CHARS / 2 ? boundary : NOTE_CHARS);
     }
@@ -50,10 +38,8 @@ function digest(text) {
 function keyOf(key) {
     return `${key.channelId}:${key.conversationId}`;
 }
-/** `web:<id>` and `task:<id>` are two names for one session id, and neither is
- *  a chat — no Channel is registered under them. So they share a lock in
- *  `ensure`, and which of the two a session records costs nothing but the
- *  answer to "what is it answering". */
+/** `web:<id>` and `task:<id>` name one session id and neither is a chat — no
+ *  Channel is registered under them — so they share a lock in `ensure`. */
 const isAlias = (key) => key.channelId === "web" || key.channelId === "task";
 export class QueueOperationError extends Error {
     reason;
@@ -65,55 +51,47 @@ export class QueueOperationError extends Error {
 export class Router {
     hub;
     resolve;
+    sessionIdOf;
     byKey = new Map();
     bySession = new Map();
-    /** Resolves in flight, so two surfaces asking at once share one session
-     *  object instead of opening a second Pi runtime on the same transcript.
-     *  Web and task keys collapse to the session id they both name. */
+    /** Resolves in flight: two surfaces asking at once must share one session
+     *  object, not open a second Pi runtime on the same transcript. */
     opening = new Map();
     channels = new Map();
     /** Who each session last heard from, so a header costs tokens only on news. */
     senders = new SenderPrefix();
-    /** Set by a graceful restart (src/drain.ts). Usually never unset, because
-     *  the process exits when the drain ends — `endDrain` exists for the one
-     *  caller that drains *speculatively* and may not get to exit. */
+    /** Set by a graceful restart (src/drain.ts); `endDrain` is for the caller
+     *  that drains speculatively and may not get to exit. */
     draining = false;
     spokenTo;
     constructor(hub, 
     /** Create or resume the session owning a conversation (wired in main.ts). */
-    resolve) {
+    resolve, 
+    /** The durable chat → session mapping, read before opening: a chat and the
+     *  workbench asking for one transcript must share one lock and one object.
+     *  Undefined for a chat that has none yet. */
+    sessionIdOf = () => undefined) {
         this.hub = hub;
         this.resolve = resolve;
+        this.sessionIdOf = sessionIdOf;
     }
     registerChannel(channel) {
         this.channels.set(channel.id, channel);
     }
-    /** Told which session a human just spoke to — every message from a chat or
-     *  the workbench passes through `dispatch`, and nothing a task or a subagent
-     *  starts does. Registered rather than a constructor argument: the one
-     *  listener is the rail's working set (web/session-state.ts), built with the
-     *  web surface long after the router. */
+    /** Fires for humans only: chats and the workbench pass through `dispatch`,
+     *  tasks and subagents do not. Registered late because the listener
+     *  (web/session-state.ts) is built with the web surface. */
     onSpokenTo(listener) {
         this.spokenTo = listener;
     }
-    /**
-     * Tell the conversation something went wrong, then the event stream.
-     *
-     * Applies to every channel, because the failure mode is the same everywhere:
-     * an IM user watching the eyes come off with no reply cannot tell a crash
-     * from a deliberate silence, and the operator cannot debug what they never
-     * saw. The web reads errors off the hub already, so only a registered channel
-     * gets a note; `notify` is used rather than `send` so it is never mistaken
-     * for an assistant turn.
-     */
+    /** A failure reaches the chat as well as the hub (§5): on IM, silence is
+     *  indistinguishable from a crash. `notify`, not `send`, so it is never
+     *  mistaken for an assistant turn. */
     report(sessionId, key, message) {
-        // Three surfaces, one failure: the chat that is waiting, the web timeline,
-        // and the log the operator greps once it is reported to them.
         log.error(`${keyOf(key)} session ${sessionId}: ${message}`);
         this.hub.emit(sessionId, { type: "error", message });
         const channel = this.channels.get(key.channelId);
-        // Best-effort and never recursive: if telling the chat also fails, the hub
-        // already has the original.
+        // Never recursive: if telling the chat also fails, the hub has the original.
         channel?.notify(key.conversationId, { text: truncate(message), origin: { kind: "error" } })
             .catch((err) => {
             log.error(`could not report the failure to ${key.channelId}`, err);
@@ -123,13 +101,8 @@ export class Router {
             });
         });
     }
-    /**
-     * Report something that happened *to* a session rather than in it: a task
-     * result that could not be delivered, say. Its conversation is told when one
-     * is attached — an agent that was promised an answer and a human watching the
-     * same thread learn it is not coming from the same place they were waiting.
-     * Otherwise the hub carries it for the web timeline.
-     */
+    /** Something that happened *to* a session (an undeliverable task result): the
+     *  attached conversation is told where it was waiting, else the hub carries it. */
     reportTo(sessionId, message) {
         const key = this.conversationOf(sessionId);
         if (key)
@@ -137,36 +110,32 @@ export class Router {
         else
             this.hub.emit(sessionId, { type: "error", message });
     }
-    /**
-     * Let go of every session that has been idle too long, so a process serving
-     * IM threads and task runs for weeks does not hold one live Pi runtime per
-     * conversation it ever saw. Only the in-memory attachment goes: the durable
-     * conversation → session mapping stays, so the next message resumes the very
-     * same transcript (channels/conversations.ts).
-     *
-     * Skipped for anything that would notice: a streaming turn, and a session
-     * someone is still watching over SSE.
-     *
-     * `includeWatched` is the one caller that may take a watched session too:
-     * configuration a session reads only when it opens has just changed, and the
-     * session most likely to need it is the one open in the tab that changed it.
-     * A turn in flight is still never touched — the exemption that stands is the
-     * one about interrupting work, not the one about being looked at.
-     */
+    /** Only the in-memory attachment goes; the durable mapping
+     *  (channels/conversations.ts) resumes the same transcript on the next message.
+     *  `includeWatched` is for config a session reads only at open: the session
+     *  most likely to need it is the one open in the tab that changed it. A
+     *  streaming turn is never evicted, nor a session holding queued messages:
+     *  Pi's queue lives only in the runtime, so disposing it would drop them. */
     async evictIdle(ttlMs = IDLE_TTL_MS, now = Date.now(), { includeWatched = false } = {}) {
         let evicted = 0;
-        // Snapshot on purpose: this loop awaits dispose(), so another turn may
-        // attach or drop a session while it is suspended.
+        // Snapshot: the loop awaits dispose(), and the map may change meanwhile.
         // oxlint-disable-next-line unicorn/no-useless-spread
         for (const [id, attached] of [...this.bySession]) {
-            if (attached.session.state === "streaming")
-                continue;
             if (this.queueOperations.has(id) || this.recoveries.get(id)?.some((b) => b.status === "submitting"))
                 continue;
             if (!includeWatched && this.hub.hasSubscribers(id))
                 continue;
             if (now - attached.activeAt < ttlMs)
                 continue;
+            const touched = attached.touched;
+            const queued = await attached.session.pendingQueue();
+            // Everything re-read after the await: a dispatch, a queue operation or a
+            // replacement may have landed meanwhile, and a prompt already accepted
+            // must not run against a disposed session.
+            if (this.bySession.get(id) !== attached || attached.touched !== touched || this.queueOperations.has(id))
+                continue;
+            if (attached.session.state === "streaming" || queued.steering.length || queued.followUp.length)
+                continue;
             this.bySession.delete(id);
             this.forgetKeys(attached.session);
             attached.unsubscribe();
@@ -174,8 +143,7 @@ export class Router {
             this.hub.dropReplay(id);
             evicted += 1;
             log.info(`evicted idle session ${id} (${keyOf(attached.key)})`);
-            // Best-effort: a runtime that will not shut down must not keep the
-            // sweeper from releasing the rest.
+            // A runtime that will not shut down must not block releasing the rest.
             await attached.session.dispose().catch((err) => log.error(`disposing session ${id} failed`, err));
         }
         return evicted;
@@ -199,18 +167,12 @@ export class Router {
     modelOf(sessionId) {
         return this.bySession.get(sessionId)?.session.model;
     }
-    /**
-     * Which conversation a session is answering, if any. The inverse of
-     * `sessionOf`, and what lets a tool act on "here" — an agent reached through
-     * a Slack thread otherwise has no way to name the thread it is replying in.
-     * A task or subagent session is attached to nothing and answers undefined.
-     */
+    /** Inverse of `sessionOf`; lets a tool act on "here". A task or subagent
+     *  session is attached to nothing and answers undefined. */
     conversationOf(sessionId) {
         return this.bySession.get(sessionId)?.key;
     }
-    /** Every key that points at this session object. One session can be reached
-     *  under more than one — `web:<id>` and `task:<id>` name the same session —
-     *  and a key left behind hands out a session that is no longer live. */
+    /** Every alias: a key left behind hands out a session that is no longer live. */
     forgetKeys(session) {
         for (const [key, held] of this.byKey)
             if (held === session)
@@ -225,92 +187,109 @@ export class Router {
             return;
         }
         if (existing) {
-            // Two live objects on one transcript: both would write it and both would
-            // answer the chat. Single-flight `ensure` closes the race that makes
-            // this, so reaching here is a bug worth seeing — the replaced one is
-            // silenced and unreachable, rather than left answering under aliases
-            // nobody knows are stale.
+            // Two live objects on one transcript would both write it and both answer
+            // the chat; single-flight `ensure` should make this unreachable.
             log.warn(`session ${session.id} replaced while attached to ${keyOf(existing.key)}`);
             existing.unsubscribe();
             this.forgetKeys(existing.session);
+            void existing.session.dispose().catch((err) => log.error(`disposing replaced session ${session.id} failed`, err));
         }
         this.byKey.set(keyOf(key), session);
         log.info(`attached ${keyOf(key)} → session ${session.id}`);
-        const unsubscribe = session.subscribe((payload) => {
-            this.hub.emit(session.id, payload);
-            // Run state is workspace-visible: every client's session list shows it.
-            if (payload.type === "state") {
-                const attached = this.bySession.get(session.id);
-                // Every turn passes through here, so this is also where a session
-                // proves to the sweeper that it is still in use.
-                if (attached)
-                    attached.stateSince = attached.activeAt = Date.now();
-                this.hub.emitWorkspace({
-                    type: "session-state",
-                    sessionId: session.id,
-                    state: payload.state,
-                });
-            }
-            // An error the session itself reported (a tool that threw, a model
-            // refusal, a lost connection). Without this it lands only in the web
-            // timeline and the IM side goes quiet for no visible reason.
-            if (payload.type === "error") {
-                log.error(`${keyOf(key)} session ${session.id} reported: ${payload.message}`);
-                const channel = this.channels.get(key.channelId);
-                channel?.notify(key.conversationId, {
-                    text: truncate(payload.message),
-                    origin: { kind: "error" },
-                }).catch((err) => log.error(`notify ${key.channelId} failed`, err));
-            }
-            // A system input is context the chat did not see being typed. It goes
-            // out before the turn it triggers, so the answer has a visible cause.
-            if (payload.type === "system-input") {
-                const channel = this.channels.get(key.channelId);
-                // A digest, not the input: the hub emit above is what carries it whole.
-                channel?.notify(key.conversationId, { text: digest(payload.text), origin: payload.origin })
-                    .catch((err) => {
-                    log.error(`notify ${key.channelId} failed`, err);
-                    this.hub.emit(session.id, {
-                        type: "error",
-                        message: `notify ${key.channelId} failed: ${String(err)}`,
-                    });
-                });
-            }
-            // A queued message with no turn left to deliver it. `decide` reads the
-            // state once, so a steer chosen against a turn that ends before the call
-            // lands sits in Pi's queue until some *later* turn reads it — on IM that
-            // is indistinguishable from the message never arriving (§5b). Pi drains
-            // its own queues up to the agent_end handler, so a non-empty queue on an
-            // idle session is exactly the message that missed that window.
-            if (payload.type === "queue-state" && (payload.steering.length || payload.followUp.length)) {
-                this.promoteQueued(session);
-            }
-            // Every turn-end reaches the channel, empty text included: an adapter's
-            // per-turn UI (Telegram's 👀 receipts) is retired here, and a turn that
-            // settled with nothing to say still has to settle.
-            if (payload.type === "turn-end") {
-                log.info(`turn end ${keyOf(key)} session ${session.id}: ${String(payload.text.length)} chars`);
-                const channel = this.channels.get(key.channelId);
-                if (channel) {
-                    channel.send(key.conversationId, splitReply(payload.text, payload.meta)).catch((err) => {
-                        this.report(session.id, key, `outbound to ${key.channelId} failed: ${String(err)}`);
-                    });
-                }
-            }
-        });
-        this.bySession.set(session.id, {
+        // Delivery reads `attached.key` live: a chat attaching after the workbench
+        // opened the session takes over (`reached`), and the closure must follow.
+        const attached = {
             session,
             key,
             stateSince: Date.now(),
             activeAt: Date.now(),
-            unsubscribe,
+            touched: 0,
+            unsubscribe: session.subscribe((payload) => {
+                const key = attached.key;
+                this.hub.emit(session.id, payload);
+                if (payload.type === "state") {
+                    // Every turn passes here, so it also proves liveness to the sweeper.
+                    attached.stateSince = attached.activeAt = Date.now();
+                    attached.touched += 1;
+                    this.hub.emitWorkspace({
+                        type: "session-state",
+                        sessionId: session.id,
+                        state: payload.state,
+                    });
+                }
+                if (payload.type === "renamed")
+                    this.hub.emitWorkspace({ type: "sessions-changed" });
+                // Without this a session-reported error lands only in the web timeline
+                // and the IM side goes quiet for no visible reason.
+                if (payload.type === "error") {
+                    log.error(`${keyOf(key)} session ${session.id} reported: ${payload.message}`);
+                    const channel = this.channels.get(key.channelId);
+                    channel?.notify(key.conversationId, {
+                        text: truncate(payload.message),
+                        origin: { kind: "error" },
+                    }).catch((err) => log.error(`notify ${key.channelId} failed`, err));
+                }
+                // Context the chat did not see typed goes out before the turn it
+                // triggers, so the answer has a visible cause. The hub carries it whole.
+                if (payload.type === "system-input") {
+                    const channel = this.channels.get(key.channelId);
+                    channel?.notify(key.conversationId, { text: digest(payload.text), origin: payload.origin })
+                        .catch((err) => {
+                        log.error(`notify ${key.channelId} failed`, err);
+                        this.hub.emit(session.id, {
+                            type: "error",
+                            message: `notify ${key.channelId} failed: ${String(err)}`,
+                        });
+                    });
+                }
+                // A steer chosen against a turn that ended before the call landed sits in
+                // Pi's queue until some later turn — on IM, a message that never arrived
+                // (§5). A non-empty queue on an idle session is exactly that case.
+                if (payload.type === "queue-state" && (payload.steering.length || payload.followUp.length)) {
+                    this.promoteQueued(session);
+                }
+                // Empty text included: adapters retire per-turn UI (👀 receipts) on it.
+                if (payload.type === "turn-end") {
+                    log.info(`turn end ${keyOf(key)} session ${session.id}: ${String(payload.text.length)} chars`);
+                    const channel = this.channels.get(key.channelId);
+                    if (channel) {
+                        const reply = splitReply(payload.text, payload.meta);
+                        this.deliver(session, key, () => channel.send(key.conversationId, reply))
+                            .catch((err) => {
+                            this.report(session.id, key, `outbound to ${key.channelId} failed: ${String(err)}`);
+                        });
+                    }
+                }
+            }),
+        };
+        this.bySession.set(session.id, attached);
+    }
+    /** An adapter's send is several platform calls (chunks, then attachments),
+     *  so two answers left to overlap interleave in the chat. Per conversation:
+     *  a slow chat may not hold up another. Also what `busy` counts as still
+     *  sending: a finished turn is not delivered until the adapter says so. */
+    delivering = new Map();
+    deliver(session, key, send) {
+        const id = keyOf(key);
+        const pending = this.delivering.get(id)?.settled;
+        // The async wrapper turns a synchronous throw into this reply's rejection.
+        const done = pending ? pending.then(send) : (async () => send())();
+        // A rejection is the caller's to report; inherited, it would fail every
+        // later reply to this conversation.
+        const settled = done.catch(() => { });
+        this.delivering.set(id, { session, key, settled });
+        // Only the tail clears the slot — a newer reply owns it by then.
+        void settled.then(() => {
+            if (this.delivering.get(id)?.settled === settled)
+                this.delivering.delete(id);
         });
+        return done;
     }
     queueOperations = new Set();
     promotionRequested = new Set();
     recoveries = new Map();
-    // Keep the latest failed batch ID so a clear cannot erase a newer rejection
-    // that arrived while it awaited the backend. ACK affects only the copy.
+    // Latest failed batch id, so a clear cannot erase a newer rejection that
+    // arrived while it awaited the backend.
     uncertaintyHeld = new Map();
     queueUncertain(sessionId) {
         return this.uncertaintyHeld.has(sessionId);
@@ -336,8 +315,8 @@ export class Router {
         this.promotionRequested.delete(sessionId);
         this.recoveryChanged(sessionId);
     }
-    /** Only queue mutation owns this lock. A model turn owns its batch, not the
-     *  next queue: manual controls remain available while that turn runs. */
+    /** Only queue mutation holds this lock; a running turn does not, so manual
+     *  controls stay available while it runs. */
     async useQueue(sessionId, action, key = { channelId: "web", conversationId: sessionId }) {
         if (this.queueOperations.has(sessionId))
             throw new QueueOperationError("busy", "Queue operation in progress");
@@ -400,8 +379,8 @@ export class Router {
                     if (mode === "restart")
                         await this.abort(sessionId);
                     this.checkQueueDrain();
-                    // Already headed at original dispatch. Calling dispatch again would
-                    // discard rejection and could attribute these words to the operator.
+                    // Not via dispatch: the text was headed at original dispatch, and a
+                    // second pass could attribute these words to the operator.
                     invoked = true;
                     const submitted = mode === "steer" && session.state === "streaming"
                         ? session.steer(text) : session.prompt(text);
@@ -424,16 +403,9 @@ export class Router {
             throw err;
         }
     }
-    /**
-     * Turn a stranded queue into the turn it was waiting for. Not routed through
-     * `dispatch`: the text was prefixed when it was first dispatched
-     * (identity.ts), and sending it back through would head it a second time.
-     *
-     * Only ever reached from a queue-state event, never from a turn ending: Pi
-     * leaves the queue alone on `abort()`, so promoting on idle would make /stop
-     * start the very turn it was asked to stop. Recovering *those* messages stays
-     * the web's recall route, which hands them back to the composer.
-     */
+    /** Only from a queue-state event, never from a turn ending: Pi leaves the
+     *  queue alone on `abort()`, so promoting on idle would make /stop start the
+     *  very turn it was asked to stop. */
     promoteQueued(session) {
         if (session.state !== "idle")
             return;
@@ -445,7 +417,6 @@ export class Router {
         queueMicrotask(() => {
             if (!this.promotionRequested.has(sessionId) || this.queueOperations.has(sessionId))
                 return;
-            // A queue event followed by rejection might describe the same input.
             // Retained failures require a human decision, not an automatic resend.
             if (this.queueUncertain(sessionId) || this.recoveries.get(sessionId)?.length)
                 return;
@@ -468,17 +439,9 @@ export class Router {
             this.promotionRequested.delete(sessionId);
         }
     }
-    /**
-     * Drop what this session was told about who is speaking, so the next message
-     * carries a full header again.
-     *
-     * For the surfaces that take a prefixed message back *out* of the context it
-     * was counted into — a recalled queue, a rewound turn. The tracker's whole
-     * job is "the model has already been told" (identity.ts), and a header that
-     * never reached the model, or reached it and was then rewound away, makes
-     * every later message from that speaker unattributed in a group chat. One
-     * redundant header is the same price eviction already pays.
-     */
+    /** For surfaces that take a prefixed message back out of the context it was
+     *  counted into (recalled queue, rewound turn): the tracker means "the model
+     *  has been told" (identity.ts), and here it has not. */
     forgetSender(sessionId) {
         this.senders.forget(sessionId);
     }
@@ -486,21 +449,17 @@ export class Router {
     beginDrain() {
         this.draining = true;
     }
-    /** Take work again. The auto-updater closes the gate *before* handing over,
-     *  so a turn cannot slip in behind the idle check — and when the handover
-     *  never happens, a Pier left refusing every message forever would be a far
-     *  worse outcome than the race it was avoiding. */
+    /** The auto-updater closes the gate before handing over; when the handover
+     *  never happens, refusing every message forever is the worse outcome. */
     endDrain() {
         this.draining = false;
     }
-    /** For surfaces that mutate state before dispatching (the web's edit and
-     *  queue-deliver routes): ask first, so a refused dispatch cannot cost a
-     *  rewound transcript or a cleared queue. */
+    /** For surfaces that mutate state before dispatching (edit, queue-deliver):
+     *  a refused dispatch must not cost a rewound transcript or a cleared queue. */
     isDraining() {
         return this.draining;
     }
-    /** The drain gate, throwing. Told to the chat directly (5b): an adapter's
-     *  dispatch catch only logs, and the web caller gets the throw. */
+    /** Told to the chat directly (§5): an adapter's dispatch catch only logs. */
     refuseDraining(key) {
         const message = "Pier is restarting — this message was not taken; send it again in a moment.";
         this.channels.get(key.channelId)
@@ -508,17 +467,25 @@ export class Router {
             .catch((err) => log.error(`could not report the drain to ${key.channelId}`, err));
         throw new Error(message);
     }
-    /** Attached sessions still mid-turn — what the drain waits on, and what its
-     *  deadline snapshots into the ledger. */
+    /** Attached sessions still mid-turn, and conversations whose answer is still
+     *  going out (`sending`) — what the drain waits on, and what its deadline
+     *  writes into the ledger. */
     busy() {
-        return [...this.bySession.values()]
-            .filter((attached) => attached.session.state === "streaming")
-            .map((attached) => ({ session: attached.session, key: attached.key }));
-    }
-    /**
-     * The session already attached to a conversation, if any. Never creates one:
-     * a channel's stop or settings command must not be what opens a session.
-     */
+        return [
+            ...[...this.bySession.values()]
+                .filter((attached) => attached.session.state === "streaming")
+                .map((attached) => ({ session: attached.session, key: attached.key })),
+            ...[...this.delivering.values()]
+                .map(({ session, key }) => ({ session, key, sending: true })),
+        ];
+    }
+    /** Every attached session, mid-turn or not — what the drain snapshots: Pi's
+     *  queue lives only in the runtime, so an idle session's queued messages die
+     *  with the process just the same. */
+    attachedSessions() {
+        return [...this.bySession.values()].map(({ session, key }) => ({ session, key }));
+    }
+    /** Never creates one: a stop or settings command must not open a session. */
     sessionOf(key) {
         return this.byKey.get(keyOf(key));
     }
@@ -527,55 +494,46 @@ export class Router {
         if (session)
             await this.abort(session.id);
     }
-    /** Session owning a conversation, resolving and attaching it on first use. */
+    /** Session owning a conversation, resolving and attaching it on first use.
+     *  One object per session id whichever key asks first: an IM key is looked up
+     *  to its session id so it shares the lock with `web:`/`task:` aliases. */
     async ensure(key) {
         let session = this.byKey.get(keyOf(key));
-        // Web and task conversation ids are session ids. Reuse an attached
-        // instance so two surfaces never open the same Pi transcript twice.
-        if (!session && isAlias(key)) {
-            session = this.bySession.get(key.conversationId)?.session;
-            if (session)
-                this.byKey.set(keyOf(key), session);
-        }
+        if (session)
+            return this.reached(session, key);
+        const id = isAlias(key) ? key.conversationId : this.sessionIdOf(key);
+        session = id === undefined ? undefined : this.bySession.get(id)?.session;
         if (!session) {
-            // Aliases share one lock: web:<id> and task:<id> must not each open one.
-            const lock = isAlias(key) ? `session:${key.conversationId}` : keyOf(key);
+            const lock = id === undefined ? keyOf(key) : `session:${id}`;
             const inflight = this.opening.get(lock);
-            // A second caller rides the first one's resolve — which attaches before
-            // this continuation runs, having awaited it first — and registers its own
-            // key against the session that came back.
             if (inflight) {
                 session = await inflight;
-                this.byKey.set(keyOf(key), session);
-                return this.reached(session, key);
-            }
-            try {
-                // Inside the try: a resolver that throws synchronously is the same
-                // failure as one that rejects, and reports the same way.
-                const opening = this.resolve(key);
-                this.opening.set(lock, opening);
-                session = await opening;
             }
-            catch (err) {
-                this.unopened(key, err);
-                throw err;
-            }
-            finally {
-                this.opening.delete(lock);
+            else {
+                try {
+                    // Inside the try: a synchronous throw must report like a rejection.
+                    const opening = this.resolve(key);
+                    this.opening.set(lock, opening);
+                    session = await opening;
+                }
+                catch (err) {
+                    this.unopened(key, err);
+                    throw err;
+                }
+                finally {
+                    this.opening.delete(lock);
+                }
             }
-            this.attach(key, session);
         }
-        return this.reached(session, key);
+        // Attaches fresh, or adds this key to the object already attached.
+        this.attach(key, session);
+        return session;
     }
-    /** A session that would not open has no event stream of its own to report on
-     *  — unless its id is what we were asked for, which is what a web or task key
-     *  is. Otherwise the chat that is waiting is told directly. Callers still get
-     *  the rejection; this is only so the waiting side is not left with nothing. */
+    /** A web or task key names the session's own stream; an IM key names a chat
+     *  that is waiting. Either way the waiting side is not left with nothing. */
     unopened(key, err) {
         log.error(`could not open a session for ${keyOf(key)}`, err);
         const message = truncate(`could not open a session: ${String(err)}`);
-        // A web or task key names the session that would not open, so its own
-        // stream is where the waiting surface is looking; an IM key names a chat.
         if (key.channelId === "web" || key.channelId === "task") {
             this.reportTo(key.conversationId, message);
             return;
@@ -584,45 +542,36 @@ export class Router {
             ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
             .catch((e) => log.error(`could not report it to ${key.channelId}`, e));
     }
-    /** Reached for, so not idle — every surface that uses a session comes
-     *  through `ensure`, including the ones that only read it.
-     *
-     *  Also where a session learns which of its two aliases is current: a task
-     *  callback (tasks/outbox.ts) opens a workbench session under `task:<id>`
-     *  whenever nothing had it attached, and the key from that first attach used
-     *  to stand forever — so the workbench's own next turn was still "a task",
-     *  and the notification for it (web/push.ts) was never sent. A chat key is
-     *  never overwritten: that one is also where turn-ends are delivered. */
+    /** Also where a session learns which key is current: a task callback
+     *  attaches under `task:<id>`, and the workbench's next turn must not still
+     *  read as "a task" (web/push.ts). A chat outranks an alias — the workbench
+     *  may have opened the session, but its turns are answered in the chat — and
+     *  an alias never overwrites a chat. */
     reached(session, key) {
         const attached = this.bySession.get(session.id);
         if (!attached)
             return session;
         attached.activeAt = Date.now();
-        if (isAlias(key) && isAlias(attached.key))
+        attached.touched += 1;
+        if (!isAlias(key) || isAlias(attached.key))
             attached.key = key;
         return session;
     }
     async dispatch(msg) {
-        // Before ensure — a drain must not be what opens a session …
+        // Before ensure — a drain must not open a session — and after, for a
+        // dispatch that was inside a slow ensure when the gate closed.
         if (this.draining)
             this.refuseDraining(msg.key);
         const session = await this.ensure(msg.key);
-        // … and after — a dispatch that was inside a slow ensure when the gate
-        // closed must not start the turn the drain just declared finished with.
         if (this.draining)
             this.refuseDraining(msg.key);
         this.spokenTo?.(session.id);
         const { action, text } = decide(msg, session.state);
-        // A group chat is many people talking into one session; without a speaker
-        // line the agent cannot tell them apart or mention anyone back. Emitted
-        // only when the speaker or the clock says something new.
         const prompt = withPrefix(this.senders.next(session.id, msg.sender), text);
         log.debug(`${action} ${keyOf(msg.key)} → session ${session.id} (${String(prompt.length)} chars)`);
-        // Turn outcomes flow through the event stream; a rejected call surfaces
-        // there too, never as a thrown exception across the seam.
+        // A rejected call surfaces on the event stream, never as a throw across the seam.
         session[action](prompt).catch((err) => {
-            // The header was counted as delivered a line above; this message never
-            // arrived, so the next one from this speaker must carry it again.
+            // The header was counted as delivered above; it never arrived.
             this.senders.forget(session.id);
             this.report(session.id, msg.key, String(err));
         });