instar 1.3.271 → 1.3.273

package/upgrades/1.3.273.md

@@ -0,0 +1,52 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a conversation (topic) moves from one machine to another in the
+multi-machine session pool, the OLD machine's session for that topic is now
+closed automatically — previously it lingered indefinitely, doing duplicate
+work alongside the new machine's session (the operator-named duplicate-sessions
+issue).
+
+Two layers:
+
+1. **Immediate** — an explicit "move this to X" closes the local session the
+   moment the move executes (the user's command is the authority; protected
+   sessions are never auto-closed; the close is silent since the user already
+   got the "Moving…" confirmation).
+2. **Standing invariant** — the SessionReaper closes any topic-bound session
+   whose topic the ownership registry shows owned by ANOTHER machine, after a
+   2-tick (~4 min) dwell that absorbs in-progress transfers. This covers
+   failovers and automatic re-placements. The close goes through the existing
+   guarded terminate authority: a KEEP-guard veto is audited and retried, never
+   forced. Works even when the duplicate is BUSY — busy-on-a-duplicate is the
+   bug.
+
+Every close (and every refusal) lands in the reap-log with reason "topic moved
+to <machine>". Config: `monitoring.sessionReaper.topicMovedCloseout` (default
+true; inert on single-machine installs) + `topicMovedConfirmTicks` (default 2).
+
+## What to Tell Your User
+
+When you move a conversation to another machine, the machine you left now
+cleans up after itself — no more duplicate sessions quietly doing the same
+work twice. If you ever wonder where a session went, the reap-log says exactly
+why ("topic moved to Laptop").
+
+## Summary of New Capabilities
+
+- Explicit topic moves immediately close the old machine's session.
+- A reaper rule guarantees eventual closeout for failover/re-placement paths.
+- `monitoring.sessionReaper.topicMovedCloseout` / `topicMovedConfirmTicks` config.
+- Reap-log + audit rows (`rule: 'topic-moved-away'`) for full traceability.
+- CLAUDE.md template + migration so agents explain auto-closed sessions correctly.
+
+## Evidence
+
+`tests/unit/session-reaper-topic-moved.test.ts` (9 — including closing a BUSY
+duplicate, churn-resets-dwell, guard-veto-retry, dry-run, budgets, all inert
+paths) + 3 migration tests; full reaper family regression 65/65 green; tsc +
+lint clean.

package/upgrades/side-effects/cutover-readiness.md

@@ -0,0 +1,63 @@
+# Side-effects review — Cutover-readiness checker (coordination-mandate spec §7, G2.4)
+
+Spec: `docs/specs/coordination-mandate.md` (approved by Justin, A/A/B, 2026-06-05) — §7
+names G2.4 and decision 1A scopes it: everything UP TO the door, never the door. Change:
+new `src/feedback-factory/cutoverReadiness.ts` + two `/cutover-readiness*` routes + the
+REAL condition resolvers replacing the deny-safe stubs in `AgentServer`'s coordination
+block.
+
+## 1. Blast radius
+
+Additive, with ONE deliberate behavior change inside the coordination block: the
+`integrity-gate-pass` and `parity-zero-divergence` conditions were `() => false` stubs;
+they now resolve from REAL durable state (the persisted import IntegrityReport and the
+durable parity window). Until that state genuinely clears, both still evaluate false —
+identical behavior to the stubs. The first mandate (per decision 3B) has no conditioned
+authority, so nothing live consumes them yet; the change makes the future
+execute-cutover authority REAL instead of permanently-denied. No other route, gate, or
+store is modified.
+
+## 2. State / data
+
+Two new files under the `.instar/state/` convention, created on first use:
+`feedback-parity-passes.jsonl` (append-only durable parity window, torn-line tolerant —
+the merged #781 persistence) and `feedback-integrity-report.json` (the import tooling's
+persisted IntegrityReport envelope). Absent files mean blocked/not-ready (deny-safe).
+
+## 3. Security model (T7 — the assertion-proof boundary)
+
+- **No "set the condition" input exists.** The ONLY writes: (a)
+  `POST /cutover-readiness/parity-pass` TRIGGERS a server-side live fetch+compare
+  (HttpParitySource → runDryRunCompare); the request body contributes NOTHING to the
+  result (integration-tested with a hostile body asserting cleanliness). (b)
+  `recordIntegrityReport()` is called by server-side import tooling — no HTTP route
+  writes it by design.
+- **A failed live check records NOTHING** — a fetch error is absence of evidence, not
+  evidence of divergence, and it cannot extend the clean window either (unit-tested
+  both ways).
+- **Freshness bound (readiness-layer addition):** the merged gate has no max-staleness —
+  a cleared streak stays cleared forever without new passes. The readiness layer marks
+  the window STALE when the last pass is older than 6h (default) and `ready` requires
+  fresh. Stated honestly: the gate's own policy is unchanged; staleness lives here.
+- **The door is structural:** there is NO fire-cutover route (integration-tested), the
+  status carries `door: 'manual-operator-click'` machine-readably, and the agent
+  template explicitly forbids presenting `ready` as permission to flip.
+- **Token handling:** the parity source token is read lazily from the encrypted
+  SecretStore (`portal.instarReadToken` by default) at check time — never persisted in
+  config, never logged, never in a response.
+
+## 4. Failure modes
+
+- No `feedbackMigration.paritySource` config → `runParityCheck` is null → the trigger
+  route 409s with a plain reason; the readiness read surface still works.
+- SecretStore miss → the check throws → 409, nothing recorded.
+- Engine init failure → coordination block's existing try/catch → routes 503, boot
+  unaffected.
+
+## 5. Test coverage
+
+9 unit + 5 integration + 3 e2e (17 total). The load-bearing e2e: a conditioned
+execute-cutover authority DENIES on a fresh boot and flips to ALLOW only after the
+durable state genuinely clears (pre-seeded parity window + integrity report written to
+the production state path, no restart) — then re-blocks on a failed report. Conditions
+provably resolve from REAL state on the production init path.

package/upgrades/side-effects/post-transfer-session-closeout.md

@@ -0,0 +1,116 @@
+# Side-Effects Review — Post-transfer session closeout
+
+**Version / slug:** `post-transfer-session-closeout`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (kill-path change, but every kill goes through the existing terminate authority; every boundary side test-pinned; inert single-machine)
+
+## Summary of the change
+
+Two halves closing the operator-named duplicate-sessions gap: (A) the transfer
+handler immediately closes the local topic session when the user explicitly
+moves a topic to another machine (operator origin, protected-skipped, silent
+recovery-bounce disposition); (B) a SessionReaper rule closes any topic-bound
+session whose topic the ownership registry shows OWNED BY ANOTHER MACHINE,
+after a 2-tick dwell, through the guarded autonomous terminate (vetoes audited
++ retried). New `topicOwnerElsewhere` reaper dep late-binds the pool objects;
+config `monitoring.sessionReaper.topicMovedCloseout` (default true) +
+`topicMovedConfirmTicks` (default 2).
+
+## Decision-point inventory
+
+1. Plan is `transfer` to another machine vs `noop`/self → immediate close vs
+   none. Covered by the rule conditions + transfer tests from #790 (noop paths
+   unchanged).
+2. Session protected → immediate close skipped (and the sweeper's guard veto
+   path). Pinned via reaper-family protected test + the explicit skip.
+3. Topic owned elsewhere vs by-self vs unowned vs no binding vs dep absent →
+   sweeper fires vs inert. All five pinned.
+4. Dwell below/at threshold; churn reset. Pinned.
+5. killsEnabled (enabled/dryRun/auto-disabled) → terminate vs `would-reap`
+   audit. Pinned.
+6. Guard veto → `reap-skipped-topic-moved` + retry. Pinned.
+7. Per-tick + hourly budgets. Pinned (per-tick), hourly shares the existing
+   tested budget mechanism.
+
+## 1. Over-block
+
+The rule only ever closes MORE sessions, never keeps one it shouldn't — the
+risk axis is over-KILLING, addressed in Under-block. No legitimate
+operation is rejected; single-machine installs are bit-identical in behavior
+(dep absent → rule unreachable).
+
+## 2. Under-block (over-kill risk — the one that matters)
+
+- **Wrong-owner false positive:** the ownership registry is the same source
+  routing already trusts; a 2-tick dwell absorbs CAS churn mid-transfer, and
+  churn RESETS the dwell (test-pinned). Worst case (registry wrong for >2
+  ticks): the session closes while the registry routes messages to the other
+  machine anyway — the close follows the routing truth, not vice versa.
+- **In-flight work on the duplicate:** deliberately closable — duplicate work
+  is the bug (operator's words). The sweeper still honors KEEP-guard vetoes
+  (retry, not force); the immediate half is the user's explicit command.
+- **Protected sessions:** never auto-closed on either half.
+- **Half A races the release CAS:** the close is fired after the release
+  attempt regardless of CAS outcome — but only when `plan.action ===
+  'transfer'`, which already passed the planner's owner/pin checks; a failed
+  CAS still means the user commanded the move, and the pin routes the next
+  message away from this machine.
+
+## 3. Level-of-abstraction fit
+
+The immediate half lives in the one handler that executes user moves; the
+invariant lives in the reaper — the component whose job is "sessions that
+should not be running, aren't" — via an injected signal, keeping
+SessionReaper free of pool imports (fully unit-testable, same pattern as
+every other dep). The terminate authority remains the single kill funnel.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+The sweeper REQUESTS kills through the guarded authority (autonomous origin —
+vetoes win). The immediate half uses operator origin, which is the documented
+user-command bypass; the terminateSession doc comment is updated to name this
+second stamp site, and protected sessions are excluded before the call so the
+bypass never reaches them on this path.
+
+## 5. Interactions
+
+- ReapGuard/ReapAuthority untouched — same funnel, same vetoes.
+- Reap-log + §P3 notifier: sweeper closes are `terminal` (one honest "session
+  was shut down — topic moved to X" notice via the existing reapNotify);
+  Half A is `recovery-bounce` (silent — the user just got "Moving…").
+- Ownership registry is read-only here (ownerOf) — no new writers.
+- The dep's try/catch absorbs the construction-order TDZ window (reaper is
+  built before the mesh block wires the registry) — rule inert until wired.
+
+## 6. External surfaces
+
+Two config keys (defaults preserve behavior except the new closeout itself,
+which is the fix). New audit rows (`rule: 'topic-moved-away'`,
+`reap-skipped-topic-moved`). CLAUDE.md template line + idempotent append
+migration. No routes, no schema.
+
+## 7. Rollback cost
+
+`monitoring.sessionReaper.topicMovedCloseout: false` is an instant per-agent
+off-switch; full revert restores the old lingering behavior. No state.
+
+## Conclusion
+
+The operator-named duplicate-session bug closed at both speeds — instantly on
+the explicit command, eventually-but-guaranteed everywhere else — without a
+single new kill path outside the existing authority.
+
+## Second-pass review (if required)
+
+Not required — see header.
+
+## Evidence pointers
+
+- `tests/unit/session-reaper-topic-moved.test.ts` (9) — incl. the headline
+  "closes a BUSY duplicate" case.
+- `tests/unit/PostUpdateMigrator-poolSessionsVisibility.test.ts` (+3).
+- Reaper family regression 65/65 green; tsc clean.
+- `docs/specs/post-transfer-session-closeout.md` + `.eli16.md`.