commandmate 0.27.1 → 0.28.0

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;
+}

package/dist/server/src/lib/cli-tools/base.js

@@ -3,39 +3,6 @@
  * Base implementation for CLI tools
  * Provides common functionality for all CLI tool implementations
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCLITool = void 0;
 const child_process_1 = require("child_process");
@@ -45,6 +12,8 @@ const tmux_1 = require("../tmux/tmux");
 const composer_spec_1 = require("./composer-spec");
 const capture_spec_1 = require("./capture-spec");
 const graceful_exit_1 = require("./graceful-exit");
+const start_availability_1 = require("./start-availability");
+const terminal_keys_1 = require("../../types/terminal-keys");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 /**
  * Abstract base class for CLI tools
@@ -105,18 +74,15 @@ class BaseCLITool {
      * nothing left to remember: implement {@link launchSession} and the reporting
      * is already wired.
      *
-     * ## Fire-and-forget, and a deferred import
-     *
-     * The notification is NOT awaited. Web push fans out to every registered
-     * device, and holding a 503 open for that would make a failed start slower to
-     * report than a successful one. `notifySessionStartFailurePush` contains its
-     * own failures, and the `.catch` here is the belt for the import itself.
+     * ## Where the reporting itself lives
      *
-     * `await import()` rather than a static import, for the reason Issue #1984
-     * gives on `CLIToolManager.stopPollers`: `push/failure-push-notifier` pulls
-     * the database and `web-push` behind it, and every one of the seven tool
-     * modules loads THIS file. Deferring it to the failure path keeps the
-     * cli-tools graph the size #1984 cut it down to.
+     * In `./start-availability` (Issue #2022), not inline here. It is still the
+     * only line in the repository that calls `notifySessionStartFailurePush`, and
+     * it is still fire-and-forget behind an `await import()` for the reasons that
+     * module's docblock spells out. It moved so that a caller which never creates
+     * a tmux session — Assistant Chat, which spawns `claude -p` directly and so
+     * never reaches this method — can report through the same one窓口 instead of
+     * opening a second.
      *
      * @param worktreeId - Worktree ID
      * @param worktreePath - Worktree path
@@ -129,14 +95,12 @@ class BaseCLITool {
             await this.launchSession(worktreeId, worktreePath, instanceId, model);
         }
         catch (error) {
-            void Promise.resolve().then(() => __importStar(require('../push/failure-push-notifier'))).then(({ notifySessionStartFailurePush }) => notifySessionStartFailurePush({
+            (0, start_availability_1.reportSessionStartFailure)({
                 worktreeId,
                 cliToolId: this.id,
                 instanceId,
                 toolName: this.name,
-                error,
-            }))
-                .catch(() => { });
+            }, error);
             throw error;
         }
     }
@@ -191,5 +155,26 @@ class BaseCLITool {
     captureSpec() {
         return (0, capture_spec_1.resolveCaptureSpec)(this.id);
     }
+    /**
+     * Declare the keys this tool's terminal UI may send (Issue #2046).
+     *
+     * The default IS the pre-#2046 global list, verbatim: the twelve navigation
+     * keys plus the codex pager's `q` that `NAVIGATION_KEY_VALUES` has published
+     * since #1017, and no leader. claude / codex / copilot / gemini / antigravity
+     * / vibe-local all take it unchanged, which is the point of putting it here
+     * rather than copying a literal into six classes — there is no per-tool list
+     * to drift, so "the six existing tools' key sets did not change" is true by
+     * construction and not merely by review.
+     * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` asserts it
+     * against `NAVIGATION_KEY_VALUES` anyway, because a future edit could still
+     * add an override to one of the six.
+     *
+     * opencode overrides it. Nothing else does.
+     *
+     * @returns This tool's {@link NavigationKeySpec}
+     */
+    navigationKeys() {
+        return { keys: terminal_keys_1.NAVIGATION_KEY_VALUES, leaderKey: null };
+    }
 }
 exports.BaseCLITool = BaseCLITool;

package/dist/server/src/lib/cli-tools/opencode-config.js

@@ -21,11 +21,23 @@
  *
  * | layer                                   | read? | on a key collision |
  * |-----------------------------------------|-------|--------------------|
+ * | `$OPENCODE_CONFIG_CONTENT`              | yes   | **beats all four below** (#2053) |
  * | `<worktree>/opencode.jsonc`             | yes   | beats `opencode.json` |
  * | `<worktree>/opencode.json`              | yes   | beats both below   |
  * | `$OPENCODE_CONFIG`                      | yes   | **loses** to the worktree file |
  * | `$XDG_CONFIG_HOME/opencode/opencode.json(c)` | yes | loses to the worktree file |
  *
+ * Issue #2053 re-measured the same way on 1.18.22 and added the top row: an
+ * inline JSON config handed over in `OPENCODE_CONFIG_CONTENT` outranks every
+ * file, `opencode.jsonc` included. It is not a write target either — #2053
+ * measured that injecting a `permission` block through it silently replaces the
+ * operator's own (a string `permission.bash` is *replaced*, not merged, by an
+ * object, turning `"ask"` into the default `allow`), and that rule order beats
+ * pattern specificity, so a broad glob from CommandMate defeats an exact-match
+ * rule the operator wrote. Details and the ruling:
+ * `docs/design/opencode-server-live-verification.md` §26 /
+ * `docs/design/agent-event-source-interface.md` §3.4.
+ *
  * `provider` maps merge across the layers, so the generated file is additive
  * *until* the operator defines the same provider key somewhere else — at which
  * point CommandMate's snapshot silently outranks the config they chose,