patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/dist/server.js

@@ -1,12 +1,19 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { EventEmitter } from "node:events";
+import { unlinkSync } from "node:fs";
 import http from "node:http";
 import { WebSocket, WebSocketServer as WsServer } from "ws";
+import { clearAnalyticsConfig, getAnalyticsConfig } from "./analyticsConfig.js";
+import { getAnalyticsPrefsAll, getAnalyticsPrefsPath, getAnalyticsSaltPath, getTelemetryPrefs, setTelemetryPrefs, } from "./analyticsPrefs.js";
 import { handleApprovalsStream, routeApprovalRequest } from "./approvalHttp.js";
 import { getApprovalQueue } from "./approvalQueue.js";
 import { saveBridgeConfigDriver } from "./config.js";
 import { tryHandleConnectorRoute, tryHandlePublicConnectorRoute, } from "./connectorRoutes.js";
 import { timingSafeStringEqual } from "./crypto.js";
 import { renderDashboardHtml } from "./dashboard.js";
+import { isLoopbackOrPrivateEndpoint } from "./drivers/local/index.js";
+import { EnvLockedFlagError, getEnvLockedValue, isEnabled, isEnvLockedFor, isWriteKillSwitchActive, KILL_SWITCH_WRITES, listFlags, setFlag, } from "./featureFlags.js";
+import { respondIfUnknownBodyKeys } from "./httpBodyValidation.js";
 import { respond500 } from "./httpErrorResponse.js";
 import { tryHandleInboxRoute } from "./inboxRoutes.js";
 import { tryHandleMcpRoute } from "./mcpRoutes.js";
@@ -49,6 +56,7 @@ export class Server extends EventEmitter {
     logger;
     extraCorsOrigins;
     pingIntervalMs;
+    trustedProxies;
     httpServer;
     wss;
     pingInterval = null;
@@ -59,9 +67,25 @@ export class Server extends EventEmitter {
     oauthServer = null;
     oauthIssuerUrl = null;
     sseSubscriberCount = 0;
+    /**
+     * Registered SSE subscribers on `/stream`, oldest-first by insertion
+     * order. Used as a defense-in-depth backstop: if a subscriber's peer is
+     * a dead-but-not-erroring socket (e.g. an orphaned proxy connection),
+     * the ping-write cleanup can fail to fire and the subscriber leaks. To
+     * guarantee a leak can never *permanently* brick `/stream`, a new
+     * request arriving at the cap evicts the oldest subscriber instead of
+     * returning 503 — mirroring the HTTP-session eviction in ADR-0005.
+     * The real cure for the known leak is the dashboard proxy aborting its
+     * upstream fetch on client disconnect; this is the backstop.
+     */
+    sseSubscribers = new Set();
     /** Cache for CC permission rules (30s TTL) to avoid filesystem walks on each dashboard poll */
     _explainRulesCache = null;
     static MAX_SSE_SUBSCRIBERS = 20;
+    /** Number of currently-registered `/stream` SSE subscribers. Read-only. */
+    get sseSubscribers_count() {
+        return this.sseSubscriberCount;
+    }
     /** Set by bridge to provide health data */
     healthDataFn = null;
     /** Set by bridge to provide Prometheus metrics */
@@ -80,6 +104,15 @@ export class Server extends EventEmitter {
     setRecipeTrustFn = null;
     /** Patchwork: set by bridge to generate a recipe YAML draft from a natural-language prompt. */
     generateRecipeFn = null;
+    /**
+     * Patchwork Phase 2A: repair a broken recipe YAML given the current
+     * content + structured LintIssue[] context. Driven by the same
+     * Claude-orchestrator infrastructure as `generateRecipeFn` (system
+     * prompt + sanitized user-tag wrapper + post-lint), but the user
+     * input is the user's CURRENT recipe rather than free-text — gated
+     * behind the `recipe.repair-ai` feature flag.
+     */
+    repairRecipeFn = null;
     /** Patchwork: set by bridge to list installed recipes for the dashboard. */
     recipesFn = null;
     /** Patchwork: set by bridge to load raw recipe source content by name. */
@@ -102,6 +135,10 @@ export class Server extends EventEmitter {
     runsFn = null;
     /** Patchwork: set by bridge to fetch a single run by seq for the detail page. */
     runDetailFn = null;
+    /** Patchwork (PR1c): aggregate halt-reason categories across recent runs. */
+    haltSummaryFn = null;
+    /** Patchwork (PR3b): aggregate judge-step verdicts across recent runs. */
+    judgeSummaryFn = null;
     /** Patchwork: set by bridge to generate a dry-run plan for a recipe by name. */
     runPlanFn = null;
     /** Patchwork (VD-4): mocked replay of an existing run. Returns the new
@@ -109,10 +146,25 @@ export class Server extends EventEmitter {
     runReplayFn = null;
     /** Patchwork: set by bridge to launch a named recipe via the orchestrator. */
     runRecipeFn = null;
+    /**
+     * Patchwork: set by bridge to re-prime the recipe scheduler when the
+     * on-disk recipe set changes (install / save / delete). Lets cron-
+     * triggered recipes start firing without a bridge restart. Optional —
+     * tests + headless tooling leave it null; the install handler treats
+     * the callback as best-effort fire-and-forget.
+     */
+    onRecipesChangedFn = null;
     /** Patchwork: admin-controlled managed settings path (highest rule precedence). */
     managedSettingsPath = undefined;
     /** Effective bridge config path to update when dashboard saves driver changes. */
     bridgeConfigPath = undefined;
+    /**
+     * Shared secret for HMAC-SHA256 verification of POST /hooks/* requests
+     * carrying `X-Hub-Signature-256`. When null (default), HMAC auth is
+     * disabled and /hooks/* requires the bridge bearer token like every
+     * other route. Set by Bridge constructor from `config.webhookSecret`.
+     */
+    webhookSecret = null;
     /** Patchwork: live approval gate level — mutated by POST /settings, read by bridge per-session setup. */
     approvalGate = "off";
     /** Patchwork: outbound webhook URL for approval notifications (from dashboard.webhookUrl in config). */
@@ -123,6 +175,10 @@ export class Server extends EventEmitter {
     pushServiceToken = undefined;
     /** Patchwork: public base URL of this bridge, embedded in push payloads as callback base. */
     pushServiceBaseUrl = undefined;
+    /** Patchwork: ntfy.sh topic for direct phone-path approvals via action buttons. */
+    ntfyTopic = undefined;
+    /** Patchwork: ntfy server (default https://ntfy.sh; override for self-hosted). */
+    ntfyServer = undefined;
     /** Patchwork: approval decision audit callback wired to activityLog.recordEvent. */
     onApprovalDecision = undefined;
     /**
@@ -145,6 +201,33 @@ export class Server extends EventEmitter {
      * the user's preference.
      */
     enableTimeOfDayAnomaly = false;
+    /**
+     * Patchwork: set by bridge to record a kill-switch audit trace.
+     * `/kill-switch` POST emits one entry on every state transition (no-op
+     * toggles do not emit). When unset, the handler logs via this.logger
+     * instead — see step 5 of issue #422.
+     *
+     * Trace encoding (v2-I6 from #422): we encode kill-switch events via
+     * the existing `DecisionTrace` schema rather than extending its
+     * `traceType` union, to keep schema migration off the kill-switch
+     * critical path. Fields used:
+     *   ref       = "kill-switch.writes"
+     *   problem   = "<short reason>" or "engage" / "release" if no reason
+     *   solution  = "ENGAGED at <ts>" or "RELEASED at <ts>"
+     *   tags      = ["kill-switch", "engage" | "release", "actor:http"]
+     *
+     * `ctxQueryTraces({tag: "kill-switch"})` returns the full audit
+     * history; pair with `tag: "engage"` / `tag: "release"` to filter
+     * direction.
+     */
+    recordKillSwitchTraceFn = null;
+    /**
+     * Set by bridge to broadcast a `kind: "kill-switch"` SSE event from
+     * `/stream` when the kill-switch state changes (issue #422 v2, pitfall I8).
+     * Bridge wires this to `activityLog.broadcastKillSwitch()` or an equivalent
+     * that notifies all active SSE listeners so the dashboard updates in <1s.
+     */
+    broadcastKillSwitchEventFn = null;
     /** Patchwork: set by bridge to match + fire webhook-triggered recipes. */
     webhookFn = null;
     /**
@@ -157,6 +240,36 @@ export class Server extends EventEmitter {
      */
     webhookPayloads = new Map();
     static MAX_WEBHOOK_PAYLOADS = 5;
+    /**
+     * Per-list FIFO bounds the per-recipe payload count, but the Map itself
+     * needs a key cap so a recipe-rename loop or a scanner hitting many
+     * distinct legitimate hookPaths can't grow `webhookPayloads.size`
+     * without bound. 1000 is generous for any realistic operator deployment
+     * (5 payloads × 1000 recipes = ~5000 entries × ~10 KB each = 50 MB).
+     * On overflow, evict the oldest *recipe* (Map iteration order is
+     * insertion order in JS), not the largest list.
+     */
+    static MAX_WEBHOOK_RECIPES = 1000;
+    /**
+     * Per-IP rate limit on the unauthenticated phone-path approval endpoints
+     * (`POST /approve/:callId` and `POST /reject/:callId` when
+     * `x-approval-token` is present). The auth gate intentionally bypasses
+     * bearer auth for those paths so a phone can dispatch without a bridge
+     * token; without rate limiting, an attacker who learns a callId (via
+     * webhook target leak, bearer-authed `/approvals` reader, etc.) can
+     * spray garbage tokens to DoS the legitimate approver. PR #380 bumped
+     * the per-callId failure cap to 1000 (memory bound, not security
+     * bound); this is the HTTP-layer spray defense flagged as the proper
+     * fix in that commit.
+     *
+     * 60 attempts per IP per minute is generous for legitimate retries
+     * (phone re-tap, network flake) and tight enough to bound brute-force
+     * attempts during the 5-minute approval TTL to 300 — well within the
+     * per-callId cap, so no legit retry budget is consumed by sprayers.
+     */
+    approvalIpCounts = new Map();
+    static APPROVAL_IP_MAX = 60;
+    static APPROVAL_IP_WINDOW_MS = 60_000;
     /** Set by bridge to handle MCP Streamable HTTP sessions (POST/GET/DELETE /mcp) */
     httpMcpHandler = null;
     /** Set by bridge to subscribe a caller to real-time activity events. Returns unsubscribe fn. */
@@ -180,6 +293,22 @@ export class Server extends EventEmitter {
     /** Set by bridge to handle POST /launch-quick-task — invokes launchQuickTask tool in-process. */
     launchQuickTaskFn = null;
     setRecipeEnabledFn = null;
+    /** Set by bridge to check if restart is safe (no in-flight tool calls). */
+    restartCheckFn = null;
+    /**
+     * Called when /restart decides it is safe to shut down. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Override in tests to a no-op so
+     * the Vitest runner process is not actually killed.
+     */
+    restartKillFn = () => process.kill(process.pid, "SIGTERM");
+    /**
+     * Called when /shutdown decides it is safe to exit. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Bridge overrides this to run its
+     * internal shutdown sequence directly — necessary on Windows where
+     * `process.kill(pid, 'SIGTERM')` is TerminateProcess and cleanup handlers
+     * never fire.
+     */
+    shutdownFn = () => process.kill(process.pid, "SIGTERM");
     /**
      * Attach an OAuth 2.0 Authorization Server.
      * When set, the bridge exposes:
@@ -196,12 +325,19 @@ export class Server extends EventEmitter {
     }
     /** Hosts accepted in the WebSocket upgrade Host header (DNS-rebinding guard). */
     allowedHosts;
-    constructor(authToken, logger, extraCorsOrigins = [], pingIntervalMs = 30_000) {
+    constructor(authToken, logger, extraCorsOrigins = [], pingIntervalMs = 30_000, 
+    // Reverse-proxy hops whose X-Forwarded-For values we trust. Empty by
+    // default — the per-IP rate limiter buckets on the direct socket peer.
+    // Behind nginx/Caddy/Cloudflare set this to the proxy's IP so distinct
+    // real clients get distinct buckets; otherwise every request looks
+    // like 127.0.0.1 and a single sprayer DoSes the legit approver.
+    trustedProxies = []) {
         super();
         this.authToken = authToken;
         this.logger = logger;
         this.extraCorsOrigins = extraCorsOrigins;
         this.pingIntervalMs = pingIntervalMs;
+        this.trustedProxies = trustedProxies;
         // Defense-in-depth: ensure token is non-empty so timingSafeTokenCompare
         // cannot accept a blank Authorization header against an empty token.
         if (authToken.length === 0) {
@@ -371,13 +507,69 @@ export class Server extends EventEmitter {
             const oauthResolved = !isStaticToken && this.oauthServer
                 ? this.oauthServer.resolveBearerToken(bearer)
                 : null;
-            // Phone-path: approve/reject with x-approval-token bypass bearer check.
+            // Phone-path: approve/reject with x-approval-token header or ?token= query param bypass bearer check.
             // The token itself is validated inside routeApprovalRequest via queue.validateToken.
             const isPhoneApprovalPath = req.method === "POST" &&
                 /^\/(approve|reject)\/[A-Za-z0-9-]+$/.test(parsedUrl.pathname) &&
-                !!req.headers["x-approval-token"];
+                !!(req.headers["x-approval-token"] || parsedUrl.searchParams.get("token"));
+            // GitHub-style webhook bypass: when --webhook-secret is configured,
+            // POST /hooks/* requests carrying X-Hub-Signature-256 bypass the
+            // bearer-token gate. Signature itself is verified inside the
+            // /hooks/* handler after the body has been read.
+            const isHmacWebhookCandidate = req.method === "POST" &&
+                parsedUrl.pathname.startsWith("/hooks/") &&
+                !!req.headers["x-hub-signature-256"] &&
+                this.webhookSecret !== null;
+            // Rate-limit the phone bypass surface. Only applies when this is
+            // actually a phone-path request that's relying on the bypass — a
+            // properly-authenticated bearer caller is unaffected. Counted +
+            // checked *before* dispatch so a sprayer can't burn the per-callId
+            // failure budget at line-rate.
+            if (isPhoneApprovalPath && !isStaticToken && !oauthResolved) {
+                const remoteIp = this.getClientIp(req);
+                if (!remoteIp) {
+                    // Fail closed — without an attributable IP we cannot bucket
+                    // safely, and the original "unknown" string was a single shared
+                    // counter every IP-less request rolled up into.
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "bad_request",
+                        error_description: "could not determine client IP",
+                    }));
+                    return;
+                }
+                const now = Date.now();
+                const entry = this.approvalIpCounts.get(remoteIp);
+                if (entry && now - entry.windowStart < Server.APPROVAL_IP_WINDOW_MS) {
+                    entry.count++;
+                    if (entry.count > Server.APPROVAL_IP_MAX) {
+                        res.writeHead(429, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "too_many_requests",
+                            error_description: "per-IP approval endpoint rate limit reached",
+                        }));
+                        return;
+                    }
+                }
+                else {
+                    this.approvalIpCounts.set(remoteIp, { count: 1, windowStart: now });
+                }
+                // GC stale entries opportunistically — bounded growth alongside
+                // the same Map. 200 is well above any legitimate concurrent IP
+                // count; well below memory pressure.
+                if (this.approvalIpCounts.size > 200) {
+                    for (const [k, v] of this.approvalIpCounts) {
+                        if (now - v.windowStart > Server.APPROVAL_IP_WINDOW_MS) {
+                            this.approvalIpCounts.delete(k);
+                        }
+                    }
+                }
+            }
             // oauthResolved is the bridge token if the OAuth token is valid; null otherwise
-            if (!isStaticToken && !oauthResolved && !isPhoneApprovalPath) {
+            if (!isStaticToken &&
+                !oauthResolved &&
+                !isPhoneApprovalPath &&
+                !isHmacWebhookCandidate) {
                 // RFC 6750: only include error= when a token was actually presented but invalid
                 const tokenPresented = bearer.length > 0;
                 const wwwAuth = this.oauthServer && this.oauthIssuerUrl
@@ -607,10 +799,18 @@ export class Server extends EventEmitter {
                 return;
             }
             if (req.url === "/stream" && req.method === "GET") {
+                // Backstop (ADR-0005 pattern): at the cap, evict the oldest
+                // subscriber rather than returning 503 forever. A leaked
+                // subscriber whose socket is dead-but-not-erroring can otherwise
+                // permanently brick /stream. The dashboard proxy abort-on-disconnect
+                // fix is the real cure; this guarantees recovery either way.
+                // sseSubscriberCount and sseSubscribers.size stay in lockstep
+                // (both mutated together below + in cleanup()), so when the
+                // counter is at the cap there is always an evictable subscriber —
+                // eviction always frees the slot.
                 if (this.sseSubscriberCount >= Server.MAX_SSE_SUBSCRIBERS) {
-                    res.writeHead(503, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Too many SSE subscribers (max 20)" }));
-                    return;
+                    const oldest = this.sseSubscribers.values().next().value;
+                    oldest?.();
                 }
                 this.sseSubscriberCount++;
                 // Disable socket timeout — SSE connections are long-lived by design
@@ -621,31 +821,58 @@ export class Server extends EventEmitter {
                     Connection: "keep-alive",
                 });
                 res.flushHeaders();
-                const unsub = this.streamFn?.((kind, entry) => {
-                    try {
-                        res.write(`data: ${JSON.stringify({ kind, ...entry })}\n\n`);
-                    }
-                    catch {
-                        // Client disconnected — unsubscribe on next tick
-                        unsub?.();
-                    }
-                }) ?? (() => { });
+                // Idempotent teardown — every disconnect path (write error,
+                // ping error, req.close) funnels through here. Without this the
+                // counter could be decremented twice for a single subscriber
+                // (req.close fires AFTER write error in some Node versions) or
+                // not at all (write error never escalates to req.close on
+                // certain proxy intermediaries). Audit 2026-05-17 (#605
+                // BLOCKER): observed in production — subscribers hit cap of 20
+                // after enough page reloads, every new SSE returns 503 and
+                // kill-switch / activity ticker silently die.
+                let cleanedUp = false;
+                let pingHandle = null;
+                let unsub = () => { };
+                // Single teardown closure, also stored directly in the registry
+                // as this subscriber's eviction handler — it tears down state AND
+                // destroys the socket so the peer (and any orphaned proxy in
+                // between) observes the close. It removes this exact function
+                // from the Set, so no placeholder/no-op function is ever created.
+                const cleanup = () => {
+                    if (cleanedUp)
+                        return;
+                    cleanedUp = true;
+                    this.sseSubscriberCount--;
+                    this.sseSubscribers.delete(cleanup);
+                    if (pingHandle)
+                        clearInterval(pingHandle);
+                    unsub();
+                    res.end();
+                    res.socket?.destroy();
+                };
+                this.sseSubscribers.add(cleanup);
+                unsub =
+                    this.streamFn?.((kind, entry) => {
+                        try {
+                            res.write(`data: ${JSON.stringify({ kind, ...entry })}\n\n`);
+                        }
+                        catch {
+                            cleanup();
+                        }
+                    }) ?? (() => { });
                 // Keep-alive comment ping every 15s so proxies don't close idle connections
-                const ping = setInterval(() => {
+                pingHandle = setInterval(() => {
                     try {
                         res.write(": ping\n\n");
                     }
                     catch {
-                        clearInterval(ping);
-                        unsub();
+                        cleanup();
                     }
                 }, 15_000);
-                ping.unref();
-                req.on("close", () => {
-                    this.sseSubscriberCount--;
-                    clearInterval(ping);
-                    unsub();
-                });
+                pingHandle.unref();
+                req.on("close", cleanup);
+                req.on("error", cleanup);
+                res.on("error", cleanup);
                 return;
             }
             if (req.url === "/tasks" && req.method === "GET") {
@@ -689,6 +916,33 @@ export class Server extends EventEmitter {
                     respond413(res, HOOKS_BODY_CAP);
                     return;
                 }
+                // HMAC-SHA256 verification for GitHub-style webhooks. Signature is
+                // computed over the raw on-the-wire bytes (read.bytes), not the
+                // utf-8-decoded string — non-UTF-8 or denormalized payloads must
+                // round-trip identically to validate.
+                const sigHeader = req.headers["x-hub-signature-256"];
+                if (typeof sigHeader === "string" && sigHeader.length > 0) {
+                    if (!this.webhookSecret) {
+                        res.writeHead(401, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "webhook_secret_not_configured" }));
+                        return;
+                    }
+                    const expected = "sha256=" +
+                        createHmac("sha256", this.webhookSecret)
+                            .update(read.bytes)
+                            .digest("hex");
+                    const expectedBuf = Buffer.from(expected, "utf-8");
+                    const providedBuf = Buffer.from(sigHeader, "utf-8");
+                    // timingSafeEqual throws on length mismatch — length-check first
+                    // so the constant-time path is only taken on equal-length inputs.
+                    const sigOk = expectedBuf.length === providedBuf.length &&
+                        timingSafeEqual(expectedBuf, providedBuf);
+                    if (!sigOk) {
+                        res.writeHead(401, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_signature" }));
+                        return;
+                    }
+                }
                 let payload;
                 if (read.body.trim()) {
                     try {
@@ -702,7 +956,7 @@ export class Server extends EventEmitter {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Webhooks unavailable — start bridge with --claude-driver subprocess",
+                        error: "Webhooks unavailable — start bridge with --driver subprocess",
                     }));
                     return;
                 }
@@ -728,6 +982,19 @@ export class Server extends EventEmitter {
                     if (existing.length > Server.MAX_WEBHOOK_PAYLOADS) {
                         existing.length = Server.MAX_WEBHOOK_PAYLOADS;
                     }
+                    // LRU eviction: Map.set() on an existing key keeps original
+                    // insertion-order position (per spec), so a hot recipe registered
+                    // at startup would otherwise be evicted in favor of a cold
+                    // scanner-spam recipe just because it was registered earlier.
+                    // Delete + re-set re-anchors the key to the END of insertion
+                    // order, making `.keys().next()` correctly point at the
+                    // least-recently-fired recipe.
+                    this.webhookPayloads.delete(hookPath);
+                    if (this.webhookPayloads.size >= Server.MAX_WEBHOOK_RECIPES) {
+                        const oldest = this.webhookPayloads.keys().next().value;
+                        if (oldest !== undefined)
+                            this.webhookPayloads.delete(oldest);
+                    }
                     this.webhookPayloads.set(hookPath, existing);
                 }
                 res.writeHead(status, { "Content-Type": "application/json" });
@@ -880,6 +1147,7 @@ export class Server extends EventEmitter {
             if (tryHandleRecipeRoute(req, res, parsedUrl, {
                 setRecipeTrustFn: this.setRecipeTrustFn,
                 generateRecipeFn: this.generateRecipeFn,
+                repairRecipeFn: this.repairRecipeFn,
                 recipesFn: this.recipesFn,
                 loadRecipeContentFn: this.loadRecipeContentFn,
                 saveRecipeContentFn: this.saveRecipeContentFn,
@@ -892,9 +1160,12 @@ export class Server extends EventEmitter {
                 setRecipeEnabledFn: this.setRecipeEnabledFn,
                 runsFn: this.runsFn,
                 runDetailFn: this.runDetailFn,
+                haltSummaryFn: this.haltSummaryFn,
+                judgeSummaryFn: this.judgeSummaryFn,
                 runPlanFn: this.runPlanFn,
                 runReplayFn: this.runReplayFn,
                 runRecipeFn: this.runRecipeFn,
+                onRecipesChangedFn: this.onRecipesChangedFn,
             })) {
                 return;
             }
@@ -933,6 +1204,21 @@ export class Server extends EventEmitter {
                 return;
             }
             if (parsedUrl.pathname === "/settings" && req.method === "POST") {
+                // Kill-switch gate: during an incident a settings mutation can
+                // defeat the panic posture (e.g. switching driver to one with a
+                // leaked API key, flipping approvalGate to "off"). The /settings
+                // card on the dashboard sits directly above the kill-switch
+                // toggle — users will reasonably read "writes blocked" as
+                // covering both. Refuse with 423 Locked; the /kill-switch
+                // endpoint itself is the only way out and is not gated.
+                if (isWriteKillSwitchActive()) {
+                    res.writeHead(423, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "kill_switch_blocked",
+                        reason: "Settings writes are disabled while the write kill-switch is engaged. Release it via POST /kill-switch to mutate config.",
+                    }));
+                    return;
+                }
                 // 16 KB — settings POSTs are short-string fields (URLs, API keys,
                 // gate level). 16 KB is generous; an authenticated attacker can't
                 // stream gigabytes here.
@@ -950,55 +1236,59 @@ export class Server extends EventEmitter {
                 try {
                     {
                         const body = parsed.value ?? {};
+                        if (respondIfUnknownBodyKeys(res, body, [
+                            "webhookUrl",
+                            "approvalGate",
+                            "enableTimeOfDayAnomaly",
+                            "driver",
+                            "model",
+                            "localEndpoint",
+                            "localModel",
+                            "apiKey",
+                            "pushServiceUrl",
+                            "pushServiceToken",
+                            "pushServiceBaseUrl",
+                            "ntfyTopic",
+                            "ntfyServer",
+                        ])) {
+                            return;
+                        }
+                        // PHASE 1 — validate ALL fields up front. No disk writes, no
+                        // secure-store writes, no live-state mutations until every input
+                        // has passed. Prevents the "valid driver + invalid ntfyTopic"
+                        // class of bug where a 400 still leaves a partial side-effect on
+                        // disk.
+                        const respond400 = (error) => {
+                            res.writeHead(400, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({ error }));
+                        };
+                        // webhookUrl
                         const hasWebhookUpdate = body.webhookUrl !== undefined;
-                        const raw = hasWebhookUpdate
+                        const webhookRaw = hasWebhookUpdate
                             ? (body.webhookUrl?.trim() ?? "")
                             : undefined;
-                        if (raw !== undefined && raw !== "" && !/^https:\/\/.+/.test(raw)) {
-                            res.writeHead(400, { "Content-Type": "application/json" });
-                            res.end(JSON.stringify({ error: "webhookUrl must be HTTPS" }));
+                        if (webhookRaw !== undefined &&
+                            webhookRaw !== "" &&
+                            !/^https:\/\/.+/.test(webhookRaw)) {
+                            respond400("webhookUrl must be HTTPS");
                             return;
                         }
+                        // approvalGate
                         const gateRaw = body.approvalGate;
                         if (gateRaw !== undefined &&
                             gateRaw !== "off" &&
                             gateRaw !== "high" &&
                             gateRaw !== "all") {
-                            res.writeHead(400, { "Content-Type": "application/json" });
-                            res.end(JSON.stringify({
-                                error: 'approvalGate must be "off", "high", or "all"',
-                            }));
+                            respond400('approvalGate must be "off", "high", or "all"');
                             return;
                         }
-                        const configPath = patchworkConfigPath();
-                        const cfg = loadPatchworkConfig(configPath);
-                        cfg.dashboard = {
-                            port: cfg.dashboard?.port ?? 3200,
-                            requireApproval: cfg.dashboard?.requireApproval ?? ["high"],
-                            pushNotifications: cfg.dashboard?.pushNotifications ?? false,
-                            webhookUrl: hasWebhookUpdate
-                                ? raw || undefined
-                                : cfg.dashboard?.webhookUrl,
-                        };
-                        if (gateRaw !== undefined) {
-                            cfg.approvalGate = gateRaw;
-                            this.approvalGate = gateRaw;
-                        }
-                        // h10 toggle: must be boolean if present. Persists to
-                        // ~/.patchwork/config.json AND live-mutates the Server
-                        // field so the next /approvals POST honors it without
-                        // needing a bridge restart.
-                        if (body.enableTimeOfDayAnomaly !== undefined) {
-                            if (typeof body.enableTimeOfDayAnomaly !== "boolean") {
-                                res.writeHead(400, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({
-                                    error: "enableTimeOfDayAnomaly must be a boolean",
-                                }));
-                                return;
-                            }
-                            cfg.enableTimeOfDayAnomaly = body.enableTimeOfDayAnomaly;
-                            this.enableTimeOfDayAnomaly = body.enableTimeOfDayAnomaly;
+                        // enableTimeOfDayAnomaly
+                        if (body.enableTimeOfDayAnomaly !== undefined &&
+                            typeof body.enableTimeOfDayAnomaly !== "boolean") {
+                            respond400("enableTimeOfDayAnomaly must be a boolean");
+                            return;
                         }
+                        // driver
                         const driverRaw = body.driver;
                         if (driverRaw !== undefined) {
                             const validDrivers = [
@@ -1012,26 +1302,11 @@ export class Server extends EventEmitter {
                                 "none",
                             ];
                             if (!validDrivers.includes(driverRaw)) {
-                                res.writeHead(400, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({
-                                    error: `driver must be one of: ${validDrivers.join(", ")}`,
-                                }));
-                                return;
-                            }
-                            const driver = driverRaw;
-                            cfg.driver = driver;
-                            try {
-                                saveBridgeConfigDriver(driver, this.bridgeConfigPath);
-                            }
-                            catch (writeErr) {
-                                this.logger.error(`[/config/patchwork] saveBridgeConfigDriver failed: ${writeErr instanceof Error ? (writeErr.stack ?? writeErr.message) : String(writeErr)}`);
-                                res.writeHead(500, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({
-                                    error: "Failed to write bridge driver config",
-                                }));
+                                respond400(`driver must be one of: ${validDrivers.join(", ")}`);
                                 return;
                             }
                         }
+                        // model
                         if (body.model !== undefined) {
                             const validModels = [
                                 "claude",
@@ -1041,40 +1316,198 @@ export class Server extends EventEmitter {
                                 "local",
                             ];
                             if (!validModels.includes(body.model)) {
-                                res.writeHead(400, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({
-                                    error: `model must be one of: ${validModels.join(", ")}`,
-                                }));
+                                respond400(`model must be one of: ${validModels.join(", ")}`);
                                 return;
                             }
-                            cfg.model = body.model;
-                            if (body.model === "local") {
-                                if (body.localEndpoint !== undefined)
-                                    cfg.localEndpoint = body.localEndpoint.trim() || undefined;
-                                if (body.localModel !== undefined)
-                                    cfg.localModel = body.localModel.trim() || undefined;
-                            }
                         }
+                        // apiKey
                         if (body.apiKey) {
                             const { provider, key } = body.apiKey;
                             const validProviders = ["anthropic", "openai", "google", "xai"];
                             if (!validProviders.includes(provider) ||
                                 typeof key !== "string") {
-                                res.writeHead(400, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({ error: "Invalid apiKey provider or key" }));
+                                respond400("Invalid apiKey provider or key");
+                                return;
+                            }
+                        }
+                        // pushServiceUrl
+                        const pushUrlTrimmed = body.pushServiceUrl !== undefined
+                            ? body.pushServiceUrl.trim()
+                            : undefined;
+                        if (pushUrlTrimmed !== undefined &&
+                            pushUrlTrimmed !== "" &&
+                            !pushUrlTrimmed.startsWith("https://")) {
+                            respond400("pushServiceUrl must be HTTPS");
+                            return;
+                        }
+                        // pushServiceToken — bearer for the push relay. Charset cap to
+                        // printable ASCII (no newlines / control chars) so it can't
+                        // header-inject when later interpolated into an outgoing
+                        // `Authorization` header. 512 chars is an order of magnitude
+                        // above any realistic relay token.
+                        const pushTokenTrimmed = body.pushServiceToken !== undefined
+                            ? body.pushServiceToken.trim()
+                            : undefined;
+                        if (pushTokenTrimmed !== undefined &&
+                            pushTokenTrimmed !== "" &&
+                            !/^[\x21-\x7E]{1,512}$/.test(pushTokenTrimmed)) {
+                            respond400("pushServiceToken must be 1-512 printable ASCII characters");
+                            return;
+                        }
+                        // pushServiceBaseUrl — bridge callback origin embedded in SW
+                        // approveUrl/rejectUrl. http:// or attacker host = approval token
+                        // exfiltration. Validate before persisting.
+                        const pushBaseTrimmed = body.pushServiceBaseUrl !== undefined
+                            ? body.pushServiceBaseUrl.trim()
+                            : undefined;
+                        if (pushBaseTrimmed !== undefined &&
+                            pushBaseTrimmed !== "" &&
+                            !pushBaseTrimmed.startsWith("https://")) {
+                            respond400("pushServiceBaseUrl must be HTTPS");
+                            return;
+                        }
+                        // ntfyTopic — bearer-token on public ntfy.sh; charset-restricted.
+                        const ntfyTopicTrimmed = body.ntfyTopic !== undefined ? body.ntfyTopic.trim() : undefined;
+                        if (ntfyTopicTrimmed !== undefined &&
+                            ntfyTopicTrimmed !== "" &&
+                            !/^[A-Za-z0-9_-]{1,64}$/.test(ntfyTopicTrimmed)) {
+                            respond400("ntfyTopic must match [A-Za-z0-9_-]{1,64}");
+                            return;
+                        }
+                        // ntfyServer — same threat model as pushServiceBaseUrl.
+                        const ntfyServerTrimmed = body.ntfyServer !== undefined
+                            ? body.ntfyServer.trim()
+                            : undefined;
+                        if (ntfyServerTrimmed !== undefined &&
+                            ntfyServerTrimmed !== "" &&
+                            !ntfyServerTrimmed.startsWith("https://")) {
+                            respond400("ntfyServer must be HTTPS");
+                            return;
+                        }
+                        // localEndpoint — used by LocalApiDriver as the inference base
+                        // URL. Must parse as http(s)://, be ≤2048 chars, and resolve to
+                        // a loopback or private address. Otherwise prompts + context
+                        // would stream to a public / metadata / file:// host. Same gate
+                        // the driver enforces at construction, raised to the HTTP
+                        // boundary so the bad value never reaches disk. Operator can
+                        // opt out via LOCAL_ENDPOINT_ALLOW_REMOTE=1 for audited
+                        // internal inference clusters.
+                        const localEndpointTrimmed = body.localEndpoint !== undefined
+                            ? body.localEndpoint.trim()
+                            : undefined;
+                        if (localEndpointTrimmed !== undefined &&
+                            localEndpointTrimmed !== "") {
+                            if (localEndpointTrimmed.length > 2048) {
+                                respond400("localEndpoint must be ≤2048 characters");
                                 return;
                             }
-                            // Provider keys go to the secure store (Keychain/DPAPI/Secret
-                            // Service / AES-256-GCM file fallback) — never persisted to
-                            // ~/.patchwork/config.json. Empty string clears.
+                            let parsed;
                             try {
-                                saveApiKeyToSecureStore(provider, key);
+                                parsed = new URL(localEndpointTrimmed);
+                            }
+                            catch {
+                                respond400("localEndpoint must be a valid http(s):// URL");
+                                return;
+                            }
+                            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                                respond400("localEndpoint must use http:// or https:// scheme");
+                                return;
+                            }
+                            if (process.env.LOCAL_ENDPOINT_ALLOW_REMOTE !== "1" &&
+                                !isLoopbackOrPrivateEndpoint(localEndpointTrimmed)) {
+                                respond400("localEndpoint must be loopback or private (set LOCAL_ENDPOINT_ALLOW_REMOTE=1 to override)");
+                                return;
+                            }
+                        }
+                        // PHASE 2 — load config and apply all in-memory edits to `cfg`.
+                        // Still no disk writes; if anything throws here the request
+                        // returns 500 with no side effects.
+                        const configPath = patchworkConfigPath();
+                        const cfg = loadPatchworkConfig(configPath);
+                        cfg.dashboard = {
+                            port: cfg.dashboard?.port ?? 3200,
+                            requireApproval: cfg.dashboard?.requireApproval ?? ["high"],
+                            pushNotifications: cfg.dashboard?.pushNotifications ?? false,
+                            webhookUrl: hasWebhookUpdate
+                                ? webhookRaw || undefined
+                                : cfg.dashboard?.webhookUrl,
+                        };
+                        if (gateRaw !== undefined) {
+                            cfg.approvalGate = gateRaw;
+                        }
+                        if (body.enableTimeOfDayAnomaly !== undefined) {
+                            cfg.enableTimeOfDayAnomaly = body.enableTimeOfDayAnomaly;
+                        }
+                        if (driverRaw !== undefined) {
+                            cfg.driver = driverRaw;
+                        }
+                        if (body.model !== undefined) {
+                            cfg.model = body.model;
+                        }
+                        // localEndpoint / localModel persist regardless of whether
+                        // `model` is sent. Previously they were silently dropped when
+                        // the dashboard updated only the endpoint of an already-local
+                        // install, which left the running driver pointed at the old
+                        // host until the user happened to re-pick "Local LLM" in the
+                        // UI.
+                        if (body.localEndpoint !== undefined) {
+                            cfg.localEndpoint = body.localEndpoint.trim() || undefined;
+                        }
+                        if (body.localModel !== undefined) {
+                            cfg.localModel = body.localModel.trim() || undefined;
+                        }
+                        // Push / ntfy fields used to be set only on `this.*` and were
+                        // lost on bridge restart. Persist alongside the rest.
+                        if (pushUrlTrimmed !== undefined) {
+                            cfg.pushServiceUrl = pushUrlTrimmed || undefined;
+                        }
+                        if (pushTokenTrimmed !== undefined) {
+                            cfg.pushServiceToken = pushTokenTrimmed || undefined;
+                        }
+                        if (pushBaseTrimmed !== undefined) {
+                            cfg.pushServiceBaseUrl = pushBaseTrimmed || undefined;
+                        }
+                        if (ntfyTopicTrimmed !== undefined) {
+                            cfg.ntfyTopic = ntfyTopicTrimmed || undefined;
+                        }
+                        if (ntfyServerTrimmed !== undefined) {
+                            cfg.ntfyServer = ntfyServerTrimmed || undefined;
+                        }
+                        // PHASE 3 — disk + secure-store writes. Order: secure store →
+                        // bridge driver config → patchwork config. Each rolls back what
+                        // it can on later failure (left to PR #02; for now log + 500).
+                        if (body.apiKey) {
+                            try {
+                                saveApiKeyToSecureStore(body.apiKey.provider, body.apiKey.key);
+                            }
+                            catch (writeErr) {
+                                // Some Keychain / Secret-Service backends echo the
+                                // payload into the error message on certain failure
+                                // modes. Cap the logged message at 200 chars AND
+                                // strip anything that looks like the leading hex/
+                                // base64 of the just-attempted key so a misbehaving
+                                // backend can't leak it into bridge logs.
+                                const raw = writeErr instanceof Error
+                                    ? writeErr.message
+                                    : String(writeErr);
+                                const safe = raw
+                                    .replaceAll(body.apiKey.key, "[redacted]")
+                                    .slice(0, 200);
+                                this.logger.error(`[/config/patchwork] saveApiKeyToSecureStore failed: ${safe}`);
+                                res.writeHead(500, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({ error: "Failed to write provider API key" }));
+                                return;
+                            }
+                        }
+                        if (driverRaw !== undefined) {
+                            try {
+                                saveBridgeConfigDriver(driverRaw, this.bridgeConfigPath);
                             }
                             catch (writeErr) {
-                                this.logger.error(`[/config/patchwork] saveApiKeyToSecureStore failed: ${writeErr instanceof Error ? (writeErr.stack ?? writeErr.message) : String(writeErr)}`);
+                                this.logger.error(`[/config/patchwork] saveBridgeConfigDriver failed: ${writeErr instanceof Error ? writeErr.message : String(writeErr)}`);
                                 res.writeHead(500, { "Content-Type": "application/json" });
                                 res.end(JSON.stringify({
-                                    error: "Failed to write provider API key",
+                                    error: "Failed to write bridge driver config",
                                 }));
                                 return;
                             }
@@ -1083,46 +1516,551 @@ export class Server extends EventEmitter {
                             savePatchworkConfig(cfg, configPath);
                         }
                         catch (writeErr) {
-                            this.logger.error(`[/config/patchwork] savePatchworkConfig failed: ${writeErr instanceof Error ? (writeErr.stack ?? writeErr.message) : String(writeErr)}`);
+                            this.logger.error(`[/config/patchwork] savePatchworkConfig failed: ${writeErr instanceof Error ? writeErr.message : String(writeErr)}`);
                             res.writeHead(500, { "Content-Type": "application/json" });
-                            res.end(JSON.stringify({
-                                error: "Failed to write patchwork config",
-                            }));
+                            res.end(JSON.stringify({ error: "Failed to write patchwork config" }));
                             return;
                         }
+                        // PHASE 4 — live state. Only after every persistence step
+                        // succeeded; ensures live state never diverges from disk.
+                        if (gateRaw !== undefined) {
+                            const prevGate = this.approvalGate;
+                            this.approvalGate = gateRaw;
+                            // When the operator downgrades to "off", every pending
+                            // queue entry becomes moot — the originating tool dispatch
+                            // now bypasses, and a phone approver who hits "Approve"
+                            // five seconds later would get a 404. Cancel them
+                            // server-side so the dashboard /approvals list clears
+                            // and any pending phone notification reflects reality.
+                            if (gateRaw === "off" && prevGate !== "off") {
+                                const cancelled = getApprovalQueue().cancelAll();
+                                if (cancelled > 0) {
+                                    this.logger.info(`[/settings] approvalGate → off; cancelled ${cancelled} pending entr${cancelled === 1 ? "y" : "ies"}`);
+                                }
+                            }
+                        }
+                        if (body.enableTimeOfDayAnomaly !== undefined) {
+                            this.enableTimeOfDayAnomaly = body.enableTimeOfDayAnomaly;
+                        }
                         if (hasWebhookUpdate) {
-                            this.approvalWebhookUrl = raw || undefined;
+                            this.approvalWebhookUrl = webhookRaw || undefined;
                         }
-                        if (body.pushServiceUrl !== undefined) {
-                            const pushUrl = body.pushServiceUrl.trim();
-                            if (pushUrl && !pushUrl.startsWith("https://")) {
-                                res.writeHead(400, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({ error: "pushServiceUrl must be HTTPS" }));
-                                return;
-                            }
-                            this.pushServiceUrl = pushUrl || undefined;
+                        if (pushUrlTrimmed !== undefined) {
+                            this.pushServiceUrl = pushUrlTrimmed || undefined;
+                        }
+                        if (pushTokenTrimmed !== undefined) {
+                            this.pushServiceToken = pushTokenTrimmed || undefined;
                         }
-                        if (body.pushServiceToken !== undefined) {
-                            this.pushServiceToken = body.pushServiceToken.trim() || undefined;
+                        if (pushBaseTrimmed !== undefined) {
+                            this.pushServiceBaseUrl = pushBaseTrimmed || undefined;
                         }
-                        if (body.pushServiceBaseUrl !== undefined) {
-                            this.pushServiceBaseUrl =
-                                body.pushServiceBaseUrl.trim() || undefined;
+                        if (ntfyTopicTrimmed !== undefined) {
+                            this.ntfyTopic = ntfyTopicTrimmed || undefined;
                         }
+                        if (ntfyServerTrimmed !== undefined) {
+                            this.ntfyServer = ntfyServerTrimmed || undefined;
+                        }
+                        // restartRequired covers fields the bridge only reads at boot:
+                        // driver/model/apiKey (env injection + driver factory), plus
+                        // localEndpoint/localModel which LocalApiDriver reads at
+                        // construction time. Push/ntfy fields are live-mutated on
+                        // `this.*` in PHASE 4 below, so they do not require restart.
                         const restartRequired = driverRaw !== undefined ||
                             body.apiKey !== undefined ||
-                            body.model !== undefined;
+                            body.model !== undefined ||
+                            body.localEndpoint !== undefined ||
+                            body.localModel !== undefined;
+                        // Audit-log emission — forensic record of every config mutation
+                        // so an operator can answer "who changed what, when?" after an
+                        // incident. Bearer-token auth doesn't carry an actor identity
+                        // (no user JWT) so we attribute to "http" with the request IP.
+                        // Secrets are redacted to the shape `"***"` — value presence
+                        // is recorded, value content is never logged.
+                        if (this.activityLog) {
+                            const changes = {};
+                            if (hasWebhookUpdate)
+                                changes.webhookUrl = webhookRaw || "";
+                            if (gateRaw !== undefined)
+                                changes.approvalGate = gateRaw;
+                            if (body.enableTimeOfDayAnomaly !== undefined)
+                                changes.enableTimeOfDayAnomaly = body.enableTimeOfDayAnomaly;
+                            if (driverRaw !== undefined)
+                                changes.driver = driverRaw;
+                            if (body.model !== undefined)
+                                changes.model = body.model;
+                            if (body.localEndpoint !== undefined)
+                                changes.localEndpoint = body.localEndpoint;
+                            if (body.localModel !== undefined)
+                                changes.localModel = body.localModel;
+                            if (body.apiKey)
+                                changes.apiKey = { provider: body.apiKey.provider, key: "***" };
+                            if (pushUrlTrimmed !== undefined)
+                                changes.pushServiceUrl = pushUrlTrimmed || "";
+                            if (pushTokenTrimmed !== undefined)
+                                changes.pushServiceToken = pushTokenTrimmed ? "***" : "";
+                            if (pushBaseTrimmed !== undefined)
+                                changes.pushServiceBaseUrl = pushBaseTrimmed || "";
+                            if (ntfyTopicTrimmed !== undefined)
+                                changes.ntfyTopic = ntfyTopicTrimmed ? "***" : "";
+                            if (ntfyServerTrimmed !== undefined)
+                                changes.ntfyServer = ntfyServerTrimmed || "";
+                            const remoteAddr = req.headers["x-forwarded-for"]
+                                ?.split(",")[0]
+                                ?.trim() ||
+                                req.socket.remoteAddress ||
+                                "unknown";
+                            this.activityLog.recordEvent("settings.change", {
+                                actor: "http",
+                                ip: remoteAddr,
+                                fields: Object.keys(changes),
+                                changes,
+                            });
+                        }
                         res.writeHead(200, { "Content-Type": "application/json" });
                         res.end(JSON.stringify({ ok: true, restartRequired }));
                     }
                 }
                 catch (err) {
-                    this.logger.error(`[/config/patchwork] error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
-                    res.writeHead(400, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Invalid request body" }));
+                    // Any error reaching this outer catch is unexpected — all caller
+                    // validation errors already returned their own 400 inline, and all
+                    // expected disk-write errors return their own 500. So this is a
+                    // server bug, not a client one. Returning 400 here misled clients
+                    // into believing they had sent a bad body when in fact something
+                    // crashed serverside.
+                    this.logger.error(`[/config/patchwork] unhandled error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Internal server error" }));
                 }
                 return;
             }
+            // /kill-switch — dedicated endpoint for the global write-tier kill switch.
+            // See issue #422 v2: not folded into /settings because kill-switch has
+            // audit + idempotency + env-lock semantics nothing else on /settings has.
+            //
+            // POST {engage: boolean, reason?: string} → toggle; idempotent.
+            //   200 {engaged, changed, locked: false}     — accepted
+            //   200 {engaged, changed: false, locked: false} — no-op (already in that state)
+            //   409 {error: "env_locked", flag, frozenValue, lockedReason}
+            //                                               — env-locked, cannot toggle
+            //   400 {error: "invalid_request"}            — malformed body
+            //
+            // GET → status. 200 {engaged, locked, lockedReason?, lockedValue?}
+            //
+            // Audit emit: state transitions log to this.logger.info (always)
+            // AND record via this.recordKillSwitchTraceFn (when wired by the
+            // bridge — see src/bridge.ts where it threads decisionTraceLog
+            // through to ~/.patchwork/decision_traces.jsonl). Tests / headless
+            // contexts that don't wire the callback still get the log line.
+            if (parsedUrl.pathname === "/kill-switch") {
+                if (req.method === "GET") {
+                    const engaged = isWriteKillSwitchActive();
+                    const locked = isEnvLockedFor(KILL_SWITCH_WRITES);
+                    const body = { engaged, locked };
+                    if (locked) {
+                        const lockedValue = getEnvLockedValue(KILL_SWITCH_WRITES);
+                        body.lockedValue = lockedValue;
+                        body.lockedReason = `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${lockedValue ? "1" : "0"} at bridge startup`;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(body));
+                    return;
+                }
+                if (req.method === "POST") {
+                    // 1 KB — body is `{engage: bool, reason?: string}`; reason is a
+                    // short audit note, 1 KB is generous.
+                    const KS_BODY_CAP = 1 * 1024;
+                    const parsed = await readJsonBody(req, KS_BODY_CAP);
+                    if (!parsed.ok) {
+                        if (parsed.code === "too_large") {
+                            respond413(res, KS_BODY_CAP);
+                            return;
+                        }
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_request", reason: "bad_json" }));
+                        return;
+                    }
+                    const body = parsed.value ?? {};
+                    if (respondIfUnknownBodyKeys(res, body, ["engage", "reason"])) {
+                        return;
+                    }
+                    if (typeof body.engage !== "boolean") {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "invalid_request",
+                            reason: "engage must be boolean",
+                        }));
+                        return;
+                    }
+                    const reason = typeof body.reason === "string" && body.reason.trim().length > 0
+                        ? body.reason.trim().slice(0, 500)
+                        : undefined;
+                    // v2-B2 + I3: surface env-lock conflict as structured 409 so CLI
+                    // + dashboard can distinguish "you sent garbage" from
+                    // "policy-locked by sysadmin via PATCHWORK_FLAG_*".
+                    if (isEnvLockedFor(KILL_SWITCH_WRITES)) {
+                        const lockedValue = getEnvLockedValue(KILL_SWITCH_WRITES);
+                        res.writeHead(409, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "env_locked",
+                            flag: KILL_SWITCH_WRITES,
+                            frozenValue: lockedValue,
+                            lockedReason: `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${lockedValue ? "1" : "0"} at bridge startup`,
+                        }));
+                        return;
+                    }
+                    // v2-I12: idempotent. State transitions emit audit; no-ops don't.
+                    const prev = isWriteKillSwitchActive();
+                    const next = body.engage;
+                    const changed = prev !== next;
+                    if (changed) {
+                        try {
+                            setFlag(KILL_SWITCH_WRITES, next, true);
+                        }
+                        catch (err) {
+                            // Belt-and-suspenders: setFlag now throws EnvLockedFlagError if
+                            // the flag was env-locked (we already checked isEnvLockedFor above,
+                            // but a race with lockKillSwitchEnv() in tests warrants this).
+                            if (err instanceof EnvLockedFlagError) {
+                                res.writeHead(409, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({
+                                    error: "env_locked",
+                                    flag: KILL_SWITCH_WRITES,
+                                    frozenValue: err.frozenValue,
+                                    lockedReason: `PATCHWORK_FLAG_KILL_SWITCH_WRITES=${err.frozenValue ? "1" : "0"} at bridge startup`,
+                                }));
+                                return;
+                            }
+                            throw err;
+                        }
+                        // v2-I6: audit emit on every state transition; no-ops skip.
+                        // The bridge wires recordKillSwitchTraceFn to write a
+                        // DecisionTrace entry to ~/.patchwork/decision_traces.jsonl
+                        // (see src/bridge.ts). The logger.info line stays as a
+                        // secondary signal in the bridge log and is the only output
+                        // when the trace fn is unset (tests, headless contexts).
+                        this.logger.info(`[kill-switch] ${next ? "ENGAGED" : "RELEASED"}${reason ? ` (reason: ${reason})` : ""} — actor=http`);
+                        this.recordKillSwitchTraceFn?.({
+                            engaged: next,
+                            reason,
+                            ts: Date.now(),
+                        });
+                        // v2-I8: broadcast SSE kind:"kill-switch" so dashboard updates
+                        // in <1s without changing the poll cadence.
+                        this.broadcastKillSwitchEventFn?.(next, reason);
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        engaged: next,
+                        changed,
+                        locked: false,
+                    }));
+                    return;
+                }
+            }
+            // /feature-flags — list + toggle USER-OPT-IN UI flags only.
+            //
+            // Deliberately scoped: this endpoint can ONLY flip flags where
+            //   category === "ui" && requiresOptIn === true && !isKillSwitch
+            // so it can never be used to disable a safety kill-switch (those go
+            // through the audited /kill-switch route) or enable an experimental
+            // flag. The motivating use is the recipe-editor "Enable & retry"
+            // affordance for `recipe.repair-ai` (default-off, opt-in, costs API
+            // tokens — see featureFlags.ts FLAG_REPAIR_AI).
+            //
+            // POST {id: string, value: boolean}
+            //   200 {id, value, changed}                 — accepted
+            //   400 {error: "invalid_request"}           — malformed body
+            //   404 {error: "unknown_flag"}              — not registered
+            //   403 {error: "not_user_toggleable"}       — flag not in the opt-in/ui set
+            //   409 {error: "env_override", envVar}      — PATCHWORK_FLAG_* pins the
+            //        value; the write persisted to config but isEnabled() still
+            //        resolves to the env value, so the toggle won't take effect.
+            if (parsedUrl.pathname === "/feature-flags") {
+                const isUserToggleable = (f) => f.category === "ui" && f.requiresOptIn && f.isKillSwitch !== true;
+                if (req.method === "POST") {
+                    const FF_BODY_CAP = 1 * 1024;
+                    const parsed = await readJsonBody(req, FF_BODY_CAP);
+                    if (!parsed.ok) {
+                        if (parsed.code === "too_large") {
+                            respond413(res, FF_BODY_CAP);
+                            return;
+                        }
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_request", reason: "bad_json" }));
+                        return;
+                    }
+                    const body = parsed.value ?? {};
+                    if (respondIfUnknownBodyKeys(res, body, ["id", "value"])) {
+                        return;
+                    }
+                    if (typeof body.id !== "string" || typeof body.value !== "boolean") {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "invalid_request",
+                            reason: "id must be string and value must be boolean",
+                        }));
+                        return;
+                    }
+                    const flagId = body.id;
+                    const flag = listFlags().find((f) => f.id === flagId);
+                    if (!flag) {
+                        res.writeHead(404, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "unknown_flag", id: flagId }));
+                        return;
+                    }
+                    if (!isUserToggleable(flag)) {
+                        res.writeHead(403, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "not_user_toggleable", id: flagId }));
+                        return;
+                    }
+                    const prev = isEnabled(flagId);
+                    setFlag(flagId, body.value, true);
+                    // Non-kill-switch flags read PATCHWORK_FLAG_* dynamically with
+                    // precedence over the config we just wrote. If a sysadmin pinned
+                    // the flag via env, the write won't take effect — surface that as
+                    // a 409 instead of a misleading 200 (the editor would otherwise
+                    // "Enable & retry" straight into another 503).
+                    const effective = isEnabled(flagId);
+                    if (effective !== body.value) {
+                        const envVar = `PATCHWORK_FLAG_${flagId
+                            .replace(/[.-]/g, "_")
+                            .toUpperCase()}`;
+                        res.writeHead(409, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "env_override",
+                            id: flagId,
+                            envVar,
+                            effectiveValue: effective,
+                        }));
+                        return;
+                    }
+                    this.logger.info(`[feature-flags] ${flagId} = ${body.value} — actor=http`);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        id: flagId,
+                        value: body.value,
+                        changed: prev !== body.value,
+                    }));
+                    return;
+                }
+            }
+            // /telemetry-prefs — read/write per-flag telemetry preferences.
+            // GET    → {crashReports, usageStats, localDiagnostics, endpoint, endpointSource}
+            // POST   {crashReports?, usageStats?, localDiagnostics?} → same shape (partial update)
+            // DELETE → clears prefs file + analytics-config + install salt
+            //          (right-to-erasure affordance).
+            if (parsedUrl.pathname === "/telemetry-prefs") {
+                if (req.method === "GET") {
+                    const prefs = getTelemetryPrefs();
+                    const all = getAnalyticsPrefsAll();
+                    const response = { ...prefs };
+                    if (all?.lastSentAt !== undefined) {
+                        response.lastSentAt = all.lastSentAt;
+                    }
+                    // Destination visibility — consent baseline. Caller can see
+                    // where their data would go and whether the destination came
+                    // from env (CI/headless) or the on-disk config file.
+                    const envEndpoint = process.env.PATCHWORK_ANALYTICS_ENDPOINT;
+                    const cfgEndpoint = getAnalyticsConfig().endpoint;
+                    const defaultEndpoint = "https://analytics.claude-ide-bridge.dev/v1/usage";
+                    if (envEndpoint) {
+                        response.endpoint = envEndpoint;
+                        response.endpointSource = "env";
+                    }
+                    else if (cfgEndpoint) {
+                        response.endpoint = cfgEndpoint;
+                        response.endpointSource = "config";
+                    }
+                    else {
+                        response.endpoint = defaultEndpoint;
+                        response.endpointSource = "default";
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(response));
+                    return;
+                }
+                if (req.method === "DELETE") {
+                    // Right-to-erasure: drop prefs, analytics-config (endpoint /
+                    // shared secret), and the install salt. Next outbound send
+                    // (if any) will mint a fresh salt and treat this as a new
+                    // install. Kill-switch is honored here too — incident-mode
+                    // operators may still want to scrub local state, so allow
+                    // it; flip if the threat model changes.
+                    try {
+                        unlinkSync(getAnalyticsPrefsPath());
+                    }
+                    catch {
+                        /* missing is fine */
+                    }
+                    try {
+                        unlinkSync(getAnalyticsSaltPath());
+                    }
+                    catch {
+                        /* missing is fine */
+                    }
+                    clearAnalyticsConfig();
+                    if (this.activityLog) {
+                        this.activityLog.recordEvent("telemetry.reset", {
+                            actor: "http",
+                            ip: req.headers["x-forwarded-for"]
+                                ?.split(",")[0]
+                                ?.trim() ||
+                                req.socket.remoteAddress ||
+                                "unknown",
+                        });
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (req.method === "POST") {
+                    // Kill-switch gate — telemetry prefs are config writes too.
+                    // GET stays open so operators can verify state during an
+                    // incident.
+                    if (isWriteKillSwitchActive()) {
+                        res.writeHead(423, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            error: "kill_switch_blocked",
+                            reason: "Telemetry pref writes are disabled while the write kill-switch is engaged.",
+                        }));
+                        return;
+                    }
+                    const TP_BODY_CAP = 1 * 1024;
+                    const parsed = await readJsonBody(req, TP_BODY_CAP);
+                    if (!parsed.ok) {
+                        if (parsed.code === "too_large") {
+                            respond413(res, TP_BODY_CAP);
+                            return;
+                        }
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "invalid_request", reason: "bad_json" }));
+                        return;
+                    }
+                    const body = parsed.value ?? {};
+                    if (respondIfUnknownBodyKeys(res, body, [
+                        "crashReports",
+                        "usageStats",
+                        "localDiagnostics",
+                    ])) {
+                        return;
+                    }
+                    const update = {};
+                    // Reject non-boolean values for known keys instead of silently
+                    // dropping them. Previously `{"crashReports": "true"}` (string)
+                    // got a 200 with no effect — caller never learned the toggle
+                    // did nothing. Misrepresented consent is the worst-case
+                    // outcome on the telemetry surface, so be strict here.
+                    for (const key of [
+                        "crashReports",
+                        "usageStats",
+                        "localDiagnostics",
+                    ]) {
+                        if (body[key] !== undefined && typeof body[key] !== "boolean") {
+                            res.writeHead(400, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({
+                                error: "invalid_request",
+                                reason: `${key} must be a boolean`,
+                            }));
+                            return;
+                        }
+                    }
+                    if (typeof body.crashReports === "boolean") {
+                        update.crashReports = body.crashReports;
+                    }
+                    if (typeof body.usageStats === "boolean") {
+                        update.usageStats = body.usageStats;
+                    }
+                    if (typeof body.localDiagnostics === "boolean") {
+                        update.localDiagnostics = body.localDiagnostics;
+                    }
+                    setTelemetryPrefs(update);
+                    const prefs = getTelemetryPrefs();
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(prefs));
+                    return;
+                }
+            }
+            // /restart — graceful bridge restart endpoint.
+            // POST → triggers SIGTERM if no active work; returns 409 if busy.
+            // Safety checks: rejects restart if sessions have in-flight tool calls.
+            if (parsedUrl.pathname === "/restart" && req.method === "POST") {
+                if (!this.restartCheckFn) {
+                    res.writeHead(503, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: "restart_unavailable",
+                        reason: "Restart endpoint not configured",
+                    }));
+                    return;
+                }
+                const check = this.restartCheckFn();
+                // Reject restart if there's active work
+                if (check.inFlightCalls > 0) {
+                    this.logger.warn(`[/restart] Rejected — ${check.inFlightCalls} in-flight tool call${check.inFlightCalls === 1 ? "" : "s"} across ${check.busySessions.length} session${check.busySessions.length === 1 ? "" : "s"}`);
+                    res.writeHead(409, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: "restart_blocked",
+                        reason: `${check.inFlightCalls} tool call${check.inFlightCalls === 1 ? "" : "s"} in progress`,
+                        activeSessions: check.totalSessions,
+                        inFlightCalls: check.inFlightCalls,
+                        busySessions: check.busySessions,
+                    }));
+                    return;
+                }
+                // Safe to restart — log and trigger SIGTERM
+                this.logger.info(`[/restart] Initiating graceful restart — ${check.totalSessions} session${check.totalSessions === 1 ? "" : "s"}, 0 in-flight calls`);
+                res.writeHead(202, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: true,
+                    message: "Restart initiated. Bridge will shut down gracefully.",
+                    activeSessions: check.totalSessions,
+                }));
+                // Trigger shutdown after response is sent (100ms delay to ensure response delivery).
+                // Uses this.restartKillFn so tests can override without killing the runner.
+                const killFn = this.restartKillFn;
+                setTimeout(() => {
+                    this.logger.info("[/restart] Sending SIGTERM to self");
+                    killFn();
+                }, 100);
+                return;
+            }
+            // /shutdown — graceful exit endpoint. POST → triggers the bridge's
+            // internal shutdown sequence (lockfile unlink, HTTP close, telemetry
+            // flush). Same in-flight safety check as /restart; pass `?force=1` to
+            // skip it. Necessary on Windows where `process.kill(pid, 'SIGTERM')`
+            // is TerminateProcess and cleanup handlers never fire — the bridge
+            // wires `shutdownFn` to call the shutdown sequence directly.
+            if (parsedUrl.pathname === "/shutdown" && req.method === "POST") {
+                const force = parsedUrl.searchParams.get("force") === "1";
+                if (!force && this.restartCheckFn) {
+                    const check = this.restartCheckFn();
+                    if (check.inFlightCalls > 0) {
+                        this.logger.warn(`[/shutdown] Rejected — ${check.inFlightCalls} in-flight tool call${check.inFlightCalls === 1 ? "" : "s"}`);
+                        res.writeHead(409, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: "shutdown_blocked",
+                            reason: `${check.inFlightCalls} tool call${check.inFlightCalls === 1 ? "" : "s"} in progress`,
+                            inFlightCalls: check.inFlightCalls,
+                            busySessions: check.busySessions,
+                        }));
+                        return;
+                    }
+                }
+                this.logger.info("[/shutdown] Initiating graceful shutdown");
+                res.writeHead(202, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: true,
+                    message: "Shutdown initiated.",
+                }));
+                const shutdownFn = this.shutdownFn;
+                setTimeout(() => {
+                    this.logger.info("[/shutdown] Calling bridge shutdown sequence");
+                    shutdownFn();
+                }, 100);
+                return;
+            }
             // CC hook notify endpoint — lightweight alternative to full MCP session for hook wiring.
             if (parsedUrl.pathname === "/notify" && req.method === "POST") {
                 // 8 KB — notify payloads carry an event name + small arg map
@@ -1208,7 +2146,9 @@ export class Server extends EventEmitter {
                         path: parsedUrl.pathname,
                         body: parsedBody,
                         query: parsedUrl.searchParams,
-                        approvalToken: req.headers["x-approval-token"],
+                        approvalToken: req.headers["x-approval-token"] ??
+                            parsedUrl.searchParams.get("token") ??
+                            undefined,
                     }, {
                         queue: getApprovalQueue(),
                         workspace: process.cwd(),
@@ -1219,6 +2159,8 @@ export class Server extends EventEmitter {
                         pushServiceUrl: this.pushServiceUrl,
                         pushServiceToken: this.pushServiceToken,
                         pushServiceBaseUrl: this.pushServiceBaseUrl,
+                        ntfyTopic: this.ntfyTopic,
+                        ntfyServer: this.ntfyServer,
                         activityLog: this.activityLog,
                         // RecipeRunLog satisfies RecipeRunQuerier structurally
                         // — the cast bridges TS contravariance: RecipeRunQuerier's
@@ -1269,7 +2211,7 @@ export class Server extends EventEmitter {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Quick tasks unavailable — requires --claude-driver subprocess",
+                        error: "Quick tasks unavailable — requires --driver subprocess",
                     }));
                     return;
                 }
@@ -1424,6 +2366,41 @@ export class Server extends EventEmitter {
             this.emit("connection", ws);
         });
     }
+    /**
+     * Resolve the client IP for rate-limit bucketing on the phone-path
+     * approval bypass. Default: the direct socket peer. When trustedProxies
+     * is set AND the socket peer is one of them, the rightmost X-Forwarded-For
+     * entry not in the trusted list is the real client. XFF from an untrusted
+     * peer is ignored — that header is spoofable by anyone who can reach the
+     * server directly. Returns null when no IP can be determined; the caller
+     * should fail closed.
+     */
+    getClientIp(req) {
+        const socketIp = req.socket?.remoteAddress;
+        if (socketIp &&
+            this.trustedProxies.length > 0 &&
+            this.trustedProxies.includes(socketIp)) {
+            const xffRaw = req.headers["x-forwarded-for"];
+            const xffStr = Array.isArray(xffRaw) ? xffRaw[0] : xffRaw;
+            if (typeof xffStr === "string" && xffStr.length > 0) {
+                const hops = xffStr
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
+                // Walk right→left (proxies append to the right). The rightmost hop
+                // we DON'T trust is the client; everything to its right is our own
+                // hop chain.
+                for (let i = hops.length - 1; i >= 0; i--) {
+                    const hop = hops[i];
+                    if (hop !== undefined && !this.trustedProxies.includes(hop)) {
+                        return hop.slice(0, 64);
+                    }
+                }
+                // Edge case: every hop is in trustedProxies — unusual; fall through.
+            }
+        }
+        return socketIp ? socketIp.slice(0, 64) : null;
+    }
     async listen(port, bindAddress = "127.0.0.1") {
         const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
         if (!LOOPBACK.has(bindAddress)) {