github-issue-tower-defence-management 1.139.0 → 1.140.0

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

@@ -0,0 +1,79 @@
+import { LocalCommandRunner } from '../../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+import {
+  TokenExhaustionHandoverUseCase,
+  DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE,
+  DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE_BARE_NAME_LEADER,
+  DEFAULT_TOKEN_EXHAUSTION_GRACE_PERIOD_SECONDS,
+} from '../../../domain/usecases/TokenExhaustionHandoverUseCase';
+import { NodeTmuxSessionRepository } from '../../repositories/NodeTmuxSessionRepository';
+import { RateLimitSnapshotRepository } from '../../repositories/RateLimitSnapshotRepository';
+import { ProcClaudeHandoverSessionRepository } from '../../repositories/ProcClaudeHandoverSessionRepository';
+import { NodeProcessSignalRepository } from '../../repositories/NodeProcessSignalRepository';
+import {
+  FileHandoverStateRepository,
+  defaultHandoverStateFilePath,
+} from '../../repositories/FileHandoverStateRepository';
+
+export type TokenExhaustionHandoverParams = {
+  enabled: boolean;
+  tokenListJsonPath: string | null;
+  handoverMessage?: string | null;
+  bareNameLeaderHandoverMessage?: string | null;
+  tokenRateLimitSnapshotBaseDir?: string | null;
+  gracePeriodSeconds?: number | null;
+  stateFilePath?: string | null;
+  localCommandRunner: LocalCommandRunner;
+  now: Date;
+};
+
+export const handleTokenExhaustionHandover = async (
+  params: TokenExhaustionHandoverParams,
+): Promise<void> => {
+  const {
+    enabled,
+    tokenListJsonPath,
+    handoverMessage,
+    bareNameLeaderHandoverMessage,
+    tokenRateLimitSnapshotBaseDir,
+    gracePeriodSeconds,
+    stateFilePath,
+    localCommandRunner,
+    now,
+  } = params;
+
+  if (tokenListJsonPath === null) {
+    console.log(
+      'Token exhaustion handover: skipped (no claudeCodeOauthTokenListJsonPath configured).',
+    );
+    return;
+  }
+
+  const snapshotRepository = new RateLimitSnapshotRepository(
+    tokenListJsonPath,
+    tokenRateLimitSnapshotBaseDir ?? undefined,
+  );
+  const stateRepository = new FileHandoverStateRepository(
+    stateFilePath ?? defaultHandoverStateFilePath(),
+  );
+  const useCase = new TokenExhaustionHandoverUseCase(
+    new ProcClaudeHandoverSessionRepository(),
+    snapshotRepository,
+    new NodeTmuxSessionRepository(localCommandRunner),
+    new NodeProcessSignalRepository(),
+  );
+
+  const result = await useCase.run({
+    enabled,
+    issueUrlLeaderMessage:
+      handoverMessage ?? DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE,
+    bareNameLeaderMessage:
+      bareNameLeaderHandoverMessage ??
+      DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE_BARE_NAME_LEADER,
+    gracePeriodSeconds:
+      gracePeriodSeconds ?? DEFAULT_TOKEN_EXHAUSTION_GRACE_PERIOD_SECONDS,
+    state: stateRepository.load(),
+    now,
+  });
+
+  stateRepository.save(result.state);
+};

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

@@ -0,0 +1,114 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  FileHandoverStateRepository,
+  defaultHandoverStateFilePath,
+} from './FileHandoverStateRepository';
+
+describe('FileHandoverStateRepository', () => {
+  let directory: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'handover-state-'));
+    filePath = path.join(directory, 'nested', 'state.json');
+  });
+
+  afterEach(() => {
+    fs.rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('returns an empty state when the file does not exist', () => {
+    const repository = new FileHandoverStateRepository(filePath);
+
+    expect(repository.load()).toEqual({ entries: {} });
+  });
+
+  it('saves and reloads state, creating parent directories', () => {
+    const repository = new FileHandoverStateRepository(filePath);
+    const state = {
+      entries: {
+        'session-a': { signaledAtEpoch: 1700000000, pid: 4242 },
+      },
+    };
+
+    repository.save(state);
+
+    expect(fs.existsSync(filePath)).toBe(true);
+    expect(new FileHandoverStateRepository(filePath).load()).toEqual(state);
+  });
+
+  it('writes atomically via a temporary file and leaves no temp file behind', () => {
+    const repository = new FileHandoverStateRepository(filePath);
+
+    repository.save({
+      entries: { 'session-a': { signaledAtEpoch: 1, pid: 2 } },
+    });
+
+    expect(fs.existsSync(`${filePath}.tmp`)).toBe(false);
+  });
+
+  it('returns an empty state when the file contains invalid JSON', () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, 'not json');
+    const repository = new FileHandoverStateRepository(filePath);
+
+    expect(repository.load()).toEqual({ entries: {} });
+  });
+
+  it('drops entries with malformed values while keeping valid ones', () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(
+      filePath,
+      JSON.stringify({
+        entries: {
+          valid: { signaledAtEpoch: 5, pid: 6 },
+          missingPid: { signaledAtEpoch: 5 },
+          notAnObject: 7,
+        },
+      }),
+    );
+    const repository = new FileHandoverStateRepository(filePath);
+
+    expect(repository.load()).toEqual({
+      entries: { valid: { signaledAtEpoch: 5, pid: 6 } },
+    });
+  });
+});
+
+describe('defaultHandoverStateFilePath', () => {
+  const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+
+  afterEach(() => {
+    if (originalXdgCacheHome === undefined) {
+      delete process.env.XDG_CACHE_HOME;
+    } else {
+      process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+  });
+
+  it('uses a TDPM-native filename distinct from the standalone monitor state file', () => {
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    expect(defaultHandoverStateFilePath()).toBe(
+      '/custom/cache/tdpm/token-exhaustion-handover-state-tdpm-native.json',
+    );
+    expect(defaultHandoverStateFilePath()).not.toBe(
+      '/custom/cache/tdpm/token-exhaustion-handover-state.json',
+    );
+  });
+
+  it('falls back to ~/.cache when XDG_CACHE_HOME is unset', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(defaultHandoverStateFilePath()).toBe(
+      path.join(
+        os.homedir(),
+        '.cache',
+        'tdpm',
+        'token-exhaustion-handover-state-tdpm-native.json',
+      ),
+    );
+  });
+});

package/src/adapter/repositories/FileHandoverStateRepository.ts

@@ -0,0 +1,76 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  TokenExhaustionHandoverState,
+  TokenExhaustionHandoverStateEntry,
+} from '../../domain/entities/TokenExhaustionHandoverState';
+import { TokenExhaustionHandoverStateRepository } from '../../domain/usecases/adapter-interfaces/TokenExhaustionHandoverStateRepository';
+
+export const defaultHandoverStateFilePath = (): string => {
+  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
+  return path.join(
+    base,
+    'tdpm',
+    'token-exhaustion-handover-state-tdpm-native.json',
+  );
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export class FileHandoverStateRepository implements TokenExhaustionHandoverStateRepository {
+  constructor(
+    private readonly filePath: string = defaultHandoverStateFilePath(),
+  ) {}
+
+  load = (): TokenExhaustionHandoverState => {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.filePath, 'utf8');
+    } catch {
+      return { entries: {} };
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return { entries: {} };
+    }
+    return { entries: this.parseEntries(parsed) };
+  };
+
+  save = (state: TokenExhaustionHandoverState): void => {
+    const directory = path.dirname(this.filePath);
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+    const temporaryPath = `${this.filePath}.tmp`;
+    fs.writeFileSync(temporaryPath, JSON.stringify(state));
+    fs.renameSync(temporaryPath, this.filePath);
+  };
+
+  private parseEntries = (
+    parsed: unknown,
+  ): Record<string, TokenExhaustionHandoverStateEntry> => {
+    const entries: Record<string, TokenExhaustionHandoverStateEntry> = {};
+    if (!isRecord(parsed)) {
+      return entries;
+    }
+    const stored = parsed.entries;
+    if (!isRecord(stored)) {
+      return entries;
+    }
+    for (const [key, value] of Object.entries(stored)) {
+      if (!isRecord(value)) {
+        continue;
+      }
+      const signaledAtEpoch = value.signaledAtEpoch;
+      const pid = value.pid;
+      if (typeof signaledAtEpoch === 'number' && typeof pid === 'number') {
+        entries[key] = { signaledAtEpoch, pid };
+      }
+    }
+    return entries;
+  };
+}

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

@@ -0,0 +1,127 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { FileSystemSilentSessionNotifiedStateRepository } from './FileSystemSilentSessionNotifiedStateRepository';
+
+describe('FileSystemSilentSessionNotifiedStateRepository', () => {
+  let rootDirectory: string;
+  let stateFilePath: string;
+
+  beforeEach(() => {
+    rootDirectory = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'silent-session-notified-state-'),
+    );
+    stateFilePath = path.join(rootDirectory, 'silent-session-notified.json');
+  });
+
+  afterEach(() => {
+    fs.rmSync(rootDirectory, { force: true, recursive: true });
+  });
+
+  const sessionAlpha = 'https://github.com/HiromiShikata/repo/issues/100';
+  const sessionBravo = 'https://github.com/HiromiShikata/repo/issues/200';
+
+  it('round-trips a saved notified set so the next cycle reads it back', async () => {
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+    const now = new Date('2026-06-26T00:00:00Z');
+
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha, sessionBravo],
+      now,
+    });
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:01:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set([sessionAlpha, sessionBravo]));
+  });
+
+  it('returns an empty set when no state file exists yet', async () => {
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:00:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set<string>());
+  });
+
+  it('excludes an entry older than the recency window when loading', async () => {
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha],
+      now: new Date('2026-06-26T00:00:00Z'),
+    });
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:20:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set<string>());
+  });
+
+  it('overwrites the latch on save so a pruned session no longer lingers', async () => {
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha, sessionBravo],
+      now: new Date('2026-06-26T00:00:00Z'),
+    });
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha],
+      now: new Date('2026-06-26T00:01:30Z'),
+    });
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:02:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set([sessionAlpha]));
+  });
+
+  it('refreshes the recorded timestamp on each save so a continuously latched session stays within the window', async () => {
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha],
+      now: new Date('2026-06-26T00:00:00Z'),
+    });
+    await repository.saveNotifiedSessionNames({
+      sessionNames: [sessionAlpha],
+      now: new Date('2026-06-26T00:14:00Z'),
+    });
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:20:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set([sessionAlpha]));
+  });
+
+  it('returns an empty set when the state file is not valid JSON', async () => {
+    fs.writeFileSync(stateFilePath, 'not json');
+    const repository = new FileSystemSilentSessionNotifiedStateRepository(
+      stateFilePath,
+    );
+
+    const loaded = await repository.loadRecentNotifiedSessionNames({
+      now: new Date('2026-06-26T00:00:00Z'),
+      recencyWindowSeconds: 15 * 60,
+    });
+
+    expect(loaded).toEqual(new Set<string>());
+  });
+});

package/src/adapter/repositories/FileSystemSilentSessionNotifiedStateRepository.ts

@@ -0,0 +1,108 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { SilentSessionNotifiedStateRepository } from '../../domain/usecases/adapter-interfaces/SilentSessionNotifiedStateRepository';
+
+type StoredNotifiedEntry = {
+  sessionName: string;
+  recordedEpochSeconds: number;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const defaultStateFilePath = (): string => {
+  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
+  return path.join(base, 'tdpm', 'silent-session-notified.json');
+};
+
+// Persists the fire-once latch: the set of session names that have already
+// received the current silent-episode reminder. The use case re-writes the
+// full latch each cycle with the current timestamp, keeping a session latched
+// for as long as it stays a reminder candidate (a continuous silent episode
+// produces exactly one reminder), and prunes a session the moment it stops
+// being a candidate so a later re-qualification fires again. The save
+// intentionally OVERWRITES rather than merges: the use case supplies the
+// complete latch to persist, so a pruned session must not linger.
+export class FileSystemSilentSessionNotifiedStateRepository implements SilentSessionNotifiedStateRepository {
+  constructor(
+    private readonly stateFilePath: string = defaultStateFilePath(),
+  ) {}
+
+  loadRecentNotifiedSessionNames = async (params: {
+    now: Date;
+    recencyWindowSeconds: number;
+  }): Promise<Set<string>> => {
+    const nowEpochSeconds = Math.floor(params.now.getTime() / 1000);
+    const oldestAllowedEpochSeconds =
+      nowEpochSeconds - params.recencyWindowSeconds;
+    const recentSessionNames = new Set<string>();
+    for (const entry of this.readNotifiedEntries()) {
+      if (entry.recordedEpochSeconds >= oldestAllowedEpochSeconds) {
+        recentSessionNames.add(entry.sessionName);
+      }
+    }
+    return recentSessionNames;
+  };
+
+  saveNotifiedSessionNames = async (params: {
+    sessionNames: string[];
+    now: Date;
+  }): Promise<void> => {
+    const recordedEpochSeconds = Math.floor(params.now.getTime() / 1000);
+    const notifiedBySessionName = new Map<string, StoredNotifiedEntry>();
+    for (const sessionName of params.sessionNames) {
+      notifiedBySessionName.set(sessionName, {
+        sessionName,
+        recordedEpochSeconds,
+      });
+    }
+    this.writeState(Array.from(notifiedBySessionName.values()));
+  };
+
+  private readNotifiedEntries = (): StoredNotifiedEntry[] => {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.stateFilePath, 'utf8');
+    } catch {
+      return [];
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return [];
+    }
+    if (!isRecord(parsed)) {
+      return [];
+    }
+    const storedEntries = parsed.notified;
+    if (!Array.isArray(storedEntries)) {
+      return [];
+    }
+    const entries: StoredNotifiedEntry[] = [];
+    for (const storedEntry of storedEntries) {
+      if (!isRecord(storedEntry)) {
+        continue;
+      }
+      const sessionName = storedEntry.sessionName;
+      const recordedEpochSeconds = storedEntry.recordedEpochSeconds;
+      if (
+        typeof sessionName === 'string' &&
+        typeof recordedEpochSeconds === 'number' &&
+        Number.isFinite(recordedEpochSeconds)
+      ) {
+        entries.push({ sessionName, recordedEpochSeconds });
+      }
+    }
+    return entries;
+  };
+
+  private writeState = (notified: StoredNotifiedEntry[]): void => {
+    const directory = path.dirname(this.stateFilePath);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporaryPath = `${this.stateFilePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryPath, JSON.stringify({ notified }));
+    fs.renameSync(temporaryPath, this.stateFilePath);
+  };
+}

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

@@ -0,0 +1,82 @@
+import { NodeProcessSignalRepository } from './NodeProcessSignalRepository';
+
+const errnoError = (message: string, code: string): NodeJS.ErrnoException => {
+  const error: NodeJS.ErrnoException = new Error(message);
+  error.code = code;
+  return error;
+};
+
+describe('NodeProcessSignalRepository', () => {
+  let repository: NodeProcessSignalRepository;
+  let killSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    repository = new NodeProcessSignalRepository();
+    jest.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('isProcessAlive', () => {
+    it('returns true for the current process', () => {
+      expect(repository.isProcessAlive(process.pid)).toBe(true);
+    });
+
+    it('returns false for a pid that does not exist', () => {
+      killSpy = jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('no such process', 'ESRCH');
+      });
+
+      expect(repository.isProcessAlive(999999)).toBe(false);
+      expect(killSpy).toHaveBeenCalledWith(999999, 0);
+    });
+
+    it('returns true when signalling is not permitted', () => {
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('operation not permitted', 'EPERM');
+      });
+
+      expect(repository.isProcessAlive(1)).toBe(true);
+    });
+  });
+
+  describe('terminateProcess', () => {
+    it('sends SIGTERM to the pid', () => {
+      killSpy = jest.spyOn(process, 'kill').mockReturnValue(true);
+
+      repository.terminateProcess(4242);
+
+      expect(killSpy).toHaveBeenCalledWith(4242, 'SIGTERM');
+    });
+
+    it('does not throw or log when the process already exited', () => {
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('no such process', 'ESRCH');
+      });
+
+      expect(() => repository.terminateProcess(4242)).not.toThrow();
+      expect(console.error).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('killProcess', () => {
+    it('sends SIGKILL to the pid', () => {
+      killSpy = jest.spyOn(process, 'kill').mockReturnValue(true);
+
+      repository.killProcess(4242);
+
+      expect(killSpy).toHaveBeenCalledWith(4242, 'SIGKILL');
+    });
+
+    it('logs an unexpected signalling error without throwing', () => {
+      jest.spyOn(process, 'kill').mockImplementation(() => {
+        throw errnoError('operation not permitted', 'EPERM');
+      });
+
+      expect(() => repository.killProcess(4242)).not.toThrow();
+      expect(console.error).toHaveBeenCalled();
+    });
+  });
+});

package/src/adapter/repositories/NodeProcessSignalRepository.ts

@@ -0,0 +1,47 @@
+import { ProcessSignalRepository } from '../../domain/usecases/adapter-interfaces/ProcessSignalRepository';
+
+const errorCode = (error: unknown): string | null => {
+  if (
+    error !== null &&
+    typeof error === 'object' &&
+    'code' in error &&
+    typeof error.code === 'string'
+  ) {
+    return error.code;
+  }
+  return null;
+};
+
+export class NodeProcessSignalRepository implements ProcessSignalRepository {
+  isProcessAlive = (pid: number): boolean => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return errorCode(error) === 'EPERM';
+    }
+  };
+
+  terminateProcess = (pid: number): void => {
+    this.signal(pid, 'SIGTERM');
+  };
+
+  killProcess = (pid: number): void => {
+    this.signal(pid, 'SIGKILL');
+  };
+
+  private signal = (pid: number, signal: NodeJS.Signals): void => {
+    try {
+      process.kill(pid, signal);
+    } catch (error) {
+      if (errorCode(error) === 'ESRCH') {
+        return;
+      }
+      console.error(
+        `Failed to send ${signal} to pid ${pid}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  };
+}