@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/attention/__tests__/attention-coordinator.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+
+import { AttentionCoordinator } from '../attention-coordinator.js';
+
+import type { IAttentionSource, TAttentionListener } from '../attention-tracker.js';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+
+class FakeSource implements IAttentionSource {
+  attended = true;
+  readonly source = 'focus' as const;
+  private readonly listeners = new Set<TAttentionListener>();
+  subscribe(listener: TAttentionListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  lost(at: string): void {
+    this.attended = false;
+    for (const listener of this.listeners) listener({ kind: 'lost', at });
+  }
+  returned(at: string): void {
+    this.attended = true;
+    for (const listener of this.listeners) listener({ kind: 'returned', at });
+  }
+  get listenerCount(): number {
+    return this.listeners.size;
+  }
+}
+
+function snapshot(
+  entries: ReadonlyArray<{
+    id: string;
+    state: 'working' | 'completed' | 'failed';
+    kind?: 'main_thread' | 'background_task';
+  }>,
+) {
+  return {
+    sessionId: 's1',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    entries: entries.map((entry) => ({
+      id: entry.id,
+      sourceId: entry.id,
+      kind: entry.kind ?? ('background_task' as const),
+      origin: { kind: 'slash_command' as const, sessionId: 's1' },
+      status: 'running' as const,
+      state: entry.state,
+      title: entry.id,
+      unread: false,
+      attention: 'none' as const,
+      visibility: 'default' as const,
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      controls: ['select' as const],
+    })),
+  } satisfies IExecutionWorkspaceSnapshot;
+}
+
+describe('AttentionCoordinator (SCREEN-1992 TC-02 wiring)', () => {
+  it('pushes one recap per unattended interval from the channel events it is fed', () => {
+    const source = new FakeSource();
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({ source, onRecap: (line) => recaps.push(line) });
+    coordinator.wire();
+    coordinator.wire();
+    expect(source.listenerCount).toBe(1);
+
+    // Before the interval: an idle main thread and a task that already finished.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'completed', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'working' },
+      ]),
+    );
+    source.lost('2026-01-01T00:00:00.000Z');
+    coordinator.onTurnSource('agent-wakeup');
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'working', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'working' },
+      ]),
+    );
+    coordinator.onComplete();
+    coordinator.onNeedsInput();
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'main:s1', state: 'completed', kind: 'main_thread' },
+        { id: 'task:done', state: 'completed' },
+        { id: 'task:a', state: 'failed' },
+      ]),
+    );
+    source.returned('2026-01-01T00:03:00.000Z');
+    expect(recaps).toEqual(['While away 3m: 1 turn finished (1 wake) · 1 needs input · 1 failed']);
+
+    // Attended activity is never recapped.
+    coordinator.onComplete();
+    source.lost('2026-01-01T00:10:00.000Z');
+    source.returned('2026-01-01T00:11:00.000Z');
+    expect(recaps).toHaveLength(1);
+
+    coordinator.unwire();
+    expect(source.listenerCount).toBe(0);
+  });
+
+  it('starts an interval immediately when wired while the user is already away', () => {
+    const source = new FakeSource();
+    source.attended = false;
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({
+      source,
+      onRecap: (line) => recaps.push(line),
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'),
+    });
+    coordinator.wire();
+    coordinator.onTurnSource('user');
+    coordinator.onComplete();
+    source.returned('2026-01-01T00:05:00.000Z');
+    expect(recaps).toEqual(['While away 5m: 1 turn finished']);
+  });
+
+  it('takes the first snapshot as the baseline when wired while already away', () => {
+    const source = new FakeSource();
+    source.attended = false;
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({
+      source,
+      onRecap: (line) => recaps.push(line),
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'),
+    });
+    coordinator.wire();
+    // A resumed session restores an already-finished task: not news.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'task:restored', state: 'completed' },
+        { id: 'task:live', state: 'working' },
+      ]),
+    );
+    coordinator.onWorkspaceSnapshot(
+      snapshot([
+        { id: 'task:restored', state: 'completed' },
+        { id: 'task:live', state: 'failed' },
+      ]),
+    );
+    source.returned('2026-01-01T00:04:00.000Z');
+    expect(recaps).toEqual(['While away 4m: 1 failed']);
+  });
+
+  it('never reports the main thread finishing a turn as a completed entry', () => {
+    const source = new FakeSource();
+    const recaps: string[] = [];
+    const coordinator = new AttentionCoordinator({ source, onRecap: (line) => recaps.push(line) });
+    coordinator.wire();
+    // The user leaves mid-turn: the main thread is `working` when attention is lost …
+    coordinator.onWorkspaceSnapshot(
+      snapshot([{ id: 'main:s1', state: 'working', kind: 'main_thread' }]),
+    );
+    source.lost('2026-01-01T00:00:00.000Z');
+    coordinator.onTurnSource('user');
+    coordinator.onComplete();
+    // … and idle (`completed`) when they return. That is the turn, already counted, not an entry.
+    coordinator.onWorkspaceSnapshot(
+      snapshot([{ id: 'main:s1', state: 'completed', kind: 'main_thread' }]),
+    );
+    source.returned('2026-01-01T00:02:00.000Z');
+    expect(recaps).toEqual(['While away 2m: 1 turn finished']);
+  });
+});

package/src/attention/__tests__/attention-tracker.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AttentionTracker, DEFAULT_IDLE_THRESHOLD_MS } from '../attention-tracker.js';
+
+function tracker(options: { focusReporting: boolean }) {
+  const events: string[] = [];
+  const instance = new AttentionTracker({
+    focusReporting: options.focusReporting,
+    now: () => Date.now(),
+  });
+  instance.subscribe((change) => events.push(`${change.kind}@${change.at}`));
+  return { instance, events };
+}
+
+describe('AttentionTracker (SCREEN-1992 TC-01)', () => {
+  it('with focus reporting, focus-out and focus-in emit once per transition and the idle source is inert', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: true });
+      instance.start();
+      expect(instance.attended).toBe(true);
+      // Requested is not confirmed: until a focus event arrives the idle source decides.
+      expect(instance.source).toBe('idle');
+      instance.focusOut();
+      expect(instance.source).toBe('focus');
+      instance.focusOut();
+      expect(instance.attended).toBe(false);
+      expect(events).toEqual(['lost@2026-01-01T00:00:00.000Z']);
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 3);
+      instance.keystroke(); // a keystroke while focus reporting is authoritative changes nothing
+      expect(instance.attended).toBe(false);
+      vi.setSystemTime(new Date('2026-01-01T00:20:00.000Z'));
+      instance.focusIn();
+      instance.focusIn();
+      expect(events).toEqual([
+        'lost@2026-01-01T00:00:00.000Z',
+        'returned@2026-01-01T00:20:00.000Z',
+      ]);
+      instance.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('with focus reporting requested but never answered, the idle source still runs', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: true });
+      instance.start();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS);
+      expect(instance.attended).toBe(false);
+      expect(instance.source).toBe('idle');
+      instance.keystroke();
+      expect(instance.attended).toBe(true);
+      expect(events.map((event) => event.split('@')[0])).toEqual(['lost', 'returned']);
+      // The first focus event disarms the idle source for good.
+      instance.focusIn();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 2);
+      expect(instance.attended).toBe(true);
+      expect(instance.source).toBe('focus');
+      instance.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('refuses a focus event when focus reporting is off', () => {
+    const { instance } = tracker({ focusReporting: false });
+    expect(() => instance.focusIn()).toThrow(/focus reporting is off/u);
+  });
+
+  it('without focus reporting, the idle threshold marks unattended and the next keystroke marks attended', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: false });
+      expect(instance.source).toBe('idle');
+      instance.start();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS - 1);
+      instance.keystroke(); // activity resets the idle clock
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS - 1);
+      expect(instance.attended).toBe(true);
+      expect(events).toEqual([]);
+      vi.advanceTimersByTime(1);
+      expect(instance.attended).toBe(false);
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatch(/^lost@/);
+      instance.keystroke();
+      expect(instance.attended).toBe(true);
+      expect(events).toHaveLength(2);
+      expect(events[1]).toMatch(/^returned@/);
+      instance.keystroke();
+      expect(events).toHaveLength(2);
+      instance.dispose();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 2);
+      expect(events).toHaveLength(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/attention/__tests__/countdown.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatCountdown } from '../countdown.js';
+
+describe('formatCountdown (SCREEN-1992 TC-04)', () => {
+  it('renders seconds, minutes and hours against the given now, and "now" once due', () => {
+    const now = new Date('2026-01-01T00:00:00.000Z');
+    expect(formatCountdown('2026-01-01T00:00:59.000Z', now)).toBe('in 59s');
+    expect(formatCountdown('2026-01-01T00:04:59.000Z', now)).toBe('in 4m 59s');
+    expect(formatCountdown('2026-01-01T02:05:00.000Z', now)).toBe('in 2h 5m');
+    expect(formatCountdown('2026-01-01T00:00:00.000Z', now)).toBe('now');
+    expect(formatCountdown('2025-12-31T23:59:00.000Z', now)).toBe('now');
+    expect(formatCountdown('not-a-date', now)).toBeUndefined();
+  });
+});

package/src/attention/__tests__/focus-input-filter.test.ts

@@ -0,0 +1,92 @@
+import { EventEmitter } from 'node:events';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { filterFocusSequences, FocusReportingStdin } from '../focus-input-filter.js';
+import { createFocusReportingWriter } from '../../terminal-focus-reporting.js';
+
+class FakeStdin extends EventEmitter {
+  isTTY = true;
+  setRawMode = vi.fn();
+  ref = vi.fn();
+  unref = vi.fn();
+}
+
+function collect(stream: FocusReportingStdin): Buffer[] {
+  const chunks: Buffer[] = [];
+  stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+  return chunks;
+}
+
+describe('focus input filter (SCREEN-1992 TC-06)', () => {
+  it('strips CSI I / CSI O only while negotiated and forwards everything else byte-identical', () => {
+    const negotiated = filterFocusSequences(Buffer.from('a\x1b[Ob\x1b[Ic'), true);
+    expect(negotiated.forwarded.toString()).toBe('abc');
+    expect(negotiated).toMatchObject({ focusIn: 1, focusOut: 1 });
+
+    const passthrough = filterFocusSequences(Buffer.from('a\x1b[Ob'), false);
+    expect(passthrough.forwarded.toString()).toBe('a\x1b[Ob');
+    expect(passthrough).toMatchObject({ focusIn: 0, focusOut: 0 });
+
+    // A split escape sequence and a bracketed paste are Ink's to parse — untouched.
+    expect(filterFocusSequences(Buffer.from('\x1b['), true).forwarded.toString()).toBe('\x1b[');
+    expect(filterFocusSequences(Buffer.from('A'), true).forwarded.toString()).toBe('A');
+    const paste = '\x1b[200~pasted \x1b[I text\x1b[201~';
+    expect(filterFocusSequences(Buffer.from(paste), false).forwarded.toString()).toBe(paste);
+    const utf8 = Buffer.from('한글\x1b[O😀');
+    expect(filterFocusSequences(utf8, true).forwarded.toString()).toBe('한글😀');
+  });
+
+  it('proxies stdin: reports focus and keystrokes, forwards isTTY/setRawMode/ref/unref', async () => {
+    const source = new FakeStdin();
+    const hooks = {
+      negotiated: () => true,
+      onFocusIn: vi.fn(),
+      onFocusOut: vi.fn(),
+      onKeystroke: vi.fn(),
+    };
+    const proxy = new FocusReportingStdin(source, hooks);
+    const chunks = collect(proxy);
+    source.emit('data', Buffer.from('\x1b[O'));
+    source.emit('data', Buffer.from('x\x1b[I'));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(hooks.onFocusOut).toHaveBeenCalledTimes(1);
+    expect(hooks.onFocusIn).toHaveBeenCalledTimes(1);
+    expect(hooks.onKeystroke).toHaveBeenCalledTimes(1);
+    expect(Buffer.concat(chunks).toString()).toBe('x');
+
+    expect(proxy.isTTY).toBe(true);
+    proxy.setRawMode(true);
+    proxy.ref();
+    proxy.unref();
+    expect(source.setRawMode).toHaveBeenCalledWith(true);
+    expect(source.ref).toHaveBeenCalledTimes(1);
+    expect(source.unref).toHaveBeenCalledTimes(1);
+
+    proxy.detach();
+    source.emit('data', Buffer.from('y'));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(Buffer.concat(chunks).toString()).toBe('x');
+  });
+
+  it('writes DECSET 1004 only when the gate allows, and DECRST once on disable', () => {
+    const written: string[] = [];
+    let supported = false;
+    const writer = createFocusReportingWriter({
+      supported: () => supported,
+      write: (text) => written.push(text),
+    });
+    writer.enable();
+    expect(writer.negotiated).toBe(false);
+    expect(written).toEqual([]);
+    supported = true;
+    writer.enable();
+    writer.enable();
+    expect(writer.negotiated).toBe(true);
+    expect(written).toEqual(['\x1b[?1004h']);
+    writer.disable();
+    writer.disable();
+    expect(writer.negotiated).toBe(false);
+    expect(written).toEqual(['\x1b[?1004h', '\x1b[?1004l']);
+  });
+});

package/src/attention/__tests__/interval-recap.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { IntervalRecap, RECAP_MAX_WIDTH } from '../interval-recap.js';
+
+describe('IntervalRecap (SCREEN-1992 TC-02)', () => {
+  it('counts turns by source, needs-input requests and terminal entries, and yields one line on return', () => {
+    const recap = new IntervalRecap();
+    // Attended: nothing is counted.
+    recap.turnSource('user');
+    recap.turnCompleted();
+    expect(recap.onReturned('2026-01-01T00:00:00.000Z')).toBeUndefined();
+
+    // Already terminal before the interval: old news, never counted.
+    recap.entryState('task:old', 'completed');
+    recap.onLost('2026-01-01T00:00:00.000Z');
+    recap.entryState('task:old', 'completed');
+    recap.turnSource('agent-wakeup');
+    recap.turnCompleted();
+    recap.turnSource('user');
+    recap.turnCompleted();
+    recap.needsInput();
+    recap.entryState('task:1', 'working');
+    recap.entryState('task:1', 'failed');
+    recap.entryState('task:1', 'failed'); // same terminal state twice counts once
+    recap.entryState('task:2', 'completed');
+    recap.entryState('task:3', 'completed');
+    recap.entryState('task:3', 'working'); // left the terminal state again: dropped
+    recap.error();
+    const line = recap.onReturned('2026-01-01T00:12:00.000Z');
+    expect(line).toBe(
+      'While away 12m: 2 turns finished (1 wake) · 1 needs input · 1 completed · 1 failed · 1 error',
+    );
+    // A second return without a new interval yields nothing.
+    expect(recap.onReturned('2026-01-01T00:13:00.000Z')).toBeUndefined();
+  });
+
+  it('yields nothing for an empty interval and bounds a long line', () => {
+    const recap = new IntervalRecap();
+    recap.onLost('2026-01-01T00:00:00.000Z');
+    expect(recap.onReturned('2026-01-01T01:00:00.000Z')).toBeUndefined();
+
+    recap.entryState('task:seed', 'working'); // a snapshot has been seen: the baseline is known
+    recap.onLost('2026-01-01T02:00:00.000Z');
+    for (let i = 0; i < 1000; i += 1) recap.entryState(`task:${i}`, 'completed');
+    const line = recap.onReturned('2026-01-01T03:30:00.000Z')!;
+    expect(line.length).toBeLessThanOrEqual(RECAP_MAX_WIDTH);
+    expect(line).toContain('While away 1h 30m');
+  });
+});

package/src/attention/attention-coordinator.ts

@@ -0,0 +1,71 @@
+import { IntervalRecap } from './interval-recap.js';
+
+import type { IAttentionSource } from './attention-tracker.js';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * SCREEN-1992: joins the attention level to the recap accumulator for one channel.
+ *
+ * The tracker outlives channels (it is the terminal's), the recap belongs to the session being
+ * shown; the coordinator subscribes for the channel's lifetime and pushes each recap line into the
+ * channel's notice store. It lives here rather than in `tui-state-manager.ts` (at its line ceiling).
+ */
+export interface IAttentionCoordinatorOptions {
+  readonly source: IAttentionSource;
+  readonly onRecap: (line: string) => void;
+  readonly now?: () => number;
+}
+
+export class AttentionCoordinator {
+  private readonly recap = new IntervalRecap();
+  private unsubscribe: (() => void) | undefined;
+  private readonly now: () => number;
+
+  constructor(private readonly options: IAttentionCoordinatorOptions) {
+    this.now = options.now ?? Date.now;
+  }
+
+  wire(): void {
+    if (this.unsubscribe !== undefined) return;
+    // A channel created while the user is already away starts its interval now.
+    if (!this.options.source.attended) this.recap.onLost(new Date(this.now()).toISOString());
+    this.unsubscribe = this.options.source.subscribe((change) => {
+      if (change.kind === 'lost') {
+        this.recap.onLost(change.at);
+        return;
+      }
+      const line = this.recap.onReturned(change.at);
+      if (line !== undefined) this.options.onRecap(line);
+    });
+  }
+
+  unwire(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+
+  onTurnSource = (source: string): void => {
+    this.recap.turnSource(source);
+  };
+
+  onComplete = (): void => {
+    this.recap.turnCompleted();
+  };
+
+  onError = (): void => {
+    this.recap.error();
+  };
+
+  onNeedsInput = (): void => {
+    this.recap.needsInput();
+  };
+
+  onWorkspaceSnapshot = (snapshot: IExecutionWorkspaceSnapshot): void => {
+    for (const entry of snapshot.entries) {
+      // The main thread's turns are counted from `complete`; its idle `completed` is not an event.
+      if (entry.kind === 'main_thread') continue;
+      this.recap.entryState(entry.id, entry.state);
+    }
+    this.recap.snapshotComplete();
+  };
+}

package/src/attention/attention-tracker.ts

@@ -0,0 +1,124 @@
+/**
+ * SCREEN-1992: whether the user is at the terminal.
+ *
+ * Two sources feed one boolean. Focus reporting (DECSET 1004) was REQUESTED, not confirmed — a
+ * terminal that does not implement the mode discards the request and never answers — so focus
+ * becomes authoritative only once the first `CSI I`/`CSI O` has actually arrived; from then on
+ * keystrokes carry no attention meaning. Until then, and wherever the mode is off, the only signal
+ * is input: silence past the idle threshold means "away", the next keystroke means "back".
+ */
+import { MS_PER_MINUTE } from './time-units.js';
+
+const DEFAULT_IDLE_THRESHOLD_MINUTES = 5;
+export const DEFAULT_IDLE_THRESHOLD_MS = DEFAULT_IDLE_THRESHOLD_MINUTES * MS_PER_MINUTE;
+
+export type TAttentionChangeKind = 'lost' | 'returned';
+
+export interface IAttentionChange {
+  readonly kind: TAttentionChangeKind;
+  /** ISO timestamp of the transition, from the injected clock. */
+  readonly at: string;
+}
+
+export type TAttentionListener = (change: IAttentionChange) => void;
+
+/** What a consumer of attention sees: the level, and every transition. */
+export interface IAttentionSource {
+  readonly attended: boolean;
+  /** Which source decides the level right now — recorded so a degraded run is never a silent default. */
+  readonly source: 'focus' | 'idle';
+  subscribe(listener: TAttentionListener): () => void;
+}
+
+export interface IAttentionTrackerOptions {
+  /** Whether DECSET 1004 was requested; the first focus event is what makes it authoritative. */
+  readonly focusReporting: boolean;
+  readonly now: () => number;
+  readonly idleThresholdMs?: number;
+}
+
+export class AttentionTracker implements IAttentionSource {
+  private attendedState = true;
+  private focusObserved = false;
+  private readonly listeners = new Set<TAttentionListener>();
+  private idleTimer: ReturnType<typeof setTimeout> | undefined;
+  private readonly idleThresholdMs: number;
+
+  constructor(private readonly options: IAttentionTrackerOptions) {
+    this.idleThresholdMs = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+  }
+
+  get attended(): boolean {
+    return this.attendedState;
+  }
+
+  get source(): 'focus' | 'idle' {
+    return this.focusObserved ? 'focus' : 'idle';
+  }
+
+  subscribe(listener: TAttentionListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Arms the idle fallback; the first focus event disarms it for good. */
+  start(): void {
+    if (this.focusObserved) return;
+    this.armIdleTimer();
+  }
+
+  focusIn(): void {
+    this.observeFocus();
+    this.transition(true);
+  }
+
+  focusOut(): void {
+    this.observeFocus();
+    this.transition(false);
+  }
+
+  /** Any key the user pressed. Only the idle source reads it. */
+  keystroke(): void {
+    if (this.focusObserved) return;
+    this.transition(true);
+    this.armIdleTimer();
+  }
+
+  private observeFocus(): void {
+    if (!this.options.focusReporting) {
+      throw new Error('AttentionTracker: a focus event arrived although focus reporting is off.');
+    }
+    if (this.focusObserved) return;
+    this.focusObserved = true;
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = undefined;
+  }
+
+  dispose(): void {
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = undefined;
+    this.listeners.clear();
+  }
+
+  private armIdleTimer(): void {
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = undefined;
+      this.transition(false);
+    }, this.idleThresholdMs);
+    // Never keep the process alive for an attention timer.
+    if (typeof this.idleTimer === 'object' && 'unref' in this.idleTimer) this.idleTimer.unref();
+  }
+
+  private transition(attended: boolean): void {
+    if (this.attendedState === attended) return;
+    this.attendedState = attended;
+    const change: IAttentionChange = {
+      kind: attended ? 'returned' : 'lost',
+      at: new Date(this.options.now()).toISOString(),
+    };
+    for (const listener of this.listeners) listener(change);
+  }
+}

package/src/attention/countdown.ts

@@ -0,0 +1,24 @@
+import {
+  MINUTES_PER_HOUR,
+  MS_PER_SECOND,
+  SECONDS_PER_HOUR,
+  SECONDS_PER_MINUTE,
+} from './time-units.js';
+
+/**
+ * SCREEN-1992: the time until a sleeping schedule fires, rendered against a given clock so the
+ * row can tick once a second without the projection changing.
+ */
+export function formatCountdown(nextFireAt: string, now: Date): string | undefined {
+  const target = Date.parse(nextFireAt);
+  if (Number.isNaN(target)) return undefined;
+  const remainingMs = target - now.getTime();
+  if (remainingMs <= 0) return 'now';
+  const totalSeconds = Math.floor(remainingMs / MS_PER_SECOND);
+  const hours = Math.floor(totalSeconds / SECONDS_PER_HOUR);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE) % MINUTES_PER_HOUR;
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  if (hours > 0) return `in ${hours}h ${minutes}m`;
+  if (minutes > 0) return `in ${minutes}m ${seconds}s`;
+  return `in ${seconds}s`;
+}