pll-python 0.2.0 → 0.5.0

package/cli.cjs

@@ -24,722 +24,1032 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/main.ts
-var path7 = __toESM(require("node:path"));
+var fs8 = __toESM(require("node:fs"));
+var path8 = __toESM(require("node:path"));
+
+// src/cli/args.ts
+var import_node_util = require("node:util");
+
+// src/core/errorText.ts
+function errorText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/cli/args.ts
+function parseCommandLine(argv, options) {
+  const config = Object.fromEntries(
+    Object.entries(options).map(([name, { type, short }]) => [name, short ? { type, short } : { type }])
+  );
+  let line;
+  try {
+    line = (0, import_node_util.parseArgs)({ args: argv, options: config, allowPositionals: true, strict: true });
+  } catch (err) {
+    return { error: reworded(err, options, argv) };
+  }
+  for (const [name, value] of Object.entries(line.values)) {
+    if (value === "") {
+      return { error: `${typedFlag(name, options[name], argv)} needs ${options[name]?.needs ?? "a value"}` };
+    }
+  }
+  return line;
+}
+function subcommandIndex(argv, name, options) {
+  const takesValue = /* @__PURE__ */ new Set();
+  for (const [long, option] of Object.entries(options)) {
+    if (option.type !== "string") continue;
+    takesValue.add(`--${long}`);
+    if (option.short) takesValue.add(`-${option.short}`);
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      return argv[i + 1] === name ? i + 1 : -1;
+    }
+    if (!arg.startsWith("-") || arg === "-") {
+      return arg === name ? i : -1;
+    }
+    if (takesValue.has(arg)) i++;
+  }
+  return -1;
+}
+function typedFlag(long, option, argv) {
+  const typedLong = argv.some((arg) => arg === `--${long}` || arg.startsWith(`--${long}=`));
+  return option?.short && !typedLong ? `-${option.short}` : `--${long}`;
+}
+function reworded(err, options, argv) {
+  const message = errorText(err);
+  const code = err.code;
+  if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+    const flag = /^Unknown option '([^']+)'/.exec(message)?.[1];
+    return flag ? `unknown option ${flag}` : message;
+  }
+  const named = /^Option '(?:-(\w), )?--([\w-]+)/.exec(message);
+  if (code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" && named) {
+    const long = named[2];
+    const option = options[long];
+    const flag = typedFlag(long, option, argv);
+    return option?.type === "string" ? `${flag} needs ${option.needs ?? "a value"}` : `${flag} does not take a value`;
+  }
+  return message;
+}
 
 // src/cli/examplar.ts
+var fs4 = __toESM(require("node:fs/promises"));
+var path4 = __toESM(require("node:path"));
+
+// src/cli/run.ts
 var fs3 = __toESM(require("node:fs/promises"));
 var path3 = __toESM(require("node:path"));
 
-// src/cli/run.ts
-var fs2 = __toESM(require("node:fs/promises"));
-var path2 = __toESM(require("node:path"));
+// src/core/editDistance.ts
+function editDistance(a, b) {
+  let twoBack = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        current[j] = Math.min(current[j], twoBack[j - 2] + 1);
+      }
+    }
+    twoBack = previous;
+    previous = current;
+  }
+  return previous[b.length];
+}
 
-// src/common/analyzers/static/shadowingExplainer.ts
-function outerScopeNoun(kind) {
-  switch (kind) {
-    case "module":
-      return "the file";
-    case "function":
-    case "lambda":
-      return "an enclosing function";
-    case "class":
-      return "an enclosing class";
-    case "comprehension":
-      return "an enclosing comprehension";
-    default:
-      return "an outer scope";
+// src/core/level.ts
+var LEVEL_RAW = "raw";
+var LEVEL_BEGINNER = "beginner";
+var LEVEL_INTERMEDIATE = "intermediate";
+var LEVEL_ADVANCED = "advanced";
+var LEVEL_NAMES = [LEVEL_RAW, LEVEL_BEGINNER, LEVEL_INTERMEDIATE, LEVEL_ADVANCED];
+var DEFAULT_LEVEL = LEVEL_RAW;
+function isLevel(name) {
+  return LEVEL_NAMES.includes(name);
+}
+var HEADER_RE = /^#\s*level\s+([a-z]+)\s*$/;
+function parseLevel(source) {
+  const lines = source.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0) {
+      continue;
+    }
+    const match = HEADER_RE.exec(line);
+    if (!match) {
+      return DEFAULT_LEVEL;
+    }
+    const name = match[1];
+    return isLevel(name) ? name : DEFAULT_LEVEL;
   }
+  return DEFAULT_LEVEL;
 }
-function explainShadowing(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const outerLine = raw.outer_line_number ?? null;
-  const outerNoun = outerScopeNoun(raw.outer_scope_kind);
-  const knownOuterLine = outerLine !== null && outerLine > 0;
-  const outerHint = knownOuterLine ? ` (first defined on line ${outerLine}, in ${outerNoun})` : ` in ${outerNoun}`;
-  return {
-    id: "shadowing",
-    errorType: "Shadowing",
-    message: raw.message,
-    headline: `\`${name}\` is already defined${outerHint}.`,
-    howToFix: [
-      `Rename the inner \`${name}\` to something distinct (e.g. \`${name}_inner\`, \`local_${name}\`, or whatever describes its role).`,
-      `Or, if you want to use the outer \`${name}\`, just read it directly without making a new variable.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
+function levelHeaderProblem(source) {
+  const lines = source.split(/\r?\n/);
+  const valid = new RegExp(`^#\\s*level\\s+(?:${LEVEL_NAMES.join("|")})\\s*$`);
+  const joined = new RegExp(`^#\\s*level(${LEVEL_NAMES.join("|")})\\s*$`);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0) {
+      continue;
+    }
+    const squashed = joined.exec(line);
+    if (squashed !== null) {
+      return {
+        line: i + 1,
+        message: `\`#level\` needs a space before \`${squashed[1]}\`: \`#level ${squashed[1]}\`.`,
+        howToFix: [`Write it as \`#level ${squashed[1]}\`, with a space.`]
+      };
+    }
+    const attempt = /^#\s*level\b(.*)$/.exec(line);
+    if (attempt === null) {
+      return misplacedHeader(lines, i, valid);
+    }
+    if (valid.test(line)) {
+      return null;
+    }
+    const named = attempt[1].trim();
+    if (named.length === 0) {
+      return {
+        line: i + 1,
+        message: `\`#level\` needs a level after it: ${levelList()}.`,
+        howToFix: [`Name one of ${levelList()}, or leave the line out.`]
+      };
+    }
+    const suggestion = closestLevel(named);
+    return {
+      line: i + 1,
+      message: `\`${named}\` is not a level` + (suggestion ? `. Did you mean \`${suggestion}\`?` : `. The levels are ${levelList()}.`),
+      howToFix: suggestion ? [`Write \`#level ${suggestion}\` on the first line, in lower case.`] : [`Name one of ${levelList()}, or leave the line out.`]
+    };
+  }
+  return null;
 }
-function explainShadowingBuiltin(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const headline = `\`${name}\` is the name of a Python built-in.`;
-  return {
-    id: "shadowing-builtin",
-    errorType: "Shadowing",
-    message: raw.message,
-    headline,
-    howToFix: [
-      `Pick a different name. Common patterns: \`my_${name}\`, \`${name}_value\`, \`${name}s\` (plural), or a more specific noun describing what this value represents.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
+function misplacedHeader(lines, from, valid) {
+  const comments = commentLines(lines);
+  let underCode = false;
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0) {
+      continue;
+    }
+    if (!comments[i]) {
+      underCode = true;
+      continue;
+    }
+    if (valid.test(line)) {
+      return {
+        line: i + 1,
+        message: `\`${line}\` only counts on the first line, so none of its checks ran.`,
+        howToFix: [
+          underCode ? "Move it to the very first line of the file, above the code." : "Move it to the very top of the file, above the comments.",
+          "Leave the line out altogether to run the file as ordinary Python."
+        ]
+      };
+    }
+  }
+  return null;
 }
-function libraryNoun(library) {
-  switch (library) {
-    case "image":
-      return "the image library";
-    case "table":
-      return "the table library";
-    case "reactor":
-      return "the reactor library";
-    default:
-      return "the PLL libraries";
+function commentLines(lines) {
+  const comments = [];
+  let open = null;
+  for (const line of lines) {
+    comments.push(open === null && line.trimStart().startsWith("#"));
+    let i = 0;
+    while (i < line.length) {
+      if (open !== null) {
+        const close = closingQuote(line, i, open);
+        if (close < 0) break;
+        i = close + open.length;
+        open = null;
+        continue;
+      }
+      const c = line[i];
+      if (c === "#") break;
+      if (c === '"' || c === "'") {
+        if (line.startsWith(c.repeat(3), i)) {
+          open = c.repeat(3);
+          i += 3;
+          continue;
+        }
+        const close = closingQuote(line, i + 1, c);
+        i = close < 0 ? line.length : close + 1;
+        continue;
+      }
+      i += 1;
+    }
   }
+  return comments;
 }
-function explainShadowingLibrary(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const noun = libraryNoun(raw.library);
-  const headline = `\`${name}\` is already defined by ${noun}.`;
-  return {
-    id: "shadowing-library",
-    errorType: "Shadowing",
-    message: raw.message,
-    headline,
-    howToFix: [
-      `Pick a different name for your definition - for example \`my_${name}\`, \`${name}_value\`, or a word that describes what yours represents.`,
-      `If you meant to use the library's \`${name}\`, call it directly instead of defining a new \`${name}\` of your own.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
-  };
+function closingQuote(line, from, quote) {
+  for (let i = from; i < line.length; i++) {
+    if (line[i] === "\\") {
+      i += 1;
+    } else if (line.startsWith(quote, i)) {
+      return i;
+    }
+  }
+  return -1;
+}
+function levelList() {
+  return LEVEL_NAMES.map((name) => `\`${name}\``).join(", ");
+}
+function closestLevel(named) {
+  const lower = named.toLowerCase();
+  let best = null;
+  let bestDistance = Infinity;
+  for (const level of LEVEL_NAMES) {
+    const distance = editDistance(lower, level);
+    if (distance < bestDistance) {
+      best = level;
+      bestDistance = distance;
+    }
+  }
+  return best !== null && bestDistance <= Math.max(2, Math.floor(best.length / 3)) ? best : null;
+}
+function levelHasStaticChecks(level) {
+  return level === LEVEL_BEGINNER || level === LEVEL_INTERMEDIATE;
 }
 
-// src/common/analyzers/static/reassignmentExplainer.ts
-function explainReassignment(raw, level, fileName) {
-  const name = raw.name_token ?? "this name";
-  const firstLine = raw.first_line_number ?? null;
-  const firstLineHint = firstLine !== null && firstLine > 0 ? ` (first assigned on line ${firstLine})` : "";
+// src/run/finding.ts
+function serializeFinding(finding) {
   return {
-    id: "reassignment",
-    errorType: "Reassignment",
-    message: raw.message,
-    headline: `\`${name}\` is already assigned${firstLineHint}.`,
-    howToFix: level === "intermediate" ? [
-      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
-      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), wrap the work in a function and rebind \`${name}\` from the function's return value: \`${name} = compute_${name}(...)\`.`
-    ] : [
-      `If you want a different value, give it a different name (e.g. \`${name}_doubled\`, \`new_${name}\`, \`${name}2\`).`,
-      `If you're trying to update a value (\`x = x + 1\`, accumulators, running totals), use a built-in like \`sum(...)\`, \`max(...)\`, or a small helper function that returns the new value instead.`
-    ],
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
+    errorType: finding.errorType,
+    headline: finding.headline,
+    howToFix: [...finding.howToFix],
+    location: findingLocation(finding)
   };
 }
-
-// src/common/analyzers/static/disallowedKeywordExplainer.ts
-function explainDisallowedKeyword(raw, level, fileName) {
-  const keyword = raw.keyword === "nonlocal" ? "nonlocal" : "global";
-  const names = Array.isArray(raw.names) ? raw.names : [];
-  const formattedNames = names.map((n) => `\`${n}\``).join(", ");
-  const namesPhrase = formattedNames.length > 0 ? ` ${formattedNames}` : "";
-  const headline = `\`${keyword}\` is not allowed at the ${level} level.`;
-  const howToFix = [];
-  if (keyword === "global") {
-    howToFix.push(
-      `Pass${namesPhrase || " the value"} into this function as an argument instead of declaring it \`global\`.`,
-      `If the function needs to *change* a value, return the new value and let the caller decide what to do with it (e.g. \`x = update(x)\`).`
-    );
-  } else {
-    howToFix.push(
-      `Return${namesPhrase || " the new value"} from this inner function and have the outer function rebind it explicitly (e.g. \`x = inner(x)\`).`,
-      `If the inner function only needs to *read* the outer name, just use it directly - you don't need \`nonlocal\` for that.`
-    );
+function findingLocation(finding) {
+  if (finding.lineNumber === null) {
+    return null;
+  }
+  if (finding.fileName === "<repl>" || finding.fileName === "<input>") {
+    return null;
   }
+  const column = finding.column;
+  const label = column !== null ? `${finding.fileName}:${finding.lineNumber}:${column + 1}` : `${finding.fileName}:${finding.lineNumber}`;
   return {
-    id: "disallowed-keyword",
-    errorType: "DisallowedKeyword",
-    message: raw.message,
-    headline,
-    howToFix,
-    fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
-    severity: "error",
-    raw: JSON.stringify(raw),
-    origin: "static",
-    level
+    fileName: finding.fileName,
+    line: finding.lineNumber,
+    column,
+    label
   };
 }
-
-// src/common/analyzers/static/registry.ts
-var explainers = {
-  shadowing: explainShadowing,
-  "shadowing-builtin": explainShadowingBuiltin,
-  "shadowing-library": explainShadowingLibrary,
-  reassignment: explainReassignment,
-  "disallowed-keyword": explainDisallowedKeyword
-};
-function fallbackExplainer(raw, level, fileName) {
+function formatFriendlyError(finding) {
+  const lines = [];
+  lines.push(`${finding.errorType}: ${finding.headline}`);
+  const location = findingLocation(finding);
+  if (location) {
+    lines.push(`  at ${location.label}`);
+  }
+  if (finding.howToFix.length > 0) {
+    lines.push("");
+    lines.push("How to fix:");
+    for (const item of finding.howToFix) {
+      lines.push(`  - ${item}`);
+    }
+  }
+  return lines;
+}
+function levelHeaderFinding(source, fileName, level) {
+  const problem = levelHeaderProblem(source);
+  if (problem === null) {
+    return null;
+  }
   return {
-    id: raw.id,
-    errorType: raw.error_type || "StaticError",
-    message: raw.message,
-    headline: raw.message,
-    howToFix: [],
+    id: "level-header",
+    errorType: "Level",
+    headline: problem.message,
+    howToFix: problem.howToFix,
     fileName,
-    lineNumber: raw.line_number,
-    column: raw.column,
-    nameToken: raw.name_token,
+    lineNumber: problem.line,
+    column: null,
+    nameToken: null,
     severity: "error",
-    raw: JSON.stringify(raw),
     origin: "static",
     level
   };
 }
-function enrichStaticFindings(rawFindings, level, fileName) {
-  return rawFindings.map((raw) => {
-    const explainer = explainers[raw.id] ?? fallbackExplainer;
-    return explainer(raw, level, fileName);
-  });
+function findRuntimeFinding(fileName, level, error) {
+  return { ...error.finding, fileName: error.finding.fileName ?? fileName, level };
 }
-
-// src/common/errors/pythonErrorParser.ts
-var NON_USER_FRAME = [
-  "<exec>",
-  "/pll_vendor",
-  "site-packages",
-  "/lib/python",
-  "_pytest",
-  "pluggy"
-];
-function userTracebackFrames(traceback) {
-  const frames = [];
-  for (const raw of traceback.split(/\r?\n/)) {
-    const m = raw.match(/^\s*File "([^"]+)", line (\d+)(?:, in (\S+))?/);
-    if (!m) continue;
-    const fileName = m[1];
-    if (NON_USER_FRAME.some((token) => fileName.includes(token))) continue;
-    frames.push({
-      fileName,
-      line: parseInt(m[2], 10),
-      functionName: m[3] && m[3] !== "<module>" ? m[3] : null
-    });
-  }
-  return frames;
-}
-function sourceIndent(source, lineNumber) {
-  if (!source) {
-    return 0;
-  }
-  const line = source.split(/\r?\n/)[lineNumber - 1];
-  if (line === void 0) {
-    return 0;
-  }
-  return line.length - line.trimStart().length;
-}
-function parsePythonError(rawTraceback, source) {
-  const traceback = rawTraceback.trimEnd();
-  const lines = traceback.split(/\r?\n/);
-  let errorType = "Error";
-  let message = traceback;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const m = line.match(/^([A-Za-z_][A-Za-z0-9_.]*):\s?(.*)$/);
-    if (m && !line.startsWith(" ")) {
-      errorType = m[1];
-      message = m[2];
-      break;
-    }
-    if (line.match(/^[A-Za-z_][A-Za-z0-9_.]*$/) && !line.startsWith(" ")) {
-      errorType = line;
-      message = "";
-      break;
-    }
-  }
-  let fileName = null;
-  let lineNumber = null;
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const m = line.match(/^\s*File\s+"([^"]+)",\s+line\s+(\d+)/);
-    if (m) {
-      fileName = m[1];
-      lineNumber = parseInt(m[2], 10);
-      break;
-    }
-  }
-  let column = null;
-  if (lineNumber !== null) {
-    for (let i = 0; i < lines.length - 1; i++) {
-      if (/^\s*\^+\s*$/.test(lines[i + 1] ?? "")) {
-        const sourceLine = lines[i];
-        const caretIdx = lines[i + 1].indexOf("^");
-        if (caretIdx >= 0) {
-          const echoed = sourceLine.length - sourceLine.trimStart().length;
-          column = Math.max(0, caretIdx - echoed) + sourceIndent(source, lineNumber);
-        }
-      }
-    }
-  }
-  let nameToken = null;
-  if (errorType === "NameError") {
-    const nm = message.match(/name '([^']+)' is not defined/);
-    if (nm) {
-      nameToken = nm[1];
-    }
-  }
+function explainTestReport(event, fileName, level) {
   return {
-    errorType,
-    message,
-    traceback,
-    fileName,
-    lineNumber,
-    column,
-    nameToken
+    ...event,
+    tests: event.tests.map(
+      ({ error, ...test }) => error ? { ...test, finding: serializeFinding(findRuntimeFinding(fileName, level, error)) } : test
+    )
   };
 }
 
-// src/common/errors/nameErrorExplainer.ts
-function explainNameError(parsed) {
-  const name = parsed.nameToken ?? "this name";
-  const didYouMean = extractDidYouMean(parsed.message);
-  const headline = `Python doesn't know what \`${name}\` means.`;
-  const howToFix = [
-    `Check the spelling of \`${name}\` (Python is case-sensitive).`,
-    `Make sure \`${name}\` is defined before this line runs.`,
-    `If \`${name}\` should be text, put it in quotes: \`"${name}"\`.`
-  ];
-  if (didYouMean.length > 0) {
-    howToFix.unshift(
-      `Python suggested: ${didYouMean.map((s) => "`" + s + "`").join(", ")} - try one of those.`
-    );
+// src/run/examplarSource.ts
+var MAX_BUNDLE_BYTES = 4 * 1024 * 1024;
+var DIRECTIVE_RE = /^#\s*examplar\s+(\S+)\s*$/;
+function parseExamplarDirective(source) {
+  const hits = [];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = DIRECTIVE_RE.exec(lines[i].trim());
+    if (match) {
+      hits.push({ url: match[1], line: i + 1 });
+    }
+  }
+  if (hits.length === 0) {
+    return { kind: "none" };
   }
-  return { headline, howToFix };
+  if (hits.length > 1) {
+    return {
+      kind: "error",
+      line: hits[1].line,
+      message: `there is more than one \`#examplar\` line (lines ${hits.map((h) => h.line).join(" and ")}). Keep the one you want.`
+    };
+  }
+  const { url, line } = hits[0];
+  const problem = validateBundleUrl(url);
+  return problem ? { kind: "error", message: problem, line } : { kind: "found", url, line };
 }
-function extractDidYouMean(message) {
-  const m = message.match(/Did you mean:\s*([^?]+)\??/i);
-  if (!m) {
-    return [];
+function validateBundleUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return `\`${url}\` is not a URL.`;
+  }
+  if (parsed.protocol === "https:") {
+    return null;
   }
-  return m[1].split(/,|\bor\b/).map((s) => s.trim().replace(/^['"`]|['"`]$/g, "")).filter((s) => s.length > 0);
+  if (parsed.protocol === "http:") {
+    const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+    return local ? null : `\`${url}\` must use https (plain http is only allowed for localhost).`;
+  }
+  return `\`${url}\` must be an https address.`;
 }
-
-// src/common/analyzers/nameErrorAnalyzer.ts
-var nameErrorAnalyzer = {
-  handles: ["NameError"],
-  analyze(input) {
-    const { parsedError, fileName, level } = input;
-    if (parsedError.errorType !== "NameError") {
-      return null;
-    }
-    const explanation = explainNameError(parsedError);
-    return {
-      id: "name-error",
-      errorType: "NameError",
-      message: parsedError.message,
-      headline: explanation.headline,
-      howToFix: explanation.howToFix,
-      fileName,
-      lineNumber: parsedError.lineNumber,
-      column: parsedError.column,
-      nameToken: parsedError.nameToken,
-      severity: "error",
-      raw: parsedError.traceback,
-      origin: "runtime",
-      level
+async function loadBundle(url, store, fetchImpl = globalThis.fetch) {
+  const cached = await store.read(url).catch(() => void 0);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: cached?.etag ? { "If-None-Match": cached.etag } : {}
+    });
+  } catch (err) {
+    const why = errorText(err);
+    return cached ? { json: cached.json, fromCache: true, note: `could not reach ${url} (${why}); using the cached copy` } : { fromCache: false, error: `could not reach ${url} (${why}), and nothing is cached` };
+  }
+  if (response.status === 304 && cached) {
+    return { json: cached.json, fromCache: true };
+  }
+  if (!response.ok) {
+    return cached ? {
+      json: cached.json,
+      fromCache: true,
+      note: `${url} returned ${response.status}; using the cached copy`
+    } : { fromCache: false, error: `${url} returned ${response.status}` };
+  }
+  const json = await response.text();
+  if (json.length > MAX_BUNDLE_BYTES) {
+    return cached ? { json: cached.json, fromCache: true, note: `${url} is unexpectedly large; using the cached copy` } : {
+      fromCache: false,
+      error: `${url} is ${json.length} bytes, past the ${MAX_BUNDLE_BYTES}-byte limit`
     };
   }
-};
+  if (!looksLikeBundle(json)) {
+    return cached ? { json: cached.json, fromCache: true, note: `${url} did not return a bundle; using the cached copy` } : { fromCache: false, error: `${url} did not return an Examplar bundle` };
+  }
+  const etag = response.headers.get("etag") ?? void 0;
+  try {
+    await store.write(url, { json, etag });
+  } catch (err) {
+    return { json, fromCache: false, note: `could not keep a copy for offline use (${errorText(err)})` };
+  }
+  return { json, fromCache: false };
+}
+function looksLikeBundle(json) {
+  try {
+    const bundle = JSON.parse(json);
+    return typeof bundle === "object" && bundle !== null && "examplar" in bundle && Array.isArray(bundle.wheats) && Array.isArray(bundle.chaffs);
+  } catch {
+    return false;
+  }
+}
 
-// src/common/level.ts
-var DEFAULT_LEVEL = "raw";
-var HEADER_RE = /^#\s*level\s+([a-z]+)\s*$/;
-var LEVEL_NAMES = [
-  "raw",
-  "beginner",
-  "intermediate",
-  "advanced"
-];
-function parseLevel(source) {
-  const lines = source.split(/\r?\n/);
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (line.length === 0) {
-      continue;
-    }
-    const match = HEADER_RE.exec(line);
-    if (!match) {
-      return DEFAULT_LEVEL;
-    }
-    const name = match[1];
-    for (const level of LEVEL_NAMES) {
-      if (name === level) return level;
-    }
-    return DEFAULT_LEVEL;
+// src/pyodide/sharedMemory.ts
+var STDIN_SAB_BYTES = 64 * 1024;
+var STDIN_STATE_INDEX = 0;
+var STDIN_LENGTH_INDEX = 1;
+var STDIN_REQUEST_INDEX = 2;
+var STDIN_PAYLOAD_OFFSET = 16;
+var STDIN_STATE_WAITING = 0;
+var STDIN_STATE_DATA = 1;
+var STDIN_STATE_EOF = 2;
+var STDIN_STATE_INTERRUPTED = 3;
+function tryCreateStdinBuffer() {
+  try {
+    return new SharedArrayBuffer(STDIN_SAB_BYTES);
+  } catch {
+    return null;
   }
-  return DEFAULT_LEVEL;
 }
-function levelRejectsBoolAsNumber(level) {
-  return level === "beginner" || level === "intermediate";
+function writeStdin(sab, request, bytes) {
+  const state = new Int32Array(sab);
+  if (Atomics.load(state, STDIN_REQUEST_INDEX) !== request || Atomics.load(state, STDIN_STATE_INDEX) !== STDIN_STATE_WAITING) {
+    return -1;
+  }
+  let n = 0;
+  if (bytes !== null) {
+    n = Math.min(bytes.length, sab.byteLength - STDIN_PAYLOAD_OFFSET);
+    new Uint8Array(sab, STDIN_PAYLOAD_OFFSET).set(bytes.subarray(0, n));
+    Atomics.store(state, STDIN_LENGTH_INDEX, n);
+  }
+  const answer = bytes === null ? STDIN_STATE_EOF : STDIN_STATE_DATA;
+  const was = Atomics.compareExchange(state, STDIN_STATE_INDEX, STDIN_STATE_WAITING, answer);
+  if (was !== STDIN_STATE_WAITING) {
+    return -1;
+  }
+  Atomics.notify(state, STDIN_STATE_INDEX);
+  return n;
 }
-function levelHasStaticChecks(level) {
-  return level === "beginner" || level === "intermediate";
+function interruptStdin(sab) {
+  const state = new Int32Array(sab);
+  if (Atomics.compareExchange(state, STDIN_STATE_INDEX, STDIN_STATE_WAITING, STDIN_STATE_INTERRUPTED) === STDIN_STATE_WAITING) {
+    Atomics.notify(state, STDIN_STATE_INDEX);
+  }
+}
+var INTERRUPT_SAB_BYTES = 2;
+var INTERRUPT_SIGINT = 2;
+var INTERRUPT_ACK_INDEX = 1;
+var INTERRUPT_RETRY_MS = 15;
+var INTERRUPT_RETRY_LIMIT_MS = 1e4;
+function tryCreateInterruptBuffer() {
+  try {
+    return new SharedArrayBuffer(INTERRUPT_SAB_BYTES);
+  } catch {
+    return null;
+  }
+}
+function requestInterrupt(sab, stillRunning, retryMs = INTERRUPT_RETRY_MS, limitMs = INTERRUPT_RETRY_LIMIT_MS) {
+  const view = new Uint8Array(sab);
+  if (view.length > INTERRUPT_ACK_INDEX) {
+    Atomics.store(view, INTERRUPT_ACK_INDEX, 0);
+  }
+  Atomics.store(view, 0, INTERRUPT_SIGINT);
+  if (view.length <= INTERRUPT_ACK_INDEX) {
+    return;
+  }
+  const deadline = Date.now() + limitMs;
+  const retry = () => {
+    if (Atomics.load(view, INTERRUPT_ACK_INDEX) !== 0 || !stillRunning() || Date.now() > deadline) {
+      return;
+    }
+    if (Atomics.load(view, 0) === 0) {
+      Atomics.store(view, 0, INTERRUPT_SIGINT);
+    }
+    setTimeout(retry, retryMs);
+  };
+  setTimeout(retry, retryMs);
 }
 
-// src/common/errors/typeCheckExplainer.ts
-var FRIENDLY_TYPES = {
-  int: "a whole number",
-  float: "a number",
-  complex: "a complex number",
-  str: "a string",
-  bool: "`True` or `False`",
-  bytes: "bytes",
-  list: "a list",
-  dict: "a dictionary",
-  set: "a set",
-  tuple: "a tuple",
-  None: "`None`",
-  NoneType: "`None`"
+// src/pyodide/runtime.ts
+var NOT_RUNNING = "Python is not running.";
+var PythonLostError = class extends Error {
+  constructor() {
+    super("Python stopped completely.");
+    this.name = "PythonLostError";
+  }
 };
-function cleanTypeName(type) {
-  return type.startsWith("__main__.") ? type.slice("__main__.".length) : type;
-}
-function describeType(type) {
-  const name = cleanTypeName(type);
-  if (name === "None" || name === "NoneType") return "`None`";
-  const friendly = FRIENDLY_TYPES[name];
-  return friendly ? `${friendly} (\`${name}\`)` : `\`${name}\``;
-}
-function describeTypes(types) {
-  const described = types.map(describeType);
-  if (described.length === 0) return "a different type";
-  if (described.length === 1) return described[0];
-  return `${described.slice(0, -1).join(", ")} or ${described[described.length - 1]}`;
-}
-function boolAsNumberNote(expected, actual, level) {
-  if (actual !== "bool" || expected.length === 0) return null;
-  if (!expected.some((type) => type === "int" || type === "float")) return null;
-  if (level !== void 0 && !levelRejectsBoolAsNumber(level)) return null;
-  return "At `#level beginner` and `#level intermediate`, `True` and `False` are not accepted as numbers, even though Python counts them as `1` and `0`.";
-}
-function conversionFor(expected, actual) {
-  if (expected.length !== 1 || actual === null) return null;
-  const to = expected[0];
-  const numeric = actual === "int" || actual === "float" || actual === "bool";
-  if (to === "int" && (actual === "str" || actual === "float")) return "int";
-  if (to === "float" && actual === "str") return "float";
-  if (to === "str" && numeric) return "str";
-  return null;
+var StoppedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StoppedError";
+  }
+};
+function deliverDisplay(display, onEvent, fileName) {
+  onEvent(display.kind === "image" || display.kind === "table" ? { ...display, source: fileName } : display);
 }
-var ELEMENT_RE = /^(item \d+|key .+|value of key .+|\[.+\]) of (.+)$/;
-function membersPhrase(element) {
-  if (element.startsWith("the value for key")) return "every value in";
-  if (element.startsWith("key ")) return "every key in";
-  return "every item in";
-}
-function describeElement(element) {
-  if (element.startsWith("value of key ")) {
-    return `the value for key ${element.slice("value of key ".length)}`;
-  }
-  if (element.startsWith("[")) return "one of the values";
-  return element;
-}
-function parseTypeCheckMessage(message) {
-  const unknown = {
-    kind: "unknown",
-    name: null,
-    element: null,
-    actual: null,
-    expected: []
-  };
-  const lines = message.split(/\r?\n/);
-  const first = lines[0].trim();
-  let expected = [];
-  let subject = null;
-  const unionAt = first.indexOf(" did not match any element in the union:");
-  if (unionAt >= 0) {
-    subject = first.slice(0, unionAt);
-    for (const raw of lines.slice(1)) {
-      const m = raw.match(/^\s*([A-Za-z_][A-Za-z0-9_.\[\], ]*):/);
-      if (m) expected.push(m[1].trim());
+var WorkerConnection = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  worker = null;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  initPromise = null;
+  stdinBuffer = null;
+  interruptBuffer = null;
+  stdinHandler = null;
+  /** The stdin request being answered, or null; a Stop ends it. */
+  stdinRequest = null;
+  /** Stdin read but not yet given: what did not fit, or what came after a Stop. */
+  stdinCarry = new Uint8Array(0);
+  /** The handler's answer being waited for, which the next request shares. */
+  stdinNext = null;
+  packageNoteHandler = null;
+  pythonLostHandler = null;
+  /** Start the worker, once - or again, if the last attempt failed. */
+  async initialize() {
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize().catch((err) => {
+        this.initPromise = null;
+        this.worker?.terminate();
+        this.worker = null;
+        throw err;
+      });
     }
-  } else {
-    const predicates = [
-      [/^(.*) is not an instance of (.+)$/, (m) => [m[2]]],
-      [/^(.*) is neither float or int$/, () => ["float"]],
-      [/^(.*) is not None$/, () => ["None"]],
-      [/^(.*) is not a ([A-Za-z_][A-Za-z0-9_]*)$/, (m) => [m[2]]]
-    ];
-    for (const [re, pick] of predicates) {
-      const m = first.match(re);
-      if (m) {
-        subject = m[1];
-        expected = pick(m);
-        break;
+    await this.initPromise;
+  }
+  async doInitialize() {
+    const indexUrl = this.options.indexUrl();
+    const worker = this.options.spawn({
+      onMessage: (msg) => this.handleMessage(msg, worker),
+      onError: (err) => this.rejectAllPending(err),
+      onExit: () => this.pythonLost(worker)
+    });
+    this.worker = worker;
+    this.stdinBuffer = tryCreateStdinBuffer();
+    this.interruptBuffer = tryCreateInterruptBuffer();
+    const packageCacheDir = this.options.packageCacheDir?.(indexUrl);
+    const started = this.send("init", {
+      indexUrl,
+      ...packageCacheDir ? { packageCacheDir } : {},
+      ...this.stdinBuffer ? { stdinBuffer: this.stdinBuffer } : {},
+      ...this.interruptBuffer ? { interruptBuffer: this.interruptBuffer } : {}
+    });
+    const limit = this.options.startTimeoutMs;
+    if (limit === void 0) {
+      await started;
+      return;
+    }
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`Python did not start within ${Math.round(limit / 1e3)} seconds`)),
+        limit
+      );
+    });
+    try {
+      await Promise.race([started, timedOut]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** Whether Python has been started, or is starting. */
+  get started() {
+    return this.initPromise !== null;
+  }
+  /** A request, once Python has started; `live` is where its output goes as it runs. */
+  async request(type, fields, live = null) {
+    await this.initialize();
+    return this.send(type, fields, live);
+  }
+  /** `fn(*args)` in Python, and what it returns; `live` streams its output. */
+  async call(fn, args, live) {
+    return await this.request("call", { fn, args, live: live !== void 0 }, live ?? null);
+  }
+  /**
+   * Ask a running program to stop, by raising `KeyboardInterrupt` at the
+   * interpreter's next bytecode check. Synchronous on purpose: the worker is
+   * blocked inside `runPython` and would not read a message until it
+   * returned. Returns false when there is no interrupt channel (no
+   * `SharedArrayBuffer`), so callers can say so rather than appear to work.
+   */
+  interrupt() {
+    if (!this.interruptBuffer) {
+      return false;
+    }
+    if (this.stdinBuffer && this.stdinRequest !== null) {
+      this.stdinRequest = null;
+      interruptStdin(this.stdinBuffer);
+    }
+    const running = new Set(this.pending.keys());
+    requestInterrupt(this.interruptBuffer, () => {
+      for (const id of running) {
+        if (this.pending.has(id)) return true;
+      }
+      return false;
+    });
+    return true;
+  }
+  /**
+   * Told when Python had to be replaced - its worker stopped, or it could
+   * no longer run - and so every session's names are gone. The request in
+   * flight fails with `PythonLostError`; the next starts a new Python.
+   */
+  setPythonLostHandler(handler) {
+    this.pythonLostHandler = handler;
+  }
+  /**
+   * Who hears what Pyodide says while it loads a package: "Loading pytest,
+   * ..." or, `failed`, why it could not. Without one, the host's log.
+   */
+  setPackageNoteHandler(handler) {
+    this.packageNoteHandler = handler;
+  }
+  /**
+   * Register the handler asked for the next of stdin when a running program
+   * reads it - `input()`, `sys.stdin.read()`. It resolves with the next text
+   * or bytes, exactly as the program should read them (a line typed is that
+   * line and its newline), or `null` at the end of stdin. The worker waits
+   * until it does, or until a Stop, which raises `KeyboardInterrupt` in the
+   * read.
+   */
+  setStdinHandler(handler) {
+    this.stdinHandler = handler;
+  }
+  dispose() {
+    this.worker?.terminate();
+    this.worker = null;
+    this.initPromise = null;
+    this.stdinBuffer = null;
+    this.interruptBuffer = null;
+    this.rejectAllPending(new Error("Runtime disposed"));
+  }
+  /** Send a request to the worker as it is now, and resolve with its reply. */
+  send(type, fields, live = null) {
+    const worker = this.worker;
+    if (!worker) {
+      return Promise.reject(new Error(NOT_RUNNING));
+    }
+    const id = this.nextId++;
+    return new Promise((resolve4, reject) => {
+      this.pending.set(id, { resolve: resolve4, reject, live });
+      worker.post({ id, type, ...fields });
+    });
+  }
+  handleMessage(msg, worker) {
+    if (msg.type === "display") {
+      const live = this.pending.get(msg.requestId)?.live;
+      if (live) {
+        deliverDisplay(msg.payload, live.onEvent, live.fileName);
       }
+      return;
+    }
+    if (msg.type === "stdinRequest") {
+      void this.handleStdinRequest(msg.request);
+      return;
+    }
+    if (msg.type === "packageNote") {
+      if (this.packageNoteHandler) this.packageNoteHandler(msg.text, msg.failed);
+      else console.error(msg.text);
+      return;
+    }
+    if (msg.type === "error" && msg.kind === "finished") {
+      this.pythonLost(worker);
+      return;
+    }
+    const pending = this.pending.get(msg.id);
+    if (!pending) {
+      return;
+    }
+    this.pending.delete(msg.id);
+    if (msg.type === "error") {
+      pending.reject(msg.kind === "interrupted" ? new StoppedError(msg.message) : new Error(msg.message));
+    } else {
+      pending.resolve(msg.value);
+    }
+  }
+  /**
+   * Python is gone: the worker exited (only a Node worker can say so), or
+   * the interpreter in it is finished and refuses everything. Either way
+   * nothing sent to it can succeed. Fail what was waiting, end the worker,
+   * and forget it, so that the next request starts a new Python.
+   *
+   * Every session's names went with the old one - but they were gone
+   * already: this follows Python stopping by itself, and never ends a
+   * Python that could still run. Whoever set `setPythonLostHandler` is told,
+   * so that each file can say so rather than only the one that was running.
+   */
+  pythonLost(worker) {
+    if (this.worker !== worker) return;
+    this.rejectAllPending(new PythonLostError());
+    this.worker = null;
+    this.initPromise = null;
+    worker.terminate();
+    this.pythonLostHandler?.();
+  }
+  rejectAllPending(err) {
+    for (const pending of this.pending.values()) {
+      pending.reject(err);
     }
+    this.pending.clear();
   }
-  if (subject === null) return unknown;
-  let actual = null;
-  const withActual = subject.match(/^(.*) \(([^()]*)\)$/);
-  if (withActual) {
-    subject = withActual[1];
-    actual = withActual[2];
-  }
-  let element = null;
-  const elementMatch = subject.match(ELEMENT_RE);
-  if (elementMatch) {
-    element = describeElement(elementMatch[1]);
-    subject = elementMatch[2];
-  }
-  if (subject === "the return value") {
-    return { kind: "return", name: null, element, actual, expected };
-  }
-  const argument = subject.match(/^argument "(.+)"$/);
-  if (argument) {
-    return { kind: "argument", name: argument[1], element, actual, expected };
-  }
-  const assigned = subject.match(/^value assigned to (.+)$/);
-  if (assigned) {
-    return { kind: "variable", name: assigned[1], element, actual, expected };
-  }
-  return { ...unknown, element, actual, expected };
-}
-function explainTypeCheckError(message, functionName, level) {
-  const parsed = parseTypeCheckMessage(message);
-  const wanted = describeTypes(parsed.expected);
-  const owner = functionName ? `\`${functionName}\`` : "this function";
-  const named = parsed.name ? `\`${parsed.name}\`` : "a value";
-  const convert = conversionFor(parsed.expected, parsed.actual);
-  const boolNote = boolAsNumberNote(parsed.expected, parsed.actual, level);
-  const annotation = parsed.expected.length === 1 ? cleanTypeName(parsed.expected[0]) : null;
-  if (parsed.kind === "argument") {
-    if (parsed.element) {
-      return {
-        headline: `${owner} expects ${membersPhrase(parsed.element)} ${named} to be ${wanted}, but ${parsed.element} is not.`,
-        howToFix: [
-          `Look at ${parsed.element} of the ${parsed.actual ?? "value"} you passed for ${named}.`,
-          "Every one has to match the annotation, not just the first."
-        ]
-      };
-    }
-    const got = parsed.actual ? `, but got ${describeType(parsed.actual)}` : "";
-    const howToFix = [`Check the value you passed for ${named} on this line.`];
-    if (boolNote) howToFix.push(boolNote);
-    if (convert) {
-      howToFix.push(`If it should be ${wanted}, convert it with \`${convert}(...)\`.`);
-    }
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or, if ${named} really should be ${describeType(parsed.actual)}, change its annotation in ${owner} from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
-      );
+  /**
+   * The next of stdin from the handler. One call at a time: a request a
+   * Stop ended leaves its call waiting, and the next request - a program
+   * that caught the `KeyboardInterrupt` and asked again - shares it, so
+   * the line typed answers that one.
+   */
+  nextStdin() {
+    if (this.stdinNext === null) {
+      const call = (async () => {
+        try {
+          const next = this.stdinHandler ? await this.stdinHandler() : null;
+          return typeof next === "string" ? new TextEncoder().encode(next) : next;
+        } catch {
+          return null;
+        }
+      })();
+      this.stdinNext = call;
+      void call.then(() => {
+        if (this.stdinNext === call) this.stdinNext = null;
+      });
     }
-    return {
-      headline: `${owner} expects ${named} to be ${wanted}${got}.`,
-      howToFix
-    };
+    return this.stdinNext;
   }
-  if (parsed.kind === "return") {
-    if (parsed.actual === "None" || parsed.actual === "NoneType") {
-      return {
-        headline: `${owner} should return ${wanted}, but it finished without returning a value.`,
-        howToFix: [
-          "Make sure every path through the function reaches a `return`.",
-          "An `if` with no `else` falls off the end, and Python then returns `None`.",
-          `Or annotate the return type as \`None\` if ${owner} is not meant to return anything.`
-        ]
-      };
+  async handleStdinRequest(request) {
+    this.stdinRequest = request;
+    let bytes = this.stdinCarry;
+    if (bytes.length === 0) {
+      bytes = await this.nextStdin();
+      if (this.stdinRequest !== request) {
+        if (bytes !== null && this.stdinRequest === null) {
+          this.stdinCarry = concatBytes(this.stdinCarry, bytes);
+        }
+        return;
+      }
     }
-    const got = parsed.actual ? describeType(parsed.actual) : "something else";
-    const howToFix = [];
-    const wantsNone = parsed.expected.length === 1 && /^(None|NoneType)$/.test(parsed.expected[0]);
-    if (wantsNone) {
-      howToFix.push("Use a bare `return`, or drop the `return` entirely.");
-    } else if (convert) {
-      howToFix.push(`Convert the returned value with \`${convert}(...)\`.`);
+    this.stdinRequest = null;
+    if (!this.stdinBuffer) {
+      return;
+    }
+    const given = writeStdin(this.stdinBuffer, request, bytes);
+    if (bytes === null) {
+      this.stdinCarry = new Uint8Array(0);
     } else {
-      howToFix.push(`Return ${wanted} from this line.`);
+      this.stdinCarry = bytes.subarray(Math.max(given, 0));
     }
-    if (boolNote) howToFix.push(boolNote);
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or change ${owner}'s return annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
+  }
+};
+function concatBytes(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+}
+
+// src/run/examplar.ts
+async function runExamplarStep(runtime, bundles, host, code, fileName) {
+  const bundle = await fetchBundle(bundles, host, code);
+  if (bundle === null) {
+    return null;
+  }
+  host.status("Checking your tests...");
+  try {
+    await runtime.mountWorkspaceFiles([]);
+  } catch (err) {
+    if (!(err instanceof StoppedError)) {
+      host.examplarCard(
+        failedCard(
+          bundle,
+          `the known implementations were not run: your files could not be set aside first (${errorText(err)})`
+        )
       );
     }
-    return {
-      headline: `${owner} says it returns ${wanted}, but this line returns ${got}.`,
-      howToFix
-    };
+    return false;
   }
-  if (parsed.kind === "variable") {
-    if (parsed.element) {
-      return {
-        headline: `${named} is annotated so ${membersPhrase(parsed.element)} it is ${wanted}, but ${parsed.element} is not.`,
-        howToFix: [`Look at ${parsed.element} of the value assigned to ${named}.`]
-      };
-    }
-    const got = parsed.actual ? describeType(parsed.actual) : "a different type";
-    const howToFix = [`Assign ${wanted} to ${named}.`];
-    if (boolNote) howToFix.push(boolNote);
-    if (convert) {
-      howToFix.push(`You can convert the value with \`${convert}(...)\`.`);
-    }
-    if (annotation && parsed.actual) {
-      howToFix.push(
-        `Or change ${named}'s annotation from \`${annotation}\` to \`${cleanTypeName(parsed.actual)}\`.`
-      );
+  try {
+    await runtime.ensurePytest();
+  } catch {
+  }
+  if (host.stopRequested()) {
+    return false;
+  }
+  let result;
+  try {
+    result = await runtime.examplarRun(code, bundle.json, fileName);
+  } catch (err) {
+    if (!(err instanceof StoppedError)) {
+      host.examplarCard(failedCard(bundle, errorText(err)));
     }
-    return {
-      headline: `${named} is annotated as ${wanted}, but ${got} was assigned here.`,
-      howToFix
-    };
+    return false;
+  }
+  for (const entry of buildExamplarEntries(bundle, result)) {
+    host.examplarCard(entry);
+  }
+  const provides = result.provides ?? [];
+  const defines = result.wheats?.[0]?.studentDefines ?? [];
+  return provides.length > 0 && provides.every((name) => defines.includes(name));
+}
+async function fetchBundle(bundles, host, code) {
+  const directive = parseExamplarDirective(code);
+  if (directive.kind === "none") {
+    return null;
+  }
+  if (directive.kind === "error") {
+    host.say(`Line ${directive.line}: ${directive.message}`, "problem");
+    return null;
   }
+  host.status("Loading implementations...");
+  const load = await loadBundle(directive.url, bundles);
+  if (load.note) {
+    host.say(`Known implementations: ${load.note}`, "note");
+  }
+  if (!load.json) {
+    host.say(`Could not load the known implementations from ${directive.url}: ${load.error}`, "problem");
+    return null;
+  }
+  return { url: directive.url, json: load.json, cached: load.fromCache };
+}
+function failedCard(bundle, problem) {
   return {
-    headline: "A value does not match the type annotation written for it.",
-    howToFix: [
-      message.split(/\r?\n/)[0].trim(),
-      "Either pass a value of the annotated type, or change the annotation."
-    ]
+    kind: "examplar",
+    url: bundle.url,
+    cached: bundle.cached,
+    card: "failed",
+    problem,
+    body: [{ kind: "line", tone: "bad", text: problem }]
   };
 }
-
-// src/common/analyzers/typeCheckAnalyzer.ts
-var HANDLED = ["TypeCheckError", "typeguard.TypeCheckError"];
-function messageWithDetail(traceback, fallback) {
-  const lines = traceback.split(/\r?\n/);
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const line = lines[i];
-    const marker = line.indexOf("TypeCheckError:");
-    if (line.startsWith(" ") || marker < 0) continue;
-    const detail = [line.slice(marker + "TypeCheckError:".length).trim()];
-    for (let j = i + 1; j < lines.length; j++) {
-      if (lines[j].trim() === "") continue;
-      if (!lines[j].startsWith(" ")) break;
-      detail.push(lines[j]);
-    }
-    return detail.join("\n");
-  }
-  return fallback;
-}
-var typeCheckAnalyzer = {
-  handles: HANDLED,
-  analyze(input) {
-    const { parsedError, fileName, level } = input;
-    if (!HANDLED.includes(parsedError.errorType)) {
-      return null;
+function buildExamplarEntries(bundle, result) {
+  if (!result.ok) {
+    return [failedCard(bundle, result.error ?? "the known implementations could not be run")];
+  }
+  if (result.timedOut) {
+    return [failedCard(bundle, timedOutProblem(result.timedOut))];
+  }
+  const wheats = result.wheats ?? [];
+  const unloadable = wheats.find((w) => !w.loaded) ?? (result.chaffs ?? []).find((c) => !c.loaded);
+  if (unloadable) {
+    const which = unloadable.targets === void 0 ? "correct" : "buggy";
+    return [
+      failedCard(
+        bundle,
+        `a known ${which} implementation could not be loaded (${unloadable.errorType}: ${unloadable.errorMessage}). The bundle may need rebuilding.`
+      )
+    ];
+  }
+  const disagreed = /* @__PURE__ */ new Set();
+  const raised = /* @__PURE__ */ new Map();
+  for (const wheat of wheats) {
+    for (const [test, outcome] of Object.entries(wheat.tests)) {
+      if (outcome.outcome === "fail") {
+        disagreed.add(test);
+      } else if (outcome.outcome === "error" && !raised.has(test)) {
+        raised.set(test, shownError(outcome.message ?? outcome.outcome));
+      }
     }
-    const message = messageWithDetail(parsedError.traceback, parsedError.message);
-    const parsed = parseTypeCheckMessage(message);
-    const frames = userTracebackFrames(parsedError.traceback);
-    const innermost = frames.length > 0 ? frames[frames.length - 1] : null;
-    const blamed = parsed.kind === "argument" && frames.length >= 2 ? frames[frames.length - 2] : innermost;
-    const explanation = explainTypeCheckError(
-      message,
-      innermost ? innermost.functionName : null,
-      level
-    );
-    return {
-      id: "type-check",
-      // Not a real Python exception name; "TypeCheckError" means nothing to
-      // a student, and "TypeError" would name a different Python error.
-      errorType: "TypeMismatch",
-      message,
-      headline: explanation.headline,
-      howToFix: explanation.howToFix,
-      fileName: blamed ? blamed.fileName : fileName,
-      lineNumber: blamed ? blamed.line : parsedError.lineNumber,
-      column: null,
-      nameToken: parsed.name,
-      severity: "error",
-      raw: parsedError.traceback,
-      origin: "runtime",
-      level
+  }
+  const unloadedFiles = (wheats[0]?.unloaded ?? []).filter((u) => isFileAccessError(u.error));
+  for (const test of disagreed) {
+    raised.delete(test);
+  }
+  const attribution = result.attribution ?? {};
+  const chaffs = result.chaffs ?? [];
+  const skipped = new Set(result.chaffsSkipped ?? []);
+  return (result.provides ?? []).map((name) => {
+    const tests = Object.entries(attribution).filter(([, names]) => names.includes(name)).map(([test]) => test);
+    const failures = tests.filter((test) => disagreed.has(test));
+    const errors = tests.filter((test) => raised.has(test)).map((test) => ({ test, message: raised.get(test) }));
+    const mine = chaffs.filter((c) => c.targets === name);
+    const missed = mine.filter((c) => c.loaded && Object.values(c.tests).every((t) => t.outcome === "pass")).map((c) => c.id);
+    const card = {
+      kind: "examplar",
+      url: bundle.url,
+      cached: bundle.cached,
+      card: "function",
+      name,
+      testCount: tests.length,
+      allPass: tests.length > 0 && failures.length === 0 && errors.length === 0,
+      failures,
+      errors,
+      hint: errors.length > 0 && (errors.some((e) => isFileAccessError(e.message)) || unloadedFiles.length > 0) ? UNMOUNTED_HINT + unloadedFiles.map((u) => ` Line ${u.line} could not run here: ${u.error}.`).join("") : void 0,
+      total: mine.length,
+      caught: mine.length - missed.length,
+      missed,
+      // The primitive gates phase two per function, so `mine` is normally
+      // already empty here. Deciding again from this function's own verdict
+      // rather than trusting the flag keeps a coverage number from ever
+      // appearing beside a test that did not pass.
+      pending: failures.length > 0 || errors.length > 0 || skipped.has(name)
     };
+    return { ...card, body: cardBody(card) };
+  });
+}
+function cardBody(card) {
+  if (card.testCount === 0) {
+    return [{ kind: "line", tone: "note", text: "No tests yet." }];
+  }
+  const CORRECT = "Against correct implementations: ";
+  const BUGGY = "Against buggy implementations: ";
+  const total = card.testCount;
+  const some = (n) => total === 1 ? "your test" : `${n} of your ${total} tests`;
+  const does = (n) => n === 1 ? "s" : "";
+  const body = [];
+  if (card.allPass) {
+    body.push({
+      kind: "line",
+      tone: "good",
+      text: total === 1 ? `${CORRECT}your test passes.` : `${CORRECT}all ${total} of your tests pass.`
+    });
   }
-};
-
-// src/common/analyzers/registry.ts
-var analyzers = [nameErrorAnalyzer, typeCheckAnalyzer];
-function findRuntimeFinding(source, fileName, level, parsedError) {
-  for (const analyzer of analyzers) {
-    if (!analyzer.handles.includes(parsedError.errorType)) {
-      continue;
+  if (card.failures.length > 0) {
+    const n = card.failures.length;
+    body.push({ kind: "line", tone: "bad", text: `${CORRECT}${some(n)} expect${does(n)} the wrong answer:` });
+    for (const test of card.failures) {
+      body.push({ kind: "item", tone: "bad", name: test });
     }
-    const finding = analyzer.analyze({ source, fileName, level, parsedError });
-    if (finding) {
-      return finding;
+  }
+  if (card.errors.length > 0) {
+    body.push({ kind: "line", tone: "warn", text: `${CORRECT}${some(card.errors.length)} could not run here:` });
+    for (const { test, message } of card.errors) {
+      body.push({ kind: "item", tone: "warn", name: test, detail: message });
     }
+    if (card.hint) body.push({ kind: "line", tone: "note", text: card.hint });
   }
-  return null;
-}
-
-// src/common/analyzers/runtimeFinding.ts
-function findingForErrorEvent(event, source, fileName, level) {
-  const traceback = event.traceback || `${event.errorType}: ${event.message}`;
-  const parsed = parsePythonError(traceback, source);
-  if (parsed.lineNumber === null && event.lineNumber != null) {
-    parsed.lineNumber = event.lineNumber;
+  if (card.pending) {
+    body.push({ kind: "line", tone: "note", text: `${BUGGY}waiting until all your tests of ${card.name} pass.` });
+  } else if (card.caught === card.total) {
+    body.push({ kind: "line", tone: "good", text: `${BUGGY}caught all ${card.total}.` });
+  } else {
+    body.push({
+      kind: "line",
+      tone: "warn",
+      text: `${BUGGY}caught ${card.caught} of ${card.total} - missed ${card.missed.join(", ")}.`
+    });
   }
-  if (parsed.column === null && event.column != null) {
-    parsed.column = event.column;
+  return body;
+}
+var UNMOUNTED_HINT = "Your tests are checked on their own, so files next to your program are not available while that happens.";
+function isFileAccessError(message) {
+  return /^(FileNotFoundError|IsADirectoryError|NotADirectoryError|PermissionError|ModuleNotFoundError|ImportError):/.test(
+    message
+  );
+}
+function shownError(message) {
+  if (isFileAccessError(message) || /^(NameError|UnboundLocalError):/.test(message)) {
+    return message;
   }
-  if (parsed.fileName === null && event.fileName) {
-    parsed.fileName = event.fileName;
+  return message.split(":")[0];
+}
+function timedOutProblem(stuck) {
+  const against = stuck.kind === "wheat" ? "a known correct implementation" : "a known buggy implementation";
+  if (stuck.test === null) {
+    return `Loading your definitions with ${against} took more than ${stuck.seconds} seconds, so the check stopped.`;
   }
-  return findRuntimeFinding(source, fileName, level, parsed);
+  return `\`${stuck.test}\` ran for more than ${stuck.seconds} seconds against ${against}, so the check stopped. ` + (stuck.kind === "wheat" ? "A test that runs that long is usually stuck in a loop." : "That implementation may never finish on what this test gives it; tell your course staff.");
 }
 
-// src/common/pyodideRunner.ts
-var ANY_IMPORT_RE = /(^|\n)[ \t]*(import|from)[ \t]+\S/;
-var PANDAS_METHOD_RE = /\.\s*to_pandas\s*\(/;
-var NEEDS_PACKAGES_RE_LIST = [PANDAS_METHOD_RE];
-function needsPackages(code) {
-  return ANY_IMPORT_RE.test(code) || NEEDS_PACKAGES_RE_LIST.some((re) => re.test(code));
+// src/run/packages.ts
+var MAY_NEED_PACKAGES_RE = /\bimport\b|__import__|\.\s*to_pandas\s*\(/;
+function needsPackages(code, siblings = []) {
+  return [code, ...siblings.map((sibling) => sibling.text)].some((text) => MAY_NEED_PACKAGES_RE.test(text));
 }
 
-// src/cli/files.ts
-var fs = __toESM(require("node:fs/promises"));
-var path = __toESM(require("node:path"));
-
-// src/common/workspaceFilePolicy.ts
+// src/core/files.ts
 var MAX_FILE_BYTES = 2 * 1024 * 1024;
 var MAX_TOTAL_BYTES = 8 * 1024 * 1024;
-var MAX_FILES = 50;
+var MAX_FILES = 100;
+var MB = 1024 * 1024;
+var WHY_LEFT_OUT = {
+  count: () => `at most ${MAX_FILES} files next to a program are`,
+  size: () => `each file can be at most ${MAX_FILE_BYTES / MB} MB`,
+  total: () => `the files together can be at most ${MAX_TOTAL_BYTES / MB} MB`,
+  unreadable: () => "it could not be read",
+  notLoaded: () => "it was not loaded, so saving it would replace a file the program never saw",
+  changed: () => "it changed on disk while the program ran",
+  python: () => "PLL never overwrites or deletes a .py file",
+  hidden: () => "PLL saves nothing into hidden folders",
+  unsaved: () => "it has unsaved changes in the editor; save it and run again",
+  failed: () => "it could not be written"
+};
+function leftOutNotes(leftOut, action) {
+  const notes = [];
+  for (const reason of Object.keys(WHY_LEFT_OUT)) {
+    const kept = leftOut.filter((file) => file.reason === reason);
+    if (kept.length === 0) {
+      continue;
+    }
+    const names = kept.map((file) => file.detail ? `${file.name} (${file.detail})` : file.name);
+    const shown = names.slice(0, 5).join(", ");
+    const more = names.length > 5 ? ` and ${names.length - 5} more` : "";
+    notes.push(`Not ${action}: ${shown}${more} - ${WHY_LEFT_OUT[reason](action)}.`);
+  }
+  return notes;
+}
 var MOUNT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".csv",
-  ".txt",
   ".tsv",
+  ".txt",
+  ".text",
   ".json",
   ".md",
   ".dat",
   ".xml",
+  ".html",
+  ".htm",
+  ".log",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".cfg",
   ".py",
-  // Pictures, for `load_image`. `.svg` is not in BINARY_EXTENSIONS below
-  // because it is text, and mounting it as text is lossless.
   ".svg",
   ".png",
   ".jpg",
@@ -747,43 +1057,26 @@ var MOUNT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".gif",
   ".webp"
 ]);
-var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
-var WRITEBACK_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".csv",
-  ".txt",
-  ".tsv",
-  ".json",
-  ".md",
-  ".dat",
-  ".xml"
-]);
+var TOOL_FOLDERS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", "venv", "env", "site-packages"]);
 function extensionOf(name) {
-  const dot = name.lastIndexOf(".");
-  if (dot <= 0) {
-    return "";
-  }
-  return name.slice(dot).toLowerCase();
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "" : base.slice(dot).toLowerCase();
 }
-function isSafeBasename(name) {
-  if (!name || name === "." || name === "..") {
-    return false;
-  }
-  if (name.startsWith(".")) {
-    return false;
-  }
-  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+function isSafePath(name) {
+  if (!name || name.includes("\\") || name.includes("\0") || name.startsWith("/")) {
     return false;
   }
-  return true;
+  return name.split("/").every((part) => part !== "" && part !== "." && part !== "..");
 }
-function isMountableName(name) {
-  return isSafeBasename(name) && MOUNT_EXTENSIONS.has(extensionOf(name));
+function isHiddenPath(name) {
+  return name.split("/").some((part) => part.startsWith(".") || TOOL_FOLDERS.has(part));
 }
-function isWritebackName(name) {
-  return isSafeBasename(name) && WRITEBACK_EXTENSIONS.has(extensionOf(name));
+function isWalkedFolder(name) {
+  return !name.startsWith(".") && !TOOL_FOLDERS.has(name);
 }
-function isBinaryMountName(name) {
-  return BINARY_EXTENSIONS.has(extensionOf(name));
+function isMountableName(name) {
+  return isSafePath(name) && !isHiddenPath(name) && MOUNT_EXTENSIONS.has(extensionOf(name));
 }
 function utf8ByteLength(text) {
   return new TextEncoder().encode(text).byteLength;
@@ -791,125 +1084,480 @@ function utf8ByteLength(text) {
 function contentsByteLength(contents) {
   return typeof contents === "string" ? utf8ByteLength(contents) : contents.byteLength;
 }
-function decodeMountContents(data) {
-  if (data.byteLength > MAX_FILE_BYTES) {
-    return void 0;
-  }
-  for (let i = 0; i < data.byteLength; i++) {
-    if (data[i] === 0) {
-      return void 0;
-    }
-  }
-  return new TextDecoder("utf-8").decode(data);
+function contentsBytes(contents) {
+  return typeof contents === "string" ? new TextEncoder().encode(contents) : contents;
 }
-function selectMountableFiles(candidates) {
-  const selected = [];
+async function readSiblingFiles(folder) {
+  let entries;
+  try {
+    entries = await folder.files();
+  } catch {
+    return { files: [], leftOut: [], loaded: {} };
+  }
+  const depth = (name) => name.split("/").length;
+  const ordered = entries.filter((entry) => isMountableName(entry.name)).sort((a, b) => depth(a.name) - depth(b.name) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const files = [];
+  const leftOut = [];
+  const loaded = {};
   let total = 0;
-  for (const candidate of candidates) {
-    if (selected.length >= MAX_FILES) {
-      break;
+  for (const entry of ordered) {
+    if (files.length >= MAX_FILES) {
+      leftOut.push({ name: entry.name, reason: "count" });
+      continue;
     }
-    if (!isMountableName(candidate.name)) {
+    if (entry.size > MAX_FILE_BYTES) {
+      leftOut.push({ name: entry.name, reason: "size" });
       continue;
     }
     let contents;
-    if (isBinaryMountName(candidate.name)) {
-      const raw = typeof candidate.contents === "string" ? new TextEncoder().encode(candidate.contents) : candidate.contents;
-      if (raw.byteLength > MAX_FILE_BYTES) {
-        continue;
-      }
-      contents = raw;
-    } else if (typeof candidate.contents === "string") {
-      if (utf8ByteLength(candidate.contents) > MAX_FILE_BYTES) {
-        continue;
-      }
-      if (candidate.contents.includes("\0")) {
-        continue;
-      }
-      contents = candidate.contents;
-    } else {
-      const decoded = decodeMountContents(candidate.contents);
-      if (decoded === void 0) {
-        continue;
-      }
-      contents = decoded;
+    try {
+      contents = await folder.read(entry.name);
+    } catch (err) {
+      leftOut.push({ name: entry.name, reason: "unreadable", detail: errorCode(err) });
+      continue;
     }
     const size = contentsByteLength(contents);
+    if (size > MAX_FILE_BYTES) {
+      leftOut.push({ name: entry.name, reason: "size" });
+      continue;
+    }
     if (total + size > MAX_TOTAL_BYTES) {
+      leftOut.push({ name: entry.name, reason: "total" });
       continue;
     }
-    selected.push({ name: candidate.name, contents });
+    files.push({ name: entry.name, contents });
+    loaded[entry.name] = { size: entry.size, mtimeMs: entry.mtimeMs };
     total += size;
   }
-  return selected;
+  return { files, leftOut, loaded };
 }
-function selectWritebackFiles(files) {
-  const selected = [];
+async function writeSiblingFiles(folder, changes, loaded) {
+  const written = [];
+  const deleted = [];
+  const leftOut = [];
   let total = 0;
-  for (const file of files) {
-    if (selected.length >= MAX_FILES) {
-      break;
+  const refusal = async (name) => {
+    if (!isSafePath(name)) return "hidden";
+    if (isHiddenPath(name)) return "hidden";
+    if (folder.unsaved?.(name)) return "unsaved";
+    const now = await folder.stat(name).catch(() => null);
+    const before = loaded[name];
+    if (now !== null && extensionOf(name) === ".py") return "python";
+    if (before === void 0) return now === null ? null : "notLoaded";
+    if (now === null || now.size !== before.size || now.mtimeMs !== before.mtimeMs) return "changed";
+    return null;
+  };
+  for (const file of [...changes.files].sort((a, b) => a.name < b.name ? -1 : 1)) {
+    const reason = await refusal(file.name);
+    if (reason !== null) {
+      leftOut.push({ name: file.name, reason });
+      continue;
     }
-    if (!isWritebackName(file.name)) {
+    const bytes = contentsBytes(file.contents);
+    if (written.length >= MAX_FILES) {
+      leftOut.push({ name: file.name, reason: "count" });
       continue;
     }
-    if (typeof file.contents !== "string") {
+    if (bytes.byteLength > MAX_FILE_BYTES) {
+      leftOut.push({ name: file.name, reason: "size" });
       continue;
     }
-    const size = utf8ByteLength(file.contents);
-    if (size > MAX_FILE_BYTES || total + size > MAX_TOTAL_BYTES) {
+    if (total + bytes.byteLength > MAX_TOTAL_BYTES) {
+      leftOut.push({ name: file.name, reason: "total" });
       continue;
     }
-    if (file.contents.includes("\0")) {
+    try {
+      await folder.write(file.name, bytes);
+      written.push(file.name);
+      total += bytes.byteLength;
+    } catch (err) {
+      leftOut.push({ name: file.name, reason: "failed", detail: errorCode(err) });
+    }
+  }
+  for (const name of [...changes.deleted].sort()) {
+    const reason = await refusal(name);
+    if (reason !== null) {
+      leftOut.push({ name, reason });
       continue;
     }
-    selected.push(file);
-    total += size;
+    try {
+      await folder.remove(name);
+      deleted.push(name);
+    } catch (err) {
+      leftOut.push({ name, reason: "failed", detail: errorCode(err) });
+    }
   }
-  return selected;
+  return { written, deleted, leftOut };
+}
+function errorCode(err) {
+  const code = err?.code;
+  const byCode = {
+    EACCES: "permission denied",
+    EPERM: "permission denied",
+    EROFS: "read-only file system",
+    ENOSPC: "no space left",
+    EISDIR: "a folder is in the way",
+    ENOTDIR: "a file is in the way",
+    NoPermissions: "permission denied"
+  };
+  if (typeof code === "string" && byCode[code]) return byCode[code];
+  const message = err instanceof Error ? err.message : String(err);
+  return message.split("\n")[0].slice(0, 80);
 }
 
-// src/cli/files.ts
-async function collectSiblingFiles(scriptPath) {
-  const folder = path.dirname(path.resolve(scriptPath));
-  let entries;
+// src/run/plan.ts
+var STOPPED = {
+  beforeStart: "Stopped before the program started. Nothing was run.",
+  checking: "Stopped while checking your tests. Your own tests and the program were not run.",
+  afterChecking: "Stopped before the program started.",
+  input: "Stopped. Your input was not run.",
+  program: "Stopped. The tests were not run.",
+  tests: "Stopped during the tests. The rest of the tests were not run.",
+  thrown: "Stopped."
+};
+async function runFilePlan(runtime, host, plan) {
+  const { code, fileName, sessionKey } = plan;
+  const level = parseLevel(code);
+  const tally = new Tally();
+  const header = levelHeaderFinding(code, fileName, level);
+  if (header !== null) {
+    host.staticFindings([header]);
+    host.say("The file was not run.", "problem");
+    return tally.summary("blocked");
+  }
+  host.level(level);
+  const checked = await staticChecks(runtime, host, code, fileName, level, null);
+  if (checked !== "passed") {
+    return tally.summary(checked);
+  }
+  const beforeStart = STOPPED.beforeStart;
+  const outcome = await withFiles(runtime, host, fileName, beforeStart, async (files, starting) => {
+    await loadPackages(runtime, host, code, await files.sources());
+    if (stopped(host, STOPPED.beforeStart)) {
+      return "stopped";
+    }
+    const complete = await runExamplarStep(runtime, plan.bundles, host, code, fileName);
+    if (complete !== null && stopped(host, STOPPED.checking)) {
+      return "stopped";
+    }
+    const beforeProgram = complete === null ? STOPPED.beforeStart : STOPPED.afterChecking;
+    await files.mount();
+    const withTests = plan.runTests && (complete !== false || plan.testsOfIncompleteFile === true) && await testsToRun(runtime, host, code);
+    if (stopped(host, beforeProgram)) {
+      return "stopped";
+    }
+    host.status("Running...");
+    starting();
+    const onEvent = tally.counting(programEvents(host, fileName, level));
+    const program = () => runtime.runFile({ code, fileName, sessionKey, level, withTests }, onEvent);
+    await (host.aroundProgram ? host.aroundProgram(program) : program());
+    if (withTests) {
+      sayWhyTestsStopped(host, tally);
+    }
+    const stopEnded = tally.testsStopped || tally.stopReached || tally.raised && host.stopRequested();
+    return stopEnded ? "stopped" : "ran";
+  });
+  return tally.summary(outcome);
+}
+var Tally = class {
+  raised = false;
+  testFailures = 0;
+  exitCode = null;
+  testsRan = false;
+  testsStopped = false;
+  stopReached = false;
+  counting(onEvent) {
+    return (event) => {
+      if (event.kind === "error") {
+        this.raised = true;
+      } else if (event.kind === "testReport") {
+        this.testsRan = true;
+        this.testsStopped = event.stopped === true;
+        this.testFailures += event.failed + event.errors;
+      } else if (event.kind === "done") {
+        if (event.exitCode !== void 0) this.exitCode = event.exitCode;
+        if (event.stopped) this.stopReached = true;
+      }
+      onEvent(event);
+    };
+  }
+  summary(outcome) {
+    return {
+      outcome,
+      raised: this.raised,
+      testFailures: this.testFailures,
+      exitCode: this.exitCode
+    };
+  }
+};
+function sayWhyTestsStopped(host, tally) {
+  if (tally.testsRan) {
+    if (tally.testsStopped) host.say(STOPPED.tests, "problem");
+    return;
+  }
+  if (host.stopRequested()) {
+    host.say(STOPPED.program, "problem");
+  } else if (tally.exitCode !== null) {
+    host.say("The tests were not run: the program ended itself first, with `sys.exit()`.", "problem");
+  } else if (tally.raised) {
+    host.say("The tests were not run, because of the error above.", "problem");
+  }
+}
+async function staticChecks(runtime, host, code, fileName, level, sessionKey) {
+  if (!levelHasStaticChecks(level)) {
+    return "passed";
+  }
+  const input = sessionKey !== null;
+  host.status("Checking...");
+  let findings;
   try {
-    entries = await fs.readdir(folder, { withFileTypes: true });
-  } catch {
-    return [];
+    findings = await runtime.staticAnalyze({
+      code,
+      fileName,
+      level,
+      ...input ? { sessionKey } : {}
+    });
+  } catch (err) {
+    if (err instanceof StoppedError) {
+      host.say(input ? STOPPED.input : STOPPED.beforeStart, "problem");
+      return "stopped";
+    }
+    host.say(`Static analysis failed (${errorText(err)}). Running anyway.`, "note");
+    return "passed";
   }
-  const candidates = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !isMountableName(entry.name)) {
-      continue;
+  host.staticFindings(findings);
+  const errors = findings.filter((finding) => finding.severity === "error").length;
+  if (errors === 0) {
+    return "passed";
+  }
+  host.say(
+    `Static analysis found ${errors} problem${errors === 1 ? "" : "s"}. ` + (input ? "Your input was not run." : "The file was not run."),
+    "problem"
+  );
+  return "blocked";
+}
+async function withFiles(runtime, host, fileName, beforeStart, run) {
+  let mounted = null;
+  let started = false;
+  let lost = false;
+  let selecting = null;
+  const select = () => selecting ??= host.siblingFiles();
+  const files = {
+    async sources() {
+      try {
+        return pythonSources(await select());
+      } catch (err) {
+        if (err instanceof StoppedError) throw err;
+        return [];
+      }
+    },
+    async mount() {
+      mounted = await mount(runtime, host, select);
     }
-    try {
-      candidates.push({ name: entry.name, contents: await fs.readFile(path.join(folder, entry.name)) });
-    } catch {
+  };
+  try {
+    return await run(files, () => {
+      started = true;
+    });
+  } catch (err) {
+    lost = err instanceof PythonLostError;
+    if (err instanceof StoppedError) {
+      host.say(started ? STOPPED.thrown : beforeStart, "problem");
+      return "stopped";
+    }
+    throw err;
+  } finally {
+    if (mounted !== null && !lost) {
+      await writeBack(runtime, host, fileName, mounted);
+    }
+  }
+}
+function pythonSources(selection) {
+  const decoder = new TextDecoder();
+  return selection.files.filter((file) => file.name.endsWith(".py")).map((file) => ({
+    name: file.name,
+    text: typeof file.contents === "string" ? file.contents : decoder.decode(file.contents)
+  }));
+}
+async function loadPackages(runtime, host, code, siblings) {
+  if (!needsPackages(code, siblings)) {
+    return;
+  }
+  host.status("Loading libraries...");
+  try {
+    await runtime.ensurePackages(code, siblings);
+  } catch (err) {
+    if (!(err instanceof StoppedError)) {
+      host.say(`Could not load libraries (${errorText(err)}). Continuing; imports may fail.`, "note");
+    }
+  }
+}
+async function mount(runtime, host, select) {
+  host.status("Loading files...");
+  try {
+    const selection = await select();
+    await runtime.mountWorkspaceFiles(selection.files, selection.leftOut);
+    for (const note of leftOutNotes(selection.leftOut, "loaded")) {
+      host.say(note, "problem");
+    }
+    return selection;
+  } catch (err) {
+    if (err instanceof StoppedError) {
+      throw err;
+    }
+    host.say(`Could not load files next to this script (${errorText(err)}). open() may fail.`, "note");
+    return null;
+  }
+}
+async function writeBack(runtime, host, fileName, mounted) {
+  try {
+    const changes = await runtime.collectWorkspaceFiles();
+    if (changes.files.length === 0 && changes.deleted.length === 0) {
+      return;
+    }
+    const { written, deleted, leftOut } = await host.writeBack(changes, mounted.loaded);
+    if (written.length > 0) {
+      host.say(`Saved ${written.join(", ")} next to ${fileName}.`, "note");
+    }
+    if (deleted.length > 0) {
+      host.say(`Deleted ${deleted.join(", ")} next to ${fileName}.`, "note");
+    }
+    for (const note of leftOutNotes(leftOut, "saved")) {
+      host.say(note, "problem");
+    }
+  } catch (err) {
+    host.say(`Could not save files next to this script (${errorText(err)}).`, "problem");
+  }
+}
+async function testsToRun(runtime, host, code) {
+  try {
+    if (!await runtime.hasTests(code)) {
+      return false;
+    }
+  } catch (err) {
+    if (!(err instanceof StoppedError)) {
+      host.say(`Could not check for tests (${errorText(err)}). Skipping them.`, "note");
+    }
+    return false;
+  }
+  host.status("Loading pytest...");
+  try {
+    await runtime.ensurePytest();
+    return true;
+  } catch (err) {
+    if (!(err instanceof StoppedError)) {
+      host.say(`Could not load pytest (${errorText(err)}). Skipping tests.`, "note");
+    }
+    return false;
+  }
+}
+function programEvents(host, fileName, level) {
+  return (event) => {
+    if (event.kind === "error") {
+      host.runtimeFinding(findRuntimeFinding(fileName, level, event.error));
+    } else if (event.kind === "testReport") {
+      host.event(explainTestReport(event, fileName, level));
+    } else {
+      host.event(event);
     }
+  };
+}
+function stopped(host, text) {
+  if (!host.stopRequested()) {
+    return false;
   }
-  return selectMountableFiles(candidates);
+  host.say(text, "problem");
+  return true;
+}
+
+// src/cli/bundleStore.ts
+var import_node_crypto = require("node:crypto");
+var fs = __toESM(require("node:fs/promises"));
+var import_node_os = require("node:os");
+var path = __toESM(require("node:path"));
+function cacheDir() {
+  return path.join(cacheRoot(), "examplar");
+}
+function cacheRoot() {
+  const usable = (dir) => dir && path.isAbsolute(dir) ? dir : void 0;
+  const base = usable(process.env.PLL_CACHE_DIR) ?? usable(process.env.XDG_CACHE_HOME) ?? ((0, import_node_os.homedir)() ? path.join((0, import_node_os.homedir)(), ".cache") : (0, import_node_os.tmpdir)());
+  return path.join(base, "pll-python");
+}
+function createFileStore(dir = cacheDir()) {
+  const fileFor = (url) => path.join(dir, (0, import_node_crypto.createHash)("sha256").update(url).digest("hex").slice(0, 32) + ".json");
+  return {
+    async read(url) {
+      try {
+        const raw = await fs.readFile(fileFor(url), "utf8");
+        const entry = JSON.parse(raw);
+        if (entry.url !== void 0 && entry.url !== url) return void 0;
+        return typeof entry.json === "string" ? { json: entry.json, etag: entry.etag } : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    async write(url, entry) {
+      await fs.mkdir(dir, { recursive: true });
+      const body = JSON.stringify({ url, json: entry.json, etag: entry.etag });
+      const target = fileFor(url);
+      const temp = `${target}.${process.pid}.tmp`;
+      await fs.writeFile(temp, body, "utf8");
+      await fs.rename(temp, target);
+    }
+  };
+}
+
+// src/cli/files.ts
+var fs2 = __toESM(require("node:fs/promises"));
+var path2 = __toESM(require("node:path"));
+function siblingFolder(scriptPath) {
+  const folder = path2.dirname(path2.resolve(scriptPath));
+  const at = (name) => path2.join(folder, ...name.split("/"));
+  return {
+    async files() {
+      const out = [];
+      const seen = /* @__PURE__ */ new Set();
+      const walk = async (dir, prefix) => {
+        const real = await fs2.realpath(dir);
+        if (seen.has(real)) return;
+        seen.add(real);
+        for (const name of await fs2.readdir(dir)) {
+          const full = path2.join(dir, name);
+          const stat2 = await fs2.stat(full).catch(() => null);
+          if (stat2 === null) continue;
+          if (stat2.isDirectory()) {
+            if (isWalkedFolder(name)) await walk(full, `${prefix}${name}/`);
+          } else if (stat2.isFile()) {
+            out.push({ name: `${prefix}${name}`, size: stat2.size, mtimeMs: stat2.mtimeMs });
+          }
+        }
+      };
+      await walk(folder, "");
+      return out;
+    },
+    read: (name) => fs2.readFile(at(name)),
+    async stat(name) {
+      const stat2 = await fs2.stat(at(name)).catch(() => null);
+      return stat2 === null ? null : { size: stat2.size, mtimeMs: stat2.mtimeMs };
+    },
+    async write(name, bytes) {
+      await fs2.mkdir(path2.dirname(at(name)), { recursive: true });
+      await fs2.writeFile(at(name), bytes);
+    },
+    remove: (name) => fs2.unlink(at(name))
+  };
 }
-async function writeBackSiblingFiles(scriptPath, files) {
-  const folder = path.dirname(path.resolve(scriptPath));
-  const written = [];
-  for (const file of selectWritebackFiles(files)) {
-    try {
-      if (typeof file.contents !== "string") {
-        continue;
-      }
-      await fs.writeFile(path.join(folder, file.name), file.contents, "utf8");
-      written.push(file.name);
-    } catch {
-    }
-  }
-  return written;
+function collectSiblingFiles(scriptPath) {
+  return readSiblingFiles(siblingFolder(scriptPath));
+}
+function writeBackSiblingFiles(scriptPath, changes, loaded) {
+  return writeSiblingFiles(siblingFolder(scriptPath), changes, loaded);
 }
 
 // src/cli/run.ts
 var EXIT = {
   ok: 0,
-  /** The program raised. */
+  /** The program raised, or Ctrl+C stopped the run. */
   programError: 1,
   /** Level checks found problems, so the file was not run. */
   blocked: 2,
@@ -919,104 +1567,140 @@ var EXIT = {
   usage: 64
 };
 async function runFile(runtime, view, opts) {
-  const fileName = path2.basename(opts.file);
-  let source;
+  const fileName = path3.basename(opts.file);
+  let bytes;
   try {
-    source = await fs2.readFile(opts.file, "utf8");
+    bytes = await fs3.readFile(opts.file);
   } catch (err) {
-    view.problem(`Cannot read ${opts.file}: ${errText(err)}`);
+    view.problem(`pll: ${cannotRead(opts.file, err)}`);
     return EXIT.usage;
   }
-  const level = parseLevel(source);
-  view.note(`${fileName} [${level}]`);
-  if (levelHasStaticChecks(level)) {
-    const blocked = await staticChecks(runtime, view, source, fileName, level);
-    if (blocked) {
-      return EXIT.blocked;
-    }
+  const decoded = decodeSource(bytes, fileName);
+  if ("problem" in decoded) {
+    view.problem(decoded.problem);
+    return EXIT.programError;
   }
-  await ensurePackages(runtime, view, source);
-  try {
-    await runtime.mountWorkspaceFiles(await collectSiblingFiles(opts.file));
-  } catch (err) {
-    view.note(`Could not load files next to this script (${errText(err)}).`);
+  const source = decoded.text;
+  const start = await startPython(runtime, opts.stopRequested ?? (() => false));
+  if (start === "stopped") {
+    view.problem("Stopped before the program started. Nothing was run.");
+    return EXIT.programError;
   }
-  const onEvent = (event) => {
-    if (event.kind === "error") {
-      const finding = findingForErrorEvent(event, source, fileName, level);
-      if (finding) {
-        view.runtimeFinding(finding);
-        return;
-      }
-    }
-    view.handle(event);
+  if (start !== "started") {
+    view.problem(`pll: Python could not start: ${start.problem}`);
+    return EXIT.usage;
+  }
+  const host = {
+    level: (level) => view.note(`${fileName} [${level}]`),
+    staticFindings: (findings) => view.findings(findings),
+    runtimeFinding: (finding) => view.runtimeFinding(finding),
+    event: (event) => view.handle(event),
+    say: (text, kind) => kind === "problem" ? view.problem(text) : view.note(text),
+    status: () => void 0,
+    stopRequested: opts.stopRequested ?? (() => false),
+    siblingFiles: () => collectSiblingFiles(opts.file),
+    writeBack: (changes, loaded) => writeBackSiblingFiles(opts.file, changes, loaded),
+    examplarCard: (card) => view.examplarCard(card)
   };
-  if (opts.runTests) {
-    await maybeRunTests(runtime, view, source, fileName, level, onEvent);
+  const summary = await runFilePlan(runtime, host, {
+    code: source,
+    fileName,
+    sessionKey: opts.file,
+    runTests: opts.runTests,
+    testsOfIncompleteFile: true,
+    bundles: createFileStore()
+  });
+  return exitCodeOf(summary);
+}
+function exitCodeOf(summary) {
+  if (summary.outcome === "blocked") return EXIT.blocked;
+  if (summary.outcome === "stopped" || summary.raised) return EXIT.programError;
+  if (summary.exitCode !== null && processStatus(summary.exitCode) !== 0) {
+    return processStatus(summary.exitCode);
   }
-  await runtime.runFile({ code: source, fileName, sessionKey: opts.file, level }, onEvent);
-  await writeBack(runtime, view, opts.file);
-  if (view.sawError) return EXIT.programError;
-  if (view.testFailures > 0) return EXIT.testsFailed;
+  if (summary.testFailures > 0) return EXIT.testsFailed;
   return EXIT.ok;
 }
-async function staticChecks(runtime, view, source, fileName, level) {
-  let raw;
-  try {
-    raw = await runtime.staticAnalyze({ code: source, fileName, level });
-  } catch (err) {
-    view.note(`Static analysis failed (${errText(err)}); running anyway.`);
-    return false;
-  }
-  const findings = enrichStaticFindings(raw, level, fileName);
-  if (findings.length === 0) {
-    return false;
-  }
-  view.findings(findings);
-  view.problem(`Static analysis found ${findings.length} problem(s). File not run.`);
-  return true;
+function processStatus(code) {
+  if (!Number.isSafeInteger(code)) return EXIT.programError;
+  return (code % 256 + 256) % 256;
 }
-async function ensurePackages(runtime, view, source) {
-  if (!needsPackages(source)) {
-    return;
-  }
+async function startPython(runtime, stopRequested) {
+  let watch;
+  const stop = new Promise((resolve4) => {
+    watch = setInterval(() => stopRequested() && resolve4("stopped"), 50);
+  });
   try {
-    await runtime.ensurePackages(source);
-  } catch (err) {
-    const message = errText(err);
-    if (!/syntaxerror|invalid syntax/i.test(message)) {
-      view.note(`Could not load libraries (${message}). Continuing.`);
-    }
+    return await Promise.race([
+      runtime.initialize().then(
+        () => "started",
+        (err) => ({ problem: errorText(err) })
+      ),
+      stop
+    ]);
+  } finally {
+    clearInterval(watch);
   }
 }
-async function maybeRunTests(runtime, view, source, fileName, level, onEvent) {
+var CODING_RE = /^[ \t\f]*#.*?coding[:=][ \t]*([-\w.]+)/;
+function decodeSource(bytes, fileName) {
   try {
-    if (!await runtime.hasTests(source)) {
-      return;
-    }
-    await runtime.ensurePytest();
-  } catch (err) {
-    view.note(`Could not check for tests (${errText(err)}); skipping them.`);
-    return;
+    return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
   }
-  await runtime.runTests({ code: source, fileName, sessionKey: fileName, level }, onEvent);
-}
-async function writeBack(runtime, view, file) {
-  try {
-    const changed = await runtime.collectWorkspaceFiles();
-    if (changed.length === 0) {
-      return;
-    }
-    const written = await writeBackSiblingFiles(file, changed);
-    if (written.length > 0) {
-      view.note(`Saved ${written.join(", ")} next to ${path2.basename(file)}.`);
+  const head = Array.from(bytes.subarray(0, 400), (b) => String.fromCharCode(b)).join("");
+  const [first = "", second = ""] = head.split(/\r?\n/);
+  const cookie = CODING_RE.exec(first) ?? (/^[ \t\f]*(#.*)?$/.test(first) ? CODING_RE.exec(second) : null);
+  const encoding = cookie?.[1].toLowerCase().replace(/_/g, "-");
+  if (encoding === "latin-1" || encoding === "iso-8859-1" || encoding === "latin1") {
+    return { text: Array.from(bytes, (b) => String.fromCharCode(b)).join("") };
+  }
+  if (encoding !== void 0) {
+    try {
+      return { text: new TextDecoder(encoding, { fatal: true }).decode(bytes) };
+    } catch {
+      const named = cookie?.[1];
+      return { problem: `SyntaxError: ${fileName} says it is in ${named}, but cannot be read as that.` };
     }
-  } catch (err) {
-    view.note(`Could not save files next to this script (${errText(err)}).`);
   }
+  const at = firstInvalidUtf8(bytes);
+  const byte = bytes[at.index].toString(16);
+  return {
+    problem: `SyntaxError: ${fileName} is not saved as UTF-8 (byte 0x${byte} on line ${at.line}). Save it as UTF-8, or declare its encoding on its first line: \`# -*- coding: latin-1 -*-\`.`
+  };
 }
-function errText(err) {
-  return err instanceof Error ? err.message : String(err);
+function firstInvalidUtf8(bytes) {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let low = 0;
+  let high = bytes.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    try {
+      decoder.decode(bytes.subarray(0, mid));
+      low = mid;
+    } catch {
+      high = mid - 1;
+    }
+  }
+  let index = Math.min(low, bytes.length - 1);
+  while (index < bytes.length - 1 && bytes[index] < 128) index++;
+  let line = 1;
+  for (let i = 0; i < index; i++) if (bytes[i] === 10) line++;
+  return { index, line };
+}
+function cannotRead(file, err) {
+  const shown = path3.relative(process.cwd(), file) || file;
+  switch (err.code) {
+    case "ENOENT":
+      return `cannot open ${shown}: there is no such file`;
+    case "EISDIR":
+      return `${shown} is a folder, not a file`;
+    case "EACCES":
+    case "EPERM":
+      return `cannot open ${shown}: permission denied`;
+    default:
+      return `cannot open ${shown}: ${errorText(err)}`;
+  }
 }
 
 // src/cli/examplar.ts
@@ -1043,66 +1727,60 @@ The bytecode is compiled by the Pyodide this package pins, so it always
 matches the interpreter that will run it - which is the reason to build
 bundles with this tool rather than a local python.
 
-  -o FILE           write here instead of stdout
+  -o, --out FILE    write here instead of stdout
   --verify TESTS    check the bundle with your own suite: it must pass on
                     every wheat and fail on every chaff. A chaff no test can
                     catch is a broken chaff, and better found now. Chaffs are
                     only checked once the wheats pass, since a suite that is
                     wrong fails on everything.
 `;
+var EXAMPLAR_USAGE_HINT = "Usage: pll examplar build <dir> [-o bundle.json] [--verify tests.py]. `pll examplar --help` says more.";
+var BUILD_OPTIONS = {
+  out: { type: "string", short: "o", needs: "a file" },
+  verify: { type: "string", needs: "a test file" },
+  help: { type: "boolean", short: "h" }
+};
 function parseExamplarArgs(argv) {
-  const args = { help: false };
+  if (argv[0] === "-h" || argv[0] === "--help") {
+    return { help: true };
+  }
   if (argv[0] !== "build") {
-    args.error = argv.length === 0 ? "examplar needs a subcommand" : `unknown examplar subcommand ${argv[0]}`;
-    if (argv[0] === "-h" || argv[0] === "--help") {
-      args.error = void 0;
-      args.help = true;
-    }
-    return args;
+    return {
+      help: false,
+      error: argv.length === 0 ? "examplar needs a subcommand" : `unknown examplar subcommand ${argv[0]}`
+    };
   }
-  for (let i = 1; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "-h" || arg === "--help") args.help = true;
-    else if (arg === "-o") {
-      args.out = argv[++i];
-      if (args.out === void 0) {
-        args.error = "-o needs a file";
-        return args;
-      }
-    } else if (arg === "--verify") {
-      args.verify = argv[++i];
-      if (args.verify === void 0) {
-        args.error = "--verify needs a test file";
-        return args;
-      }
-    } else if (arg.startsWith("-")) {
-      args.error = `unknown option ${arg}`;
-      return args;
-    } else if (args.dir === void 0) {
-      args.dir = arg;
-    } else {
-      args.error = `unexpected extra argument ${arg}`;
-      return args;
-    }
+  const line = parseCommandLine(argv.slice(1), BUILD_OPTIONS);
+  if ("error" in line) {
+    return { help: false, error: line.error };
   }
-  if (!args.help && args.dir === void 0) {
+  const { values, positionals } = line;
+  const args = {
+    dir: positionals[0],
+    out: values.out,
+    verify: values.verify,
+    help: values.help === true
+  };
+  if (positionals.length > 1) {
+    args.error = `unexpected extra argument ${positionals[1]}`;
+  } else if (!args.help && args.dir === void 0) {
     args.error = "no directory given";
   }
   return args;
 }
 async function readDir(folder) {
   try {
-    return await fs3.readdir(folder, { withFileTypes: true });
+    return await fs4.readdir(folder, { withFileTypes: true });
   } catch {
     throw new Error(`${folder} does not exist. See \`pll examplar --help\`.`);
   }
 }
 async function readWheats(dir) {
-  const folder = path3.join(dir, "wheats");
+  const folder = path4.join(dir, "wheats");
   const out = {};
   for (const entry of await readDir(folder)) {
     if (!entry.isFile() || !entry.name.endsWith(".py")) continue;
-    out[entry.name.slice(0, -3)] = await fs3.readFile(path3.join(folder, entry.name), "utf8");
+    out[entry.name.slice(0, -3)] = await fs4.readFile(path4.join(folder, entry.name), "utf8");
   }
   if (Object.keys(out).length === 0) {
     throw new Error(`${folder} has no .py files in it.`);
@@ -1110,7 +1788,7 @@ async function readWheats(dir) {
   return out;
 }
 async function readChaffs(dir) {
-  const folder = path3.join(dir, "chaffs");
+  const folder = path4.join(dir, "chaffs");
   const out = {};
   const loose = [];
   for (const entry of await readDir(folder)) {
@@ -1119,11 +1797,11 @@ async function readChaffs(dir) {
       continue;
     }
     if (!entry.isDirectory()) continue;
-    const inner = path3.join(folder, entry.name);
+    const inner = path4.join(folder, entry.name);
     const group = {};
-    for (const file of await fs3.readdir(inner, { withFileTypes: true })) {
+    for (const file of await fs4.readdir(inner, { withFileTypes: true })) {
       if (!file.isFile() || !file.name.endsWith(".py")) continue;
-      group[file.name.slice(0, -3)] = await fs3.readFile(path3.join(inner, file.name), "utf8");
+      group[file.name.slice(0, -3)] = await fs4.readFile(path4.join(inner, file.name), "utf8");
     }
     if (Object.keys(group).length > 0) {
       out[entry.name] = group;
@@ -1131,7 +1809,7 @@ async function readChaffs(dir) {
   }
   if (loose.length > 0) {
     throw new Error(
-      `${path3.join(folder, loose[0])} is not inside a function's directory. Chaffs go in \`chaffs/<function>/\`, named after the function they break - move it to \`chaffs/<function>/${loose[0]}\`.`
+      `${path4.join(folder, loose[0])} is not inside a function's directory. Chaffs go in \`chaffs/<function>/\`, named after the function they break - move it to \`chaffs/<function>/${loose[0]}\`.`
     );
   }
   if (Object.keys(out).length === 0) {
@@ -1147,16 +1825,16 @@ async function runExamplar(runtime, view, argv) {
   }
   if (args.error !== void 0) {
     process.stderr.write(`pll: ${args.error}
-
-${EXAMPLAR_USAGE}`);
+${EXAMPLAR_USAGE_HINT}
+`);
     return EXIT.usage;
   }
-  const dir = path3.resolve(args.dir);
+  const dir = path4.resolve(args.dir);
   let sources;
   try {
     sources = { wheats: await readWheats(dir), chaffs: await readChaffs(dir) };
   } catch (err) {
-    view.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
+    view.problem(`pll: ${errorText(err)}`);
     return EXIT.usage;
   }
   const built = await runtime.examplarBuild(JSON.stringify(sources));
@@ -1178,616 +1856,370 @@ ${EXAMPLAR_USAGE}`);
   if (args.out === void 0) {
     process.stdout.write(json + "\n");
   } else {
-    await fs3.writeFile(path3.resolve(args.out), json + "\n", "utf8");
+    await fs4.writeFile(path4.resolve(args.out), json + "\n", "utf8");
     view.note(`wrote ${args.out} (${json.length} bytes)`);
   }
   return EXIT.ok;
-}
-function caught(impl) {
-  return !impl.loaded || Object.values(impl.tests).some((t) => t.outcome !== "pass");
-}
-async function verify(runtime, view, bundle, testsPath) {
-  let testSource;
-  try {
-    testSource = await fs3.readFile(path3.resolve(testsPath), "utf8");
-  } catch (err) {
-    view.problem(`pll: cannot read ${testsPath}: ${err instanceof Error ? err.message : err}`);
-    return EXIT.usage;
-  }
-  try {
-    await runtime.ensurePytest();
-  } catch {
-    view.note("could not load pytest; assertion messages will be terse.");
-  }
-  const result = await runtime.examplarRun(
-    testSource,
-    JSON.stringify(bundle)
-  );
-  if (!result.ok) {
-    view.problem(`pll: ${result.error ?? "the bundle could not be run"}`);
-    return EXIT.usage;
-  }
-  let bad = 0;
-  view.problem(`verifying with ${path3.basename(testsPath)}:`);
-  for (const wheat of result.wheats ?? []) {
-    const failures = Object.entries(wheat.tests).filter(([, t]) => t.outcome !== "pass");
-    if (wheat.loaded && failures.length === 0) {
-      view.note(`  ok    wheat ${wheat.id}: all ${Object.keys(wheat.tests).length} pass`);
-      continue;
-    }
-    bad += 1;
-    view.problem(`  BAD   wheat ${wheat.id}: your own tests do not all pass on it`);
-    if (!wheat.loaded) {
-      view.problem(`          ${wheat.error_type}: ${wheat.error_message}`);
-    }
-    for (const [name, t] of failures) {
-      view.problem(`          ${name}: ${(t.message ?? t.outcome).split("\n")[0]}`);
-    }
-  }
-  for (const chaff of result.chaffs ?? []) {
-    const where = `chaff ${chaff.targets}/${chaff.id}`;
-    if (caught(chaff)) {
-      const by = Object.entries(chaff.tests).filter(([, t]) => t.outcome !== "pass").map(([name]) => name);
-      view.note(`  ok    ${where}: caught by ${by.join(", ")}`);
-      continue;
-    }
-    bad += 1;
-    view.problem(`  BAD   ${where}: no test catches it - it would never count`);
-  }
-  const attributed = Object.values(result.attribution ?? {});
-  for (const name of result.chaffs_skipped ?? []) {
-    if (attributed.some((names) => names.includes(name))) {
-      view.problem(`  ---   ${name} chaffs not checked: its tests have to pass first`);
-      continue;
-    }
-    bad += 1;
-    view.problem(
-      `  BAD   your own suite has no tests for ${name}, so its chaffs are unproven`
-    );
-  }
-  if (bad > 0) {
-    view.problem(`pll: ${bad} problem(s) with this bundle; not written.`);
-    return EXIT.testsFailed;
-  }
-  view.problem("verified.");
-  return EXIT.ok;
-}
-
-// src/cli/runtime.ts
-var path5 = __toESM(require("node:path"));
-
-// src/desktop/pyodideRuntime.ts
-var fs4 = __toESM(require("node:fs"));
-var path4 = __toESM(require("node:path"));
-var import_node_worker_threads = require("node:worker_threads");
-
-// src/common/deliverResult.ts
-function deliverRunResult(result, onEvent, fileName) {
-  if (result.displays) {
-    for (const display of result.displays) {
-      deliverDisplay(display, onEvent, fileName);
-    }
-  }
-  if (result.result_repr !== null && result.result_repr !== void 0) {
-    onEvent({ kind: "result", repr: result.result_repr });
-  }
-  if (!result.ok && result.error_type) {
-    onEvent({
-      kind: "error",
-      errorType: result.error_type,
-      message: result.error_message ?? "",
-      traceback: result.traceback ?? "",
-      lineNumber: result.line_number,
-      column: result.column,
-      fileName
-    });
-  }
-  onEvent({ kind: "done" });
-}
-function deliverDisplay(display, onEvent, fileName) {
-  switch (display.type) {
-    case "stdout":
-      onEvent({ kind: "stdout", text: display.text });
-      break;
-    case "stderr":
-      onEvent({ kind: "stderr", text: display.text });
-      break;
-    case "image":
-      onEvent({
-        kind: "image",
-        svg: display.data,
-        width: display.width,
-        height: display.height,
-        source: fileName
-      });
-      break;
-    case "reactor":
-      onEvent({
-        kind: "reactor",
-        id: display.id,
-        title: display.title,
-        tickRate: display.tick_rate,
-        ticking: display.ticking,
-        wantsKeys: display.wants_keys,
-        wantsMouse: display.wants_mouse,
-        register: display.register,
-        frame: display.frame,
-        index: display.index,
-        length: display.length,
-        atEnd: display.at_end,
-        stopped: display.stopped,
-        valueRepr: display.value_repr
-      });
-      break;
-    case "table":
-      onEvent({
-        kind: "table",
-        columns: display.columns,
-        rows: display.rows,
-        rowCount: display.row_count,
-        shownCount: display.shown_count,
-        truncated: display.truncated,
-        source: fileName
-      });
-      break;
-  }
-}
-function asPlain(value) {
-  if (value instanceof Map) {
-    const obj = {};
-    for (const [k, v] of value.entries()) {
-      obj[String(k)] = asPlain(v);
-    }
-    return obj;
-  }
-  if (Array.isArray(value)) {
-    return value.map(asPlain);
-  }
-  return value;
-}
-function friendlyTypeCheckMessage(message, level) {
-  const marker = message.indexOf("TypeCheckError:");
-  if (marker < 0) {
-    return message;
-  }
-  const detail = message.slice(marker + "TypeCheckError:".length).trim();
-  if (!detail) {
-    return message;
-  }
-  const explanation = explainTypeCheckError(detail, null, level);
-  return [explanation.headline, ...explanation.howToFix.map((line) => `- ${line}`)].join(
-    "\n"
-  );
-}
-function adaptTestCase(raw, level) {
-  const row = asPlain(raw) ?? {};
-  const line = row.line_number;
-  const message = row.message == null ? null : String(row.message);
-  return {
-    name: String(row.name ?? ""),
-    outcome: String(row.outcome ?? "failed"),
-    lineNumber: typeof line === "number" ? line : null,
-    message: message === null ? null : friendlyTypeCheckMessage(message, level),
-    stdout: row.stdout == null ? null : String(row.stdout)
-  };
-}
-function deliverTestResult(result, onEvent, fileName, level) {
-  if (result.internal_error && result.error_type) {
-    onEvent({
-      kind: "error",
-      errorType: result.error_type,
-      message: result.error_message ?? "",
-      traceback: result.traceback ?? "",
-      lineNumber: result.line_number,
-      column: result.column,
-      fileName
-    });
-    onEvent({ kind: "done" });
-    return;
-  }
-  const tests = Array.isArray(result.tests) ? result.tests.map((row) => adaptTestCase(row, level)) : [];
-  onEvent({
-    kind: "testReport",
-    fileName,
-    passed: result.passed ?? 0,
-    failed: result.failed ?? 0,
-    skipped: result.skipped ?? 0,
-    errors: result.errors ?? 0,
-    tests
-  });
-  onEvent({ kind: "done" });
-}
-
-// src/common/interruptBuffer.ts
-var INTERRUPT_SAB_BYTES = 1;
-var INTERRUPT_SIGINT = 2;
-function tryCreateInterruptBuffer() {
-  try {
-    return new SharedArrayBuffer(INTERRUPT_SAB_BYTES);
-  } catch {
-    return null;
-  }
-}
-function signalInterrupt(sab) {
-  Atomics.store(new Uint8Array(sab), 0, INTERRUPT_SIGINT);
-}
-
-// src/common/stdinBuffer.ts
-var STDIN_SAB_BYTES = 64 * 1024;
-var STDIN_STATE_INDEX = 0;
-var STDIN_LENGTH_INDEX = 1;
-var STDIN_PAYLOAD_OFFSET = 8;
-var STDIN_STATE_LINE = 1;
-var STDIN_STATE_EOF = 2;
-function tryCreateStdinBuffer() {
-  try {
-    return new SharedArrayBuffer(STDIN_SAB_BYTES);
-  } catch {
-    return null;
-  }
-}
-function writeStdinLine(sab, line) {
-  const state = new Int32Array(sab);
-  if (line === null) {
-    Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_EOF);
-    Atomics.notify(state, STDIN_STATE_INDEX);
-    return;
-  }
-  const encoded = new TextEncoder().encode(line);
-  const max = sab.byteLength - STDIN_PAYLOAD_OFFSET;
-  const n = Math.min(encoded.length, max);
-  const bytes = new Uint8Array(sab, STDIN_PAYLOAD_OFFSET);
-  bytes.set(encoded.subarray(0, n));
-  Atomics.store(state, STDIN_LENGTH_INDEX, n);
-  Atomics.store(state, STDIN_STATE_INDEX, STDIN_STATE_LINE);
-  Atomics.notify(state, STDIN_STATE_INDEX);
-}
-
-// src/common/workerRuntime.ts
-var WorkerPythonRuntime = class {
-  worker = null;
-  nextId = 1;
-  pending = /* @__PURE__ */ new Map();
-  initPromise = null;
-  stdinBuffer = null;
-  interruptBuffer = null;
-  stdinHandler = null;
-  /** Event sink for the in-flight runFile, so live displays can stream. */
-  live = null;
-  async initialize() {
-    if (!this.initPromise) {
-      this.initPromise = this.doInitialize();
-    }
-    await this.initPromise;
-  }
-  async doInitialize() {
-    const indexUrl = this.resolveIndexUrl();
-    this.worker = this.spawn({
-      onMessage: (msg) => this.handleMessage(msg),
-      onError: (err) => this.rejectAllPending(err)
-    });
-    this.stdinBuffer = tryCreateStdinBuffer();
-    this.interruptBuffer = tryCreateInterruptBuffer();
-    await this.request(
-      {
-        type: "init",
-        indexUrl,
-        ...this.stdinBuffer ? { stdinBuffer: this.stdinBuffer } : {},
-        ...this.interruptBuffer ? { interruptBuffer: this.interruptBuffer } : {}
-      },
-      "ready"
-    );
-  }
-  async runFile(request, onEvent) {
-    await this.initialize();
-    this.live = { onEvent, fileName: request.fileName };
-    try {
-      const { result } = await this.request({ type: "runFile", ...request }, "result");
-      deliverRunResult(result, onEvent, request.fileName);
-    } finally {
-      this.live = null;
-    }
-  }
-  async replEval(request, onEvent) {
-    await this.initialize();
-    const { result } = await this.request({ type: "replEval", ...request }, "result");
-    deliverRunResult(result, onEvent, "<repl>");
-  }
-  async checkReplComplete(code) {
-    await this.initialize();
-    const { result } = await this.request({ type: "checkSyntax", code }, "syntax");
-    return {
-      status: result.status,
-      errorType: result.error_type,
-      message: result.message,
-      lineNumber: result.lineno,
-      offset: result.offset
-    };
-  }
-  async hasTests(code) {
-    await this.initialize();
-    const { result } = await this.request({ type: "hasTests", code }, "hasTests");
-    return result;
-  }
-  async ensurePackages(code) {
-    await this.initialize();
-    await this.request({ type: "loadPackages", code }, "packagesReady");
-  }
-  async ensurePytest() {
-    await this.initialize();
-    await this.request({ type: "loadPytest" }, "pytestReady");
-  }
-  async runTests(request, onEvent) {
-    await this.initialize();
-    const { result } = await this.request(
-      {
-        type: "runTests",
-        code: request.code,
-        fileName: request.fileName,
-        level: request.level
-      },
-      "testResult"
-    );
-    deliverTestResult(result, onEvent, request.fileName, request.level);
-  }
-  async staticAnalyze(request) {
-    await this.initialize();
-    const { result } = await this.request({ type: "staticAnalyze", ...request }, "static");
-    return result ?? [];
-  }
-  async mountWorkspaceFiles(files) {
-    await this.initialize();
-    await this.request({ type: "mountWorkspace", files }, "workspaceReady");
-  }
-  async collectWorkspaceFiles() {
-    await this.initialize();
-    const { files } = await this.request({ type: "collectWorkspace" }, "workspaceFiles");
-    return files;
-  }
-  async examplarBuild(sources) {
-    await this.initialize();
-    const { result } = await this.request({ type: "examplarBuild", sources }, "examplarBuilt");
-    return result;
+}
+function caught(impl) {
+  return Object.values(impl.tests).some((t) => t.outcome !== "pass");
+}
+async function verify(runtime, view, bundle, testsPath) {
+  let testSource;
+  try {
+    testSource = await fs4.readFile(path4.resolve(testsPath), "utf8");
+  } catch (err) {
+    view.problem(`pll: cannot read ${testsPath}: ${errorText(err)}`);
+    return EXIT.usage;
   }
-  async examplarRun(testSource, bundle) {
-    await this.initialize();
-    const { result } = await this.request(
-      { type: "examplarRun", testSource, bundle },
-      "examplarRan"
-    );
-    return result;
+  try {
+    await runtime.ensurePytest();
+  } catch {
+    view.note("could not load pytest; assertion messages will be terse.");
   }
-  async reactorStep(reactorId, event) {
-    await this.initialize();
-    const { result } = await this.request(
-      { type: "reactorStep", reactorId, event },
-      "reactorFrame"
-    );
-    return result;
+  const result = await runtime.examplarRun(
+    testSource,
+    JSON.stringify(bundle),
+    path4.basename(testsPath)
+  );
+  if (!result.ok) {
+    view.problem(`pll: ${result.error ?? "the bundle could not be run"}`);
+    return EXIT.usage;
   }
-  async reactorSeek(reactorId, index) {
-    await this.initialize();
-    const { result } = await this.request(
-      { type: "reactorSeek", reactorId, index },
-      "reactorFrame"
+  let bad = 0;
+  view.problem(`verifying with ${path4.basename(testsPath)}:`);
+  if (result.timedOut) {
+    const { kind, id, targets, test, seconds } = result.timedOut;
+    const where = kind === "wheat" ? `wheat ${id}` : `chaff ${targets}/${id}`;
+    view.problem(
+      test !== null ? `  BAD   ${where}: ${test} ran for more than ${seconds} seconds, which stops every student's check` : `  BAD   ${where}: loading took more than ${seconds} seconds, which stops every student's check`
     );
-    return result;
-  }
-  async reactorDispose(reactorId) {
-    await this.initialize();
-    await this.request({ type: "reactorDispose", reactorId }, "reactorDisposed");
+    view.problem("pll: the bundle has a problem; not written.");
+    return EXIT.testsFailed;
   }
-  interrupt() {
-    if (!this.interruptBuffer) {
-      return false;
+  for (const wheat of result.wheats ?? []) {
+    const failures = Object.entries(wheat.tests).filter(([, t]) => t.outcome !== "pass");
+    if (wheat.loaded && failures.length === 0) {
+      view.note(`  ok    wheat ${wheat.id}: all ${Object.keys(wheat.tests).length} pass`);
+      continue;
     }
-    signalInterrupt(this.interruptBuffer);
-    return true;
-  }
-  setStdinHandler(handler) {
-    this.stdinHandler = handler;
-  }
-  dispose() {
-    this.worker?.terminate();
-    this.worker = null;
-    this.initPromise = null;
-    this.stdinBuffer = null;
-    this.interruptBuffer = null;
-    this.live = null;
-    this.rejectAllPending(new Error("Runtime disposed"));
-  }
-  /** Send `msg` and resolve with the reply, asserting it is of type `expected`. */
-  async request(msg, expected) {
-    const worker = this.worker;
-    if (!worker) {
-      throw new Error("Worker not initialized");
+    bad += 1;
+    view.problem(`  BAD   wheat ${wheat.id}: your own tests do not all pass on it`);
+    if (!wheat.loaded) {
+      view.problem(`          ${wheat.errorType}: ${wheat.errorMessage}`);
     }
-    const id = this.nextId++;
-    const reply = await new Promise((resolve4, reject) => {
-      this.pending.set(id, { resolve: resolve4, reject });
-      worker.post({ id, ...msg });
-    });
-    if (reply.type !== expected) {
-      throw new Error(`Pyodide worker replied "${reply.type}", expected "${expected}"`);
+    for (const [name, t] of failures) {
+      view.problem(`          ${name}: ${(t.message ?? t.outcome).split("\n")[0]}`);
     }
-    return reply;
   }
-  handleMessage(msg) {
-    if (msg.type === "display") {
-      if (this.live) {
-        deliverDisplay(msg.payload, this.live.onEvent, this.live.fileName);
-      }
-      return;
-    }
-    if (msg.type === "stdinRequest") {
-      void this.handleStdinRequest();
-      return;
-    }
-    const pending = this.pending.get(msg.id);
-    if (!pending) {
-      return;
+  for (const chaff of result.chaffs ?? []) {
+    const where = `chaff ${chaff.targets}/${chaff.id}`;
+    if (!chaff.loaded) {
+      bad += 1;
+      view.problem(`  BAD   ${where}: ${chaff.errorMessage}`);
+      continue;
     }
-    this.pending.delete(msg.id);
-    if (msg.type === "error") {
-      pending.reject(new Error(msg.message));
-    } else {
-      pending.resolve(msg);
+    if (caught(chaff)) {
+      const by = Object.entries(chaff.tests).filter(([, t]) => t.outcome !== "pass").map(([name]) => name);
+      view.note(`  ok    ${where}: caught by ${by.join(", ")}`);
+      continue;
     }
+    bad += 1;
+    view.problem(`  BAD   ${where}: no test catches it - it would never count`);
   }
-  rejectAllPending(err) {
-    for (const pending of this.pending.values()) {
-      pending.reject(err);
+  const attributed = Object.values(result.attribution ?? {});
+  for (const name of result.chaffsSkipped ?? []) {
+    if (attributed.some((names) => names.includes(name))) {
+      view.problem(`  ---   ${name} chaffs not checked: its tests have to pass first`);
+      continue;
     }
-    this.pending.clear();
+    bad += 1;
+    view.problem(
+      `  BAD   your own suite has no tests for ${name}, so its chaffs are unproven`
+    );
   }
-  async handleStdinRequest() {
-    let line = null;
-    try {
-      line = this.stdinHandler ? await this.stdinHandler() : null;
-    } catch {
-      line = null;
-    }
-    if (this.stdinBuffer) {
-      writeStdinLine(this.stdinBuffer, line);
-    }
+  if (bad > 0) {
+    view.problem(`pll: ${bad} problem(s) with this bundle; not written.`);
+    return EXIT.testsFailed;
   }
-};
+  view.problem("verified.");
+  return EXIT.ok;
+}
+
+// src/cli/runtime.ts
+var fs6 = __toESM(require("node:fs"));
+var path6 = __toESM(require("node:path"));
 
 // src/desktop/pyodideRuntime.ts
-var DesktopPyodideRuntime = class extends WorkerPythonRuntime {
-  constructor(paths) {
-    super();
-    this.paths = paths;
-  }
-  paths;
-  resolveIndexUrl() {
-    const found = this.paths.indexUrlCandidates.find(
-      (dir) => fs4.existsSync(path4.join(dir, "pyodide.asm.wasm"))
-    );
-    if (!found) {
-      throw new Error(this.paths.missingAssetsHint);
-    }
-    return found;
+var fs5 = __toESM(require("node:fs"));
+var path5 = __toESM(require("node:path"));
+var import_node_worker_threads = require("node:worker_threads");
+
+// src/run/python.ts
+var Python = class extends WorkerConnection {
+  /** Run a file: its output, errors and test report arrive through `onEvent`, then `done`. */
+  async runFile(request, onEvent) {
+    const { code, fileName, sessionKey, level = DEFAULT_LEVEL, withTests = false } = request;
+    const live = { onEvent, fileName };
+    const result = await this.call("_pll_run_file", [code, fileName, sessionKey, level, withTests], live);
+    deliverRunResult(result, onEvent, fileName);
   }
-  spawn(handlers) {
-    const worker = new import_node_worker_threads.Worker(this.paths.workerPath);
-    worker.on("message", (msg) => handlers.onMessage(msg));
-    worker.on(
-      "error",
-      (err) => handlers.onError(err instanceof Error ? err : new Error(String(err)))
-    );
-    return {
-      post: (msg) => worker.postMessage(msg),
-      terminate: () => void worker.terminate()
-    };
+  /** Evaluate a prompt line against its file's session. */
+  async replEval(request, onEvent) {
+    const { code, sessionKey, level = DEFAULT_LEVEL } = request;
+    const result = await this.call("_pll_repl_eval", [code, sessionKey, level]);
+    deliverRunResult(result, onEvent, "<repl>");
+  }
+  /**
+   * Whether `code` is a complete prompt input (`codeop.compile_command`).
+   * `whole` judges several lines submitted at once as one input (`exec`),
+   * not as a shell line.
+   */
+  checkReplComplete(code, whole = false) {
+    return this.call("_pll_repl_check", [code, whole]);
+  }
+  /** True if `code` contains pytest-style `test_*` functions or `Test*` classes. */
+  hasTests(code) {
+    return this.call("_pll_has_tests", [code]);
+  }
+  /**
+   * Load any Pyodide packages the code imports (pandas, numpy, ...) - it or
+   * the student's `.py` files beside it - wherever the import is. A no-op
+   * when nothing imported maps to a known package; needs network the first
+   * time it loads one.
+   */
+  async ensurePackages(code, siblings = []) {
+    const found = await this.call("_pll_package_imports", [
+      code,
+      JSON.stringify(siblings)
+    ]);
+    await this.request("load", found);
+  }
+  /** Load pytest; needs network the first time. */
+  async ensurePytest() {
+    await this.request("load", { modules: ["pytest"], network: false });
+  }
+  /**
+   * The language level's static checks of a file, each finding worded.
+   * None for a level without checks, or a file that does not parse - its
+   * run says the SyntaxError.
+   */
+  staticAnalyze(request) {
+    const { code, level, fileName, sessionKey = null } = request;
+    return this.call("_pll_static_findings", [code, level, fileName, sessionKey]);
+  }
+  /**
+   * Copy the files under the program's folder into Pyodide's work directory
+   * so `open("data/cars.csv")` / `pd.read_csv("cars.csv")` see them.
+   * Replaces any files from a previous mount. `leftOut` are the files a
+   * limit kept back, so reading one says why it is not there.
+   */
+  async mountWorkspaceFiles(files, leftOut = []) {
+    await this.request("mount", { files, leftOut });
+  }
+  /** What Python made, changed and deleted in the work directory since the last mount. */
+  collectWorkspaceFiles() {
+    return this.request("collect", {});
+  }
+  /**
+   * Compile Examplar wheats and chaffs into a bundle. `sources` is the JSON
+   * of `{wheats: {id: source}, chaffs: {id: source}}`. Authoring only; the
+   * bytecode is produced by *this* interpreter so its magic number matches
+   * by construction.
+   */
+  examplarBuild(sources) {
+    return this.call("_pll_examplar_build", [sources]);
+  }
+  /**
+   * Run a student's tests against every implementation in a bundle.
+   * `fileName` is the student's file, whose own errors are told from the
+   * implementation's.
+   */
+  examplarRun(testSource, bundle, fileName) {
+    return this.call("_pll_examplar_run", [testSource, bundle, fileName]);
+  }
+  /**
+   * Apply one event to a running reactor and get the frame it produced.
+   * `event` is the JSON of `{kind, ...}`; see `Reactor.react`. What its
+   * handlers print or show arrives through `output`, as a run's does.
+   */
+  reactorStep(reactorId, event, output) {
+    return this.call("_pll_reactor_step", [reactorId, event], output);
+  }
+  /** Show an earlier or later recorded frame, applying no event. */
+  reactorSeek(reactorId, index) {
+    return this.call("_pll_reactor_seek", [reactorId, index]);
+  }
+  /** Forget a reactor, so its recorded states can be collected. */
+  async reactorDispose(reactorId) {
+    await this.call("_pll_reactor_dispose", [reactorId]);
+  }
+  /** Forget a session and the names its runs defined. */
+  async endSession(sessionKey) {
+    if (!this.started) return;
+    await this.call("_pll_end_session", [sessionKey]);
   }
 };
+function deliverRunResult(result, onEvent, fileName) {
+  for (const display of result.displays) {
+    deliverDisplay(display, onEvent, fileName);
+  }
+  if (result.resultRepr !== null) {
+    onEvent({ kind: "result", repr: result.resultRepr });
+  }
+  if (result.error !== null) {
+    onEvent({ kind: "error", error: result.error, fileName });
+  }
+  if (result.tests !== null) {
+    onEvent({ kind: "testReport", fileName, ...result.tests });
+  }
+  onEvent({
+    kind: "done",
+    ...result.exitCode !== null ? { exitCode: result.exitCode } : {},
+    ...result.stopped ? { stopped: true } : {}
+  });
+}
+
+// src/desktop/pyodideRuntime.ts
+function desktopPython(paths) {
+  return new Python({
+    indexUrl() {
+      const found = paths.indexUrlCandidates.find((dir) => fs5.existsSync(path5.join(dir, "pyodide.asm.wasm")));
+      if (!found) {
+        throw new Error(paths.missingAssetsHint);
+      }
+      return found;
+    },
+    packageCacheDir: paths.packageCacheDir,
+    startTimeoutMs: paths.startTimeoutMs,
+    spawn(handlers) {
+      const worker = new import_node_worker_threads.Worker(paths.workerPath);
+      worker.on("message", (msg) => handlers.onMessage(msg));
+      worker.on("error", (err) => console.error("Pyodide worker failed:", err));
+      worker.on("exit", () => handlers.onExit?.());
+      return {
+        post: (msg) => worker.postMessage(msg),
+        terminate: () => void worker.terminate()
+      };
+    }
+  });
+}
 
 // src/cli/runtime.ts
 function createCliRuntime() {
-  return new DesktopPyodideRuntime({
-    // `pyodide` is external in the bundle, so this resolves at run time
-    // from the installed package rather than being inlined.
-    indexUrlCandidates: [path5.dirname(require.resolve("pyodide"))],
-    workerPath: path5.join(__dirname, "worker.cjs"),
-    missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present."
+  return desktopPython({
+    indexUrlCandidates: pyodideDirectory(),
+    workerPath: path6.join(__dirname, "worker.cjs"),
+    missingAssetsHint: "Could not find Pyodide's assets. Reinstall pll-python so its `pyodide` dependency is present.",
+    // Ample for a first start on a slow machine; an autograder waits no
+    // longer than that for a Pyodide that will never start.
+    startTimeoutMs: 12e4,
+    packageCacheDir: (indexUrl) => writable(indexUrl) ? void 0 : userPackageCache(indexUrl)
   });
 }
+function writable(dir) {
+  try {
+    fs6.accessSync(dir, fs6.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function userPackageCache(indexUrl) {
+  let version = "unknown";
+  try {
+    const manifest = fs6.readFileSync(path6.join(indexUrl, "package.json"), "utf8");
+    version = JSON.parse(manifest).version;
+  } catch {
+  }
+  return path6.join(cacheRoot(), `pyodide-${version}`);
+}
+function pyodideDirectory() {
+  try {
+    return [path6.dirname(require.resolve("pyodide"))];
+  } catch {
+    return [];
+  }
+}
 
 // src/cli/stdin.ts
-var readline = __toESM(require("node:readline"));
-function createLineReader() {
-  let rl = null;
-  let closed = false;
-  const pending = [];
+function createStdinReader() {
+  let started = false;
+  let ended = false;
+  const waiting = [];
   const buffered = [];
-  function ensure() {
-    if (rl) return rl;
-    rl = readline.createInterface({ input: process.stdin, terminal: false });
-    rl.on("line", (line) => {
-      const next = pending.shift();
-      if (next) next(line);
-      else buffered.push(line);
-    });
-    const finish = () => {
-      closed = true;
-      while (pending.length > 0) pending.shift()?.(null);
-    };
-    rl.on("close", finish);
-    process.stdin.on("end", finish);
-    return rl;
+  const onData = (chunk) => {
+    const next = waiting.shift();
+    if (next) next(chunk);
+    else buffered.push(chunk);
+  };
+  const onEnd = () => {
+    ended = true;
+    while (waiting.length > 0) waiting.shift()?.(null);
+  };
+  function start() {
+    if (started) return;
+    started = true;
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onEnd);
   }
   return {
     read() {
-      if (buffered.length > 0) {
-        return Promise.resolve(buffered.shift() ?? null);
+      const chunk = buffered.shift();
+      if (chunk) {
+        return Promise.resolve(chunk);
       }
-      if (closed) {
+      if (ended) {
         return Promise.resolve(null);
       }
-      ensure();
-      return new Promise((resolve4) => pending.push(resolve4));
+      start();
+      return new Promise((resolve4) => waiting.push(resolve4));
     },
     close() {
-      closed = true;
-      rl?.close();
-      rl = null;
+      ended = true;
+      if (started) {
+        process.stdin.off("data", onData);
+        process.stdin.off("end", onEnd);
+        process.stdin.off("error", onEnd);
+        process.stdin.pause();
+      }
     }
   };
 }
 
 // src/cli/view.ts
-var fs5 = __toESM(require("node:fs"));
-var path6 = __toESM(require("node:path"));
-
-// src/common/analyzers/findingLocation.ts
-function findingLocation(finding) {
-  if (finding.lineNumber === null) {
-    return null;
-  }
-  if (finding.fileName === "<repl>" || finding.fileName === "<input>") {
-    return null;
-  }
-  const column = typeof finding.column === "number" && Number.isFinite(finding.column) ? finding.column : null;
-  const label = column !== null ? `${finding.fileName}:${finding.lineNumber}:${column + 1}` : `${finding.fileName}:${finding.lineNumber}`;
-  return {
-    fileName: finding.fileName,
-    line: finding.lineNumber,
-    column,
-    label
-  };
-}
-
-// src/common/errorFormatter.ts
-function formatFriendlyError(finding) {
-  const lines = [];
-  lines.push(`${finding.errorType}: ${finding.headline}`);
-  const location = findingLocation(finding);
-  if (location) {
-    lines.push(`  at ${location.label}`);
-  }
-  if (finding.howToFix.length > 0) {
-    lines.push("");
-    lines.push("How to fix:");
-    for (const item of finding.howToFix) {
-      lines.push(`  - ${item}`);
-    }
-  }
-  return lines;
-}
-
-// src/cli/view.ts
+var fs7 = __toESM(require("node:fs"));
+var path7 = __toESM(require("node:path"));
 var ESC = String.fromCharCode(27);
 var CliView = class {
   constructor(opts) {
     this.opts = opts;
   }
   opts;
-  /** True once the program raised, so the exit code can reflect it. */
-  sawError = false;
-  /** Failing + erroring tests across all reports. */
-  testFailures = 0;
   imageCount = 0;
+  /** Whether the program's last output on each stream left a line unfinished. */
+  midLine = { stdout: false, stderr: false };
+  /** The program's own output, as it wrote it. */
+  program(stream, text) {
+    if (text === "") return;
+    process[stream].write(text);
+    this.midLine[stream] = !text.endsWith("\n");
+  }
+  /**
+   * PLL's own line, on a line of its own: after `print("Total:", end="")`
+   * it would otherwise run on from the program's. Both streams are one
+   * terminal when both are terminals.
+   */
+  say(text) {
+    const oneTerminal = process.stdout.isTTY === true && process.stderr.isTTY === true;
+    if (this.midLine.stderr || oneTerminal && this.midLine.stdout) {
+      process.stderr.write("\n");
+      this.midLine.stderr = false;
+      if (oneTerminal) this.midLine.stdout = false;
+    }
+    process.stderr.write(text + "\n");
+  }
   paint(code, text) {
     return this.opts.color ? `${ESC}[${code}m${text}${ESC}[0m` : text;
   }
@@ -1800,21 +2232,24 @@ var CliView = class {
   green(text) {
     return this.paint("32", text);
   }
+  yellow(text) {
+    return this.paint("33", text);
+  }
   /** PLL's own commentary. Always stderr, silenced by --quiet. */
   note(text) {
     if (!this.opts.quiet) {
-      process.stderr.write(text + "\n");
+      this.say(text);
     }
   }
   /** Something the user must see even under --quiet. */
   problem(text) {
-    process.stderr.write(text + "\n");
+    this.say(text);
   }
   /** Static-analysis findings, in the same words the editor uses. */
   findings(findings) {
     for (const finding of findings) {
       const lines = formatFriendlyError(finding);
-      this.problem(this.red(lines[0]));
+      this.problem(finding.severity === "warning" ? this.yellow(lines[0]) : this.red(lines[0]));
       for (const line of lines.slice(1)) {
         this.problem(line);
       }
@@ -1823,7 +2258,6 @@ var CliView = class {
   }
   /** A friendly finding for a runtime error, in place of the traceback. */
   runtimeFinding(finding) {
-    this.sawError = true;
     const lines = formatFriendlyError(finding);
     this.problem(this.red(lines[0]));
     for (const line of lines.slice(1)) {
@@ -1833,21 +2267,21 @@ var CliView = class {
   handle(event) {
     switch (event.kind) {
       case "stdout":
-        process.stdout.write(event.text);
+        this.program("stdout", event.text);
         break;
       case "stderr":
-        process.stderr.write(event.text);
+        this.program("stderr", event.text);
         break;
       case "result":
         if (event.repr !== null && event.repr !== void 0) {
-          process.stdout.write(event.repr + "\n");
+          this.program("stdout", event.repr + "\n");
         }
         break;
       case "image":
         this.image(event.svg, event.width, event.height);
         break;
       case "table":
-        process.stdout.write(renderTable(event) + "\n");
+        this.program("stdout", renderTable(event) + "\n");
         break;
       case "reactor": {
         const which = event.title === "reactor" ? "reactor" : `reactor "${event.title}"`;
@@ -1859,16 +2293,32 @@ var CliView = class {
       case "testReport":
         this.testReport(event);
         break;
-      case "error": {
-        this.sawError = true;
-        const body = event.traceback || `${event.errorType}: ${event.message}`;
-        process.stderr.write(this.red(body.trimEnd()) + "\n");
+      case "error":
+        this.problem(this.red(`${event.error.errorType}: ${event.error.message}`));
         break;
-      }
       case "done":
         break;
     }
   }
+  /**
+   * One card of the Examplar verdict: the same lines the panel shows, so a
+   * test is named and a buggy implementation is given by its id - nothing
+   * more, in either place. Commentary, so on stderr and silenced by --quiet.
+   */
+  examplarCard(card) {
+    this.note(this.dim("examplar: ") + (card.card === "function" ? card.name : "your tests"));
+    const tone = { good: this.green, bad: this.red, warn: this.yellow, note: this.dim };
+    for (const block of card.body) {
+      if (block.kind === "line") {
+        this.note("  " + tone[block.tone].call(this, block.text));
+        continue;
+      }
+      this.note(`    ${block.name}`);
+      for (const line of (block.detail ?? "").split("\n")) {
+        if (line.trim()) this.note(this.dim(`      ${line}`));
+      }
+    }
+  }
   image(svg, width, height) {
     this.imageCount += 1;
     const dir = this.opts.saveImagesDir;
@@ -1878,33 +2328,53 @@ var CliView = class {
       );
       return;
     }
-    const target = path6.join(dir, `image-${this.imageCount}.svg`);
+    const target = path7.join(dir, `image-${this.imageCount}.svg`);
     try {
-      fs5.mkdirSync(dir, { recursive: true });
-      fs5.writeFileSync(target, svg, "utf8");
+      fs7.mkdirSync(dir, { recursive: true });
+      fs7.writeFileSync(target, svg, "utf8");
       this.note(this.dim(`[image ${width}x${height} -> ${target}]`));
     } catch (err) {
-      this.problem(`Could not write ${target}: ${errText2(err)}`);
+      this.problem(`Could not write ${target}: ${errorText(err)}`);
     }
   }
   testReport(event) {
     const bad = event.failed + event.errors;
-    this.testFailures += bad;
-    const summary = `${event.passed} passed` + (event.failed ? `, ${event.failed} failed` : "") + (event.errors ? `, ${event.errors} errored` : "") + (event.skipped ? `, ${event.skipped} skipped` : "");
-    this.problem((bad === 0 ? this.green("tests: ") : this.red("tests: ")) + summary);
+    const parts = [
+      ...event.passed ? [`${event.passed} passed`] : [],
+      ...event.failed ? [`${event.failed} failed`] : [],
+      ...event.errors ? [`${event.errors} error${event.errors === 1 ? "" : "s"}`] : [],
+      ...event.skipped ? [`${event.skipped} skipped`] : [],
+      ...event.stopped ? [event.stoppedIn ? `stopped during ${event.stoppedIn}` : "stopped before any test ran"] : []
+    ];
+    const summary = parts.length > 0 ? parts.join(", ") : "no tests collected";
+    const label = event.stopped ? this.yellow("Tests: ") : bad === 0 ? this.green("Tests: ") : this.red("Tests: ");
+    this.problem(label + summary);
     for (const test of event.tests) {
+      const printed = (test.stdout ?? "").replace(/\s+$/, "");
+      const where = test.lineNumber === null ? "" : ` (line ${test.lineNumber})`;
       if (test.outcome === "passed") {
         this.note(this.dim(`  ok   ${test.name}`));
+        for (const line of printed ? printed.split("\n") : []) {
+          this.note(this.dim("          " + line));
+        }
+        continue;
+      }
+      if (test.outcome === "skipped") {
+        this.note(this.yellow(`  skip ${test.name}${where}`));
+        if (test.message) this.note(this.dim(`        ${test.message}`));
+        continue;
+      }
+      if (test.outcome === "stopped") {
+        this.problem(this.yellow(`  STOPPED ${test.name}${where}`));
         continue;
       }
-      const where = test.lineNumber === null ? "" : ` (line ${test.lineNumber})`;
       this.problem(this.red(`  ${test.outcome.toUpperCase()} ${test.name}${where}`));
-      for (const line of (test.message ?? "").split("\n")) {
+      const body = test.finding ? findingLines(test.finding) : (test.message ?? "").split("\n");
+      for (const line of body) {
         if (line.trim()) {
           this.problem("        " + line);
         }
       }
-      const printed = (test.stdout ?? "").replace(/\s+$/, "");
       if (printed) {
         this.problem(this.dim("        output:"));
         for (const line of printed.split("\n")) {
@@ -1914,26 +2384,49 @@ var CliView = class {
     }
   }
 };
-function errText2(err) {
-  return err instanceof Error ? err.message : String(err);
+function findingLines(finding) {
+  return [
+    `${finding.errorType}: ${finding.headline}`,
+    ...finding.location ? [`at ${finding.location.label}`] : [],
+    ...finding.howToFix.map((line) => `- ${line}`)
+  ];
 }
 function renderTable(table) {
-  const widths = table.columns.map(
-    (name, i) => Math.max(name.length, ...table.rows.map((row) => (row[i] ?? "").length), 0)
+  const columns = table.columns.map(visible);
+  const rows = table.rows.map((row) => columns.map((_, i) => visible(row[i] ?? "")));
+  const widths = columns.map(
+    (name, i) => Math.max(displayWidth(name), ...rows.map((row) => displayWidth(row[i])), 0)
   );
-  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  const pad = (cell, width) => cell + " ".repeat(Math.max(0, width - displayWidth(cell)));
+  const line = (cells) => cells.map((cell, i) => pad(cell, widths[i])).join("  ").trimEnd();
   const out = [
-    line(table.columns),
+    line(columns),
     widths.map((w) => "-".repeat(w)).join("  ").trimEnd()
   ];
-  for (const row of table.rows) {
-    out.push(line(table.columns.map((_, i) => row[i] ?? "")));
+  for (const row of rows) {
+    out.push(line(row));
   }
   out.push(
     table.truncated ? `(${table.shownCount} of ${table.rowCount} rows)` : `(${table.rowCount} row${table.rowCount === 1 ? "" : "s"})`
   );
   return out.join("\n");
 }
+var ESCAPES = { "	": "\\t", "\n": "\\n", "\r": "\\r" };
+function visible(text) {
+  return text.replace(
+    /[\u0000-\u001f\u007f-\u009f]/g,
+    (c) => ESCAPES[c] ?? `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`
+  );
+}
+var WIDE = /[\u1100-\u115f\u2e80-\u303e\u3041-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]|[\u{1f300}-\u{1faff}\u{20000}-\u{3fffd}]/u;
+function displayWidth(text) {
+  let width = 0;
+  for (const char of text) {
+    if (new RegExp("\\p{Mark}|\\u200d|\\ufe0f", "u").test(char)) continue;
+    width += WIDE.test(char) ? 2 : 1;
+  }
+  return width;
+}
 
 // src/cli/main.ts
 var USAGE = `pll - run Python with PLL's language levels, outside the editor
@@ -1948,96 +2441,138 @@ Subcommands
   examplar build       author an Examplar bundle; see \`pll examplar --help\`
 
 Options
-  --no-tests           do not run the file's \`test_*\` functions first
+  --no-tests           do not run the file's \`test_*\` functions, which
+                       otherwise run once the program finishes
   --save-images <dir>  write pictures there as .svg (they cannot be drawn
                        in a terminal); without this, each one prints a note
-  -q, --quiet          only the program's own output
+  -q, --quiet          only the program's own output and what went wrong:
+                       errors, failed tests, files not loaded or not saved
   --no-color           never use ANSI colour
   -h, --help           this message
-  -v, --version        print the version
+  -V, --version        print the version
 
 The program's own stdout is the only thing on stdout, so it can be piped;
 everything PLL says about the run goes to stderr.
 
 Exit codes
-  0  ran, tests passed        2  level checks blocked it
-  1  the program raised       3  a test failed
+  0    ran, and any tests passed
+  1    the program raised, or was stopped
+  2    level checks found problems, so it was not run
+  3    a test failed
+  64   bad usage, or Python could not start
+  130  a second Ctrl+C gave up waiting for it to stop
+  141  what it printed could no longer be read (\`| head\`)
+  143  it was ended by SIGTERM
+A program that ends with \`sys.exit(n)\` exits with n, as it would under
+\`python\`; \`sys.exit("message")\` prints the message and exits with 1.
 `;
+var USAGE_HINT = "Usage: pll <file.py> [options]. `pll --help` says more.";
+function sayPackageNotes(runtime, view) {
+  let saidDownload = false;
+  runtime.setPackageNoteHandler((text, failed) => {
+    if (failed) {
+      view.problem(text);
+      return;
+    }
+    if (/^Didn't find package \S+ locally/.test(text) && !saidDownload) {
+      saidDownload = true;
+      view.note("Downloading packages: the first time one is used, it needs the network.");
+    }
+  });
+}
 function colorDefault() {
   return process.stderr.isTTY === true && !process.env.NO_COLOR;
 }
-function parseArgs(argv) {
+var OPTIONS = {
+  "no-tests": { type: "boolean" },
+  "save-images": { type: "string", needs: "a directory" },
+  quiet: { type: "boolean", short: "q" },
+  "no-color": { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "V" }
+};
+var LEADING_OPTIONS = {
+  quiet: OPTIONS.quiet,
+  "no-color": OPTIONS["no-color"]
+};
+function parseArgs2(argv) {
+  const line = parseCommandLine(argv, OPTIONS);
+  if ("error" in line) {
+    return {
+      runTests: true,
+      quiet: false,
+      color: colorDefault(),
+      help: false,
+      version: false,
+      error: line.error
+    };
+  }
+  const { values, positionals } = line;
   const args = {
-    runTests: true,
-    quiet: false,
-    color: colorDefault(),
-    help: false,
-    version: false
+    file: positionals[0],
+    runTests: values["no-tests"] !== true,
+    saveImagesDir: values["save-images"],
+    quiet: values.quiet === true,
+    color: colorDefault() && values["no-color"] !== true,
+    help: values.help === true,
+    version: values.version === true
   };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--no-tests") args.runTests = false;
-    else if (arg === "-q" || arg === "--quiet") args.quiet = true;
-    else if (arg === "--no-color") args.color = false;
-    else if (arg === "-h" || arg === "--help") args.help = true;
-    else if (arg === "-v" || arg === "--version") args.version = true;
-    else if (arg === "--save-images") {
-      const dir = argv[++i];
-      if (dir === void 0) {
-        args.error = "--save-images needs a directory";
-        return args;
-      }
-      args.saveImagesDir = dir;
-    } else if (arg.startsWith("-")) {
-      args.error = `unknown option ${arg}`;
-      return args;
-    } else if (args.file === void 0) {
-      args.file = arg;
-    } else {
-      args.error = `unexpected extra argument ${arg}`;
-      return args;
-    }
-  }
-  if (!args.help && !args.version && args.file === void 0) {
+  if (positionals.length > 1) {
+    args.error = `unexpected extra argument ${positionals[1]}`;
+  } else if (!args.help && !args.version && args.file === void 0) {
     args.error = "no file given";
-  }
-  if (args.file !== void 0 && !args.file.endsWith(".py")) {
+  } else if (args.file !== void 0 && !args.file.endsWith(".py")) {
     args.error = `${args.file} is not a .py file`;
+  } else if (args.saveImagesDir !== void 0 && isFile(args.saveImagesDir)) {
+    args.error = `--save-images needs a directory, and ${args.saveImagesDir} is a file`;
   }
   return args;
 }
+function isFile(at) {
+  try {
+    return !fs8.statSync(at).isDirectory();
+  } catch {
+    return false;
+  }
+}
 async function main(argv) {
-  const firstPositional = argv.find((arg) => !arg.startsWith("-"));
-  if (firstPositional === "examplar") {
-    const at = argv.indexOf("examplar");
-    const leading = argv.slice(0, at);
+  const at = subcommandIndex(argv, "examplar", OPTIONS);
+  if (at !== -1) {
+    const leading = parseCommandLine(argv.slice(0, at), LEADING_OPTIONS);
+    if ("error" in leading) {
+      process.stderr.write(`pll: ${leading.error} before examplar
+${USAGE_HINT}
+`);
+      return EXIT.usage;
+    }
     const view2 = new CliView({
-      quiet: leading.includes("-q") || leading.includes("--quiet"),
-      color: colorDefault() && !leading.includes("--no-color")
+      quiet: leading.values.quiet === true,
+      color: colorDefault() && leading.values["no-color"] !== true
     });
     const runtime2 = createCliRuntime();
+    sayPackageNotes(runtime2, view2);
     try {
       return await runExamplar(runtime2, view2, argv.slice(at + 1));
     } catch (err) {
-      view2.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
+      view2.problem(`pll: ${errorText(err)}`);
       return EXIT.usage;
     } finally {
       runtime2.dispose();
     }
   }
-  const args = parseArgs(argv);
+  const args = parseArgs2(argv);
   if (args.help) {
     process.stdout.write(USAGE);
     return EXIT.ok;
   }
   if (args.version) {
-    process.stdout.write("0.2.0\n");
+    process.stdout.write("0.5.0\n");
     return EXIT.ok;
   }
   if (args.error !== void 0) {
     process.stderr.write(`pll: ${args.error}
-
-${USAGE}`);
+${USAGE_HINT}
+`);
     return EXIT.usage;
   }
   const view = new CliView({
@@ -2046,7 +2581,8 @@ ${USAGE}`);
     color: args.color
   });
   const runtime = createCliRuntime();
-  const reader = createLineReader();
+  sayPackageNotes(runtime, view);
+  const reader = createStdinReader();
   runtime.setStdinHandler(() => reader.read());
   let interrupted = false;
   const onSigint = () => {
@@ -2060,14 +2596,23 @@ ${USAGE}`);
     }
   };
   process.on("SIGINT", onSigint);
+  const onBrokenPipe = (err) => {
+    if (err.code === "EPIPE") {
+      runtime.dispose();
+      process.exit(141);
+    }
+  };
+  process.stdout.on("error", onBrokenPipe);
+  process.stderr.on("error", onBrokenPipe);
   try {
     return await runFile(runtime, view, {
-      file: path7.resolve(args.file),
-      runTests: args.runTests
+      file: path8.resolve(args.file),
+      runTests: args.runTests,
+      stopRequested: () => interrupted
     });
   } catch (err) {
-    view.problem(`pll: ${err instanceof Error ? err.message : String(err)}`);
-    return EXIT.usage;
+    view.problem(`pll: ${errorText(err)}`);
+    return err instanceof PythonLostError ? EXIT.programError : EXIT.usage;
   } finally {
     process.off("SIGINT", onSigint);
     reader.close();
@@ -2084,4 +2629,3 @@ main(process.argv.slice(2)).then(
     process.exit(EXIT.usage);
   }
 );
-//# sourceMappingURL=cli.cjs.map