@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-api-routes.test.ts

@@ -0,0 +1,1615 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import express, { Express } from 'express';
+import { AddressInfo, Server } from 'net';
+import { classifyDockerFailure, decodeUtf8TailSafely, tailLogByLines } from './kaseki-api-routes';
+import { readArtifactContent } from './routes/artifact-routes';
+import { ResultCache } from './result-cache';
+import { createApiRouter } from './kaseki-api-routes';
+import { IdempotencyStore } from './idempotency-store';
+import { PreFlightValidator } from './pre-flight-validator';
+import {
+  createMockScheduler,
+  createTestConfig,
+  type TestScheduler,
+} from './test-utils';
+
+/**
+ * Complete test app setup for kaseki-api-routes testing.
+ * Returns { app, server, port, idempotencyStore, preFlightValidator }.
+ * Call server.close() in finally block to clean up.
+ *
+ * @param scheduler Mock scheduler (use createMockScheduler from test-utils)
+ * @param config Test config (use createTestConfig from test-utils)
+ * @returns Object with Express app, HTTP server, port number, and stores
+ */
+async function createTestApp(
+  scheduler: TestScheduler,
+  config: ReturnType<typeof createTestConfig>,
+): Promise<{
+  app: Express;
+  server: Server;
+  port: number;
+  idempotencyStore: IdempotencyStore;
+  preFlightValidator: PreFlightValidator;
+}> {
+  const idempotencyStore = new IdempotencyStore(config.resultsDir, 24);
+  const preFlightValidator = new PreFlightValidator();
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createApiRouter(scheduler as any, config, idempotencyStore, preFlightValidator));
+
+  const server = app.listen(0);
+  const port = (server.address() as AddressInfo).port;
+
+  return {
+    app,
+    server,
+    port,
+    idempotencyStore,
+    preFlightValidator,
+  };
+}
+
+/**
+ * Clean shutdown of server and idempotency store.
+ */
+async function cleanupTestApp(server: Server, idempotencyStore: IdempotencyStore): Promise<void> {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  await idempotencyStore.shutdown();
+}
+
+describe('kaseki-api-routes log truncation helpers', () => {
+  test('decodeUtf8TailSafely trims incomplete 2-byte sequence split at chunk boundary', () => {
+    const input = Buffer.concat([Buffer.from('cafe ', 'utf-8'), Buffer.from([0xc3])]);
+    expect(decodeUtf8TailSafely(input)).toBe('cafe ');
+  });
+
+  test('decodeUtf8TailSafely trims incomplete 3-byte sequence split at chunk boundary', () => {
+    const input = Buffer.concat([Buffer.from('prefix ', 'utf-8'), Buffer.from([0xe4, 0xbd])]);
+    expect(decodeUtf8TailSafely(input)).toBe('prefix ');
+  });
+
+  test('decodeUtf8TailSafely trims incomplete 4-byte sequence split at chunk boundary', () => {
+    const input = Buffer.concat([Buffer.from('emoji ', 'utf-8'), Buffer.from([0xf0, 0x9f, 0x98])]);
+    expect(decodeUtf8TailSafely(input)).toBe('emoji ');
+  });
+
+  test('decodeUtf8TailSafely keeps chunks that start with continuation bytes when tail is complete', () => {
+    const input = Buffer.concat([Buffer.from([0x98, 0x80]), Buffer.from('alpha 你好 😀 beta', 'utf-8')]);
+    expect(decodeUtf8TailSafely(input)).toBe('��alpha 你好 😀 beta');
+  });
+
+  test('decodeUtf8TailSafely keeps pure ASCII tails unchanged', () => {
+    const input = Buffer.from('line1\nline2\nASCII tail', 'utf-8');
+    expect(decodeUtf8TailSafely(input)).toBe('line1\nline2\nASCII tail');
+  });
+
+  test.each([
+    {
+      name: 'empty content',
+      content: '',
+      lineCount: 3,
+      expected: '',
+    },
+    {
+      name: 'exact boundary',
+      content: 'a\nb\nc',
+      lineCount: 3,
+      expected: 'a\nb\nc',
+    },
+    {
+      name: 'over-requested lines',
+      content: 'a\nb\nc',
+      lineCount: 10,
+      expected: 'a\nb\nc',
+    },
+    {
+      name: 'CRLF input',
+      content: 'a\r\nb\r\nc\r\nd',
+      lineCount: 2,
+      expected: 'c\nd',
+    },
+    {
+      name: 'trailing newline handling',
+      content: 'a\nb\nc\n',
+      lineCount: 2,
+      expected: 'c\n',
+    },
+  ])('tailLogByLines handles $name', ({ content, lineCount, expected }) => {
+    expect(tailLogByLines(content, lineCount)).toBe(expected);
+  });
+});
+
+describe('kaseki-api-routes artifact read behavior', () => {
+  let testDir: string;
+  let artifactPath: string;
+  let cache: ResultCache;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-test-'));
+    artifactPath = path.join(testDir, 'pi-summary.json');
+    cache = new ResultCache(10, 60_000);
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test('returns fresh artifact content for running jobs when file changes between reads', () => {
+    fs.writeFileSync(artifactPath, '{"version":1}');
+    const firstRead = readArtifactContent(artifactPath, 'running', cache);
+    expect(firstRead).toBe('{"version":1}');
+
+    fs.writeFileSync(artifactPath, '{"version":2}');
+    const secondRead = readArtifactContent(artifactPath, 'running', cache);
+    expect(secondRead).toBe('{"version":2}');
+  });
+});
+
+describe('kaseki-api-routes readiness and metrics endpoints', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-ready-metrics-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('GET /api/ready returns 200 when scheduler dependencies are ready', async () => {
+    const scheduler = createMockScheduler();
+    scheduler.getReadiness.mockReturnValue({ ready: true, reasons: [] });
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/ready`);
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as any;
+      expect(body.status).toBe('ready');
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+
+  test('GET /api/ready returns 503 with machine-readable reasons when not ready', async () => {
+    const scheduler = createMockScheduler();
+    scheduler.getReadiness.mockReturnValue({ ready: false, reasons: ['results_dir_unwritable:EACCES'] });
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/ready`);
+      expect(res.status).toBe(503);
+      const body = (await res.json()) as any;
+      expect(body.status).toBe('not_ready');
+      expect(body.reasons).toContain('results_dir_unwritable:EACCES');
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+
+  test('GET /api/metrics returns prometheus content type and expected metric keys', async () => {
+    const scheduler = createMockScheduler();
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/metrics`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(res.status).toBe(200);
+      expect(res.headers.get('content-type')).toContain('text/plain');
+      const body = await res.text();
+      expect(body).toContain('kaseki_queue_pending');
+      expect(body).toContain('kaseki_runs_total');
+      expect(body).toContain('kaseki_run_duration_seconds');
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+});
+
+describe('kaseki-api-routes preflight diagnostics', () => {
+  const githubEnvKeys = [
+    'GITHUB_APP_ID',
+    'GITHUB_APP_ID_FILE',
+    'GITHUB_APP_CLIENT_ID',
+    'GITHUB_APP_CLIENT_ID_FILE',
+    'GITHUB_APP_PRIVATE_KEY',
+    'GITHUB_APP_PRIVATE_KEY_FILE',
+    'OPENROUTER_API_KEY',
+  ];
+
+  function restoreEnv(snapshot: Record<string, string | undefined>): void {
+    for (const key of githubEnvKeys) {
+      const value = snapshot[key];
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  }
+
+  test('classifies Docker socket permission failures with actionable remediation', () => {
+    const result = classifyDockerFailure(
+      'permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock'
+    );
+
+    expect(result.detail).toMatch(/socket is not accessible/);
+    expect(result.remediation).toMatch(/group_add/);
+  });
+
+  test('classifies unreachable Docker daemon separately from image misses', () => {
+    const result = classifyDockerFailure('Cannot connect to the Docker daemon at unix:///var/run/docker.sock');
+
+    expect(result.detail).toMatch(/unreachable/);
+    expect(result.remediation).toMatch(/daemon/);
+  });
+
+  test('GET /api/preflight reports readable GitHub App file credentials', async () => {
+    const snapshot = Object.fromEntries(githubEnvKeys.map((key) => [key, process.env[key]]));
+    const resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-preflight-github-'));
+    const secretsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-preflight-secrets-'));
+    const appIdFile = path.join(secretsDir, 'github_app_id');
+    const clientIdFile = path.join(secretsDir, 'github_client_id');
+    const keyFile = path.join(secretsDir, 'github_app_private_key');
+    fs.writeFileSync(appIdFile, '12345\n');
+    fs.writeFileSync(clientIdFile, 'Iv123client\n');
+    fs.writeFileSync(keyFile, '-----BEGIN RSA PRIVATE KEY-----\nabc\n-----END RSA PRIVATE KEY-----\n');
+    process.env.OPENROUTER_API_KEY = 'test-openrouter-key';
+    delete process.env.GITHUB_APP_ID;
+    delete process.env.GITHUB_APP_CLIENT_ID;
+    delete process.env.GITHUB_APP_PRIVATE_KEY;
+    process.env.GITHUB_APP_ID_FILE = appIdFile;
+    process.env.GITHUB_APP_CLIENT_ID_FILE = clientIdFile;
+    process.env.GITHUB_APP_PRIVATE_KEY_FILE = keyFile;
+
+    const scheduler = createMockScheduler();
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/preflight`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect([200, 503]).toContain(res.status);
+      const body = (await res.json()) as any;
+      const githubCheck = body.checks.find((check: any) => check.name === 'github-app');
+      expect(githubCheck).toEqual(expect.objectContaining({
+        ok: true,
+        detail: expect.stringContaining('GitHub App credentials are readable'),
+      }));
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+      fs.rmSync(resultsDir, { recursive: true, force: true });
+      fs.rmSync(secretsDir, { recursive: true, force: true });
+      restoreEnv(snapshot);
+    }
+  });
+
+  test('GET /api/preflight flags incomplete GitHub App configuration', async () => {
+    const snapshot = Object.fromEntries(githubEnvKeys.map((key) => [key, process.env[key]]));
+    const resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-preflight-github-missing-'));
+    process.env.OPENROUTER_API_KEY = 'test-openrouter-key';
+    process.env.GITHUB_APP_ID = '12345';
+    delete process.env.GITHUB_APP_ID_FILE;
+    delete process.env.GITHUB_APP_CLIENT_ID;
+    delete process.env.GITHUB_APP_CLIENT_ID_FILE;
+    delete process.env.GITHUB_APP_PRIVATE_KEY;
+    delete process.env.GITHUB_APP_PRIVATE_KEY_FILE;
+
+    const scheduler = createMockScheduler();
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/preflight`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect([200, 503]).toContain(res.status);
+      const body = (await res.json()) as any;
+      const githubCheck = body.checks.find((check: any) => check.name === 'github-app');
+      expect(githubCheck).toEqual(expect.objectContaining({
+        ok: false,
+        detail: expect.stringContaining('GitHub App credentials are incomplete'),
+      }));
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+      fs.rmSync(resultsDir, { recursive: true, force: true });
+      restoreEnv(snapshot);
+    }
+  });
+});
+
+describe('kaseki-api-routes tail file descriptor cleanup', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.dontMock('fs');
+  });
+
+  test('closes file descriptor when readSync throws', () => {
+    const closeSyncMock = jest.fn();
+
+    jest.isolateModules(() => {
+      jest.doMock('fs', () => ({
+        ...jest.requireActual('fs'),
+        openSync: jest.fn(() => 42),
+        readSync: jest.fn(() => {
+          throw new Error('read failed');
+        }),
+        closeSync: closeSyncMock,
+      }));
+
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { readTailBytes } = require('./kaseki-api-routes') as typeof import('./kaseki-api-routes');
+      expect(() => readTailBytes('/tmp/fake.log', 200, 100)).toThrow('read failed');
+    });
+
+    expect(closeSyncMock).toHaveBeenCalledWith(42);
+  });
+});
+
+describe('kaseki-api-routes results artifacts endpoint', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-api-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('failed run can retrieve failure diagnostics artifacts', async () => {
+    const jobId = 'kaseki-failed-1';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'failure.json'), JSON.stringify({ failureClass: 'validation' }));
+    fs.writeFileSync(path.join(jobDir, 'stderr.log'), 'stderr output');
+    fs.writeFileSync(path.join(jobDir, 'stdout.log'), 'stdout output');
+
+    const scheduler = createMockScheduler({
+      [jobId]: { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir },
+    });
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+    const headers = { Authorization: 'Bearer test-key' };
+
+    try {
+      const failureRes = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/failure.json`, { headers });
+      expect(failureRes.status).toBe(200);
+      const failureBody = (await failureRes.json()) as any;
+      expect(failureBody.file).toBe('failure.json');
+      expect(failureBody.contentType).toBe('application/json');
+
+      const stderrRes = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/stderr.log`, { headers });
+      expect(stderrRes.status).toBe(200);
+      const stderrBody = (await stderrRes.json()) as any;
+      expect(stderrBody.file).toBe('stderr.log');
+      expect(stderrBody.contentType).toBe('text/plain');
+      expect(stderrBody.content).toBe('stderr output');
+
+      const stdoutRes = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/stdout.log`, { headers });
+      expect(stdoutRes.status).toBe(200);
+      const stdoutBody = (await stdoutRes.json()) as any;
+      expect(stdoutBody.file).toBe('stdout.log');
+      expect(stdoutBody.content).toBe('stdout output');
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+
+  test('non-failed run is blocked from retrieving failure diagnostics artifacts', async () => {
+    const jobId = 'kaseki-running-1';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'failure.json'), JSON.stringify({ failureClass: 'validation' }));
+
+    const scheduler = createMockScheduler({
+      [jobId]: { id: jobId, status: 'running' as const, createdAt: new Date(), resultDir: jobDir },
+    });
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+    const headers = { Authorization: 'Bearer test-key' };
+
+    try {
+      const failureRes = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/failure.json`, { headers });
+      expect(failureRes.status).toBe(400);
+      const failureBody = (await failureRes.json()) as any;
+      expect(failureBody.title).toBe('Bad Request');
+      expect(failureBody.status).toBe(400);
+      expect(failureBody.detail).toContain('Artifact only available for failed runs: failure.json');
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+});
+
+describe('kaseki-api-routes run artifacts inventory endpoint', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-artifacts-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('failed run reports partial artifacts with failure-triage recommendations', async () => {
+    const jobId = 'kaseki-failed-artifacts';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'failure.json'), JSON.stringify({ failureClass: 'validation' }));
+    fs.writeFileSync(path.join(jobDir, 'stderr.log'), 'stderr output');
+    fs.writeFileSync(path.join(jobDir, 'result-summary.md'), '# summary');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId
+          ? { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir, exitCode: 1 }
+          : undefined,
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/artifacts`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.runStatus).toBe('failed');
+      expect(body.exitCode).toBe(1);
+      expect(body.recommended).toContain('failure.json');
+      expect(body.recommended).toContain('stderr.log');
+      const failureFile = body.artifacts.find((artifact: any) => artifact.name === 'failure.json');
+      const missingFile = body.artifacts.find((artifact: any) => artifact.name === 'stdout.log');
+      expect(failureFile.available).toBe(true);
+      expect(missingFile.available).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('running run does not expose failure-only artifacts as available', async () => {
+    const jobId = 'kaseki-running-artifacts';
+    const fallbackDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(fallbackDir, { recursive: true });
+    fs.writeFileSync(path.join(fallbackDir, 'result-summary.md'), '# running summary');
+    fs.writeFileSync(path.join(fallbackDir, 'stderr.log'), 'not yet final');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'running', createdAt: new Date() } : undefined),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/artifacts`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.runStatus).toBe('running');
+      expect(body.recommended).toContain('result-summary.md');
+      const stderrFile = body.artifacts.find((artifact: any) => artifact.name === 'stderr.log');
+      const summaryFile = body.artifacts.find((artifact: any) => artifact.name === 'result-summary.md');
+      expect(stderrFile.available).toBe(false);
+      expect(summaryFile.available).toBe(true);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('returns 404 when run does not exist', async () => {
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: () => undefined,
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir: fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-notfound-test-')),
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(config.resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/missing-run/artifacts`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(404);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+});
+
+describe('kaseki-api-routes logs endpoint stderr fallback', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-logs-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('failed run with missing stderr returns synthetic fallback payload', async () => {
+    const jobId = 'kaseki-failed-missing-stderr';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId
+          ? {
+            id: jobId,
+            status: 'failed',
+            createdAt: new Date(),
+            resultDir: jobDir,
+            exitCode: 17,
+            failureClass: 'validator_error',
+            error: 'Validation step crashed',
+          }
+          : undefined,
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/logs/stderr`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.logType).toBe('stderr');
+      expect(body.content).toContain(`job id: ${jobId}`);
+      expect(body.content).toContain('exit code: 17');
+      expect(body.content).toContain('failure class: validator_error');
+      expect(body.content).toContain('job.error: Validation step crashed');
+      expect(body.content).toContain('canonical stderr.log was not generated');
+      expect(body.size).toBeGreaterThan(0);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('non-failed run with missing stderr remains 404', async () => {
+    const jobId = 'kaseki-running-missing-stderr';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId
+          ? {
+            id: jobId,
+            status: 'running',
+            createdAt: new Date(),
+            resultDir: jobDir,
+          }
+          : undefined,
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/logs/stderr`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(404);
+      const body = (await response.json()) as any;
+      expect(body.detail).toContain('Log file not found: stderr');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+});
+
+describe('kaseki-api-routes controller replay and events', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-controller-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('idempotency replay returns the current job status instead of the original queued response', async () => {
+    const job = {
+      id: 'kaseki-99',
+      status: 'queued',
+      createdAt: new Date(),
+      resultDir: path.join(resultsDir, 'kaseki-99'),
+      correlationId: '11111111-1111-4111-8111-111111111111',
+      requestId: '22222222-2222-4222-8222-222222222222',
+    } as any;
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 1, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === job.id ? job : undefined),
+      submitJob: jest.fn(() => job),
+      listJobs: () => [job],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    const headers = { Authorization: 'Bearer test-key', 'Content-Type': 'application/json' };
+    const body = JSON.stringify({
+      repoUrl: 'https://github.com/org/repo',
+      ref: 'main',
+      idempotencyKey: '33333333-3333-4333-8333-333333333333',
+    });
+
+    try {
+      const first = await fetch(`http://127.0.0.1:${port}/api/runs`, { method: 'POST', headers, body });
+      expect(first.status).toBe(202);
+
+      job.status = 'failed';
+      job.completedAt = new Date();
+      job.exitCode = 143;
+      job.failureClass = 'cancelled';
+      job.error = 'Job cancelled by API request';
+
+      const replay = await fetch(`http://127.0.0.1:${port}/api/runs`, { method: 'POST', headers, body });
+      expect(replay.status).toBe(200);
+      const replayBody = (await replay.json()) as any;
+      expect(replayBody).toMatchObject({
+        id: job.id,
+        status: 'failed',
+        cached: true,
+        exitCode: 143,
+        failureClass: 'cancelled',
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('events endpoint falls back to live docker progress for active runs', async () => {
+    const jobId = 'kaseki-live-events';
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'running', createdAt: new Date() } : undefined),
+      getLiveProgressEvents: jest.fn(() => [{ source: 'docker-logs', stage: 'startup check', message: 'container booted' }]),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/events`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.sources).toEqual(['docker-logs']);
+      expect(body.events[0]).toMatchObject({ stage: 'startup check', message: 'container booted' });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('artifact listing treats zero-byte diagnostics as unavailable', async () => {
+    const jobId = 'kaseki-zero-artifacts';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'failure.json'), '');
+    fs.writeFileSync(path.join(jobDir, 'stderr.log'), 'stderr');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir } : undefined),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/artifacts`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      const failureFile = body.artifacts.find((artifact: any) => artifact.name === 'failure.json');
+      const stderrFile = body.artifacts.find((artifact: any) => artifact.name === 'stderr.log');
+      expect(failureFile.available).toBe(false);
+      expect(stderrFile.available).toBe(true);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+});
+
+describe('kaseki-api-routes status artifact hints', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-status-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('failed run reports deterministic artifact availability and prefers failure.json as diagnostic entrypoint', async () => {
+    const jobId = 'kaseki-failed-status-1';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'metadata.json'), '{"id":"meta"}');
+    fs.writeFileSync(path.join(jobDir, 'failure.json'), '{"failureClass":"validation"}');
+    fs.writeFileSync(path.join(jobDir, 'stderr.log'), 'stderr');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId
+          ? { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir, exitCode: 1 }
+          : undefined,
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.status).toBe('failed');
+      expect(body.artifacts).toEqual({
+        metadataJson: true,
+        analysisMd: false,
+        resultSummaryMd: false,
+        failureJson: true,
+        stderrLog: true,
+        availableFiles: ['metadata.json', 'failure.json', 'stderr.log'],
+      });
+      expect(body.diagnosticEntryPoint).toBe('failure.json');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('runs list includes terminal exit code from result metadata when scheduler job lacks it', async () => {
+    const jobId = 'kaseki-list-exit-code';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'metadata.json'), '{"exit_code":127}');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: jest.fn(),
+      submitJob: jest.fn(),
+      listJobs: () => [{ id: jobId, status: 'failed', createdAt: new Date('2026-05-07T12:00:00Z'), resultDir: jobDir }],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.runs[0]).toMatchObject({
+        id: jobId,
+        status: 'failed',
+        exitCode: 127,
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('failed run falls back to result-summary.md diagnostic entrypoint when failure.json is missing', async () => {
+    const jobId = 'kaseki-failed-status-2';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'result-summary.md'), '# summary');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir } : undefined),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.artifacts).toEqual({
+        metadataJson: false,
+        analysisMd: false,
+        resultSummaryMd: true,
+        failureJson: false,
+        stderrLog: false,
+        availableFiles: ['result-summary.md'],
+      });
+      expect(body.diagnosticEntryPoint).toBe('result-summary.md');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('failed run prefers analysis.md diagnostic entrypoint when failure.json is missing', async () => {
+    const jobId = 'kaseki-failed-status-analysis';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'analysis.md'), '# analysis');
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'failed', createdAt: new Date(), resultDir: jobDir } : undefined),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+    const config = { port: 0, apiKeys: ['test-key'], resultsDir, maxConcurrentRuns: 1, defaultTaskMode: 'patch' as const, maxDiffBytes: 200000, agentTimeoutSeconds: 1200, logLevel: 'info' as const };
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, { headers: { Authorization: 'Bearer test-key' } });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.artifacts.analysisMd).toBe(true);
+      expect(body.diagnosticEntryPoint).toBe('analysis.md');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('running status returns structured progress from progress.jsonl', async () => {
+    const jobId = 'kaseki-running-status-progress-file';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(jobDir, 'progress.jsonl'),
+      `${JSON.stringify({ stage: 'pi coding agent', percentComplete: 42, timestamp: '2026-05-05T00:00:00.000Z' })}\n`
+    );
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId ? { id: jobId, status: 'running', createdAt: new Date(), resultDir: jobDir, startedAt: new Date() } : undefined,
+      getLiveProgressEvents: jest.fn(() => []),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.progress).toEqual({
+        stage: 'pi coding agent',
+        percentComplete: 42,
+        message: 'pi coding agent',
+        updatedAt: '2026-05-05T00:00:00.000Z',
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('running status falls back to live progress when progress.jsonl has no parseable final event', async () => {
+    const jobId = 'kaseki-running-status-progress-malformed-file';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'progress.jsonl'), `${JSON.stringify({ stage: 'older file event' })}\n{not-json}\n`);
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) =>
+        id === jobId ? { id: jobId, status: 'running', createdAt: new Date(), resultDir: jobDir, startedAt: new Date() } : undefined,
+      getLiveProgressEvents: jest.fn(() => [
+        { stage: 'live fallback', message: 'file tail was malformed', timestamp: '2026-05-05T00:00:01.000Z' },
+      ]),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.progress).toEqual({
+        stage: 'live fallback',
+        message: 'file tail was malformed',
+        updatedAt: '2026-05-05T00:00:01.000Z',
+      });
+      expect(scheduler.getLiveProgressEvents).toHaveBeenCalledWith(jobId, 1);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('running status returns structured progress from live docker fallback', async () => {
+    const jobId = 'kaseki-running-status-progress-live';
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 1, maxConcurrent: 1 }),
+      getJob: (id: string) => (id === jobId ? { id: jobId, status: 'running', createdAt: new Date(), startedAt: new Date() } : undefined),
+      getLiveProgressEvents: jest.fn(() => [{ stage: 'startup check', message: 'container booted', timestamp: '2026-05-05T00:00:02.000Z' }]),
+      submitJob: jest.fn(),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs/${jobId}/status`, {
+        headers: { Authorization: 'Bearer test-key' },
+      });
+      expect(response.status).toBe(200);
+      const body = (await response.json()) as any;
+      expect(body.progress).toEqual({
+        stage: 'startup check',
+        message: 'container booted',
+        updatedAt: '2026-05-05T00:00:02.000Z',
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+});
+
+describe('kaseki-api-routes idempotency concurrency', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-idem-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('parallel requests with same idempotency key create exactly one job', async () => {
+    let submitted = 0;
+    const submitJob = jest.fn((runRequest: any) => {
+      submitted += 1;
+      return {
+        id: `job-${submitted}`,
+        status: 'queued',
+        createdAt: new Date(),
+        resultDir: path.join(resultsDir, `job-${submitted}`),
+        requestId: runRequest.requestId,
+        correlationId: runRequest.correlationId,
+      };
+    });
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: jest.fn(),
+      submitJob,
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    const headers = { Authorization: 'Bearer test-key', 'Content-Type': 'application/json' };
+    const body = {
+      repoUrl: 'https://github.com/example/repo',
+      ref: 'main',
+      issueNumber: 123,
+      idempotencyKey: '11111111-1111-4111-8111-111111111111',
+    };
+
+    try {
+      const requests = Array.from({ length: 8 }, () =>
+        fetch(`http://127.0.0.1:${port}/api/runs`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+        })
+      );
+      const responses = await Promise.all(requests);
+      const payloads = await Promise.all(responses.map((r) => r.json() as Promise<any>));
+
+      expect(submitJob).toHaveBeenCalledTimes(1);
+      expect(responses.every((r) => r.status === 200 || r.status === 202)).toBe(true);
+      expect(new Set(payloads.map((p) => p.id)).size).toBe(1);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('health endpoint remains responsive while run submission is contended', async () => {
+    let resolveSubmission: any;
+    const submissionGate = new Promise<any>((resolve) => {
+      resolveSubmission = resolve;
+    });
+
+    const scheduler = {
+      getQueueStatus: () => ({ pending: 0, running: 0, maxConcurrent: 1 }),
+      getJob: jest.fn(),
+      submitJob: jest.fn(async () => submissionGate),
+      listJobs: () => [],
+      cancelJob: jest.fn(),
+    } as any;
+
+    const config = {
+      port: 0,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 1,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler, config, idempotencyStore, preFlightValidator));
+
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+
+    try {
+      const runPromise = fetch(`http://127.0.0.1:${port}/api/runs`, {
+        method: 'POST',
+        headers: { Authorization: 'Bearer test-key', 'Content-Type': 'application/json' },
+        body: JSON.stringify({ repoUrl: 'https://github.com/example/repo', ref: 'main' }),
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 20));
+
+      const healthResponse = await fetch(`http://127.0.0.1:${port}/api/health`);
+      expect(healthResponse.status).toBe(200);
+      const healthBody = (await healthResponse.json()) as any;
+      expect(healthBody.status).toBeDefined();
+
+      if (resolveSubmission) resolveSubmission({
+        id: 'job-1',
+        status: 'queued',
+        createdAt: new Date(),
+        resultDir: path.join(resultsDir, 'job-1'),
+        requestId: 'req-1',
+        correlationId: 'corr-1',
+      });
+
+      const runResponse = await runPromise;
+      expect(runResponse.status).toBe(202);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+});
+
+describe('kaseki-api-routes timeoutSeconds validation', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-timeout-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('rejects invalid timeoutSeconds with 400', async () => {
+    const scheduler = createMockScheduler();
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs`, {
+        method: 'POST',
+        headers: { Authorization: 'Bearer test-key', 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          repoUrl: 'https://github.com/example/repo',
+          ref: 'main',
+          timeoutSeconds: 10,
+        }),
+      });
+      expect(response.status).toBe(400);
+      const payload = (await response.json()) as any;
+      expect(payload.detail).toMatch(/timeoutSeconds/);
+      expect(scheduler.submitJob).not.toHaveBeenCalled();
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+    }
+  });
+});
+
+describe('kaseki-api-routes publish mode validation', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-publish-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('rejects draft PR publishing when GitHub App credentials are not configured', async () => {
+    const previousEnv = {
+      GITHUB_APP_ID: process.env.GITHUB_APP_ID,
+      GITHUB_APP_ID_FILE: process.env.GITHUB_APP_ID_FILE,
+      GITHUB_APP_CLIENT_ID: process.env.GITHUB_APP_CLIENT_ID,
+      GITHUB_APP_CLIENT_ID_FILE: process.env.GITHUB_APP_CLIENT_ID_FILE,
+      GITHUB_APP_PRIVATE_KEY: process.env.GITHUB_APP_PRIVATE_KEY,
+      GITHUB_APP_PRIVATE_KEY_FILE: process.env.GITHUB_APP_PRIVATE_KEY_FILE,
+    };
+    for (const key of Object.keys(previousEnv)) {
+      delete process.env[key];
+    }
+
+    const scheduler = createMockScheduler();
+    const config = createTestConfig(resultsDir);
+    const { server, port, idempotencyStore } = await createTestApp(scheduler, config);
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/runs`, {
+        method: 'POST',
+        headers: {
+          Authorization: 'Bearer test-key',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          repoUrl: 'https://github.com/org/repo',
+          publishMode: 'draft_pr',
+        }),
+      });
+
+      expect(response.status).toBe(400);
+      const body = (await response.json()) as any;
+      expect(body.detail).toContain('publishMode=draft_pr requires readable GitHub App credentials');
+      expect(scheduler.submitJob).not.toHaveBeenCalled();
+    } finally {
+      await cleanupTestApp(server, idempotencyStore);
+      for (const [key, value] of Object.entries(previousEnv)) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    }
+  });
+});
+
+describe('artifact content cache configuration in routes', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-routes-artifact-cache-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('uses the injected artifact cache and exposes its stats on metrics', async () => {
+    const jobId = 'kaseki-artifact-cache-stats';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'result-summary.md'), 'cached summary');
+
+    const scheduler = createMockScheduler({
+      [jobId]: {
+        id: jobId,
+        status: 'completed',
+        createdAt: new Date(),
+        resultDir: jobDir,
+      },
+    });
+    const config = {
+      ...createTestConfig(resultsDir),
+      artifactCacheMaxEntries: 1,
+      artifactCacheTtlMs: 60_000,
+      artifactCacheMaxFileBytes: 1024,
+    };
+    const artifactCache = new ResultCache({
+      maxEntries: config.artifactCacheMaxEntries,
+      ttlMs: config.artifactCacheTtlMs,
+      maxFileBytes: config.artifactCacheMaxFileBytes,
+    });
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler as any, config, idempotencyStore, preFlightValidator, artifactCache));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    const headers = { Authorization: 'Bearer test-key' };
+
+    try {
+      const first = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/result-summary.md`, { headers });
+      expect(first.status).toBe(200);
+      const second = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/result-summary.md`, { headers });
+      expect(second.status).toBe(200);
+
+      const metrics = await fetch(`http://127.0.0.1:${port}/api/metrics`, { headers });
+      expect(metrics.status).toBe(200);
+      const body = await metrics.text();
+      expect(body).toContain('kaseki_artifact_cache_entries 1');
+      expect(body).toContain('kaseki_artifact_cache_hits_total 1');
+      expect(body).toContain('kaseki_artifact_cache_misses_total 1');
+      expect(body).toContain('kaseki_artifact_cache_max_entries 1');
+      expect(body).toContain('kaseki_artifact_cache_max_file_bytes 1024');
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+
+  test('honors configured max file bytes passed through artifact routes', async () => {
+    const jobId = 'kaseki-artifact-cache-size-limit';
+    const jobDir = path.join(resultsDir, jobId);
+    fs.mkdirSync(jobDir, { recursive: true });
+    fs.writeFileSync(path.join(jobDir, 'result-summary.md'), 'too large for cache');
+
+    const scheduler = createMockScheduler({
+      [jobId]: {
+        id: jobId,
+        status: 'completed',
+        createdAt: new Date(),
+        resultDir: jobDir,
+      },
+    });
+    const config = {
+      ...createTestConfig(resultsDir),
+      artifactCacheMaxEntries: 3,
+      artifactCacheTtlMs: 60_000,
+      artifactCacheMaxFileBytes: 4,
+    };
+    const artifactCache = new ResultCache({
+      maxEntries: config.artifactCacheMaxEntries,
+      ttlMs: config.artifactCacheTtlMs,
+      maxFileBytes: config.artifactCacheMaxFileBytes,
+    });
+    const idempotencyStore = new IdempotencyStore(resultsDir, 24);
+    const preFlightValidator = new PreFlightValidator();
+    const app = express();
+    app.use(express.json());
+    app.use('/api', createApiRouter(scheduler as any, config, idempotencyStore, preFlightValidator, artifactCache));
+    const server = app.listen(0);
+    const port = (server.address() as AddressInfo).port;
+    const headers = { Authorization: 'Bearer test-key' };
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/api/results/${jobId}/result-summary.md`, { headers });
+      expect(response.status).toBe(200);
+      expect(artifactCache.getStats()).toMatchObject({ entries: 0, misses: 1, maxFileBytes: 4 });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await idempotencyStore.shutdown();
+    }
+  });
+});