@shipfox/api-workflows 13.0.0 → 14.0.0

package/drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1786266649202,
       "tag": "0003_output_invalid_reason",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1787477580166,
+      "tag": "0004_dev_run_origin",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -25,28 +25,28 @@
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-agent-dto": "12.2.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-definitions-dto": "12.3.0",
-    "@shipfox/api-projects-dto": "12.2.0",
-    "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-runners-dto": "13.0.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-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-workflows-dto": "13.0.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
-    "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.2.0",
+    "@shipfox/expression": "2.2.1",
     "@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-outbox": "0.2.6",
+    "@shipfox/config": "1.2.4",
     "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-temporal": "0.4.5",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.0.1"
+    "@shipfox/workflow-document": "3.1.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/checkout.test.ts

@@ -3,9 +3,24 @@ import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module'
 import {projectFactory} from '#test/factories/project.js';
 import {createStepCheckoutSpec} from './checkout.js';
 import type {Step} from './entities/step.js';
-import type {WorkflowRunTriggerReference} from './entities/workflow-run.js';
+import type {WorkflowRunDevSource, WorkflowRunTriggerReference} from './entities/workflow-run.js';
 import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from './errors.js';
 
+const syncedRun = {origin: 'synced', devSource: null} as const;
+
+function devRun(commit: string): {origin: 'dev'; devSource: WorkflowRunDevSource} {
+  return {
+    origin: 'dev',
+    devSource: {
+      ref: 'fix-triage-prompt',
+      commit,
+      configPath: '.shipfox/workflows/triage-sentry.yml',
+      initiatedByUserId: crypto.randomUUID(),
+      replayOfEventId: null,
+    },
+  };
+}
+
 const getProjectById = vi.fn();
 const resolveCheckoutTarget = vi.fn();
 const projects = {
@@ -46,6 +61,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     const result = await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -96,6 +112,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     const result = await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -134,6 +151,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -167,6 +185,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -200,6 +219,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -216,6 +236,41 @@ describe('createStepCheckoutSpec', () => {
     });
   });
 
+  it('falls through to the dev commit when a same-project trigger has no commit', async () => {
+    const project = projectFactory.build();
+    const devCommit = 'b'.repeat(40);
+    const triggerReference = {...triggerReferenceFor(project.id), commit: null};
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: devCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun(devCommit),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: devCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
   it('keeps the provider default ref for a cross-repository target', async () => {
     const project = projectFactory.build();
     const targetProjectId = crypto.randomUUID();
@@ -232,6 +287,142 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: expect.any(String),
+      externalRepositoryId: 'github:412',
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('checks out the dev commit for a dev run without a trigger reference', async () => {
+    const project = projectFactory.build();
+    const devCommit = 'b'.repeat(40);
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: devCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun(devCommit),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: devCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('prefers the event commit over the dev commit on a dev replay of a same-project push', async () => {
+    const project = projectFactory.build();
+    const eventCommit = 'c'.repeat(40);
+    const triggerReference = {...triggerReferenceFor(project.id), commit: eventCommit};
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: eventCommit,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: eventCommit,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('preserves an explicit ref on a dev run', async () => {
+    const project = projectFactory.build();
+    const explicitRef = 'refs/heads/feature/checkout';
+    const step = checkoutStep({ref: explicitRef, permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: explicitRef,
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: explicitRef,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('keeps the provider default ref for a cross-project target in a dev run', async () => {
+    const project = projectFactory.build();
+    const targetProjectId = crypto.randomUUID();
+    const step = checkoutStep({project: targetProjectId});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: targetProjectId,
+      connectionId: crypto.randomUUID(),
+      externalRepositoryId: 'github:412',
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/target.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      run: devRun('b'.repeat(40)),
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -263,6 +454,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -294,6 +486,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -330,6 +523,7 @@ describe('createStepCheckoutSpec', () => {
     });
 
     await createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,
@@ -350,6 +544,7 @@ describe('createStepCheckoutSpec', () => {
     {connection: 'github'},
   ])('rejects invalid checkout target shape: %j', async (checkout) => {
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step: checkoutStep(checkout),
       workspaceId: crypto.randomUUID(),
       projectId: crypto.randomUUID(),
@@ -368,6 +563,7 @@ describe('createStepCheckoutSpec', () => {
     getProjectById.mockResolvedValue({project: null});
 
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step: checkoutStep({}),
       workspaceId: crypto.randomUUID(),
       projectId,
@@ -387,6 +583,7 @@ describe('createStepCheckoutSpec', () => {
     resolveConnection.mockResolvedValue(null);
 
     const act = createStepCheckoutSpec({
+      run: syncedRun,
       step,
       workspaceId: project.workspaceId,
       projectId: project.id,

package/src/core/checkout.ts

@@ -3,7 +3,10 @@ import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module'
 import {checkoutTargetValidationIssues} from '@shipfox/workflow-document';
 import {z} from 'zod';
 import type {Step} from '#core/entities/step.js';
-import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
+import type {
+  WorkflowRunOriginState,
+  WorkflowRunTriggerReference,
+} from '#core/entities/workflow-run.js';
 import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from './errors.js';
 
 const checkoutConfigSchema = z
@@ -39,6 +42,7 @@ export async function createStepCheckoutSpec({
   workspaceId,
   projectId,
   triggerReference,
+  run,
   integrations,
   projects,
 }: {
@@ -46,6 +50,8 @@ export async function createStepCheckoutSpec({
   workspaceId: string;
   projectId: string;
   triggerReference?: WorkflowRunTriggerReference | null | undefined;
+  /** The run's origin state; a dev run checks out its dev commit by default. */
+  run: WorkflowRunOriginState;
   integrations: IntegrationsModuleClient;
   projects: ProjectsModuleClient;
 }): Promise<{
@@ -79,11 +85,18 @@ export async function createStepCheckoutSpec({
     },
     target,
   });
-  const ref =
-    checkout.ref ??
-    (triggerReference?.project?.id === resolvedTarget.projectId
+  // Explicit step refs win, followed by same-project event commits (including
+  // replays), then the pinned dev commit for the run's own project. Other targets
+  // intentionally use the provider default branch.
+  const triggerCommitRef =
+    triggerReference?.project?.id === resolvedTarget.projectId
       ? (triggerReference.commit ?? undefined)
-      : undefined);
+      : undefined;
+  const devCommitRef =
+    run.origin === 'dev' && resolvedTarget.projectId === projectId
+      ? run.devSource.commit
+      : undefined;
+  const ref = checkout.ref ?? triggerCommitRef ?? devCommitRef;
   const response = await integrations.createCheckoutSpec({
     workspaceId,
     connectionId: resolvedTarget.connectionId,

package/src/core/entities/job.ts

@@ -69,7 +69,7 @@ export interface Job {
 
 export interface JobListeningTrigger {
   readonly source: string;
-  readonly event: string;
+  readonly event?: string;
   readonly inputs?: Readonly<Record<string, unknown>>;
   readonly filter?: string;
 }

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

@@ -5,6 +5,24 @@ import type {WorkflowRunAttempt} from './workflow-run-attempt.js';
 
 export type WorkflowRunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 
+export type WorkflowRunOrigin = 'synced' | 'dev';
+
+/**
+ * Why a dev run was created: the ref and pinned commit the definition came from, the
+ * file that ran, the user who started it, and the journaled event it replays when any.
+ */
+export interface WorkflowRunDevSource {
+  ref: string;
+  commit: string;
+  configPath: string;
+  initiatedByUserId: string;
+  replayOfEventId: string | null;
+}
+
+export type WorkflowRunOriginState =
+  | {origin: 'synced'; devSource: null}
+  | {origin: 'dev'; devSource: WorkflowRunDevSource};
+
 export type TerminalWorkflowRunStatus = Extract<
   WorkflowRunStatus,
   'succeeded' | 'failed' | 'cancelled'
@@ -60,7 +78,7 @@ export type TriggerPayload =
       data: unknown;
     };
 
-export interface WorkflowRun {
+export type WorkflowRun = WorkflowRunOriginState & {
   id: string;
   workspaceId: string;
   projectId: string;
@@ -89,7 +107,7 @@ export interface WorkflowRun {
   updatedAt: Date;
   startedAt: Date | null;
   finishedAt: Date | null;
-}
+};
 
 export interface StepDetail extends Step {
   attempts: StepAttempt[];
@@ -103,11 +121,11 @@ export interface WorkflowJobDetail extends Job {
   jobExecutions: JobExecutionDetail[];
 }
 
-export interface WorkflowRunDetail extends WorkflowRun {
+export type WorkflowRunDetail = WorkflowRun & {
   runAttempt: WorkflowRunAttempt;
   latestAttempt: number;
   jobs: WorkflowJobDetail[];
   /** Whether any job execution of this attempt reached its runner, decided here so the detail
    * and the list cannot answer it differently. */
   hasStartedJobExecution: boolean;
-}
+};

package/src/core/errors.ts

@@ -38,13 +38,28 @@ export class WorkspaceNotFoundError extends Error {
   }
 }
 
+export interface AgentConfigUnresolvableErrorOptions {
+  readonly cause?: unknown;
+  readonly message?: string;
+  readonly code?: string;
+  readonly managedProviderId?: string;
+}
+
 export class AgentConfigUnresolvableError extends Error {
+  readonly code?: string | undefined;
+  readonly managedProviderId?: string | undefined;
+
   constructor(
     readonly definitionId: string,
-    options?: ErrorOptions | undefined,
+    options?: AgentConfigUnresolvableErrorOptions | undefined,
   ) {
-    super(`Agent configuration cannot be resolved for definition ${definitionId}`, options);
+    super(
+      options?.message ?? `Agent configuration cannot be resolved for definition ${definitionId}`,
+      options?.cause === undefined ? undefined : {cause: options.cause},
+    );
     this.name = 'AgentConfigUnresolvableError';
+    this.code = options?.code;
+    this.managedProviderId = options?.managedProviderId;
   }
 }
 

package/src/core/job-execution.test.ts

@@ -1,3 +1,7 @@
+import {
+  type AgentInterModuleClient,
+  agentInterModuleContract,
+} from '@shipfox/api-agent-dto/inter-module';
 import {
   WORKFLOWS_JOB_STEPS_SETTLED,
   WORKFLOWS_STEP_ATTEMPT_TERMINATED,
@@ -10,6 +14,7 @@ import {
   parseWorkflowTemplate,
   planInterpolationField,
 } from '@shipfox/expression';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
 import {and, eq, sql} from 'drizzle-orm';
 import {db} from '#db/db.js';
 import {workflowsOutbox} from '#db/schema/outbox.js';
@@ -322,6 +327,55 @@ describe('nextStepForJob', () => {
     });
   });
 
+  test('reports managed provider policy failures as agent config errors', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(1);
+    const pending = steps[0];
+    if (!pending) throw new Error('Expected pending step');
+    await db()
+      .update(stepsTable)
+      .set({
+        config: {},
+        configPlan: {
+          agent: {
+            prompt: {segments: [{kind: 'literal', value: 'Review the change.'}]},
+          },
+        },
+      })
+      .where(eq(stepsTable.id, pending.id));
+
+    const agent = {
+      getValidationCatalog: vi.fn(),
+      resolveAgentConfig: vi.fn().mockRejectedValue(
+        createInterModuleKnownError(
+          agentInterModuleContract.methods.resolveAgentConfig,
+          'agent-config-invalid',
+          {
+            message: 'This instance only supports provider `shipfox`.',
+            managed_provider_id: 'shipfox',
+          },
+        ),
+      ),
+      resolveRuntimeCredentials: vi.fn(),
+    } as unknown as AgentInterModuleClient;
+
+    const next = await nextStepForJob(jobId, agent);
+
+    expect(next).toEqual({kind: 'done', status: 'failed'});
+    const after = await getStepsByJobId(jobId);
+    expect(after[0]).toMatchObject({
+      status: 'failed',
+      error: {
+        message: 'This instance only supports provider `shipfox`.',
+        reason: 'agent_config_invalid',
+        field: 'agent',
+        source: 'agent',
+        code: 'workspace-providers-disabled',
+        managedProviderId: 'shipfox',
+        agentConfigIssue: 'provider_unsupported',
+      },
+    });
+  });
+
   test('all steps succeeded → {done, succeeded}', async () => {
     const {jobId, steps} = await arrangeJobWithSteps(2);
     for (const step of steps) {

package/src/core/job-execution.ts

@@ -339,11 +339,16 @@ function dispatchConfigError(error: DispatchConfigError): Record<string, unknown
     };
   }
 
+  const isManagedProviderPolicyFailure =
+    error.code === 'workspace-providers-disabled' && error.managedProviderId !== undefined;
   return {
     message: error.message,
-    reason: 'config_unresolvable',
+    reason: isManagedProviderPolicyFailure ? 'agent_config_invalid' : 'config_unresolvable',
     field: 'agent',
     source: 'agent',
+    ...(error.code === undefined ? {} : {code: error.code}),
+    ...(error.managedProviderId === undefined ? {} : {managedProviderId: error.managedProviderId}),
+    ...(isManagedProviderPolicyFailure ? {agentConfigIssue: 'provider_unsupported'} : {}),
   };
 }
 

package/src/core/job-transition/decide-job-activation.test.ts

@@ -121,6 +121,8 @@ function workflowRun(): WorkflowRun {
     workflowName: 'Run',
     nameOverride: null,
     status: 'pending',
+    origin: 'synced',
+    devSource: null,
     currentAttempt: 1,
     triggerProvider: null,
     triggerSource: 'manual',

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

@@ -23,6 +23,12 @@ type DefinitionForWorkflowRun = NonNullable<
 let definitionResponse: DefinitionForWorkflowRun | null = null;
 const definitions: DefinitionsInterModuleClient = {
   getDefinitionForWorkflowRun: async () => ({definition: definitionResponse}),
+  resolveDefinitionAtRef: () => {
+    throw new Error('resolveDefinitionAtRef is not used by runWorkflow');
+  },
+  listDefinitionsAtRef: () => {
+    throw new Error('listDefinitionsAtRef is not used by runWorkflow');
+  },
 };
 
 function buildDefinition(
@@ -31,6 +37,7 @@ function buildDefinition(
   const {model = workflowModel(), ...definitionOverrides} = overrides;
   return {
     id: crypto.randomUUID(),
+    workflowId: crypto.randomUUID(),
     projectId: crypto.randomUUID(),
     name: 'Test Workflow',
     model: createWorkflowModelSnapshot(model),
@@ -79,7 +86,7 @@ describe('runWorkflow', () => {
 
     expect(run.id).toBeDefined();
     expect(run.projectId).toBe(projectId);
-    expect(run.definitionId).toBe(definition.id);
+    expect(run.definitionId).toBe(definition.workflowId);
     expect(run.name).toBe(definition.name);
     expect(run.status).toBe('pending');
     expect(run.triggerProvider).toBeNull();
@@ -151,6 +158,48 @@ describe('runWorkflow', () => {
     expect(run.sourceSnapshot).toEqual(sourceSnapshot);
   });
 
+  test('numbers runs by the workflow lineage id, not the definition row id', async () => {
+    const lineageId = crypto.randomUUID();
+    // A lineage whose id differs from the definition row id, as happens after
+    // the backfill when a lineage id diverges from the synced row it was born from.
+    const definition = buildDefinition({projectId, id: crypto.randomUUID(), workflowId: lineageId});
+    definitionResponse = definition;
+
+    const first = await runWorkflow(definitions, {
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+      agent,
+    });
+    const second = await runWorkflow(definitions, {
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+      agent,
+    });
+
+    expect(first.definitionId).toBe(lineageId);
+    expect(second.definitionId).toBe(lineageId);
+    expect(first.number).toBe(1);
+    expect(second.number).toBe(2);
+
+    // A later definition row that resolves to the same lineage continues the sequence.
+    const resynced = buildDefinition({projectId, id: crypto.randomUUID(), workflowId: lineageId});
+    definitionResponse = resynced;
+    const third = await runWorkflow(definitions, {
+      workspaceId,
+      projectId,
+      definitionId: resynced.id,
+      triggerPayload: manualPayload(),
+      agent,
+    });
+
+    expect(third.definitionId).toBe(lineageId);
+    expect(third.number).toBe(3);
+  });
+
   test('throws DefinitionNotFoundError for unknown definition', async () => {
     definitionResponse = null;