@rockysoft/opencode-hybrid-workflow 0.8.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

package/docs/engineering-handoffs.md

@@ -0,0 +1,67 @@
+# Engineering handoffs
+
+Hybrid Workflow turns the premium models' selected architecture into a compact responsibility map inside the existing approved report. Implementation agents follow it; reviewers compare it to the affected code. There is no additional setup, phase, file-length limit or compulsory architecture for a small change.
+
+For a substantial editor, the handoff names the view, draft/request owner, recovery adapter and authoritative validation boundary. It states what happens when a response arrives after navigation or a record change. A small extension can simply name the existing component and the behavior being added.
+
+The checkpoint returns `engineeringHandoff`, and reviewers receive `handoffChecks`. These describe contract consistency and whether declared files exist in the captured source. They do **not** prove that code follows the contract or that an acceptance check ran. A future module missing from an intermediate milestone is not automatically a defect. Existing prose plans remain usable.
+
+## Example: a bounded save workflow
+
+The premium plan may include this block alongside its explanation. Paths are exact project-relative paths, not commands or globs. State lists identify authoritative state, not every derived display value. The actual project determines the boundaries; these names are illustrative.
+
+```hybrid-handoff
+{
+  "version": 1,
+  "scope": "Save and leave an existing editor",
+  "owners": [
+    {
+      "id": "view",
+      "responsibility": "Render the form and forward user events",
+      "paths": ["src/Editor.tsx"],
+      "boundary": "client",
+      "state": [],
+      "inputs": ["session state"],
+      "outputs": ["edit, save, leave"],
+      "dependsOn": ["session"]
+    },
+    {
+      "id": "session",
+      "responsibility": "Own draft transitions and ignore results after departure or record change",
+      "paths": ["src/editor-session.ts"],
+      "boundary": "client",
+      "state": ["draft", "recordId", "requestGeneration", "departed"],
+      "inputs": ["edit, save, leave", "save result"],
+      "outputs": ["render state", "recovery write/remove intent"],
+      "dependsOn": ["save"]
+    },
+    {
+      "id": "save",
+      "responsibility": "Authorize and validate before committing a record",
+      "paths": ["src/server/save.ts"],
+      "boundary": "server",
+      "state": [],
+      "inputs": ["authenticated request, recordId, draft"],
+      "outputs": ["committed result or validation/conflict error"],
+      "dependsOn": []
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "leave-during-save",
+      "owners": ["view", "session", "save"],
+      "action": "Begin a save, confirm leaving, then deliver the response",
+      "expected": "No client redirect or recovered draft resurrection; do not claim the server commit was canceled",
+      "evidence": "Deferred-response test and representative browser navigation check"
+    }
+  ]
+}
+```
+
+Design documents add a map only when they change engineering ownership. An explicit approved amendment must reconcile conflicting contracts; a later design cannot silently erase the plan. Visual direction still belongs to the configured premium lead. References, typography, tokens and representative states stay in the design document.
+
+## Review and implementation
+
+At the first meaningful milestone of a new pattern, inspect one implementation before replicating it. Trace view -> state -> domain rules -> persistence and lifecycle where applicable. Check actual owner paths, shared client/server contracts and stale-response handling. A giant hook or a JSX-only split is not proof of separation. Conversely, a cohesive component is acceptable regardless of file length.
+
+Implementation handoffs distinguish intended scenarios from executed checks, failed checks and untested behavior. Parsing the map never executes its evidence text or follows its paths outside the frozen inventory. Reviewers assign findings only for concrete consequences. The existing rule remains: all configured current-artifact reviews, at least one pass and no unresolved medium/high/critical issues.