@rockysoft/opencode-hybrid-workflow 0.0.0-stage → 0.3.2-beta.1

package/core/workers.mjs

@@ -0,0 +1,192 @@
+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';
+
+export const resultSchema = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    verdict: { type: 'string', enum: ['pass', 'revise', 'blocked'] },
+    report: { type: 'string' },
+    findings: { type: 'array', items: findingSchema },
+  }, required: ['verdict', 'report', 'findings'],
+};
+
+export function workerArgs(who, config, folder, images = [], browser = 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"',
+    '-c', `model_reasoning_effort="${lane.effort??'high'}"`, '-c', 'web_search="live"',
+    ...(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)}`] : []),
+    ...inlineImages.flatMap(image=>['--image',image]),
+    '--output-schema', path.join(folder, 'schema.json'), '-o', path.join(folder, 'result.json'), '-'];
+  return ['-p', ...(browser?['--setting-sources','','--disable-slash-commands','--settings','{"disableAllHooks":true,"enabledPlugins":{}}']:['--safe-mode']), '--restricted', '--strict-mcp-config', '--mcp-config', JSON.stringify({mcpServers:browser?{review_browser:browser}:{}}),
+    '--no-chrome', '--no-session-persistence', '--permission-mode', 'dontAsk', '--permission-prompts', 'none',
+    '--tools', 'Read,Glob,Grep,WebSearch,WebFetch', '--allowedTools', ['Read','Glob','Grep','WebSearch','WebFetch',...(browser?browserTools.map(name=>'mcp__review_browser__'+name):[])].join(','),
+    '--model', lane.model, '--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'].includes(key))) throw new Error('Invalid reviewer result fields.');
+  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); 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 args = workerArgs(who, config, folder, metadata.images ?? [],browser);
+  if(browser){prompt=browserInstructions+'\n\n'+prompt;telemetry.value.browserAvailable=true;telemetry.save();}
+  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

@@ -0,0 +1,10 @@
+// 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.
+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.
+On follow-up, verify all earlier blocking findings, the new delta and affected dependencies. Reuse prior review coverage for unchanged responsibilities; do not retrace unrelated persistence/security paths for an evidence-only update. Full frozen source remains available whenever a correction affects those paths. Both reviewers still return fresh verdicts for this artifact; a stale pass never approves changed work. Continue only with at least one pass and no unresolved medium/high/critical finding from either completed reviewer.
+All supplied screenshots remain available as frozen local files. Large submissions use file delivery, not rejection or silent omission. Inspect the relevant changed pixels and requested states; do not reread unchanged images solely because they remain in the manifest. Keep evidence honest: captions and hashes do not establish visual or behavioral correctness.
+Independent reviews run concurrently; source remains locked until both settle. No automatic model/provider substitution. Preserve current task history and genuine unresolved findings.`;

package/index.js

@@ -0,0 +1,19 @@
+import {resolveNativeGuards} from './core/operation-lock.mjs';
+import {installNativeReviewer} from './lib/opencode-reviewer.mjs';
+import {createPlugin} from './core/plugin.mjs';
+import {readSettings,runtimeFor} from './lib/config.mjs';
+import {registerSettings} from './lib/settings-service.mjs';
+export default {id:'personal.hybrid-checkpoints', async setup(ctx) {
+  await registerSettings(ctx,ctx.options);
+  const config=readSettings(ctx.options);
+  if(!config.enabled)return;
+  if(!/^2\./.test(ctx.app?.version ?? '')||typeof ctx.session?.hook!=='function'||typeof ctx.tool?.transform!=='function'||typeof ctx.tool?.hook!=='function')
+    throw Error('Hybrid workflow needs OpenCode 2 with session/tool plugin hooks. Run opencode-hybrid doctor.');
+  // Validate the actual hook surface, not a pinned patch version.
+  config.compatibleOpenCode=[ctx.app.version];
+  config.storageFor=directory=>runtimeFor(config,directory);
+  config.reloadSettings=()=>readSettings(ctx.options);
+  config.nativeRunner=await installNativeReviewer(ctx);
+  config.resolveNativeSessions=file=>resolveNativeGuards(file,async sessionID=>{const value=await ctx.session.get({sessionID});return value.data??value;});
+  await createPlugin(config).setup(ctx);
+}};

package/lib/commands.mjs

@@ -0,0 +1,48 @@
+import {existsSync,readFileSync,readdirSync,statSync,accessSync,constants} from 'node:fs';
+import path from 'node:path';
+import {commandDirectories} from './platform.mjs';
+// Never invoke a shell or interpolate arguments. Windows package-manager shims
+// are resolved to their literal Node/native target, or rejected with a useful error.
+export function commandSpec(command, env=process.env, platform=process.platform) {
+  if(typeof command!=='string'||!command)throw Error('Executable must be a nonempty string.');
+  const suffixes=platform==='win32'?['.exe','.cmd','']:[''];
+  const dirs=path.isAbsolute(command)?['']:commandDirectories(env,platform);
+  let found;
+  for(const dir of dirs) {
+    for(const suffix of path.extname(command)?['']:suffixes) {
+      const file=dir?path.resolve(dir,command+suffix):command+suffix;
+      try{if(statSync(file).isFile()){if(platform!=='win32')accessSync(file,constants.X_OK);found=file;break;}}catch{}
+    }
+    if(found)break;
+  }
+  if(!found)throw Error(`Executable not found: ${command}. Install it or set its absolute path in hybrid/config.json.`);
+  if(platform!=='win32'||!/\.(cmd|bat)$/i.test(found))return {executable:found,args:[]};
+  const dir=path.dirname(found),text=readFileSync(found,'utf8');
+  // npm/pnpm generated wrappers quote the %dp0% or %~dp0 relative executable.
+  const candidates=[...text.matchAll(/"%(?:dp0|~dp0)%?[\\/]([^"\r\n]+\.(?:[cm]?js|exe))"/gi)].map(m=>path.resolve(dir,m[1]));
+  // Current Node installers use a variable-based npm wrapper. Resolve its
+  // literal bundled CLI assignment, without executing its prefix lookup shell.
+  const npmCLI=text.match(/SET "NPM_CLI_JS=%~dp0[\\/]([^"\r\n]*npm-cli\.js)"/i);
+  if(npmCLI)candidates.unshift(path.resolve(dir,npmCLI[1]));
+  const target=candidates.find(f=>existsSync(f)&&!/node\.exe$/i.test(f));
+  if(!target)throw Error(`Cannot safely resolve shim ${found}. Configure the native executable or Node script path.`);
+  if(/\.exe$/i.test(target))return {executable:target,args:[]};
+  const nodeCandidates=[path.join(dir,'node.exe'),...String(env.PATH??env.Path??'').split(path.delimiter).filter(Boolean).map(p=>path.join(p,'node.exe'))];
+  const node=nodeCandidates.find(file=>existsSync(file));
+  if(!node)throw Error('Node executable not found for package-manager shim; install Node or add it to PATH.');
+  return {executable:node,args:[target]};
+}
+export function nativeCodex(command) {
+  const spec=commandSpec(command);
+  if(!spec.args.length)return command;
+  const script=spec.args[0];
+  const modules=path.resolve(script,'../../..');
+  const arch=process.arch==='arm64'?'arm64':'x64';
+  const platform=process.platform==='win32'?`codex-win32-${arch}`:process.platform==='darwin'?`codex-darwin-${arch}`:`codex-linux-${arch}`;
+  const vendor=path.join(modules,'codex','node_modules','@openai',platform,'vendor');
+  if(existsSync(vendor))for(const entry of readdirSync(vendor)) {
+    const executable=path.join(vendor,entry,'bin',process.platform==='win32'?'codex.exe':'codex');
+    if(existsSync(executable))return executable;
+  }
+  return command;
+}

package/lib/config.mjs

@@ -0,0 +1,63 @@
+import {existsSync, readFileSync, realpathSync} from 'node:fs';
+import {homedir} from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {lanes} from './reviewers.mjs';
+import {validateBrowser} from './reviewer-browser.mjs';
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export function configDirectory(env=process.env, home=homedir()) {
+  return path.resolve(env.OPENCODE_CONFIG_DIR || path.join(env.XDG_CONFIG_HOME || path.join(home,'.config'),'opencode'));
+}
+export function defaultSettings(env=process.env, home=homedir()) {
+  const data = process.platform==='win32' ? (env.LOCALAPPDATA || path.join(home,'AppData','Local')) : (env.XDG_DATA_HOME || path.join(home,'.local','share'));
+  return {version:1, enabled:true, runtimeDirectory:path.join(data,'opencode-hybrid','runtime'), projectRuntimeOverrides:{},
+    reviewers:{astra:{adapter:'codex-cli',model:'gpt-6-astra',effort:'high',executable:'codex'},opus:{adapter:'claude-cli',model:'opus',effort:'high',executable:'claude'}},
+    verification:{executable:'pnpm',timeoutMs:0},reviewTimeoutMs:0,maxPacketChars:400000,
+    design:{pythonExecutable:process.platform==='win32'?'python':'python3',skillsDirectory:path.join(packageRoot,'assets','skills')}};
+}
+export function settingsFile(options={},env=process.env) {
+  const trusted=env.OPENCODE_HYBRID_CONFIG || path.join(configDirectory(env),'hybrid','config.json');
+  const file=options.configFile || trusted;
+  if(!path.isAbsolute(file))throw Error('Hybrid configFile must be an absolute path to user-owned configuration.');
+  const normalize=value=>process.platform==='win32'?path.resolve(value).toLowerCase():path.resolve(value);
+  if(normalize(file)!==normalize(trusted))throw Error('Plugin options cannot select executable settings outside the user config. Use OPENCODE_CONFIG_DIR or OPENCODE_HYBRID_CONFIG from your own launcher.');
+  if(!env.OPENCODE_HYBRID_CONFIG&&existsSync(file)) {
+    const base=realpathSync(configDirectory(env)),resolved=realpathSync(file),relative=path.relative(base,resolved);
+    if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative))throw Error('Hybrid config symlink escapes the user configuration directory.');
+  }
+  return file;
+}
+export function readSettings(options={},env=process.env) {
+  const file=settingsFile(options,env), defaults=defaultSettings(env);
+  const supplied=existsSync(file)?JSON.parse(readFileSync(file,'utf8')):{};
+  if(supplied.version!==undefined&&supplied.version!==1)throw Error('Unsupported hybrid configuration version.');
+  const config={...defaults,...supplied,reviewers:Object.fromEntries(['astra','opus'].map(who=>[who,supplied.reviewers?.[who]===null?null:supplied.reviewers?.[who]?.adapter&&supplied.reviewers[who].adapter!==defaults.reviewers[who].adapter?supplied.reviewers[who]:{...defaults.reviewers[who],...supplied.reviewers?.[who]}])),
+    design:{...defaults.design,...supplied.design},verification:{...defaults.verification,...supplied.verification}};
+  if(options.enabled===false)config.enabled=false;
+  validateBrowser(config.reviewBrowser);
+  for(const who of ['astra','opus']) {
+    if(supplied.reviewers?.[who]===null)config.reviewers[who]=null;
+    const lane=config.reviewers[who];
+    if(lane===null||lane.enabled===false)continue;
+    if(!['codex-cli','claude-cli','opencode'].includes(lane.adapter))throw Error(`Unsupported reviewer adapter: ${lane.adapter}`);
+    for(const key of lane.adapter==='opencode'?['model','providerID']:['model','executable'])if(typeof lane[key]!=='string'||!lane[key].trim())throw Error(`reviewers.${who}.${key} is required.`);
+    if(lane.effort && !/^[a-zA-Z0-9_-]+$/.test(lane.effort))throw Error('Invalid reasoning effort.');
+  }
+  if(!lanes(config).includes('astra'))throw Error('Reviewer 1 (astra storage slot) is required; disable reviewer 2 for single-reviewer mode.');
+  if(config.designAuthor && !lanes(config).includes(config.designAuthor))throw Error('designAuthor must name an enabled reviewer slot.');
+  if(!path.isAbsolute(config.runtimeDirectory))throw Error('runtimeDirectory must be absolute.');
+  for(const [project,root] of Object.entries(config.projectRuntimeOverrides))if(!path.isAbsolute(project)||typeof root!=='string'||!path.isAbsolute(root))throw Error('Project/runtime overrides must use absolute paths.');
+  for(const n of [config.reviewTimeoutMs,config.verification.timeoutMs])if(!Number.isFinite(n)||n<0)throw Error('Timeout must be zero (disabled) or a positive duration.');
+  return {...config,configFile:file, codex:config.reviewers.astra,claude:config.reviewers.opus,pnpmExecutable:config.verification.executable,verificationTimeoutMs:config.verification.timeoutMs};
+}
+export function canonicalProject(directory) {
+  const value=realpathSync(directory);
+  return process.platform==='win32'?value.toLowerCase():value;
+}
+export function runtimeFor(config,directory) {
+  const project=canonicalProject(directory);
+  for(const [key,runtime] of Object.entries(config.projectRuntimeOverrides ?? {})) {
+    try {if(canonicalProject(key)===project)return runtime;}catch { /* An absent old project does not affect other projects. */ }
+  }
+  return config.runtimeDirectory;
+}

package/lib/install.mjs

@@ -0,0 +1,111 @@
+import {existsSync,readFileSync,writeFileSync,mkdirSync,readdirSync,lstatSync,realpathSync,renameSync,unlinkSync} from 'node:fs';
+import path from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import {packageRoot,configDirectory,defaultSettings} from './config.mjs';
+const digest=text=>createHash('sha256').update(text).digest('hex');
+const json=text=>JSON.stringify(text,null,2)+'\n';
+export function parseJsonc(text) {
+  let stripped='',quoted=false,escape=false;
+  for(let i=0;i<text.length;i++) {
+    const c=text[i],next=text[i+1];
+    if(quoted){stripped+=c;if(escape)escape=false;else if(c==='\\')escape=true;else if(c==='"')quoted=false;continue;}
+    if(c==='"'){quoted=true;stripped+=c;continue;}
+    if(c==='/'&&next==='/'){while(i<text.length&&text[i]!=='\n')i++;stripped+='\n';continue;}
+    if(c==='/'&&next==='*'){i+=2;while(i<text.length&&!(text[i]==='*'&&text[i+1]==='/'))i++;if(i>=text.length)throw Error('Unterminated JSON comment');i++;stripped+=' ';continue;}
+    stripped+=c;
+  }
+  let result='';quoted=false;escape=false;
+  for(let i=0;i<stripped.length;i++) {
+    const c=stripped[i];
+    if(quoted){result+=c;if(escape)escape=false;else if(c==='\\')escape=true;else if(c==='"')quoted=false;continue;}
+    if(c==='"')quoted=true;
+    if(c===','&&/^[\s]*[}\]]/.test(stripped.slice(i+1)))continue;
+    result+=c;
+  }
+  return JSON.parse(result.replace(/^\uFEFF/,''));
+}
+export function safeTarget(root,file) {
+  const absolute=path.resolve(file),relative=path.relative(path.resolve(root),absolute);
+  if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative))throw Error('Install target is outside config directory.');
+  let current=path.resolve(root);
+  if(existsSync(current)&&lstatSync(current).isSymbolicLink())throw Error('Config directory must not be a symlink.');
+  for(const part of relative.split(path.sep)) {
+    current=path.join(current,part);
+    if(existsSync(current)&&lstatSync(current).isSymbolicLink())throw Error(`Refusing symlink install target: ${current}`);
+  }
+  return absolute;
+}
+const pluginName=value=>typeof value==='string'?value:value?.package;
+const ours=value=>/(?:^|[/\\])opencode-hybrid-workflow(?:@[^/\\]+)?$/.test(pluginName(value)??'');
+const legacySidebar=value=>/(?:^|[/\\])hybrid-usage$/.test(pluginName(value)??'');
+function assetFiles(root,prefix='') {
+  return readdirSync(root,{withFileTypes:true}).flatMap(e=>{
+    if(e.isSymbolicLink())throw Error('Bundled assets must not contain symlinks.');
+    return e.isDirectory()?assetFiles(path.join(root,e.name),prefix+e.name+'/'):[prefix+e.name];
+  });
+}
+function configPath(root,name) {
+  const plain=path.join(root,name+'.json'),comments=path.join(root,name+'.jsonc');
+  if(existsSync(plain)&&existsSync(comments))throw Error(`Both ${name}.json and ${name}.jsonc exist. Resolve ambiguity before installation.`);
+  return existsSync(comments)?comments:plain;
+}
+export function install({root=configDirectory(),source=packageRoot,settingsPatch={},replaceLegacyPackage,apply=true,registerPlugin=true}={}) {
+  root=path.resolve(root);source=realpathSync(source);
+  const edits=[],conflicts=[];
+  const read=(file,fallback={})=>existsSync(file)?parseJsonc(readFileSync(safeTarget(root,file),'utf8')):fallback;
+  const settingsPath=path.join(root,'hybrid','config.json');
+  const existing=read(settingsPath);
+  const settings={...defaultSettings(),...existing,...settingsPatch};
+  // Package-owned bundled skills resolve at runtime; only explicit user overrides persist.
+  if(!existing.design&&!settingsPatch.design)delete settings.design;
+  const managedPath=path.join(root,'hybrid','installed.json');
+  const managed=read(managedPath,{files:{}}),files={...managed.files};
+  function stage(file,body) {
+    safeTarget(root,file);
+    const before=existsSync(file)?readFileSync(file,'utf8'):null;
+    if(before!==body)edits.push({file,before,body});
+  }
+  stage(settingsPath,json(settings));
+  for(const name of ['opencode','cli']) {
+    const file=configPath(root,name),value=read(file);
+    if(value.plugins!==undefined&&!Array.isArray(value.plugins))throw Error('plugins must be an array.');
+    // Remove only entries owned by this package (and the superseded personal sidebar).
+    if(registerPlugin){
+      const plugins=(value.plugins??[]).filter(p=>!ours(p)&&path.normalize(pluginName(p)??'')!==path.normalize(source)&&!(name==='opencode'&&replaceLegacyPackage&&path.normalize(pluginName(p)??'')===path.normalize(replaceLegacyPackage))&&!(name==='cli'&&legacySidebar(p)));
+      const entry={package:source.replaceAll('\\','/'),options:{configFile:settingsPath}};
+      value.plugins=[...plugins,entry];
+    }
+    if(name==='opencode') {
+      const rules=path.join(root,'hybrid','rules.md');
+      if(value.instructions!==undefined&&!Array.isArray(value.instructions))throw Error('instructions must be an array.');
+      value.instructions=[...new Set([...(value.instructions??[]),rules])];
+    }
+    if(registerPlugin||name==='opencode')stage(file,json(value));
+  }
+  for(const relative of ['hybrid/rules.md',...assetFiles(path.join(source,'assets','agents')).map(n=>'agents/'+n),...assetFiles(path.join(source,'assets','skills')).map(n=>'skills/'+n)]) {
+    const asset=relative==='hybrid/rules.md'?'rules.md':relative;
+    const body=readFileSync(path.join(source,'assets',asset),'utf8'),file=path.join(root,relative);
+    safeTarget(root,file);
+    const before=existsSync(file)?readFileSync(file,'utf8'):null;
+    if(before!==null&&before!==body&&files[relative]!==digest(before)){conflicts.push(relative);continue;}
+    stage(file,body);files[relative]=digest(body);
+  }
+  const manifest={version:1,packageVersion:JSON.parse(readFileSync(path.join(source,'package.json'),'utf8')).version,files};
+  stage(managedPath,json(manifest));
+  const backup=path.join(root,'backups','hybrid-'+Date.now()+'-'+randomUUID());
+  if(apply&&edits.length) {
+    for(const edit of edits) {
+      if(edit.before!==null){const copy=path.join(backup,path.relative(root,edit.file));safeTarget(root,copy);mkdirSync(path.dirname(copy),{recursive:true,mode:0o700});writeFileSync(copy,edit.before,{flag:'wx',mode:0o600});}
+    }
+    // No task/session/runtime files are touched by installation.
+    const prepared=[],committed=[];
+    try {
+      for(const edit of edits){mkdirSync(path.dirname(edit.file),{recursive:true});const temporary=edit.file+'.hybrid-'+randomUUID();writeFileSync(temporary,edit.body,{flag:'wx',mode:0o600});prepared.push({...edit,temporary});}
+      for(const edit of prepared){renameSync(edit.temporary,edit.file);committed.push(edit);}
+    }catch(error){
+      for(const edit of committed.reverse()){if(edit.before===null)unlinkSync(edit.file);else writeFileSync(edit.file,edit.before,{mode:0o600});}
+      throw error;
+    }finally{for(const edit of prepared)if(existsSync(edit.temporary))unlinkSync(edit.temporary);}
+  }
+  return {configDirectory:root,settingsPath,changed:edits.map(e=>path.relative(root,e.file)),preservedCustomFiles:conflicts,backup:apply&&edits.length?backup:null,applied:apply};
+}

package/lib/native-browser.mjs

@@ -0,0 +1,79 @@
+import {spawn,spawnSync} from 'node:child_process';
+import {createInterface} from 'node:readline';
+import path from 'node:path';
+import {prepareBrowser,browserTools} from './reviewer-browser.mjs';
+import {workerEnvironment} from '../core/workers.mjs';
+import {processIdentity} from '../core/process-identity.mjs';
+
+// One transport per reviewer, started only if that reviewer uses the browser.
+export class NativeBrowser {
+  constructor(config,folder) { this.config=config;this.folder=folder;this.pending=new Map();this.nextID=0; }
+  async start() {
+    if(this.stopping)throw Error('Review browser has closed.');
+    return this.starting??=(async()=>{
+      const launch=prepareBrowser(this.config,this.folder);
+      if(!launch)throw Error('Reviewer browser access is disabled.');
+      const child=this.child=spawn(launch.command,launch.args,{cwd:this.folder,env:workerEnvironment(),shell:false,windowsHide:true,detached:process.platform!=='win32',stdio:['pipe','pipe','pipe']});
+      this.closed=new Promise(resolve=>child.once('close',()=>{this.exited=true;this.fail(Error('Review browser transport closed.'));resolve();}));
+      child.on('error',error=>this.fail(error));child.stdin.on('error',error=>this.fail(error));child.stderr.resume();
+      this.lines=createInterface({input:child.stdout});
+      this.lines.on('line',line=>{
+        let message;try{message=JSON.parse(line);}catch{return;}
+        if(message.method){if(message.id!==undefined)child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:message.id,error:{code:-32601,message:'Unsupported client request'}})+'\n');return;}
+        const request=this.pending.get(message.id);if(!request)return;
+        this.pending.delete(message.id);clearTimeout(request.timer);
+        if(message.error)request.reject(Error(message.error.message??'Browser MCP request failed.'));else request.resolve(message.result);
+      });
+      await this.request('initialize',{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'opencode-hybrid-reviewer',version:'1'}});
+      child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'})+'\n');
+      const listing=await this.request('tools/list',{});
+      this.tools=(listing.tools??[]).filter(tool=>browserTools.includes(tool.name));
+    })();
+  }
+  fail(error){this.failure=error;for(const request of this.pending.values()){clearTimeout(request.timer);request.reject(error);}this.pending.clear();}
+  request(method,params){
+    if(this.failure||this.stopping)return Promise.reject(this.failure??Error('Review browser is closing.'));
+    return new Promise((resolve,reject)=>{
+      const id=++this.nextID;
+      const timer=setTimeout(()=>{this.pending.delete(id);reject(Error('Browser operation timed out. Retry the observation; no review approval is implied.'));},120000);
+      this.pending.set(id,{resolve,reject,timer});
+      this.child.stdin.write(JSON.stringify({jsonrpc:'2.0',id,method,params})+'\n');
+    });
+  }
+  async execute(input,vision) {
+    if(input.tool&&!browserTools.includes(input.tool))throw Error('Tool is not available to reviewers.');
+    if(input.tool==='browser_take_screenshot'&&!vision)throw Error('Selected reviewer cannot inspect image pixels. Select a vision-capable model for visual review.');
+    await this.start();
+    if(!input.tool)return {content:JSON.stringify({tools:this.tools})};
+    if(!this.tools.some(tool=>tool.name===input.tool))throw Error('Tool is unavailable in the installed browser MCP.');
+    const result=await this.request('tools/call',{name:input.tool,arguments:input.arguments??{}});
+    return browserContent(result,vision);
+  }
+  async close(){return this.closing??=(async()=>{
+    this.stopping=true;this.fail(Error('Review browser is closing.'));
+    if(!this.child)return;
+    const child=this.child;
+    child.stdin.end();
+    const wait=ms=>new Promise(resolve=>{const timer=setTimeout(()=>resolve(false),ms);this.closed.then(()=>{clearTimeout(timer);resolve(true);});});
+    if(await wait(3000))return;
+    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,'SIGKILL');}catch{child.kill('SIGKILL');}}
+    if(await wait(5000))return;
+    const error=Error('Reviewer browser termination could not be confirmed; checkpoint remains closed.');
+    error.unreapedPid=child.pid;error.workerIdentity=processIdentity(child.pid);error.descendantsUnconfirmed=true;
+    this.lines?.close();child.stdin.destroy();child.stdout.destroy();child.stderr.destroy();child.unref();throw error;
+  })();}
+}
+
+export function browserContent(result,vision){
+  const content=[];
+  for(const item of result.content??[]){
+    if(item.type==='text')content.push({type:'text',text:item.text});
+    else if(item.type==='image'){
+      if(vision)content.push({type:'file',uri:`data:${item.mimeType};base64,${item.data}`,mime:item.mimeType,name:'browser-capture'});
+      else content.push({type:'text',text:'Image pixels unavailable to this model. Do not claim visual inspection.'});
+    }
+  }
+  if(result.isError)content.unshift({type:'text',text:'Browser operation failed. The following is an error, not successful evidence.'});
+  return {content:content.length?content:[{type:'text',text:'Browser returned no inspectable content.'}]};
+}