mercury-agent 0.18.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.18.2",
+  "version": "0.20.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -24,6 +24,10 @@
       "types": "./src/core/global-admin.ts",
       "default": "./src/core/global-admin.ts"
     },
+    "./core/media": {
+      "types": "./src/core/media.ts",
+      "default": "./src/core/media.ts"
+    },
     "./core/model-leg": {
       "types": "./src/core/model-leg.ts",
       "default": "./src/core/model-leg.ts"
@@ -80,14 +84,15 @@
     "typecheck": "bunx tsc --noEmit",
     "typecheck:scripts": "bunx tsc --noEmit -p tsconfig.scripts.json",
     "typecheck:examples": "bunx tsc --noEmit -p tsconfig.examples.json",
-    "lint": "bunx biome check src/ tests/ scripts/space-profile.ts scripts/football-harness.ts scripts/football-audit.ts scripts/ops-preflight.ts examples/extensions/archive/ examples/extensions/feed-watch/ examples/extensions/napkin/ examples/extensions/pinchtab/ examples/extensions/overview/ examples/extensions/longview/ examples/extensions/yahoo-mail/ examples/extensions/morning/",
-    "lint:fix": "bunx biome check --fix src/ tests/ scripts/space-profile.ts scripts/football-harness.ts scripts/football-audit.ts scripts/ops-preflight.ts examples/extensions/archive/ examples/extensions/feed-watch/ examples/extensions/napkin/ examples/extensions/pinchtab/ examples/extensions/overview/ examples/extensions/longview/ examples/extensions/yahoo-mail/ examples/extensions/morning/",
+    "lint": "bunx biome check src/ tests/ scripts/space-profile.ts scripts/football-harness.ts scripts/football-audit.ts scripts/ops-preflight.ts scripts/archive-erase-space.ts scripts/check-image-sources.ts scripts/check-sync-calls.ts examples/extensions/archive/ examples/extensions/feed-watch/ examples/extensions/gws/ examples/extensions/napkin/ examples/extensions/pinchtab/ examples/extensions/overview/ examples/extensions/longview/ examples/extensions/yahoo-mail/ examples/extensions/morning/",
+    "lint:fix": "bunx biome check --fix src/ tests/ scripts/space-profile.ts scripts/football-harness.ts scripts/football-audit.ts scripts/ops-preflight.ts scripts/archive-erase-space.ts scripts/check-image-sources.ts scripts/check-sync-calls.ts examples/extensions/archive/ examples/extensions/feed-watch/ examples/extensions/gws/ examples/extensions/napkin/ examples/extensions/pinchtab/ examples/extensions/overview/ examples/extensions/longview/ examples/extensions/yahoo-mail/ examples/extensions/morning/",
     "check:silent-catch": "bun run scripts/check-silent-catch.ts",
     "check:sync-calls": "bun run scripts/check-sync-calls.ts",
     "check:dep-floors": "bun run scripts/check-dep-floors.ts",
+    "check:image-sources": "bun run scripts/check-image-sources.ts",
     "check:no-hijack-verbs": "bun run scripts/check-no-hijack-verbs.ts src",
-    "check": "bun run check:silent-catch && bun run check:sync-calls && bun run check:dep-floors && bun run check:no-hijack-verbs && bun run typecheck && bun run typecheck:scripts && bun run typecheck:examples && bun run lint && bun test",
-    "check:fix": "bun run check:silent-catch && bun run check:sync-calls && bun run check:dep-floors && bun run check:no-hijack-verbs && bun run typecheck && bun run typecheck:scripts && bun run typecheck:examples && bun run lint:fix && bun test",
+    "check": "bun run check:silent-catch && bun run check:sync-calls && bun run check:dep-floors && bun run check:image-sources && bun run check:no-hijack-verbs && bun run typecheck && bun run typecheck:scripts && bun run typecheck:examples && bun run lint && bun test",
+    "check:fix": "bun run check:silent-catch && bun run check:sync-calls && bun run check:dep-floors && bun run check:image-sources && bun run check:no-hijack-verbs && bun run typecheck && bun run typecheck:scripts && bun run typecheck:examples && bun run lint:fix && bun test",
     "smoke:image": "bun run scripts/smoke-image.ts"
   },
   "dependencies": {
@@ -110,7 +115,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
+    "@biomejs/biome": "2.5.2",
     "@types/nodemailer": "^7.0.4",
     "@types/node": "^26.1.2",
     "imapflow": "^1.0.171",

package/resources/skills/tasks/SKILL.md

@@ -7,11 +7,12 @@ description: Manage scheduled tasks — create cron jobs or one-shot reminders t
 
 ```bash
 mrctl tasks list
-mrctl tasks create --cron "<expr>" --prompt "<text>" [--timezone "<IANA>"] [--silent]
+mrctl tasks create --cron "<expr>" --prompt "<text>" [--timezone "<IANA>"] [--silent] [--catch-up skip|once]
 mrctl tasks create --at "<ISO8601>" --prompt "<text>" [--silent]
 mrctl tasks pause <id>
 mrctl tasks resume <id>
 mrctl tasks run <id>
+mrctl tasks catch-up <id> skip|once
 mrctl tasks delete <id>
 ```
 
@@ -43,6 +44,21 @@ If you cannot determine the timezone, ask the user before creating the task. Nev
 
 - `--timezone "<IANA>"` — IANA timezone for cron evaluation (e.g. `"Asia/Jerusalem"`, `"America/New_York"`). Falls back to the agent's configured default timezone, then UTC.
 - `--silent` — task runs but output is not sent to chat (useful for background work)
+- `--catch-up skip|once` — what to do with occurrences missed while the host was
+  down. Cron tasks only; `skip` is the default.
+
+## Missed runs
+
+If the host is down when a task was due, the occurrence is **not** run late by
+default — it is logged and reported to whoever created the task, and the task
+resumes at its next scheduled time.
+
+Pass `--catch-up once` (or `mrctl tasks catch-up <id> once` on an existing task)
+when a late run is better than no run — a daily summary or article, say. The
+task then runs **one** make-up run at startup, however many occurrences were
+missed, and only if the most recent of them is within the configured window
+(12 hours by default). Leave it at `skip` for anything whose output only makes
+sense at its scheduled hour, such as a "leave for work now" reminder.
 
 ## Tasks that are usually quiet
 

package/resources/templates/AGENTS.md

@@ -55,11 +55,12 @@ mrctl config set <key> <value>  # Set config value
 
 ### Models
 ```bash
-mrctl model list                # List configured models (active one marked)
-mrctl model switch <N|MODEL_ID> # Switch active model — takes effect on the NEXT agent run
+mrctl model list                # List configured models; says whether this space is pinned
+mrctl model switch <N|MODEL_ID> # Pin this space to one leg — takes effect on the NEXT agent run
+mrctl model reset               # Clear the pin and restore the fallback chain
 ```
 
-**Note:** A switch never changes the run you are in — say so when reporting it. Switching requires the `model.switch` permission (admin by default); a 403 means the caller must ask an admin.
+**Note:** A switch never changes the run you are in — say so when reporting it. A switch **pins** the space: that leg is the only one that runs, so the other legs are switch targets, not fallbacks. `mrctl model reset` clears the pin, and is refused while the space has an active scheduled task (pause it first). Both switch and reset require the `model.switch` permission (admin by default); a 403 means the caller must ask an admin.
 
 ### Spaces
 ```bash

package/resources/templates/mercury.example.yaml

@@ -71,10 +71,19 @@
 #   # containers do not start on macOS/Windows. Ignored when
 #   # container_bwrap_docker_compat is set or the runtime is runsc.
 #   allow_unconfined: false
-#   # Which MERCURY_* vars reach containers. "all" (default) passes every
-#   # non-blocked var into every space's container; "claimed" passes only
-#   # extension-declared vars, gated by the caller's permission.
-#   env_passthrough: all
+#   # Which MERCURY_* vars reach containers. "claimed" (default) passes only
+#   # extension-declared vars, gated by the caller's permission, plus the fixed
+#   # model-provider credentials. "all" is the escape hatch: it passes every
+#   # non-blocked var into every space's container, scoped to nothing.
+#   env_passthrough: claimed
+#   # Who authors pi's system prompt. true (default) replaces it wholesale with
+#   # Mercury's own (--system-prompt); false keeps pi's coding-agent preamble
+#   # and appends Mercury's content. Leave this at true on a Claude
+#   # subscription: Anthropic's OAuth gate rejects pi's preamble as a
+#   # third-party app with a 400 that reads like a billing error. Parsed
+#   # strictly: only false/0 opt out, a blank MERCURY_OVERRIDE_PI_SYSTEM_PROMPT
+#   # is read as unset, and any other value is a startup error.
+#   override_pi_system_prompt: true
 
 # discord:
 #   gateway_duration_ms: 600000

package/src/adapters/whatsapp-ingress.ts

@@ -106,11 +106,23 @@ export function getContextInfo(
 
 /**
  * These attribute values are user-controlled — a push name is whatever the
- * sender typed — and the block is handed to the model as markup. A stray
- * double quote would close the attribute and let a sender inject their own.
+ * sender typed — and the block is handed to the model as markup.
+ *
+ * A stray double quote would close the attribute and let a sender inject their
+ * own. A stray `>` is worse: it closes the whole opening tag, so every
+ * attribute after it — `media_type` included, and `name` is emitted first —
+ * reads as quoted body. `replyToBlockHasMedia` (`core/reply-context.ts`) scans
+ * the opening tag for `media_type=`, so a `>` in a push name would answer
+ * `false` and hand a media quote back to the de-duplication that
+ * `docs/debug/moderate/2026-09-06-swipe-reply-dedupe-drops-quoted-media-signal.md`
+ * exists to stop. `&` goes first so an escape written here is not re-escaped.
  */
 function escapeAttr(value: string): string {
-  return value.replace(/"/g, """);
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
 }
 
 export function buildReplyContext(

package/src/agent/container-entry.ts

@@ -39,6 +39,53 @@ function logTiming(
 /** Trace filename inside IO_DIR. The host harvests this before reaping the container. */
 export const RUN_TRACE_FILE = "trace.jsonl";
 
+/**
+ * Append one diagnostic event to the run trace, regardless of `TRACE_RUNS`.
+ *
+ * `logTiming` writes to the container's stderr, and nothing on the host reads
+ * it: the container runs detached with `--rm` and no host code parses those
+ * lines. So a `logTiming`-only event is a reader that cannot be read — the
+ * failure this exists to close (`docs/debug/minor/…-history-budget-backstop-logs-where-nobody-reads.md`).
+ *
+ * Unlike `createRunTracer`, this is **not** gated on `TRACE_RUNS`: a full trace
+ * is opt-in because it carries the conversation verbatim, while an event
+ * written here must survive a run nobody thought to trace in advance. The host
+ * harvests `trace.jsonl` unconditionally for that reason
+ * (`harvestRunTrace`, `container-runner.ts`).
+ *
+ * **Callers pass counts and identifiers only — never message content.** That is
+ * the rule the un-gated harvest rests on: anything written here escapes the
+ * opt-in that keeps the conversation off the host's disk, and lands in
+ * `dataDir/traces/` on a deployment that deliberately turned tracing off.
+ *
+ * Returns whether the line was written; a failure is swallowed, because losing
+ * a diagnostic must never cost the turn.
+ */
+export function traceEvent(
+  event: string,
+  data: Record<string, number | string | null>,
+): boolean {
+  const ioDir = process.env.IO_DIR;
+  if (!ioDir) return false;
+  try {
+    appendFileSync(
+      path.join(ioDir, RUN_TRACE_FILE),
+      // `atEpochMs`, not the tracer's `atMs`: these events are emitted while
+      // the prompt is still being assembled, before pi is spawned, so there is
+      // no spawn to be relative to. `stream: "meta"` keeps the stdout
+      // reconstruction (concatenate `stream: "stdout"`) unaffected.
+      `${JSON.stringify({
+        atEpochMs: Date.now(),
+        stream: "meta",
+        data: JSON.stringify({ event, ...data }),
+      })}\n`,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 type TraceStream = "stdout" | "stderr" | "meta";
 type RunTracer = (stream: TraceStream, data: string) => void;
 
@@ -419,12 +466,19 @@ Wrap the message you want delivered between a \`[reply]\` line and a \`[/reply]\
 
 Everything a space's standard says about the message — language, length, format, the exact word to send when there is nothing to say — applies to the text inside the markers. Files still go to \`outbox/\`; the markers cover text only.`;
 
-  const characterChangeFlow = `## Character
+  // The reader instruction for the `## Bot Character` block, which runtime.ts
+  // injects on persona-exclusivity, not on permissions — a member in a default
+  // space gets the owner's voice and so needs the sentence that governs it.
+  // Ungated: it states a fact and a refusal, and carries no procedure.
+  const characterStanding = `## Character
 
 The system prompt may include a "Bot Character" section — the owner-defined voice for
-all conversations. Always follow it.
+all conversations. Always follow it. Only the bot owner (a global admin configured on the
+host) can change it, and the API enforces that. Unless a procedure for changing it appears
+below, treat a request to change your personality, tone, greeting style, or character as
+one you cannot carry out: say in one line that the owner sets it, and change nothing.`;
 
-When a user asks you to change your personality, tone, greeting style, or character:
+  const characterChangeFlow = `When a user asks you to change your personality, tone, greeting style, or character:
 1. Read the current character: \`mrctl character get\`
 2. Draft the FULL updated character text — merge their request with the existing
    character into one coherent text. Do not append contradictory fragments.
@@ -434,9 +488,6 @@ When a user asks you to change your personality, tone, greeting style, or charac
 5. Relay the result. If the API returns 403, tell the user that only the bot owner
    can change the global character.
 
-Only global admins (configured on the host) can change the character — the API
-enforces this.
-
 Per-space adjustments are **preferences**, not the character. They arrive in your
 prompt as a \`<preferences>\` block of key/value pairs scoped to this space, and you
 manage them with:
@@ -495,11 +546,14 @@ Your prompt carries a \`<run_budget>\` block with the exact kill time, the total
   parts.push(destructiveOps);
   parts.push(toolResultPresentation);
   parts.push(delivery);
+  parts.push(characterStanding);
   // The character / preference flow is a set of `mrctl prefs set` and
   // `mrctl character set` instructions. A caller without `prefs.set` cannot
-  // follow them, and the paragraph's "a standing instruction → set a
-  // preference" is exactly how a member's joke got escalated to "the admin
-  // must approve". Left out for that caller; the security text above stays.
+  // follow them — `GET /api/character` is global-admin-only, so even
+  // `mrctl character get` would 403 — and the paragraph's "a standing
+  // instruction → set a preference" is exactly how a member's joke got
+  // escalated to "the admin must approve". Left out for that caller; the
+  // standing instruction above and the security text stay.
   if (callerMay("prefs.set")) {
     parts.push(characterChangeFlow);
   }
@@ -515,11 +569,13 @@ Your prompt carries a \`<run_budget>\` block with the exact kill time, the total
 /**
  * Builds the system prompt passed to pi.
  *
- * - overridePiPrompt=false (default): returns Mercury additions only; pi's own default prompt
- *   comes first via --append-system-prompt.
- * - overridePiPrompt=true: returns a full standalone prompt (pi's default is replaced via
- *   --system-prompt). Includes tool snippets, guidelines, and Mercury platform content without
+ * - overridePiPrompt=true (default): returns a full standalone prompt (pi's default is replaced
+ *   via --system-prompt). Includes tool snippets, guidelines, and Mercury platform content without
  *   any pi-specific identity.
+ * - overridePiPrompt=false: returns Mercury additions only; pi's own default prompt comes first
+ *   via --append-system-prompt. Under an Anthropic OAuth credential that preamble is rejected
+ *   with 400 "Third-party apps now draw from your extra usage" — see the JSDoc on
+ *   `overridePiSystemPrompt` in `src/config.ts`.
  */
 function buildSystemPrompt(
   caps: ModelCapabilities,
@@ -622,8 +678,9 @@ function buildEpisodicMemory(spaceWorkspace: string): string | null {
   }
 }
 
-const EPISODE_TOKEN_BUDGET = 800;
-const APPROX_CHARS_PER_TOKEN = 4;
+/** Exported so a test asserts the budget the code uses, not a copy of it. */
+export const EPISODE_TOKEN_BUDGET = 800;
+export const APPROX_CHARS_PER_TOKEN = 4;
 
 interface EpisodeMeta {
   title: string;
@@ -765,6 +822,163 @@ export function buildMemberNotesXml(spaceWorkspace: string): string | null {
   return `<member_notes>\n${entries.join("\n")}\n</member_notes>`;
 }
 
+/**
+ * The Hebrew prefix letters that attach to the word they govern: ו (and),
+ * ה (the), ב (in), ל (to), מ (from), ש (that), כ (as). Up to three stack —
+ * `וכשיונייטד` is "and when United" — and the tokenizer below cannot see
+ * them, because nothing separates them from the word.
+ */
+const HEBREW_PREFIX_RE = /^[ובהלמשכ]{1,3}/;
+
+/**
+ * A stripped token must leave at least this many characters, or the strip is
+ * not taken. Three-letter Hebrew words are where the false positives live:
+ * the football profile keys Beitar on `בית`, and without this floor `בבית` /
+ * `הבית` / `לבית` — "at home", "the house" — would all select that note.
+ */
+const EPISODE_MIN_STEM_CHARS = 4;
+
+/**
+ * Mem needs one letter more than the rest. ו ה ב ל ש כ are almost always
+ * clitics, but `מ` is also how Hebrew builds whole words (מגרש, משחק,
+ * משוער), so a four-letter stem behind a leading mem is as likely to be an
+ * accident as a mention: `משוער` ("projected") strips to `שוער`
+ * ("goalkeeper"), a keyword a football note would plausibly carry, and the
+ * phrase `הרכב משוער` is the single most common request in this profile.
+ * `מהיונייטד` and `מברצלונה` are unaffected — their stems are long.
+ *
+ * The accepted cost: a mem before a *four-letter* keyword no longer strips,
+ * so `מחיפה` ("from Haifa") does not select the Haifa note while `חיפה` and
+ * `בחיפה` still do. Pinned by a test, so it reads as a choice rather than a
+ * regression to be helpfully undone.
+ */
+const EPISODE_MIN_STEM_CHARS_AFTER_MEM = 5;
+
+/**
+ * The geresh and gershayim Hebrew writes *inside* a word — `לבית"ר`, `ת"א`,
+ * `מנצ'סטר` — in the ASCII forms a phone keyboard emits and the Unicode ones
+ * (U+05F3, U+05F4). Dropped when they sit between two Hebrew letters, so the
+ * word stays one token and its prefix can be stripped; a quote anywhere else
+ * still splits the message, as it always did. The lookahead (rather than a
+ * second capture) is what makes a chain of them collapse in one pass.
+ *
+ * Escapes, not literals: U+05F3/U+05F4 render as `'`/`"` in most editors, so
+ * a literal here is indistinguishable from the ASCII pair beside it.
+ */
+const HEBREW_INWORD_QUOTE_RE =
+  /([\u05D0-\u05EA])['"\u05F3\u05F4]+(?=[\u05D0-\u05EA])/g;
+
+/**
+ * The words an episode keyword is looked up in: every token of the message,
+ * plus every prefix-stripped form of a token that opens with Hebrew prefix
+ * letters. `ליונייטד` contributes `ליונייטד`, `יונייטד`; `מהיונייטד`
+ * contributes those and `היונייטד` as well.
+ *
+ * Expanding the message side rather than the keyword side keeps the lookup an
+ * exact set membership and keeps the score untouched: a keyword still counts
+ * once, whichever form of it the message used. Listing the prefixed forms as
+ * extra keywords would instead *lower* the note's score, since `scoreEpisode`
+ * divides by the keyword count. Latin words never open with these letters, so
+ * English keywords see the exact match they always had.
+ *
+ * Two shapes reach the splitter first. An in-word geresh/gershayim is dropped
+ * (`לבית"ר` → `לביתר`), because splitting there left the 3-letter fragment
+ * `בית` that the stem floor is designed to reject. A hyphen or maqaf *is* a
+ * split point (`ל-united` → `ל` + `united`), because the anchored prefix
+ * regex cannot see past one.
+ */
+function episodeMessageWords(userPrompt: string): Set<string> {
+  const words = new Set<string>();
+  for (const token of userPrompt
+    .toLowerCase()
+    .replace(HEBREW_INWORD_QUOTE_RE, "$1")
+    .split(/[-\s,.!?;:'"()[\]{}<>\u05BE\u05F3\u05F4]+/)) {
+    if (token.length <= 1) continue;
+    words.add(token);
+    const prefix = token.match(HEBREW_PREFIX_RE)?.[0] ?? "";
+    for (let n = 1; n <= prefix.length; n++) {
+      const stem = token.slice(n);
+      // Per strip, not per token: the ambiguity belongs to the letter that
+      // sits immediately before the stem, so `ומשוער` ("and projected") must
+      // meet the mem floor at n=2 exactly as `משוער` does at n=1.
+      const minStem =
+        token[n - 1] === "מ"
+          ? EPISODE_MIN_STEM_CHARS_AFTER_MEM
+          : EPISODE_MIN_STEM_CHARS;
+      // `break`, not `continue`: stems only shrink, so nothing after a
+      // failure can clear a floor this one missed.
+      if (stem.length < minStem) break;
+      words.add(stem);
+    }
+  }
+  return words;
+}
+
+/** One `<episode>` element: the note's identity, then whatever body it is given. */
+function renderEpisodeEntry(ep: EpisodeMeta, body: string): string {
+  return `  <episode title="${escapeXmlAttr(ep.title)}" status="${ep.status}" last_mentioned="${ep.lastMentioned}">\n${escapeXmlText(body)}\n  </episode>`;
+}
+
+/**
+ * The body of a cut note: the summary, the leading `keep` lines of
+ * `## Current State`, and — when anything was left out — a marker naming the
+ * file, so the model can open the note for the rest.
+ *
+ * The marker is the whole point. `AGENTS.md` already tells the reporter to
+ * open the topic note when it did not arrive inside the message, but a note
+ * that arrives *silently truncated* looks complete: a cap the reader cannot
+ * see is a trap, not a cap.
+ */
+function cutEpisodeBody(
+  ep: EpisodeMeta,
+  stateLines: string[],
+  keep: number,
+  file: string,
+): string {
+  const parts = [ep.summary];
+  if (keep > 0) parts.push(stateLines.slice(0, keep).join("\n"));
+  const dropped = stateLines.length - keep;
+  if (dropped > 0)
+    parts.push(
+      `[cut: ${dropped} more lines in knowledge/episodes/${file} — read the file for the rest]`,
+    );
+  return parts.join("\n");
+}
+
+/**
+ * A single note that alone exceeds the per-turn budget, cut to the leading
+ * whole lines of its `## Current State` that fit.
+ *
+ * Leading lines and not a character slice: the distiller writes one fact per
+ * line with its source and date, and half a fact — a line without its
+ * `(source, date)` tail — is worse than no fact.
+ *
+ * The marker's length depends on the number dropped, so each candidate is
+ * measured whole rather than budgeted for in advance. When even the summary
+ * plus the marker overflows (a pathological one-line summary), that smallest
+ * form is returned anyway — there is nothing smaller to fall back to, and the
+ * caller's own guard still bounds every note after the first.
+ */
+function cutEpisodeEntry(
+  ep: EpisodeMeta,
+  file: string,
+  maxChars: number,
+): { entry: string; dropped: number } {
+  const stateLines = ep.currentState ? ep.currentState.split("\n") : [];
+  let best = renderEpisodeEntry(ep, cutEpisodeBody(ep, stateLines, 0, file));
+  let kept = 0;
+  for (let keep = 1; keep <= stateLines.length; keep++) {
+    const candidate = renderEpisodeEntry(
+      ep,
+      cutEpisodeBody(ep, stateLines, keep, file),
+    );
+    if (candidate.length > maxChars) break;
+    best = candidate;
+    kept = keep;
+  }
+  return { entry: best, dropped: stateLines.length - kept };
+}
+
 function buildEpisodeContext(
   spaceWorkspace: string,
   userPrompt: string,
@@ -780,21 +994,16 @@ function buildEpisodeContext(
   }
   if (files.length === 0) return null;
 
-  const messageWords = new Set(
-    userPrompt
-      .toLowerCase()
-      .split(/[\s,.!?;:'"()[\]{}<>]+/)
-      .filter((w) => w.length > 1),
-  );
+  const messageWords = episodeMessageWords(userPrompt);
 
-  const scored: Array<{ ep: EpisodeMeta; score: number }> = [];
+  const scored: Array<{ ep: EpisodeMeta; file: string; score: number }> = [];
   for (const file of files) {
     try {
       const content = readFileSync(path.join(episodesDir, file), "utf8");
       const ep = parseEpisodeFrontmatter(content);
       if (!ep) continue;
       const score = scoreEpisode(ep, messageWords);
-      if (score > 0) scored.push({ ep, score });
+      if (score > 0) scored.push({ ep, file, score });
     } catch {
       // skip malformed episode files
     }
@@ -804,15 +1013,39 @@ function buildEpisodeContext(
 
   scored.sort((a, b) => b.score - a.score);
 
+  // 3,200 UTF-16 units, not tokens: ≈800 English tokens, ≈1,100–1,300 Hebrew
+  // ones, which is the side this profile is written for.
   const maxChars = EPISODE_TOKEN_BUDGET * APPROX_CHARS_PER_TOKEN;
   const entries: string[] = [];
   let totalChars = 0;
 
-  for (const { ep } of scored) {
+  for (const { ep, file } of scored) {
     const body = ep.currentState
       ? `${ep.summary}\n${ep.currentState}`
       : ep.summary;
-    const entry = `  <episode title="${escapeXmlAttr(ep.title)}" status="${ep.status}" last_mentioned="${ep.lastMentioned}">\n${escapeXmlText(body)}\n  </episode>`;
+    let entry = renderEpisodeEntry(ep, body);
+    if (entry.length > maxChars) {
+      // One note bigger than the whole budget. The loop below only bounds the
+      // *number* of episodes and exempts the first, so before this cut an
+      // oversized note passed whole and unmarked — 11 KB of Barcelona in a
+      // 3,200-char budget.
+      const cut = cutEpisodeEntry(ep, file, maxChars);
+      entry = cut.entry;
+      if (cut.dropped > 0)
+        logTiming("episode_cut", {
+          file,
+          dropped: cut.dropped,
+          kept_chars: entry.length,
+        });
+      // Nothing to drop and still over: a note whose one-line summary alone
+      // busts the budget. Say that, rather than claim a cut that did not
+      // happen.
+      else if (entry.length > maxChars)
+        logTiming("episode_over_budget_uncuttable", {
+          file,
+          chars: entry.length,
+        });
+    }
     if (totalChars + entry.length > maxChars && entries.length > 0) break;
     entries.push(entry);
     totalChars += entry.length;
@@ -888,8 +1121,29 @@ export function buildHistoryXml(messages: StoredMessage[]): string | null {
       : "";
     const entry = `  <turn timestamp="${ts}">\n${userLine}${assistantLine}\n  </turn>`;
 
-    if (usedChars + entry.length > HISTORY_CHAR_BUDGET && entries.length > 0)
+    if (usedChars + entry.length > HISTORY_CHAR_BUDGET && entries.length > 0) {
+      // Backstop, not the primary lever: the host clips each message to
+      // `context.history_max_chars` before the window ever gets here. At the
+      // default window of 10 turns that is 10 x 2 rows x 2,000 chars = 40,000,
+      // a tenth of this budget; at the maximum window of 50 it is 200,000, half
+      // of it, and that is before per-turn XML overhead and the inflation
+      // `escapeXmlText` adds. So this branch is out of reach at the defaults
+      // and reachable for an operator who widened the window or raised the cap
+      // — and dropping whole turns silently is the failure mode the cap was
+      // written to avoid, so say so.
+      //
+      // Both sinks, on purpose. The stderr line is what a `docker logs` on a
+      // live container shows; the trace line is the one the host keeps, because
+      // the container is detached and `--rm` and nothing parses its stderr.
+      const dropped = {
+        droppedTurns: i + 1,
+        keptTurns: entries.length,
+        budgetChars: HISTORY_CHAR_BUDGET,
+      };
+      logTiming("history_budget_dropped_turns", dropped);
+      traceEvent("history_budget_dropped_turns", dropped);
       break;
+    }
     usedChars += entry.length;
     entries.unshift(entry);
   }
@@ -1185,6 +1439,22 @@ function buildBwrapArgs(
   return args;
 }
 
+/**
+ * Whether Mercury owns the whole system prompt (`--system-prompt`) rather than
+ * appending to pi's own (`--append-system-prompt`).
+ *
+ * **Absence means override.** The host always sets `OVERRIDE_PI_SYSTEM_PROMPT`
+ * explicitly (`container-runner.ts` writes it as literal "true"/"false" on
+ * every spawn), so a missing value is unreachable in production. It is still
+ * written to deny rather than allow: the mode absence used to select — append —
+ * is the one Anthropic's OAuth gate rejects outright, so an unset var would
+ * have silently produced a bot that answers nothing, with a 400 that names
+ * billing. Only an explicit "false" or "0" turns the override off.
+ */
+export function shouldOverridePiSystemPrompt(raw: string | undefined): boolean {
+  return raw !== "false" && raw !== "0";
+}
+
 function invokePiOnce(
   payload: Payload,
   provider: string,
@@ -1192,9 +1462,9 @@ function invokePiOnce(
   capabilities: ModelCapabilities,
 ): Promise<PiJsonlParseResult> {
   return new Promise((resolve, reject) => {
-    const overridePiPrompt =
-      process.env.OVERRIDE_PI_SYSTEM_PROMPT === "true" ||
-      process.env.OVERRIDE_PI_SYSTEM_PROMPT === "1";
+    const overridePiPrompt = shouldOverridePiSystemPrompt(
+      process.env.OVERRIDE_PI_SYSTEM_PROMPT,
+    );
 
     // Combine base system prompt with extension-injected fragments
     let systemPrompt = buildSystemPrompt(

package/src/agent/container-env.ts

@@ -7,8 +7,9 @@
  * extension declares via `mercury.env()` avoid this — they are injected in
  * runtime.ts behind the extension's permission gate instead.
  *
- * `containerEnvPassthrough: "claimed"` narrows the blunt path to nothing, so
- * declared vars are the only way in.
+ * `containerEnvPassthrough: "claimed"` — the default — narrows the blunt path
+ * to the model-provider list, so declared vars are the only other way in.
+ * `"all"` is the explicit escape hatch back to blind passthrough.
  */
 
 /** Vars that must never reach a container, regardless of passthrough mode. */
@@ -71,6 +72,19 @@ export const BLOCKED_ENV_VARS = new Set([
  * test), plus MERCURY_ANTHROPIC_OAUTH_TOKEN, which console provisioning sets
  * instead of an API key.
  */
+/**
+ * Container switches that pass in both modes. Not secrets — they tell
+ * container-entry which sandbox shape to run — and read there under the
+ * stripped name (`DISABLE_BUBBLEWRAP`), which only blind passthrough ever
+ * delivered: flipping the default to `claimed` silently withdrew the
+ * documented last-resort escape hatch, and the container went back to
+ * spawning bwrap on a host where bwrap cannot start. Keep this set finite
+ * and literal, like BLOCKED_ENV_VARS.
+ */
+export const CONTAINER_SWITCH_ENV_VARS = new Set([
+  "MERCURY_DISABLE_BUBBLEWRAP",
+]);
+
 export const MODEL_PROVIDER_ENV_VARS = new Set([
   "MERCURY_AI_GATEWAY_API_KEY",
   "MERCURY_ANTHROPIC_API_KEY",
@@ -118,16 +132,18 @@ export function listUnclaimedPassthroughVars(
 }
 
 /**
- * Undeclared vars that are not model-provider plumbing — the ones worth
- * surfacing at startup. Provider keys are expected to be here and would only
- * add noise; a var in this list is one nobody scoped to anything.
+ * Undeclared vars that are neither model-provider plumbing nor a container
+ * switch — the ones worth surfacing at startup. Provider keys and the sandbox
+ * hatch pass in both modes, so naming them as "withheld" would be a lie; a var
+ * in this list is one nobody scoped to anything.
  */
 export function listUnexpectedPassthroughVars(
   env: NodeJS.ProcessEnv,
   claimed: Set<string> | undefined,
 ): string[] {
   return listUnclaimedPassthroughVars(env, claimed).filter(
-    (key) => !MODEL_PROVIDER_ENV_VARS.has(key),
+    (key) =>
+      !MODEL_PROVIDER_ENV_VARS.has(key) && !CONTAINER_SWITCH_ENV_VARS.has(key),
   );
 }
 
@@ -145,8 +161,10 @@ export function selectPassthroughEnv(
 ): Array<{ key: string; value: string }> {
   const names =
     mode === "claimed"
-      ? listUnclaimedPassthroughVars(env, claimed).filter((key) =>
-          MODEL_PROVIDER_ENV_VARS.has(key),
+      ? listUnclaimedPassthroughVars(env, claimed).filter(
+          (key) =>
+            MODEL_PROVIDER_ENV_VARS.has(key) ||
+            CONTAINER_SWITCH_ENV_VARS.has(key),
         )
       : listUnclaimedPassthroughVars(env, claimed);