@pixelbyte-software/pixcode 1.49.8 → 1.49.10

package/scripts/smoke/hermes-rest-chat-api.mjs

@@ -0,0 +1,131 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ensureHermesGateway,
+  runHermesGatewayPrompt,
+  stopHermesGateway,
+} from '../../server/services/hermes-gateway.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pixcode-hermes-chat-api-'));
+const fakeHermes = path.join(tempRoot, 'hermes');
+const projectPath = path.join(tempRoot, 'project');
+const hermesHome = path.join(tempRoot, 'home');
+
+await fs.mkdir(projectPath, { recursive: true });
+await fs.writeFile(fakeHermes, `#!/usr/bin/env node
+import http from 'node:http';
+
+if (process.argv.includes('--version')) {
+  console.log('Hermes Agent v0.0.0 smoke');
+  process.exit(0);
+}
+
+if (!process.argv.includes('gateway')) {
+  console.error('expected gateway');
+  process.exit(2);
+}
+
+const host = process.env.API_SERVER_HOST || '127.0.0.1';
+const port = Number(process.env.API_SERVER_PORT || 8642);
+const key = process.env.API_SERVER_KEY || '';
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url || '/', 'http://127.0.0.1');
+  res.setHeader('content-type', 'application/json');
+  if (url.pathname !== '/health' && req.headers.authorization !== \`Bearer \${key}\`) {
+    res.statusCode = 401;
+    res.end(JSON.stringify({ error: 'bad auth' }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/health') {
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/v1/capabilities') {
+    res.end(JSON.stringify({ capabilities: ['chat'] }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/v1/models') {
+    res.end(JSON.stringify({ data: [{ id: 'hermes-agent' }] }));
+    return;
+  }
+  if (req.method === 'POST' && url.pathname === '/v1/chat/completions') {
+    let body = '';
+    for await (const chunk of req) body += chunk.toString();
+    const parsed = body ? JSON.parse(body) : {};
+    res.end(JSON.stringify({
+      id: 'chatcmpl-smoke',
+      choices: [{
+        index: 0,
+        message: {
+          role: 'assistant',
+          content: \`pixcode-hermes-chat-ok via \${parsed.model}\`,
+        },
+        finish_reason: 'stop',
+      }],
+    }));
+    return;
+  }
+  if (req.method === 'POST' && url.pathname === '/v1/responses') {
+    let body = '';
+    for await (const chunk of req) body += chunk.toString();
+    const parsed = body ? JSON.parse(body) : {};
+    res.end(JSON.stringify({
+      id: 'resp-smoke',
+      object: 'response',
+      status: 'completed',
+      model: parsed.model || 'hermes-agent',
+      output: [{
+        type: 'message',
+        role: 'assistant',
+        content: [{
+          type: 'output_text',
+          text: \`pixcode-hermes-rest-ok via \${parsed.model}\`,
+        }],
+      }],
+    }));
+    return;
+  }
+  res.statusCode = 404;
+  res.end(JSON.stringify({ error: url.pathname }));
+});
+server.listen(port, host);
+`, { mode: 0o755 });
+
+process.env.HERMES_CLI_PATH = fakeHermes;
+
+try {
+  const gateway = await ensureHermesGateway({
+    appRoot: repoRoot,
+    projectPath,
+    hermesHome,
+    pixcodeBaseUrl: 'http://127.0.0.1:9',
+    pixcodeApiKey: 'px_chat_api_smoke_key',
+    port: 18752,
+    allowSmokeHermes: true,
+    repairLaunchers: false,
+  });
+  if (!gateway.running || !gateway.probe?.ok) {
+    throw new Error(`Fake Hermes gateway did not start cleanly: ${JSON.stringify(gateway)}`);
+  }
+
+  const run = await runHermesGatewayPrompt(projectPath, {
+    input: 'selam',
+    timeoutMs: 10000,
+  });
+  if (!run.ok || run.transport !== 'responses' || !String(run.message || '').includes('pixcode-hermes-rest-ok')) {
+    throw new Error(`Hermes REST chat did not use responses: ${JSON.stringify(run)}`);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    transport: run.transport,
+    message: run.message,
+  }, null, 2));
+} finally {
+  stopHermesGateway(projectPath);
+  delete process.env.HERMES_CLI_PATH;
+}

package/scripts/smoke/hermes-rest-chat-live.mjs

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ensureHermesGateway,
+  runHermesGatewayPrompt,
+  stopHermesGateway,
+} from '../../server/services/hermes-gateway.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const projectPath = path.resolve(process.argv[2] || repoRoot);
+
+try {
+  const gateway = await ensureHermesGateway({
+    appRoot: repoRoot,
+    projectPath,
+    pixcodeBaseUrl: 'http://127.0.0.1:9',
+    pixcodeApiKey: 'px_live_chat_smoke_key',
+    port: Number(process.env.PIXCODE_HERMES_LIVE_CHAT_PORT || 18652),
+  });
+  if (!gateway.running || !gateway.probe?.ok) {
+    throw new Error(`Hermes gateway did not start cleanly: ${JSON.stringify(gateway)}`);
+  }
+
+  const run = await runHermesGatewayPrompt(projectPath, {
+    input: 'Reply with exactly: pixcode-hermes-chat-ok',
+    timeoutMs: 90000,
+  });
+  if (!run.ok || !String(run.message || '').includes('pixcode-hermes-chat-ok')) {
+    throw new Error(`Hermes chat did not return the expected response: ${JSON.stringify(run)}`);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    transport: run.transport,
+    status: run.status,
+    message: run.message,
+  }, null, 2));
+} finally {
+  stopHermesGateway(projectPath);
+}

package/scripts/smoke/hermes-rest-gateway.mjs

@@ -13,10 +13,15 @@ assert.match(service, /export async function ensureHermesGateway/, 'Pixcode shou
 assert.match(service, /export async function probeHermesGateway/, 'Pixcode should probe Hermes through its REST API.');
 assert.match(service, /export async function runHermesGatewayPrompt/, 'Pixcode should submit Hermes prompts through the managed REST gateway.');
 assert.match(service, /export function stopHermesGateway/, 'Pixcode should be able to stop a managed Hermes gateway process.');
+assert.match(service, /\/v1\/chat\/completions/, 'Hermes UI chat should use the documented OpenAI-compatible chat completions endpoint first.');
+assert.match(service, /\/v1\/responses/, 'Hermes UI chat should use the stateful OpenAI-compatible responses endpoint before legacy chat fallback.');
+assert.match(service, /transport:\s*'responses'/, 'Hermes REST responses should report their transport for terminal proof output.');
+assert.match(service, /gatewayArgs[\s\S]+\['gateway', 'run', '--replace'\]/, 'Pixcode should start Hermes gateway in replace mode so an existing gateway does not crash REST chat.');
+assert.match(service, /gatewayExitMessage/, 'Hermes gateway failures should include recent stderr/stdout instead of only exit code 1.');
 assert.match(service, /API_SERVER_ENABLED:\s*'true'/, 'Hermes gateway env should enable the API server.');
 assert.match(service, /API_SERVER_KEY/, 'Hermes gateway env should set a bearer key.');
 assert.match(service, /API_SERVER_PORT/, 'Hermes gateway env should choose a REST port.');
-assert.match(service, /spawn\(installStatus\.command,\s*\['gateway'\]/, 'Pixcode should start Hermes with `hermes gateway` for REST control.');
+assert.match(service, /spawn\(installStatus\.command,\s*gatewayArgs/, 'Pixcode should start Hermes with explicit gateway args for REST control.');
 assert.match(service, /\/health/, 'Gateway probe should call Hermes health.');
 assert.match(service, /\/v1\/capabilities/, 'Gateway probe should verify Hermes capabilities.');
 assert.match(service, /\/v1\/models/, 'Gateway probe should verify OpenAI-compatible model discovery.');

package/scripts/smoke/hermes-smoke-launcher-guard.mjs

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  readHermesInstallStatus,
+} from '../../server/services/hermes-install-jobs.js';
+
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pixcode-hermes-smoke-guard-'));
+const fakeHermes = path.join(tempRoot, 'hermes');
+
+await fs.writeFile(fakeHermes, `#!/usr/bin/env bash
+if [ "$1" = "--version" ]; then
+  echo "Hermes Agent v0.0.0 smoke"
+  exit 0
+fi
+echo "fake smoke hermes should not run"
+exit 2
+`, { mode: 0o755 });
+
+const status = readHermesInstallStatus({
+  ...process.env,
+  HERMES_CLI_PATH: fakeHermes,
+  PATH: tempRoot,
+}, {
+  repairLaunchers: false,
+});
+
+assert.notEqual(status.command, fakeHermes, 'Smoke-test HERMES_CLI_PATH must not be selected as the Hermes command.');
+assert.doesNotMatch(String(status.version || ''), /smoke/i, 'Smoke-test Hermes version output must not be reported as installed.');
+assert.doesNotMatch(String(status.error || ''), /fake smoke hermes should not run/i, 'Smoke launcher should be rejected before any non-version use.');
+
+console.log('hermes smoke launcher guard passed');

package/scripts/smoke/pixcode-workbench-1-48.mjs

@@ -67,6 +67,9 @@ assert.match(workbench, /isPlainShell/, 'Bottom terminal should open the selecte
 assert.doesNotMatch(workbench, /HERMES_AGENT_START_COMMAND/, 'Hermes Agent should not launch from the bottom terminal through a server-side sentinel.');
 assert.match(workbench, /HermesApiChatPanel/, 'Hermes Agent should render a REST-backed chat panel in the bottom area.');
 assert.match(workbench, /\/api\/orchestration\/hermes\/gateway\/chat/, 'Hermes chat panel should send prompts through the Pixcode gateway chat API.');
+assert.match(workbench, /HermesTerminalTranscript/, 'Hermes REST panel should render as a terminal transcript, not chat bubbles.');
+assert.match(workbench, /REST POST \//, 'Hermes terminal transcript should show the REST endpoint used for each reply.');
+assert.doesNotMatch(workbench, /ml-auto border-blue-500\/40 bg-blue-500\/10/, 'Hermes REST panel must not use right-aligned chat bubbles.');
 assert.match(workbench, /terminal-launches\/stream/, 'Hermes CLI launch requests should arrive through an EventSource stream.');
 assert.doesNotMatch(workbench, /HERMES_TERMINAL_LAUNCH_POLL_MS|setInterval\([\s\S]*terminal-launches/, 'Hermes CLI launch requests should not be polled every few seconds.');
 assert.doesNotMatch(workbench, /Project-scoped agent terminal\. Installs Hermes when missing/, 'Right CLI panel should not show the old Hermes card.');
@@ -85,6 +88,7 @@ assert.doesNotMatch(workbench, /suspendAutoConnect/, 'Right CLI provider starts
 assert.match(serverIndex, /\/api\/shell\/sessions\/terminate/, 'Backend should expose an authenticated endpoint to terminate cached provider PTYs immediately.');
 assert.match(serverIndex, /isPlainShell && !initialCommand/, 'Backend should spawn an interactive plain shell when no terminal command is provided.');
 assert.doesNotMatch(serverIndex, /pixcode:hermes:start/, 'Backend should not need a Hermes terminal sentinel for the workbench Hermes panel.');
+assert.doesNotMatch(serverIndex, /hermesCommand/, 'Provider shell starts should not reference the removed Hermes sentinel variable.');
 assert.doesNotMatch(hermesInstallJobs, /iex \(irm https:\/\/raw\.githubusercontent\.com\/NousResearch\/hermes-agent\/main\/scripts\/install\.ps1\)/, 'Windows Hermes install should avoid the old inline iex pattern.');
 assert.doesNotMatch(hermesInstallJobs, /scriptblock\]::Create\(\(irm https:\/\/raw\.githubusercontent\.com\/NousResearch\/hermes-agent\/main\/scripts\/install\.ps1\)\)/, 'Windows Hermes install should avoid scriptblock Invoke-RestMethod eval patterns.');
 assert.match(hermesInstallJobs, /downloadHermesInstaller/, 'Windows Hermes install should download the installer through backend API code before running it.');

package/server/index.js

@@ -2266,7 +2266,7 @@ function handleShellConnection(ws, request) {
                 console.log('📋 Session info:', hasSession ? `Resume session ${sessionId}` : (isPlainShell ? 'Plain shell mode' : 'New session'));
                 console.log('🤖 Provider:', isPlainShell ? 'plain-shell' : provider);
                 if (initialCommand) {
-                    console.log('⚡ Initial command:', hermesCommand ? hermesCommand : initialCommand);
+                    console.log('⚡ Initial command:', initialCommand || 'interactive shell');
                 }
 
                 // First send a welcome message
@@ -2413,7 +2413,7 @@ function handleShellConnection(ws, request) {
                         }
                     }
 
-                    console.log('🔧 Executing shell command:', hermesCommand ? hermesCommand : (shellCommand || 'interactive shell'));
+                    console.log('🔧 Executing shell command:', shellCommand || 'interactive shell');
 
                     // Use appropriate shell based on platform
                     const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';

package/server/services/hermes-gateway.js

@@ -173,6 +173,64 @@ function extractRunOutput(body) {
     return null;
 }
 
+function extractResponsesOutput(body) {
+    if (!body || typeof body !== 'object') return null;
+
+    const output = Array.isArray(body.output) ? body.output : [];
+    for (const item of output) {
+        if (!item || typeof item !== 'object') continue;
+        if (item.type === 'message' || item.role === 'assistant') {
+            const text = extractTextFromValue(item.content);
+            if (text) return text;
+        }
+        const text = extractTextFromValue(item.output_text)
+            || extractTextFromValue(item.text)
+            || extractTextFromValue(item.message)
+            || extractTextFromValue(item.output);
+        if (text) return text;
+    }
+
+    return extractTextFromValue(body.output_text)
+        || extractTextFromValue(body.message)
+        || extractTextFromValue(body.response)
+        || null;
+}
+
+function extractChatCompletionOutput(body) {
+    if (!body || typeof body !== 'object') return null;
+    const choices = Array.isArray(body.choices) ? body.choices : [];
+    for (const choice of choices) {
+        const text = extractTextFromValue(choice?.message?.content)
+            || extractTextFromValue(choice?.delta?.content)
+            || extractTextFromValue(choice?.text);
+        if (text) return text;
+    }
+    return extractTextFromValue(body.output_text)
+        || extractTextFromValue(body.output)
+        || extractTextFromValue(body.message)
+        || extractTextFromValue(body.response)
+        || null;
+}
+
+function recentGatewayLogText(gateway) {
+    if (!gateway?.logs?.length) return '';
+    return gateway.logs
+        .slice(-16)
+        .map((entry) => String(entry.chunk || '').trim())
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+}
+
+function gatewayExitMessage(gateway, fallback = 'Hermes gateway is not running.') {
+    if (!gateway) return fallback;
+    const exit = gateway.exitSignal
+        ? `Hermes gateway exited with signal ${gateway.exitSignal}.`
+        : `Hermes gateway exited with code ${gateway.exitCode ?? 'unknown'}.`;
+    const logs = recentGatewayLogText(gateway);
+    return logs ? `${exit}\n${logs}` : (gateway.error || exit);
+}
+
 function makeRunRequest(options) {
     const input = String(options.input || '').trim();
     return {
@@ -186,13 +244,51 @@ function makeRunRequest(options) {
     };
 }
 
+function makeChatCompletionRequest(options) {
+    const input = String(options.input || '').trim();
+    const messages = Array.isArray(options.messages) ? options.messages : [
+        {
+            role: 'system',
+            content: options.instructions || [
+                'You are Hermes Agent running inside Pixcode.',
+                'Use Pixcode MCP tools when they help inspect projects, launch CLIs, or perform workspace actions.',
+                'Keep answers concise and include concrete next steps when work is blocked.',
+            ].join(' '),
+        },
+        {
+            role: 'user',
+            content: input,
+        },
+    ];
+    return {
+        model: options.model || 'hermes-agent',
+        messages,
+        stream: false,
+    };
+}
+
+function makeResponsesRequest(options) {
+    const input = String(options.input || '').trim();
+    return {
+        model: options.model || 'hermes-agent',
+        input,
+        instructions: options.instructions || [
+            'You are Hermes Agent running inside Pixcode.',
+            'Use Pixcode MCP tools when they help inspect projects, launch CLIs, or perform workspace actions.',
+            'Keep answers concise and include concrete next steps when work is blocked.',
+        ].join(' '),
+        conversation: options.sessionId || undefined,
+        store: true,
+    };
+}
+
 async function waitForGatewayReady(gateway) {
     const started = Date.now();
     let lastError = null;
 
     while (Date.now() - started < STARTUP_TIMEOUT_MS) {
         if (!isGatewayRunning(gateway)) {
-            throw new Error(gateway.error || `Hermes gateway exited with code ${gateway.exitCode ?? 'unknown'}.`);
+            throw new Error(gatewayExitMessage(gateway));
         }
 
         try {
@@ -319,7 +415,10 @@ export async function ensureHermesGateway(options = {}) {
         apiServerKey,
         appRoot,
     });
-    const installStatus = readHermesInstallStatus(env);
+    const installStatus = readHermesInstallStatus(env, {
+        allowSmokeHermes: options.allowSmokeHermes === true,
+        repairLaunchers: options.repairLaunchers !== false,
+    });
     if (!installStatus.installed || !installStatus.command) {
         throw new Error(installStatus.error || 'Hermes Agent CLI is not installed.');
     }
@@ -345,14 +444,15 @@ export async function ensureHermesGateway(options = {}) {
 
     await configurePixcodeMcp({ appRoot, env, gateway });
 
-    const child = spawn(installStatus.command, ['gateway'], {
+    const gatewayArgs = options.gatewayArgs || ['gateway', 'run', '--replace'];
+    const child = spawn(installStatus.command, gatewayArgs, {
         cwd: projectPath,
         env,
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
     });
     gateway.child = child;
-    appendGatewayLog(gateway, 'meta', `$ ${installStatus.command} gateway\n`);
+    appendGatewayLog(gateway, 'meta', `$ ${installStatus.command} ${gatewayArgs.join(' ')}\n`);
 
     child.stdout?.on('data', (buf) => appendGatewayLog(gateway, 'stdout', buf.toString()));
     child.stderr?.on('data', (buf) => appendGatewayLog(gateway, 'stderr', buf.toString()));
@@ -458,13 +558,99 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
         throw new Error('Hermes prompt is required.');
     }
 
+    const responsesRequest = makeResponsesRequest({ ...options, input });
+    const responseRun = await callGateway(gateway, '/v1/responses', {
+        method: 'POST',
+        body: JSON.stringify(responsesRequest),
+        timeoutMs: options.responsesTimeoutMs || options.timeoutMs || RUN_TIMEOUT_MS,
+    }).catch((error) => {
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gatewayExitMessage(gateway));
+        }
+        throw error;
+    });
+
+    if (!isGatewayRunning(gateway)) {
+        throw new Error(gatewayExitMessage(gateway));
+    }
+
+    if (responseRun.ok) {
+        const status = extractRunStatus(responseRun.body) || 'completed';
+        const message = extractResponsesOutput(responseRun.body);
+        return {
+            ok: status === 'completed' || status === 'succeeded',
+            projectPath: gateway.projectPath,
+            baseUrl: gateway.baseUrl,
+            sessionId: options.sessionId || responsesRequest.conversation || null,
+            runId: null,
+            responseId: responseRun.body?.id || null,
+            status,
+            message,
+            error: (status === 'completed' || status === 'succeeded') ? null : extractTextFromValue(responseRun.body?.error) || message || 'Hermes response failed.',
+            raw: responseRun.body,
+            transport: 'responses',
+            endpoint: '/v1/responses',
+            httpStatus: responseRun.status,
+        };
+    }
+
+    if (responseRun.status && responseRun.status !== 404 && responseRun.status !== 405) {
+        throw new Error(`Hermes /v1/responses failed with HTTP ${responseRun.status}: ${JSON.stringify(responseRun.body)}`);
+    }
+
+    const chatRequest = makeChatCompletionRequest({ ...options, input });
+    const chat = await callGateway(gateway, '/v1/chat/completions', {
+        method: 'POST',
+        body: JSON.stringify(chatRequest),
+        timeoutMs: options.chatTimeoutMs || options.timeoutMs || RUN_TIMEOUT_MS,
+    }).catch((error) => {
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gatewayExitMessage(gateway));
+        }
+        throw error;
+    });
+
+    if (!isGatewayRunning(gateway)) {
+        throw new Error(gatewayExitMessage(gateway));
+    }
+
+    if (chat.ok) {
+        const message = extractChatCompletionOutput(chat.body);
+        return {
+            ok: true,
+            projectPath: gateway.projectPath,
+            baseUrl: gateway.baseUrl,
+            sessionId: options.sessionId || null,
+            runId: null,
+            status: 'completed',
+            message,
+            raw: chat.body,
+            transport: 'chat.completions',
+            endpoint: '/v1/chat/completions',
+            httpStatus: chat.status,
+        };
+    }
+
+    if (chat.status && chat.status !== 404 && chat.status !== 405) {
+        throw new Error(`Hermes /v1/chat/completions failed with HTTP ${chat.status}: ${JSON.stringify(chat.body)}`);
+    }
+
     const request = makeRunRequest({ ...options, input });
     const create = await callGateway(gateway, '/v1/runs', {
         method: 'POST',
         body: JSON.stringify(request),
         timeoutMs: options.createTimeoutMs || 15000,
+    }).catch((error) => {
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gatewayExitMessage(gateway));
+        }
+        throw error;
     });
 
+    if (!isGatewayRunning(gateway)) {
+        throw new Error(gatewayExitMessage(gateway));
+    }
+
     if (!create.ok) {
         throw new Error(`Hermes /v1/runs failed with HTTP ${create.status}: ${JSON.stringify(create.body)}`);
     }
@@ -481,6 +667,9 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
             status: initialStatus || 'completed',
             message: extractRunOutput(create.body),
             raw: create.body,
+            transport: 'runs',
+            endpoint: '/v1/runs',
+            httpStatus: create.status,
         };
     }
 
@@ -497,6 +686,9 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
         if (!poll.ok) {
             throw new Error(`Hermes /v1/runs/${runId} failed with HTTP ${poll.status}: ${JSON.stringify(poll.body)}`);
         }
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gatewayExitMessage(gateway));
+        }
         latest = poll.body;
         status = extractRunStatus(latest) || status;
     }
@@ -516,6 +708,9 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
         message,
         error: status === 'completed' ? null : extractTextFromValue(latest?.error) || message || 'Hermes run failed.',
         raw: latest,
+        transport: 'runs',
+        endpoint: '/v1/runs',
+        httpStatus: create.status,
     };
 }
 

package/server/services/hermes-install-jobs.js

@@ -144,8 +144,40 @@ function runHermesVersion(candidate, env) {
     }
 }
 
-export function isUsableHermesCommand(candidate, env = process.env) {
-    return runHermesVersion(candidate, buildHermesEnv(env)).ok;
+function isHermesSmokeCommandOutput(output) {
+    return /Hermes Agent v0\.0\.0\s+smoke/i.test(String(output || ''))
+        || /pixcode-hermes-(?:chat-api|smoke)/i.test(String(output || ''));
+}
+
+function isExplicitHermesCliPath(candidate, env = process.env) {
+    if (!candidate || !env.HERMES_CLI_PATH || !path.isAbsolute(candidate)) return false;
+    try {
+        return path.resolve(candidate) === path.resolve(env.HERMES_CLI_PATH);
+    } catch {
+        return false;
+    }
+}
+
+function isTemporaryHermesLauncher(candidate) {
+    if (!candidate || !path.isAbsolute(candidate)) return false;
+    const normalized = path.resolve(candidate);
+    const tempRoot = path.resolve(os.tmpdir());
+    return normalized === tempRoot || normalized.startsWith(`${tempRoot}${path.sep}`);
+}
+
+function shouldRepairHermesLauncher(command, env = process.env, options = {}) {
+    if (options.repairLaunchers === false) return false;
+    if (!command || command === 'hermes') return false;
+    if (isExplicitHermesCliPath(command, env)) return false;
+    if (isTemporaryHermesLauncher(command)) return false;
+    return true;
+}
+
+export function isUsableHermesCommand(candidate, env = process.env, options = {}) {
+    const result = runHermesVersion(candidate, buildHermesEnv(env));
+    if (!result.ok) return false;
+    if (!options.allowSmokeHermes && isHermesSmokeCommandOutput(result.output)) return false;
+    return true;
 }
 
 function isHermesPythonLauncher(candidate) {
@@ -313,8 +345,9 @@ export function hermesCommandCandidates(env = process.env) {
     return [...new Set(candidates.filter(Boolean))];
 }
 
-export function readHermesInstallStatus(env = process.env) {
+export function readHermesInstallStatus(env = process.env, options = {}) {
     const hermesEnv = buildHermesEnv(env);
+    const rejected = [];
 
     for (const candidate of hermesCommandCandidates(hermesEnv)) {
         const isBareCommand = candidate === 'hermes';
@@ -324,8 +357,16 @@ export function readHermesInstallStatus(env = process.env) {
 
         const result = runHermesVersion(candidate, hermesEnv);
         if (result.ok) {
-            repairHermesCommandLaunchers(candidate, hermesEnv);
             const version = formatHermesVersionOutput(result.output);
+            if (!options.allowSmokeHermes && isHermesSmokeCommandOutput(result.output)) {
+                rejected.push(`${candidate} (${version || 'smoke-test Hermes launcher'})`);
+                continue;
+            }
+
+            if (shouldRepairHermesLauncher(candidate, hermesEnv, options)) {
+                repairHermesCommandLaunchers(candidate, hermesEnv);
+            }
+
             return {
                 installed: true,
                 command: candidate,
@@ -339,7 +380,9 @@ export function readHermesInstallStatus(env = process.env) {
         installed: false,
         command: null,
         version: null,
-        error: 'Hermes Agent CLI is not installed or is not on PATH.',
+        error: rejected.length > 0
+            ? `Only smoke-test Hermes launchers were found and rejected: ${rejected.join(', ')}. Install or repair Hermes Agent.`
+            : 'Hermes Agent CLI is not installed or is not on PATH.',
     };
 }