@openagents-org/agent-launcher 0.2.193 → 0.2.194

package/src/adapters/hermes.js

@@ -10,14 +10,23 @@
  * - profile auto-detection from the agent name (falls back to 'default')
  * - workspace context injection (identity + recent history + agent roster)
  * - subprocess isolation (hermes manages its own HERMES_HOME per profile)
+ *
+ * One workspace thread is one Hermes session, resumed with `--resume` on every
+ * later message. Two rules keep that session — and the provider's prompt cache
+ * behind it — worth resuming:
+ * - a session is only given up when Hermes says it no longer exists. A turn
+ *   that fails, runs out of iterations or is stopped still belongs to it;
+ * - the workspace instructions ride alongside the conversation as a prefill
+ *   message instead of being written into it again with every user message.
  */
 
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, execFile } = require('child_process');
 // spawn() here is the WSL bridge from ../wsl: same signature as
 // child_process.spawn, and a straight pass-through unless the resolved CLI
 // lives on the other side of the Windows/WSL boundary.
@@ -25,6 +34,7 @@ const { spawn, bridgeSpawn } = require('../wsl');
 
 const BaseAdapter = require('./base');
 const { buildOpenclawSystemPrompt } = require('./workspace-prompt');
+const { isRecapEligible } = require('./decision-log');
 const { REASON } = require('./health-status');
 const { whichBinary, whereBinary } = require('../paths');
 
@@ -33,7 +43,43 @@ const HERMES_INSTALL_HINT = IS_WINDOWS
   ? 'powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex"'
   : 'curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash';
 const SESSION_ID_RE = /session_id:\s*(\S+)/;
+const SESSION_LINE_RE = /^session_id:\s*\S+$/;
+// What Hermes prints, in place of a session_id, when `--resume` names a
+// session it no longer has. Upstream localises that line
+// (t("cli.resume.session_not_found")), so this only matches the English text;
+// under another locale a lost session is not recognised as lost.
+const SESSION_NOT_FOUND_RE = /session not found/i;
 const MAX_HISTORY_ENTRIES = 12;
+const OPENAGENTS_RULES = [
+  '\n## OpenAgents-specific Rules',
+  '- Your final text response is posted back to the workspace automatically.',
+  '- If you need to ask the user something, ask in normal text. Do not try to open an interactive prompt.',
+  '- Do not reveal secrets, tokens, raw auth headers, or internal command lines.',
+  '- Keep status concise. Focus on useful output over theatre.',
+];
+// Hermes sends the messages in this file at the head of every model request
+// without storing them in the session.
+const PREFILL_ENV = 'HERMES_PREFILL_MESSAGES_FILE';
+// The CLI has read that variable since release 0.16.0 of 2026.6.5; 0.15.1
+// (2026.5.29) still took the path from config.yaml only. `hermes --version`
+// prints the release date as "(YYYY.M.D)"; desktop-app installs print only the
+// version ("Hermes Agent v0.21.6 · stable").
+const PREFILL_ENV_SINCE = [2026, 6, 5];
+const PREFILL_ENV_SINCE_VERSION = [0, 16, 0];
+const RELEASE_DATE_RE = /\((\d{4})\.(\d{1,2})\.(\d{1,2})\)/;
+const SEMVER_RE = /\bv(\d+)\.(\d+)\.(\d+)\b/;
+// Our prefill files, in os.tmpdir(); they carry the workspace token. One left
+// behind by a killed daemon is removed at the next start once this old.
+const PREFILL_FILE_RE = /^openagents-hermes-[0-9a-f]+\.json$/;
+const STALE_PREFILL_MS = 60 * 60 * 1000;
+// `prefill_messages_file:` in config.yaml, at top level or under `agent:`.
+const CONFIG_PREFILL_RE = /^[ \t]*prefill_messages_file[ \t]*:(.*)$/gm;
+const PREFILL_CLOSING = [
+  '',
+  '---',
+  '',
+  'The text above is standing context from the OpenAgents workspace, not a message to answer. The conversation follows.',
+];
 
 class HermesAdapter extends BaseAdapter {
   /**
@@ -56,11 +102,14 @@ class HermesAdapter extends BaseAdapter {
 
     this._channelSessions = {};
     this._channelProcesses = {};
+    // { bin, ok }: whether the resolved hermes reads PREFILL_ENV.
+    this._prefillEnvSupport = null;
     this._sessionsFile = path.join(
       os.homedir(), '.openagents', 'sessions',
       `${this.workspaceId}_${this.agentName}_hermes.json`,
     );
     this._loadSessions();
+    HermesAdapter.sweepStalePrefillFiles();
 
     this._hermesBin = this._findHermesBinary();
     if (this._hermesBin) {
@@ -187,6 +236,12 @@ class HermesAdapter extends BaseAdapter {
     } catch {}
   }
 
+  _forgetSession(channelName) {
+    if (!(channelName in this._channelSessions)) return;
+    delete this._channelSessions[channelName];
+    this._saveSessions();
+  }
+
   // ------------------------------------------------------------------
   // Prompt assembly
   // ------------------------------------------------------------------
@@ -210,32 +265,38 @@ class HermesAdapter extends BaseAdapter {
     }
   }
 
-  async _getRecentHistoryText(channelName) {
+  /**
+   * What was said in this channel before the message being answered — for a
+   * Hermes session that starts with nothing: a thread the agent joins midway,
+   * or one whose earlier session can no longer be resumed. A resumed session
+   * holds its own history and is never given this.
+   *
+   * Bounded, because the whole prompt travels as a single argv entry.
+   */
+  async _getRecentHistoryText(channelName, currentMessage) {
     try {
-      const messages = await this.client.pollMessages({
-        workspaceId: this.workspaceId,
-        channelName,
-        token: this.token,
-        limit: MAX_HISTORY_ENTRIES,
-      });
-      if (!Array.isArray(messages) || messages.length === 0) return '';
-      const lines = messages
-        .filter((m) => m.messageType !== 'status')
+      const messages = await this.client.getRecentMessages(
+        this.workspaceId, channelName, this.token, 30,
+      );
+      const lines = (messages || [])
+        .filter((m) => isRecapEligible(m, currentMessage))
+        .slice(-MAX_HISTORY_ENTRIES)
         .map((m) => {
           const sender = m.senderName || m.senderType || 'unknown';
-          const content = (m.content || '').trim();
-          if (!content) return null;
-          return `- ${sender}: ${content.slice(0, 400)}`;
-        })
-        .filter(Boolean);
+          return `- ${sender}: ${m.content.trim().slice(0, 400)}`;
+        });
       return lines.length ? `## Recent Workspace Messages\n${lines.join('\n')}` : '';
     } catch {
       return '';
     }
   }
 
-  async _buildContextPrefix(channelName) {
-    const parts = [
+  /**
+   * The workspace's standing instructions for a channel: who the agent is
+   * here, the mode, the workspace API, the pinned decisions and glossary.
+   */
+  _buildWorkspaceInstructions(channelName) {
+    return [
       buildOpenclawSystemPrompt({
         agentName: this.agentName,
         workspaceId: this.workspaceId,
@@ -247,20 +308,150 @@ class HermesAdapter extends BaseAdapter {
         disabledModules: this.disabledModules,
         ...this.pinnedPromptOpts(channelName),
       }),
-      '\n## OpenAgents-specific Rules',
-      '- Your final text response is posted back to the workspace automatically.',
-      '- If you need to ask the user something, ask in normal text. Do not try to open an interactive prompt.',
-      '- Do not reveal secrets, tokens, raw auth headers, or internal command lines.',
-      '- Keep status concise. Focus on useful output over theatre.',
-    ];
+      ...OPENAGENTS_RULES,
+    ].join('\n').trim();
+  }
 
-    const [agentsText, historyText] = await Promise.all([
-      this._getAgentsText(),
-      this._getRecentHistoryText(channelName),
-    ]);
-    if (agentsText) parts.push('\n' + agentsText);
-    if (historyText) parts.push('\n' + historyText);
-    return parts.join('\n').trim();
+  /**
+   * The prompt for one turn.
+   *
+   * A session that is starting out is told who else is in the workspace and
+   * what was said before; a resumed one has its own history and gets the
+   * user's message as it is. `instructions` is only passed when they could not
+   * go out as a prefill and have to travel in the message instead.
+   */
+  async _buildPrompt(channelName, content, resumeId, instructions = '') {
+    const parts = [];
+    if (instructions) parts.push(instructions);
+    if (!resumeId) {
+      const [agentsText, historyText] = await Promise.all([
+        this._getAgentsText(),
+        this._getRecentHistoryText(channelName, content),
+      ]);
+      if (agentsText) parts.push('\n' + agentsText);
+      if (historyText) parts.push('\n' + historyText);
+    }
+    const context = parts.join('\n').trim();
+    if (context) return `${context}\n\n---\n\nUser message:\n${content}`;
+    // The prompt is the value of `-q`; one starting with a dash would be read
+    // as another flag.
+    return content.startsWith('-') ? `User message:\n${content}` : content;
+  }
+
+  // ------------------------------------------------------------------
+  // Workspace instructions as a Hermes prefill
+  // ------------------------------------------------------------------
+
+  /** What `hermes --version` prints; it opens with e.g. "Hermes Agent v0.21.4 (2026.9.24)". */
+  _hermesVersionText() {
+    const { file, args } = bridgeSpawn(this._hermesBin, ['--version']);
+    return new Promise((resolve, reject) => {
+      execFile(file, args, {
+        env: { ...(this.agentEnv || process.env) },
+        timeout: 20000,
+        windowsHide: true,
+      }, (err, stdout) => (err ? reject(err) : resolve(String(stdout))));
+    });
+  }
+
+  /** True when a `hermes --version` output names a release that reads PREFILL_ENV. */
+  _readsPrefillEnv(versionText) {
+    const text = String(versionText || '');
+    const atLeast = (have, want) => {
+      const i = have.findIndex((n, k) => n !== want[k]);
+      return i === -1 || have[i] > want[i];
+    };
+    const date = RELEASE_DATE_RE.exec(text);
+    if (date) return atLeast(date.slice(1, 4).map(Number), PREFILL_ENV_SINCE);
+    const ver = SEMVER_RE.exec(text);
+    // The old calendar tags (v2026.3.12) are dates, not versions.
+    if (ver && Number(ver[1]) < 1000) return atLeast(ver.slice(1, 4).map(Number), PREFILL_ENV_SINCE_VERSION);
+    return false;
+  }
+
+  /**
+   * True when the user already points Hermes at a prefill file of their own,
+   * through the variable or `prefill_messages_file` in config.yaml. Setting
+   * the variable would replace theirs, so the instructions go in the message.
+   */
+  _userHasPrefill() {
+    const env = this.agentEnv || process.env;
+    if (String(env[PREFILL_ENV] || '').trim()) return true;
+    const homeEnv = String(env.HERMES_HOME || '').trim();
+    const home = homeEnv || (IS_WINDOWS
+      ? path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'hermes')
+      : path.join(os.homedir(), '.hermes'));
+    const configs = [path.join(home, 'config.yaml')];
+    if (this.hermesProfile && this.hermesProfile !== 'default') {
+      configs.push(path.join(home, 'profiles', this.hermesProfile, 'config.yaml'));
+    }
+    return configs.some((file) => {
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { return false; }
+      return HermesAdapter.configHasPrefill(text);
+    });
+  }
+
+  /** True when a config.yaml text sets `prefill_messages_file` to something. */
+  static configHasPrefill(text) {
+    for (const m of String(text || '').matchAll(CONFIG_PREFILL_RE)) {
+      const value = m[1].replace(/\s#.*$/, '').trim().replace(/^(["'])(.*)\1$/, '$2').trim();
+      if (value && value !== '~' && value.toLowerCase() !== 'null') return true;
+    }
+    return false;
+  }
+
+  /**
+   * Whether this hermes takes its prefill file from the environment. One that
+   * does not would simply start without the workspace instructions, so a
+   * version that cannot be read counts as too old. Asked once per binary.
+   */
+  async _supportsPrefillEnv() {
+    const known = this._prefillEnvSupport;
+    if (known && known.bin === this._hermesBin) return known.ok;
+    let ok = false;
+    try { ok = this._readsPrefillEnv(await this._hermesVersionText()); } catch {}
+    if (!ok) this._log(`This hermes does not read ${PREFILL_ENV}; sending the workspace instructions with each message`);
+    this._prefillEnvSupport = { bin: this._hermesBin, ok };
+    return ok;
+  }
+
+  /**
+   * Write the instructions where Hermes will pick them up as a prefill: one
+   * user message, placed ahead of the conversation on every model request and
+   * never stored in the session.
+   *
+   * Prepending them to each user message, as this adapter used to, wrote a
+   * fresh ~18 KB copy into the session every turn. The provider's prompt cache
+   * had never seen that copy, so it was new input each time, and it grew the
+   * conversation by that much per message however short the message — towards
+   * the point where Hermes compresses the conversation, which rewrites the
+   * cached prefix as well. Sending them once per session is not an option
+   * either: that compression folds old messages into a "reference only"
+   * summary, instructions included. As a prefill they are always there,
+   * always current, and identical from one request to the next.
+   *
+   * Returns the file's path, or null when they have to go in the message.
+   */
+  async _writePrefill(instructions) {
+    if (!(await this._supportsPrefillEnv())) return null;
+    if (this._userHasPrefill()) {
+      if (!this._userPrefillLogged) {
+        this._userPrefillLogged = true;
+        this._log('Hermes already has a prefill_messages_file; keeping it and sending the workspace instructions with each message');
+      }
+      return null;
+    }
+    const file = path.join(os.tmpdir(), `openagents-hermes-${crypto.randomBytes(8).toString('hex')}.json`);
+    const content = [instructions, ...PREFILL_CLOSING].join('\n');
+    try {
+      // Owner-only: the instructions carry the workspace token.
+      fs.writeFileSync(file, JSON.stringify([{ role: 'user', content }]), { mode: 0o600 });
+      return file;
+    } catch (e) {
+      this._log(`Could not write the Hermes prefill file (${e.message}); sending workspace instructions with the message`);
+      return null;
+    }
   }
 
   // ------------------------------------------------------------------
@@ -296,6 +487,18 @@ class HermesAdapter extends BaseAdapter {
     return { text: lines.join('\n').trim(), sessionId };
   }
 
+  /** Hermes's stderr without the session bookkeeping it prints on every run. */
+  _stderrDetail(stderr) {
+    return String(stderr || '')
+      .split(/\r?\n/)
+      .filter((line) => {
+        const stripped = line.trim();
+        return stripped && !SESSION_LINE_RE.test(stripped) && !stripped.startsWith('↻ Resumed session ');
+      })
+      .join('\n')
+      .trim();
+  }
+
   // ------------------------------------------------------------------
   // Subprocess lifecycle
   // ------------------------------------------------------------------
@@ -320,14 +523,27 @@ class HermesAdapter extends BaseAdapter {
     return args;
   }
 
-  async _runHermes(prompt, channelName) {
+  /**
+   * Run one Hermes turn and report what became of it.
+   *
+   * `sessionId` is what Hermes itself reported for this run. It prints one
+   * whenever the turn got as far as the session — finished or not — and none
+   * when the turn never began. `detail` is its stderr without that
+   * bookkeeping; `stopped` says the user stopped the turn.
+   *
+   * @returns {Promise<{stopped: boolean, exitCode: number|null, text: string,
+   *   sessionId: string|null, detail: string}>}
+   */
+  async _runHermes(prompt, channelName, resumeId = null, prefillFile = null) {
     // Stopped while this turn was being prepared: start nothing (no tokens).
-    if (this._stoppedBeforeStart(channelName)) return '';
-    const resumeId = this._channelSessions[channelName];
+    if (this._stoppedBeforeStart(channelName)) {
+      return { stopped: true, exitCode: null, text: '', sessionId: null, detail: '' };
+    }
     const args = this._buildHermesCmd(prompt, resumeId);
     this._log(`Running hermes (profile=${this.hermesProfile}, channel=${channelName}, resume=${!!resumeId})`);
 
     const env = { ...(this.agentEnv || process.env) };
+    if (prefillFile) env[PREFILL_ENV] = prefillFile;
 
     // A hermes that lives inside WSL is rewritten to `wsl.exe -e <path> …` by
     // the bridge in ../wsl (which also forces detached off, there being no
@@ -347,35 +563,88 @@ class HermesAdapter extends BaseAdapter {
 
     let stdout = '';
     let stderr = '';
+    let spawnError = null;
     proc.stdout.on('data', (d) => { stdout += d.toString('utf-8'); });
     proc.stderr.on('data', (d) => { stderr += d.toString('utf-8'); });
 
+    // 'exit' can fire with output still in the pipes, and the session id is
+    // the last thing Hermes prints. 'close' means they are drained — but it
+    // never comes while a process the agent left running holds them open, so
+    // it is only waited for briefly.
     const exitCode = await new Promise((resolve) => {
-      proc.on('exit', resolve);
-      proc.on('error', () => resolve(-1));
+      let code = null;
+      let drain = null;
+      const done = () => { clearTimeout(drain); resolve(code); };
+      proc.on('exit', (c) => { code = c; drain = setTimeout(done, 1000); });
+      proc.on('close', done);
+      proc.on('error', (e) => { spawnError = e; code = -1; done(); });
     });
     delete this._channelProcesses[channelName];
 
-    if (exitCode !== 0) {
-      if (resumeId) {
-        // Resume may have failed because the session was deleted — drop it and retry fresh
-        this._log(`Hermes resume failed (code=${exitCode}), retrying without resume`);
-        delete this._channelSessions[channelName];
-        this._saveSessions();
-        return this._runHermes(prompt, channelName);
-      }
-      const detail = (stderr || stdout).trim().slice(0, 600);
-      throw new Error(`hermes exited with code ${exitCode}: ${detail}`);
-    }
-
     // Hermes -Q mode: response body on stdout, session metadata
     // (session_id:, resume banner) on stderr — parse both streams.
     const { text, sessionId } = this._parseHermesOutput(stdout, stderr);
-    if (sessionId) {
-      this._channelSessions[channelName] = sessionId;
+    return {
+      stopped: this._stopRequestedDuringTurn(channelName),
+      exitCode,
+      text,
+      sessionId,
+      detail: spawnError ? spawnError.message : this._stderrDetail(stderr),
+    };
+  }
+
+  /**
+   * One prompt-and-run against a given session (null starts a new one), and
+   * the bookkeeping that follows from it.
+   */
+  async _attemptTurn(channelName, content, resumeId) {
+    const instructions = this._buildWorkspaceInstructions(channelName);
+    const prefillFile = await this._writePrefill(instructions);
+    let run;
+    try {
+      const prompt = await this._buildPrompt(channelName, content, resumeId, prefillFile ? '' : instructions);
+      run = await this._runHermes(prompt, channelName, resumeId, prefillFile);
+    } finally {
+      // Hermes reads it once, at startup.
+      if (prefillFile) try { fs.unlinkSync(prefillFile); } catch {}
+    }
+
+    // Whatever the exit code, a reported session exists and holds this turn.
+    if (run.sessionId && run.sessionId !== this._channelSessions[channelName]) {
+      this._channelSessions[channelName] = run.sessionId;
       this._saveSessions();
     }
-    return text;
+    return run;
+  }
+
+  /**
+   * Answer one message in the channel's Hermes session, starting a new session
+   * only when there is none to resume.
+   *
+   * Hermes exits non-zero for every turn that does not finish: a provider
+   * error, the iteration limit, a user stop. Each of those still prints the
+   * session id — the session is intact and the turn is in it — so none of them
+   * is a reason to let go of it. Reading any non-zero exit as "the resume
+   * failed" used to drop the session and run the same prompt again in an empty
+   * one: the conversation was lost, the work was done twice (tool calls
+   * included, for a turn that had spent its iterations), and the user was
+   * shown the second failure instead of Hermes's account of the first.
+   *
+   * What does call for a new session is a resumed turn that never began — no
+   * session id comes back, typically with "Session not found". The saved id is
+   * only replaced once the new run reports one of its own, or dropped when
+   * Hermes said outright that it is gone: a Hermes that cannot start at all
+   * (no credentials, say) says nothing about the session either.
+   */
+  async _converse(channelName, content) {
+    const resumeId = this._channelSessions[channelName] || null;
+    const run = await this._attemptTurn(channelName, content, resumeId);
+    const neverBegan = !run.stopped && run.exitCode !== 0 && !run.sessionId;
+    if (!resumeId || !neverBegan) return run;
+
+    this._log(`Hermes could not resume session ${resumeId} (code=${run.exitCode}), starting a new one`);
+    if (SESSION_NOT_FOUND_RE.test(run.detail)) this._forgetSession(channelName);
+    return this._attemptTurn(channelName, content, null);
   }
 
   async _stopProcess(proc) {
@@ -427,14 +696,20 @@ class HermesAdapter extends BaseAdapter {
     await this.sendStatus(msgChannel, 'thinking...');
 
     try {
-      const context = await this._buildContextPrefix(msgChannel);
-      const prompt = context ? `${context}\n\n---\n\nUser message:\n${content}` : content;
-      const responseText = await this._runHermes(prompt, msgChannel);
-
-      if (responseText) {
-        await this.sendResponse(msgChannel, responseText);
+      const run = await this._converse(msgChannel, content);
+      // The stop handler has already told the channel.
+      if (run.stopped) return;
+
+      if (run.exitCode === 0) {
+        await this.sendResponse(msgChannel, run.text || 'No response generated. Please try again.');
+      } else if (run.text) {
+        // The turn did not finish, and stdout is Hermes's own account of why,
+        // after whatever answer it had reached. Worth more to the user than
+        // an exit code.
+        this._log(`Hermes turn did not finish (code=${run.exitCode})`);
+        await this.sendError(msgChannel, run.text);
       } else {
-        await this.sendResponse(msgChannel, 'No response generated. Please try again.');
+        throw new Error(`hermes exited with code ${run.exitCode}: ${run.detail.slice(0, 600)}`);
       }
     } catch (e) {
       this._log(`Hermes adapter error: ${e.message}`);
@@ -446,6 +721,27 @@ class HermesAdapter extends BaseAdapter {
   // Static: configure Hermes's native model config from LLM env vars
   // ------------------------------------------------------------------
 
+  /**
+   * Remove prefill files a killed daemon left in `dir`: only ours, only once
+   * older than `maxAgeMs`. Best effort. Returns how many were removed.
+   */
+  static sweepStalePrefillFiles(dir = os.tmpdir(), maxAgeMs = STALE_PREFILL_MS, now = Date.now()) {
+    let removed = 0;
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return 0; }
+    for (const name of names) {
+      if (!PREFILL_FILE_RE.test(name)) continue;
+      const file = path.join(dir, name);
+      try {
+        const st = fs.lstatSync(file);
+        if (!st.isFile() || now - st.mtimeMs <= maxAgeMs) continue;
+        fs.unlinkSync(file);
+        removed++;
+      } catch {}
+    }
+    return removed;
+  }
+
   /**
    * Point Hermes at a custom OpenAI-compatible endpoint from user-provided
    * LLM_API_KEY / LLM_BASE_URL / LLM_MODEL values. Called by saveAgentEnv when

package/src/adapters/opencode.js

@@ -24,6 +24,7 @@ const BaseAdapter = require('./base');
 const { formatAttachmentsForPrompt, redactSecrets } = require('./utils');
 const { buildOpenCodeSkillMd, buildOpenCodeSystemPrompt, workspaceSkillName } = require('./workspace-prompt');
 const { whichBinary, whereBinary, getEnhancedEnv } = require('../paths');
+const { isPostinstallStub, isPostinstallStubOutput } = require('../postinstall-stub');
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -68,6 +69,7 @@ const CUSTOM_PROVIDER_ID = 'openagents-gateway';
 const FAILURE_MESSAGES = {
   cli_not_found: `OpenCode CLI not found. Install it (\`npm install -g opencode-ai@${OPENCODE_PINNED_VERSION}\`) and try again.`,
   cli_not_executable: 'OpenCode CLI was found but could not be started. Reinstall it, then retry.',
+  install_incomplete: `OpenCode is installed, but its setup never finished: the opencode-ai package's postinstall script did not run (npm \`ignore-scripts\`, or a pnpm/bun install), so the \`opencode\` command is only a placeholder. Reinstall OpenCode from the launcher — or, for a copy you installed yourself, run \`npm install -g opencode-ai@${OPENCODE_PINNED_VERSION} --ignore-scripts=false\` — then retry.`,
   unsupported_version: `This OpenCode CLI version is not supported (requires >= ${OPENCODE_MIN_VERSION}). Reinstall \`opencode-ai@${OPENCODE_PINNED_VERSION}\` and retry.`,
   model_missing: "No model is configured for OpenCode. Set a model (LLM_MODEL, e.g. `gpt-4o`) in this agent's configuration, then retry.",
   credential_missing: 'OpenCode has no API key or sign-in configured. Add an API key (LLM_API_KEY) or run `opencode auth login`, then retry.',
@@ -1063,7 +1065,18 @@ class OpenCodeAdapter extends BaseAdapter {
     if (binary) this._opencodeBinary = binary;
     if (!binary) return { ok: false, category: 'cli_not_found' };
 
+    // Before every other check: the placeholder a skipped postinstall leaves
+    // behind has no version and runs no model, so each later check would blame
+    // the wrong thing — "no model configured" first, then an unexplained exit 1
+    // on every message once a model is set.
+    if (isPostinstallStub(binary)) {
+      return { ok: false, category: 'install_incomplete', diagnostic: `${binary} is the package's postinstall placeholder` };
+    }
+
     const probe = this._detectCliVersion(binary);
+    if (probe.stub) {
+      return { ok: false, category: 'install_incomplete', diagnostic: `${binary} --version answered as the package's postinstall placeholder` };
+    }
     if (!probe.executable) {
       return { ok: false, category: 'cli_not_executable', diagnostic: 'opencode --version did not run' };
     }
@@ -1097,7 +1110,9 @@ class OpenCodeAdapter extends BaseAdapter {
   /**
    * Probe the CLI's version and executability, cached briefly so preflight never
    * spawns `--version` more than once per VERSION_PROBE_TTL_MS across channels.
-   * Returns { version: string|null, executable: boolean }.
+   * Returns { version: string|null, executable: boolean, stub: boolean } —
+   * `stub` when what answered was the package's postinstall placeholder, which
+   * a wrapper script in front of it (pnpm, bun) hides from a look at the file.
    */
   _detectCliVersion(binary) {
     const now = Date.now();
@@ -1106,6 +1121,7 @@ class OpenCodeAdapter extends BaseAdapter {
     }
     let version = null;
     let executable = false;
+    let stub = false;
     try {
       const raw = execSync(`"${binary}" --version`, {
         encoding: 'utf-8',
@@ -1126,9 +1142,13 @@ class OpenCodeAdapter extends BaseAdapter {
         const out = String((e && (e.stdout || e.stderr)) || '');
         const m = out.match(/(\d+\.\d+\.\d+)/);
         version = m ? m[1] : null;
+        stub = isPostinstallStubOutput(`${(e && e.stdout) || ''}\n${(e && e.stderr) || ''}`);
       }
     }
-    this._versionProbe = { version, executable, ts: now };
+    // A placeholder is not cached: the fix is a reinstall, and the message
+    // right after it must not still be answered from the broken copy.
+    if (stub) return { version, executable, stub, ts: now };
+    this._versionProbe = { version, executable, stub, ts: now };
     return this._versionProbe;
   }
 
@@ -1301,7 +1321,9 @@ class OpenCodeAdapter extends BaseAdapter {
     const has = (re) => re.test(hay);
 
     let category;
-    if (has(/\b(401|403)\b/) || has(/unauthor|invalid api key|invalid_api_key|authentication|auth(entication)? failed|forbidden|invalid token|no api key|missing api key|permission denied/)) {
+    if (isPostinstallStubOutput(hay)) {
+      category = 'install_incomplete';
+    } else if (has(/\b(401|403)\b/) || has(/unauthor|invalid api key|invalid_api_key|authentication|auth(entication)? failed|forbidden|invalid token|no api key|missing api key|permission denied/)) {
       category = 'auth_failed';
     } else if (has(/\b429\b/) || has(/rate.?limit|too many requests|quota|overloaded/)) {
       category = 'rate_limited';