@rockysoft/opencode-hybrid-workflow 0.9.0 → 0.9.1

package/core/workers.mjs

@@ -1,202 +1,202 @@
-import {documentTool} from '../lib/public-document.mjs';
-import {reviewer} from '../lib/reviewers.mjs';
-import { spawn, spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { Telemetry, jsonLineReader } from './telemetry.mjs';
-import { findingSchema, isMajor } from './decision.mjs';
-import {processIdentity} from './process-identity.mjs';
-import {commandSpec} from '../lib/commands.mjs';
-import {commandEnvironment} from '../lib/platform.mjs';
-import {prepareBrowser,browserTools,browserInstructions} from '../lib/reviewer-browser.mjs';
-import {evidenceServer,queryInstructions,queryTool} from '../lib/evidence-mcp.mjs';
-
-export const resultSchema = {
-  type: 'object', additionalProperties: false,
-  properties: {
-    verdict: { type: 'string', enum: ['pass', 'revise', 'blocked'] },
-    report: { type: 'string' },
-    findings: { type: 'array', items: findingSchema },
-    verifiedResolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
-  }, required: ['verdict', 'report', 'findings', 'verifiedResolutions'],
-};
-
-export function workerArgs(who, config, folder, images = [], browser = null, evidence = null) {
-  const lane=reviewer(config,who);
-  // Attachment count is a transport choice, never an evidence quota. Larger
-  // sets stay in the frozen images/ manifest and are opened with view_image.
-  const inlineImages = images.length <= 4 && images.join('').length < 2048 ? images : [];
-  if (lane.adapter === 'codex-cli') return ['exec', '--json', '--ignore-user-config', '--ignore-rules', '--ephemeral', '--skip-git-repo-check',
-    '--sandbox', 'read-only', '-C', folder, '-m', lane.model,
-    // User config is intentionally isolated, so Windows' required sandbox
-    // implementation must be explicit too. Without it shell reads are denied.
-    ...(process.platform === 'win32' ? ['-c', 'windows.sandbox="elevated"'] : []),
-    '-c', 'approval_policy="never"',
-    ...(lane.effort==='default'?[]:['-c', `model_reasoning_effort="${lane.effort??'high'}"`]), '-c', 'web_search="disabled"',
-    ...(browser ? ['-c',`mcp_servers.review_browser.command=${JSON.stringify(browser.command)}`,
-      '-c',`mcp_servers.review_browser.args=${JSON.stringify(browser.args)}`,
-      '-c','mcp_servers.review_browser.startup_timeout_sec=60',
-      '-c','mcp_servers.review_browser.tool_timeout_sec=120',
-      '-c','mcp_servers.review_browser.default_tools_approval_mode="approve"',
-      '-c',`mcp_servers.review_browser.enabled_tools=${JSON.stringify(browserTools)}`] : []),
-    ...(evidence?['-c',`mcp_servers.review_evidence.command=${JSON.stringify(evidence.command)}`,'-c',`mcp_servers.review_evidence.args=${JSON.stringify(evidence.args)}`,
-      '-c','mcp_servers.review_evidence.default_tools_approval_mode="approve"','-c',`mcp_servers.review_evidence.enabled_tools=${JSON.stringify([queryTool,documentTool])}`]:[]),
-    ...inlineImages.flatMap(image=>['--image',image]),
-    '--output-schema', path.join(folder, 'schema.json'), '-o', path.join(folder, 'result.json'), '-'];
-  return ['-p', ...(browser||evidence?['--setting-sources','','--disable-slash-commands','--settings','{"disableAllHooks":true,"enabledPlugins":{}}']:['--safe-mode']), '--restricted', '--strict-mcp-config', '--mcp-config', JSON.stringify({mcpServers:{...(browser?{review_browser:browser}:{}),...(evidence?{review_evidence:evidence}:{})}}),
-    '--no-chrome', '--no-session-persistence', '--permission-mode', 'dontAsk', '--permission-prompts', 'none',
-    '--tools', 'Read,Glob,Grep', '--allowedTools', ['Read','Glob','Grep',...(browser?browserTools.map(name=>'mcp__review_browser__'+name):[]),...(evidence?[queryTool,documentTool].map(name=>'mcp__review_evidence__'+name):[])].join(','),
-    '--model', lane.model, ...(lane.effort==='default'?[]:['--effort',lane.effort??'high']), '--output-format', 'stream-json', '--verbose',
-    '--json-schema', JSON.stringify(resultSchema)];
-}
-
-export function validateResult(value) {
-  if (!value || !['pass', 'revise', 'blocked'].includes(value.verdict) || typeof value.report !== 'string' || !value.report.trim() ||
-      !Array.isArray(value.findings)) throw new Error('Invalid reviewer result; checkpoint stays closed.');
-  if (Object.keys(value).some(key => !['verdict', 'report', 'findings','verifiedResolutions'].includes(key))) throw new Error('Invalid reviewer result fields.');
-  // Existing receipts remain readable. Omission cannot resolve tracked findings.
-  if(value.verifiedResolutions!==undefined&&(!Array.isArray(value.verifiedResolutions)||value.verifiedResolutions.some(r=>!r||Object.keys(r).some(k=>!['id','evidence'].includes(k))||typeof r.id!=='string'||!r.id.trim()||typeof r.evidence!=='string'||!r.evidence.trim())||new Set(value.verifiedResolutions.map(r=>r.id)).size!==value.verifiedResolutions.length))throw Error('Invalid verified resolutions.');
-  const ids = new Set();
-  for (const f of value.findings) {
-    if (!f || typeof f !== 'object' || Array.isArray(f) ||
-        Object.keys(f).some(key => !findingSchema.required.includes(key)) ||
-        findingSchema.required.some(key => typeof f[key] !== 'string' || !f[key].trim()) ||
-        !findingSchema.properties.severity.enum.includes(f.severity) ||
-        !findingSchema.properties.category.enum.includes(f.category) || ids.has(f.id) ||
-        (f.category === 'preference' && isMajor(f))) throw new Error('Invalid structured finding; checkpoint stays closed.');
-    ids.add(f.id);
-  }
-  if ((value.verdict === 'pass' && value.findings.some(isMajor)) ||
-      (value.verdict === 'revise' && !value.findings.length) ||
-      (value.verdict === 'blocked' && !value.findings.some(isMajor))) throw new Error('Inconsistent reviewer verdict; checkpoint stays closed.');
-  return value;
-}
-
-export function workerEnvironment(source = process.env) {
-  const env = {};
-  const allowed = /^(PATH|PATHEXT|SYSTEMROOT|WINDIR|COMSPEC|TEMP|TMP|TMPDIR|HOME|XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_STATE_HOME|XDG_CACHE_HOME|USERPROFILE|APPDATA|LOCALAPPDATA|HOMEDRIVE|HOMEPATH|USERNAME|USERDOMAIN|PROGRAMFILES|PROGRAMFILES\(X86\)|PROGRAMW6432|OS|SYSTEMDRIVE|LANG|LC_ALL)$/i;
-  for (const [key, value] of Object.entries(source)) if (allowed.test(key)) env[key] = value;
-  // Official CLIs retain their normal per-user subscription login; never extract tokens.
-  return commandEnvironment(env);
-}
-
-export function requireSubscription(who, config, folder, invoke = spawnSync) {
-  const lane=reviewer(config,who);
-  if(lane.adapter==='opencode')return;
-  const executable=lane.executable;
-  const args = lane.adapter === 'codex-cli' ? ['login', 'status'] : ['auth', 'status'];
-  const spec=invoke===spawnSync?commandSpec(executable):{executable,args:[]};
-  const result = invoke(spec.executable, [...spec.args,...args], { cwd: folder, env: workerEnvironment(), shell: false, windowsHide: true, encoding: 'utf8', timeout: 15000 });
-  let valid = false;
-  if (result.status === 0 && lane.adapter === 'codex-cli') valid = /Logged in using ChatGPT/i.test((result.stdout ?? '') + (result.stderr ?? ''));
-  if (result.status === 0 && lane.adapter === 'claude-cli') {
-    try { const auth = JSON.parse(result.stdout); valid = auth.loggedIn === true && auth.authMethod === 'claude.ai' && auth.apiProvider === 'firstParty' && !!auth.subscriptionType; } catch {}
-  }
-  if (!valid) throw new Error(`${who}: subscription authentication could not be confirmed. Sign in through the official CLI; API/unknown authentication is refused.`);
-}
-
-export async function runProcess(executable, args, folder, input, timeoutMs, signal, observer = {}) {
-  if (signal?.aborted) throw new Error('Cancelled before launch.');
-  return await new Promise((resolve, reject) => {
-    const spec=commandSpec(executable);
-    const child = spawn(spec.executable, [...spec.args,...args], { cwd: folder, env: workerEnvironment(), shell: false, windowsHide: true, detached:process.platform!=='win32', stdio: ['pipe', 'pipe', 'pipe'] });
-    child.once('spawn', () => observer.onStart?.(child.pid));
-    let output = '', failure, size = 0, reapTimer, settled=false;
-    const stop = reason => {
-      if(failure)return;
-      failure ??= new Error(reason);
-      if (process.platform === 'win32' && child.pid && child.exitCode === null) {
-        spawnSync(path.join(process.env.SystemRoot ?? 'C:/Windows', 'System32/taskkill.exe'), ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 5000 });
-      } else if(child.pid) { try {process.kill(-child.pid,'SIGTERM');} catch {child.kill();} }
-      // A failed OS termination must not hang the tool forever. Retain an explicit
-      // live-worker guard so returning an error never unlocks concurrent writers.
-      reapTimer=setTimeout(()=>{
-        if(settled)return;settled=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);
-        failure.unreapedPid=child.pid;failure.workerIdentity=processIdentity(child.pid);
-        // An exited root does not prove its descendants exited: inherited pipes
-        // can keep this call open. Never clear this uncertainty by PID lookup.
-        failure.descendantsUnconfirmed=true;
-        child.stdout.destroy();child.stderr.destroy();child.stdin.destroy();child.unref();reject(failure);
-      },5000);
-    };
-    const abort = () => stop('Review cancelled; checkpoint remains closed.');
-    signal?.addEventListener('abort', abort, { once: true });
-    const timer = Number.isFinite(timeoutMs) && timeoutMs > 0 ? setTimeout(() => stop('Process timed out; checkpoint remains closed.'), timeoutMs) : undefined;
-    child.stdout.setEncoding('utf8');
-    child.stdout.on('data', data => {
-      if (observer.streamOnly) {
-        // Reviewer CLI tool reads can be much larger than the final report.
-        // Consume all events without retaining the full transcript in RAM.
-        output = (output + data).slice(-12000); observer.onData?.(data);
-      } else {
-        size += Buffer.byteLength(data);
-        output += data; observer.onData?.(data);
-      }
-    });
-    child.stderr.setEncoding('utf8');
-    child.stderr.on('data', data => { if(observer.captureStderr) output=(output+data).slice(-12000); }); // Premium CLI stderr remains private.
-    child.stdin.on('error', () => {});
-    child.on('error', e => { failure = e; });
-    child.on('close', code => {
-      clearTimeout(timer);clearTimeout(reapTimer); signal?.removeEventListener('abort', abort);
-      if(settled)return;settled=true;
-      if (failure || code !== 0) {
-        const error = failure ?? new Error(`Process exited ${code}; no approval recorded.`);
-        error.output = output.slice(-12000); error.exitCode = code; reject(error);
-      }
-      else resolve(output);
-    });
-    child.stdin.end(input);
-  });
-}
-
-export async function runWorker(who, prompt, config, folder, signal, metadata = {}) {
-  const lane=reviewer(config,who);
-  if(lane.adapter==='opencode') {
-    if(!config.nativeRunner)throw Error('OpenCode reviewer adapter requires the active OpenCode plugin host.');
-    return config.nativeRunner(who,prompt,config,folder,signal,metadata);
-  }
-  const telemetry = new Telemetry(who, config, folder, metadata);
-  let envelope;
-  const stream = jsonLineReader(event => { telemetry.event(event); if (event.type === 'result') envelope = event; });
-  const heartbeat = setInterval(() => telemetry.save(), 5000); heartbeat.unref();
-  try {
-  if (signal?.aborted) throw new Error('Cancelled before launch.');
-  requireSubscription(who, config, folder);
-  writeFileSync(path.join(folder, 'schema.json'), JSON.stringify(resultSchema));
-  const browser=prepareBrowser(config,folder);
-  const evidence=evidenceServer(folder);
-  const args = workerArgs(who, config, folder, metadata.images ?? [],browser,evidence);
-  if(evidence)prompt=queryInstructions+'\n\n'+prompt;
-  if(browser){prompt=browserInstructions+'\n\n'+prompt;telemetry.value.browserAvailable=true;telemetry.save();}
-  telemetry.prompt(prompt);
-  const executable = lane.executable;
-  const stdout = await runProcess(executable, args, folder, prompt, config.reviewTimeoutMs ?? 0, signal, {
-    streamOnly: true, onStart: pid => telemetry.start(pid), onData: text => stream.push(text),
-  });
-  stream.finish();
-  let result;
-  if (lane.adapter === 'codex-cli') result = JSON.parse(readFileSync(path.join(folder, 'result.json'), 'utf8'));
-  else {
-    if (!envelope) { try { envelope = JSON.parse(stdout); telemetry.event(envelope); } catch {} }
-    if (!envelope) throw new Error('Claude produced no final result event; checkpoint stays closed.');
-    if (envelope.is_error || envelope.subtype !== 'success') throw new Error('Claude did not complete successfully; checkpoint stays closed.');
-    result = envelope.structured_output;
-    if (!result) {
-      // Some CLI runs return the schema JSON as the final result string.
-      // Accept only exact JSON validated below, never prose or inferred approval.
-      try { result = JSON.parse(envelope.result); } catch {}
-      if (!result) throw new Error(`Claude returned no schema result (fields: ${Object.keys(envelope).join(',')}; result type: ${typeof envelope.result}); checkpoint stays closed.`);
-    }
-  }
-  try { validateResult(result); telemetry.end('completed', result.verdict); return result; }
-  catch {
-    throw new Error(`${who}: invalid reviewer schema (verdict type ${typeof result?.verdict}; report type ${typeof result?.report}; findings count ${Array.isArray(result?.findings) ? result.findings.length : 'not-array'}). Checkpoint stays closed.`);
-  }
-  } catch (error) {
-    if(error.unreapedPid){telemetry.value.workerExitUnconfirmed=true;telemetry.value.descendantsUnconfirmed=!!error.descendantsUnconfirmed;}
-    stream.finish(); telemetry.end(signal?.aborted ? 'cancelled' : 'failed');
-    delete error.output; // Never expose raw verbose CLI event tails to OpenCode logs.
-    throw error;
-  } finally { clearInterval(heartbeat); }
-}
+import {documentTool} from '../lib/public-document.mjs';
+import {reviewer} from '../lib/reviewers.mjs';
+import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Telemetry, jsonLineReader } from './telemetry.mjs';
+import { findingSchema, isMajor } from './decision.mjs';
+import {processIdentity} from './process-identity.mjs';
+import {commandSpec} from '../lib/commands.mjs';
+import {commandEnvironment} from '../lib/platform.mjs';
+import {prepareBrowser,browserTools,browserInstructions} from '../lib/reviewer-browser.mjs';
+import {evidenceServer,queryInstructions,queryTool} from '../lib/evidence-mcp.mjs';
+
+export const resultSchema = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    verdict: { type: 'string', enum: ['pass', 'revise', 'blocked'] },
+    report: { type: 'string' },
+    findings: { type: 'array', items: findingSchema },
+    verifiedResolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
+  }, required: ['verdict', 'report', 'findings', 'verifiedResolutions'],
+};
+
+export function workerArgs(who, config, folder, images = [], browser = null, evidence = null) {
+  const lane=reviewer(config,who);
+  // Attachment count is a transport choice, never an evidence quota. Larger
+  // sets stay in the frozen images/ manifest and are opened with view_image.
+  const inlineImages = images.length <= 4 && images.join('').length < 2048 ? images : [];
+  if (lane.adapter === 'codex-cli') return ['exec', '--json', '--ignore-user-config', '--ignore-rules', '--ephemeral', '--skip-git-repo-check',
+    '--sandbox', 'read-only', '-C', folder, '-m', lane.model,
+    // User config is intentionally isolated, so Windows' required sandbox
+    // implementation must be explicit too. Without it shell reads are denied.
+    ...(process.platform === 'win32' ? ['-c', 'windows.sandbox="elevated"'] : []),
+    '-c', 'approval_policy="never"',
+    ...(lane.effort==='default'?[]:['-c', `model_reasoning_effort="${lane.effort??'high'}"`]), '-c', 'web_search="disabled"',
+    ...(browser ? ['-c',`mcp_servers.review_browser.command=${JSON.stringify(browser.command)}`,
+      '-c',`mcp_servers.review_browser.args=${JSON.stringify(browser.args)}`,
+      '-c','mcp_servers.review_browser.startup_timeout_sec=60',
+      '-c','mcp_servers.review_browser.tool_timeout_sec=120',
+      '-c','mcp_servers.review_browser.default_tools_approval_mode="approve"',
+      '-c',`mcp_servers.review_browser.enabled_tools=${JSON.stringify(browserTools)}`] : []),
+    ...(evidence?['-c',`mcp_servers.review_evidence.command=${JSON.stringify(evidence.command)}`,'-c',`mcp_servers.review_evidence.args=${JSON.stringify(evidence.args)}`,
+      '-c','mcp_servers.review_evidence.default_tools_approval_mode="approve"','-c',`mcp_servers.review_evidence.enabled_tools=${JSON.stringify([queryTool,documentTool])}`]:[]),
+    ...inlineImages.flatMap(image=>['--image',image]),
+    '--output-schema', path.join(folder, 'schema.json'), '-o', path.join(folder, 'result.json'), '-'];
+  return ['-p', ...(browser||evidence?['--setting-sources','','--disable-slash-commands','--settings','{"disableAllHooks":true,"enabledPlugins":{}}']:['--safe-mode']), '--restricted', '--strict-mcp-config', '--mcp-config', JSON.stringify({mcpServers:{...(browser?{review_browser:browser}:{}),...(evidence?{review_evidence:evidence}:{})}}),
+    '--no-chrome', '--no-session-persistence', '--permission-mode', 'dontAsk', '--permission-prompts', 'none',
+    '--tools', 'Read,Glob,Grep', '--allowedTools', ['Read','Glob','Grep',...(browser?browserTools.map(name=>'mcp__review_browser__'+name):[]),...(evidence?[queryTool,documentTool].map(name=>'mcp__review_evidence__'+name):[])].join(','),
+    '--model', lane.model, ...(lane.effort==='default'?[]:['--effort',lane.effort??'high']), '--output-format', 'stream-json', '--verbose',
+    '--json-schema', JSON.stringify(resultSchema)];
+}
+
+export function validateResult(value) {
+  if (!value || !['pass', 'revise', 'blocked'].includes(value.verdict) || typeof value.report !== 'string' || !value.report.trim() ||
+      !Array.isArray(value.findings)) throw new Error('Invalid reviewer result; checkpoint stays closed.');
+  if (Object.keys(value).some(key => !['verdict', 'report', 'findings','verifiedResolutions'].includes(key))) throw new Error('Invalid reviewer result fields.');
+  // Existing receipts remain readable. Omission cannot resolve tracked findings.
+  if(value.verifiedResolutions!==undefined&&(!Array.isArray(value.verifiedResolutions)||value.verifiedResolutions.some(r=>!r||Object.keys(r).some(k=>!['id','evidence'].includes(k))||typeof r.id!=='string'||!r.id.trim()||typeof r.evidence!=='string'||!r.evidence.trim())||new Set(value.verifiedResolutions.map(r=>r.id)).size!==value.verifiedResolutions.length))throw Error('Invalid verified resolutions.');
+  const ids = new Set();
+  for (const f of value.findings) {
+    if (!f || typeof f !== 'object' || Array.isArray(f) ||
+        Object.keys(f).some(key => !findingSchema.required.includes(key)) ||
+        findingSchema.required.some(key => typeof f[key] !== 'string' || !f[key].trim()) ||
+        !findingSchema.properties.severity.enum.includes(f.severity) ||
+        !findingSchema.properties.category.enum.includes(f.category) || ids.has(f.id) ||
+        (f.category === 'preference' && isMajor(f))) throw new Error('Invalid structured finding; checkpoint stays closed.');
+    ids.add(f.id);
+  }
+  if ((value.verdict === 'pass' && value.findings.some(isMajor)) ||
+      (value.verdict === 'revise' && !value.findings.length) ||
+      (value.verdict === 'blocked' && !value.findings.some(isMajor))) throw new Error('Inconsistent reviewer verdict; checkpoint stays closed.');
+  return value;
+}
+
+export function workerEnvironment(source = process.env) {
+  const env = {};
+  const allowed = /^(PATH|PATHEXT|SYSTEMROOT|WINDIR|COMSPEC|TEMP|TMP|TMPDIR|HOME|XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_STATE_HOME|XDG_CACHE_HOME|USERPROFILE|APPDATA|LOCALAPPDATA|HOMEDRIVE|HOMEPATH|USERNAME|USERDOMAIN|PROGRAMFILES|PROGRAMFILES\(X86\)|PROGRAMW6432|OS|SYSTEMDRIVE|LANG|LC_ALL)$/i;
+  for (const [key, value] of Object.entries(source)) if (allowed.test(key)) env[key] = value;
+  // Official CLIs retain their normal per-user official login; never extract tokens.
+  return commandEnvironment(env);
+}
+
+export function requireCliAuthentication(who, config, folder, invoke = spawnSync) {
+  const lane=reviewer(config,who);
+  if(lane.adapter==='opencode')return;
+  const executable=lane.executable;
+  const args = lane.adapter === 'codex-cli' ? ['login', 'status'] : ['auth', 'status'];
+  const spec=invoke===spawnSync?commandSpec(executable):{executable,args:[]};
+  const result = invoke(spec.executable, [...spec.args,...args], { cwd: folder, env: workerEnvironment(), shell: false, windowsHide: true, encoding: 'utf8', timeout: 15000 });
+  let valid = false;
+  if (result.status === 0 && lane.adapter === 'codex-cli') valid = /^Logged in using (?:ChatGPT|(?:an? )?API key)(?:\s|$)/im.test((result.stdout ?? '') + '\n' + (result.stderr ?? ''));
+  if (result.status === 0 && lane.adapter === 'claude-cli') {
+    try { const auth = JSON.parse(result.stdout); valid = auth.loggedIn === true && ['claude.ai','oauth_token','api_key'].includes(auth.authMethod) && auth.apiProvider === 'firstParty'; } catch {}
+  }
+  if (!valid) throw new Error(`${who}: official CLI authentication could not be confirmed. Sign in through the selected CLI using its subscription or Console/API login. Unknown or unsupported authentication is refused.`);
+}
+
+export async function runProcess(executable, args, folder, input, timeoutMs, signal, observer = {}) {
+  if (signal?.aborted) throw new Error('Cancelled before launch.');
+  return await new Promise((resolve, reject) => {
+    const spec=commandSpec(executable);
+    const child = spawn(spec.executable, [...spec.args,...args], { cwd: folder, env: workerEnvironment(), shell: false, windowsHide: true, detached:process.platform!=='win32', stdio: ['pipe', 'pipe', 'pipe'] });
+    child.once('spawn', () => observer.onStart?.(child.pid));
+    let output = '', failure, size = 0, reapTimer, settled=false;
+    const stop = reason => {
+      if(failure)return;
+      failure ??= new Error(reason);
+      if (process.platform === 'win32' && child.pid && child.exitCode === null) {
+        spawnSync(path.join(process.env.SystemRoot ?? 'C:/Windows', 'System32/taskkill.exe'), ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 5000 });
+      } else if(child.pid) { try {process.kill(-child.pid,'SIGTERM');} catch {child.kill();} }
+      // A failed OS termination must not hang the tool forever. Retain an explicit
+      // live-worker guard so returning an error never unlocks concurrent writers.
+      reapTimer=setTimeout(()=>{
+        if(settled)return;settled=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);
+        failure.unreapedPid=child.pid;failure.workerIdentity=processIdentity(child.pid);
+        // An exited root does not prove its descendants exited: inherited pipes
+        // can keep this call open. Never clear this uncertainty by PID lookup.
+        failure.descendantsUnconfirmed=true;
+        child.stdout.destroy();child.stderr.destroy();child.stdin.destroy();child.unref();reject(failure);
+      },5000);
+    };
+    const abort = () => stop('Review cancelled; checkpoint remains closed.');
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = Number.isFinite(timeoutMs) && timeoutMs > 0 ? setTimeout(() => stop('Process timed out; checkpoint remains closed.'), timeoutMs) : undefined;
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', data => {
+      if (observer.streamOnly) {
+        // Reviewer CLI tool reads can be much larger than the final report.
+        // Consume all events without retaining the full transcript in RAM.
+        output = (output + data).slice(-12000); observer.onData?.(data);
+      } else {
+        size += Buffer.byteLength(data);
+        output += data; observer.onData?.(data);
+      }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', data => { if(observer.captureStderr) output=(output+data).slice(-12000); }); // Premium CLI stderr remains private.
+    child.stdin.on('error', () => {});
+    child.on('error', e => { failure = e; });
+    child.on('close', code => {
+      clearTimeout(timer);clearTimeout(reapTimer); signal?.removeEventListener('abort', abort);
+      if(settled)return;settled=true;
+      if (failure || code !== 0) {
+        const error = failure ?? new Error(`Process exited ${code}; no approval recorded.`);
+        error.output = output.slice(-12000); error.exitCode = code; reject(error);
+      }
+      else resolve(output);
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function runWorker(who, prompt, config, folder, signal, metadata = {}) {
+  const lane=reviewer(config,who);
+  if(lane.adapter==='opencode') {
+    if(!config.nativeRunner)throw Error('OpenCode reviewer adapter requires the active OpenCode plugin host.');
+    return config.nativeRunner(who,prompt,config,folder,signal,metadata);
+  }
+  const telemetry = new Telemetry(who, config, folder, metadata);
+  let envelope;
+  const stream = jsonLineReader(event => { telemetry.event(event); if (event.type === 'result') envelope = event; });
+  const heartbeat = setInterval(() => telemetry.save(), 5000); heartbeat.unref();
+  try {
+  if (signal?.aborted) throw new Error('Cancelled before launch.');
+  requireCliAuthentication(who, config, folder);
+  writeFileSync(path.join(folder, 'schema.json'), JSON.stringify(resultSchema));
+  const browser=prepareBrowser(config,folder);
+  const evidence=evidenceServer(folder);
+  const args = workerArgs(who, config, folder, metadata.images ?? [],browser,evidence);
+  if(evidence)prompt=queryInstructions+'\n\n'+prompt;
+  if(browser){prompt=browserInstructions+'\n\n'+prompt;telemetry.value.browserAvailable=true;telemetry.save();}
+  telemetry.prompt(prompt);
+  const executable = lane.executable;
+  const stdout = await runProcess(executable, args, folder, prompt, config.reviewTimeoutMs ?? 0, signal, {
+    streamOnly: true, onStart: pid => telemetry.start(pid), onData: text => stream.push(text),
+  });
+  stream.finish();
+  let result;
+  if (lane.adapter === 'codex-cli') result = JSON.parse(readFileSync(path.join(folder, 'result.json'), 'utf8'));
+  else {
+    if (!envelope) { try { envelope = JSON.parse(stdout); telemetry.event(envelope); } catch {} }
+    if (!envelope) throw new Error('Claude produced no final result event; checkpoint stays closed.');
+    if (envelope.is_error || envelope.subtype !== 'success') throw new Error('Claude did not complete successfully; checkpoint stays closed.');
+    result = envelope.structured_output;
+    if (!result) {
+      // Some CLI runs return the schema JSON as the final result string.
+      // Accept only exact JSON validated below, never prose or inferred approval.
+      try { result = JSON.parse(envelope.result); } catch {}
+      if (!result) throw new Error(`Claude returned no schema result (fields: ${Object.keys(envelope).join(',')}; result type: ${typeof envelope.result}); checkpoint stays closed.`);
+    }
+  }
+  try { validateResult(result); telemetry.end('completed', result.verdict); return result; }
+  catch {
+    throw new Error(`${who}: invalid reviewer schema (verdict type ${typeof result?.verdict}; report type ${typeof result?.report}; findings count ${Array.isArray(result?.findings) ? result.findings.length : 'not-array'}). Checkpoint stays closed.`);
+  }
+  } catch (error) {
+    if(error.unreapedPid){telemetry.value.workerExitUnconfirmed=true;telemetry.value.descendantsUnconfirmed=!!error.descendantsUnconfirmed;}
+    stream.finish(); telemetry.end(signal?.aborted ? 'cancelled' : 'failed');
+    delete error.output; // Never expose raw verbose CLI event tails to OpenCode logs.
+    throw error;
+  } finally { clearInterval(heartbeat); }
+}

package/docs/configuration.md

@@ -34,6 +34,12 @@ redirect reviewer executable settings to its own file. The installer supports
 `--config-dir PATH` for a separate profile.
 Do not put credentials in this file; OpenCode or the selected official CLI owns authentication.
 
+CLI reviewers use the account already signed in through that CLI, including
+Claude Console/API billing or a subscription. The plugin does not switch accounts,
+copy keys or inherit API-key environment overrides. Billing follows the CLI login
+you selected. For environment-key or cloud-provider setups, connect the provider
+through OpenCode and select that provider/model in Hybrid Workflow settings.
+
 `opencode-hybrid configure` opens an interactive selector: choose one or two
 reviewers, OpenCode provider or external CLI for each, model, supported variant/CLI effort, and the
 planning/design lead. Either slot can use any supported adapter, including two