github-issue-tower-defence-management 1.104.4 → 1.105.0

package/src/adapter/entry-points/handlers/machineStatusWriter.test.ts

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { ProcHostMetricsRepository } from '../../repositories/ProcHostMetricsRepository';
+import { MachineStatusFile, writeMachineStatus } from './machineStatusWriter';
+
+const readJson = (filePath: string): unknown =>
+  JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
+
+const buildHostMetricsRepository = (
+  procDirectory: string,
+): {
+  repository: ProcHostMetricsRepository;
+} => {
+  fs.writeFileSync(
+    path.join(procDirectory, 'meminfo'),
+    'MemTotal: 1000 kB\nMemAvailable: 450 kB\n',
+  );
+  fs.writeFileSync(
+    path.join(procDirectory, 'loadavg'),
+    '1.50 0.80 0.40 1/100 200\n',
+  );
+  const statPath = path.join(procDirectory, 'stat');
+  fs.writeFileSync(statPath, 'cpu  600 0 0 400 0 0 0 0 0 0\n');
+  const sleep = async (): Promise<void> => {
+    fs.writeFileSync(statPath, 'cpu  660 0 0 440 0 0 0 0 0 0\n');
+  };
+  return { repository: new ProcHostMetricsRepository(procDirectory, sleep) };
+};
+
+describe('writeMachineStatus', () => {
+  let dir: string;
+  let procDirectory: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'machine-status-'));
+    procDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'machine-proc-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.rmSync(procDirectory, { recursive: true, force: true });
+  });
+
+  it('writes machine-status.json with mem, cpu, load and cycle minutes', async () => {
+    const { repository } = buildHostMetricsRepository(procDirectory);
+    const cacheDir = path.join(dir, 'allIssues-PVT');
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const newer = path.join(cacheDir, 'a.json');
+    const older = path.join(cacheDir, 'b.json');
+    fs.writeFileSync(older, '[]');
+    fs.writeFileSync(newer, '[]');
+    const base = Date.now();
+    fs.utimesSync(older, new Date(base - 900000), new Date(base - 900000));
+    fs.utimesSync(newer, new Date(base), new Date(base));
+
+    await writeMachineStatus({
+      dashboardDataDir: dir,
+      allIssuesCacheDir: cacheDir,
+      hostMetricsRepository: repository,
+      now: new Date('2026-06-26T12:00:00.000Z'),
+    });
+
+    const written = readJson(path.join(dir, 'machine-status.json'));
+    const expected: MachineStatusFile = {
+      memPct: 55,
+      cpuPct: 60,
+      load: [1.5, 0.8, 0.4],
+      cycleMinutes: 15,
+      capturedAt: '2026-06-26T12:00:00.000Z',
+    };
+    expect(written).toEqual(expected);
+  });
+
+  it('writes cycleMinutes null when fewer than two cache files exist', async () => {
+    const { repository } = buildHostMetricsRepository(procDirectory);
+    const cacheDir = path.join(dir, 'allIssues-PVT');
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(path.join(cacheDir, 'only.json'), '[]');
+
+    await writeMachineStatus({
+      dashboardDataDir: dir,
+      allIssuesCacheDir: cacheDir,
+      hostMetricsRepository: repository,
+    });
+
+    const written = readJson(path.join(dir, 'machine-status.json'));
+    expect(written).toMatchObject({ cycleMinutes: null });
+  });
+
+  it('is a no-op when dashboardDataDir is unset', async () => {
+    const { repository } = buildHostMetricsRepository(procDirectory);
+    await writeMachineStatus({
+      dashboardDataDir: null,
+      allIssuesCacheDir: null,
+      hostMetricsRepository: repository,
+    });
+    expect(fs.readdirSync(dir)).toEqual([]);
+  });
+});

package/src/adapter/entry-points/handlers/machineStatusWriter.ts

@@ -0,0 +1,79 @@
+import fs from 'fs';
+import path from 'path';
+import {
+  ProcHostMetricsRepository,
+  cycleMinutesFromMtimes,
+} from '../../repositories/ProcHostMetricsRepository';
+
+export type MachineStatusWriterParams = {
+  dashboardDataDir: string | null | undefined;
+  allIssuesCacheDir: string | null | undefined;
+  hostMetricsRepository?: ProcHostMetricsRepository;
+  now?: Date;
+};
+
+export type MachineStatusFile = {
+  memPct: number;
+  cpuPct: number;
+  load: [number, number, number];
+  cycleMinutes: number | null;
+  capturedAt: string;
+};
+
+const writeJsonAtomic = (filePath: string, data: unknown): void => {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data));
+  fs.renameSync(tmpPath, filePath);
+};
+
+const cacheFileMtimesDescending = (allIssuesCacheDir: string): number[] => {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(allIssuesCacheDir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => {
+      try {
+        return fs.statSync(path.join(allIssuesCacheDir, entry)).mtimeMs / 1000;
+      } catch {
+        return null;
+      }
+    })
+    .filter((value): value is number => value !== null)
+    .sort((a, b) => b - a);
+};
+
+export const writeMachineStatus = async (
+  params: MachineStatusWriterParams,
+): Promise<void> => {
+  const { dashboardDataDir, allIssuesCacheDir } = params;
+  if (!dashboardDataDir) {
+    return;
+  }
+
+  const hostMetricsRepository =
+    params.hostMetricsRepository ?? new ProcHostMetricsRepository();
+
+  const memPct = hostMetricsRepository.readMemoryUsedPercent();
+  const cpuPct = await hostMetricsRepository.readCpuUsedPercent();
+  const load = hostMetricsRepository.readLoadAverages();
+
+  const cycleMinutes = allIssuesCacheDir
+    ? cycleMinutesFromMtimes(cacheFileMtimesDescending(allIssuesCacheDir))
+    : null;
+
+  const file: MachineStatusFile = {
+    memPct,
+    cpuPct,
+    load: [load.oneMinute, load.fiveMinute, load.fifteenMinute],
+    cycleMinutes,
+    capturedAt: (params.now ?? new Date()).toISOString(),
+  };
+
+  writeJsonAtomic(path.join(dashboardDataDir, 'machine-status.json'), file);
+};

package/src/adapter/entry-points/handlers/tokenStatusWriter.test.ts

@@ -0,0 +1,176 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Issue } from '../../../domain/entities/Issue';
+import { ClaudeInteractiveSession } from '../../../domain/usecases/adapter-interfaces/ClaudeInteractiveSessionRepository';
+import { TakeOwnershipSpawn } from '../../../domain/usecases/adapter-interfaces/TakeOwnershipSpawnRepository';
+import { RateLimitSnapshot } from '../../proxy/RateLimitCache';
+import { TokenStatusFile, writeTokenStatus } from './tokenStatusWriter';
+
+const readJson = (filePath: string): unknown =>
+  JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
+
+const ASSIGNEE = 'HiromiShikata';
+
+const baseSnapshot = (
+  overrides: Partial<RateLimitSnapshot> = {},
+): RateLimitSnapshot => ({
+  fiveHourUtilization: 0.1,
+  fiveHourReset: 0,
+  sevenDayUtilization: 0.1,
+  sevenDayReset: 0,
+  blocked: false,
+  rejected: false,
+  unifiedRejected: false,
+  fiveHourRejected: false,
+  sevenDayRejected: false,
+  unifiedStatus: 'allowed',
+  overageDisabledReason: null,
+  modelWeeklyLimits: {},
+  lastUpdatedEpoch: 0,
+  blockedUntilEpoch: 0,
+  ...overrides,
+});
+
+const makeIssue = (overrides: Partial<Issue>): Issue => ({
+  nameWithOwner: 'demo/repo',
+  number: 1,
+  title: 'Issue',
+  state: 'OPEN',
+  status: null,
+  story: null,
+  nextActionDate: null,
+  nextActionHour: null,
+  estimationMinutes: null,
+  dependedIssueUrls: [],
+  completionDate50PercentConfidence: null,
+  url: 'https://github.com/demo/repo/issues/1',
+  assignees: [ASSIGNEE],
+  labels: [],
+  org: 'demo',
+  repo: 'repo',
+  body: '',
+  itemId: 'item-1',
+  isPr: false,
+  isInProgress: false,
+  isClosed: false,
+  createdAt: new Date('2026-06-13T08:18:45.000Z'),
+  author: 'someone',
+  closingIssueReferenceUrls: [],
+  ...overrides,
+});
+
+describe('writeTokenStatus', () => {
+  let dir: string;
+  let tokenListPath: string;
+  const now = new Date('2026-06-26T12:00:00.000Z');
+  const nowEpoch = Math.floor(now.getTime() / 1000);
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'token-status-'));
+    tokenListPath = path.join(dir, 'tokens.json');
+    fs.writeFileSync(
+      tokenListPath,
+      JSON.stringify([
+        { name: 'alice', token: 'token-a' },
+        { name: 'bob', token: 'token-b' },
+      ]),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('writes token-status.json with per-token color, util, prep and hum', () => {
+    const interactiveSessions: ClaudeInteractiveSession[] = [
+      {
+        token: 'token-a',
+        sessionId: 'session-1',
+        issueUrl: 'https://github.com/demo/repo/issues/1',
+      },
+    ];
+    const spawns: TakeOwnershipSpawn[] = [
+      { token: 'token-a', logPath: '/logs-aw/x.log' },
+      { token: 'token-a', logPath: '/logs-aw/x.log' },
+      { token: 'token-a', logPath: '/logs-aw/y.log' },
+    ];
+
+    writeTokenStatus({
+      dashboardDataDir: dir,
+      tokenListJsonPath: tokenListPath,
+      issues: [
+        makeIssue({
+          status: 'In Tmux by human',
+          url: 'https://github.com/demo/repo/issues/1',
+        }),
+      ],
+      now,
+      readSnapshot: (token) =>
+        token === 'token-a'
+          ? baseSnapshot({
+              fiveHourUtilization: 0.42,
+              fiveHourReset: nowEpoch + 3600,
+              sevenDayUtilization: 0.5,
+              sevenDayReset: nowEpoch + 86400,
+            })
+          : null,
+      interactiveSessionRepository: {
+        listInteractiveSessions: () => interactiveSessions,
+      },
+      spawnRepository: { listSpawns: () => spawns },
+    });
+
+    const written = readJson(path.join(dir, 'token-status.json'));
+    const expected: TokenStatusFile = {
+      capturedAt: '2026-06-26T12:00:00.000Z',
+      tokens: [
+        {
+          name: 'alice',
+          fiveHourUtilizationPercent: 42,
+          fiveHourResetSeconds: 3600,
+          sevenDayUtilizationPercent: 50,
+          sevenDayResetSeconds: 86400,
+          color: 'G',
+          prep: 2,
+          hum: 1,
+        },
+        {
+          name: 'bob',
+          fiveHourUtilizationPercent: null,
+          fiveHourResetSeconds: null,
+          sevenDayUtilizationPercent: null,
+          sevenDayResetSeconds: null,
+          color: 'Y',
+          prep: 0,
+          hum: 0,
+        },
+      ],
+    };
+    expect(written).toEqual(expected);
+  });
+
+  it('is a no-op when dashboardDataDir is unset', () => {
+    writeTokenStatus({
+      dashboardDataDir: null,
+      tokenListJsonPath: tokenListPath,
+      issues: [],
+      readSnapshot: () => null,
+      interactiveSessionRepository: { listInteractiveSessions: () => [] },
+      spawnRepository: { listSpawns: () => [] },
+    });
+    expect(fs.existsSync(path.join(dir, 'token-status.json'))).toBe(false);
+  });
+
+  it('is a no-op when the token list path is unset', () => {
+    writeTokenStatus({
+      dashboardDataDir: dir,
+      tokenListJsonPath: null,
+      issues: [],
+      readSnapshot: () => null,
+      interactiveSessionRepository: { listInteractiveSessions: () => [] },
+      spawnRepository: { listSpawns: () => [] },
+    });
+    expect(fs.existsSync(path.join(dir, 'token-status.json'))).toBe(false);
+  });
+});

package/src/adapter/entry-points/handlers/tokenStatusWriter.ts

@@ -0,0 +1,139 @@
+import fs from 'fs';
+import path from 'path';
+import type { Issue } from '../../../domain/entities/Issue';
+import {
+  GenerateTokenStatusUseCase,
+  TokenRateLimitSnapshot,
+  TokenStatus,
+  TokenStatusInput,
+} from '../../../domain/usecases/dashboard/GenerateTokenStatusUseCase';
+import { InTmuxByHumanSessionTokenCountUseCase } from '../../../domain/usecases/InTmuxByHumanSessionTokenCountUseCase';
+import { OauthTokenCandidate } from '../../../domain/usecases/OauthTokenSelectUseCase';
+import { ClaudeInteractiveSessionRepository } from '../../../domain/usecases/adapter-interfaces/ClaudeInteractiveSessionRepository';
+import { TakeOwnershipSpawnRepository } from '../../../domain/usecases/adapter-interfaces/TakeOwnershipSpawnRepository';
+import { RateLimitSnapshot, readRateLimit } from '../../proxy/RateLimitCache';
+import { loadTokenEntries } from '../../proxy/TokenListLoader';
+import { ProcClaudeInteractiveSessionRepository } from '../../repositories/ProcClaudeInteractiveSessionRepository';
+import { ProcTakeOwnershipSpawnRepository } from '../../repositories/ProcTakeOwnershipSpawnRepository';
+
+const SEVEN_DAY_SONNET_LIMIT_TYPE = 'seven_day_sonnet';
+const SEVEN_DAY_OPUS_LIMIT_TYPE = 'seven_day_opus';
+
+export type TokenStatusWriterParams = {
+  dashboardDataDir: string | null | undefined;
+  tokenListJsonPath: string | null | undefined;
+  issues: Issue[];
+  now?: Date;
+  readSnapshot?: (token: string) => RateLimitSnapshot | null;
+  interactiveSessionRepository?: ClaudeInteractiveSessionRepository;
+  spawnRepository?: TakeOwnershipSpawnRepository;
+};
+
+export type TokenStatusFile = {
+  tokens: TokenStatus[];
+  capturedAt: string;
+};
+
+const writeJsonAtomic = (filePath: string, data: unknown): void => {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data));
+  fs.renameSync(tmpPath, filePath);
+};
+
+export const toTokenRateLimitSnapshot = (
+  snapshot: RateLimitSnapshot | null,
+): TokenRateLimitSnapshot | null => {
+  if (snapshot === null) {
+    return null;
+  }
+  const hasWindowData =
+    snapshot.unifiedStatus !== null ||
+    snapshot.fiveHourReset > 0 ||
+    snapshot.sevenDayReset > 0 ||
+    snapshot.fiveHourUtilization > 0 ||
+    snapshot.sevenDayUtilization > 0;
+  return {
+    fiveHourUtilization: snapshot.fiveHourUtilization,
+    fiveHourReset: snapshot.fiveHourReset,
+    sevenDayUtilization: snapshot.sevenDayUtilization,
+    sevenDayReset: snapshot.sevenDayReset,
+    blocked: snapshot.blocked,
+    fiveHourRejected: snapshot.fiveHourRejected,
+    sevenDayRejected: snapshot.sevenDayRejected,
+    unifiedStatus: snapshot.unifiedStatus,
+    sevenDaySonnetRejected:
+      snapshot.modelWeeklyLimits[SEVEN_DAY_SONNET_LIMIT_TYPE]?.rejected ??
+      false,
+    sevenDayOpusRejected:
+      snapshot.modelWeeklyLimits[SEVEN_DAY_OPUS_LIMIT_TYPE]?.rejected ?? false,
+    hasWindowData,
+  };
+};
+
+export const writeTokenStatus = (params: TokenStatusWriterParams): void => {
+  const { dashboardDataDir, tokenListJsonPath, issues } = params;
+  if (!dashboardDataDir || !tokenListJsonPath) {
+    return;
+  }
+
+  const entries = loadTokenEntries(tokenListJsonPath);
+  if (entries === null) {
+    return;
+  }
+
+  const readSnapshot = params.readSnapshot ?? readRateLimit;
+  const interactiveSessionRepository =
+    params.interactiveSessionRepository ??
+    new ProcClaudeInteractiveSessionRepository();
+  const spawnRepository =
+    params.spawnRepository ?? new ProcTakeOwnershipSpawnRepository();
+
+  const tokenInputs: TokenStatusInput[] = entries.map((entry) => ({
+    name: entry.name,
+    token: entry.token,
+    snapshot: toTokenRateLimitSnapshot(readSnapshot(entry.token)),
+  }));
+
+  const distinctLogPathsByToken = new Map<string, Set<string>>();
+  for (const spawn of spawnRepository.listSpawns()) {
+    const logPaths =
+      distinctLogPathsByToken.get(spawn.token) ?? new Set<string>();
+    logPaths.add(spawn.logPath);
+    distinctLogPathsByToken.set(spawn.token, logPaths);
+  }
+  const prepCountByToken = new Map<string, number>();
+  for (const [token, logPaths] of distinctLogPathsByToken.entries()) {
+    prepCountByToken.set(token, logPaths.size);
+  }
+
+  const candidates: OauthTokenCandidate[] = entries.map((entry) => ({
+    name: entry.name,
+    token: entry.token,
+    snapshot: null,
+  }));
+  const humResult = new InTmuxByHumanSessionTokenCountUseCase().run(
+    candidates,
+    interactiveSessionRepository.listInteractiveSessions(),
+    issues,
+  );
+  const humCountByToken = new Map<string, number>(
+    humResult.counts.map((count) => [count.token, count.count]),
+  );
+
+  const now = params.now ?? new Date();
+  const tokens = new GenerateTokenStatusUseCase().run({
+    tokens: tokenInputs,
+    prepCountByToken,
+    humCountByToken,
+    nowEpochSeconds: Math.floor(now.getTime() / 1000),
+  });
+
+  const file: TokenStatusFile = {
+    tokens,
+    capturedAt: now.toISOString(),
+  };
+
+  writeJsonAtomic(path.join(dashboardDataDir, 'token-status.json'), file);
+};

package/src/adapter/proxy/RateLimitCache.test.ts

@@ -180,6 +180,38 @@ describe('RateLimitCache', () => {
       expect(snapshot?.sevenDayRejected).toBe(false);
     });
 
+    it('should surface the raw unified status and overage-disabled reason headers', () => {
+      const token = 'unified-status-token';
+      writeRateLimit(token, {
+        'anthropic-ratelimit-unified-status': 'allowed_warning',
+        'anthropic-ratelimit-unified-overage-disabled-reason': 'out_of_credits',
+        'anthropic-ratelimit-unified-5h-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-reset': '1700000000',
+        'anthropic-ratelimit-unified-5h-utilization': '50',
+        'anthropic-ratelimit-unified-7d-status': 'allowed',
+        'anthropic-ratelimit-unified-7d-reset': '1700100000',
+        'anthropic-ratelimit-unified-7d-utilization': '40',
+      });
+      const snapshot = readRateLimit(token);
+      expect(snapshot?.unifiedStatus).toBe('allowed_warning');
+      expect(snapshot?.overageDisabledReason).toBe('out_of_credits');
+    });
+
+    it('should expose null for the unified status and overage-disabled reason when absent', () => {
+      const token = 'no-unified-status-token';
+      writeRateLimit(token, {
+        'anthropic-ratelimit-unified-5h-status': 'allowed',
+        'anthropic-ratelimit-unified-5h-reset': '1700000000',
+        'anthropic-ratelimit-unified-5h-utilization': '50',
+        'anthropic-ratelimit-unified-7d-status': 'allowed',
+        'anthropic-ratelimit-unified-7d-reset': '1700100000',
+        'anthropic-ratelimit-unified-7d-utilization': '40',
+      });
+      const snapshot = readRateLimit(token);
+      expect(snapshot?.unifiedStatus).toBeNull();
+      expect(snapshot?.overageDisabledReason).toBeNull();
+    });
+
     it('should return null when file does not exist', () => {
       expect(readRateLimit('never-written-token')).toBeNull();
     });

package/src/adapter/proxy/RateLimitCache.ts

@@ -18,6 +18,8 @@ export interface RateLimitSnapshot {
   unifiedRejected: boolean;
   fiveHourRejected: boolean;
   sevenDayRejected: boolean;
+  unifiedStatus: string | null;
+  overageDisabledReason: string | null;
   modelWeeklyLimits: Record<string, ModelWeeklyLimit>;
   lastUpdatedEpoch: number;
   blockedUntilEpoch: number;
@@ -252,6 +254,8 @@ export const readRateLimit = (
     const status = headers['anthropic-ratelimit-unified-status'];
     const fiveHourStatus = headers['anthropic-ratelimit-unified-5h-status'];
     const sevenDayStatus = headers['anthropic-ratelimit-unified-7d-status'];
+    const overageDisabledReason =
+      headers['anthropic-ratelimit-unified-overage-disabled-reason'];
     const unifiedRejected = status === 'rejected';
     const fiveHourRejected = fiveHourStatus === 'rejected';
     const sevenDayRejected = sevenDayStatus === 'rejected';
@@ -273,6 +277,8 @@ export const readRateLimit = (
       unifiedRejected,
       fiveHourRejected,
       sevenDayRejected,
+      unifiedStatus: status ?? null,
+      overageDisabledReason: overageDisabledReason ?? null,
       modelWeeklyLimits: {
         ...parseModelRateLimitsFromHeaders(headers),
         ...readModelWeeklyLimits(parsed),

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

@@ -0,0 +1,135 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  ProcHostMetricsRepository,
+  cpuUsedPercentFromSamples,
+  cycleMinutesFromMtimes,
+  parseCpuSample,
+  parseLoadAverages,
+  parseMemoryUsedPercent,
+} from './ProcHostMetricsRepository';
+
+describe('parseMemoryUsedPercent', () => {
+  it('computes (total - available) / total rounded to a whole percent', () => {
+    expect(
+      parseMemoryUsedPercent(
+        'MemTotal: 1000 kB\nMemFree: 100 kB\nMemAvailable: 380 kB\n',
+      ),
+    ).toBe(62);
+  });
+
+  it('throws when MemTotal is not positive', () => {
+    expect(() =>
+      parseMemoryUsedPercent('MemTotal: 0 kB\nMemAvailable: 0 kB\n'),
+    ).toThrow();
+  });
+});
+
+describe('parseCpuSample', () => {
+  it('uses the aggregate cpu line with idle = idle + iowait and total = sum of all fields', () => {
+    expect(
+      parseCpuSample('cpu  100 0 100 700 100 0 0 0 0 0\ncpu0 1 2 3 4\n'),
+    ).toEqual({ total: 1000, idle: 800 });
+  });
+
+  it('throws when there is no aggregate cpu line', () => {
+    expect(() => parseCpuSample('cpu0 1 2 3 4\n')).toThrow();
+  });
+});
+
+describe('cpuUsedPercentFromSamples', () => {
+  it('computes (total_delta - idle_delta) / total_delta', () => {
+    expect(
+      cpuUsedPercentFromSamples(
+        { total: 1000, idle: 700 },
+        { total: 1100, idle: 770 },
+      ),
+    ).toBe(30);
+  });
+
+  it('throws when the total delta is not positive', () => {
+    expect(() =>
+      cpuUsedPercentFromSamples(
+        { total: 1000, idle: 700 },
+        { total: 1000, idle: 700 },
+      ),
+    ).toThrow();
+  });
+});
+
+describe('parseLoadAverages', () => {
+  it('parses the first three floats from /proc/loadavg', () => {
+    expect(parseLoadAverages('1.20 0.98 0.75 1/123 4567\n')).toEqual({
+      oneMinute: 1.2,
+      fiveMinute: 0.98,
+      fifteenMinute: 0.75,
+    });
+  });
+
+  it('throws when fewer than three numeric values are present', () => {
+    expect(() => parseLoadAverages('1.20 0.98\n')).toThrow();
+  });
+});
+
+describe('cycleMinutesFromMtimes', () => {
+  it('rounds the gap between the two newest generations to whole minutes', () => {
+    expect(cycleMinutesFromMtimes([1782469254.0, 1782468443.0])).toBe(14);
+  });
+
+  it('rounds a 1620 second gap to 27 minutes', () => {
+    expect(cycleMinutesFromMtimes([1620.0, 0.0])).toBe(27);
+  });
+
+  it('returns null when a second generation is missing', () => {
+    expect(cycleMinutesFromMtimes([1000.0])).toBeNull();
+    expect(cycleMinutesFromMtimes([])).toBeNull();
+  });
+});
+
+describe('ProcHostMetricsRepository', () => {
+  let procDirectory: string;
+
+  beforeEach(() => {
+    procDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-proc-host-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(procDirectory, { recursive: true, force: true });
+  });
+
+  it('reads memory used percent from /proc/meminfo', () => {
+    fs.writeFileSync(
+      path.join(procDirectory, 'meminfo'),
+      'MemTotal: 1000 kB\nMemAvailable: 380 kB\n',
+    );
+    const repository = new ProcHostMetricsRepository(procDirectory);
+    expect(repository.readMemoryUsedPercent()).toBe(62);
+  });
+
+  it('reads load averages from /proc/loadavg', () => {
+    fs.writeFileSync(
+      path.join(procDirectory, 'loadavg'),
+      '2.00 1.00 0.50 1/100 200\n',
+    );
+    const repository = new ProcHostMetricsRepository(procDirectory);
+    expect(repository.readLoadAverages()).toEqual({
+      oneMinute: 2.0,
+      fiveMinute: 1.0,
+      fifteenMinute: 0.5,
+    });
+  });
+
+  it('samples /proc/stat twice and computes the busy percent', async () => {
+    const statPath = path.join(procDirectory, 'stat');
+    let sampleIndex = 0;
+    fs.writeFileSync(statPath, 'cpu  700 0 0 300 0 0 0 0 0 0\n');
+    const sleep = async (): Promise<void> => {
+      sampleIndex += 1;
+      fs.writeFileSync(statPath, 'cpu  770 0 0 330 0 0 0 0 0 0\n');
+    };
+    const repository = new ProcHostMetricsRepository(procDirectory, sleep);
+    expect(await repository.readCpuUsedPercent()).toBe(70);
+    expect(sampleIndex).toBe(1);
+  });
+});