instar 1.3.270 → 1.3.271

package/upgrades/1.3.271.md

@@ -0,0 +1,154 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+One additive line in the mentor autoloop prompt (`src/scheduler/MentorAutonomousGuardian.ts`), locked by three new unit-test assertions. Earned from PR #792's no-silent-fallbacks CI failure, where a spec's "best-effort, never throws" wording invited the swallowed catch the ratchet counts.
+
+The dashboard sessions list now shows EVERY session across ALL machines in the
+multi-machine pool, and every session row states which machine it runs on
+(a machine-nickname badge). Sessions on the machine you're viewing stay fully
+interactive (live terminal, close button); sessions on other machines appear
+as informational rows with a tooltip pointing at the owning machine's
+dashboard.
+
+Under the hood: `GET /sessions` self-tags sessions with `machineId` /
+`machineNickname` when the pool is wired, and a new `GET /sessions?scope=pool`
+aggregates every reachable peer's session list (existing cross-machine Bearer
+auth, 5s timeout per peer). A dead or slow peer degrades to a `pool.failed`
+entry — the page never breaks. The plain `/sessions` route keeps its
+back-compatible array shape.
+
+Added the ReviewExchange protocol — the structured way two mandate-named agents complete
+a mutual code-review sign-off without the operator relaying messages between them. One
+exchange tracks one review package (content-addressed by checksum, fixed at creation)
+through a strict linear lifecycle: proposed, delivered, verdict recorded, complete — or
+changes-requested, which is terminal so a stale approval can never be replayed onto
+reworked code. Both sign-offs — the reviewing peer's authenticated approval and the
+owner's countersignature — are checked against the operator's coordination mandate
+before acceptance, and every accepted signature stores the audit reference of the gate
+decision that authorized it. With no mandate issued, every sign-off refuses: the
+protocol inherits deny-by-default and ships inert.
+
+A submitted Secret Drop is now persisted store-first to the durable
+AES-256-GCM encrypted SecretStore the instant it is received, instead of
+living only in the server's in-memory `received` map. The retrieve route
+transparently falls back to the durable copy when the in-memory one is gone
+(server restart, compaction, cross-machine handoff), and a successful consume
+deletes both copies — one-time semantics are preserved. Opt out with
+`secrets.persistDrops: false` in `.instar/config.json`.
+
+This closes the recurring "the user dropped a secret and the agent lost it"
+failure: with the fleet shipping many releases a day, every release restarted
+the server and evaporated any un-consumed submission.
+
+Also: the SecretStore master-key manager now forces file-key mode during test
+runs (`VITEST` / `NODE_ENV=test`). The OS keychain entry is machine-global —
+a test constructing a SecretStore against a fresh stateDir used to generate a
+new master key and silently overwrite that shared entry, making every real
+agent vault on the machine undecryptable for keychain-resolving readers. No
+test can touch the real keychain anymore. A `secrets.forceFileKey` config
+plumb is also available for operators who want to pin the key source.
+
+The CLAUDE.md template's Secret Drop "Security" bullet is rewritten (the old
+"in-memory only, never written to disk" claim is no longer true), and an
+idempotent migration updates existing agents' CLAUDE.md in place.
+
+Two fixes for the 2026-06-05 "move this to the laptop" noise incident, where
+one user message produced contradictory "Moving to Laptop" / "I can't move
+this right now (rate-limited)" replies and executed multiple times.
+
+1. **Idempotent topic transfer.** The transfer planner now recognizes a move
+   request targeting the machine the topic is already on — or already pinned
+   to — BEFORE the rate limit. Duplicates of an already-satisfied move answer
+   "This conversation is already running on X — nothing to move" instead of a
+   rate-limit rejection. The rate limit keeps its real job: damping rapid
+   flip-flops between DIFFERENT machines.
+
+2. **Exactly-once ingress turns on with the pool.** The exactly-once inbound
+   message gate (the dedupe ledger that stops retried/replayed messages from
+   re-executing commands) shipped default-OFF — even on machines whose
+   multi-machine session pool was live. The default is now stage-aware: a pool
+   at `live-transfer` or `rebalance` gets `exactlyOnceIngress` ON
+   automatically. An explicit `multiMachine.exactlyOnceIngress: false` still
+   wins.
+
+## What to Tell Your User
+
+Nothing user-visible. The autonomous mentor loop's instructions now include how to satisfy the repo's ratchet CI gates, so mentor-driven fixes stop tripping no-silent-fallbacks.
+
+Open the dashboard on any of your machines and you'll see all your sessions in
+one list — each with a badge saying which machine it's running on. No more
+opening one dashboard per machine to find a session.
+
+Your agent can now run a real code review with a partner agent under the permission
+slip you issue — no more relaying review messages between them yourself. The agents
+deliver the code package, record the reviewer's verdict, and counter-sign, and every
+step is checked against your permission slip and written to the same tamper-evident
+log. If you revoke the slip mid-review, the review stops on the spot. Until you issue
+a slip, nothing changes — every review step refuses by default.
+
+If you hand me a secret through a drop link, it now survives my server
+restarting, updating, or the conversation moving between machines. You should
+never have to re-send a secret because "I lost it" again. Secrets are stored
+encrypted and are deleted as soon as they're consumed.
+
+Asking me to move a conversation to a machine it's already on (or repeating
+the request) now gets a calm "already running there" instead of a confusing
+"rate-limited" error. And if my internals retry a message under load, the
+command runs once — not four times.
+
+## Summary of New Capabilities
+
+- `buildAutoloopGoal` includes a gate-compliance paragraph: intentional fail-open catches must report via DegradationReporter or carry an inline `@silent-fallback-ok` justification — never a ratchet baseline bump.
+- The mentor is instructed to spell out these gate notes in any task brief or spec it authors for another agent.
+
+- Dashboard sessions list shows every session across the pool with a machine badge per row.
+- `GET /sessions?scope=pool` → `{ sessions, pool: { peersOk, failed, ... } }` (agents can answer "what's running across my machines?").
+- `GET /sessions` sessions carry `machineId`/`machineNickname` on pooled installs.
+- CLAUDE.md template bullet + idempotent migration so existing agents learn the capability.
+
+- Create a review exchange for an artifact under a mandate, content-addressed so the
+  signatures bind to exactly the code that was reviewed.
+- Record delivery, the peer's authenticated verdict, and the owner's countersignature —
+  with both sign-offs evaluated through the mandate gate and refused on any deny.
+- Inspect exchanges and their signatures, each carrying the audit reference of the
+  gate decision that authorized it.
+- Maturity: stable engine and routes; ships inert (deny-by-default) until the operator
+  issues a mandate with the sign-code-review authority.
+
+- Secret Drop submissions persist store-first to the encrypted SecretStore and survive server churn.
+- Retrieval transparently falls back to the durable copy; consume deletes both copies.
+- `secrets.persistDrops: false` opts out (default ON).
+- Tests can never pollute the machine-global SecretStore keychain entry (structural guard).
+- `secrets.forceFileKey` pins the master-key source to the per-agent file key.
+
+- Duplicate "move to X" requests no-op as "already there" — never "rate-limited."
+- The transfer planner accepts an optional `currentPinOf` hook (pin-aware idempotency).
+- `exactlyOnceIngress` defaults ON whenever the session pool routes real traffic.
+
+## Evidence
+
+Three tiers green: `tests/unit/dashboard-sessionMachineBadge.test.ts` (8),
+`tests/unit/PostUpdateMigrator-poolSessionsVisibility.test.ts` (3),
+`tests/integration/sessions-pool-scope.test.ts` (5 — including a REAL second
+HTTP server as the peer and a dead-peer degradation case), and
+`tests/e2e/sessions-pool-scope-lifecycle.test.ts` (3 — real AgentServer,
+feature alive single-machine). tsc + lint clean.
+
+`tests/integration/secret-drop-store-first.test.ts` (5 route-level tests, both
+sides of every boundary), `tests/unit/secret-store.test.ts` (keychain
+pollution guard), `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts`
+(+3 migration tests), and the Tier-3 e2e
+`tests/e2e/secret-drop-store-first-lifecycle.test.ts` — which boots two REAL
+AgentServers on one stateDir and proves a secret submitted to process 1 is
+retrievable from process 2 after a true restart. tsc + lint clean.
+
+`tests/unit/TransferByNickname.test.ts` (+5, including the verbatim incident
+case: already-on-target inside the rate window → noop) and
+`tests/unit/seamlessnessConfig.test.ts` (+4, stage coupling both ways +
+explicit-override both ways). tsc + lint clean. Production logs
+(2026-06-05T04:20Z double pin, zero `exactly-once` lines on a live-transfer
+pool) are the incident evidence.

package/upgrades/autoloop-gate-compliance.eli16.md

@@ -0,0 +1,11 @@
+# Mentor autoloop prompt: gate-compliance line
+
+Instar has an automated "mentor loop" — a prompt that tells a developer agent how to run one cycle of dogfooding a mentee agent: check its health, assign it a real task, observe, and fix what breaks as a proper PR.
+
+That prompt already teaches the ship discipline (three test tiers, the dev gate, verify-before-claim). But it said nothing about the repo's *ratchet gates* — CI checks like no-silent-fallbacks that count known-bad patterns and fail if the count ever goes UP.
+
+We learned why that matters the hard way: a spec told the builder a helper should be "best-effort, never throws." The builder did exactly that — wrapped it in a catch that swallowed the error — and CI went red, because a swallowed catch is exactly what the no-silent-fallbacks ratchet counts. The spec's own wording invited the failure.
+
+This change adds one paragraph to the mentor-loop prompt: an intentional fail-open catch must either report the failure (through DegradationReporter) or carry an inline `@silent-fallback-ok` justification — and you never bump a ratchet baseline just to get CI green. It also tells the mentor to spell these notes out whenever it authors a task brief or spec for another agent, so the next builder doesn't get trapped by well-meaning "never throws" guidance.
+
+One prompt paragraph, three new test assertions locking it in. No behavior change anywhere else.

package/upgrades/side-effects/autoloop-gate-compliance.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — Mentor autoloop gate-compliance line
+
+**Version / slug:** `autoloop-gate-compliance`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `echo second-pass checklist`
+
+## Summary of the change
+
+Adds one static paragraph to `buildAutoloopGoal()` in `src/scheduler/MentorAutonomousGuardian.ts` — the deterministic prompt assembled for the autonomous mentor dogfooding loop. The paragraph teaches ratchet-gate compliance: intentional fail-open catches must report via DegradationReporter or carry an inline `@silent-fallback-ok` justification (never a baseline bump), and task briefs/specs authored for other agents must spell these notes out explicitly. Earned from PR #792's no-silent-fallbacks CI failure, where the spec's "best-effort, never throws" guidance invited the exact swallowed catch the ratchet counts.
+
+## Decision-point inventory
+
+- `buildAutoloopGoal` — modified — one additional template line appended to the returned prompt string. Pure string assembly; no new branches, no I/O, no config.
+- `tests/unit/MentorAutonomousGuardian.test.ts` — modified — three new content assertions on the assembled prompt.
+
+## 1. Over-block
+
+None possible. The function returns a string; nothing is gated, blocked, or filtered. The added text instructs the *consuming agent*; it cannot prevent any operation by itself.
+
+## 2. Over-permit
+
+None. No permission surface is touched.
+
+## 3. Token/cost impact
+
+The prompt grows by ~430 characters, sent once per autonomous-fix guardian cycle (budget- and min-interval-gated, single-instance). Negligible.
+
+## 4. Behavior change for existing consumers
+
+The only consumer is `MentorAutonomousGuardian` → spawned loop session goal text. Existing assertions on the prompt (cycle steps, discipline line, topics) are unchanged and still pass — the new line is purely additive. The `degrades gracefully when topics are unset` test still passes (the added text contains no topic interpolation).
+
+## 5. Failure modes
+
+A string literal cannot throw at runtime. The TypeScript build verifies the template syntax. If the guidance itself were wrong, the blast radius is advisory-only (an agent following it would still produce gate-passing code — DegradationReporter and `@silent-fallback-ok` are both legitimate, documented paths in `tests/unit/no-silent-fallbacks.test.ts`).
+
+## 6. Migration parity
+
+None required: the prompt is assembled at runtime from shipped code; every agent gets it on its next update through the normal release path. No installed files, hooks, config defaults, or templates change.
+
+## 7. Rollback
+
+Revert the commit. No persisted state references the new text.

package/upgrades/side-effects/dashboard-pool-sessions.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — Dashboard pool-wide sessions (every session, every machine)
+
+**Version / slug:** `dashboard-pool-sessions`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (additive read-only aggregation + UI; no authority, no mutation; every boundary test-pinned across three tiers)
+
+## Summary of the change
+
+`GET /sessions` self-tags each session with `machineId`/`machineNickname` when
+the pool is wired, and `GET /sessions?scope=pool` aggregates every reachable
+peer's plain `/sessions` (new `resolvePeerUrls` route hook off the machine
+identity registry), tagging remote sessions with their machine + `remote:true`.
+The dashboard polls the aggregate every 15s and renders a machine badge on
+every session row; remote rows are informational (no subscribe/close). CLAUDE.md
+template + idempotent migration carry the agent awareness.
+
+## Decision-point inventory
+
+1. Pool wired vs not → self-tag vs omit fields. Both sides pinned (integration).
+2. `scope=pool` vs plain → envelope vs back-compatible array. Both pinned
+   (integration + e2e).
+3. Peer reachable vs dead → merged+tagged vs `pool.failed` entry. Both pinned
+   against a REAL second HTTP server / a dead port.
+4. Dashboard row local vs remote → interactive vs informational (click, close,
+   active highlight, row key namespace). All pinned (unit).
+5. Migration: section-present-without-marker / marker-present / no-section.
+   All three pinned.
+
+## 1. Over-block
+
+Nothing rejected. The plain route's shape and fields are unchanged for
+existing callers (additive fields only). `scope=pool` is opt-in.
+
+## 2. Under-block
+
+- Remote sessions are view-only — no remote kill or terminal streaming (named
+  non-goals; the tooltip routes the user to the owning machine's dashboard).
+- The aggregate trusts each peer's self-report; a peer that lies about its
+  sessions is already inside the trust boundary (same authToken).
+- The 15s poll means a remote session can be up to ~15s stale — acceptable for
+  a visibility surface; local sessions remain real-time via the WebSocket.
+
+## 3. Level-of-abstraction fit
+
+Aggregation lives in the one route that owns session listing, reusing each
+peer's EXISTING plain route (no new peer surface, no recursion — peers are
+fetched without `scope`). Peer discovery (`resolvePeerUrls`) is wired in
+`server.ts` from the same identity-registry source the lease/marker transports
+already use. The dashboard keeps the WebSocket as the live local feed and
+layers the poll on top — remote state is kept in a separate array precisely
+because the WS replaces the local one each broadcast.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No authority added anywhere: read-only aggregation, fail-soft per peer
+(`failed` entries, never a 500), best-effort dashboard poll (a failed tick
+retries next interval).
+
+## 5. Interactions
+
+- Cross-machine fetch uses the established Bearer-authToken pattern
+  (placement-proxy precedent) with a 5s `AbortSignal.timeout` so a hung peer
+  can't pin the route.
+- No recursion: the aggregate always fetches peers' PLAIN `/sessions`.
+- The WebSocket session feed is untouched; local rows merely inherit the self
+  nickname at render time from the poll response.
+- tmux-name collisions across machines are handled by namespacing remote row
+  keys (`remote:<machineId>:<tmux>`).
+
+## 6. External surfaces
+
+One query param on an existing authed route; one optional RouteContext hook;
+dashboard HTML/JS; CLAUDE.md template bullet + idempotent migration. No config,
+no notifications, no new files on disk.
+
+## 7. Rollback cost
+
+Trivial — revert the PR. The plain route shape is unchanged, so nothing else
+depends on the new fields; no state, no schema, no migration side effects
+beyond an extra CLAUDE.md bullet (inert text).
+
+## Conclusion
+
+Additive, read-only, fail-soft visibility feature at the minimal scope that
+satisfies the operator requirement verbatim: every session shows on the
+dashboard, and every row states its machine.
+
+## Second-pass review (if required)
+
+Not required — see header.
+
+## Evidence pointers
+
+- `tests/unit/dashboard-sessionMachineBadge.test.ts` (8) — UI contract.
+- `tests/unit/PostUpdateMigrator-poolSessionsVisibility.test.ts` (3) — parity.
+- `tests/integration/sessions-pool-scope.test.ts` (5) — route contract incl. a
+  REAL peer server + dead-peer degradation.
+- `tests/e2e/sessions-pool-scope-lifecycle.test.ts` (3) — feature-alive on the
+  production init path.
+- `docs/specs/dashboard-pool-sessions.md` + `.eli16.md`.

package/upgrades/side-effects/review-exchange-protocol.md

@@ -0,0 +1,60 @@
+# Side-effects review — ReviewExchange protocol (coordination-mandate spec §7, G2.3)
+
+Spec: `docs/specs/coordination-mandate.md` (approved by Justin, A/A/B, 2026-06-05) — §7
+names G2.3: "autonomous code-review protocol over Threadline, gated by the
+`sign-code-review` authority". Change: new `src/coordination/ReviewExchange.ts` engine +
+six `/review-exchange*` routes wired through the existing coordination block in
+`AgentServer` → `RouteContext`.
+
+## 1. Blast radius
+
+Additive only. No existing route, gate, store, or sentinel is modified. The engine rides
+the EXISTING MandateGate — it adds no new authority kind, no new signing key, and no new
+trust root. Inert by inheritance: with no mandate issued (the universal state at deploy),
+every sign-off path refuses 403, so shipping this changes NO behavior until the operator
+issues a mandate AND an agent drives an exchange.
+
+## 2. State / data
+
+One new file under the `.instar/state/` convention, created on first use:
+`review-exchanges.json` (the exchange records). No schema migration; an absent file is an
+empty list. Audit entries land in the EXISTING `mandate-audit.jsonl` hash chain (the gate
+records them; this engine only stores the returned entry hashes).
+
+## 3. Security model
+
+- **No new authorization surface.** Both sign-offs (peer approve + owner countersign) are
+  evaluated through the same MandateGate (`sign-code-review` authority): named party,
+  bounds, expiry, revocation — every decision audited. A deny refuses the state
+  transition; the route surfaces it as 403 with the gate's reason (gate-deny precedence
+  over not-found, so deny-by-default cannot masquerade as a 404).
+- **requester ≠ authorizer preserved.** The exchange routes are Bearer-gated (no PIN by
+  design): creating/recording an exchange delegates nothing — the GATE is what authorizes
+  sign-offs, and the gate's authority comes only from the PIN-issued mandate.
+- **Peer asymmetry stated, not hidden.** The peer's instance may not run this engine, so
+  the peer's signature is their authenticated Threadline verdict message recorded BY
+  REFERENCE (`kind: 'authenticated-peer-verdict'`, evidence = the message ref). The gate
+  still evaluates the peer's fingerprint identically. The caller is responsible for only
+  recording verdicts that actually arrived over the authenticated relay — the same trust
+  the existing A2A surface already places in the relay's sender authentication.
+- **Content addressing.** `packageSha256` is fixed at creation and has no update path; a
+  changed package is a different exchange. `request-changes` is terminal — rework
+  restarts as a new exchange, so a stale approval can never be replayed onto new code.
+- **Kill switch reaches the protocol.** Revoking the mandate mid-exchange blocks every
+  subsequent sign-off (tested at unit + e2e tiers).
+
+## 4. Failure modes
+
+- Engine init failure → `coordination` stays null → all routes 503 (deny-safe, no boot
+  block; same try/catch as the mandate engine).
+- Torn/absent state file → empty list (`@silent-fallback-ok` annotated).
+- A gate deny mid-protocol leaves the exchange in its prior state (no partial advance) —
+  asserted by tests on both deny paths.
+
+## 5. Test coverage
+
+11 unit + 7 integration + 4 e2e (22 total): both sides of every decision boundary —
+creation validation, linear-order enforcement, gate-deny on both sign-offs,
+deny-by-default with no mandate, named-party refusals (stranger AND wrong-party), bounds
+mismatch, request-changes terminality, revocation mid-exchange, audit-hash wiring
+integrity on the production boot path, 503 when unavailable.

package/upgrades/side-effects/secret-drop-store-first.md

@@ -0,0 +1,117 @@
+# Side-Effects Review — Secret Drop store-first durable persistence
+
+**Version / slug:** `secret-drop-store-first`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (single decision boundary, both sides test-pinned; operator-mandated incident fix)
+
+## Summary of the change
+
+A submitted Secret Drop is persisted store-first to the durable AES-256-GCM
+encrypted SecretStore (`secretDrops.<token>`) the instant it is received, the
+retrieve route transparently falls back to that copy when the in-memory one is
+gone, and a successful consume deletes both. Opt out with
+`secrets.persistDrops: false` (absence = enabled). Plus a structural
+test-environment guard in `MasterKeyManager`: any VITEST/NODE_ENV=test run is
+forced to file-key mode so no test can overwrite the machine-global keychain
+entry (the failure the first run of this PR's own test caused live on
+2026-06-05, remediated same hour).
+
+## Decision-point inventory
+
+1. `persistDrops !== false` — persist on submit / fall back on retrieve / clean
+   on consume vs pre-existing in-memory-only behavior. Both sides covered in
+   `secret-drop-store-first.test.ts`.
+2. `consume` true/false against the durable copy — delete vs preserve. Both
+   sides covered.
+3. `inTestRun` in `MasterKeyManager` — file-key forced vs production keychain
+   resolution. Test side pinned in `secret-store.test.ts`; production side is
+   the unchanged existing behavior.
+
+## 1. Over-block
+
+Nothing is rejected. Submission, retrieval, and consume flows accept exactly
+what they accepted before. A durable-persist FAILURE never blocks the
+submission (best-effort + loud ERROR log) — the user's drop always succeeds if
+the in-memory submit succeeded.
+
+## 2. Under-block
+
+- A secret submitted while `persistDrops:false` still has the original churn
+  exposure — explicit operator opt-out, documented.
+- The durable copy does not yet sync cross-machine (Phase 4) — a drop made on
+  the laptop is durable on the laptop only.
+- The broader key-coherence disease (machine-global keychain account, no
+  key-id header, silent-empty on decrypt failure) is NOT fixed here — filed as
+  a follow-up finding; this PR only makes tests structurally unable to trigger
+  it.
+
+## 3. Level-of-abstraction fit
+
+The persist lives in the submit route directly after the in-memory `submit()`
+succeeds — the single place a submission is born. The fallback lives in the
+one retrieve route the hardened helper uses. No new routes, no SecretDrop
+class changes, no helper changes. The test guard lives in the
+`MasterKeyManager` constructor — the single chokepoint every key resolution
+passes through (Structure > Willpower: per-test `forceFileKey` conventions
+would rot).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority added. Persist is best-effort (loud log, never 500s);
+fallback only widens what retrieval can find; the test guard constrains TESTS
+only, never production resolution.
+
+## 5. Interactions
+
+- The 15-min in-memory TTL/idle cleanup still runs; after cleanup the durable
+  copy now serves the retrieve instead of a 404 — that is the fix working.
+- `onStuckConsumer` notify-only hardening unchanged.
+- The Telegram confirm + agent nudge fire AFTER the persist, so by the time
+  the agent is told "retrieve me," the durable copy already exists.
+- `secret-drop-retrieve.mjs` needs no changes — it talks to the same route.
+- SecretStore `set()` is read-modify-write; a decrypt failure throws BEFORE
+  any write, so the persist path cannot clobber an existing store it cannot
+  read (verified against the live 2026-06-05 key-split incident).
+
+## 6. External surfaces
+
+No new HTTP routes. One new config block (`secrets.persistDrops`,
+`secrets.forceFileKey` — both optional, absence = current defaults). CLAUDE.md
+template Security bullet rewritten + idempotent PostUpdateMigrator migration
+for existing agents. One new encrypted-at-rest artifact class:
+`secretDrops.<token>` entries inside the existing vault file.
+
+## 7. Rollback cost
+
+Low. `secrets.persistDrops: false` is an instant behavioral rollback without a
+deploy. Full revert restores in-memory-only semantics; any `secretDrops.*`
+entries already in vaults are inert data deletable via `SecretStore.delete`.
+No schema, no irreversible op.
+
+## Conclusion
+
+Operator-mandated incident fix at the minimal coherent scope: one persist
+call, one fallback branch, one cleanup branch, one structural test guard.
+Every decision boundary has both sides pinned by tests; the failure it fixes
+was reproduced live twice during the build (auto-update restart ate a 1h
+token; test run split the vault keys).
+
+## Second-pass review (if required)
+
+Not required — see header. The riskiest element (writing secrets to disk) is
+the operator's explicit instruction, encrypted with the pre-existing vault
+machinery, and consume-cleaned.
+
+## Evidence pointers
+
+- `tests/integration/secret-drop-store-first.test.ts` — 5 route-level tests.
+- `tests/unit/secret-store.test.ts` — keychain pollution guard.
+- `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` — 3
+  migration tests (rewrite, idempotency, fresh-inject wording).
+- `docs/specs/secret-drop-store-first.md` + `.eli16.md` — spec + overview.
+- Live remediation evidence: vault backup at
+  `/tmp/config.secrets.enc.backup-1780635105`; keychain entry cdat
+  `2026-06-05T04:46:39Z` matched the test run start `04:46:38`.

package/upgrades/side-effects/transfer-idempotency-exactly-once.md

@@ -0,0 +1,105 @@
+# Side-Effects Review — Transfer idempotency + exactly-once-when-live
+
+**Version / slug:** `transfer-idempotency-exactly-once`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (pure-planner reorder + config-resolution default; every boundary side test-pinned)
+
+## Summary of the change
+
+1. `planTransferByNickname`: the already-satisfied checks (`owner === target`,
+   NEW `pin === target` via optional `currentPinOf`) now run BEFORE the rate
+   limit, so a duplicate of an already-satisfied move plans `noop` ("already
+   there") instead of `reject/rate-limited`. The consumer wires `currentPinOf`
+   from `TopicPlacementPinStore` and words the `already-on-target` noop as
+   "already running on X — nothing to move."
+2. `resolveSeamlessnessConfig`: `exactlyOnceIngress` defaults ON when the
+   session pool stage is `live-transfer`/`rebalance` (a live pool without the
+   ingress dedupe ledger re-executes retried/replayed user commands — the
+   2026-06-05 4×-execution incident). Explicit values always win.
+
+## Decision-point inventory
+
+1. `owner === target` → noop vs continue. Both sides pinned (incident test +
+   transfer test).
+2. `pin === target` → noop vs continue; absent `currentPinOf` → old behavior.
+   All three pinned.
+3. Rate-limit window for a real move (different target) → still rejected.
+   Pinned.
+4. Stage-derived `exactlyOnceIngress` default: off (none/dark/shadow), on
+   (live-transfer/rebalance), explicit override both directions. All pinned.
+
+## 1. Over-block
+
+Nothing new is rejected. The planner now rejects strictly LESS (duplicates
+that previously rate-limited now noop). The exactly-once default only
+activates a gate that itself fails open (ledger errors fall through to normal
+routing, per the existing route code).
+
+## 2. Under-block
+
+- The rate limit no longer applies to same-target duplicates — deliberate:
+  re-pinning the same value is idempotent. Rapid same-target spam costs one
+  pin-store write + one "already there" reply per message; the per-topic
+  Telegram traffic itself is bounded upstream.
+- The exactly-once default does NOT retroactively enable the ledger on pools
+  still in dark/shadow — pre-live stages keep the old dark default by design.
+
+## 3. Level-of-abstraction fit
+
+The idempotency fix lives in the pure planner (the single decision function
+both the natural-language path and `POST /pool/transfer` flow through), not in
+the Telegram consumer. The exactly-once coupling lives in config RESOLUTION
+(`resolveSeamlessnessConfig`) — the one place defaults are derived — not in
+the wiring site.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No new blocking authority. The planner reorder converts rejections into
+no-ops. The exactly-once gate it activates was already authority-bearing by
+design (spec §8 G3a) and fails open on any ledger error.
+
+## 5. Interactions
+
+- `noop` consumer behavior unchanged structurally (pin set + release-if-self
+  + message): re-setting an identical pin refreshes `updatedAt`, which can
+  extend the rate window for a SUBSEQUENT different-target move by up to 10s
+  — bounded, harmless.
+- Activating `exactlyOnceIngress` on live pools also activates the
+  reply-marker transport (same flag, existing wiring) — that is the intended
+  pairing per spec §8 G3a.
+- Sentinel intercepts (emergency stop / pause) run BEFORE the ingress gate in
+  the route — unchanged; an emergency stop is never deduped away.
+
+## 6. External surfaces
+
+No new routes, no new config keys (an existing key's DEFAULT becomes
+stage-aware). One user-visible message wording improvement. No migration:
+config absence means "follow the default," which is the point.
+
+## 7. Rollback cost
+
+Trivial. `exactlyOnceIngress: false` is an instant per-agent opt-out without
+deploy; reverting the PR restores both old behaviors. No state, no schema.
+
+## Conclusion
+
+Two small, surgical changes at the correct layers, each killing one half of a
+user-facing incident: duplicates narrated as failures, and duplicates
+executing at all. Strictly less rejection, strictly more dedupe, both
+test-pinned on every side.
+
+## Second-pass review (if required)
+
+Not required — see header.
+
+## Evidence pointers
+
+- `tests/unit/TransferByNickname.test.ts` — 5 new idempotency tests (incl. the
+  verbatim incident case).
+- `tests/unit/seamlessnessConfig.test.ts` — 4 new coupling tests.
+- Production evidence: `logs/server.log` 2026-06-05T04:20:43/04:20:55 double
+  pin + zero `exactly-once` lines; topic 13481 screenshot (Moving →
+  rate-limited → Moving → rate-limited).