mercury-agent 0.5.1 → 0.5.6

package/docs/debug/major/2026-07-02-e2big-prompt-delivery-fix.md

@@ -1,382 +0,0 @@
-# Fix: E2BIG — Argument list too long on bwrap/pi spawn
-
-**Status:** Fixed  
-**Severity:** P0 — causes container crash on long conversations  
-**Affected:** All runtimes (bwrap + gVisor/direct), Docker Desktop especially  
-**File:** `src/agent/container-entry.ts`  
-**Last updated:** 2026-07-02
-
-## Symptom
-
-```
-Container failed (exit code 1): Error: E2BIG: argument list too long, posix_spawn 'bwrap'
-```
-
-Happens when a conversation has enough history that the assembled CLI args + env vars
-exceed Linux's `ARG_MAX` (~2MB). The user sees: *"Something went wrong processing your request."*
-
-## Root Cause
-
-`invokePiOnce()` (line ~741) passes both the **system prompt** and **user prompt**
-(which includes full conversation history XML) as CLI arguments:
-
-```typescript
-// CURRENT — both prompts are argv strings
-const piArgs = [
-  "--print", "--mode", "json", ...sessionArgs,
-  "--provider", provider, "--model", model,
-  ...toolModeArgs, "--no-extensions",
-  "-e", "/app/src/extensions/permission-guard.ts",
-  "-e", "/app/resources/pi-extensions/subagent/index.ts",
-  systemPromptFlag,
-  systemPrompt,        // <-- can be large (system + ext prompt)
-  buildPrompt(payload), // <-- HUGE (conversation history XML)
-];
-```
-
-These args are then passed to `spawn("bwrap", [...bwrapArgs, ...piArgs])` or
-`spawn("pi", piArgs)`. Both go through `posix_spawn`/`execve`, which enforces
-`ARG_MAX` on the combined size of all argv + envp strings.
-
-The non-bwrap (gVisor) path has the **same latent bug** — it just has slightly
-more headroom because bwrap's ~20 setup args aren't in the way.
-
-## Fix: Hybrid stdin + file-path delivery
-
-pi already supports both mechanisms natively — **no pi changes needed**:
-
-1. **`resolvePromptInput()`** in `resource-loader.js:15-29`: if the value of
-   `--system-prompt` / `--append-system-prompt` is a path to an existing file,
-   pi reads the file content. Otherwise it uses the string as-is.
-
-2. **`readPipedStdin()`** in `main.js:40-55`: when `!process.stdin.isTTY`
-   (always true inside Docker with `stdio: ["pipe", ...]`), pi reads stdin
-   and prepends it to the initial message. In `--print` mode (which Mercury
-   uses), this becomes the user prompt.
-
-### Strategy
-
-| Prompt | Delivery | Why |
-|--------|----------|-----|
-| System prompt | Write to file in IO_DIR, pass **file path** as arg | `resolvePromptInput` reads it; path string is tiny |
-| User prompt | Pipe via **stdin** | `readPipedStdin` reads it; zero argv footprint |
-| `MERCURY_EXT_SYSTEM_PROMPT` | Append to system prompt file (already concatenated in code) | Covered by the same file-path mechanism |
-
-This removes both large strings from argv entirely.
-
----
-
-## Implementation Guide
-
-All changes are in **`src/agent/container-entry.ts`** unless noted.
-
-### Step 1: Add `unlinkSync` to fs import
-
-```diff
- import {
-   accessSync,
-   constants,
-   existsSync,
-   readdirSync,
-   readFileSync,
-   renameSync,
-+  unlinkSync,
-   writeFileSync,
- } from "node:fs";
-```
-
-### Step 2: Update `buildBwrapArgs` to accept optional `ioDir`
-
-The system prompt file lives in IO_DIR, which must be visible inside the
-bwrap sandbox. Add it as a **read-only** bind mount.
-
-```diff
--function buildBwrapArgs(workspace: string, command: string[]): string[] {
-+function buildBwrapArgs(workspace: string, command: string[], ioDir?: string): string[] {
-   const args: string[] = [
-     "--ro-bind", "/usr", "/usr",
-     "--symlink", "usr/lib", "/lib",
-     "--symlink", "usr/bin", "/bin",
-     "--symlink", "usr/sbin", "/sbin",
-   ];
-   if (existsSync("/usr/lib64")) {
-     args.push("--symlink", "usr/lib64", "/lib64");
-   }
-   args.push("--ro-bind", "/app", "/app", "--ro-bind", "/etc", "/etc");
-   if (existsSync("/docs")) {
-     args.push("--ro-bind", "/docs", "/docs");
-   }
-+  if (ioDir) {
-+    args.push("--ro-bind", ioDir, ioDir);
-+  }
-   args.push(
-     "--bind", "/spaces", "/spaces",
-```
-
-### Step 3: Rewrite prompt construction in `invokePiOnce`
-
-Replace the current piArgs construction (lines ~720-758) with:
-
-```typescript
-function invokePiOnce(
-  payload: Payload,
-  provider: string,
-  model: string,
-  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";
-
-    // Combine base system prompt with extension-injected fragments
-    let systemPrompt = buildSystemPrompt(
-      capabilities,
-      payload,
-      overridePiPrompt,
-    );
-    const extPrompt = process.env.MERCURY_EXT_SYSTEM_PROMPT;
-    if (extPrompt) {
-      systemPrompt = `${systemPrompt}\n\n${extPrompt}`;
-    }
-
-    // Build the user prompt (conversation history + current message)
-    const userPrompt = buildPrompt(payload);
-
-    const sessionArgs = ["--no-session"];
-
-    const toolModeArgs = capabilities.tools
-      ? ([] as string[])
-      : (["--no-tools", "--no-skills"] as string[]);
-
-    const systemPromptFlag = overridePiPrompt
-      ? "--system-prompt"
-      : "--append-system-prompt";
-
-    // --- E2BIG fix: deliver large prompts via file + stdin ---
-    //
-    // System prompt → temp file in IO_DIR (pi's resolvePromptInput reads files).
-    // User prompt   → stdin pipe (pi's readPipedStdin reads when !isTTY).
-    // This keeps argv small regardless of conversation length.
-    const ioDir = process.env.IO_DIR;
-    let systemPromptArg: string;
-    let systemPromptFile: string | undefined;
-    if (ioDir) {
-      systemPromptFile = path.join(ioDir, "system-prompt.txt");
-      writeFileSync(systemPromptFile, systemPrompt);
-      systemPromptArg = systemPromptFile; // pi reads the file, not the path string
-    } else {
-      systemPromptArg = systemPrompt; // dev fallback: inline (small payloads)
-    }
-
-    // piArgs no longer contains the user prompt — it goes via stdin.
-    // The positional message arg is omitted entirely.
-    const piArgs = [
-      "--print",
-      "--mode",
-      "json",
-      ...sessionArgs,
-      "--provider",
-      provider,
-      "--model",
-      model,
-      ...toolModeArgs,
-      "--no-extensions",
-      "-e",
-      "/app/src/extensions/permission-guard.ts",
-      "-e",
-      "/app/resources/pi-extensions/subagent/index.ts",
-      systemPromptFlag,
-      systemPromptArg,
-      // NOTE: no positional prompt arg — user prompt piped via stdin
-    ];
-```
-
-### Step 4: Update both spawn sites
-
-Replace the spawn block (lines ~776-793):
-
-```typescript
-    const piSpawnedAt = Date.now();
-    let proc: ReturnType<typeof spawn>;
-    if (useBubblewrap) {
-      const bwrapArgs = [
-        ...buildBwrapArgs(payload.spaceWorkspace, ["pi"], ioDir ?? undefined),
-        ...piArgs,
-      ];
-      proc = spawn("bwrap", bwrapArgs, {
-        stdio: ["pipe", "pipe", "pipe"],  // changed: stdin is now "pipe"
-        env: process.env,
-      });
-    } else {
-      proc = spawn("pi", piArgs, {
-        cwd: payload.spaceWorkspace,
-        stdio: ["pipe", "pipe", "pipe"],  // changed: stdin is now "pipe"
-        env: process.env,
-      });
-    }
-
-    // Pipe user prompt via stdin — avoids E2BIG on long conversations.
-    // pi's readPipedStdin() reads this when !process.stdin.isTTY (always true in Docker).
-    proc.stdin!.on("error", () => {}); // swallow EPIPE if pi exits early
-    proc.stdin!.end(userPrompt, "utf8");
-```
-
-### Step 5: Clean up system prompt file on close
-
-In the `proc.on("close", ...)` handler (line ~815), add cleanup at the top:
-
-```diff
-     proc.on("close", (code) => {
-+      // Clean up temp system prompt file (belt-and-suspenders; IO_DIR is ephemeral)
-+      if (systemPromptFile) {
-+        try { unlinkSync(systemPromptFile); } catch {}
-+      }
-       logTiming("container.pi.done", {
-         piDurationMs: Date.now() - piSpawnedAt,
-         exitCode: code ?? null,
-       });
-```
-
-Also add the same cleanup in the `proc.on("error", ...)` handler:
-
-```diff
-     proc.on("error", (error) => {
-+      if (systemPromptFile) {
-+        try { unlinkSync(systemPromptFile); } catch {}
-+      }
-       reject(error);
-     });
-```
-
----
-
-## P0 companion: Byte-budget guard on history (defense-in-depth)
-
-Even with the delivery fix, it's good practice to cap history size. This also
-reduces token waste on very long conversations.
-
-In `buildHistoryXml` (line ~533), replace the unbounded entries construction:
-
-```typescript
-const HISTORY_CHAR_BUDGET = 400_000; // ~100K tokens — well under model limits
-
-function buildHistoryXml(messages: StoredMessage[]): string | null {
-  // Pair up user+assistant turns (existing logic unchanged)
-  const turns: Array<{ user: StoredMessage; assistant?: StoredMessage }> = [];
-  let pendingUser: StoredMessage | null = null;
-
-  for (const m of messages) {
-    if (m.role === "user") {
-      if (pendingUser) {
-        turns.push({ user: pendingUser });
-      }
-      pendingUser = m;
-    } else if (m.role === "assistant" && pendingUser) {
-      turns.push({ user: pendingUser, assistant: m });
-      pendingUser = null;
-    }
-  }
-  if (pendingUser) turns.push({ user: pendingUser });
-
-  if (turns.length === 0) return null;
-
-  // Build newest-first, stop when budget exhausted
-  const entries: string[] = [];
-  let usedChars = 0;
-
-  for (let i = turns.length - 1; i >= 0; i--) {
-    const { user, assistant } = turns[i];
-    const ts = formatContextTimestamp(user.createdAt);
-    const userLine = `    <user>${escapeXmlText(user.content)}</user>`;
-    const assistantLine = assistant
-      ? `\n    <assistant>${escapeXmlText(assistant.content)}</assistant>`
-      : "";
-    const entry = `  <turn timestamp="${ts}">\n${userLine}${assistantLine}\n  </turn>`;
-
-    if (usedChars + entry.length > HISTORY_CHAR_BUDGET) break;
-    usedChars += entry.length;
-    entries.unshift(entry); // maintain chronological order
-  }
-
-  if (entries.length === 0) return null;
-  return `<history>\n${entries.join("\n")}\n</history>`;
-}
-```
-
----
-
-## How to verify
-
-### 1. Unit test: large payload doesn't crash
-
-Create a payload with >128KB of conversation history. Verify `invokePiOnce`
-spawns successfully (no E2BIG). The container needs Docker running.
-
-### 2. Manual test: long WhatsApp conversation
-
-Find (or create) a space with 50+ messages. Send a new message. Verify the
-agent responds instead of crashing with "Something went wrong."
-
-### 3. Regression test: short conversations still work
-
-Normal short conversations should be completely unaffected. The prompts reach
-pi with identical content — only the delivery channel changed.
-
-### 4. Verify stdin content reaches pi correctly
-
-Add a temporary `logTiming("prompt.sizes", { systemPromptLen: systemPrompt.length, userPromptLen: userPrompt.length })` before spawn. Compare with pi's
-output to confirm the full prompt arrived.
-
----
-
-## Edge cases to watch
-
-| Case | Behavior |
-|------|----------|
-| IO_DIR unset (local dev) | System prompt stays inline in argv; user prompt still goes via stdin. Safe for small dev payloads. |
-| pi exits before reading stdin | `proc.stdin.on("error", () => {})` swallows EPIPE. pi's exit code/stderr still captured normally. |
-| System prompt file path collides with real text | Only triggers if the system prompt string happens to be a valid file path. Extremely unlikely for a multi-KB prompt. If paranoid, use a path with a UUID. |
-| bwrap + IO_DIR mount | IO_DIR is `--ro-bind` (read-only). pi can read the system prompt file but cannot write to IO_DIR. Correct for security. |
-| Retry logic in `runModelChain` | Each retry calls `invokePiOnce` fresh — each writes a new system prompt file and pipes stdin. Previous file is cleaned up on close. No stale state between retries. |
-| `MERCURY_EXT_SYSTEM_PROMPT` | Already concatenated into `systemPrompt` before the file write. Covered automatically. |
-
----
-
-## Summary of changes
-
-| What | Where | Lines affected |
-|------|-------|----------------|
-| Add `unlinkSync` import | fs import block | 1 line |
-| `buildBwrapArgs` accepts `ioDir` | Function signature + body | ~4 lines |
-| System prompt → file in IO_DIR | `invokePiOnce`, before piArgs | ~8 lines |
-| Remove user prompt from piArgs | `invokePiOnce`, piArgs array | Remove 1 line |
-| stdin: "ignore" → "pipe" | Both spawn sites | 2 lines |
-| Pipe user prompt to stdin | After spawn | 2 lines |
-| Cleanup system prompt file | close + error handlers | 4 lines |
-| **Total** | | **~22 lines changed** |
-| Byte-budget history (optional companion) | `buildHistoryXml` | Replace function body |
-
----
-
-## Post-Mortem
-
-### Investigation
-Verified the current state of `src/agent/container-entry.ts` against this fix guide before doing any work (bug was flagged as a hanging doc during `/f-doc-sync`, never archived). Grepped and read the relevant functions: `buildBwrapArgs` (line 676), `invokePiOnce` (line 728), `buildHistoryXml` (line 534), and both spawn sites (line 810).
-
-### Root Cause
-`invokePiOnce()` passed the system prompt and the full conversation-history XML as `argv` strings to `posix_spawn('bwrap'|'pi', …)`. On long conversations the combined argv + envp size exceeded Linux `ARG_MAX` (~2MB), so `execve` failed with `E2BIG` and the container exited 1.
-
-### Fix
-The complete fix described in this guide was **already implemented** in the tree — no new code was required:
-- `unlinkSync` imported and used in the `close`/`error` handlers (lines 854, 865).
-- `buildBwrapArgs(workspace, command, ioDir?)` binds `IO_DIR` read-only into the sandbox (line 679 signature; line 716 `--ro-bind ioDir ioDir`).
-- System prompt written to `IO_DIR/system-prompt.txt` and passed as a file path (pi's `resolvePromptInput` reads it) — lines 765–771.
-- User prompt removed from `argv` and piped via stdin (`proc.stdin?.end(userPrompt, "utf8")`) with both spawn sites using `stdio: ["pipe","pipe","pipe"]` — lines 814–831.
-- Temp system-prompt file cleaned up on close and error — lines 852–865.
-- Optional companion `HISTORY_CHAR_BUDGET = 400_000` applied in `buildHistoryXml` (lines 534, 571) as defense-in-depth.
-
-### Lessons
-- Hanging bug docs should be reconciled against the code before opening a fix session — this one was fully resolved but never archived, so it lingered as an apparent P0.
-- Never pass unbounded, caller-influenced data (conversation history) through `argv`; use stdin or a file whose path is the only thing in `argv`. Pair the delivery fix with a size budget so history growth can't regress the limit.
-- `docs/bugs/` and `docs/debug/` are gitignored working docs — archival here is a local move only, with no commit/push.

package/docs/debug/major/2026-07-02-registry-pull-no-local-fallback.md

@@ -1,194 +0,0 @@
-# Bug: mercury run fails when registry pull fails but local build exists
-
-**Status:** Fixed  
-**Severity:** P1 — blocks users who build locally but have a registry image configured  
-**Introduced in:** 0.4.22 (commit 75e8e71)  
-**File:** `src/cli/mercury.ts`, `runAction()` (~line 187)  
-**Last updated:** 2026-07-02
-
-## Symptom
-
-```
-$ mercury build          # succeeds → mercury-agent:latest exists locally
-$ mercury run
-Image 'ghcr.io/avishai-tsabari/mercury-agent:latest' not found locally, pulling...
-Error response from daemon: unauthorized
-
-Error: Failed to pull 'ghcr.io/avishai-tsabari/mercury-agent:latest'.
-If this is a private registry, authenticate first:
-  docker login ghcr.io
-```
-
-The user has a working local image (`mercury-agent:latest`) from `mercury build`,
-but `mercury run` exits with an error because the configured registry image
-can't be pulled (private registry, no auth, offline, etc.).
-
-## Root cause
-
-The 0.4.22 change replaced the local-fallback logic with auto-pull. The old
-code tried `mercury-agent:latest` as a fallback when the configured image
-wasn't found. The new code attempts `docker pull` and hard-exits on failure —
-it never checks whether a locally built image exists.
-
-### Before (0.4.21)
-
-```
-configured image not found?
-  → try mercury-agent:latest locally
-    → found? use it (with warning)
-    → not found? error: pull or build
-```
-
-### After (0.4.22)
-
-```
-configured image not found?
-  → is registry image? attempt pull
-    → pull fails? hard exit  ← BUG: should fall back to local
-  → not registry? error: run mercury build
-```
-
-## Fix
-
-After a failed pull of a registry image, check if `mercury-agent:latest`
-exists locally before giving up. If it does, use it with a warning.
-
-### Implementation (lines ~187–213 of `src/cli/mercury.ts`)
-
-Replace the current block:
-
-```typescript
-if (imageCheck.status !== 0) {
-    const isRegistryImage = imageName.includes("/");
-    if (isRegistryImage) {
-      console.log(`Image '${imageName}' not found locally, pulling...`);
-      const pull = spawnSync("docker", ["pull", imageName], {
-        stdio: "inherit",
-      });
-      if (pull.signal) {
-        process.exit(1);
-      }
-      if (pull.status !== 0) {
-        const firstSegment = imageName.split("/")[0];
-        const registry = firstSegment.includes(".")
-          ? firstSegment
-          : "docker.io";
-        console.error(`\nError: Failed to pull '${imageName}'.`);
-        console.error(
-          "If this is a private registry, authenticate first:\n" +
-            `  docker login ${registry}`,
-        );
-        process.exit(1);
-      }
-    } else {
-      console.error(`Error: Container image '${imageName}' not found.`);
-      console.error("Run 'mercury build' to build it.");
-      process.exit(1);
-    }
-  }
-```
-
-With:
-
-```typescript
-if (imageCheck.status !== 0) {
-    const isRegistryImage = imageName.includes("/");
-    let resolved = false;
-
-    if (isRegistryImage) {
-      console.log(`Image '${imageName}' not found locally, pulling...`);
-      const pull = spawnSync("docker", ["pull", imageName], {
-        stdio: "inherit",
-      });
-      if (pull.signal) {
-        process.exit(1);
-      }
-      if (pull.status === 0) {
-        resolved = true;
-      }
-    }
-
-    // Fallback: if the configured image isn't available (pull failed, not a
-    // registry image, or never pulled), try the local build tag.
-    if (!resolved) {
-      const localTag = "mercury-agent:latest";
-      if (imageName !== localTag) {
-        const localCheck = spawnSync("docker", ["image", "inspect", localTag], {
-          stdio: "pipe",
-        });
-        if (localCheck.status === 0) {
-          console.log(
-            `\nℹ️  Using locally built ${localTag} (configured image unavailable)\n`,
-          );
-          process.env.MERCURY_AGENT_IMAGE = localTag;
-          resolved = true;
-        }
-      }
-    }
-
-    if (!resolved) {
-      if (isRegistryImage) {
-        const firstSegment = imageName.split("/")[0];
-        const registry = firstSegment.includes(".")
-          ? firstSegment
-          : "docker.io";
-        console.error(`\nError: Failed to pull '${imageName}'.`);
-        console.error(
-          "If this is a private registry, authenticate first:\n" +
-            `  docker login ${registry}\n` +
-            "Or build locally:\n" +
-            "  mercury build",
-        );
-      } else {
-        console.error(`Error: Container image '${imageName}' not found.`);
-        console.error("Run 'mercury build' to build it.");
-      }
-      process.exit(1);
-    }
-  }
-```
-
-### Behavior after fix
-
-```
-configured image not found?
-  → is registry image? attempt pull
-    → pull succeeds? use it ✓
-    → pull fails? continue to fallback
-  → try mercury-agent:latest locally
-    → found? use it (with info message) ✓
-    → not found? error with both suggestions (login + build) ✓
-```
-
-## How to verify
-
-1. Build locally: `mercury build`
-2. Ensure no GHCR auth: `docker logout ghcr.io`
-3. Set `.env` to `MERCURY_AGENT_IMAGE=ghcr.io/avishai-tsabari/mercury-agent:latest`
-4. Run `mercury run` — should fall back to local image with info message
-5. Remove local image: `docker rmi mercury-agent:latest`
-6. Run `mercury run` — should error with both `docker login` and `mercury build` suggestions
-
----
-
-## Post-Mortem
-
-### Investigation
-Triaged from a hanging bug doc during `/f-doc-sync`. First confirmed the fix was NOT already present: grepped `src/` for any local-fallback logic (`Using locally built`, `localTag`, `resolved`) — zero hits — and read `runAction()` in `src/cli/mercury.ts` (lines 186–216), which was still the buggy 0.4.22 version that hard-exits on pull failure. Fixed in an isolated worktree.
-
-### Root Cause
-The 0.4.22 auto-pull rewrite dropped the pre-existing local-image fallback. When the configured image was a registry ref and `docker pull` failed (private registry / no auth / offline), `runAction()` called `process.exit(1)` immediately, never checking whether a locally built `mercury-agent:latest` existed.
-
-### Fix
-`src/cli/mercury.ts`, `runAction()` (committed to main as `1c120bf`):
-- Introduced a `resolved` flag. A registry pull sets it on success; on failure, control falls through instead of exiting.
-- Added a fallback block: if unresolved and the configured image isn't already `mercury-agent:latest`, `docker image inspect mercury-agent:latest`; if present, use it with an info message.
-- Only after both paths fail does it `process.exit(1)`, now suggesting **both** `docker login` and `mercury build`.
-- **Beyond the original fix guide:** the child is spawned with `env: { ...process.env, ...envVars }`, and `envVars` (loaded from `.env`, which typically pins `MERCURY_AGENT_IMAGE` to the registry) wins that merge. Setting only `process.env.MERCURY_AGENT_IMAGE` would have been silently clobbered — the repro scenario itself. The fix therefore also sets `envVars.MERCURY_AGENT_IMAGE = localTag`. Confirmed load-bearing by the session code review.
-
-Verification: `bun run typecheck` + `bun run lint` clean; `bun test` → 1039 pass / 0 fail; session code review returned "No issues found."
-
-### Lessons
-- When a spawn merges multiple env sources (`{ ...process.env, ...envVars }`), an override must be written to the **last-wins** source, not just `process.env` — otherwise it's silently reverted.
-- Behavior-replacing rewrites (the 0.4.22 auto-pull change) should preserve existing fallbacks explicitly; a regression test for "pull fails but local image exists" would have caught this.
-- Reconcile hanging bug docs against current code before opening a fix — two sibling P0/P1 docs (`e2big`, `bwrap-privileged`) turned out already fixed; only this one needed work.

package/docs/debug/summarization/2026-07-02-common-bug-patterns.md

@@ -1,72 +0,0 @@
-# Common Bug Patterns
-
-**Date:** 2026-07-02
-**Covers:** 1 bug report (1 major, 0 moderate, 0 minor) · 2026-07-01 → 2026-07-01
-
-This is the first bug-pattern summary. It covers a single major incident — the strict-YAML-schema crash — but that one bug braids together several distinct, reusable failure patterns worth capturing before they recur: over-strict input validation, unbounded restart loops, and the fragile-transport amplification that turns any crash into extended downtime. The dominant theme is **conflation**: treating "unknown input" and "invalid input" as the same failure, and treating "one crash" as harmless when the surrounding system amplifies it.
-
-## Findings
-
-### 1. Over-strict input validation (unknown key ≠ invalid value)
-
-Schemas that reject unrecognized input with the same severity as malformed input turn benign drift (typos, renamed fields, version skew) into hard failures.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | `mercuryFileSchema` used Zod `.strict()` on all 13 nested objects, so a single unknown `mercury.yaml` key (e.g. renamed `admin_numbers` → `admin_ids`) crashed startup with the same severity as an invalid value. |
-
-**Rule:** Separate "unknown key" (warn, strip, continue) from "invalid value" (fail fast). Default config schemas to strip-and-warn on unrecognized keys; reserve hard failure for values that are actually wrong.
-
-### 2. Version-skew intolerance
-
-Config that must be exactly in sync with the running binary breaks on every field rename, punishing the normal lifecycle of upgrades and rollbacks.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | A field renamed between 0.4.26 and 0.4.27 (`admin_numbers` → `admin_ids`) crashed any deployment whose yaml hadn't been updated in lockstep. |
-
-**Rule:** Any feature that adds or renames a config field must assume a user on version N may run a yaml from version N±1. Forward/backward-unknown keys should degrade gracefully, not crash.
-
-### 3. Unbounded restart loops amplify a single failure
-
-A deterministic startup error plus an unbounded auto-restarter converts one crash into an infinite crash loop, removing any window for human intervention.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | PM2's default unlimited restarts retried the identical failing config forever, each attempt failing the same way. |
-
-**Rule:** Configure `max_restarts` + `min_uptime` on process supervisors so a deterministic failure stops after N attempts and alerts, rather than looping. A restart policy is not a substitute for handling the error.
-
-### 4. Fragile-transport amplification
-
-When a downstream dependency punishes rapid reconnection, an unrelated crash loop escalates into a much costlier outage than the original bug.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | The crash loop drove rapid WhatsApp/Baileys reconnects, which Meta treats as abuse → session revoked (reason=401) → manual QR re-scan required for recovery. |
-
-**Rule:** Treat any crash loop as catastrophic when a session-based/unofficial transport is in play. Isolate transport-session lifecycle from process restarts, and prefer a circuit breaker that keeps the host alive while surfacing the error.
-
-## Summary table
-
-| Pattern | Count | Worst severity |
-|---------|-------|----------------|
-| Over-strict input validation | 1 | major |
-| Version-skew intolerance | 1 | major |
-| Unbounded restart loops | 1 | major |
-| Fragile-transport amplification | 1 | major |
-
-## Comparison with previous summary
-
-None — this is the first bug-pattern summary. Future summaries should track whether validation-strictness and restart-loop patterns recur once the fixes above land.
-
-## Decisions
-
-1. **Adopt strip-and-warn as the config default** across all schemas; audit remaining `.strict()` usages for the same class of crash.
-2. **Set supervisor restart limits** (`max_restarts`, `min_uptime`) plus an alert on limit-hit, so no deterministic failure can loop indefinitely.
-3. **Design a container/transport circuit breaker** (the bug's own Phase 2) so container-level errors log-and-recover instead of crashing the host and endangering the WhatsApp session.
-
-## Open Questions
-
-- Should config validation ever hard-fail on unknown keys in a "strict mode" opt-in for CI, while defaulting to warn in production?
-- What is the right `max_restarts` threshold given Baileys' revocation sensitivity — and should transport reconnection back off independently of process restarts?