instar 1.3.511 → 1.3.513

package/upgrades/1.3.513.md

@@ -0,0 +1,61 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- **Learned preferences replicate across your machines.** A preference the
+  Correction & Preference Learning loop captures on machine A (e.g. "lead with the
+  action, no preamble") is now honored on machine B. New `preferences-sync` mesh verb
+  (read/observe class, any registered same-operator peer), riding the existing
+  authenticated MeshRpc envelope and the PeerPresencePuller cadence exactly like
+  `commitments-sync`.
+- **Serve side** — `buildPreferencesSyncPage`: seq-windowed delta pages
+  (`lastMutatedSeq > sinceSeq`, exclusive cursor, byte-capped), incarnation-fenced
+  (a restored/rewound store re-mints its incarnation so peers re-pull wholesale), and
+  the free-text `learning` is credential-shape-redacted at serve time. The local-only
+  `violationPattern` (the user's self-violation detection regex) is NEVER replicated.
+- **Receive side** — `PreferenceReplicaStore`: one single-writer file per peer,
+  first-hop sender-binding (a row claiming a third machine is rejected + counted),
+  corrupt→quarantine+re-pull, per-peer bound (default 500).
+- **Merged read** — `GET /preferences/session-context?` collapses own + replicas by
+  `dedupeKey` (the same lesson seen on two machines is ONE row): newest `recordedAt`
+  wins the fields, `dedupeCount` sums across machines. A grossly-future timestamp
+  (beyond a 24h skew tolerance) is treated as untrustworthy and loses, so a
+  clock-skewed peer can't silently override your real preferences.
+- Ships **DARK** behind `multiMachine.seamlessness.ws21PreferencesPool` (default
+  false). Single-machine / flag-off = byte-identical to today (own-only). CLAUDE.md
+  template + idempotent PostUpdateMigrator bullet so deployed agents learn it.
+
+## What to Tell Your User
+
+When you run the agent on more than one computer, the little things it learns about
+how you like to work now follow you to every machine — you don't have to re-teach it
+on each one. It's careful about it: a machine with a wrong clock can't hijack your
+preferences, the agent's own private detection rules never leave the machine they're
+on, and if the same lesson was learned in two places you see it once, not twice. Off
+by default; a single-machine setup is completely unaffected.
+
+## Summary of New Capabilities
+
+- Cross-machine replication of learned preferences (`preferences-sync` mesh verb).
+- `GET /preferences/session-context` returns the merged pooled view when the pool flag
+  is on, each lesson de-duplicated across machines with a clock-skew-resistant winner.
+
+## Evidence
+
+- `tests/unit/PreferencesSync.test.ts` (18) — serve fence/delta/byte-cap/redaction,
+  receive forged-row/incarnation/quarantine/per-peer-bound, merge collapse-by-dedupeKey
+  + dedupeCount-sum + recency, and the security-review fixes (violationPattern never
+  replicated; future-skewed peer loses; legit-newer peer still wins).
+- `tests/unit/PreferencesManager-replication.test.ts` (6) — seq machinery, advert,
+  highWaterSeq rewind detection, legacy-store seeding, end-to-end getAllForSync→serve.
+- `tests/unit/ws21-preferences-pool-wiring.test.ts` (11) — serve handler registered,
+  puller drives, flag default, MeshRpc verb+RBAC, the flag-gated union over the live
+  route (off→own-only; on+replicas→merged `scope:mesh`; on+no-replicas→own-only), and
+  the real-`meshSelfId` guard.
+- `tests/integration/preferences-sync-roundtrip.test.ts` (3) — real signed MeshRpc
+  round-trip: paged delta, dedupeKey-collapse, mixed-version 501.
+- 72 WS2.1 tests green; `pnpm build` clean. Reviewed by a 4-dimension adversarial
+  Workflow (16 agents) — 7 confirmed findings fixed before ship.

package/upgrades/side-effects/green-pr-automerge-enforcement.md

@@ -0,0 +1,171 @@
+# Side-Effects Review — Green-PR Auto-Merge Enforcement (Phase 7 becomes machinery)
+
+**Version / slug:** `green-pr-automerge-enforcement`
+**Date:** `2026-06-12`
+**Author:** `echo`
+**Second-pass reviewer:** `green-pr-automerge-secondpass subagent (high-risk: merge authority + gate + watcher)`
+
+## Summary of the change
+
+A background watcher (`GreenPrAutoMerger`) that merges a green, mergeable, non-held PR
+this agent authored — so the merge survives session death (the prose "Phase 7" rule died
+with the session that read it; this is machinery). It rides on a hardened
+`scripts/safe-merge.mjs` (the act-time re-verifier), a pool-visible kill-switch
+(`GuardLatchStore` on a new replicated `guard-latch` coherence-journal kind), a per-PR
+failure ladder + circuit breaker, an identity contract, a floor-drift canary, and a Layer-2
+session-exit nudge. Off fleet-wide (`DARK_GATE_EXCLUSIONS: deliberate-fleet-default`),
+flipped on per dev agent with `expectedGhLogin`, repo-gated to an instar checkout with
+`scripts/safe-merge.mjs` present. Spec: `docs/specs/green-pr-automerge-enforcement.md`
+(converged round 7, approved). New modules: `src/monitoring/{GreenPrAutoMerger,MergeRunner,
+GuardLatchStore,greenPrLogic,floorDriftCanary,greenPrAutomergeWiring}.ts`; `guard-latch` kind
+in `CoherenceJournal.ts` + `JournalSyncApplier.ts`; Layer-2 helpers in `stopGate.ts`; six
+routes in `routes.ts`; boot wiring in `commands/server.ts`; config/registry/migration in
+`ConfigDefaults.ts`, `devGatedFeatures.ts`, `guardManifest.ts`, `PostUpdateMigrator.ts`,
+`types.ts`.
+
+## Decision-point inventory
+
+- `GreenPrAutoMerger.tick` candidate gate — **add** — decides which PRs are merge-eligible
+  (namespace + hold + mergeable + settled-green + protected-paths). Fail-toward-skip.
+- `GuardLatchStore.isMergeAllowed` (dual-latch gate) — **add** — rollback + emergency-pause
+  must BOTH be open; unreadable peers → arrive-disabled.
+- `safe-merge` required-contexts cross-check — **add** — producer-bound floor; refuses on any
+  unverifiable/missing/wrong-producer context.
+- Layer-2 `greenPrBlock` (stop-gate hot path) — **add** — blocks a session ending with a
+  green unmerged PR on its branch, ONCE, mode-independently. No runnable command in any variant.
+- The existing stop-gate router hook — **modify** — gains a mode-independent greenPrBlock
+  branch before the `mode === 'off'` early return (always-overwritten by migrateHooks).
+
+## Over-block — legitimate inputs this rejects that it shouldn't
+
+- A genuinely-green PR whose required-contexts cannot be FETCHED (gh/API hiccup) is refused
+  (`refused:contexts-unverifiable`) rather than merged. Intended: fail-toward-skip. The PR
+  stays open; the next tick retries; the hold-age backstop surfaces it if it rots.
+- A PR whose CI floor was renamed out-of-band is refused until the floor-drift canary names
+  the drift. Intended over-block (a drifted floor must not be merged around).
+- A PR touching protected paths is never auto-merged even when green — routed to the operator.
+  Intended (those PRs can mint hollow floor contexts; human eyes required).
+
+## Under-block — failure modes this still misses
+
+- **Stale-base merges (Decision 9, ratified):** `--admin` bypasses the up-to-date-branch
+  requirement, so a PR tested against an older `main` can merge an untested integration.
+  Bounded: textual conflicts never merge (`mergeable == MERGEABLE`), `main` re-runs full CI
+  after every merge (Zero-Failure makes breakage owned + the audit names the merge), and this
+  relocates the EXISTING manual-merge residual unchanged. A strict-base-freshness mode is on
+  the fleet-promotion checklist.
+- **Branch namespace is a filter, not provenance (Decision 8):** anyone holding the shared gh
+  credential can name a branch `echo/…`; the floor's producer-bound CI contexts are what make
+  a candidate "pre-approved by construction."
+- **Multi-machine peer-latch READ is single-machine in this PR:** `readPeerLatches: () => []`.
+  Outbound replication (the journal emit) works; the merged peer READ surface is a follow-up.
+  Honest consequence: on a multi-machine pool a rollback set on machine A replicates outbound
+  but machine B does not yet MERGE A's latch into its gate. The durable local file is the
+  authoritative gate per-machine, and the lease serializes the ACT — so two machines never
+  both merge — but a cross-machine STOP is not yet honored on the non-originating holder. This
+  is disclosed; the dev agent runs effectively single-machine for merge authority today.
+
+## Level-of-abstraction fit
+
+Correct layer: a monitoring watcher (the ReleaseReadinessSentinel precedent) that drives the
+blessed `safe-merge` wrapper. The watcher holds NO independent merge path and never trusts
+safe-merge's exit code (independent `gh pr view` confirm, B10). The kill-switch rides the
+existing coherence-journal replication + fenced lease (no new distributed primitive).
+
+## Signal vs authority compliance
+
+The watcher is Tier-0: the ONLY discretionary classification is hold/candidate status, and its
+failure direction is fail-toward-skip (audited), never fail-toward-merge. Everything that
+decides "is this change good" already happened upstream (spec process + gates + CI); safe-merge
+re-verifies at act time. The Layer-2 `greenPrBlock` blocks ONCE on objective replicated state
+(green candidate + exact branch match + staleness gate + armed gate) and fails open on every
+error — it does not repeat the brittle-substring-with-blocking-authority pattern of the
+stated-continuation guard it sits beside (that foundation tension is recorded in the spec, not
+inherited).
+
+## Interactions
+
+- Shares the stop-gate hot-path response with the UnjustifiedStopGate; greenPrBlock is computed
+  LAZILY (only when the snapshot has candidates) and is mode-independent, so it does not depend
+  on the UnjustifiedStopGate mode (which ships `off`).
+- Adds a journal kind: the `guard-latch` kind is closed-schema in both the writer
+  (`CoherenceJournal`) and the receiver (`JournalSyncApplier`) — a peer's forged guard-latch
+  entry is schema-rejected like any other kind.
+- One aggregated attention item with a machine-stable id (`green-pr-automerge:aggregate`) — does
+  NOT create per-PR topics (the notification-flood burst-invariant bound).
+
+## External surfaces
+
+- Merges PRs on GitHub (the one durable external side-effect — ratified at the approval gate;
+  the operator-token admin merge already happened manually via the same script since June 9).
+- Six new HTTP routes (`/green-pr-automerge*`); `/enable` + `/pool-disarm` are dashboard-PIN
+  gated (operator authority), `/rollback` + `/hold` + `/tick` are Bearer.
+- Reporter hook payload gains `cwd` (always-overwritten template; free fleet-wide).
+
+## Multi-machine posture (Cross-Machine Coherence)
+
+| Surface | Posture | Why |
+|---|---|---|
+| `state/green-pr-automerge.json` | machine-local BY DESIGN | attempt ledger; the ACT is lease-serialized |
+| `state/green-pr-automerge-latches.json` | machine-local authoritative + journal-replicated | durable STOP survives restart; emit replicates outbound |
+| `guard-latch` journal kind | pool-replicated (outbound) | a STOP/marker propagates to peers |
+| peer-latch READ (merged gate) | single-machine in this PR (follow-up) | disclosed under-block above |
+| Layer-2 snapshot | machine-local (holder only) | sessions on a non-holder get no belt; Layer 1 on the holder is the guarantee |
+| Aggregated attention id | machine-stable | lease makes dual-raise impractical; stable id makes it harmless |
+
+## Rollback cost
+
+- Runtime: `POST /green-pr-automerge/rollback` (Bearer, anyone can STOP) disarms instantly;
+  `dryRun: true` and `enabled: false` are config levers. Fleet default is off regardless.
+- Code: revert the PR. No data migration — the new state files are additive and machine-local;
+  the new `guard-latch` journal kind is additive (readers ignore unknown kinds). The hook
+  template changes are always-overwritten, so a revert restores the prior templates on the next
+  migration.
+
+## Tests
+
+- Unit (123 new): safe-merge hardening (27), guard-latch store (13), pure logic (31),
+  orchestrator (14), merge runner (12), floor-drift (9), Layer-2 helpers (11), + the journal
+  suites pass with the new kind (35).
+- Integration (6): the routes over the real HTTP pipeline — 503 unwired → 200 wired
+  (feature-alive), rollback gate closing, PIN gating, the warm-up→merge tick flow.
+- Honest gap vs the spec's full test list: a real-AgentServer-boot E2E and a dedicated
+  chaos-interleaving integration test are NOT in this PR — the route-level integration proves
+  the feature is alive through the real `createRoutes` pipeline, and the restart/orphan and
+  latch-partition paths are covered at the unit tier (MergeRunner orphan reap; GuardLatchStore
+  absorbing/unreadable). Flagged for a follow-up E2E hardening pass.
+
+## Second-pass review
+
+**Verdict: CONCUR.** An independent reviewer audited the artifact against the code (safe-merge,
+GreenPrAutoMerger, GuardLatchStore, MergeRunner, stopGate, the boot wiring), adversarially
+hunting for a path to an unintended merge. Findings:
+- No path to an unintended merge. The act path is gated in strict order every tick
+  (lease → single-flight → dual-latch gate → breaker → warm-up → candidate → identity →
+  contract probe → live re-fetch → spawn); safe-merge is the independent act-time authority and
+  refuses on red/missing-e2e/wrong-producer-floor/head-moved/unverifiable. The empty-rollup edge
+  (`statusCheckRollup:[]` passing the cheap list filter) is caught and refused at act time by
+  safe-merge — the non-authoritative filter never causes a merge.
+- Fail direction is fail-toward-SKIP on every traced path (candidate, protected-paths-unverifiable,
+  identity unconfigured/unresolved/mismatch, gather/runner exceptions, every safe-merge error exit).
+- Identity contract enforced before acting (default `expectedGhLogin:''` → skip every act).
+- Dual-latch read every tick; unreadable peers arrive-disabled; rollback Bearer, re-arm PIN-gated.
+- B10 independent confirmation at both safe-merge and the watcher.
+- Layer-2 is signal-not-authority, fails open, no variant emits a runnable command.
+- Wiring integrity confirmed (repo-gate → 503; real deps; same latch instance backs act + Layer 2).
+- Two non-blocking observations, both fail-safe: the Layer-2 hot path hardcoded `tickIntervalMs`
+  (FIXED — now read from config) and a rollback landing mid-spawned-attempt does not abort that one
+  bounded attempt (disclosed; lease + single-flight bound it to one).
+
+## CI hardening (registry + ratchet parity)
+
+Full-suite triage surfaced four registry/parity gates, all addressed: the new `guard-latch`
+journal kind updated the `CoherenceJournal.getOwnAdvert` test enumeration; the six routes were
+registered in `CapabilityIndex` (`/capabilities` discoverability); the migrator CLAUDE.md section
+was tracked in the feature-delivery-completeness parity test (migrator-only, like Release
+Readiness); and the ~20 new fail-toward-skip `catch` blocks were annotated `@silent-fallback-ok`
+(with the dead `isFile` probe in `resolveBranchFromCwd` removed) so the no-silent-fallbacks ratchet
+stays at its baseline. Three other full-suite reds were confirmed NOT from this change
+(sharedStateRoutes passes in isolation — cross-talk; sign-instar-lockfile + the npm-pack
+packageTemplateShape fail on local signing-key / `proper-lockfile` resolution; two e2e narratives
+are pre-existing). CI's clean room is the authority.

package/upgrades/side-effects/multi-machine-seamlessness-ws21-preferences-pool.md

@@ -0,0 +1,116 @@
+# Side-Effects Review — WS2.1 preferences pool: learned preferences replicate across machines
+
+**Version / slug:** `multi-machine-seamlessness-ws21-preferences-pool`
+**Date:** `2026-06-13`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `4-dimension adversarial-review Workflow (16 agents) — security / correctness / integration / Phase-C; verdict + fixes appended below`
+**Parent principle:** Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions
+
+## Summary of the change
+
+WS2.1 of the merged MULTI-MACHINE-SEAMLESSNESS-SPEC: the correction-learning
+preference store (`PreferencesManager`, `.instar/preferences.json`) becomes
+cross-machine. A preference learned on one machine is honored on the others. The
+design mirrors the proven `commitments-sync` read-replication pattern: a new
+`preferences-sync` MeshRpc verb (read/observe class), seq-windowed incarnation-fenced
+delta serve, single-writer per-peer replica store with first-hop sender binding, and a
+flag-gated union into `GET /preferences/session-context`. Preferences are ADVISORY
+session-start signals (never authority), so this is read replication only — no
+write-back, no election, no quorum.
+
+The one genuine design fork vs. commitments (resolved): commitments union on composite
+(origin,id) with no cross-origin merge; preferences COLLAPSE by `dedupeKey` (the same
+lesson observed independently on two machines is ONE row) so the injected session
+block never double-injects the same guidance.
+
+## Decision-point inventory
+
+- Merge winner: newest `(recordedAt, originMachineId)` — HLC-light. `dedupeCount` sums
+  across distinct origins.
+- Clock-skew: a `recordedAt` beyond `now + 24h` is untrustworthy → loses (treated as
+  oldest), not clamped-to-near-now. Within tolerance → normal recency.
+- Replication scope: own records only on serve; `learning` redacted; `violationPattern`
+  stripped (local-only); per-peer record bound (default 500).
+- Gate: `multiMachine.seamlessness.ws21PreferencesPool === true` AND a resolved
+  `meshSelfId` AND replicas present → merged; else the untouched own-only path.
+
+## 1. Over-block
+None. The feature gates ADD reach (replicated preferences) and never block a message,
+a route, or a session. Flag-off / single-machine = strict no-op.
+
+## 2. Under-block (the real risk surface)
+The risk is the inverse: replicated preference TEXT is injected into the session-start
+block. Mitigations: (a) `learning` is credential-shape-redacted at serve time; (b) the
+block already wraps learned preferences as advisory, non-authoritative signals;
+(c) first-hop binding rejects forged-origin rows; (d) replicas come only from
+registered same-operator Ed25519-authenticated peers. The adversarial review probed
+prompt-injection-via-preference-text — accepted residual: a compromised same-operator
+machine could inject advisory text, but it cannot escalate to authority, and the
+blast radius is one operator's own pool. Recorded as a known bound, not a blocker.
+
+## 3. Level-of-abstraction fit
+The engine (`PreferencesSync.ts`) is pure/seam-injected (build/apply/merge are
+unit-testable with in-memory fakes). Wiring sits in server.ts/routes.ts/
+PeerPresencePuller exactly where `commitments-sync` does. No new transport, no new auth.
+
+## 4. Signal vs authority compliance
+Fully signal-only. Preferences never gate or rewrite anything; the merged view only
+changes which advisory lessons appear in the session-start block. The mesh verb is
+read/observe (adds reach, never authority); the receiver re-binds origin.
+
+## 5. Interactions
+- Rides the existing MeshRpc envelope + PeerPresencePuller cadence (no new tick).
+- Independent `coherenceJournal.preferences` config section (does NOT couple to
+  commitments' tuning — review finding #4/#7).
+- Coexists with #1095 (drain) and #1096 (attention pool) — rebased onto both; MeshRpc
+  carries `drain` + `preferences-sync` side by side.
+
+## 6. External surfaces
+`GET /preferences/session-context` gains an optional `scope:'mesh'` marker + merged
+block when the pool is on. `preferences-sync` mesh verb is internal machine-to-machine
+(authenticated). No new user-facing HTTP auth surface.
+
+## 7. Multi-machine posture (Cross-Machine Coherence) + Phase C
+- **N-machine, no 2-peer assumption:** one replica file per peer; the merge is O(total
+  records) across N peers; per-peer bound keeps the merged set bounded; the formatter is
+  byte-bounded so the session block can't blow up with N peers.
+- **No LAN assumption:** per-peer HTTP over the existing pool fabric; an offline/slow
+  peer fails that peer gracefully (the puller doesn't block the tick).
+- **Headless / cloud cold-start:** a fresh VM with no replicas pulls fully from seq 0
+  (incarnation seeded), no strand.
+- **Degraded conditions:** corrupt replica → quarantine + re-pull; rewound store
+  (restore) → incarnation re-mint → peers re-pull wholesale.
+
+## 8. Rollback cost
+Trivial: flip `ws21PreferencesPool` off (or leave default) → own-only, byte-identical
+to pre-feature. The replica files under `state/preference-replicas/` are inert when the
+flag is off. No migration of existing data; additive config + entry fields only.
+
+---
+
+## Second-pass review — 4-dimension adversarial Workflow (MANDATORY)
+
+Ran a 16-agent adversarial review (4 parallel dimension reviewers → per-finding
+skeptical verification, trust-model-aware). 12 raw findings → **7 confirmed**, ALL
+FIXED + tested before ship:
+
+1. **HIGH (security) — violationPattern replicated.** The serve `...r` spread leaked
+   the user's local-only self-violation detection regex to peers. **Fix:** explicitly
+   strip `violationPattern` from `ReplicatedPreference`. Test: served row has no
+   `violationPattern`.
+2. **HIGH (security) — clock-skew recency manipulation.** `isNewer` used raw
+   `Date.parse` with no bounds; a future-skewed peer won every collision (the spec's
+   clock-skew requirement was unshipped). **Fix:** a timestamp beyond `now + 24h` is
+   untrustworthy → loses. Tests: future peer loses; legit-newer peer still wins.
+   (Full HLC logical counters tracked as follow-up: `<!-- tracked: WS2.1 HLC counters -->`.)
+3. **HIGH (correctness) — `meshSelfId ?? 'local'` fallback.** The 'local' sentinel
+   mismatched a peer's named origin and corrupted the own-echo filter. **Fix:** the
+   merge requires a real `meshSelfId`, else own-only. Test: source-asserted guard.
+4/5/7. **MEDIUM/LOW — wrong config section.** preferences-sync read
+   `coherenceJournal.commitments` for page sizing. **Fix:** dedicated
+   `coherenceJournal.preferences` section + type; both reads repointed.
+6. **LOW — meta-sidecar ordering.** Reviewed: `writeAtomic` fsyncs the store fd and
+   renames it BEFORE writing the sidecar, so the sidecar is never ahead of the store
+   (the rewind fence can't false-trip). No change needed; documented.
+
+Post-fix: 72 WS2.1 tests green; build clean; dark-gate lint clean.