patchwork-os 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/server.js

@@ -1,12 +1,15 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { WebSocket, WebSocketServer as WsServer } from "ws";
+import { getAnalyticsPrefsAll, 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 { EnvLockedFlagError, getEnvLockedValue, isEnvLockedFor, isWriteKillSwitchActive, KILL_SWITCH_WRITES, setFlag, } from "./featureFlags.js";
 import { respond500 } from "./httpErrorResponse.js";
 import { tryHandleInboxRoute } from "./inboxRoutes.js";
 import { tryHandleMcpRoute } from "./mcpRoutes.js";
@@ -49,6 +52,7 @@ export class Server extends EventEmitter {
     logger;
     extraCorsOrigins;
     pingIntervalMs;
+    trustedProxies;
     httpServer;
     wss;
     pingInterval = null;
@@ -102,6 +106,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 +117,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 +146,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 +172,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 +211,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 +264,8 @@ 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;
     /**
      * Attach an OAuth 2.0 Authorization Server.
      * When set, the bridge exposes:
@@ -196,12 +282,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) {
@@ -376,8 +469,64 @@ export class Server extends EventEmitter {
             const isPhoneApprovalPath = req.method === "POST" &&
                 /^\/(approve|reject)\/[A-Za-z0-9-]+$/.test(parsedUrl.pathname) &&
                 !!req.headers["x-approval-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
@@ -689,6 +838,34 @@ export class Server extends EventEmitter {
                     respond413(res, HOOKS_BODY_CAP);
                     return;
                 }
+                // HMAC-SHA256 verification for GitHub-style webhooks. The signature
+                // must be computed over the raw request bytes — readBodyWithCap
+                // utf-8-decodes the body, so we re-encode here. The byte sequence
+                // round-trips identically for any valid utf-8 input (which JSON is).
+                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 rawBody = Buffer.from(read.body, "utf-8");
+                    const expected = "sha256=" +
+                        createHmac("sha256", this.webhookSecret)
+                            .update(rawBody)
+                            .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 +879,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 +905,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" });
@@ -892,9 +1082,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;
             }
@@ -1106,8 +1299,46 @@ export class Server extends EventEmitter {
                             this.pushServiceToken = body.pushServiceToken.trim() || undefined;
                         }
                         if (body.pushServiceBaseUrl !== undefined) {
-                            this.pushServiceBaseUrl =
-                                body.pushServiceBaseUrl.trim() || undefined;
+                            const baseUrl = body.pushServiceBaseUrl.trim();
+                            // pushServiceBaseUrl is the bridge callback origin embedded in
+                            // the SW's approveUrl/rejectUrl. If it can be set to plain
+                            // http:// or to a host the operator didn't intend, the SW will
+                            // POST the one-shot approvalToken there — letting an attacker
+                            // who sets this redirect every approval to attacker.tld and
+                            // replay tokens to the real bridge for silent auto-approve.
+                            if (baseUrl && !baseUrl.startsWith("https://")) {
+                                res.writeHead(400, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({ error: "pushServiceBaseUrl must be HTTPS" }));
+                                return;
+                            }
+                            this.pushServiceBaseUrl = baseUrl || undefined;
+                        }
+                        if (body.ntfyTopic !== undefined) {
+                            const topic = body.ntfyTopic.trim();
+                            // Topic acts as a bearer token on the public ntfy.sh server —
+                            // anyone subscribed sees the approval payload + single-use
+                            // approvalToken. Reject empty / whitespace / control chars to
+                            // avoid silent misconfiguration.
+                            if (topic && !/^[A-Za-z0-9_-]{1,64}$/.test(topic)) {
+                                res.writeHead(400, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({
+                                    error: "ntfyTopic must match [A-Za-z0-9_-]{1,64}",
+                                }));
+                                return;
+                            }
+                            this.ntfyTopic = topic || undefined;
+                        }
+                        if (body.ntfyServer !== undefined) {
+                            const server = body.ntfyServer.trim();
+                            // Same reasoning as pushServiceBaseUrl — the bridge sends the
+                            // single-use token to this URL. http:// would expose it on the
+                            // wire; a malicious value would exfiltrate every approval.
+                            if (server && !server.startsWith("https://")) {
+                                res.writeHead(400, { "Content-Type": "application/json" });
+                                res.end(JSON.stringify({ error: "ntfyServer must be HTTPS" }));
+                                return;
+                            }
+                            this.ntfyServer = server || undefined;
                         }
                         const restartRequired = driverRaw !== undefined ||
                             body.apiKey !== undefined ||
@@ -1123,6 +1354,212 @@ export class Server extends EventEmitter {
                 }
                 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 is stubbed with this.logger.info — full plumbing
+            // (decisionTraceLog into Server) lands in step 5 of the #422 series.
+            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 (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.
+                        // When the bridge wires recordKillSwitchTraceFn (step 5),
+                        // this writes to ~/.patchwork/decision_traces.jsonl. The
+                        // logger.info line stays as a secondary signal in the
+                        // bridge log; it's 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;
+                }
+            }
+            // /telemetry-prefs — read/write per-flag telemetry preferences.
+            // GET  → {crashReports, usageStats, localDiagnostics}
+            // POST {crashReports?, usageStats?, localDiagnostics?} → same shape (partial update)
+            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;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(response));
+                    return;
+                }
+                if (req.method === "POST") {
+                    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 ?? {};
+                    const update = {};
+                    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 SIGTERM after response is sent (100ms delay to ensure response delivery)
+                setTimeout(() => {
+                    this.logger.info("[/restart] Sending SIGTERM to self");
+                    process.kill(process.pid, "SIGTERM");
+                }, 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
@@ -1219,6 +1656,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 +1708,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 +1863,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)) {