From cf52de980c9e955b99b3d26a7868bf60b7ba9425 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 16:13:07 +0700
Subject: [PATCH 01/15] wt list: worktree overview, and a config-optional
 loader

---
 bin/wt               | 135 +++++++++++++++++++++++++++++++++++++++----
 test/lifecycle.sh    |  81 ++++++++++++++++++++++++++
 test/linux-alpine.sh |   3 +
 test/linux-debian.sh |   3 +
 4 files changed, 212 insertions(+), 10 deletions(-)
 create mode 100755 test/lifecycle.sh

diff --git a/bin/wt b/bin/wt
index df7fd48..4cabcd1 100755
--- a/bin/wt
+++ b/bin/wt
@@ -50,17 +50,30 @@ ctx_init() {
   mkdir -p "$STATE_DIR/logs"
 }
 
+load_config_soft() {
+  if [ -f "$CONFIG" ]; then
+    HAS_CONFIG=1
+    load_config
+    RUNNER="$(cfg_get runner compose)"
+    SERVICE="$(cfg_get compose.service app)"
+    WORKDIR="$(cfg_get compose.workdir /app)"
+    CONTAINER_PORT="$(cfg_get hooks.container_port 3000)"
+    PREPARE="$(cfg_get hooks.prepare "")"
+    BUILD="$(cfg_get hooks.build "")"
+    SERVER_CMD="$(cfg_get hooks.server "")"
+    if [ "$RUNNER" = compose ]; then need docker; fi
+  else
+    HAS_CONFIG=0
+    RUNNER=""; SERVICE=""; WORKDIR=""; CONTAINER_PORT=3000
+    PREPARE=""; BUILD=""; SERVER_CMD=""
+  fi
+}
+
 require_config() {
-  [ -f "$CONFIG" ] || die "no worktree-kit.yml at $PRIMARY — run 'wt init' in that repo"
-  load_config
-  RUNNER="$(cfg_get runner compose)"
-  SERVICE="$(cfg_get compose.service app)"
-  WORKDIR="$(cfg_get compose.workdir /app)"
-  CONTAINER_PORT="$(cfg_get hooks.container_port 3000)"
-  PREPARE="$(cfg_get hooks.prepare "")"
-  BUILD="$(cfg_get hooks.build "")"
-  SERVER_CMD="$(cfg_get hooks.server "")"
-  if [ "$RUNNER" = compose ]; then need docker; fi
+  load_config_soft
+  if [ "$HAS_CONFIG" = 0 ]; then
+    die "no worktree-kit.yml at $PRIMARY — run 'wt init' in that repo"
+  fi
 }
 
 # ---------- yaml backend ----------
@@ -265,6 +278,77 @@ expand() {
 
 worktree_paths() { git worktree list --porcelain | awk '/^worktree /{print $2}'; }
 
+# ---------- lifecycle ----------
+
+TAB="$(printf '\t')"
+
+resolve_trunk() { # prints the trunk branch name, or empty
+  _t=""
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    _t="$(local_get worktrees.trunk "")"
+    if [ -z "$_t" ]; then _t="$(cfg_get worktrees.trunk "")"; fi
+  fi
+  if [ -z "$_t" ]; then
+    _t="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')" || _t=""
+  fi
+  if [ -z "$_t" ]; then
+    if git show-ref --verify --quiet refs/heads/main; then
+      _t=main
+    elif git show-ref --verify --quiet refs/heads/master; then
+      _t=master
+    fi
+  fi
+  printf '%s\n' "$_t"
+}
+
+worktree_for_branch() { # <branch> -> path, or empty. Always exits 0.
+  git worktree list --porcelain | awk -v b="refs/heads/$1" '
+    /^worktree /{ p = $2 }
+    $1 == "branch" && $2 == b { print p; exit }
+  '
+  true
+}
+
+# One TAB-separated row per worktree: branch, slug, status, server, iso, path.
+# wt list and the picker both read this, so they cannot drift.
+worktree_rows() {
+  _trunk="$(resolve_trunk)"
+  git worktree list --porcelain | awk '
+    /^worktree /  { p = $2 }
+    /^branch /    { b = $2; sub("refs/heads/", "", b); print p "\t" b }
+    /^detached/   { print p "\t(detached)" }
+  ' | while IFS="$TAB" read -r _p _b; do
+    _s="$(slugify "$_p")"
+
+    _st=clean
+    if [ -n "$(git -C "$_p" status --porcelain 2>/dev/null)" ]; then _st=dirty; fi
+    if [ -n "$_trunk" ] && git -C "$_p" rev-parse --verify --quiet "$_trunk" >/dev/null 2>&1; then
+      _c="$(git -C "$_p" rev-list --left-right --count "$_trunk...HEAD" 2>/dev/null || printf '0\t0')"
+      _behind="$(printf '%s' "$_c" | cut -f1)"
+      _ahead="$(printf '%s' "$_c" | cut -f2)"
+      if [ "${_ahead:-0}"  -gt 0 ]; then _st="$_st +$_ahead"; fi
+      if [ "${_behind:-0}" -gt 0 ]; then _st="$_st -$_behind"; fi
+    fi
+
+    _srv="-"; _iso="-"
+    if [ "${HAS_CONFIG:-0}" = 1 ]; then
+      if [ "$RUNNER" = compose ]; then
+        _srv="$(docker ps --filter "label=wt.project=$PROJECT" --filter "label=wt.slug=$_s" \
+                  --format '{{.Label "wt.port"}}' 2>/dev/null | head -1)"
+        _iso="$(docker ps --filter "label=wt.project=$PROJECT" --filter "label=wt.slug=$_s" \
+                  --format '{{.Label "wt.isolation"}}' 2>/dev/null | head -1)"
+      elif [ -f "$STATE_DIR/$_s.pid" ]; then
+        _srv="$(cat "$STATE_DIR/$_s.port" 2>/dev/null || echo '?')"
+      fi
+    fi
+    if [ -n "$_srv" ] && [ "$_srv" != "-" ]; then _srv=":$_srv"; else _srv="-"; fi
+    if [ -z "$_iso" ]; then _iso="-"; fi
+
+    printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$_b" "$_s" "$_st" "$_srv" "$_iso" "$_p"
+  done
+  true
+}
+
 # ---------- ports ----------
 
 # lsof (macOS) -> ss (Linux) -> bind probe via ruby/python3 -> assume free.
@@ -589,6 +673,35 @@ cmd_doctor() {
   echo "ok"
 }
 
+cmd_list() {
+  load_config_soft
+  _all=0
+  for _a in "$@"; do
+    case "$_a" in
+      --all) _all=1 ;;
+      *)     die "unknown flag: $_a (wt list [--all])" ;;
+    esac
+  done
+
+  _out="BRANCH${TAB}SLUG${TAB}STATUS${TAB}SERVER${TAB}ISO${TAB}PATH
+$(worktree_rows)"
+
+  if [ "$_all" = 1 ]; then
+    for _b in $(git for-each-ref --format='%(refname:short)' refs/heads); do
+      if [ -z "$(worktree_for_branch "$_b")" ]; then
+        _out="$_out
+$_b${TAB}-${TAB}(no worktree)${TAB}-${TAB}-${TAB}-"
+      fi
+    done
+  fi
+
+  if command -v column >/dev/null 2>&1; then
+    printf '%s\n' "$_out" | column -t -s "$TAB"
+  else
+    printf '%s\n' "$_out"
+  fi
+}
+
 usage() {
   cat <<'EOF'
 wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
@@ -601,6 +714,7 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt logs [slug]         follow a server's logs
   wt localize <file...>  snapshot a personal overlay (--list / --remove)
   wt reset [slug]        clear the own-db bootstrap marker
+  wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
 EOF
@@ -622,6 +736,7 @@ case "$1" in
   logs) shift; cmd_logs "$@" ;;
   localize) shift; cmd_localize "$@" ;;
   reset) shift; cmd_reset "$@" ;;
+  list) shift; cmd_list "$@" ;;
   init) shift; cmd_init "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
   *) die "unknown command: $1 (wt --help)" ;;
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
new file mode 100755
index 0000000..a39df2a
--- /dev/null
+++ b/test/lifecycle.sh
@@ -0,0 +1,81 @@
+#!/bin/sh
+# Lifecycle command tests — git only. No docker, no YAML backend required.
+# Run directly:            ./test/lifecycle.sh
+# Or from a linux suite:   sh /src/test/lifecycle.sh
+set -eu
+
+WT="${WT:-wt}"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAILED=0
+TAB="$(printf '\t')"
+
+ok()   { printf 'ok   - %s\n' "$1"; }
+fail() { printf 'FAIL - %s\n' "$1" >&2; FAILED=1; }
+
+assert_eq() { # <expected> <actual> <label>
+  if [ "$1" = "$2" ]; then ok "$3"; else fail "$3: expected [$1] got [$2]"; fi
+}
+
+assert_contains() { # <haystack> <needle> <label>
+  case "$1" in
+    *"$2"*) ok "$3" ;;
+    *)      fail "$3: [$1] does not contain [$2]" ;;
+  esac
+}
+
+assert_missing() { # <haystack> <needle> <label>
+  case "$1" in
+    *"$2"*) fail "$3: [$1] unexpectedly contains [$2]" ;;
+    *)      ok "$3" ;;
+  esac
+}
+
+assert_fails() { # <label> <cmd...>
+  _l="$1"; shift
+  if "$@" >/dev/null 2>&1; then fail "$_l: expected nonzero exit"; else ok "$_l"; fi
+}
+
+# Creates a repo with one commit on branch `master`; sets REPO and cds into it.
+new_repo() {
+  REPO="$TMP/$1"
+  mkdir -p "$REPO"
+  cd "$REPO"
+  git init -q
+  git config user.email t@t.t
+  git config user.name t
+  git symbolic-ref HEAD refs/heads/master
+  echo hi > README.md
+  git add README.md
+  git commit -qm init
+}
+
+# ---------- Task 1: list ----------
+
+new_repo listrepo
+out="$("$WT" list)"
+assert_contains "$out" master           "list: shows the primary branch"
+assert_contains "$out" BRANCH           "list: prints a header"
+assert_missing  "$out" "MISSING"        "list: no config is not an error"
+
+git worktree add -q "$TMP/feat-one" -b feat/one
+out="$("$WT" list)"
+assert_contains "$out" "feat/one"       "list: shows a second worktree"
+assert_contains "$out" "feat_one"       "list: slug matches ctx_init derivation"
+assert_contains "$out" "clean"          "list: clean worktree reports clean"
+
+echo dirty > "$TMP/feat-one/x.txt"
+out="$("$WT" list)"
+assert_contains "$out" "dirty"          "list: dirty worktree reports dirty"
+
+git branch -q spare
+out="$("$WT" list --all)"
+assert_contains "$out" "spare"          "list --all: includes branches with no worktree"
+out="$("$WT" list)"
+assert_missing  "$out" "spare"          "list: plain list omits branchless branches"
+
+# existing commands must still refuse to run without a config
+assert_fails "run still requires config" "$WT" run -- true
+
+[ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
+echo "LIFECYCLE PASS"
diff --git a/test/linux-alpine.sh b/test/linux-alpine.sh
index 02d70e3..96bc8a5 100755
--- a/test/linux-alpine.sh
+++ b/test/linux-alpine.sh
@@ -52,4 +52,7 @@ cd /tmp/app && wt down
 wt ps | grep -q running && exit 1 || true
 # down must kill the real server, not just the sh -c wrapper
 curl -fsS -m 2 http://localhost:4321/ >/dev/null 2>&1 && exit 1 || echo "port freed — no orphan"
+
+# lifecycle commands: git only, no docker, no YAML backend
+sh /src/test/lifecycle.sh
 echo "ALPINE PASS"
diff --git a/test/linux-debian.sh b/test/linux-debian.sh
index 7f6abeb..5234948 100755
--- a/test/linux-debian.sh
+++ b/test/linux-debian.sh
@@ -75,4 +75,7 @@ cd /tmp/app && wt down
 wt ps | grep -q running && exit 1 || true
 # down must kill the real server, not just the sh -c wrapper
 curl -fsS -m 2 http://localhost:4321/ >/dev/null 2>&1 && exit 1 || echo "port freed — no orphan"
+
+# lifecycle commands: git only, no docker, no YAML backend
+sh /src/test/lifecycle.sh
 echo "DEBIAN PASS"

From 72a7bfdbce6b7ddff512513bb55a9781e0936d7f Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 16:26:35 +0700
Subject: [PATCH 02/15] load_config_soft: never require docker
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

need docker lived inside load_config_soft's config-present branch, so
any repo with a worktree-kit.yml — even one that just omits runner:,
which defaults to compose — made wt list die on a machine without the
docker CLI. That broke the premise of the lifecycle layer: those
commands need only git. Moved the check into require_config, after the
HAS_CONFIG gate, so load_config_soft genuinely never exits and the ten
pre-existing commands keep identical behavior (they all reach the check
through require_config). Added a regression test that scrubs docker
from PATH against a compose-defaulting config and asserts wt list still
works.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 bin/wt            | 2 +-
 test/lifecycle.sh | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/bin/wt b/bin/wt
index 4cabcd1..7b47511 100755
--- a/bin/wt
+++ b/bin/wt
@@ -61,7 +61,6 @@ load_config_soft() {
     PREPARE="$(cfg_get hooks.prepare "")"
     BUILD="$(cfg_get hooks.build "")"
     SERVER_CMD="$(cfg_get hooks.server "")"
-    if [ "$RUNNER" = compose ]; then need docker; fi
   else
     HAS_CONFIG=0
     RUNNER=""; SERVICE=""; WORKDIR=""; CONTAINER_PORT=3000
@@ -74,6 +73,7 @@ require_config() {
   if [ "$HAS_CONFIG" = 0 ]; then
     die "no worktree-kit.yml at $PRIMARY — run 'wt init' in that repo"
   fi
+  if [ "$RUNNER" = compose ]; then need docker; fi
 }
 
 # ---------- yaml backend ----------
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index a39df2a..860763f 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -77,5 +77,14 @@ assert_missing  "$out" "spare"          "list: plain list omits branchless branc
 # existing commands must still refuse to run without a config
 assert_fails "run still requires config" "$WT" run -- true
 
+# load_config_soft must never require docker: a compose config (the
+# default runner when `runner:` is omitted) must not stop `wt list` from
+# working when docker isn't even on PATH — only the ten pre-existing
+# commands (via require_config) may demand it.
+new_repo nodockerrepo
+printf 'hooks:\n  server: "true"\n' > worktree-kit.yml
+out="$(PATH=/usr/bin:/bin "$WT" list)"
+assert_contains "$out" master "list: works with a compose config and no docker on PATH"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 7b835c99bca48f73c250af10d1d4d4f5462b0689 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 16:41:47 +0700
Subject: [PATCH 03/15] wt new: create or adopt a branch's worktree from a path
 template

---
 bin/wt            | 91 +++++++++++++++++++++++++++++++++++++++++++++++
 test/lifecycle.sh | 42 ++++++++++++++++++++++
 2 files changed, 133 insertions(+)

diff --git a/bin/wt b/bin/wt
index 7b47511..0439b00 100755
--- a/bin/wt
+++ b/bin/wt
@@ -349,6 +349,42 @@ worktree_rows() {
   true
 }
 
+sanitize_branch() { # <branch> -> filesystem-safe
+  printf '%s' "$1" | tr -c 'A-Za-z0-9._' '_'
+}
+
+path_template() {
+  _t=""
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    _t="$(local_get worktrees.path "")"
+    if [ -z "$_t" ]; then _t="$(cfg_get worktrees.path "")"; fi
+  fi
+  if [ -z "$_t" ]; then _t='{parent}/{repo}-worktrees/{branch}'; fi
+  printf '%s\n' "$_t"
+}
+
+# {branch_raw} MUST be substituted before {branch}, or the longer token is
+# eaten by the shorter one and leaves a stray "_raw".
+expand_path() { # <template> <raw-branch>
+  _pb="$(sanitize_branch "$2")"
+  _pp="$(dirname "$PRIMARY")"
+  _pr="$(basename "$PRIMARY")"
+  printf '%s' "$1" | sed \
+    -e "s|{branch_raw}|$2|g" \
+    -e "s|{parent}|$_pp|g" \
+    -e "s|{repo}|$_pr|g" \
+    -e "s|{branch}|$_pb|g" \
+    -e "s|{home}|$HOME|g"
+}
+
+# stdout is the cd channel: a path, and nothing else.
+emit_cd() { # <path>
+  printf '%s\n' "$1"
+  if [ -z "${WT_SHELL_INTEGRATION:-}" ]; then
+    note "not cd'd — install shell integration: eval \"\$(wt shell-init zsh)\""
+  fi
+}
+
 # ---------- ports ----------
 
 # lsof (macOS) -> ss (Linux) -> bind probe via ruby/python3 -> assume free.
@@ -673,6 +709,59 @@ cmd_doctor() {
   echo "ok"
 }
 
+cmd_new() {
+  load_config_soft
+  _base=""; _start_server=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --from)   _base="${2:-}"; [ -n "$_base" ] || die "--from needs a branch or commit"; shift 2 ;;
+      --server) _start_server=1; shift ;;
+      -*)       die "unknown flag: $1 (wt new <branch> [--from <base>] [--server])" ;;
+      *)        _branch="$1"; shift ;;
+    esac
+  done
+  [ -n "$_branch" ] || die "usage: wt new <branch> [--from <base>] [--server]"
+
+  _existing="$(worktree_for_branch "$_branch")"
+  if [ -n "$_existing" ]; then
+    die "branch $_branch already has a worktree at $_existing — use: wt switch $_branch"
+  fi
+
+  _path="$(expand_path "$(path_template)" "$_branch")"
+  case "$_path" in
+    *" "*) die "worktrees.path expands to a path containing a space:
+  $_path
+wt splits unquoted strings when building compose args and host env lists, so
+worktree paths must be space-free. Change worktrees.path or the branch name." ;;
+  esac
+  if [ -e "$_path" ]; then die "$_path already exists"; fi
+
+  mkdir -p "$(dirname "$_path")"
+  if git show-ref --verify --quiet "refs/heads/$_branch"; then
+    note "adopting existing branch $_branch"
+    git worktree add "$_path" "$_branch" >&2
+  elif [ -n "$_base" ]; then
+    git worktree add -b "$_branch" "$_path" "$_base" >&2
+  else
+    git worktree add -b "$_branch" "$_path" >&2
+  fi
+
+  # Hook output goes to stderr so it cannot pollute the cd channel.
+  if [ "$HAS_CONFIG" = 1 ] && [ -n "${PREPARE:-}" ]; then
+    note "prepare: $PREPARE"
+    if ! ( cd "$_path" && "$0" run --shared -- sh -c "$PREPARE" ) >&2; then
+      die "prepare hook failed — worktree left at $_path"
+    fi
+  fi
+
+  if [ "$_start_server" = 1 ]; then
+    if [ "$HAS_CONFIG" = 0 ]; then die "--server needs worktree-kit.yml — run 'wt init'"; fi
+    ( cd "$_path" && "$0" server ) >&2 || die "server failed to start in $_path"
+  fi
+
+  emit_cd "$_path"
+}
+
 cmd_list() {
   load_config_soft
   _all=0
@@ -714,6 +803,7 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt logs [slug]         follow a server's logs
   wt localize <file...>  snapshot a personal overlay (--list / --remove)
   wt reset [slug]        clear the own-db bootstrap marker
+  wt new <branch> [--from <base>] [--server]   create a branch + worktree
   wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
@@ -736,6 +826,7 @@ case "$1" in
   logs) shift; cmd_logs "$@" ;;
   localize) shift; cmd_localize "$@" ;;
   reset) shift; cmd_reset "$@" ;;
+  new) shift; cmd_new "$@" ;;
   list) shift; cmd_list "$@" ;;
   init) shift; cmd_init "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 860763f..3c35e07 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -6,6 +6,10 @@ set -eu
 
 WT="${WT:-wt}"
 TMP="$(mktemp -d)"
+# Canonicalize: on macOS $TMPDIR lives under a symlink (/var -> /private/var),
+# but git resolves absolute paths, so exact-path assertions below would
+# otherwise compare an unresolved $TMP against wt's resolved output.
+TMP="$(cd "$TMP" && pwd -P)"
 trap 'rm -rf "$TMP"' EXIT
 FAILED=0
 TAB="$(printf '\t')"
@@ -86,5 +90,43 @@ printf 'hooks:\n  server: "true"\n' > worktree-kit.yml
 out="$(PATH=/usr/bin:/bin "$WT" list)"
 assert_contains "$out" master "list: works with a compose config and no docker on PATH"
 
+# ---------- Task 2: new ----------
+
+new_repo newrepo
+out="$("$WT" new feat/refund-flow 2>/dev/null)"
+assert_eq "$TMP/newrepo-worktrees/feat_refund_flow" "$out" \
+  "new: default template, branch sanitized for the path"
+assert_eq "0" "$(test -d "$TMP/newrepo-worktrees/feat_refund_flow"; echo $?)" \
+  "new: directory created"
+assert_contains "$(git -C "$REPO" branch --list 'feat/refund-flow')" "feat/refund-flow" \
+  "new: branch created with slashes intact"
+assert_contains "$("$WT" list)" "feat_refund_flow" "new: slug is the last path segment"
+
+# a branch that exists but has no worktree is adopted, not rejected
+git -C "$REPO" branch -q orphan
+out="$("$WT" new orphan 2>/dev/null)"
+assert_eq "$TMP/newrepo-worktrees/orphan" "$out" "new: adopts an existing branch"
+
+# a branch that already has a worktree is an error
+assert_fails "new: rejects a branch that already has a worktree" "$WT" new orphan
+
+# --from picks the base
+git -C "$REPO" checkout -q -b basis
+echo b > "$REPO/b.txt"; git -C "$REPO" add b.txt; git -C "$REPO" commit -qm basis
+git -C "$REPO" checkout -q master
+"$WT" new derived --from basis >/dev/null 2>&1
+assert_eq "0" "$(test -f "$TMP/newrepo-worktrees/derived/b.txt"; echo $?)" \
+  "new --from: branched from the named base"
+
+# a template that yields a space is refused before anything is created
+new_repo spacerepo
+printf 'runner: host\nhooks:\n  server: "true"\n' > worktree-kit.yml
+cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/has space/{branch}"
+YML
+assert_fails "new: refuses a path containing a space" "$WT" new anything
+assert_eq "1" "$(test -d "$TMP/has space" && echo 0 || echo 1)" "new: nothing created on refusal"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From af298347379d6a52769cc3202e76c139816272d8 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 16:57:41 +0700
Subject: [PATCH 04/15] wt new: run hooks.prepare exactly once, not 2-3x
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cmd_new handed the prepare hook to `wt run` as its payload, but `wt run`
already runs hooks.prepare itself before execing its payload — running
the hook twice on every `wt new`, on both runners. `wt new --server`
made it three times, since `wt server` independently runs the hook as
part of its own command string.

Pass an inert `true` payload instead (wt run's own prepare step does
the work), and skip the standalone prepare step entirely when --server
is requested so `wt server`'s prepare run is the only one.
---
 bin/wt            | 12 +++++++++---
 test/lifecycle.sh | 13 +++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/bin/wt b/bin/wt
index 0439b00..596da52 100755
--- a/bin/wt
+++ b/bin/wt
@@ -746,10 +746,16 @@ worktree paths must be space-free. Change worktrees.path or the branch name." ;;
     git worktree add -b "$_branch" "$_path" >&2
   fi
 
-  # Hook output goes to stderr so it cannot pollute the cd channel.
-  if [ "$HAS_CONFIG" = 1 ] && [ -n "${PREPARE:-}" ]; then
+  # The prepare hook must run exactly once. `wt run` already runs
+  # hooks.prepare itself before execing its payload, so the payload here is
+  # inert (`true`) — passing the hook again as the payload would run it
+  # twice. When --server is requested, skip this step entirely: `wt server`
+  # runs hooks.prepare as part of its own command string, so running it
+  # here too would make it run twice for the bare case and three times
+  # once the server path also fires it.
+  if [ "$_start_server" = 0 ] && [ "$HAS_CONFIG" = 1 ] && [ -n "${PREPARE:-}" ]; then
     note "prepare: $PREPARE"
-    if ! ( cd "$_path" && "$0" run --shared -- sh -c "$PREPARE" ) >&2; then
+    if ! ( cd "$_path" && "$0" run --shared -- true ) >&2; then
       die "prepare hook failed — worktree left at $_path"
     fi
   fi
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 3c35e07..0e5883e 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -128,5 +128,18 @@ YML
 assert_fails "new: refuses a path containing a space" "$WT" new anything
 assert_eq "1" "$(test -d "$TMP/has space" && echo 0 || echo 1)" "new: nothing created on refusal"
 
+# hooks.prepare must run exactly once. cmd_new used to hand the hook itself
+# to `wt run` as its payload, on top of `wt run` already running the hook
+# before execing its payload — silently double-running seed/migration
+# scripts. The counter lives outside the worktree so it survives the
+# prepare hook's own cwd (the new worktree) and can be inspected here.
+new_repo prepcountrepo
+_counter="$TMP/prepare-count.txt"
+: > "$_counter"
+printf 'runner: host\nhooks:\n  prepare: "echo x >> %s"\n  server: "true"\n' "$_counter" \
+  > worktree-kit.yml
+"$WT" new prepped >/dev/null 2>&1
+assert_eq "1" "$(wc -l < "$_counter" | tr -d ' ')" "new: prepare hook runs exactly once"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 4dd1d310cf3fe2a9a1c002881517dfac9a70e5c2 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 17:05:47 +0700
Subject: [PATCH 05/15] wt switch: picker, branch lookup, and shell integration

---
 bin/wt            | 94 +++++++++++++++++++++++++++++++++++++++++++++++
 test/lifecycle.sh | 36 ++++++++++++++++++
 2 files changed, 130 insertions(+)

diff --git a/bin/wt b/bin/wt
index 596da52..ad24d3c 100755
--- a/bin/wt
+++ b/bin/wt
@@ -385,6 +385,38 @@ emit_cd() { # <path>
   fi
 }
 
+# Prints the selected worktree path. fzf draws on /dev/tty and prints only
+# the selection to stdout, so it composes with the cd channel.
+pick_worktree() {
+  _rows="$(worktree_rows)"
+  if [ -z "$_rows" ]; then die "no worktrees"; fi
+
+  if command -v fzf >/dev/null 2>&1; then
+    _sel="$(printf '%s\n' "$_rows" | fzf \
+      --delimiter="$TAB" --with-nth=1,2,3,4 \
+      --preview 'git -C {6} log --oneline -10; echo; git -C {6} status -s' \
+      --preview-window=right:60%)" || return 1
+  else
+    _tmp="$STATE_DIR/.picker.$$"
+    printf '%s\n' "$_rows" > "$_tmp"
+    _i=0
+    while IFS="$TAB" read -r _b _s _st _srv _iso _p; do
+      _i=$((_i + 1))
+      printf '%2d) %-28s %s\n' "$_i" "$_b" "$_p" >&2
+    done < "$_tmp"
+    printf 'select worktree [1-%d]: ' "$_i" >&2
+    if ! read -r _n < /dev/tty; then rm -f "$_tmp"; return 1; fi
+    case "$_n" in
+      ''|*[!0-9]*) rm -f "$_tmp"; die "not a number: $_n" ;;
+    esac
+    if [ "$_n" -lt 1 ] || [ "$_n" -gt "$_i" ]; then rm -f "$_tmp"; die "out of range: $_n"; fi
+    _sel="$(sed -n "${_n}p" "$_tmp")"
+    rm -f "$_tmp"
+  fi
+
+  printf '%s' "$_sel" | cut -f6
+}
+
 # ---------- ports ----------
 
 # lsof (macOS) -> ss (Linux) -> bind probe via ruby/python3 -> assume free.
@@ -797,6 +829,64 @@ $_b${TAB}-${TAB}(no worktree)${TAB}-${TAB}-${TAB}-"
   fi
 }
 
+cmd_switch() {
+  load_config_soft
+  if [ $# -eq 0 ]; then
+    _p="$(pick_worktree)" || exit 1
+    if [ -z "$_p" ]; then exit 1; fi
+    emit_cd "$_p"
+    return 0
+  fi
+
+  _p="$(worktree_for_branch "$1")"
+  if [ -z "$_p" ]; then
+    if git show-ref --verify --quiet "refs/heads/$1"; then
+      die "branch $1 has no worktree — create one: wt new $1"
+    fi
+    die "no worktree or branch named $1 (see: wt list --all)"
+  fi
+  emit_cd "$_p"
+}
+
+cmd_shell_init() {
+  _kind="${1:-}"
+  if [ -z "$_kind" ]; then _kind="$(basename "${SHELL:-sh}")"; fi
+  case "$_kind" in
+    bash|zsh)
+      cat <<'EOF'
+wt() {
+  case "${1:-}" in
+    switch|new|rm|merge)
+      local __wt_d
+      __wt_d="$(WT_SHELL_INTEGRATION=1 command wt "$@")" || return $?
+      # explicit if, not &&: a command that prints no path must still return 0
+      if [ -n "$__wt_d" ]; then cd "$__wt_d"; fi
+      ;;
+    *) command wt "$@" ;;
+  esac
+}
+EOF
+      ;;
+    fish)
+      cat <<'EOF'
+function wt
+  switch "$argv[1]"
+    case switch new rm merge
+      set -l __wt_d (WT_SHELL_INTEGRATION=1 command wt $argv)
+      or return $status
+      if test -n "$__wt_d"
+        cd $__wt_d
+      end
+    case '*'
+      command wt $argv
+  end
+end
+EOF
+      ;;
+    *) die "unsupported shell: $_kind (bash, zsh, fish)" ;;
+  esac
+}
+
 usage() {
   cat <<'EOF'
 wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
@@ -810,9 +900,11 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt localize <file...>  snapshot a personal overlay (--list / --remove)
   wt reset [slug]        clear the own-db bootstrap marker
   wt new <branch> [--from <base>] [--server]   create a branch + worktree
+  wt switch [<branch>]   cd to a worktree; no argument opens a picker
   wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
+  wt shell-init [bash|zsh|fish]   emit the shell function that makes switch cd
 EOF
 }
 
@@ -820,6 +912,7 @@ EOF
 case "${1:-}" in
   -h|--help|help|'') usage; exit 0 ;;
   -v|--version) echo "wt $WT_VERSION"; exit 0 ;;
+  shell-init) shift; cmd_shell_init "$@"; exit 0 ;;
 esac
 
 ctx_init
@@ -833,6 +926,7 @@ case "$1" in
   localize) shift; cmd_localize "$@" ;;
   reset) shift; cmd_reset "$@" ;;
   new) shift; cmd_new "$@" ;;
+  switch) shift; cmd_switch "$@" ;;
   list) shift; cmd_list "$@" ;;
   init) shift; cmd_init "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 0e5883e..c320333 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -141,5 +141,41 @@ printf 'runner: host\nhooks:\n  prepare: "echo x >> %s"\n  server: "true"\n' "$_
 "$WT" new prepped >/dev/null 2>&1
 assert_eq "1" "$(wc -l < "$_counter" | tr -d ' ')" "new: prepare hook runs exactly once"
 
+# ---------- Task 3: switch and shell-init ----------
+
+new_repo switchrepo
+"$WT" new feat/alpha >/dev/null 2>&1
+
+# stdout carries only the path; the hint goes to stderr
+out="$("$WT" switch feat/alpha 2>/dev/null)"
+assert_eq "$TMP/switchrepo-worktrees/feat_alpha" "$out" "switch: stdout is the bare path"
+
+err="$("$WT" switch feat/alpha 2>&1 >/dev/null)"
+assert_contains "$err" "shell-init" "switch: hints about shell integration on stderr"
+
+err="$(WT_SHELL_INTEGRATION=1 "$WT" switch feat/alpha 2>&1 >/dev/null)"
+assert_eq "" "$err" "switch: no stderr noise under shell integration"
+
+assert_fails "switch: unknown branch is an error" "$WT" switch nope
+err="$("$WT" switch nope 2>&1 >/dev/null || true)"
+assert_contains "$err" "nope" "switch: names the branch it could not find"
+
+git -C "$REPO" branch -q lonely
+err="$("$WT" switch lonely 2>&1 >/dev/null || true)"
+assert_contains "$err" "wt new lonely" "switch: branch without a worktree points at wt new"
+
+# shell-init emits a wrapper covering all four cd-channel commands
+out="$("$WT" shell-init zsh)"
+assert_contains "$out" "switch|new|rm|merge" "shell-init: wraps every cd-channel command"
+assert_contains "$out" "WT_SHELL_INTEGRATION=1" "shell-init: exports the marker"
+assert_contains "$out" 'if [ -n "$__wt_d" ]; then' "shell-init: explicit if, not && (bug 1)"
+out="$("$WT" shell-init fish)"
+assert_contains "$out" "function wt" "shell-init: fish variant"
+assert_fails "shell-init: rejects an unknown shell" "$WT" shell-init tcsh
+
+# shell-init must work outside a git repo
+out="$(cd "$TMP" && "$WT" shell-init bash)"
+assert_contains "$out" "command wt" "shell-init: works outside a git repo"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 55f54acbfae71cc6fa1a058ab4734e0edde82464 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 19:39:56 +0700
Subject: [PATCH 06/15] wt rm: reclaim the server, database, redis slot, and
 state files

---
 bin/wt            | 120 ++++++++++++++++++++++++++++++++++++++++++++++
 test/lifecycle.sh |  53 ++++++++++++++++++++
 2 files changed, 173 insertions(+)

diff --git a/bin/wt b/bin/wt
index ad24d3c..1e55632 100755
--- a/bin/wt
+++ b/bin/wt
@@ -417,6 +417,70 @@ pick_worktree() {
   printf '%s' "$_sel" | cut -f6
 }
 
+# Reclaims everything the kit provisioned for a slug. Does NOT touch the
+# worktree directory or the branch. Overlays under $OVERLAY_DIR are per-file
+# and personal, never per-worktree — they are deliberately left alone.
+teardown_worktree() { # <slug> <path>
+  _ts="$1"; _tp="$2"
+
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    "$0" down "$_ts" >&2 || true
+
+    # expand() reads the globals SLUG and N; borrow them for the target slug
+    _old_slug="$SLUG"; _old_n="$N"
+    SLUG="$_ts"; N=$(( $(hashnum "$_ts") % 15 + 1 ))
+
+    if [ -f "$STATE_DIR/$_ts.dbready" ]; then
+      _drop="$(cfg_get isolation.db_drop "")"
+      if [ -n "$_drop" ]; then
+        note "dropping database for $_ts"
+        runner_exec own_db "$(expand "$_drop")" >&2 || note "db_drop failed — the database may remain"
+      else
+        note "no isolation.db_drop configured — the database for slug $_ts is left in place"
+      fi
+    fi
+
+    _flush="$(cfg_get isolation.redis_flush "")"
+    if [ -n "$_flush" ]; then
+      note "flushing redis db $N for $_ts"
+      runner_exec isolated "$(expand "$_flush")" >&2 || note "redis_flush failed — db $N may still hold keys"
+    else
+      note "no isolation.redis_flush configured — redis db $N is left as is"
+    fi
+
+    SLUG="$_old_slug"; N="$_old_n"
+  fi
+
+  rm -f "$STATE_DIR/$_ts.pid" "$STATE_DIR/$_ts.port" \
+        "$STATE_DIR/$_ts.dbready" "$STATE_DIR/logs/$_ts.log"
+  true
+}
+
+remove_worktree_and_branch() { # <branch> <path> <keep_branch 0|1> <force 0|1>
+  if [ "$4" = 1 ]; then
+    git worktree remove --force "$2" >&2
+  else
+    git worktree remove "$2" >&2
+  fi
+  if [ "$3" = 0 ]; then
+    if [ "$4" = 1 ]; then
+      git branch -D "$1" >&2
+    else
+      git branch -d "$1" >&2
+    fi
+  fi
+  true
+}
+
+confirm() { # <prompt> — 0 on yes, reading stdin
+  printf '%s [y/N] ' "$1" >&2
+  read -r _ans || _ans=n
+  case "$_ans" in
+    y|Y|yes|YES) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 # ---------- ports ----------
 
 # lsof (macOS) -> ss (Linux) -> bind probe via ruby/python3 -> assume free.
@@ -848,6 +912,60 @@ cmd_switch() {
   emit_cd "$_p"
 }
 
+cmd_rm() {
+  load_config_soft
+  _force=0; _keep=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -f|--force)    _force=1; shift ;;
+      --keep-branch) _keep=1; shift ;;
+      -*)            die "unknown flag: $1 (wt rm [<branch>] [--keep-branch] [--force])" ;;
+      *)             _branch="$1"; shift ;;
+    esac
+  done
+  if [ -z "$_branch" ]; then _branch="$(git rev-parse --abbrev-ref HEAD)"; fi
+
+  _path="$(worktree_for_branch "$_branch")"
+  if [ -z "$_path" ]; then die "no worktree for branch $_branch (see: wt list)"; fi
+  if [ "$_path" = "$PRIMARY" ]; then die "refusing to remove the primary checkout at $PRIMARY"; fi
+
+  if [ "$_force" = 0 ]; then
+    if [ -n "$(git -C "$_path" status --porcelain)" ]; then
+      die "$_branch has uncommitted changes — commit them, or use --force"
+    fi
+    # Deliberately reachability, not "unpushed": a local-only branch has no
+    # upstream, so an unpushed test would refuse every agent worktree.
+    _trunk="$(resolve_trunk)"
+    if [ -n "$_trunk" ]; then
+      _un="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
+      if [ "$_un" -gt 0 ]; then
+        die "$_branch has $_un commit(s) not in $_trunk — merge them (wt merge $_branch), or use --force"
+      fi
+    fi
+  fi
+
+  _slug="$(slugify "$_path")"
+  note "about to remove:"
+  note "  worktree  $_path"
+  if [ "$_keep" = 0 ]; then note "  branch    $_branch"; fi
+  note "  state     $STATE_DIR/$_slug.*"
+  if [ "${HAS_CONFIG:-0}" = 1 ] && [ -f "$STATE_DIR/$_slug.dbready" ]; then
+    note "  database  provisioned for slug $_slug"
+  fi
+  if [ "$_force" = 0 ]; then
+    confirm "proceed?" || die "aborted"
+  fi
+
+  _removed_cwd=0
+  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; fi
+
+  teardown_worktree "$_slug" "$_path"
+  remove_worktree_and_branch "$_branch" "$_path" "$_keep" "$_force"
+  note "removed $_branch"
+
+  if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
+}
+
 cmd_shell_init() {
   _kind="${1:-}"
   if [ -z "$_kind" ]; then _kind="$(basename "${SHELL:-sh}")"; fi
@@ -901,6 +1019,7 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt reset [slug]        clear the own-db bootstrap marker
   wt new <branch> [--from <base>] [--server]   create a branch + worktree
   wt switch [<branch>]   cd to a worktree; no argument opens a picker
+  wt rm [<branch>] [--keep-branch] [--force]   tear down and remove a worktree
   wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
@@ -927,6 +1046,7 @@ case "$1" in
   reset) shift; cmd_reset "$@" ;;
   new) shift; cmd_new "$@" ;;
   switch) shift; cmd_switch "$@" ;;
+  rm) shift; cmd_rm "$@" ;;
   list) shift; cmd_list "$@" ;;
   init) shift; cmd_init "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index c320333..353068c 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -177,5 +177,58 @@ assert_fails "shell-init: rejects an unknown shell" "$WT" shell-init tcsh
 out="$(cd "$TMP" && "$WT" shell-init bash)"
 assert_contains "$out" "command wt" "shell-init: works outside a git repo"
 
+# ---------- Task 4: rm ----------
+
+new_repo rmrepo
+"$WT" new feat/gone >/dev/null 2>&1
+wtdir="$TMP/rmrepo-worktrees/feat_gone"
+
+# fabricate the state files a server would have left behind
+state="$REPO/.git/wt-state"
+mkdir -p "$state/logs"
+: > "$state/feat_gone.dbready"
+: > "$state/feat_gone.port"
+: > "$state/logs/feat_gone.log"
+
+# a dirty worktree is refused without --force
+echo scratch > "$wtdir/scratch.txt"
+assert_fails "rm: refuses a dirty worktree" "$WT" rm feat/gone
+assert_eq "0" "$(test -d "$wtdir" && echo 0 || echo 1)" "rm: dirty worktree survives the refusal"
+rm "$wtdir/scratch.txt"
+
+# unmerged commits are refused without --force
+( cd "$wtdir" && echo c > c.txt && git add c.txt && git commit -qm work )
+assert_fails "rm: refuses unmerged commits" "$WT" rm feat/gone
+
+# --force removes it and reclaims every state file
+"$WT" rm feat/gone --force >/dev/null 2>&1
+assert_eq "1" "$(test -d "$wtdir" && echo 0 || echo 1)"                    "rm --force: worktree gone"
+assert_eq "1" "$(test -f "$state/feat_gone.dbready" && echo 0 || echo 1)"  "rm --force: dbready cleared"
+assert_eq "1" "$(test -f "$state/feat_gone.port" && echo 0 || echo 1)"     "rm --force: port file cleared"
+assert_eq "1" "$(test -f "$state/logs/feat_gone.log" && echo 0 || echo 1)" "rm --force: log cleared"
+assert_missing "$(git -C "$REPO" branch --list 'feat/gone')" "feat/gone" \
+  "rm --force: branch deleted"
+
+# --keep-branch keeps the branch
+"$WT" new feat/keep >/dev/null 2>&1
+"$WT" rm feat/keep --force --keep-branch >/dev/null 2>&1
+assert_contains "$(git -C "$REPO" branch --list 'feat/keep')" "feat/keep" \
+  "rm --keep-branch: branch survives"
+
+# the primary checkout is never removable
+assert_fails "rm: refuses the primary checkout" "$WT" rm master --force
+
+# a clean, fully merged worktree needs no --force, but does need a yes
+"$WT" new feat/clean >/dev/null 2>&1
+printf 'y\n' | "$WT" rm feat/clean >/dev/null 2>&1
+assert_eq "1" "$(test -d "$TMP/rmrepo-worktrees/feat_clean" && echo 0 || echo 1)" \
+  "rm: clean merged worktree removed after confirmation"
+
+# answering no leaves everything alone
+"$WT" new feat/spared >/dev/null 2>&1
+printf 'n\n' | "$WT" rm feat/spared >/dev/null 2>&1 || true
+assert_eq "0" "$(test -d "$TMP/rmrepo-worktrees/feat_spared" && echo 0 || echo 1)" \
+  "rm: declining the prompt keeps the worktree"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From ac0c365854060d70c58546603498e9eab9038dde Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 20:02:36 +0700
Subject: [PATCH 07/15] =?UTF-8?q?wt=20rm:=20fix=20round=201=20=E2=80=94=20?=
 =?UTF-8?q?trunk-verify=20guard,=20dbowned=20provenance,=20cwd-safe=20remo?=
 =?UTF-8?q?val?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five review findings on the destructive path: the unmerged-commits guard
failed open when a configured trunk did not resolve in the worktree; wt rm
from inside the worktree being removed crashed after git worktree remove
deleted the cwd, stranding the branch and skipping emit_cd; a failed
server-stop was silently swallowed instead of reported; .dbready alone did
not distinguish a kit-bootstrapped database from a merely-adopted one, so
wt rm (and soon wt merge) could drop a hand-created database — added a
narrower .dbowned marker and gated the drop on it; and the whole
HAS_CONFIG=1 teardown branch (server-stop, the ownership gate, db_drop,
redis_flush, the SLUG/N borrow) had zero test coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bin/wt            | 38 +++++++++++++++++++------
 test/lifecycle.sh | 70 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 9 deletions(-)

diff --git a/bin/wt b/bin/wt
index 1e55632..e26a441 100755
--- a/bin/wt
+++ b/bin/wt
@@ -424,19 +424,23 @@ teardown_worktree() { # <slug> <path>
   _ts="$1"; _tp="$2"
 
   if [ "${HAS_CONFIG:-0}" = 1 ]; then
-    "$0" down "$_ts" >&2 || true
+    "$0" down "$_ts" >&2 || note "could not stop the server for $_ts — check for a stray process"
 
     # expand() reads the globals SLUG and N; borrow them for the target slug
     _old_slug="$SLUG"; _old_n="$N"
     SLUG="$_ts"; N=$(( $(hashnum "$_ts") % 15 + 1 ))
 
     if [ -f "$STATE_DIR/$_ts.dbready" ]; then
-      _drop="$(cfg_get isolation.db_drop "")"
-      if [ -n "$_drop" ]; then
-        note "dropping database for $_ts"
-        runner_exec own_db "$(expand "$_drop")" >&2 || note "db_drop failed — the database may remain"
+      if [ -f "$STATE_DIR/$_ts.dbowned" ]; then
+        _drop="$(cfg_get isolation.db_drop "")"
+        if [ -n "$_drop" ]; then
+          note "dropping database for $_ts"
+          runner_exec own_db "$(expand "$_drop")" >&2 || note "db_drop failed — the database may remain"
+        else
+          note "no isolation.db_drop configured — the database for slug $_ts is left in place"
+        fi
       else
-        note "no isolation.db_drop configured — the database for slug $_ts is left in place"
+        note "database for slug $_ts was adopted, not created by wt — leaving it in place"
       fi
     fi
 
@@ -452,7 +456,7 @@ teardown_worktree() { # <slug> <path>
   fi
 
   rm -f "$STATE_DIR/$_ts.pid" "$STATE_DIR/$_ts.port" \
-        "$STATE_DIR/$_ts.dbready" "$STATE_DIR/logs/$_ts.log"
+        "$STATE_DIR/$_ts.dbready" "$STATE_DIR/$_ts.dbowned" "$STATE_DIR/logs/$_ts.log"
   true
 }
 
@@ -550,7 +554,10 @@ ensure_own_db() {
   [ -n "$boot" ] || die "own-db needs isolation.db_bootstrap in worktree-kit.yml"
   note "bootstrapping isolated database for $SLUG ..."
   runner_exec own_db "$(expand "$boot")"
-  touch "$marker"
+  # .dbowned records that the kit itself created this database (as opposed
+  # to the db_check branch above, which only found one already there) — wt
+  # rm/merge must never drop a database they did not create.
+  touch "$marker" "$STATE_DIR/$SLUG.dbowned"
 }
 
 # ---------- compose runner ----------
@@ -937,6 +944,13 @@ cmd_rm() {
     # upstream, so an unpushed test would refuse every agent worktree.
     _trunk="$(resolve_trunk)"
     if [ -n "$_trunk" ]; then
+      # A configured worktrees.trunk is returned as-is, unverified — it can
+      # name a ref this worktree cannot resolve (e.g. a remote-only branch).
+      # "cannot check" must never be treated as "nothing unmerged" for a
+      # destructive command, so require the ref to resolve before counting.
+      if ! git -C "$_path" rev-parse --verify --quiet "$_trunk" >/dev/null 2>&1; then
+        die "cannot verify $_branch is merged — $_trunk not found in this worktree, use --force"
+      fi
       _un="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
       if [ "$_un" -gt 0 ]; then
         die "$_branch has $_un commit(s) not in $_trunk — merge them (wt merge $_branch), or use --force"
@@ -957,7 +971,13 @@ cmd_rm() {
   fi
 
   _removed_cwd=0
-  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; fi
+  # git worktree remove deletes the cwd out from under this process when we
+  # are inside it; the very next git call (branch -d/-D) then fails calling
+  # getcwd() ("Unable to read current working directory") and set -e kills
+  # cmd_rm before the branch is deleted or emit_cd runs. Step out first.
+  # runner_exec keys off $WT_PATH (a fixed global), not the live cwd, so
+  # this does not retarget teardown_worktree's own_db/redis work.
+  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; cd "$PRIMARY"; fi
 
   teardown_worktree "$_slug" "$_path"
   remove_worktree_and_branch "$_branch" "$_path" "$_keep" "$_force"
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 353068c..764bdd6 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -230,5 +230,75 @@ printf 'n\n' | "$WT" rm feat/spared >/dev/null 2>&1 || true
 assert_eq "0" "$(test -d "$TMP/rmrepo-worktrees/feat_spared" && echo 0 || echo 1)" \
   "rm: declining the prompt keeps the worktree"
 
+# ---------- Task 4 fix round 1 ----------
+
+# Item 3: from inside the worktree being removed, wt rm must survive git's
+# cwd being yanked out from under it (git worktree remove deletes the cwd,
+# then git branch -d's getcwd() call dies) and still land the caller in the
+# primary via the cd channel. Runs first, in rmrepo, while $REPO/cwd still
+# point there — every later block in this section calls new_repo again.
+"$WT" new feat/herecwd >/dev/null 2>&1
+wtdir_here="$TMP/rmrepo-worktrees/feat_herecwd"
+rmrepo_repo="$REPO"
+out="$( (cd "$wtdir_here" && "$WT" rm feat/herecwd --force 2>/dev/null) || true )"
+assert_eq "$rmrepo_repo" "$out" "rm: from inside the worktree, prints the primary for cd"
+
+# Item 1: the entire HAS_CONFIG=1 teardown branch (server-stop, the db
+# ownership gate, db_drop, redis_flush, the "left behind" notices, and the
+# SLUG/N borrow) is otherwise never exercised — rmrepo above has no config.
+new_repo cfgrmrepo
+db_sentinel="$TMP/db-drop.sentinel"
+redis_sentinel="$TMP/redis-flush.sentinel"
+cat > worktree-kit.yml <<YML
+runner: host
+hooks:
+  server: "true"
+isolation:
+  db_drop: "echo dropped-{slug} >> $db_sentinel"
+  redis_flush: "echo flushed-{slug}-{n} >> $redis_sentinel"
+YML
+"$WT" new feat/owned >/dev/null 2>&1
+"$WT" new feat/adopted >/dev/null 2>&1
+cfgstate="$REPO/.git/wt-state"
+# feat_owned: the kit bootstrapped this database itself.
+: > "$cfgstate/feat_owned.dbready"
+: > "$cfgstate/feat_owned.dbowned"
+# feat_adopted: db_check found a pre-existing database and merely adopted
+# it (ensure_own_db touches .dbready but never .dbowned on that path) — it
+# stands in for a database wt rm must never drop.
+: > "$cfgstate/feat_adopted.dbready"
+
+"$WT" rm feat/owned --force >/dev/null 2>&1
+assert_contains "$(cat "$db_sentinel" 2>/dev/null)" "dropped-feat_owned" \
+  "rm: drops a database the kit itself bootstrapped"
+assert_contains "$(cat "$redis_sentinel" 2>/dev/null)" "flushed-feat_owned-" \
+  "rm: flushes the redis slot for a configured worktree (SLUG/N borrow works)"
+
+"$WT" rm feat/adopted --force >/dev/null 2>&1
+assert_missing "$(cat "$db_sentinel" 2>/dev/null)" "dropped-feat_adopted" \
+  "rm: never drops a database it only adopted (.dbready without .dbowned)"
+
+# Item 2: a configured trunk that does not resolve as a ref in this worktree
+# must not be silently treated as "nothing unmerged" — "cannot check" must
+# not mean "safe to delete" for a destructive command.
+new_repo trunkguardrepo
+printf 'runner: host\nhooks:\n  server: "true"\nworktrees:\n  trunk: develop\n' \
+  > worktree-kit.yml
+"$WT" new feat/risky >/dev/null 2>&1
+( cd "$TMP/trunkguardrepo-worktrees/feat_risky" && echo x > x.txt && git add x.txt && git commit -qm risky )
+printf 'y\n' | "$WT" rm feat/risky >/dev/null 2>&1 || true
+assert_eq "0" "$(test -d "$TMP/trunkguardrepo-worktrees/feat_risky" && echo 0 || echo 1)" \
+  "rm: an unverifiable configured trunk refuses rather than failing open"
+
+# Item 4: a failed server-stop must be surfaced, not swallowed — otherwise
+# state files vanish, wt ps can no longer see the orphaned server, and wt rm
+# still reports success.
+new_repo swallowfailrepo
+printf 'hooks:\n  server: "true"\n' > worktree-kit.yml
+"$WT" new feat/failstop >/dev/null 2>&1
+err="$(PATH=/usr/bin:/bin "$WT" rm feat/failstop --force 2>&1 >/dev/null)"
+assert_contains "$err" "could not stop the server" \
+  "rm: a failed server-stop is reported, not swallowed"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 00a50105309865e78361599514105df84761eea4 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 20:13:45 +0700
Subject: [PATCH 08/15] =?UTF-8?q?wt=20rm:=20fix=20round=202=20=E2=80=94=20?=
 =?UTF-8?q?wt=20reset=20clears=20the=20dbowned=20marker=20too?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cmd_reset cleared .dbready but left a stale .dbowned behind. If the
database is later replaced by hand and db_check adopts the replacement
(touching only .dbready by design), the stale .dbowned would wrongly
authorize wt rm/merge to drop a database this incarnation of the slug
never created. Reset now clears both markers together; no heuristic
added to recover ownership after a reset, per instruction — the
accepted tradeoff is a "left in place" notice instead of a drop.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bin/wt            |  2 +-
 test/lifecycle.sh | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/bin/wt b/bin/wt
index e26a441..2b2d266 100755
--- a/bin/wt
+++ b/bin/wt
@@ -762,7 +762,7 @@ cmd_localize() {
 
 cmd_reset() {
   s="${1:-$SLUG}"
-  rm -f "$STATE_DIR/$s.dbready"
+  rm -f "$STATE_DIR/$s.dbready" "$STATE_DIR/$s.dbowned"
   note "cleared db-bootstrap marker for $s (next own-db run re-bootstraps)"
 }
 
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 764bdd6..f1cc227 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -300,5 +300,23 @@ err="$(PATH=/usr/bin:/bin "$WT" rm feat/failstop --force 2>&1 >/dev/null)"
 assert_contains "$err" "could not stop the server" \
   "rm: a failed server-stop is reported, not swallowed"
 
+# ---------- Task 4 fix round 2 ----------
+
+# wt reset must clear both provenance markers together. A stale .dbowned
+# surviving a reset would let a later, merely-adopted database (db_check
+# touches only .dbready) inherit an ownership claim it never earned — the
+# exact guarantee round 1's item 5 established for wt rm (and, imminently,
+# wt merge, which does not prompt).
+new_repo resetrepo
+rstate="$REPO/.git/wt-state"
+mkdir -p "$rstate"
+: > "$rstate/someslug.dbready"
+: > "$rstate/someslug.dbowned"
+"$WT" reset someslug >/dev/null 2>&1
+assert_eq "1" "$(test -f "$rstate/someslug.dbready" && echo 0 || echo 1)" \
+  "reset: clears the dbready marker"
+assert_eq "1" "$(test -f "$rstate/someslug.dbowned" && echo 0 || echo 1)" \
+  "reset: clears the dbowned marker too"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 3beba8150bcf35ad9d1207dd0e7d1318c325603e Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 20:24:43 +0700
Subject: [PATCH 09/15] =?UTF-8?q?wt=20merge:=20squash,=20rebase,=20fast-fo?=
 =?UTF-8?q?rward,=20tear=20down=20=E2=80=94=20with=20a=20backup=20ref?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 bin/wt            | 105 ++++++++++++++++++++++++++++++++++++++++++++++
 test/lifecycle.sh |  81 +++++++++++++++++++++++++++++++++++
 2 files changed, 186 insertions(+)

diff --git a/bin/wt b/bin/wt
index 2b2d266..6ad274b 100755
--- a/bin/wt
+++ b/bin/wt
@@ -986,6 +986,108 @@ cmd_rm() {
   if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
 }
 
+cmd_merge() {
+  load_config_soft
+  _trunk=""; _msg=""; _no_remove=0; _force=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --into)      _trunk="${2:-}"; [ -n "$_trunk" ] || die "--into needs a branch"; shift 2 ;;
+      -m)          _msg="${2:-}";   [ -n "$_msg" ]   || die "-m needs a message";   shift 2 ;;
+      --no-remove) _no_remove=1; shift ;;
+      -f|--force)  _force=1; shift ;;
+      -*)          die "unknown flag: $1 (wt merge [<branch>] [--into <trunk>] [--no-remove] [-m <msg>] [--force])" ;;
+      *)           _branch="$1"; shift ;;
+    esac
+  done
+  if [ -z "$_branch" ]; then _branch="$(git rev-parse --abbrev-ref HEAD)"; fi
+
+  _path="$(worktree_for_branch "$_branch")"
+  if [ -z "$_path" ]; then die "no worktree for branch $_branch (see: wt list)"; fi
+  if [ "$_path" = "$PRIMARY" ]; then die "refusing to merge the primary checkout's own branch"; fi
+
+  if [ -z "$_trunk" ]; then _trunk="$(resolve_trunk)"; fi
+  if [ -z "$_trunk" ]; then die "cannot determine trunk — pass --into <branch> or set worktrees.trunk"; fi
+  if [ "$_trunk" = "$_branch" ]; then die "$_branch is the trunk"; fi
+
+  # ---- guards, before anything is rewritten ----
+  if [ -n "$(git -C "$_path" status --porcelain)" ]; then
+    die "$_branch has uncommitted changes — commit or stash them first"
+  fi
+  _ahead="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
+  if [ "$_ahead" -eq 0 ]; then die "$_branch has no commits ahead of $_trunk"; fi
+
+  _primary_branch="$(git -C "$PRIMARY" rev-parse --abbrev-ref HEAD)"
+  if [ "$_primary_branch" != "$_trunk" ]; then
+    die "$_trunk is not checked out at $PRIMARY (found $_primary_branch)"
+  fi
+  if [ -n "$(git -C "$PRIMARY" status --porcelain)" ]; then
+    die "the primary checkout at $PRIMARY is dirty — commit or stash first"
+  fi
+  if git -C "$_path" rev-parse --verify --quiet "$_branch@{upstream}" >/dev/null 2>&1; then
+    if [ "$_force" = 0 ]; then
+      die "$_branch has an upstream — squashing rewrites published history; pass --force to proceed"
+    fi
+  fi
+
+  # ---- backup ref: the undo for everything below ----
+  _slug="$(slugify "$_path")"
+  _backup="refs/wt/premerge/$_slug"
+  _orig="$(git -C "$_path" rev-parse HEAD)"
+  git -C "$_path" update-ref "$_backup" "$_orig"
+  note "backup: $_backup -> $_orig"
+
+  # ---- squash ----
+  _base="$(git -C "$_path" merge-base "$_trunk" "$_branch")"
+  if [ -z "$_msg" ]; then
+    _subj="$(git -C "$_path" log --format='%s' --reverse "$_base..$_branch" | head -1)"
+    _body="$(git -C "$_path" log --format='%s' --reverse "$_base..$_branch" | tail -n +2)"
+    if [ -n "$_body" ]; then
+      _msg="$_subj
+
+$_body"
+    else
+      _msg="$_subj"
+    fi
+  fi
+  git -C "$_path" reset --soft "$_base" >&2
+  if ! git -C "$_path" commit -q -m "$_msg" >&2; then
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "squash commit failed — $_branch restored to $_orig"
+  fi
+
+  # ---- rebase ----
+  if ! git -C "$_path" rebase "$_trunk" >&2; then
+    git -C "$_path" rebase --abort >/dev/null 2>&1 || true
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "rebase of $_branch onto $_trunk hit a conflict — $_branch restored to $_orig
+resolve by hand:  git -C $_path rebase $_trunk"
+  fi
+
+  # ---- fast-forward trunk ----
+  _trunk_before="$(git -C "$PRIMARY" rev-parse "$_trunk")"
+  if ! git -C "$PRIMARY" merge --ff-only "$_branch" >&2; then
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch restored to $_orig"
+  fi
+  note "merged $_branch into $_trunk"
+  note "undo:   git -C $PRIMARY reset --hard $_trunk_before   (branch backup: $_backup)"
+
+  # ---- teardown ----
+  if [ "$_no_remove" = 1 ]; then return 0; fi
+
+  _removed_cwd=0
+  # git worktree remove deletes the cwd out from under this process when we
+  # are inside it; the very next git call (branch -d/-D) then fails calling
+  # getcwd() ("Unable to read current working directory") and set -e kills
+  # cmd_merge before the branch is deleted or emit_cd runs. Step out first.
+  # runner_exec keys off $WT_PATH (a fixed global), not the live cwd, so
+  # this does not retarget teardown_worktree's own_db/redis work.
+  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; cd "$PRIMARY"; fi
+  teardown_worktree "$_slug" "$_path"
+  remove_worktree_and_branch "$_branch" "$_path" 0 0
+  if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
+}
+
 cmd_shell_init() {
   _kind="${1:-}"
   if [ -z "$_kind" ]; then _kind="$(basename "${SHELL:-sh}")"; fi
@@ -1040,6 +1142,8 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt new <branch> [--from <base>] [--server]   create a branch + worktree
   wt switch [<branch>]   cd to a worktree; no argument opens a picker
   wt rm [<branch>] [--keep-branch] [--force]   tear down and remove a worktree
+  wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]
+                         squash, rebase, fast-forward trunk, then tear down
   wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
@@ -1067,6 +1171,7 @@ case "$1" in
   new) shift; cmd_new "$@" ;;
   switch) shift; cmd_switch "$@" ;;
   rm) shift; cmd_rm "$@" ;;
+  merge) shift; cmd_merge "$@" ;;
   list) shift; cmd_list "$@" ;;
   init) shift; cmd_init "$@" ;;
   doctor) shift; cmd_doctor "$@" ;;
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index f1cc227..cc37d86 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -318,5 +318,86 @@ assert_eq "1" "$(test -f "$rstate/someslug.dbready" && echo 0 || echo 1)" \
 assert_eq "1" "$(test -f "$rstate/someslug.dbowned" && echo 0 || echo 1)" \
   "reset: clears the dbowned marker too"
 
+# ---------- Task 5: merge ----------
+
+new_repo mergerepo
+"$WT" new feat/work >/dev/null 2>&1
+wtdir="$TMP/mergerepo-worktrees/feat_work"
+( cd "$wtdir" && echo one > one.txt && git add one.txt && git commit -qm "add one" )
+( cd "$wtdir" && echo two > two.txt && git add two.txt && git commit -qm "add two" )
+
+before="$(git -C "$REPO" rev-parse master)"
+"$WT" merge feat/work >/dev/null 2>&1
+after="$(git -C "$REPO" rev-parse master)"
+
+# assert_eq "1" "$(test A = B; echo $?)" dies inside the substitution under
+# set -eu whenever the test succeeds (before==after), i.e. exactly when the
+# merge failed to advance master — so it could only ever fail for the right
+# reason and never confirm success. Express the intent directly instead.
+if [ "$before" = "$after" ]; then fail "merge: master advanced"; else ok "merge: master advanced"; fi
+assert_eq "1" "$(git -C "$REPO" rev-list --count "$before..$after")" \
+  "merge: two commits squashed into one"
+assert_contains "$(git -C "$REPO" log -1 --format=%s)" "add one" \
+  "merge: subject taken from the first commit"
+assert_contains "$(git -C "$REPO" log -1 --format=%B)" "add two" \
+  "merge: remaining subjects form the body"
+assert_eq "1" "$(test -d "$wtdir" && echo 0 || echo 1)" "merge: worktree removed by default"
+assert_contains "$(git -C "$REPO" show-ref)" "refs/wt/premerge/feat_work" \
+  "merge: backup ref kept as the undo"
+
+# --no-remove leaves the worktree in place
+"$WT" new feat/stay >/dev/null 2>&1
+( cd "$TMP/mergerepo-worktrees/feat_stay" && echo s > s.txt && git add s.txt && git commit -qm stay )
+"$WT" merge feat/stay --no-remove >/dev/null 2>&1
+assert_eq "0" "$(test -d "$TMP/mergerepo-worktrees/feat_stay" && echo 0 || echo 1)" \
+  "merge --no-remove: worktree survives"
+
+# a conflicting rebase restores the branch exactly and leaves the worktree alone
+new_repo conflictrepo
+echo base > f.txt && git add f.txt && git commit -qm base
+"$WT" new feat/conflict >/dev/null 2>&1
+cdir="$TMP/conflictrepo-worktrees/feat_conflict"
+( cd "$cdir" && echo theirs > f.txt && git add f.txt && git commit -qm theirs )
+orig="$(git -C "$cdir" rev-parse HEAD)"
+echo ours > f.txt && git add f.txt && git commit -qm ours
+master_before="$(git -C "$REPO" rev-parse master)"
+
+assert_fails "merge: conflict is an error" "$WT" merge feat/conflict
+assert_eq "$orig" "$(git -C "$cdir" rev-parse HEAD)" \
+  "merge: branch restored to its pre-squash commit after a conflict"
+assert_eq "$master_before" "$(git -C "$REPO" rev-parse master)" \
+  "merge: master untouched after a conflict"
+assert_eq "0" "$(test -d "$cdir" && echo 0 || echo 1)" "merge: worktree survives a conflict"
+assert_eq "" "$(git -C "$cdir" status --porcelain)" \
+  "merge: no rebase left in progress"
+
+# guards
+new_repo guardrepo
+"$WT" new feat/empty >/dev/null 2>&1
+assert_fails "merge: refuses a branch with no commits ahead" "$WT" merge feat/empty
+
+"$WT" new feat/dirty >/dev/null 2>&1
+( cd "$TMP/guardrepo-worktrees/feat_dirty" && echo d > d.txt && git add d.txt \
+    && git commit -qm d && echo x > x.txt )
+assert_fails "merge: refuses a dirty worktree" "$WT" merge feat/dirty
+
+"$WT" new feat/ok >/dev/null 2>&1
+( cd "$TMP/guardrepo-worktrees/feat_ok" && echo o > o.txt && git add o.txt && git commit -qm o )
+echo primarydirt > "$REPO/dirt.txt"
+assert_fails "merge: refuses when the primary checkout is dirty" "$WT" merge feat/ok
+rm -f "$REPO/dirt.txt"
+
+# wt merge from inside the worktree being merged must survive the cwd being
+# yanked out from under it (git worktree remove deletes the cwd, then
+# git branch -d's getcwd() call dies) and still land the caller in the
+# primary via the cd channel — the same defect Task 4 fixed for wt rm.
+new_repo cwdrepo
+"$WT" new feat/incwd >/dev/null 2>&1
+wtdir_incwd="$TMP/cwdrepo-worktrees/feat_incwd"
+( cd "$wtdir_incwd" && echo w > w.txt && git add w.txt && git commit -qm w )
+cwdrepo_repo="$REPO"
+out="$( (cd "$wtdir_incwd" && "$WT" merge feat/incwd 2>/dev/null) || true )"
+assert_eq "$cwdrepo_repo" "$out" "merge: from inside the worktree, prints the primary for cd"
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 58523b128b42751875ca905ca2cb10d143096a91 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 20:55:02 +0700
Subject: [PATCH 10/15] wt merge fix round 1: detached-HEAD-safe conflict
 restore, trunk guard, untested guards covered
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rebase-conflict abort no longer trusts "rebase --abort" alone: falls back
  to checkout -f + an explicit update-ref of refs/heads/<branch> before the
  reset --hard, so a mid-rebase detached HEAD can never leave the branch
  ref silently rewritten while die claims it was restored.
- Guarded the reset --hard fallbacks in the squash-commit-failure and
  fast-forward-failure paths so a failing reset can't have set -e kill the
  function before its recovery message (and the backup ref) reach the user.
- Added cmd_rm's trunk-resolution guard (rev-parse --verify --quiet) so an
  unresolvable configured trunk dies with "cannot verify" instead of
  silently reading as "no commits ahead".
- Test: feat/conflict now gets two commits so the squash always changes
  history shape, closing a same-second-timestamp coincidence that let the
  restore assertion pass even with the restore code deleted; added a
  rev-list --count shape assertion as the load-bearing check.
- Test: backup ref assertion now checks value and timing (equals the
  pre-squash HEAD), not just that the ref name exists.
- Test: added coverage for the trunk-not-at-primary and
  upstream-without---force guards, with master/branch "untouched"
  assertions rather than bare assert_fails — needed because both guards,
  when disabled, can still exit nonzero for unrelated incidental reasons
  (a fast-forward into the wrong branch, or git's own branch -d safety
  check) while real damage already happened.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bin/wt            | 33 +++++++++++++++----
 test/lifecycle.sh | 82 +++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 106 insertions(+), 9 deletions(-)

diff --git a/bin/wt b/bin/wt
index 6ad274b..fbedafb 100755
--- a/bin/wt
+++ b/bin/wt
@@ -1013,6 +1013,13 @@ cmd_merge() {
   if [ -n "$(git -C "$_path" status --porcelain)" ]; then
     die "$_branch has uncommitted changes — commit or stash them first"
   fi
+  # A configured worktrees.trunk (or --into) is unverified — it can name a
+  # ref this worktree cannot resolve (e.g. a remote-only branch). "cannot
+  # check" must never be treated as "nothing to merge" — mirrors cmd_rm's
+  # identical guard on the same conflation.
+  if ! git -C "$_path" rev-parse --verify --quiet "$_trunk" >/dev/null 2>&1; then
+    die "cannot verify commits ahead of $_trunk — $_trunk not found in this worktree; pass --into <branch> or set worktrees.trunk"
+  fi
   _ahead="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
   if [ "$_ahead" -eq 0 ]; then die "$_branch has no commits ahead of $_trunk"; fi
 
@@ -1051,23 +1058,35 @@ $_body"
   fi
   git -C "$_path" reset --soft "$_base" >&2
   if ! git -C "$_path" commit -q -m "$_msg" >&2; then
-    git -C "$_path" reset --hard "$_orig" >&2
-    die "squash commit failed — $_branch restored to $_orig"
+    git -C "$_path" reset --hard "$_orig" >&2 \
+      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
+    die "squash commit failed — $_branch restored to $_orig (backup: $_backup)"
   fi
 
   # ---- rebase ----
   if ! git -C "$_path" rebase "$_trunk" >&2; then
-    git -C "$_path" rebase --abort >/dev/null 2>&1 || true
-    git -C "$_path" reset --hard "$_orig" >&2
-    die "rebase of $_branch onto $_trunk hit a conflict — $_branch restored to $_orig
+    # A mid-rebase HEAD is detached — refs/heads/$_branch still points at
+    # the squash commit until the rebase completes, so a bare "rebase
+    # --abort" is not enough to trust: if it fails, fall back to forcing
+    # the branch checked out, then move the branch ref itself back to
+    # $_orig explicitly rather than relying on whatever state the abort
+    # left behind. Only then reset the working tree/index to match — this
+    # guarantees the branch, not just some detached HEAD, ends up restored.
+    git -C "$_path" rebase --abort >/dev/null 2>&1 \
+      || git -C "$_path" checkout -f "$_branch" >/dev/null 2>&1 || true
+    git -C "$_path" update-ref "refs/heads/$_branch" "$_orig"
+    git -C "$_path" reset --hard "$_orig" >&2 \
+      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
+    die "rebase of $_branch onto $_trunk hit a conflict — $_branch restored to $_orig (backup: $_backup)
 resolve by hand:  git -C $_path rebase $_trunk"
   fi
 
   # ---- fast-forward trunk ----
   _trunk_before="$(git -C "$PRIMARY" rev-parse "$_trunk")"
   if ! git -C "$PRIMARY" merge --ff-only "$_branch" >&2; then
-    git -C "$_path" reset --hard "$_orig" >&2
-    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch restored to $_orig"
+    git -C "$_path" reset --hard "$_orig" >&2 \
+      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
+    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch restored to $_orig (backup: $_backup)"
   fi
   note "merged $_branch into $_trunk"
   note "undo:   git -C $PRIMARY reset --hard $_trunk_before   (branch backup: $_backup)"
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index cc37d86..502cc28 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -325,6 +325,7 @@ new_repo mergerepo
 wtdir="$TMP/mergerepo-worktrees/feat_work"
 ( cd "$wtdir" && echo one > one.txt && git add one.txt && git commit -qm "add one" )
 ( cd "$wtdir" && echo two > two.txt && git add two.txt && git commit -qm "add two" )
+pre_merge_head="$(git -C "$wtdir" rev-parse HEAD)"
 
 before="$(git -C "$REPO" rev-parse master)"
 "$WT" merge feat/work >/dev/null 2>&1
@@ -342,8 +343,14 @@ assert_contains "$(git -C "$REPO" log -1 --format=%s)" "add one" \
 assert_contains "$(git -C "$REPO" log -1 --format=%B)" "add two" \
   "merge: remaining subjects form the body"
 assert_eq "1" "$(test -d "$wtdir" && echo 0 || echo 1)" "merge: worktree removed by default"
-assert_contains "$(git -C "$REPO" show-ref)" "refs/wt/premerge/feat_work" \
-  "merge: backup ref kept as the undo"
+# Proves both the ref's name AND its value/timing: the squash's parent is
+# the merge-base (the repo's init commit), not "add one" — so a backup
+# written after the squash (instead of before) would point at a commit
+# with a different parent than pre_merge_head, and this would catch it
+# regardless of any commit-timestamp coincidence.
+backup_head="$(git -C "$REPO" rev-parse --verify --quiet refs/wt/premerge/feat_work 2>/dev/null || echo MISSING)"
+assert_eq "$pre_merge_head" "$backup_head" \
+  "merge: backup ref captures the branch's pre-squash HEAD, written before the rewrite"
 
 # --no-remove leaves the worktree in place
 "$WT" new feat/stay >/dev/null 2>&1
@@ -353,10 +360,23 @@ assert_eq "0" "$(test -d "$TMP/mergerepo-worktrees/feat_stay" && echo 0 || echo
   "merge --no-remove: worktree survives"
 
 # a conflicting rebase restores the branch exactly and leaves the worktree alone
+#
+# feat/conflict gets TWO commits (not one) deliberately: squashing a
+# single-commit branch can produce a commit identical in every field but
+# timestamp to the original, and if both land in the same wall-clock
+# second, the squash commit hashes IDENTICALLY to $orig — so a bare
+# "rebase --abort" (no explicit restore at all) would coincidentally leave
+# HEAD at a SHA equal to $orig, and the SHA-equality assertion below would
+# pass even with the restore code deleted. Two commits make the squash
+# collapse two parents into one, which changes the history SHAPE
+# (2 commits -> 1) regardless of any timestamp coincidence, so the
+# rev-list --count assertion cannot pass by accident.
 new_repo conflictrepo
 echo base > f.txt && git add f.txt && git commit -qm base
+base="$(git -C "$REPO" rev-parse HEAD)"
 "$WT" new feat/conflict >/dev/null 2>&1
 cdir="$TMP/conflictrepo-worktrees/feat_conflict"
+( cd "$cdir" && echo mid > mid.txt && git add mid.txt && git commit -qm mid )
 ( cd "$cdir" && echo theirs > f.txt && git add f.txt && git commit -qm theirs )
 orig="$(git -C "$cdir" rev-parse HEAD)"
 echo ours > f.txt && git add f.txt && git commit -qm ours
@@ -365,6 +385,8 @@ master_before="$(git -C "$REPO" rev-parse master)"
 assert_fails "merge: conflict is an error" "$WT" merge feat/conflict
 assert_eq "$orig" "$(git -C "$cdir" rev-parse HEAD)" \
   "merge: branch restored to its pre-squash commit after a conflict"
+assert_eq "2" "$(git -C "$cdir" rev-list --count "$base..HEAD")" \
+  "merge: pre-squash history restored, not just aborted"
 assert_eq "$master_before" "$(git -C "$REPO" rev-parse master)" \
   "merge: master untouched after a conflict"
 assert_eq "0" "$(test -d "$cdir" && echo 0 || echo 1)" "merge: worktree survives a conflict"
@@ -387,6 +409,62 @@ echo primarydirt > "$REPO/dirt.txt"
 assert_fails "merge: refuses when the primary checkout is dirty" "$WT" merge feat/ok
 rm -f "$REPO/dirt.txt"
 
+# trunk not checked out at the primary. assert_fails alone is not enough
+# here: without this guard, "wt merge feat/tc" would ff-only-merge into
+# whatever IS checked out ("other") instead of refusing, and since "other"
+# happens to be fully mergeable it exits 0 having done real damage — so
+# what actually proves the guard fired is that master (the real trunk)
+# never moved, not just a nonzero exit.
+new_repo trunkcheckoutrepo
+"$WT" new feat/tc >/dev/null 2>&1
+( cd "$TMP/trunkcheckoutrepo-worktrees/feat_tc" && echo t > t.txt && git add t.txt && git commit -qm t )
+git -C "$REPO" checkout -qb other
+master_before_tc="$(git -C "$REPO" rev-parse master)"
+assert_fails "merge: refuses when trunk is not checked out at the primary" "$WT" merge feat/tc
+assert_eq "0" "$(test -d "$TMP/trunkcheckoutrepo-worktrees/feat_tc" && echo 0 || echo 1)" \
+  "merge: refused-trunk-checkout worktree survives"
+assert_eq "$master_before_tc" "$(git -C "$REPO" rev-parse master)" \
+  "merge: refused-trunk-checkout master untouched — the guard fires before any rewrite"
+
+# a branch with an upstream is refused unless --force (squashing would
+# rewrite already-published history) — this is --force's only consumer
+# in wt merge, so exercise both the refusal and the override.
+#
+# assert_fails alone is not enough here either: without this guard, the
+# squash/rebase/ff-only-merge all still succeed (master DOES advance), and
+# the command only fails at the very end, when "git branch -d" hits ITS
+# OWN unrelated safety check (a branch not merged to its upstream) — an
+# entirely different, incidental refusal that fires only after the
+# destructive rewrite already happened. The real proof our guard (not
+# git's) is what's stopping this is that master and the branch never move.
+new_repo upstreamrepo
+remote_bare="$TMP/upstream-bare.git"
+git init -q --bare "$remote_bare"
+"$WT" new feat/pushed >/dev/null 2>&1
+pdir="$TMP/upstreamrepo-worktrees/feat_pushed"
+( cd "$pdir" && echo p > p.txt && git add p.txt && git commit -qm p )
+git -C "$pdir" remote add origin "$remote_bare"
+git -C "$pdir" push -q origin feat/pushed
+git -C "$pdir" branch -q --set-upstream-to=origin/feat/pushed feat/pushed
+pushed_head="$(git -C "$pdir" rev-parse HEAD)"
+master_before_upstream="$(git -C "$REPO" rev-parse master)"
+
+assert_fails "merge: refuses a branch with an upstream without --force" "$WT" merge feat/pushed
+assert_eq "0" "$(test -d "$pdir" && echo 0 || echo 1)" \
+  "merge: refused-upstream worktree survives"
+assert_eq "$master_before_upstream" "$(git -C "$REPO" rev-parse master)" \
+  "merge: refused-upstream master untouched — the guard fires before any rewrite"
+assert_eq "$pushed_head" "$(git -C "$pdir" rev-parse HEAD)" \
+  "merge: refused-upstream branch untouched — the guard fires before any rewrite"
+
+upstream_before="$(git -C "$REPO" rev-parse master)"
+"$WT" merge feat/pushed --force >/dev/null 2>&1
+if [ "$upstream_before" = "$(git -C "$REPO" rev-parse master)" ]; then
+  fail "merge --force: overrides the upstream guard and merges anyway"
+else
+  ok "merge --force: overrides the upstream guard and merges anyway"
+fi
+
 # wt merge from inside the worktree being merged must survive the cwd being
 # yanked out from under it (git worktree remove deletes the cwd, then
 # git branch -d's getcwd() call dies) and still land the caller in the

From 4ec5991839e3d08801f932bdf85d52f373411f1a Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 21:20:43 +0700
Subject: [PATCH 11/15] wt 0.2.0: doctor checks, template config, and docs for
 the lifecycle commands

---
 README.md                     | 165 +++++++++++++++++++++++++++++++++-
 bin/wt                        |  34 ++++++-
 package.json                  |   2 +-
 templates/compose/django.yml  |  17 ++++
 templates/compose/go.yml      |  17 ++++
 templates/compose/laravel.yml |  16 ++++
 templates/compose/node.yml    |  17 ++++
 templates/compose/rails.yml   |  16 ++++
 templates/host/django.yml     |  16 ++++
 templates/host/go.yml         |  16 ++++
 templates/host/laravel.yml    |  16 ++++
 templates/host/node.yml       |  16 ++++
 templates/host/rails.yml      |  16 ++++
 test/lifecycle.sh             |  38 ++++++++
 14 files changed, 396 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index cd66216..68ff9c5 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ server, port, and database.**
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-none-2ea44f)](#install)
 [![license](https://img.shields.io/github/license/VSN2015/worktree-kit?color=blue)](LICENSE)
 
-[Install](#install) · [Setup](#per-repo-setup) · [Config](#config-reference) · [Commands](#daily-use) · [Stack guides](#stack-guide-rails-on-docker-compose) · [Caveats](#caveats)
+[Install](#install) · [Setup](#per-repo-setup) · [Config](#config-reference) · [Commands](#daily-use) · [Shell integration](#shell-integration) · [Stack guides](#stack-guide-rails-on-docker-compose) · [Caveats](#caveats)
 
 </div>
 
@@ -122,6 +122,10 @@ gracefully.
 version: 1              # schema version; reserved, not read today
 runner: compose         # compose | host — how commands run (default: compose)
 
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"   # last segment becomes the slug
+  # trunk: master                              # optional; what `wt merge` targets
+
 compose:                # read only when runner: compose
   service: app          # docker-compose.yml service whose image runs your code
   workdir: /app         # where that image expects the checkout
@@ -148,6 +152,8 @@ isolation:
   db_check: "bundle exec rails runner \"ActiveRecord::Base.connection.execute('SELECT 1 FROM schema_migrations LIMIT 1')\""
   db_bootstrap: "SKIP_TEST_DATABASE=1 bundle exec rails db:create db:schema:load"
   migration_paths: [db/migrate]
+  db_drop: "SKIP_TEST_DATABASE=1 bundle exec rails db:drop"
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
 ```
 
 ### runner
@@ -162,6 +168,25 @@ isolation:
   directory with the isolation env vars exported. `wt server` daemonizes with
   nohup and tracks a pidfile under `.git/wt-state/`.
 
+### worktrees.path / worktrees.trunk
+
+- **`path`** (default `{parent}/{repo}-worktrees/{branch}`) — where
+  `wt new <branch>` creates the worktree. **The last path segment becomes
+  the slug**, and the slug names the port, the Redis `{n}` slot, and the
+  `wt_{slug}` database — so keep `{branch}` (or `{branch_raw}`) last. A
+  template whose last segment isn't branch-unique (a fixed literal, say)
+  makes every worktree share one slug, and with it one port, one Redis DB,
+  and one database; `wt doctor` warns when it detects this. The expanded
+  path also can't contain a space — `wt`'s compose args and host env lists
+  are built by word-splitting, so `wt new` refuses such a path and
+  `wt doctor` warns about it too. `worktrees.path` is the natural key to
+  override per user in `worktree-kit.local.yml` — everyone shares the
+  repo's stack config but can keep worktrees under their own preferred
+  directory.
+- **`trunk`** (default: `origin/HEAD`, then `main`, then `master`) — the
+  branch `wt merge` merges into, and the branch `wt rm` checks a branch is
+  fully merged against before removing it without `--force`.
+
 ### compose.service / compose.workdir
 
 `service` (default `app`) names the service in your `docker-compose.yml`
@@ -230,6 +255,14 @@ Three levels, each a superset of the last:
   checkout. If the worktree has files the primary lacks (i.e. new
   migrations), `wt server` auto-escalates that worktree to `own_db`, because
   migrating the shared DB would break every other branch.
+- **`db_drop`** (optional) — destroys the per-worktree database. `wt rm` and
+  `wt merge` run it only when the worktree's database carries a `.dbowned`
+  marker — i.e. `db_bootstrap` created it, as opposed to `db_check` merely
+  finding one that already existed, and `wt reset` hasn't cleared that
+  marker since. Without `db_drop` configured (or when the database was only
+  adopted), wt prints the database name and leaves it in place.
+- **`redis_flush`** (optional) — empties this worktree's Redis DB `{n}` on
+  `wt rm` / `wt merge`. Without it, the DB is left as-is.
 
 > [!IMPORTANT]
 > **wt only exports env vars — your app config must read them.** Nothing
@@ -391,6 +424,36 @@ Two consequences of how slugs work:
 - The worktree itself carries no config; running `wt` from the primary
   checkout also works and is always treated as `shared`.
 
+## Shell integration
+
+`wt switch`, `wt new`, `wt rm`, and `wt merge` can all change which worktree
+you're standing in — but a subprocess can never `cd` its parent shell, so wt
+prints the target path on stdout (the "cd channel") and leaves the actual
+`cd` to your shell. Wire that up once:
+
+```sh
+eval "$(wt shell-init zsh)"      # or: bash, fish
+```
+
+Add that line to `~/.zshrc` (or `~/.bashrc`, or fish's `config.fish`) and
+open a new shell. It defines a `wt` shell function that intercepts `switch`,
+`new`, `rm`, and `merge` — running the real binary with
+`WT_SHELL_INTEGRATION=1` set (so `wt doctor` can report it as active) and
+`cd`-ing to whatever path it printed. Every other subcommand passes straight
+through to the real `wt`.
+
+Without it, those four commands still do everything else they normally do —
+they just print the path instead of changing directory:
+
+```sh
+$ wt switch feat/login
+/Users/you/code/myapp-worktrees/feat_login
+wt: not cd'd — install shell integration: eval "$(wt shell-init zsh)"
+```
+
+so `cd "$(wt switch feat/login)"` works too, if you'd rather not install the
+function.
+
 ## Daily use
 
 Every command takes its context from the directory you run it in: `wt`
@@ -411,8 +474,14 @@ running.
 | `wt logs [slug]`                        | follow a server's logs                              |
 | `wt localize <file...>`                 | snapshot a personal overlay (`--list` / `--remove`) |
 | `wt reset [slug]`                       | clear the own-db bootstrap marker                   |
+| `wt new <branch> [--from <base>] [--server]` | create a branch + worktree                     |
+| `wt switch [<branch>]`                  | cd to a worktree; no argument opens a picker        |
+| `wt rm [<branch>] [--keep-branch] [--force]` | tear down and remove a worktree                |
+| `wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]` | squash, rebase, fast-forward trunk, then tear down |
+| `wt list [--all]`                       | list worktrees (branch, slug, status, server, isolation) |
 | `wt init`                               | write `worktree-kit.yml` from a stack template      |
 | `wt doctor`                             | environment + config checks                         |
+| `wt shell-init [bash\|zsh\|fish]`       | emit the shell function that makes `switch`/`new`/`rm`/`merge` cd |
 
 The isolation flags `--shared` / `--isolated` / `--own-db` work on `run`,
 `server`, and `up`; the [isolation](#isolation) section above covers what
@@ -559,13 +628,101 @@ Clears the marker that records "this worktree's database was bootstrapped",
 so the next `--own-db` run bootstraps again. It only clears the marker — the
 `wt_<slug>` database itself is never dropped; that's yours.
 
+### wt new — create a branch + worktree
+
+```sh
+wt new <branch> [--from <base>] [--server]
+```
+
+Creates the branch (or adopts an existing one of the same name) and a
+`git worktree add` at `worktrees.path`, runs `hooks.prepare` once, and prints
+the new worktree's path on the cd channel (see
+[Shell integration](#shell-integration)). `--from <base>` branches off
+`<base>` instead of `HEAD`; `--server` starts the server immediately instead
+(it runs `prepare` itself, so plain `wt new` doesn't also run it, to avoid
+running the hook twice).
+
+```sh
+wt new feat/login                    # new branch + worktree off HEAD
+wt new feat/login --from origin/main # off a specific base
+wt new feat/login --server           # + start its server right away
+```
+
+### wt switch — jump to a worktree
+
+```sh
+wt switch [<branch>]
+```
+
+Prints the worktree path for `<branch>` on the cd channel — or, with no
+argument, opens an interactive picker (`fzf` if installed, else a numbered
+menu) over every worktree, with a preview pane showing recent log and
+status. Needs [shell integration](#shell-integration) to actually `cd`;
+without it, `wt switch` just prints the path.
+
+### wt rm — tear down a worktree
+
+```sh
+wt rm [<branch>] [--keep-branch] [--force]
+```
+
+Stops the worktree's server, drops its database via `isolation.db_drop` —
+but only when the database carries a `.dbowned` marker, meaning wt itself
+bootstrapped it rather than merely adopting one `db_check` found already
+there (`wt reset` clears that marker, so an adopted-after-reset database is
+left in place with a notice instead) — flushes its Redis slot if
+`isolation.redis_flush` is configured, then removes the git worktree and
+deletes the branch. Defaults to the branch checked out in the current
+worktree. Prompts for confirmation, and refuses when the worktree is dirty
+or has commits not yet in the [trunk](#worktreespath--worktreestrunk);
+`--force` waives both the safety checks and the confirmation prompt.
+`--keep-branch` removes the worktree but leaves the branch.
+
+### wt merge — squash, rebase, fast-forward, tear down
+
+```sh
+wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]
+```
+
+Squashes every commit on `<branch>` since it diverged from the
+[trunk](#worktreespath--worktreestrunk) into one commit, rebases that commit
+onto the trunk, fast-forwards the trunk to it in the primary checkout, then
+tears the worktree down exactly like `wt rm` does — **without prompting**. A
+backup ref (`refs/wt/premerge/<slug>`) captures the branch's pre-squash HEAD
+before anything is rewritten; a squash failure, a rebase conflict, or a
+non-fast-forward trunk all restore the branch to that commit and leave the
+worktree in place, with the recovery command printed. `--into <trunk>`
+overrides `worktrees.trunk` for this run; `-m <msg>` sets the squash commit
+message (default: the first commit's subject, remaining subjects as the
+body); `--no-remove` merges without tearing down.
+
+> [!IMPORTANT]
+> `wt merge` never prompts — there is nothing for `--force` to skip there.
+> Its `--force` only waives the one guard that exists: refusing to squash a
+> branch that has an upstream (squashing would rewrite already-published
+> history). This is different from `wt rm --force`, which waives both the
+> safety refusals *and* the confirmation prompt.
+
+### wt list — see every worktree
+
+```sh
+wt list [--all]
+```
+
+A table of every worktree: branch, slug, git status (`clean`/`dirty`),
+running server (if any), isolation level, and path. `--all` also lists
+branches that have no worktree.
+
 ### wt init / wt doctor — setup and checks
 
 `wt init` detects the stack and writes `worktree-kit.yml` (see
 [Per-repo setup](#per-repo-setup)). `wt doctor` prints the version, primary
-and worktree paths with slug and `{n}`, the config and runner in use, which
-YAML backend was auto-detected, whether docker is up (compose repos), and
-flags stale overlays. Run it after any config change.
+and worktree paths with slug and `{n}`, the config and runner in use, the
+resolved `worktrees.path` template (warning if its last segment isn't
+branch-unique, or if it expands to a path containing a space), which YAML
+backend was auto-detected, whether docker is up (compose repos), whether
+`fzf` is installed, whether shell integration is active, and flags stale
+overlays. Run it after any config change.
 
 ## Overlays (`wt localize`)
 
diff --git a/bin/wt b/bin/wt
index fbedafb..e54406d 100755
--- a/bin/wt
+++ b/bin/wt
@@ -13,7 +13,7 @@
 # docker compose only for `runner: compose` repos.
 set -eu
 
-WT_VERSION="0.1.8"
+WT_VERSION="0.2.0"
 
 die() { echo "wt: $*" >&2; exit 1; }
 note() { echo "wt: $*" >&2; }
@@ -796,6 +796,18 @@ cmd_doctor() {
   echo "primary:   $PRIMARY"
   echo "worktree:  $WT_PATH (slug: $SLUG, n: $N)"
   if [ -f "$CONFIG" ]; then require_config; echo "config:    $CONFIG (runner: $RUNNER, cache: $WT_CFG_SRC)"; else echo "config:    MISSING — run wt init"; fi
+  load_config_soft
+  _tmpl="$(path_template)"
+  echo "wt path:   $_tmpl"
+  _last="${_tmpl##*/}"
+  case "$_last" in
+    *'{branch}'*|*'{branch_raw}'*) ;;
+    *) echo "WARN: worktrees.path's last segment is not branch-unique — every worktree would share a slug, and with it a port, redis slot, and database" ;;
+  esac
+  _probe="$(expand_path "$_tmpl" wt-doctor-probe)"
+  case "$_probe" in
+    *" "*) echo "WARN: worktrees.path expands to a path containing a space ($_probe) — wt new will refuse it" ;;
+  esac
   yaml_backend
   case "$YAML_BACKEND" in
     yq)     echo "yaml:      $(yq --version)" ;;
@@ -809,6 +821,26 @@ cmd_doctor() {
       [ "$PRIMARY/$f" -nt "$OVERLAY_DIR/$f" ] && echo "STALE overlay: $f (source is newer — wt localize $f)"
     done
   fi
+
+  if command -v fzf >/dev/null 2>&1; then
+    echo "fzf:       $(fzf --version 2>/dev/null | head -1)"
+  else
+    echo "fzf:       not installed (wt switch falls back to a numbered menu)"
+  fi
+
+  if [ -n "${WT_SHELL_INTEGRATION:-}" ]; then
+    echo "shell:     integration active"
+  else
+    _rc_found=""
+    for _rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.config/fish/config.fish"; do
+      if [ -f "$_rc" ] && grep -q 'wt shell-init' "$_rc" 2>/dev/null; then _rc_found="$_rc"; break; fi
+    done
+    if [ -n "$_rc_found" ]; then
+      echo "shell:     shell-init found in $_rc_found (open a new shell to activate)"
+    else
+      echo "shell:     unknown — no WT_SHELL_INTEGRATION set and no 'wt shell-init' in your rc files"
+    fi
+  fi
   echo "ok"
 }
 
diff --git a/package.json b/package.json
index 47c2e79..3955c41 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "worktree-kit",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "wt — run commands and app servers per git worktree, with per-worktree database/Redis isolation",
   "bin": {
     "wt": "bin/wt"
diff --git a/templates/compose/django.yml b/templates/compose/django.yml
index f407b6a..fc1b52f 100644
--- a/templates/compose/django.yml
+++ b/templates/compose/django.yml
@@ -11,6 +11,14 @@
 version: 1        # schema marker; reserved, not read today
 runner: compose   # one-off containers with the worktree mounted over workdir
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 compose:
   service: web    # your compose service whose IMAGE runs your code
   workdir: /app   # where that image expects the checkout
@@ -48,3 +56,12 @@ isolation:
   db_bootstrap: "python manage.py migrate"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: ["*/migrations"]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place. -h/-U shown for
+  # postgres (host = your compose db service); adjust for your engine.
+  db_drop: "psql -h db -U postgres -c 'DROP DATABASE IF EXISTS wt_{slug}'"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/compose/go.yml b/templates/compose/go.yml
index 8debde1..1765242 100644
--- a/templates/compose/go.yml
+++ b/templates/compose/go.yml
@@ -11,6 +11,14 @@
 version: 1        # schema marker; reserved, not read today
 runner: compose   # one-off containers with the worktree mounted over workdir
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 compose:
   service: app    # your compose service whose IMAGE runs your code
   workdir: /app   # where that image expects the checkout
@@ -47,3 +55,12 @@ isolation:
   db_bootstrap: "go run ./cmd/migrate"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place. Same host as
+  # DATABASE_URL above (your compose db service).
+  db_drop: "dropdb -h db --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/compose/laravel.yml b/templates/compose/laravel.yml
index 0da0780..7444179 100644
--- a/templates/compose/laravel.yml
+++ b/templates/compose/laravel.yml
@@ -15,6 +15,14 @@
 version: 1        # schema marker; reserved, not read today
 runner: compose   # one-off containers with the worktree mounted over workdir
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 compose:
   service: app             # your compose service whose IMAGE runs your code
                            # (Sail's default service is "laravel.test")
@@ -53,3 +61,11 @@ isolation:
   db_bootstrap: "mysql -hmysql -uroot -e 'CREATE DATABASE IF NOT EXISTS wt_{slug}' 2>/dev/null; php artisan migrate --force"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [database/migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "php artisan db:wipe --force"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/compose/node.yml b/templates/compose/node.yml
index 739e852..72ce6e9 100644
--- a/templates/compose/node.yml
+++ b/templates/compose/node.yml
@@ -11,6 +11,14 @@
 version: 1        # schema marker; reserved, not read today
 runner: compose   # one-off containers with the worktree mounted over workdir
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 compose:
   service: app    # your compose service whose IMAGE runs your code
   workdir: /app   # where that image expects the checkout
@@ -49,3 +57,12 @@ isolation:
   db_bootstrap: "npx prisma db push"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [prisma/migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place. Same host as
+  # DATABASE_URL above (your compose db service).
+  db_drop: "dropdb -h db --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/compose/rails.yml b/templates/compose/rails.yml
index 044c1a6..a0d9c9f 100644
--- a/templates/compose/rails.yml
+++ b/templates/compose/rails.yml
@@ -16,6 +16,14 @@ version: 1        # schema marker; reserved, not read today
 runner: compose   # compose = one-off `docker compose run` containers on your
                   # already-running stack; host = plain processes
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 compose:          # read only when runner: compose
   service: app    # docker-compose.yml service whose IMAGE runs your code
   workdir: /app   # where that image expects the checkout (copy from your
@@ -76,3 +84,11 @@ isolation:
   db_bootstrap: "SKIP_TEST_DATABASE=1 bundle exec rails db:create db:schema:load"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [db/migrate]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "SKIP_TEST_DATABASE=1 bundle exec rails db:drop"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/host/django.yml b/templates/host/django.yml
index 1904f86..597f608 100644
--- a/templates/host/django.yml
+++ b/templates/host/django.yml
@@ -11,6 +11,14 @@
 version: 1     # schema marker; reserved, not read today
 runner: host   # plain processes in the worktree dir with the isolation env exported
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 hooks:
   # prepare: runs before EVERY wt run / wt server — idempotent dependency self-heal.
   prepare: "pip install -q -r requirements.txt"
@@ -41,3 +49,11 @@ isolation:
   db_bootstrap: "python manage.py migrate"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: ["*/migrations"]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "dropdb --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -n {n} flushdb"
diff --git a/templates/host/go.yml b/templates/host/go.yml
index 1fb322c..c5778f1 100644
--- a/templates/host/go.yml
+++ b/templates/host/go.yml
@@ -11,6 +11,14 @@
 version: 1     # schema marker; reserved, not read today
 runner: host   # plain processes in the worktree dir with the isolation env exported
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 hooks:
   # server: the long-running command; on the host runner use {port} directly.
   # (No prepare hook needed — `go run` resolves modules itself.)
@@ -36,3 +44,11 @@ isolation:
   db_bootstrap: "createdb wt_{slug} 2>/dev/null; go run ./cmd/migrate"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "dropdb --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -n {n} flushdb"
diff --git a/templates/host/laravel.yml b/templates/host/laravel.yml
index 1213408..0b9809b 100644
--- a/templates/host/laravel.yml
+++ b/templates/host/laravel.yml
@@ -14,6 +14,14 @@
 version: 1     # schema marker; reserved, not read today
 runner: host   # plain processes in the worktree dir with the isolation env exported
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 hooks:
   # prepare: runs before EVERY wt run / wt server — idempotent dependency self-heal.
   prepare: "composer install --quiet"
@@ -45,3 +53,11 @@ isolation:
   db_bootstrap: "mysql -uroot -e 'CREATE DATABASE IF NOT EXISTS wt_{slug}' 2>/dev/null; php artisan migrate --force"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [database/migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "php artisan db:wipe --force"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -n {n} flushdb"
diff --git a/templates/host/node.yml b/templates/host/node.yml
index a633e98..cea365f 100644
--- a/templates/host/node.yml
+++ b/templates/host/node.yml
@@ -11,6 +11,14 @@
 version: 1     # schema marker; reserved, not read today
 runner: host   # plain processes in the worktree dir with the isolation env exported
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 hooks:
   # prepare: runs before EVERY wt run / wt server — idempotent dependency self-heal.
   prepare: "npm ci --prefer-offline 2>/dev/null || npm install"
@@ -37,3 +45,11 @@ isolation:
   db_bootstrap: "createdb wt_{slug} 2>/dev/null; npx prisma db push"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [prisma/migrations]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "dropdb --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -n {n} flushdb"
diff --git a/templates/host/rails.yml b/templates/host/rails.yml
index 3fcdd44..ce54da2 100644
--- a/templates/host/rails.yml
+++ b/templates/host/rails.yml
@@ -11,6 +11,14 @@
 version: 1     # schema marker; reserved, not read today
 runner: host   # plain processes in the worktree dir with the isolation env exported
 
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+
 hooks:
   # prepare: runs before EVERY wt run / wt server — idempotent dependency self-heal.
   prepare: "bundle check >/dev/null 2>&1 || bundle install --jobs=4 --retry=3"
@@ -49,3 +57,11 @@ isolation:
   db_bootstrap: "SKIP_TEST_DATABASE=1 bundle exec rails db:create db:schema:load"
   # Dirs compared against the primary to auto-escalate a server to own_db.
   migration_paths: [db/migrate]
+  # db_drop (optional): destroys the per-worktree DB. `wt rm`/`wt merge` run
+  # it only when the .dbowned marker is set — i.e. this worktree's DB was
+  # bootstrapped by wt, not merely adopted (db_check found one already
+  # there), and `wt reset` hasn't since cleared that marker. Without this
+  # key wt prints the DB name and leaves it in place.
+  db_drop: "SKIP_TEST_DATABASE=1 bundle exec rails db:drop"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  redis_flush: "redis-cli -n {n} flushdb"
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 502cc28..4cc8e3d 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -477,5 +477,43 @@ cwdrepo_repo="$REPO"
 out="$( (cd "$wtdir_incwd" && "$WT" merge feat/incwd 2>/dev/null) || true )"
 assert_eq "$cwdrepo_repo" "$out" "merge: from inside the worktree, prints the primary for cd"
 
+# ---------- Task 6: doctor ----------
+
+new_repo doctorrepo
+out="$("$WT" doctor 2>&1)"
+assert_contains "$out" "wt path:" "doctor: reports the path template"
+assert_contains "$out" "fzf:"     "doctor: reports fzf availability"
+assert_contains "$out" "shell:"   "doctor: reports shell integration state"
+
+out="$(WT_SHELL_INTEGRATION=1 "$WT" doctor 2>&1)"
+assert_contains "$out" "integration active" "doctor: detects an active wrapper"
+
+# The two template warnings need a YAML backend to read the .local file, AND
+# a main worktree-kit.yml to exist — load_config_soft gates on $CONFIG (the
+# non-local file), not $LOCAL_CONFIG, so with only the .local file present
+# HAS_CONFIG stays 0 and path_template() never consults either file. runner:
+# host is mandatory here (not compose) — require_config would otherwise
+# demand docker, which is not running in this environment.
+if command -v yq >/dev/null 2>&1 || command -v ruby >/dev/null 2>&1 \
+   || python3 -c 'import yaml' >/dev/null 2>&1; then
+  printf 'runner: host\nhooks:\n  server: "true"\n' > worktree-kit.yml
+  cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/{repo}-worktrees/fixed"
+YML
+  out="$("$WT" doctor 2>&1)"
+  assert_contains "$out" "not branch-unique" "doctor: warns on a non-branch-unique template"
+
+  cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/has space/{branch}"
+YML
+  out="$("$WT" doctor 2>&1)"
+  assert_contains "$out" "space" "doctor: warns on a template that yields a space"
+  rm -f worktree-kit.local.yml worktree-kit.yml
+else
+  ok "doctor: template warnings skipped (no YAML backend installed)"
+fi
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From 33285da3e23a6ab62e095a70509a5c29c9702707 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 21:42:57 +0700
Subject: [PATCH 12/15] Task 6 fix round 1: tighten doctor space assertion,
 de-risk django db_drop
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- test/lifecycle.sh: the "yields a space" doctor assertion matched the
  fixture's own path text regardless of whether the WARN line fired
  (cmd_doctor echoes the raw template unconditionally before the check
  runs). Assert on "wt new will refuse it" instead, which only the WARN
  line can produce. Verified load-bearing (RED/GREEN) along with the
  branch-unique assertion, which was already sound.
- templates/compose/django.yml: comment out db_drop — its db_bootstrap and
  own_db_env reveal no connection details at all, so the db/postgres host
  guess risked DROP DATABASE against the wrong server. redis_flush stays
  active.
- templates/{compose,host}/laravel.yml: note that the redis_flush host is
  an inference (this template exports REDIS_DB, not a REDIS_URL).
- bin/wt: usage() said shell-init "makes switch cd"; the wrapper actually
  intercepts switch/new/rm/merge.
---
 bin/wt                        | 2 +-
 templates/compose/django.yml  | 9 ++++++---
 templates/compose/laravel.yml | 3 +++
 templates/host/laravel.yml    | 2 ++
 test/lifecycle.sh             | 6 +++++-
 5 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/bin/wt b/bin/wt
index e54406d..6b01a93 100755
--- a/bin/wt
+++ b/bin/wt
@@ -1198,7 +1198,7 @@ wt — worktree-aware runner (config: worktree-kit.yml at the primary checkout)
   wt list [--all]        list worktrees (branch, slug, status, server, isolation)
   wt init                write worktree-kit.yml from a stack template
   wt doctor              environment + config checks
-  wt shell-init [bash|zsh|fish]   emit the shell function that makes switch cd
+  wt shell-init [bash|zsh|fish]   emit the shell function that makes switch/new/rm/merge cd
 EOF
 }
 
diff --git a/templates/compose/django.yml b/templates/compose/django.yml
index fc1b52f..c8ea71c 100644
--- a/templates/compose/django.yml
+++ b/templates/compose/django.yml
@@ -60,8 +60,11 @@ isolation:
   # it only when the .dbowned marker is set — i.e. this worktree's DB was
   # bootstrapped by wt, not merely adopted (db_check found one already
   # there), and `wt reset` hasn't since cleared that marker. Without this
-  # key wt prints the DB name and leaves it in place. -h/-U shown for
-  # postgres (host = your compose db service); adjust for your engine.
-  db_drop: "psql -h db -U postgres -c 'DROP DATABASE IF EXISTS wt_{slug}'"
+  # key wt prints the DB name and leaves it in place. Left commented out:
+  # Django reads its DB connection from settings.py, which this file never
+  # sees, so wt has no host/user/engine to connect with — guessing one would
+  # risk a DROP DATABASE against the wrong server. Fill in your real
+  # connection before enabling, e.g.:
+  # db_drop: "psql -h <your-db-host> -U <your-db-user> -c 'DROP DATABASE IF EXISTS wt_{slug}'"
   # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
   redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/compose/laravel.yml b/templates/compose/laravel.yml
index 7444179..681f335 100644
--- a/templates/compose/laravel.yml
+++ b/templates/compose/laravel.yml
@@ -68,4 +68,7 @@ isolation:
   # key wt prints the DB name and leaves it in place.
   db_drop: "php artisan db:wipe --force"
   # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  # Host assumed as "redis" — this template exports REDIS_DB, not a REDIS_URL,
+  # so there's no host to read here; adjust if your compose redis service has
+  # a different name.
   redis_flush: "redis-cli -h redis -n {n} flushdb"
diff --git a/templates/host/laravel.yml b/templates/host/laravel.yml
index 0b9809b..9fe6d10 100644
--- a/templates/host/laravel.yml
+++ b/templates/host/laravel.yml
@@ -60,4 +60,6 @@ isolation:
   # key wt prints the DB name and leaves it in place.
   db_drop: "php artisan db:wipe --force"
   # redis_flush (optional): empties this worktree's redis db on `wt rm`/`wt merge`.
+  # Host assumed as localhost — this template exports REDIS_DB, not a
+  # REDIS_URL, so there's no host to read here.
   redis_flush: "redis-cli -n {n} flushdb"
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 4cc8e3d..e54b428 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -509,7 +509,11 @@ worktrees:
   path: "{parent}/has space/{branch}"
 YML
   out="$("$WT" doctor 2>&1)"
-  assert_contains "$out" "space" "doctor: warns on a template that yields a space"
+  # Not "space" alone: the unconditional "wt path:" line above already
+  # echoes the raw template, which contains "has space" from the fixture's
+  # own directory name — that substring would match whether or not the WARN
+  # line fires. Assert on text only the WARN line itself can produce.
+  assert_contains "$out" "wt new will refuse it" "doctor: warns on a template that yields a space"
   rm -f worktree-kit.local.yml worktree-kit.yml
 else
   ok "doctor: template warnings skipped (no YAML backend installed)"

From b04fdb459c9289109e903189e49aaa93188b4370 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 22:02:27 +0700
Subject: [PATCH 13/15] wt merge fix round 2: force-delete the merged branch,
 make silent test aborts diagnosable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root cause of a flake (1-in-5 observed): remove_worktree_and_branch was
called with force=0, so branch teardown used plain "git branch -d". After
a squash+rebase, the branch's tip is a new commit object, and git's -d
refuses to delete a branch that is merged into HEAD but not merged into
its own configured upstream tracking ref — a real but redundant check
here, since a successful --ff-only merge already proves every commit is
reachable from trunk. Whether that check fired depended on a same-second
commit-timestamp coincidence in the squash, and when it fired, "wt merge"
died under set -e; since the test's "wt merge ... --force" call was a bare
statement, that nonzero exit killed the whole suite silently — no FAIL
line, no LIFECYCLE FAIL, just truncated output.

- cmd_merge now passes force=1 to remove_worktree_and_branch (git branch
  -D), with a comment explaining why this is safe and warning against
  reverting it. Accepted consequence: worktree removal also becomes
  --force (discards untracked files) — not routed around, since refusing
  at this point would strand the user with trunk already advanced and the
  database already dropped.
- Wrapped every bare "$WT" new/merge invocation in the Task 5 test block
  (not already inside assert_fails) with "|| fail ...", so a future
  regression produces a visible FAIL line and reaches LIFECYCLE FAIL
  instead of silently truncating the run.

Verified: reverting force=1 alone reproduced the flake immediately (now
failing loudly instead of silently); with both fixes applied, 30
consecutive full-suite runs plus 4 dash runs, all clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bin/wt            | 15 ++++++++++++++-
 test/lifecycle.sh | 24 ++++++++++++------------
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/bin/wt b/bin/wt
index 6b01a93..9693f8c 100755
--- a/bin/wt
+++ b/bin/wt
@@ -1135,7 +1135,20 @@ resolve by hand:  git -C $_path rebase $_trunk"
   # this does not retarget teardown_worktree's own_db/redis work.
   if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; cd "$PRIMARY"; fi
   teardown_worktree "$_slug" "$_path"
-  remove_worktree_and_branch "$_branch" "$_path" 0 0
+  # force=1 here (not 0): the --ff-only merge above already PROVED every
+  # commit on $_branch is reachable from $_trunk — that is what a
+  # fast-forward is — so plain "git branch -d"'s own "have I merged this?"
+  # safety check is redundant and can misfire: a branch with a (now stale)
+  # upstream tracking ref is merged to HEAD but not to that upstream, and
+  # -d refuses on that alone even though the invariant it exists to protect
+  # already holds. Do NOT harden this back to 0 — that would make `wt
+  # merge` on a pushed branch fail after $_trunk has already advanced and
+  # teardown has already run, the worst possible place to fail. This also
+  # makes the worktree removal itself --force (discards untracked files in
+  # $_path); that is accepted, not a bug to route around — we already
+  # refused earlier on a dirty worktree, and teardown can leave new files
+  # behind between that check and here.
+  remove_worktree_and_branch "$_branch" "$_path" 0 1
   if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
 }
 
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index e54b428..1f9eb1c 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -321,14 +321,14 @@ assert_eq "1" "$(test -f "$rstate/someslug.dbowned" && echo 0 || echo 1)" \
 # ---------- Task 5: merge ----------
 
 new_repo mergerepo
-"$WT" new feat/work >/dev/null 2>&1
+"$WT" new feat/work >/dev/null 2>&1 || fail "merge: setup — wt new feat/work failed"
 wtdir="$TMP/mergerepo-worktrees/feat_work"
 ( cd "$wtdir" && echo one > one.txt && git add one.txt && git commit -qm "add one" )
 ( cd "$wtdir" && echo two > two.txt && git add two.txt && git commit -qm "add two" )
 pre_merge_head="$(git -C "$wtdir" rev-parse HEAD)"
 
 before="$(git -C "$REPO" rev-parse master)"
-"$WT" merge feat/work >/dev/null 2>&1
+"$WT" merge feat/work >/dev/null 2>&1 || fail "merge: feat/work merge failed"
 after="$(git -C "$REPO" rev-parse master)"
 
 # assert_eq "1" "$(test A = B; echo $?)" dies inside the substitution under
@@ -353,9 +353,9 @@ assert_eq "$pre_merge_head" "$backup_head" \
   "merge: backup ref captures the branch's pre-squash HEAD, written before the rewrite"
 
 # --no-remove leaves the worktree in place
-"$WT" new feat/stay >/dev/null 2>&1
+"$WT" new feat/stay >/dev/null 2>&1 || fail "merge --no-remove: setup — wt new feat/stay failed"
 ( cd "$TMP/mergerepo-worktrees/feat_stay" && echo s > s.txt && git add s.txt && git commit -qm stay )
-"$WT" merge feat/stay --no-remove >/dev/null 2>&1
+"$WT" merge feat/stay --no-remove >/dev/null 2>&1 || fail "merge --no-remove: merge failed"
 assert_eq "0" "$(test -d "$TMP/mergerepo-worktrees/feat_stay" && echo 0 || echo 1)" \
   "merge --no-remove: worktree survives"
 
@@ -374,7 +374,7 @@ assert_eq "0" "$(test -d "$TMP/mergerepo-worktrees/feat_stay" && echo 0 || echo
 new_repo conflictrepo
 echo base > f.txt && git add f.txt && git commit -qm base
 base="$(git -C "$REPO" rev-parse HEAD)"
-"$WT" new feat/conflict >/dev/null 2>&1
+"$WT" new feat/conflict >/dev/null 2>&1 || fail "merge: setup — wt new feat/conflict failed"
 cdir="$TMP/conflictrepo-worktrees/feat_conflict"
 ( cd "$cdir" && echo mid > mid.txt && git add mid.txt && git commit -qm mid )
 ( cd "$cdir" && echo theirs > f.txt && git add f.txt && git commit -qm theirs )
@@ -395,15 +395,15 @@ assert_eq "" "$(git -C "$cdir" status --porcelain)" \
 
 # guards
 new_repo guardrepo
-"$WT" new feat/empty >/dev/null 2>&1
+"$WT" new feat/empty >/dev/null 2>&1 || fail "merge: setup — wt new feat/empty failed"
 assert_fails "merge: refuses a branch with no commits ahead" "$WT" merge feat/empty
 
-"$WT" new feat/dirty >/dev/null 2>&1
+"$WT" new feat/dirty >/dev/null 2>&1 || fail "merge: setup — wt new feat/dirty failed"
 ( cd "$TMP/guardrepo-worktrees/feat_dirty" && echo d > d.txt && git add d.txt \
     && git commit -qm d && echo x > x.txt )
 assert_fails "merge: refuses a dirty worktree" "$WT" merge feat/dirty
 
-"$WT" new feat/ok >/dev/null 2>&1
+"$WT" new feat/ok >/dev/null 2>&1 || fail "merge: setup — wt new feat/ok failed"
 ( cd "$TMP/guardrepo-worktrees/feat_ok" && echo o > o.txt && git add o.txt && git commit -qm o )
 echo primarydirt > "$REPO/dirt.txt"
 assert_fails "merge: refuses when the primary checkout is dirty" "$WT" merge feat/ok
@@ -416,7 +416,7 @@ rm -f "$REPO/dirt.txt"
 # what actually proves the guard fired is that master (the real trunk)
 # never moved, not just a nonzero exit.
 new_repo trunkcheckoutrepo
-"$WT" new feat/tc >/dev/null 2>&1
+"$WT" new feat/tc >/dev/null 2>&1 || fail "merge: setup — wt new feat/tc failed"
 ( cd "$TMP/trunkcheckoutrepo-worktrees/feat_tc" && echo t > t.txt && git add t.txt && git commit -qm t )
 git -C "$REPO" checkout -qb other
 master_before_tc="$(git -C "$REPO" rev-parse master)"
@@ -440,7 +440,7 @@ assert_eq "$master_before_tc" "$(git -C "$REPO" rev-parse master)" \
 new_repo upstreamrepo
 remote_bare="$TMP/upstream-bare.git"
 git init -q --bare "$remote_bare"
-"$WT" new feat/pushed >/dev/null 2>&1
+"$WT" new feat/pushed >/dev/null 2>&1 || fail "merge: setup — wt new feat/pushed failed"
 pdir="$TMP/upstreamrepo-worktrees/feat_pushed"
 ( cd "$pdir" && echo p > p.txt && git add p.txt && git commit -qm p )
 git -C "$pdir" remote add origin "$remote_bare"
@@ -458,7 +458,7 @@ assert_eq "$pushed_head" "$(git -C "$pdir" rev-parse HEAD)" \
   "merge: refused-upstream branch untouched — the guard fires before any rewrite"
 
 upstream_before="$(git -C "$REPO" rev-parse master)"
-"$WT" merge feat/pushed --force >/dev/null 2>&1
+"$WT" merge feat/pushed --force >/dev/null 2>&1 || fail "merge --force: merge failed"
 if [ "$upstream_before" = "$(git -C "$REPO" rev-parse master)" ]; then
   fail "merge --force: overrides the upstream guard and merges anyway"
 else
@@ -470,7 +470,7 @@ fi
 # git branch -d's getcwd() call dies) and still land the caller in the
 # primary via the cd channel — the same defect Task 4 fixed for wt rm.
 new_repo cwdrepo
-"$WT" new feat/incwd >/dev/null 2>&1
+"$WT" new feat/incwd >/dev/null 2>&1 || fail "merge: setup — wt new feat/incwd failed"
 wtdir_incwd="$TMP/cwdrepo-worktrees/feat_incwd"
 ( cd "$wtdir_incwd" && echo w > w.txt && git add w.txt && git commit -qm w )
 cwdrepo_repo="$REPO"

From 18c11f50f55f12989c204e67070042f72512df2b Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 22:45:19 +0700
Subject: [PATCH 14/15] =?UTF-8?q?wt:=20final=20review=20fixes=20=E2=80=94?=
 =?UTF-8?q?=20teardown=20targeting,=20path=20escaping,=20guarded=20removal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Whole-branch review of the lifecycle layer found seven defects that the
per-task reviews could not see, because each only spanned one command.

bin/wt:

- remove_worktree_and_branch ran four bare git calls AFTER teardown had
  already stopped the server, dropped the database and deleted every state
  file. A failure there aborted under set -e with only git's stderr: no
  "removed" line, no emit_cd, so a shell-wrapper caller was left in a
  deleted directory. The worktree removal now dies with a message saying
  the reclaim already happened; branch deletion only notes. The reachable
  trigger was `git branch -d`, which asks "merged into HEAD?" — not the
  "merged into trunk?" question cmd_rm already answered — so removing a
  sibling worktree could strand a branch wt had verified.

- teardown_worktree borrowed SLUG and N for the target but not WT_PATH,
  which is what runner_exec keys off. hooks.prepare therefore re-ran in the
  CALLER's worktree on every rm/merge of another worktree, and db_drop /
  redis_flush resolved relative paths against the wrong tree. The unused
  _tp parameter was the tell.

- expand_path fed {parent}, {repo}, {branch_raw} and {home} to sed as
  replacement text, where & means the whole match. The default template
  uses two of them, so a repo directory named "R&D-app" silently expanded
  {repo} to "R{repo}D-app" — and that path's last segment names the slug,
  the port, the redis slot and the database.

- $HOME was dereferenced unguarded under set -u in the {home} expansion and
  the rc-file scan; an unset HOME (env -i, some CI runners) died bare.

- The fish wrapper used a single-command variable override, a syntax error
  on older fish, which would break wt entirely for those users.

- The no-.dbowned notice claimed the database was "adopted, not created by
  wt". That is false for every worktree provisioned before this release —
  .dbowned did not exist — which is exactly who sees it first on upgrade.

- A failed restore in cmd_merge printed "could not restore" and then died
  saying "restored to <sha>", on the one path where the user is panicking.
  One helper now prints a single, true outcome.

test/lifecycle.sh (84 -> 110 assertions):

- Both PATH=/usr/bin:/bin scrubs would have misbehaved in the container
  suites: docker lives in /usr/bin on Linux, inverting the server-stop
  assertion, and the truncation can remove the YAML backend. They now drop
  only directories that hold docker, shimming git and the backend first.

- Guarded ~20 setup calls and captures that ran bare under set -eu, so a
  regression FAILs with a diagnostic instead of truncating the run.

- First coverage of worktrees.path from the committed config (only the
  .local path was exercised); stdout purity for rm and merge; the reason
  behind the three refusals that matter; a real rebase-state check; and the
  removal of an assertion that had no code path able to fail it.

Docs: README spells out that removal deletes the whole directory including
gitignored files, that merge tears down like `rm --force` rather than `rm`,
that hyphens fold in {branch}, and how pre-0.2.0 databases behave. The
design spec is amended in three places where the implementation knowingly
diverged, each marked as a resolved deviation.

Verified on /bin/sh and dash, six consecutive runs, 110 assertions, no
flake. test/linux.sh not run — docker daemon is down.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   42 +-
 bin/wt                                        |  114 +-
 .../plans/2026-08-29-worktree-lifecycle.md    | 1431 +++++++++++++++++
 .../2026-08-29-worktree-lifecycle-design.md   |  436 +++++
 test/lifecycle.sh                             |  352 +++-
 5 files changed, 2287 insertions(+), 88 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-08-29-worktree-lifecycle.md
 create mode 100644 docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md

diff --git a/README.md b/README.md
index 68ff9c5..82516e1 100644
--- a/README.md
+++ b/README.md
@@ -173,7 +173,16 @@ isolation:
 - **`path`** (default `{parent}/{repo}-worktrees/{branch}`) — where
   `wt new <branch>` creates the worktree. **The last path segment becomes
   the slug**, and the slug names the port, the Redis `{n}` slot, and the
-  `wt_{slug}` database — so keep `{branch}` (or `{branch_raw}`) last. A
+  `wt_{slug}` database — so keep `{branch}` (or `{branch_raw}`) last.
+  `{branch}` folds every character outside `[A-Za-z0-9._]` to `_`,
+  **hyphens included**: `wt new feat/refund-flow` gives directory (and slug)
+  `feat_refund_flow`, not `feat_refund-flow`. That is on purpose — it makes
+  the directory name and the slug identical, so what you see in `wt list` is
+  exactly what names your database. (`.` is the one survivor: branch
+  `feat.x` gives directory `feat.x` but slug `feat_x`.) `{branch_raw}` keeps
+  the branch name verbatim, slashes and all — which nests directories and
+  makes only the final segment the slug, so use it in a middle segment, not
+  the last one. A
   template whose last segment isn't branch-unique (a fixed literal, say)
   makes every worktree share one slug, and with it one port, one Redis DB,
   and one database; `wt doctor` warns when it detects this. The expanded
@@ -261,6 +270,15 @@ Three levels, each a superset of the last:
   finding one that already existed, and `wt reset` hasn't cleared that
   marker since. Without `db_drop` configured (or when the database was only
   adopted), wt prints the database name and leaves it in place.
+  Two cases leave a database wt *did* create without that marker, and both
+  are deliberate — wt errs toward keeping data:
+  **(a)** databases bootstrapped **before wt 0.2.0**, when `.dbowned` did not
+  exist yet. On your first `wt rm` after upgrading, those report "no
+  ownership marker" and are left alone; drop them by hand, or run one
+  `wt reset <slug>` + `--own-db` cycle to re-bootstrap and re-mark them.
+  **(b)** a database re-adopted after `wt reset`: `db_check` (which the rails
+  templates configure) only ever writes `.dbready`, so the database that
+  `db_check` finds on the next run is never re-marked as owned.
 - **`redis_flush`** (optional) — empties this worktree's Redis DB `{n}` on
   `wt rm` / `wt merge`. Without it, the DB is left as-is.
 
@@ -678,6 +696,14 @@ or has commits not yet in the [trunk](#worktreespath--worktreestrunk);
 `--force` waives both the safety checks and the confirmation prompt.
 `--keep-branch` removes the worktree but leaves the branch.
 
+> [!WARNING]
+> `git worktree remove` deletes the **entire worktree directory**, not just
+> git's registration of it — including files git never tracked: `.env`, local
+> SQLite databases, uploads, `tmp/`, everything `.gitignore` covers. The
+> dirty-worktree refusal does not protect these; it only looks at tracked and
+> untracked files, and ignored files are invisible to it. Copy anything you
+> want to keep out first.
+
 ### wt merge — squash, rebase, fast-forward, tear down
 
 ```sh
@@ -687,9 +713,12 @@ wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]
 Squashes every commit on `<branch>` since it diverged from the
 [trunk](#worktreespath--worktreestrunk) into one commit, rebases that commit
 onto the trunk, fast-forwards the trunk to it in the primary checkout, then
-tears the worktree down exactly like `wt rm` does — **without prompting**. A
-backup ref (`refs/wt/premerge/<slug>`) captures the branch's pre-squash HEAD
-before anything is rewritten; a squash failure, a rebase conflict, or a
+tears the worktree down like **`wt rm --force`** does — `git worktree remove
+--force` plus `git branch -D`, and **without prompting**. That deletes the
+whole worktree directory, gitignored files included (`.env`, local databases,
+uploads, `tmp/`), with no confirmation step in between. A backup ref
+(`refs/wt/premerge/<slug>`) captures the branch's pre-squash HEAD before
+anything is rewritten; a squash failure, a rebase conflict, or a
 non-fast-forward trunk all restore the branch to that commit and leave the
 worktree in place, with the recovery command printed. `--into <trunk>`
 overrides `worktrees.trunk` for this run; `-m <msg>` sets the squash commit
@@ -701,7 +730,10 @@ body); `--no-remove` merges without tearing down.
 > Its `--force` only waives the one guard that exists: refusing to squash a
 > branch that has an upstream (squashing would rewrite already-published
 > history). This is different from `wt rm --force`, which waives both the
-> safety refusals *and* the confirmation prompt.
+> safety refusals *and* the confirmation prompt. Note that the teardown is
+> the forceful kind either way — passing `--force` does not make it any more
+> destructive, and omitting it does not make it any less. Use `--no-remove`
+> if you want the worktree directory kept.
 
 ### wt list — see every worktree
 
diff --git a/bin/wt b/bin/wt
index 9693f8c..b19decc 100755
--- a/bin/wt
+++ b/bin/wt
@@ -363,18 +363,28 @@ path_template() {
   printf '%s\n' "$_t"
 }
 
+# Escapes a value used as sed REPLACEMENT text, where & means "the whole
+# match", \ starts an escape, and | is our delimiter. Unlike expand()'s
+# inputs (SLUG, N, PORT, PROJECT — all already sanitized to safe charsets),
+# expand_path substitutes raw filesystem and git names: a repo directory
+# called "R&D-app" expanded {repo} to "R{repo}D-app", and a branch with a |
+# in it (legal in a git ref) broke the sed expression outright.
+_esc() { printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'; }
+
 # {branch_raw} MUST be substituted before {branch}, or the longer token is
 # eaten by the shorter one and leaves a stray "_raw".
 expand_path() { # <template> <raw-branch>
   _pb="$(sanitize_branch "$2")"
-  _pp="$(dirname "$PRIMARY")"
-  _pr="$(basename "$PRIMARY")"
+  _pp="$(_esc "$(dirname "$PRIMARY")")"
+  _pr="$(_esc "$(basename "$PRIMARY")")"
+  _praw="$(_esc "$2")"
+  _phome="$(_esc "${HOME:-}")"
   printf '%s' "$1" | sed \
-    -e "s|{branch_raw}|$2|g" \
+    -e "s|{branch_raw}|$_praw|g" \
     -e "s|{parent}|$_pp|g" \
     -e "s|{repo}|$_pr|g" \
     -e "s|{branch}|$_pb|g" \
-    -e "s|{home}|$HOME|g"
+    -e "s|{home}|$_phome|g"
 }
 
 # stdout is the cd channel: a path, and nothing else.
@@ -426,9 +436,17 @@ teardown_worktree() { # <slug> <path>
   if [ "${HAS_CONFIG:-0}" = 1 ]; then
     "$0" down "$_ts" >&2 || note "could not stop the server for $_ts — check for a stray process"
 
-    # expand() reads the globals SLUG and N; borrow them for the target slug
-    _old_slug="$SLUG"; _old_n="$N"
-    SLUG="$_ts"; N=$(( $(hashnum "$_ts") % 15 + 1 ))
+    # expand() reads the globals SLUG and N, and runner_exec reads WT_PATH
+    # (host: `cd "$WT_PATH"`; compose: `-v $WT_PATH:$WORKDIR`). Borrow all
+    # THREE for the target — borrowing only the first two left db_drop and
+    # redis_flush running against the CALLER's worktree, which re-ran that
+    # repo's hooks.prepare (bundle install, npm ci, ...) on every wt rm of
+    # another worktree and resolved relative paths in the wrong tree. Safe
+    # because teardown always runs before the directory is removed, and
+    # cmd_rm's process-level `cd "$PRIMARY"` is unaffected: runner_exec's
+    # host branch cds inside its own subshell.
+    _old_slug="$SLUG"; _old_n="$N"; _old_path="$WT_PATH"
+    SLUG="$_ts"; N=$(( $(hashnum "$_ts") % 15 + 1 )); WT_PATH="$_tp"
 
     if [ -f "$STATE_DIR/$_ts.dbready" ]; then
       if [ -f "$STATE_DIR/$_ts.dbowned" ]; then
@@ -440,7 +458,12 @@ teardown_worktree() { # <slug> <path>
           note "no isolation.db_drop configured — the database for slug $_ts is left in place"
         fi
       else
-        note "database for slug $_ts was adopted, not created by wt — leaving it in place"
+        # Two populations reach here and the notice must be true for both:
+        # a database db_check merely adopted, AND every database wt itself
+        # bootstrapped before 0.2.0, when .dbowned did not yet exist. Saying
+        # "adopted, not created by wt" is simply wrong for the second — and
+        # the second is what every upgrading user sees on their first wt rm.
+        note "no ownership marker for $_ts (databases bootstrapped before wt 0.2.0 have none) — leaving the database in place; drop it by hand if you want it gone"
       fi
     fi
 
@@ -452,7 +475,7 @@ teardown_worktree() { # <slug> <path>
       note "no isolation.redis_flush configured — redis db $N is left as is"
     fi
 
-    SLUG="$_old_slug"; N="$_old_n"
+    SLUG="$_old_slug"; N="$_old_n"; WT_PATH="$_old_path"
   fi
 
   rm -f "$STATE_DIR/$_ts.pid" "$STATE_DIR/$_ts.port" \
@@ -460,22 +483,51 @@ teardown_worktree() { # <slug> <path>
   true
 }
 
+# Both callers run teardown_worktree BEFORE this — the irreversible half:
+# server stopped, database dropped, redis slot flushed, every state file
+# removed. So a bare failure here is the worst kind: set -e aborts on the
+# spot, the user sees only git's stderr, "removed" never prints, and emit_cd
+# never runs, leaving a shell-wrapper caller sitting in a deleted directory
+# with no explanation. Every git call below is therefore guarded.
 remove_worktree_and_branch() { # <branch> <path> <keep_branch 0|1> <force 0|1>
+  _rm_hint="could not remove the worktree at $2 — its server, database and state were already reclaimed; remove the directory by hand, then run: git worktree prune"
   if [ "$4" = 1 ]; then
-    git worktree remove --force "$2" >&2
+    git worktree remove --force "$2" >&2 || die "$_rm_hint"
   else
-    git worktree remove "$2" >&2
+    git worktree remove "$2" >&2 || die "$_rm_hint"
   fi
   if [ "$3" = 0 ]; then
     if [ "$4" = 1 ]; then
-      git branch -D "$1" >&2
+      git branch -D "$1" >&2 \
+        || note "worktree removed, but git refused to delete branch $1 — delete it with: git branch -D $1"
     else
-      git branch -d "$1" >&2
+      # -d asks "is this merged into HEAD (or its upstream)?", which is NOT
+      # the question cmd_rm already answered ("merged into trunk?"). Removing
+      # a SIBLING worktree leaves cwd — and so HEAD — on the caller's own
+      # branch, so -d can refuse a branch wt has verified. note, not die: the
+      # branch is the one recoverable thing left, and dying here would skip
+      # emit_cd and strand a shell-wrapper caller in a deleted directory.
+      git branch -d "$1" >&2 \
+        || note "worktree removed, but git refused to delete branch $1 (not merged into HEAD) — delete it with: git branch -D $1"
     fi
   fi
   true
 }
 
+# Puts the worktree at $1 back on $2 after a failed merge step, and prints
+# the tail of the caller's die message so the two lines a panicking user
+# reads tell ONE story. The old shape printed "could not restore the
+# worktree" and then died saying "$branch restored to $orig" — flatly
+# contradictory, on the one path where the user most needs to be told the
+# truth. git's own output goes to stderr, so it never reaches this stdout.
+restore_after_merge() { # <path> <orig-sha> <backup-ref> -> phrase on stdout
+  if git -C "$1" reset --hard "$2" >&2; then
+    printf 'restored to %s (backup: %s)' "$2" "$3"
+  else
+    printf 'could NOT be restored — recover by hand: git -C %s reset --hard %s' "$1" "$3"
+  fi
+}
+
 confirm() { # <prompt> — 0 on yes, reading stdin
   printf '%s [y/N] ' "$1" >&2
   read -r _ans || _ans=n
@@ -832,7 +884,10 @@ cmd_doctor() {
     echo "shell:     integration active"
   else
     _rc_found=""
-    for _rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.config/fish/config.fish"; do
+    # ${HOME:-}, not $HOME: env -i, some CI runners and some container
+    # entrypoints leave HOME unset, where set -u makes a bare $HOME fatal.
+    _home="${HOME:-}"
+    for _rc in "$_home/.zshrc" "$_home/.bashrc" "$_home/.bash_profile" "$_home/.config/fish/config.fish"; do
       if [ -f "$_rc" ] && grep -q 'wt shell-init' "$_rc" 2>/dev/null; then _rc_found="$_rc"; break; fi
     done
     if [ -n "$_rc_found" ]; then
@@ -992,7 +1047,7 @@ cmd_rm() {
 
   _slug="$(slugify "$_path")"
   note "about to remove:"
-  note "  worktree  $_path"
+  note "  worktree  $_path (directory deleted, including untracked and ignored files)"
   if [ "$_keep" = 0 ]; then note "  branch    $_branch"; fi
   note "  state     $STATE_DIR/$_slug.*"
   if [ "${HAS_CONFIG:-0}" = 1 ] && [ -f "$STATE_DIR/$_slug.dbready" ]; then
@@ -1007,8 +1062,9 @@ cmd_rm() {
   # are inside it; the very next git call (branch -d/-D) then fails calling
   # getcwd() ("Unable to read current working directory") and set -e kills
   # cmd_rm before the branch is deleted or emit_cd runs. Step out first.
-  # runner_exec keys off $WT_PATH (a fixed global), not the live cwd, so
-  # this does not retarget teardown_worktree's own_db/redis work.
+  # runner_exec keys off $WT_PATH, not the live cwd, and teardown_worktree
+  # sets $WT_PATH to the target itself, so this cd does not retarget its
+  # own_db/redis work either way.
   if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; cd "$PRIMARY"; fi
 
   teardown_worktree "$_slug" "$_path"
@@ -1090,9 +1146,7 @@ $_body"
   fi
   git -C "$_path" reset --soft "$_base" >&2
   if ! git -C "$_path" commit -q -m "$_msg" >&2; then
-    git -C "$_path" reset --hard "$_orig" >&2 \
-      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
-    die "squash commit failed — $_branch restored to $_orig (backup: $_backup)"
+    die "squash commit failed — $_branch $(restore_after_merge "$_path" "$_orig" "$_backup")"
   fi
 
   # ---- rebase ----
@@ -1107,18 +1161,14 @@ $_body"
     git -C "$_path" rebase --abort >/dev/null 2>&1 \
       || git -C "$_path" checkout -f "$_branch" >/dev/null 2>&1 || true
     git -C "$_path" update-ref "refs/heads/$_branch" "$_orig"
-    git -C "$_path" reset --hard "$_orig" >&2 \
-      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
-    die "rebase of $_branch onto $_trunk hit a conflict — $_branch restored to $_orig (backup: $_backup)
+    die "rebase of $_branch onto $_trunk hit a conflict — $_branch $(restore_after_merge "$_path" "$_orig" "$_backup")
 resolve by hand:  git -C $_path rebase $_trunk"
   fi
 
   # ---- fast-forward trunk ----
   _trunk_before="$(git -C "$PRIMARY" rev-parse "$_trunk")"
   if ! git -C "$PRIMARY" merge --ff-only "$_branch" >&2; then
-    git -C "$_path" reset --hard "$_orig" >&2 \
-      || note "could not restore the worktree — recover by hand: git -C $_path reset --hard $_backup"
-    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch restored to $_orig (backup: $_backup)"
+    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch $(restore_after_merge "$_path" "$_orig" "$_backup")"
   fi
   note "merged $_branch into $_trunk"
   note "undo:   git -C $PRIMARY reset --hard $_trunk_before   (branch backup: $_backup)"
@@ -1131,8 +1181,9 @@ resolve by hand:  git -C $_path rebase $_trunk"
   # are inside it; the very next git call (branch -d/-D) then fails calling
   # getcwd() ("Unable to read current working directory") and set -e kills
   # cmd_merge before the branch is deleted or emit_cd runs. Step out first.
-  # runner_exec keys off $WT_PATH (a fixed global), not the live cwd, so
-  # this does not retarget teardown_worktree's own_db/redis work.
+  # runner_exec keys off $WT_PATH, not the live cwd, and teardown_worktree
+  # sets $WT_PATH to the target itself, so this cd does not retarget its
+  # own_db/redis work either way.
   if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; cd "$PRIMARY"; fi
   teardown_worktree "$_slug" "$_path"
   # force=1 here (not 0): the --ff-only merge above already PROVED every
@@ -1172,11 +1223,16 @@ wt() {
 EOF
       ;;
     fish)
+      # `env VAR=x wt`, not `VAR=x command wt`: fish gained single-command
+      # variable overrides late, and on older releases that form is a SYNTAX
+      # error — which would make `eval (wt shell-init fish)` break wt
+      # outright for those users. env resolves wt from PATH, so it finds the
+      # real binary rather than recursing into this function.
       cat <<'EOF'
 function wt
   switch "$argv[1]"
     case switch new rm merge
-      set -l __wt_d (WT_SHELL_INTEGRATION=1 command wt $argv)
+      set -l __wt_d (env WT_SHELL_INTEGRATION=1 wt $argv)
       or return $status
       if test -n "$__wt_d"
         cd $__wt_d
diff --git a/docs/superpowers/plans/2026-08-29-worktree-lifecycle.md b/docs/superpowers/plans/2026-08-29-worktree-lifecycle.md
new file mode 100644
index 0000000..61a81c5
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-29-worktree-lifecycle.md
@@ -0,0 +1,1431 @@
+# Worktree Lifecycle Commands Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add `new`, `switch`, `list`, `rm`, `merge`, and `shell-init` to `bin/wt`, so a worktree can be created, found, merged, and fully torn down — reclaiming the server, database, Redis slot, and state files the kit provisioned for it.
+
+**Architecture:** The five lifecycle commands are a peer layer that needs only `git`. `require_config` is split into a soft loader (`load_config_soft`, sets `HAS_CONFIG`) and the existing strict wrapper; the ten existing commands keep the strict wrapper and behave identically. Stdout becomes a dedicated "cd channel" — lifecycle commands print a path there and nothing else, with all human output on stderr, so a shell wrapper can `cd` to it.
+
+**Tech Stack:** POSIX sh (`bin/wt`, one file, `set -eu`). `git` is the only hard dependency of this layer; `fzf` is optional. Tests are linear shell scripts with `grep`/`case` assertions, matching `test/linux-alpine.sh`.
+
+**Spec:** `docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md`
+
+## Global Constraints
+
+These apply to **every** task. Copied from the spec and CONTEXT.md.
+
+- **One file.** All code goes in `bin/wt`. No `lib/`, no new runtime files. CONTEXT.md §2 rejected `lib/*.sh` for vendoring simplicity.
+- **POSIX sh only.** No bashisms in `bin/wt` — it runs under dash and BusyBox ash. No arrays, no `[[`, no `local` (except inside the emitted *user-shell* function in Task 3, which runs in bash/zsh).
+- **CONTEXT.md §5 bug 1 — never let a function end with `[ cond ] && cmd`.** Under `set -e` a false condition makes the function return nonzero and kills the caller. Use explicit `if`, or end the function with `true`. This applies to the shell snippets `shell-init` emits, too.
+- **CONTEXT.md §7 — word-splitting is load-bearing.** Worktree paths must never contain spaces.
+- **Slug derivation is frozen.** `slugify(basename(path))` at `bin/wt:30-36` must not change; it determines existing ports, Redis slots, and database names.
+- **Lookup is always `git worktree list --porcelain`,** never a recomputed path template.
+- **Stdout is the cd channel.** Only a path, or nothing. Every note, every git subcommand's chatter, every hook's output goes to stderr.
+- **Config gating.** Read config only when `HAS_CONFIG=1`; `cfg_get`/`local_get` are not safe to call otherwise.
+- **`wt --version` is bumped once, in Task 6.** Do not bump it in earlier tasks.
+- **Variable naming.** `bin/wt` has no `local`, so every variable is global. Every new variable in this plan is `_`-prefixed to avoid colliding with `ctx_init`'s globals.
+
+### Two deliberate deviations from the spec
+
+1. **ASCII status markers.** The spec's §9 example shows up/down arrows and an em-dash. Use `+2` / `-1` / `-` instead. BusyBox `printf` and `column` handle multibyte width inconsistently, and the Alpine suite compares column output. Cosmetic only.
+2. **The backup ref survives a successful merge.** The spec (§10.2) introduces `refs/wt/premerge/<slug>` for failure recovery. Keeping it after success too costs nothing and is the only undo for a squash plus fast-forward. `wt merge` prints the undo command on success.
+
+---
+
+## File Structure
+
+| File | Responsibility | Tasks |
+|---|---|---|
+| `bin/wt` | All implementation. New helpers grouped in a `# ---------- lifecycle ----------` section placed after `worktree_paths()` (line 266) and before `# ---------- ports ----------`. Command functions (`cmd_*`) go with the other `cmd_*` functions. | 1-6 |
+| `test/lifecycle.sh` | New. Git-only lifecycle suite: scratch repos in a temp dir, no docker, no YAML backend. Runnable directly on macOS. | 1-6 |
+| `test/linux-debian.sh`, `test/linux-alpine.sh` | Modified. Each gains one line invoking `test/lifecycle.sh`. | 1 |
+| `templates/{compose,host}/*.yml` | Modified (10 files). Gain a `worktrees:` block and `isolation.db_drop` / `isolation.redis_flush`. | 6 |
+| `README.md` | Modified. New commands, shell integration, config reference entries. | 6 |
+
+---
+
+## Task 1: Test harness, soft config loading, and `wt list`
+
+**Files:**
+- Create: `test/lifecycle.sh`
+- Modify: `bin/wt:53-64` (`require_config` split), `bin/wt:266` (add lifecycle section), `bin/wt:592-628` (usage + dispatch)
+- Modify: `test/linux-debian.sh`, `test/linux-alpine.sh` (one line each)
+
+**Interfaces:**
+- Consumes: `slugify()`, `local_get()`, `cfg_get()`, `load_config()`, `note()`, `die()`, and the `ctx_init` globals `PRIMARY`, `WT_PATH`, `STATE_DIR`, `PROJECT`, `CONFIG`.
+- Produces:
+  - `load_config_soft()` — sets `HAS_CONFIG=0|1`; on 1 also sets `RUNNER`, `SERVICE`, `WORKDIR`, `CONTAINER_PORT`, `PREPARE`, `BUILD`, `SERVER_CMD`. Never exits.
+  - `require_config()` — unchanged contract: dies when there is no config.
+  - `resolve_trunk()` — prints the trunk branch name, or empty.
+  - `worktree_for_branch <branch>` — prints the worktree path for a branch, or empty. Exit status is always 0.
+  - `worktree_rows()` — prints one TAB-separated row per worktree: `branch  slug  status  server  iso  path`.
+  - `TAB` — a global holding a literal tab.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `test/lifecycle.sh`:
+
+```sh
+#!/bin/sh
+# Lifecycle command tests — git only. No docker, no YAML backend required.
+# Run directly:            ./test/lifecycle.sh
+# Or from a linux suite:   sh /src/test/lifecycle.sh
+set -eu
+
+WT="${WT:-wt}"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAILED=0
+TAB="$(printf '\t')"
+
+ok()   { printf 'ok   - %s\n' "$1"; }
+fail() { printf 'FAIL - %s\n' "$1" >&2; FAILED=1; }
+
+assert_eq() { # <expected> <actual> <label>
+  if [ "$1" = "$2" ]; then ok "$3"; else fail "$3: expected [$1] got [$2]"; fi
+}
+
+assert_contains() { # <haystack> <needle> <label>
+  case "$1" in
+    *"$2"*) ok "$3" ;;
+    *)      fail "$3: [$1] does not contain [$2]" ;;
+  esac
+}
+
+assert_missing() { # <haystack> <needle> <label>
+  case "$1" in
+    *"$2"*) fail "$3: [$1] unexpectedly contains [$2]" ;;
+    *)      ok "$3" ;;
+  esac
+}
+
+assert_fails() { # <label> <cmd...>
+  _l="$1"; shift
+  if "$@" >/dev/null 2>&1; then fail "$_l: expected nonzero exit"; else ok "$_l"; fi
+}
+
+# Creates a repo with one commit on branch `master`; sets REPO and cds into it.
+new_repo() {
+  REPO="$TMP/$1"
+  mkdir -p "$REPO"
+  cd "$REPO"
+  git init -q
+  git config user.email t@t.t
+  git config user.name t
+  git symbolic-ref HEAD refs/heads/master
+  echo hi > README.md
+  git add README.md
+  git commit -qm init
+}
+
+# ---------- Task 1: list ----------
+
+new_repo listrepo
+out="$("$WT" list)"
+assert_contains "$out" master           "list: shows the primary branch"
+assert_contains "$out" BRANCH           "list: prints a header"
+assert_missing  "$out" "MISSING"        "list: no config is not an error"
+
+git worktree add -q "$TMP/listrepo-wt" -b feat/one
+out="$("$WT" list)"
+assert_contains "$out" "feat/one"       "list: shows a second worktree"
+assert_contains "$out" "feat_one"       "list: slug matches ctx_init derivation"
+assert_contains "$out" "clean"          "list: clean worktree reports clean"
+
+echo dirty > "$TMP/listrepo-wt/x.txt"
+out="$("$WT" list)"
+assert_contains "$out" "dirty"          "list: dirty worktree reports dirty"
+
+git branch -q spare
+out="$("$WT" list --all)"
+assert_contains "$out" "spare"          "list --all: includes branches with no worktree"
+out="$("$WT" list)"
+assert_missing  "$out" "spare"          "list: plain list omits branchless branches"
+
+# existing commands must still refuse to run without a config
+assert_fails "run still requires config" "$WT" run -- true
+
+[ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
+echo "LIFECYCLE PASS"
+```
+
+Make it executable: `chmod +x test/lifecycle.sh`
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `wt: unknown command: list`
+
+- [ ] **Step 3: Split `require_config`**
+
+Replace `bin/wt:53-64` entirely with:
+
+```sh
+load_config_soft() {
+  if [ -f "$CONFIG" ]; then
+    HAS_CONFIG=1
+    load_config
+    RUNNER="$(cfg_get runner compose)"
+    SERVICE="$(cfg_get compose.service app)"
+    WORKDIR="$(cfg_get compose.workdir /app)"
+    CONTAINER_PORT="$(cfg_get hooks.container_port 3000)"
+    PREPARE="$(cfg_get hooks.prepare "")"
+    BUILD="$(cfg_get hooks.build "")"
+    SERVER_CMD="$(cfg_get hooks.server "")"
+    if [ "$RUNNER" = compose ]; then need docker; fi
+  else
+    HAS_CONFIG=0
+    RUNNER=""; SERVICE=""; WORKDIR=""; CONTAINER_PORT=3000
+    PREPARE=""; BUILD=""; SERVER_CMD=""
+  fi
+}
+
+require_config() {
+  load_config_soft
+  if [ "$HAS_CONFIG" = 0 ]; then
+    die "no worktree-kit.yml at $PRIMARY — run 'wt init' in that repo"
+  fi
+}
+```
+
+The `need docker` check moves inside the `if`, so a config-less repo never demands docker.
+
+- [ ] **Step 4: Add the lifecycle helpers**
+
+Insert after `worktree_paths()` (currently `bin/wt:266`), under a new banner:
+
+```sh
+# ---------- lifecycle ----------
+
+TAB="$(printf '\t')"
+
+resolve_trunk() { # prints the trunk branch name, or empty
+  _t=""
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    _t="$(local_get worktrees.trunk "")"
+    if [ -z "$_t" ]; then _t="$(cfg_get worktrees.trunk "")"; fi
+  fi
+  if [ -z "$_t" ]; then
+    _t="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')" || _t=""
+  fi
+  if [ -z "$_t" ]; then
+    if git show-ref --verify --quiet refs/heads/main; then
+      _t=main
+    elif git show-ref --verify --quiet refs/heads/master; then
+      _t=master
+    fi
+  fi
+  printf '%s\n' "$_t"
+}
+
+worktree_for_branch() { # <branch> -> path, or empty. Always exits 0.
+  git worktree list --porcelain | awk -v b="refs/heads/$1" '
+    /^worktree /{ p = $2 }
+    $1 == "branch" && $2 == b { print p; exit }
+  '
+  true
+}
+
+# One TAB-separated row per worktree: branch, slug, status, server, iso, path.
+# wt list and the picker both read this, so they cannot drift.
+worktree_rows() {
+  _trunk="$(resolve_trunk)"
+  git worktree list --porcelain | awk '
+    /^worktree /  { p = $2 }
+    /^branch /    { b = $2; sub("refs/heads/", "", b); print p "\t" b }
+    /^detached/   { print p "\t(detached)" }
+  ' | while IFS="$TAB" read -r _p _b; do
+    _s="$(slugify "$_p")"
+
+    _st=clean
+    if [ -n "$(git -C "$_p" status --porcelain 2>/dev/null)" ]; then _st=dirty; fi
+    if [ -n "$_trunk" ] && git -C "$_p" rev-parse --verify --quiet "$_trunk" >/dev/null 2>&1; then
+      _c="$(git -C "$_p" rev-list --left-right --count "$_trunk...HEAD" 2>/dev/null || printf '0\t0')"
+      _behind="$(printf '%s' "$_c" | cut -f1)"
+      _ahead="$(printf '%s' "$_c" | cut -f2)"
+      if [ "${_ahead:-0}"  -gt 0 ]; then _st="$_st +$_ahead"; fi
+      if [ "${_behind:-0}" -gt 0 ]; then _st="$_st -$_behind"; fi
+    fi
+
+    _srv="-"; _iso="-"
+    if [ "${HAS_CONFIG:-0}" = 1 ]; then
+      if [ "$RUNNER" = compose ]; then
+        _srv="$(docker ps --filter "label=wt.project=$PROJECT" --filter "label=wt.slug=$_s" \
+                  --format '{{.Label "wt.port"}}' 2>/dev/null | head -1)"
+        _iso="$(docker ps --filter "label=wt.project=$PROJECT" --filter "label=wt.slug=$_s" \
+                  --format '{{.Label "wt.isolation"}}' 2>/dev/null | head -1)"
+      elif [ -f "$STATE_DIR/$_s.pid" ]; then
+        _srv="$(cat "$STATE_DIR/$_s.port" 2>/dev/null || echo '?')"
+      fi
+    fi
+    if [ -n "$_srv" ] && [ "$_srv" != "-" ]; then _srv=":$_srv"; else _srv="-"; fi
+    if [ -z "$_iso" ]; then _iso="-"; fi
+
+    printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$_b" "$_s" "$_st" "$_srv" "$_iso" "$_p"
+  done
+  true
+}
+```
+
+`worktree_rows` ends with `true` — under `set -e` the trailing `while` would otherwise leak its exit status to the caller (CONTEXT.md §5 bug 1).
+
+- [ ] **Step 5: Add `cmd_list`**
+
+Insert alongside the other `cmd_*` functions, before `usage()`:
+
+```sh
+cmd_list() {
+  load_config_soft
+  _all=0
+  for _a in "$@"; do
+    case "$_a" in
+      --all) _all=1 ;;
+      *)     die "unknown flag: $_a (wt list [--all])" ;;
+    esac
+  done
+
+  _out="BRANCH${TAB}SLUG${TAB}STATUS${TAB}SERVER${TAB}ISO${TAB}PATH
+$(worktree_rows)"
+
+  if [ "$_all" = 1 ]; then
+    for _b in $(git for-each-ref --format='%(refname:short)' refs/heads); do
+      if [ -z "$(worktree_for_branch "$_b")" ]; then
+        _out="$_out
+$_b${TAB}-${TAB}(no worktree)${TAB}-${TAB}-${TAB}-"
+      fi
+    done
+  fi
+
+  if command -v column >/dev/null 2>&1; then
+    printf '%s\n' "$_out" | column -t -s "$TAB"
+  else
+    printf '%s\n' "$_out"
+  fi
+}
+```
+
+- [ ] **Step 6: Wire up dispatch and usage**
+
+In `usage()`, add above the `wt init` line:
+
+```
+  wt list [--all]        list worktrees (branch, slug, status, server, isolation)
+```
+
+In the dispatch `case`, add before `init)`:
+
+```sh
+  list) shift; cmd_list "$@" ;;
+```
+
+- [ ] **Step 7: Run the test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: all `ok -` lines, ending `LIFECYCLE PASS`
+
+- [ ] **Step 8: Hook the suite into the linux runs**
+
+In both `test/linux-debian.sh` and `test/linux-alpine.sh`, add immediately before the final `echo "... PASS"` line:
+
+```sh
+# lifecycle commands: git only, no docker, no YAML backend
+sh /src/test/lifecycle.sh
+```
+
+- [ ] **Step 9: Run the linux suites**
+
+Run: `./test/linux.sh`
+Expected: `ALL LINUX TESTS PASSED`. If docker is unavailable, run `./test/lifecycle.sh` alone and say plainly that the container suites were not run.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add bin/wt test/lifecycle.sh test/linux-debian.sh test/linux-alpine.sh
+git commit -m "wt list: worktree overview, and a config-optional loader"
+```
+
+---
+
+## Task 2: `wt new`
+
+**Files:**
+- Modify: `bin/wt` (lifecycle section, `cmd_*` section, usage, dispatch)
+- Modify: `test/lifecycle.sh` (append a section)
+
+**Interfaces:**
+- Consumes: `worktree_for_branch()`, `load_config_soft()`, `HAS_CONFIG`, `PREPARE`, `PRIMARY`.
+- Produces:
+  - `sanitize_branch <branch>` — prints a filesystem-safe branch name.
+  - `path_template()` — prints the worktree path template.
+  - `expand_path <template> <raw-branch>` — prints the expanded absolute path.
+  - `emit_cd <path>` — prints the path on stdout, plus a stderr hint when shell integration is absent.
+  - `cmd_new` — `wt new <branch> [--from <base>] [--server]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/lifecycle.sh`, immediately before the final `[ "$FAILED" = 0 ]` line:
+
+```sh
+# ---------- Task 2: new ----------
+
+new_repo newrepo
+out="$("$WT" new feat/refund-flow 2>/dev/null)"
+assert_eq "$TMP/newrepo-worktrees/feat_refund_flow" "$out" \
+  "new: default template, branch sanitized for the path"
+assert_eq "0" "$(test -d "$TMP/newrepo-worktrees/feat_refund_flow"; echo $?)" \
+  "new: directory created"
+assert_contains "$(git -C "$REPO" branch --list 'feat/refund-flow')" "feat/refund-flow" \
+  "new: branch created with slashes intact"
+assert_contains "$("$WT" list)" "feat_refund_flow" "new: slug is the last path segment"
+
+# a branch that exists but has no worktree is adopted, not rejected
+git -C "$REPO" branch -q orphan
+out="$("$WT" new orphan 2>/dev/null)"
+assert_eq "$TMP/newrepo-worktrees/orphan" "$out" "new: adopts an existing branch"
+
+# a branch that already has a worktree is an error
+assert_fails "new: rejects a branch that already has a worktree" "$WT" new orphan
+
+# --from picks the base
+git -C "$REPO" checkout -q -b basis
+echo b > "$REPO/b.txt"; git -C "$REPO" add b.txt; git -C "$REPO" commit -qm basis
+git -C "$REPO" checkout -q master
+"$WT" new derived --from basis >/dev/null 2>&1
+assert_eq "0" "$(test -f "$TMP/newrepo-worktrees/derived/b.txt"; echo $?)" \
+  "new --from: branched from the named base"
+
+# a template that yields a space is refused before anything is created
+new_repo spacerepo
+cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/has space/{branch}"
+YML
+assert_fails "new: refuses a path containing a space" "$WT" new anything
+assert_eq "1" "$(test -d "$TMP/has space"; echo $?)" "new: nothing created on refusal"
+```
+
+The last two assertions need a YAML backend to read the `.local` file. On a machine with none, `path_template` falls back to the default and they will fail — report that in the run rather than weakening the test; every CI image under `test/` installs a backend.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `wt: unknown command: new`
+
+- [ ] **Step 3: Add the path-template helpers**
+
+Append to the `# ---------- lifecycle ----------` section:
+
+```sh
+sanitize_branch() { # <branch> -> filesystem-safe
+  printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_'
+}
+
+path_template() {
+  _t=""
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    _t="$(local_get worktrees.path "")"
+    if [ -z "$_t" ]; then _t="$(cfg_get worktrees.path "")"; fi
+  fi
+  if [ -z "$_t" ]; then _t='{parent}/{repo}-worktrees/{branch}'; fi
+  printf '%s\n' "$_t"
+}
+
+# {branch_raw} MUST be substituted before {branch}, or the longer token is
+# eaten by the shorter one and leaves a stray "_raw".
+expand_path() { # <template> <raw-branch>
+  _pb="$(sanitize_branch "$2")"
+  _pp="$(dirname "$PRIMARY")"
+  _pr="$(basename "$PRIMARY")"
+  printf '%s' "$1" | sed \
+    -e "s|{branch_raw}|$2|g" \
+    -e "s|{parent}|$_pp|g" \
+    -e "s|{repo}|$_pr|g" \
+    -e "s|{branch}|$_pb|g" \
+    -e "s|{home}|$HOME|g"
+}
+
+# stdout is the cd channel: a path, and nothing else.
+emit_cd() { # <path>
+  printf '%s\n' "$1"
+  if [ -z "${WT_SHELL_INTEGRATION:-}" ]; then
+    note "not cd'd — install shell integration: eval \"\$(wt shell-init zsh)\""
+  fi
+}
+```
+
+- [ ] **Step 4: Add `cmd_new`**
+
+```sh
+cmd_new() {
+  load_config_soft
+  _base=""; _start_server=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --from)   _base="${2:-}"; [ -n "$_base" ] || die "--from needs a branch or commit"; shift 2 ;;
+      --server) _start_server=1; shift ;;
+      -*)       die "unknown flag: $1 (wt new <branch> [--from <base>] [--server])" ;;
+      *)        _branch="$1"; shift ;;
+    esac
+  done
+  [ -n "$_branch" ] || die "usage: wt new <branch> [--from <base>] [--server]"
+
+  _existing="$(worktree_for_branch "$_branch")"
+  if [ -n "$_existing" ]; then
+    die "branch $_branch already has a worktree at $_existing — use: wt switch $_branch"
+  fi
+
+  _path="$(expand_path "$(path_template)" "$_branch")"
+  case "$_path" in
+    *" "*) die "worktrees.path expands to a path containing a space:
+  $_path
+wt splits unquoted strings when building compose args and host env lists, so
+worktree paths must be space-free. Change worktrees.path or the branch name." ;;
+  esac
+  if [ -e "$_path" ]; then die "$_path already exists"; fi
+
+  mkdir -p "$(dirname "$_path")"
+  if git show-ref --verify --quiet "refs/heads/$_branch"; then
+    note "adopting existing branch $_branch"
+    git worktree add "$_path" "$_branch" >&2
+  elif [ -n "$_base" ]; then
+    git worktree add -b "$_branch" "$_path" "$_base" >&2
+  else
+    git worktree add -b "$_branch" "$_path" >&2
+  fi
+
+  # Hook output goes to stderr so it cannot pollute the cd channel.
+  if [ "$HAS_CONFIG" = 1 ] && [ -n "${PREPARE:-}" ]; then
+    note "prepare: $PREPARE"
+    if ! ( cd "$_path" && "$0" run --shared -- sh -c "$PREPARE" ) >&2; then
+      die "prepare hook failed — worktree left at $_path"
+    fi
+  fi
+
+  if [ "$_start_server" = 1 ]; then
+    if [ "$HAS_CONFIG" = 0 ]; then die "--server needs worktree-kit.yml — run 'wt init'"; fi
+    ( cd "$_path" && "$0" server ) >&2 || die "server failed to start in $_path"
+  fi
+
+  emit_cd "$_path"
+}
+```
+
+- [ ] **Step 5: Wire up dispatch and usage**
+
+In `usage()`, above the `wt list` line:
+
+```
+  wt new <branch> [--from <base>] [--server]   create a branch + worktree
+```
+
+In the dispatch `case`, before `list)`:
+
+```sh
+  new) shift; cmd_new "$@" ;;
+```
+
+- [ ] **Step 6: Run the test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: `LIFECYCLE PASS`
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add bin/wt test/lifecycle.sh
+git commit -m "wt new: create or adopt a branch's worktree from a path template"
+```
+
+---
+
+## Task 3: `wt switch`, the picker, and `wt shell-init`
+
+**Files:**
+- Modify: `bin/wt` (lifecycle section, `cmd_*` section, usage, both dispatch blocks)
+- Modify: `test/lifecycle.sh` (append a section)
+
+**Interfaces:**
+- Consumes: `worktree_rows()`, `worktree_for_branch()`, `emit_cd()`, `STATE_DIR`, `TAB`.
+- Produces:
+  - `pick_worktree()` — prints the chosen worktree path on stdout; returns nonzero if the user cancels.
+  - `cmd_switch` — `wt switch [<branch>]`.
+  - `cmd_shell_init` — `wt shell-init [bash|zsh|fish]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/lifecycle.sh`, before the final `[ "$FAILED" = 0 ]` line:
+
+```sh
+# ---------- Task 3: switch and shell-init ----------
+
+new_repo switchrepo
+"$WT" new feat/alpha >/dev/null 2>&1
+
+# stdout carries only the path; the hint goes to stderr
+out="$("$WT" switch feat/alpha 2>/dev/null)"
+assert_eq "$TMP/switchrepo-worktrees/feat_alpha" "$out" "switch: stdout is the bare path"
+
+err="$("$WT" switch feat/alpha 2>&1 >/dev/null)"
+assert_contains "$err" "shell-init" "switch: hints about shell integration on stderr"
+
+err="$(WT_SHELL_INTEGRATION=1 "$WT" switch feat/alpha 2>&1 >/dev/null)"
+assert_eq "" "$err" "switch: no stderr noise under shell integration"
+
+assert_fails "switch: unknown branch is an error" "$WT" switch nope
+err="$("$WT" switch nope 2>&1 >/dev/null || true)"
+assert_contains "$err" "nope" "switch: names the branch it could not find"
+
+git -C "$REPO" branch -q lonely
+err="$("$WT" switch lonely 2>&1 >/dev/null || true)"
+assert_contains "$err" "wt new lonely" "switch: branch without a worktree points at wt new"
+
+# shell-init emits a wrapper covering all four cd-channel commands
+out="$("$WT" shell-init zsh)"
+assert_contains "$out" "switch|new|rm|merge" "shell-init: wraps every cd-channel command"
+assert_contains "$out" "WT_SHELL_INTEGRATION=1" "shell-init: exports the marker"
+assert_contains "$out" 'if [ -n "$__wt_d" ]; then' "shell-init: explicit if, not && (bug 1)"
+out="$("$WT" shell-init fish)"
+assert_contains "$out" "function wt" "shell-init: fish variant"
+assert_fails "shell-init: rejects an unknown shell" "$WT" shell-init tcsh
+
+# shell-init must work outside a git repo
+out="$(cd "$TMP" && "$WT" shell-init bash)"
+assert_contains "$out" "command wt" "shell-init: works outside a git repo"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `wt: unknown command: switch`
+
+- [ ] **Step 3: Add the picker**
+
+Append to the `# ---------- lifecycle ----------` section:
+
+```sh
+# Prints the selected worktree path. fzf draws on /dev/tty and prints only
+# the selection to stdout, so it composes with the cd channel.
+pick_worktree() {
+  _rows="$(worktree_rows)"
+  if [ -z "$_rows" ]; then die "no worktrees"; fi
+
+  if command -v fzf >/dev/null 2>&1; then
+    _sel="$(printf '%s\n' "$_rows" | fzf \
+      --delimiter="$TAB" --with-nth=1,2,3,4 \
+      --preview 'git -C {6} log --oneline -10; echo; git -C {6} status -s' \
+      --preview-window=right:60%)" || return 1
+  else
+    _tmp="$STATE_DIR/.picker.$$"
+    printf '%s\n' "$_rows" > "$_tmp"
+    _i=0
+    while IFS="$TAB" read -r _b _s _st _srv _iso _p; do
+      _i=$((_i + 1))
+      printf '%2d) %-28s %s\n' "$_i" "$_b" "$_p" >&2
+    done < "$_tmp"
+    printf 'select worktree [1-%d]: ' "$_i" >&2
+    if ! read -r _n < /dev/tty; then rm -f "$_tmp"; return 1; fi
+    case "$_n" in
+      ''|*[!0-9]*) rm -f "$_tmp"; die "not a number: $_n" ;;
+    esac
+    if [ "$_n" -lt 1 ] || [ "$_n" -gt "$_i" ]; then rm -f "$_tmp"; die "out of range: $_n"; fi
+    _sel="$(sed -n "${_n}p" "$_tmp")"
+    rm -f "$_tmp"
+  fi
+
+  printf '%s' "$_sel" | cut -f6
+}
+```
+
+- [ ] **Step 4: Add `cmd_switch` and `cmd_shell_init`**
+
+```sh
+cmd_switch() {
+  load_config_soft
+  if [ $# -eq 0 ]; then
+    _p="$(pick_worktree)" || exit 1
+    if [ -z "$_p" ]; then exit 1; fi
+    emit_cd "$_p"
+    return 0
+  fi
+
+  _p="$(worktree_for_branch "$1")"
+  if [ -z "$_p" ]; then
+    if git show-ref --verify --quiet "refs/heads/$1"; then
+      die "branch $1 has no worktree — create one: wt new $1"
+    fi
+    die "no worktree or branch named $1 (see: wt list --all)"
+  fi
+  emit_cd "$_p"
+}
+
+cmd_shell_init() {
+  _kind="${1:-}"
+  if [ -z "$_kind" ]; then _kind="$(basename "${SHELL:-sh}")"; fi
+  case "$_kind" in
+    bash|zsh)
+      cat <<'EOF'
+wt() {
+  case "${1:-}" in
+    switch|new|rm|merge)
+      local __wt_d
+      __wt_d="$(WT_SHELL_INTEGRATION=1 command wt "$@")" || return $?
+      # explicit if, not &&: a command that prints no path must still return 0
+      if [ -n "$__wt_d" ]; then cd "$__wt_d"; fi
+      ;;
+    *) command wt "$@" ;;
+  esac
+}
+EOF
+      ;;
+    fish)
+      cat <<'EOF'
+function wt
+  switch "$argv[1]"
+    case switch new rm merge
+      set -l __wt_d (WT_SHELL_INTEGRATION=1 command wt $argv)
+      or return $status
+      if test -n "$__wt_d"
+        cd $__wt_d
+      end
+    case '*'
+      command wt $argv
+  end
+end
+EOF
+      ;;
+    *) die "unsupported shell: $_kind (bash, zsh, fish)" ;;
+  esac
+}
+```
+
+- [ ] **Step 5: Wire up dispatch and usage**
+
+In `usage()`, after the `wt new` line:
+
+```
+  wt switch [<branch>]   cd to a worktree; no argument opens a picker
+```
+
+and after the `wt doctor` line:
+
+```
+  wt shell-init [bash|zsh|fish]   emit the shell function that makes switch cd
+```
+
+`shell-init` must work outside a git repo, so dispatch it in the **pre-`ctx_init`** case at the top of the file, not the main dispatch:
+
+```sh
+case "${1:-}" in
+  -h|--help|help|'') usage; exit 0 ;;
+  -v|--version) echo "wt $WT_VERSION"; exit 0 ;;
+  shell-init) shift; cmd_shell_init "$@"; exit 0 ;;
+esac
+```
+
+Add only `switch` to the post-`ctx_init` dispatch:
+
+```sh
+  switch) shift; cmd_switch "$@" ;;
+```
+
+`cmd_shell_init` is defined above that top-level `case` already, since all function definitions precede it.
+
+- [ ] **Step 6: Run the test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: `LIFECYCLE PASS`
+
+- [ ] **Step 7: Verify the wrapper by hand in a real shell**
+
+Run:
+
+```bash
+cd /tmp && rm -rf wtdemo && mkdir wtdemo && cd wtdemo && git init -q \
+  && git commit -q --allow-empty -m init \
+  && eval "$(wt shell-init bash)" && wt new demo && pwd
+```
+
+Expected: `pwd` prints `/tmp/wtdemo-worktrees/demo`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add bin/wt test/lifecycle.sh
+git commit -m "wt switch: picker, branch lookup, and shell integration"
+```
+
+---
+
+## Task 4: `wt rm`
+
+**Files:**
+- Modify: `bin/wt` (lifecycle section, `cmd_*` section, usage, dispatch)
+- Modify: `test/lifecycle.sh` (append a section)
+
+**Interfaces:**
+- Consumes: `worktree_for_branch()`, `resolve_trunk()`, `emit_cd()`, `expand()`, `runner_exec()`, `cfg_get()`, `slugify()`, `hashnum()`, `STATE_DIR`, `PRIMARY`, `WT_PATH`, `SLUG`, `N`.
+- Produces:
+  - `teardown_worktree <slug> <path>` — stops the server, drops the database, flushes the Redis slot, clears state files. Never removes the worktree itself. Always returns 0.
+  - `remove_worktree_and_branch <branch> <path> <keep_branch 0|1> <force 0|1>`.
+  - `confirm <prompt>` — 0 on yes; reads `/dev/tty`, falling back to stdin.
+  - `cmd_rm` — `wt rm [<branch>] [--keep-branch] [--force]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/lifecycle.sh`, before the final `[ "$FAILED" = 0 ]` line:
+
+```sh
+# ---------- Task 4: rm ----------
+
+new_repo rmrepo
+"$WT" new feat/gone >/dev/null 2>&1
+wtdir="$TMP/rmrepo-worktrees/feat_gone"
+
+# fabricate the state files a server would have left behind
+state="$REPO/.git/wt-state"
+mkdir -p "$state/logs"
+: > "$state/feat_gone.dbready"
+: > "$state/feat_gone.port"
+: > "$state/logs/feat_gone.log"
+
+# a dirty worktree is refused without --force
+echo scratch > "$wtdir/scratch.txt"
+assert_fails "rm: refuses a dirty worktree" "$WT" rm feat/gone
+assert_eq "0" "$(test -d "$wtdir"; echo $?)" "rm: dirty worktree survives the refusal"
+rm "$wtdir/scratch.txt"
+
+# unmerged commits are refused without --force
+( cd "$wtdir" && echo c > c.txt && git add c.txt && git commit -qm work )
+assert_fails "rm: refuses unmerged commits" "$WT" rm feat/gone
+
+# --force removes it and reclaims every state file
+"$WT" rm feat/gone --force >/dev/null 2>&1
+assert_eq "1" "$(test -d "$wtdir"; echo $?)"                    "rm --force: worktree gone"
+assert_eq "1" "$(test -f "$state/feat_gone.dbready"; echo $?)"  "rm --force: dbready cleared"
+assert_eq "1" "$(test -f "$state/feat_gone.port"; echo $?)"     "rm --force: port file cleared"
+assert_eq "1" "$(test -f "$state/logs/feat_gone.log"; echo $?)" "rm --force: log cleared"
+assert_missing "$(git -C "$REPO" branch --list 'feat/gone')" "feat/gone" \
+  "rm --force: branch deleted"
+
+# --keep-branch keeps the branch
+"$WT" new feat/keep >/dev/null 2>&1
+"$WT" rm feat/keep --force --keep-branch >/dev/null 2>&1
+assert_contains "$(git -C "$REPO" branch --list 'feat/keep')" "feat/keep" \
+  "rm --keep-branch: branch survives"
+
+# the primary checkout is never removable
+assert_fails "rm: refuses the primary checkout" "$WT" rm master --force
+
+# a clean, fully merged worktree needs no --force, but does need a yes
+"$WT" new feat/clean >/dev/null 2>&1
+printf 'y\n' | "$WT" rm feat/clean >/dev/null 2>&1
+assert_eq "1" "$(test -d "$TMP/rmrepo-worktrees/feat_clean"; echo $?)" \
+  "rm: clean merged worktree removed after confirmation"
+
+# answering no leaves everything alone
+"$WT" new feat/spared >/dev/null 2>&1
+printf 'n\n' | "$WT" rm feat/spared >/dev/null 2>&1 || true
+assert_eq "0" "$(test -d "$TMP/rmrepo-worktrees/feat_spared"; echo $?)" \
+  "rm: declining the prompt keeps the worktree"
+```
+
+The confirmation prompt reads `/dev/tty` when one exists and stdin otherwise; the pipes above exercise the stdin path, which is what runs in CI.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `wt: unknown command: rm`
+
+- [ ] **Step 3: Add the teardown helpers**
+
+Append to the `# ---------- lifecycle ----------` section:
+
+```sh
+# Reclaims everything the kit provisioned for a slug. Does NOT touch the
+# worktree directory or the branch. Overlays under $OVERLAY_DIR are per-file
+# and personal, never per-worktree — they are deliberately left alone.
+teardown_worktree() { # <slug> <path>
+  _ts="$1"; _tp="$2"
+
+  if [ "${HAS_CONFIG:-0}" = 1 ]; then
+    "$0" down "$_ts" >&2 || true
+
+    # expand() reads the globals SLUG and N; borrow them for the target slug
+    _old_slug="$SLUG"; _old_n="$N"
+    SLUG="$_ts"; N=$(( $(hashnum "$_ts") % 15 + 1 ))
+
+    if [ -f "$STATE_DIR/$_ts.dbready" ]; then
+      _drop="$(cfg_get isolation.db_drop "")"
+      if [ -n "$_drop" ]; then
+        note "dropping database for $_ts"
+        runner_exec own_db "$(expand "$_drop")" >&2 || note "db_drop failed — the database may remain"
+      else
+        note "no isolation.db_drop configured — the database for slug $_ts is left in place"
+      fi
+    fi
+
+    _flush="$(cfg_get isolation.redis_flush "")"
+    if [ -n "$_flush" ]; then
+      note "flushing redis db $N for $_ts"
+      runner_exec isolated "$(expand "$_flush")" >&2 || note "redis_flush failed — db $N may still hold keys"
+    else
+      note "no isolation.redis_flush configured — redis db $N is left as is"
+    fi
+
+    SLUG="$_old_slug"; N="$_old_n"
+  fi
+
+  rm -f "$STATE_DIR/$_ts.pid" "$STATE_DIR/$_ts.port" \
+        "$STATE_DIR/$_ts.dbready" "$STATE_DIR/logs/$_ts.log"
+  true
+}
+
+remove_worktree_and_branch() { # <branch> <path> <keep_branch 0|1> <force 0|1>
+  if [ "$4" = 1 ]; then
+    git worktree remove --force "$2" >&2
+  else
+    git worktree remove "$2" >&2
+  fi
+  if [ "$3" = 0 ]; then
+    if [ "$4" = 1 ]; then
+      git branch -D "$1" >&2
+    else
+      git branch -d "$1" >&2
+    fi
+  fi
+  true
+}
+
+confirm() { # <prompt> — 0 on yes. Reads /dev/tty, falling back to stdin.
+  printf '%s [y/N] ' "$1" >&2
+  if [ -r /dev/tty ]; then
+    read -r _ans < /dev/tty || _ans=n
+  else
+    read -r _ans || _ans=n
+  fi
+  case "$_ans" in
+    y|Y|yes|YES) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+```
+
+- [ ] **Step 4: Add `cmd_rm`**
+
+```sh
+cmd_rm() {
+  load_config_soft
+  _force=0; _keep=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -f|--force)    _force=1; shift ;;
+      --keep-branch) _keep=1; shift ;;
+      -*)            die "unknown flag: $1 (wt rm [<branch>] [--keep-branch] [--force])" ;;
+      *)             _branch="$1"; shift ;;
+    esac
+  done
+  if [ -z "$_branch" ]; then _branch="$(git rev-parse --abbrev-ref HEAD)"; fi
+
+  _path="$(worktree_for_branch "$_branch")"
+  if [ -z "$_path" ]; then die "no worktree for branch $_branch (see: wt list)"; fi
+  if [ "$_path" = "$PRIMARY" ]; then die "refusing to remove the primary checkout at $PRIMARY"; fi
+
+  if [ "$_force" = 0 ]; then
+    if [ -n "$(git -C "$_path" status --porcelain)" ]; then
+      die "$_branch has uncommitted changes — commit them, or use --force"
+    fi
+    # Deliberately reachability, not "unpushed": a local-only branch has no
+    # upstream, so an unpushed test would refuse every agent worktree.
+    _trunk="$(resolve_trunk)"
+    if [ -n "$_trunk" ]; then
+      _un="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
+      if [ "$_un" -gt 0 ]; then
+        die "$_branch has $_un commit(s) not in $_trunk — merge them (wt merge $_branch), or use --force"
+      fi
+    fi
+  fi
+
+  _slug="$(slugify "$_path")"
+  note "about to remove:"
+  note "  worktree  $_path"
+  if [ "$_keep" = 0 ]; then note "  branch    $_branch"; fi
+  note "  state     $STATE_DIR/$_slug.*"
+  if [ "${HAS_CONFIG:-0}" = 1 ] && [ -f "$STATE_DIR/$_slug.dbready" ]; then
+    note "  database  provisioned for slug $_slug"
+  fi
+  if [ "$_force" = 0 ]; then
+    confirm "proceed?" || die "aborted"
+  fi
+
+  _removed_cwd=0
+  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; fi
+
+  teardown_worktree "$_slug" "$_path"
+  remove_worktree_and_branch "$_branch" "$_path" "$_keep" "$_force"
+  note "removed $_branch"
+
+  if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
+}
+```
+
+- [ ] **Step 5: Wire up dispatch and usage**
+
+In `usage()`, after the `wt switch` line:
+
+```
+  wt rm [<branch>] [--keep-branch] [--force]   tear down and remove a worktree
+```
+
+In the dispatch `case`:
+
+```sh
+  rm) shift; cmd_rm "$@" ;;
+```
+
+- [ ] **Step 6: Run the test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: `LIFECYCLE PASS`
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add bin/wt test/lifecycle.sh
+git commit -m "wt rm: reclaim the server, database, redis slot, and state files"
+```
+
+---
+
+## Task 5: `wt merge`
+
+**Files:**
+- Modify: `bin/wt` (`cmd_*` section, usage, dispatch)
+- Modify: `test/lifecycle.sh` (append a section)
+
+**Interfaces:**
+- Consumes: `worktree_for_branch()`, `resolve_trunk()`, `teardown_worktree()`, `remove_worktree_and_branch()`, `emit_cd()`, `slugify()`, `PRIMARY`, `WT_PATH`.
+- Produces: `cmd_merge` — `wt merge [<branch>] [--into <trunk>] [--no-remove] [-m <msg>] [--force]`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/lifecycle.sh`, before the final `[ "$FAILED" = 0 ]` line:
+
+```sh
+# ---------- Task 5: merge ----------
+
+new_repo mergerepo
+"$WT" new feat/work >/dev/null 2>&1
+wtdir="$TMP/mergerepo-worktrees/feat_work"
+( cd "$wtdir" && echo one > one.txt && git add one.txt && git commit -qm "add one" )
+( cd "$wtdir" && echo two > two.txt && git add two.txt && git commit -qm "add two" )
+
+before="$(git -C "$REPO" rev-parse master)"
+"$WT" merge feat/work >/dev/null 2>&1
+after="$(git -C "$REPO" rev-parse master)"
+
+assert_eq "1" "$(test "$before" = "$after"; echo $?)" "merge: master advanced"
+assert_eq "1" "$(git -C "$REPO" rev-list --count "$before..$after")" \
+  "merge: two commits squashed into one"
+assert_contains "$(git -C "$REPO" log -1 --format=%s)" "add one" \
+  "merge: subject taken from the first commit"
+assert_contains "$(git -C "$REPO" log -1 --format=%B)" "add two" \
+  "merge: remaining subjects form the body"
+assert_eq "1" "$(test -d "$wtdir"; echo $?)" "merge: worktree removed by default"
+assert_contains "$(git -C "$REPO" show-ref)" "refs/wt/premerge/feat_work" \
+  "merge: backup ref kept as the undo"
+
+# --no-remove leaves the worktree in place
+"$WT" new feat/stay >/dev/null 2>&1
+( cd "$TMP/mergerepo-worktrees/feat_stay" && echo s > s.txt && git add s.txt && git commit -qm stay )
+"$WT" merge feat/stay --no-remove >/dev/null 2>&1
+assert_eq "0" "$(test -d "$TMP/mergerepo-worktrees/feat_stay"; echo $?)" \
+  "merge --no-remove: worktree survives"
+
+# a conflicting rebase restores the branch exactly and leaves the worktree alone
+new_repo conflictrepo
+echo base > f.txt && git add f.txt && git commit -qm base
+"$WT" new feat/conflict >/dev/null 2>&1
+cdir="$TMP/conflictrepo-worktrees/feat_conflict"
+( cd "$cdir" && echo theirs > f.txt && git add f.txt && git commit -qm theirs )
+orig="$(git -C "$cdir" rev-parse HEAD)"
+echo ours > f.txt && git add f.txt && git commit -qm ours
+master_before="$(git -C "$REPO" rev-parse master)"
+
+assert_fails "merge: conflict is an error" "$WT" merge feat/conflict
+assert_eq "$orig" "$(git -C "$cdir" rev-parse HEAD)" \
+  "merge: branch restored to its pre-squash commit after a conflict"
+assert_eq "$master_before" "$(git -C "$REPO" rev-parse master)" \
+  "merge: master untouched after a conflict"
+assert_eq "0" "$(test -d "$cdir"; echo $?)" "merge: worktree survives a conflict"
+assert_eq "" "$(git -C "$cdir" status --porcelain)" \
+  "merge: no rebase left in progress"
+
+# guards
+new_repo guardrepo
+"$WT" new feat/empty >/dev/null 2>&1
+assert_fails "merge: refuses a branch with no commits ahead" "$WT" merge feat/empty
+
+"$WT" new feat/dirty >/dev/null 2>&1
+( cd "$TMP/guardrepo-worktrees/feat_dirty" && echo d > d.txt && git add d.txt \
+    && git commit -qm d && echo x > x.txt )
+assert_fails "merge: refuses a dirty worktree" "$WT" merge feat/dirty
+
+"$WT" new feat/ok >/dev/null 2>&1
+( cd "$TMP/guardrepo-worktrees/feat_ok" && echo o > o.txt && git add o.txt && git commit -qm o )
+echo primarydirt > "$REPO/dirt.txt"
+assert_fails "merge: refuses when the primary checkout is dirty" "$WT" merge feat/ok
+rm -f "$REPO/dirt.txt"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `wt: unknown command: merge`
+
+- [ ] **Step 3: Add `cmd_merge`**
+
+```sh
+cmd_merge() {
+  load_config_soft
+  _trunk=""; _msg=""; _no_remove=0; _force=0; _branch=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --into)      _trunk="${2:-}"; [ -n "$_trunk" ] || die "--into needs a branch"; shift 2 ;;
+      -m)          _msg="${2:-}";   [ -n "$_msg" ]   || die "-m needs a message";   shift 2 ;;
+      --no-remove) _no_remove=1; shift ;;
+      -f|--force)  _force=1; shift ;;
+      -*)          die "unknown flag: $1 (wt merge [<branch>] [--into <trunk>] [--no-remove] [-m <msg>] [--force])" ;;
+      *)           _branch="$1"; shift ;;
+    esac
+  done
+  if [ -z "$_branch" ]; then _branch="$(git rev-parse --abbrev-ref HEAD)"; fi
+
+  _path="$(worktree_for_branch "$_branch")"
+  if [ -z "$_path" ]; then die "no worktree for branch $_branch (see: wt list)"; fi
+  if [ "$_path" = "$PRIMARY" ]; then die "refusing to merge the primary checkout's own branch"; fi
+
+  if [ -z "$_trunk" ]; then _trunk="$(resolve_trunk)"; fi
+  if [ -z "$_trunk" ]; then die "cannot determine trunk — pass --into <branch> or set worktrees.trunk"; fi
+  if [ "$_trunk" = "$_branch" ]; then die "$_branch is the trunk"; fi
+
+  # ---- guards, before anything is rewritten ----
+  if [ -n "$(git -C "$_path" status --porcelain)" ]; then
+    die "$_branch has uncommitted changes — commit or stash them first"
+  fi
+  _ahead="$(git -C "$_path" rev-list --count "$_trunk..$_branch" 2>/dev/null || echo 0)"
+  if [ "$_ahead" -eq 0 ]; then die "$_branch has no commits ahead of $_trunk"; fi
+
+  _primary_branch="$(git -C "$PRIMARY" rev-parse --abbrev-ref HEAD)"
+  if [ "$_primary_branch" != "$_trunk" ]; then
+    die "$_trunk is not checked out at $PRIMARY (found $_primary_branch)"
+  fi
+  if [ -n "$(git -C "$PRIMARY" status --porcelain)" ]; then
+    die "the primary checkout at $PRIMARY is dirty — commit or stash first"
+  fi
+  if git -C "$_path" rev-parse --verify --quiet "$_branch@{upstream}" >/dev/null 2>&1; then
+    if [ "$_force" = 0 ]; then
+      die "$_branch has an upstream — squashing rewrites published history; pass --force to proceed"
+    fi
+  fi
+
+  # ---- backup ref: the undo for everything below ----
+  _slug="$(slugify "$_path")"
+  _backup="refs/wt/premerge/$_slug"
+  _orig="$(git -C "$_path" rev-parse HEAD)"
+  git -C "$_path" update-ref "$_backup" "$_orig"
+  note "backup: $_backup -> $_orig"
+
+  # ---- squash ----
+  _base="$(git -C "$_path" merge-base "$_trunk" "$_branch")"
+  if [ -z "$_msg" ]; then
+    _subj="$(git -C "$_path" log --format='%s' --reverse "$_base..$_branch" | head -1)"
+    _body="$(git -C "$_path" log --format='%s' --reverse "$_base..$_branch" | tail -n +2)"
+    if [ -n "$_body" ]; then
+      _msg="$_subj
+
+$_body"
+    else
+      _msg="$_subj"
+    fi
+  fi
+  git -C "$_path" reset --soft "$_base" >&2
+  if ! git -C "$_path" commit -q -m "$_msg" >&2; then
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "squash commit failed — $_branch restored to $_orig"
+  fi
+
+  # ---- rebase ----
+  if ! git -C "$_path" rebase "$_trunk" >&2; then
+    git -C "$_path" rebase --abort >/dev/null 2>&1 || true
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "rebase of $_branch onto $_trunk hit a conflict — $_branch restored to $_orig
+resolve by hand:  git -C $_path rebase $_trunk"
+  fi
+
+  # ---- fast-forward trunk ----
+  _trunk_before="$(git -C "$PRIMARY" rev-parse "$_trunk")"
+  if ! git -C "$PRIMARY" merge --ff-only "$_branch" >&2; then
+    git -C "$_path" reset --hard "$_orig" >&2
+    die "$_trunk could not fast-forward to $_branch — it moved underneath us; $_branch restored to $_orig"
+  fi
+  note "merged $_branch into $_trunk"
+  note "undo:   git -C $PRIMARY reset --hard $_trunk_before   (branch backup: $_backup)"
+
+  # ---- teardown ----
+  if [ "$_no_remove" = 1 ]; then return 0; fi
+
+  _removed_cwd=0
+  if [ "$WT_PATH" = "$_path" ]; then _removed_cwd=1; fi
+  teardown_worktree "$_slug" "$_path"
+  remove_worktree_and_branch "$_branch" "$_path" 0 0
+  if [ "$_removed_cwd" = 1 ]; then emit_cd "$PRIMARY"; fi
+}
+```
+
+- [ ] **Step 4: Wire up dispatch and usage**
+
+In `usage()`, after the `wt rm` line:
+
+```
+  wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]
+                         squash, rebase, fast-forward trunk, then tear down
+```
+
+In the dispatch `case`:
+
+```sh
+  merge) shift; cmd_merge "$@" ;;
+```
+
+- [ ] **Step 5: Run the test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: `LIFECYCLE PASS`
+
+- [ ] **Step 6: Run the linux suites**
+
+Run: `./test/linux.sh`
+Expected: `ALL LINUX TESTS PASSED`
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add bin/wt test/lifecycle.sh
+git commit -m "wt merge: squash, rebase, fast-forward, tear down — with a backup ref"
+```
+
+---
+
+## Task 6: `doctor` checks, templates, docs, version bump
+
+**Files:**
+- Modify: `bin/wt:571-590` (`cmd_doctor`), `bin/wt:16` (`WT_VERSION`)
+- Modify: all ten `templates/{compose,host}/*.yml`
+- Modify: `README.md`, `package.json`
+- Modify: `test/lifecycle.sh` (append a section)
+
+**Interfaces:**
+- Consumes: `path_template()`, `expand_path()`, everything from Tasks 1-5.
+- Produces: no new functions.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/lifecycle.sh`, before the final `[ "$FAILED" = 0 ]` line:
+
+```sh
+# ---------- Task 6: doctor ----------
+
+new_repo doctorrepo
+out="$("$WT" doctor 2>&1)"
+assert_contains "$out" "wt path:" "doctor: reports the path template"
+assert_contains "$out" "fzf:"     "doctor: reports fzf availability"
+assert_contains "$out" "shell:"   "doctor: reports shell integration state"
+
+out="$(WT_SHELL_INTEGRATION=1 "$WT" doctor 2>&1)"
+assert_contains "$out" "integration active" "doctor: detects an active wrapper"
+
+# The two template warnings need a YAML backend to read the .local file.
+if command -v yq >/dev/null 2>&1 || command -v ruby >/dev/null 2>&1 \
+   || python3 -c 'import yaml' >/dev/null 2>&1; then
+  cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/{repo}-worktrees/fixed"
+YML
+  out="$("$WT" doctor 2>&1)"
+  assert_contains "$out" "not branch-unique" "doctor: warns on a non-branch-unique template"
+
+  cat > worktree-kit.local.yml <<'YML'
+worktrees:
+  path: "{parent}/has space/{branch}"
+YML
+  out="$("$WT" doctor 2>&1)"
+  assert_contains "$out" "space" "doctor: warns on a template that yields a space"
+  rm -f worktree-kit.local.yml
+else
+  ok "doctor: template warnings skipped (no YAML backend installed)"
+fi
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./test/lifecycle.sh`
+Expected: FAIL — `doctor: reports the path template`
+
+- [ ] **Step 3: Extend `cmd_doctor`**
+
+Insert immediately after the existing `config:` line in `cmd_doctor`, before the `yaml_backend` call:
+
+```sh
+  load_config_soft
+  _tmpl="$(path_template)"
+  echo "wt path:   $_tmpl"
+  _last="${_tmpl##*/}"
+  case "$_last" in
+    *'{branch}'*|*'{branch_raw}'*) ;;
+    *) echo "WARN: worktrees.path's last segment is not branch-unique — every worktree would share a slug, and with it a port, redis slot, and database" ;;
+  esac
+  _probe="$(expand_path "$_tmpl" wt-doctor-probe)"
+  case "$_probe" in
+    *" "*) echo "WARN: worktrees.path expands to a path containing a space ($_probe) — wt new will refuse it" ;;
+  esac
+```
+
+Append before the final `echo "ok"`:
+
+```sh
+  if command -v fzf >/dev/null 2>&1; then
+    echo "fzf:       $(fzf --version 2>/dev/null | head -1)"
+  else
+    echo "fzf:       not installed (wt switch falls back to a numbered menu)"
+  fi
+
+  if [ -n "${WT_SHELL_INTEGRATION:-}" ]; then
+    echo "shell:     integration active"
+  else
+    _rc_found=""
+    for _rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.config/fish/config.fish"; do
+      if [ -f "$_rc" ] && grep -q 'wt shell-init' "$_rc" 2>/dev/null; then _rc_found="$_rc"; break; fi
+    done
+    if [ -n "$_rc_found" ]; then
+      echo "shell:     shell-init found in $_rc_found (open a new shell to activate)"
+    else
+      echo "shell:     unknown — no WT_SHELL_INTEGRATION set and no 'wt shell-init' in your rc files"
+    fi
+  fi
+```
+
+`cmd_doctor` already guards its own config read with `if [ -f "$CONFIG" ]`; the added `load_config_soft` call is safe unconditionally and sets `HAS_CONFIG` for `path_template`.
+
+- [ ] **Step 4: Run the doctor test to verify it passes**
+
+Run: `./test/lifecycle.sh`
+Expected: `LIFECYCLE PASS`
+
+- [ ] **Step 5: Add the `worktrees:` block to all ten templates**
+
+Insert into each of `templates/compose/{rails,laravel,node,django,go}.yml` and `templates/host/{rails,laravel,node,django,go}.yml`, immediately after the `runner:` line:
+
+```yaml
+# Where `wt new <branch>` puts a new worktree. The LAST path segment becomes
+# the slug — and the slug names the port, the redis db {n}, and the database.
+# Keep {branch} last. Personal layouts belong in worktree-kit.local.yml.
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"
+  # trunk: master     # optional; what `wt merge` merges into.
+                      # Default: origin/HEAD, then main, then master.
+```
+
+- [ ] **Step 6: Add `db_drop` and `redis_flush` to all ten templates**
+
+Add both keys to each template's `isolation:` block, **mirroring the client, host, and credentials that template's own `db_bootstrap` already uses**. Where a template declares no `db_bootstrap`, add both keys commented out with the same explanatory comment.
+
+`templates/compose/rails.yml` — append to `isolation:`:
+
+```yaml
+  # db_drop (optional): destroys the per-worktree DB. `wt rm` runs it only
+  # when the .dbready marker exists — i.e. only for a DB wt itself created.
+  # Without this key wt prints the DB name and leaves it in place.
+  db_drop: "SKIP_TEST_DATABASE=1 bundle exec rails db:drop"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`.
+  redis_flush: "redis-cli -h redis -n {n} flushdb"
+```
+
+`templates/host/node.yml` — append to `isolation:`:
+
+```yaml
+  # db_drop (optional): destroys the per-worktree DB. `wt rm` runs it only
+  # when the .dbready marker exists — i.e. only for a DB wt itself created.
+  # Without this key wt prints the DB name and leaves it in place.
+  db_drop: "dropdb --if-exists wt_{slug}"
+  # redis_flush (optional): empties this worktree's redis db on `wt rm`.
+  redis_flush: "redis-cli -n {n} flushdb"
+```
+
+Apply the same shape to the remaining eight, matching each one's existing bootstrap and its redis host (`redis` under compose, `localhost` under host):
+
+- **rails host** — `db_drop: "SKIP_TEST_DATABASE=1 bundle exec rails db:drop"`, `redis_flush: "redis-cli -n {n} flushdb"`.
+- **laravel** (both) — `db_drop: "php artisan db:wipe --force"`.
+- **django** (both) — mirror the template's bootstrap connection: `dropdb --if-exists wt_{slug}` on host, or the same `psql` host and user its bootstrap uses under compose, running `DROP DATABASE IF EXISTS wt_{slug}`.
+- **node compose** — `dropdb` against the same host its bootstrap connects to.
+- **go** (both) — mirror its bootstrap; if it declares none, add both keys commented out.
+
+Then verify every template still parses:
+
+```bash
+for f in templates/compose/*.yml templates/host/*.yml; do
+  yq -o=json "$f" > /dev/null || echo "INVALID: $f"
+done
+```
+
+If `yq` is absent, use `python3 -c 'import sys,yaml; yaml.safe_load(open(sys.argv[1]))' "$f"`.
+
+- [ ] **Step 7: Update the README**
+
+Add to the command reference, in the style of the existing entries:
+
+- `wt new <branch> [--from <base>] [--server]`
+- `wt switch [<branch>]`
+- `wt list [--all]`
+- `wt rm [<branch>] [--keep-branch] [--force]`
+- `wt merge [<branch>] [--into <trunk>] [-m <msg>] [--no-remove] [--force]`
+- `wt shell-init [bash|zsh|fish]`
+
+Add a **Shell integration** section showing `eval "$(wt shell-init zsh)"`, and explaining that without it `wt switch` prints a path instead of changing directory.
+
+Add to the config reference: `worktrees.path` (with the last-segment-becomes-the-slug rule and the no-spaces rule), `worktrees.trunk`, `isolation.db_drop`, `isolation.redis_flush`. Note that `worktrees.path` is the natural thing to override in `worktree-kit.local.yml`.
+
+- [ ] **Step 8: Bump the version**
+
+In `bin/wt:16`: `WT_VERSION="0.2.0"`
+In `package.json`: `"version": "0.2.0"`
+
+A minor bump, not a patch: this adds six commands.
+
+- [ ] **Step 9: Run everything**
+
+Run: `./test/lifecycle.sh && ./test/linux.sh`
+Expected: `LIFECYCLE PASS` then `ALL LINUX TESTS PASSED`
+
+- [ ] **Step 10: Verify the README against the real binary**
+
+Run: `wt --help`
+Confirm every command documented in the README appears in `usage()`, and every command in `usage()` is documented in the README.
+
+- [ ] **Step 11: Commit**
+
+```bash
+git add bin/wt templates README.md package.json test/lifecycle.sh
+git commit -m "wt 0.2.0: doctor checks, template config, and docs for the lifecycle commands"
+```
+
+---
+
+## Post-implementation
+
+Release is a separate, manual step and is **not** part of this plan. `wt` is published to npm and has a Homebrew tap; follow the existing release flow, and get explicit approval before any `git push` or `npm publish`.
+
+## Notes for the implementer
+
+- **Read CONTEXT.md before Task 1.** Its §5 lists eight bugs found while building this tool; three of them (1, 7, 8) are traps you can walk straight back into.
+- The Alpine suite is the one that matters. BusyBox `ash` is where the `set -e` function-return bug, the mtime-granularity bug, and the process-group bug all surfaced. If you can run only one container suite, run that one.
+- `runner_exec` and `expand` read globals (`SLUG`, `N`, `WT_PATH`). `teardown_worktree` borrows and restores `SLUG`/`N` deliberately — do not "clean this up" by passing parameters without also changing `expand`.
diff --git a/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md b/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md
new file mode 100644
index 0000000..023a0c7
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md
@@ -0,0 +1,436 @@
+# Worktree lifecycle commands for `wt`
+
+**Status:** implemented in worktree-kit 0.2.0. Three places where the
+implementation deliberately diverged are marked inline below as RESOLVED
+DEVIATION (§6.3 hyphen folding, §10.1 step 5 ownership marker, §10.2 merge
+teardown); this document is otherwise the binding design.
+**Date:** 2026-08-29
+**Base commit:** `fbdf060` (worktree-kit 0.1.8)
+
+## 1. Problem
+
+`wt` today runs things *inside* worktrees that already exist: `run`, `server`,
+`up`, `down`, `ps`, `logs`, `localize`, `reset`, `init`, `doctor`. It has no
+way to create, find, or destroy a worktree. Users create them by hand with
+`git worktree add` (or via Orca), and when they are done they delete the
+directory — leaving behind the server, the `wt_<slug>` database, the Redis
+slot, and the files under `wt-state/`.
+
+[worktrunk](https://github.com/max-sixty/worktrunk) solves the other half:
+`switch`, `list`, `merge`, `remove`, with path templates and an interactive
+picker. It is a Rust binary and knows nothing about databases, servers, or
+isolation, so its `remove` leaks every resource `wt` provisions.
+
+The two halves are complementary and there is zero command overlap. This
+design adds the lifecycle half to `wt`, wired into the isolation machinery
+that already exists.
+
+**Name collision, noted and accepted:** worktrunk's binary is also `wt`. The
+two cannot be installed side by side. This design proceeds on the assumption
+that worktree-kit owns the name for its users.
+
+## 2. Goals
+
+- Create, navigate, list, merge, and destroy worktrees from `wt`.
+- Destroying a worktree reclaims *everything* the kit provisioned for it.
+- Lifecycle commands work in any git repo, with or without `worktree-kit.yml`.
+- Existing worktrees keep their current slug, port, Redis slot, and DB name.
+- Stay one POSIX-sh file, one required dependency (`git`), no `lib/`.
+
+## 3. Non-goals
+
+Explicitly out of scope, and not to be added later without a fresh design:
+
+- LLM-generated commit messages.
+- CI status columns or AI summaries in `list`.
+- `pr:123` checkout syntax and any `gh` dependency.
+- Copying build caches (`node_modules`, `target/`) between worktrees.
+  CONTEXT.md §5 bug 6 documents why shared dependency directories thrash
+  between branch lockfiles. If this is ever revisited it must be an explicit
+  opt-in list, never inferred.
+- Pushing. `wt merge` is entirely local.
+- Restructuring the existing ten commands. The CLI surface is additive; the
+  package is published and has a Homebrew tap.
+
+## 4. Architecture: lifecycle as a git-only peer layer
+
+The five new commands require only `git`. They load `worktree-kit.yml` if it
+is present and skip config-dependent steps with a one-line note if it is not.
+
+This is the one structural change to existing code:
+
+- `require_config` currently dies when `$CONFIG` is missing.
+- Split it into `load_config_soft` (sets `HAS_CONFIG=0|1`, never dies) and
+  `require_config` (calls the soft loader, dies when `HAS_CONFIG=0`).
+- The ten existing commands keep calling `require_config` and behave
+  identically. The five new ones call `load_config_soft`.
+
+Consequence: `wt new` and `wt list` are useful the moment `wt` is installed,
+in any repo, which is the adoption path the tool currently lacks — today a
+new user must author a YAML file before the tool does anything at all.
+
+## 5. Command surface
+
+```
+wt new <branch> [--from <base>] [--server]
+wt switch [<branch>]
+wt list [--all]
+wt rm [<branch>] [--keep-branch] [--force]
+wt merge [<branch>] [--into <trunk>] [--no-remove] [-m <msg>] [--force]
+wt shell-init [bash|zsh|fish]
+```
+
+`new` rather than worktrunk's `switch -c`: the existing surface is imperative
+verbs (`up`, `down`, `ps`), and a create flag on a navigate command reads
+badly beside them.
+
+Where `<branch>` is optional and omitted, the command acts on the current
+worktree — except `switch`, which opens the picker.
+
+**Stdout is the cd channel.** Every lifecycle command prints, on stdout,
+either a path the shell should `cd` to or nothing at all. `new` and `switch`
+print the target worktree. `rm` and `merge` print the primary checkout **only
+when the worktree they removed was the caller's cwd**, and print nothing
+otherwise. All human-readable output goes to stderr. This single rule is what
+makes the shell wrapper in §8.1 uniform across all four commands.
+
+## 6. Naming and the path model
+
+### 6.1 The constraint
+
+`ctx_init` derives `SLUG` from the **directory basename** (`bin/wt:46`), and
+`SLUG` determines:
+
+- the port, via `3000 + cksum(slug) % 900`
+- the Redis slot, via `N = cksum(slug) % 15 + 1`
+- the database name, via `own_db_env` templates such as `wt_{slug}`
+- every `wt-state/<slug>.*` file and the compose container labels
+
+Slug derivation is therefore **not changed by this design**. Changing it
+would silently move an existing worktree's port and database — e.g. the
+`phase02` worktree on port 3207 with DB `wt_phase02`.
+
+The path template carries the constraint instead: **its last segment becomes
+the slug.**
+
+### 6.2 Default template
+
+```
+{parent}/{repo}-worktrees/{branch}
+```
+
+Branch `feat/refund-flow` produces directory
+`<parent>/DepositCloud-worktrees/feat_refund_flow`, slug `feat_refund_flow`,
+DB `wt_feat_refund_flow`.
+
+The existing Orca layout (`~/orca/workspaces/DepositCloud/<task>/`) already
+satisfies the constraint, so worktrees created outside `wt` keep working and
+keep their identity.
+
+A template whose last segment is not branch-unique (e.g. `{repo}.{branch}`,
+giving slug `depositcloud_feat_refund_flow`) still functions; it only makes
+uglier database names. `wt doctor` warns; it does not forbid.
+
+### 6.3 Template variables
+
+Path templates expand `{parent}` `{repo}` `{branch}` `{branch_raw}` `{home}`.
+
+These are a **separate expansion function** from the existing `expand()`,
+because `{slug}`, `{n}`, and `{port}` do not exist yet at create time.
+
+- `{branch}` is sanitized for the filesystem (slashes and other non
+  `[A-Za-z0-9._]` characters become `_`).
+- `{branch_raw}` is the branch name as git stores it.
+- `{parent}` is `dirname` of the primary checkout.
+- `{repo}` is the primary checkout's basename, unsanitized.
+
+> **RESOLVED DEVIATION (implementation, 2026-08-29).** This section
+> originally specified the keep-set as `[A-Za-z0-9._-]`, i.e. hyphens
+> preserved. The implementation's `sanitize_branch` keeps `[A-Za-z0-9._]` and
+> folds hyphens too, so that the directory basename equals the slug exactly —
+> `slugify` folds hyphens as well, and a mismatch would mean `wt list`'s PATH
+> column and its SLUG column disagreed about the same worktree. Branch
+> `feat/refund-flow` therefore gives directory *and* slug `feat_refund_flow`.
+>
+> The invariant is near-total, not total: `.` is kept by `sanitize_branch` but
+> folded by `slugify`, so branch `feat.x` yields directory `feat.x` and slug
+> `feat_x`. Left as-is — the residual only affects branch names containing a
+> dot, and closing it would change the directory names of existing worktrees.
+
+### 6.4 Lookup is always via git
+
+`wt switch`, `wt rm`, and `wt merge` resolve a branch to a path by reading
+`git worktree list --porcelain` and matching the branch — **never** by
+recomputing the template. This is what makes them work on worktrees created
+by Orca, by hand, or under a previous template setting. The template is used
+at create time only.
+
+This preserves the CONTEXT.md §2 principle "context from git, not config":
+config now says where to *put* a new worktree, but never where to *find* one.
+
+## 7. `wt new`
+
+1. Resolve the target path from the template; **hard error** if the expansion
+   contains a space (see §11).
+2. If the branch does not exist: `git worktree add -b <branch> <path> <base>`,
+   where `<base>` is `--from` or the current HEAD.
+3. If the branch exists but has no worktree: **adopt** it —
+   `git worktree add <path> <branch>`.
+4. If the branch exists and already has a worktree: error, naming the path,
+   and point at `wt switch`.
+5. If `HAS_CONFIG=1` and `hooks.prepare` is set, run it in the new worktree
+   through the configured runner. **Its output is redirected to stderr**, so
+   it cannot pollute the cd channel (§5); the hook's exit status is still
+   checked and a failure aborts before step 7.
+6. With `--server`, invoke the existing `wt server` in the new worktree.
+   Off by default — starting servers unasked is noisy past a few worktrees.
+7. Print the new path on stdout (so the shell function can `cd` to it).
+
+## 8. `wt switch`, shell integration, and the picker
+
+### 8.1 Shell integration
+
+A process cannot change its parent's directory. `wt switch` prints the
+resolved path on **stdout** and everything else on **stderr** — a split the
+script already observes, since `note()` and `die()` write to stderr.
+
+`wt shell-init zsh` emits:
+
+```sh
+wt() {
+  case "${1:-}" in
+    switch|new|rm|merge)
+      local d; d="$(WT_SHELL_INTEGRATION=1 command wt "$@")" || return
+      [ -n "$d" ] && cd "$d" ;;
+    *) command wt "$@" ;;
+  esac
+}
+```
+
+Installed with `eval "$(wt shell-init zsh)"` in the user's rc file. `bash` is
+identical; `fish` needs its own syntax.
+
+Without the wrapper, `wt switch feat/x` still prints the path and adds a
+stderr hint about `shell-init`. `WT_SHELL_INTEGRATION=1` suppresses the hint.
+
+### 8.2 Picker
+
+`wt switch` with no argument opens a picker.
+
+- With `fzf`: rows from the shared row-builder (§9), preview pane running
+  `git -C <path> log --oneline -10` and `git -C <path> status -s`. fzf draws
+  on `/dev/tty` and prints only the selection to stdout, so it composes
+  correctly with the shell wrapper.
+- Without `fzf`: a numbered menu reading from `/dev/tty`.
+
+`fzf` is strictly optional. `doctor` reports whether it is present; nothing
+requires it. `git` remains the only hard dependency of the lifecycle layer.
+
+## 9. `wt list`
+
+`wt list` and the picker share **one row-builder function**, so their
+contents cannot drift.
+
+```
+BRANCH            SLUG              STATUS        SERVER  ISO      PATH
+master            depositcloud      clean         —       —        ~/Projects/DepositCloud
+feat/refund-flow  feat_refund_flow  dirty ↑2      :3207   own_db   ~/orca/…/refund
+spike/cache       spike_cache       clean ↓1      —       —        ~/orca/…/cache
+```
+
+- BRANCH, PATH: from `git worktree list --porcelain`.
+- SLUG: `slugify(basename(path))`, i.e. exactly what `ctx_init` would derive.
+- STATUS: `git -C <path> status --porcelain` for dirty/clean, plus
+  `git -C <path> rev-list --left-right --count <trunk>...HEAD` for ahead
+  and behind counts. Two git calls per worktree; acceptable at this scale.
+- SERVER, ISO: the same sources `wt ps` uses — docker labels
+  (`wt.slug`, `wt.port`, `wt.isolation`) for the compose runner, `wt-state`
+  pidfiles and portfiles for the host runner. Both show `—` when
+  `HAS_CONFIG=0`.
+- `--all` additionally lists local branches that have no worktree, so the
+  picker doubles as "what could I check out?".
+
+## 10. `wt rm` and `wt merge`
+
+### 10.1 `wt rm [<branch>] [--keep-branch] [--force]`
+
+Order, each step skipped with a note when it does not apply:
+
+1. Resolve branch → path. **Refuse** if it is the primary checkout.
+2. **Refuse** on uncommitted changes, or on commits not reachable from trunk,
+   unless `--force`. Deliberately *not* "unpushed commits": a local-only
+   branch has no upstream, so every commit would count as unpushed and `rm`
+   would refuse for exactly the agent workflow this exists to serve. The
+   reachability test is the same question `git branch -d` asks in step 8.
+3. Print everything that will be destroyed; prompt once. `--force` skips the
+   prompt.
+4. Stop the server (the existing `wt down` path for this slug).
+5. Drop the database — **only if `wt-state/<slug>.dbowned` exists**, i.e.
+   only a database the kit itself provisioned.
+
+   > **RESOLVED DEVIATION (implementation, 2026-08-29).** This step
+   > originally gated on `.dbready`, but `.dbready` does not mean what the
+   > step needs: `ensure_own_db` writes it on *both* paths — after
+   > `db_bootstrap` creates a database, and after `db_check` merely finds one
+   > that already existed. Gating on it would let `wt rm` drop a
+   > pre-existing, possibly shared database the kit never created. A second
+   > marker, `.dbowned`, is written only on the `db_bootstrap` path, and the
+   > drop gates on that. `wt reset` clears both.
+   >
+   > Two consequences, both accepted as the safe direction: databases
+   > bootstrapped before 0.2.0 have no `.dbowned` (the marker did not exist)
+   > and are left in place with a notice; and a database re-adopted via
+   > `db_check` after a `wt reset` is likewise never dropped.
+6. Flush the Redis slot `{n}`.
+7. Remove `wt-state/<slug>.pid`, `.port`, `.dbready`, and `logs/<slug>.log`.
+8. `git worktree remove <path>`, then `git branch -d <branch>` unless
+   `--keep-branch`. `-d`, not `-D`: an unmerged branch refuses removal.
+   `--force` upgrades to `-D`.
+
+Steps 5 and 6 require new config keys (§12). **If they are absent, `wt rm`
+prints the database name and Redis slot it is leaving behind and names the
+key to add.** The core never guesses a `DROP DATABASE` — it is stack-agnostic
+by design (CONTEXT.md §2) and cannot tell MySQL from Postgres.
+
+Overlays under `<git-common>/local/` are per-file and personal, not
+per-worktree. `wt rm` never touches them.
+
+### 10.2 `wt merge [<branch>] [--into <trunk>] [--no-remove] [-m <msg>] [--force]`
+
+Trunk resolution: `--into`, else `worktrees.trunk`, else the branch behind
+`refs/remotes/origin/HEAD`, else `main`, else `master`.
+
+Happy path: squash → rebase onto trunk → fast-forward trunk → §10.1 teardown
+(unless `--no-remove`).
+
+> **RESOLVED DEVIATION (implementation, 2026-08-29).** "Full §10.1 teardown"
+> is not what merge does, and §10.1 step 3 mandates a prompt that merge never
+> shows. Concretely, `wt merge` runs the §10.1 *resource* reclaim (steps 4–7:
+> server, database, redis slot, state files) and then removes the worktree
+> with the **`--force`** variant of step 8 — `git worktree remove --force`
+> plus `git branch -D` — with **no confirmation prompt at any point**.
+>
+> Both are deliberate. `-D` rather than `-d`: the `--ff-only` merge that just
+> succeeded *proved* every commit on the branch is reachable from trunk, so
+> `-d`'s own merge check is redundant and can misfire (a branch with a stale
+> upstream tracking ref is merged to HEAD but not to that upstream, and `-d`
+> refuses on that alone) — failing there would strand the user after trunk has
+> already advanced and teardown has already run. `--force` on the worktree
+> removal follows from the same call: merge already refused earlier on a dirty
+> worktree, and teardown itself can leave files behind between that check and
+> the removal.
+>
+> The user-visible cost is that `wt merge` deletes the worktree directory
+> including gitignored files, without asking. That is documented in the
+> README's `wt merge` section rather than softened here.
+
+The safety rules matter more than the happy path:
+
+- **Backup ref first.** Before anything rewrites history, write
+  `refs/wt/premerge/<slug>` at the worktree's current HEAD. Every failure
+  path prints the exact command to restore from it. This is what makes the
+  command trustworthy.
+- **Refuse** if the worktree is dirty.
+- **Refuse** if the branch has no commits ahead of trunk.
+- **Refuse** if the primary checkout (where trunk is checked out) is dirty.
+- **Squash** with `git reset --soft $(git merge-base <trunk> HEAD)` followed
+  by a commit. Default message: the first commit's subject, with the
+  remaining subjects as the body. `-m` overrides. No LLM, no editor.
+- **Rebase** onto trunk. On conflict: `git rebase --abort`, restore from the
+  backup ref, leave the worktree exactly as found, exit nonzero with
+  instructions. A half-merged state is never left behind.
+- **Merge with `--ff-only`.** Having just rebased, anything other than a
+  fast-forward means trunk moved underneath us — refuse rather than silently
+  create a merge commit.
+- **Never push.**
+- If the branch has an upstream, squashing rewrites published history —
+  **warn and require `--force`**.
+
+## 11. Error handling
+
+Driven by the bug list in CONTEXT.md §5:
+
+- **No new function may end with `[ cond ] && cmd`.** Under `set -e` a false
+  condition makes the function return nonzero and kills the caller — bug 1,
+  which broke every host-runner repo. Use explicit `if`, or end with `true`.
+- **A path template expanding to a path containing a space is a hard error**
+  at create time, printing the offending expansion. CONTEXT.md §7 records
+  that word-splitting is load-bearing in compose args and host `env` lists;
+  this converts a latent corruption into an upfront message.
+- Branch names keep slashes for git and are sanitized for the directory.
+- Every destructive step names what it is about to destroy before doing it.
+
+## 12. Config schema additions
+
+```yaml
+worktrees:
+  path: "{parent}/{repo}-worktrees/{branch}"  # last segment becomes the slug
+  trunk: master                                # optional; else origin/HEAD
+
+isolation:
+  db_drop: "mysql -hmysql -uroot -e 'DROP DATABASE IF EXISTS wt_{slug}'"
+  redis_flush: "redis-cli -n {n} flushdb"
+```
+
+- `worktrees.path` resolves `local_get` → `cfg_get` → built-in default,
+  matching how ports and isolation already layer. Personal layouts (Orca)
+  belong in `worktree-kit.local.yml`; the committed file carries the team
+  default.
+- `worktrees.trunk` is optional.
+- `isolation.db_drop` and `isolation.redis_flush` are optional and run through
+  the configured runner with own-db isolation env, symmetric with the
+  existing `db_check` and `db_bootstrap`.
+- The config cache dumper flattens the whole file, so these keys need **no
+  cache changes** — they are read with the existing `cfg_get` / `local_get`.
+- All ten templates under `templates/{compose,host}/` gain both blocks,
+  commented in the style of the existing keys.
+
+## 13. `wt doctor` additions
+
+1. Warn when the path template's last segment is not branch-unique.
+2. Warn when the template would produce a path containing a space.
+3. Report whether `fzf` is present.
+4. Report whether shell integration is installed. A child process cannot
+   inspect its parent shell's functions, so the check is twofold: honour
+   `WT_SHELL_INTEGRATION` if the wrapper exported it, otherwise grep the
+   user's rc files (`~/.zshrc`, `~/.bashrc`, `~/.bash_profile`,
+   `~/.config/fish/config.fish`) for `wt shell-init`. Report "unknown"
+   rather than "missing" when neither is conclusive.
+
+## 14. Testing
+
+The five lifecycle commands need only `git`, so they test against a scratch
+repo with no docker and run in all three existing suites — macOS,
+`test/linux-debian.sh`, `test/linux-alpine.sh`.
+
+Cases:
+
+1. `new` — asserts the created path, the branch, and that the resulting slug
+   matches what `ctx_init` derives from the directory basename.
+2. `new` adopting an existing branch that has no worktree.
+3. `new` on a branch that already has a worktree — asserts the error.
+4. `list` — column contents, including a worktree with no config.
+5. `switch` — a bare path on stdout, hints on stderr, exit status.
+6. `merge` — happy path, asserting the squashed commit and fast-forwarded
+   trunk.
+7. **`merge` with a deliberate conflict** — asserts the backup ref restores
+   the pre-squash state exactly and the worktree is untouched.
+8. `rm` — asserts no `wt-state` residue for the slug.
+9. Path template containing a space — asserts the hard error.
+
+Alpine coverage matters most: BusyBox ash is where bugs 1, 7, and 8 all
+surfaced.
+
+## 15. Estimated size
+
+Roughly 450–500 lines added to `bin/wt`, taking it from 628 to about 1100.
+CONTEXT.md §2 rejected `lib/*.sh` for vendoring simplicity; that decision
+stands, and `install.sh` remains a single symlink.
+
+## 16. Deferred
+
+- `wt merge --pr` (verify an upstream PR merged via `gh`, then clean up).
+  Rejected for v1 to keep merge's code and test matrix small; merge is the
+  command most able to destroy work.
+- Build-cache copying between worktrees (§3).
+- Any resolution of the `wt` binary name collision with worktrunk.
diff --git a/test/lifecycle.sh b/test/lifecycle.sh
index 1f9eb1c..c4cf457 100755
--- a/test/lifecycle.sh
+++ b/test/lifecycle.sh
@@ -40,6 +40,49 @@ assert_fails() { # <label> <cmd...>
   if "$@" >/dev/null 2>&1; then fail "$_l: expected nonzero exit"; else ok "$_l"; fi
 }
 
+# Setup calls whose failure is not itself the thing under test. Without this
+# a regression in `wt new` (say) aborts the whole run under `set -eu` with no
+# FAIL line at all — CI still notices (LIFECYCLE PASS never prints) but the
+# diagnostic is gone. Never use it inside assert_fails, and never for a call
+# whose output is being asserted (guard the capture instead).
+wt_ok() { "$WT" "$@" >/dev/null 2>&1 || fail "setup: wt $*"; }
+
+# Does this host have any YAML backend at all? Anything that makes wt read a
+# worktree-kit.yml needs one; without it load_config dies and an unguarded
+# capture would abort the suite silently.
+have_yaml() {
+  command -v yq >/dev/null 2>&1 || command -v ruby >/dev/null 2>&1 \
+    || python3 -c 'import yaml' >/dev/null 2>&1
+}
+
+# A PATH on which `command -v docker` genuinely finds nothing.
+#
+# Two tests need docker to be *absent*, not merely broken: they cover
+# `need docker` never firing for load_config_soft, and firing (so the stop
+# fails and gets reported) for require_config. A stub that exits 127 would
+# satisfy `command -v` and prove neither.
+#
+# Truncating PATH to /usr/bin:/bin is not it either: on Linux docker lives in
+# /usr/bin, so the second assertion would invert and pass vacuously, and the
+# truncation can take yq/ruby/python3 (and even git) down with it. Instead
+# drop every directory that actually holds a docker executable, and symlink
+# the tools wt needs into a scratch bin first so the drop cannot remove them.
+NODOCKER_BIN="$TMP/nodocker-bin"
+mkdir -p "$NODOCKER_BIN"
+for _t in git sh awk sed grep tr cut head tail cat basename dirname mkdir rm mv \
+          cksum wc find xargs column sort yq ruby python3; do
+  _p="$(command -v "$_t" 2>/dev/null)" || continue
+  case "$_p" in /*) ln -s "$_p" "$NODOCKER_BIN/$_t" 2>/dev/null || true ;; esac
+done
+NODOCKER_PATH="$NODOCKER_BIN"
+_oldifs="$IFS"; IFS=:
+for _d in $PATH; do
+  [ -n "$_d" ] || _d=.
+  if [ -x "$_d/docker" ]; then continue; fi
+  NODOCKER_PATH="$NODOCKER_PATH:$_d"
+done
+IFS="$_oldifs"
+
 # Creates a repo with one commit on branch `master`; sets REPO and cds into it.
 new_repo() {
   REPO="$TMP/$1"
@@ -57,25 +100,30 @@ new_repo() {
 # ---------- Task 1: list ----------
 
 new_repo listrepo
-out="$("$WT" list)"
+out="$("$WT" list)" || fail "setup: wt list"
 assert_contains "$out" master           "list: shows the primary branch"
 assert_contains "$out" BRANCH           "list: prints a header"
-assert_missing  "$out" "MISSING"        "list: no config is not an error"
+# Was assert_missing "$out" "MISSING" — a string cmd_list has no code path to
+# print (it belongs to cmd_doctor), i.e. an assertion that could not fail.
+# What "no config is not an error" actually means for wt list is that the
+# missing config draws no complaint on stderr and no nonzero exit.
+err="$("$WT" list 2>&1 >/dev/null)" || fail "list: nonzero exit without a config"
+assert_eq "" "$err"                     "list: no config is not an error"
 
 git worktree add -q "$TMP/feat-one" -b feat/one
-out="$("$WT" list)"
+out="$("$WT" list)" || fail "setup: wt list"
 assert_contains "$out" "feat/one"       "list: shows a second worktree"
 assert_contains "$out" "feat_one"       "list: slug matches ctx_init derivation"
 assert_contains "$out" "clean"          "list: clean worktree reports clean"
 
 echo dirty > "$TMP/feat-one/x.txt"
-out="$("$WT" list)"
+out="$("$WT" list)" || fail "setup: wt list"
 assert_contains "$out" "dirty"          "list: dirty worktree reports dirty"
 
 git branch -q spare
-out="$("$WT" list --all)"
+out="$("$WT" list --all)" || fail "setup: wt list --all"
 assert_contains "$out" "spare"          "list --all: includes branches with no worktree"
-out="$("$WT" list)"
+out="$("$WT" list)" || fail "setup: wt list"
 assert_missing  "$out" "spare"          "list: plain list omits branchless branches"
 
 # existing commands must still refuse to run without a config
@@ -87,13 +135,17 @@ assert_fails "run still requires config" "$WT" run -- true
 # commands (via require_config) may demand it.
 new_repo nodockerrepo
 printf 'hooks:\n  server: "true"\n' > worktree-kit.yml
-out="$(PATH=/usr/bin:/bin "$WT" list)"
-assert_contains "$out" master "list: works with a compose config and no docker on PATH"
+if have_yaml; then
+  out="$(PATH="$NODOCKER_PATH" "$WT" list)" || fail "list: died with a compose config and no docker"
+  assert_contains "$out" master "list: works with a compose config and no docker on PATH"
+else
+  ok "list: works with a compose config and no docker on PATH (skipped: no YAML backend)"
+fi
 
 # ---------- Task 2: new ----------
 
 new_repo newrepo
-out="$("$WT" new feat/refund-flow 2>/dev/null)"
+out="$("$WT" new feat/refund-flow 2>/dev/null)" || fail "setup: wt new feat/refund-flow"
 assert_eq "$TMP/newrepo-worktrees/feat_refund_flow" "$out" \
   "new: default template, branch sanitized for the path"
 assert_eq "0" "$(test -d "$TMP/newrepo-worktrees/feat_refund_flow"; echo $?)" \
@@ -104,7 +156,7 @@ assert_contains "$("$WT" list)" "feat_refund_flow" "new: slug is the last path s
 
 # a branch that exists but has no worktree is adopted, not rejected
 git -C "$REPO" branch -q orphan
-out="$("$WT" new orphan 2>/dev/null)"
+out="$("$WT" new orphan 2>/dev/null)" || fail "setup: wt new orphan"
 assert_eq "$TMP/newrepo-worktrees/orphan" "$out" "new: adopts an existing branch"
 
 # a branch that already has a worktree is an error
@@ -114,10 +166,23 @@ assert_fails "new: rejects a branch that already has a worktree" "$WT" new orpha
 git -C "$REPO" checkout -q -b basis
 echo b > "$REPO/b.txt"; git -C "$REPO" add b.txt; git -C "$REPO" commit -qm basis
 git -C "$REPO" checkout -q master
-"$WT" new derived --from basis >/dev/null 2>&1
+wt_ok new derived --from basis
 assert_eq "0" "$(test -f "$TMP/newrepo-worktrees/derived/b.txt"; echo $?)" \
   "new --from: branched from the named base"
 
+# expand_path feeds {parent} {repo} {home} and {branch_raw} to sed as
+# REPLACEMENT text, where & means "the whole match" and \ starts an escape.
+# The DEFAULT template uses {parent} and {repo}, so a repo directory holding
+# an & silently produced a wrong path (R&D-app -> R{repo}D-app) — and the
+# last segment of that path is what names the slug, the port, the redis slot
+# and the database.
+new_repo 'R&D-app'
+ampout="$("$WT" new feat/amp 2>/dev/null)" || fail "setup: wt new in an & repo"
+assert_eq "$TMP/R&D-app-worktrees/feat_amp" "$ampout" \
+  "new: an & in the repo directory survives path expansion literally"
+assert_eq "0" "$(test -d "$TMP/R&D-app-worktrees/feat_amp" && echo 0 || echo 1)" \
+  "new: the & path is the directory actually created"
+
 # a template that yields a space is refused before anything is created
 new_repo spacerepo
 printf 'runner: host\nhooks:\n  server: "true"\n' > worktree-kit.yml
@@ -138,22 +203,27 @@ _counter="$TMP/prepare-count.txt"
 : > "$_counter"
 printf 'runner: host\nhooks:\n  prepare: "echo x >> %s"\n  server: "true"\n' "$_counter" \
   > worktree-kit.yml
-"$WT" new prepped >/dev/null 2>&1
-assert_eq "1" "$(wc -l < "$_counter" | tr -d ' ')" "new: prepare hook runs exactly once"
+if have_yaml; then
+  wt_ok new prepped
+  assert_eq "1" "$(wc -l < "$_counter" | tr -d ' ')" "new: prepare hook runs exactly once"
+else
+  ok "new: prepare hook runs exactly once (skipped: no YAML backend)"
+fi
 
 # ---------- Task 3: switch and shell-init ----------
 
 new_repo switchrepo
-"$WT" new feat/alpha >/dev/null 2>&1
+wt_ok new feat/alpha
 
 # stdout carries only the path; the hint goes to stderr
-out="$("$WT" switch feat/alpha 2>/dev/null)"
+out="$("$WT" switch feat/alpha 2>/dev/null)" || fail "setup: wt switch feat/alpha"
 assert_eq "$TMP/switchrepo-worktrees/feat_alpha" "$out" "switch: stdout is the bare path"
 
-err="$("$WT" switch feat/alpha 2>&1 >/dev/null)"
+err="$("$WT" switch feat/alpha 2>&1 >/dev/null)" || fail "setup: wt switch feat/alpha"
 assert_contains "$err" "shell-init" "switch: hints about shell integration on stderr"
 
-err="$(WT_SHELL_INTEGRATION=1 "$WT" switch feat/alpha 2>&1 >/dev/null)"
+err="$(WT_SHELL_INTEGRATION=1 "$WT" switch feat/alpha 2>&1 >/dev/null)" \
+  || fail "setup: wt switch feat/alpha under shell integration"
 assert_eq "" "$err" "switch: no stderr noise under shell integration"
 
 assert_fails "switch: unknown branch is an error" "$WT" switch nope
@@ -165,22 +235,29 @@ err="$("$WT" switch lonely 2>&1 >/dev/null || true)"
 assert_contains "$err" "wt new lonely" "switch: branch without a worktree points at wt new"
 
 # shell-init emits a wrapper covering all four cd-channel commands
-out="$("$WT" shell-init zsh)"
+out="$("$WT" shell-init zsh)" || fail "setup: wt shell-init zsh"
 assert_contains "$out" "switch|new|rm|merge" "shell-init: wraps every cd-channel command"
 assert_contains "$out" "WT_SHELL_INTEGRATION=1" "shell-init: exports the marker"
 assert_contains "$out" 'if [ -n "$__wt_d" ]; then' "shell-init: explicit if, not && (bug 1)"
-out="$("$WT" shell-init fish)"
+out="$("$WT" shell-init fish)" || fail "setup: wt shell-init fish"
 assert_contains "$out" "function wt" "shell-init: fish variant"
+# fish gained single-command variable overrides (VAR=x cmd) late; on older
+# releases that form is a SYNTAX error, which would make `eval (wt shell-init
+# fish)` break the wt function outright. `env VAR=x cmd` parses everywhere.
+assert_contains "$out" 'env WT_SHELL_INTEGRATION=1 wt $argv' \
+  "shell-init: fish uses env, not a fish-version-dependent inline override"
+assert_missing "$out" '(WT_SHELL_INTEGRATION=1 command wt' \
+  "shell-init: fish avoids the inline override form entirely"
 assert_fails "shell-init: rejects an unknown shell" "$WT" shell-init tcsh
 
 # shell-init must work outside a git repo
-out="$(cd "$TMP" && "$WT" shell-init bash)"
+out="$(cd "$TMP" && "$WT" shell-init bash)" || fail "setup: wt shell-init bash outside a repo"
 assert_contains "$out" "command wt" "shell-init: works outside a git repo"
 
 # ---------- Task 4: rm ----------
 
 new_repo rmrepo
-"$WT" new feat/gone >/dev/null 2>&1
+wt_ok new feat/gone
 wtdir="$TMP/rmrepo-worktrees/feat_gone"
 
 # fabricate the state files a server would have left behind
@@ -190,18 +267,28 @@ mkdir -p "$state/logs"
 : > "$state/feat_gone.port"
 : > "$state/logs/feat_gone.log"
 
-# a dirty worktree is refused without --force
+# a dirty worktree is refused without --force. assert_fails only pins the
+# exit code, so each refusal below also pins WHY — a guard-ordering
+# regression that refused for a different reason would otherwise pass.
 echo scratch > "$wtdir/scratch.txt"
 assert_fails "rm: refuses a dirty worktree" "$WT" rm feat/gone
+err="$("$WT" rm feat/gone 2>&1 >/dev/null || true)"
+assert_contains "$err" "uncommitted changes" "rm: the dirty refusal names uncommitted changes"
 assert_eq "0" "$(test -d "$wtdir" && echo 0 || echo 1)" "rm: dirty worktree survives the refusal"
 rm "$wtdir/scratch.txt"
 
 # unmerged commits are refused without --force
 ( cd "$wtdir" && echo c > c.txt && git add c.txt && git commit -qm work )
 assert_fails "rm: refuses unmerged commits" "$WT" rm feat/gone
-
-# --force removes it and reclaims every state file
-"$WT" rm feat/gone --force >/dev/null 2>&1
+err="$("$WT" rm feat/gone 2>&1 >/dev/null || true)"
+assert_contains "$err" "commit(s) not in master" \
+  "rm: the unmerged refusal names the commits and the trunk"
+
+# --force removes it and reclaims every state file. Nothing may reach stdout:
+# the removed worktree was not the caller's cwd, and stdout is the cd channel
+# — a stray line there makes the shell wrapper cd to garbage.
+rmout="$("$WT" rm feat/gone --force 2>/dev/null)" || fail "setup: wt rm feat/gone --force"
+assert_eq "" "$rmout" "rm: silent on stdout when the cwd was not removed"
 assert_eq "1" "$(test -d "$wtdir" && echo 0 || echo 1)"                    "rm --force: worktree gone"
 assert_eq "1" "$(test -f "$state/feat_gone.dbready" && echo 0 || echo 1)"  "rm --force: dbready cleared"
 assert_eq "1" "$(test -f "$state/feat_gone.port" && echo 0 || echo 1)"     "rm --force: port file cleared"
@@ -210,8 +297,8 @@ assert_missing "$(git -C "$REPO" branch --list 'feat/gone')" "feat/gone" \
   "rm --force: branch deleted"
 
 # --keep-branch keeps the branch
-"$WT" new feat/keep >/dev/null 2>&1
-"$WT" rm feat/keep --force --keep-branch >/dev/null 2>&1
+wt_ok new feat/keep
+wt_ok rm feat/keep --force --keep-branch
 assert_contains "$(git -C "$REPO" branch --list 'feat/keep')" "feat/keep" \
   "rm --keep-branch: branch survives"
 
@@ -219,13 +306,13 @@ assert_contains "$(git -C "$REPO" branch --list 'feat/keep')" "feat/keep" \
 assert_fails "rm: refuses the primary checkout" "$WT" rm master --force
 
 # a clean, fully merged worktree needs no --force, but does need a yes
-"$WT" new feat/clean >/dev/null 2>&1
-printf 'y\n' | "$WT" rm feat/clean >/dev/null 2>&1
+wt_ok new feat/clean
+printf 'y\n' | "$WT" rm feat/clean >/dev/null 2>&1 || fail "setup: wt rm feat/clean"
 assert_eq "1" "$(test -d "$TMP/rmrepo-worktrees/feat_clean" && echo 0 || echo 1)" \
   "rm: clean merged worktree removed after confirmation"
 
 # answering no leaves everything alone
-"$WT" new feat/spared >/dev/null 2>&1
+wt_ok new feat/spared
 printf 'n\n' | "$WT" rm feat/spared >/dev/null 2>&1 || true
 assert_eq "0" "$(test -d "$TMP/rmrepo-worktrees/feat_spared" && echo 0 || echo 1)" \
   "rm: declining the prompt keeps the worktree"
@@ -237,7 +324,7 @@ assert_eq "0" "$(test -d "$TMP/rmrepo-worktrees/feat_spared" && echo 0 || echo 1
 # then git branch -d's getcwd() call dies) and still land the caller in the
 # primary via the cd channel. Runs first, in rmrepo, while $REPO/cwd still
 # point there — every later block in this section calls new_repo again.
-"$WT" new feat/herecwd >/dev/null 2>&1
+wt_ok new feat/herecwd
 wtdir_here="$TMP/rmrepo-worktrees/feat_herecwd"
 rmrepo_repo="$REPO"
 out="$( (cd "$wtdir_here" && "$WT" rm feat/herecwd --force 2>/dev/null) || true )"
@@ -247,18 +334,23 @@ assert_eq "$rmrepo_repo" "$out" "rm: from inside the worktree, prints the primar
 # ownership gate, db_drop, redis_flush, the "left behind" notices, and the
 # SLUG/N borrow) is otherwise never exercised — rmrepo above has no config.
 new_repo cfgrmrepo
+if have_yaml; then
 db_sentinel="$TMP/db-drop.sentinel"
 redis_sentinel="$TMP/redis-flush.sentinel"
+# hooks.prepare records the cwd runner_exec used, so the teardown's target
+# can be checked, not just its effect.
+where_sentinel="$TMP/prepare-cwd.sentinel"
 cat > worktree-kit.yml <<YML
 runner: host
 hooks:
+  prepare: "pwd >> $where_sentinel"
   server: "true"
 isolation:
   db_drop: "echo dropped-{slug} >> $db_sentinel"
   redis_flush: "echo flushed-{slug}-{n} >> $redis_sentinel"
 YML
-"$WT" new feat/owned >/dev/null 2>&1
-"$WT" new feat/adopted >/dev/null 2>&1
+wt_ok new feat/owned
+wt_ok new feat/adopted
 cfgstate="$REPO/.git/wt-state"
 # feat_owned: the kit bootstrapped this database itself.
 : > "$cfgstate/feat_owned.dbready"
@@ -268,37 +360,80 @@ cfgstate="$REPO/.git/wt-state"
 # stands in for a database wt rm must never drop.
 : > "$cfgstate/feat_adopted.dbready"
 
-"$WT" rm feat/owned --force >/dev/null 2>&1
+# Discard what `wt new` itself recorded; only the teardown's runs matter.
+: > "$where_sentinel"
+wt_ok rm feat/owned --force
 assert_contains "$(cat "$db_sentinel" 2>/dev/null)" "dropped-feat_owned" \
   "rm: drops a database the kit itself bootstrapped"
 assert_contains "$(cat "$redis_sentinel" 2>/dev/null)" "flushed-feat_owned-" \
   "rm: flushes the redis slot for a configured worktree (SLUG/N borrow works)"
-
-"$WT" rm feat/adopted --force >/dev/null 2>&1
+# teardown_worktree borrowed SLUG and N for the target but left $WT_PATH
+# pointing at the CALLER's worktree, which is what runner_exec keys off: the
+# repo's prepare hook re-ran in the caller (bundle install, npm ci, ...) and
+# db_drop/redis_flush resolved relative paths against the wrong tree.
+assert_contains "$(cat "$where_sentinel" 2>/dev/null)" \
+  "$TMP/cfgrmrepo-worktrees/feat_owned" \
+  "rm: teardown hooks run in the TARGET worktree"
+# grep -xF, not assert_missing: $REPO is a string PREFIX of the target path,
+# so a substring test could never distinguish the two.
+assert_eq "" "$(grep -xF "$REPO" "$where_sentinel" 2>/dev/null || true)" \
+  "rm: teardown hooks never re-run in the caller's worktree"
+
+wt_ok rm feat/adopted --force
 assert_missing "$(cat "$db_sentinel" 2>/dev/null)" "dropped-feat_adopted" \
   "rm: never drops a database it only adopted (.dbready without .dbowned)"
 
+# The no-.dbowned notice is what every pre-0.2.0 user sees on their first
+# wt rm: .dbowned did not exist before this release, so their kit-created
+# databases carry only .dbready. It must not claim wt did not create them.
+wt_ok new feat/msg
+: > "$cfgstate/feat_msg.dbready"
+err="$("$WT" rm feat/msg --force 2>&1 >/dev/null)" || true
+assert_contains "$err" "no ownership marker" \
+  "rm: the no-.dbowned notice does not assert the database was adopted"
+assert_missing "$err" "adopted, not created by wt" \
+  "rm: the no-.dbowned notice is not wrong for upgrading users"
+else
+  for _l in "rm: drops a database the kit itself bootstrapped" \
+            "rm: flushes the redis slot for a configured worktree (SLUG/N borrow works)" \
+            "rm: teardown hooks run in the TARGET worktree" \
+            "rm: teardown hooks never re-run in the caller's worktree" \
+            "rm: never drops a database it only adopted (.dbready without .dbowned)" \
+            "rm: the no-.dbowned notice does not assert the database was adopted" \
+            "rm: the no-.dbowned notice is not wrong for upgrading users"; do
+    ok "$_l (skipped: no YAML backend)"
+  done
+fi
+
 # Item 2: a configured trunk that does not resolve as a ref in this worktree
 # must not be silently treated as "nothing unmerged" — "cannot check" must
 # not mean "safe to delete" for a destructive command.
 new_repo trunkguardrepo
 printf 'runner: host\nhooks:\n  server: "true"\nworktrees:\n  trunk: develop\n' \
   > worktree-kit.yml
-"$WT" new feat/risky >/dev/null 2>&1
-( cd "$TMP/trunkguardrepo-worktrees/feat_risky" && echo x > x.txt && git add x.txt && git commit -qm risky )
-printf 'y\n' | "$WT" rm feat/risky >/dev/null 2>&1 || true
-assert_eq "0" "$(test -d "$TMP/trunkguardrepo-worktrees/feat_risky" && echo 0 || echo 1)" \
-  "rm: an unverifiable configured trunk refuses rather than failing open"
+if have_yaml; then
+  wt_ok new feat/risky
+  ( cd "$TMP/trunkguardrepo-worktrees/feat_risky" && echo x > x.txt && git add x.txt && git commit -qm risky )
+  printf 'y\n' | "$WT" rm feat/risky >/dev/null 2>&1 || true
+  assert_eq "0" "$(test -d "$TMP/trunkguardrepo-worktrees/feat_risky" && echo 0 || echo 1)" \
+    "rm: an unverifiable configured trunk refuses rather than failing open"
+else
+  ok "rm: an unverifiable configured trunk refuses rather than failing open (skipped: no YAML backend)"
+fi
 
 # Item 4: a failed server-stop must be surfaced, not swallowed — otherwise
 # state files vanish, wt ps can no longer see the orphaned server, and wt rm
 # still reports success.
 new_repo swallowfailrepo
 printf 'hooks:\n  server: "true"\n' > worktree-kit.yml
-"$WT" new feat/failstop >/dev/null 2>&1
-err="$(PATH=/usr/bin:/bin "$WT" rm feat/failstop --force 2>&1 >/dev/null)"
-assert_contains "$err" "could not stop the server" \
-  "rm: a failed server-stop is reported, not swallowed"
+if have_yaml; then
+  wt_ok new feat/failstop
+  err="$(PATH="$NODOCKER_PATH" "$WT" rm feat/failstop --force 2>&1 >/dev/null)" || true
+  assert_contains "$err" "could not stop the server" \
+    "rm: a failed server-stop is reported, not swallowed"
+else
+  ok "rm: a failed server-stop is reported, not swallowed (skipped: no YAML backend)"
+fi
 
 # ---------- Task 4 fix round 2 ----------
 
@@ -312,12 +447,67 @@ rstate="$REPO/.git/wt-state"
 mkdir -p "$rstate"
 : > "$rstate/someslug.dbready"
 : > "$rstate/someslug.dbowned"
-"$WT" reset someslug >/dev/null 2>&1
+wt_ok reset someslug
 assert_eq "1" "$(test -f "$rstate/someslug.dbready" && echo 0 || echo 1)" \
   "reset: clears the dbready marker"
 assert_eq "1" "$(test -f "$rstate/someslug.dbowned" && echo 0 || echo 1)" \
   "reset: clears the dbowned marker too"
 
+# ---------- Task 4 fix round 3: removal after the irreversible half ----------
+#
+# Both callers run teardown_worktree FIRST — server stopped, DROP DATABASE,
+# FLUSHDB, every state file gone. Only then is the worktree/branch removed.
+# Bare git calls there mean a failure at that point aborts under set -e with
+# nothing but git's own stderr: no "removed", no cd-channel output, and no
+# hint that the irreversible half already ran.
+
+# The reachable case: `git branch -d` asks "merged into HEAD?", a different
+# question from the "merged into trunk?" cmd_rm already answered. Removing a
+# sibling worktree leaves cwd — and HEAD — on the sibling's branch, so -d can
+# refuse a branch wt has verified.
+new_repo unmergedheadrepo
+wt_ok new feat/behind                      # stays at master's original commit
+bhdir="$TMP/unmergedheadrepo-worktrees/feat_behind"
+wt_ok new feat/ahead
+ahdir="$TMP/unmergedheadrepo-worktrees/feat_ahead"
+( cd "$ahdir" && echo z > z.txt && git add z.txt && git commit -qm z )
+git -C "$REPO" merge -q --ff-only feat/ahead   # merged into trunk, not into feat/behind
+rmerr="$( (cd "$bhdir" && printf 'y\n' | "$WT" rm feat/ahead 2>&1 >/dev/null) )" \
+  || fail "rm: a git branch -d refusal must not abort after teardown"
+assert_eq "1" "$(test -d "$ahdir" && echo 0 || echo 1)" \
+  "rm: the worktree is still removed when git branch -d refuses"
+assert_contains "$rmerr" "refused to delete branch" \
+  "rm: a git branch -d refusal is reported, not fatal"
+
+# The happy cross-worktree case: removing a sibling must succeed, delete the
+# branch, and print nothing at all on the cd channel.
+new_repo crossrmrepo
+wt_ok new feat/a
+adir="$TMP/crossrmrepo-worktrees/feat_a"
+( cd "$adir" && echo a > a.txt && git add a.txt && git commit -qm a )
+git -C "$REPO" merge -q --ff-only feat/a
+wt_ok new feat/b                           # branched from master, which now has feat/a
+bdir="$TMP/crossrmrepo-worktrees/feat_b"
+crossout="$( (cd "$bdir" && printf 'y\n' | "$WT" rm feat/a 2>/dev/null) )" \
+  || fail "rm: cross-worktree removal failed"
+assert_eq "" "$crossout" "rm: silent on stdout when a sibling worktree was removed"
+assert_missing "$(git -C "$REPO" branch --list 'feat/a')" "feat/a" \
+  "rm: cross-worktree branch deleted"
+assert_eq "1" "$(test -d "$adir" && echo 0 || echo 1)" "rm: cross-worktree directory removed"
+
+# git worktree remove itself can fail after teardown (a locked worktree is
+# the reliable trigger). The message must say the reclaim already happened.
+new_repo lockedrmrepo
+wt_ok new feat/locked
+ldir="$TMP/lockedrmrepo-worktrees/feat_locked"
+git -C "$REPO" worktree lock "$ldir"
+lockerr="$(printf 'y\n' | "$WT" rm feat/locked 2>&1 >/dev/null || true)"
+assert_contains "$lockerr" "already reclaimed" \
+  "rm: a failed worktree removal says the server, database and state are already gone"
+assert_contains "$lockerr" "git worktree prune" \
+  "rm: a failed worktree removal prints the recovery command"
+git -C "$REPO" worktree unlock "$ldir"
+
 # ---------- Task 5: merge ----------
 
 new_repo mergerepo
@@ -328,7 +518,10 @@ wtdir="$TMP/mergerepo-worktrees/feat_work"
 pre_merge_head="$(git -C "$wtdir" rev-parse HEAD)"
 
 before="$(git -C "$REPO" rev-parse master)"
-"$WT" merge feat/work >/dev/null 2>&1 || fail "merge: feat/work merge failed"
+# Capture stdout rather than discarding it: the removed worktree is not the
+# caller's cwd, so spec §5 requires nothing at all on the cd channel.
+mout="$("$WT" merge feat/work 2>/dev/null)" || fail "merge: feat/work merge failed"
+assert_eq "" "$mout" "merge: silent on stdout when the cwd was not removed"
 after="$(git -C "$REPO" rev-parse master)"
 
 # assert_eq "1" "$(test A = B; echo $?)" dies inside the substitution under
@@ -391,7 +584,15 @@ assert_eq "$master_before" "$(git -C "$REPO" rev-parse master)" \
   "merge: master untouched after a conflict"
 assert_eq "0" "$(test -d "$cdir" && echo 0 || echo 1)" "merge: worktree survives a conflict"
 assert_eq "" "$(git -C "$cdir" status --porcelain)" \
-  "merge: no rebase left in progress"
+  "merge: working tree left clean after a conflict"
+# status --porcelain reports working-tree state, not rebase state — an
+# interrupted rebase with a clean tree passes it. Ask git for the real thing:
+# neither rebase state directory may exist (merge backend or am backend).
+rebase_state=0
+for _d in rebase-merge rebase-apply; do
+  if [ -e "$(git -C "$cdir" rev-parse --git-path "$_d")" ]; then rebase_state=1; fi
+done
+assert_eq "0" "$rebase_state" "merge: no rebase left in progress"
 
 # guards
 new_repo guardrepo
@@ -450,6 +651,9 @@ pushed_head="$(git -C "$pdir" rev-parse HEAD)"
 master_before_upstream="$(git -C "$REPO" rev-parse master)"
 
 assert_fails "merge: refuses a branch with an upstream without --force" "$WT" merge feat/pushed
+uerr="$("$WT" merge feat/pushed 2>&1 >/dev/null || true)"
+assert_contains "$uerr" "has an upstream" \
+  "merge: the upstream refusal names the upstream, not some later incidental failure"
 assert_eq "0" "$(test -d "$pdir" && echo 0 || echo 1)" \
   "merge: refused-upstream worktree survives"
 assert_eq "$master_before_upstream" "$(git -C "$REPO" rev-parse master)" \
@@ -480,35 +684,47 @@ assert_eq "$cwdrepo_repo" "$out" "merge: from inside the worktree, prints the pr
 # ---------- Task 6: doctor ----------
 
 new_repo doctorrepo
-out="$("$WT" doctor 2>&1)"
+out="$("$WT" doctor 2>&1)" || fail "setup: wt doctor"
 assert_contains "$out" "wt path:" "doctor: reports the path template"
 assert_contains "$out" "fzf:"     "doctor: reports fzf availability"
 assert_contains "$out" "shell:"   "doctor: reports shell integration state"
 
-out="$(WT_SHELL_INTEGRATION=1 "$WT" doctor 2>&1)"
+out="$(WT_SHELL_INTEGRATION=1 "$WT" doctor 2>&1)" || fail "setup: wt doctor under integration"
 assert_contains "$out" "integration active" "doctor: detects an active wrapper"
 
+# $HOME is dereferenced unguarded under set -eu in two places doctor reaches:
+# the {home} path expansion (evaluated whether or not the template uses it)
+# and the rc-file scan. env -i, some CI runners and some container
+# entrypoints leave HOME unset, where a bare $HOME is a fatal
+# parameter-not-set rather than a missing-integration report.
+if ( unset HOME; "$WT" doctor >/dev/null 2>&1 ); then
+  ok "doctor: survives an unset HOME"
+else
+  fail "doctor: survives an unset HOME"
+fi
+homeout="$( (unset HOME; "$WT" doctor 2>&1) || true )"
+assert_contains "$homeout" "shell:" "doctor: still reports shell integration with HOME unset"
+
 # The two template warnings need a YAML backend to read the .local file, AND
 # a main worktree-kit.yml to exist — load_config_soft gates on $CONFIG (the
 # non-local file), not $LOCAL_CONFIG, so with only the .local file present
 # HAS_CONFIG stays 0 and path_template() never consults either file. runner:
 # host is mandatory here (not compose) — require_config would otherwise
 # demand docker, which is not running in this environment.
-if command -v yq >/dev/null 2>&1 || command -v ruby >/dev/null 2>&1 \
-   || python3 -c 'import yaml' >/dev/null 2>&1; then
+if have_yaml; then
   printf 'runner: host\nhooks:\n  server: "true"\n' > worktree-kit.yml
   cat > worktree-kit.local.yml <<'YML'
 worktrees:
   path: "{parent}/{repo}-worktrees/fixed"
 YML
-  out="$("$WT" doctor 2>&1)"
+  out="$("$WT" doctor 2>&1)" || fail "setup: wt doctor with a fixed template"
   assert_contains "$out" "not branch-unique" "doctor: warns on a non-branch-unique template"
 
   cat > worktree-kit.local.yml <<'YML'
 worktrees:
   path: "{parent}/has space/{branch}"
 YML
-  out="$("$WT" doctor 2>&1)"
+  out="$("$WT" doctor 2>&1)" || fail "setup: wt doctor with a spacey template"
   # Not "space" alone: the unconditional "wt path:" line above already
   # echoes the raw template, which contains "has space" from the fixture's
   # own directory name — that substring would match whether or not the WARN
@@ -519,5 +735,33 @@ else
   ok "doctor: template warnings skipped (no YAML backend installed)"
 fi
 
+# ---------- worktrees.path from the COMMITTED config ----------
+#
+# All ten shipped templates carry worktrees.path in worktree-kit.yml, but
+# every other path test above writes worktree-kit.local.yml — so only
+# local_get was covered and path_template()'s cfg_get fallback never ran.
+# runner: host, not compose: compose would make wt new demand docker.
+new_repo cfgpathrepo
+if have_yaml; then
+  cat > worktree-kit.yml <<'YML'
+runner: host
+hooks:
+  server: "true"
+worktrees:
+  path: "{parent}/wt-committed-path/{branch}"
+YML
+  out="$("$WT" new feat/mainpath 2>/dev/null)" || fail "setup: wt new under a committed worktrees.path"
+  assert_eq "$TMP/wt-committed-path/feat_mainpath" "$out" \
+    "worktrees.path: a committed (non-.local) template drives the created path"
+  assert_eq "0" "$(test -d "$TMP/wt-committed-path/feat_mainpath" && echo 0 || echo 1)" \
+    "worktrees.path: the committed template's directory is the one created"
+  assert_contains "$("$WT" list)" "feat_mainpath" \
+    "worktrees.path: the slug follows the committed template's last segment"
+else
+  ok "worktrees.path: a committed (non-.local) template drives the created path (skipped: no YAML backend)"
+  ok "worktrees.path: the committed template's directory is the one created (skipped: no YAML backend)"
+  ok "worktrees.path: the slug follows the committed template's last segment (skipped: no YAML backend)"
+fi
+
 [ "$FAILED" = 0 ] || { echo "LIFECYCLE FAIL" >&2; exit 1; }
 echo "LIFECYCLE PASS"

From f936d19aa53b585c69ea5dc7f3da0078176e4449 Mon Sep 17 00:00:00 2001
From: Ethan <sangnguyen07dhth@gmail.com>
Date: Sat, 29 Aug 2026 23:00:20 +0700
Subject: [PATCH 15/15] docs: correct the pre-0.2.0 db recovery advice, note
 the .dbowned cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The db_drop bullet told upgrading users that `wt reset <slug>` plus an
--own-db cycle would re-bootstrap and re-mark a pre-0.2.0 database. It
cannot: reset clears both markers, but ensure_own_db then runs db_check,
which succeeds because the database still exists, and returns having
touched only .dbready. .dbowned is written solely on the db_bootstrap
path, which runs only when the database is missing. The bullet therefore
contradicted its own case (b) two lines further down. It now says to drop
the database by hand first, and explains why reset alone is not enough.

Also amends spec §10.1 step 7, which still listed four state files while
the implementation removes .dbowned as well — a fourth divergence, marked
like the other three, and the status header updated to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  8 ++++++--
 .../2026-08-29-worktree-lifecycle-design.md   | 20 +++++++++++++++----
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 82516e1..31ba728 100644
--- a/README.md
+++ b/README.md
@@ -274,8 +274,12 @@ Three levels, each a superset of the last:
   are deliberate — wt errs toward keeping data:
   **(a)** databases bootstrapped **before wt 0.2.0**, when `.dbowned` did not
   exist yet. On your first `wt rm` after upgrading, those report "no
-  ownership marker" and are left alone; drop them by hand, or run one
-  `wt reset <slug>` + `--own-db` cycle to re-bootstrap and re-mark them.
+  ownership marker" and are left alone. To reclaim one, drop the database by
+  hand and let the next `--own-db` run rebuild it: only the `db_bootstrap`
+  path writes `.dbowned`, and it runs only when the database is missing.
+  `wt reset` alone will not do it — it clears both markers, but the next
+  run then finds the database still there via `db_check` and re-adopts it,
+  which is case (b).
   **(b)** a database re-adopted after `wt reset`: `db_check` (which the rails
   templates configure) only ever writes `.dbready`, so the database that
   `db_check` finds on the next run is never re-marked as owned.
diff --git a/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md b/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md
index 023a0c7..a18f5e3 100644
--- a/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md
+++ b/docs/superpowers/specs/2026-08-29-worktree-lifecycle-design.md
@@ -1,9 +1,10 @@
 # Worktree lifecycle commands for `wt`
 
-**Status:** implemented in worktree-kit 0.2.0. Three places where the
+**Status:** implemented in worktree-kit 0.2.0. Four places where the
 implementation deliberately diverged are marked inline below as RESOLVED
-DEVIATION (§6.3 hyphen folding, §10.1 step 5 ownership marker, §10.2 merge
-teardown); this document is otherwise the binding design.
+DEVIATION (§6.3 hyphen folding, §10.1 step 5 ownership marker, §10.1 step 7
+marker cleanup, §10.2 merge teardown); this document is otherwise the
+binding design.
 **Date:** 2026-08-29
 **Base commit:** `fbdf060` (worktree-kit 0.1.8)
 
@@ -282,7 +283,18 @@ Order, each step skipped with a note when it does not apply:
    > and are left in place with a notice; and a database re-adopted via
    > `db_check` after a `wt reset` is likewise never dropped.
 6. Flush the Redis slot `{n}`.
-7. Remove `wt-state/<slug>.pid`, `.port`, `.dbready`, and `logs/<slug>.log`.
+7. Remove `wt-state/<slug>.pid`, `.port`, `.dbready`, `.dbowned`, and
+   `logs/<slug>.log`.
+
+   > **RESOLVED DEVIATION (implementation, 2026-08-29).** This step
+   > originally listed four files; the implementation removes `.dbowned`
+   > too, which did not exist when the step was written (see step 5). It
+   > must: leaving an ownership marker behind for a slug whose database has
+   > just been dropped would hand that claim to whatever database next
+   > occupied the name, and `wt rm`/`wt merge` would then drop a database
+   > the kit never created. `wt reset` clears both markers for the same
+   > reason.
+
 8. `git worktree remove <path>`, then `git branch -d <branch>` unless
    `--keep-branch`. `-d`, not `-D`: an unmerged branch refuses removal.
    `--force` upgrades to `-D`.