instar 1.3.265 → 1.3.267

package/upgrades/1.3.266.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`SessionManager.isMarkerStuckAtPrompt()` now recognizes Gemini CLI's input box. It checked the pane line for `❯` (Claude) or `›` (codex) to find the prompt; Gemini has neither — its active input is a `│ * <text>` box line — so a Telegram message injected into a Gemini session was never detected as stuck, and `verifyInjection`'s Enter-recovery never fired for Gemini. Forwarded prompts stalled unsubmitted in the box (the recurring mentee-layer auto-submit friction; it stalled a message to Codey live this session until manually nudged). The fix adds `│ *` to the prompt-indicator set. The downstream gate is unchanged — a line only counts as stuck if it also contains the exact injected marker, so `│ *` alone (or Gemini's empty-box placeholder) never false-fires, and Claude/codex detection is untouched. Sibling of the earlier codex `›` fix; all three CLIs now get the same stuck-input auto-recovery.
+
+Adds an anti-clobber safety guard to cross-machine secret-sync: outbound push is now opt-in and
+**off by default**.
+
+- `multiMachine.secretSync.enabled` now activates the RECEIVE path only.
+- Outbound push (the boot best-effort push + `POST /secrets/sync-now`) requires
+  `multiMachine.secretSync.pushEnabled: true`, set only on the machine whose secret store is
+  authoritative.
+- A receive-only machine refuses `POST /secrets/sync-now` with `409`; `GET /secrets/sync-status`
+  now reports `pushEnabled` and `mode` (`full` | `receive-only`).
+- Reason (earned live): a machine whose local secret store is stale/divergent — e.g. recovered from
+  a master-key drift — would otherwise auto-push its stale secrets on boot and overwrite peers'
+  good ones. Receive-only-by-default removes that foot-gun and makes "authoritative machine pushes,
+  stale machine only receives" the safe default.
+
+## What to Tell Your User
+
+- Your saved credentials are safer across machines now. When I sync a secret between your machines,
+  only the machine you've designated as the source can send — a machine with an out-of-date copy can
+  receive an update but can never overwrite the good copy on your other machines.
+
+## Summary of New Capabilities
+
+- Receive-only mode for secret-sync (the safe default): a machine can accept synced secrets without
+  ever pushing its own.
+- Per-machine push opt-in via `multiMachine.secretSync.pushEnabled`.
+- `GET /secrets/sync-status` now reports the machine's sync mode.
+
+## Evidence
+
+- `vitest run tests/unit/codex-stranded-draft-recovery.test.ts tests/unit/session-multishot-recovery.test.ts` → **27/27 green** (Gemini box-detect + empty-box placeholder immunity + Claude/codex no-regression + no false-fire on a markerless `│ *` line).
+- `tsc --noEmit` clean.
+- Fixture mirrors a real Gemini idle pane captured live (`│ * [telegram:1] [Long message saved to …]`).
+
+16 tests across all three tiers (8 unit / 5 integration / 3 e2e), including a guard test proving a
+receive-only machine returns 409 on `sync-now` and leaves the peer store untouched. tsc + lint clean.
+Spec: docs/specs/cross-machine-secret-sync-spec.md (Guarantees → "Push is opt-in; receive-only by default").

package/upgrades/1.3.267.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`telegram-reply.sh` now supports `--stdin-base64`, an additive mode for sending replies whose text may contain shell metacharacters or a literal heredoc delimiter line. The script decodes the base64 payload before using the existing JSON request path, so ordinary replies and server behavior are unchanged.
+
+Existing unmodified relay scripts are upgraded through the SHA-based migrator. Customized relay scripts are preserved and receive a `.new` candidate as before.
+
+## What to Tell Your User
+
+Telegram replies are more robust when an agent needs to send text that looks like shell syntax or contains a heredoc-closing line. Normal replies work the same way; the safer mode is only used when needed.
+
+## Summary of New Capabilities
+
+- `telegram-reply.sh --stdin-base64 TOPIC_ID` decodes base64 input and sends the original text.
+- Generated agent instructions mention the safer fallback for delimiter-sensitive content.
+- Post-update migration upgrades the v1.3.266 shipped relay script to the new version without overwriting local customizations.
+
+## Evidence
+
+- Focused unit run passed: `telegram-reply-port-resolution`, `PostUpdateMigrator-telegramReply`, `migration-relay-script-hash`, `IdentityRenderer`, and `telegramRelayPrompt`.
+- The new relay test sends shell-looking content plus a literal `EOF` line through `--stdin-base64` and asserts the server receives the exact original text.

package/upgrades/side-effects/secret-sync-push-guard.md

@@ -0,0 +1,91 @@
+# Side-Effects Review — Secret-Sync push opt-in (receive-only default)
+
+**Version / slug:** `secret-sync-push-guard`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (Tier 2; single-author, safety-tightening change)
+
+## Summary of the change
+
+Adds an anti-clobber safety guard to cross-machine secret-sync (PR #771 / v1.3.258). Previously
+`multiMachine.secretSync.enabled` activated BOTH receive and push, and a boot best-effort
+push fired unconditionally — so a machine whose local secret store is stale/divergent would
+auto-push its stale set to peers and overwrite their good secrets. This change splits push out
+behind `multiMachine.secretSync.pushEnabled` (default **false**): `enabled` alone is now
+RECEIVE-ONLY; outbound (boot push + `POST /secrets/sync-now`) requires `pushEnabled: true`,
+set only on the machine whose store is authoritative. Files: `src/commands/server.ts` (gate +
+handle field + boot-push guard), `src/core/SecretSync.ts` (`SecretSyncHandle.pushEnabled`),
+`src/core/types.ts` (config field), `src/server/routes.ts` (sync-status reports `mode`;
+sync-now 409s when receive-only), `src/scaffold/templates.ts` + `PostUpdateMigrator.ts`
+(agent awareness, incl. a migration for agents that already have the section).
+
+Earned live: 2026-06-04 the mini's store drifted (keychain↔file master-key); enabling the
+original (push-on) secret-sync there would have clobbered the laptop's authoritative secrets.
+
+## Decision-point inventory
+
+- `multiMachine.secretSync.pushEnabled` gate (server.ts) — **add** — splits outbound from inbound.
+- Boot best-effort `provisionAll()` (server.ts) — **modify** — now gated on pushEnabled.
+- `POST /secrets/sync-now` (routes.ts) — **modify** — returns 409 when receive-only.
+- `GET /secrets/sync-status` (routes.ts) — **modify** — now reports `pushEnabled` + `mode`.
+
+## 1. Over-block
+
+The guard "blocks" outbound push when `pushEnabled` is false — that is the intended behavior, not
+over-block. A user who genuinely wants push must set `pushEnabled: true` (one config line). No
+legitimate RECEIVE is blocked. The 409 response names the exact remedy.
+
+## 2. Under-block
+
+The guard does not validate that the push-enabled machine's store is ACTUALLY authoritative — it
+trusts the operator's `pushEnabled: true`. A misconfiguration (pushEnabled on a stale machine)
+could still clobber. Mitigated by: default-off (you must deliberately opt in) + the doc guidance
+("set only on the machine whose store is authoritative"). A value-hash reconciliation (only push
+keys the peer is missing/older) is a sound follow-up but out of scope here.
+
+## 3. Level-of-abstraction fit
+
+Right layer: a config flag + a wiring gate, consistent with the rest of secret-sync. It reuses the
+existing provisioner/handle; no new primitive. The default-off posture matches the project's
+"dark by default" rollout discipline for risky features.
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change has no block/allow surface over user messages. (It gates an internal
+  outbound sync action behind an explicit config flag — deterministic, not a heuristic gate.)
+
+## 5. Interactions
+
+- **Shadowing:** none — `pushEnabled` only narrows when the existing push path runs.
+- **Double-fire:** reduces it — the boot push no longer fires on receive-only machines.
+- **Races:** unchanged — same SecretStore read-modify-write as before; receive path untouched.
+- **Feedback loops:** none. A receive-only machine that gets corrected by an authoritative push
+  does NOT re-push (it can't), so no ping-pong.
+
+## 6. External surfaces
+
+- **Peers:** strictly safer — a receive-only machine no longer sends to peers at all.
+- **Config:** new optional field `multiMachine.secretSync.pushEnabled` (absent ⇒ false ⇒ no push).
+  No migrateConfig default needed (absence = safe default).
+- **API:** `/secrets/sync-status` gains `pushEnabled` + `mode` fields (additive); `/secrets/sync-now`
+  can now return 409 (receive-only) in addition to its prior 200/503/500.
+- **Persistent state:** none changed.
+
+## 7. Rollback cost
+
+Pure code change. Revert = secret-sync returns to push-on-enable (the less-safe prior behavior).
+No persistent state to unwind. Because push was never enabled on any real machine between #771 and
+this change (the mini incident is exactly why), there is no in-the-wild push to reconcile.
+
+## Conclusion
+
+A small, safety-tightening change with a default-off posture; it closes the divergent-store clobber
+risk that the 2026-06-04 mini incident exposed and makes laptop→mini the safe reconciliation
+direction for the live verification. The one residual (operator opts pushEnabled on a non-authoritative
+machine) is documented and a value-hash reconciliation is the natural follow-up. Clear to ship.
+
+## Evidence pointers
+
+16 tests green: 8 unit, 5 integration (incl. the new receive-only guard test: sync-now 409s + peer
+vault untouched), 3 e2e. tsc + lint clean. Spec updated (Guarantees → "Push is opt-in"). Related: the
+SecretStore keychain-drift repair that surfaced this (re-key file→keychain).

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.

package/upgrades/1.3.265.md

@@ -1,22 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-`SessionManager.isMarkerStuckAtPrompt()` now recognizes Gemini CLI's input box. It checked the pane line for `❯` (Claude) or `›` (codex) to find the prompt; Gemini has neither — its active input is a `│ * <text>` box line — so a Telegram message injected into a Gemini session was never detected as stuck, and `verifyInjection`'s Enter-recovery never fired for Gemini. Forwarded prompts stalled unsubmitted in the box (the recurring mentee-layer auto-submit friction; it stalled a message to Codey live this session until manually nudged). The fix adds `│ *` to the prompt-indicator set. The downstream gate is unchanged — a line only counts as stuck if it also contains the exact injected marker, so `│ *` alone (or Gemini's empty-box placeholder) never false-fires, and Claude/codex detection is untouched. Sibling of the earlier codex `›` fix; all three CLIs now get the same stuck-input auto-recovery.
-
-## What to Tell Your User
-
-None — internal change (no user-facing surface).
-
-## Summary of New Capabilities
-
-None — internal change (no user-facing surface).
-
-## Evidence
-
-- `vitest run tests/unit/codex-stranded-draft-recovery.test.ts tests/unit/session-multishot-recovery.test.ts` → **27/27 green** (Gemini box-detect + empty-box placeholder immunity + Claude/codex no-regression + no false-fire on a markerless `│ *` line).
-- `tsc --noEmit` clean.
-- Fixture mirrors a real Gemini idle pane captured live (`│ * [telegram:1] [Long message saved to …]`).