@rockysoft/opencode-hybrid-workflow 1.2.0 → 1.3.1

package/core/workers.mjs

@@ -1,202 +1,205 @@
-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); }
-}
+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';
+import {recoverySchema} from './planning-escalation.mjs';
+
+export const resultSchema = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    verdict: { type: 'string', enum: ['pass', 'revise', 'blocked'] },
+    report: { type: 'string' },
+    findings: { type: 'array', items: findingSchema },
+    recovery: recoverySchema,
+    verifiedResolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
+  }, required: ['verdict', 'report', 'findings', 'verifiedResolutions', 'recovery'],
+};
+
+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','recovery'].includes(key))) throw new Error('Invalid reviewer result fields.');
+  if(value.recovery!=null&&(!value.recovery||typeof value.recovery!=='object'||Array.isArray(value.recovery)||Object.keys(value.recovery).some(k=>!['kind','instructions'].includes(k))||!recoverySchema.properties.kind.enum.includes(value.recovery.kind)||typeof value.recovery.instructions!=='string'||!value.recovery.instructions.trim()))throw Error('Invalid planning recovery directive.');
+  // 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,18 @@
 # Release notes
 
+## 1.3.1
+
+- Carry original OpenCode user messages to both reviewers so explicit scope amendments are not reduced to implementation-agent claims or overridden by stale briefs.
+- Reopen planning, design and code-review evidence checks when the original user context changes. Preserve task history and reject approval against context changed during review.
+- Keep synthetic recovery, attachments and agent output separate from user authority; screen common credential formats and verify session/project boundaries. Existing two-reviewer approval requirements are unchanged.
+
+## 1.3.0
+
+- Route disputed or unclear planning findings to the configured premium lead through `escalate`, with concrete research, resubmission, developer or tooling directives.
+- Recover visible premature planning stops inside the active execution while honoring interruptions, waiting instructions and approval boundaries.
+- Preserve reviewer-owned finding resolution and detect unchanged recovery attempts without repeatedly spending model calls.
+- Distinguish malformed reviewer JSON from schema/verdict conflicts in transport errors.
+
 ## 1.2.0
 
 - Keep global specialist roles independent of a preferred framework, database or cloud while preserving responsibility, correctness, security and testing standards.

package/docs/planning-recovery.md

@@ -1,22 +1,30 @@
-# Continue blocked planning
+# Planning recovery
 
-Continue the existing OpenCode chat. A new chat in the same project shares the same checkpoint and does not reset it.
+The implementation model collects facts and builds the approved design. Premium planners evaluate architectural/security choices and decide whether findings are valid. A closed planning gate is not a reason to reset a task or disable Hybrid.
 
-Ask normally: **“Collect the missing planning evidence and continue. Keep installation and integration checks at the implementation stages that can actually execute them.”**
+When a finding or requested correction is unclear, disputed or blocked by a missing capability, call `hybrid_checkpoint` with `action: "escalate"` and the observations in `checks`. This sends the current plan, finding history and research evidence to the configured planning lead. It preserves the task, reviewer assignments and approvals.
 
-The agent can use these checkpoint actions before application edits are approved:
+The lead returns a `planningNext` directive:
 
-| Action | What it does |
+| Kind | Next step |
 | --- | --- |
-| `status` | Shows current-stage findings and concrete recovery actions. |
-| `inspect` | Reports installed tool versions and reviewer authentication diagnostics. |
-| `research`, `kind: packages` | Fetches public npm metadata for `{name, version}` entries. It does not install packages or read npm credentials. |
-| `research`, `kind: note` | Saves attributed evidence from `checks` in task runtime storage and includes it in subsequent planning. |
-| `research`, `kind: report` | Reads a saved report by its `reportCall` from `status.reports`. |
-| `plan` | Submits the evidence and proposed resolutions to the configured reviewers. |
+| Research | Collect the specific public facts/excerpts, save attributed evidence through `research` and return it to `plan`. Do not invent architecture contracts. |
+| Resubmit | Submit the lead's corrected contract or rebuttal through normal planning validation. |
+| Developer | Present the specific question, options and consequences; wait for the developer. |
+| Tooling | Explain the exact missing access/capability and repair required. Do not repeatedly retry an unchanged failure. |
 
-Notes are unverified claims. Registry receipts prove what the registry returned, not a successful install. Neither closes a finding or grants approval. Arbitrary shell commands and application edits stay gated. There is no package-count or research-call quota; network requests have transport timeouts and per-response memory protection.
+An advisory escalation never grants implementation approval or closes findings. A reviewer can explicitly withdraw its own mistaken finding with a reason through `verifiedResolutions`; another model's pass or the implementer's assertion cannot erase dissent. Normal current-plan validation still requires the configured reports, at least one pass, and no unresolved medium/high/critical finding. Reserved developer decisions remain reserved.
 
-Planning must settle material architecture choices. Installation, deployed-service and live-account checks belong to the stages that can execute them. The plan must name their owner, dependent operation, required evidence and failure/replan path. A fundamental feasibility or security unknown cannot be deferred merely to obtain a pass. Only the originating reviewer can verify that a previous finding is resolved by a corrected stage boundary.
+On supported OpenCode hosts, a visible premature stop after active planning work can receive a continuation inside the same execution. It routes through the next step above, respects interruptions and explicit waiting instructions, excludes children/reviewer sessions and pending question-tool interactions, and suppresses unchanged recovery loops. It does not start a background session or resume an interrupted one. An already-idle conversation still needs a normal user message to resume.
 
-Package/note receipts attach only to planning. For design or code review, use that checkpoint's existing `checks` and `images` inputs. Use `replan` for changed architectural requirements, preserving history and prior findings.
+Native reviewers use captured evidence and approved documentation/browser tools. This feature does not add unrestricted web search. The implementation agent may gather the lead's requested documentation using its available tools; the premium lead evaluates it. External evidence remains untrusted and must contain no credentials or private source sent to public research services.
+
+Older saved tasks remain readable. The report schema adds a nullable `recovery` object for new responses; existing receipts without it remain accepted. For a recovery response, verdicts retain their usual meaning: a missing essential fact uses `blocked` with an actionable research directive, not `pass` with a medium finding. JSON syntax and schema/verdict errors are reported separately.
+
+## Original user decisions
+
+Checkpoints now attach the original user messages exposed by OpenCode, with session/message IDs and dates. Both reviewers receive the same captured evidence. An explicit scope change in chat can supersede an old brief; you do not need to edit a file manually to prove it. The plan should cite the message, state the effective scope and schedule stale documentation updates during implementation. A generic “continue” still does not approve an unspecified stack migration.
+
+On OpenCode 2.2.5, the plugin reads original messages in active context. It does not mistake compaction summaries for user approval. Previously captured originals missing from the active window remain labelled historical evidence, because compaction and reversion cannot be distinguished through that API. They cannot authorize new reserved actions. Hosts exposing the projected-message listing API are read page by page. An unavailable decision may require a focused clarification; it is not a reason to reset the task or ask for manual source edits.
+
+Visible assistant proposals are included only as context for replies. Synthetic messages, tool results and attachment bodies are not promoted to user instructions. Common credential formats are redacted before forwarding; this screening is best-effort, so keep credentials out of chat. Provider access remains the configured reviewers' access. User-role provenance is supplied by the OpenCode host, not cryptographic proof of human authorship.

package/lib/continuation.mjs

@@ -3,6 +3,7 @@ import {isReviewerSession} from './opencode-reviewer.mjs';
 import {writeJSONAtomic,runtimePath} from '../core/state-store.mjs';
 import {operationBusy} from '../core/operation-lock.mjs';
 import {continuationFile} from './continuation-notice.mjs';
+import {planningStopDecision} from './planning-continuation.mjs';
 
 const SOURCE='hybrid-silent-stop';
 const unwrap=value=>value.data??value;
@@ -63,7 +64,8 @@ export async function registerContinuation(ctx,forSession) {
       const controller=await forSession(event.sessionID);
       if(operationBusy(controller.lockFile))return;
       const messages=unwrap(await ctx.session.context({sessionID:event.sessionID}));
-      const decision=silentStopDecision(messages,controller.read(),event.sessionID,event.background);
+      const state=controller.read();
+      const decision=planningStopDecision(messages,state,event.sessionID,event.background)??silentStopDecision(messages,state,event.sessionID,event.background);
       if(!decision)return;
       const current=unwrap(await ctx.session.get({sessionID:event.sessionID}));
       const busy=Number(new Date(current.time?.busy??0)),idle=Number(new Date(current.time?.idle??0));

package/lib/native-result.mjs

@@ -26,6 +26,7 @@ export async function readNativeResult(ctx,sessionID,{isAborted=()=>false,onReco
  // Accept only an exact single JSON fence wrapper, not prose or guessed JSON
  // substrings. The complete enclosed object still passes the same strict schema.
  const fenced=/^```(?:json)?[ \t]*\r?\n([\s\S]*)\r?\n```$/.exec(text);
- let result;try{result=validateResult(JSON.parse(fenced?fenced[1]:text));}catch{throw Error('Reviewer returned invalid JSON; no approval recorded.');}
+ let parsed;try{parsed=JSON.parse(fenced?fenced[1]:text);}catch{throw Error('Reviewer returned invalid JSON; no approval recorded.');}
+ let result;try{result=validateResult(parsed);}catch(error){throw Error('Reviewer returned a schema-invalid result: '+error.message+' No approval recorded.');}
  return {result,session};
 }

package/lib/planning-continuation.mjs

@@ -0,0 +1,40 @@
+import {planningNext} from '../core/planning-escalation.mjs';
+
+const SOURCE='hybrid-planning-handoff';
+const terminalText=m=>(m?.content??[]).filter(p=>p.type==='text').map(p=>p.text??'').join('').trim();
+function unchangedEscalation(parts){
+ const last=parts.findLast(p=>p.name==='hybrid_checkpoint');
+ if(last?.state?.status!=='completed'||last.state.input?.action!=='escalate')return false;
+ const content=last.state.content;
+ const text=typeof content==='string'?content:Array.isArray(content)?content.filter(p=>p.type==='text').map(p=>p.text??'').join(''):'';
+ try{return JSON.parse(text).escalationUnchanged===true;}catch{return false;}
+}
+function explicitHandoff(request){
+ const text=request.replace(/\b(?:do not|don't|never)\s+(?:stop|pause|cancel)\b/gi,'continue');
+ if(/\b(stop|pause|cancel|do not continue|don't continue|status only|do not run|don't run)\b/i.test(text))return true;
+ // Be conservative about handoffs. The single supported deferred boundary is
+ // explicit completion of planning before waiting; it is still pending here.
+ const remaining=text.replace(/\b(finish|complete|finalize)\b[^.!?\n]{0,55}\bplan(?:ning)?\b[^.!?\n]{0,35}\bthen\s+wait\b/gi,'');
+ return /\b(wait|hold|await)\b/i.test(remaining);
+}
+export function planningStopDecision(messages,state,sessionID,background=[]){
+ const next=planningNext(state);
+ if(!next||!['escalate','research','resubmit'].includes(next.kind)||background.some(w=>w.sessionID===sessionID))return null;
+ const userIndex=messages.findLastIndex(m=>m.type==='user');if(userIndex<0)return null;
+ const user=messages[userIndex],request=user.text??terminalText(user);
+ // Explicit human stop/status-only requests do not authorize more work.
+ if(explicitHandoff(request))return null;
+ const turn=messages.slice(userIndex+1),last=turn.findLast(m=>m.type==='assistant');
+ if(!last||last.error||last.finish!=='stop'||!terminalText(last))return null;
+ if(turn.some(m=>m.type==='assistant'&&(m.error||['error','length','content-filter'].includes(m.finish))))return null;
+ const parts=turn.filter(m=>m.type==='assistant').flatMap(m=>m.content??[]).filter(p=>p.type==='tool');
+ if(parts.some(p=>p.state?.status==='error'||p.name==='question'))return null;
+ const participates=parts.some(p=>p.name==='hybrid_checkpoint'&&p.state?.status==='completed'&&
+  (['plan','escalate'].includes(p.state.input?.action)||p.state.input?.action==='research'&&['note','packages'].includes(p.state.input?.kind)));
+ if(!participates)return null;
+ if(unchangedEscalation(parts))return {notice:'The premium lead already evaluated the unchanged planning evidence. Follow its saved research/decision instructions; no approval was granted and no reset is needed.'};
+ const metadata={source:SOURCE,taskID:state.id,key:next.key};
+ if(turn.some(m=>m.type==='synthetic'&&m.metadata?.source===SOURCE&&m.metadata?.taskID===state.id&&m.metadata?.key===next.key))return {notice:'Planning recovery made no evidence progress. The saved premium directive remains available; report the exact unavailable capability or decision instead of resetting the task. Approval is unchanged.'};
+ return {resume:false,metadata,description:'Hybrid Workflow: returning unfinished planning to the premium lead’s recovery path.',
+  text:`The current planning checkpoint has an actionable next step, not a request to reset the workflow. Continue within this execution. Next kind: ${next.kind}; checkpoint action: ${next.action}. ${next.instructions}\nFor escalate, send the findings and concrete observations in checks to hybrid_checkpoint escalate now. For research, collect only the lead-requested facts, save attributed evidence with research kind=note and submit plan; do not invent security/architecture contracts. For resubmit, call plan with the premium directive and collected evidence. If the directive cannot be followed, escalate the exact missing tool/access or developer decision for premium evaluation. Never waive a finding, disable Hybrid or reset state. This message grants no developer approval; retain all explicit pauses and approval boundaries. New user input or interruption takes precedence.`};
+}