@indigoai-us/hq-cloud 6.13.4 → 6.13.5

package/dist/lib/net-errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Transient network-failure classification for the sync runner.
+ *
+ * The auto-sync watcher runs an unattended poll loop. At the top of every pass
+ * it calls `GET /membership/me` to resolve which companies to sync. When the
+ * machine is briefly offline (wifi drop, waking from sleep, a DNS blip, the
+ * vault API momentarily unreachable) that call fails at the transport layer —
+ * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
+ * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
+ *
+ * This is NOT a crash: the next poll (~30s later) succeeds once the network is
+ * back. But the runner used to `return 1` for it, the watch loop propagated
+ * that non-zero exit, the process exited, and the menubar supervisor reported
+ * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
+ * HQ-SYNC-1W cluster. We classify these so the watch loop can stay alive and
+ * retry instead of surfacing a false crash, while a one-shot `hq sync` still
+ * exits non-zero so a human running it by hand sees the failure.
+ */
+/**
+ * Distinct runner exit code for a transient network failure. The watch loop
+ * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
+ * still exits non-zero so the failure is visible to a human/script. Value 75 =
+ * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
+ * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
+ */
+export declare const TRANSIENT_NETWORK_EXIT = 75;
+/**
+ * True when `err` is (or wraps) a transient network-transport failure. Walks the
+ * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
+ * latter), matching either undici's canonical `TypeError: fetch failed` message
+ * or a known transient `.code`. Conservative by design: an arbitrary
+ * `new Error("network down")` with no code and a non-canonical message is NOT
+ * treated as transient, so only real transport-failure shapes qualify.
+ */
+export declare function isTransientNetworkError(err: unknown, depth?: number): boolean;
+//# sourceMappingURL=net-errors.d.ts.map

package/dist/lib/net-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.d.ts","sourceRoot":"","sources":["../../src/lib/net-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AA0BzC;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAsBxE"}

package/dist/lib/net-errors.js

@@ -0,0 +1,81 @@
+/**
+ * Transient network-failure classification for the sync runner.
+ *
+ * The auto-sync watcher runs an unattended poll loop. At the top of every pass
+ * it calls `GET /membership/me` to resolve which companies to sync. When the
+ * machine is briefly offline (wifi drop, waking from sleep, a DNS blip, the
+ * vault API momentarily unreachable) that call fails at the transport layer —
+ * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
+ * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
+ *
+ * This is NOT a crash: the next poll (~30s later) succeeds once the network is
+ * back. But the runner used to `return 1` for it, the watch loop propagated
+ * that non-zero exit, the process exited, and the menubar supervisor reported
+ * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
+ * HQ-SYNC-1W cluster. We classify these so the watch loop can stay alive and
+ * retry instead of surfacing a false crash, while a one-shot `hq sync` still
+ * exits non-zero so a human running it by hand sees the failure.
+ */
+/**
+ * Distinct runner exit code for a transient network failure. The watch loop
+ * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
+ * still exits non-zero so the failure is visible to a human/script. Value 75 =
+ * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
+ * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
+ */
+export const TRANSIENT_NETWORK_EXIT = 75;
+/**
+ * Node/undici error `code`s that mean "the request never completed at the
+ * transport layer" — the machine could not reach the host. All are transient:
+ * a later attempt from the same machine can succeed unchanged.
+ */
+const TRANSIENT_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EHOSTUNREACH",
+    "EHOSTDOWN",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "ECONNABORTED",
+    // undici's own timeout/socket failures
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/**
+ * True when `err` is (or wraps) a transient network-transport failure. Walks the
+ * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
+ * latter), matching either undici's canonical `TypeError: fetch failed` message
+ * or a known transient `.code`. Conservative by design: an arbitrary
+ * `new Error("network down")` with no code and a non-canonical message is NOT
+ * treated as transient, so only real transport-failure shapes qualify.
+ */
+export function isTransientNetworkError(err, depth = 0) {
+    if (depth > 8 || !(err instanceof Error))
+        return false;
+    // undici's transport failure surfaces as exactly this message.
+    if (err.message === "fetch failed")
+        return true;
+    const code = err.code;
+    if (typeof code === "string" && TRANSIENT_CODES.has(code))
+        return true;
+    // AggregateError (e.g. happy-eyeballs) stashes the per-attempt errors here.
+    const aggregated = err.errors;
+    if (Array.isArray(aggregated)) {
+        for (const inner of aggregated) {
+            if (isTransientNetworkError(inner, depth + 1))
+                return true;
+        }
+    }
+    const cause = err.cause;
+    if (cause !== undefined && cause !== err) {
+        return isTransientNetworkError(cause, depth + 1);
+    }
+    return false;
+}
+//# sourceMappingURL=net-errors.js.map

package/dist/lib/net-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.js","sourceRoot":"","sources":["../../src/lib/net-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;GAIG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS;IACtC,cAAc;IACd,YAAY;IACZ,WAAW;IACX,WAAW;IACX,WAAW;IACX,OAAO;IACP,cAAc;IACd,WAAW;IACX,aAAa;IACb,UAAU;IACV,cAAc;IACd,uCAAuC;IACvC,yBAAyB;IACzB,yBAAyB;IACzB,sBAAsB;IACtB,gBAAgB;CACjB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY,EAAE,KAAK,GAAG,CAAC;IAC7D,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEvD,+DAA+D;IAC/D,IAAI,GAAG,CAAC,OAAO,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,4EAA4E;IAC5E,MAAM,UAAU,GAAI,GAA4B,CAAC,MAAM,CAAC;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,IAAI,uBAAuB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAI,GAA2B,CAAC,KAAK,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACzC,OAAO,uBAAuB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/net-errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=net-errors.test.d.ts.map

package/dist/lib/net-errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.test.d.ts","sourceRoot":"","sources":["../../src/lib/net-errors.test.ts"],"names":[],"mappings":""}

package/dist/lib/net-errors.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { isTransientNetworkError, TRANSIENT_NETWORK_EXIT } from "./net-errors.js";
+describe("isTransientNetworkError", () => {
+    it("treats undici's canonical `fetch failed` TypeError as transient", () => {
+        // This is the exact shape the runner's discovery step sees in production
+        // (HQ-SYNC-1W): `{"type":"error","message":"fetch failed","path":"(discovery)"}`.
+        expect(isTransientNetworkError(new TypeError("fetch failed"))).toBe(true);
+    });
+    it("treats known transport `.code`s as transient", () => {
+        for (const code of ["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT"]) {
+            const err = Object.assign(new Error("boom"), { code });
+            expect(isTransientNetworkError(err)).toBe(true);
+        }
+    });
+    it("walks the .cause chain (fetch failed wrapping a DNS error)", () => {
+        const cause = Object.assign(new Error("getaddrinfo ENOTFOUND api"), {
+            code: "ENOTFOUND",
+        });
+        const err = Object.assign(new TypeError("fetch failed"), { cause });
+        expect(isTransientNetworkError(err)).toBe(true);
+    });
+    it("walks AggregateError.errors (happy-eyeballs)", () => {
+        const agg = Object.assign(new AggregateError([
+            Object.assign(new Error("v4"), { code: "ECONNREFUSED" }),
+            Object.assign(new Error("v6"), { code: "EHOSTUNREACH" }),
+        ], "all attempts failed"), {});
+        expect(isTransientNetworkError(agg)).toBe(true);
+    });
+    it("is conservative: an arbitrary error is NOT transient", () => {
+        // A bare message like "network down" (no code, not the canonical undici
+        // message) must not be misclassified — only real transport shapes qualify.
+        expect(isTransientNetworkError(new Error("network down"))).toBe(false);
+        expect(isTransientNetworkError(new Error("boom"))).toBe(false);
+        expect(isTransientNetworkError("fetch failed")).toBe(false);
+        expect(isTransientNetworkError(undefined)).toBe(false);
+    });
+    it("does not infinite-loop on a self-referential cause", () => {
+        const err = new Error("weird");
+        err.cause = err;
+        expect(isTransientNetworkError(err)).toBe(false);
+    });
+    it("exposes a distinct exit code off the runner's other codes", () => {
+        expect(TRANSIENT_NETWORK_EXIT).toBe(75);
+        expect([0, 1, 2, 17]).not.toContain(TRANSIENT_NETWORK_EXIT);
+    });
+});
+//# sourceMappingURL=net-errors.test.js.map

package/dist/lib/net-errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-errors.test.js","sourceRoot":"","sources":["../../src/lib/net-errors.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "6.13.4",
+  "version": "6.13.5",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bin/sync-runner-watch-loop.ts

@@ -8,6 +8,7 @@ import {
   OPERATION_LOCKED_EXIT,
 } from "../operation-lock.js";
 import { describeError } from "../lib/describe-error.js";
+import { TRANSIENT_NETWORK_EXIT } from "../lib/net-errors.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
   TreeWatcher,
@@ -430,7 +431,16 @@ export async function runWatchLoop(
   try {
     while (!stopped) {
       const result = await runGuarded(passArgv);
-      if (result !== 0) {
+      if (result === TRANSIENT_NETWORK_EXIT) {
+        // The machine was briefly offline (the discovery fetch failed after
+        // retries). That is NOT a crash — stay alive and retry on the next
+        // poll. Returning it here would exit the watcher and the menubar would
+        // report "watcher exited unexpectedly" for every network blip
+        // (HQ-SYNC-1W). Log to stderr so it still shows up as a breadcrumb.
+        process.stderr.write(
+          "hq-sync-runner: watch pass skipped — transient network failure; retrying next poll\n",
+        );
+      } else if (result !== 0) {
         return result;
       }
       await Promise.race([sleep(pollMs), stoppedSignal]);

package/src/bin/sync-runner.test.ts

@@ -35,6 +35,7 @@ import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
 import { HQ_CLOUD_VERSION } from "../version.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
+import { TRANSIENT_NETWORK_EXIT } from "../lib/net-errors.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
 import type {
@@ -397,6 +398,49 @@ describe("memberships retry", () => {
     });
   });
 
+  it("a transient network failure (fetch failed) during discovery returns TRANSIENT_NETWORK_EXIT, not 1 (HQ-SYNC-1W)", async () => {
+    // Regression for the "auto-sync watcher exited unexpectedly (code=Some(1))"
+    // cluster: a machine that stays offline through all 3 membership retries
+    // used to `return 1`, which the watch loop propagated and the menubar
+    // reported as a crash for every network blip. undici surfaces the blip as
+    // `TypeError: fetch failed`; that must map to the retryable exit code so the
+    // watcher stays alive instead of crash-reporting. A one-shot run still sees
+    // a non-zero exit.
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.reject(new TypeError("fetch failed"));
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(TRANSIENT_NETWORK_EXIT);
+    expect(listCalls).toBe(3);
+    // Still surfaced for observability — just no longer a "code 1" crash.
+    const events = deps.stderr.events();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: "error",
+      message: "fetch failed",
+      path: "(discovery)",
+    });
+  });
+
+  it("a NON-transient discovery failure still returns 1 (unchanged)", async () => {
+    // Guard the conservative classifier: a generic error (not a transport
+    // shape) is still a hard exit 1, exactly as before.
+    let listCalls = 0;
+    const stub = makeVaultStub();
+    stub.listMyMemberships = () => {
+      listCalls++;
+      return Promise.reject(new Error("unexpected 500 from vault api"));
+    };
+    const deps = makeDeps({ createVaultClient: () => stub });
+    const code = await runRunner(["--companies"], deps);
+    expect(code).toBe(1);
+    expect(listCalls).toBe(3);
+  });
+
   it("VaultAuthError short-circuits retry (no retries on auth failure)", async () => {
     let listCalls = 0;
     const stub = makeVaultStub();
@@ -3307,6 +3351,39 @@ describe("runRunnerWithLoop — event-push wiring", () => {
     expect(watcher.disposed).toBe(true);
   });
 
+  it("a TRANSIENT_NETWORK_EXIT poll pass does NOT surface as a crash — the loop retries (HQ-SYNC-1W)", async () => {
+    // A transient offline blip must keep the watcher alive: the loop logs and
+    // polls again instead of returning the code and letting the process exit
+    // (which the menubar reports as "watcher exited unexpectedly"). A genuine
+    // hard error on a later pass still terminates the loop.
+    const watcher = makeWatcherStub();
+    let n = 0;
+    const runPass = vi.fn().mockImplementation(async () => {
+      n++;
+      // First pass: machine is offline (transient). Second pass: a real hard
+      // error, used here only to end the otherwise-infinite loop deterministically.
+      return n === 1 ? TRANSIENT_NETWORK_EXIT : 2;
+    });
+
+    const code = await runRunnerWithLoop(
+      ["--companies", "--watch", "--event-push", "--hq-root", "/tmp/hq"],
+      {
+        runPass,
+        clock: new FakeClock(),
+        createWatcher: () => watcher,
+        sleep: () => Promise.resolve(),
+        onShutdownSignal: () => () => {},
+      },
+    );
+
+    // The transient pass did NOT end the loop — it ran again…
+    expect(runPass).toHaveBeenCalledTimes(2);
+    // …and the transient code was never surfaced as the watcher's exit code.
+    expect(code).toBe(2);
+    expect(code).not.toBe(TRANSIENT_NETWORK_EXIT);
+    expect(watcher.disposed).toBe(true);
+  });
+
   it("without --event-push, no watcher is created (poll-only safety net)", async () => {
     let triggerShutdown = () => {};
     const createWatcher = vi.fn(() => makeWatcherStub());

package/src/bin/sync-runner.ts

@@ -110,6 +110,10 @@ import type { ReindexOptions, ReindexResult } from "../cli/reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
 import { materializeCodexAgents } from "../agent-codex-instructions.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
+import {
+  isTransientNetworkError,
+  TRANSIENT_NETWORK_EXIT,
+} from "../lib/net-errors.js";
 import { describeError } from "../lib/describe-error.js";
 import type { Clock, TreeChangeBatch } from "../watcher.js";
 import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
@@ -1160,15 +1164,19 @@ export async function runRunner(
       });
       return 0;
     }
-    // Any other failure is unrecoverable — surface as an error event and
-    // exit non-zero so the spawner knows the runner didn't get far enough
-    // to emit a useful protocol stream.
+    // Surface the failure as an error event for observability either way.
     emit({
       type: "error",
       message: err instanceof Error ? err.message : String(err),
       path: "(discovery)",
     });
-    return 1;
+    // A transient network failure (offline, DNS blip, vault API briefly
+    // unreachable) is NOT a crash — it self-heals on the next poll. Return the
+    // retryable exit code so the watch loop stays alive instead of exiting and
+    // being reported as "watcher exited unexpectedly (code=Some(1))" for every
+    // blip (HQ-SYNC-1W). A one-shot run still exits non-zero. Any other failure
+    // is treated as a hard error (exit 1), as before.
+    return isTransientNetworkError(err) ? TRANSIENT_NETWORK_EXIT : 1;
   }
 
   const targetPlan = await buildFanoutPlan({

package/src/lib/net-errors.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { isTransientNetworkError, TRANSIENT_NETWORK_EXIT } from "./net-errors.js";
+
+describe("isTransientNetworkError", () => {
+  it("treats undici's canonical `fetch failed` TypeError as transient", () => {
+    // This is the exact shape the runner's discovery step sees in production
+    // (HQ-SYNC-1W): `{"type":"error","message":"fetch failed","path":"(discovery)"}`.
+    expect(isTransientNetworkError(new TypeError("fetch failed"))).toBe(true);
+  });
+
+  it("treats known transport `.code`s as transient", () => {
+    for (const code of ["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT"]) {
+      const err = Object.assign(new Error("boom"), { code });
+      expect(isTransientNetworkError(err)).toBe(true);
+    }
+  });
+
+  it("walks the .cause chain (fetch failed wrapping a DNS error)", () => {
+    const cause = Object.assign(new Error("getaddrinfo ENOTFOUND api"), {
+      code: "ENOTFOUND",
+    });
+    const err = Object.assign(new TypeError("fetch failed"), { cause });
+    expect(isTransientNetworkError(err)).toBe(true);
+  });
+
+  it("walks AggregateError.errors (happy-eyeballs)", () => {
+    const agg = Object.assign(new AggregateError([
+      Object.assign(new Error("v4"), { code: "ECONNREFUSED" }),
+      Object.assign(new Error("v6"), { code: "EHOSTUNREACH" }),
+    ], "all attempts failed"), {});
+    expect(isTransientNetworkError(agg)).toBe(true);
+  });
+
+  it("is conservative: an arbitrary error is NOT transient", () => {
+    // A bare message like "network down" (no code, not the canonical undici
+    // message) must not be misclassified — only real transport shapes qualify.
+    expect(isTransientNetworkError(new Error("network down"))).toBe(false);
+    expect(isTransientNetworkError(new Error("boom"))).toBe(false);
+    expect(isTransientNetworkError("fetch failed")).toBe(false);
+    expect(isTransientNetworkError(undefined)).toBe(false);
+  });
+
+  it("does not infinite-loop on a self-referential cause", () => {
+    const err = new Error("weird") as Error & { cause?: unknown };
+    err.cause = err;
+    expect(isTransientNetworkError(err)).toBe(false);
+  });
+
+  it("exposes a distinct exit code off the runner's other codes", () => {
+    expect(TRANSIENT_NETWORK_EXIT).toBe(75);
+    expect([0, 1, 2, 17]).not.toContain(TRANSIENT_NETWORK_EXIT);
+  });
+});

package/src/lib/net-errors.ts

@@ -0,0 +1,83 @@
+/**
+ * Transient network-failure classification for the sync runner.
+ *
+ * The auto-sync watcher runs an unattended poll loop. At the top of every pass
+ * it calls `GET /membership/me` to resolve which companies to sync. When the
+ * machine is briefly offline (wifi drop, waking from sleep, a DNS blip, the
+ * vault API momentarily unreachable) that call fails at the transport layer —
+ * Node's `fetch` throws `TypeError: fetch failed` with the real cause (an
+ * `ECONNREFUSED` / `ENOTFOUND` / `ETIMEDOUT` / … Error) on `.cause`.
+ *
+ * This is NOT a crash: the next poll (~30s later) succeeds once the network is
+ * back. But the runner used to `return 1` for it, the watch loop propagated
+ * that non-zero exit, the process exited, and the menubar supervisor reported
+ * "auto-sync watcher exited unexpectedly (code=Some(1))" for every blip — the
+ * HQ-SYNC-1W cluster. We classify these so the watch loop can stay alive and
+ * retry instead of surfacing a false crash, while a one-shot `hq sync` still
+ * exits non-zero so a human running it by hand sees the failure.
+ */
+
+/**
+ * Distinct runner exit code for a transient network failure. The watch loop
+ * treats it as "stay alive, retry next tick" (never a crash); a one-shot run
+ * still exits non-zero so the failure is visible to a human/script. Value 75 =
+ * `EX_TEMPFAIL` from sysexits.h ("temporary failure; retry"). Kept off the
+ * codes already in use by the runner (0 ok, 1 error, 2 partial, 17 op-locked).
+ */
+export const TRANSIENT_NETWORK_EXIT = 75;
+
+/**
+ * Node/undici error `code`s that mean "the request never completed at the
+ * transport layer" — the machine could not reach the host. All are transient:
+ * a later attempt from the same machine can succeed unchanged.
+ */
+const TRANSIENT_CODES = new Set<string>([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ETIMEDOUT",
+  "EPIPE",
+  "EHOSTUNREACH",
+  "EHOSTDOWN",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "ECONNABORTED",
+  // undici's own timeout/socket failures
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+
+/**
+ * True when `err` is (or wraps) a transient network-transport failure. Walks the
+ * `.cause` chain and `AggregateError.errors` (undici's happy-eyeballs raises the
+ * latter), matching either undici's canonical `TypeError: fetch failed` message
+ * or a known transient `.code`. Conservative by design: an arbitrary
+ * `new Error("network down")` with no code and a non-canonical message is NOT
+ * treated as transient, so only real transport-failure shapes qualify.
+ */
+export function isTransientNetworkError(err: unknown, depth = 0): boolean {
+  if (depth > 8 || !(err instanceof Error)) return false;
+
+  // undici's transport failure surfaces as exactly this message.
+  if (err.message === "fetch failed") return true;
+
+  const code = (err as { code?: unknown }).code;
+  if (typeof code === "string" && TRANSIENT_CODES.has(code)) return true;
+
+  // AggregateError (e.g. happy-eyeballs) stashes the per-attempt errors here.
+  const aggregated = (err as { errors?: unknown }).errors;
+  if (Array.isArray(aggregated)) {
+    for (const inner of aggregated) {
+      if (isTransientNetworkError(inner, depth + 1)) return true;
+    }
+  }
+
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause !== undefined && cause !== err) {
+    return isTransientNetworkError(cause, depth + 1);
+  }
+  return false;
+}