# Doctor & Disaster Recovery

Diagnostics, repair, backup, and restore for Agent Mail.

---

## Quick Health Check

```bash
am robot health                     # primary — CLI/direct, works without the HTTP server
curl http://127.0.0.1:8765/health   # only if the HTTP MCP server is running (am serve-http)
# → {"status": "healthy"}
```

---

## Doctor Commands

### Run Diagnostics

```bash
# Basic check
am doctor check

# Verbose with details
am doctor check --verbose

# JSON output for automation
am doctor check --json

# Check specific project
am doctor check /abs/path/project
```

**Checks performed:**
- Stale file reservations (expired TTL)
- Database integrity
- Orphaned records
- FTS index sync
- Git archive consistency

### Preview Repairs (Dry Run)

```bash
am doctor repair --dry-run
```

Shows what would be fixed without making changes.

### Apply Repairs

```bash
# Interactive (prompts for confirmation)
am doctor repair

# Auto-confirm (creates backup first)
am doctor repair --yes

# With custom backup directory
am doctor repair --yes --backup-dir /tmp/backups
```

---

## Backup & Restore

### Create Backup

```bash
# With label
am archive save --label nightly

# Default label (timestamp)
am archive save
```

### List Backups

```bash
am doctor backups

# JSON format
am doctor backups --json
```

### Restore from Backup

```bash
# Preview what would be restored
am doctor restore /path/to/backup.zip --dry-run

# Perform restore
am doctor restore /path/to/backup.zip --yes
```

---

## Static Mailbox Export

Export mailbox for auditors, stakeholders, or archives.

### Interactive Wizard (Recommended)

```bash
am share wizard
```

Guides you through export options, signing, encryption, and deployment.

### Manual Export

```bash
# Basic export
am share export --output ./bundle

# With cryptographic signing
am share export \
  --output ./bundle \
  --signing-key ./keys/signing.key

# With age encryption
am share export \
  --output ./bundle \
  --age-recipient age1abc...xyz

# Scrub sensitive content
am share export \
  --output ./bundle \
  --scrub-preset strict  # or 'standard'
```

### Preview Exported Bundle

```bash
am share preview ./bundle --port 9000 --open-browser
```

### Verify Bundle Integrity

```bash
am share verify ./bundle
```

### Refresh Existing Bundle

```bash
am share update ./bundle
```

### Decrypt Age-Encrypted Bundle

```bash
am share decrypt bundle.zip.age --identity ~/.age/key.txt
```

---

## Dangerous Operations (admin/DR mode — explicit caller authorization required)

These are the admin/disaster-recovery surface, not coordination. Each needs the
caller's explicit authorization for that specific operation; none runs as a side
effect of coordination. `doctor repair`, backup/restore, and especially the full
reset below cross from advisory into destructive.

### Full Reset (Destructive, irreversible!)

```bash
# Prompts for archive first — run only with explicit destructive-reset authorization
am clear-and-reset-everything

# Skips prompts — NEVER run without an explicit destructive-reset authorization
am clear-and-reset-everything --force --no-archive
```

**WARNING:** Deletes the SQLite database and all storage contents and cannot be
undone. `--force --no-archive` also skips the safety archive. Do not run either
form on your own initiative; report the situation and let the caller authorize.

---

## File Reservation Management

### List Reservations

```bash
# All reservations
am file_reservations list /abs/path/project

# Active only
am file_reservations list /abs/path/project --active-only

# Active with limit
am file_reservations active /abs/path/project --limit 10
```

### Expiring Soon

```bash
# Reservations expiring within 30 minutes
am file_reservations soon /abs/path/project --minutes 30
```

---

## ACK Management

### Pending Acknowledgments

```bash
am acks pending /abs/path/project GreenCastle --limit 10
```

### Overdue ACKs

```bash
am acks overdue /abs/path/project GreenCastle --ttl-minutes 60
```

### Remind About Old ACKs

```bash
am acks remind /abs/path/project GreenCastle --min-age-minutes 30
```

---

## Common Issues

| Symptom | Diagnosis | Fix |
|---------|-----------|-----|
| Stale reservations accumulating | Agent crashed without releasing | `doctor repair --yes` |
| FTS search returns wrong results | Index out of sync | `doctor repair --yes` |
| "database is locked" | Another runtime may own or be actively using the selected storage root | Identify the owner and use that root's frozen access mode; report degraded if it remains busy, and do not restart the server as a coordination side effect |
| "mailbox activity lock is busy" | A daemon or another direct runtime owns the same storage root | Use the running daemon through MCP, or a separately authorized isolated CLI root; do not restart or repair as a coordination side effect |
| "refusing to traverse symlinked snapshot directory /var" on macOS | Direct-read snapshot temporary path resolves through macOS's `/var` symlink | For an isolated invocation, set `TMPDIR` to a non-symlinked caller-scoped temporary root; do not disable traversal protection |
| Corrupted git archive | Interrupted write | Restore from backup |
| Server won't start | Port conflict | `config set-port 9000` |

# Agent Mail Tools Reference

## Table of Contents
- [Project & Identity](#project--identity)
- [Messaging](#messaging)
- [File Reservations](#file-reservations)
- [Contact Management](#contact-management)
- [Macros](#macros)
- [Guard Tools](#guard-tools)
- [Health](#health)

---

## Project & Identity

### ensure_project

Create/ensure project exists.

```
ensure_project(human_key="/abs/path/to/project")
```

**Returns:** `{id, slug, human_key, created_at}`

### register_agent

Register identity in project.

```
register_agent(
  project_key="/abs/path/project",
  program="codex-cli",
  model="YOUR_MODEL",
  name="GreenCastle",        # Optional, auto-generates if omitted
  task_description="Auth work"
)
```

**Agent naming rules:**
- MUST be adjective+noun: GreenCastle, BlueLake, RedBear
- NOT descriptive: BackendHarmonizer, DatabaseMigrator (invalid)
- Best practice: Omit `name` for auto-generation

**Returns:** `{id, name, program, model, task_description, inception_ts, last_active_ts}`

### whois

Get agent profile with recent commits.

```
whois(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  include_recent_commits=true,
  commit_limit=5
)
```

### create_agent_identity

Always create new unique agent (never updates existing).

```
create_agent_identity(
  project_key="/abs/path/project",
  program="codex-cli",
  model="YOUR_MODEL",
  name_hint="GreenCastle"    # Optional
)
```

---

## Messaging

### send_message

Send message to one or more recipients.

```
send_message(
  project_key="/abs/path/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  subject="API review needed",
  body_md="Please check the auth endpoints...",
  cc=["RedBear"],            # Optional
  bcc=["Overseer"],          # Optional
  thread_id="bd-123",        # Optional, for threading
  importance="normal",       # low|normal|high|urgent
  ack_required=true          # Request acknowledgment
)
```

### reply_message

Reply preserving thread.

```
reply_message(
  project_key="/abs/path/project",
  message_id=1234,
  sender_name="BlueLake",
  body_md="Looks good, one suggestion...",
  to=["GreenCastle"],        # Optional, defaults to original sender
  cc=["RedBear"],            # Optional
  subject_prefix="Re:"       # Default
)
```

### fetch_inbox

Get messages for agent.

```
fetch_inbox(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  limit=20,
  since_ts="2025-01-01T00:00:00Z",  # Optional
  urgent_only=false,
  include_bodies=true
)
```

### mark_message_read

Mark message as read.

```
mark_message_read(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  message_id=1234
)
```

### acknowledge_message

Acknowledge receipt (also marks read).

```
acknowledge_message(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  message_id=1234
)
```

### search_messages

FTS5 full-text search.

```
search_messages(
  project_key="/abs/path/project",
  query='"auth module" AND error',
  limit=20
)
```

### summarize_thread

Extract key points and actions.

```
summarize_thread(
  project_key="/abs/path/project",
  thread_id="bd-123",
  include_examples=true,
  llm_mode=true
)
```

---

## File Reservations

### file_reservation_paths

Reserve files before editing.

```
file_reservation_paths(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],
  ttl_seconds=3600,
  exclusive=true,
  reason="bd-123"
)
```

**Returns:** `{granted: [...], conflicts: [...]}`

Conflicts are advisory — reservations still granted.

### release_file_reservations

Release reservations.

```
release_file_reservations(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  paths=["src/auth/**"],     # Optional, releases all if omitted
  file_reservation_ids=[101] # Optional, by ID
)
```

### renew_file_reservations

Extend TTL.

```
renew_file_reservations(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  extend_seconds=1800
)
```

### force_release_file_reservation

Clear stale reservation from another agent.

```
force_release_file_reservation(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  file_reservation_id=101,
  note="Agent crashed, clearing stale lock",
  notify_previous=true
)
```

---

## Contact Management

### request_contact

Request permission to message another agent.

```
request_contact(
  project_key="/abs/path/project",
  from_agent="GreenCastle",
  to_agent="BlueLake",
  to_project="/abs/path/other",  # Optional, for cross-project
  reason="API coordination",
  ttl_seconds=604800             # 7 days default
)
```

### respond_contact

Accept or deny contact request.

```
respond_contact(
  project_key="/abs/path/project",
  to_agent="BlueLake",
  from_agent="GreenCastle",
  accept=true
)
```

### list_contacts

List contact links for agent.

```
list_contacts(
  project_key="/abs/path/project",
  agent_name="GreenCastle"
)
```

### set_contact_policy

Set contact policy.

```
set_contact_policy(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  policy="auto"  # open|auto|contacts_only|block_all
)
```

---

## Macros

### macro_start_session

One-call bootstrap.

```
macro_start_session(
  human_key="/abs/path/project",
  program="codex-cli",
  model="YOUR_MODEL",
  task_description="Auth refactor",
  file_reservation_paths=["src/auth/**"],
  inbox_limit=10
)
```

**Returns:** `{project, agent, file_reservations, inbox}`

### macro_prepare_thread

Join existing thread with context.

```
macro_prepare_thread(
  project_key="/abs/path/project",
  thread_id="bd-123",
  program="codex-cli",
  model="YOUR_MODEL",
  include_examples=true,
  inbox_limit=10
)
```

### macro_file_reservation_cycle

Reserve, work, auto-release.

```
macro_file_reservation_cycle(
  project_key="/abs/path/project",
  agent_name="GreenCastle",
  paths=["src/auth/**"],
  ttl_seconds=3600,
  auto_release=true
)
```

### macro_contact_handshake

Contact setup with optional auto-accept.

```
macro_contact_handshake(
  project_key="/abs/path/project",
  requester="GreenCastle",
  target="BlueLake",
  auto_accept=true,
  welcome_subject="Coordination request",
  welcome_body="Let's sync on API changes"
)
```

---

## Guard Tools

### install_precommit_guard

Install git pre-commit hook to enforce file reservations.

```
install_precommit_guard(
  project_key="/abs/path/project",
  code_repo_path="/abs/path/project"
)
```

### uninstall_precommit_guard

Remove pre-commit guard.

```
uninstall_precommit_guard(code_repo_path="/abs/path/project")
```

---

## Health

### health_check

Return server readiness status.

```
health_check()
```

**Returns:** `{status: "healthy"}`

# Agent Mail Coordination Patterns

Agent Mail is an optional messaging and file-reservation adapter for an
explicitly coordinated multi-writer run. The caller supplies the actors,
project, thread, paths, and message. Agent Mail does not select work, assign
ownership, decide readiness, validate a candidate, or record completion.

## Start an explicit coordination lane

The caller must provide:

- absolute project path;
- sender and recipient identities;
- stable caller-owned thread ID;
- exact path patterns and reservation TTL;
- the factual message to send.

Example:

```text
macro_start_session(
  human_key="/abs/project",
  program="codex-cli",
  model="caller-selected"
)

file_reservation_paths(
  project_key="/abs/project",
  agent_name="GreenCastle",
  paths=["src/auth/**"],
  ttl_seconds=3600,
  exclusive=true,
  reason="caller-supplied packet auth-surface"
)

send_message(
  project_key="/abs/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  thread_id="auth-surface",
  subject="[auth-surface] write scope active",
  body_md="Reserved src/auth/** for the supplied packet.",
  ack_required=true
)
```

If a reservation conflicts, report the conflicting paths and holder once.
Do not automatically wait, split the packet, retry, or choose a different
scope. The caller owns that decision.

## Request an independent review

A message can carry a review request, but its acknowledgement or reply is not
an AgentOps verdict. Include exact identity and evidence:

```text
send_message(
  project_key="/abs/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  thread_id="auth-surface",
  subject="[auth-surface] review request",
  body_md="""
Candidate manifest: sha256:...
Acceptance digest: sha256:...
Changed paths: src/auth/oauth.ts, src/auth/oauth_test.ts
Evidence: go test ./src/auth/...
Please return findings with checked and not-checked scope.
""",
  ack_required=true
)
```

The reviewer may reply with findings and evidence references. Validate remains
the sole owner of `verdict.v2`; Agent Mail never turns a reply into PASS.

## Handoff facts

Use one thread to report facts needed by another explicit actor:

```text
send_message(
  project_key="/abs/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  thread_id="auth-surface",
  subject="[auth-surface] handoff",
  body_md="""
Candidate manifest: sha256:...
Changed paths: src/auth/oauth.ts, src/auth/oauth_test.ts
Checks: go test ./src/auth/... (exit 0)
Unchecked: external identity provider integration
"""
)
```

A handoff carries no implicit ownership, approval, next action, or delivery
authority. The caller interprets it.

## Release reservations

Release only reservations held by the named actor:

```text
release_file_reservations(
  project_key="/abs/project",
  agent_name="GreenCastle",
  paths=["src/auth/**"]
)
```

Releasing a reservation is coordination cleanup, not work completion.

## Failure reporting

Return exactly the observed adapter result:

- session registration succeeded or failed;
- reservation acquired or conflicted, with paths and holder;
- message ID and recipients, or send error;
- release result.

Do not translate transport errors into retry state, queue state, lifecycle
status, or an andon. Stop after reporting the facts.