commandmate 0.27.1 → 0.29.0

package/dist/lib/server/localhost-self-check.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Startup self-check: does the URL we tell users to open actually reach US?
+ * Issue #2113
+ *
+ * CommandMate binds IPv4 `127.0.0.1` by default (server.ts, `CM_BIND`), but every
+ * setup guide sends the user to `http://localhost:<port>`. On macOS `localhost`
+ * resolves `::1` (IPv6) BEFORE `127.0.0.1`, and a `0.0.0.0`/`::` bind of ours never
+ * covers `::1` either — so an unrelated process holding `::1:<port>` silently owns
+ * the address the docs advertise. The browser then talks to that process while
+ * CommandMate keeps reporting a healthy `> Ready on http://127.0.0.1:<port>`.
+ *
+ * Measured 2026-08-27 on develop 54e122a9: `127.0.0.1:3000` answered in 14ms while
+ * `localhost:3000` and `[::1]:3000` both timed out after 10s against a stray Next.js
+ * dev server. Because the squatter was also Next.js, the browser pulled chunks from
+ * the WRONG app and rendered CommandMate's own `error.chunkReload.title`
+ * ("Updating to the latest version") — an error screen that looks like ours while
+ * not being served by us at all.
+ *
+ * HOW IDENTITY IS DECIDED (the part that has to be exact):
+ *
+ * The probe sends a GET to `<protocol>://localhost:<port>/api/auth/status` carrying a
+ * one-shot random nonce in `x-cm-self-check`, and our own HTTP server carries a
+ * temporary `prependListener('request')` that watches for that nonce. The verdict comes
+ * from OUR OWN OBSERVATION of the request, never from trusting the response body:
+ *
+ *   observed the nonce            -> 'self'         (the advertised URL reaches us)
+ *   got an HTTP response, no nonce-> 'foreign'      (something else answered)  <- WARN
+ *   connection error / timeout    -> 'unreachable'  (nothing there; browsers fall
+ *                                                    through to 127.0.0.1)     <- silent
+ *
+ * `/api/auth/status` is deliberately an EXISTING endpoint (it is in
+ * AUTH_EXCLUDED_PATHS, touches no DB and mutates nothing), so no diagnostic route had
+ * to be added. Nothing in the verdict depends on what it returns, which is why the
+ * check still works with auth on, with an IP ACL that would 403 us, and against an
+ * HTTPS server with a self-signed certificate.
+ *
+ * FAIL-OPEN IS THE CONTRACT. Nothing here throws, nothing here blocks `listen`, and
+ * only the 'foreign' verdict produces output. 'unreachable' is deliberately silent:
+ * an empty `::1` is the NORMAL case on a machine where nothing squats the port, and
+ * Node's Happy Eyeballs (and every browser) then falls through to `127.0.0.1`.
+ *
+ * @module lib/server/localhost-self-check
+ */
+import { type IncomingMessage, type ServerResponse } from 'http';
+/** Header the probe request carries its nonce in */
+export declare const SELF_CHECK_HEADER = "x-cm-self-check";
+/**
+ * Endpoint the probe targets. Existing route, in AUTH_EXCLUDED_PATHS
+ * (src/config/auth-config.ts), no DB access, no side effects.
+ */
+export declare const SELF_CHECK_PATH = "/api/auth/status";
+/** Hostname the docs advertise, and therefore the one under test */
+export declare const SELF_CHECK_HOSTNAME = "localhost";
+/** How long to wait for either the nonce observation or a response */
+export declare const SELF_CHECK_TIMEOUT_MS = 3000;
+/**
+ * Directory (under the config dir) the conflict records live in.
+ *
+ * `logs/` and not a dedicated `self-check/`: in a local install `getConfigDir()` is the
+ * repository checkout itself, and `.gitignore` already ignores `logs/` there (it does
+ * the same for `data/`, `skills/`, `temp/` — "service-owned runtime state lands at the
+ * repo root"). A new top-level directory would show up as an untracked change in the
+ * user's own repository, which for a worktree manager means dirtying a repo it also
+ * displays. The record is diagnostic output keyed by port, so `logs/` fits it anyway.
+ */
+export declare const SELF_CHECK_DIR_NAME = "logs";
+/** Filename prefix of a conflict record inside {@link SELF_CHECK_DIR_NAME} */
+export declare const SELF_CHECK_FILE_PREFIX = "self-check-";
+/**
+ * What the startup probe concluded.
+ *
+ * Only `foreign` is actionable; see the module header for why `unreachable` is silent.
+ */
+export type LocalhostProbeVerdict = 'self' | 'foreign' | 'unreachable';
+/**
+ * The record a conflicted server leaves behind for `commandmate status`.
+ *
+ * `pid` is what makes the record trustworthy: `status` only reports it when it matches
+ * the PID it just read out of the state file, so a record left by an earlier server on
+ * the same port can never be attributed to the current one.
+ */
+export interface LocalhostConflictRecord {
+    /** Port the conflict was observed on */
+    port: number;
+    /** PID of the CommandMate server that observed it */
+    pid: number;
+    /** CM_BIND as configured */
+    bind: string;
+    /** URL CommandMate actually listens on */
+    boundUrl: string;
+    /** URL that was probed, i.e. the one the documentation advertises */
+    probedUrl: string;
+    /** ISO timestamp of the observation */
+    detectedAt: string;
+}
+/**
+ * The slice of `http.Server` the probe needs. Structural on purpose: tests hand it a
+ * real `http.Server`, and nothing here should be able to touch the rest of the server.
+ */
+export interface RequestObserver {
+    prependListener(event: 'request', listener: (req: IncomingMessage, res: ServerResponse) => void): unknown;
+    removeListener(event: 'request', listener: (req: IncomingMessage, res: ServerResponse) => void): unknown;
+}
+/** Options for {@link probeLocalhostIdentity} */
+export interface ProbeLocalhostOptions {
+    /** Our own HTTP(S) server, used to observe the probe request landing on us */
+    server: RequestObserver;
+    /** Port the server listens on */
+    port: number;
+    /** Protocol the server speaks (default: 'http') */
+    protocol?: 'http' | 'https';
+    /** Hostname to probe (default: {@link SELF_CHECK_HOSTNAME}); overridden in tests */
+    host?: string;
+    /** Request path (default: {@link SELF_CHECK_PATH}) */
+    path?: string;
+    /** Deadline for the whole probe (default: {@link SELF_CHECK_TIMEOUT_MS}) */
+    timeoutMs?: number;
+    /** Nonce override; generated per call when omitted */
+    nonce?: string;
+}
+/**
+ * Ask "if a user opens the URL we advertise, do they reach this process?".
+ *
+ * Resolves as soon as the answer is known — the nonce observation fires on our
+ * server's `request` event, i.e. when headers arrive, so a 'self' verdict does not
+ * wait for Next.js to render or compile the route.
+ *
+ * Never rejects.
+ */
+export declare function probeLocalhostIdentity(options: ProbeLocalhostOptions): Promise<LocalhostProbeVerdict>;
+/**
+ * Build the dialable URL for a bind address, matching resolveServerEndpoint()'s rule
+ * that a wildcard bind is reported as 127.0.0.1.
+ */
+export declare function formatBoundUrl(protocol: 'http' | 'https', bind: string, port: number): string;
+/**
+ * The warning, as lines, shared by the startup log and `commandmate status` so the two
+ * can never drift apart.
+ */
+export declare function formatLocalhostConflictWarning(record: LocalhostConflictRecord): string[];
+/** Directory holding the per-port conflict records */
+export declare function getSelfCheckDir(): string;
+/**
+ * Path of the record for one port (`<configDir>/logs/self-check-<port>.json`).
+ *
+ * @throws Error when the port is not a plausible TCP port — the value becomes a
+ *   filename, so it is validated rather than interpolated blindly.
+ */
+export declare function getSelfCheckStatePath(port: number): string;
+/**
+ * Persist a conflict for `commandmate status` to read.
+ *
+ * @returns true when the record was written
+ */
+export declare function writeLocalhostConflict(record: LocalhostConflictRecord): boolean;
+/**
+ * Read the conflict recorded for a port.
+ *
+ * Never throws: `status` must keep working on an unreadable, truncated or
+ * hand-edited record, and on a machine where the config dir cannot be resolved at all.
+ *
+ * @returns The record, or null when there is none (or it is unusable)
+ */
+export declare function readLocalhostConflict(port: number): LocalhostConflictRecord | null;
+/**
+ * Drop the record for a port. Called on every clean self-check and on shutdown, so a
+ * fixed environment stops warning on the next start rather than needing a manual sweep.
+ */
+export declare function clearLocalhostConflict(port: number): void;
+/** Options for {@link runLocalhostSelfCheck} */
+export interface RunLocalhostSelfCheckOptions {
+    /** Our own HTTP(S) server */
+    server: RequestObserver;
+    /** Port the server listens on */
+    port: number;
+    /** CM_BIND as configured */
+    bind: string;
+    /** Protocol the server speaks (default: 'http') */
+    protocol?: 'http' | 'https';
+    /** Hostname to probe (default: {@link SELF_CHECK_HOSTNAME}); overridden in tests */
+    host?: string;
+    /** Deadline for the probe */
+    timeoutMs?: number;
+    /** PID to stamp the record with (default: `process.pid`) */
+    pid?: number;
+    /** Clock, injectable for deterministic tests */
+    now?: () => Date;
+    /** Where the warning goes (default: `console.warn`) */
+    warn?: (message: string) => void;
+    /** Probe override, injected by tests */
+    probe?: (options: ProbeLocalhostOptions) => Promise<LocalhostProbeVerdict>;
+}
+/**
+ * Run the startup self-check and route its verdict to the log and the status file.
+ *
+ * Fail-open by construction: every path is wrapped, the function never rejects, and the
+ * caller in server.ts does not await it. A `null` return means the check could not be
+ * carried out at all — which is reported as nothing, exactly like 'unreachable'.
+ *
+ * @returns The verdict, or null when the check itself failed
+ */
+export declare function runLocalhostSelfCheck(options: RunLocalhostSelfCheckOptions): Promise<LocalhostProbeVerdict | null>;
+//# sourceMappingURL=localhost-self-check.d.ts.map

package/dist/lib/server/localhost-self-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localhost-self-check.d.ts","sourceRoot":"","sources":["../../../src/lib/server/localhost-self-check.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/localhost-self-check.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * Startup self-check: does the URL we tell users to open actually reach US?
+ * Issue #2113
+ *
+ * CommandMate binds IPv4 `127.0.0.1` by default (server.ts, `CM_BIND`), but every
+ * setup guide sends the user to `http://localhost:<port>`. On macOS `localhost`
+ * resolves `::1` (IPv6) BEFORE `127.0.0.1`, and a `0.0.0.0`/`::` bind of ours never
+ * covers `::1` either — so an unrelated process holding `::1:<port>` silently owns
+ * the address the docs advertise. The browser then talks to that process while
+ * CommandMate keeps reporting a healthy `> Ready on http://127.0.0.1:<port>`.
+ *
+ * Measured 2026-08-27 on develop 54e122a9: `127.0.0.1:3000` answered in 14ms while
+ * `localhost:3000` and `[::1]:3000` both timed out after 10s against a stray Next.js
+ * dev server. Because the squatter was also Next.js, the browser pulled chunks from
+ * the WRONG app and rendered CommandMate's own `error.chunkReload.title`
+ * ("Updating to the latest version") — an error screen that looks like ours while
+ * not being served by us at all.
+ *
+ * HOW IDENTITY IS DECIDED (the part that has to be exact):
+ *
+ * The probe sends a GET to `<protocol>://localhost:<port>/api/auth/status` carrying a
+ * one-shot random nonce in `x-cm-self-check`, and our own HTTP server carries a
+ * temporary `prependListener('request')` that watches for that nonce. The verdict comes
+ * from OUR OWN OBSERVATION of the request, never from trusting the response body:
+ *
+ *   observed the nonce            -> 'self'         (the advertised URL reaches us)
+ *   got an HTTP response, no nonce-> 'foreign'      (something else answered)  <- WARN
+ *   connection error / timeout    -> 'unreachable'  (nothing there; browsers fall
+ *                                                    through to 127.0.0.1)     <- silent
+ *
+ * `/api/auth/status` is deliberately an EXISTING endpoint (it is in
+ * AUTH_EXCLUDED_PATHS, touches no DB and mutates nothing), so no diagnostic route had
+ * to be added. Nothing in the verdict depends on what it returns, which is why the
+ * check still works with auth on, with an IP ACL that would 403 us, and against an
+ * HTTPS server with a self-signed certificate.
+ *
+ * FAIL-OPEN IS THE CONTRACT. Nothing here throws, nothing here blocks `listen`, and
+ * only the 'foreign' verdict produces output. 'unreachable' is deliberately silent:
+ * an empty `::1` is the NORMAL case on a machine where nothing squats the port, and
+ * Node's Happy Eyeballs (and every browser) then falls through to `127.0.0.1`.
+ *
+ * @module lib/server/localhost-self-check
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SELF_CHECK_FILE_PREFIX = exports.SELF_CHECK_DIR_NAME = exports.SELF_CHECK_TIMEOUT_MS = exports.SELF_CHECK_HOSTNAME = exports.SELF_CHECK_PATH = exports.SELF_CHECK_HEADER = void 0;
+exports.probeLocalhostIdentity = probeLocalhostIdentity;
+exports.formatBoundUrl = formatBoundUrl;
+exports.formatLocalhostConflictWarning = formatLocalhostConflictWarning;
+exports.getSelfCheckDir = getSelfCheckDir;
+exports.getSelfCheckStatePath = getSelfCheckStatePath;
+exports.writeLocalhostConflict = writeLocalhostConflict;
+exports.readLocalhostConflict = readLocalhostConflict;
+exports.clearLocalhostConflict = clearLocalhostConflict;
+exports.runLocalhostSelfCheck = runLocalhostSelfCheck;
+const http_1 = require("http");
+const https_1 = require("https");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+// Relative, NOT `@/cli/utils/...`: this module is pulled into the CLI program by
+// src/cli/commands/status.ts, and tsconfig.cli.json resets `paths` to {} — an alias
+// import here would break `npm run build:cli`. Same reason as version-probes.ts.
+const install_context_1 = require("../../cli/utils/install-context");
+/** Header the probe request carries its nonce in */
+exports.SELF_CHECK_HEADER = 'x-cm-self-check';
+/**
+ * Endpoint the probe targets. Existing route, in AUTH_EXCLUDED_PATHS
+ * (src/config/auth-config.ts), no DB access, no side effects.
+ */
+exports.SELF_CHECK_PATH = '/api/auth/status';
+/** Hostname the docs advertise, and therefore the one under test */
+exports.SELF_CHECK_HOSTNAME = 'localhost';
+/** How long to wait for either the nonce observation or a response */
+exports.SELF_CHECK_TIMEOUT_MS = 3000;
+/**
+ * Directory (under the config dir) the conflict records live in.
+ *
+ * `logs/` and not a dedicated `self-check/`: in a local install `getConfigDir()` is the
+ * repository checkout itself, and `.gitignore` already ignores `logs/` there (it does
+ * the same for `data/`, `skills/`, `temp/` — "service-owned runtime state lands at the
+ * repo root"). A new top-level directory would show up as an untracked change in the
+ * user's own repository, which for a worktree manager means dirtying a repo it also
+ * displays. The record is diagnostic output keyed by port, so `logs/` fits it anyway.
+ */
+exports.SELF_CHECK_DIR_NAME = 'logs';
+/** Filename prefix of a conflict record inside {@link SELF_CHECK_DIR_NAME} */
+exports.SELF_CHECK_FILE_PREFIX = 'self-check-';
+/**
+ * Ask "if a user opens the URL we advertise, do they reach this process?".
+ *
+ * Resolves as soon as the answer is known — the nonce observation fires on our
+ * server's `request` event, i.e. when headers arrive, so a 'self' verdict does not
+ * wait for Next.js to render or compile the route.
+ *
+ * Never rejects.
+ */
+async function probeLocalhostIdentity(options) {
+    const { server, port, protocol = 'http', host = exports.SELF_CHECK_HOSTNAME, path = exports.SELF_CHECK_PATH, timeoutMs = exports.SELF_CHECK_TIMEOUT_MS, } = options;
+    const nonce = options.nonce ?? (0, crypto_1.randomBytes)(16).toString('hex');
+    return new Promise((resolve) => {
+        let settled = false;
+        let observed = false;
+        let timer = null;
+        // Prepended so we read the header before server.ts's own request handler can
+        // rewrite anything on it.
+        const listener = (req) => {
+            const seen = req?.headers?.[exports.SELF_CHECK_HEADER];
+            const value = Array.isArray(seen) ? seen[0] : seen;
+            if (value === nonce) {
+                observed = true;
+                settle('self');
+            }
+        };
+        const settle = (verdict) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            try {
+                server.removeListener('request', listener);
+            }
+            catch {
+                // A server that cannot detach a listener is still not a reason to fail startup.
+            }
+            resolve(verdict);
+        };
+        try {
+            server.prependListener('request', listener);
+        }
+        catch {
+            // Without the observer there is no way to tell 'self' from 'foreign'; declaring
+            // 'foreign' here would warn on a perfectly healthy machine.
+            resolve('unreachable');
+            return;
+        }
+        timer = setTimeout(() => settle(observed ? 'self' : 'unreachable'), timeoutMs);
+        let req;
+        try {
+            const send = protocol === 'https' ? https_1.request : http_1.request;
+            req = send({
+                host,
+                port,
+                path,
+                method: 'GET',
+                headers: {
+                    [exports.SELF_CHECK_HEADER]: nonce,
+                    'user-agent': 'commandmate-self-check',
+                },
+                // A self-signed certificate is the documented local HTTPS setup
+                // (`mkcert localhost`, see `commandmate start --cert`), so verifying here
+                // would turn every such install's check into a silent 'unreachable'.
+                // Skipping verification is safe HERE and only here: the verdict comes from
+                // our own in-process observation rather than from trusting the peer, the
+                // request carries no credentials, and its only payload is a random nonce
+                // that means nothing to anyone else. NODE_TLS_REJECT_UNAUTHORIZED is never
+                // touched — this is scoped to this one request.
+                ...(protocol === 'https' ? { rejectUnauthorized: false } : {}),
+            });
+        }
+        catch {
+            settle(observed ? 'self' : 'unreachable');
+            return;
+        }
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+        });
+        req.on('response', (res) => {
+            // Drain so the socket can close; the body is never inspected.
+            res.resume();
+            settle(observed ? 'self' : 'foreign');
+        });
+        req.on('error', () => {
+            settle(observed ? 'self' : 'unreachable');
+        });
+        try {
+            req.end();
+        }
+        catch {
+            settle(observed ? 'self' : 'unreachable');
+        }
+    });
+}
+/**
+ * Bracket a bare IPv6 literal so the result is a URL a user can paste. `localhost` and
+ * dotted-quad hosts pass through untouched.
+ */
+function formatHostForUrl(host) {
+    return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+/**
+ * Build the dialable URL for a bind address, matching resolveServerEndpoint()'s rule
+ * that a wildcard bind is reported as 127.0.0.1.
+ */
+function formatBoundUrl(protocol, bind, port) {
+    const host = bind === '0.0.0.0' ? '127.0.0.1' : bind;
+    return `${protocol}://${formatHostForUrl(host)}:${port}`;
+}
+/**
+ * The warning, as lines, shared by the startup log and `commandmate status` so the two
+ * can never drift apart.
+ */
+function formatLocalhostConflictWarning(record) {
+    return [
+        `Another process is answering on ${record.probedUrl} — it is NOT this CommandMate server.`,
+        `  CommandMate is listening on ${record.boundUrl} (CM_BIND=${record.bind}).`,
+        `  "localhost" can resolve to ::1 (IPv6) first, and ${record.bind} does not cover ::1,`,
+        '  so a browser opening the localhost URL reaches the other process instead.',
+        `  Open ${record.boundUrl} instead, or free the port:`,
+        `    lsof -nP -iTCP:${record.port} -sTCP:LISTEN`,
+    ];
+}
+/** Directory holding the per-port conflict records */
+function getSelfCheckDir() {
+    return (0, path_1.join)((0, install_context_1.getConfigDir)(), exports.SELF_CHECK_DIR_NAME);
+}
+/**
+ * Path of the record for one port (`<configDir>/logs/self-check-<port>.json`).
+ *
+ * @throws Error when the port is not a plausible TCP port — the value becomes a
+ *   filename, so it is validated rather than interpolated blindly.
+ */
+function getSelfCheckStatePath(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port for self-check state path: ${String(port)}`);
+    }
+    return (0, path_1.join)(getSelfCheckDir(), `${exports.SELF_CHECK_FILE_PREFIX}${port}.json`);
+}
+/**
+ * Persist a conflict for `commandmate status` to read.
+ *
+ * @returns true when the record was written
+ */
+function writeLocalhostConflict(record) {
+    try {
+        const dir = getSelfCheckDir();
+        if (!(0, fs_1.existsSync)(dir)) {
+            (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        }
+        (0, fs_1.writeFileSync)(getSelfCheckStatePath(record.port), `${JSON.stringify(record)}\n`, {
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the conflict recorded for a port.
+ *
+ * Never throws: `status` must keep working on an unreadable, truncated or
+ * hand-edited record, and on a machine where the config dir cannot be resolved at all.
+ *
+ * @returns The record, or null when there is none (or it is unusable)
+ */
+function readLocalhostConflict(port) {
+    try {
+        const statePath = getSelfCheckStatePath(port);
+        if (!(0, fs_1.existsSync)(statePath)) {
+            return null;
+        }
+        const parsed = JSON.parse((0, fs_1.readFileSync)(statePath, 'utf-8'));
+        return isConflictRecord(parsed) && parsed.port === port ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Drop the record for a port. Called on every clean self-check and on shutdown, so a
+ * fixed environment stops warning on the next start rather than needing a manual sweep.
+ */
+function clearLocalhostConflict(port) {
+    try {
+        const statePath = getSelfCheckStatePath(port);
+        if ((0, fs_1.existsSync)(statePath)) {
+            (0, fs_1.unlinkSync)(statePath);
+        }
+    }
+    catch {
+        // Best effort: a stale record is guarded by the PID comparison in `status`.
+    }
+}
+/** Structural check for a record read back off disk */
+function isConflictRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const r = value;
+    return (typeof r.port === 'number' &&
+        typeof r.pid === 'number' &&
+        typeof r.bind === 'string' &&
+        typeof r.boundUrl === 'string' &&
+        typeof r.probedUrl === 'string' &&
+        typeof r.detectedAt === 'string');
+}
+/**
+ * Run the startup self-check and route its verdict to the log and the status file.
+ *
+ * Fail-open by construction: every path is wrapped, the function never rejects, and the
+ * caller in server.ts does not await it. A `null` return means the check could not be
+ * carried out at all — which is reported as nothing, exactly like 'unreachable'.
+ *
+ * @returns The verdict, or null when the check itself failed
+ */
+async function runLocalhostSelfCheck(options) {
+    const { server, port, bind, protocol = 'http', host = exports.SELF_CHECK_HOSTNAME, timeoutMs = exports.SELF_CHECK_TIMEOUT_MS, pid = process.pid, now = () => new Date(), warn = (message) => console.warn(message), probe = probeLocalhostIdentity, } = options;
+    try {
+        const verdict = await probe({ server, port, protocol, host, timeoutMs });
+        if (verdict !== 'foreign') {
+            clearLocalhostConflict(port);
+            return verdict;
+        }
+        const record = {
+            port,
+            pid,
+            bind,
+            boundUrl: formatBoundUrl(protocol, bind, port),
+            probedUrl: `${protocol}://${formatHostForUrl(host)}:${port}`,
+            detectedAt: now().toISOString(),
+        };
+        writeLocalhostConflict(record);
+        for (const line of formatLocalhostConflictWarning(record)) {
+            warn(line);
+        }
+        return verdict;
+    }
+    catch {
+        // A diagnostic must never be the reason a server is considered unhealthy.
+        return null;
+    }
+}

package/dist/server/locales/en/notifications.json

@@ -12,9 +12,28 @@
         "completion": "Also tell me about completions (optional)",
         "completionDesc": "Ordinary completions that need nothing from you. Off by default on newly registered devices (change it for this device here)"
     },
+    "defaultsNotice": {
+        "heading": "What changed in notifications",
+        "completionChanged": "Ordinary completions that need nothing from you are now off by default on newly registered devices. This device is still on, so they keep arriving.",
+        "failuresAdded": "\"When you need to act\" now also covers a failed verification gate, an upstream API fault, and a session that could not start. This device receives those too.",
+        "adopt": "Use the new default (turn completions off)",
+        "keep": "Keep this device as it is",
+        "adopted": "Completions turned off on this device",
+        "kept": "Left this device's settings unchanged"
+    },
     "permission": {
         "denied": "Notifications are blocked in your browser settings. Allow them for this site to receive push notifications."
     },
+    "delivery": {
+        "headingFailing": "This device is not receiving notifications",
+        "headingRemoved": "This device was dropped by the push service",
+        "failing": "The push service has rejected the last {count} notification(s) for this device (HTTP {status}). Your subscription is intact — nothing was deleted.",
+        "failingUnknownStatus": "The push service has rejected the last {count} notification(s) for this device. Your subscription is intact — nothing was deleted.",
+        "removed": "The push service reported this subscription as gone (HTTP {status}), so the server stopped sending to it. Turn notifications on again below to re-subscribe.",
+        "removedUnknownStatus": "The push service reported this subscription as gone, so the server stopped sending to it. Turn notifications on again below to re-subscribe.",
+        "apnsHint": "On iPhone/iPad an HTTP 403 usually means the server's CM_VAPID_SUBJECT is not a contact Apple accepts. See docs/user-guide/webapp-guide.md.",
+        "since": "First failure: {timestamp}"
+    },
     "unsupported": "This browser does not support push notifications.",
     "notConfigured": "Push notifications are not configured on this server. Set the VAPID keys to enable them.",
     "ios": {
@@ -45,7 +64,10 @@
         "failureSessionUnavailable": "Could not start the session: the CLI tool is not installed",
         "failureWithExcerpt": "Failed: {excerpt}",
         "failure": "Failed",
-        "promptResolved": "Handled — answered on another device"
+        "failureAgentSessionWithExcerpt": "The agent stopped with an error: {excerpt}",
+        "failureAgentSession": "The agent stopped with an error",
+        "promptResolved": "Handled — answered on another device",
+        "updateAvailable": "An update for {agent} is available: {version}"
     },
     "escalation": {
         "heading": "Reminder",

package/dist/server/locales/ja/notifications.json

@@ -12,9 +12,28 @@
         "completion": "完了も知らせる（任意）",
         "completionDesc": "対応の要らない正常完了。新しく登録した端末では既定でオフです（この端末の設定はここで変えられます）"
     },
+    "defaultsNotice": {
+        "heading": "通知の既定が変わりました",
+        "completionChanged": "対応の要らない正常完了は、新しく登録した端末では既定でオフになりました。この端末はオンのままなので、これまでどおり届きます。",
+        "failuresAdded": "「対応が必要なとき」に、検証ゲートの不合格・上流APIの障害・セッションの起動失敗の3種が加わりました。この端末はこれらも受け取ります。",
+        "adopt": "新しい既定にする（完了通知をオフ）",
+        "keep": "この端末の設定を保つ",
+        "adopted": "完了通知をこの端末でオフにしました",
+        "kept": "この端末の設定はそのままにしました"
+    },
     "permission": {
         "denied": "ブラウザの設定で通知がブロックされています。このサイトの通知を許可してください。"
     },
+    "delivery": {
+        "headingFailing": "この端末には通知が届いていません",
+        "headingRemoved": "この端末の購読はプッシュサービス側で失効しました",
+        "failing": "直近 {count} 件の通知がプッシュサービスに拒否されました（HTTP {status}）。購読は削除されていません。",
+        "failingUnknownStatus": "直近 {count} 件の通知がプッシュサービスに拒否されました。購読は削除されていません。",
+        "removed": "プッシュサービスがこの購読を失効と報告したため（HTTP {status}）、送信を停止しました。下のボタンで通知を有効にし直すと再購読できます。",
+        "removedUnknownStatus": "プッシュサービスがこの購読を失効と報告したため、送信を停止しました。下のボタンで通知を有効にし直すと再購読できます。",
+        "apnsHint": "iPhone / iPad で HTTP 403 が出る場合、サーバーの CM_VAPID_SUBJECT が Apple の受け付けない値になっていることがほとんどです。docs/user-guide/webapp-guide.md を参照してください。",
+        "since": "最初の失敗: {timestamp}"
+    },
     "unsupported": "このブラウザはプッシュ通知に対応していません。",
     "notConfigured": "このサーバーではプッシュ通知が設定されていません。VAPID鍵を設定すると有効になります。",
     "ios": {
@@ -45,7 +64,10 @@
         "failureSessionUnavailable": "セッションを起動できませんでした: CLI ツールがインストールされていません",
         "failureWithExcerpt": "失敗しました: {excerpt}",
         "failure": "失敗しました",
-        "promptResolved": "対応済みです（他の端末で応答されました）"
+        "failureAgentSessionWithExcerpt": "エージェントがエラーで停止しました: {excerpt}",
+        "failureAgentSession": "エージェントがエラーで停止しました",
+        "promptResolved": "対応済みです（他の端末で応答されました）",
+        "updateAvailable": "{agent} の更新が利用できます: {version}"
     },
     "escalation": {
         "heading": "再通知",