@edspencer/paddock 0.66.0 → 0.66.2

package/packages/server/dist/routes/projects.js

@@ -13,7 +13,14 @@ import { quiesceProject, turnRunningError } from "../turn-interlock.js";
  * (#553): the badge's semantics are "whatever this function returns", and there
  * is no second implementation for the root to drift from. The completed-turn
  * side comes from the cheap job-record scan (grouped by keeper agent), so this
- * costs no `listSessions` fan-out and no transcript parse.
+ * costs no transcript parse; `live` adds one cached session listing per
+ * workspace (see {@link liveSessionIds}).
+ *
+ * Two things are pruned OUT of the raw job-record fold, and the invariant they
+ * add up to is: **the badge counts exactly what the Home Unread feed counts.**
+ * A chat that no longer exists, and a chat the user archived. #488 made read
+ * state server-authoritative so surfaces could not diverge; a badge counting
+ * chats `/chats/attention` does not is that divergence one layer up.
  *
  * `key` is a WORKSPACE key, so `""` (the root) is a perfectly ordinary argument:
  * `turnsByProject` is already keyed that way (`lastTurnCompletedAtByProject`
@@ -21,12 +28,27 @@ import { quiesceProject, turnRunningError } from "../turn-interlock.js";
  * `keeperAgentName("")` encodes to `keeper-_root`. Nothing here may test `key`
  * for truthiness.
  */
-async function buildChatTurns(key, turnsByProject, user, readState, unread) {
+async function buildChatTurns(key, turnsByProject, live, user, readState, unread, archive) {
     const bySession = turnsByProject.get(key);
     if (!bySession)
         return [];
     const keeper = keeperAgentName(key);
-    return Promise.all([...bySession].map(async ([sessionId, lastTurnCompletedAt]) => {
+    const rows = await Promise.all([...bySession].map(async ([sessionId, lastTurnCompletedAt]) => {
+        // #732, prune 1 — a chat that no longer exists. The job records this fold
+        // reads are removed with the chat now, but that cannot heal a badge
+        // already stuck, and a transcript can leave by routes that are not a
+        // delete at all (an adoption undone, a JSONL removed by hand). `live` is
+        // `null` when the listing FAILED, which is not the same as empty: an
+        // unreadable chat store must leave the badge alone, not silently zero it.
+        if (live && !live.has(sessionId))
+            return null;
+        // #732, prune 2 — archiving is the user saying "stop bothering me about
+        // this one", and `/chats/attention` has always honoured that. The badge
+        // did not, so the sidebar could read 3 while the Home Unread feed showed
+        // nothing. One rule, both surfaces: archived is silent. It is silenced,
+        // not consumed — unarchiving brings the chat back to both.
+        if (await archive.isArchived(keeper, sessionId).catch(() => false))
+            return null;
         const lastSeen = await readState.getLastSeen(user, keeper, sessionId).catch(() => 0);
         // Manual unread override (#458): carry it so the sidebar's workspace
         // unread badge counts a manually-flagged chat, staying in step with
@@ -39,14 +61,42 @@ async function buildChatTurns(key, turnsByProject, user, readState, unread) {
             ...(isUnread ? { unread: true } : {}),
         };
     }));
+    return rows.filter((r) => r !== null);
+}
+/**
+ * The session ids a workspace actually still has, for {@link buildChatTurns}'s
+ * prune — or `null` if we could not find out.
+ *
+ * That distinction is the whole point: a failed listing must NOT be read as "no
+ * chats", or a transient discovery error would empty the badge instead of
+ * leaving it alone. `listSessions` is a superset of the keeper chats the fold
+ * covers (it also returns hook-agent chats), which is the safe direction — it
+ * can only fail to prune, never over-prune.
+ *
+ * This costs one session listing per workspace on `GET /api/projects`, which
+ * #529 was careful to keep off this route. It is affordable because it is not
+ * the expensive half: the listing is a cached directory read (core's discovery
+ * cache is mtime-keyed with a TTL), whereas the 61%-of-CPU problem #529 fixed
+ * was YAML-parsing every job record. `/chats/attention` already does exactly
+ * this listing across the whole fleet on the Home tab.
+ */
+async function liveSessionIds(herdctl, project) {
+    if (!project)
+        return null;
+    try {
+        return new Set((await herdctl.listSessions(project)).map((s) => s.sessionId));
+    }
+    catch {
+        return null;
+    }
 }
 export function registerProjectRoutes(app, ctx) {
-    const { projects, herdctl, git, readState, unread, readStateUser } = ctx;
+    const { projects, herdctl, git, readState, unread, archive, readStateUser } = ctx;
     app.get("/api/projects", {
         schema: {
             tags: ["Projects"],
             summary: "List projects",
-            description: "Returns `{ projects, root }`. `projects` is an array of the root workspace's CHILDREN; each entry carries the project metadata plus a compact `chatTurns` array (per-chat `{ sessionId, lastTurnCompletedAt, lastSeen? }` for the sidebar UNREAD count) and a `dirty` uncommitted-file count. `root` is the ROOT workspace itself, carrying the same `chatTurns` field so the sidebar's Home entry gets the identical badge; it is `null` only if the root record could not be read.",
+            description: "Returns `{ projects, root }`. `projects` is an array of the root workspace's CHILDREN; each entry carries the project metadata plus a compact `chatTurns` array (per-chat `{ sessionId, lastTurnCompletedAt, lastSeen? }` for the sidebar UNREAD count) and a `dirty` uncommitted-file count. `chatTurns` covers only chats that still EXIST and are not ARCHIVED, so the badge cannot outlive its chats (#732) and agrees with `/chats/attention` on archived ones. `root` is the ROOT workspace itself, carrying the same `chatTurns` field so the sidebar's Home entry gets the identical badge; it is `null` only if the root record could not be read.",
             response: {
                 200: {
                     description: "Object with a `projects` array (each item a project enriched with `chatTurns` and `dirty`) and a `root` workspace object enriched with `chatTurns`.",
@@ -79,7 +129,7 @@ export function registerProjectRoutes(app, ctx) {
         const user = readStateUser(req);
         const projectsOut = await Promise.all(list.map(async (p) => ({
             ...p,
-            chatTurns: await buildChatTurns(p.slug, turnsByProject, user, readState, unread),
+            chatTurns: await buildChatTurns(p.slug, turnsByProject, await liveSessionIds(herdctl, p), user, readState, unread, archive),
             // The cheap store-wide sweep above buckets by path segment under
             // `projectsRoot`, so it can only speak for projects whose working dir is
             // the metadata dir. For one pointing somewhere else (a linked checkout,
@@ -94,7 +144,10 @@ export function registerProjectRoutes(app, ctx) {
         // a file directly in the projects root has no bucket at all. Reporting 0
         // would be a fabricated clean; the field is optional, so it stays absent.
         const rootOut = root
-            ? { ...root, chatTurns: await buildChatTurns(ROOT_KEY, turnsByProject, user, readState, unread) }
+            ? {
+                ...root,
+                chatTurns: await buildChatTurns(ROOT_KEY, turnsByProject, await liveSessionIds(herdctl, root), user, readState, unread, archive),
+            }
             : null;
         return { projects: projectsOut, root: rootOut };
     });
@@ -437,6 +490,17 @@ export function registerProjectWorkspaceRoutes(app, ctx) {
             catch (err) {
                 req.log.warn({ err }, "keeper-agent unregister failed (project dir already removed)");
             }
+            // #734: and its herdctl JOB RECORDS, which `remove()` cannot reach — they
+            // live in the shared fleet-wide jobs dir, not under the project. They are
+            // keyed by agent name, which is derived from the slug, which is derived
+            // from the NAME: leaving them behind means a project created later with
+            // the same name inherits this one's run history — prompt text and reply
+            // summaries — plus a phantom unread badge over zero chats.
+            await herdctl
+                .purgeProjectJobs(project.slug, Object.keys(project.hooks ?? {}), Object.keys(project.triggers ?? {}))
+                .catch((err) => {
+                req.log.warn({ err }, "job-record purge failed (project is still deleted)");
+            });
             return reply.code(200).send({ ok: true, slug: project.slug });
         }
         catch (err) {

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,12 +214,45 @@ 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;
+        /**
+         * Files staged in the composer that must ride the queued message (#728).
+         *
+         * Attachments used to be consumed ONLY by `chat:send`, so a message queued
+         * during a live turn left them staged: the tray never cleared and the file
+         * silently rode whatever the user sent next — a message they never meant to
+         * attach it to. They belong to the queued message, so they travel with it into
+         * the shared slot and are sent by the drain.
+         *
+         * Merged into the slot as a UNION BY ID, never a replace: a write can only
+         * ever ADD to what is staged, so one client's `set_queue` cannot silently drop
+         * another's file, and a client re-asserting its queue on reload (which by then
+         * has an empty tray) is a no-op rather than a wipe. Attachments leave the slot
+         * only when it is cleared outright or popped back to a composer.
+         */
+        attachments?: Array<{
+            id: string;
+            filename: string;
+            kind?: string;
+        }>;
     };
 }
 /**
@@ -380,6 +413,96 @@ export interface ChatQueuedFlushedMessage {
          * when the frame is just telling the client to clear a stale/already-sent copy.
          */
         text?: string;
+        /**
+         * The attachments that rode the drained message (#728), so the client renders
+         * the auto-sent user bubble with its files exactly as a live send does. Only
+         * present alongside `text` (a clear-only frame carries neither).
+         */
+        attachments?: Array<{
+            id: string;
+            filename: string;
+            kind?: 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 files staged on the slot (#728). Shared exactly like the text is: every
+         * attached client renders the same chips, so a file queued on one device is
+         * visible on the other rather than being invisible state that surfaces only
+         * when the drain sends it. Absent/empty when the slot holds no attachments.
+         */
+        attachments?: Array<{
+            id: string;
+            filename: string;
+            kind?: string;
+        }>;
+        /**
+         * 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;
+        /**
+         * The files that were staged on the slot (#728), for the client to put back in
+         * its attachment tray. Stop returns the whole message, not just its prose —
+         * dropping the files here would be the same silent loss under a different name,
+         * and leaving them on the (now cleared) slot would strand them server-side.
+         */
+        attachments?: Array<{
+            id: string;
+            filename: string;
+            kind?: string;
+        }>;
     };
 }
 /**
@@ -418,6 +541,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

@@ -166,6 +166,28 @@ export function resolveTurnUsage(state) {
         outputTokens: Math.max(base.outputTokens, state.cumulative?.outputTokens ?? 0),
     };
 }
+/**
+ * Validate an optional wire list of composer attachment refs (#328/#728). Shared
+ * by `chat:send` and `chat:set_queue` — the queue carries the same refs the send
+ * does, so it validates them the same way rather than by a second, drifting copy.
+ * `undefined` is valid (the field is optional everywhere it appears).
+ */
+function isAttachmentRefList(v) {
+    if (v === undefined)
+        return true;
+    if (!Array.isArray(v))
+        return false;
+    for (const a of v) {
+        if (!a || typeof a !== "object")
+            return false;
+        const ao = a;
+        if (typeof ao.id !== "string" || typeof ao.filename !== "string")
+            return false;
+        if (ao.kind !== undefined && typeof ao.kind !== "string")
+            return false;
+    }
+    return true;
+}
 export function isClientMessage(data) {
     if (typeof data !== "object" || data === null)
         return false;
@@ -187,19 +209,8 @@ export function isClientMessage(data) {
             return false;
         if (p.model !== undefined && typeof p.model !== "string")
             return false;
-        if (p.attachments !== undefined) {
-            if (!Array.isArray(p.attachments))
-                return false;
-            for (const a of p.attachments) {
-                if (!a || typeof a !== "object")
-                    return false;
-                const ao = a;
-                if (typeof ao.id !== "string" || typeof ao.filename !== "string")
-                    return false;
-                if (ao.kind !== undefined && typeof ao.kind !== "string")
-                    return false;
-            }
-        }
+        if (!isAttachmentRefList(p.attachments))
+            return false;
         return p.sessionId === undefined || p.sessionId === null || typeof p.sessionId === "string";
     }
     if (m.type === "chat:command") {
@@ -245,6 +256,12 @@ 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;
+        // The queued message carries the composer's staged files (#728), validated
+        // exactly as `chat:send` validates its own.
+        if (!isAttachmentRefList(p.attachments))
+            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";