instar 0.28.57 → 0.28.59

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/initiative-tracker-core-and-api.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Initiative Tracker core + API
+
+**Version / slug:** `initiative-tracker-core-and-api`
+**Date:** `2026-04-17`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required — new opt-in persistence surface behind its own routes; no existing behavior is modified`
+
+## Summary of the change
+
+Introduces a long-running-work tracker to close the user-feedback gap where multi-phase efforts (e.g. the PR-REVIEW-HARDENING rollout) stall silently because there is no structural place to persist "this is phase N of M, last touched on D, needs user decision X." Existing primitives (AttentionItem = single actionable; Job = recurring cron; Dispatch = broadcast) don't cover this shape.
+
+Files added/modified:
+- **new** `src/core/InitiativeTracker.ts` — class with CRUD + phase transitions + digest scan; atomic-write persistence to `.instar/initiatives.json` following the existing AttentionItem pattern.
+- **new** `tests/unit/InitiativeTracker.test.ts` — 28 unit tests (CRUD, validation, phase transitions, persistence, digest scan).
+- **new** `tests/unit/routes-initiatives.test.ts` — 15 integration tests hitting real Express with real persistence.
+- **mod** `src/server/AgentServer.ts` — adds `initiativeTracker` to constructor options and routeContext.
+- **mod** `src/server/routes.ts` — RouteContext field + 7 new endpoints: `GET/POST /initiatives`, `GET /initiatives/digest`, `GET/PATCH/DELETE /initiatives/:id`, `POST /initiatives/:id/phase/:phaseId`.
+- **mod** `src/commands/server.ts` — instantiates `InitiativeTracker` and passes to `new AgentServer`.
+
+## Decision-point inventory
+
+1. **Persistence location**: `.instar/initiatives.json` at the root of stateDir. Follows the same convention as `jobs.json`, `telegram-messages.jsonl`, etc. Alternative considered: nest under `.instar/state/initiatives/`. Rejected because the existing convention for top-level agent state is flat JSON at stateDir root.
+2. **Persistence format**: single JSON file with `{ initiatives: [...] }` root (same shape as AttentionItem persistence). Not a directory-per-initiative. Rationale: expected volume is ≤50 records, fits comfortably in one atomic write; per-record writes would risk torn state.
+3. **Ready-to-advance signal definition**: emits when the previous phase is `done` AND the current phase is `pending` (untouched). Does not emit once the current phase is `in-progress` — by then the advance has started and the signal would become noise. (Bug discovered mid-test-run and corrected.)
+4. **Staleness threshold**: 7 days (`STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000`). Only applies to `active` initiatives. Configurable in a future change if noise is observed.
+5. **Id validation**: lowercase kebab-case, 1–63 chars, must start with alphanumeric. Matches slug conventions used elsewhere (job slugs, topic names).
+
+## 1. Over-block review
+
+No blocking behavior introduced. Every endpoint is opt-in (503 when `initiativeTracker` is null, which cannot happen in practice since the server always instantiates it). No existing routes or middleware are changed. No pre-commit hook, git-sync behavior, or session lifecycle is touched.
+
+## 2. Under-block review
+
+N/A — there is no block-or-pass decision. The tracker is purely a persistence + query surface.
+
+## 3. Level-of-abstraction fit
+
+- Persistence logic lives in `InitiativeTracker` class (domain layer).
+- HTTP shape lives in `routes.ts` (transport layer).
+- Construction lives in `commands/server.ts` (composition root).
+- Tests hit both the class layer and the HTTP layer independently.
+
+This matches the pattern established by `BackupManager`, `RelationshipManager`, `FeedbackManager`.
+
+## 4. Signal-vs-authority review
+
+The digest scan emits **signals only** (`DigestItem[]`). It has zero blocking authority — callers (daily digest job, dashboard UI, the user) decide what to do with the signal. The daily digest job (separate commit) will use these signals to decide whether to push a Telegram notification; the threshold for pushing is the job's concern, not the tracker's.
+
+## 5. Interactions review
+
+- **Does not interact with Telegram**: tracker has no knowledge of topics, messages, or channels. The separate daily-digest job will bridge signal → Telegram.
+- **Does not interact with JobScheduler**: the digest job reads the tracker but lives separately.
+- **Does not interact with BackupManager**: `.instar/initiatives.json` is picked up by default backup globbing (no explicit include needed).
+- **Does not conflict with AttentionItem**: complementary — AttentionItem is for single-shot actionables, Initiative is for multi-phase long-lived work. A future convenience could auto-create an AttentionItem from a `needs-user` digest row, but that's a separate design decision.
+
+## 6. External surfaces
+
+- **HTTP API**: 7 new routes under `/initiatives`, all behind the existing auth middleware. No public unauthenticated surface.
+- **File system**: one new file (`.instar/initiatives.json`), atomic-rename writes prevent torn state.
+- **Dashboard**: not wired yet — separate commit adds the Initiatives tab.
+
+## 7. Rollback cost
+
+Low. `git revert` removes the tracker class, routes, wiring, and tests. `.instar/initiatives.json` persists on disk but is ignored by all revived code paths (no other consumer reads it). The user can delete the file manually if desired, or leave it as dead data.
+
+## Conclusion
+
+Additive-only change. No existing behavior modified. 43 new tests (28 class + 15 route), all passing. `tsc --noEmit` clean. Clear to ship as commit 1 of 4 for the Initiative Tracker feature.
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/InitiativeTracker.test.ts` (28 pass).
+- Integration tests: `tests/unit/routes-initiatives.test.ts` (15 pass).
+- Prior Phase A tests still green (spot-checked: `routes-prGatePhaseGate`, `PostUpdateMigrator-gitignore`, `PostUpdateMigrator-prPipelineArtifacts` — 37 pass).
+- `npx tsc --noEmit` — clean.

package/upgrades/side-effects/initiative-tracker-dashboard-tab.md

@@ -0,0 +1,94 @@
+# Side-Effects Review — Initiative Tracker dashboard tab
+
+**Version / slug:** `initiative-tracker-dashboard-tab`
+**Date:** `2026-04-17`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required — read-only UI surface, identical XSS-safety pattern to the PR Pipeline tab shipped in Phase A commit fb16f5c`
+
+## Summary of the change
+
+Adds an "Initiatives" tab to the dashboard that renders the initiatives
+board at a glance: each initiative's title, status, phases (as pills),
+last-touched date, blockers, and a digest summary of actionable signals
+(stale / needs-user / next-check-due / ready-to-advance).
+
+Read-only. No mutation buttons in this commit — the tracker already
+exposes CRUD via the HTTP API, but the dashboard does not wire any of
+those mutating endpoints to UI actions at this layer. Keeps the XSS
+attack surface minimal while the tracker is new.
+
+Files modified:
+- `dashboard/index.html` — tab button, panel container, TAB_REGISTRY
+  entry, `loadInitiatives()` function (~170 lines).
+- **new** `tests/unit/dashboard-initiativesTab.test.ts` — 9 smoke tests
+  inspecting the HTML to verify wiring, XSS invariant, and signal
+  rendering.
+
+## Decision-point inventory
+
+1. **Read-only vs. mutable UI**: read-only. The API supports mutation
+   via CRUD + phase-transition, but exposing those as buttons would
+   widen the XSS surface and introduce state-mutation from the browser.
+   Defer to a later commit after live-use feedback tells us what, if
+   anything, deserves a UI button.
+2. **Digest panel placement**: top of tab content, only visible when
+   `digestRes.items.length > 0`. Zero items = quiet panel. Matches the
+   "don't push noise" principle for the digest job.
+3. **Status filter default**: 'active'. Most-useful-first; user can
+   flip to 'All' / 'Completed' / 'Archived' / 'Abandoned' via the
+   dropdown.
+4. **Count badge**: tab button shows the count of initiatives matching
+   the current filter (matches Sessions / Jobs tab convention).
+
+## 1. Over-block / 2. Under-block review
+
+N/A — tab is read-only. No gating decision in this surface.
+
+## 3. Level-of-abstraction fit
+
+UI rendering lives next to the PR Pipeline tab (same file, same
+patterns, same XSS invariants). `loadInitiatives()` is a sibling of
+`loadPrPipeline()` in layout and structure.
+
+## 4. Signal-vs-authority review
+
+The digest panel renders **signals** produced by the tracker; the UI
+has no blocking authority over anything. A human user is a smart gate;
+showing them signals is exactly the right hand-off.
+
+## 5. Interactions review
+
+- **No effect on PR Pipeline tab**: separate panel, separate loader,
+  separate TAB_REGISTRY entry.
+- **No effect on other tabs**: tab registry is additive.
+- **XSS**: all content goes through `textContent` or DOM element
+  construction; `innerHTML` is not used anywhere inside
+  `loadInitiatives()`. Enforced by a test.
+
+## 6. External surfaces
+
+- Dashboard HTML served to authenticated users (dashboard PIN or auth
+  token). No new public surface.
+- Two new GET requests when the tab activates:
+  `GET /initiatives?status=active`, `GET /initiatives/digest`. Both
+  behind existing auth middleware.
+
+## 7. Rollback cost
+
+Very low. `git revert` removes the tab button, panel, registry entry,
+and loader function — no residual state.
+
+## Conclusion
+
+Additive UI surface. 9 new smoke tests (all passing). `tsc --noEmit`
+not affected (HTML/JS, not TS). XSS invariant guarded by a test that
+greps the function body for `.innerHTML =` assignments.
+
+Commit 2 of 4 for the Initiative Tracker feature (commit 1 = core +
+API; commit 3 = daily digest job; commit 4 = seed real initiatives).
+
+## Evidence pointers
+
+- Smoke tests: `tests/unit/dashboard-initiativesTab.test.ts` (9 pass).
+- Referenced spec: `docs/specs/INITIATIVE-TRACKER-SPEC.md`.
+- Prior art: `dashboard/index.html` commit `fb16f5c` (PR Pipeline tab).