@edspencer/paddock 0.66.1 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.66.1",
+  "version": "0.67.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/herdctl-jobs.d.ts

@@ -72,6 +72,26 @@ export declare function listProjectRuns(stateDir: string, project: Project, limi
  * view degrades to config-only rather than failing to render.
  */
 export declare function listRunsForAgents(stateDir: string, agents: string[], limit?: number): Promise<JobMetadata[]>;
+/**
+ * Drop the job records of one or more CHATS (#732) — called when Paddock removes
+ * a chat from a project, so the record cannot outlive the transcript and keep
+ * the sidebar badge counting a chat that is no longer there to open.
+ */
+export declare function purgeSessionJobs(stateDir: string, sessionIds: string[]): Promise<number>;
+/**
+ * Drop the job records of one or more AGENTS (#734) — called when a project is
+ * deleted, for every agent name that project owned (keeper, sweeper, hooks,
+ * triggers). Agent-keyed rather than project-keyed because the agent name is
+ * what the record actually carries.
+ *
+ * This is the containment half of the fix rather than the structural one: the
+ * durable answer to "a re-created project inherits the old one's records" is to
+ * key them by a stable project id instead of the user-controlled, reusable slug.
+ * That is a herdctl-side identity change (records are herdctl's format, written
+ * by its runtimes); purging on delete makes the leak impossible NOW without
+ * waiting for it, and stays correct afterwards.
+ */
+export declare function purgeAgentJobs(stateDir: string, agents: string[]): Promise<number>;
 /**
  * Point every herdctl job record for `sessionId` at the project's keeper so
  * the core attribution index (last-write-wins per session) lists the session

package/packages/server/dist/herdctl-jobs.js

@@ -138,6 +138,100 @@ export async function listRunsForAgents(stateDir, agents, limit = 200) {
     const filtered = jobs.filter((j) => wanted.has(j.agent));
     return limit > 0 ? filtered.slice(0, limit) : filtered;
 }
+/**
+ * Delete every job record matching `match`, plus each one's sibling `.jsonl`
+ * output file. Returns how many records were removed.
+ *
+ * The shared inverse of the writes above (#732 / #734). The jobs directory is
+ * append-only and fleet-wide, and until now NOTHING ever removed a record — so a
+ * record outlived whatever it described. Two user-visible consequences, one
+ * mechanism:
+ *
+ *  - A deleted CHAT kept feeding {@link lastTurnCompletedAtByProject}, i.e. the
+ *    sidebar unread badge, with no chat left to open to clear it (#732).
+ *  - A deleted PROJECT left its keeper's whole history behind, keyed by the
+ *    agent name — which is derived from the slug, which is derived from the
+ *    NAME. Re-creating a project called the same thing therefore inherited the
+ *    previous incarnation's `/runs`, prompt text and reply summaries included
+ *    (#734).
+ *
+ * Records are matched by reading them, not by parsing filenames: a job id
+ * encodes only a date and six characters of the session id, which is neither an
+ * agent nor a reliable session key.
+ *
+ * Best-effort per file, deliberately: a record we cannot read is a record we
+ * cannot prove is ours, so it is left alone rather than removed on a guess, and
+ * an unlink failure never fails the delete the user actually asked for. The
+ * caller invalidates {@link JobsDirIndex} afterwards — the index also drops
+ * vanished files on its own next scan, so this is belt-and-braces.
+ */
+async function purgeJobs(stateDir, match) {
+    const jobsDir = jobsDirOf(stateDir);
+    let entries = [];
+    try {
+        entries = await fs.readdir(jobsDir);
+    }
+    catch {
+        return 0; // no jobs dir yet — nothing to purge
+    }
+    let removed = 0;
+    for (const name of entries) {
+        if (!name.endsWith(".yaml"))
+            continue;
+        const file = path.join(jobsDir, name);
+        let parsed = null;
+        try {
+            parsed = YAML.parse(await fs.readFile(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || !match(parsed))
+            continue;
+        await fs.rm(file, { force: true }).catch(() => undefined);
+        // The record names its own output file; fall back to the `<id>.jsonl`
+        // convention {@link writeAgentAdoptionJob} writes when it does not.
+        const output = typeof parsed.output_file === "string" && parsed.output_file.length > 0
+            ? parsed.output_file
+            : path.join(jobsDir, `${name.slice(0, -".yaml".length)}.jsonl`);
+        // Only ever unlink an output file that lives in the jobs dir we just read.
+        if (path.dirname(path.resolve(output)) === path.resolve(jobsDir)) {
+            await fs.rm(output, { force: true }).catch(() => undefined);
+        }
+        removed++;
+    }
+    return removed;
+}
+/**
+ * Drop the job records of one or more CHATS (#732) — called when Paddock removes
+ * a chat from a project, so the record cannot outlive the transcript and keep
+ * the sidebar badge counting a chat that is no longer there to open.
+ */
+export async function purgeSessionJobs(stateDir, sessionIds) {
+    if (sessionIds.length === 0)
+        return 0;
+    const wanted = new Set(sessionIds);
+    return purgeJobs(stateDir, (r) => typeof r.session_id === "string" && wanted.has(r.session_id));
+}
+/**
+ * Drop the job records of one or more AGENTS (#734) — called when a project is
+ * deleted, for every agent name that project owned (keeper, sweeper, hooks,
+ * triggers). Agent-keyed rather than project-keyed because the agent name is
+ * what the record actually carries.
+ *
+ * This is the containment half of the fix rather than the structural one: the
+ * durable answer to "a re-created project inherits the old one's records" is to
+ * key them by a stable project id instead of the user-controlled, reusable slug.
+ * That is a herdctl-side identity change (records are herdctl's format, written
+ * by its runtimes); purging on delete makes the leak impossible NOW without
+ * waiting for it, and stays correct afterwards.
+ */
+export async function purgeAgentJobs(stateDir, agents) {
+    if (agents.length === 0)
+        return 0;
+    const wanted = new Set(agents);
+    return purgeJobs(stateDir, (r) => typeof r.agent === "string" && wanted.has(r.agent));
+}
 /**
  * Point every herdctl job record for `sessionId` at the project's keeper so
  * the core attribution index (last-write-wins per session) lists the session

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

@@ -515,6 +515,52 @@ export declare class HerdctlService {
      * — so `retained` is how a caller tells "gone" from "no longer shown here".
      */
     deleteSession(agentName: string, sessionId: string): Promise<ChatDeletion>;
+    /**
+     * Drop the herdctl job records for chats that have left this instance (#732),
+     * so a record cannot outlive its transcript and keep the sidebar unread badge
+     * counting a chat there is no longer anything to open.
+     *
+     * Takes a LIST rather than one id, and is called by the delete routes rather
+     * than from inside {@link deleteSession}, for one reason: purging is a scan of
+     * the whole shared jobs directory, and the batch route deletes up to 500 chats
+     * in a loop. Per-chat purging would re-scan a 2,000-record directory 500 times
+     * (see `herdctl-jobs-index.ts` for what that costs). One pass, all ids.
+     *
+     * Callers pass only the chats whose transcript was actually REMOVED. Under
+     * `claude.transcripts: host` a delete RELEASES instead — the chat is still
+     * listed there, a known deferred gap (#693, asserted by
+     * `delete-chat-host-transcripts.test.ts`), and purging would close it as a
+     * side effect, because the job record is part of what re-attributes a
+     * structurally-discovered session to the keeper. Resolving somebody else's
+     * deferred decision by accident is not this change's business, and keeping the
+     * record for a chat that is still in the list is coherent anyway:
+     * `buildChatTurns` prunes against the live chat list, so the badge follows the
+     * list either way — and will stop counting the chat the moment #693 makes it
+     * leave.
+     *
+     * Best-effort: tidying state must never fail the delete the user asked for.
+     */
+    purgeSessionJobs(sessionIds: string[]): Promise<void>;
+    /**
+     * Drop the herdctl job records of every agent a project owned (#734) — the
+     * records half of a project delete.
+     *
+     * Job records are keyed by AGENT NAME, and an agent name is derived from the
+     * slug, which is derived from the project NAME. So without this, deleting
+     * "Foo" and creating a new "Foo" hands the new project the old one's run
+     * history: prompts, reply summaries, and a phantom `chatTurns` entry that
+     * shows an unread badge on a project with zero chats. Files, `.chats/` and
+     * `read-state.json` were already cleaned; these were the one thing left.
+     *
+     * Takes the same hook/trigger name lists {@link removeProjectAgent} does, so
+     * the two together are the full inverse of the create flow — and so they stay
+     * in step: if a delete ever has to sweep DESCENDANT workspaces (nesting), both
+     * need the same widening, not just one. Matching is on the exact agent name,
+     * so deleting `foo` cannot touch a sibling `foo-bar`.
+     *
+     * Best-effort — the project directory is already gone by the time we get here.
+     */
+    purgeProjectJobs(slug: string, hookNames?: string[], triggerNames?: string[]): Promise<void>;
     /**
      * Drop the agent-level session pointer when it names a transcript we just
      * removed. Issue #730 — silent data loss, and the fix is one `rm` of a file

package/packages/server/dist/herdctl.js

@@ -903,6 +903,64 @@ export class HerdctlService {
         this.invalidateSessions(agentName);
         return { removed: false, retained: true };
     }
+    /**
+     * Drop the herdctl job records for chats that have left this instance (#732),
+     * so a record cannot outlive its transcript and keep the sidebar unread badge
+     * counting a chat there is no longer anything to open.
+     *
+     * Takes a LIST rather than one id, and is called by the delete routes rather
+     * than from inside {@link deleteSession}, for one reason: purging is a scan of
+     * the whole shared jobs directory, and the batch route deletes up to 500 chats
+     * in a loop. Per-chat purging would re-scan a 2,000-record directory 500 times
+     * (see `herdctl-jobs-index.ts` for what that costs). One pass, all ids.
+     *
+     * Callers pass only the chats whose transcript was actually REMOVED. Under
+     * `claude.transcripts: host` a delete RELEASES instead — the chat is still
+     * listed there, a known deferred gap (#693, asserted by
+     * `delete-chat-host-transcripts.test.ts`), and purging would close it as a
+     * side effect, because the job record is part of what re-attributes a
+     * structurally-discovered session to the keeper. Resolving somebody else's
+     * deferred decision by accident is not this change's business, and keeping the
+     * record for a chat that is still in the list is coherent anyway:
+     * `buildChatTurns` prunes against the live chat list, so the badge follows the
+     * list either way — and will stop counting the chat the moment #693 makes it
+     * leave.
+     *
+     * Best-effort: tidying state must never fail the delete the user asked for.
+     */
+    async purgeSessionJobs(sessionIds) {
+        await jobs.purgeSessionJobs(this.cfg.stateDir, sessionIds).catch(() => 0);
+        this.jobsIndexOrNull?.invalidate();
+    }
+    /**
+     * Drop the herdctl job records of every agent a project owned (#734) — the
+     * records half of a project delete.
+     *
+     * Job records are keyed by AGENT NAME, and an agent name is derived from the
+     * slug, which is derived from the project NAME. So without this, deleting
+     * "Foo" and creating a new "Foo" hands the new project the old one's run
+     * history: prompts, reply summaries, and a phantom `chatTurns` entry that
+     * shows an unread badge on a project with zero chats. Files, `.chats/` and
+     * `read-state.json` were already cleaned; these were the one thing left.
+     *
+     * Takes the same hook/trigger name lists {@link removeProjectAgent} does, so
+     * the two together are the full inverse of the create flow — and so they stay
+     * in step: if a delete ever has to sweep DESCENDANT workspaces (nesting), both
+     * need the same widening, not just one. Matching is on the exact agent name,
+     * so deleting `foo` cannot touch a sibling `foo-bar`.
+     *
+     * Best-effort — the project directory is already gone by the time we get here.
+     */
+    async purgeProjectJobs(slug, hookNames = [], triggerNames = []) {
+        const agents = [
+            keeperAgentName(slug),
+            sweeperAgentName(slug),
+            ...hookNames.map((name) => hookAgentName(slug, name)),
+            ...triggerNames.map((name) => triggerAgentName(slug, name)),
+        ];
+        await jobs.purgeAgentJobs(this.cfg.stateDir, agents).catch(() => 0);
+        this.jobsIndexOrNull?.invalidate();
+    }
     /**
      * Drop the agent-level session pointer when it names a transcript we just
      * removed. Issue #730 — silent data loss, and the fix is one `rm` of a file

package/packages/server/dist/instance-config.d.ts

@@ -74,7 +74,17 @@ export interface InstanceConfigFieldDto {
     help?: string;
     type: FieldType;
     enumValues?: readonly string[];
+    /** EFFECTIVE now: the value the running (frozen) process resolved at boot. */
     value: unknown;
+    /**
+     * PENDING: what this field would resolve to if the process restarted right
+     * now — i.e. what is in `paddock.config.yaml` this instant (or the built-in
+     * default where the file says nothing, or `value` where an env var wins). This
+     * is what the editor renders and what a save round-trips through (#722).
+     */
+    pendingValue: unknown;
+    /** `pendingValue` differs from `value` — the file has diverged from the process. */
+    pendingRestart: boolean;
     default: unknown;
     editable: boolean;
     sensitive: boolean;
@@ -92,9 +102,33 @@ export interface InstanceConfigDto {
     groups: InstanceConfigGroupDto[];
     /** Absolute path of the file a PUT writes to (informational). */
     configPath: string;
-    /** Always false — instance config is frozen at boot; edits need a restart. */
-    restartRequired: false;
+    /**
+     * At least one editable field's `pendingValue` differs from its `value`: the
+     * file on disk no longer describes the running process, and a restart would
+     * change behaviour. Was hardcoded `false` before #722 — which meant nothing
+     * ever told an operator their own save was unapplied.
+     */
+    restartRequired: boolean;
+    /**
+     * Fingerprint of the config file as read for THIS response (`null` when the
+     * file does not exist yet). A client echoes it back as `expectedVersion` on
+     * the PUT; the server refuses the write if the file changed meanwhile, so two
+     * tabs conflict loudly instead of silently last-writer-winning (#722).
+     */
+    configVersion: string | null;
+    /**
+     * Set when the file exists but could not be read or parsed. Pending values are
+     * unknowable in that state, so they fall back to the effective ones — better
+     * to say why than to silently report "nothing pending".
+     */
+    configFileError?: string;
 }
+/**
+ * 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 declare function instanceConfigVersion(configPath: string): string | null;
 /**
  * Resolve the path a PUT writes to: an explicit `PADDOCK_CONFIG` env var wins
  * (the same rule {@link import("./config.js").loadConfigFile} reads it back
@@ -102,9 +136,25 @@ export interface InstanceConfigDto {
  */
 export declare function instanceConfigPath(cfg: PaddockConfig): string;
 /**
- * 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 declare function buildInstanceConfig(cfg: PaddockConfig): InstanceConfigDto;
 /** A rejected PUT: which field failed and why (surfaced as a 400). */
@@ -117,6 +167,7 @@ export declare 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`

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);