instar 0.28.64 → 0.28.65

package/upgrades/side-effects/build-stall-visibility-fix2-3.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — /build mid-run heartbeats + long-tool-wait detector (Fix 2 + Fix 3)
+
+**Version / slug:** `build-stall-visibility-fix2-3`
+**Date:** `2026-04-20`
+**Author:** `echo`
+**Spec:** `docs/specs/BUILD-STALL-VISIBILITY-SPEC.md`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Two fixes to surface progress during long /build waits that previously went silent.
+
+**Fix 2 — mid-run heartbeats.** Adds `POST /build/heartbeat` to the agent server. The /build skill (build-state.py) calls it on every phase transition and on completion. The endpoint validates against allowlists (phase / tool / status), enforces a runId regex, requires exactly one of topicId/channelId, and dispatches the templated message via Telegram or Slack. After dispatch, `ProxyCoordinator.recordBuildHeartbeat(topicId)` records the timestamp; `PresenceProxy.fireTier` checks `hasRecentBuildHeartbeat` (default 6-min window) before firing Tier 2/3 standby — so the user hears one progress voice per channel, not two.
+
+**Fix 3 — long-tool-wait detector.** Extends PresenceProxy with a snapshot-diff detector: per-topic state tracks `toolStartedAt` (last unchanged-snapshot baseline) and `lastAgentTextAt`. When `enterThresholdMs` (default 8 min) of unchanged snapshot with a `Cogitated` marker passes, Tier 2/3 swap their templated message to a tool-specific one. Hysteresis exit after `exitHysteresisMs` of sustained new text. One-time escalation at `escalationCapMs`. Feature-flagged off by default.
+
+Files touched:
+- `src/server/routes.ts` — POST /build/heartbeat handler (already present from prior session).
+- `src/monitoring/ProxyCoordinator.ts` — `recordBuildHeartbeat` / `hasRecentBuildHeartbeat` / `clearBuildHeartbeat` (prior session).
+- `src/monitoring/PresenceProxy.ts` — `hasRecentBuildHeartbeat` config + Tier 2/3 suppression (prior session); long-tool-wait detector (`recordAgentText`, `recordToolWait`, `getLongToolWaitMessage`, `updateToolWaitFromSnapshot`) wired into `fireTier2` and `fireTier3` (this session).
+- `src/server/AgentServer.ts` + `src/commands/server.ts` — proxyCoordinator passed into routeContext + hasRecentBuildHeartbeat callback wired to PresenceProxy (prior session).
+- `playbook-scripts/build-state.py` — `post_heartbeat()` helper called from `cmd_transition` and `cmd_complete` (this session).
+- `tests/unit/proxy-coordinator-heartbeat.test.ts` (8) — record/has/clear semantics, default 6-min window, per-topic isolation.
+- `tests/unit/build-heartbeat-route.test.ts` (12) — enum allowlists, runId regex, exactly-one-of-topic/channel, telegram/slack dispatch, ProxyCoordinator integration, 503 on missing transport.
+- `tests/unit/presence-proxy-build-heartbeat-suppression.test.ts` (4) — Tier 1 NOT suppressed; Tier 2/3 suppressed when heartbeat is fresh; normal emission when no heartbeat.
+- `tests/unit/presence-proxy-long-tool-wait.test.ts` (5) — off-by-default; threshold + hysteresis exit + escalation cap; per-topic.
+- `tests/unit/build-state-heartbeat.test.ts` (5) — Python smoke test against a localhost fake server: phase POST, complete POST, no-op when env unset, best-effort on POST failure (audit log entry, no exit code), Slack channel routing.
+
+Decision points touched: heartbeat suppression authority (PresenceProxy), heartbeat dispatch authority (POST /build/heartbeat), tool-wait swap authority (PresenceProxy.getLongToolWaitMessage).
+
+## Decision-point inventory
+
+- **POST /build/heartbeat** — *signal generator* — produces a typed `build-progress` event for ProxyCoordinator + dispatches a templated message. No block/allow on agent prose.
+- **PresenceProxy heartbeat suppression** — *authority* — decides not to fire Tier 2/3 when heartbeat is fresh. Tier 1 deliberately exempt (first signal of life).
+- **PresenceProxy long-tool-wait detector** — *signal generator + message swap* — feeds the existing standby authority a different templated string when tripped. Does not introduce a new block decision.
+
+---
+
+## 1. Over-block
+
+**Heartbeat suppression.** Suppression applies only to Tier 2 (2-min) and Tier 3 (5-min) — never Tier 1 (20-sec). Tier 1's job is the first signal of life when the agent is busy; we want it to fire even when /build is producing heartbeats, so the user hears the standby voice within 20 seconds of a follow-up message. Verified: `presence-proxy-build-heartbeat-suppression.test.ts > does NOT suppress Tier 1 even when a build heartbeat is fresh`.
+
+The suppression window is 6 min while heartbeats fire every ~5 min — one missed/delayed heartbeat does not unsuppress standby (worst case: a slightly stale "phase=executing" beats a "still working" generic). After the 6-min window with no fresh heartbeat, standby resumes — Tier 2 and Tier 3 are rescheduled when the suppression check fires (not cancelled). Verified by inspection of `fireTier`'s reschedule branch.
+
+**Long-tool-wait detector.** Detector is OFF by default. When ON, the swap message replaces (not blocks) the LLM-generated standby — same channel, same tier, same authority, different content. The hysteresis-during-recovery branch suppresses the "blocked" message while sustained text is accumulating, so the user never sees "blocked" while watching new output appear.
+
+---
+
+## 2. Under-block
+
+**Heartbeat suppression.** A single `recordBuildHeartbeat` call wins suppression for 6 min. If the /build skill crashes mid-run and never sends another heartbeat, standby resumes after 6 min — appropriate. If the channel sees a malicious heartbeat (an agent or attacker calls POST /build/heartbeat with junk content), the templated allowlist (phase + tool + status enums + runId regex + elapsedMs bounds) caps the blast radius — no free-form prose, no path leakage, no command injection. The dispatched message is structurally fixed.
+
+**Long-tool-wait detector.** Off by default; the introduction release has zero behavioral change for unconfigured agents. The escalation cap (one-time alert at 30 min) prevents alert fatigue even in pathological hangs. Without escalation cap, an actually-hung tool would silently sit forever — escalation gives the user one explicit cue before going quiet.
+
+The detector relies on snapshot-hash diff plus the `Cogitated for Nm Ns` marker. Snapshot hashes already exist in `PresenceState.tier1SnapshotHash` / `tier2SnapshotHash` for the duplicate-output check — we reuse them, no new state pressure.
+
+---
+
+## 3. Level-of-abstraction fit
+
+POST /build/heartbeat lives at the server route layer alongside other typed-event endpoints (e.g. POST /telegram/post-update). Dispatch via `ctx.telegram.sendToTopic` matches existing routing surface for proxy-class messages. ProxyCoordinator is the right home for the `lastBuildHeartbeatAt` map — it already coordinates PresenceProxy ↔ PromiseBeacon mutex; adding a heartbeat-timestamp dimension keeps three-way deconfliction state in one place.
+
+The long-tool-wait detector lives inside PresenceProxy — same class that owns Tier 2/3 message authority. Adding a detector here is the *minimum viable* change to that authority — we did not introduce a new monitor class. Per signal-vs-authority doc, detector + authority colocation in one class is acceptable when (a) the detector is a pure projection of state already maintained for other reasons (snapshot hashes), and (b) the detector is feature-flagged so its rollout can be reverted without touching the authority.
+
+The build-state.py helper is the lowest-overhead surface for emitting heartbeats — phase transitions are the natural cadence point in the /build state machine. Stdlib-only (urllib.request, hashlib, os, socket) avoids any new Python dependency. Best-effort on failure preserves the build state machine's existing exit-code contract.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Heartbeat dispatch — *signal*. POST /build/heartbeat produces a templated event with enumerated fields and bounds; structural validation at the system boundary, no judgment call. Permitted per doc §"When this principle does NOT apply: Hard-invariant validation."
+- [x] Heartbeat suppression — *authority*. PresenceProxy decides whether to fire Tier 2/3. Single-authority principle preserved: only one progress voice per channel per cycle.
+- [x] Long-tool-wait detector — *signal generator that feeds the existing standby authority*. Detector produces a richer signal (tool identity + elapsed + zero-delta boolean); PresenceProxy remains the one authority deciding whether to send and what to say. No new blocking decision.
+- [x] Tone gate fast-path — heartbeats are templated system messages, not agent prose. Skipping LLM tone-gate invocation is permitted under the structural-validator carve-out (gate_latency_vs_client_timeout memory item).
+
+---
+
+## 5. Interactions
+
+- **PresenceProxy ↔ PromiseBeacon ↔ /build heartbeat** — three-way coordination via ProxyCoordinator. PresenceProxy reads `hasRecentBuildHeartbeat` before sending Tier 2/3 (suppress when /build is talking). PromiseBeacon's existing mutex acquire is unchanged. Heartbeat record is in a *separate* map from the mutex — heartbeats never hold the per-topic mutex, so they cannot starve other proxies.
+- **Long-tool-wait detector ↔ heartbeat suppression** — order matters: heartbeat-suppression check (in `fireTier`) runs *before* the detector check (in `fireTier2`/`fireTier3`). If a heartbeat is fresh, Tier 2/3 is suppressed entirely — the detector swap never runs. This is correct: when /build is talking, we don't want to muddy the channel with the long-wait swap.
+- **Detector ↔ existing snapshot-hash diff** — the detector reuses `state.tier1SnapshotHash` / `state.tier2SnapshotHash` already maintained by `fireTier1`/`fireTier2`. No new persistent state on disk; the per-topic `toolWaitState` map lives in the in-memory PresenceProxy instance, lost on restart (acceptable — Tier 2/3 cycles re-establish baselines).
+- **build-state.py ↔ POST /build/heartbeat** — the helper is best-effort with a 2s timeout. If the local instar server is down or 401s, the audit log records `heartbeat.skipped` and the transition succeeds. The build state machine's exit-code contract is preserved.
+- **Routes registry test** — adding POST /build/heartbeat is a new surface; `route-completeness.test.ts` (existing) iterates handlers, may need update if it asserts a fixed count.
+
+Verified by running new test suite (34 tests across 5 files) and adjacent regression tests (presence-proxy-* and build-state.test.ts, 64 + previous tests).
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the machine:** none — each agent has its own server + ProxyCoordinator instance.
+- **Install base:** new POST /build/heartbeat endpoint; pre-fix /build skills won't call it (no-op). Post-fix /build skills running against pre-fix server will get 404 — caught by best-effort try/except in build-state.py, logged to audit, transition continues.
+- **External services:** Telegram and Slack adapters dispatch the heartbeat text. No external credentials touched. Outbound message is templated → no PII / secret leakage path.
+- **Persistent state:** none. ProxyCoordinator and PresenceProxy detector state are in-memory only.
+- **Telemetry:** new `heartbeat.skipped` audit event in `.instar/state/build/audit.jsonl` when POST fails. Bounded by 200-char error string; no body content stored.
+- **Timing:** 2s POST timeout for build-state.py heartbeat (worst-case 2s overhead per phase transition; happy-path <50ms locally).
+
+---
+
+## 7. Rollback cost
+
+**Per spec §Rollback** — both fixes are independently revertable.
+
+- **Fix 2 rollback (heartbeat).** Revert the five files touched (server routes + monitoring + commands + build-state.py). No persistent state to migrate. ProxyCoordinator's `lastBuildHeartbeatAt` is in-memory and lost on restart. PresenceProxy falls back to standard standby behavior. Channels just stop seeing the templated `🔨 /build —` line.
+
+- **Fix 3 rollback (detector).** Two paths:
+  1. **Config flip** — set `longToolWaitDetector.enabled: false` in PresenceProxy config. Zero deploy. Detector becomes inert; existing behavior restored.
+  2. **Hard revert** — remove the detector code blocks from PresenceProxy.ts and the test file. Tier 2/3 LLM-summary path is the original, untouched.
+
+Cost: ~5 min via config flip, ~30 min via hard revert + test update. No data loss either way.
+
+---
+
+## 8. Acceptance evidence
+
+- POST /build/heartbeat handler at `src/server/routes.ts:4158` with full validation + dispatch + ProxyCoordinator integration.
+- PresenceProxy Tier 2/3 suppression at `src/monitoring/PresenceProxy.ts:617` (untouched from prior session).
+- Long-tool-wait detector public methods (`recordAgentText`, `recordToolWait`, `getLongToolWaitMessage`) on PresenceProxy.
+- build-state.py `post_heartbeat()` called from `cmd_transition` and `cmd_complete`.
+- New tests: 34 passing across 5 new test files.
+- TypeScript: `npx tsc --noEmit` clean.
+- Adjacent regressions: presence-proxy-cancel-race, presence-proxy-idle, presence-proxy-quota, presence-proxy-context-exhaustion, build-state — all green.

package/upgrades/side-effects/build-stop-hook-deployment.md

@@ -0,0 +1,98 @@
+# Side-Effects Review — build-stop-hook.sh deployment + settings-reference validator
+
+**Version / slug:** `build-stop-hook-deployment`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Moves `build-stop-hook.sh` from a one-shot conditional copy in `src/commands/init.ts` into the canonical `PostUpdateMigrator.migrateHooks` pattern — unconditional overwrite on every upgrade, shared content with `init.ts` via `getHookContent('build-stop-hook')`. Adds `PostUpdateMigrator.validateHookReferences` which scans `.claude/settings.json` after `migrateHooks` completes and reports any hook `command:` path under `.instar/hooks/instar/` that does not exist on disk.
+
+Files touched:
+- `src/core/PostUpdateMigrator.ts` — new `getBuildStopHook()`, new `validateHookReferences()`, wired into `migrateHooks` and `getHookContent`.
+- `src/commands/init.ts` — replaced inline copy block with `migrator.getHookContent('build-stop-hook')` write.
+- `tests/unit/PostUpdateMigrator-buildStopHook.test.ts` — 7 new tests covering install-when-missing, idempotent overwrite, getHookContent round-trip, validator flags missing refs, validator passes when refs exist, validator ignores custom/ hooks and external commands, validator is no-op without settings.json.
+
+Decision points touched: none on runtime message flow. The new validator is a structural invariant check at upgrade-time (file existence), not a message/judgment gate.
+
+## Decision-point inventory
+
+- `PostUpdateMigrator.validateHookReferences` — **add** — structural invariant: every `command:` referenced in settings.json pointing to `.instar/hooks/instar/*` must exist on disk. Emits `result.errors` entries; does not throw, does not block upgrade.
+
+---
+
+## 1. Over-block
+
+No block/allow surface on runtime behavior — over-block not applicable to message flow.
+
+Validator-level: the regex `(?:^|\s)(\.instar\/hooks\/instar\/[^\s"]+)` only matches paths under `.instar/hooks/instar/` — the instar-owned subtree. Custom hooks at `.instar/hooks/custom/` and external commands (`/usr/local/bin/foo`, shell builtins) are deliberately skipped. Test coverage: `ignores hooks outside the .instar/hooks/instar/ tree (custom hooks)`.
+
+---
+
+## 2. Under-block
+
+No block/allow surface on runtime behavior — under-block not applicable to message flow.
+
+Validator-level: the validator only inspects `command:` strings. Hooks registered via `type: "http"` would not be checked, but those have their own failure signal (HTTP error) and are outside the "file on disk" invariant this validator owns. A hook referenced through a variable expansion (e.g. `$INSTAR_HOOKS_DIR/foo.sh`) would not be caught — none currently exist in the default settings template.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The build-stop-hook deployment change is pure mechanics — moves one hook into the same installation path already used by the other 18 instar-owned hooks. No new abstraction; removes the one-off conditional copy in init.ts that was the root cause.
+
+The validator lives on `PostUpdateMigrator` alongside `migrateHooks`, which is the correct layer: `PostUpdateMigrator` already owns installing hooks and verifying hook content (see `migrateHttpHooksToCommandHooks` for precedent). Running the check at upgrade time catches drift both when upgrading instar *and* when the user hand-edits settings.json. A runtime-side check (on each Claude Code hook firing) would be lower-level but redundant — Claude Code's own "non-blocking status" already reports missing-file failures, they just aren't surfaced to the user. The upgrade-time check puts the signal where a human or agent will read it.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface (on runtime messages/decisions).
+- [x] Yes — but validator is a hard-invariant structural check (file existence at the system boundary), explicitly permitted per doc §"When this principle does NOT apply": *"Hard-invariant validation. 'This field must be a number.' Typing and structural validators at the boundary of the system are not decision points in the sense this principle applies to — they don't evaluate messages, they reject malformed input."*
+
+The validator is not a message-flow authority and has no brittle judgment call — "file exists on disk" is an enumerable binary fact. It emits into `result.errors` (surface, not block), specifically to avoid wedging upgrades on references we don't own (custom hooks outside the matched path prefix).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** `migrateHooks` runs before `validateHookReferences`, so the validator sees the post-install state — it won't flag `build-stop-hook.sh` as missing after this change (by construction, the write preceded the check). Confirmed by running `migrateHooks` end-to-end in the new test suite — `result.errors` is empty for the happy path.
+- **Double-fire:** No. init.ts writes the hook once at init; `migrateHooks` overwrites on every upgrade. Same content both paths.
+- **Races:** None. Synchronous fs operations, single-threaded.
+- **Feedback loops:** None.
+- **Existing migrators:** `migrateHooks` already contains 17 try/catch blocks that each write one hook. The new `build-stop-hook.sh` block follows the exact same pattern; failures are reported into `result.errors` without aborting the rest of the migration.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the machine:** none directly. Each agent's `PostUpdateMigrator` runs against its own `stateDir`. This change only affects what that agent's migration produces.
+- **Install base:** on next `instar upgrade-ack`, every agent gets the hook deployed (overwriting any local edits — consistent with existing migrator semantics for instar-owned hooks). Agents that never ran an upgrade post-this-change keep seeing the "No such file" errors until they upgrade.
+- **External services:** none.
+- **Persistent state:** writes one file (`.instar/hooks/instar/build-stop-hook.sh`, 755). Does not touch the build-state ledger, dashboard, or any server state.
+- **Timing:** none.
+
+---
+
+## 7. Rollback cost
+
+Pure code change on the installer path. Back-out: revert the three files and ship as a patch release. No persistent state to migrate back. Agents that already received the file on upgrade keep it — functionally a no-op (the hook only fires when a `/build` is active and its state file exists), so no user-visible regression during the rollback window.
+
+If the validator starts emitting a false-positive for some install shape we didn't anticipate, the effect is a noisy `result.errors` entry in upgrade logs — not a broken install. Revertable in isolation.
+
+---
+
+## Conclusion
+
+Change is scoped to one deployment bug with a narrow structural guard to prevent the same shape from recurring. No runtime message flow touched. Test coverage: 7 new unit tests + existing 63 migrator tests all green. TypeScript clean. Ready to ship as a patch release after merge.
+
+---
+
+## Evidence pointers
+
+- Live reproduction (pre-fix): `echo-instar-agent-robustness` tmux pane captured 2026-04-19 ~19:00 PT showing 6× `Stop hook error: bash: .instar/hooks/instar/build-stop-hook.sh: No such file or directory`.
+- Missing file verified on echo's state dir: `ls .instar/hooks/instar/ | grep build-stop-hook` → empty.
+- Post-fix test evidence: `tests/unit/PostUpdateMigrator-buildStopHook.test.ts` 7/7, full PostUpdateMigrator suite 70/70.

package/upgrades/side-effects/dashboard-secrets-tab.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Dashboard Secrets tab
+
+**Version / slug:** `dashboard-secrets-tab`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds a "Secrets" tab to the Instar dashboard that surfaces Secret Drop state to the user: a list of currently pending secret requests with per-item live countdown, an "Open drop link" shortcut, per-item Cancel button, and a "Create test request" button for verification. The tab is positioned after "Send Content" and before "Jobs" for prominence. The implementation is pure dashboard — HTML, DOM-building JS, and a 1-second ticker — against the existing `/secrets/pending`, `/secrets/request`, and `/secrets/pending/:token` endpoints. No server code is added or modified.
+
+Files touched:
+- `dashboard/index.html` — tab button, panel div, TAB_REGISTRY entry, `loadSecrets()`, ticker, `createTestSecretRequest()`.
+- `tests/unit/dashboard-secretsTab.test.ts` — smoke tests mirroring the initiatives pattern (tab wiring, loader definition, endpoint usage, XSS invariant).
+
+## Decision-point inventory
+
+This change has no decision-point surface. It is a read-only presentation layer plus two user-initiated actions (create-test, cancel) that call existing routes. No gating, filtering, blocking, or routing logic is introduced.
+
+- *(none — presentation-only)*
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is presentation on top of existing transport endpoints. The right layer: the dashboard already owns other read-only capability views (Initiatives, Commitments, PR Pipeline), and the Secrets tab follows that pattern exactly — TAB_REGISTRY entry, panel div, async loader, textContent-only rendering. No new primitive, no duplication of an existing view. The live-countdown ticker is a tab-local concern and is started/stopped by the tab's own activate/deactivate hooks, matching the precedent set by `integratedBeingPollTimer`.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The tab reads `/secrets/pending` and displays it. The "Create test request" button calls `/secrets/request` with user-initiated intent. The Cancel button calls `DELETE /secrets/pending/:token` with user-initiated intent. None of these are judgment decisions about meaning or agent intent; they are direct user actions mediated by the dashboard. The underlying endpoints already enforce their own structural validation (label length, ttl bounds, concurrent-request cap).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** None. The tab renders its own panel and does not wrap or intercept any other tab's flow. `switchTab()` handles panel visibility via the existing TAB_REGISTRY.
+- **Double-fire:** The ticker is a 1-second interval that updates DOM textContent of elements keyed by `secretCountdown-${token}`. Elements missing from the DOM short-circuit. `startSecretsTicker()` calls `stopSecretsTicker()` first to prevent double-registration if a user rapidly switches tabs. `onDeactivate` clears the ticker.
+- **Races:** The ticker reads from `secretsLastPending` (module-level) which is rewritten on each `loadSecrets()` call. Worst case under rapid switch + reload: a tick runs against stale data and updates countdowns by one extra second before the next reload; no correctness impact.
+- **Feedback loops:** None — the tab is a read surface. The only write actions are user-initiated (create-test, cancel). Creating a test request will occupy one of the 20 concurrent-request slots for up to 5 minutes; server-side rate limiting is unchanged and enforces the cap.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** No change. Secret Drop state is per-agent-server.
+- **Other users of the install base:** New dashboard tab appears on version upgrade. Additive — no existing UI element is removed or repositioned except the visible gap between "Send Content" and "Jobs" which now contains the new button.
+- **External systems:** None. No new outbound calls.
+- **Persistent state:** None. Secret Drop state is in-memory by design; this change does not persist anything.
+- **Timing/runtime:** The 1-second ticker runs only while the Secrets tab is active. Negligible CPU.
+
+---
+
+## 7. Rollback cost
+
+Pure presentation change. Revert the two file changes (`dashboard/index.html`, new test file) and ship as a patch. No data migration, no agent state repair, no user-visible regression beyond the tab disappearing.
+
+---
+
+## Conclusion
+
+Straightforward additive UI work that gives users and agents eyes on Secret Drop state. No decision-point surface; signal-vs-authority does not apply. Existing endpoint tests cover the backend (25 tests in `SecretDrop.test.ts` still passing). New dashboard smoke tests (12) exercise the HTML-level invariants — tab wiring, loader presence, endpoint usage, XSS safety — matching the pattern established for Initiatives and PR Pipeline tabs. Safe to ship.
+
+---
+
+## Evidence pointers
+
+- Test run: `npx vitest run tests/unit/dashboard-secretsTab.test.ts` → 12/12 passed.
+- Regression sanity: `dashboard-initiativesTab`, `dashboard-prPipelineTab`, `dashboard-resumeLive`, `SecretDrop` → 49/49 passed together.

package/upgrades/side-effects/threadline-relay-rapid-fire-pipe-guard.md

@@ -0,0 +1,46 @@
+# Side-effects review — threadline relay rapid-fire same-thread pipe guard
+
+**Scope**: Close high-severity data-loss bug where rapid-fire messages on the same Threadline thread silently drop because `PipeSessionSpawner.spawn` unconditionally kills the prior `tmux` session, and the pipe eligibility gate never checks whether a prior pipe session is already live on that thread.
+
+**Files touched**:
+- `src/threadline/PipeSessionSpawner.ts` — add `hasActiveSessionForThread(threadId: string): boolean` method that iterates the existing `activeSessions` Map and returns true iff any session's `threadId` matches. No new state, no new configuration.
+- `src/commands/server.ts` — extend the Phase 2a pipe-mode eligibility condition at ~line 5688 to also require `!pipeSpawner.hasActiveSessionForThread(msg.threadId)`. When the guard fires, control falls through to the existing Phase 2b listener-inbox path, which serializes deliveries via `ListenerSessionManager.writeToInbox` → inbox.jsonl append.
+
+**Under-block**: None for the target bug. The guard covers every rapid-fire same-thread case at the exact chokepoint (relay handler, pre-pipe-spawn). There is no remaining code path where two same-thread messages could reach `spawn()` concurrently with pipe-mode enabled.
+
+**Over-block**: Minimal. If a prior pipe session is "stuck" (tmux alive but claude process hung), subsequent messages for that thread now go through the listener rather than killing the stuck session. This is actually desirable — killing a stuck pipe session was previously how operators unblocked threads, but that kill was a side-effect of a concurrency bug, not a designed recovery path. The proper recovery (listener accumulates the messages; stuck pipe session eventually times out via existing `maxRuntimeMs`; next request after timeout enters pipe mode cleanly) is already the intended behavior.
+
+**Level-of-abstraction fit**: `PipeSessionSpawner` already owns the `activeSessions` Map and the `threadId` field on each session. Adding a lookup method at this abstraction is the correct home — the server.ts caller asks a question of the spawner rather than reaching into its internal Map. The guard in server.ts stays at the relay-routing level where Phase 2a/2b selection already lives.
+
+**Signal vs authority**: No authority change. `PipeSessionSpawner` remains the single authority over pipe-mode sessions; the new method is a read-only query. The server.ts caller gains one new piece of information but no new authority.
+
+**Interactions**:
+- `ListenerSessionManager.writeToInbox` is exercised more often now (every rapid-fire same-thread overflow). Its contract (append to inbox.jsonl, serialized by file lock) is already designed for this and is the safer path per cluster research.
+- `activeSessions.delete(sessionName)` on session exit (existing line ~390) means the guard correctly opens again when a session completes — no permanent lockout.
+- Auto-ack behavior (line 5681-5684) is unchanged; acks still fire immediately before the routing decision.
+- `threadResumeMap` check remains in front of the guard, preserving thread-resume semantics untouched.
+
+**External surfaces**:
+- New public method: `PipeSessionSpawner.hasActiveSessionForThread(threadId: string): boolean`.
+- No new CLI flag, no new config field, no new API endpoint, no new log format, no new metric.
+
+**Rollback cost**: Trivial. Revert two files. No migration. No data format change. Existing `inbox.jsonl` files remain valid under both old and new code paths.
+
+**Tests**:
+- The change is verified to compile cleanly (`npm run build` passes with the change; PipeSessionSpawner.ts and server.ts emit valid JS into `dist/`).
+- `npm test` vitest run executed (see trace).
+- The new method is trivial (single Map iteration); its correctness is directly observable in the server.ts guard at runtime.
+- An integration test that demonstrates rapid-fire messages queue serially through the listener inbox instead of killing each other is the natural next coverage, but is out of scope for this minimal fix. The existing unit suite for `PipeSessionSpawner` remains green.
+
+**Decision-point inventory**:
+1. **Method name**: `hasActiveSessionForThread` (vs. `isThreadActive`, `threadHasSession`) — chosen to mirror the existing `activeSessions` field name so readers find the answer by following the noun. The method is a direct question about the collection it owns.
+2. **Guard placement**: Inline in the Phase 2a `if` condition (vs. inside `shouldUsePipeMode`) — kept in server.ts because the fall-through target (Phase 2b listener path) is a server.ts concept. Putting the check inside `shouldUsePipeMode` would return `{eligible: false}` but couldn't express "eligible for listener, not pipe", which is the actual semantics we want. The eligibility gate in the spawner remains a pure property of the spawner's capacity/trust/iqs/length gates.
+3. **Fallthrough target**: Phase 2b listener inbox (vs. Phase 2c cold-spawn) — per research, the listener inbox already serializes rapid-fire via a file append + lock, which is the correct model for same-thread queuing. Cold-spawn would also work but creates a new session per message, defeating the listener's reuse.
+4. **No cache TTL**: `activeSessions` entries are already removed on session exit (`activeSessions.delete(sessionName)` in existing cleanup path). No stale-entry risk; no TTL needed.
+
+**Why LOW risk**:
+- Purely additive: new method + new boolean term in an existing `if`.
+- Fall-through target is already the documented safer path for ineligible-for-pipe messages.
+- No change to behavior when the guard does not fire (i.e., the common single-message-per-thread case).
+- No data-format change; no persistent state added.
+- Reversible with a two-line revert.

package/upgrades/side-effects/watchdog-mcp-version-pin.md

@@ -0,0 +1,121 @@
+# Side-Effects Review — Watchdog `-mcp`/`/mcp` exclusion: allow `@version` suffix
+
+**Version / slug:** `watchdog-mcp-version-pin`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `general-purpose subagent`
+
+## Summary of the change
+
+Two exclusion regexes in `src/monitoring/SessionWatchdog.ts` (added in the prior watchdog-user-comfort change) were missing a token boundary case: version-pinned package invocations like `npm exec @playwright/mcp@latest` or `foo-mcp@1.2.3`. The lookahead only allowed `$`, whitespace, `/`, or `.` after `mcp`, so a trailing `@version` escaped the match and the watchdog killed the MCP server. Direct observation: `watchdog-interventions.jsonl` shows a SIGTERM on `npm exec @playwright/mcp@latest` at 2026-04-19T20:16Z on `echo-session-robustness`. Fix: add `@` to both lookaheads. Two new test cases cover `@playwright/mcp@latest`, `@playwright/mcp@1.2.3`, `@modelcontextprotocol/mcp@0.5.0`, `some-other-mcp@2.0.0`, and `foo-mcp-server@latest`.
+
+## Decision-point inventory
+
+- `SessionWatchdog.EXCLUDED_PATTERNS` (both MCP regexes) — **modify** — broaden lookahead by one character (`@`).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The added `@` boundary lets the exclusion match when `mcp` is followed by an `@`. Legitimate commands that:
+- Contain the literal `-mcp@` or `/mcp@` as a token with `@version`-shaped suffix
+- Are NOT long-running MCP stdio servers
+…would be mistakenly skipped by the watchdog. Plausible false-positive candidates: a shell alias or binary named `something-mcp` invoked with an email address as an argument (e.g., `something-mcp user@example.com`). The `-mcp` regex matches here. However, any binary named `*-mcp` is almost certainly an MCP stdio server by convention, so skipping it is safe. No credible legitimate rejection found.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- MCP servers whose command line uses `mcp` as an internal path component but not as the trailing token (e.g. `node /opt/weird-mcp-launcher/bin.js`) — already handled by the existing `-mcp` regex since `-mcp-launcher` ends with `/`.
+- An MCP server whose executable is named without a `-mcp` or `/mcp` marker (e.g. `claude-code-bridge` that happens to be an MCP server). No naming convention, so the exclusion list cannot know. This is a broader architectural gap, not new.
+- Commands hidden behind a wrapper (`bash -c "… | mcp-thing"`) where ps reports only the outer shell. Unchanged from before.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+EXCLUDED_PATTERNS is a low-level, brittle detector. It holds pass-through authority for watchdog kills — "if name matches, skip the kill ladder." The prior side-effects review (watchdog-user-comfort.md) accepted this as a safety carve-out: brittle exclusion is OK when the default action is irreversible (SIGKILL) and the cost of an over-block is "watchdog lets a truly-stuck process run longer." This change extends the same detector's coverage; it does not change its layer or authority. Appropriate.
+
+---
+
+## 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] Yes — but this is a *safety guard* on an irreversible kill action, not a block/allow gate on user input. The layered-authority principle permits brittle detectors when the default action is destructive. See prior review (`watchdog-user-comfort.md` §4) for the accepted carve-out.
+
+No change in compliance posture. The regex is still a pass-through filter on watchdog-initiated kills; the kill ladder is still the authority.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** None. The regex runs inside `isExcluded()`; no other code path intercepts.
+- **Double-fire:** None. The change only broadens what `isExcluded()` returns true for; it cannot cause the watchdog to fire twice.
+- **Races:** None. Pure pattern evaluation, no shared state.
+- **Feedback loops:** None. The exclusion short-circuits the kill ladder; it cannot re-enter.
+
+Confirmed by reading `SessionWatchdog.ts`: `isExcluded()` is called from `checkChildren()` only, single call site, no downstream handlers.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the same machine: unchanged — each agent runs its own watchdog.
+- Install base: unchanged — behavior is strictly more lenient (fewer kills), no breaking change.
+- External systems: unchanged — no external calls.
+- Persistent state: `watchdog-interventions.jsonl` will see fewer entries for MCP commands. Historical entries unchanged.
+- Timing: no timing change.
+
+No external surface changes.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix:** revert the regex change (two character deletions) and ship as a patch. Trivial.
+- **Data migration:** none. No persistent state shape change.
+- **Agent state repair:** none. Agents pick up the change on restart via shadow-install rsync.
+- **User visibility:** during rollback window, watchdog would once again kill `@scope/mcp@version` commands — same regression we just fixed. User-visible: the "wrench" message appears less often (or again, on rollback). No data loss.
+
+Low rollback cost.
+
+---
+
+## Conclusion
+
+Two-character change fixing a concrete regex gap observed in production just hours ago (`@playwright/mcp@latest` was SIGTERM'd). Added two test cases covering the version-pin variant. Same layer, same authority, strictly fewer kills, fully reversible. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** general-purpose subagent
+**Independent read of the artifact: concur**
+
+- No credible over-block: theoretical `rm /path/mcp@backup`-style matches don't survive to kill thresholds.
+- No catastrophic backtracking: simple char classes with single `+`, no nested repetition, linear time.
+- Minor still-missed gap: docker `foo/mcp:latest` and pip `foo/mcp==1.0` style pins are not covered — but those were not the observed failure mode; reviewer recommends waiting for live evidence before expanding. Scoping the fix to the observed `@version` token is the right discipline.
+- Non-blocking suggestion: add a comment above the regexes listing the accepted boundary chars (`$ \s / . @`) for future extenders. Applied below.
+
+---
+
+## Evidence pointers
+
+- Live evidence of the bug: `.instar/watchdog-interventions.jsonl` entry at `1776654972394` (2026-04-19T20:16:12Z), `echo-session-robustness`, command `npm exec @playwright/mcp@latest`, level 1 (Ctrl+C) then level 2 (SIGTERM), outcome `recovered` after 60s.
+- Regex verification: `node -e "…"` script in session trace confirming 4 legitimate NOT-EXCLUDED cases remain NOT-EXCLUDED post-fix, 6 MCP-shaped cases now EXCLUDED.
+- Test additions: `tests/unit/SessionWatchdog-mcp-exclusion.test.ts` (21 passing, 2 new).

package/dist/core/InitiativeDigestJob.d.ts

@@ -1,54 +0,0 @@
-import type { InitiativeTracker, Digest } from './InitiativeTracker.js';
-export interface InitiativeDigestJobOptions {
-    tracker: InitiativeTracker;
-    /** Called with the formatted digest message when there's something to send. */
-    sendMessage: (text: string) => Promise<void> | void;
-    /** How often to scan. Default: 24 hours. */
-    intervalMs?: number;
-    /** Don't re-send the same digest within this window. Default: 23h. */
-    resendSuppressionMs?: number;
-    /**
-     * Delay before the first scan. Default: 60s (gives the server time
-     * to finish startup so we don't ping during a partial boot).
-     */
-    initialDelayMs?: number;
-    /** Time source (injectable for tests). */
-    now?: () => Date;
-}
-export interface LastSend {
-    signature: string;
-    at: string;
-}
-export declare class InitiativeDigestJob {
-    private readonly tracker;
-    private readonly sendMessage;
-    private readonly intervalMs;
-    private readonly resendSuppressionMs;
-    private readonly initialDelayMs;
-    private readonly now;
-    private lastSend;
-    private initialTimer;
-    private intervalTimer;
-    private running;
-    constructor(opts: InitiativeDigestJobOptions);
-    start(): void;
-    stop(): void;
-    /**
-     * Run one scan. Exposed for tests and for the manual-trigger API.
-     * Returns the digest that was scanned and whether a message was sent.
-     */
-    tick(): Promise<{
-        digest: Digest;
-        sent: boolean;
-        suppressedReason?: string;
-    }>;
-    /**
-     * Stable hash of the digest (reason + initiativeId pairs, sorted) so
-     * that identical digests produce identical signatures regardless of
-     * map iteration order.
-     */
-    private signatureOf;
-    format(digest: Digest): string;
-    getLastSend(): LastSend | null;
-}
-//# sourceMappingURL=InitiativeDigestJob.d.ts.map

package/dist/core/InitiativeDigestJob.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"InitiativeDigestJob.d.ts","sourceRoot":"","sources":["../../src/core/InitiativeDigestJob.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,+EAA+E;IAC/E,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ;AAMD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,0BAA0B;IAS5C,KAAK,IAAI,IAAI;IASb,IAAI,IAAI,IAAI;IAQZ;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BnF;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAQnB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IA4B9B,WAAW,IAAI,QAAQ,GAAG,IAAI;CAG/B"}