@geraldmaron/construct 1.3.1 → 1.4.0

package/lib/mcp-platform-config.mjs

@@ -28,9 +28,18 @@ function resolveTemplateObject(input, resolvedValues, fallback) {
   );
 }
 
+// A value is unsafe to write into a host MCP env block when it is an unresolved
+// `__NAME__` template or a 1Password `op://` reference. The op:// form must never
+// be written verbatim: a host that cannot run `op read` would pass the literal
+// reference to the child process, and writing it persists secret topology on disk.
+
+function isUnwritableEnvValue(value) {
+  return typeof value !== "string" || value.includes("__") || value.startsWith("op://");
+}
+
 function stripUnresolvedValues(input) {
   return Object.fromEntries(
-    Object.entries(input).filter(([, value]) => typeof value === "string" && !value.includes("__")),
+    Object.entries(input).filter(([, value]) => !isUnwritableEnvValue(value)),
   );
 }
 
@@ -40,14 +49,32 @@ function resolveArgs(args, resolvedValues) {
   );
 }
 
+// Remote MCP header values carry secrets (e.g. `Authorization: Bearer __GITHUB_TOKEN__`).
+// Emit a host-resolved env reference rather than the literal token value, so a live
+// credential never lands in a config file on disk. Each host expands a different
+// reference syntax; the secret stays in one place (config.env / the shell env) and the
+// host resolves it at launch.
+
+const SECRET_REF = {
+  claude: (name) => `\${${name}}`,
+  vscode: (name) => `\${env:${name}}`,
+  opencode: (name) => `{env:${name}}`,
+};
+
+// Local/stdio MCP env is materialized as resolved values rather than host env-ref
+// forms. The SECRET_REF syntaxes above are verified for the remote `headers` field
+// only; whether Claude / VS Code / OpenCode expand a `${VAR}`-style reference inside
+// a stdio `env` block is unconfirmed, so the value-to-reference flip is deferred. The
+// secret is still kept off disk by the child inheriting resolved env from the parent
+// (config.env -> loadConstructEnv -> process.env); `stripUnresolvedValues` guarantees
+// no unresolved template or op:// reference is persisted here.
+
 function buildLocalEnvironment(mcpDef, resolvedValues) {
   return stripUnresolvedValues(resolveTemplateObject(mcpDef.env ?? {}, resolvedValues));
 }
 
-function buildRemoteHeaders(mcpDef, resolvedValues) {
-  return stripUnresolvedValues(
-    resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues, (name) => `{env:${name}}`),
-  );
+function buildRemoteHeaders(mcpDef, secretRef) {
+  return resolveTemplateObject(mcpDef.headers ?? {}, {}, secretRef);
 }
 
 function withMemoryDefaults(id, values) {
@@ -56,11 +83,18 @@ function withMemoryDefaults(id, values) {
   return { ...values, MEMORY_PORT: "8765" };
 }
 
-export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
+// auth defaults to "oauth": remote MCP servers (e.g. GitHub's hosted server) are
+// configured by URL only, and the host runs the browser OAuth flow and stores the
+// token in its own secure store — nothing secret touches the config file. "pat"
+// is the opt-in fallback for non-OAuth contexts (headless/CI), emitting an env
+// reference for the credential, never the literal value.
+
+export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}, { host = "claude", auth = "oauth" } = {}) {
   const values = withMemoryDefaults(id, { CX_TOOLKIT_DIR: ROOT_DIR, ...resolvedValues });
+  const secretRef = SECRET_REF[host] ?? SECRET_REF.claude;
 
   if (mcpDef.type === "url") {
-    const headers = buildRemoteHeaders(mcpDef, values);
+    const headers = auth === "pat" ? buildRemoteHeaders(mcpDef, secretRef) : {};
     const url =
       id === "memory" && values.MEMORY_PORT
         ? `http://127.0.0.1:${values.MEMORY_PORT}/`
@@ -80,7 +114,7 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
   };
 }
 
-export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
+export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}, { auth = "oauth" } = {}) {
   const runtimeValues = withMemoryDefaults(id, {
     CX_TOOLKIT_DIR: ROOT_DIR,
     ...resolvedValues,
@@ -92,12 +126,13 @@ export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
       id === "memory" && runtimeValues.MEMORY_PORT
         ? `http://127.0.0.1:${runtimeValues.MEMORY_PORT}/`
         : resolveTemplateString(mcpDef.url, runtimeValues);
+    const headers = auth === "pat" ? buildRemoteHeaders(mcpDef, SECRET_REF.opencode) : {};
     return {
       id: openCodeId,
       entry: {
         type: "remote",
         url,
-        ...(Object.keys(buildRemoteHeaders(mcpDef, runtimeValues)).length > 0 ? { headers: buildRemoteHeaders(mcpDef, runtimeValues) } : {}),
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
       },
     };
   }

package/lib/models/provider-poll.mjs

@@ -8,7 +8,10 @@
  * fails) fall back to the curated tier options, flagged source:'curated' so the
  * UI never implies a live result it could not verify. Every poller is
  * best-effort: it resolves to [] on any error and never throws, and results are
- * cached to ~/.cx/provider-catalog-cache.json so repeat opens are instant.
+ * cached to ~/.cx/provider-catalog-cache.json so repeat opens are instant. When a
+ * fresh catalog (within CACHE_TTL_MS) already covers every configured provider it
+ * is served directly without polling, so opening the picker on a warm cache
+ * resolves no secret and triggers no 1Password prompt.
  */
 
 import fs from 'node:fs';
@@ -306,6 +309,14 @@ async function enrichPricing(models, { env }) {
   });
 }
 
+function sortProviderGroups(groups) {
+  return groups.sort((a, b) => {
+    const ai = PROVIDER_ORDER.indexOf(a.id);
+    const bi = PROVIDER_ORDER.indexOf(b.id);
+    return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi) || a.label.localeCompare(b.label);
+  });
+}
+
 /**
  * Poll every configured provider in parallel and return one group per provider,
  * in render order, each with its live model list. A provider that can't be
@@ -327,6 +338,25 @@ export async function pollConfiguredProviders({ env = process.env, cwd = process
     }
   }
 
+  // Cache-first: when a fresh catalog (within TTL) already covers every configured
+  // provider, serve it without resolving any secret. Opening the picker on a warm
+  // cache must not spawn `op read` or trigger a 1Password prompt.
+  const freshCached = readProviderCatalogCache({ homeDir, maxAgeMs: CACHE_TTL_MS }) || [];
+  const freshById = new Map(freshCached.map((g) => [g.id, g]));
+  if (groupIds.length && groupIds.every((gid) => freshById.get(gid)?.models?.length)) {
+    const fresh = groupIds.map((gid) => {
+      const group = groupForId.get(gid);
+      const cachedGroup = freshById.get(gid);
+      return {
+        id: gid,
+        label: group.label,
+        models: cachedGroup.models.map((m) => ({ ...m, source: 'cached' })),
+        live: false,
+      };
+    });
+    return sortProviderGroups(fresh);
+  }
+
   const cached = readProviderCatalogCache({ homeDir, maxAgeMs: Infinity }) || [];
   const cachedById = new Map(cached.map((g) => [g.id, g]));
 
@@ -367,11 +397,7 @@ export async function pollConfiguredProviders({ env = process.env, cwd = process
     groups.push({ id: gid, label: group.label, models: [unreachableHint(gid, group.label)], live: false });
   }
 
-  groups.sort((a, b) => {
-    const ai = PROVIDER_ORDER.indexOf(a.id);
-    const bi = PROVIDER_ORDER.indexOf(b.id);
-    return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi) || a.label.localeCompare(b.label);
-  });
+  sortProviderGroups(groups);
 
   if (liveGroupsToCache.length) writeProviderCatalogCache(liveGroupsToCache, { homeDir });
 

package/lib/orchestration/readiness.mjs

@@ -0,0 +1,183 @@
+/**
+ * lib/orchestration/readiness.mjs — observed orchestration attachment readiness.
+ *
+ * Deliberately separate from embedded-contract/execution.mjs: execution resolve
+ * reports what Construct can plan; readiness reports what a host/session or
+ * local probe actually exposed.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getInstalledVersion } from '../version.mjs';
+import { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION } from '../embedded-contract/contract-version.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
+
+export const ORCHESTRATION_READINESS_REASONS = Object.freeze([
+  'attached',
+  'host_not_attached',
+  'server_unreachable',
+  'auth_unavailable',
+  'profile_mismatch',
+  'capability_negotiation_failed',
+  'version_mismatch',
+  'tool_unlisted',
+  'unknown',
+]);
+
+export const DEFAULT_ORCHESTRATION_TOOLS = Object.freeze([
+  'orchestration_policy',
+  'orchestration_run',
+]);
+
+const NEXT_STEPS = Object.freeze({
+  attached: 'Proceed: call orchestration_policy, then orchestration_run when policy indicates an orchestrated or focused run.',
+  host_not_attached: 'Refresh the host adapter with `construct sync`, restart the host session, then rerun `construct orchestrate preflight --json` inside the target project.',
+  server_unreachable: 'Run `construct doctor`, verify the generated MCP command points at this checkout, then rerun `construct sync` if the server path is stale.',
+  auth_unavailable: 'Configure the required Construct/provider credential, restart the host so its MCP process inherits it, then rerun preflight.',
+  profile_mismatch: 'Check the active Construct scope/profile and host adapter selection, then rerun `construct sync` from the project root.',
+  capability_negotiation_failed: 'Restart the host session so MCP initialize/tools.list negotiation runs again; if it persists, attach the diagnostic bundle to GH #323.',
+  version_mismatch: 'Upgrade Construct and refresh adapters with `construct sync` so the host and server use compatible contract versions.',
+  tool_unlisted: 'Refresh adapters with `construct sync`; if using a reduced local tool surface, ensure orchestration_run is reachable through the `call` gateway enum.',
+  unknown: 'Run `construct doctor` and attach the diagnostic bundle to GH #323.',
+});
+
+function normalizeList(values) {
+  if (!values) return [];
+  const arr = Array.isArray(values) ? values : String(values).split(',');
+  return [...new Set(arr.map((v) => String(v || '').trim()).filter(Boolean))].sort();
+}
+
+function compareSemver(a, b) {
+  const pa = String(a || '').split('.').map((n) => Number(n));
+  const pb = String(b || '').split('.').map((n) => Number(n));
+  for (let i = 0; i < 3; i += 1) {
+    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (av > bv) return 1;
+    if (av < bv) return -1;
+  }
+  return 0;
+}
+
+function hasTool(tool, observed, reachable) {
+  return observed.includes(tool) || reachable.includes(tool);
+}
+
+function redactedEnvFacts(env) {
+  return {
+    hasRemoteOrchestrationUrl: Boolean(env.CONSTRUCT_ORCHESTRATION_URL),
+    hasRemoteOrchestrationToken: Boolean(env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN),
+    hasOpenRouterKey: Boolean(env.OPENROUTER_API_KEY),
+    hasAnthropicKey: Boolean(env.ANTHROPIC_API_KEY),
+    hasOpenAiKey: Boolean(env.OPENAI_API_KEY),
+  };
+}
+
+export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const requiredTools = normalizeList(input.requiredTools ?? input.required_tools ?? DEFAULT_ORCHESTRATION_TOOLS);
+  const observedTools = normalizeList(input.observedTools ?? input.observed_tools);
+  const reachableTools = normalizeList(input.reachableTools ?? input.reachable_tools);
+  const host = input.host ?? null;
+  const sessionId = input.sessionId ?? input.session_id ?? null;
+  const observationScope = input.observationScope ?? input.observation_scope ?? (observedTools.length || reachableTools.length ? 'host-session' : 'local-config');
+  const probeError = input.probeError ?? input.probe_error ?? null;
+  const clientContractVersion = input.clientContractVersion ?? input.client_contract_version ?? CONTRACT_VERSION;
+  const profileExpected = input.expectedProfile ?? input.expected_profile ?? null;
+  const profileActual = input.actualProfile ?? input.actual_profile ?? null;
+  const authRequired = Boolean(input.authRequired ?? input.auth_required);
+
+  const missingTools = requiredTools.filter((tool) => !hasTool(tool, observedTools, reachableTools));
+  const constructVersion = getInstalledVersion()?.version || 'unknown';
+  const diagnosticId = input.diagnosticId ?? input.diagnostic_id ?? `orch-${randomUUID()}`;
+
+  let reasonCode = 'attached';
+  let detail = 'Required orchestration tools are reachable.';
+
+  if (probeError) {
+    reasonCode = 'server_unreachable';
+    detail = String(probeError);
+  } else if (compareSemver(clientContractVersion, MIN_CLIENT_CONTRACT_VERSION) < 0) {
+    reasonCode = 'version_mismatch';
+    detail = `Client contract ${clientContractVersion} is older than minimum ${MIN_CLIENT_CONTRACT_VERSION}.`;
+  } else if (profileExpected && profileActual && profileExpected !== profileActual) {
+    reasonCode = 'profile_mismatch';
+    detail = `Expected profile ${profileExpected}, observed ${profileActual}.`;
+  } else if (authRequired && !(env.CONSTRUCT_ORCHESTRATION_TOKEN || env.CONSTRUCT_DASHBOARD_TOKEN)) {
+    reasonCode = 'auth_unavailable';
+    detail = 'A remote/team orchestration token is required but not configured.';
+  } else if (observationScope === 'host-session' && observedTools.length === 0 && reachableTools.length === 0) {
+    reasonCode = 'host_not_attached';
+    detail = 'No observed MCP tools were provided for the active host session.';
+  } else if (missingTools.length > 0) {
+    reasonCode = 'tool_unlisted';
+    detail = `Missing required tool(s): ${missingTools.join(', ')}.`;
+  }
+
+  const verdict = reasonCode === 'attached' ? 'pass' : 'fail';
+  const bundle = {
+    diagnosticId,
+    host,
+    sessionId,
+    cwd,
+    observationScope,
+    constructVersion,
+    contractVersion: CONTRACT_VERSION,
+    minClientContractVersion: MIN_CLIENT_CONTRACT_VERSION,
+    clientContractVersion,
+    deploymentMode: getDeploymentMode(env, { cwd }),
+    requiredTools,
+    observedTools,
+    reachableTools,
+    missingTools,
+    reasonCode,
+    detail,
+    env: redactedEnvFacts(env),
+  };
+
+  return {
+    verdict,
+    attached: verdict === 'pass',
+    reasonCode,
+    nextStep: NEXT_STEPS[reasonCode] || NEXT_STEPS.unknown,
+    host,
+    sessionId,
+    observationScope,
+    requiredTools,
+    observedTools,
+    reachableTools,
+    missingTools,
+    constructVersion,
+    contractVersion: CONTRACT_VERSION,
+    minClientContractVersion: MIN_CLIENT_CONTRACT_VERSION,
+    diagnosticBundle: bundle,
+  };
+}
+
+export function summarizeOrchestrationReadiness(readiness) {
+  const state = readiness.attached ? 'Orchestration attached' : 'Orchestration unavailable';
+  const missing = readiness.missingTools?.length ? ` missing=${readiness.missingTools.join(',')}` : '';
+  const host = readiness.host ? ` host=${readiness.host}` : '';
+  return `${state} (${readiness.reasonCode}; scope=${readiness.observationScope}${host}${missing})`;
+}
+
+export function recordOrchestrationReadinessEvent(readiness, { homeDir, at = new Date().toISOString() } = {}) {
+  const event = {
+    ts: at,
+    type: 'orchestration.readiness',
+    host: readiness.host ?? null,
+    sessionId: readiness.sessionId ?? null,
+    observationScope: readiness.observationScope,
+    verdict: readiness.verdict,
+    attached: readiness.attached,
+    reasonCode: readiness.reasonCode,
+    requiredTools: readiness.requiredTools ?? [],
+    missingTools: readiness.missingTools ?? [],
+    diagnosticId: readiness.diagnosticBundle?.diagnosticId ?? null,
+  };
+  const file = join(doctorRoot(homeDir), 'orchestration-readiness.jsonl');
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, `${JSON.stringify(event)}\n`);
+  return { path: file, event };
+}

package/lib/output-quality.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/output-quality.mjs — Post-export output validation for the publish path.
+ *
+ * After an artifact exports, this runs the checks the source-level release gate cannot reach: the
+ * produced file is validated for real (PDF page count, exported-text roundtrip against the source
+ * headings, on-disk reference integrity), and the brand text palette is asserted against WCAG AA.
+ * At render-smoke or higher gate levels the export is additionally rendered to images and the
+ * screenshot evidence recorded. Every check degrades with a typed reason when its tool is absent
+ * rather than failing the publish; only a real, document-scoped validity failure (a zero-page PDF,
+ * dropped content, a missing local reference) marks the result not-ok.
+ */
+
+import { validatePdf, contentRoundtrip, referenceIntegrity } from './export-validate.mjs';
+import { validateBrandContrast } from './brand-contrast.mjs';
+import { captureRenderEvidence } from './render-evidence.mjs';
+import { lintDocumentDiagrams } from './diagram-quality.mjs';
+import { auditAccessibility } from './a11y-audit.mjs';
+
+const RENDER_GATE_LEVELS = new Set(['render-smoke', 'full-certification', 'human-reviewed']);
+
+// render-pipeline keys an export format to an image renderer; deck is HTML under the hood. A
+// format with no renderer skips the screenshot capture rather than guessing one.
+
+function renderFormatFor(format) {
+  if (format === 'pdf') return 'pdf';
+  if (format === 'html' || format === 'deck') return 'html';
+  if (format === 'pptx') return 'pptx';
+  return null;
+}
+
+export function runOutputQuality({
+  exportPath,
+  format,
+  sourceMarkdown = '',
+  baseDir = null,
+  gateLevel = 'standard',
+  diagramStrict = false,
+  rootDir = process.cwd(),
+  env = process.env,
+} = {}) {
+  const checks = {};
+
+  if (format === 'pdf') checks.pdf = validatePdf(exportPath, env);
+  checks.roundtrip = contentRoundtrip({ exportPath, format, sourceMarkdown, env });
+  if (sourceMarkdown && baseDir) checks.references = referenceIntegrity(sourceMarkdown, baseDir);
+
+  // Diagram legibility is advisory by default; `cx_diagram_quality: strict` escalates it.
+  const diagrams = lintDocumentDiagrams(sourceMarkdown);
+
+  // Per-format accessibility, with an honest checked-vs-uncheckable coverage report.
+  const a11y = auditAccessibility({ format, exportPath, sourceMarkdown, env });
+
+  // Palette contrast is a brand-system invariant, not a property of this document, so a
+  // regression is surfaced as advisory rather than failing the user's publish.
+
+  const contrast = validateBrandContrast();
+
+  let render = null;
+  if (RENDER_GATE_LEVELS.has(gateLevel)) {
+    const renderFormat = renderFormatFor(format);
+    if (renderFormat) render = captureRenderEvidence({ format: renderFormat, inputPath: exportPath, rootDir, env });
+  }
+
+  // A typed degradation (tool absent) never fails the publish; only a non-degraded,
+  // document-scoped check whose ok is explicitly false does.
+
+  const failures = Object.entries(checks)
+    .filter(([, result]) => result && result.ok === false && !result.degradation)
+    .map(([name, result]) => `${name}: ${result.message || 'failed'}`);
+
+  if (diagramStrict && !diagrams.ok) {
+    for (const w of diagrams.warnings) failures.push(`diagram ${w.diagram} (${w.kind}): ${w.code}`);
+  }
+
+  // Accessibility is advisory at standard levels and escalates at full-certification and above;
+  // rendered-format limits stay in the uncheckable list, never a false pass.
+  const a11yStrict = gateLevel === 'full-certification' || gateLevel === 'human-reviewed';
+  if (a11yStrict) for (const f of a11y.failures || []) failures.push(`a11y ${f}`);
+
+  return {
+    ok: failures.length === 0,
+    gateLevel,
+    checks,
+    contrast: { ok: contrast.ok, failures: contrast.failures },
+    diagrams,
+    a11y,
+    render,
+    failures,
+  };
+}

package/lib/pixel-regression.mjs

@@ -0,0 +1,172 @@
+/**
+ * lib/pixel-regression.mjs — true pixel-level regression, gated to full-certification.
+ *
+ * Compares two PNGs by decoding them to raw pixels and counting pixels whose channels differ
+ * beyond a tolerance — not by comparing compressed file bytes, which are meaningless across
+ * encoders (PNG is DEFLATE-compressed, so two pixel-identical images can differ byte-for-byte).
+ * Decoding uses node:zlib only, honoring the zero-npm-core constraint (ADR-0001); 8-bit
+ * non-interlaced PNGs in the grayscale/RGB/GA/RGBA color types are supported and anything else
+ * returns a typed `unsupported-encoding` rather than a false pass.
+ *
+ * Fixture-regeneration policy: a golden is updated only through regenerateGolden (single writer),
+ * never edited in place. Pixel regression runs only at the full-certification gate level so its
+ * decode-and-compare cost (O(pixels), a few milliseconds per image) never burdens cheaper gates.
+ */
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+export const PIXEL_REGRESSION_LEVEL = 'full-certification';
+
+const CHANNELS_BY_COLOR_TYPE = Object.freeze({ 0: 1, 2: 3, 4: 2, 6: 4 });
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+// Walk the PNG chunk stream for IHDR geometry and the concatenated IDAT payload, then inflate and
+// reverse the per-scanline filter to recover raw pixels. CRCs are skipped; only the decode matters.
+
+function decodePng(buffer) {
+  if (buffer.length < 8 || buffer[0] !== 0x89 || buffer[1] !== 0x50) return { error: 'invalid-png' };
+  let pos = 8;
+  let header = null;
+  const idat = [];
+  while (pos + 8 <= buffer.length) {
+    const length = buffer.readUInt32BE(pos);
+    const type = buffer.toString('ascii', pos + 4, pos + 8);
+    const dataStart = pos + 8;
+    if (type === 'IHDR') {
+      header = {
+        width: buffer.readUInt32BE(dataStart),
+        height: buffer.readUInt32BE(dataStart + 4),
+        bitDepth: buffer[dataStart + 8],
+        colorType: buffer[dataStart + 9],
+        interlace: buffer[dataStart + 12],
+      };
+    } else if (type === 'IDAT') {
+      idat.push(buffer.subarray(dataStart, dataStart + length));
+    } else if (type === 'IEND') {
+      break;
+    }
+    pos = dataStart + length + 4;
+  }
+  if (!header) return { error: 'invalid-png' };
+  const channels = CHANNELS_BY_COLOR_TYPE[header.colorType];
+  if (header.bitDepth !== 8 || header.interlace !== 0 || !channels) return { error: 'unsupported-encoding' };
+
+  let raw;
+  try {
+    raw = zlib.inflateSync(Buffer.concat(idat));
+  } catch {
+    return { error: 'invalid-png' };
+  }
+
+  const { width, height } = header;
+  const stride = width * channels;
+  if (raw.length < height * (stride + 1)) return { error: 'invalid-png' };
+
+  const pixels = Buffer.alloc(height * stride);
+  let prior = Buffer.alloc(stride);
+  let rpos = 0;
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[rpos];
+    rpos += 1;
+    const recon = pixels.subarray(y * stride, y * stride + stride);
+    for (let x = 0; x < stride; x += 1) {
+      const left = x >= channels ? recon[x - channels] : 0;
+      const up = prior[x];
+      const upLeft = x >= channels ? prior[x - channels] : 0;
+      let value = raw[rpos + x];
+      if (filter === 1) value += left;
+      else if (filter === 2) value += up;
+      else if (filter === 3) value += (left + up) >> 1;
+      else if (filter === 4) value += paeth(left, up, upLeft);
+      recon[x] = value & 0xff;
+    }
+    rpos += stride;
+    prior = recon;
+  }
+  return { width, height, channels, pixels };
+}
+
+export function comparePng(pathA, pathB, { tolerance = 0 } = {}) {
+  let bufferA;
+  let bufferB;
+  try {
+    bufferA = fs.readFileSync(pathA);
+  } catch {
+    return { ok: false, reason: 'missing-image', identical: false, diffPixels: null, diffRatio: null };
+  }
+  try {
+    bufferB = fs.readFileSync(pathB);
+  } catch {
+    return { ok: false, reason: 'missing-image', identical: false, diffPixels: null, diffRatio: null };
+  }
+
+  if (bufferA.equals(bufferB)) {
+    return { ok: true, reason: 'identical', identical: true, diffPixels: 0, diffRatio: 0 };
+  }
+
+  const a = decodePng(bufferA);
+  const b = decodePng(bufferB);
+  if (a.error || b.error) {
+    return { ok: false, reason: a.error || b.error, identical: false, diffPixels: null, diffRatio: null };
+  }
+  if (a.width !== b.width || a.height !== b.height) {
+    return { ok: false, reason: 'dimension-mismatch', identical: false, diffPixels: null, diffRatio: null, dimsA: { width: a.width, height: a.height }, dimsB: { width: b.width, height: b.height } };
+  }
+  if (a.channels !== b.channels) {
+    return { ok: false, reason: 'channel-mismatch', identical: false, diffPixels: null, diffRatio: null };
+  }
+
+  const total = a.width * a.height;
+  const threshold = Math.round(tolerance * 255);
+  let diffPixels = 0;
+  for (let p = 0; p < total; p += 1) {
+    let maxChannelDelta = 0;
+    for (let k = 0; k < a.channels; k += 1) {
+      const delta = Math.abs(a.pixels[p * a.channels + k] - b.pixels[p * a.channels + k]);
+      if (delta > maxChannelDelta) maxChannelDelta = delta;
+    }
+    if (maxChannelDelta > threshold) diffPixels += 1;
+  }
+
+  const diffRatio = total ? diffPixels / total : 0;
+  const ok = diffPixels === 0;
+  return {
+    ok,
+    reason: ok ? 'identical-pixels' : 'pixel-drift',
+    identical: false,
+    width: a.width,
+    height: a.height,
+    totalPixels: total,
+    diffPixels,
+    diffRatio: Math.round(diffRatio * 1e6) / 1e6,
+  };
+}
+
+export function pixelRegressionGate({ level, currentPath, goldenPath, tolerance = 0 }) {
+  if (level !== PIXEL_REGRESSION_LEVEL) {
+    return { skipped: true, reason: 'pixel regression runs only at full-certification', ok: true };
+  }
+  return { ...comparePng(goldenPath, currentPath, { tolerance }), skipped: false };
+}
+
+// The single sanctioned writer of a golden: copy the freshly-rendered image over it. No code path
+// edits a golden in place, so regeneration stays deterministic and reviewable as one file swap.
+
+export function regenerateGolden({ currentPath, goldenPath }) {
+  try {
+    fs.copyFileSync(currentPath, goldenPath);
+    return { ok: true, goldenPath };
+  } catch (err) {
+    return { ok: false, reason: `regeneration failed: ${err.message}` };
+  }
+}

package/lib/providers/op-run.mjs

@@ -3,10 +3,11 @@
  *
  * When CONSTRUCT_OP_ENV_FILE points to an `op run` env-file (KEY=op://… lines)
  * and the `op` CLI is installed, long-lived Construct services are spawned through
- * `op run --no-masking --env-file <file> -- <cmd>`, so op:// references resolve
- * once at startup into the process env. This mirrors the per-invocation model
- * other LLM CLIs use (e.g. `op run -- opencode`) and gives child processes
- * resolved provider keys without a shell wrapper.
+ * `op run --env-file <file> -- <cmd>`, so op:// references resolve once at startup
+ * into the process env. lib/service-manager.mjs calls wrapWithOpRun at each service
+ * spawn, so the memory server, OpenCode, the copilot bridge, the doctor daemon, and
+ * the oracle daemon all inherit resolved provider keys without a per-invocation
+ * shell wrapper. Masking stays on so resolved secrets are not echoed to service logs.
  *
  * Strictly opt-in: with the var unset, the file missing, or `op` absent, the
  * command is returned unchanged and 1Password is never invoked. No other setup
@@ -51,7 +52,7 @@ export function wrapWithOpRun(command, args = [], { env = process.env, homeDir =
   if (!file || !hasOp()) return { command, args, wrapped: false, envFile: null };
   return {
     command: 'op',
-    args: ['run', '--no-masking', `--env-file=${file}`, '--', command, ...args],
+    args: ['run', `--env-file=${file}`, '--', command, ...args],
     wrapped: true,
     envFile: file,
   };

package/lib/providers/secret-audit-wiring.mjs

@@ -0,0 +1,32 @@
+/**
+ * lib/providers/secret-audit-wiring.mjs — connect secret resolution to the durable
+ * audit trail.
+ *
+ * enableSecretAuditTrail routes the value-free events from secret-resolver into the
+ * append-only audit log (lib/audit-trail.mjs). Only actual op:// resolutions are
+ * recorded — the prompt-bearing, security-significant events — not cache hits or
+ * high-frequency plain reads, so the resolve path is not serialized behind a file
+ * lock. The materialized secret value is never available to this layer and is never
+ * written. Wiring is per-process: the CLI entrypoint enables it; worker and daemon
+ * processes are a tracked follow-up.
+ */
+
+import { appendAuditRecord } from '../audit-trail.mjs';
+import { setSecretAuditSink } from './secret-resolver.mjs';
+
+export function enableSecretAuditTrail({ file } = {}) {
+  setSecretAuditSink((event) => {
+    if (event.event !== 'secret.op_read' || event.cacheHit) return;
+    appendAuditRecord(
+      {
+        ts: new Date().toISOString(),
+        tool: 'secret-resolver',
+        action: 'op_read',
+        ref: event.ref,
+        ok: event.ok,
+        code: event.code ?? null,
+      },
+      file ? { file } : {},
+    );
+  });
+}