@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/server/index.mjs

@@ -4,7 +4,7 @@
  * Serves the single-page dashboard from lib/server/static/, provides a JSON
  * status API, SSE live-reload, REST endpoints for registry management,
  * artifact generation/listing, approval queue inspection, snapshot data,
- * token-based auth, and SSE-streamed chat via the claude CLI.
+ * token-based auth, legacy claude CLI chat, and owned-loop SSE web chat.
  * Runs on port 4242 (overridable via PORT env var), bound to 127.0.0.1.
  */
 import { createServer } from 'http';
@@ -19,15 +19,21 @@ import { buildStatus as buildSharedStatus } from '../status.mjs';
 import { generateArtifact, listArtifacts } from '../embed/artifact.mjs';
 import { ApprovalQueue } from '../embed/approval-queue.mjs';
 import { resolveEmbedStatus } from '../embed/cli.mjs';
-import { loadConstructEnv } from '../env-config.mjs';
+import { loadConstructEnv, prepareConstructEnv } from '../runtime-env.mjs';
 import {
   isAuthConfigured, isAuthenticated, rejectUnauthorized,
   validateToken, createSession, sessionCookieHeader, clearSessionCookieHeader,
   getDashboardToken, getAuthConfig,
 } from './auth.mjs';
 import { handleChatStream, handleChat, handleChatHistory } from './chat.mjs';
+import {
+  handleChatLoopStream, handleChatLoopPermission, handleChatLoopPending, handleChatLoopConfig,
+  handleChatLoopCommand, handleChatLoopHistory, handleChatLoopCancel, handleChatModels, handleChatModelSelect,
+} from './chat-loop.mjs';
 import { createWebhookHandler, createSlackCommandHandler } from './webhook.mjs';
 import { onEmbedNotification } from '../embed/notifications.mjs';
+import { artifactTypes, templateMetadata } from '../artifact-manifest.mjs';
+import { resolveDemoPreviewPath, demoPreviewMime } from './demo-preview.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
@@ -355,6 +361,9 @@ async function buildStatus() {
     ...status,
     skills: listSkills(),
     commands: listCommands(),
+    artifactManifest: Object.fromEntries(
+      artifactTypes({ rootDir: ROOT_DIR }).map((type) => [type, templateMetadata(type, { rootDir: ROOT_DIR })]),
+    ),
   };
 }
 
@@ -693,6 +702,7 @@ const server = createServer(async (req, res) => {
     ensureCsrfCookie(req, res);
   }
   const rateTier = url.pathname === '/api/chat/stream' || url.pathname === '/api/chat'
+    || url.pathname === '/api/chat/loop/stream'
     ? 'chat'
     : (req.method !== 'GET' && req.method !== 'HEAD' ? 'write' : 'read');
   if (checkRateLimit) {
@@ -836,6 +846,141 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname === '/api/certification/status' && req.method === 'GET') {
+    try {
+      const { buildCertificationDashboard } = await import('../certification/dashboard-api.mjs');
+      const capabilityId = url.searchParams.get('capabilityId');
+      const payload = capabilityId
+        ? (await import('../certification/status.mjs')).buildCertificationStatus({
+          rootDir: process.cwd(),
+          capabilityId,
+        })
+        : buildCertificationDashboard({ rootDir: process.cwd() });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  if (url.pathname === '/api/oracle/pending' && req.method === 'GET') {
+    try {
+      const { listPending } = await import('../oracle/actions.mjs');
+      const pending = listPending(process.cwd()).filter((p) => p.status !== 'approved');
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ pending }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  if (url.pathname === '/api/improvement/pending' && req.method === 'GET') {
+    try {
+      const { listPending } = await import('../improvement/surface.mjs');
+      const pending = listPending(process.cwd());
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ pending }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  if (url.pathname.startsWith('/api/improvement/') && req.method === 'POST') {
+    const action = url.pathname.slice('/api/improvement/'.length);
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', async () => {
+      try {
+        const data = JSON.parse(body || '{}');
+        const projectDir = process.cwd();
+        const { reviewRecord, approveRecord, applyRecord, rollbackRecord } = await import('../improvement/surface.mjs');
+        let result;
+        if (action === 'review') {
+          if (!data.id) throw new Error('Missing id');
+          result = reviewRecord(projectDir, data.id);
+        } else if (action === 'approve') {
+          if (!data.id) throw new Error('Missing id');
+          result = approveRecord(projectDir, data.id, { identity: data.identity });
+        } else if (action === 'apply') {
+          if (!data.id) throw new Error('Missing id');
+          result = applyRecord(projectDir, data.id, { monitor: data.monitor });
+        } else if (action === 'rollback') {
+          if (!data.id) throw new Error('Missing id');
+          result = rollbackRecord(projectDir, data.id, { reason: data.reason });
+        } else {
+          throw new Error(`Unknown improvement action: ${action}`);
+        }
+        const status = result.ok === false && result.error ? 400 : 200;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+        notifyClients();
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+    });
+    return;
+  }
+
+  if (url.pathname.startsWith('/api/improvement/') && req.method === 'GET') {
+    const id = decodeURIComponent(url.pathname.slice('/api/improvement/'.length));
+    if (id && id !== 'pending') {
+      try {
+        const { loadRecord } = await import('../improvement/store.mjs');
+        const record = loadRecord(process.cwd(), id);
+        if (!record) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'not-found' }));
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(record));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+  }
+
+  if (url.pathname === '/api/oracle' && req.method === 'GET') {
+    try {
+      const { homedir: osHome } = await import('node:os');
+      const { readHeartbeat } = await import('../daemons/contract.mjs');
+      const { heartbeatPath, readLastTick } = await import('../oracle/index.mjs');
+      const { collectReadModel, enrichReadModel } = await import('../oracle/read-model.mjs');
+      const { synthesizeVerdict } = await import('../oracle/synthesize.mjs');
+      const home = osHome();
+      const projectDir = process.cwd();
+      const readModel = collectReadModel({ rootDir: ROOT_DIR, projectDir, homeDir: home });
+      const enriched = await enrichReadModel(readModel);
+      const synthesis = synthesizeVerdict(enriched);
+      const hb = readHeartbeat(heartbeatPath(home));
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        running: !!hb,
+        heartbeat: hb,
+        lastTick: readLastTick(home),
+        verdict: synthesis.verdict,
+        gaps: synthesis.gaps,
+        recommendedActions: synthesis.recommendedActions,
+        orgGraph: enriched.orgGraph,
+        openBeads: enriched.beads?.openCount ?? null,
+        lastPropagationCheck: enriched.orgGraph?.propagation ?? null,
+      }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
   if (url.pathname === '/api/doctor') {
     try {
       const { readState } = await import('../doctor/index.mjs');
@@ -1438,7 +1583,9 @@ const server = createServer(async (req, res) => {
   if (url.pathname === '/api/intake/config' && req.method === 'GET') {
     try {
       const { loadIntakeConfig, INTAKE_DEPTH_GUIDANCE, INTAKE_HARD_MAX_DEPTH } = await import('../intake/intake-config.mjs');
+      const { getRebrand } = await import('../profiles/rebrand.mjs');
       const config = loadIntakeConfig(ROOT_DIR, process.env);
+      const rebrand = getRebrand(ROOT_DIR);
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({
         config,
@@ -1446,6 +1593,8 @@ const server = createServer(async (req, res) => {
         guidance: INTAKE_DEPTH_GUIDANCE,
         hardMaxDepth: INTAKE_HARD_MAX_DEPTH,
         defaults: { projectInbox: '.cx/inbox', docsIntake: 'docs/intake' },
+        label: rebrand.intakeQueueLabel,
+        itemNoun: rebrand.signalNoun,
       }));
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -1457,10 +1606,17 @@ const server = createServer(async (req, res) => {
   if (url.pathname === '/api/intake/list' && req.method === 'GET') {
     try {
       const { createIntakeQueue } = await import('../intake/queue.mjs');
+      const { getRebrand } = await import('../profiles/rebrand.mjs');
       const queue = createIntakeQueue(ROOT_DIR, process.env);
       const items = queue.listPending();
+      const rebrand = getRebrand(ROOT_DIR);
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ items, total: items.length }));
+      res.end(JSON.stringify({
+        items,
+        total: items.length,
+        label: rebrand.intakeQueueLabel,
+        itemNoun: rebrand.signalNoun,
+      }));
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: err.message }));
@@ -1934,6 +2090,51 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname === '/api/chat/loop/stream' && req.method === 'GET') {
+    handleChatLoopStream(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/loop/pending' && req.method === 'GET') {
+    handleChatLoopPending(req, res);
+    return;
+  }
+
+  if (url.pathname === '/api/chat/loop/permission' && req.method === 'POST') {
+    handleChatLoopPermission(req, res);
+    return;
+  }
+
+  if (url.pathname === '/api/chat/config' && (req.method === 'GET' || req.method === 'POST')) {
+    handleChatLoopConfig(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/models' && req.method === 'GET') {
+    void handleChatModels(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/models/select' && req.method === 'POST') {
+    handleChatModelSelect(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/loop/command' && req.method === 'POST') {
+    handleChatLoopCommand(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/loop/history' && req.method === 'GET') {
+    handleChatLoopHistory(req, res, { rootDir: ROOT_DIR });
+    return;
+  }
+
+  if (url.pathname === '/api/chat/loop/cancel' && req.method === 'POST') {
+    handleChatLoopCancel(req, res);
+    return;
+  }
+
   if (req.method === 'POST') {
     let body = '';
     req.on('data', chunk => { body += chunk; });
@@ -2298,9 +2499,21 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname.startsWith('/demo-preview/')) {
+    const preview = resolveDemoPreviewPath(url.pathname);
+    if (!preview.ok) {
+      res.writeHead(preview.status);
+      res.end(preview.message);
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': demoPreviewMime(preview.ext) });
+    res.end(readFileSync(preview.filePath));
+    return;
+  }
+
   // Static files
   let filePath = url.pathname === '/' ? '/index.html' : url.pathname;
-  const fullPath = join(STATIC_DIR, filePath);
+  let fullPath = join(STATIC_DIR, filePath);
 
   if (!fullPath.startsWith(STATIC_DIR)) {
     res.writeHead(403);
@@ -2308,7 +2521,14 @@ const server = createServer(async (req, res) => {
     return;
   }
 
-  if (!existsSync(fullPath)) {
+  if (existsSync(fullPath) && statSync(fullPath).isDirectory()) {
+    fullPath = join(fullPath, 'index.html');
+  } else if (!existsSync(fullPath)) {
+    const indexCandidate = join(STATIC_DIR, filePath, 'index.html');
+    if (existsSync(indexCandidate)) fullPath = indexCandidate;
+  }
+
+  if (!existsSync(fullPath) || statSync(fullPath).isDirectory()) {
     res.writeHead(404);
     res.end('Not found');
     return;
@@ -2345,11 +2565,12 @@ function runEmbedSync() {
 // from process.env (telemetry credentials, model provider keys, etc.) find them
 // even when the server is started directly (not through bin/construct).
 try {
-  const { loadConstructEnv, getUserEnvPath } = await import('../env-config.mjs');
+  const { getUserEnvPath } = await import('../env-config.mjs');
+  const { prepareConstructEnv } = await import('../runtime-env.mjs');
   const homeDir = HOME || homedir();
   const envPath = getUserEnvPath(homeDir);
   if (existsSync(envPath)) {
-    const ENV = loadConstructEnv({ rootDir: ROOT_DIR, homeDir, env: process.env });
+    const ENV = prepareConstructEnv({ rootDir: ROOT_DIR, homeDir, env: process.env });
     for (const [key, value] of Object.entries(ENV)) {
       if (!(key in process.env)) process.env[key] = value;
     }

package/lib/service-manager.mjs

@@ -13,10 +13,13 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { findAvailablePort } from './host-capabilities.mjs';
+import { wrapWithOpRun } from './providers/op-run.mjs';
 import { getUserEnvPath, loadConstructEnv, parseEnvFile, writeEnvValues } from './env-config.mjs';
 import { runPressureRelease } from './runtime-pressure.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 import { memoryPort as derivedMemoryPort } from './home-namespace.mjs';
+import { readHeartbeat } from './daemons/contract.mjs';
+import { heartbeatPath } from './oracle/index.mjs';
 
 const DASHBOARD_STATE_FILE = 'dashboard.json';
 
@@ -95,7 +98,7 @@ export function buildRuntimeRecoverySummary({ rootDir, homeDir = os.homedir(), r
 }
 
 export function isManagedConstructPostgresUrl(databaseUrl = '') {
-  // Construct no longer manages local Postgres containers.
+  // Local Postgres lifecycle is out of Construct's scope, so no URL is Construct-managed.
   return false;
 }
 
@@ -249,6 +252,25 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   return { started: true, logPath };
 }
 
+export function startOracle({ rootDir, homeDir = os.homedir(), projectDir = rootDir } = {}) {
+  if (process.env.CONSTRUCT_ORACLE === 'off' || process.env.CONSTRUCT_ORACLE === '0') {
+    return { started: false, reason: 'disabled' };
+  }
+  const entry = path.join(INSTALL_ROOT, 'lib', 'oracle', 'daemon-entry.mjs');
+  if (!fs.existsSync(entry)) return { started: false, reason: 'missing-binary' };
+  const live = readHeartbeat(heartbeatPath(homeDir));
+  if (live) return { started: false, reused: true, pid: live.pid };
+  const { logPath } = spawnDetached('node', [entry], homeDir, 'oracle-daemon.log', {
+    cwd: projectDir,
+    env: {
+      ...process.env,
+      CONSTRUCT_ORACLE_ROOT: rootDir,
+      CONSTRUCT_ORACLE_PROJECT: projectDir,
+    },
+  });
+  return { started: true, logPath };
+}
+
 export async function startDashboard({ rootDir, homeDir = os.homedir(), preferredPort = 4242 } = {}) {
   const existing = readDashboardState(homeDir);
   if (existing && await isDashboardRunning(existing.port)) {
@@ -262,7 +284,16 @@ export async function startDashboard({ rootDir, homeDir = os.homedir(), preferre
   fs.mkdirSync(path.dirname(outPath), { recursive: true });
   const out = fs.openSync(outPath, 'a');
   const err = fs.openSync(outPath, 'a');
-  const child = spawn(process.execPath, [path.join(INSTALL_ROOT, 'lib', 'server', 'index.mjs')], {
+
+  // Opt-in: with CONSTRUCT_OP_ENV_FILE set, launch the daemon under `op run` so
+  // 1Password op:// refs resolve once at startup into its env. The biometric
+  // unlock prompt makes first launch slower, so widen the readiness window then.
+  const { command, args, wrapped } = wrapWithOpRun(
+    process.execPath,
+    [path.join(INSTALL_ROOT, 'lib', 'server', 'index.mjs')],
+    { env: process.env },
+  );
+  const child = spawn(command, args, {
     detached: true,
     stdio: ['ignore', out, err],
     env: { ...process.env, PORT: String(port) },
@@ -270,7 +301,8 @@ export async function startDashboard({ rootDir, homeDir = os.homedir(), preferre
   child.unref();
 
   let ready = false;
-  for (let i = 0; i < 30; i += 1) {
+  const maxTries = wrapped ? 150 : 30;
+  for (let i = 0; i < maxTries; i += 1) {
     if (await probeRuntimePort(port)) { ready = true; break; }
     await new Promise((resolve) => setTimeout(resolve, 200));
   }
@@ -278,7 +310,8 @@ export async function startDashboard({ rootDir, homeDir = os.homedir(), preferre
   if (!ready) {
     let logTail = '';
     try { logTail = fs.readFileSync(outPath, 'utf8').split('\n').slice(-12).join('\n'); } catch { /* log unreadable */ }
-    return { started: false, failed: true, port, logPath: outPath, error: `dashboard did not bind 127.0.0.1:${port} within 6s`, logTail };
+    const window = wrapped ? '30s (op run awaits 1Password unlock)' : '6s';
+    return { started: false, failed: true, port, logPath: outPath, error: `dashboard did not bind 127.0.0.1:${port} within ${window}`, logTail };
   }
 
   const state = {
@@ -342,6 +375,16 @@ export const SELECTABLE_SERVICES = Object.freeze([
   { key: 'copilot-bridge', label: 'Copilot Bridge', description: 'Host-native Copilot bridge proxy (requires gh auth).' },
 ]);
 
+// Construct does not impose an Ollama keep-alive: an operator value is honored when
+// present, otherwise the variable is left unset so the Ollama server applies its own
+// default and idle models unload on their own. A forced value would keep every
+// requested model resident in unified memory for the whole window.
+
+export function resolveOllamaKeepAlive(env = {}) {
+  const operatorValue = typeof env?.OLLAMA_KEEP_ALIVE === 'string' ? env.OLLAMA_KEEP_ALIVE.trim() : '';
+  return operatorValue || null;
+}
+
 export async function startServices({
   rootDir,
   homeDir = os.homedir(),
@@ -370,10 +413,10 @@ export async function startServices({
 
   const liveEnv = loadConstructEnvFn({ rootDir, homeDir });
   const results = [];
-  
-  // Set Ollama persistence for local inference performance
-  liveEnv.OLLAMA_KEEP_ALIVE = "-1";
-  
+
+  const operatorKeepAlive = resolveOllamaKeepAlive(liveEnv);
+  if (operatorKeepAlive) liveEnv.OLLAMA_KEEP_ALIVE = operatorKeepAlive;
+
   const pressureReport = runPressureReleaseFn({ env: { ...liveEnv, HOME: homeDir } });
   if (pressureReport?.killed?.length) {
     results.push({
@@ -481,6 +524,15 @@ export async function startServices({
     results.push({ name: 'Doctor', status: 'unavailable', note: doctor.reason });
   }
 
+  const oracle = startOracle({ rootDir, homeDir, projectDir: rootDir });
+  if (oracle.started) {
+    results.push({ name: 'Oracle', status: 'started', note: `L0.5 overseer · logs: ${oracle.logPath}` });
+  } else if (oracle.reused) {
+    results.push({ name: 'Oracle', status: 'reused', note: `pid ${oracle.pid}` });
+  } else if (oracle.reason !== 'disabled') {
+    results.push({ name: 'Oracle', status: 'unavailable', note: oracle.reason });
+  }
+
   emitServiceFailures(results);
 
   return {

package/lib/setup.mjs

@@ -32,6 +32,9 @@ import { getCanonicalOpenCodeConfigPath, readOpenCodeConfig, writeOpenCodeConfig
 import { getEmbeddingModelInfo, warmupEmbeddingModel } from './storage/embeddings-engine.mjs';
 import { buildPressureGuardValues, installPressureGuardLaunchAgent, loadPressureGuardLaunchAgent } from './runtime-pressure.mjs';
 import { consentToInstall } from './setup-prompts.mjs';
+import { cleanupLegacyGlobalConstruct } from './install/legacy-global-cleanup.mjs';
+import { downloadDesktopBinary } from './install/desktop-binary-download.mjs';
+import { buildDesktopBinary, hasDesktopSource } from './chat/desktop-build.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
@@ -40,7 +43,7 @@ function printHelp() {
   console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-launch-agent] [--reconfigure] [--with-docling]
+  construct install [--scope=project|user|both] [--yes] [--dry-run] [--no-launch-agent] [--reconfigure] [--with-docling] [--cleanup-legacy-global]
 
 Flags:
   --scope=<s>       project | user | both (default: project — see ADR-0029)
@@ -56,6 +59,9 @@ Flags:
   --with-docling    eagerly provision the docling document-extraction venv now
                       (heavy, ~10 min via uv; otherwise provisioned lazily on
                       first document ingest)
+  --cleanup-legacy-global
+                    remove legacy user-global Construct adapters/MCP/history
+                      before setup; does not uninstall a global construct CLI
 
 What --scope=user does:
   - creates ~/.construct/config.env
@@ -307,14 +313,35 @@ function printProjectScopeGuidance() {
   console.log('  construct install --scope=both');
 }
 
+function runLegacyGlobalCleanup({ homeDir, dryRun }) {
+  const result = cleanupLegacyGlobalConstruct({ homeDir, dryRun });
+  const action = dryRun ? 'would remove' : 'removed';
+  console.log(`Legacy global cleanup: ${result.removed.length ? `${action} ${result.removed.length} item(s)` : 'nothing detected'}`);
+  for (const item of result.removed.slice(0, 20)) {
+    console.log(`  - ${item}`);
+  }
+  if (result.removed.length > 20) {
+    console.log(`  - ...and ${result.removed.length - 20} more`);
+  }
+  return result;
+}
+
 // Dry-run renders the user-scope plan as intent only — every line names a write,
 // network call, or service registration that the real run would perform — and
 // returns before touching disk so the preview is provably side-effect-free.
 
-function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent }) {
+function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupLegacyGlobal }) {
   console.log('Construct install — dry-run (no changes written)');
   console.log('────────────────────────────────────────────────');
   console.log(`Scope: ${scope}`);
+  if (cleanupLegacyGlobal) {
+    console.log('\nLegacy global cleanup:');
+    runLegacyGlobalCleanup({ homeDir, dryRun: true });
+  }
+  if (scope === 'project') {
+    console.log('\nWould not run user-scope setup. Re-run without --dry-run to apply cleanup only.');
+    return;
+  }
   if (scope === 'both') {
     console.log('  · would print project-scope guidance, then run the user-scope plan below');
   }
@@ -326,6 +353,7 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent }) {
   console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
   console.log('\nWould check / install runtime tooling:');
   console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
+  console.log('  · construct-chat desktop binary (from GitHub releases → ~/.construct/bin/)');
   console.log('\nWould reach the network / external services:');
   console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
   if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
@@ -341,13 +369,14 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   const argSet = new Set(args);
   const isYes = argSet.has('--yes');
   const reconfigure = argSet.has('--reconfigure');
+  const cleanupLegacyGlobal = argSet.has('--cleanup-legacy-global');
 
   if (argSet.has('--help') || argSet.has('-h')) {
     printHelp();
     return;
   }
 
-  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--help', '-h']);
+  const KNOWN_FLAGS = new Set(['--yes', '--dry-run', '--no-launch-agent', '--reconfigure', '--with-docling', '--cleanup-legacy-global', '--help', '-h']);
   const dryRun = argSet.has('--dry-run');
   const withDocling = argSet.has('--with-docling');
   const unknownFlags = args.filter((a) => {
@@ -369,13 +398,25 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   }
   const scope = scopeResult.scope;
 
-  if (scope === 'project') {
-    printProjectScopeGuidance();
+  if (dryRun) {
+    if (scope === 'project' && !cleanupLegacyGlobal) {
+      printProjectScopeGuidance();
+      return;
+    }
+    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent'), cleanupLegacyGlobal });
     return;
   }
 
-  if (dryRun) {
-    printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent: argSet.has('--no-launch-agent') });
+  if (cleanupLegacyGlobal) {
+    runLegacyGlobalCleanup({ homeDir, dryRun: false });
+    if (scope === 'project') {
+      printProjectScopeGuidance();
+      return;
+    }
+  }
+
+  if (scope === 'project') {
+    printProjectScopeGuidance();
     return;
   }
 
@@ -415,6 +456,28 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     if (cassInstall.installCommand) console.log(`  Install with: ${cassInstall.installCommand}`);
   }
 
+  try {
+    if (hasDesktopSource(ROOT_DIR)) {
+      const built = buildDesktopBinary({ repoRoot: ROOT_DIR, env: process.env });
+      if (built.ok) {
+        console.log(`Desktop binary: built from source → ${built.binaryPath}`);
+      } else {
+        console.log(`Desktop binary: build skipped (${built.reason}) — runs on first \`construct chat\``);
+      }
+    } else {
+      const desktop = await downloadDesktopBinary({ homeDir, env: process.env });
+      if (desktop.status === 'downloaded') {
+        console.log(`Desktop binary: ${desktop.version} → ${desktop.dest}`);
+      } else if (desktop.status === 'failed') {
+        console.log(`Desktop binary: download failed (${desktop.reason}) — run \`construct install --scope=user\` again to retry`);
+      } else {
+        console.log(`Desktop binary: ${desktop.reason}`);
+      }
+    }
+  } catch (err) {
+    console.log(`Desktop binary: skipped (${err?.message || 'unknown error'})`);
+  }
+
   const telemetryResult = process.env.CONSTRUCT_TELEMETRY_URL
     ? { status: 'configured', note: `remote export configured (${process.env.CONSTRUCT_TELEMETRY_URL})` }
     : { status: 'local', note: 'local JSONL traces in .cx/traces; remote export optional' };

package/lib/specialists/prompt-schema.mjs

@@ -5,8 +5,8 @@
  * shape: YAML frontmatter (structured metadata) + markdown body (the authored
  * prose), mirroring skills/roles/*.md. This validates the frontmatter and the
  * canonical-section contract, and gates the highest-value invariant — the
- * frontmatter `perspective{}` must equal the registry's, since the two
- * currently duplicate each other and drift silently (ADR-0037).
+ * frontmatter `perspective{}` is the sole source of truth (ADR-0037); registry.json
+ * carries routing metadata only.
  *
  * A file with no frontmatter is treated as not-yet-converted: reported, never an
  * error, so the linter can run across a half-migrated corpus. Frontmatter is the
@@ -55,11 +55,6 @@ function hasHeading(body, title) {
   return false;
 }
 
-function samePerspective(a, b) {
-  if (!a || !b) return false;
-  return PERSPECTIVE_FIELDS.every((f) => String(a[f] ?? '').trim() === String(b[f] ?? '').trim());
-}
-
 /**
  * Validate one prompt file's content against the hybrid format.
  *
@@ -103,9 +98,6 @@ export function validatePromptContent({ content, id = '(prompt)', registryEntry
     for (const f of PERSPECTIVE_FIELDS) {
       if (!persp[f] || !String(persp[f]).trim()) errors.push(`${id}: perspective.${f} is required and must be non-empty`);
     }
-    if (registryEntry?.perspective && !samePerspective(persp, registryEntry.perspective)) {
-      errors.push(`${id}: perspective{} drifts from registry.json — they must match while both exist (frontmatter is the source of truth; update the registry)`);
-    }
   } else if (frontmatter.perspective != null) {
     errors.push(`${id}: perspective must be an object with ${PERSPECTIVE_FIELDS.join(', ')}`);
   }
@@ -160,3 +152,20 @@ function loadRegistry(rootDir) {
     return { specialists: [] };
   }
 }
+
+/**
+ * Resolve a specialist's perspective from its prompt frontmatter.
+ * @param {string} agentName - registry name or cx-prefixed id
+ * @returns {object|null}
+ */
+export function resolvePerspectiveFromPrompt(agentName, { rootDir = process.cwd(), registry } = {}) {
+  const reg = registry ?? loadRegistry(rootDir);
+  const normalized = String(agentName ?? '').trim().replace(/^cx-/, '');
+  const entry = (reg.specialists ?? []).find((s) => s.name === normalized);
+  if (!entry?.promptFile) return null;
+  const filePath = path.join(rootDir, entry.promptFile);
+  if (!fs.existsSync(filePath)) return null;
+  const { frontmatter } = splitFrontmatter(fs.readFileSync(filePath, 'utf8'));
+  const persp = frontmatter?.perspective;
+  return persp && typeof persp === 'object' ? persp : null;
+}