Sessions (#217)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: binarypie

dot_files/devcube/Containerfile

@@ -258,27 +258,33 @@ RUN mkdir -p /etc/profile.d /etc/fish/conf.d \
 # =============================================================================
 # LAYER 14: Bake the Neovim configuration + pre-install plugins
 # =============================================================================
-# The full LazyVim config is baked into $HOME/.config/nvim. Personal overrides
-# are bind-mounted at runtime from the host (~/.config/hypercube/nvim) and
-# layered on top via the runtimepath (see lua/config/lazy.lua).
+# The full LazyVim config is baked into a PRISTINE, non-volume path under
+# /usr/share/hypercube/config. The entrypoint syncs it into $HOME/.config/nvim
+# on every start, so config updates ship with the image instead of going stale
+# on the persisted (copy-up-seeded) home volume. Personal overrides are
+# bind-mounted at runtime from the host (~/.config/hypercube/nvim) and layered
+# on top via the runtimepath (see lua/config/lazy.lua).
 # NOTE: the build context is dot_files/, so the nvim config lives under nvim/.
-COPY nvim/config/ /root/.config/nvim/
+COPY nvim/config/ /usr/share/hypercube/config/nvim/
 
 # Pre-install all plugins + build treesitter parsers so first launch is fast and
-# offline. HOME=/root and PATH already include the brew nvim binary.
-RUN nvim --headless "+Lazy! sync" +qa
+# offline. Point nvim at the pristine config via XDG_CONFIG_HOME; plugins still
+# land in stdpath('data') = /root/.local/share/nvim, which IS on the home volume
+# (seeded via copy-up on first run, matching the baked lazy-lock.json).
+RUN XDG_CONFIG_HOME=/usr/share/hypercube/config nvim --headless "+Lazy! sync" +qa
 
 # =============================================================================
 # LAYER 14b: Bake the shell / multiplexer / orchestrator configs
 # =============================================================================
 # fish + starship give a good in-container shell/prompt; zellij + workmux drive
-# the parallel-agent workflow. These seed into the persisted home volume on
-# first run (podman copy-up), like the nvim config above. starship.toml lands at
-# the exact path dot_files/fish/config.fish hardcodes for STARSHIP_CONFIG, so
-# fish needs no edits (and it lives outside /root, so it's always present).
-COPY fish/     /root/.config/fish/
-COPY zellij/   /root/.config/zellij/
-COPY workmux/  /root/.config/workmux/
+# the parallel-agent workflow. Like the nvim config above, these are baked into
+# the pristine /usr/share/hypercube/config path and synced into $HOME/.config by
+# the entrypoint on every start (so config updates ship with the image rather
+# than going stale on the home volume). starship.toml already lives here at the
+# exact path dot_files/fish/config.fish hardcodes for STARSHIP_CONFIG.
+COPY fish/     /usr/share/hypercube/config/fish/
+COPY zellij/   /usr/share/hypercube/config/zellij/
+COPY workmux/  /usr/share/hypercube/config/workmux/
 COPY starship/ /usr/share/hypercube/config/starship/
 
 # Make fish root's login shell so every interactive shell in the container

dot_files/devcube/Justfile

@@ -6,6 +6,8 @@
 local_image := "localhost/devcube"
 remote_image := "ghcr.io/binarypie-dev/devcube:latest"
 # Throwaway volumes so local testing never touches the real per-project state.
+# Passing DEVCUBE_VOLUME explicitly forces this single fixed home volume instead
+# of the wrapper's per-project derivation, keeping local testing predictable.
 test_volume := "hypercube-devcube-test"
 test_wt_prefix := "devcube-wt-test"
 
@@ -80,6 +82,11 @@ test-build: build
     # The entrypoint must pin $SHELL to fish so workmux drops new worktrees into
     # fish (its default-shell fallback is /bin/sh otherwise).
     podman run --rm {{local_image}} sh -c '[ "$SHELL" = "$(command -v fish)" ]'
+    # Baked config lives at the pristine path, NOT under /root (the home volume),
+    # so config updates ship with the image instead of going stale on the volume.
+    podman run --rm --entrypoint sh {{local_image}} -c 'for c in nvim fish zellij workmux; do test -d /usr/share/hypercube/config/$c || exit 1; done && ! test -e /root/.config/nvim'
+    # ...and the entrypoint syncs it into /root/.config on every start.
+    podman run --rm {{local_image}} sh -c 'test -d /root/.config/nvim && test -f /root/.config/fish/config.fish && test -d /root/.config/zellij && test -d /root/.config/workmux'
     @echo ""
     @echo "All tests passed!"
 

dot_files/devcube/README.md

@@ -42,8 +42,10 @@ Linux desktop, a remote box, and macOS — no distrobox required.
 | `devc codex`      | OpenAI Codex CLI, run directly |
 | `devc agy`        | Antigravity CLI, run directly |
 
-All entry points share one home volume, so an AI login from any of them works in
-all of them.
+Within a project, all entry points share that project's home volume, so an AI
+login from any of them works in all of them. The home volume is **per-project**
+(derived from the launch path), so logins and state never leak between
+workspaces — you log in once per project.
 
 ### Parallel agents
 
@@ -88,17 +90,20 @@ only what's needed. The mounts:
 
 | Mounted in | Purpose |
 |---|---|
-| named volume `hypercube-devcube-home` → `/root` | plugin/mason updates, sessions, shada, **and AI-CLI auth** — seeded from the image on first run, persisted after |
+| per-project volume `hypercube-devcube-home-<proj>-<hash>` → `/root` | plugin/mason updates, sessions, shada, **and AI-CLI auth** — seeded from the image on first run, persisted after; one per project so creds never leak between workspaces |
 | current directory | the project you're editing |
 | per-project volume `devcube-wt-<proj>-<hash>` → `/worktrees` | worktrees + workmux state (orchestrators only) |
 | `~/.config/hypercube/nvim` | **your** plugin overrides, layered on top of the baked config |
 | `~/.gitconfig` (ro) | commit identity |
 | `$SSH_AUTH_SOCK` (Linux) | SSH agent for git/gh |
 
-Everything else (the LazyVim config, plugins, AI CLIs, zellij/workmux/fish/
-starship config) lives in the image. The container runs as `--user 0:0` so files
-you edit are owned by your host user under rootless podman. Multiple sessions run
-concurrently.
+The AI CLIs and nvim plugins live in the image and seed onto the home volume on
+first run. The **baked config** (LazyVim, zellij, workmux, fish, starship) is
+image-owned: it's stored at a pristine path and synced into `/root/.config` by
+the entrypoint on **every** start, so config updates ship with `podman pull` —
+no volume reset needed (plugin *version* bumps still want `:Lazy update`). The
+container runs as `--user 0:0` so files you edit are owned by your host user
+under rootless podman. Multiple sessions run concurrently.
 
 Clipboard uses **OSC 52** through the terminal, so yank/paste works locally
 (Ghostty) and over SSH without forwarding a Wayland/pbcopy socket.
@@ -114,8 +119,8 @@ devc nvim file.rs      # ...or just the editor
 | Command | Description |
 |---------|-------------|
 | `ujust devcube-setup`   | pull image + install the `devc` wrapper |
-| `ujust devcube-upgrade` | pull the latest image + refresh the wrapper |
-| `ujust devcube-reset`   | drop the home volume to re-seed (clears plugin state + AI logins); optionally prune per-project worktree volumes |
+| `ujust devcube-upgrade` | pull the latest image + refresh the wrapper (baked config refreshes itself on next launch) |
+| `ujust devcube-reset`   | drop all per-project home volumes to re-seed (clears plugin state + AI logins); optionally prune per-project worktree volumes |
 | `ujust devcube-shell`   | debug shell inside a throwaway container |
 
 ## Setup (macOS / any podman host)

dot_files/devcube/devcube-session.sh

@@ -15,19 +15,57 @@
 # interpreted as "add these tabs to the (not-yet-existing) session" and zellij
 # errors with "There is no active session!". The flag that always starts a fresh
 # named session with a layout is --new-session-with-layout, used below.
+#
+# Recovering from an unsaved exit. The home volume (/root) outlives any single
+# `--rm` container, but the live zellij socket lives in the container's
+# ephemeral /tmp. If a devcube is torn down WITHOUT going through Ctrl+Space q
+# (the terminal/container is just killed), the socket dies with the container
+# while a stale scrap of session state can linger on the persisted volume. zellij
+# then refuses to reopen that name -- "session ... already exists, but is dead" --
+# and the next `devc` wedges instead of recovering. So when no usable session of
+# this name is left to attach to, we clear any dead remnant before creating a
+# fresh one (see below). Cleanly saved sessions still resurrect; only the wedged
+# leftovers get cleared.
 set -euo pipefail
 
 session="$1"
 layout="${2:-}"
 
-# A session of this name already exists (running or serialized/resurrectable)?
-# `list-sessions` prints the name as the first field for both; awk matches it
-# exactly. With no sessions it errors to stderr (suppressed) and prints nothing.
-if zellij list-sessions --no-formatting 2>/dev/null |
-	awk -v s="$session" '$1 == s { found = 1 } END { exit !found }'; then
-	exec zellij attach "$session"
-elif [ -n "$layout" ]; then
-	exec zellij --session "$session" --new-session-with-layout "$layout"
+# The zellij binary, overridable so the logic can be exercised by tests with a
+# stub on this seam (see scripts/devcube/test-devcube-session.sh). Defaults to
+# the real `zellij` on PATH in the container.
+zellij_bin="${ZELLIJ_BIN:-zellij}"
+
+# Does a session of this name currently exist that we can attach to -- either
+# running, or serialized/resurrectable (left by Ctrl+Space q -> Save, or by the
+# periodic snapshot of a session we never cleanly closed)? `list-sessions` prints
+# the name as the first field for both kinds, tagging the resurrectable ones; awk
+# matches the name exactly. With no sessions it errors to stderr (suppressed) and
+# prints nothing, so awk finds no match.
+session_attachable() {
+	"$zellij_bin" list-sessions --no-formatting 2>/dev/null |
+		awk -v s="$session" '$1 == s { found = 1 } END { exit !found }'
+}
+
+if session_attachable; then
+	# Running -> reattach; serialized -> resurrect. `attach` does both, restoring
+	# the saved tabs / panes / worktrees. --force-run-commands re-runs the
+	# serialized command panes (claude, nvim, ...) immediately instead of parking
+	# them behind zellij's "Press ENTER to run" banner, so a resumed devcube comes
+	# back live. (No-op when merely reattaching to a still-running session.)
+	exec "$zellij_bin" attach "$session" --force-run-commands
+fi
+
+# Nothing attachable by this name. A session killed uncleanly (container torn
+# down without Ctrl+Space q) can still leave a *dead* remnant that list-sessions
+# won't surface yet `zellij --session NAME` trips over with "already exists, but
+# is dead" -- the wedged state that breaks the next `devc`. Clear any such remnant
+# first; delete-session is a harmless no-op (non-zero, swallowed) when there's
+# nothing to remove, so a truly first-run session is unaffected.
+"$zellij_bin" delete-session "$session" --force >/dev/null 2>&1 || true
+
+if [ -n "$layout" ]; then
+	exec "$zellij_bin" --session "$session" --new-session-with-layout "$layout"
 else
-	exec zellij --session "$session"
+	exec "$zellij_bin" --session "$session"
 fi

dot_files/devcube/entrypoint.sh

@@ -26,6 +26,35 @@ if [ -z "${TERM:-}" ] || ! infocmp "$TERM" >/dev/null 2>&1; then
     export TERM=xterm-256color
 fi
 
+# Refresh image-baked editor/shell/multiplexer config into the home volume on
+# every start, so config updates ship with `podman pull` instead of forcing a
+# volume wipe. Only these fully image-owned dirs are replaced; auth + state
+# (~/.local, ~/.claude, ~/.cache, plugin downloads + lazy-lock, shell history,
+# zellij session serialization) live elsewhere on the volume and are untouched.
+# rm -rf + cp -a (not rsync, which isn't installed) so files removed from the
+# image also drop from the dir. The personal nvim override (~/.config/hypercube/
+# nvim) is a different dir and is never touched.
+config_src="/usr/share/hypercube/config"
+for c in nvim fish zellij workmux; do
+    src="$config_src/$c"
+    dest="$HOME/.config/$c"
+    [ -d "$src" ] || continue
+    mkdir -p "$HOME/.config"
+    # fish writes its universal variables (set -U, e.g. fish_user_paths/colors)
+    # to $dest/fish_variables -- that's runtime STATE, not baked config, so carry
+    # it across the refresh rather than wiping it with the config dir.
+    saved=""
+    if [ "$c" = fish ] && [ -f "$dest/fish_variables" ]; then
+        saved="$(mktemp)" && cp -a "$dest/fish_variables" "$saved"
+    fi
+    rm -rf "$dest"
+    cp -a "$src" "$dest"
+    if [ -n "$saved" ]; then
+        cp -a "$saved" "$dest/fish_variables"
+        rm -f "$saved"
+    fi
+done
+
 if [ $# -eq 0 ]; then
     exec nvim
 else

dot_files/devcube/scripts/devcube.sh

@@ -14,21 +14,29 @@
 #   devc agy        -> Antigravity CLI, run directly
 #
 # Extra args after the tool are passed through (e.g. `devc nvim file.rs`,
-# `devc claude --resume`). All entry points share the same home volume, so
-# AI-CLI logins persist across them -- log in once and every tool is authed.
+# `devc claude --resume`). Within one project all entry points share that
+# project's home volume, so an AI-CLI login from any of them works in all of
+# them -- but the home volume is PER-PROJECT (derived from the launch path like
+# the worktree volume below), so creds/state never leak between workspaces.
 #
 # zellij/workmux run the parallel-agent flow: each `workmux add <branch>`
 # creates a git worktree on a PER-PROJECT named volume mounted at /worktrees,
 # so worktrees (and workmux's state) persist across restarts and never collide
-# with another project's. The project mount is the git repo root (discovered from
-# the launch dir), or the launch dir itself when not in a repo; workmux requires
-# a repo, the other tools don't. Plus your personal overrides and a few host
-# facts (git identity, SSH agent, terminal). Portable across Linux and macOS.
+# with another project's. The project itself (the git repo root, discovered from
+# the launch dir, or the launch dir when not in a repo) is mounted at /workspace
+# -- a fixed, branch-independent path that's kept out of /worktrees so it can
+# never collide with a /worktrees/<branch> linked worktree. The direct tools
+# instead get the project at its host path. workmux requires a repo, the other
+# tools don't. Plus your personal overrides and a few host facts (git identity,
+# SSH agent, terminal). Portable across Linux and macOS.
 #
 # Env overrides:
-#   DEVCUBE_IMAGE      container image (default ghcr.io/binarypie-dev/devcube:latest)
-#   DEVCUBE_VOLUME     named volume holding state + AI auth (default hypercube-devcube-home)
-#   DEVCUBE_WT_PREFIX  prefix for the per-project worktree volume (default devcube-wt)
+#   DEVCUBE_IMAGE        container image (default ghcr.io/binarypie-dev/devcube:latest)
+#   DEVCUBE_VOLUME       exact home-volume name (default: a per-project name derived
+#                        from DEVCUBE_HOME_PREFIX + the launch path). Set this to
+#                        force a single fixed volume (the test harness does this).
+#   DEVCUBE_HOME_PREFIX  prefix for the per-project home volume (default hypercube-devcube-home)
+#   DEVCUBE_WT_PREFIX    prefix for the per-project worktree volume (default devcube-wt)
 set -euo pipefail
 
 # The tool to run is the first argument; default to the workmux workspace.
@@ -45,7 +53,6 @@ nvim | claude | codex | agy | zellij | workmux)
 esac
 
 IMAGE="${DEVCUBE_IMAGE:-ghcr.io/binarypie-dev/devcube:latest}"
-VOLUME="${DEVCUBE_VOLUME:-hypercube-devcube-home}"
 OVERRIDE_DIR="$HOME/.config/hypercube/nvim"
 
 # Personal overrides are layered on top of the baked config. Ensure the dir
@@ -67,26 +74,47 @@ if [ "$TOOL" = workmux ] && [ -z "$git_root" ]; then
 	exit 1
 fi
 
+# Stable, repo-root-derived names so a project's state persists across restarts,
+# is shared no matter which subdir you launch from, and never collides with
+# another project's. cksum is available on both Linux and macOS (the wrapper
+# stays portable). Used for the per-project home volume here and the per-project
+# worktree volume + zellij session name in the orchestrator case below.
+slug="$(basename "$project_dir" | tr -c 'a-zA-Z0-9_.-' '-')"
+phash="$(printf '%s' "$project_dir" | cksum | cut -d' ' -f1)"
+
+# Home volume: PER-PROJECT by default so AI auth + state stay isolated between
+# workspaces. DEVCUBE_VOLUME forces an exact name (the test harness relies on
+# this); otherwise the name is derived from DEVCUBE_HOME_PREFIX + project, just
+# like the worktree volume.
+HOME_PREFIX="${DEVCUBE_HOME_PREFIX:-hypercube-devcube-home}"
+VOLUME="${DEVCUBE_VOLUME:-${HOME_PREFIX}-${slug}-${phash}}"
+
+# Where the project shows up inside the container. By default it's mounted at
+# its own host path (identity) so file paths line up on both sides. The
+# orchestrators override this below.
+mount_target="$project_dir"
+
 # Default: run the tool with only the project mounted. The orchestrators
 # (zellij/workmux) additionally get a per-project worktree volume + the zellij
 # backend, and run inside a zellij session.
 container_cmd=("$TOOL")
 extra=()
 case "$TOOL" in
 zellij | workmux)
-	# Stable, repo-root-derived names so a project's worktrees + workmux state
-	# persist across restarts, are shared no matter which subdir you launch from,
-	# and never collide with another project's. cksum is available on both Linux
-	# and macOS (the wrapper stays portable).
-	slug="$(basename "$project_dir" | tr -c 'a-zA-Z0-9_.-' '-')"
-	phash="$(printf '%s' "$project_dir" | cksum | cut -d' ' -f1)"
+	# Per-project worktree volume + zellij session name, from the same slug/phash
+	# computed above so a project's worktrees + workmux state persist across
+	# restarts and never collide with another project's.
 	wt_volume="${DEVCUBE_WT_PREFIX:-devcube-wt}-${slug}-${phash}"
 	# Stable, per-project zellij session name so closing the devcube (Ctrl+Space
-	# q -> Save) and reopening it resumes the SAME session. The home volume
-	# (/root) is shared across every project, so the name must be unique per
-	# project -> include phash. zellij session names can't contain '.', so the
-	# slug's dots are squashed to '-' (the volume name keeps them; it's separate).
+	# q -> Save) and reopening it resumes the SAME session. zellij session names
+	# can't contain '.', so the slug's dots are squashed to '-' (the volume names
+	# keep them; they're separate).
 	session="devcube-$(printf '%s' "$slug" | tr '.' '-')-${phash}"
+	# Mount the project at a fixed /workspace -- a stable, branch-independent path
+	# regardless of which branch the host checkout is on -- kept separate from the
+	# /worktrees volume so it never collides with a workmux /worktrees/<branch>
+	# linked worktree.
+	mount_target="/workspace"
 	extra=(
 		# Worktrees live here (podman auto-creates the volume on first mount).
 		-v "${wt_volume}:/worktrees:rw"
@@ -118,16 +146,19 @@ args=(
 	-e TERM
 	-e COLORTERM
 	"${extra[@]}"
-	# State + plugin updates + AI auth. Empty volume is seeded from the image's
-	# /root on first run (podman copy-up); never use a fixed container --name so
-	# multiple sessions can run concurrently.
+	# Per-project home volume: AI auth + plugin/state updates + shell history.
+	# Empty volume is seeded from the image's /root on first run (podman copy-up);
+	# baked config (nvim/fish/zellij/workmux) is NOT here -- the entrypoint syncs
+	# it from the image on every start so config updates ship without a wipe.
+	# Never use a fixed container --name so multiple sessions run concurrently.
 	-v "${VOLUME}:/root"
-	# The project -- the git repo root, or the launch dir when not in a repo --
-	# at the same path inside the container.
-	-v "${project_dir}:${project_dir}:rw"
+	# The project -- the git repo root, or the launch dir when not in a repo.
+	# Mounted at its host path for the direct tools, or at /workspace for the
+	# orchestrators (see mount_target above).
+	-v "${project_dir}:${mount_target}:rw"
 	# Personal plugin overrides (nested over the home volume).
 	-v "${OVERRIDE_DIR}:/root/.config/hypercube/nvim:rw"
-	-w "${project_dir}"
+	-w "${mount_target}"
 )
 
 # Read-only git identity (name/email/aliases) from the host.