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

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

@@ -13,7 +13,7 @@ const createMockRunner = (): Mocked<LocalCommandRunner> => ({
 
 describe('TmuxSilentSessionNotificationRepository', () => {
   describe('sendSelfCheckNotification', () => {
-    it('sends the message literally then submits it with Enter', async () => {
+    it('wraps the message in bracketed-paste framing, sends it literally, then submits it with Enter', async () => {
       const runner = createMockRunner();
       const repository = new TmuxSilentSessionNotificationRepository(runner);
 
@@ -29,7 +29,7 @@ describe('TmuxSilentSessionNotificationRepository', () => {
           '-t',
           'https_//github_com/owner/repo/issues/9',
           '-l',
-          'self check message',
+          '\x1b[200~self check message\x1b[201~',
         ],
       ]);
       expect(runner.runCommand.mock.calls[1]).toEqual([
@@ -38,6 +38,27 @@ describe('TmuxSilentSessionNotificationRepository', () => {
       ]);
     });
 
+    it('preserves an unchanged multi-line message body inside the bracketed-paste frame', async () => {
+      const runner = createMockRunner();
+      const repository = new TmuxSilentSessionNotificationRepository(runner);
+      const multiLineMessage = 'first line\nsecond line\n\nthird line';
+
+      await repository.sendSelfCheckNotification(
+        'https_//github_com/owner/repo/issues/9',
+        multiLineMessage,
+      );
+
+      const literalArgument = runner.runCommand.mock.calls[0][1][4];
+      expect(literalArgument.startsWith('\x1b[200~')).toBe(true);
+      expect(literalArgument.endsWith('\x1b[201~')).toBe(true);
+      expect(
+        literalArgument.slice('\x1b[200~'.length, -'\x1b[201~'.length),
+      ).toBe(multiLineMessage);
+      const literalBytes = Buffer.from(literalArgument, 'utf8').toString('hex');
+      expect(literalBytes.startsWith('1b5b3230307e')).toBe(true);
+      expect(literalBytes.endsWith('1b5b3230317e')).toBe(true);
+    });
+
     it('throws when sending the message literally fails', async () => {
       const runner = createMockRunner();
       runner.runCommand.mockResolvedValueOnce({

package/src/adapter/repositories/TmuxSilentSessionNotificationRepository.ts

@@ -1,6 +1,9 @@
 import { SilentSessionNotificationRepository } from '../../domain/usecases/adapter-interfaces/SilentSessionNotificationRepository';
 import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
 
+const BRACKETED_PASTE_START = '\x1b[200~';
+const BRACKETED_PASTE_END = '\x1b[201~';
+
 export class TmuxSilentSessionNotificationRepository implements SilentSessionNotificationRepository {
   constructor(private readonly localCommandRunner: LocalCommandRunner) {}
 
@@ -8,12 +11,13 @@ export class TmuxSilentSessionNotificationRepository implements SilentSessionNot
     sessionName: string,
     message: string,
   ): Promise<void> => {
+    const framedMessage = `${BRACKETED_PASTE_START}${message}${BRACKETED_PASTE_END}`;
     const literalResult = await this.localCommandRunner.runCommand('tmux', [
       'send-keys',
       '-t',
       sessionName,
       '-l',
-      message,
+      framedMessage,
     ]);
     if (literalResult.exitCode !== 0) {
       throw new Error(

package/src/domain/entities/ClaudeHandoverSession.ts

@@ -0,0 +1,11 @@
+export type ClaudeHandoverSessionKind =
+  'issueUrlLeader' | 'bareNameLeader' | 'implSubagent';
+
+export type ClaudeHandoverSession = {
+  kind: ClaudeHandoverSessionKind;
+  pid: number;
+  token: string;
+  sessionName: string | null;
+  name: string | null;
+  issueUrl: string | null;
+};

package/src/domain/entities/TokenExhaustionHandoverState.ts

@@ -0,0 +1,8 @@
+export type TokenExhaustionHandoverStateEntry = {
+  signaledAtEpoch: number;
+  pid: number;
+};
+
+export type TokenExhaustionHandoverState = {
+  entries: Record<string, TokenExhaustionHandoverStateEntry>;
+};

package/src/domain/usecases/NotifySilentLiveSessionsUseCase.test.ts

@@ -21,6 +21,7 @@ import { OwnerCallStatusProvider } from './adapter-interfaces/OwnerCallStatusPro
 import { RefusalTailStatusProvider } from './adapter-interfaces/RefusalTailStatusProvider';
 import { SilentSessionNotificationRepository } from './adapter-interfaces/SilentSessionNotificationRepository';
 import { SilentSessionCandidateStateRepository } from './adapter-interfaces/SilentSessionCandidateStateRepository';
+import { SilentSessionNotifiedStateRepository } from './adapter-interfaces/SilentSessionNotifiedStateRepository';
 import { SilentSessionHubTaskStatusCacheRepository } from './adapter-interfaces/SilentSessionHubTaskStatusCacheRepository';
 import { SilentSessionMessageComposer } from './adapter-interfaces/SilentSessionMessageComposer';
 import { Sleeper } from './adapter-interfaces/Sleeper';
@@ -50,6 +51,7 @@ describe('NotifySilentLiveSessionsUseCase', () => {
   let mockOwnerCallStatusProvider: Mocked<OwnerCallStatusProvider>;
   let mockNotificationRepository: Mocked<SilentSessionNotificationRepository>;
   let mockCandidateStateRepository: Mocked<SilentSessionCandidateStateRepository>;
+  let mockNotifiedStateRepository: Mocked<SilentSessionNotifiedStateRepository>;
   let mockMessageComposer: Mocked<SilentSessionMessageComposer>;
   let mockSleeper: Mocked<Sleeper>;
   let mockHubTaskStatusResolver: Mocked<HubTaskStatusResolver>;
@@ -169,6 +171,12 @@ describe('NotifySilentLiveSessionsUseCase', () => {
         .mockResolvedValue(everyNameRecentSet()),
       saveCandidateSessionNames: jest.fn().mockResolvedValue(undefined),
     };
+    mockNotifiedStateRepository = {
+      loadRecentNotifiedSessionNames: jest
+        .fn()
+        .mockResolvedValue(new Set<string>()),
+      saveNotifiedSessionNames: jest.fn().mockResolvedValue(undefined),
+    };
     mockMessageComposer = {
       composeMainStalledSection: jest
         .fn()
@@ -201,6 +209,7 @@ describe('NotifySilentLiveSessionsUseCase', () => {
       mockOwnerCallStatusProvider,
       mockNotificationRepository,
       mockCandidateStateRepository,
+      mockNotifiedStateRepository,
       mockMessageComposer,
       mockSleeper,
       mockHubTaskStatusResolver,
@@ -209,6 +218,20 @@ describe('NotifySilentLiveSessionsUseCase', () => {
     );
   });
 
+  // Simulates the on-disk fire-once latch across the per-cycle fresh monitor
+  // process: load returns the currently persisted set, save overwrites it.
+  const wireStatefulNotifiedLatch = (): void => {
+    let persistedNotifiedSessionNames = new Set<string>();
+    mockNotifiedStateRepository.loadRecentNotifiedSessionNames.mockImplementation(
+      async () => new Set(persistedNotifiedSessionNames),
+    );
+    mockNotifiedStateRepository.saveNotifiedSessionNames.mockImplementation(
+      async ({ sessionNames }) => {
+        persistedNotifiedSessionNames = new Set(sessionNames);
+      },
+    );
+  };
+
   const issueFor = (overrides: Partial<Issue>): Issue => ({
     nameWithOwner: 'HiromiShikata/repo',
     number: 42,
@@ -706,7 +729,8 @@ describe('NotifySilentLiveSessionsUseCase', () => {
     ).not.toHaveBeenCalled();
   });
 
-  it('re-notifies a persistent stall on every cycle once it has been a candidate in the previous cycle', async () => {
+  it('notifies a persistent stall only once per silent episode instead of every cycle', async () => {
+    wireStatefulNotifiedLatch();
     setupLiveInteractiveSession(GITHUB_SESSION);
     mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
       [
@@ -719,18 +743,60 @@ describe('NotifySilentLiveSessionsUseCase', () => {
       ],
     );
 
+    await useCase.run(runParams());
     await useCase.run(runParams());
     await useCase.run(runParams());
 
     expect(
       mockNotificationRepository.sendSelfCheckNotification,
-    ).toHaveBeenCalledTimes(2);
+    ).toHaveBeenCalledTimes(1);
+    expect(
+      mockNotificationRepository.sendSelfCheckNotification,
+    ).toHaveBeenCalledWith(GITHUB_SESSION, MAIN_STALLED_SECTION);
+  });
+
+  it('re-notifies a session after its silent episode resolves and a new one begins', async () => {
+    wireStatefulNotifiedLatch();
+    setupLiveInteractiveSession(GITHUB_SESSION);
+    const stalled = [
+      {
+        sessionName: GITHUB_SESSION,
+        lastOutputEpochSeconds:
+          nowEpochSeconds - DEFAULT_MAIN_SILENT_THRESHOLD_SECONDS,
+        hasInProgressToolCall: false,
+      },
+    ];
+    const active = [
+      {
+        sessionName: GITHUB_SESSION,
+        lastOutputEpochSeconds: nowEpochSeconds,
+        hasInProgressToolCall: false,
+      },
+    ];
+
+    mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+      stalled,
+    );
+    await useCase.run(runParams());
+    expect(
+      mockNotificationRepository.sendSelfCheckNotification,
+    ).toHaveBeenCalledTimes(1);
+
+    mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+      active,
+    );
+    await useCase.run(runParams());
     expect(
       mockNotificationRepository.sendSelfCheckNotification,
-    ).toHaveBeenNthCalledWith(1, GITHUB_SESSION, MAIN_STALLED_SECTION);
+    ).toHaveBeenCalledTimes(1);
+
+    mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+      stalled,
+    );
+    await useCase.run(runParams());
     expect(
       mockNotificationRepository.sendSelfCheckNotification,
-    ).toHaveBeenNthCalledWith(2, GITHUB_SESSION, MAIN_STALLED_SECTION);
+    ).toHaveBeenCalledTimes(2);
   });
 
   describe('two-consecutive-cycle debounce', () => {
@@ -832,6 +898,147 @@ describe('NotifySilentLiveSessionsUseCase', () => {
     });
   });
 
+  describe('fire-once latch and input-state gating', () => {
+    const setupSilentGithubSession = (): void => {
+      setupLiveInteractiveSession(GITHUB_SESSION);
+      mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+        [
+          {
+            sessionName: GITHUB_SESSION,
+            lastOutputEpochSeconds:
+              nowEpochSeconds - DEFAULT_MAIN_SILENT_THRESHOLD_SECONDS,
+            hasInProgressToolCall: false,
+          },
+        ],
+      );
+    };
+
+    const idleSubAgent = (label: string): SubAgentActivity => ({
+      label,
+      silentSeconds: DEFAULT_SUBAGENT_SILENT_THRESHOLD_SECONDS,
+      runningSeconds: 60,
+      waitingOnExternalProcess: false,
+    });
+
+    it('loads the fire-once latch using the configured recency window', async () => {
+      setupSilentGithubSession();
+
+      await useCase.run(
+        runParams({ candidateDebounceRecencyWindowSeconds: 900 }),
+      );
+
+      expect(
+        mockNotifiedStateRepository.loadRecentNotifiedSessionNames,
+      ).toHaveBeenCalledWith({ now, recencyWindowSeconds: 900 });
+    });
+
+    it('persists the sent session in the fire-once latch on a send cycle', async () => {
+      setupSilentGithubSession();
+
+      await useCase.run(runParams());
+
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).toHaveBeenCalledWith(GITHUB_SESSION, MAIN_STALLED_SECTION);
+      expect(
+        mockNotifiedStateRepository.saveNotifiedSessionNames,
+      ).toHaveBeenCalledWith({ sessionNames: [GITHUB_SESSION], now });
+    });
+
+    it('does not re-send but keeps the latch for a session already notified this episode', async () => {
+      setupSilentGithubSession();
+      mockNotifiedStateRepository.loadRecentNotifiedSessionNames.mockResolvedValue(
+        new Set([GITHUB_SESSION]),
+      );
+
+      await useCase.run(runParams());
+
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).not.toHaveBeenCalled();
+      expect(
+        mockNotifiedStateRepository.saveNotifiedSessionNames,
+      ).toHaveBeenCalledWith({ sessionNames: [GITHUB_SESSION], now });
+    });
+
+    it('prunes the fire-once latch for a previously notified session that is no longer a candidate', async () => {
+      mockNotifiedStateRepository.loadRecentNotifiedSessionNames.mockResolvedValue(
+        new Set([GITHUB_SESSION]),
+      );
+
+      await useCase.run(runParams());
+
+      expect(
+        mockNotifiedStateRepository.saveNotifiedSessionNames,
+      ).toHaveBeenCalledWith({ sessionNames: [], now });
+    });
+
+    it('does not inject into a session whose main REPL has an in-progress tool call even when a sub-agent advisory qualifies', async () => {
+      setupLiveInteractiveSession(GITHUB_SESSION);
+      mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+        [
+          {
+            sessionName: GITHUB_SESSION,
+            lastOutputEpochSeconds: nowEpochSeconds,
+            hasInProgressToolCall: true,
+          },
+        ],
+      );
+      mockSubAgentActivityRepository.listSubAgentActivitiesBySessionName.mockResolvedValue(
+        new Map([[GITHUB_SESSION, [idleSubAgent('sub-process-1')]]]),
+      );
+
+      await useCase.run(runParams());
+
+      expect(mockMessageComposer.composeSubAgentSection).toHaveBeenCalled();
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).not.toHaveBeenCalled();
+      expect(
+        mockNotifiedStateRepository.saveNotifiedSessionNames,
+      ).toHaveBeenCalledWith({ sessionNames: [], now });
+    });
+
+    it('delivers the deferred reminder once the main REPL becomes input-ready', async () => {
+      wireStatefulNotifiedLatch();
+      setupLiveInteractiveSession(GITHUB_SESSION);
+      mockSubAgentActivityRepository.listSubAgentActivitiesBySessionName.mockResolvedValue(
+        new Map([[GITHUB_SESSION, [idleSubAgent('sub-process-1')]]]),
+      );
+
+      mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+        [
+          {
+            sessionName: GITHUB_SESSION,
+            lastOutputEpochSeconds: nowEpochSeconds,
+            hasInProgressToolCall: true,
+          },
+        ],
+      );
+      await useCase.run(runParams());
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).not.toHaveBeenCalled();
+
+      mockSessionOutputActivityRepository.listSessionOutputActivities.mockResolvedValue(
+        [
+          {
+            sessionName: GITHUB_SESSION,
+            lastOutputEpochSeconds: nowEpochSeconds,
+            hasInProgressToolCall: false,
+          },
+        ],
+      );
+      await useCase.run(runParams());
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).toHaveBeenCalledTimes(1);
+      expect(
+        mockNotificationRepository.sendSelfCheckNotification,
+      ).toHaveBeenCalledWith(GITHUB_SESSION, SUBAGENT_SECTION);
+    });
+  });
+
   describe('sub-agent state-based reminder judgment', () => {
     const hungSubAgent = (label: string): SubAgentActivity => ({
       label,
@@ -893,7 +1100,8 @@ describe('NotifySilentLiveSessionsUseCase', () => {
       ).toHaveBeenCalledWith(GITHUB_SESSION, SUBAGENT_SECTION);
     });
 
-    it('keeps notifying a hung sub-agent on every cycle while the condition holds', async () => {
+    it('notifies a hung sub-agent only once per episode instead of every cycle', async () => {
+      wireStatefulNotifiedLatch();
       setupSubAgents([hungSubAgent('sub-process-1')]);
 
       await useCase.run(runParams());
@@ -901,7 +1109,7 @@ describe('NotifySilentLiveSessionsUseCase', () => {
 
       expect(
         mockNotificationRepository.sendSelfCheckNotification,
-      ).toHaveBeenCalledTimes(2);
+      ).toHaveBeenCalledTimes(1);
     });
 
     it('never selects a waiting sub-agent for the long-running section even when quiet past both thresholds', async () => {
@@ -942,7 +1150,8 @@ describe('NotifySilentLiveSessionsUseCase', () => {
       ).toHaveBeenCalledWith(GITHUB_SESSION, SUBAGENT_SECTION);
     });
 
-    it('keeps notifying a quiet long-running sub-agent on every cycle while the condition holds', async () => {
+    it('notifies a quiet long-running sub-agent only once per episode while still evaluating it every cycle', async () => {
+      wireStatefulNotifiedLatch();
       setupSubAgents([quietLongRunningSubAgent('sub-process-1', false)]);
 
       await useCase.run(runParams());
@@ -950,7 +1159,7 @@ describe('NotifySilentLiveSessionsUseCase', () => {
 
       expect(
         mockNotificationRepository.sendSelfCheckNotification,
-      ).toHaveBeenCalledTimes(2);
+      ).toHaveBeenCalledTimes(1);
       expect(
         mockMessageComposer.composeSubAgentSection,
       ).toHaveBeenNthCalledWith(2, {
@@ -1626,6 +1835,7 @@ describe('NotifySilentLiveSessionsUseCase', () => {
         mockOwnerCallStatusProvider,
         mockNotificationRepository,
         mockCandidateStateRepository,
+        mockNotifiedStateRepository,
         mockMessageComposer,
         mockSleeper,
         mockHubTaskStatusResolver,

package/src/domain/usecases/NotifySilentLiveSessionsUseCase.ts

@@ -9,6 +9,7 @@ import { SessionSubAgentActivityRepository } from './adapter-interfaces/SessionS
 import { SilentSessionMessageComposer } from './adapter-interfaces/SilentSessionMessageComposer';
 import { SilentSessionNotificationRepository } from './adapter-interfaces/SilentSessionNotificationRepository';
 import { SilentSessionCandidateStateRepository } from './adapter-interfaces/SilentSessionCandidateStateRepository';
+import { SilentSessionNotifiedStateRepository } from './adapter-interfaces/SilentSessionNotifiedStateRepository';
 import { SilentSessionHubTaskStatusCacheRepository } from './adapter-interfaces/SilentSessionHubTaskStatusCacheRepository';
 import { Sleeper } from './adapter-interfaces/Sleeper';
 import { IssueRepository } from './adapter-interfaces/IssueRepository';
@@ -70,6 +71,7 @@ type NotifyCandidate = {
   sessionName: string;
   message: string;
   sectionLabels: string[];
+  mainInputBusy: boolean;
 };
 
 export class NotifySilentLiveSessionsUseCase {
@@ -84,6 +86,7 @@ export class NotifySilentLiveSessionsUseCase {
     private readonly ownerCallStatusProvider: OwnerCallStatusProvider,
     private readonly notificationRepository: SilentSessionNotificationRepository,
     private readonly candidateStateRepository: SilentSessionCandidateStateRepository,
+    private readonly notifiedStateRepository: SilentSessionNotifiedStateRepository,
     private readonly messageComposer: SilentSessionMessageComposer,
     private readonly sleeper: Sleeper,
     private readonly hubTaskStatusResolver: HubTaskStatusResolver | null = null,
@@ -185,8 +188,44 @@ export class NotifySilentLiveSessionsUseCase {
       `Silent live session notification: ${debouncedCandidates.length} debounced candidate(s) of ${candidates.length} current candidate(s) across ${interactiveSessions.length} interactive session(s); ${suppressedFirstCycleCount} first-cycle candidate(s) deferred until they persist into the next cycle.`,
     );
 
+    // Fire-once latch: the set of sessions already reminded during their
+    // current silent episode. A session that is still a candidate this cycle
+    // and was already reminded is NOT re-injected, so a continuous silent
+    // episode produces exactly one reminder instead of one every schedule
+    // cycle. The latch is keyed by the globally-unique session name and
+    // persisted across the per-cycle fresh monitor process on disk.
+    const currentCandidateSessionNames = new Set(
+      candidates.map((candidate) => candidate.sessionName),
+    );
+    const previouslyNotifiedSessionNames =
+      await this.notifiedStateRepository.loadRecentNotifiedSessionNames({
+        now: params.now,
+        recencyWindowSeconds: params.candidateDebounceRecencyWindowSeconds,
+      });
+
     let sentCount = 0;
+    const notifiedThisCycleSessionNames: string[] = [];
     for (const candidate of debouncedCandidates) {
+      if (previouslyNotifiedSessionNames.has(candidate.sessionName)) {
+        console.log(
+          `Skipping ${candidate.sessionName}: the current silent-episode reminder was already delivered; not re-injecting until the condition resolves and re-arises.`,
+        );
+        continue;
+      }
+      // Input-state gating: a session whose main REPL is mid-turn — currently
+      // running an in-progress tool call, which includes waiting on a
+      // long-running sub-agent — cannot accept an injected prompt cleanly, so
+      // the reminder is deferred rather than piled into a busy input box. The
+      // session stays a candidate, so it is reminded once it becomes
+      // input-ready. A tool call pending past
+      // IN_PROGRESS_TOOL_CALL_MAX_SUPPRESS_SECONDS is treated as hung and no
+      // longer counts as busy (see composeCandidate).
+      if (candidate.mainInputBusy) {
+        console.log(
+          `Skipping ${candidate.sessionName}: main REPL is not in an input-accepting state (in-progress tool call); deferring reminder until it is idle.`,
+        );
+        continue;
+      }
       if (
         !(await this.isHubTaskActive(
           candidate.sessionName,
@@ -205,6 +244,7 @@ export class NotifySilentLiveSessionsUseCase {
         candidate.message,
       );
       sentCount += 1;
+      notifiedThisCycleSessionNames.push(candidate.sessionName);
       // One line per send, grep-stable on the `Notified ` prefix: the
       // ISO-8601 UTC timestamp disambiguates concurrent schedule runs and
       // the section list records what the message actually contained.
@@ -212,6 +252,25 @@ export class NotifySilentLiveSessionsUseCase {
         `Notified ${candidate.sessionName} at=${params.now.toISOString()} sections=[${candidate.sectionLabels.join(',')}]`,
       );
     }
+
+    // Persist the latch for the next cycle: keep every already-latched session
+    // that is STILL a candidate (refreshing its timestamp so a continuous
+    // episode stays latched) plus the sessions notified this cycle, and prune
+    // any latched session that is no longer a candidate so its episode ends and
+    // a later re-qualification fires a fresh reminder.
+    const retainedNotifiedSessionNames = [
+      ...previouslyNotifiedSessionNames,
+    ].filter((sessionName) => currentCandidateSessionNames.has(sessionName));
+    const notifiedSessionNamesToPersist = Array.from(
+      new Set([
+        ...retainedNotifiedSessionNames,
+        ...notifiedThisCycleSessionNames,
+      ]),
+    );
+    await this.notifiedStateRepository.saveNotifiedSessionNames({
+      sessionNames: notifiedSessionNamesToPersist,
+      now: params.now,
+    });
   };
 
   private isHubTaskActive = async (
@@ -488,6 +547,7 @@ export class NotifySilentLiveSessionsUseCase {
       sessionName: snapshot.sessionName,
       message: sections.join('\n\n'),
       sectionLabels,
+      mainInputBusy: suppressedByInProgressToolCall,
     };
   };
 }