@animalabs/agent-framework 0.26.2 → 0.27.0

package/src/mcpl/reference-fetcher.ts

@@ -25,15 +25,23 @@
  * Autofetch policy (host default, not protocol): eager only below
  * DEFAULT_EAGER_FETCH_MAX_BYTES from the connection origin — anything under
  * that threshold the server could legitimately have inlined, so eager
- * materialization is never worse than the status quo. Everything larger is
- * fetched on demand (the fetch_reference tool, or the code-execution result
- * hook, where a script receiving a result is the strongest available signal
- * that the bytes are wanted). Per-server budgets cap cumulative appetite.
+ * materialization is never worse than the status quo for a reference whose
+ * claim is true. A fetch the eager default starts reads no further than the
+ * first chunk past its server's eager limit (autofetch.maxBytes, this
+ * default when that's unset), whatever size the server claims; one it joins
+ * is its starter's, whose success answers it too. The eager default doesn't
+ * choose a reference again once its fetch of it failed. Everything larger
+ * is fetched on demand (the fetch_reference tool, or the code-execution
+ * result hook, where a script receiving a result is the strongest available
+ * signal that the bytes are wanted). Per-server budgets cap cumulative
+ * appetite.
  */
 import { createHash } from 'node:crypto';
-import type { ReferenceRecord } from './references.js';
+import type { ReferenceRecord, Refusal, ServerAddress } from './references.js';
 import { boundedForLog, describeCause } from './errors.js';
-import { EXPIRY_REASON, noAddressReason, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel, UNBOUND_REASON } from './references.js';
+import { dialCheck, dialServer, FRESH_REFERENCE, NOTHING_TO_DO, REFERENCE_LIMITS, sanitizeLabel, shownServerId } from './references.js';
+
+export { normalizedOrigin, type Refusal } from './references.js';
 
 /** Per-fetch hard ceiling on actual bytes. A call can lower it for itself
  *  (fetch_reference's max_bytes, which it clamps to this); nothing raises it. */
@@ -44,17 +52,18 @@ export const DEFAULT_EAGER_FETCH_MAX_BYTES = 256 * 1024;
  *  through a server reads counts against that server's, whether or not it's
  *  kept. */
 export const DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
+/** How long a caller waits for a fetch, its save included, unless it asks
+ *  for another time. */
 const FETCH_TIMEOUT_MS = 60_000;
+/** How long the eager default waits for one reference. */
 const EAGER_FETCH_TIMEOUT_MS = 10_000;
 
 // What calling again can do, as each failure's remedy says it. The fetcher
 // doesn't know where a reference came from (a tool result, a push, a channel
 // message), so none names a tool, and fetch_reference's max_bytes is named
-// only where a larger one can fetch it.
-const NOTHING_TO_DO = "Calling again won't change that.";
-/** The registry keys a record by its uri, so a fresh reference to the same
- *  uri arrives as this very id and refreshes its record. */
-const FRESH_REFERENCE = "Once a fresh reference to it arrives, fetching may work; until then, fetching it again won't.";
+// only where a larger one can fetch it. The refusals before dialing that a
+// stub shares come from references.ts (dialServer, dialCheck) with their
+// remedies (NOTHING_TO_DO, FRESH_REFERENCE, SERVER_BACK).
 const TRY_LATER = 'Trying again later may work.';
 /** A request that failed before an answer: a refused or reset connection
  *  can clear, and a cause that repeats on every try (a port fetch refuses, a
@@ -71,8 +80,6 @@ const BUDGET = "The budget doesn't renew on its own, so calling again won't chan
 /** The host's own ceiling: fetch_reference clamps max_bytes to it, and no
  *  config sets another. */
 const HOST_CEILING = "No max_bytes or setting lifts that limit, so calling again won't change it.";
-/** The resolver reads the host's server configs as they are at each fetch. */
-const SERVER_BACK = "Calling again won't change that unless whoever runs this host adds that server back.";
 
 export interface ResolvedServerBinding {
   /** The url the host dials the server at. The framework's resolver gives only
@@ -90,18 +97,6 @@ export interface ResolvedServerBinding {
  *  know resolves to undefined. */
 export type ServerResolution = ResolvedServerBinding | 'no-address';
 
-/** Why a fetch failed, or would be refused before dialing. */
-export interface Refusal {
-  /** What happened, as a clause that completes "couldn't fetch <ref>: ",
-   *  whatever it's about: fetch_reference's sentence, save_recent_image's,
-   *  and the eager and script-demand fetches' log lines read it. */
-  error: string;
-  /** What calling again can do, as a sentence. fetch_reference and
-   *  save_recent_image show it; the eager and script-demand fetches log the
-   *  error alone. */
-  remedy: string;
-}
-
 /** A fetch's result: the saved copy, or why it failed, which every failure
  *  says with both a clause and a remedy. The fields the other side lacks are
  *  declared undefined, so a caller can read them before checking ok. */
@@ -116,10 +111,49 @@ export type FetchOutcome =
     error?: undefined;
     remedy?: undefined;
   }
-  | ({ ok: false; path?: undefined; bytes?: undefined; mimeType?: undefined; digestVerified?: undefined } & Refusal);
+  | ({ ok: false; path?: undefined; bytes?: undefined; mimeType?: undefined; digestVerified?: undefined } & Pick<Refusal, 'error' | 'remedy'>);
 
 const refused = (error: string, remedy: string): { refusal: Refusal } => ({ refusal: { error, remedy } });
 const fail = (error: string, remedy: string): FetchOutcome => ({ ok: false, error, remedy });
+/** A timeout, naming the timeout that ran out: its starter's, when the
+ *  fetch is aborted at its deadline, or a caller's own, when its wait ends
+ *  while the fetch or its save goes on. */
+function tookLonger(timeoutMs: number): FetchOutcome {
+  const seconds = timeoutMs / 1000;
+  return fail(`it took longer than ${seconds} second${seconds === 1 ? '' : 's'}`, TRY_LATER);
+}
+
+/** The two endings that name a call's own byte ceiling, as a function of it,
+ *  so a caller that joined a fetch is told its own ceiling, not its
+ *  starter's. */
+const claimOver = (claimed: number) => (ceiling: number): string =>
+  `it claims ${claimed} bytes, over the ${ceiling} bytes this call allows`;
+const readPast = (received: number) => (ceiling: number): string =>
+  `the download had reached ${received} bytes, past the ${ceiling} bytes this call allows, so it was stopped and nothing was kept`;
+
+/** How a fetch ended, with the bound of its starter's it stopped on, if any:
+ *  its byte ceiling, which a claim over it reaches before dialing too, or its
+ *  deadline. A caller that takes a ceiling ending is told its own ceiling
+ *  (atCeiling). A deadline ending names its starter's timeout, which ran out
+ *  unanswered, so it holds for every caller that takes it. */
+type Ended = FetchOutcome & { stoppedBy?: 'ceiling' | 'deadline'; atCeiling?: (ceiling: number) => string };
+
+/** A fetch in flight, under the bounds of the caller that started it: its
+ *  byte ceiling and its timeout. */
+interface Flight {
+  ended: Promise<Ended>;
+  ceiling: number;
+  timeoutMs: number;
+}
+
+/** What the promise settles to, or undefined if the deadline, on the
+ *  monotonic clock, comes first. */
+function settledBy<T>(promise: Promise<T>, deadline: number): Promise<T | undefined> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => resolve(undefined), Math.max(0, deadline - performance.now()));
+    promise.finally(() => clearTimeout(timer)).then(resolve, reject);
+  });
+}
 
 /** What calling again can do about a server's HTTP status. A later try can
  *  work after a timeout, a conflict or lock the server's state can clear, a
@@ -191,101 +225,107 @@ const EXT_BY_MIME = new Map<string, string>(Object.entries({
   'application/pdf': 'pdf', 'application/zip': 'zip',
 }));
 
-/** A server's address as it's configured, its scheme and host, for a
- *  clause: never its userinfo, path or query. URL's own origin is 'null' for
- *  a scheme that isn't special, which normalizedOrigin accepts. The caller
- *  has already parsed it. */
-function configuredOrigin(url: string): string {
-  const u = new URL(url);
-  return `${u.protocol}//${u.host}`;
-}
-
-/** ws→http / wss→https with default ports elided, for origin comparison. */
-export function normalizedOrigin(url: string): string | null {
-  try {
-    const u = new URL(url);
-    const scheme = u.protocol === 'ws:' ? 'http:' : u.protocol === 'wss:' ? 'https:' : u.protocol;
-    const defaultPort = scheme === 'https:' ? '443' : '80';
-    const port = u.port === '' || u.port === defaultPort ? '' : `:${u.port}`;
-    return `${scheme}//${u.hostname.toLowerCase()}${port}`;
-  } catch {
-    return null;
-  }
-}
-
 export class ReferenceFetcher {
   /** Bytes read through each server in this process, charged to the server a
    *  fetch dials through as each chunk is read, kept or not. Concurrent
    *  fetches through one server share the total, so each checks what the
    *  others have taken. */
   private totals = new Map<string, number>();
-  private inFlight = new Map<string, Promise<FetchOutcome>>();
+  private inFlight = new Map<string, Flight>();
 
   constructor(
+    /** A server's address, credential and limits, by id, from the
+     *  framework's own config: the origin a fetch is checked against and the
+     *  token it carries come from one answer. */
     private readonly resolveServer: (serverId: string) => ServerResolution | undefined,
     /** Persist the payload; returns a mount-prefixed path or null when no
      *  writable mount without an include exists. File name is host-generated (§7.3). */
     private readonly saveFile: (fileName: string, data: Buffer, mimeType: string) => Promise<string | null>,
   ) {}
 
-  /** Would the eager (autofetch) default fetch this record? Not one the fetch
-   *  would refuse before dialing, asked as the eager fetch asks it, with the
-   *  default ceiling, so such a record takes no eager slot; and only one whose
-   *  claimed size is within the eager limit of the server it dials. For one
-   *  whose fetch is already under way, which the eager fetch would join as
-   *  fetch() does, only the server and its eager limit enter: the expiry,
-   *  the budget and the ceiling were checked when that fetch began. */
+  /** The server a check (dialServer or dialCheck) chose, with its credential
+   *  and limits from the same resolver answer whose address the check read:
+   *  each server's resolution is read once here, so the origin the check
+   *  passes and the token the fetch sends come from one answer, whatever a
+   *  resolver answers the next time it's asked. */
+  private chosen(
+    check: (addressOf: (serverId: string) => ServerAddress | undefined) => { serverId: string } | { refusal: Refusal },
+  ): { serverId: string; binding: ResolvedServerBinding } | { refusal: Refusal } {
+    const resolutions = new Map<string, ServerResolution | undefined>();
+    const addressOf = (serverId: string): ServerAddress | undefined => {
+      if (!resolutions.has(serverId)) resolutions.set(serverId, this.resolveServer(serverId));
+      const resolution = resolutions.get(serverId);
+      return resolution === undefined || resolution === 'no-address' ? resolution : { url: resolution.url };
+    };
+    const server = check(addressOf);
+    if ('refusal' in server) return server;
+    // The check chose only a server whose address it read as a url, so that
+    // server's resolution is a binding.
+    return { serverId: server.serverId, binding: resolutions.get(server.serverId) as ResolvedServerBinding };
+  }
+
+  /** The server a fetch of a record dials (§6.2), with its credential and
+   *  limits, or why none can be. */
+  private serverFor(record: ReferenceRecord): { serverId: string; binding: ResolvedServerBinding } | { refusal: Refusal } {
+    return this.chosen((addressOf) => dialServer(record, addressOf));
+  }
+
+  /** Would the eager (autofetch) default fetch this record? Not one whose
+   *  eager fetch already failed; not one the fetch would refuse before
+   *  dialing, asked with the default ceiling, so such a record takes no eager
+   *  slot; and only one whose claimed size is within the eager limit of the
+   *  server it dials. For one whose fetch is already under way, which the
+   *  eager fetch would join as fetch() does, only the server and its eager
+   *  limit enter: the expiry, the budget and the ceiling were checked when
+   *  that fetch began. */
   isEagerEligible(record: ReferenceRecord): boolean {
-    if (record.fetchedPath) return false;
+    if (record.fetchedPath || record.eagerFailed) return false;
     const check = this.inFlight.has(record.refId) ? this.serverFor(record) : this.beforeDial(record);
     if ('refusal' in check) return false;
-    const cap = check.binding.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
-    return record.testimony.sizeBytes !== undefined && record.testimony.sizeBytes <= cap;
+    return record.testimony.sizeBytes !== undefined && record.testimony.sizeBytes <= this.eagerLimit(check.binding);
   }
 
-  /** The server to dial for a record (§6.2): the first, in the order they
-   *  delivered it, whose address is on the uri's origin. When none is, the
-   *  first server's refusal (unknown to this host, with no address to dial,
-   *  or the origin check's), and for a record no server delivered, that it's
-   *  unbound. */
-  private serverFor(record: ReferenceRecord): { serverId: string; binding: ResolvedServerBinding } | { refusal: Refusal } {
-    let refusal: { refusal: Refusal } | undefined;
-    for (const serverId of record.serverIds) {
-      const binding = this.resolveServer(serverId);
-      if (!binding) {
-        refusal ??= refused(`this host no longer has the "${serverId}" server it came from`, SERVER_BACK);
-        continue;
-      }
-      if (binding === 'no-address') {
-        refusal ??= refused(noAddressReason(serverId), NOTHING_TO_DO);
-        continue;
-      }
-      const offOrigin = this.originCheck(record, binding, serverId);
-      if (offOrigin === null) return { serverId, binding };
-      refusal ??= offOrigin;
-    }
-    // A later delivery of the same uri by a server binds this record.
-    return refusal ?? refused(`it's ${UNBOUND_REASON}`, FRESH_REFERENCE);
+  /** The eager default's fetch. One it starts reads no further than the first
+   *  chunk past the server's eager limit, whatever size the reference claims;
+   *  one it joins reads under its starter's ceiling, and that fetch's success
+   *  answers it too (fetch()). It waits no longer than
+   *  EAGER_FETCH_TIMEOUT_MS. One that fails is remembered on the record, so
+   *  the eager default doesn't choose that reference again; fetch_reference
+   *  still fetches it. */
+  async fetchEager(record: ReferenceRecord): Promise<FetchOutcome> {
+    const server = this.serverFor(record);
+    const maxBytes = this.eagerLimit('refusal' in server ? undefined : server.binding);
+    const outcome = await this.fetch(record, { maxBytes, timeoutMs: EAGER_FETCH_TIMEOUT_MS });
+    if (!outcome.ok) record.eagerFailed = true;
+    return outcome;
+  }
+
+  /** This server's eager limit: its autofetch.maxBytes,
+   *  DEFAULT_EAGER_FETCH_MAX_BYTES when that's unset. Eligibility holds a
+   *  claim to it, and a fetch the eager default starts stops reading at the
+   *  first chunk past it. The host's own ceiling, which every fetch checks
+   *  first, still holds past a larger one. */
+  private eagerLimit(binding: ResolvedServerBinding | undefined): number {
+    return binding?.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
   }
 
   /** Every check the fetch makes before it dials, in its order: the server
    *  (none, unknown, no address, an address of its own or the reference's
    *  that doesn't parse, a reference address carrying a user name or
-   *  password, a scheme other than http: or https:, off the uri's origin),
-   *  the expiry, a claimed size over the host's own ceiling, the server's
-   *  spent budget, a claimed size over a call's ceiling. For a record with no
-   *  saved copy and no fetch under way, the fetch, `refusal()` and the eager
-   *  check all ask this, so what save_recent_image says is the reason the
-   *  fetch would refuse with, and no eager slot goes to a fetch that would be
-   *  refused. */
+   *  password, a scheme other than http: or https:, off the uri's origin)
+   *  and the expiry, which dialCheck makes as a reference's stub does; then
+   *  a claimed size over the host's own ceiling, the server's spent budget,
+   *  a claimed size over a call's ceiling. For a record with no saved copy
+   *  and no fetch under way, the fetch, `refusal()` and the eager check all
+   *  ask this, so what save_recent_image says is the reason the fetch would
+   *  refuse with, and no eager slot goes to a fetch that would be refused. */
   private beforeDial(record: ReferenceRecord, opts?: { maxBytes?: number }):
-    { refusal: Refusal } | { serverId: string; binding: ResolvedServerBinding; ceiling: number; budget: number } {
-    const server = this.serverFor(record);
+    { refusal: Refusal; byCeiling?: true; atCeiling?: (ceiling: number) => string } |
+    { serverId: string; binding: ResolvedServerBinding; ceiling: number; budget: number } {
+    const server = this.chosen((addressOf) => dialCheck(record, addressOf));
     if ('refusal' in server) return server;
     const { serverId, binding } = server;
     const t = record.testimony;
-    const expiry = referenceExpiry(t);
-    if (expiry) return refused(`the reference is ${EXPIRY_REASON[expiry]}`, FRESH_REFERENCE);
 
     const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
     // A claim past the host's own ceiling is refused first: nothing lifts
@@ -299,23 +339,29 @@ export class ReferenceFetcher {
     const budget = binding.autofetch?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
     const used = this.totals.get(serverId) ?? 0;
     if (used >= budget) {
-      return refused(`this host's fetch budget for the "${serverId}" server is used up (${used} of ${budget} bytes)`, BUDGET);
+      return refused(`this host's fetch budget for the "${shownServerId(serverId)}" server is used up (${used} of ${budget} bytes)`, BUDGET);
     }
     // Vector 4: a claim already over the ceiling refuses without dialing. One
     // that's also over what's left of the budget is told about the budget,
     // which no max_bytes lifts. A claim over what's left but within the
     // ceiling still dials, and the budget stops it at its first chunk past.
+    // Both refusals here are reached only through the call's own ceiling, so
+    // each is that ceiling's ending: a caller whose ceiling holds the claim
+    // would dial, and one that joined this call's fetch does (fetch()).
     if (t.sizeBytes !== undefined && t.sizeBytes > ceiling) {
       if (t.sizeBytes > budget - used) {
-        return refused(
-          `it claims ${t.sizeBytes} bytes, more than the ${budget - used} bytes left of this host's fetch budget for the "${serverId}" server`,
-          BUDGET,
-        );
+        return {
+          ...refused(
+            `it claims ${t.sizeBytes} bytes, more than the ${budget - used} bytes left of this host's fetch budget for the "${shownServerId(serverId)}" server`,
+            BUDGET,
+          ),
+          byCeiling: true,
+        };
       }
       // Within what's left of the budget and the host's ceiling, so a
       // ceiling of the call's own is what a larger max_bytes lifts.
-      return refused(`it claims ${t.sizeBytes} bytes, over the ${ceiling} bytes this call allows`,
-        `Pass max_bytes of at least ${t.sizeBytes} to fetch it.`);
+      const atCeiling = claimOver(t.sizeBytes);
+      return { ...refused(atCeiling(ceiling), `Pass max_bytes of at least ${t.sizeBytes} to fetch it.`), byCeiling: true, atCeiling };
     }
     return { serverId, binding, ceiling, budget };
   }
@@ -331,67 +377,63 @@ export class ReferenceFetcher {
     return 'refusal' in check ? check.refusal : null;
   }
 
-  /** §6.1/§7.1 policy check; returns a refusal or null. */
-  private originCheck(record: ReferenceRecord, binding: ResolvedServerBinding, serverId: string): { refusal: Refusal } | null {
-    const refOrigin = normalizedOrigin(record.testimony.uri);
-    if (!refOrigin) return refused("its address doesn't parse as a URL", NOTHING_TO_DO);
-    // A server's address that doesn't parse leaves nothing to dial. The
-    // framework's resolver gives only an address its transport dials, so this
-    // guards other resolvers.
-    const dialedOrigin = normalizedOrigin(binding.url);
-    if (!dialedOrigin) {
-      return refused(`the "${serverId}" server's address doesn't parse as a URL, so there's nowhere to fetch it from`,
-        "Calling again won't change that unless whoever runs this host corrects the server's address.");
-    }
-    const refUrl = new URL(record.testimony.uri);
-    // A user name or password in the uri is a credential embedded in it,
-    // which RFC-005 §6.1 forbids a server to mint and lets a host refuse
-    // (vector 6). This host neither sends nor repeats it: fetch refuses such
-    // a url with a message that holds it whole.
-    if (refUrl.username !== '' || refUrl.password !== '') {
-      return refused("its address carries a user name or password, which this host doesn't send", NOTHING_TO_DO);
-    }
-    // The uri's own scheme, not its origin's: an origin reads ws: as http:
-    // and wss: as https:, and fetch refuses a ws: or wss: uri ('unknown
-    // scheme') before connecting, which would read as a failed request a
-    // later try can mend.
-    const scheme = refUrl.protocol;
-    if (scheme !== 'https:' && scheme !== 'http:') {
-      return refused(`its address uses ${scheme}, and this host fetches only http: and https: addresses`, NOTHING_TO_DO);
-    }
-    // Origins compare with their schemes, so this also refuses an http:
-    // reference from a server dialed over TLS (wss://).
-    if (refOrigin !== dialedOrigin) {
-      return refused(`it points to ${refOrigin}, not to the "${serverId}" server's own address (${configuredOrigin(binding.url)}), ` +
-        'and this host fetches only from the server itself', NOTHING_TO_DO);
+  /** Fetch a reference to workspace storage. Idempotent per record. Callers
+   *  of one record share the fetch in flight, each under its own bounds: it
+   *  waits no longer than its own timeout, counted from its call and covering
+   *  the save. When the fetch it joined stopped on its starter's byte ceiling
+   *  and its own is wider, it fetches again under its own. When that fetch
+   *  stopped at its starter's deadline, it fetches again only if it has more
+   *  time left than that starter's whole timeout, since a fresh fetch with no
+   *  more time than one that ran out unanswered would likely be stopped too;
+   *  otherwise it takes that ending. (A refetch's flight had less than its
+   *  starter's timeout, so this errs toward not dialing.) A fetch that
+   *  succeeds answers every caller waiting on it, whatever its own ceiling. A
+   *  save still running when a caller stops waiting goes on, and the record
+   *  is marked fetched when it lands. */
+  async fetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
+    const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
+    const timeoutMs = opts?.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const deadline = performance.now() + timeoutMs;
+    for (;;) {
+      if (record.fetchedPath) {
+        return { ok: true, path: record.fetchedPath, bytes: record.verifiedBytes,
+          mimeType: record.verifiedMimeType, digestVerified: record.digestVerified };
+      }
+      const flight = this.inFlight.get(record.refId) ?? this.start(record, ceiling, deadline, timeoutMs);
+      const ended = await settledBy(flight.ended, deadline);
+      if (ended === undefined) return tookLonger(timeoutMs);
+      const { stoppedBy, atCeiling, ...outcome } = ended;
+      if (stoppedBy === 'ceiling') {
+        if (ceiling > flight.ceiling) continue;
+        return (atCeiling ? { ...outcome, error: atCeiling(ceiling) } : outcome) as FetchOutcome;
+      }
+      if (stoppedBy === 'deadline' && deadline - performance.now() > flight.timeoutMs) continue;
+      return outcome as FetchOutcome;
     }
-    return null;
   }
 
-  /** Fetch a reference to workspace storage. Idempotent per record; concurrent
-   *  callers share one in-flight fetch. */
-  fetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
-    if (record.fetchedPath) {
-      return Promise.resolve({ ok: true, path: record.fetchedPath, bytes: record.verifiedBytes,
-        mimeType: record.verifiedMimeType, digestVerified: record.digestVerified });
-    }
-    const existing = this.inFlight.get(record.refId);
-    if (existing) return existing;
-    const p = this.doFetch(record, opts).finally(() => this.inFlight.delete(record.refId));
-    this.inFlight.set(record.refId, p);
-    return p;
+  private start(record: ReferenceRecord, ceiling: number, deadline: number, timeoutMs: number): Flight {
+    const flight: Flight = {
+      ceiling,
+      timeoutMs,
+      ended: this.doFetch(record, ceiling, deadline, timeoutMs).finally(() => this.inFlight.delete(record.refId)),
+    };
+    this.inFlight.set(record.refId, flight);
+    return flight;
   }
 
-  private async doFetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
+  private async doFetch(record: ReferenceRecord, ceiling: number, deadline: number, timeoutMs: number): Promise<Ended> {
     const t = record.testimony;
-    const check = this.beforeDial(record, opts);
-    if ('refusal' in check) return { ok: false, ...check.refusal };
-    const { serverId, binding, ceiling, budget } = check;
-    const server = `the "${serverId}" server`;
+    const check = this.beforeDial(record, { maxBytes: ceiling });
+    if ('refusal' in check) {
+      const refusal = fail(check.refusal.error, check.refusal.remedy);
+      return check.byCeiling ? { ...refusal, stoppedBy: 'ceiling', atCeiling: check.atCeiling } : refusal;
+    }
+    const { serverId, binding, budget } = check;
+    const server = `the "${shownServerId(serverId)}" server`;
 
-    const timeoutMs = opts?.timeoutMs ?? FETCH_TIMEOUT_MS;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => controller.abort(), Math.max(0, deadline - performance.now()));
     try {
       const headers: Record<string, string> = {};
       if (binding.token) headers.authorization = `Bearer ${binding.token}`;
@@ -430,8 +472,8 @@ export class ReferenceFetcher {
         }
         if (received > ceiling) {
           controller.abort();
-          return fail(`the download had reached ${received} bytes, past the ${ceiling} bytes this call allows, ` +
-            'so it was stopped and nothing was kept', largerMaxBytes(received, budget - total, server));
+          const atCeiling = readPast(received);
+          return { ...fail(atCeiling(ceiling), largerMaxBytes(received, budget - total, server)), stoppedBy: 'ceiling', atCeiling };
         }
         const buf = Buffer.from(value);
         hash.update(buf);
@@ -486,16 +528,13 @@ export class ReferenceFetcher {
       return { ok: true, path, bytes: data.length, mimeType: observedMime, digestVerified };
     } catch (e) {
       // The timer is the only abort that throws: the budget and the ceiling
-      // abort the download and return at once.
-      if ((e as Error)?.name === 'AbortError') {
-        const seconds = timeoutMs / 1000;
-        return fail(`it took longer than ${seconds} second${seconds === 1 ? '' : 's'}`, TRY_LATER);
-      }
+      // abort the download and return at once. It fires at the starter's
+      // deadline, and a caller with more time left than the starter's whole
+      // timeout fetches again (fetch()).
+      if ((e as Error)?.name === 'AbortError') return { ...tookLonger(timeoutMs), stoppedBy: 'deadline' };
       return fail(`the request to ${server} failed: ${boundedForLog(whyFetchFailed(e))}`, REQUEST_FAILED);
     } finally {
       clearTimeout(timer);
     }
   }
 }
-
-export { EAGER_FETCH_TIMEOUT_MS };