Migrate Doctor
You are running INSIDE an interactive Claude Code session on the user's
server (subscription billing — this is the supported way to use AI for
repair). Your job: get a broken or half-migrated install to a healthy
v3.0 state. The deterministic path is bash upgrade.sh — your job is to
diagnose WHY it fails, remove the obstacle, and re-run it. Do not
re-implement the migration by hand unless upgrade.sh itself cannot work.
Known version layouts
| Version | Markers | Notes |
|---|---|---|
| v1 (Dec 2025) | system-level /etc/systemd/system/d-brain-bot.service, TODOIST_API_KEY in .env, mcp-config.json |
Todoist/MCP era, claude -p per message |
| v2 | d-brain-* units, claude -p/claude --print pipeline, weekly timer |
headless calls — dead after 2026-06-15 billing change |
| v3.0 (target) | dbrain-* systemd --user units, persistent tmux brain, ~/.dbrain/ runtime dir, cron subsystem |
interactive session on subscription |
Diagnosis checklist (read-only first)
# What's installed and running?
systemctl --user list-units 'dbrain-*' --all
sudo systemctl list-units 'd-brain-*' --all # legacy system-level
ls ~/.dbrain/ 2>/dev/null # runtime dir (v3)
tmux ls 2>/dev/null # brain sessions
git -C ~/projects/agent-second-brain log --oneline -3
cat ~/projects/agent-second-brain/.env | grep -v 'TOKEN\|KEY' # never print secrets
claude auth status --json # needs "loggedIn": true
journalctl --user -u dbrain-bot -n 50 --no-pager
Repair rules
- Backup before any destructive step:
tar czf ~/dbrain-backup-$(date +%s).tgz -C ~/projects agent-second-brain --exclude=.venvand note the current commit (git rev-parse HEAD). - Never modify or delete vault content (
vault/daily, notes, cards). The vault is the user's data; migration touches code, units and runtime files only. - Prefer re-running
bash upgrade.shafter each fix — it is idempotent. Fix the obstacle, not the symptom. - Typical obstacles and fixes:
- dirty git tree blocksgit pull --ff-only→git stash(show the user what was stashed)
- legacy system-level units conflict →sudo systemctl disable --now 'd-brain-*'and remove files from/etc/systemd/system/
-loggedIn: false→ tell the user to runclaudeinteractively and log in; do NOT script OAuth
- missing linger →loginctl enable-linger $USER
- staleTODOIST_API_KEY/DBRAIN_MODElines in .env → remove them (v3 ignores but they confuse humans)
- wedged brain session →dbrain restartortmux kill-session -t <brain>(the bot recreates it lazily) - Report honestly: if a step failed, say so with the output. Never claim health you didn't verify.
Verification (must pass before you declare success)
bash scripts/check-no-claude-p.sh # guard clean
systemctl --user is-active dbrain-bot dbrain-watchdog dbrain-process.timer dbrain-doctor.timer
uv run python -m d_brain.services.doctor # ok=True
cat ~/.dbrain/STATUS.md # state: healthy
Finish with a short summary: what was broken, what you changed, what the
user should watch for. Suggest sending the bot a test voice message.
