@shipfox/api-workflows 12.2.0 → 12.3.0

package/src/db/workflow-runs/steps.ts

@@ -1,5 +1,5 @@
 import type {LogOutcomeDto} from '@shipfox/api-workflows-dto';
-import {and, asc, count, eq, gte, inArray, sql} from 'drizzle-orm';
+import {and, asc, count, desc, eq, gte, inArray, sql} from 'drizzle-orm';
 import type {
   PersistedEvaluationTraceEntry,
   Step,
@@ -11,8 +11,11 @@ import type {
 import {deriveCompletion, isTerminal} from '#core/step-transition/decide-step-transition.js';
 import {db, type Tx} from '../db.js';
 import {jobExecutions} from '../schema/job-executions.js';
+import {jobs} from '../schema/jobs.js';
 import {stepAttempts, toStepAttempt} from '../schema/step-attempts.js';
 import {steps, toStep} from '../schema/steps.js';
+import {workflowRunAttempts} from '../schema/workflow-run-attempts.js';
+import {workflowRuns} from '../schema/workflow-runs.js';
 import {writeJobStepsSettledOutbox, writeStepAttemptTerminatedOutbox} from './outbox.js';
 import {NON_TERMINAL_STEP_STATUS_FILTER} from './shared.js';
 
@@ -39,6 +42,105 @@ export async function getStepById(stepId: string): Promise<Step | undefined> {
   return toStep(row);
 }
 
+export interface StepAttemptDetail {
+  workflowRunId: string;
+  workflowRunAttemptId: string;
+  step: Step;
+  attempt: StepAttempt;
+}
+
+export interface JobExecutionFailureOrigin {
+  jobExecutionId: string;
+  stepId: string;
+  stepName: string;
+  stepStatus: StepStatus;
+  stepAttempt: number;
+  stepError: Record<string, unknown> | null;
+  attemptStatus: StepAttemptStatus | null;
+  attemptError: Record<string, unknown> | null;
+  attemptExitCode: number | null;
+}
+
+/**
+ * Read only the current attempt for the most relevant step. The terminal job event identifies
+ * the execution, so this intentionally avoids hydrating the execution's complete attempt
+ * history. If no attempt was dispatched, the first step still gives the projection a stable
+ * troubleshooting origin for failures that happened before step work started.
+ */
+export async function getJobExecutionFailureOrigin(
+  jobExecutionId: string,
+): Promise<JobExecutionFailureOrigin | undefined> {
+  const rows = await db()
+    .select({
+      jobExecutionId: jobExecutions.id,
+      stepId: steps.id,
+      stepName: steps.name,
+      stepStatus: steps.status,
+      stepAttempt: steps.currentAttempt,
+      stepError: steps.error,
+      attemptStatus: stepAttempts.status,
+      attemptError: stepAttempts.error,
+      attemptExitCode: stepAttempts.exitCode,
+    })
+    .from(jobExecutions)
+    .innerJoin(steps, eq(steps.jobExecutionId, jobExecutions.id))
+    .leftJoin(
+      stepAttempts,
+      and(eq(stepAttempts.stepId, steps.id), eq(stepAttempts.attempt, steps.currentAttempt)),
+    )
+    .where(eq(jobExecutions.id, jobExecutionId))
+    .orderBy(
+      desc(
+        sql<number>`case when ${steps.status} = 'failed' or ${stepAttempts.status} = 'failed' or ${steps.statusReason} = 'condition_errored' then 1 else 0 end`,
+      ),
+      asc(steps.position),
+      asc(steps.id),
+    )
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+
+  return {
+    ...row,
+    stepError: (row.stepError as Record<string, unknown> | null) ?? null,
+    attemptError: (row.attemptError as Record<string, unknown> | null) ?? null,
+    attemptStatus: row.attemptStatus === null ? null : (row.attemptStatus as StepAttemptStatus),
+    attemptExitCode: row.attemptExitCode ?? null,
+  };
+}
+
+export async function getStepAttemptDetail(params: {
+  stepId: string;
+  attempt: number;
+}): Promise<StepAttemptDetail | undefined> {
+  const rows = await db()
+    .select({
+      workflowRunId: workflowRuns.id,
+      workflowRunAttemptId: workflowRunAttempts.id,
+      step: steps,
+      stepAttempt: stepAttempts,
+    })
+    .from(stepAttempts)
+    .innerJoin(steps, eq(stepAttempts.stepId, steps.id))
+    .innerJoin(jobExecutions, eq(steps.jobExecutionId, jobExecutions.id))
+    .innerJoin(jobs, eq(jobExecutions.jobId, jobs.id))
+    .innerJoin(workflowRunAttempts, eq(jobs.workflowRunAttemptId, workflowRunAttempts.id))
+    .innerJoin(workflowRuns, eq(workflowRunAttempts.workflowRunId, workflowRuns.id))
+    .where(and(eq(stepAttempts.stepId, params.stepId), eq(stepAttempts.attempt, params.attempt)))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+
+  return {
+    workflowRunId: row.workflowRunId,
+    workflowRunAttemptId: row.workflowRunAttemptId,
+    step: toStep(row.step),
+    attempt: toStepAttempt(row.stepAttempt),
+  };
+}
+
 export async function getStepsByJobId(jobId: string): Promise<Step[]> {
   const rows = await db()
     .select({step: steps})
@@ -105,6 +207,7 @@ export async function bulkUpdateStepStatuses(
       await writeStepAttemptTerminatedOutbox(tx, {
         stepId: attempt.stepId,
         attempt: attempt.attempt,
+        status: params.status,
         logOutcome: attempt.logOutcome ?? 'abandoned',
       });
     }
@@ -367,6 +470,7 @@ export async function finishStepAttempt(params: FinishStepAttemptParams, tx: Tx)
   await writeStepAttemptTerminatedOutbox(tx, {
     stepId: row.stepId,
     attempt: row.attempt,
+    status: params.status,
     logOutcome: row.logOutcome ?? params.logOutcome,
   });
 }

package/src/db/workflow-runs.ts

@@ -90,9 +90,11 @@ export type {
   DispatchStepWithCompletedConfigParams,
   FinishStepAttemptParams,
   InsertRunningStepAttemptParams,
+  JobExecutionFailureOrigin,
   MarkStepRunningParams,
   MarkStepSkippedParams,
   RewindStepsToPendingParams,
+  StepAttemptDetail,
 } from './workflow-runs/steps.js';
 export {
   applyStepResult,
@@ -101,6 +103,8 @@ export {
   countStepAttempts,
   dispatchStepWithCompletedConfig,
   finishStepAttempt,
+  getJobExecutionFailureOrigin,
+  getStepAttemptDetail,
   getStepAttempts,
   getStepAttemptsByJobExecutionId,
   getStepAttemptsByJobIds,

package/src/index.ts

@@ -17,6 +17,8 @@ import type {SecretsInterModuleClient} from '@shipfox/api-secrets-dto/inter-modu
 import {
   WORKFLOWS_JOB_EVENT_DELIVERED,
   WORKFLOWS_JOB_STEPS_SETTLED,
+  WORKFLOWS_JOB_TERMINATED,
+  WORKFLOWS_STEP_ATTEMPT_TERMINATED,
   WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED,
   WORKFLOWS_WORKFLOW_RUN_CANCELLED,
   type WorkflowsEventMapDto,
@@ -30,9 +32,11 @@ import {
   createWorkflowRoutes,
   onJobEventDelivered,
   onJobStepsSettled,
+  onJobTerminatedFailureAnnotation,
   onRunnerJobClaimed,
   onRunnerJobLeaseExpired,
   onRunnerJobQueued,
+  onStepAttemptTerminatedFailureAnnotation,
   onWorkflowRunAttemptCreated,
   onWorkflowRunCancelled,
 } from '#presentation/index.js';
@@ -118,6 +122,11 @@ export function createWorkflowsModule({
       subscriber(WORKFLOWS_WORKFLOW_RUN_CANCELLED, onWorkflowRunCancelled),
       subscriber(WORKFLOWS_JOB_EVENT_DELIVERED, onJobEventDelivered),
       subscriber(WORKFLOWS_JOB_STEPS_SETTLED, onJobStepsSettled),
+      subscriber(
+        WORKFLOWS_STEP_ATTEMPT_TERMINATED,
+        onStepAttemptTerminatedFailureAnnotation(annotations),
+      ),
+      subscriber(WORKFLOWS_JOB_TERMINATED, onJobTerminatedFailureAnnotation(annotations)),
       subscriber(RUNNER_JOB_LEASE_EXPIRED, onRunnerJobLeaseExpired),
       subscriber(RUNNER_JOB_QUEUED, onRunnerJobQueued),
       subscriber(RUNNER_JOB_CLAIMED, onRunnerJobClaimed),

package/src/metrics/instance.ts

@@ -91,6 +91,12 @@ const agentToolWarningFailedCount = meter.createCounter<{
   description: 'Agent tool capability warning failures by bounded reason',
 });
 
+const failureAnnotationFailedCount = meter.createCounter<{
+  reason: 'lookup' | 'budget' | 'write';
+}>('workflows_failure_annotation_failed', {
+  description: 'Failure annotation projection failures by bounded reason',
+});
+
 const listenerEventsCoalesced = meter.createHistogram<Record<string, never>>(
   'workflows_listener_events_coalesced',
   {
@@ -172,3 +178,7 @@ export function recordListenerEventsCoalesced(batchSize: number): void {
 export function recordWorkflowAgentToolWarningFailed(reason: 'budget' | 'lookup' | 'write'): void {
   agentToolWarningFailedCount.add(1, {reason});
 }
+
+export function recordWorkflowFailureAnnotationFailed(reason: 'lookup' | 'budget' | 'write'): void {
+  failureAnnotationFailedCount.add(1, {reason});
+}

package/src/presentation/dto/evaluation-trace.ts

@@ -0,0 +1,27 @@
+import type {EvaluationTraceDto, EvaluationTraceEntryDto} from '@shipfox/api-workflows-dto';
+import type {PersistedEvaluationTraceEntry} from '#core/entities/step.js';
+
+export function toEvaluationTraceDto(
+  trace: readonly PersistedEvaluationTraceEntry[] | null | undefined,
+): EvaluationTraceDto | null {
+  if (trace === null || trace === undefined) return null;
+  return trace.map(toEvaluationTraceEntryDto);
+}
+
+function toEvaluationTraceEntryDto(entry: PersistedEvaluationTraceEntry): EvaluationTraceEntryDto {
+  if ('dropped' in entry) return {truncated: true, dropped: entry.dropped};
+
+  return {
+    expression: entry.expression,
+    roots: [...entry.roots],
+    fill_target: entry.fillTarget,
+    evaluated_at: entry.evaluatedAt,
+    field: entry.field,
+    ...(entry.value === undefined ? {} : {value: entry.value}),
+    ...(entry.truncated === undefined ? {} : {truncated: entry.truncated}),
+    ...(entry.exprTruncated === undefined ? {} : {expr_truncated: entry.exprTruncated}),
+    ...(entry.reference === undefined ? {} : {reference: entry.reference}),
+    ...(entry.degraded === undefined ? {} : {degraded: entry.degraded}),
+    ...(entry.envKey === undefined ? {} : {env_key: entry.envKey}),
+  };
+}

package/src/presentation/dto/index.ts

@@ -1,3 +1,4 @@
+export {toEvaluationTraceDto} from './evaluation-trace.js';
 export {toJobDto, toJobExecutionDto} from './job.js';
-export {toStepAttemptDto, toStepDto} from './step.js';
+export {toStepAttemptDetailResponseDto, toStepAttemptDto, toStepDto} from './step.js';
 export {toRunAttemptDto, toRunDto, toRunListItemDto} from './workflow-run.js';

package/src/presentation/dto/job.ts

@@ -1,6 +1,7 @@
 import type {JobDto, JobExecutionDto} from '@shipfox/api-workflows-dto';
 import type {Job} from '#core/entities/job.js';
 import type {JobExecution} from '#core/entities/job-execution.js';
+import {toEvaluationTraceDto} from './evaluation-trace.js';
 
 export function toJobDto(job: Job): JobDto {
   return {
@@ -12,6 +13,9 @@ export function toJobDto(job: Job): JobDto {
     status: job.status,
     status_reason: job.statusReason,
     carried_over: job.carriedOver,
+    success: job.success ?? null,
+    runner: job.runner,
+    evaluation_trace: toEvaluationTraceDto(job.evaluationTrace),
     listening:
       job.listeningOn === null
         ? null
@@ -52,8 +56,10 @@ export function toJobExecutionDto(jobExecution: JobExecution): JobExecutionDto {
     name: jobExecution.name,
     status: jobExecution.status,
     status_reason: jobExecution.statusReason,
+    runner: jobExecution.runner,
     trigger_events: jobExecution.triggerEvents,
     outputs: jobExecution.outputs,
+    evaluation_trace: toEvaluationTraceDto(jobExecution.evaluationTrace),
     queued_at: jobExecution.queuedAt?.toISOString() ?? null,
     started_at: jobExecution.startedAt?.toISOString() ?? null,
     finished_at: jobExecution.finishedAt?.toISOString() ?? null,

package/src/presentation/dto/step.test.ts

@@ -1,5 +1,10 @@
 import type {Step, StepAttempt} from '#core/entities/step.js';
-import {fromStepErrorDto, toStepAttemptDto, toStepDto} from './step.js';
+import {
+  fromStepErrorDto,
+  toStepAttemptDetailResponseDto,
+  toStepAttemptDto,
+  toStepDto,
+} from './step.js';
 
 function step(overrides: Partial<Step> & {type: string}): Step {
   return {
@@ -102,6 +107,37 @@ describe('fromStepErrorDto', () => {
 });
 
 describe('toStepDto error category', () => {
+  it('surfaces status reasons and evaluation traces', () => {
+    const dto = toStepDto(
+      step({
+        type: 'run',
+        statusReason: 'condition_errored',
+        evaluationTrace: [
+          {
+            expression: 'inputs.environment',
+            roots: ['inputs.environment'],
+            fillTarget: 'step-dispatch',
+            evaluatedAt: 'step-dispatch',
+            field: 'condition',
+            value: 'production',
+          },
+        ],
+      }),
+    );
+
+    expect(dto.status_reason).toBe('condition_errored');
+    expect(dto.evaluation_trace).toEqual([
+      {
+        expression: 'inputs.environment',
+        roots: ['inputs.environment'],
+        fill_target: 'step-dispatch',
+        evaluated_at: 'step-dispatch',
+        field: 'condition',
+        value: 'production',
+      },
+    ]);
+  });
+
   it("derives category 'setup' for a setup step error and surfaces the reason", () => {
     const dto = toStepDto(
       step({type: 'setup', error: {message: 'mkdir denied', reason: 'workspace_prep_failed'}}),
@@ -222,6 +258,24 @@ const baseAttempt: StepAttempt = {
 };
 
 describe('toStepAttemptDto', () => {
+  it('keeps evaluation traces on the lazy detail response instead of run polling', () => {
+    const result = toStepAttemptDto({
+      ...baseAttempt,
+      evaluationTrace: [
+        {
+          expression: 'inputs.message',
+          roots: ['inputs.message'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          field: 'run',
+          value: 'hello',
+        },
+      ],
+    });
+
+    expect(result).not.toHaveProperty('evaluation_trace');
+  });
+
   it('maps passed gate payloads to typed gate results', () => {
     const attempt: StepAttempt = {
       ...baseAttempt,
@@ -337,3 +391,44 @@ describe('toStepAttemptDto', () => {
     });
   });
 });
+
+describe('toStepAttemptDetailResponseDto', () => {
+  it('returns authored config, resolved config, and attempt trace', () => {
+    const stepData = step({
+      type: 'run',
+      authoredConfig: {run: 'echo $' + '{{ inputs.message }}'},
+      config: {run: 'echo hello'},
+    });
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      config: {run: 'echo hello'},
+      evaluationTrace: [
+        {
+          expression: 'inputs.message',
+          roots: ['inputs.message'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          field: 'run',
+          value: 'hello',
+        },
+      ],
+    };
+
+    expect(toStepAttemptDetailResponseDto(stepData, attempt)).toEqual({
+      step_id: stepData.id,
+      attempt: 1,
+      authored_config: {run: 'echo $' + '{{ inputs.message }}'},
+      config: {run: 'echo hello'},
+      evaluation_trace: [
+        {
+          expression: 'inputs.message',
+          roots: ['inputs.message'],
+          fill_target: 'step-dispatch',
+          evaluated_at: 'step-dispatch',
+          field: 'run',
+          value: 'hello',
+        },
+      ],
+    });
+  });
+});

package/src/presentation/dto/step.ts

@@ -1,5 +1,6 @@
 import {
   agentConfigIssueSchema,
+  type StepAttemptDetailResponseDto,
   type StepAttemptDto,
   type StepDto,
   type StepErrorCategoryDto,
@@ -9,6 +10,7 @@ import {
 } from '@shipfox/api-workflows-dto';
 import type {Step, StepAttempt} from '#core/entities/step.js';
 import {GATE_EVALUATION_ERROR_REASON} from '#core/step-transition/evaluate-gate.js';
+import {toEvaluationTraceDto} from './evaluation-trace.js';
 
 // Domain `error` is loosely typed (jsonb), so narrow it to the fixed runner
 // contract rather than trusting whatever shape the row happens to hold. `category`
@@ -105,8 +107,10 @@ export function toStepDto(step: Step): StepDto {
     name: step.name,
     source_location: toStepSourceLocationDto(step.sourceLocation),
     status: step.status,
+    status_reason: step.statusReason,
     type: step.type,
     config: step.config,
+    evaluation_trace: toEvaluationTraceDto(step.evaluationTrace),
     error: toStepErrorDto(
       step.error,
       step.type === 'setup' || step.type === 'checkout' ? 'setup' : 'user',
@@ -146,3 +150,16 @@ export function toStepAttemptDto(attempt: StepAttempt): StepAttemptDto {
     finished_at: attempt.finishedAt ? attempt.finishedAt.toISOString() : null,
   };
 }
+
+export function toStepAttemptDetailResponseDto(
+  step: Step,
+  attempt: StepAttempt,
+): StepAttemptDetailResponseDto {
+  return {
+    step_id: step.id,
+    attempt: attempt.attempt,
+    authored_config: step.authoredConfig,
+    config: attempt.config,
+    evaluation_trace: toEvaluationTraceDto(attempt.evaluationTrace),
+  };
+}

package/src/presentation/index.ts

@@ -2,9 +2,11 @@ export {createWorkflowRoutes} from './routes/index.js';
 export {
   onJobEventDelivered,
   onJobStepsSettled,
+  onJobTerminatedFailureAnnotation,
   onRunnerJobClaimed,
   onRunnerJobLeaseExpired,
   onRunnerJobQueued,
+  onStepAttemptTerminatedFailureAnnotation,
   onWorkflowRunAttemptCreated,
   onWorkflowRunCancelled,
 } from './subscribers/index.js';

package/src/presentation/routes/get-step-attempt-detail.test.ts

@@ -0,0 +1,159 @@
+import {buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import {ClientError} from '@shipfox/node-fastify';
+import type {FastifyInstance} from 'fastify';
+import Fastify from 'fastify';
+import {serializerCompiler, validatorCompiler} from 'fastify-type-provider-zod';
+import type {Step, StepAttempt} from '#core/entities/step.js';
+import * as dbMocks from '#db/index.js';
+import {getStepAttemptDetailRoute} from './get-step-attempt-detail.js';
+
+vi.mock('#db/index.js', () => ({
+  getStepAttemptDetail: vi.fn(),
+  getWorkflowRunById: vi.fn(),
+}));
+
+const getProjectById = vi.fn();
+const projects = {getProjectById} as unknown as ProjectsModuleClient;
+const STEP_ID = crypto.randomUUID();
+const getStepAttemptDetail = vi.mocked(dbMocks.getStepAttemptDetail);
+const getWorkflowRunById = vi.mocked(dbMocks.getWorkflowRunById);
+
+describe('GET /api/workflows/runs/steps/:stepId/attempts/:attempt', () => {
+  let app: FastifyInstance;
+  let workspaceId: string;
+  const workflowRunId = crypto.randomUUID();
+  const projectId = crypto.randomUUID();
+
+  beforeAll(async () => {
+    app = Fastify();
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+    app.addHook('onRequest', (request, _reply, done) => {
+      setUserContext(
+        request,
+        buildUserContext({
+          userId: crypto.randomUUID(),
+          email: 'user@example.com',
+          memberships: [{workspaceId, role: 'admin', workspaceStatus: 'active'}],
+        }),
+      );
+      done();
+    });
+    app.get(
+      '/api/workflows/runs/steps/:stepId/attempts/:attempt',
+      getStepAttemptDetailRoute(projects),
+    );
+    await app.ready();
+  });
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    vi.clearAllMocks();
+    getProjectById.mockResolvedValue({
+      project: {id: projectId, workspaceId, name: 'Project'},
+    });
+    getWorkflowRunById.mockResolvedValue({projectId} as never);
+  });
+
+  it('returns the requested attempt detail for an accessible run', async () => {
+    const step = stepEntity();
+    const attempt = stepAttemptEntity();
+    getStepAttemptDetail.mockResolvedValue({
+      workflowRunId,
+      workflowRunAttemptId: crypto.randomUUID(),
+      step,
+      attempt,
+    });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/steps/${STEP_ID}/attempts/1`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({
+      step_id: STEP_ID,
+      attempt: 1,
+      authored_config: {run: 'pnpm test'},
+      config: {run: 'pnpm test'},
+    });
+    expect(getProjectById).toHaveBeenCalledWith({projectId});
+  });
+
+  it('returns 404 for a missing attempt', async () => {
+    getStepAttemptDetail.mockResolvedValue(undefined);
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/steps/${STEP_ID}/attempts/1`,
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(getProjectById).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 for an attempt in an inaccessible run', async () => {
+    getStepAttemptDetail.mockResolvedValue({
+      workflowRunId,
+      workflowRunAttemptId: crypto.randomUUID(),
+      step: stepEntity(),
+      attempt: stepAttemptEntity(),
+    });
+    getProjectById.mockRejectedValueOnce(new ClientError('Forbidden', 'forbidden', {status: 403}));
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs/steps/${STEP_ID}/attempts/1`,
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json().code).toBe('not-found');
+  });
+});
+
+function stepEntity(): Step {
+  return {
+    id: STEP_ID,
+    jobExecutionId: crypto.randomUUID(),
+    key: 'test',
+    name: 'Run tests',
+    sourceLocation: null,
+    status: 'failed',
+    statusReason: null,
+    evaluationTrace: null,
+    type: 'run',
+    config: {run: 'pnpm test'},
+    condition: null,
+    configPlan: null,
+    authoredConfig: {run: 'pnpm test'},
+    error: {reason: 'command_failed', message: 'Command failed'},
+    position: 1,
+    version: 1,
+    currentAttempt: 1,
+    createdAt: new Date('2026-08-05T12:00:00.000Z'),
+    updatedAt: new Date('2026-08-05T12:01:00.000Z'),
+  };
+}
+
+function stepAttemptEntity(): StepAttempt {
+  return {
+    id: crypto.randomUUID(),
+    stepId: STEP_ID,
+    attempt: 1,
+    executionOrder: 1,
+    status: 'failed',
+    config: {run: 'pnpm test'},
+    evaluationTrace: null,
+    output: {result: 'failed'},
+    response: null,
+    error: {reason: 'command_failed', message: 'Command failed'},
+    exitCode: 1,
+    gateResult: null,
+    restartFeedback: null,
+    logOutcome: 'drained',
+    startedAt: new Date('2026-08-05T12:00:00.000Z'),
+    finishedAt: new Date('2026-08-05T12:01:00.000Z'),
+    createdAt: new Date('2026-08-05T12:00:00.000Z'),
+  };
+}

package/src/presentation/routes/get-step-attempt-detail.ts

@@ -0,0 +1,33 @@
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import {stepAttemptDetailResponseSchema} from '@shipfox/api-workflows-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {getStepAttemptDetail} from '#db/index.js';
+import {toStepAttemptDetailResponseDto} from '#presentation/dto/step.js';
+import {requireAccessibleRun} from './require-accessible-run.js';
+
+export function getStepAttemptDetailRoute(projects: ProjectsModuleClient) {
+  return defineRoute({
+    method: 'GET',
+    path: '/steps/:stepId/attempts/:attempt',
+    description: 'Get troubleshooting details for one step attempt',
+    schema: {
+      params: z.object({
+        stepId: z.string().uuid(),
+        attempt: z.coerce.number().int().positive(),
+      }),
+      response: {
+        200: stepAttemptDetailResponseSchema,
+      },
+    },
+    handler: async (request) => {
+      const detail = await getStepAttemptDetail(request.params);
+      if (!detail) {
+        throw new ClientError('Step attempt not found', 'not-found', {status: 404});
+      }
+
+      await requireAccessibleRun({request, id: detail.workflowRunId, projects});
+      return toStepAttemptDetailResponseDto(detail.step, detail.attempt);
+    },
+  });
+}

package/src/presentation/routes/index.ts

@@ -13,6 +13,7 @@ import {cancelRunRoute} from './cancel-run.js';
 import {createCheckoutTokenRoute} from './checkout-token.js';
 import {getRunRoute} from './get-run.js';
 import {getRunAggregatesRoute} from './get-run-aggregates.js';
+import {getStepAttemptDetailRoute} from './get-step-attempt-detail.js';
 import {createGetStepSecretsRoute} from './get-step-secrets.js';
 import {listRunAttemptsRoute} from './list-run-attempts.js';
 import {listRunsRoute} from './list-runs.js';
@@ -62,6 +63,7 @@ export function createWorkflowRoutes(params: WorkflowRouteClients): RouteGroup[]
         getRunAggregatesRoute(params.projects),
         listRunAttemptsRoute(params.projects),
         getRunRoute(params.projects),
+        getStepAttemptDetailRoute(params.projects),
         cancelRunRoute(params.projects),
         rerunRunRoute(params.projects, params.workspaces),
       ],

package/src/presentation/subscribers/index.ts

@@ -1,3 +1,7 @@
+export {
+  onJobTerminatedFailureAnnotation,
+  onStepAttemptTerminatedFailureAnnotation,
+} from './on-failure-annotations.js';
 export {onJobEventDelivered} from './on-job-event-delivered.js';
 export {onJobStepsSettled} from './on-job-steps-settled.js';
 export {onRunnerJobClaimed} from './on-runner-job-claimed.js';