@theappagency/valinor 9.2.0 → 9.5.0

package/README.md

@@ -18,7 +18,14 @@ The launcher is **trivial by design** and contains no Valinor functionality itse
    version runs **fully offline** with no network I/O;
 4. executes the cached CLI, passing through all arguments and the exit code.
 
-No npm registry auth, no `.npmrc`, no tokens, no secrets — `npx` it anywhere, including CI.
+No npm registry auth, no `.npmrc`, no tokens, no secrets — `npx` it anywhere, including CI. It runs on
+Node 22 or later, so a GitHub runner's default Node works without a `setup-node` step.
+
+A download that fails for a transient reason (a dropped connection, a stalled transfer, a timeout, or an
+HTTP 408, 425, 429 or 5xx) is retried with jittered backoff: 3 attempts per file within a 2-minute budget by default. A 404
+and a checksum mismatch are never retried. When `review-trigger-run` still cannot be fetched after the
+retries, the launcher prints a warning and exits 0: the verb posts nothing when it cannot run, and the next
+wake-up or the hourly sweep evaluates the PR again. Every other command exits 1.
 **The launcher sends no telemetry.** Its only network activity is fetching the artifact above.
 
 ## Environment variables
@@ -28,7 +35,10 @@ No npm registry auth, no `.npmrc`, no tokens, no secrets — `npx` it anywhere,
 | `VALINOR_VERSION` | Run a specific version or dist-tag (e.g. `3.1.0`, `latest`), overriding the launcher's own pinned version. |
 | `VALINOR_DOWNLOADS_URL` | Override the downloads endpoint base URL (staging/fixtures). |
 | `VALINOR_CACHE_DIR` | Override the cache location (default `~/.valinor/cache`). |
-| `VALINOR_FETCH_TIMEOUT_MS` | Per-request fetch timeout in milliseconds (default `30000`) — a silent/blackholed endpoint aborts here rather than hanging. |
+| `VALINOR_FETCH_TIMEOUT_MS` | Per-attempt timeout in milliseconds, covering the response body as well as the headers (default `30000`) — a silent/blackholed endpoint or a stalled transfer aborts here rather than hanging. |
+| `VALINOR_FETCH_ATTEMPTS` | Attempts per file for a transient failure: a whole number, at least `1` (default `3`). |
+| `VALINOR_FETCH_BACKOFF_MS` | Retry backoff base in milliseconds (default `1000`); attempt *n* waits 50–100% of base × 2^(n−1). |
+| `VALINOR_FETCH_TOTAL_TIMEOUT_MS` | The whole download's budget in milliseconds, across every attempt (default `120000`). |
 | `VALINOR_LAUNCHER_DEBUG` | Print full error causes (default output is the actionable message only). |
 
 ## Licensing

package/bin/valinor.js

@@ -1,12 +1,26 @@
 #!/usr/bin/env node
 // The launcher bin: delegate to lib/launcher.js and render its loud, actionable errors without a
 // stack trace (the cause chain is preserved on the error for VALINOR_LAUNCHER_DEBUG=1 diagnosis).
-import { run } from "../lib/launcher.js";
+import { run, softFailWarning } from "../lib/launcher.js";
 
+const args = process.argv.slice(2);
 try {
-  process.exitCode = await run(process.argv.slice(2));
+  process.exitCode = await run(args);
 } catch (e) {
-  console.error(`valinor launcher: ${e instanceof Error ? e.message : String(e)}`);
+  const message = e instanceof Error ? e.message : String(e);
+  const warning = softFailWarning(e, args);
+  if (warning) {
+    // Exit 0 for a verb whose not-running IS its fail-closed outcome (see SOFT_FAIL_VERBS); the
+    // annotation keeps the infrastructure error visible on the run without a red check on the PR.
+    console.error(`valinor launcher: warning — ${warning}\n${message}`);
+    if (process.env.GITHUB_ACTIONS === "true") console.log(`::warning title=Valinor bundle download failed::${warning}`);
+    process.exitCode = 0;
+  } else {
+    console.error(`valinor launcher: ${message}`);
+    if (process.env.GITHUB_ACTIONS === "true" && e?.transient === true) {
+      console.log("::error title=Valinor bundle download failed::The Valinor downloads endpoint did not answer after retries. This is an infrastructure error; re-run the job.");
+    }
+    process.exitCode = 1;
+  }
   if (process.env.VALINOR_LAUNCHER_DEBUG) console.error(e);
-  process.exitCode = 1;
 }

package/lib/launcher.js

@@ -16,6 +16,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { setTimeout as sleep } from "node:timers/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -126,43 +127,124 @@ export function parseSha256Sums(text, filename) {
 }
 
 /**
- * The per-request timeout (ms): a firewalled/blackholed endpoint that ACCEPTS a connection but never
- * replies must fail LOUDLY in seconds, not hang forever. Reads the supplied env (NOT a hard-coded
+ * The per-ATTEMPT timeout (ms): a firewalled/blackholed endpoint that ACCEPTS a connection but never
+ * replies must fail LOUDLY in seconds, not hang forever. The signal covers the response BODY as well as
+ * the headers, so a transfer that stalls mid-body aborts here too. Reads the supplied env (NOT a hard-coded
  * `process.env` — `run()` threads its own env through so a caller/test override actually engages).
  * Default 30s; tests dial it down to prove the abort fires.
  */
 export function fetchTimeoutMs(env = process.env) {
-  const parsed = Number(env.VALINOR_FETCH_TIMEOUT_MS);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;
+  return positiveNumber(env.VALINOR_FETCH_TIMEOUT_MS, 30_000);
+}
+
+function positiveNumber(raw, fallback) {
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/** A whole number of at least one, else the default: a fractional count must never floor to zero attempts. */
+function positiveInteger(raw, fallback) {
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed >= 1 ? parsed : fallback;
 }
 
 /**
- * GET a URL, throwing a loud error naming the URL on any non-200, TIMEOUT, or network failure.
- * `timeoutMs` is REQUIRED (resolved once by the caller from its env) — passing it explicitly is what
- * fixes the bug where `fetchTimeoutMs()` read the ambient `process.env` and a `run(args, env)`
- * override was silently dropped. A timed-out abort surfaces as `TimeoutError`, named in the message.
+ * How the launcher retries a download. A stalled or dropped transfer is TRANSIENT: on 2026-09-25 a
+ * handful of CI runs across two consumer repos saw the tarball's body stall for the whole 30s while the
+ * endpoint served the same bytes in under half a second to every other run. One fresh attempt clears
+ * that, so a transient failure is retried with jittered exponential backoff inside a bounded total
+ * budget. Only transient failures retry: a 404 (a retracted or missing artifact), a malformed manifest,
+ * and a SHA-256 mismatch stay terminal on the first sight — retrying them would only delay a loud refusal.
+ *
+ *   VALINOR_FETCH_ATTEMPTS         attempts per file, default 3
+ *   VALINOR_FETCH_BACKOFF_MS       backoff base, default 1000 (attempt n waits 50–100% of base × 2^(n-1))
+ *   VALINOR_FETCH_TOTAL_TIMEOUT_MS the whole download's budget, default 120000 — a later attempt gets
+ *                                  only what is left, so a run never waits longer than this
  */
-async function fetchOrThrow(url, fetchImpl, timeoutMs) {
-  let res;
-  try {
-    res = await (fetchImpl ?? fetch)(url, { redirect: "follow", signal: AbortSignal.timeout(timeoutMs) });
-  } catch (e) {
-    // AbortSignal.timeout rejects with a DOMException named "TimeoutError" — surface that distinctly
-    // so the failure reads as "timed out after Nms", not an opaque cause code.
-    const cause =
-      e?.name === "TimeoutError"
-        ? `timed out after ${timeoutMs}ms`
-        : (e?.cause?.code ?? e?.code ?? (e instanceof Error ? e.message : String(e)));
-    throw new Error(`could not reach ${url} (${cause})`, { cause: e });
+export function fetchPolicy(env = process.env) {
+  return {
+    timeoutMs: fetchTimeoutMs(env),
+    attempts: positiveInteger(env.VALINOR_FETCH_ATTEMPTS, 3),
+    backoffMs: positiveNumber(env.VALINOR_FETCH_BACKOFF_MS, 1_000),
+    totalTimeoutMs: positiveNumber(env.VALINOR_FETCH_TOTAL_TIMEOUT_MS, 120_000),
+  };
+}
+
+/** HTTP statuses worth another attempt: the server said "not now", never "not here". */
+function isTransientStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+/** An error carrying whether another attempt could succeed. `transient` rides onto the error `run()`
+ *  throws, so the bin can tell an outage (retry later) from a refusal (fix something). */
+function fetchError(message, transient, cause) {
+  const e = new Error(message, cause === undefined ? undefined : { cause });
+  e.transient = transient;
+  return e;
+}
+
+/** The reason a request failed, in words: a timeout names its duration, anything else its cause code. */
+function describeFailure(e, timeoutMs, phase) {
+  if (e?.name === "TimeoutError" || e?.name === "AbortError") return `timed out after ${timeoutMs}ms ${phase}`;
+  return String(e?.cause?.code ?? e?.code ?? (e instanceof Error ? e.message : e));
+}
+
+/**
+ * GET a URL and READ ITS BODY with `read(res)` under ONE abort signal per attempt, retrying transient
+ * failures. Reading the body inside the attempt is the fix for the 2026-09-25 failures: the body used to
+ * be read after this function returned, so a mid-body stall escaped as a bare "The operation was aborted
+ * due to timeout" with no URL, no retry, and nothing to act on. Throws a loud error naming the URL, the
+ * attempt count and the last cause. `cancel` (optional) stops the loop — the in-flight request and any
+ * backoff wait — once a sibling download has already failed terminally, so the process never idles out
+ * the rest of the budget on a run that must fail anyway.
+ */
+async function fetchBody(url, read, fetchImpl, policy, cancel) {
+  const deadline = Date.now() + policy.totalTimeoutMs;
+  let last;
+  let made = 0;
+  for (let attempt = 1; attempt <= policy.attempts; attempt++) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    cancel?.throwIfAborted();
+    made = attempt;
+    const timeoutMs = Math.min(policy.timeoutMs, remaining);
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = cancel ? AbortSignal.any([timeout, cancel]) : timeout;
+    let res;
+    try {
+      res = await (fetchImpl ?? fetch)(url, { redirect: "follow", signal });
+    } catch (e) {
+      last = fetchError(`could not reach ${url} (${describeFailure(e, timeoutMs, "waiting for a response")})`, true, e);
+    }
+    if (res && !res.ok) {
+      last = fetchError(`${url} returned HTTP ${res.status}`, isTransientStatus(res.status));
+      await res.body?.cancel().catch(() => {});
+    } else if (res) {
+      try {
+        return await read(res);
+      } catch (e) {
+        // A body that PARSES wrong (a malformed manifest) is a refusal, not an outage: never retried.
+        last = fetchError(`could not download ${url} (${describeFailure(e, timeoutMs, "reading the response body")})`, !(e instanceof SyntaxError), e);
+      }
+    }
+    cancel?.throwIfAborted();
+    if (!last.transient) throw last;
+    if (attempt < policy.attempts) {
+      const wait = policy.backoffMs * 2 ** (attempt - 1) * (0.5 + Math.random() * 0.5);
+      if (Date.now() + wait >= deadline) break;
+      await sleep(wait, undefined, { signal: cancel });
+    }
   }
-  if (!res.ok) throw new Error(`${url} returned HTTP ${res.status}`);
-  return res;
+  throw fetchError(
+    `${last?.message ?? `could not reach ${url}`} — gave up after ${made} attempt(s) within the ${policy.totalTimeoutMs}ms budget`,
+    true,
+    last,
+  );
 }
 
-/** Fetch + validate the endpoint manifest. `timeoutMs` is threaded from the caller's env. */
-export async function fetchManifest(base, fetchImpl, timeoutMs = fetchTimeoutMs()) {
-  const res = await fetchOrThrow(`${base}/manifest.json`, fetchImpl, timeoutMs);
-  return res.json();
+/** Fetch + validate the endpoint manifest, retrying transient failures. `policy` is threaded from the caller's env. */
+export async function fetchManifest(base, fetchImpl, policy = fetchPolicy()) {
+  return fetchBody(`${base}/manifest.json`, (res) => res.json(), fetchImpl, policy);
 }
 
 /**
@@ -173,17 +255,23 @@ export async function fetchManifest(base, fetchImpl, timeoutMs = fetchTimeoutMs(
  * a temp dir and atomically renamed into place, so a crashed install can never half-populate a
  * version dir that a later run would trust.
  */
-export async function ensureVersion(base, version, root, fetchImpl, timeoutMs = fetchTimeoutMs()) {
+export async function ensureVersion(base, version, root, fetchImpl, policy = fetchPolicy()) {
   const versionDir = join(root, version);
   if (existsSync(join(versionDir, ".complete"))) return versionDir; // cache hit — zero network.
 
   const tarballUrl = `${base}/v/${version}/valinor.tgz`;
-  const [tarballRes, sumsRes] = await Promise.all([
-    fetchOrThrow(tarballUrl, fetchImpl, timeoutMs),
-    fetchOrThrow(`${base}/v/${version}/SHA256SUMS`, fetchImpl, timeoutMs),
+  // Either file failing for good fails the install, so it cancels the other's retry loop at once.
+  const siblings = new AbortController();
+  const settle = (p) =>
+    p.catch((e) => {
+      siblings.abort(e);
+      throw e;
+    });
+  const [tarball, sums] = await Promise.all([
+    settle(fetchBody(tarballUrl, async (res) => Buffer.from(await res.arrayBuffer()), fetchImpl, policy, siblings.signal)),
+    settle(fetchBody(`${base}/v/${version}/SHA256SUMS`, (res) => res.text(), fetchImpl, policy, siblings.signal)),
   ]);
-  const tarball = Buffer.from(await tarballRes.arrayBuffer());
-  const expected = parseSha256Sums(await sumsRes.text(), "valinor.tgz");
+  const expected = parseSha256Sums(sums, "valinor.tgz");
   const actual = createHash("sha256").update(tarball).digest("hex");
   if (actual !== expected) {
     throw new Error(
@@ -243,9 +331,9 @@ export async function run(args, env = process.env) {
   const base = downloadsUrl(env);
   const root = cacheRoot(env);
   const requested = requestedVersion(env);
-  // Resolve the timeout ONCE from THIS call's env (the bug fix — `fetchOrThrow` used to read the
-  // ambient process.env, so a `run(args, env)` override never engaged) and thread it into every fetch.
-  const timeoutMs = fetchTimeoutMs(env);
+  // Resolve the fetch policy ONCE from THIS call's env (an earlier bug read the ambient process.env, so a
+  // `run(args, env)` override never engaged) and thread it into every fetch.
+  const policy = fetchPolicy(env);
 
   let version;
   if (SEMVER_RE.test(requested)) {
@@ -253,24 +341,53 @@ export async function run(args, env = process.env) {
   } else {
     let manifest;
     try {
-      manifest = await fetchManifest(base, undefined, timeoutMs);
+      manifest = await fetchManifest(base, undefined, policy);
     } catch (e) {
-      throw new Error(`${e instanceof Error ? e.message : String(e)}\n${offlineHint(base, root)}`, { cause: e });
+      throw withHint(e, `${e instanceof Error ? e.message : String(e)}\n${offlineHint(base, root)}`);
     }
     version = resolveVersion(manifest, requested);
   }
 
   let versionDir;
   try {
-    versionDir = await ensureVersion(base, version, root, undefined, timeoutMs);
+    versionDir = await ensureVersion(base, version, root, undefined, policy);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     // Integrity failures are terminal as-is; reachability failures get the offline hint.
-    throw new Error(msg.includes("SHA-256 MISMATCH") ? msg : `${msg}\n${offlineHint(base, root)}`, { cause: e });
+    throw withHint(e, msg.includes("SHA-256 MISMATCH") ? msg : `${msg}\n${offlineHint(base, root)}`);
   }
   return spawnCli(cachedBinPath(versionDir), args);
 }
 
+/** Re-wrap an error with the actionable message, keeping whether it was transient. */
+function withHint(e, message) {
+  const wrapped = new Error(message, { cause: e });
+  wrapped.transient = e?.transient === true;
+  return wrapped;
+}
+
+/**
+ * The verbs whose NOT RUNNING is already their fail-closed outcome. `review-trigger-run` posts a review
+ * trigger only on a fully green head and exits 0 on every error of its own ("failing closed (no
+ * trigger)"), because the next wake or the hourly sweep re-evaluates the same PR. A launcher that could
+ * not fetch the bundle has produced exactly that outcome — nothing posted — so failing the job would add
+ * nothing but a red check on the PR head that no later wake clears (a later run attaches its check to a
+ * different commit). Only a TRANSIENT failure qualifies: a missing artifact or a SHA-256 mismatch still
+ * exits 1, loudly. A gate verb is never listed here — a gate that did not run must never read as passed.
+ */
+export const SOFT_FAIL_VERBS = new Set(["review-trigger-run"]);
+
+/** The warning to print instead of failing, when `error` is a transient fetch failure for a
+ *  {@link SOFT_FAIL_VERBS} verb; `null` when the launcher must fail as usual. */
+export function softFailWarning(error, args) {
+  if (error?.transient !== true || !SOFT_FAIL_VERBS.has(args[0])) return null;
+  return (
+    `could not download the Valinor bundle, so \`${args[0]}\` did not run and posted nothing (fail-closed). ` +
+    "This is an infrastructure error, not a check result: the next wake-up or the hourly sweep re-evaluates, " +
+    "and re-running this job retries now."
+  );
+}
+
 /** The actionable degradation message: name the endpoint + the offline cache state. */
 function offlineHint(base, root) {
   const cached = cachedVersions(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theappagency/valinor",
-  "version": "9.2.0",
+  "version": "9.5.0",
   "description": "Public launcher for the Valinor CLI — fetches, SHA-256-verifies, caches, and runs the proprietary Valinor bundle from downloads.valinorci.com. Zero setup, zero secrets, zero npm auth.",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "lib"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "license": "MIT",
   "publishConfig": {