create-walle 0.10.1 → 0.10.2

package/template/wall-e/lib/mcp-integration.js

@@ -6,6 +6,7 @@ const http = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { resolveRealNode } = require('./real-node');
+const { isWritableOnlyByOwner } = require('../../shared/owner-write-safety');
 const {
   assertNotReserved,
   withClientConfigLock,
@@ -1339,16 +1340,15 @@ function _ensurePrivateDirectory(dirPath, homeDir) {
       stat = fs.lstatSync(current, { bigint: true });
     }
     if (stat.isSymbolicLink() || !stat.isDirectory()) throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
-    const mode = Number(stat.mode & 0o777n);
     const owned = current === ownedRoot || current.startsWith(`${ownedRoot}${path.sep}`);
     if (owned) {
-      if (stat.uid !== BigInt(process.getuid()) || (mode & 0o022) !== 0) {
+      if (stat.uid !== BigInt(process.getuid()) || !isWritableOnlyByOwner(stat)) {
         throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
       }
       continue;
     }
     if (stat.uid === 0n) continue; // system ancestor above the owned boundary
-    if (stat.uid === BigInt(process.getuid()) && (mode & 0o022) === 0) continue;
+    if (stat.uid === BigInt(process.getuid()) && isWritableOnlyByOwner(stat)) continue;
     throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
   }
   return dirPath;
@@ -1418,15 +1418,14 @@ function _admitHistoryDirectoryChain(dirPath, homeDir) {
       throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
     }
     if (stat.isSymbolicLink() || !stat.isDirectory()) throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
-    const mode = Number(stat.mode & 0o777n);
     if (current === ownedRoot || current.startsWith(`${ownedRoot}${path.sep}`)) {
-      if (stat.uid !== BigInt(process.getuid()) || (mode & 0o022) !== 0) {
+      if (stat.uid !== BigInt(process.getuid()) || !isWritableOnlyByOwner(stat)) {
         throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
       }
       continue;
     }
     if (stat.uid === 0n) continue; // system ancestor above the owned boundary
-    if (stat.uid === BigInt(process.getuid()) && (mode & 0o022) === 0) continue;
+    if (stat.uid === BigInt(process.getuid()) && isWritableOnlyByOwner(stat)) continue;
     throw new ClientConfigError('CLIENT_CONFIG_OWNERSHIP_LOST');
   }
   return true;

package/template/wall-e/lib/runtime-worker-pool.js

@@ -48,6 +48,7 @@ const SCHEDULER_JOB_LANES = Object.freeze({
   'telemetry:cleanup': 'maintenance',
   'agent-benchmark': 'llm_background',
   'weekly-eval-loop': 'llm_background',
+  'helper-rules-probe': 'maintenance', // WP-5b §6.8: brain-write-only daily tick (same class as brain-retention)
   'deferred:embeddings-init': 'embedding',
   'deferred:temporal-backfill': 'maintenance',
   'deferred:skill-reference-sync': 'io',

package/template/wall-e/lib/scheduler-worker-jobs.js

@@ -244,6 +244,11 @@ async function runSchedulerJob(jobName, payload = {}) {
         result = await _measurePhase(phases, 'weeklyEval.run', () => runWeeklyEval(brain, { runAgentLoop }));
         break;
       }
+      case 'helper-rules-probe':
+        // WP-5b §6.8: this worker's brain handle is read-only, so the helper-rules record's
+        // daily probe crosses to the owner through _brainWrite (the same split brain-retention uses).
+        result = await _measurePhase(phases, 'helperRules.dailyTick', () => _brainWrite('helperRulesDailyTick'));
+        break;
       case 'deferred:embeddings-init':
         result = await _measurePhase(phases, 'embeddings.init', async () => {
           await require('../embeddings').init();
@@ -347,6 +352,7 @@ function supportedSchedulerWorkerJobs() {
     'telemetry:cleanup',
     'agent-benchmark',
     'weekly-eval-loop',
+    'helper-rules-probe',
     'deferred:embeddings-init',
     'deferred:temporal-backfill',
     'deferred:skill-reference-sync',

package/template/wall-e/lib/telemetry-db-schema.js

@@ -14,6 +14,33 @@ const { createMigrationRunner, pragmaVersionStore } = require('../shared/db-migr
 
 const TELEMETRY_DB_FILENAME = 'telemetry.db';
 
+// WP-1 (blog-view-counts, design §5 D-2, lead review correction): the two
+// additive blog-view tables (a running total per article and a bounded set of
+// short-lived per-tab receipts) are DDL, so the walle-telemetry migration owner
+// declares them HERE — the baseline creates them and migration 2 adds them to a
+// v1 database, so a fresh install and an upgrade land on the same schema. The
+// read/write path (lib/blog-view-store.js) owns only queries, never DDL.
+const BLOG_VIEW_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS blog_view_counts (
+    slug TEXT PRIMARY KEY,
+    views INTEGER NOT NULL DEFAULT 0 CHECK (views >= 0)
+  );
+  CREATE TABLE IF NOT EXISTS blog_view_receipts (
+    slug TEXT NOT NULL,
+    token TEXT NOT NULL,
+    expires_at_ms INTEGER NOT NULL,
+    PRIMARY KEY (slug, token)
+  );
+  CREATE INDEX IF NOT EXISTS idx_blog_view_expiry ON blog_view_receipts (expires_at_ms);
+`;
+
+// Idempotent: every statement is IF NOT EXISTS, so re-running the baseline or
+// migration 2 on an already-migrated database is a no-op. Called only from the
+// two runner-owned spec entries below — never from a request path.
+function createBlogViewTables(db) {
+  db.exec(BLOG_VIEW_SCHEMA_SQL);
+}
+
 function _telemetryColumnExists(db, table, column) {
   return db.prepare(`PRAGMA table_info(${table})`).all().some((row) => row.name === column);
 }
@@ -157,6 +184,9 @@ function telemetryBaseline(db) {
         PRIMARY KEY(identity_key, content_hash)
       );
     `);
+  // WP-1 (blog-view-counts): durable per-article view counters live in this same
+  // database (design §5 D-2 — reuse the existing volume, no new open, no new job).
+  createBlogViewTables(db);
 }
 
 const TELEMETRY_MIGRATIONS = {
@@ -173,6 +203,11 @@ const TELEMETRY_MIGRATIONS = {
       _telemetryAddColumn(d, 'feedback_reports', 'ip_first_seen', 'TEXT');
     },
   },
+  2: {
+    label: 'blog-view-tables',
+    rerunSafe: true, // CREATE TABLE/INDEX IF NOT EXISTS, safe to re-execute
+    up: (d) => createBlogViewTables(d),
+  },
 };
 
 /** Builds a fresh createMigrationRunner() instance for walle-telemetry. Callers that need
@@ -188,8 +223,10 @@ function createTelemetryMigrationRunner() {
 }
 
 module.exports = {
+  BLOG_VIEW_SCHEMA_SQL,
   TELEMETRY_DB_FILENAME,
   telemetryBaseline,
   TELEMETRY_MIGRATIONS,
+  createBlogViewTables,
   createTelemetryMigrationRunner,
 };

package/template/wall-e/lib/telemetry-process-client.js

@@ -3,6 +3,11 @@
 const path = require('node:path');
 const { fork } = require('node:child_process');
 const { decodeIpcResult } = require('./ipc-result-codec');
+// WP-1 (blog-view-counts): the ONE public counter path and its body cap have to
+// be recognised on THIS side of the IPC boundary — the 1024-byte limit is
+// enforced before a byte crosses it, and the counter's peer identity travels in
+// its own field. Pure data/predicates, no env read at require time.
+const { BLOG_VIEW_MAX_BODY_BYTES, isBlogViewsPath } = require('./blog-view-policy');
 
 const MAX_REQUEST_BYTES = 2 * 1024 * 1024;
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
@@ -15,6 +20,38 @@ function codedError(code, message) {
   return error;
 }
 
+// The TCP peer, as THIS process sees it — a transport fact, never a header. Only
+// the parent can observe it (the worker's own socket is a pipe), so it is carried
+// to the worker in its own IPC field and re-attached there as
+// req.socket.remoteAddress. Absent/blank is passed through as '' so the worker
+// can leave the request exactly as it was before this feature.
+function readClientAddress(req) {
+  const address = req && req.socket ? req.socket.remoteAddress : undefined;
+  return typeof address === 'string' ? address : '';
+}
+
+// The counter's own refusal shape, written by this process when it refuses a
+// request BEFORE the IPC hop (oversized body) or because the hop failed. Same
+// headers and the same four generic messages the handler in the worker uses, so a
+// caller cannot tell where the refusal came from, and no internal detail (a driver
+// message, a timeout code, a stack) ever reaches the wire.
+//
+// `extraHeaders` exists for the one refusal that answers while the client may
+// still be uploading (the 413): it asks for the connection to be closed by the
+// normal HTTP means instead of tearing the socket down mid-body.
+function sendCounterFailure(res, status, error, extraHeaders) {
+  if (res.headersSent) return;
+  const payload = JSON.stringify({ error });
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+    'Cache-Control': 'no-store',
+    'Vary': 'Origin',
+    ...(extraHeaders || {}),
+  });
+  res.end(payload);
+}
+
 class TelemetryProcessClient {
   constructor(options = {}) {
     this.workerPath = options.workerPath || path.join(__dirname, '..', 'workers', 'telemetry-worker.js');
@@ -155,6 +192,11 @@ class TelemetryProcessClient {
   }
 
   proxy(req, res, url) {
+    // The public blog counter shares this transport but not its limits: its body
+    // cap (1024 B) is enforced here, on the parent side, BEFORE any IPC work —
+    // the generic telemetry routes keep the 2 MiB bound unchanged.
+    const counterRoute = isBlogViewsPath(url.pathname);
+    const maxRequestBytes = counterRoute ? BLOG_VIEW_MAX_BODY_BYTES : MAX_REQUEST_BYTES;
     const chunks = [];
     let bytes = 0;
     let rejected = false;
@@ -171,12 +213,27 @@ class TelemetryProcessClient {
             'x-forwarded-for': req.headers['x-forwarded-for'],
             'x-real-ip': req.headers['x-real-ip'],
             origin: req.headers.origin,
+            // WP-1: the counter's bot filter reads the UA and its limiter prefers
+            // Fly-Client-IP when (and only when) the child really is a Fly app.
+            // Forwarded for this one route only, so the existing telemetry routes
+            // keep answering from exactly the headers they saw before.
+            ...(counterRoute ? {
+              'user-agent': req.headers['user-agent'],
+              'fly-client-ip': req.headers['fly-client-ip'],
+            } : {}),
           },
+          ...(counterRoute ? { clientAddress: readClientAddress(req) } : {}),
           body: chunks.length ? Buffer.concat(chunks).toString('base64') : '',
         });
         res.writeHead(response.status || 200, response.headers || {});
         res.end(response.body || '');
       } catch (error) {
+        if (counterRoute) {
+          // A transport/queue/timeout failure is a 503 with the counter's generic
+          // body — never the internal error code or message.
+          sendCounterFailure(res, 503, 'View count unavailable');
+          return;
+        }
         const status = error.code === 'WALL_E_TELEMETRY_REQUEST_TOO_LARGE' ? 413 : 503;
         res.writeHead(status, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: error.message, code: error.code, retry_after_ms: 500 }));
@@ -185,8 +242,20 @@ class TelemetryProcessClient {
     req.on('data', chunk => {
       if (rejected) return;
       bytes += chunk.length;
-      if (bytes > MAX_REQUEST_BYTES) {
+      if (bytes > maxRequestBytes) {
         rejected = true;
+        if (counterRoute) {
+          // Over-cap counter body: the refusal is written and the connection is
+          // ended by the protocol, NEVER by destroying the socket out from under
+          // the response. `req.destroy()` here raced the JSON write — a client on
+          // a real connection could see a TCP reset instead of the complete
+          // 'payload_too_large' document. Connection: close is enough: the
+          // `rejected` flag above already stops every further chunk from being
+          // buffered, so the unread remainder cannot grow this process, and Node
+          // tears the socket down itself once the response is flushed.
+          sendCounterFailure(res, 413, 'payload_too_large', { Connection: 'close' });
+          return;
+        }
         res.writeHead(413, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Telemetry request exceeds 2 MiB' }));
         req.destroy();
@@ -198,6 +267,12 @@ class TelemetryProcessClient {
     req.on('error', error => {
       if (rejected) return;
       rejected = true;
+      if (counterRoute) {
+        // An aborted upload is a client problem: the counter's malformed-payload
+        // answer, with no detail about the transport failure.
+        sendCounterFailure(res, 400, 'invalid_payload');
+        return;
+      }
       res.writeHead(400, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: error.message }));
     });

package/template/wall-e/llm/default-fallback.js

@@ -523,6 +523,10 @@ module.exports = {
     shouldFallThroughClass,
     _configFromRow,
     _hasEnvKey,
+    // The provider-type -> credential-env-var map _hasEnvKey reads. Exported so a fixture can
+    // clear exactly the keys that decide whether an env-only provider candidate exists (the D-2
+    // seed reads the same map through routing-policy.js envCandidate).
+    _ENV_KEY_BY_TYPE,
     TRANSIENT_CLASSES,
     FALLTHROUGH_CLASSES,
   },

package/template/wall-e/llm/model-catalog.js

@@ -19,7 +19,7 @@ const modelFactsCore = require('../lib/model-facts-core');
 const { resolveReasoningControl, intersectReasoningControls } = require('./reasoning-control');
 const { policyRankFor: routeRankPolicyStage } = require('./route-rank');
 // D-5: llm/worker-route.js is a cycle-free leaf (node builtins + ./portkey + ../../shared/*).
-const { reasoningParamsForRoute, routeReasoningLevels } = require('./worker-route');
+const { reasoningParamsForRoute, routeReasoningLevels, routeModelReasoningLevels } = require('./worker-route');
 const {
   KNOWN_MAKER_TYPES,
   canonicalModelId,
@@ -273,8 +273,15 @@ function groupSessionRows(models, providerById, live) {
       // the registry row; a row without it (join absent, non-identity row)
       // carries ''.
       region: String(row.identity_region || ''),
-      // D-5 (§6.3): the route's CLI effort levels, off the one definition.
-      reasoning_levels: Array.isArray(provider.reasoning_levels) ? provider.reasoning_levels.slice() : [],
+      // D-1/D-2 (§6): the route's CLI effort levels for THIS route's model id,
+      // off the one producer (llm/worker-route.js routeModelReasoningLevels) --
+      // an anthropic-messages passthrough route publishes the Claude matrix for
+      // `modelId` instead of the empty chat-translate fragment map.
+      reasoning_levels: routeModelReasoningLevels({
+        type: String(provider.type || '').toLowerCase(),
+        upstream_apis: Array.isArray(provider.upstream_apis) ? provider.upstream_apis : [],
+        model_id: modelId,
+      }),
       reasoning_control: resolveReasoningControl({ providerType, modelId }),
     };
 
@@ -442,8 +449,10 @@ function normalizeSessionProvider(provider = {}) {
     // is routable at all. getProviderWithMeta (http/model-admin.js) stamps
     // both on every provider row before it reaches the catalog build.
     upstream_apis: Array.isArray(provider.upstream_apis) ? provider.upstream_apis.slice() : [],
-    // D-5 (§6.3): the CLI effort levels this route can carry upstream — the one
+    // D-5 (§6.3): the CLI effort levels this provider can carry upstream — the one
     // definition (llm/worker-route.js routeReasoningLevels) over its upstream APIs.
+    // Route-wide and model-less on purpose (D-3): the per-model value the picker
+    // reads lives on each catalog route instead (groupSessionRows above).
     reasoning_levels: routeReasoningLevels(reasoningParamsForRoute(String(provider.type || '').toLowerCase(), Array.isArray(provider.upstream_apis) ? provider.upstream_apis : [])),
     routable: provider.routable !== false,
     // D-7 (§6.3): why a routable:false provider cannot serve a worker — the

package/template/wall-e/llm/model-roles.js

@@ -35,6 +35,8 @@ const TASK_ROLE = Object.freeze({
   'approval-review': 'background',
   'approval-ai-refinement': 'background',
   'approval-scenario-classify': 'background',
+  'lead-wait-watch': 'background', // WP-1 worker-wait watcher tick (pinned to the worker's own route:model; the role is never consulted)
+  'explore-handoff-grade': 'background', // WP-6 spot-check grader (pinned to helper_rules.grader_model; the role is never consulted)
   // user-triggered, single completion
   'meeting-notes': 'chat',
   'dictation-refine': 'chat',
@@ -261,6 +263,10 @@ async function completeForRole({
   const role = resolution.role;
   const ledgerWrite = _writeLedger(brain, {
     source, feature, requestId, providerType, providerId, modelId, usage: response?.usage, latencyMs,
+    // WP-4b (D-9, S-19): the caller's sessionId (CTM sends the watched worker's ctm_session_id for
+    // a `lead-wait-watch` tick) is stored on the row, so watcher spend is readable per cell. A
+    // caller that passes nothing keeps today's NULL.
+    sessionId,
     stopReason: response?.stopReason || null,
     metadata: { taskType: task, role, tier, pinSource: resolution.source, fallbackFrom },
   });

package/template/wall-e/llm/portkey-http.js

@@ -0,0 +1,150 @@
+'use strict';
+// Portkey HTTP transport: one bounded, redirect-safe, retrying JSON fetch for every
+// request in the Portkey path (sync, discovery, catalog, resolver). Extracted verbatim
+// from llm/portkey-sync.js (WP-0 of docs/codex-routed-fork-cold-restore-guard-2026-10-22.html)
+// so that file stays under its size ceiling; the contract (D-1 transient classes,
+// D-2 retry engine + test seam, manual redirects) is unchanged.
+const { redactSecrets } = require('./provider-error');
+const { createRetryPolicy } = require('../lib/kernel/retry-policy');
+
+// D-2: TOTAL attempts for a transient failure, with the backoff between them.
+const PORTKEY_REQUEST_ATTEMPTS = 3;
+const PORTKEY_RETRY_DELAYS_MS = [1000, 3000];
+const PORTKEY_RETRY_AFTER_MAX_MS = 30 * 1000;
+
+// WP-1 review R6: this is the ONLY request budget in the Portkey path, and it
+// is per REQUEST, not per host — callers that must bound a whole host (the
+// resolver) also cap the number of pages. There is deliberately no
+// AbortController+setTimeout fallback when `AbortSignal.timeout` is missing:
+// that would be a recovery timer, which `stabilization-lint` requires to be
+// registered in release/ownership-registry.json and which this feature's
+// design forbids. `AbortSignal.timeout` is Node >= 17.3 and this repo pins
+// v25.2.1, so the fallback branch below is unreachable in practice; if it is
+// ever reached the request is unbounded and the caller's page cap is what
+// stops it.
+function withTimeout(timeoutMs) {
+  if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout && Number.isFinite(timeoutMs)) {
+    return { signal: AbortSignal.timeout(timeoutMs) };
+  }
+  return {};
+}
+
+async function safeJson(response) {
+  try { return await response.json(); } catch { return null; /* expected: non-JSON or empty error body; callers fall back to a generic message */ }
+}
+
+// D-2 test seam: when set, createRetryPolicy uses it instead of the kernel's
+// own registered timer. null (default) means "use the kernel sleep".
+let _retrySleepOverride = null;
+
+function _setRetrySleepForTest(fn) {
+  _retrySleepOverride = typeof fn === 'function' ? fn : null;
+}
+
+// D-1: TRANSIENT iff no response at all (status 0) or 408/429/5xx; every other
+// status (3xx/401/403/AB03/033/other 4xx) is DEFINITIVE and never retried.
+function isTransientStatus(status) {
+  if (status === 0) return true;
+  const code = Number(status);
+  return code === 408 || code === 429 || (code >= 500 && code <= 599);
+}
+
+// D-2: honour Retry-After only as integer seconds ≤ 30 s; else fixed backoff.
+function retryAfterMs(response) {
+  if (!response || typeof response.headers?.get !== 'function') return null;
+  const raw = response.headers.get('retry-after');
+  if (raw == null) return null;
+  const seconds = Number(String(raw).trim());
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  const ms = seconds * 1000;
+  return ms <= PORTKEY_RETRY_AFTER_MAX_MS ? ms : null;
+}
+
+function errorCodeFromBody(body) {
+  if (!body || typeof body !== 'object') return '';
+  if (body.data && body.data.errorCode) return String(body.data.errorCode);
+  if (body.error && body.error.code) return String(body.error.code);
+  return '';
+}
+
+function errorMessageFromBody(body, fallback) {
+  if (body && typeof body === 'object') {
+    if (body.data && body.data.message) return String(body.data.message);
+    if (body.message) return String(body.message);
+  }
+  return fallback;
+}
+
+// `redirect: 'manual'` is the DEFAULT here, for EVERY request in the Portkey
+// path — not only the resolver's probe (final review, finding #3). Every one
+// carries the full gateway key in `x-portkey-api-key`, and undici keeps that
+// header across a cross-origin redirect, so following a 3xx would hand the key
+// to a host the user never named (the axios GHSA-jr5f-v2jv-69x6 class). With
+// `manual` a 3xx is not followed and `response.ok` is false, so it surfaces as
+// `{ok:false, status:3xx}` — a verdict, never a second request.
+// `fetchInit` (WP-1): extra init the CALLER owns — today the resolver's
+// per-host AbortController signal. Spread last so it replaces withTimeout's.
+// D-2: ONE attempt; returns today's ok/failure shape plus the response's
+// Retry-After (null when the fetch threw — a transport failure has no headers).
+async function fetchJsonOnce(fetchFn, url, { headers, timeoutMs, fallbackMessage, fetchInit } = {}) {
+  try {
+    const response = await fetchFn(url, { headers, redirect: 'manual', ...withTimeout(timeoutMs), ...(fetchInit || {}) });
+    const body = await safeJson(response);
+    if (response.ok) return { result: { ok: true, status: response.status, body }, retryAfter: null };
+    return {
+      result: {
+        ok: false,
+        status: response.status,
+        code: errorCodeFromBody(body),
+        message: redactSecrets(errorMessageFromBody(body, fallbackMessage(response.status))),
+      },
+      retryAfter: retryAfterMs(response),
+    };
+  } catch (err) {
+    // D-1: no HTTP response at all (status 0 — transport/timeout) is transient.
+    const message = err && err.message ? err.message : String(err);
+    return { result: { ok: false, status: 0, code: '', message: redactSecrets(message) }, retryAfter: null };
+  }
+}
+
+// D-2: transient failures are retried through wall-e's ONE retry engine
+// (lib/kernel/retry-policy.js); a caller owning its own abort signal (the
+// resolver's single probe) is single-shot and never retries.
+async function fetchJsonOrError(fetchFn, url, opts = {}) {
+  if (opts.fetchInit) {
+    const { result } = await fetchJsonOnce(fetchFn, url, opts);
+    if (result.ok) return result;
+    const transient = isTransientStatus(result.status);
+    return transient ? { ...result, transient, attempts: 1 } : { ...result, transient };
+  }
+  let nextDelay = null;
+  let lastAttempt = 1;
+  const policyOptions = {
+    maxAttempts: PORTKEY_REQUEST_ATTEMPTS,
+    jitter: 0,
+    delayFn: (attempt) => nextDelay ?? PORTKEY_RETRY_DELAYS_MS[attempt - 1],
+    classify: (err) => (err && err.portkeyTransient ? 'transient' : 'permanent'),
+    layer: 'portkey-sync',
+    operation: 'fetch',
+  };
+  // Only override the kernel's own registered timer when a test seam is set.
+  if (_retrySleepOverride) policyOptions.sleep = (ms) => _retrySleepOverride(ms);
+  const policy = createRetryPolicy(policyOptions);
+  try {
+    return await policy.run(async (attempt) => {
+      const { result, retryAfter } = await fetchJsonOnce(fetchFn, url, opts);
+      if (result.ok || !isTransientStatus(result.status)) {
+        return result.ok ? result : { ...result, transient: false };
+      }
+      nextDelay = retryAfter;
+      lastAttempt = attempt;
+      throw Object.assign(new Error(result.message), { portkeyTransient: true, result });
+    });
+  } catch (err) {
+    // Only our transient sentinel is converted; anything else propagates.
+    if (!err || !err.portkeyTransient) throw err;
+    return { ...err.result, transient: true, attempts: lastAttempt };
+  }
+}
+
+module.exports = { fetchJsonOrError, fetchJsonOnce, safeJson, isTransientStatus, _setRetrySleepForTest };