@edspencer/paddock 0.65.0 → 0.66.1

package/packages/server/dist/projects.js

@@ -30,6 +30,7 @@ import { sanitizeTrigger, sanitizeTriggers, isValidTriggerName, } from "./trigge
 import { sanitizeRecoveryOverride } from "./recovery-config.js";
 import { sanitizeCurationOverride } from "./curation-config.js";
 import { sanitizeAttachmentsOverride } from "./attachments-config.js";
+import { PROJECT_SCHEMA_VERSION, SCHEMA_VERSION_KEY, projectSchemaSkip, } from "./schema-version.js";
 // --- re-export barrels (issue #403) ------------------------------------------
 // The moved symbols are re-exported from here so external importers keep finding
 // them at `./projects.js` — the same one-place-to-import discipline as before.
@@ -98,6 +99,8 @@ export class ProjectStore {
         this.dataDir = dataDir;
         this.log = log;
     }
+    /** `${file} ${declaredVersion}` pairs already warned about — see {@link warnOnceAboutSchema}. */
+    schemaWarned = new Set();
     /** Ensure the projects root exists. Call once at startup. */
     async init() {
         await fs.mkdir(this.root, { recursive: true });
@@ -1052,9 +1055,10 @@ export class ProjectStore {
      */
     async readSafe(key) {
         const dir = this.dirFor(key);
+        const file = path.join(dir, PROJECT_FILE);
         let yaml;
         try {
-            const raw = await fs.readFile(path.join(dir, PROJECT_FILE), "utf8");
+            const raw = await fs.readFile(file, "utf8");
             const parsed = YAML.parse(raw);
             if (!parsed || typeof parsed !== "object") {
                 if (!isRootKey(key))
@@ -1062,6 +1066,18 @@ export class ProjectStore {
                 yaml = this.normalize({}, key);
             }
             else {
+                // The downgrade guard (#724), BEFORE `normalize` gets to be lenient with
+                // it. A file from the future is skipped whole — including the root's,
+                // which falls through to a `not_found` rather than to the empty-record
+                // defaults, because those defaults are precisely what a subsequent write
+                // would flatten it to. Nothing is written here, and every mutator reaches
+                // the file through `get()`, so a skipped record cannot be rewritten.
+                const declared = parsed[SCHEMA_VERSION_KEY];
+                const skip = projectSchemaSkip(declared, file);
+                if (skip !== undefined) {
+                    this.warnOnceAboutSchema(file, declared, skip);
+                    return null;
+                }
                 yaml = this.normalize(parsed, key);
             }
         }
@@ -1236,9 +1252,31 @@ export class ProjectStore {
     async writeYaml(slug, yaml) {
         const header = "# Paddock project metadata. Directory name MUST equal `slug`.\n" +
             "# status: idea | active | paused | blocked | done | abandoned\n";
-        const body = YAML.stringify(yaml);
+        // Stamped here rather than threaded through ProjectYaml/the DTO, because
+        // this is the one write choke point and because what it describes is the
+        // FILE, not the project (#724). Unconditional and first: every write is a
+        // full rewrite from the normalized record, so what lands on disk is by
+        // construction this build's shape whatever the file said before. A legacy
+        // file therefore gains the key the next time it is saved for some other
+        // reason — there is no backfill pass, and merely reading one writes nothing.
+        const body = YAML.stringify({ [SCHEMA_VERSION_KEY]: PROJECT_SCHEMA_VERSION, ...yaml });
         await fs.writeFile(path.join(this.dirFor(slug), PROJECT_FILE), header + body, "utf8");
     }
+    /**
+     * Say out loud that a project was skipped for being from the future (#724),
+     * once per (file, declared version).
+     *
+     * `list()` runs on every `GET /api/projects`, so an unconditional warn would
+     * bury the log. Keyed on the declared version as well as the path so a
+     * hand-edit — or the same instance being downgraded further — speaks up again.
+     */
+    warnOnceAboutSchema(file, declared, message) {
+        const seen = `${file} @ ${JSON.stringify(declared) ?? "?"}`;
+        if (this.schemaWarned.has(seen))
+            return;
+        this.schemaWarned.add(seen);
+        this.log.warn(message);
+    }
     toDto(dir, yaml, hasOverview) {
         return {
             ...yaml,

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

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

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

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

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

@@ -24,6 +24,7 @@ import { childOf, HUMAN_ROOT, ADOPTED_ROOT } from "../run-provenance.js";
 import { sendProjectError } from "../route-errors.js";
 import { mapWithConcurrency, FILE_FANOUT_CONCURRENCY } from "../concurrency.js";
 import { CHAT_USAGE_SCOPES, SAFE_SESSION_ID, RUNS_SEEN_SESSION, clampRunsLimit, toChatUsage, buildProjectChats, makeTriggerResolver, makeParentResolver, normalizeBatchSessionIds, BATCH_SESSIONS_MAX, } from "../chat-dto.js";
+import { quiesceSession, turnRunningError } from "../turn-interlock.js";
 /**
  * Workspace-scoped chat routes: paths are declared RELATIVE to the workspace
  * (e.g. `/chats/:sessionId`), and this plugin is mounted TWICE — once at
@@ -56,6 +57,17 @@ export function registerChatWorkspaceRoutes(app, ctx) {
      * feed then degrades to its unread half instead of 500ing.
      */
     const isRunning = (sessionId) => ctx.managementOpsContext?.hub.isRunning(sessionId) ?? false;
+    /**
+     * The interlock every DESTRUCTIVE chat route runs first (issue #731).
+     *
+     * `claude` writes the transcript itself, so unlinking or rewriting it while a
+     * turn is live does not remove the chat — the surviving process re-creates the
+     * file from its own tail and the chat comes back with its history gone. These
+     * routes therefore stop the turn and WAIT for it to be dead before touching a
+     * byte; `stuck` means we could not confirm that, and the only safe answer then
+     * is to refuse.
+     */
+    const interlock = { hub: ctx.managementOpsContext?.hub, herdctl };
     // --- chats (sessions) --------------------------------------------------
     app.get("/chats", {
         schema: {
@@ -595,7 +607,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object `{ ok, removed }` indicating whether the transcript was removed.",
+                    description: "Object `{ ok, removed, retained, cancelledTurn }` — whether the transcript was removed, and whether a live turn had to be stopped first (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped, so nothing was deleted (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -604,6 +621,15 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     }, async (req, reply) => {
         try {
             const agent = await agentForSlug(req.params.slug);
+            // #731: stop any in-flight turn FIRST. A delete is an unambiguous "this
+            // chat is going away", so we cancel rather than refuse — refusing would
+            // strand the user behind a turn that may never end (a hung turn was
+            // exactly how this was found). If the turn will not die we refuse, since
+            // deleting under a live writer is what resurrected the chat.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             await cleanupAttachments(agent, req.params.sessionId);
             const { removed, retained } = await herdctl.deleteSession(agent, req.params.sessionId);
             // Drop any archived/starred/unread/detached flag so a future session id
@@ -619,7 +645,9 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             // has to be cleared on the same path — otherwise a recycled session id
             // silently starts life detached from a parent it never had.
             await parentDetach.setDetached(agent, req.params.sessionId, false).catch(() => undefined);
-            return reply.code(200).send({ ok: true, removed, retained });
+            return reply
+                .code(200)
+                .send({ ok: true, removed, retained, cancelledTurn: quiesced === "stopped" });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -751,7 +779,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object reporting how many messages were removed.",
+                    description: "Object reporting how many messages were removed, and whether a live turn had to be stopped first (`cancelledTurn`, #731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped, so nothing was truncated (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -763,8 +796,19 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             if (!uuid)
                 return reply.code(400).send({ error: "uuid is required" });
             const project = await projects.get(req.params.slug);
+            // #731: revert truncates the LIVE transcript in place — the same file a
+            // running turn is appending to — so mid-turn it left an orphan
+            // `tool_result` whose `tool_use` had just been truncated away. Cancel
+            // rather than refuse: an in-flight turn is by definition part of the tail
+            // the user just asked to throw away.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             const { removed } = await herdctl.revertSession(project, req.params.sessionId, uuid);
-            return reply.code(200).send({ ok: true, removed });
+            return reply
+                .code(200)
+                .send({ ok: true, removed, cancelledTurn: quiesced === "stopped" });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -1206,6 +1250,14 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             const failed = [];
             for (const sessionId of sessionIds) {
                 try {
+                    // #731: same interlock as the single delete, per id. A chat whose
+                    // turn refuses to die lands in `failed` rather than aborting the
+                    // batch — the route is already best-effort-and-honest per chat, and
+                    // "still running" is exactly the kind of partial failure it reports.
+                    if ((await quiesceSession(interlock, sessionId)) === "stuck") {
+                        failed.push(sessionId);
+                        continue;
+                    }
                     await cleanupAttachments(agent, sessionId);
                     const gone = await herdctl.deleteSession(agent, sessionId);
                     // `retained` counts as success here, and the distinction matters for
@@ -1279,7 +1331,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 201: {
-                    description: "Object `{ project, promoted, sessionId }` describing the created project and whether the transcript was re-homed.",
+                    description: "Object `{ project, promoted, sessionId, cancelledTurn }` describing the created project, whether the transcript was re-homed, and whether a live turn had to be stopped first (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped. Nothing was moved and NO project was created (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -1292,6 +1349,15 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         }
         try {
             const from = await projects.get(req.params.slug);
+            // #731: promote MOVES the transcript, so mid-turn it lost the chat from
+            // BOTH projects — the surviving process rewrote the source path it still
+            // held, while the moved copy went unlisted in the target with no recovery
+            // path in the UI. Quiesce BEFORE `projects.create` so a refusal doesn't
+            // leave an empty project behind as a side-effect of a failed promote.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             const project = await projects.create({
                 name: body.name,
                 slug: body.slug,
@@ -1315,7 +1381,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             catch (err) {
                 req.log.warn({ err }, "promote: could not re-home the transcript");
             }
-            return reply.code(201).send({ project, promoted, sessionId: req.params.sessionId });
+            return reply.code(201).send({
+                project,
+                promoted,
+                sessionId: req.params.sessionId,
+                cancelledTurn: quiesced === "stopped",
+            });
         }
         catch (err) {
             return sendProjectError(reply, err);

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

@@ -1,9 +1,10 @@
-import { ProjectError, ROOT_KEY, } from "../projects.js";
+import { ProjectError, ROOT_KEY, isRootKey, } from "../projects.js";
 import { keeperAgentName } from "../herdctl.js";
 import { isKnownModel, isKnownPermissionMode, isValidMaxTurns, isKnownDriveMode, resolveModels, MAX_TURNS_LIMIT, } from "../models.js";
 import { isValidMaxSpawnDepth, MAX_SPAWN_DEPTH_LIMIT } from "../spawn-capability.js";
 import { sendProjectError } from "../route-errors.js";
 import { buildProjectChats, makeTriggerResolver, makeParentResolver } from "../chat-dto.js";
+import { quiesceProject, turnRunningError } from "../turn-interlock.js";
 /**
  * Build ONE workspace's compact `{ sessionId, lastTurnCompletedAt, lastSeen?,
  * unread? }` list — the sidebar's UNREAD-badge feed (#161), server-backed (#189).
@@ -406,11 +407,30 @@ export function registerProjectWorkspaceRoutes(app, ctx) {
                     type: "object",
                     additionalProperties: true,
                 },
+                409: {
+                    description: "`{ code: 'turn_running', sessionIds }` — one or more of the project's chats has a turn that could not be stopped, so nothing was deleted (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
             },
         },
     }, async (req, reply) => {
         try {
-            const project = await projects.remove(req.params.slug); // throws not_found
+            // #731: a project delete takes every chat in it, so it races the same live
+            // writers a chat delete does — and the orphaned `claude` was observed
+            // running on with a cwd of `…/<slug> (deleted)`. Stop them all first, and
+            // refuse rather than remove the directory out from under one.
+            //
+            // `remove()` refuses the ROOT workspace, and a refusal must not have killed
+            // the root's live turns on the way to saying no — so that one check comes
+            // first, mirroring the guard in `remove()` rather than duplicating its
+            // error.
+            if (!isRootKey(req.params.slug)) {
+                const stuck = await quiesceProject({ hub: ctx.managementOpsContext?.hub, herdctl }, req.params.slug);
+                if (stuck.length > 0)
+                    return reply.code(409).send(turnRunningError(stuck));
+            }
+            const project = await projects.remove(req.params.slug); // throws not_found / refuses root
             try {
                 await herdctl.removeProjectAgent(project.slug, Object.keys(project.hooks ?? {}), Object.keys(project.triggers ?? {}));
             }

package/packages/server/dist/schema-version.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Schema versioning for the two on-disk formats paddock OWNS (issue #724).
+ *
+ * Those two are `project.yaml` and `paddock.config.yaml`, and only those two.
+ * The `version: 1` fields elsewhere in the tree belong to herdctl — its fleet
+ * config (`herdctl-agent-config.ts`) and `@herdctl/core`'s session metadata —
+ * and transcripts are Claude Code's format. Paddock reads neither back.
+ *
+ * ## What this is for: the DOWNGRADE guard, not migrations
+ *
+ * There is no migration runner here, deliberately (#724, and #717 for the
+ * sequencing). With `1` as the only version there is nothing to migrate, and a
+ * runner with zero migrations cannot be meaningfully tested.
+ *
+ * The value delivered on its own is the guard. Running an OLDER paddock against
+ * a data dir a newer one wrote — `npx @edspencer/paddock@0.62.0` is one command
+ * away — lenient-parses it: `ProjectStore.normalize` drops every key it does not
+ * recognise, and the next `update()` writes the file back without them. A
+ * `path:` or a `managed:` disappears with no error. A declared version turns
+ * that into "this file is version 4, I understand 1, I am not touching it".
+ *
+ * **Never lenient-parse a file from the future.** That is the whole point.
+ *
+ * ## Adoption cost: nothing
+ *
+ * The CURRENT on-disk shape *is* version 1, and an ABSENT `schemaVersion` reads
+ * as 1 — so no live instance needs rewriting and nothing pre-adoption can break,
+ * because those files genuinely are v1. Files we write carry the field
+ * explicitly; existing files gain it whenever they are next written for some
+ * other reason. There is no backfill.
+ *
+ * ## When to bump — read this before changing either format
+ *
+ * Bump ONLY when an old reader would get the wrong answer, or a new reader
+ * cannot recover the truth from an old file:
+ *
+ * | Change                                              | Bump? |
+ * | --------------------------------------------------- | ----- |
+ * | Add an optional key with a safe default             | **No** — lenient parsing already handles it |
+ * | Rename a key                                        | Yes   |
+ * | Change what an existing key *means*                 | Yes — silent misinterpretation, the dangerous one |
+ * | Change a default so *absence* now means something new | Yes |
+ * | Remove a load-bearing key                           | Yes   |
+ *
+ * Adding a key does not bump, which covers most changes. The additive-vs-
+ * breaking distinction is expressed by NOT bumping, rather than by a second
+ * version component — hence a monotonic integer and never semver. A data file
+ * has one consumer, the app, and it always wants latest: there is no version
+ * negotiation for a minor/patch to describe, and migrations chain (1→2→3), which
+ * "does 1.2→2.0 include 1.3?" cannot express. Rails, Django, SQLite's
+ * `user_version` and IndexedDB all land in the same place.
+ *
+ * Worked example, so the table is not abstract. v0.64.0's `managed` default is
+ * `managed ?? !(repo || path)` (`project-paths.ts`) — row four, the absence of a
+ * key acquiring a derived meaning. Under this scheme that was a 1→2 migration:
+ * read v1, compute `managed`, write it explicitly, stamp 2. Instead it is a
+ * derivation re-evaluated on every read, forever, with `stripDto` deliberately
+ * letting `managed` survive so the first PATCH pins it. It works, but it is a
+ * migration in disguise, and that pattern accretes.
+ *
+ * The two constants are independent on purpose: a breaking change to
+ * `project.yaml` should not force every `paddock.config.yaml` to claim a version
+ * whose shape it never had. They happen to both be 1 today.
+ */
+/** Schema version of the `project.yaml` format this build writes and understands. */
+export declare const PROJECT_SCHEMA_VERSION = 1;
+/** Schema version of the `paddock.config.yaml` format this build writes and understands. */
+export declare const CONFIG_SCHEMA_VERSION = 1;
+/** The key both formats carry it under. */
+export declare const SCHEMA_VERSION_KEY = "schemaVersion";
+/**
+ * The version a parsed file declares, or `null` if it declares something we
+ * cannot make sense of.
+ *
+ * - **Absent / null** → {@link PROJECT_SCHEMA_VERSION}-era, i.e. `1`. Every file
+ *   written before adoption is genuinely a v1 file.
+ * - A positive integer (or a string spelling one, since YAML quoting is easy to
+ *   get wrong by hand) → that integer.
+ * - Anything else — `0`, `-1`, `1.5`, `"banana"`, a list — → `null`.
+ *
+ * `null` is deliberately treated by callers the same way a from-the-future
+ * version is, not the same way an absent one is. A file whose own claim about
+ * its shape is unreadable is a file we cannot establish is safe to rewrite, and
+ * the failure mode this whole mechanism exists to prevent is rewriting one we
+ * did not understand.
+ */
+export declare function readSchemaVersion(raw: unknown): number | null;
+/** Whether `raw` declares a version this build cannot safely read. */
+export declare function isFromTheFuture(raw: unknown, supported: number): boolean;
+/**
+ * Why `paddock.config.yaml` is unreadable by this build, or `undefined` if it is
+ * fine. Pure, so the decision is testable without a filesystem.
+ *
+ * Fail-closed, in the same shape as the `claudeHome`-points-at-your-own-`~/.claude`
+ * refusal in `config.ts`: an instance config from the future governs auth mode,
+ * bind host and data paths, and half-understanding those is worse than not
+ * starting.
+ */
+export declare function configSchemaRefusal(raw: unknown, configPath: string): string | undefined;
+/**
+ * Why a `project.yaml` cannot be read by this build, or `undefined` if it is fine.
+ *
+ * Asymmetric with {@link configSchemaRefusal} on purpose, and this is the
+ * judgement call worth knowing about: a project from the future is SKIPPED,
+ * loudly, rather than refusing the boot. `readSafe` already returns `null` for
+ * an unreadable `project.yaml` and the project simply vanishes from `list()`, so
+ * saying it out loud is a strict improvement on today. Bricking a whole instance
+ * because one project directory was copied in from a newer box would be a worse
+ * failure than the data loss being prevented.
+ */
+export declare function projectSchemaSkip(raw: unknown, file: string): string | undefined;