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

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/docs/configuration.md

@@ -0,0 +1,134 @@
+# Configuration reference
+
+Use Hybrid Workflow settings inside OpenCode for routine setup. These details are for advanced configuration and migration.
+
+For terminal commands below, use `npx --package @rockysoft/opencode-hybrid-workflow@beta opencode-hybrid` in place of `opencode-hybrid` unless you installed the standalone CLI globally.
+
+## Configuration
+
+Both CLI and OpenCode-provider reviewers can independently inspect the running
+app with Playwright. Configure this through **Hybrid Workflow settings > Reviewer
+browser**. Installing browser support downloads a pinned Playwright MCP package
+and Firefox into plugin-managed tooling, then enables isolated headless sessions.
+The existing implementation MCP entry is preserved. Existing browser commands can
+also be enabled without downloading replacements.
+
+Advanced settings live in `reviewBrowser` in `hybrid/config.json`: `command`,
+`browser` (chrome/msedge/firefox/webkit), and `headless`. The CLI browser commands
+remain available for scripted administration.
+
+All reviewer adapters can navigate, inspect DOM, resize, click,
+fill test forms, evaluate page JavaScript, inspect console/network information,
+and capture screenshots. Output goes to that review's `browser-artifacts`; tool
+names are logged in `actions.jsonl`. This is not desktop control or the user's
+signed-in browser. Source edits, server startup, local-file upload and arbitrary
+host-code execution remain unavailable; Codex retains read-only shell inspection
+of evidence, while Claude uses its read tools. Browser interactions can still mutate application
+data: use a disposable test environment and synthetic data. Reviewers are told
+to inspect relevant states directly and distinguish live observations from the
+frozen source artifact. Supply the actual app URL in checkpoint checks and keep
+the development/test server running. Browser access does not authorize a reviewer
+to start/restart the app server.
+
+OpenCode-provider reviewers use the internal `hybrid_browser` tool for the same
+isolated Playwright access. Each call has its own browser process, started only
+when needed and closed before the review completes. Browser sessions are never
+shared between reviewers or inherited from the implementation agent. Vision-capable
+models receive actual image pixels; text-only models cannot approve visual evidence.
+
+`opencode-hybrid config` prints the configuration location, normally
+`~/.config/opencode/hybrid/config.json`. `OPENCODE_CONFIG_DIR`,
+`OPENCODE_HYBRID_CONFIG` can choose another user-owned location from your launcher.
+Plugin `options.configFile` must match that trusted location; a project cannot
+redirect reviewer executable settings to its own file. The installer supports
+`--config-dir PATH` for a separate profile.
+Do not put credentials in this file; OpenCode or the selected official CLI owns authentication.
+
+`opencode-hybrid configure` opens an interactive selector: choose one or two
+reviewers, OpenCode provider or external CLI for each, model, supported variant/CLI effort, and the
+planning/design lead. Either slot can use any supported adapter, including two
+OpenCode models, two CLI models, or one of each. `opencode-hybrid models` lists the
+enabled tool-capable models from your OpenCode provider catalog. Any enabled
+provider is eligible; Copilot is an ordinary catalog provider, not a special adapter. No local model
+server, GPU setup, Strata launcher or model download is managed by this package.
+
+Noninteractive examples (use actual IDs returned by `models`):
+
+```sh
+opencode-hybrid configure --reviewer1 codex-cli:gpt-6-astra --reviewer2 claude-cli:opus --variant1 high --variant2 high
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 none
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 claude-cli:opus --variant1 SUPPORTED_VARIANT
+```
+
+```json
+{
+  "version": 1,
+  "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
+}
+```
+
+`astra` and `opus` are stable storage-slot IDs, not provider restrictions. Set the
+second slot to `null` for one reviewer. An OpenCode slot has
+`{"adapter":"opencode","providerID":"...","model":"...","variant":"..."}`;
+omit `variant` for the provider default. There is no invented universal effort
+mapping. `designAuthor` selects `astra` or `opus`; default is the last enabled slot.
+Legacy defaults remain Codex/Astra and Claude/Opus, both high effort; first-run
+setup asks for explicit choices and initially highlights OpenCode providers.
+
+Native reviewers run in read-only OpenCode child sessions with only frozen
+evidence, public-documentation tools and the optional isolated browser. They cannot edit source, delegate or
+recursively start checkpoints. Image reviews require an image-capable model.
+Unknown/disabled models, unsupported variants and invalid reports fail explicitly;
+there is no provider fallback. Provider context limits still apply.
+
+Reviewer assignments are pinned for an active task; changing defaults affects
+the next task without restarting OpenCode. Existing findings are retained. One
+reviewer must pass with no medium-or-higher findings; it does not claim independent
+cross-model agreement. With two, both reports must complete and neither may have
+an unresolved medium-or-higher finding. Low/info suggestions do not block a pass.
+
+Installation merges plugin entries into `opencode.json` and `cli.json`, installs
+nine specialist definitions and the three design skills, and adds a managed rules
+file. Existing custom agent/skill files are preserved and reported. Other settings,
+permissions and implementation-model choices are retained. JSONC is accepted;
+comments are removed from the rewritten file, with an exact original backup.
+Updates replace only unchanged package-managed instruction files. It does not
+import personal project memories or modify Claude/Codex global rules.
+
+## Storage and existing sessions
+
+New state lives outside both the package and project: Windows uses
+`%LOCALAPPDATA%/opencode-hybrid/runtime`, other platforms use
+`$XDG_DATA_HOME/opencode-hybrid/runtime` or `~/.local/share/opencode-hybrid/runtime`.
+Projects are isolated by canonical path. Checkpoints are project-scoped; concurrent
+conversations editing the same project must coordinate against the same gate.
+Opening a subfolder of a Git repository asks you to open its root.
+
+To retain a trial project's exact existing history without copying/resetting it:
+
+```sh
+opencode-hybrid init --legacy-config /path/to/old/config.json --project /path/to/project
+```
+
+Only that project receives a runtime override; new projects use portable storage.
+OpenCode conversation history is separate. Sessions created under an isolated
+`XDG_DATA_HOME` remain in that profile; installation does not move them. Existing
+trial profiles stay usable. Restart OpenCode to load changed modules; installation
+does not interrupt running sessions or restart model servers.
+
+## Troubleshooting
+
+Use **Hybrid Workflow settings > Run diagnostics** to check prerequisites,
+reviewer connections, design skills and browser access. Sign in to each provider
+on the machine where you use OpenCode. Reopen OpenCode after a plugin update.
+
+## License
+
+The original plugin code is MIT-licensed; bundled skills retain their own
+licenses as listed in `THIRD_PARTY_NOTICES.md`. Authenticate providers on each
+machine rather than copying account credentials.

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;
+}