@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/oracle/routing.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/oracle/routing.mjs — deterministic gap → specialist routing table.
+ *
+ * Mirrors cx-oracle.md routing without LLM involvement. Issue raising,
+ * approve execution, and routing artifact generation consume these mappings.
+ */
+
+const GAP_ROUTES = {
+  'parity-drift': { primary: 'cx-platform-engineer', secondary: 'cx-docs-keeper' },
+  'contract-violations': { primary: 'cx-reviewer', secondary: 'cx-engineer' },
+  'doctor-escalation': { primary: 'cx-sre', secondary: 'cx-operations' },
+  'outcomes-degradation': { primary: 'cx-trace-reviewer', secondary: null },
+  'census-stale': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
+  'alignment-regression': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
+  'true-skill-orphan': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
+  'observations-empty': { primary: 'cx-explorer', secondary: 'cx-data-engineer' },
+  'beads-hygiene': { primary: 'cx-operations', secondary: null },
+  'hook-failures': { primary: 'cx-sre', secondary: null },
+  'registry-warn': { primary: 'cx-platform-engineer', secondary: null },
+  'consistency-drift': { primary: 'cx-platform-engineer', secondary: null },
+  'propagation-stale': { primary: 'cx-platform-engineer', secondary: 'cx-docs-keeper' },
+  'policy-coverage-gap': { primary: 'cx-architect', secondary: null },
+  'workflow-misaligned': { primary: 'cx-product-manager', secondary: null },
+  'legal-review-pending': { primary: 'cx-legal-compliance', secondary: null },
+  'capability-unvalidated': { primary: 'cx-platform-engineer', secondary: null },
+  'dead-code-regression': { primary: 'cx-architect', secondary: null },
+  'structure-sprawl': { primary: 'cx-architect', secondary: null },
+  'init-duplicate-lanes': { primary: 'cx-architect', secondary: null },
+  'outcomes-missing': { primary: 'cx-data-engineer', secondary: null },
+  'repo-layout-legacy': { primary: 'cx-platform-engineer', secondary: 'cx-architect' },
+  'specialist-audit-drift': { primary: 'cx-architect', secondary: 'cx-docs-keeper' },
+  'artifact-gate-bypass': { primary: 'cx-reviewer', secondary: 'cx-docs-keeper' },
+  'artifact-reviewer-gap': { primary: 'cx-reviewer', secondary: null },
+  'dependency-graph-stale': { primary: 'cx-platform-engineer', secondary: null },
+  'matrix-coverage-gap': { primary: 'cx-architect', secondary: 'cx-qa' },
+  'impact-untested': { primary: 'cx-qa', secondary: 'cx-engineer' },
+};
+
+const ACTION_ROUTES = {
+  'specialist-review': { primary: 'cx-reviewer', gateType: 'specialist-dispatch' },
+  'doctor-followup': { primary: 'cx-sre', gateType: 'operational-followup' },
+  'trace-review': { primary: 'cx-trace-reviewer', gateType: 'specialist-dispatch' },
+  'outcomes-aggregate': { primary: 'cx-data-engineer', gateType: 'maintenance' },
+  'executive-signoff-required': { primary: 'cx-product-manager', gateType: 'executive-gate' },
+  'structure-cleanup-proposal': { primary: 'cx-architect', gateType: 'human-approval' },
+  'graph-rebuild': { primary: 'cx-platform-engineer', gateType: 'maintenance' },
+};
+
+/**
+ * @param {{ id?: string, signal?: string }} gap
+ * @returns {{ primary: string, secondary: string|null, gateType?: string }}
+ */
+export function routeGap(gap) {
+  const id = gap?.id ?? gap?.signal ?? '';
+  const row = GAP_ROUTES[id];
+  if (row) return { ...row, gateType: signOffGateForGap(id) };
+  return { primary: 'cx-oracle', secondary: null, gateType: 'human-approval' };
+}
+
+/**
+ * @param {string} actionKind
+ */
+export function routeAction(actionKind) {
+  return ACTION_ROUTES[actionKind] ?? { primary: 'cx-oracle', gateType: 'human-approval' };
+}
+
+function signOffGateForGap(gapId) {
+  if (gapId === 'legal-review-pending') return 'legal-compliance';
+  if (gapId === 'workflow-misaligned') return 'executive-gate';
+  if (gapId === 'capability-unvalidated') return 'capability-human-gate';
+  if (gapId === 'structure-sprawl' || gapId === 'dead-code-regression') return 'human-approval';
+  return null;
+}
+
+/**
+ * Sign-off metadata attached to approve actions and high-severity gaps.
+ *
+ * @param {{ id: string, severity?: string }} gap
+ * @param {string} projectDir
+ */
+export function signOffMetadata(gap, projectDir) {
+  const route = routeGap(gap);
+  return {
+    gateType: route.gateType ?? 'human-approval',
+    requiredApprover: route.primary,
+    artifactPath: `.cx/oracle/verdicts/`,
+    projectDir,
+  };
+}

package/lib/oracle/synthesize.mjs

@@ -0,0 +1,384 @@
+/**
+ * lib/oracle/synthesize.mjs — derive verdicts, gaps, and recommended actions
+ * from the Oracle read model. Pure function — no side effects.
+ */
+
+import { orgGraphToGapHints } from './org-graph.mjs';
+import { routeAction, routeGap, signOffMetadata } from './routing.mjs';
+
+const LOW_SUCCESS_RATE = 0.6;
+
+function gap(id, severity, signal, detail, extra = {}) {
+  return { id, severity, signal, detail, ...extra };
+}
+
+function action(kind, summary, context = {}) {
+  return { kind, summary, ...context };
+}
+
+function isDoctorEscalation(entry) {
+  return entry.result === 'escalated'
+    || entry.kind === 'escalation'
+    || entry.kind === 'escalate';
+}
+
+/**
+ * @param {object} readModel — output of collectReadModel / enrichReadModel
+ * @returns {{ verdict: string, gaps: object[], recommendedActions: object[] }}
+ */
+export function synthesizeVerdict(readModel) {
+  const gaps = [];
+  const recommendedActions = [];
+
+  if (readModel.parity && !readModel.parity.skipped && !readModel.parity.ok) {
+    const drift = (readModel.parity.summary ?? []).filter((s) => s.includes('drift') || s.includes('stale'));
+    gaps.push(gap(
+      'parity-drift',
+      'high',
+      'parity',
+      drift.length ? drift.join('; ') : 'Project adapter parity check failed',
+    ));
+    recommendedActions.push(action(
+      'adapters-sync',
+      'Sync project adapters to repair parity drift',
+      { surfaces: (readModel.parity.surfaces ?? []).filter((s) => s.status !== 'ok').map((s) => s.surface) },
+    ));
+  }
+
+  const violations = readModel.contractViolations?.recentCount ?? 0;
+  if (violations > 0) {
+    gaps.push(gap(
+      'contract-violations',
+      violations >= 5 ? 'high' : 'medium',
+      'contract-violations',
+      `${violations} contract violation(s) in the last 24h`,
+    ));
+    recommendedActions.push(action(
+      'specialist-review',
+      'Review recent contract violations and route remediation to owning specialists',
+      { count: violations, signOff: signOffMetadata({ id: 'contract-violations' }, readModel.projectDir) },
+    ));
+  }
+
+  const doctorEscalations = (readModel.doctorLog?.recent ?? []).filter(isDoctorEscalation);
+  if (doctorEscalations.length > 0) {
+    gaps.push(gap(
+      'doctor-escalation',
+      'high',
+      'doctor-log',
+      `${doctorEscalations.length} doctor escalation(s) in the last 24h`,
+    ));
+    recommendedActions.push(action(
+      'doctor-followup',
+      'Inspect doctor escalations and confirm L0 recovery or open a beads issue',
+      { count: doctorEscalations.length, signOff: signOffMetadata({ id: 'doctor-escalation' }, readModel.projectDir) },
+    ));
+  }
+
+  const roles = readModel.outcomes?.roles ?? {};
+  const degradedRoles = Object.entries(roles)
+    .filter(([, stats]) => {
+      const rate = stats?.last30?.successRate ?? stats?.successRate;
+      return Number.isFinite(rate) && rate < LOW_SUCCESS_RATE && (stats?.last30?.count ?? stats?.count ?? 0) >= 3;
+    })
+    .map(([role]) => role);
+
+  if (degradedRoles.length > 0) {
+    gaps.push(gap(
+      'outcomes-degradation',
+      'medium',
+      'outcomes',
+      `Low 30-day success rate for: ${degradedRoles.join(', ')}`,
+    ));
+    recommendedActions.push(action(
+      'trace-review',
+      'Dispatch cx-trace-reviewer to inspect degraded specialist outcomes',
+      { roles: degradedRoles, signOff: signOffMetadata({ id: 'outcomes-degradation' }, readModel.projectDir) },
+    ));
+  }
+
+  if (!readModel.outcomes?.present) {
+    gaps.push(gap(
+      'outcomes-missing',
+      'low',
+      'outcomes',
+      'No .cx/outcomes/_summary.json — learning tiebreakers are blind',
+    ));
+    recommendedActions.push(action(
+      'outcomes-aggregate',
+      'Run outcomes aggregation to populate _summary.json',
+    ));
+  }
+
+  const census = readModel.alignmentCensus;
+  if (census?.present === false) {
+    gaps.push(gap(
+      'census-stale',
+      'low',
+      'alignment-census',
+      'No audit-artifacts/alignment-census.json — alignment scorecard may be stale',
+    ));
+    recommendedActions.push(action(
+      'census-run',
+      'Run alignment census to refresh scorecard inputs',
+    ));
+  } else if (census?.present) {
+    if (census.stale) {
+      gaps.push(gap(
+        'census-stale',
+        'medium',
+        'alignment-census',
+        `Alignment census older than 7 days (${census.generatedAt})`,
+      ));
+      recommendedActions.push(action('census-run', 'Refresh stale alignment census'));
+    }
+    const regressions = census.audit?.regressions ?? [];
+    if (regressions.length > 0) {
+      gaps.push(gap(
+        'alignment-regression',
+        'high',
+        'alignment-census',
+        `${regressions.length} alignment ratchet regression(s): ${regressions.slice(0, 3).join(', ')}`,
+      ));
+    }
+    const findingsCount = census.audit?.findingsCount ?? 0;
+    if (findingsCount > 0 && regressions.length === 0) {
+      gaps.push(gap(
+        'alignment-regression',
+        'medium',
+        'alignment-census',
+        `${findingsCount} open alignment audit finding(s)`,
+      ));
+    }
+    const trueOrphans = census.skills?.trueOrphanCount ?? 0;
+    if (trueOrphans > 0) {
+      gaps.push(gap(
+        'true-skill-orphan',
+        'medium',
+        'alignment-census',
+        `${trueOrphans} true skill orphan(s) in census`,
+      ));
+    }
+  }
+
+  if (readModel.observations?.present && readModel.observations.count === 0) {
+    gaps.push(gap(
+      'observations-empty',
+      'low',
+      'observations',
+      'Observation store exists but contains no records',
+    ));
+  }
+
+  if (readModel.registryValidate?.needsRun) {
+    recommendedActions.push(action(
+      'registry-validate',
+      'Validate capability registry against repo reality',
+      { warnings: readModel.registryValidate.warningCount, errors: readModel.registryValidate.errorCount },
+    ));
+  }
+
+  if ((readModel.registryValidate?.warningCount ?? 0) > 0) {
+    gaps.push(gap(
+      'registry-warn',
+      'medium',
+      'registry',
+      `${readModel.registryValidate.warningCount} capability registry warning(s)`,
+    ));
+  }
+
+  const hookFailures = readModel.hookFailures?.count ?? 0;
+  if (hookFailures > 0) {
+    gaps.push(gap(
+      'hook-failures',
+      'high',
+      'doctor-log',
+      `${hookFailures} hook failure(s) in the last 24h`,
+    ));
+  }
+
+  const stuck = readModel.beads?.stuckInProgress ?? 0;
+  const staleOpen = readModel.beads?.staleOpen ?? 0;
+  if (stuck > 0 || staleOpen > 2) {
+    gaps.push(gap(
+      'beads-hygiene',
+      stuck > 0 ? 'high' : 'medium',
+      'beads',
+      `Beads hygiene: ${stuck} stuck in_progress, ${staleOpen} stale-open`,
+    ));
+  }
+
+  const deadRegressions = readModel.deadCode?.regressions ?? [];
+  if (deadRegressions.length > 0) {
+    gaps.push(gap(
+      'dead-code-regression',
+      'high',
+      'dead-code',
+      `${deadRegressions.length} new dead module(s): ${deadRegressions.slice(0, 3).join(', ')}`,
+    ));
+    recommendedActions.push(action(
+      'structure-cleanup-proposal',
+      'Propose dead-code cleanup (no auto-delete)',
+      { modules: deadRegressions, signOff: signOffMetadata({ id: 'dead-code-regression' }, readModel.projectDir) },
+    ));
+  }
+
+  const dupLanes = readModel.structure?.duplicateLanes ?? [];
+  if (dupLanes.length > 0) {
+    gaps.push(gap(
+      'structure-sprawl',
+      'medium',
+      'structure',
+      `Parallel doc lanes detected: ${dupLanes.join(', ')}`,
+    ));
+    recommendedActions.push(action(
+      'structure-cleanup-proposal',
+      'Review duplicate doc lane scaffolding',
+      { lanes: dupLanes, signOff: signOffMetadata({ id: 'structure-sprawl' }, readModel.projectDir) },
+    ));
+  }
+
+  const rootLayout = readModel.alignmentCensus?.rootLayout;
+  if (rootLayout && rootLayout.clean === false) {
+    const parts = [];
+    if (rootLayout.legacyDirs?.length) parts.push(`legacy dirs: ${rootLayout.legacyDirs.join(', ')}`);
+    if (rootLayout.phantomPackPaths?.length) parts.push(`phantom pack: ${rootLayout.phantomPackPaths.join(', ')}`);
+    if (rootLayout.legacyImports?.length) parts.push(`${rootLayout.legacyImports.length} legacy import(s)`);
+    gaps.push(gap(
+      'repo-layout-legacy',
+      'high',
+      'root-layout',
+      `Tool-repo layout drift (${parts.join('; ') || `${rootLayout.findingCount} finding(s)`})`,
+    ));
+    recommendedActions.push(action(
+      'structure-cleanup-proposal',
+      'Remediate legacy root layout per audit phase 03c-root-layout',
+      { rootLayout, signOff: signOffMetadata({ id: 'repo-layout-legacy' }, readModel.projectDir) },
+    ));
+  }
+
+  const artifactGate = readModel.artifactGate ?? {};
+  if (artifactGate.specialistAudit?.present && !artifactGate.specialistAudit.pass) {
+    gaps.push(gap(
+      'specialist-audit-drift',
+      'high',
+      'artifact-manifest',
+      `Specialist audit cross-check failed (${artifactGate.specialistAudit.crossCheckCount} issue(s))`,
+    ));
+    recommendedActions.push(action(
+      'registry-validate',
+      'Run construct audit specialists and repair manifest/registry drift',
+    ));
+  }
+
+  if ((artifactGate.bypassCount ?? 0) > 0) {
+    gaps.push(gap(
+      'artifact-gate-bypass',
+      'medium',
+      'artifact-manifest',
+      `${artifactGate.bypassCount} artifact(s) bypass release gate via cx_release_gate frontmatter`,
+    ));
+    recommendedActions.push(action(
+      'specialist-review',
+      'Review bypassed artifacts and confirm cx_release_gate_reason is durable',
+      { paths: (artifactGate.bypassed ?? []).map((b) => b.path).slice(0, 5) },
+    ));
+  }
+
+  if ((artifactGate.reviewerGapCount ?? 0) > 0) {
+    gaps.push(gap(
+      'artifact-reviewer-gap',
+      'medium',
+      'artifact-manifest',
+      `${artifactGate.reviewerGapCount} high-risk artifact(s) missing manifest required reviewers in agent log`,
+    ));
+  }
+
+  const dg = readModel.dependencyGraph;
+  if (dg?.present) {
+    if (dg.stale) {
+      gaps.push(gap(
+        'dependency-graph-stale',
+        'low',
+        'dependency-graph',
+        `Dependency matrix stale (${dg.staleReason ?? 'seeds changed'}) — run \`construct matrix build\``,
+      ));
+      recommendedActions.push(action('graph-rebuild', 'Rebuild the dependency matrix to clear staleness'));
+    }
+
+    const cov = dg.coverage ?? {};
+    const noTest = cov.capabilitiesWithoutTest ?? [];
+    const noImpl = cov.capabilitiesWithoutImpl ?? [];
+    const uncovered = cov.workflowsUncovered ?? [];
+    const coverageMisses = noTest.length + noImpl.length + uncovered.length;
+    if (coverageMisses > 0) {
+      const parts = [];
+      if (noTest.length) parts.push(`${noTest.length} capability(ies) with no validating test`);
+      if (noImpl.length) parts.push(`${noImpl.length} with no implementation edge`);
+      if (uncovered.length) parts.push(`${uncovered.length} workflow(s) with no capability`);
+      gaps.push(gap(
+        'matrix-coverage-gap',
+        coverageMisses >= 5 ? 'medium' : 'low',
+        'dependency-graph',
+        `Dependency matrix coverage: ${parts.join('; ')}`,
+      ));
+    }
+
+    if (dg.untested?.length) {
+      gaps.push(gap(
+        'impact-untested',
+        dg.untested.length >= 5 ? 'high' : 'medium',
+        'dependency-graph',
+        `${dg.untested.length} capability(ies) have implementation changes since last validation: ${dg.untested.slice(0, 5).map((u) => u.capability).join(', ')}`,
+        { signOff: signOffMetadata({ id: 'impact-untested' }, readModel.projectDir) },
+      ));
+      recommendedActions.push(action(
+        'specialist-review',
+        'Re-run affected tests and refresh lastValidated for capabilities with changed implementation',
+        { capabilities: dg.untested.map((u) => u.capability) },
+      ));
+    }
+  }
+
+  for (const hint of orgGraphToGapHints(readModel.orgGraph ?? {})) {
+    if (!gaps.some((g) => g.id === hint.id)) gaps.push(hint);
+    if (hint.id === 'workflow-misaligned') {
+      recommendedActions.push(action(
+        'executive-signoff-required',
+        'Workflow alignment requires executive gate review',
+        { signOff: signOffMetadata(hint, readModel.projectDir) },
+      ));
+    }
+    if (hint.id === 'legal-review-pending') {
+      recommendedActions.push(action(
+        'specialist-review',
+        'Route legal-compliance intake for sign-off',
+        { signOff: signOffMetadata(hint, readModel.projectDir) },
+      ));
+    }
+  }
+
+  for (const g of gaps) {
+    const route = routeGap(g);
+    g.remediationRoute = {
+      primary: route.primary,
+      secondary: route.secondary ?? null,
+      gateType: route.gateType ?? null,
+    };
+  }
+  for (const a of recommendedActions) {
+    const route = routeAction(a.kind);
+    a.remediationRoute = {
+      primary: route.primary,
+      gateType: route.gateType ?? null,
+    };
+  }
+
+  let verdict = 'healthy';
+  if (gaps.some((g) => g.severity === 'high')) verdict = 'degraded';
+  else if (gaps.length > 0) verdict = 'attention';
+
+  return { verdict, gaps, recommendedActions };
+}
+
+export { isDoctorEscalation };

package/lib/oracle/verdicts.mjs

@@ -0,0 +1,51 @@
+/**
+ * lib/oracle/verdicts.mjs — durable per-tick verdict history under
+ * <project>/.cx/oracle/verdicts/.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function verdictsDir(projectDir) {
+  return path.join(projectDir, '.cx', 'oracle', 'verdicts');
+}
+
+function dateKey(iso = new Date().toISOString()) {
+  return iso.slice(0, 10);
+}
+
+/**
+ * Write one tick verdict. Same calendar day overwrites the latest snapshot for
+ * that date (last tick wins) while preserving tick history in an array.
+ *
+ * @param {string} projectDir
+ * @param {object} tick — runOracleTick tick payload
+ * @param {object} [extra] — beadsRaised, orgGraph, etc.
+ */
+export function writeVerdict(projectDir, tick, extra = {}) {
+  const dir = verdictsDir(projectDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${dateKey(tick.at)}.json`);
+  let existing = { date: dateKey(tick.at), ticks: [] };
+  if (fs.existsSync(file)) {
+    try { existing = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* reset */ }
+  }
+  if (!Array.isArray(existing.ticks)) existing.ticks = [];
+  existing.ticks.push({ ...tick, ...extra });
+  existing.latest = existing.ticks[existing.ticks.length - 1];
+  fs.writeFileSync(file, JSON.stringify(existing, null, 2));
+  return file;
+}
+
+export function readLatestVerdict(projectDir) {
+  const dir = verdictsDir(projectDir);
+  if (!fs.existsSync(dir)) return null;
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+  if (!files.length) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(dir, files[files.length - 1]), 'utf8'));
+    return data.latest ?? data;
+  } catch {
+    return null;
+  }
+}

package/lib/orchestration/worker.mjs

@@ -23,8 +23,8 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { resolveSecret } from '../providers/secret-resolver.mjs';
 
 export const INLINE = 'inline';
 export const PROVIDER = 'provider';
@@ -52,6 +52,33 @@ function isAnthropic(provider, model) {
   return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
 }
 
+// Provider family for execution dispatch. The explicit `provider` argument is
+// authoritative — orchestration model ids are OpenRouter-style slugs (for
+// example `openai/gpt-4o-mini` is a model served *through* OpenRouter), so the
+// direct OpenAI endpoint is taken only when the caller names `openai`. Copilot
+// is resolved separately because it authenticates via the device-flow token
+// store rather than an API key; everything unrecognized stays on OpenRouter.
+
+function classifyWorkerProvider(provider, model) {
+  const p = (provider || '').toLowerCase();
+  if (p === 'github-copilot' || /^github-copilot\//.test(model || '')) return 'github-copilot';
+  if (p === 'openai') return 'openai';
+  if (isAnthropic(provider, model)) return 'anthropic';
+  return 'openrouter';
+}
+
+const WORKER_KEY_VAR = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+};
+
+const WORKER_PROVIDER_LABEL = {
+  anthropic: 'Anthropic',
+  openai: 'OpenAI',
+  openrouter: 'OpenRouter',
+};
+
 // Extended-thinking shape is model-specific. Opus 4.8 / 4.7 REJECT the legacy
 // `{type:'enabled', budget_tokens}` form with a 400 and require adaptive
 // thinking; Opus 4.6 and Sonnet 4.6 recommend adaptive too. Only genuinely
@@ -66,23 +93,14 @@ function anthropicThinkingConfig(model) {
     : { type: 'enabled', budget_tokens: REASONING_BUDGET_TOKENS };
 }
 
-// Key resolution mirrors provider-extract: env first, then the two cheap dotenv
-// files, and only when the caller did not inject an explicit env. A caller that
-// passes its own env object (embedded callers, tests) is authoritative and
-// hermetic — ambient discovery is suppressed so a developer's real key never
-// bleeds into a test run.
+// Key resolution delegates to the shared secret resolver so env, the dotenv
+// files, shell rc exports, and 1Password op:// references all behave identically
+// across the worker, the chat engine, and the router. allowAmbient stays the
+// hermetic switch: a caller that injects its own env (embedded callers, tests)
+// suppresses file/rc discovery so a developer's real key never bleeds into a run.
 
 function resolveKey(varName, env, allowAmbient) {
-  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
-  if (!allowAmbient) return null;
-  for (const file of [join(homedir(), '.construct', 'config.env'), join(homedir(), '.env')]) {
-    try {
-      if (!existsSync(file)) continue;
-      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
-      if (m && m[1]) return m[1].trim();
-    } catch { /* unreadable dotenv is not authoritative */ }
-  }
-  return null;
+  return resolveSecret(varName, { env, allowAmbient });
 }
 
 // The persona prompt is the specialist's system context. It lives in
@@ -171,6 +189,42 @@ async function callOpenRouter({ model, apiKey, system, user, fetchImpl, reasonin
   return { output: message.content || '', reasoning: reasoning ? extractOpenRouterReasoning(message) : '' };
 }
 
+async function callCopilot({ model, system, user, fetchImpl }) {
+  const { getCopilotToken, copilotApiHeaders, COPILOT_API_BASE } = await import('../providers/copilot-auth.mjs');
+  const token = await getCopilotToken({ fetchImpl });
+  const res = await fetchImpl(`${COPILOT_API_BASE}/chat/completions`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'content-type': 'application/json', ...copilotApiHeaders() },
+    body: JSON.stringify({
+      model: model.replace(/^github-copilot\//, ''),
+      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `GitHub Copilot specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Run `construct creds login copilot`, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  const message = data.choices?.[0]?.message || {};
+  return { output: message.content || '', reasoning: '' };
+}
+
+async function callOpenAI({ model, apiKey, system, user, fetchImpl }) {
+  const res = await fetchImpl('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: model.replace(/^openai\//, ''),
+      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenAI specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENAI_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  const message = data.choices?.[0]?.message || {};
+  return { output: message.content || '', reasoning: '' };
+}
+
 /**
  * Execute one specialist task via the configured provider/model.
  *
@@ -190,26 +244,33 @@ export async function runTaskViaProvider({ task, run, model, provider = null, en
   if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
   if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
 
-  const anthropic = isAnthropic(provider, model);
-  const keyVar = anthropic ? 'ANTHROPIC_API_KEY' : 'OPENROUTER_API_KEY';
-  const apiKey = resolveKey(keyVar, env, env === process.env);
-  if (!apiKey) {
-    throw providerError('PROVIDER_KEY_MISSING', `No API key for ${anthropic ? 'Anthropic' : 'OpenRouter'} specialist execution.`, `Set ${keyVar}, or set orchestration.workerBackend to "inline".`);
-  }
-
+  const family = classifyWorkerProvider(provider, model);
   const system = loadPersona(task?.role);
   const user = buildUserPrompt({ task, run });
   const wantsReasoning = chainOfThought !== 'hidden';
-  const { output, reasoning } = anthropic
-    ? await callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning })
-    : await callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning });
+
+  let output;
+  let reasoning;
+  if (family === 'github-copilot') {
+    ({ output, reasoning } = await callCopilot({ model, system, user, fetchImpl }));
+  } else {
+    const keyVar = WORKER_KEY_VAR[family];
+    const apiKey = resolveKey(keyVar, env, env === process.env);
+    if (!apiKey) {
+      throw providerError('PROVIDER_KEY_MISSING', `No API key for ${WORKER_PROVIDER_LABEL[family]} specialist execution.`, `Set ${keyVar} (a value or an op:// reference), or set orchestration.workerBackend to "inline".`);
+    }
+    const call = family === 'anthropic' ? callAnthropic
+      : family === 'openai' ? callOpenAI
+        : callOpenRouter;
+    ({ output, reasoning } = await call({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning }));
+  }
 
   const text = output || '';
   return {
     output: text,
     reasoning: wantsReasoning ? (reasoning || '') : '',
     model,
-    provider: anthropic ? 'anthropic' : 'openrouter',
+    provider: family,
     characters: text.length,
   };
 }