instar 1.3.267 → 1.3.269

package/upgrades/1.3.268.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Gemini CLI can still stop on framework-level interactive modals even when an
+autonomous session is otherwise running in YOLO mode. Instar already detected
+and relayed those prompts to Telegram, but the Gemini process remained blocked
+until somebody pressed a key in the tmux pane.
+
+Prompt Gate now recognizes Gemini CLI's known safe-default modals before the
+generic relay/classifier path:
+
+- loop-detection prompt: keep loop detection enabled;
+- workspace-trust prompt: trust the workspace;
+- install-confirm prompt: accept Gemini CLI's highlighted/default path.
+
+The existing Prompt Gate auto-response hook sends the deterministic key directly
+to the session and clears detector state, so autonomous Gemini sessions do not
+freeze on these modals and the prompt does not spam Telegram.
+
+Tests cover the loop-detection modal with explicit options and the live no-option
+shape, workspace trust, install confirm, and a generic non-Gemini install prompt
+that must not receive an auto-answer.
+
+## What to Tell Your User
+
+Gemini should stop freezing on its own safety/setup modals during autonomous
+work. I now answer the known Gemini defaults directly, while generic install or
+human-judgment questions still go through the normal review path.
+
+## Summary of New Capabilities
+
+- Gemini loop-detection modal is answered by keeping loop detection enabled.
+- Gemini workspace-trust modal is answered by trusting the current workspace.
+- Gemini install-confirm modal uses Gemini CLI's highlighted/default answer.
+
+## Evidence
+
+Reproduced from the live apprenticeship report: Gemini CLI stopped at the modal
+"A potential loop was detected" and stayed blocked until Justin manually pressed
+Enter. The Prompt Gate path was confirmed in source: detected prompts with
+`autoDismissKey` are answered through `SessionManager.sendKey` before Telegram
+relay/classification.
+
+Before: Gemini modals could be relayed to Telegram while the tmux session stayed
+frozen at the modal. After: the known Gemini modal fixtures emit deterministic
+keys in `PromptGate`, so the existing session-send hook answers the modal and
+clears detector state.
+
+Verification: focused Prompt Gate/classifier/approver unit tests passed, lint
+passed, the stall-recovery integration suite passed, and Gemini loop/capacity
+e2e lifecycle suites passed.

package/upgrades/1.3.269.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Dashboard link refresh failures now report actionable diagnostics instead of opaque command failures. The built-in refresh job gate and refresh command use Node's native request support, so they no longer depend on a shell HTTP client being installed. The dashboard-refresh route now reports which layer failed: missing Telegram setup, missing tunnel state, tunnel without a URL, local request failure, or Telegram broadcast failure.
+
+The Telegram dashboard broadcast path also stops hiding hard send/edit failures from the scheduled refresh route. Best-effort pinning remains best effort, but failure to deliver the Dashboard message is now visible to the job.
+
+## What to Tell Your User
+
+Dashboard link refresh failures should now explain what broke and what to check next, instead of showing a vague job failure.
+
+## Summary of New Capabilities
+
+- The dashboard link refresh job gate and refresh command no longer depend on a shell HTTP client being installed.
+- Dashboard refresh failures include the failed layer, detail, and next step.
+- Telegram dashboard message delivery failures are surfaced to the refresh job instead of being hidden as success.
+
+## Evidence
+
+Focused diagnostics coverage passed with `tests/unit/dashboard-refresh-diagnostics.test.ts`, and the full TypeScript/lint gate passed.

package/upgrades/side-effects/dashboard-refresh-diagnostics.md

@@ -0,0 +1,76 @@
+# Side-Effects Review - Dashboard refresh diagnostics
+
+**Version / slug:** `dashboard-refresh-diagnostics`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not run - subagent delegation unavailable without explicit user request in this session`
+
+## Summary of the change
+
+This change improves diagnostics for the built-in `dashboard-link-refresh` job and the `/telegram/dashboard-refresh` route. It adds `src/server/DashboardRefreshDiagnostics.ts`, switches the default job gate and command in `src/commands/init.ts` from curl-only shell commands to Node/fetch diagnostic scripts, makes `src/server/routes.ts` return structured failure bodies with stage/detail/nextStep, and makes `src/messaging/TelegramAdapter.ts` throw on hard dashboard broadcast failures instead of swallowing them. Focused coverage lives in `tests/unit/dashboard-refresh-diagnostics.test.ts`.
+
+## Decision-point inventory
+
+- `src/server/routes.ts` `/telegram/dashboard-refresh` - modified - maps missing Telegram/tunnel state and broadcast failures into explicit HTTP failure responses.
+- `src/messaging/TelegramAdapter.ts` `broadcastDashboardUrl` - modified - treats failure to edit/send the Dashboard message as a hard delivery failure; pinning remains best-effort.
+- `src/commands/init.ts` `dashboard-link-refresh` default job gate and command - modified - chooses diagnostic scripts installed or repaired for built-in legacy jobs.
+- `src/server/DashboardRefreshDiagnostics.ts` generated refresh command - modified - reads the injected auth token from the job environment first and only uses a string-valued config token as fallback.
+
+## 1. Over-block
+
+The route now returns failure for a hard Telegram dashboard broadcast failure where the previous adapter could log the error and return normally. A legitimate refresh call can therefore fail if Telegram send/edit is unavailable. That is intentional because the job's purpose is delivery of a dashboard link; a false success here is the opaque failure mode being fixed.
+
+Named tunnels still skip refresh as before. Agents without Telegram or without a tunnel still receive skipped precondition responses instead of a successful refresh.
+
+## 2. Under-block
+
+This does not verify that the pinned Telegram message is visible to every user, nor does it validate that the remote tunnel URL actually serves the dashboard after the Telegram message is sent. The route checks local state and Telegram delivery, not end-to-end browser reachability.
+
+The diagnostic script reports the response body and common request failures, but it cannot diagnose every OS/network layer beyond the thrown request error. It gives the next local step rather than attempting repair.
+
+## 3. Level-of-abstraction fit
+
+The change sits at the right layers: the job script diagnoses local execution and HTTP request failures; the route diagnoses server-side preconditions; the Telegram adapter reports hard delivery failure. It does not add a parallel health checker or a new scheduler policy. It uses the existing built-in job repair path in `refreshJobs`, which syncs built-in gate/execute fields while preserving user-tunable schedule/enabled/priority settings.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No - this change is structural precondition/request validation, not a brittle judgment gate.
+
+The route and script have blocking authority only over malformed or failed infrastructure operations: no Telegram adapter, no tunnel URL, failed HTTP request, or failed Telegram delivery. These are mechanical facts, not semantic judgments about user intent or message meaning. The change does not add a detector that blocks conversational content.
+
+## 5. Interactions
+
+- **Shadowing:** The route's precondition checks now return structured bodies, but the same preconditions already caused non-success responses. No higher-level authority is bypassed.
+- **Double-fire:** Startup tunnel rebroadcast callers already catch dashboard broadcast failures where they want best-effort behavior. The scheduled refresh route awaits the same adapter method and now receives the hard failure.
+- **Races:** The tunnel URL can disappear between reading `ctx.tunnel.url` and broadcasting; that remains a runtime race. The failure now reports the stage if delivery fails rather than pretending the job succeeded.
+- **Feedback loops:** The built-in legacy job refresh path may update existing built-in `dashboard-link-refresh` execute content on update, which is intended for built-in job implementation details. User-forked job files are not touched by this path.
+
+## 6. External surfaces
+
+The visible external surface is improved job output and HTTP error JSON for `/telegram/dashboard-refresh`. The Telegram user-facing Dashboard message content is unchanged. The change affects existing agents when the built-in job definition is refreshed, because the built-in `execute.value` is treated as implementation-owned. It does not write persistent state beyond the existing dashboard message ID path when a new Telegram message is successfully sent.
+
+The gate and script no longer depend on a shell HTTP client being installed, which improves portability for Gemini/Codex-style environments where the shell path may not include curl.
+
+The refresh command now preserves compatibility with externalized auth tokens. Job sessions receive the resolved token in their environment, and the config-file fallback rejects non-string placeholder objects instead of sending them as bearer tokens.
+
+## 7. Rollback cost
+
+Rollback is a patch revert of the helper, route, adapter, default job command, test, ELI16, release note, and this artifact. No data migration is introduced. Existing agents that already received the improved built-in job command would receive the reverted command on a later update through the same built-in job repair path.
+
+## Conclusion
+
+The review did not identify a signal-vs-authority violation. The main behavior change is that a dashboard refresh can now fail loudly when Telegram delivery fails; that is the intended correction because silent success was the operationally harmful path. The change is clear to ship with the focused test and lint coverage.
+
+## Second-pass review
+
+**Reviewer:** `instar-codey separate pass`
+**Independent read of the artifact: concur with constraint**
+
+The high-risk checklist would normally call for a delegated reviewer because this touches Telegram delivery. The available subagent tool is policy-limited to explicit user requests for delegation, so no subagent was spawned. A separate read of the code and artifact found the design acceptable: hard delivery failures now surface only for the dashboard refresh operation, while best-effort pinning remains non-fatal and startup callers already catch broadcast errors.
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/dashboard-refresh-diagnostics.test.ts` passed.
+- `npm run lint` passed.

package/upgrades/side-effects/gemini-interactive-modal-autofill.md

@@ -0,0 +1,85 @@
+# Side-effects review — Gemini interactive modal autofill
+
+## What changed
+
+`PromptGate` now has a structural matcher for known Gemini CLI framework modals
+that block autonomous sessions:
+
+- loop detection: sends the explicit "keep loop detection enabled" option when
+  visible, otherwise sends `Enter` for the live default path Justin observed;
+- workspace trust: sends the explicit trust/yes/allow option when visible,
+  otherwise sends `Enter`;
+- install confirmation: sends `Enter` to accept Gemini CLI's highlighted/default
+  response.
+
+These matches run before the generic question, selection, and LLM prompt
+detection paths. The existing server wiring already consumes `autoDismissKey` by
+sending that key to the tmux session and skipping the relay/classifier pipeline.
+
+## Why
+
+The failure mode is a real autonomy wedge. Instar detected the Gemini modal and
+forwarded it to Telegram, but the Gemini CLI process stayed blocked waiting for
+keypress input in the pane. YOLO mode does not suppress these Gemini CLI modals.
+
+Loop detection is a safety rail, so the auto-answer keeps it enabled. Workspace
+trust is part of normal agent operation in the bound project. Install-confirm is
+handled as Gemini CLI's own highlighted/default decision, not as a broad "yes to
+any install" rule.
+
+## Risk
+
+Blast radius is limited to prompt detection. There is no schema, database,
+configuration, route, migration, Telegram adapter, or session-spawn change.
+
+The main risk is false positive auto-answering. The patterns are constrained to
+Gemini-specific modal text or Gemini/MCP/tool install context, and the generic
+non-Gemini install fixture proves a plain install question does not receive an
+auto-answer. Existing broad prompt patterns still handle unrelated questions and
+confirmations the same way they did before.
+
+The second risk is semantic drift if Gemini CLI changes its wording. The loop
+modal uses the live phrase Justin observed ("A potential loop was detected") and
+falls back to `Enter` when no numbered row is visible. Workspace and install
+patterns also accept option rows where Gemini renders numeric choices.
+
+## Framework generality
+
+Claude Code and Codex CLI behavior is unchanged. Their existing Prompt Gate
+patterns still run after this new Gemini-specific matcher, and the new matcher
+requires Gemini-specific loop/trust/install context before it emits an
+`autoDismissKey`.
+
+This fix is explicitly for `gemini-cli`, and it reaches Gemini sessions through
+the same provider-neutral `PromptGate` and `SessionManager.sendKey` abstraction
+already used by Claude optional-survey dismissal and manual Telegram prompt
+responses.
+
+## Tests
+
+- Unit: `tests/unit/PromptGate.test.ts` covers Gemini loop detection with
+  numbered options, the live no-option loop modal shape, workspace trust,
+  install confirmation, and a generic non-Gemini install question that must not
+  auto-answer.
+- Unit: existing `InputClassifier` and `AutoApprover` tests stay green, proving
+  the normal classification and approval layers were not widened.
+- Focused run: `npm test -- --run tests/unit/PromptGate.test.ts tests/unit/InputClassifier.test.ts tests/unit/AutoApprover.test.ts`
+  passed with 95 tests.
+- Integration: `npm test -- --run tests/integration/stall-recovery-e2e.test.ts`
+  passed with 12 tests.
+- E2E: `npm test -- --run tests/e2e/gemini-loop-driver-lifecycle.test.ts tests/e2e/gemini-capacity-policy-lifecycle.test.ts`
+  passed with 4 tests.
+- Type/lint: `npm run lint` passed.
+
+An attempted broader session-management e2e smoke was not used as acceptance
+evidence: `tests/e2e/session-management-e2e.test.ts` hit the existing respawn
+fixture timing/session-loss path (`waitFor timed out after 15000ms`) while 30/31
+tests passed under a longer timeout. That file does not exercise this PromptGate
+matcher and the failure was in tmux respawn injection, not modal detection.
+
+## Rollback
+
+Revert the PromptGate matcher and tests. No persisted state or migration is
+introduced. Rollback restores the previous behavior where Gemini CLI modals are
+detected/relayed but may remain blocked until a human presses the key in the
+terminal.