@shipfox/api-workflows-dto 10.0.0 → 12.1.0

package/dist/working-directory.d.ts

@@ -0,0 +1,9 @@
+export declare class InvalidWorkingDirectoryError extends Error {
+    constructor(value: unknown);
+}
+/**
+ * Checks the path shape shared by the server dispatch boundary and the runner.
+ * Filesystem containment is checked by the runner after resolving symlinks.
+ */
+export declare function assertWorkingDirectory(value: unknown): asserts value is string;
+//# sourceMappingURL=working-directory.d.ts.map

package/dist/working-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-directory.d.ts","sourceRoot":"","sources":["../src/working-directory.ts"],"names":[],"mappings":"AAGA,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,KAAK,EAAE,OAAO;CAM3B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAW9E"}

package/dist/working-directory.js

@@ -0,0 +1,23 @@
+const WINDOWS_ABSOLUTE_PATH = /^[A-Za-z]:[\\/]/;
+const PATH_SEPARATOR = /[\\/]/;
+export class InvalidWorkingDirectoryError extends Error {
+    constructor(value){
+        super(`Invalid working_directory ${JSON.stringify(value)}: it must be a relative path without '..' segments or absolute path syntax.`);
+        this.name = 'InvalidWorkingDirectoryError';
+    }
+}
+/**
+ * Checks the path shape shared by the server dispatch boundary and the runner.
+ * Filesystem containment is checked by the runner after resolving symlinks.
+ */ export function assertWorkingDirectory(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidWorkingDirectoryError(value);
+    }
+    const isAbsolute = value.startsWith('/') || value.startsWith('\\') || WINDOWS_ABSOLUTE_PATH.test(value);
+    const hasParentSegment = value.split(PATH_SEPARATOR).some((segment)=>segment === '..');
+    if (isAbsolute || hasParentSegment) {
+        throw new InvalidWorkingDirectoryError(value);
+    }
+}
+
+//# sourceMappingURL=working-directory.js.map

package/dist/working-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/working-directory.ts"],"sourcesContent":["const WINDOWS_ABSOLUTE_PATH = /^[A-Za-z]:[\\\\/]/;\nconst PATH_SEPARATOR = /[\\\\/]/;\n\nexport class InvalidWorkingDirectoryError extends Error {\n  constructor(value: unknown) {\n    super(\n      `Invalid working_directory ${JSON.stringify(value)}: it must be a relative path without '..' segments or absolute path syntax.`,\n    );\n    this.name = 'InvalidWorkingDirectoryError';\n  }\n}\n\n/**\n * Checks the path shape shared by the server dispatch boundary and the runner.\n * Filesystem containment is checked by the runner after resolving symlinks.\n */\nexport function assertWorkingDirectory(value: unknown): asserts value is string {\n  if (typeof value !== 'string' || value.length === 0) {\n    throw new InvalidWorkingDirectoryError(value);\n  }\n\n  const isAbsolute =\n    value.startsWith('/') || value.startsWith('\\\\') || WINDOWS_ABSOLUTE_PATH.test(value);\n  const hasParentSegment = value.split(PATH_SEPARATOR).some((segment) => segment === '..');\n  if (isAbsolute || hasParentSegment) {\n    throw new InvalidWorkingDirectoryError(value);\n  }\n}\n"],"names":["WINDOWS_ABSOLUTE_PATH","PATH_SEPARATOR","InvalidWorkingDirectoryError","Error","value","JSON","stringify","name","assertWorkingDirectory","length","isAbsolute","startsWith","test","hasParentSegment","split","some","segment"],"mappings":"AAAA,MAAMA,wBAAwB;AAC9B,MAAMC,iBAAiB;AAEvB,OAAO,MAAMC,qCAAqCC;IAChD,YAAYC,KAAc,CAAE;QAC1B,KAAK,CACH,CAAC,0BAA0B,EAAEC,KAAKC,SAAS,CAACF,OAAO,2EAA2E,CAAC;QAEjI,IAAI,CAACG,IAAI,GAAG;IACd;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,uBAAuBJ,KAAc;IACnD,IAAI,OAAOA,UAAU,YAAYA,MAAMK,MAAM,KAAK,GAAG;QACnD,MAAM,IAAIP,6BAA6BE;IACzC;IAEA,MAAMM,aACJN,MAAMO,UAAU,CAAC,QAAQP,MAAMO,UAAU,CAAC,SAASX,sBAAsBY,IAAI,CAACR;IAChF,MAAMS,mBAAmBT,MAAMU,KAAK,CAACb,gBAAgBc,IAAI,CAAC,CAACC,UAAYA,YAAY;IACnF,IAAIN,cAAcG,kBAAkB;QAClC,MAAM,IAAIX,6BAA6BE;IACzC;AACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows-dto",
   "license": "MIT",
-  "version": "10.0.0",
+  "version": "12.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,8 +23,8 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "10.0.0",
-    "@shipfox/inter-module": "0.2.2"
+    "@shipfox/api-agent-dto": "12.0.0",
+    "@shipfox/inter-module": "0.2.3"
   },
   "imports": {
     "#*": "./dist/*"

package/src/index.ts

@@ -4,10 +4,16 @@ export {
   agentConfigIssueSchema,
   agentRuntimeConfigQuerySchema,
   type CheckoutIntentDto,
+  type CheckoutResultDto,
   type CheckoutTokenAuthDto,
+  type CheckoutTokenParamsDto,
+  type CheckoutTokenQueryDto,
   type CheckoutTokenResponseDto,
   checkoutIntentSchema,
+  checkoutResultSchema,
   checkoutTokenAuthSchema,
+  checkoutTokenParamsSchema,
+  checkoutTokenQuerySchema,
   checkoutTokenResponseSchema,
   type JobDto,
   type JobExecutionDto,
@@ -79,6 +85,9 @@ export {
   workflowRunDtoSchema,
   workflowRunJobDetailDtoSchema,
   workflowRunJobExecutionDetailDtoSchema,
+  workflowRunJobStatusCountDtoSchema,
+  workflowRunJobSummaryDtoSchema,
+  workflowRunListItemSchema,
   workflowRunListQuerySchema,
   workflowRunListResponseSchema,
   workflowRunRerunModeSchema,
@@ -88,7 +97,13 @@ export {
 } from '#schemas/index.js';
 export {type StepSourceLocationDto, stepSourceLocationSchema} from '#schemas/step.js';
 export {
+  WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
+  type WorkflowRunJobStatusCountDto,
+  type WorkflowRunJobSummaryDto,
+  type WorkflowRunListItemDto,
+  type WorkflowRunTriggerReferenceDto,
   type WorkflowSourceSnapshotDto,
+  workflowRunTriggerReferenceSchema,
   workflowSourceSnapshotSchema,
 } from '#schemas/workflow-run.js';
 export {
@@ -128,3 +143,4 @@ export {
   workflowsWorkflowRunCancelledSchema,
   workflowsWorkflowRunTerminatedSchema,
 } from './events.js';
+export {assertWorkingDirectory, InvalidWorkingDirectoryError} from './working-directory.js';

package/src/inter-module.test.ts

@@ -13,6 +13,7 @@ describe('workflowsInterModuleContract', () => {
         deliveryId: 'delivery-1',
         data: {ref: 'refs/heads/main'},
       },
+      triggerConnectionId: '00000000-0000-4000-8000-000000000005',
       idempotencyKey: 'subscription-1:event-1',
     });
     const delivery = workflowsInterModuleContract.methods.deliverEventToJobListener.input.parse({
@@ -23,12 +24,28 @@ describe('workflowsInterModuleContract', () => {
       source: 'github',
       event: 'push',
       provider: 'github',
+      triggerConnectionId: '00000000-0000-4000-8000-000000000005',
       payload: {ref: 'refs/heads/main'},
       receivedAt: '2026-07-20T12:00:00.000Z',
     });
+    const reference =
+      workflowsInterModuleContract.methods.resolveWorkflowRunTriggerReference.input.parse({
+        workspaceId: '00000000-0000-4000-8000-000000000001',
+        triggerConnectionId: '00000000-0000-4000-8000-000000000005',
+        triggerPayload: {
+          provider: 'github',
+          source: 'github',
+          event: 'push',
+          deliveryId: 'delivery-1',
+          data: {ref: 'refs/heads/main'},
+        },
+      });
 
     expect(start.idempotencyKey).toBe('subscription-1:event-1');
+    expect(start.triggerConnectionId).toBe('00000000-0000-4000-8000-000000000005');
     expect(delivery.disposition).toBe('fire');
+    expect(reference.triggerConnectionId).toBe('00000000-0000-4000-8000-000000000005');
+    expect(delivery.triggerConnectionId).toBe('00000000-0000-4000-8000-000000000005');
   });
 
   test('accepts the minimal Logs and agent-tools query payloads', () => {

package/src/inter-module.ts

@@ -3,6 +3,13 @@ import {defineInterModuleContract, type InterModuleClient} from '@shipfox/inter-
 import {z} from 'zod';
 
 const idSchema = z.string().uuid();
+const workflowRunTriggerReferenceSchema = z.object({
+  project: z.object({id: idSchema}).nullable(),
+  repository: z.string().nullable(),
+  ref: z.string().nullable(),
+  commit: z.string().nullable(),
+  actor: z.string().nullable(),
+});
 const triggerPayloadSchema = z.union([
   z.object({
     provider: z.literal('manual').optional(),
@@ -32,11 +39,19 @@ const interpolationFieldSchema = z.enum([
   'agent.prompt',
   'agent.model',
   'agent.provider',
+  'agent.thinking',
   'job.runner',
   'job.outputs',
-  'job.name',
+  'job.execution_name',
+  'workflow.run_name',
   'step.name',
+  'step.working_directory',
   'step.feedback',
+  'checkout.project',
+  'checkout.connection',
+  'checkout.repository',
+  'checkout.ref',
+  'checkout.path',
 ]);
 
 /**
@@ -51,6 +66,7 @@ export const workflowsInterModuleContract = defineInterModuleContract({
         workspaceId: idSchema,
         projectId: idSchema,
         definitionId: idSchema,
+        triggerConnectionId: idSchema.optional(),
         triggerPayload: triggerPayloadSchema,
         inputs: z.record(z.string(), z.unknown()).optional(),
         idempotencyKey: z.string().min(1),
@@ -73,6 +89,14 @@ export const workflowsInterModuleContract = defineInterModuleContract({
         'invalid-job-runner-labels': z.object({labels: z.array(z.string())}),
       },
     },
+    resolveWorkflowRunTriggerReference: {
+      input: z.object({
+        workspaceId: idSchema,
+        triggerConnectionId: idSchema,
+        triggerPayload: triggerPayloadSchema,
+      }),
+      output: workflowRunTriggerReferenceSchema.nullable(),
+    },
     deliverEventToJobListener: {
       input: z.object({
         jobId: idSchema,
@@ -82,6 +106,8 @@ export const workflowsInterModuleContract = defineInterModuleContract({
         source: z.string().min(1),
         event: z.string().min(1),
         provider: z.string().min(1),
+        triggerConnectionId: idSchema.optional(),
+        triggerReference: workflowRunTriggerReferenceSchema.nullable().optional(),
         payload: z.unknown(),
         receivedAt: z.string().datetime(),
       }),

package/src/schemas/checkout-token.test.ts

@@ -1,8 +1,33 @@
-import {checkoutTokenResponseSchema} from './checkout-token.js';
+import {
+  checkoutTokenParamsSchema,
+  checkoutTokenQuerySchema,
+  checkoutTokenResponseSchema,
+} from './checkout-token.js';
+
+describe('checkout token request schemas', () => {
+  it('accepts a UUID step id', () => {
+    const stepId = crypto.randomUUID();
+
+    expect(checkoutTokenParamsSchema.parse({stepId})).toEqual({stepId});
+  });
+
+  it('rejects a non-UUID step id', () => {
+    expect(() => checkoutTokenParamsSchema.parse({stepId: 'step-1'})).toThrow();
+  });
+
+  it('coerces a positive integer attempt', () => {
+    expect(checkoutTokenQuerySchema.parse({attempt: '2'})).toEqual({attempt: 2});
+  });
+
+  it.each([0, -1, 'not-a-number'])('rejects invalid attempt %p', (attempt) => {
+    expect(() => checkoutTokenQuerySchema.parse({attempt})).toThrow();
+  });
+});
 
 const bearerResponse = {
   repository_url: 'https://github.com/acme/repo.git',
   ref: 'main',
+  fetch_depth: 1,
   auth: {
     kind: 'bearer',
     token: 'gh-token',
@@ -16,6 +41,7 @@ const bearerResponse = {
 const basicResponse = {
   repository_url: 'https://github.com/acme/repo.git',
   ref: 'main',
+  fetch_depth: 1,
   auth: {
     kind: 'basic',
     username: 'x-access-token',
@@ -55,7 +81,11 @@ describe('checkoutTokenResponseSchema', () => {
   });
 
   it('accepts a credential-free response with no auth (debug provider)', () => {
-    const input = {repository_url: 'https://github.com/acme/repo.git', ref: 'main'};
+    const input = {
+      repository_url: 'https://github.com/acme/repo.git',
+      ref: 'main',
+      fetch_depth: 1,
+    };
 
     const result = checkoutTokenResponseSchema.parse(input);
 
@@ -159,4 +189,16 @@ describe('checkoutTokenResponseSchema', () => {
 
     expect(parse).toThrow();
   });
+
+  it('accepts zero for a full-history fetch', () => {
+    const result = checkoutTokenResponseSchema.parse({...bearerResponse, fetch_depth: 0});
+
+    expect(result.fetch_depth).toBe(0);
+  });
+
+  it('rejects a negative fetch depth', () => {
+    const parse = () => checkoutTokenResponseSchema.parse({...bearerResponse, fetch_depth: -1});
+
+    expect(parse).toThrow();
+  });
 });

package/src/schemas/checkout-token.ts

@@ -33,9 +33,22 @@ export const checkoutTokenAuthSchema = z.discriminatedUnion('kind', [
 
 export type CheckoutTokenAuthDto = z.infer<typeof checkoutTokenAuthSchema>;
 
+export const checkoutTokenParamsSchema = z.object({
+  stepId: z.string().uuid(),
+});
+
+export type CheckoutTokenParamsDto = z.infer<typeof checkoutTokenParamsSchema>;
+
+export const checkoutTokenQuerySchema = z.object({
+  attempt: z.coerce.number().int().positive(),
+});
+
+export type CheckoutTokenQueryDto = z.infer<typeof checkoutTokenQuerySchema>;
+
 export const checkoutTokenResponseSchema = z.object({
   repository_url: z.string().min(1),
   ref: z.string().min(1),
+  fetch_depth: z.number().int().nonnegative(),
   git_author: checkoutGitAuthorSchema.optional(),
   // Optional: credential-free providers (e.g. the debug source control) return a
   // public clone URL with no auth material, so the runner clones without a token.

package/src/schemas/index.ts

@@ -5,8 +5,12 @@ export {
 export {type CheckoutIntentDto, checkoutIntentSchema} from './checkout.js';
 export {
   type CheckoutTokenAuthDto,
+  type CheckoutTokenParamsDto,
+  type CheckoutTokenQueryDto,
   type CheckoutTokenResponseDto,
   checkoutTokenAuthSchema,
+  checkoutTokenParamsSchema,
+  checkoutTokenQuerySchema,
   checkoutTokenResponseSchema,
 } from './checkout-token.js';
 export {
@@ -18,6 +22,8 @@ export {
   jobStatusSchema,
 } from './job.js';
 export {
+  type CheckoutResultDto,
+  checkoutResultSchema,
   type NextStepResponseDto,
   nextStepResponseSchema,
   type ReportStepBodyDto,
@@ -66,27 +72,36 @@ export {
 export {
   type RerunWorkflowRunBodyDto,
   rerunWorkflowRunBodySchema,
+  WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
   type WorkflowRunAggregatesQueryDto,
   type WorkflowRunAggregatesResponseDto,
   type WorkflowRunAttemptDto,
   type WorkflowRunAttemptsResponseDto,
   type WorkflowRunDto,
+  type WorkflowRunJobStatusCountDto,
+  type WorkflowRunJobSummaryDto,
+  type WorkflowRunListItemDto,
   type WorkflowRunListQueryDto,
   type WorkflowRunListResponseDto,
   type WorkflowRunRerunModeDto,
   type WorkflowRunResponseDto,
   type WorkflowRunStatusDto,
+  type WorkflowRunTriggerReferenceDto,
   type WorkflowSourceSnapshotDto,
   workflowRunAggregatesQuerySchema,
   workflowRunAggregatesResponseSchema,
   workflowRunAttemptDtoSchema,
   workflowRunAttemptsResponseSchema,
   workflowRunDtoSchema,
+  workflowRunJobStatusCountDtoSchema,
+  workflowRunJobSummaryDtoSchema,
+  workflowRunListItemSchema,
   workflowRunListQuerySchema,
   workflowRunListResponseSchema,
   workflowRunRerunModeSchema,
   workflowRunResponseSchema,
   workflowRunStatusSchema,
+  workflowRunTriggerReferenceSchema,
   workflowSourceSnapshotSchema,
 } from './workflow-run.js';
 export {

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

@@ -24,4 +24,19 @@ describe('reportStepBodySchema', () => {
 
     expect(result.success).toBe(false);
   });
+  it('accepts resolved checkout details as a dedicated report field', () => {
+    const parsed = reportStepBodySchema.parse({
+      status: 'succeeded',
+      attempt: 1,
+      exit_code: 0,
+      log_outcome: 'drained',
+      checkout: {
+        repository: 'https://github.com/acme/api.git',
+        ref: 'refs/pull/412/head',
+        commit: '9f2c000000000000000000000000000000000000',
+        path: '/runner/workspace/job-1',
+      },
+    });
+    expect(parsed.checkout?.ref).toBe('refs/pull/412/head');
+  });
 });

package/src/schemas/job-execution.ts

@@ -36,6 +36,16 @@ export const nextStepResponseSchema = z.discriminatedUnion('kind', [
 
 export type NextStepResponseDto = z.infer<typeof nextStepResponseSchema>;
 
+export const checkoutResultSchema = z
+  .object({
+    repository: z.string().min(1),
+    ref: z.string().min(1),
+    commit: z.string().min(1),
+    path: z.string().min(1),
+  })
+  .describe('Resolved repository checkout details reported by the runner.');
+export type CheckoutResultDto = z.infer<typeof checkoutResultSchema>;
+
 export const reportStepBodySchema = z
   .object({
     status: z.enum(['succeeded', 'failed']).describe('Final status reported for the step attempt.'),
@@ -65,6 +75,9 @@ export const reportStepBodySchema = z
       .describe(
         'Structured output captured for attempt history. Large textual logs are stored separately.',
       ),
+    checkout: checkoutResultSchema
+      .optional()
+      .describe('Resolved repository checkout details captured for attempt history.'),
     response: z
       .string()
       .max(STEP_RESPONSE_MAX_LENGTH)

package/src/schemas/job-listening.test.ts

@@ -31,6 +31,10 @@ describe('execution context schemas', () => {
       event: 'pull_request_review',
       delivery_id: 'delivery-1',
       received_at: '2026-06-25T00:00:00.000Z',
+      project: null,
+      repository: null,
+      ref: null,
+      commit: null,
       data: {body: 'LGTM'},
     };
 

package/src/schemas/job-listening.ts

@@ -33,6 +33,10 @@ export const workflowExecutionEventSchema = z.object({
   event: z.string(),
   delivery_id: z.string(),
   received_at: z.string(),
+  project: z.object({id: z.string().uuid()}).nullable(),
+  repository: z.string().nullable(),
+  ref: z.string().nullable(),
+  commit: z.string().nullable(),
   data: z.unknown(),
 });
 

package/src/schemas/step.test.ts

@@ -61,6 +61,18 @@ describe('stepErrorDtoSchema', () => {
     });
   });
 
+  it.each([
+    'checkout_path_invalid',
+    'checkout_destination_occupied',
+  ] as const)('accepts the runner checkout destination reason %s', (reason) => {
+    const result = stepErrorDtoSchema.parse({
+      message: 'Checkout destination policy rejected the step.',
+      reason,
+    });
+
+    expect(result?.reason).toBe(reason);
+  });
+
   it('rejects unknown agent config issues', () => {
     const result = stepErrorDtoSchema.safeParse({
       message: 'Model provider credentials are not configured',

package/src/schemas/step.ts

@@ -2,7 +2,7 @@ import {z} from 'zod';
 
 // Machine-readable cause of a step failure, for DB troubleshooting. The runner
 // reports it and the server stores it as-is. The `checkout_*`, `git_unavailable`,
-// `workspace_prep_failed`, and `setup_aborted` values cover setup-phase failures.
+// `workspace_prep_failed`, and `setup_aborted` values cover checkout/setup failures.
 // For agent steps the cause is split three ways: `agent_config_invalid` is a user-fixable
 // configuration error and carries an `agent_config_issue`; `agent_invocation_failed`
 // covers a provider/API failure once the configuration is valid; and
@@ -13,6 +13,8 @@ export const stepErrorReasonSchema = z.enum([
   'checkout_failed',
   'checkout_auth_failed',
   'checkout_unavailable',
+  'checkout_path_invalid',
+  'checkout_destination_occupied',
   'git_unavailable',
   'workspace_prep_failed',
   'setup_aborted',

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

@@ -1,10 +1,17 @@
-import {workflowRunDtoSchema, workflowSourceSnapshotSchema} from './workflow-run.js';
+import {
+  WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
+  workflowRunDtoSchema,
+  workflowRunListItemSchema,
+  workflowSourceSnapshotSchema,
+} from './workflow-run.js';
 
 const baseRun = {
   id: '11111111-1111-4111-8111-111111111111',
   project_id: '22222222-2222-4222-8222-222222222222',
   definition_id: '33333333-3333-4333-8333-333333333333',
+  number: 1,
   name: 'Build',
+  workflow_name: 'Build',
   status: 'pending',
   source_run_id: null,
   root_run_id: null,
@@ -16,6 +23,7 @@ const baseRun = {
   trigger_source: 'manual',
   trigger_event: 'fire',
   trigger_payload: {source: 'manual', event: 'fire'},
+  trigger_reference: null,
   inputs: null,
   created_at: '2026-06-16T00:00:00.000Z',
   updated_at: '2026-06-16T00:00:00.000Z',
@@ -46,6 +54,8 @@ describe('workflow source snapshot schemas', () => {
     const result = workflowRunDtoSchema.parse({...baseRun, source_snapshot: null});
 
     expect(result.source_snapshot).toBeNull();
+    expect(result.name).toBe('Build');
+    expect(result.workflow_name).toBe('Build');
   });
 
   test('accepts run DTOs with source snapshots', () => {
@@ -57,3 +67,98 @@ describe('workflow source snapshot schemas', () => {
     expect(result.source_snapshot).toEqual({content: 'name: Build\njobs: {}\n', format: 'yaml'});
   });
 });
+
+describe('workflow run trigger reference schema', () => {
+  test('accepts a partially resolved reference', () => {
+    const result = workflowRunDtoSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      trigger_reference: {
+        repository: 'acme/api',
+        ref: 'refs/heads/main',
+        commit: null,
+        actor: null,
+      },
+    });
+
+    expect(result.trigger_reference).toEqual({
+      repository: 'acme/api',
+      ref: 'refs/heads/main',
+      commit: null,
+      actor: null,
+    });
+  });
+
+  test('rejects a reference missing a field rather than defaulting it', () => {
+    const result = workflowRunDtoSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      trigger_reference: {repository: 'acme/api', ref: 'refs/heads/main', commit: null},
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('workflow run list item schema', () => {
+  function jobDto(position: number) {
+    return {
+      id: `44444444-4444-4444-8444-${String(position).padStart(12, '0')}`,
+      key: `job-${position}`,
+      name: null,
+      status: 'succeeded' as const,
+      position,
+    };
+  }
+
+  test('carries job status glyphs alongside the run', () => {
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [jobDto(0)],
+      job_status_counts: [{status: 'succeeded', count: 1}],
+    });
+
+    expect(result.jobs).toHaveLength(1);
+    expect(result.jobs[0]?.status).toBe('succeeded');
+  });
+
+  // The preview is a bounded slice, so counts describe jobs the payload never carried.
+  test('accepts counts larger than the preview it ships', () => {
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [jobDto(0)],
+      job_status_counts: [
+        {status: 'succeeded', count: 40},
+        {status: 'failed', count: 2},
+      ],
+    });
+
+    expect(result.job_status_counts).toHaveLength(2);
+  });
+
+  test('rejects a preview longer than the documented bound', () => {
+    const result = workflowRunListItemSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: Array.from({length: WORKFLOW_RUN_JOB_PREVIEW_LIMIT + 1}, (_, index) => jobDto(index)),
+      job_status_counts: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test.each([
+    ['a jobs array', {job_status_counts: []}],
+    ['job status counts', {jobs: []}],
+  ])('rejects a run list item without %s', (_missing, partial) => {
+    const result = workflowRunListItemSchema.safeParse({
+      ...baseRun,
+      source_snapshot: null,
+      ...partial,
+    });
+
+    expect(result.success).toBe(false);
+  });
+});