@edspencer/paddock 0.64.0 → 0.66.0

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

@@ -23,6 +23,8 @@ export declare class ProjectStore {
     constructor(root: string, dataDir?: string | undefined, log?: {
         warn: (message: string) => void;
     });
+    /** `${file} ${declaredVersion}` pairs already warned about — see {@link warnOnceAboutSchema}. */
+    private readonly schemaWarned;
     /** Ensure the projects root exists. Call once at startup. */
     init(): Promise<void>;
     /**
@@ -67,9 +69,18 @@ export declare class ProjectStore {
      * root, and that implicit safety is gone.
      *
      * So the check is made explicit and centralised here rather than re-derived at
-     * each call site: an `fs.rm` that escapes throws instead of deleting. Both
-     * current callers already only pass in-root paths — this exists so that stays
-     * true when someone later adds a third one.
+     * each call site: an `fs.rm` that escapes throws instead of deleting. Every
+     * caller already only passes in-root paths — this exists so that stays true
+     * when someone later adds another one.
+     *
+     * `promote()`'s two rollbacks route through here as well. Their target is
+     * `<projectsRoot>/<slug>/<checkoutName>`, which is in-root by construction, so
+     * the guard is inert there today — that is the point. This is the choke point
+     * the comment above promised, and a recursive delete that skips it is exactly
+     * the drift it exists to prevent. {@link rollback} is the deliberate exception:
+     * it deletes paths that may legitimately sit OUTSIDE the root (a user-nominated
+     * clone target), and is safe by a different mechanism — it only ever removes
+     * directories this operation created.
      */
     private rmInsideRoot;
     /**
@@ -346,6 +357,15 @@ export declare class ProjectStore {
      */
     private ensureSidecarGitignore;
     private writeYaml;
+    /**
+     * 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.
+     */
+    private warnOnceAboutSchema;
     private toDto;
     /**
      * Drop the derived DTO-only fields, leaving the on-disk shape.

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 });
@@ -202,9 +205,18 @@ export class ProjectStore {
      * root, and that implicit safety is gone.
      *
      * So the check is made explicit and centralised here rather than re-derived at
-     * each call site: an `fs.rm` that escapes throws instead of deleting. Both
-     * current callers already only pass in-root paths — this exists so that stays
-     * true when someone later adds a third one.
+     * each call site: an `fs.rm` that escapes throws instead of deleting. Every
+     * caller already only passes in-root paths — this exists so that stays true
+     * when someone later adds another one.
+     *
+     * `promote()`'s two rollbacks route through here as well. Their target is
+     * `<projectsRoot>/<slug>/<checkoutName>`, which is in-root by construction, so
+     * the guard is inert there today — that is the point. This is the choke point
+     * the comment above promised, and a recursive delete that skips it is exactly
+     * the drift it exists to prevent. {@link rollback} is the deliberate exception:
+     * it deletes paths that may legitimately sit OUTSIDE the root (a user-nominated
+     * clone target), and is safe by a different mechanism — it only ever removes
+     * directories this operation created.
      */
     async rmInsideRoot(target) {
         const resolved = path.resolve(target);
@@ -641,7 +653,7 @@ export class ProjectStore {
             await cloneRepo(repo, checkoutDir);
         }
         catch (err) {
-            await fs.rm(checkoutDir, { recursive: true, force: true }).catch(() => undefined);
+            await this.rmInsideRoot(checkoutDir).catch(() => undefined);
             throw new ProjectError(err instanceof Error ? err.message : `Failed to clone ${repo}`, "invalid");
         }
         // `writeYaml` is the atomic COMMIT point: until it succeeds the notebook is
@@ -666,7 +678,7 @@ export class ProjectStore {
             await this.writeYaml(slug, next);
         }
         catch (err) {
-            await fs.rm(checkoutDir, { recursive: true, force: true }).catch(() => undefined);
+            await this.rmInsideRoot(checkoutDir).catch(() => undefined);
             throw err;
         }
         // Post-commit finalization — the project is now validly repo-backed; these
@@ -1043,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))
@@ -1053,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);
             }
         }
@@ -1227,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/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;

package/packages/server/dist/schema-version.js

@@ -0,0 +1,142 @@
+/**
+ * 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 const PROJECT_SCHEMA_VERSION = 1;
+/** Schema version of the `paddock.config.yaml` format this build writes and understands. */
+export const CONFIG_SCHEMA_VERSION = 1;
+/** The key both formats carry it under. */
+export 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 function readSchemaVersion(raw) {
+    if (raw === undefined || raw === null)
+        return 1;
+    const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw.trim()) : NaN;
+    if (!Number.isInteger(n) || n < 1)
+        return null;
+    return n;
+}
+/** How a declared version reads in a message, including the unreadable case. */
+function describeDeclared(raw) {
+    const found = readSchemaVersion(raw);
+    return found === null ? `an unreadable \`schemaVersion\` (${JSON.stringify(raw)})` : `version ${found}`;
+}
+/** Whether `raw` declares a version this build cannot safely read. */
+export function isFromTheFuture(raw, supported) {
+    const found = readSchemaVersion(raw);
+    return found === null || found > supported;
+}
+/**
+ * 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 function configSchemaRefusal(raw, configPath) {
+    if (!isFromTheFuture(raw, CONFIG_SCHEMA_VERSION))
+        return undefined;
+    return (`refusing to start: ${configPath} declares ${describeDeclared(raw)} of the paddock config ` +
+        `format, but this build understands up to version ${CONFIG_SCHEMA_VERSION}. It was written ` +
+        `by a NEWER paddock. Reading it with this build would silently drop every key this version ` +
+        `does not know, and the next write would persist the loss. Upgrade paddock to a version that ` +
+        `understands it, or point PADDOCK_CONFIG at a config file this build wrote.`);
+}
+/**
+ * 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 function projectSchemaSkip(raw, file) {
+    if (!isFromTheFuture(raw, PROJECT_SCHEMA_VERSION))
+        return undefined;
+    return (`skipping a project: ${file} declares ${describeDeclared(raw)} of the paddock project ` +
+        `format, but this build understands up to version ${PROJECT_SCHEMA_VERSION}. It was written ` +
+        `by a NEWER paddock. The project is hidden — NOT deleted, and the file is left exactly as it ` +
+        `is — because reading it here would drop the keys this version does not know and the next ` +
+        `save would persist that loss. Upgrade paddock to see it again.`);
+}

package/packages/server/dist/self-mcp-descriptions.d.ts

@@ -14,6 +14,7 @@ export declare const ARCHIVE_CHAT_DESC: string;
 export declare const UNARCHIVE_CHAT_DESC: string;
 export declare const FORK_CHAT_BATCH_DESC: string;
 export declare const CREATE_PROJECT_DESC: string;
+export declare const PROMOTE_PROJECT_DESC: string;
 export declare const SET_TRIGGER_DESC: string;
 export declare const REMOVE_TRIGGER_DESC: string;
 export declare const RUN_TRIGGER_DESC: string;