@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/dist/settings-api.js

@@ -1,7 +1,41 @@
+import { normalizeSettingsInstancePatch, removesInstanceOverride } from "./settings-instance-patch.js";
+import { settingsRequestExecution, settingsWrite } from "./settings-request-capability.js";
+import { noteSettingsWrite, settingsUndo, undoSettingsPaths } from "./settings-transaction.js";
+import { readBoundedWebBody } from "./web-body.js";
+import { validPublicLinkPatch } from "./public-web-link.js";
+import { permitWebContinuation } from "./web-continuation.js";
+/**
+ * Settings Web API (`/settings`) — CRUD over fleet.yaml + classicBot.yaml.
+ *
+ *   GET  /settings                              → static page
+ *   GET  /api/settings/fleet                    → fleet config as JSON
+ *   GET  /api/settings/classic                  → classicBot.yaml as JSON
+ *   PUT  /api/settings/fleet/defaults           → merge fleet defaults
+ *   PUT  /api/settings/fleet/channels           → replace channels[]
+ *   POST /api/settings/fleet/instances/:name    → create instance
+ *   PATCH/api/settings/fleet/instances/:name    → merge into instance
+ *   DELETE /api/settings/fleet/instances/:name  → remove instance
+ *   PUT  /api/settings/classic/defaults         → merge classic defaults
+ *   PATCH/api/settings/classic/channels/:key    → update + restart a Classic channel
+ *   POST /api/settings/reload                   → SIGHUP hot-reload
+ *   POST /api/settings/instances/:name/pause    → manually pause a running instance
+ *   POST /api/settings/instances/:name/wake     → manually wake a paused instance
+ *   GET  /api/settings/status-emojis            → status-emoji keys, built-ins, pickable sets
+ *   POST /api/settings/status-emojis/preview    → resolve a map exactly as the bots will
+ *   GET  /api/settings/status-emojis/guild-emojis?channel=<id>[&refresh=1] → a Discord bot's servers' emojis
+ *
+ * Auth: all routes require the web.token — enforced by the global web-token gate
+ * in fleet-manager BEFORE this handler runs (settings paths are not exempt), so
+ * no per-route auth is repeated here.
+ *
+ * Writes are validated first (config-validator): any error → 400 and nothing is
+ * written; warnings are non-blocking and returned alongside the result.
+ */
+import { serveAppShell } from "./web-api.js";
+import { isSettingsPage } from "./web-shell-routes.js";
 import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, statSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import yaml from "js-yaml";
 import { KNOWN_BACKENDS, validateFleetConfig, validateClassicBotConfig } from "./config-validator.js";
 import { clearPausedMarker } from "./pause-marker.js";
@@ -11,7 +45,6 @@ import { handleQuickstartRequest } from "./quickstart-api.js";
 import { requestSessionBinding, } from "./connection-secrets.js";
 import { providerRegistryEnvKeys, isReservedProviderEnvKey } from "./provider-secret-registry.js";
 import { STATUS_EMOJI_CONFIG_KEYS, STATUS_EMOJI_SUGGESTIONS, TELEGRAM_REACTION_EMOJIS, builtinStatusEmojis, customEmojiValue, emojiImageUrl, previewStatusEmojis, } from "./status-emojis.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
 function json(res, code, body, noStore = false) {
     res.writeHead(code, {
         "Content-Type": "application/json",
@@ -20,21 +53,7 @@ function json(res, code, body, noStore = false) {
     res.end(JSON.stringify(body));
 }
 function readBody(req, maxBytes) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let size = 0;
-        req.on("data", (c) => {
-            size += c.length;
-            if (size > maxBytes) {
-                reject(new Error("payload too large"));
-                req.destroy();
-                return;
-            }
-            chunks.push(c);
-        });
-        req.on("end", () => resolve(Buffer.concat(chunks)));
-        req.on("error", reject);
-    });
+    return readBoundedWebBody(req, maxBytes);
 }
 /**
  * Channel/group identifiers are opaque provider coordinates.  JSON numbers
@@ -52,7 +71,7 @@ function normalizeChannelIdValue(value, path) {
     return { ok: false, error: `${path} must be a string (or a safe integer)` };
 }
 export function isSettingsPath(path) {
-    return path === "/settings" || path.startsWith("/api/settings/");
+    return isSettingsPage(path) || path.startsWith("/api/settings/");
 }
 const classicPath = (ctx) => join(ctx.dataDir, "classicBot.yaml");
 class ClassicConfigParseError extends Error {
@@ -78,6 +97,7 @@ function writeClassicAtomic(ctx, classic) {
     const target = classicPath(ctx);
     const temp = `${target}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
     const mode = existsSync(target) ? statSync(target).mode : 0o600;
+    noteSettingsWrite(target, readClassic(ctx), classic);
     try {
         writeFileSync(temp, yaml.dump(classic, { lineWidth: -1 }), { encoding: "utf-8", mode });
         renameSync(temp, target);
@@ -98,6 +118,31 @@ const issueKey = (i) => i.path + "\u0000" + i.message;
  * user out of saving anything, which reads as "save didn't persist".
  * Returns true (and responds 400) when the edit adds errors.
  */
+/**
+ * #1490 (Fable's 2.2 audit): the connection fields Settings writes. A PUT carries whole connections back, so a field
+ * outside these (one added by hand to fleet.yaml) passes through unchanged — but it is never added or changed here:
+ * an inline `bot_token`, or anything else, cannot reach fleet.yaml through this endpoint.
+ */
+const CHANNEL_FIELDS = new Set(["id", "type", "mode", "bot_token_env", "group_id", "access", "options", "telegram_api_root", "mirror_topic_id"]);
+const CHANNEL_ACCESS_FIELDS = new Set(["mode", "allowed_users", "max_pending_codes", "code_expiry_minutes"]);
+const CHANNEL_OPTION_FIELDS = new Set(["category_name", "general_channel_id", "topic_probe", "sticker_sets", "status_emojis"]);
+function unownedChannelField(candidate, previous) {
+    const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+    const check = (fields, next, prev, at) => {
+        const before = record(prev) ? prev : {};
+        for (const key of Object.keys(next)) {
+            if (fields.has(key))
+                continue;
+            if (Object.hasOwn(before, key) && JSON.stringify(before[key]) === JSON.stringify(next[key]))
+                continue;
+            return `${at}${key}`;
+        }
+        return null;
+    };
+    return check(CHANNEL_FIELDS, candidate, previous, "")
+        ?? (record(candidate.access) ? check(CHANNEL_ACCESS_FIELDS, candidate.access, previous?.access, "access.") : null)
+        ?? (record(candidate.options) ? check(CHANNEL_OPTION_FIELDS, candidate.options, previous?.options, "options.") : null);
+}
 function rejectIfWorse(res, before, after) {
     const had = new Set(before.errors.map(issueKey));
     const introduced = after.errors.filter(e => !had.has(issueKey(e)));
@@ -118,16 +163,13 @@ export function handleSettingsRequest(req, res, url, ctx) {
     if (!isSettingsPath(path))
         return false;
     const method = req.method ?? "GET";
-    // ── Static page ──
-    if (method === "GET" && path === "/settings") {
-        try {
-            const html = readFileSync(join(__dirname, "ui", "settings.html"), "utf-8");
-            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-            res.end(html);
-        }
-        catch {
-            json(res, 500, { error: "settings.html not found" });
+    // ── The page: the app shell, which mounts the Settings panel (#1408 step 3) ──
+    if (isSettingsPage(path)) {
+        if (method !== "GET" && method !== "HEAD") {
+            json(res, 405, { error: "Method not allowed" });
+            return true;
         }
+        serveAppShell(req, res, ctx, "full");
         return true;
     }
     // ── Reads ──
@@ -140,6 +182,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             // Non-null means a restart cannot clear the fleet row, so the page shows
             // the mismatch instead of offering a button that can never succeed.
             fleet_signature_mismatch: ctx.fleetSignatureMismatchKeys?.() ?? null,
+            // Whether the provider-secret routes exist on this fleet: the page reads them only then (no 404 on every load).
+            provider_secrets: ctx.providerSecretsEnabled?.() === true,
         });
         return true;
     }
@@ -174,6 +218,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
     }
     if (method === "POST" && path === "/api/settings/status-emojis/preview") {
         readBody(req, 64 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -279,6 +325,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const specId = decodeURIComponent(providerSecretVerifyMatch[1]);
         readBody(req, 16 * 1024).then(async (buf) => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -314,6 +362,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const specId = decodeURIComponent(providerSecretApplyMatch[1]);
         readBody(req, 16 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -328,7 +378,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 return json(res, 400, { error: "verification_id required" }, true);
             if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(key))
                 return json(res, 400, { error: "Idempotency-Key required" }, true);
-            const result = ctx.startProviderSecretApply({ specId, verificationId, sessionBinding: requestSessionBinding(req), idempotencyKey: key });
+            const result = ctx.startProviderSecretApply({ specId, verificationId, sessionBinding: requestSessionBinding(req), idempotencyKey: key, execution: settingsRequestExecution(req) });
             if ("error" in result)
                 return json(res, 422, { ok: false, error: "provider secret apply rejected" }, true);
             if ("busy" in result)
@@ -364,6 +414,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const connectionId = decodeURIComponent(secretVerifyMatch[1]);
         readBody(req, 16 * 1024).then(async (buf) => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -407,6 +459,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const connectionId = decodeURIComponent(secretApplyMatch[1]);
         readBody(req, 16 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -425,7 +479,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 connectionId,
                 verificationId,
                 sessionBinding: requestSessionBinding(req),
-                idempotencyKey: key,
+                idempotencyKey: key, execution: settingsRequestExecution(req),
             });
             if ("error" in result)
                 return json(res, 422, { ok: false, error: "secret apply rejected" }, true);
@@ -468,6 +522,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const connectionId = decodeURIComponent(bindingVerifyMatch[1]);
         readBody(req, 16 * 1024).then(async (buf) => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -511,6 +567,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const connectionId = decodeURIComponent(bindingApplyMatch[1]);
         readBody(req, 16 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -526,7 +584,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
             if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(key))
                 return json(res, 400, { error: "Idempotency-Key required" }, true);
             const result = ctx.startConnectionBindingApply({
-                connectionId, verificationId, sessionBinding: requestSessionBinding(req), idempotencyKey: key,
+                connectionId, verificationId, sessionBinding: requestSessionBinding(req), idempotencyKey: key, execution: settingsRequestExecution(req),
             });
             if ("error" in result)
                 return json(res, 422, { ok: false, error: "binding apply rejected" }, true);
@@ -572,6 +630,53 @@ export function handleSettingsRequest(req, res, url, ctx) {
             .catch(err => json(res, 409, { error: err.message }));
         return true;
     }
+    // One hot web toggle; an unrelated Settings edit never materializes defaults.
+    if (method === "PUT" && path === "/api/settings/fleet/web") {
+        if (!cfg) {
+            json(res, 503, { error: "fleet not loaded" });
+            return true;
+        }
+        readBody(req, 4096).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8"));
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" });
+            }
+            if (!body || typeof body !== "object" || Array.isArray(body)
+                || Object.keys(body).some(key => key !== "echo_to_channel" && key !== "public_link"))
+                return json(res, 400, { error: "unknown web field" });
+            const patch = body;
+            if (patch.echo_to_channel !== undefined && typeof patch.echo_to_channel !== "boolean")
+                return json(res, 400, { error: "echo_to_channel must be a boolean" });
+            if (patch.public_link !== undefined && !validPublicLinkPatch(patch.public_link))
+                return json(res, 400, { error: "invalid public_link settings" });
+            const changes = [];
+            const web = { ...cfg.web };
+            if (typeof patch.echo_to_channel === "boolean") {
+                web.echo_to_channel = patch.echo_to_channel;
+                changes.push({ path: ["web", "echo_to_channel"], value: patch.echo_to_channel });
+            }
+            if (validPublicLinkPatch(patch.public_link)) {
+                if (Object.keys(patch.public_link).length)
+                    web.public_link = { ...web.public_link, ...patch.public_link };
+                for (const [key, value] of Object.entries(patch.public_link))
+                    changes.push({ path: ["web", "public_link", key], value });
+            }
+            if (!changes.length)
+                return json(res, 200, { ok: true });
+            const before = validateFleetConfig(cfg);
+            const after = validateFleetConfig({ ...cfg, web });
+            if (rejectIfWorse(res, before, after))
+                return;
+            settingsWrite(req, () => { cfg.web = web; ctx.saveFleetConfig(changes); });
+            json(res, 200, { ok: true, warnings: saveWarnings(before, after) });
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
     // ── Fleet defaults ──
     if (method === "PUT" && path === "/api/settings/fleet/defaults") {
         if (!cfg) {
@@ -579,6 +684,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 512 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -597,8 +704,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
             const after = validateFleetConfig({ ...cfg, defaults: merged });
             if (rejectIfWorse(res, before, after))
                 return;
-            cfg.defaults = merged;
-            ctx.saveFleetConfig();
+            settingsWrite(req, () => { cfg.defaults = merged; ctx.saveFleetConfig(); });
             json(res, 200, { ok: true, warnings: saveWarnings(before, after) });
         }).catch(() => json(res, 400, { error: "bad request" }));
         return true;
@@ -610,6 +716,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 512 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "[]");
@@ -650,6 +758,9 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 const id = typeof candidate.id === "string" ? candidate.id
                     : typeof candidate.type === "string" ? candidate.type : `channel-${index}`;
                 const previous = currentById.get(id);
+                const unowned = unownedChannelField(candidate, previous);
+                if (unowned)
+                    return json(res, 400, { ok: false, error: `unsupported connection field: channels[${index}].${unowned}` }, true);
                 const tokenEnv = typeof candidate.bot_token_env === "string" ? candidate.bot_token_env : null;
                 if (tokenEnv && (providerRegistryEnvKeys().has(tokenEnv) || isReservedProviderEnvKey(tokenEnv))) {
                     return json(res, 409, { ok: false, error: "bot token env conflicts with a protected provider secret key" }, true);
@@ -680,9 +791,22 @@ export function handleSettingsRequest(req, res, url, ctx) {
             const after = validateFleetConfig(next);
             if (rejectIfWorse(res, before, after))
                 return;
-            cfg.channels = normalizedBody;
-            delete cfg.channel;
-            ctx.saveFleetConfig();
+            const previous = { channels: cfg.channels, channel: cfg.channel, hadChannel: "channel" in cfg };
+            try {
+                settingsWrite(req, () => {
+                    cfg.channels = normalizedBody;
+                    delete cfg.channel;
+                    ctx.saveFleetConfig();
+                });
+            }
+            catch (err) {
+                // #1056: the save refused (fleet.yaml unchanged): memory goes back to what the file still says.
+                cfg.channels = previous.channels;
+                if (previous.hadChannel)
+                    cfg.channel = previous.channel;
+                ctx.logger.warn({ err }, "settings: channels save refused");
+                return json(res, 500, { ok: false, error: err.message });
+            }
             json(res, 200, { ok: true, warnings: saveWarnings(before, after) });
         }).catch(() => json(res, 400, { error: "bad request" }));
         return true;
@@ -690,6 +814,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
     // ── Classic defaults ──
     if (method === "PUT" && path === "/api/settings/classic/defaults") {
         readBody(req, 512 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -717,7 +843,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 return;
             classic.defaults = merged;
             try {
-                writeClassicAtomic(ctx, classic);
+                settingsWrite(req, () => writeClassicAtomic(ctx, classic));
             }
             catch (err) {
                 ctx.logger.warn({ err }, "settings: failed to atomically update classicBot.yaml");
@@ -744,6 +870,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 512 * 1024).then(async (buf) => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -761,6 +889,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 "context_lines",
                 "tool_progress",
                 "reply_completion_guard",
+                "web_echo",
             ]);
             const unknown = Object.keys(body).filter(field => !allowed.has(field));
             if (unknown.length)
@@ -787,6 +916,9 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 && typeof body.reply_completion_guard !== "boolean") {
                 return json(res, 400, { error: "reply_completion_guard must be a boolean" });
             }
+            if (body.web_echo !== undefined && typeof body.web_echo !== "boolean") {
+                return json(res, 400, { error: "web_echo must be a boolean" });
+            }
             let classic;
             try {
                 classic = readClassic(ctx);
@@ -797,7 +929,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
             const channels = classic.channels;
             if (!channels || typeof channels !== "object" || Array.isArray(channels))
                 return json(res, 404, { error: "classic channel not found" });
-            const current = channels[key];
+            const current = Object.hasOwn(channels, key) ? channels[key] : undefined;
             if (!current || typeof current !== "object" || Array.isArray(current))
                 return json(res, 404, { error: "classic channel not found" });
             const previous = structuredClone(classic);
@@ -816,29 +948,42 @@ export function handleSettingsRequest(req, res, url, ctx) {
             if (rejectIfWorse(res, before, after))
                 return;
             try {
-                writeClassicAtomic(ctx, classic);
+                settingsWrite(req, () => writeClassicAtomic(ctx, classic), false);
             }
             catch (err) {
                 ctx.logger.warn({ err, key }, "settings: failed to atomically update classic channel");
                 return json(res, 500, { error: "failed to write classicBot.yaml" });
             }
+            const undo = settingsUndo(classicPath(ctx), previous, classic, Object.keys(body).map(field => ["channels", key, field]));
+            const execution = settingsRequestExecution(req);
             const instanceName = typeof merged.instanceName === "string" ? merged.instanceName : undefined;
+            const restore = instanceName ? ctx.captureClassicSettingsRestoration?.(instanceName, Object.keys(body), execution) : undefined;
             try {
                 if (instanceName && ctx.restartClassicInstanceFromSettings) {
-                    await ctx.restartClassicInstanceFromSettings(instanceName, Object.keys(body));
+                    if (execution)
+                        await ctx.restartClassicInstanceFromSettings(instanceName, Object.keys(body), execution);
+                    else
+                        await ctx.restartClassicInstanceFromSettings(instanceName, Object.keys(body));
+                    execution?.assert();
                 }
             }
             catch (err) {
                 // Keep disk and runtime consistent if the requested restart fails.
                 try {
-                    writeClassicAtomic(ctx, previous);
+                    const retained = undoSettingsPaths(classicPath(ctx), readClassic(ctx), undo);
+                    writeClassicAtomic(ctx, retained.value);
+                    if (retained.conflicts)
+                        throw new Error("concurrent Classic edit retained");
                 }
                 catch (rollbackErr) {
                     ctx.logger.error({ err: rollbackErr, key }, "settings: failed to roll back classic channel update");
                 }
                 if (instanceName && ctx.restartClassicInstanceFromSettings) {
                     try {
-                        await ctx.restartClassicInstanceFromSettings(instanceName, Object.keys(body));
+                        if (restore)
+                            await restore();
+                        else
+                            await ctx.restartClassicInstanceFromSettings(instanceName, Object.keys(body));
                     }
                     catch (recoveryErr) {
                         ctx.logger.error({ err: recoveryErr, key, instanceName }, "settings: failed to restore classic instance after rollback");
@@ -847,6 +992,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 ctx.logger.warn({ err, key, instanceName }, "settings: classic channel restart failed; config rolled back");
                 return json(res, 409, { error: `classic instance restart failed: ${err.message}` });
             }
+            execution?.complete();
             ctx.logger.info({ key, instanceName }, "settings: updated classic channel");
             const hotOnly = Object.keys(body).length > 0
                 && Object.keys(body).every(field => CLASSIC_HOT_CONFIG_KEYS.has(field));
@@ -871,6 +1017,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 64 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body = {};
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -919,6 +1067,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 64 * 1024).then(async (buf) => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body = {};
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -983,9 +1133,6 @@ export function handleSettingsRequest(req, res, url, ctx) {
     }
     // ── Instances (create / patch / delete) ──
     const validName = (n) => !!n && /^[^\\/\x00]+$/.test(n);
-    const nullableInstanceOverrides = new Set(["model", "auto_pause_after", "hang_detector", "agent_mode", "tool_set", "tool_progress", "reply_completion_guard", "log_level", "lightweight", "model_failover", "display_name", "status_emojis", "cross_instance_visibility"]);
-    const removesInstanceOverride = (key, value) => nullableInstanceOverrides.has(key)
-        && (value === null || (key === "model" && typeof value === "string" && value.trim() === ""));
     const rawInstancePatches = (name, patch) => {
         const changes = [];
         for (const [key, value] of Object.entries(patch)) {
@@ -1008,33 +1155,24 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         const base = (exists ? cfg.instances[name] : {});
         const patch = body;
-        const mergedInst = { ...base, ...patch };
-        if (patch.hang_detector && typeof patch.hang_detector === "object" && !Array.isArray(patch.hang_detector)) {
-            const hangPatch = patch.hang_detector;
-            const mergedHang = { ...(base.hang_detector ?? {}), ...hangPatch };
-            // Nested null removes only the timeout override while preserving any
-            // independently configured `enabled` override.
-            if (hangPatch.timeout_minutes === null)
-                delete mergedHang.timeout_minutes;
-            if (Object.keys(mergedHang).length)
-                mergedInst.hang_detector = mergedHang;
-            else
-                delete mergedInst.hang_detector;
+        let mergedInst;
+        try {
+            mergedInst = normalizeSettingsInstancePatch(base, patch);
         }
-        // JSON has no `undefined`; null is the PATCH sentinel for removing an
-        // optional override so the instance inherits the fleet default again.
-        for (const key of nullableInstanceOverrides) {
-            if (removesInstanceOverride(key, patch[key]))
-                delete mergedInst[key];
+        catch {
+            json(res, 400, { error: "unsupported_instance_null" });
+            return;
         }
         const before = validateFleetConfig(cfg);
         const after = validateFleetConfig({ ...cfg, instances: { ...cfg.instances, [name]: mergedInst } });
         if (rejectIfWorse(res, before, after))
             return;
-        cfg.instances[name] = mergedInst;
-        if (!exists)
-            clearPausedMarker(join(ctx.dataDir, "instances", name));
-        ctx.saveFleetConfig(rawInstancePatches(name, patch));
+        settingsWrite(req, () => {
+            Object.defineProperty(cfg.instances, name, { value: mergedInst, writable: true, enumerable: true, configurable: true });
+            if (!exists)
+                clearPausedMarker(join(ctx.dataDir, "instances", name));
+            ctx.saveFleetConfig(rawInstancePatches(name, patch));
+        });
         json(res, 200, { ok: true, warnings: saveWarnings(before, after) });
     };
     // POST /api/settings/fleet/instances  — create, name taken from the body.
@@ -1044,6 +1182,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         readBody(req, 512 * 1024).then(buf => {
+            if (!permitWebContinuation(req, res, ctx))
+                return;
             let body;
             try {
                 body = JSON.parse(buf.toString("utf-8") || "{}");
@@ -1056,7 +1196,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
             const name = typeof body.name === "string" ? body.name.trim() : "";
             if (!validName(name))
                 return json(res, 400, { error: "missing or invalid instance name (provide `name` in the body)" });
-            if (cfg.instances[name])
+            if (Object.hasOwn(cfg.instances, name))
                 return json(res, 409, { error: "instance already exists" });
             const { name: _n, ...instBody } = body;
             commitInstance(name, false, instBody);
@@ -1076,19 +1216,21 @@ export function handleSettingsRequest(req, res, url, ctx) {
             return true;
         }
         if (method === "DELETE") {
-            if (!cfg.instances[name]) {
+            if (!Object.hasOwn(cfg.instances, name)) {
                 json(res, 404, { error: "instance not found" });
                 return true;
             }
             // DELETE never blocks on validation; surface any resulting warnings.
-            delete cfg.instances[name];
-            clearPausedMarker(join(ctx.dataDir, "instances", name));
-            ctx.saveFleetConfig();
+            settingsWrite(req, () => {
+                delete cfg.instances[name];
+                clearPausedMarker(join(ctx.dataDir, "instances", name));
+                ctx.saveFleetConfig();
+            });
             json(res, 200, { ok: true, warnings: validateFleetConfig(cfg).warnings });
             return true;
         }
         if (method === "POST" || method === "PATCH") {
-            const exists = !!cfg.instances[name];
+            const exists = Object.hasOwn(cfg.instances, name);
             if (method === "POST" && exists) {
                 json(res, 409, { error: "instance already exists" });
                 return true;
@@ -1098,6 +1240,8 @@ export function handleSettingsRequest(req, res, url, ctx) {
                 return true;
             }
             readBody(req, 512 * 1024).then(buf => {
+                if (!permitWebContinuation(req, res, ctx))
+                    return;
                 let body;
                 try {
                     body = JSON.parse(buf.toString("utf-8") || "{}");