instar 1.3.424 → 1.3.426

package/upgrades/eli16/provider-swap.md

@@ -0,0 +1,33 @@
+# Herd-Aware Provider-Swap — Plain-English Overview
+
+> The one-line version: when a safety gate's AI is rate-limited, instead of giving up (and falling back to weak code), it tries your OTHER AI providers first — and only fails closed if every one is down.
+
+## The problem in one breath
+
+We just made the safety gates fail closed when their AI is down. That's safe, but it means more things pause for approval during a rate-limit. The better answer: don't fail at all if another AI provider is available — swap to it.
+
+## What already exists
+
+- **One shared AI router** that every gate and sentinel calls. It already routes different components to different AI frameworks (Claude, Codex, Pi) and gives each its own circuit breaker.
+- **The fail-closed gates** (from the previous change) — on an AI failure they require approval / hold, rather than silently proceeding.
+
+## What this adds
+
+A **failure-swap** at that one router. When a SAFETY-GATING call's AI fails, the router walks a configured ordered list of fallback frameworks, **skips any whose circuit is already open** (so it never piles load onto a provider that's also struggling), and serves the answer from the first healthy one. Only if every provider is down does it fail closed.
+
+## The new pieces
+
+- **`failureSwap` config** — an ordered list of frameworks to try on a gating call's failure (e.g. Codex, then Pi). Default: empty = today's behavior, nothing changes unless you turn it on.
+- **A `gating` flag** on the call — only safety-gating calls swap. This keeps the "herd" tiny: a rate-limited framework can't dump its whole load onto another, because only the few real gates swap (advisory calls keep degrading as before).
+
+## The safeguards
+
+**Prevents herding.** The original router deliberately didn't swap, to avoid a rate-limited framework dumping all its traffic onto the fallback at once. This keeps that protection two ways: only gating calls swap (small set), and any fallback whose circuit is already open is skipped instantly.
+
+**Fail-closed is still the floor.** If every provider is down, the error re-throws and the gate fails closed — never a silent drop to weak code.
+
+**Generalizes to all your providers.** Claude, Codex, Pi, and Copilot-via-Pi are each a separate account/quota, so the same model reachable through multiple paths is redundancy. Composes with the subscription-pool (which manages accounts within a provider).
+
+## What ships when
+
+This PR is the router swap + the gating flags on the five safety gates. Follow-ups: a model-family-diverse default order, the lint, the iterative re-audit to convergence, and the throwaway-agent test harness.

package/upgrades/guard-forcepush-precise.eli16.md

@@ -0,0 +1,29 @@
+# Guard force-with-lease check — scope it to the actual push command
+
+> The one-line version: the safety hook that blocks force-pushes was reading the *whole* command line — including unrelated status text — so it sometimes blocked a perfectly safe branch update by mistake; now it reads only the `git push` part.
+
+## The problem in one breath
+
+Instar has a safety hook (`dangerous-command-guard`) that stops dangerous git commands. It deliberately *allows* one safe case: `git push --force-with-lease` to your own feature/PR branch (the normal way to update a rebased branch), while still blocking a force-push that targets a protected branch like `main`, `master`, `develop`, or anything starting with `release`. The trouble was *how* it decided "is this targeting a protected branch": it scanned the entire command string for those words. So if the command happened to contain unrelated text — for example a chained status message or log line that mentioned "release cadence" or "main menu" — the guard saw the word "release"/"main" and wrongly concluded you were force-pushing a protected branch. It blocked a legitimate update to a feature branch.
+
+## What already exists
+
+- **`dangerous-command-guard` hook** — a PreToolUse shell hook that inspects every shell command an agent runs and blocks catastrophic or destructive ones (`rm -rf /`, `git push --force`, etc.). It already had the force-with-lease carve-out; only the protected-branch test inside it was too broad.
+- **The carve-out itself** — the logic that says "force-with-lease to a non-protected branch is fine, force-with-lease to main is not." That intent is correct and unchanged.
+- **Three writers of the guard** — the same guard script is produced in three places: the shipped template (`src/templates/hooks/dangerous-command-guard.sh`), the migration writer that updates existing agents (`PostUpdateMigrator`), and the fresh-install writer (`init.ts`). All three carried the identical bug.
+
+## What this adds
+
+The fix narrows the protected-branch check so it looks **only at the extracted `git push …` invocation**, not the whole command. Concretely: pull out just the `git push ...` portion of the command, and check *that* for a protected-branch token. Unrelated text elsewhere in the command can no longer flip the decision. The main/master/develop/release block stays exactly as precise as before for the part that actually matters — the push command — so nothing is loosened; force-with-lease to `main` is still blocked.
+
+The same one-line change is applied to all three writers, so existing agents get it on their next update and new agents get it at install. A regression test pins the exact false-positive (a force-with-lease to a feature branch with the word "release" in trailing text must be allowed).
+
+## The safeguards
+
+**Prevents the false-positive without widening the guard.** The check is now scoped to the push invocation, so it is *narrower*, not broader. A force-push to a protected branch is still blocked; plain `--force` / `-f` (no lease) is still blocked; everything the guard caught before, it still catches.
+
+**Prevents drift between the three writers.** All three copies are fixed together, and existing tests already assert all three writers contain the carve-out, so a future edit that fixes only one copy would be caught.
+
+## What ships when
+
+One PR, one release. The migration writer means deployed agents pick the fix up automatically on their next update; no action required from anyone.

package/upgrades/side-effects/guard-forcepush-precise.md

@@ -0,0 +1,38 @@
+# Side-Effects Review — scope force-with-lease protected-branch check to the push invocation
+
+**Version / slug:** `guard-forcepush-precise`
+**Date:** `2026-06-07`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; the does-this-widen-the-guard question addressed below`
+
+## Summary of the change
+
+The `dangerous-command-guard` carve-out that permits `git push --force-with-lease` to a non-protected branch previously decided "is this a protected branch?" by scanning the WHOLE command input (`$INPUT`) for `(main|master|develop|release*)`. Any unrelated text in the command — a chained heredoc status message, a redirect path, a log line mentioning "release cadence" or "main" — false-positived and blocked a legitimate PR-branch force-with-lease update (observed live 2026-06-07, topic 19437: a force-push whose accompanying report text mentioned "release cadence" was blocked). The fix extracts only the `git push …` invocation (`grep -oiE 'git +push[^|;&]*' | head -1`) and scans THAT for the protected-branch token. Applied identically to all three writers (template, PostUpdateMigrator, init.ts) plus a regression test.
+
+## Decision-point inventory
+
+- Protected-branch scan target — modified — `$INPUT` (whole command) → `$PUSH_INVOCATION` (extracted `git push …` segment only). No change to the regex itself.
+- Carve-out semantics — unchanged — force-with-lease to a non-protected branch allowed; to main/master/develop/release* blocked; plain `--force`/`-f` blocked.
+- Writers touched — all three (template `.sh`, `PostUpdateMigrator.getDangerousCommandGuard`, `init.ts` inline copy) — kept byte-consistent.
+
+## 1. Direction-of-failure analysis
+
+- **Old failure (live):** the guard blocked a SAFE force-with-lease to a feature branch whenever unrelated command text contained a protected-branch word → recurring friction; the agent could not update its own PR branch and resorted to workarounds.
+- **New behavior:** the scan is confined to the push command. `git push --force-with-lease origin echo/feature && echo "release cadence on main"` is now ALLOWED (push targets a feature branch); `git push --force-with-lease origin main` is still BLOCKED. Both pinned by tests.
+- **Trust surface NOT widened:** the change makes the protected-branch check NARROWER (fewer inputs match), never broader. A force-push to a protected branch, and plain `--force`/`-f`, remain blocked exactly as before — verified by the existing "BLOCKS force-with-lease that explicitly targets main/master" and "BLOCKS plain git push --force" tests, which still pass.
+
+## 2. Over-permit
+
+None. The only behavioral delta is that unrelated text outside the `git push` segment no longer triggers the protected-branch block. No new verbs, no wildcarding, no relaxation of the protected-branch set.
+
+## 3. Scope deliberately NOT taken
+
+- The broader text-scanning class (a `git commit` whose *message* mentions `git push --force` trips the risky-pattern loop) is a real but separate limitation of the deploy/risky-pattern scan; fixing it requires command-verb parsing across the whole guard and is out of scope for this targeted carve-out fix. Noted for a follow-up.
+
+## 4. Migration parity
+
+Covered. The migration writer (`PostUpdateMigrator.getDangerousCommandGuard`) is fixed, so existing agents receive the corrected guard on their next update (built-in `instar/` hooks are always-overwritten on migration). New agents get it via `init.ts`. The shipped template is fixed for completeness.
+
+## 5. Token/cost impact
+
+None.

package/upgrades/side-effects/provider-swap.md

@@ -0,0 +1,29 @@
+# Side-Effects Review — Herd-aware provider-swap
+
+**Version / slug:** `provider-swap` · **Date:** `2026-06-07` · **Author:** `Echo` · **Second-pass:** `not required (Tier-1)`
+
+## Summary of the change
+`IntelligenceRouter.evaluate` now, on a RUNTIME provider failure for a SAFETY-GATING call (`attribution.gating: true`), walks `componentFrameworks.failureSwap` (ordered frameworks), skips circuit-open targets, serves from the first healthy one, and re-throws if all are down (caller fails closed). New `failureSwap` config field + `gating` attribution flag. 5 safety-gating callers marked gating (ExternalOperationGate, MessagingToneGate, MessageSentinel, IntentLlmJudge, InputGuard).
+
+## Decision-point inventory
+- `IntelligenceRouter.evaluate` failure path — add (swap-on-failure for gating calls)
+- `ComponentFrameworksConfig.failureSwap` — add (opt-in)
+- `IntelligenceOptions.attribution.gating` — add (opt-in marker)
+
+## 1. Over-block / Under-block
+No allow/deny surface. The swap only changes WHICH provider answers a gating call on failure; the gate's own verdict logic is unchanged. Non-gating calls and the unconfigured default are byte-identical to before.
+
+## 2. Data / state
+None. No files, no schema, no persistence. Pure in-memory routing.
+
+## 3. Performance
+On the FAILURE path only, a gating call may make up to N extra provider attempts (N = failureSwap length), each short-circuited by its own breaker if open. The happy path (provider healthy) is unchanged — one call. No hot-path cost added.
+
+## 4. Failure modes / herding
+This IS failure-mode handling. Herding is bounded two ways: only gating calls swap (small set), and circuit-open targets are skipped (no load onto a stressed provider). All-down → re-throw → caller fails closed. No infinite loop (finite list, `target===framework` skipped).
+
+## 5. Security / auth
+Hardens availability of the safety gates (they get a working provider before failing closed). No new endpoints/capabilities/credentials. The swap reuses already-wired per-framework providers.
+
+## 6. Migration / compatibility
+No migration. Default (no `failureSwap`) = unchanged behavior. Opt-in per agent via `componentFrameworks.failureSwap`. `gating` is additive on attribution (ignored by old code paths).