@edspencer/paddock 0.66.0 → 0.66.2

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

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

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

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

@@ -134,14 +134,17 @@ 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: {
@@ -632,6 +635,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 +1258,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 +1284,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