@rockysoft/opencode-hybrid-workflow 0.9.0 → 1.0.0

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/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Release notes
 
+## 1.0.0
+
+- Carry reviewed project ownership hints into subsequent tasks, with project/source bindings and automatic invalidation when files change. Hints never replace source inspection or approval.
+- Show accurate resume context, pending findings and verification freshness.
+- Order stable context consistently without removing evidence. No token-saving or speed improvement is claimed.
+- Correct UI/UX Pro Max instructions for macOS/Linux and Windows.
+- Exclude generated Python bytecode from package and managed skill installation.
+
+## 0.9.1
+
+- Recognize Claude Console/API authentication when using the optional Claude CLI adapter.
+
+## 0.9.0
+
+- Add structured engineering handoffs for responsibility boundaries, state ownership and behavioral acceptance checks.
+- Keep material architecture and design choices with the configured planning/design reviewers while implementation specialists follow approved contracts.
+- Preserve proportional review of small changes without file-length quotas.
+
 ## 0.8.0
 
 - Capture repeatable frontend scenarios, screenshots and assertions once for both reviewers.

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
@@ -126,3 +132,9 @@ machine rather than copying account credentials.
 ## Frozen source lookup
 
 Reviewers automatically receive `hybrid_evidence_query` (under `review_evidence` for CLI connections). It supports inventory, literal case-sensitive search and batch line reads within the captured source snapshot. Results include hashes, snapshot identity, UTF-16 offsets and continuation fields. Missing, withheld or changed captures are explicitly unavailable. Existing file/image readers remain available. No symbol analysis, regex execution or live-project reads are added. Query contents never enter usage logs; CLI query measurements contain only operation names, sizes, duration and status.
+
+## Project context and resume
+
+New tasks keep stable contracts ahead of changing review details. Full skills, plans and frozen source remain accessible through the existing evidence transport. Cache behavior is managed by your provider, so stable prompts do not guarantee cache hits or lower charges.
+
+After an accepted code review, structured engineering handoffs can supply project-specific ownership hints. Any captured source/configuration change makes these hints stale; conflicting plan/design owners are omitted. Hints cannot approve work or replace verification. The checkpoint status includes current contracts, pending findings, verification freshness and the next permitted step for resuming work. Existing tasks retain their earlier transport; no conversation is reset.

package/lib/context-layout.mjs

@@ -0,0 +1,20 @@
+import {hash} from '../core/snapshot.mjs';
+
+// Order object keys, never arrays: source order and reviewer precedence can matter.
+export function canonical(value) {
+  if(Array.isArray(value))return value.map(canonical);
+  if(value&&typeof value==='object')return Object.fromEntries(Object.keys(value).sort().filter(key=>value[key]!==undefined).map(key=>[key,canonical(value[key])]));
+  return value;
+}
+export const stableJSON = value => JSON.stringify(canonical(value));
+const stableKeys=['brief','plan','design','skills'];
+export function orderContext(packet) {
+  const ordered=canonical(packet);
+  return Object.fromEntries([...stableKeys.filter(key=>Object.hasOwn(ordered,key)),...Object.keys(ordered).filter(key=>!stableKeys.includes(key))].map(key=>[key,ordered[key]]));
+}
+export function contextReceipt(packet) {
+  const stable=Object.fromEntries(stableKeys.filter(key=>Object.hasOwn(packet,key)).map(key=>[key,packet[key]]));
+  const text=stableJSON(stable);
+  return {version:1,contractsHash:hash(text),contractsChars:text.length,layout:'stable-fields-first',
+    cacheControl:'provider-managed',cacheHit:'unknown',note:'Canonical field ordering adds no prompt text. No explicit provider cache control, TTL, token saving or cache-hit guarantee.'};
+}