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

package/bin/domain/usecases/TokenExhaustionHandoverUseCase.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenExhaustionHandoverUseCase = exports.TOKEN_EXHAUSTION_SEVEN_DAY_WARNING_FREE_THRESHOLD = exports.TOKEN_EXHAUSTION_FIVE_HOUR_WARNING_FREE_THRESHOLD = exports.TOKEN_EXHAUSTION_SEVEN_DAY_FREE_THRESHOLD = exports.TOKEN_EXHAUSTION_FIVE_HOUR_FREE_THRESHOLD = exports.TOKEN_EXHAUSTION_SNAPSHOT_HARD_STALE_THRESHOLD_SECONDS = exports.TOKEN_EXHAUSTION_SNAPSHOT_STALE_THRESHOLD_SECONDS = exports.DEFAULT_TOKEN_EXHAUSTION_GRACE_PERIOD_SECONDS = exports.DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE_BARE_NAME_LEADER = exports.DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE = void 0;
+exports.DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE = 'TOKEN NEAR EXHAUSTION. Within 2 minutes, write a CHECKPOINT to your assigned task issue: the in-flight subagents and what each is doing, their durable refs (branch and pull request URLs), the working directory and branch, the single concrete next action to resume, and the reason (token near exhaustion). Do this WITHOUT waiting for long-running or CI-watching subagents. Then self-kill your own tmux session with `tmux kill-session`.';
+exports.DEFAULT_TOKEN_EXHAUSTION_HANDOVER_MESSAGE_BARE_NAME_LEADER = 'TOKEN NEAR EXHAUSTION. You are a resident leader with no assigned task issue. Within 2 minutes, write a CHECKPOINT for every in-flight subagent (what each is doing and its durable refs = branch and pull request URLs, plus the single concrete next action to resume and the working directory and branch) into the GitHub issue that each subagent is working on, WITHOUT waiting for long-running or CI-watching subagents. Then stop and stay idle; do NOT self-kill. This session will be terminated and relaunched on a token that still has quota so its work is preserved.';
+exports.DEFAULT_TOKEN_EXHAUSTION_GRACE_PERIOD_SECONDS = 180;
+exports.TOKEN_EXHAUSTION_SNAPSHOT_STALE_THRESHOLD_SECONDS = 900;
+exports.TOKEN_EXHAUSTION_SNAPSHOT_HARD_STALE_THRESHOLD_SECONDS = 3600;
+exports.TOKEN_EXHAUSTION_FIVE_HOUR_FREE_THRESHOLD = 0.1;
+exports.TOKEN_EXHAUSTION_SEVEN_DAY_FREE_THRESHOLD = 0.05;
+exports.TOKEN_EXHAUSTION_FIVE_HOUR_WARNING_FREE_THRESHOLD = 0.25;
+exports.TOKEN_EXHAUSTION_SEVEN_DAY_WARNING_FREE_THRESHOLD = 0.15;
+class TokenExhaustionHandoverUseCase {
+    constructor(handoverSessionRepository, snapshotRepository, tmuxSessionRepository, processSignalRepository) {
+        this.handoverSessionRepository = handoverSessionRepository;
+        this.snapshotRepository = snapshotRepository;
+        this.tmuxSessionRepository = tmuxSessionRepository;
+        this.processSignalRepository = processSignalRepository;
+        this.run = async (input) => {
+            const nowEpochSeconds = Math.floor(input.now.getTime() / 1000);
+            const sessions = this.handoverSessionRepository.listHandoverSessions();
+            const snapshots = this.snapshotRepository.listSnapshots();
+            const snapshotByToken = new Map(snapshots.map((snapshot) => [snapshot.token, snapshot]));
+            const liveSessionNames = new Set(await this.tmuxSessionRepository.listLiveSessionNames());
+            const nextEntries = {
+                ...input.state.entries,
+            };
+            const newlyHandoverSentSessionNames = [];
+            const killedSessionNames = [];
+            const terminatedPids = [];
+            const relaunchedLeaderNames = [];
+            const leftAliveSessionNames = [];
+            for (const session of sessions) {
+                try {
+                    const snapshot = snapshotByToken.get(session.token);
+                    if (snapshot === undefined) {
+                        continue;
+                    }
+                    const hasTmux = session.kind !== 'implSubagent';
+                    const verdict = this.evaluateSnapshot(snapshot, nowEpochSeconds, hasTmux);
+                    const stateKey = this.stateKeyFor(session);
+                    if (verdict.stale) {
+                        continue;
+                    }
+                    if (!verdict.exhausted) {
+                        delete nextEntries[stateKey];
+                        continue;
+                    }
+                    if (!this.isFresherTokenAvailable(session.token, snapshots, nowEpochSeconds)) {
+                        console.log(`Token exhaustion handover: leaving ${this.displayName(session)} alive (token pool globally exhausted, no fresher token available)`);
+                        leftAliveSessionNames.push(this.displayName(session));
+                        continue;
+                    }
+                    const entry = nextEntries[stateKey];
+                    if (entry === undefined) {
+                        if (input.enabled) {
+                            await this.sendHandover(session, input);
+                        }
+                        console.log(`Token exhaustion handover: signaled ${this.displayName(session)} kind=${session.kind} reason=${verdict.reason} enabled=${input.enabled}`);
+                        nextEntries[stateKey] = {
+                            signaledAtEpoch: nowEpochSeconds,
+                            pid: session.pid,
+                        };
+                        newlyHandoverSentSessionNames.push(this.displayName(session));
+                        continue;
+                    }
+                    if (nowEpochSeconds - entry.signaledAtEpoch <
+                        input.gracePeriodSeconds) {
+                        console.log(`Token exhaustion handover: waiting for grace period for ${this.displayName(session)} remainingSeconds=${input.gracePeriodSeconds - (nowEpochSeconds - entry.signaledAtEpoch)}`);
+                        continue;
+                    }
+                    const alive = hasTmux
+                        ? session.sessionName !== null &&
+                            liveSessionNames.has(session.sessionName)
+                        : this.processSignalRepository.isProcessAlive(entry.pid);
+                    if (!alive) {
+                        if (input.enabled && this.needsRelaunch(session)) {
+                            await this.relaunchBareNameLeader(session, relaunchedLeaderNames);
+                        }
+                        delete nextEntries[stateKey];
+                        continue;
+                    }
+                    if (!input.enabled) {
+                        console.log(`Token exhaustion handover: would force-kill ${this.displayName(session)} kind=${session.kind} (dry-run, enabled=false)`);
+                        delete nextEntries[stateKey];
+                        continue;
+                    }
+                    await this.forceKill(session, entry);
+                    if (this.needsRelaunch(session)) {
+                        await this.relaunchBareNameLeader(session, relaunchedLeaderNames);
+                    }
+                    console.log(`Token exhaustion handover: force-killed ${this.displayName(session)} kind=${session.kind}`);
+                    if (hasTmux) {
+                        killedSessionNames.push(this.displayName(session));
+                    }
+                    else {
+                        terminatedPids.push(entry.pid);
+                    }
+                    delete nextEntries[stateKey];
+                }
+                catch (error) {
+                    console.error(`Token exhaustion handover: error processing ${this.displayName(session)}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            console.log(`Token exhaustion handover: cycle summary evaluated=${sessions.length} enabled=${input.enabled} signaled=${newlyHandoverSentSessionNames.length} killed=${killedSessionNames.length} terminatedPids=${terminatedPids.length} relaunched=${relaunchedLeaderNames.length} leftAlive=${leftAliveSessionNames.length}`);
+            return {
+                newlyHandoverSentSessionNames,
+                killedSessionNames,
+                terminatedPids,
+                relaunchedLeaderNames,
+                leftAliveSessionNames,
+                state: { entries: nextEntries },
+            };
+        };
+        this.needsRelaunch = (session) => session.kind === 'bareNameLeader' && session.name !== null;
+        this.relaunchBareNameLeader = async (session, relaunchedLeaderNames) => {
+            if (session.name === null) {
+                return;
+            }
+            await this.tmuxSessionRepository.launchBareNameLeaderSession(session.name);
+            relaunchedLeaderNames.push(session.name);
+        };
+        this.sendHandover = async (session, input) => {
+            if (session.kind === 'implSubagent') {
+                this.processSignalRepository.terminateProcess(session.pid);
+                return;
+            }
+            if (session.sessionName === null) {
+                return;
+            }
+            const message = session.kind === 'issueUrlLeader'
+                ? input.issueUrlLeaderMessage
+                : input.bareNameLeaderMessage;
+            await this.tmuxSessionRepository.sendKeys(session.sessionName, message);
+        };
+        this.forceKill = async (session, entry) => {
+            if (session.kind === 'implSubagent') {
+                this.processSignalRepository.killProcess(entry.pid);
+                return;
+            }
+            if (session.sessionName !== null) {
+                try {
+                    await this.tmuxSessionRepository.killSession(session.sessionName);
+                }
+                catch (error) {
+                    console.error(`Token exhaustion handover: killSession failed for ${session.sessionName}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            this.processSignalRepository.killProcess(entry.pid);
+        };
+        this.stateKeyFor = (session) => session.kind === 'implSubagent'
+            ? `pid:${session.pid}`
+            : (session.sessionName ?? `pid:${session.pid}`);
+        this.displayName = (session) => session.sessionName ?? `pid:${session.pid}`;
+        this.isFresherTokenAvailable = (currentToken, snapshots, nowEpochSeconds) => {
+            for (const snapshot of snapshots) {
+                if (snapshot.token === currentToken) {
+                    continue;
+                }
+                const verdict = this.evaluateSnapshot(snapshot, nowEpochSeconds, true);
+                if (!verdict.stale && !verdict.exhausted) {
+                    return true;
+                }
+            }
+            return false;
+        };
+        this.evaluateSnapshot = (snapshot, nowEpochSeconds, hasTmux) => {
+            const age = nowEpochSeconds - snapshot.lastUpdatedEpoch;
+            const fiveHourFree = this.freeRatio(snapshot.fiveHourUtilization, snapshot.fiveHourReset, nowEpochSeconds);
+            const sevenDayFree = this.freeRatio(snapshot.sevenDayUtilization, snapshot.sevenDayReset, nowEpochSeconds);
+            const blocked = snapshot.blocked ||
+                snapshot.rejected ||
+                snapshot.blockedUntilEpoch > nowEpochSeconds;
+            const weeklyCapped = this.isWeeklyCapped(snapshot.modelWeeklyLimits, nowEpochSeconds);
+            if (age > exports.TOKEN_EXHAUSTION_SNAPSHOT_HARD_STALE_THRESHOLD_SECONDS) {
+                return {
+                    stale: true,
+                    exhausted: false,
+                    reason: 'hard_stale',
+                    fiveHourFree,
+                    sevenDayFree,
+                    blocked,
+                    weeklyCapped,
+                };
+            }
+            const inWarningBand = fiveHourFree < exports.TOKEN_EXHAUSTION_FIVE_HOUR_WARNING_FREE_THRESHOLD ||
+                sevenDayFree < exports.TOKEN_EXHAUSTION_SEVEN_DAY_WARNING_FREE_THRESHOLD ||
+                blocked ||
+                weeklyCapped;
+            if (age > exports.TOKEN_EXHAUSTION_SNAPSHOT_STALE_THRESHOLD_SECONDS &&
+                !inWarningBand) {
+                return {
+                    stale: true,
+                    exhausted: false,
+                    reason: 'stale_healthy',
+                    fiveHourFree,
+                    sevenDayFree,
+                    blocked,
+                    weeklyCapped,
+                };
+            }
+            const exhausted = fiveHourFree < exports.TOKEN_EXHAUSTION_FIVE_HOUR_FREE_THRESHOLD ||
+                (hasTmux && sevenDayFree < exports.TOKEN_EXHAUSTION_SEVEN_DAY_FREE_THRESHOLD) ||
+                blocked ||
+                weeklyCapped;
+            const reason = weeklyCapped
+                ? 'weekly_hard_cap_rejected'
+                : fiveHourFree < exports.TOKEN_EXHAUSTION_FIVE_HOUR_FREE_THRESHOLD
+                    ? 'five_hour_free_below_threshold'
+                    : hasTmux && sevenDayFree < exports.TOKEN_EXHAUSTION_SEVEN_DAY_FREE_THRESHOLD
+                        ? 'seven_day_free_below_threshold'
+                        : blocked
+                            ? 'blocked_or_rejected'
+                            : 'healthy';
+            return {
+                stale: false,
+                exhausted,
+                reason,
+                fiveHourFree,
+                sevenDayFree,
+                blocked,
+                weeklyCapped,
+            };
+        };
+        this.freeRatio = (utilization, resetEpoch, nowEpochSeconds) => {
+            if (resetEpoch > 0 && nowEpochSeconds > resetEpoch) {
+                return 1;
+            }
+            return 1 - this.clamp01(utilization);
+        };
+        this.clamp01 = (value) => {
+            if (value < 0) {
+                return 0;
+            }
+            if (value > 1) {
+                return 1;
+            }
+            return value;
+        };
+        this.isWeeklyCapped = (modelWeeklyLimits, nowEpochSeconds) => {
+            for (const limit of modelWeeklyLimits) {
+                if (!limit.rejected) {
+                    continue;
+                }
+                if (limit.resetsAt > 0 && nowEpochSeconds > limit.resetsAt) {
+                    continue;
+                }
+                return true;
+            }
+            return false;
+        };
+    }
+}
+exports.TokenExhaustionHandoverUseCase = TokenExhaustionHandoverUseCase;
+//# sourceMappingURL=TokenExhaustionHandoverUseCase.js.map

package/bin/domain/usecases/TokenExhaustionHandoverUseCase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenExhaustionHandoverUseCase.js","sourceRoot":"","sources":["../../../src/domain/usecases/TokenExhaustionHandoverUseCase.ts"],"names":[],"mappings":"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"}

package/bin/domain/usecases/adapter-interfaces/ClaudeHandoverSessionRepository.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ClaudeHandoverSessionRepository.js.map

package/bin/domain/usecases/adapter-interfaces/ClaudeHandoverSessionRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeHandoverSessionRepository.js","sourceRoot":"","sources":["../../../../src/domain/usecases/adapter-interfaces/ClaudeHandoverSessionRepository.ts"],"names":[],"mappings":""}

package/bin/domain/usecases/adapter-interfaces/ProcessSignalRepository.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ProcessSignalRepository.js.map

package/bin/domain/usecases/adapter-interfaces/ProcessSignalRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessSignalRepository.js","sourceRoot":"","sources":["../../../../src/domain/usecases/adapter-interfaces/ProcessSignalRepository.ts"],"names":[],"mappings":""}

package/bin/domain/usecases/adapter-interfaces/TokenExhaustionHandoverStateRepository.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=TokenExhaustionHandoverStateRepository.js.map

package/bin/domain/usecases/adapter-interfaces/TokenExhaustionHandoverStateRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenExhaustionHandoverStateRepository.js","sourceRoot":"","sources":["../../../../src/domain/usecases/adapter-interfaces/TokenExhaustionHandoverStateRepository.ts"],"names":[],"mappings":""}

package/bin/domain/usecases/adapter-interfaces/TokenRateLimitSnapshotRepository.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=TokenRateLimitSnapshotRepository.js.map

package/bin/domain/usecases/adapter-interfaces/TokenRateLimitSnapshotRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRateLimitSnapshotRepository.js","sourceRoot":"","sources":["../../../../src/domain/usecases/adapter-interfaces/TokenRateLimitSnapshotRepository.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-issue-tower-defence-management",
-  "version": "1.139.1",
+  "version": "1.140.1",
   "description": "",
   "main": "bin/index.js",
   "scripts": {

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;
+  };
+}