instar 0.28.58 → 0.28.59

package/dashboard/index.html

@@ -3221,6 +3221,7 @@
 
       activeSession = tmuxSession;
       userIsFollowing = true; // Reset scroll tracking on session switch
+      hideResumeButton(); // Carry-over button from prior session would be misleading
       historyLinesLoaded = 2000; // Reset history state for new session
       historyLoading = false;
       historyExhausted = false;
@@ -3334,15 +3335,20 @@
         if (atBottom && !userIsFollowing) {
           // User scrolled back to bottom — resume following and apply pending output
           userIsFollowing = true;
+          hideResumeButton();
           if (pendingOutputData) {
             const data = pendingOutputData;
             pendingOutputData = null;
             term.clear();
-            term.write(data);
-            term.scrollToBottom();
+            // term.write is async — scroll after write completes so the buffer is populated.
+            term.write(data, () => { term.scrollToBottom(); });
           }
-        } else if (!atBottom) {
+        } else if (!atBottom && userIsFollowing) {
+          // User scrolled up — pause follow and surface the resume button
+          // even if no new output is pending. The button is the always-available
+          // "take me back to live" control.
           userIsFollowing = false;
+          showResumeButton();
         }
 
         // Infinite scroll: load more history when scrolled near the top
@@ -3370,12 +3376,13 @@
             const atBottom = buf.baseY === 0 || (buf.baseY - buf.viewportY) <= 5;
             if (atBottom) {
               userIsFollowing = true;
+              hideResumeButton();
               if (pendingOutputData) {
                 const data = pendingOutputData;
                 pendingOutputData = null;
                 term.clear();
-                term.write(data);
-                term.scrollToBottom();
+                // term.write is async — scroll after write completes so the buffer is populated.
+                term.write(data, () => { term.scrollToBottom(); });
               }
             }
           }
@@ -3449,23 +3456,20 @@
         btn.style.cssText = 'position:absolute;bottom:12px;left:50%;transform:translateX(-50%);z-index:10;background:var(--accent);color:#000;border:none;padding:6px 16px;border-radius:4px;font-size:12px;cursor:pointer;font-weight:600;opacity:0.95;box-shadow:0 2px 8px rgba(0,0,0,0.3);';
         btn.onclick = () => {
           userIsFollowing = true;
+          const snapToBottom = () => {
+            term.scrollToBottom();
+            const container = document.getElementById('terminalContainer');
+            if (container) container.scrollIntoView({ block: 'end', behavior: 'instant' });
+          };
           if (pendingOutputData) {
             const data = pendingOutputData;
             pendingOutputData = null;
             term.clear();
-            term.write(data);
-            // Delay scrollToBottom until after xterm renders the written data
-            requestAnimationFrame(() => {
-              term.scrollToBottom();
-              // Also scroll the browser viewport to show the terminal bottom
-              const container = document.getElementById('terminalContainer');
-              if (container) container.scrollIntoView({ block: 'end', behavior: 'instant' });
-            });
+            // term.write is async — use its completion callback so scroll runs
+            // after the buffer is populated, not against a stale viewport.
+            term.write(data, snapToBottom);
           } else {
-            // No pending data — just snap to bottom of existing content
-            term.scrollToBottom();
-            const container = document.getElementById('terminalContainer');
-            if (container) container.scrollIntoView({ block: 'end', behavior: 'instant' });
+            snapToBottom();
           }
           hideResumeButton();
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.58",
+  "version": "0.28.59",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-04-19T02:15:10.872Z",
-  "instarVersion": "0.28.58",
+  "generatedAt": "2026-04-19T02:56:02.572Z",
+  "instarVersion": "0.28.59",
   "entryCount": 186,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.59.md

@@ -0,0 +1,85 @@
+# Upgrade Guide — Dashboard "Resume live output" reliability + always-visible control
+
+## What Changed
+
+Fixed two long-standing rough edges in the dashboard's terminal view for the
+"▼ Resume live output" control.
+
+### Scroll-to-bottom now actually lands at the bottom
+
+Clicking "▼ Resume live output" after scrolling up in a session view used to
+sometimes leave the viewport mid-history instead of snapping to the tail of
+live output — defeating the purpose of the button. The same stale-scroll
+happened on the two sibling auto-resume paths that fire when the user
+scrolls back to the bottom or wheels down into it.
+
+Root cause: `term.write(data)` in xterm is asynchronous. The old code called
+`term.scrollToBottom()` immediately after the write, or inside a
+`requestAnimationFrame` — neither guarantees the buffer has been populated,
+so the scroll operated on stale viewport state and landed above the new
+output.
+
+Fix: all three resume paths now use xterm's write-completion callback —
+`term.write(data, () => term.scrollToBottom())`. The scroll runs after the
+buffer is populated, so the viewport lands at the new bottom.
+
+### The button is always visible when paused
+
+Previously the "▼ Resume live output" button only appeared when new output
+happened to arrive while the user was scrolled up. In idle sessions —
+nothing streaming, user just scrolled up to read history — the button never
+surfaced, and there was no UI control to jump back to live.
+
+Fix: button visibility now mirrors `!userIsFollowing` from every code path
+that flips the flag. Scroll up in a session view (idle or streaming) and the
+button appears. Scroll back to the bottom, click the button, wheel down into
+the tail, or switch sessions, and the button hides.
+
+## What to Tell Your User
+
+The "Resume live output" button in your dashboard's session view now works
+the way you'd expect: it shows up any time you've scrolled up (even in an
+idle session where nothing is streaming), and clicking it reliably drops
+you at the bottom of the live output instead of leaving you mid-history.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Reliable auto-follow resume in the dashboard terminal | Click "▼ Resume live output" after scrolling up in any session view; viewport snaps to the bottom |
+| Button always available while paused | Scroll up in any session — the button surfaces automatically; scroll back down or click it to resume |
+
+## Evidence
+
+The fix was reproduced from Justin's report (topic 6309 on echo agent): the
+button left him mid-history, and in idle sessions there was no button at
+all.
+
+Regression test (`tests/unit/dashboard-resumeLive.test.ts`, 10 tests) locks
+in both invariants at the HTML-inspection layer:
+
+- Scroll-after-write: all three resume paths use the xterm write callback;
+  the old `term.write(data); requestAnimationFrame(() => term.scrollToBottom())`
+  shape is explicitly banned.
+- Button visibility: `term.onScroll` shows the button on scroll-up and
+  hides it on scroll-to-bottom; the wheel-down resume path hides the
+  button; session-switch reset hides any carry-over button.
+
+Full dashboard test suite green across `dashboard-*.test.ts`.
+
+Side-effects review:
+`upgrades/side-effects/dashboard-resume-live-scroll.md` — concludes no
+decision-point touched (pure UI timing + visibility fix), no over/under-block
+risk, trivial rollback (git revert).
+
+## Deployment Notes
+
+No operator action required on update. The dashboard is static HTML served
+from the installed instar package — clients pick up the fix on their next
+page load after `instar` updates to 0.28.59.
+
+## Rollback
+
+Downgrade reverts the three resume paths to the prior (racy) code and
+returns the button to its contingent-on-new-output visibility. No schema
+changes, no state-file changes, no API changes.

package/upgrades/side-effects/dashboard-resume-live-scroll.md

@@ -0,0 +1,132 @@
+# Side-Effects Review — Dashboard "Resume live output" reliability + always-visible while paused
+
+**Version / slug:** `dashboard-resume-live-scroll`
+**Date:** `2026-04-18`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — pure UI timing fix, no gate/sentinel/watchdog/session-lifecycle surface`
+
+## Summary of the change
+
+The dashboard's "Resume live output" button (and the two sibling resume paths that
+fire on scroll-to-bottom and wheel-down) did not reliably snap the xterm viewport
+to the bottom after being clicked. The user still landed mid-history and had to
+scroll manually to see live output — defeating the purpose of the button.
+
+Root cause: `term.write(data)` is asynchronous — xterm parses and renders the
+write on a microtask. The old code called `term.scrollToBottom()` either
+immediately after the write or inside a `requestAnimationFrame`. Neither
+guarantees the buffer has been populated, so `scrollToBottom()` snapped against
+a stale `baseY` and landed above the new output.
+
+Fix: use xterm's write-completion callback — `term.write(data, () => { term.scrollToBottom(); })`.
+The callback fires after the write is flushed, so the scroll operates on the
+final buffer state.
+
+## Secondary change — button visibility mirrors follow state
+
+The prior behavior only showed the "▼ Resume live output" button when new
+output happened to arrive while the user was scrolled up — via `showResumeButton()`
+inside `renderTerminalOutput`'s not-following branch. If the user scrolled up in
+an idle session (no new output arriving), the button never appeared, and there
+was no UI control to jump back to live.
+
+Fix: `term.onScroll` now surfaces the button the moment the user scrolls up
+(`!atBottom && userIsFollowing` → flip false + `showResumeButton()`), and hides
+it the moment they return to the bottom by any means (`atBottom && !userIsFollowing`
+→ flip true + `hideResumeButton()`). The wheel-down resume path hides the button
+for the same reason. Session-switch reset calls `hideResumeButton()` so a
+carry-over button from a prior session doesn't mislead.
+
+The button is now the always-available "take me back to live" control, not a
+contingent reaction to incoming output.
+
+Files touched:
+
+- `dashboard/index.html` — two overlapping changes:
+  - Three resume paths use xterm's write-completion callback:
+    1. The button `onclick` handler.
+    2. The `term.onScroll` handler's auto-resume branch.
+    3. The `xtermViewport` wheel handler's auto-resume branch.
+    The button handler retains `container.scrollIntoView({block:'end'})` in a
+    shared `snapToBottom` closure so both the pending-data and no-pending-data
+    branches do the same thing.
+  - Button visibility now mirrors `!userIsFollowing` from every path that
+    flips the flag: scroll-up in `onScroll`, scroll-to-bottom in `onScroll`,
+    wheel-down resume, and session-switch reset.
+- `tests/unit/dashboard-resumeLive.test.ts` — new. HTML-inspection regression
+  test, consistent with the existing `dashboard-*.test.ts` pattern. Ten tests,
+  split across two describe blocks: (a) scroll-after-write invariants — locks
+  in the callback form on all three paths and bans the old
+  `term.write(data); requestAnimationFrame(() => term.scrollToBottom())` shape;
+  (b) button-visibility invariants — asserts show on scroll-up, hide on
+  scroll-to-bottom / wheel-resume / session switch.
+
+## 1. Over-block
+
+N/A — no block/allow decision exists in this change. The only behavior altered
+is the timing of a DOM scroll call relative to an xterm write.
+
+## 2. Under-block
+
+N/A — see Over-block.
+
+## 3. Level-of-abstraction fit
+
+The fix lives at the exact layer where the bug lives: dashboard JavaScript
+interacting with xterm.js. xterm's documented API for scheduling work after
+a write is the write callback; using `requestAnimationFrame` was a workaround
+that guessed at timing instead of using the library's native hook. The fix
+moves us from guessing to the library-native pattern.
+
+There is no higher-level authority that should own terminal-viewport scrolling
+— this is a leaf UI behavior. There is no lower layer to delegate to — xterm
+itself is the layer.
+
+## 4. Signal-vs-authority compliance
+
+No decision point touched. This is not a gate, filter, sentinel, watchdog, or
+dispatcher. No brittle logic holds blocking authority. The principle does not
+apply. Documented in Phase 1.
+
+## 5. Interactions
+
+- **`renderTerminalOutput` (the steady-state write path):** Still uses the
+  bare `term.write(data); term.scrollToBottom();` form. That path runs only
+  when `userIsFollowing === true` — xterm's default behavior is to auto-track
+  the bottom when the viewport is already there, so the follow-up
+  `scrollToBottom()` is essentially redundant and harmless. Not touched.
+- **`term.onScroll` flag-flipping:** The scroll event fires during
+  `term.write()` as the buffer grows. If the write callback runs after
+  `scrollToBottom()`, the onScroll handler sees `atBottom === true` and
+  keeps `userIsFollowing === true`. No race with flag-flipping introduced.
+- **Concurrent WS output:** If a new frame arrives via WebSocket during the
+  click handler, it calls `renderTerminalOutput` with `userIsFollowing === true`
+  (we just set it). That path does its own `term.clear()` + `term.write` +
+  `scrollToBottom()`, which will overwrite whatever our click handler was
+  mid-flight. Net effect: user ends up at bottom either way. No deadlock, no
+  torn state.
+- **Infinite-scroll history loader:** Unaffected — uses `buf.viewportY <= 10`,
+  which is a separate concern from the bottom-snap logic.
+
+## 6. External surfaces
+
+None. This is client-side JavaScript in the dashboard HTML, served to the
+user's browser. No other agents, no other users, no other systems observe the
+change. No server API touched. No persisted state touched.
+
+## 7. Rollback cost
+
+Trivial: `git revert <commit>`. No data migration, no state repair, no release
+coordination. Dashboard is static HTML served by the instar server; a revert
+commit + server restart puts the old code back in front of the user
+immediately.
+
+## Verification
+
+- HTML-inspection regression test passing (`tests/unit/dashboard-resumeLive.test.ts`, 6 tests).
+- Full dashboard test suite passing (`dashboard-*.test.ts`, 20 tests total).
+- Manual browser verification: deferred to user acceptance — reproducing the
+  bug end-to-end requires a live session with pending output and a user
+  scrolled up, which is Justin's original reporting path. The mechanical fix
+  is narrow enough (swap `term.write(data); scroll` → `term.write(data, scroll)`)
+  that the HTML regression is the load-bearing guarantee.