@inflexa-ai/harness 0.35.1 → 0.35.3

package/dist/execution/dbos-run-launcher.d.ts

@@ -1,7 +1,18 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import type { RunLauncher } from "./run-launcher.js";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export declare const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
 export declare function createDbosRunLauncher(): RunLauncher;

package/dist/execution/dbos-run-launcher.js

@@ -1,13 +1,38 @@
 /**
  * DBOS realization of the `RunLauncher` seam — the single production adapter,
- * shared by every embedder. Host-neutral: it references only DBOS, which the harness
- * already depends on, so it ships in the harness.
+ * shared by every embedder. Host-neutral: it references only DBOS and the OTel
+ * API, which the harness already depends on, so it ships in the harness.
+ *
+ * A launch detaches the run from the caller's trace. The DBOS workflow span
+ * takes the active context as its parent, and the caller is a chat request
+ * (or another short-lived operation) whose span ends in milliseconds while the
+ * run lasts hours. So the launch opens a root span of its own, runs
+ * `startWorkflow` under it, and joins the two traces by a span link back to
+ * the originating span plus `inflexa.run_id` on both sides. With no
+ * TracerProvider registered every call here is a no-op on the API's
+ * non-recording span.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { context, isSpanContextValid, ROOT_CONTEXT, trace } from "@opentelemetry/api";
+/** Attribute carrying the run id on the originating span and on the run's root span. */
+export const ATTR_INFLEXA_RUN_ID = "inflexa.run_id";
+const TRACER_NAME = "inflexa.harness.run-launcher";
 export function createDbosRunLauncher() {
     return {
         async launch(workflow, opts, input) {
-            await DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input);
+            const originating = trace.getSpan(context.active());
+            const links = [];
+            if (originating !== undefined && isSpanContextValid(originating.spanContext())) {
+                originating.setAttribute(ATTR_INFLEXA_RUN_ID, opts.workflowId);
+                links.push({ context: originating.spanContext() });
+            }
+            const root = trace.getTracer(TRACER_NAME).startSpan("launch run", { links, attributes: { [ATTR_INFLEXA_RUN_ID]: opts.workflowId } }, ROOT_CONTEXT);
+            try {
+                await context.with(trace.setSpan(ROOT_CONTEXT, root), () => DBOS.startWorkflow(workflow, { workflowID: opts.workflowId })(input));
+            }
+            finally {
+                root.end();
+            }
         },
     };
 }

package/dist/execution/reconcile-manifest.js

@@ -23,7 +23,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { classifyWithinRoot, computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
-import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
+import { recordArtifactReconcileDropped, recordLineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
     const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
@@ -62,7 +62,7 @@ export async function reconcileManifestWithDisk(input) {
                 logger.debug("dropping phantom entry", { path: entry.path });
                 collector.removeRecord(entry.path);
                 droppedCount++;
-                artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+                recordArtifactReconcileDropped({ agentId });
                 continue;
             }
             throw err;
@@ -75,7 +75,7 @@ export async function reconcileManifestWithDisk(input) {
             logger.debug("dropping non-file entry", { path: entry.path });
             collector.removeRecord(entry.path);
             droppedCount++;
-            artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
+            recordArtifactReconcileDropped({ agentId });
             continue;
         }
         // The registration payload reads output hashes from `entries` (this
@@ -140,14 +140,14 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, boundSite: "container-prefix" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "container-prefix" });
+            recordLineageInputDropped({ agentId, reason: "container-prefix" });
             collector.dropInput(ref);
             continue;
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "workspace-root" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "workspace-root" });
+            recordLineageInputDropped({ agentId, reason: "workspace-root" });
             collector.dropInput(ref);
             continue;
         }
@@ -159,7 +159,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         // verdict (a dangling link) falls through to the ENOENT drop below.
         if ((await classifyWithinRoot(resourceRoot, hostPath)) === "escaped") {
             logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "realpath" });
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "symlink-escape" });
+            recordLineageInputDropped({ agentId, reason: "symlink-escape" });
             collector.dropInput(ref);
             continue;
         }
@@ -173,7 +173,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
                 // consumed, and the count of those is how a reader tells a noisy
                 // hook from an artifact that genuinely vanished under the step.
                 logger.warn("dropping input not present at reconcile from lineage", { ...attestation, hostPath, dropSite: "input-enoent" });
-                lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "missing" });
+                recordLineageInputDropped({ agentId, reason: "missing" });
                 collector.dropInput(ref);
                 continue;
             }
@@ -187,7 +187,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
             logger.debug("dropping non-file input from lineage", attestation);
-            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "directory" });
+            recordLineageInputDropped({ agentId, reason: "directory" });
             collector.dropInput(ref);
             continue;
         }

package/dist/lib/metrics.d.ts

@@ -4,6 +4,24 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
-export declare const artifactReconcileDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
-export declare const lineageInputDropped: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record one manifest entry dropped at reconcile. */
+export declare function recordArtifactReconcileDropped(args: {
+    readonly agentId: string;
+}): void;
+export type LineageInputDropReason = "container-prefix" | "workspace-root" | "symlink-escape" | "missing" | "directory";
+/** Record one tracked input read dropped from lineage at reconcile. */
+export declare function recordLineageInputDropped(args: {
+    readonly agentId: string;
+    readonly reason: LineageInputDropReason;
+}): void;
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export declare function __resetReconcileMetricsForTest(): void;

package/dist/lib/metrics.js

@@ -4,16 +4,44 @@
  * Instruments:
  *   - cortex.artifact.reconcile.dropped — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped — counter for lineage input drops
+ *
+ * Both carry `agent_id` (about 15 values) and never a per-step or per-run
+ * identifier: a label with unbounded values multiplies the series count.
+ *
+ * Instruments are lazy so the record site binds to whichever `MeterProvider`
+ * is globally registered at first use. The metrics API has no late-binding
+ * proxy: a meter taken at module load, before `initOtel` runs, would stay
+ * on the no-op provider for the life of the process.
  */
 import { metrics } from "@opentelemetry/api";
-const meter = metrics.getMeter("cortex");
-export const artifactReconcileDropped = meter.createCounter("cortex.artifact.reconcile.dropped", {
-    description: "Manifest entries dropped because their on-disk file was missing at " +
-        "registration time (writes-then-deletes, renames). Tagged by agent_id, step_id.",
-});
-export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
-    description: "Tracked input reads dropped from lineage at reconcile because they are " +
-        "not content-attestable files of the analysis (directory reads, " +
-        "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
-        "agent_id, step_id, reason.",
-});
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex");
+        instruments = {
+            artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
+                description: "Manifest entries dropped because their on-disk file was missing at " +
+                    "registration time (writes-then-deletes, renames). Tagged by agent_id.",
+            }),
+            lineageInputDropped: meter.createCounter("cortex.artifact.reconcile.input_dropped", {
+                description: "Tracked input reads dropped from lineage at reconcile because they are " +
+                    "not content-attestable files of the analysis (directory reads, " +
+                    "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
+                    "agent_id, reason.",
+            }),
+        };
+    }
+    return instruments;
+}
+/** Record one manifest entry dropped at reconcile. */
+export function recordArtifactReconcileDropped(args) {
+    getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
+}
+/** Record one tracked input read dropped from lineage at reconcile. */
+export function recordLineageInputDropped(args) {
+    getInstruments().lineageInputDropped.add(1, { agent_id: args.agentId, reason: args.reason });
+}
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export function __resetReconcileMetricsForTest() {
+    instruments = undefined;
+}

package/dist/lib/otel-spans.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Span policy of the harness TracerProvider: which DBOS traces are recorded,
+ * which spans reach the exporter, and the names the exported spans carry.
+ *
+ * DBOS names a workflow span after the registered workflow and a step span
+ * after the step function, and it runs each body under its span, so every
+ * child (a step, a patched fetch, a pg query) sits under the workflow span.
+ * Three shapes of that output are noise in a trace store, and each is stopped
+ * in the process, before export, rather than in a collector downstream. The
+ * decisions live where the workflows and steps are written; this module holds
+ * the mechanism only:
+ *
+ * - A module that registers a housekeeping workflow declares it untraced with
+ *   `untracedWorkflow(name)` next to its registration. The sampler drops a
+ *   root span that carries such a name at creation, and `ParentBased`
+ *   sampling carries the decision to every child.
+ * - A replayed step re-emits its span with `cached=true`, which DBOS sets
+ *   after the span has started. A sampler cannot see that, so
+ *   `DbosSpanProcessor` drops the span at `onEnd`.
+ * - A step whose DBOS name embeds an id calls `stableSpan` as the first
+ *   statement of its body. The helper renames the active DBOS span to the
+ *   stable prefix and puts the id in an `inflexa.*` attribute. The DBOS step
+ *   name itself is untouched: DBOS compares it against the recorded name on
+ *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
+ *   would break every workflow in flight across a deploy.
+ */
+import { type Attributes, type Context } from "@opentelemetry/api";
+import { type ReadableSpan, type Sampler, type Span, type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/**
+ * Declare a registered DBOS workflow untraced: no root span for it is
+ * recorded, and no child span under it. Call it next to the
+ * `DBOS.registerWorkflow` that gives the workflow the same name.
+ */
+export declare function untracedWorkflow(name: string): void;
+/**
+ * The sampler of the harness TracerProvider. A root span named after an
+ * untraced workflow is not recorded; every other root is. A span with a parent
+ * takes the parent's decision (the standard `ParentBased` behaviour), so a DBOS
+ * step, a fetch, or a pg span under a dropped root is dropped with it, and a
+ * remote parent (an inbound `traceparent`) is honoured as usual.
+ */
+export declare function createHarnessSampler(): Sampler;
+/** The plan step id a `compose-step-seed` step carries. */
+export declare const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
+/** The provider tool-use id of a tool step. */
+export declare const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
+/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+export declare const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
+/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
+export declare const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
+/** The per-item key (a ChEMBL or NCT id) of a target-assessment fan-out step. */
+export declare const ATTR_INFLEXA_FANOUT_KEY = "inflexa.fanout_key";
+/**
+ * Rename the DBOS span of the step that is running to `name` and put its id
+ * in `attributes`. Call it as the first statement of a step body whose DBOS
+ * name embeds an id, with that DBOS name as `dbosName`.
+ *
+ * DBOS runs the body under its span, so with tracing on the active span is
+ * the step span. With tracing off DBOS opens no span, and the active span, if
+ * there is one, belongs to whoever started the workflow or the chat turn. The
+ * helper therefore renames a span only when its name is `dbosName`, and it
+ * leaves a missing or non-recording span alone.
+ */
+export declare function stableSpan(dbosName: string, name: string, attributes: Attributes): void;
+/**
+ * Sits in front of the exporting processor and forwards every span except a
+ * replayed one (`cached=true`), which it drops at `onEnd`.
+ */
+export declare class DbosSpanProcessor implements SpanProcessor {
+    private readonly next;
+    constructor(next: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnding(span: Span): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/lib/otel-spans.js

@@ -0,0 +1,123 @@
+/**
+ * Span policy of the harness TracerProvider: which DBOS traces are recorded,
+ * which spans reach the exporter, and the names the exported spans carry.
+ *
+ * DBOS names a workflow span after the registered workflow and a step span
+ * after the step function, and it runs each body under its span, so every
+ * child (a step, a patched fetch, a pg query) sits under the workflow span.
+ * Three shapes of that output are noise in a trace store, and each is stopped
+ * in the process, before export, rather than in a collector downstream. The
+ * decisions live where the workflows and steps are written; this module holds
+ * the mechanism only:
+ *
+ * - A module that registers a housekeeping workflow declares it untraced with
+ *   `untracedWorkflow(name)` next to its registration. The sampler drops a
+ *   root span that carries such a name at creation, and `ParentBased`
+ *   sampling carries the decision to every child.
+ * - A replayed step re-emits its span with `cached=true`, which DBOS sets
+ *   after the span has started. A sampler cannot see that, so
+ *   `DbosSpanProcessor` drops the span at `onEnd`.
+ * - A step whose DBOS name embeds an id calls `stableSpan` as the first
+ *   statement of its body. The helper renames the active DBOS span to the
+ *   stable prefix and puts the id in an `inflexa.*` attribute. The DBOS step
+ *   name itself is untouched: DBOS compares it against the recorded name on
+ *   replay and throws `DBOSUnexpectedStepError` on a mismatch, so a rename
+ *   would break every workflow in flight across a deploy.
+ */
+import { trace } from "@opentelemetry/api";
+import { ParentBasedSampler, SamplingDecision, } from "@opentelemetry/sdk-trace-base";
+/**
+ * Names of the DBOS workflows whose traces are not recorded. A registering
+ * module adds its own name at registration, which runs at boot inside
+ * `assembleCoreRuntime`, before `DBOS.launch` starts the first workflow. The
+ * sampler reads the set on every root span, so the set is complete before it
+ * is consulted, and a name added later applies from the next root span on.
+ */
+const untracedWorkflowNames = new Set();
+/**
+ * Declare a registered DBOS workflow untraced: no root span for it is
+ * recorded, and no child span under it. Call it next to the
+ * `DBOS.registerWorkflow` that gives the workflow the same name.
+ */
+export function untracedWorkflow(name) {
+    untracedWorkflowNames.add(name);
+}
+/** Root decision only: `NOT_RECORD` for an untraced workflow, `RECORD_AND_SAMPLED` for every other root. */
+class UntracedWorkflowRootSampler {
+    shouldSample(_context, _traceId, spanName) {
+        return {
+            decision: untracedWorkflowNames.has(spanName) ? SamplingDecision.NOT_RECORD : SamplingDecision.RECORD_AND_SAMPLED,
+        };
+    }
+    toString() {
+        return "UntracedWorkflowRootSampler";
+    }
+}
+/**
+ * The sampler of the harness TracerProvider. A root span named after an
+ * untraced workflow is not recorded; every other root is. A span with a parent
+ * takes the parent's decision (the standard `ParentBased` behaviour), so a DBOS
+ * step, a fetch, or a pg span under a dropped root is dropped with it, and a
+ * remote parent (an inbound `traceparent`) is honoured as usual.
+ */
+export function createHarnessSampler() {
+    return new ParentBasedSampler({ root: new UntracedWorkflowRootSampler() });
+}
+/** The plan step id a `compose-step-seed` step carries. */
+export const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
+/** The provider tool-use id of a tool step. */
+export const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
+/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+export const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
+/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
+export const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
+/** The per-item key (a ChEMBL or NCT id) of a target-assessment fan-out step. */
+export const ATTR_INFLEXA_FANOUT_KEY = "inflexa.fanout_key";
+/**
+ * Rename the DBOS span of the step that is running to `name` and put its id
+ * in `attributes`. Call it as the first statement of a step body whose DBOS
+ * name embeds an id, with that DBOS name as `dbosName`.
+ *
+ * DBOS runs the body under its span, so with tracing on the active span is
+ * the step span. With tracing off DBOS opens no span, and the active span, if
+ * there is one, belongs to whoever started the workflow or the chat turn. The
+ * helper therefore renames a span only when its name is `dbosName`, and it
+ * leaves a missing or non-recording span alone.
+ */
+export function stableSpan(dbosName, name, attributes) {
+    const span = trace.getActiveSpan();
+    if (span === undefined || !span.isRecording())
+        return;
+    // The API `Span` has no name accessor; the SDK span the provider hands out does.
+    if (span.name !== dbosName)
+        return;
+    span.updateName(name);
+    span.setAttributes(attributes);
+}
+/**
+ * Sits in front of the exporting processor and forwards every span except a
+ * replayed one (`cached=true`), which it drops at `onEnd`.
+ */
+export class DbosSpanProcessor {
+    next;
+    constructor(next) {
+        this.next = next;
+    }
+    onStart(span, parentContext) {
+        this.next.onStart(span, parentContext);
+    }
+    onEnding(span) {
+        this.next.onEnding?.(span);
+    }
+    onEnd(span) {
+        if (span.attributes.cached === true)
+            return;
+        this.next.onEnd(span);
+    }
+    forceFlush() {
+        return this.next.forceFlush();
+    }
+    shutdown() {
+        return this.next.shutdown();
+    }
+}

package/dist/lib/otel.d.ts

@@ -1,14 +1,27 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * Exported as `initOtel()` and called explicitly from the host's boot sequence
+ * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set.
+ *         is set. The provider carries the span policy of otel-spans.ts: the
+ *         root span of a workflow declared with `untracedWorkflow` is not
+ *         recorded (and its children with it), a replayed `cached=true` span
+ *         is dropped before export, and a step body that calls `stableSpan`
+ *         is exported under a stable name with its id in an `inflexa.*`
+ *         attribute.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
+ *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
+ *           the environment wins on a conflict, so a deployment can set
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,
@@ -16,16 +29,45 @@
  *        not currently wired.
  */
 import type { Logger } from "./logger.js";
+/** The SDK's own default when neither the host nor the environment says otherwise. */
+export declare const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60000;
+export interface InitOtelOptions {
+    /** Diagnostics sink; omitted falls back to no-op. */
+    readonly logger?: Logger;
+    /** `service.name` when `OTEL_SERVICE_NAME` is unset. Default `cortex`. */
+    readonly serviceName?: string;
+    /** `service.version` — the host's package version. Omitted leaves the attribute unset. */
+    readonly serviceVersion?: string;
+}
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export declare function metricsExportDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export declare function metricExportIntervalMs(env?: NodeJS.ProcessEnv): number;
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export declare function initOtel(injected?: Logger): void;
+export declare function initOtel(options?: InitOtelOptions): void;
 /**
  * Flush and shut down the OTel exporters. Called by the graceful-shutdown
  * sequence so in-flight batch spans/metrics make it to the collector
  * before the process exits. Never throws.
  */
 export declare function shutdownOtel(): Promise<void>;
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export declare function __resetOtelForTest(): Promise<void>;
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export declare function __otelMeterProviderRegisteredForTest(): boolean;

package/dist/lib/otel.js

@@ -1,47 +1,95 @@
 /**
  * OpenTelemetry SDK initialization — traces + metrics.
  *
- * Exported as `initOtel()` and called explicitly from index.ts to prevent
- * the bundler from tree-shaking it (side-effect-only imports get dropped).
+ * Exported as `initOtel()` and called explicitly from the host's boot sequence
+ * so the bundler cannot tree-shake it (side-effect-only imports get dropped).
  *
  * Traces: NodeTracerProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *         is set.
+ *         is set. The provider carries the span policy of otel-spans.ts: the
+ *         root span of a workflow declared with `untracedWorkflow` is not
+ *         recorded (and its children with it), a replayed `cached=true` span
+ *         is dropped before export, and a step body that calls `stableSpan`
+ *         is exported under a stable name with its id in an `inflexa.*`
+ *         attribute.
  *
- * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT
- *          is set. Custom Cortex metrics are defined in metrics.ts.
+ * Metrics: MeterProvider exports to OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is
+ *          set and OTEL_METRICS_EXPORTER is not `none`. The export interval is
+ *          OTEL_METRIC_EXPORT_INTERVAL (ms), default 60 s. Custom Cortex
+ *          metrics are defined in metrics.ts.
+ *
+ * Resource: the host's `serviceName` / `serviceVersion` merged with the SDK
+ *           env detector (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`);
+ *           the environment wins on a conflict, so a deployment can set
+ *           `deployment.environment.name` or override the service name without
+ *           a code change. Traces and metrics share the one resource.
  *
  * Note: OTEL's instrumentation-http patches node:http but does not cover
  *        Hono's request handling or Node 22's undici-based globalThis.fetch,
  *        so inbound/outbound trace-context propagation across those paths is
  *        not currently wired.
  */
-import { propagation, metrics, trace } from "@opentelemetry/api";
+import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
+import { createHarnessSampler, DbosSpanProcessor } from "./otel-spans.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { detectResources, envDetector, resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+/** The SDK's own default when neither the host nor the environment says otherwise. */
+export const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60_000;
 let initialized = false;
 let registeredTracerProvider;
 let registeredMeterProvider;
+/**
+ * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
+ * stays set for traces. Any other value (including unset) keeps the OTLP
+ * exporter, the only one the harness ships.
+ */
+export function metricsExportDisabled(env = process.env) {
+    return env.OTEL_METRICS_EXPORTER === "none";
+}
+/**
+ * Export interval from `OTEL_METRIC_EXPORT_INTERVAL` (milliseconds). An unset,
+ * non-numeric, or non-positive value falls back to the 60 s default.
+ */
+export function metricExportIntervalMs(env = process.env) {
+    const raw = env.OTEL_METRIC_EXPORT_INTERVAL;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+    return Math.floor(parsed);
+}
+function buildResource(options) {
+    const manual = {
+        [ATTR_SERVICE_NAME]: options.serviceName ?? "cortex",
+    };
+    if (options.serviceVersion)
+        manual[ATTR_SERVICE_VERSION] = options.serviceVersion;
+    // `merge` gives precedence to the argument: the environment overrides the
+    // host's values, which is the OTel SDK convention for env configuration.
+    return resourceFromAttributes(manual).merge(detectResources({ detectors: [envDetector] }));
+}
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export function initOtel(injected) {
+export function initOtel(options = {}) {
     if (initialized)
         return;
     initialized = true;
-    const logger = (injected ?? createNoopLogger()).named("otel");
+    const logger = (options.logger ?? createNoopLogger()).named("otel");
     // ── W3C Trace Context propagation ──────────────────────────────────
     propagation.setGlobalPropagator(new W3CTraceContextPropagator());
     const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    const resource = buildResource(options);
     // ── Traces ─────────────────────────────────────────────────────────
     // Always register a TracerProvider so trace.getTracer() returns real spans
     // with unique IDs. Without this, the OtelBridge gets no-op spans (all zeros)
@@ -50,14 +98,11 @@ export function initOtel(injected) {
         const spanProcessors = [];
         if (endpoint) {
             const base = endpoint.replace(/\/+$/, "");
-            spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` })));
+            spanProcessors.push(new DbosSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` }))));
         }
-        const serviceName = process.env.OTEL_SERVICE_NAME || "cortex";
-        const resource = resourceFromAttributes({
-            [ATTR_SERVICE_NAME]: serviceName,
-        });
         const tracerProvider = new NodeTracerProvider({
             resource,
+            sampler: createHarnessSampler(),
             spanProcessors,
         });
         tracerProvider.register();
@@ -71,20 +116,29 @@ export function initOtel(injected) {
         // `initTelemetry: () => {}` — its TUI owns stdout, so the banner corrupted
         // the screen and the whole of the harness's traces + metrics were switched
         // off to avoid it. At debug through the injected seam it costs nothing.
-        logger.debug("TracerProvider registered", { spanId: ctx.spanId, noop: isNoop, endpoint: endpoint ?? null, processors: spanProcessors.length });
+        logger.debug("TracerProvider registered", {
+            spanId: ctx.spanId,
+            noop: isNoop,
+            endpoint: endpoint ?? null,
+            processors: spanProcessors.length,
+            resource: resource.attributes,
+        });
         testSpan.end();
     }
     // ── Metrics ────────────────────────────────────────────────────────
-    if (endpoint) {
+    // With no MeterProvider registered the API's global no-op provider serves
+    // every instrument, so the record sites stay valid when export is off.
+    if (endpoint && !metricsExportDisabled()) {
         const base = endpoint.replace(/\/+$/, "");
         const metricExporter = new OTLPMetricExporter({
             url: `${base}/v1/metrics`,
         });
         const meterProvider = new MeterProvider({
+            resource,
             readers: [
                 new PeriodicExportingMetricReader({
                     exporter: metricExporter,
-                    exportIntervalMillis: 30_000,
+                    exportIntervalMillis: metricExportIntervalMs(),
                 }),
             ],
         });
@@ -105,3 +159,22 @@ export async function shutdownOtel() {
         tasks.push(registeredMeterProvider.shutdown());
     await Promise.allSettled(tasks);
 }
+/**
+ * Test hook: shut the providers down and unregister every global the init
+ * touched, so a test can drive `initOtel` again under a different environment.
+ * Test-only.
+ */
+export async function __resetOtelForTest() {
+    await shutdownOtel();
+    registeredTracerProvider = undefined;
+    registeredMeterProvider = undefined;
+    trace.disable();
+    metrics.disable();
+    context.disable();
+    propagation.disable();
+    initialized = false;
+}
+/** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
+export function __otelMeterProviderRegisteredForTest() {
+    return registeredMeterProvider !== undefined;
+}

package/dist/loop/run-agent.js

@@ -3,6 +3,7 @@ import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { ATTR_INFLEXA_TOOL_USE_ID, stableSpan } from "../lib/otel-spans.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { stripUnansweredToolCalls } from "../memory/tool-call-integrity.js";
@@ -70,7 +71,13 @@ export async function runAgent(agent, initial, session, opts) {
         session,
         signal,
         emit,
-        runStep: (name, fn) => runStep(`${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`, fn),
+        runStep: (name, fn) => {
+            const stepName = `${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`;
+            return runStep(stepName, () => {
+                stableSpan(stepName, `tool:${tu.toolName}:${name}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
+                return fn();
+            });
+        },
         ask,
         turnUsage,
     });
@@ -540,7 +547,11 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
         const startedAt = performance.now();
-        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding)).then((settled) => {
+        const stepName = toolStepName(tu.toolName, tu.toolCallId);
+        return runStep(stepName, () => {
+            stableSpan(stepName, `tool:${tu.toolName}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
+            return dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        }).then((settled) => {
             durations[idx] = elapsedMs(startedAt);
             const dispatched = readDispatchedStep(settled);
             results[idx] = dispatched.result;

package/dist/runtime/dbos.d.ts

@@ -12,6 +12,7 @@
  *
  * See `openspec/changes/harness-dbos-runtime`.
  */
+import { type DBOSConfig, type DLogger } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
 /**
@@ -31,18 +32,61 @@ export interface DbosConfig {
     /** Stable per-pod executor id (e.g. `process.env.HOSTNAME ?? "local-dev"`). */
     readonly executorId: string;
     /**
-     * SDK log verbosity (winston levels; the SDK's own default is `info`).
-     * Interactive embedders pass `warn` so the launch banner and migration
-     * chatter don't interleave with their own command output; the server root
-     * omits it and keeps the informative default.
+     * Least severe SDK record forwarded to the host's `Logger` (winston level
+     * names; the SDK's own default is `info`). The SDK's lines ride the
+     * harness `Logger` seam under `[dbos.sdk]`, so this threshold is applied by
+     * the bridge, not by the SDK. Interactive embedders pass `warn` so the
+     * launch banner and migration chatter stay out of their logs; the server
+     * root omits it and keeps the informative default.
      */
     readonly logLevel?: string;
+    /**
+     * Emit DBOS workflow and step spans on the globally registered
+     * TracerProvider, and run every workflow and step body under an active
+     * OTel context. Default `false`.
+     *
+     * DBOS installs nothing of its own here: with no OTLP endpoint of its own it
+     * probes the global provider and, when one is registered, emits under the
+     * instrumentation scope `dbos-tracer` through that provider's processors.
+     * A host that registers no provider (the CLI passes a no-op
+     * `initTelemetry`) must leave this off, otherwise the SDK installs its own
+     * `BasicTracerProvider` and every span is created and never exported.
+     *
+     * Attribute names follow the `dbos.*` semantic-convention layout
+     * (`otelAttributeFormat: "semconv"`).
+     *
+     * The harness TracerProvider shapes what the SDK emits (`lib/otel-spans.ts`):
+     * a workflow declared with `untracedWorkflow` is not recorded, a replayed
+     * `cached=true` span is dropped before export, and a step body that calls
+     * `stableSpan` is exported under a stable name with its id in an
+     * `inflexa.*` attribute. The step name DBOS records is unchanged.
+     *
+     * Known SDK behavior a host must plan for: a recovered workflow starts a
+     * new root trace, with no link to the trace of the original execution.
+     */
+    readonly tracingEnabled?: boolean;
 }
 /** DBOS lifecycle facts a host's readiness probe reports on. */
 export interface DbosState {
     launched: boolean;
     recoveryStarted: boolean;
 }
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export declare function dbosSdkLogger(logger: Logger, logLevel: string | undefined): DLogger;
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export declare function dbosSdkConfig(config: DbosConfig, logger: Logger): DBOSConfig;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.

package/dist/runtime/dbos.js

@@ -45,6 +45,76 @@ function systemDatabaseUrl(config) {
     const database = encodeURIComponent(config.dbName);
     return `postgresql://${user}:${password}@${host}:${port}/${database}?sslmode=${dbosSslMode(config.dbSslMode)}`;
 }
+/** Winston severity ranks, ascending verbosity — the scale `DbosConfig.logLevel` names. */
+const SDK_LOG_LEVEL_RANK = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    http: 3,
+    verbose: 4,
+    debug: 5,
+    silly: 6,
+};
+const SDK_DEFAULT_LOG_LEVEL = "info";
+/**
+ * Bridge the SDK's internal logger onto the harness `Logger` seam, so the
+ * SDK's own lines (`Recovering N workflows…`, migration chatter) land in the
+ * host's sink instead of on the process console. The SDK does not filter by
+ * `logLevel` before it delegates to a custom logger, so the threshold is
+ * applied here. Records arrive as strings; an `Error` arrives as its message
+ * with the stack (and cause chain) in `metadata.stack`; inside a workflow or
+ * step body `metadata.span.attributes` carries the operation context, which
+ * rides as fields.
+ */
+export function dbosSdkLogger(logger, logLevel) {
+    const sink = logger.named("sdk");
+    const threshold = SDK_LOG_LEVEL_RANK[logLevel ?? SDK_DEFAULT_LOG_LEVEL] ?? SDK_LOG_LEVEL_RANK[SDK_DEFAULT_LOG_LEVEL];
+    const passes = (level) => SDK_LOG_LEVEL_RANK[level] <= threshold;
+    const fields = (metadata) => {
+        const attributes = metadata?.span?.attributes;
+        const stack = metadata?.stack;
+        if (attributes === undefined && stack === undefined)
+            return undefined;
+        return { ...attributes, ...(stack !== undefined ? { stack } : {}) };
+    };
+    const message = (entry) => (typeof entry === "string" ? entry : String(entry));
+    return {
+        debug: (entry, metadata) => {
+            if (passes("debug"))
+                sink.debug(message(entry), fields(metadata));
+        },
+        info: (entry, metadata) => {
+            if (passes("info"))
+                sink.info(message(entry), fields(metadata));
+        },
+        warn: (entry, metadata) => {
+            if (passes("warn"))
+                sink.warn(message(entry), fields(metadata));
+        },
+        error: (entry, metadata) => {
+            if (passes("error"))
+                sink.error(message(entry), fields(metadata));
+        },
+    };
+}
+/**
+ * The SDK config `launchDbos` sets. Pure over `DbosConfig`, so a test can
+ * assert on the mapping without a launch.
+ */
+export function dbosSdkConfig(config, logger) {
+    return {
+        name: config.appName,
+        systemDatabaseUrl: systemDatabaseUrl(config),
+        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
+        executorID: config.executorId,
+        applicationVersion: config.applicationVersion,
+        adminPort: parseInt(config.adminPort, 10),
+        logLevel: config.logLevel,
+        logger: dbosSdkLogger(logger, config.logLevel),
+        tracingEnabled: config.tracingEnabled ?? false,
+        otelAttributeFormat: "semconv",
+    };
+}
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
@@ -57,25 +127,17 @@ export async function launchDbos({ config, logger: injected }) {
     if (state.launched)
         return;
     const logger = injected.named("dbos");
-    const executorID = config.executorId;
-    const adminPort = parseInt(config.adminPort, 10);
-    DBOS.setConfig({
-        name: config.appName,
-        systemDatabaseUrl: systemDatabaseUrl(config),
-        systemDatabasePoolSize: DBOS_SYSTEM_POOL_SIZE,
-        executorID,
-        applicationVersion: config.applicationVersion,
-        adminPort,
-        logLevel: config.logLevel,
-    });
+    const sdkConfig = dbosSdkConfig(config, logger);
+    DBOS.setConfig(sdkConfig);
     const start = performance.now();
     await DBOS.launch();
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {
-        executorID,
+        executorID: sdkConfig.executorID,
         applicationVersion: config.applicationVersion,
-        adminPort,
+        adminPort: sdkConfig.adminPort,
+        tracingEnabled: sdkConfig.tracingEnabled,
         durationMs: Math.round(performance.now() - start),
     });
 }

package/dist/sandbox/await-exec.js

@@ -55,6 +55,7 @@
  * varied between replays would desynchronise the recorded function-ID sequence.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { ATTR_INFLEXA_ATTEMPT, ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
 import { digestBody } from "./digest.js";
 import { signCallback, verifyCallback } from "./hmac.js";
 import { createEscalationPolicy, probeLiveness, syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
@@ -182,9 +183,11 @@ export async function awaitExecCallback(ref, execId, emit, deadlineMs, options =
     /** Ask the sandbox directly. Returns null when the exec has not finished. */
     const pull = async () => {
         pullAttempt += 1;
-        const pulled = await runStep(() => pullExecResult(fetchImpl, ref, execId), {
-            name: `sandbox.pull-exec-result.${execId}.${pullAttempt}`,
-        });
+        const pullStepName = `sandbox.pull-exec-result.${execId}.${pullAttempt}`;
+        const pulled = await runStep(() => {
+            stableSpan(pullStepName, "sandbox.pull-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pullAttempt });
+            return pullExecResult(fetchImpl, ref, execId);
+        }, { name: pullStepName });
         if (pulled.kind !== "completed")
             return null;
         // Identical treatment to a pushed completion: the bytes were signed by
@@ -341,9 +344,11 @@ export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {})
     let probeAttempt = 0;
     while (true) {
         pollAttempt += 1;
-        const polled = await runStep(() => pollExecOnce(fetchImpl, ref, execId, cursor), {
-            name: `sandbox.poll-exec-result.${execId}.${pollAttempt}`,
-        });
+        const pollStepName = `sandbox.poll-exec-result.${execId}.${pollAttempt}`;
+        const polled = await runStep(() => {
+            stableSpan(pollStepName, "sandbox.poll-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pollAttempt });
+            return pollExecOnce(fetchImpl, ref, execId, cursor);
+        }, { name: pollStepName });
         if (polled.kind === "ok") {
             // Identical treatment to a pushed completion: the bytes were signed by
             // the same secret, so a forgery is as fatal here as it is there.
@@ -385,9 +390,11 @@ export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {})
         }
         if (isAlive && escalation.onPoll(polled.kind === "ok" ? "ok" : "unavailable")) {
             probeAttempt += 1;
-            const verdict = await runStep(() => probeLiveness(isAlive, ref), {
-                name: `sandbox.probe-liveness.${execId}.${probeAttempt}`,
-            });
+            const probeStepName = `sandbox.probe-liveness.${execId}.${probeAttempt}`;
+            const verdict = await runStep(() => {
+                stableSpan(probeStepName, "sandbox.probe-liveness", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: probeAttempt });
+                return probeLiveness(isAlive, ref);
+            }, { name: probeStepName });
             // Only an observably dead machine fails the exec — the result lives
             // in that machine and nowhere else, so it is unrecoverable and the
             // synthetic failure races nothing. `alive` (live-but-slow exec,

package/dist/sandbox/notification-sweep.js

@@ -18,7 +18,9 @@
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 const SWEEP_CRON = "0 */5 * * * *";
+const SWEEP_WORKFLOW = "dbos-notifications-sweep";
 const DELETE_BATCH_LIMIT = 10_000;
 export async function sweepStaleNotifications(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("notification-sweep");
@@ -68,9 +70,10 @@ export function registerNotificationSweep(deps) {
     // a workflow registration. Register, then schedule the same callable.
     const sweep = DBOS.registerWorkflow(async () => {
         await sweepStaleNotifications({ deleteStale, logger: deps.logger });
-    }, { name: "dbos-notifications-sweep" });
+    }, { name: SWEEP_WORKFLOW });
+    untracedWorkflow(SWEEP_WORKFLOW);
     DBOS.registerScheduled(sweep, {
-        name: "dbos-notifications-sweep",
+        name: SWEEP_WORKFLOW,
         crontab: SWEEP_CRON,
     });
 }

package/dist/sandbox/reaper.js

@@ -21,9 +21,11 @@
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { reconcileReapedSandbox } from "../state/active-sandboxes.js";
 const REAPER_CRON = "0 */5 * * * *";
+const REAPER_WORKFLOW = "sandbox-reaper";
 const DEFAULT_GRACE_MS = 10 * 60_000;
 /**
  * Workflow statuses that mean "still owns its sandbox — never reap". Must
@@ -152,9 +154,10 @@ export function registerSandboxReaper(deps) {
             graceMs: deps.graceMs,
             logger: deps.logger,
         }), { name: "sandbox-reaper-sweep" });
-    }, { name: "sandbox-reaper" });
+    }, { name: REAPER_WORKFLOW });
+    untracedWorkflow(REAPER_WORKFLOW);
     DBOS.registerScheduled(reaper, {
-        name: "sandbox-reaper",
+        name: REAPER_WORKFLOW,
         crontab: REAPER_CRON,
     });
 }

package/dist/sandbox/submit-exec.js

@@ -17,6 +17,7 @@
  * untouched.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { ATTR_INFLEXA_EXEC_ID, stableSpan } from "../lib/otel-spans.js";
 import { EXEC_STREAM_BYTE_CAP } from "../tools/workspace/result-bounds.js";
 import { signCallback } from "./hmac.js";
 const SUBMIT_HTTP_TIMEOUT_MS = 30_000;
@@ -71,7 +72,9 @@ export async function submitExec(ref, body, deps = {}) {
         stdoutByteCap: body.stdoutByteCap ?? deps.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP,
         stderrByteCap: body.stderrByteCap ?? deps.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP,
     };
-    await runStep(() => postExec(fetchImpl, ref, capped), {
-        name: `sandbox.submit-exec.${body.execId}`,
-    });
+    const stepName = `sandbox.submit-exec.${body.execId}`;
+    await runStep(() => {
+        stableSpan(stepName, "sandbox.submit-exec", { [ATTR_INFLEXA_EXEC_ID]: body.execId });
+        return postExec(fetchImpl, ref, capped);
+    }, { name: stepName });
 }

package/dist/sandbox/watchdog.js

@@ -21,11 +21,14 @@
 import { createHash } from "node:crypto";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { untracedWorkflow } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { workflowIdFromExec } from "./exec-id.js";
 import { syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
 export const SHARD_COUNT = 8;
 const WATCHDOG_CRON = "*/60 * * * * *";
+const WATCHDOG_PARENT_WORKFLOW = "sandbox-watchdog-parent";
+const WATCHDOG_SHARD_WORKFLOW = "sandbox-watchdog-shard";
 /** Stable hash → shard mapping, exported for tests. */
 export function shardIndex(sandboxId, shardCount = SHARD_COUNT) {
     const digest = createHash("sha1").update(sandboxId).digest();
@@ -131,7 +134,8 @@ export function registerWatchdog(deps) {
             },
             logger: deps.logger,
         });
-    }, { name: "sandbox-watchdog-shard" });
+    }, { name: WATCHDOG_SHARD_WORKFLOW });
+    untracedWorkflow(WATCHDOG_SHARD_WORKFLOW);
     // The scheduled target must itself be a registered workflow — DBOS's
     // scheduler loop skips (and errors on) any `@scheduled` function that lacks
     // a workflow registration. Register, then schedule the same callable.
@@ -148,9 +152,10 @@ export function registerWatchdog(deps) {
                 continue;
             await DBOS.startWorkflow(childCheckShard)(shard);
         }
-    }, { name: "sandbox-watchdog-parent" });
+    }, { name: WATCHDOG_PARENT_WORKFLOW });
+    untracedWorkflow(WATCHDOG_PARENT_WORKFLOW);
     DBOS.registerScheduled(watchdogParent, {
-        name: "sandbox-watchdog-parent",
+        name: WATCHDOG_PARENT_WORKFLOW,
         crontab: WATCHDOG_CRON,
     });
 }

package/dist/workflows/execute-analysis.js

@@ -63,6 +63,7 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { ATTR_INFLEXA_STEP_ID, stableSpan } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { RunDedupCollisionError, countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
@@ -770,7 +771,11 @@ async function runSchedulerLoop(args) {
             // `completed`, so this is the first (and only) moment their results
             // can be named. Checkpointed so a replay re-dispatches the child
             // with a byte-identical prompt instead of re-reading the DB/disk.
-            const prompt = await DBOS.runStep(() => composeStepSeed({ input, stepId, runId, deps }), { name: `compose-step-seed:${stepId}` });
+            const seedStepName = `compose-step-seed:${stepId}`;
+            const prompt = await DBOS.runStep(() => {
+                stableSpan(seedStepName, "compose-step-seed", { [ATTR_INFLEXA_STEP_ID]: stepId });
+                return composeStepSeed({ input, stepId, runId, deps });
+            }, { name: seedStepName });
             const baseChildInput = buildChildInput({
                 input,
                 stepId,

package/dist/workflows/execute-target-assessment.js

@@ -37,6 +37,7 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { forSubAgent } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { ATTR_INFLEXA_FANOUT_KEY, stableSpan } from "../lib/otel-spans.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { durableStep } from "../loop/run-step.js";
 import { createPubMedTool } from "../tools/bio/pubmed.js";
@@ -278,9 +279,14 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             }))
             : [];
         async function runFanoutBlock(items, stepKindForName, keyOf, fn) {
-            return Promise.all(items.map((item) => DBOS.runStep(() => fn(item), {
-                name: `ta-fanout:${stepKindForName}:${keyOf(item)}`,
-            }).catch((err) => wrapCollectorThrow(err))));
+            return Promise.all(items.map((item) => {
+                const key = keyOf(item);
+                const stepName = `ta-fanout:${stepKindForName}:${key}`;
+                return DBOS.runStep(() => {
+                    stableSpan(stepName, `ta-fanout:${stepKindForName}`, { [ATTR_INFLEXA_FANOUT_KEY]: key });
+                    return fn(item);
+                }, { name: stepName }).catch((err) => wrapCollectorThrow(err));
+            }));
         }
         const [perModulatorFaersResults, perTrialAesResults, perModulatorPolypharmResults, perClassDrugAesResults] = await Promise.all([
             runFanoutBlock(triageShortlist, "modulator-faers", (item) => item.moleculeChemblId, faersForOneModulator),

package/dist/workflows/metrics.d.ts

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,15 +18,5 @@
 export declare function recordCancelledChild(args: {
     readonly cause: "fail_fast" | "budget_exceeded" | "external_cancel";
 }): void;
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export declare function recordStreamWrite(args: {
-    readonly bytes: number;
-    readonly kind: string;
-}): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export declare function __resetWorkflowMetricsForTest(): void;

package/dist/workflows/metrics.js

@@ -1,15 +1,10 @@
 /**
- * Workflow-side OTel metrics → Middleware.io.
+ * Workflow-side OTel metrics.
  *
- * Two signals so 3-hour runs and pause-resume cascades are observable:
  *   - cortex.workflow.parent.cancelled_children — counter, incremented once
  *     per child the fail-fast or pause cascade reaps. A baseline near 0
  *     means runs land cleanly; a spike means siblings keep colliding with
  *     a single failing step.
- *   - cortex.workflow.stream.bytes               — counter, incremented by
- *     the byte count of every UI part written onto the DBOS stream. The
- *     leading indicator for 3-hour stream growth is monotonic — a runaway
- *     emitter shows up as an unbounded slope.
  *
  * Instruments are lazy so the workflow body binds to whichever
  * `MeterProvider` is globally registered at startup.
@@ -23,10 +18,6 @@ function getInstruments() {
             cancelledChildren: meter.createCounter("cortex.workflow.parent.cancelled_children", {
                 description: "Children cancelled by the parent's fail-fast or pause cascade",
             }),
-            streamBytes: meter.createCounter("cortex.workflow.stream.bytes", {
-                description: "Bytes written to the parent's DBOS UI-parts stream — proxy for " + "3-hour stream growth",
-                unit: "By",
-            }),
         };
     }
     return instruments;
@@ -40,15 +31,6 @@ function getInstruments() {
 export function recordCancelledChild(args) {
     getInstruments().cancelledChildren.add(1, { cause: args.cause });
 }
-/**
- * Record one UI-part write. `bytes` is the serialised JSON size of the
- * part as it lands on the stream; `kind` is the part `type` for
- * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
- * so a single emitter records once per part.
- */
-export function recordStreamWrite(args) {
-    getInstruments().streamBytes.add(args.bytes, { kind: args.kind });
-}
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export function __resetWorkflowMetricsForTest() {
     instruments = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.35.1",
+    "version": "0.35.3",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",