instar 1.3.236 → 1.3.238

package/upgrades/1.3.238.md

@@ -0,0 +1,68 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Wires the Gemini multi-turn loop-driver engine (`need-gem-002`, increment 1,
+already merged) into a real, budget-gated, **dark** capability — so the Gemini
+mentee can be handed a goal it works across turns instead of one reply.
+
+- `geminiLoopProduction.ts` — the production dependencies: a subscription-auth
+  spawn (routes through the billing-env-stripping gemini transport, so no run can
+  introduce an API key), a `gemini --list-sessions` handle parser that picks the
+  freshest session by age, and a budget gate that reuses the existing QuotaTracker
+  spawn-admission signal (fails open if no tracker).
+- `GeminiLoopRunner` — a multi-turn run can take minutes, so `POST` ADMITS a run
+  (enabled? under the concurrency cap? budget open?) and returns a `runId`
+  immediately; the loop runs in the background and the result lands in a bounded
+  in-memory registry.
+- Routes `POST /gemini-loop/runs` + `GET /gemini-loop/runs[/:id]`.
+- Config `autonomousSessions.geminiLoopDriver` (`enabled`, `model`, `maxTurns`
+  default 12, `minTurnIntervalMs`, `maxConcurrent` default 1, `turnTimeoutMs`).
+
+Ships **dark** behind `autonomousSessions.geminiLoopDriver.enabled` (default
+`false`); the `developmentAgent` gate turns it on for development agents only.
+Rollback = set the flag `false` (instant, no redeploy). Subscription auth is
+structural. 21 new tests across all three tiers (unit + integration route + e2e
+alive + wired-source check). Spec: `docs/specs/gemini-multi-turn-loop-driver.md`.
+
+**The Parallel-Work overlap councilor can now actually run.** The previous change shipped the
+detector and the sentinel as tested library code; this wires the `ParallelWorkSentinel` into
+the server so it ticks on a cadence over the cross-topic activity index, spots when two of
+your topics are working on the same thing, and nudges you once — with a cooldown so it never
+re-nags. It is signal-only and never gates.
+
+It ships **dark**: off by default behind `monitoring.parallelWorkSentinel.enabled`. A
+false-positive nudge is worse than silence, so it graduates only after it is shown to be
+quiet. When on, it scans every ~15 minutes, audits every transition to
+`logs/sentinel-events.jsonl`, and the timer is unref'd + cleaned up on shutdown.
+
+## What to Tell Your User
+
+On development agents I can now be handed a multi-step task for the Gemini side
+and work it across several turns on my own — on subscription login, never an API
+key — with a hard turn cap and a spend gate so it can't run away. On every other
+agent it ships turned off, so nothing changes there. This is the capability the
+apprenticeship program needed so the Gemini mentee can do real multi-step work
+instead of stopping after one reply.
+
+Optional: if your agent works across many topics and you want it to proactively notice when
+two topics are doing the same work, you can turn on the overlap councilor in your monitoring
+config. It is off by default and only ever sends a gentle heads-up -- it never blocks anything.
+
+## Summary of New Capabilities
+
+- `monitoring.parallelWorkSentinel.enabled` (default false, ships dark) +
+  `cadenceMinutes` (default 15) — turns on and tunes the proactive overlap councilor.
+- The `ParallelWorkSentinel` is now constructed + cadenced in the server when enabled, with
+  every transition audited to `logs/sentinel-events.jsonl`.
+
+## Evidence
+
+- Wiring-integrity test (Testing Integrity Standard): boots the real AgentServer and asserts
+  the sentinel is NOT constructed when the flag is off (ships dark) and IS constructed +
+  ticks when the flag is on. tsc clean.
+- The detector + sentinel logic is already covered by 17 unit tests (shipped with the
+  prior change); this change only turns them on.

package/upgrades/side-effects/gemini-loop-driver-wiring.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Gemini loop-driver wiring (need-gem-002, increment 2)
+
+**Version / slug:** `gemini-loop-driver-wiring`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (ships DARK behind
+`autonomousSessions.geminiLoopDriver.enabled`; the developmentAgent gate turns it
+on for dev agents only; rollback = flag false, instant)
+
+## Summary of the change
+
+Wires the (already-merged, increment 1) `GeminiLoopDriver` engine into a real,
+budget-gated, dark capability:
+- `geminiLoopProduction.ts` — production deps: the subscription-auth spawn
+  (`createGeminiLoopSpawn` → the billing-env-stripping transport), the
+  `--list-sessions` handle parser (`parseLatestGeminiSessionHandle`, min-age), and
+  the QuotaTracker-backed budget gate (`createQuotaBudgetGate`).
+- `GeminiLoopRunner.ts` — admits + launches runs async (a loop can take minutes,
+  so a run returns a `runId` immediately) into a bounded in-memory registry.
+- Routes `POST /gemini-loop/runs` (admit) + `GET /gemini-loop/runs[/:id]` (poll).
+- `server.ts` constructs it under the developmentAgent gate; `types.ts` adds
+  `autonomousSessions.geminiLoopDriver`.
+
+## Decision-point inventory
+
+Admission has four refusal boundaries (disabled / at-capacity / budget / invalid)
+plus the OK path; the handle parser picks min-age or null; the budget gate maps
+the QuotaTracker signal (fail-open with no tracker). All covered both-sides
+across the unit/integration suites.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** Nothing on the fleet — it
+ships dark (disabled → POST returns 409 'disabled'). When enabled: a closed budget
+gate refuses to start (intended — the overspend guard), `maxConcurrent: 1` refuses
+a 2nd concurrent run (intended — keeps shared-cwd handle capture unambiguous), and
+an empty goal is 400. A requested `maxTurns` is clamped DOWN to the config cap, never
+up. These are all the guardrails, not false rejections.
+
+## 2. Under-block
+
+**What does this still miss?** Handle capture uses the shared process cwd, so it is
+only unambiguous at `maxConcurrent: 1` (a per-loop cwd needs a transport `cwd`
+option — deferred; documented in the spec risks). The runner does not persist runs
+across a restart (in-memory registry — acceptable for a dev dark feature; a SQLite
+store is a later increment if it graduates). A 429/capacity wall ends a turn via
+the engine's spawn-failure path rather than a graceful gemini-capacity-policy
+pause (noted as a refinement). A mentee that finishes silently (no sentinel) runs
+to the turn cap rather than an LLM-judge early-exit (judge = a later increment).
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. Production deps live in `monitoring/` beside the engine and
+depend only on the gemini transport (subscription-auth guarantee stays in the
+transport, reused not re-implemented). The runner is constructed beside the other
+dark monitoring features in `server.ts` under the same `developmentAgent` gate
+pattern, and threads through the existing `AgentServer` options → `RouteContext`
+plumbing (mirrors `mcpProcessReaper`). The budget gate reuses the existing
+QuotaTracker spawn-admission decision rather than inventing new accounting.

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,94 @@
+# 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.
+
+## Phase B wiring (the on-switch)
+- `src/config/ConfigDefaults.ts` — `monitoring.parallelWorkSentinel: { enabled: false }` — ships
+  DARK (false-positive nudge worse than silence; graduate after proven quiet). Add-missing-only
+  via applyDefaults ⇒ free migration; never a destructive sub-flag default.
+- `src/core/types.ts` — `MonitoringConfig.parallelWorkSentinel?: { enabled, cadenceMinutes? }`.
+- `src/server/AgentServer.ts` — when enabled, construct `ParallelWorkSentinel` over the index in
+  its OWN try/catch (cascade isolation), tick on an unref'd cadence (default 15min), audit each
+  transition to `logs/sentinel-events.jsonl`; cleared on `stop()`. Signal-only.
+
+## 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 ⇒ []).