commandmate 0.30.2 → 0.31.1

package/dist/server/src/lib/tmux/session-hooks.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Server side of Issue #2317's session-scoped hooks and geometry hand-back.
+ *
+ * Two jobs, both keyed off one session name:
+ *
+ *  - {@link ensureSessionHooks} reconciles the two OPT-IN `client-attached`
+ *    hooks (Phase C's auto popup, Phase D's delegate-on-hand-attach) with what
+ *    the environment asks for. Like #1623's key binding it CONVERGES: turning an
+ *    option off removes the hook a previous run installed, rather than merely
+ *    not installing it again.
+ *  - {@link reconcileDelegatedGeometry} is the safety net the Issue asked a
+ *    `client-detached` hook to be. tmux 3.5a does not fire that hook
+ *    session-scoped (measured — see the table in `live-attach.ts`), so the
+ *    restore runs from the status poll instead: every couple of seconds, for
+ *    every session, "is this delegated while no human is looking at it?".
+ *
+ * Nothing here throws. All of it hangs off the status poll and off session
+ * creation, and neither may be failed by a convenience feature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSessionHooks = ensureSessionHooks;
+exports.reconcileDelegatedGeometry = reconcileDelegatedGeometry;
+exports.forgetSessionHooks = forgetSessionHooks;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const session_hook_scripts_1 = require("./session-hook-scripts");
+const geometry_delegation_1 = require("./geometry-delegation");
+const logger_1 = require("../logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const logger = (0, logger_1.createLogger)('tmux-session-hooks');
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+const ensured = globalThis.__cmEnsuredSessionHooks ?? (globalThis.__cmEnsuredSessionHooks = new Set());
+/**
+ * Reconcile a session's opt-in `client-attached` hooks with the environment.
+ *
+ * Runs once per session per process; call it freely. Both hooks are removed when
+ * their option is off, so `CM_READ_MODE_AUTO_POPUP=on` followed by a restart
+ * without it leaves no hook behind.
+ *
+ * @param sessionName - Target session
+ */
+async function ensureSessionHooks(sessionName) {
+    if (!(0, tmux_session_surface_1.isCommandMateSession)(sessionName))
+        return;
+    if (ensured.has(sessionName))
+        return;
+    ensured.add(sessionName);
+    try {
+        if ((0, tmux_session_surface_1.isLiveAttachHookEnabled)() && (0, tmux_session_surface_1.isLiveAttachEligibleSession)(sessionName)) {
+            // The restore script rides along with the delegate one: a user whose
+            // server is down needs the manual way back, and materializing it here is
+            // the only moment we know the delegate path is in use at all.
+            (0, session_hook_scripts_1.materializeLiveRestoreScript)();
+            const args = (0, tmux_session_surface_1.buildInstallDelegateHookArgs)(sessionName, (0, session_hook_scripts_1.materializeLiveDelegateScript)());
+            if (args)
+                await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        else {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildRemoveDelegateHookArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        if ((0, tmux_session_surface_1.isAutoPopupEnabled)()) {
+            const args = (0, tmux_session_surface_1.buildInstallAutoPopupHookArgs)(sessionName, (0, session_hook_scripts_1.materializeAutoPopupScript)());
+            if (args)
+                await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        else {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildRemoveAutoPopupHookArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+    }
+    catch (error) {
+        logger.debug('session-hooks:reconcile-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Take a delegated session's geometry back when no human is attached.
+ *
+ * The Phase D safety net. Restores unconditionally once the two conditions hold,
+ * because the sequence is idempotent — a session already at `manual` 200x1000
+ * with no `@cm_delegated` is left byte-identical by it.
+ *
+ * Also self-healing for a flag left behind by a CLI that was killed: the flag
+ * alone never keeps a window unpinned, because this runs whenever nobody is
+ * looking.
+ *
+ * @param sessionName - Target session
+ * @returns true when the geometry was handed back by this call
+ */
+async function reconcileDelegatedGeometry(sessionName) {
+    try {
+        if (!(await (0, geometry_delegation_1.isGeometryDelegated)(sessionName)))
+            return false;
+        if (await (0, geometry_delegation_1.hasHumanClientAttached)(sessionName))
+            return false;
+        for (const args of (0, tmux_session_surface_1.buildRestoreGeometryCommands)(sessionName)) {
+            await execFileAsync('tmux', args, { timeout: TMUX_TIMEOUT });
+        }
+        logger.info('session-hooks:geometry-restored', { sessionName });
+        return true;
+    }
+    catch (error) {
+        logger.debug('session-hooks:geometry-restore-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/** Forget a session's hook bookkeeping — call when it is known to be gone. */
+function forgetSessionHooks(sessionName) {
+    ensured.delete(sessionName);
+    (0, geometry_delegation_1.forgetGeometryDelegation)(sessionName);
+}

package/dist/server/src/lib/tmux/session-status-options.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Phase B of Issue #2317: publish the session's state ONTO the tmux session.
+ *
+ * Before this module, `running` / `waiting` / `ready` / `idle` existed only
+ * inside CommandMate. `tmux ls` showed a name and a window count, an attached
+ * status line showed tmux's stock clock, and an operator who wanted to know what
+ * an agent was doing had to open the web UI or run `commandmate ls`. Two writes
+ * per transition fix that:
+ *
+ *  - **user options** (`@cm_status` and friends) — readable without attaching:
+ *    `tmux ls -F '#{session_name} #{@cm_status}'`;
+ *  - **a session-scoped `status-right`** — readable while attached, rendered
+ *    from those same options so the line updates without being rewritten.
+ *
+ * ## Everything here is session-scoped, and that is the point
+ *
+ * `set-option -t <session>` writes the SESSION's option table. The tmux server's
+ * global table — which every session on the machine inherits, including ones
+ * CommandMate knows nothing about — is never touched, and
+ * `tests/unit/tmux/session-status-options-2317.test.ts` asserts that by
+ * inspecting the argv of every call this module makes. #1623's `bind-key` is the
+ * one global mutation CommandMate makes and it is not made here.
+ *
+ * ## Writes happen on TRANSITION, not on every poll
+ *
+ * `GET /api/worktrees` probes every tool of every worktree every couple of
+ * seconds. Setting five options on each of those polls would be a few hundred
+ * `execFile` round-trips a minute for a value that changes a few times an hour,
+ * so {@link publishSessionStatus} keeps the last published tuple per session and
+ * returns without touching tmux when nothing moved. The memo is keyed by session
+ * name and dropped by {@link forgetSessionStatus} when the session goes away.
+ *
+ * ## The opt-out converges, without a startup hook
+ *
+ * `CM_TMUX_STATUS=off` does not merely stop writing: the first status poll after
+ * the restart REMOVES the `@cm_*` options and the CommandMate `status-right`
+ * from each session it visits, once per session. That is the same "an opt-out
+ * that uninstalls" contract #1623 gave `CM_READ_MODE`, and it is done from the
+ * poll rather than from a startup sweep for two reasons — the poll already knows
+ * which sessions exist (a sweep would have to ask tmux again), and it keeps this
+ * feature from needing a wire into `server.ts`, whose startup path is
+ * deliberately a single dynamic import per module graph.
+ *
+ * ## Nothing here may ever throw
+ *
+ * This is a convenience surface hanging off the status poll. A tmux hiccup must
+ * not be able to fail the poll that the sidebar, `commandmate ls` and the header
+ * chip all read, so every entry point swallows its errors and logs at debug.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishSessionStatus = publishSessionStatus;
+exports.ensureSessionStatusLine = ensureSessionStatusLine;
+exports.clearSessionStatus = clearSessionStatus;
+exports.forgetSessionStatus = forgetSessionStatus;
+exports.publishedSessionCount = publishedSessionCount;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const logger_1 = require("../logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const logger = (0, logger_1.createLogger)('tmux-session-status');
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+const published = globalThis.__cmPublishedTmuxStatus ??
+    (globalThis.__cmPublishedTmuxStatus = new Map());
+/** Sessions this process has already uninstalled the surface from. */
+const cleared = globalThis.__cmClearedTmuxStatus ?? (globalThis.__cmClearedTmuxStatus = new Set());
+/**
+ * Write one session's state onto its tmux session, if it changed.
+ *
+ * @param publication - Session identity plus the status word to publish
+ * @returns What was done, for tests and for the caller's logging
+ */
+async function publishSessionStatus(publication) {
+    const { sessionName, worktreeId, cliToolId, instanceId, status } = publication;
+    if (!(0, tmux_session_surface_1.isTmuxStatusEnabled)()) {
+        // The uninstall path. Once per session per process: `clearSessionStatus`
+        // issues six `execFile` calls, and repeating them on every poll of a server
+        // that has the surface turned off would be the cost the feature was turned
+        // off to avoid.
+        if (!cleared.has(sessionName)) {
+            cleared.add(sessionName);
+            await clearSessionStatus(sessionName);
+        }
+        return 'disabled';
+    }
+    const previous = published.get(sessionName);
+    if (previous &&
+        previous.status === status &&
+        previous.worktreeId === worktreeId &&
+        previous.cliToolId === cliToolId &&
+        previous.instanceId === instanceId) {
+        return 'unchanged';
+    }
+    const updated = (publication.now ?? new Date()).toISOString();
+    const writes = [
+        [tmux_session_surface_1.CM_STATUS_OPTION, status],
+        [tmux_session_surface_1.CM_WORKTREE_OPTION, worktreeId],
+        [tmux_session_surface_1.CM_TOOL_OPTION, cliToolId],
+        [tmux_session_surface_1.CM_INSTANCE_OPTION, instanceId],
+        [tmux_session_surface_1.CM_UPDATED_OPTION, updated],
+    ];
+    try {
+        for (const [option, value] of writes) {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildSetSessionOptionArgs)(sessionName, option, value), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        published.set(sessionName, { status, worktreeId, cliToolId, instanceId });
+        // The line renders FROM the options above, so it is installed after them —
+        // a status-right referencing `#{@cm_status}` on a session that has none
+        // paints an empty pair of brackets until the first write lands.
+        await ensureSessionStatusLine(sessionName);
+        return 'written';
+    }
+    catch (error) {
+        // A session that was killed between the poll and this write is the ordinary
+        // case, not an incident. Drop the memo so the next live session under the
+        // same name republishes rather than being deduped against a dead one.
+        published.delete(sessionName);
+        logger.debug('session-status:write-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 'error';
+    }
+}
+/**
+ * Install the session-scoped `status-right`, unless the session already has one.
+ *
+ * "Already has one" means a SESSION-scoped value, which is exactly what
+ * `show-options -t <session> status-right` reports: measured on tmux 3.5a, a
+ * session that never set it answers with empty stdout (the global value is not
+ * echoed), and one that did answers `status-right "…"`. So a user who
+ * customised this session in `.tmux.conf` — or who set it by hand — keeps their
+ * line, and everyone else gets CommandMate's.
+ *
+ * Idempotent: once installed, the value contains {@link CM_STATUS_RIGHT_FORMAT}
+ * and is recognised as ours, so a restart re-installs nothing.
+ *
+ * @param sessionName - Target session
+ * @returns true when the line is CommandMate's after this call
+ */
+async function ensureSessionStatusLine(sessionName) {
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildShowSessionOptionArgs)(sessionName, 'status-right'), { timeout: TMUX_TIMEOUT });
+        const existing = stdout.trim();
+        if (existing !== '' && !existing.includes(tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT)) {
+            logger.debug('session-status:status-right-user-owned', { sessionName, existing });
+            return false;
+        }
+        if (existing === '') {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildSetStatusRightArgs)(sessionName, tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT), { timeout: TMUX_TIMEOUT });
+        }
+        return true;
+    }
+    catch (error) {
+        logger.debug('session-status:status-right-failed', {
+            sessionName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Remove every `@cm_*` option and the session-scoped `status-right` we own.
+ *
+ * The `status-right` is only removed when it is still ours — a user who rebound
+ * it after us owns it now, and clobbering that would be the same rudeness
+ * {@link ensureSessionStatusLine} exists to avoid.
+ *
+ * @param sessionName - Target session
+ */
+async function clearSessionStatus(sessionName) {
+    published.delete(sessionName);
+    for (const option of tmux_session_surface_1.CM_SESSION_OPTIONS) {
+        try {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildUnsetSessionOptionArgs)(sessionName, option), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+        catch {
+            // Unsetting an option that was never set exits non-zero on some builds.
+        }
+    }
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildShowSessionOptionArgs)(sessionName, 'status-right'), { timeout: TMUX_TIMEOUT });
+        if (stdout.includes(tmux_session_surface_1.CM_STATUS_RIGHT_FORMAT)) {
+            await execFileAsync('tmux', (0, tmux_session_surface_1.buildUnsetStatusRightArgs)(sessionName), {
+                timeout: TMUX_TIMEOUT,
+            });
+        }
+    }
+    catch {
+        // Same reasoning as above: nothing here may fail a caller.
+    }
+}
+/**
+ * Forget a session's published state without touching tmux.
+ *
+ * Called when a session is known to be gone. The next session created under the
+ * same name then publishes from scratch instead of being deduped against the
+ * dead one's last status.
+ */
+function forgetSessionStatus(sessionName) {
+    published.delete(sessionName);
+    cleared.delete(sessionName);
+}
+/** Test seam: how many sessions currently have a memoised publication. */
+function publishedSessionCount() {
+    return published.size;
+}

package/dist/server/src/lib/tmux/tmux.js

@@ -4,7 +4,7 @@
  * Provides functions to manage tmux sessions for Claude CLI integration
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = void 0;
+exports.REPAINT_INVALIDATE_DELAY_MS = exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = void 0;
 exports.exactTarget = exactTarget;
 exports.reconcileSessionGeometry = reconcileSessionGeometry;
 exports.isTmuxAvailable = isTmuxAvailable;
@@ -28,6 +28,7 @@ exports.sendSpecialKeysAndInvalidate = sendSpecialKeysAndInvalidate;
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const tmux_capture_cache_1 = require("./tmux-capture-cache");
+const geometry_delegation_1 = require("./geometry-delegation");
 const validation_1 = require("../../lib/cli-tools/validation");
 const tmux_pane_config_1 = require("../../config/tmux-pane-config");
 const logger_1 = require("../../lib/logger");
@@ -77,6 +78,24 @@ function exactTarget(sessionName) {
  * Failures are intentionally non-fatal: geometry improves capture fidelity but
  * must never make an otherwise healthy CLI session unusable.
  *
+ * ## It stands down while a human is attached (Issue #2317, Phase D)
+ *
+ * `commandmate attach --live` hands the window to the terminal looking at it so
+ * the transcript is readable at all; every `send` to a running session reaches
+ * here through `reconcileExistingSession()`, and snapping the canvas back to
+ * 200x1000 mid-read would undo that under the reader's hands. So when the
+ * geometry does NOT already match, this asks whether a NON-control-mode client
+ * is attached and leaves the window alone if one is.
+ *
+ * Two properties of that ordering are load-bearing:
+ *
+ *  - the question is asked only on the path that would actually resize, so the
+ *    overwhelmingly common "already correct" call still costs exactly the two
+ *    tmux round-trips it always has;
+ *  - it keys off a live client rather than off `@cm_delegated`, so a flag left
+ *    behind by a CLI that was killed can never pin a window open forever — the
+ *    next reconcile with nobody attached repairs it.
+ *
  * @returns true when at least one tmux option was changed.
  */
 async function reconcileSessionGeometry(sessionName, options = {}) {
@@ -103,6 +122,13 @@ async function reconcileSessionGeometry(sessionName, options = {}) {
     const sizeMatches = currentWidth === windowWidth && currentHeight === windowHeight;
     if (modeMatches && sizeMatches)
         return false;
+    // Issue #2317: a human is reading this pane at their terminal's size. See the
+    // docblock — asked here, after the cheap match, so the ordinary call is
+    // unchanged.
+    if ((options.respectAttachedClient ?? true) && (await (0, geometry_delegation_1.hasHumanClientAttached)(sessionName))) {
+        logger.info('session-geometry:delegated-to-client', { sessionName });
+        return false;
+    }
     try {
         if (!modeMatches) {
             await execFileAsync('tmux', ['set-window-option', '-t', target, 'window-size', 'manual'], { timeout: DEFAULT_TIMEOUT });
@@ -316,7 +342,13 @@ async function createSession(sessionNameOrOptions, cwd) {
         // replaced (verified: `show-window-options -v window-size` came back empty),
         // so reconciling first would have the setting thrown away and leave the pane
         // tracking the latest client again.
-        await reconcileSessionGeometry(sessionName, { windowWidth, windowHeight });
+        await reconcileSessionGeometry(sessionName, {
+            windowWidth,
+            windowHeight,
+            // Nothing can be attached to a session this call is still creating, so the
+            // Phase D client probe would be a round-trip with one possible answer.
+            respectAttachedClient: false,
+        });
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -433,6 +465,20 @@ const ALLOWED_SPECIAL_KEYS = new Set([
     // are tmux named keys; 'q' is the pager's literal "quit" character (sent verbatim by
     // `tmux send-keys`, no injection risk — single fixed char via execFile, not a shell).
     'PageUp', 'PageDown', 'Home', 'End', 'q',
+    // Issue #2254: the answer characters `1`-`9` / `y` / `n`, so a dialog nobody
+    // could parse can be answered from the chat surface's dialog card instead of
+    // only from the terminal. Literal characters on the wire like `q` above.
+    // `n` was already deliverable as an opencode chord letter and is not repeated.
+    '1', '2', '3', '4', '5', '6', '7', '8', '9', 'y',
+    // Issue #2297: claude's "use this session only" key. Its `/model` footer reads
+    // `Enter to set as default · s to use this session only · Esc to cancel`, and
+    // `Enter` there rewrites `model` in ~/.claude/settings.json (#1495) — so
+    // without this the chat surface could deliver the destructive half of that
+    // footer and not the safe half. A literal character like `q` / `y` above.
+    // Deliverable here for every session; only claude and Command Code DECLARE it
+    // (`CLAUDE_NAVIGATION_KEY_VALUES`), so the route answers 400 for anyone else —
+    // which matters, because `s` is `sort:relevance` on copilot's session picker.
+    's',
     // Issue #2046: opencode's own chords. `C-x` is its leader prefix (measured
     // default of 1.18.22, 2000 ms window), `C-p` opens the command palette and
     // `C-t` cycles the model variant. The lower-case letters complete a leader
@@ -802,6 +848,36 @@ async function clearComposerLine(sessionName) {
 function isAllowedSpecialKey(key, vocabulary = terminal_keys_1.NAVIGATION_KEY_VALUES) {
     return vocabulary.includes(key) && isSendableSpecialKey(key);
 }
+/**
+ * How long after a key lands the TUI is still allowed to be repainting
+ * (Issue #2297).
+ *
+ * `invalidateCache()` fires the instant `tmux send-keys` returns, which is
+ * BEFORE the CLI has drawn the consequence of the key. The next capture — the
+ * chat surface's own `onKeysSent` refresh, or any of the pollers that share this
+ * cache (the sidebar status probe, the global session poller) — therefore has a
+ * good chance of storing the PRE-repaint frame, and {@link CACHE_TTL_MS} then
+ * serves that stale frame for five seconds. That is the "the highlight does not
+ * move" report in Issue #2297: the send worked, the cache was invalidated, and
+ * the surface still drew the old dialog.
+ *
+ * 250 ms is comfortably past an ink/bubbletea repaint (`SPECIAL_KEY_DELAY_MS`,
+ * the gap this transport already leaves BETWEEN keys of one chord, is 100 ms)
+ * and comfortably inside the 1-second budget the Issue sets for seeing the
+ * highlight move.
+ */
+exports.REPAINT_INVALIDATE_DELAY_MS = 250;
+/**
+ * Drop the cached frame again once the TUI has had time to repaint.
+ *
+ * Fire-and-forget on purpose: the route must not wait 250 ms to answer, and the
+ * work is one `Map.delete`. The timer is `unref()`ed where the runtime supports
+ * it so a pending invalidation can never hold a process (or a test runner) open.
+ */
+function scheduleRepaintInvalidation(sessionName) {
+    const timer = setTimeout(() => (0, tmux_capture_cache_1.invalidateCache)(sessionName), exports.REPAINT_INVALIDATE_DELAY_MS);
+    timer.unref?.();
+}
 /**
  * Send special keys to a tmux session and invalidate the capture cache.
  * Wrapper combining sendSpecialKeys() + invalidateCache() for DRY (DR1-003).
@@ -812,4 +888,5 @@ function isAllowedSpecialKey(key, vocabulary = terminal_keys_1.NAVIGATION_KEY_VA
 async function sendSpecialKeysAndInvalidate(sessionName, keys) {
     await sendSpecialKeys(sessionName, keys);
     (0, tmux_capture_cache_1.invalidateCache)(sessionName);
+    scheduleRepaintInvalidation(sessionName);
 }

package/dist/server/src/lib/version-checker.js

@@ -20,12 +20,15 @@ exports.isNewerVersion = isNewerVersion;
 exports.getClientVersion = getClientVersion;
 exports.getServerVersion = getServerVersion;
 exports.getCurrentVersion = getCurrentVersion;
+exports.getServedBundleVersion = getServedBundleVersion;
+exports.resolveBundleDrift = resolveBundleDrift;
 exports.validateReleaseUrl = validateReleaseUrl;
 exports.sanitizeReleaseName = sanitizeReleaseName;
 exports.checkForUpdate = checkForUpdate;
 exports.resetCacheForTesting = resetCacheForTesting;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const types_1 = require("../lib/realtime/types");
 // =============================================================================
 // Constants
 // =============================================================================
@@ -60,6 +63,17 @@ const FETCH_TIMEOUT_MS = 5000;
  * project directory) leaking a foreign version.
  */
 const PACKAGE_NAME = 'commandmate';
+/**
+ * The manifest `next build` writes beside the client bundle, relative to the
+ * package root. [Issue #2271]
+ *
+ * It snapshots the *resolved* next.config — the `env` block included — so
+ * `config.env.NEXT_PUBLIC_APP_VERSION` is literally the string that build
+ * inlined into every browser bundle it emitted. That makes it the only file on
+ * disk that can answer "which version is the bundle we are serving?" without
+ * asking the bundle itself.
+ */
+const NEXT_BUILD_MANIFEST_PATH = ['.next', 'required-server-files.json'];
 const cache = globalThis.__versionCheckCache ??
     (globalThis.__versionCheckCache = {
         result: null,
@@ -162,6 +176,99 @@ function getServerVersion() {
 function getCurrentVersion() {
     return getServerVersion();
 }
+// =============================================================================
+// Served bundle identity (Issue #2271)
+// =============================================================================
+/**
+ * Memoised answer of {@link getServedBundleVersion}, resolved on first use and
+ * then frozen for the life of the process. [Issue #2271]
+ *
+ * Frozen on purpose. The question is "which build is this process serving?",
+ * and a running Next production server answers that once — at startup, from the
+ * `.next` it opened. Re-reading the manifest on every call would let a
+ * `next build` performed *underneath* the running server rename the served
+ * build without the server having reloaded a single byte of it, which is the
+ * false positive this Issue exists to remove, in a new disguise.
+ */
+let servedBundleVersion = null;
+/**
+ * Read the version `next build` inlined into the client bundle, from the build
+ * manifest it left on disk. [Issue #2271]
+ *
+ * @returns The baked version, or null when the manifest is absent, unreadable,
+ *   malformed, or predates the `env` block.
+ */
+function readServedBundleVersionFromBuild() {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), ...NEXT_BUILD_MANIFEST_PATH), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const baked = parsed.config?.env?.NEXT_PUBLIC_APP_VERSION;
+        if (typeof baked === 'string' && baked.length > 0)
+            return baked;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** First-use resolution behind {@link getServedBundleVersion}'s memo. */
+function resolveServedBundleVersion() {
+    // `next dev` compiles on demand and never writes the build manifest, but a
+    // stale one left by an earlier `npm run build` is still sitting in `.next` —
+    // and it names a version the dev bundle was never built from. Under dev the
+    // live next.config populates `process.env` for the server too, so the baked
+    // value already *is* the honest answer and the manifest must not be consulted.
+    if (process.env.NODE_ENV === 'production') {
+        const built = readServedBundleVersionFromBuild();
+        if (built)
+            return built;
+    }
+    return getClientVersion();
+}
+/**
+ * The version of the **client bundle this server is serving**. [Issue #2271]
+ *
+ * Deliberately *not* {@link getServerVersion}. That one reads package.json at
+ * runtime, which is the right answer for "is there a newer release on GitHub?"
+ * and the wrong one for "should this tab reload?": the release procedure bumps
+ * package.json on `develop` and never rebuilds the primary checkout (doing so
+ * would swap `.next` out from under the running server — see the release
+ * skill's Phase 2-3), so `package.json > bundle` is the steady state after
+ * every release. Comparing against it therefore told **every** tab, forever,
+ * that it was out of date.
+ *
+ * The honest comparand is the build the bundle came from, so this reads the
+ * `next build` manifest and falls back — never to package.json — to the baked
+ * `NEXT_PUBLIC_APP_VERSION`, and finally to `'0.0.0'`, which
+ * {@link isVersionMismatch} treats as "unknown" and never reports as drift.
+ *
+ * @returns Served bundle version string (e.g., "0.2.3"), or "0.0.0" as fallback
+ */
+function getServedBundleVersion() {
+    servedBundleVersion ??= resolveServedBundleVersion();
+    return servedBundleVersion;
+}
+/**
+ * Decide whether a tab running `clientBundleVersion` is on a stale build.
+ * [Issue #2271]
+ *
+ * The single seam the WebSocket version handshake calls, so "what counts as
+ * drift" has exactly one definition and one place to test it. Both sides are
+ * build identities: the client sends the `NEXT_PUBLIC_APP_VERSION` its bundle
+ * was compiled with, and this compares it against the version of the bundle
+ * being served — so a bare `package.json` bump moves neither side, and only a
+ * rebuild does.
+ *
+ * @param clientBundleVersion - The version the tab's bundle was built from
+ * @returns The drifted pair, or null when the two builds agree or either side
+ *   is an unknown/fallback version
+ */
+function resolveBundleDrift(clientBundleVersion) {
+    const serverVersion = getServedBundleVersion();
+    if (!(0, types_1.isVersionMismatch)(serverVersion, clientBundleVersion))
+        return null;
+    return { serverVersion, clientVersion: clientBundleVersion };
+}
 /**
  * Validate that a URL is a legitimate GitHub Releases URL.
  * [SEC-SF-001] OWASP A03:2021 - Prevents injection via DNS pollution/MITM.
@@ -259,6 +366,9 @@ function resetCacheForTesting() {
     cache.result = null;
     cache.fetchedAt = 0;
     cache.rateLimitResetAt = null;
+    // Issue #2271: the served-bundle memo is frozen for the life of a process, so
+    // a suite that moves process.cwd() between cases must be able to thaw it.
+    servedBundleVersion = null;
 }
 // =============================================================================
 // Internal Functions

package/dist/server/src/lib/ws-server.js

@@ -426,28 +426,34 @@ function handleMessage(ws, message) {
     }
 }
 /**
- * Handle a client-version hello (#1338/#1356).
+ * Handle a client-version hello (#1338/#1356/#2271).
  *
- * The client announces its baked bundle version on every (re)connect. If the
- * server's actually-running version (runtime package.json, resolved by
- * getServerVersion) has drifted from it, reply with a version_mismatch event so
- * the tab can surface a reload nudge. Stays silent when the versions match or
- * either side is an unknown/fallback version (受入条件: 誤検知しない).
+ * The client announces the version its bundle was built from on every
+ * (re)connect. `resolveBundleDrift` compares that against the version of the
+ * bundle **this server is serving** and answers null unless the two builds
+ * really differ; on drift, reply with a version_mismatch event so the tab can
+ * surface a reload nudge.
+ *
+ * Issue #2271: this used to ask `getServerVersion()`, i.e. the installed
+ * package.json. Releases bump that file without rebuilding the running server's
+ * `.next` — by design — so the comparison was permanently unequal and every tab
+ * carried an undismissable banner. The resolver, not this handler, is where
+ * "what counts as drift" is defined; keep it that way.
  */
 function handleClientVersion(ws, message) {
     const clientVersion = typeof message.version === 'string' ? message.version : '';
     if (!clientVersion)
         return;
-    const serverVersion = (0, version_checker_1.getServerVersion)();
-    if (!(0, types_2.isVersionMismatch)(serverVersion, clientVersion))
+    const drift = (0, version_checker_1.resolveBundleDrift)(clientVersion);
+    if (!drift)
         return;
     if (ws.readyState !== ws_1.WebSocket.OPEN)
         return;
     try {
         ws.send(JSON.stringify({
             type: types_2.VERSION_MISMATCH_EVENT_TYPE,
-            serverVersion,
-            clientVersion,
+            serverVersion: drift.serverVersion,
+            clientVersion: drift.clientVersion,
         }));
     }
     catch (error) {