@geraldmaron/construct 1.4.1 → 1.5.0

package/scripts/sync-specialists.mjs

@@ -10,11 +10,16 @@
  *       `orchestrator` entry). Specialists, slash commands, and skills do NOT
  *       land at global scope — they are project content.
  *     - Plus the hook installer in `~/.claude/settings.json`, which has to be
- *       global so hooks fire in every Claude Code session.
+ *       global so hooks fire in every Claude Code session. MCP server
+ *       definitions are a separate file: Claude Code reads user-scope MCP
+ *       servers from the top-level `mcpServers` object in `~/.claude.json`,
+ *       not from settings.json (construct-ranh).
  *
  *   Project scope (`<project>/.claude/`, `<project>/.codex/`, `<project>/.github/`, …)
  *     - `construct` front door only (Single Front Door), slash commands, skills, MCP
  *       wiring. Specialists dispatch internally via orchestration MCP tools.
+ *       MCP server definitions land in `<project>/.mcp.json` (Claude Code's
+ *       documented project scope), not `.claude/settings.json`.
  *
  * Flags:
  *   --dry-run             Print a diff of what would change without writing anything.
@@ -47,6 +52,7 @@ import {
 import { findOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig, ensureOpenRouterProviderAuth } from "../lib/opencode-config.mjs";
 import { HEAVY_EXTERNAL_MCP_IDS, LOCAL_SURFACE_MODES, decideTrim, isLocalModel } from "../lib/mcp/tool-budget.mjs";
 import { emitCursorRules } from "../lib/rules-delivery.mjs";
+import { memoryPort } from "../lib/home-namespace.mjs";
 import { resolvePromptContract, readPromptBody } from "../lib/prompt-composer.js";
 import { renderPersonaForTier } from "../lib/persona-sections.mjs";
 import { getModelVerdict } from "../lib/ollama/capability-store.mjs";
@@ -117,7 +123,6 @@ function unifiedToLegacyRegistry(unified) {
   };
 }
 
-clearCache();
 clearCache();
 const unified = loadRegistry({ rootDir: root });
 const registry = unifiedToLegacyRegistry(unified);
@@ -454,7 +459,7 @@ const standardConstructTools = [
 // agent's tools list or the call is blocked, leaving the orchestrator unable to route.
 // Single source of truth so every host's orchestrator grant stays in parity.
 
-const ORCHESTRATOR_DISPATCH_TOOLS = ["orchestration_policy", "orchestration_run"];
+const ORCHESTRATOR_DISPATCH_TOOLS = ["orchestration_policy", "orchestration_run", "orchestration_delegation_next"];
 const managedStart = `# BEGIN ${systemName.toUpperCase()} AGENTS`;
 const managedEnd = `# END ${systemName.toUpperCase()} AGENTS`;
 const mdManagedStart = `<!-- BEGIN ${systemName.toUpperCase()} AGENTS -->`;
@@ -486,10 +491,17 @@ function resolveArgs(args) {
     : a));
 }
 
-function resolveTemplateStrings(value) {
+// A secret-suffixed placeholder (TOKEN/SECRET/API_KEY/PUBLIC_KEY/PRIVATE_KEY) always
+// resolves to OpenCode's `{env:NAME}` reference form, even when the named var is set
+// in process.env, so a live credential never lands in a generated config file. This
+// guard runs before the general env lookup below, mirroring the buildLocalEnvironment
+// value->ref flip in lib/mcp-platform-config.mjs. GITHUB_TOKEN is an intentional alias
+// that still materializes GITHUB_PERSONAL_ACCESS_TOKEN's value: that branch stays ahead
+// of the suffix guard since it targets a different source var, not GITHUB_TOKEN itself.
+
+export function resolveTemplateStrings(value) {
   if (typeof value === "string") {
     return value.replace(/__([A-Z0-9_]+)__/g, (_, name) => {
-      if (process.env[name] !== undefined && process.env[name] !== "") return process.env[name];
       if (name === "CX_TOOLKIT_DIR") return root;
       if (name === "MEMORY_PORT") return process.env.MEMORY_PORT || "8765";
       if (name === "CONSTRUCT_MEMORY_BRIDGE_URL") {
@@ -501,6 +513,7 @@ function resolveTemplateStrings(value) {
       if (/(?:TOKEN|SECRET|API_KEY|PUBLIC_KEY|PRIVATE_KEY)$/.test(name)) {
         return `{env:${name}}`;
       }
+      if (process.env[name] !== undefined && process.env[name] !== "") return process.env[name];
       return `__${name}__`;
     });
   }
@@ -773,13 +786,13 @@ function orchestrationMicroPrompt(platform) {
     `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
     `  call ${policyTool} { "request": "add rate limiting to the API" }\n` +
     `If the route is focused/orchestrated specialist work, call \`${runTool}\` with the same request. If the route suggests a workflow such as \`research-synthesis\`, pass it as \`workflow_type\`. Do not narrate completed research unless \`${runTool}\` or evidence tools actually ran.\n\n` +
-    `If a request needs a capability you lack — live web/network access, external data, code execution — do not refuse or tell the user to run it themselves. Route it via \`${runTool}\` to the specialist that holds the capability (web access lives with the researcher), or ask one clarifying question when the target is ambiguous.`
+    `If a request needs a capability you lack — live web/network access, external data, code execution — route it via \`${runTool}\` to the specialist that holds it (the researcher performs live web retrieval when a web path is available). Do not tell the user to run it themselves. But if \`${runTool}\` reports the capability was unavailable (degraded with \`capability-unavailable\`, or a prepare-only result), say plainly it could not be reached and return an insufficient-evidence result — never fabricate URLs, dates, quotes, or citations. Ask one clarifying question when the target is ambiguous.`
   );
 }
 
 // Directive for the local editor agent (construct-local). It executes bounded work on
 // the cheap local model and hands planning/reasoning back to the construct architect —
-// the aider architect/editor split. Kept short: a small model must actually obey it.
+// a cheap-editor/capable-architect split. Kept short: a small model must actually obey it.
 
 const LOCAL_EDITOR_DIRECTIVE =
   `You are a focused execution agent running on a local model, dispatched by construct to do one bounded job. Do well-scoped edits for the current task and verify them; make the smallest correct change, never a broad rewrite.\n` +
@@ -1017,7 +1030,7 @@ ${buildPrompt(entry, allEntries, "claude")}
  * Rewrite the home-mode hook command pattern
  *   node "$HOME/.config/construct/lib/hooks/<name>.mjs"
  * into the project-portable form
- *   node "${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook <name>
+ *   node "${CLAUDE_PROJECT_DIR:-<absRoot>}/.construct/run.mjs" hook <name>
  * so the resulting settings.json works on any clone where the project ships
  * the .construct/ launcher (committed by `npm install`'s postinstall or by
  * `construct init`). The launcher resolves Construct via node_modules → npx
@@ -1025,21 +1038,29 @@ ${buildPrompt(entry, allEntries, "claude")}
  * works for non-Node ecosystems too. Other commands (inline node -e
  * snippets, npx block-no-verify@…) are left untouched.
  *
- * The `${CLAUDE_PROJECT_DIR:-.}` anchor matters: Claude Code invokes hooks with
+ * The `${CLAUDE_PROJECT_DIR:-<absRoot>}` anchor matters: hosts invoke hooks with
  * a working directory that is not guaranteed to be the project root (observed:
- * $HOME), and a bare relative `.construct/run.mjs` then fails with MODULE_NOT_FOUND
- * at node:internal/modules/cjs/loader. CLAUDE_PROJECT_DIR is the project root Claude
- * Code exports to every hook (same var lib/hooks/*.mjs already read); the `:-.`
- * fallback preserves the prior relative behavior wherever the var is unset.
+ * $HOME, a `cd`-ed scratch dir), and a bare relative `.construct/run.mjs` then
+ * fails with MODULE_NOT_FOUND at node:internal/modules/cjs/loader — before any
+ * code in run.mjs can execute, so the shim cannot self-correct. CLAUDE_PROJECT_DIR
+ * is the project root Claude Code exports to every hook (same var lib/hooks/*.mjs
+ * already read) and stays correct if the checkout moves; the fallback is the
+ * absolute project root baked at sync time, so tools that do not export
+ * CLAUDE_PROJECT_DIR (or any host with a drifted cwd) still resolve the launcher.
+ * `.claude/settings.json` is gitignored and regenerated per machine by
+ * `construct sync`, so an absolute fallback is machine-correct without leaking a
+ * shared path. The prior `:-.` fallback was cwd-relative and broke on any drift.
  */
-function makeHooksPortable(hooksJson) {
+function makeHooksPortable(hooksJson, projectRoot) {
+  const anchor = `\${CLAUDE_PROJECT_DIR:-${path.resolve(projectRoot)}}`;
+
   // Operate on the in-memory object so we don't fight JSON string escaping.
   const replaceCommand = (cmd) => {
     if (typeof cmd !== 'string') return cmd;
     const m = cmd.match(/^node\s+"?\$HOME\/\.config\/construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
     if (!m) return cmd;
     const [, name, rest] = m;
-    return `node "\${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook ${name}${rest ? ' ' + rest.trim() : ''}`;
+    return `node "${anchor}/.construct/run.mjs" hook ${name}${rest ? ' ' + rest.trim() : ''}`;
   };
 
   const walk = (node) => {
@@ -1092,14 +1113,9 @@ function syncGlobalClaudeMcpServers(settings, registryMcp) {
   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);
+    const desiredEntry = buildClaudeMcpEntry(id, mcpDef, process.env);
+    if (!needsRefresh(existingEntry, desiredEntry, { root })) continue;
+    settings.mcpServers[id] = desiredEntry;
   }
 }
 
@@ -1108,6 +1124,12 @@ function syncGlobalClaudeMcpServers(settings, registryMcp) {
  * with hook commands rewritten to be path-relative to whatever Construct
  * install the project carries. Merges into an existing settings.json
  * if one is already in the project; otherwise creates a fresh one.
+ *
+ * Carries hooks and permissions only — Claude Code does not read MCP server
+ * definitions from settings.json at any scope (confirmed against
+ * code.claude.com/docs/en/mcp's installation-scopes table and live `claude
+ * mcp list` repro, construct-ranh). Project-scope MCP wiring is
+ * writeProjectMcpJson's job, targeting `.mcp.json`.
  */
 function writeProjectClaudeSettings(targetDir) {
   const settingsPath = path.join(targetDir, ".claude", "settings.json");
@@ -1121,17 +1143,42 @@ function writeProjectClaudeSettings(targetDir) {
     : {};
 
   if (template.hooks) {
-    existing.hooks = JSON.parse(makeHooksPortable(template.hooks));
+    existing.hooks = JSON.parse(makeHooksPortable(template.hooks, targetDir));
   }
   if (template.permissions) {
     existing.permissions ??= template.permissions;
   }
-  if (template.mcpServers) {
-    existing.mcpServers ??= {};
-    for (const [id, mcpDef] of Object.entries(template.mcpServers)) {
-      if (existing.mcpServers[id]) continue;
-      if (!PROJECT_DEFAULT_MCP_IDS.has(id)) continue;
-      existing.mcpServers[id] = mcpDef;
+
+  if (DRY_RUN) return;
+  mkdirp(path.dirname(settingsPath));
+  writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n");
+}
+
+/**
+ * Materialise project-scope MCP wiring at `.mcp.json` in the project root —
+ * the scope Claude Code documents for team-shared, version-controlled MCP
+ * server definitions (settings.json only carries policy keys and hooks).
+ * Merges into an existing `.mcp.json` if the project already has one;
+ * existing entries win so manual edits or a prior `claude mcp add --scope
+ * project` stick.
+ */
+function writeProjectMcpJson(targetDir) {
+  const mcpJsonPath = path.join(targetDir, ".mcp.json");
+  const templatePath = path.join(root, "platforms", "claude", "settings.template.json");
+
+  const existing = fs.existsSync(mcpJsonPath)
+    ? JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"))
+    : {};
+  existing.mcpServers ??= {};
+
+  if (fs.existsSync(templatePath)) {
+    const template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+    if (template.mcpServers) {
+      for (const [id, mcpDef] of Object.entries(template.mcpServers)) {
+        if (existing.mcpServers[id]) continue;
+        if (!PROJECT_DEFAULT_MCP_IDS.has(id)) continue;
+        existing.mcpServers[id] = mcpDef;
+      }
     }
   }
 
@@ -1140,19 +1187,23 @@ function writeProjectClaudeSettings(targetDir) {
   // 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.
+  // registry on top of the template seed via needsRefresh(): an existing entry
+  // wins as long as it still matches the registry (env keys, pinned version,
+  // transport, toolkit path), so a manual opt-in sticks but drift — a missing
+  // registry env key, a stale pinned version — gets corrected.
   const registryMcp = scopedManagedMcpDefs({ projectScope: true });
-  existing.mcpServers ??= {};
   for (const [id, mcpDef] of Object.entries(registryMcp)) {
-    if (existing.mcpServers[id]) continue;
     if (!PROJECT_DEFAULT_MCP_IDS.has(id)) continue;
-    existing.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+    const existingEntry = existing.mcpServers[id];
+    const desiredEntry = buildClaudeMcpEntry(id, mcpDef, process.env);
+    if (!needsRefresh(existingEntry, desiredEntry, { root })) continue;
+    existing.mcpServers[id] = desiredEntry;
   }
+  reconcileStaleManagedEntries(existing.mcpServers, { registryMcp, rebuildEntry: (id, def) => buildClaudeMcpEntry(id, def, process.env) });
 
   if (DRY_RUN) return;
-  mkdirp(path.dirname(settingsPath));
-  writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n");
+  mkdirp(path.dirname(mcpJsonPath));
+  writeFile(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n");
 }
 
 function syncClaude(entries, targetDir = null, wants = true) {
@@ -1183,6 +1234,7 @@ function syncClaude(entries, targetDir = null, wants = true) {
 
   if (targetDir) {
     writeProjectClaudeSettings(targetDir);
+    writeProjectMcpJson(targetDir);
     return;
   }
 
@@ -1200,7 +1252,7 @@ ${personaList}
     // User-managed file with our managed-block carved out — never doc-stamp.
     writeFile(claudeMdPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd), { stamp: false });
 
-    // Sync MCP servers into ~/.claude/settings.json if it exists
+    // Sync hooks into ~/.claude/settings.json if it exists
     const claudeSettingsPath = path.join(home, ".claude", "settings.json");
     if (fs.existsSync(claudeSettingsPath)) {
       const settings = JSON.parse(fs.readFileSync(claudeSettingsPath, "utf8"));
@@ -1220,10 +1272,22 @@ ${personaList}
           settings.hooks = JSON.parse(hookStr);
         }
       }
-      const registryMcp = scopedManagedMcpDefs({ projectScope: false });
-      syncGlobalClaudeMcpServers(settings, registryMcp);
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
     }
+
+    // Sync user-scope MCP servers into ~/.claude.json's top-level `mcpServers`
+    // — Claude Code does not read MCP server definitions from settings.json at
+    // any scope (confirmed against code.claude.com/docs/en/mcp and live `claude
+    // mcp list` repro, construct-ranh). Gated on the file already existing, same
+    // as the hooks sync above: only write into Claude Code's own state file for
+    // a user who has actually run the CLI at least once.
+    const claudeUserConfigPath = path.join(home, ".claude.json");
+    if (fs.existsSync(claudeUserConfigPath)) {
+      const claudeUserConfig = JSON.parse(fs.readFileSync(claudeUserConfigPath, "utf8"));
+      const registryMcp = scopedManagedMcpDefs({ projectScope: false });
+      syncGlobalClaudeMcpServers(claudeUserConfig, registryMcp);
+      if (!DRY_RUN) fs.writeFileSync(claudeUserConfigPath, JSON.stringify(claudeUserConfig, null, 2) + "\n");
+    }
   }
 }
 
@@ -1368,15 +1432,14 @@ When using this prompt, stay within the role above and adapt to the current repo
 // recognized here, so the orchestrator needs its own VS Code agent or it lists
 // in the picker with no usable tools.
 
-const COPILOT_AGENT_TOOLS = [
-  "construct-mcp/*",
-  "web/fetch",
-  "web/githubRepo",
+export const COPILOT_AGENT_TOOLS = [
+  "construct-mcp/orchestration_policy",
+  "construct-mcp/orchestration_run",
+  "construct-mcp/orchestration_readiness",
   "search/codebase",
   "search/usages",
   "search/fileSearch",
   "read/problems",
-  "edit/editFiles",
 ];
 
 function copilotAgentFile(entry, allEntries) {
@@ -1486,6 +1549,86 @@ function getVSCodeUserMcpPaths() {
     .filter((file) => fs.existsSync(file));
 }
 
+// One comparator every host dialect (global Claude, project Claude, VS Code,
+// Cursor, OpenCode) calls instead of a bespoke preserve/refresh predicate per
+// surface — so the construct-mcp telemetry env passthrough and a pinned package
+// version converge identically everywhere rather than drifting per host.
+// needsRefresh() is the one question every dialect asks: does this host's
+// existing entry still match what the registry wants, across placeholder
+// resolution, transport, registry-declared env keys, pinned package versions,
+// and toolkit path. Callers
+// build the desired entry with their own host-specific builder (buildClaudeMcpEntry
+// / buildOpenCodeMcpEntry) first — both a Claude-shape entry (`args`/`env`) and an
+// OpenCode-shape entry (`command` array with the binary as element 0 / `environment`)
+// are normalized here so one comparator serves both shapes.
+
+function entryArgs(entry) {
+  if (Array.isArray(entry?.args)) return entry.args;
+  if (Array.isArray(entry?.command)) return entry.command;
+  return [];
+}
+
+function entryEnv(entry) {
+  return entry?.env ?? entry?.environment ?? {};
+}
+
+function entryIsRemote(entry) {
+  return entry?.type === "http" || entry?.type === "remote";
+}
+
+// A registry env block that declares a key (e.g. the construct-mcp telemetry
+// passthrough) must be present on the host entry by name; the host-resolved
+// value differs per host (a literal, a `${VAR}`, a `{env:VAR}`) so only key
+// presence is compared. Absence — including "no env block at all" — means stale.
+
+function envKeysMissing(existingEnv, desiredEnv) {
+  const desiredKeys = Object.keys(desiredEnv ?? {});
+  if (desiredKeys.length === 0) return false;
+  const existingKeys = new Set(Object.keys(existingEnv ?? {}));
+  return desiredKeys.some((key) => !existingKeys.has(key));
+}
+
+// A version-pinned package arg (`@scope/name@version`, including the `@latest`
+// anti-pin) is compared as an exact string: if the registry's desired pin string
+// is not present verbatim anywhere in the existing args/command, the host is
+// carrying a different (or floating) version and must be refreshed. Unversioned
+// packages are not compared — pinning is opt-in per package via the catalog.
+
+function argsVersionDiffers(existingArgs, desiredArgs) {
+  const isPinned = (arg) => typeof arg === "string" && /^@[^/]+\/[^@]+@[\w.-]+$/.test(arg);
+  const desiredPins = (desiredArgs ?? []).filter(isPinned);
+  if (desiredPins.length === 0) return false;
+  const existingPins = new Set((existingArgs ?? []).filter(isPinned));
+  return desiredPins.some((pin) => !existingPins.has(pin));
+}
+
+export function needsRefresh(existingEntry, desiredEntry, { root } = {}) {
+  if (!existingEntry) return true;
+  if (JSON.stringify(existingEntry).includes("__")) return true;
+  if (!entryIsRemote(desiredEntry) && entryIsRemote(existingEntry)) return true;
+  if (envKeysMissing(entryEnv(existingEntry), entryEnv(desiredEntry))) return true;
+  if (argsVersionDiffers(entryArgs(existingEntry), entryArgs(desiredEntry))) return true;
+  if (root && mcpEntryPointsOutsideToolkit({ args: entryArgs(existingEntry) }, root)) return true;
+  if (desiredEntry?.cwd !== undefined && existingEntry.cwd !== desiredEntry.cwd) return true;
+  return false;
+}
+
+// VS Code's orchestration tools default their working directory to the SERVER
+// process's cwd, which is host-launch-dependent (construct-6y6w.9) — the same
+// tool call can read/write a different project depending on which host
+// launched the server and from where. VS Code resolves `${workspaceFolder}`
+// against the workspace that owns the `.vscode/mcp.json` the entry lives in,
+// so pinning it there removes the ambiguity for exactly the host that has a
+// single fixed workspace folder per config file. A remote/http entry has no
+// process cwd to pin and is left untouched.
+
+const VSCODE_WORKSPACE_CWD = "${workspaceFolder}";
+
+function withVscodeWorkspaceCwd(entry) {
+  if (!entry || entry.type === "http" || entry.type === "remote") return entry;
+  return { ...entry, cwd: VSCODE_WORKSPACE_CWD };
+}
+
 // A merged mcp.json preserves existing entries so user customizations survive a
 // re-sync. A construct-owned server path is a fully-resolved, non-placeholder
 // path, so the preserve rule keeps it even when it points at a different toolkit
@@ -1493,34 +1636,119 @@ function getVSCodeUserMcpPaths() {
 // exist. Treat a construct toolkit path outside the current root as stale so the
 // sync refreshes it; user-owned servers carry no lib/mcp toolkit path and stay.
 
+// Claude/VS Code/Cursor entries carry the script path in `args`; OpenCode's local
+// entry shape (buildOpenCodeMcpEntry) instead carries `command: [bin, ...args]`.
+// Falling back to `command` when `args` is absent lets this one predicate serve
+// both shapes without OpenCode's caller having to reshape the entry first.
+
 export function mcpEntryPointsOutsideToolkit(entry, root) {
-  const args = Array.isArray(entry?.args) ? entry.args : [];
-  return args.some(
-    (arg) => typeof arg === "string"
-      && /\/lib\/mcp\/[a-z0-9-]+\.mjs$/.test(arg)
-      && !arg.startsWith(`${root}/`),
-  );
+  const args = Array.isArray(entry?.args) ? entry.args : (Array.isArray(entry?.command) ? entry.command : []);
+  return args.some((arg) => {
+    if (typeof arg !== "string") return false;
+    const normalArg = arg.replace(/\\/g, "/");
+    const normalRoot = root.replace(/\\/g, "/");
+    return /\/lib\/mcp\/[a-z0-9-]+\.mjs$/i.test(normalArg)
+      && !normalArg.startsWith(`${normalRoot}/`);
+  });
 }
 
-// VS Code scans both `.github/agents` and `.claude/agents`, so the orchestrator
-// would list twice — once with VS Code tools (.github/agents) and once with
-// Claude tool names VS Code ignores (.claude/agents). `chat.agentFilesLocations`
-// is the documented lever to pin the scan; its power over the built-in
-// `.claude/agents` compatibility scan is version-dependent, so this is a
-// best-effort hint, not a guarantee. Merge only into a strictly-parseable file
-// and never overwrite an existing choice, so a commented (JSONC) or
-// user-customized settings.json is left untouched.
+// The desired-set loop only visits registryMcp ids, so a construct-managed entry
+// present in the host config but OUTSIDE the current sync set (an optional server
+// like `memory` the user opted into) is never revisited — a stale toolkit path in it
+// becomes immortal. This second pass rewrites those in place: the double guard (id is
+// construct-managed AND its path points outside the toolkit) never touches an
+// unmanaged/user entry, and rewriting to a path under root makes it idempotent (a
+// second run finds nothing stale). Rewrite, never delete, never seed — opt-in sticks.
+
+// A memory entry can be stale without pointing outside the toolkit: pinned to the dead
+// legacy port, to a port other than the one currently allocated, or to a bridge script
+// path that does not exist (an old checkout). Any of these means the entry cannot reach
+// the running memory server — the split-brain — so it must be rewritten to the current
+// port and path.
+
+function memoryEntryIsStale(entry) {
+  if (!entry) return false;
+  const want = String(memoryPort(process.env));
+  const portOf = (s) => String(s || "").match(/:(\d+)\/?$/)?.[1];
+  const bridgeUrlEnv = entry.env?.CONSTRUCT_MEMORY_BRIDGE_URL ?? entry.environment?.CONSTRUCT_MEMORY_BRIDGE_URL;
+  const ports = [portOf(entry.url), portOf(bridgeUrlEnv)];
+  const portStale = ports.some((p) => p && p !== want);
+  const commandArgs = Array.isArray(entry.args) ? entry.args : (Array.isArray(entry.command) ? entry.command : []);
+  const scriptArg = commandArgs.find((a) => typeof a === "string" && a.endsWith("memory-bridge.mjs"));
+  const pathMissing = scriptArg ? !fs.existsSync(scriptArg) : false;
+  return portStale || pathMissing;
+}
+
+// OpenCode keys config.mcp by getOpenCodeMcpId(id), not the catalog id (identity
+// today, but the indirection exists for a future per-host rename) — so the host
+// config key this loop sees is not always the id `registryMcp`/`managedMcpDefs()`
+// know. `mapId` translates the host key back to the catalog id for the ownership
+// and sync-set checks; the write-back stays keyed on the original host key so no
+// entry is renamed, only rewritten in place.
+
+export function reconcileStaleManagedEntries(configMap, { registryMcp, rebuildEntry, mapId = (key) => key }) {
+  if (!configMap) return false;
+  const managed = managedMcpDefs();
+  let changed = false;
+  for (const [key, entry] of Object.entries(configMap)) {
+    const catalogId = mapId(key);
+    if (catalogId in registryMcp) continue;
+    const mcpDef = managed[catalogId];
+    if (!mcpDef) continue;
+    const stale = mcpEntryPointsOutsideToolkit(entry, root) || (catalogId === "memory" && memoryEntryIsStale(entry));
+    if (!stale) continue;
+    configMap[key] = rebuildEntry(catalogId, mcpDef);
+    changed = true;
+  }
+  return changed;
+}
+
+// Workspace defaults Construct manages for VS Code chat. `chat.agentFilesLocations`
+// pins the agent scan to `.github/agents` so the orchestrator does not list twice
+// (VS Code also scans `.claude/agents`, whose Claude tool names it ignores); its
+// power over that built-in compatibility scan is version-dependent, so it is a
+// best-effort hint. `chat.mcp.autostart` (VS Code ≥1.105, string enum) set to
+// `always` eager-starts MCP servers so `construct-mcp` is live without a manual
+// Start each session — the orchestrator's first move is an MCP call, so a dormant
+// server otherwise reads as "enable the MCP server". Neither removes the one-time
+// per-developer MCP trust grant, which VS Code stores locally, not in committed
+// config. Each key is applied only when unset, and a settings.json that is not
+// strict JSON (commented/JSONC or user-customized) is left untouched.
+
+const VSCODE_MANAGED_SETTINGS = {
+  "chat.agentFilesLocations": { ".github/agents": true, ".claude/agents": false },
+  "chat.mcp.autoStart": "always",
+};
+
+// Strip full-line JSONC comments (`// …`) and trailing commas before JSON.parse.
+// Handles the common VS Code settings.json patterns (line comments, trailing commas);
+// does not attempt to handle inline comments after values.
+
+function parseJsoncContent(text) {
+  const stripped = text
+    .split('\n')
+    .map((line) => {
+      const t = line.trimStart();
+      return t.startsWith('//') ? '' : line;
+    })
+    .join('\n')
+    .replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(stripped);
+}
 
-export function pinVscodeAgentLocations(targetDir) {
+export function pinVscodeChatSettings(targetDir) {
   if (DRY_RUN) return;
   const settingsPath = path.join(targetDir, ".vscode", "settings.json");
   let settings = {};
   if (fs.existsSync(settingsPath)) {
-    try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")) || {}; }
+    try { settings = parseJsoncContent(fs.readFileSync(settingsPath, "utf8")) || {}; }
     catch { return; }
   }
-  if (settings["chat.agentFilesLocations"]) return;
-  settings["chat.agentFilesLocations"] = { ".github/agents": true, ".claude/agents": false };
+  let changed = false;
+  for (const [key, value] of Object.entries(VSCODE_MANAGED_SETTINGS)) {
+    if (settings[key] === undefined) { settings[key] = value; changed = true; }
+  }
+  if (!changed) return;
   mkdirp(path.dirname(settingsPath));
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
@@ -1568,20 +1796,16 @@ function syncVSCode(targetDir = null, wants = true) {
     if (!config.servers) config.servers = {};
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
       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;
-      const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
-      if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
-      config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
+      const desiredEntry = withVscodeWorkspaceCwd(buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" }));
+      if (!needsRefresh(existingEntry, desiredEntry, { root })) continue;
+      config.servers[id] = desiredEntry;
     }
+    reconcileStaleManagedEntries(config.servers, { registryMcp, rebuildEntry: (id, def) => withVscodeWorkspaceCwd(buildClaudeMcpEntry(id, def, process.env, { host: "vscode" })) });
     if (!DRY_RUN) {
       mkdirp(path.dirname(mcpPath));
       fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
     }
-    pinVscodeAgentLocations(targetDir);
+    pinVscodeChatSettings(targetDir);
     return true;
   }
 
@@ -1594,14 +1818,9 @@ function syncVSCode(targetDir = null, wants = true) {
       if (!config.servers) config.servers = {};
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
         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;
-        const staleToolkitPath = mcpEntryPointsOutsideToolkit(existingEntry, root);
-        if (existingEntry && !hasPlaceholder && !transportMismatch && !staleToolkitPath) continue;
-        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
+        const desiredEntry = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
+        if (!needsRefresh(existingEntry, desiredEntry, { root })) continue;
+        config.servers[id] = desiredEntry;
       }
       if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
       synced = true;
@@ -1665,14 +1884,11 @@ function syncCursor(targetDir = null, wants = true) {
   if (!config.mcpServers) config.mcpServers = {};
   for (const [id, mcpDef] of Object.entries(registryMcp)) {
     const existingEntry = config.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;
-    config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
+    const desiredEntry = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
+    if (!needsRefresh(existingEntry, desiredEntry, { root })) continue;
+    config.mcpServers[id] = desiredEntry;
   }
+  reconcileStaleManagedEntries(config.mcpServers, { registryMcp, rebuildEntry: (id, def) => buildClaudeMcpEntry(id, def, process.env, { host: "vscode" }) });
   if (!DRY_RUN) {
     mkdirp(path.dirname(cursorMcpPath));
     fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
@@ -1944,18 +2160,32 @@ function syncOpencode(entries, targetDir = null, wants = true) {
       // any remote/http memory entry must be rewritten when the registry
       // defines a command-based bridge.
       const existingEntry = config.mcp[openCodeId];
-      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
-      const existingIsRemote = existingEntry && (existingEntry.type === 'remote' || existingEntry.type === 'http');
-      const transportMismatch = registryWantsCommand && existingIsRemote;
+      const desiredEntry = buildOpenCodeMcpEntry(id, mcpDef, process.env).entry;
 
-      const existing = JSON.stringify(existingEntry ?? "");
-      const hasPlaceholder = existing.includes("__");
+      // The registry's own args can carry an unresolved `__NAME__` template (a
+      // secret var not yet set in this environment); needsRefresh only inspects
+      // built entries, so a still-templated registry def is checked separately
+      // and always wins a refresh once the var resolves.
       const argsHaveTemplates = (mcpDef.args ?? []).some((a) => typeof a === 'string' && a.includes('__'));
-      if (!existingEntry || hasPlaceholder || argsHaveTemplates || transportMismatch) {
-        config.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcpDef, process.env).entry;
+      if (argsHaveTemplates || needsRefresh(existingEntry, desiredEntry, { root })) {
+        config.mcp[openCodeId] = desiredEntry;
       }
     }
 
+    // The sync-set loop above only visits `registryMcp` ids, so a managed-but-optional
+    // entry (e.g. `memory` in project scope) with a stale toolkit path is never
+    // revisited here either — the same immortal-entry gap fixed for VS Code/Cursor/
+    // Claude project (construct-6y6w.1). `getOpenCodeMcpId` keys config.mcp by the
+    // host id rather than the catalog id, so map it back before checking ownership.
+    const catalogIdForOpenCodeKey = new Map(
+      Object.keys(managedMcpDefs()).map((catalogId) => [getOpenCodeMcpId(catalogId), catalogId]),
+    );
+    reconcileStaleManagedEntries(config.mcp, {
+      registryMcp,
+      mapId: (key) => catalogIdForOpenCodeKey.get(key) ?? key,
+      rebuildEntry: (catalogId, def) => buildOpenCodeMcpEntry(catalogId, def, process.env).entry,
+    });
+
     // Heavy external MCP servers serialize a measured ~37k tokens of tool schema
     // into EVERY agent's request — github ~30k alone (fixtures 2026-06-22) —
     // agent's request — including the built-in Build/Plan agents the per-agent
@@ -2033,7 +2263,7 @@ function syncOpencode(entries, targetDir = null, wants = true) {
     };
   }
 
-  // Hybrid split (aider architect/editor). When the fast tier is a LOCAL model, emit a
+  // Hybrid split (cheap local editor, capable architect). When the fast tier is a LOCAL model, emit a
   // narrow `construct-local` editor: it does bounded edits on a cheap local model and hands
   // planning/reasoning back to `construct` (the architect, which stays on the user's chosen
   // model — we never pin it). The editor's model is NOT the generic fast-tier default
@@ -2096,17 +2326,17 @@ function syncOpencode(entries, targetDir = null, wants = true) {
     delete config.model;
   }
 
-  // OpenCode's built-in helper agents drive session naming, summaries, and
-  // compaction. Keep them on a stronger auxiliary model so those surfaces do not
-  // inherit the main chat model's selection history or a low-end coder default.
-  const auxiliaryModel = resolvedModels.reasoning || resolvedModels.standard || resolvedModels.fast;
-  if (auxiliaryModel) {
-    for (const key of ["title", "summary", "compaction"]) {
-      config.agent[key] = {
-        ...(config.agent[key] && typeof config.agent[key] === "object" ? config.agent[key] : {}),
-        model: auxiliaryModel,
-      };
-    }
+  // OpenCode's built-in helper agents (session naming, summaries, compaction)
+  // must follow the host's live routing — an absolute model pin here made
+  // compaction call a provider the user had no key/credits for, failing hard
+  // even though a working model was selected for the session. Keep the entries
+  // present (hosts and tests rely on them existing) but strip any model pin a
+  // previous sync wrote, whether the old weak coder default or a strong tier
+  // pin, so OpenCode falls back to its own session-model/small_model routing.
+  for (const key of ["title", "summary", "compaction"]) {
+    const existing = config.agent[key] && typeof config.agent[key] === "object" ? config.agent[key] : {};
+    delete existing.model;
+    config.agent[key] = existing;
   }
 
   writeOpenCodeConfig(config, configPath);