instar 1.3.279 → 1.3.281

package/upgrades/{1.3.279.md → 1.3.280.md}

@@ -5,6 +5,24 @@
 
 ## What Changed
 
+Prompt Gate now recognizes the exact Gemini CLI package-runner install prompt
+that blocked the live mentorship cycle: an `instar` package version followed by
+`Ok to proceed? (y)`. That narrow prompt is answered with the highlighted
+default, so the agent can continue through its own Instar CLI command without a
+manual Enter press. Arbitrary package installs are not auto-answered.
+
+Prompt Gate also recognizes Gemini CLI execution-approval modals, but with the
+opposite policy. Execution approvals ask whether model-proposed command text may
+run. This change adds no approval path. When the known modal shape includes the
+reject option, Prompt Gate chooses that reject option and records the rejected
+command text in the server log plus an observable Prompt Gate event.
+
+Fixed an invisible-verdict bug in the pre-send message-quality gate. When the gate
+blocked an outbound message, it wrote its reasons to the wrong output channel, so
+the agent saw a generic "hook error" instead of the actual findings — and would
+retry blind. The reasons now land on the channel the runtime actually shows, so a
+blocked message comes back with the specific quality findings to fix.
+
 Added a Mandates tab to the dashboard — the operator's surface for the coordination
 permission slips. It lists every issued mandate with live authorship verification and
 state, provides PIN-gated forms to issue a new mandate or revoke an existing one, and
@@ -24,6 +42,16 @@ written to the server log, even if the caller's connection already timed out.
 
 ## What to Tell Your User
 
+Gemini can now get past the specific Instar package install prompt that was
+blocking mentor cycles. If Gemini asks to run an arbitrary command, Instar will
+not approve it automatically. It rejects the known approval prompt and leaves a
+visible record of the command it refused, so the mentor can see why the task
+changed course.
+
+Your agent's pre-send quality check now explains itself. If it holds a message
+back, the agent sees exactly why and revises, instead of appearing to hit a
+mysterious error.
+
 Your dashboard now has a Mandates tab where you manage the permission slips for
 autonomous agent-to-agent work: see every slip and whether its authorship still
 verifies, issue a new one with your PIN, tear one up with your PIN, and read the
@@ -36,6 +64,16 @@ results always show up in the logs.
 
 ## Summary of New Capabilities
 
+- Auto-answer the narrow Gemini package-runner install confirmation for Instar
+  package versions.
+- Auto-reject Gemini execution-approval modals with an explicit reject option.
+- Record execution auto-rejects visibly so mentor diagnosis does not depend on
+  guessing from a stalled terminal.
+
+- Blocked outbound messages surface their quality findings to the agent instead
+  of an opaque hook error.
+- Maturity: stable; the gate's judgments are unchanged — only their visibility.
+
 - See all coordination mandates with live authorship-verification badges and
   active/revoked/expired state at a glance.
 - Issue a mandate from a form (pre-filled with the standard two-authority shape) —
@@ -51,3 +89,14 @@ results always show up in the logs.
 - Comparison outcomes are always logged server-side, even when the requester's
   connection timed out first.
 - Maturity: stable; no other route's timing changes.
+
+## Evidence
+
+Not reproducible in a live dev shell without driving Gemini into the exact
+interactive modal, but covered by deterministic unit fixtures from the captured
+terminal shapes:
+
+- package-runner install prompt for `instar@1.3.270` auto-dismisses with Enter;
+- arbitrary package-runner install prompt does not auto-dismiss;
+- execution-approval modal with highlighted Allow once still auto-rejects;
+- rejected execution command text is carried in the detected prompt metadata.

package/upgrades/1.3.281.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`Config.loadConfig` (loud merge failure + critical-placeholder boot guard `assertNoCriticalSecretPlaceholders`), `GlobalSecretStore.initWithKeychain` (generation guard, injectable exec), `SecretManager` (reported degradations), `SecretMigrator` (drops `forceFileKey`). Complements #810 (vault-key-coherence — per-agent keychain slots, keyId header, dual-key reads), which owns the SecretStore layer. Spec: `docs/specs/keychain-per-agent-master-key.md`.
+
+## What to Tell Your User
+
+Nothing user-visible in normal operation. The remaining layers of the 2026-06-05 secrets incident are closed: an undecryptable secret store now stops the boot immediately with a precise, actionable error (instead of a confusing crash-loop minutes later), and the shared secret vault can no longer orphan existing data by generating a fresh key over it.
+
+## Summary of New Capabilities
+
+- Boot fails fast with an actionable message when secrets cannot be resolved for boot-critical fields (enabled messaging adapters' tokens; authToken when binding non-loopback) — never a placeholder-driven type-error crash minutes later.
+- `mergeConfigWithSecrets` failures are reported through DegradationReporter instead of an empty catch.
+- The user-global secret store refuses to generate a new key over existing encrypted data it would orphan; it reports and stays locked instead.
+- Local secret-store failures in SecretManager are reported instead of silently returning empty results.
+- `migrateSecrets` writes with the same key resolution the boot read path uses (no manufactured key divergence).

package/upgrades/keychain-per-agent-master-key.eli16.md

@@ -0,0 +1,3 @@
+# Secrets boot guard + orphan-proof stores
+
+When an agent's encrypted secrets can't be decrypted, the old behavior was to silently swallow the failure and let placeholder objects leak into the running config — the server then crash-looped minutes later on an unrelated-looking type error (the 2026-06-05 incident). Now the boot fails fast with a message naming the exact affected fields, the shared cross-agent secret vault refuses to generate a fresh key over existing data it would orphan, and secret-store failures are loudly reported instead of looking like "no secrets stored." Complements PR #810, which fixed the key storage layer itself.

package/upgrades/side-effects/gemini-modal-safe-reject.md

@@ -0,0 +1,86 @@
+# Side-effects Review: Gemini Modal Safe Rejects
+
+## Change
+
+This Tier-1 change extends the existing Prompt Gate deterministic modal path.
+It does not introduce a new policy engine or a new execution surface.
+
+Touched surfaces:
+
+- `src/monitoring/PromptGate.ts`: adds narrow Gemini CLI matchers for the
+  observed `npx instar@... Ok to proceed? (y)` install prompt and for Gemini
+  execution-approval modals with an explicit reject option.
+- `src/commands/server.ts`: logs execution auto-rejects before sending the
+  reject key, and reports them through `DegradationReporter`.
+- `tests/unit/PromptGate.test.ts`: covers the install-confirm match and
+  near-miss, plus the execution-approval reject boundary.
+
+## Overreach / Underreach
+
+The install matcher is deliberately under-broad. It accepts only the captured
+package-runner shape for `instar@x.y.z`, because the live miss was `instar`
+itself. It does not auto-answer unrelated package installs such as `left-pad`.
+
+The execution matcher is also narrow. It only auto-rejects when the terminal
+shows the known `Allow execution of:` modal and a reject option. If the UI shape
+changes or the reject option is missing, normal relay/classification remains the
+fallback. There is no auto-approve path.
+
+## Safety Boundary
+
+Install confirmations and execution approvals are not the same class.
+
+An `npx instar@... Ok to proceed? (y)` prompt confirms the package runner's
+default for an Instar command the agent already invoked. Accepting it unblocks
+the intended tool path.
+
+An execution-approval prompt asks whether arbitrary command text may run. The
+command can be malformed, unrelated to the task, or unsafe. The live Gemini
+cycle proved this with a shell-comment command. Auto-approving that class would
+turn model output into code execution. This change therefore only supports
+safe-reject for execution approvals.
+
+## Observability
+
+Auto-rejects are intentionally visible. Before sending the reject key, the
+server writes a `[PromptGate] Auto-rejected execution approval...` warning with
+the rejected command text and emits a `PromptGate.executionApprovalAutoReject`
+DegradationReporter event.
+
+This is not just debugging convenience. It is part of the safety design: when a
+mentee appears to stall or pivot, the mentor can see that the framework rejected
+an execution prompt and why.
+
+## Signal vs Authority
+
+The new matchers are deterministic authority only for two tightly-scoped UI
+shapes:
+
+- safe-default for `instar@...` package-runner install confirmation;
+- safe-reject for Gemini execution approval with an explicit reject option.
+
+Everything else remains signal for the existing Prompt Gate relay/classifier
+flow. The change does not add an LLM prompt filter, does not broaden yes/no
+auto-approval, and does not treat generic `Ok to proceed?` text as authority.
+
+## Adjacent Systems
+
+- Telegram/Slack prompt relay: unchanged for prompts that do not match the new
+  exact shapes.
+- AutoApprover: unchanged. Execution safe-reject uses the pre-classifier
+  auto-dismiss path, not the auto-approve path.
+- DegradationReporter: receives one observable event per execution auto-reject.
+  The event is intentional and mentor-facing; it should not be treated as a
+  failure of Prompt Gate.
+
+## Rollback
+
+Revert the three code/test changes and remove these upgrade artifacts. Runtime
+state does not need migration. Existing agents would return to relaying or
+waiting on these Gemini prompts.
+
+## Verification
+
+- `npm test -- --run tests/unit/PromptGate.test.ts` passed, 57 tests.
+- `npx tsc --noEmit` passed.
+

package/upgrades/side-effects/hook-block-stderr.md

@@ -0,0 +1,33 @@
+# Side-effects review — grounding hook block-output → STDERR
+
+Live incident (2026-06-05): the message-quality gate (convergence check inside the
+grounding-before-messaging PreToolUse hook) correctly BLOCKED several outbound
+messages — but wrote the findings + block banner to STDOUT. On a PreToolUse exit-2
+block, Claude Code surfaces ONLY STDERR, so every block rendered to the agent as
+"hook error ... No stderr output": a malfunction instead of a verdict. The agent
+(me) retried blind several times before diagnosing via direct hook invocation.
+
+## 1. The change
+
+Both copies of the hook source (the `src/templates/hooks/` init-time file AND the
+inline `PostUpdateMigrator.getGroundingBeforeMessaging()` that migrateHooks
+always-overwrites onto every agent) now route the block findings + banner to
+STDERR. The pass path (GROUNDED on stdout, exit 0) is unchanged.
+
+## 2. Migration parity
+
+Built-in hooks in `.instar/hooks/instar/` are ALWAYS overwritten on every
+migration run — the fix reaches every deployed agent automatically on the next
+update; no new migration code needed.
+
+## 3. Blast radius
+
+Two-line behavioral change inside an existing block branch. The gate's
+DECISIONS are untouched — only where the explanation lands. No config, routes,
+or schema.
+
+## 4. Test coverage
+
+6 tests (3 × both template copies via describe.each): block → exit 2 + findings
+on STDERR with stdout clean; pass → exit 0 + GROUNDED on stdout; non-messaging
+input untouched. Run against the REAL hook sources with a stubbed quality check.

package/upgrades/side-effects/keychain-per-agent-master-key.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — Secrets boot guard + orphan-proof stores
+
+**Version / slug:** `keychain-per-agent-master-key`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `codex gpt-5.5 adversarial spec review (SHIP-WITH-CHANGES, all 8 required changes applied); re-scoped after PR #810 landed the SecretStore layer in parallel — surviving sections were part of the converged design`
+
+## Summary of the change
+
+Closes the remaining layers of the 2026-06-05 keychain master-key poisoning incident (Echo boot crash-loop, ~25 min Telegram mute) that PR #810 (vault-key-coherence) did not cover: `loadConfig` reports merge failures via DegradationReporter and fails the boot fast when `{secret:true}` placeholders survive in boot-critical fields; `GlobalSecretStore.initWithKeychain` refuses to generate over existing ciphertext; `SecretManager` local-store catches report instead of silently returning null/{}; `migrateSecrets` drops the `forceFileKey` write/read asymmetry.
+
+## Decision-point inventory
+
+- `Config.loadConfig` — modified — merge catch reports via DegradationReporter; `assertNoCriticalSecretPlaceholders` fails boot on surviving placeholders in ENABLED adapters' required secret fields (telegram token/chatId, slack botToken/appToken) or authToken when binding non-loopback.
+- `GlobalSecretStore.initWithKeychain` — modified — generation guard over existing ciphertext (report + stay locked, never orphan); injectable exec for hermetic tests.
+- `SecretManager.get/set/getAllFromLocal` — modified — failures reported via `reportLocalStoreFailure`, behavior (degrade) unchanged.
+- `SecretMigrator.migrateSecrets` — modified — drops `forceFileKey: true` (writes resolve through the same key resolution as reads).
+
+## 1. Over-block
+
+The boot guard could block a boot that previously "worked" in a degraded state (placeholders present but the adapter happened to be broken anyway). That is intentional: the previous behavior was a 2-minute zombie boot ending in `tokenHash(Object)`. Scope is narrowed to enabled adapters' required fields + conditional authToken; disabled adapters and unknown fields never block (codex review changes #5/#6). Verified by integration tests on both sides of each boundary.
+
+## 2. Over-permit
+
+None added. The generation guard strictly REMOVES a permissive path (fresh key over existing ciphertext). The boot guard never relaxes any existing check.
+
+## 3. Interplay with the parallel fixes (#810, #802, #789)
+
+- **#810 (vault-key-coherence)** owns SecretStore: per-agent accounts (`master-key:<stateDir>`), keyId header, dual-key fallback, convergence-on-write. Its named wrong-key error flows verbatim into this PR's actionable boot failure — the two compose: #810 makes most key divergence self-heal; when nothing decrypts, this PR makes the failure fast and precise instead of a placeholder leak.
+- **#802** guards the CONSUMER side (TelegramAdapter string-shape checks). This PR guards the PRODUCER side (config load). #802's PR body names this spec as the owner of the config layer.
+- **#789/#810's VITEST guard** keeps test runs file-key-only; this PR's tests never touch the real keychain (GlobalSecretStore tests use the injectable exec / password-mode seeding; the real-keychain generation test is darwin-scoped `skipIf`).
+
+## 4. Failure modes
+
+- No key decrypts a store → #810 throws its named error → merge catch reports → boot guard throws the actionable message naming fields (never silent placeholders).
+- Secrets genuinely absent (fresh agent, no migration) → no placeholders in config → guard never fires → zero change.
+- GlobalSecretStore keychain entry vanishes with data present → store stays LOCKED with a report instead of silently orphaning data behind a fresh key.
+- Loopback-only agent with an authToken placeholder → degrade-with-report (boot proceeds) — matches the existing non-loopback-only criticality condition.
+
+## 5. Migration parity
+
+No installed-file/config-shape changes — `PostUpdateMigrator` untouched by design. The boot guard activates purely from existing on-disk state.
+
+## 6. Token/cost impact
+
+None. No LLM calls; one config-tree scan at boot (microseconds).
+
+## 7. Rollback
+
+Revert the commit. All four changes are behavior-narrowing or report-only; no data format changes, nothing re-encrypted. Old behavior (silent catch, generate-on-miss) returns exactly as before.