@geraldmaron/construct 1.0.21 → 1.0.24

package/bin/construct

@@ -65,10 +65,9 @@ import { runTeamReviewCli } from '../lib/telemetry/team-rollup.mjs';
 import { readDashboardState, startDashboard, startServices } from '../lib/service-manager.mjs';
 import { readCostLog, summarizeCostData, formatCostReport, clearCostLog } from '../lib/cost.mjs';
 import { readEfficiencyLog, summarizeEfficiencyData, formatEfficiencyReport } from '../lib/efficiency.mjs';
+import { resolveColors } from '../lib/term-format.mjs';
 import { buildHybridSearchResultsAsync } from '../lib/storage/hybrid-query.mjs';
-import { createSqlClient, closeSqlClient, readVectorConfig } from '../lib/storage/backend.mjs';
-import { describeVectorStore } from '../lib/storage/vector-store.mjs';
-import { describeSqlStore } from '../lib/storage/sql-store.mjs';
+import { createSqlClient, closeSqlClient } from '../lib/storage/backend.mjs';
 import { syncFileStateToSql } from '../lib/storage/sync.mjs';
 import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, resetStorage } from '../lib/storage/admin.mjs';
 import { runPressureRelease } from '../lib/runtime-pressure.mjs';
@@ -80,12 +79,7 @@ for (const [key, value] of Object.entries(ENV)) {
   if (!(key in process.env)) process.env[key] = value;
 }
 
-const COLORS = (!process.env.NO_COLOR && process.stdout.isTTY && process.env.TERM !== 'dumb')
-  ? {
-      bold: '\u001b[1m', dim: '\u001b[2m', reset: '\u001b[0m',
-      red: '\u001b[31m', green: '\u001b[32m', yellow: '\u001b[33m', cyan: '\u001b[36m',
-    }
-  : { bold: '', dim: '', reset: '', red: '', green: '', yellow: '', cyan: '' };
+const COLORS = resolveColors();
 
 function println(message = '') { process.stdout.write(`${message}\n`); }
 function errorln(message = '') { process.stderr.write(`${message}\n`); }
@@ -250,6 +244,45 @@ async function cmdSync(args) {
     opLog.close('failed', { stage: 'sync-specialists', status: syncStatus });
     process.exit(syncStatus);
   }
+
+  // State reconciliation (ADR-0027): bring on-disk state in line with the
+  // current disposition contract. Auto-safety tasks run silently; ask-safety
+  // tasks surface via construct doctor instead. --reconcile=<id> runs one task
+  // on explicit consent (the path for ask-safety tasks). --no-reconcile
+  // bypasses the auto pass entirely for diagnostic runs.
+
+  const reconcileArg = args.find((a) => a.startsWith('--reconcile='));
+  if (reconcileArg) {
+    const id = reconcileArg.slice('--reconcile='.length);
+    try {
+      const { runReconciliation } = await import('../lib/reconcile/index.mjs');
+      const result = await runReconciliation(id, {});
+      if (!result.ok) {
+        errorln(`Reconciliation failed (${id}): ${result.reason}`);
+        if (result.available) errorln(`Available: ${result.available.join(', ')}`);
+        opLog.close('failed', { stage: 'reconcile', id, reason: result.reason });
+        process.exit(1);
+      }
+      if (result.ran) ok(`Reconciled (${id}): ${result.summary}`);
+      else println(`Reconciliation (${id}): ${result.summary}`);
+      opLog.event('reconcile-explicit', { id, ran: !!result.ran });
+    } catch (err) {
+      errorln(`Reconciliation error (${id}): ${err.message}`);
+      opLog.close('failed', { stage: 'reconcile', id, reason: err.message });
+      process.exit(1);
+    }
+  } else if (!args.includes('--no-reconcile')) {
+    try {
+      const verbose = args.includes('--verbose') || args.includes('-v');
+      const { runAutoReconciliations } = await import('../lib/reconcile/index.mjs');
+      const { applied } = await runAutoReconciliations({ verbose });
+      for (const entry of applied) ok(`Reconciled (${entry.id}): ${entry.summary}`);
+      opLog.event('reconcile', { applied: applied.length });
+    } catch (err) {
+      opLog.event('reconcile-error', { message: err.message });
+    }
+  }
+
   if (args.includes('--no-docs')) {
     opLog.close('ok', { docs: 'skipped' });
     return;
@@ -584,23 +617,24 @@ async function cmdDoctor() {
   // Tier model selection. Construct ships with no default — at least
   // one tier must be configured (registry.json primary OR CX_MODEL_*
   // env override) before any LLM-backed workflow can run.
-  // Skip in CI — model tiers are user-specific, not repo-wide.
-  const inCI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+  // A missing, partial, or unresolvable tier is advisory, not a repo defect:
+  // model tiers are user/machine-specific config, so doctor warns and never
+  // fails the gate on them.
   try {
     const { resolveModelTiers } = await import('../lib/model-registry.mjs');
     const resolved = resolveModelTiers({ env: process.env });
     if (resolved.complete && !resolved.errors) {
       add('Models — all tiers configured', true);
     } else if (resolved.configured === 0) {
-      add('Models — no tier configured (pick one in the dashboard or run `construct models --apply`)', inCI, inCI);
+      add('Models — no tier configured (pick one in the dashboard or run `construct models --apply`)', false, true);
     } else {
       const missing = Object.entries(resolved.models)
         .filter(([, v]) => !v)
         .map(([k]) => k);
-      add(`Models — only ${resolved.configured}/3 tiers configured (missing: ${missing.join(', ')})`, inCI, inCI);
+      add(`Models — only ${resolved.configured}/3 tiers configured (missing: ${missing.join(', ')})`, false, true);
     }
   } catch (err) {
-    add(`Models — check failed: ${err.message}`, inCI, inCI);
+    add(`Models — check failed: ${err.message}`, false, true);
   }
 
   add('Node.js 20+ (recommended)', Number.parseInt(process.versions.node.split('.')[0], 10) >= 20);
@@ -786,35 +820,10 @@ async function cmdDoctor() {
     const researchLintResults = lintResearchRepo({ rootDir: process.cwd() });
     add('Research artifacts meet minimum evidence structure', researchLintResults.every((entry) => entry.errors.length === 0), true);
 
-    const sqlConfig = describeSqlStore(process.env);
-    const sqlClient = createSqlClient(process.env);
-    // Track SQL reachability so the schema-migration check can cascade correctly
-    // rather than emitting a redundant second warning for the same offline server.
-    let sqlReachable = false;
-    if (sqlConfig.configured && sqlClient) {
-      try {
-        await sqlClient`select 1 as ok`;
-        sqlReachable = true;
-        add('SQL backend reachable', true);
-      } catch {
-        // In solo mode the local vector index is the active storage path, so an
-        // unreachable Postgres is expected unless the user has started it. Emit a
-        // contextual message rather than a bare ⚠ so the fix is obvious.
-        const { getDeploymentMode } = await import('../lib/deployment-mode.mjs');
-        const mode = getDeploymentMode(process.env) ?? 'solo';
-        const hint = mode === 'solo'
-          ? ' (solo mode — run `construct dev` to start Postgres)'
-          : ' — check DATABASE_URL and that the server is running';
-        add(`SQL backend unreachable${hint}`, false, true);
-      } finally {
-        await closeSqlClient(sqlClient);
-      }
-    } else {
-      add('SQL backend configured', sqlConfig.fallbackAvailable, true);
-    }
-
-    const vectorConfig = describeVectorStore(process.env);
-    add('Vector backend configured', Boolean(vectorConfig.endpoint || vectorConfig.indexPath || vectorConfig.mode === 'file'));
+    const { VectorClient } = await import('../lib/storage/vector-client.mjs');
+    const vectorClient = new VectorClient({ env: process.env });
+    const vectorOk = await vectorClient.isHealthy();
+    add('Vector backend (LanceDB) reachable', vectorOk);
 
     const { regenerateDocs } = await import('../lib/auto-docs.mjs');
     const { changed: stale } = await regenerateDocs({ rootDir: ROOT_DIR, check: true });
@@ -943,35 +952,6 @@ async function cmdDoctor() {
       add('Observation size', false, true);
     }
 
-    // Only run the schema migration check when SQL is both configured AND
-    // currently reachable. If the SQL check above already failed (sqlReachable
-    // is false) this check will also fail with the same ECONNREFUSED and would
-    // produce a redundant second warning about the same offline server.
-    if (sqlConfig.configured && sqlReachable) {
-      try {
-        const migClient = createSqlClient(process.env);
-        if (migClient) {
-          const { describeMigrations } = await import('../lib/storage/migrations.mjs');
-          const m = await describeMigrations(migClient);
-          await closeSqlClient(migClient);
-          const ok = !!m.ok && m.drift.length === 0;
-          let label = 'Schema migrations applied + no drift';
-          if (!ok && m.drift && m.drift.length > 0) {
-            const repairable = m.drift.filter((d) => d.idempotent).length;
-            const notRepairable = m.drift.length - repairable;
-            if (notRepairable === 0) {
-              label = `Schema migrations: ${m.drift.length} drifted (all idempotent — run \`construct storage repair-migrations --yes\`)`;
-            } else {
-              label = `Schema migrations: ${m.drift.length} drifted (${notRepairable} non-idempotent — write a new migration file)`;
-            }
-          }
-          add(label, ok, true);
-        }
-      } catch {
-        add('Schema migrations applied + no drift', false, true);
-      }
-    }
-
     try {
       const { detectBeadsDrift } = await import('../lib/beads/drift.mjs');
       const drift = detectBeadsDrift();
@@ -1001,24 +981,6 @@ async function cmdDoctor() {
       add('cm available', false, true);
     }
 
-    try {
-      const dockerCli = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['docker'], { stdio: 'pipe' });
-      let dockerOk = false;
-      let dockerNote = 'Docker not installed (optional — managed Postgres needs it)';
-      if (dockerCli.status === 0) {
-        const dockerInfo = spawnSync('docker', ['info'], { stdio: 'pipe' });
-        if (dockerInfo.status === 0) {
-          dockerOk = true;
-          dockerNote = 'Docker daemon reachable';
-        } else {
-          dockerNote = 'Docker CLI installed but daemon not reachable — run `construct up` on macOS to auto-start, or start Docker manually';
-        }
-      }
-      add(dockerOk ? 'Docker daemon reachable' : `Docker daemon reachable (${dockerNote})`, dockerOk, true);
-    } catch {
-      add('Docker daemon reachable', false, true);
-    }
-
     try {
       const failuresPath = path.join(HOME, '.cx', 'hook-failures.jsonl');
       if (fs.existsSync(failuresPath)) {
@@ -1069,6 +1031,26 @@ async function cmdDoctor() {
     add('Registry integrity check', false);
   }
 
+  // Reconciliation drift (ADR-0027). Any task reporting needsRepair is surfaced
+  // with its summary and the exact `construct sync --reconcile=<id>` command.
+  // Auto tasks that still show drift (e.g. a run with --no-reconcile) and all
+  // ask tasks both land here, since ask tasks never run from the auto pass.
+  let reconcileDrift = [];
+  try {
+    const { listReconciliations } = await import('../lib/reconcile/index.mjs');
+    const tasks = await listReconciliations();
+    reconcileDrift = tasks.filter((t) => t.needsRepair);
+    add(
+      reconcileDrift.length === 0
+        ? 'Reconciliation drift: none'
+        : `Reconciliation drift: ${reconcileDrift.length} task${reconcileDrift.length === 1 ? '' : 's'} need repair (see below)`,
+      reconcileDrift.length === 0,
+      true,
+    );
+  } catch (err) {
+    add(`Reconciliation drift check failed: ${err.message}`, false, true);
+  }
+
   println('Construct Health Check');
   println('══════════════════════');
   println('');
@@ -1080,6 +1062,17 @@ async function cmdDoctor() {
     else if (check.optional) warnCount += 1;
     else failCount += 1;
   }
+
+  if (reconcileDrift.length > 0) {
+    println('');
+    println('Reconciliation drift:');
+    for (const task of reconcileDrift) {
+      println(`  ⚠ ${task.id} (${task.safety})`);
+      if (task.summary) println(`       ${task.summary}`);
+      println(`       fix: construct sync --reconcile=${task.id}`);
+    }
+  }
+
   println('');
   println(`Results: ${okCount} passed, ${warnCount} warnings, ${failCount} failed`);
   if (failCount > 0) process.exit(1);
@@ -1178,6 +1171,16 @@ async function cmdUp(args = []) {
     else warn(`${svc.name}: ${svc.note}`);
   }
 
+  // Show Langfuse credentials guidance after first start
+  const langfuseService = results.find(r => r.name === 'Langfuse');
+  if (langfuseService && langfuseService.status === 'started' && langfuseService.note?.includes('auto-configured')) {
+    println('');
+    info('Langfuse credentials:');
+    info('  Dashboard: http://localhost:54330 (login: admin@construct.local / construct-admin)');
+    info('  API keys auto-saved to ~/.construct/config.env');
+    info('  Run `construct status` anytime to view credentials');
+  }
+
   if (recovery) {
     println('');
     info(`Recovery: ${recovery.message}`);
@@ -1410,6 +1413,44 @@ async function cmdIngest(args) {
   }
 }
 
+async function cmdExport(args) {
+  // construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>]
+  // Optional capability per ADR-0024: requires pandoc on PATH (and typst for PDF).
+  // Absent tooling returns a structured "install X" error, not a crash.
+
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const inputPath = positional[0];
+  const toFlag = args.find((a) => a.startsWith('--to='))?.split('=')[1];
+  const outFlag = args.find((a) => a.startsWith('--output='))?.split('=')[1];
+  const detectOnly = args.includes('--detect');
+
+  const { detect, exportMarkdown, EXPORT_FORMATS } = await import('../lib/document-export.mjs');
+
+  if (detectOnly) {
+    const format = toFlag || 'pdf';
+    println(JSON.stringify(detect(format), null, 2));
+    return;
+  }
+
+  if (!inputPath) {
+    errorln('Usage: construct export <markdown-file> --to=<pdf|docx|html> [--output=<path>] [--detect]');
+    process.exit(1);
+  }
+  if (!toFlag) {
+    errorln(`--to is required. Supported formats: ${EXPORT_FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const resolvedIn = path.resolve(process.cwd(), inputPath);
+  const resolvedOut = outFlag ? path.resolve(process.cwd(), outFlag) : null;
+  const result = exportMarkdown({ inputPath: resolvedIn, outputPath: resolvedOut, format: toFlag });
+  if (!result.ok) {
+    errorln(result.message);
+    process.exit(result.missing?.length ? 2 : 1);
+  }
+  ok(result.message);
+}
+
 async function cmdInfer(args) {
   try {
     const result = await runInferCli(args, { cwd: process.cwd() });
@@ -1454,49 +1495,11 @@ async function cmdStorage(args) {
     println(`Reconciled observations: re-embedded ${result.reembedded} of ${result.checked} (model ${result.model}).`);
     return;
   }
-  if (action === 'migrations') {
-    const { describeMigrations } = await import('../lib/storage/migrations.mjs');
-    const sqlClient = createSqlClient(process.env);
-    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
-    try {
-      const report = await describeMigrations(sqlClient);
-      println(JSON.stringify(report, null, 2));
-      if (report.drift?.length > 0) process.exit(2);
-    } finally {
-      await closeSqlClient(sqlClient);
-    }
-    return;
-  }
-  if (action === 'repair-migrations') {
-    const confirm = rest.includes('--yes');
-    if (!confirm) {
-      errorln('This re-applies drifted migrations (idempotent only) and updates their recorded SHA.');
-      errorln('Destructive migrations (DROP / TRUNCATE / ALTER…DROP / DELETE) are refused.');
-      errorln('Re-run with --yes to proceed.');
-      process.exit(1);
-    }
-    const { runMigrations } = await import('../lib/storage/migrations.mjs');
-    const sqlClient = createSqlClient(process.env);
-    if (!sqlClient) { errorln('No DATABASE_URL configured.'); process.exit(1); }
-    try {
-      const result = await runMigrations(sqlClient, { repair: true });
-      println(JSON.stringify({
-        applied: result.applied,
-        repaired: result.repaired,
-        skipped: result.skipped,
-        drift: result.drift,
-      }, null, 2));
-      if (result.drift.length > 0) {
-        errorln('');
-        errorln('Refused to repair non-idempotent migrations:');
-        for (const d of result.drift) errorln(`  ${d.filename}`);
-        process.exit(2);
-      }
-      info(`Repaired ${result.repaired.length} migration(s); applied ${result.applied.length} new.`);
-    } finally {
-      await closeSqlClient(sqlClient);
-    }
-    return;
+  if (action === 'migrations' || action === 'repair-migrations') {
+    // Postgres schema migrations were removed with the SQL backend; LanceDB
+    // tables are created on demand and need no migration runner.
+    errorln('construct storage ' + action + ' is no longer supported: Postgres was removed.');
+    process.exit(1);
   }
   if (action === 'sync') {
     const result = await syncFileStateToSql(process.cwd(), { env: process.env, project: inferProjectName(process.cwd()) });
@@ -1976,7 +1979,17 @@ async function cmdEmbeddedTriage(args) {
     input = fs.readFileSync(0, 'utf8');
   }
   if (!input.trim() && !ingestion?.error) {
-    errorln('Usage: construct intake classify --json [--text "..." | --file <path> | <stdin>] [--source <path>] [--artifact-type <t>] [--available-roles a,b]');
+    // This is an embedded-contract verb: an embedder that pipes empty/no input
+    // must still get a parseable, versioned envelope — not a bare exit. Emit a
+    // typed error envelope on stdout so the contract holds, and exit non-zero so
+    // shell callers still see failure.
+    const { wrapResponse } = await import('../lib/embedded-contract/envelope.mjs');
+    const envelope = wrapResponse({
+      surface: 'cli',
+      warnings: ['No artifact provided — pass --text "...", --file <path>, or pipe content on stdin.'],
+      data: { error: { code: 'missing_input', message: 'intake classify requires an artifact to classify; received empty input.' } },
+    });
+    println(JSON.stringify(envelope, null, 2));
     process.exit(1);
   }
   const request = {
@@ -3364,6 +3377,47 @@ async function cmdOrchestrate(args) {
   const flag = (name) => { const i = rest.indexOf(name); return i !== -1 ? rest[i + 1] : undefined; };
   const wantsJson = rest.includes('--json') || args.includes('--json');
 
+  // Thin-client mode: drive the local orchestration daemon over HTTP instead of
+  // running in-process, proving the engine-as-service contract editors/CI use.
+  if (rest.includes('--remote')) {
+    const remoteVal = flag('--remote');
+    const base = (remoteVal && /^https?:\/\//.test(remoteVal)) ? remoteVal.replace(/\/$/, '') : `http://${process.env.BIND_HOST || '127.0.0.1'}:${process.env.PORT || '4242'}`;
+    const { getDashboardToken } = await import('../lib/server/auth.mjs');
+    const token = getDashboardToken();
+    const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+    const positional = rest.filter((a) => !a.startsWith('--'));
+    try {
+      if (sub === 'run') {
+        const text = flag('--text') || positional.join(' ').trim();
+        if (!text) { errorln('Usage: construct orchestrate run "<request>" --remote [--strategy S] [--worker-backend provider] [--json]'); process.exit(1); }
+        const res = await fetch(`${base}/api/orchestration/runs`, { method: 'POST', headers, body: JSON.stringify({ request: text, workflowType: flag('--workflow-type'), requestedStrategy: flag('--strategy') || 'auto', host: flag('--host'), hostModel: flag('--host-model'), hostProvider: flag('--host-provider'), workerBackend: flag('--worker-backend'), fileCount: Number(flag('--file-count') || 0), moduleCount: Number(flag('--module-count') || 0) }) });
+        const env = await res.json();
+        if (!res.ok) { errorln(`Daemon error (${res.status}): ${env.error || 'unknown'}`); process.exit(1); }
+        if (wantsJson) { println(JSON.stringify(env.data, null, 2)); return; }
+        println(`Run ${env.data.runId} started on ${base} — ${env.data.status} · executionMode=${env.data.execution?.executionMode}. Poll: construct orchestrate status ${env.data.runId} --remote`);
+        return;
+      }
+      if (sub === 'status') {
+        const runId = positional[0];
+        const path = runId ? `/api/orchestration/runs/${encodeURIComponent(runId)}` : '/api/orchestration/runs';
+        const res = await fetch(`${base}${path}`, { headers });
+        const env = await res.json();
+        if (!res.ok) { errorln(`Daemon error (${res.status}): ${env.error || 'unknown'}`); process.exit(1); }
+        if (wantsJson) { println(JSON.stringify(env.data, null, 2)); return; }
+        if (runId) {
+          println(`Run ${env.data.runId} — ${env.data.status} · executionMode=${env.data.execution?.executionMode}`);
+          for (const t of env.data.tasks || []) println(`  ${t.id} ${t.role} — ${t.status}${t.output ? ` (${t.output.length} chars)` : ''}`);
+        } else {
+          for (const r of env.data.runs || []) println(`  ${r.runId} — ${r.status} · ${r.executionMode || ''} · ${r.createdAt}`);
+        }
+        return;
+      }
+    } catch (err) {
+      errorln(`Could not reach the orchestration daemon at ${base}: ${err.message}. Start it with \`construct dashboard\`.`);
+      process.exit(1);
+    }
+  }
+
   if (sub === 'run') {
     const { runOrchestration, planRun, hostAdapterMetadata } = await import('../lib/orchestration/runtime.mjs');
     const positional = rest.filter((a, i) => !a.startsWith('--') && !(i > 0 && rest[i - 1].startsWith('--') && !['--no-construct', '--no-execute', '--json'].includes(rest[i - 1])));
@@ -3377,6 +3431,7 @@ async function cmdOrchestrate(args) {
       host: flag('--host'),
       hostModel: flag('--host-model'),
       hostProvider: flag('--host-provider'),
+      workerBackend: flag('--worker-backend'),
       fileCount: Number(flag('--file-count') || 0),
       moduleCount: Number(flag('--module-count') || 0),
     };
@@ -3386,6 +3441,9 @@ async function cmdOrchestrate(args) {
     if (run.execution.degraded) println(`  degraded: ${run.execution.degradationReason}`);
     if (run.tasks.length) println(`  tasks: ${run.tasks.map((t) => `${t.role}(${t.status})`).join(' → ')}`);
     else println('  tasks: none (no Construct-owned specialist sequence for this execution mode)');
+    for (const t of run.tasks) {
+      if (t.reasoning) println(`  ↳ ${t.role} reasoning: ${t.reasoning.length > 300 ? `${t.reasoning.slice(0, 300)}…` : t.reasoning}`);
+    }
     return;
   }
 
@@ -3397,7 +3455,10 @@ async function cmdOrchestrate(args) {
       if (!run) { errorln(`Run not found: ${runId}`); process.exit(1); }
       if (wantsJson) { println(JSON.stringify(hostAdapterMetadata(run), null, 2)); return; }
       println(`Run ${run.runId} — ${run.status} · executionMode=${run.execution.executionMode}`);
-      for (const t of run.tasks) println(`  ${t.id} ${t.role} — ${t.status}`);
+      for (const t of run.tasks) {
+        println(`  ${t.id} ${t.role} — ${t.status}`);
+        if (t.reasoning) println(`    reasoning: ${t.reasoning.length > 300 ? `${t.reasoning.slice(0, 300)}…` : t.reasoning}`);
+      }
       return;
     }
     const runs = await getRuns(process.cwd());
@@ -4394,99 +4455,10 @@ async function cmdLintContracts() {
 }
 
 async function cmdBackup(args) {
-  const sub = args[0];
-
-  if (!sub || sub === 'create') {
-    const includeSecrets = args.includes('--include-secrets');
-    const noPrune = args.includes('--no-prune');
-    const keepArg = args.find((a) => a.startsWith('--keep='));
-    const keep = keepArg
-      ? Number(keepArg.split('=')[1])
-      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
-    const { createBackup, pruneBackups } = await import('../lib/storage/backup.mjs');
-    println('Creating backup…');
-    try {
-      const result = await createBackup({ includeSecrets });
-      ok(`Backup created: ${result.path}`);
-      println(`  Contents: ${result.manifest.contents.join(', ') || '(empty)'}`);
-      if (!includeSecrets) println('  Secrets redacted. Use --include-secrets to include them.');
-      if (!noPrune) {
-        const pruned = pruneBackups({ keep });
-        if (pruned.removed.length) {
-          println(`  Auto-pruned ${pruned.removed.length} old backup(s); kept ${pruned.kept}.`);
-        }
-      }
-    } catch (err) {
-      errorln(`Backup failed: ${err.message}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (sub === 'prune') {
-    const keepArg = args.find((a) => a.startsWith('--keep='));
-    const keep = keepArg
-      ? Number(keepArg.split('=')[1])
-      : Number(process.env.CONSTRUCT_BACKUP_RETAIN || 10);
-    const { pruneBackups } = await import('../lib/storage/backup.mjs');
-    const result = pruneBackups({ keep });
-    if (result.removed.length === 0) {
-      println(`Nothing to prune (have ${result.kept}, keeping ${keep}).`);
-    } else {
-      ok(`Pruned ${result.removed.length} backup(s); kept ${result.kept}.`);
-      for (const r of result.removed) println(`  removed ${r}`);
-    }
-    return;
-  }
-
-  if (sub === 'verify') {
-    const archivePath = args[1];
-    if (!archivePath) { errorln('Usage: construct backup verify <archive>'); process.exit(1); }
-    const { verifyBackup } = await import('../lib/storage/backup.mjs');
-    const result = await verifyBackup(archivePath);
-    if (result.ok) {
-      ok('Backup verified — all checksums match.');
-    } else {
-      errorln(`Backup verification failed:\n  ${result.errors.join('\n  ')}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (sub === 'restore') {
-    const archivePath = args[1];
-    const yes = args.includes('--yes');
-    if (!archivePath) { errorln('Usage: construct backup restore <archive> [--yes]'); process.exit(1); }
-    if (!yes) {
-      println(`About to restore from: ${archivePath}`);
-      println('This will overwrite observations, sessions, config.env, and registry.json.');
-      println('Press Ctrl+C to cancel, or re-run with --yes to proceed.');
-      await new Promise((r) => setTimeout(r, 3000));
-    }
-    const { restoreBackup } = await import('../lib/storage/backup.mjs');
-    const result = await restoreBackup(archivePath, { yes });
-    if (result.ok) {
-      ok(`Restored: ${result.restored.join(', ')}`);
-    } else {
-      if (result.restored.length) println(`Partially restored: ${result.restored.join(', ')}`);
-      errorln(`Errors:\n  ${result.errors.join('\n  ')}`);
-      process.exit(1);
-    }
-    return;
-  }
-
-  if (sub === 'list') {
-    const { listBackups } = await import('../lib/storage/backup.mjs');
-    const backups = listBackups();
-    if (!backups.length) { println('No backups found.'); return; }
-    for (const b of backups) {
-      const mb = (b.size / 1024 / 1024).toFixed(1);
-      println(`  ${b.name}  (${mb} MB)  ${b.mtime.toISOString().slice(0, 19)}`);
-    }
-    return;
-  }
-
-  errorln(`Unknown backup subcommand: ${sub}. Available: create, verify, restore, list, prune`);
+  // Postgres-era backups were removed with the SQL backend (lib/storage/backup.mjs).
+  // State is now Git-backed (.cx/) plus the local LanceDB index under .cx/lancedb.
+  void args;
+  errorln('construct backup is no longer supported: Postgres was removed. Commit .cx/ for Git-backed state; the LanceDB index lives under .cx/lancedb.');
   process.exit(1);
 }
 
@@ -5059,6 +5031,7 @@ async function readStdin() {
 const handlers = new Map([
   // Core
   ['dev', cmdUp],
+  ['dashboard', cmdServe],
   ['stop', cmdDown],
   ['status', cmdStatus],
   ['install', cmdSetup],
@@ -5080,6 +5053,7 @@ const handlers = new Map([
   ['diff', cmdDiff],
   ['distill', cmdDistill],
   ['ingest', cmdIngest],
+  ['export', cmdExport],
   ['infer', cmdInfer],
   ['search', cmdSearch],
   ['storage', cmdStorage],
@@ -5119,6 +5093,10 @@ const handlers = new Map([
   ['models', cmdModels],
   ['execution', cmdExecution],
   ['orchestrate', cmdOrchestrate],
+  ['acp', async () => {
+    const { runAcpServer } = await import('../lib/acp/server.mjs');
+    runAcpServer({ input: process.stdin, output: process.stdout, env: process.env, defaultCwd: process.cwd() });
+  }],
   ['beads:stats', async (args) => {
     const { getContentionStats, getHumanStatus } = await import('../lib/beads-optimistic.mjs');
     const jsonOutput = args.includes('--json');

package/bin/construct-postinstall.mjs

@@ -24,6 +24,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { stageProjectAdapters } from '../lib/install/stage-project.mjs';
+import { missingIgnorePatterns } from '../lib/host-disposition.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(HERE, '..');
@@ -70,23 +71,17 @@ try {
   }
 } catch { /* fall through */ }
 
-// `npm i -g @geraldmaron/construct` runs the postinstall with
-// npm_config_global=true. Wire the `construct` front-door agent into the
-// user's home directories so it's reachable from every host (Claude Code,
-// Codex, Copilot, OpenCode) immediately after a global install. Specialists
-// stay project-only and land when the user runs `construct init` in a repo.
+// ADR-0029: machine-scope writes are opt-in. The postinstall hook for a global
+// install prints scope guidance and exits; `~/.claude/CLAUDE.md`,
+// `~/.claude/settings.json`, and `~/.construct/*` land only when the user runs
+// `construct install --scope=user`, so the consent point is visible.
 
 if (process.env.npm_config_global === 'true' || process.env.npm_config_global === true) {
-  const syncScript = path.join(PKG_ROOT, 'scripts', 'sync-specialists.mjs');
-  if (existsSync(syncScript)) {
-    log('global install detected; syncing front-door agent into ~/');
-    const result = spawnSync(process.execPath, [syncScript, '--global'], {
-      stdio: 'inherit',
-    });
-    if (result.status !== 0) {
-      fail(`Global front-door sync failed (exit ${result.status}).`, 'Run `construct sync --global` to complete it.');
-    }
-  }
+  log('global install detected; machine-scope setup is opt-in (ADR-0029)');
+  log('to wire ~/.construct/* and the front-door agent, run:');
+  log('  construct install --scope=user');
+  log('to set up a project, cd into it and run:');
+  log('  construct init');
   process.exit(0);
 }
 
@@ -114,6 +109,21 @@ try {
     pkgVersion: PKG_VERSION,
     log,
   });
+
+  // ADR-0027: Ensure .gitignore covers the newly staged adapters (construct-f6l6).
+  // Idempotent: missingIgnorePatterns returns only patterns not already present.
+  const giPath = path.join(initCwd, '.gitignore');
+  const existing = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
+  const missing = missingIgnorePatterns(existing);
+  if (missing.length > 0) {
+    const HEADER = '# Construct — generated adapters, launcher, and runtime state.';
+    const SUBHEADER = '# Machine-specific, recreated by `construct sync`; never source (ADR-0027).';
+    const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+    const block = `${prefix}\n${HEADER}\n${SUBHEADER}\n${missing.join('\n')}\n`;
+    const { appendFileSync } = await import('node:fs');
+    appendFileSync(giPath, block, 'utf8');
+    log(`appended ${missing.length} Construct ignore pattern(s) to .gitignore`);
+  }
 } catch (err) {
   fail(`Adapter staging failed: ${err.message}`, 'The package is installed; run `npx construct init` in this project to complete setup.');
   // Intentionally exit 0: staging is best-effort completion, and a non-zero exit