@rockysoft/opencode-hybrid-workflow 0.9.0 → 0.9.1

package/core/plugin.mjs

@@ -1,93 +1,93 @@
-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: 'Hybrid-Workflow',
-  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. browser: capture declared package.json hybrid.browser static frontend scenarios with disposable API fixtures; see docs/browser-evidence.md. Results attach to reviews automatically and do not grant approval. Builds need approval; source-only baseline capture can run earlier. For SSR/live backends retain existing integration tests and images/checks. Status is free.',
-      options: { codemode: false },
-      input: { type: 'object', additionalProperties: false, properties: {
-        action: { type: 'string', enum: ['begin', 'plan', 'replan', 'design', 'verify', 'browser', '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'] },
-        verificationMode:{type:'string',enum:['auto','full'],description:'auto honors a project deterministic Vitest input contract; full always executes the entire script. Targeted checks are partial coverage, never a full-suite pass.'},
-        resolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
-        retryReason:{type:'string',description:'After repeated identical reviewer transport/auth/schema failure, describe new diagnostic/recovery evidence. Does not change review evidence, clear findings or grant approval.'},
-        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();
-    });
-  },
-}; }
+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: 'Hybrid-Workflow',
+  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 CLI 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. browser: capture declared package.json hybrid.browser static frontend scenarios with disposable API fixtures; see docs/browser-evidence.md. Results attach to reviews automatically and do not grant approval. Builds need approval; source-only baseline capture can run earlier. For SSR/live backends retain existing integration tests and images/checks. Status is free.',
+      options: { codemode: false },
+      input: { type: 'object', additionalProperties: false, properties: {
+        action: { type: 'string', enum: ['begin', 'plan', 'replan', 'design', 'verify', 'browser', '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'] },
+        verificationMode:{type:'string',enum:['auto','full'],description:'auto honors a project deterministic Vitest input contract; full always executes the entire script. Targeted checks are partial coverage, never a full-suite pass.'},
+        resolutions: {type:'array',items:{type:'object',additionalProperties:false,properties:{id:{type:'string'},evidence:{type:'string'}},required:['id','evidence']}},
+        retryReason:{type:'string',description:'After repeated identical reviewer transport/auth/schema failure, describe new diagnostic/recovery evidence. Does not change review evidence, clear findings or grant approval.'},
+        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/telemetry.mjs

@@ -1,111 +1,111 @@
-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.trace=metadata.trace;this.callSpan=metadata.callSpan;
-    this.callSpan?.measure({adapter:lane.adapter,providerID:lane.providerID,model:lane.model,effort:lane.variant??lane.effort??'default'});
-    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(); }
-  prompt(text){this.callSpan?.measure({promptBodyChars:text.length,promptBodyBytes:Buffer.byteLength(text)});}
-  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();
-    this.callSpan?.end({status,usage:this.value.usage});
-  }
-}
-
-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 };
-}
+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.trace=metadata.trace;this.callSpan=metadata.callSpan;
+    this.callSpan?.measure({adapter:lane.adapter,providerID:lane.providerID,model:lane.model,effort:lane.variant??lane.effort??'default'});
+    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 CLI 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(); }
+  prompt(text){this.callSpan?.measure({promptBodyChars:text.length,promptBodyBytes:Buffer.byteLength(text)});}
+  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();
+    this.callSpan?.end({status,usage:this.value.usage});
+  }
+}
+
+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 };
+}