instar 1.3.291 → 1.3.293

package/upgrades/side-effects/dashboard-headless-gemini-framework.md

@@ -0,0 +1,90 @@
+# Side-Effects Review — dashboard headless Gemini framework parity
+
+**Version / slug:** `dashboard-headless-gemini-framework`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `self-review required by session-spawn lifecycle surface; concur`
+
+## Summary of the change
+
+The dashboard headless session-spawn route had a stale framework allowlist that accepted Claude and Codex but rejected Gemini before `SessionManager.spawnSession` could handle the request. This change updates that route-level validation to accept the same three shipped frameworks (`claude-code`, `codex-cli`, `gemini-cli`) and makes route model validation framework-aware for Gemini by accepting the known Gemini CLI model ids exported by the Gemini adapter. Regression tests cover successful Gemini pass-through, invalid-framework error text, and Gemini model acceptance.
+
+## Decision-point inventory
+
+- `POST /sessions/spawn` framework validation — **modify** — widens the accepted framework values to include Gemini, matching the already-supported headless launcher surface.
+- `POST /sessions/spawn` model validation — **modify** — routes Gemini requests to Gemini's known-model list instead of falling through to Claude model names.
+- Session launching authority — **pass-through** — unchanged; `SessionManager` and `buildHeadlessLaunch` still own actual launch behavior.
+
+---
+
+## 1. Over-block
+
+No new over-block identified. The only rejection behavior changed is that previously-rejected Gemini requests now pass route validation. Claude and Codex allowed model sets are unchanged. Invalid framework values are still rejected, but the error message now includes Gemini in the valid set.
+
+---
+
+## 2. Under-block
+
+The route still rejects unknown raw Gemini model ids because it only accepts generic tiers and the adapter's current known Gemini model list. That is intentional for this route-level validator: arbitrary model-id passthrough belongs either in the Gemini adapter policy or in an explicit model-discovery change, not in a dashboard route hotfix. A Gemini request with no model remains allowed and continues to use downstream defaulting.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This fix is at the correct layer because the bug was route-local validation rejecting a value that the lower-level session launcher already supports. The route should validate the request envelope and then pass supported framework values through; it should not invent a narrower framework universe than `SessionManager`. Reusing `KNOWN_GEMINI_MODELS` avoids duplicating Gemini model names in a second place.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [x] Yes — but this is deterministic schema validation at an HTTP boundary, not a brittle detector making contextual behavioral decisions.
+- [ ] Yes, with brittle logic — STOP. Reshape the design.
+
+The route has blocking authority over malformed requests, but the logic is a deterministic allowlist of shipped framework identifiers and shipped adapter model ids. It does not interpret conversation content, infer intent, or suppress agent behavior. The authority is appropriate for request schema validation.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** this route validation runs before `SessionManager.spawnSession`. The old version shadowed Gemini's existing launcher support by rejecting the request too early; the new version removes that shadow for Gemini.
+- **Double-fire:** no double action. Successful requests still call exactly one session-manager spawn path.
+- **Races:** no shared mutable state added. The Gemini model list is a static exported constant.
+- **Feedback loops:** none. The change does not alter dashboard refresh, prompt gates, degradation reporters, or launcher retry behavior.
+
+---
+
+## 6. External surfaces
+
+Visible external surface: dashboard/headless API callers can now create Gemini sessions through the existing spawn route. Invalid-framework error text changes to include Gemini as a valid value. No persistent state format, config, migration, Telegram behavior, Cloudflare tunnel behavior, or session cleanup policy changes.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a pure code revert and patch release. No data migration or agent state repair is required. During rollback, dashboard Gemini headless spawns would return to the known-broken route rejection while lower-level Gemini session support would remain intact.
+
+---
+
+## Conclusion
+
+This is a narrow route-parity fix: the dashboard route now accepts the Gemini framework and known Gemini models already supported by the headless launcher. The main risk was accidentally widening model validation too far or changing Claude/Codex validation; tests bind both the successful Gemini path and invalid-framework behavior, and the implementation keeps Claude/Codex allowlists unchanged.
+
+---
+
+## Second-pass review
+
+**Reviewer:** instar-codey self-review
+**Independent read of the artifact:** concur
+
+The lifecycle surface is a session-spawn route, so I re-read the change as a reviewer after writing the artifact. The fix removes a route-local false rejection and does not add a new launcher path, lifecycle transition, or cleanup behavior. The scoped tests cover the route boundary where the regression lived.
+
+---
+
+## Evidence pointers
+
+- Focused unit gate: `npx vitest run tests/unit/server.test.ts tests/unit/route-validation-edge.test.ts` — 46 tests passed.
+- Original observed failure from verification: dashboard/headless spawn rejected Gemini with `"framework" must be one of: claude-code, codex-cli`.

package/upgrades/side-effects/job-mcp-access.md

@@ -0,0 +1,51 @@
+# Side-Effects Review — per-job MCP access scoping (`mcpAccess`)
+
+**Version / slug:** `job-mcp-access`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; the capability-loss question (does any job need MCP?) is addressed explicitly below`
+
+## Summary of the change
+
+`JobDefinition.mcpAccess?: 'project' | 'none'`. When `'none'`, `spawnJobSession` passes the EXISTING `disableProjectMcp` option to `spawnSession` (shipped + verified by the mentor autonomous-fix loop, docs/specs/LOOP-SESSION-NO-MCP-SPEC.md), which emits `--strict-mcp-config --mcp-config '{"mcpServers":{}}'` on claude-code spawns and nothing on other frameworks. The field flows frontmatter → InstallBuiltinJobs → per-slug manifest → validateManifest → manifestToJobDefinition. 14 shipped utility templates declare `mcpAccess: none`.
+
+## Decision-point inventory
+
+- `types.ts JobDefinition.mcpAccess` — add — optional, absent = legacy.
+- `AgentMdJobLoader.ALLOWED_FRONTMATTER_KEYS` — modified — `mcpAccess` joins the closed-set whitelist (deliberate, per the set's own doc).
+- `PerSlugManifest.mcpAccess` + `validateManifest` — add — closed two-value enum, loud throw otherwise.
+- `buildPerSlugManifest` — modified — carries the field; omits the key when undefined.
+- `InstallBuiltinJobs` — modified — derives from frontmatter; out-of-set values → undefined (fail-safe to legacy), then validateManifest re-checks the generated manifest.
+- `JobScheduler.spawnJobSession` — modified — `disableProjectMcp: job.mcpAccess === 'none' ? true : undefined`.
+- 14 templates — modified — `mcpAccess: none` added to frontmatter.
+
+## 1. Direction-of-failure analysis (capability loss)
+
+The risk: a job whose body NEEDS an MCP tool gets spawned without MCP and fails mid-run.
+
+- **Grounding:** zero shipped templates reference `mcp__*`, `threadline_*`, playwright, browser, or chrome (grep across `src/scaffold/templates/jobs/instar/*.md`). The marked 14 are bash/curl-only by construction.
+- **Deliberately unmarked:** the orchestration family (`mentor-onboarding`, all `overseer-*`, `evolution-proposal-implement`) keeps project MCP — they drive sessions/build code and are the apprenticeship machinery; this slice does not touch their spawn behavior.
+- **Custom/user jobs:** never affected — the field is opt-in and absent on every existing user job.
+- **Worst NEW case:** a future template author marks a job `none` then writes a body that wants MCP — the session still runs (built-in tools work; MCP tools are simply absent), the job degrades visibly in its own output rather than hanging. That is strictly better than the current failure direction (auth-required remote MCP can hang the headless boot silently).
+
+## 2. Over-permit
+
+None — the change only ever REMOVES servers from a spawn, never adds; and only for jobs that explicitly opt in.
+
+## 3. Scope deliberately NOT taken
+
+- No default flip: absent stays legacy full-MCP. A future slice may flip instar-origin jobs by default after this one soaks.
+- Topic/chat sessions untouched (capability matters there; the standing-cost problem for those is the idle-reap path, fixed separately by the meaningful-tail work).
+- No per-job CUSTOM MCP subset (`--mcp-config` with a real server list) — only the binary none/project. Subset selection is a follow-up if a real job needs it.
+
+## 4. Migration parity
+
+Built-in templates are re-installed by `installBuiltinJobs()` on every update via `refreshHooksAndSettings()`, and the per-slug manifests are REGENERATED from the templates — existing agents pick up the 14 `mcpAccess: none` declarations on their next update without a dedicated migration. Operator-disabled jobs keep their disabled state (existing `existingEnabled` preservation). No config/hook/skill/CLAUDE.md surface changes.
+
+## 5. Token/cost impact
+
+Strictly negative (saves): every marked job spawn skips MCP server boot (playwright-mcp alone ≈125MB + node startup per spawn; health-check spawns 288×/day). No new LLM calls.
+
+## 6. Rollback
+
+Revert the commit. Manifests regenerate without the field on the next install pass; spawns return to full-project-MCP.