@edspencer/paddock 0.66.1 → 0.67.0

package/packages/server/dist/project-paths.d.ts

@@ -71,9 +71,54 @@ export declare function repoCheckoutName(repo: string): string;
  * (it does NOT follow symlinks — callers that care resolve them beforehand).
  *
  * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
- * `/data/projects-old` a child of `/data/projects`.
+ * `/data/projects-old` a child of `/data/projects`. It does NOT hold for the one
+ * parent whose string already ends in a separator — the filesystem root — where
+ * appending would ask for `"//"` and report every child as outside (issue #719).
+ * That made the bidirectional overlap guard in `validatePath` fail open in both
+ * directions once any project's working dir was `/`, so two keepers could be
+ * created with overlapping working trees. Append the separator only when the
+ * parent doesn't already end in one.
  */
 export declare function isPathInside(child: string, parent: string): boolean;
+/**
+ * Directories beneath which a project may never be linked (issue #720) — the
+ * operating system rather than anybody's work.
+ *
+ * Each entry denies itself and everything under it. The filesystem root is
+ * handled separately in {@link isSystemPath}: it is refused by exact match, not
+ * by containment, because since #719 EVERY absolute path is "inside" `/`.
+ *
+ * This is a floor, not an allow-list. The alternative the issue floated —
+ * requiring linked paths to sit under a configurable allowed root — is a bigger
+ * lever than the problem needs: it adds a config dimension and would invalidate
+ * every already-linked project the day it shipped. A denylist only ever refuses
+ * paths nobody legitimately links a project at.
+ *
+ * Deliberately NOT here: `/opt`, `/srv`, `/mnt`, `/tmp`, `/root` and `/var` —
+ * each is somewhere a real checkout or notebook plausibly lives (`/var` in
+ * particular holds Paddock's own data dir on some boxes, and macOS temp dirs
+ * canonicalise under `/private/var`).
+ *
+ * On most distros `/bin`, `/sbin` and `/lib*` are symlinks into `/usr`;
+ * {@link import("./projects.js").ProjectStore.validatePath} canonicalises before
+ * checking, so those are caught by the `/usr` entry too. They are listed anyway
+ * for the systems where they are real directories.
+ */
+export declare const SYSTEM_PATH_DENYLIST: readonly ["/bin", "/boot", "/dev", "/etc", "/lib", "/lib32", "/lib64", "/libx32", "/proc", "/run", "/sbin", "/sys", "/usr"];
+/**
+ * Whether a (resolved) path is the filesystem root or sits inside a system
+ * directory — the floor beneath which {@link
+ * import("./projects.js").ProjectStore.validatePath} refuses to link a project
+ * (issue #720).
+ *
+ * This is a FOOTGUN guard, not a privilege boundary: anyone who can reach the
+ * projects API can already create projects and run turns as whoever Paddock runs
+ * as. It exists because the failure is silent and the blast radius is large — a
+ * linked project's directory becomes a keeper's cwd, that keeper runs
+ * `acceptEdits` by default, and a MANAGED project's `contentDir` IS that
+ * directory, so the sweeper writes `CLAUDE.md`/`CHANGELOG.md` into it.
+ */
+export declare function isSystemPath(candidate: string): boolean;
 /**
  * Resolve a project's working directory (keeper cwd) from its metadata dir plus
  * whichever backing field is set:

package/packages/server/dist/project-paths.js

@@ -79,12 +79,76 @@ export function repoCheckoutName(repo) {
  * (it does NOT follow symlinks — callers that care resolve them beforehand).
  *
  * The `+ path.sep` is load-bearing: a plain `startsWith(parent)` would call
- * `/data/projects-old` a child of `/data/projects`.
+ * `/data/projects-old` a child of `/data/projects`. It does NOT hold for the one
+ * parent whose string already ends in a separator — the filesystem root — where
+ * appending would ask for `"//"` and report every child as outside (issue #719).
+ * That made the bidirectional overlap guard in `validatePath` fail open in both
+ * directions once any project's working dir was `/`, so two keepers could be
+ * created with overlapping working trees. Append the separator only when the
+ * parent doesn't already end in one.
  */
 export function isPathInside(child, parent) {
     const c = path.resolve(child);
     const p = path.resolve(parent);
-    return c === p || c.startsWith(p + path.sep);
+    return c === p || c.startsWith(p.endsWith(path.sep) ? p : p + path.sep);
+}
+/**
+ * Directories beneath which a project may never be linked (issue #720) — the
+ * operating system rather than anybody's work.
+ *
+ * Each entry denies itself and everything under it. The filesystem root is
+ * handled separately in {@link isSystemPath}: it is refused by exact match, not
+ * by containment, because since #719 EVERY absolute path is "inside" `/`.
+ *
+ * This is a floor, not an allow-list. The alternative the issue floated —
+ * requiring linked paths to sit under a configurable allowed root — is a bigger
+ * lever than the problem needs: it adds a config dimension and would invalidate
+ * every already-linked project the day it shipped. A denylist only ever refuses
+ * paths nobody legitimately links a project at.
+ *
+ * Deliberately NOT here: `/opt`, `/srv`, `/mnt`, `/tmp`, `/root` and `/var` —
+ * each is somewhere a real checkout or notebook plausibly lives (`/var` in
+ * particular holds Paddock's own data dir on some boxes, and macOS temp dirs
+ * canonicalise under `/private/var`).
+ *
+ * On most distros `/bin`, `/sbin` and `/lib*` are symlinks into `/usr`;
+ * {@link import("./projects.js").ProjectStore.validatePath} canonicalises before
+ * checking, so those are caught by the `/usr` entry too. They are listed anyway
+ * for the systems where they are real directories.
+ */
+export const SYSTEM_PATH_DENYLIST = [
+    "/bin",
+    "/boot",
+    "/dev",
+    "/etc",
+    "/lib",
+    "/lib32",
+    "/lib64",
+    "/libx32",
+    "/proc",
+    "/run",
+    "/sbin",
+    "/sys",
+    "/usr",
+];
+/**
+ * Whether a (resolved) path is the filesystem root or sits inside a system
+ * directory — the floor beneath which {@link
+ * import("./projects.js").ProjectStore.validatePath} refuses to link a project
+ * (issue #720).
+ *
+ * This is a FOOTGUN guard, not a privilege boundary: anyone who can reach the
+ * projects API can already create projects and run turns as whoever Paddock runs
+ * as. It exists because the failure is silent and the blast radius is large — a
+ * linked project's directory becomes a keeper's cwd, that keeper runs
+ * `acceptEdits` by default, and a MANAGED project's `contentDir` IS that
+ * directory, so the sweeper writes `CLAUDE.md`/`CHANGELOG.md` into it.
+ */
+export function isSystemPath(candidate) {
+    const p = path.resolve(candidate);
+    if (p === path.parse(p).root)
+        return true;
+    return SYSTEM_PATH_DENYLIST.some((root) => isPathInside(p, root));
 }
 /**
  * Resolve a project's working directory (keeper cwd) from its metadata dir plus

package/packages/server/dist/project-types.d.ts

@@ -412,3 +412,26 @@ export type UpdateProjectInput = Partial<Pick<ProjectYaml, "name" | "status" | "
      */
     curation?: CurationOverride | null;
 };
+/**
+ * The plain metadata keys a PATCH may set — the RUNTIME half of
+ * {@link UpdateProjectInput} (issue #721).
+ *
+ * The type is a compile-time shape; the request body is not type-checked at all,
+ * so `update()` used to spread it straight into the record it persisted and any
+ * invented key landed in `project.yaml` verbatim. This list is what it filters
+ * against.
+ *
+ * It deliberately covers ONLY the blanket-spread fields. The tri-state overrides
+ * (`models`/`driveMode`/`maxSpawnDepth`/`hooksMcpEnabled`/`recovery`/
+ * `attachments`/`curation`) are destructured out and applied explicitly, because
+ * a spread cannot express "delete this field" — which is how an override is
+ * cleared back to inherit — so they are patchable without being listed here.
+ *
+ * Not here, and not patchable by any route: `slug`/`started` (identity),
+ * `pinned`/`triggers` (their own endpoints), and `path`/`managed`/`repo` — the
+ * three fields that decide the keeper's cwd (issues #206, #718).
+ *
+ * The `satisfies` clause is the drift guard: a key removed from `ProjectYaml`
+ * fails the build here rather than silently becoming un-patchable.
+ */
+export declare const PATCHABLE_KEYS: readonly ["name", "status", "domain", "group", "visibility", "summary", "links", "model", "permissionMode", "maxTurns", "docker"];

package/packages/server/dist/project-types.js

@@ -46,3 +46,38 @@ export function normalizeLinks(raw) {
     }
     return out;
 }
+/**
+ * The plain metadata keys a PATCH may set — the RUNTIME half of
+ * {@link UpdateProjectInput} (issue #721).
+ *
+ * The type is a compile-time shape; the request body is not type-checked at all,
+ * so `update()` used to spread it straight into the record it persisted and any
+ * invented key landed in `project.yaml` verbatim. This list is what it filters
+ * against.
+ *
+ * It deliberately covers ONLY the blanket-spread fields. The tri-state overrides
+ * (`models`/`driveMode`/`maxSpawnDepth`/`hooksMcpEnabled`/`recovery`/
+ * `attachments`/`curation`) are destructured out and applied explicitly, because
+ * a spread cannot express "delete this field" — which is how an override is
+ * cleared back to inherit — so they are patchable without being listed here.
+ *
+ * Not here, and not patchable by any route: `slug`/`started` (identity),
+ * `pinned`/`triggers` (their own endpoints), and `path`/`managed`/`repo` — the
+ * three fields that decide the keeper's cwd (issues #206, #718).
+ *
+ * The `satisfies` clause is the drift guard: a key removed from `ProjectYaml`
+ * fails the build here rather than silently becoming un-patchable.
+ */
+export const PATCHABLE_KEYS = [
+    "name",
+    "status",
+    "domain",
+    "group",
+    "visibility",
+    "summary",
+    "links",
+    "model",
+    "permissionMode",
+    "maxTurns",
+    "docker",
+];

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

@@ -1,7 +1,7 @@
 import { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor } from "./project-mime.js";
 export { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor };
-import { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError } from "./project-paths.js";
-export { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
+import { ROOT_KEY, isRootKey, isPathInside, isSystemPath, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError } from "./project-paths.js";
+export { ROOT_KEY, isRootKey, isPathInside, isSystemPath, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
 import { type Project, type FileKind, type FileEntry, type CreateProjectInput, type UpdateProjectInput } from "./project-types.js";
 export * from "./project-types.js";
 export declare class ProjectStore {
@@ -112,6 +112,9 @@ export declare class ProjectStore {
      *  - a relative path (a cwd must be unambiguous — it is baked into every
      *    transcript path, and resolving it against the server's cwd is a footgun);
      *  - a path that exists but isn't a directory;
+     *  - the filesystem root, or a path inside a system directory (issue #720) —
+     *    see {@link isSystemPath} for the floor and why it is a denylist rather
+     *    than a configurable allowed root;
      *  - a path inside `projectsRoot` or the data dir — that is Paddock's own
      *    state, and pointing at it re-creates the nesting this feature exists to
      *    avoid (plus `remove()` would then really delete it);

package/packages/server/dist/projects.js

@@ -36,10 +36,10 @@ import { PROJECT_SCHEMA_VERSION, SCHEMA_VERSION_KEY, projectSchemaSkip, } from "
 // them at `./projects.js` — the same one-place-to-import discipline as before.
 import { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor, } from "./project-mime.js";
 export { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor };
-import { SLUG_RE, ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, today, claudeTemplate, ProjectError, } from "./project-paths.js";
-export { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
+import { SLUG_RE, ROOT_KEY, isRootKey, isPathInside, isSystemPath, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, today, claudeTemplate, ProjectError, } from "./project-paths.js";
+export { ROOT_KEY, isRootKey, isPathInside, isSystemPath, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
 import { gitRemotes, normalizeRemote } from "./adoptable.js";
-import { normalizeLinks, } from "./project-types.js";
+import { normalizeLinks, PATCHABLE_KEYS, } from "./project-types.js";
 import * as projectFiles from "./project-files.js";
 // Barrel: re-export all type declarations + normalizeLinks + the config-type
 // re-exports (PaddockSchedule/PaddockHook/PaddockTrigger/RecoveryOverride/
@@ -221,7 +221,12 @@ export class ProjectStore {
     async rmInsideRoot(target) {
         const resolved = path.resolve(target);
         const root = path.resolve(this.root);
-        if (resolved === root || !isPathInside(resolved, root)) {
+        // A projects root of `/` would make every path on the box "inside" it and
+        // turn this guard into a no-op. That was accidentally safe before #719 (when
+        // `isPathInside(x, "/")` was false for everything); now that containment
+        // reports the truth, refuse the degenerate root explicitly rather than
+        // relying on a bug to hold the line.
+        if (root === path.parse(root).root || resolved === root || !isPathInside(resolved, root)) {
             throw new ProjectError(`Refusing to delete outside the projects root: ${target}`, "invalid");
         }
         await fs.rm(resolved, { recursive: true, force: true });
@@ -259,6 +264,9 @@ export class ProjectStore {
      *  - a relative path (a cwd must be unambiguous — it is baked into every
      *    transcript path, and resolving it against the server's cwd is a footgun);
      *  - a path that exists but isn't a directory;
+     *  - the filesystem root, or a path inside a system directory (issue #720) —
+     *    see {@link isSystemPath} for the floor and why it is a denylist rather
+     *    than a configurable allowed root;
      *  - a path inside `projectsRoot` or the data dir — that is Paddock's own
      *    state, and pointing at it re-creates the nesting this feature exists to
      *    avoid (plus `remove()` would then really delete it);
@@ -297,6 +305,18 @@ export class ProjectStore {
                 throw new ProjectError(`Project path is not a directory: ${input}`, "not_directory");
             }
         }
+        // The system-path floor (issue #720), applied to BOTH spellings.
+        //
+        // The canonicalised path is the one that matters — a symlink pointing at
+        // `/etc` must be refused for where it really goes. But the path AS WRITTEN
+        // has to be checked too, because `/proc/self/cwd` canonicalises to an
+        // ordinary directory (Paddock's own checkout) and so passes the resolved
+        // check: a `/proc` path is process-relative and non-durable, which a cwd
+        // baked into every transcript path can never be.
+        if (isSystemPath(resolved) || isSystemPath(input)) {
+            throw new ProjectError(`Project path is a system directory and cannot back a project: ${input}` +
+                (resolved === path.resolve(input) ? "" : ` (resolves to ${resolved})`), "invalid");
+        }
         if (isPathInside(resolved, this.root)) {
             throw new ProjectError(`Project path must be outside the projects root (${this.root}): ${input}`, "invalid");
         }
@@ -699,30 +719,64 @@ export class ProjectStore {
         // can't express "delete this field", which is how an override is cleared back
         // to inherit.
         const { driveMode: driveModePatch, maxSpawnDepth: maxSpawnDepthPatch, hooksMcpEnabled: hooksMcpPatch, recovery: recoveryPatch, attachments: attachmentsPatch, curation: curationPatch, models: modelsPatch, ...rest } = patch;
+        // Take ONLY the allowlisted keys off the body (issue #721). `rest` is spread
+        // from an untrusted request body, so the previous `...rest` persisted any key
+        // a caller invented — verbatim, unbounded, into a file re-parsed on every
+        // project listing — and a key seeded with garbage today is a landmine for the
+        // release that starts honouring it.
+        const unknown = [];
+        const patched = {};
+        for (const [key, value] of Object.entries(rest)) {
+            if (value === undefined)
+                continue;
+            if (!PATCHABLE_KEYS.includes(key)) {
+                unknown.push(key);
+                continue;
+            }
+            patched[key] = value;
+        }
+        if (unknown.length > 0) {
+            this.log.warn(`Ignoring unpatchable key(s) in PATCH of project "${slug}": ${unknown.join(", ")}`);
+        }
         const next = {
             ...this.stripDto(current),
-            ...rest,
+            ...patched,
             slug: current.slug, // immutable
             started: current.started, // immutable
             updated: today(),
         };
-        // `path` and `managed` are immutable (issue #206), enforced here rather than
-        // by their absence from UpdateProjectInput — that type is a compile-time shape
-        // while `rest` is spread from a request body.
+        // `path`, `managed` and `repo` are immutable — the THREE fields that feed
+        // `workingDirFor()` and therefore decide the keeper's cwd. The allowlist above
+        // already keeps them out of `patched`; re-asserting them from `current` here
+        // is deliberate belt-and-braces at the point the record is built, so a key
+        // later added to the allowlist cannot silently move a cwd.
         //
-        // For `path` both directions matter: a project must not be RE-POINTED (its cwd
-        // is baked into every transcript path, so moving it strands the history), and
-        // one must not be given a path by a stray key, which would silently hand its
-        // keeper a cwd somewhere else on the box that never went through
-        // `validatePath`. `managed` is re-asserted from `current` for the same reason
-        // — flipping it would move where the curated trio lives and either start the
-        // sweeper writing into a checkout or orphan the existing notes. (Changing it
-        // deliberately is a migration, not a PATCH; see #708 for what a silent
-        // location flip does to history.)
+        // For `path` both directions matter (issue #206): a project must not be
+        // RE-POINTED (its cwd is baked into every transcript path, so moving it
+        // strands the history), and one must not be GIVEN a path by a stray key,
+        // which would hand its keeper a cwd somewhere else on the box that never went
+        // through `validatePath`. `managed` is re-asserted for the same reason —
+        // flipping it moves where the curated trio lives and either starts the sweeper
+        // writing into a checkout or orphans the existing notes.
+        //
+        // `repo` was the one that got missed (issue #718). It is documented immutable
+        // (`ProjectYaml.repo`: "Set at creation; immutable thereafter"), `create()` and
+        // `promote()` both validate it with `isValidRepoUrl()`, and `update()` did
+        // neither: `PATCH {"repo":"not a url at all"}` returned 200 and relocated
+        // `workingDir` AND `contentDir` to `<dir>/not-a-url-at-all`, a directory that
+        // does not exist — every subsequent turn then hung 60s waiting for a session
+        // file and failed, with the existing chats stranded on the old cwd. Acquiring a
+        // repo for an existing project is what `promote()` is for; changing a backing
+        // store is a migration, not a PATCH (see #708 for what a silent location flip
+        // does to history).
         if (current.path)
             next.path = current.path;
         else
             delete next.path;
+        if (current.repo)
+            next.repo = current.repo;
+        else
+            delete next.repo;
         next.managed = current.managed;
         if (driveModePatch === null) {
             // Clear the per-project override -> inherit the global default (issue #122).

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

@@ -12,9 +12,22 @@ export interface QueuedPart {
     id: string;
     text: string;
 }
+/**
+ * A composer attachment staged on the slot (#728) — the same lightweight ref the
+ * `chat:send` path carries. The bytes live in the AttachmentStore; only the id,
+ * filename and kind travel with the queued message.
+ */
+export interface QueuedAttachment {
+    id: string;
+    filename: string;
+    kind?: string;
+}
 /** A queued message awaiting auto-send. */
 export interface QueuedMessage {
-    /** The slot's full text — what gets sent. */
+    /**
+     * The slot's full text — what gets sent. May be `""` when the slot holds only
+     * attachments (#728: an attachment-only message is valid, #328).
+     */
     text: string;
     /** SERVER-stamped enqueue time. Informational — never load-bearing (#736). */
     createdAtMs: number;
@@ -30,7 +43,22 @@ export interface QueuedMessage {
      * entry written by an older server; readers treat that as one legacy identity.
      */
     parts?: QueuedPart[];
+    /**
+     * Files staged in the composer that ride this message when it drains (#728).
+     * Merged as a UNION BY ID so a write can only ever add: a client re-asserting
+     * its queue after a reload has an empty tray by then, and must not be able to
+     * wipe the files off the shared slot.
+     */
+    attachments?: QueuedAttachment[];
 }
+/**
+ * Union two attachment lists by id, preserving order and preferring the entry
+ * already on the slot (its filename/kind is the one every client has been shown).
+ * Bounded by {@link MAX_SLOT_ATTACHMENTS}.
+ */
+export declare function unionAttachments(current: QueuedAttachment[] | undefined, incoming: QueuedAttachment[] | undefined): QueuedAttachment[];
+/** Does this slot hold anything worth sending? Text, attachments, or both. */
+export declare function hasQueuedContent(m: QueuedMessage | null | undefined): boolean;
 /** The identities of an entry, synthesising one for a legacy entry without any. */
 export declare function partsOf(m: QueuedMessage): QueuedPart[];
 export declare class QueuedMessageStore {
@@ -86,7 +114,9 @@ export declare class QueuedMessageStore {
      * `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>;
+    upsert(agent: string, sessionId: string, incoming: QueuedPart & {
+        attachments?: QueuedAttachment[];
+    }, 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

@@ -49,6 +49,58 @@ function keyOf(agent, sessionId) {
 const MERGE_SEP = "\n";
 /** How many (id, text) identities one slot remembers. Bounds the sidecar entry. */
 const MAX_KNOWN = 24;
+/**
+ * How many attachments one slot can hold (#728). The composer caps a single
+ * message at 10 by default, but the slot is shared and merges additively, so two
+ * devices could otherwise stack refs into the sidecar without bound. Well above
+ * any real queued follow-up; the excess is dropped rather than persisted.
+ */
+const MAX_SLOT_ATTACHMENTS = 20;
+/**
+ * Union two attachment lists by id, preserving order and preferring the entry
+ * already on the slot (its filename/kind is the one every client has been shown).
+ * Bounded by {@link MAX_SLOT_ATTACHMENTS}.
+ */
+export function unionAttachments(current, incoming) {
+    const out = [];
+    const seen = new Set();
+    for (const a of [...(current ?? []), ...(incoming ?? [])]) {
+        if (!a || typeof a.id !== "string" || !a.id || seen.has(a.id))
+            continue;
+        seen.add(a.id);
+        out.push(a.kind === undefined ? { id: a.id, filename: a.filename } : { ...a });
+        if (out.length >= MAX_SLOT_ATTACHMENTS)
+            break;
+    }
+    return out;
+}
+/** Narrow a parsed value to a well-formed attachment list (dropping junk). */
+function sanitizeAttachments(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const a of v) {
+        if (!a || typeof a !== "object")
+            continue;
+        const o = a;
+        if (typeof o.id !== "string" || !o.id)
+            continue;
+        if (typeof o.filename !== "string" || !o.filename)
+            continue;
+        out.push({
+            id: o.id,
+            filename: o.filename,
+            ...(typeof o.kind === "string" ? { kind: o.kind } : {}),
+        });
+    }
+    return out;
+}
+/** Does this slot hold anything worth sending? Text, attachments, or both. */
+export function hasQueuedContent(m) {
+    if (!m)
+        return false;
+    return m.text.length > 0 || (m.attachments?.length ?? 0) > 0;
+}
 /**
  * Fold a write from a client that ISN'T on the slot's current version into the
  * slot's text.
@@ -120,11 +172,16 @@ export class QueuedMessageStore {
                                 typeof p.text === "string")
                             : [];
                         const id = typeof v.id === "string" ? entry.id : undefined;
+                        // Same tolerance for the staged attachments (#728): malformed entries
+                        // are dropped, never thrown on — a corrupt sidecar must not be able to
+                        // stop the queue loading.
+                        const attachments = sanitizeAttachments(v.attachments);
                         map.set(k, {
                             text: entry.text,
                             createdAtMs: entry.createdAtMs,
                             ...(id ? { id } : {}),
                             ...(parts.length > 0 ? { parts } : {}),
+                            ...(attachments.length > 0 ? { attachments } : {}),
                         });
                     }
                 }
@@ -208,29 +265,51 @@ export class QueuedMessageStore {
         const map = await this.ensureLoaded();
         const key = keyOf(agent, sessionId);
         const current = map.get(key) ?? null;
-        if (!incoming.text.trim())
+        // Attachments merge additively and independently of the text (#728): a write
+        // can add files, never remove them. Computed first so an attachments-only
+        // write — a valid message with no prose (#328) — has something to write even
+        // though every text rule below leaves the text alone.
+        const attachments = unionAttachments(current?.attachments, incoming.attachments);
+        const gainedAttachments = attachments.length > (current?.attachments?.length ?? 0);
+        const hasText = incoming.text.trim().length > 0;
+        if (!hasText && !gainedAttachments)
             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))
+        // Already folded in under some identity ⇒ a re-assert, not new text. Still
+        // worth writing if it brought new files with it.
+        if (hasText && known.some((p) => p.text === incoming.text) && !gainedAttachments) {
             return current;
+        }
+        const textIsNew = hasText && !known.some((p) => p.text === incoming.text);
         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);
+            : !textIsNew
+                ? // Nothing new to say — an attachments-only write, or a re-assert that
+                    // brought files. The slot's prose is untouched.
+                    current.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);
+        // An attachments-only write contributes no text, so it contributes no identity
+        // to remember either — an empty-text part would match nothing and only crowd
+        // the ledger. The slot version is always recorded.
+        const parts = [
+            ...known,
+            ...(hasText ? [{ id: incoming.id, text: incoming.text }] : []),
+            { id: version, text },
+        ].slice(-MAX_KNOWN);
         const next = {
             text,
             createdAtMs: current?.createdAtMs ?? nowMs,
             id: version,
             parts,
+            ...(attachments.length > 0 ? { attachments } : {}),
         };
         map.set(key, next);
         await this.persist(map);