commandmate 0.27.0 → 0.28.0

package/dist/server/src/lib/push/vapid.js

@@ -1,27 +1,286 @@
 "use strict";
 /**
- * VAPID configuration for Web Push (Issue #1125).
+ * VAPID configuration for Web Push, and the one startup check that reports on it
+ * (Issue #1125; the check and the subject rules are Issues #2123 / #2124).
  *
  * Keys are supplied via environment variables and read lazily so tests can vary
  * them and so an unconfigured deployment simply disables push (never crashes).
  * The private key and subject are secrets — never log the returned config.
+ *
+ * ## Why the default subject is an https: URL (Issue #2124)
+ *
+ * The VAPID `sub` claim is the sender's contact, and **Apple validates it**. The
+ * original default, `mailto:commandmate@localhost`, names a domain that cannot
+ * exist, so APNs answered 403 and iOS/iPadOS received nothing while Android kept
+ * working — FCM is permissive about `sub`, so testing on Android alone cannot
+ * see it. Measured by the orchestrator during the Epic #2002 device UAT
+ * (2026-08-27, develop e8d09989), fanning ONE waiting notification to two
+ * devices:
+ *
+ *   Android 10 / Chrome 151 -> FCM   default subject: delivered
+ *   iPad / iPadOS 18.7      -> APNs  default subject: 403, push-send-failed
+ *                                    https://github.com/Kewton/CommandMate: delivered
+ *
+ * This file's author did NOT reproduce that on hardware; the APNs/FCM behaviour
+ * above is quoted from that UAT and is not re-measured here. What IS pinned by
+ * the unit suite is the pure part: which subjects this module accepts and which
+ * it flags, and that the default is one of the accepted ones.
+ *
+ * RFC 8292 §2.1 allows both `mailto:` and `https:` for `sub`, so a project URL
+ * is a conforming default that needs no per-install mailbox.
+ *
+ * ## Why an invalid subject is reported and NOT replaced
+ *
+ * {@link inspectVapidConfig} flags a bad `CM_VAPID_SUBJECT`; {@link getVapidConfig}
+ * still returns it verbatim. Silently substituting the default would make the
+ * warning describe a value the server does not actually send, and would make
+ * `commandmate status` disagree with the wire. The operator set it; they are told
+ * it will be rejected, and startup is never blocked (fail-open, exactly as
+ * `lib/server/localhost-self-check` is).
+ *
+ * ## No `@/` imports here, ever
+ *
+ * `src/cli/commands/status.ts` imports this module so the CLI and the server run
+ * the SAME check, and `tsconfig.cli.json` resets `paths` to `{}` — an alias
+ * import here would break `npm run build:cli`. Same constraint as
+ * `lib/server/localhost-self-check.ts` and `lib/detection/version-probes.ts`.
+ * This module must also stay dependency-free for that reason.
+ *
+ * @module lib/push/vapid
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAPID_ENV_KEYS = exports.VAPID_DEFAULT_SUBJECT = void 0;
+exports.extractVapidSubjectHost = extractVapidSubjectHost;
+exports.classifyVapidSubject = classifyVapidSubject;
+exports.inspectVapidConfig = inspectVapidConfig;
+exports.formatVapidReportLines = formatVapidReportLines;
+exports.runVapidSelfCheck = runVapidSelfCheck;
 exports.getVapidConfig = getVapidConfig;
 exports.isPushConfigured = isPushConfigured;
 exports.getVapidPublicKey = getVapidPublicKey;
-const DEFAULT_SUBJECT = 'mailto:commandmate@localhost';
+/**
+ * Default `sub` claim when `CM_VAPID_SUBJECT` is unset.
+ *
+ * A real, resolvable https: URL — see the module header for the APNs measurement
+ * that made `mailto:commandmate@localhost` the wrong answer (Issue #2124).
+ */
+exports.VAPID_DEFAULT_SUBJECT = 'https://github.com/Kewton/CommandMate';
+/** The three environment variables that configure Web Push. */
+exports.VAPID_ENV_KEYS = {
+    publicKey: 'CM_VAPID_PUBLIC_KEY',
+    privateKey: 'CM_VAPID_PRIVATE_KEY',
+    subject: 'CM_VAPID_SUBJECT',
+};
+/**
+ * Host suffixes that never resolve on the public internet, so a push service can
+ * never verify a `sub` that names one.
+ *
+ * `.example` is here as a *TLD*; `example.com` is an ordinary resolvable domain
+ * and is deliberately NOT rejected (it is the conventional placeholder in every
+ * VAPID tutorial and in this repository's own tests).
+ */
+const NON_ROUTABLE_TLDS = [
+    'local',
+    'localhost',
+    'localdomain',
+    'internal',
+    'intranet',
+    'home',
+    'lan',
+    'test',
+    'invalid',
+    'example',
+];
+/** Loopback / unspecified literals, which are never a contact anyone can reach. */
+function isLoopbackLiteral(host) {
+    if (host === '::1' || host === '0.0.0.0' || host === '::')
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/**
+ * The host a subject names, lowercased, or `null` when it names none.
+ *
+ * `mailto:` takes everything after the LAST `@` (a local part may legally contain
+ * one when quoted) up to the first `?` (RFC 6068 header separator). `https:` is
+ * parsed by `URL`, whose `hostname` already strips the brackets off an IPv6
+ * literal.
+ */
+function extractVapidSubjectHost(subject) {
+    const trimmed = subject.trim();
+    if (/^mailto:/i.test(trimmed)) {
+        const address = trimmed.slice('mailto:'.length).split('?')[0];
+        const at = address.lastIndexOf('@');
+        if (at < 0)
+            return null;
+        const host = address.slice(at + 1).trim().toLowerCase();
+        return host.length > 0 ? host : null;
+    }
+    try {
+        const url = new URL(trimmed);
+        return url.hostname.length > 0 ? url.hostname.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a `sub` claim is one a push service can be expected to accept.
+ *
+ * Deliberately conservative: it rejects only hosts that provably cannot resolve.
+ * A reachable-but-wrong contact (`mailto:nobody@example.com`) is the operator's
+ * business, and a check that guessed at it would warn on healthy installs.
+ *
+ * @param subject - Raw `CM_VAPID_SUBJECT`, or the default.
+ * @returns The problem, or `null` when the subject is usable.
+ */
+function classifyVapidSubject(subject) {
+    const trimmed = subject.trim();
+    if (!/^(mailto:|https:\/\/)/i.test(trimmed))
+        return 'unsupported-scheme';
+    const host = extractVapidSubjectHost(trimmed);
+    if (host === null)
+        return 'missing-host';
+    if (isLoopbackLiteral(host))
+        return 'non-routable-host';
+    // A bare name (`localhost`, `mac-mini`) has no public resolution path.
+    if (!host.includes('.'))
+        return 'non-routable-host';
+    const tld = host.slice(host.lastIndexOf('.') + 1);
+    if (NON_ROUTABLE_TLDS.includes(tld))
+        return 'non-routable-host';
+    return null;
+}
+/**
+ * Read the three variables and say, in one verdict, everything both Issues need
+ * reported: whether push is on at all (#2123) and whether the subject will be
+ * accepted (#2124).
+ *
+ * ONE check, two facts — deliberately not two checks. The startup log, the
+ * `commandmate status` output and the unit suite all consume this one function,
+ * so the two surfaces cannot drift apart.
+ *
+ * Pure: no I/O, no logging, never throws.
+ *
+ * @param env - Environment to read (default: `process.env`). `commandmate status`
+ *   passes the env the *daemon* runs with, which is not this process's own.
+ */
+function inspectVapidConfig(env = process.env) {
+    const publicKey = env[exports.VAPID_ENV_KEYS.publicKey]?.trim() ?? '';
+    const privateKey = env[exports.VAPID_ENV_KEYS.privateKey]?.trim() ?? '';
+    const rawSubject = env[exports.VAPID_ENV_KEYS.subject]?.trim() ?? '';
+    const presentKeys = [];
+    const missingKeys = [];
+    (publicKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.publicKey);
+    (privateKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.privateKey);
+    const subject = rawSubject || exports.VAPID_DEFAULT_SUBJECT;
+    const subjectSource = rawSubject ? 'env' : 'default';
+    const subjectIssue = classifyVapidSubject(subject);
+    if (rawSubject)
+        presentKeys.push(exports.VAPID_ENV_KEYS.subject);
+    const configured = publicKey !== '' && privateKey !== '';
+    const status = configured
+        ? subjectIssue === null
+            ? 'ok'
+            : 'invalid-subject'
+        : publicKey || privateKey
+            ? 'partial'
+            : 'unconfigured';
+    return {
+        status,
+        configured,
+        subject,
+        subjectSource,
+        subjectIssue,
+        presentKeys,
+        missingKeys,
+    };
+}
+/** Human-readable reason for a {@link VapidSubjectIssue}. */
+function describeSubjectIssue(issue) {
+    switch (issue) {
+        case 'unsupported-scheme':
+            return 'it is neither a "mailto:" address nor an "https://" URL (RFC 8292 allows only those two)';
+        case 'missing-host':
+            return 'it names no host at all';
+        case 'non-routable-host':
+            return 'its host cannot be resolved from the public internet (localhost, a bare name, or a reserved TLD)';
+    }
+}
+/**
+ * The startup / `status` report, as lines — shared by both surfaces so they can
+ * never drift apart, exactly as `formatLocalhostConflictWarning` is (#2113).
+ *
+ * **Returns an empty array when the configuration is healthy.** That silence is
+ * the negative control both Issues ask for: a correctly configured server prints
+ * nothing about push, so the presence of a line is itself the signal.
+ *
+ * Never includes a key or a private value. `subject` is printed because it is the
+ * value the operator has to fix, and it is a contact address rather than a
+ * credential — the module header's "never log the config" rule is about the keys.
+ */
+function formatVapidReportLines(inspection) {
+    switch (inspection.status) {
+        case 'ok':
+            return [];
+        case 'unconfigured':
+            return [
+                'Push notifications are disabled: no VAPID keys are configured.',
+                `  Set ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} to enable them.`,
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'partial':
+            return [
+                `Push notifications are disabled: ${inspection.missingKeys.join(' and ')} ${inspection.missingKeys.length > 1 ? 'are' : 'is'} not set.`,
+                `  Both ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} are required;` +
+                    ' a key pair only works as a pair.',
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'invalid-subject':
+            return [
+                `${exports.VAPID_ENV_KEYS.subject}="${inspection.subject}" will be rejected by Apple (APNs):` +
+                    ` ${describeSubjectIssue(inspection.subjectIssue)}.`,
+                '  iPhone/iPad receive nothing while Android keeps working, because FCM does not check it.',
+                `  Use a reachable contact, e.g. ${exports.VAPID_DEFAULT_SUBJECT} or mailto:you@your-domain.example.org.`,
+                `  Unset ${exports.VAPID_ENV_KEYS.subject} to fall back to ${exports.VAPID_DEFAULT_SUBJECT}.`,
+            ];
+    }
+}
+/**
+ * Run the startup self-check and print its verdict, or nothing when healthy.
+ *
+ * Fail-open by construction, the same contract `runLocalhostSelfCheck` carries:
+ * it never throws, it never blocks `listen`, and a healthy install is silent.
+ *
+ * @returns The inspection, or `null` when the check itself could not be carried
+ *   out (which is reported as nothing at all).
+ */
+function runVapidSelfCheck(options = {}) {
+    const { env = process.env, warn = (message) => console.warn(message) } = options;
+    try {
+        const inspection = inspectVapidConfig(env);
+        for (const line of formatVapidReportLines(inspection)) {
+            warn(line);
+        }
+        return inspection;
+    }
+    catch {
+        // A diagnostic must never be the reason a server fails to start.
+        return null;
+    }
+}
 /**
  * Returns the VAPID config, or null when push is not configured (both public
  * and private keys must be present). Read from env on every call.
  */
 function getVapidConfig() {
-    const publicKey = process.env.CM_VAPID_PUBLIC_KEY?.trim();
-    const privateKey = process.env.CM_VAPID_PRIVATE_KEY?.trim();
+    const publicKey = process.env[exports.VAPID_ENV_KEYS.publicKey]?.trim();
+    const privateKey = process.env[exports.VAPID_ENV_KEYS.privateKey]?.trim();
     if (!publicKey || !privateKey) {
         return null;
     }
-    const subject = process.env.CM_VAPID_SUBJECT?.trim() || DEFAULT_SUBJECT;
+    const subject = process.env[exports.VAPID_ENV_KEYS.subject]?.trim() || exports.VAPID_DEFAULT_SUBJECT;
     return { publicKey, privateKey, subject };
 }
 /** True when both VAPID keys are configured. */

package/dist/server/src/lib/push/waiting-push-notifier.js

@@ -152,6 +152,13 @@ function handleWaitingTransition(transition) {
         // way #1790 already does for the opening one. Fire-and-forget: the notifier
         // never rejects, and the `void` keeps the synchronous listener contract
         // `emit` relies on.
+        //
+        // Issue #2057: what reaches here is bounded by `waiting-episode-state`,
+        // which is in memory. A `waiting: false` poll on an instance this process
+        // never saw waiting emits nothing at all, so a wait that ended while the
+        // server was down produces no closing edge and no resolution — durable card
+        // marks do not change that, and it is the limitation §6.2 of the design
+        // note records rather than one this module can close.
         void (0, resolution_push_notifier_1.notifyPromptResolved)({
             worktreeId: transition.worktreeId,
             agentName: transition.instanceId ?? transition.cliToolId,

package/dist/server/src/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;
+    }
+}