instar 1.3.257 → 1.3.259

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/1.3.259.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a CI gate (`.github/workflows/eli16-pr-gate.yml` + the pure check
+`scripts/eli16-pr-description-check.mjs`) that requires every PR's DESCRIPTION to carry a
+plain-English ELI16 overview, and FAILS the PR when it is missing. Per Justin's standard
+(2026-06-05): the PR description is what a reviewer reads and approves on the link, and the PRs "had
+different formats." The ELI16 *file* (docs/specs/<slug>.eli16.md) is unchanged and still enforced at
+commit time; this closes the PR-body half. Re-runs on `edited` (self-clears on a description fix);
+exempts bot authors + the automated release-cut PR.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- The decision is a PURE function (`checkPrDescriptionEli16`) with 10 unit tests covering both
+  sides (has-overview → pass; missing / too-short / next-heading-boundary / comment-stripped → fail)
+  and every exemption (bot, release-cut, title-mentions-release non-exemption, null inputs).
+- `node --check scripts/eli16-pr-description-check.mjs` clean. New additive workflow — cannot affect
+  existing checks/builds/releases; a failing PR is visible + self-clears on a description edit.
+- This PR's own description carries an ELI16 overview (dogfoods the gate). scripts + workflow + test
+  only, no `src/` (internal-only lane).

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/eli16-pr-description-gate.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — ELI16-on-every-PR gate (PR description)
+
+**Version / slug:** `eli16-pr-description-gate`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `required (a new gate that blocks EVERY PR)`
+
+## Summary
+
+Justin's standard (2026-06-05): every PR's DESCRIPTION must carry a plain-English ELI16 overview,
+because the description is what a reviewer reads and approves when they open the PR link — and the
+current PRs "have different formats." This adds a CI gate (`.github/workflows/eli16-pr-gate.yml`)
+that runs a pure check (`scripts/eli16-pr-description-check.mjs`) on every PR body and FAILS the PR
+when no ELI16 overview is present. The ELI16 *file* (`docs/specs/<slug>.eli16.md`) is unchanged and
+still enforced at commit time by the instar-dev gate; this is the missing PR-body half.
+
+## Decision-point inventory
+
+One decision: does the PR body contain an ELI16 overview? PASS when (a) the author is a Bot, or
+(b) the title is a `chore: release` cut, or (c) the body has a heading whose text contains
+`ELI16`/`ELI-16`/`ELI 16` followed by >= 200 chars of (comment-stripped) content. Otherwise FAIL.
+
+## 1. Over-block (what it blocks)
+
+A human/agent PR whose description lacks a real ELI16 overview is blocked — that's the point. The
+check re-runs on `edited`, so adding the overview to the description clears it WITHOUT a new push.
+The failure message is actionable (tells you exactly what to add + that the file is a good source).
+
+## 2. Under-block (what it lets through)
+
+Bot PRs and the automated `chore: release` PR (which has no human reviewer reading an ELI16). A PR
+that has a real ELI16 heading + >= 200 chars passes. The check measures content only up to the next
+heading, so a one-line ELI16 followed by a long "What Changed" does NOT slip through (tested).
+
+## 3. Blast radius — CRITICAL
+
+This gate blocks EVERY non-exempt PR, so a false-fail would block the whole fleet's PRs. Mitigations:
+the decision is a PURE function with 10 unit tests covering both sides AND every exemption (bot,
+release-cut, the "title mentions release" non-exemption, null/empty inputs, the next-heading
+boundary, comment-stripping). The gate is a NEW, additive workflow — it cannot affect existing
+checks, builds, or releases; a failing PR is VISIBLE and self-clears on a description edit (not a
+silent jam like the manifest/publish class). No `src/` runtime change.
+
+## 4. Reversibility
+
+Fully reversible: delete the workflow + script + test. No state, no migration. Verified: the check
+script parses (`node --check`); 10/10 unit tests pass. This PR's own description carries an ELI16
+overview (dogfoods the gate).