mercury-agent 0.5.0 → 0.5.2

package/docs/{bugs/bwrap-privileged-linux-docker.md → debug/major/2026-07-02-bwrap-privileged-linux-docker.md}

@@ -1,8 +1,10 @@
 # Bug: bwrap fails to mount /proc on Linux Docker Engine (non-Desktop)
 
+**Status:** Fixed  
 **Severity:** P1 — blocks all agent responses on standard Linux Docker hosts  
 **Affected:** Linux servers running Docker Engine (not Docker Desktop, not gVisor)  
-**File:** `src/agent/container-runner.ts`, bwrap compat branch (~line 980)
+**File:** `src/agent/container-runner.ts`, bwrap compat branch (~line 980)  
+**Last updated:** 2026-07-02
 
 ## Symptom
 
@@ -138,3 +140,21 @@ EOF
 2. Start mercury: `pm2 restart all` or `mercury service install`
 3. Run: `mercury chat 'hello'`
 4. Check logs — should see successful container run, no bwrap errors
+
+---
+
+## Post-Mortem
+
+### Investigation
+Reconciled this hanging bug doc against the current code during `/f-doc-sync` triage. Read the bwrap compat branch in `src/agent/container-runner.ts` (grep for `privileged`/`containerBwrapDockerCompat`/`isDockerDesktop`).
+
+### Root Cause
+On standard Linux Docker Engine, the lighter compat flags (`seccomp=unconfined` + `apparmor=unconfined` + `CAP_SYS_ADMIN`) don't permit `mount(2)` inside a user namespace, so bwrap failed with `Can't mount proc on /newroot/proc: Operation not permitted`. Only `--privileged` restores the permissions bwrap needs.
+
+### Fix
+**Option A was already implemented** — no new code required. In `container-runner.ts` (lines 1003–1008), the compat branch now pushes `--privileged` when `containerBwrapDockerCompat` is explicitly `true` (with a log line "Enabling bwrap Docker compat with --privileged"), while Docker Desktop auto-detection keeps the lighter `seccomp/apparmor/SYS_ADMIN` flags. This matches the recommended fix exactly.
+
+### Lessons
+- Reconcile hanging bug docs against the code before opening a fix session — this P1 was already resolved but never archived.
+- Container-sandbox permissions differ between Docker Desktop (permissive VM kernel) and bare Linux Docker Engine; gate the heavier `--privileged` escalation behind an explicit opt-in rather than applying it everywhere.
+- `docs/bugs/` and `docs/debug/` are gitignored working docs — archival here is a local move only.

package/docs/{bugs/e2big-prompt-delivery-fix.md → debug/major/2026-07-02-e2big-prompt-delivery-fix.md}

@@ -1,8 +1,10 @@
 # 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`
+**File:** `src/agent/container-entry.ts`  
+**Last updated:** 2026-07-02
 
 ## Symptom
 
@@ -354,3 +356,27 @@ output to confirm the full prompt arrived.
 | 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/{bugs/registry-pull-no-local-fallback.md → debug/major/2026-07-02-registry-pull-no-local-fallback.md}

@@ -1,8 +1,10 @@
 # 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)
+**File:** `src/cli/mercury.ts`, `runAction()` (~line 187)  
+**Last updated:** 2026-07-02
 
 ## Symptom
 
@@ -166,3 +168,27 @@ configured image not found?
 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

@@ -0,0 +1,72 @@
+# 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?

package/docs/deployment.md

@@ -1,199 +1,199 @@
-# Deployment
-
-Mercury can run as a background daemon with automatic restart on crash.
-
-For **environment variables vs `mercury.yaml`**, see [configuration.md](configuration.md).
-
-## Quick Setup
-
-```bash
-# Install as user service (recommended)
-mercury service install
-
-# Check status
-mercury service status
-
-# View logs
-mercury service logs -f
-
-# Uninstall when needed
-mercury service uninstall
-```
-
-## Platform Support
-
-### Linux (systemd)
-
-Mercury installs as a systemd user service by default:
-
-```bash
-# Install as user service (no sudo required)
-mercury service install
-
-# Or explicitly specify user mode
-mercury service install --user
-```
-
-The service file is written to `~/.config/systemd/user/mercury.service`.
-
-**Manual systemd commands:**
-
-```bash
-# Check status
-systemctl --user status mercury
-
-# Restart service
-systemctl --user restart mercury
-
-# Stop service
-systemctl --user stop mercury
-
-# View logs (follow mode)
-journalctl --user -u mercury -f
-```
-
-**User service notes:**
-- No root/sudo required
-- Service runs under your user account
-- Starts automatically on user login
-- For 24/7 operation without login, enable lingering: `loginctl enable-linger $USER`
-
-### macOS (launchd)
-
-Mercury installs as a launchd user agent:
-
-```bash
-mercury service install
-```
-
-The plist is written to `~/Library/LaunchAgents/com.mercury.agent.plist`.
-
-Logs are written to `.mercury/logs/` in your project directory:
-- `mercury.log` — stdout
-- `mercury.error.log` — stderr
-
-**Manual launchd commands:**
-
-```bash
-# Check if running
-launchctl list com.mercury.agent
-
-# Stop service
-launchctl stop com.mercury.agent
-
-# Start service
-launchctl start com.mercury.agent
-
-# Unload completely
-launchctl unload ~/Library/LaunchAgents/com.mercury.agent.plist
-
-# View logs
-tail -f .mercury/logs/mercury.log
-```
-
-### Windows
-
-Not currently supported via `mercury service`. Options:
-
-1. **Task Scheduler**: Create a task that runs `mercury run` at startup
-2. **NSSM**: Use [NSSM](https://nssm.cc/) to wrap Mercury as a Windows service
-3. **PM2**: Use `pm2 start "mercury run" --name mercury`
-
-## Auto-Restart Behavior
-
-Both systemd and launchd are configured to automatically restart Mercury if it crashes:
-
-- **systemd**: `Restart=on-failure` with 10-second delay
-- **launchd**: `KeepAlive=true` for immediate restart
-
-## Working Directory
-
-The service is configured to run from the directory where you ran `mercury service install`. This means:
-
-- Your `.env` file is loaded from that directory
-- Relative paths in configuration resolve from there
-- The `.mercury/` data directory is in that location
-
-If you move your Mercury project, you'll need to uninstall and reinstall the service.
-
-## Logs
-
-### Linux
-
-Logs go to the systemd journal:
-
-```bash
-# View recent logs
-mercury service logs
-
-# Follow logs in real-time
-mercury service logs -f
-
-# Or use journalctl directly
-journalctl --user -u mercury -n 100
-journalctl --user -u mercury --since "1 hour ago"
-```
-
-### macOS
-
-Logs go to files in `.mercury/logs/`:
-
-```bash
-# View recent logs
-mercury service logs
-
-# Follow logs in real-time
-mercury service logs -f
-
-# Or use tail directly
-tail -f .mercury/logs/mercury.log
-```
-
-## Troubleshooting
-
-### Service fails to start
-
-1. Run `mercury doctor` to check for common issues
-2. Check that `mercury run` works manually first
-3. Verify `.env` exists and is configured
-4. Check logs for errors: `mercury service logs`
-
-### Permission denied (Linux)
-
-If you see permission errors with system-level install, use user mode:
-
-```bash
-mercury service install --user
-```
-
-### Service not found after reboot (Linux)
-
-Enable user lingering so services start without login:
-
-```bash
-loginctl enable-linger $USER
-```
-
-### Logs not appearing (macOS)
-
-Check that the log directory exists:
-
-```bash
-mkdir -p .mercury/logs
-```
-
-Then reinstall the service:
-
-```bash
-mercury service uninstall
-mercury service install
-```
-
-### Multiple instances
-
-Each Mercury project should be installed as a separate service from its own directory. The service name is always `mercury`, so only one instance can be managed per user account.
-
-For multiple instances, consider:
-- Running different instances under different user accounts
-- Using Docker/Podman with separate containers
-- Manual systemd service files with unique names
+# Deployment
+
+Mercury can run as a background daemon with automatic restart on crash.
+
+For **environment variables vs `mercury.yaml`**, see [configuration.md](configuration.md).
+
+## Quick Setup
+
+```bash
+# Install as user service (recommended)
+mercury service install
+
+# Check status
+mercury service status
+
+# View logs
+mercury service logs -f
+
+# Uninstall when needed
+mercury service uninstall
+```
+
+## Platform Support
+
+### Linux (systemd)
+
+Mercury installs as a systemd user service by default:
+
+```bash
+# Install as user service (no sudo required)
+mercury service install
+
+# Or explicitly specify user mode
+mercury service install --user
+```
+
+The service file is written to `~/.config/systemd/user/mercury.service`.
+
+**Manual systemd commands:**
+
+```bash
+# Check status
+systemctl --user status mercury
+
+# Restart service
+systemctl --user restart mercury
+
+# Stop service
+systemctl --user stop mercury
+
+# View logs (follow mode)
+journalctl --user -u mercury -f
+```
+
+**User service notes:**
+- No root/sudo required
+- Service runs under your user account
+- Starts automatically on user login
+- For 24/7 operation without login, enable lingering: `loginctl enable-linger $USER`
+
+### macOS (launchd)
+
+Mercury installs as a launchd user agent:
+
+```bash
+mercury service install
+```
+
+The plist is written to `~/Library/LaunchAgents/com.mercury.agent.plist`.
+
+Logs are written to `.mercury/logs/` in your project directory:
+- `mercury.log` — stdout
+- `mercury.error.log` — stderr
+
+**Manual launchd commands:**
+
+```bash
+# Check if running
+launchctl list com.mercury.agent
+
+# Stop service
+launchctl stop com.mercury.agent
+
+# Start service
+launchctl start com.mercury.agent
+
+# Unload completely
+launchctl unload ~/Library/LaunchAgents/com.mercury.agent.plist
+
+# View logs
+tail -f .mercury/logs/mercury.log
+```
+
+### Windows
+
+Not currently supported via `mercury service`. Options:
+
+1. **Task Scheduler**: Create a task that runs `mercury run` at startup
+2. **NSSM**: Use [NSSM](https://nssm.cc/) to wrap Mercury as a Windows service
+3. **PM2**: Use `pm2 start "mercury run" --name mercury`
+
+## Auto-Restart Behavior
+
+Both systemd and launchd are configured to automatically restart Mercury if it crashes:
+
+- **systemd**: `Restart=on-failure` with 10-second delay
+- **launchd**: `KeepAlive=true` for immediate restart
+
+## Working Directory
+
+The service is configured to run from the directory where you ran `mercury service install`. This means:
+
+- Your `.env` file is loaded from that directory
+- Relative paths in configuration resolve from there
+- The `.mercury/` data directory is in that location
+
+If you move your Mercury project, you'll need to uninstall and reinstall the service.
+
+## Logs
+
+### Linux
+
+Logs go to the systemd journal:
+
+```bash
+# View recent logs
+mercury service logs
+
+# Follow logs in real-time
+mercury service logs -f
+
+# Or use journalctl directly
+journalctl --user -u mercury -n 100
+journalctl --user -u mercury --since "1 hour ago"
+```
+
+### macOS
+
+Logs go to files in `.mercury/logs/`:
+
+```bash
+# View recent logs
+mercury service logs
+
+# Follow logs in real-time
+mercury service logs -f
+
+# Or use tail directly
+tail -f .mercury/logs/mercury.log
+```
+
+## Troubleshooting
+
+### Service fails to start
+
+1. Run `mercury doctor` to check for common issues
+2. Check that `mercury run` works manually first
+3. Verify `.env` exists and is configured
+4. Check logs for errors: `mercury service logs`
+
+### Permission denied (Linux)
+
+If you see permission errors with system-level install, use user mode:
+
+```bash
+mercury service install --user
+```
+
+### Service not found after reboot (Linux)
+
+Enable user lingering so services start without login:
+
+```bash
+loginctl enable-linger $USER
+```
+
+### Logs not appearing (macOS)
+
+Check that the log directory exists:
+
+```bash
+mkdir -p .mercury/logs
+```
+
+Then reinstall the service:
+
+```bash
+mercury service uninstall
+mercury service install
+```
+
+### Multiple instances
+
+Each Mercury project should be installed as a separate service from its own directory. The service name is always `mercury`, so only one instance can be managed per user account.
+
+For multiple instances, consider:
+- Running different instances under different user accounts
+- Using Docker/Podman with separate containers
+- Manual systemd service files with unique names