instar 1.3.246 → 1.3.248

package/upgrades/1.3.248.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Telegraph publishing end-to-end test (`tests/e2e/telegraph-publish.test.ts`)
+makes real calls to the live Telegraph API, which occasionally returns transient
+errors (`PAGE_SAVE_FAILED`, network blips, 5xx, rate-limit) through no fault of
+ours. Because the suite runs in the standard CI lane (it only skips when
+`SKIP_E2E=1`), one such hiccup failed the entire build on an unrelated PR — a
+Gemini quota change (#756) that touches zero Telegraph code got a red build
+purely because the Telegraph service blinked at the wrong moment.
+
+This change adds a test-local `withTransientRetry` helper wrapping the six
+live-API call sites (`ensureAccount` / `publishPage` / `editPage` /
+`getPageViews`): a transient / network / 5xx / 429 error is retried up to 4× with
+short backoff; a real failure — an assertion-worthy bug, or a persistent outage
+after retries are exhausted — still fails immediately and loudly.
+
+## What to Tell Your User
+
+Nothing user-facing — this is an internal CI-reliability fix. No shipped behavior
+changes; agent-only.
+
+## Summary of New Capabilities
+
+None — internal test-suite robustness improvement (flaky external-API e2e no
+longer fails CI on unrelated PRs).
+
+## Evidence
+
+- **Reproduction:** Codey PR #756 (a Gemini quota-state change touching zero
+  Telegraph code) got a red CI build when the live Telegraph API returned a
+  transient `PAGE_SAVE_FAILED` during the Unit-Tests node-22 shard. Confirmed via
+  `instar dev:ci-failures 756`:
+  `✗ src/publishing/TelegraphService.ts:298 Telegraph API error: PAGE_SAVE_FAILED`
+  surfacing at `tests/e2e/telegraph-publish.test.ts:102`.
+- **Before:** any transient Telegraph hiccup failed the whole build on unrelated
+  PRs — a false failure that blocks merges and sends people chasing a non-bug.
+- **After:** the six live-API calls retry transient errors up to 4×; real
+  failures still fail immediately. Verified locally: `tsc --noEmit` clean and all
+  5 e2e tests pass against the live API
+  (`npx vitest run tests/e2e/telegraph-publish.test.ts --config vitest.e2e.config.ts`
+  → `Tests 5 passed (5)`).

package/upgrades/side-effects/mm-placement-transfer-robustness.md

@@ -0,0 +1,45 @@
+# Multi-Machine Placement Observability + Reliable Transfer — Plain-English Overview
+
+> The one-line version: an agent (and a user) can now reliably ASK which machine a topic is running on and WHY, and move a topic between machines deterministically — instead of guessing from a hostname and hoping a phrase gets recognized.
+
+## The problem in one breath
+
+While testing live topic-transfer on a real laptop↔mini pair, two gaps surfaced. (1) "Move this to <a machine>" worked toward a peer but silently did nothing when moving *back* to the machine currently handling the topic — the command fell through into the session as a normal message. (2) From a standby session there was no way to read where a topic actually runs or why, so the agent inferred placement and stated a guess as fact, confusing the user.
+
+## What already exists
+
+- **Session pool routing (§L4)** — the lease-holder polls Telegram and forwards a topic's messages to the machine that owns the session; ownership lives in the SessionOwnership registry, hard pins in the TopicPlacementPinStore (a holder-local file).
+- **"move this to <nickname>" recognizer** — a deterministic recognizer over the known-machine nickname set, fed from `MachinePoolRegistry.getCapacities()`.
+- **GET /pool** — shows machines, nicknames, the lease-holder. It does NOT answer per-topic placement.
+
+## What this adds
+
+The root cause of (1): the recognizer's known-nickname set came straight from `getCapacities()`, which can omit a machine's OWN nickname. Because the lifeline forwards inbound to the holder, the relocation check runs on the very machine you're moving back to — so its own nickname being absent made "move to self" unrecognizable. The fix unions the local machine's own nickname (resolved capacities → identity entry → deterministic derive) into the recognizer set.
+
+On top of that, two new HTTP surfaces:
+
+- **GET /pool/placement?topic=N** — owner machine + nickname, the REASON (`pinned` = deliberate move vs `placed` = load-balanced vs `unowned`), and the lease-holder. Answerable from any machine: a non-holder proxies to the holder, whose pin store is authoritative.
+- **POST /pool/transfer {topic, to}** — a deterministic move that runs the SAME validated planner as the natural-language path (rate-limit, online, already-there checks), without depending on phrasing. A non-holder proxies to the holder.
+
+## The new pieces
+
+- **RelocationNicknameSet** (pure) — builds the recognizer's nickname set, unioning the self nickname. Cannot do I/O; fully unit-tested.
+- **TopicPlacementDescription** (pure) — computes the placement answer from already-resolved state + a nickname resolver. No I/O.
+- **Two routes** in the existing pool route group — read-only placement; mutating transfer. Both 503 when the pool is dark/single-machine.
+
+## The safeguards
+
+- **Reversibility / blast radius** — the recognizer change is behaviorally identical when the self nickname is already present (the common case); it only ADDS resolution when it was missing. The routes are gated: they 503 unless the pool is wired (dark by default on the fleet), so production agents are unaffected until the pool is enabled.
+- **No new authority** — the transfer route reuses the existing `planTransferByNickname` planner (same rate-limit + offline-confirm gates); it does not invent a new mutation path. Ownership release uses the existing CAS.
+- **Migration parity** — `PostUpdateMigrator` gains an idempotent block that appends the two new capability lines to agents that already have the pool section (guarded by a unique `/pool/placement` marker), and the freshly-injected section includes them for new agents. The CLAUDE.md template is updated in lockstep (Agent Awareness Standard).
+- **Tests** — Tier 1 (12 unit: both pure helpers, incl. the exact regression), Tier 2 (11 integration: both routes over HTTP incl. pinned-vs-placed, 404/409/confirm), Tier 3 (3 e2e: routes alive through the real AgentServer + auth-gated). Full `tsc --noEmit` clean.
+
+## Spec lineage
+
+This is §L4 (Session Router / placement + TopicPlacement metadata) and §L5 (Transfer orchestrator) of the approved `docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md` — surfacing observability + a deterministic lever over machinery the spec already defines. No new primitives, no new authority.
+
+## CI follow-up (same PR #750)
+
+Two CI gates flagged the additive surface; both fixed without behavior change:
+- **Docs Coverage** (`route`/`class` floors): documented the new routes + helper classes (and several related pool/mesh ones) in `site/src/content/docs/architecture/multi-machine-session-pool.md` and `features/multi-machine.md` — real feature docs the area lacked. Both floors back ≥55%.
+- **no-silent-fallbacks ratchet** (457): the proxy/best-effort `catch` blocks added by the two new routes + the self-nickname resolver are annotated `@silent-fallback-ok` with honest justifications (the proxy fallbacks are explicitly labelled in the response or surface a 502; the ownership-release catch is a best-effort optimization the pin already covers). Count back to the 457 baseline — no new genuine silent fallbacks.

package/upgrades/side-effects/telegraph-e2e-flake-tolerant.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — Telegraph e2e tolerant of transient external-API errors
+
+**Version / slug:** `telegraph-e2e-flake-tolerant`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`tests/e2e/telegraph-publish.test.ts` makes REAL calls to the public Telegraph
+API. That API intermittently returns transient errors (`PAGE_SAVE_FAILED`,
+network blips, 5xx, rate-limit) under no fault of ours. Because the suite runs
+in the standard CI lane (it only skips when `SKIP_E2E=1`), a transient hiccup
+fails the whole build on UNRELATED PRs — it just failed the Unit-Tests shard on
+Codey PR #756 (a Gemini quota change touching zero Telegraph code).
+
+The fix adds a test-local `withTransientRetry(label, fn)` helper and wraps the
+six live-API call sites (`ensureAccount` ×2, `publishPage` ×2, `editPage`,
+`getPageViews`). On a transient/network error it retries up to 4× with linear
+backoff; a non-transient error (real bug / assertion-worthy failure) throws
+immediately; if all retries are exhausted it throws (genuinely-down → fail).
+
+## Decision-point inventory
+
+One decision point: `withTransientRetry` classifies a caught error as transient
+(via the `TRANSIENT_API_ERROR` regex) or not. Transient → retry/eventually-fail;
+non-transient → rethrow immediately.
+
+## 1. Over-block
+
+**What legitimate failures does this now hide?** None that matter. The regex
+matches only transient external-service signatures (`PAGE_SAVE_FAILED`,
+`ENOTFOUND`/`ECONNRESET`/`ETIMEDOUT`/`EAI_AGAIN`, `socket hang up`,
+`fetch failed`, 5xx, 429). Assertion failures (`expect(...)`) are NOT thrown by
+the wrapped service calls, so real test-logic regressions still fail. A genuine
+persistent API outage still fails the test after the retries are exhausted.
+
+## 2. Under-block
+
+**What does it still catch?** Any non-transient error from the service (bad
+auth, a real TelegraphService bug, a 4xx other than 429) rethrows on the first
+attempt — no masking. The retry is scoped to the e2e file only; no production
+code path retries (so the publish-idempotency concern — a retry creating a
+duplicate page — is irrelevant: duplicate test pages are harmless, Telegraph
+pages are free + don't expire, and the assertions check `>= 1`, not an exact
+count).
+
+## 3. Blast radius
+
+Test-only: one file, `tests/e2e/telegraph-publish.test.ts`. No `src/` change, no
+production behavior change, no API/schema/config change. The helper is local to
+the file (not exported / not shared).
+
+## 4. Reversibility
+
+Fully reversible: revert the one file. No state, no migration, no persisted
+format. Verified locally: `tsc --noEmit` clean and all 5 e2e tests pass against
+the live API.