commandmate 0.26.0 → 0.27.0

package/dist/server/src/lib/cli-tools/graceful-exit.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * How each tool is asked to quit, and what must be true once it has
+ * (Issue #1933, 受入条件 S10 / §13.2).
+ *
+ * ## The postcondition, and why "the pane is gone" is not all of it
+ *
+ * Every `killSession()` in this package ends with `tmux kill-session`, so the
+ * pane always disappears and every shutdown has always *looked* successful.
+ * Two failures hide inside that:
+ *
+ *  - **`graceful_exit_timeout`** — the TUI never quit and the pane was
+ *    destroyed under it. Recoverable (the process dies with the pane) but worth
+ *    reporting, because a tool that stops honouring its own exit command is
+ *    otherwise invisible: `COPILOT_EXIT_WAIT_MS` had to be raised from 500 to
+ *    3000 in #1905 precisely because every sample of copilot 1.0.80's shutdown
+ *    (1.006 s … 2.193 s) was past the generic window, i.e. the tmux kill had
+ *    been landing mid-shutdown for every copilot session, silently.
+ *  - **`port_orphaned`** — opencode's TUI *is* an HTTP server once it is given
+ *    `--port` (#1758 §5.1.2), and `lib/hooks/sources/opencode/ports` hands the
+ *    number to the next instance that asks. If the server outlives the pane,
+ *    that next instance's subscription attaches to the OLD server: its events
+ *    are then filed against the wrong worktree, with no error anywhere. The
+ *    port is only safe to reuse once `/global/health` stops answering.
+ *
+ * {@link verifyGracefulExit} is the check, with both probes injected so it can
+ * be driven without tmux and without a socket.
+ *
+ * ## What this module deliberately does NOT do
+ *
+ * It does not execute {@link GracefulExitSpec.keys}. The seven `killSession()`
+ * implementations keep sending their own measured sequences, and
+ * `tests/unit/cli-tools/graceful-exit-conformance-1933.test.ts` pins that what
+ * they actually send equals what they declare here. Routing them through a
+ * shared executor would change the argv of calls that
+ * `tests/unit/api/kill-session-cli-tool-gateway-1905.test.ts` pins by exact
+ * arity — a file outside this Issue's scope — for no behavioural gain: the exit
+ * strings (`/exit`, `/quit`) are tool-owned constants, not tmux key names, so
+ * `-l` changes not one byte for them. The user-typed message body, which is the
+ * string that *does* change, went through `-l` in this same commit.
+ *
+ * @module lib/cli-tools/graceful-exit
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRACEFUL_EXIT_SPEC = exports.GEMINI_EXIT_COMMAND_TEXT = exports.OPENCODE_EXIT_COMMAND_TEXT = exports.COPILOT_EXIT_COMMAND_TEXT = void 0;
+exports.resolveGracefulExitSpec = resolveGracefulExitSpec;
+exports.verifyGracefulExit = verifyGracefulExit;
+const copilot_constants_1 = require("../../config/copilot-constants");
+const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
+const cli_tool_contracts_1 = require("../../types/cli-tool-contracts");
+/** The graceful exit command copilot's TUI accepts. */
+exports.COPILOT_EXIT_COMMAND_TEXT = '/exit';
+/** The graceful exit command opencode's TUI accepts. */
+exports.OPENCODE_EXIT_COMMAND_TEXT = '/exit';
+/** The graceful exit command gemini's TUI accepts. */
+exports.GEMINI_EXIT_COMMAND_TEXT = '/quit';
+/**
+ * A literal whose Enter is part of the same tmux write.
+ *
+ * `send-keys -t X '/quit' 'C-m'` and `send-keys -t X -l -- '/quit\r'` put the
+ * identical six bytes (`2f 71 75 69 74 0d`) into the pty in one write —
+ * measured on tmux 3.5a, private socket, `cat` on a raw pty. So a tool that
+ * still batches its exit command is described faithfully by a single literal
+ * step ending in CR, and nothing has to be modelled as "a literal that is
+ * secretly not literal".
+ */
+function submittedLiteral(text, delayAfterMs) {
+    return (0, cli_tool_contracts_1.literalStep)(`${text}\r`, delayAfterMs);
+}
+/**
+ * The claude-shaped default, which is also `BaseCLITool`'s: one Ctrl-D, then
+ * the generic TUI shutdown window.
+ */
+exports.DEFAULT_GRACEFUL_EXIT_SPEC = {
+    keys: [(0, cli_tool_contracts_1.keyStep)('C-d')],
+    exitWaitMs: cli_tool_timing_config_1.TUI_EXIT_WAIT_MS,
+    ownsLoopbackServer: false,
+};
+/**
+ * Per-tool exit descriptions.
+ *
+ * Every sequence is what the tool's `killSession()` already sends; the
+ * conformance suite is what keeps that true.
+ */
+const GRACEFUL_EXIT_SPECS = {
+    claude: exports.DEFAULT_GRACEFUL_EXIT_SPEC,
+    codex: exports.DEFAULT_GRACEFUL_EXIT_SPEC,
+    antigravity: exports.DEFAULT_GRACEFUL_EXIT_SPEC,
+    // Ctrl-C to abandon anything running, a settle, then `/quit` submitted in one
+    // write (gemini is the one tool still on the pre-#1471 batched form).
+    gemini: {
+        keys: [
+            (0, cli_tool_contracts_1.keyStep)('C-c', cli_tool_timing_config_1.TUI_INTERRUPT_SETTLE_MS),
+            submittedLiteral(exports.GEMINI_EXIT_COMMAND_TEXT),
+        ],
+        exitWaitMs: cli_tool_timing_config_1.TUI_EXIT_WAIT_MS,
+        ownsLoopbackServer: false,
+    },
+    // Two Ctrl-Cs: the first interrupts, the second exits.
+    'vibe-local': {
+        keys: [(0, cli_tool_contracts_1.keyStep)('C-c', cli_tool_timing_config_1.TUI_INTERRUPT_SETTLE_MS), (0, cli_tool_contracts_1.keyStep)('C-c')],
+        exitWaitMs: cli_tool_timing_config_1.TUI_EXIT_WAIT_MS,
+        ownsLoopbackServer: false,
+    },
+    // Ctrl-C, then `/exit` typed and submitted as SEPARATE tmux commands. The
+    // 3000 ms window is copilot's own: every measured shutdown of 1.0.80 (1.006 /
+    // 1.109 / … / 2.193 s) is past the generic 500 (#1905).
+    copilot: {
+        keys: [
+            (0, cli_tool_contracts_1.keyStep)('C-c', cli_tool_timing_config_1.TUI_INTERRUPT_SETTLE_MS),
+            (0, cli_tool_contracts_1.literalStep)(exports.COPILOT_EXIT_COMMAND_TEXT, copilot_constants_1.COPILOT_TEXT_INPUT_DELAY_MS),
+            (0, cli_tool_contracts_1.keyStep)('Enter'),
+        ],
+        exitWaitMs: cli_tool_timing_config_1.COPILOT_EXIT_WAIT_MS,
+        ownsLoopbackServer: false,
+    },
+    // `/exit` typed and submitted separately, because the batched form does not
+    // exit at all: typing `/` opens the command palette and the `C-m` arriving in
+    // the same tmux command is consumed by it, leaving `/exit` in the composer
+    // 10.8 s later, 2 runs out of 2 (#1905).
+    opencode: {
+        keys: [
+            (0, cli_tool_contracts_1.literalStep)(exports.OPENCODE_EXIT_COMMAND_TEXT, cli_tool_timing_config_1.TUI_TEXT_INPUT_WAIT_MS),
+            (0, cli_tool_contracts_1.keyStep)('Enter'),
+        ],
+        exitWaitMs: cli_tool_timing_config_1.OPENCODE_EXIT_WAIT_MS,
+        ownsLoopbackServer: true,
+    },
+};
+/**
+ * The graceful-exit description for a CLI tool.
+ *
+ * @param cliToolId - CLI tool identifier
+ * @returns That tool's {@link GracefulExitSpec}
+ */
+function resolveGracefulExitSpec(cliToolId) {
+    return GRACEFUL_EXIT_SPECS[cliToolId] ?? exports.DEFAULT_GRACEFUL_EXIT_SPEC;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Decide whether a graceful exit met its postcondition.
+ *
+ * Order matters and is not arbitrary: the session is checked first because a
+ * live pane makes the port question meaningless, and the port is checked only
+ * after the pane is gone because that is the only moment "still answering"
+ * means "orphaned".
+ *
+ * The default is a SINGLE check with no polling, which is byte-for-byte what
+ * every `killSession()` already did after its own `exitWaitMs` sleep. A caller
+ * that wants the tool given more rope passes `attempts` / `intervalMs`.
+ *
+ * @param probe - How to observe the session and the port
+ * @returns `{ ok: true }`, or the reason the postcondition failed
+ */
+async function verifyGracefulExit(probe) {
+    const attempts = Math.max(1, probe.attempts ?? 1);
+    const intervalMs = probe.intervalMs ?? 0;
+    const sleep = probe.sleep ?? defaultSleep;
+    let alive = true;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        alive = await probe.sessionAlive();
+        if (!alive)
+            break;
+        if (attempt < attempts - 1 && intervalMs > 0)
+            await sleep(intervalMs);
+    }
+    if (alive)
+        return { ok: false, reason: 'graceful_exit_timeout' };
+    const portAnswering = probe.portAnswering;
+    if (!portAnswering)
+        return { ok: true };
+    let answering = true;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        answering = await portAnswering();
+        if (!answering)
+            break;
+        if (attempt < attempts - 1 && intervalMs > 0)
+            await sleep(intervalMs);
+    }
+    return answering ? { ok: false, reason: 'port_orphaned' } : { ok: true };
+}

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

@@ -6,9 +6,19 @@
  * @module cli-tools
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLIToolManager = exports.AntigravityTool = exports.GeminiTool = exports.CodexTool = exports.ClaudeTool = exports.BaseCLITool = exports.isImageCapableCLITool = void 0;
+exports.CLIToolManager = exports.AntigravityTool = exports.GeminiTool = exports.CodexTool = exports.ClaudeTool = exports.BaseCLITool = exports.DEFAULT_GRACEFUL_EXIT_SPEC = exports.verifyGracefulExit = exports.resolveGracefulExitSpec = exports.GEMINI_PANE_HEIGHT = exports.resolveCaptureSpec = exports.DEFAULT_COMPOSER_SPEC = exports.resolveComposerSpec = exports.isImageCapableCLITool = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "isImageCapableCLITool", { enumerable: true, get: function () { return types_1.isImageCapableCLITool; } });
+var composer_spec_1 = require("./composer-spec");
+Object.defineProperty(exports, "resolveComposerSpec", { enumerable: true, get: function () { return composer_spec_1.resolveComposerSpec; } });
+Object.defineProperty(exports, "DEFAULT_COMPOSER_SPEC", { enumerable: true, get: function () { return composer_spec_1.DEFAULT_COMPOSER_SPEC; } });
+var capture_spec_1 = require("./capture-spec");
+Object.defineProperty(exports, "resolveCaptureSpec", { enumerable: true, get: function () { return capture_spec_1.resolveCaptureSpec; } });
+Object.defineProperty(exports, "GEMINI_PANE_HEIGHT", { enumerable: true, get: function () { return capture_spec_1.GEMINI_PANE_HEIGHT; } });
+var graceful_exit_1 = require("./graceful-exit");
+Object.defineProperty(exports, "resolveGracefulExitSpec", { enumerable: true, get: function () { return graceful_exit_1.resolveGracefulExitSpec; } });
+Object.defineProperty(exports, "verifyGracefulExit", { enumerable: true, get: function () { return graceful_exit_1.verifyGracefulExit; } });
+Object.defineProperty(exports, "DEFAULT_GRACEFUL_EXIT_SPEC", { enumerable: true, get: function () { return graceful_exit_1.DEFAULT_GRACEFUL_EXIT_SPEC; } });
 // Export base class
 var base_1 = require("./base");
 Object.defineProperty(exports, "BaseCLITool", { enumerable: true, get: function () { return base_1.BaseCLITool; } });

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

@@ -3,6 +3,39 @@
  * CLI Tool Manager
  * Singleton class to manage multiple CLI tools (Claude, Codex, Gemini, Vibe Local, OpenCode)
  */
+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.CLIToolManager = void 0;
 const claude_1 = require("./claude");
@@ -12,7 +45,6 @@ const vibe_local_1 = require("./vibe-local");
 const opencode_1 = require("./opencode");
 const copilot_1 = require("./copilot");
 const antigravity_1 = require("./antigravity");
-const response_poller_1 = require("../polling/response-poller");
 /**
  * CLI Tool Manager (Singleton)
  * Provides centralized access to all CLI tools (Issue #368: includes Vibe Local, Issue #379: includes OpenCode)
@@ -155,6 +187,25 @@ class CLIToolManager {
      * This method abstracts the poller stopping logic so API layer
      * doesn't need to know about specific poller implementations.
      *
+     * ## Issue #1984: なぜ `await import()` なのか
+     *
+     * この 1 行のためだけに `manager.ts` が `../polling/response-poller` を静的 import して
+     * いたことが、モジュールスコープの循環の起点だった:
+     *
+     *     ws-server -> cli-tools/manager -> polling/response-poller
+     *       -> polling/response-poller-core -> polling/response-checker -> ws-server
+     *       -> polling/response-poller-core -> realtime/terminal-broadcast -> ws-server
+     *
+     * `manager` を通る循環は実測 8 本あり、その **8 本すべて**が
+     * `manager -> response-poller` を通る。つまりここ 1 辺で全部落ちる
+     * （検査は tests/unit/guards/no-manager-poller-cycle-1984.test.ts）。
+     *
+     * 代償は API の非同期化。呼び出し元は `api/worktrees/[id]/kill-session/route.ts` の
+     * 1 箇所だけで、そこは `await` を付けてある。**付け忘れると poller 停止が
+     * 直後の `deleteSessionState()` より後ろにずれる**（型も lint も検出しない静かな
+     * 挙動変化）ので、順序を
+     * tests/unit/api/kill-session-stop-pollers-order-1984.test.ts で固定している。
+     *
      * @param worktreeId - Worktree ID
      * @param cliToolId - CLI tool ID
      * @param instanceId - Agent instance ID (Issue #868). Defaults to the primary instance.
@@ -162,12 +213,13 @@ class CLIToolManager {
      * @example
      * ```typescript
      * const manager = CLIToolManager.getInstance();
-     * manager.stopPollers('my-worktree', 'claude');
+     * await manager.stopPollers('my-worktree', 'claude');
      * ```
      */
-    stopPollers(worktreeId, cliToolId, instanceId) {
+    async stopPollers(worktreeId, cliToolId, instanceId) {
         // Stop response-poller for all tools
-        (0, response_poller_1.stopPolling)(worktreeId, cliToolId, instanceId);
+        const { stopPolling: stopResponsePolling } = await Promise.resolve().then(() => __importStar(require('../polling/response-poller')));
+        stopResponsePolling(worktreeId, cliToolId, instanceId);
     }
 }
 exports.CLIToolManager = CLIToolManager;

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

@@ -7,6 +7,35 @@
  * @remarks [D1-001 SRP] Separated from opencode.ts to maintain single responsibility.
  * This module handles Ollama/LM Studio HTTP API calls and config file I/O,
  * while opencode.ts handles tmux session management.
+ *
+ * ## Issue #1908: writing is opt-in, and the worktree is no longer the default
+ *
+ * Starting an opencode session used to drop a 4 KB `opencode.json` into the
+ * worktree root whenever Ollama or LM Studio answered on localhost — one
+ * untracked file per repository, in six repositories on the reporting machine,
+ * including CommandMate's own checkout. Nothing asked, nothing announced, and
+ * `git status` carried it from then on.
+ *
+ * Measured on opencode 1.18.21 (`opencode debug config`, disposable `HOME`), a
+ * worktree-root `opencode.json` is not an additive convenience:
+ *
+ * | layer                                   | read? | on a key collision |
+ * |-----------------------------------------|-------|--------------------|
+ * | `<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 |
+ *
+ * `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,
+ * `OPENCODE_CONFIG` included. That is the reason the skip list below is not just
+ * "is there an `opencode.json`".
+ *
+ * So: generation is off unless {@link OPENCODE_LOCAL_PROVIDER_CONFIG_ENV} asks
+ * for it, and even then it stands down in front of any configuration the
+ * operator already owns. Files written by earlier versions are left exactly
+ * where they are — they still load, so nobody's provider list disappears.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -42,12 +71,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LM_STUDIO_MODEL_PATTERN = exports.MAX_LM_STUDIO_MODELS = exports.LM_STUDIO_BASE_URL = exports.LM_STUDIO_API_URL = exports.OLLAMA_MODEL_PATTERN = exports.MAX_OLLAMA_MODELS = exports.OLLAMA_BASE_URL = exports.OLLAMA_API_URL = void 0;
+exports.OPENCODE_CONFIG_ENV = exports.OPENCODE_LOCAL_PROVIDER_CONFIG_ENV = exports.LM_STUDIO_MODEL_PATTERN = exports.MAX_LM_STUDIO_MODELS = exports.LM_STUDIO_BASE_URL = exports.LM_STUDIO_API_URL = exports.OLLAMA_MODEL_PATTERN = exports.MAX_OLLAMA_MODELS = exports.OLLAMA_BASE_URL = exports.OLLAMA_API_URL = void 0;
 exports.fetchOllamaModels = fetchOllamaModels;
 exports.fetchLmStudioModels = fetchLmStudioModels;
+exports.opencodeGlobalConfigDir = opencodeGlobalConfigDir;
+exports.resolveOpencodeConfigMode = resolveOpencodeConfigMode;
+exports.findOwnedOpencodeConfig = findOwnedOpencodeConfig;
 exports.ensureOpencodeConfig = ensureOpencodeConfig;
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const safe_directory_1 = require("../../config/safe-directory");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('cli-tools/opencode-config');
 // =============================================================================
@@ -125,6 +159,41 @@ const LM_STUDIO_API_TIMEOUT_MS = 3000;
 const MAX_LM_STUDIO_RESPONSE_SIZE = 1 * 1024 * 1024;
 /** Config file name */
 const CONFIG_FILE_NAME = 'opencode.json';
+/**
+ * The environment variable that turns local-provider config generation back on
+ * (Issue #1908).
+ *
+ * Unset — the default — means CommandMate writes nothing. `worktree` restores
+ * the pre-#1908 destination (`<worktree>/opencode.json`), `global` writes the
+ * same content to `$XDG_CONFIG_HOME/opencode/opencode.json` so one machine-wide
+ * file serves every checkout instead of one file per repository.
+ *
+ * An env var rather than a stored setting because that is how every other
+ * launch-path switch in this codebase is spelled (`CM_AGENT_HOOKS_INJECT`,
+ * `CM_OPENCODE_PORT_FILE`), and because the decision has to be readable from the
+ * CLI, the server and a test without a database.
+ */
+exports.OPENCODE_LOCAL_PROVIDER_CONFIG_ENV = 'CM_OPENCODE_LOCAL_PROVIDER_CONFIG';
+/**
+ * opencode's own "use this file" override. Treated as **positive evidence that
+ * the operator owns the configuration**, never as a write target: measured on
+ * 1.18.21, a worktree-root `opencode.json` outranks `$OPENCODE_CONFIG` on a key
+ * collision, so generating one is the one thing most likely to defeat it.
+ */
+exports.OPENCODE_CONFIG_ENV = 'OPENCODE_CONFIG';
+/**
+ * Config file names opencode reads out of a project directory, in the order it
+ * merges them (measured with `opencode debug config`, 1.18.21). `.opencode/` is
+ * included because a config placed there loads exactly like a root-level one.
+ */
+const WORKTREE_CONFIG_RELATIVE_PATHS = [
+    'opencode.json',
+    'opencode.jsonc',
+    path.join('.opencode', 'opencode.json'),
+    path.join('.opencode', 'opencode.jsonc'),
+];
+/** Config file names opencode reads out of its global config directory. */
+const GLOBAL_CONFIG_FILE_NAMES = ['opencode.json', 'opencode.jsonc'];
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -308,35 +377,84 @@ async function fetchLmStudioModels() {
 // Main function
 // =============================================================================
 /**
- * Ensure opencode.json exists in the worktree directory.
- * If the file already exists, it is NOT overwritten (respects user configuration).
- * If both Ollama and LM Studio are not running, the function returns without error
- * and does not generate opencode.json.
+ * opencode's global config directory — `$XDG_CONFIG_HOME/opencode`, falling
+ * back to `~/.config/opencode` (confirmed against `opencode debug paths` under a
+ * disposable `HOME`).
  *
- * Provider configuration is built dynamically: only providers with models are included.
- * If a 3rd provider is added, consider refactoring to a data-driven design
- * (providerDefinitions array + loop) instead of inline if-branches. [KISS]
- * HTTP fetch logic (fetchWithTimeout) can be extracted to a shared helper.
+ * `resolveSafeDirectory` because `XDG_CONFIG_HOME` is an operator-supplied
+ * directory that reaches a recursive `mkdir` below, which is the exact shape
+ * Issue #1774 guards.
  *
- * @param worktreePath - Worktree directory path (from DB)
  * @internal
  */
-async function ensureOpencodeConfig(worktreePath) {
-    // Validate path [D4-004]
-    const validatedPath = validateWorktreePath(worktreePath);
-    const configPath = path.join(validatedPath, CONFIG_FILE_NAME);
-    // Skip if config already exists (respect user configuration)
-    if (fs.existsSync(configPath)) {
-        return;
+function opencodeGlobalConfigDir(env = process.env) {
+    const home = path.join(os.homedir(), '.config');
+    return path.join((0, safe_directory_1.resolveSafeDirectory)(env.XDG_CONFIG_HOME, home, 'XDG_CONFIG_HOME'), 'opencode');
+}
+/**
+ * Read {@link OPENCODE_LOCAL_PROVIDER_CONFIG_ENV}.
+ *
+ * Unknown values resolve to `off` rather than to the old behaviour: a typo in an
+ * opt-in must not opt the operator in.
+ *
+ * @internal
+ */
+function resolveOpencodeConfigMode(env = process.env) {
+    const raw = (env[exports.OPENCODE_LOCAL_PROVIDER_CONFIG_ENV] ?? '').trim().toLowerCase();
+    if (raw === 'worktree' || raw === 'project')
+        return 'worktree';
+    if (raw === 'global' || raw === 'user')
+        return 'global';
+    if (raw !== '' && raw !== 'off' && raw !== '0' && raw !== 'false' && raw !== 'none') {
+        logger.warn('opencode-config-mode-unrecognised', {
+            variable: exports.OPENCODE_LOCAL_PROVIDER_CONFIG_ENV,
+            value: raw,
+        });
+    }
+    return 'off';
+}
+/**
+ * The configuration the operator already owns, if any.
+ *
+ * Returns the first thing found so the caller can log *what* made it stand down
+ * — `'env:OPENCODE_CONFIG'` or a path. Order is "most explicit first".
+ *
+ * @param worktreePath - Directory to check for project-level config, or null to
+ *   check only the global layer
+ * @internal
+ */
+function findOwnedOpencodeConfig(worktreePath, env = process.env) {
+    const explicit = (env[exports.OPENCODE_CONFIG_ENV] ?? '').trim();
+    if (explicit !== '')
+        return `env:${exports.OPENCODE_CONFIG_ENV}`;
+    if (worktreePath !== null) {
+        for (const relative of WORKTREE_CONFIG_RELATIVE_PATHS) {
+            const candidate = path.join(worktreePath, relative);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    const globalDir = opencodeGlobalConfigDir(env);
+    for (const name of GLOBAL_CONFIG_FILE_NAMES) {
+        const candidate = path.join(globalDir, name);
+        if (fs.existsSync(candidate))
+            return candidate;
     }
-    // Fetch models from both providers in parallel.
-    // Each function catches all exceptions internally and returns {} on failure,
-    // so Promise.all will never reject.
+    return null;
+}
+/**
+ * Build the `provider` block from whatever is answering on localhost.
+ *
+ * Both fetches catch everything internally and answer `{}`, so `Promise.all`
+ * never rejects. Only providers with at least one model are included.
+ *
+ * @internal
+ */
+async function buildLocalProviderBlock() {
     const [ollamaModels, lmStudioModels] = await Promise.all([
         fetchOllamaModels(),
         fetchLmStudioModels(),
     ]);
-    // Dynamic provider configuration: only include providers with models
     const provider = {};
     if (Object.keys(ollamaModels).length > 0) {
         provider.ollama = {
@@ -354,9 +472,56 @@ async function ensureOpencodeConfig(worktreePath) {
             models: lmStudioModels,
         };
     }
-    // Both providers have 0 models: skip opencode.json generation
+    return provider;
+}
+/**
+ * Generate a local-provider `opencode.json`, if and only if the operator asked
+ * for one (Issue #1908).
+ *
+ * ## Decision order
+ *
+ * 1. {@link resolveOpencodeConfigMode} is `off` (the default): return
+ *    immediately. Nothing is read, nothing is fetched, nothing is written — the
+ *    two localhost probes that used to run on every launch are skipped too.
+ * 2. {@link findOwnedOpencodeConfig} finds configuration the operator owns:
+ *    stand down. In `worktree` mode that includes the global layer, because a
+ *    file in the worktree root outranks both `$OPENCODE_CONFIG` and the global
+ *    config on a key collision (measured, 1.18.21) — writing one would quietly
+ *    override the very thing that proves they configured opencode themselves.
+ *    In `global` mode only the global layer is consulted; one repository's
+ *    config says nothing about the machine.
+ * 3. Neither Ollama nor LM Studio has a model: nothing worth writing.
+ * 4. Write with `flag: 'wx'`, so a racing writer wins and is left alone.
+ *
+ * Write failures stay non-fatal — a session must start whether or not this
+ * succeeded.
+ *
+ * **Pre-existing files are never touched or removed.** A file an older
+ * CommandMate wrote still loads, so upgrading does not take anyone's provider
+ * list away; it only stops new ones appearing.
+ *
+ * @param worktreePath - Worktree directory path (from DB)
+ * @returns What was decided, for logging and tests
+ * @internal
+ */
+async function ensureOpencodeConfig(worktreePath) {
+    const mode = resolveOpencodeConfigMode();
+    if (mode === 'off') {
+        return { written: false, configPath: null, reason: 'disabled' };
+    }
+    // Validate path [D4-004]. Only on the worktree path, which is the only mode
+    // that touches the caller-supplied directory.
+    const validatedPath = mode === 'worktree' ? validateWorktreePath(worktreePath) : null;
+    const owned = findOwnedOpencodeConfig(validatedPath);
+    if (owned !== null) {
+        logger.info('opencode-config-generation-skipped', { mode, owned });
+        return { written: false, configPath: null, reason: 'existing-config' };
+    }
+    const targetDir = validatedPath ?? opencodeGlobalConfigDir();
+    const configPath = path.join(targetDir, CONFIG_FILE_NAME);
+    const provider = await buildLocalProviderBlock();
     if (Object.keys(provider).length === 0) {
-        return;
+        return { written: false, configPath: null, reason: 'no-providers' };
     }
     // [D4-005] Generate config using JSON.stringify (not template literals).
     // JSON.stringify ensures proper escaping of model names and other values,
@@ -366,6 +531,9 @@ async function ensureOpencodeConfig(worktreePath) {
         provider,
     };
     try {
+        if (mode === 'global') {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), {
             encoding: 'utf-8',
             flag: 'wx',
@@ -373,9 +541,12 @@ async function ensureOpencodeConfig(worktreePath) {
     }
     catch (error) {
         if (error.code === 'EEXIST') {
-            return;
+            return { written: false, configPath: null, reason: 'existing-config' };
         }
         // Non-fatal: write failure should not prevent session start
         logger.warn('failed-to-write-opencodejson:error-insta');
+        return { written: false, configPath: null, reason: 'write-failed' };
     }
+    logger.info('opencode-config-generated', { mode, configPath });
+    return { written: true, configPath, reason: 'written' };
 }