instar 1.3.235 → 1.3.237

package/upgrades/1.3.237.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+First increment (the pure engine) of the **Gemini multi-turn loop-driver**
+(`need-gem-002`) — the mechanism that will let a Gemini mentee sustain a
+multi-turn task instead of being bounded to one-shots (the #1 program-need from
+the codey-to-gemini apprenticeship retro).
+
+A new `GeminiLoopDriver` (`src/monitoring/GeminiLoopDriver.ts`) drives a goal
+across turns. Unlike Claude/codex — which run as persistent hook-capable sessions
+and re-prompt via the autonomous Stop hook — gemini runs as one-shots, so the loop
+is driven EXTERNALLY: turn 1 is a one-shot that establishes a session, and each
+later turn re-spawns gemini with the proven native resume path. Because gemini
+restores the session's context itself, the driver re-prompts with only the next
+instruction — never the accumulated transcript — which is the quota-efficient
+design that respects the subscription-auth / no-overspend rule.
+
+The engine is fully dependency-injected (the gemini spawn, an optional budget
+gate, the session-handle capture, sleep, clock), so its loop logic is exercised
+by 14 unit tests with zero real gemini calls and zero quota. It terminates on a
+done-sentinel, a turn cap, a budget-gate halt, a spawn failure, or a
+handle-capture failure (it ABORTS rather than resuming a foreign session). A
+companion transport helper `buildGeminiResumeArgv` adds the `-r <handle>` resume
+argv (keeping the explicit `-m` that bypasses gemini-cli's flaky pre-turn
+model-router classifier).
+
+This increment is **dark and unwired**: nothing invokes the engine yet. Lifecycle
+invocation (a budget-gated route + the apprenticeship machinery calling it, the
+real `--list-sessions` handle parser, and a config flag) is the next increment,
+which is where the §6 budget-guardrail defaults are finalized. Spec:
+`docs/specs/gemini-multi-turn-loop-driver.md`.
+
+**Your agent can now see what all its hands are doing across topics at once.** A new
+cross-topic Activity Index reads your existing per-topic intent and presents one view:
+every topic, its current focus, high-specificity tags, and whether a session is live on
+it. This is the antidote to self-blindness — starting work in one topic that another topic
+already finished (the exact thing that happened in the resource-tracking workstream, where
+one topic re-specced CPU work another had already shipped).
+
+Crucially, this does NOT add a new store. The design review found that the per-topic focus
+data already exists (the Topic-Intent layer, updated structurally on every turn), so this is
+a thin read-aggregator over it — no duplication, no new write path to remember.
+
+This is Phase A (the read surface). The proactive overlap councilor — a sentinel that
+notices "two of your topics are working on the same thing" and tells you — is Phase B and
+ships separately (and dark, because a false-positive nudge is worse than silence).
+
+## What to Tell Your User
+
+Nothing is live to announce yet. This is internal groundwork — a tested engine
+that, once wired up in a following change, will let the Gemini agent work through
+a multi-step task on its own (on subscription login, never an API key) instead of
+stopping after one reply. It ships turned off and disconnected, so it changes
+nothing about how I work today. I will only surface it as a real capability once
+it is wired, budget-guarded, and verified.
+
+Your agent is now less likely to duplicate work across different conversations. It can list
+what each of its topics is working on in one place, so before it starts something big it can
+notice another topic already has it covered. Nothing to configure; it reads data the agent
+already keeps.
+
+## Summary of New Capabilities
+
+- `GET /parallel-work/activities` — read-only cross-topic index: per topic, its current focus,
+  high-specificity tags, freshness, and whether a session is live on it.
+- A specificity-aware tag extractor that ignores generic boilerplate (so two topics that both
+  say "fix the test" don't look like the same work) and keeps genuine shared entities.
+
+## Evidence
+
+- Converged spec (2-reviewer adversarial + integration pass that RESHAPED the design — from a
+  new store to a thin index over the existing Topic-Intent layer, with a distinct
+  /parallel-work prefix to avoid the existing Coherence-Gate naming collision):
+  docs/specs/parallel-activity-coherence.md.
+- All three test tiers green: 7 unit (extractTags specificity boundary incl. cpu vs
+  cpu-sampling; focus derivation goal>decision>purpose; empty-dir ⇒ []), 2 integration
+  (200/503), 3 e2e (feature-alive on the real AgentServer init path + Bearer-auth + read-only).
+  tsc clean.

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 ⇒ []).

package/upgrades/side-effects/per-component-framework-routing.md

@@ -0,0 +1,88 @@
+# Side-Effects Review — Per-component framework routing (B1)
+
+**Version / slug:** `per-component-framework-routing`
+**Date:** `2026-06-03`
+**Author:** `Echo (instar-dev agent)`
+**Tier:** `2` (new capability; converged + approved spec: docs/specs/per-component-framework-routing.md)
+**Second-pass reviewer:** `not required (the converged spec already carries a 2-reviewer adversarial+integration pass)`
+
+## Summary of the change
+Adds an `IntelligenceRouter` at the single LLM funnel so different internal components
+(sentinels, gates, …) can be routed to different agentic frameworks (e.g. all sentinels on
+Codex while the agent stays on Claude), to move that LLM chatter off the Claude rate-limit
+budget. ABSENT-by-default config ⇒ byte-identical to today.
+
+New / changed:
+- `src/core/componentCategories.ts` (NEW) — component-name → category registry + resolver.
+- `src/core/IntelligenceRouter.ts` (NEW) — funnel-level, per-call, per-framework routing with
+  per-framework circuit breakers and circuit-aware fallback.
+- `src/core/intelligenceProviderFactory.ts` — additive `breaker?` option threaded to the wrap
+  calls (lets the router give each framework its OWN breaker).
+- `src/core/CircuitBreakingIntelligenceProvider.ts` — `wrapIntelligenceWithCircuitBreaker`
+  gains an optional `breaker` param (default unchanged = global singleton).
+- `src/core/types.ts` — additive `attribution.category?` on IntelligenceOptions; additive
+  `sessions.componentFrameworks?` config (TYPE-ONLY — NOT added to ConfigDefaults).
+- `src/commands/server.ts` — wrap the shared provider in the router in its OWN try/catch.
+- `tests/unit/intelligence-router.test.ts` (NEW) — 11 tests.
+
+## Decision-point inventory
+- `IntelligenceRouter.evaluate` routing — **add** — chooses WHICH framework answers; no
+  block/allow authority (providers are signal). The one safety branch is fallback (D4).
+- `wrapIntelligenceWithCircuitBreaker` / factory `breaker?` — **modify (additive)** — default
+  path unchanged; only the router passes a distinct breaker.
+
+## 1. Over-block / 2. Under-block
+No block/allow surface — providers are SIGNAL. The router cannot block a running agent; the
+worst it does is degrade-and-report (D4). Unconfigured, it is a transparent passthrough.
+
+## 3. Level-of-abstraction fit
+Correct — the router sits at the existing `CircuitBreakingIntelligenceProvider` funnel (the
+one chokepoint every `.evaluate()` already passes), so it covers ALL callers (including the
+config-path and inline-closure ones) without editing 38 call sites — Structure > Willpower.
+
+## 4. Signal vs authority compliance
+**Reference:** docs/signal-vs-authority.md. [x] No block/allow surface of its own. Routing
+changes which model answers; it adds no gate. The per-framework breakers are the existing
+breaker authority, now correctly ISOLATED per framework (a Claude trip no longer pauses Codex)
+— a correctness improvement, not a new authority.
+
+## 5. Interactions
+- **Breaker isolation:** each non-default framework gets a distinct `new LlmCircuitBreaker()`
+  (proven by unit test — a routed call reaches a different provider instance than the default).
+  The default framework keeps the global singleton, so status/health surfaces are unchanged for
+  it. (Per-framework breaker states are additionally surfaced via GET /intelligence/routing —
+  part 2 of B1, see "Remaining".)
+- **Fallback (D4):** binary-missing → degrade to default + DegradationReporter (no silent
+  fallback — composes with Task-1's re-armed gate); rate-limited → LlmCircuitOpenError
+  propagates and the caller swallows it into its heuristic (NO herd onto Claude).
+- **Cascade-503:** the router is built in its OWN try/catch in server boot; a build failure
+  leaves the raw provider, never 503s the server.
+- **Config:** type-only; NOT in ConfigDefaults (applyDefaults deep-merge would otherwise inject
+  it everywhere and break absent-equals-unchanged).
+
+## 6. External surfaces
+- (Remaining in this PR) `GET /intelligence/routing` read-only surface + its CapabilityIndex
+  classification (the #727 lesson). No persistent state. Config: `sessions.componentFrameworks`
+  (opt-in, absent by default).
+
+## 7. Rollback cost
+Pure additive + opt-in. Remove `componentFrameworks` (or revert) → every call routes to the
+single shared provider exactly as today. No state, no migration.
+
+## Conclusion
+B1 complete across all three test tiers (tsc clean): per-call funnel resolution,
+per-framework breaker isolation, circuit-aware fallback, live-config (hot), the category
+registry, factory breaker-threading, config type, server wiring, the `GET /intelligence/routing`
+read surface (+ CapabilityIndex INTERNAL_PREFIXES classification — the #727 lesson),
+CLAUDE.md agent-awareness (template + migrateClaudeMd for existing agents). Tests: 11 unit
+(`intelligence-router.test.ts`) + 3 integration (`intelligence-routing-routes.test.ts`,
+200/503) + 3 e2e (`intelligence-routing-lifecycle.test.ts`, feature-alive on the real
+AgentServer init path + Bearer-auth + read-only). The design was converged (2-reviewer
+adversarial+integration) which corrected the breaker-isolation and resolution-point design
+before any code — see the spec's Convergence Report. B2 (gates/reflectors + per-framework
+spend accounting + dashboard view) is a deliberate follow-up.
+
+## Evidence pointers
+- `tsc --noEmit` clean.
+- `vitest run tests/unit/intelligence-router.test.ts` → 11/11 pass (resolution precedence,
+  dispatch, per-framework instance isolation, fallback both modes, live-config hot, for() surface).