@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/observation-store.mjs

@@ -4,31 +4,36 @@
  * Stores distilled insights that specialists learn during work:
  *   - patterns, anti-patterns, dependency relationships, decisions, insights
  *   - each scoped to a role (cx-engineer, cx-architect, etc.)
- *   - vector-indexed for semantic search via hashing-bow-v1
+ *   - vector-indexed for semantic search via embedded LanceDB
  *
  * Storage layout:
  *   .cx/observations/index.json      — lightweight listing for fast filtering
  *   .cx/observations/<id>.json       — full observation record
- *   .cx/observations/vectors.json    — local vector index for semantic search
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { cosineSimilarity, rankByBm25 } from './storage/embeddings.mjs';
-import { embedSync as embedText } from './storage/embeddings-legacy.mjs';
 import { embedText as embedTextEngine } from './storage/embeddings-engine.mjs';
 import { VectorClient } from './storage/vector-client.mjs';
-import { withFileLockSync } from './storage/file-lock.mjs';
 import { ensureCxDir } from './project-init-shared.mjs';
 
 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.
+// VectorClient resolves its store from CONSTRUCT_LANCEDB_PATH and otherwise
+// falls back to process.cwd(). Observations are scoped to rootDir, so when no
+// explicit path is configured (tests, unmanaged checkouts) the vector store
+// must follow rootDir — not the caller's cwd — or a reader in a different cwd
+// than the writer sees an empty table. A configured path (managed installs)
+// is left untouched so the home-global store keeps working.
+
+function vectorClientFor(rootDir) {
+  const env = process.env.CONSTRUCT_LANCEDB_PATH
+    ? process.env
+    : { ...process.env, CONSTRUCT_LANCEDB_PATH: path.join(rootDir, '.cx', 'lancedb') };
+  return new VectorClient({ env });
+}
 
 export function observationSearchText(obs) {
   return [obs.summary, obs.content, ...(obs.tags || [])].filter(Boolean).join(' ');
@@ -40,9 +45,6 @@ export function observationContentHash(text) {
 const MAX_SUMMARY = 500;
 const MAX_CONTENT = 2000;
 const MAX_TAGS = 10;
-// Size guardrail: surfaces in `construct doctor` when the observation tree
-// exceeds this byte cap. Doesn't drop data — the operator decides whether to
-// run `construct memory consolidate` (which prunes archive) or raise the cap.
 const MAX_BYTES = 50 * 1024 * 1024;
 
 const VALID_CATEGORIES = new Set([
@@ -50,8 +52,6 @@ const VALID_CATEGORIES = new Set([
 ]);
 
 function ensureDir(dir, rootDir = null) {
-  // Preserves the construct context invariant: any code that creates a .cx/
-  // subdirectory also initializes context.md from the project template.
   if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
@@ -64,10 +64,6 @@ function indexPath(rootDir) {
   return path.join(obsDir(rootDir), INDEX_FILE);
 }
 
-function vectorsPath(rootDir) {
-  return path.join(obsDir(rootDir), VECTORS_FILE);
-}
-
 function generateId() {
   const ts = Date.now().toString(36);
   const rand = crypto.randomBytes(4).toString('hex');
@@ -132,30 +128,6 @@ function writeIndex(rootDir, entries) {
   return { dropped };
 }
 
-function readVectors(rootDir) {
-  const p = vectorsPath(rootDir);
-  if (!fs.existsSync(p)) return [];
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return [];
-  }
-}
-
-function writeVectors(rootDir, records) {
-  ensureDir(obsDir(rootDir), rootDir);
-  const dropped = Math.max(0, records.length - MAX_INDEX);
-  if (dropped > 0) {
-    logCapDrop(rootDir, 'observation-vectors', dropped, records.length);
-  }
-  fs.writeFileSync(vectorsPath(rootDir), JSON.stringify(records, null, 2) + '\n');
-  return { dropped };
-}
-
-/**
- * Add a new observation and vectorize it for semantic search.
- * Uses SQL + neural embeddings when available, falls back to local JSON + hashing.
- */
 export async function addObservation(rootDir, {
   role = 'unknown',
   category = 'insight',
@@ -175,10 +147,9 @@ export async function addObservation(rootDir, {
   const clampedSummary = clamp(String(summary), MAX_SUMMARY);
   const clampedContent = clamp(String(content), MAX_CONTENT);
   const clampedTags = (Array.isArray(tags) ? tags : []).slice(0, MAX_TAGS).map(String);
-  // Structured metadata: opt-in. Capped at 2 KB stringified so a misuse can't
-  // bloat the per-id JSON. Plain object only; rejects arrays and functions.
   const clampedExtras = sanitizeExtras(extras);
 
+  const effectiveProject = project ? String(project) : rootDir.split('/').pop();
   const record = {
     id,
     role: String(role),
@@ -186,7 +157,7 @@ export async function addObservation(rootDir, {
     summary: clampedSummary,
     content: clampedContent,
     tags: clampedTags,
-    project: project ? String(project) : null,
+    project: effectiveProject,
     confidence: Math.max(0, Math.min(1, Number(confidence) || 0.8)),
     source: source || null,
     gitSha: gitSha ? String(gitSha).slice(0, 40) : null,
@@ -195,37 +166,30 @@ export async function addObservation(rootDir, {
     updatedAt: now,
   };
 
-  // Lock the per-store index so concurrent writers (CLI + hooks) cannot
-  // corrupt the index/vectors JSON pair. The observation JSON file is
-  // unique-per-id and doesn't need the lock; the shared structures do.
   ensureDir(obsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(obsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + '\n',
   );
 
-  let indexDropped = 0;
-  withFileLockSync(indexPath(rootDir), () => {
-    const index = readIndex(rootDir);
-    index.unshift({
-      id,
-      role: record.role,
-      category: record.category,
-      summary: record.summary,
-      project: record.project,
-      createdAt: now,
-    });
-    indexDropped = writeIndex(rootDir, index).dropped;
+  const index = readIndex(rootDir);
+  index.unshift({
+    id,
+    role: record.role,
+    category: record.category,
+    summary: record.summary,
+    project: record.project,
+    createdAt: now,
   });
+  const indexDropped = writeIndex(rootDir, index).dropped;
   if (indexDropped > 0) {
     record.capDropped = indexDropped;
     process.stderr.write(`[observation-store] observation cap reached: ${indexDropped} oldest entries evicted (cap=${MAX_INDEX})\n`);
   }
 
-  // Try SQL storage with neural embeddings
   try {
-    const client = new VectorClient();
-    if (await client.isHealthy() && await client.isPgvectorEnabled()) {
+    const client = vectorClientFor(rootDir);
+    if (await client.isHealthy()) {
       const searchText = observationSearchText(record);
       const { embedding, model } = await embedTextEngine(searchText);
       await client.storeObservation({
@@ -234,30 +198,15 @@ export async function addObservation(rootDir, {
         contentHash: observationContentHash(searchText),
         model,
       });
-      await client.close();
-      return record;
     }
     await client.close();
-  } catch {
-    // Fall through to local vector storage
+  } catch (err) {
+    process.stderr.write(`[observation-store] vector store failed; kept observation in local index: ${err?.message || err}\n`);
   }
 
-  // Fallback: local JSON vector index with hashing-bow-v1.
-  const searchText = [record.summary, record.content, ...record.tags].filter(Boolean).join(' ');
-  const embedding = embedText(searchText);
-  withFileLockSync(vectorsPath(rootDir), () => {
-    const vectors = readVectors(rootDir);
-    vectors.push({ id, embedding, role: record.role, category: record.category, project: record.project });
-    writeVectors(rootDir, vectors.slice(-MAX_INDEX));
-  });
-
   return record;
 }
 
-/**
- * Search observations using SQL + neural embeddings when available,
- * falling back to hybrid cosine + BM25 on local JSON.
- */
 export async function searchObservations(rootDir, query, {
   role = null,
   category = null,
@@ -266,16 +215,15 @@ export async function searchObservations(rootDir, query, {
 } = {}) {
   if (!query) return [];
 
-  // Try SQL + neural embeddings first
   try {
-    const client = new VectorClient();
-    if (await client.isHealthy() && await client.isPgvectorEnabled()) {
+    const client = vectorClientFor(rootDir);
+    if (await client.isHealthy()) {
       const { embedding } = await embedTextEngine(String(query));
       const results = await client.searchObservations({
         project: project || rootDir.split('/').pop(),
         queryEmbedding: embedding,
         limit,
-        minSimilarity: 0.1,
+        minSimilarity: 0.01,
         role,
         category,
       });
@@ -284,6 +232,7 @@ export async function searchObservations(rootDir, query, {
         id: r.id,
         role: r.role,
         category: r.category,
+        project: r.project,
         summary: r.summary,
         content: r.content,
         tags: r.tags || [],
@@ -295,65 +244,12 @@ export async function searchObservations(rootDir, query, {
     }
     await client.close();
   } catch {
-    // Fall through to local JSON search
+    // If Vector search fails, return empty since fallback is removed.
   }
 
-  // Fallback: local JSON + hashing-bow-v1
-  const queryEmbedding = embedText(String(query));
-  let vectors = readVectors(rootDir);
-
-  if (role) vectors = vectors.filter((v) => v.role === role);
-  if (category) vectors = vectors.filter((v) => v.category === category);
-  if (project) vectors = vectors.filter((v) => v.project === project);
-
-  // Cosine pass
-  const cosineScored = vectors
-    .map((v) => ({
-      id: v.id,
-      score: cosineSimilarity(queryEmbedding, v.embedding || []),
-    }))
-    .filter(({ score }) => score > 0.05);
-
-  // Load full records for BM25 pass
-  const candidateIds = new Set(cosineScored.map((v) => v.id));
-  const recentIndex = readIndex(rootDir);
-  const filtered = role ? recentIndex.filter((e) => e.role === role) : recentIndex;
-  const filteredCat = category ? filtered.filter((e) => e.category === category) : filtered;
-  const filteredProj = project ? filteredCat.filter((e) => e.project === project) : filteredCat;
-  for (const entry of filteredProj.slice(0, Math.max(limit * 3, 30))) candidateIds.add(entry.id);
-
-  const candidateRecords = [...candidateIds]
-    .map((id) => getObservation(rootDir, id))
-    .filter(Boolean)
-    .map((r) => ({ ...r, text: [r.summary, r.content, ...(r.tags || [])].filter(Boolean).join(' ') }));
-
-  const bm25Scored = rankByBm25(candidateRecords, query, { limit: limit * 2 });
-
-  // Merge: highest score wins per id
-  const scoreMap = new Map();
-  for (const { id, score } of cosineScored) {
-    scoreMap.set(id, score);
-  }
-  for (const item of bm25Scored) {
-    const prev = scoreMap.get(item.id) || 0;
-    const bm25Max = bm25Scored[0]?.score || 1;
-    const normalized = Math.min(item.score / bm25Max, 1);
-    scoreMap.set(item.id, Math.max(prev, normalized));
-  }
-
-  return [...scoreMap.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, limit)
-    .map(([id, score]) => {
-      const record = getObservation(rootDir, id);
-      return record ? { ...record, score } : null;
-    })
-    .filter(Boolean);
+  return [];
 }
 
-/**
- * List observations from the index with optional filters.
- */
 export function listObservations(rootDir, {
   role = null,
   category = null,
@@ -367,9 +263,6 @@ export function listObservations(rootDir, {
   return entries.slice(0, limit);
 }
 
-/**
- * Load a full observation record by ID.
- */
 export function getObservation(rootDir, id) {
   const filePath = path.join(obsDir(rootDir), `${id}.json`);
   if (!fs.existsSync(filePath)) return null;
@@ -380,31 +273,17 @@ export function getObservation(rootDir, id) {
   }
 }
 
-/**
- * Delete an observation by id.
- */
 export function deleteObservation(rootDir, id) {
   const filePath = path.join(obsDir(rootDir), `${id}.json`);
   if (fs.existsSync(filePath)) fs.rmSync(filePath, { force: true });
 
-  withFileLockSync(indexPath(rootDir), () => {
-    const index = readIndex(rootDir);
-    const filtered = index.filter((e) => e.id !== id);
-    if (filtered.length !== index.length) writeIndex(rootDir, filtered);
-  });
-
-  withFileLockSync(vectorsPath(rootDir), () => {
-    const vectors = readVectors(rootDir);
-    const filteredVec = vectors.filter((v) => v.id !== id);
-    if (filteredVec.length !== vectors.length) writeVectors(rootDir, filteredVec);
-  });
+  const index = readIndex(rootDir);
+  const filtered = index.filter((e) => e.id !== id);
+  if (filtered.length !== index.length) writeIndex(rootDir, filtered);
 
   return true;
 }
 
-/**
- * Count observations, optionally filtered.
- */
 export function countObservations(rootDir, { role = null, project = null } = {}) {
   let entries = readIndex(rootDir);
   if (role) entries = entries.filter((e) => e.role === role);
@@ -412,9 +291,6 @@ export function countObservations(rootDir, { role = null, project = null } = {})
   return entries.length;
 }
 
-// On-disk byte size of the observation tree (live + archive) at rootDir.
-// Backs the `Observation size` doctor surface so size pressure shows up
-// independently of count-based caps.
 export function getObservationsSize(rootDir) {
   const root = obsDir(rootDir);
   if (!fs.existsSync(root)) return 0;
@@ -435,4 +311,4 @@ export function getObservationsSize(rootDir) {
 export function checkObservationsSize(rootDir, { cap = MAX_BYTES } = {}) {
   const size = getObservationsSize(rootDir);
   return { size, cap, ok: size <= cap };
-}
+}

package/lib/opencode-config.mjs

@@ -48,7 +48,7 @@ export function sanitizeOpenCodeConfig(config) {
 
 export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
   // Treat the canonical home config as the default target; any explicit path
-  // outside the canonical home dir (e.g. project-scoped .opencode/config.json)
+  // outside the canonical home dir (e.g. project-scoped .opencode/opencode.json)
   // is honored as-is so per-project sync writes to the right tree.
 
   const canonical = getCanonicalOpenCodeConfigPath();

package/lib/orchestration/events.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/orchestration/events.mjs — in-process run lifecycle event bus.
+ *
+ * The orchestration runtime persists runs to a store and appends durable JSONL
+ * traces, but has no live pub/sub a server can stream from. This is that
+ * primitive: a process-local EventEmitter keyed by runId so an HTTP SSE handler
+ * can subscribe to a single run's transitions (planned → running → per-task →
+ * completed) and forward them to a thin client. Events are lightweight status
+ * deltas — never task output or any credential — so the stream stays cheap and
+ * secret-free; clients fetch full run records (envelope-guarded) for outputs.
+ *
+ * Process-local by design: it streams runs executing in THIS process. Durable,
+ * cross-process history lives in the run store and the trace log.
+ */
+
+import { EventEmitter } from 'node:events';
+
+const bus = new EventEmitter();
+bus.setMaxListeners(0);
+
+function channel(runId) {
+  return `run:${runId}`;
+}
+
+/**
+ * Emit a run lifecycle event. Stamps runId + an ISO timestamp; callers pass a
+ * small status delta (type, status, taskId, role, executor, error).
+ *
+ * @param {string} runId
+ * @param {object} event
+ */
+export function emitRunEvent(runId, event = {}) {
+  if (!runId) return;
+  bus.emit(channel(runId), { runId, at: new Date().toISOString(), ...event });
+}
+
+/**
+ * Subscribe to one run's events.
+ *
+ * @param {string} runId
+ * @param {(event:object)=>void} handler
+ * @returns {() => void} unsubscribe
+ */
+export function onRunEvent(runId, handler) {
+  const ch = channel(runId);
+  bus.on(ch, handler);
+  return () => bus.off(ch, handler);
+}
+
+// Cooperative, between-task cancellation. executeRun checks this before each
+// task and stops cleanly if set — an honest soft cancel (it cannot abort a
+// model call already in flight), not a forced kill.
+
+const cancelled = new Set();
+
+export function requestCancel(runId) {
+  if (runId) cancelled.add(runId);
+}
+
+export function isCancelRequested(runId) {
+  return cancelled.has(runId);
+}
+
+export function clearCancel(runId) {
+  cancelled.delete(runId);
+}

package/lib/orchestration/runtime.mjs

@@ -35,12 +35,16 @@ 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 { CHAIN_OF_THOUGHT_MODES } from '../config/schema.mjs';
 import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
 import { resolveRunStore } from './store.mjs';
 import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
+import { emitRunEvent, isCancelRequested, clearCancel } from './events.mjs';
 
 export const WORKER_BACKENDS = WORKER_BACKEND_SET;
 export const DEFAULT_WORKER_BACKEND = INLINE;
+export const CHAIN_OF_THOUGHT = CHAIN_OF_THOUGHT_MODES;
+export const DEFAULT_CHAIN_OF_THOUGHT = 'hidden';
 
 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.';
 
@@ -97,6 +101,7 @@ function buildTasks(route) {
     status: 'queued',
     executor: null,
     output: null,
+    reasoning: null,
     error: null,
     startedAt: null,
     finishedAt: null,
@@ -112,6 +117,16 @@ function resolveWorkerBackend({ explicit, run, config }) {
   return WORKER_BACKENDS.includes(candidate) ? candidate : DEFAULT_WORKER_BACKEND;
 }
 
+// Chain-of-thought disclosure is a deployment concern (ADR-0030): an explicit
+// option wins, then the run's recorded mode, then config
+// (orchestration.chainOfThought), then the hidden default. An unknown value
+// falls back to hidden — specialist reasoning is never surfaced by guess.
+
+function resolveChainOfThought({ explicit, run, config }) {
+  const candidate = explicit || run?.chainOfThought || config?.orchestration?.chainOfThought || DEFAULT_CHAIN_OF_THOUGHT;
+  return CHAIN_OF_THOUGHT.includes(candidate) ? candidate : DEFAULT_CHAIN_OF_THOUGHT;
+}
+
 function loadConfig(cwd, env) {
   try {
     return loadProjectConfig(cwd, env).config || {};
@@ -132,6 +147,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
   const {
     request: text = '', workflowType = null, requestedStrategy = 'auto', useConstruct = true,
     host = null, hostModel = null, hostProvider = null, fileCount = 0, moduleCount = 0,
+    workerBackend: explicitWorkerBackend = null,
   } = request;
 
   const config = loadConfig(cwd, env);
@@ -146,7 +162,8 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
   const traceId = newTraceId();
   const runId = newRunId();
   const now = new Date().toISOString();
-  const workerBackend = resolveWorkerBackend({ config });
+  const workerBackend = resolveWorkerBackend({ explicit: explicitWorkerBackend, config });
+  const chainOfThought = resolveChainOfThought({ 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
@@ -162,6 +179,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
     request: { summary: truncate(text, 200), workflowType, requestedStrategy },
     hostRole: resolveHostRole(host),
     workerBackend,
+    chainOfThought,
     execution: pickExecution(execData),
     plan: {
       intent: route.intent,
@@ -182,6 +200,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
     rootDir: cwd, env, traceId, spanId: newSpanId(), eventType: 'task_graph.created',
     metadata: { runId, executionMode: run.execution.executionMode, specialists: run.plan.specialists, workerBackend: run.workerBackend },
   });
+  emitRunEvent(runId, { type: 'planned', status: 'planned', executionMode: run.execution.executionMode, taskCount: tasks.length });
   return run;
 }
 
@@ -198,25 +217,29 @@ function prepareTaskInline(task) {
 // 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) {
+async function executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought) {
   try {
     const result = await runTaskViaProvider({
       task, run,
       model: run.execution?.selectedModel,
       provider: run.execution?.selectedProvider,
-      env, fetchImpl,
+      env, fetchImpl, chainOfThought,
     });
     task.output = result.output;
     task.executor = `provider:${result.provider}:${result.model}`;
     task.status = 'done';
     task.finishedAt = new Date().toISOString();
-    return true;
+
+    // `surface` attaches reasoning to the task so every display surface renders
+    // it; `telemetry_only` keeps it off the task (recorded only in the trace).
+    if (chainOfThought === 'surface' && result.reasoning) task.reasoning = result.reasoning;
+    return { ok: true, reasoning: result.reasoning || '' };
   } 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;
+    return { ok: false, reasoning: '' };
   }
 }
 
@@ -240,33 +263,51 @@ export async function executeRun(cwd, runId, { env = process.env, workerBackend
   }
 
   const backend = resolveWorkerBackend({ explicit: workerBackend, run, config });
+  const chainOfThought = resolveChainOfThought({ run, config });
   run.workerBackend = backend;
+  run.chainOfThought = chainOfThought;
   run.status = 'running';
   run.updatedAt = new Date().toISOString();
   await store.saveRun(run);
+  emitRunEvent(runId, { type: 'running', status: 'running', workerBackend: backend });
 
   let anyFailed = false;
+  let cancelled = false;
   for (const task of run.tasks) {
+    if (isCancelRequested(runId)) { cancelled = true; break; }
     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, workerBackend: backend } });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: 'running' });
 
+    let taskReasoning = '';
     if (backend === PROVIDER) {
-      const ok = await executeTaskViaProvider(task, run, env, fetchImpl);
-      if (!ok) anyFailed = true;
+      const res = await executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought);
+      if (!res.ok) anyFailed = true;
+      taskReasoning = res.reasoning;
     } 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 } });
+    // telemetry_only records reasoning to the trace without ever surfacing it to
+    // a display; surface keeps it off the trace (it rides on task.reasoning).
+    const completedMeta = { runId, status: task.status };
+    if (chainOfThought === 'telemetry_only' && taskReasoning) {
+      completedMeta.reasoning = taskReasoning;
+      completedMeta.reasoningChars = taskReasoning.length;
+    }
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: completedMeta });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: task.status, executor: task.executor, ...(task.reasoning ? { reasoning: task.reasoning } : {}), ...(task.error ? { error: task.error } : {}) });
     run.updatedAt = new Date().toISOString();
     await store.saveRun(run);
   }
 
-  run.status = anyFailed ? 'completed-with-failures' : 'completed';
+  run.status = cancelled ? 'cancelled' : (anyFailed ? 'completed-with-failures' : 'completed');
   run.updatedAt = new Date().toISOString();
   await store.saveRun(run);
+  clearCancel(runId);
   emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
+  emitRunEvent(runId, { type: 'completed', status: run.status });
   return run;
 }
 
@@ -278,6 +319,26 @@ export async function runOrchestration(request = {}, { env = process.env, cwd =
   return executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl });
 }
 
+/**
+ * Start a run for a thin client: plan + persist synchronously, then execute in
+ * the BACKGROUND (not awaited) so the caller gets a runId immediately and tracks
+ * progress via the event stream / run store. Execution failures are caught and
+ * surfaced as a terminal `error` run event rather than an unhandled rejection.
+ *
+ * @param {object} request
+ * @param {object} [opts]   { env, cwd, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the planned run (status `planned`)
+ */
+export async function startRun(request = {}, { env = process.env, cwd = process.cwd(), workerBackend = null, fetchImpl } = {}) {
+  const planned = await planRun(request, { env, cwd });
+  Promise.resolve()
+    .then(() => executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl }))
+    .catch((err) => {
+      emitRunEvent(planned.runId, { type: 'error', status: 'error', error: { code: err.code || 'RUN_FAILED', message: err.message } });
+    });
+  return planned;
+}
+
 /**
  * The structured metadata a host adapter consumes for runtime-backed integration.
  */
@@ -292,12 +353,13 @@ export function hostAdapterMetadata(run) {
     executionMode: e.executionMode,
     constructCapabilitiesActive: e.constructCapabilitiesActive,
     workerBackend: run.workerBackend,
+    chainOfThought: run.chainOfThought ?? null,
     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 })),
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null, output: t.output ?? null, error: t.error ?? null })),
     warnings: run.warnings || [],
     semantics: run.semantics,
     executionSemantics: run.executionSemantics,