···11+# Emacs Stack Report — Docker Container Context (2026-01-21)
22+33+## Purpose
44+Document how the Emacs stack works inside the dev container, why the UI can appear as only `*scratch*`, and how to reliably bring back the full Aesthetic tab layout after crashes.
55+66+## Primary Entry Points
77+1. **Daemon start script**
88+ - The container starts Emacs in daemon mode with the repo config:
99+ - Config path: [dotfiles/dot_config/emacs.el](dotfiles/dot_config/emacs.el)
1010+ - Startup logic: [ .devcontainer/config.fish](.devcontainer/config.fish)
1111+1212+2. **Crash monitor / watchdog**
1313+ - Keeps the daemon alive and restarts it if it becomes unresponsive.
1414+ - Crash monitor script: [monitor-emacs.sh](monitor-emacs.sh)
1515+ - Logs: [.emacs-logs](.emacs-logs)
1616+1717+3. **Terminal client**
1818+ - `emacsclient -t` or `ac-aesthetic` connects a terminal frame.
1919+ - The first terminal frame triggers the backend that creates tabs and Eat terminals.
2020+2121+## Core Runtime Components
2222+### `aesthetic-backend`
2323+Defined in [dotfiles/dot_config/emacs.el](dotfiles/dot_config/emacs.el).
2424+- Creates tab bar layout and terminal buffers.
2525+- Runs all `ac-*` commands that launch web servers, sessions, Redis, oven, etc.
2626+- Switches to a target tab after creation (default: `artery`).
2727+2828+### `ac--maybe-start-backend`
2929+Also in [dotfiles/dot_config/emacs.el](dotfiles/dot_config/emacs.el).
3030+- Registered via `after-make-frame-functions`.
3131+- Only runs when a **terminal frame** connects.
3232+- That’s why headless daemon restarts show `*scratch*` only until a terminal frame connects.
3333+3434+### Eat terminals
3535+Each tab uses Eat to run a fish command (e.g., `ac-redis`, `ac-site`, `ac-session`).
3636+If Emacs restarts without a terminal frame, **none of these processes are re-spawned** until `aesthetic-backend` runs again.
3737+3838+## Normal Startup Flow (Expected)
3939+1. Daemon starts via `.devcontainer/config.fish`.
4040+2. Terminal frame connects (`ac-aesthetic` or `emacsclient -t`).
4141+3. `ac--maybe-start-backend` calls `aesthetic-backend`.
4242+4. Tabs and Eat buffers are created in order.
4343+5. After a delay, Emacs switches to the target tab (`artery`).
4444+4545+## Crash + Auto-Restart Flow (Observed)
4646+1. Crash monitor restarts the daemon.
4747+2. Daemon is alive **but no terminal frame is connected**.
4848+3. `aesthetic-backend` does **not** run automatically.
4949+4. User sees only `*scratch*` and no tabs.
5050+5151+**This is expected behavior** given the current hook architecture.
5252+5353+## Why You See Only `*scratch*`
5454+The backend startup is tied to `after-make-frame-functions` and specifically checks for terminal frames. When the daemon restarts in the background, no terminal client connects, so the backend never runs. This leaves a minimal Emacs session without tabs or Eat buffers.
5555+5656+## Recovery Steps
5757+If Emacs restarts and only `*scratch*` is visible:
5858+1. Connect a terminal frame:
5959+ - `emacsclient -t`
6060+2. If the tabs do not appear, explicitly run:
6161+ - `M-x aesthetic-backend`
6262+ - Or evaluate: `(aesthetic-backend "artery")`
6363+6464+## Signals and Logs to Verify State
6565+- **Is the daemon running?**
6666+ - `pgrep -f "emacs.*daemon"`
6767+- **Did `aesthetic-backend` run?**
6868+ - Check [ .emacs-logs/emacs-debug.log](.emacs-logs/emacs-debug.log) for:
6969+ - `Starting aesthetic-backend with target-tab: artery`
7070+- **Did tabs get created?**
7171+ - `emacsclient -e '(tab-bar-tabs)'`
7272+7373+## Known Failure Modes
7474+1. **Crash without terminal reconnect**
7575+ - Result: only `*scratch*` and no tabs.
7676+2. **Backend delay warnings**
7777+ - Log entry: `WARNING: aesthetic-backend has been running for 30+ seconds`.
7878+ - Usually indicates slow-starting processes in Eat buffers.
7979+3. **CDP tunnel failure**
8080+ - Log entry: `CDP tunnel failed: exited abnormally with code 1`.
8181+ - Non-fatal, but indicates a missing tunnel endpoint.
8282+8383+## Suggested Improvements (Optional)
8484+To avoid manual recovery after crashes:
8585+1. **Crash monitor should run `aesthetic-backend` after restart.**
8686+2. Or **auto-connect a terminal client** (`emacsclient -t`) after daemon start.
8787+3. Add a lightweight sanity check:
8888+ - If no tabs beyond `*scratch*`, trigger `aesthetic-backend` automatically.
8989+9090+## Quick Reference
9191+- Main config: [dotfiles/dot_config/emacs.el](dotfiles/dot_config/emacs.el)
9292+- Daemon start: [.devcontainer/config.fish](.devcontainer/config.fish)
9393+- Crash monitor: [monitor-emacs.sh](monitor-emacs.sh)
9494+- Debug log: [.emacs-logs/emacs-debug.log](.emacs-logs/emacs-debug.log)
9595+- Crash diary: [.emacs-logs/crashes.log](.emacs-logs/crashes.log)