@geraldmaron/construct 1.0.21 → 1.0.24

package/scripts/sync-specialists.mjs

@@ -52,6 +52,7 @@ import {
 } from "../lib/mcp-platform-config.mjs";
 import { loadConstructEnv } from "../lib/env-config.mjs";
 import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
+import { loadManifest } from "../lib/roles/manifest.mjs";
 import { resolveActiveProfile } from "../lib/profiles/loader.mjs";
 import { resolveTiersForPrimary } from "../lib/model-router.mjs";
 import { stampFrontmatter } from "../lib/doc-stamp.mjs";
@@ -156,6 +157,67 @@ const COMPRESS_PERSONAS = process.argv.includes("--compress-personas");
 const PROJECT_FLAG = process.argv.includes("--project");
 const GLOBAL_FLAG = process.argv.includes("--global");
 
+// --quiet suppresses only the closing one-line summary, not the work or any
+// warning. `construct install` runs the global tier twice (plain `sync` then
+// `sync --global`); in a non-project cwd both land in the same global branch and
+// print the identical "Synced … to global scope" + "Completions updated" lines.
+// Passing --quiet to the first call lets the canonical summary print exactly once
+// from `sync --global`, with no change to what either call writes.
+
+const QUIET = process.argv.includes("--quiet") || process.argv.includes("-q");
+const summary = (msg) => { if (!QUIET) console.log(msg); };
+
+// Project-tier host selection. `--hosts=claude,codex,…` (or CONSTRUCT_SYNC_HOSTS)
+// restricts which adapter sets the project tier writes, so `construct init` can
+// scaffold only the hosts the user actually has (construct-4xy6 / ADR-0027 §1).
+// Absent → null → write every host, preserving `construct sync` back-compat.
+
+import { detectHostCapabilities } from "../lib/host-capabilities.mjs";
+
+const HOST_KEYS = ["claude", "codex", "copilot", "opencode", "vscode", "cursor"];
+
+function parseHostSelection() {
+  const arg = process.argv.find((a) => a.startsWith("--hosts="));
+  const raw = arg ? arg.slice("--hosts=".length) : process.env.CONSTRUCT_SYNC_HOSTS;
+  if (!raw) {
+    // Default to detected hosts if none are explicitly requested.
+    const detected = new Set();
+    const nameToKey = {
+      "Claude Code": "claude",
+      "OpenCode": "opencode",
+      "Codex": "codex",
+      "VS Code": "vscode",
+      "Cursor": "cursor",
+      "Copilot": "copilot",
+    };
+    try {
+      for (const cap of detectHostCapabilities()) {
+        if (cap.availability === "installed" && nameToKey[cap.host]) {
+          detected.add(nameToKey[cap.host]);
+        }
+      }
+    } catch { /* detection is advisory */ }
+
+    // Config file present means the user has (or had) OpenCode — include it
+    // so the sync writes to the existing config rather than pruning it.
+    // Binary-based detection misses non-PATH installs and CI-runner setups.
+    if (!detected.has("opencode")) {
+      try {
+        if (fs.existsSync(findOpenCodeConfigPath())) detected.add("opencode");
+      } catch { /* advisory */ }
+    }
+
+    // Always include Claude as the baseline if nothing else is detected.
+    if (detected.size === 0) detected.add("claude");
+    return detected;
+  }
+  const wanted = new Set(raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean));
+  return new Set(HOST_KEYS.filter((k) => wanted.has(k)));
+}
+
+const HOST_SELECTION = parseHostSelection();
+const wantsHost = (key) => HOST_SELECTION.has(key);
+
 /**
  * A Construct project carries `.construct/` (the launcher staged by
  * `stage-project.mjs`) or `.cx/` (state). When `construct sync` runs inside
@@ -469,6 +531,64 @@ function buildRoleFooter(entry) {
   return `\n\n${lines.join("\n")}`;
 }
 
+// Fence + handoff data is the source of truth in specialists/role-manifests.json
+// (events, fence.allowedPaths, fence.allowedBdLabels, fence.approvalRequired,
+// handoffCandidates, outputs.docTypes). Restating that JSON inside each
+// specialist prompt would invite drift across 28 files; the renderer below
+// emits the section from the manifest entry so the JSON is the only authority.
+//
+// Returns the empty string for an unonboarded persona (no manifest entry, or
+// an empty fence block). buildPrompt appends the result verbatim, so the
+// returned string carries its own leading separator.
+
+export function renderRoleFrameworkSection(entry) {
+  const personaName = String(entry?.name || "").replace(/^cx-/, "");
+  if (!personaName) return "";
+  const manifest = loadManifest(personaName);
+  if (!manifest) return "";
+
+  const events = Array.isArray(manifest.events) ? manifest.events : [];
+  const fence = manifest.fence || {};
+  const allowedPaths = Array.isArray(fence.allowedPaths) ? fence.allowedPaths : [];
+  const allowedBdLabels = Array.isArray(fence.allowedBdLabels) ? fence.allowedBdLabels : [];
+  const approvalRequired = Array.isArray(fence.approvalRequired) ? fence.approvalRequired : [];
+  const handoffCandidates = Array.isArray(manifest.handoffCandidates) ? manifest.handoffCandidates : [];
+  const docTypes = Array.isArray(manifest.outputs?.docTypes) ? manifest.outputs.docTypes : [];
+
+  // Empty fence + empty events means the persona is reserved but not wired —
+  // no section to render rather than emit a misleading stub.
+
+  if (!events.length && !allowedPaths.length) return "";
+
+  const fmt = (xs) => xs.map((x) => `\`${x}\``).join(", ");
+  const eventList = events.length ? fmt(events) : "_handoff events_";
+  const pathList = allowedPaths.length ? fmt(allowedPaths) : "_none declared_";
+  const labelList = allowedBdLabels.length ? fmt(allowedBdLabels) : "_none declared_";
+  const approvalList = approvalRequired.length ? fmt(approvalRequired) : "_no approval gate declared_";
+  const docTypeList = docTypes.length ? fmt(docTypes) : "role-specific artifacts";
+  const handoffList = handoffCandidates.length
+    ? handoffCandidates.map((c) => `\`next:cx-${c}\``).join(", ")
+    : "";
+
+  const lines = [
+    "",
+    "## When invoked via the role framework",
+    "",
+    `Construct may dispatch you in response to ${eventList} events. A bd issue with the event payload exists when dispatched: read it first via \`bd show <id>\`.`,
+    "",
+    `**Fence** (source of truth: \`specialists/role-manifests.json\` → \`${personaName}\`):`,
+    `- Allowed paths: ${pathList}`,
+    `- Allowed bd labels: ${labelList}`,
+    `- Approval required: ${approvalList}`,
+    "",
+    `You may freely create, edit, and verify within the fence (allowed paths and labels above). You produce ${docTypeList}. You **must not** commit, push, or operate outside the fence without explicit user approval per \`rules/common/commit-approval.md\`.`,
+  ];
+  if (handoffList) {
+    lines.push("", `**Handoff syntax**: append a bd label of the form \`next:cx-<role>\`. Candidates from this role: ${handoffList}.`);
+  }
+  return `\n\n${lines.join("\n")}`;
+}
+
 function buildPrompt(entry, allEntries, platform) {
   let prompt = resolvePromptContract(entry, {
     rootDir: root,
@@ -485,6 +605,8 @@ function buildPrompt(entry, allEntries, platform) {
 
   prompt += buildRoleFooter(entry);
 
+  prompt += renderRoleFrameworkSection(entry);
+
   const platformItems = platformGuidance[platform] ?? [];
   const allGuidance = [...sharedGuidance, ...platformItems];
   if (allGuidance.length > 0) {
@@ -678,6 +800,50 @@ function makeHooksPortable(hooksJson) {
   return JSON.stringify(walk(hooksJson));
 }
 
+const GLOBAL_CLAUDE_HOOK_IDS = new Set([
+  'pre:bash:block-no-verify',
+  'pre:bash:guard-dangerous',
+  'pre:edit:config-protection',
+  'pre:edit-guard',
+  'post:edit:json-validate',
+  'post:edit:scan-secrets',
+]);
+
+const GLOBAL_CLAUDE_MCP_IDS = new Set([
+  'context7',
+]);
+
+function filterGlobalClaudeHooks(hooksJson) {
+  const filtered = {};
+  for (const [event, groups] of Object.entries(hooksJson ?? {})) {
+    const kept = groups.filter((group) => GLOBAL_CLAUDE_HOOK_IDS.has(group.id));
+    if (kept.length > 0) filtered[event] = kept;
+  }
+  return filtered;
+}
+
+function syncGlobalClaudeMcpServers(settings, registryMcp) {
+  settings.mcpServers ??= {};
+  for (const id of Object.keys(settings.mcpServers)) {
+    if (id in registryMcp && !GLOBAL_CLAUDE_MCP_IDS.has(id)) {
+      delete settings.mcpServers[id];
+    }
+  }
+
+  for (const [id, mcpDef] of Object.entries(registryMcp)) {
+    if (!GLOBAL_CLAUDE_MCP_IDS.has(id)) continue;
+    const existingEntry = settings.mcpServers[id];
+    const existing = JSON.stringify(existingEntry ?? "");
+    const hasPlaceholder = existing.includes("__");
+    const hasFloatingVersion = existing.includes("@latest");
+    const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+    const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+    const transportMismatch = registryWantsCommand && existingIsRemote;
+    if (existingEntry && !hasPlaceholder && !hasFloatingVersion && !transportMismatch) continue;
+    settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+  }
+}
+
 /**
  * Materialise a project-local `.claude/settings.json` from the home template,
  * with hook commands rewritten to be path-relative to whatever Construct
@@ -709,22 +875,40 @@ function writeProjectClaudeSettings(targetDir) {
     }
   }
 
+  // The registry is the single source of truth for MCP servers; VS Code, Codex,
+  // and OpenCode all wire it. Project Claude must match — above all `construct-mcp`,
+  // the server exposing project_context/get_skill/get_template/orchestration_policy
+  // that the specialist loop depends on. The curated template omits it, which left
+  // Claude Code as the only selected tool without the construct config. Merge the
+  // registry on top of the template seed; existing entries win so user edits stick,
+  // and buildClaudeMcpEntry resolves each server's path/env.
+  const registryMcp = registry.mcpServers ?? {};
+  existing.mcpServers ??= {};
+  for (const [id, mcpDef] of Object.entries(registryMcp)) {
+    if (existing.mcpServers[id]) continue;
+    existing.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+  }
+
   if (DRY_RUN) return;
   mkdirp(path.dirname(settingsPath));
   writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n");
 }
 
-function syncClaude(entries, targetDir = null) {
+function syncClaude(entries, targetDir = null, wants = true) {
   const claudeAgentsDir = targetDir
     ? path.join(targetDir, ".claude", "agents")
     : path.join(home, ".claude", "agents");
-  if (!DRY_RUN) mkdirp(claudeAgentsDir);
+  if (!DRY_RUN && wants) mkdirp(claudeAgentsDir);
 
-  // Global scope ships only the `construct` front-door agent; specialists are
-  // project content. removeStaleAdapters will sweep any cx-* files left over
-  // from previous syncs because they fall out of the manifest set.
+  // Claude Code and VS Code both read the user-scope `~/.claude/agents/`, so a
+  // global front-door agent duplicates the project orchestrator in any editor
+  // that reads both scopes (the construct ×2 in the VS Code picker). Global
+  // scope therefore writes NO agent file — the project's own
+  // `.claude/agents/construct.md` is the front door; global hooks (settings.json)
+  // and CLAUDE.md still install. An empty write set sweeps any global agent.
+  // Both global and project scope now emit only the front door (Single Front Door).
 
-  const writeEntries = targetDir ? entries : globalEntries(entries);
+  const writeEntries = (targetDir && wants) ? globalEntries(entries) : [];
 
   for (const entry of writeEntries) {
     const name = adapterName(entry);
@@ -733,7 +917,7 @@ function syncClaude(entries, targetDir = null) {
   }
   removeStaleAdapters(claudeAgentsDir, ".md", writeEntries);
   if (!targetDir) {
-    sweepLegacyPrefixedFiles(claudeAgentsDir, ".md", writeEntries.map((e) => `${adapterName(e)}.md`));
+    sweepLegacyPrefixedFiles(claudeAgentsDir, ".md", []);
   }
 
   if (targetDir) {
@@ -768,23 +952,13 @@ ${personaList}
           const constructReal = (() => {
             try { return fs.realpathSync(path.join(home, ".construct")); } catch { return path.join(home, ".construct"); }
           })();
-          const hookStr = JSON.stringify(template.hooks)
+          const hookStr = JSON.stringify(filterGlobalClaudeHooks(template.hooks))
             .replace(/\$HOME\/\.construct/g, constructReal.replace(/\\/g, "/"));
           settings.hooks = JSON.parse(hookStr);
         }
       }
-      if (!settings.mcpServers) settings.mcpServers = {};
       const registryMcp = registry.mcpServers ?? {};
-      for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existingEntry = settings.mcpServers[id];
-        const existing = JSON.stringify(existingEntry ?? "");
-        const hasPlaceholder = existing.includes("__");
-        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
-        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
-        const transportMismatch = registryWantsCommand && existingIsRemote;
-        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-        settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
-      }
+      syncGlobalClaudeMcpServers(settings, registryMcp);
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
     }
   }
@@ -824,14 +998,29 @@ function isCodexMcpSupported() {
   return true;
 }
 
-function syncCodex(entries, targetDir = null) {
+// Codex aborts at startup when an MCP server's bearer_token_env_var names an env
+// var that is unset ("Environment variable GITHUB_TOKEN for MCP server github is
+// not set"). Unlike OpenCode — which keeps the `{env:VAR}` ref and resolves it at
+// runtime — Codex must have the credential at sync time, so an entry whose token
+// env var is unresolved is omitted from the Codex config (construct-n6h7).
+// Entries with no credential requirement always pass.
+
+function codexMcpEnvResolves(id, def, env = process.env) {
+  const entry = buildCodexMcpEntry(id, def, env);
+  const tokenVar = entry?.bearer_token_env_var;
+  if (!tokenVar) return true;
+  const val = env[tokenVar];
+  return val !== undefined && val !== "";
+}
+
+function syncCodex(entries, targetDir = null, wants = true) {
   const codexDir = targetDir
     ? path.join(targetDir, ".codex")
     : path.join(home, ".codex");
   const codexAgentsDir = path.join(codexDir, "agents");
-  if (!DRY_RUN) mkdirp(codexAgentsDir);
+  if (!DRY_RUN && wants) mkdirp(codexAgentsDir);
 
-  const writeEntries = targetDir ? entries : globalEntries(entries);
+  const writeEntries = wants ? globalEntries(entries) : [];
 
   for (const entry of writeEntries) {
     writeFile(path.join(codexAgentsDir, `${adapterName(entry)}.toml`), codexAgentToml(entry, entries));
@@ -847,8 +1036,12 @@ function syncCodex(entries, targetDir = null) {
   const existing = removeDanglingConstructMcpMarkers(removeDanglingConstructMcpTimeouts(readCodexConfig(configPath)));
   const entryNames = writeEntries.map(adapterName);
   const registryMcp = registry.mcpServers ?? {};
+  // Seed every supported MCP server (parity with Claude/OpenCode/VS Code/Cursor),
+  // not just tables already present — otherwise Codex never receives `construct-mcp`
+  // and the orchestration tool is unreachable there. existingMcpIds still drives
+  // cleanup of any pre-existing standalone tables so the managed block stays canonical.
+  const mcpIds = Object.keys(registryMcp).filter((id) => isCodexMcpSupported() && codexMcpEnvResolves(id, registryMcp[id], process.env));
   const existingMcpIds = Object.keys(registryMcp).filter((id) => hasCodexMcpTable(existing, id));
-  const mcpIds = existingMcpIds.filter(isCodexMcpSupported);
   const withoutManagedTables = removeDanglingConstructMcpMarkers(removeTomlTables(
     removeCodexAgentTables(existing, entryNames),
     existingMcpIds.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]),
@@ -856,6 +1049,14 @@ function syncCodex(entries, targetDir = null) {
   const hasAgentsRoot = /^\[agents\]\s*$/m.test(withoutManagedTables);
   const rootBlock = hasAgentsRoot ? "" : "[agents]\nmax_threads = 6\nmax_depth = 1\n\n";
 
+  // Workspace-write agents (the orchestrator + canEdit specialists) need network
+  // access for WebFetch/context7 — Codex's workspace-write sandbox blocks the
+  // network unless this is set. Skip when the user already manages the table so
+  // their own sandbox settings (e.g. writable_roots) are not clobbered.
+
+  const hasSandboxConfig = /^\[sandbox_workspace_write\]/m.test(withoutManagedTables);
+  const sandboxBlock = hasSandboxConfig ? "" : "[sandbox_workspace_write]\nnetwork_access = true\n\n";
+
   // In project scope every entry is reachable from the user (Construct dispatches
   // internal specialists itself, but project teammates may want to address them).
   // In global scope only the `construct` front-door agent is registered.
@@ -869,7 +1070,7 @@ config_file = ${tomlString(`agents/${adapterName(e)}.toml`)}
   const mcpBlock = mcpIds
     .map((id) => serializeCodexMcpTable(id, buildCodexMcpEntry(id, registryMcp[id], process.env)))
     .join("\n\n");
-  const withAgents = replaceManagedBlock(withoutManagedTables, `${rootBlock}${blocks}`);
+  const withAgents = replaceManagedBlock(withoutManagedTables, `${sandboxBlock}${rootBlock}${blocks}`);
   writeCodexConfig(replaceManagedBlock(
     withAgents,
     mcpBlock,
@@ -897,13 +1098,13 @@ When using this prompt, stay within the role above and adapt to the current repo
 `;
 }
 
-function syncCopilot(entries, targetDir = null) {
+function syncCopilot(entries, targetDir = null, wants = true) {
   const promptsDir = targetDir
     ? path.join(targetDir, ".github", "prompts")
     : path.join(home, ".github", "prompts");
-  if (!DRY_RUN) mkdirp(promptsDir);
+  if (!DRY_RUN && wants) mkdirp(promptsDir);
 
-  const writeEntries = targetDir ? entries : globalEntries(entries);
+  const writeEntries = wants ? globalEntries(entries) : [];
 
   for (const entry of writeEntries) {
     writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries), { stamp: false });
@@ -913,6 +1114,16 @@ function syncCopilot(entries, targetDir = null) {
     sweepLegacyPrefixedFiles(promptsDir, ".prompt.md", writeEntries.map((e) => `${adapterName(e)}.prompt.md`));
   }
 
+  // VS Code / Copilot agent mode reads the project's `.claude/agents/*.md`
+  // natively (Claude-format custom agents), so Construct does NOT write a
+  // separate `.github/agents/` set — doing so duplicated every agent in the
+  // picker. A pre-existing `.github/agents/` from an earlier sync is swept.
+
+  if (targetDir) {
+    const staleAgentsDir = path.join(targetDir, ".github", "agents");
+    if (!DRY_RUN && fs.existsSync(staleAgentsDir)) fs.rmSync(staleAgentsDir, { recursive: true, force: true });
+  }
+
   const instructionsPath = targetDir
     ? path.join(targetDir, ".github", "copilot-instructions.md")
     : path.join(home, ".github", "copilot-instructions.md");
@@ -928,7 +1139,7 @@ function syncCopilot(entries, targetDir = null) {
   const list = listEntries.map((e) => `- \`${adapterName(e)}\`: use \`${promptPathPrefix}/${adapterName(e)}.prompt.md\`.`).join("\n");
   const note = `## ${systemName.charAt(0).toUpperCase() + systemName.slice(1)} Agent Prompts
 
-Copilot does not expose true spawnable subagents. Use these reusable prompt profiles for role-specific passes:
+For a real multi-specialist run, Copilot agent mode calls the \`orchestration_run\` MCP tool (start the engine with \`construct dashboard\`). The prompts below are reusable role profiles for single-pass work:
 
 ${list || "(no front-door prompts to surface)"}`;
 
@@ -939,48 +1150,75 @@ ${list || "(no front-door prompts to surface)"}`;
 
 // --- VS Code adapter ---
 
-function getVSCodeSettingsPaths() {
+function getVSCodeUserDirs() {
   const platform = os.platform();
-  const candidates = [];
+  const dirs = [];
   if (platform === "darwin") {
-    candidates.push(
-      path.join(home, "Library", "Application Support", "Code", "User", "settings.json"),
-      path.join(home, "Library", "Application Support", "Code - Insiders", "User", "settings.json"),
+    dirs.push(
+      path.join(home, "Library", "Application Support", "Code", "User"),
+      path.join(home, "Library", "Application Support", "Code - Insiders", "User"),
     );
   } else if (platform === "linux") {
-    candidates.push(
-      path.join(home, ".config", "Code", "User", "settings.json"),
-      path.join(home, ".config", "Code - Insiders", "User", "settings.json"),
+    dirs.push(
+      path.join(home, ".config", "Code", "User"),
+      path.join(home, ".config", "Code - Insiders", "User"),
     );
   } else if (platform === "win32") {
     const appData = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
-    candidates.push(
-      path.join(appData, "Code", "User", "settings.json"),
-      path.join(appData, "Code - Insiders", "User", "settings.json"),
+    dirs.push(
+      path.join(appData, "Code", "User"),
+      path.join(appData, "Code - Insiders", "User"),
     );
   }
-  // settings.json present → ready to merge. settings.json absent but the
-  // VS Code User dir exists → installed without ever opening Preferences,
-  // and global sync still needs to write the MCP block. The User dir is
-  // the installation signal; bootstrap a minimal settings.json there.
+  return dirs;
+}
 
-  return candidates.filter((candidate) => {
-    if (fs.existsSync(candidate)) return true;
-    const userDir = path.dirname(candidate);
-    return fs.existsSync(userDir);
-  });
+function getVSCodeUserMcpPaths() {
+  // VS Code's "MCP: Open User Configuration" edits `<User>/mcp.json` (top-level
+  // `servers`). Global sync returns only files that already exist — per-window
+  // MCP config is never seeded, mirroring the non-polluting Cursor/OpenCode
+  // global behavior.
+
+  return getVSCodeUserDirs()
+    .map((dir) => path.join(dir, "mcp.json"))
+    .filter((file) => fs.existsSync(file));
 }
 
-function syncVSCode(targetDir = null) {
+function syncVSCode(targetDir = null, wants = true) {
   const registryMcp = registry.mcpServers ?? {};
   if (Object.keys(registryMcp).length === 0) return false;
 
   // Project scope writes a dedicated `.vscode/mcp.json` (VS Code's documented
-  // workspace MCP config). Global scope mutates the user's `settings.json`
-  // under `github.copilot.mcpServers`, preserving any non-Construct entries.
+  // workspace MCP config, top-level `servers`). Global scope merges into the
+  // user-profile `mcp.json` (the file "MCP: Open User Configuration" edits), and
+  // only when it already exists — global sync never seeds per-window MCP config.
 
   if (targetDir) {
     const mcpPath = path.join(targetDir, ".vscode", "mcp.json");
+
+    if (!wants) {
+      if (!DRY_RUN && fs.existsSync(mcpPath)) {
+        // Only delete if it matches our managed block pattern or is a simple
+        // Construct-only file. For now, simple removal of the file if it
+        // matches our expected content.
+        try {
+          const config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+          const keys = Object.keys(config?.servers ?? {});
+          const allManaged = keys.every(id => id in registryMcp);
+          if (allManaged) {
+          fs.rmSync(mcpPath, { force: true });
+          try {
+            const vscodeDir = path.dirname(mcpPath);
+            if (fs.existsSync(vscodeDir) && fs.readdirSync(vscodeDir).length === 0) {
+              fs.rmdirSync(vscodeDir);
+            }
+          } catch { /* ignore non-empty */ }
+        }
+        } catch { /* skip cleanup of unreadable file */ }
+      }
+      return false;
+    }
+
     let config = { servers: {} };
     if (fs.existsSync(mcpPath)) {
       try { config = JSON.parse(fs.readFileSync(mcpPath, "utf8")) || { servers: {} }; }
@@ -1004,50 +1242,40 @@ function syncVSCode(targetDir = null) {
     return true;
   }
 
-  const settingsPaths = getVSCodeSettingsPaths();
-  if (settingsPaths.length === 0) return false;
+  const mcpPaths = getVSCodeUserMcpPaths();
+  if (mcpPaths.length === 0) return false;
   let synced = false;
-  for (const settingsPath of settingsPaths) {
+  for (const mcpPath of mcpPaths) {
     try {
-      let settings;
-      if (fs.existsSync(settingsPath)) {
-        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-      } else {
-        // VS Code installed (User dir present) but never opened → seed an
-        // empty settings.json. Single object literal, no other keys, so
-        // a later launch of VS Code finds it valid and writes user prefs
-        // alongside.
-        settings = {};
-      }
-      if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
-      const mcpServers = settings["github.copilot.mcpServers"];
+      const config = JSON.parse(fs.readFileSync(mcpPath, "utf8")) || {};
+      if (!config.servers) config.servers = {};
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existingEntry = mcpServers[id];
+        const existingEntry = config.servers[id];
         const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
         const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
         const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
         const transportMismatch = registryWantsCommand && existingIsRemote;
         if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-        mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
-      settings["github.copilot.mcpServers"] = mcpServers;
-      if (!DRY_RUN) fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+      if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
       synced = true;
-    } catch { /* unreadable settings file */ }
+    } catch { /* unreadable mcp.json */ }
   }
   return synced;
 }
 
 // --- Cursor adapter ---
 
-function syncCursor(targetDir = null) {
+function syncCursor(targetDir = null, wants = true) {
   const registryMcp = registry.mcpServers ?? {};
   if (Object.keys(registryMcp).length === 0) return false;
 
-  const cursorMcpPath = targetDir
-    ? path.join(targetDir, ".cursor", "mcp.json")
-    : path.join(home, ".cursor", "mcp.json");
+  const cursorDir = targetDir
+    ? path.join(targetDir, ".cursor")
+    : path.join(home, ".cursor");
+  const cursorMcpPath = path.join(cursorDir, "mcp.json");
 
   // Global scope only updates Cursor's MCP config when the user has already
   // initialized `~/.cursor/mcp.json`; we don't conjure user-scope config out
@@ -1056,6 +1284,35 @@ function syncCursor(targetDir = null) {
 
   if (!targetDir && !fs.existsSync(cursorMcpPath)) return false;
 
+  if (!wants) {
+    if (!DRY_RUN && fs.existsSync(cursorMcpPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(cursorMcpPath, "utf8"));
+        const keys = Object.keys(config?.mcpServers ?? {});
+        const allManaged = keys.every(id => id in registryMcp);
+        if (allManaged) {
+          fs.rmSync(cursorMcpPath, { force: true });
+          // Also clean up rules if this was a project sync
+          if (targetDir) {
+            const rulesPath = path.join(cursorDir, "rules", "construct.mdc");
+            if (fs.existsSync(rulesPath)) fs.rmSync(rulesPath, { force: true });
+            // Remove .cursor if empty
+            try {
+              const rulesDir = path.join(cursorDir, "rules");
+              if (fs.existsSync(rulesDir) && fs.readdirSync(rulesDir).length === 0) {
+                fs.rmdirSync(rulesDir);
+              }
+              if (fs.existsSync(cursorDir) && fs.readdirSync(cursorDir).length === 0) {
+                fs.rmdirSync(cursorDir);
+              }
+            } catch { /* ignore non-empty or access errors */ }
+          }
+        }
+      } catch { /* skip cleanup of unreadable file */ }
+    }
+    return false;
+  }
+
   let config = { mcpServers: {} };
   if (fs.existsSync(cursorMcpPath)) {
     try { config = JSON.parse(fs.readFileSync(cursorMcpPath, "utf8")) || { mcpServers: {} }; }
@@ -1097,12 +1354,31 @@ function syncCursor(targetDir = null) {
 // --- OpenCode adapter ---
 
 function opencodePermissions(entry) {
-  if (entry.permissions) {
-    return Object.fromEntries(
-      Object.entries(entry.permissions).map(([k, v]) => [k, v])
-    );
+  // Review-only specialists (canEdit:false) must not modify files — honor the
+  // registry's canEdit contract here as Claude does, rather than defaulting every
+  // specialist to edit:allow.
+
+  const perms = entry.permissions
+    ? Object.fromEntries(Object.entries(entry.permissions).map(([k, v]) => [k, v]))
+    : { edit: entry.canEdit === false ? "deny" : "allow", bash: "allow" };
+
+  // The orchestrator is the primary write surface; translate its abstract
+  // bash:allow into OpenCode's scoped permission map so destructive commands are
+  // denied and remote/history rewrites prompt — the commit-approval contract
+  // enforced at the tool layer, not just in the prompt. Subagents keep the
+  // abstract grant. This scoped shape is an OpenCode translation detail and stays
+  // out of the cross-adapter registry.
+
+  if (entry.isOrchestrator && perms.bash === "allow") {
+    perms.bash = {
+      "*": "allow",
+      "rm -rf *": "deny",
+      "git push *": "ask",
+      "git push --force*": "ask",
+      "git reset --hard *": "ask",
+    };
   }
-  return { edit: "allow", bash: "allow" };
+  return perms;
 }
 
 function opencodeTaskPermissions(entry) {
@@ -1112,16 +1388,52 @@ function opencodeTaskPermissions(entry) {
   };
 }
 
-function syncOpencode(entries, targetDir = null) {
-  // Project scope writes `.opencode/config.json` (OpenCode's documented
-  // per-project config layer, which shadows `~/.config/opencode/`). Global
-  // scope writes the user-level config and only when it already exists.
+function syncOpencode(entries, targetDir = null, wants = true) {
+  // OpenCode's resolver reads `<project>/opencode.json`, `opencode.jsonc`, or
+  // `<project>/.opencode/opencode.json` — never `.opencode/config.json`. Write the
+  // namespaced `.opencode/opencode.json` so project agents + MCP actually load; a
+  // prior `.opencode/config.json` was silently ignored by the host. Global scope
+  // writes the user-level config and only when it already exists.
 
   const configPath = targetDir
-    ? path.join(targetDir, ".opencode", "config.json")
+    ? path.join(targetDir, ".opencode", "opencode.json")
     : findOpenCodeConfigPath();
+
   if (!targetDir && !fs.existsSync(configPath)) return false;
-  if (targetDir) mkdirp(path.dirname(configPath));
+
+  if (!wants) {
+    if (!DRY_RUN && fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const agentKeys = Object.keys(config?.agent ?? {});
+        const allManaged = agentKeys.every(id => id === 'construct' || (registry.specialists || []).some(s => s.name === id.replace(/^cx-/, '')));
+        if (allManaged) {
+          fs.rmSync(configPath, { force: true });
+          if (targetDir) {
+            const pluginsDir = path.join(targetDir, ".opencode", "plugins");
+            if (fs.existsSync(pluginsDir)) fs.rmSync(pluginsDir, { recursive: true, force: true });
+            try {
+              if (fs.readdirSync(path.join(targetDir, ".opencode")).length === 0) {
+                fs.rmdirSync(path.join(targetDir, ".opencode"));
+              }
+            } catch { /* ignore non-empty */ }
+          }
+        }
+      } catch { /* skip cleanup */ }
+    }
+    return false;
+  }
+
+  if (targetDir) {
+    mkdirp(path.dirname(configPath));
+    // Converge a stale `.opencode/config.json` (a path OpenCode never read) onto
+    // the canonical name — rename to preserve content, or drop it if both exist.
+    const legacyPath = path.join(targetDir, ".opencode", "config.json");
+    if (!DRY_RUN && fs.existsSync(legacyPath)) {
+      if (!fs.existsSync(configPath)) fs.renameSync(legacyPath, configPath);
+      else fs.rmSync(legacyPath);
+    }
+  }
 
   const pluginsDir = targetDir
     ? path.join(targetDir, ".opencode", "plugins")
@@ -1129,7 +1441,7 @@ function syncOpencode(entries, targetDir = null) {
   const managedPluginPath = path.join(pluginsDir, "construct-fallback.js");
   const toolkitPluginPath = path.join(root, "platforms", "opencode", "plugins", "construct-fallback.js");
 
-  const writeEntries = targetDir ? entries : globalEntries(entries);
+  const writeEntries = globalEntries(entries);
 
   const { config } = targetDir
     ? { config: fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : {} }
@@ -1247,6 +1559,14 @@ function syncOpencode(entries, targetDir = null) {
     };
   }
 
+  // Seed a cheap auxiliary model for titles and summaries when the user has not
+  // chosen one — a cost lever only. The primary `model` stays the user's choice
+  // and is never written. Global scope only; project configs inherit it.
+
+  if (!targetDir && config.small_model === undefined) {
+    config.small_model = "anthropic/claude-haiku-4-5-20251001";
+  }
+
   writeOpenCodeConfig(config, configPath);
 
   const sourcePluginsDir = path.join(root, "platforms", "opencode", "plugins");
@@ -1427,38 +1747,38 @@ if (COMPRESS_PERSONAS) {
 acquireLock();
 try {
   if (projectDir) {
-    syncClaude(entries, projectDir);
-    syncCodex(entries, projectDir);
-    syncCopilot(entries, projectDir);
-    const opencodeOk = syncOpencode(entries, projectDir);
-    const vscodeOk = syncVSCode(projectDir);
-    const cursorOk = syncCursor(projectDir);
-    const cmdCount = syncCommands(projectDir);
-    const skillCount = syncSkills(projectDir);
+    syncClaude(entries, projectDir, wantsHost("claude"));
+    syncCodex(entries, projectDir, wantsHost("codex"));
+    syncCopilot(entries, projectDir, wantsHost("copilot"));
+    const opencodeOk = syncOpencode(entries, projectDir, wantsHost("opencode"));
+    const vscodeOk = syncVSCode(projectDir, wantsHost("vscode"));
+    const cursorOk = syncCursor(projectDir, wantsHost("cursor"));
+    const cmdCount = wantsHost("claude") ? syncCommands(projectDir) : 0;
+    const skillCount = wantsHost("claude") ? syncSkills(projectDir) : 0;
 
     if (DRY_RUN) {
       printDryRunDiff();
     } else {
       commitStaging();
       const targets = [
-        "Claude Code",
-        "Codex",
-        "Copilot",
+        wantsHost("claude") && "Claude Code",
+        wantsHost("codex") && "Codex",
+        wantsHost("copilot") && "Copilot",
         opencodeOk && "OpenCode",
         vscodeOk && "VS Code",
         cursorOk && "Cursor",
       ].filter(Boolean).join(", ");
-      console.log(`Synced ${entries.length} agents + ${cmdCount} commands + ${skillCount} skills to ${path.relative(process.cwd(), projectDir) || "."} (project mode → ${targets}).`);
+      summary(`Synced ${entries.length} agents + ${cmdCount} commands + ${skillCount} skills to ${path.relative(process.cwd(), projectDir) || "."} (project mode → ${targets}).`);
     }
   } else {
     const personaCount = entries.filter((e) => e.isOrchestrator).length;
 
-    syncCodex(entries);
-    syncClaude(entries);
-    syncCopilot(entries);
-    const opencodeOk = syncOpencode(entries);
-    const vscodeOk = syncVSCode();
-    const cursorOk = syncCursor();
+    syncCodex(entries, null, wantsHost("codex"));
+    syncClaude(entries, null, wantsHost("claude"));
+    syncCopilot(entries, null, wantsHost("copilot"));
+    const opencodeOk = syncOpencode(entries, null, wantsHost("opencode"));
+    const vscodeOk = syncVSCode(null, wantsHost("vscode"));
+    const cursorOk = syncCursor(null, wantsHost("cursor"));
     syncCommands();
     syncSkills();
 
@@ -1474,11 +1794,11 @@ try {
         vscodeOk && "VS Code",
         cursorOk && "Cursor",
       ].filter(Boolean).join(", ");
-      console.log(`Synced ${personaCount} front-door agent to global scope (${targets}). Specialists, commands, and skills are project-only — run \`construct init\` inside a project to scaffold them.`);
+      summary(`Synced ${personaCount} front-door agent to global scope (${targets}). Specialists, commands, and skills are project-only — run \`construct init\` inside a project to scaffold them.`);
 
       const completionsDir = generateCompletions();
       if (completionsDir) {
-        console.log(`Completions updated → ${completionsDir}`);
+        summary(`Completions updated → ${completionsDir}`);
       }
     }
   }