@shipfox/api-workflows 14.0.0 → 15.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "14.0.0",
+  "version": "15.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,30 +23,30 @@
     "drizzle-orm": "^0.45.2",
     "js-yaml": "^4.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-auth-dto": "12.0.0",
+    "@shipfox/api-auth-context": "15.0.0",
+    "@shipfox/api-auth-dto": "15.0.0",
+    "@shipfox/api-agent-dto": "15.0.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-agent-dto": "14.0.0",
-    "@shipfox/api-definitions-dto": "14.0.0",
-    "@shipfox/api-integration-core-dto": "14.0.0",
+    "@shipfox/api-definitions-dto": "15.0.0",
+    "@shipfox/api-projects-dto": "15.0.0",
+    "@shipfox/api-integration-core-dto": "15.0.0",
     "@shipfox/api-runners-dto": "14.0.0",
-    "@shipfox/api-projects-dto": "14.0.0",
-    "@shipfox/api-workflows-dto": "14.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/api-workflows-dto": "15.0.0",
+    "@shipfox/api-workspaces-dto": "15.0.0",
+    "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.2.1",
+    "@shipfox/expression": "2.3.0",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
-    "@shipfox/node-fastify": "0.4.2",
-    "@shipfox/node-module": "1.0.6",
-    "@shipfox/node-opentelemetry": "0.6.4",
+    "@shipfox/node-fastify": "0.4.3",
+    "@shipfox/node-module": "1.0.7",
+    "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/config": "1.2.4",
     "@shipfox/node-postgres": "0.5.0",
-    "@shipfox/node-temporal": "0.4.5",
+    "@shipfox/node-temporal": "0.4.6",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.1.0"
+    "@shipfox/workflow-document": "3.2.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/entities/workflow-run.ts

@@ -58,14 +58,16 @@ export type TriggerPayload =
       source: 'manual';
       provider?: 'manual' | undefined;
       event: 'fire';
-      subscriptionId: string;
+      // A dev trigger has no subscription row, so the id is optional here.
+      subscriptionId?: string | undefined;
       userId: string;
     }
   | {
       source: 'cron';
       provider?: 'cron' | undefined;
       event: 'tick';
-      scheduleId: string;
+      // A dev trigger has no schedule row, so the id is optional here.
+      scheduleId?: string | undefined;
     }
   // Integration sources (github, gitlab, sentry, …) flow through opaquely: the
   // run records what fired it and carries the raw event payload, without the

package/src/core/index.ts

@@ -35,8 +35,8 @@ export {
   deriveJobSuccess,
   type JobActivationDecision,
 } from './job-transition/index.js';
-export type {RunWorkflowParams} from './run-workflow.js';
-export {runWorkflow} from './run-workflow.js';
+export type {RunDevWorkflowParams, RunWorkflowParams} from './run-workflow.js';
+export {runDevWorkflow, runWorkflow} from './run-workflow.js';
 export {
   type MaterializedWorkflowJob,
   type MaterializedWorkflowStep,

package/src/core/run-workflow.test.ts

@@ -3,9 +3,9 @@ import {createWorkflowModelSnapshot, type WorkflowModel} from '@shipfox/api-defi
 import type {DefinitionsInterModuleClient} from '@shipfox/api-definitions-dto/inter-module';
 import {agentValidationCatalog} from '#test/fixtures/agent-inter-module.js';
 import {workflowModel} from '#test/index.js';
-import type {TriggerPayload} from './entities/workflow-run.js';
+import type {TriggerPayload, WorkflowRunDevSource} from './entities/workflow-run.js';
 import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
-import {runWorkflow} from './run-workflow.js';
+import {runDevWorkflow, runWorkflow} from './run-workflow.js';
 
 const mockResolveAgentConfig = vi.hoisted(() =>
   vi.fn().mockResolvedValue({
@@ -248,3 +248,102 @@ describe('runWorkflow', () => {
     expect(run.inputs).toEqual({env: 'staging'});
   });
 });
+
+describe('runDevWorkflow', () => {
+  let workspaceId: string;
+  let projectId: string;
+  const agent: AgentInterModuleClient = {
+    getValidationCatalog: vi.fn().mockResolvedValue(agentValidationCatalog),
+    resolveAgentConfig: mockResolveAgentConfig,
+    resolveRuntimeCredentials: vi.fn(),
+  };
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    mockResolveAgentConfig.mockClear();
+  });
+
+  const devSource: WorkflowRunDevSource = {
+    ref: 'fix-triage-prompt',
+    commit: 'a'.repeat(40),
+    configPath: '.shipfox/workflows/triage-sentry.yml',
+    initiatedByUserId: crypto.randomUUID(),
+    replayOfEventId: null,
+  };
+
+  function devPayload(): TriggerPayload {
+    return {source: 'manual', event: 'fire', userId: crypto.randomUUID()};
+  }
+
+  function buildDevRun(workflowId: string, triggerPayload: TriggerPayload = devPayload()) {
+    return runDevWorkflow(agent, {
+      workspaceId,
+      projectId,
+      workflowId,
+      model: createWorkflowModelSnapshot(workflowModel({name: 'Dev Workflow'})),
+      sourceSnapshot: {content: 'name: Dev Workflow\n', format: 'yaml'},
+      devSource,
+      triggerPayload,
+    });
+  }
+
+  test('creates a dev run with the lineage id as definition_id and dev provenance', async () => {
+    const workflowId = crypto.randomUUID();
+    const triggerPayload = devPayload();
+    const run = await buildDevRun(workflowId, triggerPayload);
+
+    expect(run.definitionId).toBe(workflowId);
+    expect(run.origin).toBe('dev');
+    expect(run.devSource).toEqual(devSource);
+    expect(run.name).toBe('Dev Workflow');
+    expect(run.workflowName).toBe('Dev Workflow');
+    expect(run.sourceSnapshot).toEqual({content: 'name: Dev Workflow\n', format: 'yaml'});
+    expect(run.triggerPayload).toEqual(triggerPayload);
+    expect(run.triggerIdempotencyKey).toBeNull();
+  });
+
+  test('continues the lineage number sequence across dev and synced runs of one workflow file', async () => {
+    const workflowId = crypto.randomUUID();
+    // The file exists on the branch only: the dev run opens the sequence.
+    const devRun = await buildDevRun(workflowId);
+    expect(devRun.number).toBe(1);
+
+    // After merge, the synced run of the same lineage continues the sequence.
+    const definition = buildDefinition({
+      projectId,
+      id: crypto.randomUUID(),
+      workflowId,
+      model: workflowModel({name: 'Dev Workflow'}),
+    });
+    definitionResponse = definition;
+    const syncedRun = await runWorkflow(definitions, {
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+      agent,
+    });
+    expect(syncedRun.definitionId).toBe(workflowId);
+    expect(syncedRun.origin).toBe('synced');
+    expect(syncedRun.number).toBe(2);
+
+    // And a later dev run of the same file keeps the sequence going.
+    const secondDevRun = await buildDevRun(workflowId);
+    expect(secondDevRun.number).toBe(3);
+  });
+
+  test('accepts a manual payload without a subscription id, as a dev trigger has no row', async () => {
+    const workflowId = crypto.randomUUID();
+    const triggerPayload = {
+      source: 'manual' as const,
+      event: 'fire' as const,
+      userId: crypto.randomUUID(),
+    };
+    const run = await buildDevRun(workflowId, triggerPayload);
+
+    expect(run.triggerProvider).toBeNull();
+    expect(run.triggerSource).toBe('manual');
+    expect(run.triggerPayload).toEqual(triggerPayload);
+  });
+});

package/src/core/run-workflow.ts

@@ -1,12 +1,17 @@
 import type {AgentInterModuleClient} from '@shipfox/api-agent-dto/inter-module';
-import {workflowModelFromSnapshot} from '@shipfox/api-definitions-dto';
+import {type WorkflowModelSnapshot, workflowModelFromSnapshot} from '@shipfox/api-definitions-dto';
 import type {DefinitionsInterModuleClient} from '@shipfox/api-definitions-dto/inter-module';
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
 import type {SecretsInterModuleClient} from '@shipfox/api-secrets-dto/inter-module';
 import {createWorkflowRun} from '#db/workflow-runs.js';
 import {createAgentDefaultsResolver} from './agent-defaults.js';
-import type {TriggerPayload, WorkflowRun} from './entities/workflow-run.js';
+import type {
+  TriggerPayload,
+  WorkflowRun,
+  WorkflowRunDevSource,
+  WorkflowSourceSnapshot,
+} from './entities/workflow-run.js';
 import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
 import {modelHasAgentStep} from './step-config/materialize-workflow-model.js';
 
@@ -58,3 +63,54 @@ export async function runWorkflow(
     projects: params.projects,
   });
 }
+
+export interface RunDevWorkflowParams {
+  workspaceId: string;
+  projectId: string;
+  /** Workflow lineage id, becomes the run's definition_id. */
+  workflowId: string;
+  model: WorkflowModelSnapshot;
+  sourceSnapshot: WorkflowSourceSnapshot;
+  devSource: WorkflowRunDevSource;
+  triggerPayload: TriggerPayload;
+  triggerConnectionId?: string | undefined;
+  inputs?: Record<string, unknown> | undefined;
+  integrations?: IntegrationsModuleClient | undefined;
+  projects?: ProjectsModuleClient | undefined;
+}
+
+/**
+ * Creates a dev run from an inline model and snapshot. Unlike
+ * trigger-originated runs, dev runs do not carry an idempotency key because
+ * each call represents a distinct intent. The lineage id is used as the run's
+ * definition_id so dev runs share the workflow numbering sequence before and
+ * after the file merges.
+ */
+export function runDevWorkflow(
+  agent: AgentInterModuleClient,
+  params: RunDevWorkflowParams,
+  options: {secrets?: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'>} = {},
+): Promise<WorkflowRun> {
+  const model = workflowModelFromSnapshot(params.model);
+  const resolveAgentDefaults = createAgentDefaultsResolver(
+    agent,
+    modelHasAgentStep(model) ? params.workspaceId : null,
+  );
+
+  return createWorkflowRun({
+    workspaceId: params.workspaceId,
+    projectId: params.projectId,
+    definitionId: params.workflowId,
+    model,
+    triggerPayload: params.triggerPayload,
+    triggerConnectionId: params.triggerConnectionId,
+    inputs: params.inputs,
+    sourceSnapshot: params.sourceSnapshot,
+    origin: 'dev',
+    devSource: params.devSource,
+    resolveAgentDefaults,
+    secrets: options.secrets,
+    integrations: params.integrations,
+    projects: params.projects,
+  });
+}

package/src/db/workflow-runs/run-create.test.ts

@@ -87,6 +87,54 @@ describe('workflow run queries', () => {
         .where(eq(workflowRuns.id, run.id));
     });
 
+    test('persists a dev origin with its dev source', async () => {
+      const devSource = {
+        ref: 'fix-triage-prompt',
+        commit: 'a'.repeat(40),
+        configPath: '.shipfox/workflows/triage-sentry.yml',
+        initiatedByUserId: crypto.randomUUID(),
+        replayOfEventId: null,
+      };
+      const run = await createWorkflowRun({
+        workspaceId,
+        projectId,
+        definitionId,
+        model: buildModel(),
+        triggerPayload: {
+          source: 'manual',
+          event: 'fire',
+          userId: crypto.randomUUID(),
+        },
+        origin: 'dev',
+        devSource,
+      });
+
+      expect(run.origin).toBe('dev');
+      expect(run.devSource).toEqual(devSource);
+      await expect(getWorkflowRunById(run.id)).resolves.toMatchObject({
+        origin: 'dev',
+        devSource,
+      });
+      // The persisted jsonb carries snake_case keys, matching the read boundary.
+      await expect(
+        db()
+          .select({origin: workflowRuns.origin, devSource: workflowRuns.devSource})
+          .from(workflowRuns)
+          .where(eq(workflowRuns.id, run.id)),
+      ).resolves.toEqual([
+        {
+          origin: 'dev',
+          devSource: {
+            ref: devSource.ref,
+            commit: devSource.commit,
+            config_path: devSource.configPath,
+            initiated_by_user_id: devSource.initiatedByUserId,
+            replay_of_event_id: devSource.replayOfEventId,
+          },
+        },
+      ]);
+    });
+
     test('persists normalized integration trigger facts alongside the payload', async () => {
       const triggerConnectionId = crypto.randomUUID();
       const integrations = {

package/src/db/workflow-runs/run-create.ts

@@ -21,6 +21,8 @@ import {
 import type {
   TriggerPayload,
   WorkflowRun,
+  WorkflowRunDevSource,
+  WorkflowRunOrigin,
   WorkflowSourceSnapshot,
 } from '#core/entities/workflow-run.js';
 import {InterpolationUnresolvableError} from '#core/errors.js';
@@ -40,7 +42,7 @@ import {
 import {db, type Tx} from '../db.js';
 import {workflowRunAttempts} from '../schema/workflow-run-attempts.js';
 import {workflowRunCounters} from '../schema/workflow-run-counters.js';
-import {toWorkflowRun, workflowRuns} from '../schema/workflow-runs.js';
+import {toWorkflowRun, type WorkflowRunDevSourceDb, workflowRuns} from '../schema/workflow-runs.js';
 import {type MaterializedRunGraphJob, persistMaterializedRunGraph} from './run-graph.js';
 
 export type WorkflowModelJob = WorkflowModel['jobs'][number];
@@ -63,6 +65,9 @@ export interface CreateWorkflowRunParams {
   inputs?: Record<string, unknown> | undefined;
   sourceSnapshot?: WorkflowSourceSnapshot | null | undefined;
   triggerIdempotencyKey?: string | undefined;
+  /** Run provenance. Defaults to a synced run with no dev source. */
+  origin?: WorkflowRunOrigin | undefined;
+  devSource?: WorkflowRunDevSource | null | undefined;
   resolveAgentDefaults?: AgentDefaultsResolver | undefined;
   secrets?: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'> | undefined;
   integrations?: IntegrationsModuleClient | undefined;
@@ -132,6 +137,11 @@ export async function createWorkflowRun(params: CreateWorkflowRunParams): Promis
         inputs: params.inputs ?? null,
         sourceSnapshot: params.sourceSnapshot ?? null,
         triggerIdempotencyKey: params.triggerIdempotencyKey ?? null,
+        origin: params.origin ?? 'synced',
+        devSource:
+          params.devSource === undefined || params.devSource === null
+            ? null
+            : toWorkflowRunDevSourceDb(params.devSource),
       })
       .onConflictDoNothing({target: workflowRuns.triggerIdempotencyKey})
       .returning();
@@ -281,6 +291,18 @@ async function allocateWorkflowRunNumber(tx: Tx, definitionId: string): Promise<
   return counterRow.number;
 }
 
+// The run entity carries camelCase dev-source fields while the persisted jsonb uses
+// snake_case keys, so the write boundary maps explicitly rather than spreading.
+function toWorkflowRunDevSourceDb(source: WorkflowRunDevSource): WorkflowRunDevSourceDb {
+  return {
+    ref: source.ref,
+    commit: source.commit,
+    config_path: source.configPath,
+    initiated_by_user_id: source.initiatedByUserId,
+    replay_of_event_id: source.replayOfEventId,
+  };
+}
+
 export async function loadReferencedVariables(params: {
   readonly model: WorkflowModel;
   readonly jobs?: readonly WorkflowModelJob[] | undefined;

package/src/presentation/inter-module.test.ts

@@ -1,3 +1,4 @@
+import {createWorkflowModelSnapshot} from '@shipfox/api-definitions-dto';
 import {workflowsInterModuleContract} from '@shipfox/api-workflows-dto/inter-module';
 import {workspacesInterModuleContract} from '@shipfox/api-workspaces-dto/inter-module';
 import {createInterModuleKnownError, isInterModuleKnownError} from '@shipfox/inter-module';
@@ -9,7 +10,13 @@ import {
   InterpolationUnresolvableError,
   ProjectMismatchError,
 } from '#core/index.js';
-import {createWorkflowsInterModulePresentation, toStartRunKnownError} from './inter-module.js';
+import {getWorkflowRunById} from '#db/workflow-runs.js';
+import {workflowModel} from '#test/index.js';
+import {
+  createWorkflowsInterModulePresentation,
+  toStartDevRunKnownError,
+  toStartRunKnownError,
+} from './inter-module.js';
 
 const mocks = vi.hoisted(() => ({
   deliverEventToListener: vi.fn(),
@@ -188,6 +195,129 @@ describe('Workflows inter-module presentation', () => {
     ).toBe('workspace-not-found');
   });
 
+  const devInput = {
+    workspaceId: input.workspaceId,
+    projectId: input.projectId,
+    workflowId: '00000000-0000-4000-8000-000000000006',
+    model: createWorkflowModelSnapshot(
+      workflowModel({name: 'Dev Workflow', jobs: {build: {steps: [{run: 'echo dev'}]}}}),
+    ),
+    sourceSnapshot: {content: 'name: Dev Workflow\n', format: 'yaml' as const},
+    devSource: {
+      ref: 'fix-triage-prompt',
+      commit: 'a'.repeat(40),
+      configPath: '.shipfox/workflows/triage-sentry.yml',
+      initiatedByUserId: input.triggerPayload.userId,
+    },
+    triggerPayload: {
+      source: 'manual' as const,
+      event: 'fire' as const,
+      userId: input.triggerPayload.userId,
+    },
+  };
+
+  test.each([
+    ['agent-config-unresolvable', () => new AgentConfigUnresolvableError(devInput.workflowId)],
+    [
+      'agent-integration-materialization-failed',
+      () => new AgentIntegrationMaterializationError('integration unavailable'),
+    ],
+    [
+      'interpolation-unresolvable',
+      () =>
+        new InterpolationUnresolvableError(devInput.workflowId, {
+          field: 'env',
+          source: 'event.ref',
+          envKey: 'REF',
+        }),
+    ],
+    ['invalid-job-runner-labels', () => new InvalidJobRunnerLabelsError(['gpu'])],
+  ] as const)('maps %s to the published dev-run contract error', (code, error) => {
+    const result = toStartDevRunKnownError(error());
+
+    expect(
+      isInterModuleKnownError(workflowsInterModuleContract.methods.startDevRun, result) &&
+        result.code,
+    ).toBe(code);
+  });
+
+  test.each([
+    ['definition-not-found', () => new DefinitionNotFoundError(devInput.workflowId)],
+    ['project-mismatch', () => new ProjectMismatchError(devInput.projectId, devInput.workflowId)],
+  ] as const)('does not map %s on the dev-run contract', (_code, error) => {
+    const result = toStartDevRunKnownError(error());
+
+    expect(isInterModuleKnownError(workflowsInterModuleContract.methods.startDevRun, result)).toBe(
+      false,
+    );
+  });
+
+  test.each([
+    ['suspended', 'workspace-suspended'],
+    ['deleted', 'workspace-deleted'],
+  ] as const)('rejects dev runs for %s workspaces before creating a run', async (status, code) => {
+    const getWorkspaceOperatingState = vi.fn().mockResolvedValue({status});
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {getWorkspaceOperatingState} as never,
+    });
+
+    const error = await Promise.resolve(
+      presentation.handlers.startDevRun(devInput, {
+        signal: new AbortController().signal,
+      }),
+    ).catch((caught: unknown) => caught);
+
+    expect(getWorkspaceOperatingState).toHaveBeenCalledWith({workspaceId: devInput.workspaceId});
+    expect(
+      isInterModuleKnownError(workflowsInterModuleContract.methods.startDevRun, error) &&
+        error.code,
+    ).toBe(code);
+  });
+
+  test('creates a dev run with dev provenance and lineage numbering', async () => {
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {
+        getWorkspaceOperatingState: vi.fn().mockResolvedValue({status: 'active'}),
+      } as never,
+    });
+    // A fresh lineage id keeps the assertion independent of counter rows left
+    // behind by earlier suite runs against the shared test database.
+    const workflowId = crypto.randomUUID();
+    const runInput = {...devInput, workflowId};
+
+    const first = await presentation.handlers.startDevRun(runInput, {
+      signal: new AbortController().signal,
+    });
+    const second = await presentation.handlers.startDevRun(runInput, {
+      signal: new AbortController().signal,
+    });
+
+    const firstRun = await getWorkflowRunById(first.id);
+    const secondRun = await getWorkflowRunById(second.id);
+    expect(firstRun).toMatchObject({
+      definitionId: workflowId,
+      origin: 'dev',
+      devSource: {...devInput.devSource, replayOfEventId: null},
+      number: 1,
+      name: 'Dev Workflow',
+      sourceSnapshot: devInput.sourceSnapshot,
+    });
+    // Each call is a distinct intent, so the lineage number sequence continues.
+    expect(secondRun).toMatchObject({definitionId: workflowId, origin: 'dev', number: 2});
+  });
+
   test.each([
     ['suspended', 'workspace-suspended'],
     ['deleted', 'workspace-deleted'],

package/src/presentation/inter-module.ts

@@ -27,6 +27,7 @@ import {
   DefinitionNotFoundError,
   InterpolationUnresolvableError,
   ProjectMismatchError,
+  runDevWorkflow,
   runWorkflow,
 } from '#core/index.js';
 import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-reference.js';
@@ -72,6 +73,34 @@ export function createWorkflowsInterModulePresentation(params: {
         throw toStartRunKnownError(error, input.definitionId);
       }
     },
+    startDevRun: async (input) => {
+      try {
+        await assertWorkspaceAdmitsNewJobs(params.workspaces, input.workspaceId);
+        const run = await runDevWorkflow(
+          params.agent,
+          {
+            workspaceId: input.workspaceId,
+            projectId: input.projectId,
+            workflowId: input.workflowId,
+            model: input.model,
+            sourceSnapshot: input.sourceSnapshot,
+            devSource: {
+              ...input.devSource,
+              replayOfEventId: input.devSource.replayOfEventId ?? null,
+            },
+            triggerPayload: input.triggerPayload,
+            triggerConnectionId: input.triggerConnectionId,
+            inputs: input.inputs,
+            integrations: params.integrations,
+            projects: params.projects,
+          },
+          {secrets: params.secrets},
+        );
+        return {id: run.id, name: run.name};
+      } catch (error) {
+        throw toStartDevRunKnownError(error);
+      }
+    },
     resolveWorkflowRunTriggerReference: async (input) =>
       await resolveWorkflowRunTriggerReference({
         workspaceId: input.workspaceId,
@@ -158,14 +187,29 @@ export function createWorkflowsInterModulePresentation(params: {
 
 export function toStartRunKnownError(error: unknown, definitionId: string): unknown {
   const method = workflowsInterModuleContract.methods.startRunFromTrigger;
-  const workspaceError = toWorkspaceAdmissionKnownError(method, error);
-  if (workspaceError !== undefined) return workspaceError;
+  const mapped = toRunCreationKnownError(method, error);
+  if (mapped !== undefined) return mapped;
   if (error instanceof DefinitionNotFoundError) {
     return createInterModuleKnownError(method, 'definition-not-found', {definitionId});
   }
   if (error instanceof ProjectMismatchError) {
     return createInterModuleKnownError(method, 'project-mismatch', {});
   }
+  return error;
+}
+
+export function toStartDevRunKnownError(error: unknown): unknown {
+  return toRunCreationKnownError(workflowsInterModuleContract.methods.startDevRun, error) ?? error;
+}
+
+function toRunCreationKnownError(
+  method:
+    | typeof workflowsInterModuleContract.methods.startRunFromTrigger
+    | typeof workflowsInterModuleContract.methods.startDevRun,
+  error: unknown,
+): unknown {
+  const workspaceError = toWorkspaceAdmissionKnownError(method, error);
+  if (workspaceError !== undefined) return workspaceError;
   if (error instanceof AgentConfigUnresolvableError) {
     return createInterModuleKnownError(method, 'agent-config-unresolvable', {
       definitionId: error.definitionId,
@@ -187,12 +231,13 @@ export function toStartRunKnownError(error: unknown, definitionId: string): unkn
       labels: [...error.labels],
     });
   }
-  return error;
+  return undefined;
 }
 
 function toWorkspaceAdmissionKnownError(
   method:
     | typeof workflowsInterModuleContract.methods.startRunFromTrigger
+    | typeof workflowsInterModuleContract.methods.startDevRun
     | typeof workflowsInterModuleContract.methods.deliverEventToJobListener,
   error: unknown,
 ): WorkspaceAdmissionKnownError | undefined {