instar 1.3.266 → 1.3.268

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.

package/upgrades/side-effects/telegram-reply-robust-content.md

@@ -0,0 +1,31 @@
+# Side-effects review — telegram reply robust content mode
+
+## What changed
+
+`telegram-reply.sh` now accepts `--stdin-base64` / `--base64-stdin`. In that mode, the script decodes the provided base64 payload before building the existing JSON request body. This gives agents a transport-safe path when the reply text itself contains shell metacharacters, quotes, JSON-looking text, or a literal heredoc delimiter line.
+
+The normal heredoc path remains unchanged. The new mode is additive and only activates when the flag is present.
+
+## Why
+
+The standard relay instruction uses a single-quoted heredoc. That protects most shell-sensitive text, but it still fails when the response body contains a line that exactly matches the heredoc delimiter. During Gemini mentoring, Gemi hit this class directly: its heredoc relay attempt ended in a shell syntax error, then it recovered by squeezing the response into a quoted argument. That workaround is fragile for long or structured replies.
+
+Base64 stdin moves the fragile bytes out of shell syntax entirely. The shell only carries base64 characters; the canonical reply script restores the original text before sending.
+
+## Migration footprint
+
+Existing unmodified `telegram-reply.sh` copies are SHA-migrated by `PostUpdateMigrator`. This PR registers the v1.3.266 template SHA as a prior shipped version so deployed agents receive the new script on update. Locally modified scripts are still preserved: the migrator writes a `.new` candidate and reports the existing relay-script-modified-locally degradation instead of overwriting custom content.
+
+Generated identity/scaffold guidance now keeps the familiar heredoc example and adds the base64 fallback for delimiter-sensitive content.
+
+## Risk
+
+Low. The default send path, HTTP route, auth headers, port resolution, tone-gate handling, 408 ambiguous handling, recoverable relay queue, and JSON body shape are unchanged. The new branch only decodes input before the existing JSON builder.
+
+The main operational risk is invalid base64 input; the script exits before contacting the server and prints a clear error.
+
+## Tests
+
+- Unit: `tests/unit/telegram-reply-port-resolution.test.ts` now proves `--stdin-base64` sends shell-sensitive text and a literal `EOF` line as exact message text.
+- Unit: existing `PostUpdateMigrator-telegramReply`, `migration-relay-script-hash`, `IdentityRenderer`, and `telegramRelayPrompt` tests cover migration and generated guidance.
+- Focused run: 58 tests passed across those five files.

package/upgrades/telegram-reply-robust-content.eli16.md

@@ -0,0 +1,11 @@
+# ELI16 — Telegram Reply Robust Content Mode
+
+Agents usually send Telegram replies by pasting the reply into a shell heredoc. That is fine for normal text, but it can break if the reply itself contains the heredoc closing word on its own line.
+
+This change adds a safer backup path. The reply script can now accept base64 text, decode it, and send the original message. That means the shell only sees safe base64 characters, while Telegram receives the real reply text.
+
+Nothing changes for ordinary replies. The normal heredoc command still works, the server route is the same, and the script still builds the same JSON body after it has the final text. The new flag only changes how the text gets into the script.
+
+Existing agents with the standard reply script are upgraded automatically. The migrator recognizes the last shipped script by its hash, backs it up, and installs the new version. If an operator edited the script locally, Instar does not overwrite it. Instead it writes the new version next to it as a review candidate, preserving the local customization.
+
+This matters for agents because reply failures are easy to miss: the user sees silence, while the agent may only see a shell error in its pane. The safer path gives agents a reliable escape hatch for long reports, code examples, JSON snippets, or any text that accidentally contains the heredoc closing line.