instar 1.3.278 → 1.3.280

package/upgrades/1.3.280.md

@@ -0,0 +1,102 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## 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
+shows the tamper-evident decision audit with its chain status. The PIN is typed at
+action time, sent once, and cleared immediately — it is never stored anywhere in the
+browser. Also backfilled the agent-awareness sections for the three coordination
+surfaces into existing agents' instruction files on update, so agents updated in
+place learn these capabilities exist (previously only freshly-initialized agents got
+them).
+
+Gave the cutover-readiness live-comparison trigger a realistic time budget. A real
+comparison downloads the full live dataset and takes a few minutes; the default
+30-second request limit cut off every response mid-run, and a late failure then
+crashed the response handling with no record of what happened. The trigger now has
+a six-minute budget, and whatever the outcome — recorded or failed — it is always
+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
+tamper-evident log of every allowed and denied action under them. Your PIN is asked
+for right when you act and is never remembered by the page.
+
+Nothing changes day to day. If your agent runs live data comparisons for a
+migration, those checks now finish reliably instead of getting cut off, and their
+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) —
+  PIN required, typed at issuance, never stored.
+- Revoke any active mandate inline with a reason — PIN required.
+- Read the hash-chained decision audit; a broken chain is flagged loudly as possible
+  tampering.
+- Existing agents now learn the mandate, review-exchange, and cutover-readiness
+  surfaces via the update path, not just fresh installs.
+
+- The live parity-comparison trigger completes within a realistic six-minute
+  budget instead of being cut off at thirty seconds.
+- 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/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/parity-pass-timeout.md

@@ -0,0 +1,30 @@
+# Side-effects review — parity-pass request-timeout fix
+
+Live finding (2026-06-05, first real trigger of the just-deployed G2.4 surface): a
+real parity pass fetches the FULL live Portal cluster set and takes ~3.5 minutes
+(measured 204s). The 30s default request timeout 408'd every trigger; the handler
+kept running, and a late failure's 409 crashed into ERR_HTTP_HEADERS_SENT with no
+trace of the outcome anywhere.
+
+## 1. The change
+
+- `middleware.ts`: `PARITY_PASS_TIMEOUT_MS = 360_000` + a `buildRequestTimeoutOverrides`
+  entry for `/cutover-readiness/parity-pass` — the exact `/spec/conformance-check`
+  precedent (single heavy call, per-path budget). Longest-prefix matching means the
+  read-only `GET /cutover-readiness` sibling keeps the 30s default (tested).
+- `routes.ts` (trigger route): the outcome is now ALWAYS logged server-side
+  (recorded/failed + reason), and the response is skipped when `res.headersSent`
+  (a 408 already went out) — never a double-respond crash, never a silent outcome.
+
+## 2. Blast radius
+
+Two files, additive. No other route's budget changes. T7 unchanged: the trigger
+still computes server-side; failures still record nothing.
+
+## 3. Test coverage
+
+5 new tests: override resolves for the trigger (≥ the measured real-pass duration)
+and ONLY the trigger; over real HTTP with a tiny budget — a slow SUCCESSFUL pass
+still records after the 408 with the outcome logged and no crash; a slow FAILED
+pass records nothing with the reason logged; the fast path still 200s. Existing
+override wiring suite green (20 total).

package/upgrades/1.3.278.md

@@ -1,36 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-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
-shows the tamper-evident decision audit with its chain status. The PIN is typed at
-action time, sent once, and cleared immediately — it is never stored anywhere in the
-browser. Also backfilled the agent-awareness sections for the three coordination
-surfaces into existing agents' instruction files on update, so agents updated in
-place learn these capabilities exist (previously only freshly-initialized agents got
-them).
-
-## What to Tell Your User
-
-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
-tamper-evident log of every allowed and denied action under them. Your PIN is asked
-for right when you act and is never remembered by the page.
-
-## Summary of New Capabilities
-
-- 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) —
-  PIN required, typed at issuance, never stored.
-- Revoke any active mandate inline with a reason — PIN required.
-- Read the hash-chained decision audit; a broken chain is flagged loudly as possible
-  tampering.
-- Existing agents now learn the mandate, review-exchange, and cutover-readiness
-  surfaces via the update path, not just fresh installs.