instar 1.3.236 → 1.3.237

package/upgrades/side-effects/gemini-multi-turn-loop-driver.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — Gemini multi-turn loop-driver (engine increment)
+
+**Version / slug:** `gemini-multi-turn-loop-driver`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (dark + unwired engine increment; the
+spendable surface — the invoking route/wiring — is a separate later increment
+that will carry its own review)
+
+## Summary of the change
+
+Adds `GeminiLoopDriver` (`src/monitoring/GeminiLoopDriver.ts`), a dependency-
+injected engine that drives a gemini task across turns via the native
+`gemini -r <handle>` resume path (turn 1 one-shot establishes the session; later
+turns resume by a stable handle, re-prompting with only the next instruction so
+no transcript is re-sent). Adds the `buildGeminiResumeArgv` transport helper. The
+engine is NOT invoked anywhere yet (dark + unwired); only its 14 unit tests
+exercise it.
+
+## Decision-point inventory
+
+The engine makes five terminal decisions per run: done-sentinel detected,
+turn-cap reached, budget-gate closed, spawn failure (non-zero exit), and
+handle-capture failure. Each is covered both-sides in the unit suite.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** Nothing in production today —
+the engine is unwired, so no caller is gated by it. Within a run: a closed budget
+gate halts before spawning (intended — that IS the overspend guard), and a
+`null` handle-capture aborts the loop after turn 1 rather than resuming (intended
+— resuming `latest` could hijack a foreign session; aborting is the safe choice).
+The `maxTurns` clamp floors at 1, so a 0/negative cap still runs exactly one turn
+rather than zero or infinite.
+
+## 2. Under-block
+
+**What does this still miss?** The engine does not itself enforce a token budget —
+it delegates to the injected `budgetGate`, which is wired to the real
+QuotaTracker only in the (later) invocation increment; an integrator that injects
+a permissive gate gets no budget protection. It does not detect a wedged turn
+mid-spawn (it relies on the injected spawn's own timeout, which the real
+`spawnGeminiAndWait` provides). It does not yet verify the empirically-noted 3+
+turn resume-accumulation (a live-verify gate recorded in the spec before any
+enable). Completion relies on the mentee emitting the sentinel OR (later) a judge;
+a mentee that finishes silently without the sentinel runs to the turn cap.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The engine sits in `src/monitoring/` beside the other
+driver/lifecycle components and depends only on the gemini transport's pure argv
+builders (`buildGeminiOneShotArgv` / `buildGeminiResumeArgv`); all I/O is
+injected, so the subscription-auth guarantee stays in the transport
+(`buildGeminiChildEnv` strips billing env) and is reused, not re-implemented. The
+resume argv helper lives in the transport module next to the one-shot builder,
+keeping the gemini-cli invocation surface in one place.

package/upgrades/side-effects/parallel-activity-coherence.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — Parallel-Work Awareness, Phase A core (cross-topic index)
+
+**Version / slug:** `parallel-activity-coherence`
+**Date:** `2026-06-03`
+**Author:** `Echo (instar-dev agent)`
+**Tier:** `2` (new capability; converged + approved spec: docs/specs/parallel-activity-coherence.md)
+**Second-pass reviewer:** `not required (the converged spec carries a 2-reviewer adversarial+integration pass that reshaped it)`
+
+## Summary of the change
+Phase A CORE of the Parallel-Work Awareness feature: `ParallelActivityIndex` — a thin
+CROSS-topic read aggregator over the EXISTING Topic-Intent Layer. It does NOT add a new
+per-topic store (convergence: that would duplicate `TopicIntentStore`); it only READS the
+existing per-topic intent files and presents the cross-topic view ("all my topics + what
+each is working on") that genuinely did not exist. Plus `extractTags` — high-specificity
+token extraction (drops generic boilerplate so two "fix the test" topics don't false-match).
+
+New:
+- `src/core/ParallelActivityIndex.ts` — enumerate `{stateDir}/topic-intent/*.json`; per
+  topic derive `focus` (latest goal > latest decision > purpose), `tags` (high-specificity
+  tokens), `refCount`, `updatedAt`, `running`. Read-only; an injectable `getRefs` seam for
+  testability (production uses the real `TopicIntentStore.getRefsAtOrAbove`).
+- `tests/unit/parallel-activity-index.test.ts` — 7 tests.
+
+Phase A is now COMPLETE: `GET /parallel-work/activities` route + CapabilityIndex entry
+(`parallelWork`, prefixes `['/parallel-work']`) + server wiring (constructed in AgentServer
+in its OWN try/catch, injected into routeCtx, `running` enriched from the live session list)
++ integration/e2e tests + CLAUDE.md template + migrateClaudeMd agent-awareness. The overlap
+ParallelWorkSentinel is Phase B (ships dark), a separate PR.
+
+## Phase B (overlap sentinel core — added to this PR)
+- `src/monitoring/ParallelWorkOverlap.ts` — the PURE cross-topic overlap detector: activity
+  gate (only recently-worked topics), IDF/specificity weighting over the already-boilerplate-
+  filtered tags, ≥1 shared high-specificity tag required, self-exclusion, signature = sorted
+  shared-tag set, + `signatureChangedMaterially` (hysteresis) and `pairKey`. No I/O, no real
+  time (injected nowMs) ⇒ exhaustively unit-tested (11 tests).
+- `src/monitoring/ParallelWorkSentinel.ts` — the stateful councilor: `tick(nowMs)` reads the
+  activities, runs the detector, and emits ONE `overlap` nudge per genuinely-fresh overlap.
+  Containment: PAIR-KEYED cooldown (survives focus edits), signature hysteresis (no re-nag on
+  a one-token tweak), audit sink for every transition. SIGNAL-ONLY (emits an event; never
+  gates/mutates). 6 tests. The cadence + lease-gating + server wiring + config (ships dark) +
+  the nudge→Telegram/sentinel-events routing are the remaining wiring on this branch.
+
+## Decision-point inventory
+- `ParallelActivityIndex` read aggregation — **add** — pure read over existing state; no
+  block/allow surface, no mutation.
+- `ParallelWorkOverlap` / `ParallelWorkSentinel` — **add** — pure detector + a signal-only
+  EventEmitter; no block/allow surface, no mutation. The nudge informs; the agent decides.
+
+## 1./2. Over/Under-block
+No block/allow surface. Signal-only observability over existing data.
+
+## 3. Level-of-abstraction fit
+Correct — it reads the Topic-Intent layer (the right source for "what each topic intends")
+and presents a cross-topic view; it does not re-implement intent capture or storage.
+
+## 4. Signal vs authority
+**Reference:** docs/signal-vs-authority.md. [x] No block/allow surface. A read aggregator.
+
+## 5. Interactions
+- **No new store / no new write path** — reuses `TopicIntentStore` (which already has the
+  structural per-turn write path via TopicIntentCapture). No duplication, no second decay engine.
+- **False-positive containment starts here:** `extractTags` strips generic boilerplate +
+  requires specificity (compound/identifier tokens, or rare ≥4-char words), so the Phase B
+  overlap comparison rests on genuine shared entities, not coincidental generic words.
+- **Robustness:** missing intent dir ⇒ empty list; a corrupt/again topic file ⇒ that topic
+  contributes no refs (swallowed), never throws.
+
+## 6. External surfaces
+- (Remaining) `GET /parallel-work/activities` + CapabilityIndex classification (the #727
+  lesson). No persistent state of its own (reads existing topic-intent files). Config flag
+  (`monitoring.parallelWorkSentinel`) lands with the sentinel (Phase B), ships dark.
+
+## 7. Rollback cost
+Pure additive read code. Revert ⇒ gone, no state, no migration.
+
+## Conclusion
+Phase A core complete + unit-tested (7 tests, tsc clean): the cross-topic index over the
+existing Topic-Intent layer + specificity-aware tag extraction. Non-duplicative (the
+convergence-mandated reshape). Route + wiring + integration/e2e + agent-awareness follow on
+this branch; the overlap ParallelWorkSentinel is Phase B (ships dark).
+
+## Evidence pointers
+- `tsc --noEmit` clean; `vitest run tests/unit/parallel-activity-index.test.ts` → 7/7
+  (extractTags specificity boundary incl. the cpu vs cpu-sampling case; focus derivation
+  goal>decision>purpose; tags; running/nickname; empty-dir ⇒ []).