xtralab 0.15.0 → 0.15.2

package/src/terminals/model.ts

@@ -10,101 +10,76 @@ import type { Title, Widget } from '@lumino/widgets';
 import type { IAgentSessions } from '../agentSessions';
 import { fetchRunningAgents } from './detection';
 
-/**
- * The widget shape every entry in `ITerminalTracker` takes — kept here
- * so the registry's call sites read cleanly.
- */
 export type TerminalWidget = MainAreaWidget<ITerminal.ITerminal>;
 
 /**
- * The slice of an xterm.js `Terminal` the registry reads to surface a
- * session's most recent line of output. JupyterLab keeps its xterm in the
- * terminal widget's private `_term` field, so a structural type reaches the
- * buffer without taking a dependency on `@xterm/xterm` — the same access the
- * terminal-notifications plugin already relies on. If the field is ever
- * renamed, `_term` reads back `undefined` and the activity line is simply
- * omitted: the row falls back to its title alone.
+ * Slice of xterm.js reached through the terminal widget's private `_term`
+ * field, so the buffer is readable without depending on `@xterm/xterm`.
+ * If upstream renames the field, the activity line is simply omitted.
  */
 interface IXtermBufferLine {
+  /**
+   * Whether this row is a soft-wrap continuation of the previous row.
+   */
   readonly isWrapped: boolean;
+  /**
+   * Translate the row to its text, trimming trailing whitespace on request.
+   */
   translateToString(trimRight?: boolean): string;
 }
+/**
+ * An xterm.js buffer exposing the cursor position and row access.
+ */
 interface IXtermBuffer {
+  /**
+   * Buffer row of the viewport's top line when scrolled to the bottom.
+   */
   readonly baseY: number;
+  /**
+   * The cursor's row relative to the viewport top.
+   */
   readonly cursorY: number;
+  /**
+   * Get the line at the given buffer row, or `undefined` if out of range.
+   */
   getLine(index: number): IXtermBufferLine | undefined;
 }
+/**
+ * An xterm.js terminal narrowed to its buffer namespace.
+ */
 interface IXtermTerminal {
+  /**
+   * The buffer namespace; `active` is the buffer currently on screen.
+   */
   readonly buffer: { readonly active: IXtermBuffer };
 }
+/**
+ * The terminal widget content with its private xterm.js instance exposed.
+ */
 interface ITerminalContentInternals extends ITerminal.ITerminal {
+  /**
+   * The underlying xterm.js terminal; absent until the widget creates it.
+   */
   _term?: IXtermTerminal;
 }
 
-/**
- * How often to ask the server which agent (if any) is running in each
- * terminal. Snappy enough that a manually-started agent's logo shows up
- * within a few seconds, light enough that walking the shells' process trees
- * stays negligible.
- */
 const DETECT_POLL_INTERVAL_MS = 3000;
 
-/**
- * Upper bound on the exponential backoff when detection fails repeatedly
- * (e.g. the endpoint is missing on an older server). Matches the rest of the
- * plugin's polls.
- */
 const DETECT_POLL_MAX_MS = 300_000;
 
 /**
- * Grace window after a session first appears during which an optimistic
- * launch tag outranks a `null` detection result. It covers the gap between
- * issuing an agent's command and its process actually being spawnable, so the
- * freshly-launched logo doesn't blink off if a detection poll lands in that
- * sliver. Comfortably longer than a cold agent start; short enough that a tag
- * for an agent that never really started clears quickly.
+ * Window during which a fresh launch tag outranks a `null` detection result:
+ * covers the gap between launching an agent and its process becoming visible.
  */
 const LAUNCH_GRACE_MS = 4000;
 
-/**
- * How often to re-read each open coding-agent terminal's output buffer to
- * refresh the "latest activity" line shown under its row. Brisk enough to feel
- * live while an agent works, cheap because it only walks the last screenful of
- * a handful of terminals and emits only when a line actually changes.
- */
 const ACTIVITY_POLL_INTERVAL_MS = 1500;
 
 /**
- * Source-of-truth model for the running-terminals panel. Each running
- * terminal session known to the server is one entry; the registry caches
- * the last `widget.title.label` we observed so the agent name (or any
- * xterm-published title) survives the user closing the tab while the
- * session continues running on the backend.
- *
- * For sessions running a coding agent it also surfaces a *latest activity*
- * line — the freshest meaningful line of the terminal's output, read from the
- * open tab's xterm buffer on a poll (see {@link activityFor}) — so each row
- * shows what its agent is doing, not just its name.
- *
- * It also resolves *which agent is running* in each session, so the panel can
- * badge rows with the agent's logo. Two inputs feed that, reconciled by
- * {@link agentCommandFor}:
- *   - an optimistic launch tag ({@link IAgentSessions}) written when we start
- *     an agent ourselves — instant, but blind to the agent later exiting; and
- *   - authoritative server-side process detection, polled here, which works
- *     for hand-started agents too and clears once an agent exits.
- *
- * Upstream session signals:
- *   - `serviceManager.terminals.runningChanged` is the authoritative
- *     list of live sessions; everything not in it has been shut down
- *     server-side and we must drop it.
- *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
- *     `disposed` signals keep our label cache in sync with whatever
- *     xterm/the launcher has set on the open tabs.
- *
- * `stateChanged` is emitted for every kind of update; the panel hooks it
- * through a `UseSignal` so a single subscription re-renders the list on
- * any change.
+ * Source-of-truth model for the running-terminals panel: live sessions,
+ * labels cached across tab closes, agent badges (launch tags reconciled with
+ * polled detection, see {@link agentCommandFor}), and per-row latest-activity
+ * lines. `stateChanged` fires on every kind of update.
  */
 export class SessionRegistry implements IDisposable {
   constructor(options: SessionRegistry.IOptions) {
@@ -120,18 +95,9 @@ export class SessionRegistry implements IDisposable {
     this._tracker.forEach(widget => this._trackWidget(widget));
     this._refreshLive();
 
-    // Track which terminal is the current widget in the main area so the panel
-    // can highlight its row — and highlight nothing while a notebook or any
-    // other non-terminal tab is current instead. `currentChanged` is optional
-    // on the shell interface (not every shell can switch focus), so guard it;
-    // when it is absent the highlight stays off.
     this._shell?.currentChanged?.connect(this._onShellCurrentChanged, this);
     this._updateCurrent();
 
-    // A freshly written launch tag should re-render the panel immediately
-    // (show the logo) and again once the grace window closes (so a tag for
-    // an agent that never started, or that detection later contradicts,
-    // doesn't linger).
     this._agentSessions?.changed.connect(this._onTagChanged, this);
 
     this._poll = new Poll({
@@ -145,10 +111,8 @@ export class SessionRegistry implements IDisposable {
       standby: 'when-hidden'
     });
 
-    // A second, faster poll reads the live output buffer of each open
-    // coding-agent terminal to keep its "latest activity" line current. Kept
-    // separate from the detection poll so reading xterm buffers neither delays
-    // nor is delayed by the server round-trip that drives the agent badges.
+    // Separate from the detection poll so reading xterm buffers neither
+    // delays nor is delayed by the server round-trip.
     this._activityPoll = new Poll({
       name: '@xtralab/terminals:activity',
       factory: () => this._refreshActivity(),
@@ -158,21 +122,21 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Emitted whenever the live session list, a cached label, or the detected
-   * running agent changes.
+   * Emitted on any change to the session list, labels, badges, or activity.
    */
   get stateChanged(): ISignal<this, void> {
     return this._stateChanged;
   }
 
+  /**
+   * Whether the registry has been disposed.
+   */
   get isDisposed(): boolean {
     return this._isDisposed;
   }
 
   /**
-   * Names of all live sessions, ordered by their stable rank so the
-   * rendered list keeps a consistent order (roughly creation order) as
-   * new sessions are added and old ones shut down.
+   * Names of all live sessions in stable (roughly creation) order.
    */
   sessionNames(): string[] {
     const names = Array.from(this._live);
@@ -181,23 +145,17 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * True iff the named session is still on the server. Used by the panel
-   * to skip a row during the brief window between the session's shutdown
-   * and the next `runningChanged` arriving.
+   * True iff the named session is still on the server.
    */
   has(name: string): boolean {
     return this._live.has(name);
   }
 
   /**
-   * Display name for the session. The cache wins because it only
-   * holds "real" labels (the launcher's agent name or an xterm escape
-   * sequence — see `_cacheLabel` for the filter); reading it first
-   * prevents the transient `Terminal {name}` an XTerm widget shows
-   * during reconnect from flickering into the panel. The live widget
-   * title is used when no cache exists, and the `Terminal {name}`
-   * fallback covers sessions we have never seen a widget for (e.g.
-   * surviving a lab reload).
+   * Display name for the session. The cache wins — it holds only "real"
+   * labels (see `_cacheLabel`), so the transient `Terminal {name}` an xterm
+   * widget shows during reconnect never flickers into the panel; the final
+   * fallback covers sessions never seen with a widget (e.g. a lab reload).
    */
   labelFor(name: string): string {
     const cached = this._labels.get(name);
@@ -212,18 +170,10 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * An identifier for the agent running in the session — its configured
-   * command, or its canonical id when detection matched the spawned process by
-   * id rather than by an aliased command — or `null` if none. Callers resolve
-   * it to a logo through the plugin's `iconForCommand`, which accepts either.
-   *
-   * Server-side detection is authoritative whenever it reports a running
-   * agent. A launch tag fills two gaps: the startup grace window right after
-   * we launch an agent (so its logo shows before its process is detectable),
-   * and any time detection is unavailable (older server, transient error).
-   * Once the grace window has passed and detection has reported the session
-   * as idle, the tag is ignored — that is how the badge clears when an agent
-   * exits.
+   * Agent identifier for the session (configured command or canonical id), or
+   * `null`. Detection wins when it reports an agent; a launch tag fills the
+   * grace window and detection outages, and is ignored once detection says
+   * idle — that is how the badge clears when an agent exits.
    */
   agentCommandFor(name: string): string | null {
     // `string` = detected running agent, `null` = polled and idle,
@@ -246,13 +196,9 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * The agent command server-side detection currently reports for the
-   * session, or `null` when it has not confirmed one (the session is idle,
-   * not yet covered by a poll, or detection is unavailable). Unlike
-   * {@link agentCommandFor} this never falls back to the optimistic launch
-   * tags: callers about to *write into* a session use it, and text must only
-   * ever be sent to a confirmed running agent — pasted into a shell prompt it
-   * would be executed.
+   * The agent command detection currently confirms for the session, or
+   * `null`. Never falls back to launch tags: callers about to *write into* a
+   * session use it, and text pasted into a shell prompt would be executed.
    */
   detectedCommandFor(name: string): string | null {
     const detected = this._detected.get(name);
@@ -260,13 +206,9 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * The most recent meaningful line of output from the session's terminal, or
-   * `null` when there is nothing to surface — no coding agent is running in the
-   * session, its tab is closed (so there is no live buffer to read), or the
-   * buffer holds only the agent's input box and chrome. Refreshed on a poll by
-   * {@link _refreshActivity}; shown as a smaller line under the row's title.
-   * Always `null` while the activity line is disabled (see
-   * {@link setActivityEnabled}).
+   * The most recent meaningful line of the session's output, or `null` when
+   * nothing qualifies (no running agent, closed tab, chrome-only buffer, or
+   * the activity line is disabled).
    */
   activityFor(name: string): string | null {
     if (!this._activityEnabled) {
@@ -276,11 +218,8 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Turn the per-row latest-activity line on or off, driven by the
-   * `xtralab:terminals` `showAgentActivity` setting. When turned off the
-   * activity poll stops reading terminal buffers and any cached lines are
-   * dropped, so rows fall back to their title alone; when turned back on the
-   * lines are repopulated on the spot. A no-op when the value is unchanged.
+   * Turn the per-row activity line on or off (the `showAgentActivity`
+   * setting). Off drops cached lines; on repopulates them on the spot.
    */
   setActivityEnabled(enabled: boolean): void {
     if (enabled === this._activityEnabled) {
@@ -288,8 +227,6 @@ export class SessionRegistry implements IDisposable {
     }
     this._activityEnabled = enabled;
     if (enabled) {
-      // Repopulate immediately rather than waiting for the next poll tick;
-      // `_refreshActivity` emits `stateChanged` if it finds anything to show.
       void this._refreshActivity();
     } else {
       this._activity.clear();
@@ -298,9 +235,7 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Return the open widget for a session, if any. The panel uses this to
-   * switch behavior between "activate existing tab" and "open a new tab
-   * connected to the live session".
+   * The open widget for a session, if any.
    */
   widgetFor(name: string): TerminalWidget | null {
     return (
@@ -309,22 +244,16 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Session name of the terminal that is currently the active widget in the
-   * shell's main area, or `null` when that widget is not a terminal (for
-   * example a notebook or text editor is current). The panel uses this to
-   * highlight the current terminal's row — mirroring how the file browser
-   * surfaces the open document — and to leave every row unhighlighted while a
-   * non-terminal tab is current.
+   * Session name of the terminal that is the shell's current main-area
+   * widget, or `null` when the current widget is not a terminal.
    */
   currentSessionName(): string | null {
     return this._currentName;
   }
 
   /**
-   * Stable per-session rank assigned in observation order. Used to keep
-   * the rendered list in a steady order so rows don't reshuffle as
-   * sessions come and go. Cleaned up when the session is shut down so the
-   * counter does not grow without bound across long sessions.
+   * Stable per-session rank in observation order, so rows don't reshuffle as
+   * sessions come and go.
    */
   rankFor(name: string): number {
     let rank = this._ranks.get(name);
@@ -335,6 +264,9 @@ export class SessionRegistry implements IDisposable {
     return rank;
   }
 
+  /**
+   * Dispose of the registry's polls and signal connections.
+   */
   dispose(): void {
     if (this._isDisposed) {
       return;
@@ -364,16 +296,12 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Adopt `next` as the live set and prune every per-session map for
-   * sessions that have gone away — labels, ranks, first-seen timestamps,
-   * detection results, and the shared launch tag. Without this the maps (and
-   * the rank counter) would grow without bound as terminals come and go.
+   * Adopt `next` as the live set and prune every per-session map, so the
+   * maps and rank counter don't grow without bound.
    */
   private _reconcileLive(next: Set<string>): void {
-    // Names we had already seen, captured before we prune below — the set of
-    // candidates whose launch tag may now need forgetting. (The tag map is
-    // not enumerable, so we drive the prune from the sessions we know about;
-    // `_firstSeen` has an entry for every session that has ever been live.)
+    // The tag map is not enumerable, so the tag prune below is driven from
+    // `_firstSeen`, which has an entry for every session ever live.
     const known = Array.from(this._firstSeen.keys());
 
     for (const name of next) {
@@ -407,10 +335,8 @@ export class SessionRegistry implements IDisposable {
         this._activity.delete(name);
       }
     }
-    // Forget launch tags for sessions that have gone away. This matters for
-    // correctness as well as bookkeeping: terminado reuses session names, so
-    // a stale tag could otherwise mislabel a brand-new terminal that happens
-    // to reuse a closed session's name.
+    // terminado reuses session names, so a stale tag could mislabel a
+    // brand-new terminal that reuses a closed session's name.
     for (const name of known) {
       if (!next.has(name)) {
         this._agentSessions?.delete(name);
@@ -419,9 +345,8 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Poll body: ask the server which agent runs in each terminal and update
-   * the detection map. On failure we keep the previous results rather than
-   * clearing them, so a transient error doesn't strip every badge.
+   * Poll body: update the detection map from the server. On failure the
+   * previous results are kept, so a transient error doesn't strip every badge.
    */
   private async _refreshDetection(): Promise<void> {
     const commands = this._detectCommands();
@@ -449,15 +374,9 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Poll body: re-read the buffer of each open coding-agent terminal and cache
-   * its latest meaningful line of output. Only sessions that have a running
-   * *agent* (not an editor) and an open tab qualify — a closed tab has no live
-   * buffer, editors run full-screen UIs that are not "activity", and plain
-   * shells would only echo their prompt. While a tab is reopening (its xterm
-   * is not ready yet) any existing line is kept; once the buffer is readable
-   * but has nothing worth showing the line is dropped, so a screen the agent
-   * has cleared doesn't leave a frozen line behind. Cached lines for sessions
-   * that no longer qualify are pruned. Emits only when something changed.
+   * Poll body: cache the latest meaningful output line of each open agent
+   * terminal (closed tabs have no live buffer; editors and shells don't
+   * qualify). Emits only when something changed.
    */
   private async _refreshActivity(): Promise<void> {
     if (!this._activityEnabled) {
@@ -477,8 +396,8 @@ export class SessionRegistry implements IDisposable {
       qualifying.add(name);
       const term = (widget.content as ITerminalContentInternals)._term;
       if (!term) {
-        // The tab is reopening and its xterm is not ready; keep any existing
-        // line until the buffer can be read again.
+        // The tab is reopening; keep any existing line until its xterm buffer
+        // is readable again.
         continue;
       }
       const line = Private.readActivity(term);
@@ -488,8 +407,8 @@ export class SessionRegistry implements IDisposable {
           changed = true;
         }
       } else if (this._activity.delete(name)) {
-        // Readable buffer with nothing to surface (e.g. the agent cleared its
-        // screen) — drop the now-stale line instead of freezing it.
+        // Readable buffer with nothing to surface (e.g. a cleared screen) —
+        // drop the stale line instead of freezing it.
         changed = true;
       }
     }
@@ -506,8 +425,8 @@ export class SessionRegistry implements IDisposable {
 
   private _onTagChanged(): void {
     this._stateChanged.emit();
-    // Re-render once the grace window closes so a tag that detection never
-    // confirmed (or has since contradicted) stops being shown.
+    // Re-emit once the grace window closes so a tag detection never confirmed
+    // (or has since contradicted) stops being shown.
     setTimeout(() => {
       if (!this._isDisposed) {
         this._stateChanged.emit();
@@ -525,10 +444,8 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Recompute which terminal (if any) is the active main-area widget and emit
-   * only when it changes. The terminal tracker tells us whether the shell's
-   * current widget is one of our terminals; anything else — a notebook, an
-   * editor, or nothing — clears the highlight.
+   * Recompute which terminal (if any) is the active main-area widget; emits
+   * only on change. Anything not a tracked terminal clears the highlight.
    */
   private _updateCurrent(): void {
     const current = this._shell?.currentWidget ?? null;
@@ -565,16 +482,10 @@ export class SessionRegistry implements IDisposable {
   }
 
   /**
-   * Update the cached label for a session, but only when the new
-   * label is "real" — non-empty and not one of the transient defaults
-   * the XTerm widget cycles through during reconnect (`'...'` while
-   * the websocket is opening, `'Terminal {name}'` once
-   * `_initialConnection` fires). Without the filter, briefly
-   * reopening a tab while an agent has yet to re-emit its xterm
-   * title escape sequence would clobber the cached agent name with
-   * `Terminal 1`. Live widget titles still display whatever the widget
-   * currently holds because `labelFor` consults the widget first;
-   * the filter only affects what survives a tab close.
+   * Cache a label only when it is "real" — not `'...'` or `Terminal {name}`,
+   * the transient defaults xterm cycles through during reconnect. Without the
+   * filter, reopening a tab before the agent re-emits its title escape would
+   * clobber the cached agent name.
    */
   private _cacheLabel(name: string, label: string): void {
     if (!label) {
@@ -587,11 +498,8 @@ export class SessionRegistry implements IDisposable {
   }
 
   private _onWidgetDisposed(widget: Widget): void {
-    // The widget is gone but the session may still be running on the
-    // server — keep the cached label so the panel keeps the agent's name
-    // when the user reopens the tab. We only clean up our subscriptions
-    // here; the cache is purged by `runningChanged` once the session
-    // itself goes away.
+    // The session may still be running on the server; the cached label stays
+    // until `runningChanged` purges it with the session itself.
     this._untrackWidget(widget as TerminalWidget);
     this._stateChanged.emit();
   }
@@ -621,15 +529,21 @@ export class SessionRegistry implements IDisposable {
  * Construction options for {@link SessionRegistry}.
  */
 export namespace SessionRegistry {
+  /**
+   * The instantiation options for a session registry.
+   */
   export interface IOptions {
+    /**
+     * The service manager whose terminal manager supplies the sessions.
+     */
     serviceManager: ServiceManager.IManager;
+    /**
+     * The tracker of open terminal widgets.
+     */
     tracker: ITerminalTracker;
     /**
-     * The application shell, used to tell which widget is currently active so
-     * the panel can highlight the terminal that is the current main-area
-     * widget — and highlight nothing when that widget is not a terminal (a
-     * notebook, an editor, …). Optional: without it, or on a shell that cannot
-     * report `currentChanged`, the highlight stays off.
+     * Used to highlight the row of the current main-area terminal. Optional:
+     * without it (or its `currentChanged`) the highlight stays off.
      */
     shell?: JupyterFrontEnd.IShell | null;
     /**
@@ -638,19 +552,15 @@ export namespace SessionRegistry {
      */
     agentSessions?: IAgentSessions | null;
     /**
-     * Returns the names the server should look for when detecting running
-     * agents — each agent's command together with its canonical id, so a
-     * command pointed at an alias (e.g. `ccm` running `claude`) is still
-     * matched by the process it spawns. Read on every poll so it tracks the
-     * live agent list.
+     * Names to detect: each agent's command plus its canonical id, so an
+     * aliased command (e.g. `ccm` running `claude`) is still matched by the
+     * process it spawns. Read on every poll.
      */
     detectCommands?: () => string[];
     /**
-     * Whether a detected command (or id) belongs to a coding agent rather than
-     * an editor. Only agent sessions get a latest-activity line — editors
-     * (Neovim/Vim) are badged too, but run full-screen UIs whose buffer is not
-     * meaningfully "activity". Defaults to treating every detected command as an
-     * agent.
+     * Whether a detected command (or id) belongs to a coding agent rather
+     * than an editor; only agent sessions get a latest-activity line.
+     * Defaults to treating every detected command as an agent.
      */
     isAgentCommand?: (command: string) => boolean;
   }
@@ -658,8 +568,7 @@ export namespace SessionRegistry {
 
 namespace Private {
   /**
-   * Value-equality for two detection maps, so a poll that changes nothing
-   * doesn't trigger a re-render.
+   * Whether two detection maps hold identical entries.
    */
   export function detectedEqual(
     a: Map<string, string | null>,
@@ -676,36 +585,24 @@ namespace Private {
     return true;
   }
 
-  /**
-   * Rows above the cursor to scan when looking for the latest output.
-   */
   const ACTIVITY_SCAN_ROWS = 64;
 
-  /**
-   * Clamp for the activity string so one runaway block can't bloat a row.
-   */
   const ACTIVITY_MAX_LENGTH = 160;
 
   /**
-   * Horizontal box-drawing / rule characters, treated as blanks when
-   * sanitizing. Agents pad a status line or draw a separator with these (e.g.
-   * `Worked for 1m 06s ────`), which is chrome, not text. Vertical bars are
-   * deliberately excluded — {@link isMeaningfulActivity} relies on them to
-   * recognise (and skip) the contents of an input/quote box.
+   * Horizontal rule characters treated as blanks when sanitizing (status-line
+   * padding is chrome, not text). Vertical bars are excluded on purpose —
+   * {@link isMeaningfulActivity} uses them to skip input/quote boxes.
    */
   const RULE_CHARS = new Set([
     0x2500, 0x2501, 0x2504, 0x2505, 0x2508, 0x2509, 0x254c, 0x254d, 0x2550
   ]);
 
   /**
-   * The most recent meaningful line of agent output, or `null` if none is
-   * found. Agents park the cursor in an input box at the bottom of the screen,
-   * so the scan starts there and walks *up*, skipping that box, any hint or
-   * footer beneath it, blank lines and separators, until it reaches the block
-   * of real output nearest the input. It then rewinds to that block's first row
-   * and stitches the block back together (see {@link joinBlock}), so a reply
-   * the agent hard-wrapped across several rows reads as its opening sentence
-   * rather than the trailing fragment left next to the cursor.
+   * The most recent meaningful line of agent output, or `null`. Agents park
+   * the cursor in a bottom input box, so the scan walks *up* past chrome to
+   * the nearest output block, then rewinds to that block's first row so a
+   * hard-wrapped reply reads as its opening sentence, not a trailing fragment.
    */
   export function readActivity(term: IXtermTerminal): string | null {
     const buffer = term.buffer?.active;
@@ -718,8 +615,6 @@ namespace Private {
       if (!isMeaningfulActivity(lineText(buffer, row))) {
         continue;
       }
-      // `row` is the bottom of the output block nearest the input; walk up
-      // while rows stay meaningful to find the block's first row.
       let topRow = row;
       while (
         topRow > limit &&
@@ -733,17 +628,16 @@ namespace Private {
   }
 
   /**
-   * Sanitized text of one buffer row.
+   * Read a buffer row as sanitized text; empty when the row is missing.
    */
   export function lineText(buffer: IXtermBuffer, row: number): string {
     return sanitizeActivity(buffer.getLine(row)?.translateToString(true) ?? '');
   }
 
   /**
-   * Stitch rows `[topRow, lastRow]` of one output block into a single string,
-   * stopping once it is long enough to fill the row. A soft-wrapped row
-   * continues the previous one mid-word, so it is appended directly; a hard
-   * newline is a word boundary, so it is joined with a space.
+   * Stitch rows `[topRow, lastRow]` of one output block into a single string.
+   * A soft-wrapped row continues mid-word (appended directly); a hard newline
+   * is a word boundary (joined with a space).
    */
   export function joinBlock(
     buffer: IXtermBuffer,
@@ -776,9 +670,7 @@ namespace Private {
   }
 
   /**
-   * Collapse a raw buffer row into displayable text: replace control characters
-   * and horizontal rule characters with spaces (so no escape sequence or drawn
-   * separator rides along), squeeze runs of whitespace, and trim.
+   * Replace control and rule characters with spaces and collapse whitespace.
    */
   export function sanitizeActivity(value: string): string {
     let result = '';
@@ -791,18 +683,10 @@ namespace Private {
   }
 
   /**
-   * Whether a sanitized row is worth showing as activity, i.e. real output
-   * rather than chrome. Doubles as the block-boundary test for
-   * {@link readActivity}'s walk up. A row is skipped when it:
-   *   - is blank or pure box-drawing (carries no letter or digit);
-   *   - begins with a vertical box-drawing bar (the contents of an input or
-   *     quote box), a prompt chevron (the input row and its ghost suggestion),
-   *     or Claude's tool-result / tip marker `⎿`; or
-   *   - is a transient status footer — one carrying a `for <time>` / `(<time>`
-   *     elapsed-time stamp, as agents print while and after they work
-   *     ("✻ Churned for 17s", "Working… (8s · …)", "— Worked for 1m 06s"). This
-   *     carries no real content, so skipping it lets the scan reach the reply
-   *     the agent wrote just above it.
+   * Whether a sanitized row is real output rather than chrome; doubles as
+   * {@link readActivity}'s block-boundary test. Skips rows without a letter
+   * or digit, rows starting with a box bar / prompt chevron / `⎿`, and
+   * elapsed-time status footers ("✻ Churned for 17s", "Working… (8s · …)").
    */
   export function isMeaningfulActivity(text: string): boolean {
     if (!text) {