mercury-agent 0.4.23 → 0.4.24

package/docs/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# {Project Name} — Architecture Reference
+
+> On-demand reference. Do not auto-load. Read when a task is cross-cutting or you need to understand inter-package data flow.
+
+## Packages
+
+| Package | Purpose | Stack | Runs On |
+|---------|---------|-------|---------|
+| `{package}/` | {purpose} | {stack} | {where it runs} |
+
+## Deployment Topology
+
+```
+{ASCII diagram of your deployment — servers, services, databases, CDNs, etc.}
+```
+
+## Data Flow
+
+> How data moves between packages, services, and external systems. Include request paths, event flows, and storage interactions.
+
+## Key Invariants
+
+> Rules that must always hold true across the system. Breaking these causes cascading failures.
+
+- {Invariant 1}
+- {Invariant 2}
+
+## Extension Points
+
+> Where the system is designed to be extended — plugin interfaces, hook points, configuration surfaces.

package/docs/DESIGN.md

@@ -0,0 +1,42 @@
+# {Project Name} — Design System
+
+> Fill this in if your project has a UI. Skip if it's a backend-only project.
+
+## 1. Visual Theme
+
+> Design principles — what the UI should feel like.
+
+## 2. Color Roles
+
+> CSS variable inventory. All colors must be defined as variables — never hardcode hex in component files.
+
+| Token | Dark Value | Light Value | Role |
+|-------|-----------|-------------|------|
+| `--bg` | {hex} | {hex} | Page background |
+| `--surface` | {hex} | {hex} | Card/panel background |
+| `--text` | {hex} | {hex} | Primary text |
+| `--muted` | {hex} | {hex} | Secondary text |
+| `--accent` | {hex} | {hex} | Interactive elements |
+| `--border` | {hex} | {hex} | Borders and dividers |
+| `--color-success` | {hex} | {hex} | Success states |
+| `--color-error` | {hex} | {hex} | Error states |
+| `--color-warning` | {hex} | {hex} | Warning states |
+
+## 3. Typography
+
+> Font families, sizes, weights. Which fonts for which contexts.
+
+## 4. Layout & Spacing
+
+> Grid system, breakpoints, spacing scale. Include RTL/logical property conventions if applicable.
+
+## 5. Components
+
+> Component conventions — buttons, inputs, cards, modals, status indicators, etc.
+
+## 6. Hard Rules
+
+> Violations block merge. Examples:
+> - No hardcoded hex colors in component files — use CSS variables
+> - No physical CSS properties (`left`/`right`) — use logical properties
+> - All interactive elements must have visible focus rings

package/docs/ROADMAP.md

@@ -0,0 +1,41 @@
+# {Project Name} — Roadmap
+
+Single source of truth for priority. Rule: ≤15 min/week to maintain.
+
+---
+
+## Inbox
+
+> Uncategorized ideas. Triage into Now / Next / Later or drop.
+
+| Item | Doc | Notes |
+|------|-----|-------|
+| — | — | — |
+
+## Now
+
+> Max 2 items. What you're actively working on.
+
+| Item | Doc | Started | Notes |
+|------|-----|---------|-------|
+| — | — | — | — |
+
+## Next
+
+| # | Item | Doc | Depends on | Why now |
+|---|------|-----|-----------|---------|
+| 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
+
+## Later
+
+| Item | Doc | Notes |
+|------|-----|-------|
+| — | — | — |
+
+---
+
+## Shipped
+
+| Item | Shipped | What |
+|------|---------|------|
+| — | — | — |

package/docs/VISION.md

@@ -0,0 +1,32 @@
+# {Project Name} — Product Vision
+
+## What {Project Name} Is
+
+> One-sentence pitch.
+
+## Target User
+
+> Who is this for? Be specific — role, context, what they're trying to accomplish.
+
+## What Makes {Project Name} Different
+
+| Differentiator | Why it matters |
+|---------------|----------------|
+| {differentiator} | {why} |
+
+## Non-Goals
+
+> Explicit list of what this project does NOT try to be. Helps filter feature requests.
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Guiding Questions for New Ideas
+
+> Use these to evaluate whether a feature idea fits the product:
+
+1. Does this serve the target user directly?
+2. Does this align with the differentiators above?
+3. Does this conflict with any non-goal?
+4. Can the user benefit from this without configuration or documentation?
+5. Would removing this make the product worse for the target user?

package/docs/bugs/bwrap-privileged-linux-docker.md

@@ -0,0 +1,140 @@
+# Bug: bwrap fails to mount /proc on Linux Docker Engine (non-Desktop)
+
+**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)
+
+## Symptom
+
+```
+Container error: Container failed (exit code 1): Error: pi CLI failed (1):
+bwrap: Can't mount proc on /newroot/proc: Operation not permitted
+```
+
+Happens on Linux servers (e.g. Hetzner, AWS EC2, DigitalOcean) running
+Docker Engine with the default kernel config. The existing bwrap Docker compat
+flags (`seccomp=unconfined`, `apparmor=unconfined`, `CAP_SYS_ADMIN`) are not
+sufficient for bwrap to mount `/proc` inside the container.
+
+## Root cause
+
+On Linux Docker Engine, the default seccomp + AppArmor + capability set does
+not allow `mount(2)` inside a user namespace, even with:
+- `--security-opt seccomp=unconfined`
+- `--security-opt apparmor=unconfined`
+- `--cap-add SYS_ADMIN`
+
+This is a known limitation: Docker's default behavior strips many mount-related
+permissions that `--privileged` restores (device cgroup rules, all capabilities,
+full /sys and /proc access).
+
+**Verified:** `--privileged` makes bwrap work:
+```bash
+# Fails:
+docker run --rm --entrypoint bwrap \
+  --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
+  --cap-add SYS_ADMIN mercury-agent:latest \
+  --ro-bind /usr /usr --proc /proc --dev /dev --unshare-pid echo hello
+# → bwrap: Can't mount proc on /newroot/proc: Operation not permitted
+
+# Works:
+docker run --rm --entrypoint bwrap --privileged mercury-agent:latest \
+  --ro-bind /usr /usr --proc /proc --dev /dev --unshare-pid echo hello
+# → execvp echo: No such file or directory  (bwrap ran fine, echo just not in /usr)
+```
+
+## Fix
+
+### Option A: Add `--privileged` flag to bwrap compat (recommended short-term)
+
+In `container-runner.ts` (~line 985), replace the current compat flags with
+`--privileged` when `containerBwrapDockerCompat` is explicitly set to `true`:
+
+```typescript
+    } else if (this.config.containerBwrapDockerCompat || isDockerDesktop()) {
+      logger.info("Enabling bwrap Docker compat (seccomp/apparmor/SYS_ADMIN)", {
+        configFlag: this.config.containerBwrapDockerCompat,
+        dockerDesktop: isDockerDesktop(),
+      });
+      if (this.config.containerBwrapDockerCompat) {
+        // Explicit opt-in: Linux Docker Engine needs --privileged for bwrap
+        // to mount /proc inside a user namespace. The finer-grained flags
+        // (seccomp=unconfined + apparmor=unconfined + SYS_ADMIN) are not
+        // sufficient on standard Linux kernels.
+        args.push("--privileged");
+      } else {
+        // Docker Desktop auto-detection: use the lighter-weight flags
+        // (Docker Desktop's VM has a more permissive kernel config)
+        args.push(
+          "--security-opt",
+          "seccomp=unconfined",
+          "--security-opt",
+          "apparmor=unconfined",
+          "--cap-add",
+          "SYS_ADMIN",
+        );
+      }
+    }
+```
+
+This keeps the lighter flags for Docker Desktop (where they work) and uses
+`--privileged` only when the user explicitly opted in via
+`MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=true`.
+
+### Option B: Add a separate `MERCURY_CONTAINER_PRIVILEGED` config flag
+
+If you prefer to keep the compat flag behavior unchanged, add a new flag:
+
+In `config.ts`, add:
+```typescript
+containerPrivileged: boolean; // default: false
+```
+
+In `config-file.ts`, add the env mapping:
+```typescript
+containerPrivileged: "MERCURY_CONTAINER_PRIVILEGED",
+```
+
+In `container-runner.ts`, after the existing compat block:
+```typescript
+    if (this.config.containerPrivileged) {
+      args.push("--privileged");
+    }
+```
+
+User sets `MERCURY_CONTAINER_PRIVILEGED=true` in `.env`.
+
+### Option C: Auto-detect and use --privileged as fallback
+
+Run a probe container on startup to test if bwrap works with the lighter
+flags. If it fails, automatically escalate to `--privileged` and log a
+warning. This is the most user-friendly but adds startup latency.
+
+## Workaround (immediate)
+
+Until the fix is in place, users can work around this by manually running
+mercury with Docker's `--privileged` flag. However, since `mercury run`
+doesn't expose extra Docker args, the only current workaround is to
+modify `MERCURY_AGENT_IMAGE` to point to a locally-built image and skip
+bwrap entirely by setting `MERCURY_CONTAINER_RUNTIME=runsc` (requires
+gVisor installed), or to apply the code change.
+
+## Linux server setup checklist
+
+These sysctl settings are needed regardless of the fix above:
+
+```bash
+sysctl -w kernel.unprivileged_userns_clone=1
+sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+cat > /etc/sysctl.d/99-bubblewrap.conf << 'EOF'
+kernel.unprivileged_userns_clone=1
+kernel.apparmor_restrict_unprivileged_userns=0
+EOF
+```
+
+## How to verify
+
+1. Set `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=true` in `.env`
+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

package/docs/runbooks/publish-checklist.md

@@ -0,0 +1,8 @@
+# Publish Checklist
+
+Before publishing a new version to npm:
+
+1. **`bun run check`** — typecheck + lint + tests
+2. **`mercury build`** — if you touched build path, Dockerfiles, or file-copy logic
+3. **`mercury init` + `mercury service install`** in a test project — if you touched CLI flow, config loading, or service management
+4. **Smoke test assistants** — send a message, verify they respond

package/docs/templates/TEMPLATE-AUTOPILOT-CONFIG.yaml

@@ -0,0 +1,35 @@
+# Autopilot Configuration
+# Copy this file to docs/autopilot/config.yaml and customize.
+# The orchestrator script reads this file each iteration.
+
+gates:
+  max_iterations: 10                   # stop after N iterations per session
+  max_features_without_review: 3       # stop after completing N features/bugs without human review
+  max_retries_same_task: 3             # skip a task after N failed attempts
+  iteration_timeout_minutes: 30        # kill a single execute phase after this long
+
+risk:
+  sensitive_paths:                     # changes to these = immediate stop for review
+    - "**/auth/**"
+    - "**/migration*"
+    - "**/.env*"
+    - "**/schema*"
+  auto_stop_risk_threshold: 8          # risk_score >= this from assess = stop
+
+scope:
+  allowed_actions:                     # which actions the autopilot may take
+    - implement_feature
+    - continue_feature
+    - fix_bug
+    - sync_docs
+    # - propose_decomposition          # uncomment to enable autonomous planning (requires allow_autonomous_planning: true)
+  skip_slugs:                           # slugs to never touch autonomously
+    # - my-feature-slug
+
+planning:
+  allow_autonomous_planning: false     # when true, autopilot can decompose ideas into draft plans (requires propose_decomposition in allowed_actions)
+                                       # plans land as Status: Proposed and always stop for human review
+
+notifications:
+  on_stop: console                     # "console" | "file" (future: "slack", "email")
+  decision_log: docs/autopilot/decision-log.md

package/docs/templates/TEMPLATE-BUG.md

@@ -0,0 +1,71 @@
+# Bug: {Title}
+
+**Status**: Open | In-Progress | Fixed
+**Severity**: minor | moderate | major
+**Slug**: {slug}
+**Reported**: {YYYY-MM-DD}
+**Last updated**: {YYYY-MM-DD}
+
+---
+
+## Summary
+
+{One-sentence description of what's broken and where.}
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+{What should happen.}
+
+## Actual Behavior
+
+{What actually happens. Include any error messages or observable symptoms.}
+
+## Impact
+
+- {Who or what is affected, and how severely.}
+
+## Suspected Location
+
+- {File path(s) or component(s) most likely responsible.}
+
+## Notes
+
+- {Workarounds, related issues, env var context, etc.}
+
+---
+
+## Implementation Checklist
+
+- [ ] Root cause identified
+- [ ] Fix implemented
+- [ ] `{your check command}` passes
+- [ ] No secrets or `.env` files committed
+- [ ] No unrelated files modified
+
+---
+
+## Post-Mortem
+
+> Fill in after the fix is complete.
+
+### Investigation
+
+{How you traced the bug — files read, code paths followed, assumptions tested.}
+
+### Root Cause
+
+{Precise explanation of the defective code and why it caused the symptom.}
+
+### Fix
+
+{What changed and why. Include file paths and key line references.}
+
+### Lessons
+
+- {Takeaways applicable to future work — patterns to avoid, checks to add, etc.}

package/docs/templates/TEMPLATE-CI.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # TODO: Add stack setup steps, e.g.:
+      # - uses: actions/setup-node@v4
+      #   with: { node-version: 20 }
+      # - run: npm ci
+
+      - name: Run checks
+        run: |
+          # TODO: Paste your check command from .claude/project-checks.md
+          # Example: npm run typecheck && npm run lint && npm test
+          echo "CI not configured — fill in the check command above"
+          exit 1

package/docs/templates/TEMPLATE-DECISIONS.md

@@ -0,0 +1,11 @@
+# Decisions: {Goal Title}
+
+**Goal**: [{goal-slug}](goal.md)
+
+## D-001: {Decision title}
+- **Category:** tech-stack | architecture | scope | pattern | trade-off
+- **Decided:** {what was chosen}
+- **Alternatives considered:** {list}
+- **Reasoning:** {why this choice}
+- **Revisit if:** {condition that would invalidate this decision}
+- **Used by:** {feature-slug-1}, {feature-slug-2}

package/docs/templates/TEMPLATE-FEATURE.md

@@ -0,0 +1,127 @@
+# {Feature Name}
+
+**Status**: Proposed | Backlog | In-Progress | Done
+**Slug**: {slug}
+**Created**: {YYYY-MM-DD}
+**Last updated**: {YYYY-MM-DD}
+
+---
+
+## Goal
+
+> One paragraph. Why does this feature exist? What problem does it solve, for whom, and why now?
+
+## User Stories
+
+- As a {role}, I want {action} so that {outcome}.
+
+## MVP Scope
+
+**In scope:** what ships in v1.
+
+**Out of scope:** what is explicitly deferred — each item with a one-line reason.
+
+---
+
+## Context for Claude
+
+> Key files to read before touching anything. 2-5 pointers — the exact paths and what lives there.
+
+- `{path/to/file}` — relevant pattern / existing logic
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+Schema definitions, column types, relationships, migrations required.
+
+```
+// exact table/type definitions here
+```
+
+### API Contracts
+
+Endpoints — HTTP method, URL, auth, request body, response shapes, error codes.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `{path}` | New | … |
+
+### Implementation Sequence
+
+Ordered steps. Call out blockers explicitly ("Step 3 must precede Step 4 because…").
+Each step must include `Read first:` (files to load before starting) and `Verify:` (how to confirm the step is done).
+
+1. {Description}
+   - Read first: `{path}`
+   - Verify: {observable outcome or command}
+
+---
+
+## Non-Negotiable Rules
+
+> Hard constraints that must not be violated. Security invariants, data-loss rules, API contracts other systems depend on.
+
+- Rule 1
+- Rule 2
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| … | … |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal (fill before asking for approval)
+- [ ] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture (fill after Goal approved)
+- [ ] Architecture & Data section complete
+- [ ] Non-Negotiable Rules defined
+- [ ] Edge Cases covered
+- [ ] Context for Claude pointers filled in
+
+### Implementation (tick off as you go)
+- [ ] Step 1 …
+- [ ] Step 2 …
+- [ ] `{your check command}` passes
+- [ ] No secrets or `.env` files committed
+- [ ] No unrelated files modified
+- [ ] All user stories verifiably met
+
+---
+
+## Open Questions
+
+- [ ] Question 1 — owner: TBD
+
+---
+
+## Retrospective
+
+> Fill this section when archiving. 3–5 bullets max. Focus on surprises and decisions — not a summary of what was built (the code is the record of that).
+
+**Residual risks / follow-ups:**
+> Every known limitation or deferred risk must be tracked or accepted — `/f-feature-dev` hard-blocks archival otherwise. Each bullet must be one of: `<desc> → ideas/<slug>.md`, `<desc> → backlog/<slug>.md`, `<desc> — accepted`, or exactly `- none` if there are no residual risks.
+- none
+
+**What changed from the plan:**
+- …
+
+**Key decisions made during implementation:**
+- …
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] New package/module added
+- [ ] New data model or schema change
+- [ ] New inter-package interaction
+- [ ] Deployment topology changed

package/docs/templates/TEMPLATE-GOAL.md

@@ -0,0 +1,31 @@
+# {Goal Title}
+
+**Status**: Proposed | Active | Paused | Complete | Abandoned
+**Slug**: {goal-slug}
+**Created**: {YYYY-MM-DD}
+**Last updated**: {YYYY-MM-DD}
+
+---
+
+## Goal Statement
+
+{The user's original goal, captured verbatim or lightly edited for clarity}
+
+## Constraints
+
+{Hard constraints: budget, timeline, must-integrate-with, regulatory, etc.
+"None stated" if the user had none.}
+
+## Preferences
+
+{User preferences: "use Vue.js", "keep it simple", "no ORMs", etc.
+Each preference is labeled (required) or (preferred) or (you decide).
+"None stated" if the user left all decisions to AI.}
+
+## Target Users
+
+{Who uses this product and how. If not stated, AI's best inference marked as "(inferred)".}
+
+## Success Criteria
+
+{What "done" looks like — observable, testable outcomes. 3-5 bullets max.}

package/docs/templates/TEMPLATE-IDEA.md

@@ -0,0 +1,31 @@
+# {Idea Title}
+
+**Status**: Idea | Considering | Promoted | Dropped
+**Slug**: {slug}
+**Created**: {YYYY-MM-DD}
+
+---
+
+## Problem
+
+> What pain or opportunity does this address? For whom?
+
+## Idea
+
+> One paragraph. What's the rough solution or approach?
+
+## How It Might Work
+
+> Optional rough sketch — not architecture, just enough to evaluate feasibility.
+
+| What | Where |
+|------|-------|
+| … | … |
+
+## Why Now
+
+> What makes this worth capturing? Urgency, dependencies, strategic fit.
+
+## Open Questions
+
+- [ ] …

package/docs/templates/TEMPLATE-NOTE.md

@@ -0,0 +1,27 @@
+# {Title}
+
+**Date**: {YYYY-MM-DD}
+**Context**: {What triggered this note — a question, comparison, research session, or discussion.}
+
+---
+
+## Summary
+
+> 2–3 sentences. What was explored and what's the takeaway?
+
+## Findings
+
+> Main content. Structure freely — tables, sections, bullet lists, whatever fits the topic.
+
+## Decisions
+
+> Optional. Concrete decisions made during or after this session. Omit if the note is purely informational.
+
+- {Decision 1}
+- {Decision 2}
+
+## Open Questions
+
+> Optional. Unresolved items worth revisiting. Omit if none.
+
+- [ ] {Question 1}