instar 1.3.276 → 1.3.278

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/vault-key-coherence.md

@@ -0,0 +1,113 @@
+# Side-Effects Review — Vault key coherence (CMT-1038)
+
+**Version / slug:** `vault-key-coherence`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (crypto algorithm unchanged; resolution/format layers only; every boundary side test-pinned; v1 reads preserved; failure modes strictly improve on today's silent-empty)
+
+## Summary of the change
+
+Three layers killing the key-bifurcation disease: (1) per-agent keychain
+accounts (`master-key:<stateDir>`) with read-time adoption of the legacy
+global slot (which is never written again); (2) v2 store format with a keyId
+header (`'ISv2'|keyId(8)|iv|tag|ct`) so wrong-key is a precise, named error
+distinct from corruption — v1 files read forever; (3) dual-key read fallback
+(primary first, then the other source, read-only alternates) with a loud
+DegradationReporter on divergence and natural convergence on the next write.
+Plus: `GET /secrets/sync-status` now reports `vault: {status:'ok'|'empty'|
+'decrypt-failed', error?}` instead of masking decrypt-failure as empty.
+Keychain ops are injectable (`SecretStoreConfig.keychainOps`) so all of this
+is unit-tested against a fake; the #789 real-keychain test guard holds
+whenever no fake is injected.
+
+## Decision-point inventory (each side pinned)
+
+1. Per-agent slot present / legacy-only (adopt, global untouched) / neither
+   (generate → per-agent slot, NEVER global) — 3 tests.
+2. v2 keyId match / no-match (named error, "NOT empty") / matching-key
+   corruption (GCM auth error) — 3 tests.
+3. v1 primary-key read / v1 fallback-key read (THE incident case) /
+   write-after-fallback converges to primary / forceFileKey primary with
+   keychain alternate — 4 tests.
+4. Guard: no injected fake + VITEST ⇒ file-key only — 1 test.
+5. vaultStatus: ok / empty / decrypt-failed (route surface).
+
+## 1. Over-block
+
+Nothing readable today becomes unreadable: every key the old code could
+resolve is still a candidate, plus more. The new thrown errors fire ONLY
+where today's code also throws (v1, both keys wrong) or silently lied
+(reported empty); the route now reports those as `decrypt-failed` instead of
+`[]`.
+
+## 2. Under-block
+
+- The legacy global slot remains readable machine-wide until every agent
+  adopts — by design (deleting it would break un-migrated agents). It decays
+  naturally: nothing writes it, every reader adopts away from it.
+- Dual-key fallback widens which keys may open a vault to keys the SAME agent
+  resolves from ITS OWN two sources — no new principals, no cross-agent keys.
+- Convergence-on-write re-encrypts with the primary; if another process of
+  the same agent still resolves only the stale alternate, IT then uses its
+  own fallback (now in the other direction) and converges the same way — the
+  fixed point is both sources agreeing, reached after adoption.
+
+## 3. Level-of-abstraction fit
+
+Resolution lives in MasterKeyManager (the single key authority); format +
+fallback in SecretStore.read/write (the single at-rest codec); the route only
+gains a status field. Wire-sync crypto (X25519/HKDF) untouched.
+
+## 4. Signal vs authority compliance
+
+**Reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+No gating added. Errors got MORE precise; the degradation report is
+signal-only; adoption/convergence are self-healing writes within the agent's
+own key material.
+
+## 5. Interactions
+
+- Store-first drop persistence (#789), sealed-handoff at-rest, and the sync
+  provisioner all read through the same read() — regression suites green
+  (21/21).
+- Echo's live vault (v1, file-key, keychain slot deleted in the incident
+  remediation): reads via primary file key unchanged; first write upgrades to
+  v2 with the file keyId. No migration step needed anywhere — resolution-time
+  adoption + write-time format upgrade.
+- Mixed fleet versions: older readers can't read v2 — but a vault is only
+  read by ITS OWN agent on ITS OWN machine (wire sync re-encrypts per peer),
+  so the only mixed-version reader of a given file is the same agent
+  mid-update, which restarts onto the new code. Residual window ≈ one
+  restart; documented.
+
+## 6. External surfaces
+
+`vault` field on sync-status (additive); exported `perAgentKeychainAccount`/
+`keyIdOf` helpers; `SecretStoreConfig.keychainOps` (test seam). No config
+flags, no migration, no new routes.
+
+## 7. Rollback cost
+
+Revert restores old code — which reads v1 files only. Any vault already
+upgraded to v2 would need its 28-byte header stripped (`tail -c +13` of the
+post-magic body) — documented here as the rollback runbook; low likelihood
+(revert would only follow a fast-caught regression, before fleet-wide v2
+rewrites).
+
+## Conclusion
+
+The recurring "vault looks empty" disease removed at its three roots —
+shared slot, mute wrong-key failures, single-key reads — with strictly more
+diagnosable failure modes and zero operator action.
+
+## Second-pass review (if required)
+
+Not required — see header.
+
+## Evidence pointers
+
+- `tests/unit/secret-store-key-coherence.test.ts` (11, incl. THE incident
+  case verbatim and convergence-on-write).
+- `tests/unit/secret-store.test.ts` 29/29; secret-adjacent regression suites
+  21/21 (store-first integration + sealed-handoff + hardening + e2e).
+- `docs/specs/vault-key-coherence.md` + `.eli16.md`. <!-- tracked: CMT-1038 -->