@edspencer/paddock 0.66.0 → 0.66.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.66.0",
+  "version": "0.66.1",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/app.d.ts

@@ -16,6 +16,7 @@ import { HerdctlService } from "./herdctl.js";
 import { GitService } from "./git.js";
 import { GithubAuth } from "./github-auth.js";
 import { type Transcriber } from "./transcribe.js";
+import type { SessionHub } from "./session-hub.js";
 import { SweepService } from "./sweep.js";
 import { ArchiveStore } from "./archive.js";
 import { StarStore } from "./star.js";
@@ -49,6 +50,13 @@ export interface BuiltApp {
     events: PaddockEventBus;
     /** Unified trigger registry (Epic T / T1) — the sole trigger CRUD surface. */
     triggers: TriggerService;
+    /**
+     * The WS layer's session hub — every in-flight turn, and the fan-out to the
+     * sockets watching it. Exposed for callers that need to observe or annotate a
+     * turn without holding a socket (the destructive-op interlock reaches it the
+     * same way, via the route context).
+     */
+    hub: SessionHub;
     /** Tear down the fleet + close the server (no process.exit, for tests). */
     close: () => Promise<void>;
 }

package/packages/server/dist/app.js

@@ -399,5 +399,8 @@ export async function buildApp(opts = {}) {
         await herdctl.stop().catch(() => undefined);
         await app.close().catch(() => undefined);
     };
-    return { app, cfg, projects, herdctl, git, githubAuth, sweep, archive, star, readState, unread, parentDetach, runProvenance, queuedMessage, transcriber, events, triggers, close };
+    // `hub` rides along like every other built piece: it is the WS layer's turn
+    // bookkeeping, and the only place a caller can observe or annotate a turn
+    // without a live socket (see SessionHub.noteCancel).
+    return { app, cfg, projects, herdctl, git, githubAuth, sweep, archive, star, readState, unread, parentDetach, runProvenance, queuedMessage, transcriber, events, triggers, hub: chatHandler.managementOpsContext.hub, close };
 }

package/packages/server/dist/queued-message.d.ts

@@ -1,8 +1,38 @@
+/**
+ * One identity a chat's queued message has been known by.
+ *
+ * `id` is OPAQUE and compared only for EQUALITY — never ordered — so a client with
+ * a skewed clock can't poison anything (#736). Two kinds of id land here: the one a
+ * CLIENT sent with its `chat:set_queue`, and the slot VERSION the server minted in
+ * response and broadcast back. A client re-asserting a queue on reload sends one of
+ * the two, which is exactly what makes the drain able to recognise it (see
+ * `drainQueue` in ws.ts).
+ */
+export interface QueuedPart {
+    id: string;
+    text: string;
+}
 /** A queued message awaiting auto-send. */
 export interface QueuedMessage {
+    /** The slot's full text — what gets sent. */
     text: string;
+    /** SERVER-stamped enqueue time. Informational — never load-bearing (#736). */
     createdAtMs: number;
+    /**
+     * The slot's current VERSION, minted on every write and broadcast to every
+     * attached client. A client echoes back the version it last saw, which is how
+     * the server can tell "this client is editing the slot it can see" from "this
+     * client composed a queue of its own, not knowing about the other one" (#629).
+     */
+    id?: string;
+    /**
+     * Every (id, text) this slot has been known by — the dedup ledger. Absent on an
+     * entry written by an older server; readers treat that as one legacy identity.
+     */
+    parts?: QueuedPart[];
 }
+/** The identities of an entry, synthesising one for a legacy entry without any. */
+export declare function partsOf(m: QueuedMessage): QueuedPart[];
 export declare class QueuedMessageStore {
     private readonly stateFile;
     /** In-memory map of key -> QueuedMessage (loaded once, written through on change). */
@@ -30,6 +60,33 @@ export declare class QueuedMessageStore {
      * Setting `null` deletes the key, keeping the file compact.
      */
     set(agent: string, sessionId: string, message: QueuedMessage | null): Promise<void>;
+    /**
+     * Write one client's queue into a chat's single slot, MERGING rather than
+     * overwriting (#629), and return the resulting entry. The read-modify-write
+     * happens with no `await` between the load and the mutation, so two clients
+     * queueing at once can't lose one another's text the way the old unconditional
+     * `set` overwrite did.
+     *
+     * `incoming.id` is the identity the client is writing under — either the slot
+     * VERSION it last saw (broadcast to it via `chat:queued_state`) or, if it has
+     * never seen one, its own queue id. That is what distinguishes the two cases:
+     *
+     *  - **it matches the current version** ⇒ the client can see the slot as it is
+     *    now, so its text IS the whole slot: replace. This covers the ordinary
+     *    single-client edit/append (#245 stable identity) and any client that has
+     *    caught up with a merge.
+     *  - **it doesn't** ⇒ the client composed this queue without knowing the
+     *    slot's current contents (a second device, or a tab that missed the
+     *    broadcast): APPEND, so neither message is lost.
+     *
+     * A write whose text the slot has already been known by is a re-assert — a
+     * reconnecting client pushing its stored copy — and is a no-op, so reconnecting
+     * can't duplicate text into the slot.
+     *
+     * `nowMs` stamps a fresh slot's `createdAtMs` SERVER-side; an existing slot keeps
+     * the one it has. The client's clock never enters the store (#736).
+     */
+    upsert(agent: string, sessionId: string, incoming: QueuedPart, nowMs: number, mintVersion: () => string): Promise<QueuedMessage | null>;
     /** Write-through, serialised so overlapping writes can't corrupt the file. */
     private persist;
 }

package/packages/server/dist/queued-message.js

@@ -15,6 +15,26 @@
  * When a turn completes, the server checks for a queued message, auto-sends it as
  * the next message, and deletes the stored entry. The web client receives a
  * `chat:queued_flushed` frame to clear its localStorage.
+ *
+ * ## One slot, many contributors (#629)
+ *
+ * The slot is per CHAT, not per client — a chat has one "next message", the same
+ * model the composer renders. It used to be a bare overwrite, so a second client
+ * queueing on the same chat silently destroyed the first client's text (and the
+ * first client's transcript then rendered a user bubble nobody there had typed).
+ *
+ * The slot now holds an ordered list of {@link QueuedPart}s: one per contributing
+ * client queue, identified by that client's opaque queue id. A client updating ITS
+ * OWN part replaces it in place (an edit/append — #245's stable identity); a
+ * DIFFERENT client's queue appends a new part. `text` is the joined result and
+ * stays the thing that gets sent, so nothing downstream — nor an older reader of
+ * this file — needs to know about parts.
+ *
+ * The parts double as the drain's dedup ledger. A client that never saw the
+ * `chat:queued_flushed` clear (it is broadcast un-buffered) re-asserts its own
+ * (id, text) on reload; matching that against the parts actually flushed is what
+ * lets the drain tell a stale re-assert from a genuinely new message WITHOUT
+ * comparing wall clocks (#736). See `drainQueue` in ws.ts.
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -25,6 +45,45 @@ const KEY_SEP = "\u0000";
 function keyOf(agent, sessionId) {
     return `${agent}${KEY_SEP}${sessionId}`;
 }
+/** Joiner when a second client's queue is merged in — what the composer uses. */
+const MERGE_SEP = "\n";
+/** How many (id, text) identities one slot remembers. Bounds the sidecar entry. */
+const MAX_KNOWN = 24;
+/**
+ * Fold a write from a client that ISN'T on the slot's current version into the
+ * slot's text.
+ *
+ * Usually that client is simply appending to its own queue: it holds text the slot
+ * already contains and has added a line to the end of it. That is the ordinary
+ * single-client append — the composer keeps one queue id across an append (#245),
+ * and an older client sends only its enqueue `ts`, so neither ever carries the
+ * current version. It also covers the plain race of appending faster than the
+ * broadcast round trip. In every one of those, the client's text EXTENDS something
+ * the slot already holds, so we substitute in place rather than appending — or the
+ * client's own earlier text would appear twice.
+ *
+ * Otherwise the client queued without knowing what was already there (a second
+ * device), and its text is appended so neither message is lost (#629).
+ */
+function mergeInto(current, known, incoming) {
+    // The most specific thing the incoming text extends — longest first, since a
+    // queue that has been appended to is known by every prefix it has passed through.
+    const extended = known
+        .filter((p) => p.text.length > 0 && incoming.startsWith(`${p.text}${MERGE_SEP}`))
+        .sort((a, b) => b.text.length - a.text.length)[0];
+    const at = extended ? current.indexOf(extended.text) : -1;
+    if (at < 0)
+        return `${current}${MERGE_SEP}${incoming}`;
+    // Splice rather than String.replace: the texts are user prose and `$&`-style
+    // patterns in a replacement string would be interpreted.
+    return current.slice(0, at) + incoming + current.slice(at + extended.text.length);
+}
+/** The identities of an entry, synthesising one for a legacy entry without any. */
+export function partsOf(m) {
+    if (m.parts && m.parts.length > 0)
+        return m.parts;
+    return [{ id: m.id ?? `legacy:${m.createdAtMs}`, text: m.text }];
+}
 export class QueuedMessageStore {
     stateFile;
     /** In-memory map of key -> QueuedMessage (loaded once, written through on change). */
@@ -49,7 +108,24 @@ export class QueuedMessageStore {
                         typeof v === "object" &&
                         typeof v.text === "string" &&
                         typeof v.createdAtMs === "number") {
-                        map.set(k, v);
+                        const entry = v;
+                        // `parts` is optional (an older server wrote entries without it) and
+                        // corruption-tolerant like everything else here: a malformed parts
+                        // array is dropped, leaving a legacy single-part entry, not a throw.
+                        const raw = v.parts;
+                        const parts = Array.isArray(raw)
+                            ? raw.filter((p) => Boolean(p) &&
+                                typeof p === "object" &&
+                                typeof p.id === "string" &&
+                                typeof p.text === "string")
+                            : [];
+                        const id = typeof v.id === "string" ? entry.id : undefined;
+                        map.set(k, {
+                            text: entry.text,
+                            createdAtMs: entry.createdAtMs,
+                            ...(id ? { id } : {}),
+                            ...(parts.length > 0 ? { parts } : {}),
+                        });
                     }
                 }
             }
@@ -102,6 +178,64 @@ export class QueuedMessageStore {
         }
         await this.persist(map);
     }
+    /**
+     * Write one client's queue into a chat's single slot, MERGING rather than
+     * overwriting (#629), and return the resulting entry. The read-modify-write
+     * happens with no `await` between the load and the mutation, so two clients
+     * queueing at once can't lose one another's text the way the old unconditional
+     * `set` overwrite did.
+     *
+     * `incoming.id` is the identity the client is writing under — either the slot
+     * VERSION it last saw (broadcast to it via `chat:queued_state`) or, if it has
+     * never seen one, its own queue id. That is what distinguishes the two cases:
+     *
+     *  - **it matches the current version** ⇒ the client can see the slot as it is
+     *    now, so its text IS the whole slot: replace. This covers the ordinary
+     *    single-client edit/append (#245 stable identity) and any client that has
+     *    caught up with a merge.
+     *  - **it doesn't** ⇒ the client composed this queue without knowing the
+     *    slot's current contents (a second device, or a tab that missed the
+     *    broadcast): APPEND, so neither message is lost.
+     *
+     * A write whose text the slot has already been known by is a re-assert — a
+     * reconnecting client pushing its stored copy — and is a no-op, so reconnecting
+     * can't duplicate text into the slot.
+     *
+     * `nowMs` stamps a fresh slot's `createdAtMs` SERVER-side; an existing slot keeps
+     * the one it has. The client's clock never enters the store (#736).
+     */
+    async upsert(agent, sessionId, incoming, nowMs, mintVersion) {
+        const map = await this.ensureLoaded();
+        const key = keyOf(agent, sessionId);
+        const current = map.get(key) ?? null;
+        if (!incoming.text.trim())
+            return current;
+        const known = current ? partsOf(current) : [];
+        // Already folded in under some identity ⇒ a re-assert, not new text.
+        if (known.some((p) => p.text === incoming.text))
+            return current;
+        const text = !current
+            ? incoming.text
+            : incoming.id === current.id
+                ? // The client can see the slot as it stands, so its text IS the slot.
+                    incoming.text
+                : mergeInto(current.text, known, incoming.text);
+        const version = mintVersion();
+        // Remember BOTH identities this write creates: what the client sent (which it
+        // will re-assert on reload) and the version we hand back (which it will
+        // re-assert once it adopts the broadcast). Either one reaching a later drain
+        // has to be recognisable as already-flushed.
+        const parts = [...known, { id: incoming.id, text: incoming.text }, { id: version, text }].slice(-MAX_KNOWN);
+        const next = {
+            text,
+            createdAtMs: current?.createdAtMs ?? nowMs,
+            id: version,
+            parts,
+        };
+        map.set(key, next);
+        await this.persist(map);
+        return next;
+    }
     /** Write-through, serialised so overlapping writes can't corrupt the file. */
     persist(map) {
         this.writing = this.writing.then(async () => {

package/packages/server/dist/session-hub.d.ts

@@ -98,6 +98,17 @@ export interface ActiveInfo {
     jobId: string | null;
     running: boolean;
 }
+/** Why a turn is being cancelled, and which socket asked for it. */
+export interface CancelIntent {
+    /**
+     * `stop` — a user pressed Stop (`chat:cancel`): they are taking control back.
+     * `quiesce` — a destructive op is stopping the turn so it can safely mutate
+     * the transcript (#731); the chat is being deleted, reverted or promoted.
+     */
+    reason: "stop" | "quiesce";
+    /** The socket that asked, if any. */
+    origin: HubSocket | null;
+}
 export declare class SessionHub {
     /** sessionId → the current (running or recently-completed) turn for that session. */
     private bySession;
@@ -109,6 +120,51 @@ export declare class SessionHub {
      * button restore (#52) and streaming indicators (#53). Set by the WS layer.
      */
     onActive: ((info: ActiveInfo) => void) | null;
+    /**
+     * Notified once per turn, when that turn stops running (#627). Set by the WS
+     * layer, which uses it to drain a queued follow-up.
+     *
+     * This exists because "after a turn" was, for a long time, spelled as a call at
+     * ONE of the eight `turn.end()` sites — the `chat:send` completion. A message
+     * queued during a slash command, a trigger/spawn turn, a scheduler wake, a
+     * background sub-agent stretch or a Stopped turn was therefore persisted and
+     * then stranded, escaping only when some LATER `chat:send` happened to flush it —
+     * arriving after a message the user typed afterwards. Every one of those paths
+     * already funnels through {@link end}, so hanging the drain here makes "drain on
+     * every turn-ending path" structural rather than a list somebody has to remember
+     * to extend — including for turn paths that don't exist yet.
+     *
+     * Fires only once a turn's session id is known (a turn that died before its id
+     * resolved has no chat to drain), and always AFTER the terminal frame its caller
+     * emitted, so a drained follow-up's bubble lands below the turn it followed.
+     */
+    onTurnEnd: ((info: {
+        sessionId: string;
+        projectSlug: string;
+        origin: HubSocket | null;
+        /** Set when this end was CAUSED by an explicit cancel — see {@link noteCancel}. */
+        cancel?: CancelIntent;
+    }) => void) | null;
+    /**
+     * Why a turn was cancelled, and by whom, pending the end it causes.
+     * Consumed by the next {@link end} for that session.
+     */
+    private cancels;
+    /**
+     * Record that a cancel was just issued for `sessionId`, so the turn end it
+     * causes can be told apart from a turn that finished on its own.
+     *
+     * The distinction is not cosmetic: "the turn ended" and "the user took control
+     * back" call for opposite treatment of anything queued behind that turn. A
+     * `stop` hands the queued message back to the client that pressed Stop; a
+     * `quiesce` (the destructive-op interlock, #731) must not touch it at all —
+     * that caller is about to delete or rewrite the transcript, and starting a
+     * fresh turn into it is the resurrection #730 was about.
+     *
+     * `origin` is the socket that asked, so the WS layer knows where to hand the
+     * message back; null when the cancel came from no socket at all.
+     */
+    noteCancel(sessionId: string, intent: CancelIntent): void;
     /**
      * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
      * chat / a slash command) so the turn is re-attachable from its very first
@@ -143,7 +199,19 @@ export declare class SessionHub {
      * like `chat:queued_flushed` that must reach a client that reconnected on a new
      * socket after the origin died.
      */
-    broadcast(sessionId: string, msg: HubMessage): void;
+    broadcast(sessionId: string, msg: HubMessage, opts?: {
+        except?: HubSocket | null;
+    }): void;
+    /**
+     * The session a cancellable job id belongs to, or null if no tracked turn
+     * carries it. `chat:cancel` names only a job id, so this is how the WS layer
+     * learns WHICH chat a Stop was aimed at. Covers a background stretch too — it
+     * publishes its synthetic id on its own hub turn (#528).
+     */
+    sessionForJob(jobId: string): {
+        sessionId: string;
+        projectSlug: string;
+    } | null;
     /** Whether a session currently has a RUNNING turn plus its job id, or null. */
     activeInfo(sessionId: string): ActiveInfo | null;
     /** Snapshot of every session with a running turn (for a newly-connected client). */

package/packages/server/dist/session-hub.js

@@ -50,6 +50,47 @@ export class SessionHub {
      * button restore (#52) and streaming indicators (#53). Set by the WS layer.
      */
     onActive = null;
+    /**
+     * Notified once per turn, when that turn stops running (#627). Set by the WS
+     * layer, which uses it to drain a queued follow-up.
+     *
+     * This exists because "after a turn" was, for a long time, spelled as a call at
+     * ONE of the eight `turn.end()` sites — the `chat:send` completion. A message
+     * queued during a slash command, a trigger/spawn turn, a scheduler wake, a
+     * background sub-agent stretch or a Stopped turn was therefore persisted and
+     * then stranded, escaping only when some LATER `chat:send` happened to flush it —
+     * arriving after a message the user typed afterwards. Every one of those paths
+     * already funnels through {@link end}, so hanging the drain here makes "drain on
+     * every turn-ending path" structural rather than a list somebody has to remember
+     * to extend — including for turn paths that don't exist yet.
+     *
+     * Fires only once a turn's session id is known (a turn that died before its id
+     * resolved has no chat to drain), and always AFTER the terminal frame its caller
+     * emitted, so a drained follow-up's bubble lands below the turn it followed.
+     */
+    onTurnEnd = null;
+    /**
+     * Why a turn was cancelled, and by whom, pending the end it causes.
+     * Consumed by the next {@link end} for that session.
+     */
+    cancels = new Map();
+    /**
+     * Record that a cancel was just issued for `sessionId`, so the turn end it
+     * causes can be told apart from a turn that finished on its own.
+     *
+     * The distinction is not cosmetic: "the turn ended" and "the user took control
+     * back" call for opposite treatment of anything queued behind that turn. A
+     * `stop` hands the queued message back to the client that pressed Stop; a
+     * `quiesce` (the destructive-op interlock, #731) must not touch it at all —
+     * that caller is about to delete or rewrite the transcript, and starting a
+     * fresh turn into it is the resurrection #730 was about.
+     *
+     * `origin` is the socket that asked, so the WS layer knows where to hand the
+     * message back; null when the cancel came from no socket at all.
+     */
+    noteCancel(sessionId, intent) {
+        this.cancels.set(sessionId, intent);
+    }
     /**
      * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
      * chat / a slash command) so the turn is re-attachable from its very first
@@ -129,7 +170,7 @@ export class SessionHub {
      * like `chat:queued_flushed` that must reach a client that reconnected on a new
      * socket after the origin died.
      */
-    broadcast(sessionId, msg) {
+    broadcast(sessionId, msg, opts = {}) {
         const set = new Set();
         const turn = this.bySession.get(sessionId);
         if (turn?.origin)
@@ -138,9 +179,24 @@ export class SessionHub {
         if (subs)
             for (const s of subs)
                 set.add(s);
+        if (opts.except)
+            set.delete(opts.except);
         for (const s of set)
             SessionHub.write(s, msg);
     }
+    /**
+     * The session a cancellable job id belongs to, or null if no tracked turn
+     * carries it. `chat:cancel` names only a job id, so this is how the WS layer
+     * learns WHICH chat a Stop was aimed at. Covers a background stretch too — it
+     * publishes its synthetic id on its own hub turn (#528).
+     */
+    sessionForJob(jobId) {
+        for (const [sessionId, turn] of this.bySession) {
+            if (turn.jobId === jobId)
+                return { sessionId, projectSlug: turn.projectSlug };
+        }
+        return null;
+    }
     // --- internals, driven by TurnHandle -------------------------------------
     /** Whether a session currently has a RUNNING turn plus its job id, or null. */
     activeInfo(sessionId) {
@@ -191,11 +247,27 @@ export class SessionHub {
     }
     /** Mark a turn finished; retain its buffer briefly for an end-of-turn reconnect. */
     end(turn) {
+        if (!turn.running)
+            return; // already ended — never fire onTurnEnd twice
         turn.running = false;
         if (turn.sessionId) {
             this.fireActive(turn);
             turn.evictTimer = setTimeout(() => this.evict(turn), COMPLETED_TTL_MS);
             turn.evictTimer.unref?.();
+            // #627: the session is idle again — let the WS layer deal with anything
+            // queued behind this turn. Never allowed to throw into a caller finalizing
+            // its turn. A pending cancel intent belongs to THIS end, so consume it.
+            const cancel = this.cancels.get(turn.sessionId);
+            this.cancels.delete(turn.sessionId);
+            if (this.onTurnEnd) {
+                const { sessionId, projectSlug, origin } = turn;
+                try {
+                    this.onTurnEnd({ sessionId, projectSlug, origin, ...(cancel ? { cancel } : {}) });
+                }
+                catch {
+                    /* a drain that throws must not break turn teardown */
+                }
+            }
         }
     }
     /**

package/packages/server/dist/turn-interlock.js

@@ -29,6 +29,14 @@ export async function quiesceSession(deps, sessionId, opts = {}) {
     const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS);
     const cancelled = new Set();
     let reaped = false;
+    // Mark the turn end this is about to cause as OURS, not a user's Stop. The WS
+    // layer treats the two oppositely for anything queued behind the turn: a Stop
+    // hands the message back to the user's composer, while this caller is about to
+    // delete, revert or promote the transcript — so the queue must be left strictly
+    // alone. Draining it here would start a fresh turn on a chat being removed (the
+    // #730 resurrection), and would make the session busy again so the poll below
+    // could never settle.
+    deps.hub?.noteCancel(sessionId, { reason: "quiesce", origin: null });
     for (;;) {
         const jobId = deps.hub?.activeInfo(sessionId)?.jobId ?? null;
         if (jobId && !cancelled.has(jobId)) {

package/packages/server/dist/ws-protocol.d.ts

@@ -214,10 +214,23 @@ export interface ChatSetQueueMessage {
         /** The queued message text, or null/empty to clear. */
         text?: string | null;
         /**
-         * Client-stamped identity of this queued message (#245): the ms timestamp of
-         * when it was first enqueued, stable across reloads. The server records the ts
-         * of the message it last drained per session so it can skip re-sending a stale
-         * copy a reloaded client re-asserts. Absent → the server stamps `Date.now()`.
+         * OPAQUE identity of this client's queue (#245 stable identity, #736). Minted
+         * once when the queue is first created and kept across edits, appends and
+         * reloads, so the server can tell (a) this client updating its own queue apart
+         * from another client queueing alongside it (#629) and (b) a stale re-assert of
+         * an already-drained message apart from a new one — by EQUALITY, never ordering.
+         *
+         * Absent from an older client, which sends only `ts`; the server folds that
+         * into an id.
+         */
+        qid?: string | null;
+        /**
+         * Legacy client-stamped enqueue time (#245). Superseded by `qid`: it was used
+         * as an ORDERED identity, so one client with a fast clock poisoned the dedup
+         * marker and every later queued message on that chat — from any client — was
+         * silently destroyed (#736). Still accepted (older clients send it, and it
+         * still identifies a message) but only ever compared for equality, and never
+         * stored as the enqueue time — the server stamps that itself.
          */
         ts?: number | null;
     };
@@ -382,6 +395,64 @@ export interface ChatQueuedFlushedMessage {
         text?: string;
     };
 }
+/**
+ * The chat's queued message changed (#629). Broadcast to EVERY socket attached to
+ * the session whenever the slot is written, so the queue is shared chat state that
+ * all clients render identically instead of invisible per-client state.
+ *
+ * Before this, a queue was only ever written and never announced: a second client
+ * queueing on the same chat overwrote the first client's text with no signal to
+ * anyone. The first user's chip sat there showing a message that no longer existed,
+ * and when the drain finally fired, their transcript rendered — as their own user
+ * bubble — a message they had never typed. The slot now MERGES contributions, and
+ * this frame is what makes the merge visible.
+ */
+export interface ChatQueuedStateMessage {
+    type: "chat:queued_state";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        /** The chat's full queued text, or null when the slot is now empty. */
+        text: string | null;
+        /**
+         * The slot's identity. A client adopts it as its own queue id, so its next
+         * edit updates this shared slot in place rather than appending beside it.
+         */
+        qid?: string;
+        /**
+         * Why the slot changed, when it is worth explaining. `returned` means a user
+         * pressed Stop and the message went back to THEIR composer — sent to the
+         * other clients so a chip that just vanished from under them has a reason
+         * attached, rather than looking like the message evaporated. The client that
+         * pressed Stop is excluded from this broadcast; it gets
+         * {@link ChatQueuedReturnedMessage} instead.
+         */
+        reason?: "returned";
+    };
+}
+/**
+ * A user pressed Stop, so the message queued behind that turn is handed BACK to
+ * them (#751 follow-up). Sent only to the socket that asked to cancel.
+ *
+ * Stop means "give me control back". Auto-sending the follow-up would have the
+ * agent start working again the instant the user stopped it, and holding the
+ * message server-side is what stranded it (#627) — so it returns to the composer,
+ * where it is visible, editable, and sent only when the user says so.
+ *
+ * Deliberately NOT `chat:queued_flushed` with a flag: that frame means "this text
+ * was sent, render it as the user's bubble", and a returned message is precisely
+ * one that was NOT sent. Overloading it risks a phantom user turn in the
+ * transcript for a message the agent never received.
+ */
+export interface ChatQueuedReturnedMessage {
+    type: "chat:queued_returned";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        /** The queued text, for the client to put back in its composer. */
+        text: string;
+    };
+}
 /**
  * A background task was killed at the turn boundary and the keeper is idle
  * (issue #347). Broadcast LIVE by the recovery engine the moment the kill is
@@ -418,6 +489,6 @@ export interface ChatNoticeMessage {
 export interface PongMessage {
     type: "pong";
 }
-export type ServerMessage = ChatResponseMessage | ChatToolCallMessage | ChatToolStartMessage | ChatMessageBoundaryMessage | ChatCompleteMessage | ChatErrorMessage | ChatResyncMessage | ChatActiveMessage | ChatQueuedFlushedMessage | ChatKilledTaskMessage | ChatNoticeMessage | PongMessage;
+export type ServerMessage = ChatResponseMessage | ChatToolCallMessage | ChatToolStartMessage | ChatMessageBoundaryMessage | ChatCompleteMessage | ChatErrorMessage | ChatResyncMessage | ChatActiveMessage | ChatQueuedFlushedMessage | ChatQueuedStateMessage | ChatQueuedReturnedMessage | ChatKilledTaskMessage | ChatNoticeMessage | PongMessage;
 export declare function isClientMessage(data: unknown): data is ClientMessage;
 export {};

package/packages/server/dist/ws-protocol.js

@@ -245,6 +245,8 @@ export function isClientMessage(data) {
             return false;
         if (p.ts !== undefined && p.ts !== null && typeof p.ts !== "number")
             return false;
+        if (p.qid !== undefined && p.qid !== null && typeof p.qid !== "string")
+            return false;
         return true;
     }
     return false;

package/packages/server/dist/ws.d.ts

@@ -1,55 +1,3 @@
-/**
- * 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 type { WebSocket } from "@fastify/websocket";
 export * from "./ws-protocol.js";
 import type { ChatHandlerDeps } from "./ws-context.js";