github-issue-tower-defence-management 1.156.2 → 1.156.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-issue-tower-defence-management",
-  "version": "1.156.2",
+  "version": "1.156.4",
   "description": "",
   "main": "bin/index.js",
   "scripts": {
@@ -75,7 +75,7 @@
     "@storybook/react-vite": "^10.5.3",
     "@tailwindcss/vite": "^4.3.3",
     "@testing-library/react": "16.3.2",
-    "@types/better-sqlite3": "7.6.13",
+    "@types/better-sqlite3": "9.6.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",

package/src/adapter/entry-points/cli/projectConfig.test.ts

@@ -78,6 +78,39 @@ describe('mergeConfigs disks', () => {
   });
 });
 
+describe('parseProjectReadmeConfig labelsNotRequiringPullRequest', () => {
+  const makeReadme = (yaml: string) =>
+    `<details>\n<summary>config</summary>\n${yaml}\n</details>`;
+
+  it('returns labelsNotRequiringPullRequest from the README config section', () => {
+    const readme = makeReadme(
+      'labelsNotRequiringPullRequest:\n  - chore\n  - accounting\n',
+    );
+    const result = parseProjectReadmeConfig(readme);
+    expect(result.labelsNotRequiringPullRequest).toEqual([
+      'chore',
+      'accounting',
+    ]);
+  });
+
+  it('does not emit a warning for labelsNotRequiringPullRequest', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    const readme = makeReadme('labelsNotRequiringPullRequest:\n  - chore\n');
+    parseProjectReadmeConfig(readme, 'https://example.com/project');
+    expect(warnSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining('labelsNotRequiringPullRequest'),
+    );
+    warnSpy.mockRestore();
+  });
+
+  it('yields undefined labelsNotRequiringPullRequest when the key is absent', () => {
+    const readme = makeReadme('defaultAgentName: impl\n');
+    expect(
+      parseProjectReadmeConfig(readme).labelsNotRequiringPullRequest,
+    ).toBeUndefined();
+  });
+});
+
 describe('parseProjectReadmeConfig labelsAsLlmAgentName', () => {
   const makeReadme = (yaml: string) =>
     `<details>\n<summary>config</summary>\n${yaml}\n</details>`;

package/src/adapter/entry-points/cli/projectConfig.ts

@@ -130,6 +130,7 @@ const knownProjectReadmeConfigKeys = [
   'awLogDirectoryPath',
   'awLogStaleThresholdMinutes',
   'labelsAsLlmAgentName',
+  'labelsNotRequiringPullRequest',
   'changeTargetPathAliases',
 ] as const;
 
@@ -272,6 +273,10 @@ export const parseProjectReadmeConfig = (
         'awLogStaleThresholdMinutes',
       ),
       labelsAsLlmAgentName: getStringArrayValue(parsed, 'labelsAsLlmAgentName'),
+      labelsNotRequiringPullRequest: getStringArrayValue(
+        parsed,
+        'labelsNotRequiringPullRequest',
+      ),
       changeTargetPathAliases: getStringRecordValue(
         parsed,
         'changeTargetPathAliases',

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

@@ -1,12 +1,10 @@
 import fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import type { RotationOrderEntry } from '../../../domain/usecases/StartPreparationUseCase';
+import { tdpmCacheDirectory } from '../../repositories/localStorageCacheDirectory';
 
-const rotationOrderFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'rotation-order.json');
-};
+const rotationOrderFilePath = (): string =>
+  path.join(tdpmCacheDirectory(), 'rotation-order.json');
 
 export const writeRotationOrderFile = (
   rotationOrder: RotationOrderEntry[],

package/src/adapter/proxy/RateLimitCache.ts

@@ -1,7 +1,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
+import { tdpmCacheDirectory } from '../repositories/localStorageCacheDirectory';
 
 export interface ModelWeeklyLimit {
   rejected: boolean;
@@ -44,10 +44,8 @@ const SEVEN_DAY_STATUS_HEADER = 'anthropic-ratelimit-unified-7d-status';
 
 const SEVEN_DAY_RESET_HEADER = 'anthropic-ratelimit-unified-7d-reset';
 
-export const cacheDir = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'ratelimit');
-};
+export const cacheDir = (): string =>
+  path.join(tdpmCacheDirectory(), 'ratelimit');
 
 export const hashToken = (token: string): string =>
   crypto.createHash(HASH_ALGORITHM).update(token).digest('hex');

package/src/adapter/repositories/FileHandoverStateRepository.ts

@@ -1,20 +1,17 @@
 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';
+import { tdpmCacheDirectory } from './localStorageCacheDirectory';
 
-export const defaultHandoverStateFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(
-    base,
-    'tdpm',
+export const defaultHandoverStateFilePath = (): string =>
+  path.join(
+    tdpmCacheDirectory(),
     'token-exhaustion-handover-state-tdpm-native.json',
   );
-};
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);

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

@@ -1,7 +1,10 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { FileSystemKevReportWatermarkRepository } from './FileSystemKevReportWatermarkRepository';
+import {
+  defaultKevReportWatermarkFilePath,
+  FileSystemKevReportWatermarkRepository,
+} from './FileSystemKevReportWatermarkRepository';
 
 describe('FileSystemKevReportWatermarkRepository', () => {
   let temporaryDirectory: string;
@@ -251,3 +254,31 @@ describe('FileSystemKevReportWatermarkRepository', () => {
     ).toBe(true);
   });
 });
+
+describe('defaultKevReportWatermarkFilePath', () => {
+  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('places the watermark file at tdpm/kev-report-watermark.json below XDG_CACHE_HOME when set', () => {
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    expect(defaultKevReportWatermarkFilePath()).toBe(
+      '/custom/cache/tdpm/kev-report-watermark.json',
+    );
+  });
+
+  it('places the watermark file at tdpm/kev-report-watermark.json below the home cache directory when XDG_CACHE_HOME is absent', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(defaultKevReportWatermarkFilePath()).toBe(
+      path.join(os.homedir(), '.cache', 'tdpm', 'kev-report-watermark.json'),
+    );
+  });
+});

package/src/adapter/repositories/FileSystemKevReportWatermarkRepository.ts

@@ -1,11 +1,11 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { KevReportWatermark } from '../../domain/entities/KevReportWatermark';
 import {
   KevReportWatermarkLoadResult,
   KevReportWatermarkRepository,
 } from '../../domain/usecases/adapter-interfaces/KevReportWatermarkRepository';
+import { tdpmCacheDirectory } from './localStorageCacheDirectory';
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -29,14 +29,12 @@ const isCalendarYmd = (value: string): boolean => {
   );
 };
 
-const defaultStateFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'kev-report-watermark.json');
-};
+export const defaultKevReportWatermarkFilePath = (): string =>
+  path.join(tdpmCacheDirectory(), 'kev-report-watermark.json');
 
 export class FileSystemKevReportWatermarkRepository implements KevReportWatermarkRepository {
   constructor(
-    private readonly stateFilePath: string = defaultStateFilePath(),
+    private readonly stateFilePath: string = defaultKevReportWatermarkFilePath(),
   ) {}
 
   load = async (): Promise<KevReportWatermarkLoadResult> => {

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

@@ -1,7 +1,10 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { FileSystemSessionDegenerationCooldownStateRepository } from './FileSystemSessionDegenerationCooldownStateRepository';
+import {
+  defaultSessionDegenerationCooldownStateFilePath,
+  FileSystemSessionDegenerationCooldownStateRepository,
+} from './FileSystemSessionDegenerationCooldownStateRepository';
 
 describe('FileSystemSessionDegenerationCooldownStateRepository', () => {
   let temporaryDirectory: string;
@@ -83,3 +86,36 @@ describe('FileSystemSessionDegenerationCooldownStateRepository', () => {
     expect(reloaded.has('fresh-session')).toBe(true);
   });
 });
+
+describe('defaultSessionDegenerationCooldownStateFilePath', () => {
+  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('places the state file at tdpm/output-degeneration-cooldown.json below XDG_CACHE_HOME when set', () => {
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    expect(defaultSessionDegenerationCooldownStateFilePath()).toBe(
+      '/custom/cache/tdpm/output-degeneration-cooldown.json',
+    );
+  });
+
+  it('places the state file at tdpm/output-degeneration-cooldown.json below the home cache directory when XDG_CACHE_HOME is absent', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(defaultSessionDegenerationCooldownStateFilePath()).toBe(
+      path.join(
+        os.homedir(),
+        '.cache',
+        'tdpm',
+        'output-degeneration-cooldown.json',
+      ),
+    );
+  });
+});

package/src/adapter/repositories/FileSystemSessionDegenerationCooldownStateRepository.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { SessionDegenerationCooldownStateRepository } from '../../domain/usecases/adapter-interfaces/SessionDegenerationCooldownStateRepository';
+import { tdpmCacheDirectory } from './localStorageCacheDirectory';
 
 type StoredResetEntry = {
   sessionName: string;
@@ -13,14 +13,12 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 
 export const DEFAULT_RESET_RETENTION_WINDOW_SECONDS = 60 * 60;
 
-const defaultStateFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'output-degeneration-cooldown.json');
-};
+export const defaultSessionDegenerationCooldownStateFilePath = (): string =>
+  path.join(tdpmCacheDirectory(), 'output-degeneration-cooldown.json');
 
 export class FileSystemSessionDegenerationCooldownStateRepository implements SessionDegenerationCooldownStateRepository {
   constructor(
-    private readonly stateFilePath: string = defaultStateFilePath(),
+    private readonly stateFilePath: string = defaultSessionDegenerationCooldownStateFilePath(),
     private readonly retentionWindowSeconds: number = DEFAULT_RESET_RETENTION_WINDOW_SECONDS,
   ) {}
 

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

@@ -3,6 +3,7 @@ import * as os from 'os';
 import * as path from 'path';
 import {
   DEFAULT_STATE_RETENTION_WINDOW_SECONDS,
+  defaultSilentSessionCandidateStateFilePath,
   FileSystemSilentSessionCandidateStateRepository,
 } from './FileSystemSilentSessionCandidateStateRepository';
 
@@ -251,3 +252,36 @@ describe('FileSystemSilentSessionCandidateStateRepository', () => {
     });
   });
 });
+
+describe('defaultSilentSessionCandidateStateFilePath', () => {
+  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('places the state file at tdpm/silent-session-candidates.json below XDG_CACHE_HOME when set', () => {
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    expect(defaultSilentSessionCandidateStateFilePath()).toBe(
+      '/custom/cache/tdpm/silent-session-candidates.json',
+    );
+  });
+
+  it('places the state file at tdpm/silent-session-candidates.json below the home cache directory when XDG_CACHE_HOME is absent', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(defaultSilentSessionCandidateStateFilePath()).toBe(
+      path.join(
+        os.homedir(),
+        '.cache',
+        'tdpm',
+        'silent-session-candidates.json',
+      ),
+    );
+  });
+});

package/src/adapter/repositories/FileSystemSilentSessionCandidateStateRepository.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { SilentSessionCandidateStateRepository } from '../../domain/usecases/adapter-interfaces/SilentSessionCandidateStateRepository';
+import { tdpmCacheDirectory } from './localStorageCacheDirectory';
 
 type StoredCandidateEntry = {
   sessionName: string;
@@ -13,10 +13,8 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 
 export const DEFAULT_STATE_RETENTION_WINDOW_SECONDS = 60 * 60;
 
-const defaultStateFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'silent-session-candidates.json');
-};
+export const defaultSilentSessionCandidateStateFilePath = (): string =>
+  path.join(tdpmCacheDirectory(), 'silent-session-candidates.json');
 
 // Persists only the candidate set used by the two-consecutive-cycle
 // debounce. The formerly persisted announced-running-sub-agent labels
@@ -28,7 +26,7 @@ const defaultStateFilePath = (): string => {
 // write.
 export class FileSystemSilentSessionCandidateStateRepository implements SilentSessionCandidateStateRepository {
   constructor(
-    private readonly stateFilePath: string = defaultStateFilePath(),
+    private readonly stateFilePath: string = defaultSilentSessionCandidateStateFilePath(),
     private readonly retentionWindowSeconds: number = DEFAULT_STATE_RETENTION_WINDOW_SECONDS,
   ) {}
 

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

@@ -3,6 +3,7 @@ import * as os from 'os';
 import * as path from 'path';
 import {
   DEFAULT_HUB_TASK_STATUS_RETENTION_WINDOW_SECONDS,
+  defaultSilentSessionHubTaskStatusCacheFilePath,
   FileSystemSilentSessionHubTaskStatusCacheRepository,
 } from './FileSystemSilentSessionHubTaskStatusCacheRepository';
 
@@ -249,3 +250,36 @@ describe('FileSystemSilentSessionHubTaskStatusCacheRepository', () => {
     expect(DEFAULT_HUB_TASK_STATUS_RETENTION_WINDOW_SECONDS).toBe(60 * 60);
   });
 });
+
+describe('defaultSilentSessionHubTaskStatusCacheFilePath', () => {
+  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('places the state file at tdpm/silent-session-hub-task-status.json below XDG_CACHE_HOME when set', () => {
+    process.env.XDG_CACHE_HOME = '/custom/cache';
+
+    expect(defaultSilentSessionHubTaskStatusCacheFilePath()).toBe(
+      '/custom/cache/tdpm/silent-session-hub-task-status.json',
+    );
+  });
+
+  it('places the state file at tdpm/silent-session-hub-task-status.json below the home cache directory when XDG_CACHE_HOME is absent', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(defaultSilentSessionHubTaskStatusCacheFilePath()).toBe(
+      path.join(
+        os.homedir(),
+        '.cache',
+        'tdpm',
+        'silent-session-hub-task-status.json',
+      ),
+    );
+  });
+});

package/src/adapter/repositories/FileSystemSilentSessionHubTaskStatusCacheRepository.ts

@@ -1,11 +1,11 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { Issue } from '../../domain/entities/Issue';
 import {
   SilentSessionHubTaskStatusCacheEntry,
   SilentSessionHubTaskStatusCacheRepository,
 } from '../../domain/usecases/adapter-interfaces/SilentSessionHubTaskStatusCacheRepository';
+import { tdpmCacheDirectory } from './localStorageCacheDirectory';
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -15,14 +15,12 @@ const isIssueState = (value: unknown): value is Issue['state'] =>
 
 export const DEFAULT_HUB_TASK_STATUS_RETENTION_WINDOW_SECONDS = 60 * 60;
 
-const defaultStateFilePath = (): string => {
-  const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'silent-session-hub-task-status.json');
-};
+export const defaultSilentSessionHubTaskStatusCacheFilePath = (): string =>
+  path.join(tdpmCacheDirectory(), 'silent-session-hub-task-status.json');
 
 export class FileSystemSilentSessionHubTaskStatusCacheRepository implements SilentSessionHubTaskStatusCacheRepository {
   constructor(
-    private readonly stateFilePath: string = defaultStateFilePath(),
+    private readonly stateFilePath: string = defaultSilentSessionHubTaskStatusCacheFilePath(),
     private readonly retentionWindowSeconds: number = DEFAULT_HUB_TASK_STATUS_RETENTION_WINDOW_SECONDS,
   ) {}
 

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

@@ -69,7 +69,7 @@ describe('FileSystemSubAgentLivenessResolver', () => {
     expect(result).toEqual(new Set());
   });
 
-  it('returns an empty set when the runtime root exists and the session has no running file', async () => {
+  it('returns null when the runtime root exists and the session has no running file', async () => {
     const resolver = new FileSystemSubAgentLivenessResolver(runtimeRoot);
 
     const result = await resolver.resolveLiveSubAgentIds({
@@ -77,7 +77,7 @@ describe('FileSystemSubAgentLivenessResolver', () => {
       mainTranscriptPath,
     });
 
-    expect(result).toEqual(new Set());
+    expect(result).toBeNull();
   });
 
   it('returns null when the configured runtime root directory does not exist', async () => {
@@ -192,7 +192,7 @@ describe('running-subagents record agent id contract with TranscriptSessionSubAg
     ]);
   });
 
-  it('reports no sub-agent when the runtime root exists and the session has no running-subagents record', async () => {
+  it('detects a working sub-agent when the runtime root exists and the session has no running-subagents record', async () => {
     const subAgentsDirectory = path.join(
       transcriptRoot,
       cwdSlug,
@@ -224,6 +224,14 @@ describe('running-subagents record agent id contract with TranscriptSessionSubAg
       new Map([[sessionName, mainTranscriptPath]]),
     );
 
-    expect(result.get(sessionName)).toBeUndefined();
+    expect(result.get(sessionName)).toEqual([
+      {
+        label: `agent-${liveAgentId}`,
+        silentSeconds: 0,
+        runningSeconds: 694800,
+        waitingOnExternalProcess: false,
+        finishedResultUnconsumed: false,
+      },
+    ]);
   });
 });

package/src/adapter/repositories/FileSystemSubAgentLivenessResolver.ts

@@ -4,12 +4,6 @@ import { SubAgentLivenessResolver } from '../../domain/usecases/adapter-interfac
 
 const RUNNING_SUBAGENTS_FILE_NAME = 'running-subagents.txt';
 
-const isMissingFileError = (error: unknown): boolean =>
-  typeof error === 'object' &&
-  error !== null &&
-  'code' in error &&
-  error.code === 'ENOENT';
-
 export class FileSystemSubAgentLivenessResolver implements SubAgentLivenessResolver {
   constructor(private readonly runtimeRootDirectory: string | null) {}
 
@@ -26,10 +20,7 @@ export class FileSystemSubAgentLivenessResolver implements SubAgentLivenessResol
     let content: string;
     try {
       content = fs.readFileSync(runningFilePath, 'utf8');
-    } catch (error) {
-      if (isMissingFileError(error) && this.hasReadableRuntimeRootDirectory()) {
-        return new Set();
-      }
+    } catch {
       return null;
     }
     const liveIds = new Set<string>();
@@ -42,17 +33,6 @@ export class FileSystemSubAgentLivenessResolver implements SubAgentLivenessResol
     return liveIds;
   };
 
-  private hasReadableRuntimeRootDirectory = (): boolean => {
-    if (this.runtimeRootDirectory === null) {
-      return false;
-    }
-    try {
-      return fs.statSync(this.runtimeRootDirectory).isDirectory();
-    } catch {
-      return false;
-    }
-  };
-
   private resolveRunningSubAgentsFilePath = (
     mainTranscriptPath: string | null,
   ): string | null => {

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import {
   localStorageCacheBaseDirectory,
   projectCacheDirectory,
+  tdpmCacheDirectory,
 } from './localStorageCacheDirectory';
 
 describe('localStorageCacheBaseDirectory', () => {
@@ -52,3 +53,29 @@ describe('projectCacheDirectory', () => {
     );
   });
 });
+
+describe('tdpmCacheDirectory', () => {
+  const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+
+  afterEach(() => {
+    if (originalXdgCacheHome === undefined) {
+      delete process.env.XDG_CACHE_HOME;
+    } else {
+      process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+  });
+
+  test('places the tdpm directory below XDG_CACHE_HOME when it is set', () => {
+    process.env.XDG_CACHE_HOME = '/var/tmp/xdg-cache-home-for-test';
+
+    expect(tdpmCacheDirectory()).toBe('/var/tmp/xdg-cache-home-for-test/tdpm');
+  });
+
+  test('places the tdpm directory below the home cache directory when XDG_CACHE_HOME is absent', () => {
+    delete process.env.XDG_CACHE_HOME;
+
+    expect(tdpmCacheDirectory()).toBe(
+      path.join(os.homedir(), '.cache', 'tdpm'),
+    );
+  });
+});

package/src/adapter/repositories/localStorageCacheDirectory.ts

@@ -1,10 +1,13 @@
 import os from 'node:os';
 import path from 'node:path';
 
-export const localStorageCacheBaseDirectory = (): string => {
+export const tdpmCacheDirectory = (): string => {
   const base = process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache');
-  return path.join(base, 'tdpm', 'cache');
+  return path.join(base, 'tdpm');
 };
 
+export const localStorageCacheBaseDirectory = (): string =>
+  path.join(tdpmCacheDirectory(), 'cache');
+
 export const projectCacheDirectory = (projectName: string): string =>
   path.join(localStorageCacheBaseDirectory(), projectName);

package/types/adapter/entry-points/cli/projectConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projectConfig.d.ts","sourceRoot":"","sources":["../../../../src/adapter/entry-points/cli/projectConfig.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gCAAgC,CAAC,EAAE,MAAM,CAAC;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wCAAwC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClE,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAsDF,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AA6CvE,eAAO,MAAM,cAAc,GAAI,gBAAgB,MAAM,KAAG,UAuEvD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,QAAQ,MAAM,EACd,aAAa,MAAM,KAClB,UAwEF,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,EACtB,cAAc,UAAU,EACxB,iBAAiB,UAAU,KAC1B,UAmFD,CAAC;AAkBH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAoDvB,CAAC"}
+{"version":3,"file":"projectConfig.d.ts","sourceRoot":"","sources":["../../../../src/adapter/entry-points/cli/projectConfig.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gCAAgC,CAAC,EAAE,MAAM,CAAC;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAC;IACzC,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wCAAwC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClE,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAsDF,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AA8CvE,eAAO,MAAM,cAAc,GAAI,gBAAgB,MAAM,KAAG,UAuEvD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,QAAQ,MAAM,EACd,aAAa,MAAM,KAClB,UA4EF,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,EACtB,cAAc,UAAU,EACxB,iBAAiB,UAAU,KAC1B,UAmFD,CAAC;AAkBH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,OAAO,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAoDvB,CAAC"}

package/types/adapter/entry-points/handlers/rotationOrderFileWriter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rotationOrderFileWriter.d.ts","sourceRoot":"","sources":["../../../../src/adapter/entry-points/handlers/rotationOrderFileWriter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAO3F,eAAO,MAAM,sBAAsB,GACjC,eAAe,kBAAkB,EAAE,KAClC,IAOF,CAAC"}
+{"version":3,"file":"rotationOrderFileWriter.d.ts","sourceRoot":"","sources":["../../../../src/adapter/entry-points/handlers/rotationOrderFileWriter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAM3F,eAAO,MAAM,sBAAsB,GACjC,eAAe,kBAAkB,EAAE,KAClC,IAOF,CAAC"}

package/types/adapter/proxy/RateLimitCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimitCache.d.ts","sourceRoot":"","sources":["../../../src/adapter/proxy/RateLimitCache.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAIlD,eAAO,MAAM,uCAAuC,KAAK,CAAC;AAE1D,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAQzD,eAAO,MAAM,QAAQ,QAAO,MAG3B,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,MACqB,CAAC;AAEhE,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,MAAwD,CAAC;AAsD5D,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,EACb,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,aAAY,MAAM,GAAG,IAAW,KAC/B,IAoDF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,EACb,QAAQ,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACvC,IAkBF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,WAAW,MAAM,GAAG,IAAI,KAAG,OACL,CAAC;AAEpD,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAUD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,KACrD,uBAWF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,EACb,mBAAmB,MAAM,GAAG,IAAI,EAChC,gBAAe,MAAM,GAAG,IAAW,KAClC,IAQF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,IAYF,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA0BjC,CAAC;AAOF,eAAO,MAAM,+BAA+B,GAC1C,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAmBjC,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,iBAAiB,GAAG,IAuEtB,CAAC"}
+{"version":3,"file":"RateLimitCache.d.ts","sourceRoot":"","sources":["../../../src/adapter/proxy/RateLimitCache.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAIlD,eAAO,MAAM,uCAAuC,KAAK,CAAC;AAE1D,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAQzD,eAAO,MAAM,QAAQ,QAAO,MACkB,CAAC;AAE/C,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,MACqB,CAAC;AAEhE,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,MAAwD,CAAC;AAsD5D,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,EACb,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,aAAY,MAAM,GAAG,IAAW,KAC/B,IAoDF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,EACb,QAAQ,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACvC,IAkBF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,WAAW,MAAM,GAAG,IAAI,KAAG,OACL,CAAC;AAEpD,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAUD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,KACrD,uBAWF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,EACb,mBAAmB,MAAM,GAAG,IAAI,EAChC,gBAAe,MAAM,GAAG,IAAW,KAClC,IAQF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,IAYF,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA0BjC,CAAC;AAOF,eAAO,MAAM,+BAA+B,GAC1C,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAmBjC,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,EACb,UAAS,MAAmB,KAC3B,iBAAiB,GAAG,IAuEtB,CAAC"}

package/types/adapter/repositories/FileHandoverStateRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileHandoverStateRepository.d.ts","sourceRoot":"","sources":["../../../src/adapter/repositories/FileHandoverStateRepository.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,4BAA4B,EAE7B,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,sCAAsC,EAAE,MAAM,iFAAiF,CAAC;AAEzI,eAAO,MAAM,4BAA4B,QAAO,MAO/C,CAAC;AAKF,qBAAa,2BAA4B,YAAW,sCAAsC;IAEtF,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,MAAuC;IAGpE,IAAI,QAAO,4BAA4B,CAcrC;IAEF,IAAI,GAAI,OAAO,4BAA4B,KAAG,IAAI,CAQhD;IAEF,OAAO,CAAC,YAAY,CAsBlB;CACH"}
+{"version":3,"file":"FileHandoverStateRepository.d.ts","sourceRoot":"","sources":["../../../src/adapter/repositories/FileHandoverStateRepository.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,4BAA4B,EAE7B,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,sCAAsC,EAAE,MAAM,iFAAiF,CAAC;AAGzI,eAAO,MAAM,4BAA4B,QAAO,MAI7C,CAAC;AAKJ,qBAAa,2BAA4B,YAAW,sCAAsC;IAEtF,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,MAAuC;IAGpE,IAAI,QAAO,4BAA4B,CAcrC;IAEF,IAAI,GAAI,OAAO,4BAA4B,KAAG,IAAI,CAQhD;IAEF,OAAO,CAAC,YAAY,CAsBlB;CACH"}

package/types/adapter/repositories/FileSystemKevReportWatermarkRepository.d.ts

@@ -1,5 +1,6 @@
 import { KevReportWatermark } from '../../domain/entities/KevReportWatermark';
 import { KevReportWatermarkLoadResult, KevReportWatermarkRepository } from '../../domain/usecases/adapter-interfaces/KevReportWatermarkRepository';
+export declare const defaultKevReportWatermarkFilePath: () => string;
 export declare class FileSystemKevReportWatermarkRepository implements KevReportWatermarkRepository {
     private readonly stateFilePath;
     constructor(stateFilePath?: string);

package/types/adapter/repositories/FileSystemKevReportWatermarkRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileSystemKevReportWatermarkRepository.d.ts","sourceRoot":"","sources":["../../../src/adapter/repositories/FileSystemKevReportWatermarkRepository.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC7B,MAAM,uEAAuE,CAAC;AA6B/E,qBAAa,sCAAuC,YAAW,4BAA4B;IAEvF,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,GAAE,MAA+B;IAGjE,IAAI,QAAa,OAAO,CAAC,4BAA4B,CAAC,CAiEpD;IAEF,IAAI,GAAU,WAAW,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAAC,CAazD;IAEF,OAAO,CAAC,UAAU,CAKhB;CACH"}
+{"version":3,"file":"FileSystemKevReportWatermarkRepository.d.ts","sourceRoot":"","sources":["../../../src/adapter/repositories/FileSystemKevReportWatermarkRepository.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC7B,MAAM,uEAAuE,CAAC;AAyB/E,eAAO,MAAM,iCAAiC,QAAO,MACS,CAAC;AAE/D,qBAAa,sCAAuC,YAAW,4BAA4B;IAEvF,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,GAAE,MAA4C;IAG9E,IAAI,QAAa,OAAO,CAAC,4BAA4B,CAAC,CAiEpD;IAEF,IAAI,GAAU,WAAW,kBAAkB,KAAG,OAAO,CAAC,IAAI,CAAC,CAazD;IAEF,OAAO,CAAC,UAAU,CAKhB;CACH"}

package/types/adapter/repositories/FileSystemSessionDegenerationCooldownStateRepository.d.ts

@@ -1,5 +1,6 @@
 import { SessionDegenerationCooldownStateRepository } from '../../domain/usecases/adapter-interfaces/SessionDegenerationCooldownStateRepository';
 export declare const DEFAULT_RESET_RETENTION_WINDOW_SECONDS: number;
+export declare const defaultSessionDegenerationCooldownStateFilePath: () => string;
 export declare class FileSystemSessionDegenerationCooldownStateRepository implements SessionDegenerationCooldownStateRepository {
     private readonly stateFilePath;
     private readonly retentionWindowSeconds;