clembot-doorman 0.1.0

package/doorman/src/fit-review.mjs

@@ -0,0 +1,255 @@
+/**
+ * Fit review: does MY system need this at all?
+ *
+ * The scorecard answers "is this trustworthy", which is external, paid, and
+ * about the candidate. This answers "do I already have it", which is internal,
+ * free, and about you. It runs FIRST, so a redundant candidate never costs a
+ * cent.
+ *
+ * One model call, temperature 0, pinned model, strict JSON out.
+ *
+ * The validation below matters more than the prompt. A fit review that names a
+ * subagent you do not have, or an overlap that does not exist, is worse than no
+ * review at all: it reads as placement advice and it is fiction. So every name
+ * the model returns is checked against the inventory it was given, and a name
+ * that is not there is a rejected response, not a warning.
+ */
+
+export const FIT_VERDICTS = ['redundant', 'fits', 'needs-new-subagent', 'out-of-scope'];
+export const OVERLAP_KINDS = ['agent', 'skill', 'mcp-server', 'command'];
+
+/** Two sentences. A rationale that runs long stops being read. */
+export const MAX_RATIONALE_CHARS = 400;
+
+export class FitReviewError extends Error {
+  constructor(message, { attempts, lastResponse } = {}) {
+    super(message);
+    this.name = 'FitReviewError';
+    this.attempts = attempts;
+    this.lastResponse = lastResponse;
+  }
+}
+
+const SYSTEM = `You decide whether an agent system NEEDS a candidate capability.
+You are not judging whether the candidate is good, safe, or well built. A
+separate paid audit does that, and it only runs if you say the capability is
+needed. Your job is the cheap question that comes first: does this system
+already have this?
+
+Answer with a single JSON object and nothing else. No prose, no code fence.
+
+{
+  "verdict": "redundant" | "fits" | "needs-new-subagent" | "out-of-scope",
+  "owner": "<subagent name>" | null,
+  "rationale": "<at most two sentences>",
+  "overlaps": [ { "kind": "agent"|"skill"|"mcp-server"|"command",
+                  "name": "<exact name from the inventory>",
+                  "why": "<one clause: what it already covers>" } ]
+}
+
+Verdicts:
+- "redundant": an existing subagent, skill or configured server already covers
+  this need. Populate overlaps.
+- "fits": genuinely new capability, and one EXISTING subagent should own it.
+  Set owner to that subagent's exact name.
+- "needs-new-subagent": genuinely new capability, but no existing subagent is
+  the right home. owner must be null.
+- "out-of-scope": the system has no business doing this at all. owner null.
+
+Rules you must not break:
+- Every "name" in overlaps MUST appear verbatim in the inventory below. Never
+  invent one, and never guess at a plausible-sounding name.
+- "owner" MUST be an exact subagent name from the inventory, and MUST be null
+  unless the verdict is "fits".
+- Prefer "redundant" when coverage is genuine. Declining to spend money is the
+  point of this step, not a failure of it.
+- If the inventory says a section is UNKNOWN rather than empty, say so in the
+  rationale instead of assuming the system has nothing.`;
+
+function buildUserPrompt(candidate, inventoryBlock) {
+  return [
+    '# CANDIDATE',
+    `url or path: ${candidate.id}`,
+    `type: ${candidate.type}`,
+    `wanted for: ${candidate.needed_for || '(not stated)'}`,
+    candidate.description ? `self-described as: ${candidate.description}` : '',
+    '',
+    '# THE SYSTEM AS IT EXISTS TODAY',
+    inventoryBlock,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Pull the JSON object out of a response.
+ *
+ * Strict, with exactly one concession: a ```json fence, because models emit
+ * them constantly and rejecting that would burn a retry on a formatting habit
+ * rather than on a wrong answer. Anything else is malformed.
+ */
+export function extractJson(text) {
+  const trimmed = (text ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'empty response' };
+
+  const fenced = /^```(?:json)?\s*\r?\n([\s\S]*?)\r?\n?```$/.exec(trimmed);
+  const body = fenced ? fenced[1].trim() : trimmed;
+
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, error: 'response parsed but is not a JSON object' };
+    }
+    return { ok: true, value: parsed };
+  } catch (e) {
+    return { ok: false, error: 'not valid JSON: ' + e.message };
+  }
+}
+
+/**
+ * Check a parsed response against the inventory it was given.
+ *
+ * Returns a list of problems. Empty means usable. Every message is written to
+ * be handed straight back to the model on the retry, so they say what was
+ * wrong and what to do instead.
+ */
+export function validateVerdict(v, inventory) {
+  const problems = [];
+  const agentNames = new Set(inventory.agents.map((a) => a.name));
+  const known = new Map();
+  for (const a of inventory.agents) known.set(`agent:${a.name}`, true);
+  for (const s of inventory.skills) known.set(`skill:${s.name}`, true);
+  for (const m of inventory.mcpServers) known.set(`mcp-server:${m.name}`, true);
+  for (const a of inventory.allowlisted) known.set(`mcp-server:${a.key}`, true);
+
+  if (!FIT_VERDICTS.includes(v.verdict)) {
+    problems.push(
+      `"verdict" was ${JSON.stringify(v.verdict)}; it must be exactly one of ` +
+      FIT_VERDICTS.map((x) => `"${x}"`).join(', ') + '.',
+    );
+  }
+
+  const ownerGiven = v.owner !== null && v.owner !== undefined && v.owner !== '';
+  if (v.verdict === 'fits') {
+    if (!ownerGiven) {
+      problems.push('"verdict" is "fits" but "owner" is null. A fit with no owner is not a placement.');
+    } else if (!agentNames.has(v.owner)) {
+      // The single most important check here. An invented subagent reads as
+      // advice and is fiction.
+      problems.push(
+        `"owner" was ${JSON.stringify(v.owner)}, which is not a subagent in the ` +
+        'inventory. Use an exact name from the SUBAGENTS section, or change the ' +
+        'verdict to "needs-new-subagent".',
+      );
+    }
+  } else if (ownerGiven) {
+    problems.push(
+      `"owner" must be null when the verdict is ${JSON.stringify(v.verdict)}; got ${JSON.stringify(v.owner)}.`,
+    );
+  }
+
+  if (typeof v.rationale !== 'string' || v.rationale.trim() === '') {
+    problems.push('"rationale" must be a non-empty string.');
+  } else if (v.rationale.length > MAX_RATIONALE_CHARS) {
+    problems.push(`"rationale" is ${v.rationale.length} chars; keep it under ${MAX_RATIONALE_CHARS}.`);
+  }
+
+  if (!Array.isArray(v.overlaps)) {
+    problems.push('"overlaps" must be an array, empty if there are none.');
+  } else {
+    v.overlaps.forEach((o, i) => {
+      if (!o || typeof o !== 'object') {
+        problems.push(`overlaps[${i}] must be an object with kind, name and why.`);
+        return;
+      }
+      if (!OVERLAP_KINDS.includes(o.kind)) {
+        problems.push(
+          `overlaps[${i}].kind was ${JSON.stringify(o.kind)}; must be one of ` +
+          OVERLAP_KINDS.map((x) => `"${x}"`).join(', ') + '.',
+        );
+        return;
+      }
+      if (typeof o.name !== 'string' || !known.has(`${o.kind}:${o.name}`)) {
+        problems.push(
+          `overlaps[${i}] names ${JSON.stringify(o.name)} as a ${o.kind}, which is not ` +
+          'in the inventory. Only cite things that are actually listed.',
+        );
+      }
+      if (typeof o.why !== 'string' || o.why.trim() === '') {
+        problems.push(`overlaps[${i}].why must say what that thing already covers.`);
+      }
+    });
+  }
+
+  if (v.verdict === 'redundant' && Array.isArray(v.overlaps) && v.overlaps.length === 0) {
+    problems.push('"redundant" with no overlaps is not an answer. Name what already covers this.');
+  }
+
+  return problems;
+}
+
+/**
+ * Run the review.
+ *
+ * ONE call, then at most one retry. The retry is fed the exact problems from
+ * the first attempt, because "try again" without saying what was wrong mostly
+ * produces the same answer at a different temperature, and temperature is 0.
+ *
+ * Failing loudly after that is deliberate. A fit review that degrades to a
+ * default verdict would either spend money it should not have, or refuse a
+ * capability the system genuinely needs, and both would look like a decision.
+ */
+export async function fitReview(candidate, inventory, { llm, renderInventory, maxAttempts = 2 } = {}) {
+  if (!llm) throw new FitReviewError('fitReview needs an llm client');
+  if (!renderInventory) throw new FitReviewError('fitReview needs a renderInventory function');
+
+  const block = renderInventory(inventory);
+  let user = buildUserPrompt(candidate, block);
+  let lastResponse = null;
+  const failures = [];
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const res = await llm.complete({ system: SYSTEM, user, max_tokens: 1024 });
+    lastResponse = res?.text ?? '';
+
+    const parsed = extractJson(lastResponse);
+    if (!parsed.ok) {
+      failures.push(`attempt ${attempt}: ${parsed.error}`);
+      user = retryPrompt(candidate, block, [parsed.error]);
+      continue;
+    }
+
+    const problems = validateVerdict(parsed.value, inventory);
+    if (problems.length === 0) {
+      const v = parsed.value;
+      return {
+        verdict: v.verdict,
+        owner: v.verdict === 'fits' ? v.owner : null,
+        rationale: v.rationale.trim(),
+        overlaps: v.overlaps.map((o) => ({ kind: o.kind, name: o.name, why: o.why.trim() })),
+        model: llm.model,
+        attempts: attempt,
+      };
+    }
+
+    failures.push(`attempt ${attempt}: ${problems.join(' ')}`);
+    user = retryPrompt(candidate, block, problems);
+  }
+
+  throw new FitReviewError(
+    `fit review failed after ${maxAttempts} attempts:\n  ` + failures.join('\n  '),
+    { attempts: maxAttempts, lastResponse },
+  );
+}
+
+function retryPrompt(candidate, block, problems) {
+  return [
+    'Your previous answer was rejected. Fix exactly these problems and return',
+    'the corrected JSON object, nothing else:',
+    ...problems.map((p) => `- ${p}`),
+    '',
+    buildUserPrompt(candidate, block),
+  ].join('\n');
+}
+
+export const __testing = { SYSTEM, buildUserPrompt, retryPrompt };

package/doorman/src/injection.mjs

@@ -0,0 +1,189 @@
+/**
+ * VENDORED from mcp-scorecard/src/probes/injection_sniff.ts.
+ *
+ * ── Why a copy and not an import ─────────────────────────────────────────────
+ *
+ * This repo is the giveaway. When it is extracted to its own public repo the
+ * scorecard's source is not there, and the scorecard's build artifact
+ * (`runner/lib.mjs`) is gitignored, so neither an import nor a bundled copy
+ * survives extraction. A vendored copy does.
+ *
+ * The cost of a copy is drift, and drift here is silent: a pattern tightened in
+ * the scorecard would keep passing here while quietly grading skills by an
+ * older rule than MCP servers. So `test/injection.test.mjs` parses the TypeScript
+ * source and fails when the two diverge. That test skips itself once the source
+ * is gone, which is the only moment a copy is legitimately on its own.
+ *
+ * If you change a pattern, change it THERE first. This file follows.
+ *
+ * ── What this covers, and what it does not ───────────────────────────────────
+ *
+ * The scorecard scans a tool SURFACE: descriptions, titles, schema field
+ * descriptions. That code stays there, because only the scorecard has an
+ * inventory to scan.
+ *
+ * This scans PROSE: a SKILL.md, a README, a gist. Same patterns, different
+ * input. A skill has no tools to probe, so this is the entire security signal
+ * available for a skill or repo candidate, and the report must say so rather
+ * than implying a behavioural grade happened.
+ */
+
+/** Verbatim from the source. Order is preserved so hit order matches. */
+export const INJECTION_PATTERNS = [
+  { name: 'ignore-previous-instructions',
+    re: /\b(ignore|disregard|forget|override)\b[^.]{0,40}\b(previous|prior|above|earlier|all)\b[^.]{0,20}\b(instruction|prompt|rule|direction|context)/i, severity: 'hard' },
+  { name: 'addresses-the-model-directly',
+    re: /\b(you are|you must|you should)\b[^.]{0,60}\b(assistant|ai|model|claude|gpt|agent)\b/i, severity: 'hard' },
+  { name: 'system-prompt-manipulation',
+    // Mentioning a system prompt is not manipulating one. The old form fired on
+    // three LLM tools whose entire job is to accept one as a parameter. The
+    // signal is a verb that CHANGES or EXTRACTS it, or a literal delimiter,
+    // which has no innocent reading inside a tool description.
+    re: /\b(ignore|override|replace|reveal|disclose|print|dump|leak|rewrite)\b[^.]{0,25}\b(system prompt|system message)\b|<\s*system\s*>|\[\s*system\s*\]|\b(new|updated) instructions?\b/i, severity: 'hard' },
+  { name: 'exfiltration-request',
+    // Window narrowed from 40 chars to 12, and bare "conversation" dropped.
+    // At 40 this matched "To send for real, sign up for an API key" and "post
+    // the reply to the main conversation": in a messaging API those words
+    // co-occur constantly with nothing leaving. Exfiltration puts the verb next
+    // to its object, "send your api key", "forward the chat history". A whole
+    // clause in between is a sentence, not an instruction.
+    //
+    // Bare "conversation" is gone, but a DEICTIC one stays: "the current
+    // conversation", "your conversation", "this conversation" all point at the
+    // agent's own context, while Slack's "the main conversation" and a thread
+    // reader's "in conversation order" point at something in the product's own
+    // domain. That distinction is the whole difference between the planted
+    // hostile fixture and two innocent messaging APIs.
+    re: /\b(send|post|forward|upload|transmit|leak|exfiltrate)\b[^.]{0,20}\b(api[_ -]?key|token|secret|credential|password|chat history|system prompt|(the current|your|this) conversation)\b/i, severity: 'hard' },
+  { name: 'secrecy-instruction',
+    re: /\b(do not|don't|never)\b[^.]{0,30}\b(tell|inform|mention|reveal|disclose|show)\b[^.]{0,30}\b(user|human|owner|operator)\b/i, severity: 'hard' },
+  { name: 'coerced-tool-preference',
+    // "only" dropped. "only use this tool AFTER generating the PDF" is a
+    // sequencing constraint and "only use this tool for X" is scoping, both of
+    // which are ordinary documentation. Coercion is "always" or "must": it
+    // removes the model's judgement rather than describing when the tool
+    // applies. Those two still trip, which is the point.
+    re: /\b(always|must)\b[^.]{0,30}\b(use|call|prefer|choose)\b[^.]{0,20}\bthis tool\b/i, severity: 'hard' },
+  // A role marker at the start of a line used to be enough. It is not: a Python
+  // docstring "Args:" block puts "system:" and "user:" on their own indented
+  // lines as PARAMETER NAMES, and that shape is everywhere in this ecosystem.
+  // Split by how ambiguous the word is.
+  { name: 'embedded-role-marker',
+    // "assistant:" and "human:" are not plausible parameter names.
+    re: /(^|\n)\s*(assistant|human)\s*:\s*\S/i, severity: 'hard' },
+  { name: 'embedded-chat-transcript',
+    // "system:" and "user:" are, so they need corroboration. Two things supply
+    // it: a SECOND turn, which makes it a transcript, or text addressed to the
+    // model, which makes it an instruction.
+    //
+    // Requiring only the second turn was too strict and dropped
+    // "system: you are now in developer mode", a single marker that is plainly
+    // hostile. The scorecard's own fixture test caught that, which is what a
+    // planted hostile server is for.
+    re: /(^|\n)\s*(system|user)\s*:[\s\S]{0,400}\n\s*(assistant|human|user|system)\s*:\s*\S|(^|\n)\s*(system|user)\s*:\s*(you\b|ignore\b|disregard\b|forget\b|now\b|from now\b|act as\b|pretend\b|assume\b)/i, severity: 'hard' },
+  { name: 'hidden-instruction-delimiter',
+    re: /(<\|[a-z_]+\|>|\[INST\]|###\s*(instruction|system))/i, severity: 'hard' },
+
+  // ── Commercial steering ────────────────────────────────────────────────
+  // A tool description is documentation. These constructions are a sales
+  // script addressed to the model, billed to the user's context window on
+  // every call. Reported, scored, never a hard fail.
+  { name: 'imperative-to-model',
+    re: /\byou MUST\b/, severity: 'steering' },
+  { name: 'always-offer',
+    re: /\b(proactively offer|always offer|every single time)\b/i, severity: 'steering' },
+  // The bare "use this instead of" caught five vendors routing between two
+  // tools in their OWN server: "instead of polling get_workflow_status",
+  // "instead of competitive_deep_dive". That is good documentation, not
+  // steering. Steering points the model away from someone ELSE, and shows up
+  // two ways, which are two patterns because they need different flags:
+  { name: 'steer-from-competitor',
+    // It redirects what the USER gets told. Case-insensitive.
+    re: /\binstead of (telling|pointing|sending|directing|referring) the user\b/i, severity: 'steering' },
+  { name: 'names-competing-products',
+    // Or it names products. A product reads as Capitalised and usually arrives
+    // in a slash list ("Vercel/Netlify/AWS"). This one CANNOT take /i: the
+    // capitalisation is the entire signal, and lowercasing it would match
+    // "instead of polling/fetching" again.
+    re: /\binstead of\b[^.]{0,25}\b[A-Z][a-zA-Z0-9]{2,}\s*\/\s*[A-Z][a-zA-Z0-9]{2,}/, severity: 'steering' },
+  { name: 'prescribed-user-line',
+    re: /\bthe (right|correct) closing line\b/i, severity: 'steering' },
+  { name: 'internalize-directive',
+    re: /\binternali[sz]e (it|this)\b/i, severity: 'steering' },
+  { name: 'preempt-the-user',
+    re: /\bdo(?: not|n't) wait for the user\b|\beven if the user did not ask\b/i, severity: 'steering' },
+];
+
+/**
+ * A window around the match, so a reviewer can check the accusation.
+ *
+ * Verbatim from the source. This is a SUMMARY field. The untouched original
+ * text always remains available to the caller.
+ */
+export function excerptAround(text, index, len) {
+  const start = Math.max(0, index - 30);
+  const end = Math.min(text.length, index + len + 30);
+  return (start > 0 ? '...' : '') + text.slice(start, end).replace(/\s+/g, ' ').trim() +
+    (end < text.length ? '...' : '');
+}
+
+/**
+ * Scan one block of prose.
+ *
+ * Returns every pattern that fired, each with the text that fired it, verbatim.
+ * An accusation that cannot be checked is not evidence.
+ *
+ * Deliberately conservative, for the same reason the source is: a false hit is
+ * a public claim about somebody else's work.
+ */
+export function scanText(text, location = 'instructions') {
+  const hits = [];
+  if (typeof text !== 'string' || !text) return hits;
+  for (const p of INJECTION_PATTERNS) {
+    const m = p.re.exec(text);
+    if (m) {
+      hits.push({
+        location,
+        pattern: p.name,
+        severity: p.severity,
+        excerpt: excerptAround(text, m.index, m[0].length),
+      });
+    }
+  }
+  return hits;
+}
+
+/**
+ * The same shape the scorecard's probe returns, so a note renderer does not
+ * need to care which path produced it.
+ *
+ * `hard_fail` is set for exactly the same reason it is there: injection-shaped
+ * content is disqualifying on its own, whatever else is true.
+ */
+export function sniffInstructions(text, location = 'instructions') {
+  const hits = scanText(text, location);
+  const hard = hits.filter((h) => h.severity === 'hard');
+  const steering = hits.filter((h) => h.severity === 'steering');
+  return {
+    scanned_chars: typeof text === 'string' ? text.length : 0,
+    hits,
+    hard: hard.length,
+    steering: steering.length,
+    // Same severity rule as the source: only an ATTACK caps a grade. A
+    // description that advertises through the agent is reported and scored,
+    // never treated as a jailbreak attempt.
+    score: hard.length ? 0 : (steering.length ? Math.max(25, 100 - steering.length * 15) : 100),
+    failure_modes: [
+      ...hard.map(
+        (h) => 'injection-shaped content in ' + h.location + ' (' + h.pattern + '): "' + h.excerpt + '"',
+      ),
+      ...steering.map(
+        (h) => 'commercial steering in ' + h.location + ' (' + h.pattern + '): "' + h.excerpt + '"',
+      ),
+    ],
+    hard_fail: hard.length
+      ? 'injection-shaped content in ' + hard.length + ' location(s): ' +
+        [...new Set(hard.map((h) => h.location))].join(', ')
+      : undefined,
+  };
+}

package/doorman/src/instructions.mjs

@@ -0,0 +1,134 @@
+/**
+ * Fetch the instruction text of a skill or a repo.
+ *
+ * This is the only other file allowed to touch the network, and it is
+ * deliberately dull: one GET, a size cap, no redirect chasing beyond what fetch
+ * does on its own, no execution of anything.
+ *
+ * ── The text is DATA ─────────────────────────────────────────────────────────
+ *
+ * What comes back is somebody else's instruction text, which is precisely the
+ * kind of content that might be trying to talk to a reading agent. Nothing here
+ * interprets it, summarises it, or passes it to a model. It goes to the pattern
+ * scanner and into the note as a quoted excerpt. Handing it to an LLM for a
+ * "what does this skill do" summary would be reading the letter, which is the
+ * thing this project exists to refuse.
+ *
+ * ── Why the fit review still sees the candidate's own words ──────────────────
+ *
+ * The fit review gets the candidate's SELF-DESCRIPTION, which is short and
+ * clearly labelled as a claim. That is different from feeding a model an entire
+ * untrusted README.
+ */
+
+import { readFileSync } from 'node:fs';
+
+/** A README past this is not being read by a human either. */
+export const MAX_INSTRUCTION_BYTES = 200_000;
+
+export class InstructionFetchError extends Error {}
+
+/**
+ * Turn a candidate into the url that actually serves its text.
+ *
+ * github.com/owner/repo         -> the raw README on the default branch
+ * github.com/owner/repo/blob/.. -> the raw file
+ * gist.github.com/u/id          -> the gist's raw endpoint
+ * anything ending .md           -> itself
+ */
+export function instructionUrl(candidate) {
+  const raw = candidate.id;
+  if (!/^https?:\/\//i.test(raw)) return { kind: 'file', target: raw };
+
+  const u = new URL(raw);
+  const host = u.hostname.toLowerCase();
+  const segments = u.pathname.split('/').filter(Boolean);
+
+  if (host === 'github.com' || host === 'www.github.com') {
+    if (segments.length >= 4 && (segments[2] === 'blob' || segments[2] === 'raw')) {
+      const [owner, repo, , ...rest] = segments;
+      return {
+        kind: 'http',
+        target: `https://raw.githubusercontent.com/${owner}/${repo}/${rest.join('/')}`,
+      };
+    }
+    const [owner, repo] = segments;
+    // Branch name is not knowable without an API call, and an API call needs a
+    // token. Try the two names that cover essentially everything, in order.
+    return {
+      kind: 'http',
+      target: `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/README.md`,
+      alternates: [
+        `https://raw.githubusercontent.com/${owner}/${repo}/main/README.md`,
+        `https://raw.githubusercontent.com/${owner}/${repo}/master/README.md`,
+      ],
+    };
+  }
+
+  if (host === 'gist.github.com') {
+    return { kind: 'http', target: raw.replace(/\/$/, '') + '/raw' };
+  }
+
+  return { kind: 'http', target: raw };
+}
+
+/**
+ * @param {object} candidate  from detectCandidate
+ * @param {object} [deps]     `{ fetch, readFile }` injectable for tests
+ * @returns {Promise<{ text, source, bytes, truncated }>}
+ */
+export async function fetchInstructions(candidate, { fetch: f = fetch, readFile = readFileSync, timeoutMs = 20_000 } = {}) {
+  const plan = instructionUrl(candidate);
+
+  if (plan.kind === 'file') {
+    let text;
+    try {
+      text = readFile(plan.target, 'utf8');
+    } catch (e) {
+      throw new InstructionFetchError(`could not read ${plan.target}: ${e.message}`);
+    }
+    return capped(text, plan.target);
+  }
+
+  const targets = [plan.target, ...(plan.alternates ?? [])];
+  const failures = [];
+
+  for (const target of targets) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+      res = await f(target, { signal: ac.signal, redirect: 'follow' });
+    } catch (e) {
+      failures.push(`${target}: ${e.message}`);
+      continue;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!res.ok) {
+      failures.push(`${target}: HTTP ${res.status}`);
+      continue;
+    }
+    const text = await res.text();
+    return capped(text, target);
+  }
+
+  throw new InstructionFetchError(
+    'could not fetch instruction text.\n  ' + failures.join('\n  '),
+  );
+}
+
+function capped(text, source) {
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const truncated = bytes > MAX_INSTRUCTION_BYTES;
+  return {
+    // Truncation is reported rather than hidden. A scanner that silently read
+    // the first 200 KB of a 900 KB file would report "clean" about 22% of a
+    // document.
+    text: truncated ? text.slice(0, MAX_INSTRUCTION_BYTES) : text,
+    source,
+    bytes,
+    truncated,
+  };
+}