@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/worker/entrypoint.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * lib/worker/entrypoint.mjs — long-running worker loop for team / enterprise mode.
+ *
+ * Claims pending intake items from the Postgres-backed queue and runs them
+ * through `runJob`, attaching evidence to the originating task graph node.
+ * Exits when the queue stays empty for `--idle-timeout-seconds` (default
+ * 300s) so a Kubernetes / nomad scheduler can scale workers to zero.
+ *
+ * The container's path policy is the workspace mount: `runJob` enforces
+ * `allowedPaths: [workspace]` so the worker can only touch the
+ * bind-mounted project tree even if a malicious command tries `..`.
+ *
+ * Invocation (inside the image):
+ *   node lib/worker/entrypoint.mjs \
+ *     --project=<project-name> \
+ *     --workspace=/work \
+ *     --idle-timeout-seconds=300 \
+ *     --poll-interval-ms=2000
+ *
+ * Env: DATABASE_URL must be set. The container reads it from the platform
+ * (compose / k8s secret); the entrypoint does not source ~/.construct/config.env.
+ */
+
+import path from 'node:path';
+
+import { createSqlClient, closeSqlClient } from '../storage/backend.mjs';
+import { PostgresIntakeQueue } from '../intake/postgres-queue.mjs';
+import { FilesystemTaskGraphStore } from '../task-graph/store.mjs';
+import { runJob } from './run.mjs';
+import { evidenceFromJobResult, recordEvidence, blockedPacket } from './evidence.mjs';
+import { emitTraceEvent, newTraceId } from './trace.mjs';
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_IDLE_TIMEOUT_SECONDS = 300;
+const DEFAULT_TIMEOUT_SECONDS = 300;
+
+function parseArgs(argv) {
+  const out = {};
+  for (const arg of argv.slice(2)) {
+    const m = arg.match(/^--([a-z-]+)(?:=(.*))?$/);
+    if (!m) continue;
+    out[m[1]] = m[2] === undefined ? true : m[2];
+  }
+  return out;
+}
+
+function readWorkerName() {
+  return process.env.HOSTNAME || `worker-${process.pid}`;
+}
+
+function logEvent(rootDir, eventType, fields = {}) {
+  try {
+    emitTraceEvent({
+      rootDir,
+      eventType,
+      ...fields,
+    });
+  } catch { /* observability never breaks the worker loop */ }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Map an intake packet to a worker job. The packet's triage names the
+ * recommendedAction; we read the project's verification requirements
+ * from the task graph (if one was auto-generated) or fall back to a
+ * conservative `node --version` smoke command so the worker always
+ * has something to execute against and the queue drains.
+ */
+function jobFromPacket(packet, { workspace, defaultCommand }) {
+  const command = packet?.workerCommand || defaultCommand;
+  return {
+    jobId: `${packet.id}-${Date.now()}`,
+    taskId: packet.id,
+    project: packet.intake?.project || null,
+    workspaceRef: workspace,
+    command,
+    args: [],
+    timeoutSeconds: packet?.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS,
+    envPolicy: 'restricted',
+    allowedPaths: [workspace],
+  };
+}
+
+/**
+ * Process one claimed packet end-to-end: run the command, record evidence
+ * if a graph node is named in the packet, mark the queue item processed
+ * or blocked. Returns true on success, false on failure (which surfaces
+ * a blocked packet for human review).
+ */
+async function processClaim({ packet, queue, store, rootDir, workspace, defaultCommand, workerName }) {
+  const traceId = packet?.traceId || newTraceId();
+  const job = jobFromPacket(packet, { workspace, defaultCommand });
+
+  let result;
+  try {
+    result = await runJob({
+      rootDir,
+      job: { ...job, traceId },
+    });
+  } catch (err) {
+    logEvent(rootDir, 'worker.completed', {
+      traceId,
+      project: job.project,
+      taskId: job.taskId,
+      metadata: { status: 'errored', error: err?.message || String(err) },
+    });
+    await queue.markSkipped(packet.id, {
+      skippedBy: workerName,
+      reason: `worker exec error: ${err?.message || String(err)}`,
+    });
+    return false;
+  }
+
+  // If the packet carries graphId + nodeId, attach evidence to that node.
+  if (packet?.graphId && packet?.nodeId) {
+    try {
+      const evidence = evidenceFromJobResult(result, {
+        evidenceType: packet.evidenceType || 'test-result',
+      });
+      recordEvidence({
+        store,
+        graphId: packet.graphId,
+        nodeId: packet.nodeId,
+        evidence,
+        rootDir,
+      });
+    } catch { /* evidence write best-effort */ }
+  }
+
+  if (result.status === 'passed') {
+    await queue.markProcessed(packet.id, {
+      processedBy: workerName,
+      notes: `passed in ${result.durationMs}ms`,
+    });
+    return true;
+  }
+
+  // Failure path: surface as a blocked packet with attempted steps so the
+  // main agent can pick it up and decide next.
+  const reason = result.status === 'timeout'
+    ? `command timed out after ${packet?.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS}s`
+    : `command failed with exit code ${result.exitCode}`;
+  const attempted = [job.command];
+  const blocked = blockedPacket({ taskId: packet.id, reason, attempted });
+  await queue.markSkipped(packet.id, {
+    skippedBy: workerName,
+    reason: `${reason}; stdout=${result.stdoutPath}; stderr=${result.stderrPath}`,
+  });
+  logEvent(rootDir, 'worker.completed', {
+    traceId,
+    project: job.project,
+    taskId: job.taskId,
+    metadata: { status: result.status, exitCode: result.exitCode, blocked, durationMs: result.durationMs },
+  });
+  return false;
+}
+
+/**
+ * Long-running worker loop. Resolves with the run statistics when the
+ * idle timeout elapses or when `stopAfter` jobs have completed (test mode).
+ */
+export async function runWorkerLoop({
+  rootDir,
+  workspace,
+  project,
+  sql,
+  queue: injectedQueue = null,
+  store: injectedStore = null,
+  pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+  idleTimeoutSeconds = DEFAULT_IDLE_TIMEOUT_SECONDS,
+  defaultCommand = 'node --version',
+  stopAfter = null,
+  now = Date.now,
+} = {}) {
+  if (!project) throw new Error('runWorkerLoop: project is required');
+  if (!workspace) throw new Error('runWorkerLoop: workspace is required');
+  if (!injectedQueue && !sql) throw new Error('runWorkerLoop: sql client (or injected queue) is required');
+
+  const workerName = readWorkerName();
+  const queue = injectedQueue || new PostgresIntakeQueue({ sql, project });
+  const store = injectedStore || new FilesystemTaskGraphStore(rootDir);
+
+  let processed = 0;
+  let skipped = 0;
+  let idleSince = now();
+
+  while (true) {
+    const claimed = await queue.claim({ claimedBy: workerName });
+    if (claimed) {
+      const ok = await processClaim({
+        packet: claimed,
+        queue,
+        store,
+        rootDir,
+        workspace,
+        defaultCommand,
+        workerName,
+      });
+      if (ok) processed += 1; else skipped += 1;
+      idleSince = now();
+      if (stopAfter && (processed + skipped) >= stopAfter) break;
+      continue;
+    }
+
+    if ((now() - idleSince) >= idleTimeoutSeconds * 1000) break;
+    await sleep(pollIntervalMs);
+  }
+
+  return { processed, skipped, workerName };
+}
+
+// CLI entrypoint when invoked directly (the Dockerfile.worker CMD).
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  const args = parseArgs(process.argv);
+  const workspace = args.workspace || process.env.CONSTRUCT_WORKSPACE || process.cwd();
+  const rootDir = args['root-dir'] || workspace;
+  const project = args.project || process.env.CONSTRUCT_PROJECT_NAME || path.basename(path.resolve(workspace));
+  const pollIntervalMs = Number(args['poll-interval-ms'] || DEFAULT_POLL_INTERVAL_MS);
+  const idleTimeoutSeconds = Number(args['idle-timeout-seconds'] || DEFAULT_IDLE_TIMEOUT_SECONDS);
+
+  const sql = createSqlClient(process.env);
+  if (!sql) {
+    process.stderr.write('[worker] DATABASE_URL is required for the worker entrypoint.\n');
+    process.exit(78); // EX_CONFIG
+  }
+
+  try {
+    const summary = await runWorkerLoop({
+      rootDir, workspace, project, sql, pollIntervalMs, idleTimeoutSeconds,
+    });
+    process.stdout.write(`[worker] exiting after idle timeout — processed=${summary.processed} skipped=${summary.skipped} worker=${summary.workerName}\n`);
+    process.exit(0);
+  } finally {
+    await closeSqlClient(sql);
+  }
+}

package/lib/worker/evidence.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/worker/evidence.mjs — record verified evidence onto task graph nodes.
+ *
+ * Evidence is the contract that lets a node move from in-progress → done.
+ * The worker plane emits one evidence record per executed job; the
+ * higher-level dispatcher refuses to mark a node done without at least
+ * one evidence entry. BLOCKED and NEEDS_MAIN_INPUT statuses carry their
+ * own dedicated schemas: BLOCKED requires `attempted` steps; NEEDS_MAIN_INPUT
+ * requires `question`, `safeDefault`, and `context` fields.
+ *
+ * Evidence record shape:
+ *   {
+ *     taskId, evidenceType, command?, status, summary,
+ *     artifacts?, traceId?, createdAt
+ *   }
+ */
+
+import { emitTraceEvent } from './trace.mjs';
+
+export const EVIDENCE_TYPES = [
+  'test-result',
+  'lint-result',
+  'build-result',
+  'retrieval-eval',
+  'manual-verification',
+  'source-citation',
+  'trace-link',
+  'sample-output',
+];
+
+function buildSummary(jobResult) {
+  if (!jobResult) return '';
+  const head = `${jobResult.status} · exit ${jobResult.exitCode} · ${jobResult.durationMs}ms`;
+  return head;
+}
+
+export function evidenceFromJobResult(jobResult, { evidenceType = 'test-result', summary } = {}) {
+  if (!jobResult?.taskId) throw new Error('evidenceFromJobResult: jobResult.taskId is required');
+  return {
+    taskId: jobResult.taskId,
+    evidenceType,
+    command: jobResult.command || null,
+    status: jobResult.status,
+    summary: summary || buildSummary(jobResult),
+    artifacts: jobResult.artifacts || [],
+    traceId: jobResult.traceId || null,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Append an evidence record to a task graph node and emit the matching
+ * trace event. Returns the updated node.
+ */
+export function recordEvidence({ store, graphId, nodeId, evidence, rootDir, emitEvent = emitTraceEvent }) {
+  if (!store) throw new Error('recordEvidence: store is required');
+  if (!graphId || !nodeId) throw new Error('recordEvidence: graphId and nodeId are required');
+  if (!evidence) throw new Error('recordEvidence: evidence is required');
+
+  const node = store.updateNodeStatus(graphId, nodeId, undefined, { addEvidence: evidence });
+
+  if (rootDir) {
+    emitEvent({
+      rootDir,
+      eventType: 'evidence.recorded',
+      traceId: evidence.traceId || undefined,
+      project: node.project,
+      taskId: nodeId,
+      metadata: {
+        evidenceType: evidence.evidenceType,
+        status: evidence.status,
+        summary: evidence.summary,
+      },
+    });
+  }
+  return node;
+}
+
+export function blockedPacket({ taskId, attempted = [], reason }) {
+  if (!taskId) throw new Error('blockedPacket: taskId is required');
+  if (!reason) throw new Error('blockedPacket: reason is required');
+  if (!Array.isArray(attempted) || attempted.length === 0) {
+    throw new Error('blockedPacket: at least one attempted step is required');
+  }
+  return {
+    taskId,
+    status: 'blocked',
+    reason,
+    attempted,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function needsInputPacket({ taskId, question, safeDefault, context }) {
+  if (!taskId) throw new Error('needsInputPacket: taskId is required');
+  if (!question) throw new Error('needsInputPacket: question is required');
+  if (safeDefault === undefined) throw new Error('needsInputPacket: safeDefault is required (use null if none)');
+  if (!context) throw new Error('needsInputPacket: context is required');
+  return {
+    taskId,
+    status: 'needs-input',
+    question,
+    safeDefault,
+    context,
+    createdAt: new Date().toISOString(),
+  };
+}

package/lib/worker/run.mjs

@@ -0,0 +1,154 @@
+/**
+ * lib/worker/run.mjs — bounded command execution for the worker plane.
+ *
+ * Runs a single shell command with a hard timeout and a path-policy
+ * check so workers cannot write outside their allowed workspace. The
+ * worker plane stays decoupled from the control plane: this module
+ * accepts a job descriptor and returns a job result; it does not pick
+ * what to run or interpret the result. Higher layers (intake claim,
+ * task graph dispatcher, evidence recorder) glue the pieces together.
+ *
+ * Job input:
+ *   { jobId, taskId, project, workspaceRef, command, args?,
+ *     timeoutSeconds, envPolicy, allowedPaths, network }
+ *
+ * Job output:
+ *   { jobId, taskId, status, exitCode, stdoutPath, stderrPath,
+ *     durationMs, artifacts, traceId, spanId }
+ *
+ * `envPolicy: 'restricted'` strips the env down to PATH, HOME, USER,
+ * TZ, LANG plus an explicit allowlist. Path policy is enforced by
+ * resolving every entry in allowedPaths and refusing to start when
+ * the resolved workspaceRef sits outside that allowlist.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { emitTraceEvent, newTraceId, newSpanId } from './trace.mjs';
+
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const ARTIFACTS_SUBDIR = '.cx/runtime/worker';
+
+function artifactsDir(rootDir) {
+  return path.join(rootDir, ARTIFACTS_SUBDIR);
+}
+
+function buildRestrictedEnv(allowedKeys = []) {
+  const base = ['PATH', 'HOME', 'USER', 'TZ', 'LANG', 'LC_ALL', 'TMPDIR'];
+  const env = {};
+  for (const key of [...base, ...allowedKeys]) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
+function isInsideAllowedPaths(workspaceRef, allowedPaths) {
+  if (!allowedPaths || allowedPaths.length === 0) return true;
+  const target = path.resolve(workspaceRef);
+  return allowedPaths
+    .map((p) => path.resolve(p))
+    .some((allowed) => target === allowed || target.startsWith(`${allowed}${path.sep}`));
+}
+
+/**
+ * Run a worker job. Resolves with the result regardless of command outcome;
+ * rejects only on programmer errors (invalid job shape, path policy denial).
+ */
+export async function runJob({
+  rootDir,
+  job,
+  emitEvent = emitTraceEvent,
+  spawnFn = spawn,
+} = {}) {
+  if (!rootDir) throw new Error('runJob: rootDir is required');
+  if (!job?.jobId) throw new Error('runJob: job.jobId is required');
+  if (!job?.command) throw new Error('runJob: job.command is required');
+
+  const traceId = job.traceId || newTraceId();
+  const spanId = newSpanId();
+  const timeoutSeconds = Number(job.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS);
+  const workspaceRef = path.resolve(job.workspaceRef || rootDir);
+
+  if (!isInsideAllowedPaths(workspaceRef, job.allowedPaths)) {
+    throw new Error(`runJob: workspaceRef ${workspaceRef} is outside allowedPaths`);
+  }
+
+  const artifactsRoot = artifactsDir(rootDir);
+  if (!existsSync(artifactsRoot)) mkdirSync(artifactsRoot, { recursive: true });
+  const stdoutPath = path.join(artifactsRoot, `${job.jobId}.stdout.log`);
+  const stderrPath = path.join(artifactsRoot, `${job.jobId}.stderr.log`);
+
+  const env = job.envPolicy === 'restricted'
+    ? buildRestrictedEnv(job.allowedEnvKeys)
+    : { ...process.env };
+
+  emitEvent({
+    rootDir,
+    eventType: 'worker.started',
+    traceId,
+    spanId,
+    project: job.project,
+    taskId: job.taskId,
+    metadata: { jobId: job.jobId, command: job.command, timeoutSeconds, workspaceRef },
+  });
+
+  const started = Date.now();
+  const child = spawnFn(job.command, job.args || [], {
+    cwd: workspaceRef,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: typeof job.command === 'string' && (!job.args || job.args.length === 0),
+  });
+
+  let stdout = '';
+  let stderr = '';
+  let timedOut = false;
+  child.stdout.on('data', (d) => { stdout += d.toString(); });
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill('SIGTERM');
+    setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+  }, timeoutSeconds * 1000);
+
+  const exitCode = await new Promise((resolve) => {
+    child.once('close', (code) => resolve(code ?? -1));
+    child.once('error', () => resolve(-1));
+  });
+  clearTimeout(timer);
+
+  writeFileSync(stdoutPath, stdout, 'utf8');
+  writeFileSync(stderrPath, stderr, 'utf8');
+
+  const durationMs = Date.now() - started;
+  const status = timedOut ? 'timeout' : exitCode === 0 ? 'passed' : 'failed';
+
+  const result = {
+    jobId: job.jobId,
+    taskId: job.taskId || null,
+    project: job.project || null,
+    status,
+    exitCode,
+    stdoutPath,
+    stderrPath,
+    durationMs,
+    artifacts: [{ path: stdoutPath, kind: 'stdout' }, { path: stderrPath, kind: 'stderr' }],
+    traceId,
+    spanId,
+  };
+
+  emitEvent({
+    rootDir,
+    eventType: 'worker.completed',
+    traceId,
+    spanId,
+    project: job.project,
+    taskId: job.taskId,
+    metadata: { jobId: job.jobId, status, exitCode, durationMs, stdoutPath, stderrPath, timedOut },
+  });
+
+  return result;
+}

package/lib/worker/trace.mjs

@@ -0,0 +1,182 @@
+/**
+ * lib/worker/trace.mjs — append-only trace event log for worker + intake flow.
+ *
+ * Trace events tie an intake packet → task graph → role dispatch → worker
+ * job → evidence record together via traceId + spanId. Events land in two
+ * places concurrently:
+ *
+ *   1. `.cx/traces/<YYYY-MM-DD>.jsonl` — append-only local JSONL. Always on,
+ *      no credentials required. Tail live, archive, or replay.
+ *   2. Remote telemetry backend — fire-and-forget batched ingest when
+ *      CONSTRUCT_TELEMETRY_PUBLIC_KEY + CONSTRUCT_TELEMETRY_SECRET_KEY are
+ *      configured and CONSTRUCT_TRACE_BACKEND is `remote` (or unset).
+ *      Each unique traceId triggers one trace-create plus an event-create
+ *      per emitted event. Failures never throw — observability must not
+ *      break the caller.
+ *
+ *      Reads CONSTRUCT_TELEMETRY_PUBLIC_KEY / CONSTRUCT_TELEMETRY_SECRET_KEY /
+ *      CONSTRUCT_TELEMETRY_URL from env.
+ *
+ * Event types in current use:
+ *   intake.received        — daemon ingested a file
+ *   intake.triaged         — classifyRdIntake produced a triage block
+ *   task_graph.created     — graph derived from triage
+ *   role.dispatched        — context router selected a persona
+ *   tool.called            — agent invoked a tool
+ *   worker.started         — worker began executing a command
+ *   worker.completed       — worker finished (status: passed | failed | timeout)
+ *   evidence.recorded      — evidence appended to a task graph node
+ *   approval.requested     — high-risk action blocked on approval
+ *   approval.resolved      — approval granted or denied
+ *   memory.written         — durable memory record persisted
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+
+import { createIngestClient } from '../telemetry/ingest.mjs';
+
+const TRACE_SUBDIR = '.cx/traces';
+
+export const TRACE_EVENT_TYPES = [
+  'daemon.started',
+  'daemon.heartbeat',
+  'daemon.stopped',
+  'lifecycle.completed',
+  'intake.received',
+  'intake.triaged',
+  'task_graph.created',
+  'role.dispatched',
+  'tool.called',
+  'worker.started',
+  'worker.completed',
+  'evidence.recorded',
+  'approval.requested',
+  'approval.resolved',
+  'memory.written',
+];
+
+export function traceDir(rootDir) {
+  return path.join(rootDir, TRACE_SUBDIR);
+}
+
+function todayShard() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function newTraceId() {
+  return `trace-${randomBytes(8).toString('hex')}`;
+}
+
+export function newSpanId() {
+  return `span-${randomBytes(6).toString('hex')}`;
+}
+
+// Reused per-process. The ingest client batches; recreating it would lose
+// the queue. `available` flips false when keys aren't set, which is the
+// graceful no-op path for solo-mode users without no telemetry backend configured.
+let telemetryClient = null;
+const seenTraces = new Set();
+
+function getTelemetryClient(env = process.env) {
+  if (telemetryClient !== null) return telemetryClient;
+  const backend = (env.CONSTRUCT_TRACE_BACKEND || 'remote').toLowerCase();
+  if (backend === 'none' || backend === 'off' || backend === 'local') {
+    telemetryClient = { available: false, trace: () => {}, event: () => {} };
+    return telemetryClient;
+  }
+  telemetryClient = createIngestClient({
+    baseUrl: (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, ''),
+    publicKey: env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
+    secretKey: env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+  });
+  return telemetryClient;
+}
+
+/**
+ * Internal: reset the cached telemetry client. Test-only.
+ */
+export function _resetTelemetryClient() {
+  telemetryClient = null;
+  seenTraces.clear();
+}
+
+
+function exportToRemote(event, env) {
+  const client = getTelemetryClient(env);
+  if (!client.available) return;
+
+  // First time we see a traceId, register the trace so subsequent events
+  // attach to a known parent.
+  if (event.traceId && !seenTraces.has(event.traceId)) {
+    seenTraces.add(event.traceId);
+    try {
+      client.trace({
+        id: event.traceId,
+        name: event.eventType,
+        metadata: {
+          project: event.project || undefined,
+          role: event.role || undefined,
+          taskId: event.taskId || undefined,
+          intakeId: event.intakeId || undefined,
+        },
+        timestamp: event.createdAt,
+      });
+    } catch { /* observability must not break the caller */ }
+  }
+
+  try {
+    client.event({
+      id: event.spanId,
+      traceId: event.traceId,
+      parentObservationId: event.parentSpanId || undefined,
+      name: event.eventType,
+      metadata: event.metadata,
+      input: undefined,
+      output: undefined,
+      startTime: event.createdAt,
+    });
+  } catch { /* swallow */ }
+}
+
+export function emitTraceEvent({
+  rootDir,
+  eventType,
+  traceId,
+  spanId,
+  parentSpanId = null,
+  project = null,
+  role = null,
+  taskId = null,
+  intakeId = null,
+  metadata = {},
+  env = process.env,
+}) {
+  if (!rootDir) throw new Error('emitTraceEvent: rootDir is required');
+  if (!eventType) throw new Error('emitTraceEvent: eventType is required');
+  if (!TRACE_EVENT_TYPES.includes(eventType)) {
+    throw new Error(`emitTraceEvent: unknown eventType ${eventType}`);
+  }
+
+  const dir = traceDir(rootDir);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const event = {
+    traceId: traceId || newTraceId(),
+    spanId: spanId || newSpanId(),
+    parentSpanId,
+    eventType,
+    project,
+    role,
+    taskId,
+    intakeId,
+    metadata,
+    createdAt: new Date().toISOString(),
+  };
+  appendFileSync(path.join(dir, `${todayShard()}.jsonl`), `${JSON.stringify(event)}\n`, 'utf8');
+
+  // Fire-and-forget export to remote telemetry backend. Silent no-op when not configured.
+  exportToRemote(event, env);
+  return event;
+}