commandmate 0.27.1 → 0.29.0

package/dist/server/src/lib/hooks/sources/opencode/reattach.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * Re-open the event streams of opencode panes that outlived this process
+ * (Issue #2108).
+ *
+ * ## The gap this closes
+ *
+ * `./ports` writes every assignment to `~/.commandmate/opencode-ports.json`
+ * precisely so a CommandMate restart can find a server that is still listening,
+ * and `recoverOpencodePort` already does the whole of the recovery: read the
+ * file, refuse an entry recorded for a different worktree, and refuse a port
+ * that does not answer `/global/health` as opencode. What was missing was a
+ * *caller*. The only chain that reached it was
+ * `OpenCodeTool.launchSession()` -> `resumeOpencodeEventStream()`, which runs
+ * on the "the pane already exists" branch of a **launch** — and a launch is
+ * exactly what does not happen after a restart, because `POST /send` skips
+ * `startSession` when `isRunning` is already true.
+ *
+ * So the in-memory map stayed empty for the life of the process while the file
+ * on disk held the right number. Measured on 2026-08-26 (opencode 1.18.23,
+ * design doc §28): with the pane alive and `GET /global/health` answering
+ * `{"healthy":true}` on the recorded port, a restarted CommandMate returned
+ * `409 NO_OPENCODE_PORT` from `POST /api/worktrees/<id>/opencode/session`,
+ * `connected: false` from `GET .../instances/opencode` and `live: false` from
+ * `GET .../opencode/session` — while `current-output` still reported
+ * `isRunning: true`, because the screen scraper never needed the port. That
+ * asymmetry is what made the defect hard to see: the terminal looked fine and
+ * only the HTTP surfaces were dead.
+ *
+ * ## Why this reuses `resumeOpencodeEventStream` rather than deferring
+ *
+ * The obvious alternative is to recover lazily, inside
+ * `getAssignedOpencodePort()` on a miss. It cannot be done safely there: that
+ * function is synchronous and takes no `worktreePath`, so neither of
+ * `recoverOpencodePort`'s two guards — the recorded-path comparison and the
+ * health check — can be applied. A lazy recovery would hand back a number from
+ * a file with nothing verifying that the thing on it is this worktree's
+ * opencode, which is the "two owners of one port" failure `./ports` was written
+ * to avoid.
+ *
+ * ## What it will not do
+ *
+ * - **It does not resurrect dead entries.** The port file accumulates
+ *   assignments for panes that are long gone (7 of the 8 entries on the
+ *   author's machine were `/tmp/wt-alpha`-style leftovers from tests). An entry
+ *   is only a candidate when its pane answers `isRunning` right now, so a stale
+ *   row costs a `has-session` rather than a health-check timeout.
+ * - **It does not adopt a stolen port.** `recoverOpencodePort` health-checks
+ *   before it writes anything and logs `opencode-port-recovery-unhealthy` when
+ *   nothing answers; a *different* opencode that took the number is caught by
+ *   the subscription watchdog's existing `port_identity_changed` path, which
+ *   compares server versions. Neither is re-implemented here.
+ * - **It does not let the file vouch for itself.** `recoverOpencodePort`'s
+ *   second guard compares the caller's `worktreePath` against the recorded one,
+ *   and handing the recorded value straight back would make that comparison
+ *   trivially true — the guard would be present and inert. The path passed in
+ *   is therefore the *database's*, freshly re-synced by `initializeWorktrees()`
+ *   a moment earlier, so the two sides of the comparison have independent
+ *   origins exactly as they do on the launch path. A worktree id the database
+ *   does not know is skipped without a probe.
+ * - **It does not delay startup.** Every entry is swept concurrently and the
+ *   whole sweep is fail-open, so `server.ts` hands it off without awaiting it.
+ *   The worst case for one entry is a health probe that times out.
+ * - **It touches no other tool.** claude, codex, copilot, gemini, antigravity
+ *   and vibe-local have no port to recover and no branch here; keys for any
+ *   other `cliToolId` are skipped before anything is derived from them.
+ *
+ * ## Why the pane check goes through `ICLITool.isRunning`
+ *
+ * A single `tmux list-sessions` would answer for the whole sweep in one call,
+ * and it is not allowed: Issue #1922 §4 D4 keeps `src/lib/tmux/**` behind the
+ * CLITool gateway, for the static *and* the dynamic import (`.eslintrc.json`
+ * has a `no-restricted-syntax` selector for the second, with no allowlist).
+ * `OpenCodeTool.isRunning` is one of the five sanctioned entry points and it
+ * derives the session name the same way the launcher does, which is the
+ * comparison that actually matters here. The cost is one `has-session` per
+ * persisted row instead of one `list-sessions` per sweep; they run concurrently
+ * and each is a few milliseconds.
+ *
+ * @module lib/hooks/sources/opencode/reattach
+ */
+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.reattachOpencodeEventStreams = reattachOpencodeEventStreams;
+const auto_yes_state_1 = require("../../../../lib/auto-yes-state");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const logger_1 = require("../../../../lib/logger");
+const ports_1 = require("./ports");
+const runtime_1 = require("./runtime");
+const tool_id_1 = require("./tool-id");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/reattach');
+const EMPTY_REPORT = {
+    persisted: 0,
+    candidates: 0,
+    reattached: 0,
+    skipped: 0,
+};
+/**
+ * Turn a persisted key back into the instance it names.
+ *
+ * The key is `buildCompositeKey`'s output, so the split is that function's
+ * inverse and the three `extract*` helpers are the one implementation of it.
+ * Anything that is not an opencode key — a hand-edited file, a key written by
+ * a future tool — answers null rather than being coerced into one.
+ */
+function targetOfKey(key) {
+    const cliToolId = (0, auto_yes_state_1.extractCliToolId)(key);
+    if (cliToolId !== tool_id_1.OPENCODE_CLI_TOOL_ID)
+        return null;
+    const worktreeId = (0, auto_yes_state_1.extractWorktreeId)(key);
+    if (worktreeId.length === 0)
+        return null;
+    const instanceId = (0, auto_yes_state_1.extractInstanceId)(key);
+    if (instanceId === null || instanceId.length === 0)
+        return null;
+    return { worktreeId, cliToolId, instanceId };
+}
+/** The opencode rows of the persisted file, in file order. */
+function readOpencodeEntries(persisted) {
+    const entries = [];
+    for (const [key, assignment] of Object.entries(persisted)) {
+        const target = targetOfKey(key);
+        if (target === null)
+            continue;
+        entries.push({ target, recordedPath: assignment.worktreePath, port: assignment.port });
+    }
+    return entries;
+}
+/**
+ * A `worktreeId -> path` lookup backed by the database.
+ *
+ * Answers null for every id when the database cannot be opened, which makes the
+ * sweep a no-op rather than a crash — the same fail-open the rest of this
+ * pipeline has. Loaded through `await import` for the reason `./ingest` does:
+ * keeping `better-sqlite3` out of the static graph of `@/lib/hooks/sources` is
+ * what lets the launcher import this directory at all.
+ */
+async function loadWorktreePathResolver() {
+    try {
+        const [{ getDbInstance }, { getWorktreeById }] = await Promise.all([
+            Promise.resolve().then(() => __importStar(require('../../../../lib/db/db-instance'))),
+            Promise.resolve().then(() => __importStar(require('../../../../lib/db'))),
+        ]);
+        const db = getDbInstance();
+        return (worktreeId) => getWorktreeById(db, worktreeId)?.path ?? null;
+    }
+    catch (error) {
+        logger.warn('opencode-reattach-worktree-lookup-unavailable', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return () => null;
+    }
+}
+/**
+ * "Is this instance's pane still running?", through the sanctioned gateway.
+ *
+ * Answers false when the gateway itself refuses — `getSessionName` throws on a
+ * worktree id that could not have produced a tmux session, which for a file the
+ * user can edit is a reason to skip the row rather than to abandon the sweep.
+ */
+async function loadPaneCheck() {
+    const { CLIToolManager } = await Promise.resolve().then(() => __importStar(require('../../../../lib/cli-tools/manager')));
+    const tool = CLIToolManager.getInstance().getTool(tool_id_1.OPENCODE_CLI_TOOL_ID);
+    return async (target) => {
+        try {
+            return await tool.isRunning(target.worktreeId, target.instanceId);
+        }
+        catch (error) {
+            logger.info('opencode-reattach-pane-check-failed', {
+                worktreeId: target.worktreeId,
+                instanceId: target.instanceId ?? target.cliToolId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    };
+}
+/**
+ * Re-subscribe to every opencode pane that survived the last process.
+ *
+ * Called once from `server.ts`, after the migrations that `./ingest` needs and
+ * without being awaited. Never throws and never rejects.
+ *
+ * @returns What the sweep found and did
+ */
+async function reattachOpencodeEventStreams() {
+    // No injection means no `--port` was ever passed, so there is no server on
+    // any recorded number. Checked before anything is loaded so the sweep costs
+    // nothing at all when the feature is off.
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return { ...EMPTY_REPORT };
+    try {
+        // Read once: the sweep must not see two different versions of the file, and
+        // a launch racing it would otherwise be counted in one half and not the
+        // other.
+        const entries = readOpencodeEntries((0, ports_1.readPersistedOpencodePorts)());
+        if (entries.length === 0)
+            return { ...EMPTY_REPORT };
+        const [isPaneRunning, resolveWorktreePath] = await Promise.all([
+            loadPaneCheck(),
+            loadWorktreePathResolver(),
+        ]);
+        // Concurrent on purpose: the cost of an entry is a `has-session` plus, for
+        // a live pane, a health probe against a server that is either there
+        // (sub-millisecond) or not (one timeout). Serialising them would make the
+        // sweep as slow as the sum of the dead ones.
+        const outcomes = await Promise.all(entries.map(async (entry) => {
+            if (!(await isPaneRunning(entry.target)))
+                return 'no-pane';
+            const instanceId = entry.target.instanceId ?? entry.target.cliToolId;
+            const worktreePath = resolveWorktreePath(entry.target.worktreeId);
+            if (worktreePath === null) {
+                // The pane outlived the worktree row (deleted, or renumbered without
+                // its alias). Nothing here can say where it is, and guessing is what
+                // the guard exists to prevent.
+                logger.info('opencode-reattach-unknown-worktree', {
+                    worktreeId: entry.target.worktreeId,
+                    instanceId,
+                    recorded: entry.recordedPath,
+                });
+                return 'skipped';
+            }
+            if (await (0, runtime_1.resumeOpencodeEventStream)(entry.target, worktreePath))
+                return 'reattached';
+            // `recoverOpencodePort` has already said *why* at info level
+            // (`opencode-port-recovery-unhealthy` / `-path-mismatch`); this names
+            // the pane that is consequently scraper-only for the rest of its life.
+            logger.info('opencode-reattach-skipped', {
+                worktreeId: entry.target.worktreeId,
+                instanceId,
+                port: entry.port,
+            });
+            return 'skipped';
+        }));
+        const report = {
+            persisted: entries.length,
+            candidates: outcomes.filter((outcome) => outcome !== 'no-pane').length,
+            reattached: outcomes.filter((outcome) => outcome === 'reattached').length,
+            skipped: outcomes.filter((outcome) => outcome === 'skipped').length,
+        };
+        logger.info(report.candidates === 0 ? 'opencode-reattach-no-live-panes' : 'opencode-reattach-complete', { ...report });
+        return report;
+    }
+    catch (error) {
+        // Fail-open like everything else in this pipeline: a sweep that cannot run
+        // leaves exactly the pre-#2108 behaviour, which is the screen scraper.
+        logger.warn('opencode-reattach-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { ...EMPTY_REPORT };
+    }
+}

package/dist/server/src/lib/hooks/sources/opencode/runtime.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * The three calls `OpenCodeTool` makes (Issue #1763).
+ * The calls `OpenCodeTool` makes into the event pipeline (Issue #1763).
  *
  * `src/lib/cli-tools/opencode.ts` owns the tmux pane; this module owns the
  * event stream that runs beside it. Keeping them apart is what stops the
@@ -9,6 +9,11 @@
  * is reached by every import of `@/lib/hooks/sources`, and the wiring below is
  * the only place that pulls `./ingest` in.
  *
+ * Three of them are the lifecycle below. The fourth is {@link abortOpencodeTurn},
+ * which is not lifecycle at all: it is the interrupt path taking the server
+ * route when there is one (Issue #2034), and it fails open to the keyboard the
+ * same way everything else here fails open to the scraper.
+ *
  * ## The lifecycle, and what it deliberately does not include
  *
  * There is **no server process to manage**. Issue #1763's text asked for
@@ -27,11 +32,12 @@
  * @module lib/hooks/sources/opencode/runtime
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPENCODE_ATTACH_HEALTH_DELAYS_MS = void 0;
+exports.OPENCODE_ABORT_IDLE_TIMEOUT_MS = exports.OPENCODE_ATTACH_HEALTH_DELAYS_MS = void 0;
 exports.opencodeTarget = opencodeTarget;
 exports.reserveOpencodeServerPort = reserveOpencodeServerPort;
 exports.attachOpencodeEventStream = attachOpencodeEventStream;
 exports.resumeOpencodeEventStream = resumeOpencodeEventStream;
+exports.abortOpencodeTurn = abortOpencodeTurn;
 exports.releaseOpencodeEventStream = releaseOpencodeEventStream;
 const logger_1 = require("../../../../lib/logger");
 const client_1 = require("./client");
@@ -154,11 +160,13 @@ async function attachOpencodeEventStream(target) {
         await source_1.opencodeAgentEventSource.subscribe(target, (event) => {
             void (0, ingest_1.ingestOpencodeEvent)(target, event);
         });
+        const activity = await probeAttachedActivity(target);
         logger.info('opencode-event-stream-attached', {
             worktreeId: target.worktreeId,
             instanceId: target.instanceId ?? target.cliToolId,
             port,
             version: health.version,
+            activity,
         });
         return true;
     }
@@ -170,6 +178,55 @@ async function attachOpencodeEventStream(target) {
         return false;
     }
 }
+/**
+ * Re-read whether the conversation is working, right after a stream attaches
+ * (Issue #2054).
+ *
+ * **The first production caller of `AgentEventSource.probeActivity`.** The
+ * method has existed since Phase 4-1 (#1759) with nothing but its own definition
+ * reading it, and this is the gap it was written for: a stream that opens in the
+ * middle of a turn delivers its first frame when that turn *ends*, so between
+ * {@link attachOpencodeEventStream} and the next `session.idle` — which on a
+ * long turn is minutes — CommandMate has no answer to "is this pane working
+ * right now?" except the screen. `GET /session/status` has the answer and this
+ * is the one call that asks it.
+ *
+ * Deliberately **through the source interface** rather than through
+ * `client.fetchOpencodeActivity`, which this module could import directly. Three
+ * call sites already read `getOpencodeLiveness` directly and Issue #2054's
+ * instruction was not to add a fourth of anything; going through the registered
+ * source also means the port lookup, the "no port assigned" null and the request
+ * timeout are the source's business rather than a second copy of them here.
+ *
+ * Not the same read as `subscription.recoverTurnState`, and it does not replace
+ * it: that one is per *session* and re-arms the turn gate, this one is the
+ * instance-level aggregate the surfaces can render. Both go through the single
+ * reader in `./client`.
+ *
+ * Never throws and never blocks the attach for long — one loopback request
+ * against a server whose health probe has just succeeded, capped by
+ * `OPENCODE_REQUEST_TIMEOUT_MS`.
+ *
+ * @param target - The instance whose stream has just been attached
+ * @returns The answer, or null when the source could not be asked
+ */
+async function probeAttachedActivity(target) {
+    let activity = null;
+    try {
+        activity = await source_1.opencodeAgentEventSource.probeActivity(target);
+    }
+    catch (error) {
+        // A probe that throws is a probe that did not answer, which is what null
+        // already means. The attach itself succeeded and must not be undone by it.
+        logger.debug('opencode-activity-probe-failed', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    (0, subscription_1.recordOpencodeProbedActivity)(target, activity, Date.now());
+    return activity;
+}
 /**
  * Re-open the stream for an instance whose pane outlived this process.
  *
@@ -197,6 +254,112 @@ async function resumeOpencodeEventStream(target, worktreePath) {
         return false;
     }
 }
+/**
+ * How long to wait for the `session.idle` that confirms an abort (Issue #2034).
+ *
+ * Two seconds against a measured latency of roughly zero: on 1.18.22 the first
+ * `session.idle` was emitted in the same millisecond as the abort's `200 true`
+ * reply, and #1758 §5.3.2 measured the same on 1.18.3. The budget is not sized
+ * for the ordinary case, it is the point at which "the server took my request"
+ * stops being evidence that the turn ended — and it is spent inside the HTTP
+ * request the Interrupt button is waiting on, so it cannot be generous.
+ *
+ * Only the *failure* path pays it: a confirmed abort resolves as soon as the
+ * frame lands.
+ */
+exports.OPENCODE_ABORT_IDLE_TIMEOUT_MS = 2_000;
+/**
+ * End the running turn through the server, if there is a server (Issue #2034).
+ *
+ * The primary path for `OpenCodeTool.interrupt`. `POST /session/:id/abort`
+ * ends the turn outright, where the keyboard route depends on the TUI's own
+ * draw state — two Escapes inside a five-second footer label (#1894) that a
+ * picker or a dialog on screen can swallow.
+ *
+ * **Every no is the same no.** No port assigned, a subscription that is not
+ * live, no session the gate calls this instance's, a request that was refused,
+ * a completion that never arrived: all of them answer `false`, and the caller
+ * presses Escape twice exactly as it did before this Issue. That is the whole
+ * safety property — an instance launched with `CM_AGENT_HOOKS_INJECT=0`, or on
+ * an opencode too old for `--port`, must not become an instance that cannot be
+ * interrupted. Nothing here throws, for the same reason.
+ *
+ * The order matters and is measured: the watch is armed **before** the request
+ * goes out, because the idle can be on the wire before the reply is
+ * (see {@link watchOpencodeSessionIdle}).
+ *
+ * @param target - The instance whose turn should stop
+ * @returns Whether the turn was aborted *and* confirmed idle
+ */
+async function abortOpencodeTurn(target) {
+    const instanceId = target.instanceId ?? target.cliToolId;
+    try {
+        const port = (0, ports_1.getAssignedOpencodePort)(target);
+        if (port === null)
+            return false;
+        const liveness = (0, subscription_1.getOpencodeLiveness)(target);
+        if (liveness.state !== 'live') {
+            logger.info('opencode-abort-skipped-not-live', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                port,
+                liveness: liveness.state,
+            });
+            return false;
+        }
+        const sessionId = (0, subscription_1.getOpencodePrimarySession)(target);
+        if (sessionId === null) {
+            logger.info('opencode-abort-skipped-no-session', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                port,
+            });
+            return false;
+        }
+        const watch = (0, subscription_1.watchOpencodeSessionIdle)(target, sessionId, exports.OPENCODE_ABORT_IDLE_TIMEOUT_MS);
+        const accepted = await (0, client_1.abortOpencodeSession)(port, sessionId);
+        if (!accepted) {
+            watch.cancel();
+            logger.warn('opencode-abort-rejected', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                port,
+                sessionId,
+            });
+            return false;
+        }
+        const confirmed = await watch.seen;
+        if (!confirmed) {
+            // The server said yes and the turn did not end within the budget. Saying
+            // so out loud rather than reporting a success: the caller falls back to
+            // the keystrokes, and an operator seeing this repeatedly is looking at a
+            // server that accepts aborts it does not act on.
+            logger.warn('opencode-abort-unconfirmed', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                port,
+                sessionId,
+                timeoutMs: exports.OPENCODE_ABORT_IDLE_TIMEOUT_MS,
+            });
+            return false;
+        }
+        logger.info('opencode-abort-confirmed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            port,
+            sessionId,
+        });
+        return true;
+    }
+    catch (error) {
+        logger.warn('opencode-abort-failed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
 /**
  * Stop watching an instance and give its port back.
  *

package/dist/server/src/lib/hooks/sources/opencode/source.js

@@ -20,7 +20,25 @@
  *   read this through `describeAbstain()` and owe the operator a visible signal.
  * - **`configScope: 'none'`** — nothing is written anywhere. No settings file,
  *   no hooks entry, no change to `~/.config/opencode/opencode.jsonc`. The whole
- *   integration is a `--port` argument and a subscription.
+ *   integration is a `--port` argument and a subscription. **#2053 re-opened
+ *   this and closed it again.** Handing opencode an inline config through
+ *   `OPENCODE_CONFIG_CONTENT` writes no file, and a `permission` `deny` declared
+ *   that way really does make the dialog disappear — measured on 1.18.22,
+ *   `permission.asked` went from 1 to 0 and the turn completed on `session.idle`
+ *   instead of blocking forever. It is still not adopted, because inline config
+ *   is the *top* of a five-layer precedence chain and therefore overwrites the
+ *   operator's own `permission` rules with no warning and no way for
+ *   CommandMate to see the collision: a string `permission.bash: "ask"` is
+ *   replaced wholesale by an injected object (silently downgrading every
+ *   unnamed command to the built-in `allow`), and within a merged object the
+ *   rule order beats pattern specificity, so a broad glob from CommandMate
+ *   defeats an exact-match rule the operator wrote. A malformed injection also
+ *   makes the TUI refuse to start and exit 0 with no port, while `serve` keeps
+ *   answering `GET /global/health` with `healthy` — a failure `liveness()`
+ *   reports as alive. Ruling and the alternative (read the merged `permission`
+ *   instead of writing one): `docs/design/agent-event-source-interface.md` §3.4;
+ *   measurements: `docs/design/opencode-server-live-verification.md` §26.
+ *   Pinned by `tests/unit/hooks/sources/opencode-config-scope-2053.test.ts`.
  * - **`decisionTimeoutSeconds: null`** — the honest encoding of "waits forever".
  *   Not zero, which would read as "answer instantly or lose the chance", and not
  *   a large number, which would read as a deadline that exists.
@@ -53,6 +71,7 @@ const pending_decisions_1 = require("../pending-decisions");
 const client_1 = require("./client");
 const mappers_1 = require("./mappers");
 const payloads_1 = require("./payloads");
+const launch_settings_1 = require("./launch-settings");
 const ports_1 = require("./ports");
 const subscription_1 = require("./subscription");
 const tool_id_1 = require("./tool-id");
@@ -226,6 +245,22 @@ async function probeOpencodeActivity(target) {
  * `--hostname` is passed explicitly even though `127.0.0.1` is the default,
  * because the default is the security property: the server is unauthenticated,
  * and `--mdns` (never passed) would move it to `0.0.0.0` (#1758 §5.8.3).
+ *
+ * ## The instance's own settings (Issue #2048)
+ *
+ * `--agent` and `--model` are appended when the operator configured them for
+ * this instance, from the cache `loadOpencodeLaunchSettings` filled immediately
+ * before this call — see `./launch-settings` for why the value arrives that way
+ * rather than on {@link AgentLaunchContext}. **The `bare` branches above stay
+ * bare**: a launch with no port has no structured events, and an operator who
+ * turned hook injection off asked for the pre-#1763 command line, so neither is
+ * a place to start adding flags.
+ *
+ * The variant is deliberately not here. `--variant` is a flag of `opencode run`
+ * and **not** of the TUI (measured on 1.18.22,
+ * `docs/design/opencode-server-live-verification.md` §20.3): passing it makes
+ * opencode print its usage and exit, leaving an empty pane. It travels on the
+ * prompt instead, which is the one channel measured to apply it.
  */
 function prepareOpencodeLaunch({ target, executablePath, }) {
     // `env` is empty for every branch: opencode is the one source that needs no
@@ -237,11 +272,17 @@ function prepareOpencodeLaunch({ target, executablePath, }) {
     const port = (0, ports_1.getAssignedOpencodePort)(target);
     if (port === null)
         return bare;
+    const settings = (0, launch_settings_1.opencodeLaunchArguments)((0, launch_settings_1.getOpencodeLaunchSettings)(target));
     return {
-        command: `${(0, hook_settings_generator_1.shellQuote)(executablePath)} --port ${port} --hostname ${client_1.OPENCODE_SERVER_HOST}`,
+        command: `${(0, hook_settings_generator_1.shellQuote)(executablePath)} --port ${port} --hostname ${client_1.OPENCODE_SERVER_HOST}` +
+            settings,
         // Nothing is written to disk. `configScope: 'none'` says the same thing to
         // a caller that asks the capabilities instead of the plan.
         settingsPath: null,
+        // `env` stays empty on purpose, and #2053 is the reason it is worth saying
+        // twice: `OPENCODE_CONFIG_CONTENT` would fit here and would work, but it is
+        // the top precedence layer, so anything CommandMate puts in it silently
+        // outranks the operator's own config. See the module doc.
         env: {},
     };
 }
@@ -257,6 +298,9 @@ exports.opencodeAgentEventSource = (0, define_source_1.definePullEventSource)({
     noDecision: { kind: 'blocks' },
     capabilities: {
         supportedEvents: OPENCODE_SUPPORTED_EVENTS,
+        // #2053 measured the one candidate for changing this — an inline config in
+        // `OPENCODE_CONFIG_CONTENT` — and ruled against it. Read the module doc
+        // before flipping this value; the reason is not "it does not work".
         configScope: 'none',
         decisionTimeoutSeconds: null,
         // Issue #1924, §4 D3. Not hooks at all: CommandMate holds the SSE stream and