@cplieger/web-terminal-ui 7.1.0 → 7.2.0

package/README.md

@@ -153,9 +153,25 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
   nowhere: no terminal emulator puts a percentage next to a tab label, and a chip
   that shrinks toward a 100px floor has no width to spare. It is likewise never
   written to the browser document title, since one page title cannot represent
-  several sessions. An OSC 9 notification is posted as a browser
-  notification when the user is not already looking at that terminal (permission
-  is requested on a user gesture; a denial degrades silently to the tab dots).
+  several sessions.
+
+  Beside that dot, every chip carries a second mark for a host-reported
+  background activity that outlives a turn (a workflow run, in the
+  `web-terminal-kiro` case). It is a rounded-square ring rather than a disc, so
+  it does not read as another status dot, and band width carries its three
+  states: a 2px band with a breathing glow while a background task is running, a
+  1px band with a halo while one is paused and resumable, and a 2px band with
+  that same halo while one is blocked on the user. The state and the count are
+  announced in the tab's accessible name and repeated as the mark's hover
+  tooltip. The mark is independent of the dot's reveal gate, so a tab can show
+  one and not the other, and it collapses to no width when there is nothing to
+  report: a chip with no background activity measures exactly as it did before
+  the mark existed. It draws from `--status-working` and `--status-input`, so
+  theming the activity-dot palette themes it too and no extra token is needed.
+
+  An OSC 9 notification is posted as a browser notification when the user is not
+  already looking at that terminal (permission is requested on a user gesture; a
+  denial degrades silently to the tab dots).
   Clicking one switches to the session that raised it: the Notifications API's
   own click default already focuses the page, and the handler supplies the
   in-page half. These are non-persistent notifications, so per the API the

package/css/30-tabs.css

@@ -964,6 +964,120 @@
   border-color: var(--status-failed);
 }
 
+/* ===== Secondary activity mark (a host's background-activity channel) =====
+   A SECOND per-tab mark, orthogonal to the activity dot beside it: the dot
+   reports the session's turn, this reports a background task that outlives one.
+   Three states (working / waiting / input) and it WITHDRAWS when there is none.
+
+   It is a rounded-SQUARE RING, never a filled disc and never a pictogram, and
+   that silhouette is the WCAG 1.4.1 channel: the round dot sits 8px away at all
+   three chip sites, and the two share a hue vocabulary (--status-input is input's
+   dot colour too), so shape is what separates them at 9px. Between the mark's OWN
+   three states the channel is BAND WIDTH, in a deliberate 2:1 ratio, because
+   waiting and input share one ink.
+
+   A literal 3px radius, not --radius-sm: the smallest token rung is 4px, which on
+   a 9px box reads as a circle and defeats the silhouette.
+
+   It costs ZERO layout while no state is set. The footprint cancel is a negative
+   inline-start margin of exactly the box plus the chip's own flex gap, so the
+   label's box does not move when the element is added to a chip that has nothing
+   to report; setting data-activity zeroes the margin and the label shifts right by
+   that same amount. The gap term is per-site (31-switcher.css sets --sp-2 for the
+   two mobile chips), so it must stay a var() reference — a literal breaks whichever
+   site it does not match. box-sizing: border-box is global under .wt-root, so a
+   band change never moves layout either. */
+:where(.wt-root) .wt-activity-mark {
+  --wt-mark-size: 9px;
+  --wt-mark-gap: var(--sp-1);
+  /* waiting and input both speak through this ink and separate by band alone;
+     working overrides it. */
+  --wt-mark-ink: var(--status-input);
+
+  width: var(--wt-mark-size);
+  height: var(--wt-mark-size);
+  flex: none;
+  position: relative;
+  border-radius: 3px;
+  /* Zero-width at rest, so the ring is drawn entirely by a state's band. The
+     colour rides --wt-mark-ink here rather than in each state, so a state sets
+     one variable and one width. */
+  border: 0 solid var(--wt-mark-ink);
+  background: transparent;
+  opacity: 0;
+  /* While collapsed the box overlaps the status dot, and a title-less span over
+     the dot would eat the dot's own hover tooltip. Restored with the state. */
+  pointer-events: none;
+  margin-inline-start: calc(-1 * (var(--wt-mark-size) + var(--wt-mark-gap)));
+  /* Two lists, because the two directions are not symmetric. This one is the EXIT:
+     the mark fades out first and the space closes behind it, so nothing is still on
+     screen while the row reclaims its width. The ENTRY is on the [data-activity]
+     rule below, and it is what the tuck exists for.
+
+     The space is carried by a LAYOUT property on purpose: no transform moves the
+     label, and the label being pushed IS the reveal. Bounded to one flex line and
+     one mark plus one gap, once per state change. */
+  transition:
+    opacity var(--dur-exit) var(--ease-exit),
+    margin-inline-start var(--dur-standard) var(--ease-standard) var(--dur-exit);
+}
+
+/* The ENTRY, the reverse of the tuck's list: the space opens, and the mark fades in
+   after it on a delay equal to that same duration, so a reader sees the label make
+   room and then the mark arrive in the room it made. */
+:where(.wt-root) .wt-activity-mark[data-activity] {
+  margin-inline-start: 0;
+  opacity: 1;
+  pointer-events: auto;
+  transition:
+    margin-inline-start var(--dur-standard) var(--ease-standard),
+    opacity var(--dur-enter) var(--ease-enter) var(--dur-standard);
+}
+
+/* Working: the heavier bare band, plus a breathing glow. Its own compositing
+   layer for the reason the status dot's rule records — a nested overlay layer
+   snaps to device pixels independently of a fractional parent position, which at
+   this size reads as an off-centre pulse. */
+:where(.wt-root) .wt-activity-mark[data-activity="working"] {
+  --wt-mark-ink: var(--status-working);
+
+  border-width: 2px;
+  transform: translateZ(0);
+}
+
+/* The breath: a pre-painted radial animating OPACITY only, never colours, so the
+   beat costs compositing rather than a repaint per frame for as long as a
+   background task runs (the battery reason the dot's glow overlay records). */
+:where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
+  content: "";
+  position: absolute;
+  inset: -1px;
+  border-radius: 4px;
+  background: radial-gradient(
+    closest-side,
+    color-mix(in oklch, var(--wt-mark-ink) 78%, #fff) 0 70%,
+    transparent 92%
+  );
+  opacity: 0;
+  animation: wt-activity-breath 1.2s ease-in-out infinite;
+  will-change: opacity;
+}
+
+/* Waiting: the thin band plus a static halo. Stopped and resumable, nobody being
+   asked — so no motion, and the lightest band of the three. */
+:where(.wt-root) .wt-activity-mark[data-activity="waiting"] {
+  border-width: 1px;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--wt-mark-ink) 30%, transparent);
+}
+
+/* Input: the same ink and the same halo as waiting, at TWICE its band. The pair
+   is the only place two states share one ink, which is why the ratio is 2:1
+   rather than a hairline apart. */
+:where(.wt-root) .wt-activity-mark[data-activity="input"] {
+  border-width: 2px;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--wt-mark-ink) 30%, transparent);
+}
+
 /* The disc's glow beat: base -> brighter -> base, then a rest until the next
    cycle — expressed as the opacity envelope of the pre-painted bright overlay
    (the ::before rule above), so the beat costs compositing, not repaints.
@@ -1019,6 +1133,21 @@
   }
 }
 
+/* The activity mark's breath, same envelope as the dot's glow: rest, one bright
+   swell, rest. Opacity only — a colour keyframe here would reintroduce the
+   per-frame repaint this shape exists to avoid. */
+@keyframes wt-activity-breath {
+  0%,
+  70%,
+  100% {
+    opacity: 0;
+  }
+
+  35% {
+    opacity: 1;
+  }
+}
+
 /* Reduced-motion: drop the animated states' motion (glow + ripple), keep color.
    All three degrade the same way, since they are one object with three hues. */
 @media (prefers-reduced-motion: reduce) {
@@ -1045,6 +1174,28 @@
   :where(.wt-root) .wt-status-dot[data-status="failed"]::after {
     content: none;
   }
+
+  /* Both of the mark's transition lists carry a DELAY on their second property,
+     and 01-scope.css zeroes animation and transition DURATIONS inside .wt-root
+     while saying nothing about delay — so an un-zeroed delay parks the fade with
+     the space already open, or the close with the mark already gone. The state
+     selector is listed because its own `transition` shorthand outranks the base
+     rule's delay and would otherwise keep the entry's. */
+  :where(.wt-root) .wt-activity-mark,
+  :where(.wt-root) .wt-activity-mark[data-activity] {
+    transition-delay: 0s;
+  }
+
+  /* Working loses its breath, so it takes the HEAVIEST band instead: motion is
+     REPLACED by a channel rather than removed, and the three states then separate
+     by band alone (3px bare / 1px halo / 2px halo). */
+  :where(.wt-root) .wt-activity-mark[data-activity="working"] {
+    border-width: 3px;
+  }
+
+  :where(.wt-root) .wt-activity-mark[data-activity="working"]::before {
+    content: none;
+  }
 }
 
 /* ===== Catching-up cue (tabs feature, sections 12/13) =====

package/css/31-switcher.css

@@ -194,6 +194,17 @@
   min-width: 0;
 }
 
+/* The secondary activity mark's footprint cancel is "the box plus the chip's own
+   flex gap" (30-tabs.css), and these two chips lay their parts out on --sp-2
+   where the desktop chip uses --sp-1 — so the collapsed mark would leave 4px of
+   layout behind at both mobile sites. This is the one per-site value; the rendered
+   geometry test in features/tabs/chip-geometry.test.ts measures all three sites,
+   which is what stops it drifting. */
+:where(.wt-root) .wt-switcher-current-inner .wt-activity-mark,
+:where(.wt-root) .wt-switcher-row-select .wt-activity-mark {
+  --wt-mark-gap: var(--sp-2);
+}
+
 /* Ink-centring geometry, identical to .wt-tab-label: a symmetric ink allowance
    the ellipsis clipping needs, plus a bottom margin of twice --label-ink-shift
    that lifts the CAP band (cap top to baseline, never cap-to-descender) to the row

package/css/40-animations.css

@@ -45,9 +45,17 @@
 
 /* The chip's content dissolves as it becomes the drop slot, and comes back when the
    drag ends (30-tabs.css fades every child to nothing). One rule on the children,
-   not four per-part rules: the label, the status dot, the progress bar and the close
-   all leave together, because they leave for one reason. */
-:where(.wt-root.wt-animate) .wt-tab > * {
+   not a per-part rule each: the label, the status dot, the progress bar and the
+   close all leave together, because they leave for one reason.
+
+   The activity mark is the fifth child and is deliberately NOT one of them: it
+   animates on its own timing (30-tabs.css), a delayed fade that follows the
+   footprint snap. Both declarations are `transition` at equal specificity and this
+   file loads later, so dropping the :not() silently resets the mark's reveal at the
+   desktop chip while the two mobile chips, which are not .wt-tab children, keep it
+   — one element revealing two ways. chip-geometry.test.ts measures the resolved
+   values under .wt-animate at all three sites. */
+:where(.wt-root.wt-animate) .wt-tab > *:not(.wt-activity-mark) {
   transition: opacity var(--dur-micro) var(--ease-standard);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -50,7 +50,7 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.5.0",
+    "@types/node": "26.5.1",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/browser": "5.0.0",
     "@vitest/browser-playwright": "5.0.0",

package/src/features/tabs/index.ts

@@ -29,10 +29,13 @@ import {
   compareTabOrder,
   createSessionAPI,
   createTombstones,
+  foldedCueStatus,
   hasPinnedName,
   isCueStatus,
   isEndedStatus,
   isUnseenCue,
+  normalizeActivity,
+  normalizeActivityCount,
   normalizeProgress,
   orderedInsertIndex,
   parseCueSeen,
@@ -54,6 +57,7 @@ import {
   TAB_HTML,
   kbButtonHTML,
   newButtonHTML,
+  paintActivityMark,
   paintProgress,
   paintStatusDot,
   pick,
@@ -498,6 +502,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // every expanded list row carries a .wt-progress-bar of its own, so an
       // unscoped pick would be ambiguous the moment the list is populated.
       const swProgress = pick(switcher, ".wt-switcher-current .wt-progress-bar");
+      // The active row's secondary activity mark, scoped for the same reason.
+      const swActivity = pick(switcher, ".wt-switcher-current .wt-activity-mark");
       const swClose = pick(switcher, ".wt-switcher-current-close");
       // The active-tab elements that translate together during a horizontal
       // swipe: the content (dot + label) and the close (x). Moving both keeps the
@@ -652,12 +658,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // is one: there is no state of its own to get out of step, so no path can
       // leave it stale, and it is cheap enough to run on every tick (a loop over a
       // handful of tabs, then sinks that no-op when nothing changed). The dot is
-      // the store — statusOf reads each tab's status back off it — so this reads
-      // exactly what the user is looking at.
+      // the store — cueStatusOf reads each tab's status back off it — so this and
+      // the raise in applyStatus fold the same value.
       function paintAttention(): void {
         attention.apply(
           summarize(
-            tabList.map((t) => ({ id: t.id, status: statusOf(t) })),
+            tabList.map((t) => ({ id: t.id, status: cueStatusOf(t) })),
             cueSeen,
           ),
         );
@@ -928,7 +934,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // is a 2px line with no text, so without this a screen-reader user
           // cannot tell a working tab from a crashed one, or hear how far along
           // a determinate one is.
-          t.aria.setLabel(tabAccessibleName(display, statusOf(t), shownProgress(t)));
+          t.aria.setLabel(
+            tabAccessibleName({
+              label: display,
+              status: statusOf(t),
+              progress: shownProgress(t),
+              activity: t.activity,
+              activityCount: t.activityCount,
+            }),
+          );
         }
       }
 
@@ -939,6 +953,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         return t.dot.dataset["status"] ?? "idle";
       }
 
+      /** cueStatusOf folds a tab for the cue surfaces (foldedCueStatus). Off the
+       *  DOT rather than the wire status, so a server's empty status arrives here
+       *  as "idle" and cannot be mistaken for the blanked-cue sentinel. */
+      function cueStatusOf(t: Tab): string {
+        return foldedCueStatus(statusOf(t), t.activity);
+      }
+
       /** shownProgress is a tab's percentage as it may currently be DISPLAYED:
        *  the last value the server reported, dropped unless the current status is
        *  one the progress channel owns. Those are the only two ways a percentage
@@ -1041,6 +1062,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         swLabel.textContent = active ? active.display : "";
         paintStatusDot(swDot, active ? statusOf(active) : "idle", active?.reports ?? false);
         paintProgress(swProgress, active ? shownProgress(active) : PROGRESS_ABSENT);
+        paintActivityMark(swActivity, active?.activity ?? "", active?.activityCount ?? 0);
         // The aggregate background-notification cue rides the dedicated switch
         // button's dot (paintSwitchDot), not the active surface (it did not fit
         // there).
@@ -1066,6 +1088,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function updateRow(row: HTMLElement, t: Tab): void {
         paintStatusDot(pick(row, ".wt-switcher-row-dot"), statusOf(t), t.reports);
         paintProgress(pick(row, ".wt-progress-bar"), shownProgress(t));
+        paintActivityMark(pick(row, ".wt-activity-mark"), t.activity, t.activityCount);
         pick(row, ".wt-switcher-row-label").textContent = t.display;
       }
       // renderSwitcherList reconciles the expanded list to a row per OTHER tab
@@ -1444,9 +1467,10 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         const el = fromHTML(TAB_HTML);
         const label = el.querySelector<HTMLElement>(".wt-tab-label");
         const dot = el.querySelector<HTMLElement>(".wt-tab-dot");
+        const activityEl = el.querySelector<HTMLElement>(".wt-activity-mark");
         const progressEl = el.querySelector<HTMLElement>(".wt-progress-bar");
         const close = el.querySelector<HTMLButtonElement>(".wt-tab-close");
-        if (!label || !dot || !progressEl || !close) {
+        if (!label || !dot || !activityEl || !progressEl || !close) {
           throw new Error("web-terminal-ui: tab chrome missing parts");
         }
         paintStatusDot(dot, info.status, reportsOf(info.reportsActivity));
@@ -1482,21 +1506,31 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           el,
           label,
           dot,
+          activityEl,
           progressEl,
           // A percentage exists only on the status STREAM, so a tab adopted from
           // the REST list starts with none; the first status event fills it in.
           progress: normalizeProgress(info.progressValue),
+          activity: normalizeActivity(info.activity),
+          activityCount: normalizeActivityCount(info.activityCount),
           aria,
           view: null,
           reports: reportsOf(info.reportsActivity),
         };
         paintProgress(progressEl, renderedProgress(info.status, tab.progress));
+        paintActivityMark(activityEl, tab.activity, tab.activityCount);
         // Set an initial label immediately (relabelAll refines it with de-dup
         // once the tab is in tabList and syncChrome runs).
         tab.display = baseLabel(tab).text;
         label.textContent = tab.display;
         aria.setLabel(
-          tabAccessibleName(tab.display, info.status, renderedProgress(info.status, tab.progress)),
+          tabAccessibleName({
+            label: tab.display,
+            status: info.status,
+            progress: renderedProgress(info.status, tab.progress),
+            activity: tab.activity,
+            activityCount: tab.activityCount,
+          }),
         );
         el.addEventListener("click", (e) => {
           if ((e.target as HTMLElement).closest(".wt-tab-close")) {
@@ -3307,6 +3341,18 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           t.progress = normalizeProgress(rec.progressValue);
         }
         paintProgress(t.progressEl, shownProgress(t));
+        // The host's secondary activity, read with the same PRESENT-only guard and
+        // for the same reason: the polling fallback lists SessionInfo, and a
+        // pre-release server carries neither field at all, so reading absence as
+        // "no background task" would blank a live mark on every tick. An empty
+        // string IS the withdrawal, and it arrives explicitly.
+        if (rec.activity !== undefined) {
+          t.activity = normalizeActivity(rec.activity);
+        }
+        if (rec.activityCount !== undefined) {
+          t.activityCount = normalizeActivityCount(rec.activityCount);
+        }
+        paintActivityMark(t.activityEl, t.activity, t.activityCount);
         // A session that reports activity is a session whose program speaks OSC 9,
         // so it is also one that may post a notification: arm the permission
         // request for the next user gesture (see notify.ts).
@@ -3327,9 +3373,17 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // dismissal stick across those is cueSeen — a latch this viewer already
         // acknowledged raises nothing, while a status that moved on drops the
         // acknowledgement so the next latch is a fresh cue.
-        if (!isCueStatus(rec.status)) {
-          forgetCueSeen(rec.id);
-        } else if (rec.id === activeId && pageVisible()) {
+        //
+        // Two inputs, one per question, and the ORDER keeps them apart. The
+        // acknowledgement asks whether this reader has SEEN the tab's real state:
+        // RAW status, first, and only for a cue — a non-cue one has nothing to
+        // acknowledge and has to reach the forget below. The raise and the forget
+        // ask whether anything should be ANNOUNCED: folded. Off the fold the
+        // acknowledgement misses a watched turn until its task ends; off the raw
+        // status the forget makes the "" sentinel pointless.
+        const raw = statusOf(t);
+        const cue = cueStatusOf(t);
+        if (rec.id === activeId && pageVisible() && isCueStatus(raw)) {
           // The user is looking at this terminal as it latches, so there is
           // nothing to notify — and nothing to re-raise once they move away.
           //
@@ -3340,9 +3394,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // it is precisely the case the out-of-page surfaces exist for, so a
           // latch arriving on a HIDDEN page now raises them and is acknowledged
           // when the user comes back (see onPageVisible).
-          markCueSeen(rec.id, rec.status);
-        } else if (isUnseenCue(rec.status, rec.id, cueSeen)) {
-          switchNotify = rec.status;
+          markCueSeen(rec.id, raw);
+        } else if (cue === "") {
+          // A blanked cue is NO INFORMATION, not a state, so nothing is raised and
+          // the acknowledgement map is left alone: forgetting here would re-raise
+          // the cue from scratch the moment the background task ended.
+        } else if (!isCueStatus(cue)) {
+          forgetCueSeen(rec.id);
+        } else if (isUnseenCue(cue, rec.id, cueSeen)) {
+          switchNotify = cue;
           switchNotifyId = rec.id;
           paintSwitchDot();
         }

package/src/features/tabs/model.ts

@@ -20,8 +20,19 @@ export type { SessionInfo };
  *  (SessionStatus.progressValue). Both status sources flow through one code path
  *  this way, and the optionality is meaningful: the polling fallback lists
  *  SessionInfo with no percentage at all, which means "no information" and must
- *  not be read as "the percentage was cleared". */
-export type StatusRecord = SessionInfo & { readonly progressValue?: number };
+ *  not be read as "the percentage was cleared".
+ *
+ *  `activity`/`activityCount` are declared here as a FORWARD declaration: the
+ *  published engine's SessionInfo does not carry them yet. Drop both from this
+ *  intersection once it does, so the wire shape has one home again — if the
+ *  intersection then narrows anything, the engine's declaration is the wrong
+ *  one. Both are `string`/`number` rather than unions for the same reason
+ *  `status` is: the stream is parsed, not validated. */
+export type StatusRecord = SessionInfo & {
+  readonly progressValue?: number;
+  readonly activity?: string;
+  readonly activityCount?: number;
+};
 
 // The status vocabulary, module-private on purpose: every consumer asks one of
 // the predicates below (isEndedStatus / statusRevealsDot / isCueStatus /
@@ -161,6 +172,63 @@ export function renderedProgress(status: string, progress: number): number {
   return statusOwnsProgress(status) ? progress : PROGRESS_ABSENT;
 }
 
+// The secondary-activity vocabulary: a host-reported background activity that
+// OUTLIVES the turn, orthogonal to the status above. Module-private for the same
+// reason the status vocabulary is — every consumer asks a predicate, so a state's
+// MEANING has one home.
+//
+// A background task is running.
+const ACTIVITY_WORKING = "working";
+// Stopped and resumable; nobody is being asked for anything.
+const ACTIVITY_WAITING = "waiting";
+// A background task is blocked on the user.
+const ACTIVITY_INPUT = "input";
+
+/** normalizeActivity cleans the wire value into the closed set, or "" for no
+ *  mark. Anything outside it — an unknown state from a newer server, a
+ *  non-string, absent — is "": an unrecognised state must fail toward NO mark
+ *  rather than toward a lit one whose meaning this build cannot name. */
+export function normalizeActivity(value: unknown): string {
+  if (value === ACTIVITY_WORKING || value === ACTIVITY_WAITING || value === ACTIVITY_INPUT) {
+    return value;
+  }
+  return "";
+}
+
+/** normalizeActivityCount cleans the count off the wire: a non-integer, a
+ *  negative or an absent value is 0. The engine documents count >= 1 whenever
+ *  the state is non-empty, so 0 beside a live state is a server that does not
+ *  count, which activityPhrase reads as one. */
+export function normalizeActivityCount(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    return 0;
+  }
+  return value;
+}
+
+/** activityPhrase is the human wording for the mark, used for BOTH its hover
+ *  tooltip and the suffix in a tab's accessible name — one definition, so what a
+ *  sighted user reads on hover and what a screen reader announces cannot
+ *  disagree (the statusPhrase rule). "" for no mark.
+ *
+ *  It cannot say "workflow": the secondary channel is generic, so the wording has
+ *  to be true for whatever a host puts on it. */
+export function activityPhrase(state: string, count: number): string {
+  const normalized = normalizeActivity(state);
+  if (normalized === "") {
+    return "";
+  }
+  const n = Math.max(1, normalizeActivityCount(count));
+  const subject = `${String(n)} background task${n === 1 ? "" : "s"}`;
+  if (normalized === ACTIVITY_WORKING) {
+    return `${subject} running`;
+  }
+  if (normalized === ACTIVITY_WAITING) {
+    return `${subject} paused`;
+  }
+  return `${subject} waiting for you`;
+}
+
 /** tabAccessibleName is a tab's announced name: its rendered label plus the
  *  session's state, and the percentage when one is showing.
  *
@@ -173,16 +241,23 @@ export function renderedProgress(status: string, progress: number): number {
  *
  *  Pass PROGRESS_ABSENT for progress to announce the state alone. Callers hand in
  *  renderedProgress's output, so a percentage the tab is not showing is not
- *  announced either. */
-export function tabAccessibleName(
-  renderedLabel: string,
-  status: string,
-  progress: number = PROGRESS_ABSENT,
-): string {
-  const state = statusPhrase(status);
-  return progress < 0
-    ? `${renderedLabel} — ${state}`
-    : `${renderedLabel} — ${state}, ${String(progress)}%`;
+ *  announced either.
+ *
+ *  A RECORD rather than positional arguments: `label` and `status` are adjacent
+ *  same-typed strings, so a transposition compiles. */
+export function tabAccessibleName(v: {
+  readonly label: string;
+  readonly status: string;
+  readonly progress?: number;
+  readonly activity?: string;
+  readonly activityCount?: number;
+}): string {
+  const state = statusPhrase(v.status);
+  const progress = v.progress ?? PROGRESS_ABSENT;
+  const head =
+    progress < 0 ? `${v.label} — ${state}` : `${v.label} — ${state}, ${String(progress)}%`;
+  const activity = activityPhrase(v.activity ?? "", v.activityCount ?? 0);
+  return activity === "" ? head : `${head} (${activity})`;
 }
 
 // localStorage key for the last active session id, so a page reload reopens the
@@ -251,6 +326,37 @@ export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
   return "alert";
 }
 
+/** The cue statuses that mean the session's own turn is OVER WITHOUT INCIDENT, and
+ *  therefore the only ones a live background task may blank.
+ *
+ *  Narrow on purpose, and `done` is the whole set. Every other cue status is
+ *  something the viewer has to be told AT ONCE, so none of them may wait on a task:
+ *  `crashed` and `exited` mean the PROCESS is gone (and a task belonging to a dead
+ *  session is dead too), `input` IS what the viewer is being pointed at whatever
+ *  else the session is doing, and `failed` is an error the program declared, which
+ *  does not become less urgent because something else is still running. On this
+ *  engine's path `failed` is OSC 9;4 state 2 rather than a turn verdict, so it is
+ *  deliberately NOT treated the way vibekit's settle probe treats its own `failed`
+ *  (see web-terminal-engine.md). */
+const SETTLED_CUES: ReadonlySet<string> = new Set<CueStatus>(["done"]);
+
+/** foldedCueStatus is the status the CUE surfaces see for a session: its own
+ *  status, unless a settled turn's background task is still running, in which
+ *  case "". Nothing about the status DOT changes — the strip keeps rendering the
+ *  turn's real state; only the cue's view of it is blanked.
+ *
+ *  "" and NOT "idle", and the difference is load-bearing: "" means NO
+ *  INFORMATION, so a caller must leave the wt-cue-seen map alone, where "idle" is
+ *  a real non-cue state that FORGETS the acknowledgement. Blanking with "idle"
+ *  would drop the dismissal and re-raise the cue from scratch the moment the task
+ *  ended, even for a session the viewer had already visited. */
+export function foldedCueStatus(status: string, activity: string): string {
+  if (!SETTLED_CUES.has(status) || normalizeActivity(activity) === "") {
+    return status;
+  }
+  return "";
+}
+
 /** isUnseenCue reports whether a session's CURRENT status is a cue this viewer
  *  has not acknowledged. The single predicate behind both the raise and the
  *  attention count, so a dot can never light for a session the count omits.
@@ -460,6 +566,16 @@ export interface Tab {
    *  question (renderedProgress), and the prefix it produces is never stored on
    *  any title field. */
   progress: number;
+  /** The chip's secondary activity mark (the rounded-square ring beside the
+   *  status dot). Present on every chip, and costing no layout until a state
+   *  arrives. */
+  activityEl: HTMLElement;
+  /** The host's secondary activity state for this session, normalised to the
+   *  closed set ("" for none). Independent of `status` and of `reports`: a
+   *  background task can be running while the turn that launched it is finished. */
+  activity: string;
+  /** How many sources produced that state, 0 when the server does not count. */
+  activityCount: number;
   aria: TabHandle;
   /** This tab's saved reading position: the absolute LINE at the viewport top
    *  plus its on-screen offset and the follow state, as captureViewMemory()

package/src/features/tabs/strip.ts

@@ -10,7 +10,7 @@
 // The status vocabulary itself (which statuses reveal a dot, and how each one is
 // worded for a human) lives in the DOM-free model, so the painters here and the
 // accessible names index.ts builds read one definition.
-import { statusPhrase, statusRevealsDot } from "./model.js";
+import { activityPhrase, normalizeActivity, statusPhrase, statusRevealsDot } from "./model.js";
 
 // --- Reorder preview -------------------------------------------------------
 // Every chip in this strip is the same width (see .wt-tab in 30-tabs.css: a
@@ -121,6 +121,13 @@ const SWITCH_SVG = `<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="8
 // class (.wt-progress-bar) styles it everywhere and every chip site gets it for
 // free. It starts `hidden` — a session with no percentage must render NO bar
 // (paintProgress).
+//
+// The secondary activity mark (.wt-activity-mark) rides here for the same reason
+// and takes no per-site class either. It carries NO `hidden` attribute, unlike
+// the bar: `hidden` is display:none, and an element out of layout cannot animate
+// into it. Absence is the absence of `data-activity`, which the CSS answers by
+// cancelling the mark's own footprint (see 30-tabs.css), so a chip with no
+// secondary activity measures exactly as it did before this element existed.
 export function chipContent(v: { dot: string; label: string; close: string; closeAttr?: string }): {
   dotLabel: string;
   close: string;
@@ -128,6 +135,7 @@ export function chipContent(v: { dot: string; label: string; close: string; clos
   return {
     dotLabel:
       `<span class="${v.dot} wt-status-dot" aria-hidden="true"></span>` +
+      `<span class="wt-activity-mark" aria-hidden="true"></span>` +
       `<span class="${v.label}"></span>` +
       `<span class="wt-progress-bar" aria-hidden="true" hidden></span>`,
     close: `<button type="button" class="${v.close}" aria-label="Close terminal"${v.closeAttr ?? ""}>${CLOSE_SVG}</button>`,
@@ -195,6 +203,27 @@ export function paintStatusDot(el: HTMLElement, status: string, reports: boolean
   el.title = statusPhrase(value);
 }
 
+/** paintActivityMark applies the secondary mark's two bits: data-activity drives
+ *  its appearance (working / waiting / input via CSS) and `title` gives it a
+ *  hover tooltip, worded by activityPhrase so hover text and announced text
+ *  cannot drift. No state REMOVES the attribute, which is what collapses the
+ *  mark's footprint to zero.
+ *
+ *  The reveal is the mark's OWN state, deliberately not the status dot's
+ *  reportsActivity gate: a background run is a fact about the session that is
+ *  independent of whether its program ever spoke OSC 9, which is the whole point
+ *  of a second mark. */
+export function paintActivityMark(el: HTMLElement, state: string, count: number): void {
+  const phrase = activityPhrase(state, count);
+  if (phrase === "") {
+    delete el.dataset["activity"];
+    el.removeAttribute("title");
+    return;
+  }
+  el.dataset["activity"] = normalizeActivity(state);
+  el.title = phrase;
+}
+
 /** paintProgress renders one chip's determinate progress bar from a percentage.
  *
  *  An absent percentage (PROGRESS_ABSENT / any negative) renders NO bar: the

package/src/kernel/scrollback.ts

@@ -115,7 +115,11 @@ interface StoredEntry {
  * neither could be observed: 15 of the file's 19 surviving mutants were those
  * two guards and their bodies.
  */
-function readStoredEntry(entry: NonNullable<unknown>): StoredEntry | null {
+// Spelled `{}` rather than `NonNullable<unknown>`: the two are the same type, and
+// only the second is a type OPERATION, which `no-generated-empty-object-type`
+// (typescript-eslint 8.70+) reports even where resolving to `{}` is the point.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- "any non-nullish value" is the intended type; the paragraph above says why there is no object test here
+function readStoredEntry(entry: {}): StoredEntry | null {
   const rec = entry as Record<string, unknown>;
   const savedAt = rec["savedAt"];
   // Finite, not merely a number: the age comparison below is a subtraction, and