@geraldmaron/construct 1.0.19 → 1.0.21

package/lib/ingest/strategy.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/ingest/strategy.mjs — resolve the ingest extraction strategy and provider model.
+ *
+ * Construct's ingest path historically extracted documents through local binary
+ * adapters (docling/whisper/pdftotext) without surfacing that choice. This module
+ * makes the choice explicit and configurable:
+ *   - `adapter` (default): the local-extractor pipeline, byte-for-byte unchanged.
+ *   - `provider`: route document understanding through the configured provider/model.
+ * A `fallback` policy (`none`/`provider`/`adapter`) governs what happens on
+ * primary-path failure; the default `none` never silently masks a strategy
+ * mismatch. Resolution precedence matches the project-config convention:
+ * env > config > default. Provider/model identification reuses the embedded model
+ * resolution contract and the tier registry so no second selection surface exists.
+ */
+
+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;
+  const lowered = value.trim().toLowerCase();
+  return allowed.includes(lowered) ? lowered : null;
+}
+
+// The strategy step a document-understanding model serves under is `fast`; ingest
+// is an extraction/understanding pass, not a reasoning workflow. The embedded
+// resolution contract maps this tier to a concrete provider/model.
+
+const INGEST_WORKFLOW_TYPE = 'evidence-ingest';
+
+function resolveProviderModel({ env, registryPath }) {
+  const resolved = resolveEmbeddedModel({ workflowType: INGEST_WORKFLOW_TYPE }, { env, registryPath });
+  return {
+    model: resolved.selectedModel || null,
+    provider: resolved.selectedProvider || null,
+    resolutionSource: resolved.resolutionSource || null,
+    error: resolved.error || null,
+  };
+}
+
+/**
+ * Resolve the effective ingest strategy, fallback policy, and provider model.
+ *
+ * Precedence for both strategy and fallback is env > config > explicit override
+ * > default, where an explicit `override` (a CLI flag) wins over env/config when
+ * provided. The returned `model`/`provider` are non-null only when the resolved
+ * strategy is `provider` or when `fallback` could route to a provider.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]      loaded project config object
+ * @param {Record<string,string>} [opts.env]
+ * @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, orchestration:string, model:(string|null), provider:(string|null), modelResolution:(object|null), execution:object}}
+ */
+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({
+    config,
+    jsonPath: 'ingest.strategy',
+    env,
+    envKey: 'CONSTRUCT_INGEST_STRATEGY',
+    defaultValue: DEFAULT_INGEST_STRATEGY,
+  });
+  const strategy = overrideStrategy
+    || coerceEnum(fromSettings.value, INGEST_STRATEGIES)
+    || DEFAULT_INGEST_STRATEGY;
+
+  const fallbackSetting = resolveSetting({
+    config,
+    jsonPath: 'ingest.fallback',
+    env,
+    envKey: 'CONSTRUCT_INGEST_FALLBACK',
+    defaultValue: DEFAULT_INGEST_FALLBACK,
+  });
+  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/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/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/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,
+  }));
+}