@geraldmaron/construct 1.0.20 → 1.0.21

package/bin/construct

@@ -3380,7 +3380,7 @@ 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}`);
@@ -3393,14 +3393,14 @@ 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}`);
       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}`);

package/lib/cli-commands.mjs

@@ -250,7 +250,7 @@ export const CLI_COMMANDS = [
     category: 'Work',
     core: false,
     description: 'Convert documents to indexed markdown',
-    usage: 'construct ingest <file> [--strategy=adapter|provider] [--strict] [--legacy-extractor]',
+    usage: 'construct ingest <file> [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--strict] [--legacy-extractor]',
   },
   {
     name: 'infer',

package/lib/config/schema.mjs

@@ -26,6 +26,10 @@ export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cu
 
 export const INGEST_STRATEGIES = ['adapter', 'provider'];
 export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
+export const INGEST_ORCHESTRATIONS = ['prompt-only', 'orchestrated'];
+
+export const ORCHESTRATION_WORKER_BACKENDS = ['inline', 'provider'];
+export const ORCHESTRATION_STORES = ['filesystem', 'sqlite', 'postgres'];
 
 // SessionStart context routing. `auto` keeps the rich payload on stdout for
 // interactive sessions and suppresses it (to a debug log) for non-interactive /
@@ -47,6 +51,11 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   ingest: Object.freeze({
     strategy: 'adapter',
     fallback: 'none',
+    orchestration: 'prompt-only',
+  }),
+  orchestration: Object.freeze({
+    workerBackend: 'inline',
+    store: 'filesystem',
   }),
   telemetry: Object.freeze({
     enabled: true,
@@ -105,6 +114,15 @@ export const FIELD_RULES = {
     fields: {
       strategy: { type: 'string', enum: INGEST_STRATEGIES },
       fallback: { type: 'string', enum: INGEST_FALLBACKS },
+      orchestration: { type: 'string', enum: INGEST_ORCHESTRATIONS },
+    },
+  },
+  orchestration: {
+    type: 'object',
+    required: false,
+    fields: {
+      workerBackend: { type: 'string', enum: ORCHESTRATION_WORKER_BACKENDS },
+      store: { type: 'string', enum: ORCHESTRATION_STORES },
     },
   },
   telemetry: {

package/lib/decisions/enforced-baseline.json

@@ -6,6 +6,7 @@
     "ADR-0018",
     "ADR-0019",
     "ADR-0020",
+    "ADR-0021",
     "any-to-business-strategist",
     "any-to-explorer",
     "architect-to-data-engineer",

package/lib/document-ingest.mjs

@@ -14,7 +14,7 @@ import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
 import { loadProjectConfig } from './config/project-config.mjs';
-import { resolveIngestStrategy, INGEST_STRATEGIES } from './ingest/strategy.mjs';
+import { resolveIngestStrategy, INGEST_STRATEGIES, INGEST_ORCHESTRATION_STRATEGIES } from './ingest/strategy.mjs';
 import { extractViaProvider } from './ingest/provider-extract.mjs';
 
 const DEFAULT_TARGET_DIR = '.cx/knowledge/internal';
@@ -167,6 +167,7 @@ export async function ingestDocuments(inputPaths, {
   strict = false,
   highFidelity = true,
   strategy = null,
+  orchestration = null,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -182,7 +183,7 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const { config } = loadProjectConfig(cwd, env);
-  const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy });
+  const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy, orchestrationOverride: orchestration, cwd });
 
   const results = [];
   let totalDrops = 0;
@@ -266,9 +267,11 @@ export async function ingestDocuments(inputPaths, {
     ingestion: {
       strategy: resolvedStrategy.strategy,
       fallback: resolvedStrategy.fallback,
+      orchestration: resolvedStrategy.orchestration,
       model: resolvedStrategy.model,
       provider: resolvedStrategy.provider,
       fallbackApplied,
+      execution: resolvedStrategy.execution,
     },
   };
 }
@@ -282,6 +285,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let strict = false;
   let highFidelity = true;
   let strategy = null;
+  let orchestration = null;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
@@ -289,6 +293,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--strategy=')) strategy = arg.split('=').slice(1).join('=');
     else if (arg === '--strategy') strategy = '';
+    else if (arg.startsWith('--orchestration=')) orchestration = arg.split('=').slice(1).join('=');
     else if (arg === '--sync') sync = true;
     else if (arg === '--strict') strict = true;
     else if (arg === '--legacy-extractor') highFidelity = false;
@@ -299,8 +304,9 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--sync] [--strict] [--legacy-extractor]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--legacy-extractor]\n` +
       `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
+      `  --orchestration: prompt-only (deterministic extraction) or orchestrated (engage the specialist chain)\n` +
       `  --strict: exit non-zero if any extraction drops occur\n` +
       `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
@@ -309,6 +315,9 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   if (strategy !== null && strategy !== '' && !INGEST_STRATEGIES.includes(strategy)) {
     throw new Error(`Unsupported strategy: ${strategy}. Valid strategies: ${INGEST_STRATEGIES.join(', ')}`);
   }
+  if (orchestration !== null && !INGEST_ORCHESTRATION_STRATEGIES.includes(orchestration)) {
+    throw new Error(`Unsupported orchestration: ${orchestration}. Valid values: ${INGEST_ORCHESTRATION_STRATEGIES.join(', ')}`);
+  }
   const knowledgeTargets = KNOWLEDGE_SUBDIRS.map((s) => `knowledge/${s}`);
   if (!['sibling', ...knowledgeTargets].includes(target)) {
     throw new Error(
@@ -316,5 +325,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, orchestration: orchestration || null, env });
 }

package/lib/embedded-contract/triage.mjs

@@ -16,6 +16,7 @@ import { classifyRdIntake } from '../intake/classify.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { workflowTypeForIntake } from './workflow-defs.mjs';
+import { resolveExecution } from './execution.mjs';
 
 const CONFIDENCE_FLOOR = 0.6;
 
@@ -46,7 +47,7 @@ function buildRiskFactors(triage) {
  * @returns {object}
  */
 export function recommendPlan(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
-  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null } = request;
+  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null, host, hostModel, hostProvider, constructStrategy = 'auto' } = request;
   const warnings = [];
 
   // Surface extraction provenance and flag low-yield/truncated inputs so a
@@ -109,6 +110,26 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
   if (canExecute) nextStepOptions.push({ action: 'invoke-workflow', description: 'Invoke the recommended role chain as an embedded workflow.' });
   if (!canExecute) nextStepOptions.push({ action: 'clarify', description: 'Request more detail; classification confidence is low or unknown.' });
 
+  const suggestedWorkflowType = workflowTypeForIntake(triage.intakeType);
+
+  // Execution preview: forecast the executionMode an invocation of the suggested
+  // workflow would resolve to, but only when the host supplies context — absent
+  // it, forcing a model resolution on every triage call would be wasteful and
+  // the preview would be uninformative. null keeps the field parity-stable.
+  let execution = null;
+  if (suggestedWorkflowType && (hostModel || hostProvider || (constructStrategy && constructStrategy !== 'auto'))) {
+    const e = resolveExecution({ workflowType: suggestedWorkflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider }, { env, cwd });
+    execution = {
+      executionMode: e.executionMode,
+      effectiveStrategy: e.effectiveStrategy,
+      requestedStrategy: e.requestedStrategy,
+      constructCapabilitiesActive: e.constructCapabilitiesActive,
+      degraded: e.degraded,
+      degradationReason: e.degradationReason,
+      semantics: e.semantics,
+    };
+  }
+
   return {
     classification: { intakeType: triage.intakeType, rdStage: triage.rdStage },
     ingestion,
@@ -117,7 +138,8 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
     primaryOwner,
     recommendedAction: triage.recommendedAction,
     recommendedChain: chain,
-    suggestedWorkflowType: workflowTypeForIntake(triage.intakeType),
+    suggestedWorkflowType,
+    execution,
     roleRationale: rationale,
     suggestedSkills,
     evidenceRequirements,

package/lib/embedded-contract/workflow-invoke.mjs

@@ -26,6 +26,7 @@ import { recordApprovalRequest } from '../roles/approval-surface.mjs';
 import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { resolveExecution } from './execution.mjs';
 import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs';
 
 const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
@@ -91,6 +92,7 @@ function errorResult({ workflowId, traceId, approvalMode, code, message, warning
  * @param {string} [request.host]
  * @param {string} [request.hostModel]
  * @param {string} [request.hostProvider]
+ * @param {string} [request.constructStrategy]  orchestrated | prompt-only | auto (execution mode)
  * @param {object} [opts]   { env, cwd }
  * @returns {Promise<object>}
  */
@@ -98,6 +100,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const {
     workflowType, context = {}, roleStrategy = 'auto', requestedRoles,
     approvalMode, trace = true, host, hostModel, hostProvider, ingestion = null,
+    constructStrategy = 'auto',
   } = request;
   const warnings = [];
   if (ingestion) {
@@ -129,6 +132,23 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   );
   for (const w of modelWarnings) warnings.push(`model-resolution: ${w}`);
 
+  // The execution-capability contract reports the PLANNED executionMode for this
+  // run (descriptive, not enforced — ADR-0019). Construct returns a plan; the
+  // host runtime executes it, so this never claims observed specialist execution.
+  const executionData = resolveExecution(
+    { workflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider, requestedTier: def.tier },
+    { env, cwd },
+  );
+  const execution = {
+    executionMode: executionData.executionMode,
+    effectiveStrategy: executionData.effectiveStrategy,
+    requestedStrategy: executionData.requestedStrategy,
+    constructCapabilitiesActive: executionData.constructCapabilitiesActive,
+    degraded: executionData.degraded,
+    degradationReason: executionData.degradationReason,
+    semantics: executionData.semantics,
+  };
+
   const primaryOwner = selectedRoles[0];
   const facts = contractFacts(primaryOwner);
   const skillsApplied = skillsForChain(selectedRoles, map);
@@ -204,6 +224,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     roleRationale: rationale,
     skillsApplied,
     modelResolution,
+    execution,
     outputs,
     recommendations,
     evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },

package/lib/ingest/strategy.mjs

@@ -15,12 +15,21 @@
 
 import { resolveSetting } from '../config/project-config.mjs';
 import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
+import { resolveExecution } from '../embedded-contract/execution.mjs';
 
 export const INGEST_STRATEGIES = ['adapter', 'provider'];
 export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
 
+// Orchestration is a second, independent axis from extraction (adapter|provider):
+// `prompt-only` runs ingest as a deterministic extraction pass; `orchestrated`
+// engages the Construct specialist chain for the evidence-ingest workflow. Both
+// axes coexist — extraction is HOW bytes become text, orchestration is WHETHER
+// specialists process the result.
+export const INGEST_ORCHESTRATION_STRATEGIES = ['prompt-only', 'orchestrated'];
+
 export const DEFAULT_INGEST_STRATEGY = 'adapter';
 export const DEFAULT_INGEST_FALLBACK = 'none';
+export const DEFAULT_INGEST_ORCHESTRATION = 'prompt-only';
 
 function coerceEnum(value, allowed) {
   if (typeof value !== 'string') return null;
@@ -55,11 +64,13 @@ function resolveProviderModel({ env, registryPath }) {
  * @param {object} opts
  * @param {object} [opts.config]      loaded project config object
  * @param {Record<string,string>} [opts.env]
- * @param {string} [opts.override]    explicit strategy override (CLI flag)
+ * @param {string} [opts.override]    explicit extraction strategy override (CLI flag)
+ * @param {string} [opts.orchestrationOverride] explicit orchestration override (CLI flag)
+ * @param {string} [opts.cwd]
  * @param {string} [opts.registryPath]
- * @returns {{strategy:string, fallback:string, model:(string|null), provider:(string|null), modelResolution:(object|null)}}
+ * @returns {{strategy:string, fallback:string, orchestration:string, model:(string|null), provider:(string|null), modelResolution:(object|null), execution:object}}
  */
-export function resolveIngestStrategy({ config = null, env = process.env, override = null, registryPath = null } = {}) {
+export function resolveIngestStrategy({ config = null, env = process.env, override = null, orchestrationOverride = null, cwd = process.cwd(), registryPath = null } = {}) {
   const overrideStrategy = coerceEnum(override, INGEST_STRATEGIES);
 
   const fromSettings = resolveSetting({
@@ -82,14 +93,35 @@ export function resolveIngestStrategy({ config = null, env = process.env, overri
   });
   const fallback = coerceEnum(fallbackSetting.value, INGEST_FALLBACKS) || DEFAULT_INGEST_FALLBACK;
 
+  const orchestrationSetting = resolveSetting({
+    config,
+    jsonPath: 'ingest.orchestration',
+    env,
+    envKey: 'CONSTRUCT_INGEST_ORCHESTRATION',
+    defaultValue: DEFAULT_INGEST_ORCHESTRATION,
+  });
+  const orchestration = coerceEnum(orchestrationOverride, INGEST_ORCHESTRATION_STRATEGIES)
+    || coerceEnum(orchestrationSetting.value, INGEST_ORCHESTRATION_STRATEGIES)
+    || DEFAULT_INGEST_ORCHESTRATION;
+
   const needsProviderModel = strategy === 'provider' || fallback === 'provider';
   const modelResolution = needsProviderModel ? resolveProviderModel({ env, registryPath }) : null;
 
+  // The execution-capability contract is the single source of truth for whether
+  // the ingest workflow will actually orchestrate; reuse it rather than deriving
+  // a second answer here.
+  const { warnings, modelResolution: _drop, ...execution } = resolveExecution(
+    { workflowType: INGEST_WORKFLOW_TYPE, requestedStrategy: orchestration },
+    { env, cwd, registryPath },
+  );
+
   return {
     strategy,
     fallback,
+    orchestration,
     model: modelResolution?.model || null,
     provider: modelResolution?.provider || null,
     modelResolution,
+    execution,
   };
 }

package/lib/orchestration/run-store-postgres.mjs

@@ -0,0 +1,85 @@
+/**
+ * lib/orchestration/run-store-postgres.mjs — Postgres-backed run store (Mode-C).
+ *
+ * Mirrors lib/intake/postgres-queue.mjs: a class taking the tagged-template `sql`
+ * client from createSqlClient(env) (porsager/postgres style) and a project key.
+ * Orchestration runs persist to `construct_orchestration_runs`; triage-like
+ * columns (status, execution_mode) are flattened for filtering while the full run
+ * round-trips in `payload jsonb`. Multi-project isolation comes from the
+ * (run_id, project) composite primary key.
+ *
+ * Scope: the STORE is the deliverable. Container-worker spawning (Mode-C's
+ * optional worker topology) is out of scope (ADR-0021); a Postgres run store lets
+ * a team/enterprise deployment share durable runs across processes today.
+ */
+
+export class PostgresRunStore {
+  constructor({ sql, project } = {}) {
+    if (!sql) throw new Error('PostgresRunStore: sql client is required');
+    if (!project) throw new Error('PostgresRunStore: project is required');
+    this.sql = sql;
+    this.project = project;
+  }
+
+  async ensureSchema() {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS construct_orchestration_runs (
+        run_id TEXT,
+        project TEXT,
+        created_at TEXT,
+        status TEXT,
+        execution_mode TEXT,
+        payload JSONB,
+        PRIMARY KEY (run_id, project)
+      )
+    `;
+  }
+
+  async saveRun(run) {
+    if (!run?.runId) throw new Error('saveRun: run.runId is required');
+    await this.sql`
+      INSERT INTO construct_orchestration_runs (
+        run_id, project, created_at, status, execution_mode, payload
+      ) VALUES (
+        ${run.runId}, ${this.project}, ${run.createdAt || null},
+        ${run.status || null}, ${run.execution?.executionMode || null},
+        ${this.sql.json(run)}
+      )
+      ON CONFLICT (run_id, project) DO UPDATE SET
+        created_at = EXCLUDED.created_at,
+        status = EXCLUDED.status,
+        execution_mode = EXCLUDED.execution_mode,
+        payload = EXCLUDED.payload
+    `;
+    return run;
+  }
+
+  async loadRun(runId) {
+    if (!runId) return null;
+    const rows = await this.sql`
+      SELECT payload FROM construct_orchestration_runs
+      WHERE run_id = ${runId} AND project = ${this.project}
+      LIMIT 1
+    `;
+    return rows[0]?.payload || null;
+  }
+
+  async listRuns({ limit = 20 } = {}) {
+    const rows = await this.sql`
+      SELECT payload FROM construct_orchestration_runs
+      WHERE project = ${this.project}
+      ORDER BY created_at DESC
+      LIMIT ${limit}
+    `;
+    return rows.map((row) => {
+      const run = row.payload || {};
+      return {
+        runId: run.runId,
+        status: run.status,
+        executionMode: run.execution?.executionMode || null,
+        createdAt: run.createdAt,
+        request: run.request?.summary || null,
+      };
+    });
+  }
+}

package/lib/orchestration/run-store-sqlite.mjs

@@ -0,0 +1,122 @@
+/**
+ * lib/orchestration/run-store-sqlite.mjs — SQLite-backed run store (Mode-B).
+ *
+ * Same saveRun/loadRun/listRuns surface as the filesystem store (run-store.mjs),
+ * backed by a single `node:sqlite` database under
+ * `.cx/runtime/orchestration/runs.db`. A daemon-grade local store: durable,
+ * single-file, queryable, with no Postgres/Docker dependency.
+ *
+ * Node compatibility boundary: `node:sqlite` exists only on Node >=22.5, but the
+ * CI matrix also runs Node 20. So the import is LAZY (inside a function, never at
+ * module top level) and `sqliteAvailable()` reports false when it throws. The
+ * store factory throws a structured SQLITE_UNAVAILABLE error (with remediation)
+ * rather than crashing, so the resolver can fall back to filesystem. Nothing on
+ * the default test path statically imports node:sqlite.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const RUNTIME_REL = join('.cx', 'runtime', 'orchestration');
+
+let cachedDatabaseSync;
+
+// The node:sqlite probe is cached and synchronous. createRequire above is a
+// plain static import of node:module (always present); only node:sqlite itself
+// is loaded lazily here, so Node 20 never touches the unavailable builtin.
+
+function loadDatabaseSync() {
+  if (cachedDatabaseSync !== undefined) return cachedDatabaseSync;
+  try {
+    cachedDatabaseSync = require('node:sqlite').DatabaseSync;
+  } catch {
+    cachedDatabaseSync = null;
+  }
+  return cachedDatabaseSync;
+}
+
+export function sqliteAvailable() {
+  return loadDatabaseSync() != null;
+}
+
+function projectRoot(cwd) {
+  return isAbsolute(cwd) ? cwd : resolve(cwd);
+}
+
+function dbPath(cwd) {
+  const dir = join(projectRoot(cwd), RUNTIME_REL);
+  mkdirSync(dir, { recursive: true });
+  return join(dir, 'runs.db');
+}
+
+function openDb(cwd) {
+  const DatabaseSync = loadDatabaseSync();
+  if (!DatabaseSync) {
+    const err = new Error('SQLite run store requires Node >=22.5 (node:sqlite is unavailable on this runtime).');
+    err.code = 'SQLITE_UNAVAILABLE';
+    err.remediation = 'Upgrade to Node >=22.5, or set orchestration.store to "filesystem" / "postgres".';
+    throw err;
+  }
+  const db = new DatabaseSync(dbPath(cwd));
+  db.exec(`CREATE TABLE IF NOT EXISTS runs (
+    run_id TEXT PRIMARY KEY,
+    created_at TEXT,
+    status TEXT,
+    execution_mode TEXT,
+    json TEXT
+  )`);
+  return db;
+}
+
+/**
+ * Build a SQLite-backed run store bound to a project directory.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @returns {{ saveRun(run):object, loadRun(runId):object|null, listRuns(opts):Array }}
+ */
+export function createSqliteRunStore({ cwd = process.cwd() } = {}) {
+  const db = openDb(cwd);
+  return {
+    saveRun(run) {
+      const stmt = db.prepare(`INSERT INTO runs (run_id, created_at, status, execution_mode, json)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(run_id) DO UPDATE SET
+          created_at = excluded.created_at,
+          status = excluded.status,
+          execution_mode = excluded.execution_mode,
+          json = excluded.json`);
+      stmt.run(run.runId, run.createdAt || null, run.status || null, run.execution?.executionMode || null, JSON.stringify(run));
+      return run;
+    },
+    loadRun(runId) {
+      if (!runId) return null;
+      const row = db.prepare('SELECT json FROM runs WHERE run_id = ?').get(runId);
+      if (!row || !row.json) return null;
+      try {
+        return JSON.parse(row.json);
+      } catch {
+        return null;
+      }
+    },
+    listRuns({ limit = 20 } = {}) {
+      const rows = db.prepare('SELECT json FROM runs ORDER BY created_at DESC LIMIT ?').all(limit);
+      const out = [];
+      for (const row of rows) {
+        try {
+          const run = JSON.parse(row.json);
+          out.push({
+            runId: run.runId,
+            status: run.status,
+            executionMode: run.execution?.executionMode || null,
+            createdAt: run.createdAt,
+            request: run.request?.summary || null,
+          });
+        } catch { /* a corrupt row is skipped, not fatal to listing */ }
+      }
+      return out;
+    },
+  };
+}

package/lib/orchestration/runtime.mjs

@@ -1,25 +1,32 @@
 /**
- * lib/orchestration/runtime.mjs — Construct-owned local orchestration runtime (Mode-A).
+ * lib/orchestration/runtime.mjs — Construct-owned local orchestration runtime.
  *
  * The product goal: hosts are front doors, Construct is the system. A
  * host that lacks native multi-agent execution should still reach equivalent
  * Construct outcomes through a Construct-owned runtime rather than depending on
- * whichever editor exposes the strongest teammate mechanics. This module is the
- * Mode-A (zero-dependency, single-process, filesystem-backed) slice of that
- * runtime: it intakes a request, plans/decomposes it into a sequenced specialist
- * chain (reusing the orchestration-policy planner), resolves the execution-
- * capability contract (reusing resolveExecution), persists a durable run + task
- * lifecycle (run-store), and emits lifecycle traces.
+ * whichever editor exposes the strongest teammate mechanics. This module intakes
+ * a request, plans/decomposes it into a sequenced specialist chain (reusing the
+ * orchestration-policy planner), resolves the execution-capability contract
+ * (reusing resolveExecution), persists a durable run + task lifecycle through a
+ * pluggable run store (filesystem default, sqlite Mode-B, postgres Mode-C), and
+ * emits lifecycle traces.
  *
- * Honesty boundary (ADR-0020, extending ADR-0019): the Mode-A worker backend is
- * `inline` — it OWNS planning, sequencing, handoff state, persistence, and
- * observability, and PREPARES each specialist task (role, reason, handoff
- * contract) for a downstream executor. It does NOT itself perform specialist LLM
- * reasoning; a provider-backed worker backend is a separate, later backend. The
- * run reports `workerBackend` and per-task `executor` so a host can never mistake
- * a prepared task for executed specialist output. When the execution contract
- * resolves to prompt-only or host-direct, Construct owns no specialist task
- * sequence and the run records that explicitly rather than implying orchestration.
+ * Worker backends (ADR-0020, ADR-0021):
+ *   - `inline` (default): OWNS planning, sequencing, handoff state, persistence,
+ *     and observability, and PREPARES each specialist task for a downstream
+ *     executor. It does NOT itself perform specialist LLM reasoning. Tasks reach
+ *     status `prepared`; the prepare-only disclaimer applies.
+ *   - `provider`: EXECUTES each specialist task by calling the configured
+ *     provider/model with the specialist persona prompt. Tasks reach status
+ *     `done` carrying real model output; the prepare-only disclaimer does NOT
+ *     apply to provider-executed tasks. A failing task is recorded (status
+ *     `failed`) and the run completes `completed-with-failures` rather than
+ *     crashing.
+ *
+ * The run reports `workerBackend` and per-task `executor` so a host can never
+ * mistake a prepared task for executed specialist output. When the execution
+ * contract resolves to prompt-only or host-direct, Construct owns no specialist
+ * task sequence and the run records that explicitly.
  */
 
 import { randomBytes } from 'node:crypto';
@@ -27,13 +34,15 @@ import { randomBytes } from 'node:crypto';
 import { routeRequest } from '../orchestration-policy.mjs';
 import { resolveExecution } from '../embedded-contract/execution.mjs';
 import { detectHostCapabilities } from '../host-capabilities.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
 import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
-import { saveRun, loadRun, listRuns } from './run-store.mjs';
+import { resolveRunStore } from './store.mjs';
+import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
 
-export const WORKER_BACKENDS = ['inline'];
-export const DEFAULT_WORKER_BACKEND = 'inline';
+export const WORKER_BACKENDS = WORKER_BACKEND_SET;
+export const DEFAULT_WORKER_BACKEND = INLINE;
 
-const RUNTIME_SEMANTICS = 'Mode-A inline backend owns planning, sequencing, handoff state, persistence, and observability, and prepares each specialist task for a downstream executor. It does not perform specialist LLM reasoning itself; tasks reaching status "prepared" are ready for a worker backend or host to execute.';
+const RUNTIME_SEMANTICS = 'The inline worker backend owns planning, sequencing, handoff state, persistence, and observability, and prepares each specialist task for a downstream executor. It does not perform specialist LLM reasoning itself; tasks reaching status "prepared" are ready for a worker backend or host to execute. The provider worker backend executes specialist reasoning via the configured model and records real output as task.output.';
 
 function newRunId() {
   return `run-${randomBytes(6).toString('hex')}`;
@@ -87,25 +96,47 @@ function buildTasks(route) {
     handoffContract: handoffByProducer.get(role.replace(/^cx-/, '')) || null,
     status: 'queued',
     executor: null,
+    output: null,
+    error: null,
     startedAt: null,
     finishedAt: null,
   }));
 }
 
+// The worker backend is a deployment concern: an explicit option wins, then the
+// run's recorded backend, then config (orchestration.workerBackend), then the
+// inline default. An unknown value falls back to inline rather than guessing.
+
+function resolveWorkerBackend({ explicit, run, config }) {
+  const candidate = explicit || run?.workerBackend || config?.orchestration?.workerBackend || DEFAULT_WORKER_BACKEND;
+  return WORKER_BACKENDS.includes(candidate) ? candidate : DEFAULT_WORKER_BACKEND;
+}
+
+function loadConfig(cwd, env) {
+  try {
+    return loadProjectConfig(cwd, env).config || {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Plan a run: resolve the execution contract, decompose into a specialist chain,
  * and persist a durable run record (status `planned`). Pure of model calls.
  *
  * @param {object} request
  * @param {object} [opts]   { env, cwd }
- * @returns {object} the persisted run
+ * @returns {Promise<object>} the persisted run
  */
-export function planRun(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
+export async function planRun(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
   const {
     request: text = '', workflowType = null, requestedStrategy = 'auto', useConstruct = true,
     host = null, hostModel = null, hostProvider = null, fileCount = 0, moduleCount = 0,
   } = request;
 
+  const config = loadConfig(cwd, env);
+  const { store, warnings: storeWarnings } = resolveRunStore({ config, env, cwd });
+
   const execData = resolveExecution(
     { workflowType, requestedStrategy, useConstruct, host, hostModel, hostProvider },
     { env, cwd },
@@ -115,6 +146,7 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
   const traceId = newTraceId();
   const runId = newRunId();
   const now = new Date().toISOString();
+  const workerBackend = resolveWorkerBackend({ config });
 
   // Construct owns a specialist task sequence only when the contract resolves to
   // orchestrated execution; prompt-only and host-direct own none, and the run
@@ -129,7 +161,7 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
     updatedAt: now,
     request: { summary: truncate(text, 200), workflowType, requestedStrategy },
     hostRole: resolveHostRole(host),
-    workerBackend: DEFAULT_WORKER_BACKEND,
+    workerBackend,
     execution: pickExecution(execData),
     plan: {
       intent: route.intent,
@@ -140,12 +172,12 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
     },
     tasks,
     status: 'planned',
-    warnings: execData.warnings || [],
+    warnings: [...(execData.warnings || []), ...storeWarnings],
     semantics: RUNTIME_SEMANTICS,
     executionSemantics: execData.semantics,
   };
 
-  saveRun(cwd, run);
+  await store.saveRun(run);
   emitTraceEvent({
     rootDir: cwd, env, traceId, spanId: newSpanId(), eventType: 'task_graph.created',
     metadata: { runId, executionMode: run.execution.executionMode, specialists: run.plan.specialists, workerBackend: run.workerBackend },
@@ -153,46 +185,87 @@ export function planRun(request = {}, { env = process.env, cwd = process.cwd() }
   return run;
 }
 
+// The inline backend prepares one task: queued → running → prepared, no model
+// reasoning. The boundary ADR-0020 makes explicit.
+
+function prepareTaskInline(task) {
+  task.executor = 'inline:prepared';
+  task.status = 'prepared';
+  task.finishedAt = new Date().toISOString();
+}
+
+// The provider backend executes one task against the configured model. A failed
+// task is recorded (status `failed`, task.error) and does not abort the run, so
+// one specialist failure cannot lose the work of the others.
+
+async function executeTaskViaProvider(task, run, env, fetchImpl) {
+  try {
+    const result = await runTaskViaProvider({
+      task, run,
+      model: run.execution?.selectedModel,
+      provider: run.execution?.selectedProvider,
+      env, fetchImpl,
+    });
+    task.output = result.output;
+    task.executor = `provider:${result.provider}:${result.model}`;
+    task.status = 'done';
+    task.finishedAt = new Date().toISOString();
+    return true;
+  } catch (err) {
+    task.executor = `provider:error`;
+    task.error = { code: err.code || 'PROVIDER_EXECUTION_FAILED', message: err.message };
+    task.status = 'failed';
+    task.finishedAt = new Date().toISOString();
+    return false;
+  }
+}
+
 /**
- * Execute a planned run through the inline (Mode-A) worker backend: advance each
- * task queued → running → prepared, persisting after each transition so the run
- * is resumable and observable. The inline backend prepares tasks; it does not
- * perform specialist LLM reasoning.
+ * Execute a planned run through the chosen worker backend, persisting after each
+ * task transition so the run is resumable and observable.
  *
  * @param {string} cwd
  * @param {string} runId
- * @param {object} [opts]   { env }
- * @returns {object} the completed run
+ * @param {object} [opts]   { env, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the completed run
  */
-export function executeRun(cwd, runId, { env = process.env } = {}) {
-  const run = loadRun(cwd, runId);
+export async function executeRun(cwd, runId, { env = process.env, workerBackend = null, fetchImpl } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  const run = await store.loadRun(runId);
   if (!run) {
     const err = new Error(`Orchestration run not found: ${runId}`);
     err.code = 'RUN_NOT_FOUND';
     throw err;
   }
 
+  const backend = resolveWorkerBackend({ explicit: workerBackend, run, config });
+  run.workerBackend = backend;
   run.status = 'running';
   run.updatedAt = new Date().toISOString();
-  saveRun(cwd, run);
+  await store.saveRun(run);
 
+  let anyFailed = false;
   for (const task of run.tasks) {
     task.status = 'running';
     task.startedAt = new Date().toISOString();
-    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.started', role: task.role, taskId: task.id, metadata: { runId } });
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.started', role: task.role, taskId: task.id, metadata: { runId, workerBackend: backend } });
 
-    task.executor = 'inline:prepared';
-    task.status = 'prepared';
-    task.finishedAt = new Date().toISOString();
-    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: { runId, status: 'prepared' } });
+    if (backend === PROVIDER) {
+      const ok = await executeTaskViaProvider(task, run, env, fetchImpl);
+      if (!ok) anyFailed = true;
+    } else {
+      prepareTaskInline(task);
+    }
 
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: { runId, status: task.status } });
     run.updatedAt = new Date().toISOString();
-    saveRun(cwd, run);
+    await store.saveRun(run);
   }
 
-  run.status = 'completed';
+  run.status = anyFailed ? 'completed-with-failures' : 'completed';
   run.updatedAt = new Date().toISOString();
-  saveRun(cwd, run);
+  await store.saveRun(run);
   emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
   return run;
 }
@@ -200,9 +273,9 @@ export function executeRun(cwd, runId, { env = process.env } = {}) {
 /**
  * Plan and execute in one call (the common `orchestrate run` path).
  */
-export function runOrchestration(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
-  const planned = planRun(request, { env, cwd });
-  return executeRun(cwd, planned.runId, { env });
+export async function runOrchestration(request = {}, { env = process.env, cwd = process.cwd(), workerBackend = null, fetchImpl } = {}) {
+  const planned = await planRun(request, { env, cwd });
+  return executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl });
 }
 
 /**
@@ -231,10 +304,14 @@ export function hostAdapterMetadata(run) {
   };
 }
 
-export function getRun(cwd, runId) {
-  return loadRun(cwd, runId);
+export async function getRun(cwd, runId, { env = process.env } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  return store.loadRun(runId);
 }
 
-export function getRuns(cwd, opts) {
-  return listRuns(cwd, opts);
+export async function getRuns(cwd, { env = process.env, ...opts } = {}) {
+  const config = loadConfig(cwd, env);
+  const { store } = resolveRunStore({ config, env, cwd });
+  return store.listRuns(opts);
 }

package/lib/orchestration/store.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/orchestration/store.mjs — run-store resolver for the orchestration runtime.
+ *
+ * One interface — saveRun(run), loadRun(runId), listRuns(opts) — over three
+ * backends: filesystem (Mode-A default, zero dependency), sqlite (Mode-B,
+ * node:sqlite), and postgres (Mode-C, shared team/enterprise store). The runtime
+ * resolves a store through here instead of importing run-store functions
+ * directly, so the backend is a deployment concern rather than a code edit.
+ *
+ * Selection precedence: explicit config (`orchestration.store`) or the
+ * CONSTRUCT_ORCHESTRATION_STORE env override win; otherwise the deployment mode
+ * decides (solo→filesystem, team/enterprise→postgres). When the chosen backend
+ * is unavailable (sqlite on Node <22.5, or postgres with no DATABASE_URL / null
+ * sql client) the resolver falls back to filesystem and records a warning rather
+ * than failing — durability of the default tier is never sacrificed to an
+ * optional one. The returned store is always async-uniform so callers await it
+ * regardless of backend; the filesystem and sqlite backends resolve synchronously
+ * under the hood, so the default Mode-A run record is byte-for-byte unchanged.
+ */
+
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { createSqlClient } from '../storage/backend.mjs';
+import { saveRun as fsSaveRun, loadRun as fsLoadRun, listRuns as fsListRuns } from './run-store.mjs';
+import { sqliteAvailable, createSqliteRunStore } from './run-store-sqlite.mjs';
+import { PostgresRunStore } from './run-store-postgres.mjs';
+
+export const ORCHESTRATION_STORES = ['filesystem', 'sqlite', 'postgres'];
+export const STORE_ENV_KEY = 'CONSTRUCT_ORCHESTRATION_STORE';
+
+function filesystemStore(cwd) {
+  return {
+    kind: 'filesystem',
+    saveRun: (run) => fsSaveRun(cwd, run),
+    loadRun: (runId) => fsLoadRun(cwd, runId),
+    listRuns: (opts) => fsListRuns(cwd, opts),
+  };
+}
+
+function sqliteStore(cwd) {
+  const store = createSqliteRunStore({ cwd });
+  return {
+    kind: 'sqlite',
+    saveRun: (run) => store.saveRun(run),
+    loadRun: (runId) => store.loadRun(runId),
+    listRuns: (opts) => store.listRuns(opts),
+  };
+}
+
+function postgresStore({ sql, project }) {
+  const store = new PostgresRunStore({ sql, project });
+  let ensured = null;
+  const ready = () => {
+    if (!ensured) ensured = store.ensureSchema();
+    return ensured;
+  };
+  return {
+    kind: 'postgres',
+    saveRun: async (run) => { await ready(); return store.saveRun(run); },
+    loadRun: async (runId) => { await ready(); return store.loadRun(runId); },
+    listRuns: async (opts) => { await ready(); return store.listRuns(opts); },
+  };
+}
+
+function projectKey(config, cwd) {
+  return config?.deployment?.projectName || cwd || 'default';
+}
+
+function chooseBackend({ config, env, cwd }) {
+  const explicit = String(env?.[STORE_ENV_KEY] || config?.orchestration?.store || '').trim().toLowerCase();
+  if (ORCHESTRATION_STORES.includes(explicit)) return explicit;
+  const mode = getDeploymentMode(env, { cwd });
+  return mode === 'solo' ? 'filesystem' : 'postgres';
+}
+
+/**
+ * Resolve a run store for the runtime.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]   loaded project config (reads orchestration.store)
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.cwd]
+ * @returns {{ store: {kind:string, saveRun:Function, loadRun:Function, listRuns:Function}, backend: string, warnings: string[] }}
+ */
+export function resolveRunStore({ config = {}, env = process.env, cwd = process.cwd() } = {}) {
+  const warnings = [];
+  const requested = chooseBackend({ config, env, cwd });
+
+  if (requested === 'sqlite') {
+    if (sqliteAvailable()) return { store: sqliteStore(cwd), backend: 'sqlite', warnings };
+    warnings.push('orchestration.store "sqlite" requires Node >=22.5 (node:sqlite unavailable); falling back to filesystem.');
+    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+  }
+
+  if (requested === 'postgres') {
+    const sql = createSqlClient(env);
+    if (sql) return { store: postgresStore({ sql, project: projectKey(config, cwd) }), backend: 'postgres', warnings };
+    warnings.push('orchestration.store "postgres" requires a reachable DATABASE_URL; falling back to filesystem.');
+    return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+  }
+
+  return { store: filesystemStore(cwd), backend: 'filesystem', warnings };
+}

package/lib/orchestration/worker.mjs

@@ -0,0 +1,167 @@
+/**
+ * lib/orchestration/worker.mjs — provider-backed worker backend for the local
+ * orchestration runtime.
+ *
+ * The inline backend (runtime.mjs) PREPARES a specialist task and stops short of
+ * model reasoning (ADR-0020). The provider backend closes that gap: it EXECUTES
+ * one specialist task by calling the configured provider/model with the
+ * specialist's persona prompt as system context and the run's request as the
+ * user turn, returning the model's real output (ADR-0021). Because it genuinely
+ * runs the model, the prepare-only disclaimer does not apply to provider-executed
+ * tasks — runtime.mjs records `task.output` and `executor='provider:<provider>:<model>'`
+ * so a host can distinguish prepared from executed work.
+ *
+ * Provider selection mirrors lib/ingest/provider-extract.mjs: Anthropic
+ * `/v1/messages` for Claude-family models, OpenRouter `/v1/chat/completions`
+ * otherwise; key resolution reads env (ANTHROPIC_API_KEY / OPENROUTER_API_KEY)
+ * and augments with ambient dotenv only when the caller did not inject an
+ * explicit env (hermetic-when-explicit). `fetchImpl` is injectable so the path is
+ * exercised end to end against a mock provider without a live key. Failures
+ * surface as structured codes (PROVIDER_KEY_MISSING, PROVIDER_MODEL_UNRESOLVED,
+ * PROVIDER_EXECUTION_FAILED) rather than opaque HTTP errors.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const INLINE = 'inline';
+export const PROVIDER = 'provider';
+export const WORKER_BACKEND_SET = [INLINE, PROVIDER];
+
+const MAX_OUTPUT_TOKENS = 2048;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROMPTS_DIR = join(HERE, '..', '..', 'specialists', 'prompts');
+
+function providerError(code, reason, remediation) {
+  const err = new Error(reason);
+  err.code = code;
+  err.remediation = remediation;
+  return err;
+}
+
+function isAnthropic(provider, model) {
+  return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
+}
+
+// Key resolution mirrors provider-extract: env first, then the two cheap dotenv
+// files, and only when the caller did not inject an explicit env. A caller that
+// passes its own env object (embedded callers, tests) is authoritative and
+// hermetic — ambient discovery is suppressed so a developer's real key never
+// bleeds into a test run.
+
+function resolveKey(varName, env, allowAmbient) {
+  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
+  if (!allowAmbient) return null;
+  for (const file of [join(homedir(), '.construct', 'config.env'), join(homedir(), '.env')]) {
+    try {
+      if (!existsSync(file)) continue;
+      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+      if (m && m[1]) return m[1].trim();
+    } catch { /* unreadable dotenv is not authoritative */ }
+  }
+  return null;
+}
+
+// The persona prompt is the specialist's system context. It lives in
+// specialists/prompts/cx-<role>.md; absent that file, a minimal role-named system
+// prompt keeps the backend functional rather than failing on a missing persona.
+
+function loadPersona(role) {
+  const slug = String(role || '').replace(/^cx-/, '');
+  const file = join(PROMPTS_DIR, `cx-${slug}.md`);
+  try {
+    if (existsSync(file)) return readFileSync(file, 'utf8');
+  } catch { /* unreadable persona falls back to the minimal prompt */ }
+  return `You are the ${slug} specialist. Execute your part of the request within your role and return your result directly.`;
+}
+
+function buildUserPrompt({ task, run }) {
+  const summary = run?.request?.summary || '';
+  const reason = task?.reason ? `\n\nWhy you were dispatched: ${task.reason}` : '';
+  const handoff = task?.handoffContract ? `\nHandoff contract: ${task.handoffContract}` : '';
+  return `Request: ${summary}${reason}${handoff}\n\nDo your part of this request as the ${String(task?.role || '').replace(/^cx-/, '')} specialist. Return your result directly.`;
+}
+
+async function bodyExcerpt(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return '';
+  }
+}
+
+async function callAnthropic({ model, apiKey, system, user, fetchImpl }) {
+  const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: model.replace(/^anthropic\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      system,
+      messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `Anthropic specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  return (data.content || []).filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+}
+
+async function callOpenRouter({ model, apiKey, system, user, fetchImpl }) {
+  const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/construct' },
+    body: JSON.stringify({
+      model: model.replace(/^openrouter\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXECUTION_FAILED', `OpenRouter specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set orchestration.workerBackend to "inline".');
+  }
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || '';
+}
+
+/**
+ * Execute one specialist task via the configured provider/model.
+ *
+ * @param {object} opts
+ * @param {object} opts.task            the run task (carries role, reason, handoffContract)
+ * @param {object} opts.run             the run (carries request summary)
+ * @param {string} opts.model           resolved provider model id
+ * @param {string} [opts.provider]      resolved provider id (selects the API)
+ * @param {Record<string,string>} [opts.env]
+ * @param {Function} [opts.fetchImpl]   injectable fetch (for tests)
+ * @returns {Promise<{output:string, model:string, provider:string, characters:number}>}
+ */
+export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
+  if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
+
+  const anthropic = isAnthropic(provider, model);
+  const keyVar = anthropic ? 'ANTHROPIC_API_KEY' : 'OPENROUTER_API_KEY';
+  const apiKey = resolveKey(keyVar, env, env === process.env);
+  if (!apiKey) {
+    throw providerError('PROVIDER_KEY_MISSING', `No API key for ${anthropic ? 'Anthropic' : 'OpenRouter'} specialist execution.`, `Set ${keyVar}, or set orchestration.workerBackend to "inline".`);
+  }
+
+  const system = loadPersona(task?.role);
+  const user = buildUserPrompt({ task, run });
+  const output = anthropic
+    ? await callAnthropic({ model, apiKey, system, user, fetchImpl })
+    : await callOpenRouter({ model, apiKey, system, user, fetchImpl });
+
+  const text = output || '';
+  return {
+    output: text,
+    model,
+    provider: anthropic ? 'anthropic' : 'openrouter',
+    characters: text.length,
+  };
+}

package/lib/parity.mjs

@@ -30,6 +30,38 @@ import { fileURLToPath } from 'node:url';
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(MODULE_DIR, '..');
 
+// VS Code and Cursor user settings are JSONC: line/block comments and trailing
+// commas are valid and common. Strict JSON.parse rejects them, producing a
+// false "unreadable" parity failure on a perfectly valid editor config. This
+// strips comments string-aware (so `//` inside a "https://…" value survives)
+// and drops trailing commas before parsing.
+
+function parseJsonc(text) {
+  let out = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; out += ch; continue; }
+    if (ch === '/' && next === '/') { while (i < text.length && text[i] !== '\n') i += 1; out += '\n'; continue; }
+    if (ch === '/' && next === '*') { i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1; i += 1; continue; }
+    out += ch;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function readJsoncFile(file) {
+  return parseJsonc(fs.readFileSync(file, 'utf8'));
+}
+
 function loadRegistry(rootDir = ROOT_DIR) {
   const file = path.join(rootDir, 'specialists', 'registry.json');
   return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -130,7 +162,7 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
@@ -183,7 +215,7 @@ function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
   const actualSet = new Set();
   for (const settingsPath of paths) {
     try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const settings = readJsoncFile(settingsPath);
       for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
     } catch (err) {
       return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
@@ -208,7 +240,7 @@ function checkCursor(registry, { homeDir = os.homedir() } = {}) {
   if (!fs.existsSync(file)) return { surface: 'cursor', kind: 'mcps', status: 'absent', file };
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    config = readJsoncFile(file);
   } catch (err) {
     return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",