a2acalling 0.6.75 → 0.6.76

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.claude/commands/a2a-setup.md

@@ -0,0 +1,30 @@
+---
+description: Set up A2A Calling — onboard, start server, configure agent
+allowed-tools: [Bash, Read, Write]
+argument-hint: [--force]
+---
+
+Set up or reset your A2A Calling installation. Runs onboarding, starts the server, and configures your agent.
+
+## Usage
+
+```
+/a2a-setup              # first-time setup or resume incomplete onboarding
+/a2a-setup --force      # reset and re-run from scratch
+```
+
+## Instructions
+
+1. Check if already onboarded: `a2a config --show`
+2. If not onboarded (or `--force`): run `a2a quickstart $ARGUMENTS`
+3. If already onboarded but server not running: run `a2a server` in background
+4. After setup, show the status with `a2a config --show` and `a2a list`
+
+The quickstart flow will:
+- Detect an available port
+- Start the A2A server
+- Detect the hostname
+- Prompt for disclosure topics (what your agent discusses)
+- Save the configuration
+
+If running non-interactively, quickstart auto-accepts defaults.

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.claude/commands/a2a-skills.md

@@ -0,0 +1,27 @@
+---
+description: Reinstall A2A skill files into current project
+allowed-tools: [Bash]
+argument-hint: [--check|--force]
+---
+
+Reinstall or check A2A slash-command skill files in the current project.
+
+## Usage
+
+```
+/a2a-skills              # reinstall skill files (skips unchanged)
+/a2a-skills --check      # check which files are installed vs missing
+/a2a-skills --force      # force reinstall all files
+```
+
+## Instructions
+
+Run the skills command with the user's arguments:
+
+```bash
+a2a skills $ARGUMENTS
+```
+
+Show the result: which files were installed, skipped (already up to date), or had errors.
+
+If files were reinstalled, suggest reloading Claude Code to pick up the new slash commands.

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.claude/commands/a2a-status.md

@@ -0,0 +1,46 @@
+---
+description: Check A2A server status, active conversations, version, and agent health
+allowed-tools: [Bash, Read]
+argument-hint: [--version]
+---
+
+Check the health of your A2A installation — server running, conversations active, contacts online, version info.
+
+## Usage
+
+```
+/a2a-status              # full status dashboard
+/a2a-status --version    # show version only
+```
+
+## Instructions
+
+### Version only
+
+If `--version` is specified:
+
+```bash
+a2a version
+```
+
+Show the version and exit.
+
+### Full status (default)
+
+Run these commands and compile a status report:
+
+1. **Version:** `a2a version`
+2. **Config:** `a2a config --show`
+3. **Active tokens:** `a2a list`
+4. **Contacts:** `a2a contacts`
+5. **Recent conversations:** `a2a conversations --limit 5`
+
+Present a clear status dashboard:
+- Version: current version number
+- Server: running/stopped (with port and hostname)
+- Tokens: N active, N expired/revoked
+- Contacts: N total
+- Recent calls: last 5 conversations with status
+
+If the server is not running, suggest `/a2a-setup` to start it.
+If not onboarded, suggest `/a2a-setup` for first-time setup.

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.claude/commands/a2a-uninstall.md

@@ -0,0 +1,36 @@
+---
+description: Uninstall A2A Calling — stop server and remove config
+allowed-tools: [Bash, Read]
+argument-hint: [--keep-config]
+---
+
+Uninstall A2A Calling. Stops the server, removes skill files, and optionally removes configuration.
+
+## Usage
+
+```
+/a2a-uninstall                # uninstall with confirmation
+/a2a-uninstall --keep-config  # uninstall but preserve config files
+```
+
+## Instructions
+
+**This is a destructive operation. Always confirm with the user before proceeding.**
+
+1. Show the user what will be removed:
+   - Running A2A server (will be stopped)
+   - Skill files in `.claude/commands/a2a-*.md`
+   - CLAUDE.md A2A section
+   - `.codex/AGENTS.md`
+   - Config at `~/.config/openclaw/a2a-config.json` (unless `--keep-config`)
+   - Disclosure at `~/.config/openclaw/a2a-disclosure.json` (unless `--keep-config`)
+
+2. Ask the user to confirm: "This will stop the A2A server and remove installed files. Proceed?"
+
+3. If confirmed, run:
+
+```bash
+a2a uninstall --force
+```
+
+If `--keep-config` was specified, tell the user their config files were preserved and can be reused on reinstall.

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.claude/commands/a2a-update.md

@@ -0,0 +1,41 @@
+---
+description: Check for and install A2A updates
+allowed-tools: [Bash]
+argument-hint: [--check]
+---
+
+Check for available A2A updates and optionally install them.
+
+## Usage
+
+```
+/a2a-update              # check for updates and install if available
+/a2a-update --check      # check only, don't install
+```
+
+## Instructions
+
+1. First, check for updates:
+
+```bash
+a2a update --check
+```
+
+2. Show the user the current version vs available version.
+
+3. If an update is available and `--check` was NOT specified:
+   - Tell the user what version is available
+   - Ask for confirmation before updating
+   - If confirmed, run:
+
+```bash
+a2a update
+```
+
+4. After updating, show the new version:
+
+```bash
+a2a version
+```
+
+If the user is already on the latest version, tell them so.

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/.node-version

@@ -0,0 +1 @@
+20

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/ARCHITECTURE.md

@@ -0,0 +1,135 @@
+# Architecture — A2A Calling
+
+## System Overview
+
+A2A Calling enables agent-to-agent communication across OpenClaw instances. Agents create tokens with scoped permissions, share invite URLs, and remote agents call in via HTTP.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  CLI (bin/cli.js)                                                │
+│  Commands: create/list/revoke/call + ops commands (quickstart, gui, update, app, skills) │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Express Server (src/server.js)                                   │
+│  ├─ /api/a2a/* (invoke/end/message:send/agent-card/tokens/admin) → src/routes/a2a.js │
+│  ├─ /api/a2a/callbook/* + /callbook/* → src/routes/callbook.js         │
+│  ├─ /api/a2a/dashboard/* + /dashboard/* → src/routes/dashboard.js      │
+│  └─ /.well-known/a2a-agent-card → src/lib/agent-card.js               │
+└───────────┬──────────────────────────────────────────────────────┘
+            │
+┌───────────▼──────────────────────────────────────────────────────┐
+│  Core Libraries (src/lib/)                                        │
+│  ├─ tokens.js         Token CRUD, validation, tiers               │
+│  ├─ client.js         A2AClient for outbound calls (retry + size cap) │
+│  ├─ conversations.js  ConversationStore (SQLite)                  │
+│  ├─ conversation-driver.js  Multi-turn call orchestration         │
+│  ├─ summarizer.js     Call summary generation                     │
+│  ├─ summary-prompt.js Unified summary prompt builder              │
+│  ├─ summary-formatter.js  Format summaries for display            │
+│  ├─ disclosure.js     Disclosure manifest loading + tier merging  │
+│  ├─ config.js         Config file management                      │
+│  ├─ crypto.js         Ed25519 identity keypair + signing           │
+│  ├─ agent-card.js     Google A2A Agent Card generation            │
+│  ├─ logger.js         Structured logger (SQLite + stdout)         │
+│  ├─ call-monitor.js   Active call monitoring                      │
+│  ├─ callbook.js       Contact/callbook management                 │
+│  ├─ claude-subagent.js  Claude API integration for summaries      │
+│  ├─ openclaw-integration.js  OpenClaw runtime hooks               │
+│  ├─ prompt-template.js  Prompt template utilities                 │
+│  ├─ runtime-adapter.js  Runtime mode detection (openclaw/claude/test) │
+│  ├─ dashboard-events.js  SSE event broadcasting                   │
+│  ├─ external-ip.js    External IP/hostname detection              │
+│  ├─ invite-host.js    Invite URL construction                     │
+│  ├─ port-scanner.js   Available port detection                    │
+│  ├─ pid-file.js       PID file management                         │
+│  ├─ turn-timeout.js   Conversation turn timeout handling          │
+│  ├─ local-request.js  Proxy-aware local request detection (A2A-73) │
+│  ├─ update-checker.js Version update detection                    │
+│  └─ update-manager.js Self-update orchestration                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Data Storage
+
+- **Tokens**: JSON file at `~/.config/openclaw/a2a.json`
+- **Conversations**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-conversations.db` (WAL mode, A2A-71)
+- **Logs**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-logs.db` (WAL mode, A2A-71)
+- **Callbook**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-callbook.db`
+- **Dashboard Events**: SQLite via `better-sqlite3` at `~/.config/openclaw/a2a-events.db`
+- **Config**: JSON at `~/.config/openclaw/a2a-config.json`
+- **Disclosure**: JSON at `~/.config/openclaw/a2a-disclosure.json`
+
+## Database Lifecycle Management (A2A-55)
+
+All three data stores have automatic retention cleanup that runs on server startup:
+
+- **Conversations**: `ConversationStore.pruneOld()` compresses messages 7+ days old, deletes concluded/timeout conversations 90+ days old. Active conversations are never deleted.
+- **Logs**: `LogStore.pruneOld()` deletes entries 30+ days old. Auto-prune triggers on every 1000th write (best effort). `pruneAllLoggerStores()` iterates all cached stores.
+- **Tokens**: `TokenStore.cleanupExpired()` removes tokens expired >1 hour (grace for in-flight calls) and revoked tokens >30 days old.
+
+All retention periods are configurable via `a2a-config.json` `retention` section. SQLite VACUUM runs only after >100 rows deleted. All cleanup is best-effort — failures are logged but never prevent server startup.
+
+## Permission System
+
+Three tiers with escalating capabilities:
+- **public**: `context-read` only
+- **friends**: `context-read`, `calendar.read`, `email.read`, `search`
+- **family**: `context-read`, `calendar`, `email`, `search`, `tools`, `memory`
+
+Disclosure policy is manifest-driven (`~/.config/openclaw/a2a-disclosure.json`), not a token/tier `disclosure` field:
+- Per-tier `topics`, `objectives`, and `do_not_discuss` are loaded from the disclosure manifest
+- Global `never_disclose` always applies
+- Tier inheritance is enforced in prompt construction (`friends` includes `public`; `family` includes `friends` + `public`)
+
+## Dependencies
+
+Only two runtime dependencies (intentionally minimal):
+- `express` — HTTP server and routing
+- `better-sqlite3` — SQLite for conversations, logs, callbook, and dashboard events
+
+## Dashboard
+
+Single-page app served from `src/dashboard/public/`. Uses Shoelace web components. Communicates with the API via `/api/a2a/dashboard/*` routes. UI is served at both `/api/a2a/dashboard/*` and legacy `/dashboard/*` mounts. Includes panels: Contacts, Calls, Permissions, Invites, Logs, Health (E2E test results), and Settings.
+
+## Native macOS App
+
+Tauri v2 app at `native/macos/` wrapping the dashboard SPA. Provides native menus, notifications, and server lifecycle management.
+
+Runtime behavior:
+- App startup uses a sidecar-first strategy (`app.shell().sidecar("a2a-server")`) from `native/macos/src-tauri/src/server.rs`
+- If sidecar spawn fails, it falls back to starting an external `a2a` CLI process
+- Sidecar exits are monitored with bounded auto-restart and exponential backoff (up to 5 consecutive crashes)
+- Sidecar logs are bridged to the UI via emitted events
+
+Packaging:
+- The standalone server binary is built from `src/server.js` via `scripts/build-standalone.sh` using `@yao-pkg/pkg`
+- Output binaries live at `native/macos/src-tauri/binaries/a2a-server-*`
+- Tauri release builds bundle the app artifacts (`.dmg`, `.app.tar.gz`) via `.github/workflows/tauri-build.yml`
+
+## Identity Verification
+
+Ed25519 cryptographic identity for agents. Each instance generates a keypair on first run (stored in config). Outbound calls sign messages; inbound calls verify signatures. Uses Node.js built-in `crypto.sign`/`crypto.verify` — no external dependencies. See `src/lib/crypto.js`.
+
+## Google A2A Compatibility
+
+Inbound compatibility endpoints are implemented in `src/routes/a2a.js`:
+- `POST /api/a2a/message:send` (Google A2A wire format ingress mapped into internal invoke flow)
+- `GET /api/a2a/agent-card` and `GET /.well-known/a2a-agent-card` (Agent Card discovery via `src/lib/agent-card.js`)
+
+Outbound calls auto-detect Google A2A remotes via Agent Card (`GET /.well-known/a2a-agent-card`, cached 5 min with prune-on-access eviction). When detected, `A2AClient.call()` sends via `message:send` format with response translation to the internal `{ response, conversation_id, can_continue }` shape; `end()` returns a synthetic `{ ended: true, summary: null }`. See `src/lib/client.js` (A2A-80).
+
+## Testing
+
+Zero-dependency test runner at `test/run.js` with custom assert API. Three test tiers:
+- `test/unit/` — Unit tests for individual modules
+- `test/integration/` — Integration tests for multi-module flows
+- `test/e2e/` — End-to-end tests for full system flows
+
+Test profiles at `test/profiles/` represent real personas with distinct permission tiers.
+
+E2E test results are persisted to `~/.config/openclaw/test-results/` via `test/e2e/persist.js` (timestamped `result-*.json` plus `latest.json`) and surfaced in the dashboard Health tab. The `scripts/run-e2e.sh` orchestrator runs E2E suites and stores results.
+
+## Network Resilience
+
+The outbound A2A client (`src/lib/client.js`) retries transient network failures (ECONNRESET, ECONNREFUSED, EPIPE, ENOTFOUND, EAI_AGAIN, timeouts) with exponential backoff (0s, 1s, 2s). HTTP 4xx/5xx errors are not retried. All response accumulation is capped at 2MB to prevent OOM from malicious remotes. These retry and size-cap mechanisms apply equally to Google A2A outbound calls via the same `withRetry()` and `handleSizeCappedResponse()` functions (A2A-80).

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/CLAUDE-INSTALL.md

@@ -0,0 +1,156 @@
+# A2A Calling — Installed Package Context
+
+This file is automatically installed by the `a2acalling` package to give Claude Code
+immediate context after `npm install`. It describes what A2A Calling is, how to get
+started, and the full CLI reference — so you never need to grep source code.
+
+## Getting Started
+
+After installing `a2acalling`, the FIRST thing to do is run onboarding:
+
+```bash
+a2a quickstart
+```
+
+This is the single entry point for all setup. It will:
+1. Detect an available port (prefers 80, falls back to 3001+)
+2. Start the A2A server
+3. Detect the hostname
+4. Prompt for disclosure topics (what your agent discusses with callers)
+5. On macOS, offer to install the native Callbook app
+6. Save configuration to `~/.config/openclaw/a2a-config.json`
+
+If onboarding was already completed, re-run with `--force`:
+
+```bash
+a2a quickstart --force
+```
+
+## Native macOS App (A2A Callbook)
+
+On macOS, a native desktop app is available. It provides a dashboard GUI for managing
+calls, contacts, tokens, and logs.
+
+```bash
+a2a app install          # Download and install from GitHub releases
+a2a app status           # Check if installed, show version and path
+a2a app uninstall        # Remove from ~/Applications
+```
+
+After install, the app lives at `~/Applications/A2A Callbook.app`. You can also
+open the dashboard in a browser:
+
+```bash
+a2a gui                  # Open dashboard in browser (or native app if installed)
+a2a gui --tab logs       # Open specific tab: contacts|calls|logs|settings|invites
+```
+
+## Full CLI Reference
+
+### Token Management
+
+```bash
+a2a create --name "AgentName" --owner "OwnerName" --expires 7d --permissions friends
+  # Options:
+  #   --name, -n        Token/agent name
+  #   --owner, -o       Owner name
+  #   --expires, -e     1h, 1d, 7d, 30d, never (default: 1d)
+  #   --permissions, -p public, friends, family (default: public)
+  #   --disclosure, -d  public, minimal, none (default: minimal)
+  #   --notify          all, summary, none (default: all)
+  #   --max-calls       Maximum invocations (default: 100)
+  #   --topics          Custom topics (comma-separated)
+  #   --tools           Custom tool allowlist (comma-separated)
+  #   --link, -l        Auto-link to contact name
+
+a2a list                 # List active tokens
+a2a revoke <token_id>    # Revoke a token
+```
+
+### Contacts
+
+```bash
+a2a contacts             # List all contacts (shows permission badges)
+a2a contacts add <url> --name "Alice" --owner "Alice Chen"
+a2a contacts show <name> # Show contact details + linked token
+a2a contacts edit <name> # Edit contact metadata
+a2a contacts link <name> <token_id>  # Link a token to a contact
+a2a contacts ping <name> # Ping contact, update status
+a2a contacts rm <name>   # Remove contact
+```
+
+### Calling
+
+```bash
+a2a call <contact|url> "<message>"   # Multi-turn call (default: 8-25 turns)
+a2a call Alice "Hello!"              # Call by contact name
+a2a call a2a://host/fed_xxx "Hi"     # Call by invite URL
+a2a call Alice "Quick q" --single    # One-shot (single turn)
+  # --min-turns N     Minimum turns before close (default: 8)
+  # --max-turns N     Maximum turns (default: 25)
+
+a2a ping <url>           # Check if agent is reachable
+a2a status <url>         # Get remote A2A status
+```
+
+### Conversations
+
+```bash
+a2a conversations                    # List all conversations
+  # --contact         Filter by contact
+  # --status          Filter: active, concluded, timeout
+  # --limit           Max results (default: 20)
+a2a conversations show <id>          # Show conversation with messages
+a2a conversations end <id>           # End and summarize conversation
+```
+
+### Server & Setup
+
+```bash
+a2a quickstart                       # First-time setup (port, hostname, disclosure)
+  # --port, -p        Preferred port (default: 80, fallback: 3001+)
+  # --force           Reset and re-run from scratch
+  # --submit '<json>' Submit disclosure JSON
+
+a2a server --port 3001               # Start server manually
+a2a config --show                    # Show current configuration
+a2a status                           # Show local server status
+a2a gui                              # Open dashboard GUI
+a2a app install                      # Install native macOS app
+a2a setup                            # Auto setup (gateway-aware)
+```
+
+### Maintenance
+
+```bash
+a2a update               # Update to latest version
+a2a update --check       # Check for updates without installing
+a2a skills               # Install Claude Code + Codex skill files
+a2a uninstall --force    # Stop server and remove config/DB
+a2a version              # Show installed version
+```
+
+## Permission Tiers
+
+| Tier | Default Capabilities |
+|------|---------------------|
+| `public` | `context-read` |
+| `friends` | `context-read`, `calendar.read`, `email.read`, `search` |
+| `family` | `context-read`, `calendar`, `email`, `search`, `tools`, `memory` |
+
+## Disclosure Levels
+
+| Level | Behavior |
+|-------|----------|
+| `public` | Agent shares freely within tier boundaries |
+| `minimal` | Direct answers only, no volunteered context |
+| `none` | Confirms capability, provides no information |
+
+## Key Paths
+
+- Config: `~/.config/openclaw/a2a-config.json`
+- Disclosure: `~/.config/openclaw/a2a-disclosure.json`
+- Native app: `~/Applications/A2A Callbook.app` (macOS only)
+- Dashboard: `http://127.0.0.1:<port>/dashboard/`
+
+<!-- END A2A CALLING SECTION -->

package/.claude/worktrees/agent-acefedbd/.claude/worktrees/agent-a04dc0fe/CONVENTIONS.md

@@ -0,0 +1,179 @@
+# Conventions — A2A Calling
+
+## Logging
+
+For runtime/server code under `src/`, use the structured logger from `src/lib/logger.js`. Keep bare `console.log`/`console.error` limited to CLI/setup/test entrypoints (for user-facing terminal output) and the logger sink implementation in `src/lib/logger.js`.
+
+```js
+const { createLogger } = require('./logger');
+const logger = createLogger({ component: 'a2a.mymodule' });
+logger.info('Something happened', { event: 'my_event', data: { key: 'val' } });
+```
+
+Components follow dotted naming: `a2a.tokens`, `a2a.server`, `a2a.client`, etc.
+
+## Error Handling
+
+- Use the project's existing error patterns (e.g., `A2AError` from `src/lib/client.js`)
+- Log errors with `logger.error()`, including error codes and hints
+- HTTP responses use consistent JSON format: `{ success: false, error: { code, message } }`
+- Do NOT create new error classes without strong justification
+
+## Config Resolution
+
+Config directory resolves via:
+1. `process.env.A2A_CONFIG_DIR`
+2. `process.env.OPENCLAW_CONFIG_DIR`
+3. `~/.config/openclaw/`
+
+Always use `src/lib/config.js` for config access. Do not hardcode paths.
+
+## Testing
+
+- Test runner: `node test/run.js` (zero-dependency, custom assert API)
+- Test files: `*.test.js` in `test/unit/`, `test/integration/`, `test/e2e/`
+- Test helpers: `test/helpers.js`
+- Test profiles: `test/profiles/*.js` — real personas, not generic stubs
+- Prefer testing through the public API of each module
+
+## Dependencies
+
+This project is intentionally minimal-dependency. Only two runtime deps:
+- `express` — HTTP
+- `better-sqlite3` — SQLite
+
+Do NOT add new npm dependencies without explicit justification. Use Node.js built-ins.
+
+## Module Pattern
+
+Runtime/server modules use CommonJS (`require`/`module.exports`). Each lib file exports a focused API. Large modules export a class (e.g., `TokenStore`, `ConversationStore`, `A2AClient`). Utility modules export functions. Tooling scripts in this repo currently use CommonJS as well; only introduce ESM if a host integration requires it, and keep module style consistent within a file.
+
+## Naming
+
+- Files: kebab-case (`call-monitor.js`, `dashboard-events.js`)
+- Classes: PascalCase (`TokenStore`, `A2AClient`)
+- Functions/variables: camelCase
+- Constants: UPPER_SNAKE_CASE for true constants
+- Token IDs: prefixed with `fed_` (federation tokens)
+- Trace IDs: prefixed with `trace_`
+
+## Dashboard
+
+- Single-page app in `src/dashboard/public/`
+- Uses Shoelace web components (`<sl-*>` elements)
+- Communicates via fetch to `/api/a2a/dashboard/*` endpoints
+- SSE for real-time updates via `src/lib/dashboard-events.js`
+- Dark theme is the default; uses CSS custom properties for theming
+- Sidebar navigation with panel switching (Contacts, Calls, Permissions, Invites, Logs, Health, Settings)
+- Permissions tab uses tier cards with tool toggles and auto-save
+- Drag-and-drop uses event delegation on stable parent containers (`.perm-sidebar` for sidebar items, zone containers for drop targets) — do NOT bind listeners directly to innerHTML-generated elements (A2A-61)
+
+## Network Resilience (A2A-54)
+
+Outbound client methods (`call()`, `end()`) automatically retry transient network errors with exponential backoff. Pattern:
+- Use `withRetry(fn, { delays })` for retryable operations
+- Only retry on transient errors (ECONNRESET, ECONNREFUSED, EPIPE, ENOTFOUND, EAI_AGAIN, timeout)
+- Never retry HTTP 4xx/5xx — those are explicit server rejections
+- All HTTP responses are size-capped at 2MB via `handleSizeCappedResponse()`
+- Configurable retry delays via `_retryDelays` constructor option (used in tests with `[0,0,0]` for fast execution)
+
+## Dashboard API Testing (A2A-56)
+
+Dashboard API integration tests follow the pattern in `test/integration/dashboard-logs.test.js`:
+- Mount `createDashboardApiRouter()` on an Express app
+- Use `helpers.request()` for HTTP assertions (binds to 127.0.0.1 — bypasses auth)
+- Bust module caches for `dashboard`, `logger`, `tokens`, `config`, `disclosure`, `conversations`, `callbook`, `dashboard-events`
+- Call `loggerModule.closeAllLoggerStores()` in teardown to prevent SQLite handle leaks
+- Pass `convStore` directly via `options.convStore` when testing calls endpoints
+
+## Store Lifecycle (A2A-57)
+
+All SQLite store classes (`ConversationStore`, `DashboardEventStore`, `CallbookStore`, `LoggerStore`) implement a `close()` method following this pattern:
+```js
+close() {
+  if (this.db) {
+    try { this.db.close(); } catch (_) {}
+    this.db = null;
+  }
+}
+```
+- `close()` must be idempotent (safe to call multiple times)
+- `close()` must be a no-op when DB was never initialized (`this.db === null`)
+- The `server.js` `shutdown()` function closes all stores on SIGTERM/SIGINT: `serverConvStore`, `eventStore`, `callbookStore` (A2A-59), and logger stores
+- All stores should be created at the `server.js` module level and passed to route factories — do NOT create stores inside route factories (A2A-59)
+- Test teardown should call `store.close()` to prevent SQLite handle leaks
+
+## Permission Tiers
+
+Tokens carry a permissions tier (`public`, `friends`, `family`, `custom`). Disclosure policy is manifest-driven via `src/lib/disclosure.js` and tier inheritance in prompt/runtime paths.
+
+Do not add new logic that depends on `tier.disclosure` or `token.disclosure` fields; those fields were removed from the core tier/token model.
+
+## Local Request Detection (A2A-73)
+
+Use `isDirectLocalRequest(req)` from `src/lib/local-request.js` for admin/dashboard local-only checks. This helper validates loopback socket origin, localhost Host header, and absence of proxy-forwarding headers. Do NOT use raw `req.ip` comparison behind reverse proxies. The module also exports `isLoopbackAddress(ip)` for IP-only checks.
+
+## Route Hardening (A2A-53)
+
+- Rate limit Map has eviction: entries are swept when Map exceeds 1000 entries (stale >24h first, then oldest by insertion order)
+- Admin token comparison uses `timingSafeTokenEqual()` from `src/routes/a2a.js` — do NOT use `!==` for secret comparison
+- Query parameter parsing follows the dashboard.js pattern: `Math.min(max, Math.max(min, Number.parseInt(String(value), 10) || defaultValue))`
+
+## Retention & Cleanup (A2A-55)
+
+All data stores implement retention cleanup following the `dashboard-events.js` auto-prune pattern:
+
+- **Cleanup component**: Use `createLogger({ component: 'a2a.cleanup' })` for all retention logging
+- **Best effort**: Prune failures are caught and logged as warnings — never crash the server
+- **VACUUM threshold**: Only run SQLite VACUUM after >100 rows deleted (costly I/O)
+- **Auto-prune**: Logger store prunes on every 1000th `write()` call (counter-based, like dashboard-events.js)
+- **Recursion safety**: Logger `pruneOld()` uses `_pruning` flag to prevent auto-prune during explicit prune
+- **Server startup**: `src/server.js` calls all three retention mechanisms after `writePidFile()`, before `updateManager.start()`
+- **Config defaults**: `A2AConfig.getRetention()` merges partial config with defaults — never writes defaults to disk
+- **Token grace period**: Expired tokens are kept for 1 hour after expiry (in-flight call protection)
+
+## Test Runtime (A2A-66)
+
+`A2A_RUNTIME=test` provides a minimal runtime for CI and headless environments:
+- `runTurn()`: if `A2A_AGENT_COMMAND` env var is set, spawns it with `shell: true` and JSON payload on stdin; otherwise echoes the message
+- `summarize()`: returns canned `{ summary, ownerSummary }` — no LLM required
+- `notify()`: no-op (same as claude mode)
+- Non-zero exit from `A2A_AGENT_COMMAND` throws an error with stderr context
+- The CI smoke lane (`a2atesting/a2acalling/scenarios/smoke-lane.js`) uses this mode
+
+## In-Memory Map Eviction (A2A-69)
+
+For in-memory Maps that accumulate entries over time (e.g., `claudeSessions` in `runtime-adapter.js`), use the prune-on-access pattern:
+- TTL eviction: delete entries older than a configurable threshold (checked via `updatedAt` timestamp)
+- Max-entry eviction: delete oldest entries first when Map exceeds a configurable max size
+- Prune runs at the start of the next operation (not on a timer) — zero overhead when idle
+- Both thresholds configurable via environment variables
+- Refresh `updatedAt` on every access to prevent evicting active entries
+
+## Native App Sidecar Lifecycle (A2A-93, A2A-96)
+
+For native macOS server process management in `native/macos/src-tauri/src/server.rs`:
+- Start with sidecar first (`a2a-server` bundled binary), then fall back to external `a2a` only if sidecar fails
+- Track child process state in shared `SidecarState` and clear dead children on exit
+- Use exponential backoff for restart attempts and enforce a hard crash cap to avoid restart loops
+- Emit status/log events to the frontend for observability; do not silently retry in background
+- During shutdown, set explicit shutdown state to prevent unintended auto-restart
+
+## Native App Auto-Updater (A2A-100)
+
+The Tauri app uses `tauri-plugin-updater` to check for and install updates from GitHub Releases:
+- Update manifest (`latest.json`) is uploaded as a GitHub Release asset by CI
+- Background check runs 5 seconds after app launch, rate-limited to once per hour via `UpdateCheckState`
+- Manual check available from View → Check for Updates menu and Settings tab
+- Updates require user consent — banner shows in dashboard, user clicks "Update Now"
+- Signing key pair: private key in `TAURI_SIGNING_PRIVATE_KEY` GitHub secret, public key in `tauri.conf.json`
+- Do NOT auto-restart without user consent
+
+## Anti-Patterns
+
+- Do NOT use `console.log` outside the logger sink in `src/lib/logger.js`
+- Do NOT add npm dependencies for things Node.js builtins handle
+- Do NOT create new error classes — use existing patterns
+- Do NOT hardcode config paths — use config resolution
+- Do NOT use `var` — use `const` or `let`
+- Do NOT use sync file I/O in request handlers (sync is OK in CLI and setup)