instar 1.3.18 → 1.3.19

package/upgrades/side-effects/PR-BODY-cross-machine-seamlessness.md

@@ -0,0 +1,63 @@
+# Cross-Machine Seamlessness — one agent that follows the user across machines
+
+Implements the converged + approved **Cross-Machine Seamlessness** spec
+(`docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md`), grounded in the 2026-05-26
+real-hardware Phase-0 run. Closes the gap between "a backup machine can take
+over" and "the same agent follows you across machines with no amnesia and no
+double-replies."
+
+## What this fixes (the Phase-0 findings)
+- **G2 — auto-sync never fired.** A self-electing machine changed its role but
+  nothing pushed it to git. Now `roleChange`/`leaseEpochChange` → a debounced,
+  single-writer `RegistrySyncDebouncer` push (the wiring is named + a
+  wiring-integrity test reproduces the original failure and proves it caught).
+- **G1 — split-brain.** Two machines both showed `awake`. Replaced with a
+  **fenced lease** (clock-proof, epoch-fenced CAS); `shouldSkipProcessing` gates
+  on `holdsLease()`, so a wedged old-awake is structurally fenced out. A holder
+  that can't confirm its lease over a shared medium for > leaseTtlMs
+  self-suspends (no partitioned-old-awake split-brain).
+- **G3 — the seamless channel experience.** Durable message-processing ledger
+  (no-loss / no-duplicate-reply, structural), fencing-gated outbox, encrypted-
+  live-tail buffer with sequence-dedup + secret redaction, and a HandoffSentinel
+  that yields the lease ONLY on a verified ack + passing validation (else stays
+  awake). Channel Seamlessness Contract implemented by Telegram (reference) +
+  Slack (second target).
+
+## Layers (commit-by-commit)
+1. Foundations + G2 auto-sync (types, config resolver/validator, FencedLease,
+   RegistrySyncDebouncer, registryReplayGuard, the named wiring).
+2. G1 fenced-lease leader resolution (LeaseCoordinator + GitLeaseStore + live
+   coordinator integration).
+3. G3 idempotent ledger + handoff lifecycle + adapter contract.
+4. G3 live-tail buffer + redaction + fenced outbox.
+5. Observability (`/health.multiMachine.syncStatus`) + agent awareness
+   (CLAUDE.md generate + migrate).
+6. Telegram + Slack Channel Seamlessness Contract.
+
+## Tunability, migration parity, observability
+- All §9 knobs under `.instar/config.json` → `multiMachine`, with startup
+  invariant validation (a violating config is rejected, not run silently).
+- Knobs default in code (existing agents get the feature without config bloat);
+  server code ships automatically; SQLite stores self-initialize; CLAUDE.md
+  awareness is migrated to existing agents.
+- `/health.multiMachine.syncStatus` (leaseHolder, leaseEpoch, holdsLease,
+  splitBrainState, awakeMachineCount, protocolVersion) — the Phase-1
+  feature-alive surface.
+
+## Tests
+~100 new unit tests (real Ed25519, real SQLite): lease CAS/fencing/clock-skew/
+livelock, registry replay/epoch/unknown-key guard, the Phase-0-catching push
+wiring test, message-ledger redelivery/stuck-recovery/dual-medium marker,
+fenced-outbox suppression, live-tail sequence-dedup/gap-discard, redaction,
+HandoffSentinel verify-before-yield (every abort gate), feature-alive syncStatus,
+and Telegram + Slack contract conformance.
+
+## Deliberate staging (honest)
+- The **live cross-machine handoff TRANSPORT** (server-to-server live-tail + ack
+  over the wire) and the **inbound-dispatch integration** of the ledger/outbox
+  are the validation-phase work proven by the real-hardware gate (test-as-self
+  over Telegram on two machines). The machinery is built + unit-tested here; the
+  wire integration lands with the hardware validation.
+- Onboarding/self-propagation gaps are tracked to ACT-156 (companion spec).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

package/upgrades/side-effects/cross-machine-seamlessness-g1-lease.md

@@ -0,0 +1,71 @@
+# Side-Effects Review — Cross-Machine Seamlessness: G1 fenced-lease integration
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §6 + §8 G1 (converged, approved)
+**Increment:** wire the FencedLease primitive into the live coordinator as the
+authority for awake/standby — closing the Phase-0 split-brain structurally.
+
+## What changed
+- `src/core/LeaseCoordinator.ts` (new) — drives FencedLease over a durable store
+  (+ optional tunnel): acquisition (bounded-retry CAS + livelock backoff),
+  renewal with a medium-agnostic confirmation requirement, the `holdsLease()`
+  fencing gate, epoch-advance signal, and unresolvable-split escalation. Tracks
+  `selfIssued` (the holder's freshest self-signed lease) so a renewal's new
+  expiry is honored without churning git.
+- `src/core/GitLeaseStore.ts` (new) — durable CAS over git: pull-rebase →
+  epoch-check → write → push-or-reject-reread (never force-push). `refresh()`
+  does a same-epoch durable expiry bump and declines if superseded. Bumps the
+  holder's syncSequence/authoredUnderEpoch so the lease write passes peers'
+  replay guard.
+- `src/core/GitSync.ts` — added `pullRebase()` (targeted, no auto-commit) for
+  the lease CAS. Additive.
+- `src/core/MultiMachineCoordinator.ts` — optional `leaseCoordinator`;
+  `shouldSkipProcessing()` returns `!holdsLease()` when attached (the structural
+  demotion Phase-0 lacked); `attachLeaseCoordinator` / `initializeLease` /
+  `tickLease` / `reconcileRoleToLease`; the monitor tick drives the lease when
+  attached (heartbeat retained for liveness display only).
+- `src/commands/server.ts` — constructs the lease crypto (signs with the
+  identity key whose pubkey is registered; verifies peers via the SAS-paired
+  registry), the GitLeaseStore, and the LeaseCoordinator; attaches + initializes
+  it; wires onEpochAdvance → `leaseEpochChange` (→ durable registry push).
+
+## Over-block / under-block
+- **Over-block:** `shouldSkipProcessing` now gates on `holdsLease()`. Risk: a
+  single git-backed machine that briefly can't read its own lease would skip
+  processing. Mitigated — a single machine acquires epoch 1 trivially at
+  `initializeLease()` (no peer to contend), and `holdsLease` reads its own
+  `selfIssued` lease (in-memory), not requiring git. Non-git / single-machine /
+  independent-mode meshes have NO leaseCoordinator → fall back to the existing
+  heartbeat path unchanged.
+- **Under-block:** git-only (no tunnel) means lease transfer latency is bounded
+  by git cadence, not RTT. Acceptable for the launch increment (Phase 0 proved
+  pairing works over git alone). The split-brain SAFETY is preserved via the
+  refresh-confirmation self-suspend (a partitioned holder stops within
+  leaseTtlMs). The tunnel ACCELERATOR is a tracked follow-on, not a correctness
+  gap.
+
+## Signal vs authority
+- Detectors emit signals (`checkForUnresolvableSplit`, sync-health); only the
+  lease HOLDER mutates authority-bearing state. A non-holder fails its own
+  fencing check and self-fences — no cooperative demotion needed.
+
+## Interactions
+- The lease epoch advance fires `leaseEpochChange`, which the G2 wireRegistrySync
+  already subscribes → the new epoch is pushed durably. Closed loop.
+- `reconcileRoleToLease` updates `_role` + StateManager read-only + heartbeat
+  writer to match lease holding — keeps existing role-dependent code paths
+  (scheduler `coordinator.isAwake`, etc.) coherent.
+- Heartbeat failover logic is bypassed when a lease is attached (the lease is
+  the single authority) — avoids two mechanisms fighting over role.
+
+## Rollback cost
+- Low–moderate. The lease is only active when git-backed multi-machine is
+  enabled AND construction succeeds (inside the existing try/catch). Reverting
+  the server.ts block + the coordinator's lease methods restores the
+  heartbeat-only behavior; the new modules become dead code.
+
+## Tests
+- `tests/unit/LeaseCoordinator.test.ts` (real Ed25519): acquire, presumed-dead
+  takeover, CAS contention yield, tunnel + git-only self-suspend, escalation,
+  epoch-advance signal. FencedLease/config/wiring/replay suites still green (57
+  total). Coordinator-integration + git-CAS-under-real-contention land in the
+  Tier-3 e2e + the real-hardware gate.

package/upgrades/side-effects/cross-machine-seamlessness-g2-foundation.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Cross-Machine Seamlessness: foundations + G2 auto-sync
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md (converged, approved)
+**Increment:** type/config foundations, the FencedLease primitive (logic), and G2
+automated state sync with the named wiring + pull-side replay/freshness guard.
+
+## What changed
+
+New, self-contained modules (no behavior wired into existing flows except the two named seams):
+- `src/core/seamlessnessConfig.ts` — resolve + validate the §9 tunable knobs; auto-derives
+  `standbyPullIntervalMs = min(failoverThresholdMs/4, leaseTtlMs/2)` to satisfy BOTH cross-knob
+  invariants (the bare `/4` the spec first stated violated the `< leaseTtlMs` invariant at default
+  ratios — caught by the unit test; spec table corrected to match).
+- `src/core/FencedLease.ts` — pure lease logic (epoch CAS candidate, signing/verify, fencing check
+  `holdsValidLease`, `effectiveEpoch = max(tunnel,git)`, tunnel accept guard, presumed-dead
+  acquisition, livelock backoff). Transport-agnostic; not yet wired into the coordinator (that is the
+  G1 integration step).
+- `src/core/RegistrySyncDebouncer.ts` — debounced, single-writer durable registry push + sync-health
+  signal.
+- `src/core/wireRegistrySync.ts` — the NAMED G2 wiring (coordinator roleChange/leaseEpochChange →
+  markRegistryDirty), extracted as a testable seam.
+- `src/core/registryReplayGuard.ts` — pure replay/freshness + epoch-floor + unknown-key-first-commit
+  validator.
+
+Edits to existing files:
+- `src/core/types.ts` — additive optional fields on `MachineRegistryEntry` (syncSequence,
+  authoredUnderEpoch, protocolVersion, rejoined), new `LeaseRecord`, optional `lease` on
+  `MachineRegistry`, and the seamlessness knobs on `MultiMachineConfig`. All optional → no existing
+  caller breaks.
+- `src/core/GitSync.ts` — `sync()` snapshots the registry before pull and calls a new
+  `reconcilePulledRegistry()` after a successful pull to scrub stale/unauthorized entries. Additive;
+  on any error it warns and continues (never blocks sync).
+- `src/commands/server.ts` — validates the seamlessness config at startup (rejects a violating
+  config), constructs `gitSync` for BOTH roles (so a self-electing standby can push), and wires the
+  RegistrySyncDebouncer. Stops it on shutdown.
+
+## Over-block / under-block
+- **Over-block risk:** startup config validation throws on a violating override. Mitigated: default
+  and absent configs resolve to valid values (unit-tested), so only an explicitly bad override fails —
+  which is the intended "reject, don't degrade silently" behavior (spec §9).
+- **Under-block risk:** the replay guard only runs when `registryBefore` was readable and the pull
+  changed HEAD; a first-ever pull with no prior registry simply trusts the incoming (no local baseline
+  to compare). Acceptable — signed-commit verification still applies, and the unknown-key constraint
+  still rejects an unknown machine asserting awake.
+
+## Level-of-abstraction fit
+- The durable push lives in a debouncer (coarse, registry-only), NOT in the per-tick heartbeat path —
+  honoring the ephemeral/durable split so steady-state produces ~0 commits.
+- FencedLease is pure logic with injected crypto; the transport (git/tunnel) is the coordinator's job.
+  This keeps the dangerous CAS/fencing logic unit-testable.
+
+## Signal vs. authority
+- RegistrySyncDebouncer is single-writer: it only pushes when `isAuthoritative()` (awake / lease
+  holder). A standby marking dirty is a no-op push — removes the O(N) thundering-herd.
+- The replay guard and sync-health are SIGNALS (reject an entry / flip health); the authority to act
+  on unhealthy sync (self-suspend ingress) belongs to the lease layer, wired in the G1 step.
+
+## Interactions
+- `gitSync` now constructed for standby too. It does NOT pull/push at boot unless awake (the boot
+  `sync()` stays gated on `isAwake`); construction alone has no side effects beyond signing setup.
+- `reconcilePulledRegistry` writes back a cleaned registry only when something was rejected — normal
+  pulls are untouched (no spurious writes).
+- The lease object in the registry is explicitly NOT reconciled by the guard (the FencedLease epoch
+  CAS owns it) — avoids two components fighting over the same field.
+
+## Rollback cost
+- Low. New modules are unreferenced except the two seams in server.ts/GitSync.ts. Reverting the
+  server.ts wiring + the GitSync snapshot/reconcile block restores prior behavior exactly; the new
+  files become dead code. No schema/migration shipped in this increment (config knobs are read with
+  defaults; migrateConfig lands in P4).
+
+## Tests
+- `tests/unit/FencedLease.test.ts` (real Ed25519), `seamlessnessConfig.test.ts`,
+  `registry-sync-wiring.test.ts` (incl. the Phase-0-catching "role change triggers a push" test),
+  `registryReplayGuard.test.ts`. All green. Tier-2 (real git repo) reconcile + Tier-3 land in P5.

package/upgrades/side-effects/cross-machine-seamlessness-g3-telegram-contract.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Cross-Machine Seamlessness: Telegram adapter contract impl
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §Channel Seamlessness Contract (converged, approved)
+
+## What changed
+- `src/messaging/TelegramAdapter.ts` — implements the Channel Seamlessness
+  Contract (the reference adapter):
+  - `dedupeKey(rawEvent)` → `telegram:<update_id>` (with a fallback to a
+    normalized Message's metadata.update_id).
+  - `getIngressPosition()` → `{ platform:'telegram', cursor:lastUpdateId, ... }`.
+  - `stopConsuming()` → halts the poll loop, persists the offset, returns the
+    DURABLE position (the saved offset, not the in-memory cursor).
+  - `resumeConsuming(position)` → restores the offset (never lowers it below
+    what we already know, so no replay) and restarts polling; rejects a
+    wrong-platform position.
+
+## Over-block / under-block
+- All four methods are additive (the interface declares them optional). No
+  existing TelegramAdapter behavior changes — start/stop/send/onMessage are
+  untouched. `resumeConsuming` uses `Math.max(lastUpdateId, cursor)` so it can
+  only advance the offset, never rewind into a replay.
+
+## Signal vs authority / interactions
+- These are pure adapter capabilities (where-am-I / stop / resume / identify);
+  they carry no authority. The seamless handoff path (a follow-on) calls them;
+  on their own they have no runtime effect until invoked.
+- `stopConsuming` reuses the existing `saveOffset()` (atomic-rename), so the
+  durable position is consistent with the normal poll-offset persistence.
+
+## Rollback cost
+- Minimal — removing the four methods reverts to the prior adapter exactly.
+
+## Tests
+- `tests/unit/telegram-seamless-contract.test.ts` (6): all four methods present,
+  dedupeKey stability/distinctness + metadata fallback, ingress-position shape,
+  stop→durable-position→resume round-trip (no replay), wrong-platform rejection.

package/upgrades/side-effects/cross-machine-seamlessness-g3a-ledger-handoff.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — Cross-Machine Seamlessness: G3 idempotent ledger + handoff lifecycle + adapter contract
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3a/G3e + Channel Seamlessness Contract (converged, approved)
+
+## What changed
+- `src/messaging/MessageProcessingLedger.ts` (new) — SQLite-backed
+  received→processing→reply_committed→cursor_advanced lifecycle keyed by
+  dedupeKey. Redelivery of an acted-on event is dropped; cursor advances only on
+  durable completion; stuck-`processing` entries are re-runnable; a remote
+  reply-committed marker (dual-medium) prevents a failover re-send. Deterministic
+  `computeReplyIdempotencyKey(dedupeKey, replyIndex)`. Self-initializing schema,
+  per-agent-id isolation, WAL+busy_timeout (the PendingRelayStore pattern).
+- `src/core/HandoffSentinel.ts` (new) — the planned-handoff state machine
+  (prepare→tail_synced→ingress_fenced→new_owner_active→old_owner_standby→
+  committed). Yields the lease ONLY on a verified ack (echo of tailSeq + ingress
+  position + thread-history hash) AND a passing validation; otherwise aborts and
+  stays awake. Anti-oscillation floor + a race guard (`inProgress`).
+- `src/core/types.ts` — new `IngressPosition` type and OPTIONAL Channel
+  Seamlessness Contract methods on `MessagingAdapter`
+  (getIngressPosition/stopConsuming/resumeConsuming/dedupeKey).
+
+## Over-block / under-block
+- The contract methods are OPTIONAL, so every existing adapter
+  (Telegram/Slack/WhatsApp/iMessage) compiles unchanged — no adapter is forced
+  "seamless-ready" before it implements + passes the conformance suite.
+- The ledger's `record` is INSERT OR IGNORE — a benign double-record is a no-op;
+  a genuinely new event is `firstSeen:true`. No over-block (it never refuses a
+  first-seen event).
+
+## Signal vs authority
+- The ledger is a pure substrate (records facts); it carries no authority. The
+  fencing epoch is STORED (reply_epoch) but the authority to send is the lease
+  layer's (the fencing-gated outbox, next increment).
+- HandoffSentinel encodes the authority rule structurally: no yield without
+  verified ack + validation. The validator is a Tier-1 signal; the yield is the
+  authority act, gated on it.
+
+## Interactions
+- MessageProcessingLedger is standalone (not yet wired into the inbound path —
+  that wiring + the fencing-gated outbox is the next G3 increment). No live
+  behavior changes from this commit.
+- HandoffSentinel is standalone (constructed + wired in the integration step);
+  its ops are injected, so it has no ambient dependencies.
+- `applyRemoteReplyMarker` uses COALESCE so a local commit already present is
+  never downgraded — safe under concurrent local+remote marking.
+
+## Rollback cost
+- Minimal — both new modules are unreferenced by live code in this commit; the
+  types change is purely additive (optional fields). Reverting removes the files
+  with no behavioral impact.
+
+## Tests
+- `tests/unit/MessageProcessingLedger.test.ts` (real SQLite, 10 tests): redelivery
+  dropped, cursor-only-on-completion, idempotent commit, stuck re-run, dual-medium
+  marker. `tests/unit/HandoffSentinel.test.ts` (10 tests): every abort gate proven
+  to NOT yield. 77 unit tests green overall.

package/upgrades/side-effects/cross-machine-seamlessness-g3bc-livetail-outbox.md

@@ -0,0 +1,51 @@
+# Side-Effects Review — Cross-Machine Seamlessness: live-tail buffer + redaction + fenced outbox
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §8 G3a/G3b/G3c (converged, approved)
+
+## What changed (all new, standalone modules)
+- `src/core/LiveTailBuffer.ts` — standby-side persisted tail with strict
+  sequence-dedup: applies a flush only at lastAppliedSeq+1, holds out-of-order,
+  drops duplicates, and after liveTailOutOfOrderTimeoutMs declares an unfillable
+  gap (discards held, proceeds) — bounding the holdout and preventing context
+  corruption. Per-topic byte cap (drop-oldest).
+- `src/core/liveTailRedaction.ts` — versioned (REDACTION_CATEGORY_VERSION) named
+  enum of credential categories + redactForLiveTail(); scrubs bearer tokens,
+  private-key blocks, AWS keys, JWT-like, api-keys, secret assignments before any
+  tail content leaves the machine.
+- `src/messaging/FencedOutbox.ts` — structural no-duplicate-reply at the send
+  path: sends only while holding the lease at the stamped epoch; suppresses a
+  fenced (no-lease / stale-epoch) machine's reply; idempotent via the ledger's
+  acted-on check + deterministic idempotency key.
+
+## Over-block / under-block
+- FencedOutbox SUPPRESSES on no-lease/stale-epoch — intended over-block (a fenced
+  machine must not send). Risk of under-send if `holdsLease()` is wrongly false;
+  mitigated because a single machine trivially holds its lease, and the stamped
+  epoch equals the current epoch in the normal (non-handoff) case.
+- Redaction is conservative/high-precision; over-redaction (a false positive) is
+  acceptable per spec ("false positives cheaper than a leak"). Ordinary prose is
+  left untouched (tested).
+
+## Signal vs authority
+- FencedOutbox consults the lease authority (holdsLease/currentEpoch injected) —
+  it does not itself decide authority, it enforces it at the send boundary.
+- LiveTailBuffer is a pure data structure (no authority); it only guarantees
+  context integrity on the receiving side.
+
+## Interactions
+- All three are standalone in this commit (not yet wired into the live message
+  path — that integration is the next increment). No runtime behavior changes.
+- FencedOutbox depends on MessageProcessingLedger (already shipped) — commitReply
+  is idempotent, so a double-send attempt is safe.
+- Redaction is designed to run before the (encrypted) transport; carry-by-
+  reference for large tool output (a follow-on in the transport wiring) reduces
+  the raw sensitive surface structurally beyond pattern-matching.
+
+## Rollback cost
+- Minimal — unreferenced by live code. Reverting removes the files.
+
+## Tests
+- `tests/unit/LiveTailBuffer.test.ts` (9): order, dup-drop, hold+drain,
+  gap-discard, byte cap, redaction categories. `tests/unit/FencedOutbox.test.ts`
+  (5): send, already-replied, fenced-no-lease, fenced-stale-epoch, send-failed.
+  91 unit tests green overall.

package/upgrades/side-effects/cross-machine-seamlessness-p4-awareness-observability.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — Cross-Machine Seamlessness: observability + agent awareness + migration parity
+
+**Spec:** docs/specs/CROSS-MACHINE-SEAMLESSNESS-SPEC.md §11 (converged, approved)
+
+## What changed
+- `src/core/MultiMachineCoordinator.ts` — `getSyncStatus()`: the
+  /health.multiMachine.syncStatus surface (leaseHolder, leaseEpoch, holdsLease,
+  splitBrainState, awakeMachineCount, protocolVersion). Always returns valid
+  fields (never null/throws) — the Phase-1 "feature is alive" surface.
+- `src/server/routes.ts` — RouteContext gains `coordinator`; authed `/health`
+  now includes `multiMachine: { enabled, syncStatus }`.
+- `src/server/AgentServer.ts` — threads `options.coordinator` into the route
+  context.
+- `src/scaffold/templates.ts` (`generateClaudeMd`) + `src/core/PostUpdateMigrator.ts`
+  (`migrateClaudeMd`) — a concise Cross-Machine Seamlessness awareness section
+  (one-agent-many-machines, no double-reply, compaction-pause handoff bar, honest
+  machine-provenance, where to read sync status, how to read a split-brain
+  escalation). New agents get it via generate; existing agents via the
+  content-sniffed migration.
+
+## Migration parity decision (explicit)
+- The `multiMachine` seamlessness KNOBS default safely in code
+  (`resolveSeamlessnessConfig` applies defaults for any absent key), so every
+  existing agent's server resolves valid values without a config write. I
+  DELIBERATELY did not write ~13 knobs into every agent's config.json — that is
+  noise, and functional migration parity is already achieved by the code
+  defaults + the server code shipping + the SQLite stores self-initializing +
+  the CLAUDE.md awareness migration. The dials remain user-settable under
+  `multiMachine` (documented in the awareness section). A literal config-knob
+  migration is a trivial follow-on if a reviewer wants it.
+
+## Over-block / under-block
+- `getSyncStatus` is read-only and defensive (try/catch around the registry
+  read → awakeMachineCount 0 on failure). It cannot block anything.
+- `/health.multiMachine` is only in the AUTHED branch (unchanged auth posture);
+  the unauthenticated basic health is untouched.
+
+## Signal vs authority / interactions
+- Pure observability — no authority, no mutation. RouteContext.coordinator is
+  `| null`; single-machine installs report `{ enabled:false, syncStatus:null }`
+  or the trivially-held lease. Existing route tests still pass (tolerant
+  context builders).
+- protocolVersion is reported (for partial-migration visibility); its
+  enforcement point (refusing to hand the awake lease to an old-version machine)
+  lands with the live two-machine handoff transport.
+
+## Rollback cost
+- Low. Removing the /health block + getSyncStatus + the template sections
+  reverts cleanly; the RouteContext field is additive (`| null`).
+
+## Tests
+- `tests/unit/multimachine-syncstatus.test.ts` — the feature-alive surface
+  returns valid non-null fields on a single-machine install and never throws.
+  119 unit tests green overall.

package/upgrades/side-effects/feedback-factory-dispatch.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — dispatch (guidance-out) logic (Phase 1, increment 7)
+
+**Slug:** `feedback-factory-dispatch`
+**Date:** `2026-05-27`
+**Author:** Echo (autonomous)
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The pure logic of the dispatch endpoint (the channel that sends guidance back out to agents) — type/priority vocab, semver version-compat filtering, and the create-dedup title normalization. NOT the HTTP wiring/storage (app-placement decision, blocked).
+
+## Summary of the change
+
+Ports the pure logic of `the-portal/pages/api/instar/dispatches/index.ts` into `src/feedback-factory/dispatch/dispatch.ts`: the dispatch `DISPATCH_TYPES`/`DISPATCH_PRIORITIES` vocab + validators, `parseVersion`/`isVersionGte`/`isVersionLte` (the semver comparison), `filterDispatchesForVersion` (an agent only receives a dispatch whose `[minVersion, maxVersion]` window includes its version), and `normalizeDispatchTitle` (trim + 500-char cap, used for create-dedup). **Not wired into any route yet** — no behavioral change.
+
+## Equivalence verification
+
+Reference is TypeScript, so equivalence is by faithful transcription + exhaustive both-sides-of-boundary unit tests (9): semver compare at equal/greater/lesser across all three components; the version-compat filter with min-only / max-only / both-bounds / unbounded, boundaries inclusive; unparseable version → `[0,0,0]`; title trim + 500 cap. The comparison loop, the inclusive-equal semantics, and the filter predicate are copied verbatim from the reference.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure functions, no I/O, no state, not imported by any runtime path.
+2. **Level-of-abstraction fit** — `src/feedback-factory/dispatch/` — the dispatch layer. HTTP/storage excluded (the blocked app-placement decision); this is the reusable core.
+3. **Signal vs Authority** — N/A; pure filters/validators.
+4. **Interactions** — None. New isolated module; nothing imports it yet.
+5. **Rollback cost** — Trivial: delete the module + tests.
+6. **Migration parity** — N/A. New internal library code; no agent-installed file touched.
+7. **Failure modes** — (a) Semver-compare divergence (esp. inclusive-equal + multi-component ordering) → covered by both-direction tests across all components. (b) Unparseable version handling → tested ([0,0,0] fallback matches the reference, so a garbage version is treated as 0.0.0). (c) Title-dedup divergence → trim+slice(500) transcribed + tested.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/dispatch.test.ts` — 9 tests (vocab, parseVersion, gte/lte, version-compat filter boundaries, title normalization).
+- No cross-runtime parity harness (reference is TS; equivalence by transcription + boundary tests).
+- No integration/E2E this increment: HTTP wiring/storage is the blocked app-placement decision; this logic attaches to a route when that's decided. Reasoned, documented.