Portability Survey — 2026-04-16 #

Catalog of hardcoded paths, user-specific constants, and binary dependencies that block running reverie on a clean Debian/Ubuntu/WSL2 box with a different username.

Inventory #

Minimum Viable Port #

Five smallest changes that unblock a fresh-box install with a different username:

1. Export COORD_ROOT from reveried/meshctl

   • Change: In meshctl-tui/src/lib.rs, reverie-status-tui/src/data.rs, and shell hooks: read COORD_ROOT env var (default /tmp/claude-coord)
   • Impact: Allows users to override the coordination directory on first startup
   • Files: meshctl-tui/src/lib.rs, reverie-status-tui/src/data.rs, reverie-lock/src/lib.rs, scripts/mesh/worker-lifecycle-hook.sh, scripts/mesh/file-lock-gate-hook.sh

2. Fix HOME fallback in sleeper_rebound.rs

   • Change: Line 265, change unwrap_or_else(|_| "/home/ctodie".into()) to panic or use only env var
   • Impact: Prevent silent use of wrong home directory; fail explicitly if HOME is unset
   • Files: crates/reveried/src/sleeper_rebound.rs

3. Make anchor tmux session configurable

   • Change: Add REVERIE_ANCHOR_SESSION env var (default reverie-anchor)
   • Impact: Allow teams to use different anchor session names
   • Files: crates/meshctl/src/main.rs, crates/meshctl/src/roles.rs

4. Use ~ in systemd unit for engram binary

   • Change: Line 12 in ops/systemd/user/reveried.service, replace /home/ctodie/.local/bin/engram with %h/.local/bin/engram (systemd expands %h to home)
   • Impact: Makes systemd unit portable; no hardcoded username
   • Files: ops/systemd/user/reveried.service

5. Fix anchor-offload.sh hardcoded openrouter path

   • Change: Line 97, replace /home/ctodie/.local/bin/openrouter-call with $HOME/.local/bin/openrouter-call
   • Impact: Respects $HOME environment variable
   • Files: scripts/anchor-offload.sh

Non-goals #

These are explicitly out of scope:

• Email addresses, GPG keys, GitHub accounts — project metadata. Users should fork/rebrand as needed.
• Entity aliases (“ctodie”, “chris”) — part of the test/benchmark fixtures. Not runtime-critical.
• Default project in bench/smoke tests — fixtures can be parameterized per test invocation.
• Signed commits — pre-commit hook can be disabled with --no-verify if GPG key is unavailable.
• Worktree naming scheme — reverie-wt-{role} is a documented convention; keep it.

Risks & Open Questions #

1. Coord root migration: Changing COORD_ROOT requires killing all running coord sessions. Should this be a one-time init step or auto-migrated?

2. Lock semantics: /tmp/claude-coord assumes Unix tmpfs. On Windows WSL2, /tmp is shared with host; could cause collisions if multiple WSL instances run reverie. Consider $XDG_RUNTIME_DIR or user-scoped subdirectory.

3. Systemd %h support: Verify %h expansion works in Type=simple services on all target distros (Debian 11+, Ubuntu 20.04+).

4. Fallback for missing HOME: sleeper_rebound.rs, meshctl, and reverie-lock all have /home/ctodie fallbacks. Panic or use /root when HOME is unset? Recommend panic (fail-fast).

5. Logging directory: /tmp/anchor-offload.log, /tmp/coord-heartbeat-keeper.log are hardcoded. Consider moving to $HOME/.local/state/reverie/ (per systemd state directory best practice).

6. Multi-user scenarios: If multiple users run reverie on the same box, shared /tmp/claude-coord will cause conflicts. Consider scoping to $UID or $XDG_RUNTIME_DIR (which is already per-user).

Implementation Priority #

• P0 (blocking): Export COORD_ROOT (#1), fix HOME fallback (#2), make anchor session configurable (#3).
• P1 (usability): Systemd unit portability (#4), anchor-offload.sh (#5).
• P2 (future): Multi-user isolation, logging directory standardization, worktree path detection.

Generated by portability survey (TOD-729). Last updated: 2026-04-16.