github-issue-tower-defence-management 1.109.2 → 1.110.1

package/src/adapter/repositories/ConfigurableSilentSessionMessageComposer.ts

@@ -0,0 +1,51 @@
+import { SubAgentActivity } from '../../domain/entities/LiveSessionActivitySnapshot';
+import { SilentSessionMessageComposer } from '../../domain/usecases/adapter-interfaces/SilentSessionMessageComposer';
+
+export type SilentSessionMessageTemplates = {
+  mainStalledMessage: string | null;
+  subAgentMessageHeader: string | null;
+  subAgentMessageFooter: string | null;
+};
+
+const formatMinutes = (seconds: number): string => {
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m`;
+};
+
+export class ConfigurableSilentSessionMessageComposer implements SilentSessionMessageComposer {
+  constructor(
+    private readonly templates: SilentSessionMessageTemplates,
+    private readonly fallback: SilentSessionMessageComposer,
+  ) {}
+
+  composeMainStalledSection = (mainSilentSeconds: number): string => {
+    if (this.templates.mainStalledMessage === null) {
+      return this.fallback.composeMainStalledSection(mainSilentSeconds);
+    }
+    return this.templates.mainStalledMessage;
+  };
+
+  composeSubAgentSection = (subAgents: SubAgentActivity[]): string => {
+    if (
+      this.templates.subAgentMessageHeader === null &&
+      this.templates.subAgentMessageFooter === null
+    ) {
+      return this.fallback.composeSubAgentSection(subAgents);
+    }
+    const lines = subAgents.map(
+      (subAgent) =>
+        `- ${subAgent.label}: silent for ${formatMinutes(
+          subAgent.silentSeconds,
+        )}, running for ${formatMinutes(subAgent.runningSeconds)}`,
+    );
+    const sections: string[] = [];
+    if (this.templates.subAgentMessageHeader !== null) {
+      sections.push(this.templates.subAgentMessageHeader);
+    }
+    sections.push(...lines);
+    if (this.templates.subAgentMessageFooter !== null) {
+      sections.push(this.templates.subAgentMessageFooter);
+    }
+    return sections.join('\n');
+  };
+}

package/src/adapter/repositories/FileSystemSessionOutputActivityRepository.test.ts

@@ -0,0 +1,92 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { FileSystemSessionOutputActivityRepository } from './FileSystemSessionOutputActivityRepository';
+
+describe('FileSystemSessionOutputActivityRepository', () => {
+  let rootDirectory: string;
+
+  beforeEach(() => {
+    rootDirectory = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'session-output-activity-'),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(rootDirectory, { force: true, recursive: true });
+  });
+
+  const writeOutputFileWithMtime = (
+    sessionName: string,
+    epochSeconds: number,
+  ): void => {
+    const fileName = sessionName.replace(/\//g, '_');
+    const filePath = path.join(rootDirectory, fileName);
+    fs.writeFileSync(filePath, 'output', 'utf8');
+    fs.utimesSync(filePath, epochSeconds, epochSeconds);
+  };
+
+  it('returns the latest output epoch derived from each session output file mtime', async () => {
+    const sessionName = 'https_//github_com/owner/repo/issues/9';
+    writeOutputFileWithMtime(sessionName, 1700000000);
+    const repository = new FileSystemSessionOutputActivityRepository(
+      rootDirectory,
+    );
+
+    const result = await repository.listSessionOutputActivities([sessionName]);
+
+    expect(result).toEqual([
+      { sessionName, lastOutputEpochSeconds: 1700000000 },
+    ]);
+  });
+
+  it('omits sessions that have no output file', async () => {
+    const presentSessionName = 'https_//github_com/owner/repo/issues/9';
+    const missingSessionName = 'https_//github_com/owner/repo/issues/10';
+    writeOutputFileWithMtime(presentSessionName, 1700000000);
+    const repository = new FileSystemSessionOutputActivityRepository(
+      rootDirectory,
+    );
+
+    const result = await repository.listSessionOutputActivities([
+      presentSessionName,
+      missingSessionName,
+    ]);
+
+    expect(result).toEqual([
+      { sessionName: presentSessionName, lastOutputEpochSeconds: 1700000000 },
+    ]);
+  });
+
+  it('returns an empty list when the root directory does not exist', async () => {
+    const repository = new FileSystemSessionOutputActivityRepository(
+      path.join(rootDirectory, 'does-not-exist'),
+    );
+
+    const result = await repository.listSessionOutputActivities([
+      'https_//github_com/owner/repo/issues/9',
+    ]);
+
+    expect(result).toEqual([]);
+  });
+
+  it('returns an empty list when the root directory is null', async () => {
+    const repository = new FileSystemSessionOutputActivityRepository(null);
+
+    const result = await repository.listSessionOutputActivities([
+      'https_//github_com/owner/repo/issues/9',
+    ]);
+
+    expect(result).toEqual([]);
+  });
+
+  it('returns an empty list when no session names are requested', async () => {
+    const repository = new FileSystemSessionOutputActivityRepository(
+      rootDirectory,
+    );
+
+    const result = await repository.listSessionOutputActivities([]);
+
+    expect(result).toEqual([]);
+  });
+});

package/src/adapter/repositories/FileSystemSessionOutputActivityRepository.ts

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { LiveSessionOutputActivity } from '../../domain/entities/LiveSessionOutputActivity';
+import { SessionOutputActivityRepository } from '../../domain/usecases/adapter-interfaces/SessionOutputActivityRepository';
+
+export class FileSystemSessionOutputActivityRepository implements SessionOutputActivityRepository {
+  constructor(private readonly rootDirectory: string | null) {}
+
+  listSessionOutputActivities = async (
+    sessionNames: string[],
+  ): Promise<LiveSessionOutputActivity[]> => {
+    if (this.rootDirectory === null) {
+      return [];
+    }
+    const activities: LiveSessionOutputActivity[] = [];
+    for (const sessionName of sessionNames) {
+      const lastOutputEpochSeconds =
+        this.readLastOutputEpochSeconds(sessionName);
+      if (lastOutputEpochSeconds !== null) {
+        activities.push({ sessionName, lastOutputEpochSeconds });
+      }
+    }
+    return activities;
+  };
+
+  private readLastOutputEpochSeconds = (sessionName: string): number | null => {
+    if (this.rootDirectory === null) {
+      return null;
+    }
+    const filePath = path.join(
+      this.rootDirectory,
+      this.toOutputFileName(sessionName),
+    );
+    let stats: fs.Stats;
+    try {
+      stats = fs.statSync(filePath);
+    } catch {
+      return null;
+    }
+    if (!stats.isFile()) {
+      return null;
+    }
+    return Math.floor(stats.mtimeMs / 1000);
+  };
+
+  private toOutputFileName = (sessionName: string): string =>
+    sessionName.replace(/\//g, '_');
+}

package/src/adapter/repositories/FileSystemSubAgentSilentSecondsResolver.test.ts

@@ -0,0 +1,56 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { FileSystemSubAgentSilentSecondsResolver } from './FileSystemSubAgentSilentSecondsResolver';
+
+const NOW = new Date('2026-06-26T00:00:00.000Z');
+const NOW_EPOCH_SECONDS = Math.floor(NOW.getTime() / 1000);
+
+describe('FileSystemSubAgentSilentSecondsResolver', () => {
+  let rootDirectory: string;
+
+  beforeEach(() => {
+    rootDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'subagent-out-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(rootDirectory, { force: true, recursive: true });
+  });
+
+  it('returns 0 when the root directory is not configured', () => {
+    const resolver = new FileSystemSubAgentSilentSecondsResolver(null, NOW);
+    expect(resolver.resolveSilentSeconds('task-a')).toBe(0);
+  });
+
+  it('returns 0 when the output file does not exist', () => {
+    const resolver = new FileSystemSubAgentSilentSecondsResolver(
+      rootDirectory,
+      NOW,
+    );
+    expect(resolver.resolveSilentSeconds('task-a')).toBe(0);
+  });
+
+  it('returns the seconds since the output file was last modified', () => {
+    const filePath = path.join(rootDirectory, 'task-a');
+    fs.writeFileSync(filePath, 'output', 'utf8');
+    const silentEpoch = NOW_EPOCH_SECONDS - 360;
+    fs.utimesSync(filePath, silentEpoch, silentEpoch);
+    const resolver = new FileSystemSubAgentSilentSecondsResolver(
+      rootDirectory,
+      NOW,
+    );
+    expect(resolver.resolveSilentSeconds('task-a')).toBe(360);
+  });
+
+  it('replaces slashes in the label when resolving the file name', () => {
+    const filePath = path.join(rootDirectory, 'group_task-a');
+    fs.writeFileSync(filePath, 'output', 'utf8');
+    const silentEpoch = NOW_EPOCH_SECONDS - 120;
+    fs.utimesSync(filePath, silentEpoch, silentEpoch);
+    const resolver = new FileSystemSubAgentSilentSecondsResolver(
+      rootDirectory,
+      NOW,
+    );
+    expect(resolver.resolveSilentSeconds('group/task-a')).toBe(120);
+  });
+});

package/src/adapter/repositories/FileSystemSubAgentSilentSecondsResolver.ts

@@ -0,0 +1,32 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { SubAgentSilentSecondsResolver } from '../../domain/usecases/adapter-interfaces/SubAgentSilentSecondsResolver';
+
+export class FileSystemSubAgentSilentSecondsResolver implements SubAgentSilentSecondsResolver {
+  constructor(
+    private readonly rootDirectory: string | null,
+    private readonly now: Date,
+  ) {}
+
+  resolveSilentSeconds = (label: string): number => {
+    if (this.rootDirectory === null) {
+      return 0;
+    }
+    const filePath = path.join(this.rootDirectory, this.toFileName(label));
+    let stats: fs.Stats;
+    try {
+      stats = fs.statSync(filePath);
+    } catch {
+      return 0;
+    }
+    if (!stats.isFile()) {
+      return 0;
+    }
+    const lastOutputEpochSeconds = Math.floor(stats.mtimeMs / 1000);
+    const nowEpochSeconds = Math.floor(this.now.getTime() / 1000);
+    const silentSeconds = nowEpochSeconds - lastOutputEpochSeconds;
+    return silentSeconds > 0 ? silentSeconds : 0;
+  };
+
+  private toFileName = (label: string): string => label.replace(/\//g, '_');
+}

package/src/adapter/repositories/FileSystemSubAgentTranscriptDirectoryResolver.test.ts

@@ -0,0 +1,32 @@
+import * as path from 'path';
+import { FileSystemSubAgentTranscriptDirectoryResolver } from './FileSystemSubAgentTranscriptDirectoryResolver';
+
+describe('FileSystemSubAgentTranscriptDirectoryResolver', () => {
+  it('builds the subagents directory under the session-specific directory', () => {
+    const resolver = new FileSystemSubAgentTranscriptDirectoryResolver(
+      '/var/transcripts',
+    );
+
+    const result = resolver.resolveSubAgentsDirectory(
+      'https_//github_com/owner/repo/issues/9',
+    );
+
+    expect(result).toBe(
+      path.join(
+        '/var/transcripts',
+        'https_//github_com_owner_repo_issues_9'.replace(/\//g, '_'),
+        'subagents',
+      ),
+    );
+  });
+
+  it('returns null when the root directory is null', () => {
+    const resolver = new FileSystemSubAgentTranscriptDirectoryResolver(null);
+
+    const result = resolver.resolveSubAgentsDirectory(
+      'https_//github_com/owner/repo/issues/9',
+    );
+
+    expect(result).toBeNull();
+  });
+});

package/src/adapter/repositories/FileSystemSubAgentTranscriptDirectoryResolver.ts

@@ -0,0 +1,17 @@
+import * as path from 'path';
+import { SubAgentTranscriptDirectoryResolver } from '../../domain/usecases/adapter-interfaces/SubAgentTranscriptDirectoryResolver';
+
+export class FileSystemSubAgentTranscriptDirectoryResolver implements SubAgentTranscriptDirectoryResolver {
+  constructor(private readonly rootDirectory: string | null) {}
+
+  resolveSubAgentsDirectory = (sessionName: string): string | null => {
+    if (this.rootDirectory === null) {
+      return null;
+    }
+    return path.join(
+      this.rootDirectory,
+      sessionName.replace(/\//g, '_'),
+      'subagents',
+    );
+  };
+}

package/src/adapter/repositories/NoUnansweredOwnerCallStatusProvider.test.ts

@@ -0,0 +1,12 @@
+import { NoUnansweredOwnerCallStatusProvider } from './NoUnansweredOwnerCallStatusProvider';
+
+describe('NoUnansweredOwnerCallStatusProvider', () => {
+  it('always reports no session as having an unanswered owner call', async () => {
+    const provider = new NoUnansweredOwnerCallStatusProvider();
+    const result = await provider.listSessionNamesWithUnansweredOwnerCall([
+      'session-a',
+      'session-b',
+    ]);
+    expect(result.size).toBe(0);
+  });
+});

package/src/adapter/repositories/NoUnansweredOwnerCallStatusProvider.ts

@@ -0,0 +1,9 @@
+import { OwnerCallStatusProvider } from '../../domain/usecases/adapter-interfaces/OwnerCallStatusProvider';
+
+export class NoUnansweredOwnerCallStatusProvider implements OwnerCallStatusProvider {
+  listSessionNamesWithUnansweredOwnerCall = (
+    _sessionNames: string[],
+  ): Promise<Set<string>> => {
+    return Promise.resolve(new Set<string>());
+  };
+}

package/src/adapter/repositories/NodeSubAgentProcessLister.test.ts

@@ -0,0 +1,43 @@
+import { NodeSubAgentProcessLister } from './NodeSubAgentProcessLister';
+import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+
+type Mocked<T> = jest.Mocked<T> & jest.MockedObject<T>;
+
+const createRunner = (
+  stdout: string,
+  exitCode = 0,
+): Mocked<LocalCommandRunner> => ({
+  runCommand: jest.fn().mockResolvedValue({ stdout, stderr: '', exitCode }),
+});
+
+describe('NodeSubAgentProcessLister', () => {
+  it('parses elapsed seconds and command line from ps output', async () => {
+    const runner = createRunner(
+      '  1200 worker session=s1 label=task-a\n   30 another --flag value\n',
+    );
+    const lister = new NodeSubAgentProcessLister(runner);
+    const processes = await lister.listProcesses();
+    expect(processes).toEqual([
+      { commandLine: 'worker session=s1 label=task-a', elapsedSeconds: 1200 },
+      { commandLine: 'another --flag value', elapsedSeconds: 30 },
+    ]);
+    expect(runner.runCommand.mock.calls[0]).toEqual([
+      'ps',
+      ['-eo', 'etimes=,args='],
+    ]);
+  });
+
+  it('returns an empty array when ps exits non-zero', async () => {
+    const runner = createRunner('', 1);
+    const lister = new NodeSubAgentProcessLister(runner);
+    expect(await lister.listProcesses()).toEqual([]);
+  });
+
+  it('skips blank lines and lines without a command', async () => {
+    const runner = createRunner('\n  1200 \n  500 valid command\n');
+    const lister = new NodeSubAgentProcessLister(runner);
+    expect(await lister.listProcesses()).toEqual([
+      { commandLine: 'valid command', elapsedSeconds: 500 },
+    ]);
+  });
+});

package/src/adapter/repositories/NodeSubAgentProcessLister.ts

@@ -0,0 +1,40 @@
+import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+import {
+  SubAgentProcess,
+  SubAgentProcessLister,
+} from '../../domain/usecases/adapter-interfaces/SubAgentProcessLister';
+
+export class NodeSubAgentProcessLister implements SubAgentProcessLister {
+  constructor(private readonly localCommandRunner: LocalCommandRunner) {}
+
+  listProcesses = async (): Promise<SubAgentProcess[]> => {
+    const { stdout, exitCode } = await this.localCommandRunner.runCommand(
+      'ps',
+      ['-eo', 'etimes=,args='],
+    );
+    if (exitCode !== 0) {
+      return [];
+    }
+    const processes: SubAgentProcess[] = [];
+    for (const line of stdout.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) {
+        continue;
+      }
+      const separatorIndex = trimmed.indexOf(' ');
+      if (separatorIndex < 0) {
+        continue;
+      }
+      const elapsedSeconds = Number(trimmed.slice(0, separatorIndex));
+      if (!Number.isFinite(elapsedSeconds)) {
+        continue;
+      }
+      const commandLine = trimmed.slice(separatorIndex + 1).trim();
+      if (commandLine.length === 0) {
+        continue;
+      }
+      processes.push({ commandLine, elapsedSeconds });
+    }
+    return processes;
+  };
+}

package/src/adapter/repositories/ProcessListSessionSubAgentActivityRepository.test.ts

@@ -0,0 +1,109 @@
+import { ProcessListSessionSubAgentActivityRepository } from './ProcessListSessionSubAgentActivityRepository';
+import { SubAgentProcessLister } from '../../domain/usecases/adapter-interfaces/SubAgentProcessLister';
+import { SubAgentSilentSecondsResolver } from '../../domain/usecases/adapter-interfaces/SubAgentSilentSecondsResolver';
+
+type Mocked<T> = jest.Mocked<T> & jest.MockedObject<T>;
+
+const createLister = (
+  processes: { commandLine: string; elapsedSeconds: number }[],
+): Mocked<SubAgentProcessLister> => ({
+  listProcesses: jest.fn().mockResolvedValue(processes),
+});
+
+const createResolver = (
+  silentSeconds: number,
+): Mocked<SubAgentSilentSecondsResolver> => ({
+  resolveSilentSeconds: jest.fn().mockReturnValue(silentSeconds),
+});
+
+describe('ProcessListSessionSubAgentActivityRepository', () => {
+  it('returns an empty map when the match pattern is not configured', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      null,
+      createLister([
+        { commandLine: 'anything session=s1', elapsedSeconds: 10 },
+      ]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.size).toBe(0);
+  });
+
+  it('returns an empty map when the match pattern is an empty string', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      '',
+      createLister([
+        { commandLine: 'anything session=s1', elapsedSeconds: 10 },
+      ]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.size).toBe(0);
+  });
+
+  it('associates a matched process to a monitored session using the session capture group', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      'session=(?<session>[^ ]+) label=(?<label>[^ ]+)',
+      createLister([
+        {
+          commandLine: 'worker session=s1 label=task-a',
+          elapsedSeconds: 1200,
+        },
+      ]),
+      createResolver(180),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.get('s1')).toEqual([
+      { label: 'task-a', silentSeconds: 180, runningSeconds: 1200 },
+    ]);
+  });
+
+  it('ignores processes whose captured session is not monitored', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      'session=(?<session>[^ ]+)',
+      createLister([
+        { commandLine: 'worker session=other', elapsedSeconds: 1200 },
+      ]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.size).toBe(0);
+  });
+
+  it('falls back to the session name as the label when no label group is captured', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      'session=(?<session>[^ ]+)',
+      createLister([{ commandLine: 'worker session=s1', elapsedSeconds: 30 }]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.get('s1')).toEqual([
+      { label: 's1', silentSeconds: 0, runningSeconds: 30 },
+    ]);
+  });
+
+  it('groups multiple matched processes under the same session', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      'session=(?<session>[^ ]+) label=(?<label>[^ ]+)',
+      createLister([
+        { commandLine: 'worker session=s1 label=task-a', elapsedSeconds: 10 },
+        { commandLine: 'worker session=s1 label=task-b', elapsedSeconds: 20 },
+      ]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.get('s1')).toHaveLength(2);
+  });
+
+  it('ignores processes that do not match the pattern', async () => {
+    const repository = new ProcessListSessionSubAgentActivityRepository(
+      'session=(?<session>[^ ]+)',
+      createLister([
+        { commandLine: 'unrelated process', elapsedSeconds: 1200 },
+      ]),
+      createResolver(0),
+    );
+    const result = await repository.listSubAgentActivitiesBySessionName(['s1']);
+    expect(result.size).toBe(0);
+  });
+});

package/src/adapter/repositories/ProcessListSessionSubAgentActivityRepository.ts

@@ -0,0 +1,56 @@
+import { SubAgentActivity } from '../../domain/entities/LiveSessionActivitySnapshot';
+import { SessionSubAgentActivityRepository } from '../../domain/usecases/adapter-interfaces/SessionSubAgentActivityRepository';
+import { SubAgentProcessLister } from '../../domain/usecases/adapter-interfaces/SubAgentProcessLister';
+import { SubAgentSilentSecondsResolver } from '../../domain/usecases/adapter-interfaces/SubAgentSilentSecondsResolver';
+
+export class ProcessListSessionSubAgentActivityRepository implements SessionSubAgentActivityRepository {
+  private readonly matchRegExp: RegExp | null;
+
+  constructor(
+    matchPattern: string | null,
+    private readonly processLister: SubAgentProcessLister,
+    private readonly silentSecondsResolver: SubAgentSilentSecondsResolver,
+  ) {
+    this.matchRegExp =
+      matchPattern === null || matchPattern.length === 0
+        ? null
+        : new RegExp(matchPattern);
+  }
+
+  listSubAgentActivitiesBySessionName = async (
+    sessionNames: string[],
+  ): Promise<Map<string, SubAgentActivity[]>> => {
+    const result = new Map<string, SubAgentActivity[]>();
+    if (this.matchRegExp === null) {
+      return result;
+    }
+    const monitoredSessionNames = new Set(sessionNames);
+    const processes = await this.processLister.listProcesses();
+    for (const process of processes) {
+      const match = this.matchRegExp.exec(process.commandLine);
+      if (match === null || match.groups === undefined) {
+        continue;
+      }
+      const sessionName = match.groups.session;
+      if (
+        sessionName === undefined ||
+        !monitoredSessionNames.has(sessionName)
+      ) {
+        continue;
+      }
+      const label = match.groups.label ?? sessionName;
+      const activity: SubAgentActivity = {
+        label,
+        silentSeconds: this.silentSecondsResolver.resolveSilentSeconds(label),
+        runningSeconds: process.elapsedSeconds,
+      };
+      const existing = result.get(sessionName);
+      if (existing === undefined) {
+        result.set(sessionName, [activity]);
+      } else {
+        existing.push(activity);
+      }
+    }
+    return result;
+  };
+}

package/src/adapter/repositories/RealSleeper.test.ts

@@ -0,0 +1,19 @@
+import { RealSleeper } from './RealSleeper';
+
+describe('RealSleeper', () => {
+  it('resolves after roughly the requested delay', async () => {
+    const sleeper = new RealSleeper();
+    const start = Date.now();
+    await sleeper.sleep(30);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeGreaterThanOrEqual(20);
+  });
+
+  it('resolves immediately for a non-positive delay', async () => {
+    const sleeper = new RealSleeper();
+    const start = Date.now();
+    await sleeper.sleep(0);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(20);
+  });
+});

package/src/adapter/repositories/RealSleeper.ts

@@ -0,0 +1,12 @@
+import { Sleeper } from '../../domain/usecases/adapter-interfaces/Sleeper';
+
+export class RealSleeper implements Sleeper {
+  sleep = (milliseconds: number): Promise<void> => {
+    if (milliseconds <= 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      setTimeout(resolve, milliseconds);
+    });
+  };
+}