@edspencer/paddock 0.66.0 → 0.66.2

package/packages/server/dist/ws.js

@@ -1,9 +1,63 @@
+/**
+ * WebSocket chat transport.
+ *
+ * Protocol (the contract the frontend agent matches):
+ *
+ *   client -> server:
+ *     { type: "chat:send", payload: {
+ *         projectSlug: string,        // workspace key: a project slug, or "" for the root
+ *         sessionId: string | null,   // resume an existing chat, or null = new
+ *         message: string,
+ *         preloadContext?: boolean,   // new chat: prepend the project OVERVIEW.md
+ *         model?: string,             // per-chat model override (a known model id)
+ *     } }
+ *     { type: "chat:cancel", payload: { jobId } }   // optional: stop a running turn
+ *     { type: "ping" }
+ *
+ *   server -> client (all carry projectSlug + sessionId + jobId for routing):
+ *     { type: "chat:response",         payload: { projectSlug, sessionId, jobId, chunk } }
+ *     { type: "chat:tool_call",        payload: { projectSlug, sessionId, jobId,
+ *                                                  toolName, inputSummary, output,
+ *                                                  isError, durationMs } }
+ *     { type: "chat:message_boundary", payload: { projectSlug, sessionId, jobId } }
+ *     { type: "chat:complete",         payload: { projectSlug, sessionId, jobId, success, error?,
+ *                                                  model?, usage? } }
+ *         // model: the model the turn ran on (lastModel ?? effectiveModel).
+ *         // usage: { inputTokens, outputTokens, cacheReadTokens,
+ *         //          cacheCreationTokens, contextTokens, contextLimit } — the
+ *         //          LAST per-turn usage observed; omitted (with model) if none.
+ *         //          contextTokens = input + cacheRead + cacheCreation;
+ *         //          contextLimit  = getContextLimit(model). Stale-by-one-turn
+ *         //          by design (it reflects the just-completed turn's input).
+ *     { type: "chat:injected",         payload: { projectSlug, sessionId, jobId,
+ *                                                  sender, content, timestamp } }
+ *         // A machine-injected user turn (issue #290 Part 2): another chat
+ *         // send_message'd / a schedule fired into this session. Emitted so a
+ *         // client already viewing the recipient chat renders the injected user
+ *         // bubble LIVE (with its sender attribution) instead of only seeing the
+ *         // assistant reply and needing a refresh. `sender` is the MessageSender.
+ *     { type: "chat:error",            payload: { projectSlug, error } }
+ *     { type: "pong" }
+ *
+ * Streaming is wired for real via HerdctlService.chat()'s onMessage callback
+ * (the public trigger API supports it). The SDKMessage -> chat-event translation
+ * (assistant text deltas, message boundaries, and paired tool_use -> tool_result
+ * calls enriched with input summaries + wall-clock durations) is done by
+ * @herdctl/chat's `createSDKMessageHandler` — the shared, transport-agnostic
+ * translator every herdctl chat surface uses — so paddock no longer reimplements
+ * it (and as of @herdctl/chat@0.4.1 it pairs CLI tool results correctly, so the
+ * prior `normalizeForTranslator` shim is gone). We compose it with a tiny wrapper
+ * that also captures, from each raw SDK message, the session id and the per-turn
+ * usage + model (the translator only exposes text/boundary/tool events).
+ */
+import { randomUUID } from "node:crypto";
 import { createSDKMessageHandler } from "@herdctl/chat";
 import { extractSubagentLaunches, subagentLaunchFields, } from "./subagents.js";
 import { keeperAgentName, keeperSlugFromAgent, } from "./herdctl.js";
 import { consumeResumedTurn } from "./resume-drain.js";
 import { isKnownModel, getContextLimit, DEFAULT_MODEL, isKnownDriveMode, } from "./models.js";
 import { SessionHub } from "./session-hub.js";
+import { hasQueuedContent, partsOf, } from "./queued-message.js";
 import { resolveAttachmentsConfig } from "./attachments-config.js";
 import { wrapAttachments, inferAttachmentKind } from "./attachments-hint.js";
 import { sendFileServerDef, SEND_FILE_SERVER_KEY } from "./send-file-mcp.js";
@@ -40,6 +94,48 @@ const SERVER_PING_INTERVAL_MS = 30_000;
 // ripgrep/grep treat this file as binary and skip it during directory traversal
 // (silently, exit 1, indistinguishable from "no matches"). See issue #570.
 const KEY_SEP = "\u0000";
+/**
+ * Cap on a single queued message. The sidecar is rewritten in full on every queue
+ * mutation and the text is persisted verbatim, so an unbounded queue is a cheap
+ * way to bloat the data dir (a 2 MB `chat:set_queue` was accepted as-is). Well
+ * above any hand-typed follow-up, including a pasted stack trace.
+ */
+const MAX_QUEUED_CHARS = 100_000;
+/**
+ * The opaque identity of the client queue a `chat:set_queue` belongs to (#736).
+ *
+ * Whatever the client supplies is used for EQUALITY ONLY — never compared as a
+ * clock — so a skewed clock can't poison anything. A legacy client sends only the
+ * enqueue `ts`, which is folded into an id (still a perfectly good per-client
+ * identity, just no longer an ordering). A client that sends neither gets a fresh
+ * id, so its queue is always treated as new: with nothing stable to match on, the
+ * safe failure is to send the message rather than to discard it.
+ */
+function queueIdOf(payload) {
+    if (typeof payload.qid === "string" && payload.qid.length > 0)
+        return payload.qid;
+    if (typeof payload.ts === "number")
+        return `ts:${payload.ts}`;
+    return `anon:${randomUUID()}`;
+}
+/** Write one frame straight to a single socket, skipping a closed one. */
+function writeFrame(socket, msg) {
+    if (socket.readyState !== socket.OPEN)
+        return;
+    try {
+        socket.send(JSON.stringify(msg));
+    }
+    catch {
+        /* a socket that throws on send is effectively gone */
+    }
+}
+/**
+ * The identity of a slot as a whole (not of one contribution). Written by every
+ * `upsert`; synthesised for an entry an older server wrote without one.
+ */
+function slotVersion(m) {
+    return m.id ?? `legacy:${m.createdAtMs}`;
+}
 export function makeChatHandler(deps) {
     // ONE hub shared across every socket this handler serves: it tracks each
     // session's in-flight turn and fans its frames out to whichever socket(s) are
@@ -53,14 +149,61 @@ export function makeChatHandler(deps) {
     // double-send only survives a server restart, when the persisted store is
     // already empty anyway.
     //
-    // A message's identity is the (ts, text) TUPLE, not the timestamp alone (#628).
-    // The client deliberately KEEPS one enqueue ts when APPENDING to an existing
-    // queue (#245 stable identity), so "same ts, different text" is a genuinely new
-    // message — deduping on the ts alone silently destroyed the appended text.
-    // Timestamps are monotonic per session (a fresh queue stamps `Date.now()`), so
-    // anything strictly OLDER than `ts` is stale by construction and only the texts
-    // flushed AT `ts` need remembering — one bounded set per session.
+    // A queued message's identity is the (queue id, text) TUPLE, matched by
+    // EQUALITY (#628/#736). The client KEEPS one queue id when APPENDING to an
+    // existing queue (#245 stable identity), so "same id, different text" is a
+    // genuinely new message — deduping on the id alone would silently destroy the
+    // appended text.
+    //
+    // This used to be a (ts, text) tuple with an ORDERING rule on top: anything
+    // older than the last flushed ts was "stale by construction, timestamps being
+    // monotonic". They are monotonic within ONE client — but the ts came from
+    // whichever browser queued the message, so a single client with a fast clock
+    // parked the marker in the future and every subsequent queued message on that
+    // chat, from ANY client, was silently destroyed until wall-clock time caught up
+    // (#736). Equality assumes nothing about clocks, so the ordering rule is gone;
+    // in exchange every flushed id has to be remembered rather than just the newest.
+    //
+    // Bounded on both axes: MAX_FLUSHED_SESSIONS chats, MAX_FLUSHED_IDS ids each,
+    // oldest evicted first (insertion-ordered Maps). Overflow can only cost a rare
+    // double-send of a re-asserted message, the same exposure a server restart has.
     const lastFlushed = new Map();
+    const MAX_FLUSHED_SESSIONS = 512;
+    const MAX_FLUSHED_IDS = 32;
+    const MAX_FLUSHED_TEXTS = 8;
+    /** This session's flushed-parts ledger (id -> the texts flushed under it). */
+    const flushedLedger = (markerKey) => {
+        let m = lastFlushed.get(markerKey);
+        if (!m) {
+            m = new Map();
+            lastFlushed.set(markerKey, m);
+            if (lastFlushed.size > MAX_FLUSHED_SESSIONS) {
+                lastFlushed.delete(lastFlushed.keys().next().value);
+            }
+        }
+        return m;
+    };
+    // Slots we could NOT hand back to a composer on Stop, keyed `agent \0 sessionId`
+    // → the slot version that was parked. A parked message stays queued and visible,
+    // but no turn end auto-sends it: the user pressed Stop, and firing their
+    // follow-up later — behind whatever they type next — is the stranding this whole
+    // change exists to remove. Any real edit mints a new slot version, so the parked
+    // id simply stops matching and the message becomes ordinary again; a bare
+    // re-assert keeps the version and stays parked. Same bound as the ledger above.
+    const parked = new Map();
+    /** Record one flushed part, trimming the oldest entries past the bounds. */
+    const rememberFlushed = (ledger, id, text) => {
+        let texts = ledger.get(id);
+        if (!texts) {
+            texts = new Set();
+            ledger.set(id, texts);
+            if (ledger.size > MAX_FLUSHED_IDS)
+                ledger.delete(ledger.keys().next().value);
+        }
+        texts.add(text);
+        if (texts.size > MAX_FLUSHED_TEXTS)
+            texts.delete(texts.values().next().value);
+    };
     // Every currently-connected socket, so a turn's start/stop transition can be
     // broadcast to all clients — powering the per-chat sidebar streaming dots that
     // must update even for chats whose pane isn't mounted (issue #53).
@@ -253,84 +396,19 @@ export function makeChatHandler(deps) {
     // consumes the returned surface.
     const engine = makeTurnEngine({ deps, hub });
     const { startAgentTurn, wakeInjection, selfMcpCtx, injectRecoveryNudge, recoveryEngine, emitAfterTurn, composePreloadedPrompt, fireTrigger, makeBackgroundTurnSink, } = engine;
-    const handle = async function handle(socket) {
-        const send = (m) => {
-            if (socket.readyState === socket.OPEN)
-                socket.send(JSON.stringify(m));
-        };
-        // Register this socket for active-turn broadcasts, and immediately catch it
-        // up on which sessions are currently running (so the sidebar dots and a
-        // returning pane's Stop button reflect reality from the first paint).
-        clients.add(socket);
-        for (const info of hub.runningSessions())
-            send(activeFrame(info));
-        // Heartbeat: browsers auto-answer protocol ping frames with a pong, so a
-        // client whose TCP has silently died (idle drop, sleep) fails to pong and is
-        // terminated on the next tick — freeing server resources and letting the
-        // client's own reconnect take over. Cleared when the socket closes.
-        let isAlive = true;
-        socket.on("pong", () => {
-            isAlive = true;
-        });
-        const heartbeat = setInterval(() => {
-            if (!isAlive) {
-                socket.terminate();
-                return;
-            }
-            isAlive = false;
-            try {
-                socket.ping();
-            }
-            catch {
-                socket.terminate();
-            }
-        }, SERVER_PING_INTERVAL_MS);
-        socket.on("close", () => {
-            clearInterval(heartbeat);
-            // Drop this socket from every session fan-out set so the hub stops trying
-            // to write to it (a running turn keeps going for other attached sockets).
-            hub.unsubscribeSocket(socket);
-            clients.delete(socket);
-        });
-        socket.on("message", (raw) => {
-            let parsed;
-            try {
-                parsed = JSON.parse(raw.toString());
-            }
-            catch {
-                send({ type: "chat:error", payload: { projectSlug: "?", error: "Invalid JSON" } });
-                return;
-            }
-            if (!isClientMessage(parsed)) {
-                send({ type: "chat:error", payload: { projectSlug: "?", error: "Unknown message" } });
-                return;
-            }
-            if (parsed.type === "ping") {
-                send({ type: "pong" });
-                return;
-            }
-            if (parsed.type === "chat:cancel") {
-                void deps.herdctl.cancel(parsed.payload.jobId).catch(() => undefined);
-                return;
-            }
-            if (parsed.type === "chat:subscribe") {
-                onSubscribe(parsed);
-                return;
-            }
-            if (parsed.type === "chat:set_queue") {
-                void onSetQueue(parsed);
-                return;
-            }
-            if (parsed.type === "chat:command") {
-                void onChatCommand(parsed);
-                return;
-            }
-            if (parsed.type === "chat:continue") {
-                void onChatContinue(parsed);
-                return;
-            }
-            void onChatSend(parsed);
-        });
+    /**
+     * Build the chat operations for ONE connection: the handlers behind every
+     * client frame, plus the queue drain they share.
+     *
+     * A factory rather than plain closures inside {@link handle} because the drain
+     * has to run with NO socket at all (#627). A turn started by a trigger, a
+     * scheduler wake or a spawn has no originating connection, and a queued
+     * follow-up must still go out when it ends — so `socket` is nullable and the
+     * ops are built once, socket-less, for those paths (see `headlessOps` below).
+     * A socket-less send is a no-op: everything a client needs to see travels over
+     * the hub, which fans out to every socket attached to the session.
+     */
+    const makeChatOps = (socket, send) => {
         /**
          * Manual keeper recovery (issue #301, Layer 2). Re-drive a hung keeper whose
          * background task was killed at the turn boundary by injecting the recovery
@@ -369,6 +447,8 @@ export function makeChatHandler(deps) {
             });
         };
         const onSubscribe = (msg) => {
+            if (!socket)
+                return; // the socket-less ops never receive client frames
             const { sessionId, wantReplay, lastSeq } = msg.payload;
             const result = hub.attach(sessionId, socket, {
                 wantReplay: wantReplay === true,
@@ -387,63 +467,158 @@ export function makeChatHandler(deps) {
             const active = hub.activeInfo(sessionId);
             if (active)
                 send(activeFrame(active));
+            // …and what is currently QUEUED on it (#629). The queue is shared chat
+            // state, but a pane could only ever learn it from its own localStorage, so
+            // a message queued on another device — or one parked by a Stop nobody was
+            // left to hand it back to — was invisible to whoever opened the chat next.
+            const slug = msg.payload.projectSlug;
+            if (deps.queuedMessage && typeof slug === "string") {
+                void deps.queuedMessage
+                    .get(keeperAgentName(slug), sessionId)
+                    .then((queued) => {
+                    if (!hasQueuedContent(queued))
+                        return;
+                    send({
+                        type: "chat:queued_state",
+                        payload: {
+                            projectSlug: slug,
+                            sessionId,
+                            text: queued.text || null,
+                            ...(queued.id ? { qid: queued.id } : {}),
+                            ...(queued.attachments?.length ? { attachments: queued.attachments } : {}),
+                        },
+                    });
+                })
+                    .catch(() => undefined);
+            }
         };
         // Server-authoritative queue drain (#245): auto-send a persisted queued
-        // message as the next turn, exactly once. Called (a) when a turn completes
-        // successfully and (b) when a queue is set while the session is idle — a queue
-        // that arrived (e.g. via the reconnect outbox) after the turn it was meant to
-        // follow already ended. `take` makes the read+clear atomic so the two callers
-        // can never both send it; the `lastFlushed` marker skips a message already
-        // drained (a stale client re-assert on reload) so it isn't sent twice.
+        // message as the next turn, exactly once. Called (a) whenever a turn ends —
+        // through the hub, so EVERY turn path drains (#627) — and (b) when a queue is
+        // set while the session is idle, i.e. a queue that arrived (e.g. via the
+        // reconnect outbox) after the turn it was meant to follow already ended.
+        // `take` makes the read+clear atomic so two concurrent drains can never both
+        // send it; the flushed-parts ledger skips what was already drained (a stale
+        // client re-assert on reload) so it isn't sent twice.
+        /**
+         * Put attachments the drain could not carry back onto the (now empty) slot as
+         * an attachments-only queued message, and tell every client (#728). Only the
+         * slash-command path uses this: a command cannot carry files, and dropping
+         * them here would be the silent loss this whole change is about.
+         */
+        const restageAttachments = async (slug, sessionId, attachments) => {
+            if (!deps.queuedMessage)
+                return;
+            const agent = keeperAgentName(slug);
+            await deps.queuedMessage
+                .set(agent, sessionId, {
+                text: "",
+                createdAtMs: Date.now(),
+                id: randomUUID(),
+                attachments,
+            })
+                .catch(() => undefined);
+            hub.broadcast(sessionId, {
+                type: "chat:queued_state",
+                payload: { projectSlug: slug, sessionId, text: null, attachments },
+            });
+        };
         const drainQueue = async (slug, sessionId) => {
             if (!deps.queuedMessage)
                 return;
+            // Another turn is already live on this session (a drain racing a fresh send,
+            // or a turn ending while its successor has started). Leave the queue for
+            // that turn's own end — sending now would interleave two turns.
+            if (hub.isRunning(sessionId))
+                return;
             const agent = keeperAgentName(slug);
             const queued = await deps.queuedMessage.take(agent, sessionId).catch(() => null);
-            if (!queued?.text)
+            // A slot with no prose but staged files is a real message (#328/#728), so
+            // "is there anything here" is content, not text.
+            if (!hasQueuedContent(queued) || !queued)
                 return;
             const markerKey = `${agent}${KEY_SEP}${sessionId}`;
-            const marker = lastFlushed.get(markerKey);
-            // Already drained, on the (ts, text) tuple (#628): either this exact text
-            // went out at this exact ts, or the whole message predates the last one we
-            // flushed — which, timestamps being monotonic, can only be a stale re-assert.
-            // An APPEND reuses the ts with longer text, so it is NOT a duplicate.
-            const already = marker !== undefined &&
-                (queued.createdAtMs < marker.ts ||
-                    (queued.createdAtMs === marker.ts && marker.texts.has(queued.text)));
+            // Parked by a Stop we couldn't hand back (see returnQueueToComposer): the
+            // user asked for control, so it waits for them, not for the next turn end.
+            // Put it back — `take` already removed it.
+            if (parked.get(markerKey) === slotVersion(queued)) {
+                await deps.queuedMessage.set(agent, sessionId, queued).catch(() => undefined);
+                return;
+            }
+            const ledger = flushedLedger(markerKey);
+            // Have we already sent this? (#628/#736.)
+            //
+            // Identity is the (id, text) TUPLE, matched by EQUALITY, against every
+            // identity the slot has been known by — so a client re-asserting its stored
+            // copy on reload is recognised whether it holds the id it sent or the slot
+            // version the server broadcast back.
+            //
+            // It used to be a (ts, text) tuple with an ORDERING rule on top: "older than
+            // the last flush ⇒ stale by construction, timestamps being monotonic". They
+            // are monotonic within one client, but the ts came from whichever BROWSER
+            // queued the message — so a single client with a fast clock left the marker
+            // five minutes in the future, and every later queued message on that chat,
+            // from any client, was taken, classified already-flushed, deleted and never
+            // sent, until wall-clock time caught up (#736). Equality assumes nothing
+            // about clocks. An APPEND keeps its identity with LONGER text (#245), so it
+            // still reads as a genuinely new message and is sent — #628, unchanged.
+            const parts = partsOf(queued);
+            const stale = parts.some((p) => ledger.get(p.id)?.has(p.text));
+            const text = stale ? "" : queued.text;
+            // A leading-slash queued message is a slash command (e.g. "/compact"): the
+            // CLI dispatches it, and a command carries no attachments — exactly as the
+            // live composer refuses to attach files to one. Keep them on the slot rather
+            // than destroying them: they stay visible as a queued message of their own
+            // and go out after the command's turn, which is the only outcome here that
+            // isn't silent loss (#728). Unreachable from the current client, which never
+            // stages files onto a slash-command queue; reachable if one ever appends
+            // prose + a file behind an already-queued command.
+            const isCommand = !stale && text.startsWith("/");
+            const attachments = stale || isCommand ? [] : (queued.attachments ?? []);
+            // An attachments-only slot has no text but is still a real message
+            // (#328/#728), so what makes this a send is CONTENT, not prose.
+            const sending = !stale && (Boolean(text) || attachments.length > 0);
             // Tell every attached client (origin + reconnected sockets) to clear its copy
-            // of this message. When we're really sending it, carry the text so the client
-            // renders the sent bubble in-transcript; on a stale re-assert we only clear.
+            // of this message. When we're really sending it, carry the text + attachments
+            // so the client renders the sent bubble in-transcript exactly as a live send
+            // does; on a stale re-assert we only clear.
             hub.broadcast(sessionId, {
                 type: "chat:queued_flushed",
                 payload: {
                     projectSlug: slug,
                     sessionId,
-                    ...(already ? {} : { text: queued.text }),
+                    ...(sending && text ? { text } : {}),
+                    ...(sending && attachments.length > 0 ? { attachments } : {}),
                 },
             });
-            if (already)
+            if (!sending)
                 return;
-            // Record the tuple. A newer ts supersedes the marker outright (everything at
-            // the old ts is now stale); the same ts adds one more flushed text.
-            if (marker !== undefined && marker.ts === queued.createdAtMs)
-                marker.texts.add(queued.text);
-            else
-                lastFlushed.set(markerKey, { ts: queued.createdAtMs, texts: new Set([queued.text]) });
+            // Every identity this slot carried is now flushed, so a re-assert from any
+            // client that held one of them is recognised rather than sent again.
+            for (const p of parts)
+                rememberFlushed(ledger, p.id, p.text);
             // Broadcast the flush frame BEFORE kicking the turn so the user bubble renders
-            // above the reply. Run it detached, like a human send. A leading-slash queued
-            // message is a slash command (e.g. "/compact"): route it through the command
-            // path so the CLI dispatches it — matching how the composer sends one live.
-            if (queued.text.startsWith("/")) {
+            // above the reply. Run it detached, like a human send.
+            if (isCommand) {
+                if ((queued.attachments?.length ?? 0) > 0) {
+                    void restageAttachments(slug, sessionId, queued.attachments);
+                }
                 void onChatCommand({
                     type: "chat:command",
-                    payload: { projectSlug: slug, command: queued.text, sessionId },
+                    payload: { projectSlug: slug, command: text, sessionId },
                 });
             }
             else {
                 void onChatSend({
                     type: "chat:send",
-                    payload: { projectSlug: slug, sessionId, message: queued.text },
+                    payload: {
+                        projectSlug: slug,
+                        sessionId,
+                        message: text,
+                        // The files the user staged behind this message (#728). They used to
+                        // stay in the composer tray and ride whatever was sent NEXT.
+                        ...(attachments.length > 0 ? { attachments } : {}),
+                    },
                 });
             }
         };
@@ -456,18 +631,59 @@ export function makeChatHandler(deps) {
                 return;
             const sessionId = msg.payload.sessionId ?? null;
             const text = msg.payload.text ?? null;
+            // The composer's staged files ride the queued message (#728). They merge
+            // additively into the slot, so a write that carries none never removes any.
+            const attachments = msg.payload.attachments ?? [];
             // Every chat belongs to a workspace keeper.
             const agent = keeperAgentName(slug);
             if (!sessionId) {
                 // New chat: queue isn't stored until the session id exists. The client
-                // re-asserts it (with the same ts) once the id resolves, so it persists then.
+                // re-asserts it (same qid) once the id resolves, so it persists then.
                 return;
             }
-            // Store or clear the queued message.
-            if (text && text.trim().length > 0) {
-                await deps.queuedMessage
-                    .set(agent, sessionId, { text, createdAtMs: msg.payload.ts ?? Date.now() })
+            // Store or clear the queued message. A slot with staged files but no prose is
+            // a real message (#328: an attachment-only send is valid), so "is there
+            // anything to store" is text OR attachments — it used to be text alone, which
+            // is why an attachment-only submit during a live turn was a silent no-op.
+            if ((text && text.trim().length > 0) || attachments.length > 0) {
+                // A queued message is persisted verbatim and the whole sidecar is rewritten
+                // on every mutation, so an unbounded one is a cheap way to bloat the data
+                // dir. Refuse it loudly rather than silently truncating the user's text.
+                if (text != null && text.length > MAX_QUEUED_CHARS) {
+                    send({
+                        type: "chat:error",
+                        payload: {
+                            projectSlug: slug,
+                            error: `Queued message is too long (${text.length} characters; the limit is ${MAX_QUEUED_CHARS}).`,
+                        },
+                    });
+                    return;
+                }
+                // Merge into the chat's single slot rather than overwriting it (#629). The
+                // id the client wrote under says which this is: a client editing the slot
+                // it can currently see (replace) or one that queued without knowing what
+                // was already there (append). The old unconditional overwrite destroyed the
+                // first client's message with no signal to anyone — and then rendered it,
+                // in that client's own transcript, as a user bubble they never typed.
+                const next = await deps.queuedMessage
+                    .upsert(agent, sessionId, { id: queueIdOf(msg.payload), text: text ?? "", attachments }, Date.now(), randomUUID)
                     .catch(() => undefined);
+                // The queue is shared chat state, so announce it: every attached client
+                // renders the same slot, and echoing `qid` back on its next write is how a
+                // client proves it is editing the slot as it stands rather than replacing
+                // someone else's text with its own.
+                if (next !== undefined) {
+                    hub.broadcast(sessionId, {
+                        type: "chat:queued_state",
+                        payload: {
+                            projectSlug: slug,
+                            sessionId,
+                            text: next?.text || null,
+                            ...(next?.id ? { qid: next.id } : {}),
+                            ...(next?.attachments?.length ? { attachments: next.attachments } : {}),
+                        },
+                    });
+                }
                 // If no turn is running, this queue arrived after the turn it was meant to
                 // follow already ended — drain it now rather than wait for a completion
                 // that won't come (the reported stranding bug, #245).
@@ -475,7 +691,14 @@ export function makeChatHandler(deps) {
                     await drainQueue(slug, sessionId);
             }
             else {
+                // A clear wipes the WHOLE slot, including another client's contribution:
+                // with the state broadcast the chip is shared, so clearing it is a
+                // deliberate act on something the user can actually see.
                 await deps.queuedMessage.set(agent, sessionId, null).catch(() => undefined);
+                hub.broadcast(sessionId, {
+                    type: "chat:queued_state",
+                    payload: { projectSlug: slug, sessionId, text: null },
+                });
             }
         };
         const onChatSend = async (msg) => {
@@ -838,13 +1061,13 @@ export function makeChatHandler(deps) {
                         ...(completeUsage ? { model: completeModel, usage: completeUsage } : {}),
                     },
                 });
+                // Ending the turn drains any queued follow-up (#197/#245) via the hub's
+                // turn-end hook — the ONE place every turn path converges (#627), rather
+                // than this call site alone. It no longer waits for a SUCCESSFUL turn:
+                // holding the queue on a failed/Stopped turn didn't keep it for the user,
+                // it stranded it, to be flushed by the NEXT `chat:send` — landing behind a
+                // message typed later, with a stale chip in between. See drainQueue.
                 turn.end();
-                // After a SUCCESSFUL turn, auto-send any queued follow-up (#197/#245). A
-                // Stop/failed turn holds the queue for the user (no drain). drainQueue owns
-                // the take + client notify + next-turn kickoff, shared with the idle path.
-                if (effectiveSuccess && finalSession) {
-                    await drainQueue(slug, finalSession);
-                }
                 // Layer 3 (issue #301): arm a post-turn recovery watch for a session-mode
                 // keeper turn. If this turn launched a background task that the runtime kills
                 // at the turn boundary (herdctl#374) and the keeper doesn't wake on its own,
@@ -1040,6 +1263,201 @@ export function makeChatHandler(deps) {
                 turn.end();
             }
         };
+        return { onChatContinue, onSubscribe, drainQueue, onSetQueue, onChatSend, onChatCommand };
+    };
+    // The ops used when a turn ends with no socket behind it — a trigger, a wake, a
+    // spawned turn, a background sub-agent stretch — so the drain still has a way to
+    // dispatch the follow-up. Built once: it holds no per-connection state.
+    const headlessOps = makeChatOps(null, () => { });
+    // Prefer the ending turn's ORIGIN socket when there is one, so a drained turn
+    // keeps the same fan-out (and error routing) the turn it followed had; a turn
+    // with no origin falls back to the headless ops.
+    const opsFor = (origin) => origin
+        ? makeChatOps(origin, (m) => {
+            if (origin.readyState === origin.OPEN)
+                origin.send(JSON.stringify(m));
+        })
+        : headlessOps;
+    /**
+     * Stop hands the queued message BACK to the user instead of sending it.
+     *
+     * Stop means "give me control back", so the one thing it must not do is have
+     * the agent start working again on the follow-up the instant it is stopped.
+     * Holding the message server-side isn't the answer either — that is exactly
+     * what stranded it (#627): it sat there and went out behind whatever the user
+     * typed next. So it goes back to the composer of the client that pressed Stop,
+     * where it is visible, editable, and sent only when they say so. The client
+     * runs its existing "Edit queued message" path on the frame; the composer draft
+     * is persisted to localStorage by the same effect that persists any draft.
+     *
+     * Every OTHER turn-ending path — normal completion, a slash command, a trigger,
+     * a wake, a spawn, a background stretch — still drains. This is the single
+     * explicit exception, not a gap.
+     */
+    const returnQueueToComposer = async (slug, sessionId, to) => {
+        if (!deps.queuedMessage)
+            return;
+        // A successor turn is already live (a Stop racing the next send): leave the
+        // queue to that turn's own end rather than yanking it mid-flight.
+        if (hub.isRunning(sessionId))
+            return;
+        const agent = keeperAgentName(slug);
+        const queued = await deps.queuedMessage.take(agent, sessionId).catch(() => null);
+        if (!hasQueuedContent(queued) || !queued)
+            return;
+        const attachments = queued.attachments ?? [];
+        const live = to && to.readyState === to.OPEN ? to : null;
+        if (!live) {
+            // Nobody to hand it to — the tab closed between the Stop and this turn
+            // ending, or the cancel came from no socket at all. Put it back and PARK
+            // it: still queued, still visible (every attached client is told, and a
+            // pane opening this chat is told on subscribe), but no turn end will
+            // auto-send it. Dropping it here would be exactly the silent loss this
+            // change is about, and sending it would be the surprise Stop must not have.
+            await deps.queuedMessage.set(agent, sessionId, queued).catch(() => undefined);
+            const key = `${agent}${KEY_SEP}${sessionId}`;
+            parked.set(key, slotVersion(queued));
+            if (parked.size > MAX_FLUSHED_SESSIONS) {
+                parked.delete(parked.keys().next().value);
+            }
+            hub.broadcast(sessionId, {
+                type: "chat:queued_state",
+                payload: {
+                    projectSlug: slug,
+                    sessionId,
+                    text: queued.text || null,
+                    ...(queued.id ? { qid: queued.id } : {}),
+                    ...(attachments.length > 0 ? { attachments } : {}),
+                },
+            });
+            return;
+        }
+        // The stopping client gets the text AND the files staged behind it (#728) —
+        // Stop returns the whole message, and a file left on the cleared slot would be
+        // stranded server-side. Everyone else just sees the shared slot clear, WITH a
+        // reason — a chip vanishing from under you with no explanation is the same
+        // silence that made #629 bite.
+        writeFrame(live, {
+            type: "chat:queued_returned",
+            payload: {
+                projectSlug: slug,
+                sessionId,
+                text: queued.text,
+                ...(attachments.length > 0 ? { attachments } : {}),
+            },
+        });
+        hub.broadcast(sessionId, {
+            type: "chat:queued_state",
+            payload: { projectSlug: slug, sessionId, text: null, reason: "returned" },
+        }, { except: live });
+    };
+    // #627: EVERY turn-ending path deals with the queue, because every one of them
+    // ends its turn through the hub. Previously this was a single call after a
+    // successful `chat:send`, so a message queued during a slash command, a trigger,
+    // a wake or a background stretch was stranded until some later `chat:send`
+    // flushed it — out of order, behind a message the user typed afterwards.
+    hub.onTurnEnd = ({ sessionId, projectSlug, origin, cancel }) => {
+        // A destructive op stopped this turn so it can delete/revert/promote the
+        // chat (#731). Its transcript is about to be rewritten or removed, so a
+        // drained follow-up would either race that or resurrect the chat (#730) —
+        // and, by making the session busy again, would make the interlock time out
+        // and refuse the operation. Leave the queue exactly where it is.
+        if (cancel?.reason === "quiesce")
+            return;
+        if (cancel?.reason === "stop") {
+            void returnQueueToComposer(projectSlug, sessionId, cancel.origin);
+            return;
+        }
+        void opsFor(origin).drainQueue(projectSlug, sessionId);
+    };
+    const handle = async function handle(socket) {
+        const send = (m) => {
+            if (socket.readyState === socket.OPEN)
+                socket.send(JSON.stringify(m));
+        };
+        // This connection's operations. The frame dispatcher below closes over them.
+        const { onChatContinue, onSubscribe, onSetQueue, onChatSend, onChatCommand } = makeChatOps(socket, send);
+        // Register this socket for active-turn broadcasts, and immediately catch it
+        // up on which sessions are currently running (so the sidebar dots and a
+        // returning pane's Stop button reflect reality from the first paint).
+        clients.add(socket);
+        for (const info of hub.runningSessions())
+            send(activeFrame(info));
+        // Heartbeat: browsers auto-answer protocol ping frames with a pong, so a
+        // client whose TCP has silently died (idle drop, sleep) fails to pong and is
+        // terminated on the next tick — freeing server resources and letting the
+        // client's own reconnect take over. Cleared when the socket closes.
+        let isAlive = true;
+        socket.on("pong", () => {
+            isAlive = true;
+        });
+        const heartbeat = setInterval(() => {
+            if (!isAlive) {
+                socket.terminate();
+                return;
+            }
+            isAlive = false;
+            try {
+                socket.ping();
+            }
+            catch {
+                socket.terminate();
+            }
+        }, SERVER_PING_INTERVAL_MS);
+        socket.on("close", () => {
+            clearInterval(heartbeat);
+            // Drop this socket from every session fan-out set so the hub stops trying
+            // to write to it (a running turn keeps going for other attached sockets).
+            hub.unsubscribeSocket(socket);
+            clients.delete(socket);
+        });
+        socket.on("message", (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.toString());
+            }
+            catch {
+                send({ type: "chat:error", payload: { projectSlug: "?", error: "Invalid JSON" } });
+                return;
+            }
+            if (!isClientMessage(parsed)) {
+                send({ type: "chat:error", payload: { projectSlug: "?", error: "Unknown message" } });
+                return;
+            }
+            if (parsed.type === "ping") {
+                send({ type: "pong" });
+                return;
+            }
+            if (parsed.type === "chat:cancel") {
+                // Tell the hub this end is a user Stop, and which socket asked, so the
+                // turn end it causes hands the queued follow-up back to THAT composer
+                // instead of sending it. `chat:cancel` names only a job id, so the hub
+                // resolves the chat it belongs to; a stale Stop for a turn that already
+                // finished resolves to nothing and marks nothing.
+                const target = hub.sessionForJob(parsed.payload.jobId);
+                if (target)
+                    hub.noteCancel(target.sessionId, { reason: "stop", origin: socket });
+                void deps.herdctl.cancel(parsed.payload.jobId).catch(() => undefined);
+                return;
+            }
+            if (parsed.type === "chat:subscribe") {
+                onSubscribe(parsed);
+                return;
+            }
+            if (parsed.type === "chat:set_queue") {
+                void onSetQueue(parsed);
+                return;
+            }
+            if (parsed.type === "chat:command") {
+                void onChatCommand(parsed);
+                return;
+            }
+            if (parsed.type === "chat:continue") {
+                void onChatContinue(parsed);
+                return;
+            }
+            void onChatSend(parsed);
+        });
     };
     // The socket handler PLUS the manual trigger-fire entrypoint: a "trigger now"
     // action fires a schedule-type trigger on demand through the exact same hub path a