@edspencer/paddock 0.66.0 → 0.66.2

package/packages/server/dist/instance-config.js

@@ -29,7 +29,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseDocument } from "yaml";
+import { createHash } from "node:crypto";
+import { parse, parseDocument } from "yaml";
 import { DRIVE_MODES, DEFAULT_DRIVE_MODE, MODELS, isKnownModel } from "./models.js";
 import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capability.js";
 import { DEFAULT_RECOVERY } from "./recovery-config.js";
@@ -57,32 +58,82 @@ export const GROUPS = [
 ];
 // --- coercion helpers -------------------------------------------------------
 const asBool = (raw) => typeof raw === "boolean" ? { ok: true, value: raw } : { ok: false, error: "must be a boolean" };
+/**
+ * Parse a JSON patch value that is meant to be a number, WITHOUT `Number()`'s
+ * coercions (issue #723). `Number()` happily turns `null` into `0`, `true` into
+ * `1` and `[7]` into `7` — so `{"recovery.maxRetries": null}`, documented to
+ * CLEAR the override, used to write a very meaningful `0` instead. Only a real
+ * number, or a non-blank numeric string (what an `<input type=number>` sends),
+ * counts; everything else is `NaN` and gets rejected by the callers below.
+ */
+const numeric = (raw) => {
+    if (typeof raw === "number")
+        return raw;
+    if (typeof raw === "string" && raw.trim() !== "")
+        return Number(raw.trim());
+    return NaN;
+};
+/**
+ * Ceiling for the numeric fields. Nothing downstream bounds these — a paste-o of
+ * `20000000` into a millisecond timeout is a 231-day debounce, and a token budget
+ * of 1e15 disables curation silently. A billion is far past any deliberate value
+ * (≈31 years in ms) and keeps every one of them a safe integer.
+ */
+const MAX_NUMBER = 1e9;
+/**
+ * Ceiling for a plain `string` field, in characters. These are names, paths and
+ * URLs; without a bound a 200 KB paste into `brand.name` becomes a 200 KB
+ * `paddock.config.yaml` that every boot must parse. The prompt-shaped `text`
+ * fields have their own, much larger {@link MAX_PROMPT_CHARS}.
+ */
+const MAX_STRING_CHARS = 1024;
 const posInt = (raw) => {
-    const n = Number(raw);
-    return Number.isFinite(n) && Number.isInteger(n) && n > 0
+    const n = numeric(raw);
+    return Number.isInteger(n) && n > 0 && n <= MAX_NUMBER
         ? { ok: true, value: n }
-        : { ok: false, error: "must be a positive integer" };
+        : { ok: false, error: `must be a positive integer (at most ${MAX_NUMBER})` };
 };
+/** A non-negative integer, OR null/empty-string to clear the override (#723). */
 const nonNegInt = (raw) => {
-    const n = Number(raw);
-    return Number.isFinite(n) && Number.isInteger(n) && n >= 0
+    if (raw === null || raw === "" || raw === undefined)
+        return { ok: true, value: null };
+    const n = numeric(raw);
+    return Number.isInteger(n) && n >= 0 && n <= MAX_NUMBER
         ? { ok: true, value: n }
-        : { ok: false, error: "must be a non-negative integer" };
+        : {
+            ok: false,
+            error: `must be a non-negative integer up to ${MAX_NUMBER} (or blank to use the default)`,
+        };
 };
 /** A non-negative number, OR null/empty-string to clear the override. */
 const optNonNegNumber = (raw) => {
     if (raw === null || raw === "" || raw === undefined)
         return { ok: true, value: null };
-    const n = Number(raw);
-    return Number.isFinite(n) && n >= 0
+    const n = numeric(raw);
+    return Number.isFinite(n) && n >= 0 && n <= MAX_NUMBER
         ? { ok: true, value: n }
-        : { ok: false, error: "must be a non-negative number (or blank to use the default)" };
+        : { ok: false, error: `must be a non-negative number up to ${MAX_NUMBER} (or blank to use the default)` };
+};
+const nonEmptyString = (raw) => {
+    if (typeof raw !== "string")
+        return { ok: false, error: "must be a non-empty string" };
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return { ok: false, error: "must be a non-empty string" };
+    if (trimmed.length > MAX_STRING_CHARS) {
+        return { ok: false, error: `must be at most ${MAX_STRING_CHARS} characters (got ${trimmed.length})` };
+    }
+    return { ok: true, value: trimmed };
 };
-const nonEmptyString = (raw) => typeof raw === "string" && raw.trim().length > 0
-    ? { ok: true, value: raw.trim() }
-    : { ok: false, error: "must be a non-empty string" };
 /** A string that may be blank (blank clears the override → falls back to default). */
-const optString = (raw) => typeof raw === "string" ? { ok: true, value: raw.trim() } : { ok: false, error: "must be a string" };
+const optString = (raw) => {
+    if (typeof raw !== "string")
+        return { ok: false, error: "must be a string" };
+    const trimmed = raw.trim();
+    return trimmed.length <= MAX_STRING_CHARS
+        ? { ok: true, value: trimmed }
+        : { ok: false, error: `must be at most ${MAX_STRING_CHARS} characters (got ${trimmed.length})` };
+};
 /**
  * Upper bound on a prompt-shaped field, in characters. Nothing enforces a limit
  * downstream — the text is concatenated into the system prompt of every single
@@ -120,17 +171,33 @@ const oneOf = (values) => (raw) => typeof raw === "string" && values.includes(ra
     ? { ok: true, value: raw }
     : { ok: false, error: `must be one of: ${values.join(", ")}` };
 const spawnDepth = (raw) => {
-    const n = Number(raw);
+    // Same shape as `nonNegInt`, for the same #723 reason: `Number(null)` is 0,
+    // which IS a valid depth — so "clear this override" wrote the one depth that
+    // switches every child's self-MCP off. Depth 0 stays settable; it just has to
+    // be asked for.
+    if (raw === null || raw === "" || raw === undefined)
+        return { ok: true, value: null };
+    const n = numeric(raw);
     return isValidMaxSpawnDepth(n)
         ? { ok: true, value: n }
-        : { ok: false, error: "must be a small non-negative integer" };
+        : { ok: false, error: "must be a small non-negative integer (or blank to use the default)" };
 };
 const hexColor = (raw) => typeof raw === "string" && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(raw.trim())
     ? { ok: true, value: raw.trim() }
     : { ok: false, error: "must be a hex color like #c2603c" };
+/** Bounds on a free-form list field, for the same reason as {@link MAX_STRING_CHARS}. */
+const MAX_LIST_ITEMS = 64;
+const MAX_LIST_ITEM_CHARS = 256;
 const stringList = (raw) => {
     const list = sanitizeAllowedTypes(raw);
-    return list ? { ok: true, value: list } : { ok: false, error: "must be a non-empty list of type/extension strings" };
+    if (!list)
+        return { ok: false, error: "must be a non-empty list of type/extension strings" };
+    if (list.length > MAX_LIST_ITEMS)
+        return { ok: false, error: `must have at most ${MAX_LIST_ITEMS} entries` };
+    if (list.some((s) => s.length > MAX_LIST_ITEM_CHARS)) {
+        return { ok: false, error: `each entry must be at most ${MAX_LIST_ITEM_CHARS} characters` };
+    }
+    return { ok: true, value: list };
 };
 /**
  * Coerce a raw model allow-list (issue #457 Step 2) into a de-duped list of
@@ -290,6 +357,55 @@ function envOverride(envVars, whenDefined = false) {
     }
     return undefined;
 }
+/**
+ * Read + parse `paddock.config.yaml` for the GET path. Never throws: a missing
+ * file is the normal case, and a malformed one must not take down the screen
+ * that exists to fix it (the boot loader is the strict reader — see
+ * `loadConfigFile`).
+ */
+function readConfigFileSnapshot(configPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { data: null, version: null };
+        return { data: null, version: null, error: `failed to read ${configPath}: ${err.message}` };
+    }
+    const version = createHash("sha256").update(raw).digest("hex").slice(0, 16);
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (err) {
+        return { data: null, version, error: `failed to parse ${configPath}: ${err.message}` };
+    }
+    // Empty / comments-only file → no overrides, same reading as loadConfigFile.
+    if (parsed === null || parsed === undefined)
+        return { data: {}, version };
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { data: null, version, error: `${configPath} is not a YAML mapping` };
+    }
+    return { data: parsed, version };
+}
+/**
+ * The current fingerprint of the config file (`null` when absent) — the PUT
+ * path's half of the optimistic-concurrency check. Deliberately re-reads rather
+ * than trusting a cached value: the point is to notice a write we did not make.
+ */
+export function instanceConfigVersion(configPath) {
+    return readConfigFileSnapshot(configPath).version;
+}
+/** Structural equality for the value shapes a field can hold (scalars + string lists). */
+function valuesEqual(a, b) {
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => v === b[i]);
+    }
+    return a === b;
+}
 /**
  * Default filename for the instance-config file, resolved under the data dir.
  * Kept in sync with config.ts's private constant (both point at the same file);
@@ -310,9 +426,25 @@ export function instanceConfigPath(cfg) {
     return path.join(cfg.dataDir, DEFAULT_CONFIG_FILENAME);
 }
 /**
- * Build the grouped GET DTO from the resolved (frozen) config + live env. Each
- * field reports its current `value`, built-in `default`, and whether an env var
- * currently shadows it (so the UI renders env-shadowed fields read-only).
+ * Build the grouped GET DTO from the resolved (frozen) config, the live env AND
+ * the config file on disk. Each field reports:
+ *
+ *  - `value` — EFFECTIVE now, out of the frozen boot config;
+ *  - `pendingValue` — what a restart would resolve, out of the file this instant;
+ *  - `pendingRestart` — those two differ.
+ *
+ * Reading the file is the load-bearing part (#722). While this built the DTO
+ * from the frozen config alone, `GET` could not observe ANY write — including
+ * the one the caller had just made — so a successful save appeared to revert,
+ * two tabs clobbered each other with nothing able to notice, and
+ * `restartRequired` had no choice but to be a hardcoded `false`.
+ *
+ * Pending values are computed for EDITABLE, non-env-shadowed fields only:
+ *  - an env-shadowed field resolves to the same env value after a restart, so
+ *    the file cannot make it diverge;
+ *  - the read-only `advanced` bindings are normalised at boot (`dataDir` and
+ *    friends are canonicalised, `port` is `Number()`-ed), so comparing them
+ *    against raw file text would manufacture divergence that isn't there.
  */
 export function buildInstanceConfig(cfg) {
     const groups = GROUPS.map((g) => ({
@@ -322,9 +454,31 @@ export function buildInstanceConfig(cfg) {
         fields: [],
     }));
     const groupById = new Map(groups.map((g) => [g.id, g]));
+    const configPath = instanceConfigPath(cfg);
+    const file = readConfigFileSnapshot(configPath);
+    let restartRequired = false;
     for (const f of FIELDS) {
         const shadow = envOverride(f.envVars, f.envShadowWhenDefined);
         const raw = readPath(cfg, f.key);
+        // `undefined` (e.g. sweepMinIntervalMs unset, optional endpoint) → null so
+        // it JSON-serializes as an explicit absence rather than dropping the key.
+        const value = raw === undefined ? null : raw;
+        let pendingValue = value;
+        let pendingRestart = false;
+        if (f.editable && shadow === undefined && file.data) {
+            // Absent, or present-but-null (`debounceMs:` with nothing after it), both
+            // mean "no override" — `fileOr`/`fileOpt` degrade a null to the default.
+            const fileRaw = readPath(file.data, f.key);
+            pendingValue = fileRaw == null ? (f.default ?? null) : coerceForDisplay(f, fileRaw);
+            // A field the frozen config leaves unset IS its built-in default (that is
+            // what `default` documents), so normalise before comparing — otherwise
+            // e.g. `models`, unset and therefore null, would read as forever diverging
+            // from the catalog list the file's absence implies.
+            const effective = value === null ? (f.default ?? null) : value;
+            pendingRestart = !valuesEqual(pendingValue, effective);
+            if (pendingRestart)
+                restartRequired = true;
+        }
         const dto = {
             key: f.key,
             group: f.group,
@@ -332,9 +486,9 @@ export function buildInstanceConfig(cfg) {
             help: f.help,
             type: f.type,
             enumValues: f.enumValues,
-            // `undefined` (e.g. sweepMinIntervalMs unset, optional endpoint) → null so
-            // it JSON-serializes as an explicit absence rather than dropping the key.
-            value: raw === undefined ? null : raw,
+            value,
+            pendingValue,
+            pendingRestart,
             default: f.default,
             editable: f.editable,
             sensitive: f.sensitive ?? false,
@@ -343,7 +497,26 @@ export function buildInstanceConfig(cfg) {
         };
         groupById.get(f.group)?.fields.push(dto);
     }
-    return { groups, configPath: instanceConfigPath(cfg), restartRequired: false };
+    return {
+        groups,
+        configPath,
+        restartRequired,
+        configVersion: file.version,
+        ...(file.error ? { configFileError: file.error } : {}),
+    };
+}
+/**
+ * Normalise a value read back out of the file into the shape the writer would
+ * have produced, so a hand-typed `"1234"` doesn't read as diverging from a
+ * written `1234`. A value the field's own validator rejects is reported
+ * verbatim: the file really does say that, and the screen showing it is how an
+ * operator finds out (the boot loader would degrade it to the default).
+ */
+function coerceForDisplay(f, raw) {
+    if (!f.coerce)
+        return raw;
+    const res = f.coerce(raw);
+    return res.ok ? res.value : raw;
 }
 /** A rejected PUT: which field failed and why (surfaced as a 400). */
 export class InstanceConfigError extends Error {
@@ -359,6 +532,7 @@ export class InstanceConfigError extends Error {
  * {@link InstanceConfigError} on the first offending field:
  *  - an unknown key,
  *  - a read-only / non-editable key,
+ *  - a key an env var currently shadows,
  *  - a value the field's `coerce` rejects.
  * Returns the coerced `{ key, value }` pairs ready to write. A field whose value
  * is `null` (an editable optional being cleared) is returned with `value: null`
@@ -373,6 +547,14 @@ export function validatePatch(patch) {
         if (!spec.editable || !spec.coerce) {
             throw new InstanceConfigError(`Setting is read-only: ${key}`, key);
         }
+        // `env > file > default`: writing a shadowed field to the file changes
+        // nothing an operator can observe, now or after a restart. The UI already
+        // renders these read-only; without this check the API happily returned 200 +
+        // `restartRequired: true` for a write that could never take effect.
+        const shadow = envOverride(spec.envVars, spec.envShadowWhenDefined);
+        if (shadow !== undefined) {
+            throw new InstanceConfigError(`${spec.label} (${key}) is set by the environment variable ${shadow}, which wins over the config file — change it there instead`, key);
+        }
         const res = spec.coerce(raw);
         if (!res.ok)
             throw new InstanceConfigError(`${spec.label} (${key}) ${res.error}`, key);

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

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

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

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

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

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

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

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

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

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