instar 1.3.497 → 1.3.499

package/upgrades/1.3.499.md

@@ -0,0 +1,58 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+On a multi-machine pool, two of the agent's background voices had no machine
+coordination: the 🔭 standby notices (PresenceProxy) had no machine-ownership gate at
+all — every machine could answer for the same conversation — and the ⏳ commitment
+heartbeats (PromiseBeacon) HAD a gate, but it compared against a field
+(`ownerMachineId`) that nothing ever populated, so it was silently inert on every
+deployed agent (audit findings F18/F19, MULTI-MACHINE-SEAMLESSNESS-SPEC WS3.1/3.2).
+
+This ships the one-voice layer: a shared deterministic `SpeakerElection`
+(`src/monitoring/SpeakerElection.ts`) consulted by both sentinels at their single
+emission chokepoints. The topic's owner machine speaks; unknown ownership FAILS TOWARD
+SPEECH (lease-holder, then a deterministic lowest-online-id tiebreak) so the pool is
+never silent — the failure mode the convergence review proved is worse than
+double-voice. A lease-stability dwell defers decisions during a lease flap (bounded,
+then tiebreak) and holds a chosen speaker's identity so the voice can't alternate.
+Commitments now record `ownerMachineId` at creation, the beacon re-resolves the LIVE
+owner at speak time (the stamp is only a fallback), and a PostUpdateMigrator backfill
+stamps existing open commitments on deployed agents (idempotent; skipped-not-marked
+when no machine identity exists yet).
+
+Ships DARK behind `multiMachine.seamlessness.ws3OneVoice` (default false — verdicts
+are byte-for-byte today's behavior). Single-machine agents are structurally inert at
+every layer (election never engages below 2 online machines), locked by tests.
+
+## What to Tell Your User
+
+- "When your agent runs on more than one machine, exactly one machine now speaks for
+  each conversation's background notices — no more two machines answering the same
+  question, and (just as important) never both staying silent because each assumed
+  the other had it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| One-voice gating for standby + commitment notices | Enable `multiMachine.seamlessness.ws3OneVoice` (multi-machine pools only; dark by default) |
+
+## Evidence
+
+- `tests/unit/SpeakerElection.test.ts` — 13 tests including the exactly-one-speaks
+  invariant simulated across whole pools (owner known, owner unknown, no lease-holder,
+  OFFLINE lease-holder, flapping lease with bounded defer, dwell hold) and the strict
+  legacy/no-op guards.
+- `tests/unit/ws3-one-voice-wiring.test.ts` — 11 tests: creation stamp defaults,
+  gate seams in both sentinels, one shared election wired server-side, local-only
+  ownership reads on the hot path, migration idempotency + the
+  no-identity-skips-without-marking retry path.
+- All affected suites green (PromiseBeacon ×3, PresenceProxy ×5, CommitmentTracker ×2,
+  beacon integration ×3); `tsc --noEmit` clean; full build green.
+- Side-effects artifact: `upgrades/side-effects/multi-machine-seamlessness-ws3.md`
+  (second-pass review: required and recorded in the artifact).
+- Spec: `docs/specs/MULTI-MACHINE-SEAMLESSNESS-SPEC.md` (converged + approved, on main).

package/upgrades/side-effects/multi-machine-posture-review-dimension.md

@@ -0,0 +1,76 @@
+# Side-Effects Review — Multi-machine posture review dimension (Cross-Machine Coherence widening)
+
+**Trigger:** operator question, 2026-06-12 topic 13481 ("we have developed so many
+features that have gaps … is it the constitution or our enforcement?"). The audit
+answer: both, but chiefly enforcement — NO review surface ever asked the multi-machine
+question, so ~20 features shipped machine-blind.
+**Change:** (1) side-effects template gains mandatory §7 "Multi-machine posture"
+(replicated / proxied-on-read / machine-local-by-design-with-reason; single-machine
+assumption is a finding, not a posture); (2) the matching Phase-4 question in the
+instar-dev SKILL; (3) a mandatory posture check in spec-converge's
+integration/deployment reviewer charter; (4) the Cross-Machine Coherence article's
+"Applied through" widened to name these gates (so the conformance audit can verify
+them); (5) PostUpdateMigrator migration delivering the updated skill content to
+deployed agents (Migration Parity, "updating existing skill content" — pattern copy of
+migrateSpecConvergeFoundationAudit: marker-sniffed, fingerprint-guarded, idempotent,
+customized files untouched).
+
+## 1. Over-block
+The new review question blocks nothing programmatically — it is a required SECTION in
+a review document and a reviewer charter line. The cost it adds is one honest
+paragraph per change. A genuinely machine-agnostic change answers "machine-local by
+design: <reason>" in one line. No legitimate change becomes unshippable.
+
+## 2. Under-block
+The question is willpower-adjacent until the conformance audit verifies the section's
+presence (the registry now names the gates, which is what the Standards Enforcement
+Coverage audit reads). A reviewer can still write a lazy posture answer — the
+spec-converge integration reviewer's charter makes a silent single-machine assumption
+a MATERIAL finding, which is the structural counterweight. Programmatic
+section-presence checking in the pre-commit gate is a natural ratchet if lazy answers
+show up (the registry text gives it a home).
+
+## 3. Level-of-abstraction fit
+Right layer: the defect was a missing QUESTION at review time, so the fix adds the
+question to both review surfaces (side-effects + spec-converge) and anchors it in the
+constitution article those surfaces trace to. Not duplicated logic — one rule, named
+in the registry, asked at the two existing chokepoints.
+
+## 4. Signal vs authority compliance
+No new blocking authority. The template/charter additions are review-content
+requirements; the only "block" is the existing spec-converge materiality bar, which is
+already the convergence mechanism. The migration is a content patch with no decision
+logic.
+
+## 5. Interactions
+- The migration follows the established skill-content-update pattern and runs once
+  (marker check). It cannot fight installBuiltinSkills (which never overwrites).
+- Renumbering Rollback cost §7→§8 in the template: existing committed artifacts are
+  unaffected (the pre-commit gate checks artifact existence/coverage, not section
+  numbering).
+- The spec-converge charter addition extends the integration reviewer's prompt
+  composition; no phase logic changes.
+
+## 6. External surfaces
+None outside the install base. Deployed agents receive updated skill files on their
+next update via the migration; operator-customized files are left untouched and
+reported in the migration result.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**machine-local BY DESIGN, with reason** — these are agent-installed skill/template
+files: each machine's install legitimately carries its own copy at its own installed
+version, kept current per machine by PostUpdateMigrator on that machine's update
+cycle. Version skew between machines is bounded by the existing update train (drift
+promoter). No user-facing notices, no durable runtime state, no generated URLs.
+(This section is itself the new question, answered — dogfooded on its own PR.)
+
+## 8. Rollback cost
+Revert the template/SKILL/registry edits and ship; the migration is marker-gated so a
+reverted bundle simply stops patching (already-patched agents keep the question — a
+benign residue: it asks reviewers for one honest paragraph). No data, no config, no
+runtime behavior.
+
+## Second-pass review
+Not required — no block/allow decisions, no session lifecycle, no
+gate/sentinel/watchdog runtime surface (docs/skills content + a content-patch
+migration following an established pattern).

package/upgrades/side-effects/multi-machine-seamlessness-ws3.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — WS3.1/WS3.2 one-voice gates (SpeakerElection)
+
+**Spec:** docs/specs/MULTI-MACHINE-SEAMLESSNESS-SPEC.md (converged 2026-06-12, approved; merged to main in PR #1083)
+**Change:** new `src/monitoring/SpeakerElection.ts` (deterministic speaker election with
+lease-stability dwell); PresenceProxy gate at its single send chokepoint (closes F18 —
+it had NO machine gate); PromiseBeacon gate upgraded to live owner re-resolution with
+the commitment stamp as fallback (closes F19); CommitmentTracker stamps
+`ownerMachineId` at creation (defaulting to originMachineId); PostUpdateMigrator
+backfills existing open commitments; dark config flag
+`multiMachine.seamlessness.ws3OneVoice` (default false) + `ws3DwellMs`.
+
+## 1. Over-block — what legitimate emissions could this wrongly silence?
+
+The known hazard (round-1 adversarial finding, addressed in the converged spec): a
+gate keyed on "am I the owner?" can conclude "no" on EVERY machine and silence the
+pool. The election is built against that direction of error:
+- Unknown ownership NEVER yields pool-wide silence: lease-holder speaks; no/offline
+  lease-holder → deterministic lowest-online-id tiebreak; flapping lease → bounded
+  defer then tiebreak. The exactly-one-speaks invariant test asserts ≥1 as well as ≤1,
+  including under a flapping lease.
+- Every guard failure (flag off, no machine id, pool < 2, deps unbound during the
+  boot window) returns "speak" — fail toward speech.
+- PromiseBeacon's silent verdicts RE-ARM the commitment (schedule), never drop it; the
+  owning machine's beacon carries the heartbeat.
+Residual over-block: a STALE local placement view could say "owner is the other
+machine" while that machine is dead — its election (not running) can't speak, ours
+stays silent for that topic until placement converges. Mitigation: ownership records
+key the election only when status is 'active'; a dead machine's records converge via
+the existing failover path, and PresenceProxy's cadence re-evaluates each tick.
+Accepted as bounded-by-failover; noted for the WS1.3 reconcile build which shortens
+exactly this window. Second residual (independent reviewer finding): a held silent
+verdict can outlive the chosen speaker's departure for up to one dwell window
+(default 60s) plus one cadence tick on a doubly-degraded path (speaker offline
+mid-dwell + unknown ownership + no online lease-holder) — bounded, self-healing
+(re-election after dwell expiry), and no emission is dropped (both consumers re-arm).
+
+## 2. Under-block — what double-voice does this still miss?
+
+- Both gates only cover PresenceProxy + PromiseBeacon (the F18/F19 surfaces named in
+  the spec). Other notice paths (rate-limit sentinel, recovery notices — F23/WS3.3)
+  are explicitly a separate spec item with episode-key dedup; not silently claimed.
+- The ≥1/≤1 invariant holds when machines agree on the replicated inputs. During a
+  partition with divergent placement views, two machines can transiently both believe
+  they own a topic and both speak — the same exposure as today (no regression), fully
+  closed only by the WS1 epoch-fenced reconcile family.
+
+## 3. Level-of-abstraction fit
+
+One shared deterministic module consumed by both sentinels at their existing
+chokepoints — not two bespoke gates (the F18 finding showed exactly how per-sentinel
+divergence happens). The election reads only local replicated state (ownership
+registry, capacity registry, lease status) — never a mesh call on the emission path
+(spec hot-path rule). The dwell lives in the module so every consumer inherits it.
+
+## 4. Signal vs authority compliance
+
+The election holds NARROW authority: it gates WHO SPEAKS a duplicate-prone sentinel
+notice — never recovery actions, never message content, never anything user-initiated
+(spec "Decision points touched": WS3 gates sentinel SPEECH only). Its logic is
+deterministic over replicated state (not brittle pattern-matching), it fails open to
+"speak" on every uncertainty, ships dark, and every verdict is observable (onVerdict
+hook → server log; P7). This is the blocking-authority shape the converged spec
+explicitly reviewed and approved across three rounds.
+
+## 5. Interactions
+
+- The per-topic proxy mutex (PromiseBeacon/PresenceProxy double-post guard, spec A10)
+  is untouched and still applies AFTER the election — the two compose (election picks
+  the machine, mutex serializes emitters within it).
+- PromiseBeacon's legacy static gate remains for election-absent construction
+  (back-compat for tests/embedders); the election branch supersedes it when wired.
+- The CommitmentTracker stamp default cannot collide with cross-machine commitment
+  sync (P1.5): originMachineId was already recorded; ownerMachineId now mirrors it at
+  creation and remains mutable via the existing CAS mutate path.
+- The migration touches state/commitments.json directly at update time (server down/
+  pre-boot — same pattern as every other PostUpdateMigrator state migration); it
+  stamps only missing fields on 'pending' records.
+
+## 6. External surfaces
+
+None new. No routes, no message formats, no cross-machine wire changes. The flag is
+config-local. Single-machine agents: structurally inert (no SpeakerElection
+engagement below 2 online machines; CommitmentTracker stamp is absent without an
+originMachineId — both tested).
+
+## 7. Rollback cost
+
+Flag-flip: `multiMachine.seamlessness.ws3OneVoice: false` (the default) restores
+legacy verdicts instantly at the next decision — no restart-ordering hazard since the
+flag is read live per decision. The backfilled ownerMachineId stamps are inert data
+when the flag is off (the legacy gate only acts when currentMachineId is ALSO set,
+i.e. multi-machine pools) and are correct-by-construction on single-machine agents;
+no data rollback needed.
+
+## Second-pass review
+
+REQUIRED (sentinel surface). Reviewer response appended below.
+
+<!-- second-pass reviewer response appended below by the independent reviewer -->
+
+---
+
+## Second-pass reviewer response (independent subagent, 2026-06-12)
+
+Concur with the review
+
+1. **Fail-toward-speech verified on every uncertain path.** Both consumer gates skip the send ONLY when `!verdict.speak` (PromiseBeacon.ts:360, PresenceProxy.ts:1847), and `SpeakerElection.decideInner` returns `speak:true` on every legacy/no-op/ambiguous branch: flag-off (`legacy-disabled`), no machine id, pool<2 (`single-machine`), owner-self, stamp-self, lease-holder-self, and the deterministic `tiebreak-lowest-id` whenever the lease holder is null or offline. The guards are ordered legacy/no-op FIRST, so none of the election machinery runs when disabled. The boot-window no-op is real: `poolMachineIds()` returns `[]` until `ws3PoolDeps` binds, yielding `single-machine`/speak. The flag is read live (`() => ws3Cfg().ws3OneVoice === true`) so the rollback flip takes effect at the next decision with no restart — artifact §7 is accurate.
+
+2. **Silent verdicts re-arm, never drop.** PromiseBeacon calls `this.schedule(c)` on a non-speak verdict, which re-arms at the commitment cadence (default 10min, 1s floor — no busy-loop); PresenceProxy logs and returns, and its own cadence re-evaluates. No emission is lost on a silent/defer verdict. The legacy static gate is preserved for election-absent construction as the artifact §5 claims.
+
+3. **Migration direction-of-error is safe and idempotent.** `migrateCommitmentOwnerBackfill` stamps ONLY `status==='pending'` records lacking `ownerMachineId`, with THIS machine's own identity.json machineId — and crucially, when no identity exists it skips WITHOUT writing the marker, so it retries on a later update rather than permanently no-op'ing. The stamp is only a fallback; live placement re-resolution at speak time means a stale backfilled stamp racing a transfer cannot wedge the gate (live owner beats stamp; tested). The single-machine no-op is genuinely byte-identical: no `originMachineId` → `ownerMachineId` stays absent (tested).
+
+4. **No authority beyond sentinel speech; cannot gate recovery/delivery/user flows.** The election is consumed at exactly two chokepoints — `PresenceProxy.sendProxyMessage` and `PromiseBeacon.fire` — both of which emit duplicate-prone 🔭/heartbeat notices. It is injected as an optional dep; it touches no recovery action, no message content, no user-initiated path, and `resolveTopicOwner` reads only local replicated state with no mesh/fetch call on the hot path (asserted by test). The `onVerdict` hook is try/catch-swallowed so observability can never gate. I agree with the artifact's "no issue identified" answers in §3–§6.
+
+5. **Bounded memory; ≤1 invariant holds.** The `held` map is opportunistically swept past the dwell window at size>512 and `unstableSince` entries are deleted on every decisive path — no unbounded growth. Two machines cannot BOTH speak for a topic under agreed replicated inputs: live owner is single-valued, the stamp comparison is to one id, and the tiebreak picks one `sort()[0]`. (Divergent-placement double-voice during a partition is correctly scoped to WS1 and disclosed as no-regression in §2.)
+
+**One verification note for the record (bounded, not a blocker):** the speaker-identity dwell can HOLD a silent verdict, and the held branch returns it irrespective of current pool state. If the chosen speaker machine drops offline mid-dwell while ownership is unknown AND there is no online lease holder AND the remaining pool is still ≥2, the surviving machines can each return a fresh held-silent verdict, producing a transient ALL-silent window for that topic. This does NOT violate the spec's ≥1 framing ("never pool-wide / never unbounded silence"): it is bounded by `dwellMs` (default 60s) plus one cadence tick, it self-heals (after dwell expiry the new lowest-id re-elects to `tiebreak-lowest-id` and speaks), no emission is dropped (both consumers re-arm), and the `single-machine` guard correctly rescues the pool-of-1 case by firing before the dwell check. It is strictly no worse in outcome than the partition exposure already disclosed in §2, and the gate holds no authority beyond speech — an acceptable residual on a doubly-degraded path, not a defect. Recorded in §1's residual list.
+
+## Addendum — no-silent-fallbacks ratchet (CI round 1)
+
+The three new fail-open guards in server.ts (identity read, pool-ids read, ownership
+read) tripped the repo-wide silent-fallback ratchet (466 > 463). Each now carries the
+sanctioned `@silent-fallback-ok` exemption with its reason inline: every one degrades
+to the election's designed fail-toward-speech/no-op verdict — the documented safe
+direction, not a silent loss. Ratchet count restored to baseline.