From eb29b0b8340dded40f67ae1fd66d77308198cc9e Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 22 Jun 2026 15:33:10 -0700
Subject: [PATCH 1/5] feat(pool): add durable worktree lease (get --lease)

Add a persistent, process-independent worktree reservation so a caller can
permanently hold a pooled worktree as a home without keeping a live process
inside it. This replaces the fragile process-based hold that consumers like
firstmate's persistent secondmate homes relied on.

- New WorktreeEntry.Leased/LeaseHolder/LeasedAt persistent state, all
  omitempty so pre-lease state files keep today's behavior.
- `treehouse get --lease` acquires without a subshell, marks the worktree
  leased, and prints only its absolute path to stdout (all banners and hook
  output go to stderr), so `path=$(treehouse get --lease)` is clean in
  scripts. `--lease-holder` / $TREEHOUSE_LEASE_HOLDER records the holder.
- Leased worktrees are skipped by get and prune regardless of running
  processes, require --force to destroy, and healState never clears them.
- `treehouse return <path>` clears the lease and returns the worktree,
  keeping its existing lingering-process termination behavior.
- `treehouse status` shows a distinct `leased` state with the holder.
- Concurrency is guarded by the existing WithStateLock (flock); both Acquire
  and AcquireLease delegate to a shared acquire() core.

Tests cover: lease prints only the path to stdout with info on stderr; a
leased worktree is skipped by get and prune with no process inside; return
releases it; status shows the leased state; concurrent acquires never
double-lease. README and AGENTS.md document the flag and the lease concept.
---
 AGENTS.md                  |   4 +-
 README.md                  |  31 ++++-
 cmd/e2e_test.go            | 141 ++++++++++++++++++++
 cmd/get.go                 |  42 +++++-
 cmd/status.go              |   9 +-
 internal/pool/pool.go      |  81 +++++++++++-
 internal/pool/pool_test.go | 265 +++++++++++++++++++++++++++++++++++++
 internal/pool/prune.go     |   2 +-
 internal/pool/state.go     |  10 ++
 9 files changed, 571 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ff564fe..b9eebb6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,7 +7,7 @@ Treehouse is a Go CLI tool that manages a pool of git worktrees for parallel AI
 ## Project Structure
 
 - `main.go` - entry point, calls `cmd.Execute()`
-- `cmd/` - CLI commands (cobra): `get`, `return`, `status`, `prune`, `destroy`
+- `cmd/` - CLI commands (cobra): `get` (incl. `get --lease`), `return`, `status`, `prune`, `destroy`
 - `internal/config/` - config file loading (`treehouse.toml`)
 - `internal/hooks/` - user-configured lifecycle hook command execution
 - `internal/pool/` - pool manager (acquire, release, list, destroy, prune) + state file
@@ -37,6 +37,8 @@ make test
 - No daemon - all operations are inline CLI commands
 - Detached HEAD worktrees reset to whichever of local or origin default branch is further ahead (prefers origin on divergence)
 - In-use detection uses process scanning plus short-lived persisted owner reservations for lifecycle operations
+- Durable leases are a separate, process-independent reservation: `WorktreeEntry.Leased`/`LeaseHolder`/`LeasedAt` persist in the state file (all `omitempty`, so pre-lease state files keep today's behavior). A lease is NOT derived from live processes, so it survives with zero processes inside the worktree and `healState` never clears it (it only clears dead owner reservations). Leased worktrees are skipped by `Acquire` and `prune`, treated as in-use by `worktreeInUse` (so non-force `destroy` rejects them), surfaced by `status` as `StatusLeased`, and cleared by `Release` (`return`)
+- `get --lease` (see `getLeaseRunE`) is the non-interactive acquire: it implies the durable lease, opens no subshell, routes post-create hook stdout and all banners to stderr, and prints ONLY the worktree path to stdout so `path=$(treehouse get --lease)` is clean. `--lease-holder`/`$TREEHOUSE_LEASE_HOLDER` set the recorded holder. `pool.AcquireLease` is the entry point; both it and `Acquire` delegate to the shared `acquire(..., acquireOptions)` core, and `markAcquired` stamps either a lease or an owner reservation. Concurrency safety comes from the existing `WithStateLock` (flock) around all pool mutation
 - Dirty checks include untracked files even when repository config hides them from normal `git status` output
 - Prune deletes only idle managed worktrees that are clean and whose HEAD is merged into the default branch; dry run is the default
 - Prune reports unsafe idle worktrees in grouped, stable categories and keeps raw git diagnostics for verbose output instead of default output
diff --git a/README.md b/README.md
index 74c2927..836c512 100644
--- a/README.md
+++ b/README.md
@@ -132,6 +132,7 @@ The default treehouse root is `~/.treehouse/`.
 - **Detached HEAD** — worktrees use detached HEAD mode, reset to whichever of the local or remote default branch is further ahead, avoiding branch name conflicts entirely.
 - **No daemon** — all operations are inline CLI commands. No background processes, no state to get corrupted.
 - **In-use detection** — treehouse scans running processes and short-lived owner reservations to determine which worktrees are in-use. Reservations are persisted only while `get`, `destroy`, and `prune` lifecycle work is running.
+- **Durable leases** — `treehouse get --lease` reserves a worktree as a persistent home without keeping a process inside it. The lease is recorded in treehouse's own state, so the worktree is never handed out by a later `get` and never removed by `prune` until you release it with `treehouse return`. Unlike process-based in-use detection, a lease survives with zero processes running inside the worktree.
 - **Dirty detection** - treehouse treats tracked changes and untracked files as dirty, even when repository config hides untracked files from normal `git status` output.
 - **Safe pruning** - By default, `treehouse prune` removes only idle managed worktrees whose HEAD is already merged into the default branch and whose working tree is clean.
   `treehouse prune --all` applies the same safety checks across every managed pool under the user-level treehouse root.
@@ -144,8 +145,9 @@ The default treehouse root is `~/.treehouse/`.
 | -------------------------- | ---------------------------------------------------- |
 | `treehouse`                | Get a worktree and open a subshell (alias for `get`) |
 | `treehouse get`            | Acquire a worktree from the pool                     |
-| `treehouse status`         | Show pool status (highlights your current worktree)  |
-| `treehouse return [path]`  | Terminate lingering worktree processes and return it to the pool |
+| `treehouse get --lease`    | Durably lease a worktree without a subshell; print its path |
+| `treehouse status`         | Show pool status (highlights leased and current worktrees) |
+| `treehouse return [path]`  | Release any lease, terminate lingering worktree processes, and return it to the pool |
 | `treehouse prune`          | Dry-run removal of stale idle worktrees in the current repo pool |
 | `treehouse prune --all`    | Dry-run removal of stale idle worktrees across every managed pool |
 | `treehouse destroy [path]` | Remove a worktree from the pool                      |
@@ -156,6 +158,8 @@ The default treehouse root is `~/.treehouse/`.
 
 | Command   | Flag      | Description                       |
 | --------- | --------- | --------------------------------- |
+| `get`     | `--lease` | Durably lease the worktree without opening a subshell; print only its path to stdout |
+| `get`     | `--lease-holder` | Optional label recorded as the lease holder (defaults to `$TREEHOUSE_LEASE_HOLDER`) |
 | `return`  | `--force` | Clean, reset, and return without prompting |
 | `prune`   | `--yes`   | Delete listed prune candidates instead of doing a dry run |
 | `prune`   | `--all`   | Sweep every managed pool under the user-level treehouse root |
@@ -165,6 +169,27 @@ The default treehouse root is `~/.treehouse/`.
 | `destroy` | `--force` | Force destroy even if in-use      |
 | `destroy` | `--all`   | Destroy all worktrees in the pool |
 
+### Leasing a worktree (no subshell)
+
+`treehouse get` normally opens an interactive subshell whose lifetime is the hold: when the shell exits, the worktree returns to the pool.
+That is awkward for callers that need a worktree to persist as a permanent home with no long-lived process inside it.
+
+`treehouse get --lease` is the non-interactive, durable alternative:
+
+```sh
+path=$(treehouse get --lease)
+# $path is the leased worktree's absolute path; all banners went to stderr.
+```
+
+It acquires a worktree exactly like `get`, but instead of opening a subshell it marks the worktree **leased** in treehouse's persistent state and prints only the worktree's absolute path to stdout (every human-facing message goes to stderr, so command substitution stays clean).
+
+A leased worktree is never handed out by a later `get` and never removed by `prune`, regardless of whether any process runs inside it, until the lease is explicitly released.
+It also requires `--force` to `destroy`.
+
+Pass `--lease-holder <label>` (or set `$TREEHOUSE_LEASE_HOLDER`) to record who holds the lease; `treehouse status` then shows it next to the `leased` state.
+
+Release a lease with `treehouse return <path>`, which clears the lease, terminates any lingering processes, resets the worktree, and returns it to the pool.
+
 ### Pruning stale worktrees and orphans
 
 `treehouse prune` is a dry run by default.
@@ -176,7 +201,7 @@ Pass `treehouse prune --all` or `treehouse prune --global` to inspect every mana
 Global prune reads the user-level config and hooks, derives each worktree's owning repository from git metadata, then fetches and checks merge safety against that repository.
 Without `--prune-orphans`, pass `treehouse prune --all --yes` to delete only the globally safe stale candidates.
 
-Prune ignores worktrees that are currently in use or reserved by another lifecycle operation.
+Prune ignores worktrees that are currently in use, leased, or reserved by another lifecycle operation.
 It skips idle worktrees that are unsafe to remove and prints the skip reason, such as uncommitted tracked or untracked changes, or a HEAD commit that is not merged into the default branch.
 Skip output is grouped by reason so large global sweeps stay scannable.
 When `origin` exists, prune fetches it and proves each HEAD against the current remote default branch tracking ref.
diff --git a/cmd/e2e_test.go b/cmd/e2e_test.go
index fa254fb..13f359c 100644
--- a/cmd/e2e_test.go
+++ b/cmd/e2e_test.go
@@ -434,6 +434,147 @@ func TestGetAndStatus(t *testing.T) {
 	}
 }
 
+func TestGetLeasePrintsOnlyPathToStdout(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	stdout, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease")
+	if code != 0 {
+		t.Fatalf("treehouse get --lease failed (code %d): %s", code, stderr)
+	}
+
+	// stdout must be exactly the worktree path on a single line, so scripts can
+	// do path=$(treehouse get --lease).
+	lines := strings.Split(strings.TrimRight(stdout, "\n"), "\n")
+	if len(lines) != 1 {
+		t.Fatalf("expected exactly one stdout line, got %d:\n%q", len(lines), stdout)
+	}
+	wtPath := lines[0]
+	if !filepath.IsAbs(wtPath) {
+		t.Fatalf("expected an absolute path on stdout, got %q", wtPath)
+	}
+	if _, err := os.Stat(filepath.Join(wtPath, "README.md")); err != nil {
+		t.Fatalf("expected leased worktree to contain repo content: %v", err)
+	}
+
+	// Human-facing banners go to stderr only.
+	if strings.Contains(stdout, "🌳") || strings.Contains(stdout, "Leased worktree") {
+		t.Fatalf("stdout must contain only the path, got:\n%q", stdout)
+	}
+	if !strings.Contains(stderr, "Leased worktree at") {
+		t.Fatalf("expected lease banner on stderr, got:\n%s", stderr)
+	}
+
+	// status reports the durable lease as a distinct state.
+	statusOut, statusErr, code := runTreehouse(t, repoDir, homeDir, nil, "status")
+	if code != 0 {
+		t.Fatalf("status failed (code %d): %s", code, statusErr)
+	}
+	if !strings.Contains(statusOut, "leased") {
+		t.Fatalf("expected status to show leased state, got:\n%s", statusOut)
+	}
+}
+
+func TestGetLeaseRecordsHolder(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	_, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease", "--lease-holder", "secondmate-home")
+	if code != 0 {
+		t.Fatalf("treehouse get --lease failed (code %d): %s", code, stderr)
+	}
+
+	statusOut, statusErr, code := runTreehouse(t, repoDir, homeDir, nil, "status")
+	if code != 0 {
+		t.Fatalf("status failed (code %d): %s", code, statusErr)
+	}
+	if !strings.Contains(statusOut, "leased") || !strings.Contains(statusOut, "secondmate-home") {
+		t.Fatalf("expected status to show lease holder, got:\n%s", statusOut)
+	}
+}
+
+func TestLeasedWorktreeSkippedByGetAndPrune(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease")
+	if code != 0 {
+		t.Fatalf("get --lease failed (code %d): %s", code, leaseErr)
+	}
+	leasedPath := strings.TrimSpace(leaseOut)
+	if leasedPath == "" {
+		t.Fatal("could not capture leased worktree path")
+	}
+
+	// A later interactive get must not hand out the leased worktree.
+	env := []string{"SHELL=" + exitShellBin}
+	_, getErr, code := runTreehouse(t, repoDir, homeDir, env, "get")
+	if code != 0 {
+		t.Fatalf("get failed (code %d): %s", code, getErr)
+	}
+	otherPath := extractWorktreePath(getErr, homeDir)
+	if otherPath == "" {
+		t.Fatal("could not extract second worktree path")
+	}
+	if otherPath == leasedPath {
+		t.Fatalf("get handed out the leased worktree %s", leasedPath)
+	}
+
+	// prune must never remove the leased worktree, even with no process inside.
+	pruneOut, pruneErr, code := runTreehouse(t, repoDir, homeDir, nil, "prune", "--yes")
+	if code != 0 {
+		t.Fatalf("prune --yes failed (code %d): %s", code, pruneErr)
+	}
+	prettyLeased := "~" + leasedPath[len(homeDir):]
+	if strings.Contains(pruneOut, prettyLeased) {
+		t.Fatalf("prune listed the leased worktree %s:\n%s", prettyLeased, pruneOut)
+	}
+	if _, err := os.Stat(leasedPath); err != nil {
+		t.Fatalf("prune removed leased worktree %s: %v", leasedPath, err)
+	}
+}
+
+func TestReturnReleasesLease(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease")
+	if code != 0 {
+		t.Fatalf("get --lease failed (code %d): %s", code, leaseErr)
+	}
+	leasedPath := strings.TrimSpace(leaseOut)
+	if leasedPath == "" {
+		t.Fatal("could not capture leased worktree path")
+	}
+
+	_, returnErr, code := runTreehouse(t, repoDir, homeDir, nil, "return", leasedPath)
+	if code != 0 {
+		t.Fatalf("return failed (code %d): %s", code, returnErr)
+	}
+	if !strings.Contains(returnErr, "Worktree returned to pool") {
+		t.Fatalf("expected return confirmation, got: %s", returnErr)
+	}
+
+	// Status no longer reports the worktree as leased.
+	statusOut, statusErr, code := runTreehouse(t, repoDir, homeDir, nil, "status")
+	if code != 0 {
+		t.Fatalf("status failed (code %d): %s", code, statusErr)
+	}
+	if strings.Contains(statusOut, "leased") {
+		t.Fatalf("expected lease to be released, got status:\n%s", statusOut)
+	}
+	if !strings.Contains(statusOut, "available") {
+		t.Fatalf("expected released worktree to be available, got status:\n%s", statusOut)
+	}
+
+	// The released worktree is reusable by a normal get.
+	env := []string{"SHELL=" + exitShellBin}
+	_, getErr, code := runTreehouse(t, repoDir, homeDir, env, "get")
+	if code != 0 {
+		t.Fatalf("get after release failed (code %d): %s", code, getErr)
+	}
+	reusedPath := extractWorktreePath(getErr, homeDir)
+	if reusedPath != leasedPath {
+		t.Fatalf("expected released worktree %s to be reused, got %s", leasedPath, reusedPath)
+	}
+}
+
 func TestGetReusesWorktree(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 	env := []string{"SHELL=" + exitShellBin}
diff --git a/cmd/get.go b/cmd/get.go
index 98718d6..c4f850c 100644
--- a/cmd/get.go
+++ b/cmd/get.go
@@ -17,13 +17,27 @@ import (
 	"github.com/kunchenguid/treehouse/internal/ui"
 )
 
+var (
+	getLease       bool
+	getLeaseHolder string
+)
+
 var getCmd = &cobra.Command{
 	Use:   "get",
 	Short: "Acquire a worktree from the pool and open a subshell",
-	RunE:  getRunE,
+	Long: `Acquire a worktree from the pool and open a subshell in it.
+
+Pass --lease for a non-interactive, durable acquire: treehouse reserves the
+worktree, marks it leased in its persistent state, and prints only the worktree's
+absolute path to stdout (all banners go to stderr). A leased worktree is never
+handed out by a later get and never removed by prune, even with no process
+running inside it, until you release it with 'treehouse return <path>'.`,
+	RunE: getRunE,
 }
 
 func init() {
+	getCmd.Flags().BoolVar(&getLease, "lease", false, "Durably lease a worktree without opening a subshell; print only its path to stdout")
+	getCmd.Flags().StringVar(&getLeaseHolder, "lease-holder", "", "Optional label recorded as the lease holder (defaults to $TREEHOUSE_LEASE_HOLDER)")
 	rootCmd.AddCommand(getCmd)
 }
 
@@ -47,6 +61,10 @@ func getRunE(cmd *cobra.Command, args []string) error {
 		fmt.Fprintf(os.Stderr, "warning: failed to update .gitignore: %v\n", err)
 	}
 
+	if getLease {
+		return getLeaseRunE(repoRoot, poolDir, cfg)
+	}
+
 	wtPath, err := pool.Acquire(repoRoot, poolDir, cfg.MaxTrees, cfg.Hooks.PostCreate)
 	if err != nil {
 		return err
@@ -86,6 +104,28 @@ func getRunE(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// getLeaseRunE performs a non-interactive, durable acquire. It reserves a
+// worktree, marks it leased in persistent state, prints only the worktree path
+// to stdout, and routes every human-facing message to stderr so that
+// `path=$(treehouse get --lease)` works cleanly in scripts.
+func getLeaseRunE(repoRoot, poolDir string, cfg config.Config) error {
+	holder := getLeaseHolder
+	if holder == "" {
+		holder = os.Getenv("TREEHOUSE_LEASE_HOLDER")
+	}
+
+	wtPath, err := pool.AcquireLease(repoRoot, poolDir, cfg.MaxTrees, cfg.Hooks.PostCreate, holder)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "🌳 Leased worktree at %s. Run 'treehouse return %s' to release it.\n",
+		ui.PrettyPath(wtPath), ui.PrettyPath(wtPath))
+	// The bare path is the only thing on stdout, so callers can capture it.
+	fmt.Fprintln(os.Stdout, wtPath)
+	return nil
+}
+
 // killLingeringProcesses terminates any process whose cwd is within the given
 // worktree. Called before returning a worktree to the pool so detached tools
 // (e.g. opencode servers that ignore SIGHUP) don't keep holding the worktree.
diff --git a/cmd/status.go b/cmd/status.go
index dd88e21..d38f876 100644
--- a/cmd/status.go
+++ b/cmd/status.go
@@ -47,6 +47,7 @@ var statusCmd = &cobra.Command{
 		red := color.New(color.FgRed).SprintFunc()
 		yellow := color.New(color.FgYellow).SprintFunc()
 		cyan := color.New(color.FgCyan, color.Bold).SprintFunc()
+		magenta := color.New(color.FgMagenta).SprintFunc()
 
 		// statusWidth must be >= longest status string ("you're here" = 11)
 		const statusWidth = 11
@@ -60,13 +61,19 @@ var statusCmd = &cobra.Command{
 				status = red(wt.Status)
 			case pool.StatusDirty:
 				status = yellow(wt.Status)
+			case pool.StatusLeased:
+				status = magenta(wt.Status)
 			case pool.StatusHere:
 				status = cyan(wt.Status)
 			}
 
 			// "%-4s  %-11s  " = 4 + 2 + 11 + 2 = 19 chars before path
 			statusPad := strings.Repeat(" ", statusWidth-len(wt.Status))
-			fmt.Fprintf(os.Stdout, "%-4s  %s%s  %s\n", wt.Name, status, statusPad, ui.PrettyPath(wt.Path))
+			line := fmt.Sprintf("%-4s  %s%s  %s", wt.Name, status, statusPad, ui.PrettyPath(wt.Path))
+			if wt.Status == pool.StatusLeased && wt.LeaseHolder != "" {
+				line += fmt.Sprintf("  (held by %s)", wt.LeaseHolder)
+			}
+			fmt.Fprintln(os.Stdout, line)
 
 			if len(wt.Processes) > 0 {
 				var procStrs []string
diff --git a/internal/pool/pool.go b/internal/pool/pool.go
index 02db948..0069131 100644
--- a/internal/pool/pool.go
+++ b/internal/pool/pool.go
@@ -2,6 +2,7 @@ package pool
 
 import (
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strconv"
@@ -16,6 +17,7 @@ const (
 	StatusAvailable = "available"
 	StatusDirty     = "dirty"
 	StatusInUse     = "in-use"
+	StatusLeased    = "leased"
 	StatusHere      = "you're here"
 )
 
@@ -24,9 +26,48 @@ type WorktreeStatus struct {
 	Path      string
 	Status    string
 	Processes []process.ProcessInfo
+	// LeaseHolder is the recorded holder for a leased worktree, if any.
+	LeaseHolder string
 }
 
+// acquireOptions controls how Acquire reserves the worktree it hands out.
+type acquireOptions struct {
+	// lease records a durable, process-independent reservation instead of the
+	// default short-lived owner reservation.
+	lease bool
+	// leaseHolder is an optional label stored with a lease.
+	leaseHolder string
+	// hookStdout/hookStderr receive post-create hook output. Lease mode routes
+	// hook stdout to stderr so the worktree path stays the only stdout line.
+	hookStdout io.Writer
+	hookStderr io.Writer
+}
+
+// Acquire reserves a clean worktree from the pool with a short-lived owner
+// reservation (the calling process). It is the backing call for the interactive
+// `treehouse get` subshell.
 func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (string, error) {
+	return acquire(repoRoot, poolDir, poolSize, postCreate, acquireOptions{
+		hookStdout: os.Stdout,
+		hookStderr: os.Stderr,
+	})
+}
+
+// AcquireLease reserves a clean worktree and marks it durably LEASED so the
+// reservation survives with zero processes running inside it. The lease persists
+// until it is released by Release. holder is an optional label recorded with the
+// lease for diagnostics. Post-create hook stdout is routed to stderr so callers
+// can capture the returned path as the sole stdout line.
+func AcquireLease(repoRoot, poolDir string, poolSize int, postCreate []string, holder string) (string, error) {
+	return acquire(repoRoot, poolDir, poolSize, postCreate, acquireOptions{
+		lease:       true,
+		leaseHolder: holder,
+		hookStdout:  os.Stderr,
+		hookStderr:  os.Stderr,
+	})
+}
+
+func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts acquireOptions) (string, error) {
 	branch, err := git.GetDefaultBranch(repoRoot)
 	if err != nil {
 		return "", err
@@ -50,9 +91,9 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 
 		state = healState(state)
 
-		// Try to find an available worktree (clean and not in-use)
+		// Try to find an available worktree (clean, not in-use, not leased)
 		for i, wt := range state.Worktrees {
-			if wt.Destroying || ownerAlive(wt) {
+			if wt.Destroying || wt.Leased || ownerAlive(wt) {
 				continue
 			}
 			inUse, _ := process.IsWorktreeInUse(wt.Path)
@@ -67,7 +108,7 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 			if err := git.ResetWorktree(wt.Path, branch); err != nil {
 				continue
 			}
-			if err := reserveOwner(&state.Worktrees[i]); err != nil {
+			if err := markAcquired(&state.Worktrees[i], opts); err != nil {
 				return err
 			}
 			acquired = wt.Path
@@ -100,7 +141,7 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 			Path:      wtPath,
 			CreatedAt: time.Now(),
 		}
-		if err := reserveOwner(&entry); err != nil {
+		if err := markAcquired(&entry, opts); err != nil {
 			return err
 		}
 		state.Worktrees = append(state.Worktrees, entry)
@@ -116,12 +157,27 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 		return "", err
 	}
 	if runPostCreate {
-		hooks.Run(postCreate, acquired, os.Stdout, os.Stderr)
+		hooks.Run(postCreate, acquired, opts.hookStdout, opts.hookStderr)
 	}
 
 	return acquired, nil
 }
 
+// markAcquired stamps an acquired worktree entry: a durable lease in lease mode,
+// otherwise the default short-lived owner reservation.
+func markAcquired(wt *WorktreeEntry, opts acquireOptions) error {
+	if opts.lease {
+		wt.Leased = true
+		wt.LeaseHolder = opts.leaseHolder
+		wt.LeasedAt = time.Now()
+		// A lease is process-independent, so it carries no owner reservation.
+		wt.OwnerPID = 0
+		wt.OwnerStartedAt = 0
+		return nil
+	}
+	return reserveOwner(wt)
+}
+
 func Release(poolDir, worktreePath string) error {
 	repoRoot, err := git.FindRepoRootFrom(worktreePath)
 	if err != nil {
@@ -160,6 +216,7 @@ func Release(poolDir, worktreePath string) error {
 				}
 				state.Worktrees[i].OwnerPID = 0
 				state.Worktrees[i].OwnerStartedAt = 0
+				clearLease(&state.Worktrees[i])
 				break
 			}
 		}
@@ -196,7 +253,10 @@ func List(poolDir string) ([]WorktreeStatus, error) {
 			procs, _ := process.FindProcessesInWorktree(wt.Path)
 			ws.Processes = procs
 
-			if ownerAlive(wt) {
+			if wt.Leased {
+				ws.Status = StatusLeased
+				ws.LeaseHolder = wt.LeaseHolder
+			} else if ownerAlive(wt) {
 				ws.Status = StatusInUse
 			} else if len(procs) > 0 {
 				ws.Status = StatusInUse
@@ -398,12 +458,19 @@ func reserveOwner(wt *WorktreeEntry) error {
 }
 
 func worktreeInUse(wt WorktreeEntry) (bool, error) {
-	if ownerAlive(wt) {
+	if wt.Leased || ownerAlive(wt) {
 		return true, nil
 	}
 	return process.IsWorktreeInUse(wt.Path)
 }
 
+// clearLease removes any durable lease from a worktree entry.
+func clearLease(wt *WorktreeEntry) {
+	wt.Leased = false
+	wt.LeaseHolder = ""
+	wt.LeasedAt = time.Time{}
+}
+
 func sameDestroyReservation(current, reserved WorktreeEntry) bool {
 	return current.Path == reserved.Path &&
 		current.Destroying &&
diff --git a/internal/pool/pool_test.go b/internal/pool/pool_test.go
index fb72112..c8a9f7e 100644
--- a/internal/pool/pool_test.go
+++ b/internal/pool/pool_test.go
@@ -5,6 +5,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 )
@@ -1152,6 +1153,270 @@ func TestRelease_RejectsDestroyingWorktree(t *testing.T) {
 	}
 }
 
+func TestAcquireLease_MarksWorktreeLeasedInState(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "secondmate-home")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+	if wtPath == "" {
+		t.Fatal("AcquireLease returned empty path")
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	if len(state.Worktrees) != 1 {
+		t.Fatalf("expected one worktree, got %#v", state.Worktrees)
+	}
+	wt := state.Worktrees[0]
+	if !wt.Leased || wt.LeaseHolder != "secondmate-home" {
+		t.Fatalf("expected durable lease with holder, got %#v", wt)
+	}
+	// A lease must not depend on a live process: no owner reservation is kept.
+	if wt.OwnerPID != 0 || wt.OwnerStartedAt != 0 {
+		t.Fatalf("expected no owner reservation on a lease, got %#v", wt)
+	}
+	if wt.LeasedAt.IsZero() {
+		t.Fatalf("expected LeasedAt to be set, got %#v", wt)
+	}
+}
+
+func TestAcquireLease_NotHandedOutBySubsequentAcquire(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	leased, err := AcquireLease(repoDir, poolDir, 4, nil, "")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	// A plain acquire must never reuse the leased worktree even though no
+	// process runs inside it.
+	next, err := Acquire(repoDir, poolDir, 4, nil)
+	if err != nil {
+		t.Fatalf("Acquire failed: %v", err)
+	}
+	if next == leased {
+		t.Fatalf("acquire reused leased worktree %s", leased)
+	}
+}
+
+func TestAcquireLease_ExhaustsPoolWhenAllLeased(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	if _, err := AcquireLease(repoDir, poolDir, 1, nil, ""); err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	// With pool size 1 and the only worktree leased, a second acquire cannot
+	// find or create one.
+	if _, err := Acquire(repoDir, poolDir, 1, nil); err == nil {
+		t.Fatal("expected acquire to fail when the only worktree is leased")
+	}
+}
+
+func TestPrune_NeverRemovesLeasedWorktreeWithoutProcess(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "home")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	result, err := Prune(repoDir, poolDir, false, nil)
+	if err != nil {
+		t.Fatalf("Prune failed: %v", err)
+	}
+	if len(result.Candidates) != 0 || len(result.Pruned) != 0 || len(result.Skipped) != 0 {
+		t.Fatalf("expected leased worktree to be ignored by prune, got %#v", result)
+	}
+	if _, err := os.Stat(wtPath); err != nil {
+		t.Fatalf("prune removed leased worktree %s: %v", wtPath, err)
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	if len(state.Worktrees) != 1 || !state.Worktrees[0].Leased {
+		t.Fatalf("expected lease to persist after prune, got %#v", state.Worktrees)
+	}
+}
+
+func TestRelease_ClearsLease(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "home")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+	if err := Release(poolDir, wtPath); err != nil {
+		t.Fatalf("Release failed: %v", err)
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	if len(state.Worktrees) != 1 {
+		t.Fatalf("expected one worktree, got %#v", state.Worktrees)
+	}
+	if state.Worktrees[0].Leased || state.Worktrees[0].LeaseHolder != "" || !state.Worktrees[0].LeasedAt.IsZero() {
+		t.Fatalf("expected lease to be cleared, got %#v", state.Worktrees[0])
+	}
+
+	// After release the worktree becomes available for reuse.
+	reused, err := Acquire(repoDir, poolDir, 4, nil)
+	if err != nil {
+		t.Fatalf("Acquire after release failed: %v", err)
+	}
+	if reused != wtPath {
+		t.Fatalf("expected released worktree %s to be reused, got %s", wtPath, reused)
+	}
+}
+
+func TestList_ShowsLeasedState(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "secondmate-7")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	statuses, err := List(poolDir)
+	if err != nil {
+		t.Fatalf("List failed: %v", err)
+	}
+	if len(statuses) != 1 || statuses[0].Path != wtPath {
+		t.Fatalf("expected one leased worktree, got %#v", statuses)
+	}
+	if statuses[0].Status != StatusLeased {
+		t.Fatalf("expected leased status, got %q", statuses[0].Status)
+	}
+	if statuses[0].LeaseHolder != "secondmate-7" {
+		t.Fatalf("expected lease holder to be reported, got %q", statuses[0].LeaseHolder)
+	}
+}
+
+func TestHealState_PreservesLease(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "home")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	// Simulate a stale owner pid alongside the lease; healing must clear the
+	// dead owner reservation but keep the durable lease intact.
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	state.Worktrees[0].OwnerPID = 999999
+	state.Worktrees[0].OwnerStartedAt = 1
+	if err := WriteState(poolDir, state); err != nil {
+		t.Fatalf("WriteState failed: %v", err)
+	}
+
+	statuses, err := List(poolDir)
+	if err != nil {
+		t.Fatalf("List failed: %v", err)
+	}
+	if len(statuses) != 1 || statuses[0].Status != StatusLeased {
+		t.Fatalf("expected lease to survive healing, got %#v", statuses)
+	}
+
+	state, err = ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	if !state.Worktrees[0].Leased {
+		t.Fatalf("expected lease to persist after healing, got %#v", state.Worktrees[0])
+	}
+	if state.Worktrees[0].OwnerPID != 0 {
+		t.Fatalf("expected stale owner reservation to be cleared, got %#v", state.Worktrees[0])
+	}
+	_ = wtPath
+}
+
+func TestDestroy_NonForceRejectsLeasedWorktree(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+
+	wtPath, err := AcquireLease(repoDir, poolDir, 4, nil, "home")
+	if err != nil {
+		t.Fatalf("AcquireLease failed: %v", err)
+	}
+
+	err = Destroy(repoDir, poolDir, wtPath, false, nil)
+	if err == nil {
+		t.Fatal("expected non-force Destroy to reject leased worktree")
+	}
+	if !strings.Contains(err.Error(), "is in use") {
+		t.Fatalf("expected in-use error, got %v", err)
+	}
+	if _, err := os.Stat(wtPath); err != nil {
+		t.Fatalf("expected leased worktree to remain on disk: %v", err)
+	}
+
+	// --force overrides the lease.
+	if err := Destroy(repoDir, poolDir, wtPath, true, nil); err != nil {
+		t.Fatalf("force Destroy failed: %v", err)
+	}
+	if _, err := os.Stat(wtPath); !os.IsNotExist(err) {
+		t.Fatalf("expected leased worktree to be removed after force destroy, stat err: %v", err)
+	}
+}
+
+func TestAcquireLease_ConcurrentAcquiresNeverDoubleLease(t *testing.T) {
+	// A local repo has no origin, so AcquireLease skips git fetch and avoids
+	// concurrent-fetch races; the state lock still serializes pool mutation.
+	repoDir, poolDir := setupLocalRepo(t)
+
+	const n = 6
+	paths := make([]string, n)
+	errs := make([]error, n)
+	var wg sync.WaitGroup
+	wg.Add(n)
+	for i := 0; i < n; i++ {
+		go func(i int) {
+			defer wg.Done()
+			paths[i], errs[i] = AcquireLease(repoDir, poolDir, n, nil, "")
+		}(i)
+	}
+	wg.Wait()
+
+	seen := make(map[string]int)
+	for i := 0; i < n; i++ {
+		if errs[i] != nil {
+			t.Fatalf("AcquireLease %d failed: %v", i, errs[i])
+		}
+		if paths[i] == "" {
+			t.Fatalf("AcquireLease %d returned empty path", i)
+		}
+		seen[paths[i]]++
+	}
+	for path, count := range seen {
+		if count != 1 {
+			t.Fatalf("worktree %s was leased %d times (double-lease)", path, count)
+		}
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState failed: %v", err)
+	}
+	if len(state.Worktrees) != n {
+		t.Fatalf("expected %d distinct leased worktrees, got %d: %#v", n, len(state.Worktrees), state.Worktrees)
+	}
+	for _, wt := range state.Worktrees {
+		if !wt.Leased {
+			t.Fatalf("expected every concurrently acquired worktree to be leased, got %#v", wt)
+		}
+	}
+}
+
 func hasSkippedReason(skipped []PruneSkipped, path, reason string) bool {
 	for _, wt := range skipped {
 		if wt.Path == path && strings.Contains(wt.Reason, reason) {
diff --git a/internal/pool/prune.go b/internal/pool/prune.go
index ea5b93c..36b1783 100644
--- a/internal/pool/prune.go
+++ b/internal/pool/prune.go
@@ -547,7 +547,7 @@ func analyzePruneCandidate(resolveContext pruneContextResolver, wt WorktreeEntry
 	worktree := PruneWorktree{Name: wt.Name, Path: wt.Path}
 	skipped := PruneSkipped{Name: wt.Name, Path: wt.Path}
 
-	if wt.Destroying || ownerAlive(wt) {
+	if wt.Destroying || wt.Leased || ownerAlive(wt) {
 		return worktree, skipped, false, pruneContext{}, nil
 	}
 	inUse, err := process.IsWorktreeInUse(wt.Path)
diff --git a/internal/pool/state.go b/internal/pool/state.go
index aded62b..8378174 100644
--- a/internal/pool/state.go
+++ b/internal/pool/state.go
@@ -14,6 +14,16 @@ type WorktreeEntry struct {
 	Destroying     bool      `json:"destroying,omitempty"`
 	OwnerPID       int32     `json:"owner_pid,omitempty"`
 	OwnerStartedAt int64     `json:"owner_started_at,omitempty"`
+	// Leased marks a worktree as durably reserved by an external consumer that
+	// keeps no live process inside it. Unlike OwnerPID/OwnerStartedAt (which are
+	// process-derived and self-heal when the owner dies), a lease persists until
+	// it is explicitly released by `treehouse return`. A missing field decodes to
+	// false, so pre-lease state files keep today's behavior.
+	Leased bool `json:"leased,omitempty"`
+	// LeaseHolder is an optional human-readable label for who holds the lease.
+	LeaseHolder string `json:"lease_holder,omitempty"`
+	// LeasedAt records when the lease was taken.
+	LeasedAt time.Time `json:"leased_at,omitempty"`
 }
 
 type State struct {

From 3c9c32f08203853915c33492a8ca626869ead9fa Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 22 Jun 2026 15:40:30 -0700
Subject: [PATCH 2/5] no-mistakes(review): Omit cleared lease timestamps from
 state

---
 internal/pool/pool_test.go | 10 ++++++++++
 internal/pool/state.go     |  2 +-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/internal/pool/pool_test.go b/internal/pool/pool_test.go
index c8a9f7e..7a70860 100644
--- a/internal/pool/pool_test.go
+++ b/internal/pool/pool_test.go
@@ -1266,6 +1266,16 @@ func TestRelease_ClearsLease(t *testing.T) {
 	if state.Worktrees[0].Leased || state.Worktrees[0].LeaseHolder != "" || !state.Worktrees[0].LeasedAt.IsZero() {
 		t.Fatalf("expected lease to be cleared, got %#v", state.Worktrees[0])
 	}
+	data, err := os.ReadFile(stateFilePath(poolDir))
+	if err != nil {
+		t.Fatalf("reading state file failed: %v", err)
+	}
+	stateJSON := string(data)
+	for _, field := range []string{`"leased"`, `"lease_holder"`, `"leased_at"`} {
+		if strings.Contains(stateJSON, field) {
+			t.Fatalf("expected cleared lease field %s to be omitted from state file:\n%s", field, stateJSON)
+		}
+	}
 
 	// After release the worktree becomes available for reuse.
 	reused, err := Acquire(repoDir, poolDir, 4, nil)
diff --git a/internal/pool/state.go b/internal/pool/state.go
index 8378174..86fdddd 100644
--- a/internal/pool/state.go
+++ b/internal/pool/state.go
@@ -23,7 +23,7 @@ type WorktreeEntry struct {
 	// LeaseHolder is an optional human-readable label for who holds the lease.
 	LeaseHolder string `json:"lease_holder,omitempty"`
 	// LeasedAt records when the lease was taken.
-	LeasedAt time.Time `json:"leased_at,omitempty"`
+	LeasedAt time.Time `json:"leased_at,omitempty,omitzero"`
 }
 
 type State struct {

From d1766467eca59077b5b62bc4374dfebeab635357 Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 22 Jun 2026 15:49:23 -0700
Subject: [PATCH 3/5] no-mistakes(review): Fix return-by-path lease release

---
 cmd/e2e_test.go   | 33 +++++++++++++++++++++++++++++++++
 cmd/return_cmd.go |  7 ++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/cmd/e2e_test.go b/cmd/e2e_test.go
index 13f359c..b38e4c2 100644
--- a/cmd/e2e_test.go
+++ b/cmd/e2e_test.go
@@ -575,6 +575,39 @@ func TestReturnReleasesLease(t *testing.T) {
 	}
 }
 
+func TestReturnExplicitPathFromOutsideRepoReleasesLease(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease")
+	if code != 0 {
+		t.Fatalf("get --lease failed (code %d): %s", code, leaseErr)
+	}
+	leasedPath := strings.TrimSpace(leaseOut)
+	if leasedPath == "" {
+		t.Fatal("could not capture leased worktree path")
+	}
+
+	outsideDir := t.TempDir()
+	_, returnErr, code := runTreehouseFromDir(t, repoDir, outsideDir, homeDir, nil, "return", leasedPath)
+	if code != 0 {
+		t.Fatalf("return from outside repo failed (code %d): %s", code, returnErr)
+	}
+	if !strings.Contains(returnErr, "Worktree returned to pool") {
+		t.Fatalf("expected return confirmation, got: %s", returnErr)
+	}
+
+	statusOut, statusErr, code := runTreehouse(t, repoDir, homeDir, nil, "status")
+	if code != 0 {
+		t.Fatalf("status failed (code %d): %s", code, statusErr)
+	}
+	if strings.Contains(statusOut, "leased") || strings.Contains(statusOut, "in-use") {
+		t.Fatalf("expected status to show lease released, got:\n%s", statusOut)
+	}
+	if !strings.Contains(statusOut, "available") {
+		t.Fatalf("expected returned worktree to be available, got:\n%s", statusOut)
+	}
+}
+
 func TestGetReusesWorktree(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 	env := []string{"SHELL=" + exitShellBin}
diff --git a/cmd/return_cmd.go b/cmd/return_cmd.go
index 4b087e2..526bf53 100644
--- a/cmd/return_cmd.go
+++ b/cmd/return_cmd.go
@@ -24,7 +24,12 @@ var returnCmd = &cobra.Command{
 			return err
 		}
 
-		repoRoot, err := git.FindRepoRoot()
+		var repoRoot string
+		if len(args) > 0 {
+			repoRoot, err = git.FindMainRepoRootFrom(wtPath)
+		} else {
+			repoRoot, err = git.FindRepoRoot()
+		}
 		if err != nil {
 			return fmt.Errorf("not in a git repository: %w", err)
 		}

From a22297d2bda85e045324784bcc47504953d171aa Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 22 Jun 2026 16:01:40 -0700
Subject: [PATCH 4/5] no-mistakes(review): Fix return-by-path pool lookup

---
 cmd/e2e_test.go   | 42 ++++++++++++++++++++++++++++
 cmd/return_cmd.go | 70 +++++++++++++++++++++++++++++++++--------------
 2 files changed, 91 insertions(+), 21 deletions(-)

diff --git a/cmd/e2e_test.go b/cmd/e2e_test.go
index b38e4c2..a92d872 100644
--- a/cmd/e2e_test.go
+++ b/cmd/e2e_test.go
@@ -608,6 +608,48 @@ func TestReturnExplicitPathFromOutsideRepoReleasesLease(t *testing.T) {
 	}
 }
 
+func TestReturnExplicitPathFromLinkedWorktreePool(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	if err := os.WriteFile(filepath.Join(repoDir, "treehouse.toml"), []byte("root = \"../treehouse-pool\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	gitCmd(t, repoDir, "add", "treehouse.toml")
+	gitCmd(t, repoDir, "commit", "-m", "configure treehouse root")
+
+	linkedDir := filepath.Join(filepath.Dir(repoDir), "agent-home")
+	gitCmd(t, repoDir, "worktree", "add", "-b", "agent-home", linkedDir, "main")
+
+	leaseOut, leaseErr, code := runTreehouseFromDir(t, repoDir, linkedDir, homeDir, nil, "get", "--lease")
+	if code != 0 {
+		t.Fatalf("get --lease from linked worktree failed (code %d): %s", code, leaseErr)
+	}
+	leasedPath := strings.TrimSpace(leaseOut)
+	if leasedPath == "" {
+		t.Fatal("could not capture leased worktree path")
+	}
+
+	outsideDir := t.TempDir()
+	_, returnErr, code := runTreehouseFromDir(t, repoDir, outsideDir, homeDir, nil, "return", leasedPath)
+	if code != 0 {
+		t.Fatalf("return from outside repo failed (code %d): %s", code, returnErr)
+	}
+	if !strings.Contains(returnErr, "Worktree returned to pool") {
+		t.Fatalf("expected return confirmation, got: %s", returnErr)
+	}
+
+	statusOut, statusErr, code := runTreehouseFromDir(t, repoDir, linkedDir, homeDir, nil, "status")
+	if code != 0 {
+		t.Fatalf("status failed (code %d): %s", code, statusErr)
+	}
+	if strings.Contains(statusOut, "leased") || strings.Contains(statusOut, "in-use") {
+		t.Fatalf("expected status to show lease released, got:\n%s", statusOut)
+	}
+	if !strings.Contains(statusOut, "available") {
+		t.Fatalf("expected returned worktree to be available, got:\n%s", statusOut)
+	}
+}
+
 func TestGetReusesWorktree(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 	env := []string{"SHELL=" + exitShellBin}
diff --git a/cmd/return_cmd.go b/cmd/return_cmd.go
index 526bf53..4410310 100644
--- a/cmd/return_cmd.go
+++ b/cmd/return_cmd.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -14,6 +15,7 @@ import (
 )
 
 var returnForce bool
+var errReturnWorktreeUnmanaged = errors.New("return worktree unmanaged")
 
 var returnCmd = &cobra.Command{
 	Use:   "return [path]",
@@ -24,31 +26,14 @@ var returnCmd = &cobra.Command{
 			return err
 		}
 
-		var repoRoot string
-		if len(args) > 0 {
-			repoRoot, err = git.FindMainRepoRootFrom(wtPath)
-		} else {
-			repoRoot, err = git.FindRepoRoot()
-		}
-		if err != nil {
-			return fmt.Errorf("not in a git repository: %w", err)
-		}
-
-		cfg, err := config.Load(repoRoot)
-		if err != nil {
-			return fmt.Errorf("failed to load config: %w", err)
-		}
-
-		poolDir, err := config.ResolvePoolDir(repoRoot, cfg.Root)
+		poolDir, err := resolveReturnPoolDir(wtPath, len(args) > 0)
 		if err != nil {
+			if errors.Is(err, errReturnWorktreeUnmanaged) {
+				return fmt.Errorf("worktree %s is not managed by treehouse", wtPath)
+			}
 			return err
 		}
 
-		entry, err := pool.FindByPath(poolDir, wtPath)
-		if err != nil || entry == nil {
-			return fmt.Errorf("worktree %s is not managed by treehouse", wtPath)
-		}
-
 		if !returnForce {
 			dirty, _ := git.IsDirty(wtPath)
 			if dirty {
@@ -89,3 +74,46 @@ func resolveWorktreePath(args []string) (string, error) {
 	}
 	return os.Getwd()
 }
+
+func resolveReturnPoolDir(wtPath string, explicitPath bool) (string, error) {
+	pathPoolDir := filepath.Dir(filepath.Dir(wtPath))
+	entry, err := pool.FindByPath(pathPoolDir, wtPath)
+	if err != nil {
+		return "", err
+	}
+	if entry != nil {
+		return pathPoolDir, nil
+	}
+
+	var repoRoot string
+	if explicitPath {
+		repoRoot, err = git.FindMainRepoRootFrom(wtPath)
+	} else {
+		repoRoot, err = git.FindRepoRoot()
+	}
+	if err != nil {
+		if explicitPath {
+			return "", errReturnWorktreeUnmanaged
+		}
+		return "", fmt.Errorf("not in a git repository: %w", err)
+	}
+
+	cfg, err := config.Load(repoRoot)
+	if err != nil {
+		return "", fmt.Errorf("failed to load config: %w", err)
+	}
+
+	fallbackPoolDir, err := config.ResolvePoolDir(repoRoot, cfg.Root)
+	if err != nil {
+		return "", err
+	}
+
+	entry, err = pool.FindByPath(fallbackPoolDir, wtPath)
+	if err != nil {
+		return "", err
+	}
+	if entry == nil {
+		return "", errReturnWorktreeUnmanaged
+	}
+	return fallbackPoolDir, nil
+}

From d91100f948cd0569c729c9345fd61dba8dbf2007 Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 22 Jun 2026 16:16:28 -0700
Subject: [PATCH 5/5] no-mistakes(document): Sync lease docs

---
 .../fm/treehouse-lease-t4/lease-cli-e2e.txt   | 90 +++++++++++++++++++
 AGENTS.md                                     |  3 +-
 README.md                                     | 12 +--
 internal/pool/pool.go                         | 11 +++
 internal/pool/prune.go                        |  5 +-
 5 files changed, 113 insertions(+), 8 deletions(-)
 create mode 100644 .no-mistakes/evidence/fm/treehouse-lease-t4/lease-cli-e2e.txt

diff --git a/.no-mistakes/evidence/fm/treehouse-lease-t4/lease-cli-e2e.txt b/.no-mistakes/evidence/fm/treehouse-lease-t4/lease-cli-e2e.txt
new file mode 100644
index 0000000..7adb285
--- /dev/null
+++ b/.no-mistakes/evidence/fm/treehouse-lease-t4/lease-cli-e2e.txt
@@ -0,0 +1,90 @@
+Treehouse durable lease CLI E2E transcript
+source_commit=a22297d2bda85e045324784bcc47504953d171aa
+evidence_generated_at=2026-06-22T23:10:18Z
+
+$ go build -o <run-dir>/treehouse .
+build_exit=0
+
+Fixture repo created at /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/repo with isolated HOME /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/home and pool root /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root.
+
+$ path=$(treehouse get --lease --lease-holder secondmate-home)
+stdout:
+/Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo
+stderr:
+🌳 Setting up worktree...
+🌳 Leased worktree at /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo. Run 'treehouse return /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo' to release it.
+stdout_line_count=1
+stdout_is_absolute_path=yes
+stdout_contains_banner=no
+leased_path_exists=yes
+
+$ sed -n '1,120p' <treehouse-state.json after lease>
+{
+  "worktrees": [
+    {
+      "name": "1",
+      "path": "/Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo",
+      "created_at": "2026-06-22T16:10:18.892955-07:00",
+      "leased": true,
+      "lease_holder": "secondmate-home",
+      "leased_at": "2026-06-22T16:10:18.892955-07:00"
+    }
+  ]
+}
+owner_pid_present_after_lease=no
+
+$ treehouse status
+stdout:
+1     leased       /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo  (held by secondmate-home)
+stderr:
+<empty>
+
+$ SHELL=<true> treehouse get
+stdout:
+<empty>
+stderr:
+🌳 Setting up worktree...
+🌳 Entered worktree at /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/2/repo. Type 'exit' to return.
+🌳 Worktree returned to pool.
+normal_get_path=/Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/2/repo
+normal_get_reused_leased_path=no
+
+$ treehouse prune --yes
+stdout:
+🌳 Pruned 1 stale worktree and freed 625 B.
+2     625 B  /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/2/repo
+stderr:
+<empty>
+leased_path_exists_after_prune=yes
+
+$ printf 'y\n' | treehouse destroy <leased-path>
+stdout:
+<empty>
+stderr:
+Destroy worktree /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo? [y/N] worktree /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo is in use by an agent. Use --force to override
+destroy_exit_code=1
+leased_path_exists_after_destroy_rejection=yes
+
+$ treehouse return <leased-path>
+stdout:
+<empty>
+stderr:
+🌳 Worktree returned to pool.
+
+$ treehouse status # after return
+stdout:
+1     available    /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo
+stderr:
+<empty>
+
+$ SHELL=<true> treehouse get # after return
+stdout:
+<empty>
+stderr:
+🌳 Setting up worktree...
+🌳 Entered worktree at /Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo. Type 'exit' to return.
+🌳 Worktree returned to pool.
+reused_path_after_return=/Users/kunchen/.no-mistakes/worktrees/8c0b202f5740/01KVRQHS508TSFYHYAJN944WEG/.no-mistakes/evidence/fm/treehouse-lease-t4/.tmp-lease-e2e-55093/pool-root/.treehouse/repo-5f2bf8/1/repo
+released_worktree_reused=yes
+
+All manual lease E2E assertions passed.
diff --git a/AGENTS.md b/AGENTS.md
index b9eebb6..43a9f95 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,7 +46,8 @@ make test
 - Prune never treats an unreachable origin as a deletable orphan; those worktrees stay skipped because the repository may still be valid
 - Global prune enumerates managed pool directories under the user-level treehouse root and derives each worktree's owning repository from git metadata instead of relying on the current directory
 - Global prune loads user-level config and hooks only because it can run without a repository context
-- State file tracks pool membership and temporary owner/destroy reservations, not long-term usage status
+- State file tracks pool membership, temporary owner/destroy reservations, and explicit durable leases.
+  It still does not infer long-term usage from processes.
 - Git operations shell out to `git` (go-git has incomplete worktree support)
 - Self-healing: stale state entries are auto-removed
 
diff --git a/README.md b/README.md
index 836c512..6c2fccf 100644
--- a/README.md
+++ b/README.md
@@ -97,10 +97,10 @@ The default treehouse root is `~/.treehouse/`.
   git fetch origin
       │
       ▼
-  ┌────────────────────────────────────┐
-  │  Scan pool for available worktree  │
-  │  (not in-use, not dirty)           │
-  └──────────┬─────────────────────────┘
+  ┌───────────────────────────────────────┐
+  │  Scan pool for available worktree     │
+  │  (not leased, not in-use, not dirty)  │
+  └──────────┬────────────────────────────┘
              │
         ┌────┴────┐
         │  Found? │
@@ -166,7 +166,7 @@ The default treehouse root is `~/.treehouse/`.
 | `prune`   | `--global` | Alias for `--all` |
 | `prune`   | `--prune-orphans` | Include backing-repository-missing orphans in prune candidates |
 | `prune`   | `--verbose`, `-v` | Show detailed skip diagnostics |
-| `destroy` | `--force` | Force destroy even if in-use      |
+| `destroy` | `--force` | Force destroy even if in-use or leased |
 | `destroy` | `--all`   | Destroy all worktrees in the pool |
 
 ### Leasing a worktree (no subshell)
@@ -189,6 +189,7 @@ It also requires `--force` to `destroy`.
 Pass `--lease-holder <label>` (or set `$TREEHOUSE_LEASE_HOLDER`) to record who holds the lease; `treehouse status` then shows it next to the `leased` state.
 
 Release a lease with `treehouse return <path>`, which clears the lease, terminates any lingering processes, resets the worktree, and returns it to the pool.
+When you pass an explicit path, `treehouse return` can run from outside the repository because it resolves the managed pool from that worktree path.
 
 ### Pruning stale worktrees and orphans
 
@@ -248,6 +249,7 @@ pre_destroy = ["./scripts/teardown.sh"]
 ```
 
 - `post_create` runs after a worktree is provisioned or reset and right before `treehouse get` hands it to you.
+  For `treehouse get --lease`, stdout from `post_create` is routed to stderr so stdout remains the leased path.
 - `pre_destroy` runs before a worktree is removed by `treehouse destroy`, `treehouse destroy --all`, or prune deletion commands such as `treehouse prune --yes` and `treehouse prune --prune-orphans --yes`.
 
 Commands in each list run sequentially in the worktree directory, via the OS shell (`/bin/sh -c` on Linux/macOS, `%COMSPEC% /c` on Windows).
diff --git a/internal/pool/pool.go b/internal/pool/pool.go
index 0069131..b0859c0 100644
--- a/internal/pool/pool.go
+++ b/internal/pool/pool.go
@@ -21,6 +21,7 @@ const (
 	StatusHere      = "you're here"
 )
 
+// WorktreeStatus describes one managed worktree as reported by List.
 type WorktreeStatus struct {
 	Name      string
 	Path      string
@@ -178,6 +179,8 @@ func markAcquired(wt *WorktreeEntry, opts acquireOptions) error {
 	return reserveOwner(wt)
 }
 
+// Release resets a managed worktree, clears its short-lived owner reservation or
+// durable lease, and returns it to the available pool.
 func Release(poolDir, worktreePath string) error {
 	repoRoot, err := git.FindRepoRootFrom(worktreePath)
 	if err != nil {
@@ -224,6 +227,8 @@ func Release(poolDir, worktreePath string) error {
 	})
 }
 
+// List returns the current status of managed worktrees in poolDir.
+// Leased worktrees are reported with StatusLeased and their optional holder.
 func List(poolDir string) ([]WorktreeStatus, error) {
 	var result []WorktreeStatus
 
@@ -275,6 +280,9 @@ func List(poolDir string) ([]WorktreeStatus, error) {
 	return result, err
 }
 
+// Destroy removes one managed worktree from the pool.
+// Without force, it refuses worktrees with live processes, owner reservations,
+// or durable leases.
 func Destroy(repoRoot, poolDir, worktreePath string, force bool, preDestroy []string) error {
 	var reserved WorktreeEntry
 	if err := WithStateLock(poolDir, func() error {
@@ -342,6 +350,9 @@ func Destroy(repoRoot, poolDir, worktreePath string, force bool, preDestroy []st
 	})
 }
 
+// DestroyAll removes every managed worktree from the pool.
+// Without force, it refuses when any worktree has live processes, an owner
+// reservation, or a durable lease.
 func DestroyAll(repoRoot, poolDir string, force bool, preDestroy []string) error {
 	var worktrees []WorktreeEntry
 	if err := WithStateLock(poolDir, func() error {
diff --git a/internal/pool/prune.go b/internal/pool/prune.go
index 36b1783..fa36bca 100644
--- a/internal/pool/prune.go
+++ b/internal/pool/prune.go
@@ -98,8 +98,9 @@ type plannedPrunePool struct {
 }
 
 // Prune finds stale idle managed worktrees and optionally deletes them.
-// A stale worktree is clean, unused, unreserved, and merged into the default
-// branch ref selected by git.DefaultBranchMergeRef.
+// A stale worktree is clean, unused, unleased, not reserved by another lifecycle
+// operation, and merged into the default branch ref selected by
+// git.DefaultBranchMergeRef.
 // In dryRun mode Prune reports candidates and reclaimable bytes without deleting.
 // Backing-repository-missing orphans are reported as skipped; use
 // PruneWithOptions with PruneOptions.PruneOrphans to include them as candidates.