instar 1.3.247 → 1.3.248

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.247",
+  "version": "1.3.248",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T20:50:10.151Z",
-  "instarVersion": "1.3.247",
+  "generatedAt": "2026-06-04T21:08:49.274Z",
+  "instarVersion": "1.3.248",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

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/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.