@geraldmaron/construct 1.0.20 → 1.0.23

package/README.md

@@ -22,12 +22,14 @@ Install the CLI (once per machine):
 npm install -g @geraldmaron/construct
 ```
 
-Bootstrap local services (once per machine):
+Bootstrap local services (once per machine, opt-in to machine-scope writes):
 
 ```bash
-construct install --yes
+construct install --scope=user --yes
 ```
 
+`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
+
 Initialize a project:
 
 ```bash
@@ -37,7 +39,7 @@ construct init --yes
 
 `construct init` scaffolds the project (`.cx/`, `AGENTS.md`, `plan.md`, adapters) and starts the local services by default. Pass `--no-start` to skip service startup, or `--interactive` for the guided flow.
 
-Open your editor and talk to `@construct`. A walkthrough lives in `construct_guide.md` at your project root.
+Open your editor and talk to `@construct`. A walkthrough lives in `.cx/construct_guide.md` (gitignored — local reference only).
 
 No Node? Try `brew install geraldmaron/construct/construct`. Cloning a project that already uses Construct? `npx -y @geraldmaron/construct init` wires it up.
 
@@ -97,6 +99,18 @@ First run downloads `uv` and creates `.cx/runtime/docling/.venv` (~1.5 GB includ
 
 Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/concepts/gates-and-enforcement).
 
+## Footprint contract
+
+Construct's writes are scoped and disclosed up front. The default `construct install` (no flag) writes nothing — it prints scope guidance. Project writes happen only under `construct init` inside a project directory; machine writes happen only under `construct install --scope=user`, with an itemized interactive consent prompt for any global Claude Code config mutation.
+
+| Scope | Trigger | Paths |
+|---|---|---|
+| Project | `construct init` | `.construct/`, `.cx/`, `.claude/` adapter tree, host adapters (`.codex/`, `.opencode/`, `.cursor/`, `.vscode/`), `construct.config.json`, marker block in `CLAUDE.md` / `AGENTS.md`, `.gitignore` append, `.beads/` |
+| Machine | `construct install --scope=user` | `~/.construct/config.env`, `~/.construct/lib` (symlink), `~/.construct/services/`, `~/Library/LaunchAgents/` (macOS), MCP entries in `~/.config/opencode/opencode.json` and `~/.codex/config.toml`, marker block in `~/.claude/CLAUDE.md`, hook injection in `~/.claude/settings.json` (last two require interactive consent or `--yes`) |
+| Never touched | — | Shell rc files (`~/.bashrc`, `~/.zshrc`), npm global config, `git config --global` |
+
+Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md).
+
 ## Learning loops
 
 Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
@@ -114,11 +128,12 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 | Command | What it does |
 |---|---|
+| `construct dashboard` | Start the local dashboard/orchestration daemon (or --token to mint a dashboard token) |
 | `construct dev` | Start services for development |
 | `construct docs` | Documentation commands |
 | `construct doctor` | Check installation health |
 | `construct init` | Project setup (once per repo): scaffold .cx/, AGENTS.md, plan.md, adapters |
-| `construct install` | Machine setup (once per machine): Docker, cm/cass, config, embeddings |
+| `construct install` | Machine setup (scoped per ADR-0029): --scope=project\|user\|both, default project |
 | `construct intake` | View and process the active profile's intake queue (queue label varies by profile) |
 | `construct profile` | Manage the active org profile and its lifecycle (draft, promote, archive, health) |
 | `construct recommendations` | View and manage artifact recommendations |
@@ -136,6 +151,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct customer` | Manage customer profiles for product intelligence |
 | `construct distill` | Distill documents with query-focused chunking |
 | `construct drop` | Ingest file from Downloads/Desktop |
+| `construct export` | Export markdown to PDF/DOCX/HTML via Pandoc + Typst (optional system binaries; ADR-0024) |
 | `construct graph` | Task graph management |
 | `construct handoffs` | List and inspect session handoff files in .cx/handoffs/ |
 | `construct headhunt` | Create domain expertise overlays |
@@ -157,13 +173,14 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 | Command | What it does |
 |---|---|
+| `construct acp` | Run Construct as an Agent Client Protocol (ACP) server over stdio for Zed/JetBrains/VS Code ACP clients |
 | `construct capability` | Describe what this Construct install can do (embedded contract; read-only, secret-free) |
 | `construct claude:allow` | Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it) |
 | `construct execution` | Resolve the execution-capability contract for an embedded workflow (orchestrated vs prompt-only; descriptive, not enforced) |
 | `construct hosts` | Show host support for Construct orchestration |
 | `construct mcp` | Manage MCP integrations |
 | `construct models` | Show or update model tier assignments |
-| `construct orchestrate` | Construct-owned local orchestration runtime (Mode-A: single-process, filesystem-backed, no Docker) |
+| `construct orchestrate` | Construct-owned local orchestration runtime, in-process or against the local daemon (--remote) |
 | `construct plugin` | Manage external Construct plugin manifests |
 
 ### Integrations
@@ -251,6 +268,7 @@ construct/
 ├── bin              CLI entrypoint (`construct`)
 ├── commands         Command prompt assets
 ├── config
+├── dashboard
 ├── db
 ├── deploy
 ├── docs             Architecture notes, runbooks, and documentation contract

package/bin/construct

@@ -65,6 +65,7 @@ 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';
@@ -80,12 +81,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 +246,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 +619,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);
@@ -1069,6 +1105,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 +1136,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 +1245,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 +1487,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() });
@@ -1976,7 +2091,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 +3489,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])));
@@ -3380,12 +3546,15 @@ async function cmdOrchestrate(args) {
       fileCount: Number(flag('--file-count') || 0),
       moduleCount: Number(flag('--module-count') || 0),
     };
-    const run = rest.includes('--no-execute') ? planRun(request, {}) : runOrchestration(request, {});
+    const run = rest.includes('--no-execute') ? await planRun(request, {}) : await runOrchestration(request, {});
     if (wantsJson) { println(JSON.stringify(hostAdapterMetadata(run), null, 2)); return; }
     println(`Run ${run.runId} — ${run.status} · executionMode=${run.execution.executionMode} · backend=${run.workerBackend} · hostRole=${run.hostRole}`);
     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;
   }
 
@@ -3393,14 +3562,17 @@ async function cmdOrchestrate(args) {
     const { getRun, getRuns, hostAdapterMetadata } = await import('../lib/orchestration/runtime.mjs');
     const runId = rest.find((a) => !a.startsWith('--'));
     if (runId) {
-      const run = getRun(process.cwd(), runId);
+      const run = await getRun(process.cwd(), runId);
       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 = getRuns(process.cwd());
+    const runs = await getRuns(process.cwd());
     if (wantsJson) { println(JSON.stringify(runs, null, 2)); return; }
     if (!runs.length) { println('No orchestration runs recorded.'); return; }
     for (const r of runs) println(`  ${r.runId} — ${r.status} · ${r.executionMode || ''} · ${r.createdAt}`);
@@ -5059,6 +5231,7 @@ async function readStdin() {
 const handlers = new Map([
   // Core
   ['dev', cmdUp],
+  ['dashboard', cmdServe],
   ['stop', cmdDown],
   ['status', cmdStatus],
   ['install', cmdSetup],
@@ -5080,6 +5253,7 @@ const handlers = new Map([
   ['diff', cmdDiff],
   ['distill', cmdDistill],
   ['ingest', cmdIngest],
+  ['export', cmdExport],
   ['infer', cmdInfer],
   ['search', cmdSearch],
   ['storage', cmdStorage],
@@ -5119,6 +5293,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

package/lib/acp/server.mjs

@@ -0,0 +1,113 @@
+/**
+ * lib/acp/server.mjs — Construct as an Agent Client Protocol (ACP) server.
+ *
+ * ACP (agentclientprotocol.com) is the editor↔agent standard that lets Zed,
+ * JetBrains, and the VS Code ACP client drive any agent over JSON-RPC 2.0 on
+ * stdio. This makes Construct a first-class native agent in those editors: an
+ * ACP `session/prompt` runs a real multi-specialist orchestration via the same
+ * engine the daemon and the MCP tool use (ADR-0023) — the editor is a thin
+ * client, Construct owns the loop.
+ *
+ * Framing is newline-delimited JSON (one JSON-RPC message per line). Supported
+ * methods: `initialize`, `session/new`, `session/prompt`, `session/cancel`;
+ * progress streams as `session/update` notifications. The prompt bridges to
+ * planRun/executeRun and forwards run-lifecycle events as agent message chunks.
+ */
+
+import { createInterface } from 'node:readline';
+
+const PROTOCOL_VERSION = 1;
+
+function describeEvent(event) {
+  if (event.type === 'planned') return `Planned ${event.tasks ?? ''} specialist task(s).`;
+  if (event.type === 'running') return 'Running orchestration…';
+  if (event.type === 'task') return `· ${event.role ?? 'task'} — ${event.status ?? ''}`;
+  if (event.type === 'completed') return `Completed: ${event.status ?? 'done'}.`;
+  if (event.type === 'error') return `Error: ${event.error?.message ?? 'run failed'}.`;
+  return null;
+}
+
+function summarize(run) {
+  const tasks = (run.tasks || []).map((t) => `- ${t.role} (${t.status})`).join('\n');
+  return `Orchestration ${run.status} — executionMode=${run.execution?.executionMode}.\n${tasks}`;
+}
+
+function textFromPrompt(prompt) {
+  if (!Array.isArray(prompt)) return '';
+  return prompt.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n').trim();
+}
+
+export function runAcpServer({ input, output, env = process.env, defaultCwd = process.cwd() } = {}) {
+  const sessions = new Map();
+  let sessionCounter = 0;
+
+  const write = (msg) => output.write(`${JSON.stringify(msg)}\n`);
+  const respond = (id, result) => write({ jsonrpc: '2.0', id, result });
+  const fail = (id, code, message) => write({ jsonrpc: '2.0', id, error: { code, message } });
+  const notify = (method, params) => write({ jsonrpc: '2.0', method, params });
+  const update = (sessionId, text) => notify('session/update', { sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } });
+
+  async function handlePrompt(id, params) {
+    const sessionId = params?.sessionId;
+    const session = sessions.get(sessionId);
+    if (!session) return fail(id, -32602, `Unknown sessionId: ${sessionId}`);
+    const text = textFromPrompt(params?.prompt);
+    if (!text) return fail(id, -32602, 'prompt has no text content');
+
+    const { planRun, executeRun } = await import('../orchestration/runtime.mjs');
+    const { onRunEvent, isCancelRequested } = await import('../orchestration/events.mjs');
+    try {
+      const planned = await planRun({ request: text, requestedStrategy: 'orchestrated' }, { env, cwd: session.cwd });
+      session.runId = planned.runId;
+      const off = onRunEvent(planned.runId, (event) => {
+        const line = describeEvent(event);
+        if (line) update(sessionId, line);
+      });
+      const run = await executeRun(session.cwd, planned.runId, { env, workerBackend: 'inline' });
+      off();
+      update(sessionId, summarize(run));
+      respond(id, { stopReason: isCancelRequested(planned.runId) ? 'cancelled' : 'end_turn' });
+    } catch (err) {
+      update(sessionId, `Error: ${err.message}`);
+      respond(id, { stopReason: 'refusal' });
+    }
+  }
+
+  async function dispatch(msg) {
+    const { id, method, params } = msg;
+    if (method === 'initialize') {
+      respond(id, {
+        protocolVersion: typeof params?.protocolVersion === 'number' ? params.protocolVersion : PROTOCOL_VERSION,
+        agentCapabilities: { promptCapabilities: { image: false, audio: false, embeddedContext: true } },
+        authMethods: [],
+      });
+      return;
+    }
+    if (method === 'session/new') {
+      const sessionId = `acp-${++sessionCounter}`;
+      sessions.set(sessionId, { cwd: params?.cwd || defaultCwd, runId: null });
+      respond(id, { sessionId });
+      return;
+    }
+    if (method === 'session/prompt') { await handlePrompt(id, params); return; }
+    if (method === 'session/cancel') {
+      const session = sessions.get(params?.sessionId);
+      if (session?.runId) { const { requestCancel } = await import('../orchestration/events.mjs'); requestCancel(session.runId); }
+      return;
+    }
+    if (id !== undefined) fail(id, -32601, `Method not found: ${method}`);
+  }
+
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  rl.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try { msg = JSON.parse(trimmed); } catch { return; }
+    Promise.resolve(dispatch(msg)).catch((err) => {
+      if (msg?.id !== undefined) fail(msg.id, -32603, err.message);
+    });
+  });
+
+  return { close: () => rl.close() };
+}