instar 1.3.256 → 1.3.258

package/upgrades/1.3.258.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Finishes Phase 4 of the multi-machine arc: cross-machine secret sync. A secret given to the
+agent on one machine can now be distributed, encrypted, to its other machines — so the same
+agent can use it everywhere without the user re-entering it per machine.
+
+- **`SecretSync` module** — `SecretProvisioner` (sender side: encrypts the secret set per
+  recipient to that machine's X25519 key and pushes a signed `secret-share` over the mesh) +
+  `SecretShareHandler` (receiver side: decrypts with this machine's own key and stores into
+  the local encrypted vault) + `secretKeyPaths` (names-only flattening for status).
+- **Reuses the existing forward-secret crypto** (`encryptForSync`/`decryptFromSync`,
+  ephemeral-key-per-payload X25519 → AES-GCM); the mesh already enforces TLS, Ed25519
+  signing, and the registered-peer gate, so this adds application-layer confidentiality.
+- **Two routes** (both behind auth): `GET /secrets/sync-status` reports which secret key
+  NAMES this machine holds plus the peers it would sync to (never a value); `POST
+  /secrets/sync-now` is the deterministic push lever (encrypts per online peer and pushes).
+- **Config flag** `multiMachine.secretSync.enabled` — ships dark; defaults on only for the
+  development agent. A single-machine agent is a no-op.
+
+## What to Tell Your User
+
+- **A secret you give me on one machine can become usable on your other machines** — a bot
+  token, an API key, a login — without you setting it up again on each computer. It travels
+  encrypted to each of your machines and is never written down in plain text along the way.
+- This is an early capability and ships turned off by default. When it is on, if you ever
+  start re-entering something you already gave me elsewhere, I can tell you it already synced.
+
+## Summary of New Capabilities
+
+- Cross-machine secret distribution: drop a secret once, use it on every paired machine.
+- A read-only status view of which secrets a machine holds (names only, never values).
+- A deterministic push lever to sync secrets on demand.
+
+## Evidence
+
+15 tests across all three tiers: 8 unit (real-crypto round-trip, per-recipient sealing,
+wrong-key-fails confidentiality, best-effort fan-out, names-only flattening), 4 integration
+(real SecretStore + real crypto encrypt→ship→decrypt through the HTTP routes, asserting no
+secret value ever appears in a response, plus the 503-when-disabled paths), and 3 e2e (the
+routes alive through the real AgentServer with a genuine round-trip into a peer vault, behind
+auth). Spec: docs/specs/cross-machine-secret-sync-spec.md (approved).

package/upgrades/side-effects/cross-machine-secret-sync.md

@@ -0,0 +1,112 @@
+# Side-Effects Review — Cross-Machine Secret Sync
+
+**Version / slug:** `cross-machine-secret-sync`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (Tier 2; single-author under Justin's explicit signoff)
+
+## Summary of the change
+
+Implements Phase 4 of the multi-machine arc: a secret given to the agent on one machine is
+distributed, encrypted per-recipient, to its other registered machines so the same agent can
+use it everywhere without re-entry. New `src/core/SecretSync.ts` holds a `SecretProvisioner`
+(sender: encrypt the secret set to each online peer's X25519 key, push a signed `secret-share`
+over the mesh), a `SecretShareHandler` (receiver: decrypt with this machine's own key, store
+into the local encrypted vault), and `secretKeyPaths` (names-only flattening for status). The
+inbound dispatcher handler was already wired in `src/commands/server.ts`; this change adds the
+OUTBOUND provisioner (constructed after the MeshRpcClient), a route-facing `_secretSyncHandle`,
+two routes in `src/server/routes.ts` (`GET /secrets/sync-status`, `POST /secrets/sync-now`)
+plumbed through `AgentServer` + `RouteContext`, the `multiMachine.secretSync` config type, and
+agent-awareness (CLAUDE.md template + `PostUpdateMigrator` section). Crypto is reused, not new
+(`encryptForSync`/`decryptFromSync`, forward-secret ephemeral-key X25519→AES-GCM).
+
+## Decision-point inventory
+
+- `multiMachine.secretSync.enabled` gate (server.ts) — **add** — enables inbound handler +
+  outbound provisioner; resolves to `config.multiMachine.secretSync.enabled ?? !!developmentAgent`
+  (dark for normal agents, on for the dev agent).
+- `SecretProvisioner.listPeers` online filter — **add** — only online, registered peers with a
+  resolvable encryption key receive a push.
+- `secret-share` mesh acceptance — **pass-through** — authenticity, signing, registered-peer
+  gate, and nonce replay are already enforced by the existing MeshRpcDispatcher verify/RBAC
+  layer; this change adds only application-layer confidentiality on top.
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The two routes 503 only when the feature
+is disabled or the handle is absent; they never reject a legitimate request when enabled.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. (Security property of note instead: a
+`secret-share` payload sealed to machine A cannot be decrypted by machine B — GCM auth fails —
+covered by the "wrong key fails" unit test.)
+
+## 3. Level-of-abstraction fit
+
+Right layer. The transport-level guarantees (TLS, Ed25519 signing, registered-peer gate, nonce
+replay) live in the mesh and are reused, not re-implemented. This change is purely the
+application-layer secret-distribution logic over that transport, plus thin route/handle wiring.
+It USES the existing `encryptForSync`/`decryptFromSync` primitive rather than rolling new crypto,
+and USES `SecretStore.read()`/`set()` rather than re-implementing vault access. No higher-level
+gate is duplicated.
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change has no block/allow surface.
+
+The routes are read (status) and an explicit push lever; neither holds block authority over any
+message or operation. The mesh acceptance layer (the existing smart authority) owns
+accept/reject for `secret-share`.
+
+## 5. Interactions
+
+- **Shadowing:** none. The two new routes are new paths (`/secrets/sync-status`,
+  `/secrets/sync-now`) that don't sit before/after any existing check.
+- **Double-fire:** the inbound `secret-share` handler is idempotent at the vault level — a
+  re-delivered share just re-writes the same decrypted value (rotate=overwrite, per spec).
+  Boot best-effort push + the deterministic route can both push the same set; the receiver
+  storing the same value twice is harmless.
+- **Races:** `SecretStore.read`/`set` is read-modify-write to one encrypted file via an atomic
+  temp-file rename. Concurrent shares writing different key-paths could interleave a read with a
+  write; v1 syncs the whole set on provision and overwrites, so a lost interleaved write is
+  re-converged by the next push. Flagged as a known v1 limitation, not a correctness break for
+  the single-writer-at-a-time provision pattern.
+- **Feedback loops:** none. A received share does not itself trigger a re-push (no boot/provision
+  event fires on inbound store), so shares don't ping-pong between machines.
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** none — keyed to this agent's own mesh + vault.
+- **Install base:** ships DARK; a normal agent and a single-machine agent are no-ops.
+- **External systems:** none new. Uses the existing mesh transport between the user's own paired
+  machines; no third-party service involved.
+- **Persistent state:** writes decrypted secrets into the RECEIVING machine's existing encrypted
+  vault (`config.secrets.enc`) — the same store Secret Drop / SecretMigrator already write. No
+  new on-disk plaintext; the wire payload is forward-secret encrypted.
+- **Timing:** boot best-effort push is fire-and-forget and never blocks startup.
+
+## 7. Rollback cost
+
+Pure code change behind a dark flag — revert and ship a patch; no user-visible regression during
+the rollback window (the feature is off for everyone except the dev agent). The only persistent
+side effect is that secrets already pushed to a peer remain in that peer's vault after rollback —
+which is the intended end-state (the user wanted them there) and requires no cleanup. No schema
+or migration to unwind.
+
+## Conclusion
+
+The review surfaced one honest v1 limitation (whole-set overwrite means an interleaved partial
+write is re-converged on the next push rather than merged) which is acceptable for the
+push-on-provision model and is documented. No design changes were required. Crypto is reused, the
+transport gate is reused, the feature ships dark, and rollback is a clean revert. Clear to ship
+through the ceremony, with live-verification on the real laptop+mini pair as the final gate
+before enabling it beyond the dev agent.
+
+## Evidence pointers
+
+- 15 tests green: `tests/unit/secret-sync.test.ts` (8), `tests/integration/secret-sync-routes.test.ts`
+  (4, real crypto round-trip through HTTP + no-value-leak asserts), `tests/e2e/secret-sync-alive.test.ts`
+  (3, real AgentServer alive + round-trip into a peer vault + auth).
+- `tsc --noEmit` clean; `npm run lint` clean.
+- Spec: `docs/specs/cross-machine-secret-sync-spec.md` (approved).

package/upgrades/side-effects/prepush-gate-diff-base-main-ref.md

@@ -0,0 +1,45 @@
+# Side-Effects Review — pre-push gate diffs against the main ref, not @{u}
+
+**Version / slug:** `prepush-gate-diff-base-main-ref`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (build-gate diff base; safe-by-construction)`
+
+## Summary
+
+`scripts/pre-push-gate.js` computed `changedFiles` via `git diff --name-only ${remoteBranch}...HEAD`
+where `remoteBranch = @{u}` (the branch's OWN upstream). That breaks when a PR is updated by
+MERGING main in (the no-force-push path used to resolve conflicts): `@{u}...HEAD` then includes
+ALL of main's already-shipped changes, so the gate's section-3/3b checks see 173+ unrelated `src/`
+files → false "src changed without a release-note fragment" errors, forcing `INSTAR_PRE_PUSH_SKIP=1`
+(hit live on #663). The fix computes the diff against the PR's MERGE TARGET — the first resolvable
+of `JKHeadley/main`/`origin/main`/`upstream/main`/`main` — falling back to the old `@{u}` behaviour
+only when no main ref resolves.
+
+## 1. Over-block (what it still flags)
+
+Unchanged for the normal incremental-push case: `main...HEAD` (three-dot, from the merge-base =
+the branch point) == the PR's commits == what `@{u}...HEAD` gave for a never-merged-main branch.
+The src→tests, src→fragment (#23), and internal-only (§3c) checks all still fire on the PR's real
+`src/` changes. The "chore: release" commit (upgrades/ + version, no `src/`) still doesn't trip
+section-3b, same as before.
+
+## 2. Under-block (what it now lets through)
+
+Nothing it shouldn't. A three-dot diff against main can NEVER under-report the PR's own changes
+(the merge-base of main and HEAD is the branch point, so all the PR's commits are in the diff). The
+only direction it can err is OVER-reporting (if a branch is based off another branch, not main) —
+the safe direction (extra false-positives, never a missed src-change-without-fragment). The fix
+specifically REMOVES the merge-from-main false-positive without weakening any check.
+
+## 3. Blast radius
+
+One file: `scripts/pre-push-gate.js` (the `changedFiles` computation feeding sections 3/3b/3c) +
+its unit test. No `src/`, no runtime, no agent surface. `pickRef` is a local helper; on any error
+it falls through to the prior `@{u}` logic, so a clone without a `main` remote behaves exactly as
+before.
+
+## 4. Reversibility
+
+Fully reversible: revert the one hunk. No state. Verified: `node --check` clean; 16 pre-push-gate
+unit tests pass.