@shipfox/api-workflows 2.0.0

package/src/presentation/routes/rerun-run.ts

@@ -0,0 +1,48 @@
+import {requireUserContext} from '@shipfox/api-auth-context';
+import {rerunWorkflowRunBodySchema, workflowRunResponseSchema} from '@shipfox/api-workflows-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {NoFailedJobsError, RunNotTerminalError, SourceRunNotFoundError} from '#core/errors.js';
+import {createRerunWorkflowRun} from '#db/index.js';
+import {toRunDto} from '#presentation/dto/index.js';
+import {requireAccessibleRun} from './require-accessible-run.js';
+
+export const rerunRunRoute = defineRoute({
+  method: 'POST',
+  path: '/:id/rerun',
+  description: 'Re-run a terminal workflow run',
+  schema: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+    body: rerunWorkflowRunBodySchema,
+    response: {
+      200: workflowRunResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof SourceRunNotFoundError) {
+      throw new ClientError('Run not found', 'not-found', {status: 404});
+    }
+    if (error instanceof RunNotTerminalError) {
+      throw new ClientError('Run is not terminal', 'run-not-terminal', {status: 409});
+    }
+    if (error instanceof NoFailedJobsError) {
+      throw new ClientError('Run has no failed jobs', 'no-failed-jobs', {status: 409});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const {id} = request.params;
+    const sourceRun = await requireAccessibleRun({request, id});
+
+    const actor = requireUserContext(request);
+    const run = await createRerunWorkflowRun({
+      workflowRunId: sourceRun.id,
+      mode: request.body.mode,
+      actorUserId: actor.userId,
+    });
+
+    return toRunDto(run, run.currentAttempt);
+  },
+});

package/src/presentation/subscribers/index.ts

@@ -0,0 +1,7 @@
+export {onJobEventDelivered} from './on-job-event-delivered.js';
+export {onJobStepsSettled} from './on-job-steps-settled.js';
+export {onRunnerJobClaimed} from './on-runner-job-claimed.js';
+export {onRunnerJobLeaseExpired} from './on-runner-job-lease-expired.js';
+export {onRunnerJobQueued} from './on-runner-job-queued.js';
+export {onWorkflowRunAttemptCreated} from './on-workflow-run-attempt-created.js';
+export {onWorkflowRunCancelled} from './on-workflow-run-cancelled.js';

package/src/presentation/subscribers/on-job-event-delivered.test.ts

@@ -0,0 +1,71 @@
+import type {WorkflowsJobEventDeliveredEventDto} from '@shipfox/api-workflows-dto';
+import {onJobEventDelivered} from './on-job-event-delivered.js';
+
+const signalMock = vi.fn();
+const getHandleMock = vi.fn(() => ({signal: signalMock}));
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  logger: () => ({debug: vi.fn()}),
+}));
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({workflow: {getHandle: getHandleMock}}),
+}));
+
+function buildPayload(
+  overrides: Partial<WorkflowsJobEventDeliveredEventDto> = {},
+): WorkflowsJobEventDeliveredEventDto {
+  return {
+    jobId: crypto.randomUUID(),
+    disposition: 'fire',
+    eventRef: crypto.randomUUID(),
+    eventName: 'pull_request_review',
+    ...overrides,
+  };
+}
+
+describe('onJobEventDelivered', () => {
+  beforeEach(() => {
+    getHandleMock.mockClear();
+    signalMock.mockReset();
+    signalMock.mockResolvedValue(undefined);
+  });
+
+  it('signals the listener workflow when a fire event is delivered', async () => {
+    const payload = buildPayload({disposition: 'fire'});
+
+    await onJobEventDelivered(payload);
+
+    expect(getHandleMock).toHaveBeenCalledWith(`job-listener:${payload.jobId}`);
+    expect(signalMock).toHaveBeenCalledWith('events-available');
+  });
+
+  it('signals the listener workflow when a resolve event is delivered', async () => {
+    const payload = buildPayload({disposition: 'resolve'});
+
+    await onJobEventDelivered(payload);
+
+    expect(getHandleMock).toHaveBeenCalledWith(`job-listener:${payload.jobId}`);
+    expect(signalMock).toHaveBeenCalledWith('resolve');
+  });
+
+  it('discards a delivered event when the listener workflow already terminated', async () => {
+    const notFound = new Error('gone');
+    notFound.name = 'WorkflowNotFoundError';
+    signalMock.mockRejectedValueOnce(notFound);
+
+    const result = onJobEventDelivered(buildPayload());
+
+    await expect(result).resolves.toBeUndefined();
+    expect(signalMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows a non-terminal signal failure', async () => {
+    const failure = new Error('temporal unavailable');
+    signalMock.mockRejectedValueOnce(failure);
+
+    const result = onJobEventDelivered(buildPayload());
+
+    await expect(result).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/on-job-event-delivered.ts

@@ -0,0 +1,30 @@
+import type {WorkflowsJobEventDeliveredEventDto} from '@shipfox/api-workflows-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
+import {LISTENER_EVENTS_AVAILABLE_SIGNAL, LISTENER_RESOLVE_SIGNAL} from '#temporal/constants.js';
+import {isWorkflowNotFound} from '#temporal/workflow-not-found.js';
+
+export async function onJobEventDelivered(
+  payload: WorkflowsJobEventDeliveredEventDto,
+): Promise<void> {
+  const signal =
+    payload.disposition === 'resolve' ? LISTENER_RESOLVE_SIGNAL : LISTENER_EVENTS_AVAILABLE_SIGNAL;
+  const handle = temporalClient().workflow.getHandle(`job-listener:${payload.jobId}`);
+  try {
+    await handle.signal(signal);
+  } catch (err) {
+    if (isWorkflowNotFound(err)) {
+      logger().debug(
+        {
+          jobId: payload.jobId,
+          disposition: payload.disposition,
+          eventRef: payload.eventRef,
+          eventName: payload.eventName,
+        },
+        'Listener workflow already terminated; delivered event discarded',
+      );
+      return;
+    }
+    throw err;
+  }
+}

package/src/presentation/subscribers/on-job-steps-settled.test.ts

@@ -0,0 +1,75 @@
+import type {WorkflowsJobStepsSettledEventDto} from '@shipfox/api-workflows-dto';
+import {onJobStepsSettled} from './on-job-steps-settled.js';
+
+const signalMock = vi.fn();
+const getHandleMock = vi.fn(() => ({signal: signalMock}));
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({workflow: {getHandle: getHandleMock}}),
+}));
+
+function buildPayload(
+  overrides: Partial<WorkflowsJobStepsSettledEventDto> = {},
+): WorkflowsJobStepsSettledEventDto {
+  return {
+    jobId: crypto.randomUUID(),
+    jobExecutionId: crypto.randomUUID(),
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    status: 'succeeded',
+    ...overrides,
+  };
+}
+
+describe('onJobStepsSettled', () => {
+  beforeEach(() => {
+    getHandleMock.mockClear();
+    signalMock.mockReset();
+    signalMock.mockResolvedValue(undefined);
+  });
+
+  it('signals the job workflow with the settled status', async () => {
+    const payload = buildPayload({status: 'failed'});
+
+    await onJobStepsSettled(payload);
+
+    expect(getHandleMock).toHaveBeenCalledWith(`job:${payload.jobId}`);
+    expect(signalMock).toHaveBeenCalledWith('job-finished', {
+      status: 'failed',
+      jobExecutionId: payload.jobExecutionId,
+    });
+  });
+
+  it('routes a stale-attempt event only to the payload job workflow', async () => {
+    const previousAttemptJobId = crypto.randomUUID();
+    const payload = buildPayload({
+      jobId: previousAttemptJobId,
+      workflowRunAttemptId: crypto.randomUUID(),
+    });
+
+    await onJobStepsSettled(payload);
+
+    expect(getHandleMock).toHaveBeenCalledTimes(1);
+    expect(getHandleMock).toHaveBeenCalledWith(`job:${previousAttemptJobId}`);
+  });
+
+  it('discards a late event when the job workflow already terminated', async () => {
+    const notFound = new Error('gone');
+    notFound.name = 'WorkflowNotFoundError';
+    signalMock.mockRejectedValueOnce(notFound);
+
+    const result = onJobStepsSettled(buildPayload());
+
+    await expect(result).resolves.toBeUndefined();
+    expect(signalMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows a non-terminal signal failure', async () => {
+    const failure = new Error('temporal unavailable');
+    signalMock.mockRejectedValueOnce(failure);
+
+    const result = onJobStepsSettled(buildPayload());
+
+    await expect(result).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/on-job-steps-settled.ts

@@ -0,0 +1,42 @@
+import type {WorkflowsJobStepsSettledEventDto} from '@shipfox/api-workflows-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
+import {JOB_FINISHED_SIGNAL} from '#temporal/constants.js';
+import {isWorkflowNotFound} from '#temporal/workflow-not-found.js';
+
+// Per-step execution finishes a job inside recordStepResult (no runner /complete
+// call), which enqueues WORKFLOWS_JOB_STEPS_SETTLED in the same transaction. The
+// persisted per-step projection is already terminal, so the workflow only flips
+// the job status — no steps are carried.
+export async function onJobStepsSettled(payload: WorkflowsJobStepsSettledEventDto): Promise<void> {
+  logger().info(
+    {
+      jobId: payload.jobId,
+      jobExecutionId: payload.jobExecutionId,
+      status: payload.status,
+    },
+    'Signaling job finished',
+  );
+  const handle = temporalClient().workflow.getHandle(`job:${payload.jobId}`);
+  try {
+    await handle.signal(JOB_FINISHED_SIGNAL, {
+      status: payload.status,
+      jobExecutionId: payload.jobExecutionId,
+    });
+  } catch (err) {
+    // Workflow already terminated (e.g. timeout path); its status is
+    // authoritative, drop this late event.
+    if (isWorkflowNotFound(err)) {
+      logger().debug(
+        {
+          jobId: payload.jobId,
+          jobExecutionId: payload.jobExecutionId,
+          status: payload.status,
+        },
+        'Job workflow already terminated; job-finished event discarded',
+      );
+      return;
+    }
+    throw err;
+  }
+}

package/src/presentation/subscribers/on-runner-job-claimed.test.ts

@@ -0,0 +1,57 @@
+import {getJobExecutionsByJobId, getJobsByWorkflowRunId} from '#db/index.js';
+import {workflowRunFactory} from '#test/index.js';
+import {onRunnerJobClaimed} from './on-runner-job-claimed.js';
+
+describe('onRunnerJobClaimed', () => {
+  it('stamps started_at on the job execution from the claim event payload', async () => {
+    const run = await workflowRunFactory.create();
+    const job = (await getJobsByWorkflowRunId(run.id))[0];
+    expect(job).toBeDefined();
+    if (!job) return;
+    const jobExecution = (await getJobExecutionsByJobId(job.id))[0];
+    expect(jobExecution).toBeDefined();
+    if (!jobExecution) return;
+    const claimedAt = new Date('2026-06-22T10:05:00.000Z');
+
+    await onRunnerJobClaimed({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      claimedAt: claimedAt.toISOString(),
+    });
+
+    const after = (await getJobExecutionsByJobId(job.id))[0];
+    expect(after?.startedAt?.getTime()).toBe(claimedAt.getTime());
+  });
+
+  it('is idempotent: a redelivered event keeps the first started_at (coalesce)', async () => {
+    const run = await workflowRunFactory.create();
+    const job = (await getJobsByWorkflowRunId(run.id))[0];
+    expect(job).toBeDefined();
+    if (!job) return;
+    const jobExecution = (await getJobExecutionsByJobId(job.id))[0];
+    expect(jobExecution).toBeDefined();
+    if (!jobExecution) return;
+    const first = new Date('2026-06-22T10:05:00.000Z');
+    const second = new Date('2026-06-22T10:06:00.000Z');
+
+    await onRunnerJobClaimed({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      claimedAt: first.toISOString(),
+    });
+    await onRunnerJobClaimed({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      claimedAt: second.toISOString(),
+    });
+
+    const after = (await getJobExecutionsByJobId(job.id))[0];
+    expect(after?.startedAt?.getTime()).toBe(first.getTime());
+  });
+});

package/src/presentation/subscribers/on-runner-job-claimed.ts

@@ -0,0 +1,23 @@
+import type {RunnerJobClaimedEvent} from '@shipfox/api-runners-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {recordJobExecutionStartedAt} from '#db/index.js';
+
+// Anticorruption layer: the runner reports a `claimed` fact in its own lease-broker
+// language; the run lifecycle treats the claim as the job's start, so we project it onto
+// `started_at`. Use the runner-owned claim timestamp, not subscriber time; the DB
+// projection is first-write-wins so outbox replay cannot move the run boundary.
+export async function onRunnerJobClaimed(payload: RunnerJobClaimedEvent): Promise<void> {
+  logger().debug(
+    {
+      workflowRunId: payload.workflowRunId,
+      workflowRunAttemptId: payload.workflowRunAttemptId,
+      jobId: payload.jobId,
+      jobExecutionId: payload.jobExecutionId,
+    },
+    'Recording job execution started_at from claim',
+  );
+  await recordJobExecutionStartedAt({
+    jobExecutionId: payload.jobExecutionId,
+    startedAt: new Date(payload.claimedAt),
+  });
+}

package/src/presentation/subscribers/on-runner-job-lease-expired.test.ts

@@ -0,0 +1,73 @@
+import type {RunnerJobLeaseExpiredEvent} from '@shipfox/api-runners-dto';
+import {onRunnerJobLeaseExpired} from './on-runner-job-lease-expired.js';
+
+const signalMock = vi.fn();
+const getHandleMock = vi.fn(() => ({signal: signalMock}));
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({workflow: {getHandle: getHandleMock}}),
+}));
+
+function buildPayload(
+  overrides: Partial<RunnerJobLeaseExpiredEvent> = {},
+): RunnerJobLeaseExpiredEvent {
+  return {
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    jobId: crypto.randomUUID(),
+    jobExecutionId: crypto.randomUUID(),
+    ...overrides,
+  };
+}
+
+describe('onRunnerJobLeaseExpired', () => {
+  beforeEach(() => {
+    getHandleMock.mockClear();
+    signalMock.mockReset();
+    signalMock.mockResolvedValue(undefined);
+  });
+
+  it('signals the job workflow that its lease expired', async () => {
+    const payload = buildPayload();
+
+    await onRunnerJobLeaseExpired(payload);
+
+    expect(getHandleMock).toHaveBeenCalledWith(`job:${payload.jobId}`);
+    expect(signalMock).toHaveBeenCalledWith('job-lease-expired', {
+      jobExecutionId: payload.jobExecutionId,
+    });
+  });
+
+  it('routes a stale-attempt event only to the payload job workflow', async () => {
+    const previousAttemptJobId = crypto.randomUUID();
+    const payload = buildPayload({
+      jobId: previousAttemptJobId,
+      workflowRunAttemptId: crypto.randomUUID(),
+    });
+
+    await onRunnerJobLeaseExpired(payload);
+
+    expect(getHandleMock).toHaveBeenCalledTimes(1);
+    expect(getHandleMock).toHaveBeenCalledWith(`job:${previousAttemptJobId}`);
+  });
+
+  it('discards a late event when the job workflow already terminated', async () => {
+    const notFound = new Error('gone');
+    notFound.name = 'WorkflowNotFoundError';
+    signalMock.mockRejectedValueOnce(notFound);
+
+    const result = onRunnerJobLeaseExpired(buildPayload());
+
+    await expect(result).resolves.toBeUndefined();
+    expect(signalMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows a non-terminal signal failure', async () => {
+    const failure = new Error('temporal unavailable');
+    signalMock.mockRejectedValueOnce(failure);
+
+    const result = onRunnerJobLeaseExpired(buildPayload());
+
+    await expect(result).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/on-runner-job-lease-expired.ts

@@ -0,0 +1,36 @@
+import type {RunnerJobLeaseExpiredEvent} from '@shipfox/api-runners-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
+import {JOB_LEASE_EXPIRED_SIGNAL} from '#temporal/constants.js';
+import {isWorkflowNotFound} from '#temporal/workflow-not-found.js';
+
+// The stuck-job detector emits runners.job.lease_expired when a runner's heartbeat
+// goes stale. Wake the job workflow so it resolves the outcome from authoritative
+// server state (adopt the terminal status if the steps finished concurrently,
+// otherwise fail the job and cancel the remaining steps).
+export async function onRunnerJobLeaseExpired(payload: RunnerJobLeaseExpiredEvent): Promise<void> {
+  logger().info(
+    {
+      workflowRunId: payload.workflowRunId,
+      workflowRunAttemptId: payload.workflowRunAttemptId,
+      jobId: payload.jobId,
+      jobExecutionId: payload.jobExecutionId,
+    },
+    'Signaling job orchestration of lease expiry',
+  );
+  const handle = temporalClient().workflow.getHandle(`job:${payload.jobId}`);
+  try {
+    await handle.signal(JOB_LEASE_EXPIRED_SIGNAL, {jobExecutionId: payload.jobExecutionId});
+  } catch (err) {
+    // Workflow already terminated (it finished or hit the timeout backstop first);
+    // its status is authoritative, drop this late event.
+    if (isWorkflowNotFound(err)) {
+      logger().debug(
+        {jobId: payload.jobId, jobExecutionId: payload.jobExecutionId},
+        'Job workflow already terminated; lease-expired event discarded',
+      );
+      return;
+    }
+    throw err;
+  }
+}

package/src/presentation/subscribers/on-runner-job-queued.test.ts

@@ -0,0 +1,57 @@
+import {getJobExecutionsByJobId, getJobsByWorkflowRunId} from '#db/index.js';
+import {workflowRunFactory} from '#test/index.js';
+import {onRunnerJobQueued} from './on-runner-job-queued.js';
+
+describe('onRunnerJobQueued', () => {
+  it('stamps queued_at on the job execution from the event payload', async () => {
+    const run = await workflowRunFactory.create();
+    const job = (await getJobsByWorkflowRunId(run.id))[0];
+    expect(job).toBeDefined();
+    if (!job) return;
+    const jobExecution = (await getJobExecutionsByJobId(job.id))[0];
+    expect(jobExecution).toBeDefined();
+    if (!jobExecution) return;
+    const queuedAt = new Date('2026-06-22T10:00:00.000Z');
+
+    await onRunnerJobQueued({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      queuedAt: queuedAt.toISOString(),
+    });
+
+    const after = (await getJobExecutionsByJobId(job.id))[0];
+    expect(after?.queuedAt?.getTime()).toBe(queuedAt.getTime());
+  });
+
+  it('is idempotent: a redelivered event keeps the first queued_at (coalesce)', async () => {
+    const run = await workflowRunFactory.create();
+    const job = (await getJobsByWorkflowRunId(run.id))[0];
+    expect(job).toBeDefined();
+    if (!job) return;
+    const jobExecution = (await getJobExecutionsByJobId(job.id))[0];
+    expect(jobExecution).toBeDefined();
+    if (!jobExecution) return;
+    const first = new Date('2026-06-22T10:00:00.000Z');
+    const second = new Date('2026-06-22T11:00:00.000Z');
+
+    await onRunnerJobQueued({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      queuedAt: first.toISOString(),
+    });
+    await onRunnerJobQueued({
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId: job.id,
+      jobExecutionId: jobExecution.id,
+      queuedAt: second.toISOString(),
+    });
+
+    const after = (await getJobExecutionsByJobId(job.id))[0];
+    expect(after?.queuedAt?.getTime()).toBe(first.getTime());
+  });
+});

package/src/presentation/subscribers/on-runner-job-queued.ts

@@ -0,0 +1,23 @@
+import type {RunnerJobQueuedEvent} from '@shipfox/api-runners-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {recordJobExecutionQueuedAt} from '#db/index.js';
+
+// Anticorruption layer for the runner's `queued` fact. Here the two contexts happen to
+// share the word, so this is an identity mapping (unlike claimed → started_at). Use the
+// runner-owned queue timestamp, not subscriber time; the DB projection is first-write-wins
+// so outbox replay cannot move the queue boundary.
+export async function onRunnerJobQueued(payload: RunnerJobQueuedEvent): Promise<void> {
+  logger().debug(
+    {
+      workflowRunId: payload.workflowRunId,
+      workflowRunAttemptId: payload.workflowRunAttemptId,
+      jobId: payload.jobId,
+      jobExecutionId: payload.jobExecutionId,
+    },
+    'Recording job execution queued_at',
+  );
+  await recordJobExecutionQueuedAt({
+    jobExecutionId: payload.jobExecutionId,
+    queuedAt: new Date(payload.queuedAt),
+  });
+}

package/src/presentation/subscribers/on-workflow-run-attempt-created.test.ts

@@ -0,0 +1,69 @@
+import type {WorkflowsWorkflowRunAttemptCreatedEventDto} from '@shipfox/api-workflows-dto';
+import {onWorkflowRunAttemptCreated} from './on-workflow-run-attempt-created.js';
+
+const startMock = vi.fn();
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({workflow: {start: startMock}}),
+}));
+
+function buildPayload(
+  overrides: Partial<WorkflowsWorkflowRunAttemptCreatedEventDto> = {},
+): WorkflowsWorkflowRunAttemptCreatedEventDto {
+  return {
+    workflowRunId: crypto.randomUUID(),
+    workflowRunAttemptId: crypto.randomUUID(),
+    attempt: 1,
+    workspaceId: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    definitionId: crypto.randomUUID(),
+    ...overrides,
+  };
+}
+
+describe('onWorkflowRunAttemptCreated', () => {
+  beforeEach(() => {
+    startMock.mockReset();
+    startMock.mockResolvedValue({});
+  });
+
+  it('starts the run orchestration keyed on the attempt id', async () => {
+    const payload = buildPayload();
+
+    await onWorkflowRunAttemptCreated(payload);
+
+    expect(startMock).toHaveBeenCalledWith('runOrchestration', {
+      taskQueue: 'workflows-orchestrator',
+      workflowId: `workflow-run-attempt:${payload.workflowRunAttemptId}`,
+      workflowIdConflictPolicy: 'USE_EXISTING',
+      workflowIdReusePolicy: 'REJECT_DUPLICATE',
+      args: [
+        {
+          workflowRunId: payload.workflowRunId,
+          runAttemptId: payload.workflowRunAttemptId,
+          workspaceId: payload.workspaceId,
+        },
+      ],
+    });
+  });
+
+  it('swallows an already-started orchestration (outbox is at-least-once)', async () => {
+    const alreadyStarted = new Error('already started');
+    alreadyStarted.name = 'WorkflowExecutionAlreadyStartedError';
+    startMock.mockRejectedValueOnce(alreadyStarted);
+
+    const result = onWorkflowRunAttemptCreated(buildPayload());
+
+    await expect(result).resolves.toBeUndefined();
+    expect(startMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('rethrows any other start failure', async () => {
+    const failure = new Error('temporal unavailable');
+    startMock.mockRejectedValueOnce(failure);
+
+    const result = onWorkflowRunAttemptCreated(buildPayload());
+
+    await expect(result).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/on-workflow-run-attempt-created.ts

@@ -0,0 +1,40 @@
+import type {WorkflowsWorkflowRunAttemptCreatedEventDto} from '@shipfox/api-workflows-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
+import {WORKFLOWS_TASK_QUEUE} from '#temporal/constants.js';
+
+export async function onWorkflowRunAttemptCreated(
+  payload: WorkflowsWorkflowRunAttemptCreatedEventDto,
+): Promise<void> {
+  logger().info(
+    {workflowRunId: payload.workflowRunId, workflowRunAttemptId: payload.workflowRunAttemptId},
+    'Starting workflow run attempt orchestration',
+  );
+  try {
+    await temporalClient().workflow.start('runOrchestration', {
+      taskQueue: WORKFLOWS_TASK_QUEUE,
+      workflowId: `workflow-run-attempt:${payload.workflowRunAttemptId}`,
+      workflowIdConflictPolicy: 'USE_EXISTING',
+      workflowIdReusePolicy: 'REJECT_DUPLICATE',
+      args: [
+        {
+          workflowRunId: payload.workflowRunId,
+          runAttemptId: payload.workflowRunAttemptId,
+          workspaceId: payload.workspaceId,
+        },
+      ],
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'WorkflowExecutionAlreadyStartedError') {
+      logger().info(
+        {
+          workflowRunId: payload.workflowRunId,
+          workflowRunAttemptId: payload.workflowRunAttemptId,
+        },
+        'Orchestration already started, skipping',
+      );
+      return;
+    }
+    throw error;
+  }
+}