# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

**The feedback-factory migration's parity check no longer flags two systems as
"diverged" just because they spell the same status differently.** As Portal's
feedback processor is ported into Instar, the two run side-by-side and a parity
comparator confirms they reach the same conclusions before any cutover. But Portal
still writes the legacy status words (`open`, `fixed`, `resolved`) while the ported
Instar processor emits the canonical lifecycle words (`new`, `fix_applied`,
`closed`). The comparator compared those words literally, so a cluster Portal
marked `resolved` and Instar marked `closed` — the *same* outcome — was reported as
a divergence, which structurally blocks the cutover. That was benign vocabulary
skew being treated as a real history fork.

The fix adds the canonical status-normalization primitives Dawn (Portal's owner)
pinned as the authoritative contract — a legacy→canonical projection map, a
terminal-state check evaluated on the normalized status, and an idempotent
`normalizeStatus()` — and applies the projection to **both sides** before the
parity comparator comparison. A genuine lifecycle mismatch still surfaces, and the
reported values stay raw so an operator still sees each side's actual stored status.

**A moved conversation's reply no longer hangs silently when the other machine
is briefly unreachable.** When you move a conversation to another machine, that
machine relays its replies through the machine that holds the Telegram
connection. That relay had two operational defects, both found by driving the
multi-machine feature live: it had no time limit (so when the receiving machine's
connection was momentarily restarting, the reply hung for over a minute with no
result), and it failed completely silently (a dropped reply wrote nothing to the
log, so there was no way to tell why it didn't arrive).

The relay is now bounded and observable: it gives the receiving machine a fixed
window (15 seconds by default, adjustable) and then fails fast, and every failure
writes one clear line saying exactly what went wrong (no reachable machine, a
rejection with its status code, or a timeout). The relay logic was also extracted
into its own well-tested unit.

It also no longer reports a false success: previously the relay could report
"delivered" even when the message never actually reached the chat (it accepted a
response that carried no real message id). Now the receiving machine returns the
real message id and the relay only counts a reply as delivered when that id is
present — otherwise it's treated as undelivered and surfaced, so a busy or flaky
moment becomes a real, visible failure (and a retry candidate) instead of a
silent loss dressed up as success.

`GET /updates/status` now includes the `restartImmediately` field. PR #641 added
the primary-developer-mode flag and claimed it was surfaced in this endpoint, but
the route's hand-picked response object had omitted it — so the flag's live state
wasn't actually readable there. This adds the one missing line so the route
echoes the value `AutoUpdater.getStatus()` already computes.

**The pre-messaging honesty guard now recognizes your agent's other machines as
its own.** A multi-machine instar agent runs on more than one machine, each
exposed at its own subdomain under the operator's tunnel domain (for example the
laptop and the Mac Mini each get a subdomain of the same tunnel domain). The
URL-provenance check — which blocks messages containing made-up-looking links —
previously trusted only the agent's exact own tunnel host, so a legitimate
operation addressing a sibling machine of the same agent was falsely flagged as
an "unfamiliar domain" and blocked.

It now also trusts hosts that share the agent's tunnel parent domain, so sibling
nodes are recognized — while still blocking genuinely fabricated links. Two
guards keep it safe: the parent domain is derived only when the own host has at
least three labels (never trusts a bare public-suffix apex), and the match is a
true DNS-suffix test (a look-alike like echo.dawn-tunnel.dev.evil.com stays
blocked because it actually ends in evil.com). Single-machine agents are
completely unaffected.

## What to Tell Your User

Nothing to configure, and nothing changes for any current capability. This is
internal plumbing for the in-progress feedback-factory migration: the
Portal↔Instar parity check that gates cutover now reconciles the two status
vocabularies instead of failing on the difference. No routes, jobs, or user-facing
behavior are affected.

Nothing to configure. If you run across more than one machine and move a
conversation between them, a reply that can't be delivered now fails quickly with
a clear reason in the log, instead of hanging for over a minute and vanishing
without explanation. Single-machine setups are unaffected.

Nothing to do. If anyone asks how to tell whether an agent is set to always jump
to the newest version immediately, the status readout now shows that on/off state
directly.

Nothing to configure. If your agent runs across more than one machine, it can
now perform legitimate cross-machine operations (like the multi-machine reply
relay) without its own honesty guard blocking the request — while still catching
invented links. If you only run one machine, nothing changes at all.

## Summary of New Capabilities

- `normalizeStatus()` / `isTerminalStatus()` / `V1_TO_V2_STATUS` / `TERMINAL_STATUSES`
  (`src/feedback-factory/processor/transitions.ts`) — the canonical status-vocabulary
  primitives, byte-mirrored from Portal's reference (`feedback-processor.py` :1035 / :379).
  Normalize-before-terminal-check so a legacy `resolved` correctly reads terminal.
- `compareClusterOutcomes` (`src/feedback-factory/processor/parity.ts`) now normalizes
  both sides before comparing status — eliminating false cutover-blocking divergences
  from v1↔v2 vocabulary skew while still flagging real lifecycle mismatches.

- `relayOutbound` (`src/core/TelegramRelay.ts`) — the tokenless-standby reply
  relay, extracted as a pure injectable unit with a bounded `AbortController`
  timeout and a log line on every failure path. `server.ts` wires
  `telegram.outboundRelay` to it. New optional `multiMachine.relayTimeoutMs`
  (default 15000).

- `GET /updates/status` response gains a `restartImmediately` boolean (default
  false for the fleet; true for an agent in primary-developer mode). Read-only;
  agents gain it automatically on update.

- `convergence-check.sh` URL-provenance guard trusts sibling-node tunnel hosts
  (any host under the agent's tunnel parent domain), in addition to the agent's
  own host, Cloudflare quick tunnels, and the static allowlist. Deploys to
  existing agents via the standard `migrateScripts()` template path (the template
  content is the migration — no `PostUpdateMigrator` code change).

## Evidence

Reproduction: feed the parity comparator one cluster (same fingerprint) whose
outcome is expressed in the two vocabularies — Instar `closed` vs Portal `resolved`
(the same terminal outcome) — and observe the status-branch verdict before vs after
the change. Ran live against the worktree source:

```
input: { instar: "closed", portal: "resolved" }
BEFORE (raw `i.status !== p.status`):        divergent = true   ← false positive, blocks cutover
AFTER  (normalizeStatus both sides):         divergent = false  (both → "closed")
genuine mismatch (instar "investigating" vs portal "resolved"): still_flagged = true
```

So the benign vocabulary skew that previously produced a red parity verdict now
reconciles, while a real lifecycle divergence (`investigating` vs `resolved`→`closed`)
still surfaces. Confirmed across the full pair set + recurrence-not-masked + a green
`compareInvariants` verdict over a vocabulary-skewed window in
`tests/unit/feedback-factory/parity.test.ts` (156 unit + 4 integration green, `tsc` clean).

- Reproduction (live, 2026-06-01): driving the multi-machine reply proof, a
  relayed reply hung 25s then 70s with no result and no log line; root cause was
  the holder's tunnel being mid-restart, and the relay `fetch` having no timeout.
  Once the tunnel was back, the relay completed (a tone-gate response and an `ok`
  came back through the full standby→holder chain), confirming the path itself
  works — but the hang + silence were real operational defects on the way there.
- Tests: `tests/unit/telegram-relay-timeout-observability.test.ts` (7) drive the
  real `relayOutbound` with an injected fetch + logger: 2xx returns messageId and
  posts the right URL + `Bearer` header; self-hold no-ops; no-peer-URL logs;
  non-2xx logs the status; **a hanging holder aborts within the timeout (elapsed
  under 2s) and logs `timeout after Nms`**; a network error logs its message; the
  `silent` flag passes through. 7/7 green; `tsc` clean.

- The gap was observed live on 1.3.180: with the flag set true in config, the
  agent behaved correctly (restarts not deferred) but `/updates/status` returned
  no `restartImmediately` field — the #641 "surfaced in /updates/status" claim
  was incomplete.
- Test: `tests/integration/updates-status-restart-immediately-route.test.ts`
  (+2) — asserts the field is present and correct for both true and false. tsc +
  linters clean.

- Reproduction (live, 2026-06-01): proving the multi-machine reply relay, the
  command `POST https://echo-mini.dawn-tunnel.dev/telegram/reply/8882` (laptop
  driving the mini's tokenless-standby relay) was blocked by the
  `grounding-before-messaging` hook because its convergence-check URL-provenance
  guard flagged `echo-mini.dawn-tunnel.dev` as unfamiliar — it knew the laptop's
  own host `echo.dawn-tunnel.dev` but not its sibling. The mini's LAN address was
  firewalled, so the tunnel host was the only path, and the proof was blocked.
- Before/after (the guard decision, real shipped template): own host
  `echo.dawn-tunnel.dev` → parent `dawn-tunnel.dev`; sibling
  `echo-mini.dawn-tunnel.dev` BLOCK→PASS (the fix); own host PASS→PASS;
  `totally-fake-host.xyz` BLOCK→BLOCK; look-alike `echo.dawn-tunnel.dev.evil.com`
  BLOCK→BLOCK; arbitrary host with a 2-label apex config BLOCK→BLOCK (apex not
  over-trusted).
- Tests: `tests/unit/convergence-check-sibling-trust.test.ts` (6) execute the
  real shipped `convergence-check.sh`: `bash -n` valid; sibling trusted; own
  unchanged; fabricated blocked; look-alike suffix blocked; 2-label apex not
  over-trusted. 6/6 green; `tsc` clean.
