instar 1.3.269 → 1.3.271

package/upgrades/side-effects/coordination-mandate-enforcement.md

@@ -0,0 +1,86 @@
+# Side-effects review — Coordination Mandate enforcement (spec §4, G2.2)
+
+Spec: `docs/specs/coordination-mandate.md` (approved by Justin, A/A/B, 2026-06-05).
+Change: new `src/coordination/` module (types, MandateStore, MandateGate, MandateAudit,
+ConditionsRegistry) + six `/mandate*` routes wired through `AgentServer` → `RouteContext`.
+
+## 1. Blast radius
+Additive only. No existing route, gate, sentinel, or store is modified. The engine is
+**deny-by-default and inert**: with no mandate issued (the universal state at deploy),
+every `/mandate/evaluate` call denies — so shipping this changes NO behavior anywhere
+until the operator issues the first mandate through the PIN-gated route. It never
+weakens an existing safety check; it adds a controlled delegation surface beside them.
+
+## 2. State / data
+Two new files under the `.instar/state/` convention, created on first use:
+`coordination-mandates.json` (the signed mandates) and `mandate-audit.jsonl`
+(append-only, hash-chained). No schema migration; absent files mean an empty store and
+an empty audit. Torn-trailing-line tolerant reads.
+
+## 3. Security model (the load-bearing dimension)
+- **requester ≠ authorizer preserved:** the human-authored mandate is the authorizer.
+  The agent's Bearer token CANNOT issue or revoke — `/mandate/issue` and
+  `/mandate/:id/revoke` require the operator's dashboard PIN (sha256 + timingSafeEqual +
+  per-IP attempt limiting, mirroring `/dashboard/unlock`). Tested at all three tiers.
+- **Authorship proof (T1/T2):** HMAC over the canonical authored bytes (key-order-stable
+  serialization), produced only at issuance. A forged or widened mandate fails
+  `verifyAuthorship` → the gate denies. `revoked` is excluded from the proof so the
+  kill switch works post-issuance; revocation is checked on every evaluation (T5).
+- **Conditions (T7/T10):** objective resolvers from real state; an unregistered or
+  throwing resolver evaluates FALSE (deny-safe). The first mandate (per decision 3B)
+  carries no conditioned authority; `integrity-gate-pass` and `parity-zero-divergence`
+  are registered deny-safe stubs until the real state is wired for a future cutover
+  authority — which per decision 1A is not delegated anyway.
+- **Audit (T3/T8):** every decision (allow AND deny) appends a hash-chained entry;
+  `verifyChain()` detects any edit/deletion and is surfaced on `GET /mandate/audit`.
+- **Stated trust boundary (T12):** an attacker with local disk write access could edit
+  server-managed state — the same trust root as today; the proof stops forged AUTHORED
+  content, and the audit chain makes tamper detectable. Out of scope per the spec.
+
+## 4. Failure modes
+- No `stateDir` → engine is null → all `/mandate*` routes 503 (tested).
+- Engine init failure → own try/catch, never cascades to other inits.
+- Malformed issuance body → 400 with a specific reason (agents pair, non-empty
+  authorities, future expiry — each tested both sides).
+- No `dashboardPin` configured → issuance/revocation 503 (PIN auth unavailable) — the
+  gate cannot be bypassed by the PIN simply being absent.
+
+## 5. Interactions
+- `RouteContext` gains a required `coordination` field; the only production assembler
+  (`AgentServer`) is updated. Route tests use partial `ctx: any` → unaffected (tsc green).
+- Express route-order hazard handled: `/mandate/audit` and `/mandate/evaluate` are
+  registered BEFORE `/mandate/:id` (tested explicitly).
+- No locks, queues, LLM calls, or budgets shared with other components.
+
+## 6. Performance
+O(mandates) reads of a small JSON file per evaluation + one appendFileSync per decision.
+Evaluation volume is a handful of A2A actions per migration step — negligible.
+
+## 7. Migration parity
+No `.claude/settings.json` hook, config default, or hook-script change → no
+`PostUpdateMigrator` entry needed. Server-side code activates on the next server start
+after update. Agent-Awareness satisfied: CLAUDE.md template gains a Coordination
+Mandate blurb (`generateClaudeMd`). The feature is inert-by-default everywhere (deny
+without a mandate), so fleet exposure is zero until an operator issues one.
+
+## Tests
+- Unit (`tests/unit/coordination-mandate.test.ts`, 17): authorship valid/forged/widened,
+  revoke-preserves-proof, canonical key-order stability, audit chain intact/tampered,
+  conditions (true/false/unknown/compound/throwing), the gate's FULL deny ladder
+  (missing, forged, expired, revoked, non-party, unlisted action, out-of-bounds params,
+  unmet condition) + both allow paths, bounds helper both sides.
+- Integration (`tests/integration/mandate-routes.test.ts`, 9): PIN-less issue refused,
+  wrong PIN refused, issue/list/evaluate/revoke round-trip, deny-by-default audited,
+  route order, validation 400s, 503s.
+- E2E (`tests/e2e/coordination-mandate-lifecycle.test.ts`, 5): real AgentServer boot,
+  alive + Bearer-gated, deny-by-default on fresh boot, full PIN-issue→allow→deny→
+  revoke→deny lifecycle with chain-verified audit, and the production-HMAC
+  wiring-integrity proof (persisted authProof verifies; a widened mandate fails).
+
+## Post-review amendment (same PR, pre-merge)
+
+- **Discoverability:** the `/mandate` prefix is classified in `CapabilityIndex.ts`
+  (CAPABILITY_INDEX → surfaced in `/capabilities` with all six endpoints + the
+  evaluate-before-acting + PIN-gating semantics), satisfying the
+  capabilities-discoverability gate. Agents discover the gate; they still cannot
+  issue through it.

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/feedback-phase3-monitor.md

@@ -0,0 +1,37 @@
+# Side effects — Phase-3 parity monitor + cutover gate
+
+## New files (additive only)
+- `src/feedback-factory/monitor/parityMonitor.ts` — `ParityMonitor` (records passes, tracks
+  the zero-divergence streak, exposes the `gate()` cutover signal) + `DEFAULT_GATE_POLICY`.
+- `tests/unit/feedback-factory/parity-monitor.test.ts` (9 tests).
+
+## Runtime impact
+- **None at boot / on the live server.** Not imported by `server.ts`, any route, job, or
+  hook. No new endpoint, no config key, no `PostUpdateMigrator` entry. No new dependency
+  (pure logic over the existing `ParityResult` type).
+
+## Behavioral guarantees
+- `gate()` clears ONLY when all four conditions hold: ≥ requiredCleanPasses consecutive clean
+  passes, clean window ≥ minWindowMs of real time, ≥ minClustersObserved clusters across the
+  streak, and zero divergence in the streak. Any divergent pass resets the streak.
+- The monitor never mutates anything and never triggers cutover itself — it only computes a
+  cleared/blocked verdict that a downstream executor reads.
+- Conservative failure mode: an over-strict policy keeps the gate BLOCKED longer (cutover
+  waits); it can never clear early.
+
+## Reversibility
+- Fully reversible: delete `monitor/parityMonitor.ts` + its test. Nothing references it yet.
+
+## Follow-on wiring (not in this PR)
+- The Coordination Mandate condition registry (G2.2) maps `parity-zero-divergence` →
+  `monitor.gate(now).cleared`. The Phase-4 cutover executor (G2.4) consults it before the flip.
+- A durable wrapper (persist passes to JSONL so the window survives a restart) + a read-only
+  `/parity/status` route land with the cutover-executor wiring.
+
+## Durability (added)
+- `parityMonitorStore.ts` — `DurableParityMonitor` + `JsonlPassPersistence`. The zero-divergence
+  window spans HOURS; without persistence a restart silently resets the streak. Passes are
+  appended to an append-only JSONL and reloaded on construction, so the window survives a
+  restart. Torn final line (crash mid-append) is skipped on reload, never corrupting the prior
+  window. Injectable `PassPersistence` keeps the logic unit-testable without disk. Still not
+  wired into the running server (the cutover executor constructs it with the live path).

package/upgrades/side-effects/feedback-phase4-integrity.md

@@ -0,0 +1,35 @@
+# Side effects — Phase-4 feedback-migration integrity tooling
+
+## New files (additive only)
+- `src/feedback-factory/migration/immutableGuard.ts` — `GuardedFeedbackStore` decorator +
+  `isClusterImmutable` / `hasGovernanceNotes` invariants.
+- `src/feedback-factory/migration/importIntegrity.ts` — pure import-gate core (checksums,
+  fingerprint-uniqueness scan, schema-equivalence, referential integrity, sequence reset,
+  `runIntegrityGate`).
+- `tests/unit/feedback-factory/immutable-guard.test.ts` (15 tests).
+- `tests/unit/feedback-factory/import-integrity.test.ts` (21 tests).
+
+## Runtime impact
+- **None at boot / on the live server.** These modules are NOT imported by `server.ts`, any
+  route, job, or hook. They are library building blocks the Phase-4 cutover execution will
+  call. No new endpoint, no new config key, no migration to `PostUpdateMigrator`.
+- No new dependencies (uses `node:crypto` only).
+
+## Behavioral guarantees
+- `GuardedFeedbackStore` only ever REFUSES a mutation of an immutable cluster (pre-cutover
+  createdAt or non-null governance note) and records a `GuardViolation`; it never alters
+  data and passes all reads + non-curated writes straight through to the inner store.
+- A failing `onViolation` audit sink can never break the store or surface as a mutation
+  (try/caught, annotated `@silent-fallback-ok`).
+- Checksums collapse null/undefined/"" so the import gate does not flap on the
+  null-vs-empty governance-note distinction (that distinction is asserted separately by
+  schema-equivalence).
+
+## Reversibility
+- Fully reversible: delete the two `migration/` files + their tests. Nothing else
+  references them yet.
+
+## Follow-on wiring (not in this PR)
+- Phase-4 cutover executor (G2.4) constructs the `GuardedFeedbackStore` around the real
+  Prisma-backed store with the cutover timestamp from config, and runs `runIntegrityGate`
+  over the export/import pair as the Phase-2 gate.

package/upgrades/side-effects/respawn-build-context-reestablishment.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Respawn build-context re-establishment
+
+**Version / slug:** `respawn-build-context-reestablishment`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `instar-codey second-pass checklist`
+
+## Summary of the change
+
+This change hardens the interactive SessionManager respawn path for developer build sessions. A new sidecar store records each running session's live tmux pane working directory, using the generic state layer's temp-file-plus-rename atomic write. When a resumed interactive session has a fresh saved cwd under an agent worktree, SessionManager prepends a `[BUILD-CONTEXT RESTORE]` continuation note to the resumed message. Normal home-only sessions, stale records, missing worktrees, and non-enabled agents receive no note.
+
+The feature is dark by default for normal agents. Server boot resolves the session-level feature flag as an explicit override if present, otherwise the standard development-agent gate.
+
+## Decision-point inventory
+
+- `SessionBuildContextStore` — add — owns sidecar state validation, crash-safe persistence through StateManager, cwd eligibility, staleness, missing-path checks, branch enrichment, and restore-note formatting.
+- `SessionManager.monitorTick` — modified — records pane cwd after liveness is confirmed, without changing session lifecycle decisions.
+- `SessionManager.spawnInteractiveSession` — modified — prepends a restore note only for resume spawns with an eligible saved worktree context.
+- `server` startup wiring — modified — resolves the feature dark by default and live for development agents unless explicitly overridden.
+- Session-management e2e — modified — proves a real tmux pane under a fixture worktree gets the restore note while a home-only control stays unchanged.
+
+## 1. Over-block
+
+The restore can skip a legitimate build context if the tmux cwd is not under a `.worktrees` path. That is intentional. The spec's blast-radius guard is more important than restoring every possible hand-navigated directory. Agents can still recover manually from conversation context; the automated note is limited to the known build-worktree convention.
+
+The restore can also skip when the sidecar is stale or the worktree directory was removed. That prevents a respawn from sending the agent back into a deleted or long-finished checkout.
+
+## 2. Under-block
+
+The sidecar records cwd for running sessions when the feature is enabled, including home-only sessions. Home-only records are not eligible for restore, so this is additional local state but not additional behavior. The record contains local paths and an optional branch name; it does not include prompt content or credentials.
+
+The branch name is best-effort enrichment. If Git cannot read the branch, the restore note still works with the worktree path alone. Failure to read branch never blocks monitoring or respawn.
+
+## 3. Level-of-abstraction fit
+
+SessionManager owns tmux lifecycle, liveness checks, interactive respawn, and initial-message injection, so it is the correct place to sample pane cwd and prepend the resume note. The sidecar store keeps persistence and eligibility logic out of the large SessionManager class and makes the boundary unit-testable.
+
+The change does not force tmux to spawn inside the worktree. That matches the design spec: the session home remains stable, and the resumed agent receives deterministic instruction to return to the build checkout only when appropriate.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Not applicable to conversational/product judgment — this is structural session lifecycle restoration.
+
+The cwd sample is a mechanical tmux fact. The restore decision is a deterministic filesystem/scope guard: fresh, existing, different from spawn cwd, and under a worktree path. It does not judge user intent or message meaning.
+
+## 5. Interactions
+
+- **Shadowing:** The restore note is prepended before the normal initial-message injection. Existing InputGuard and injection mechanics still handle the resulting message through the same path.
+- **Double-fire:** The note is computed once per resumed spawn. Reusing an already-live tmux session does not inject a restore note.
+- **Races:** A worktree can be removed between sidecar read and agent acting on the note. The respawn path checks existence immediately before injecting; after that, the note is advisory and the agent can report if the path disappears.
+- **Feedback loops:** Monitoring persists only when cwd changes, avoiding a write every tick for steady sessions.
+
+## 6. External surfaces
+
+The visible behavior is a new continuation preamble for eligible resumed developer sessions. The preamble is intentionally plain text and starts with `[BUILD-CONTEXT RESTORE]` so the agent can act on it deterministically. Normal topic sessions that remain in agent home see no new text.
+
+The persistent surface is a local sidecar state record keyed by tmux session name. It stores spawn cwd, current cwd, optional branch, and update time.
+
+## 7. Rollback cost
+
+Rollback is a code revert of the sidecar store, SessionManager wiring, server gate wiring, tests, and artifacts. The sidecar state file can remain harmlessly on disk; without the code path it is ignored. No migration or state repair is required.
+
+## Conclusion
+
+The change addresses the respawn amnesia failure without changing normal spawn cwd, without broadening behavior for home-only sessions, and without relying on conversation memory to rediscover the checkout. The test set covers pure eligibility/staleness behavior, mocked tracker-to-respawn wiring, and a real tmux e2e with both worktree and home-only controls.
+
+## Second-pass review
+
+**Reviewer:** `instar-codey separate pass`
+**Independent read of the artifact:** concur
+
+The risky surface is SessionManager. The implementation keeps the new behavior behind a feature gate, samples only after liveness is confirmed, writes through crash-safe state persistence, and injects only a continuation note for eligible resumed spawns. The scope guard is the core safety property and is covered in all three test tiers.
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/session-build-context-store.test.ts tests/integration/session-build-context-respawn.test.ts` passed.
+- `npm test -- --run tests/e2e/session-management-e2e.test.ts -t "restores a worktree build context"` passed.
+- `npm test -- --run tests/unit/no-silent-fallbacks.test.ts tests/unit/session-build-context-store.test.ts` passed after marking best-effort branch enrichment as an intentional fail-open.
+- `npm run lint` passed.

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