instar 0.28.58 → 0.28.60

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.60",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:push": "vitest run --config vitest.push.config.ts",
+    "test:smoke": "vitest run --config vitest.push.config.ts --changed origin/main",
     "test:flaky": "vitest run tests/unit/relationship-routes.test.ts tests/integration/messaging-routes.test.ts tests/integration/whatsapp-routes.test.ts tests/unit/server.test.ts tests/e2e/semantic-memory-lifecycle.test.ts tests/e2e/system-reviewer-e2e.test.ts tests/e2e/working-memory-lifecycle.test.ts tests/e2e/messaging-multi-agent.test.ts",
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",

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-19T05:19:43.879Z",
+  "instarVersion": "0.28.60",
   "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/0.28.60.md

@@ -0,0 +1,80 @@
+# Upgrade Guide — Pre-push smoke tier (fast local test gate)
+
+## What Changed
+
+The local pre-push test gate now runs only the tests affected by files
+you changed, instead of the full suite. On a typical small push this
+drops from ~10 minutes to tens of seconds. The full suite still runs in
+CI on the PR across 8 sharded runners, and CI is the authority for
+merge.
+
+### Before
+
+Every `git push` ran `npm run test:push` — the full suite minus the
+known-flaky exclude list — serially (no in-process parallelism because
+tests collide on ports, SQLite, npm). Wall-clock ~9–10 min on every
+push, including pushes that only touched docs or config.
+
+### After
+
+Every `git push` now runs `npm run test:smoke` — the same test set,
+gated by vitest's `--changed origin/main` mode, so only tests whose
+files (or their transitive imports) appear in your diff execute. The
+exclude list and `fileParallelism: false` are preserved; the change is
+which files are included, not how they run.
+
+Escape hatches, for the cases where you want the old behavior:
+
+| Variable | Effect |
+|----------|--------|
+| `INSTAR_PRE_PUSH_FULL=1 git push` | Run the full push suite locally (old behavior, ~10 min) |
+| `INSTAR_PRE_PUSH_SKIP=1 git push` | Skip pre-push tests entirely; CI is the only gate |
+
+The NEXT.md / version / side-effects pre-push gate still runs first on
+every push — that's independent of the test tier and stays as-is.
+
+## What to Tell Your User
+
+Pushing local changes now takes seconds instead of minutes in the
+common case. The exhaustive test run still happens on GitHub before
+anything merges, so you won't ship a broken change — you just won't
+wait for the full suite on your laptop.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Fast local pre-push gate | Nothing to do — `git push` now runs only tests touched by your diff |
+| Force full local suite | `INSTAR_PRE_PUSH_FULL=1 git push` |
+| Skip local tests entirely | `INSTAR_PRE_PUSH_SKIP=1 git push` (CI still runs the full suite) |
+
+## Evidence
+
+- Local run of `npm run test:smoke` on this change (which only touches
+  `.husky/pre-push` and `package.json` scripts) runs 0 tests — the
+  diff doesn't cover any source files, so `--changed` has no targets.
+  That's the intended fast-path.
+- Local run of `npm run test:push` unchanged — ~10 min as before, now
+  opt-in via `INSTAR_PRE_PUSH_FULL=1`.
+- CI's 8-shard matrix on `ci.yml` is unchanged and continues to run
+  the full push suite on every PR — that's the authority; pre-push is
+  a signal.
+
+Side-effects review:
+`upgrades/side-effects/pre-push-smoke-tier.md` — covers over/under-block,
+level-of-abstraction fit (signal-vs-authority: pre-push is a signal, CI
+is the authority), interactions with the NEXT.md gate and the retry
+loop, external surfaces, rollback cost.
+
+## Deployment Notes
+
+No operator action required on update. The change is to the
+contributor-side git hook, which is installed by `npm install` via
+husky. Contributors pick it up automatically on their next `npm ci`.
+
+## Rollback
+
+Revert this commit. `.husky/pre-push` returns to running
+`npm run test:push` (full suite) on every push, `test:smoke` script
+stays harmless in package.json until removed. No schema changes, no
+state-file changes, no API changes.

package/upgrades/side-effects/0.28.57.md

@@ -0,0 +1,33 @@
+# Side-Effects Review — 0.28.57 (release aggregate)
+
+**Version:** `0.28.57`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.57 bundles two changes that were each reviewed individually at merge time. The publish workflow's file-renamer skipped the corresponding `upgrades/side-effects/` artifact during the 0.28.57 finalization (it renames `upgrades/NEXT.md → upgrades/{version}.md` but not the side-effects counterpart), so this file is a minimal aggregator that points at the two component reviews already on disk. Captured as a follow-up in the pre-push gate: teach `publish.yml` or `check-upgrade-guide.js` to also rename the matching side-effects artifact so this backfill isn't needed on future releases.
+
+## Components
+
+### 1. TelegramLifeline sends auth on `/internal/*` forwards
+
+Landed via PR #64. Surgical fix in `src/lifeline/TelegramLifeline.ts` to add `Authorization: Bearer <authToken>` to `forwardToServer()` and `handleCallbackQuery()`. Reasoning: the 0.28.53 server-side tightening that required auth on `/internal/*` had no matching client-side update in the lifeline — every inbound Telegram message was 401ing.
+
+- No runtime decision points introduced; a signal-less, surface-narrow header addition.
+- Over-block / under-block: not applicable — no block/allow surface.
+- Level-of-abstraction: header is constructed exactly where the fetch is built; no new indirection.
+- Signal-vs-authority: not applicable — hard-invariant transport-layer auth.
+- Interactions: none with other gates; backwards-compatible on servers that don't require the header.
+- Rollback: revert the single file.
+
+### 2. Drop duplicate CI gate from `publish.yml` (PR #67)
+
+Full review: `upgrades/side-effects/publish-drop-duplicate-ci-gate.md` (in this directory). Summary: removed the `ci` job from `publish.yml` that duplicated `ci.yml` on the same `push: branches: [main]` event. Publish wall-clock measured 11m → 55s on the first post-merge run. Branch-protection-at-PR-time remains the actual authority.
+
+## Notes
+
+This aggregator file exists to satisfy the `pre-push-gate.js` requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content. The finer-grained artifacts for each component are the authoritative reviews; this file only provides the version-named pointer.
+
+Follow-up captured: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename.

package/upgrades/side-effects/0.28.58.md

@@ -0,0 +1,24 @@
+# Side-Effects Review — 0.28.58 (release aggregate)
+
+**Version:** `0.28.58`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.58 shipped the Initiative Tracker recovery merge (PR #68). The two component reviews exist in this directory under slug names because `publish.yml`'s finalization renames `upgrades/NEXT.md → upgrades/{version}.md` but does not rename the corresponding side-effects artifact. This file is a minimal aggregator that satisfies `pre-push-gate.js`'s requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content.
+
+## Components
+
+### Initiative Tracker — core and API
+
+Full review: `upgrades/side-effects/initiative-tracker-core-and-api.md`. Persisted multi-phase work tracker with phase / blocker / last-touched state; backed by a JSON store; 28 core tests + 15 route tests added.
+
+### Initiative Tracker — dashboard tab
+
+Full review: `upgrades/side-effects/initiative-tracker-dashboard-tab.md`. New "Initiatives" tab in the dashboard rendering the tracker state; 9 dashboard smoke tests added.
+
+## Notes
+
+Same follow-up as noted in `0.28.57.md` aggregator: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename. Until one of those lands, each release will need a backfill aggregator like this one.

package/upgrades/side-effects/0.28.59.md

@@ -0,0 +1,20 @@
+# Side-Effects Review — 0.28.59 (release aggregate)
+
+**Version:** `0.28.59`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.59 shipped the dashboard "Resume live output" scroll-reliability + always-visible control fix (PR #63). The component review exists in this directory under its slug name (`dashboard-resume-live-scroll.md`) because `publish.yml`'s finalization renames `upgrades/NEXT.md → upgrades/{version}.md` but does not rename the corresponding side-effects artifact. This file is a minimal aggregator that satisfies `pre-push-gate.js`'s requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content.
+
+## Components
+
+### Dashboard "Resume live output" reliability + always-visible control
+
+Full review: `upgrades/side-effects/dashboard-resume-live-scroll.md`. Pure UI timing + visibility fix — all three resume paths now use xterm's write-completion callback so `scrollToBottom()` runs after the buffer is populated; button visibility now mirrors `!userIsFollowing` from every code path that flips the flag. 10 regression tests added at `tests/unit/dashboard-resumeLive.test.ts`.
+
+## Notes
+
+Same follow-up as captured in `0.28.57.md` and `0.28.58.md` aggregators: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename. Until one of those lands, each release will need a backfill aggregator like this one.

package/upgrades/side-effects/ci-shard-unit-tests.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Shard CI unit tests across 4 parallel runners
+
+**Version / slug:** `ci-shard-unit-tests`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`.github/workflows/ci.yml` unit-test job is extended to run the pre-push test suite across 4 vitest shards per Node version, using vitest's built-in `--shard=N/M` file-partitioning. The matrix changes from `{ node-version: [20, 22] }` (2 runners, each ~9½ min serial) to `{ node-version: [20, 22], shard: [1,2,3,4] }` (8 runners, each ~2½ min serial inside its shard). `fileParallelism: false` in `vitest.push.config.ts` stays untouched — each shard still runs its files one-at-a-time to preserve the port / SQLite / npm isolation that commit `002a463` established. `fail-fast: false` is added so one flaky shard doesn't kill the others. Expected impact on CI wall-clock: unit-test phase 9½ min → ~3 min, which pulls overall PR-CI time from ~12 min toward ~5-6 min (next bottleneck becomes integration/e2e). Only file touched: `.github/workflows/ci.yml`.
+
+## Decision-point inventory
+
+- `ci.yml.unit` — **modify** — job matrix gains a `shard` dimension; test runner invoked with `--shard=${{ matrix.shard }}/4`.
+
+No runtime / agent-behavior decision points touched.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface on message flow — over-block not applicable in the runtime sense.
+
+In the CI sense: the change runs *exactly the same* set of tests as before, just partitioned across 4 runners per Node version. Vitest's sharding is deterministic and disjoint — the union of `--shard=1/4 … 4/4` is the full include set. A commit that passed unsharded would pass sharded. No new rejection surface.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Same as before: anything `test:push` doesn't cover (the flaky-exclusion list in `vitest.push.config.ts` is unchanged — the same ~30 files that were excluded as flaky remain excluded; full suite still runs separately via `npm test` and is not part of CI gating). No new under-block introduced by this change.
+
+One theoretical concern: if the shard hash assignment is not stable across vitest versions, a file could disappear from all shards after a vitest upgrade. This is vanishingly unlikely in practice because vitest's shard algorithm is documented and stable; the union is enforced by the CLI. If we ever suspect it, a simple sanity check is to run with `--shard=` omitted and compare the test count.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. File-level parallelism was disabled in `vitest.push.config.ts` because tests spawn HTTP servers, SQLite DBs, and real npm operations that collide when running in the same process pool (see commit `002a463`). Sharding at the CI-runner level (one process per shard on its own VM) sidesteps that collision entirely — each shard has its own ports, own filesystem, own npm cache — without re-enabling in-process parallelism. This is the right layer: the isolation problem was resource-contention across a single machine's pool; moving to multiple machines solves the resource contention without touching the isolation invariant.
+
+Signal/authority lens: not applicable. CI test-pass is still an authority-grade signal computed over the same logical test set; we're just distributing the computation.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface on message flow or agent behavior.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+CI sharding is a runtime-distribution change. The test suite itself is unchanged — same authority (the full union of tests), same verdict logic (all must pass), just faster. Signal-vs-authority domain untouched.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** `unit` is a `needs:` target for `integration`, `e2e`, `contract`, and `build`. GitHub Actions' default behavior when a `needs:` target is a matrix is to wait for **all** combinations to succeed before downstream jobs run. With 8 combinations (2 node × 4 shard), downstream jobs now wait for all 8 instead of 2. This is a stricter gate, not weaker. No shadowing introduced.
+- **Double-fire:** n/a — the old 2-runner unit matrix was the only thing that ran tests. The new 8-runner matrix replaces it; total test-run count remains "once per Node × shard" (1 per runner).
+- **Races:** each shard runs in its own ephemeral GitHub-hosted runner VM. No shared filesystem, no shared ports, no shared npm cache across shards. No race surface.
+- **Feedback loops:** none. CI result feeds into PR-level required status checks, unchanged by this.
+
+One behavioral nuance worth noting: with `fail-fast: false`, a PR that has genuinely broken tests will now consume 8 runners (all reporting the same failure) instead of 2. Cost is small (GitHub-hosted free minutes; we're not anywhere near the cap), and the upside is clearer diagnostic signal — if only shard-3 fails, the problem is isolated; if all 8 fail, the problem is universal.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** no.
+- **Other users of the install base:** no runtime behavior change. The shipped package is identical byte-for-byte.
+- **External systems:** GitHub Actions runs more matrix combinations. Cost impact for public repos on GitHub-hosted free runners: negligible — Actions minutes are free for public repos. If a private fork is on a paid plan, the extra 6 runners per CI run will show up in billing; flag to callers who fork.
+- **Persistent state:** none touched.
+- **Status check names:** the job name becomes `Unit Tests (node 20, shard 1/4)` etc. instead of `Unit Tests (20)`. Only required status check in the branch ruleset today is `verify`; `Unit Tests` matrix jobs are **not** required checks (confirmed via `gh api repos/JKHeadley/instar/rules/branches/main` on 2026-04-19). So the rename does not break branch protection. If a watcher tool or dashboard specifically hardcoded `Unit Tests (20)` / `Unit Tests (22)` as an expected name, it would need updating — unlikely, but captured here.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. Revert the single `.github/workflows/ci.yml` change — restore the 2-runner matrix and the original `name:` / `run:` lines. No persistent state. No downstream code affected. Worst realistic "wrong" outcome: the shard hash algorithm has a pathological case that leaves one shard with most of the heavy tests, so the wall-clock win is smaller than projected. That's an optimization miss, not a correctness failure — still faster than pre-change, and the remediation is increasing shard count (6 or 8) rather than reverting. Full revert cost: one commit, no migration, no user impact.
+
+---
+
+## Conclusion
+
+Pure CI distribution change with no runtime surface, no decision-point surface, no signal/authority interaction. Preserves the isolation invariant from commit `002a463` by sharding at the runner level instead of re-enabling in-process parallelism. Expected wall-clock win on unit-test phase: 9½ min → ~3 min; overall CI: ~12 min → ~5-6 min (next bottleneck likely integration/e2e, captured as follow-up). Rollback is one revert. Cleared to ship.
+
+---
+
+## Evidence pointers
+
+- Root cause of current serial execution: commit `002a463` (2026-02-28) — "fix(test): disable file parallelism to prevent lock contention". Confirms the isolation problem is real and resource-contention-based; sharding at the VM level is the right remediation.
+- Shard algorithm: [vitest docs — CLI `--shard`](https://vitest.dev/guide/cli.html) — deterministic file-path hash distribution; union of all shards equals the full include set.
+- Required-check topology: `gh api repos/JKHeadley/instar/rules/branches/main` (2026-04-19) shows only `verify` as a required context. Unit-test matrix jobs are observed green on recent PRs but are not ruleset-required.

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.

package/upgrades/side-effects/pre-push-smoke-tier.md

@@ -0,0 +1,235 @@
+# Side-Effects Review — Pre-push smoke tier (changed-files only)
+
+**Version / slug:** `pre-push-smoke-tier`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`.husky/pre-push` now runs `npm run test:smoke` (new script:
+`vitest run --config vitest.push.config.ts --changed origin/main`) instead of
+`npm run test:push`. The new script executes the same excluded/included set
+and same `fileParallelism: false` isolation — the only difference is that
+vitest's `--changed origin/main` filter restricts the run to tests whose
+files (or transitive imports) are in the diff vs. origin/main. The
+pre-push gate (`scripts/pre-push-gate.js` — NEXT.md / version / side-effects
+artifact / contract-evidence / source-without-tests checks) runs first,
+unchanged. Two escape hatches: `INSTAR_PRE_PUSH_FULL=1` (run full push
+suite locally) and `INSTAR_PRE_PUSH_SKIP=1` (skip tests entirely; CI is
+the only gate). Full suite continues to run in CI across 8 sharded
+runners on every PR; CI remains the authority for merge.
+
+Files touched:
+
+- `package.json` — adds `test:smoke` script; bumps version 0.28.59 → 0.28.60.
+- `.husky/pre-push` — switches to `test:smoke` by default, adds env-var
+  escape hatches, keeps the 2-attempt retry loop and the pre-push gate
+  exactly as before.
+- `upgrades/NEXT.md` — upgrade guide (new file at release time).
+- `upgrades/side-effects/pre-push-smoke-tier.md` — this review.
+
+## Decision-point inventory
+
+- `.husky/pre-push` — **modify** — chooses which test script runs based on
+  env vars and falls back to smoke tier by default.
+- `package.json scripts.test:smoke` — **add** — new script, thin wrapper
+  over existing push config with `--changed origin/main`.
+
+No runtime / agent-behavior decision points touched. Strictly contributor-side
+git hook behavior.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+On the runtime / message surface: no block/allow change. The pre-push gate
+is a contributor-side hook, not a runtime gate, so over-block doesn't apply
+in the agent-behavior sense.
+
+On the contributor surface: the smoke tier runs *fewer* tests than the full
+push suite, so it will **accept pushes that the full suite would have
+rejected** — the opposite of over-blocking. See Under-block below.
+
+There is one narrow over-block possibility: if `origin/main` is stale (user
+hasn't fetched recently), the `--changed` diff may include files that are
+already merged, running more tests than strictly needed. We mitigate with
+`git fetch --quiet origin main` inside the hook. If the fetch fails (offline
+push), the diff falls back to whatever the local `origin/main` ref points
+at — worst case runs a few extra tests, still fast.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+This is the real surface to review. Moving from "full suite" to "tests
+affected by changed files" trades thoroughness for speed. Specifically:
+
+1. **Regression in unchanged code** — if your change to file A breaks
+   file B via some runtime-only coupling that vitest's module graph
+   doesn't see (e.g., a serialization format that both sides implement
+   independently), the smoke tier will miss it. CI's full suite on PR
+   will catch it before merge. Net risk: the contributor experiences
+   "passed locally, failed in CI" more often. Cost: one extra CI round
+   trip. Benefit: ~9 minutes saved per push across all pushes that don't
+   break anything (i.e., the vast majority).
+
+2. **Config/global-state files** — if a change touches a file imported by
+   most tests (e.g., a vitest global setup, a shared fixture builder),
+   `--changed` will correctly include the full test set. No extra risk
+   here; the mechanism is self-balancing.
+
+3. **No-change pushes** — pure doc or comment changes produce 0 tests,
+   which is correct. The pre-push gate still enforces NEXT.md presence
+   and side-effects artifact presence independently, so doc pushes that
+   claim a fix/feature still require the corresponding artifact.
+
+4. **Stale local `origin/main`** — if the user hasn't fetched for days,
+   the diff could be larger than reality, but never smaller. Under-block
+   is bounded: you cannot *miss* a file this way, only over-include.
+   We still proactively `git fetch --quiet origin main` inside the hook
+   to keep it tight.
+
+The accepted residual risk is (1). Mitigation: CI is the merge authority
+(per `docs/signal-vs-authority.md`); the pre-push gate is downgraded from
+"implicit authority" to "explicit signal" by this change, which matches
+the architectural principle.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The correct layer is the pre-push hook itself (the boundary where
+we trade speed for confidence on the contributor side). Alternatives:
+
+- **Change vitest.push.config.ts to be smaller** — wrong layer. That
+  config defines "the push suite"; the smoke tier is a *different use*
+  of that same config, selected per-push based on diff size. Keeping
+  two scripts that share one config is cleaner than two configs that
+  overlap.
+- **Change CI to run less** — wrong direction. CI is the authority; it
+  must remain exhaustive or the invariant breaks.
+- **Tag some tests as "smoke" and run only those** — brittle taxonomy
+  that humans would have to maintain. Vitest's `--changed` computes
+  affected tests from the module graph automatically; no taxonomy drift.
+
+Signal-vs-authority reference: `docs/signal-vs-authority.md`. The new
+pre-push hook is a signal consumed by the contributor (and, if they
+push anyway via `INSTAR_PRE_PUSH_SKIP=1`, CI is the binding authority).
+The old hook *was* acting as authority by blocking pushes that CI
+would have caught anyway — same verdict, earlier but slower. Moving
+the authority to CI and keeping a fast signal locally is the correct
+decomposition.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface on message flow or agent behavior.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The pre-push hook is now explicitly a *signal* — it fails the push fast
+when a clearly-affected test regressed, and otherwise lets CI act as
+authority. The `INSTAR_PRE_PUSH_SKIP=1` escape hatch formalizes this:
+contributors can bypass the signal; they cannot bypass CI on the PR.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Pre-push gate (NEXT.md / version / side-effects / contract evidence):**
+  runs *before* the test tier and is unchanged. Smoke tier substitution
+  happens after that gate passes. No interaction risk — orthogonal
+  concerns.
+- **Retry loop:** the 2-attempt retry is preserved, now wrapped around
+  `test:smoke`. Same behavior on flaky failures; just shorter because
+  the retry suite is smaller.
+- **CI (`ci.yml`):** unchanged. Still runs 8 sharded unit-test matrix +
+  integration + e2e + build + type-check on every PR. CI remains the
+  authority on merge-readiness.
+- **Shadowing:** does not exist. CI is not a `needs:` target of the
+  pre-push hook or vice versa; they operate on different events
+  (contributor push vs. GitHub Actions PR event).
+- **Double-fire:** if a contributor has the smoke tier pass and pushes,
+  CI re-runs the full suite — intentional double-gate (fast local
+  signal, authoritative remote). Not wasted work; that's the design.
+- **Races:** none. Contributor-side hook, synchronous, no shared state.
+- **Feedback loops:** if `origin/main` ref moves mid-push, the diff
+  window shifts but the push is a single event; the diff is snapshotted
+  at hook-start time.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** no. The git hook runs only in
+  the contributor's shell during `git push`.
+- **Other users of the install base:** no runtime change. The shipped
+  npm package is unchanged. Only the contributor-side hook installed
+  by `npm install` is affected, and only for people working *in* the
+  instar repo — not consumers of the `instar` package.
+- **External systems:** no.
+- **Persistent state:** none touched.
+- **CI minutes consumption:** unchanged — CI runs the same matrix.
+  If anything, fewer "contributor runs full suite locally, then CI
+  runs it again" iterations means slightly less duplicated load on
+  developer machines.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. Revert the commit that changes `.husky/pre-push` and
+`package.json`. `test:push` is unchanged, so the pre-push hook
+reverts to running the full suite exactly as it did before. No
+migration, no state cleanup, no user-visible impact (since the
+npm package is unaffected).
+
+Partial rollback also available without reverting: set the env var
+`INSTAR_PRE_PUSH_FULL=1` globally (e.g., in the user's shell rc) to
+restore the old blocking behavior without changing any code.
+
+---
+
+## Conclusion
+
+Moves the pre-push test gate from "implicit authority" (slow, exhaustive,
+blocks every push) to "fast signal" (runs only tests affected by the
+diff, CI remains the merge authority). Matches the signal-vs-authority
+architectural principle. Preserves the exclude list, the isolation
+invariant (`fileParallelism: false`), the NEXT.md / version / side-effects
+gate, the retry loop, and the full suite in CI — all authorities stay
+authoritative. Expected wall-clock on a typical small push: ~9 min → <1
+min. Escape hatches for the edge cases. Rollback is one revert. Cleared
+to ship.
+
+---
+
+## Evidence pointers
+
+- `docs/signal-vs-authority.md` — the architectural principle this change
+  aligns the hook with.
+- Vitest `--changed` mode docs:
+  <https://vitest.dev/guide/cli.html#changed> — deterministic, based on
+  module graph, safe to compose with `--config`.
+- CI authority chain: `.github/workflows/ci.yml` — 8-shard unit matrix
+  + integration + e2e + build + type-check; required by branch
+  protection on main (per the ruleset update landed with PR #69).