@edspencer/paddock 0.66.1 → 0.67.0

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

@@ -134,20 +134,23 @@ export function registerChatWorkspaceRoutes(app, ctx) {
      *
      * `running` is authoritative (the live hub), not inferred from timestamps.
      * `unread` reuses the sidebar badge's derivation — the manual override (#458)
-     * or a completed turn newer than the read watermark (#189) — with ONE
-     * deliberate difference: archived chats are filed away on purpose, so they
-     * are excluded here. That means an archived chat with an unread turn still
-     * counts toward the sidebar's badge (`buildChatTurns` never consults
-     * `ArchiveStore`) while not appearing in this list. The two can therefore
-     * disagree by exactly that set; making them agree means teaching the badge
-     * about archiving, which is a behaviour change to the badge, not to this
-     * route.
+     * or a completed turn newer than the read watermark (#189) — INCLUDING the
+     * archived exclusion below.
+     *
+     * That last part used to be this route's alone: the badge never consulted
+     * `ArchiveStore`, so an archived unread chat counted toward the sidebar while
+     * being absent from this feed, and the two surfaces disagreed by exactly that
+     * set. #732 settled it the way this route already read it — archiving is the
+     * user filing a chat away, so it silences both — and `buildChatTurns` now
+     * applies the same rule. Keep the two in step: read state was made
+     * server-authoritative (#488) so surfaces could not diverge, and a rule that
+     * lives in only one of them is that divergence again.
      */
     app.get("/chats/attention", {
         schema: {
             tags: ["Chats"],
             summary: "List the chats in this workspace's subtree that are running or unread",
-            description: "Returns `{ running, unread }` — the chats in this workspace AND its descendants that currently have a live turn (`running`) or hold an unread reply (`unread`). Each row is a chat DTO plus the `projectSlug`/`projectName` it belongs to, so a fleet-wide list stays attributable. On the root mount (`/api/root/chats/attention`) the subtree is the whole instance, because the root workspace's key (`\"\"`) prefixes every workspace key; on a project mount it is that project alone. A chat is never in both lists: a live turn hasn't landed a reply yet, so running wins.",
+            description: "Returns `{ running, unread }` — the chats in this workspace AND its descendants that currently have a live turn (`running`) or hold an unread reply (`unread`). Each row is a chat DTO plus the `projectSlug`/`projectName` it belongs to, so a fleet-wide list stays attributable. On the root mount (`/api/root/chats/attention`) the subtree is the whole instance, because the root workspace's key (`\"\"`) prefixes every workspace key; on a project mount it is that project alone. A chat is never in both lists: a live turn hasn't landed a reply yet, so running wins. `running` rows additionally carry resolved `contextTokens`/`contextLimit` so a caller can draw a context gauge for live work; `unread` rows do not, because resolving usage streams a transcript per chat and only the running set is bounded by how many turns can be in flight at once.",
             params: {
                 type: "object",
                 properties: {
@@ -194,7 +197,19 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                 const provenanceOf = (s) => runProvenance.get(s.sessionId);
                 const triggerOf = makeTriggerResolver(p);
                 const parentOf = makeParentResolver(runProvenance, messageProvenance, p.slug, (id) => parentDetach.isDetached(keeper, id));
-                const chats = await buildProjectChats(p.dir, sessions, undefined, archivedOf, lastTurnAt, lastSeenOf, provenanceOf, triggerOf, starredOf, unreadOf, parentOf);
+                // Usage is deliberately NOT resolved for the whole subtree: it streams
+                // a transcript per chat, and this route refetches on every turn
+                // boundary across the fleet. A RUNNING chat is the one exception —
+                // every context gauge in the app (Home's running rows, the fleet
+                // readout) reads `contextTokens`/`contextLimit` off these rows, and
+                // with no resolver they were always null, so the gauges rendered
+                // blank. The running set is bounded by how many turns can be in
+                // flight at once (a handful), not by how many chats the instance
+                // holds, so the cost stays proportional to live work and not to
+                // history.
+                const usageOf = chatUsageResolver(p.dir, p.model ?? DEFAULT_MODEL);
+                const usageIfRunning = async (s) => isRunning(s.sessionId) ? usageOf(s) : null;
+                const chats = await buildProjectChats(p.dir, sessions, usageIfRunning, archivedOf, lastTurnAt, lastSeenOf, provenanceOf, triggerOf, starredOf, unreadOf, parentOf);
                 for (const c of chats) {
                     const row = { ...c, projectSlug: p.slug, projectName: p.name };
                     if (isRunning(c.sessionId)) {
@@ -632,6 +647,13 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             }
             await cleanupAttachments(agent, req.params.sessionId);
             const { removed, retained } = await herdctl.deleteSession(agent, req.params.sessionId);
+            // #732: and the chat's herdctl job records, which are what feeds the
+            // sidebar unread badge. Left behind, they kept the badge counting a chat
+            // there was nothing left to open to clear. Only when the transcript was
+            // actually REMOVED — see `purgeSessionJobs` for why a `retained`
+            // (released) chat keeps its records.
+            if (removed)
+                await herdctl.purgeSessionJobs([req.params.sessionId]);
             // Drop any archived/starred/unread/detached flag so a future session id
             // can't inherit it. (Read-state watermarks, other users' unread overrides,
             // provenance and any queued message are deliberately NOT swept here — that
@@ -1248,6 +1270,10 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             const user = readStateUser(req);
             const removed = [];
             const failed = [];
+            // The subset whose transcript was genuinely deleted — the ids whose job
+            // records may be purged (#732). Narrower than `removed`, which also
+            // holds RELEASED chats: those are still listed, so their records stay.
+            const deleted = [];
             for (const sessionId of sessionIds) {
                 try {
                     // #731: same interlock as the single delete, per id. A chat whose
@@ -1270,11 +1296,16 @@ export function registerChatWorkspaceRoutes(app, ctx) {
                         removed.push(sessionId);
                     else
                         failed.push(sessionId);
+                    if (gone.removed)
+                        deleted.push(sessionId);
                 }
                 catch {
                     failed.push(sessionId);
                 }
             }
+            // ONE jobs-dir pass for the whole batch (#732) — purging per chat would
+            // re-scan the shared directory once per id, up to 500 times.
+            await herdctl.purgeSessionJobs(deleted);
             // Drop the archived/starred/unread/detached flags of the chats that were
             // ACTUALLY removed, so a recycled session id can't inherit stale state.
             //

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

@@ -1,6 +1,6 @@
 import { resolveAttachmentsConfig, maxFileBytes, isTypeAllowed, } from "../attachments-config.js";
 import { inferAttachmentKind } from "../attachments-hint.js";
-import { buildInstanceConfig, writeInstanceConfig, validatePatch, instanceConfigPath, InstanceConfigError, } from "../instance-config.js";
+import { buildInstanceConfig, writeInstanceConfig, validatePatch, instanceConfigPath, instanceConfigVersion, InstanceConfigError, } from "../instance-config.js";
 import { TranscriptionError } from "../transcribe.js";
 import { resolveModels, resolveDefaultModel } from "../models.js";
 import { sendProjectError } from "../route-errors.js";
@@ -134,7 +134,7 @@ export function registerMetaRoutes(app, ctx) {
         schema: {
             tags: ["System"],
             summary: "Read instance-wide config",
-            description: "Reports every surfaced instance-config field (value / default / editable / sensitive / env-shadow) for the top-level admin screen. Returns a JSON object keyed by field.",
+            description: "Reports every surfaced instance-config field for the top-level admin screen: `value` (effective in the running, boot-frozen process), `pendingValue` (what a restart would resolve, read from paddock.config.yaml on every request), `pendingRestart`, plus default / editable / sensitive / env-shadow flags. Top level carries `restartRequired` (any field diverges), `configPath`, and `configVersion` — a fingerprint of the file to echo back as `expectedVersion` on the PUT.",
             response: {
                 200: {
                     description: "Instance config snapshot.",
@@ -148,13 +148,16 @@ export function registerMetaRoutes(app, ctx) {
         schema: {
             tags: ["System"],
             summary: "Write instance-wide config",
-            description: "Writes the editable subset of the instance config to paddock.config.yaml (comment-preserving, atomic). Writes DO NOT hot-apply — the config is frozen at boot — so a successful write returns `{ restartRequired: true, configPath }` and the process keeps its current config until it restarts. Returns 400 on a malformed patch or invalid field, 500 on write failure.",
+            description: "Writes the editable subset of the instance config to paddock.config.yaml (comment-preserving, atomic). Writes DO NOT hot-apply — the config is frozen at boot — so a successful write returns `{ restartRequired: true, configPath, configVersion }` and the process keeps its current config until it restarts. A `null` value clears that key (the built-in default applies again). Pass `expectedVersion` (the `configVersion` from the GET you were editing) to make the write conditional: 409 if the file changed underneath you, instead of silently overwriting another editor. Returns 400 on a malformed patch, an invalid/read-only/env-shadowed field, 500 on write failure.",
             body: {
                 // Documentation-only (no validation/coercion): accept any/empty body.
                 type: ["object", "null"],
                 additionalProperties: true,
                 properties: {
                     patch: { description: "Map of config field name to new value to write." },
+                    expectedVersion: {
+                        description: "Optional. The `configVersion` this patch was composed against; the write is refused with 409 if the file no longer matches.",
+                    },
                 },
             },
             response: {
@@ -163,6 +166,11 @@ export function registerMetaRoutes(app, ctx) {
                     type: "object",
                     additionalProperties: true,
                 },
+                409: {
+                    description: "`expectedVersion` no longer matches the file — another writer got there first. Nothing was written.",
+                    type: "object",
+                    additionalProperties: true,
+                },
             },
         },
     }, async (req, reply) => {
@@ -180,14 +188,33 @@ export function registerMetaRoutes(app, ctx) {
             }
             throw err;
         }
+        const configPath = instanceConfigPath(cfg);
+        // Optimistic concurrency (#722). Opt-in — a client that sends no
+        // `expectedVersion` (curl, a script) writes unconditionally, as before —
+        // but the UI always sends one, so two tabs editing the same file now
+        // collide loudly instead of the second silently erasing the first.
+        if (Object.prototype.hasOwnProperty.call(req.body ?? {}, "expectedVersion")) {
+            const current = instanceConfigVersion(configPath);
+            if (current !== (req.body?.expectedVersion ?? null)) {
+                return reply.code(409).send({
+                    error: "The config file changed on disk since this page loaded (another tab, or an editor). Nothing was written — reload the settings and apply your changes again.",
+                    code: "config_conflict",
+                    configVersion: current,
+                });
+            }
+        }
         try {
-            writeInstanceConfig(instanceConfigPath(cfg), pairs);
+            writeInstanceConfig(configPath, pairs);
         }
         catch (err) {
             return reply.code(500).send({ error: `failed to write config file: ${err.message}` });
         }
         // The write lands in the file but NOT in the running (frozen) config.
-        return { restartRequired: true, configPath: instanceConfigPath(cfg) };
+        return {
+            restartRequired: true,
+            configPath,
+            configVersion: instanceConfigVersion(configPath),
+        };
     });
     // Selectable models + the keeper/sweeper defaults (CONTRACT-v3 §3). The offered
     // models are the instance ALLOW-LIST (issue #457 Step 2): the built-in catalog

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

@@ -72,6 +72,14 @@ interface Turn {
     baseSeq: number;
     nextSeq: number;
     running: boolean;
+    /**
+     * Epoch-ms the turn began. The hub is the only place that knows this: a job
+     * record is written when a turn ENDS, and the transcript's own timestamps are
+     * the model's, not the run's. Surfaced on {@link ActiveInfo} so a client that
+     * loads mid-turn — or reconnects — can still say how long the fleet has been
+     * working, rather than restarting every clock at zero on every page load.
+     */
+    startedAt: number;
     evictTimer: ReturnType<typeof setTimeout> | null;
 }
 /** How long a completed turn's buffer lingers so an end-of-turn reconnect still gets the tail. */
@@ -97,6 +105,8 @@ export interface ActiveInfo {
     /** The running turn's cancellable job id, if known yet (null early in a turn). */
     jobId: string | null;
     running: boolean;
+    /** Epoch-ms this turn started. See {@link Turn.startedAt}. */
+    startedAt: number;
 }
 /** Why a turn is being cancelled, and which socket asked for it. */
 export interface CancelIntent {

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

@@ -107,6 +107,7 @@ export class SessionHub {
             baseSeq: 0,
             nextSeq: 0,
             running: true,
+            startedAt: Date.now(),
             evictTimer: null,
         };
         const handle = new TurnHandle(this, turn);
@@ -203,14 +204,26 @@ export class SessionHub {
         const turn = this.bySession.get(sessionId);
         if (!turn || !turn.running)
             return null;
-        return { sessionId, projectSlug: turn.projectSlug, jobId: turn.jobId, running: true };
+        return {
+            sessionId,
+            projectSlug: turn.projectSlug,
+            jobId: turn.jobId,
+            running: true,
+            startedAt: turn.startedAt,
+        };
     }
     /** Snapshot of every session with a running turn (for a newly-connected client). */
     runningSessions() {
         const out = [];
         for (const [sessionId, turn] of this.bySession) {
             if (turn.running) {
-                out.push({ sessionId, projectSlug: turn.projectSlug, jobId: turn.jobId, running: true });
+                out.push({
+                    sessionId,
+                    projectSlug: turn.projectSlug,
+                    jobId: turn.jobId,
+                    running: true,
+                    startedAt: turn.startedAt,
+                });
             }
         }
         return out;
@@ -288,6 +301,7 @@ export class SessionHub {
             projectSlug: turn.projectSlug,
             jobId: turn.jobId,
             running: turn.running,
+            startedAt: turn.startedAt,
         });
     }
     recipients(turn) {

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

@@ -233,6 +233,26 @@ export interface ChatSetQueueMessage {
          * 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;
+        }>;
     };
 }
 /**
@@ -373,6 +393,21 @@ export interface ChatActiveMessage {
         /** The running turn's cancellable job id, when known. */
         jobId: string | null;
         running: boolean;
+        /**
+         * Epoch-ms the running turn began, from the session hub. The hub is the only
+         * thing that knows: a job record is written when a turn ENDS, and the
+         * transcript's timestamps are the model's rather than the run's. Because the
+         * server replays its whole running snapshot to every socket on connect, a
+         * client that reloads mid-turn still learns the true start — which is what
+         * lets a fleet readout say "running 12:04" instead of restarting at zero on
+         * every page load.
+         *
+         * Sent on the STOP frame too (`running: false`), where it describes the turn
+         * that just ended and a client has no use for it — the hub emits one frame
+         * shape for both transitions rather than branching. Optional on the wire so
+         * a client built against an older server still parses the frame.
+         */
+        startedAt?: number;
     };
 }
 /**
@@ -393,6 +428,16 @@ 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;
+        }>;
     };
 }
 /**
@@ -414,6 +459,17 @@ export interface ChatQueuedStateMessage {
         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.
@@ -451,6 +507,17 @@ export interface ChatQueuedReturnedMessage {
         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;
+        }>;
     };
 }
 /**

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") {
@@ -247,6 +258,10 @@ export function isClientMessage(data) {
             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;