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

package/core/plugin.mjs

@@ -0,0 +1,91 @@
+import {isReviewerSession} from '../lib/opencode-reviewer.mjs';
+import {roleText} from '../lib/reviewers.mjs';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { WORKFLOW_POLICY } from './workflow-policy.mjs';
+import { Controller } from './controller.mjs';
+import { readDashboard } from './monitor-data.mjs';
+import { DESIGN_POLICY, recordDesignRequest } from './design.mjs';
+import { researchTool } from './research-tools.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// V2's Plugin.define is an identity function. This plain plugin needs no installed dependencies.
+import { FRONTEND_COMMON, FRONTEND_BUILD } from './frontend-policy.mjs';
+export const readTools = /^(read|glob|grep|list|ls|skill|webfetch|websearch|todowrite|todoread|question|subagent|hybrid_checkpoint|hybrid_activity|context7_.+|serena_(find_symbol|find_referencing_symbols|get_symbols_overview|search_for_pattern|read_file|list_dir|find_file|read_memory|list_memories|initial_instructions|check_onboarding_performed)|playwright_browser_(snapshot|take_screenshot|console_messages|network_requests))$/;
+export function createPlugin(config, storage = config.runtimeDirectory ?? path.join(here, 'runtime')) { return {
+  id: 'personal.hybrid-checkpoints',
+  async setup(ctx) {
+    if (!config.enabled) return; // Inert until explicit later activation.
+    const compatible = config.compatibleOpenCode ?? [config.targetOpenCode];
+    if (!compatible.includes(ctx.app.version)) throw new Error(`Hybrid plugin compatibility check required: running OpenCode ${ctx.app.version}; verified versions: ${compatible.join(', ')}. Run the isolated compatibility probe before adding this version. Existing task history is preserved.`);
+    const controllers = new Map();
+    const forSession = async sessionID => {
+      const result = await ctx.session.get({ sessionID });
+      const session = result.data ?? result;
+      const directory = session.location?.directory;
+      if (typeof directory !== 'string') throw new Error('Cannot resolve session workspace; refusing to act on plugin-instance directory.');
+      if (!controllers.has(directory)) controllers.set(directory, new Controller(directory, config.storageFor?.(directory) ?? storage, config));
+      return controllers.get(directory);
+    };
+    await ctx.session.hook('prompt', async event => {
+      if(await isReviewerSession(ctx,event.sessionID))return;
+      const response = await ctx.session.get({sessionID:event.sessionID});
+      const session = response.data ?? response;
+      if (session.parentID) return; // Subagent assignments are not new human design requests.
+      const text = event.prompt.text;
+      if (typeof text === 'string') recordDesignRequest(await forSession(event.sessionID),text,event.messageID);
+    });
+    await ctx.session.hook('context', async event => {
+      if(await isReviewerSession(ctx,event.sessionID))return;
+      event.system.push({type:'text',text:roleText(DESIGN_POLICY)});
+      event.system.push({type:'text',text:roleText(WORKFLOW_POLICY)});
+      event.system.push({type:'text',text:`${FRONTEND_COMMON}\n${FRONTEND_BUILD}`});
+      event.system.push({type:'text',text:'Hybrid recovery: completed negative/blocked code reviews allow corrections and evidence collection in fix; continue automatically and re-review, never claim acceptance. action=fix recovers a legacy completed review. New evidence in checks/images resumes paused plan/design; action=replan with concrete changed requirements opens architecture revision while preserving findings and history. action=inspect checks installed tools and subscription logins without model calls and is available during planning. Never edit bridge state or reset history. Playwright research outputs use plain filenames in .playwright-mcp/hybrid-evidence; this generated evidence is excluded from source snapshots. Navigation/resizing and screenshot capture are available while planning/designing. Supply actual PNGs to plan/design/review as images [{path,caption,artifactHash}], using status.currentArtifactHash for the code/reference being inspected. Recapture after code changes and include interaction evidence in checks. Both reviewers receive pixels; never substitute hashes or ask the user to attest images merely because they live outside Git.'});
+    });
+    await ctx.tool.transform(editor => editor.add({
+      name: 'hybrid_checkpoint',
+      description: 'High-level checkpoints. begin: mode cosmetic/small/ui/feature, brief, designMode none/existing/supplied/new and reference designEvidence for reuse/supplied designs. Use ui for existing-app visual redesigns preserving architecture/behavior; design directly. Feature plan precedes new design: configured lead authors, configured reviewers validate. At least one pass and zero medium/high/critical findings from all configured reviewers required. Negative review permits corrections; fix recovers legacy completed blocked reviews. plan/design accept new checks/images to resolve evidence pauses. replan accepts changed requirements in checks, retaining history/baseline. inspect checks dependencies/auth without model calls. Actual PNG images [{path,caption,artifactHash}] can accompany plan/design/review; use status.currentArtifactHash. Playwright outputs are in project/.playwright-mcp/hybrid-evidence. Follow-up reviews focus on changes and unresolved findings. Supply resolutions [{id,evidence}] for every blocking ID; incomplete explicit checklists return without spending calls. No code-line or screenshot-count quotas. Status is free.',
+      options: { codemode: false },
+      input: { type: 'object', additionalProperties: false, properties: {
+        action: { type: 'string', enum: ['begin', 'plan', 'replan', 'design', 'verify', 'review', 'fix', 'inspect', 'status', 'finish'] },
+        mode: { type: 'string', enum: ['cosmetic', 'small', 'ui', 'feature'] }, brief: { type: 'string' }, checks: { type: 'string' },
+        designMode: {type:'string',enum:['none','existing','supplied','new']}, designEvidence:{type:'string'},
+        script: { type: 'string', enum: ['typecheck', 'lint', 'test', 'build'] },
+        resolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
+        images: { type:'array', items:{type:'object',additionalProperties:false,properties:{path:{type:'string'},caption:{type:'string'},artifactHash:{type:'string'}},required:['path','caption','artifactHash']} },
+      }, required: ['action'] },
+      execute: async (input, context) => {
+        const controller = await forSession(context.sessionID);
+        let pendingProgress = false;
+        const progress = async () => {
+          if (!context.progress || pendingProgress) return;
+          pendingProgress = true;
+          try {
+            const data = readDashboard(controller.folder, config), latest = data.calls.at(-1);
+            await context.progress({ title: latest ? `${latest.who} · ${latest.label} · ${latest.status}` : 'Hybrid checkpoint',
+              output: JSON.stringify({ phase: data.phase, totals: data.totals, latest: latest && { model: latest.resolvedModels, effort: latest.effort, action: latest.currentAction, usage: latest.usage } }) });
+          } catch { /* Monitoring does not change checkpoint outcome. */ } finally { pendingProgress = false; }
+        };
+        const timer = setInterval(progress, 3000); timer.unref();
+        try { const result = await controller.operation(input, context.signal, {sessionID:context.sessionID}); await progress(); return { content: JSON.stringify(result) }; }
+        finally { clearInterval(timer); }
+      },
+    }));
+    await ctx.tool.transform(editor => editor.add({
+      name: 'hybrid_activity', description: 'Read-only reviewer activity, requested/resolved models, effort and CLI-reported token usage. Missing usage is unavailable, not zero. Usage cards are integrated in the sidebar.',
+      options: { codemode: false }, input: { type: 'object', properties: {}, additionalProperties: false },
+      execute: async (_input, context) => {
+        const controller = await forSession(context.sessionID), data = readDashboard(controller.folder, config);
+        return { content: JSON.stringify({ phase: data.phase, operationActive: data.operationActive, totals: data.totals,
+          calls: data.calls.map(({ sequence, who, label, status, requestedModel, resolvedModels, effort, usage, verdict }) => ({ sequence, who, label, status, requestedModel, resolvedModels, effort, usage, verdict })) }) };
+      },
+    }));
+    await ctx.tool.hook('execute.before', async event => {
+      if(await isReviewerSession(ctx,event.sessionID))return;
+      const controller=await forSession(event.sessionID);
+      if(researchTool(event,controller.directory))return;
+      if (!readTools.test(event.tool)) controller.assertWritable();
+    });
+  },
+}; }

package/core/posix-lock.mjs

@@ -0,0 +1,31 @@
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {commandSpec} from '../lib/commands.mjs';
+import {commandEnvironment} from '../lib/platform.mjs';
+
+// macOS has neither Windows named pipes nor Linux abstract Unix sockets.
+// Use an OS advisory lock through Python (already a design-research prerequisite).
+export async function acquirePosixMutex(file){
+ const python=commandSpec('python3');
+ const child=spawn(python.executable,[...python.args,'-I','-u',fileURLToPath(new URL('./posix-lock.py',import.meta.url)),file+'.mutex'],{
+  env:commandEnvironment(),shell:false,windowsHide:true,stdio:['pipe','pipe','pipe'],
+ });
+ let stderr='',failure;
+ child.stderr.on('data',data=>{stderr=(stderr+data).slice(-2000);});
+ child.stdin.on('error',()=>{});
+ child.on('error',error=>{failure=error;});
+ const closed=new Promise(resolve=>child.once('close',code=>resolve(code)));
+ async function release(){
+  child.stdin.end();
+  const timer=setTimeout(()=>child.kill('SIGKILL'),3000);
+  try{await closed;}finally{clearTimeout(timer);}
+ }
+ try{
+  await new Promise((resolve,reject)=>{
+   let output='';const timer=setTimeout(()=>reject(Error('Checkpoint mutex could not start. Check Python 3 in Hybrid diagnostics.')),15000);
+   child.stdout.on('data',data=>{output+=data;if(output==='locked\n'){clearTimeout(timer);resolve();}});
+   closed.then(code=>{clearTimeout(timer);reject(failure??Error(code===73?'Another checkpoint operation is active. Wait for it to finish; history is preserved.':`Checkpoint mutex failed: ${stderr.trim()||'Python exited '+code}`));});
+  });
+  return release;
+ }catch(error){await release();throw error;}
+}

package/core/posix-lock.py

@@ -0,0 +1,23 @@
+"""Kernel-held checkpoint mutex. The inode persists; the lock never does.
+
+Do not unlink this file: unlinking a locked inode permits two simultaneous owners.
+EOF on the parent-owned pipe (including a parent crash) releases the descriptor.
+"""
+import errno
+import fcntl
+import os
+import stat
+import sys
+
+fd = os.open(sys.argv[1], os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+if not stat.S_ISREG(os.fstat(fd).st_mode):
+    raise RuntimeError("Checkpoint mutex must be a regular file")
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except OSError as error:
+    if error.errno in (errno.EACCES, errno.EAGAIN):
+        sys.exit(73)
+    raise
+print("locked", flush=True)
+sys.stdin.buffer.read()
+os.close(fd)

package/core/pricing.mjs

@@ -0,0 +1,53 @@
+// Standard USD API rates per million tokens, verified 2026-10-27.
+export const pricingInfo = {
+  date: '2026-10-27',
+  sources: [
+    { name: 'OpenAI Astra pricing', url: 'https://developers.openai.com/api/docs/models/gpt-6-astra' },
+    { name: 'Anthropic pricing', url: 'https://platform.claude.com/docs/en/about-claude/pricing' },
+  ],
+  basis: 'USD, standard API rates. Astra: $10 input / $1 cache read / $50 output per million tokens. Opus 5.5: $4 input / $0.20 cache read / $20 output; cache writes $5 (5m) or $8 (1h). Haiku 5.5: $0.10 input / $0.01 cache read / $0.50 output below 100K prompt tokens; 5x above. Ranges cover missing per-request context sizes or cache-write lifetimes. Tool-service fees are not included. Subscription payments are separate.',
+};
+const valid = n => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+export function reportedUsage(call) {
+  const parts = Object.values(call.usageByModel ?? {});
+  const fields = ['input','output','cacheRead','cacheWrite','total'];
+  if (!parts.length || !parts.every(u => u && fields.every(k => valid(u[k])))) return call.usage;
+  const summed = Object.fromEntries(fields.map(key => [key, parts.reduce((n,u) => n+u[key],0)]));
+  // Claude's headline usage may cover the main model only; modelUsage also includes helpers.
+  if (valid(call.usage?.total) && summed.total < call.usage.total) return call.usage;
+  return { ...summed, inputIncludesCache: parts[0].inputIncludesCache, reasoningOutput: null };
+}
+function priceUsage(model, u, includesCache) {
+  if (!u || !['input','output','cacheRead','cacheWrite'].every(k => valid(u[k]))) return null;
+  const input = includesCache ? u.input - u.cacheRead : u.input;
+  if (input < 0) return null;
+  const prompt = input + u.cacheRead + u.cacheWrite;
+  let low, high;
+  if (model === 'gpt-6-astra') {
+    low = input * 10 + u.cacheRead + u.cacheWrite * 12.5 + u.output * 50;
+    // Aggregated usage cannot establish whether any individual request exceeded 272K.
+    high = prompt > 272000 ? (input * 10 + u.cacheRead + u.cacheWrite * 25) * 2 + u.output * 75 : input * 10 + u.cacheRead + u.cacheWrite * 25 + u.output * 50;
+  } else if (model === 'claude-opus-5-5') {
+    low = input * 4 + u.cacheRead * .2 + u.cacheWrite * 5 + u.output * 20;
+    high = input * 4 + u.cacheRead * .2 + u.cacheWrite * 8 + u.output * 20;
+  } else if (model === 'claude-haiku-5-5') {
+    low = input * .1 + u.cacheRead * .01 + u.cacheWrite * .125 + u.output * .5;
+    high = (input * .1 + u.cacheRead * .01 + u.cacheWrite * .2 + u.output * .5) * (prompt > 100000 ? 5 : 1);
+  } else return null;
+  return { low: low / 1e6, high: high / 1e6 };
+}
+export function priceCall(call) {
+  if(valid(call.apiCost))return {low:call.apiCost,high:call.apiCost};
+  const entries = Object.entries(call.usageByModel ?? {});
+  if (entries.length) {
+    // Never price a mixed-model aggregate entirely at the primary model's rate.
+    const results = entries.map(([model, usage]) => priceUsage(model, usage, usage?.inputIncludesCache ?? call.who==='astra'));
+    if (results.some(value => !value)) return null;
+    const partsTotal = entries.reduce((sum, [, usage]) => sum + (usage?.total ?? NaN), 0);
+    if (!Number.isFinite(partsTotal) || (valid(call.usage?.total) && partsTotal < call.usage.total)) return null;
+    return { low: results.reduce((sum, p) => sum + p.low, 0), high: results.reduce((sum, p) => sum + p.high, 0) };
+  }
+  if (call.resolvedModels?.length > 1) return null;
+  const model = call.resolvedModels?.[0] ?? call.requestedModel;
+  return priceUsage(model, call.usage, call.usage?.inputIncludesCache ?? call.who==='astra');
+}

package/core/process-identity.mjs

@@ -0,0 +1,19 @@
+import {spawnSync} from 'node:child_process';
+import path from 'node:path';
+export function processIdentity(pid) {
+  if(!Number.isInteger(pid)||pid<1)return null;
+  const windows=process.platform==='win32';
+  const result=windows?spawnSync(path.join(process.env.SystemRoot??'C:/Windows','System32/WindowsPowerShell/v1.0/powershell.exe'),
+    ['-NoLogo','-NoProfile','-NonInteractive','-Command',`try { [Diagnostics.Process]::GetProcessById(${pid}).StartTime.ToUniversalTime().Ticks } catch { exit 1 }`],{encoding:'utf8',windowsHide:true,timeout:5000}):
+    spawnSync('ps',['-p',String(pid),'-o','lstart='],{encoding:'utf8',timeout:5000});
+  const value=result.stdout?.trim();return result.status===0&&value?value:null;
+}
+let selfIdentity;
+export function ownIdentity(){return selfIdentity??=(processIdentity(process.pid));}
+export function sameProcess(pid,identity) {
+  if(!Number.isInteger(pid)||pid<1)return true;
+  try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')return false;return true;}
+  if(!identity)return true;
+  const current=pid===process.pid?ownIdentity():processIdentity(pid);
+  return current===null||current===identity; // Unknown is never silently treated as dead.
+}

package/core/research-tools.mjs

@@ -0,0 +1,37 @@
+import {mkdirSync,realpathSync,lstatSync,existsSync} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+
+const outputs=/^playwright_browser_(snapshot|take_screenshot|console_messages|network_requests)$/;
+const navigation=/^playwright_browser_(navigate|resize|wait_for)$/;
+export function researchTool(event,directory) {
+  const input=event.input??{};
+  if(outputs.test(event.tool)) {
+    // These apparent reads can write files. Always confine those outputs, including during planning.
+    const root=path.join(realpathSync(directory),'.playwright-mcp','hybrid-evidence');
+    mkdirSync(root,{recursive:true});
+    if(realpathSync(root)!==root)throw new Error('Evidence output directory must not contain symbolic links.');
+    const extension=event.tool.endsWith('take_screenshot')?'.png':'.txt';
+    const supplied=input.filename;
+    if(supplied!==undefined&&typeof supplied!=='string')throw new Error('Evidence filename must be text.');
+    const file=supplied?path.resolve(root,supplied):path.join(root,`${randomUUID()}${extension}`);
+    const relative=path.relative(root,file);
+    if(!relative||relative.startsWith('..'+path.sep)||relative==='..'||path.isAbsolute(relative)||path.extname(file).toLowerCase()!==extension)
+      throw new Error(`Save this research output under ${root}, with extension ${extension}. Source files cannot be overwritten by evidence tools.`);
+    // Flat files keep containment check and actual write independent of untrusted subdirectories.
+    if(path.dirname(file)!==root || (existsSync(file)&&(lstatSync(file).isSymbolicLink()||!lstatSync(file).isFile()||lstatSync(file).nlink>1)))throw new Error('Use a plain filename in the evidence output folder.');
+    event.input={...input,filename:file,...(extension==='.png'?{type:'png'}:{})};return true;
+  }
+  if(navigation.test(event.tool)) {
+    if(event.tool.endsWith('navigate')) {
+      let url;try{url=new URL(input.url);}catch{throw new Error('Use an HTTP(S) preview or documentation URL.');}
+      if(!['http:','https:'].includes(url.protocol))throw new Error('Use an HTTP(S) preview or documentation URL.');
+    }
+    return true;
+  }
+  if(event.tool==='serena_activate_project') {
+    if(typeof input.project!=='string'||realpathSync(path.resolve(directory,input.project))!==realpathSync(directory))throw new Error('Activate the current project for research.');
+    return true;
+  }
+  return false;
+}

package/core/review-context.mjs

@@ -0,0 +1,43 @@
+import {lanes} from '../lib/reviewers.mjs';
+import { delta, hash } from './snapshot.mjs';
+import { isMajor } from './decision.mjs';
+
+export function blockingChecklist(feedback = []) {
+  const items = new Map();
+  for (const review of feedback) for (const finding of review.findings ?? []) {
+    if (!isMajor(finding)) continue;
+    const item = items.get(finding.id) ?? { id: finding.id, requirements: [] };
+    item.requirements.push({ reviewer: review.who, severity: finding.severity, category: finding.category,
+      consequence: finding.consequence, resolution: finding.resolution });
+    items.set(finding.id, item);
+  }
+  return [...items.values()];
+}
+
+export function reviewContract(state) {
+  return hash(JSON.stringify([state.brief, state.plan, state.planningClarification, state.designApproval,
+    state.designEvidence, state.recoveries]));
+}
+
+export function followupContext(state, current, images) {
+  const previous = state.reviewCoverage;
+  if (!previous || previous.contract !== reviewContract(state) || !state.measureFrom ||
+      previous.artifactHash !== state.measureFrom.fingerprint || state.reviewFeedback?.length !== (state.reviewerSettings?lanes(state.reviewerSettings).length:2)) return null;
+  const oldImages = new Set(previous.images.map(i => i.sha256));
+  const changes = delta(state.measureFrom, current);
+  return { kind: changes.changed.length ? 'focused-correction' : 'evidence-follow-up',
+    previousArtifactHash: previous.artifactHash, previousReports: state.reviewFeedback,
+    changesSinceReview: changes, requiredFindings: blockingChecklist(state.reviewFeedback),
+    changedImages: images.filter(i => !oldImages.has(i.manifest.sha256)).map(i => i.manifest.path),
+    instruction: 'Verify the open checklist and this delta, including impacted dependencies. Earlier review coverage is context, never automatic approval. Return all still-open findings and a fresh verdict for the current artifact. Do not repeat unrelated review or introduce unrequested acceptance scope.' };
+}
+
+// Structural preflight only: it never asserts a finding has been fixed. Reviewers
+// independently judge the cited evidence. Legacy calls without this field remain usable.
+export function missingResolutions(feedback, resolutions) {
+  if (resolutions === undefined) return [];
+  if (!Array.isArray(resolutions) || resolutions.some(r => !r || typeof r.id !== 'string' || !r.id.trim() ||
+      typeof r.evidence !== 'string' || !r.evidence.trim())) throw new Error('Each resolution needs a finding id and concrete evidence.');
+  const supplied = new Set(resolutions.map(r => r.id));
+  return blockingChecklist(feedback).filter(f => !supplied.has(f.id));
+}

package/core/snapshot.mjs

@@ -0,0 +1,95 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, lstatSync, realpathSync, openSync, closeSync, readSync, readlinkSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export const hash = value => createHash('sha256').update(value).digest('hex');
+const secret = /(^|\/)(\.env(?:\..*)?|.*\.(pem|key|p12|pfx)|credentials?(?:\..*)?|auth\.json|\.npmrc|\.netrc|\.mcp\.json|id_(rsa|ed25519|ecdsa)|opencode\.jsonc?)$|(^|\/)(\.aws|\.ssh|\.azure|\.kube|\.gcloud|\.docker|\.claude|\.codex|\.opencode)\//i;
+const secretContent = /\b(?:sk-ant-[a-zA-Z0-9_-]{20,}|sk-[a-zA-Z0-9_-]{30,}|gh[pousr]_[a-zA-Z0-9]{20,}|AKIA[A-Z0-9]{16})\b|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
+const generated = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?)$/;
+export function initializeProject(directory) {
+  const root = realpathSync(directory);
+  // Begin may initialize this explicit project, never an enclosing repository or a user's home.
+  let ancestor = root;
+  while (true) {
+    if (existsSync(path.join(ancestor, '.git'))) return;
+    const parent = path.dirname(ancestor); if (parent === ancestor) break; ancestor = parent;
+  }
+  if (root === path.parse(root).root || root.toLowerCase() === realpathSync(homedir()).toLowerCase()) throw new Error('Select a dedicated project folder before beginning.');
+  execFileSync('git', ['-C',root,'init','--quiet'], {windowsHide:true});
+}
+function inspectFile(file, name) {
+  const digest = createHash('sha256'), fd = openSync(file,'r'), buffer = Buffer.alloc(65536);
+  let binary = false, sensitive = secret.test(name), previous = '';
+  try { let count; while ((count = readSync(fd,buffer,0,buffer.length,null))) {
+    const chunk=buffer.subarray(0,count); digest.update(chunk); binary ||= chunk.includes(0);
+    const text=previous+chunk.toString('utf8'); sensitive ||= secretContent.test(text); previous=text.slice(-512);
+  } } finally { closeSync(fd); }
+  return {hash:digest.digest('hex'), kind:sensitive?'sensitive':binary?'binary':'text'};
+}
+export function snapshot(directory) {
+  const root = realpathSync(directory);
+  const top = realpathSync(execFileSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', windowsHide: true }).trim());
+  if (root.toLowerCase() !== top.toLowerCase()) throw new Error(`Open the Git repository root for hybrid checkpoints: ${top}`);
+  const names = [...new Set(execFileSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', windowsHide: true, maxBuffer: Infinity }).split('\0').filter(Boolean))].sort();
+  const files = Object.create(null);
+  for (const name of names) {
+    // Dedicated plugin output, never implementation source; capturing evidence must
+    // not change the artifact being reviewed. Only flat PNG/TXT outputs are written here.
+    if(/^\.playwright-mcp\/hybrid-evidence\/[^/]+\.(png|txt)$/i.test(name))continue;
+    const absolute = path.resolve(root, name);
+    if (!absolute.startsWith(root + path.sep)) throw new Error('Out-of-root Git path.');
+    // Git can enumerate through Windows directory junctions. Inventory the link itself,
+    // never copy its target or make removing that link impossible through the gate.
+    let prefix=root, link=false;
+    for(const part of path.relative(root,absolute).split(path.sep)) {
+      prefix=path.join(prefix,part);if(!existsSync(prefix))break;
+      if(lstatSync(prefix).isSymbolicLink()) {
+        const key=path.relative(root,prefix).split(path.sep).join('/');
+        files[key]={hash:hash(readlinkSync(prefix)),text:null,kind:'link',hidden:true,generated:false,note:'Link target is not traversed or transmitted.'};link=true;break;
+      }
+    }
+    if(link)continue;
+    let info;
+    try { info = lstatSync(absolute); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+    if (!info.isFile() || info.isSymbolicLink()) {
+      const target=info.isSymbolicLink()?readlinkSync(absolute):'directory/submodule';
+      files[name]={hash:hash(target),text:null,kind:'link',hidden:true,generated:false,note:'Link/submodule is inventoried, never traversed. Inspect its intended target separately.'}; continue;
+    }
+    const resolved = realpathSync(absolute);
+    if (!resolved.startsWith(root + path.sep)) throw new Error(`File resolves outside project: ${name}`);
+    const inspected=inspectFile(absolute,name);let hidden=inspected.kind!=='text', text=null;
+    if(!hidden) {
+      const data=readFileSync(absolute);if(hash(data)!==inspected.hash)throw new Error(`File changed while being captured: ${name}. Retry after the write finishes.`);
+      text=data.toString('utf8');
+      if(hash(Buffer.from(text))!==inspected.hash){inspected.kind='binary';hidden=true;text=null;}
+    }
+    files[name] = { ...inspected, bytes:info.size, text, generated: generated.test(name), hidden };
+  }
+  return { root, files, fingerprint: hash(JSON.stringify(Object.entries(files).map(([n, f]) => [n, f.hash]))) };
+}
+
+export function delta(before, after) {
+  const changed = [];
+  let lines = 0;
+  for (const name of [...new Set([...Object.keys(before.files), ...Object.keys(after.files)])].sort()) {
+    const a = before.files[name], b = after.files[name];
+    if (a?.hash === b?.hash) continue;
+    if (a?.hidden || b?.hidden) {
+      changed.push({file:name,kind:b?.kind??a?.kind??'opaque',beforeHash:a?.hash??null,afterHash:b?.hash??null,bytes:b?.bytes??0,before:'',after:'',
+        note:'Non-text or sensitive change. Contents are not transmitted. Do not infer correctness from hashes; request applicable screenshots, safe configuration evidence or asset checks. Credentials must never be included.'}); continue;
+    }
+    const oldLines = a?.text?.split('\n') ?? [], newLines = b?.text?.split('\n') ?? [];
+    let first = 0, lastA = oldLines.length, lastB = newLines.length;
+    while (first < lastA && first < lastB && oldLines[first] === newLines[first]) first++;
+    while (lastA > first && lastB > first && oldLines[lastA - 1] === newLines[lastB - 1]) { lastA--; lastB--; }
+    // Conservative changed-span count, not an exact Git line count: scattered edits may checkpoint early.
+    if (!(a?.generated || b?.generated)) lines += lastA - first + lastB - first;
+    changed.push({ file: name, generated: !!(a?.generated || b?.generated), startLine: Math.max(0, first - 3) + 1,
+      before: oldLines.slice(Math.max(0, first - 3), lastA + 3).join('\n'),
+      after: newLines.slice(Math.max(0, first - 3), lastB + 3).join('\n'),
+      note: 'Changed span with 3 context lines. Complete current text is in the captured source tree.' });
+  }
+  return { lines, changed };
+}

package/core/telemetry.mjs

@@ -0,0 +1,107 @@
+import {reviewer} from '../lib/reviewers.mjs';
+import { writeFileSync, renameSync } from 'node:fs';
+import path from 'node:path';
+import {processIdentity} from './process-identity.mjs';
+
+const count = n => Number.isSafeInteger(n) && n >= 0 ? n : null;
+export function normalizeUsage(provider, raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const input = count(raw.input_tokens ?? raw.inputTokens);
+  const output = count(raw.output_tokens ?? raw.outputTokens);
+  const cached = count(raw.cached_input_tokens ?? raw.cache_read_input_tokens ?? raw.cacheReadInputTokens);
+  const written = provider === 'astra' ? 0 : count(raw.cache_creation_input_tokens ?? raw.cacheCreationInputTokens);
+  if (input === null || output === null) return null;
+  // Codex input includes cache reads; Claude input excludes cache reads/writes.
+  const total = provider === 'astra' ? input + output : cached === null || written === null ? null : input + cached + written + output;
+  return { input, output, cacheRead: cached, cacheWrite: written, total,
+    inputIncludesCache: provider === 'astra', reasoningOutput: count(raw.reasoning_output_tokens) };
+}
+
+export function stageLabel(stage) {
+  if (stage === 'design-author') return 'Lead authors UI/UX design';
+  if (stage === 'design-validate') return 'Review exact approved design';
+  if (stage === 'plan-proposal') return 'Independent architecture proposal';
+  if (stage === 'plan-synthesis') return 'Consolidate plan and address findings';
+  if (stage === 'plan-validate') return 'Verify exact shared plan version';
+  const match = /^plan-(\d+)-(independent|synthesis)$/.exec(stage);
+  if (match) {
+    const round = Number(match[1]);
+    return round === 1 ? 'Round 1 · independent proposal' : match[2] === 'synthesis' ? `Round ${round} · reconcile and synthesize plan` : `Round ${round} · compare and challenge prior plans`;
+  }
+  return stage === 'review' ? 'Independent code and security review' : stage;
+}
+
+export class Telemetry {
+  constructor(who, config, folder, metadata = {}) {
+    const lane=reviewer(config,who);
+    this.file = path.join(folder, 'activity.json');
+    this.value = { version: 1, who, adapter:lane.adapter, providerID:lane.providerID, requestedModel: lane.model,
+      effort: lane.variant??lane.effort??'default',
+      resolvedModels: [], stage: metadata.stage ?? 'diagnostic', label: stageLabel(metadata.stage ?? 'diagnostic'),
+      call: metadata.call ?? null, parentPid: process.pid, status: 'preparing', startedAt: new Date().toISOString(),
+      endedAt: null, currentAction: 'Checking subscription authentication', usage: null, usageByModel: {}, toolEvents: [], verdict: null };
+    this.save();
+  }
+  save() {
+    this.value.updatedAt = new Date().toISOString();
+    try { writeFileSync(this.file + '.tmp', JSON.stringify(this.value)); renameSync(this.file + '.tmp', this.file); } catch { /* Observability must never approve/block a checkpoint. */ }
+  }
+  start(pid) { this.value.status = 'running'; this.value.workerPid = pid; this.value.workerIdentity=processIdentity(pid); this.value.currentAction = 'Model working'; this.save(); }
+  event(event) {
+    const v = this.value;
+    if (!event || typeof event !== 'object') return;
+    if (v.adapter === 'codex-cli') {
+      if (event.type === 'turn.completed') {
+        const usage = normalizeUsage('astra', event.usage);
+        if (usage) {
+          if (!v.usage) v.usage = usage;
+          else for (const field of ['input','output','cacheRead','cacheWrite','total','reasoningOutput']) {
+            v.usage[field] = v.usage[field] === null || usage[field] === null ? null : v.usage[field] + usage[field];
+          }
+        }
+      }
+      if (event.type?.startsWith('item.') && event.item?.type) {
+        const labels = { web_search: 'Researching online documentation', command_execution: 'Inspecting with a read-only command', mcp_tool_call: 'Using a research tool', agent_message: 'Producing a report', reasoning: 'Evaluating the task', plan_update: 'Updating the plan' };
+        if (labels[event.item.type]) v.currentAction = labels[event.item.type];
+      }
+      // Do not claim an alias is a resolved model when the CLI does not report one.
+      if (typeof event.model === 'string') v.resolvedModels = [event.model.slice(0, 150)];
+    } else {
+      if (event.type === 'system' && event.subtype === 'init' && typeof event.model === 'string') v.resolvedModels = [event.model.slice(0, 150)];
+      if (event.type === 'assistant') {
+        if (typeof event.message?.model === 'string') v.resolvedModels = [...new Set([...v.resolvedModels, event.message.model.slice(0, 150)])];
+        for (const block of event.message?.content ?? []) {
+          if (block.type === 'tool_use') {
+            const name = String(block.name ?? '').replace(/[^a-zA-Z0-9_.-]/g, '').slice(0, 80);
+            v.currentAction = name ? `Using ${name}` : 'Using a research tool';
+            v.toolEvents = [...v.toolEvents, { name, at: new Date().toISOString() }].slice(-20);
+          }
+        }
+      }
+      if (event.type === 'result') {
+        v.usage = normalizeUsage('opus', event.usage);
+        for (const [model, usage] of Object.entries(event.modelUsage ?? {})) {
+          if (model.length <= 150) v.usageByModel[model] = normalizeUsage('opus', usage);
+        }
+        if (Object.keys(v.usageByModel).length) v.resolvedModels = Object.keys(v.usageByModel);
+      }
+    }
+    this.save();
+  }
+  end(status, verdict = null) {
+    this.value.status = status; this.value.verdict = verdict; this.value.endedAt = new Date().toISOString();
+    this.value.currentAction = status === 'completed' ? 'Report produced' : status === 'cancelled' ? 'Cancelled; no approval' : 'Call failed; checkpoint remains closed';
+    this.save();
+  }
+}
+
+export function jsonLineReader(onEvent) {
+  let pending = '';
+  const emit = () => { if (pending.trim()) { try { onEvent(JSON.parse(pending)); } catch {} } pending = ''; };
+  return { push(text) {
+    for (const [i, part] of text.split('\n').entries()) {
+      if (i > 0) emit();
+      pending += part;
+    }
+  }, finish: emit };
+}