@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/reconcile/mcp-entry-reconcile.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/reconcile/mcp-entry-reconcile.mjs — strip Codex `[mcp_servers.<id>]`
+ * tables whose `bearer_token_env_var` references an unset env var from configs
+ * written before the sync-time fix (ADR-0027 / construct-n6h7).
+ *
+ * Codex aborts at startup when an MCP server's bearer_token_env_var names an
+ * env var that is unset. The sync writer now omits such entries, but a config
+ * written by an earlier version still carries them. This repair removes exactly
+ * those construct-managed tables from the global `~/.codex/config.toml` and a
+ * project `.codex/config.toml` when present, preserving every other table.
+ *
+ * Detection mirrors the sync-time gate (codexMcpEnvResolves): an entry whose
+ * token env var resolves is kept; only unresolved-credential tables are pruned.
+ * Tables with no credential requirement are never touched. Removal is scoped to
+ * registry-managed MCP ids by exact table name, so user-authored mcp_servers
+ * tables are out of scope. Safety: `auto`. detect() reads only; apply() is
+ * idempotent because removeTomlTables drains the matched tables to none.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { homeDir } from '../paths.mjs';
+import {
+  getCodexConfigPath,
+  buildCodexMcpEntry,
+  removeTomlTables,
+  tomlString,
+} from '../codex-config.mjs';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function registryMcpServers() {
+  const installed = path.join(homeDir(), '.construct', 'specialists', 'registry.json');
+  const bundled = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
+  for (const src of [installed, bundled]) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(src, 'utf8'));
+      if (parsed && parsed.mcpServers) return parsed.mcpServers;
+    } catch {
+      continue;
+    }
+  }
+  return {};
+}
+
+function hasMcpTable(text, id) {
+  return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, 'm').test(text);
+}
+
+// An entry with no bearer_token_env_var has no credential requirement and is
+// always valid. An entry whose token env var is set resolves; an unset value
+// (undefined or empty string) is the abort condition Codex hits at startup.
+
+function tokenResolves(id, def, 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 configTargets() {
+  const targets = [{ scope: 'global', file: getCodexConfigPath(homeDir()) }];
+  const projectConfig = path.join(process.cwd(), '.codex', 'config.toml');
+  if (fs.existsSync(projectConfig)) targets.push({ scope: 'project', file: projectConfig });
+  return targets;
+}
+
+function unresolvedTables(text, registryMcp, env) {
+  const ids = [];
+  for (const id of Object.keys(registryMcp)) {
+    if (!hasMcpTable(text, id)) continue;
+    if (tokenResolves(id, registryMcp[id], env)) continue;
+    ids.push(id);
+  }
+  return ids;
+}
+
+async function detect() {
+  const registryMcp = registryMcpServers();
+  if (Object.keys(registryMcp).length === 0) {
+    return { needsRepair: false, summary: 'No registry MCP servers to reconcile.' };
+  }
+  const env = process.env;
+  const offenders = [];
+  for (const target of configTargets()) {
+    let text = '';
+    try {
+      if (!fs.existsSync(target.file)) continue;
+      text = fs.readFileSync(target.file, 'utf8');
+    } catch {
+      continue;
+    }
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length > 0) offenders.push({ ...target, ids });
+  }
+  if (offenders.length === 0) {
+    return { needsRepair: false, summary: 'No Codex MCP tables reference an unset token env var.' };
+  }
+  const total = offenders.reduce((acc, o) => acc + o.ids.length, 0);
+  return {
+    needsRepair: true,
+    summary: `${total} Codex MCP table${total === 1 ? '' : 's'} reference an unset token env var (${offenders.map((o) => `${o.scope}: ${o.ids.join(', ')}`).join('; ')}).`,
+    details: { offenders: offenders.map((o) => ({ scope: o.scope, ids: o.ids })) },
+  };
+}
+
+async function apply() {
+  const registryMcp = registryMcpServers();
+  const env = process.env;
+  let removed = 0;
+  const scopes = [];
+  for (const target of configTargets()) {
+    if (!fs.existsSync(target.file)) continue;
+    const text = fs.readFileSync(target.file, 'utf8');
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length === 0) continue;
+
+    // Strip both the bare and quoted table forms per id, matching the names
+    // the sync writer emits, so a table written either way is removed.
+
+    const tableNames = ids.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]);
+    const cleaned = removeTomlTables(text, tableNames);
+    fs.writeFileSync(target.file, `${cleaned.trimEnd()}\n`, 'utf8');
+    removed += ids.length;
+    scopes.push(`${target.scope}: ${ids.join(', ')}`);
+  }
+  if (removed === 0) return { summary: 'Already clean.' };
+  return { summary: `Removed ${removed} unresolved Codex MCP table${removed === 1 ? '' : 's'} (${scopes.join('; ')}).` };
+}
+
+export default {
+  id: 'mcp-entry-reconcile',
+  description: 'Strip Codex MCP tables whose bearer_token_env_var references an unset env var from existing configs.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/reconcile/postgres-namespace.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/reconcile/postgres-namespace.mjs — migrate a local Postgres compose that
+ * predates per-home identifier derivation (ADR-0027 / construct-lb7b).
+ *
+ * Earlier versions wrote a singular `construct-postgres` container on the fixed
+ * 54329 port. Two isolated HOMEs sharing that container clobber each other's
+ * data and fight over the port. The derivation namespaces both per home; the
+ * repair rewrites a legacy compose file to the namespaced form.
+ *
+ * apply() is strictly data-safe: it only rewrites the compose via
+ * writeLocalPostgresCompose(home). It runs no docker command, removes no
+ * container, and deletes no volume — the existing volume and any data inside it
+ * are left intact. The returned summary instructs the operator to run
+ * `construct down && construct up` to recreate the container against the
+ * namespaced compose.
+ *
+ * Safety: `ask`. The rewrite changes the container/port a running stack binds
+ * to, so it runs only on explicit consent. detect() reads only; apply() is
+ * idempotent because the namespaced compose fails to match the legacy markers.
+ */
+
+import fs from 'node:fs';
+
+import { homeDir } from '../paths.mjs';
+import {
+  LEGACY_PG_CONTAINER,
+  LEGACY_PG_PORT,
+  postgresContainerName,
+  postgresPort,
+} from '../home-namespace.mjs';
+import { localPostgresComposePath, writeLocalPostgresCompose } from '../setup.mjs';
+
+// The container marker anchors to end-of-line so the namespaced form
+// `construct-postgres-<suffix>` does not match the singular legacy name as a
+// prefix (which would defeat idempotency).
+
+const LEGACY_CONTAINER_RE = new RegExp(`container_name:\\s*${LEGACY_PG_CONTAINER}\\s*$`, 'm');
+const LEGACY_PORT_RE = new RegExp(`:${LEGACY_PG_PORT}:`);
+
+function legacyMarkers(content, home) {
+  const derivedContainer = postgresContainerName(process.env, home);
+  const derivedPort = postgresPort(process.env, home);
+
+  // The legacy singular container only counts when the derivation would name it
+  // differently; an explicit CONSTRUCT_PG_CONTAINER override pinned to the
+  // singular name is the intended state, not drift.
+
+  const hasLegacyContainer = LEGACY_CONTAINER_RE.test(content) && derivedContainer !== LEGACY_PG_CONTAINER;
+  const hasLegacyPort = LEGACY_PORT_RE.test(content) && derivedPort !== LEGACY_PG_PORT;
+  return { hasLegacyContainer, hasLegacyPort, derivedContainer, derivedPort };
+}
+
+async function detect() {
+  const home = homeDir();
+  const composePath = localPostgresComposePath(home);
+  if (!fs.existsSync(composePath)) {
+    return { needsRepair: false, summary: 'No local Postgres compose file present.' };
+  }
+  let content = '';
+  try {
+    content = fs.readFileSync(composePath, 'utf8');
+  } catch (err) {
+    return { needsRepair: false, summary: `Could not read compose file: ${err.message}` };
+  }
+  const markers = legacyMarkers(content, home);
+  if (!markers.hasLegacyContainer && !markers.hasLegacyPort) {
+    return { needsRepair: false, summary: 'Local Postgres compose already uses per-home identifiers.' };
+  }
+  const reasons = [];
+  if (markers.hasLegacyContainer) reasons.push(`container ${LEGACY_PG_CONTAINER} → ${markers.derivedContainer}`);
+  if (markers.hasLegacyPort) reasons.push(`port ${LEGACY_PG_PORT} → ${markers.derivedPort}`);
+  return {
+    needsRepair: true,
+    summary: `Local Postgres compose predates per-home derivation (${reasons.join(', ')}).`,
+    details: { composePath, ...markers },
+  };
+}
+
+async function apply() {
+  const home = homeDir();
+  const composePath = localPostgresComposePath(home);
+  if (!fs.existsSync(composePath)) return { summary: 'No compose file to migrate.' };
+
+  // Rewrite the compose to the per-home form only. No docker invocation, no
+  // container removal, no volume deletion — the operator recreates the
+  // container themselves so data handling stays under their control.
+
+  writeLocalPostgresCompose(home);
+  const container = postgresContainerName(process.env, home);
+  const port = postgresPort(process.env, home);
+  return {
+    summary: `Rewrote local Postgres compose to per-home identifiers (container ${container}, port ${port}). Run \`construct down && construct up\` to recreate the container; existing data and volume are untouched.`,
+  };
+}
+
+export default {
+  id: 'postgres-namespace',
+  description: 'Rewrite a legacy local Postgres compose to per-home container/port identifiers (data-safe).',
+  safety: 'ask',
+  detect,
+  apply,
+};

package/lib/runtime/uv-bootstrap.mjs

@@ -37,12 +37,32 @@ function which(bin) {
   return result.stdout.trim().split('\n')[0] || null;
 }
 
+// First-run docling provisioning blocks for minutes (uv install, venv, then a
+// large `uv pip install docling` that pulls ML deps). Without a heartbeat it
+// reads as a hang. Progress goes to stderr only, so JSON consumers on stdout are
+// unaffected; it is the long-operation's own channel, not a suppressible notice.
+
+function progress(message) {
+  try { process.stderr.write(`[docling setup] ${message}\n`); } catch { /* stderr closed */ }
+}
+
+// spawnSync sets status=null and error.code=ETIMEDOUT on timeout; distinguish a
+// timeout from a real non-zero exit so the message tells the user what to do.
+
+function describeStepFailure(label, result, timeoutMs) {
+  if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+    return `${label} timed out after ${Math.round(timeoutMs / 1000)}s — docling's one-time download did not complete. Check network/proxy and re-run; or set ingest.fallback to "adapter" to skip docling.`;
+  }
+  return `${label} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message || 'unknown error'}`;
+}
+
 function ensureUv(installDir) {
   const fromPath = which('uv');
   if (fromPath) return fromPath;
   const cachedUv = path.join(installDir, 'bin', 'uv');
   if (existsSync(cachedUv)) return cachedUv;
   mkdirSync(installDir, { recursive: true });
+  progress('Installing uv (Python toolchain) — first run only…');
   const env = { ...process.env, UV_INSTALL_DIR: path.join(installDir, 'bin'), UV_NO_MODIFY_PATH: '1' };
   const sh = spawnSync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], {
     env,
@@ -50,7 +70,7 @@ function ensureUv(installDir) {
     encoding: 'utf8',
   });
   if (sh.status !== 0) {
-    throw new Error(`uv install failed (${sh.status}): ${sh.stderr || sh.stdout}`);
+    throw new Error(describeStepFailure('uv install', sh, UV_TIMEOUT_MS));
   }
   if (!existsSync(cachedUv)) {
     throw new Error(`uv install reported success but binary not found at ${cachedUv}`);
@@ -86,23 +106,27 @@ export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = fa
     return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
   }
 
+  progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
   const uv = ensureUv(runtimeDir);
 
+  progress('Creating Python 3.11 virtualenv…');
   const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
     timeout: VENV_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (venvResult.status !== 0) {
-    throw new Error(`uv venv failed (${venvResult.status}): ${venvResult.stderr}`);
+    throw new Error(describeStepFailure('uv venv', venvResult, VENV_TIMEOUT_MS));
   }
 
+  progress(`Installing docling ${DOCLING_PIN} and its dependencies — the slow step (large download)…`);
   const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
     timeout: INSTALL_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (installResult.status !== 0) {
-    throw new Error(`docling install failed (${installResult.status}): ${installResult.stderr}`);
+    throw new Error(describeStepFailure('docling install', installResult, INSTALL_TIMEOUT_MS));
   }
+  progress('docling extractor ready.');
 
   const pythonBin = pythonBinFor(venvDir);
   writeMarker(markerPath, {

package/lib/schema-infer.mjs

@@ -210,9 +210,23 @@ async function callModel(userContent, { traceId } = {}) {
   }
 
   // If only Anthropic key available, use configured fast tier directly.
+  // Construct ships with no implicit model defaults (ADR-0027,
+  // tests/model-router-no-defaults.test.mjs), so an unconfigured fast tier
+  // resolves to null. Surface a clear configuration error instead of letting
+  // null leak into the candidate loop where /^anthropic\//.test(null) throws.
+
   if (candidates.length === 0 && anthropicKey) {
     const envPath = getUserEnvPath();
-    candidates = [readCurrentModels(envPath, {}).fast];
+    const fast = readCurrentModels(envPath, {}).fast;
+    if (!fast) {
+      throw new Error(
+        "Schema inference requires a fast-tier model. " +
+        "Either set OPENROUTER_API_KEY (to use free model fallbacks) or " +
+        "configure a fast tier with 'construct models --apply' or " +
+        "'export CX_MODEL_FAST=<model-id>'."
+      );
+    }
+    candidates = [fast];
   }
 
   let lastError;
@@ -261,7 +275,7 @@ async function callModel(userContent, { traceId } = {}) {
           headers: {
             Authorization: `Bearer ${orKey}`,
             'content-type': 'application/json',
-            'HTTP-Referer': 'https://github.com/construct',
+            'HTTP-Referer': 'https://github.com/geraldmaron/construct',
           },
           body: JSON.stringify({
             model: openRouterModelId,

package/lib/server/csrf.mjs

@@ -66,6 +66,11 @@ export function ensureCsrfCookie(req, res) {
  */
 export function verifyCsrf(req, { skip } = {}) {
   if (SAFE_METHODS.has(req.method)) return true;
+  // A request authenticated by an Authorization header (bearer token) is not
+  // cookie-driven, so it cannot be forged cross-origin — CSRF defends ambient
+  // cookie auth, not header tokens. This is what lets programmatic API clients
+  // (editor adapters, CLI, CI) POST without the browser CSRF dance.
+  if (req.headers && req.headers.authorization) return true;
   if (typeof skip === 'function' && skip(req.url || '')) return true;
   const headerVal = req.headers[HEADER_NAME];
   const cookieVal = parseCookies(req)[COOKIE_NAME];
@@ -78,13 +83,20 @@ export function verifyCsrf(req, { skip } = {}) {
 }
 
 /**
- * Default skip predicate — webhooks and auth/login may legitimately accept
- * cross-origin POSTs without the CSRF dance.
+ * Default skip predicate — webhooks, auth/login, and the orchestration API
+ * legitimately accept POSTs without the CSRF dance. CSRF defends a browser
+ * cookie session; the `/api/orchestration/*` endpoints are consumed only by
+ * programmatic clients (the `--remote` CLI, the MCP tool, editor adapters) that
+ * carry a bearer token (or nothing in no-token mode), never the dashboard
+ * cookie — so CSRF is the wrong control there, and the auth gate still protects
+ * them in token mode. Without this, a no-token daemon rejects every orchestration
+ * run with a 403.
  */
 export function defaultSkip(url) {
   if (!url) return false;
   return (
     url.startsWith('/api/webhooks/') ||
+    url.startsWith('/api/orchestration/') ||
     url === '/api/auth/login' ||
     url === '/api/slack/commands'
   );

package/lib/server/index.mjs

@@ -32,6 +32,14 @@ import { onEmbedNotification } from '../embed/notifications.mjs';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
 const HOME = homedir();
+
+// The daemon is a long-lived, detached service not bound to one project, so its
+// orchestration runs persist under the user data root (HOME → ~/.cx/runtime/
+// orchestration via the run store's relative path) rather than the install
+// directory. A global install dir can be shared or read-only and would mix
+// every project's runs together; HOME is always writable and survives reinstalls.
+
+const ORCHESTRATION_RUN_ROOT = HOME;
 const PORT = parseInt(process.env.PORT ?? '4242', 10);
 
 // Default bind is loopback regardless of NODE_ENV. Exposing the dashboard to
@@ -464,6 +472,88 @@ async function handleApprovals(req, res) {
   res.end('Method Not Allowed');
 }
 
+// Orchestration daemon surface: start a run (background execution), inspect runs,
+// and stream a single run's lifecycle over SSE. Construct's runtime owns the
+// orchestration; this lets any thin client (editor, TUI, CI) reach the outcome.
+// Responses are wrapped in the versioned, secret-free embedded-contract envelope.
+
+async function handleOrchestration(req, res) {
+  const url = new URL(req.url, `http://${BIND_HOST}:${PORT}`);
+  const { startRun, getRun, getRuns } = await import('../orchestration/runtime.mjs');
+  const { onRunEvent, requestCancel } = await import('../orchestration/events.mjs');
+  const { wrapResponse } = await import('../embedded-contract/envelope.mjs');
+
+  const send = (code, data) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(wrapResponse({ data, surface: 'sdk' })));
+  };
+  const fail = (code, message) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: message }));
+  };
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'POST') {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', async () => {
+      try {
+        const d = JSON.parse(body || '{}');
+        if (!d.request || typeof d.request !== 'string') throw new Error('Missing "request" string');
+        const run = await startRun(
+          { request: d.request, workflowType: d.workflowType, requestedStrategy: d.requestedStrategy, host: d.host, hostModel: d.hostModel, hostProvider: d.hostProvider, fileCount: d.fileCount, moduleCount: d.moduleCount },
+          { cwd: ORCHESTRATION_RUN_ROOT, workerBackend: d.workerBackend || null },
+        );
+        send(202, run);
+      } catch (err) {
+        fail(400, err.message);
+      }
+    });
+    return;
+  }
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'GET') {
+    const limit = Number(url.searchParams.get('limit') || 20);
+    send(200, { runs: await getRuns(ORCHESTRATION_RUN_ROOT, { limit }) });
+    return;
+  }
+
+  const match = url.pathname.match(/^\/api\/orchestration\/runs\/([^/]+)(\/events|\/cancel)?$/);
+  if (match) {
+    const runId = decodeURIComponent(match[1]);
+    const sub = match[2];
+
+    if (!sub && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      if (!run) { fail(404, `Run not found: ${runId}`); return; }
+      send(200, run);
+      return;
+    }
+
+    if (sub === '/cancel' && req.method === 'POST') {
+      requestCancel(runId);
+      send(202, { runId, cancelRequested: true });
+      return;
+    }
+
+    if (sub === '/events' && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'Access-Control-Allow-Origin': '*' });
+      res.write(': connected\n\n');
+      if (run) {
+        const snapshot = { type: 'snapshot', runId, status: run.status, chainOfThought: run.chainOfThought ?? null, tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null })) };
+        res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+      }
+      const off = onRunEvent(runId, (event) => {
+        try { res.write(`data: ${JSON.stringify(event)}\n\n`); } catch { off(); }
+      });
+      req.on('close', off);
+      return;
+    }
+  }
+
+  fail(404, 'Not found');
+}
+
 // ── Config handler ────────────────────────────────────────────────────────
 
 function handleConfig(req, res) {
@@ -701,6 +791,11 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname.startsWith('/api/orchestration/')) {
+    await handleOrchestration(req, res);
+    return;
+  }
+
   if (url.pathname === '/api/registry' && req.method === 'GET') {
     try {
       const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));

package/lib/service-manager.mjs

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { findAvailablePort } from './host-capabilities.mjs';
 import { getUserEnvPath, loadConstructEnv, parseEnvFile, writeEnvValues } from './env-config.mjs';
@@ -22,15 +23,24 @@ import {
   isRemoteTelemetry,
 } from './services/local-postgres.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
+import { postgresPort, postgresContainerName, memoryPort as derivedMemoryPort } from './home-namespace.mjs';
 
 const CONSTRUCT_PG_COMPOSE_DIR = 'services/postgres';
-const CONSTRUCT_PG_CONTAINER = 'construct-postgres';
-const CONSTRUCT_PG_PORT = 54329;
+const CONSTRUCT_PG_CONTAINER = postgresContainerName();
+const CONSTRUCT_PG_PORT = postgresPort();
 const CONSTRUCT_PG_HEALTH_RETRIES = 12;
 const CONSTRUCT_PG_HEALTH_INTERVAL_MS = 2000;
 
 const DASHBOARD_STATE_FILE = 'dashboard.json';
 
+// The caller's `rootDir` is the project (for compose/context/traces), but the
+// dashboard and doctor entrypoints ship with the install, not the project. They
+// must resolve against the install root — derived from this module's own
+// location — or `construct init` spawns `<project>/lib/server/index.mjs` and the
+// process dies with MODULE_NOT_FOUND while still advertising the URL.
+
+const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
 // pruneStashDir and verifyTelemetryKeys now live in lib/services/telemetry-backend.mjs.
 // Re-exported below at module bottom for tests that already import from here.
 
@@ -260,7 +270,7 @@ export function startDoctor({ rootDir, homeDir = os.homedir() } = {}) {
   }
   const existing = readDoctorState(homeDir);
   if (existing) return { started: false, reused: true, pid: existing.pid };
-  const indexPath = path.join(rootDir, 'lib', 'doctor', 'index.mjs');
+  const indexPath = path.join(INSTALL_ROOT, 'lib', 'doctor', 'index.mjs');
   if (!fs.existsSync(indexPath)) return { started: false, reason: 'missing-binary' };
   const { logPath } = spawnDetached('node', [indexPath], homeDir, 'doctor.log', { cwd: rootDir, env: { ...process.env } });
   return { started: true, logPath };
@@ -279,13 +289,30 @@ 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(rootDir, 'lib', 'server', 'index.mjs')], {
+  const child = spawn(process.execPath, [path.join(INSTALL_ROOT, 'lib', 'server', 'index.mjs')], {
     detached: true,
     stdio: ['ignore', out, err],
     env: { ...process.env, PORT: String(port) },
   });
   child.unref();
 
+  // Confirm the process actually bound the port before persisting state or
+  // advertising the URL. Without this the caller reports a dead PID/URL when the
+  // server crashes on boot — the readiness gate turns a silent failure into an
+  // honest, actionable one (the log tail names the cause).
+
+  let ready = false;
+  for (let i = 0; i < 30; i += 1) {
+    if (await probeRuntimePort(port)) { ready = true; break; }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+
+  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 state = {
     pid: child.pid,
     port,
@@ -320,7 +347,7 @@ export async function getRuntimePorts(homeDir = os.homedir(), {
 
   return {
     dashboard: dashboard?.port ?? await resolvePort('DASHBOARD_PORT', 4242, dashboardProbeFn),
-    memory: await resolvePort('MEMORY_PORT', 8765, memoryProbeFn),
+    memory: await resolvePort('MEMORY_PORT', derivedMemoryPort(), memoryProbeFn),
     bridge: await resolvePort('BRIDGE_PORT', 5173, openCodeProbeFn),
   };
 }
@@ -375,13 +402,13 @@ async function waitForConstructPostgresHealthy({
 }
 
 function startConstructPostgres({ rootDir, homeDir = os.homedir(), spawnSyncFn = spawnSync, detectDockerComposeFn = detectDockerCompose } = {}) {
-  const composeRunner = detectDockerComposeFn();
+  const composeRunner = detectDockerComposeFn({ autoStart: true });
   if (!composeRunner) return { status: 'unavailable', note: 'Docker not available' };
 
   const composeFile = constructPgComposePath(rootDir);
   if (!fs.existsSync(composeFile)) return { status: 'unavailable', note: 'Postgres compose file not found — run construct init first' };
 
-  const args = [...composeRunner.argsPrefix, '-p', 'construct-postgres', '-f', composeFile, 'up', '-d'];
+  const args = [...composeRunner.argsPrefix, '-p', CONSTRUCT_PG_CONTAINER, '-f', composeFile, 'up', '-d'];
   const r = spawnSyncFn(composeRunner.command, args, { stdio: 'pipe', encoding: 'utf8' });
   if (r.status === 0) return { status: 'started' };
   return { status: 'error', note: (r.stderr || '').trim().split('\n')[0] || 'compose up failed' };
@@ -394,7 +421,7 @@ function stopConstructPostgres({ rootDir, homeDir = os.homedir(), spawnSyncFn =
   const composeFile = constructPgComposePath(rootDir);
   if (!fs.existsSync(composeFile)) return { status: 'skipped', note: 'no compose file' };
 
-  const args = [...composeRunner.argsPrefix, '-p', 'construct-postgres', '-f', composeFile, 'down'];
+  const args = [...composeRunner.argsPrefix, '-p', CONSTRUCT_PG_CONTAINER, '-f', composeFile, 'down'];
   const r = spawnSyncFn(composeRunner.command, args, { stdio: 'pipe', encoding: 'utf8' });
   if (r.status === 0) return { status: 'stopped' };
   return { status: 'error', note: (r.stderr || '').trim().split('\n')[0] || 'compose down failed' };
@@ -540,11 +567,9 @@ export async function startServices({
   // Dashboard
   if (wants('dashboard')) {
     const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
-    results.push({
-      name: 'Dashboard',
-      url: dashboard.url,
-      status: dashboard.reused ? 'reused' : 'started',
-    });
+    results.push(dashboard.failed
+      ? { name: 'Dashboard', status: 'failed', note: `${dashboard.error} — see ${dashboard.logPath}` }
+      : { name: 'Dashboard', url: dashboard.url, status: dashboard.reused ? 'reused' : 'started' });
   }
 
   const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
@@ -705,7 +730,7 @@ export async function stopServices({
   // Memory (cm) — find port from config.env or fall back to default
   const envPath = getUserEnvPath(homeDir);
   const envValues = parseEnvFile(envPath);
-  const memoryPort = Number(envValues.MEMORY_PORT) || 8765;
+  const memoryPort = Number(envValues.MEMORY_PORT) || derivedMemoryPort();
   const cmKilled = killPortOwners(memoryPort, spawnSyncFn);
   results.push({ name: 'Memory (cm)', status: cmKilled ? 'stopped' : 'not-running' });
 

package/lib/setup-prompts.mjs

@@ -29,6 +29,7 @@ export async function consentToInstall({
   alreadyConfigured = false,
   alreadyConfiguredNote = '',
   envPath,
+  question = '',
   defaultYes = true,
   readlineModule = readline,
   stdin = process.stdin,
@@ -64,7 +65,7 @@ export async function consentToInstall({
   }
 
   const answer = await promptYesNo({
-    question: `Install local ${name} via Docker?`,
+    question: question || `Install local ${name} via Docker?`,
     defaultYes,
     readlineModule,
     stdin,