instar 1.3.277 → 1.3.279

package/upgrades/side-effects/mandates-dashboard-tab.md

@@ -0,0 +1,56 @@
+# Side-effects review — Mandates dashboard tab + coordination awareness backfill
+
+Spec: `docs/specs/coordination-mandate.md` (approved A/A/B; decision 2A makes the
+dashboard-behind-PIN the issuance surface). Change: a new dashboard **Mandates** tab
+(`dashboard/mandates.js` external module + index.html shim) + the Migration-Parity
+CLAUDE.md backfill for the three coordination surfaces shipped in #788/#797/#799.
+
+## 1. Blast radius
+
+- **Dashboard:** additive — one new tab button, panel, TAB_REGISTRY entry, lazy
+  module import (the process-health.js pattern), and scoped `.mnd-*` CSS. No existing
+  tab, function, or style is modified. The dashboard ships inside the npm package, so
+  existing agents receive the tab on their next update with no migration.
+- **PostUpdateMigrator:** three new content-sniffed CLAUDE.md backfill blocks
+  (Coordination Mandate / ReviewExchange / Cutover Readiness), appended only when the
+  distinctive route marker is absent — idempotent, never rewrites existing content.
+  This closes a REAL parity gap: #788/#797/#799 added the template blurbs for new
+  agents but no backfill, so the deployed fleet would never have learned these
+  surfaces exist.
+- **templates.ts:** one line sharpened (point the operator at the "Mandates tab"
+  rather than the generic dashboard).
+
+## 2. Security model (the PIN discipline, in the UI this time)
+
+- The tab's issue/revoke forms collect the PIN in a `type="password"` input with
+  `autocomplete="off"`, send it ONCE in the request body to the already-PIN-gated
+  routes, and **clear the field immediately after the response — success or failure**.
+  It is never written to localStorage, module state, or logs (behaviorally tested).
+- The Bearer token the dashboard holds cannot issue/revoke — that is the engine's
+  server-side design (#788); this tab is just the human surface decision 2A names.
+- Rendering is XSS-safe: every dynamic field (ids, scopes, fingerprints, authority
+  bounds, audit reasons — all potentially attacker-influenced via the API) is escaped
+  (tested with hostile payloads).
+- A broken audit chain (`chain.ok:false`) renders as a loud "CHAIN BROKEN — possible
+  tampering" badge, never silently.
+
+## 3. State / data
+
+None on the server. The tab reads `/mandate` + `/mandate/audit` and writes only
+through the existing PIN-gated routes. Browser-side, nothing persists beyond the
+already-stored dashboard Bearer token (unchanged).
+
+## 4. Failure modes
+
+- Older server without the engine → 503 → friendly "engine unavailable" copy.
+- Module load failure → console error, tab simply shows nothing (no crash).
+- Wrong PIN → the route's 403 + attempt limiting surface as an inline error; the
+  field still clears.
+
+## 5. Test coverage
+
+18 tests: 5 HTML-at-rest wiring (tab/panel/registry/lazy-import/plain-language), 4
+renderer (deny-by-default copy, badges, XSS with hostile payloads, broken-chain), 6
+controller (PIN required → no request; PIN sent once then CLEARED on success AND on
+403; template prefill; 503 state), 4 migration (backfill lands with port baked in,
+security copy verbatim, idempotent, no double-patch on fresh agents).

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).