@geraldmaron/construct 1.3.2 → 1.4.1

package/lib/export-validate.mjs

@@ -0,0 +1,106 @@
+/**
+ * lib/export-validate.mjs — Post-export validity, content roundtrip, and reference integrity.
+ *
+ * Three deterministic checks that today only a >1KB file-size heuristic covered: a PDF is parsed
+ * by pdfinfo for a real page count, exported text is extracted and compared against the source's
+ * key phrases to catch dropped content, and local image/link targets are resolved on disk. Each
+ * returns a typed degradation reason when its tool is absent rather than a silent pass. Closes the
+ * gaps in subagents/document-export-quality.md and absorbs the construct-amfg PDF-fidelity work.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { whichBin } from './document-export.mjs';
+
+function degraded(reason, message, extra = {}) {
+  return { ok: false, degradation: reason, message, ...extra };
+}
+
+export function validatePdf(pdfPath, env = process.env) {
+  if (!whichBin('pdfinfo', env)) return degraded('missing-dependency', 'pdfinfo not available', { valid: null, pageCount: 0 });
+  if (!fs.existsSync(pdfPath)) return degraded('skipped-by-policy', `pdf not found: ${pdfPath}`, { valid: false, pageCount: 0 });
+  const result = spawnSync('pdfinfo', [pdfPath], { encoding: 'utf8', env });
+  if (result.status !== 0) {
+    return { ok: false, valid: false, pageCount: 0, degradation: null, message: (result.stderr || '').trim() || 'pdfinfo reported an invalid PDF' };
+  }
+  const match = result.stdout.match(/^Pages:\s+(\d+)/m);
+  const pageCount = match ? Number(match[1]) : 0;
+  return { ok: pageCount > 0, valid: pageCount > 0, pageCount, degradation: null, message: `valid PDF, ${pageCount} page(s)` };
+}
+
+// Each format uses the cheapest faithful text extractor; a missing tool degrades with a typed
+// reason instead of reporting empty text as a pass.
+
+function extractText(filePath, format, env) {
+  if (format === 'pdf') {
+    if (!whichBin('pdftotext', env)) return { degradation: 'missing-dependency' };
+    const result = spawnSync('pdftotext', [filePath, '-'], { encoding: 'utf8', env });
+    return result.status === 0 ? { text: result.stdout } : { degradation: 'unavailable-renderer' };
+  }
+  if (format === 'html') {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const text = raw
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .replace(/<(style|script)[\s\S]*?<\/\1>/gi, ' ')
+      .replace(/<[^>]+>/g, ' ');
+    return { text };
+  }
+  if (format === 'docx' || format === 'pptx') {
+    if (!whichBin('unzip', env)) return { degradation: 'missing-dependency' };
+    const member = format === 'docx' ? 'word/document.xml' : 'ppt/slides/slide*.xml';
+    const result = spawnSync('unzip', ['-p', filePath, member], { encoding: 'utf8', env });
+    return result.status === 0 ? { text: result.stdout.replace(/<[^>]+>/g, ' ') } : { degradation: 'unavailable-renderer' };
+  }
+  return { degradation: 'unsupported-format' };
+}
+
+function sourcePhrases(sourceMarkdown) {
+  const body = sourceMarkdown.replace(/^---\n[\s\S]*?\n---\n/, '').replace(/```[\s\S]*?```/g, '');
+  const headings = [...body.matchAll(/^#{1,6}\s+(.+)$/gm)]
+    .map((match) => match[1].trim())
+    .filter((heading) => !/[{}<>]/.test(heading));
+  return [...new Set(headings)].slice(0, 12);
+}
+
+export function contentRoundtrip({ exportPath, format, sourceMarkdown, env = process.env } = {}) {
+  if (!fs.existsSync(exportPath)) return degraded('skipped-by-policy', `export not found: ${exportPath}`, { textRatio: 0, missingPhrases: [] });
+  const extracted = extractText(exportPath, format, env);
+  if (extracted.degradation) return degraded(extracted.degradation, `cannot extract text from ${format}`, { textRatio: 0, missingPhrases: [] });
+
+  // PDF and DOCX text extraction wrap lines arbitrarily, so a heading that survives the export
+  // can still appear with an embedded newline. Collapse all whitespace on both sides before the
+  // substring match; otherwise a faithful export reads as dropped content.
+
+  const normalize = (text) => text.toLowerCase().replace(/\s+/g, ' ').trim();
+  const haystack = normalize(extracted.text || '');
+  const phrases = sourcePhrases(sourceMarkdown);
+  const missingPhrases = phrases.filter((phrase) => !haystack.includes(normalize(phrase)));
+  const ratio = phrases.length ? (phrases.length - missingPhrases.length) / phrases.length : 1;
+  return {
+    ok: missingPhrases.length === 0,
+    textRatio: Math.round(ratio * 100) / 100,
+    missingPhrases,
+    degradation: null,
+    message: `${phrases.length - missingPhrases.length}/${phrases.length} key phrases preserved`,
+  };
+}
+
+// Local image and link targets must resolve on disk; remote URLs, anchors, and mailto are out of
+// scope for an on-disk integrity check.
+
+export function referenceIntegrity(sourceMarkdown, baseDir) {
+  const body = sourceMarkdown.replace(/```[\s\S]*?```/g, '');
+  const missingImages = [];
+  const brokenLinks = [];
+  for (const match of body.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
+    const ref = match[1].split(/\s+/)[0];
+    if (/^https?:|^data:/.test(ref)) continue;
+    if (!fs.existsSync(path.resolve(baseDir, ref))) missingImages.push(ref);
+  }
+  for (const match of body.matchAll(/(?<!!)\[[^\]]*\]\(([^)]+)\)/g)) {
+    const ref = match[1].split(/\s+/)[0];
+    if (/^https?:|^#|^mailto:/.test(ref)) continue;
+    if (!fs.existsSync(path.resolve(baseDir, ref))) brokenLinks.push(ref);
+  }
+  return { ok: missingImages.length === 0 && brokenLinks.length === 0, missingImages, brokenLinks };
+}

package/lib/gates-audit.mjs

@@ -22,6 +22,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
+import { loadArtifactManifest, validateArtifactManifest } from './artifact-manifest.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT_DIR = join(MODULE_DIR, '..');
@@ -58,6 +59,7 @@ const GATE_DEFINITIONS = [
   { ciJob: 'docs drift check',               prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
   { ciJob: 'comment policy',                 prePushLabel: null, preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
   { ciJob: 'template policy',                prePushLabel: null, preCommitGhPrIntercept: true, critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'certification gate',             prePushLabel: null, preCommitCheck: null, critical: true, note: 'artifact release-gate certification: `construct certify gate`; mirrored locally by release:check', requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
   { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null, preCommitCheck: null, critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
 ];
 
@@ -194,6 +196,23 @@ function identifyGaps(state) {
   return gaps;
 }
 
+// Artifact-gate config drift: the manifest's qualityContract gate levels and required completion
+// states are the source of truth for what each artifact's release gate enforces. A typo or an
+// out-of-enum level silently weakens the gate, so the audit validates the manifest and reports any
+// drift. A repo with no manifest (the gates-audit fixture) is skipped, not failed.
+
+export function auditArtifactGateConfig(rootDir = DEFAULT_ROOT_DIR) {
+  const manifestPath = join(rootDir, 'specialists', 'artifact-manifest.json');
+  if (!existsSync(manifestPath)) return { ok: true, errors: [], skipped: 'no manifest' };
+  try {
+    const manifest = loadArtifactManifest({ rootDir, force: true });
+    const result = validateArtifactManifest(manifest);
+    return { ok: result.valid, errors: result.errors || [] };
+  } catch (err) {
+    return { ok: false, errors: [`artifact-manifest unreadable: ${err.message}`] };
+  }
+}
+
 export function auditGates({ rootDir = DEFAULT_ROOT_DIR, repo, branch = 'main' } = {}) {
   const inCI = process.env.CI === 'true' || process.env.CI === '1';
   const ciJobs = parseCIJobs(rootDir);
@@ -204,6 +223,12 @@ export function auditGates({ rootDir = DEFAULT_ROOT_DIR, repo, branch = 'main' }
 
   const state = { ciJobs, prePushJobs, preCommitChecks, branchProtection, hooksPath, rootDir, inCI };
   const gaps = identifyGaps(state);
+
+  const artifactGateConfig = auditArtifactGateConfig(rootDir);
+  for (const error of artifactGateConfig.errors) {
+    gaps.push({ kind: 'artifact-gate-config-drift', gate: error, critical: true });
+  }
+
   const criticalGaps = gaps.filter((g) => g.critical);
 
   return {
@@ -213,6 +238,7 @@ export function auditGates({ rootDir = DEFAULT_ROOT_DIR, repo, branch = 'main' }
     preCommitChecks,
     hooksPath,
     branchProtection,
+    artifactGateConfig,
     gaps,
     criticalGaps,
     inCI,
@@ -241,6 +267,14 @@ export function formatReport(report) {
   lines.push(`core.hooksPath: ${report.hooksPath || '(unset)'}`);
   lines.push('');
 
+  if (report.artifactGateConfig) {
+    const cfg = report.artifactGateConfig;
+    const state = cfg.skipped ? `skipped (${cfg.skipped})` : (cfg.ok ? 'OK ✓' : `${cfg.errors.length} drift issue(s) ✗`);
+    lines.push(`Artifact gate config: ${state}`);
+    for (const e of cfg.errors || []) lines.push(`  • ${e}`);
+    lines.push('');
+  }
+
   if (report.branchProtection.status === 'fetched') {
     lines.push(`Branch protection (main): ${report.branchProtection.requiredContexts.length} required contexts`);
     for (const c of report.branchProtection.requiredContexts) lines.push(`  • ${c}`);

package/lib/health-check.mjs

@@ -9,7 +9,7 @@
 import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, chmodSync } from 'node:fs';
 import { extractOpRef, hasAnySecret, hasSecret } from './providers/secret-resolver.mjs';
 import { configDir } from './config/xdg.mjs';
 
@@ -296,12 +296,15 @@ const CREDENTIAL_VARS = [
 ];
 
 /**
- * Link discovered credential references into the XDG config dir config.env without
- * invoking `op read`. Plain values and op:// refs are persisted as found.
+ * Discover where credential env vars are configured, without invoking `op read`.
+ * Returns a presence map (op:// refs as-is, plain values as found) for reporting.
+ * When writeConfig is set, only op:// references are persisted into the XDG
+ * config.env (mode 0600) — a resolved or plain secret value is never copied to
+ * disk, so config.env holds late-bound references rather than materialized keys.
  * @param {Object} options
  * @param {string} options.homeDir
- * @param {boolean} options.writeConfig - Write keys to config.env (default: false)
- * @returns {Promise<Record<string, string>>} raw values linked (never plaintext from op)
+ * @param {boolean} options.writeConfig - Persist discovered op:// refs to config.env (default: false)
+ * @returns {Promise<Record<string, string>>} discovered raw values (refs or plain), never resolved via op
  */
 export async function resolveCredentials(options = {}) {
   const { homeDir = os.homedir(), writeConfig = false } = options;
@@ -317,10 +320,21 @@ export async function resolveCredentials(options = {}) {
     linked[varName] = ref || raw;
   }
 
-  if (writeConfig && Object.keys(linked).length > 0) {
-    try {
-      writeEnvValues(getUserEnvPath(homeDir), linked);
-    } catch { /* best effort */ }
+  // Persist references only. A plain value discovered in a dotenv or shell rc is
+  // reported as present but never written into config.env — copying a resolved
+  // secret to disk is the late-binding violation this path must not commit.
+  if (writeConfig) {
+    const refsOnly = {};
+    for (const [name, value] of Object.entries(linked)) {
+      if (extractOpRef(value)) refsOnly[name] = value;
+    }
+    if (Object.keys(refsOnly).length > 0) {
+      try {
+        const file = getUserEnvPath(homeDir);
+        writeEnvValues(file, refsOnly);
+        chmodSync(file, 0o600);
+      } catch { /* best effort */ }
+    }
   }
 
   return linked;

package/lib/hooks/guard-bash.mjs

@@ -4,7 +4,9 @@
  *
  * Runs as PreToolUse on Bash. Scans the command against a blocklist of destructive patterns (rm -rf, force push to main, etc.) and exits 2 to block matches.
  *
- * @p95ms 5
+ * Budget covers the role-fence path below — doctorRoot lookup, last-agent file reads, and the lazy manifest/fence/approval imports — which the original 5ms target predated; the nightly bench (variance-heavy CI lane) measured ~17-19ms marginal, so the budget reflects that real cost with the ×2 gate tolerance still catching a true regression.
+ *
+ * @p95ms 15
  * @maxBlockingScope PreToolUse
  *
  * @lifecycle PreToolUse

package/lib/hooks/session-start.mjs

@@ -260,6 +260,7 @@ try {
 // `knowledge_search` instead of training-data recall. Full policy in persona.
 
 const selfKnowledgeNote = '\nSelf-knowledge: call `knowledge_search` for any Construct-specific question.\n';
+const orchestrationReadinessNote = '\nOrchestration readiness: not checked for this host session — run `construct orchestrate preflight --json` or call MCP `orchestration_readiness` before relying on multi-specialist execution.\n';
 
 // Configured provider sources hint — tell Construct what repos/projects are
 // wired so it knows to call `provider_fetch` instead of saying "no context".
@@ -386,7 +387,7 @@ try {
 // that pollutes the caller's output contract, so the resolved output mode routes
 // the payload to stdout (interactive), stderr, or a debug log (silent).
 
-const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
+const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${orchestrationReadinessNote}${rolesNote}${intakeReviewNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
 try {
   const { mode } = resolveHookOutputMode({ cwd, env: process.env });
   writeHookContext({ payload, mode });

package/lib/init-unified.mjs

@@ -612,12 +612,14 @@ function preflight(target) {
     throw new Error('Not a git repository. Run `git init` first.');
   }
   
-  // Check working tree clean (silent unless verbose)
+  // A dirty working tree before init/upgrade is surfaced by default so the user knows scaffolding
+  // lands on top of uncommitted changes; the file-count detail stays behind --verbose.
+
   const porcelain = execSync('git status --porcelain', { cwd: target, encoding: 'utf8' }).trim();
   const clean = porcelain === '';
-  if (!clean && verbose) {
+  if (!clean) {
     console.warn('Warning: Working tree has uncommitted changes');
-    if (porcelain.split('\n').length > 10) {
+    if (verbose && porcelain.split('\n').length > 10) {
       console.warn(`  (${porcelain.split('\n').length} files modified)`);
     }
   }

package/lib/mcp/server.mjs

@@ -3,7 +3,8 @@
  * lib/mcp/server.mjs — Construct MCP server: tool registry and request dispatcher.
  *
  * Thin dispatcher only — all tool implementations live in lib/mcp/tools/*.mjs.
- * Registers 52 tools across 8 modules: project, document, storage, skills, workflow, telemetry, memory, scope.
+ * Registers the Construct MCP tool catalog across project, document, storage,
+ * skills, workflow, telemetry, memory, scope, and orchestration modules.
  * Consumed by Claude Code, OpenCode, and any MCP-compatible host.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -62,6 +63,7 @@ import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, exec
 import { authorArtifact } from './tools/artifact-author.mjs';
 import { findTool } from './tools/find-tool.mjs';
 import { recoverToolName, recordToolNameMiss, isGatewayName } from './tool-recovery.mjs';
+import { buildOrchestrationReadiness } from '../orchestration/readiness.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -1284,6 +1286,19 @@ const ALL_TOOL_DEFS = [
         },
       },
     },
+    {
+      name: 'web_search',
+      description: 'Search the PUBLIC WEB and return CITED results — the only search surface that reaches the open web, kept distinct from knowledge_search / provider_fetch / repo search so it is never conflated or faked. Requires a governed provider (WEB_SEARCH_URL); without one it returns a typed degradation (capability-unavailable) and zero results, never source/repo results dressed as web. Every result carries a verifiable URL, a claim-relative class, and an Admiralty grade with derived confidence (ADR-0017; high reserved for A1/A2/B1).',
+      inputSchema: {
+        type: 'object',
+        required: ['query', 'claim'],
+        properties: {
+          query: { type: 'string', description: 'The search query string.' },
+          claim: { type: 'string', description: 'The claim the results are meant to support — drives claim-relative source classification (ADR-0017).' },
+          recency: { type: 'string', description: 'Optional freshness window hint (e.g. "30d").' },
+        },
+      },
+    },
     {
       name: 'orchestration_status',
       description: 'Inspect orchestration runs on the local Construct daemon: pass run_id for the full record (status, per-task status/executor/output/error), or omit it for a list of recent runs. Fails fast if the daemon is unreachable.',
@@ -1295,6 +1310,22 @@ const ALL_TOOL_DEFS = [
         },
       },
     },
+    {
+      name: 'orchestration_readiness',
+      description: 'Report whether this MCP session has the required Construct orchestration tools attached and reachable now. Returns a pass/fail verdict, typed reasonCode, one next step, required/observed/missing tools, and a redacted diagnostic bundle for support.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          host: { type: 'string', description: 'Host/IDE identifier, if known.' },
+          session_id: { type: 'string', description: 'Host session/thread id, if known.' },
+          observed_tools: { type: 'array', items: { type: 'string' }, description: 'Optional tool names the host observed in tools/list. Defaults to this server catalog.' },
+          reachable_tools: { type: 'array', items: { type: 'string' }, description: 'Optional long-tail tools reachable through a gateway enum.' },
+          required_tools: { type: 'array', items: { type: 'string' }, description: 'Tools required for orchestration. Defaults to orchestration_policy + orchestration_run.' },
+          client_contract_version: { type: 'string', description: 'Client contract version for compatibility checks.' },
+          observation_scope: { type: 'string', enum: ['host-session', 'local-config'], description: 'What was observed. MCP calls normally use host-session.' },
+        },
+      },
+    },
 ];
 
 // Curated flat core: high-frequency, low-arg tools the orchestrator and the
@@ -1303,10 +1334,10 @@ const ALL_TOOL_DEFS = [
 // host/model; the long tail is reachable, just not front-loaded.
 
 const CORE_TOOL_NAMES = new Set([
-  'orchestration_policy', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
+  'orchestration_policy', 'orchestration_run', 'get_skill', 'get_template', 'search_skills', 'knowledge_search',
   'memory_search', 'project_context', 'summarize_diff', 'find_tool',
   'author_artifact', 'document_export', 'publish_run', 'artifact_workflow',
-  'workflow_invoke', 'triage_recommend',
+  'workflow_invoke', 'triage_recommend', 'orchestration_readiness',
 ]);
 
 const LONG_TAIL_DEFS = ALL_TOOL_DEFS.filter((t) => !CORE_TOOL_NAMES.has(t.name));
@@ -1340,6 +1371,15 @@ export function exposedTools() {
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: exposedTools() }));
 
+function currentMcpToolCatalog() {
+  const tools = exposedTools();
+  const observedTools = tools.map((t) => t.name);
+  const reachableTools = tools.flatMap((t) => (
+    t.name === 'call' ? (t.inputSchema?.properties?.tool?.enum ?? []) : []
+  ));
+  return { observedTools, reachableTools };
+}
+
 // Single dispatch table shared by the direct CallTool path and the construct_call
 // meta-tool, so collapsing the surface costs no capability — every tool stays
 // reachable by name. construct_call re-enters here once (guarded against
@@ -1466,7 +1506,17 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'artifact_workflow') result = artifactWorkflow(args);
     else if (name === 'author_artifact') result = await authorArtifact(args, opts);
     else if (name === 'find_tool') result = await findTool(args, { toolDefs: ALL_TOOL_DEFS, env: process.env });
+    else if (name === 'orchestration_readiness') {
+      const catalog = currentMcpToolCatalog();
+      result = buildOrchestrationReadiness({
+        ...args,
+        observedTools: args.observed_tools ?? catalog.observedTools,
+        reachableTools: args.reachable_tools ?? catalog.reachableTools,
+        observationScope: args.observation_scope ?? 'host-session',
+      }, { env: process.env, cwd: process.cwd() });
+    }
     else if (name === 'orchestration_run') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationRun(args); }
+    else if (name === 'web_search') { const m = await import('./tools/web-search.mjs'); result = await m.webSearch(args); }
     else if (name === 'orchestration_status') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationStatus(args); }
     else if (name === 'call') {
       const inner = String(args?.tool || '');

package/lib/mcp/tool-recovery.mjs

@@ -42,3 +42,59 @@ export function recordToolNameMiss(rootDir, { name, recovered = null } = {}) {
     /* telemetry is best-effort; never break dispatch */
   }
 }
+
+function readJsonl(rootDir, file, kind) {
+  const out = [];
+  try {
+    for (const line of fs.readFileSync(path.join(rootDir, '.cx', 'observations', file), 'utf8').split('\n')) {
+      if (!line) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry.kind === kind) out.push(entry);
+    }
+  } catch { /* absent file = no records */ }
+  return out;
+}
+
+function aggregateByKey(entries, key) {
+  const counts = new Map();
+  let recovered = 0;
+  for (const e of entries) {
+    const k = e[key] || '(unknown)';
+    const c = counts.get(k) || { name: k, count: 0, recovered: 0 };
+    c.count += 1;
+    if (e.recovered) { c.recovered += 1; recovered += 1; }
+    counts.set(k, c);
+  }
+  const byName = [...counts.values()].sort((a, b) => b.count - a.count);
+  return { total: entries.length, recovered, byName };
+}
+
+// The read side of recordToolNameMiss: aggregate misses by name so the
+// discoverability signal is acted on, not just stored. A name missed repeatedly
+// is a tool agents cannot find — the candidate for a doc/alias fix.
+
+export function summarizeToolNameMisses(rootDir, { top = 5 } = {}) {
+  const agg = aggregateByKey(readJsonl(rootDir, 'tool-name-misses.jsonl', 'tool-name-miss'), 'name');
+  return { ...agg, top: agg.byName.slice(0, top) };
+}
+
+// Failure capture: record a tool/command failure (timeout, error, gate denial) as
+// an observation so repeated failures become a learnable anti-pattern rather than
+// an invisible one-off. Best-effort, like the miss telemetry above.
+
+export function recordToolFailure(rootDir, { tool, code = null, message = '' } = {}) {
+  try {
+    const dir = path.join(rootDir, '.cx', 'observations');
+    fs.mkdirSync(dir, { recursive: true });
+    const line = `${JSON.stringify({ at: new Date().toISOString(), kind: 'tool-failure', name: tool, code, message })}\n`;
+    fs.appendFileSync(path.join(dir, 'tool-failures.jsonl'), line);
+  } catch {
+    /* telemetry is best-effort; never break dispatch */
+  }
+}
+
+export function summarizeToolFailures(rootDir, { top = 5 } = {}) {
+  const agg = aggregateByKey(readJsonl(rootDir, 'tool-failures.jsonl', 'tool-failure'), 'name');
+  return { ...agg, top: agg.byName.slice(0, top) };
+}

package/lib/mcp/tools/web-search.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/mcp/tools/web-search.mjs — governed public web search (construct-rr63.5.3).
+ *
+ * The one Construct search surface that reaches the public web, kept distinct from the source/repo/
+ * local surfaces so it can never be faked or conflated (the contract in
+ * docs/notes/research/construct-self-audit/synthesis/web-search-capability-contract.md). Three
+ * invariants: (1) every returned result carries a verifiable URL, a claim-relative class, and an
+ * Admiralty grade with a derived confidence (ADR-0017) — results without a URL are dropped, not
+ * guessed; (2) every result is labeled `source: 'web'` and the tool never falls back to repo/source
+ * search; (3) when no governed provider is configured or the provider is unreachable, the tool
+ * returns a typed degradation and zero results rather than claiming it searched the web.
+ */
+
+const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
+const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
+
+// Recency enforcement (rules/common/research.md §1, research-execution-policy
+// recencyRule). The researcher is told to search most-recent-first and treat
+// sources older than 12 months as stale, but the provider returns relevance- and
+// authority-ranked results with the date dropped, so older established sources
+// surface over newer ones. Normalize a date from whatever field the provider
+// supplies, flag staleness against the 12-month window, and reorder
+// most-recent-first. Admiralty-derived `confidence` is left intact (ADR-0017);
+// recency rides alongside it as `date` + `stale` rather than folded into it.
+
+const STALE_AFTER_DAYS = 365;
+
+function normalizeDate(it) {
+  const raw = it.date || it.publishedAt || it.published || it.published_at || it.datePublished || null;
+  if (!raw) return null;
+  const t = Date.parse(raw);
+  return Number.isNaN(t) ? null : new Date(t).toISOString().slice(0, 10);
+}
+
+function providerConfig(env) {
+  const url = env.WEB_SEARCH_URL;
+  if (!url) return null;
+  return { url, key: env.WEB_SEARCH_KEY || null };
+}
+
+// Claim-relative class (ADR-0017): community content is admissible primary evidence for sentiment/
+// demand claims under a checklist the tool cannot verify deterministically, so it defaults community
+// hosts to `tertiary` (conservative for factual claims) and everything else to `secondary`, leaving
+// the researcher to promote a community source to primary when the claim is about experience.
+
+function classifyResult(url) {
+  try {
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    return COMMUNITY_HOSTS.some((h) => host === h || host.endsWith('.' + h)) ? 'tertiary' : 'secondary';
+  } catch {
+    return 'tertiary';
+  }
+}
+
+// Confidence maps from the Admiralty grade; `high` is reserved for A1/A2/B1 (ADR-0017). A grade with
+// reliability A/B or credibility 1/2 is `medium`; anything weaker is `low`.
+
+function confidenceFromGrade(grade) {
+  if (HIGH_CONFIDENCE_GRADES.has(grade)) return 'high';
+  const reliability = grade?.[0];
+  const credibility = grade?.[1];
+  if (reliability === 'A' || reliability === 'B' || credibility === '1' || credibility === '2') return 'medium';
+  return 'low';
+}
+
+function degraded(reason, note) {
+  return { source: 'web', degraded: true, degradationReason: reason, results: [], note };
+}
+
+export async function webSearch(args = {}, { env = process.env, fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  const { query, claim, recency = null } = args;
+  if (!query || typeof query !== 'string') {
+    return { error: { code: 'INVALID_INPUT', message: 'query (string) is required' } };
+  }
+  if (!claim || typeof claim !== 'string') {
+    return { error: { code: 'INVALID_INPUT', message: 'claim (string) is required — it drives source classification (ADR-0017)' } };
+  }
+
+  const provider = providerConfig(env);
+  if (!provider) {
+    return degraded('capability-unavailable', 'No governed web search provider is configured (set WEB_SEARCH_URL). Construct will not present source or repo search as web search.');
+  }
+
+  let payload;
+  try {
+    const qs = `?q=${encodeURIComponent(query)}${recency ? `&recency=${encodeURIComponent(recency)}` : ''}`;
+    const res = await fetchImpl(provider.url + qs, { headers: provider.key ? { Authorization: `Bearer ${provider.key}` } : {} });
+    if (!res.ok) return degraded('server-unreachable', `Web search provider returned HTTP ${res.status}`);
+    payload = await res.json();
+  } catch (err) {
+    return degraded('server-unreachable', `Web search provider unreachable: ${err.message}`);
+  }
+
+  const items = Array.isArray(payload?.results) ? payload.results : [];
+  const results = items
+    .filter((it) => it && typeof it.url === 'string' && /^https?:\/\//.test(it.url))
+    .map((it) => {
+      const admiralty = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty) ? it.admiralty : 'C3';
+      const date = normalizeDate(it);
+      const stale = date != null && (now - Date.parse(date)) > STALE_AFTER_DAYS * 86_400_000;
+      return {
+        source: 'web',
+        url: it.url,
+        title: typeof it.title === 'string' && it.title ? it.title : it.url,
+        snippet: typeof it.snippet === 'string' ? it.snippet : '',
+        class: classifyResult(it.url),
+        admiralty,
+        confidence: confidenceFromGrade(admiralty),
+        date,
+        stale,
+        needsGrading: !(typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty)),
+      };
+    });
+
+  // Order most-recent-first: fresh dated results, then undated (provider order
+  // kept by the stable sort), then stale ones; newest first within a tier.
+
+  const tier = (r) => (r.date && !r.stale ? 0 : r.date ? 2 : 1);
+  results.sort((a, b) => {
+    const t = tier(a) - tier(b);
+    if (t !== 0) return t;
+    if (a.date && b.date) return Date.parse(b.date) - Date.parse(a.date);
+    return 0;
+  });
+
+  return { source: 'web', degraded: false, query, claim, results, dropped: items.length - results.length };
+}

package/lib/mcp-manager.mjs

@@ -4,7 +4,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, chmodSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { homedir, platform } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -441,11 +441,18 @@ export async function cmdMcpAdd(id) {
     removeCodexMcp(id);
   }
 
-  // --- SYNC TO .ENV ---
+  // The credential lands in the XDG config.env, the single secret store read by
+  // loadConstructEnv and secret-resolver. Host MCP env blocks reference the env var
+  // name; config.env is what populates process.env so child MCP processes inherit the
+  // value (or its lazily-resolved op:// reference), so this write is load-bearing, not
+  // a redundant copy. config.env can hold a plaintext secret, so it is chmod 0600 to
+  // match credential-bootstrap; an op:// reference is preserved verbatim and resolved
+  // lazily rather than materialized here.
+
   const envPath = getUserEnvPath(homedir());
   writeEnvValues(envPath, envValues);
+  if (existsSync(envPath)) chmodSync(envPath, 0o600);
   console.log(`✓ Credentials synchronized to ${envPath}`);
-  // --------------------
 
   console.log(`\n✓ ${mcp.name} successfully wired into Claude Code, OpenCode, and Codex.`);
   console.log(`✓ Setup mode: ${setupMode}`);
@@ -453,7 +460,7 @@ export async function cmdMcpAdd(id) {
   console.log(`✓ Services synchronized.`);
   console.log(`\nNext: Restart OpenCode, Claude Code, or Codex to activate the new tools.`);
   if (id === 'github' && authMode === 'oauth') {
-    console.log(`\nAuthenticate (one-click OAuth, no token stored on disk):`);
+    console.log(`\nAuthenticate (one-click OAuth — no PAT to paste; the host manages the token):`);
     console.log(`   Claude Code: \`claude mcp login github\`   ·   OpenCode: \`opencode mcp auth github\``);
     console.log(`   VS Code / Cursor: approve the sign-in prompt on first use.`);
     console.log(`   PAT fallback (headless/CI): \`construct mcp add github --token\``);

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)),
   );
 }
 
@@ -52,6 +61,14 @@ const SECRET_REF = {
   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));
 }