@codemation/host 0.5.1 → 0.7.0

package/prisma-generated/prisma-sqlite-client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "prisma-client-b708fc5a44cdec791f8903ca7af0faa8ee36ab36c4e12693b2e42c5a474e6685",
+  "name": "prisma-client-f1f592cca96cc07ff4c49ca6848788c0583fceb20133a8099c5c0d76247b55cc",
   "main": "index.js",
   "types": "index.d.ts",
   "browser": "default.js",

package/prisma-generated/prisma-sqlite-client/schema.prisma

@@ -18,6 +18,7 @@ model Run {
   executionOptionsJson String? @map("execution_options_json")
   controlJson          String? @map("control_json")
   workflowSnapshotJson String? @map("workflow_snapshot_json")
+  workflowSnapshotId   String? @map("workflow_snapshot_id")
   policySnapshotJson   String? @map("policy_snapshot_json")
   engineCountersJson   String? @map("engine_counters_json")
   mutableStateJson     String? @map("mutable_state_json")
@@ -33,10 +34,12 @@ model Run {
   slotProjection     RunSlotProjection?
   testSuiteRun       TestSuiteRun?       @relation(fields: [testSuiteRunId], references: [id])
   testAssertions     TestAssertion[]
+  workflowSnapshot   WorkflowSnapshot?   @relation(fields: [workflowSnapshotId], references: [id])
 
   @@index([workflowId, startedAt])
   @@index([workflowId, status, finishedAt])
   @@index([testSuiteRunId, testCaseIndex])
+  @@index([workflowSnapshotId])
 }
 
 model RunWorkItem {
@@ -107,6 +110,7 @@ model ExecutionInstance {
   iterationId          String?  @map("iteration_id")
   itemIndex            Int?     @map("item_index")
   parentInvocationId   String?  @map("parent_invocation_id")
+  childRunId           String?  @map("child_run_id")
 
   run Run @relation(fields: [runId], references: [runId], onDelete: Cascade)
 
@@ -259,6 +263,20 @@ model TelemetrySpan {
   @@index([retentionExpiresAt])
 }
 
+model WorkflowSnapshot {
+  id           String @id
+  workflowId   String @map("workflow_id")
+  /// SHA-256 hex digest of snapshotJson — dedup key: same workflow content → one row.
+  snapshotHash String @map("snapshot_hash")
+  snapshotJson String @map("snapshot_json")
+  createdAt    String @map("created_at")
+
+  runs Run[]
+
+  @@unique([workflowId, snapshotHash])
+  @@index([workflowId, snapshotHash])
+}
+
 model TelemetryArtifact {
   artifactId         String   @id @map("artifact_id")
   traceId            String   @map("trace_id")
@@ -273,6 +291,7 @@ model TelemetryArtifact {
   previewJson        String?  @map("preview_json")
   payloadText        String?  @map("payload_text")
   payloadJson        String?  @map("payload_json")
+  payloadStorageKey  String?  @map("payload_storage_key")
   bytes              Int?
   truncated          Boolean?
   createdAt          String   @map("created_at")
@@ -469,3 +488,23 @@ model VerificationToken {
   @@unique([identifier, token])
   @@map("codemation_auth_verification_token")
 }
+
+model WorkflowAuditLog {
+  id             String   @id @map("id")
+  occurredAt     DateTime @map("occurred_at")
+  actorUserId    String   @map("actor_user_id")
+  actorSessionId String?  @map("actor_session_id")
+  action         String   @map("action")
+  resourceType   String   @map("resource_type")
+  resourceId     String   @map("resource_id")
+  outcome        String   @map("outcome")
+  errorCode      String?  @map("error_code")
+  correlationId  String?  @map("correlation_id")
+  workflowId     String   @map("workflow_id")
+  runId          String?  @map("run_id")
+  nodeId         String?  @map("node_id")
+
+  @@index([actorUserId, occurredAt])
+  @@index([workflowId, occurredAt])
+  @@map("workflow_audit_log")
+}

package/scripts/check-collections.mjs

@@ -0,0 +1,18 @@
+import { AppConfigLoader } from "../src/presentation/server/AppConfigLoader.ts";
+
+const loader = new AppConfigLoader();
+const result = await loader.load({
+  consumerRoot: "/home/cblokland/projects/made/codemation/apps/test-dev",
+  repoRoot: "/home/cblokland/projects/made/codemation",
+  env: process.env,
+});
+console.log("collections.length:", result.appConfig.collections.length);
+console.log(
+  "collection names:",
+  result.appConfig.collections.map((c) => c.name),
+);
+const first = result.appConfig.collections[0];
+console.log(
+  "first collection:",
+  first ? { name: first.name, fields: Object.keys(first.fields ?? {}), indexes: first.indexes } : "no collections",
+);

package/scripts/generate-prisma-clients.mjs

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { execaSync } from "execa";
 import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -15,7 +16,7 @@ class PrismaClientGenerator {
     this.reexecUnderSupportedNodeWhenNeeded();
     for (const provider of this.providers) {
       const result = spawnSync(process.execPath, [this.prismaCliEntrypoint, "generate"], {
-        cwd: import.meta.dirname.replace(/\/scripts$/, ""),
+        cwd: path.dirname(import.meta.dirname),
         env: {
           ...process.env,
           CODEMATION_PRISMA_PROVIDER: provider,
@@ -41,7 +42,7 @@ class PrismaClientGenerator {
       );
     }
     const result = spawnSync(supportedNodeBinary, [new URL(import.meta.url).pathname], {
-      cwd: import.meta.dirname.replace(/\/scripts$/, ""),
+      cwd: path.dirname(import.meta.dirname),
       env: {
         ...process.env,
         [this.reexecMarker]: "1",
@@ -80,16 +81,24 @@ class PrismaClientGenerator {
     if (npmExecPath) {
       return realpathSync(npmExecPath);
     }
-    const result = spawnSync("bash", ["-lc", 'realpath "$(command -v pnpm)"'], {
-      env: process.env,
-      encoding: "utf8",
-      shell: false,
-    });
-    if (result.status !== 0) {
-      return undefined;
+    try {
+      // execa resolves bare command names against the OS-appropriate PATH (handles `.cmd` / `.exe`
+      // shims on Windows automatically), so this works on every platform we run dev on.
+      const result = execaSync("pnpm", ["root", "-g"], { reject: false });
+      if (result.exitCode === 0 && typeof result.stdout === "string" && result.stdout.trim().length > 0) {
+        // pnpm root -g prints "<pnpm-store>/global/5/node_modules"; the pnpm binary lives one level
+        // up under the install root. We only need *a* directory close to the pnpm binary so the
+        // sibling-`node` lookup below can probe candidate paths.
+        const globalRoot = result.stdout.trim();
+        const candidate = path.resolve(globalRoot, "..", "..", "pnpm");
+        if (existsSync(candidate)) {
+          return realpathSync(candidate);
+        }
+      }
+    } catch {
+      // fall through
     }
-    const pnpmPath = result.stdout.trim();
-    return pnpmPath.length > 0 ? pnpmPath : undefined;
+    return undefined;
   }
 
   static isSupportedNode(version) {

package/src/application/WorkflowAuditLogPruneScheduler.ts

@@ -0,0 +1,96 @@
+import type { Clock } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { Logger } from "./logging/Logger";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { ServerLoggerFactory } from "../infrastructure/logging/ServerLoggerFactory";
+import {
+  PrismaDatabaseClientToken,
+  type PrismaDatabaseClient,
+} from "../infrastructure/persistence/PrismaDatabaseClient";
+
+/**
+ * Periodically deletes WorkflowAuditLog rows older than the configured retention period.
+ *
+ * Default retention: 90 days.
+ * Override: `CODEMATION_AUDIT_WORKFLOW_RETENTION_SECONDS` in env.
+ * Disable: `CODEMATION_AUDIT_PRUNE_ENABLED=false`.
+ */
+@injectable()
+export class WorkflowAuditLogPruneScheduler {
+  static readonly defaultIntervalMs = 60 * 60 * 1_000;
+  /** 90 days in seconds (default retention). */
+  static readonly defaultRetentionSeconds = 90 * 24 * 3600;
+
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(ApplicationTokens.Clock) private readonly clock: Clock,
+    @inject(PrismaDatabaseClientToken) private readonly prisma: PrismaDatabaseClient,
+    @inject(ApplicationTokens.AppConfig) private readonly appConfig: AppConfig,
+    @inject(ServerLoggerFactory) loggerFactory: ServerLoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("codemation.auditPrune");
+  }
+
+  start(): void {
+    if (this.appConfig.env.CODEMATION_AUDIT_PRUNE_ENABLED === "false") {
+      return;
+    }
+    if (this.timer) {
+      return;
+    }
+    const intervalMs = Number(
+      this.appConfig.env.CODEMATION_AUDIT_PRUNE_INTERVAL_MS ??
+        this.appConfig.env.CODEMATION_RUN_PRUNE_INTERVAL_MS ??
+        WorkflowAuditLogPruneScheduler.defaultIntervalMs,
+    );
+    void this.runScheduledTick();
+    this.timer = setInterval(() => {
+      void this.runScheduledTick();
+    }, intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  /** Exposed for tests; production path is the interval started by {@link start}. */
+  async runOnce(): Promise<void> {
+    const retentionSec = Number(
+      this.appConfig.env.CODEMATION_AUDIT_WORKFLOW_RETENTION_SECONDS ??
+        WorkflowAuditLogPruneScheduler.defaultRetentionSeconds,
+    );
+    const now = this.clock.now();
+    const cutoff = new Date(now.getTime() - retentionSec * 1000);
+    const limit = Number(this.appConfig.env.CODEMATION_TELEMETRY_PRUNE_LIMIT ?? 2_000);
+
+    // Two-step delete: find IDs first (respects limit), then delete by ID.
+    const rows = await this.prisma.workflowAuditLog.findMany({
+      where: { occurredAt: { lt: cutoff } },
+      select: { id: true },
+      take: limit,
+    });
+
+    if (rows.length === 0) {
+      return;
+    }
+
+    const ids = rows.map((r) => r.id);
+    await this.prisma.workflowAuditLog.deleteMany({ where: { id: { in: ids } } });
+
+    this.logger.info(`WorkflowAuditLog prune: deleted ${ids.length} row(s) older than ${cutoff.toISOString()}`);
+  }
+
+  private async runScheduledTick(): Promise<void> {
+    try {
+      await this.runOnce();
+    } catch (error) {
+      this.logger.warn(`WorkflowAuditLog prune tick failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}

package/src/application/auth/AuthenticatedPrincipal.ts

@@ -2,4 +2,8 @@ export type AuthenticatedPrincipal = Readonly<{
   id: string;
   email: string | null;
   name: string | null;
+  /** Set to "managed-jwt" when the principal was verified from a CP-signed bearer token. */
+  source?: "managed-jwt";
+  /** The workspace ID from the JWT `aud` claim. Present when source === "managed-jwt". */
+  workspaceId?: string;
 }>;

package/src/application/commands/StartWorkflowRunCommandHandler.ts

@@ -21,6 +21,7 @@ import { CommandHandler } from "../bus/CommandHandler";
 import type { CreateRunRequest, RunCommandResult } from "../contracts/RunContracts";
 import { WorkflowDebuggerOverlayStateFactory } from "../workflows/WorkflowDebuggerOverlayStateFactory";
 import { StartWorkflowRunCommand } from "./StartWorkflowRunCommand";
+import { CredentialBindingService } from "../../domain/credentials/CredentialBindingService";
 
 @HandlesCommand.forCommand(StartWorkflowRunCommand)
 export class StartWorkflowRunCommandHandler extends CommandHandler<StartWorkflowRunCommand, RunCommandResult> {
@@ -39,6 +40,8 @@ export class StartWorkflowRunCommandHandler extends CommandHandler<StartWorkflow
     private readonly workflowRunRepository: WorkflowRunRepository,
     @inject(ApplicationTokens.WorkflowDebuggerOverlayRepository)
     private readonly workflowDebuggerOverlayRepository: WorkflowDebuggerOverlayRepository,
+    @inject(CredentialBindingService)
+    private readonly credentialBindingService: CredentialBindingService,
     @inject(ApplicationTokens.LoggerFactory)
     loggerFactory: LoggerFactory,
   ) {
@@ -58,6 +61,7 @@ export class StartWorkflowRunCommandHandler extends CommandHandler<StartWorkflow
     if (!workflow) {
       throw new ApplicationRequestError(404, "Unknown workflowId");
     }
+    await this.credentialBindingService.assertRequiredCredentialsBound(body.workflowId);
     const executionOptions = body.mode
       ? {
           mode: body.mode,

package/src/application/contracts/WorkflowViewContracts.ts

@@ -23,6 +23,17 @@ export type WorkflowNodeDto = Readonly<{
    * mailbox / fixture file / data source the test cases originate from.
    */
   description?: string;
+  /**
+   * When present, the node is a SubWorkflow invocation targeting this workflow id. Surfaced in
+   * the properties panel as an "Open in editor" navigation link.
+   */
+  referencedWorkflowId?: string;
+  /**
+   * Static configuration summary for the inspector — short label/value pairs that describe
+   * what this node will do at a glance, before any run telemetry exists. Pulled from the
+   * node config's optional `inspectorSummary()` hook (`NodeConfigBase.inspectorSummary`).
+   */
+  inspectorSummary?: ReadonlyArray<Readonly<{ label: string; value: string }>>;
 }>;
 
 export type WorkflowEdgeDto = Readonly<{

package/src/application/contracts/WorkflowWebsocketMessage.ts

@@ -1,8 +1,10 @@
 import type { RunEvent } from "@codemation/core";
+import type { TelemetrySpanUpsert } from "../../domain/telemetry/TelemetryContracts";
 
 export type WorkflowWebsocketMessage =
   | Readonly<{ kind: "event"; event: RunEvent }>
   | Readonly<{ kind: "workflowChanged"; workflowId: string }>
   | Readonly<{ kind: "devBuildStarted"; workflowId: string; buildVersion?: string }>
   | Readonly<{ kind: "devBuildCompleted"; workflowId: string; buildVersion: string }>
-  | Readonly<{ kind: "devBuildFailed"; workflowId: string; message: string }>;
+  | Readonly<{ kind: "devBuildFailed"; workflowId: string; message: string }>
+  | Readonly<{ kind: "telemetryEvent"; runId: string; span: TelemetrySpanUpsert }>;

package/src/application/mapping/WorkflowDefinitionMapper.ts

@@ -13,6 +13,7 @@ import type {
   WorkflowNodeDto,
   WorkflowSummary,
 } from "../contracts/WorkflowViewContracts";
+import { McpServerCatalog } from "../../mcp/McpServerCatalog";
 import type { DataMapper } from "./DataMapper";
 import { WorkflowPolicyUiPresentationFactory } from "./WorkflowPolicyUiPresentationFactory";
 
@@ -23,6 +24,8 @@ export class WorkflowDefinitionMapper implements DataMapper<WorkflowDefinition,
     private readonly policyUi: WorkflowPolicyUiPresentationFactory,
     @inject(CoreTokens.WorkflowActivationPolicy)
     private readonly workflowActivationPolicy: WorkflowActivationPolicy,
+    @inject(McpServerCatalog)
+    private readonly mcpCatalog: McpServerCatalog,
   ) {}
 
   async map(workflow: WorkflowDefinition): Promise<WorkflowDto> {
@@ -133,6 +136,8 @@ export class WorkflowDefinitionMapper implements DataMapper<WorkflowDefinition,
           ? ((node.config as { triggerKind?: "live" | "test" }).triggerKind ?? "live")
           : undefined;
       const description = (node.config as { description?: string }).description;
+      const referencedWorkflowId = (node.config as { workflowId?: string }).workflowId;
+      const inspectorSummary = this.readInspectorSummary(node.config);
       nodes.push({
         id: node.id,
         kind: node.kind,
@@ -145,6 +150,10 @@ export class WorkflowDefinitionMapper implements DataMapper<WorkflowDefinition,
         ...this.nodePortFieldsFromConfig(node.config),
         ...(triggerKind ? { triggerKind } : {}),
         ...(typeof description === "string" && description.trim().length > 0 ? { description } : {}),
+        ...(typeof referencedWorkflowId === "string" && referencedWorkflowId.trim().length > 0
+          ? { referencedWorkflowId }
+          : {}),
+        ...(inspectorSummary ? { inspectorSummary } : {}),
       });
       if (AgentConfigInspector.isAgentNodeConfig(node.config)) {
         this.appendVirtualConnectionNodes(
@@ -217,7 +226,9 @@ export class WorkflowDefinitionMapper implements DataMapper<WorkflowDefinition,
       if (!AgentConfigInspector.isAgentNodeConfig(node.config)) {
         continue;
       }
-      const descriptors = AgentConnectionNodeCollector.collect(node.id, node.config);
+      const descriptors = AgentConnectionNodeCollector.collect(node.id, node.config, (id) =>
+        this.mcpCatalog.get(id),
+      );
       byAgentNodeId.set(node.id, descriptors);
       const byChildId = new Map<string, AgentConnectionNodeDescriptor>();
       for (const descriptor of descriptors) {
@@ -283,6 +294,38 @@ export class WorkflowDefinitionMapper implements DataMapper<WorkflowDefinition,
    * Omit optional port fields when undefined so persisted snapshot DTOs (which never serialize
    * undefined keys) stay aligned with live workflow mapping.
    */
+  private readInspectorSummary(
+    config: NodeDefinition["config"] | undefined,
+  ): ReadonlyArray<Readonly<{ label: string; value: string }>> | undefined {
+    if (!config || typeof config !== "object") {
+      return undefined;
+    }
+    const fn = (config as { inspectorSummary?: () => unknown }).inspectorSummary;
+    if (typeof fn !== "function") {
+      return undefined;
+    }
+    let raw: unknown;
+    try {
+      raw = fn.call(config);
+    } catch {
+      // A misbehaving inspectorSummary must not break workflow loading; skip silently.
+      return undefined;
+    }
+    if (!Array.isArray(raw)) {
+      return undefined;
+    }
+    const rows: Array<Readonly<{ label: string; value: string }>> = [];
+    for (const entry of raw) {
+      if (!entry || typeof entry !== "object") continue;
+      const { label, value } = entry as { label?: unknown; value?: unknown };
+      if (typeof label !== "string" || typeof value !== "string") continue;
+      const trimmedLabel = label.trim();
+      if (trimmedLabel.length === 0) continue;
+      rows.push({ label: trimmedLabel, value });
+    }
+    return rows.length > 0 ? rows : undefined;
+  }
+
   private nodePortFieldsFromConfig(
     config: NodeDefinition["config"] | undefined,
   ): Pick<WorkflowNodeDto, "continueWhenEmptyOutput" | "declaredOutputPorts" | "declaredInputPorts"> {

package/src/application/runs/WorkflowRunRetentionPruneScheduler.ts

@@ -104,7 +104,13 @@ export class WorkflowRunRetentionPruneScheduler {
     if (this.appConfig.env.CODEMATION_TELEMETRY_PRUNE_ENABLED !== "false") {
       const telemetryLimit = Number(this.appConfig.env.CODEMATION_TELEMETRY_PRUNE_LIMIT ?? 2_000);
       prunedSpanCount = await this.telemetrySpanStore.pruneExpired({ nowIso, limit: telemetryLimit });
-      prunedArtifactCount = await this.telemetryArtifactStore.pruneExpired({ nowIso, limit: telemetryLimit });
+      const { count: artifactCount, storageKeys: artifactStorageKeys } = await this.telemetryArtifactStore.pruneExpired(
+        { nowIso, limit: telemetryLimit },
+      );
+      for (const key of artifactStorageKeys) {
+        await this.binaryStorage.delete(key);
+      }
+      prunedArtifactCount = artifactCount;
       prunedMetricCount = await this.telemetryMetricPointStore.pruneExpired({ nowIso, limit: telemetryLimit });
     }
 

package/src/application/telemetry/OtelExecutionTelemetry.types.ts

@@ -9,6 +9,7 @@ import { OtelIdentityFactory } from "./OtelIdentityFactory";
 import { TelemetryEnricherChain } from "./TelemetryEnricherChain";
 import { TelemetryPrivacyPolicy } from "./TelemetryPrivacyPolicy";
 import { TelemetryRetentionTimestampFactory } from "./TelemetryRetentionTimestampFactory";
+import { NoOpTelemetrySpanPublisher, type TelemetrySpanPublisher } from "./TelemetrySpanPublisher";
 
 export type StoredExecutionTelemetryDeps = Readonly<{
   traceId: string;
@@ -24,8 +25,12 @@ export type StoredExecutionTelemetryDeps = Readonly<{
   telemetryPrivacyPolicy: TelemetryPrivacyPolicy;
   telemetryRetentionTimestampFactory: TelemetryRetentionTimestampFactory;
   otelIdentityFactory: OtelIdentityFactory;
+  /** Optional publisher for streaming span upserts over WebSocket. Defaults to no-op. */
+  telemetrySpanPublisher?: TelemetrySpanPublisher;
 }>;
 
+export { NoOpTelemetrySpanPublisher };
+
 export type StoredSpanScopeArgs = StoredExecutionTelemetryDeps &
   Readonly<{
     spanId: string;

package/src/application/telemetry/OtelExecutionTelemetryFactory.ts

@@ -12,6 +12,7 @@ import { StoredExecutionTelemetry } from "./StoredExecutionTelemetry";
 import { TelemetryEnricherChain } from "./TelemetryEnricherChain";
 import { TelemetryPrivacyPolicy } from "./TelemetryPrivacyPolicy";
 import { TelemetryRetentionTimestampFactory } from "./TelemetryRetentionTimestampFactory";
+import type { TelemetrySpanPublisher } from "./TelemetrySpanPublisher";
 
 @injectable()
 export class OtelExecutionTelemetryFactory implements ExecutionTelemetryFactory {
@@ -32,6 +33,8 @@ export class OtelExecutionTelemetryFactory implements ExecutionTelemetryFactory
     private readonly telemetryRetentionTimestampFactory: TelemetryRetentionTimestampFactory,
     @inject(OtelIdentityFactory)
     private readonly otelIdentityFactory: OtelIdentityFactory,
+    @inject(ApplicationTokens.TelemetrySpanPublisher)
+    private readonly telemetrySpanPublisher: TelemetrySpanPublisher,
   ) {}
 
   create(
@@ -51,6 +54,7 @@ export class OtelExecutionTelemetryFactory implements ExecutionTelemetryFactory
       telemetryPrivacyPolicy: this.telemetryPrivacyPolicy,
       telemetryRetentionTimestampFactory: this.telemetryRetentionTimestampFactory,
       otelIdentityFactory: this.otelIdentityFactory,
+      telemetrySpanPublisher: this.telemetrySpanPublisher,
     });
   }
 }

package/src/application/telemetry/StoredTelemetrySpanScope.ts

@@ -12,6 +12,7 @@ import type {
 } from "@codemation/core";
 import { NoOpTelemetryArtifactReference } from "@codemation/core";
 import type { TelemetrySpanUpsert } from "../../domain/telemetry/TelemetryContracts";
+import { NoOpTelemetrySpanPublisher } from "./TelemetrySpanPublisher";
 import type { StoredSpanScopeArgs } from "./OtelExecutionTelemetry.types";
 
 export class StoredTelemetrySpanScope implements TelemetrySpanScope {
@@ -226,7 +227,7 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
     const retentionExpiresAt =
       update.retentionExpiresAt ??
       this.deps.telemetryRetentionTimestampFactory.createSpanExpiry(this.deps.policySnapshot, observedAt);
-    await this.deps.telemetrySpanStore.upsert({
+    const upsertRecord: TelemetrySpanUpsert = {
       traceId: this.traceId,
       spanId: this.spanId,
       parentSpanId: this.parentSpanId,
@@ -241,7 +242,10 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
       nodeRole: enrichment.nodeRole,
       retentionExpiresAt,
       ...update,
-    });
+    };
+    await this.deps.telemetrySpanStore.upsert(upsertRecord);
+    const publisher = this.deps.telemetrySpanPublisher ?? NoOpTelemetrySpanPublisher;
+    await publisher.publishSpan(upsertRecord);
     await this.touchTraceContextExpiry(
       this.deps.telemetryRetentionTimestampFactory.createTraceContextExpiry(this.deps.policySnapshot, observedAt),
     );

package/src/application/telemetry/TelemetryRetentionTimestampFactory.ts

@@ -3,38 +3,48 @@ import { injectable } from "@codemation/core";
 
 @injectable()
 export class TelemetryRetentionTimestampFactory {
-  createSpanExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string | undefined {
-    return this.createExpiry(policySnapshot?.telemetrySpanRetentionSeconds, observedAt);
+  /** Default span retention: 7 days (overridden by policySnapshot). */
+  static readonly defaultSpanRetentionSeconds = 7 * 24 * 3600;
+  /** Default artifact retention: 3 days (overridden by policySnapshot). */
+  static readonly defaultArtifactRetentionSeconds = 3 * 24 * 3600;
+  /** Default metric retention: 30 days (overridden by policySnapshot). */
+  static readonly defaultMetricRetentionSeconds = 30 * 24 * 3600;
+
+  createSpanExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string {
+    return this.createExpiry(
+      policySnapshot?.telemetrySpanRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultSpanRetentionSeconds,
+      observedAt,
+    );
   }
 
-  createArtifactExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string | undefined {
-    return this.createExpiry(policySnapshot?.telemetryArtifactRetentionSeconds, observedAt);
+  createArtifactExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string {
+    return this.createExpiry(
+      policySnapshot?.telemetryArtifactRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultArtifactRetentionSeconds,
+      observedAt,
+    );
   }
 
-  createMetricExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string | undefined {
-    return this.createExpiry(policySnapshot?.telemetryMetricRetentionSeconds, observedAt);
+  createMetricExpiry(policySnapshot: PersistedRunPolicySnapshot | undefined, observedAt: Date): string {
+    return this.createExpiry(
+      policySnapshot?.telemetryMetricRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultMetricRetentionSeconds,
+      observedAt,
+    );
   }
 
   createTraceContextExpiry(
     policySnapshot: PersistedRunPolicySnapshot | undefined,
     observedAt: Date,
-  ): string | undefined {
+  ): string {
     const candidates = [
-      policySnapshot?.telemetrySpanRetentionSeconds,
-      policySnapshot?.telemetryArtifactRetentionSeconds,
-      policySnapshot?.telemetryMetricRetentionSeconds,
+      policySnapshot?.telemetrySpanRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultSpanRetentionSeconds,
+      policySnapshot?.telemetryArtifactRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultArtifactRetentionSeconds,
+      policySnapshot?.telemetryMetricRetentionSeconds ?? TelemetryRetentionTimestampFactory.defaultMetricRetentionSeconds,
     ].filter((value): value is number => typeof value === "number" && value > 0);
-    if (candidates.length === 0) {
-      return undefined;
-    }
     const maxSeconds = Math.max(...candidates);
     return this.createExpiry(maxSeconds, observedAt);
   }
 
-  private createExpiry(retentionSeconds: number | undefined, observedAt: Date): string | undefined {
-    if (!retentionSeconds || retentionSeconds <= 0) {
-      return undefined;
-    }
+  private createExpiry(retentionSeconds: number, observedAt: Date): string {
     return new Date(observedAt.getTime() + retentionSeconds * 1000).toISOString();
   }
 }

package/src/application/telemetry/TelemetrySpanPublisher.ts

@@ -0,0 +1,11 @@
+import type { TelemetrySpanUpsert } from "../../domain/telemetry/TelemetryContracts";
+
+export interface TelemetrySpanPublisher {
+  publishSpan(span: TelemetrySpanUpsert): Promise<void>;
+}
+
+export const NoOpTelemetrySpanPublisher: TelemetrySpanPublisher = {
+  async publishSpan(_span: TelemetrySpanUpsert): Promise<void> {
+    // No-op: used in tests and when websocket relay is not wired in.
+  },
+};

package/src/application/websocket/TelemetrySpanWebsocketRelay.ts

@@ -0,0 +1,31 @@
+import { inject, injectable } from "@codemation/core";
+import type { TelemetrySpanUpsert } from "../../domain/telemetry/TelemetryContracts";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { TelemetrySpanPublisher } from "../telemetry/TelemetrySpanPublisher";
+import type { WorkflowWebsocketPublisher } from "./WorkflowWebsocketPublisher";
+
+/**
+ * Implements {@link TelemetrySpanPublisher} by forwarding each span upsert to a
+ * per-run WebSocket room (`run:<runId>`). Clients subscribe to this room when they
+ * open the inspector for a specific run.
+ *
+ * The relay fires *after* the span has been committed to persistent storage so that
+ * HTTP catch-up (on reconnect or initial mount) and WS pushes represent a consistent
+ * view of the data.
+ */
+@injectable()
+export class TelemetrySpanWebsocketRelay implements TelemetrySpanPublisher {
+  constructor(
+    @inject(ApplicationTokens.WorkflowWebsocketPublisher)
+    private readonly workflowWebsocketPublisher: WorkflowWebsocketPublisher,
+  ) {}
+
+  async publishSpan(span: TelemetrySpanUpsert): Promise<void> {
+    const roomId = `run:${span.runId}`;
+    await this.workflowWebsocketPublisher.publishToRoom(roomId, {
+      kind: "telemetryEvent",
+      runId: span.runId,
+      span,
+    });
+  }
+}