# Domain Pitfalls: ngn-agent v1.1

**Domain:** Hermes Agent session workspace, memory & reporting integration
**Researched:** 2026-06-14

## Critical Pitfalls

Mistakes that cause rewrites or major issues.

### Pitfall 1: Docker Container Restart Loses Cloned Repos
**What goes wrong:** Docker container restarts (after idle timeout or gateway restart) lose all git repos cloned inside the container. Session-init clones are gone.
**Why it happens:** Container persistent storage (`container_persistent: true`) keeps containers alive for `lifetime_seconds` (300s = 5min) of inactivity. After that, the container is destroyed. Any `git clone` inside `/tmp` or `/root` is ephemeral.
**Consequences:** Repos disappear mid-session. The agent loses its workspace.
**Prevention:** **Always clone to a host-mounted volume.** Add `~/Projects:/workspace/repos:rw` to `docker_volumes`. The session-init script should check for existing clones on the mounted volume and only clone if missing.
**Detection:** Agent reports "directory not found" when accessing repos. Script always re-clones (slow) instead of checking `.git` directory existence.

### Pitfall 2: Memory Provider Conflict (Multiple External Providers)
**What goes wrong:** Configuring two external memory providers (e.g., Hindsight + Honcho) silently fails — only the first is registered.
**Why it happens:** `MemoryManager.add_provider()` explicitly rejects a second external provider with a warning (agent/memory_manager.py:342-354).
**Consequences:** User thinks both are active but only one works. No error message visible outside logs.
**Prevention:** Set `memory.provider: hindsight` and nothing else. Never add a second external provider.
**Detection:** `hermes memory list` shows only one provider. Check `~/.hermes/hermes-agent/logs/` for "Rejected memory provider" warning.

### Pitfall 3: Cron Job Prompt Injection via Skill Content
**What goes wrong:** A skill loaded by a cron job contains hidden prompt-injection payload that causes the cron LLM to take unintended actions.
**Why it happens:** Cron jobs load skill content at runtime via `_build_job_prompt()`. Skill content is scanned for injection patterns, but false negatives are possible (cron/scheduler.py:1249-1303).
**Consequences:** Cron job runs with auto-approved tools (cron jobs have `approvals.cron_mode: deny` but denial is for tool approval, not LLM output).
**Prevention:** Keep cron job skills simple and vetted. Use `no_agent` scripts for deterministic operations.
**Detection:** Cron output contains unexpected content. Check `cron/output/<job_id>/` for anomalous responses.

## Moderate Pitfalls

### Pitfall 1: Hindsight Cloud API Rate Limits
**What goes wrong:** Hindsight API rate-limits or throttles requests, causing memory writes to silently fail (async, non-blocking in MemoryManager).
**Why it happens:** `sync_turn()` is dispatched to a background thread. Failures are logged as warnings, not surfaced to the agent or user.
**Consequences:** Memory loss — agent thinks it saved facts but they never persisted.
**Prevention:** Monitor `~/.hermes/hermes-agent/logs/` for "sync_turn failed" warnings. Consider Hindsight local mode if Cloud proves unreliable.
**Detection:** `grep "sync_turn failed" ~/.hermes/hermes-agent/logs/*`

### Pitfall 2: SSH Key Exposure Inside Docker
**What goes wrong:** Hermes agent running inside Docker has read access to `~/.ssh/` via mounted volume.
**Why it happens:** The agent has file read tools. If an attacker compromises the agent (prompt injection), they could exfiltrate SSH keys.
**Consequences:** Private SSH keys leaked. Access to all repos the keys authorize.
**Prevention:** 
- Mount `~/.ssh:ro` (read-only, keys can't be modified by agent)
- Use a **deploy key** (per-repo, read-only) instead of personal SSH key
- Set `ssh-add -l` to verify key restrictions
- Consider HTTPS + personal access token (scoped, revocable) instead of SSH
**Detection:** Monitor Docker container network egress for unexpected outbound connections.

### Pitfall 3: Shell Init Script Blocking Container Start
**What goes wrong:** The session-init.sh script hangs (git clone needs SSH key passphrase, network timeout, etc.), blocking the Docker shell.
**Why it happens:** `shell_init_files` runs synchronously before the shell prompt appears. A hanging script prevents the agent from starting.
**Consequences:** Agent gets a timeout error from the terminal backend. Session is stuck.
**Prevention:** Add timeout to clone operations: `timeout 30 git clone ...`. Wrap script in `(sleep 5; ...) &` for async init. Add `set -euo pipefail` for early failure detection.
**Detection:** Docker exec test: `docker exec <container> /bin/bash -c "echo test"` to verify shell responsiveness.

## Minor Pitfalls

### Pitfall 1: Hindsight API Key in Git History
**What goes wrong:** `.env` containing `HINDSIGHT_API_KEY` gets committed to a git repo.
**Why it happens:** Developer accidentally stages `.env` files. 
**Prevention:** `/Users/bapung/.hermes/` is outside the ngn-agent repo. No risk unless `.env` is copied into a repo directory.

### Pitfall 2: DEFAULT_REPOS Superposition
**What goes wrong:** Two different session-init scripts or skills try to clone the same repo simultaneously.
**Why it happens:** Both `shell_init_files` and a session-start hook try to clone.
**Prevention:** Use only ONE mechanism. Prefer `shell_init_files` as it's guaranteed to run before the agent starts.

### Pitfall 3: Cron Report Delivers to Wrong Chat
**What goes wrong:** Daily report delivers to the wrong Telegram chat.
**Why it happens:** `deliver: origin` routes to the chat where the cron job was created. If created via CLI, `origin` is missing and cron falls back to the first available home channel (cron/scheduler.py:444).
**Prevention:** Explicitly set `deliver: telegram:474440517` (the ngn-agent DM) instead of `deliver: telegram` or `deliver: origin`.
**Detection:** Check cron delivery errors via `hermes cron list`.

## Phase-Specific Warnings

| Phase Topic | Likely Pitfall | Mitigation |
|-------------|---------------|------------|
| Hindsight activation | Provider conflict with other external provider | Verify `memory.provider` is set to only `hindsight` |
| Docker SSH volume | Key exposure via agent | Use deploy keys, read-only mount, monitor egress |
| Session init script | Blocking clone hangs container | Add timeouts, async background mode |
| Daily report skill | Poor quality LLM summaries | Iterate skill prompt; test with `hermes cron run <id>` |
| Stale cleanup script | Deleting active sessions | Add dry-run mode; check `last_updated` carefully |
| Docker volumes | Path mismatch between host/container | Use absolute paths in `docker_volumes` config |
| Git clone auth | SSH key passphrase prompt | Use key without passphrase or `ssh-agent` forwarding |

## Sources

- Hermes v0.16.0 source: `agent/memory_manager.py` line 342-354 (provider conflict)
- Hermes v0.16.0 source: `agent/memory_provider.py` line 115-131 (async sync_turn, silent failure)
- Hermes v0.16.0 source: `cron/scheduler.py` line 1249-1303 (prompt injection scanning)
- Hermes v0.16.0 source: `cron/scheduler.py` line 444 (origin fallback for delivery)
- Docker container lifecycle: `container_persistent: true` + `lifetime_seconds: 300` in config.yaml
- Existing shell init script pattern: `terminal.shell_init_files: []` (currently empty)