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

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

@@ -10,6 +10,7 @@ import { writeMachineStatus } from './machineStatusWriter';
 import { writeTokenStatus } from './tokenStatusWriter';
 import { writeInTmuxByHumanData } from './inTmuxByHumanDataWriter';
 import { reconcileInTmuxByHumanSessions } from './inTmuxByHumanSessionReconciler';
+import { handleTokenExhaustionHandover } from './tokenExhaustionHandover';
 import { cleanStaleTmuxSessions } from './staleTmuxSessionCleaner';
 import {
   notifySilentTmuxSessions,
@@ -115,6 +116,12 @@ export class HandleScheduledEventUseCaseHandler {
       inTmuxConsoleToken?: string;
       inTmuxProjectOrder?: string[];
       inTmuxLauncherCommand?: string;
+      tokenExhaustionHandoverEnabled?: boolean;
+      tokenExhaustionHandoverMessage?: string;
+      tokenExhaustionHandoverBareNameLeaderMessage?: string;
+      tokenRateLimitSnapshotBaseDir?: string;
+      tokenExhaustionGracePeriodSeconds?: number;
+      tokenExhaustionHandoverStateFilePath?: string;
       silentNotificationEnabled?: boolean;
       ownerCallMarker?: string;
       subAgentOutputRootDirectory?: string;
@@ -554,6 +561,31 @@ export class HandleScheduledEventUseCaseHandler {
         );
       }
 
+      try {
+        await handleTokenExhaustionHandover({
+          enabled: mergedInput.tokenExhaustionHandoverEnabled ?? false,
+          tokenListJsonPath:
+            mergedInput.claudeCodeOauthTokenListJsonPath ?? null,
+          handoverMessage: mergedInput.tokenExhaustionHandoverMessage ?? null,
+          bareNameLeaderHandoverMessage:
+            mergedInput.tokenExhaustionHandoverBareNameLeaderMessage ?? null,
+          tokenRateLimitSnapshotBaseDir:
+            mergedInput.tokenRateLimitSnapshotBaseDir ?? null,
+          gracePeriodSeconds:
+            mergedInput.tokenExhaustionGracePeriodSeconds ?? null,
+          stateFilePath:
+            mergedInput.tokenExhaustionHandoverStateFilePath ?? null,
+          localCommandRunner: nodeLocalCommandRunner,
+          now: inTmuxNow,
+        });
+      } catch (error) {
+        console.error(
+          `Failed to handle token exhaustion handover: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+
       try {
         await reconcileInTmuxByHumanSessions({
           inTmuxLauncherCommand: mergedInput.inTmuxLauncherCommand ?? null,

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/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)
+        }`,
+      );
+    }
+  };
+}

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

@@ -294,4 +294,136 @@ describe('NodeTmuxSessionRepository', () => {
       ]);
     });
   });
+
+  describe('sendKeys', () => {
+    it('sends the literal text then Enter and stops when the composer is empty', async () => {
+      const runner = createMockRunner();
+      runner.runCommand
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 })
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 })
+        .mockResolvedValueOnce({
+          stdout: 'idle pane content\n> ',
+          stderr: '',
+          exitCode: 0,
+        });
+      const repository = new NodeTmuxSessionRepository(runner, '/proc', 0);
+
+      await repository.sendKeys('session-a', 'checkpoint now');
+
+      expect(runner.runCommand.mock.calls[0][1]).toEqual([
+        'send-keys',
+        '-t',
+        'session-a',
+        '-l',
+        'checkpoint now',
+      ]);
+      expect(runner.runCommand.mock.calls[1][1]).toEqual([
+        'send-keys',
+        '-t',
+        'session-a',
+        'Enter',
+      ]);
+      expect(runner.runCommand.mock.calls[2][1]).toEqual([
+        'capture-pane',
+        '-p',
+        '-t',
+        'session-a',
+      ]);
+      expect(runner.runCommand.mock.calls).toHaveLength(3);
+    });
+
+    it('re-sends Enter when the message is still visible in the composer', async () => {
+      const runner = createMockRunner();
+      runner.runCommand
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 })
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 })
+        .mockResolvedValueOnce({
+          stdout: '> checkpoint now',
+          stderr: '',
+          exitCode: 0,
+        })
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
+      const repository = new NodeTmuxSessionRepository(runner, '/proc', 0);
+
+      await repository.sendKeys('session-a', 'checkpoint now');
+
+      expect(runner.runCommand.mock.calls).toHaveLength(4);
+      expect(runner.runCommand.mock.calls[3][1]).toEqual([
+        'send-keys',
+        '-t',
+        'session-a',
+        'Enter',
+      ]);
+    });
+
+    it('throws when sending the literal text fails', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockResolvedValue({
+        stdout: '',
+        stderr: 'no session',
+        exitCode: 1,
+      });
+      const repository = new NodeTmuxSessionRepository(runner, '/proc', 0);
+
+      await expect(repository.sendKeys('session-a', 'text')).rejects.toThrow(
+        'Failed to send keys to tmux session "session-a"',
+      );
+    });
+  });
+
+  describe('launchBareNameLeaderSession', () => {
+    it('creates a detached tmux session running cl for the bare name', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockResolvedValue({
+        stdout: '',
+        stderr: '',
+        exitCode: 0,
+      });
+      const repository = new NodeTmuxSessionRepository(runner);
+
+      await repository.launchBareNameLeaderSession('app');
+
+      expect(runner.runCommand.mock.calls[0][0]).toBe('tmux');
+      expect(runner.runCommand.mock.calls[0][1]).toEqual([
+        'new-session',
+        '-d',
+        '-s',
+        'app',
+        'bash',
+        '-lc',
+        "cl 'app'; exec /bin/bash",
+      ]);
+    });
+
+    it('normalizes dots and colons in the session name', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockResolvedValue({
+        stdout: '',
+        stderr: '',
+        exitCode: 0,
+      });
+      const repository = new NodeTmuxSessionRepository(runner);
+
+      await repository.launchBareNameLeaderSession('tdpm-cli.v2');
+
+      expect(runner.runCommand.mock.calls[0][1][3]).toBe('tdpm-cli_v2');
+      expect(runner.runCommand.mock.calls[0][1][6]).toBe(
+        "cl 'tdpm-cli.v2'; exec /bin/bash",
+      );
+    });
+
+    it('throws when tmux fails to create the session', async () => {
+      const runner = createMockRunner();
+      runner.runCommand.mockResolvedValue({
+        stdout: '',
+        stderr: 'duplicate session',
+        exitCode: 1,
+      });
+      const repository = new NodeTmuxSessionRepository(runner);
+
+      await expect(
+        repository.launchBareNameLeaderSession('app'),
+      ).rejects.toThrow('Failed to relaunch bare-name leader session "app"');
+    });
+  });
 });