@rockysoft/opencode-hybrid-workflow 1.1.2 → 1.3.0

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/core/workflow-policy.mjs

@@ -1,7 +1,7 @@
 // Shared workflow guidance for the host agents and isolated reviewer processes.
 export const WORKFLOW_POLICY = `Proportionate hybrid workflow:
 Classify by actual change, not page count or code length. Use mode=ui for a visual redesign of an existing app that preserves architecture, data contracts and behavior: go directly to configured design-lead authoring and reviewer validation, then implement and review. Use mode=feature for new applications, substantive new behavior or architecture changes; investigate and plan those before design. Do not label a redesign feature merely because it is substantial visually. Exact cosmetic changes may use cosmetic; faithful bounded extensions use small with existing/supplied design evidence.
-Decision ownership: the configured premium reviewers own material architecture and structural decisions, including new frameworks/dependencies, data models, shared API contracts, server/client boundaries and substantial changes to the approved plan. The implementation model and its native subagents gather facts, present alternatives and implement the approved decisions; they do not independently approve or replace them. The native fullstack-architect is a read-only researcher supporting premium planning. Route a newly discovered material choice through hybrid_checkpoint replan/plan (or design for UI/UX) before dependent implementation. Mechanical implementation details and faithful small/medium extensions within established patterns do not need a new planning ceremony.
+Decision ownership: the configured premium reviewers own material architecture and structural decisions, including new frameworks/dependencies, data models, shared API contracts, server/client boundaries and substantial changes to the approved plan. The implementation model and its native subagents gather facts, present alternatives and implement the approved decisions; they do not independently approve or replace them. The native fullstack-architect is a read-only researcher supporting premium planning. Route a newly discovered material choice through hybrid_checkpoint replan/plan (or design for UI/UX) before dependent implementation. Framework/library replacements or deviations additionally require a proposal with benefits, risks and alternatives followed by explicit developer approval before dependent edits/installs; a premium pass is not that approval. Mechanical implementation details and faithful small/medium extensions within established patterns do not need a new planning ceremony.
 Design acceptance must be risk-based: list changed component families, affected behavior, representative viewports/states and the concrete risk each check covers. Exercise genuinely distinct responsive layouts, error/interaction paths and print behavior that changed. Reuse shared-component coverage; do not demand the Cartesian product of every state and every width by default. Expand coverage when an observed defect or distinct implementation warrants it. An exhaustive matrix invented by an agent is not an explicit user requirement. If an already-approved contract is excessive, obtain a focused design amendment; do not silently ignore it or falsify evidence.
 Separate product defects, missing evidence and preferences. Medium or higher requires a concrete material consequence or an essential unknown about the affected work. A missing screenshot alone is not medium unless that screenshot is necessary to resolve such a risk. Minor documentation wording, optional polish or preferred aesthetics are low/info. Never lower a real defect to force approval.
 Before re-review, address the entire consolidated blocking checklist. Supply checks linking each finding ID to the actual fix and verification; use resolutions [{id,evidence}] for an explicit checklist. Do not send partial submissions hoping another full review will discover what is still missing. If evidence is unavailable, collect it or state the genuine external blocker. No numeric code-line, screenshot-count, correction-round or lifetime-call quota applies.

package/docs/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release notes
 
+## 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.
+- Require a researched Stack implementation contract in new architecture plans, using Context7 and official web documentation matched to selected versions.
+- Require a concrete benefits/risks proposal and explicit developer approval for framework/library replacements or deviations from the existing or approved stack.
+- Refresh managed agent/rule assets when a new plugin version starts. Preserve customized files and report them in diagnostics without changing settings or task history.
+
 ## 1.1.2
 
 - Let blocked planning collect public package metadata, save attributed research notes and read its prior reports without opening application writes or running arbitrary shell commands.

package/docs/planning-recovery.md

@@ -1,22 +1,22 @@
-# 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.

package/docs/stack-planning.md

@@ -0,0 +1,36 @@
+# Stack decisions belong in the project plan
+
+Hybrid's global agents define engineering responsibilities and quality requirements. They do not select a default application framework, database, ORM or cloud.
+
+For a new application, the premium planners recommend a suitable stack and explain why. Before implementation, the approved plan contains the practical rules for using that stack. Research uses **both Context7 and web search with actual official documentation reads**, matched to the selected versions.
+
+For an existing application, keep its stack. Replacing a framework/library or deviating from the existing or approved stack requires a concrete proposal and **explicit developer approval** before dependent edits or installs. Explain benefits/gains, alternatives, migration effort, compatibility/security risks and rollback. A reviewer pass, generic "continue" or permission to build a feature is not that approval. An explicit request for the exact change already supplies it.
+
+## What the plan contains
+
+Use a clearly identified **Stack implementation contract** section in the existing plan; equivalent prose is fine.
+
+| Item | Required content |
+| --- | --- |
+| Decision | Selected technologies/versions, current installed versions, fit, alternatives and compatibility/deployment constraints. Distinguish latest stable from the selected version. |
+| Research | Lookup date, Context7 library ID and actual returned version, official page URLs and the specific facts established. Record unavailable tools or version mismatches and authoritative fallback evidence honestly. |
+| Implementation guidance | Relevant APIs and module ownership, supported patterns, version pitfalls, source citations and meaningful acceptance checks. Separate framework requirements from project choices. |
+| Coverage | Rendering, routing, mutations, state/forms, validation, persistence, identity, failure/concurrency, runtime and tests as applicable. Do not invent services to fill headings. |
+| Approval | For replacements/deviations, the specific developer-approved change and scope. Preserve existing choices while approval is pending. |
+| Deferred checks | Owner, dependent operation, required evidence and failure/replan path. Installation/build checks follow scaffolding; foundational unsafe decisions cannot be deferred. |
+
+Build saves the approved plan and supplies its path and relevant rules to each implementation specialist. Reviewers check evidence and code against that contract. A heading or collection of links does not prove research. Unchanged decisions reuse verified evidence; ordinary existing-pattern edits do not trigger another full-stack study.
+
+## Documentation accuracy
+
+Context7's documented workflow resolves a library before querying its documentation and supports version-qualified IDs. Verify the returned source/version rather than assuming the requested version is indexed. Cross-check material decisions with official version-specific documentation, release notes and compatibility information. See [Context7 MCP tools](https://context7.com/docs/resources/all-clients) and [Context7 API version guidance](https://context7.com/docs/api-guide).
+
+If Context7 lacks a library or a tool is unavailable, record the attempted lookup and use authoritative documentation or bundled source/help as an explicit fallback. Do not fabricate a successful lookup. Resolve essential unknowns before dependent implementation, while continuing independent work. Research sends public technology names and generic API questions only; never private code, credentials or internal URLs.
+
+## Enforcement boundary
+
+This is an agent/reviewer instruction contract, delivered to the host, installed specialists and isolated reviewers. The existing checkpoint still enforces reviewer verdicts and unresolved findings. There is no new heading-count parser, automated claim of documentation verification, or retroactive approval reset. The harness does not independently prove that an agent read a source or that a quoted approval came from the developer; agents and reviewers must verify the actual evidence and authorization.
+
+Framework-specific skill examples remain reference material for the chosen stack. The plugin's own Node/OpenTUI implementation and optional package-script verification adapters are implementation constraints of Hybrid, not instructions to build every application with those technologies.
+
+On startup after a package update, configured standard profiles refresh package-managed agents, rules and skills with backups. Reviewer settings, plugin registration and task history are unchanged. User-customized files are preserved; **Run diagnostics → Managed instructions** lists files that need comparison with the new package. Custom settings-file profiles remain read-only and need their existing installation workflow to update assets.

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));