commandmate 0.27.1 → 0.29.0

package/dist/server/server.js

@@ -433,8 +433,98 @@ app.prepare().then(() => {
     server.listen(port, hostname, async () => {
         console.log(`> Ready on ${protocol}://${hostname}:${port}`);
         console.log(`> WebSocket server ready`);
+        // Issue #2113: verify that the URL the documentation advertises
+        // (`http://localhost:<port>`) actually reaches THIS process. It does not when
+        // another process holds `::1:<port>`: `localhost` resolves ::1 before 127.0.0.1
+        // on macOS, and neither a 127.0.0.1 nor a 0.0.0.0 bind covers ::1. The user's
+        // browser then talks to the squatter while we keep printing "Ready".
+        //
+        // Deliberately NOT awaited and wrapped in its own catch: a diagnostic must never
+        // delay or block a successful `listen`. `runLocalhostSelfCheck` is fail-open in
+        // its own right (it resolves `null` rather than throwing) and warns only on the
+        // one actionable verdict — see src/lib/server/localhost-self-check.ts.
+        //
+        // Dynamic import for the same reason as every reconciler below: adding a module
+        // graph to server.ts's eval-time graph perturbs Next's AsyncLocalStorage bootstrap
+        // under `tsx server.ts` and kills the first request that compiles middleware. Do
+        // not hoist this.
+        void (async () => {
+            try {
+                const selfCheck = await Promise.resolve().then(() => __importStar(require('./src/lib/server/localhost-self-check')));
+                clearStartupSelfCheckState = () => selfCheck.clearLocalhostConflict(port);
+                await selfCheck.runLocalhostSelfCheck({
+                    server,
+                    port,
+                    bind: hostname,
+                    protocol: protocol === 'https' ? 'https' : 'http',
+                });
+            }
+            catch (error) {
+                console.error('Startup self-check failed:', error);
+            }
+        })();
+        // Issue #2123 / #2124: say, in one line, whether Web Push can work at all.
+        // Unconfigured VAPID keys disable push silently (correct fail-safe, wrong
+        // ergonomics: the reader observes only "no notifications ever arrive"), and
+        // a `CM_VAPID_SUBJECT` Apple will not accept silences iPhone/iPad while
+        // Android keeps working. ONE check reports both — see src/lib/push/vapid.ts.
+        //
+        // A healthy configuration prints NOTHING, which is what makes the presence
+        // of a line meaningful. Same contract as the localhost self-check above:
+        // fail-open, never blocks `listen`. `commandmate status` runs the same
+        // function over the env the daemon was started with, so the two surfaces
+        // cannot drift.
+        //
+        // Dynamic import for the same reason as every reconciler here: adding a
+        // module graph to server.ts's eval-time graph perturbs Next's
+        // AsyncLocalStorage bootstrap under `tsx server.ts`. Do not hoist this.
+        void (async () => {
+            try {
+                const { runVapidSelfCheck } = await Promise.resolve().then(() => __importStar(require('./src/lib/push/vapid')));
+                runVapidSelfCheck();
+            }
+            catch (error) {
+                console.error('VAPID self-check failed:', error);
+            }
+        })();
         // Initialize worktrees after server starts
         await initializeWorktrees();
+        // Issue #2108: re-open the event streams of opencode panes that outlived
+        // the last process. The port each one's server listens on is in
+        // `~/.commandmate/opencode-ports.json`, and until this call nothing read it
+        // at startup: the only chain that reached `recoverOpencodePort` was a
+        // *launch*, and a restart does not launch anything — `POST /send` skips
+        // `startSession` while the pane is running. The result was a server that
+        // was alive and reachable while every HTTP surface answered
+        // `409 NO_OPENCODE_PORT`, with the terminal view still working because the
+        // screen scraper never needed the port.
+        //
+        // Deliberately NOT awaited. The sweep's cost is a health probe per live
+        // pane, and a pane whose server has died pays a timeout for it; the
+        // managers below must not queue behind that. It is fail-open in its own
+        // right (it never rejects) and the `try`/`catch` below is belt-and-braces.
+        //
+        // Runs after `initializeWorktrees()` because the ingest path this
+        // re-subscribes reaches `@/lib/db` at event time and the migrations above
+        // are what make that table set current.
+        //
+        // Dynamic import for the same reason as every reconciler above: adding this
+        // module graph to server.ts's eval-time graph perturbs Next's
+        // AsyncLocalStorage bootstrap under `tsx server.ts` and the first request
+        // that compiles middleware then dies. Do not hoist this.
+        void (async () => {
+            try {
+                const { reattachOpencodeEventStreams } = await Promise.resolve().then(() => __importStar(require('./src/lib/hooks/sources/opencode/reattach')));
+                const report = await reattachOpencodeEventStreams();
+                if (report.candidates > 0) {
+                    console.log(`opencode streams reattached: ${report.reattached}/${report.candidates} ` +
+                        `live pane(s) (persisted=${report.persisted} skipped=${report.skipped})`);
+                }
+            }
+            catch (error) {
+                console.error('Error reattaching opencode event streams:', error);
+            }
+        })();
         // Issue #1623: reconcile the `prefix+g` reading-mode binding on the user's
         // tmux server. Fail-open in its own try/catch — a convenience key must never
         // be able to stop the server from serving.
@@ -462,6 +552,12 @@ app.prepare().then(() => {
     });
     // Graceful shutdown with timeout
     let isShuttingDown = false;
+    /**
+     * Issue #2113: drop this port's localhost-conflict record on the way out, so a
+     * resolved conflict cannot outlive the server that observed it. Assigned once the
+     * self-check module has loaded; null until then, and never awaited.
+     */
+    let clearStartupSelfCheckState = null;
     function gracefulShutdown(signal) {
         if (isShuttingDown) {
             console.log('Shutdown already in progress, forcing exit...');
@@ -469,6 +565,13 @@ app.prepare().then(() => {
         }
         isShuttingDown = true;
         console.log(`${signal} received: shutting down...`);
+        // Issue #2113: best-effort, never fatal.
+        try {
+            clearStartupSelfCheckState?.();
+        }
+        catch {
+            // A leftover record is harmless: `status` only reports one whose PID matches.
+        }
         // Stop polling first
         (0, response_poller_1.stopAllPolling)();
         // Issue #138: Stop all auto-yes pollers

package/dist/server/src/config/auth-config.js

@@ -35,6 +35,11 @@ exports.AUTH_EXCLUDED_PATHS = [
     '/api/auth/login',
     '/api/auth/logout',
     '/api/auth/status',
+    // Issue #1937 (R5): one-shot pairing-code exchange for `commandmate remote`.
+    // The pairing SCREEN is '/login' above, driven by a '#code=' fragment, so
+    // this is the only entry the remote feature adds. Handler:
+    // src/app/api/remote/pair/route.ts (it authenticates the code itself).
+    '/api/remote/pair',
     // Issue #1124 (PWA): non-sensitive resources that must stay reachable before
     // auth so the app is installable and the offline fallback can be precached.
     // All carry no user data (app metadata / public SW code / static fallback).

package/dist/server/src/config/image-extensions.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Image Extensions Configuration
+ * [SF-001] Configuration for image file extensions
+ * [Stage 3 SF-001] isImageExtension() function for extension validation
+ *
+ * This module defines which file extensions are recognized as images
+ * and provides security validation for image files.
+ *
+ * Security features:
+ * - Extension whitelist
+ * - Magic bytes validation for binary formats
+ * - SVG XSS prevention (script tags, event handlers, dangerous URIs, foreignObject)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACHABLE_IMAGE_ACCEPT = exports.ATTACHABLE_IMAGE_EXTENSIONS = exports.IMAGE_EXTENSION_VALIDATORS = exports.IMAGE_MAX_SIZE_BYTES = exports.IMAGE_EXTENSIONS = void 0;
+exports.normalizeExtension = normalizeExtension;
+exports.getMimeTypeByExtension = getMimeTypeByExtension;
+exports.isImageExtension = isImageExtension;
+exports.validateImageMagicBytes = validateImageMagicBytes;
+exports.validateWebPMagicBytes = validateWebPMagicBytes;
+exports.validateSvgContent = validateSvgContent;
+exports.validateImageContent = validateImageContent;
+/**
+ * List of supported image file extensions
+ * All extensions must include the leading dot
+ */
+exports.IMAGE_EXTENSIONS = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.svg',
+];
+/**
+ * Maximum image file size in bytes (20MB)
+ * [SF-001] Named with _BYTES suffix for clarity, matching existing patterns
+ */
+exports.IMAGE_MAX_SIZE_BYTES = 20 * 1024 * 1024;
+/**
+ * Validators for each supported image extension
+ * Includes magic bytes for binary format verification
+ */
+exports.IMAGE_EXTENSION_VALIDATORS = [
+    {
+        extension: '.png',
+        mimeType: 'image/png',
+        magicBytes: [0x89, 0x50, 0x4E, 0x47],
+    },
+    {
+        extension: '.jpg',
+        mimeType: 'image/jpeg',
+        magicBytes: [0xFF, 0xD8, 0xFF],
+    },
+    {
+        extension: '.jpeg',
+        mimeType: 'image/jpeg',
+        magicBytes: [0xFF, 0xD8, 0xFF],
+    },
+    {
+        extension: '.gif',
+        mimeType: 'image/gif',
+        magicBytes: [0x47, 0x49, 0x46, 0x38],
+    },
+    {
+        extension: '.webp',
+        mimeType: 'image/webp',
+        magicBytes: [0x52, 0x49, 0x46, 0x46],
+    },
+    {
+        extension: '.svg',
+        mimeType: 'image/svg+xml',
+        // SVG is text-based, no magic bytes
+    },
+];
+/**
+ * [DRY] Normalize file extension to include leading dot and lowercase
+ * Extracted to avoid code duplication across validation functions
+ *
+ * @param ext - File extension with or without leading dot
+ * @returns Normalized extension with leading dot in lowercase (e.g., '.png')
+ */
+function normalizeExtension(ext) {
+    if (!ext)
+        return '';
+    return ext.startsWith('.') ? ext.toLowerCase() : '.' + ext.toLowerCase();
+}
+/**
+ * [DRY] Get MIME type for an image extension
+ * Centralized MIME type lookup to avoid duplication
+ *
+ * @param ext - File extension with or without leading dot
+ * @returns MIME type string, or 'application/octet-stream' if not found
+ */
+function getMimeTypeByExtension(ext) {
+    const normalizedExt = normalizeExtension(ext);
+    const validator = exports.IMAGE_EXTENSION_VALIDATORS.find(v => v.extension === normalizedExt);
+    return validator?.mimeType || 'application/octet-stream';
+}
+/**
+ * Check if a file extension is a supported image format
+ * [SF-003] Handles dot normalization for API compatibility
+ *
+ * @param ext - File extension with or without leading dot
+ * @returns True if the extension is a supported image format
+ */
+function isImageExtension(ext) {
+    if (!ext)
+        return false;
+    const normalizedExt = normalizeExtension(ext);
+    return exports.IMAGE_EXTENSIONS.includes(normalizedExt);
+}
+/**
+ * Validate image file magic bytes
+ * [SF-003] Handles dot normalization
+ * [DRY] Uses normalizeExtension helper
+ *
+ * @param extension - File extension with or without leading dot
+ * @param buffer - File content buffer
+ * @returns True if magic bytes match the expected format
+ */
+function validateImageMagicBytes(extension, buffer) {
+    const normalizedExt = normalizeExtension(extension);
+    const validator = exports.IMAGE_EXTENSION_VALIDATORS.find(v => v.extension === normalizedExt);
+    if (!validator?.magicBytes) {
+        // SVG is text-based, no magic bytes to validate
+        return normalizedExt === '.svg';
+    }
+    const offset = validator.magicBytesOffset || 0;
+    // Check if buffer is long enough
+    if (buffer.length < offset + validator.magicBytes.length) {
+        return false;
+    }
+    return validator.magicBytes.every((byte, index) => buffer[offset + index] === byte);
+}
+/**
+ * Validate WebP magic bytes completely
+ * [SEC-SF-004] Checks both RIFF header and WEBP signature
+ *
+ * @param buffer - File content buffer
+ * @returns True if both RIFF header and WEBP signature are present
+ */
+function validateWebPMagicBytes(buffer) {
+    // RIFF header check (offset 0-3)
+    const riffHeader = [0x52, 0x49, 0x46, 0x46];
+    const hasRiff = riffHeader.every((byte, i) => buffer[i] === byte);
+    if (!hasRiff) {
+        return false;
+    }
+    // WEBP signature check (offset 8-11)
+    if (buffer.length < 12) {
+        return false;
+    }
+    const webpSignature = [0x57, 0x45, 0x42, 0x50];
+    return webpSignature.every((byte, i) => buffer[8 + i] === byte);
+}
+/**
+ * Validate SVG content for security
+ * [SEC-MF-001] Event handler detection
+ * [SEC-MF-002] Dangerous URI scheme detection
+ * [SEC-MF-003] foreignObject element detection
+ *
+ * This function serves two purposes:
+ * 1. SVG format validation: Ensures the content is valid SVG
+ * 2. Security validation: Detects XSS attack vectors
+ *
+ * @param content - SVG file content as string
+ * @returns Validation result with error message if invalid
+ */
+function validateSvgContent(content) {
+    // [Format validation] Check for SVG tag or XML declaration
+    if (!content.includes('<svg') && !content.startsWith('<?xml')) {
+        return { valid: false, error: 'Invalid SVG format' };
+    }
+    // [Security 1] Script tag detection (XSS prevention)
+    if (/<script[\s>]/i.test(content)) {
+        return { valid: false, error: 'SVG contains script tags' };
+    }
+    // [Security 2] Event handler attribute detection (SEC-MF-001)
+    // Matches: onload, onclick, onmouseover, onerror, onfocus, etc.
+    // Example attack: <svg onload="alert('XSS')">
+    if (/\s+on\w+\s*=/i.test(content)) {
+        return { valid: false, error: 'SVG contains event handler attributes' };
+    }
+    // [Security 3] Dangerous URI scheme detection (SEC-MF-002)
+    // Matches: href="javascript:...", xlink:href="data:...", href="vbscript:..."
+    // Example attack: <a xlink:href="javascript:alert('XSS')">
+    if (/(?:xlink:)?href\s*=\s*["']?\s*(?:javascript|data|vbscript):/i.test(content)) {
+        return { valid: false, error: 'SVG contains dangerous URI scheme' };
+    }
+    // [Security 4] foreignObject element detection (SEC-MF-003)
+    // foreignObject can embed arbitrary HTML including scripts
+    // Example attack: <foreignObject><body><script>...</script></body></foreignObject>
+    if (/<foreignObject[\s>]/i.test(content)) {
+        return { valid: false, error: 'SVG contains foreignObject element' };
+    }
+    return { valid: true };
+}
+/**
+ * Attachable image extensions (SVG excluded for XSS prevention)
+ * Issue #474: Used for image attachment file selection dialog
+ * [S1-S3] DRY: Single source of truth for attachable image extensions
+ */
+exports.ATTACHABLE_IMAGE_EXTENSIONS = exports.IMAGE_EXTENSIONS.filter((ext) => ext !== '.svg');
+/**
+ * File selection dialog accept attribute value for image attachments
+ * Issue #474: Generated from ATTACHABLE_IMAGE_EXTENSIONS for DRY compliance
+ * [DRY] Uses getMimeTypeByExtension instead of direct validator lookup
+ * Format: comma-separated MIME types (e.g., 'image/png,image/jpeg,...')
+ */
+exports.ATTACHABLE_IMAGE_ACCEPT = exports.ATTACHABLE_IMAGE_EXTENSIONS
+    .map((ext) => getMimeTypeByExtension(ext))
+    .filter((mime) => mime !== 'application/octet-stream')
+    .join(',');
+/**
+ * Validate image content comprehensively
+ * [SF-002] Combines size, magic bytes, and SVG security validation
+ * [DRY] Uses normalizeExtension helper
+ *
+ * @param extension - File extension with or without leading dot
+ * @param buffer - File content buffer
+ * @returns Validation result with error message if invalid
+ */
+function validateImageContent(extension, buffer) {
+    // File size validation
+    if (buffer.length > exports.IMAGE_MAX_SIZE_BYTES) {
+        return {
+            valid: false,
+            error: `File size exceeds ${exports.IMAGE_MAX_SIZE_BYTES / 1024 / 1024}MB limit`,
+        };
+    }
+    const normalizedExt = normalizeExtension(extension);
+    // SVG requires special validation (text-based, XSS concerns)
+    if (normalizedExt === '.svg') {
+        const content = buffer.toString('utf-8');
+        return validateSvgContent(content);
+    }
+    // Binary formats require magic bytes validation
+    if (!validateImageMagicBytes(extension, buffer)) {
+        return { valid: false, error: 'Invalid image magic bytes' };
+    }
+    return { valid: true };
+}

package/dist/server/src/config/opencode-constants.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * opencode `run` option constants (Issue #2044)
+ *
+ * The CMATE.md CLI Tool column can now say more than `opencode --model x`:
+ * `--agent`, `--variant`, `--continue` and `--title` all reach `opencode run`.
+ * The values are user-authored text in a Markdown cell that becomes argv, so
+ * each one needs a bound before it is handed to `execFile`.
+ *
+ * ## Why a separate pattern from Copilot's
+ *
+ * `MODEL_NAME_PATTERN` (`copilot-constants.ts`) allows `/` and `:` because a
+ * model id is `provider/model` and can carry a tag (`ollama/qwen3:8b`). An
+ * `--agent` or `--variant` value is neither: measured against opencode 1.18.22,
+ * the built-in agents are `build` / `plan` and the documented variants are
+ * `high` / `max` / `minimal` — bare words. Reusing the model pattern would
+ * accept `plan/../../etc` and call it an agent name.
+ *
+ * The leading-alphanumeric requirement is the same rule and the same reason as
+ * DR4-001: a value starting with `-` would be read by the CLI as another option
+ * rather than as this one's argument.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_RUN_JSON_EVENT_TYPES = exports.MAX_OPENCODE_TITLE_LENGTH = exports.MAX_OPENCODE_RUN_NAME_LENGTH = exports.OPENCODE_RUN_NAME_PATTERN = void 0;
+/**
+ * Allowed shape for `--agent` and `--variant` values.
+ *
+ * Leading alphanumeric (DR4-001), then word characters, `.`, `_` and `-`.
+ * Deliberately no `/` and no `:` — see the module comment.
+ */
+exports.OPENCODE_RUN_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9\-._]*$/;
+/**
+ * Longest `--agent` / `--variant` value accepted.
+ *
+ * Generous next to the measured vocabulary (`build`, `plan`, `high`, `max`,
+ * `minimal`) because opencode lets a project define its own agents in
+ * `opencode.json`, and this layer has no way to enumerate them.
+ */
+exports.MAX_OPENCODE_RUN_NAME_LENGTH = 64;
+/**
+ * Longest `--title` value accepted.
+ *
+ * 200 to match what `agent-session-telemetry.ts` keeps of a session title
+ * (`MAX_AGENT_SESSION_TITLE_LENGTH`), so a title CommandMate wrote survives the
+ * round trip back through `structuredEvents.session` without being reported as
+ * truncated. Not imported from there: that module is `lib/hooks` and this one is
+ * read by the client-safe CMATE.md parser.
+ */
+exports.MAX_OPENCODE_TITLE_LENGTH = 200;
+/**
+ * The event `type` values `opencode run --format json` emits on stdout.
+ *
+ * Measured on 1.18.22 in an isolated `HOME` (see
+ * `docs/design/opencode-server-live-verification.md` §15): a plain prompt gives
+ * `step_start` / `text` / `step_finish`; a prompt that uses a tool adds
+ * `tool_use`; a run that fails gives a single `error` frame **on stdout** with
+ * an empty stderr and exit 1.
+ *
+ * This list is documentation, not a filter — {@link extractOpencodeFinalText}
+ * matches on `text` and `error` and ignores everything else, so an event word
+ * added by a later opencode release cannot break extraction.
+ */
+exports.OPENCODE_RUN_JSON_EVENT_TYPES = [
+    'step_start',
+    'text',
+    'tool_use',
+    'step_finish',
+    'error',
+];

package/dist/server/src/config/tmux-pane-config.js

@@ -17,7 +17,8 @@
  * so `capture-pane` cost / render load stays reasonable.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TMUX_HISTORY_LIMIT = exports.OPENCODE_PANE_HEIGHT = exports.TUI_PANE_WIDTH = exports.TUI_PANE_HEIGHT = void 0;
+exports.OPENCODE_PANE_WIDTH_MAX = exports.OPENCODE_PANE_WIDTH_MIN = exports.OPENCODE_PANE_WIDTH_ENV = exports.OPENCODE_SIDEBAR_MIN_WIDTH = exports.OPENCODE_PANE_WIDTH = exports.TMUX_HISTORY_LIMIT = exports.OPENCODE_PANE_HEIGHT = exports.TUI_PANE_WIDTH = exports.TUI_PANE_HEIGHT = void 0;
+exports.resolveOpencodePaneWidth = resolveOpencodePaneWidth;
 /** Fixed pane height (rows) for TUI sessions. Large enough to retain useful history. */
 exports.TUI_PANE_HEIGHT = 1000;
 /** Fixed pane width (columns) for TUI sessions. Matches the historical default. */
@@ -71,3 +72,101 @@ exports.OPENCODE_PANE_HEIGHT = 200;
  * 1977/2000 lines used, i.e. actively losing transcript).
  */
 exports.TMUX_HISTORY_LIMIT = 20000;
+/**
+ * Default OpenCode tmux pane width (columns) — Issue #2047.
+ *
+ * ## Why 80 is a measurement and not a leftover
+ *
+ * `launchSession()` in `lib/cli-tools/opencode.ts` used to spell this `80`
+ * inline, twice, with the comment "hide sidebar for clean capture-pane output".
+ * #2047 measured what that comment is worth on opencode 1.18.22, and it is
+ * load-bearing: **opencode paints a right-hand sidebar at 121 columns and wider,
+ * and hides it at 120 and narrower.** The boundary was walked one column at a
+ * time on a live TUI and is reproducible in both directions (see
+ * `docs/design/opencode-server-live-verification.md` §21).
+ *
+ * The sidebar is not a separate region of the capture. It shares ROWS with the
+ * transcript, so at >=121 columns every captured line is
+ * `<transcript text> … <sidebar text>` and the detection layer reads both as one
+ * row. Measured consequences at 200 columns, on frames captured from the same
+ * session as their 80/120 counterparts:
+ *
+ * - `sliceOpenCodeTurn()` + `cleanOpenCodeResponse()` saved the sidebar as the
+ *   assistant's reply (`8,501 tokens / $0.00 spent / LSP / LSPs are disabled`)
+ *   for a turn whose real reply extracted to the empty string at 80 and 120.
+ * - `detectSessionStatus` flipped `ready`/`opencode_response_complete` to
+ *   `running`/`unknown_frame` on an aborted turn, because the sidebar rows push
+ *   the previous turn's `▣ … · 36.1s` out of branch D's content window.
+ * - `OPENCODE_IDLE_COMPOSER_PATTERN` false-matched, because the sidebar prints
+ *   the session TITLE on a row that already carries the transcript gutter — so
+ *   `^\s*┃\s*Ask anything\.\.\.` matches a title, not a composer.
+ *
+ * At 120 columns all 13 measured frames produced byte-identical verdicts to 80.
+ * **120 is therefore the measured safe ceiling, and the default stays 80** —
+ * #2047's acceptance condition was "raise the default only if 200 is green",
+ * and 200 is not.
+ *
+ * @see OPENCODE_SIDEBAR_MIN_WIDTH
+ * @see resolveOpencodePaneWidth
+ */
+exports.OPENCODE_PANE_WIDTH = 80;
+/**
+ * The narrowest pane width at which opencode 1.18.22 paints its right-hand
+ * sidebar (Issue #2047, measured — 120 hides it, 121 shows it, walked one column
+ * at a time and reproduced in both directions).
+ *
+ * Anything at or above this width interleaves sidebar text into transcript rows,
+ * which is what {@link OPENCODE_PANE_WIDTH}'s docblock lists the damage from.
+ * `lib/cli-tools/opencode.ts` warns when an operator's
+ * `CM_OPENCODE_PANE_WIDTH` lands here or above.
+ */
+exports.OPENCODE_SIDEBAR_MIN_WIDTH = 121;
+/** Environment variable that overrides {@link OPENCODE_PANE_WIDTH}. */
+exports.OPENCODE_PANE_WIDTH_ENV = 'CM_OPENCODE_PANE_WIDTH';
+/**
+ * Bounds accepted for {@link OPENCODE_PANE_WIDTH_ENV}.
+ *
+ * The floor is opencode's own layout: its input box plus gutter needs room, and
+ * below ~40 columns the footer rows the detector anchors on wrap into each
+ * other. The ceiling is a guard against a typo (`8000`) resizing a pane to
+ * something tmux will accept and every `capture-pane` will then pay for — a
+ * 200-row frame already grows from ~2.5 KB at 80 columns to ~40 KB at 200
+ * because of the sidebar's background painting (measured, #2047 §21).
+ */
+exports.OPENCODE_PANE_WIDTH_MIN = 40;
+/** @see OPENCODE_PANE_WIDTH_MIN */
+exports.OPENCODE_PANE_WIDTH_MAX = 400;
+/**
+ * Resolve the pane width a new or reconnected opencode session is sized to.
+ *
+ * Read at CALL time rather than at module load so a process can be started with
+ * the variable set without import-order deciding whether it is seen, and so
+ * tests can drive it without module-registry surgery.
+ *
+ * A value that is not a base-10 integer, or that falls outside
+ * [{@link OPENCODE_PANE_WIDTH_MIN}, {@link OPENCODE_PANE_WIDTH_MAX}], is ignored
+ * in favour of {@link OPENCODE_PANE_WIDTH}: a malformed override must never
+ * produce a pane no detector has ever been measured against. Callers that want
+ * to tell the operator their value was dropped compare the result against what
+ * they passed in.
+ *
+ * @param env - Environment to read. Defaults to `process.env` where there is one.
+ * @returns Pane width in columns.
+ */
+function resolveOpencodePaneWidth(env = typeof process === 'undefined'
+    ? undefined
+    : process.env) {
+    const raw = env?.[exports.OPENCODE_PANE_WIDTH_ENV];
+    if (raw === undefined)
+        return exports.OPENCODE_PANE_WIDTH;
+    const trimmed = raw.trim();
+    // `Number()` accepts '0x50', '1e2' and '' — none of which an operator means by
+    // a column count, and all of which would silently resize a real pane.
+    if (!/^\d+$/.test(trimmed))
+        return exports.OPENCODE_PANE_WIDTH;
+    const parsed = Number.parseInt(trimmed, 10);
+    if (parsed < exports.OPENCODE_PANE_WIDTH_MIN || parsed > exports.OPENCODE_PANE_WIDTH_MAX) {
+        return exports.OPENCODE_PANE_WIDTH;
+    }
+    return parsed;
+}