@songsid/agend 2.1.5 → 2.1.6-beta.10

package/dist/settings-api.js

@@ -5,9 +5,17 @@ import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import { KNOWN_BACKENDS, validateFleetConfig, validateClassicBotConfig } from "./config-validator.js";
 import { clearPausedMarker } from "./pause-marker.js";
+import { buildSettingsImpactSchema, CLASSIC_HOT_CONFIG_KEYS } from "./instance-config-impact.js";
+import { viewOf } from "./apply-job.js";
+import { handleQuickstartRequest } from "./quickstart-api.js";
+import { requestSessionBinding, } from "./connection-secrets.js";
+import { providerRegistryEnvKeys, isReservedProviderEnvKey } from "./provider-secret-registry.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-function json(res, code, body) {
-    res.writeHead(code, { "Content-Type": "application/json" });
+function json(res, code, body, noStore = false) {
+    res.writeHead(code, {
+        "Content-Type": "application/json",
+        ...(noStore ? { "Cache-Control": "no-store" } : {}),
+    });
     res.end(JSON.stringify(body));
 }
 function readBody(req, maxBytes) {
@@ -27,6 +35,21 @@ function readBody(req, maxBytes) {
         req.on("error", reject);
     });
 }
+/**
+ * Channel/group identifiers are opaque provider coordinates.  JSON numbers
+ * are accepted only while they are still exactly representable, then
+ * canonicalized to strings before validation/persistence.  An unsafe number
+ * is rejected rather than silently rounding a Discord snowflake.
+ */
+function normalizeChannelIdValue(value, path) {
+    if (value === undefined || value === null || typeof value === "string") {
+        return { ok: true, value };
+    }
+    if (typeof value === "number" && Number.isSafeInteger(value)) {
+        return { ok: true, value: String(value) };
+    }
+    return { ok: false, error: `${path} must be a string (or a safe integer)` };
+}
 export function isSettingsPath(path) {
     return path === "/settings" || path.startsWith("/api/settings/");
 }
@@ -107,6 +130,18 @@ export function handleSettingsRequest(req, res, url, ctx) {
         return true;
     }
     // ── Reads ──
+    // What each field costs to change, derived from HOT_INSTANCE_CONFIG_KEYS.
+    // The page used to carry its own copy of the hot set plus one hand-written
+    // badge per field, which could disagree with what the fleet actually does.
+    if (method === "GET" && path === "/api/settings/schema") {
+        json(res, 200, {
+            ...buildSettingsImpactSchema(),
+            // 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,
+        });
+        return true;
+    }
     if (method === "GET" && path === "/api/settings/fleet") {
         json(res, 200, ctx.fleetConfig ?? {});
         return true;
@@ -124,6 +159,331 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }
         return true;
     }
+    // ── Secure Connections & Bots ──
+    // These routes deliberately do not reuse the broad fleet/channel CRUD API:
+    // a token is accepted only in a body, verified server-side, and never echoed
+    // or written to a log/SSE frame. Adapter replacement is owned by FleetManager
+    // so writing .env alone can never be reported as "applied".
+    if (method === "GET" && path === "/api/settings/connections") {
+        if (!ctx.listSecureConnections) {
+            json(res, 501, { error: "connection secrets unavailable" });
+            return true;
+        }
+        json(res, 200, ctx.listSecureConnections().map(connection => ({
+            ...connection,
+            token_present: !!connection.token_present,
+        })), true);
+        return true;
+    }
+    // Generic provider API-key registry.  Unlike the legacy connection token
+    // routes, this endpoint accepts a code-owned spec id only; env key, origin,
+    // auth header and verifier are resolved server-side.  The body is consumed
+    // once and no secret-bearing value is ever placed in a URL, job, SSE frame,
+    // or response.
+    const providerSecretsEnabled = ctx.providerSecretsEnabled?.() === true;
+    if (method === "GET" && (path === "/api/settings/provider-secrets" || path === "/api/settings/secrets")) {
+        if (!providerSecretsEnabled) {
+            json(res, 404, { error: "not found" }, true);
+            return true;
+        }
+        if (!ctx.listProviderSecrets) {
+            json(res, 501, { error: "provider secret registry unavailable" }, true);
+            return true;
+        }
+        json(res, 200, ctx.listProviderSecrets().map(item => ({
+            id: item.id,
+            display_name: item.display_name,
+            kind: item.kind,
+            token_present: item.token_present,
+            verifier: item.verifier,
+            activation: item.activation,
+            stale_consumers: item.stale_consumers,
+        })), true);
+        return true;
+    }
+    const providerSecretVerifyMatch = path.match(/^\/api\/settings\/(?:provider-secrets|secrets)\/([^/]+)\/verify$/);
+    if (method === "POST" && providerSecretVerifyMatch) {
+        if (!providerSecretsEnabled) {
+            json(res, 404, { error: "not found" }, true);
+            return true;
+        }
+        if (!ctx.verifyProviderSecret) {
+            json(res, 501, { error: "provider secret registry unavailable" }, true);
+            return true;
+        }
+        const specId = decodeURIComponent(providerSecretVerifyMatch[1]);
+        readBody(req, 16 * 1024).then(async (buf) => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" }, true);
+            }
+            const secret = typeof body.secret === "string" ? body.secret : "";
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!secret)
+                return json(res, 400, { error: "secret required" }, true);
+            if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(key))
+                return json(res, 400, { error: "Idempotency-Key required" }, true);
+            const result = await ctx.verifyProviderSecret({ specId, secret, sessionBinding: requestSessionBinding(req), idempotencyKey: key });
+            if (!result.ok) {
+                const code = result.status === "unsupported_verifier" ? 422 : result.status === "provider_unavailable" ? 503 : 422;
+                return json(res, code, { ok: false, result: result.status, error: result.status === "unsupported_verifier" ? "unsupported verifier" : "provider secret verification failed" }, true);
+            }
+            json(res, 200, { ok: true, result: "verified", verification_id: result.verification_id, expires_at: result.expires_at, spec_id: result.spec_id, activation: result.activation }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }, true));
+        return true;
+    }
+    const providerSecretApplyMatch = path.match(/^\/api\/settings\/(?:provider-secrets|secrets)\/([^/]+)\/apply$/);
+    if (method === "POST" && providerSecretApplyMatch) {
+        if (!providerSecretsEnabled) {
+            json(res, 404, { error: "not found" }, true);
+            return true;
+        }
+        if (!ctx.startProviderSecretApply) {
+            json(res, 501, { error: "provider secret registry unavailable" }, true);
+            return true;
+        }
+        const specId = decodeURIComponent(providerSecretApplyMatch[1]);
+        readBody(req, 16 * 1024).then(buf => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" }, true);
+            }
+            const verificationId = typeof body.verification_id === "string" ? body.verification_id : "";
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!verificationId)
+                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 });
+            if ("error" in result)
+                return json(res, 422, { ok: false, error: "provider secret apply rejected" }, true);
+            if ("busy" in result)
+                return json(res, 409, { ok: false, result: "applying", job_id: result.busy?.id ?? null }, true);
+            json(res, result.reused ? 200 : 202, { ok: true, result: result.job.result, job_id: result.job.id, reused: result.reused, stale_consumers: result.job.stale_consumers ?? [] }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }, true));
+        return true;
+    }
+    const providerSecretStatusMatch = path.match(/^\/api\/settings\/(?:provider-secrets|secrets)\/[^/]+\/apply\/([A-Za-z0-9_-]+)$/);
+    if (method === "GET" && providerSecretStatusMatch) {
+        if (!providerSecretsEnabled) {
+            json(res, 404, { error: "not found" }, true);
+            return true;
+        }
+        if (!ctx.getProviderSecretApply) {
+            json(res, 501, { error: "provider secret registry unavailable" }, true);
+            return true;
+        }
+        const job = ctx.getProviderSecretApply(providerSecretStatusMatch[1], requestSessionBinding(req));
+        if (!job) {
+            json(res, 404, { error: "job not found" }, true);
+            return true;
+        }
+        json(res, 200, job, true);
+        return true;
+    }
+    const secretVerifyMatch = path.match(/^\/api\/settings\/connections\/([^/]+)\/secret\/verify$/);
+    if (method === "POST" && secretVerifyMatch) {
+        const verifyConnectionSecret = ctx.verifyConnectionSecret;
+        if (!verifyConnectionSecret) {
+            json(res, 501, { error: "connection secret verification unavailable" });
+            return true;
+        }
+        const connectionId = decodeURIComponent(secretVerifyMatch[1]);
+        readBody(req, 16 * 1024).then(async (buf) => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" });
+            }
+            const secret = typeof body.secret === "string" ? body.secret : "";
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!secret)
+                return json(res, 400, { error: "secret required" }, true);
+            if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(key))
+                return json(res, 400, { error: "Idempotency-Key required" }, true);
+            const result = await verifyConnectionSecret({
+                connectionId,
+                secret,
+                sessionBinding: requestSessionBinding(req),
+                idempotencyKey: key,
+            });
+            // The provider may have echoed request material in an SDK error. Keep
+            // the HTTP contract deliberately generic; FleetManager logs only a
+            // redacted diagnostic and the browser has no need for the raw reason.
+            if (!result.ok)
+                return json(res, 422, { ok: false, error: "secret verification failed" }, true);
+            json(res, 200, {
+                ok: true,
+                result: "verified",
+                verification_id: result.verification_id,
+                expires_at: result.expires_at,
+                identity: result.identity,
+            }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    const secretApplyMatch = path.match(/^\/api\/settings\/connections\/([^/]+)\/secret\/apply$/);
+    if (method === "POST" && secretApplyMatch) {
+        if (!ctx.startConnectionSecretApply) {
+            json(res, 501, { error: "connection secret apply unavailable" });
+            return true;
+        }
+        const connectionId = decodeURIComponent(secretApplyMatch[1]);
+        readBody(req, 16 * 1024).then(buf => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" });
+            }
+            const verificationId = typeof body.verification_id === "string" ? body.verification_id : "";
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!verificationId)
+                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.startConnectionSecretApply({
+                connectionId,
+                verificationId,
+                sessionBinding: requestSessionBinding(req),
+                idempotencyKey: key,
+            });
+            if ("error" in result)
+                return json(res, 422, { ok: false, error: "secret apply rejected" }, true);
+            if ("busy" in result)
+                return json(res, 409, {
+                    ok: false,
+                    result: "applying",
+                    job_id: result.busy?.id ?? null,
+                }, true);
+            json(res, result.reused ? 200 : 202, {
+                ok: true,
+                result: result.job.result,
+                job_id: result.job.id,
+                reused: result.reused,
+            }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    const secretApplyStatusMatch = path.match(/^\/api\/settings\/connections\/[^/]+\/secret\/apply\/([A-Za-z0-9_-]+)$/);
+    if (method === "GET" && secretApplyStatusMatch) {
+        if (!ctx.getConnectionSecretApply) {
+            json(res, 501, { error: "connection secret apply unavailable" });
+            return true;
+        }
+        const job = ctx.getConnectionSecretApply(secretApplyStatusMatch[1], requestSessionBinding(req));
+        if (!job) {
+            json(res, 404, { error: "job not found" }, true);
+            return true;
+        }
+        // Job errors are already provider-redacted by FleetManager. Never add raw
+        // request data here, and never expose a secret-bearing provider response.
+        json(res, 200, job, true);
+        return true;
+    }
+    const bindingVerifyMatch = path.match(/^\/api\/settings\/connections\/([^/]+)\/binding\/verify$/);
+    if (method === "POST" && bindingVerifyMatch) {
+        if (!ctx.verifyConnectionBinding) {
+            json(res, 501, { error: "connection binding verification unavailable" });
+            return true;
+        }
+        const connectionId = decodeURIComponent(bindingVerifyMatch[1]);
+        readBody(req, 16 * 1024).then(async (buf) => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" });
+            }
+            // Provider IDs must arrive as strings. Accepting a JSON number here can
+            // round a Discord snowflake before the verifier ever sees it.
+            if (typeof body.group_id !== "string"
+                || (body.general_channel_id !== undefined
+                    && body.general_channel_id !== null
+                    && typeof body.general_channel_id !== "string")) {
+                return json(res, 400, { error: "binding IDs must be strings" }, true);
+            }
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!/^[A-Za-z0-9_.:-]{8,128}$/.test(key))
+                return json(res, 400, { error: "Idempotency-Key required" }, true);
+            const result = await ctx.verifyConnectionBinding({
+                connectionId,
+                binding: { group_id: body.group_id, general_channel_id: body.general_channel_id },
+                sessionBinding: requestSessionBinding(req),
+                idempotencyKey: key,
+            });
+            if (!result.ok)
+                return json(res, 422, { ok: false, error: "binding verification failed" }, true);
+            json(res, 200, {
+                ok: true, result: "verified",
+                verification_id: result.verification_id, expires_at: result.expires_at,
+                binding: result.binding, probe: result.probe,
+            }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    const bindingApplyMatch = path.match(/^\/api\/settings\/connections\/([^/]+)\/binding\/apply$/);
+    if (method === "POST" && bindingApplyMatch) {
+        if (!ctx.startConnectionBindingApply) {
+            json(res, 501, { error: "connection binding apply unavailable" });
+            return true;
+        }
+        const connectionId = decodeURIComponent(bindingApplyMatch[1]);
+        readBody(req, 16 * 1024).then(buf => {
+            let body;
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch {
+                return json(res, 400, { error: "invalid JSON" });
+            }
+            const verificationId = typeof body.verification_id === "string" ? body.verification_id : "";
+            const key = typeof req.headers["idempotency-key"] === "string"
+                ? req.headers["idempotency-key"] : typeof body.idempotency_key === "string" ? body.idempotency_key : "";
+            if (!verificationId)
+                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.startConnectionBindingApply({
+                connectionId, verificationId, sessionBinding: requestSessionBinding(req), idempotencyKey: key,
+            });
+            if ("error" in result)
+                return json(res, 422, { ok: false, error: "binding apply rejected" }, true);
+            if ("busy" in result)
+                return json(res, 409, { ok: false, result: "applying", job_id: result.busy?.id ?? null }, true);
+            json(res, result.reused ? 200 : 202, { ok: true, result: result.job.result, job_id: result.job.id, reused: result.reused }, true);
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    const bindingApplyStatusMatch = path.match(/^\/api\/settings\/connections\/[^/]+\/binding\/apply\/([A-Za-z0-9_-]+)$/);
+    if (method === "GET" && bindingApplyStatusMatch) {
+        if (!ctx.getConnectionBindingApply) {
+            json(res, 501, { error: "connection binding apply unavailable" });
+            return true;
+        }
+        const job = ctx.getConnectionBindingApply(bindingApplyStatusMatch[1], requestSessionBinding(req));
+        if (!job) {
+            json(res, 404, { error: "job not found" }, true);
+            return true;
+        }
+        json(res, 200, job, true);
+        return true;
+    }
     // Everything below mutates — needs an in-memory fleet config.
     const cfg = ctx.fleetConfig;
     // ── Manual pause / wake ──
@@ -187,13 +547,68 @@ export function handleSettingsRequest(req, res, url, ctx) {
             }
             if (!Array.isArray(body))
                 return json(res, 400, { error: "expected an array of channels" });
-            const next = { ...cfg, channels: body };
+            const normalizedBody = [];
+            // Rebinding an existing provider connection is security-sensitive: a
+            // broad channel replace must not bypass the positive provider probe and
+            // ready-adapter fence exposed by /connections/:id/binding/*.
+            const currentChannels = cfg.channels ?? (cfg.channel ? [cfg.channel] : []);
+            const currentById = new Map(currentChannels.map((channel, index) => [channel.id ?? channel.type ?? `channel-${index}`, channel]));
+            const currentTokenEnvs = new Set(currentChannels.map(channel => channel.bot_token_env).filter(Boolean));
+            for (const [index, raw] of body.entries()) {
+                if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                    normalizedBody.push(raw);
+                    continue;
+                }
+                const candidate = { ...raw };
+                const group = normalizeChannelIdValue(candidate.group_id, `channels[${index}].group_id`);
+                if (!group.ok)
+                    return json(res, 400, { ok: false, error: group.error }, true);
+                if (group.value !== undefined)
+                    candidate.group_id = group.value;
+                if (candidate.options && typeof candidate.options === "object" && !Array.isArray(candidate.options)) {
+                    const options = { ...candidate.options };
+                    const general = normalizeChannelIdValue(options.general_channel_id, `channels[${index}].options.general_channel_id`);
+                    if (!general.ok)
+                        return json(res, 400, { ok: false, error: general.error }, true);
+                    if (general.value !== undefined)
+                        options.general_channel_id = general.value;
+                    candidate.options = options;
+                }
+                normalizedBody.push(candidate);
+                const id = typeof candidate.id === "string" ? candidate.id
+                    : typeof candidate.type === "string" ? candidate.type : `channel-${index}`;
+                const previous = currentById.get(id);
+                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);
+                }
+                const reusedByAnotherChannel = tokenEnv !== null && currentChannels.some((channel, channelIndex) => {
+                    const ownerId = channel.id ?? channel.type ?? `channel-${channelIndex}`;
+                    return ownerId !== id && channel.bot_token_env === tokenEnv;
+                });
+                if ((!previous && tokenEnv !== null && currentTokenEnvs.has(tokenEnv))
+                    || (previous && tokenEnv !== previous.bot_token_env && reusedByAnotherChannel)) {
+                    return json(res, 409, { ok: false, error: "new connections reusing an existing bot token require verified rebind" }, true);
+                }
+                if (!previous)
+                    continue;
+                const oldGeneral = previous.options?.general_channel_id == null ? null : String(previous.options.general_channel_id);
+                const nextOptions = candidate.options && typeof candidate.options === "object" && !Array.isArray(candidate.options)
+                    ? candidate.options : {};
+                const nextGeneral = nextOptions.general_channel_id == null ? null : String(nextOptions.general_channel_id);
+                const oldGroup = previous.group_id == null ? null : String(previous.group_id);
+                const nextGroup = candidate.group_id == null ? null : String(candidate.group_id);
+                if (oldGroup !== nextGroup || oldGeneral !== nextGeneral) {
+                    return json(res, 409, { ok: false, error: "connection binding changes require verified rebind" }, true);
+                }
+            }
+            const next = { ...cfg, channels: normalizedBody };
             delete next.channel; // channels[] supersedes the legacy single channel
             const before = validateFleetConfig(cfg);
             const after = validateFleetConfig(next);
             if (rejectIfWorse(res, before, after))
                 return;
-            cfg.channels = body;
+            cfg.channels = normalizedBody;
             delete cfg.channel;
             ctx.saveFleetConfig();
             json(res, 200, { ok: true, warnings: saveWarnings(before, after) });
@@ -362,7 +777,7 @@ export function handleSettingsRequest(req, res, url, ctx) {
             }
             ctx.logger.info({ key, instanceName }, "settings: updated classic channel");
             const hotOnly = Object.keys(body).length > 0
-                && Object.keys(body).every(field => field === "tool_progress" || field === "reply_completion_guard");
+                && Object.keys(body).every(field => CLASSIC_HOT_CONFIG_KEYS.has(field));
             json(res, 200, {
                 ok: true,
                 warnings: saveWarnings(before, after),
@@ -372,7 +787,117 @@ export function handleSettingsRequest(req, res, url, ctx) {
         }).catch(() => json(res, 400, { error: "bad request" }));
         return true;
     }
+    // ── Apply (observable) ──
+    //
+    // Replaces the fire-and-forget SIGHUP below for anything that wants to watch:
+    // the answer is a job, and the job is the authority. `apply_progress` SSE
+    // frames are an accelerator carrying no event id, so a client that reconnects
+    // cannot replay what it missed — it re-reads the job.
+    if (method === "POST" && path === "/api/settings/apply") {
+        if (!ctx.startSettingsApply) {
+            json(res, 501, { error: "apply jobs unavailable" });
+            return true;
+        }
+        readBody(req, 64 * 1024).then(buf => {
+            let body = {};
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch { /* key may come from the header */ }
+            // The client generates the key before its first attempt. A server-minted
+            // id cannot deduplicate a retry whose first response was lost.
+            const header = req.headers["idempotency-key"];
+            const key = (typeof header === "string" ? header : undefined)
+                ?? (typeof body.idempotency_key === "string" ? body.idempotency_key : undefined);
+            if (!key || !/^[A-Za-z0-9_.:-]{8,128}$/.test(key)) {
+                json(res, 400, { error: "Idempotency-Key required (8-128 chars of [A-Za-z0-9_.:-])" });
+                return;
+            }
+            const result = ctx.startSettingsApply(key);
+            if ("busy" in result) {
+                // One reconcile at a time: two of them stop and start the same agent in
+                // parallel. The running job's id lets the client watch that one instead.
+                ctx.logger.info({ runningJobId: result.busy?.id ?? null }, "settings: apply refused — a reconcile is already running");
+                json(res, 409, {
+                    error: "a configuration reload is already running",
+                    running_job_id: result.busy?.id ?? null,
+                });
+                return;
+            }
+            ctx.logger.info({ jobId: result.job.id, reused: result.reused }, result.reused
+                ? "settings: apply retry rejoined the existing job"
+                : "settings: apply job started");
+            json(res, result.reused ? 200 : 202, viewOf(result.job));
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    // ── Setup wizard ──
+    // Served by the same handlers the pre-fleet setup host serves, so the wizard
+    // asks the same questions whether or not a fleet is running yet.
+    if (handleQuickstartRequest(req, res, url, ctx))
+        return true;
+    // ── Restart AgEnD itself ──
+    //
+    // Deliberately not part of Apply. The panel is reachable from outside the
+    // LAN, so restarting the whole fleet is its own action with its own
+    // confirmation, its own idempotency key, and its own rate limit.
+    if (method === "POST" && path === "/api/settings/restart-fleet") {
+        if (!ctx.requestSettingsSelfRestart) {
+            json(res, 501, { error: "self restart unavailable" });
+            return true;
+        }
+        readBody(req, 64 * 1024).then(async (buf) => {
+            let body = {};
+            try {
+                body = JSON.parse(buf.toString("utf-8") || "{}");
+            }
+            catch { /* reported below */ }
+            const header = req.headers["idempotency-key"];
+            const key = (typeof header === "string" ? header : undefined)
+                ?? (typeof body.idempotency_key === "string" ? body.idempotency_key : undefined);
+            if (!key || !/^[A-Za-z0-9_.:-]{8,128}$/.test(key)) {
+                json(res, 400, { error: "Idempotency-Key required (8-128 chars of [A-Za-z0-9_.:-])" });
+                return;
+            }
+            // A literal, not a boolean: a stray `true` in a replayed body should not
+            // be able to mean "yes, restart the fleet".
+            if (body.confirm !== "restart-agend") {
+                json(res, 400, { error: 'confirm must be the literal "restart-agend"' });
+                return;
+            }
+            const jobId = typeof body.job_id === "string" ? body.job_id : "";
+            if (!jobId) {
+                json(res, 400, { error: "job_id required" });
+                return;
+            }
+            const result = await ctx.requestSettingsSelfRestart(jobId, key);
+            if (result.ok) {
+                ctx.logger.info({ jobId: result.jobId, reused: !!result.reused }, "settings: self restart accepted");
+                json(res, result.reused ? 200 : 202, { job_id: result.jobId, restarting: true });
+                return;
+            }
+            ctx.logger.warn({ jobId, status: result.status, reason: result.error }, "settings: self restart refused");
+            if (result.retryAfterSeconds)
+                res.setHeader("Retry-After", String(result.retryAfterSeconds));
+            json(res, result.status, {
+                error: result.error,
+                ...(result.retryAfterSeconds ? { retry_after_seconds: result.retryAfterSeconds } : {}),
+            });
+        }).catch(() => json(res, 400, { error: "bad request" }));
+        return true;
+    }
+    const jobMatch = path.match(/^\/api\/settings\/apply\/([A-Za-z0-9-]+)$/);
+    if (method === "GET" && jobMatch) {
+        const job = ctx.applyJobs?.get(jobMatch[1]) ?? null;
+        if (!job) {
+            json(res, 404, { error: "job not found" });
+            return true;
+        }
+        json(res, 200, viewOf(job));
+        return true;
+    }
     // ── Reload (SIGHUP) ──
+    // The unobserved path, kept for scripts. Nothing reports what it did.
     if (method === "POST" && path === "/api/settings/reload") {
         ctx.logger.info("settings: reload requested — sending SIGHUP");
         try {