@geraldmaron/construct 1.0.18 → 1.0.20

package/lib/mcp/server.mjs

@@ -8,12 +8,14 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
 import { loadConstructEnv } from '../env-config.mjs';
+import { getInstalledVersion } from '../version.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
 import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
 
 // Apply config.env values to process.env, letting config.env win over shell env
@@ -56,7 +58,7 @@ import {
   profileCreate, profileArchive, sandboxList, learningStatus,
   knowledgeGraphAsk,
 } from './tools/profile.mjs';
-import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe } from './tools/embedded-contract.mjs';
+import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve } from './tools/embedded-contract.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -64,11 +66,58 @@ loadToolkitEnv(ROOT_DIR);
 
 const opts = { ROOT_DIR };
 
+// Identity an MCP host can render meaningfully: the real installed version (not a
+// hardcoded stub), a one-line description of what the server offers (shown in the
+// host's server-detail view), and a `construct://status` resource for live state.
+// Without these the host shows only "<name> · OK" with an empty detail panel.
+
+const VERSION = getInstalledVersion()?.version || 'unknown';
+const DEPLOYMENT_MODE = getDeploymentMode(process.env, { cwd: ROOT_DIR });
+const INSTRUCTIONS = [
+  `Construct MCP — agent orchestration for this workspace (v${VERSION}, ${DEPLOYMENT_MODE} mode).`,
+  'Tools cover: project context and diff review, skills/templates/teams, document ingestion and vector storage,',
+  'workflow orchestration and contracts, telemetry and scoring, and cross-session memory.',
+  'Read the `construct://status` resource for live state, or run `construct status` for full project health.',
+  'Start the dashboard with `construct dev`.',
+].join(' ');
+
 const server = new Server(
-  { name: 'construct-mcp', version: '1.0.0' },
-  { capabilities: { tools: {} } }
+  { name: 'construct-mcp', version: VERSION },
+  { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS },
 );
 
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'construct://status',
+      name: 'Construct status',
+      description: 'Live toolkit status: version, deployment mode, MCP broker, and how to get full project health.',
+      mimeType: 'application/json',
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params?.uri !== 'construct://status') {
+    throw new Error(`Unknown resource: ${req.params?.uri}`);
+  }
+  const payload = {
+    name: 'Construct',
+    version: VERSION,
+    deploymentMode: DEPLOYMENT_MODE,
+    mcpBroker: process.env.CONSTRUCT_MCP_BROKER === 'on' ? 'on' : 'off',
+    capabilities: [
+      'project-context', 'skills', 'templates', 'teams', 'document-ingestion',
+      'vector-storage', 'workflow', 'telemetry', 'memory',
+    ],
+    fullHealth: 'run `construct status`',
+    dashboard: 'run `construct dev`, then open the printed URL',
+  };
+  return {
+    contents: [{ uri: req.params.uri, mimeType: 'application/json', text: JSON.stringify(payload, null, 2) }],
+  };
+});
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
@@ -1109,6 +1158,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'construct_execution_resolve',
+      description: 'Resolve the execution-capability contract for an embedded workflow BEFORE/at workflow start: returns executionMode (construct-orchestrated | construct-prompt-only | host-direct | same-family-fallback), constructCapabilitiesActive (subset of personas/skills/workflow-routing/prompt-envelope), degraded + machine-readable degradationReason, requestedStrategy vs effectiveStrategy, and the resolved provider/model. Descriptive, not enforced: reports what Construct planned and can resolve a model for, never an observation that the host ran personas (see the semantics field). Read-only and secret-free.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          workflow_type: { type: 'string', description: 'Workflow whose orchestration plan is weighed (e.g. evidence-ingest, architecture-review). Absent ⇒ generic orchestration availability.' },
+          requested_strategy: { type: 'string', enum: ['orchestrated', 'prompt-only', 'auto'], description: 'Desired execution strategy (default auto).' },
+          use_construct: { type: 'boolean', description: 'false ⇒ host-direct (host runs without Construct capabilities). Default true.' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host is currently using, for model resolution.' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, when no host_model is given.' },
+          requested_tier: { type: 'string', enum: ['reasoning', 'standard', 'fast'], description: 'Desired model tier; overrides the workflow-type hint.' },
+          capabilities: { type: 'array', items: { type: 'string' }, description: 'Optional required capabilities; unverifiable ones are returned as warnings.' },
+          allow_cross_provider_fallback: { type: 'boolean', description: 'Permit model fallback outside the host provider family (default false).' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1190,6 +1257,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'triage_recommend') result = await triageRecommend(args);
     else if (name === 'workflow_invoke') result = await workflowInvoke(args);
     else if (name === 'capability_describe') result = capabilityDescribe(args);
+    else if (name === 'construct_execution_resolve') result = executionResolve(args);
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };

package/lib/mcp/tools/embedded-contract.mjs

@@ -12,11 +12,12 @@ import { resolveEmbeddedModel as resolveModelCore } from '../../embedded-contrac
 import { recommendPlan as recommendPlanCore } from '../../embedded-contract/triage.mjs';
 import { invokeWorkflow as invokeWorkflowCore } from '../../embedded-contract/workflow-invoke.mjs';
 import { buildCapabilityContract } from '../../embedded-contract/capability.mjs';
+import { resolveExecution as resolveExecutionCore } from '../../embedded-contract/execution.mjs';
 import { resolveInput } from '../../embedded-contract/ingest.mjs';
 
 async function ingestArgs(args) {
   if (args.input || !args.file_path) return { input: args.input, ingestion: undefined };
-  const resolved = await resolveInput({ filePath: args.file_path });
+  const resolved = await resolveInput({ filePath: args.file_path, strategy: args.ingest_strategy });
   return { input: resolved.text, ingestion: resolved.error ? { ...(resolved.ingestion || {}), error: resolved.error } : resolved.ingestion };
 }
 
@@ -75,3 +76,18 @@ export async function workflowInvoke(args = {}) {
 export function capabilityDescribe(args = {}) {
   return wrapContractResult(buildCapabilityContract({ rootDir: args.root_dir }), { surface: 'mcp' });
 }
+
+export function executionResolve(args = {}) {
+  const request = {
+    workflowType: args.workflow_type,
+    requestedStrategy: args.requested_strategy,
+    useConstruct: args.use_construct !== false,
+    host: args.host,
+    hostModel: args.host_model,
+    hostProvider: args.host_provider,
+    requestedTier: args.requested_tier,
+    capabilities: csv(args.capabilities),
+    allowCrossProviderFallback: Boolean(args.allow_cross_provider_fallback),
+  };
+  return wrapContractResult(resolveExecutionCore(request), { surface: 'mcp' });
+}

package/lib/mode-commands.mjs

@@ -9,6 +9,8 @@
 // Standardized command contracts across deployment modes
 
 import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
 
 export const MODE_COMMANDS = {
   // Intake queue operations
@@ -65,19 +67,15 @@ function getDeploymentMode() {
 function parseIntakeFiles(stdout) {
   return stdout.split('\n')
     .filter(Boolean)
-    .map(f => ({ id: path.basename(f, '.json'), source: 'file' }));
+    .map(f => ({ id: basename(f, '.json'), source: 'file' }));
 }
 
 function readIntakeFile(id, options) {
-  const fs = require('fs');
-  const path = require('path');
-  const filePath = path.join(options.cwd || process.cwd(), '.cx/intake/pending', `${id}.json`);
-  
-  if (!fs.existsSync(filePath)) {
+  const filePath = join(options.cwd || process.cwd(), '.cx/intake/pending', `${id}.json`);
+  if (!existsSync(filePath)) {
     return { error: `Intake item ${id} not found` };
   }
-  
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return JSON.parse(readFileSync(filePath, 'utf8'));
 }
 
 async function queryPostgresIntake(options) {

package/lib/observation-store.mjs

@@ -25,6 +25,18 @@ const OBS_DIR = '.cx/observations';
 const INDEX_FILE = 'index.json';
 const VECTORS_FILE = 'vectors.json';
 const MAX_INDEX = 1000;
+
+// The exact text fed to the embedder, and its content hash. addObservation and
+// the reconciliation pass MUST derive both the same way, so the (content_hash,
+// model) fingerprint they compare is computed identically.
+
+export function observationSearchText(obs) {
+  return [obs.summary, obs.content, ...(obs.tags || [])].filter(Boolean).join(' ');
+}
+
+export function observationContentHash(text) {
+  return crypto.createHash('sha256').update(String(text || '')).digest('hex');
+}
 const MAX_SUMMARY = 500;
 const MAX_CONTENT = 2000;
 const MAX_TAGS = 10;
@@ -214,11 +226,13 @@ export async function addObservation(rootDir, {
   try {
     const client = new VectorClient();
     if (await client.isHealthy() && await client.isPgvectorEnabled()) {
-      const searchText = [record.summary, record.content, ...record.tags].filter(Boolean).join(' ');
-      const { embedding } = await embedTextEngine(searchText);
+      const searchText = observationSearchText(record);
+      const { embedding, model } = await embedTextEngine(searchText);
       await client.storeObservation({
         ...record,
         embedding,
+        contentHash: observationContentHash(searchText),
+        model,
       });
       await client.close();
       return record;

package/lib/opencode-telemetry.mjs

@@ -29,7 +29,7 @@ export function getIngestClient(env = process.env) {
     rootDir: env.CX_TOOLKIT_DIR,
     onError: (err) => {
       if (env.CONSTRUCT_TRACE_DEBUG === "1") {
-        // eslint-disable-next-line no-console
+         
         console.error("[construct-telemetry]", err?.message || err);
       }
     },

package/lib/orchestration/run-store.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/orchestration/run-store.mjs — filesystem-backed persistence for the local
+ * orchestration runtime (Mode-A, zero-dependency).
+ *
+ * Orchestration runs and their task lifecycle live as JSON under the project's
+ * `.cx/runtime/orchestration/runs/`, so a run survives editor/host restarts and
+ * is inspectable without a daemon, a database, or Docker. Writes are atomic
+ * (temp file then rename) so a crash mid-write cannot leave a half-written run;
+ * reads tolerate a corrupt file by skipping it rather than throwing. This is the
+ * Mode-A backend; Mode-B/C (SQLite/Postgres) would implement the same load/save
+ * surface without changing callers.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const RUNTIME_REL = join('.cx', 'runtime', 'orchestration');
+
+let writeCounter = 0;
+
+function projectRoot(cwd) {
+  return isAbsolute(cwd) ? cwd : resolve(cwd);
+}
+
+export function runtimeDir(cwd = process.cwd()) {
+  return join(projectRoot(cwd), RUNTIME_REL);
+}
+
+function runsDir(cwd) {
+  return join(runtimeDir(cwd), 'runs');
+}
+
+// Atomic JSON write: a same-directory temp file then rename, which is atomic on
+// POSIX filesystems. A per-process counter keeps concurrent writers from
+// colliding on the temp name before the rename lands.
+
+function atomicWriteJson(filePath, value) {
+  writeCounter = (writeCounter + 1) % 100000;
+  const tmp = `${filePath}.${process.pid}.${writeCounter}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, filePath);
+}
+
+export function saveRun(cwd, run) {
+  const dir = runsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  atomicWriteJson(join(dir, `${run.runId}.json`), run);
+  return run;
+}
+
+export function loadRun(cwd, runId) {
+  if (!runId) return null;
+  const file = join(runsDir(cwd), `${runId}.json`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function listRuns(cwd, { limit = 20 } = {}) {
+  const dir = runsDir(cwd);
+  if (!existsSync(dir)) return [];
+  const runs = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      runs.push(JSON.parse(readFileSync(join(dir, name), 'utf8')));
+    } catch {
+      /* a corrupt run file is skipped, not fatal to listing */
+    }
+  }
+  runs.sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
+  return runs.slice(0, limit).map((run) => ({
+    runId: run.runId,
+    status: run.status,
+    executionMode: run.execution?.executionMode || null,
+    createdAt: run.createdAt,
+    request: run.request?.summary || null,
+  }));
+}

package/lib/orchestration/runtime.mjs

@@ -0,0 +1,240 @@
+/**
+ * lib/orchestration/runtime.mjs — Construct-owned local orchestration runtime (Mode-A).
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+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 { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
+import { saveRun, loadRun, listRuns } from './run-store.mjs';
+
+export const WORKER_BACKENDS = ['inline'];
+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.';
+
+function newRunId() {
+  return `run-${randomBytes(6).toString('hex')}`;
+}
+
+function truncate(text, max) {
+  const s = String(text || '');
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+// hostRole reports how the calling host orchestrates, so an adapter can decide
+// whether to delegate to Construct's runtime (its reason for being). A direct
+// CLI call has no host; an unrecognized host name is reported as unknown rather
+// than guessed.
+
+function resolveHostRole(hostName) {
+  if (!hostName) return 'cli-direct';
+  const match = detectHostCapabilities().find((h) => h.host.toLowerCase() === String(hostName).toLowerCase());
+  return match ? match.orchestration : 'unknown';
+}
+
+function pickExecution(data) {
+  return {
+    executionMode: data.executionMode,
+    effectiveStrategy: data.effectiveStrategy,
+    requestedStrategy: data.requestedStrategy,
+    constructCapabilitiesActive: data.constructCapabilitiesActive,
+    degraded: data.degraded,
+    degradationReason: data.degradationReason,
+    selectedProvider: data.selectedProvider,
+    selectedModel: data.selectedModel,
+    resolutionSource: data.resolutionSource,
+    orchestrationPlanned: data.orchestrationPlanned,
+    orchestrationAvailable: data.orchestrationAvailable,
+    deploymentMode: data.deploymentMode,
+  };
+}
+
+function buildTasks(route) {
+  const reasons = route.dispatchReasons || {};
+  const handoffByProducer = new Map();
+  for (const edge of route.contractChain || []) {
+    const producer = edge.contract?.producer;
+    if (producer && !handoffByProducer.has(producer)) handoffByProducer.set(producer, edge.contract.id);
+  }
+  return (route.specialists || []).map((role, i) => ({
+    id: `t${i + 1}`,
+    seq: i,
+    role,
+    reason: reasons[role] || null,
+    handoffContract: handoffByProducer.get(role.replace(/^cx-/, '')) || null,
+    status: 'queued',
+    executor: null,
+    startedAt: null,
+    finishedAt: null,
+  }));
+}
+
+/**
+ * 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
+ */
+export 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 execData = resolveExecution(
+    { workflowType, requestedStrategy, useConstruct, host, hostModel, hostProvider },
+    { env, cwd },
+  );
+  const route = routeRequest({ request: text, fileCount, moduleCount });
+
+  const traceId = newTraceId();
+  const runId = newRunId();
+  const now = new Date().toISOString();
+
+  // Construct owns a specialist task sequence only when the contract resolves to
+  // orchestrated execution; prompt-only and host-direct own none, and the run
+  // records that rather than implying orchestration that did not happen.
+  const orchestrates = execData.effectiveStrategy === 'orchestrated';
+  const tasks = orchestrates ? buildTasks(route) : [];
+
+  const run = {
+    runId,
+    traceId,
+    createdAt: now,
+    updatedAt: now,
+    request: { summary: truncate(text, 200), workflowType, requestedStrategy },
+    hostRole: resolveHostRole(host),
+    workerBackend: DEFAULT_WORKER_BACKEND,
+    execution: pickExecution(execData),
+    plan: {
+      intent: route.intent,
+      track: route.track,
+      specialists: route.specialists || [],
+      dispatchPlan: route.dispatchPlan,
+      contractChain: (route.contractChain || []).map((e) => ({ id: e.contract?.id, producer: e.contract?.producer, consumer: e.contract?.consumer, stage: e.stage })),
+    },
+    tasks,
+    status: 'planned',
+    warnings: execData.warnings || [],
+    semantics: RUNTIME_SEMANTICS,
+    executionSemantics: execData.semantics,
+  };
+
+  saveRun(cwd, 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 },
+  });
+  return run;
+}
+
+/**
+ * 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.
+ *
+ * @param {string} cwd
+ * @param {string} runId
+ * @param {object} [opts]   { env }
+ * @returns {object} the completed run
+ */
+export function executeRun(cwd, runId, { env = process.env } = {}) {
+  const run = loadRun(cwd, runId);
+  if (!run) {
+    const err = new Error(`Orchestration run not found: ${runId}`);
+    err.code = 'RUN_NOT_FOUND';
+    throw err;
+  }
+
+  run.status = 'running';
+  run.updatedAt = new Date().toISOString();
+  saveRun(cwd, run);
+
+  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 } });
+
+    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' } });
+
+    run.updatedAt = new Date().toISOString();
+    saveRun(cwd, run);
+  }
+
+  run.status = 'completed';
+  run.updatedAt = new Date().toISOString();
+  saveRun(cwd, run);
+  emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
+  return run;
+}
+
+/**
+ * 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 });
+}
+
+/**
+ * The structured metadata a host adapter consumes for runtime-backed integration.
+ */
+export function hostAdapterMetadata(run) {
+  const e = run.execution || {};
+  return {
+    runId: run.runId,
+    traceId: run.traceId,
+    status: run.status,
+    requestedStrategy: e.requestedStrategy,
+    effectiveStrategy: e.effectiveStrategy,
+    executionMode: e.executionMode,
+    constructCapabilitiesActive: e.constructCapabilitiesActive,
+    workerBackend: run.workerBackend,
+    hostRole: run.hostRole,
+    degraded: e.degraded,
+    degradationReason: e.degradationReason,
+    selectedProvider: e.selectedProvider,
+    selectedModel: e.selectedModel,
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor })),
+    warnings: run.warnings || [],
+    semantics: run.semantics,
+    executionSemantics: run.executionSemantics,
+  };
+}
+
+export function getRun(cwd, runId) {
+  return loadRun(cwd, runId);
+}
+
+export function getRuns(cwd, opts) {
+  return listRuns(cwd, opts);
+}

package/lib/roles/cli.mjs

@@ -6,11 +6,13 @@
  *   latest              — show the most recent unresolved invocation (full brief)
  *   show <fingerprint>  — show one invocation by fingerprint
  *   status              — show onboarded personas + their event types
+ *   resolve <fp>        — mark one invocation resolved
+ *   prune               — compact the queue: drop resolved + TTL-expired entries
  *   reset               — clear the pending queue (manual recovery)
  */
 
 import { listOnboardedPersonas, loadManifest } from './manifest.mjs';
-import { listPending, markResolved, resetPending } from './gateway.mjs';
+import { listPending, markResolved, resetPending, prunePending } from './gateway.mjs';
 import { recent as recentEvents } from './event-bus.mjs';
 
 function fmtTime(ts) {
@@ -106,6 +108,12 @@ export async function runCli(args) {
     return ok ? 0 : 1;
   }
 
+  if (sub === 'prune') {
+    const { removed, resolved, expired, fixtures, kept } = prunePending();
+    console.log(`Pruned ${removed} entr${removed === 1 ? 'y' : 'ies'} (${resolved} resolved, ${expired} expired, ${fixtures} fixture) · ${kept} remaining.`);
+    return 0;
+  }
+
   if (sub === 'reset') {
     resetPending();
     console.log('Pending queue cleared.');
@@ -113,6 +121,6 @@ export async function runCli(args) {
   }
 
   console.error(`Unknown role subcommand: ${sub}`);
-  console.error('Usage: construct role [list|latest|show <fp>|status|resolve <fp>|reset]');
+  console.error('Usage: construct role [list|latest|show <fp>|status|resolve <fp>|prune|reset]');
   return 2;
 }

package/lib/roles/gateway.mjs

@@ -30,6 +30,7 @@ const DEFAULTS = {
   thresholdWindowMs: 10 * 60 * 1000,
   cooldownMs: 30 * 60 * 1000,
   rateCeilingPerHour: 3,
+  pendingTtlMs: 14 * 24 * 60 * 60 * 1000,
 };
 
 function ensureDir() {
@@ -226,10 +227,58 @@ export async function recordAndMaybeInvoke(eventType, payload = {}) {
   return { recorded: true, ...r };
 }
 
+// A surfaced role invocation is a prompt to act, not a durable record (bd owns
+// the durable issue). Unresolved entries older than the TTL are stale noise —
+// e.g. pre-fixture-guard escalations that would otherwise surface at every
+// session-start forever — so they drop out of listings and never expire bd work.
+
+function isExpired(entry, now) {
+  return typeof entry.ts === 'number' && (now - entry.ts) > DEFAULTS.pendingTtlMs;
+}
+
 export function listPending({ unresolved = true } = {}) {
   const entries = readPending();
   if (!unresolved) return entries;
-  return entries.filter((e) => !e.resolvedAt);
+  const now = Date.now();
+  return entries.filter((e) => !e.resolvedAt && !isExpired(e, now));
+}
+
+// An entry that names an OS-tmp path is a pre-guard test-fixture escalation
+// (shouldEscalate now blocks these at the source). Sweep them on prune so the
+// historical noise — e.g. the cx-secrets fixtures — clears immediately rather
+// than waiting out the TTL.
+
+function referencesFixture(entry) {
+  for (const field of [entry.cwd, entry.project, entry.summary]) {
+    if (typeof field !== 'string') continue;
+    for (const token of field.split(/\s+/)) {
+      if (isTestFixturePath(token.replace(/[)\].,:;]+$/, ''))) return true;
+    }
+  }
+  return false;
+}
+
+// Compact the queue on disk: drop resolved, TTL-expired, and fixture-path
+// entries. Idempotent; returns counts so the CLI and session-start can report
+// what was reclaimed.
+
+export function prunePending({ now = Date.now() } = {}) {
+  const entries = readPending();
+  const kept = [];
+  let resolved = 0;
+  let expired = 0;
+  let fixtures = 0;
+  for (const e of entries) {
+    if (e.resolvedAt) { resolved += 1; continue; }
+    if (isExpired(e, now)) { expired += 1; continue; }
+    if (referencesFixture(e)) { fixtures += 1; continue; }
+    kept.push(e);
+  }
+  const removed = resolved + expired + fixtures;
+  if (removed > 0) {
+    writeFileSync(pendingPath(), kept.length ? kept.map((e) => JSON.stringify(e)).join('\n') + '\n' : '');
+  }
+  return { removed, resolved, expired, fixtures, kept: kept.length };
 }
 
 // Drain events that accumulated outside a Claude session. Walks recent