garden: derive instance identity from checkout location, mirror home, per-user image

The launcher keyed the container name off the mutable .garden shard file while the
bind mount used a fixed /home/<user> path. The decoupling let a container strand
under a name matching no checkout (the "lost container"), and the host<->container
path mismatch (-v $SCRIPT_DIR:/home/kris) made git canonicalize journal-worktree
paths to a bind-mount source that did not exist inside the container, corrupting
the journal worktree on every op.

Identity is now derived purely from the checkout's canonical path
(<hostname>-<basename>-<hash8>), pinned into --name/--hostname at creation, so it
is collision-free, stable, and self-healing; the .garden file and GARDEN env knob
are gone (common.sh resolves via its hostname -s fallback). The checkout is
bind-mounted at its own host path and the bot user's home is relocated to match
(entrypoint usermod -d, launcher GARDEN_HOME), so an absolute path denotes the
same file inside the container and out -- which also fixes the journal-worktree
corruption. The container's unix user (name + uid) is baked per-build to match the
host user, tagging the image per-user (garden-<user>); nothing is pinned to one
account. Adds a `create` subcommand for headless bring-up.

Verified: two concurrent instances (endolin-garden, endolin-garden2) with mirrored
homes, correct GARDEN/GARDEN_ROOT, idempotent re-attach, and a clean git worktree
add whose gitdir target exists in-container.

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

Author: endolinbot

CLAUDE.md

@@ -79,7 +79,7 @@ Create `skills/<name>/SKILL.md`. Sections: purpose, inputs, state (if any), proc
 
 ## Host environment
 
-The garden lives in the bot user's home directory; that directory is what `<garden-root>` refers to throughout this document. Each host has a logical **`GARDEN` identity** — the shard name that keys job claims, per-host worker counts, journal index entries, and the leader marker, and **must be unique across running instances**. Its resolution order (`GARDEN` env → the gitignored `<garden-root>/.garden` file → `hostname -s`), the `.garden` naming knob, why an exported env var does not reach the `--user` units, and the container-rename move all live in [context/first-run/identity.md](context/first-run/identity.md).
+The garden lives in the bot user's home directory; that directory is what `<garden-root>` refers to throughout this document, and the container **mirrors** it — the checkout is bind-mounted at its own host path and the bot user's home is relocated to match, so an absolute path denotes the same file inside the container and out. Each instance has a logical **`GARDEN` identity** — the shard name that keys job claims, per-host worker counts, journal index entries, and the leader marker, and **must be unique across running instances**. That identity is **derived from the checkout's location**, `<hostname>-<basename>-<hash8>` of the canonical path, and pinned into the container's `--name`/`--hostname` at creation; the fleet reads it back through `common.sh`'s `hostname -s` fallback. There is no `.garden` file or `GARDEN` env knob to set — distinct directories yield distinct instances automatically, and the only cross-instance requirement the human must ensure is that **hosts have unique short hostnames**. The derivation, the multi-instance recipe, and the expert overrides live in [context/first-run/identity.md](context/first-run/identity.md). The container's unix user matches the **host** user (name + uid, baked per-build), so nothing is pinned to one maintainer's account.
 
 Each host configures its bot identity once in the garden repo's local git config:
 

Dockerfile

@@ -9,12 +9,14 @@
 # recipe (privileged, writable cgroup mount, tmpfs at /run and /tmp,
 # STOPSIGNAL SIGRTMIN+3 — supplied by the `garden` launcher script).
 #
-# Identity: runs as user `kris` (uid 1000) and uses whatever ssh / gh
-# credentials are present in the bind-mounted /home/kris. The bot's git
-# identity (e.g. endolinbot / kriscendobot) is the repo-local git config,
-# not a separate unix user. The per-host logical name must be UNIQUE
-# across garden instances (see CLAUDE.md § Job system) and is fixed at
-# container creation via the launcher's --hostname.
+# Identity: runs as a unix user matching the HOST user (name + uid, via
+# --build-arg USERNAME/USER_UID) and uses whatever ssh / gh credentials are
+# present in the bind-mounted home. The container home is relocated at runtime
+# to mirror the checkout's host path (entrypoint `usermod -d`, launcher
+# GARDEN_HOME). The bot's git identity (a bot login) is the repo-local git config,
+# not a separate unix user. The per-host logical name is
+# the location-derived instance id (<hostname>-<basename>-<hash>), unique across
+# instances and fixed at container creation via the launcher's --hostname.
 
 FROM ubuntu:24.04
 
@@ -23,6 +25,17 @@ ARG GO_VERSION=1.23.6
 ARG DOTFILES_REPO=https://github.com/kriskowal/dotfiles.git
 ARG VUNDLE_REPO=https://github.com/VundleVim/Vundle.vim.git
 
+# The unix user is baked to match the HOST user running ./garden (name + uid),
+# passed by the launcher's cmd_build. Nothing is hardcoded to one maintainer's
+# account, and the launcher tags the image per-user (garden-<user>) so builds
+# don't drift or collide across users. (USERNAME is first USED at the useradd
+# step far below, so declaring it here does not invalidate the expensive apt /
+# node / go layers; GARDEN_USER is exported as an ENV late, for the same reason.)
+# Neutral defaults (never the maintainer's account); the launcher always passes
+# the real host user via --build-arg, so these apply only to a bare `docker build`.
+ARG USERNAME=bot
+ARG USER_UID=1000
+
 ENV DEBIAN_FRONTEND=noninteractive
 
 # systemd + dbus + base packages.
@@ -114,21 +127,23 @@ RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
 RUN npm install -g @anthropic-ai/claude-code \
     && command -v claude
 
-# Create kris user with uid 1000 to match the host user so the
-# bind-mounted home stays writable.
+# Create the bot user matching the HOST user (name + uid, from --build-arg) so the
+# bind-mounted home stays writable and nothing is pinned to one account. Ubuntu
+# 24.04 ships a default `ubuntu` user at uid 1000; remove it first so USER_UID
+# (often 1000) is free.
 RUN userdel -r ubuntu 2>/dev/null || true \
-    && useradd -m -s /bin/bash -u 1000 -G sudo kris \
-    && echo 'kris ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+    && useradd -m -s /bin/bash -u "${USER_UID}" -G sudo "${USERNAME}" \
+    && echo "${USERNAME} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 # Dotfiles in /opt so the bind mount can't mask them.
 RUN git clone "${DOTFILES_REPO}" /opt/dotfiles \
-    && chown -R kris:kris /opt/dotfiles
+    && chown -R "${USERNAME}:${USERNAME}" /opt/dotfiles
 
 # Vundle + plugins.
-USER kris
+USER ${USERNAME}
 RUN git clone "${VUNDLE_REPO}" /opt/dotfiles/vim/bundle/Vundle.vim \
-    && ln -sfn /opt/dotfiles/vim    /home/kris/.vim \
-    && ln -sfn /opt/dotfiles/.vimrc /home/kris/.vimrc \
+    && ln -sfn /opt/dotfiles/vim    "/home/${USERNAME}/.vim" \
+    && ln -sfn /opt/dotfiles/.vimrc "/home/${USERNAME}/.vimrc" \
     && vim -E -u /opt/dotfiles/.vimrc -i NONE \
          -c 'set nomore' \
          -c 'PluginInstall' \
@@ -145,7 +160,7 @@ RUN printf '%s\n' \
     'export PATH="$HOME/bin:$HOME/go/bin:/opt/go-tools/bin:/usr/local/go/bin:$PATH"' \
     > /etc/profile.d/garden.sh
 
-ENV PATH="/home/kris/bin:/home/kris/go/bin:${PATH}"
+ENV PATH="/home/${USERNAME}/bin:/home/${USERNAME}/go/bin:${PATH}"
 
 # Mask systemd units that don't make sense in a container (they would
 # otherwise fail noisily on boot).
@@ -160,12 +175,18 @@ RUN systemctl mask \
         getty-static.service \
     || true
 
-# Enable lingering for kris so systemd starts user@1000.service at boot,
-# which brings up the user-mode garden-* units (installed by
+# Enable lingering for the bot user so systemd starts its user@<uid>.service at
+# boot, which brings up the user-mode garden-* units (installed by
 # scripts/jobs/install-units.sh into ~/.config/systemd/user/) without a
 # logged-in session. This is the headless prerequisite the CLAUDE.md
 # startup procedure relies on.
-RUN mkdir -p /var/lib/systemd/linger && touch /var/lib/systemd/linger/kris
+RUN mkdir -p /var/lib/systemd/linger && touch "/var/lib/systemd/linger/${USERNAME}"
+
+# Bake the bot user's name so the runtime entrypoint (which relocates this user's
+# home to the mirrored checkout path) knows it without a hardcoded account.
+# Declared LATE, after the expensive apt/node/go layers, so it never invalidates
+# their cache.
+ENV GARDEN_USER=${USERNAME}
 
 # Entrypoint links dotfiles and prepares the user-systemd dir before
 # exec'ing systemd as PID 1.
@@ -175,11 +196,11 @@ RUN chmod +x /usr/local/bin/garden-entrypoint
 # systemd's clean-shutdown signal.
 STOPSIGNAL SIGRTMIN+3
 
-# PID 1 is systemd (entrypoint runs as root, its domain); the garden
-# units run as user kris via the user@1000 manager. Interactive access is
-# `docker exec -it -u kris ... bash -l` (the `garden` launcher does this) —
-# entering as kris, not root, so the session uses kris's gh/ssh credentials
+# PID 1 is systemd (entrypoint runs as root, its domain); the garden units run
+# as the bot user via its user@<uid> manager. Interactive access is
+# `docker exec -it -u <hostuser> ... bash -l` (the `garden` launcher does this) —
+# entering as the bot user, not root, so the session uses its gh/ssh credentials
 # and drives `systemctl --user` directly without sudo.
-WORKDIR /home/kris
+WORKDIR /home/${USERNAME}
 ENTRYPOINT ["/usr/local/bin/garden-entrypoint"]
 CMD ["/lib/systemd/systemd"]

context/first-run/identity.md

@@ -4,73 +4,82 @@ Every garden instance has one logical name — its **`GARDEN` shard identity** 
 and it **must be unique across every running instance you own**. It keys job
 claims, per-host worker counts (`hosts/<host>`), journal index entries, and the
 leader marker; two instances sharing a name silently corrupt each other's
-per-host state. This page is the naming knob and the uniqueness discipline: the
-`.garden` file as the one place the name lives, `GARDEN=… ./garden` as sugar
-over it, why an exported env var does not reach the fleet, and the rename /
-parallel-pool moves. If your question is "how do I name this instance" or "these
-two instances are stepping on each other," you are in the right place; the
-multi-host leader/follower mechanics that the marker gates are
+per-host state. The good news: you no longer set this name by hand. It is
+**derived from where the checkout lives**, so it is unique by construction and
+cannot drift. This page explains that derivation and how to run several
+instances; the multi-host leader/follower mechanics that the marker gates are
 `../operations/leader-follower.md`.
 
-## The one naming knob: `.garden`
+## Identity is the checkout's location
 
-The streamlined, preferred way to name an instance is one line **before the
-first `./garden`**:
+The launcher computes the identity at container creation from the checkout's
+canonical path:
 
-```sh
-echo petunias > .garden
 ```
+<hostname>-<basename>-<hash8>          e.g.  endolin-garden2-5bcdff64
+```
+
+- **`hostname`** — the host's short hostname, so instances on different hosts
+  never collide in the shared journal.
+- **`basename`** — the checkout directory's own name, the human-readable middle.
+- **`hash8`** — the first 8 hex of the SHA-256 of the full canonical path, which
+  disambiguates same-named directories at different paths on one host (e.g.
+  `/srv/a/garden` vs `/srv/b/garden`).
+
+There is **no `.garden` file and no environment knob** to seed, edit, or forget.
+Because the id is a pure function of location and is pinned into the container's
+`--name` and `--hostname` at creation, it can never drift away from the container
+afterward — the failure that used to strand a container under a name matching no
+checkout is now structurally impossible.
 
-The launcher reads `.garden` when present and derives the container name and
-`--hostname` from it. Bare `./garden` needs **no environment variables** — every
-default is satisfactory, and an unnamed instance falls back to the container
-hostname. You only name an instance when you run **more than one**.
+## Running more than one instance
 
-The convenience form does the same thing through an env var:
+Put each instance in **its own directory**. Distinct paths yield distinct ids,
+distinct containers, and distinct (mirrored) homes automatically:
 
 ```sh
-GARDEN=petunias ./garden
+# two collaborating instances on one host — nothing to name:
+( cd ~/garden  && ./garden create )    # -> <host>-garden-<hashA>
+( cd ~/garden2 && ./garden create )    # -> <host>-garden2-<hashB>
 ```
 
-This sets the container hostname **and** writes `.garden`, so the container is
-built and named from that identity either way. The env var is **sugar over the
-file**, and the file is the documented default. `GARDEN_CONTAINER` /
-`GARDEN_HOSTNAME` remain as expert overrides; `GARDEN_SHARD` is a deprecated
-alias for `GARDEN` for one release.
+The container **home is mirrored** to the checkout's own host path (e.g. a
+checkout at `/srv/garden2` has `$HOME` = `/srv/garden2` inside the container), so
+an absolute path means the same thing inside the container and out, and each
+instance's credentials live in its own `.ssh` / `.config/gh` under that path.
 
 ## How the fleet resolves the identity
 
 Every fleet script resolves `GARDEN` as: **`GARDEN` env → the gitignored
-`.garden` file → `hostname -s`** (`common.sh`). The durable file exists because
-an **exported `GARDEN` does not reach the systemd `--user` units** — they are
-started by the user manager, not your shell, so they read the file, not your
-environment. That is the whole reason the name is written to disk rather than
-left in the environment: set it at container-creation time so it lands in
-`.garden`, and every unit sees it.
+`.garden` file → `hostname -s`** (`common.sh`). With the location-derived scheme
+there is no `.garden` file, so resolution lands on **`hostname -s`** — and the
+launcher has pinned the container's `--hostname` to the computed instance id, so
+every systemd `--user` unit sees exactly that id without any environment
+plumbing. (An exported `GARDEN` still does not reach the `--user` manager; that
+is why the id rides `--hostname` instead.)
 
 ## The uniqueness check (the human's one answer)
 
-The kernel hostname cannot be changed from inside a container (its capabilities
-are zero), so the logical name is **fixed at container creation** via
-`--hostname`/`--name` (both `GARDEN_CONTAINER`). During the tutorial the liaison
-reads `.garden` and asks the single question only the human can answer: **"is
-this name unique among your running garden instances?"** A default or a
-collision is the only thing that needs fixing here.
+Within a host, uniqueness is automatic (distinct paths → distinct ids). The one
+thing only you can guarantee is that your **hosts have distinct short
+hostnames** — the cross-host tiebreaker in the shared journal. If two hosts share
+a hostname, give one a distinct hostname (or use `GARDEN_HOSTNAME`, below) before
+standing up the second.
 
-## Rename, and the parallel-pool move
+## Rename, and expert overrides
 
-To **rename** an existing instance, reset and re-create it under the new name:
+To **rename** an instance, move (or re-clone) the checkout to a new path and
+re-create the container; the id follows the new location:
 
 ```sh
-./garden reset
-echo <unique-name> > .garden   # or: GARDEN=<unique-name> ./garden
-./garden
+./garden reset          # remove the old container
+# move the checkout to its new path, then:
+./garden                # re-create — new path yields the new id
 ```
 
-For a **lighter, per-invocation** identity — a second follower pool on the same
-machine, launched from a checked-out worktree with no Dockerfile change — just
-export `GARDEN=<unique>` for that invocation. Set `GARDEN` at creation only when
-a pool's identity must differ from its hostname.
+`GARDEN_CONTAINER` and `GARDEN_HOSTNAME` remain expert overrides for the rare
+case where the container name or logical id must differ from the location-derived
+default (e.g. two hosts that unavoidably share a short hostname).
 
-Rationale for the container/hostname coupling and the resolution order lives in
+Rationale for the location-derived scheme and the home mirroring lives in
 `CLAUDE.md` § Host environment; this page is the operator's how-to.

entrypoint.sh

@@ -3,12 +3,16 @@
 #
 # Runs as root inside the garden container. Before handing PID 1 to
 # systemd it:
-#   1. Symlinks dotfiles from /opt/dotfiles into /home/kris.
-#   2. Prepares /home/kris/.config/systemd/user/ owned by kris, so
+#   1. Relocates the bot user's home to the mirrored checkout path (GARDEN_HOME).
+#   2. Symlinks dotfiles from /opt/dotfiles into that home.
+#   3. Prepares <home>/.config/systemd/user/ owned by the bot user, so
 #      `systemctl --user enable` (run later by scripts/jobs/install-units.sh)
 #      can write its default.target.wants/ links and the units survive a
 #      container restart.
-#   3. exec's "$@" (the CMD, /lib/systemd/systemd).
+#   4. exec's "$@" (the CMD, /lib/systemd/systemd).
+#
+# The bot user's name is baked into the image (ENV GARDEN_USER, = the host user)
+# and read here so nothing is pinned to one account.
 #
 # Note: the garden units carry an @GARDEN_ROOT@ placeholder and must be
 # RENDERED into ~/.config/systemd/user/ by scripts/jobs/install-units.sh
@@ -19,7 +23,25 @@
 set -e
 
 DOTFILES=/opt/dotfiles
-HOME_DIR=/home/kris
+# The bot user, baked to match the host user (Dockerfile ARG USERNAME → ENV
+# GARDEN_USER). If the env is somehow absent, fall back to the first real
+# (uid >= 1000) account in the image rather than a guessed literal, so we never
+# target a nonexistent user and abort PID-1 boot.
+GARDEN_USER="${GARDEN_USER:-$(getent passwd | awk -F: '$3>=1000 && $3<65534 {print $1; exit}')}"
+
+# Home is MIRRORED to the checkout's host path when the launcher passes
+# GARDEN_HOME (a bind mount lives at that same path). Relocate the bot user's home
+# in /etc/passwd to it — no -m, since the bind mount already provides the directory
+# — so $HOME, the login shell, and the systemd --user manager all agree on the
+# mirrored path. Absolute paths then mean the same thing inside the container and
+# on the host. Done here, as root, before systemd (PID 1) starts and while the bot
+# user still has no running process. Guarded on the user existing so a misresolved
+# name can never crash boot. Absent GARDEN_HOME, home stays as built.
+HOME_DIR="${GARDEN_HOME:-$(getent passwd "$GARDEN_USER" | cut -d: -f6)}"
+if [ -n "${GARDEN_HOME:-}" ] && getent passwd "$GARDEN_USER" >/dev/null \
+   && [ "$(getent passwd "$GARDEN_USER" | cut -d: -f6)" != "$HOME_DIR" ]; then
+    usermod -d "$HOME_DIR" "$GARDEN_USER"
+fi
 SYSTEMD_USER_DIR="${HOME_DIR}/.config/systemd/user"
 
 link_if_safe() {
@@ -40,15 +62,15 @@ if [[ -d "$DOTFILES" ]]; then
     link_if_safe "$DOTFILES/zshrc"         "$HOME_DIR/.zshrc"
     mkdir -p "$HOME_DIR/.config/git"
     link_if_safe "$DOTFILES/git/.gitconfig" "$HOME_DIR/.config/git/config"
-    chown -h kris:kris \
+    chown -h "$GARDEN_USER:$GARDEN_USER" \
         "$HOME_DIR/.bashrc" "$HOME_DIR/.bash_profile" "$HOME_DIR/.vimrc" \
         "$HOME_DIR/.vimrc.local" "$HOME_DIR/.vim" "$HOME_DIR/.tmux.conf" \
         "$HOME_DIR/.tigrc" "$HOME_DIR/.zshrc" "$HOME_DIR/.config/git/config" \
         2>/dev/null || true
 fi
 
-# Prepare the user-systemd tree (must be kris-owned for `--user enable`).
+# Prepare the user-systemd tree (must be owned by the bot user for `--user enable`).
 mkdir -p "$SYSTEMD_USER_DIR"
-chown -R kris:kris "$HOME_DIR/.config/systemd" 2>/dev/null || true
+chown -R "$GARDEN_USER:$GARDEN_USER" "$HOME_DIR/.config/systemd" 2>/dev/null || true
 
 exec "$@"