instar 1.3.549 → 1.3.551

package/upgrades/side-effects/ws41-durable-ack.md

@@ -0,0 +1,37 @@
+# Side-Effects Review — WS4.1 follow-up: durable operator-bound /ack (an ack survives the owner machine being briefly offline)
+
+**Spec:** docs/specs/MULTI-MACHINE-SEAMLESSNESS-SPEC.md (review-convergence + approved:true). **Parent:** Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions.
+**Ships DARK** behind `multiMachine.seamlessness.ws41DurableAck` (default false). Single-machine / flag-off agents are a strict no-op.
+**Files:** src/core/RemoteAckStore.ts (new), src/server/routes.ts, src/config/ConfigDefaults.ts, src/core/PostUpdateMigrator.ts, src/scaffold/templates.ts, site/src/content/docs/features/multi-machine.md, site/src/content/docs/reference/api.md
+
+## What changed
+
+1. **RemoteAckStore.ts (new):** durable queue for an operator's ack/resolve of a POOLED attention item whose OWNER is briefly offline. Persists the ack INTENT — with the AUTHENTICATED operator principal that performed it — so the intent survives the owner being dark; a drain tick + a boot sweep re-deliver it when the owner returns. Append-then-compact JSONL under `logs/` (no DB dep, mirrors RemoteCloseAudit / PendingInboundStore). Idempotent on `(itemId, targetMachineId)` — a re-ack refreshes intent, never stacks duplicates. Best-effort writes: a failed append/compact logs loudly but never throws into the ack path. **The store never authorizes anything — it only remembers intent; the OWNER revalidates the carried principal at apply time.**
+2. **routes.ts (`POST /attention/:id/remote-ack`):** the operator-facing leg. When `ws41DurableAck` is off it 503s; when on, a remote-owned item's ack is persisted to the store (with the Bearer-authenticated principal) instead of evaporating against the offline owner. The receiver-side precedence guard (an owner applying a remote-ack intent on return) is gated on the same flag — a no-op when off.
+3. **ConfigDefaults.ts:** new `ws41DurableAck: false` sibling under `multiMachine.seamlessness`. Deliberately NOT named `enabled` → it is outside the dev-agent dark-gate lint by construction (no inline `enabled:` line added).
+4. **PostUpdateMigrator.ts + templates.ts:** an Attention-Queue awareness bullet — `generateClaudeMd` (new agents) + an idempotent content-sniffed `migrateClaudeMd` additive patcher (existing agents).
+5. **docs:** multi-machine.md + api.md note the route + the dark posture.
+
+## Blast radius
+
+- **Config-gated, not wiring-gated.** With `ws41DurableAck` false (the fleet default) the route 503s, the store is never constructed, and the receiver precedence guard is inert. A single-machine agent never has a remote owner, so the path is dead by topology too.
+- **No authorization surface.** The store carries the operator principal as DATA the owner revalidates at apply — it never grants anything. The Bearer auth on the route is the only authority; the durable intent is replayed THROUGH the owner's normal ack authorization, not around it.
+- **No new MeshRpc verb / no broadcast.** The intent re-delivers on the owner's existing return/boot path. N-machine-safe, no LAN assumption.
+
+## Risk + mitigation
+
+- **Risk:** a stale or forged ack intent resolves an item it shouldn't. **Mitigation:** the owner revalidates the carried authenticated principal at apply time; an intent it can't authorize is dropped. The store is idempotent on (itemId,targetMachineId), so a redelivery can't double-apply.
+- **Risk:** the store grows unbounded if an owner stays dark. **Mitigation:** append-then-compact keyed on (itemId,targetMachineId) collapses re-acks; a delivered/applied intent is compacted out. (A TTL horizon is a tracked follow-up if dark-peer accumulation proves real — CMT-1416.)
+- **Risk:** a store write error breaks the operator's ack path. **Mitigation:** every write is best-effort try/catch — a failure logs loudly (an unrecorded ack-intent deserves a trace) but the route still returns; the operator's ack is never blocked by the durability layer.
+
+## Migration parity
+
+- `ws41DurableAck: false` reaches existing agents via the generic config add-missing path (sibling under the already-migrated `multiMachine.seamlessness` block). The CLAUDE.md awareness bullet ships in `generateClaudeMd` + an idempotent content-sniffed `migrateClaudeMd` patcher. The Attention-Queue section heading is UNCHANGED → feature-delivery-completeness stays green (sub-bullet into an already-tracked section, the WS5.3/WS4.2 precedent).
+
+## Dark-gate line-map
+
+- The `ws41DurableAck` flag is NOT an inline `enabled:` line, so the attributor sees no NEW attributed path. Any cartographer line shift came from main advancing; the EXPECTED map was recomputed. Verified: `tests/unit/lint-dev-agent-dark-gate.test.ts` → 24/24 green.
+
+## Rollback
+
+- Revert the squash commit. Dark-by-default means nothing was live; no data migration, no state repair. The `logs/` JSONL (only written when an operator enabled the flag AND a remote-owned ack happened) is inert append-only data that simply stops being read.

package/upgrades/side-effects/ws52-busyness.md

@@ -0,0 +1,38 @@
+# Side-Effects Review — WS5.2 balancer busyness signal (drain-target refinement)
+
+**Version / slug:** `ws52-busyness`
+**Date:** 2026-06-13
+**Author:** echo
+**Second-pass reviewer:** not required (a pure read-only data-signal helper + thin wiring; no gate/sentinel/lifecycle/write surface; the balancer it feeds is already dry-run-gated + B3a-reviewed)
+
+## Summary of the change
+
+Resolves the tracked busyness follow-up for the autonomous balancer (Increment B). Adds a pure `computeBusynessBySlot(sessions, slotOf, defaultSlot)` to `CredentialRebalancerSnapshot.ts` — per-slot busyness = count of RUNNING claude-code sessions on each slot (a session's slot is its account's current slot via `ledger.slotOf`; an untagged session counts toward the default slot; non-running / explicit-non-claude sessions don't count). Wires it into the server's `listSlots` provider so the balancer's drain objective targets the actually-busiest slot (real signal) instead of uniform-0. Read-only; affects only the §2.4 drain TARGET selection, and only in dry-run on a dev agent (zero credential writes).
+
+## Decision-point inventory
+
+- `CredentialRebalancerPolicy` drain-target selection (objective 2) — now fed a real busyness signal instead of uniform 0. No new decision point; it sharpens an existing one (which busy slot a drain deals to). No authority change; the balancer remains dry-run-gated.
+
+---
+
+## 1. Over-block / ## 2. Under-block
+No block/allow surface. The signal only orders drain TARGET candidates; a wrong count would at worst pick a sub-optimal busy slot to drain to (still a valid eligible slot), and only in dry-run.
+
+## 3. Level-of-abstraction fit
+Correct: the busyness computation is a pure mapper in the snapshot module (alongside mapSlot/mapAccount), kept out of server.ts so a counting bug is unit-testable. The server wiring is a one-line provider change passing `state.listSessions()` + the ledger's `slotOf`.
+
+## 4. Signal vs authority compliance
+- [x] No — a read-only data-signal helper; no block/allow surface, no authority. (Ref: docs/signal-vs-authority.md.)
+
+## 5. Interactions
+- Feeds only the policy's drain `busyness` field (already consumed; previously always 0). No shadowing/race — pure, computed fresh each pass from the live session list.
+- The untagged-session-→-default-slot attribution is a deliberate choice (the default interactive session runs on the default account); documented.
+
+## 6. External surfaces
+- None directly. The balancer's `GET /credentials/rebalancer` status (and its dry-run audit) will now reflect drain decisions that target the busiest slot — observably better dogfooding signal, still zero writes (dry-run on dev; dark on fleet).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+- **Machine-local BY DESIGN.** Busyness is computed from THIS machine's live session list + THIS machine's ledger; per-machine. No cross-machine input.
+
+## 8. Rollback cost
+Trivial. Revert → the balancer falls back to uniform busyness (drain picks the first eligible busy slot). No state, no migration, no credential touch.